| name | adversarial-implementation-executor |
| description | 专门为 module-implementation-orchestrator 的对抗性验证流程服务的实现执行器。
处理两种场景：(1) 按设计文档优雅实现模块（Phase 2），输出实现代码 + 函数签名清单；
(2) 根据盲测失败摘要修复实现代码（Phase 5），不接触任何测试代码。
本 skill 不直接响应用户指令，仅由 module-implementation-orchestrator 通过 Agent 工具调度使用。
|
对抗性实现执行器
定位与边界
本 skill 是 module-implementation-orchestrator 的专属实现工具，仅通过 Agent 工具被 orchestrator 调度，不直接响应用户指令。
| 维度 | 本 skill 的特征 |
|---|
| 触发方式 | 仅被 orchestrator 调度，通过 Agent(subagent_type="coder", prompt="...") 激活 |
| 测试运行 | 不运行任何测试。测试由 orchestrator Phase 4 盲测统一执行 |
| 验收责任 | 由 orchestrator Phase 4 盲测负责 |
| Phase 2（初始实现）输出 | 实现代码 + 函数签名清单（JSON） |
| Phase 5（修复迭代）输入 | 失败摘要（Markdown），不含任何测试代码或具体输入值 |
| Phase 5（修复迭代）输出 | 修改后的代码 + 修改说明（引用 case ID） |
| 用户沟通 | 不可 AskUserQuestion。所有待确认事项按保守假设处理并返回 orchestrator |
触发识别
本 skill 仅在被以下方式调用时激活：
Agent(subagent_type="coder", prompt="...对抗性验证...实现落地...")
Agent(subagent_type="coder", prompt="...失败摘要...修复...")
核心原则
- 不运行测试：本 skill 的 workflow 中没有"运行测试"步骤。测试由 orchestrator 的 Phase 4 盲测统一执行。
- 信息隔离：绝对禁止读取
{module_code_dir}/.tmp/adversarial-tests/ 目录下的任何文件。不要查看、不要搜索、不要分析该目录中的内容。
- 契约权威：实现代码严格按落地规范编写，不根据想象中的测试来调整实现。
- 增量优先：优先修改现有代码以适配新需求，仅在现有文件职责不符或不存在时新建。禁止为"统一风格"而大面积重写未涉及的现有代码。
- 不向用户提问：本 skill 运行于 SubAgent 环境，所有需要用户裁决的事项必须按保守假设处理，并以"待确认事项"形式返回给 orchestrator，由 orchestrator 决定是否向用户提问。
信息隔离补充
扫描现有代码时，排除 {module_code_dir}/.tmp/adversarial-tests/ 目录。
实现规范（适用于模式 A 和模式 B）
复杂后端实现模式（状态机、重试降级、依赖注入等）的详细代码示例和模式说明见 references/implementation-patterns.md。前端模块或简单 CRUD 可跳过。
实现顺序
代码按以下顺序生长：
- 类型系统（枚举、常量、字面量类型）
- 数据契约层（Pydantic / TypeScript interface / Zod / Go struct）
- 工具代码（helper/utility 函数）
- 原子功能单元（每步骤一个独立函数/组件）
- 状态机（如需要，独立的状态流转模块）
- 组合层（编排——主文件只调度核心功能）
- 异常处理（装饰器 / 中间件 / ErrorBoundary）
- 依赖适配（依赖注入 / Props / Context）
代码组织铁律
- 严格遵循项目结构设计文档：文件必须放在指定目录中
- 命名必须符合项目规范：文件、类、函数、常量命名与项目一致
- 共享资源必须复用：通用工具、类型、常量使用项目指定的共享位置
- 单文件长度上限：超过 500 行（不含空行和注释）必须拆分
质量要求
- 100% 兑现设计文档，除非有不可改变的技术限制
- 所有 I/O 使用强类型
- 通过函数组合、依赖注入连接，非深层继承
- 每个边界条件有保护分支，写入操作尽量幂等
- 注释即文档：后端 Google Style docstring，前端 TSDoc/JSDoc
待确认事项处理策略（保守假设 + 上浮）
关键约束：本 skill 运行于 SubAgent 环境，不可调用 AskUserQuestion。所有需要用户裁决的事项按保守假设处理，并以"待确认事项"章节返回给 orchestrator。
可上浮到 orchestrator 的事项（SubAgent 不再处理）
以下事项已由 orchestrator 在调度 SubAgent 前解决，SubAgent 收到的契约是已裁决的统一版本：
| 原提问情形 | 上浮到 orchestrator 的阶段 | SubAgent 收到的输入状态 |
|---|
| 设计文档冲突或模糊 | Phase 1.2 契约仲裁 | 统一的契约，无矛盾 |
| 设计未覆盖的场景 | Phase 1.2 契约补全 | 契约中已标注处理方式 |
| 失败摘要与契约矛盾 | Phase 4.3 验证失败的正确性 | 已过滤，不传入 Phase 5 |
| 修复方向不明确 | Phase 4.4 失败摘要预处理 | 已消除歧义，指令清晰 |
SubAgent 保留的待确认事项（2 类）
以下事项无法干净上浮，按保守假设处理并记录：
| 情形 | 保守假设策略 | 记录要求 |
|---|
| 与现有代码冲突 | 优先修改现有文件以适配新需求（保持向后兼容），仅在会破坏现有接口契约时新建 | 在"待确认事项"中说明冲突详情和策略 |
| 无法判断缺失或冲突 | 按缺失实现处理（新建），同时保留现有代码不变 | 记录为"疑似冲突，待确认" |
待确认事项记录格式
SubAgent 必须将待确认事项写入专用文件，禁止仅在对话文本中提及。
存放路径：{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md
路径变量说明：{module_code_dir} 由 orchestrator 在调度 prompt 中通过 模块代码目录： 显式提供。若 prompt 中未提供该变量，不得自行推断路径——必须将文件写入 .tmp/adversarial-tests/{module_id}/（相对于当前工作目录），并在返回中注明 {module_code_dir} 未提供。
文件内容格式（即使为空也必须生成该文件）：
## 待确认事项（SubAgent 无法提问，已按保守假设处理）
### 事项 1：与现有代码冲突
- **涉及文件**：`src/existing.py`
- **冲突描述**：已有字段 `status` 为 `str` 类型，落地规范要求 `StatusEnum`
- **采取策略**：保持现有 `str` 类型，新增 `StatusEnum` 用于新接口
- **风险**：新旧接口混用可能导致类型不一致
### 事项 2：无法判断缺失或冲突
- **涉及文件**：`src/utils.py`
- **描述**：`validate_input` 函数已实现部分校验，不确定是补充还是冲突
- **采取策略**：补充缺失校验，保留现有校验逻辑不变
- **判断依据**：现有校验仅检查非空，落地规范要求额外检查格式
空文件格式（无任何待确认事项时）：
## 待确认事项
无。
orchestrator 通过读取上述文件审查待确认事项，如有重大风险会暂停流程向用户提问。
多模块依赖处理
读取落地规范「依赖与集成接口」章节，区分两类依赖：
| 依赖类型 | 处理方式 | 说明 |
|---|
| 关键基础设施依赖（数据库、日志、外部 API、消息队列等） | 必须真实实现，不可用 mock 替代 | 若基础设施连接配置缺失，在待确认事项中说明，由 orchestrator 决定是否向用户确认 |
| 核心功能依赖（其他业务模块的接口） | 若未落地，提取接口定义生成 mock / stub | 在待确认事项中标注"依赖项 {模块名} 待落地" |
禁止行为
| 禁止项 | 原因 |
|---|
| 上帝函数/组件 | 职责不清，难以测试和维护 |
| 全局变量通信 | 引入隐式耦合 |
| 跳过输入校验 | 对抗性测试的首要目标就是发现校验缺失 |
| 魔法字面量替代枚举 | 可读性差，易出错 |
| 静默吞异常 | 掩盖错误，导致调试困难 |
| 引入设计文档外的依赖 | 破坏技术栈约定 |
| 交付无注释的公开接口 | 可维护性下降 |
| 违反项目结构设计文档的代码组织 | 项目结构混乱 |
| 无必要地重写现有代码 | 破坏增量优先原则 |
| 向用户提问（AskUserQuestion） | 本 skill 运行于 SubAgent，待确认事项应返回 orchestrator |
工作模式 A：初始实现落地（对应 orchestrator Phase 2）
A.1 解析设计文档
每模块由三份文档组成：落地规范（编码主要来源）、设计文档（项目上下文）、项目结构设计文档（代码组织规范）。
解析项目结构设计文档（强制）
开始编码前必须定位并解析项目结构设计文档。文件命名一般为 xxx-项目结构.md。
必须提取的内容：目录结构规范、模块边界、命名规范、技术栈约束、共享资源位置。
若找不到项目结构设计文档：
- 搜索
docs/ 目录下包含"项目结构"、"目录结构"、"structure"等关键词的文件
- 若仍找不到，在待确认事项中记录"项目结构文档缺失，采用最小合理结构"
- 采用模块内"最小合理结构"
解析模块设计文档
从落地规范的"技术栈绑定"章节确定本模块的技术栈。
契约信息已由 orchestrator Phase 1 提取：输入/输出类型定义、异常条件、状态约束、边界定义等均已写入 contract-expectations.md，直接读取该文件即可，无需自行提取。
设计文档冲突仲裁
若多份设计文档要求不一致，按以下优先级执行：
| 优先级 | 文档 | 约束范围 |
|---|
| P0 | 项目结构设计文档 | 目录结构、模块边界、命名规范、共享资源位置 |
| P1 | 落地规范 | 类型定义、逻辑步骤、状态机、异常策略 |
| P2 | 设计文档 | 业务意图、上下文说明、兼容性分析 |
即：文件放哪里 → 按项目结构设计文档；代码怎么写 → 按落地规范；为什么这么写 → 按设计文档。
若发现冲突，在待确认事项中记录冲突详情和按优先级采取的裁决策略。
A.2 扫描现有代码
目标：识别可复用的现有代码，为"增量优先"原则提供依据。
手动扫描方法：
- 按"已有设计兼容性分析"章节给出的文件路径定位
- grep 设计文档中的类型/组件/类名
- 搜索与模块名称同名的文件/类/函数/组件
- 搜索核心动词——仅在前 3 步无结果时使用
输出要求：文件路径 → 已实现项 → 差异（缺失字段/类型不匹配/步骤缺失），标注增量潜力评估。
若文档标注"全新模块"，跳过此步骤。
额外约束：文件扫描范围排除 {module_code_dir}/.tmp/adversarial-tests/。
A.3 差异比对
逐项比对，只记差异。
| 差异类型 | 判定标准 | 处理方式 |
|---|
| 缺失实现 | 设计文档有要求，代码中完全不存在 | 直接实现 |
| 字段/类型/枚举值冲突 | 已有代码存在但定义不一致 | 在待确认事项中记录，按保守假设处理 |
| 已有逻辑冲突 | 已有实现逻辑与设计文档步骤不符 | 在待确认事项中记录，按保守假设处理 |
| 技术栈冲突 | 已有代码使用设计文档外的技术 | 在待确认事项中记录 |
| 设计文档冲突 | 多份设计文档要求不一致 | 按优先级仲裁，在待确认事项中记录 |
| 设计未覆盖 | 某实现细节未定义 | 在待确认事项中记录，采用最宽松假设 |
A.4 优雅实现
核心哲学：每个功能点是高内聚、低耦合的原子单元，通过管道/策略/装饰器模式组合，避免"上帝对象"。
增量优先原则：
- 优先修改现有文件以适配需求，仅在现有文件职责不符或不存在时新建
- 禁止为"统一风格"而重写未涉及的现有代码
- 修改现有代码时，保持其原有接口契约
多模块依赖处理：见上文"多模块依赖处理"章节。
质量要求：100% 兑现设计文档、强类型 I/O、函数组合而非深层继承、边界条件保护、注释即文档。
禁止行为：上帝函数/组件、全局变量通信、跳过校验、魔法字面量替代枚举、静默吞异常、引入设计文档外的依赖、交付无注释的公开接口、违反项目结构设计文档、无必要地重写现有代码。
A.5 生成函数签名清单（新增，强制）
提取所有公开函数/方法的签名，生成 JSON 格式的函数签名清单：
{
"module_id": "模块编号（如 M01）",
"module_name": "模块名称",
"functions": [
{
"name": "func_name",
"signature": "def func_name(param_a: int, param_b: str = \"\") -> ResultType",
"parameters": [
{"name": "param_a", "type": "int", "required": true},
{"name": "param_b", "type": "str", "required": false, "default": "\"\""}
],
"return_type": "ResultType",
"exceptions": ["ValueError", "TimeoutError"]
}
]
}
存放路径：{module_code_dir}/.tmp/adversarial-tests/{module_id}/function-signatures.json
路径变量说明：{module_code_dir} 由 orchestrator 在调度 prompt 中通过 模块代码目录： 显式提供。若 prompt 中未提供该变量，将文件写入 .tmp/adversarial-tests/{module_id}/（相对于当前工作目录），并在返回中注明 {module_code_dir} 未提供。
根据实际平台调整路径分隔符。
A.6 输出
返回 orchestrator：
- 实现代码文件列表（完整路径）
- 函数签名清单（JSON 文件路径）
- 实现说明（简要）
- 待确认事项文件路径：
{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md
若 {module_code_dir} 未在 prompt 中提供，写入 .tmp/adversarial-tests/{module_id}/pending-confirmations.md（相对于当前工作目录）。
工作模式 B：修复迭代（对应 orchestrator Phase 5）
B.1 阅读输入
输入材料：
- 失败摘要（Markdown，来自 orchestrator Phase 4）
- 当前实现代码
- 落地规范
- 契约期望清单（可选，用于理解契约条款）
失败摘要格式：
#### [case-001] TypeError: 参数收到非期望类型
- **涉及函数**：`calculate_limit`
- **涉及参数**：`limit`（类型：int (≥1)）
- **契约条款**：§3.2
- **失败原因**：参数收到 None，函数未进行类型校验
- **修复建议**：在函数入口处添加参数非空和类型校验
B.2 分析修复优先级
按失败摘要中的"修复方向建议"排序，优先处理影响用例数多的问题。
修复策略映射：
| 失败原因 | 修复动作 |
|---|
| 参数未校验 | 添加输入校验（类型检查、非空检查） |
| 边界未处理 | 添加边界检查（范围、长度） |
| 空值未防护 | 添加 None/空值分支 |
| 异常未抛出 | 添加异常抛出（按契约要求的异常类型） |
| 状态未检查 | 添加前置条件/状态检查 |
| 返回值错误 | 修正返回值（按契约要求的返回类型/值） |
B.3 修复实现
约束：
- 仅修改实现代码，不修改任何测试文件
- 每处修改必须对应失败摘要中的一个 case ID
- 修复应最小化，不引入超出当前失败摘要范围的行为
- 保持现有接口契约不变（不增删参数、不改返回值类型）
- 若修复方向与现有代码产生冲突，按保守假设处理并在待确认事项中记录
B.4 输出
返回 orchestrator：
- 修改后的实现代码文件列表
- 修改说明（Markdown 格式）：
## 修复说明（第 {N} 轮）
### case-001
- **修复文件**：`src/services/calculator.py`
- **修复内容**：在 `calculate_limit` 函数入口处添加参数校验
```python
if limit is None:
raise TypeError("limit must be int, got None")
case-042
...
3. **待确认事项文件路径**：`{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md`
> 若 `{module_code_dir}` 未在 prompt 中提供，写入 `.tmp/adversarial-tests/{module_id}/pending-confirmations.md`（相对于当前工作目录）。
---
## 设计文档补充更新
执行完毕后（包括修复迭代），若发现项目结构设计文档或落地规范存在未覆盖的场景，**必须补充更新**。
**更新判定标准**：仅当执行过程中向用户确认过、且用户给出了明确方向时，才更新设计文档。禁止将未经用户确认的假设写入设计文档。
**更新操作模板**：
对 `xxx-项目结构.md` 的追加格式：
```markdown
## 补充条目（{YYYY-MM-DD}）
### {条目名称}
- **场景**：{触发条件}
- **规范**：{用户确认后的存放位置/命名规则/边界定义}
- **来源**：adversarial-implementation-executor 执行 {module_id} 时发现
对 xxx-落地规范.md 的修正格式：
## 修正记录（{YYYY-MM-DD}）
### {修正项}
- **原内容**：{原文引用}
- **修正为**：{修正后内容}
- **原因**：{与项目结构设计文档冲突 / 歧义 / 未覆盖场景}
- **来源**：adversarial-implementation-executor 执行 {module_id} 时确认
若用户明确指示"不要修改设计文档"，则跳过此步骤，但在结果汇报中注明"设计文档未更新（按用户指示）"。
