lanyasheng Improvement Executor
Applies accepted candidates with automatic backup and rollback.
When to Use
- 把已批准的改进候选应用到目标文件（自动创建备份，支持一键回滚）
- 回滚之前的变更（通过 receipt 中的 rollback_pointer 精确恢复）
- 用
--dry-run预览变更效果，确认无误后再真正执行 - 在 orchestrator pipeline 第 4 阶段自动调用
- 需要对 YAML frontmatter 做字段级合并更新时（update_yaml 模式）
- 需要在指定 heading 前插入新内容时（insert_before 模式）
- 批量执行 ranking 中多个候选的变更
- 验证变更是否可逆——每次执行都会产出 receipt，receipt 包含完整的原始内容
When NOT to Use
- 给候选打分 → use
improvement-discriminator（executor 不做质量判断） - 门禁验证 → use
improvement-gate（executor 只执行，gate 才验证结果） - 全流程编排 → use
improvement-orchestrator（orchestrator 统一调度各阶段） - 评估 skill 结构 → use
improvement-learner - 候选尚未通过 discriminator 评分时，不应直接调用 executor
- 不要用 executor 做批量文件重命名或目录结构变更——它只处理单文件内容修改
- 不要在没有 ranking.json 的情况下调用——输入必须是 discriminator 产出的标准格式
- 不要手动编辑 receipt.json——receipt 包含哈希校验，手动修改会导致 rollback 失败
4 Action Types
| Action | Description |
|---|---|
append_markdown_section |
Append a new section to the end of the file |
replace_markdown_section |
Replace an existing section by heading match (exact heading text) |
insert_before_section |
Insert content before a matched heading |
update_yaml_frontmatter |
Merge fields into YAML frontmatter (deep merge, preserves existing keys) |
每种 action 的适用场景：
- append — 新增全新 section（如添加 "## Caveats"），不影响已有内容
- replace — 重写已有 section 的全部内容，按 heading 精确匹配（大小写敏感）
- insert_before — 在指定 section 前插入内容，适合在 "## CLI" 前加 "## Design Notes"
- update_yaml — 合并 frontmatter 字段，已有字段会被覆盖，新字段会被添加
Why Automatic Backup Matters
Tradeoff: disk space for safety — every apply creates a full copy of the original file.
之所以每次变更前都做自动备份，原因是：
- One bad apply can corrupt the entire skill — replace_markdown_section 如果匹配到错误的 heading，会覆盖关键内容。没有备份就无法恢复。
- Backup 是 rollback 的基础 — receipt 中的
rollback_pointer指向备份文件的绝对路径和原始内容哈希。回滚时先校验哈希，确保备份未被篡改，再恢复。 - 备份成本极低 — SKILL.md 通常不超过 10KB，备份文件存储在
.state/backups/下，按时间戳命名，不会干扰版本控制。 - 审计需求 — 备份链构成了完整的变更历史，可以追溯任意时间点的文件状态。
问题: 为什么不用 git 替代备份？Because executor 可能在没有 git repo 的环境中运行（例如临时目录中的 skill 测试），且 git commit 粒度太粗——一次 orchestrator run 可能执行多个候选，每个都需要独立的回滚点。
CLI
execute.py 是核心入口，接收 ranking artifact 和 candidate ID，输出 result.json。
rollback.py 负责回滚，接收 receipt.json 还原到变更前的状态。
两个命令都支持 --dry-run 预览变更而不实际修改文件。
execute.py 会在执行前自动创建备份，备份路径记录在 result.json 的 backup_path 字段中。
建议对高风险变更（replace/update_yaml）始终先跑 --dry-run 确认。
rollback.py 在恢复前会校验备份文件的 SHA256 哈希，防止备份被篡改。
# Apply a single candidate (requires ranking artifact + candidate ID)
python3 scripts/execute.py --input ranking.json --candidate-id CANDIDATE_ID --output result.json
# Rollback a previous change using its receipt
python3 scripts/rollback.py --receipt receipt.json
# Dry-run: preview what rollback would do without modifying files
python3 scripts/rollback.py --receipt receipt.json --dry-run
Each action type maps to a different candidate structure. Examples:
# append_markdown_section: add a new "## Caveats" section at the end
python3 scripts/execute.py --input ranking.json --candidate-id C001 --output result.json
# candidate C001's action = "append_markdown_section", content = "## Caveats\n..."
# replace_markdown_section: overwrite the "## When to Use" section
python3 scripts/execute.py --input ranking.json --candidate-id C002 --output result.json
# candidate C002's action = "replace_markdown_section", heading = "When to Use"
# insert_before_section: insert content before "## CLI"
python3 scripts/execute.py --input ranking.json --candidate-id C003 --output result.json
# candidate C003's action = "insert_before_section", before_heading = "CLI"
# update_yaml_frontmatter: merge {version: "0.2.0"} into frontmatter
python3 scripts/execute.py --input ranking.json --candidate-id C004 --output result.json
# candidate C004's action = "update_yaml_frontmatter", fields = {version: "0.2.0"}
Always preview with --dry-run before executing irreversible changes:
# Dry-run for execute (not just rollback)
python3 scripts/execute.py \
--input ranking.json \
--candidate-id CANDIDATE_ID \
--dry-run \
--output preview.json
# preview.json shows the diff without modifying the target file
Output Artifacts
| Request | Deliverable |
|---|---|
| Execute | JSON with rollback_pointer (original content hash, backup absolute path, timestamp) |
| Rollback | Restored file + confirmation JSON with restore status and hash verification result |
| Dry-run (execute) | JSON diff preview: before/after content, action type, target heading |
| Dry-run (rollback) | JSON showing what would be restored without modifying files |
result.json 的核心字段：
status: success / failure / dry_runaction: 执行的 action 类型（append/replace/insert_before/update_yaml）target_file: 被修改的文件绝对路径backup_path: 备份文件路径（用于 rollback）content_hash_before/content_hash_after: 变更前后的 SHA256 哈希rollback_pointer: 包含恢复所需的全部信息，传给 rollback.py 即可一键恢复
Related Skills
- improvement-discriminator: Scores candidates before execution — executor 的输入是 discriminator 排序后的 ranking
- improvement-gate: Validates results after execution — gate 验证 executor 产出的 result.json
- improvement-orchestrator: Calls executor as stage 4 — 全流程中 executor 在 evaluator 之后、gate 之前
- improvement-generator: Produces the candidates — generator 的输出经 discriminator 评分后成为 executor 的输入
- improvement-evaluator: Task-based evaluation — evaluator 在 executor 之前验证候选的可行性
- improvement-learner: 6-dim structural scoring — executor 应用变更后，learner 可重新评分验证质量提升
- benchmark-store: Pareto front data — executor 变更后 gate 会用 benchmark 数据做回归检测
Pipeline 中的数据流: generator → discriminator → evaluator → executor → gate