Pbi Reviewer

需求返讲助手

帮助研发人员高效完成需求返讲工作，包括需求理解、完整性检查、文档撰写。

执行声明规范

AI 在执行此 Skill 时，必须向用户明确告知执行状态：

开始执行时

📝 **正在执行: 需求返讲助手** (`#pbi-reviewer`)

✅ 已加载 Skill 指引
⭕ 当前步骤: 步骤1 - 解析需求

调用其他专家时

🔗 **调用领域专家**: `#{{PLATFORM_REPO}}-roi-expert`
   原因: 需求涉及 ROI 测量功能

每个步骤完成时

✅ 步骤1 完成: 解析需求
   提取到 3 个功能点、2 个验收标准
⭕ 当前步骤: 步骤2 - 识别模块

遇到问题时

⚠️ **问题提示**:
   - 未配置需求检查清单，将使用通用检查项
   - 如需自定义检查清单，请在 UI 中配置 `需求检查清单` 路径

执行完成时

✅ **执行完成**: 需求返讲助手

参考来源:
- Skill: `#pbi-reviewer`
- 领域专家: `#{{PLATFORM_REPO}}-roi-expert`, `#{{PLATFORM_REPO}}-layout-expert`
- 检查清单: 通用检查项 / 自定义清单

产出物: 需求返讲文档

适用场景

• 收到PM的PBI需求，需要进行返讲评审
• 检查需求是否有遗漏或理解偏差
• 撰写标准格式的需求返讲文档
• 拆解复杂需求为可执行的开发任务

工作流程

输入: PBI链接/ID/标题/内容
       ↓
步骤0: 智能解析输入 → 识别PBI来源，自动获取详情
       ↓
步骤1: 解析需求 → 提取功能点、业务场景、验收标准
       ↓
步骤1-B: 🔴 搜索历史PBI → 从 CSV 查找相关/相似 PBI（必须执行）
       ↓
步骤2: 识别模块 → 根据关键词匹配功能模块，调用领域专家
       ↓
步骤3: 应用检查清单 → 逐项检查影响范围
       ↓
步骤4: 生成文档 → 输出标准格式的返讲文档
       ↓
步骤5: 发布文档（默认） → 优先飞书MCP，不可用时降级为本地MD
       ↓
输出: 飞书文档链接 / 本地Markdown + 检查清单 + 风险点

详细步骤

🔴 前置检查：一次性请求拦截（需求返讲 + 设计评审）

当用户请求中同时包含「需求返讲」和「设计评审/圆桌会议/出设计」关键词时， 必须先拦截，引导用户分步执行。

检测规则: 用户输入同时匹配以下两组关键词：

• 组A（需求返讲）: 需求返讲 / 评审需求 / 返讲 / PBI评审
• 组B（设计评审）: 设计评审 / 圆桌会议 / 出设计 / 写设计 / 设计文档

匹配到时，使用 ask_questions 拦截:

header: "分步确认"
question: "检测到您希望同时进行需求返讲和设计评审。\n\n⚠️ 建议分步执行：先完成需求返讲，与 PM 澄清所有待确认问题后，再启动设计评审。否则设计方案可能因需求理解偏差而返工。\n\n请选择执行方式："
options:
  - label: "先做需求返讲，稍后再出设计"
    description: "完成返讲后，您可以与 PM 确认问题，再单独启动设计评审"
    recommended: true
  - label: "我已确认需求，直接做完返讲后继续设计"
    description: "跳过中间确认环节，返讲完成后自动启动圆桌会议"

• 用户选择「先做需求返讲」→ 只执行需求返讲（步骤0-6），不自动触发圆桌会议
• 用户选择「直接做完返讲后继续设计」→ 执行完需求返讲后，自动加载 #roundtable-debate 继续

📌 如果用户请求中只提到「需求返讲」，不触发此拦截，直接执行。

步骤0: 智能解析 PBI 输入 ⭐ 必须执行

⚠️ 强制规则: 如果从用户输入中检测到 PBI ID（数字），必须先调用 MCP 获取 PBI 详情，不得跳过！

支持的输入格式（按优先级）：

解析正则表达式：

// 1. 从 URL 提取 ID
url.match(/\/_(?:queries|workitems)\/(?:edit\/)?([0-9]+)/)

// 2. 从标准格式提取
text.match(/(?:Product Backlog Item|PBI|Work Item|Bug)\s*#?([0-9]+)/i)

// 3. 纯数字 (5-8位，符合 DevOps ID 范围)
text.match(/\b([0-9]{5,8})\b/)

// 4. PBI 标题 (用于搜索)
text.match(/PBI_[A-Za-z0-9_]+/)

🔴 强制执行：MCP 调用

当检测到 PBI ID 时，必须尝试以下 MCP 工具调用：

工具名称: mcp_azuredevops_get_work_item
参数: 
  - id: <提取到的PBI数字ID>
  
示例调用:
  mcp_azuredevops_get_work_item(id=1073716)

⚠️ API 返回内容对比（务必选对工具）

🔴 禁止：用 list_work_items（WIQL）获取单个 PBI 详情。WIQL 不返回 HTML/大文本字段，即使 SELECT 中指定了 [System.Description]，返回值也为空。

如果只有标题没有 ID，使用搜索：

工具名称: mcp_azuredevops_search_work_items  
参数:
  - query: <PBI标题>

🟡 MCP 不可用时的备选方案

当 MCP 工具不存在或调用失败时，执行以下备选流程：

⚠️ **MCP 状态**: Azure DevOps 工具不可用
   原因: [工具未加载 / 连接失败 / 认证错误]

🔄 **启用备选方案**:
   1. 查询历史 PBI 知识库
   2. 请用户手动提供 PBI 内容

步骤0-B: MCP 不可用时的处理

历史 PBI CSV 搜索已提升为独立步骤（步骤1-B），无论 MCP 是否可用都会自动执行。 此处仅需告知用户 MCP 状态，请求粘贴 PBI 完整内容。

执行流程：

📥 **步骤0: 解析 PBI 输入** (强制)

1️⃣ 识别输入类型:
   - 检测到: [链接/ID/标题/内容]
   - 提取的 ID: [具体数字，如 1073716]

2️⃣ 🔴 尝试调用 MCP 获取详情:
   → 调用 mcp_azuredevops_get_work_item(id=1073716)
   → 如果成功，提取: 标题、描述、验收标准、状态、迭代
   → 如果失败，转到步骤 2-B

2️⃣-B 🟡 MCP 不可用，启用备选:
   → 告知用户 MCP 状态，请求粘贴完整内容
   → 历史 PBI CSV 搜索将在步骤1-B 自动执行

3️⃣ 提取关键信息:
   - System.Title: 标题
   - System.Description: 需求描述 (HTML格式，需解析)
   - Microsoft.VSTS.Common.AcceptanceCriteria: 验收标准
   - System.State: 状态
   - System.IterationPath: 迭代路径

📚 **参考来源声明** (必须输出):
   - MCP DevOps: [成功/不可用]
   - 历史PBI: 将在步骤1-B 填充

步骤1: 解析需求

从PBI中提取以下信息:

1. 基本信息

   • PBI编号和标题
   • 所属迭代/版本
   • 优先级

2. 功能描述

   • 业务背景
   • 用户故事
   • 功能点列表

3. 验收标准

   • 功能验收条件
   • 非功能性要求（性能、兼容性等）

4. 关联信息

   • 相关PBI链接
   • 设计稿/原型链接
   • 二级链接（如果有）

5. 术语确认 🔍

   • 对 PBI 描述中出现的技术术语、模块名、组件名
   • 如果 AI 不确定其含义 → grep_search 搜索项目代码或查询 expert skill 确认
   • 如果搜索后仍不确定 → 在返讲文档「待确认问题」中标注

步骤1-B: 搜索历史 PBI 知识库 🔴 必须执行

⚠️ 强制规则: 无论 MCP 是否可用，此步骤都必须执行。这是填充返讲文档 ### 相关PBI 表格的唯一来源。

获取 PBI 文件路径（本地优先）:

1. 优先: 检查 .github/copilot-resources/data/ 目录下是否有 *-index.md 和 *-detail.md 文件（CSV 已自动转换为分层 Markdown） → 如果有，直接读取（工作区内文件，无需授权）
2. 降级: 查看 .github/copilot-instructions.md 中「项目文档配置」段落，获取 PBI 索引/详情路径

📁 .github/copilot-resources/ 是工具自动复制的本地副本。PBI 数据已分为索引文件（轻量表格，含关键词列）和详情文件（完整描述），避免一次性加载过多 token。

如果已配置 PBI 知识库 — 双路搜索工作流:

路径A: read_file 索引文件 → 按标题/关键词匹配
路径B: grep_search 详情文件 → 按描述内容匹配
合并去重 → read_file 按需读取详情片段

路径A — 索引匹配:

1. 用 read_file 读取索引文件（*-index.md，~400行，轻量）
2. 索引表列结构:
   • ID: PBI 编号
   • Title: 标题
   • State: 状态
   • Keywords: 从描述中自动提取的领域关键词
   • RefLinks: 描述中引用的 URL
3. 搜索策略:
   • 按当前 PBI ID 精确匹配（排除自身，查找关联记录）
   • 按标题关键词模糊匹配（提取功能关键词，如 配准、Spectrum、CT）
   • 按 Keywords 列匹配功能模块名（如 ROI、Layout、DataLoad）

路径B — 详情搜索（补充路径A遗漏）:

1. 从当前 PBI 标题/描述中提取 2-3 个核心功能关键词
2. 用 grep_search 在详情文件（*-detail.md）中搜索每个关键词
3. 从搜索结果中提取匹配到的 ## PBI-{id} section 标题

合并与去重:

1. 将路径A和路径B的匹配结果合并，按 PBI ID 去重
2. 对路径B新发现的 PBI，用 read_file 读取详情文件中对应 section 获取完整描述
3. 返回最相关的 3-5 条记录
4. 将结果填充到返讲文档模板的 ### 相关PBI 表格

如果未配置 PBI 知识库:

⚠️ 未配置历史 PBI 知识库，跳过历史搜索。
   如需启用，请在 GUI 向导中配置 `PBI CSV 路径`。

输出格式:

✅ 步骤1-B 完成: 搜索历史 PBI
   索引文件: [文件名] | 详情文件: [文件名]
   路径A(索引匹配): X 条 | 路径B(详情搜索): Y 条
   合并去重后: Z 条相关记录
   - PBI-XXXXXX: [标题] (关系: [依赖/关联/相似])
   - PBI-YYYYYY: [标题] (关系: [依赖/关联/相似])

📚 参考来源更新:

- 历史PBI: [索引文件名] + [详情文件名] (Z 条相关记录) / 未配置

步骤2: 识别功能模块

根据需求内容的关键词，识别涉及的功能模块并调用对应专家:

🔴 扫描 Skills 目录进行专家匹配

# 扫描 .github/skills/ 目录
for skill_dir in list_dir(".github/skills/"):
    if skill_dir.startswith("_"):  # 跳过 _templates
        continue
    skill_md = read_file(f".github/skills/{skill_dir}/SKILL.md")
    # 解析 frontmatter 的 description，提取触发关键词
    # 与 PBI 内容进行正则匹配
    if keywords_match(pbi_content, skill_description):
        call_expert(skill_name)
        output(f"🔗 调用领域专家: #{skill_name}\n   原因: 匹配关键词")

💡 每个 SKILL.md 的 description 包含触发关键词，格式如： 触发关键词: ROI、轮廓、测量、标注

降级策略：关键词未匹配任何 expert 时

如果 PBI 涉及的功能模块没有对应的 expert skill，执行以下降级：

# 降级：搜索项目代码确认影响范围
if matched_experts == 0:
    # 1. 从 PBI 标题/描述中提取技术关键词
    keywords = extract_technical_keywords(pbi_title, pbi_desc)
    # 2. 搜索项目代码
    for kw in keywords:
        grep_search(kw, includePattern="**/*.cs")
    # 3. 根据搜索结果识别涉及的文件和模块
    output("⚠️ 未找到对应领域专家，基于代码搜索分析影响范围")

平台项目工作区检测: 当匹配到的关键词涉及平台组件（如 DataLoad、DataSave、ROI、VOI、Layout、Volume 等 平台 平台关键词）时，检查用户是否具备平台代码访问能力：

1. 检查工作区是否包含 {{PLATFORM_REPO}} 文件夹
2. 检查 .github/copilot-instructions.md 中是否配置了 DevOps MCP 仓库

如果两者都没有，使用 ask_questions 提示用户：

header: "平台项目"
question: "检测到 PBI 可能涉及平台组件（匹配关键词: {关键词}），但工作区未打开平台项目且未配置 DevOps 远程仓库。\n\n后续设计评审阶段需要读取平台源码进行接口分析，建议提前配置。"
options:
  - label: "我来添加平台项目到工作区"
    description: "将 {{PLATFORM_REPO}} 添加到多根工作区"
  - label: "已有 DevOps MCP，继续"
    description: "DevOps MCP 已配置，可远程搜索平台代码"
  - label: "跳过，继续返讲"
    description: "先完成需求返讲，后续设计评审时再处理"
    recommended: true

📌 此检测为提示性的，不阻断需求返讲流程。主要目的是让用户提前知晓，以便在进入设计评审阶段前做好准备。

步骤3: 应用检查清单

根据识别的模块，应用对应的检查清单:

🔴 全面匹配原则（强制）

检查清单是用户最信任的产出物之一，任何遗漏都可能导致后续分析出现毁灭性错误。 宁可多花资源全面分析，绝不能遗漏。

1. 穷尽所有章节: 必须扫描检查清单的每一个章节，不能只看"最明显相关"的一两个
2. 多维度关键词匹配: 从 PBI 标题和内容中提取所有功能关键词，分别与每个章节匹配
   • 示例: PBI「保存_VOI轮廓导入导出_ExportFormat」→ 关键词: 保存 + VOI + 轮廓 + 导入导出 + ExportFormat
   • 必须匹配: 保存功能章节 ✖ VOI管理章节 ✖ 数据加载章节 ✖ 配准联动章节 ✖ ...
3. 每个匹配章节的每一项都要列出: 不得只挑"高频影响"项，普通项也必须列出并给出判断
4. 跨章节关联检查: 当一个功能点在多个章节出现时（如 VOI 出现在加载/管理/保存多个章节），每个章节都要检查

❗ 反例警示: PBI"保存_VOI轮廓导入导出_ExportFormat"——如果只检查了「保存功能」章节，而遗漏了「VOI管理」「数据加载」「配准联动」等章节中的 VOI 相关项，就是严重遗漏。

🔍 代码验证（可选但推荐）: 对于“是否影响现有功能”“是否影响其他模块”等检查项， 如果仅靠 expert skill 文本描述无法确认，可用 grep_search 搜索项目代码中的调用关系来确认实际影响范围。

📁 用户配置的文档（本地优先）

🔴 优先从 .github/copilot-resources/docs/ 读取，避免工作区外文件授权弹窗。 降级时才从 .github/copilot-instructions.md 中的「项目文档配置」段落获取绝对路径。

配置项	本地优先路径	用途	使用时机
需求检查清单	.github/copilot-resources/docs/	检查需求完整性	步骤3 检查时读取
功能模块清单	.github/copilot-resources/docs/	识别受影响模块	步骤2 识别模块时参考
功能依赖关系	.github/copilot-resources/docs/	分析影响范围	步骤2/3 分析影响时参考

⚠️ 如果配置了这些文档，必须读取并在回复中声明参考了哪些文件

如未配置，使用以下通用检查项:

通用检查项:

功能完整性检查

• 需求描述是否清晰完整？
• 是否有遗漏的功能点？
• 边界条件是否明确？
• 异常场景是否考虑？

兼容性检查

• 是否影响现有功能？
• 是否需要数据迁移？
• 是否影响其他模块？

非功能性检查

• 性能要求是否明确？
• 多模态支持是否考虑？(PT/CT/MR/NM)
• 多语言是否需要支持？
• 多分辨率是否需要适配？

配置文件影响检查（FE↔BE 通路）

💡 当需求涉及新增功能、新消息通路或新界面组件时，检查是否需要修改运行时 XML 配置文件。 配置文件通常位于 appdata/{appname}/config/ 下。

• 是否需要新增 Operation/Widget/Model 注册？（[后端配置文件]）
• 是否需要新增 BE→FE 消息路由？（[前端命令配置]）
• Controller 级 Operation 链是否需要修改？（BE/WorkflowController.xml）
• 是否需要新增 Cell 初始化链？（[前端配置文件]）
• 是否需要新增 IoC 容器注册？（[前端容器配置]）

步骤4: 生成返讲文档

💡 金字塔原则: 结论先行，先给核心结论，再展开详细分析

文档结构要求:

1. 摘要先行: 开篇给出需求概要和核心结论
2. 支撑论点: 列出主要影响和风险
3. 详细展开: 功能拆解、检查清单、计划等

不进行分步确认: 直接输出完整文档

📌 模板填写提示:

• ### 相关PBI 表格数据来自步骤1-B 的 CSV 搜索结果
• 如果步骤1-B 找到相关记录，必须填入表格，不得留空
• 如果未配置 CSV 或无匹配，填写 "无历史相关PBI" 并注明原因

使用以下模板生成返讲文档:

返讲文档模板

# [PBI编号] 需求返讲

## 1. 需求概述

### 1.1 基本信息

| 属性 | 值 |
|------|-----|
| PBI编号 | [填写] |
| 需求标题 | [填写] |
| 所属迭代 | [填写] |
| 优先级 | [填写] |
| 预估工作量 | [填写] |

### 1.2 业务背景

[描述需求的业务背景和用户痛点]

### 1.3 功能点列表

| 序号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| 1 | [功能点名称] | [简要描述] | P0/P1/P2 |
| 2 | ... | ... | ... |

## 2. 需求理解

### 2.1 用户故事

作为 [用户角色]，
我希望 [功能描述]，
以便 [业务价值]。

### 2.2 业务流程

```mermaid
flowchart LR
    A[开始] --> B[步骤1]
    B --> C[步骤2]
    C --> D[结束]

2.3 界面交互

[如有原型图，附上链接或描述关键交互]

3. 影响分析

3.1 涉及模块

3.2 检查清单结果

[根据 docs/需求检查清单.md 逐项检查的结果]

3.3 依赖关系

• 上游依赖: [列出依赖的模块/功能]
• 下游影响: [列出会影响的模块/功能]

4. 风险与问题

4.1 识别的风险

4.2 待确认问题

📌 状态说明：🔴待确认 → ✅已确认 → ❌已取消。PM答复列填写沟通结果。

5. 开发计划

5.1 任务拆解

5.2 里程碑

6. 验收标准

6.1 功能验收

• [验收条件1]
• [验收条件2]

6.2 非功能验收

• 性能: [具体指标]
• 兼容性: [支持的模态/设备]

附录

相关PBI

参考资料

• [设计稿链接]
• [原型链接]
• [相关文档]

---

## 输出说明

完成需求返讲后，输出以下内容:

1. **返讲文档** - 按上述模板填写的完整文档
2. **检查清单** - 各模块检查项的结果汇总
3. **风险清单** - 识别的风险和待确认问题
4. **遗漏建议** - 可能遗漏的功能点或场景

## 示例

### 输入示例

**方式1: DevOps 链接**

帮我做需求返讲: https://your-devops-server.example.com/YourProject/_queries/edit/1073716/?triage=true

**方式2: 标准格式**

请分析这个 PBI: Product Backlog Item 1073716: PBI_Func_{{APP_NAME}}_Feature_XXX_功能优化

**方式3: 纯 ID**

需求返讲 1073716

**方式4: PBI 标题**

帮我评价下PBI PBI_Func_{{APP_NAME}}_Feature_XXX_功能优化

**方式5: 直接粘贴内容**

帮我做一下这个PBI的需求返讲: PBI-123456: VOI分割支持多阈值配置 需求描述: 用户希望在进行PET病灶分割时，能够配置多个阈值策略...

### 输出示例（自动获取 PBI 详情）

```markdown
📝 **正在执行: 需求返讲助手** (`#pbi-reviewer`)

✅ 已加载 Skill 指引
⭕ 当前步骤: 步骤0 - 智能解析 PBI 输入

---

📥 **步骤0: 解析 PBI 输入**

1️⃣ 识别输入类型:
   - 检测到: DevOps 链接
   - 提取 ID: 1073716

2️⃣ 获取 PBI 详情:
   🔧 调用 MCP: azureDevOps.get_work_item
   ✅ 获取成功

3️⃣ PBI 基本信息:
   - 标题: PBI_Func_{{APP_NAME}}_Feature_XXX_功能优化
   - 状态: Active
   - 迭代: Sprint 42
   - 优先级: P1

✅ 步骤0 完成
⭕ 当前步骤: 步骤1 - 解析需求

---

# PBI-1073716 需求返讲

## 1. 需求概述
...

相关资源

🔴 文档读取优先级（强制）

所有文档必须按以下优先级读取，禁止跳过本地副本直接读取绝对路径。

具体操作：

1. 先执行 list_dir(".github/copilot-resources/") 检查目录是否存在
2. 如果存在 → 从 docs/ 读取检查清单/模块清单/依赖关系，从 data/ 读取 PBI CSV
3. 如果不存在 → 从 copilot-instructions.md 获取路径后读取

历史 PBI 知识库

如果配置了 PBI CSV，工具会自动将其转换为分层 Markdown 存放在 .github/copilot-resources/data/ 下：

• 索引文件 (*-index.md): 轻量表格（~400行），含 ID/Title/State/Keywords/RefLinks 列，优先读取
• 详情文件 (*-detail.md): 完整内容（~10000行），每个 PBI 一个 ## PBI-{id} section，按需用 grep_search + read_file 读取

双路搜索工作流: 先读索引匹配 → 再 grep_search 详情补充 → 合并去重 → read_file 读取目标 section

默认资源

• 检查清单: .github/copilot-resources/docs/ 下的检查清单文件
• 功能模块: .github/copilot-resources/docs/ 下的模块清单文件
• 依赖关系: .github/copilot-resources/docs/ 下的依赖关系文件
• 历史PBI: .github/copilot-resources/data/ 下的 Markdown 文件（从CVS自动转换）
• 专家索引: #expert-index

📚 参考来源声明模板

执行完成时，必须输出以下声明：

📚 **参考来源**:
- MCP DevOps: [成功获取 PBI-XXXXXX / 不可用]
- 历史PBI: [索引文件名] + [详情文件名] (X 条相关记录) / 未配置
- 检查清单: [文件路径] / 使用通用检查项
- 功能模块: [文件路径] / 未配置
- 依赖关系: [文件路径] / 未配置
- 领域专家: [调用的专家列表]

步骤5: 发布文档（默认执行）

⚙️ 默认策略: 飞书优先，MCP 不可用时自动降级为本地 Markdown

执行流程：

生成返讲文档
    │
    ▼
检测飞书 MCP 工具是否可用
    │
    ├── 可用 → 调用 #lark-doc-generator → 输出飞书文档链接
    │
    └── 不可用 → 输出本地 Markdown 文档 + 配置提示

5.1 飞书 MCP 可用时（默认路径）

🔗 **自动调用**: `#lark-doc-generator`
   原因: 默认发布到飞书

⭕ 正在将返讲文档发布到飞书...

5.2 完整示例

用户输入:

需求返讲 1073716

AI 执行流程:

📝 **正在执行: 需求返讲助手** (`#pbi-reviewer`)

✅ 步骤0-4 完成: 生成返讲文档
   产出: [PBI-1073716 需求返讲文档]

🔗 **自动调用**: `#lark-doc-generator`
   原因: 默认发布到飞书（飞书优先策略）

---

🚀 **正在执行: 飞书文档生成器** (`#lark-doc-generator`)

✅ 已将文档发布到飞书
📄 飞书文档链接: https://xxx.feishu.cn/docx/xxxxx

---

✅ **执行完成**: 需求返讲助手

参考来源:
- Skill: `#pbi-reviewer` → `#lark-doc-generator`
- MCP DevOps: 成功获取 PBI-1073716
- 飞书文档: 已发布

产出物: 
1. 飞书文档链接（主要）
2. 本地 Markdown 备份

5.3 飞书 MCP 不可用时（降级路径）

如果飞书 MCP 工具不可用，自动降级为本地 Markdown：

⚠️ **飞书 MCP 不可用，已降级为本地 Markdown**

✅ 已生成本地文档: `docs/PBI-1073716-需求返讲.md`

💡 如需发布到飞书，请先配置飞书 MCP:
   1. 运行 `docs/setup-lark-mcp.ps1` 配置飞书 MCP
   2. 或参考 `#lark-mcp-troubleshooting` 排查连接问题
   3. 配置完成后重新执行本命令

5.4 禁用飞书发布（可选）

如用户明确要求只生成本地文档，可跳过飞书发布：

需求返讲 1073716 --local-only
需求返讲 1073716，只生成本地文档

步骤6: 产出持久化 + 下一步建议（自动输出）

6.0 持久化返讲文档（强制）

🔴 必须在输出返讲文档后，将完整文档写入文件，供后续对话（如圆桌会议）直接读取。

# 根据 PBI ID 生成文件路径
review_path = f".copilot-temp/pbi-{pbi_id}-review.md"
create_file(review_path, review_document_with_context_summary)

📌 如果 .copilot-temp/ 目录不存在，自动创建。该目录已通过 .git/info/exclude 排除。

🔴 持久化文件必须包含的内容结构

写入文件的内容必须按以下结构组织，确保新对话能仅通过读取此文件就完全恢复上下文：

# PBI {ID} 需求返讲文档

## 上下文摘要（供新对话读取）

| 属性 | 值 |
|------|------|
| PBI ID | {ID} |
| 标题 | {标题} |
| 模块 | {所属功能模块} |
| 涉及平台组件 | {是/否 + 组件名} |
| 创建时间 | {YYYY-MM-DD HH:mm} |
| 待澄清问题数 | {N 个待确认 / M 个已确认} |

### 关键文件路径
- FE: `src/{{PLATFORM_NAMESPACE}}.{Module}/...`
- BE: `src/{{PLATFORM_NS_PREFIX}}{Module}/...`
- 平台: `{{PLATFORM_REPO}}/{Component}/...`

### 关键技术决策
- {决策1}: {简述}
- {决策2}: {简述}

---

## 正文（返讲文档内容）

{完整的返讲文档内容，包含所有分析、检查清单、待澄清问题等}

## CLARIFICATION_LIST

<!-- CLARIFICATION_LIST_START -->
{待确认问题表格}
<!-- CLARIFICATION_LIST_END -->

## 下一步建议
- 用圆桌会议分析 PBI {ID}: `用圆桌会议分析 PBI {ID}`

🔴 禁止写入的内容：

• 中间搜索过程（grep_search 结果、MCP 调用记录）
• 文件全文副本（只保留路径，新对话自己读取）
• 对话中的来回讨论和已淘汰的备选方案
• 多轮修正中的历史错误版本（只保留最终正确版本）

🔴 修正场景处理

如果用户在文档生成后要求修正（“这里分析不对，应该是XXX”）：

1. 修正内容后，必须立即覆写持久化文件：

   # 修正后立即覆写，不是追加
   create_file(f".copilot-temp/pbi-{pbi_id}-review.md", corrected_full_content)
   

   修正完成后输出：📄 返讲文档已更新并重新保存到 .copilot-temp/pbi-{ID}-review.md

2. 修正超过 3 轮时，建议新开对话（避免历史错误版本污染上下文）

6.1 下一步建议 + 新对话引导

返讲文档生成并发布后，自动输出以下提示：

---

💡 **下一步 & 对话建议**:
- 产出已保存到: `.copilot-temp/pbi-{ID}-review.md`
- 如需进入设计评审阶段，建议**新开对话**输入:
  `用圆桌会议分析 PBI {ID}`
- 在新对话中，AI 会自动读取本次返讲文档作为设计输入

> ⚠️ 建议先与 PM 确认所有待澄清问题后，再启动设计评审。

6.2 需求澄清检查（ask_questions 引导）

如果返讲过程中发现了待确认/待澄清的问题，必须使用 ask_questions 对话框提醒用户：

header: "需求澄清"
question: "返讲中发现以下待确认问题，建议进入设计阶段前与 PM/相关人士沟通确认：\n\n[列出所有待确认问题，含 ID]\n\n⚠️ 未澄清的问题如果直接进入设计阶段，可能导致设计方案偏离实际需求。"
options:
  - label: "我已了解，稍后去确认"
    description: "记录待确认问题，后续与 PM 沟通后再启动设计评审"
    recommended: true
  - label: "这些问题可以跳过，直接出设计"
    description: "基于当前理解直接进入圆桌会议设计评审"
  - label: "帮我整理澄清沟通要点"
    description: "生成一份可以发给 PM 的问题清单"
  - label: "部分问题已确认，帮我更新状态"
    description: "录入 PM 答复，更新待确认问题的状态"
    allowFreeformInput: true

🔴 如果没有待确认问题，跳过此对话框，直接输出下一步建议。

📌 用户选择“部分问题已确认”时：根据用户输入的 PM 答复，更新返讲文档中 CLARIFICATION_LIST 标记区段内对应行的状态（🔴待确认 → ✅已确认）和 PM答复列，使用 replace_string_in_file 更新本地文档。