大多数AI智能体教程从工具配置开始。连接这个MCP服务器。注册那个skill。配置这些提示词。
然后用户就会疑惑，为什么他们的”营销总监”智能体某天通过SendGrid发邮件，第二天又通过Mailgun发。或者为什么”SEO分析师”有时查询Google Analytics，有时查询Search Console，有时干脆编造数据。
这些智能体理论上有能力。他们有邮件工具。他们有分析访问权限。但他们无法可靠运行。
这是我们在为TeamDay构建14个AI Character时学到的：问题不在于工具，问题在于方法论。
抽象化陷阱
AI智能体生态系统热衷于分类法。工具 vs MCP服务器 vs skills vs 插件 vs 提示词。开发者花数小时争论：邮件应该是MCP工具还是bash脚本skill？
从业务用户的角度来看，这些区别毫无意义。
当有人要求营销总监”发送每周更新”时，他们不在乎邮件是否通过以下方式发送：
- 调用Resend API的MCP工具
- 执行bash curl命令的skill
- 使用环境变量中凭据的TypeScript脚本
- 通过sendmail的直接SMTP
他们在乎的是邮件是否被发送。正确地。每次都是。
去掉抽象化，剩下的正好是两个原语：
1. 可执行函数 — 运行并返回结果的代码（工具、MCP工具、bash命令、脚本）
2. 提示文本 — AI读取并遵循的指令（系统提示、skills、CLAUDE.md文件）
其他所有内容都是围绕这两个原语的包装和组织结构。
当你为分类法（在工具类型之间选择）而不是为可靠性（这真的有效吗？）进行优化时，抽象化陷阱就会出现。
可运行示例原则
这是AI智能体能力的真正单位：
带有凭据的可运行示例。
不是工具注册。不是MCP服务器配置。不是skill描述。
可运行示例如下所示：
# 通过Resend发送邮件
curl -X POST https://api.resend.com/emails \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": "[email protected]",
"subject": "每周更新",
"html": "<p>内容在这里</p>"
}'
# 预期响应：
# {"id": "abc-123", "status": "sent"}
# 凭据：.env中的RESEND_API_KEY
# 最后测试：2026-02-10
# 负责人：营销团队没有可运行示例，Claude会从1000个选项中随机选择。有了可运行示例，它每次都会遵循经过验证的模式。
“理论上可以发邮件”与”使用我们的凭据通过Resend可靠地发送邮件”的区别，在于一个经过测试、有文档记录的可运行示例。
配方模型
配方是我们对特定任务的经过测试、验证过的可运行示例的称呼。
我们的营销总监Character有以下配方：
- 通过Resend发送邮件（已测试，env中有凭据）
- 查询Search Console API（已测试，OAuth已配置）
- 通过Ahrefs分析关键词（已测试，env中有API密钥）
- 获取Google Analytics数据（已测试，属性ID已记录）
每个配方包括：
- 何时使用 — “用于发送交易邮件”
- 凭据参考 — “API密钥：RESEND_API_KEY（在.env中）”
- 可运行示例 — 实际有效的curl命令或代码片段
- 预期响应 — 成功是什么样子
- 最后测试 — 我们验证它实际有效的日期
配方不是抽象的工具定义。它们是具体的、经过测试的流程，我们知道它们有效，因为我们已经运行过它们。
配方是原子构建块。Character是组合体。
自底向上的Character设计
以下是真正有效的方法论：
第一步：这个Character是谁？
不是抽象能力。是具体的角色和目的。
错误：“具有营销能力的AI助手”
正确：“向利益相关者发送每周绩效报告的营销总监”
角色越清晰，设计就越容易。
第二步：这个角色实际上执行哪些任务？
不是他们理论上可以做什么。是他们周二早上实际做什么。
对于营销总监：
- 检查营销活动效果（周一上午9点）
- 查看自然流量趋势（每天）
- 向利益相关者发送每周更新（周五下午4点）
- 分析关键词排名（按需）
注意这些是任务，不是工具。“检查营销活动效果”是需要完成的工作。是使用Google Ads API还是Search Console还是两者都用，是实现细节。
第三步：真实的人如何完成这些任务？
这是你对技术栈具体化的地方。
对于”检查营销活动效果”：
- 真实的人登录Google Analytics
- 查看过去7天的流量
- 与上一时间段进行比较
- 记录重大变化
技术翻译：
- 查询Google Analytics API
- 属性ID：478766521
- 指标：会话数、页面浏览量、跳出率
- 日期范围：过去7天 vs 前7天
- 需要OAuth凭据
现在你知道要构建什么配方了。
第四步：我们的技术栈支持这个吗？
我们能从运行时环境访问这些API吗？
检查：
- 我们有凭据吗？（检查.env，检查OAuth设置）
- 我们能从沙箱进行API调用吗？（测试curl命令）
- 是否安装了所需的包？（检查Docker镜像或按需安装）
如果答案是否，要么：
- 向运行时添加该功能（安装包，配置OAuth）
- 使用不同的方法（有重型依赖时使用MCP服务器）
- 调整Character的角色（承认限制）
运行时现实限制了可能的事情。如果沙箱中没有安装psql，无论多少提示词工程都无法给Claude数据库访问权限。
第五步：编写并测试配方
这是大多数人跳过的关键步骤。
不要写：
智能体可以使用API查询Google Analytics。要写：
# 查询Google Analytics — 过去7天流量
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
"https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
-d '{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"metrics": [{"name": "sessions"}]
}'
# 最后测试：2026-02-10（有效）
# 负责人：营销团队
# 凭据：来自OAuth的GA_ACCESS_TOKEN（1小时后过期）然后实际运行它。验证它是否有效。修复失败的部分。记录有效版本。
配方只有经过测试才是真实的。
第六步：组合Character
现在你有了：
- 清晰的角色（营销总监）
- 具体的任务（每周更新、流量分析）
- 经过测试的配方（Search Console、Analytics、Resend）
Character就是这个组合：
# 营销总监Character
## 角色
你是TeamDay的营销总监。你监控绩效，
分析趋势，并向利益相关者传达洞察。
## 主要职责
- 发送每周绩效报告（周五下午4点）
- 每天监控自然流量
- 按需分析关键词排名
## 可用配方
### 通过Resend发送邮件
何时：向利益相关者发送更新时
配方：/recipes/send-email-resend.md
### 查询Search Console
何时：分析自然流量或关键词时
配方：/recipes/search-console-query.md
### 获取Google Analytics
何时：检查整体流量趋势时
配方：/recipes/google-analytics-query.md
## 沟通风格
- 直接，不用企业术语
- 用数字开头（"流量较上周+15%"）
- 解释发生了什么变化以及为什么重要Character引用配方。配方包含可运行示例。
这就是构建真正有效的Character的方式。
通过技术栈重叠实现复用
这是配方模型发挥价值的地方。
营销总监需要访问Search Console。SEO分析师需要访问Search Console。同一个配方。
销售代表需要发邮件。营销总监需要发邮件。同一个配方。
配方自然而然地形成一个库：
/recipes/
├── send-email-resend.md
├── search-console-query.md
├── google-analytics-query.md
├── ahrefs-keyword-analysis.md
├── postgres-query.md
└── notion-page-create.md每个新Character可能只添加1-2个新配方。大多数都被复用。
**但这只有在配方是经过测试的可运行示例时才有效。**如果它们是抽象的工具定义，复用性就无关紧要了，因为它们根本就无法可靠运行。
质量门控
Character的能力只与其经过测试的配方一样真实。
需要问的问题：
不是：“这个Character有邮件配置吗？”
而是：“我们验证过邮件配方真的能发送邮件吗？”
不是：“这个Character能访问我们的数据库吗？”
而是：“我们用真实凭据测试过数据库查询配方吗？”
外表光鲜的Character与真正交付的Character之间的区别在于经过测试的配方。
我们是吃了苦头才学到这一点的。我们为营销网站的/team页面构建了Character。看起来很好。14位可以雇佣的AI员工。专业的描述。令人印象深刻的能力。
然后我们尝试将它们用于真实工作。大多数无法端到端运行。缺少依赖项。未经测试的配方。没有可运行示例的抽象能力。
质量门控：如果我们没有测试过，就不发布。
运行时现实：实际可能的事情
沙箱环境限制了可能的事情。理解这些限制有助于更好地设计Character。
到处都能用的东西
通过curl的HTTP API：
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpoint每个沙箱都有curl。如果你能通过HTTP访问API，就能集成它。
Bash脚本：
#!/bin/bash
# 任何你能脚本化的逻辑都能在沙箱中运行常用CLI工具：
git, grep, sed, awk, jq, node, python需要设置的东西
数据库客户端：
- 需要安装
psql或mysql - 选项1：在Docker镜像中预安装
- 选项2：HTTP API包装器（pg-gateway）
- 选项3：用于复杂查询的MCP服务器
重型包（Puppeteer、Playwright）：
- 大型依赖树
- 二进制依赖（Chrome）
- 选项1：在基础镜像中预安装（如果常用）
- 选项2：MCP服务器（隔离，单独管理）
OAuth流程：
- 交互式身份验证
- Token刷新逻辑
- 选项1：预配置token（环境变量）
- 选项2：MCP服务器处理认证
实用决策树
- 能用curl做吗？ → 写配方，测试，完成
- 需要小于50MB的包？ → 安装到Docker镜像
- 需要重型依赖？ → MCP服务器（最后手段）
- 需要交互式认证？ → MCP服务器或预配置token
运行时要求越简单，Character就越可靠。
与大多数人构建方式的区别
自顶向下（常见方法）：
- 选择AI智能体框架
- 配置MCP服务器
- 添加skills和工具
- 编写系统提示
- 期望它能用
问题：
- 工具已配置但未测试
- 没有可运行示例，只有抽象能力
- Character理论上能做任何事，可靠地什么都做不了
- 第一次真实使用揭示它实际上不起作用
自底向上（我们的方法）：
- 定义具体的角色和任务
- 将任务映射到真实的人类工作流程
- 测试并验证每个工作流程（编写配方）
- 从经过测试的配方中组合Character
- 质量门控：每项能力都经过验证
结果：
- 每个配方都经过测试，已知有效
- Character能力与经过测试的现实相符
- 第一次使用有效，因为配方已经过验证
- 出问题时，我们知道要修复哪个配方
方法论颠覆了流程：从经过验证的工作流程开始，向上组合到Character——而不是从上往下配置工具并抱有希望。
真实示例：营销总监
让我展示我们其中一个Character的实际设计过程。
第一步：角色定义
谁： TeamDay的营销总监 目的： 监控营销绩效并传达洞察
第二步：实际任务
在观察真实营销工作后：
- 检查Google Analytics的流量趋势（每天）
- 监控Search Console的自然关键词排名（每周）
- 向利益相关者发送绩效报告（每周）
- 按需分析特定活动
第三步：真实人类工作流程
对于”发送每周更新”：
- 人员登录Google Analytics
- 查看过去7天：会话数、页面浏览量、热门页面
- 与上周比较
- 记录重大变化
- 检查Search Console的热门查询
- 撰写包含发现的邮件
- 通过Gmail发送
第四步：技术栈检查
Google Analytics：
- ✅ 有API访问权限
- ✅ 属性ID：478766521
- ✅ OAuth已配置
- ✅ 可通过curl查询
Search Console：
- ✅ 有API访问权限
- ✅ 网站：teamday.ai
- ✅ OAuth已配置
- ✅ 可通过curl查询
邮件：
- ✅ 使用Resend（不是Gmail）
- ✅ env中有API密钥：RESEND_API_KEY
- ✅ 可通过curl发送
第五步：编写配方
配方1：Google Analytics — 过去7天
#!/bin/bash
# 从Google Analytics获取过去7天的流量
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
"https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
-d '{
"dateRanges": [
{"startDate": "7daysAgo", "endDate": "today"},
{"startDate": "14daysAgo", "endDate": "8daysAgo"}
],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "screenPageViews"}
],
"dimensions": [{"name": "pagePath"}]
}'
# 测试结果（2026-02-10）：
# {
# "rows": [
# {"dimensionValues": [{"value": "/"}],
# "metricValues": [{"value": "1243"}, {"value": "892"}, ...]}
# ]
# }
# 凭据：GA_ACCESS_TOKEN（OAuth，1小时有效期）已测试： ✅ 有效 最后验证： 2026-02-10
配方2：通过Resend发送邮件
#!/bin/bash
# 通过Resend API发送邮件
TO="$1"
SUBJECT="$2"
BODY="$3"
curl -X POST https://api.resend.com/emails \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"from\": \"[email protected]\",
\"to\": \"$TO\",
\"subject\": \"$SUBJECT\",
\"html\": \"$BODY\"
}"
# 测试结果（2026-02-10）：
# {"id": "abc-123", "status": "sent"}
# 凭据：.env中的RESEND_API_KEY已测试： ✅ 有效 最后验证： 2026-02-10
第六步：组合Character
# 营销总监
你是TeamDay的营销总监。你监控绩效
并传达洞察。
## 每周更新任务
每周五下午4点：
1. 查询Google Analytics（过去7天 vs 前一时间段）
配方：/recipes/google-analytics-7day.sh
2. 查询Search Console（热门自然查询）
配方：/recipes/search-console-top-queries.sh
3. 撰写邮件：
- 主题："TeamDay营销更新 — [日期]那周"
- 格式：
**流量：** [会话数]（较上周[+/-]%）
**热门页面：** [列出前3名]
**热门查询：** [列出前3名]
**显著变化：** [任何变化>20%的内容]
4. 通过Resend发送
配方：/recipes/send-email-resend.sh
收件人：jozo at teamday.ai结果： 一个能可靠发送每周更新的Character，因为每个步骤都是经过测试的配方。
我们吃苦头学到的东西
1. “已测试”意味着真正测试过
我们记录了配方。看起来不错。我们发布了Character。
然后我们尝试使用它们。一半的配方从未运行过。API端点已经改变。凭据是错的。属性ID已过时。
解决方案： 测试每个配方。真正运行它。验证响应。API改变时更新。
2. 配方会衰减
API会改变。凭据会过期。服务会被弃用。
解决方案： 给每个配方标注日期。当Character失败时，检查配方日期。重新测试并更新。
3. 运行时差距是真实存在的
我们设计了一个查询数据库的SQL分析师Character。然后发现沙箱中没有安装psql。
解决方案： 在设计Character之前测试运行时能力。如果没有psql，要么安装它，要么使用HTTP API包装器。
4. 组合胜过配置
我们花了几周为各种能力配置MCP服务器。复杂的设置。很多活动部件。
然后我们用curl命令写了简单的bash脚本。它们立即就能用了。
教训： 从简单开始。带curl的bash脚本能走完80%的路。只有当简单方案不够用时才添加复杂性。
元洞察
整个方法论来自于构建必须真正有效的AI Character——而不只是在演示中好看。
当你为演示构建时：
- 抽象能力没问题
- “能发邮件”就够了
- 配置截图看起来令人印象深刻
当你为生产构建时：
- 经过测试的配方是必须的
- “使用我们的凭据通过Resend可靠地发送邮件”才是标准
- 可运行示例比配置复杂性更重要
方法论差异：演示为能力广度优化，生产为可靠性深度优化。
我们正在构建Character真正工作的AI团队。这迫使我们解决可靠性问题。
自底向上的以配方为先的方法论就是结果。
自己试试
要构建真正有效的Character：
-
定义具体角色 不要：“营销AI” 要做：“发送每周更新的营销总监”
-
列出3个实际任务 不要：“分析营销数据” 要做：“检查Google Analytics中过去7天的流量”
-
写一个可运行示例 不要记录工具。写一个有效的curl命令。 测试它。验证响应。
-
创建一个配方文件 将可运行示例保存为
/recipes/任务名称.md包含：何时使用、凭据、有效代码、最后测试日期 -
从Character中引用 系统提示引用配方文件 Character知道何时使用它、如何调用它
-
端到端测试 真正将Character用于该任务 修复不起作用的东西 更新配方
从一个任务、一个配方、一个Character开始。
一旦你构建了一个可靠运行的，方法论就会豁然开朗。然后扩展到更多配方和更多Character。
我们的/team页面上有14个AI Character。它们看起来很专业。令人印象深刻的能力。但我们学到了：看起来有能力和真正有能力是不同的事情。
真正有效的那些有经过测试的配方。那些是外表光鲜的有抽象的工具定义。
方法论并不复杂：从可运行示例自底向上，组合成Character，端到端测试。
但它颠覆了大多数人构建AI智能体的方式。正是这种颠覆让Character变得可靠。
从配方开始构建。测试一切。发布有效的东西。