需求文档skill回溯专家博弈之前

.claude/skills/requirement-generator-v1/开发文档.md

@@ -0,0 +1,393 @@
+# requirement-generator-v1 - 开发文档
+
+## 核心设计理念
+
+设计原则:
+
+1. **动态适应用户能力**: 业务语言优先，通过观察用户回答动态评估其技术深度，切换语言风格
+2. **允许用户中途介入**：允许用户中途完全介入，及时修正
+3. **多专家博弈评审**：4位专家独立评审 + 两轮交叉博弈，通过观点碰撞提升评审质量
+4. **用户需求基准原则**：以用户原始需求为最高准则，专家建议不可违背用户核心需求
+5. **最终校验确保质量**：确保最终的需求文档以客观、陈述性输出，前后逻辑闭环，无明显矛盾
+
+## 执行流程概览
+
+```mermaid
+flowchart TB
+    subgraph Phase1_4["阶段 1-4: 需求生成"]
+        A[用户描述] --> B[项目类型判断]
+        B --> C[智能访谈]
+        C --> D[生成 requirement.md]
+    end
+
+    subgraph Phase5["阶段 5: 用户交互"]
+        D --> E{用户选择}
+        E -->|修改| F[修改文档]
+        F --> E
+        E -->|结束| G[流程结束]
+    end
+
+    subgraph Phase6["阶段 6: 多角色评审"]
+        E -->|进入评审| H[领域识别]
+
+        subgraph Review["独立评审"]
+            H --> I1[开发专家]
+            H --> I2[产品经理]
+            H --> I3[AI专家]
+            H --> I4[领域专家]
+        end
+
+        subgraph Debate1["博弈-评价阶段"]
+            I2 & I3 & I4 --> J1[开发专家评价]
+            I1 & I3 & I4 --> J2[产品经理评价]
+            I1 & I2 & I4 --> J3[AI专家评价]
+            I1 & I2 & I3 --> J4[领域专家评价]
+        end
+
+        subgraph Debate2["博弈-回应阶段"]
+            J2 & J3 & J4 --> K1[开发专家回应]
+            J1 & J3 & J4 --> K2[产品经理回应]
+            J1 & J2 & J4 --> K3[AI专家回应]
+            J1 & J2 & J3 --> K4[领域专家回应]
+        end
+
+        K1 & K2 & K3 & K4 --> L{决策模式}
+        L -->|用户确认| M1[req_consolidator]
+        L -->|自动应用| M2[req_auto_consolidator]
+        M1 & M2 --> N[requirement_final.md]
+        N --> O[质量审查]
+        O --> P[输出最终总结]
+    end
+```
+
+## 阶段详细说明
+
+### 阶段 1-4: 需求生成
+
+```
+用户描述 → 项目类型判断 → 智能访谈 → 生成需求文档(requirement.md)
+```
+
+### 阶段 5: 用户交互
+
+系统展示文档概览，询问用户选择下一步操作：
+- **修改**: 用户编辑或提出修改建议，完成后再次询问
+- **进入多角色评审**: 进入阶段6
+- **结束**: 直接使用当前版本
+
+### 阶段 6: 多角色评审
+
+#### 6.1 领域识别与角色生成
+
+读取 requirement.md，分析项目领域特征，生成领域专家角色定义，保存到 `temp/domain_role.md`。
+
+#### 6.2 独立评审（并行）
+
+4位专家并行评审 requirement.md：
+
+| 专家 | 输出文件 | 评审重点 |
+|------|----------|----------|
+| 开发专家 | `temp/review_dev.json` | 技术可行性、架构、性能、风险 |
+| 产品经理 | `temp/review_pm.json` | 业务目标、用户价值、场景完整性 |
+| AI专家 | `temp/review_ai.json` | 智能化需求合理性、AI能力边界 |
+| 领域专家 | `temp/review_domain.json` | 领域合规性、行业规范、特殊要求 |
+
+#### 6.3 博弈-评价阶段：交叉评价（并行）
+
+每位专家阅读其他3位专家的评审结果，对有冲突、不合理或需要补充的观点进行评价：
+
+| 专家 | 读取文件 | 输出文件 |
+|------|----------|----------|
+| 开发专家 | review_pm/ai/domain.json | `temp/evaluate_dev.json` |
+| 产品经理 | review_dev/ai/domain.json | `temp/evaluate_pm.json` |
+| AI专家 | review_dev/pm/domain.json | `temp/evaluate_ai.json` |
+| 领域专家 | review_dev/pm/ai.json | `temp/evaluate_domain.json` |
+
+**评价输出格式**（必须包含目标定位）：
+```json
+{
+  "responses": [
+    {
+      "target_expert": "产品经理",
+      "target_file": "temp/review_pm.json",
+      "target_location": "issues[2]",
+      "target_content": "对方观点摘要",
+      "my_comment": "我的评价",
+      "reasoning": "专业理由"
+    }
+  ]
+}
+```
+
+#### 6.4 博弈-回应阶段：交叉回应（并行）
+
+每位专家只读取针对自己的评价，决定是否修正原始观点，确定最终立场：
+
+| 专家 | 读取内容 | 输出文件 |
+|------|----------|----------|
+| 开发专家 | evaluate_*.json 中 target_expert="开发专家" | `temp/response_dev.json` |
+| 产品经理 | evaluate_*.json 中 target_expert="产品经理" | `temp/response_pm.json` |
+| AI专家 | evaluate_*.json 中 target_expert="AI专家" | `temp/response_ai.json` |
+| 领域专家 | evaluate_*.json 中 target_expert="领域专家" | `temp/response_domain.json` |
+
+**回应输出包含**：
+- `final_issues`: 最终问题列表（含 consensus_level: unanimous/majority/contested）
+- `withdrawn_issues`: 被说服后撤回的问题
+- `new_issues_from_debate`: 博弈中新发现的问题
+
+#### 6.5 决策模式选择
+
+询问用户选择处理方式：
+- **用户确认模式**: 调用 `req_consolidator`，逐项与用户确认
+- **自动应用模式**: 调用 `req_auto_consolidator`，自动评估并应用
+
+#### 6.6 汇总整合
+
+汇总Agent读取 **14个文件**：
+
+| 类别 | 文件 | 数量 |
+|------|------|------|
+| 用户需求基准 | `temp/interview_result.json` | 1 |
+| 原始需求文档 | `requirement.md` | 1 |
+| 初始评审 | `temp/review_*.json` | 4 |
+| 交叉评价 | `temp/evaluate_*.json` | 4 |
+| 交叉回应 | `temp/response_*.json` | 4 |
+
+**合并决策规则**：
+1. **可以采纳**: 优化补充用户需求、细化实现细节的建议
+2. **谨慎采纳**: 与用户需求有出入但专家一致认同的建议
+3. **禁止采纳**: 完全背离用户原始需求的建议（即使专家全员同意）
+
+**共识度处理**：
+- `unanimous`（全员一致）: 自动采纳
+- `majority`（多数同意）: 自动采纳
+- `contested`（存在争议）: 按裁决规则处理或询问用户
+
+#### 6.7 质量审查
+
+调用 `review_report` 检查最终文档：
+- 文档结构是否符合模板（不能有多余章节）
+- 客观性（无评审标注、讨论性词汇）
+- 逻辑严谨性（前后无矛盾）
+- 闭环性（功能描述完整）
+- 业务完整性（无"待确认"的业务问题）
+
+## 专家博弈流程图
+
+```mermaid
+sequenceDiagram
+    participant Main as 主窗口
+    participant Dev as 开发专家
+    participant PM as 产品经理
+    participant AI as AI专家
+    participant Domain as 领域专家
+    participant Consolidator as 汇总Agent
+
+    Note over Main: 阶段6.2 独立评审
+    par 并行评审
+        Main->>Dev: mode: review
+        Main->>PM: mode: review
+        Main->>AI: mode: review
+        Main->>Domain: mode: review
+    end
+    Dev-->>Main: review_dev.json
+    PM-->>Main: review_pm.json
+    AI-->>Main: review_ai.json
+    Domain-->>Main: review_domain.json
+
+    Note over Main: 阶段6.3 博弈-评价阶段
+    par 并行评价
+        Main->>Dev: mode: evaluate
+        Main->>PM: mode: evaluate
+        Main->>AI: mode: evaluate
+        Main->>Domain: mode: evaluate
+    end
+    Dev-->>Main: evaluate_dev.json
+    PM-->>Main: evaluate_pm.json
+    AI-->>Main: evaluate_ai.json
+    Domain-->>Main: evaluate_domain.json
+
+    Note over Main: 阶段6.4 博弈-回应阶段
+    par 并行回应
+        Main->>Dev: mode: respond
+        Main->>PM: mode: respond
+        Main->>AI: mode: respond
+        Main->>Domain: mode: respond
+    end
+    Dev-->>Main: response_dev.json
+    PM-->>Main: response_pm.json
+    AI-->>Main: response_ai.json
+    Domain-->>Main: response_domain.json
+
+    Note over Main: 阶段6.6 汇总整合
+    Main->>Consolidator: 整合14个文件
+    Consolidator-->>Main: requirement_final.md
+```
+
+## Agent 协作架构
+
+### 需求生成 Agents (阶段1-4)
+
+| Agent | 职责 | 关键能力 |
+|-------|------|---------|
+| **project_type_matcher** | 项目类型识别 | 语义匹配，置信度分级 |
+| **req_interviewer** | 智能访谈 | 动态评估技术深度，业务到技术转化 |
+| **req_writer** | 文档生成 | 模板驱动，决策标注 |
+
+### 评审 Agents (阶段6)
+
+| Agent | 视角 | 重点 | 工作模式 |
+|-------|------|------|----------|
+| **dev_expert_reviewer** | 技术 | 可行性、架构、性能、风险 | review/evaluate/respond |
+| **pm_reviewer** | 业务 | 目标、价值、场景、验收标准 | review/evaluate/respond |
+| **ai_expert_reviewer** | 智能化 | AI能力边界、智能化合理性 | review/evaluate/respond |
+| **domain_expert_reviewer** | 领域 | 合规性、行业规范、特殊要求 | review/evaluate/respond |
+| **req_consolidator** | 整合 | 用户确认模式，多轮交互 | - |
+| **req_auto_consolidator** | 整合 | 自动评估模式，无用户交互 | - |
+| **review_report** | 质量 | 客观性、逻辑严谨性、业务完整性 | - |
+
+## 目录结构
+
+```
+requirement-generator-v1/
+├── SKILL.md                    # 主流程（简化版）
+├── 开发文档.md                 # 本文档
+├── references/                 # 详细指南（渐进式披露）
+│   ├── phase3_interview_guide.md
+│   └── phase6_review_guide.md
+├── assets/                     # 项目类型配置
+│   ├── agent_dev.md
+│   ├── feature_update.md
+│   └── testing.md
+└── templates/                  # 需求文档模板
+    ├── agent_dev_template.md
+    ├── feature_update_template.md
+    └── testing_template.md
+
+项目 agents/ (D:\AA_Work\AIEC-团队开发规范Skills\.claude\agents\)
+├── project_type_matcher.md
+├── req_interviewer.md
+├── req_writer.md
+├── dev_expert_reviewer.md
+├── pm_reviewer.md
+├── ai_expert_reviewer.md
+├── domain_expert_reviewer.md
+├── req_consolidator.md
+├── req_auto_consolidator.md
+└── review_report.md
+
+temp/ (运行时生成)
+├── interview_result.json       # 访谈结果
+├── domain_role.md              # 领域专家角色定义
+├── review_dev.json             # 开发专家初始评审
+├── review_pm.json              # 产品经理初始评审
+├── review_ai.json              # AI专家初始评审
+├── review_domain.json          # 领域专家初始评审
+├── evaluate_dev.json           # 开发专家交叉评价
+├── evaluate_pm.json            # 产品经理交叉评价
+├── evaluate_ai.json            # AI专家交叉评价
+├── evaluate_domain.json        # 领域专家交叉评价
+├── response_dev.json           # 开发专家交叉回应
+├── response_pm.json            # 产品经理交叉回应
+├── response_ai.json            # AI专家交叉回应
+├── response_domain.json        # 领域专家交叉回应
+└── consolidation_report.json   # 汇总应用记录（自动模式）
+```
+
+## 数据传递策略
+
+本 Skill 采用以下数据传递模式：
+
+| 传递方向 | 策略 | 说明 |
+|----------|------|------|
+| 主窗口 → Agent | 标识符/模式 | 仅传递 `mode: review/evaluate/respond` |
+| Agent → temp/ | JSON文件 | 结构化数据存储，便于其他Agent读取 |
+| Agent → 主窗口 | 概要文字 | 简洁提示，详细数据在文件中 |
+| Agent → Agent | 文件路径 | 通过 `temp/*.json` 传递，主窗口不加载 |
+
+## 关键设计决策
+
+### 1. 专家博弈机制
+
+采用博弈机制提升评审质量，每轮博弈包含两个阶段：
+- **评价阶段**: 专家指出其他专家观点中的问题
+- **回应阶段**: 专家根据评价决定是否修正
+
+**设计理由**: 单轮评审可能存在盲点，博弈过程可发现更多问题，共识度标注帮助汇总决策。
+
+### 2. 原始评审不可变
+
+`review_*.json` 在生成后保持不变，所有修正记录在 `response_*.json` 中。
+
+**设计理由**: 保留完整的观点演变历史，便于追溯和审计。
+
+### 3. 用户需求基准原则
+
+汇总时以 `interview_result.json` 中的用户原始需求为最高准则，专家建议不可违背。
+
+**设计理由**: 专家是辅助角色，最终产品要满足用户需求。
+
+### 4. Agent 自治性
+
+所有 Agent 采用自治设计模式：
+- 执行规则、工具使用规范固化在 Agent 定义中
+- Agent 自行读取配置文件（路径在 Agent 定义中硬编码）
+- 主窗口仅传递模式标识，不传递执行逻辑
+
+### 5. 文档版本管理
+
+采用双文档策略保留完整历史：
+- `requirement.md`: 初版文档，生成后不再修改
+- `requirement_final.md`: 评审优化版，仅在阶段6生成
+
+## 扩展指南
+
+### 添加新项目类型
+
+1. 参考现有配置文件（如 `assets/agent_dev.md`）创建新配置
+2. 编辑 frontmatter 字段：type, keywords, priority
+3. 定义核心问题（业务版本 + 技术版本）
+4. 设计业务到技术的映射规则
+5. 创建对应的文档模板 `templates/{type}_template.md`
+6. 测试访谈流程和文档生成完整性
+
+### 添加新评审专家
+
+1. 在 `agents/` 目录创建新专家定义文件
+2. 实现三种工作模式：review/evaluate/respond
+3. 定义专家视角和评审重点
+4. 更新 SKILL.md 和 phase6_review_guide.md 中的调用列表
+5. 更新汇总 Agent 的文件读取列表
+
+## 常见场景处理
+
+### 用户描述过于简短
+
+当 project_type_matcher 返回低置信度时：
+1. 系统列出所有可用项目类型供用户选择
+2. req_interviewer 通过多轮访谈补充缺失信息
+
+### 用户选择"未知类型"
+
+系统采用开放式访谈模式：
+1. req_interviewer 通过开放式问题理解项目本质
+2. Agent 自主决定文档结构
+3. req_writer 根据 custom_sections 构建文档（不使用预定义模板）
+
+### 专家意见严重冲突
+
+当 `contested` 级别问题较多时：
+- **用户确认模式**: 向用户展示争议双方观点，由用户决定
+- **自动应用模式**: 按裁决规则处理（合规性优先 > 技术可行性优先 > 用户价值优先）
+
+### 博弈后仍有分歧
+
+即使博弈后仍有 `contested` 问题：
+1. 汇总 Agent 根据裁决规则自动处理
+2. 在 `consolidation_report.json` 中记录裁决过程
+3. 用户可事后查看裁决依据
+
+---
+
+**最后更新**: 2025-12-01
+**Skill 版本**: v1