Loa：本地优先、可变状态机的自主编程代理

Loa 是一个本地优先（local-first）的状态化自主编程代理，目标不是一次性补全，而是"项目级工程任务 + 长时间运行的自动化开发"。它把控制系统的思想引入 AI 编程流程：用显式状态转换、结构化工具调用、持久任务状态、记忆检索、评估与恢复这些明确分工，取代"一个开放式的模型/工具循环"。作者 laughingmandev 在 README 里把它定位为"宏观架构工程师"——它会自己拆活、推进计划、回滚失败、刷新记忆，最终交付一个可以被人类审计的工程结果。

项目简介

Loa 的运行完全在本机或私有云里：运行时状态放在项目内的 .loa/ 目录、项目配置放在 .loa.json，都不会被远程服务持久化。模型推理走你配置的 OpenAI 兼容端点，Ollama、vLLM、本地 llama.cpp 服务都行；嵌入甚至可以在 CPU 上跑本地 GGUF，不需要额外的向量库服务。作者明确警告：不建议接按量计费的云端 API，因为哪怕是项目初次扫描都会消耗大量模型调用，Planned Mode 长任务可能消耗非常多的请求数。

核心功能

• 可变 DAG 执行引擎：复杂任务走 Planned Mode，先产出验收标准和一张 DAG 计划图，再分步执行；每一步的依赖决定哪些已完成步骤的结果被注入作为"前置上下文"，计划随执行进展可分解、可重排。
• 显式执行与评估分离：工具调用与模型决策解耦——可前置假设、结果可独立评估、失败可路由到 repair、rollback、clarification、replanning 等不同恢复路径。
• 本地状态与项目记忆：.loa/ 存运行时状态，.loa.json 存项目配置；项目结构化记忆基于 Narrative Frame，锚定到源文件上，跨会话保留；会话记忆与任务记忆分开存储。
• 重组上下文策略：不做"递归整段历史压缩"那种容易丢信息的老办法，每次推理前重新组装上下文——包含当前任务状态、当前步骤、直接前置步骤的结果、最近的面包屑/消息、选中的检索/工具上下文，全部受预算约束。
• 可选 Docker 沙箱：默认可在主机运行（你的用户权限），也可放进 loa-sandbox 容器；文件工具锁在项目根目录，shell/process 工具继承 Loa 自身的权限。
• 可观察状态：UI 暴露当前 plan/graph、working/session/project 记忆视图、artifacts、最近一次组装的模型上下文、执行日志、审批、上传与任务控制。

技术实现

Loa 的核心抽象是一个可变有向无环图（DAG）。图的节点是执行步骤，边是"上下文注入依赖"——某个步骤的输入会显式地拼装自所有已完成依赖步骤的输出，而不是堆叠在对话历史里。这种设计带来三点工程优势：第一，上下文组装是确定性的、可重放的，便于事后审计；第二，计划可以在执行中变更——重排、分解、合并都很自然；第三，"步骤"边界让评估、恢复、重试都颗粒度更细，而不是一坨对话。

记忆部分走双层架构：项目层用 Narrative Frame 锚定源文件，跨会话保留；会话层与任务层独立存储。运行时通过 llama.cpp 兼容的 GGUF 或 OpenAI 协议端点推理，作者建议本地 Ollama 等自托管方案。可选的 loa-sandbox 通过 Docker Compose 把项目挂载到容器内的 /workspace，UI 默认端口 8104；主机模式则直接以用户权限运行，默认端口 7171。整套 release 当前面向 Linux amd64 和 arm64 环境。

快速上手

# 一键安装（Linux amd64/arm64）
curl -fsSL https://raw.githubusercontent.com/laughingmandev/loa/main/scripts/setup.sh | bash

# 进入你的项目目录
cd /path/to/your/project

# 主机模式（默认 127.0.0.1:7171）
loa .

# 或沙箱模式（默认 8104，把当前项目挂到容器 /workspace）
loa-sandbox

安装脚本会把 Loa 装到 ~/.loa/bin，下载 ast-grep，确保 ctags 可用，按需装沙箱文件与本地嵌入模型。如果 ~/.local/bin 或 ~/bin 可写，会自动建 loa 符号链接，否则会打印路径让你自己加到 PATH。

适用人群

• 想在本地或私有云运行 AI 编程代理、不愿把代码交给云端 API 的独立开发者；
• 处理跨模块重构、批量迁移、长期任务的工程团队；
• 想研究"AI 控制系统"思路、把 DAG/状态机当作 AI 编排原语的研究者；
• 需要可审计、可回放执行过程的合规场景，例如内部工具开发、审计日志敏感的项目。

出品方与官方链接

• 作者：laughingmandev（GitHub 个人开发者）
• 仓库许可证：以仓库 LICENSE 为准
• GitHub：https://github.com/laughingmandev/loa
• 架构文档：https://github.com/laughingmandev/loa/blob/main/docs/core_concepts/architecture.md
• 设计哲学：https://github.com/laughingmandev/loa/blob/main/docs/core_concepts/design_philosophy.md
• 使用指南：https://github.com/laughingmandev/loa/blob/main/docs/getting_started/usage_guide.md