laude-institute/headlong

来源: https://github.com/laude-institute/headlong

██ ██ █████ ████ █████ ██ ████ ██ ██ ████ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██▀▀██ ████ ██████ ██ ██ ██ ██ ██ ██▀███ ██ ███ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ▀██ ██ ██ ██ ██ ██ ██ █████ ██ ██ █████ █████ ████ ██ ██ █████ ██

CI (https://github.com/laude-institute/headlong/actions/workflows/ci.yml)

Headlong 是一个开源的智能体微框架，一个完整的智能体运行环境，其核心代码不到 10,000 行 Bash。Headlong 的显著特点是持久主体性。你的智能体在两次外部交互之间会保持思考，运行一个受人类内心独白启发的自主循环。人类发来的消息不会启动一个会话，而是作为又一条观察信息落入智能体的思维流，由智能体决定是否以及何时做出回应。你为你的智能体设定一个名字和个性，它就会自行确定兴趣和优先级，启动自己的项目，并在有话要说时主动联系你。

Headlong 智能体在设计上也支持共享。整个团队可以通过 Slack、Telegram 和聊天应用与同一个智能体交流，所有对话都会汇入该智能体单一的思维流。智能体会跟进不同人的工作，将他们联系起来，并在认为最相关时主动联系相应人员。共享一个智能体很有趣，因为它表现得更像一个人，而非一项服务。

Headlong 的核心是 shellm，一个用 Bash 实现的递归语言模型（RLM）(https://alexzhang13.github.io/blog/2025/rlm/)。智能体通过编写 shell 命令、执行它们并读取输出来进行思考。除了 Bash 之外，不需要任何工具系统。

快速开始

一行命令即可安装所有内容，通过访谈引导一个 Headlong 智能体诞生，并打开一个仪表板，让你观察其思维运行：

curl -fsSL https://headlong.ai/install.sh | bash

你需要 bash 3.2+、git、curl、jq 和一个大语言模型 API 密钥（Anthropic、OpenAI、Gemini 或 OpenRouter）；仪表板还需要 uv (https://docs.astral.sh/uv/) 和 bun 或 node，安装程序会为你获取这些依赖。

Headlong 是 alpha 阶段的研究软件。请使用一个有预算限制的专用密钥，因为你的智能体会运行真实的 shell 命令并全天候思考。在运行 Docker 的情况下，安装程序可以选择将整个智能体置于容器中，或者在你的机器上安装但智能体的命令在容器中沙箱化运行（也提供非沙箱的主机安装选项，需要显式确认，不推荐）。如果没有 Docker，命令将直接以你的身份在你的机器上运行，因此安装程序会停下来并要求显式确认才会设置此项。后台思考的开销取决于智能体循环的速度以及使用哪个模型。当无人与智能体对话时，思考频率会指数级降低，当消息到达时则会立即恢复。按照我们运行智能体的设置，每小时成本约为 1 到 2 美元。

智能体的名字将成为一个命令：

ada hello            # 发送一条消息，等待回复
ada                  # 进入聊天
ada stop / ada start # 暂停 / 恢复其思维
ada dash             # 打开仪表板
ada bugreport        # 打包日志和轨迹（密钥已脱敏）用于错误报告

如果你需要紧急停止按钮，headlong-killall 可以停止机器上所有 Headlong 相关进程。curl -fsSL https://headlong.ai/status.sh | bash 显示已安装和运行的内容；curl -fsSL https://headlong.ai/uninstall.sh | bash 则移除所有内容（详情见 docs/install.md）。

安装程序提供的容器流程如下，你也可以自行运行：

docker run -it --name headlong --restart unless-stopped -p 8080:8080 buildpack-deps:curl \
  bash -c 'curl -fsSL https://headlong.ai/install.sh | bash; exec bash'

详细信息、非交互式/CI 安装以及从检出代码安装的方法，请参阅 docs/install.md。

核心理念

• 持久主体性。 大多数框架是反应式的，或按计划唤醒执行固定清单。Headlong 智能体永不休眠，也没有清单。它会持续生成对它认为有趣事物的思考，即使没有外部输入。来自 Slack、Telegram 或聊天应用的消息作为观察信息被注入思维流，由智能体决定是否以及何时回应。经典的轮流请求/响应模式同样适用。
• 多人协作乐趣。 一个智能体，一个思维，多人参与。没有按用户划分的会话；智能体在单一时间线中体验其所有对话，并决定回复谁以及何时回复。这种单一的思维流也意味着人与人之间没有严格的隔墙：假设你告诉智能体的任何事都会与和它对话的所有人共享。
• 围绕 Ken Thompson 的哲学构建。 核心工具链是一系列小型 Bash 可执行文件（shellm、traj、llm、context、mem、skills 等），每个都做好一件事，并通过管道、文件和环境变量进行组合。模型编写 shell 命令，因此 curl 是 HTTP 客户端，jq 是 JSON 处理器。
• 智能体的轨迹是一个具有分叉和合并功能的 jsonl 文件有向无环图（DAG）。 智能体可以访问它思考和做过的所有事情，以及探索这些内容直至任何单个步骤的工具。
• 上下文是轨迹的一种投影。 没有任何信息会被原地压缩移除。压缩和智能体自省使用相同的工具操作相同的文件。
• 分层上下文压缩。 整个轨迹以指数衰减的分辨率保持在上下文中。近期条目原样呈现，较旧的条目则被逐步总结。这些层级充当索引，因此智能体可以在需要时检索原始条目。
• 子智能体可以看到其父代的轨迹。 子智能体可以了解它为何被创建、父代已经尝试过什么，以及它如何融入整体图景。
• 默认使用 Docker。 生成的代码只要 Docker 可用就会将自己沙箱化到容器中，并且容器重用使得重启成本很低。本地模式同样可行。
• 通过分叉、测试、合并实现自我改进。 智能体分叉 Headlong 代码库（并可选地分叉其自身的轨迹），进行修改并运行测试。如果成功，则合并更改；如果失败，则丢弃该智能体及其更改。无需回滚机制。我们在 Laude 运行的智能体就在本仓库的自己分叉中工作，我们已经将其 50 多个提交合并回了主分支。

完整的故事背景和设计理念详见 philosophy.md。

工具集

要创建一个最小的智能体，你需要：

• 一个循环重复生成下一个思维的组件（thinkers，它调用 llm），
• 一种让思维进行推理和行动的方法（shellm，Bash 作为唯一工具），
• 一种记录智能体轨迹（其至今的生命历程）的方法（traj），以及
• 一种将该轨迹转化为下一次调用大语言模型所需的上下文的方法（context）。

Headlong 还为智能体提供了一些便利工具，例如一种提炼和固化其经验的方法（mem）以及一种为专门任务保存和复用流程的方法（skills）。核心是运行思维执行的工具，即 bin/ 目录中的可执行文件加上 thinkers/ 中的思维过程，根据 cloc 统计共计 9.8K 行代码。如此小的框架可以通读，并且易于修改和实验。

所有在思维核心之外运行的工具位于 tools/ 目录：

了解更多

• philosophy.md — 阐述将 Ken Thompson 的哲学应用于智能体微框架的理由，以及完整的设计故事
• docs/shellm.md — shellm 引擎参考：循环、上下文传递、Docker 沙箱、环境变量、llm 工具、选项
• docs/install.md — 所有安装变体，包括 CI/非交互式和长期运行的 Docker
• AGENTS.md — 操作运行中的身份（面向人类和编程智能体）：路径、日志、健康检查、注意事项
• web/、slack/、telegram/ — 仪表板和聊天桥接器
• deploy/ — 在专用服务器上运行智能体（systemd 单元、terraform、运维）

致谢

shellm 中的递归语言模型思想部分来源于递归 LLM (https://github.com/andyk/recursive_llm) 实验（2023年4月）和 Alex Zhang 的递归 LM (RLM) (https://alexzhang13.github.io/blog/2025/rlm/) 项目（2025年10月）。Headlong 持久主体性背后的持续思考——以及其名称——则来源于 Headlong (https://github.com/andyk/headlong) 研究项目。

许可证

Apache 2.0. 版权所有 2026 Laude Institute。