1. 为什么我要把 DeepSeek Harness 和 TaoToken 放在一起跑DeepSeek Harness下称 dsh是 DeepSeek 官方开源的 Agent 运行框架核心口号是“一切皆插件”。它把模型适配器、工具注册表、会话日志、甚至 Agent 主循环都做成可替换的插件基于内嵌的 Cordis 框架构建。适合谁适合已经会用命令行、想快速跑通一个插件化 Agent 框架、并且希望把模型调用统一到一个 Key 通道上的开发者。我最初跑 dsh 的时候卡点不在插件机制而在模型通道。dsh 默认走 DeepSeek 官方接口但如果你同时还在用别的模型、或者想在一个 Key 下切换多个模型做对比就得反复改配置。TaoToken 在这里的角色是统一 API 通道一个 Key、一个 Base URL兼容 OpenAI 风格的请求格式dsh 的 LLM 适配器只要指向它就能跑通。这篇是入门第一篇目标很具体给你一份可复制的config.toml与settings.json骨架演示一次插件加载加 Agent 调用最后用一条验证请求确认通道连通。版本基线是 dsh v0.1.0-rc.5rc 阶段 API 会变一切以你本地源码为准。2. TaoToken 前置拿 Key、认地址、选对入口在动 dsh 之前先把通道侧的事情做完。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数配置里写错会 404。拿 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。进去之后新建一个 Key复制出来先存到本地环境变量别直接写进会提交到 git 的文件里。这里有个分流建议按你的使用场景选你的场景推荐入口说明只想先验证模型通不通模型对话网页里直接发一条消息确认 Key 有效长期写代码、跑 AgentCoding Plan适合持续调用、多轮工具链要接进 dsh 这类框架API Keys 接入文档拿 Key、看请求格式接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了 Base URL 和鉴权头的写法。我实测下来dsh 的 LLM 适配器只要把baseURL指向https://taotoken.net/api、apiKey填你拿到的 Key就能走通。注意Key 只显示一次丢了就重新建。环境变量名建议统一用TAOTOKEN_API_KEY后面 dsh 配置里直接引用避免明文散落。3. 可复制配置config.toml 与 settings.json 骨架dsh 的配置体系是 Profile → Bundle → Patch 三层叠加。入门阶段你不需要理解全部先照抄下面两份骨架把通道和插件挂上。3.1 config.toml声明模型通道与插件入口在 dsh 的 harness home本机实测是用户目录下的.dsh里建一个config.toml。这份骨架做了三件事声明一个指向 TaoToken 的 LLM 适配器、注册一个最小插件、指定默认 profile。# ~/.dsh/config.toml # dsh v0.1.0-rc.5 基线rc 阶段字段可能变化 [llm] # 默认使用的适配器 id对应下面 [llm.adapters.taotoken] default taotoken [llm.adapters.taotoken] # 统一通道TaoToken 的 API 根地址注意不带 UTM base_url https://taotoken.net/api # 从环境变量读取避免明文写进文件 api_key_env TAOTOKEN_API_KEY # 走 OpenAI 兼容的请求格式 protocol openai # 具体模型名按你控制台里可用的填 model deepseek-chat [plugins] # 插件目录dsh 启动时按顺序加载 dirs [./plugins] [profile] # 默认档案web 会拉起 Web GUI default web关键点api_key_env而不是api_key这样 Key 不进版本库。protocol openai是因为 TaoToken 的请求格式兼容 OpenAI 风格dsh 的适配器缝直接吃这个格式。3.2 settings.json插件与运行期参数有些运行期参数 dsh 走 JSON 配置放在同一个 harness home 下的settings.json。这份骨架声明插件启用状态和一次调用的超时、重试。{ plugins: { enabled: [hello-agent], disabled: [] }, runtime: { requestTimeoutMs: 60000, maxRetries: 2, logLevel: info }, agent: { defaultPreset: default, maxStepsPerTurn: 8 } }maxStepsPerTurn是回合内最多几步入门阶段给 8 够用防止插件写错导致死循环。requestTimeoutMs给 60 秒模型首 token 慢的时候不至于被误判超时。3.3 最小插件hello-agent在./plugins/hello-agent下建两个文件。这是 Cordis 风格的最小插件注册一个工具卸载时自动回收。// plugins/hello-agent/src/index.ts import type { Context } from deepseek-ai/cordis import { defineTool } from deepseek-ai/dsh-tools export const name hello-agent export const inject [tools] export function apply(ctx: Context) { ctx.tools.register( defineTool({ name: hello, description: Return a greeting for the given name., parameters: { name: { type: string, required: true, description: Name to greet } }, output: { schema: { type: string }, render: (_args, value) [{ type: text, text: value }] }, async execute(args) { return hello, ${args.name} } }) ) }// plugins/hello-agent/package.json { name: local/dsh-plugin-hello-agent, version: 0.0.1, private: true, main: src/index.ts, dsh: { plugin: true } }inject [tools]表示这个插件依赖 tools 服务dsh 会保证 tools 先就绪再加载它。ctx.tools.register的返回值就是 disposer插件卸载时工具自动消失不会残留。4. 验证请求跑一次插件加载与 Agent 调用配置写完先别急着开 Web GUI用 headless 方式跑一次输出干净、好排查。4.1 导出 Key 并启动# Linux / macOS export TAOTOKEN_API_KEY你的Key # Windows PowerShell $env:TAOTOKEN_API_KEY你的Key # 用 headless profile 跑一次性任务 npx deepseek-ai/dsh --profile headless 用 hello 工具向 TaoToken 打个招呼如果你已经本地克隆了仓库用仓库内的 CLI 入口也行pnpm dsh --profile headless 用 hello 工具向 TaoToken 打个招呼4.2 期望的成功结果跑通之后终端里应该能看到类似这样的输出Agent 先请求模型模型决定调用hello工具工具返回字符串模型再把结果组织成回复。关键标志有三个一是日志里出现llm/stream相关的事件说明请求确实发到了 TaoToken 的通道二是出现tools/execute且工具名是hello说明插件加载成功三是最终 assistant 消息里包含hello,字样说明整条链路闭环。4.3 单独验证通道连通如果 Agent 调用没跑通先剥离插件单独验证通道。用 curl 直接打 TaoToken 的接口curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: ping}], max_tokens: 16 }返回里有choices字段且内容非空说明 Key 和 Base URL 都对。这一步过了再回头查 dsh 配置问题范围就缩小到插件或 profile 层。5. 本篇常见错排查5.1 401 或鉴权失败最常见的原因是环境变量没导出或者api_key_env写的名字和实际导出的不一致。dsh 读的是环境变量名不是 Key 本身。检查方式echo $TAOTOKEN_API_KEYWindows 用echo $env:TAOTOKEN_API_KEY有输出再启动 dsh。另一个原因是 Key 复制时带了空格或换行重新复制一次。5.2 404 或路径不对Base URL 写成https://taotoken.net/api/带尾斜杠、或者误加了 UTM 参数都会导致路径拼接出错。配置里统一写https://taotoken.net/api不带尾斜杠、不带查询参数。dsh 的适配器会自己拼/v1/chat/completions。5.3 插件没被加载settings.json里enabled数组的名字要和插件package.json的name对应或者和插件目录名对应取决于你的加载器实现。我踩过的坑是目录名写hello_agent、配置里写hello-agent下划线和中划线不一致插件静默不加载。统一用中划线。5.4 工具注册了但模型不调用检查工具的description和参数description是否清晰。模型靠这段描述决定调不调。hello这种工具如果描述写成“do something”模型大概率不调。把描述写具体比如“Return a greeting for the given name”命中率明显提升。5.5 瀑布事件没放行如果你在插件里监听了agent/pre-step或tools/*这类瀑布事件监听器里必须调用next()否则整条链被短路表现为 Agent 卡住不动。这是新手最容易写错的点入门阶段先别碰瀑布事件等第 6 篇展开再说。6. 下一步把通道固定下来再深入插件跑通这一篇之后你手上应该有一个能用的 dsh 环境、一个指向 TaoToken 的统一通道、一个能加载的最小插件。接下来两条路一条是继续深入插件机制看 Profile → Bundle → Patch 三层怎么叠加、--dump-config怎么看清你的插件树另一条是把通道侧固定下来长期编码或跑 Agent 的话用 Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 会更省心不用每次单独配 Key。如果你在接入过程中卡在鉴权或路径上直接翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把 Base URL、鉴权头、请求格式都列清楚了。想先确认模型本身通不通用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息最快。Key 管理统一在 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 建议给 dsh 单独建一个 Key方便按项目排查调用量。下一篇会带你把源码搭建跑通、Web GUI 亮起来并用--dump-config看清你自己的插件树长什么样。
DeepSeek Harness 初探：一切皆插件的 Agent 框架，TaoToken 统一 Key 接入配置骨架
1. 为什么我要把 DeepSeek Harness 和 TaoToken 放在一起跑DeepSeek Harness下称 dsh是 DeepSeek 官方开源的 Agent 运行框架核心口号是“一切皆插件”。它把模型适配器、工具注册表、会话日志、甚至 Agent 主循环都做成可替换的插件基于内嵌的 Cordis 框架构建。适合谁适合已经会用命令行、想快速跑通一个插件化 Agent 框架、并且希望把模型调用统一到一个 Key 通道上的开发者。我最初跑 dsh 的时候卡点不在插件机制而在模型通道。dsh 默认走 DeepSeek 官方接口但如果你同时还在用别的模型、或者想在一个 Key 下切换多个模型做对比就得反复改配置。TaoToken 在这里的角色是统一 API 通道一个 Key、一个 Base URL兼容 OpenAI 风格的请求格式dsh 的 LLM 适配器只要指向它就能跑通。这篇是入门第一篇目标很具体给你一份可复制的config.toml与settings.json骨架演示一次插件加载加 Agent 调用最后用一条验证请求确认通道连通。版本基线是 dsh v0.1.0-rc.5rc 阶段 API 会变一切以你本地源码为准。2. TaoToken 前置拿 Key、认地址、选对入口在动 dsh 之前先把通道侧的事情做完。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数配置里写错会 404。拿 Key 的路径是控制台里的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。进去之后新建一个 Key复制出来先存到本地环境变量别直接写进会提交到 git 的文件里。这里有个分流建议按你的使用场景选你的场景推荐入口说明只想先验证模型通不通模型对话网页里直接发一条消息确认 Key 有效长期写代码、跑 AgentCoding Plan适合持续调用、多轮工具链要接进 dsh 这类框架API Keys 接入文档拿 Key、看请求格式接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面写了 Base URL 和鉴权头的写法。我实测下来dsh 的 LLM 适配器只要把baseURL指向https://taotoken.net/api、apiKey填你拿到的 Key就能走通。注意Key 只显示一次丢了就重新建。环境变量名建议统一用TAOTOKEN_API_KEY后面 dsh 配置里直接引用避免明文散落。3. 可复制配置config.toml 与 settings.json 骨架dsh 的配置体系是 Profile → Bundle → Patch 三层叠加。入门阶段你不需要理解全部先照抄下面两份骨架把通道和插件挂上。3.1 config.toml声明模型通道与插件入口在 dsh 的 harness home本机实测是用户目录下的.dsh里建一个config.toml。这份骨架做了三件事声明一个指向 TaoToken 的 LLM 适配器、注册一个最小插件、指定默认 profile。# ~/.dsh/config.toml # dsh v0.1.0-rc.5 基线rc 阶段字段可能变化 [llm] # 默认使用的适配器 id对应下面 [llm.adapters.taotoken] default taotoken [llm.adapters.taotoken] # 统一通道TaoToken 的 API 根地址注意不带 UTM base_url https://taotoken.net/api # 从环境变量读取避免明文写进文件 api_key_env TAOTOKEN_API_KEY # 走 OpenAI 兼容的请求格式 protocol openai # 具体模型名按你控制台里可用的填 model deepseek-chat [plugins] # 插件目录dsh 启动时按顺序加载 dirs [./plugins] [profile] # 默认档案web 会拉起 Web GUI default web关键点api_key_env而不是api_key这样 Key 不进版本库。protocol openai是因为 TaoToken 的请求格式兼容 OpenAI 风格dsh 的适配器缝直接吃这个格式。3.2 settings.json插件与运行期参数有些运行期参数 dsh 走 JSON 配置放在同一个 harness home 下的settings.json。这份骨架声明插件启用状态和一次调用的超时、重试。{ plugins: { enabled: [hello-agent], disabled: [] }, runtime: { requestTimeoutMs: 60000, maxRetries: 2, logLevel: info }, agent: { defaultPreset: default, maxStepsPerTurn: 8 } }maxStepsPerTurn是回合内最多几步入门阶段给 8 够用防止插件写错导致死循环。requestTimeoutMs给 60 秒模型首 token 慢的时候不至于被误判超时。3.3 最小插件hello-agent在./plugins/hello-agent下建两个文件。这是 Cordis 风格的最小插件注册一个工具卸载时自动回收。// plugins/hello-agent/src/index.ts import type { Context } from deepseek-ai/cordis import { defineTool } from deepseek-ai/dsh-tools export const name hello-agent export const inject [tools] export function apply(ctx: Context) { ctx.tools.register( defineTool({ name: hello, description: Return a greeting for the given name., parameters: { name: { type: string, required: true, description: Name to greet } }, output: { schema: { type: string }, render: (_args, value) [{ type: text, text: value }] }, async execute(args) { return hello, ${args.name} } }) ) }// plugins/hello-agent/package.json { name: local/dsh-plugin-hello-agent, version: 0.0.1, private: true, main: src/index.ts, dsh: { plugin: true } }inject [tools]表示这个插件依赖 tools 服务dsh 会保证 tools 先就绪再加载它。ctx.tools.register的返回值就是 disposer插件卸载时工具自动消失不会残留。4. 验证请求跑一次插件加载与 Agent 调用配置写完先别急着开 Web GUI用 headless 方式跑一次输出干净、好排查。4.1 导出 Key 并启动# Linux / macOS export TAOTOKEN_API_KEY你的Key # Windows PowerShell $env:TAOTOKEN_API_KEY你的Key # 用 headless profile 跑一次性任务 npx deepseek-ai/dsh --profile headless 用 hello 工具向 TaoToken 打个招呼如果你已经本地克隆了仓库用仓库内的 CLI 入口也行pnpm dsh --profile headless 用 hello 工具向 TaoToken 打个招呼4.2 期望的成功结果跑通之后终端里应该能看到类似这样的输出Agent 先请求模型模型决定调用hello工具工具返回字符串模型再把结果组织成回复。关键标志有三个一是日志里出现llm/stream相关的事件说明请求确实发到了 TaoToken 的通道二是出现tools/execute且工具名是hello说明插件加载成功三是最终 assistant 消息里包含hello,字样说明整条链路闭环。4.3 单独验证通道连通如果 Agent 调用没跑通先剥离插件单独验证通道。用 curl 直接打 TaoToken 的接口curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: ping}], max_tokens: 16 }返回里有choices字段且内容非空说明 Key 和 Base URL 都对。这一步过了再回头查 dsh 配置问题范围就缩小到插件或 profile 层。5. 本篇常见错排查5.1 401 或鉴权失败最常见的原因是环境变量没导出或者api_key_env写的名字和实际导出的不一致。dsh 读的是环境变量名不是 Key 本身。检查方式echo $TAOTOKEN_API_KEYWindows 用echo $env:TAOTOKEN_API_KEY有输出再启动 dsh。另一个原因是 Key 复制时带了空格或换行重新复制一次。5.2 404 或路径不对Base URL 写成https://taotoken.net/api/带尾斜杠、或者误加了 UTM 参数都会导致路径拼接出错。配置里统一写https://taotoken.net/api不带尾斜杠、不带查询参数。dsh 的适配器会自己拼/v1/chat/completions。5.3 插件没被加载settings.json里enabled数组的名字要和插件package.json的name对应或者和插件目录名对应取决于你的加载器实现。我踩过的坑是目录名写hello_agent、配置里写hello-agent下划线和中划线不一致插件静默不加载。统一用中划线。5.4 工具注册了但模型不调用检查工具的description和参数description是否清晰。模型靠这段描述决定调不调。hello这种工具如果描述写成“do something”模型大概率不调。把描述写具体比如“Return a greeting for the given name”命中率明显提升。5.5 瀑布事件没放行如果你在插件里监听了agent/pre-step或tools/*这类瀑布事件监听器里必须调用next()否则整条链被短路表现为 Agent 卡住不动。这是新手最容易写错的点入门阶段先别碰瀑布事件等第 6 篇展开再说。6. 下一步把通道固定下来再深入插件跑通这一篇之后你手上应该有一个能用的 dsh 环境、一个指向 TaoToken 的统一通道、一个能加载的最小插件。接下来两条路一条是继续深入插件机制看 Profile → Bundle → Patch 三层怎么叠加、--dump-config怎么看清你的插件树另一条是把通道侧固定下来长期编码或跑 Agent 的话用 Coding Plan 入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 会更省心不用每次单独配 Key。如果你在接入过程中卡在鉴权或路径上直接翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把 Base URL、鉴权头、请求格式都列清楚了。想先确认模型本身通不通用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息最快。Key 管理统一在 API Keys 页面 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 建议给 dsh 单独建一个 Key方便按项目排查调用量。下一篇会带你把源码搭建跑通、Web GUI 亮起来并用--dump-config看清你自己的插件树长什么样。
