# AI Agent 规格模板（Agent Spec Template）

> 用途：做一个新的专业 AI Agent 时，把这份模板复制一份，逐格填空。
> 通用 AI Agent（Codex / Claude Code / Cursor 等）读懂你的自然语言后，
> 本质上就是照着这个模子，把你那句大白话"编译"成下面这几份明确的规格。
>
> 框架参考：Lilian Weng, *LLM Powered Autonomous Agents* (2023-06-23)
> https://lilianweng.github.io/posts/2023-06-23-agent/
> —— LLM 作为大脑，外加三大组件：Planning（规划）/ Memory（记忆）/ Tool use（工具）。
>
> 配套文章：《AI Agent 孵化器：用一个父 Agent，批量造出贴身服务的子 Agent》 https://www.fanyamin.com

---

## 0. 一句话需求（Raw Intent）

> 先用大白话写下你想让它干的那件事，别急着规整。翻译机就是从这句话往下推的。

示例：
> 帮我做一个日程安排专家：我用大白话告诉它今天要干嘛，它去查天气、看我的日历、
> 翻我的待办清单，然后排出一张日程表，再帮我把提醒设好——重要的用声音，
> 一般的发消息，正式的发邮件。

你的：
```
（在这里写）
```

---

## 1. 角色与边界（Role & Scope）

| 项 | 内容 |
|---|---|
| 名称 | 例：日程安排专家 |
| 一句话职责 | 例：把自然语言需求排成日程表并设置分级提醒 |
| 服务对象 | 例：我自己 / 团队 / 某类用户 |
| **明确不做**（边界） | 例：不写代码、不闲聊、不越权修改待办内容 |

> 提示：边界比职责更重要。范围一宽，Agent 就容易飘。

---

## 2. 大脑：模型与规划（Brain & Planning）

- **底座模型**：例：GPT-4 类 / Claude / 本地开源模型
- **工作模式**：例：ReAct（Thought → Action → Observation 循环）
- **任务分解**：复杂请求是否需要先拆成子目标？（对应翁荔的 Task Decomposition）
- **自我反思**：出错时是否要回看上一步、纠正后重试？（Self-Reflection）
- **停机条件**：什么时候算"办完了"？最多循环几轮，防止空转？

---

## 3. 记忆（Memory）

| 类型 | 存什么 | 怎么存 |
|---|---|---|
| 短期记忆 | 本次对话/本轮任务的上下文 | 放在 prompt 上下文里 |
| 长期记忆 | 用户偏好、历史决策、常用资料 | 例：向量库 + 检索（RAG） |

> 小 Agent 可以先只要短期记忆；要"越用越懂你"再上长期记忆。

---

## 4. 工具集（Tools）

> 从需求里的"动词"倒推该配哪些工具。三样通用底座 + 若干专属数据源。

| 工具 | 作用 | 触发场景 | 备注/接口 |
|---|---|---|---|
| search（联网搜索） | 查外部实时信息 | 例：查展会开门时间 | |
| rag（知识库检索） | 从自有资料里翻答案 | 例：翻项目文档找 deadline | |
| bash（执行命令） | 真正动手操作系统 | 例：写文件、设提醒、发邮件 | ⚠️ 高危，需白名单/确认 |
| （专属工具1） | 例：weather 天气 | 例：判断能否安排户外 | |
| （专属工具2） | 例：calendar 日历 | 例：查已占用时段 | |
| （专属工具3） | 例：todo 待办 | 例：取出待排事项 | |

分工口诀：**search 管"外面的世界"，rag 管"你自己的资料"，bash 管"真去把事办了"。**

---

## 5. 决策规矩（Decision Rules）—— 最需要你亲自填

> 这是"专业"二字的含金量，也是自动生成里最容易翻车、最不该全自动的一格。
> AI 会替你补一版默认规矩，但那个"合理"未必是你心里那版。逐条审、逐条改。

- 例：户外活动遇到下雨/高温 → 提示改期，不许硬排
- 例：两件事时间冲突 → 按紧急程度取舍，并说明理由
- 例：不安排深夜打扰家人的提醒
- 例：拿不准的时间 → 先查证，不许瞎编
- （你的规矩……）

---

## 6. 提示词（Prompts）

### System Prompt（岗位说明书，长期不变）
```text
你是一个"{{名称}}"。你的职责是：{{一句话职责}}。

可用工具：{{工具列表}}

工作方式（ReAct）：
- 每一步先输出 Thought（思考），再输出 Action（要调用的工具和参数）
- 我会把工具结果作为 Observation 返回给你
- 信息够了就输出 Final Answer：{{最终交付物}}

规矩（边界）：
- {{规矩1}}
- {{规矩2}}
- {{规矩3}}
```

### User Prompt（每次不同的工单）
```text
{{用户当场说的那句大白话}}
例：帮我把明天安排一下，上午想去拍个外景，下午 3 点和客户有个会。
```

---

## 7. 验收标准（Acceptance / Eval）

> 给它几条能对答案的场景，让它有靶子可打——也是你判断"生成得对不对"的依据。

| 输入场景 | 期望行为（正确答案） |
|---|---|
| 例：明天有雨 + 上午安排了户外拍摄 | 提示改期，不硬排户外 |
| 例：两个会议都排在 15:00 | 按紧急度取舍，并说明理由 |
| 例：某待办没有明确时间 | 先查证/追问，不瞎编时间 |
| （你的场景……） | （期望……） |

---

## 使用清单（照着走一遍）

1. [ ] 写下第 0 节"一句话需求"
2. [ ] 让通用 Agent 照本模板生成 1–6 节的草稿
3. [ ] **重点复核第 1 节边界、第 5 节规矩**——这两格 AI 最容易替你想歪
4. [ ] 补齐第 7 节验收场景，让它能自测
5. [ ] 让通用 Agent 照规格搭出可运行骨架，用第 7 节的场景验证
6. [ ] 跑不通就把失败场景喂回去，让它自己"打转"改到通过