代理副驾驶（Agent Copilot Pro）

面向 AI Agent 开发者的工程化副驾驶，把零散的 Prompt 工程经验沉淀为模板库、评估器与循环工程工作流，让 Agent 从"能跑"升级到"稳定可控"。

设计动机：四大高频痛点

快速开始（< 60 秒）

场景一：生成一个结构化 System Prompt

用户："帮我设计一个客服 Agent 的 system prompt，处理退款咨询"

输出结构：
1. 角色定位（你是谁、服务谁）
2. 能力边界（能做什么、不能做什么）
3. 行为规范（语气、流程、禁忌）
4. 输出格式（结构化响应 schema）
5. 异常处理（兜底策略、转人工条件）

场景二：诊断长会话的上下文腐烂

用户："这个 Agent 聊到第 20 轮就开始跑偏，帮我诊断"

诊断输出：
- 信息密度衰减率：第 1-5 轮 85% → 第 16-20 轮 42%
- 噪声累积：无关工具调用结果占上下文 38%
- 注意力漂移：核心约束在第 12 轮后未被引用
- 治理建议：[具体建议列表]

场景三：拆解复杂任务为 DAG

用户："把这个'调研竞品并生成报告'的任务拆解"

输出：DAG 拆解树（节点+依赖边），每节点标注：
- 预估 token 消耗
- 所需工具
- 失败重试策略
- 颗粒度评分（0-1，建议 0.6-0.8）

核心能力详解

1. System Prompt 五段式结构化生成

摒弃"一段话写到底"的写法，强制五段式结构：

[1. 角色定位]
你是{角色}，服务{目标用户}，核心目标是{目标}。

[2. 能力边界]
能做：{能力列表}
不能做：{禁忌列表}
不确定时：{兜底行为}

[3. 行为规范]
语气：{语气描述}
流程：{标准处理流程}
禁忌：{绝对禁止的行为}

[4. 输出格式]
响应 schema（JSON / Markdown 模板）：
{schema 定义}

[5. 异常处理]
输入异常：{处理方式}
工具失败：{重试/降级策略}
转人工条件：{触发条件}

质量检查清单：

• 角色定位是否含明确的目标用户与目标
• 能力边界是否区分"能做/不能做/不确定"
• 行为规范是否可执行（非模糊描述）
• 输出格式是否有 schema 定义
• 异常处理是否含转人工条件

2. 上下文腐烂诊断器

长会话中上下文质量会衰减，本技能量化三大因素：

治理建议库：

1. 摘要压缩：把第 1-N 轮压缩为摘要，保留关键决策与约束
2. 约束重申：每 5 轮自动重申核心约束
3. 噪声清理：移除已完成的工具调用结果，仅保留结论
4. 分段会话：超过 30 轮建议开新会话，传递关键上下文摘要
5. 工具结果归档：长工具输出移到外部文件，上下文只保留引用

3. 工具选择决策矩阵

基于三个维度推荐工具调用策略：

维度一：任务类型
  - 信息检索类 → 优先搜索引擎/知识库工具
  - 计算推理类 → 优先代码执行/计算器工具
  - 创作生成类 → 优先 LLM 直出，少用工具
  - 操作执行类 → 优先 API 调用工具，需确认

维度二：参数复杂度
  - 低（1-2 个简单参数） → 可自动调用
  - 中（3-5 个参数或含枚举） → 调用前确认参数
  - 高（嵌套对象/需上下文推导） → 必须人工确认

维度三：失败成本
  - 低（可撤销/只读） → 自动重试 3 次
  - 中（有副作用但可恢复） → 确认后执行，失败降级
  - 高（不可逆/涉及资金数据） → 强制人工确认，不自动重试

决策结果示例：

4. 任务拆解 DAG

将复杂任务拆为有向无环图（DAG），每个节点可独立执行：

任务："调研竞品并生成报告"

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 模式选择

选择决策树：

是否需要调用工具？
├─ 否 → CoT
└─ 是 → 任务步数是否 > 5？
        ├─ 否 → ReAct
        └─ 是 → 是否需要全局规划？
                ├─ 是 → Plan-Execute
                └─ 否 → ReAct + Reflection（每 3 步反思一次）

6. Prompt 质量评估器

对生成的 Prompt 进行多维评估：

幻觉检测规则：

1. 检查是否含"不确定时承认不知道"约束
2. 检查是否禁止编造引用/数据
3. 检查是否要求标注信息来源
4. 检查是否对事实性输出加校验步骤
5. 检查是否限制输出范围（避免过度发挥）

回归测试用例生成：

• 针对 Prompt 生成 5-10 个测试输入（含正常/边界/恶意）
• 每个测试输入预期输出 schema
• 运行后对比实际输出，统计通过率

Token 预算管理

按任务复杂度分配上下文配额，避免单任务吃满窗口：

超配处理：

1. 优先压缩工具结果（保留结论，移除原始数据）
2. 其次压缩历史上下文（摘要化早期轮次）
3. 最后压缩 System Prompt（合并相似约束）

循环工程（Loops Engineering）

面向 Agent 工作流的系统化设计方法：

循环工程五阶段：

1. 任务发现
   - 监听用户输入/外部事件
   - 识别可执行任务
   - 评估任务优先级

2. 任务分配
   - 匹配合适的 Agent/工具
   - 分配 token 预算
   - 设定 SLA（延迟/质量）

3. 执行
   - 调用 LLM/工具
   - 流式输出进度
   - 异常捕获与降级

4. 质量检查
   - 输出 schema 校验
   - 幻觉检测
   - 业务规则校验
   - 人工评审（高风险任务）

5. 迭代
   - 不合格则回到分配阶段重试
   - 合格则归档与学习
   - 更新 Prompt 模板库

循环工程 vs 传统 Prompt 工程区别：

输出解析与 Schema 校验

强制 Agent 输出结构化数据时，配套校验：

# 输出 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

1. 五段式 Prompt 生成（角色=退款客服，目标=高效处理退款咨询）
2. 工具选择决策矩阵（任务=操作执行，参数=中，失败成本=高→人工确认）
3. Agent Loop 选择（步数<5→ReAct）
4. 质量评估器检查（幻觉风险、完整性）
5. 生成回归测试用例（正常退款/超期/欺诈/转人工）

场景二：治理长会话上下文腐烂

1. 诊断三因素（密度衰减/噪声/注意力漂移）
2. 输出治理建议：
   - 第 1-10 轮压缩为摘要
   - 移除已完成工具的原始结果
   - 重申核心约束
3. 应用治理后重新评估
4. 建议每 15 轮主动触发治理

场景三：多 Agent 协作任务编排

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 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux

第三方依赖

API Key 配置

• 本技能基于 Markdown 指令，无需额外 API Key（LLM 由 Agent 平台提供）

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分高级功能需 exec 执行校验脚本）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 进行 Prompt 工程与任务编排