1. 从「青岛港 PB 粉」说起：structured-query 与模型通道的关系
在 mystu 项目里，我经常要回答「青岛港 PB 粉最新库存和环比？」这类问题。若手工处理，得先登录数据库、写 SQL、再把结果翻译成人话；后来把整条链路做成了 deepagents 的一个 Skill，让 Agent 自己走sql_db_list_tables→sql_db_schema→sql_db_query。整套编排里真正消耗 Token 的是 LLM 的推理与工具调用决策，而模型 Key 的分散管理一直是痛点。现在我统一把模型通道切到 TaoToken，先去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建一把 Key，再把 deepagents 的model参数指向https://taotoken.net/api，Skill 的装配逻辑一行都不用改。
1.1 什么是 structured-query 智能问数
结构化智能问数，简单说就是让大模型把自然语言问题拆解成数据库查询动作，再把查询结果组织成一句带口径的话。整个过程不需要向量检索，也不涉及 Embedding，核心是「LLM 写 SQL → 服务端校验 → 只读执行 → LLM 解读结果」。以「青岛港 PB 粉最新库存和环比？」为例，Agent 需要先识别这是一个需要具体数值、聚合、排名的结构化问题，接着查看数据库里有哪些白名单视图，然后生成一条只读 SELECT，最后把「统计日、库存量、环比变化、数据来源」说清楚。
在 structured-query-pack 中，这条链路被拆成三层：最上层是 Skill，也就是SKILL.md，它告诉大模型「何时用、按什么顺序调工具、如何解释结果」；中间层是 Toolkit，提供 LangChain 标准的 SQL 四工具，并在sql_db_query外包一层 sqlglot 护栏；最底层是 Host 接入，也就是 mystu 的deepagent.py，负责把模型、工具、Skill 目录装配到一起。TaoToken 只替换了模型层的 Key 和 Base URL，这三层本身完全不用动。
1.2 Token 消耗集中在 LLM 编排，而不是 SQL 工具
很多人误以为智能问数很贵是因为数据库查询，其实 SQL 工具本身只是把字符串发给 MySQL 再拿回结果，几乎不产生模型费用。真正花钱的是中间这几步：大模型判断问题是否匹配 Skill、调用read_file读取SKILL.md全文、决定按什么顺序调用sql_db_list_tables和sql_db_schema、参考 schema 生成 SQL、看到查询结果后再组织自然语言回答。每一步都是一次模型推理，也就是一次 Token 消耗。
所以你会发现，模型 Key 越稳定、Base URL 越统一，后期排查成本越低。现在这套通道扮演的是统一 API 入口：同一个 Key 可以服务多个 Agent 项目，用量在控制台一目了然，不用再为每个项目单独维护一套 DeepSeek 或其它厂商的密钥。如果你还在为「每个 Agent 项目一套 Key、一套 Base URL」头疼，可以把这一步先收敛掉，再回来看 Skill 的工作流。
2. 模型通道换到 TaoToken 前，先到官网创建 API Key
继续使用 deepagents 的 structured-query Skill 之前，你需要一个能被 LangChain 和 deepagents 同时识别的模型入口。以前我直接配 DeepSeek 的 Key 和 Base URL，换一个项目就要复制一份环境变量，团队里其他人问起来还得解释半天。这次我换成 TaoToken：打开官网，注册后进入控制台创建 API Key，复制下来当作YOUR_API_KEY。这个 Key 不是用来填进 SQL 工具链的，它是给 deepagents 的 LLM 层用的。注意 Key 的格式和创建位置都以官网控制台为准，不要在其它渠道乱找。
2.1 官网地址和接口地址不要混用
这套通道有两类地址，写错一步就会 404 或 401。一类是给人点的页面，用于注册、创建 Key、看模型广场、看用量，统一写https://taotoken.net/?utm_source=taotoken_aicg_blog_end；另一类是填进程序里的 API 地址，写https://taotoken.net/api，末尾不要加/v1。很多 SDK 默认会帮你追加/v1，如果你自己又写了一个，最终请求会变成https://taotoken.net/api/v1/v1之类的路径，必然失败。
这里有个小技巧：在 ChatOpenAI 这类客户端里，base_url参数填到/api为止，剩下的路径由 SDK 自己拼。不要把官网链接复制进代码，也不要把utm_source参数拼到接口地址上。API 地址是给程序用的，官网链接是给人用的，两者职责不同。
| 用途 | 地址 |
|---|---|
| 注册、创建 Key、模型广场、用量 | https://taotoken.net/?utm_source=taotoken_aicg_blog_end |
| 填进程序的 Base URL | https://taotoken.net/api（不带 /v1） |
2.2 模型 ID 以官网模型广场当时列表为准
它提供了一个模型广场，里面会列出当前可用的模型 ID。由于模型列表会持续更新，我不在这里写死任何具体 ID，避免你照抄之后发现不存在。配置时，打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end ，找到你需要的模型，把它的 ID 复制出来，替换代码里的YOUR_MODEL_ID。
模型 ID 的大小写和特殊符号必须完全一致，比如有些模型带日期后缀，少一个点都会导致 404。这个 ID 和 API Key 一样，都是给 LLM 层用的，与 SQL 工具链无关。如果你在多个 Agent 项目里复用同一个 Key，模型 ID 可以根据每个项目的需求选择不同型号，但都要以模型广场当时列表为准。
3. deepagents 装配 structured-query：CompositeBackend 与 skills 参数保持原样
模型通道换好后，接下来是 deepagents 侧的装配。如果你以前跑过 structured-query-pack，会发现除了model的初始化方式变了，其他代码几乎不用动。核心仍然是把/skills/虚拟路径映射到 pack 的磁盘目录，然后让 SkillsMiddleware 在会话启动时扫描每个 skill 的SKILL.mdfrontmatter，把摘要注入系统提示词。这叫做渐进式披露：启动时大模型只看到「有哪些 Skill、分别干什么」，不会一上来就把整篇 Skill 文档塞进上下文。
3.1 SkillsMiddleware 只扫 SKILL.md，不扫 references
一个常见的误解是 references 目录里的iron-ore.md会自动进入上下文。实际上，SkillsMiddleware 通过CompositeBackend列出/skills/下的子目录后，只读取每个目录里的SKILL.md，解析 YAML frontmatter 中的 name、description、allowed-tools，然后把摘要追加到系统提示词。references/下的领域 overlay 文档不会被自动加载，除非大模型主动调用内置的read_file工具去读取。
这意味着你可以在references/iron-ore.md里写很详细的表名字段口径，但它不会污染每次对话的上下文；只有当你希望大模型「必定使用」这个 overlay 时，才需要在SKILL.md正文里显式写一行「执行结构化查数前，请先阅读 /skills/structured-query/references/iron-ore.md」。这个设计让通用模板和领域知识解耦，也是 structured-query-pack 能轻松拷贝到其他项目的原因。
3.2 model 初始化：把 LangChain 模型指向 TaoToken
deepagents 的create_deep_agent接受一个 LangChain 兼容的模型实例。我们不需要改 deepagents 的任何源码，只需要把模型初始化从「读 DeepSeek 环境变量」改为「读 TaoToken 的 Key 和 Base URL」。下面这段代码可以直接放进你的deepagent.py：
from langchain_openai import ChatOpenAI model = ChatOpenAI( model="YOUR_MODEL_ID", # 以模型广场当时列表为准 base_url="https://taotoken.net/api", api_key="YOUR_API_KEY", temperature=0, )注意base_url末尾不要加/v1，api_key必须是从官网创建的那把。这里用 ChatOpenAI 是因为它兼容 OpenAI 协议，这套通道可以接入这类客户端；如果你更习惯 Anthropic 风格，也可以换成对应的 LangChain Anthropic 模型，只要base_url和api_key仍指向同一套通道。模型能力、上下文长度、价格都会因 ID 而异，以模型广场当时列表为准。
3.3 完整装配代码：CompositeBackend、工具注入、skills 参数
下面把完整装配写出来。这里和原始示例的差异只在model的构造，其余部分保持一致：
from deepagents import create_deep_agent from deepagents.backends import CompositeBackend, StateBackend from deepagents.backends.filesystem import FilesystemBackend from langchain_openai import ChatOpenAI from structured_query_pack import ( AGENT_SKILLS_DIR, SKILLS_VIRTUAL_PREFIX, get_sql_toolkit_tools, ) def build_backend(): return CompositeBackend( default=StateBackend(), routes={ SKILLS_VIRTUAL_PREFIX: FilesystemBackend( root_dir=str(AGENT_SKILLS_DIR), virtual_mode=True, ), }, ) model = ChatOpenAI( model="YOUR_MODEL_ID", base_url="https://taotoken.net/api", api_key="YOUR_API_KEY", temperature=0, ) tools = [*get_sql_toolkit_tools(model)] agent = create_deep_agent( model=model, tools=tools, system_prompt="你的系统提示词（说明何时走结构化查数）", backend=build_backend(), skills=[SKILLS_VIRTUAL_PREFIX], )get_sql_toolkit_tools(model)返回四个 SQL 工具：sql_db_list_tables、sql_db_schema、sql_db_query_checker、sql_db_query。其中sql_db_query会在执行前被sql_guard拦一道，用 sqlglot 解析成 AST，只放行 SELECT，表白名单校验不通过就返回错误字符串给大模型，让它改写 SQL 重试。这套护栏不依赖模型通道，哪怕你换到任意一个模型，它都照常工作。
4. 完整问数链路：list → schema → checker → query
以「青岛港 PB 粉最新库存和环比？」为例，跑一遍完整链路。这条链路在原始实现里分为阶段 0 到阶段 4，其中阶段 0 是 Agent 启动时的装配，阶段 1 到 4 是运行时行为。我们一条条看，你就能知道哪些步骤消耗 Token、哪些步骤只是工具调用。
4.1 阶段 0：启动时注入 Skill 摘要与 SQL 工具
服务启动后，build_agent()会做四件事：创建 LangChain 模型实例并传入create_deep_agent；把get_sql_toolkit_tools(model)返回的四个工具追加到工具列表；设置CompositeBackend，把/skills/映射到 pack 磁盘目录；设置skills=["/skills/"]，启用 SkillsMiddleware。完成之后，structured-query的 SKILL.md frontmatter 摘要已经出现在系统提示词里，但完整文件还没被读取。这一步会消耗一次模型调用的 Token，因为系统提示词被送进了 LLM。
4.2 阶段 1 到 4：匹配 Skill、读取工作流、生成 SQL、执行查询
当用户发来「青岛港 PB 粉最新库存和环比？」时，大模型根据摘要判断这个问题属于数值指标查询，于是调用内置read_file读取/skills/structured-query/SKILL.md。这一步是一次工具调用，会产生输入 Token（读取的文件内容进入上下文），但比直接把整个 Skill 常驻上下文要省得多。
SKILL.md会引导大模型按顺序做四件事：先sql_db_list_tables看当前白名单视图（比如view_port_inventory），再sql_db_schema看这个视图的列与样例行，然后用sql_db_query_checker自检 SQL 语法和逻辑，最后sql_db_query执行查询。过程中生成的可能 SQL 长这样：
SELECT stat_date, port_name, ore_type, inventory_wet_10k_tons, wow_change_10k_tons, data_source FROM view_port_inventory WHERE port_name = '青岛港' AND ore_type = 'PB粉' ORDER BY stat_date DESC LIMIT 1注意，这条 SQL 不是由人写的，而是大模型根据SKILL.md里的示例和sql_db_schema返回的列信息生成的。生成 SQL 和解读结果的两个环节会消耗 Token，sql_db_list_tables和sql_db_schema的返回结果也会作为上下文传给模型，所以你会看到一次问数的 Token 用量包含了多次工具调用的输入输出。这些都可以在控制台的用量记录里看到。
4.3 SQL 执行的安全边界
为了安全，sql_db_query到达数据库前还会经过sql_guard：sqlglot 解析为 AST，只允许 SELECT 和 UNION；SQL 中出现的表名必须在SQL_ALLOWED_TABLES白名单内；禁止 DML/DDL 关键字；如果 SQL 没有 LIMIT，自动追加LIMIT 100。如果你在自己的环境里复现，请务必使用只读 MySQL 账号，并让 Agent 只能访问白名单视图。
也就是说，Agent 生成 SQL、工具执行查询都发生在受控的测试库或只读账号下；不要让 Agent 直连生产写库。对于重要生产库，更稳妥的做法是让 Agent 只生成和解释 SQL，由你在本地 SQL 客户端执行后再把结果贴回对话。这不是模型通道能解决的，而是数据库权限设计的一部分。
5. 验证一次「青岛港 PB 粉」调用，并让同一个 Key 复用到其他 Agent
配完之后，不要急着写业务代码。先跑一条最小验证，确认模型通道、Skill 发现、SQL 工具三件事都正常。最好的验证方式是直接调用 agent 实例，传入一个已知的领域问题，观察输出是否包含完整的 list → schema → query 过程。
5.1 对着控制台跑一次完整链路
启动你的 deepagents 服务后，在对话里发一句「青岛港 PB 粉最新库存和环比？」。如果一切正常，日志中应该能看到sql_db_list_tables、sql_db_schema、sql_db_query三个工具被依次调用，最后返回一句包含统计日、库存量、环比变化和单位（万吨湿吨）的自然语言回答。类似这样：
截至 2026-06-26，青岛港 PB 粉库存为 142.6 万吨湿吨，环比上周减少 3.2 万吨湿吨，数据来源为港口调研周报。此时打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的用量页面，你应该能看到这次对话产生的 Token 记录。这里要特别说明：官网落地页只能用于看用量、管理 Key 和模型广场，真正执行查询的 Base URL 仍然是https://taotoken.net/api，不要把官网地址填进程序。
5.2 同一个 Key 如何复用到多个 Agent 项目
这套通道的 Key 和账号绑定，不是和某个项目绑定。所以你在 mystu 里创建了YOUR_API_KEY后，另一个 LangGraph Agent 或 deepagents 项目可以直接复用同一个 Key，只需要把base_url填成https://taotoken.net/api，模型 ID 按各自需要选择。如果团队里有多个人，建议在控制台分别创建 Key，方便对账。
这样你就不需要为每个项目维护独立的 DeepSeek Key，也不用在项目之间复制环境变量。Skill 和 Tool 层面本来就是可拷贝的：把structured-query-pack/整个目录复制到新仓库，安装依赖、配置SQL_READONLY_DSN和SQL_ALLOWED_TABLES，再渲染SKILL.md，最后把 model 初始化里的 Key 和 Base URL 换成同一套配置，即可跑起来。复用成本非常低。
6. 排障：401 与「跳过 SQLDatabaseToolkit」
接入过程中，我遇到的报错主要集中在两处：一处是模型通道的认证失败，另一处是 SQL 工具没有被注入。下面这两个排查路径基本覆盖了大多数问题。
6.1 401 Unauthorized：Key 没创建或模型 ID 不对
如果你在调用时收到 401，先检查api_key是否填成了占位符YOUR_API_KEY，或者 Key 是否真的在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建过。官网控制台创建的 Key 是唯一的，复制时不要带上多余空格。另一个容易踩的是模型 ID 写错：模型广场会列出当前可用的模型 ID，如果你把某个模型的旧名称或自己猜的日期后缀填进去，网关会拒绝认证或返回 404。记住，模型 ID 要以模型广场当时列表为准，不要凭记忆写。
6.2 启动日志出现「跳过 SQLDatabaseToolkit」或工具列表为空
如果 Agent 能正常对话，但遇到数值问题不会走 list → schema → query，很可能是 SQL 四工具没有注入。pack 里get_sql_toolkit_tools(model)在SQL_READONLY_DSN未配置或SQL_ALLOWED_TABLES为空时会返回空列表，从而优雅降级。你需要检查.env是否设置了这两个变量，并确认白名单视图真的存在。
另一个常见问题是SQLDatabaseToolkit在 MySQL 下默认view_support=False，导致白名单里的 VIEW 报not found；pack 已经通过view_support=True和兼容包装处理了，如果你自己写工具，要留意这个坑。
6.3 Skill 摘要没进系统提示词
如果你在日志里完全看不到structured-query的摘要，先确认skills=[SKILLS_VIRTUAL_PREFIX]确实传给了create_deep_agent，且CompositeBackend的 routes 里包含对应映射。还要检查SKILL.md的 frontmatter 是否包含 name 和 description，并且 name 与目录名一致。注意allowed-tools必须和get_sql_toolkit_tools注入的工具名完全一致，否则即使 Skill 被发现，工具调用也会被中间件过滤掉。
7. 跑通之后：去控制台对账，再按需选 Coding Plan
当「青岛港 PB 粉」这条链路能稳定返回自然语言回答，说明模型通道和 structured-query Skill 已经打通。下一步建议去控制台做一次对账，确认这次调用的 Token 消耗和预期一致，再决定后续的套餐。
7.1 先到模型对话做一次冒烟测试
到 模型对话 用同一把 Key 发一条测试消息，确认模型 ID 和 Base URL 没有填错。这条链路跑通后，再回 deepagents 里验证一次完整问数，就能确认工具调用没有受到模型通道切换的影响。冒烟测试最好选一条领域问题，而不是简单的「你好」，这样能同时验证工具调用和自然语言回答两个环节。
7.2 长期使用再看 Coding Plan 和 API Keys
如果接下来打算长期写 Agent，可以打开 Coding Plan 看套餐是否够用；需要重新创建或管理 Key，就去 控制台 API Keys。完整的环境变量对照可以参考 接入文档，虽然文档标题是 Claude Code，但 Base URL 的填写规则对 deepagents 同样适用：统一填https://taotoken.net/api，不要带/v1，Key 用YOUR_API_KEY。
