1. 项目定位与用途
LRA 是一个面向 AI Agent 的长任务执行框架，定位为‘规范驱动 + 任务管理 + 质量保障系统 + 迭代阶段引导’的一体化解决方案。其核心用途是管理需要多步骤、长时间迭代的复杂任务，通过结构化流程确保 Agent 输出的稳定性和可交付性。框架以命令行工具 `lra` 为主要接口，用户可通过一系列命令完成项目初始化、任务创建、状态跟踪与质量验证，最终形成从任务定义到完成验证的完整闭环。
项目档案命令行工具
LRA AI Agent 长任务框架：Constitution 规范驱动与 pip 一键安装使用指南
LRA 是一个超稳定 AI Agent 长任务执行框架，突破上下文限制，提供 Constitution 质量门禁与 7 阶段迭代引导。本文详细介绍其安装、使用方式及适用场景，支持 pip 一键安装与跨平台运行。
AI 总结
LRA 是一个面向 AI Agent 的长任务超稳定执行框架，通过 Constitution 规范驱动与 Ralph Loop 迭代引导，解决长上下文限制与质量保障问题，支持 pip 一键安装与跨平台运行。
中文项目介绍
LRA（Long-Run Agent）是一个专为 AI Agent 设计的长期任务执行与管理框架，旨在提升长任务执行的稳定性和结果质量。
针对 AI 在处理复杂、多步骤长任务时面临的上下文长度限制、输出质量不稳定、迭代过程缺乏引导等核心问题，LRA 提供了系统性的解决方案：通过任务拆分与依赖管理降低单次上下文压力；引入 Constitution 机制定义不可协商原则与质量门禁，在关键节点自动验证，防止 Agent 偷懒；结合 Ralph Loop 七阶段渐进式优化路径，为每次迭代提供明确目标与检查项，避免优化盲目性。
该框架适用于需要长期迭代与高质量交付的场景，包括但不限于软件开发（如功能实现、代码重构）、创意写作（如小说章节创作）以及数据处理与分析任务。
技术层面，LRA 以命令行工具 `lra` 为核心交互方式，支持通过 `pip install long-run-agent` 一键安装，并提供 `[dev]`、`[full]` 两种扩展依赖。其架构采用分层设计，集成 Jinja2 模板引擎、多 Agent 协作锁机制、输出限制感知推荐等特性，已在 v5.0 版本中实现 Windows、Linux、macOS 全平台兼容。
详细信息与使用说明
2. 解决的问题
LRA 主要解决 AI Agent 在长任务执行中的四大问题：一是突破上下文长度限制，通过任务自动拆分与依赖（DAG）管理，将大任务分解为可管理子任务；二是质量保障缺失，引入 Constitution 机制定义不可协商原则（NON_NEGOTIABLE）与强制门禁（MANDATORY），在任务完成、Ralph Loop 结束等关键节点自动验证，失败则转入优化状态；三是迭代过程盲目，提供 Ralph Loop 七阶段引导，每轮迭代有明确目标与检查项，避免重复劳动或跳过关键步骤；四是多 Agent 协作冲突，通过层级锁机制支持并行开发与任务依赖自动解锁。
3. 适用场景
LRA 适用于需要长期迭代、多步骤且对质量有要求的场景。主要场景包括：软件开发（如实现登录功能、用户认证模块开发，支持测试验证与代码质量检查）、创意写作（如小说章节创作，通过模板管理章节结构）、数据处理与分析（如多步骤数据清洗与转换任务）。框架的通用任务模型与 Jinja2 模板引擎使其可灵活适配不同领域，而输出限制感知功能能根据模型能力推荐或拆分任务规模，确保在各类 LLM 环境下均可稳定运行。
4. 安装方式
LRA 支持通过 pip 一键安装，安装包名为 `long-run-agent`，命令行工具为 `lra`。基础安装命令为 `pip install long-run-agent`，自动包含 Jinja2 依赖。开发环境需安装额外开发依赖：`pip install long-run-agent[dev]`，包含 pytest、black、ruff、mypy 等工具。完整安装（含浏览器自动化测试支持）使用 `pip install long-run-agent[full]`，额外安装 playwright。项目要求 Python 版本 >=3.8，并支持 Windows、Linux、macOS 全平台。注意：npm 包 `lra` 仅作为启动器，核心功能仍依赖 Python 环境。
5. 使用方式
LRA 通过 `lra` 命令行工具操作。初始化项目：`lra init --name "My Project"` 自动创建 Constitution 配置。快速创建并认领任务：`lra new "实现登录功能"`；复杂任务可自动拆分：`lra new "实现用户认证模块" --auto-split`。Constitution 管理：`lra constitution show` 查看配置，`lra constitution validate` 验证有效性。获取上下文：`lra context --output-limit 8k` 或 `lra orientation` 重建上下文。查看进度：`lra status`。任务状态更新：`lra set task_001 completed` 会自动触发 Constitution 验证，失败则进入 optimizing 状态。强制进入下一迭代阶段：`lra set task_001 force_next_stage`。
6. 补充说明：Constitution 与质量保障机制
Constitution 是 LRA v5.0 的核心机制，定义项目的‘不可协商原则’与质量标准。其三层原则体系包括：NON_NEGOTIABLE（绝对必须通过，无法绕过）、MANDATORY（强制门禁，必需通过）、CONFIGURABLE（可配置启用/禁用）。验证通过三种门禁类型实现：command（执行 shell 命令，如 pytest）、field_exists（检查任务文件字段）、custom（自定义函数）。该机制在任务完成、Ralph Loop 结束、强制完成时自动触发，即使使用 `--force` 参数，NON_NEGOTIABLE 原则仍需通过，确保 AI 无法偷懒。配置文件位于 `.long-run-agent/constitution.yaml`，详细设计见 `docs/CONSTITUTION_DESIGN.md` 与 `docs/CONSTITUTION_ENFORCEMENT.md`。
思维导图
LRA 长任务执行框架
核心特性
通用任务模型
Jinja2 模板引擎
DAG 任务依赖
P0-P3 优先级调度
多 Agent 协作锁
输出限制感知
Constitution 规范驱动
三层原则体系
质量门禁自动验证
不可协商原则强制
Ralph Loop 迭代引导
7 阶段渐进优化
阶段目标与检查项
质量门禁按阶段触发
任务管理与协作
任务生命周期管理
自动拆分与认领
上下文重建
安装与使用
pip 一键安装
lra 命令行工具
init/new/constitution 等命令
常见问题
LRA 是什么？主要用途有哪些？
LRA 是 Long-Run Agent 的缩写，是一个面向 AI Agent 的长任务执行框架。主要用途是管理软件开发、小说写作、数据处理等需要多步骤迭代的复杂任务，通过规范驱动与质量保障系统确保任务稳定完成。
如何安装 LRA？是否有不同安装选项？
通过 pip 一键安装：`pip install long-run-agent`。提供两种可选依赖：开发环境 `pip install long-run-agent[dev]`（包含 pytest、black 等），完整安装 `pip install long-run-agent[full]`（额外包含 playwright 浏览器测试支持）。要求 Python >=3.8。
Constitution 机制如何保证任务质量？
Constitution 定义项目的不可协商原则与质量标准，分为 NON_NEGOTIABLE（绝对必须通过）、MANDATORY（强制门禁）和 CONFIGURABLE（可配置）三层。通过命令执行、字段检查、自定义函数等门禁类型，在任务完成、迭代结束等关键节点自动验证，确保 AI 无法绕过核心规则。