Headlong是一个开源的 Agent 微内核（agent microharness），主打"持久智能体 + 递归 LLM"，一切基于 bash。它最有趣的扩展点叫thinker：每个 thinker 就是一个独立的"思考过程"，能订阅 Agent 的思维轨迹（trajectory），并在有新步骤写入时自动被唤醒处理。本文是一份面向新手的 Headlong thinker 扩展开发指南，带你从零写出自己的 Agent 扩展模块——只需要一个目录、一个step脚本和一个订阅文件。

什么是 thinker？Headlong 的 Agent 扩展机制

可以把 Headlong 的 identity（身份体）想象成一颗"大脑"，它的心智活动全部记录在一条根轨迹（root trajectory）上：每一次思考（thought）、行动（action）、观察（observation）、消息（message）都是一行 JSON。

thinker 就是订阅这条轨迹上的事件、并被事件唤醒的独立模块：

• 分发器（dispatcher）在后台tail跟踪轨迹文件；
• 每当有新步骤写入，dispatcher 匹配所有 thinker 的订阅规则；
• 命中的 thinker 的step脚本被调用，触发步骤的 JSON 通过stdin传入；
• thinker 处理后，把结果写回轨迹（用traj append），又会唤醒其他 thinker——由此实现并发与组合。

完整机制文档见 design/THINKERS_spec.md，模块总览见 thinkers/README.md。

💡 一个关键规则：thinker 写入轨迹的每个步骤都必须带"source":"<thinker名字>"字段，dispatcher 靠它做"防自触发"，避免你的模块对自己输出死循环。

动手前先读这三个内置 thinker

Headlong 自带三个参考实现，分别代表了三种典型形态，建议对照学习：

其中 thinkers/responder/subscriptions.jsonl 的内容极简，只有一行：

{"types":["message"]}

这就是最简单的订阅：任何message步骤都会唤醒它。而 thinkers/monolith/subscriptions.jsonl 则展示了带trigger_self的完整写法：

{"types":["observation","action","merge","monolith-wake"],"trigger_self":false}

一步创建新 thinker：scaffold 脚手架

在 identity 环境下（identity shell <name>进入），执行：

thinkers new my-thinker

CLI 实现位于 bin/thinkers 的cmd_new函数。一条命令即可在$THINKERS_DIR/my-thinker/下生成标准目录结构：

my-thinker/ step # 必填：每次匹配到步骤时被调用的可执行脚本 subscriptions.jsonl # 必填：订阅哪些步骤类型 prompt.md # 可选：shellm 型 thinker 的提示词模板 start / stop # 可选：thinkers start/stop 时调用（常驻进程用）

命名规则：小写字母、数字、连字符（不能带点号，pending 队列文件名按点分隔，见下文"进阶技巧"）。

编写 step 脚本：如何读取触发事件、写回结果

step是一个普通 bash 可执行文件，协议非常轻量：触发步骤的 JSON 从 stdin 进来，处理完退出即可。官方脚手架生成的骨架逻辑（节选自 bin/thinkers 中cmd_new生成的模板）：

#!/usr/bin/env bash set -euo pipefail step_json=$(cat) # 读取触发的 step JSON # ... 在这里实现你的逻辑：调 llm、跑 shellm、或直接处理 # 结果用 traj append 写回轨迹，记得带 source 字段

写回轨迹的标准写法（参考 thinkers/retrieval/step 第 71–74 行）：

jq -nc --arg c "I recalled something" --arg s "$THINKER_NAME" \ '{type:"observation", content:$c, source:$s}' | traj append

脚本运行时会拿到全套 identity 环境变量：

公共工具函数（加载环境、组装系统提示词、读取最近流等）都在 thinkers/_lib/common.sh，你的step里直接source "$SCRIPT_DIR/../_lib/common.sh"就能复用——三个内置 thinker 都是这么干的。

配置订阅文件：subscriptions.jsonl 字段速查

subscriptions.jsonl每行一个 JSON 对象，字段如下（详见 design/THINKERS_spec.md）：

常用步骤类型：thought、action、observation、message、merge、idle，还可以有自定义类型（如monolith-wake）。

⚠️ 注意：订阅是静态的，dispatcher 只在启动时读取一次。修改subscriptions.jsonl后必须重启分发器：

thinkers stop && thinkers start

启动与验证：确认你的 thinker 已接入

thinkers start # 启动 dispatcher（会调用各 thinker 的 start 脚本） thinkers list # 列出已安装 thinker 及其订阅信息 thinkers status # 查看 dispatcher 与各 thinker 状态

排查问题时看两个地方：

1. 日志：$IDENTITY_DIR/run/logs/<name>.log—— 每个 thinker 每次 step 的 stdout/stderr 都在这里；
2. 轨迹：traj tail查看你的 thinker 写回的步骤是否带上了正确的source字段。

进阶技巧：避开三个最常见的坑

1. 自触发与防死循环：默认trigger_self:false下，dispatcher 会自动把source等于你名字的步骤过滤掉。如果你希望"自我循环"（像 monolith 早期版本那样持续思考），需显式设trigger_self:true——但要保证每次唤醒都追加至少一个步骤，否则循环会断。

2. 并发时的 pending 队列：thinker 正忙时到达的步骤不会丢——message和action会按 FIFO 排队（每个 thinker 每类型最多 16 条），其他类型则"后到覆盖先到"（last-wins 合并）。所以 thinker 名字和步骤类型不能带点号。

3. 看门狗保活：对trigger_self型订阅，dispatcher 有 liveness watchdog——你的 thinker 若在某时间窗口内彻底安静，会被合成idle触发重新唤醒。即使你的脚本崩溃，最坏情况也只是延迟一个窗口时间，而不会"脑死亡"。

总结：Headlong thinker 开发的三步清单

想深入主循环设计，可继续阅读 design/monolith_thinker.md（monolith 的设计动机与函数菜单）和 design/monolith_backoff.md（唤醒退避时钟）。祝你在 Headlong 的 bash 世界里构建出属于自己的思维模块！ 🧠