docs(adr): 记录场景分诊、Research 子 agent 与技能隔离架构决策

- 新增 ADR 0009：场景分诊编排、独立 @researcher、permission.skill 技能隔离
- architecture.md：Agent 团队 5→6（新增 @researcher）、权限矩阵加技能列、
  dev-lifecycle 编排补 Phase 0 场景分诊、安全性补技能隔离

Author: devcxl

docs/adr/2026-08-06-scenario-dispatch-and-research.md

@@ -0,0 +1,41 @@
+# ADR 0009: 场景分诊编排、Research 子 agent 与子 agent 技能隔离
+
+**状态:** Accepted（2026-08-06）
+**日期:** 2026-08-06
+**上级:** [ADR 0002](/adr/0002-adopt-thin-workflow-kernel)（薄工作流内核 / 纯 Prompt + goal 架构）
+
+## 背景
+
+opencode-cabbage 的 `@dev-lifecycle` 是一条**单线、面向新功能开发**的流水线（`setup → requirements → design → tasks → code → review → release`），对 Bug 修复、紧急修复（hotfix）、业务调整、重构、技术债、基础设施、文档、回滚等常见场景强制套用重量模型，适用性不足。同时：
+
+- `flow-requirements` 的决策映射定义了 `Research` 型 Ticket，但**无执行者**，调研落空。
+- 子 agent（architect/developer/reviewer/goal-verify）可加载**任意** skill，无职责边界，易越权加载无关技能。
+- 需求 / 设计阶段如需技术可行性调研，无专门承接。
+
+## 决策
+
+采用「场景分诊编排 + 独立 Research 子 agent + 子 agent 技能隔离」架构：
+
+1. **`dev-lifecycle` 升级为场景分诊编排器**：新增 **Phase 0 场景分诊**，内联权威路由表（新功能 / Bug 修复 / 紧急修复 / 业务调整 / 重构 / 技术债 / 基础设施 / 文档 / 回滚 / 调研），按输入特征分派到「完整功能流」或「轻量路径」；轻量路径复用 `flow-tdd`/`flow-code`/`flow-review`/`flow-release` 与 goal 工具，跳过 requirements/design/tasks 重量模型。
+2. **新增 `@researcher` 子 agent + `flow-research` skill**：独立承接 Research 型 Ticket 与调研场景，产出 `docs/dev/research/<topic>.md`；方法论融合 `research`（后台核查、一手来源）、`deep-research`（迭代深化、来源评分、反方搜索、置信度、元评审）、`deep-thinking`（决策自检）。
+3. **异常处理接入 `@deep-think` 升级**：Task 失败重试 3 次后、以及连续 continuation 无可验证进展时，先派发更强模型系统审视根因与替代方案，再 Pause 求助。
+4. **子 agent 技能隔离**：通过 OpenCode agent `permission.skill`（模式→动作）默认 `deny` 全部 skill，仅放行各自归属技能；`tools` 布尔已废弃，改用 `permission.skill`。
+5. **非功能场景 SOP 文档化**：写入 `docs/guides/sops/`（一场景一文档），作为人工参考，**不随插件分发**；运行时权威分派逻辑在 `dev-lifecycle` Phase 0。
+
+## 备选方案
+
+| 方案 | 说明 | 否决理由 |
+|------|------|---------|
+| 新增独立 primary 路由器 agent | 由 `@flow-router` 判断输入并转发 | 每会话仅一个 primary 槽位，新增产生入口歧义；分诊本质是决策，作为 dev-lifecycle 首个 Phase 更自然 |
+| Research 并入 `@architect` | 不加新 agent，architect 加载调研 skill | 用户明确要求独立 Research subagent；调研与设计职责分离更清晰 |
+| 用 agent `tools` 布尔限制技能 | `tools: { "<skill>": false }` | schema 标注 `tools` 已废弃，官方改推 `permission` 字段；且 `permission.skill` 支持模式匹配更精确 |
+| 一 SOP 一 skill 全量实现 | 为 hotfix/docs/rollback 也建独立 skill | YAGNI：这些场景由编排 + 复用现有 skill 足够，单独建 skill 过度设计 |
+
+## 后果
+
+- **正向**：开发生命周期从「仅功能流」扩展为「多场景 + 轻重两级」，常见非功能场景有明确路径。
+- **正向**：Research 型 Ticket 有独立执行者，调研产出结构化、可追溯。
+- **正向**：子 agent 职责边界清晰，技能隔离降低越权加载与上下文污染。
+- **风险**：`permission.skill` 依赖 OpenCode 运行时的 skill→模式匹配语义，弱模型可能绕过——缓解：prompt 内显式声明技能归属 + prompt-lint 校验资产一致性。
+- **风险**：新增 Research 能力后 skill 由 8 → 9，需同步更新收敛测试——缓解：`test/skills.test.ts` 已更新期望清单。
+- **风险**：场景分诊依赖模型判断输入类型，可能误判——缓解：无法确定时暂停询问用户，不擅自选择。

docs/guides/architecture.md

@@ -22,9 +22,9 @@
 │  └───────────────────────────────────────────────────────┘  │
 │                                                             │
 │  ┌───────────────────────────────────────────────────────┐  │
-│  │           Agent 团队 (5 agents)                        │  │
+│  │           Agent 团队 (6 agents)                        │  │
 │  │  @dev-lifecycle → @architect → @developer             │  │
-│  │                    → @reviewer → @goal-verify          │  │
+│  │     → @reviewer → @researcher → @goal-verify          │  │
 │  └───────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -90,6 +90,7 @@ setup → requirements → design → tasks → code → review → release（
 
 - **primary 编排器（dev-lifecycle）** 全权：直接执行 push/PR/merge 等高险命令
 - **子 agent 只读/受限**：architect 只写 docs；developer 只在 worktree 内开发不 push；reviewer 只读；goal-verify 只读 + 测试（deny publish）
+- **子 agent 技能隔离**：`permission.skill` 默认 `deny` 全部 skill，仅放行各自归属技能（architect→design/tasks；developer→code/tdd；reviewer→review；researcher→research；goal-verify 无）
 - 复用宿主 `gh auth`，不建设第二套凭据
 
 ### Project Context 注入
@@ -147,9 +148,10 @@ setup → requirements → design → tasks → code → review → release（
 
 ### dev-lifecycle 自动编排
 
-需求确认后，`@dev-lifecycle` 一条命令跑完 `design → tasks → code → review`：
+`@dev-lifecycle` 先做 **Phase 0 场景分诊**，按输入选择路径（功能流或轻量路径，路由表见 `assets/agents/dev-lifecycle.md`），再按路径编排；功能流一条命令跑完 `design → tasks → code → review`：
 
 ```
+0. Phase 0: 场景分诊 → 功能流继续下方；非功能路径（修复/hotfix/业务调整/重构/技术债/基础设施/文档/回滚/调研）按轻量路径执行
 1. goal({op:"create", parent_issue_number}) → 读取 Parent Issue 目标
 2. Phase 1: 委派 @architect 出方案 + ADR → 分支 + PR 合入（设计基线）
 3. Phase 2: 委派 @architect 拆 DAG → gh issue create 建 Sub Issues
@@ -163,6 +165,9 @@ setup → requirements → design → tasks → code → review → release（
        → git worktree remove（脏目录提示人工处理）
 5. Phase 4: 确认全部合并 → 派 @goal-verify 独立验证
 6. goal-verify 验证通过 → goal({op:"complete"})
+
+调研等非功能场景：派发 `@researcher` 加载 `flow-research` 产出 `docs/dev/research/<topic>.md`；
+异常处理在重试后先派发 `@deep-think`（更强模型）系统审视，再 Pause 求助。
 ```
 
 关键机制：
@@ -173,13 +178,14 @@ setup → requirements → design → tasks → code → review → release（
 
 ### Agent 权限矩阵
 
-| agent | bash | edit/write | 职责 |
-|-------|------|-----------|------|
-| `dev-lifecycle` | 全部 allow | 全权 | 编排一切（push/PR/merge/worktree） |
-| `architect` | 只读查询 | 只写 docs/assets | 方案、ADR、DAG 拆解 |
-| `developer` | 只读查询 | 全权（worktree 内） | TDD 实现 |
-| `reviewer` | 只读查询 | 只读 | 双轴审查 |
-| `goal-verify` | 查询 + 测试，deny publish | 只读 | 独立验证 + goal complete |
+| agent | bash | edit/write | 技能(skill) | 职责 |
+|-------|------|-----------|------|------|
+| `dev-lifecycle` | 全部 allow | 全权 | 全部 | 编排一切（push/PR/merge/worktree） |
+| `architect` | 只读查询 | 只写 docs/assets | flow-design, flow-tasks | 方案、ADR、DAG 拆解 |
+| `developer` | 只读查询 | 全权（worktree 内） | flow-code, flow-tdd | TDD 实现 |
+| `reviewer` | 只读查询 | 只读 | flow-review | 双轴审查 |
+| `researcher` | 只读 + 网络读取(curl) | 只写 docs/dev/research | flow-research | 调研、事实核查 |
+| `goal-verify` | 查询 + 测试，deny publish | 只读 | 无 | 独立验证 + goal complete |
 
 ## 事件驱动
 
@@ -227,6 +233,7 @@ Continue working.
 - 只有 `@goal-verify` 可以 complete goal（goal.ts 内置授权）
 - goal-verify 为只读验证 agent（bash deny publish）
 - 子 agent 无高险写权限：developer 不 push、reviewer 只读、architect 只写 docs
+- 子 agent 技能隔离：`permission.skill` deny 非归属 skill，防越权加载与上下文污染
 - worktree 销毁前检查干净状态；脏目录不自动删除
 
 ## 依赖关系