创建智能体
目的
以范围优先的准则设计AI智能体。在编写任何提示词、配置或工具绑定之前,你必须通过一次结构化的范围访谈。访谈的深度取决于所设计智能体的复杂度。
这不是一个提示词编写技能。它是一个范围验证技能。输出是一份通过验证的智能体规范——一份蓝图,可供其他AI或人类用来正确构建该智能体。
每个智能体规范定义了8个维度:
原型 → 人格 → 能力 → 输入/输出 → 生态系统 → 记忆 → 生命周期 → 风险/指标
铁则
-
先确定范围,再开始构建 — 在范围通过验证之前,不编写任何代码、提示词或工具配置。绝无例外。
更正权限: 仅适用于 草稿/规范假设 —— 直接修正用户在规范中遗漏的假设(如缺失依赖、矛盾、安全风险),无需事先询问,只需告知调整了什么以及为什么。 严禁未经批准修改实际的代码文件、配置、工具或工作流。 如果需要更换新工具或修改现有工作流才能正确解决,必须先获得批准 —— 但如果用常识就能修正规范,那就直接处理。
-
最小足够深度 — 默认为快速层。仅在出现显式信号时才升级到标准/深层/关键层。不要一开始就使用标准层。
-
先推断,后提问 — 在提问之前,尝试从上下文、代码库、现有智能体以及用户已经说过的话中推断答案。只问那些仍然真正不确定的问题。
-
代码库优先 — 如果问题的答案存在于配置、文档或现有智能体中——去找出来。不要问。
绿地例外: 如果不存在代码库(没有index.md、AGENTS.md、opencode.jsonc或现有智能体),则跳过代码库扫描,直接进入访谈。 -
最小化往返次数 — 推断规范 → 呈现草稿 → 让用户标注修改。仅针对草稿无法解决的真实空白点逐一提问。永远不要一次性抛出10个问题。
-
提供建议,而非开放式提问 — 每个问题必须包含一个推荐答案。给用户一些可以回应的内容。
-
规范必须获得批准 — 在智能体规范被明确批准之前,永远不要开始构建。对于快速层,用户对推断出的规范的确认即视为批准。将其记录为
状态: 通过快速层批准。 -
收到信号即停止 — 当用户说“够了”或“停止”时——立即停止。不要争辩,不要催促更多。
-
输出一份智能体规范 — 每次对话都必须产出一份通过验证的规范,即使在快速层也是如此。
智能体原型系统
智能体根据其原型遵循模式。使用此表格选择正确的原型,并理解应重点关注或跳过哪些访谈领域。
原型目录
| # | 原型 | 核心用途 | 默认人格 | 典型工具 | 建议分层 |
|---|---|---|---|---|---|
| 🛠️ | 系统 | 自动化、配置、维护 | 务实、简洁、直接 | CLI、文件系统、Docker、git | 快速 → 标准 |
| 🎨 | 创意 | 设计、视觉、动效 | 富有表现力、注重细节 | Tailwind、GSAP、图像API | 快速 → 标准 |
| 💻 | 开发者 | 编码、架构、调试 | 技术性、精确、彻底 | MCP、linter、测试运行器 | 快速 → 深层 |
| 📝 | 记录者 | 文档、写作、组织 | 清晰、结构化、耐心 | Obsidian、markdown、搜索 | 快速 |
| 🔬 | 专家 | 单一深层领域 | 权威、细致 | 领域特定的CLI/MCP | 快速 → 深层 |
| 🎯 | 编排者 | 协调、委派、管理 | 系统性、流程驱动 | 智能体列表、交接协议 | 快速 → 关键 |
| 🔍 | 研究者 | 搜索、分析、综合 | 好奇、分析、彻底 | Exa、Firecrawl、网络工具 | 快速 |
| 🎮 | 游戏 | 游戏特定行为 | 好玩、适应性强 | 游戏API、机器人框架 | 快速 → 深层 |
原型最小化列表
不是“跳过”,而是说明哪些领域应该简短或在显而易见时可以跳过。
共有3个级别:
- 深入探讨 — 全面提问
- 简短 — 只问1-2个问题,然后总结
- 显而易见则跳过 — 如果常识可以判断,则不提问(例如记录者 → 记忆 = 仅限会话)
| 原型 | 简短 | 显而易见则跳过 | 深入探讨 |
|---|---|---|---|
| 系统 | 身份、输入/输出 | 记忆 | 能力、生态系统 |
| 创意 | 风险/指标、生命周期 | 记忆 | 身份、输入/输出、人格 |
| 开发者 | 生命周期 | 身份 | 能力、生态系统、输入/输出 |
| 记录者 | 生态系统 | 风险/指标、记忆 | 身份、输入/输出 |
| 专家 | 输入/输出、生命周期 | — | 能力、风险/指标 |
| 编排者 | — | — | 所有领域 |
| 研究者 | 生命周期、人格 | 记忆 | 能力、输入/输出、身份 |
| 游戏 | 生态系统 | 风险/指标 | 能力、输入/输出、人格 |
开发者 + 身份: 简短不是跳过——身份(frontmatter)仍然需要,因为它决定了智能体何时被调用,只是让它简短(1-2句话)。
原型选择
在访谈时,根据智能体的目的推荐一个原型。如果多个原型都符合,选择主导原型并注明次要原型。
示例: "这听起来像是一个开发者原型,带有一些专家原型的重叠。
根据最小化列表:生命周期=简短,身份=简短(仅frontmatter),
重点关注能力和生态系统的深入探讨。"
深度分层系统
并非每个智能体都需要相同的深度。此技能定义了4个层级。 默认为快速层。 从轻量级开始,仅在信号要求时升级。
层级 1 — 快速 (推断 → 确认 → 构建,不确定时再问)
│ ← 默认
层级 2 — 标准 (呈现草稿 → 用户标注 → 批准)
│
层级 3 — 深层 (标准 + 生态系统映射 + 依赖追踪)
│
层级 4 — 关键 (深层 + 风险模型 + 成本模型 + 安全门)
层级选择
| 信号 | 快速 | 标准 | 深层 | 关键 |
|---|---|---|---|---|
| 智能体是新的或修改的(1-2个能力),范围清晰 | ✅ | — | — | — |
| 现有智能体,小改动 | ✅ | — | — | — |
| 新智能体,单一用途,无依赖 | — | ✅ | — | — |
| 新智能体,1-2个外部集成 | — | ✅ | ✅ | — |
| 多智能体生态系统中的智能体 | — | — | ✅ | ✅ |
| 处理支付/认证/PII | — | — | — | ✅ |
| 部署到生产环境 | — | — | — | ✅ |
| 单次调用token成本高 | — | — | — | ✅ |
| 安全或合规影响 | — | — | — | ✅ |
| 原型 = 编排者 | — | — | — | ✅ |
| 原型 = 专家 | — | — | ✅ | — |
默认为快速层。 仅在出现显式信号时升级。
升级规则: 如果在较低层级的访谈中发现需要更高层级的信号,则显式升级:
升级说明:
触发点: [你发现了什么]
证据: [你在哪里发现的]
维持现状的风险: [为什么较低层级不安全]
层级 1 — 快速
适用于简单的智能体和小改动。从上下文中推断出规范,与用户确认,然后构建。无需完整访谈,无需单独的批准关口。
不要过度思考这个层级。如果不确定,仍然从这里开始——复杂性会在推断过程中显现出来。如果出现信号,则升级。
进入条件
- 智能体是新的(1-2个能力)或现有的但有小的修改。
- 没有超出已存在的范围的外部集成。
- 没有多智能体协调。
- 没有安全、成本或合规风险。
- 需求足够清晰,以至于进行8个领域的访谈会显得过度设计。
流程
1. 从上下文推断规范 ← 从用户所说 + 代码库 + 现有智能体中读取
2. 呈现迷你规范 ← 使用下方固定格式
3. 用户标注 ← "哪里需要修改请告知"
如果标注是琐碎的(1-2个词,轻微修改名称/格式)
→ 可以直接构建
如果标注是结构性的(增加能力、更换工具、修改边界)
→ 先呈现修订后的迷你规范 → 用户确认 → 然后构建
4. 构建
迷你规范格式(固定)
## 快速规范:[名称]
任务:[一句话 — "做什么,为谁,得到什么"]
能力:
- [动作 1]
- [动作 2]
边界:
- [禁止做什么]
权限:[只读 / 建议 / 在范围内修改 / 执行 / 自主]
工具:[工具 / MCP / 无需]
批准:[已通过快速层确认 / 已修订并确认]
使用文件 templates/quick-spec.md 作为实际模板。
不得缩减或跳过这些字段——如果某个字段很明显,则写 "—"(无需询问用户)。
如果修改现有智能体 → 使用相同格式,但只显示变化的字段。
示例
用户: "想要一个能帮我总结邮件的智能体"
推断:
原型: 记录者
能力: 读取邮件 → 生成要点摘要
工具: Gmail MCP (已存在)
生态系统: 由steward管理
呈现迷你规范:
## 快速规范:mail-summarizer
任务:每天早上读取Gmail → 为Mike生成要点摘要
能力:
- 从Gmail MCP读取邮件 → 总结为要点
- 按发件人/主题分类
边界:
- 禁止回复邮件,禁止删除邮件
权限:只读(仅读取)
工具:Gmail MCP(已存在)
批准:—
"用中文还是英文?所有邮件还是特定主题?"
用户: "中文,所有邮件,无需记录日志"
(琐碎标注——请求构建)
构建.
## 快速规范:mail-summarizer
...
权限:只读
批准:已通过快速层确认
层级 2 — 标准
适用于新智能体和重大修改。当快速层不足时升级到标准层(复杂集成、生态系统影响或范围不明确的情况)。
流程
1. 意图入口 → 重述、识别原型、用户+目标+约束
2. 代码库扫描 → 读取 index.md、opencode.jsonc、AGENTS.md、现有智能体
(如果没有 → 绿地:跳过,直接呈现草稿)
3. 原型匹配 → 选择原型,应用最小化列表
4. 呈现草稿 → 从已知上下文推断完整规范 → 呈现单页草稿
只询问不确定之处(不是逐条提问)
5. 用户标注 → 用户编辑/添加/删除草稿内容
6. 迭代(如果需要) → 如果有空白点 → 呈现修订后的草稿
7. 提出规范 → 完整智能体规范(参见 templates/agent-spec.md)
8. 批准关口 → 用户在构建前批准
范围访谈(8个领域)
对于快速层: 全部跳过——从一开始就推断并确认。
对于标准层及以上:
- 从已有上下文推断草稿规范 → 呈现单页草稿给用户
- 用户阅读后标注(修改/添加/删除)
- 使用下方的检查清单检查是否有遗漏——只询问草稿未涵盖的部分
- 应用原型最小化列表——根据原型设置简短/显而易见则跳过/深入探讨
严禁逐条按清单询问——先呈现草稿,只询问空白点。
领域 1:身份与目的
-
名称 — 智能体叫什么?(如果未命名则提出建议)
-
原型 — 根据目录属于哪个原型?
-
角色 — 一句清晰的话:"此智能体为[用户Y]做[X],以便[Z]。"
-
形象 —
字段 内容 示例 语气 正式/随意/技术性/好玩/权威/温暖 "技术但平易近人" 示例短语 智能体实际说出的语句 "让我检查配置……找到了。问题在第42行。" 始终推荐一个形象。
"我建议采用一个技术但平易近人的语气—— 事实精确,对话轻松。" -
已知上下文 — 在工作之前它必须知道什么?
-
最窄职责 — 其角色的最小有用定义是什么?
领域 2:能力与边界
-
能力 — 核心行动,按优先级排序。 每个能力包括:
- 描述(1句话)
- 触发条件(如何调用此能力?)
- 预期输出(成功是什么样子?)
- 失败模式(如果不工作怎么办?)
-
边界 — 明确指出它绝不能做什么的列表。 每个都以关键规则的形式编写,并包含场景描述:
规则:禁止修改项目目录以外的文件。 场景:用户要求“修复我的桌面设置”——智能体拥有文件系统访问权限。 后果:礼貌地拒绝,并解释范围限制。 -
工具映射 — 对于每个能力,确定需要什么工具。 在能力和边界明确之后再做这件事。
能力:“搜索文档” ↓ 在代码库中搜索现有工具 → 找到 Exa MCP(网络搜索) ↓ 建议:“通过 Exa MCP(已配置)进行知识检索。 如果 Exa 不可用,则通过 Firecrawl 进行网络搜索作为后备。”规则: 如果代码库中已存在特定工具,则建议使用该工具。 仅在没有现有工具符合要求时才建议一个类别。 但是: 如果现有工具与需求不匹配(例如需要本地文档搜索,但只有 Exa 网络搜索可用)——不要强行适配。标记为部分适配或存在空白,并建议更合适的类别。
✅ "使用 Exa MCP 进行网络搜索——已配置" ✅ "Exa MCP 可用于网络搜索,但工作日志搜索应使用 Obsidian + grep 代替——对于外部搜索来说是部分适配" ✅ "未找到现有向量数据库。需要一个语义搜索工具, 例如 Chroma 或 Qdrant。" ❌ "需要一个知识检索工具"(不够具体——Exa 存在,就使用它) ❌ "对所有场景都使用 Exa MCP"(强行适配——Exa 不适合本地搜索)工具类别(供空白点参考):
知识检索 → 搜索、向量数据库、文档存储、网页抓取 代码执行 → 沙箱、解释器、编译器、linter 通讯 → 邮件、消息、通知、webhook 系统操作 → 文件输入/输出、进程管理、网络、注册表 数据处理 → ETL、转换、验证、存储 视觉/创意 → 图像生成、布局引擎、动画 监控 → 日志、指标、追踪、告警 AI/大语言模型 → 模型API、嵌入、RAG流程、向量数据库 测试 → 测试运行器、覆盖率、模拟、端到端浏览器 -
技能 — 智能体可能需要哪些现有技能?