SKILL: 智能体应用开发（Agent App Development）

目标：把一个“能用、可控、可扩展”的智能体应用从想法落地到工程实现，覆盖：工具调用、检索、记忆、工作流编排、评测与上线。

---

1. 适用范围与不适用范围

✅ 适用范围

• 单/多智能体应用架构设计（planner / executor / critic / router）
• 工具系统：function calling、MCP、HTTP 工具、数据库工具
• 工作流编排：LangGraph / 状态机 / plan-act-observe-replan
• 检索增强：RAG（向量库/混合检索/重排序/引用与溯源）
• 记忆：短期/长期/用户偏好、结构化存储（SQL/Key-Value/Docstore）
• 可靠性：权限约束、人类确认（HITL）、回退策略、重试与幂等
• 评测：离线回放、golden set、自动评审、成本/延迟/成功率指标
• 工程化：日志/追踪、配置化、部署（容器化/无服务器/队列）

❌ 不适用范围

• 要求绕过安全限制、窃取隐私、未授权访问（拒绝）
• “完全自动化替代决策”且不允许人工确认的高风险场景
• 无可测目标的泛泛需求（会先给默认目标与可度量指标）

---

2. 交付物（Outputs）

• 架构图（文字版组件与数据流）
• 状态定义（State Schema）与节点职责
• 工具清单（Tool Contract：name/args/return/error）
• 提示词模板（System/Developer/Node Prompts）
• 评测方案与指标表
• 最小可运行骨架（伪代码或可粘贴代码片段）

---

3. 输入格式（Inputs）

最小输入：

• 用例：用户要完成什么任务（例如“读论文 → 写综述 → 生成表格”）
• 资源：可用的数据源/工具（本地文件、API、数据库、网页）
• 约束：成本、时延、离线/在线、是否需要引用来源

推荐输入：

• 失败样例与成功样例各 3 个
• 需要的工具权限边界（读/写/删除/支付等）
• 期望的 UI/交互形态（聊天、表单、批处理、插件）

---

4. 设计原则（Agent Skill 核心）

1. 可控优先：先把边界与权限写清楚，再追求自动化
2. 可测优先：每个节点要有可度量的输入输出与成功条件
3. 最小闭环：先做能跑通的 end-to-end MVP，再逐步增强
4. 显式状态：用结构化 State 传递信息，避免“凭空记忆”
5. 工具契约：工具返回统一结构，错误可恢复（recoverable）
6. 失败即路径：为常见失败设定回退策略与用户澄清模板

---

5. 标准工作流（Workflow）

Step 0：定义目标与评测

• 目标：成功率、准确率、引用覆盖率、成本、延迟
• 评测集：golden queries（最少 20 条）+ 边界案例（最少 10 条）

Step 1：拆解为节点（Nodes）

建议 4~7 个节点，典型如下：

• Intake：收集意图/约束/上下文，形成结构化需求
• Plan：生成可执行计划（含工具调用点与停止条件）
• Act：执行工具调用（幂等、重试、限流）
• Observe：解析工具结果，写入 State
• Judge：质量审查（引用、格式、覆盖、风险）
• Respond：面向用户生成最终输出
• Repair：失败修复（缩小范围、换策略、请求澄清）

Step 2：定义 State Schema

• goal：用户目标
• constraints：成本/时延/安全
• artifacts：中间产物（摘要、表格、代码片段）
• tool_calls：历史工具调用（request/response/error）
• citations：引用与出处
• decision_log：关键决策理由（用于调试与复盘）

Step 3：工具契约（Tool Contract）

统一返回结构（示例）：

• ok: bool
• data: any
• error: {type, message, retryable, details}
• meta: {latency_ms, cost, source}

Step 4：失败处理与回退

• 工具失败：指数退避 + 降级模式（少工具/少步骤）
• 检索失败：扩大 query、改用混合检索、请求用户提供关键词
• 输出失败：缩短答案、分段输出、先给结论后给依据

---

6. 提示词与路由模板

6.1 节点提示词结构

• Role：你是谁、你的职责
• Inputs：你从 State 读什么
• Outputs：你必须写回什么字段
• Constraints：不能做什么、必须引用什么
• Rubric：通过/失败标准

6.2 路由（Router）规则

• 依据：intent、所需工具、风险等级、是否需要澄清
• 输出：下一节点 + 理由（写入 decision_log）

---

7. RAG 与记忆（推荐实现）

7.1 RAG 最小形态

• chunk → embedding → top-k → 生成（带引用）

7.2 增强形态

• 混合检索（BM25 + 向量）
• 重排序（cross-encoder / reranker）
• 引用对齐（回答段落 ↔ chunk id）

7.3 记忆分层

• 短期：对话窗口内 state
• 长期：用户偏好/项目事实（结构化表）
• 可撤销：用户可要求遗忘

---

8. 评测与可观测性（Observability）

8.1 指标

• 成功率：任务完成 / 总任务
• 工具成功率：ok / 调用
• 引用覆盖率：含引用回答 / 需要引用回答
• 幻觉率：错误事实 / 抽检
• 成本：token + 工具成本
• 延迟：p50/p95

8.2 日志与追踪

• trace_id / run_id
• node_latency、tool_latency
• state_diff（关键字段变化）
• error 分类与频次

---

9. 反例（Anti-patterns）

• 把所有逻辑塞进一个超长 prompt，没有显式 state
• 工具返回格式混乱，错误不可恢复
• 没有评测集，靠主观感觉迭代
• 没有权限边界与用户确认，高风险动作直接执行

---

10. 交互方式（How to Ask Me）

你可以这样给我需求：

A. 做一个可落地的智能体

• 目标：帮我把论文 PDF → 自动提炼相关工作 → 输出表格
• 工具：本地 PDF、向量库、网页搜索（可选）
• 约束：需要引用来源；成本尽量低
• 输出：Markdown + 可复制表格

B. 诊断智能体失败

• 失败案例：贴出用户输入、工具返回、最终输出
• 现象：引用丢失/走错路由/循环调用
• 期望：修复策略 + 节点/状态改造建议

---

11. 质量标准（Definition of Done）

• ✅ MVP 可跑通：给定 20 条测试集成功率达标
• ✅ 输出稳定：同输入多次运行差异可解释
• ✅ 可控：高风险动作默认需要确认
• ✅ 可观测：能定位“卡在哪个节点/哪个工具”
• ✅ 可扩展：新增工具/新增节点不破坏整体