@zeyue0329/xiaoma-cli 1.0.42 → 1.0.44

package/xiaoma-core/tasks/requirement-analysis-with-rag.md

@@ -0,0 +1,352 @@
+<!-- Powered by XiaoMa™ Core -->
+
+# 基于知识库的需求分析任务
+
+## Purpose
+
+通过结合外部需求文档(req.txt)和知识库(RAG/MCP)进行深度需求分析，生成高质量的PRD文档。
+
+## Workflow Overview
+
+```
+req.txt → 问题生成 → 知识库查询 → 知识落地(docs/rag/) → 需求分析 → PRD生成
+```
+
+## Phase 1: 需求文档解析与问题生成
+
+### 1.1 需求文档初步解析
+
+首先读取并分析 req.txt 文档，识别以下关键信息：
+
+```yaml
+解析维度:
+  业务领域: 识别需求所属的业务领域和子领域
+  核心功能: 提取需求描述的主要功能点
+  用户角色: 识别涉及的用户类型和角色
+  业务流程: 提取隐含或显式的业务流程
+  数据实体: 识别涉及的数据对象和关系
+  集成点: 识别与外部系统的交互需求
+  约束条件: 提取技术、业务、时间等约束
+  模糊点: 标记需要澄清的不明确内容
+```
+
+### 1.2 知识库问题生成框架
+
+基于解析结果，生成以下类别的问题向知识库查询：
+
+---
+
+## Phase 2: 知识库提问清单模板
+
+### 类别 A: 业务知识查询
+
+#### A1. 业务领域背景
+```
+问题模板:
+- "关于[业务领域]，现有系统中有哪些相关的业务规则和约束？"
+- "[业务流程名称]的完整流程是什么？包括哪些步骤和参与者？"
+- "在[业务场景]中，有哪些已知的边界情况和异常处理逻辑？"
+- "[业务概念A]和[业务概念B]之间的关系是什么？"
+```
+
+#### A2. 现有功能调研
+```
+问题模板:
+- "系统中是否已存在类似[功能描述]的功能？如果有，实现方式是什么？"
+- "[模块名称]目前支持哪些操作？有什么限制？"
+- "用户当前如何完成[业务目标]？现有流程有什么痛点？"
+```
+
+#### A3. 业务规则确认
+```
+问题模板:
+- "[数据实体]的业务规则有哪些？例如：必填字段、取值范围、状态流转规则"
+- "[操作A]在什么条件下可以执行？有哪些前置条件？"
+- "不同[用户角色]在[功能]上的权限差异是什么？"
+```
+
+---
+
+### 类别 B: 技术知识查询
+
+#### B1. 系统架构
+```
+问题模板:
+- "现有系统的技术架构是什么？使用了哪些核心框架和技术栈？"
+- "[模块名称]的代码结构和目录组织是怎样的？"
+- "系统的数据库设计采用什么模式？主要的数据表有哪些？"
+- "系统中有哪些公共组件和工具类可以复用？"
+```
+
+#### B2. 接口与集成
+```
+问题模板:
+- "与[外部系统]的集成接口是什么？数据格式和协议是什么？"
+- "系统提供了哪些API接口？[功能相关]的接口规范是什么？"
+- "现有的消息队列/事件机制是如何设计的？"
+```
+
+#### B3. 数据模型
+```
+问题模板:
+- "[数据实体]在数据库中的表结构是什么？包含哪些字段？"
+- "[实体A]和[实体B]之间的数据库关系是怎样的？"
+- "系统中有哪些枚举值或字典表与[业务领域]相关？"
+```
+
+#### B4. 代码实现参考
+```
+问题模板:
+- "类似[功能]的实现在代码中是如何组织的？请提供示例代码位置"
+- "[技术方案]在现有代码中有没有参考实现？"
+- "系统中处理[技术问题]的通用模式是什么？"
+```
+
+---
+
+### 类别 C: 历史需求与变更
+
+#### C1. 相关需求追溯
+```
+问题模板:
+- "之前有没有类似[需求描述]的需求？实现情况如何？"
+- "[功能模块]的历史变更记录有哪些？最近的改动是什么？"
+- "有没有与[需求]相关的已知问题或技术债务？"
+```
+
+#### C2. 决策记录
+```
+问题模板:
+- "[技术方案]为什么选择了当前的实现方式？有什么历史背景？"
+- "[设计决策]有没有相关的ADR(架构决策记录)？"
+```
+
+---
+
+### 类别 D: 上下文与约束
+
+#### D1. 项目约束
+```
+问题模板:
+- "项目的技术栈限制有哪些？必须遵循的技术规范是什么？"
+- "项目的安全合规要求有哪些？"
+- "项目的性能要求和SLA标准是什么？"
+```
+
+#### D2. 团队规范
+```
+问题模板:
+- "团队的代码规范和开发流程是什么？"
+- "团队的测试要求和代码审查标准是什么？"
+- "项目的部署流程和环境配置是怎样的？"
+```
+
+---
+
+## Phase 3: 问题生成执行流程
+
+### 3.1 智能问题生成
+
+```yaml
+执行步骤:
+  步骤1_解析需求:
+    输入: req.txt
+    动作: 提取关键实体、流程、约束
+    输出: 需求要素清单
+
+  步骤2_映射问题类别:
+    输入: 需求要素清单
+    动作: 将每个要素映射到问题类别(A/B/C/D)
+    输出: 问题类别映射表
+
+  步骤3_生成具体问题:
+    输入: 问题类别映射表 + 问题模板
+    动作: 用具体内容填充模板生成问题
+    输出: 知识库查询问题清单
+
+  步骤4_问题优先级排序:
+    优先级规则:
+      P0_阻塞级: 缺失会导致无法理解需求的核心问题
+      P1_重要级: 影响需求完整性的问题
+      P2_补充级: 有助于优化实现的问题
+```
+
+### 3.2 问题清单输出格式
+
+```markdown
+# 知识库查询问题清单
+
+## 基本信息
+- 需求文档: req.txt
+- 生成时间: {{timestamp}}
+- 问题总数: {{total_count}}
+
+## P0 阻塞级问题 (必须回答)
+
+### 业务知识
+1. [A1-001] {{具体问题}}
+   - 关联需求点: {{需求中的相关描述}}
+   - 预期答案类型: {{期望获得的信息类型}}
+
+### 技术知识
+2. [B1-001] {{具体问题}}
+   - 关联需求点: {{需求中的相关描述}}
+   - 预期答案类型: {{期望获得的信息类型}}
+
+## P1 重要级问题 (建议回答)
+...
+
+## P2 补充级问题 (可选回答)
+...
+```
+
+---
+
+## Phase 4: 知识落地与组织
+
+### 4.1 知识存储结构
+
+```
+docs/rag/
+├── _index.md                    # 知识索引文件
+├── business/                    # 业务知识
+│   ├── domain-rules.md         # 业务规则
+│   ├── processes.md            # 业务流程
+│   └── entities.md             # 业务实体
+├── technical/                   # 技术知识
+│   ├── architecture.md         # 系统架构
+│   ├── data-model.md          # 数据模型
+│   ├── apis.md                 # 接口规范
+│   └── code-patterns.md        # 代码模式
+├── history/                     # 历史信息
+│   ├── related-requirements.md # 相关需求
+│   └── decisions.md            # 决策记录
+└── constraints/                 # 约束条件
+    ├── technical.md            # 技术约束
+    └── compliance.md           # 合规要求
+```
+
+### 4.2 知识文档格式
+
+```markdown
+# {{知识标题}}
+
+## 元信息
+- 来源: 知识库MCP查询
+- 查询问题: {{原始问题}}
+- 查询时间: {{timestamp}}
+- 置信度: {{high/medium/low}}
+
+## 内容摘要
+{{一句话总结}}
+
+## 详细内容
+{{知识库返回的完整内容}}
+
+## 与需求的关联
+- 关联需求点: {{req.txt中的相关内容}}
+- 影响分析: {{这个知识如何影响需求实现}}
+
+## 后续问题
+{{基于此知识产生的新问题(如有)}}
+```
+
+---
+
+## Phase 5: 需求分析与PRD生成
+
+### 5.1 分析输入整合
+
+```yaml
+分析输入:
+  主要输入:
+    - req.txt: 原始需求文档
+    - docs/rag/*: 知识库查询结果
+  辅助输入:
+    - 项目简报(如存在): docs/brief.md
+    - 技术偏好(如存在): data/technical-preferences.yaml
+```
+
+### 5.2 需求分析维度
+
+```yaml
+分析维度:
+  功能分析:
+    - 核心功能拆解
+    - 功能优先级排序
+    - 功能依赖关系
+
+  用户分析:
+    - 用户角色定义
+    - 用户旅程映射
+    - 用户价值主张
+
+  技术分析:
+    - 技术可行性评估
+    - 与现有系统的兼容性
+    - 技术风险识别
+
+  业务分析:
+    - 业务规则验证
+    - 业务流程优化机会
+    - 业务价值量化
+
+  差距分析:
+    - 现有能力 vs 需求能力
+    - 需要新增/修改的功能
+    - 需要新增/修改的数据
+```
+
+### 5.3 PRD生成流程
+
+```yaml
+PRD生成:
+  步骤1:
+    动作: 整合所有知识输入
+    输出: 知识上下文汇总
+
+  步骤2:
+    动作: 执行需求分析(5.2维度)
+    输出: 需求分析报告
+
+  步骤3:
+    动作: 套用PRD模板(prd-tmpl.yaml)
+    输出: PRD草稿
+
+  步骤4:
+    动作: 启发式验证(advanced-elicitation)
+    输出: 优化后的PRD
+
+  步骤5:
+    动作: 输出最终PRD到指定位置
+    输出: docs/prd.md
+```
+
+---
+
+## 使用说明
+
+### 智能体激活命令
+
+```
+*analyze-requirement {req_file}
+```
+
+### 执行参数
+
+```yaml
+参数:
+  req_file: 需求文档路径 (默认: req.txt)
+  rag_output: 知识输出路径 (默认: docs/rag/)
+  prd_output: PRD输出路径 (默认: docs/prd.md)
+  skip_rag: 跳过知识库查询 (默认: false)
+  interactive: 交互模式 (默认: true)
+```
+
+### 交互模式流程
+
+1. **解析阶段**: 展示需求解析结果，请用户确认
+2. **提问阶段**: 展示问题清单，请用户确认或调整
+3. **查询阶段**: 依次查询知识库，展示返回结果
+4. **分析阶段**: 展示分析结论，请用户确认
+5. **生成阶段**: 生成PRD草稿，启用启发式优化

package/xiaoma-core/tasks/requirements-coverage-audit.md

@@ -11,7 +11,7 @@
 ### 📋 需求转化检查
 
 - PRD文档需求是否完全转化为用户故事
-- 史诗级需求的用户故事覆盖度分析
+- 模块级需求的用户故事覆盖度分析
 - 需求优先级和实施状态匹配度验证
 
 ### ✅ 用户故事完整性检查
@@ -36,10 +36,10 @@
 *requirements-coverage-audit
 ```
 
-### 专注特定史诗的审计
+### 专注特定模块的审计
 
 ```bash
-*coverage-audit --epic=史诗-1基础设施与核心文档展示
+*coverage-audit --epic=模块-1基础设施与核心文档展示
 ```
 
 ### 验证用户故事状态准确性
@@ -54,12 +54,12 @@
 
 1. **加载PRD文档**
    - 读取主PRD文档
-   - 扫描docs/prd/目录下的史诗文件
+   - 扫描docs/prd/目录下的模块文件
    - 提取所有需求和用户故事定义
    - 构建需求层次结构
 
 2. **提取需求矩阵**
-   - 识别所有史诗和用户故事
+   - 识别所有模块和用户故事
    - 提取验收标准和功能点
    - 分析需求优先级
    - 构建需求依赖关系

package/xiaoma-core/templates/fullstack-architecture-tmpl.yaml

@@ -340,7 +340,7 @@ sections:
       1. 如果是 REST API, 创建一个 OpenAPI 3.0 规范
       2. 如果是 GraphQL, 提供 GraphQL 模式
       3. 如果是 tRPC, 展示路由定义
-      4. 包括来自史诗/故事的所有端点
+      4. 包括来自模块/故事的所有端点
       5. 基于数据模型定义请求/响应模式
       6. 记录认证要求
       7. 包括请求/响应示例

package/xiaoma-core/templates/prd-tmpl.yaml

@@ -73,7 +73,7 @@ sections:
         title: 关键交互范式
       - id: core-screens
         title: 核心屏幕与视图
-        instruction: 从产品角度看，为实现 PRD 的价值和目标，最关键的屏幕或视图是什么？这旨在提供概念性的高层概览，以驱动粗略的史诗或用户故事。
+        instruction: 从产品角度看，为实现 PRD 的价值和目标，最关键的屏幕或视图是什么？这旨在提供概念性的高层概览，以驱动粗略的模块或用户故事。
         examples:
           - "登录屏幕"
           - "主仪表盘"
@@ -123,38 +123,38 @@ sections:
         instruction: 在起草本文档的整个过程中，如果提出或发现任何其他适合架构师的技术假设，请在此处作为额外的项目符号添加。
 
   - id: epic-list
-    title: 史诗列表
+    title: 模块列表
     instruction: |
-      向用户呈现一份高层次的史诗列表以供批准。每个史诗应有一个标题和一个简短的（1句话）目标陈述。这使用户能在深入细节之前审阅整体结构。
+      向用户呈现一份高层次的模块列表以供批准。每个模块应有一个标题和一个简短的（1句话）目标陈述。这使用户能在深入细节之前审阅整体结构。
 
-      关键：史诗必须遵循敏捷最佳实践，保持逻辑上的顺序：
+      关键：模块必须遵循敏捷最佳实践，保持逻辑上的顺序：
 
-      - 每个史诗都应交付一个重要的、端到端的、完全可部署且可测试的功能增量。
-      - 史诗 1 必须建立基础项目设施（应用设置、Git、CI/CD、核心服务），除非我们是向现有应用添加新功能。同时，它还应交付一个初始功能，即使只是一个健康检查路由或一个简单的金丝雀页面显示——在为第一个史诗编写用户故事时要记住这一点！
-      - 每个后续的史诗都在之前史诗功能的基础上构建，交付主要的功能模块，这些模块在部署时能为用户或业务提供切实的价值。
-      - 并非每个项目都需要多个史诗，一个史诗需要交付价值。例如，一个已完成的 API 即使 UI 尚未完成并计划在另一个史诗中实现，也可以交付价值。
-      - 倾向于设置较少的史诗，但要告知用户你的理由，并提供拆分选项，如果某些史诗看起来太大或关注点分散的话。
-      - 横切关注点应该贯穿于史诗和用户故事中，而不是作为最后的用户故事。例如，在一个史诗的最后一个故事中添加日志框架，或者在项目结束时作为最后一个史诗或故事来做，这将非常糟糕，因为我们从一开始就没有日志记录。
+      - 每个模块都应交付一个重要的、端到端的、完全可部署且可测试的功能增量。
+      - 模块 1 必须建立基础项目设施（应用设置、Git、CI/CD、核心服务），除非我们是向现有应用添加新功能。同时，它还应交付一个初始功能，即使只是一个健康检查路由或一个简单的金丝雀页面显示——在为第一个模块编写用户故事时要记住这一点！
+      - 每个后续的模块都在之前模块功能的基础上构建，交付主要的功能模块，这些模块在部署时能为用户或业务提供切实的价值。
+      - 并非每个项目都需要多个模块，一个模块需要交付价值。例如，一个已完成的 API 即使 UI 尚未完成并计划在另一个模块中实现，也可以交付价值。
+      - 倾向于设置较少的模块，但要告知用户你的理由，并提供拆分选项，如果某些模块看起来太大或关注点分散的话。
+      - 横切关注点应该贯穿于模块和用户故事中，而不是作为最后的用户故事。例如，在一个模块的最后一个故事中添加日志框架，或者在项目结束时作为最后一个模块或故事来做，这将非常糟糕，因为我们从一开始就没有日志记录。
     elicit: true
     examples:
-      - "史诗 1：基础与核心设施：建立项目设置、认证和基本用户管理"
-      - "史诗 2：核心业务实体：创建和管理主要领域对象的 CRUD 操作"
-      - "史诗 3：用户工作流与交互：实现关键用户旅程和业务流程"
-      - "史诗 4：报告与分析：为用户提供洞察和数据可视化"
+      - "模块 1：基础与核心设施：建立项目设置、认证和基本用户管理"
+      - "模块 2：核心业务实体：创建和管理主要领域对象的 CRUD 操作"
+      - "模块 3：用户工作流与交互：实现关键用户旅程和业务流程"
+      - "模块 4：报告与分析：为用户提供洞察和数据可视化"
 
   - id: epic-details
-    title: 史诗 {{epic_number}} {{epic_title}}
+    title: 模块 {{epic_number}} {{epic_title}}
     repeatable: true
     instruction: |
-      在史诗列表被批准后，将每个史诗及其所有的用户故事和验收标准作为一个完整的审查单元呈现。
+      在模块列表被批准后，将每个模块及其所有的用户故事和验收标准作为一个完整的审查单元呈现。
 
-      为每个史诗提供扩展的目标（2-3 句话描述所有故事将实现的目标和价值）。
+      为每个模块提供扩展的目标（2-3 句话描述所有故事将实现的目标和价值）。
 
       关键的用户故事排序要求：
 
-      - 每个史诗中的用户故事必须在逻辑上是顺序的。
+      - 每个模块中的用户故事必须在逻辑上是顺序的。
       - 每个故事都应该是一个“垂直切片”，交付完整的功能，除了项目基础的早期使能型故事。
-      - 任何故事都不应依赖于后续故事或史诗的工作。
+      - 任何故事都不应依赖于后续故事或模块的工作。
       - 识别并注明任何直接的前置故事。
       - 关注“做什么”和“为什么”，而不是“怎么做”（将技术实现留给架构师），但要足够精确以支持故事之间逻辑上顺序的操作。
       - 确保每个故事都交付明确的用户或业务价值，尽量避免使能型故事，而是将它们构建到交付价值的故事中。