| name | long-running-agent |
| description | 长周期任务管理框架，基于 Anthropic 官方最佳实践，支持多代理协作、进度追踪、强制闭环。触发词：长任务、复杂项目、多会话、团队协作、子代理。 |
| version | 4 |
Long-Running Agent 长周期任务管理 v4.0
重要： 所有 Agent 必须遵守 behavior-guidelines.md 中的行为准则！
该文件定义了说话风格、工作流程、安全协议等核心规范。
基于 Anthropic 官方研究构建：
一、核心理念：简单优先，渐进复杂
黄金法则
❌ 不要一开始就构建复杂的代理系统
✅ 从简单的 Prompt 开始，优化评估后再增加复杂度
✅ 只有在简单方案不够时才添加多步骤代理系统
成功的三个核心原则
- 保持简单：不需要时不要增加复杂度
- 透明化：明确展示 Agent 的推理过程
- 精心设计工具接口：通过良好的工具文档实现控制
二、Token 使用量决定性能（核心原理）
关键数据
在 BrowseComp 评估中，三个因素解释了 95% 的性能方差：
- Token 使用量（80%）← 最重要！
- 工具调用次数
- 模型选择
结论：多代理架构通过分配工作到独立上下文窗口，
有效扩展 Token 使用量，突破单代理限制。
多代理系统性能数据
| 指标 | 数值 |
|---|
| 单代理 → 多代理性能提升 | 90.2% |
| 代理 Token 消耗 | 约 4× 聊天 |
| 多代理 Token 消耗 | 约 15× 聊天 |
适用场景判断
✅ 适合多代理：
- 任务可并行化
- 信息超过单上下文窗口
- 需要多种工具/视角
❌ 不适合多代理：
- 所有代理需共享相同上下文
- 代理间有大量依赖关系
- 大多数编码任务（并行化任务较少）
三、五大工作流模式详解
模式总览
| 模式 | 适用场景 | 复杂度 | 本框架使用 |
|---|
| Prompt Chaining | 固定步骤任务 | ⭐ | 辅助 |
| Routing | 分类导向处理 | ⭐⭐ | 辅助 |
| Parallelization | 可并行子任务 | ⭐⭐ | 辅助 |
| Orchestrator-Workers | 复杂不可预测任务 | ⭐⭐⭐ | 核心 |
| Evaluator-Optimizer | 需要迭代改进 | ⭐⭐⭐ | 核心 |
1. Prompt Chaining（提示链）
任务分解为固定步骤，每步处理上一步输出
适用场景：
- 任务可清晰分解为固定子任务
- 愿意用延迟换取更高准确性
示例：
输入 → LLM调用1 → 检查点 → LLM调用2 → 检查点 → 输出
2. Routing（路由）
分类输入，导向专门的处理流程
适用场景：
- 复杂任务有明确分类
- 不同类别需要不同处理
示例：
输入 → 分类器 → 路由到专门Prompt → 输出
3. Parallelization（并行化）
多个 LLM 同时工作，结果聚合
两种变体：
- 分段：任务分成独立部分并行处理
- 投票：多个 LLM 尝试同一任务，取多数
适用场景：
- 子任务可并行化
- 需要多视角或多次尝试提高置信度
4. Orchestrator-Workers（编排者-工作者）⭐ 核心
中央 LLM 动态分解任务，委托给 Worker LLM，综合结果
适用场景：
- 复杂任务无法预测子任务（如编程，文件数量和改动类型不确定）
- 需要灵活性而非预定义子任务
架构图：
┌─────────────────────────────────────────────────────┐
│ Lead Agent │
│ (分析查询，制定策略，分配任务，综合结果) │
└─────────────────┬───────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Subagent│ │Subagent│ │Subagent│
│ (搜索) │ │ (编码) │ │ (测试) │
└────────┘ └────────┘ └────────┘
│ │ │
└─────────────┴─────────────┘
│
▼
Lead Agent 综合
│
▼
Reviewer 审查
│
▼
完成 ✓
多代理系统的优势：
- 并行压缩：Subagent 独立探索，只返回最重要的 Token 给 Lead Agent
- 关注分离：不同的工具、提示和探索路径
- 性能提升：Claude Opus 4 Lead + Sonnet 4 Subagents 比单代理 Opus 4 性能提升 90.2%
多代理系统的代价：
- 代理使用约 4× Token（相比聊天）
- 多代理系统使用约 15× Token（相比聊天）
- 经济可行性要求任务价值足够高
5. Evaluator-Optimizer（评估者-优化者）⭐ 核心
一个 LLM 生成响应，另一个提供评估和反馈，循环迭代
这是 Claude Code 最推荐的模式！
适用场景：
- 有明确的评估标准
- 迭代改进有可衡量的价值
- LLM 响应可通过人类反馈改进
四、Token 效率原则
核心数据
Token 使用量解释 80% 的性能方差
关键限制：
- 单次输出限制：25,000 tokens
- 评估最小样本：~20 个测试用例
- 中位数代理运行时间：~45 秒
效率优化实践
## 输出优化
❌ 错误：返回全部数据
```json
{"data": [/* 1000 条记录 */]}
✅ 正确：返回摘要 + 分页
{
"summary": "找到 1000 条记录",
"page": 1,
"per_page": 20,
"items": [],
"has_more": true
}
搜索优化
❌ 错误：单次大搜索
"搜索所有 Hyprland 配置问题"
✅ 正确：多次精准搜索
- "Hyprland keybind conflict" (小)
- "Hyprland config syntax error" (小)
- "Hyprland window rules" (小)
工具返回优化
优先返回：
✅ name, image_url, file_type（直接信息）
❌ uuid, 256px_image_url, mime_type（技术标识符）
自然语言标识符比 UUID 更有效：
- UUID: "a1b2c3d4" → 容易幻觉
- 语义 ID: "user_jane" → 精确检索
### 效率优化原则
```markdown
1. 分页获取大数据
2. 压缩输出返回摘要
3. 多次小搜索优于单次大搜索
4. 单次输出限制 25,000 tokens
5. 错误提示要明确具体
五、核心问题：Agent 容易"假装完成"
❌ 写了几行代码就标记完成
❌ 没有运行测试验证
❌ 没有人 review
❌ 遇到问题就跳过
❌ 会话结束进度丢失
六、六大强制机制
1. 任务必须定义"完成标准"
TaskCreate 时必须包含：
TaskCreate(
subject: "实现登录 API",
description: `
开发 POST /login 接口
## 完成标准（必须全部满足）
- [ ] API 能响应 POST /login
- [ ] 正确用户返回 JWT token
- [ ] 错误密码返回 401
- [ ] 单元测试通过
## 验证命令
npm test
`
)
2. Reviewer 角色必须存在
每个团队必须有 reviewer，负责：
团队成员:
- project-lead: 协调
- researcher: 调研
- coder: 编码
- reviewer: 审查 ← 必须！
- tester: 测试
3. 强制闭环流程
Agent 完成工作
↓
不能直接标记 completed！
↓
必须发送消息给 reviewer 审查：
SendMessage(
type: "message",
recipient: "reviewer",
content: "任务 #X 请求审查..."
)
↓
Reviewer 验证后回复：
SendMessage(
type: "message",
recipient: "coder",
content: "审查通过 ✅ / 不通过 ❌"
)
↓
只有审查通过时才能 TaskUpdate(status: "completed")
4. Agent 自查清单（强制执行）
在标记完成前，Agent 必须自查：
## 自查清单
1. 我是否运行了相关测试？
2. 我是否验证了"完成标准"的每一项？
3. 我是否更新了相关文档？
4. 代码是否能正常编译/运行？
5. 是否有遗留的 TODO 或 FIXME？
**如果任何一项是"否"，不能标记完成！**
5. 进度持久化（强制）
每个会话结束时必须写入：
{
"last_session": "2024-03-13T15:00:00",
"completed": ["task-1", "task-2"],
"in_progress": "task-3",
"next_steps": ["完成 API 测试"],
"notes": "登录逻辑已实现"
}
6. 会话恢复协议
新会话开始时必须：
1. 读取 progress.json
2. 检查 TaskList
3. 找到 in_progress 的任务
4. 发送消息唤醒相关 Agent
5. 如果 Agent 已关闭，重新 spawn
七、角色配置标准
角色定义
| 角色 | subagent_type | 职责 | 必须性 |
|---|
| project-lead | general-purpose | 协调、综合、决策 | 必须 |
| researcher | Explore | 搜索、分析、调研 | 按需 |
| coder | general-purpose | 编码、实现 | 按需 |
| reviewer | general-purpose | 审查、验证 | 必须！ |
| tester | general-purpose | 测试、验证 | 按需 |
项目类型配置
软件开发项目：
团队成员:
- project-lead (team-lead): 协调进度、审阅代码
- researcher: 技术调研、方案设计
- coder-1: 前端开发
- coder-2: 后端开发
- reviewer: 代码审查 ← 必须
- tester: 测试验证
文档/写作项目：
团队成员:
- project-lead: 统筹进度
- researcher: 资料收集、深度调研
- writer-1: 主要撰写
- writer-2: 辅助撰写
- editor: 审阅修订 ← 必须（相当于 reviewer）
研究/分析项目：
团队成员:
- project-lead: 统筹方向
- researcher-1: 主要研究
- researcher-2: 辅助研究
- analyst: 数据分析
- reviewer: 结果验证 ← 必须
八、创建团队的标准流程
完整初始化示例
TeamCreate(
team_name: "auth-system",
description: "开发用户认证系统"
)
TaskCreate(
subject: "实现登录 API",
description: `
开发 POST /login 接口
## 完成标准
- [ ] 返回 JWT token
- [ ] 密码错误返回 401
- [ ] 测试覆盖率 > 80%
## 验证命令
npm test
curl -X POST localhost:3000/login -d '{"user":"test","pass":"wrong"}'
`,
activeForm: "开发登录 API"
)
Agent(subagent_type: "general-purpose", name: "coder", team_name: "auth-system")
Agent(subagent_type: "general-purpose", name: "reviewer", team_name: "auth-system")
Agent(subagent_type: "general-purpose", name: "tester", team_name: "auth-system")
TaskUpdate(taskId: "1", owner: "coder")
九、Evaluator-Optimizer 模式实现
核心流程图
┌─────────┐ ┌──────────┐ ┌─────────┐
│ Worker │ ──→ │ Reviewer │ ──→ │ approve │ ──→ 完成
└─────────┘ └──────────┘ │ = true? │
↑ │ └─────────┘
└───────────────┘
approve = false (返回修改)
强制执行规则
**禁止行为**：
- ❌ Worker 直接标记 completed
- ❌ 没有 Reviewer 就标记完成
- ❌ Reviewer 未通过就继续
**必须行为**：
- ✅ Worker 完成后发送 review 请求
- ✅ Reviewer 运行测试验证
- ✅ 只有 approve=true 才能 TaskUpdate(status: "completed")
Reviewer 验证清单
## 审查清单
1. **功能验证**
- [ ] 代码能否正常编译/运行？
- [ ] 测试是否通过？
- [ ] 完成标准是否全部满足？
2. **质量检查**
- [ ] 代码风格是否一致？
- [ ] 是否有 TODO/FIXME 遗留？
- [ ] 是否遵循最佳实践？
3. **安全审查**
- [ ] 是否有安全风险？
- [ ] 敏感信息是否泄露？
十、Agent 行为规范
Coder 角色规范
当我认为任务完成时：
1. 先运行测试：npm test
2. 检查完成标准的每一项
3. 如果测试失败 → 修复 → 重新测试
4. 如果测试通过 → 发送 review 请求：
SendMessage(
type: "message",
recipient: "reviewer",
content: """
任务 #1 请求审查
完成标准检查：
- [x] 返回 JWT token
- [x] 密码错误返回 401
- [x] 测试覆盖率 85%
验证命令：
- npm test
- npm run coverage
文件变更：
- src/auth/login.ts
- tests/auth.test.ts
"""
)
5. 等待 reviewer 回复
6. 如果被拒绝 → 修复 → 重新请求审查
7. 如果通过 → TaskUpdate(status: "completed")
Reviewer 角色规范
收到 review 请求后：
1. 读取相关文件
2. 运行测试：npm test
3. 检查代码质量
4. 回复：
如果通过：
SendMessage(
type: "message",
recipient: "coder",
content: "审查通过 ✅\n\n所有测试通过，代码质量良好。\n\n你可以标记任务完成了。"
)
如果不通过：
SendMessage(
type: "message",
recipient: "coder",
content: "审查不通过 ❌\n\n问题：\n1. 测试用例缺少边界情况\n2. 缺少错误处理\n\n请修复后重新提交审查。"
)
十一、项目文件结构
初始化时自动创建：
project/
├── .agent/
│ ├── progress.json # 进度追踪
│ ├── feature_list.json # 功能列表
│ └── session.log # 会话日志
├── research/ # 研究资料
├── drafts/ # 草稿/开发中
├── review/ # 审阅中
└── completed/ # 已完成
进度文件位置
进程唯一（推荐）：绑定到项目路径
{项目目录}/.agent/progress.json
{项目目录}/.agent/feature_list.json
团队配置仍然放在全局：
~/.claude/teams/{project-hash}/config.json
十二、会话恢复流程
每个新会话开始时执行：
cat .agent/progress.json
TaskList
Read ~/.claude/teams/{team-name}/config.json
会话恢复示例
# 新会话开始
1. 读取 ~/.claude/teams/auth-system/progress.json
→ in_progress: "task-3"
→ next_steps: ["完成 API 测试"]
2. 检查 TaskList
→ task-3 status: in_progress, owner: coder
3. 检查 team config
→ coder: 已关闭
4. 重新 spawn coder
Agent(subagent_type: "general-purpose", name: "coder", team_name: "auth-system")
5. 发送恢复消息
SendMessage(
recipient: "coder",
content: "继续工作：task-3\n\n下一步：完成 API 测试\n\n上次进度：登录逻辑已实现"
)
十三、Git 自动化
自动初始化
如果项目没有 git，自动初始化：
cd {项目目录}
git init
git add .
git commit -m "初始化项目"
进度变更自动提交
每次任务状态变化时，自动提交：
任务开始 → git commit -m "开始: {任务名}"
任务完成 → git commit -m "完成: {任务名}"
重要修改 → git commit -m "更新: {修改描述}"
会话结束 → git commit -m "进度: 保存会话进度"
十四、五不原则
| 原则 | 含义 |
|---|
| 不做完不结束 | 每个任务必须有明确完成标准 |
| 不验证不完成 | 必须有人审查 |
| 不记录不结束 | 必须写入进度 |
| 不恢复不开始 | 新会话必须检查上次进度 |
| 不提交不结束 | 每次变更必须 git commit |
十五、评估与迭代
1. 立即开始小样本评估
早期代理开发中，变化有巨大影响：
- 一个提示调整可能从 30% 提升到 80%
- 只需要约 20 个测试用例
- 不要等到有几百个测试用例才开始
最佳实践：小规模测试立即开始，而非延迟
2. LLM-as-Judge
使用 LLM 评估输出的标准：
- 事实准确性（声明是否匹配来源？）
- 引用准确性（引用来源是否匹配声明？）
- 完整性（是否覆盖所有请求方面？）
- 来源质量（是否使用主要来源？）
- 工具效率（工具使用是否合理？）
推荐：单个 LLM 调用输出 0.0-1.0 分数和通过/失败
十六、生产可靠性
1. 代理是有状态的，错误会复合
- 代理可能运行很长时间
- 小错误可能导致代理探索完全不同的轨迹
- 需要能够从错误发生点恢复
- 让代理知道工具失败并让其适应
2. 调试需要新方法
代理是非确定性的，相同提示可能产生不同结果
解决方案：
- 完整的生产追踪
- 监控代理决策模式
- 不监控对话内容（保护隐私）
十七、触发条件
当检测到以下情况时，自动启动此 skill：
- 用户说"帮我开发/创建/实现一个..."
- 任务涉及多个模块或文件
- 预估工作量超过一个会话
- 用户明确提到"团队"、"分工"、"协作"
- 任务可以分解为 3+ 个子任务
关键数字速查
| 指标 | 数值 |
|---|
| 代理 Token 消耗 | 约 4× 聊天 |
| 多代理 Token 消耗 | 约 15× 聊天 |
| 多代理性能提升 | 90.2% (vs 单代理) |
| Token 使用解释方差 | 80% |
| 工具响应限制 | 25,000 tokens |
| 评估最小样本 | ~20 个测试用例 |
| 中位数代理运行时间 | ~45 秒 |
参考资源
v4.0 - 更新于 2026-03-13
整合 Anthropic 官方最佳实践
