English | 中文
A universal framework for AI agents to work continuously across multiple sessions with auto-run, triple protection, and multiple task templates.
Based on Anthropic's Engineering Blog.
- 🔄 Auto-Run - Automatic task execution loop without manual intervention
- 🛡️ Triple Protection - Layer protection + Sandbox + Git validation
- 📝 Multiple Templates - Web development, data analysis, research, documentation, etc.
- 📋 Problem Recording - Automatically avoid known issues in future sessions
- 🎯 One Task Per Session - Prevent context overflow
# Copy framework
cp -r long-running-agent my-project && cd my-project
# Initialize (first time)
opencode
> 请阅读 prompts/initializer.md 并按照指示开始工作。
# Auto-run
./scripts/auto-run.sh基于 Anthropic 的工程博客 实现，用于支持 AI 代理在多个会话中持续工作的通用框架。
- 🔄 自动运行 - 无需手动干预，自动循环执行任务
- 🛡️ 三重保护 - 分层保护 + 沙盒隔离 + Git 变更检测
- 📝 多任务模板 - Web开发、数据分析、研究、文档等
- 📋 问题记录 - 自动记录已知问题，下次会话规避
- 🎯 一次一个 - 防止上下文溢出
AI 代理在多个上下文窗口工作时面临挑战：
| 问题 | 描述 |
|---|---|
| 无记忆 | 每个新会话没有之前的记忆 |
| 上下文溢出 | 一次性做太多导致上下文耗尽 |
| 过早完成 | 容易过早宣布项目完成 |
| 状态混乱 | 会话间可能留下破损的代码状态 |
采用双代理模式 + 严格边界限制 + 三重保护机制。
┌─────────────────────────────────────────────────────────────┐
│ 项目生命周期 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 阶段 1: 初始化（仅首次） │
│ ───────────────────── │
│ Initializer Agent → 创建任务配置和功能列表 │
│ │
│ 阶段 2: 工作循环（重复执行） │
│ ───────────────────── │
│ Worker Agent × N 次 → 逐个实现功能 │
│ │
│ 阶段 3: 完成 │
│ ───────────────────── │
│ 所有功能 passes: true → 项目完成 │
│ │
└─────────────────────────────────────────────────────────────┘
触发方式：首次使用，手动输入提示词
请阅读 prompts/initializer.md 并按照指示开始工作。
执行流程：
┌─────────────────────────────────────────────────────────────┐
│ Initializer Agent 执行流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 步骤 1: 检查现有配置 │
│ ├── 检查 core/config.json 是否存在 │
│ └── 如果存在 → 跳过初始化 │
│ │
│ 步骤 2: 选择任务模板 │
│ ├── 展示可用模板列表 │
│ ├── 用户选择或创建自定义模板 │
│ └── 加载模板配置 │
│ │
│ 步骤 3: 填写任务规格 │
│ ├── 引导用户描述任务需求 │
│ └── 保存到 prompts/task_spec.md │
│ │
│ 步骤 4: 创建功能列表 │
│ ├── 基于任务规格拆解功能 │
│ ├── 生成 100-200+ 功能项 │
│ └── 保存到 core/feature_list.json │
│ │
│ 步骤 5: 初始化进度文件 │
│ └── 创建 core/progress.md │
│ │
│ 步骤 6: 创建任务配置 │
│ └── 保存到 core/config.json │
│ │
│ 步骤 7: Git 提交 │
│ └── git commit -m "初始化..." │
│ │
└─────────────────────────────────────────────────────────────┘
输出文件：
core/config.json- 任务配置core/feature_list.json- 功能列表（100-200+项）core/progress.md- 进度记录core/known_issues.md- 已知问题（空文件）prompts/task_spec.md- 任务规格说明
触发方式：每次新会话，手动输入或自动运行
请阅读 prompts/worker.md 并按照指示继续工作。
执行流程（9步）：
┌─────────────────────────────────────────────────────────────┐
│ Worker Agent 单次会话流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 步骤 1: 了解状态 ────────────────────────────────────────── │
│ ├── 读取 core/config.json（任务配置） │
│ ├── 读取 prompts/task_spec.md（任务规格） │
│ ├── 读取 core/feature_list.json（功能列表） │
│ ├── 读取 core/progress.md（进度记录） │
│ ├── 读取 core/known_issues.md（已知问题，重要！） │
│ └── 检查 git log（最近提交） │
│ │
│ 步骤 2: 验证已有功能 ────────────────────────────────────── │
│ ├── 选择 1-2 个 passes: true 的功能 │
│ ├── 按步骤验证 │
│ └── 如有问题 → 标记 passes: false + 修复 │
│ │
│ 步骤 3: 选择一个功能 ────────────────────────────────────── │
│ ├── 找到 passes: false 的功能 │
│ ├── 按 priority 排序（high > medium > low） │
│ └── 选择最高优先级 │
│ │
│ 步骤 4: 实现功能 ────────────────────────────────────────── │
│ ├── 理解需求 │
│ ├── 编写/修改代码 │
│ └── 初步测试 │
│ │
│ 步骤 5: 验证功能 ────────────────────────────────────────── │
│ ├── 端到端测试（单元测试不够） │
│ └── 验证通过才能继续 │
│ │
│ 步骤 6: 更新功能列表 ────────────────────────────────────── │
│ └── 只改 passes: false → passes: true │
│ │
│ 步骤 7: Git 变更检测 ────────────────────────────────────── │
│ ├── git diff --name-only │
│ ├── 检查是否修改了保护文件 │
│ └── 违规则回滚 │
│ │
│ 步骤 8: 提交进度 ────────────────────────────────────────── │
│ └── git commit │
│ │
│ 步骤 9: 更新进度文件 ────────────────────────────────────── │
│ ├── 更新 core/progress.md │
│ └── 如有问题 → 更新 core/known_issues.md │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ 还有未完成功能？│
└────────┬────────┘
│
┌──────────────┴──────────────┐
│ Yes │ No
▼ ▼
开启新会话 项目完成！
继续执行 Worker Agent
使用 scripts/auto-run.sh 自动循环执行 Worker Agent。
执行流程：
┌─────────────────────────────────────────────────────────────┐
│ auto-run.sh 执行流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 检查环境 │
│ ├── 检查 core/feature_list.json │
│ └── 检查 prompts/worker.md │
│ │
│ 2. 循环执行 ┌──────────────────────────────────────────┐ │
│ │ │ │
│ │ a. 检查剩余任务 → 为 0 则退出 │ │
│ │ │ │
│ │ b. 设置 AUTO_RUN_MODE=true │ │
│ │ │ │
│ │ c. 运行 opencode（执行 worker.md） │ │
│ │ │ │
│ │ d. 检查进度变化 │ │
│ │ ├── 有进展 → 重置计数器 │ │
│ │ └── 无进展 → 增加计数器 │ │
│ │ │ │
│ │ e. 连续 3 次无进展 → 停止并警告 │ │
│ │ │ │
│ └──────────────────────────────────────────┘ │
│ │
│ 3. 退出条件 │
│ ├── 所有任务完成 │
│ ├── 达到最大迭代次数（默认 300） │
│ └── 连续 3 次无进展 │
│ │
└─────────────────────────────────────────────────────────────┘
使用方式：
# 基本使用
./scripts/auto-run.sh
# 自定义参数
MAX_ITERATIONS=100 DELAY_SECONDS=10 ./scripts/auto-run.sh确保 AI Agent 不会违反边界：
┌─────────────────────────────────────────────────────────────┐
│ 三重保护机制 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 第一层：分层保护（预防） │
│ ───────────────────── │
│ 🔴 红色层：core/config.json, prompts/, templates/ │
│ → 绝对禁止修改 │
│ 🟡 黄色层：core/feature_list.json │
│ → 只能修改 passes 字段 │
│ 🟢 绿色层：src/, output/, 其他 │
│ → 自由操作 │
│ │
│ 第二层：沙盒操作（隔离） │
│ ───────────────────── │
│ AI 创建的脚本必须在 .sandbox/ 中执行 │
│ 即使脚本有 bug，也不会直接破坏核心文件 │
│ │
│ 第三层：Git 变更检测（检测） │
│ ───────────────────── │
│ 在 git commit 前检查修改的文件 │
│ 如果违规 → git checkout 回滚 │
│ │
└─────────────────────────────────────────────────────────────┘
详细说明：边界保护实现
| 文件 | 作用 | 谁可以修改 | 分层 |
|---|---|---|---|
core/config.json |
任务配置 | 仅 Initializer Agent | 🔴 红色 |
prompts/task_spec.md |
任务规格说明 | 仅 Initializer Agent | 🔴 红色 |
prompts/*.md |
代理提示词 | 用户手动 | 🔴 红色 |
templates/ |
任务模板 | 用户手动 | 🔴 红色 |
core/feature_list.json |
功能列表 | Worker Agent 只能改 passes | 🟡 黄色 |
core/progress.md |
进度记录 | Worker Agent 每次会话更新 | 🟢 绿色 |
core/known_issues.md |
已知问题记录 | Worker Agent 遇到问题时更新 | 🟢 绿色 |
src/, output/ 等 |
项目文件 | Worker Agent 自由操作 | 🟢 绿色 |
遇到问题时记录到 core/known_issues.md，下次会话自动规避：
┌─────────────────────────────────────────────────────────────┐
│ 问题记录流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 会话开始时： │
│ ─────────── │
│ 1. 读取 core/known_issues.md │
│ 2. 了解之前遇到的问题 │
│ 3. 规避已知问题 │
│ │
│ 遇到新问题时： │
│ ─────────── │
│ 1. 记录到 core/known_issues.md │
│ 2. 描述问题和原因 │
│ 3. 提供规避方法 │
│ │
└─────────────────────────────────────────────────────────────┘
记录格式：
## [ISS-001] 问题标题
**状态**：open / resolved
**发现时间**：YYYY-MM-DD
**发现于功能**：F001
**影响范围**：描述影响
### 问题描述
详细描述问题
### 问题原因
分析原因
### 规避方法
1. 具体步骤
2. 注意事项cp -r lrf-test-template-01 my-project
cd my-projectopencode请阅读 prompts/initializer.md 并按照指示开始工作。
手动运行：
请阅读 prompts/worker.md 并按照指示继续工作。
自动运行：
./scripts/auto-run.sh| 模板 | 用途 | 功能数建议 |
|---|---|---|
web-development |
前后端 Web 应用开发 | 200+ |
data-analysis |
数据处理、分析、可视化 | 100+ |
research |
文献调研、实验分析 | 80+ |
documentation |
技术文档、教程编写 | 60+ |
product-requirements |
产品需求拆解、技术方案 | 80+ |
custom |
自定义任务 | 用户定义 |
| 规则 | 说明 |
|---|---|
| 只改 passes | 只能将 passes: false 改为 passes: true |
| 一次一个 | 每次会话只完成一个功能 |
| 先验证后标记 | 必须验证通过后才能标记完成 |
| 干净退出 | 会话结束时代码必须可工作 |
| 必须提交 | 每次会话必须 git commit |
| 记录问题 | 遇到问题记录到 known_issues.md |
- ❌ 删除功能列表中的任何功能
- ❌ 修改功能的描述或步骤
- ❌ 跳过验证就标记完成
- ❌ 一次尝试多个功能
- ❌ 修改红色层文件
lrf-test-template-01/
│
├── core/ # 框架核心（任务运行时数据）
│ ├── config.json # 任务配置 🔴
│ ├── feature_list.json # 功能列表 🟡
│ ├── progress.md # 进度记录 🟢
│ └── known_issues.md # 已知问题 🟢
│
├── prompts/ # 代理提示词 🔴
│ ├── initializer.md # 初始化代理
│ ├── worker.md # 工作代理（9步流程）
│ ├── template_wizard.md # 模板创建向导
│ └── task_spec.md # 任务规格模板
│
├── templates/ # 任务模板 🔴
│ ├── web-development/ # Web 开发
│ ├── data-analysis/ # 数据分析
│ ├── research/ # 研究任务
│ ├── documentation/ # 文档编写
│ ├── product-requirements/ # 产品需求拆解
│ └── _custom/ # 自定义模板
│
├── scripts/ # 脚本
│ └── auto-run.sh # 自动化运行脚本
│
├── docs/ # 文档
│ ├── theory/ # 理论文档
│ │ └── 长时间运行代理框架翻译.md
│ └── guides/ # 使用指南
│ ├── quick-start.md # 快速开始
│ ├── create-template.md # 创建自定义模板
│ ├── best-practices.md # 最佳实践
│ ├── boundaries.md # 边界限制详解
│ ├── protection-implementation.md # 边界保护实现
│ └── auto-run.md # 自动化运行指南
│
└── .sandbox/ # 沙盒目录（AI 脚本执行）
├── scripts/ # AI 创建的脚本
├── temp/ # 临时文件
└── output/ # 脚本输出
| 文档 | 内容 | 适合谁 |
|---|---|---|
| 快速开始 | 详细的使用步骤 | 新用户 |
| 创建自定义模板 | 如何创建自己的任务模板 | 需要自定义任务的用户 |
| 最佳实践 | 使用技巧和常见问题 | 所有用户 |
| 边界限制详解 | 为什么需要边界、如何遵守 | 所有用户 |
| 边界保护实现 | 三重保护机制的技术实现 | 想了解技术细节的用户 |
| 自动化运行指南 | 自动化脚本使用方法 | 想要自动运行的用户 |
| 理论翻译 | Anthropic 原文翻译 | 想深入了解的用户 |
如果你想对框架进行迭代，以下是各功能的实现位置：
| 功能 | 实现位置 | 说明 |
|---|---|---|
| 初始化流程 | prompts/initializer.md |
修改初始化步骤 |
| 工作流程 | prompts/worker.md |
修改 9 步流程 |
| 分层保护 | prompts/worker.md → "三重保护机制" |
修改文件分层 |
| 沙盒规则 | prompts/worker.md → "第二层：沙盒操作" |
修改沙盒规则 |
| Git 检测 | prompts/worker.md → "步骤 7：Git 变更检测" |
修改检测规则 |
| 自动运行 | scripts/auto-run.sh |
修改自动运行逻辑 |
| 问题记录 | core/known_issues.md |
问题记录文件 |
| 新增模板 | templates/ |
创建新模板目录 |