Long-Running Agent - 长时间运行智能体编排框架

基于 Anthropic 论文《Long-Running Claude for Scientific Research》实现，让 AI 智能体能够跨会话持续工作并完成复杂任务。

核心理念

问题：AI智能体每次会话都是新生的，没有记忆延续。

解决方案：通过文件系统作为外部大脑，实现跨会话的持续工作能力。

快速开始

创建新项目

当用户说 创建一个[项目名]项目 时：

Step 1: 确认项目名称和目标
Step 2: 在 workspace/tasks/{项目名}/ 创建目录
Step 3: 生成 PROJECT.md（项目简报）
Step 4: 生成 CHANGELOG.md（进度追踪）
Step 5: 开始第一项任务

示例对话：

用户: 创建一个博客系统项目，用 Node.js 实现

QClaw: ✅ 项目已创建: 博客系统

📁 位置: tasks/博客系统/
📄 PROJECT.md - 项目简报
📄 CHANGELOG.md - 进度追踪

🎯 目标: 用 Node.js 实现博客系统

下一步: 定义详细需求

请告诉我：

1. 1. 博客系统需要哪些功能？
2. 使用什么数据库？

继续项目

当用户说 继续[项目名]项目 时：

Step 1: 读取 tasks/{项目名}/PROJECT.md（了解上下文）
Step 2: 读取 tasks/{项目名}/CHANGELOG.md（了解进度）
Step 3: 执行定向协议（PROJECT.md 中定义）
Step 4: 从下一步继续工作

示例对话：

用户: 继续博客系统项目

QClaw: 📋 继续项目: 博客系统

📊 当前状态: Phase 2 进行中
📈 进度: 5/12 任务，42%

🔄 Ralph Loop: 迭代 4/20

📍 下一步: 实现文章 API

[开始工作...]

查看项目状态

用户: 我有哪些项目？

QClaw: 📋 项目列表 (共 3 个)

名称 | 状态 | 进度
------------------------|----------------|---------
博客系统 | Phase 2 | 42%
用户管理API | 已完成 | 100%
数据分析工具 | Phase 1 | 15%

文件结构

每个项目都有标准结构：

workspace/
├── tasks/
│ └── {项目名}/
│ ├── PROJECT.md # 项目简报（目标、成功标准、定向协议）
│ ├── CHANGELOG.md # 进度追踪（跨会话记忆）
│ ├── tests/ # 测试预言机
│ └── src/ # 项目源代码
└── memory/
└── YYYY-MM-DD.md # 每日记录

核心组件

1. PROJECT.md - 项目简报

每个项目的说明书：

markdown

PROJECT.md - {项目名称}

项目概述

交付物

• - [ ] 交付物1
• [ ] 交付物2

成功标准

• - 所有测试通过
• 测试覆盖率 > 80%
• 功能完整可用

定向协议

1. 1. 读取 CHANGELOG.md 的当前状态和下一步
2. 运行快速测试确认无回归
3. 从优先列表选择任务
4. 开始工作

不要做的事

• - ❌ 跳过定向协议
• ❌ 重新尝试已记录为失败的方法
• ❌ 在测试失败时提交代码

2. CHANGELOG.md - 进度追踪

最重要的文件！ 智能体的长期记忆：

markdown

CHANGELOG.md

当前状态: Phase 2 进行中

1. 1. 实现文章 API
2. 编写测试

Ralph Loop 状态:
迭代: 4/20
成功标准: 所有测试通过，覆盖率>80%

失败的方法

⚠️ 最重要！防止重复尝试

方法：使用 Python 实现 - 2026-03-19

完成的任务

2026-03-19: 用户模型实现

• - 实现 User 数据类
• 10 个测试用例通过
• 提交: abc123

会话日志

Session 4 - 2026-03-19

3. 测试预言机

让智能体能自主判断是否在进步：

4. Ralph Loop

解决智能体惰性问题——智能体有时会在完成部分任务后找借口停下来。

实现：循环检查，确保真正完成

for i in 1..MAX_ITERATIONS:
result = agent.work(task)
if result.includes(DONE) and verify_completion():
break
else:
agent.continue(你确定完成了吗？请验证：{success_criteria})

在 CHANGELOG.md 中声明：

markdown
Ralph Loop 状态:
迭代: 1/20
成功标准: 所有测试通过，覆盖率>80%

每次会话检查是否达到标准，未达到则继续推进。

5. Git 协调

每个有意义的工作单元后提交代码：

一个功能实现 → 一次提交
一个 bug 修复 → 一次提交
一个重构 → 一次提交

命令参考

工作规则

必须做

• - ✅ 每个子任务完成后更新 CHANGELOG.md
• ✅ 先写测试再写代码（TDD）
• ✅ 记录所有失败的方法（最重要！）
• ✅ 使用定向协议确保从正确位置开始
• ✅ 简洁输出（成功5-10行，失败20行）

禁止做

• - ❌ 跳过定向协议
• ❌ 重新尝试已记录为失败的方法
• ❌ 在测试失败时提交代码
• ❌ 打印完整数组或日志
• ❌ 冗长的描述

输出规范

创建项目时

✅ 项目已创建: {项目名}

📁 位置: tasks/{项目名}/
📄 PROJECT.md - 项目简报
📄 CHANGELOG.md - 进度追踪

🎯 目标: {项目目标}
📊 成功标准: {成功标准}

下一步: {第一个任务}

继续项目时

📋 继续项目: {项目名}

📊 当前状态: {状态}
📈 进度: {X/Y 任务，Z%}

🔄 Ralph Loop: 迭代 {N}/20

📍 下一步: {下一个任务}

[开始工作...]

更新进度时

📝 进度已更新

状态: {新状态}
进度: {X/Y → X+1/Y}
完成: {刚完成的任务}
下一步: {新任务}

与 HEARTBEAT 集成

可以将项目检查加入 HEARTBEAT.md，实现后台持续推进：

markdown

当前 Ralph Loop 任务

项目: 博客系统
迭代: 4/20
成功标准: 所有测试通过

检查：是否需要继续推进？

模板文件

详见 references/ 目录：

• - project-template.md - PROJECT.md 完整模板
• [changelog-template.md](references/ch