meta-optimize

Meta-Optimize：面向 ARIS 的外循环 Harness 优化

每次评审前，请遵循可选评审者： 解析调用 → .aris/reviewer.json → 默认使用 Claude Code（Codex MCP）， 并通过规范的辅助解析器使用 reviewer_route.py，保留本次评审档位、 全新上下文、源文件／图像输入和确定性门禁。 下方的 Codex 示例／固定配置仅适用于 backend=codex；其他路由使用各自的 首次调用／回复约定。保存路由和实际返回的身份； 无法使用所选评审者时，标记为 REVIEW_UNAVAILABLE。根据实际 家族／完成情况／范围对验收进行分类。将调用中指定的评审者／模型／工作量覆盖项 传递给需要评审者的子任务。生成工作线程保持不变。

分析累积的使用日志，并针对以下内容提出优化建议：$ARGUMENTS

权限边界 — 此技能是只读产出者

meta-optimize 只提出建议，不落地修改。对技能语料库的修改是另一项由人工调用的技能 /meta-apply 的专属职责。 这种分离是结构性的，而非建议性的——它确保即使遗漏了某条指令，本循环也不能自行应用补丁（即自我免责故障模式）：

• 没有 Write／Edit 工具。 此技能无法使用便捷修改工具编辑 SKILL.md／共享参考／ 任何语料库文件。它的唯一输出是报告和暂存补丁文件，写入 .aris/meta/ 下（该目录是临时工作区，不属于语料库）。
• 没有应用步骤。 技能内部没有“应用补丁”的途径（见步骤 6）。产出者的最后操作是为 /meta-apply 暂存已批准的补丁；之后必须由人工调用 /meta-apply 才能落地修改。 人工操作就是落地门禁。
• 通过 Bash 写入语料库的行为会被过滤，但并非绝无可能——请如实说明各层防护。 真正完全封闭的是：意外／流程内的自我免责——此技能没有 Write／Edit 工具， 也没有应用步骤，因此正常执行时无法悄然编辑语料库。纵深防御：安装 corpus_write_guard PreToolUse hook（与 meta_logging.json 类似），它会 DENY 常见的 Bash shell 写入操作（>、tee、 sed -i、cp／mv、touch、open(...,'w')）写入语料库路径。这是一份黑名单， 并非完整沙箱——刻意隐藏的 Bash 写入（git apply、patch、 $var／绝对路径、语言的文件 API）并不会全部被拦截。要实现完全的结构性防护，必须移除 此技能的 Bash 工具，或使用文件系统沙箱——对于尚未承担关键职责的产出者而言，这是过度设计，因此推迟到门禁需要承载大量自动修改时再处理（即砖块 3 的触发条件）。针对蓄意写入的预期后备措施是检测，而非阻止——如果语料库变更没有有效／最新的 provenance 标记（内容哈希不匹配），本可通过推送前完整性检查捕获——但该校验器尚未构建 （provenance.py 有 content_hash，但没有完整性检查子命令，也没有推送前 hook 会运行该检查）。 因此目前，蓄意写入既不会被阻止，也不会被主动检测；在此产出者承担关键职责前，请将完整性校验器列为后续任务。合法的 Bash 写入操作仅会写入 .aris/meta/。

请参阅shared-references/acceptance-gate.md： 循环可以由同一模型驱动（提出建议、评审），但让变更得以落地的免责裁定必须跨模型（步骤 4 的陪审团），并且落地必须是单独经过人工门禁的操作（/meta-apply）。

上下文

ARIS 是一个研究框架——由技能、桥接、工作流和产物契约组成的系统，围绕大模型构建，用于编排研究。此技能实现了一个原型外层循环，用于观察框架的使用情况，并提出对框架本身的改进建议（而非对其生成的研究产物提出建议）。

灵感来自 Meta-Harness（Lee 等人，2026 年）：核心观点是，框架设计与模型权重同样重要；通过记录执行轨迹并据此指导改进，框架工程可以实现部分自动化。

此技能优化的内容（框架组件）

组件	示例	可优化？
SKILL.md 提示词	审查者说明、质量关卡、步骤描述	是
默认参数	difficulty: medium、MAX_ROUNDS: 4、threshold: 6/10	是
收敛规则	何时停止审查循环、重试次数	是
工作流顺序	工作流中的技能链顺序	是
产物架构	EXPERIMENT_LOG.md、idea-stage/IDEA_REPORT.md 中包含哪些字段	谨慎
MCP 桥接配置	使用哪个审查者模型、路由规则	否（基础设施）

不优化：研究产物本身（论文、代码、实验）。这些由常规工作流负责。

前提条件

1. 必须启用日志记录。 将 templates/claude-hooks/meta_logging.json 复制到项目的 .claude/settings.json（或合并其中的 hooks 部分）。
2. 数据量必须充足。 .aris/meta/events.jsonl 中至少记录了 5 次完整的工作流运行。如果数据不足，此技能会进行检查并发出警告。

工作流

步骤 0：检查数据是否可用

EVENTS_FILE=".aris/meta/events.jsonl"
if [ ! -f "$EVENTS_FILE" ]; then
    echo "ERROR: No event log found at $EVENTS_FILE"
    echo "Enable logging first: copy templates/claude-hooks/meta_logging.json into .claude/settings.json"
    exit 1
fi

EVENT_COUNT=$(wc -l < "$EVENTS_FILE")
SKILL_INVOCATIONS=$(grep -c '"skill_invoke"' "$EVENTS_FILE" || echo 0)
SESSIONS=$(grep -c '"session_start"' "$EVENTS_FILE" || echo 0)

echo "📊 Event log: $EVENT_COUNT events, $SKILL_INVOCATIONS skill invocations, $SESSIONS sessions"

if [ "$SKILL_INVOCATIONS" -lt 5 ]; then
    echo "⚠️  Insufficient data (<5 skill invocations). Continue using ARIS normally and re-run later."
    exit 0
fi

# Bottleneck succession: what did the LAST cycle say was the limiting stage?
BOTTLENECK_LOG=".aris/meta/bottleneck_log.jsonl"
if [ -f "$BOTTLENECK_LOG" ]; then
    echo "🧭 Prior cycle's bottleneck: $(tail -1 "$BOTTLENECK_LOG")"
fi

如果存在先前的瓶颈记录，则在打开报告（步骤 5）时，先说明该记录中提到的瓶颈是否已解决（以及由哪些已落地的补丁解决），以及瓶颈现在转移到了哪里——瓶颈的演进，而不只是其存在与否，才是这份记录旨在传达的信号。

步骤 1：分析使用模式

读取 .aris/meta/events.jsonl 并计算：

频率分析：

• 哪些技能调用最频繁？
• 用户最常输入哪些斜杠命令？
• 哪些参数覆盖最常见？（这可能说明默认值不合适。）

失败分析：

• 哪些工具最常失败？出现在哪些技能中？
• 哪些错误模式反复出现？（OOM、导入、编译、超时）
• 每次工作流运行会进行多少次自动调试重试？

收敛分析（针对 auto-review-loop）：

• 达到阈值平均需要多少轮？
• 分数变化轨迹是什么形态？（快速提升？趋于平稳？振荡？）
• 哪一轮评审发现的关键问题最多？
• 用户是否会在运行过程中覆盖难度设置？

人工干预分析：

• 用户会在工作流的哪些环节插入手动提示词？
• 用户最常进行哪些手动修正？（这些可能说明技能存在缺口。）

模型差异分析（精简 harness）：

• 会话模型（session_start 事件的 model 字段）或固定的评审模型，是否在某项技能的 SKILL.md 上次修改后发生了变化？ （比较 git log -1 --format=%cs -- skills/<skill>/SKILL.md 与模型升级日期。）
• 模型升级是重新阅读的触发条件，而非其本身的证据。对于该 SKILL.md 中的每个推理辅助步骤或示例，删除提案都必须引用针对该目标的证据，证明新模型不再需要它：能力专属的发行说明，或事件日志中反复观察到的行为（例如，自模型升级以来，受该步骤保护的环节未发生任何失败或干预）。“模型更新了”本身绝不能成为删除的理由。
• 无论模型如何，以下内容都绝不能列为删除候选：权限边界、验收／评审关卡、语料库和来源完整性规则、输出约定，以及安全检查。精简只针对模型补偿性辅助内容——新模型原生具备的能力纯属额外负担（上下文占用、偏移风险、阅读成本）。只会不断增长的 harness，最终没人会重新阅读。

触发率分析（可选，基于实测，不来自事件日志）：

• 事件日志能显示哪些技能已被使用，但无法显示哪些技能本应被使用却被遗漏——它看不到遗漏这一失败模式（当已安装技能列表过长时，Claude Code 跳过了合适的技能）。tools/meta_opt/trigger_eval.py 可直接测量这一点：它会在中立工作目录中运行带有释义意图查询的 claude -p 探测（因此会加载真实的长安装语料），并将结果评为触发、混淆（→哪项技能）或未触发。
• 当怀疑某项技能触发不足或触发错误时，或修改描述前后进行对比时，可运行： python3 tools/meta_opt/trigger_eval.py --eval-file tools/meta_opt/trigger_evals.sample.json --skills <name> --samples 2
• 混淆矩阵才是关键信号，而不只是触发率：如果某个查询总是落到同类技能上，就说明两者的描述在该意图上存在重叠——解决方法是消除歧义，而不是“让描述更积极地推销自己”。
• 仅用于测量，是证据而非裁决。 低触发率可作为步骤 2 提案的输入（提案仅通过 /meta-apply 生效），绝不能据此自行改写描述。触发率取决于模型，因此比较时要保持条件一致（记录探测所用模型），并将其视为代理指标——它衡量的是在给定查询集下的选择情况，而非完整的长列表遗漏问题。

以结构化摘要表的形式呈现发现。

步骤 1.5：命名当前瓶颈

综合步骤 1 的分析，用一句话指出当前限制最大的单个流水线阶段，例如“规划”“验证质量”“实验执行可靠性”或“写作润色”，并提供支持证据。瓶颈总在变化：当编码不再是限制因素时，规划就会成为瓶颈；规划问题解决后，验证会成为瓶颈；验证实现自动化后，品味会成为瓶颈。本步骤旨在让当前的限制因素一目了然，使步骤 2 的排序表能够围绕一个已命名的限制因素列出子改进，而不是罗列零散调整。

将结论追加到仅追加的日志 .aris/meta/bottleneck_log.jsonl（遵循 .aris/runs/<run_id>.iterations.jsonl 的不可更改原则）：

mkdir -p .aris/meta
# json.dumps, NOT hand-interpolated shell strings: bottleneck/evidence are
# natural language — a stray quote must not break the JSONL (or the shell).
python3 - <<'PY'
import json, datetime
entry = {
    "ts": datetime.datetime.now().astimezone().isoformat(timespec="seconds"),
    "cycle": 3,
    "bottleneck": "verification quality",
    "evidence": "review rounds plateau at 6/10 while tool failures are rare",
    "top_patch_ids": ["P1", "P2"],
}
with open(".aris/meta/bottleneck_log.jsonl", "a", encoding="utf-8") as fh:
    fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
PY

绝不编辑或删除之前的行——保留演进历史才是关键。

步骤 2：确定优化目标

根据步骤 1，按预期影响对优化机会排序：

## Optimization Opportunities (ranked)

| # | Target | Signal | Proposed Change | Expected Impact |
|---|--------|--------|-----------------|-----------------|
| 1 | auto-review-loop default threshold | Users override to 7/10 in 60% of runs | Change default from 6/10 to 7/10 | Fewer manual overrides |
| 2 | experiment-bridge retry count | 40% of runs hit max retries on OOM | Add OOM-specific recovery (reduce batch size) | Fewer failed experiments |
| 3 | paper-write de-AI patterns | Users manually fix "delve" in 80% of runs | Add "delve" to default watchword list | Fewer manual edits |
| 4 | experiment-bridge Phase-2 hand-holding steps | Model bump (session_start model changed); scaffold untouched since 2 generations ago; zero tool_failures in the steps it guards | **DELETE steps N–M — the new model does this unprompted** | Smaller harness, less drift surface |

“拟议更改”列明确允许填写删除——“删除步骤 N，新模型可以免费完成这项工作”属于一等优化，并按与新增内容相同的影响逻辑排序。

如果 $ARGUMENTS 指定了目标技能，则只分析该技能。 如果 $ARGUMENTS 为空或为 "all"，则分析所有数据充足的技能。

步骤 3：生成补丁提案

针对每个优化目标，生成一个具体的差异：

--- a/skills/auto-review-loop/SKILL.md
+++ b/skills/auto-review-loop/SKILL.md
@@ -15,7 +15,7 @@
 ## Constants
 
-- **SCORE_THRESHOLD = 6** — Minimum review score to accept.
+- **SCORE_THRESHOLD = 7** — Minimum review score to accept. (Raised based on usage data: 60% of users overrode to 7+.)

补丁生成规则：

• 每个优化目标对应一个补丁
• 每个补丁都必须附带注释，说明原因（并引用日志中的数据）
• 补丁必须尽量精简——只更改数据所支持的内容
• v1 中绝不更改工件架构或 MCP 桥接配置
• 绝不更改会破坏现有用户工作流的行为
• 防止自我毒化检查（参见 shared-references/capture-antipatterns.md）： 使用 tools/capture_filter.py 检查拟议补丁的理由（通过规范链解析）。绝不提出会将负面的工具能力断言（“codex 不能……”或“gemini 坏了”）或一次性／暂时性失败固化为持久规则的更改——这些会逐渐变成引用自身的拒绝。应记录修复方法／所需标记／变通方案，而不是“X 不能做 Y”。

步骤 4：对补丁进行跨模型评审（建议性预筛选）

此评审仅供参考——它会完善步骤 5 的报告，帮助人工决定要暂存哪些更改。它不是最终批准结论。具有约束力的跨模型评审将在稍后的应用阶段进行，位于 /meta-apply 中，并针对实际暂存的差异（由生成方转交的结论可能伪造）。仅将此结果记录为 advisory_screen。

将每个补丁提交给 GPT-6-Astra xhigh 进行对抗性评审：

请先解析此评审者槽位；以下是 backend=codex 示例。

mcp__codex__codex:
  model: gpt-6-astra
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    You are reviewing a proposed optimization to an ARIS SKILL.md file.
    
    ## Original Skill (relevant section)
    [paste original]
    
    ## Proposed Patch
    [paste diff]
    
    ## Evidence from Usage Log
    [paste summary stats]
    
    Review this patch:
    1. Does the evidence support the change?
    2. Could this change hurt other use cases?
    3. Is the change minimal and safe?
    4. Score 1-10: should this be applied?
    
    If score < 7, explain what additional evidence would be needed.

    === SCOPE LIMITS (these bound what you PROPOSE, never what you look for) ===
    Report anything that is actually wrong here — including a rare-looking case, if
    this repo actually produces it. Then keep the fix in scope:
    1. This is a RESEARCH-WORKFLOW tool, not a security paper. Verification is
       welcome; over-defense is not. Assume a cooperating operator on their own
       machine — a malicious local user is NOT in the threat model.
    2. Do NOT propose SHA / hash / content-fingerprint / digest-binding schemes.
       Reporting a real defect in hashing code that already exists is fine.
    3. NO speculative machinery: do not add feature flags, migration frameworks,
       compat layers, wrappers, pins, or similar mechanisms unless evidence shows
       a current repo defect they fix or an explicit existing invariant they must
       preserve. "Load-bearing", "compatibility", and "not scaffolding" are labels,
       not evidence. Point to the failing path/artifact or invariant, and check the
       proposal's factual premises, such as whether a named package version exists.
    4. NO corner-case obsession: exotic encodings, symlink races, RTL text and
       millisecond races are out of scope unless you can show the case arises here.
    5. Where a rubric or checklist is genuinely needed, do not over-mechanize
       judgement. A clear sentence a human reads beats a scored table nobody
       maintains.
    Exception: code that runs remote commands, starts a network service, or installs
    an MCP server runs on the user's machine with their credentials — trust-boundary
    findings there are in scope and the default is strict.
    Say plainly when something is correct. Do not manufacture findings.

步骤 5：呈现结果

输出结构化报告：

# ARIS Meta-Optimization Report

**Date**: [today]
**Data**: [N] events, [M] skill invocations, [K] sessions
**Target**: [skill name or "all"]

## Current Bottleneck

**[one-phrase name]** — [one-line evidence]. Prior cycle's bottleneck: [name —
resolved by <patch ids> / unresolved / first recorded cycle]. (Ledger:
`.aris/meta/bottleneck_log.jsonl`)

## Proposed Changes

### Change 1: [title]
- **Target**: [skill/file:line]
- **Signal**: [what the data shows]
- **Patch**: [diff]
- **Reviewer Score**: [X/10]
- **Reviewer Notes**: [summary]
- **Status**: ✅ Recommended / ⚠️ Needs more data / ❌ Rejected

### Change 2: ...

## Changes NOT Made (insufficient evidence)
- [pattern observed but too few samples]

## Recommendations
- [ ] Apply Change 1 (reviewer approved)
- [ ] Collect more data for Change 3 (need N more runs)
- [ ] Consider manual review of Change 2

## Next Steps
This skill only **proposes**. To land changes: tell me which to stage, then run
`/meta-apply` (a separate, human-invoked applier that re-checks the cross-model
verdict before mutating anything). meta-optimize never applies.

第 6 步：为 /meta-apply 暂存已批准的补丁（技能内不得应用）

此技能不会应用任何更改。用户阅读第 5 步的 REPORT 并指出要落实哪些更改后，将其暂存以供特权应用器使用：

1. 对每项已批准的更改 N，将其统一差异写入 .aris/meta/pending/<NN>_<skill>.diff，并在 .aris/meta/pending/manifest.jsonl 中追加一行： {patch: "<NN>_<skill>.diff", target: "<corpus path>", author_model: "<executor>", advisory_screen: "pass|kill", advisory_reason: "<one line>"}。 advisory_screen（第 4 步的 codex 预审）仅供参考，有助于人工阅读 REPORT。它不是落实裁定，/meta-apply 也不会信任它：由补丁生成者编写的裁定可以伪造。具有约束力的跨模型评审团会在落实时，于 /meta-apply 内部对实际暂存的差异进行评审。
2. 告诉用户："已暂存 M 个补丁。运行 /meta-apply 以进行评审并落实。"

备份 → 落实时的新一轮评审团评审 → 应用 → 溯源盖章 → 日志记录，全部在 /meta-apply 内完成。meta-optimize 从不触碰语料库，也从不出具无罪裁定。

绝不要在此技能中应用更改。落实必须始终经过 /meta-apply、新一轮评审团评审和人工确认。

关键规则

• 以日志为依据，不凭空猜测。 每项提议的更改都必须引用事件日志中的具体数据。不能说“我觉得这样会更好”。
• 补丁越小越好。 一次只改一处。不要重写整个技能——唯一获准的大规模编辑是有特定目标模型差异证据支持的脚手架删除（能力专属的发行说明，或升级后反复出现的事件日志行为，表明该脚手架未被使用——模型名称变化只是触发检查的信号，绝非充分证据）。权限边界、验收门槛、语料库／溯源规则、输出约定和安全检查永远不能作为删除对象。删除内容也必须经过与其他更改相同的评审和批准门槛。
• 必须经过评审。 每个补丁在提出建议前都必须经过跨模型评审。
• 可逆。 应用前务必备份。务必记录更改内容。
• 经用户批准。 切勿自动应用。先展示并解释，再让用户决定。
• 如实说明不确定性。 如果数据不足，就如实说明。不要根据噪声进行优化。
• 可移植。 优化应惠及所有用户，而不仅是符合某一位用户的风格。如果更改似乎只适合特定用户，请标明。

事件架构参考

.aris/meta/events.jsonl 中的日志包含以下结构的 JSONL 记录：

{"ts":"...","session":"...","event":"skill_invoke","skill":"auto-review-loop","args":"difficulty: hard"}
{"ts":"...","session":"...","event":"PostToolUse","tool":"Bash","input_summary":"pdflatex main.tex"}
{"ts":"...","session":"...","event":"codex_call","tool":"mcp__codex__codex","input_summary":"review..."}
{"ts":"...","session":"...","event":"tool_failure","tool":"Bash","input_summary":"python train.py"}
{"ts":"...","session":"...","event":"slash_command","command":"/auto-review-loop","args":""}
{"ts":"...","session":"...","event":"user_prompt","prompt_preview":"change difficulty to hard"}
{"ts":"...","session":"...","event":"session_start","source":"startup","model":"claude-opus-4-6"}
{"ts":"...","session":"...","event":"session_end"}

触发方式

此技能不属于标准的 W1→W1.5→W2→W3→W4 流程。它是一个具有三种触发机制的维护工作流：

1. 被动记录（始终开启）：Claude Code 钩子会在正常使用期间自动将事件记录到 .aris/meta/events.jsonl。用户无需付出任何精力。

2. 自动就绪检查（SessionEnd 钩子）：Claude Code 会话结束时，check_ready.sh 会统计自上次运行 /meta-optimize 以来的技能调用次数。如果累计了 ≥5 次新调用，就会打印提醒：

   📊 ARIS has logged 8 skill runs since last optimization. Run /meta-optimize to check for improvement opportunities.
   

   此外，如果会话模型与上次优化时不同（与 .aris/meta/.last_optimize_model 比较），无论调用次数多少，都会触发：

   🔁 Model changed since last optimization (claude-opus-4-6 → claude-opus-4-8). Run /meta-optimize — a model bump makes existing scaffolding a deletion candidate (harness diet).
   

   两者都只是建议——不会自动运行优化。

3. 手动触发：用户看到提醒后，或在任何需要的时候运行 /meta-optimize。

每次运行 /meta-optimize 后，技能都会将当前时间戳写入 .aris/meta/.last_optimize，并将当前会话模型（最新 session_start 事件的 model 字段）写入 .aris/meta/.last_optimize_model，以便就绪检查能够检测到新的使用记录和模型升级。

致谢

灵感来源于 Meta-Harness（Lee 等人，2026）——通过基于文件系统的经验访问和 Agent 式代码搜索，对模型执行环境进行端到端优化。

输出协议

所有输出文件均遵循以下共享协议：

• 输出版本控制协议 — 先写入带时间戳的文件，再复制到固定名称
• 输出清单协议 — 将每项输出记录到 MANIFEST.md
• 输出语言协议 — 遵循项目的语言设置

审查追踪

每次调用 mcp__codex__codex 或 mcp__codex__codex-reply 审查器后，按照 shared-references/review-tracing.md 保存追踪记录（策略 C — 取证；绝不悄然跳过）。使用 save_trace.sh（按照 shared-references/integration-contract.md §2 中的链解析路径），或直接将文件写入 .aris/traces/<skill>/<date>_run<NN>/。遵循 --- trace: 参数（默认值：full）。