add-coder 0.3.16 → 0.3.18

package/templates/core/templates/collab-contract-template.md

@@ -0,0 +1,203 @@
+# {需求域名}-{核心内容}-collab-contract-v{版本号}
+
+# ADD 范式并发协作契约（{平台名} 多智能体实施）
+
+> **性质**：并发协作契约（Concurrency Collaboration Contract）——非实施 Plan。
+> 本契约定义"总控 Plan + N 个子 Plan"在多智能体模式（如 Qoder Quest Experts）下**如何并行协作、按触发条件依次工作**的规则集。实施内容由各子 Plan 把控，本契约只管**协作秩序**。
+>
+> **适用条件**：已有 ≥2 个子 Plan 需并行实施；平台支持 Lead Agent 调度 + 自定义子智能体（子智能体可绑定独立 planKeyword / Skills / MCP）。
+
+## PLAN 元信息
+
+- **契约名称**: {需求域名}-{核心内容}-collab-contract-v{版本号}
+- **制定时间**: {ISO 时间戳}
+- **主导 AI**: {AI 助手标识}
+- **目标仓库**: {仓库绝对路径}
+- **关联体系**:
+  - 总控 Plan: `{总控 Plan 路径}`
+  - 子 Plan 1: `{子 Plan 1 路径}`
+  - 子 Plan 2: `{子 Plan 2 路径}`
+  - 子 Plan N: `{子 Plan N 路径}`
+- **ADD-7 审计策略**:
+
+| 文件 | targetType | action | beforeState | afterState | 状态 |
+|-----|-----------|--------|------------|-----------|------|
+| {契约文件路径} | PLAN | PLAN_CREATED | 无并发协作契约 | 多智能体协作规则集 | 本文件 |
+
+---
+
+## HITL 契约总览（一次性提交人类审核）
+
+| 维度 | 内容 | 人类决策 |
+|------|------|:---:|
+| 参与者 | {Lead Agent 角色} + {N 个自定义专家} | 同意/调整 |
+| 并行策略 | {阶段划分与并行度描述} | 同意/调整 |
+| 触发机制 | {Lead 如何解析依赖与拉起专家} | 同意/调整 |
+| 文件边界 | {三方文件域划分} | 同意/调整 |
+| 风险等级 | {🟢/🟡/🔴} | 同意/调整 |
+
+> **人类确认后**：契约定稿，可作为平台专家团配置指南。
+
+---
+
+## 一、背景与目标
+
+### 1.1 问题现状
+
+{为什么需要并发契约：已有子 Plan 体系但协作秩序未定义 / 平台能力已具备但规则未制定 / 无契约时并行必然冲突}
+
+### 1.2 目标
+
+1. {定义并行协作规则（角色/触发/边界/仲裁）}
+2. {让平台多智能体模式原生承载 ADD 范式}
+3. {审计天然分桶，跨会话恢复不混淆}
+
+---
+
+## 二、参与者与角色
+
+| 角色 | 平台实体 | 对应 Plan | 职责 |
+|------|-----------|-----------|------|
+| **Lead Agent** | {主智能体} | {总控 Plan} | {调度/对齐/验收；不写实施代码} |
+| **专家 1** | {自定义子智能体} | {子 Plan 1} | {职责} |
+| **专家 2** | {自定义子智能体} | {子 Plan 2} | {职责} |
+| **专家 N** | {自定义子智能体} | {子 Plan N} | {职责} |
+
+**每个专家绑定**：
+- 独立 planKeyword（hook 事件 + record_dev_operation 归因）
+- 独立 Skills + MCP
+- **description 字段**（平台自动委派依据——描述“何时被调用”，与 §3.1 触发条件对齐）
+- 追加提示词：职责边界 + 文件边界 + 完成判定
+
+> **专家定义（2026-08-05 websearch 核实）**：平台 Subagent 本质是**任务委派单元**——通过 `description` 字段声明“何时被调用”，主智能体按任务描述自动匹配并委派。本项目将 Subagent 绑定为「Plan 实施单元」：description 即触发条件（§3.1），tools/skills/mcpServers 即能力边界（§2.1）。
+
+### 2.1 能力矩阵（每个专家的能力边界）——必填
+
+| 能力 | 专家 1 | 专家 2 | ... | Lead |
+|------|:---:|:---:|:---:|:---:|
+| {能力 A} | ✅/❌ | ✅/❌ | | ✅/❌ |
+| {能力 B} | ✅/❌ | ✅/❌ | | ✅/❌ |
+
+**能力边界规则**：每个专家只能在其能力列 ✅ 范围内工作；能力交叉区按文件边界细分（§3.2）。
+
+---
+
+## 三、协作规则（契约主体）
+
+### 3.1 触发条件表（谁先谁后）——必填
+
+| 阶段 | 专家 | 触发条件 | 并行度 |
+|------|------|---------|:---:|
+| A | {专家} | {前置依赖/无依赖} | 并行/串行 |
+| B | {专家} | {消费 A 产出} | 串行 |
+
+**规则**：Lead Agent 每轮检查触发条件——满足即拉起，不满足不阻塞（等待或先做无依赖部分）。
+
+**触发机制（平台 Subagent 调度）**：主智能体把当前任务描述与各专家 `description` 比对，命中即委派；彼此独立的任务可并发。因此每个专家的 `description` 必须与本节触发条件表对齐：
+
+| 专家 | description 建议文案（触发匹配依据） |
+|------|-----------------------------------|
+| 专家 1 | “实施 {子 Plan 1}：{一句话职责}” |
+| 专家 2 | “实施 {子 Plan 2}：{一句话职责}” |
+| Lead | “总控：解析依赖拓扑，按触发条件委派专家，验收整合” |
+
+### 3.1.1 依赖拓扑图（完整）——必填
+
+```
+{ASCII 依赖图：Lead 在顶，专家分叉，标注产出/消费关系与阶段}
+```
+
+**依赖关系声明**（机器可读，供 Lead 解析）：
+
+```
+依赖: {专家X} → { 专家Y产出(说明), ... }
+无依赖: {专家A}, {专家B}（可立即并行）
+```
+
+### 3.2 文件边界（防冲突硬约束）——必填
+
+| 专家 | 独占文件域 | 禁区 |
+|------|-----------|------|
+| {专家 1} | {路径域} | {禁改域} |
+| {专家 2} | {路径域} | {禁改域} |
+
+**仲裁**：跨边界修改必须经 Lead Agent 批准（记录仲裁事件，planKeyword=总控）。
+
+> **隔离强度（2026-08-05 websearch 核实）**：平台支持 Subagent 在独立 git worktree 运行（隔离工作区）。默认文件边界（软隔离），高风险/大改场景升级 worktree（硬隔离）：
+>
+> | 模式 | 适用 | 隔离强度 |
+> |------|------|---------|
+> | 文件边界（默认） | 常规实施 | 软隔离（git diff 检查交叉） |
+> | worktree 隔离 | 大改/高风险 | 硬隔离（独立 git worktree） |
+>
+> worktree 模式由 Lead Agent 判定启用。
+
+### 3.3 审计归因（ADD-7）
+
+| 动作 | 归因规则 |
+|------|---------|
+| `record_dev_operation` | 专家用自己 planKeyword 落库 |
+| hook 事件 | 专家绑定的 planKeyword 写入 |
+| 审计查询 | `query_audit_logs({ planKeyword: "<子Plan>" })` 分桶检索 |
+| HITL 审批 | 子 Plan 级走子 Plan 审批；跨 Plan 决策走总控审批 |
+
+### 3.4 完成判定——必填
+
+| 专家 | 完成标志 |
+|------|---------|
+| {专家 1} | {可验证的完成条件} |
+| Lead | {总控 checklist 全过 + DPS ≥ 80 → 白皮书/最终产物} |
+
+### 3.5 冲突仲裁流程
+
+```
+专家 A 需要触碰专家 B 的边界文件
+  → 记录请求（planKeyword=总控，action=BOUNDARY_REQUEST）
+  → Lead Agent 裁决（同意/拒绝/改道）
+  → 裁决结果 record_dev_operation 落库
+  → 专家 A 按裁决执行
+```
+
+### 3.6 契约自身 HITL 审批配套——必填
+
+> 契约是文档类型，不是实施 Plan——但契约变更（参与者/边界/触发条件）直接影响并行秩序，必须走 HITL 审批。
+
+| 项 | 设计 |
+|----|------|
+| 审批类型 | `HitlType` 扩展 `COLLAB_CONTRACT`（与 PLAN/PLAN_REVIEW 并列） |
+| 审批对象 | 契约文件 + 变更 diff（参与者/能力矩阵/文件边界/依赖拓扑） |
+| 发起时机 | 契约新建 / 契约重大变更（参与者增减、边界重划、触发条件变更） |
+| round 机制 | 复用 HitlRecord.round（同一契约多次变更递增 round） |
+| 与子 Plan 审批关系 | 契约审批是**总控级**（planName=总控 Plan）；子 Plan 审批独立进行（互不阻塞） |
+| 哨兵 | `.qoder/hitl/.tongyi-{contractName}`（复用现有哨兵机制） |
+| 审计 | 契约审批记录入 HitlRecord（type=COLLAB_CONTRACT）→ query_audit_logs 可查 |
+
+---
+
+## 四、Task 映射（契约 ↔ 子 Plan）
+
+| 契约 Task | 子 Plan Task | 专家 | 触发 |
+|-----------|-------------|------|------|
+| CT-1 {描述} | {子 Plan Task} | {专家} | {触发条件} |
+
+---
+
+## 五、验收标准
+
+- [ ] Lead Agent 按触发条件正确拉起全部专家（无提前/无遗漏）
+- [ ] 各方文件边界零冲突（git diff 无交叉）
+- [ ] 审计分桶正确（query_audit_logs 按 planKeyword 各查各的）
+- [ ] 边界仲裁有记录（BOUNDARY_REQUEST 事件可查）
+- [ ] 全部专家完成判定达标 → 总控 DPS ≥ 80 → 最终产物产出
+
+---
+
+## 六、关联文档
+
+| 文档 | 路径 |
+|------|------|
+| 总控 Plan | `{路径}` |
+| 子 Plan 1..N | `{路径}` |
+| 平台文档 | {官方能力依据 URL} |
+
+---

package/templates/core/templates/collab-contract-template.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "collab-contract-template",
+  "description": "ADD 范式并发协作契约模板（多智能体协作规则集）",
+  "type": "object",
+  "required": ["contractName", "participants", "stages", "fileBoundaries", "auditAttribution", "completionCriteria"],
+  "properties": {
+    "contractName": {
+      "type": "string",
+      "description": "契约名称：{需求域名}-{核心内容}-collab-contract-v{版本号}"
+    },
+    "participants": {
+      "type": "array",
+      "description": "参与者（Lead Agent + 自定义专家）",
+      "items": {
+        "type": "object",
+        "required": ["role", "platformEntity", "boundPlan", "responsibility", "planKeyword", "description"],
+        "properties": {
+          "role": { "type": "string", "description": "角色：Lead Agent / 专家 N" },
+          "platformEntity": { "type": "string", "description": "平台实体（主智能体/自定义子智能体）" },
+          "boundPlan": { "type": "string", "description": "绑定的子 Plan 名称" },
+          "responsibility": { "type": "string", "description": "职责描述" },
+          "planKeyword": { "type": "string", "description": "审计归因 planKeyword" },
+          "description": { "type": "string", "description": "Subagent 触发匹配描述（平台自动委派依据）" }
+        }
+      }
+    },
+    "contractRole": {
+      "type": "object",
+      "description": "Plan 主/从角色（§3.6）：MASTER=总控 / SUB=子 Plan",
+      "properties": {
+        "masterPlan": { "type": "string", "description": "总控 Plan 名称（ContractRole=MASTER）" },
+        "subPlans": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "子 Plan 名称列表（ContractRole=SUB）"
+        }
+      }
+    },
+    "hitlApproval": {
+      "type": "object",
+      "description": "契约自身 HITL 审批配套（§3.6）",
+      "properties": {
+        "type": { "type": "string", "enum": ["COLLAB_CONTRACT"] },
+        "triggerTiming": { "type": "string" },
+        "sentinelPath": { "type": "string" }
+      }
+    },
+    "abilityMatrix": {
+      "type": "object",
+      "description": "能力矩阵（§2.1）：每个专家的能力边界",
+      "additionalProperties": {
+        "type": "object",
+        "description": "能力 → 各专家是否具备",
+        "additionalProperties": { "type": "boolean" }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "description": "触发条件表（§3.1）：阶段/专家/触发条件/并行度",
+      "items": {
+        "type": "object",
+        "required": ["stage", "expert", "trigger", "parallelism"],
+        "properties": {
+          "stage": { "type": "string", "description": "阶段标识（A/B/C/D）" },
+          "expert": { "type": "string", "description": "执行的专家" },
+          "trigger": { "type": "string", "description": "触发条件（前置依赖/无依赖）" },
+          "parallelism": { "enum": ["parallel", "serial"], "description": "并行度" }
+        }
+      }
+    },
+    "dependencyGraph": {
+      "type": "string",
+      "description": "依赖拓扑 ASCII 图（§3.1.1）"
+    },
+    "dependencyDeclarations": {
+      "type": "array",
+      "description": "机器可读依赖声明（§3.1.1）",
+      "items": { "type": "string", "description": "如：依赖: 专家2 → { 专家1产出 }" }
+    },
+    "fileBoundaries": {
+      "type": "array",
+      "description": "文件边界（§3.2）：防冲突硬约束",
+      "items": {
+        "type": "object",
+        "required": ["expert", "exclusiveDomain", "forbidden"],
+        "properties": {
+          "expert": { "type": "string" },
+          "exclusiveDomain": { "type": "string", "description": "独占文件域" },
+          "forbidden": { "type": "string", "description": "禁改域" },
+          "isolationMode": { "type": "string", "enum": ["file", "worktree"], "description": "隔离模式：file=文件级独占 / worktree=工作树级隔离" }
+        }
+      }
+    },
+    "auditAttribution": {
+      "type": "object",
+      "description": "审计归因（§3.3）",
+      "properties": {
+        "recordDevOperation": { "type": "string" },
+        "hookEvents": { "type": "string" },
+        "auditQuery": { "type": "string" },
+        "hitlApproval": { "type": "string" }
+      }
+    },
+    "completionCriteria": {
+      "type": "object",
+      "description": "完成判定（§3.4）",
+      "additionalProperties": {
+        "type": "string",
+        "description": "专家 → 可验证的完成标志"
+      }
+    },
+    "taskMapping": {
+      "type": "array",
+      "description": "Task 映射（§四）",
+      "items": {
+        "type": "object",
+        "required": ["contractTask", "subPlanTask", "expert", "trigger"],
+        "properties": {
+          "contractTask": { "type": "string" },
+          "subPlanTask": { "type": "string" },
+          "expert": { "type": "string" },
+          "trigger": { "type": "string" }
+        }
+      }
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "description": "验收标准（§五）",
+      "items": { "type": "string" }
+    }
+  }
+}