autoresearch-hooks

autoresearch-hooks

可选脚本，会在 autoresearch 会话的迭代边界运行。两个钩子对运行循环的 Agent 都是透明的——它们的效果要么是写入磁盘上的文件，要么是发送引导消息。

.auto/hooks/
  before.sh    # fires before each iteration (prospective)
  after.sh     # fires after each log_experiment (retrospective)

两个文件都是可选的。没有可执行位的文件会被静默忽略。

---

约定

标准输入 — before.sh

一行 JSON。使用 jq 解析。实际示例：

{
  "event": "before",
  "cwd": "/path/to/workdir",
  "next_run": 6,
  "last_run": {
    "run": 5,
    "status": "discard",
    "metric": 42.1,
    "description": "Simplified to sorted(arr) — copy cost dominates",
    "asi": {
      "hypothesis": "Built-in sort avoids Python overhead",
      "next_focus": "list copy avoidance"
    }
  },
  "session": {
    "metric_name": "total_ms",
    "metric_unit": "ms",
    "direction": "lower",
    "baseline_metric": 40.7,
    "best_metric": 33.5,
    "run_count": 5,
    "goal": "optimize sort speed"
  }
}

字段	说明
last_run	最近一次运行条目。新会话中为 null。
session.direction	"lower" 或 "higher"——哪一端的数值更优。
session.baseline_metric	当前区段的首次运行指标。在至少有一次运行前为 null。
session.best_metric	仅在保留的运行中取得的最优指标。在至少有一次运行被保留前为 null。
session.goal	由 init_experiment 设置的会话名称。
session.run_count	目前记录的运行总数（包括所有状态）。

标准输入 — after.sh

{
  "event": "after",
  "cwd": "/path/to/workdir",
  "run_entry": {
    "run": 6,
    "status": "discard",
    "metric": 38.9,
    "description": "Timsort hybrid slower on random",
    "asi": {
      "hypothesis": "Partial-sort heuristic on input distribution",
      "learned": "Overhead dominates on random arrays"
    }
  },
  "session": {
    "metric_name": "total_ms",
    "metric_unit": "ms",
    "direction": "lower",
    "baseline_metric": 40.7,
    "best_metric": 33.5,
    "run_count": 6,
    "goal": "optimize sort speed"
  }
}

字段	说明
run_entry	刚刚记录的运行。始终存在。
session	与 before.sh 中结构相同，反映运行后的状态。

输出

• 标准输出（最多 8 KB）——会在下一轮作为引导消息发送给 Agent。为空 = 静默。
• 标准错误 + 非零退出码——作为错误引导消息呈现。
• 超时——30 s 后强制终止；会在可观测性条目中标记。

保留

自动还原后，.auto/** 仍会保留——整个 .auto/ 文件夹都会保留。（为正在进行的会话，也仍会保留旧版 autoresearch.* 路径。）

---

示例

可运行的参考脚本位于此技能的 examples/ 目录中——每种模式一个文件。路径以技能目录（SKILL.md 的父目录）为基准解析。可浏览这些示例以获取灵感；它们不是强制规范。

• examples/before/ — 外部搜索、qmd 文档搜索、防止反复试错、创意轮换、假设反思、上下文轮换
• examples/after/ — 经验记录日志、发现新最佳结果时发送 macOS 通知、自动标记获胜提交

每个示例都是完整且自包含的脚本，包含具名常量、简短辅助函数、守卫子句和意图明确的名称。阅读头部注释了解其用途，然后复制到 .auto/hooks/<stage>.sh 并进行调整。

---

添加钩子的步骤

1. 了解会话。 阅读 .auto/prompt.md，了解目标和指标；快速查看 .auto/measure.sh，了解工作负载。钩子应补充循环，而不是重复其功能。

2. 明确用户意图。 要在什么边界执行什么操作？事前研究 / 事后记录 / 获胜时通知 / 反复试错时介入 / 等等。

3. 从 examples/ 中选择最符合意图的示例作为起点（以技能目录为基准解析路径）。如果没有合适的示例，就按照相同风格从头编写（具名常量、简短函数、守卫子句、使用 jq 解析 JSON 标准输入）。如果请求同时涉及回顾和前瞻事项，请同时使用 before.sh 和 after.sh——不要把所有逻辑都塞进一个脚本。

4. 复制、调整并设置可执行权限。

   mkdir -p .auto/hooks
   cp "<skill-dir>/examples/before/external-search.sh" .auto/hooks/before.sh
   # ... adapt the script ...
   chmod +x .auto/hooks/before.sh
   

5. 在将其用于循环前，使用管道输入模拟数据进行健全性测试：

   jq -n '
     {
       event: "before",
       cwd: ".",
       next_run: 1,
       last_run: null,
       session: {
         metric_name: "total_ms",
         metric_unit: "ms",
         direction: "lower",
         baseline_metric: null,
         best_metric: null,
         run_count: 0,
         goal: "test"
       }
     }
   ' | ./.auto/hooks/before.sh
   

   对于 after.sh，将 last_run: null 替换为一个 run_entry 对象（参见上文的架构）。

6. 将钩子与其他会话文件一同提交。 因为钩子位于 .auto/ 下，所以在还原后仍会保留。

---

实用经验

• 读取 Agent 自然写入的字段——asi.hypothesis、asi.next_focus、asi.learned、description。不要凭空发明一个“钩子输入”字段并要求 Agent 填写；这会破坏透明性原则。

• 默认保持静默。 只有在有对 Agent 有用的信息时才输出到 stdout。stdout 为空表示无需引导。

• 使用提前退出进行保护。 [ -z "$query" ] && exit 0 比用 if 包裹所有内容更简洁清晰。

• 每个脚本只处理一个关注点。 如果需要研究和学习内容，请放在单独的文件中（before.sh 和 after.sh）。不要打包在一起。

• 不要使用环境变量。 所有内容都通过 stdin 传入；使用 jq 提取 cwd（以及其他所需内容）。不存在 $AUTORESEARCH_WORK_DIR。