long-run-agent 5.1.0

A powerful framework for managing long-running AI Agent tasks with quality assurance

LRA - AI Agent Task Manager v5.1.0

规范驱动 + 任务管理 + 质量保障系统 + 迭代阶段引导

核心特性

• 通用任务模型：支持软件开发、小说写作、数据处理等多种场景
• Jinja2 模板：强大的模板引擎，支持条件/循环语法
• 任务依赖：DAG 依赖关系，自动解锁完成的任务
• 优先级调度：P0-P3 优先级，Agent 自评
• 多 Agent 协作：层级锁机制，支持大模型拆分任务、小模型并行开发
• 输出限制感知：根据模型输出能力推荐/拆分任务
• 🆕 Agent 自治初始化 (v3.3.0): 自动预检 + 增量处理 + 文档闭环
• ✨ 质量保障系统 (v5.0.0): 验证机制 + 回归测试 + 代码质量检查
• 🎯 迭代阶段引导 (v4.1.0): 7阶段渐进式优化 + 智能引导 + 安全检查
• 🚀 Constitution机制 (v5.0.0): 规范驱动开发 + 质量门禁 + 不可协商原则
• 🌍 跨平台支持 (v5.0.0): Windows / Linux / macOS 全平台兼容

安装

# 安装（自动包含 Jinja2）
pip install long-run-agent

# 开发环境
pip install long-run-agent[dev]

# 完整安装（包含浏览器测试支持）
pip install long-run-agent[full]

注意：安装包名为 long-run-agent，命令行工具为 lra。

快速开始

# 初始化项目（自动创建Constitution）
cd /your/project
lra init --name "My Project"

# 快速创建+认领任务（推荐）
lra new "实现登录功能"

# 复杂任务：自动拆分+认领第一个子任务
lra new "实现用户认证模块" --auto-split

# 查看Constitution配置
lra constitution show

# Agent 获取上下文
lra context --output-limit 8k

# Agent 上下文重建（推荐）
lra orientation

# 查看项目进度
lra status

🆕 Constitution功能 (v5.0)

核心概念

Constitution定义项目的不可协商原则和质量标准，在任务完成前自动验证，确保质量底线。

快速上手

# 1. 查看Constitution使用指南
lra constitution help

# 2. 查看当前配置
lra constitution show

# 3. 验证配置有效性
lra constitution validate

# 4. 创建任务
lra create "实现登录功能"

# 5. 完成任务（自动验证Constitution）
lra set task_001 completed
# 如果验证失败，会自动进入optimizing状态并给出修复建议

三层原则体系

原则类型	说明	强制性
🔴 NON_NEGOTIABLE	不可协商原则	必须通过，无法绕过
🟡 MANDATORY	强制原则	必需门禁必须通过
🟢 CONFIGURABLE	可配置原则	可启用/禁用

三种门禁类型

• command: 执行shell命令检查（如：pytest tests/）
• field_exists: 检查任务文件字段（如：test_evidence）
• custom: 自定义检查函数

强制执行机制

⚠️ 重要: Constitution在以下场景自动验证，AI无法绕过：

1. 任务完成时 (lra set task completed) - 自动验证所有原则
2. Ralph Loop完成时 - 必须通过所有原则
3. 强制完成时 - NON_NEGOTIABLE原则仍需通过

无法偷懒保证: 即使使用--force参数，NON_NEGOTIABLE原则也必须通过！

配置文件

配置文件位置：.long-run-agent/constitution.yaml

示例配置：

core_principles:
  - id: "no_broken_tests"
    type: "NON_NEGOTIABLE"
    name: "测试必须通过"
    gates:
      - type: "command"
        command: "pytest tests/"

详细文档

• docs/CONSTITUTION_ENFORCEMENT.md - 强制执行机制说明
• docs/CONSTITUTION_DESIGN.md - 详细设计文档
• CONSTITUTION_COMPLETE.md - 功能完成报告

命令参考

核心命令

命令	用途
lra init --name <name>	初始化项目（自动创建Constitution）
lra new <desc>	🆕 快速创建+认领任务（自动填充字段）
lra new <desc> --auto-split	🆕 创建+自动拆分+认领第一个子任务
lra constitution help	🆕 Constitution使用指南
lra constitution show	🆕 查看Constitution配置
lra constitution validate	🆕 验证Constitution有效性
lra context [--output-limit Xk]	获取项目状态 + 可领取任务
lra list [--status X] [--template X]	列出任务
lra create <desc> --template <name>	创建任务
lra show <id>	任务详情（包含迭代进度和阶段引导）
lra set <id> <status>	更新状态（自动Constitution验证）
lra set <id> force_next_stage	🆕 强制进入下一迭代阶段（含阶段质量检查）
lra split <id> --auto	🆕 使用decompose建议自动拆分
lra decompose <id>	🆕 分析任务并建议如何拆分

🎯 Ralph Loop 迭代阶段引导 (v4.1.0)

核心特性：Ralph Loop 是任务级循环优化机制，让 Agent 不再"偷懒"，每一步都扎实。

渐进式优化路径：每个任务最多7次迭代，每次迭代有明确的目标、优先级检查项和忽略项。

查看迭代状态：

lra show task_001

# 输出示例：
## 🔄 Ralph Loop 状态

当前轮次: 3/7
已优化次数: 2次

### 质量检查结果

| 检查项 | 状态 | 详情 |
|--------|------|------|
| 测试通过 | ✅ | 通过 |
| Lint检查 | ❌ | 失败 |
| 验收标准 | ✅ | 满足 |

╔═══════════════════════════════════════════════════════════╗
║                     🎯 迭代阶段引导                   ║
╠═══════════════════════════════════════════════════════════╣
║  当前迭代: 3/7                                        ║
║  阶段名称: 质量提升                                   ║
║                                                           ║
║  📌 本次重点:                                         ║
║     • 修复 lint 警告                                  ║
║     • 改善代码结构                                    ║
║     • 增加注释                                         ║
║                                                           ║
║  ⏭️  可跳过:                                          ║
║     • 性能优化                                         ║
║     • 高级功能                                         ║
╚═══════════════════════════════════════════════════════════╝

质量门禁按阶段触发：

阶段	触发检查	忽略检查
1. 理解规划	目标理解、计划创建	实现细节
2. 基础实现	核心功能、可运行性	性能、边界
3. 功能完善	边界处理、错误处理	优化、重构
4. 质量提升	Lint、测试覆盖	性能深入
5. 优化改进	性能指标	单元测试
6. 验证测试	全部测试、回归测试	文档
7. 交付准备	验收标准、文档完整	-

支持的模板：

• code-module: 理解需求 → 基础功能 → 功能完善 → 质量提升 → 优化改进 → 全面测试 → 交付准备
• novel-chapter: 理解大纲 → 完成初稿 → 情节完善 → 人物塑造 → 语言润色 → 逻辑检查 → 最终定稿
• data-pipeline: 理解需求 → 数据可用 → 数据质量 → 功能完整 → 性能优化 → 可视化 → 交付验证
• doc-update: 理解需求 → 内容收集 → 结构设计 → 内容编写 → 格式优化 → 审校修改 → 最终发布
• task: 理解规划 → 基础实现 → 功能完善 → 质量提升 → 优化改进 → 验证测试 → 交付准备

关键特性：

• ✅ 提前完成：所有必需检查通过即可提前完成（不必走完7次）
• ✅ 阶段卡住检测：同一阶段卡住3次后提示强制进入下一阶段
• ✅ 安全检查：代码重构阶段提供测试覆盖率检查等安全提示
• ✅ 自动质量门禁：根据当前阶段自动触发对应的质量检查

工作流示例：

# 1. 创建任务（自动启用 Ralph Loop）
lra create "用户登录功能" --template code-module

# 2. 认领并开始工作
lra claim task_001

# 3. 完成任务（自动触发质量检查）
lra set task_001 completed

# 4. 如果质量检查未通过，显示迭代引导
#    - 当前阶段和进度
#    - 失败原因
#    - 本次重点和可跳过项
#    - 修复建议

# 5. 修复后再次提交，可能提前完成
# 输出：🎉 恭喜！任务可提前完成（迭代 2/7）

# 6. 如果在同一阶段卡住3次
# 输出：⚠️ 在当前阶段已尝试3次，建议使用：
lra set task_001 force_next_stage  # 强制进入下一阶段

项目分析命令

命令	用途
lra analyze project	分析整个项目结构，生成文档和索引
lra analyze module <name>	分析指定模块代码
lra analyze module <name> --output-doc	分析模块并生成文档
lra system-check	执行系统预检
lra system-check --report	查看预检报告

Agent 索引命令

命令	用途
lra where	显示所有关键文件位置
lra where --index	输出完整索引内容（JSON）

锁命令

命令	用途
lra claim <id>	领取任务（锁定自己+子任务）
lra publish <id>	发布子任务（释放子任务锁）
lra pause <id>	暂停并保存快照
lra resume <id>	查看快照
lra heartbeat <id>	心跳保活（每5分钟）
lra batch lock status	查看批量锁状态
lra batch lock acquire	获取批量锁

模板命令

命令	用途
lra template list	列出模板
lra template show <name>	查看模板详情
lra template create <name>	创建模板

依赖命令

命令	用途
lra deps <id>	查看任务依赖
lra deps <id> --dependents	查看依赖此任务的其他任务
lra check-blocked	检查并解锁 blocked 任务

优先级命令

命令	用途
lra set-priority <id> <P0|P1|P2|P3>	设置任务优先级

内置模板

模板	用途	状态
task	通用任务	pending → in_progress → completed
novel-chapter	小说章节	drafting → revising → finalized
code-module	代码模块	pending → in_progress → pending_test → completed
data-pipeline	数据流程	pending → running → success

多 Agent 协作流程

1. 大模型 new "Web应用开发" --auto-split（创建+拆分+认领第一个子任务）
2. 大模型编写架构/接口契约
3. 大模型 decompose task_001（查看拆分建议）
4. 大模型 split task_001 --auto（使用建议自动拆分）
5. 大模型 publish task_001（释放子任务锁）
6. 小模型 context --output-limit 8k（获取可领取任务）
7. 小模型 claim task_001_02（领取子任务）
8. 小模型按契约开发
9. 大模型验收/集成

输出限制适配

模型	输出限制	使用
GPT-4o-mini	4K	--output-limit 4k
Claude 3.5	8K	--output-limit 8k
Claude 3.5 Sonnet	16K	--output-limit 16k
Claude 3.5 Sonnet Max	128K	--output-limit 128k

数据结构

.long-run-agent/
├── config.json          # 项目配置
├── task_list.json       # 任务列表
├── locks.json           # 任务锁
├── templates/           # 模板（可自定义）
│   ├── task.yaml
│   ├── novel-chapter.yaml
│   ├── code-module.yaml
│   └── data-pipeline.yaml
├── tasks/               # 任务文件
│   └── task_001.md
└── records/             # 变更记录
    └── task_001.json

自定义模板

# .long-run-agent/templates/my-template.yaml
name: my-template
description: 我的自定义模板
version: "2.0"
template_engine: jinja2  # 使用 Jinja2 引擎

structure: |
  # {{ id }}
  
  ## 描述
  {{ description }}
  
  {% if tech_stack %}
  ## 技术栈
  {{ tech_stack }}
  {% endif %}
  
  ## 交付物
  <!-- 请列出交付物 -->

states:
  - pending
  - working
  - done

transitions:
  pending: [working]
  working: [done]
  done: []

acceptance:
  - 验收标准 1
  - 验收标准 2

创建任务示例

# 基础创建
lra create "实现用户登录"

# 带优先级
lra create "紧急 Bug 修复" --priority P0

# 带依赖
lra create "集成测试" --dependencies task_001,task_002 --dependency-type all

# 带截止时间
lra create "发布版本" --deadline "2026-02-28T23:59:59"

# 带模板变量
lra create "API 开发" --template code-module \
  --variables '{"tech_stack": "FastAPI", "input_params": "user_id"}'

状态说明

状态	说明
blocked	依赖未完成，不可领取
pending	初始状态，可领取
in_progress	进行中
completed	完成（终态）

blocked 状态自动解锁：当依赖的任务完成后，blocked 任务会自动变为 pending 状态。

🆕 v3.3.0 Agent 自治式初始化

系统预检任务

LRA v3.3.0 引入自动化系统预检，在首次创建任务时自动执行项目评估：

检测维度：

• ✅ 代码规模（≤5MB）
• ✅ Git 提交规范性（≥30%）
• ✅ 文档覆盖率（≥40%）
• ✅ 函数注释占比（≥20%）

决策模式：

• 全量模式（OR 逻辑，任一条件满足）：
  • 代码体积 ≤ 5MB
  • 或 文档覆盖率 ≥ 40%
  • 或 Git 规范提交 ≥ 30%
• 增量模式（所有条件均不满足）：仅允许创建模块级任务

强制全量解析： 使用 --force 参数可强制进入全量解析模式，忽略所有阈值检查。

使用方法：

# 自动触发（首次创建任务时）
lra create "支付模块开发"

# 手动执行预检
lra system-check

# 查看预检报告
lra system-check --report

# 强制重新检查
lra system-check --full

# 强制全量解析模式（忽略阈值）
lra system-check --force

# 分析指定模块（代码结构分析）
lra analyze module QAFetch

# 分析模块并生成文档
lra analyze module QAFetch --output-doc

# 分析整个项目
lra analyze project

# 分析项目并生成文档到指定目录
lra analyze project --output-dir docs

# 强制重新分析
lra analyze project --force

# 分析项目但不创建任务
lra analyze project --no-create-tasks

项目分析器

v3.4.0 新增项目代码分析器，支持多语言项目结构分析：

支持语言：Python、JavaScript/TypeScript、Go

分析内容：

• 项目模块结构
• 文件数量、代码行数
• 核心类和函数
• 模块依赖关系
• 文档覆盖率

输出结构：

项目根目录/
├── docs/                           # 人类可读文档
│   ├── MODULES.md                  # 模块总览
│   ├── modules/                    # 模块详情
│   └── files/                      # 文件详情
│
└── .long-run-agent/analysis/
    ├── index.json                  # Agent 快速索引（类/函数/文件）
    ├── summary.json                # 项目摘要
    └── modules/                    # 模块详情 JSON

Agent 快速索引：

// .long-run-agent/analysis/index.json
{
  "classes": {
    "Calculator": {"file": "mymodule.py", "line": 3, "methods": ["add"]}
  },
  "functions": {
    "helper": {"file": "mymodule.py", "line": 10}
  }
}

使用方法：

# 初始化项目
lra init --name MyProject

# 执行完整项目分析
lra analyze project

# 查看 Agent 索引位置
lra where

# 输出索引内容（JSON）
lra where --index

# 查看模块详情
lra analyze module payment --output-doc

# 强制重新分析
lra analyze project --force

文档闭环

v3.3.0 新增文档更新任务自动绑定：

# 创建业务任务时，自动生成绑定的文档任务
lra create "支付模块开发" --priority P0

# 自动生成：doc_update_001（依赖 task_001）
# 描述：更新支付模块 README + 接口文档

配置模式（.long-run-agent/config.yaml）：

system_check:
  doc_enforcement: strict  # strict(强制) | soft(推荐) | disabled(关闭)

预检报告示例

{
  "project_id": "old_project_001",
  "decision": "incremental",
  "metrics": {
    "code_total_size_mb": 8.5,
    "git_valid_ratio": 0.15,
    "doc_coverage_ratio": 0.25
  },
  "reason": "代码体积 8.5MB>5MB，文档覆盖率 25%<40%，触发增量处理"
}

性能基准

测试环境

• Python: 3.9.6
• 操作系统: macOS (darwin)
• CPU 核心数: 20
• 物理内存: 64.0 GB

性能指标

规模	基础内存 (MB)	峰值内存 (MB)	每任务内存 (KB)	创建延迟 (ms)	读取延迟 (ms)	更新延迟 (ms)	吞吐量 (ops/s)
10 ⚡	21.8	22.2	41.6	2.85	0.06	3.03	807.58
50 ⚡	22.2	23.59	28.48	2.94	0.12	3.5	724.88
100 ⚡	23.59	23.83	2.4	3.25	0.2	4.25	663.94
200 ⚡	23.83	24.3	2.4	3.99	0.36	5.74	540.05
500	24.3	24.5	0.42	6.16	0.94	9.93	293.52
1000	24.5	26.52	2.06	9.9	1.91	17.23	172.12

说明:

• ⚡ 表示执行了依赖关系测试（200 任务以下）
• 测试包含：任务创建、读取、更新操作
• 详细报告：scripts/BENCHMARK_RESULTS.md

性能分析

• 内存增长: 10 任务 → 1000 任务，内存增长仅 19.5%
• 平均创建延迟: 4.85 ms
• 平均读取延迟: 0.60 ms
• 平均更新延迟: 7.28 ms
• 性能评级: 🟢 优秀 - 系统性能优秀，适合大规模任务管理

结沦

• ✅ 100 任务以下: 极快响应（< 4ms），适合实时交互
• ✅ 500 任务以下: 良好性能（< 10ms），适合常规使用
• ✅ 1000 任务: 可接受（< 20ms），适合批量处理

环境要求

• Python ≥ 3.8
• Git ≥ 2.0（可选）

链接

• GitHub: https://github.com/hotjp/long-run-agent
• PyPI: https://pypi.org/project/lra/

🆕 v5.0 新功能

质量保障系统

v5.0 新增了完整的质量保障系统，确保任务完成质量：

1. 验证前置机制

任务完成前必须提供验证证据：

## 验证证据（完成前必填）

- [ ] **实现证明**: [描述实现]
- [ ] **测试验证**: [如何测试]
- [ ] **影响范围**: [影响的功能]

### 测试步骤
1. [步骤1]
2. [步骤2]

2. 回归测试

# 运行回归测试
lra test regression

# 查看报告
lra test regression --report

# 测试特定模板
lra test regression --template code-module

3. 浏览器自动化测试

# 检查任务验证状态
lra test browser task_001

# 生成测试脚本
lra test browser task_001 --script

4. 代码质量检查

# 运行质量检查
lra test quality

# 查看报告
lra test quality --report

Agent 工作流优化

上下文重建协议

# Agent 专用：完整上下文重建
lra orientation

提供：

• 工作目录
• 项目结构
• 最近提交
• 任务进度
• Agent 索引位置

进度可视化

# 查看项目进度
lra status

输出示例：

📊 项目进度: 45/200 (22.5%)

[████████░░░░░░░░░░░░░░░░░░░░░░░░░░]

📈 任务分布:
  ✅ Completed:   45 █████████████████████████
  🔄 In Progress:  5 ███
  ⏳ Pending:    150 ████████████████

⏱️  预估剩余时间: 12.5 小时

统一提示词模板

查看完整的 Agent 工作流程：

cat lra/prompts/agent_prompt.md

13步标准化工作流，包含完整的故障排除指南。

命令参考

核心命令

命令	用途
lra init --name <name>	初始化项目（默认 task 模板）
lra context [--output-limit Xk]	获取项目状态 + 可领取任务
lra list [--status X] [--template X]	列出任务
lra create <desc> --template <name>	创建任务
lra show <id>	任务详情
lra set <id> <status>	更新状态（受模板约束）
lra split <id> --plan '<json>'	拆分任务（模型提供方案）

🆕 质量保障命令

命令	用途
lra status	项目进度可视化
lra orientation	Agent上下文重建
lra test regression [--report]	回归测试
lra test browser <id> [--script]	浏览器自动化测试
lra test quality [--report]	代码质量检查

🆕 迭代阶段引导机制

每个任务支持最多7次迭代优化，每次迭代有明确的阶段目标：

迭代阶段示例（code-module模板）

迭代1: 基础功能验证  - 让功能跑起来
迭代2: 功能完善      - 补充测试和边界情况
迭代3: 代码质量提升  - 修复lint、改善结构
迭代4: 初步优化      - 性能瓶颈分析
迭代5: 代码重构      - 消除重复、优化设计（有安全检查）
迭代6: 全面测试      - 集成测试、性能测试
迭代7: 交付准备      - 文档、审查、交付

关键特性

1. 提前完成：所有必需检查通过即可提前退出（不必走完7次）
2. 阶段卡住检测：同一阶段失败3次后提示强制进入下一阶段
3. 安全检查：代码重构阶段自动检查测试覆盖率等安全指标

详细文档：ITERATION_GUIDANCE_FINAL_REPORT.md