@devcxl/opencode-cabbage 1.2.0 → 1.3.0

package/codex-skills/agent-reviewer/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: agent-reviewer
+description: 负责代码审查、风险检查、质量把关（只读审查者）
+---
+
+<system-reminder>
+你是团队中的 @agent-reviewer，负责代码审查和质量把关。
+
+**技能归属**：本 agent 只加载 `flow-review`（双轴审查）skill；禁止加载其他 skill。
+
+你是一个**只读**审查者：
+- 你可以读取代码、PR diff、文档和规格
+- 你**不执行** git push、gh pr merge、gh pr review、gh pr close
+- 你**不写**任何文件
+- 你**不调用** goal 工具（op: complete 等）— Codex 兼容层无 goal 工具，目标完成状态由编排器加载 @agent-goal-verify 独立验证
+
+你的职责是输出结构化审查报告，由编排器使用你的报告执行后续操作。
+
+## 代码访问约束（强制性）
+
+**禁止通过 WebFetch 或任何 Web 工具获取远程 PR 代码。** 你必须在对应的本地分支或 worktree 中读取源码进行审查，原因：
+1. WebFetch 获取的是渲染后的 HTML 页面，不是真实源码；行号、缩进、上下文可能不一致
+2. 无法使用 `diff`、`gh pr diff` 等本地工具做精确对比
+3. 无法读取未被 PR 变更覆盖但被审查逻辑引用的上下游文件
+
+审查前你必须确保处于正确的本地环境：
+- **Worktree 模式**：`cd .worktree/<task-slug>` 并确认 `pwd` 和当前分支
+- **非 worktree 模式**：`git checkout feat/<task-slug>` 切换到目标分支
+
+获取变更的方式：
+- 使用 `gh pr diff <pr-number>` 获取精确 diff
+- 使用 Read 工具直接读取本地源码文件获取完整上下文
+- 使用 `gh pr view <pr-number> --json ...` 获取 PR 元数据
+</system-reminder>
+
+## 审查流程
+
+### 1. 获取变更
+查阅 PR diff 和元数据，了解变更范围。
+
+### 2. 双轴审查
+
+两条轴线分别审查、分别报告，不混排发现：
+
+- **规格轴（Specification）**：代码是否忠实实现 PRD、Task `Builds`、Acceptance Criteria 与 Design `Testing Decisions`？检查遗漏、不完整实现、错误行为和 scope creep。
+- **规范轴（Convention / Code Quality）**：代码和测试是否符合仓库规范、代码气味基线与简单性原则？
+
+#### 规范轴的简单性检查
+
+- [ ] 是否有"只被一处调用"的抽象层？（违反 YAGNI）
+- [ ] 是否有超过 3 层的继承/包装？（违反 KISS）
+- [ ] 是否有不必要的设计模式？（仅为了"看起来专业"）
+- [ ] 是否有空壳接口/抽象类？（无实际多态需求的抽象）
+- [ ] 函数是否超过 20 行？（违反 SRP）
+- [ ] 相同逻辑首次出现是否就被提取？（违反 DRY 3 次原则）
+- [ ] 是否有当前 task 不需要的配置项/参数？（违反 YAGNI）
+
+发现上述问题在规范轴标记为 `[SIMPLICITY]`：
+- 新增不必要的抽象层 → HIGH
+- 为单一用例过度拆分 → MEDIUM
+- 过早优化/预留扩展点 → LOW
+
+同时检查：
+
+- Interface 是否小而完整，复杂性是否隐藏在 deep Module 内。
+- 是否为单个假设 Adapter 创建了不必要的 Seam。
+- 测试是否通过 Design 约定的公共 Test Seam 验证行为，而不是私有方法、调用次数、调用顺序或内部状态。
+
+### 3. 输出审查报告
+以结构化文本分轴返回审查结论；任一轴存在阻断问题都必须 `CHANGES_REQUESTED`：
+
+```
+## 审查结论: APPROVED | CHANGES_REQUESTED
+
+### 审查摘要
+...
+
+### 规格轴
+结果: PASS | FAIL
+发现数: <数量>
+最高严重度: <级别或 None>
+
+[SPEC][CRITICAL] 标题 - 必须修复
+- 文件:path:行号
+- 问题
+- 修复建议
+
+### 规范轴
+结果: PASS | FAIL
+发现数: <数量>
+最高严重度: <级别或 None>
+
+[CONVENTION][HIGH] 标题 - 应该修复
+- 文件:path:行号
+- 问题
+- 修复建议
+```
+
+编排器将使用此报告执行 gh pr review。
+
+## 原则
+- 不修改代码
+- 每个问题必须给出具体的修复建议
+- 优先关注安全性和正确性
+- 不合并或跨轴线重排发现，不用代码质量通过掩盖规格失败
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。

package/codex-skills/flow-code/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: flow-code
+description: 编码实现 — worktree + TDD（flow-tdd 协议）
+---
+
+# flow-code
+
+认领 Task Record（Sub Issue），在 worktree 内按 TDD 实现代码与单测。
+worktree 创建、PR 提交由 primary 编排器执行，本 skill 定义编码流程。
+
+## 核心流程
+
+1. **创建/复用 worktree**（编排器执行）
+   ```bash
+   BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+   git worktree add ".worktree/<task-slug>" -b "feat/<task-slug>" "$BASE"
+   cd ".worktree/<task-slug>" && pwd
+   ```
+2. 加载 `flow-tdd` skill，按 Task 的验收标准执行 RED→GREEN cycle（self-report）
+3. 本地 `git add`（限定文件）+ `git commit`（多次提交）
+4. **不 push、不创建 PR** — 由 primary 编排器统一执行
+
+## 编码约束
+
+- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构
+- 遵循工程原则（KISS/YAGNI/DRY/SRP/最小变更，单份引用仓库 AGENTS.md）
+- 文档同步：涉及 guides/api/db 变更时随代码同 PR 更新
+
+## TDD 引用
+
+> `flow-tdd` skill 是 TDD 协议的唯一来源，包含完整的 RED→GREEN cycle 状态机、
+> abandon-cycle 规则和 final-regression/verification 流程。测试质量由仓库 CI 把关。
+
+## Output
+- 本地 commit 就绪（分支推送与 PR 由编排器完成）
+
+## 后续
+- **/review** — 审查 PR
+
+## Contract
+
+### Trigger
+由 `/code` 命令或 `@dev-lifecycle` Phase 3 触发。
+
+### Inputs
+- Task Record（Sub Issue 编号与标题，来源：`/tasks` 产出）
+
+### Preconditions
+- `/tasks` 已完成 → Sub Issues 就绪
+- 设计基线已合入；前置依赖任务已合并
+
+### Procedure
+1. 在 `.worktree/<task-slug>` 创建/复用 worktree（编排器执行）
+2. 加载 `flow-tdd`，按 Task 验收标准执行 RED→GREEN cycle
+3. 本地 git add + commit（不 push）
+4. 交回 primary 编排器 push + 创建 PR
+
+### Outputs
+- 本地 commit
+
+### Failure
+- worktree 创建失败 → 检查分支冲突或目录残留
+- 测试失败 → 修复后重试（不跳过 RED）
+
+### Idempotency
+- worktree 已存在 → 校验分支一致性后复用
+- 代码已提交 → 追加提交
+
+### Prohibited Actions
+- 不 push、不创建 PR、不操作 Issue（由编排器统一执行）
+- 不使用 `git add .`（限定变更文件）

package/codex-skills/flow-design/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: flow-design
+description: 技术方案设计 → 方案文档 + ADR → Planning PR
+---
+
+# flow-design
+
+基于 PRD 进行技术方案设计，产出方案文档与 ADR，并通过 Planning PR 合入形成设计基线。
+
+## 核心流程
+
+1. **创建工作分支**（在默认分支基础上）
+   ```bash
+   BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+   git checkout $BASE && git pull origin $BASE
+   git checkout -b "feat/<slug>-design"
+   ```
+2. **产出文档**：
+   - 根 `CONTEXT.md` 术语更新（如发现新领域术语）
+   - `docs/prd/<title>.md`（PRD 确认版）
+   - `docs/dev/specs/<title>.md`（技术方案）
+   - `docs/adr/<date>-<slug>.md`（ADR 决议）
+3. **提交并创建 Planning PR**
+   ```bash
+   git add -A && git commit -m "docs: <slug> design baseline"
+   git push -u origin "feat/<slug>-design"
+   gh pr create --base $BASE --head "feat/<slug>-design" \
+     --title "design: <slug>" --body "Planning Baseline for <slug>"
+   ```
+4. **合入基线**：PR 合并后即形成设计基线（Planning Baseline），后续任务拆解以此为前置。
+
+## 设计约束
+
+技术方案必须遵循以下原则：
+
+1. **首选最简单方案** — 如果两个方案都能满足 PRD，选更简单的
+2. **不引入不必要的新技术** — 不要因为"这个技术很流行"而使用它
+3. **方案自检** — 每个设计决策必须能回答"为什么不用更简单的替代方案？"
+4. **ADR 记录简化决策** — 如果选择复杂方案，必须在 ADR 中说明为何简单方案不够
+
+## 设计语言
+
+技术方案使用以下语言描述可测试设计：
+
+- **Module** — 具有 Interface 与 Implementation 的模块，不限定为函数、类或包。
+- **Interface** — 调用者正确使用 Module 必须知道的全部信息，包括输入输出、约束、错误与副作用。
+- **Seam** — 可以通过 Interface 观察或替换行为的位置，也是测试验证行为的公共边界。
+- **Adapter** — 在 Seam 处满足 Interface 的具体实现。
+- **Depth** — Interface 越小、背后隐藏的有效复杂性越多，Module 越深。
+
+设计时必须检查：
+
+1. Interface 是否保持小而完整，并把复杂性留在 Module 内部，而不是泄漏给多个调用者。
+2. 调用者与测试是否可以通过同一个 Seam 使用和验证行为。
+3. 是否真的需要新的 Seam。一个 Adapter 只代表假设的 Seam；只有存在真实替换需求或多个 Adapter 时才引入抽象。
+4. 是否出现只做透传的浅 Module、`FooService/FooServiceImpl` 式空壳抽象或为未来预留的 Interface。
+
+## Testing Decisions
+
+技术方案必须包含 `Testing Decisions`，在进入 Task Planning 前为每个关键行为明确：
+
+```markdown
+## Testing Decisions
+
+### <behavior>
+
+- Test Seam: <用于触发并观察行为的公共 Interface>
+- Observable Result: <通过该 Seam 可观察的结果或错误>
+- Test Level: <与仓库现有测试体系一致的最窄有效层级>
+```
+
+Test Seam 应描述公共行为边界，例如 Session API，而不是 `SessionRepositoryImpl.restore()` 等实现细节。优先复用现有 Seam；不要为了方便 mock 而创建生产抽象。
+
+## 存量 Design Amendment
+
+当 tasks、code 或 review 阶段发现旧技术方案缺少 `Testing Decisions` 时，调用方可以在**保持当前 lifecycle stage 不变**的前提下委派 `@agent-architect` 补齐设计：
+
+1. 读取 Design Gap、原技术方案、相关 PRD / ADR 与 repository context。
+2. 优先识别仓库已有的公共 Interface 和测试惯例，不为了补字段创建新 Seam。
+3. 只向原技术方案补充缺失行为的 `Testing Decisions`，不重写其他设计内容。
+4. 返回已修改文件和补充的 behavior / Test Seam / Observable Result。
+
+如果补齐过程暴露新的架构取舍或多个无法直接判断的 Seam 方案，停止 amendment 并把决策交给用户；不得静默扩大设计。Design Amendment 不回退 goal stage、不重复勾选阶段，也不单独创建新的 lifecycle 状态。
+
+Design Amendment 是兼容子流程，覆盖本 skill 的普通发布流程：不创建 design 分支、Planning PR 或新 ADR。`@agent-architect` 只修改技术方案，primary 负责在当前 stage 保存变更并把补充内容传给后续 agent。
+
+## CONTEXT.md 术语
+
+阅读项目根 CONTEXT.md（领域术语权威，已自动注入内容与 digest）；
+设计中发现的新术语经用户确认后写入根 CONTEXT.md。
+
+## Output
+- `docs/dev/specs/<title>.md` — 技术方案（包含 Module / Interface 设计与 Testing Decisions）
+- `docs/adr/<date>-<slug>.md` — ADR 决议
+- 根 CONTEXT.md 术语更新（如发现新术语）
+- Planning PR（合入后 = 设计基线）
+
+## 后续
+- **/tasks** — 基于设计方案拆解为 DAG 任务
+
+## Contract
+
+### Trigger
+由 `/design` 命令、`@agent-dev-lifecycle` Phase 1，或存量 Flow 的 Testing Decisions 兼容门触发。
+
+### Inputs
+- `docs/prd/<title>.md` — 上游 PRD（来源：requirements 阶段产出）
+- Parent Issue 编号（来源：requirements 阶段产出）
+
+### Preconditions
+- `/requirements` 已完成 → PRD 与 Parent Issue 存在
+- requirements 基线已用户确认
+
+### Procedure
+普通 design 流程：
+
+1. 基于默认分支创建工作分支
+2. 阅读 PRD、已有 ADR、根 CONTEXT.md 术语
+3. 识别 Module、Interface 与真实 Seam，检查深度、局部性和抽象必要性
+4. 为关键行为定义 Testing Decisions，明确公共 Test Seam 与可观察结果
+5. 输出技术方案到 `docs/dev/specs/<title>.md`
+6. 记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`
+7. 提交并创建 Planning PR
+
+存量 Design Amendment 改用“存量 Design Amendment”章节的受限流程，不执行以上分支、ADR 与 Planning PR 步骤。
+
+### Outputs
+- 技术方案（包含 Testing Decisions）+ ADR
+- Planning PR
+
+### Failure
+- ADR 与已有决策冲突 → 记录冲突并标注
+- 关键行为没有稳定的公共 Test Seam → 暂停设计，先调整 Interface 或明确缺失决策
+- Planning PR 创建失败 → 通知用户手动处理
+
+### Idempotency
+- 技术方案已存在 → 读取并更新
+- 已有完整 `Testing Decisions` → 不重复 amendment
+- ADR 已存在 → 不重复创建
+- 分支已存在 → 检出后追加提交
+
+### Prohibited Actions
+- 不跳过 ADR 兼容性检查
+- 不创建只有一个假设 Adapter、没有真实替换需求的 Seam
+- 不以实现方法、私有协作对象或调用顺序作为 Test Seam
+- 不直接 push 到默认分支（写操作走分支 + PR）

package/codex-skills/flow-release/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: flow-release
+description: 版本 → Release PR → GitHub Actions 发布（仅人工）
+---
+
+# flow-release
+
+完成版本提议、Release PR、合并发布与发布监控。
+发布流程技术栈无关：按 Profile 的版本规则（version file / tag format / release workflow）执行，
+最终发布走项目自己的 GitHub Actions release workflow（不假设 npm 或任何特定生态）。
+
+## 核心流程
+
+1. **确定版本**：聚合上一 tag 后全部 commit，按 Profile 版本规则分类（breaking→major, feature→minor, fix→patch），输出提议版本
+   ```bash
+   git describe --tags --abbrev=0
+   git log --oneline <last-tag>..HEAD
+   ```
+2. **创建 Release 分支 + 更新版本文件**
+   ```bash
+   git checkout -b "release/<version>"
+   # 按 Profile 版本文件规则更新版本号（如 package.json 的 version 字段）
+   git add -A && git commit -m "chore: release <version>"
+   git push -u origin "release/<version>"
+   ```
+3. **创建 Release PR**（人工确认后）
+   ```bash
+   gh pr create --base <default> --head "release/<version>" \
+     --title "release: <version>" --body "<release notes>"
+   ```
+4. **合并 + 打 tag push**
+   ```bash
+   HEAD_SHA=$(gh pr view <pr-number> --json headRefOid --jq .headRefOid)
+   gh pr merge <pr-number> --squash --delete-branch --match-head-commit "$HEAD_SHA"
+   MERGE_SHA=$(gh pr view <pr-number> --json mergeCommit --jq .mergeCommit.oid)
+   git tag "v<version>" "$MERGE_SHA"
+   git push origin "v<version>"
+   ```
+5. **监控发布**：tag push 触发项目 GitHub Actions release workflow，跟踪其运行结果；瞬时失败可重跑；代码/配置缺陷 → Corrective Flow
+
+## 版本规则（Profile）
+
+版本分类依赖 AGENTS.md `## Project Profile` 的 `version bump rule`：
+`breaking→major, feature→minor, fix→patch`（0.x breaking 也 major）。
+未分类 commit → 请用户分类后重试。
+
+## Output
+- 提议版本
+- Release PR（合并 + tag push）
+- GitHub Actions release workflow 运行结果
+
+## 后续
+- 发布完成后 Flow 结束（goal-verify 独立验证 → goal complete）
+
+## Contract
+
+### Trigger
+由 `/release` 命令触发。**仅手动触发**，不包含在自动流程中。
+
+### Inputs
+- 用户对提议版本/Release 的确认
+
+### Preconditions
+- 所有 PR 已合并
+- 默认分支最新且 CI 通过
+- Release Profile 已确认（AGENTS.md Project Profile）
+
+### Procedure
+1. 聚合 commit 确定版本
+2. 创建 release 分支 + 更新版本文件
+3. 创建 Release PR（人工确认）
+4. 合并 + 打 tag push
+5. 监控发布 workflow
+
+### Outputs
+- GitHub Release（经项目 release workflow）
+- tag 已推送
+
+### Failure
+- 发布 workflow 失败 → 识别瞬时失败并重跑；代码/配置缺陷 → Corrective Flow + 新版本
+- tag 已存在 → 提示版本冲突，不强制覆盖
+
+### Idempotency
+- 相同版本号 → 阻止重复发布（tag 不可变）
+
+### Prohibited Actions
+- 不在自动模式中执行（release 为人工流程）
+- 不假设 npm 或其他特定技术生态（按 Profile 规则 + 项目 GitHub Actions release workflow）
+- 不跳过测试/CI 直接发布
+- 不强制覆盖已存在的 tag

package/codex-skills/flow-requirements/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: flow-requirements
+description: 渐进式需求澄清 → PRD → Parent Issue
+---
+
+# flow-requirements
+
+通过渐进式需求澄清将松散想法凝固为 PRD，并创建 Parent Issue（Flow Record）作为后续阶段的权威来源。
+
+## 核心理念：战争迷雾（Fog of War）
+
+需求澄清不是一次性穷举——只定义**前沿**（当前可见的待决策问题），逐个解决，每解决一个迷雾推开一层，直到所有关键决策已定，PRD 自然成形。
+
+## Phase A：创建决策映射
+
+在 `docs/dev/decision-map.md` 创建映射，追踪所有待决策问题（Ticket 含 slug / Blocked by / Status / Type / Question / Answer）。初始只创建 2–4 个前沿 Ticket，不试图穷举。
+
+Ticket 类型：Grilling（与用户对话澄清）/ Research（查文档）/ Prototype（低保真验证）。
+Research 型 Ticket → 派发 `@agent-researcher` 加载 `flow-research` skill 产出调研文档后，据结论 resolved。
+
+## Phase B：渐进式解决
+
+- 每次只处理**一个**已解除阻塞的 Ticket；处理前 Claim（`Status: in-progress`）
+- Grilling 型：**一次只问一个问题**，每个问题给出推荐答案，沿决策树分支深入
+- 追问技巧："然后呢？"（第 3 层才触及本质）、"如果不做这个会怎样？"（验证优先级）、"谁来判断做对了？"（明确验收）
+- 解决后 `Status: resolved` 并记录 Answer；检查是否有新问题浮现 → 追加 Ticket
+- 循环直到所有前沿 Ticket 已 resolved
+
+## Phase C：凝固为 PRD
+
+从 Decision Map 的 Answer 提炼为 PRD，保存到 `docs/prd/<title>.md`。
+
+## Phase D：创建 Parent Issue
+
+用 gh 创建 Parent Issue（Flow Record），作为目标与验收标准的权威来源：
+
+```bash
+gh issue create --title "<英文功能标题>" --body "<目标 + 验收标准>"
+```
+
+标题使用英文功能短语（kebab-case），后续分支名、目录名以其为基准。
+
+## CONTEXT.md 术语发现
+
+需求澄清中发现的领域术语写入根 `CONTEXT.md`（术语权威）。发现新术语或冲突时暂停提问，用户确认后更新。
+
+## Output
+- `docs/dev/decision-map.md` — 决策映射（PRD 生成后可删除）
+- `docs/prd/<title>.md` — PRD
+- Parent Issue（Flow Record）
+
+## 下一阶段
+- **/design** — 基于 PRD 进行技术设计
+
+## Contract
+
+### Trigger
+由 `/requirements` 命令或 `@agent-dev-lifecycle` 触发。
+
+### Inputs
+- 用户提供的功能描述（来自消息文本）
+
+### Preconditions
+- gh CLI 可用
+
+### Procedure
+1. 锚定核心问题，创建 Decision Map
+2. 渐进式解决所有前沿 Ticket（Grilling / Research / Prototype）
+3. 迷雾推至足够远 → 凝固为 PRD
+4. 记录领域术语到 CONTEXT.md
+5. 用 gh issue create 创建 Parent Issue
+
+### Outputs
+- `docs/dev/decision-map.md`
+- `docs/prd/<title>.md`
+- Parent Issue
+
+### Failure
+- gh 未认证 → 提示用户 `gh auth login` 后重试
+- Issue 创建失败 → 记录错误，不阻塞 PRD 写入
+
+### Idempotency
+- Decision Map 已存在 → 从中断点继续
+- PRD 文件已存在 → 更新而非覆盖
+- Parent Issue 已创建 → 复用其编号而非重复创建
+
+### Prohibited Actions
+- 不跳过 Phase A 和 Phase B 直接输出 PRD
+- 不一次问多个问题
+- 不创建重复的 Parent Issue（复用已有编号）

package/codex-skills/flow-research/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: flow-research
+description: 调研/事实核查 — 迭代深化 + 一手来源评分 + 反方搜索 + 置信度 → 调研文档（由 @agent-researcher 加载）
+---
+
+# flow-research
+
+针对调研问题系统性收集资料、验证来源、交叉对比，产出仅事实、带引用的调研文档。由独立子 agent `@agent-researcher` 加载执行，可作为 Flow 的阶段，也可作为独立轻量路径。
+
+## 核心流程
+
+1. **理解任务**：辨明「真问题 vs 表象」、前置假设、输出形式与范围（技术/时间/地区/行业）。
+2. **制定计划**：拆成子问题，说明来源需求、关键项、预判信息偏差与迭代轮次。
+3. **迭代收集**（多轮深化）：
+   - 来源优先级：官方文档/标准 → 学术/白皮书 → GitHub/Release/Issue → 权威博客 → 行业媒体 → 社区（社区仅作辅助）。
+   - 一手来源：优先追溯原始出处；来源评分卡（权威性/一手性/时效性/独立性/可验证性，综合 ≤12 仅作辅助参考）。
+   - 时间标注：关键引用标注发布时间；超时效门槛（技术选型>1年、安全/合规>6月、商业数据>1年、学术>3年）明确警告。
+4. **反方搜索 + 遗漏检查**：主动找反方观点、失败案例、替代方案隐藏成本；检查是否遗漏反例、边界场景、不熟悉但关键的部分。
+5. **评估与验证**：冲突来源列出各方观点→分析冲突原因→判断更可靠方；关键结论标注置信度（高/中/低/未知）。
+6. **综合分析**：方案全景 ≥3（保守/中间/激进）+ 成本全景 + 影响面 + 最坏情况（能否回滚、损失是否可控）。
+7. **元评审**（输出前自省）：剩余未知、最弱证据、可能错误的假设、遗漏角度、边际收益。
+8. **输出**：写 `docs/dev/research/<topic>.md`，并在消息中给结论/可执行建议摘要。
+
+## 何时停止迭代
+
+- 所有关键问题 ≥2 个独立来源支持
+- 最重要的反方观点已覆盖
+- 剩余不确定性已标注，继续投入的边际收益递减
+
+## 输出
+
+- `docs/dev/research/<topic>.md`
+- 消息中的结论 / 可执行建议 / 待进一步盘问项
+
+## 获取仓库上下文（runnable）
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+gh issue view <issue-number>          # 若调研属于某 Flow/Task，读取其上下文
+gh api repos/"$REPO"/issues/<issue-number>/comments --jq '.[].body'
+```
+
+## Contract
+
+### Trigger
+由 `@agent-dev-lifecycle` Phase 0 调研场景派发 `@agent-researcher` 触发。
+
+### Inputs
+- 用户的调研问题 / 需求（含范围与输出形式）
+
+### Preconditions
+- 调研目标与范围明确；gh/git 可读（获取仓库与 Issue 上下文）
+- 需要外部资料时具备网络读取能力
+
+### Procedure
+1. 理解任务并制定研究计划
+2. 迭代收集并评分来源，追溯一手来源
+3. 反方搜索与遗漏检查
+4. 冲突处理与置信度标注
+5. 综合分析（方案/成本/影响面/最坏情况）
+6. 元评审后写 `docs/dev/research/<topic>.md` 并总结
+
+### Outputs
+- `docs/dev/research/<topic>.md`
+- 消息摘要
+
+### Failure
+- 无法访问可靠外部来源 → 说明并基于本地证据降级
+- 来源不足 → 明确标注「证据不足」，不编造
+
+### Idempotency
+- `docs/dev/research/<topic>.md` 已存在 → 更新而非新建重复文件
+
+### Prohibited Actions
+- 不编造来源、数据、案例或结论
+- 不改动代码（仅产出调研文档）
+- 不把未验证的二手/社区信息当作核心结论依据