| name | generate-test-doc |
| description | 根据需求文档和 MR 代码变更，自动生成或补充飞书提测文档的关键章节（背景、提测目标、功能变更清单等）。当用户提到"提测文档"、"提测"、"补充提测"、"生成提测文档"、"写提测文档"、"更新提测文档"，或者给出飞书提测文档链接并要求填写/补充内容时，使用此 skill。即使用户只说"帮我写下提测文档"而没有明确说出 skill 名称，也应触发。 |
生成/补充飞书提测文档
背景
提测文档是研发提交测试前的标准化交付物，用于向 QA 同步本次变更的范围、目标和注意事项。手工编写提测文档耗时且容易遗漏，本 skill 通过分析需求文档和 MR 代码 diff，自动生成提测文档的核心章节。
触发条件
以下任一情况即可触发：
- 用户提供了飞书提测文档链接，要求补充/更新内容
- 用户要求"生成提测文档"或"写提测文档"
- 用户提供了需求文档 + MR 链接，要求生成提测相关内容
所需输入
| 输入 | 必需 | 说明 |
|---|
| 提测文档 URL | 否 | 飞书云文档链接，已有的提测文档。未提供时基于模板自动创建新文档 |
| 需求文档 URL | 是 | 飞书云文档链接，包含功能需求描述 |
| MR 链接 | 是 | GitLab Merge Request 链接，用于定位代码变更分支 |
| 模板 URL | 否 | 自定义提测单模板链接。未提供时使用默认模板 |
如果用户未提供需求文档或 MR 链接，主动询问补全。
默认模板
默认使用「营销提测单模版 V1.0」：https://tigertech.feishu.cn/wiki/NPu5w7dmkiwrWNkeDSwct2XDnXg
在开始生成提测文档前，必须主动告知用户当前使用的模板，例如：
当前使用模板：「营销提测单模版 V1.0」(https://tigertech.feishu.cn/wiki/NPu5w7dmkiwrWNkeDSwct2XDnXg)
如需使用其他模板，请提供模板链接。
等待用户确认或提供新模板后再继续。
工作流程
前置检查：飞书 MCP 可用性
在开始任何操作前，先确认当前环境有飞书 MCP 工具（feishu_fetch-doc、feishu_update-doc 等）。如果没有这些工具，立即告知用户：
当前环境未配置飞书 MCP 工具，无法读写飞书文档。请先安装并配置飞书 MCP Server 后重试。
确认工具可用后再继续。
第一步：确认模板并获取信息（并行）
模板确认（前置）： 在开始工作前，先告知用户当前使用的模板名称和链接，等待用户确认或提供新模板链接。
确认后，根据用户是否提供了提测文档 URL 分两种模式：
模式 A：用户提供了提测文档 URL（更新已有文档）
同时执行以下三项：
-
获取提测文档 — 用 feishu_fetch-doc 读取现有提测文档，了解文档结构和已有内容，确定哪些章节需要补充
-
获取需求文档 — 用 feishu_fetch-doc 读取需求文档。需求文档通常较长，如果内容被截断，使用 Task(explore) 子代理读取完整内容并提取摘要
-
获取 MR 代码变更 — GitLab 通常需要登录无法直接 WebFetch，改用本地 git 操作。先 git fetch origin 确保远程分支最新，然后按以下策略获取 diff：
步骤 1：定位分支
- 从 MR 链接提取 MR 编号（如
!772）和可能的分支关键词
- 搜索本地分支：
git branch -a | grep -i <关键词>
- 如果找不到，搜索 commit message：
git log --all --oneline --grep="<关键词>" | head -10
步骤 2：获取 diff（按优先级尝试）
分支可能已合入 master，直接 git diff origin/master...origin/<branch> 可能返回空。需要按以下策略逐步尝试：
a. 分支未合入（三点 diff 有结果）：
git diff origin/master...origin/<branch> --stat
b. 分支已合入 master（三点 diff 为空）：
- 找到 merge commit：
git log --all --oneline --grep="<branch_name>" | head -5
- 从 merge commit 获取两个 parent：
git show <merge_commit> --stat（merge commit 格式为 Merge: <parent1> <parent2>）
- 用两个 parent 做 diff：
git diff <parent1>...<parent2> --stat
c. 多个相关 MR（同一需求有多个分支）：
- 搜索所有相关 merge commit，分别获取 diff
- 合并分析所有变更
步骤 3：获取关键文件 diff
- 从
--stat 结果中筛选业务文件（排除 *_test.go、*_ai_test.go、wire_gen.go、*.yml 配置文件等）
- 对关键业务文件获取具体 diff：
git diff <parent1>...<parent2> -- <file>
- 如果变更文件较多（>15个），使用 Task(general) 子代理并行读取 diff 并汇总分析，避免上下文溢出
模式 B：用户未提供提测文档 URL（基于模板创建新文档）
先引导用户手动复制模板，再在副本上填充内容。这样可以完整保留模板中的 bitable、lark-table 等复杂组件。
- 告知用户：「请先手动复制模板文档，然后将副本链接发给我。复制方式：打开模板 → 右上角「...」→ 创建副本。」
- 等待用户提供副本链接
- 收到副本链接后，同时执行：
- 获取副本文档 — 用
feishu_fetch-doc 读取副本，确认文档结构
- 获取需求文档 — 同模式 A
- 获取 MR 代码变更 — 同模式 A
第二步：分析变更
基于需求文档和代码 diff，提炼以下内容：
- 背景 — 为什么做这个需求，解决什么问题，当前痛点是什么
- 提测目标 — 本次提测需要验证的核心能力点，每个点一句话概括
- 功能变更清单 — 按模块/文件维度组织，列出具体的代码变更内容：
- 数据结构变更（新增字段、表结构）
- 接口变更（新增/修改的 API 参数、返回值）
- 业务逻辑变更（校验规则、计算逻辑、匹配逻辑）
- 基础设施变更（新增连接、工具方法）
- SQL/数据库变更（新建表、ALTER 语句、新增索引）
- 配置变更（新增配置项、环境差异）
- 定时任务变更（新增/修改的 cron job）
分析时注意：
- 从代码 diff 中提取事实，不要臆测功能
- 结合需求文档理解变更的业务含义，而不是仅描述代码改动
- 关注对测试有影响的变更点，忽略纯重构或格式调整
- 如果变更文件较多，使用 Task(general) 子代理读取 diff 并按模块汇总，避免上下文溢出
- 需求文档中标注为"蓝色"或"新增"的内容通常是本次迭代重点，优先关注
第三步：写入文档
通用原则（两种模式共用）：
- 每个章节单独更新，避免一次性覆盖整个文档
- 保留文档中已有的其他内容（如表格、bitable 等）不被破坏
- 更新完成后，用
feishu_update-doc 的 new_title 参数修改文档标题为需求名称（如「支持FCN分佣活动配置 - 提测单」）
- 每次更新后用
feishu_fetch-doc 验证结果，确认无重复内容或结构异常
文本换行注意事项：
飞书文档中多行文本（如"需求来源/需求文档/接口文档"）必须用飞书扩展语法确保换行，不能简单拼接在一行。正确做法：
<text color="gray">**需求来源：**</text> [链接文字](URL)
<text color="gray">**需求文档：**</text> [链接文字](URL)
<text color="gray">**接口文档：**</text> 见需求文档内接口定义部分
每行之间必须有空行，否则飞书会将多行合并为一行显示。
模式 A（更新已有文档）：
使用 feishu_update-doc 的 replace_range 模式精确更新对应章节：
- 优先使用
selection_by_title 定位纯文本章节（如背景、提测目标、实现逻辑）
- 对于含 lark-table 的章节，避免用
selection_by_title 整章替换（容易导致旧内容删除失败产生重复）。改用 selection_with_ellipsis 精确定位表格内的占位文本进行替换
模式 B（基于模板副本更新）：
副本完整保留了模板的所有组件。更新时遵循以下原则：
-
lark-table 处理规则：
- 对于需要填入实际数据的表格（如「代码与构建」）：用
replace_range + selection_by_title 定位章节，重写整个 lark-table，保持原有列数、列宽、表头不变，将占位数据行替换为实际内容
- 对于需要清空占位内容的表格（如「测试环境信息」）：用
selection_with_ellipsis 精确定位每个需要清空的单元格内容进行替换，而不是替换整个表格章节。这样更安全，避免产生重复章节标题
- 重复内容修复：如果
replace_range 返回 warning 提示"Old content deletion failed"导致内容重复，立即用 delete_range 删除旧的重复部分。删除后用 feishu_fetch-doc 确认文档结构正确
-
bitable 处理规则：bitable 的 token 绑定文档，无法通过文档 API 修改内容。处理方式：
- 将需要填入 bitable 的内容（如功能变更清单）以编号列表形式写入文档中，插入到 bitable 所在章节之后、下一个章节之前（如「研发交付物清单」bitable 之后、「四、测试环境信息」之前），并用 callout 提示用户手动复制到多维表格
- 功能变更清单格式：
1. **模块名称** — 变更说明，每项一行，标好序号，不使用 lark-table
- 如果 bitable 中有需要清空的占位行（如研发自测报告、已知未修复问题等），告知用户手动清空
-
文本章节处理规则：用 replace_range + selection_by_title 替换占位文本为实际内容（背景、提测目标、功能变更清单等）
输出格式规范
背景章节
简洁描述：现状 → 痛点 → 本次迭代目标（带编号列表）。控制在 200 字以内。
提测目标章节
编号列表，每项一句话，覆盖本次变更的所有可测试点。通常 5-10 项。
功能变更清单章节
写入"实现逻辑&注意事项"章节（或类似章节），按模块分组，使用三级标题组织：
### 1. 模块名称
- 变更点 1（具体描述，包含字段名、方法名等）
- 变更点 2
### 2. 另一个模块
- 变更点 1
注意事项
飞书文档操作
- lark-table：保留表格结构和表头，清除占位/示例数据行，替换为实际内容。如果某些行暂无实际数据，清空单元格留白供用户后续填写
- bitable：token 绑定文档，无法通过文档 API 修改。将需要填入的内容以编号列表形式写入文档中 bitable 之后、下一章节之前，用 callout 提示用户手动复制到多维表格。不使用 lark-table，直接用
1. **模块名** — 说明 格式逐行列出
- replace_range 陷阱：对含 lark-table 的章节使用
selection_by_title 整章替换时，飞书可能无法正确删除旧内容，导致出现重复的章节标题和表格。更安全的做法是用 selection_with_ellipsis 精确定位需要替换的文本片段
- 重复内容修复：每次
replace_range 后检查返回的 warnings 字段。如果出现 "Old content deletion failed" 警告，立即用 delete_range 清理重复内容，然后 feishu_fetch-doc 验证
- 换行问题：飞书 markdown 中相邻的行如果没有空行分隔会被合并为一行。需要独立显示的每行之间必须插入空行
Git 操作
- 开始前先
git fetch origin 确保远程分支最新
- 如果 MR 分支在本地 git 中找不到，提示用户先
git fetch origin 更新远程分支
- 分支已合入 master 时，三点 diff（
origin/master...origin/<branch>）会返回空结果，需要通过 merge commit 的两个 parent 来获取 diff
- 同一需求可能有多个 MR（如基础优化 + 功能迭代），需要搜索所有相关分支并合并分析
- 排除非业务文件：
*_test.go、*_ai_test.go、wire_gen.go、*.yml（配置文件单独关注）
内容生成
- 如果提测文档已有部分内容，保留已有内容并在此基础上补充，而非覆盖
- 变更清单中涉及的方法名、字段名使用反引号包裹，便于阅读
- 背景章节控制在 200 字以内，避免冗长
- 提测目标通常 5-12 项，覆盖所有可测试点，每项一句话
- 功能变更清单按模块分组，使用三级标题组织，便于 QA 按模块分工测试
