QA 操作手册

你是谁 / 本手册范围

你是 QA 工程师：接 PM 推过来的需求文档 + 合约工程师推过来的 ABI 文档 + 后台工程师推过来的接口文档，基于三类文档生成结构化测试用例 → 执行冒烟 / 合约 / 接口测试 → 发现 Bug 即录即通知 → 跟进修复并做复测 → 关闭或 reopen。本手册只讲 QA 专属的 skill 流程。全员通用的环境准备、/git-*、/docs-push-gitlab、/notify、/deploy-gen 等请先读 common.md，再回这里看专属流程。

本手册假设你已按 common.md 跑过 /docs-init + /skills-install。QA 是 Bug 管理的高频使用方，/bug-add + /bug-update 建议每天熟练使用。

首次配置

1. 初始化 `.docs.env`

跑 /docs-init，把管理员通过安全渠道发给你的配置整段粘贴进 .docs.env。管理员会用 /member-token-gen 为你签发。QA 角色必须包含以下字段（完整字段表见 common.md 的「环境准备」章节）：

# 顶层（monorepo 迁移后统一单 token）
GITLAB_BASE_URL=https://gitlab.ironetwork.com
GITLAB_DOCS_BRANCH=main
GITLAB_DOCS_PROJECT_ID=213              # docs-site 仓库，所有项目共用
GITLAB_DOCS_WRITE_TOKEN=glpat-xxxx      # ⚠️ QA 用 Write Token，既要拉三类文档，也要推 tests/ + bugs/

# daily-log 写 content/manage/** 用
DOCS_SITE_PROJECT_ID=213
GITLAB_DOCS_SITE_WRITE_TOKEN=glpat-xxxx

# 你的身份
MEMBER_NAME=your_name
MEMBER_TG=@your_tg

# Skills 安装用
SKILLS_ROLE=qa
SKILLS_COMMON_TOKEN=glpat-xxxx
SKILLS_QA_TOKEN=glpat-xxxx

# 图床（bug-add / bug-update 贴截图必需，QA 最高频字段）
LSKY_BASE_URL=https://bugs.ironetwork.com
LSKY_TOKEN=xxx

# Telegram（全局一个 bot token；chat id 按项目）
TELEGRAM_BOT_TOKEN=bot123:xxx

# 按项目一段
[pay-fi]
GITLAB_PROJECT_ID=101                   # notify 场景引用
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=1                      # ⚠️ 每个项目一个 strategy，截图分库存

[fomo-pad]
GITLAB_PROJECT_ID=102
TELEGRAM_CHAT_ID=-100...
LSKY_STRATEGY_ID=2

2. 安装 QA 角色 skill 包

/skills-install

SKILLS_ROLE=qa 会自动拉 skills-common + skills-qa 两个仓库
完成后按提示重启 Claude Code

3. 自检 QA 必需字段

QA 角色特有的必填项：顶层 GITLAB_DOCS_WRITE_TOKEN（拉需求 / 合约 / 后台三类文档，推 tests/ 和 bugs/）+ LSKY_BASE_URL / LSKY_TOKEN / LSKY_STRATEGY_ID（/bug-add 和 /bug-update 贴截图，QA 每天都会用到）+ 至少一个项目段的 TELEGRAM_CHAT_ID（通知场景 4 / 5）。缺任一项，对应 skill 会在 HARD-GATE 阶段拦下来并指名缺什么。

强提示：Lsky Pro 三件套是 QA 的命根子 — 截图上传失败 = /bug-add 流程中断。配置完成后先跑一次 /bug-add 把一张测试截图粘进去验证链路。

日常工作流

QA 工程师从「开工拉最新三方文档」到「录 Bug / 复测 / 通知团队」，下面 6 个场景覆盖 95% 的工作。

场景 A：拉最新需求 + 合约 + 后台文档

什么时候用：PM / 合约 / 后台任一角色 @你「文档已更新」，或准备开始新一轮测试前。

触发命令：

/qa-docs-pull                    # 交互选项目
/qa-docs-pull --project pay-fi   # 指定单项目
/qa-docs-pull --all              # 全量同步所有 [project] 段

关键输入：多项目时选要拉的项目；对 tests/ 里「远程已更新」的文件，按编号或 all / skip 选是否覆盖本地（保护你尚未推送的测试用例草稿）。

产出结果：

content/{project}/requirements/ → .docs/{project}/requirements/（全量同步，只读）
content/{project}/contract/ → .docs/{project}/contract/（全量同步，只读，合约 ABI 文档）
content/{project}/backend/ → .docs/{project}/backend/（全量同步，只读，后台接口文档）
content/{project}/tests/ → docs/{project}/tests/（差异拉取，本地新建未推的保留不动）
输出摘要：📥 新增 N / 🔄 覆盖 M / ⏭️ 跳过 K / 仅本地 J，超过 7 天未更新的文档标 ⚠️⚠️ 提醒联系对应角色确认

场景 B：生成测试用例

什么时候用：三方文档同步完成后，基于最新规格产出测试用例。QA 有两个生成 skill，分工清晰：

触发命令（二选一）：

/qa-docs-gen             # 结构化输出到 docs/{project}/tests/（主力）
/qa-gen                  # 读 docs/tasks/{task}/overview.md + 所有角色文档 产 QA 覆盖表（任务级）

两者区别：

命令	输入	输出位置	适合场景
`/qa-docs-gen`	`.docs/{project}/requirements/` + `contract/` + `backend/`（全项目文档）	`docs/{project}/tests/smoke/` + `contract/` + `api/` 按模块拆分	日常新功能 / 接口 / 合约变更，主力用
`/qa-gen`	`docs/tasks/{task}/overview.md` + `frontend.md` + `backend.md` + `contract.md` + 原 `qa.md`	覆盖任务目录下 `qa.md`，可选 Cypress / Playwright / Jest 自动化脚本骨架	某个 task 要做全链路 E2E 覆盖或需要跑自动化

关键输入（以 /qa-docs-gen 为主）：

多项目时选目标项目
测试类型四选一：1. 冒烟测试 / 2. 合约测试 / 3. 接口测试 / 4. 全部
若某类源文档为空（如 contract/ 未同步），skill 跳过对应类型不报错但会提示

产出结果：

docs/{project}/tests/
├── smoke/{模块}.md       # 覆盖每个模块的核心正向路径（用户故事来源）
├── contract/{合约}.md    # 覆盖每个方法 / 事件 / 权限 / 边界值（ABI 来源）
└── api/{模块}/api.md     # 覆盖每个接口的正向 + 必填缺失 + 类型错误 + 错误码（接口文档来源）

每个文件头部含生成时间 + 文档来源 + 总用例数统计。完成后接 /docs-push-gitlab 选 4. tests → 推到 docs-site content/{project}/tests/ → /notify 选场景 4。

场景 C：提新 bug

什么时候用：测试中发现任何规格不符 / 崩溃 / 性能问题。QA 是此 skill 的高频使用方，建议两种模式都熟练。

触发命令：

/bug-add            # 默认单条引导模式
# 提示出现后回复 "批量" 切到 Excel 批量导入

关键输入：

① 单条快速模板（默认）— 按快速模板填标题 / 步骤 / 预期 / 实际 / 关联 FEAT，AI 自动解析字段；可用 cmd+V 粘贴截图，自动上传 LSKY_BASE_URL + LSKY_TOKEN + LSKY_STRATEGY_ID 对应图床，返回 URL 写入 bug 段；严重度（P0-P3）和负责角色（contract / backend / frontend）由 AI 预判，ok 全部采纳或关键字覆盖（如 P0 backend）。

② Excel 批量导入（回复 批量 触发）— 自动生成 bug-import-template.xlsx 到项目根目录（含下拉约束、示例、说明 sheet），填完拖回窗口 → AI 校验必填 + 去重 + 预览 → ok 批量写入。截图用 WPS / Office 365「放置在单元格」功能（浮动图不可识别）。批量模式适合一次集中录入回归测试发现的 5+ 条同类 Bug。

产出结果：

content/{project}/bugs/bugs.md 追加 ## BUG-XXX 段，按「严重度 + 状态」自动排序
content/{project}/bugs/stats.md 刷新（每日 / 角色分布 / 修复效率 / 个人贡献 / 月度数据）
截图 URL 内嵌到 bug 详情段

标准三步走：/bug-add → /docs-push-gitlab 选 5. bugs → /notify 选场景 5。

场景 D：复测 bug

什么时候用：负责人把 bug 改完推「状态已改为 fixed」或 TG 群里收到场景 9 / 10 / 11「Bug 已修复」通知，你负责验证是否真的修好了。

触发命令：

/bug-update BUG-007 status=closed        # 复测通过，关单
/bug-update BUG-007 status=reopen        # 不通过，打回（自动从 archive 迁回）
/bug-update BUG-007                      # 交互模式（不确定改啥时用）

合法状态流转：

open → in-progress → fixed → closed
             ↑          ↓
             └── reopen ┘       （closed 7 天后自动归档，reopen 会自动从 archive 迁回）

关键输入：

跳级流转（如 open → closed）直接拒绝，必须按提示补中间状态
status 变 closed 时自动填 closer=MEMBER_NAME，用于 stats.md 统计
reopen 时 skill 会扫 archive/bugs-{YYYY-MM}.md，把 bug 段原样迁回当前 bugs.md 并重排，截图 URL 保留不丢
写入时也走乐观锁 + 3 次重试，冲突会提示「并发冲突过多」，5 秒后重跑即可

产出结果：bugs.md 重排 + stats.md 刷新。之后 /docs-push-gitlab 选 5. bugs + /notify 场景 5。

场景 E：通知 bug 文档更新

什么时候用：跑完 /bug-add 或 /bug-update 并 /docs-push-gitlab 之后。

触发命令：

/notify
# 选场景 5「测试 Bug 文档已更新」

关键输入：无需手填 @mention 列表 — 场景 5 是唯一动态 @mention 场景，skill 自动：

解析本次推送 bugs.md 的 git diff，提取所有变更段的 frontmatter
收集每个变更 bug 的 reporter_role + assignee 对应的 role
去重、排除发送人本人，按 role 分组生成 @mention 行

产出结果：Telegram 消息含新增 bug 列表（🔴 + 链接）+ 状态变更列表（🟡 原→新），末尾追加动态 @mention + @hi_sam1369 兜底；同时在 content/manage/members/{MEMBER_NAME}/{YYYY-MM-DD}.md 追加日志条目。

场景 F：通知测试用例更新

什么时候用：跑完 /qa-docs-gen 并 /docs-push-gitlab 选 4. tests 之后。

触发命令：

/notify
# 选场景 4「测试用例已更新」

关键输入：填本次新增 / 变更的用例覆盖场景、重点测试项（如「新增登录模块 5 个冒烟用例 + 支付接口 3 个边界用例」）。

产出结果：Telegram 通知自动 @mention backend / frontend / contract，消息结尾附 @hi_sam1369 兜底；成员日志追加条目。

状态追踪你这边能做什么：`/story-status`

/story-status FEAT-002 US-01           # 单个
/story-status FEAT-002 US-01,US-03     # 多个（同一 FEAT）
/story-status FEAT-002 all             # 该 FEAT 涉及你的所有 story

你（QA）的权限： 推进「QA」列 未开始 → 已完成（前置：所有涉及的 dev 列都已完成；测试通过后推；不通过走 /bug-add，状态保持 未开始）。仅前进、不回退、不旁路。 改错了找管理员通过 GitLab Web UI 修。详细列结构和首次启用说明见 common.md 状态追踪节。

查看进度： team-docs.pages.dev/{project}/status

通用 skill 速查

全员通用 skill 的详细规则看 common.md，QA 本地最常用三个：

命令	QA 的典型使用场景
`/docs-push-gitlab`	生成完测试用例推 `4. tests`；每次 `/bug-add` / `/bug-update` 后推 `5. bugs`。并发冲突检测会提示 72h 内他人修改，逐文件 y/n
`/notify`	推完 `tests/` 选场景 4；推完 `bugs/` 选场景 5（动态 @mention，不用手填）。每次通知成功后自动追成员日志
`/git-branch` + `/git-commit`	QA 极少直接在代码仓库起分支，主要在 docs-site 仓库改测试用例时用 `/git-commit` 预览 Conventional Commits 信息

常见问题 / 故障排查

Q1：/bug-add 粘截图上传 401 / 超时 / 图太大失败？

先看具体错：401 → LSKY_TOKEN 失效，联系管理员重签新 token 替换 .docs.env；400 strategy not found → LSKY_STRATEGY_ID 错了，每个项目一个 strategy（[pay-fi] 段 LSKY_STRATEGY_ID=1，[fomo-pad] 段是 2），别搞混；413 payload too large → Lsky 默认上限约 10 MB，截图若是整屏 4K 录屏截帧请先用 cmd+shift+5 截选区或用预览 App 压缩；超时 → 图床偶发抖动，等 30 秒重跑 /bug-add 粘同一张图即可，已写入的字段不会丢。

Q2：/bug-update BUG-XXX status=reopen 提示「BUG 未找到」？

bug 已归档到 archive/bugs-{YYYY-MM}.md（closed 7 天后自动迁走），reopen 会自动跨档还原但前提是本地有最新的 archive 文件。先跑 /qa-docs-pull（或 /docs-pull）把 archive/ 也同步下来再 reopen；若 archive 里也找不到，说明这条 bug 已经归档超过 3 个月被清理，需要手动 /bug-add 重新录一条并在 关联 字段写原 BUG-XXX 做引用。

Q3：/qa-docs-gen 报「未检测到本地文档，请先执行 qa-docs-pull」？

HARD-GATE 检查 .docs/{project}/ 目录存在且非空。常见原因：一、压根没跑过 /qa-docs-pull；二、跑了但选错项目（.docs/pay-fi/ 有，但你选了 fomo-pad 生成）；三、.docs/ 超过 24 小时未更新，skill 会提示「是否继续使用当前文档」，可以回 y 继续，但建议先 /qa-docs-pull 拿最新版。彻底解决：每天开工先 /qa-docs-pull --all 刷一次。

Q4：/notify 场景 5 的动态 @mention 是怎么算出来的？

skill 会读 docs/{project}/bugs/bugs.md 的 git diff（本次 push 新增 / 修改的段），提取每段 frontmatter 的 reporter_role（谁报的）+ assignee（谁负责，按 team.md 反查 role），去重后 @对应角色的所有成员，排除你自己。例如：本次你一次推了 3 条新增 bug，其中 2 条 assignee 是后台 Alice、1 条是前端 Bob，reporter_role 都是 QA — 那 @mention 会 @backend 组 + @frontend 组（QA 是你自己，被排除）。若 diff 为空（纯格式调整），@mention 会退化为只 @兜底账号。

Q5：Excel 批量导入模板里哪些列是必填，怎么加截图？

模板生成后第一个 sheet 有下拉约束和示例行，必填列：标题 / 实际表现 / 严重度（P0-P3）/ 负责角色（contract / backend / frontend）；可空列：步骤 / 预期 / 关联 FEAT / 截图（用「放置在单元格」功能嵌入，不是浮动图片）/ reporter（默认取 MEMBER_NAME）。AI 会做两件事：一、按标题做精确匹配去重（strip 空格后比较，已存在则跳过并列出），二、对单元格内嵌图调 Lsky Pro 批量上传。若你更喜欢先录字段再补图，留空截图列导入完，按返回的 BUG-XXX 编号逐个 /bug-update BUG-XXX 粘图即可。

QA 操作手册

QA 操作手册

你是谁 / 本手册范围

首次配置

1. 初始化 .docs.env

2. 安装 QA 角色 skill 包

3. 自检 QA 必需字段

日常工作流

场景 A：拉最新需求 + 合约 + 后台文档

场景 B：生成测试用例

场景 C：提新 bug

场景 D：复测 bug

场景 E：通知 bug 文档更新

场景 F：通知测试用例更新

状态追踪你这边能做什么：/story-status

通用 skill 速查

常见问题 / 故障排查

相关文档链接

1. 初始化 `.docs.env`

状态追踪你这边能做什么：`/story-status`