---
name: pbi-reviewer
description: |
  需求返讲助手 - 帮助研发人员进行需求评审和返讲文档撰写。
  触发关键词: 需求返讲、评审需求、返讲文档、检查需求、需求拆解、PBI评审、需求完整性。
  输入: DevOps PBI链接、需求描述、或PBI内容。
  输出: 需求返讲文档、检查清单结果、风险点、遗漏项。
  适用场景: 收到PM需求后进行评审、检查需求完整性、撰写返讲文档。
---

# 需求返讲助手

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

---

## 执行声明规范

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

### 开始执行时

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

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

### 调用其他专家时

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

### 每个步骤完成时

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

### 遇到问题时

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

### 执行完成时

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

参考来源:
- 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 详情**，不得跳过！

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

| 格式 | 示例 | 解析方式 |
|------|------|----------|
| DevOps 链接 | `https://your-devops-server.example.com/YourProject/_queries/edit/1073716/...` | 从 URL 提取数字 ID |
| 工作项格式 | `Product Backlog Item 1073716: PBI_Func_...` | 提取 "Item" 后的数字 |
| 纯数字 ID | `1073716` | 直接使用 |
| PBI 标题 | `PBI_Func_{{APP_NAME}}_Feature_XXX_功能优化
| 自然语言 | `帮我评价下PBI PBI_Func_{{APP_NAME}}_Feature_XXX_功能优化

**解析正则表达式：**
```javascript
// 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 返回内容对比（务必选对工具）**

| API | Description | AcceptanceCriteria | 适用场景 |
|-----|:-----------:|:------------------:|----------|
| `get_work_item` | ✅ 完整返回 | ✅ 完整返回 | 获取单个 PBI 详情（**必须用这个**） |
| `list_work_items` | ❌ 始终为空 | ❌ 始终为空 | 仅用于批量查 ID/Title/State |
| `search_work_items` | ⚠️ 仅摘要 | ❌ 不返回 | 关键词模糊搜索 |

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

如果只有标题没有 ID，使用搜索：
```
工具名称: mcp_azuredevops_search_work_items  
参数:
  - query: <PBI标题>
```

**🟡 MCP 不可用时的备选方案**

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

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

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

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

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

**执行流程：**
```markdown
📥 **步骤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 知识库**:

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

**输出格式**:

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

**📚 参考来源更新**:
```
- 历史PBI: [索引文件名] + [详情文件名] (Z 条相关记录) / 未配置
```

### 步骤2: 识别功能模块

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

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

```python
# 扫描 .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，执行以下降级：

```python
# 降级：搜索项目代码确认影响范围
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" 并注明原因

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

---

## 返讲文档模板

```markdown
# [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 逐项检查的结果]

| 检查项 | 结果 | 备注 |
|--------|------|------|
| [检查项] | Y/N/待确认 | [备注] |

### 3.3 依赖关系

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

## 4. 风险与问题

### 4.1 识别的风险

| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| [风险描述] | 高/中/低 | [措施] |

### 4.2 待确认问题

<!-- CLARIFICATION_LIST_START -->
| ID | 问题 | 状态 | 负责人 | PM答复 |
|----|------|------|--------|--------|
| Q1 | [问题描述] | 🔴待确认 | [PM/研发] | - |
<!-- CLARIFICATION_LIST_END -->

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

## 5. 开发计划

### 5.1 任务拆解

| 任务 | 预估工时 | 依赖 |
|------|----------|------|
| [任务描述] | [X]h | [依赖任务] |

### 5.2 里程碑

| 里程碑 | 日期 | 交付物 |
|--------|------|--------|
| 需求返讲 | [日期] | 返讲文档 |
| 设计评审 | [日期] | 设计文档 |
| 开发完成 | [日期] | 代码提交 |
| 测试完成 | [日期] | 测试报告 |

## 6. 验收标准

### 6.1 功能验收

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

### 6.2 非功能验收

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

---

## 附录

### 相关PBI

| 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. 需求概述
...
```

## 相关资源

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

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

| 优先级 | 路径 | 说明 |
|--------|------|------|
| ➀ 本地副本（优先） | `.github/copilot-resources/docs/` 和 `.github/copilot-resources/data/` | 工具自动复制，工作区内文件，无需授权 |
| ➁ 配置路径（降级） | `.github/copilot-instructions.md` 中的「项目文档配置」表格 | 可能是绝对路径，会触发授权弹窗 |

**具体操作**：
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

| 索引表列名 | 说明 |
|------|------|
| `ID` | PBI 编号 |
| `Title` | 标题 |
| `State` | 状态 |
| `Keywords` | 从描述中自动提取的领域关键词 |
| `RefLinks` | 描述中引用的 URL |

### 默认资源

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

### 📚 参考来源声明模板

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

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

---

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

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

**执行流程**：

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

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

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

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

### 5.2 完整示例

**用户输入**:
```
需求返讲 1073716
```

**AI 执行流程**:
```markdown
📝 **正在执行: 需求返讲助手** (`#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：

```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 持久化返讲文档（强制）

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

```python
# 根据 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` 排除。

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

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

```markdown
# 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. **修正内容后，必须立即覆写持久化文件**：
   ```python
   # 修正后立即覆写，不是追加
   create_file(f".copilot-temp/pbi-{pbi_id}-review.md", corrected_full_content)
   ```
   修正完成后输出：`📄 返讲文档已更新并重新保存到 .copilot-temp/pbi-{ID}-review.md`

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

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

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

```markdown
---

💡 **下一步 & 对话建议**:
- 产出已保存到: `.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` 更新本地文档。