菜单
长周期任务管理框架，基于 Anthropic 官方最佳实践，支持多代理协作、进度追踪、强制闭环。触发词：长任务、复杂项目、多会话、团队协作、子代理。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | long-running-agent |
| description | 长周期任务管理框架，基于 Anthropic 官方最佳实践，支持多代理协作、进度追踪、强制闭环。触发词：长任务、复杂项目、多会话、团队协作、子代理。 |
| version | 4 |
重要： 所有 Agent 必须遵守
behavior-guidelines.md中的行为准则！ 该文件定义了说话风格、工作流程、安全协议等核心规范。基于 Anthropic 官方研究构建：
❌ 不要一开始就构建复杂的代理系统
✅ 从简单的 Prompt 开始，优化评估后再增加复杂度
✅ 只有在简单方案不够时才添加多步骤代理系统
在 BrowseComp 评估中，三个因素解释了 95% 的性能方差：
- Token 使用量（80%）← 最重要！
- 工具调用次数
- 模型选择
结论：多代理架构通过分配工作到独立上下文窗口，
有效扩展 Token 使用量，突破单代理限制。
| 指标 | 数值 |
|---|---|
| 单代理 → 多代理性能提升 | 90.2% |
| 代理 Token 消耗 | 约 4× 聊天 |
| 多代理 Token 消耗 | 约 15× 聊天 |
✅ 适合多代理：
- 任务可并行化
- 信息超过单上下文窗口
- 需要多种工具/视角
❌ 不适合多代理：
- 所有代理需共享相同上下文
- 代理间有大量依赖关系
- 大多数编码任务（并行化任务较少）
| 模式 | 适用场景 | 复杂度 | 本框架使用 |
|---|---|---|---|
| Prompt Chaining | 固定步骤任务 | ⭐ | 辅助 |
| Routing | 分类导向处理 | ⭐⭐ | 辅助 |
| Parallelization | 可并行子任务 | ⭐⭐ | 辅助 |
| Orchestrator-Workers | 复杂不可预测任务 | ⭐⭐⭐ | 核心 |
| Evaluator-Optimizer | 需要迭代改进 | ⭐⭐⭐ | 核心 |
任务分解为固定步骤，每步处理上一步输出
适用场景：
- 任务可清晰分解为固定子任务
- 愿意用延迟换取更高准确性
示例：
输入 → LLM调用1 → 检查点 → LLM调用2 → 检查点 → 输出
分类输入，导向专门的处理流程
适用场景：
- 复杂任务有明确分类
- 不同类别需要不同处理
示例：
输入 → 分类器 → 路由到专门Prompt → 输出
多个 LLM 同时工作，结果聚合
两种变体：
- 分段：任务分成独立部分并行处理
- 投票：多个 LLM 尝试同一任务，取多数
适用场景：
- 子任务可并行化
- 需要多视角或多次尝试提高置信度
中央 LLM 动态分解任务，委托给 Worker LLM，综合结果
适用场景：
- 复杂任务无法预测子任务（如编程，文件数量和改动类型不确定）
- 需要灵活性而非预定义子任务
架构图：
┌─────────────────────────────────────────────────────┐
│ Lead Agent │
│ (分析查询，制定策略，分配任务，综合结果) │
└─────────────────┬───────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Subagent│ │Subagent│ │Subagent│
│ (搜索) │ │ (编码) │ │ (测试) │
└────────┘ └────────┘ └────────┘
│ │ │
└─────────────┴─────────────┘
│
▼
Lead Agent 综合
│
▼
Reviewer 审查
│
▼
完成 ✓
多代理系统的优势：
多代理系统的代价：
- 代理使用约 4× Token（相比聊天）
- 多代理系统使用约 15× Token（相比聊天）
- 经济可行性要求任务价值足够高
一个 LLM 生成响应，另一个提供评估和反馈，循环迭代
这是 Claude Code 最推荐的模式！
适用场景：
- 有明确的评估标准
- 迭代改进有可衡量的价值
- LLM 响应可通过人类反馈改进
Token 使用量解释 80% 的性能方差
关键限制：
- 单次输出限制：25,000 tokens
- 评估最小样本：~20 个测试用例
- 中位数代理运行时间：~45 秒
## 输出优化
❌ 错误：返回全部数据
```json
{"data": [/* 1000 条记录 */]}
✅ 正确：返回摘要 + 分页
{
"summary": "找到 1000 条记录",
"page": 1,
"per_page": 20,
"items": [/* 20 条记录 */],
"has_more": true
}
❌ 错误：单次大搜索 "搜索所有 Hyprland 配置问题"
✅ 正确：多次精准搜索
优先返回： ✅ name, image_url, file_type（直接信息） ❌ uuid, 256px_image_url, mime_type（技术标识符）
自然语言标识符比 UUID 更有效：
### 效率优化原则
```markdown
1. 分页获取大数据
2. 压缩输出返回摘要
3. 多次小搜索优于单次大搜索
4. 单次输出限制 25,000 tokens
5. 错误提示要明确具体
❌ 写了几行代码就标记完成
❌ 没有运行测试验证
❌ 没有人 review
❌ 遇到问题就跳过
❌ 会话结束进度丢失
TaskCreate 时必须包含：
TaskCreate(
subject: "实现登录 API",
description: `
开发 POST /login 接口
## 完成标准（必须全部满足）
- [ ] API 能响应 POST /login
- [ ] 正确用户返回 JWT token
- [ ] 错误密码返回 401
- [ ] 单元测试通过
## 验证命令
npm test
`
)
每个团队必须有 reviewer，负责：
团队成员:
- project-lead: 协调
- researcher: 调研
- coder: 编码
- reviewer: 审查 ← 必须！
- tester: 测试
Agent 完成工作
↓
不能直接标记 completed！
↓
必须发送消息给 reviewer 审查：
SendMessage(
type: "message",
recipient: "reviewer",
content: "任务 #X 请求审查..."
)
↓
Reviewer 验证后回复：
SendMessage(
type: "message",
recipient: "coder",
content: "审查通过 ✅ / 不通过 ❌"
)
↓
只有审查通过时才能 TaskUpdate(status: "completed")
在标记完成前，Agent 必须自查：
## 自查清单
1. 我是否运行了相关测试？
2. 我是否验证了"完成标准"的每一项？
3. 我是否更新了相关文档？
4. 代码是否能正常编译/运行？
5. 是否有遗留的 TODO 或 FIXME？
**如果任何一项是"否"，不能标记完成！**
每个会话结束时必须写入：
// .agent/progress.json
{
"last_session": "2024-03-13T15:00:00",
"completed": ["task-1", "task-2"],
"in_progress": "task-3",
"next_steps": ["完成 API 测试"],
"notes": "登录逻辑已实现"
}
新会话开始时必须：
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: 结果验证 ← 必须
// 1. 创建团队
TeamCreate(
team_name: "auth-system",
description: "开发用户认证系统"
)
// 2. 创建任务（带完成标准）
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"
)
// 3. Spawn 团队成员
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")
// 4. 分配任务
TaskUpdate(taskId: "1", owner: "coder")
┌─────────┐ ┌──────────┐ ┌─────────┐
│ Worker │ ──→ │ Reviewer │ ──→ │ approve │ ──→ 完成
└─────────┘ └──────────┘ │ = true? │
↑ │ └─────────┘
└───────────────┘
approve = false (返回修改)
**禁止行为**：
- ❌ Worker 直接标记 completed
- ❌ 没有 Reviewer 就标记完成
- ❌ Reviewer 未通过就继续
**必须行为**：
- ✅ Worker 完成后发送 review 请求
- ✅ Reviewer 运行测试验证
- ✅ 只有 approve=true 才能 TaskUpdate(status: "completed")
## 审查清单
1. **功能验证**
- [ ] 代码能否正常编译/运行？
- [ ] 测试是否通过？
- [ ] 完成标准是否全部满足？
2. **质量检查**
- [ ] 代码风格是否一致？
- [ ] 是否有 TODO/FIXME 遗留？
- [ ] 是否遵循最佳实践？
3. **安全审查**
- [ ] 是否有安全风险？
- [ ] 敏感信息是否泄露？
当我认为任务完成时：
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")
收到 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
每个新会话开始时执行：
# 1. 读取进度
cat .agent/progress.json
# 2. 读取任务列表
TaskList
# 3. 检查团队状态
Read ~/.claude/teams/{team-name}/config.json
# 4. 选择下一个任务
# 优先选择：pending + 无 owner + 无 blockedBy
# 新会话开始
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，自动初始化：
cd {项目目录}
git init
git add .
git commit -m "初始化项目"
每次任务状态变化时，自动提交：
任务开始 → git commit -m "开始: {任务名}"
任务完成 → git commit -m "完成: {任务名}"
重要修改 → git commit -m "更新: {修改描述}"
会话结束 → git commit -m "进度: 保存会话进度"
| 原则 | 含义 |
|---|---|
| 不做完不结束 | 每个任务必须有明确完成标准 |
| 不验证不完成 | 必须有人审查 |
| 不记录不结束 | 必须写入进度 |
| 不恢复不开始 | 新会话必须检查上次进度 |
| 不提交不结束 | 每次变更必须 git commit |
早期代理开发中，变化有巨大影响：
- 一个提示调整可能从 30% 提升到 80%
- 只需要约 20 个测试用例
- 不要等到有几百个测试用例才开始
最佳实践：小规模测试立即开始，而非延迟
使用 LLM 评估输出的标准：
- 事实准确性（声明是否匹配来源？）
- 引用准确性（引用来源是否匹配声明？）
- 完整性（是否覆盖所有请求方面？）
- 来源质量（是否使用主要来源？）
- 工具效率（工具使用是否合理？）
推荐：单个 LLM 调用输出 0.0-1.0 分数和通过/失败
- 代理可能运行很长时间
- 小错误可能导致代理探索完全不同的轨迹
- 需要能够从错误发生点恢复
- 让代理知道工具失败并让其适应
代理是非确定性的，相同提示可能产生不同结果
解决方案：
- 完整的生产追踪
- 监控代理决策模式
- 不监控对话内容（保护隐私）
当检测到以下情况时，自动启动此 skill：
| 指标 | 数值 |
|---|---|
| 代理 Token 消耗 | 约 4× 聊天 |
| 多代理 Token 消耗 | 约 15× 聊天 |
| 多代理性能提升 | 90.2% (vs 单代理) |
| Token 使用解释方差 | 80% |
| 工具响应限制 | 25,000 tokens |
| 评估最小样本 | ~20 个测试用例 |
| 中位数代理运行时间 | ~45 秒 |
v4.0 - 更新于 2026-03-13 整合 Anthropic 官方最佳实践
PRD 驱动的完整开发工作流 - 从用户故事分析到自动化测试的端到端流程。 当用户需要"一条龙开发"、"全自动开发"、"从需求到代码"、"先分析PRD再开发"、 "多模型分析后自动开发"、"完整开发流程"、"从需求分析到测试"或任何涉及 PRD分析→需求整合→代码生成→自动化测试的连续工作时，**必须**使用此技能。 整合多模型聚合、Kimi深度整合、PRD生成、多模型代码审查、代码开发、自动化测试等能力。 **新增**: 智能决策大脑(th-workflow-decision-engine) - 自动判断何时使用GitNexus代码分析、 unified-search联网搜索、多模型聚合，测试失败时智能选择修复策略。
PRD驱动工作流的决策大脑 - 智能判断何时使用搜索、代码分析、多模型聚合。 作为子Skill被 th-prd-driven-dev-workflow 调用，负责工具选择和策略决策。
动态 Agent 生成器（母体模式）。当用户需要处理复杂项目时，自动分析需求并生成定制化专业 Agent 团队。接收项目描述、技术栈、版本号、约束条件，输出完整的 Agent 配置和启动命令。触发词：需要专业团队、生成 Agent、创建定制化 Agent、复杂项目团队、动态生成 Agent。
Arch Linux 系统特性（PEP 668、AUR Helpers）
浏览器交互自动化：网页测试、表单填写、截图、数据提取。触发词：打开网页、填写表单、网页截图。
系统化代码审查：安全性、性能、可维护性、正确性、测试覆盖。触发词：代码审查、review 代码、PR 审查。