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 代理，同時保持整個堆疊透明且可編輯的開發者。