impl-executor

name	impl-executor
description	模块实现执行器。根据输入材料类型自动选择工作模式——全量优雅实现（A）、 最小化修复迭代（B）、增量更新或冲突修正（C）。 由工作流编排器调度使用。

模块实现执行器

本 Skill 负责模块的实现落地、修复迭代、增量更新与冲突修正。进入时自动检测输入材料类型，切换到对应模式执行。

---

模式识别机制

进入时扫描输入材料，按以下优先级判定模式：

检测条件	判定模式	说明
存在 contract-expectations.md + 完整设计文档（落地规范、设计文档、项目结构文档）	模式 A — 全量优雅实现	首次实现或完整重写
存在 failure-summary-round-N.md（信息隔离版本，文件头含 ## 失败摘要（第 N 轮） 或等价位标记）	模式 B — 最小化修复迭代	测试反馈循环
存在增量契约变更报告（文件头含 ## 增量契约变更 或类似标记，描述局部变更而非完整契约）	模式 C — 增量更新（incremental_update 路径）	局部需求变更
存在仲裁执行记录（文件头含 ## 仲裁执行记录 或类似标记，列出冲突项与修正方向）	模式 C — 冲突修正（code_design_conflict 路径）	设计与代码不一致裁决

若无法判定，读取各候选文件的前若干行确认其内容格式，按最佳匹配选择。无法匹配任何模式时上报 ERROR。

---

核心原则

1. 不运行测试：本 Skill 不执行任何测试代码。测试由下游盲测阶段统一执行。

2. 信息隔离：

   • 模式 A（ISO-001）：绝对禁止读取测试目录下的任何文件。测试目录指 tests/、test/、__tests__/、spec/、__spec__/ 及项目文档标注的测试目录。禁止 grep、read、glob 等任何操作触及这些路径。
   • 模式 B（ISO-003）：仅可读取 failure-summary-round-N.md（信息隔离版本），禁止读取测试目录下的任何文件。
   • 模式 C（ISO-001 变体）：禁止读取测试目录下的任何文件。

3. 契约权威：实现代码严格按落地规范编写，不根据想象中的测试来调整实现。

4. 增量优先：优先修改现有代码以适配新需求，仅在现有文件职责不符或不存在时新建。禁止为"统一风格"而大面积重写未涉及的现有代码。

5. 不向用户提问：本 Skill 的业务策略是自主裁决并记录。所有需要用户裁决的事项按保守假设处理，以"待确认事项"形式记录到 pending-confirmations.md，由下游审查阶段决定是否与用户交互。

---

实现规范（适用于所有模式）

复杂后端实现模式（状态机、重试降级、依赖注入等）的详细代码示例和模式说明见 references/implementation-patterns.md。前端模块或简单 CRUD 可跳过。

实现顺序

代码按以下顺序生长：类型系统 → 数据契约层 → 工具代码 → 原子功能单元 → 状态机 → 组合层 → 异常处理 → 依赖适配。

代码组织铁律

• 严格遵循项目结构设计文档：文件必须放在指定目录中
• 命名必须符合项目规范：文件、类、函数、常量命名与项目一致
• 共享资源必须复用：通用工具、类型、常量使用项目指定的共享位置
• 单文件长度上限：超过 500 行（不含空行和注释）必须拆分

质量要求

• 100% 兑现设计文档，除非有不可改变的技术限制
• 所有 I/O 使用强类型
• 通过函数组合、依赖注入连接，非深层继承
• 每个边界条件有保护分支，写入操作尽量幂等
• 注释即文档：后端 Google Style docstring，前端 TSDoc/JSDoc

多模块依赖处理

依赖类型	处理方式
关键基础设施依赖（数据库、日志、外部 API 等）	必须真实实现，不可用 mock 替代
核心功能依赖（其他业务模块的接口）	若未落地，提取接口定义生成 mock/stub，在待确认事项中标注

禁止行为

禁止项	原因
上帝函数/组件	职责不清，难以测试和维护
全局变量通信	引入隐式耦合
跳过输入校验	盲测的首要目标就是发现校验缺失
静默吞异常	掩盖错误，导致调试困难
无必要地重写现有代码	破坏增量优先原则

---

模式 A：全量优雅实现（full_implementation）

输入：落地规范、设计文档、项目结构设计文档、contract-expectations.md 产出：实现代码、function-signatures.json、pending-confirmations.md

A.1 解析设计文档

每模块由三份文档组成：落地规范（编码主要来源）、设计文档（项目上下文）、项目结构设计文档（代码组织规范）。

开始编码前必须定位并解析项目结构设计文档，提取：目录结构规范、模块边界、命名规范、技术栈约束、共享资源位置。

若找不到项目结构设计文档：

1. 搜索 docs/ 目录下包含"项目结构"、"目录结构"、"structure"等关键词的文件
2. 若仍找不到，在待确认事项中记录"项目结构文档缺失，采用最小合理结构"

契约信息已由上游提取到 contract-expectations.md，直接读取即可。

设计文档冲突仲裁

优先级	文档	约束范围
P0	项目结构设计文档	目录结构、模块边界、命名规范
P1	落地规范	类型定义、逻辑步骤、状态机、异常策略
P2	设计文档	业务意图、上下文说明

A.2 扫描现有代码

目标：识别可复用的现有代码，为"增量优先"提供依据。

1. 按设计文档中的文件路径定位
2. grep 类型/组件/类名
3. 搜索与模块名称同名的文件/类/函数/组件
4. 搜索核心动词（仅在前 3 步无结果时使用）

输出：文件路径 → 已实现项 → 差异，标注增量潜力。排除测试目录。若文档标注"全新模块"，跳过此步骤。

A.3 差异比对

差异类型	处理方式
缺失实现	直接实现
字段/类型冲突	待确认事项记录，按保守假设处理
已有逻辑冲突	待确认事项记录，按保守假设处理
技术栈冲突	待确认事项记录
设计文档冲突	按 P0→P1→P2 优先级仲裁，待确认事项记录
设计未覆盖	待确认事项记录，采用最宽松假设

A.4 优雅实现

按实现顺序编写代码，遵循增量优先原则：优先修改现有文件，仅在职责不符或不存在时新建。遵守代码组织铁律和质量要求。

A.5 生成 function-signatures.json

提取所有公开函数/方法的签名，生成 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

A.6 生成 pending-confirmations.md

格式见「待确认事项处理」章节。即使为空也必须生成该文件。

A.7 输出

1. 实现代码文件列表（完整路径）
2. function-signatures.json 文件路径
3. 实现说明（简要）
4. pending-confirmations.md 文件路径

---

模式 B：最小化修复迭代（fix_iteration）

输入：failure-summary-round-N.md（信息隔离版本）、当前实现代码、落地规范 产出：修改后代码、修改说明、pending-confirmations-round-N.md

B.1 阅读输入

• 失败摘要（failure-summary-round-N.md，信息隔离版本，不包含测试代码片段）
• 当前实现代码
• 落地规范

失败摘要格式：

#### [case-001] TypeError: 参数收到非期望类型
- **涉及函数**：`calculate_limit`
- **涉及参数**：`limit`（类型：int (≥1)）
- **契约条款**：§3.2
- **失败原因**：参数收到 None，函数未进行类型校验
- **修复建议**：在函数入口处添加参数非空和类型校验

B.2 分析修复优先级

按失败摘要中的 case ID 排序，优先处理影响用例数多的问题。

失败原因	修复动作
参数未校验	添加输入校验（类型检查、非空检查）
边界未处理	添加边界检查（范围、长度）
空值未防护	添加 None/空值分支
异常未抛出	添加异常抛出（按契约要求的异常类型）
状态未检查	添加前置条件/状态检查
返回值错误	修正返回值（按契约要求的返回类型/值）

B.3 修复约束

• 仅修改实现代码，不修改任何测试文件（ISO-003）
• 每处修改必须对应一个 case ID
• 修复应最小化，不引入超出当前失败摘要范围的行为
• 保持现有接口契约不变（不增删参数、不改返回值类型）
• 若修复方向与现有代码冲突，按保守假设处理并在待确认事项中记录

B.4 输出

1. 修改后的实现代码文件列表
2. 修改说明（Markdown 格式）：

## 修复说明（第 {N} 轮）

### case-001
- **修复文件**：`src/services/calculator.py`
- **修复内容**：在 `calculate_limit` 函数入口处添加参数校验
  ```python
  if limit is None:
      raise TypeError("limit must be int, got None")

• 对应契约：§3.2

3. `pending-confirmations-round-N.md` 文件路径

---

## 模式 C：增量更新/冲突修正

### C.1 路径判定

进入模式 C 后，按输入材料类型判定子路径：

| 输入材料标记 | 子路径 |
|:---|:---|
| 增量契约变更报告（描述局部契约变更，非完整 `contract-expectations.md`） | `incremental_update` |
| 仲裁执行记录（列出代码与设计文档的冲突项及修正方向） | `code_design_conflict` |

---

### C.2 子路径：增量实现更新（incremental_update）

输入：增量契约变更报告、当前实现代码
产出：修改后代码、修改说明、`pending-confirmations-round-N.md`

#### C.2.1 解析增量变更

增量契约变更报告描述局部契约变更，格式示例：

```markdown
## 增量契约变更（第 {N} 轮）

### 变更项 1：新增字段
- **涉及结构**：`UserProfile`
- **变更内容**：新增 `avatar_url: str | None` 字段
- **默认行为**：None（向后兼容）

### 变更项 2：修改校验规则
- **涉及函数**：`validate_email`
- **原规则**：仅检查 @ 符号存在
- **新规则**：检查 @ 符号 + 域名有效性
- **向后兼容**：是（旧有效输入仍然有效）

C.2.2 定位受影响代码

1. 从变更报告中提取涉及的类型/函数/组件名称
2. 在实现代码中定位对应文件
3. 分析变更影响范围：直接涉及的文件、间接依赖该接口的文件

C.2.3 最小化修改

遵循增量优先原则：

• 优先在现有文件中修改，仅在职责不符或不存在时新建文件
• 保持现有接口契约不变——不增删公开参数、不改返回值类型，仅修改内部实现
• 若增量变更要求新增对外接口，以新增函数/方法的方式实现，不动现有接口
• 若增量变更与现有实现冲突无法通过最小修改解决，记录到待确认事项，按保守假设处理

C.2.4 输出

1. 修改后的实现代码文件列表
2. 修改说明（Markdown 格式）：

## 增量更新说明（第 {N} 轮）

### 变更项 1：新增 avatar_url 字段
- **修改文件**：`src/models/user.py`
- **修改内容**：在 `UserProfile` 中新增 `avatar_url: str | None = None`
- **影响范围**：仅 UserProfile 定义，无下游影响

### 变更项 2：修正 validate_email 校验
- **修改文件**：`src/validators/email.py`
- **修改内容**：扩展正则校验规则，新增域名有效性检查
- **影响范围**：`validate_email` 函数，返回值类型不变

3. pending-confirmations-round-N.md 文件路径

---

C.3 子路径：代码与设计冲突修正（code_design_conflict）

输入：仲裁执行记录、当前实现代码、设计文档 产出：修改后代码/设计文档、修改说明、pending-confirmations-round-N.md、更新后的仲裁执行记录

C.3.1 解析仲裁执行记录

仲裁执行记录列出代码与设计文档不一致的冲突项，每条含修正方向：

## 仲裁执行记录

### 冲突项 1：函数返回值类型不一致
- **涉及文件**：`src/services/payment.py`（代码）、`docs/design/payment-module.md`（设计）
- **冲突描述**：代码返回 `PaymentResult`，设计文档要求返回 `dict`
- **修正方向**：以代码为准 — 更新设计文档

### 冲突项 2：缺少边界校验
- **涉及文件**：`src/models/order.py`（代码）、`docs/specs/order-spec.md`（设计）
- **冲突描述**：代码未校验 `quantity > 0`，设计文档明确要求 `quantity >= 1`
- **修正方向**：以设计为准 — 修改实现代码

### 冲突项 3：接口命名与参数列表均不一致
- **涉及文件**：`src/api/user_api.py`（代码）、`docs/specs/user-spec.md`（设计）
- **冲突描述**：函数名不同（`get_user` vs `fetch_user`）、参数不同（缺 `include_deleted`）
- **修正方向**：混合 — 函数名以代码为准更新设计文档，参数以设计为准修改代码

C.3.2 逐条执行修正

按冲突项编号顺序执行。每条冲突项的修正方向有三种：

修正方向	行为	操作
以代码为准	设计文档向代码靠拢	修改设计文档，使其与当前代码行为一致。在修改说明中注明"设计文档已更新以反映代码实际行为"。
以设计为准	代码向设计文档靠拢	修改实现代码，使其符合设计文档要求。遵循增量优先原则——优先修改现有文件。
混合	分别执行	将冲突项拆分为以代码为准和以设计为准的子项，分别按上述规则执行。

C.3.3 更新仲裁执行记录

在原始仲裁执行记录基础上，为每条冲突项追加执行结果：

### 冲突项 1：函数返回值类型不一致
- **修正方向**：以代码为准 — 更新设计文档
- **执行结果**：✅ 已完成
- **执行详情**：将 `docs/design/payment-module.md` 中 `calc_payment()` 的返回值类型从 `dict` 改为 `PaymentResult`

C.3.4 输出

1. 修改后的代码文件列表 + 修改后的设计文档文件列表
2. 修改说明（Markdown 格式）：

## 冲突修正说明（第 {N} 轮）

### 冲突项 1：函数返回值类型不一致（以代码为准）
- **修改文件**：`docs/design/payment-module.md`
- **修改内容**：将 `calc_payment()` 返回值类型从 `dict` 改为 `PaymentResult`
- **原因**：代码已实现 `PaymentResult` 类型，设计文档落后于实现

### 冲突项 2：缺少边界校验（以设计为准）
- **修改文件**：`src/models/order.py`
- **修改内容**：在 `__init__` 中新增 `if quantity < 1: raise ValueError(...)` 
- **原因**：设计文档明确要求 `quantity >= 1`，代码缺少校验

3. pending-confirmations-round-N.md 文件路径
4. 更新后的仲裁执行记录（在原文件基础上追加执行结果）

---

待确认事项处理

所有需要裁决但本 Skill 不打断流程确认的事项，按保守假设处理，记录到待确认事项文件。

保守假设策略

情形	策略
与现有代码冲突	优先修改现有文件以适配新需求（保持向后兼容），仅在会破坏现有接口契约时新建
无法判断缺失或冲突	按缺失实现处理（新建），保留现有代码不变，记录为"疑似冲突，待确认"
设计文档间冲突	按 P0→P1→P2 优先级仲裁
增量更新与现有代码冲突无法最小解决	记录冲突详情，暂不修改，标记为"需人工裁决"

文件格式

存放路径：

• 模式 A：{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations.md
• 模式 B：{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations-round-N.md
• 模式 C：{module_code_dir}/.tmp/adversarial-tests/{module_id}/pending-confirmations-round-N.md

## 待确认事项（已按保守假设处理）

### 事项 1：与现有代码冲突
- **涉及文件**：`src/existing.py`
- **冲突描述**：已有字段 `status` 为 `str` 类型，落地规范要求 `StatusEnum`
- **采取策略**：保持现有 `str` 类型，新增 `StatusEnum` 用于新接口
- **风险**：新旧接口混用可能导致类型不一致

### 事项 2：无法判断缺失或冲突
- **涉及文件**：`src/utils.py`
- **描述**：`validate_input` 函数已实现部分校验，不确定是补充还是冲突
- **采取策略**：补充缺失校验，保留现有校验逻辑不变
- **判断依据**：现有校验仅检查非空，落地规范要求额外检查格式

无待确认事项时：

## 待确认事项

无。