laude-institute/headlong

Headlong – 基于 Bash 的持续性 AI 代理微框架

是什么

• 一个开源研究框架，可在您自己的机器（或 Docker 中）运行一个持续思考的 AI「代理」。核心代码约 11K 行 Bash，实现了 递归语言模型（RLM）：LLM 生成 Bash 命令，系统执行，将输出作为上下文反馈给模型，循环往复。
• 专为 持续性代理 设计——即使无人与其对话，代理也会持续生成思考，并自主决定何时以及如何回复。
• 支持 多用户交互：Slack、Telegram 或 Web 仪表板均接入同一共享思维流，多人可与同一代理对话。

核心概念

概念	含义
持续性代理	无请求/响应清单；代理运行一个循环，持续生成「思考」（shell 命令），仅在认为消息值得回复时才中断该循环。
递归语言模型（shellm）	LLM 接收当前上下文，返回 Bash 片段，片段被执行，其 stdout/stderr 成为下一轮上下文的一部分。这是模型唯一使用的「工具」——Bash 本身。
轨迹	一个仅追加的 JSON-L DAG，记录代理执行的每一条命令、输出和元数据。整个历史可被探索、分叉、合并或总结。
分层上下文压缩	最近条目保持原样；较旧条目逐步被总结，使模型以低成本保留长期记忆，而不超出 token 限制。
子代理	代理可生成继承父代理轨迹的子代理，支持层级化项目和自我改进。
Docker 容器沙箱	默认安装器在容器内运行代理，隔离生成的命令与主机。主机安装可行，但需显式确认「是」。

主要工具（均为小型 Bash 可执行文件）

• shellm – RLM 引擎（核心循环）。
• llm – 统一 CLI，支持 Anthropic、OpenAI、Gemini、OpenRouter 或任何 OpenAI 兼容的本地服务器（Ollama、llama.cpp、vLLM 等）。
• traj – 操作轨迹 DAG（追加、分叉、合并）。
• context – 将轨迹渲染为 LLM 兼容的消息数组，支持分层压缩。
• thinkers – 运行一个或多个思考进程的调度器。
• mem / skills – 基于文件的内存存储和可复用技能定义（Markdown 描述的流程）。
• headlong-web – 浏览器仪表板，实时观察思维过程。
• headlong-slack-bridge / headlong-telegram-bridge – 将聊天消息转换为代理的观测输入。
• headlong-killall – 紧急按钮，立即停止所有 Headlong 进程。

安装与入门

# 一行安装程序（需 bash、git、curl、jq、Python 3 和 LLM API 密钥）
curl -fsSL https://headlong.ai/install.sh | bash

• 安装程序询问是否在 Docker 中运行代理（推荐）或直接在主机上运行。
• 安装后，将获得以代理名为名的命令（如 ada）。

  ada hello            # 发送一条消息并等待回复
  ada                  # 打开交互式聊天会话
  ada dash             # 启动 Web 仪表板（http://localhost:8080）
  ada stop / ada start # 暂停或恢复后台思考循环
  

• headlong-killall 立即停止所有进程；status.sh 报告运行状态；uninstall.sh 卸载设置。

使用本地模型运行

• 任何实现 OpenAI 聊天补全 API 的服务器均可（Ollama、llama.cpp、vLLM、LM Studio 等）。
• 在 ~/.headlong/.env 中设置提供者、URL 和模型（或导出 HEADLONG_* 变量），然后重启代理。
• Ollama 示例：

  export HEADLONG_PROVIDER=local
  export HEADLONG_LOCAL_URL=http://127.0.0.1:11434/v1
  export HEADLONG_LOCAL_MODEL=qwen3:8b
  curl -fsSL https://headlong.ai/install.sh | bash
  

成本与安全提示

• 由于代理持续运行真实 shell 命令，建议使用 专用且支出受限的 API 密钥，并保持代理沙箱化（Docker 或显式容器化）。
• 作者报告默认设置下典型运行成本为 每小时 1–2 美元，具体取决于模型大小和循环速度。
• 代理空闲时系统会指数级退避，无人对话时成本急剧下降。

文档与进一步阅读

• philosophy.md – 设计理念及「肯·汤普森」哲学：小而可组合的 Bash 工具。
• docs/shellm.md – RLM 循环、上下文处理和 Docker 沙箱的深入解析。
• docs/install.md – 所有安装变体、CI 友好的非交互式安装，以及在专用服务器上运行的方法。
• AGENTS.md – 如何管理身份（角色）、查看日志和执行健康检查。
• web/, slack/, telegram/ – 仪表板和聊天桥接的源码。

许可证

• Apache 2.0（© 2026 Laude Institute）。

---

总结：Headlong 是一个研究级、以 Bash 为中心的框架，可让您快速搭建一个能够持续自主推理、支持多用户交互并能自我修改代码的 LLM 驱动代理。它刻意轻量、高度可检查，并基于 LLM 应直接编写并执行 shell 命令，而非通过独立的工具调用层。适合希望在自有硬件上实验持续性 AI 代理，同时保持整个栈透明且可编辑的开发者。