@chongyan/autospec 1.0.1

package/knowledge/guides/support/pipeline-protocol.md

@@ -0,0 +1,438 @@
+---
+name: pipeline-protocol
+description: AutoSpec核心流程命令的协议，包含流程执行所需的扩展能力
+type: protocol
+---
+
+# 使用说明
+
+本文档包含AutoSpec核心流程命令的执行协议。
+
+**【适用范围】**
+- 仅适用于核心流程命令：run、explore、propose、apply、archive
+- 自进化命令：self-evolve、field-evolve、project-evolve
+- 其他命令（validate、status、env系列、component系列）不需要读取本协议
+
+**【强制要求】**
+- 核心流程命令执行前必须先读取本协议
+- 核心能力包括：前后置处理、精准回退、安全制动、上下文管理、双层验证
+
+---
+
+## 定位
+
+AutoSpec核心流程命令的执行协议。负责提供流程执行所需的扩展能力，包括前置检查、精准回退、安全制动、上下文管理、双层验证等。
+
+---
+
+## 流程能力
+
+### 1. 前后置处理
+
+#### 解析命令与参数
+
+```
+a. 识别命令类型 → 确定执行模式
+b. 解析 $ARGUMENTS:
+   - 提取任务描述
+   - 提取选项参数 (--workflow, --roles, --verbose等)
+c. 确定执行模式 (interactive/autonomous)
+```
+
+#### 加载必要文件
+
+```
+a. 核心文件（所有命令）：
+   - {{framework}}/constitution.md → 宪法红线
+   - .autospec/runtime/config.json → 项目配置
+   - .autospec/runtime/state.json → 流程状态（如有）
+
+b. 命令特定文件（按需加载）：
+   - run: pipeline/overview.md, 阶段Skills
+   - explore: pipeline/01-requirement.md, requirement-analyzer skill
+   - propose: pipeline/02-design.md, design-planner skill
+   - apply: pipeline/03-implementation.md ~ 05-testing.md, code-* skills
+   - archive: pipeline/06-delivery.md, release-checker skill
+   - status: 仅读取state.json
+   - validate: 根据config确定验证策略
+   - evolve: evolution.md, skill-distiller skill
+```
+
+#### 执行命令前置检查
+
+```
+a. 状态检查（适用于 explore/propose/apply/archive）:
+   - 检查上游阶段是否已完成
+   - 未完成 → 阻断并提示先执行前置命令
+
+b. 配置文件检查:
+   - 确保 config.json 存在
+   - 验证配置兼容性
+
+c. 环境检查（适用于 run/apply）:
+   - 项目能否安装依赖
+   - 能否运行现有测试
+```
+
+---
+
+### 2. 精准回退机制（DP6）
+
+#### 问题分类（回退前先分类）
+
+**AUTO-FIX（自动修复，两种模式都直接执行）**：
+- 格式问题（缩进、标点、Markdown格式）
+- 术语不一致（统一替换）
+- 缺失的必填字段（从上下文推断填充）
+- 引用错误（链接修复）
+
+**AUTO-DECIDE（自动模式自动决策，交互模式询问）**：
+- 安全相关（认证、加密）→ 自动模式用最安全选项
+- 业务逻辑冲突 → 自动模式用保守默认
+- 性能权衡决策 → 自动模式用推荐配置
+- 合规性要求 → 自动模式用最严格标准
+
+**REQUIRE-REVIEW（两种模式都记录，自动模式不阻塞）**：
+- 架构变更
+- 大范围重构（>20行核心逻辑）
+- 外部系统集成
+- 宪法红线相关决策
+
+#### 回退流程
+
+验证不通过时，按以下顺序执行：
+
+**Level 1: 内联重试**
+- 生成失败 → 立即单次重试（零成本尝试）
+
+**Level 2: 修正循环（最多3次）**
+- 将结构化诊断反馈给"做"类skill
+- 只重处理失败项，不全量重做
+- 定向修复 → 重验证
+
+**Level 2.5: 3-Strike 假设验证**（Level 2 第3次前执行）
+- 对失败原因生成 3 个假设（H1/H2/H3）
+- 逐一验证假设（对照上下文、代码、日志）
+- 假设全部失败 → 说明问题超出当前阶段能力，升级 Level 3
+- 交互模式：展示三个假设和验证结果，请用户指导
+- 自动模式：使用最保守假设，记录低置信度决策
+
+**Level 3: 升级人工**
+- 暂停流程，执行结构化根因分析
+- 将诊断报告 + 当前阶段输入 + 审查意见提交给人工
+- 交互模式：阻塞等待人工决策
+- 自动模式：标记 BLOCKED + 记录诊断报告，跳过该阶段
+
+---
+
+### 3. 安全制动检查（DP10）
+
+每个阶段执行后检查：
+- **安全漏洞** → 立即停止
+- **数据丢失风险** → 立即停止
+- **同一问题修复3次仍未通过** → 诊断后升级人工
+- **不可逆动作**（DB迁移、部署、外部API）→ 必须人工确认
+- **宪法门禁违反** → 立即停止
+
+---
+
+### 4. 上下文管理（DP4）
+
+三层上下文架构：
+- **热层**（始终加载）：宪法、核心规范、当前阶段上下文
+- **温层**（按需加载）：角色profile、阶段skill、领域知识
+- **冷层**（检索加载）：详细文档、历史案例、完整代码
+
+规则：
+- 阶段间传递精炼契约，不传原文
+- 每个agent独立上下文
+- 关键决策写入文件（压缩后可自动恢复）
+- 60-70%容量主动压缩
+
+---
+
+### 5. 统一输出格式
+
+```
+## 执行摘要
+
+- 命令: {command}
+- 状态: ✅ 成功 / ❌ 失败
+- 产出物:
+  - {path/to/artifact1}
+  - {path/to/artifact2}
+
+## 关键决策
+- {决策1} (置信度: {high/medium/low})
+
+## 下一步
+- {建议的下一步操作}
+```
+
+---
+
+### 6. 双层验证
+
+**Layer 1: 确定性验证**
+- 编译/测试/lint/类型检查/schema校验（视阶段而定）
+- 用Hook实现，不依赖AI判断
+- 不通过 → 进入精准回退，不进Layer 2
+
+**Layer 2: AI审查**
+- 调用"审"类skills执行评审（独立AI实例，做审分离DP2）
+- 审查输出必须包含：结论 + 逐项判定 + 证据 + 修复建议
+- 不接受无证据的"通过"
+
+---
+
+## 反模式清单
+
+1. **跳过前置检查**：未检查上游依赖直接执行 → 必须检查依赖状态
+2. **忽略执行模式**：自动模式下阻塞等待用户 → 必须用推荐值自动决策
+3. **丢失上下文**：未传递关键假设 → 必须维护假设追踪表
+4. **重复加载**：每次执行都重新加载文件 → 应使用缓存机制
+5. **命令越权**：命令直接执行而非调用Skill → 必须调用对应Skill执行
+6. **跳过Layer 1**：确定性验证未通过就进入AI审查 → Layer1是硬门禁，不可跳过
+7. **做审同体**：做和审由同一个AI实例执行 → 必须用Agent工具启动独立子进程
+8. **全量重做**：回退时从头开始而非定向修复 → 回退只重处理失败项
+9. **无限循环**：修正循环超过3次仍继续 → 3次上限触发人工升级
+10. **上下文膨胀**：传递原文而非精炼契约 → 阶段间只传契约
+11. **假设丢失**：阶段间未传递关键假设 → 假设追踪表贯穿全流程
+12. **安全绕过**：跳过不可逆动作的人工确认 → 宪法门禁不可关闭
+13. **急于生成**：收到任务直接写代码，跳过需求和设计 → 启动门禁强制执行
+14. **假装验证**：Layer 1无法执行时用静态分析替代 → 结果必须附带真实执行日志
+15. **自动模式阻塞**：自动模式下等待用户输入 → 禁止任何阻塞操作
+
+---
+
+## 适用命令
+
+本协议仅适用于以下核心流程命令：
+
+| Command | 执行文件 |
+|---------|---------|
+| run | `plugins/commands/run.md` |
+| explore | `plugins/commands/explore.md` |
+| propose | `plugins/commands/propose.md` |
+| apply | `plugins/commands/apply.md` |
+| archive | `plugins/commands/archive.md` |
+| self-evolve | `plugins/skills/self-evolve/SKILL.md` |
+| field-evolve | `plugins/skills/field-evolve/SKILL.md` |
+| project-evolve | `plugins/skills/project-evolve/SKILL.md` |
+
+**不适用本协议的命令**：validate、status、env系列、component系列
+
+---
+
+## AI 增强 Pipeline
+
+> 本章节定义如何利用 AI 增强 Pipeline 自动化能力。
+> 与 `knowledge/process/ai-sdlc.md` 互补。
+
+### 1. AI 驱动的 Pipeline 能力
+
+#### 1.1 AI 自动生成
+
+| 能力 | 描述 | 触发条件 |
+|------|------|---------|
+| **AI 测试生成** | 自动生成单元/集成测试 | 代码变更提交 |
+| **AI 文档生成** | 自动生成/更新 API 文档 | 代码变更提交 |
+| **AI 变更日志** | 自动生成 CHANGELOG | 版本发布 |
+
+#### 1.2 AI 自动化门禁
+
+| 门禁 | AI 能力 | 触发条件 |
+|------|---------|---------|
+| **代码质量** | AI 代码风格检查 | 每次提交 |
+| **安全扫描** | AI 安全漏洞检测 | 每次提交 |
+| **性能评估** | AI 性能反模式检测 | 每次提交 |
+| **架构检查** | AI 架构合规性检查 | PR 创建 |
+
+#### 1.3 AI 辅助决策
+
+| 决策点 | AI 能力 | 输出 |
+|--------|---------|------|
+| **是否通过** | AI 综合评估 | 通过/需修复/需人工 |
+| **风险评估** | AI 变更风险分析 | 风险等级 |
+| **回归范围** | AI 变更影响分析 | 影响范围 |
+
+### 2. AI Pipeline 流程
+
+```
+代码变更
+    │
+    ▼
+┌─────────────────┐
+│   AI 预检查      │ ← 快速扫描，阻断明显问题
+│  (风格/安全)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   AI 生成       │ ← 按需触发
+│ (测试/文档)    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   AI 审查       │ ← 多代理并行审查
+│  (架构/逻辑)   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   人类确认      │ ← 最终确认
+│                 │
+└─────────────────┘
+```
+
+### 3. AI Pipeline 配置
+
+```yaml
+# .autospec/ai-pipeline.yaml
+ai_pipeline:
+  enabled: true
+
+  # 自动生成
+  generation:
+    test:
+      enabled: true
+      coverage_target: 80%
+    docs:
+      enabled: true
+      types: [api, readme, changelog]
+
+  # 自动化门禁
+  gates:
+    quality:
+      enabled: true
+      auto_fix: true
+    security:
+      enabled: true
+      auto_fix: false
+    performance:
+      enabled: true
+      auto_fix: false
+    architecture:
+      enabled: true
+      auto_fix: false
+
+  # AI 审查
+  review:
+    enabled: true
+    agents:
+      - architecture
+      - security
+      - performance
+      - maintainability
+      - logic
+    parallel: true
+    auto_merge_threshold: high
+
+  # 人类介入
+  human:
+    required_for:
+      - security_issues
+      - architecture_changes
+      - performance_degradation
+    auto_merge_for:
+      - style_fixes
+      - documentation
+      - test_additions
+```
+
+### 4. 持续进化机制
+
+#### 4.1 AI 辅助 practice-log 分析
+
+```
+practice-log 收集
+       │
+       ▼
+AI 自动分类（问题类型/严重程度）
+       │
+       ▼
+AI 模式识别（重复问题检测）
+       │
+       ▼
+AI 建议生成（skill 更新/流程改进）
+       │
+       ▼
+人类审核
+       │
+       ▼
+自动应用/手动执行
+```
+
+#### 4.2 AI 辅助 skill 生成
+
+| 阶段 | AI 能力 |
+|------|---------|
+| 触发识别 | AI 检测重复解决方案 |
+| 模式提取 | AI 归纳通用模式 |
+| Skill 生成 | AI 生成 Skill 骨架 |
+| 验证 | 人类确认 |
+
+#### 4.3 AI 辅助 benchmark 更新
+
+| 能力 | 描述 |
+|------|------|
+| 效果趋势分析 | AI 分析 benchmark 得分趋势 |
+| 异常检测 | AI 检测 benchmark 异常 |
+| 阈值建议 | AI 建议新的 benchmark 阈值 |
+
+### 5. 与现有机制的集成
+
+#### 5.1 与双层验证的集成
+
+```
+Layer 1: AI 辅助的确定性验证
+  ├── AI 风格检查
+  ├── AI 安全扫描
+  └── AI 性能检查
+
+Layer 2: AI 审查 + 人类确认
+  ├── 多代理 AI 审查
+  └── 人类最终确认
+```
+
+#### 5.2 与精准回退的集成
+
+```
+AI 检测问题 → 自动分类
+       │
+       ├── AUTO-FIX → AI 自动修复
+       │
+       ├── AUTO-DECIDE → AI 自动决策
+       │
+       └── REQUIRE-REVIEW → 人类确认
+```
+
+#### 5.3 与安全制动的集成
+
+```
+AI 发现安全漏洞 → 立即阻断
+AI 发现数据丢失风险 → 立即阻断
+AI 发现 3 次修复未通过 → 升级人工
+```
+
+---
+
+## Phase 2 演进方向
+
+```
+当前 Phase 1：单agent顺序执行
+目标 Phase 2：Orchestrator + Workers（DP9）
+  - 任务分解（满足ATOMIC原则，DP11）
+  - 分配Worker（每个Worker独立上下文+worktree隔离）
+  - 状态监控（状态机驱动）
+  - 自动反应（声明式：ci-failed→自动修复，stuck→升级）
+  - 顺序合并Worker产出
+  - 触发回流
+
+AI 增强 Phase 2：
+  - AI 自动任务分解
+  - AI Worker 分配优化
+  - AI 状态预测
+  - AI 自动恢复
+```