@chongyan/autospec 1.0.1

package/knowledge/process/overview.md

@@ -0,0 +1,319 @@
+# 研发流程概览
+
+## 执行模式
+
+| 模式 | 触发方式 | 特点 | 阻塞行为 |
+|-----|---------|------|---------|
+| **交互模式** | 普通运行、单阶段命令 | 有人值守，可询问用户 | 允许阻塞等待用户输入 |
+| **自动模式** | `/autospec:run` | 无人值守，全自动执行 | **禁止阻塞**，必须自动决策或记录待办 |
+
+**核心原则**：
+- 自动模式下，所有"需要用户确认"的场景 → 使用推荐值 + 记录 `pendingConfirmations`
+- 交互模式下，利用 AskUserQuestion 批处理提升效率（收集所有歧义一次性提问）
+- 同一套阶段逻辑，通过模式开关控制行为
+
+### 执行模式
+
+| 模式 | 人工介入点 | 说明 |
+|------|-----------|------|
+| **自主模式** | 仅异常/宪法/方向决策 | 全流程自动运行，AI自主决策 |
+| **交互模式** | 每阶段确认 | 分阶段执行，人工确认后进入下一阶段 |
+
+## 启动门禁（必须执行，不可跳过）
+
+收到任何开发/建设类任务时：
+
+```
+1. 读取本文件 → 确定迭代模式
+2. 读取 constitution.md → 确认红线
+3. 确认执行模式（自主/交互）→ 决定人工介入点
+4. 向用户确认：任务范围 + 迭代模式 + 涉及角色
+   - 交互模式：阻塞等待确认
+   - 自主模式：使用推荐配置，记录到 pendingConfirmations
+5. 确认后进入第一个阶段
+```
+
+**违反 = 宪法违规 → 立即停止**
+
+## 全流程
+
+```
+[Stage 0] → 需求分析 → 方案设计 → 编码实现(含自测) → 代码审查 → QA测试 → 交付部署
+  环境就绪      │           │              │              │          │          │
+               ▼           ▼              ▼              ▼          ▼          ▼
+           [双层验证]  [双层验证]     [双层验证]     [双层验证] [双层验证] [双层验证]
+```
+
+### Stage 0: 环境就绪检查（编码前必过）
+
+```
+- [ ] 项目能安装依赖
+- [ ] 能运行现有测试（如有）
+- [ ] 开发服务器能启动（如适用）
+- [ ] 环境变量完备（如任务需要访问数据环境）
+- [ ] 不满足 → 先解决环境问题，不开始写代码
+```
+
+### 每个阶段执行流程
+
+1. **规范预学习**（强制）：读取相关规范和领域知识，记忆关键规则
+2. 组织上下文（上游精炼契约 + 角色关注点）
+3. 做类skills执行生产
+4. **检查点输出**：每个关键步骤输出进度状态（步骤/状态/产出物）
+5. Layer 1 确定性验证（编译/测试/lint/schema校验）——**必须真实执行，无日志=BLOCKED**
+6. Layer 1通过 → Layer 2 AI审查（审类skills，通过Agent工具独立子进程执行，实现信息隔离）
+7. 两层都过 → 阶段确认：
+   - 交互模式：等待用户确认
+   - 自主模式：使用 stage-gate-evaluator Agent 替代人工确认
+8. 确认通过 → 输出精炼契约 → 下一阶段
+
+### 阶段确认的模式分支
+
+| 场景 | 交互模式 | 自主模式 |
+|-----|---------|---------|
+| 需求澄清 | AskUserQuestion 批处理（收集所有歧义一次性提问） | 使用推荐值，记录 pendingConfirmations |
+| 设计决策 | 展示选项等待用户选择 | 采用保守默认值，记录 autoDecisions |
+| 验证失败 | 阻塞，展示错误等待修复 | 记录失败，标记 BLOCKED，继续可执行的步骤 |
+| 安全/合规 | 阻塞，要求明确确认 | 使用最安全选项，标记 HIGH_PRIORITY_REVIEW |
+| 阶段准出 | 等待人工确认 | stage-gate-evaluator Agent 自动评估 |
+
+## 双层验证机制（DP1）
+
+每个质量关卡分两层，**Layer 1不过，不进Layer 2**：
+
+| 层级 | 验证方式 | 特征 | 执行者 |
+|------|---------|------|--------|
+| Layer 1 | 确定性验证 | 编译/测试/lint/类型检查/schema校验 | 机器（Hook/CI） |
+| Layer 2 | AI审查 | 架构合理性/需求覆盖度/设计一致性/安全 | 审类skill（独立AI实例） |
+
+Layer 2输出必须包含：结论（通过/不通过）+ 逐项判定 + 证据 + 修复建议。不接受无证据的"通过"。
+
+### Layer 1 验证分级
+
+为平衡效率与质量，Layer 1 分为两级：
+
+| 级别 | 检查项 | 适用场景 | 耗时 |
+|------|--------|---------|------|
+| **快速验证** | 编译 + 单元测试 | 编码阶段每次提交 | 秒~分钟 |
+| **完整验证** | 编译 + 全量测试 + Lint + 类型检查 | 阶段准出、交付前 | 分钟~十分钟 |
+
+**规则**：
+- 快速验证不通过 → 不得提交代码
+- 完整验证不通过 → 不得进入下一阶段
+- 验证必须真实执行，附带日志，无日志=BLOCKED
+- 不接受"应该可以"、"之前测过"等推测性表述
+
+## 做审分离（DP2）
+
+做和审由不同AI实例执行。同一AI既做又审容易自我确认偏差。command-runner负责协调，确保做类Worker和审类Worker独立运作。
+
+## 精准回退机制（DP6）
+
+```
+验证不通过
+    │
+    ▼
+Level 1: 内联重试（单次，零成本尝试）
+    │ 仍不通过
+    ▼
+Level 2: 修正循环（最多3次）
+    │  结构化诊断 → 只重处理失败项 → 重验证
+    │ 第3次仍不通过
+    ▼
+Level 3: 使用 failure-diagnostician Agent 执行根因分析 → 升级人工
+    │  提交：诊断报告 + 3次产出 + 3次审查意见
+    ▼
+人工决策（修正/回退/调整需求）
+```
+
+## 阶段间契约传递（DP4+DP12）
+
+- 阶段间传递**精炼契约**，不传原文（控制上下文膨胀）
+- 契约必须包含：产出物 + 关键假设清单 + 证据清单
+- 关键假设分为"已确认"和"待确认"，待确认超过3个 → 升级人工
+- 关键决策写入文件，防止上下文压缩后丢失
+
+## 迭代模式模板
+
+| 模式 | 走哪些阶段 | 说明 | 适用场景 |
+|------|-----------|------|---------|
+| **waterfall** | 需求→设计→实现(含自测)→审查→QA测试→部署 | 完整6阶段 | 新功能开发 |
+| **agile** | 需求(拆故事)→[设计→实现→审查]×N→集成测试→部署 | 故事驱动循环 | 迭代开发、用户故事驱动 |
+| **experiment** | 需求→设计→原型+效果评测 | AI实验验证 | 技术探索、AI/ML |
+| **hotfix** | 需求→实现(含自测)→审查→部署 | 快速通道 | 紧急修复 |
+
+### Agile（敏捷迭代）模式说明
+
+```
+需求分析 → 拆解为用户故事（按优先级排序）
+  │
+  ▼ 对每个故事循环：
+  ┌─────────────────────────────┐
+  │ 方案设计 → 编码实现 → 代码审查 │  ← 小循环，快速交付
+  └─────────────────────────────┘
+  │
+  ▼ 所有故事完成后：
+集成测试 → 交付部署
+```
+
+- 需求阶段产出用户故事列表，每个故事有验收标准
+- 设计→编码→审查是每个故事的小循环（iterableStages: 02→03→04）
+- 每个小循环独立通过双层验证
+- 所有故事完成后进入集成测试和交付
+
+## 标准化产物结构（DP16）
+
+每个特性/任务在 `.autospec/specs/` 下生成标准化产物目录：
+
+```
+.autospec/specs/[NNN-feature-name]/
+├── requirement.md      ← 需求文档（WHAT/WHY）
+├── clarifications.md   ← 澄清记录（DP17）
+├── design.md           ← 技术方案（HOW）
+├── assumptions.md      ← 关键假设清单（已确认/待确认）
+├── tasks.md            ← 任务分解（含依赖关系和并行标记）
+├── contracts/          ← API/接口契约
+├── review-report.md    ← 审查报告（Layer 2产出）
+└── test-report.md      ← 测试报告
+```
+
+**产物规则**：
+- 主文档保持可导航（不超过200行），细节放子目录
+- 每个产物包含强制字段（不填=schema校验不通过）
+- 不确定项标记 `[NEEDS CLARIFICATION]`（最多3个）
+- 阶段间传递精炼契约，不传原文
+
+### tasks.md 任务分解格式
+
+任务拆分三视角统一：**系统边界 + 任务规模 + 阶段依赖**。
+
+```markdown
+# 任务分解
+
+## 拆分依据
+
+- 系统边界：涉及后端、前端、AI、数据四个子系统
+- 任务规模：预估 40 人时，需拆分
+- 阶段依赖：AI 效果验证 → 后端 API → 前端/移动端
+
+## 依赖图（含解耦标记）
+
+\`\`\`
+[P1: AI模型验证] →data(不可解耦)→ [P2: 后端API]
+                                        ├─→contract→ [P3: 前端页面]
+                                        └─→contract→ [P4: 移动端]
+[P2: 后端API]
+    ├─→contract→ [P5: 数据管道]（数据Schema定义后并行）
+    └─→ [T2.1: 数据模型] →logic→ [T2.2: 核心接口]
+\`\`\`
+
+## 解耦并行分析
+
+| 依赖关系 | 可解耦 | 解耦方式 | 标准产出物 |
+|----------|--------|----------|------------|
+| P2 →data→ P3 | ✅ | API契约定义后并行 | OpenAPI Schema |
+| P2 →data→ P4 | ✅ | API契约定义后并行 | OpenAPI Schema |
+| P2 →data→ P5 | ✅ | 数据Schema定义后并行 | 表结构定义 |
+| P1 →data→ P2 | ❌ | 效果不达标则后续无意义 | - |
+
+## 任务清单
+
+| ID | Phase | 任务 | 依赖 | 并行 | 预估 | 验证标准 |
+|----|-------|------|------|------|------|----------|
+| P1 | AI | 模型效果验证 | - | - | 8h | 准确率>85% |
+| T2.0 | Backend | API契约定义 | - | - | 1h | OpenAPI文档 |
+| P2 | Backend | 后端API开发 | P1→data | - | 12h | 全部接口测试通过 |
+| T2.1 | Backend | 数据模型设计 | - | - | 2h | ER图评审通过 |
+| T2.2 | Backend | 核心接口实现 | T2.1→logic | - | 6h | 接口测试通过 |
+| P3 | Frontend | 前端页面开发 | T2.0→contract | 与P4,P5并行 | 6h | E2E测试通过 |
+| P4 | Mobile | 移动端适配 | T2.0→contract | 与P3,P5并行 | 4h | 真机测试通过 |
+| P5 | Data | 数据管道开发 | T2.1→contract | 与P3,P4并行 | 4h | 数据校验通过 |
+
+## 执行批次
+
+| 批次 | Phase/Task | 说明 |
+|------|------------|------|
+| 1 | P1 | 阻塞后续，必须先完成 |
+| 2 | T2.0, T2.1 | 契约+数据模型定义（解耦关键） |
+| 3 | T2.2, P3, P4, P5 | 契约定义后并行执行 |
+| 4 | 联调验证 | P3/P4/P5 与 P2 联调 |
+```
+
+**依赖标记说明**：
+- `→data`：数据依赖，上游产出作为下游输入
+- `→logic`：逻辑依赖，业务流程顺序约束
+- `→res`：资源依赖，共享资源需串行访问
+- `→contract`：契约解耦，定义标准产出物后可并行
+- `→mock`：Mock并行，下游基于Mock开发
+- `[P]`：可并行执行
+
+**解耦并行原则**：
+- 可定义标准产出物（API契约、数据Schema）→ 可解耦并行
+- 不可解耦依赖 → 必须串行，不硬跳过
+
+## 结构化澄清协议（DP17）
+
+需求分析阶段发现歧义时，执行有界澄清：
+
+```
+Step 1: 11维分类扫描
+  功能范围 | 数据模型 | UX流程 | 非功能需求 | 集成接口
+  边界案例 | 约束条件 | 术语定义 | 优先级 | 风险项 | 验收标准
+
+Step 2: 按 Impact × Uncertainty 排序
+
+Step 3: 最多5个问题，逐个提问
+  每个问题附AI推荐答案 + 推理过程
+  用户可接受推荐或给出不同答案
+
+Step 4: 每个回答原子更新到需求文档
+```
+
+**规则**：
+- 超过5个歧义 → 先澄清Top 5，其余用知情猜测（DP5）
+- 澄清记录存入 `clarifications.md`（可追溯）
+- 自主模式下，AI可直接采用推荐答案（仍需记录）
+
+## 角色化执行
+
+```
+通用pipeline + 通用skills + 角色profile + 角色特有skills = 角色化执行
+```
+
+command-runner 启动时：
+1. 识别任务类型 → 选择工作流模板
+2. 识别涉及的角色 → 加载角色profile
+3. 对每个阶段合并：通用skills + 角色特有skills + 角色特有检查项
+4. 支持单角色和多角色模式（多角色取检查项并集）
+
+## 安全制动（DP10）
+
+任何阶段触发以下条件 → 立即停止全流程：
+- 安全漏洞
+- 数据丢失风险
+- 同一问题修复3次仍未通过 → 使用 failure-diagnostician Agent 诊断后升级人工
+- 不可逆动作（DB迁移、部署、外部API发送）→ 使用 safety-auditor Agent 审计后，必须人工确认
+
+## 各阶段概览
+
+| 阶段 | 输入 | 核心动作 | 输出 | Layer 1验证 | Layer 2审查 |
+|------|------|---------|------|------------|------------|
+| 需求分析 | 原始需求 | 拆解、澄清、排优先级 | 结构化需求文档 | schema校验 | requirement-reviewer |
+| 方案设计 | 需求文档 | 架构、接口、数据建模 | 技术方案文档 | schema校验 | design-reviewer |
+| 编码实现 | 技术方案 | 编码+研发自测 | 自测通过的代码 | 编译/测试/lint | code-reviewer |
+| 代码审查 | 代码+方案 | 质量/安全/性能审查 | 审查报告 | lint/类型检查 | 独立code-reviewer |
+| QA测试 | 代码+需求 | 功能/探索性测试 | 测试报告 | 测试执行通过 | test-coverage-reviewer |
+| 交付部署 | 测试通过代码 | 前置检查/部署/验证 | 上线功能 | release checklist | release-checker |
+
+## 各阶段认知原则（CP）配置
+
+每个阶段加载 `methodology/principles.md`，重点应用不同原则：
+
+| 阶段 | 认知姿态 | 重点CP |
+|------|---------|--------|
+| 需求分析 | 发散+挑战 | CP1(合伙人模式)、CP3(先问后做)、CP5(置信度) |
+| 方案设计 | 发散→收敛 | CP4(逻辑链完整)、CP9(刚好够用)、CP5(置信度) |
+| 编码实现 | 严格执行 | CP8(偏航检测)、CP9(刚好够用)、CP10(自我质检) |
+| QA测试 | 批判思维 | CP6(错误即信号)、CP10(自我质检)、CP1(合伙人模式) |
+| 交付部署 | 收敛+安全 | CP10(自我质检)、CP8(偏航检测) |
+| 自进化 | 反思+提炼 | CP6(错误即信号)、CP7(模式识别) |