diegosouzapw 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 核心）
- 可控优先：先把边界与权限写清楚，再追求自动化
- 可测优先：每个节点要有可度量的输入输出与成功条件
- 最小闭环：先做能跑通的 end-to-end MVP，再逐步增强
- 显式状态：用结构化 State 传递信息，避免“凭空记忆”
- 工具契约：工具返回统一结构，错误可恢复（recoverable）
- 失败即路径：为常见失败设定回退策略与用户澄清模板
5. 标准工作流（Workflow）
Step 0：定义目标与评测
- 目标：成功率、准确率、引用覆盖率、成本、延迟
- 评测集：golden queries（最少 20 条）+ 边界案例（最少 10 条）
Step 1：拆解为节点（Nodes）
建议 4~7 个节点，典型如下：
Intake：收集意图/约束/上下文，形成结构化需求Plan：生成可执行计划（含工具调用点与停止条件）Act：执行工具调用（幂等、重试、限流）Observe：解析工具结果，写入 StateJudge：质量审查（引用、格式、覆盖、风险）Respond：面向用户生成最终输出Repair：失败修复（缩小范围、换策略、请求澄清）
Step 2：定义 State Schema
goal：用户目标constraints：成本/时延/安全artifacts：中间产物（摘要、表格、代码片段）tool_calls：历史工具调用（request/response/error）citations：引用与出处decision_log：关键决策理由（用于调试与复盘）
Step 3：工具契约（Tool Contract）
统一返回结构（示例）：
ok: booldata: anyerror: {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 条测试集成功率达标
- ✅ 输出稳定：同输入多次运行差异可解释
- ✅ 可控：高风险动作默认需要确认
- ✅ 可观测：能定位“卡在哪个节点/哪个工具”
- ✅ 可扩展：新增工具/新增节点不破坏整体