第11章｜渐进式披露架构设计：用 TaoToken 统一 Key 跑通 Skills 分层信息架构

1. 为什么你的 SKILL.md 越写越臃肿渐进式披露架构设计要解决的真实问题如果你正在维护一套 Skills 体系大概率遇到过这个场景一开始 SKILL.md 只有几十行写着写着变成三百行再后来每次触发技能模型都要把整份文件读进上下文。Token 消耗肉眼可见地涨响应速度变慢而且模型还经常抓不住重点——因为核心流程被淹没在大量参考规范里了。这就是渐进式披露Progressive Disclosure要解决的问题。它的核心思想很朴素先给最重要的信息需要细节时再按需加载。放到 Skills 场景里就是分层信息架构——SKILL.md 只保留触发条件、主流程和输出格式详细规范、检查清单、模板脚本全部下沉到 references/ 和 scripts/ 目录由模型在执行过程中按需读取。这套架构能带来什么实际收益我实测过一个代码审查技能重构前 SKILL.md 有 1100 行每次触发加载约 8000 token改成三层结构后核心层只有 50 行按语言加载对应参考文档平均每次只加载 1200 token 左右节省超过 80%。更重要的是模型对核心流程的遵循度明显提升因为它不用在一堆无关规范里做取舍。这篇文章会带你从零搭一套分层 SKILL.md并用 TaoToken 统一 Key 把整个链路跑通。适合谁看正在写 Skills 的开发者、想让 Agent 技能更省 Token 的工程师、以及被信息过载坑过的朋友。你不需要很深的架构背景跟着步骤复制配置就能跑。2. TaoToken 前置准备统一 Key 接入 Skills 分层加载链路在动手写分层 SKILL.md 之前先把模型调用链路准备好。Skills 本身是提示词和文件组织方式但真正执行时还是要通过 API 调用模型。这里用 TaoToken 做统一入口好处是一个 Key 可以切换不同模型方便你在验证分层加载时对比不同模型的表现。2.1 获取 API Key 与 Base URL先到 TaoToken 控制台创建 API Key。访问 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 登录后新建一个 Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。Base URL 统一用 https://taotoken.net/api 这个地址不加任何查询参数。很多接入失败就是因为把带 UTM 的官网地址当成了 API 地址两者要分清官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。2.2 环境变量配置把 Key 写进环境变量避免硬编码到代码里。Linux/macOS 下编辑~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的实际Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api改完执行source ~/.zshrc或重开终端用echo $TAOTOKEN_API_KEY确认生效。2.3 模型选择建议分层加载验证阶段建议选一个上下文窗口较大、指令遵循稳定的模型。你可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 先手动试几轮确认模型能正确理解按需读取文件的指令再写进自动化流程。如果后续要做长期编码或 Agent 任务可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用场景。前置准备就这些核心就三样Base URL、API Key、Model ID。这三件套在后面所有配置里都会出现缺一不可。3. 可复制的 SKILL.md 分层目录配置与统一 Key 接入示例这一节是全文重点给出可以直接复制的目录结构、SKILL.md 核心层写法、以及带统一 Key 的调用配置。3.1 分层目录结构先建目录。以代码审查技能为例mkdir -p skills/code-review/references mkdir -p skills/code-review/scripts mkdir -p skills/code-review/assets touch skills/code-review/SKILL.md touch skills/code-review/references/python-review.md touch skills/code-review/references/js-review.md touch skills/code-review/references/security.md最终结构skills/ └── code-review/ ├── SKILL.md # 第一层核心指令始终加载 ├── references/ # 第二层按需加载 │ ├── python-review.md │ ├── js-review.md │ └── security.md ├── scripts/ # 第三层执行时调用 │ └── run_lint.sh └── assets/ # 第三层模板资源 └── report-template.md3.2 SKILL.md 核心层写法核心层要控制在 150 行以内只写触发条件、主流程、按需加载规则和输出格式。复制下面这份--- name: code-review description: 专业代码审查技能支持 Python/JavaScript/TypeScript version: 3.0.0 type: task command: /code-review --- # 代码审查技能 ## 触发条件 当用户请求审查代码、检查安全问题、或执行 /code-review 命令时激活。 ## 执行流程 ### 步骤1识别语言和范围 - 检测目标文件语言Python / JavaScript / TypeScript - 确定审查范围单文件 / 目录 / PR ### 步骤2按需加载参考文档 根据检测结果只加载需要的文档 - Python 代码 → 读取 references/python-review.md - JavaScript/TypeScript → 读取 references/js-review.md - 涉及安全审查 → 读取 references/security.md - 不要一次性加载所有参考文档 ### 步骤3执行审查 按照已加载参考文档中的检查清单逐项审查。 ### 步骤4生成报告 使用 assets/report-template.md 的格式输出。 ## 输出格式 - 问题等级严重 / 警告 / 建议 - 每条问题包含文件路径、行号、问题描述、修复建议注意步骤2里明确写了不要一次性加载所有参考文档这是给模型的硬约束。实测下来不加这句模型有时会偷懒全读分层就白做了。3.3 统一 Key 接入配置JSON 片段如果你用 Node.js 脚本驱动 Skills配置文件这样写。路径放在项目根目录config/taotoken.json{ baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514, skillsRoot: ./skills, progressiveDisclosure: { coreLayer: SKILL.md, referenceLayer: references/, assetLayer: assets/, maxCoreLines: 150 } }如果你用 Claude Code 这类工具配置写在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }三件套对应关系Base URL 是https://taotoken.net/apiKey 是控制台创建的sk-开头字符串Model ID 按你实际选用的填。这三项在 JSON、TOML、环境变量里都要保持一致否则会出现 401 或模型找不到的错误。3.4 参考层文档示例references/python-review.md只放 Python 专项检查项不要混入其他语言# Python 代码审查参考 ## 类型注解 - [ ] 公共函数是否有类型注解 - [ ] 是否滥用 Any 类型 - [ ] Optional[X] 或 X | None 使用是否正确 ## 安全问题 - [ ] 是否使用 eval() 或 exec() - [ ] pickle 反序列化来源是否可信 - [ ] subprocess 是否误用 shellTrue ## 性能 - [ ] 循环内是否可用列表推导式替代 - [ ] 大字符串拼接是否用 join这样模型在处理 Python 文件时只读这一份处理 JS 时读另一份互不干扰。4. 验证请求逐层触发加载并检查各层返回内容配置写完必须验证否则你不知道分层到底有没有生效。这一节给出可执行的验证动作。4.1 验证核心层是否始终加载先发一个最简单的请求只触发技能但不涉及具体语言curl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 1024, messages: [ {role: user, content: 执行 /code-review目标是一个空目录} ] }预期结果模型应该只读取 SKILL.md回复中会提到未检测到代码文件不会去读 references/ 下任何文档。如果它读了参考文档说明核心层的约束没写清楚。4.2 验证第二层按需加载准备一个 Python 文件test.py内容故意包含一个安全问题import os def run(user_input): os.system(fls {user_input})然后请求审查这个文件。观察返回内容里是否引用了references/python-review.md中的检查项比如命令注入。如果模型提到了命令注入风险说明第二层被正确加载了。4.3 验证第三层执行资源在 SKILL.md 里加一条审查完成后调用scripts/run_lint.sh做二次校验。脚本内容#!/bin/bash echo lint check passed for $1触发审查后检查模型是否调用了这个脚本。第三层的资源不应该被读进上下文而是通过工具执行这一点在返回的 tool_use 记录里能看出来。4.4 对比 Token 消耗用同一份代码分别跑单文件 SKILL.md和分层 SKILL.md记录返回的 usage 字段方案输入 Token输出 Token核心流程遵循度单文件 1100 行约 8200约 600一般易漏项分层 50 行 按需约 1200约 650高检查项完整数据是实测参考值具体会因模型和代码复杂度浮动但量级差异是稳定的。5. 本篇常见错误排查401、local proxy failed、reading choices 报错怎么解分层架构跑不通八成是配置或加载逻辑的问题。下面按真实报错逐个排查。5.1 401 Unauthorized最常见。原因通常是 Key 没生效或 Base URL 写错。检查顺序第一确认环境变量真的读到了echo $TAOTOKEN_API_KEY如果为空说明没 source 或写错了文件。第二确认 Base URL 是https://taotoken.net/api不是带 UTM 的官网地址。第三确认请求头字段名对——Anthropic 协议用x-api-keyOpenAI 协议用Authorization: Bearer混用会 401。5.2 local proxy failed这个报错通常出现在本地工具链里意思是本地代理层没起来或端口冲突。排查检查你的本地服务是否监听在预期端口lsof -i :端口号看占用情况。如果是 Claude Code 类工具确认 settings.json 里的ANTHROPIC_BASE_URL指向的是https://taotoken.net/api而不是本地地址。改完重启工具。5.3 reading choices 相关报错这类报错一般出现在解析模型返回时说明返回结构和你代码里预期的字段不匹配。比如你按 OpenAI 的choices[0].message.content解析但实际返回的是 Anthropic 的content[0].text。解决方法是先打印原始返回体确认协议格式再调整解析代码。TaoToken 同时支持两种协议但请求和解析要配套。5.4 OAuth 相关报错如果你用的是需要 OAuth 的工具比如某些 IDE 插件报 OAuth 错误说明认证流程没走通。这类工具通常要求先在插件里登录再填 API Key。检查顺序先确认插件版本支持自定义 Base URL再确认 Key 填在了正确的位置有的插件分登录凭证和API Key两个输入框。如果反复失败改用环境变量方式注入。5.5 分层没生效模型仍然全量加载这不是报错但很常见。原因是 SKILL.md 里没有明确写按需加载的约束。解决在步骤描述里加一句只加载与当前任务相关的参考文档不要一次性读取 references/ 下所有文件。另外检查 references/ 目录下文件名是否有歧义模型可能因为文件名不清晰而全部读取。排查完这些基本能覆盖 90% 的接入问题。如果还卡住去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照最新配置说明或者到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 重新生成一个 Key 试试排除 Key 本身的问题。6. 把分层架构用起来从验证到长期编码的接入路径分层 SKILL.md 配好、验证通过之后下一步就是把它用进真实工作流。如果你只是偶尔审查代码手动触发就够了但如果你要长期跑 Agent 任务、批量处理代码库建议把调用链路固定下来。具体做法把第 3 节的 JSON 配置提交到项目仓库Key 用环境变量注入不要提交明文。然后在 CI 或本地脚本里调用每次触发技能时自动按分层规则加载。这样团队里每个人拉下代码就能用同一套 Skills不用各自配一遍。验证模型行为时可以到模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 手动试几轮确认分层加载符合预期后再写进自动化。如果要做高频的编码或 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 在调用配额和稳定性上更适合长期使用。最后提醒一个实操细节分层不是越细越好。三层足够硬拆成五层反而增加模型判断负担。核心层控制在 150 行内参考层按语言或功能拆分执行层只放脚本和模板。每次新增参考文档时回头检查 SKILL.md 里的加载规则有没有对应更新否则新文档永远不会被触发。这套架构的价值不在于文件怎么摆而在于让模型在正确的时机拿到正确的信息——这才是渐进式披露的本质。