@chongyan/autospec 1.0.1 → 1.0.3

package/knowledge/guides/knowledge-management.md

@@ -1,369 +0,0 @@
-# 知识管理指南
-
-> **版本**: 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

@@ -1,329 +0,0 @@
-# 需求工程指南
-
-> **版本**: 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-安全与紧急制动)