一句话定位：让 AI Agent 不偷懒、不崩溃、不跑偏，把"睡一觉醒来跑完 5 万行代码"这件事变成现实。 一句话上手：pip 一键安装，lra init 自动生成 CLAUDE.md / AGENTS.md，你的 Agent 立刻就会用。

一、功能亮点

1. 轻量到极致，零门槛接入 pip install long-run-agent 一行装好，没有重型依赖、没有服务端、没有数据库。所有状态就是 .long-run-agent/ 目录下几个 JSON / YAML 文件，跟着 Git 走，人能读、Agent 也能读。

2. 突破上下文窗口限制 内置输出限制感知：4K 的 GPT-4o-mini、8K/16K/128K 的各类 Claude 都能各司其职。lra context --output-limit 按模型能力自动推荐和拆分任务；lra orientation 一条命令完成上下文重建（工作目录、项目结构、最近提交、任务进度、索 引位置），Agent 重启即接续，不再被上下文长度卡死。

3. Constitution 规范驱动 + 质量门禁，专治"AI 偷懒" 这是 LRA 区别于普通任务清单工具的核心。项目把不可协商的原则写进 .long-run-agent/constitution.yaml，分三层： - NON_NEGOTIABLE（不可协商）：连 --force 都绕不过去，必须通过； - MANDATORY（强制）：必需门禁必须过； - CONFIGURABLE（可配置）：按需开关。 门禁支持 shell 命令（如 pytest tests/）、字段检查、自定义函数。任务完成时自动验证，失败自动进入 optimizing 状态并给出修复建议——AI 没法靠"我说做完了"蒙混过关。

4. Ralph Loop 7 阶段迭代引导，逼着每一步走扎实 每个任务最多 7 次渐进式迭代：理解规划 → 基础实现 → 功能完善 → 质量提升 → 优化改进 → 验证测试 → 交付准备。质量门禁按阶段触发，早期阶段不卡性能、不卡深度 测试，后期逐步加严。三件贴心设计：所有必需检查通过可提前完成（不必硬走 7 次）、同一阶段卡 3 次自动提示跳阶段、重构阶段带测试覆盖率安全提示。

5. Relay 全自动接力 + 断点续跑，真正的"自动驾驶" lra relay 一条命令跑完整个队列：取任务 → claim 加锁 → 跑 Agent → Constitution 验证 → 更新状态 → git commit，全程无人值守。崩溃恢复靠"阶段级提交"——每个阶段完成立即 commit，iteration 在 commit 之后才递增，所以崩溃丢的最多是当前阶段；锁超时 15 分钟后变 orphan，新进程自动接管，从 ralph.iteration 指向的阶段继续。挂个 tmux，断了重连接着跑。

6. 多 Agent 协作：大模型拆、小模型并行干 层级锁机制让大模型负责架构和接口契约、decompose 拆分、publish 释放子任务锁；小模型按 --output-limit 领取可承担的子任务并行开发，最后大模型验收集成。文件锁（单实例）+ 任务级锁（单任务）双层并发安全，多 Agent 提交到同一分支无 merge 冲突。

7. 兼容你正在用的全部 Agent 工具 Claude Code、OpenCode、Open Claw、Cursor、Trae……一条 lra init 自动生成对应的 CLAUDE.md / AGENTS.md / lra.md，Agent 读完就知道工作流，不挑工具、不改习惯。

8. 全平台 + 高性能 Windows / Linux / macOS 全平台兼容（CI 验证）。基准测试：1000 任务规模下创建延迟 <10ms、更新延迟 <20ms、吞吐 172 ops/s，10→1000 任务内存增长仅 19.5%——开箱即用撑住大型项目。

9. 通用任务模型，不止写代码 内置 code-module、novel-chapter、data-pipeline、doc-update、task 五套模板，软件开发、小说创作、数据处理、文档维护都能套；Jinja2 模板引擎支持条件/循环，自定义模板零成本。

二、典型使用场景

1. 大型软件项目的多模块并行开发 把一个 Web 应用拆成认证、订单、支付等模块，大模型定契约、小模型分头干活，Constitution 保证每块合并时测试必过、文档必更新。

2. 长任务挂机自动化（"睡一觉跑完"） tmux 里 lra relay --max-steps 100，第二天回来看进度条。配合国内高性价比的中小 输出模型（4K/8K）把成本压下来，长任务也能跑得起。

3. 多 Agent / 多模型混编 贵模型干规划与验收，便宜模型干实现，靠层级锁和输出限制适配把分工切干净，避免" 大材小用"烧 token。

4. 长篇内容创作（小说、系列文档） novel-chapter 模板的 7 阶段路径：理解大纲 → 初稿 → 情节完善 → 人物塑造 → 语言润色 → 逻辑检查 → 最终定稿，每一稿都有阶段目标和可跳过项，不被一次性输出上限困住。

5. 数据管道与数据处理 data-pipeline 模板覆盖数据可用性 → 质量 → 完整性 → 性能 → 可视化 → 交付验证全链路，适合周期性、需要回归保障的数据任务。

6. 老项目接入与文档治理 v3.3+ 的系统预检（代码规模、Git 规范、文档覆盖率、注释占比）自动评估项目健康度 ，增量/全量两种模式；创建业务任务时自动绑定文档更新任务，doc_enforcement 可设 strict 强制闭环。

7. 团队级 Agent 工作流标准化 lra orientation + 13 步标准化提示词 + 项目分析器（Python/JS/TS/Go），新 Agent 上手即对齐既有规范，降低协作摩擦。

三、社区收录与认可（可核实）

• 开源协议：MIT License，GitHub 仓库 hotjp/long-run-agent，已发布 23 个 Release，最新 v5.2.2（完整 Windows 兼容性，CI 验证）。

• PyPI 已发布：pip install long-run-agent，命令行工具为 lra。

• 收录于 GitHub Topic「long-running-agent」分类。

• 被第三方开源聚合站 Star Wiki 收录，列为「适合 AI Agent 开发的开源项目」之一。

• 掘金、CSDN 等技术社区有专文介绍与实测，核心评价聚焦在"轻量、零门槛、可直接落
  地的长任务调度"。

四、FAQ

Q1：LRA 和其他 Agent 框架（LangGraph / AutoGen / CrewAI 等）有什么本质区别？ A：那些框架解决的是"怎么编排 Agent 调用"，LRA 解决的是"长任务怎么不崩、不偷懒、可接续"。它不接管你的模型调用，而是给任意 Agent 工具提供一层规范驱动的任务管理 + 质量门禁 + 断点续跑外壳。Constitution 强制门禁 + Ralph Loop 阶段引导是其他任务清单类工具没有的。

Q2：AI 总喜欢说"我做完了"就交差，LRA 怎么治？ A：靠 Constitution 的 NON_NEGOTIABLE 原则 + 质量门禁。任务完成时自动跑你定义的 检查（pytest、lint、字段是否存在……），失败就自动进 optimizing 状态给修复建议；即使加 --force 强制完成，NON_NEGOTIABLE 原则照样必须通过，绕不过去。

Q3：跑长任务中途进程崩了，进度会丢吗？ A：不会。Relay 采用阶段级提交——每个阶段完成立即 git commit，崩溃后重启 lra relay 会读取 ralph.iteration 从断点续跑；锁超时 15 分钟自动转 orphan，新进程接管。建议挂 tmux，断网断电都能续。

Q4：支持哪些 AI 模型和编程工具？ A：模型层面按输出能力自适应（4K–128K 全覆盖，特别适配国内高性价比中小模型）。工具层面 v5.0 全面兼容 Claude Code、OpenCode、Open Claw、Cursor、Trae 等，lra init 自动生成对应配置文件，Agent 自动学会工作流。

Q5：支持 Windows 吗？ A：支持。v5.0 起全平台兼容（Windows / Linux / macOS），v5.2.2 已通过 CI 完整验证，跨平台相关操作使用跨平台原语，无平台锁。

Q6：数据存在哪？会不会丢？多人/多 Agent 同时操作安全吗？ A：所有状态就是 .long-run-agent/ 下的 JSON/YAML/Markdown，跟 Git 走、可 review。原子文件 I/O（SafeJson + FileLock）保证写不撕裂；并发场景下文件锁（单实例）+ 任务级锁（单任务）双重保护，多 Agent 提交同一分支不冲突。

Q7：性能扛得住大项目吗？ A：扛得住。1000 任务规模：创建 <10ms、读取 <2ms、更新 <20ms、吞吐 172 ops/s，10→1000 任务内存增长仅 19.5%。500 任务以内属常规使用区间。

Q8：收费吗？ A：MIT 开源，完全免费。安装：pip install long-run-agent（开发版加 [dev]，含浏览器测试加 [full]）。

Q9：最快怎么跑起来？ A：四条命令—— lra init --name "My Project" # 初始化（自动建 Constitution） lra new "实现登录功能" # 创建+认领 lra new "用户认证模块" --auto-split # 复杂任务自动拆分 lra status # 看进度 想全自动就 lra relay --dry-run 先干跑看看。