第04篇：技能（Skill）系统 —— 用 Rhai 脚本扩展 AI 能力，TaoToken 统一 Key 接入实践

1. 为什么需要 Skill 系统：从单步工具到多步流程

很多人第一次接触 AI Agent 的时候，会觉得“工具调用”已经很厉害了：模型能读文件、能搜网页、能发请求，似乎什么都能干。但真正把它放到日常任务里，你会发现一个尴尬的事实——单步工具解决不了复合任务。

举个我自己踩过的例子。我想让 AI 帮我盯一只股票：每隔十分钟查一次价格，跌破某个阈值就发通知，同时把每次查询结果写进日志。如果只靠工具，我得让模型自己规划：先调行情接口，再判断数值，再决定要不要发消息，最后再写文件。每一步都要模型“想一遍”，中间任何一步格式跑偏，整条链路就断了。更麻烦的是，这种任务需要重复执行，每次都让模型重新推理，既慢又不稳定。

这就是 Skill（技能）系统要解决的问题。技能 = 把多个工具调用封装成可复用的确定性流程。它和工具的关系，有点像“函数”和“语句”：工具是原子操作，技能是有逻辑、有分支、有错误处理的复合体。

一个技能通常由三部分组成，分工非常清晰：

这个设计最妙的地方在于：LLM 的行为可以通过改 Markdown 来调整，不需要重新训练模型。你想让技能多支持一种股票市场，改 SKILL.md 里的表格就行；你想改阈值判断逻辑，改 SKILL.rhai 就行。灵活性和可控性同时拿到了。

而 Rhai 脚本在这里扮演的是“确定性执行层”的角色。它是一个嵌入式脚本语言，语法接近 JavaScript 和 Rust 的混合体，专为嵌入 Rust 程序设计。你不需要懂 Rust，只要会写let、if、for，就能写出可用的技能脚本。对于没有编程经验的人来说，它的上手门槛比 Python 还低——没有缩进陷阱，没有复杂的包管理，一个文件就是一个技能。

接下来的内容，我会带你从零跑通一条完整链路：写一个 Rhai 技能脚本，用 TaoToken 统一 Key 接入模型调用，然后验证技能能被正确触发执行。全程可复制，不需要你提前配好一堆环境。

2. TaoToken 前置准备：统一 Key 与 API 通道

在写脚本之前，得先把模型调用的通道打通。技能系统本身负责编排逻辑，但真正“动脑子”的部分——比如理解用户意图、生成 SKILL.md 里的操作规范、在脚本里做语义判断——还是需要调用大模型。如果每个技能都单独配一套 Key，管理起来会非常痛苦。

TaoToken 在这里的作用就是统一 Key 和 API 通道。你只需要一个 Key，就能通过同一个 Base URL 访问多种模型，技能脚本里不用关心具体走的是哪家模型，换模型也不用改脚本。

先拿到 Key。打开控制台地址：

https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

登录后进入 API Keys 页面创建一个新 Key：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

创建时建议给 Key 起一个能识别的名字，比如skill-rhai-demo，方便后面排查问题时定位。Key 只在创建时完整显示一次，复制后先存到安全的地方。

接下来是接入配置。TaoToken 的 API 入口是：

https://taotoken.net/api

注意这个地址不带任何查询参数，是纯粹的 API 端点。如果你用的是 OpenAI 兼容的 SDK 或者工具，配置通常长这样：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "claude-sonnet-4-20250514" }

如果你用的是 Claude Code 这类工具，配置会写在 settings 文件里。以~/.claude/settings.json为例：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

这里有个细节要注意：Base URL 和 Key 必须配套。如果你只改了 Key 没改 Base URL，请求会打到默认端点，然后报 401；反过来只改 Base URL 没换 Key，同样会认证失败。我见过不少人在这两个地方来回折腾，其实只要记住“三件套一起改”就行：Base URL、Key、Model ID。

Model ID 的写法要和你实际使用的模型对应。TaoToken 支持多种模型，具体可用的 Model ID 可以在模型对话页面查看：

https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

配置完成后，先别急着写技能脚本，用一条最简单的请求验证通道是否通。可以用 curl：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复 OK 两个字母"}], "max_tokens": 10 }'

如果返回的 JSON 里有正常的choices字段，说明通道没问题。如果报错，先看错误码：401 是 Key 问题，404 是 Base URL 或路径问题，429 是额度或频率问题。这一步验证通过后，再进入技能脚本的编写，能省掉很多“到底是脚本问题还是通道问题”的排查时间。

3. 可复制配置：Rhai 技能脚本模板与接入片段

现在进入核心部分。我会给出一个完整的技能目录结构，以及三个文件的可复制内容。你可以直接照着建目录、贴文件，然后跑起来。

先建目录。假设你的工作目录是~/.blockcell/workspace/skills/，创建一个叫stock_monitor的技能：

mkdir -p ~/.blockcell/workspace/skills/stock_monitor cd ~/.blockcell/workspace/skills/stock_monitor

第一个文件：meta.yaml

这个文件负责触发词匹配和权限声明。系统会根据用户输入去匹配triggers里的关键词，命中后加载这个技能。

name: stock_monitor description: "A股/港股/美股实时行情监控与分析" version: "1.0.0" triggers: - "查股票" - "股价" - "行情" - "监控股票" - "stock price" permissions: - network - storage

permissions里声明network是因为脚本要调行情接口，声明storage是因为要把结果写日志。权限声明不是摆设，如果脚本里调用了未声明的能力，执行时会被拦截。

第二个文件：SKILL.md

这是给 LLM 看的操作手册。它不是给人读的文档，而是注入到模型上下文里的“行为规范”。写法上要尽量结构化，用表格和步骤降低模型的歧义。

# 股票监控技能操作手册 ## 数据源速查 | 市场 | 代码格式 | 工具调用 | |------|---------|---------| | A股沪市 | 6位数字，如 600519 | finance_api stock_quote source=eastmoney | | A股深市 | 6位数字，如 000001 | finance_api stock_quote source=eastmoney | | 港股 | 5位数字，如 00700 | finance_api stock_quote source=eastmoney | | 美股 | 字母代码，如 AAPL | finance_api stock_quote | ## 常见股票代码 - 贵州茅台: 600519 - 中国平安: 601318 - 腾讯控股: 00700（港股） - 苹果: AAPL ## 场景一：查询实时股价 步骤： 1. 调用 finance_api，action=stock_quote，symbol=股票代码 2. 返回：价格、涨跌幅、成交量、市盈率 ## 场景二：查询历史走势 步骤： 1. 调用 finance_api，action=stock_history，symbol=股票代码，period=1mo 2. 可选：调用 chart_generate 画折线图 ## 错误处理 如果 finance_api 返回错误，降级使用 web_search 搜索 "{symbol} 股价 今日"。

第三个文件：SKILL.rhai

这是真正执行的编排脚本。Rhai 的语法很轻，下面这个模板包含了参数校验、工具调用、错误降级和结果格式化四个环节。

// SKILL.rhai 示例：股票监控 // 获取用户输入的股票代码 let symbol = ctx["symbol"]; if symbol == "" { set_output("请提供股票代码，例如：600519（茅台）"); return; } // 查询实时行情 let quote_result = call_tool("finance_api", #{ "action": "stock_quote", "symbol": symbol }); if is_error(quote_result) { // 降级：尝试用 web_search 搜索 log_warn("finance_api 失败，尝试 web_search"); let search_result = call_tool("web_search", #{ "query": `${symbol} 股价 今日` }); set_output(search_result); return; } // 格式化输出 let price = get_field(quote_result, "price"); let change = get_field(quote_result, "change_pct"); set_output(`${symbol} 当前价格：${price}，涨跌幅：${change}%`);

几个关键点解释一下。ctx是系统传入的上下文，里面装着用户提供的参数。call_tool是调用内置工具的入口，第二个参数是一个 Map，写法是#{ "key": "value" }。is_error判断调用是否失败，get_field从返回结果里取字段。set_output把最终结果返回给用户。

如果你想让技能在跌幅超过阈值时发通知，可以加一段判断：

let threshold = ctx["threshold"] ?? 3.0; let change = get_field(quote_result, "change_pct"); if change < -threshold { call_tool("notification", #{ "channel": "telegram", "message": ` ${symbol} 跌幅 ${change}%，超过阈值 ${threshold}%` }); }

??是空值合并运算符，如果ctx["threshold"]不存在就用默认值 3.0。这个写法在 Rhai 里很常用，能避免参数缺失导致的报错。

接入配置片段

技能脚本里如果需要调用模型做语义判断，可以在脚本里通过 HTTP 工具请求 TaoToken。配置片段如下：

let llm_result = call_tool("http_request", #{ "url": "https://taotoken.net/api/v1/chat/completions", "method": "POST", "headers": #{ "Content-Type": "application/json", "Authorization": "Bearer sk-你的Key" }, "body": #{ "model": "claude-sonnet-4-20250514", "messages": [ #{ "role": "user", "content": "判断这句话的情绪：今天大盘暴跌" } ] } });

注意这里的Authorization头是Bearer sk-你的Key，Base URL 用的是https://taotoken.net/api。如果你把 Key 直接写在脚本里，记得不要把这个技能目录提交到公开仓库。更安全的做法是把 Key 放在环境变量里，脚本里用env("TAOTOKEN_KEY")读取。

4. 验证请求：从注册技能到触发执行

文件都建好之后，需要验证技能能被正确加载和触发。这一步分三个动作：注册、触发、看结果。

动作一：注册技能

技能目录放在~/.blockcell/workspace/skills/下，系统启动时会自动扫描。如果你是在运行中创建的，可以通过对话让 AI 重新加载：

帮我重新加载技能目录

系统会扫描 skills 目录，把meta.yaml里的触发词注册到匹配表里。加载成功后，通常会看到类似这样的日志：

[skill] loaded: stock_monitor (triggers: 查股票, 股价, 行情, 监控股票, stock price)

如果没看到日志，先检查目录结构对不对。meta.yaml、SKILL.md、SKILL.rhai三个文件必须在同一个目录下，目录名就是技能名。文件名大小写也要注意，SKILL.rhai不能写成skill.rhai。

动作二：触发技能

在对话里输入包含触发词的内容：

帮我查一下茅台的股价

系统会匹配到stock_monitor技能，然后把SKILL.md注入到 LLM 上下文，同时把用户输入里的参数提取出来传给SKILL.rhai。Rhai 引擎执行脚本，调用finance_api工具，拿到结果后格式化输出。

动作三：看结果

如果一切正常，你会看到类似这样的返回：

600519 当前价格：1680.50，涨跌幅：-1.23%

如果行情接口失败，脚本会走降级逻辑，用web_search搜索，返回搜索结果。如果连搜索也失败，会返回错误信息。你可以通过日志确认走了哪条路径：

[skill] stock_monitor executed, tool=finance_api, status=ok

验证模型调用通道

如果你的技能脚本里包含了对 TaoToken 的模型调用，可以用一条独立的请求先验证通道。打开模型对话页面：

https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

在对话框里输入“回复 OK”，如果能正常返回，说明 Key 和 Base URL 配置正确。这一步和技能脚本里的调用是同一个通道，通道通了，脚本里的请求就不会因为认证问题失败。

热重载验证

技能系统支持热重载。你修改SKILL.rhai后，不需要重启整个系统。比如把阈值从 3% 改成 5%：

let threshold = ctx["threshold"] ?? 5.0;

保存文件后，系统会检测到变化并重新加载。日志里会看到：

[skill] reloaded: stock_monitor

这个功能在开发调试阶段特别有用。你可以一边改脚本一边触发，不用反复重启。

一个完整的验证清单

这张表建议存下来，后面遇到问题按行排查，比盲目试错快得多。

5. 常见错误排查：401、local proxy failed、reading choices、OAuth

技能系统跑起来之后，最容易出问题的不是脚本逻辑，而是接入层。下面这几个报错我见过太多次，逐个拆解。

报错一：401 Unauthorized

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

这个最直接，Key 不对。可能的原因有三个：Key 复制时少了字符、Key 已经被删除或重置、Key 和 Base URL 不匹配。排查顺序是：先去 API Keys 页面确认 Key 还在，然后重新复制一次，确保没有多余空格。如果用的是环境变量，检查变量名有没有拼错。

echo $ANTHROPIC_API_KEY

如果输出为空，说明环境变量没生效。在 settings.json 里配置的话，注意 JSON 格式，末尾不能有多余逗号。

报错二：local proxy failed

Error: local proxy failed: connection refused

这个报错通常出现在你本地配了代理，但代理服务没启动，或者端口不对。技能脚本里的 HTTP 请求会走系统代理设置，如果代理挂了，请求就发不出去。排查方法是先确认代理服务状态，或者临时把代理关掉，直接用直连测试。

如果你在 settings.json 里配了HTTP_PROXY或HTTPS_PROXY，先注释掉再试。TaoToken 的 API 入口是公网地址，不需要额外代理就能访问。

报错三：reading choices

Error: reading 'choices' - undefined

这个报错说明请求发出去了，也拿到了响应，但响应结构里没有choices字段。常见原因是 Base URL 写错了，比如写成了https://taotoken.net而不是https://taotoken.net/api，或者路径少了/v1。另一个可能是 Model ID 写错了，服务端返回了一个错误对象，而不是正常的 completion 结构。

排查方法是用 curl 直接打一次，看返回的原始 JSON：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}]}'

如果返回里有error字段，按错误信息处理。如果没有choices也没有error，检查 Model ID 是否在支持列表里。

报错四：OAuth 相关错误

Error: OAuth token expired

如果你用的是 Claude Code 这类带 OAuth 流程的工具，可能会遇到 token 过期。这时候需要重新走一次授权，或者改用 API Key 方式接入。用 TaoToken 的 Key 接入时，配置里应该用ANTHROPIC_API_KEY而不是 OAuth token。两者不要混用，混用会导致认证冲突。

三件套检查法

不管是哪个报错，先检查三件套是否一致：

如果三件套都对，再看网络和权限。技能脚本里的permissions声明了network才能发请求，没声明会被拦截。这个拦截报错通常会说permission denied，和认证错误区分开。

一个容易忽略的点

技能热重载之后，如果脚本里有语法错误，系统可能不会立即报错，而是在触发时才报。所以改完脚本后，最好手动触发一次，确认没有运行时错误。Rhai 的错误信息会指出行号，按行号定位很快。

6. 语义一致 CTA：把技能接入你的工作流

技能系统跑通之后，下一步就是把它接到你日常的工作流里。这里给几个方向，按需选择。

如果你主要是在做排障和接入，建议先把 API Keys 和接入文档过一遍，确保通道稳定：

https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

接入文档里有各种语言和工具的配置示例，包括 Claude Code、Cline、Codex 等：

https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

如果你只是想验证模型是否可用，直接打开模型对话页面，输入一句话就能测：

https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

如果你打算长期用技能做编码或 Agent 任务，Coding Plan 会更合适，额度和稳定性都更适合持续调用：

https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=skill_rhai&utm_campaign=rewrite

回到技能本身。Rhai 脚本的扩展能力不止于股票监控。你可以把任何重复性的多步流程封装成技能：每天早上汇总日程、监控某个网页变化、批量处理文件、定时抓取数据。核心思路是一样的：meta.yaml定义触发条件，SKILL.md给模型操作规范，SKILL.rhai写确定性逻辑。

我自己的习惯是，先把流程用 Rhai 写死，跑通之后再考虑要不要让模型介入做语义判断。确定性逻辑交给脚本，模糊判断交给模型，两者分工明确，整个链路就稳了。技能目录建议用 git 管理，但记得把 Key 放在环境变量里，不要提交到仓库。

最后留一个实用技巧：调试 Rhai 脚本时，多用log_warn和set_output打中间结果。Rhai 没有断点调试，但日志足够定位问题。把中间变量输出出来，比盯着报错猜要快得多。