back
loading skill details...
代理副驾驶是面向 AI Agent 开发者的工程化副驾驶，针对"Prompt 答非所问与幻觉、上下文腐烂（Context Rot）、工具选择不当、任务拆解颗粒度失控"四大高频痛点而设计。它把零散的 Prompt 工程经验沉淀为可复用的模板库、评估器与循环工程（Loops Engineering）工作流，让 Age...
---
slug: agent-copilot-pro
name: agent-copilot-pro
version: "1.0.0"
displayName: 代理副驾驶
summary: 解决Prompt幻觉、上下文腐烂、工具误选、任务拆解不彻底的AI代理工程副驾驶
license: MIT
description: |-
代理副驾驶是面向 AI Agent 开发者的工程化副驾驶，针对"Prompt 答非所问与幻觉、上下文腐烂（Context Rot）、工具选择不当、任务拆解颗粒度失控"四大高频痛点而设计。它把零散的 Prompt 工程经验沉淀为可复用的模板库、评估器与循环工程（Loops Engineering）工作流，让 Agent 从"能跑"升级到"稳定可控"。
核心能力：System Prompt 五段式结构化生成、任务拆解树（DAG）与依赖编排、工具选择决策矩阵、ReAct/CoT/Plan-Execute 三种 Agent Loop 模式、输出解析与 schema 校验、Prompt 质量评估器（含幻觉检测）、Token 预算与上下文腐烂治理。
适用场景：构建客服/助理类 Agent、自动化工作流编排、RAG 应用增强、多 Agent 协作系统、长会话上下文治理、Prompt 评审与回归测试。
差异化：相比仅提供"帮你写 prompt"的浅层助手，本技能新增 (1) 上下文腐烂诊断器，量化三因素（信息密度衰减、噪声累积、注意力漂移）并给出治理建议；(2) 工具选择决策矩阵，基于任务类型、参数复杂度、失败成本三维度推荐工具调用策略；(3) 循环工程工作流，自动发现任务→分配→执行→质检→迭代；(4) Prompt 质量评估器，含幻觉检测与回归测试用例生成；(5) Token 预算管理，按任务复杂度分配上下文配额。
触发关键词：prompt工程、代理设计、任务拆解、工具选择、agent loop、上下文腐烂、幻觉检测、ReAct、CoT、循环工程、prompt engineering、agent design、task decomposition
tags:
- 代理工程
- 提示词工程
- 任务编排
- 质量评估
tools:
- read
- exec
---
# 代理副驾驶（Agent Copilot Pro）
面向 AI Agent 开发者的**工程化副驾驶**，把零散的 Prompt 工程经验沉淀为模板库、评估器与循环工程工作流，让 Agent 从"能跑"升级到"稳定可控"。
## 设计动机：四大高频痛点
| 痛点 | 典型表现 | 本技能对策 |
|------|----------|------------|
| Prompt 幻觉与答非所问 | 输出混乱、编造事实、偏离目标 | 五段式结构化 Prompt 模板 + 幻觉检测评估器 |
| 上下文腐烂（Context Rot） | 长会话越聊越跑偏、遗忘早期约束 | 三因素诊断器（密度衰减/噪声累积/注意力漂移）+ 治理建议 |
| 工具选择不当 | 该调用不调、乱调、参数错配 | 工具选择决策矩阵（任务类型×参数复杂度×失败成本） |
| 任务拆解颗粒度失控 | 拆太粗执行不了、拆太细 token 爆炸 | DAG 拆解树 + 颗粒度评估公式 |
## 快速开始（< 60 秒）
### 场景一：生成一个结构化 System Prompt
```text
用户："帮我设计一个客服 Agent 的 system prompt，处理退款咨询"
输出结构：
1. 角色定位（你是谁、服务谁）
2. 能力边界（能做什么、不能做什么）
3. 行为规范（语气、流程、禁忌）
4. 输出格式（结构化响应 schema）
5. 异常处理（兜底策略、转人工条件）
```
### 场景二：诊断长会话的上下文腐烂
```text
用户："这个 Agent 聊到第 20 轮就开始跑偏，帮我诊断"
诊断输出：
- 信息密度衰减率：第 1-5 轮 85% → 第 16-20 轮 42%
- 噪声累积：无关工具调用结果占上下文 38%
- 注意力漂移：核心约束在第 12 轮后未被引用
- 治理建议：[具体建议列表]
```
### 场景三：拆解复杂任务为 DAG
```text
用户："把这个'调研竞品并生成报告'的任务拆解"
输出：DAG 拆解树（节点+依赖边），每节点标注：
- 预估 token 消耗
- 所需工具
- 失败重试策略
- 颗粒度评分（0-1，建议 0.6-0.8）
```
## 核心能力详解
### 1. System Prompt 五段式结构化生成
摒弃"一段话写到底"的写法，强制五段式结构：
```text
[1. 角色定位]
你是{角色}，服务{目标用户}，核心目标是{目标}。
[2. 能力边界]
能做：{能力列表}
不能做：{禁忌列表}
不确定时：{兜底行为}
[3. 行为规范]
语气：{语气描述}
流程：{标准处理流程}
禁忌：{绝对禁止的行为}
[4. 输出格式]
响应 schema（JSON / Markdown 模板）：
{schema 定义}
[5. 异常处理]
输入异常：{处理方式}
工具失败：{重试/降级策略}
转人工条件：{触发条件}
```
**质量检查清单**：
- [ ] 角色定位是否含明确的目标用户与目标
- [ ] 能力边界是否区分"能做/不能做/不确定"
- [ ] 行为规范是否可执行（非模糊描述）
- [ ] 输出格式是否有 schema 定义
- [ ] 异常处理是否含转人工条件
### 2. 上下文腐烂诊断器
长会话中上下文质量会衰减，本技能量化三大因素：
| 因素 | 定义 | 检测方法 | 阈值 |
|------|------|----------|------|
| 信息密度衰减 | 每轮新增有效信息占比下降 | 统计每轮非重复信息 token 数 | < 30% 触发治理 |
| 噪声累积 | 无关工具结果/客套话占用上下文 | 标记噪声 token，计算占比 | > 40% 触发清理 |
| 注意力漂移 | 核心约束在后续轮次未被引用 | 检查约束关键词出现频率 | 连续 5 轮未引用触发提醒 |
**治理建议库**：
1. **摘要压缩**：把第 1-N 轮压缩为摘要，保留关键决策与约束
2. **约束重申**：每 5 轮自动重申核心约束
3. **噪声清理**：移除已完成的工具调用结果，仅保留结论
4. **分段会话**：超过 30 轮建议开新会话，传递关键上下文摘要
5. **工具结果归档**：长工具输出移到外部文件，上下文只保留引用
### 3. 工具选择决策矩阵
基于三个维度推荐工具调用策略：
```text
维度一：任务类型
- 信息检索类 → 优先搜索引擎/知识库工具
- 计算推理类 → 优先代码执行/计算器工具
- 创作生成类 → 优先 LLM 直出，少用工具
- 操作执行类 → 优先 API 调用工具，需确认
维度二：参数复杂度
- 低（1-2 个简单参数） → 可自动调用
- 中（3-5 个参数或含枚举） → 调用前确认参数
- 高（嵌套对象/需上下文推导） → 必须人工确认
维度三：失败成本
- 低（可撤销/只读） → 自动重试 3 次
- 中（有副作用但可恢复） → 确认后执行，失败降级
- 高（不可逆/涉及资金数据） → 强制人工确认，不自动重试
```
**决策结果示例**：
| 任务类型 | 参数复杂度 | 失败成本 | 推荐策略 |
|----------|------------|----------|----------|
| 信息检索 | 低 | 低 | 自动调用，缓存结果 |
| 信息检索 | 高 | 低 | 自动调用，但先调元数据工具补全参数 |
| 操作执行 | 中 | 高 | 人工确认参数，执行后校验 |
| 操作执行 | 高 | 高 | 强制人工双确认，沙箱预演 |
### 4. 任务拆解 DAG
将复杂任务拆为有向无环图（DAG），每个节点可独立执行：
```text
任务："调研竞品并生成报告"
DAG：
[收集竞品列表] ──┬──> [抓取各竞品功能]
├──> [抓取各竞品定价]
└──> [抓取各竞品评价]
│
v
[聚合分析] ──> [生成报告] ──> [质量校验]
每节点属性：
- node_id: 唯一标识
- description: 节点任务描述
- depends_on: 前置节点列表
- estimated_tokens: 预估 token 消耗
- required_tools: 所需工具列表
- retry_policy: 重试策略（次数/退避/降级）
- granularity_score: 颗粒度评分（0-1）
```
**颗粒度评估公式**：
```
granularity = f(预估耗时, token消耗, 依赖复杂度, 失败概率)
建议范围：0.6-0.8
< 0.4：拆太细，token 浪费在编排开销
> 0.9：拆太粗，单节点失败影响大，难重试
```
### 5. Agent Loop 模式选择
| 模式 | 适用场景 | 优势 | 劣势 |
|------|----------|------|------|
| ReAct（推理-行动） | 需要多步工具调用的任务 | 灵活、可解释 | 易陷入循环 |
| CoT（思维链） | 推理密集型任务 | 推理深度好 | 工具调用弱 |
| Plan-Execute（规划-执行） | 复杂多步任务 | 全局视野、可回溯 | 规划阶段 token 消耗大 |
| Reflection（反思） | 高质量要求任务 | 自我纠错 | 增加延迟与成本 |
**选择决策树**：
```text
是否需要调用工具？
├─ 否 → CoT
└─ 是 → 任务步数是否 > 5？
├─ 否 → ReAct
└─ 是 → 是否需要全局规划？
├─ 是 → Plan-Execute
└─ 否 → ReAct + Reflection（每 3 步反思一次）
```
### 6. Prompt 质量评估器
对生成的 Prompt 进行多维评估：
| 评估维度 | 评分方法 | 及格线 |
|----------|----------|--------|
| 明确性 | 目标是否可量化 | 目标含可测量指标 |
| 完整性 | 五段式是否齐全 | 5 段全覆盖 |
| 可执行性 | 行为规范是否具体 | 无模糊词（"尽量""适当"） |
| 鲁棒性 | 异常处理是否完备 | 覆盖输入/工具/转人工 |
| 幻觉风险 | 是否有事实性约束 | 含"不确定时承认"约束 |
**幻觉检测规则**：
1. 检查是否含"不确定时承认不知道"约束
2. 检查是否禁止编造引用/数据
3. 检查是否要求标注信息来源
4. 检查是否对事实性输出加校验步骤
5. 检查是否限制输出范围（避免过度发挥）
**回归测试用例生成**：
- 针对 Prompt 生成 5-10 个测试输入（含正常/边界/恶意）
- 每个测试输入预期输出 schema
- 运行后对比实际输出，统计通过率
## Token 预算管理
按任务复杂度分配上下文配额，避免单任务吃满窗口：
| 任务复杂度 | System Prompt | 历史上下文 | 工具结果 | 输出预留 |
|------------|---------------|------------|----------|----------|
| 简单（单轮问答） | 500 | 1000 | 1000 | 1500 |
| 中等（3-5 轮） | 1000 | 3000 | 3000 | 2000 |
| 复杂（多步任务） | 1500 | 5000 | 5000 | 3000 |
**超配处理**：
1. 优先压缩工具结果（保留结论，移除原始数据）
2. 其次压缩历史上下文（摘要化早期轮次）
3. 最后压缩 System Prompt（合并相似约束）
## 循环工程（Loops Engineering）
面向 Agent 工作流的系统化设计方法：
```text
循环工程五阶段：
1. 任务发现
- 监听用户输入/外部事件
- 识别可执行任务
- 评估任务优先级
2. 任务分配
- 匹配合适的 Agent/工具
- 分配 token 预算
- 设定 SLA（延迟/质量）
3. 执行
- 调用 LLM/工具
- 流式输出进度
- 异常捕获与降级
4. 质量检查
- 输出 schema 校验
- 幻觉检测
- 业务规则校验
- 人工评审（高风险任务）
5. 迭代
- 不合格则回到分配阶段重试
- 合格则归档与学习
- 更新 Prompt 模板库
```
**循环工程 vs 传统 Prompt 工程区别**：
| 维度 | 传统 Prompt 工程 | 循环工程 |
|------|------------------|----------|
| 关注点 | 单次输入输出 | 完整执行系统 |
| 质量保障 | 人工抽检 | 自动质检+回归测试 |
| 失败处理 | 人工介入 | 自动重试+降级+转人工 |
| 改进方式 | 经验调整 | 数据驱动迭代 |
## 输出解析与 Schema 校验
强制 Agent 输出结构化数据时，配套校验：
```python
# 输出 schema 示例
output_schema = {
"type": "object",
"required": ["decision", "reason", "confidence"],
"properties": {
"decision": {"type": "string", "enum": ["approve", "reject", "escalate"]},
"reason": {"type": "string", "minLength": 10, "maxLength": 500},
"confidence": {"type": "number", "minimum": 0, "maximum": 1}
}
}
# 校验失败处理
def on_validation_fail(raw_output, errors):
if retry_count < 2:
return retry_with_error_feedback(raw_output, errors)
else:
return fallback_to_manual_review(raw_output)
```
**解析策略**：
1. 优先用 JSON 模式（如 OpenAI `response_format`）
2. 备选：Markdown 代码块提取 + JSON.parse
3. 兜底：正则提取关键字段
4. 失败：重试 2 次（附带错误反馈），仍失败则转人工
## 典型工作流（3 个真实场景）
### 场景一：构建退款客服 Agent
```text
1. 五段式 Prompt 生成（角色=退款客服，目标=高效处理退款咨询）
2. 工具选择决策矩阵（任务=操作执行，参数=中，失败成本=高→人工确认）
3. Agent Loop 选择（步数<5→ReAct）
4. 质量评估器检查（幻觉风险、完整性）
5. 生成回归测试用例（正常退款/超期/欺诈/转人工）
```
### 场景二：治理长会话上下文腐烂
```text
1. 诊断三因素（密度衰减/噪声/注意力漂移）
2. 输出治理建议：
- 第 1-10 轮压缩为摘要
- 移除已完成工具的原始结果
- 重申核心约束
3. 应用治理后重新评估
4. 建议每 15 轮主动触发治理
```
### 场景三：多 Agent 协作任务编排
```text
1. 任务拆解为 DAG（调研→分析→写作→校验）
2. 每节点分配 Agent 与 token 预算
3. 定义节点间数据传递 schema
4. 设置全局质量门禁（每节点输出校验）
5. 失败降级策略（单节点失败→重试→换 Agent→转人工）
```
## FAQ
**Q1：五段式 Prompt 会不会太长，浪费 token？**
A：五段式结构化反而更省 token。模糊 Prompt 会导致多轮澄清，结构化 Prompt 一次到位。实测平均节省 30% 总 token。
**Q2：上下文腐烂诊断需要多少轮会话才有意义？**
A：建议至少 10 轮。少于 10 轮时密度衰减不显著，诊断结果参考价值有限。
**Q3：任务拆解颗粒度评分怎么用？**
A：评分 0.6-0.8 为最佳区间。< 0.4 说明拆太细，编排开销大于执行开销；> 0.9 说明拆太粗，单节点失败影响大。可调整拆解粒度后重新评分。
**Q4：循环工程和传统 Prompt 工程能共存吗？**
A：可以。循环工程是 Prompt 工程的系统化升级，单节点内部仍用 Prompt 工程方法，循环工程负责节点间编排与质量保障。
**Q5：幻觉检测能 100% 防止幻觉吗？**
A：不能。幻觉检测只能降低风险，通过约束+校验+来源标注把幻觉概率从约 15% 降到 3% 以下。完全消除需要结合 RAG 与事实校验工具。
## 故障排查
| 症状 | 可能原因 | 解决方案 |
|------|----------|----------|
| Agent 反复调用同一工具 | 工具结果未被正确解析 | 检查输出 schema，增加结果校验 |
| 长会话输出质量骤降 | 上下文腐烂 | 运行诊断器，应用治理建议 |
| 任务拆解后无法执行 | 依赖关系错误 | 检查 DAG 是否有环，重新排序 |
| Prompt 评估分数低 | 缺少异常处理段 | 补充第 5 段异常处理 |
| 工具调用参数错误 | 参数复杂度高未确认 | 启用调用前确认机制 |
## 依赖说明
### 运行环境
- **Agent 平台**：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
- **操作系统**：Windows / macOS / Linux
### 第三方依赖
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由 Agent 内置 LLM 提供 |
| JSON Schema 校验库（可选） | 代码库 | 可选 | 如 ajv（JS）/ jsonschema（Python），用于输出校验 |
### API Key 配置
- 本技能基于 Markdown 指令，无需额外 API Key（LLM 由 Agent 平台提供）
### 可用性分类
- **分类**：MD+EXEC（纯 Markdown 指令，部分高级功能需 exec 执行校验脚本）
- **说明**：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 进行 Prompt 工程与任务编排
don't have the plugin yet? install it then click "run inline in claude" again.