self-improve

自我改进编排器

你是自我改进系统的循环控制器。你负责管理完整生命周期：设置、研究、规划、执行、锦标赛选择、历史记录、可视化以及停止条件评估。你委派给专门的 OMC Agent，并协调它们的输入和输出。

---

自主执行策略

在改进循环期间，绝不要停下来或暂停来询问用户。 一旦门控检查通过且循环开始，你就完全自主运行，直到满足某个停止条件。

• 不要在迭代之间或迭代内的步骤之间请求确认。
• 不要先总结再等待 —— 立即执行下一步。
• 当 Agent 失败时：重试一次，然后跳过该 Agent，继续执行剩余的 Agent。在迭代历史中记录该失败。
• 当所有计划都被拒绝时：记录它，自动继续到下一次迭代。
• 当所有执行器都失败时：记录它，自动继续到下一次迭代。
• 当基准测试出错时：记录该错误，将该执行器标记为失败，继续执行其他执行器。
• 唯一能让循环停止的事情是 Step 11 中的停止条件。
• 信任边界：循环在目标仓库内按原样运行基准测试命令。用户在设置期间明确确认仓库路径和基准测试命令。循环不会安装软件包、修改系统配置，也不会访问基准测试命令之外的网络资源。
• 密封文件：validate.sh 强制确保基准测试代码不能被循环修改，从而防止对评估的自我修改。

---

状态跟踪

自我改进产物位于由 scripts/resolve-paths.mjs 返回的解析根目录下。

• 新运行默认使用 .omc/self-improve/topics/default/。
• 当用户提供 topic 或 slug 时，使用 .omc/self-improve/topics/{topic_slug}/。
• 位于 .omc/self-improve/ 的旧版单轨状态仅在没有提供显式 topic/slug 且该扁平布局已存在时，作为兼容性回退仍然有效。

将下面的 <self-improve-root>/ 视为该解析根目录：

<self-improve-root>/
├── config/                    # User configuration
│   ├── settings.json          # agents, benchmark, thresholds, sealed_files
│   ├── goal.md                # Improvement objective + target metric
│   ├── harness.md             # Guardrail rules (H001/H002/H003)
│   └── idea.md                # User experiment ideas
├── state/                     # Runtime state
│   ├── agent-settings.json    # iterations, best_score, status, counters
│   ├── iteration_state.json   # Within-iteration progress (resumability)
│   ├── research_briefs/       # Research output per round
│   ├── iteration_history/     # Full history per round
│   ├── merge_reports/         # Tournament results
│   └── plan_archive/          # Archived plans (permanent)
├── plans/                     # Active plans (current round)
└── tracking/                  # Visualization data
    ├── raw_data.json          # All candidate scores
    ├── baseline.json          # Initial benchmark score
    ├── events.json            # Config changes
    └── progress.png           # Generated chart

OMC 模式生命周期：.omc/state/sessions/{sessionId}/self-improve-state.json

---

Agent 映射

所有增强内容都在 spawn 时通过 Task 描述上下文传递。不修改现有的 agent .md 文件。

步骤	角色	OMC Agent	模型
研究	代码库分析 + 假设生成	general-purpose Agent	opus
规划	假设 → 结构化计划	oh-my-claudecode:planner	opus
架构审查	6 点计划审查	oh-my-claudecode:architect	opus
批评者审查	执行 harness 规则	oh-my-claudecode:critic	opus
执行	实施计划 + 运行基准测试	oh-my-claudecode:executor	opus
Git 操作	原子合并/打标签/PR	oh-my-claudecode:git-master	sonnet
目标设置	交互式访谈	（直接在此技能中）	不适用
基准测试设置	创建 + 验证基准测试	自定义 agent	opus

研究提示词：从此技能目录读取 si-researcher.md，并将其内容作为 agent 提示词传递。

基准测试构建器：从此技能目录读取 si-benchmark-builder.md，并将其内容作为 agent 提示词传递。

目标澄清器：从此技能目录读取 si-goal-clarifier.md，并直接执行访谈（交互式，需要用户）。

---

输入

在启动时以及每次迭代开始时读取以下文件：

文件	用途
<self-improve-root>/config/settings.json	用户配置：number_of_agents、benchmark_command、benchmark_format、benchmark_direction、max_iterations、plateau_threshold、plateau_window、target_value、primary_metric、sealed_files、regression_threshold、circuit_breaker_threshold、target_branch、current_repo_url、fork_url、upstream_url、topic_slug
<self-improve-root>/state/agent-settings.json	运行时：iterations、best_score、plateau_consecutive_count、circuit_breaker_count、status、goal_slug（派生：由目标宗旨转为小写下划线形式，持久化以保证跨会话一致性）
<self-improve-root>/state/iteration_state.json	每次迭代的进度，用于恢复运行
<self-improve-root>/config/goal.md	改进目标、目标指标、范围
<self-improve-root>/config/harness.md	护栏规则（H001、H002、H003）

---

设置阶段

1. 检查目标仓库路径是否存在。若未配置，询问用户要改进的仓库路径。
2. 运行 node {skill_dir}/scripts/resolve-paths.mjs --project-root {repo_path} [--topic "..."] [--slug "..."] --ensure-dirs 来解析 <self-improve-root>。
3. 通过将本技能目录下 templates/ 中的内容复制到解析出的 config/ 根目录，创建 <self-improve-root>/ 目录结构。
4. 读取 <self-improve-root>/state/agent-settings.json。检查 si_setting_goal、si_setting_benchmark、si_setting_harness。
5. 信任确认（强制，不可跳过）： a. 若 agent-settings.json 中的 trust_confirmed 已为 true，跳到第 5 步（恢复路径）。 b. 显示目标仓库路径并请用户确认： "Self-improve 将在 {repo_path} 内运行基准测试命令。这会在该仓库中执行任意代码。确认？[yes/no]" c. 若用户拒绝：中止设置并退出。不要继续。 d. 记录同意：在 agent-settings.json 中设置 trust_confirmed: true。
6. 当解析出的根目录按主题划分时，将 topic_slug 持久化到 config/settings.json，以便以后的恢复保持在同一轨道上。
7. 若未设置目标 → 从本技能目录读取 si-goal-clarifier.md，并直接在此上下文中运行 4 维度苏格拉底式访谈（目标、指标、目标值、范围）。将结果写入 <self-improve-root>/config/goal.md。
8. 若未设置基准 → 从本技能目录读取 si-benchmark-builder.md，以其中内容作为提示词启动一个自定义 Agent(model=opus)。该 Agent 调研仓库、创建或封装基准、验证 3 次并记录基线。 基准设置完成后，与用户确认基准命令： "基准命令：{benchmark_command}。这将在循环中反复运行。确认？[yes/no]" 若用户拒绝：中止设置并退出。
9. 若未设置护栏 → 与用户确认默认护栏规则（H001/H002/H003）或进行自定义。
10. 门禁：si_setting_goal、si_setting_benchmark、si_setting_harness、trust_confirmed 必须全部为 true。
11. 创建改进分支（若不存在）：

    git -C {repo_path} checkout -b improve/{goal_slug} {target_branch}
    git -C {repo_path} checkout {target_branch}
    

    其中 {goal_slug} 由目标宗旨派生（小写、下划线）。若分支已存在，跳过创建。将 goal_slug 持久化到 agent-settings.json。
12. 模式互斥：调用 state_list_active。若 autopilot 或 ralph 处于活动状态，拒绝启动。
13. 写入初始状态：state_write(mode='self-improve', active=true, iteration=0, started_at=<now>)

---

Git 策略

所有 git 操作都在目标仓库中执行，而不是在 OMC 项目根目录中。

• 改进分支：improve/{goal_slug} — 仅累积胜出的更改。
• 实验分支：experiment/round_{n}_executor_{id} — 生命周期短，每个执行器各有一个。
• 归档标签：archive/round_{n}_executor_{id} — 删除前为落败分支打标签。
• 工作树设置（SKILL.md 会在每个执行器运行前创建）：

  git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}
  

• 通过 oh-my-claudecode:git-master 合并胜出分支：

  Merge experiment/round_{n}_executor_{winner_id} into improve/{goal_slug} with --no-ff
  Message: "Iteration {n}: {hypothesis} (score: {before} → {after})"
  

• 合并后推送：git -C {repo_path} push origin improve/{goal_slug}（备份操作，不阻塞流程）
• 归档落败分支：通过 git-master 打标签并删除。

---

改进循环

门槛：所有设置都必须为 true。门槛通过后，持续执行，不要停止。

更新 state_write(mode='self-improve', active=true, status="running")。

步骤 0 — 清理陈旧工作树（必须，每次迭代都运行）

前置条件：此步骤必须在任何其他步骤（包括恢复逻辑）之前运行完毕。该操作具有幂等性，可安全地多次运行。

1. 列出目标仓库中的所有工作树：git -C {repo_path} worktree list
2. 对于任何匹配 worktrees/round_* 且不属于当前迭代的工作树，使用 git -C {repo_path} worktree remove {path} --force 将其移除
3. 运行 git -C {repo_path} worktree prune 清理陈旧引用
4. 此步骤用于崩溃恢复——在新一轮迭代开始前，清理被中断迭代遗留的孤立工作树

步骤 1 — 刷新状态

运行 state_write(mode='self-improve', active=true, iteration=N)，重置 30 分钟 TTL。

步骤 2 — 检查停止请求

通过 state_read(mode='self-improve') 读取状态。

如果状态已清除（已调用取消操作）或状态为 user_stopped： a. 在 <self-improve-root>/state/agent-settings.json 中设置 status: "user_stopped" b. 更新 iteration_state.json：设置 status: "interrupted"，记录 current_step c. 清理当前轮次的所有活动工作树（按步骤 0 的逻辑） d. 记录日志："Self-improve stopped by user at iteration {N}, step {current_step}" e. 正常退出——不要再次调用 /cancel（已取消）

步骤 3 — 检查用户想法

读取 <self-improve-root>/config/idea.md。如果内容非空，为规划器保存快照。规划器使用后清空。

步骤 4 — 调研

生成 1 个通用 Agent(model=opus)，并将 si-researcher.md 的内容作为提示词。

在提示词中传入：

• 当前迭代编号
• 目标仓库的路径
• <self-improve-root>/config/goal.md 的路径
• <self-improve-root>/state/iteration_history/ 的路径（所有过往记录）
• <self-improve-root>/state/research_briefs/ 的路径（过往简报）
• data_contracts.md 第 3 节的内容（Research Brief 架构）

预期输出：研究简报 JSON → <self-improve-root>/state/research_briefs/round_{n}.json

如果研究员失败，则仅使用历史记录继续。

步骤 5 — 规划

并行生成 N 个 oh-my-claudecode:planner(model=opus) Agent（N = 设置中的 number_of_agents）。

在每个规划器的提示词中传入：

• 规划器身份（planner_a、planner_b、planner_c……）
• 研究简报路径
• 迭代历史路径
• <self-improve-root>/config/harness.md 中的 Harness 规则
• Plan Document 的数据契约架构
• 覆盖指令：输出 JSON（而非 Markdown），跳过访谈模式，每份计划恰好提出一个可测试的假设，并包含 approach_family 标签和 history_reference。
• 用户想法（如有，优先提供给 planner_a）

预期输出：Plan Document JSON → <self-improve-root>/plans/round_{n}/plan_planner_{id}.json

步骤 6 — 审查

对于每个计划，并行启动架构师和评论员（两者都是 Claude Agent）：

6a. 架构审查：使用计划和 6 点检查清单启动 oh-my-claudecode:architect：

1. 可测试性 — 假设是否可测试？
2. 新颖性 — 是否不同于之前的尝试？
3. 范围 — 大小是否合适？
4. 目标文件 — 是否存在且未封存？
5. 实现清晰度 — 执行者能否无需猜测即可实现？
6. 预期结果 — 根据现有证据是否现实？

架构师的结论仅供参考。

6b. 评论员审查：使用计划和测试框架规则启动 oh-my-claudecode:critic：

• H001：恰好一个假设（如果为零个或多个，则拒绝）
• H002：approach_family 重复连续次数 >= 3
• H003：轮内多样性（同一轮中的计划不得属于相同系列）
• 根据 data_contracts.md 验证架构
• 检查历史记录

评论员设置 critic_approved: true 或 false。false 的计划将从执行中排除。

如果所有计划都被拒绝，则记录并跳至步骤 9。

步骤 7 — 执行

对每个已批准的计划，并行启动 oh-my-claudecode:executor(model=opus)。

启动前，创建工作树：

git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}

在每个执行者的提示词中传入：

• 已批准的计划 JSON
• 工作树目录路径
• 设置中的基准测试命令
• 设置中的封存文件列表
• 此技能目录中 scripts/validate.sh 的路径
• Benchmark Result 的数据契约架构
• 覆盖指令：忠实实现计划，在进行基准测试前运行 validate.sh，运行基准测试命令，并输出 Benchmark Result JSON。

预期输出：Benchmark Result JSON（由执行者写入文件或作为输出返回）。

步骤 8 — 锦标赛选择

SKILL.md 直接执行此步骤（不委派）：

1. 收集所有执行者结果
2. 仅筛选 status: "success" 的结果。如果候选项为零，则跳至步骤 9（记录与可视化）。
3. 根据 benchmark_score 排序（遵循 benchmark_direction）
4. 按排名遍历候选项 — 按排名顺序（从最佳开始）逐一处理每个候选项： a. 无回归检查：遵循 benchmark_direction，候选项分数必须优于或持平于 best_score（higher_is_better：score >= best_score；lower_is_better：score <= best_score） b. 通过 oh-my-claudecode:git-master 合并：git merge experiment/round_{n}_executor_{id} --no-ff -m "Iteration {n}: {hypothesis} (score: {before} → {after})" c. 在合并后的状态上重新运行基准测试以确认改进 d. 如果重新运行基准测试确认有改进：接受胜出者，退出循环 e. 如果重新运行基准测试显示回归：通过 git -C {repo_path} reset --hard HEAD~1 还原合并，继续检查下一个候选项 f. 如果合并发生冲突：运行 git -C {repo_path} merge --abort，继续检查下一个候选项
5. 如果接受了胜出者，且设置中的 auto_push 为 true：推送改进分支：git -C {repo_path} push origin improve/{goal_slug}（非阻塞）。 如果 auto_push 为 false（默认值）：跳过推送。记录："Push skipped (auto_push: false). Run manually: git -C {repo_path} push origin improve/{goal_slug}"
6. 通过 git-master 归档所有非胜出分支：添加标签并删除
7. 如果没有候选项通过此循环：本轮不进行合并。改进分支保持先前状态。
8. 将 Merge Report JSON 写入 <self-improve-root>/state/merge_reports/round_{n}.json（架构：data_contracts.md 第 9 节）。

步骤 9 — 记录与可视化

1. 将迭代历史写入 <self-improve-root>/state/iteration_history/round_{n}.json
2. 更新 <self-improve-root>/state/agent-settings.json：
   • 将 iterations 加 1
   • 如果有胜出方案，且改进幅度超过 plateau_threshold（abs(new_score - best_score) >= plateau_threshold）：更新 best_score，将 plateau_consecutive_count 重置为 0，将 circuit_breaker_count 重置为 0
   • 如果有胜出方案，且改进幅度低于阈值（abs(new_score - best_score) < plateau_threshold）：如果表现更好，则更新 best_score；将 plateau_consecutive_count += 1，将 circuit_breaker_count 重置为 0
   • 如果没有胜出方案（全部被拒绝、全部失败或全部退步）：将 circuit_breaker_count += 1（不要增加 plateau_consecutive_count——平台期统计的是停滞不前的胜出方案，而不是失败）
3. 在 <self-improve-root>/tracking/raw_data.json 末尾追加内容（每个候选方案一条记录）
4. 运行 python3 {skill_dir}/scripts/plot_progress.py --tracking-dir <self-improve-root>/tracking 以生成可视化
5. 归档计划：将当前轮次的计划复制到 state/plan_archive/round_{n}/

步骤 10 — 清理

移除工作树：

git -C {repo_path} worktree remove worktrees/round_{n}_executor_{id} --force
git -C {repo_path} worktree prune

将 iteration_state.json 中的状态更新为 completed。

步骤 11 — 检查停止条件

评估所有条件。如果任一条件为真，则退出：

条件	检查方式
用户停止	agent-settings 中 status == "user_stopped" 或状态已清除
达到目标	best_score 达到或超过 target_value（遵循方向设置）
平台期	plateau_consecutive_count >= plateau_window
最大迭代次数	iterations >= max_iterations
熔断器	circuit_breaker_count >= circuit_breaker_threshold

如果没有停止条件成立：立即返回步骤 1。

---

可恢复性

前提条件：在执行任何恢复逻辑之前，必须先完整执行步骤 0（清理过期工作树），无论先前状态如何。

调用时，在进入循环之前：

1. 始终运行步骤 0（清理过期工作树）——即使是全新启动
2. 读取 <self-improve-root>/state/agent-settings.json：
   • 如果 status: "user_stopped"：询问用户 "Previous run was stopped at iteration {N}. Resume? [yes/no]"。如果回答 no，则退出；如果回答 yes，则继续。
   • 如果 status: "running"：会话已崩溃——自动恢复（不询问用户）
   • 如果 status: "idle"：全新启动
3. 仅当 agent-settings.json 中的 trust_confirmed 为 false 时，重新确认信任门控
4. 读取 <self-improve-root>/state/iteration_state.json：
   • status: "in_progress" → 从 current_step 恢复，跳过已完成的子步骤
   • status: "completed" → 开始下一轮迭代
   • status: "failed" → 如有需要，完成记录步骤，然后开始下一轮迭代
   • 文件不存在 → 从第 1 轮迭代开始

---

完成

循环退出时：

1. 使用最终状态更新 agent-settings.json
2. 如果 target_reached 且设置中的 auto_pr 为 true：启动 git-master，从 improve/{goal_slug} 向上游创建 PR。 如果 auto_pr 为 false（默认值）：跳过创建 PR。记录："PR creation skipped (auto_pr: false). Run manually: gh pr create --head improve/{goal_slug} --base {target_branch}"
3. 最后再运行一次 plot_progress.py
4. 打印摘要报告：

   === Self-Improvement Loop Complete ===
   Status: {status}
   Iterations: {iterations}
   Best Score: {best_score} (baseline: {baseline})
   Improvement: {delta} ({delta_pct}%)
   

5. 运行 /oh-my-claudecode:cancel 以清理状态

---

错误处理

情况	操作
Agent 未能生成输出	重试一次。如果仍无输出，则记录并继续。
研究者生成的简报为空	继续——规划者仅依据历史记录开展工作。
评论者拒绝所有计划	跳过执行。记录情况。继续下一轮迭代。
所有执行者均失败	跳过锦标赛。记录失败情况。继续。
合并冲突	拒绝该候选方案，尝试下一个。
重新基准测试出现退步	拒绝该候选方案，撤销合并，尝试下一个。
推送失败	记录警告。继续——推送是备份操作。
工作树已存在	移除并重新创建。
设置损坏	报告问题并停止。

---

并行会话注意事项

• 多仓库工作区锚点： 在父目录中放置 .omc-workspace 标记，让多个子仓库中的会话共用一个 .omc/。解析顺序：OMC_STATE_DIR > .omc-workspace > git > cwd。参见 docs/REFERENCE.md。
• 会话 ID 来源： 在 CLI 上下文中，OMC_SESSION_ID 环境变量优先；在 hook 上下文中，hook payload 的 data.session_id 优先。
• 计划 ID（如适用）： 自我改进产物目录按主题 slug 划分；在同一工作区中以同一主题并行运行时，预计会采用 Wave B2 的会话 ID 后缀。
• 并行判定： 支持但有注意事项（可能发生主题 slug 冲突；参见 Wave B2）

方法系列分类

每个计划必须且只能标记以下一项：

标签	描述
architecture	模型／组件结构变更
training_config	优化器、LR、调度器、批量大小
data	数据加载、增强、预处理
infrastructure	混合精度、分布式训练、编译内核
optimization	算法／数值优化
testing	评估方法变更
documentation	仅修改文档
other	不符合以上类别——请在证据中说明