@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/src/modules/xmc/workflows/auto-iteration/knowledge-base/kb-interface.md

@@ -0,0 +1,347 @@
+# 知识库接口层
+
+> 本文档定义知识库的访问接口，支持前期 RAG 文件模式和后期 MCP 服务模式的无缝切换。
+
+---
+
+## 接口配置
+
+### 知识库模式配置
+
+在执行全自动迭代开发前，需要配置知识库模式：
+
+```yaml
+# auto-iteration-config.yaml
+knowledge_base:
+  # 模式: rag | mcp
+  mode: "rag"
+
+  # RAG 模式配置（前期）
+  rag:
+    file_path: "{project-root}/docs/rag/rag.md"
+    search_strategy: "keyword_match"  # keyword_match | semantic
+
+  # MCP 模式配置（后期）
+  mcp:
+    server: "knowledge-base-mcp"
+    endpoint: "mcp__kb__query"
+    timeout: 30000
+```
+
+---
+
+## RAG 文件模式（前期实现）
+
+### 数据源
+
+**文件路径**: `{project-root}/docs/rag/rag.md`
+
+### 文件结构要求
+
+RAG 文件必须按以下结构组织，以支持关键词匹配检索：
+
+```markdown
+# 知识库 - RAG 文档
+
+## 业务知识
+
+### 业务术语
+<!-- KB-TYPE: business_term -->
+<!-- KB-KEYWORDS: 术语名1, 术语名2 -->
+
+#### 术语: {术语名}
+**定义**: ...
+**使用场景**: ...
+**相关规则**: ...
+
+### 业务规则
+<!-- KB-TYPE: business_rule -->
+<!-- KB-KEYWORDS: 关键词1, 关键词2 -->
+
+#### 规则: BR-001 {规则名称}
+**描述**: ...
+**适用场景**: ...
+**规则逻辑**: ...
+
+### 业务流程
+<!-- KB-TYPE: business_process -->
+<!-- KB-KEYWORDS: 流程名1, 流程名2 -->
+
+#### 流程: {流程名}
+**步骤**: ...
+**前置条件**: ...
+**输出**: ...
+
+---
+
+## 技术知识
+
+### 技术栈规范
+<!-- KB-TYPE: tech_spec -->
+<!-- KB-KEYWORDS: 前端, 后端, 数据库 -->
+
+### 编码规范
+<!-- KB-TYPE: coding_standard -->
+<!-- KB-KEYWORDS: 命名, 格式, 注释 -->
+
+### 架构模式
+<!-- KB-TYPE: architecture_pattern -->
+<!-- KB-KEYWORDS: MVC, Repository, Service -->
+
+### API 规范
+<!-- KB-TYPE: api_spec -->
+<!-- KB-KEYWORDS: RESTful, 响应格式, 错误码 -->
+
+### 测试规范
+<!-- KB-TYPE: testing_standard -->
+<!-- KB-KEYWORDS: 单元测试, 集成测试, 覆盖率 -->
+```
+
+### RAG 查询执行流程
+
+```yaml
+rag_query_flow:
+  step_1_load_file:
+    action: "读取 docs/rag/rag.md 文件内容"
+
+  step_2_extract_keywords:
+    action: "从查询问题中提取关键词"
+    example:
+      query: "请查询用户认证相关的业务规则"
+      keywords: ["用户", "认证", "业务规则"]
+
+  step_3_match_sections:
+    action: "在 RAG 文件中查找匹配的章节"
+    logic: |
+      1. 查找包含 KB-KEYWORDS 匹配的章节
+      2. 查找标题或内容包含关键词的章节
+      3. 按匹配度排序
+
+  step_4_extract_content:
+    action: "提取匹配章节的完整内容"
+
+  step_5_format_response:
+    action: "格式化为标准响应格式"
+```
+
+### RAG 查询指令
+
+在工作流中，使用以下格式调用 RAG 查询：
+
+```markdown
+## 知识库查询
+
+**调用点**: KBC-1.2 (业务规则验证)
+
+**查询问题**:
+```
+请查询与以下功能相关的业务规则：
+- 功能描述: 用户偏好设置
+- 涉及实体: User, UserPreference
+- 业务场景: 用户修改个人偏好
+```
+
+**执行动作**:
+1. 读取 `{project-root}/docs/rag/rag.md`
+2. 提取关键词: ["用户", "偏好", "设置", "业务规则"]
+3. 在文件中搜索匹配内容
+4. 返回匹配结果
+
+**查询结果**:
+[从 RAG 文件中提取的相关内容]
+
+**来源**: docs/rag/rag.md#业务规则-用户偏好
+**匹配度**: 高/中/低
+```
+
+---
+
+## MCP 服务模式（后期实现）
+
+### MCP 服务调用格式
+
+当 MCP 知识库服务上线后，查询将通过 MCP 调用：
+
+```yaml
+mcp_call:
+  service: "knowledge-base-mcp"
+  method: "query"
+  parameters:
+    question: "{查询问题}"
+    context:
+      phase: "{当前阶段}"
+      call_point: "{调用点 ID}"
+      keywords: ["{关键词列表}"]
+    options:
+      knowledge_type: "business" | "technical" | "all"
+      max_results: 5
+      include_related: true
+```
+
+### MCP 响应格式
+
+```yaml
+mcp_response:
+  success: true
+  data:
+    answer: "知识库返回的答案内容"
+    sources:
+      - document: "业务规则文档"
+        section: "用户偏好规则"
+        confidence: 0.95
+        content: "具体内容..."
+    related_topics:
+      - topic: "用户权限管理"
+        relevance: 0.8
+    suggestions:
+      - "可能还需要查询用户权限规则"
+  metadata:
+    query_time: "120ms"
+    knowledge_version: "2024-01-15"
+```
+
+### MCP 查询指令
+
+```markdown
+## 知识库查询 (MCP)
+
+**调用点**: KBC-1.2 (业务规则验证)
+
+**MCP 调用**:
+```
+mcp__kb__query({
+  question: "请查询与用户偏好设置相关的业务规则",
+  context: {
+    phase: "phase_1_analyze",
+    call_point: "KBC-1.2",
+    keywords: ["用户", "偏好", "设置"]
+  },
+  options: {
+    knowledge_type: "business",
+    max_results: 5
+  }
+})
+```
+
+**等待 MCP 响应...**
+
+**响应结果**:
+[MCP 服务返回的结果]
+```
+
+---
+
+## 统一查询接口
+
+无论使用 RAG 模式还是 MCP 模式，工作流中的查询接口保持一致：
+
+### 查询请求格式
+
+```yaml
+kb_query_request:
+  call_point: "KBC-X.X"           # 调用点 ID
+  question: "查询问题"             # 完整的查询问题
+  context:
+    phase: "phase_X"              # 当前阶段
+    task: "当前任务"
+    related_content: "相关上下文"
+  knowledge_type: "business|technical|all"
+  required: true|false            # 是否必须找到答案
+```
+
+### 查询响应格式
+
+```yaml
+kb_query_response:
+  status: "found|not_found|partial"
+  answer: "答案内容"
+  sources:
+    - source: "来源文档/章节"
+      confidence: "high|medium|low"
+  fallback_used: true|false       # 是否使用了回退策略
+  decision_basis: "决策依据说明"
+```
+
+---
+
+## 回退策略
+
+当知识库查询未找到匹配内容时，按以下策略处理：
+
+```yaml
+fallback_strategy:
+  level_1_expand_search:
+    description: "扩大搜索范围"
+    actions:
+      - 使用同义词搜索
+      - 扩大关键词范围
+      - 搜索相关主题
+
+  level_2_infer:
+    description: "基于上下文推断"
+    actions:
+      - 从相似知识推断
+      - 从通用最佳实践推断
+      - 标记为"推断结果"
+
+  level_3_default:
+    description: "使用默认值"
+    actions:
+      - 使用行业标准默认值
+      - 使用保守的实现方式
+      - 标记为"待确认"
+
+  level_4_flag:
+    description: "标记为需人工确认"
+    condition: "required = true 且前三级都未解决"
+    actions:
+      - 记录详细的查询信息
+      - 继续执行其他任务
+      - 在最终报告中列出待确认项
+```
+
+---
+
+## 查询日志
+
+所有知识库查询都会记录到执行日志：
+
+```yaml
+kb_query_log:
+  - id: "Q-001"
+    timestamp: "2024-01-15T10:15:30Z"
+    call_point: "KBC-1.2"
+    phase: "phase_1_analyze"
+    question: "查询问题..."
+    keywords: ["关键词1", "关键词2"]
+    mode: "rag"  # rag | mcp
+    result:
+      status: "found"
+      sources: ["docs/rag/rag.md#section"]
+      confidence: "high"
+    decision: "基于查询结果，决定..."
+    duration_ms: 150
+```
+
+---
+
+## 模式切换
+
+从 RAG 模式切换到 MCP 模式只需修改配置：
+
+```yaml
+# 切换前 (RAG 模式)
+knowledge_base:
+  mode: "rag"
+  rag:
+    file_path: "{project-root}/docs/rag/rag.md"
+
+# 切换后 (MCP 模式)
+knowledge_base:
+  mode: "mcp"
+  mcp:
+    server: "knowledge-base-mcp"
+    endpoint: "mcp__kb__query"
+```
+
+工作流代码无需修改，查询接口自动适配。

package/src/modules/xmc/workflows/auto-iteration/knowledge-base/kb-query.md

@@ -0,0 +1,368 @@
+# 知识库查询工作流
+
+> **工作流 ID**: kb-query
+> **触发命令**: `*kb-query`
+> **智能体**: Phoenix (全自动化迭代开发编排器)
+
+---
+
+## 查询机制
+
+知识库查询是全自动迭代开发的核心能力，用于在执行过程中自动获取业务规则和技术规范。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     知识库查询流程                           │
+├─────────────────────────────────────────────────────────────┤
+│  1. 接收查询请求                                             │
+│     └─ 查询关键词 / 查询问题 / 查询上下文                     │
+├─────────────────────────────────────────────────────────────┤
+│  2. 关键词提取                                               │
+│     └─ 从查询中提取核心关键词                                │
+├─────────────────────────────────────────────────────────────┤
+│  3. 索引匹配                                                 │
+│     ├─ 在 kb-index.yaml 中查找匹配文档                       │
+│     └─ 按相关度排序                                         │
+├─────────────────────────────────────────────────────────────┤
+│  4. 文档读取                                                 │
+│     └─ 读取匹配文档的相关内容                                │
+├─────────────────────────────────────────────────────────────┤
+│  5. 答案提取                                                 │
+│     ├─ 从文档中提取与查询相关的答案                          │
+│     └─ 格式化为结构化输出                                    │
+├─────────────────────────────────────────────────────────────┤
+│  6. 返回结果                                                 │
+│     ├─ 找到: 返回答案 + 来源引用                             │
+│     └─ 未找到: 返回推断答案 + 标记为推断                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 查询类型
+
+### 1. 业务规则查询
+
+```yaml
+query_type: business_rule
+example_queries:
+  - "用户注册需要满足什么条件？"
+  - "订单取消的业务规则是什么？"
+  - "VIP 用户有哪些特权？"
+
+response_format:
+  rule_id: "BR-001"
+  rule_name: "用户注册规则"
+  rule_content: |
+    1. 邮箱必须唯一
+    2. 密码长度至少 8 位
+    3. 必须同意服务条款
+  source: "business-rules/user-management.md"
+  confidence: "high"  # high | medium | low | inferred
+```
+
+### 2. 技术规范查询
+
+```yaml
+query_type: technical_spec
+example_queries:
+  - "API 响应格式规范是什么？"
+  - "数据库字段命名规范？"
+  - "错误处理应该怎么做？"
+
+response_format:
+  spec_id: "TS-001"
+  spec_name: "API 响应格式规范"
+  spec_content: |
+    所有 API 响应必须包含：
+    - code: 状态码
+    - message: 消息
+    - data: 数据
+  code_example: |
+    {
+      "code": 200,
+      "message": "success",
+      "data": {}
+    }
+  source: "api-specs/response-format.md"
+  confidence: "high"
+```
+
+### 3. 架构模式查询
+
+```yaml
+query_type: architecture_pattern
+example_queries:
+  - "数据访问层应该使用什么模式？"
+  - "服务层的设计原则？"
+  - "前端状态管理方案？"
+
+response_format:
+  pattern_name: "Repository Pattern"
+  description: "将数据访问逻辑封装在仓储类中"
+  implementation_guide: |
+    1. 定义仓储接口
+    2. 实现具体仓储类
+    3. 通过依赖注入使用
+  code_example: |
+    interface UserRepository {
+      findById(id: string): User;
+      save(user: User): void;
+    }
+  source: "architecture-patterns/repository-pattern.md"
+  confidence: "high"
+```
+
+### 4. 代码规范查询
+
+```yaml
+query_type: coding_standard
+example_queries:
+  - "变量命名规范？"
+  - "函数长度限制？"
+  - "注释规范？"
+
+response_format:
+  standard_name: "命名规范"
+  rules:
+    - "变量使用 camelCase"
+    - "常量使用 UPPER_SNAKE_CASE"
+    - "类名使用 PascalCase"
+  examples:
+    correct: "const userName = 'John';"
+    incorrect: "const user_name = 'John';"
+  source: "coding-standards/naming-conventions.md"
+  confidence: "high"
+```
+
+---
+
+## 自动查询触发
+
+在全自动迭代开发过程中，以下场景会自动触发知识库查询：
+
+### Phase 1 - 需求分析
+
+```yaml
+auto_queries:
+  - trigger: "解析到业务术语"
+    query: "查询术语定义"
+    kb_type: "business"
+
+  - trigger: "识别到业务流程"
+    query: "查询业务流程规则"
+    kb_type: "business"
+
+  - trigger: "发现潜在约束"
+    query: "查询相关业务规则"
+    kb_type: "business"
+```
+
+### Phase 2 - 需求规划
+
+```yaml
+auto_queries:
+  - trigger: "定义功能需求"
+    query: "查询相关业务规则验证需求合理性"
+    kb_type: "business"
+
+  - trigger: "定义非功能需求"
+    query: "查询技术规范确定 NFR 标准"
+    kb_type: "technical"
+```
+
+### Phase 3 - 架构设计
+
+```yaml
+auto_queries:
+  - trigger: "选择技术方案"
+    query: "查询推荐的架构模式"
+    kb_type: "technical"
+
+  - trigger: "设计数据模型"
+    query: "查询数据建模规范"
+    kb_type: "technical"
+
+  - trigger: "设计 API"
+    query: "查询 API 设计规范"
+    kb_type: "technical"
+```
+
+### Phase 4 - 开发实现
+
+```yaml
+auto_queries:
+  - trigger: "编写代码"
+    query: "查询代码规范"
+    kb_type: "technical"
+
+  - trigger: "实现业务逻辑"
+    query: "查询业务规则确保实现正确"
+    kb_type: "business"
+
+  - trigger: "编写测试"
+    query: "查询测试规范"
+    kb_type: "technical"
+```
+
+---
+
+## 查询结果处理
+
+### 找到匹配结果
+
+```yaml
+result_found:
+  action: "使用知识库内容作为决策依据"
+  output:
+    answer: "[从知识库提取的答案]"
+    source: "[来源文档路径]"
+    confidence: "high"
+    decision_record: |
+      决策: [具体决策]
+      依据: [知识库来源]
+      时间: [时间戳]
+```
+
+### 部分匹配结果
+
+```yaml
+partial_match:
+  action: "使用匹配内容 + 推断补充"
+  output:
+    answer: "[部分匹配内容 + 推断内容]"
+    source: "[来源文档路径]"
+    inferred_parts: "[推断的部分]"
+    confidence: "medium"
+    decision_record: |
+      决策: [具体决策]
+      依据: [知识库来源] + [推断逻辑]
+      时间: [时间戳]
+```
+
+### 未找到匹配
+
+```yaml
+no_match:
+  action: "使用推断或默认值"
+  output:
+    answer: "[基于上下文推断的答案]"
+    inference_basis: "[推断依据]"
+    confidence: "low"
+    flag: "需要后续验证"
+    decision_record: |
+      决策: [具体决策]
+      依据: 推断 - [推断逻辑]
+      标记: 需人工确认
+      时间: [时间戳]
+```
+
+---
+
+## 手动查询使用
+
+当用户执行 `*kb-query` 时：
+
+```markdown
+## 知识库查询
+
+请输入你的查询：
+
+**查询类型**（可选）:
+- `business` - 业务知识库
+- `technical` - 技术知识库
+- `all` - 全部（默认）
+
+**查询内容**:
+[在此输入你的问题或关键词]
+
+---
+
+### 查询结果
+
+**查询**: [用户输入的查询]
+**类型**: [查询类型]
+
+**结果**:
+
+| 来源 | 相关度 | 内容摘要 |
+|-----|-------|---------|
+| [文档路径] | 高 | [内容摘要] |
+
+**详细内容**:
+
+[从知识库提取的详细内容]
+
+**知识库引用**:
+- 来源: [文档路径]
+- 章节: [章节名称]
+- 置信度: [高/中/低]
+```
+
+---
+
+## 查询优化策略
+
+### 1. 关键词扩展
+
+```yaml
+keyword_expansion:
+  original: "用户登录"
+  expanded:
+    - "用户登录"
+    - "用户认证"
+    - "身份验证"
+    - "登录流程"
+    - "认证机制"
+```
+
+### 2. 上下文关联
+
+```yaml
+context_association:
+  current_phase: "架构设计"
+  current_task: "API 设计"
+  related_queries:
+    - "API 设计规范"
+    - "RESTful 最佳实践"
+    - "接口安全规范"
+```
+
+### 3. 历史查询学习
+
+```yaml
+query_history:
+  - query: "用户认证方式"
+    result: "found"
+    source: "tech-stack/auth.md"
+    useful: true
+
+  - query: "JWT 最佳实践"
+    result: "not_found"
+    fallback: "使用默认 JWT 配置"
+    note: "建议添加到知识库"
+```
+
+---
+
+## 知识库维护建议
+
+执行过程中会自动记录以下建议：
+
+```yaml
+kb_maintenance_suggestions:
+  new_entries:
+    - topic: "微服务通信模式"
+      reason: "多次查询未找到匹配"
+      suggested_content: "[推断的内容]"
+
+  updates:
+    - document: "api-specs/response-format.md"
+      reason: "规范已过时"
+      suggested_change: "[建议的更新]"
+
+  missing_coverage:
+    - area: "性能优化规范"
+      frequency: 5
+      priority: "high"
+```