| name | module-implementation-orchestrator |
| description | 模块实现编排器。将功能模块实现拆分为多阶段流水线：先按设计文档优雅实现，再基于接口契约生成对抗性测试进行盲测，最后根据失败摘要迭代修复。
核心特征：信息隔离（实现者不知测试内容，测试者不知实现细节），对抗性验证，渐进收敛。
当用户要求实现模块、将规格落地为代码，或提到"对抗性测试"、"盲测"、"对抗验证"、"渐进式实现"时触发。
|
模块实现编排器
路径分隔符默认为 /，Windows 环境下自行适配为 \。
角色边界（铁律）
你（当前实例）是编排器，不是实现者也不是测试者。所有"写代码/改代码"的工作必须通过 SubAgent 完成。
| 禁止行为 | 原因 |
|---|
| 自己写/改实现代码 | 破坏信息隔离——你知晓测试策略，会无意识"应试编程" |
| 自己生成/修改对抗性测试 | 破坏信息隔离——你知晓实现细节，测试不再客观 |
| 自己修复实现代码 | 同上，修复必须由不知测试内容的 SubAgent 完成 |
| 进入 plan 模式重新规划 | 本 skill 已提供完整流水线，直接执行 |
在 Phase 4 修改 .tmp/adversarial-tests/ 下的测试文件 | 对抗性验证的客观性依赖测试代码不被 orchestrator 污染 |
你必须做的：运行命令、检查结果、协调流程、验证格式、调度 SubAgent。SubAgent 调用统一使用 model: "haiku"。
Phase 4 文件写权限：orchestrator 只能写 failure-summary-round-*.md 和 test-defects-round-*.md。测试代码文件（*.py/*.ts/*.js/*.go）绝对禁止写入。违规即意味着信息隔离崩溃、流程产出不可信，必须中止并报告用户。
设计哲学
通过 "实现 → 对抗 → 修复 → 再对抗" 的循环渐进逼近正确：
- 实现者不应被测试绑架——按设计优雅落地，不必猜测测试意图
- 测试者不应被实现污染——只看接口契约，更容易发现盲点
- 信息隔离保证客观性——双方信息不对称，避免"测试-实现共谋"
- 渐进收敛优于大爆炸——通过有限轮次迭代，逐步消灭漏洞
输入与输出
输入：模块设计文档、落地规范、契约文件（docs/contracts/{module_id}/*.json）、项目结构设计文档、现有代码库路径
输出：新增/修改的源码文件、对抗性测试代码（.tmp/ 隔离目录，不进版本控制）、漏洞发现与修复记录、执行结果汇报（docs/testing-design/{module_id}/adversarial-report.md）
核心流程
Phase 1: 设计解析与环境同步（orchestrator）
↓
Phase 2: 实现落地（SubAgent → adversarial-implementation-executor）
输出：实现代码 + function-signatures.json
↓
Phase 3: 对抗性测试生成（SubAgent → adversarial-test-generator）
输入：契约期望清单 + 函数签名清单（不含实现源码）
输出：对抗性测试代码（隔离目录）
↓
Phase 4: 盲测执行（orchestrator）
运行测试，判定失败类型，生成失败摘要
├─ 全部通过 → Phase 6
├─ 实现漏洞 → Phase 5
└─ 测试缺陷 → 退回 Phase 3 修正 → 重新 Phase 4
↓
Phase 5: 修复迭代（SubAgent → adversarial-implementation-executor）
输入：失败摘要（不含测试代码），最多 3 轮
↓
Phase 6: 完成汇报（orchestrator）
前置步骤：环境同步 + 就绪检查
- 检测 git worktree 状态，同步主分支最新代码
- 检查
docs/ 目录设计文档是否有未同步变更
- 运行就绪检查脚本（推荐）：
python scripts/preflight_check.py --module-id {module_id} --check-sub-skills
此脚本验证 Python 版本、脚本完整性、契约目录存在性、SubAgent skill 可用性。不通过则不得进入 Phase 1。
核心原则
1. 信息隔离
| SubAgent | 禁止接触 |
|---|
| adversarial-implementation-executor (Phase 2/5) | .tmp/adversarial-tests/ 下所有文件、测试运行输出 |
| adversarial-test-generator (Phase 3/4.5.2) | 实现源码文件、实现目录 |
Phase 4 向 Phase 5 传递的失败摘要只含：错误类型、涉及函数/参数、违反的契约条款、修复方向建议。不得含：测试代码、具体输入值、测试文件路径。
2. 对抗优先
对抗性测试的目标是找漏洞，不是验证正确性。聚焦边界破坏、类型破坏、状态破坏。
3. 渐进收敛
不追求一次性消灭所有漏洞。每轮迭代修复部分问题，允许在最大轮次内未完全通过（向用户报告收敛状态）。
4. 契约权威
实现与测试的唯一共同依据是接口契约。若契约本身模糊或矛盾，由用户仲裁，不得让实现者或测试者自行解释。
Phase 1：设计解析与环境同步
1.1 提取接口契约
从 docs/contracts/{module_id}/ 下的 JSON Schema 契约文件和落地规范中提取接口契约。
提取优先级：契约文件（P0）→ 落地规范的类型定义/异常处理/状态机章节（P1）→ 设计文档补充（P2）
详细提取算法（五步骤程序化提取）见 references/contract-extractor.md。
输出：
- 契约期望清单（冻结文件）：
{module_code_dir}/.tmp/adversarial-tests/{module_id}/contract-expectations.md
- 格式：
| 编号 | 契约维度 | 破坏性输入 | 期望行为 | 来源章节 |
- 编号规则：
A01, A02, ...（参数约束）、B01, B02, ...（状态约束）
验证后冻结：
python scripts/validate_contract_expectations.py \
{module_code_dir}/.tmp/adversarial-tests/{module_id}/contract-expectations.md \
--function-signatures {module_code_dir}/.tmp/adversarial-tests/{module_id}/function-signatures.json
验证失败则修正后重试，通过后冻结（后续不得修改，除非用户仲裁）。
1.2 设计文档冲突仲裁
多份文档要求不一致时，按优先级：项目结构设计文档（P0）> 落地规范（P1）> 设计文档（P2）。未覆盖场景（字段未定义、边界值未声明）调用 AskUserQuestion 向用户确认，禁止自行假设。
1.3 输出执行计划预览
向用户展示执行计划（含模块信息、契约条目数、SubAgent 调度计划），用户确认后进入 Phase 2。
Phase 2：实现落地（SubAgent）
调度
调用 Agent 工具，使用 references/subagent-prompts.md 中的模板 1，替换占位符后发送。
关键约束：
subagent_type: "coder"，model: "haiku"- 工作目录排除
{module_code_dir}/.tmp/adversarial-tests/
- 实现代码的外部接口类型必须与契约文件一致，但不得 import 契约文件本身
输出验证
SubAgent 返回后，orchestrator 执行：
python scripts/validate_function_signatures.py \
{module_code_dir}/.tmp/adversarial-tests/{module_id}/function-signatures.json
验证不通过则退回 SubAgent 修正。同时检查 pending-confirmations.md：若无待确认项则进入 Phase 3；存在风险可控项则记录并在 Phase 6 标注；存在重大风险项则暂停流程，调用 AskUserQuestion 确认。
Phase 3：对抗性测试生成（SubAgent）
调度
调用 Agent 工具，使用 references/subagent-prompts.md 中的模板 2。
向 SubAgent 提供：契约期望清单（冻结文件）、函数签名清单（已验证）、落地规范的异常处理/类型定义章节。不提供实现源码和实现目录路径。传递前确认契约期望清单已通过验证。
输出
测试代码存放于 {module_code_dir}/.tmp/adversarial-tests/{module_id}/：
test_{module_id}.adversarial.{ext} — 可直接运行的测试代码{module_id}.adversarial.test.list.md — 测试清单（含破坏意图）
orchestrator 检查文件存在性、语法可解析性、导入路径正确性。发现问题则退回 SubAgent 修正。
Phase 4：盲测执行（orchestrator）
4.1 运行测试
pytest {module_code_dir}/.tmp/adversarial-tests/{module_id}/ -v --tb=short
npx vitest run {module_code_dir}/.tmp/adversarial-tests/{module_id}/
cd {module_code_dir}/.tmp/adversarial-tests/{module_id}/ && go test -v
4.2 判定失败类型（强制分支）
首先使用辅助脚本进行自动分类，然后人工复核：
python scripts/classify_failures.py \
--test-output /tmp/pytest-output.txt \
--framework pytest \
--contract {contract_expectations_path} \
--output /tmp/classification.json
| 失败类型 | 判定标准 | 处理方式 |
|---|
| 实现漏洞 | 错误指向被测函数的行为缺陷（如参数校验缺失、边界未处理） | 生成失败摘要 → Phase 5 |
| 测试代码 bug | 语法错误、导入错误、断言逻辑自相矛盾 | 强制退回 Phase 3 SubAgent 修正（见 4.5） |
| 契约矛盾 | 测试期望与落地规范/契约清单矛盾 | 标记为"测试缺陷"，退回 Phase 3 SubAgent 修正 |
分支逻辑是无选择的强制流程，orchestrator 不得跳过或自行选择路径：
Phase 4.2 判定
├─ 全部通过 → Phase 6
├─ 实现漏洞 → Phase 4.3 生成失败摘要 → Phase 5
└─ 测试缺陷 → 4.5.1 生成缺陷报告 → 4.5.2 调度 SubAgent 修正 → 重新 Phase 4
4.3 生成失败摘要
优先使用自动化脚本：
python scripts/generate_failure_summary.py \
--test-output /tmp/pytest-output.txt \
--framework pytest \
--contract {contract_expectations_path} \
--signatures {function_signatures_path} \
--round {N} --max-rounds 3 \
--output {module_code_dir}/.tmp/adversarial-tests/{module_id}/failure-summary-round-{N}.md
python scripts/validate_failure_summary.py \
{module_code_dir}/.tmp/adversarial-tests/{module_id}/failure-summary-round-{N}.md
失败摘要的精确格式和信息边界规则见 references/failure-summary-format.md。验证脚本确保信息隔离合规——不泄露测试代码、输入值、文件路径。
4.4 回归检查
每轮对比上轮结果，检测退化（上轮通过的用例本轮失败）和收敛停滞（连续两轮失败集合相同）。退化 = 红灯，立即冻结迭代并向用户报告。
4.5 测试缺陷修正（强制子流程）
4.5.1 生成测试缺陷报告
编写纯文本缺陷报告至 {module_code_dir}/.tmp/adversarial-tests/{module_id}/test-defects-round-{N}.md：
## 测试缺陷报告（第 {N} 轮）
#### [缺陷-001] {测试函数名}
- **契约条款**：{§N.N}
- **缺陷类型**：{语法错误 / 导入错误 / 断言逻辑矛盾 / 契约矛盾}
- **期望行为**：{根据契约，测试应该如何断言}
- **修复方向**：{具体修复建议，不含代码}
关键约束：缺陷报告只能描述"问题是什么"和"期望怎么修"，不得包含测试代码片段、具体输入值。
4.5.2 调度 SubAgent 修正测试
调用 Agent 工具，使用 references/subagent-prompts.md 中的模板 3。orchestrator 不得直接修改测试文件。SubAgent 修正完成后，回到 Phase 4 重新运行盲测。
Phase 5：修复迭代（SubAgent）
调度
调用 Agent 工具，使用 references/subagent-prompts.md 中的模板 4。
SubAgent 职责：阅读失败摘要 → 阅读当前实现 → 按契约条款修复。修复策略映射见下表：
| 失败原因 | 修复动作 |
|---|
| 参数未校验 | 添加输入校验（类型检查、非空检查） |
| 边界未处理 | 添加边界检查（范围、长度） |
| 空值未防护 | 添加 None/空值分支 |
| 异常未抛出 | 添加异常抛出（按契约要求的异常类型） |
| 状态未检查 | 添加前置条件/状态检查 |
| 返回值错误 | 修正返回值（按契约要求的返回类型/值） |
输出与记录
SubAgent 返回后，检查 pending-confirmations-round-{N}.md。每轮修复的待确认事项按轮次命名，不覆盖上一轮记录。
循环与终止
修复完成后回到 Phase 4 重新盲测。
终止条件：
- 全部测试通过 → Phase 6
- 达到最大轮次（默认 3 轮）→ Phase 6（报告未修复项）
- 收敛停滞 → Phase 6（报告停滞原因）
- 退化 → 立即向用户报告，请求人工介入
Phase 6：完成汇报
生成报告至 docs/testing-design/{module_id}/adversarial-report.md，使用 references/report-template.md 模板。
验收检查清单（逐项确认，无法勾选的项必须在报告中说明原因）：
角色合规项未勾选的处理：对应声明在报告诚实声明中标记为 ❌，说明影响和原因。
数据传递与验证工具链
orchestrator 与 SubAgent 之间传递三种核心数据文件，均须经程序化验证。详细格式定义见 references/data-format-spec.md。
| 文件 | 阶段 | 验证脚本 |
|---|
function-signatures.json | Phase 2 → 3 | scripts/validate_function_signatures.py |
contract-expectations.md | Phase 1 → 3 | scripts/validate_contract_expectations.py |
failure-summary-round-{N}.md | Phase 4 → 5 | scripts/validate_failure_summary.py |
| 契约文件 vs 实现代码 | Phase 6 验收 | scripts/validate_contract_consistency.py |
自动化工具链汇总：
| 脚本 | 用途 | 调用时机 |
|---|
preflight_check.py | 流水线就绪检查（Python版本、脚本完整性、SubAgent可用性） | 前置步骤 |
validate_function_signatures.py | 验证函数签名 JSON | Phase 2.4 |
validate_contract_expectations.py | 验证契约期望清单 | Phase 1.1 |
generate_failure_summary.py | 从测试输出自动生成失败摘要 | Phase 4.3 |
validate_failure_summary.py | 验证失败摘要的信息隔离合规性 | Phase 4.3 |
classify_failures.py | 辅助判定失败类型（实现漏洞/测试缺陷/契约矛盾） | Phase 4.2 |
check_isolation.py | 审计 orchestrator 是否违规修改测试文件 | Phase 4 结束 / Phase 6 |
validate_contract_consistency.py | 验证实现代码与契约文件类型一致性 | Phase 6.3 |
异常处理
契约模糊或矛盾：记录模糊项 → AskUserQuestion 向用户确认 → 继续流程 → 纳入结果汇报
对抗性测试无法运行：向用户报告 → 退回 Phase 3 SubAgent 修复 → 修复后重新运行
实现代码导致崩溃：记录异常 → 向用户报告 → 建议手动检查
参考资源
流程与格式
references/contract-extractor.md — 契约提取五步骤算法references/failure-summary-format.md — 失败摘要格式、信息边界、收敛判定逻辑references/report-template.md — Phase 6 报告模板（含诚实声明）references/data-format-spec.md — 三种数据文件的精确格式和验证规则references/subagent-prompts.md — 四个 SubAgent 调度 prompt 模板（含占位符说明）
被调 Skill
adversarial-implementation-executor — Phase 2 实现落地 + Phase 5 修复迭代adversarial-test-generator — Phase 3 测试生成 + Phase 4.5.2 测试缺陷修正
Schema
references/schemas/function-signatures.schema.json — 函数签名 JSON Schema
