agentDevCoder

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