@chongyan/autospec 1.0.1

package/knowledge/guides/knowledge-management.md

@@ -0,0 +1,369 @@
+# 知识管理指南
+
+> **版本**: v1.0
+> **最后更新**: 2026-03-26
+> **基于**: 业界知识库 / 插件市场知识管理体系
+> **适用范围**: 所有知识库建设和维护场景
+
+---
+
+## 目标
+
+建立分层、易用、可演进的知识库体系，支撑 AI 驱动的研发流程。
+
+---
+
+## 知识分层架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Layer 1: Metadata（元数据层）                              │
+│  · skill description（触发条件）                           │
+│  · 知识库导航（README/SUMMARY）                            │
+│  · 快速索引（标签、分类）                                  │
+│  用途：快速定位，决定是否加载                               │
+├─────────────────────────────────────────────────────────┤
+│  Layer 2: SKILL.md（核心逻辑层）                           │
+│  · 执行步骤（Steps）                                      │
+│  · 输入输出（Guardrails）                                 │
+│  · 检查清单（Checklist）                                  │
+│  用途：指导 AI 执行具体任务                                 │
+├─────────────────────────────────────────────────────────┤
+│  Layer 3: References（参考文档层）                         │
+│  · 详细规范（coding-style.md 等）                         │
+│  · 最佳实践（best-practices/）                            │
+│  · 示例代码（examples/）                                  │
+│  用途：按需加载，提供详细参考                              │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 各层设计原则
+
+**Layer 1: Metadata**
+- 简洁明了，一句话说清"什么时候用"
+- 不包含工作流细节（避免 AI 直接按 description 执行）
+- 创造信息差，迫使 AI 加载完整正文
+
+**Layer 2: SKILL.md**
+- 结构化步骤（Step 1, Step 2, ...）
+- 明确的输入输出（Guardrails）
+- 嵌入式检查清单（Post-Check）
+- 检查点机制（BLOCKING CHECKPOINT）
+
+**Layer 3: References**
+- 详细的规范文档
+- 丰富的示例代码
+- 最佳实践总结
+- 可按需加载，不强制全读
+
+---
+
+## 业务文档写作规范
+
+### 定位
+
+业务文档（`knowledge/domain/`）描述"业务是什么"，不描述"技术怎么实现"。
+
+### 内容范围
+
+**应该写**:
+- 业务流程（用户视角的流转）
+- 业务规则（准入、限制、计算规则）
+- 业务术语（定义、解释）
+- 业务场景（用例、场景描述）
+
+**不应该写**:
+- 技术实现细节（类、方法、算法）
+- 数据库设计（表结构、索引）
+- 接口定义（API、参数）
+- 架构设计（分层、模块）
+
+### 示例对比
+
+**错误示例**（混入技术实现）:
+```markdown
+# 产品购买流程
+
+1. 用户调用 `/api/product/purchase`接口
+2. 系统创建 PurchaseOrder 对象
+3. 调用 ProductService.createOrder() 方法
+4. 写入 purchase_order 表
+```
+
+**正确示例**（纯业务视角）:
+```markdown
+# 产品购买流程
+
+1. 用户提交购买申请（填写金额、选择产品）
+2. 系统校验购买资格（账户状态、风险评估、限额）
+3. 冻结用户资金（购买金额 + 手续费）
+4. 确认份额（T+1 日，按确认日价值）
+5. 份额登记（登记到用户账户）
+```
+
+---
+
+## 技术文档写作规范
+
+### 定位
+
+技术文档（`knowledge/system/`）描述"技术怎么实现"，指导开发和运维。
+
+### 标准文件结构
+
+```markdown
+# {系统名称}
+
+## 1. Overview（概述）
+- 系统定位
+- 核心职责
+- 技术栈
+
+## 2. Model（模型）
+- 领域模型
+- 数据模型
+- 状态机
+
+## 3. Process（流程）
+- 核心业务流程
+- 关键时序图
+
+## 4. Design（设计）
+- 架构设计
+- 模块划分
+- 接口定义
+```
+
+### 各章节编写指南
+
+**1. Overview**
+- 一句话描述系统定位
+- 列出核心职责（3-5 条）
+- 技术栈清单（框架、中间件、语言）
+
+**2. Model**
+- 领域模型图（Mermaid classDiagram）
+- 数据模型图（Mermaid erDiagram）
+- 状态流转图（Mermaid stateDiagram）
+
+**3. Process**
+- 核心业务流程图（Mermaid flowchart）
+- 关键时序图（Mermaid sequenceDiagram）
+- 异常流程说明
+
+**4. Design**
+- 系统架构图（分层、模块关系）
+- 模块职责说明
+- 对外接口清单
+
+---
+
+## 术语管理
+
+### 原则
+
+**不独立维护 glossary**，术语解释在正文中首次出现时括号说明。
+
+### 示例
+
+```markdown
+# 产品转换流程
+
+产品转换是指投资者将其持有的某个产品（转出产品）转换为同一机构旗下的另一个产品（转入产品）的行为。
+
+转换流程：
+1. 投资者提交转换申请
+2. 系统计算转出产品的可转换份额
+3. 按转换日价值计算转入产品份额
+4. 份额变更登记
+```
+
+### 术语使用规则
+
+1. **首次出现**: 括号解释（如：产品转换（将持有的产品 A 转换为产品 B））
+2. **后续出现**: 直接使用术语，不再解释
+3. **一词多义**: 明确标注不同含义的使用场景
+
+---
+
+## 共用规则管理
+
+### 原则
+
+通用规则在父级文档，差异文件仅记录不同点。
+
+### 示例结构
+
+```
+knowledge/domain/product/
+├── README.md              # 产品业务通用规则
+├── purchase.md            # 购买特有规则
+├── redeem.md              # 赎回特有规则
+└── transfer.md            # 转换特有规则
+```
+
+### purchase.md 示例
+
+```markdown
+# 产品购买
+
+## 通用规则
+
+参考 [产品业务通用规则](README.md)
+
+## 特有规则
+
+### 购买限额
+
+| 渠道 | 单笔限额 | 单日限额 | 单月限额 |
+|------|---------|---------|---------|
+| 直销 | 100 万 | 500 万 | 2000 万 |
+| 代销 | 50 万 | 200 万 | 1000 万 |
+
+### 购买费率
+
+| 金额区间 | 费率 |
+|---------|------|
+| <100 万 | 1.5% |
+| 100-500 万 | 1.0% |
+| ≥500 万 | 1000 元/笔 |
+```
+
+---
+
+## 知识库导航设计
+
+### SUMMARY.md 结构
+
+```markdown
+# 知识库导航
+
+## 业务知识 (domain/)
+* [产品业务](domain/product/README.md)
+  * [购买流程](domain/product/purchase.md)
+  * [赎回流程](domain/product/redeem.md)
+  * [转换流程](domain/product/transfer.md)
+* [支付业务](domain/payment/README.md)
+
+## 系统文档 (system/)
+* [交易系统](system/trade/README.md)
+* [账户系统](system/account/README.md)
+
+## API 文档 (api/)
+* [交易接口](api/trade/README.md)
+* [账户接口](api/account/README.md)
+
+## 数据文档 (data/)
+* [表结构](data/schema/README.md)
+* [数据字典](data/dictionary/README.md)
+```
+
+### 导航设计原则
+
+1. **层次清晰**: 按业务域/系统/类型分层
+2. **命名一致**: 同级目录命名风格一致
+3. **链接有效**: 所有链接可正常跳转
+4. **及时更新**: 新增文档及时更新导航
+
+---
+
+## AI Skills 自动生成
+
+### 从知识库到 Skill
+
+AI Skills 可从知识库文档自动生成：
+
+```
+知识库文档 → Skill 提取器 → SKILL.md
+```
+
+### Skill 模板结构
+
+```markdown
+---
+name: domain-{业务域}
+description: {业务域} 领域知识，当用户提到 {关键词} 时加载
+---
+
+# {业务域} 领域知识
+
+## 业务规则
+
+{从知识库提取的业务规则}
+
+## 术语定义
+
+{从知识库提取的术语}
+
+## 典型场景
+
+{从知识库提取的典型场景}
+```
+
+---
+
+## 知识维护流程
+
+### 新增知识
+
+1. **识别类型**: 业务文档/技术文档/API 文档
+2. **选择位置**: 按目录结构存放
+3. **编写内容**: 遵循对应规范
+4. **更新导航**: 更新 SUMMARY.md
+5. **注册 Skill**: 如需要，创建对应的 SKILL.md
+
+### 更新知识
+
+1. **变更识别**: 从代码/流程变更识别知识变更
+2. **影响分析**: 分析受影响的文档
+3. **更新文档**: 更新相关内容
+4. **版本记录**: 记录变更内容和日期
+
+### 废弃知识
+
+1. **标记废弃**: 在文档顶部添加`> ⚠️ 已废弃`
+2. **指向替代**: 说明替代文档
+3. **保留历史**: 不删除，保留历史记录
+
+---
+
+## 知识质量检查
+
+### 完整性检查
+
+- [ ] 业务文档覆盖所有业务域
+- [ ] 技术文档覆盖所有系统
+- [ ] API 文档覆盖所有接口
+- [ ] 导航链接全部有效
+
+### 一致性检查
+
+- [ ] 业务文档与技术文档一致
+- [ ] 术语定义一致（同一概念不同文档中名称一致）
+- [ ] 流程图与实际流程一致
+
+### 时效性检查
+
+- [ ] 文档更新日期在 1 年内
+- [ ] 废弃文档已标记
+- [ ] 过时内容已更新
+
+---
+
+## 最佳实践
+
+1. **分层加载**: 按 Layer 1→Layer 2→Layer 3 渐进式加载
+2. **业务技术分离**: 业务文档不写技术实现，技术文档不写业务背景
+3. **术语管理**: 首次出现时解释，不独立维护 glossary
+4. **共用规则**: 通用规则在父级，差异仅记录不同点
+5. **导航清晰**: SUMMARY.md 层次清晰，链接有效
+6. **及时更新**: 变更代码同时更新文档
+7. **AI 友好**: Skills 结构化，便于 AI 理解和执行
+
+---
+
+## 参考资料
+
+- [template-registry](../environment/template-registry.md)
+- [design-philosophy - 渐进式披露](../principles/design-philosophy.md#核心设计模式)
+- [design-philosophy - 上下文精确管理](../principles/design-philosophy.md#dp4-上下文精确管理)

package/knowledge/guides/requirement-engineering.md

@@ -0,0 +1,329 @@
+# 需求工程指南
+
+> **版本**: v1.0
+> **最后更新**: 2026-03-26
+> **基于**: 业界需求工程最佳实践 / 结构化需求分析方法
+> **适用范围**: 所有需求分析场景
+
+---
+
+## 目标
+
+将原始需求转化为结构化、无歧义、可实现的需求文档（proposal.md）。
+
+---
+
+## 8 类场景检查清单识别业务域
+
+在需求分析开始时，通过 8 类场景检查清单识别涉及的业务域：
+
+| 场景类型 | 检查问题 | 涉及业务域 |
+|---------|---------|-----------|
+| 外部对接 | 是否涉及外部系统、第三方服务对接？ | gateway（网关系统） |
+| 账户体系 | 是否涉及用户账户、资金账户、账务处理？ | account（账户系统） |
+| 交易链路 | 是否涉及下单、支付、确认、结算？ | trade（交易系统） |
+| 资产/资源管理 | 是否涉及资产计算、估值、登记？ | asset（资产/资源系统） |
+| 数据管道 | 是否涉及数据采集、清洗、流转、报表？ | data（数据系统） |
+| AI/模型 | 是否涉及模型训练、推理、效果评估？ | ai/ml（AI 系统） |
+| 运营营销 | 是否涉及活动、营销、用户运营？ | operation（运营系统） |
+| 监控运维 | 是否涉及监控、告警、应急、部署？ | ops（运维系统） |
+
+**使用方法**：
+1. 逐条检查 8 类场景
+2. 标记"涉及"的业务域
+3. 针对每个涉及的业务域，读取对应的领域知识（domain-xxx skill）
+4. 在需求文档中明确标注涉及的业务域
+
+---
+
+## 需求提案 11 章节模板
+
+```markdown
+# Proposal: {需求名称}
+
+## 1. 背景与价值
+### 1.1 业务背景
+### 1.2 业务价值 (Why)
+
+## 2. 目标与范围
+### 2.1 目标 (Success Criteria)
+### 2.2 范围 (包含/不包含)
+
+## 3. 业务架构设计
+### 3.1 总体架构图
+### 3.2 需求用例图
+### 3.3 业务域拆解
+### 3.4 资金流方案 (涉及资金链路时必须)
+### 3.5 用例业务流程
+### 3.6 跨域接口 (概要)
+### 3.7 数据一致性保障
+
+## 4. 关键决策
+
+## 5. 风险与缓解
+
+## 6. 非目标与约束
+### 6.1 非目标
+### 6.2 知识库缺失识别
+
+## 7. Open Questions
+
+## 8. 参考资料
+```
+
+### 各章节编写指南
+
+#### 1. 背景与价值
+
+**1.1 业务背景**：
+- 描述当前面临的问题或机会
+- 用数据说话（当前指标、目标指标）
+- 避免主观描述，用客观事实
+
+**1.2 业务价值**：
+- 为什么要做这个需求
+- 预期的业务价值是什么
+- 与团队/公司目标的对齐关系
+
+#### 2. 目标与范围
+
+**2.1 目标 (Success Criteria)**：
+- 用 SMART 原则定义目标
+- 可衡量的指标（例如：支持 X 场景、性能提升 Y%）
+- 验收的具体标准
+
+**2.2 范围**：
+- **包含**：明确列出本次需求包含的功能
+- **不包含**：明确排除的范围，避免范围蔓延
+
+#### 3. 业务架构设计
+
+**3.1 总体架构图**：
+- 使用 Mermaid flowchart
+- 按功能域分层展示
+- 标注系统边界和外部交互
+
+**3.2 需求用例图**：
+- 使用 Mermaid flowchart
+- 按角色分组
+- 原子粒度用例（不可再拆分）
+
+**3.3 业务域拆解**：
+| 场景类型 | 是否涉及 | 业务域 | 识别依据 |
+|---------|---------|--------|---------|
+| 外部对接 | Y/N | gateway | ... |
+| ... | ... | ... | ... |
+
+**3.4 资金流方案**（涉及资金链路时必须）：
+- 使用 Mermaid flowchart 或 sequence diagram
+- 标注账户间资金流转
+- 标注时间和方向
+
+**3.5 用例业务流程**：
+- 每个用例一个 sequence diagram
+- 从用户视角描述交互流程
+- 标注异常处理分支
+
+**3.6 跨域接口**（概要）：
+| 接口名 | 调用方 | 被调用方 | 协议 | 说明 |
+|-------|--------|---------|------|------|
+
+**3.7 数据一致性保障**：
+- 描述数据一致性方案
+- 分布式事务（2PC/SAGA）
+- 中间态 + 定时任务重试
+- 消息队列（RocketMQ）
+
+#### 4. 关键决策
+
+| 决策点 | 选项 | 决策 | 理由 |
+|-------|------|------|------|
+| {决策 1} | 选项 A/B | {决策} | {理由} |
+
+#### 5. 风险与缓解
+
+| 风险项 | 影响 | 概率 | 缓解措施 |
+|-------|------|------|---------|
+| {风险 1} | 高/中/低 | 高/中/低 | {措施} |
+
+#### 6. 非目标与约束
+
+**6.1 非目标**：
+- 明确说明本次需求不包含的内容
+- 避免后续误解
+
+**6.2 知识库缺失识别**：
+| 缺失项 | 影响 | 补充计划 |
+|-------|------|---------|
+| {缺失 1} | {影响} | {计划} |
+
+#### 7. Open Questions
+
+| 问题 | 提出人 | 日期 | 状态 | 决议 |
+|------|--------|------|------|------|
+| {问题 1} | {人名} | {日期} | Open/Closed | {决议} |
+
+---
+
+## WHEN-THEN 规格描述（Gherkin 风格）
+
+需求描述使用 WHEN-THEN 格式，确保无歧义：
+
+```gherkin
+场景：{场景名称}
+  给定：{前置条件}
+  当：{触发事件}
+  则：{预期结果}
+  而且：{额外预期}
+```
+
+### 示例
+
+```gherkin
+场景：用户购买产品
+  给定：用户账户余额充足
+    而且：当前账户状态正常
+  当：用户发起购买申请 100 元
+  则：创建购买订单，状态为"处理中"
+    而且：用户可用余额减少 100 元
+    而且：发送通知告知用户
+```
+
+### 使用规则
+
+1. **给定**：描述前置条件，必须可验证
+2. **当**：描述触发事件，必须具体
+3. **则**：描述预期结果，必须可测量
+4. **而且**：可多条，补充预期结果
+
+---
+
+## 三板斧发布清单
+
+需求分析阶段必须考虑发布相关的三板斧：
+
+### 灰度策略
+
+| 灰度维度 | 说明 | 本需求适用 |
+|---------|------|-----------|
+| 用户灰度 | 按用户 ID/用户群灰度 | Y/N |
+| 流量灰度 | 按流量百分比分流 | Y/N |
+| 功能灰度 | 按功能开关控制 | Y/N |
+| 数据灰度 | 按数据范围灰度 | Y/N |
+
+### 监控指标
+
+| 指标类型 | 指标名称 | 告警阈值 | 本需求适用 |
+|---------|---------|---------|-----------|
+| 业务指标 | 下单成功率 | <95% | Y/N |
+| 性能指标 | 接口响应时间 | P99>500ms | Y/N |
+| 错误指标 | 错误日志数量 | >10/min | Y/N |
+| 资源指标 | CPU/内存使用率 | >80% | Y/N |
+
+### 应急预案
+
+| 风险项 | 应急操作 | 操作步骤 | 负责人 |
+|-------|---------|---------|--------|
+| 新功能异常 | 功能开关降级 | 1. 关闭开关 2. 验证恢复 | {人名} |
+| 性能问题 | 限流降级 | 1. 开启限流 2. 通知用户 | {人名} |
+| 数据问题 | 数据回滚 | 1. 停止写入 2. 回滚数据 | {人名} |
+
+---
+
+## 需求澄清协议（DP17）
+
+发现需求歧义时，执行有界澄清：
+
+### Step 1: 11 维分类扫描
+
+| 维度 | 检查问题 |
+|------|---------|
+| 功能范围 | 要做什么功能？ |
+| 数据模型 | 涉及哪些数据实体？ |
+| UX 流程 | 用户如何交互？ |
+| 非功能需求 | 性能/安全/兼容性要求？ |
+| 集成接口 | 与哪些系统交互？ |
+| 边界案例 | 异常/极端情况如何处理？ |
+| 约束条件 | 有哪些技术/业务约束？ |
+| 术语定义 | 关键术语的定义？ |
+| 优先级 | 优先级如何排定？ |
+| 风险项 | 有哪些潜在风险？ |
+| 验收标准 | 如何判断需求完成？ |
+
+### Step 2: 按 Impact × Uncertainty 排序
+
+计算每个问题的优先级分数：
+- **Impact**（影响）：高 (3) / 中 (2) / 低 (1)
+- **Uncertainty**（不确定性）：高 (3) / 中 (2) / 低 (1)
+- **优先级分数** = Impact × Uncertainty
+
+### Step 3: 最多 5 个问题，逐个提问
+
+每个问题格式：
+```
+问题：{问题描述}
+AI 推荐答案：{推荐答案}
+推理过程：{为什么推荐这个答案}
+```
+
+### Step 4: 每个回答原子更新到需求文档
+
+- 澄清记录存入 `clarifications.md`
+- 更新需求文档中的对应章节
+- 标记澄清状态（已确认/待确认）
+
+**规则**：
+- 超过 5 个歧义 → 先澄清 Top 5，其余用知情猜测（DP5）
+- 自主模式下，AI 可直接采用推荐答案（仍需记录）
+
+---
+
+## 需求检查清单
+
+### 必填章节检查
+
+- [ ] 1.1 业务背景
+- [ ] 1.2 业务价值
+- [ ] 2.1 目标
+- [ ] 2.2 范围
+- [ ] 3.2 需求用例图
+- [ ] 3.5 用例业务流程
+
+### 质量检查
+
+- [ ] 每条功能需求有明确的验收标准
+- [ ] 需求描述无歧义（不同人读到的理解一致）
+- [ ] 技术可行性已初步评估
+- [ ] 边界清晰（明确列出做什么、不做什么）
+- [ ] 非功能需求已覆盖（性能、安全、兼容性）
+- [ ] 依赖和约束已识别
+- [ ] 需求描述符合 5W 标准（Who/Where+When/What/Why）
+- [ ] 用户痛点已穿透至少两层
+- [ ] 客户价值公式成立（新方案 - 旧方案 - 转换成本>0）
+
+### 三板斧检查
+
+- [ ] 灰度策略已定义
+- [ ] 监控指标已定义
+- [ ] 应急预案已定义
+
+---
+
+## 最佳实践
+
+1. **用例原子化**: 每个用例应该是原子的，不可再拆分
+2. **流程图优先**: 能用图表达的不用文字
+3. **明确边界**: 清晰定义包含和不包含的范围
+4. **关键决策记录**: 记录重要技术选型和方案取舍
+5. **风险前置**: 提前识别风险并制定缓解措施
+6. **WHEN-THEN 格式**: 用 Gherkin 风格描述需求，确保无歧义
+7. **三板斧思维**: 发布前必须考虑灰度、监控、应急
+
+---
+
+## 参考资料
+
+- [proposal 模板](../templates/proposal.md)
+- [需求检查清单](../checklists/requirement.md)
+- [设计哲学 - 结构化澄清协议](../principles/design-philosophy.md#dp17-结构化澄清协议)
+- [设计哲学 - 三板斧](../principles/design-philosophy.md#dp10-安全与紧急制动)