企业官网建设流程全解析

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.5，rc 阶段 API 会变，一切以你本地源码为准。

2. TaoToken 前置：拿 Key、认地址、选对入口

在动 dsh 之前，先把通道侧的事情做完。TaoToken 的官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api ，注意这个地址后面不加任何 UTM 参数，配置里写错会 404。

拿 Key 的路径是控制台里的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。进去之后新建一个 Key，复制出来先存到本地环境变量，别直接写进会提交到 git 的文件里。

这里有个分流建议，按你的使用场景选：

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面写了 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_KEY（Windows 用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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 会更省心，不用每次单独配 Key。

如果你在接入过程中卡在鉴权或路径上，直接翻接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面把 Base URL、鉴权头、请求格式都列清楚了。想先确认模型本身通不通，用模型对话 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 发一条消息最快。Key 管理统一在 API Keys 页面 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，建议给 dsh 单独建一个 Key，方便按项目排查调用量。

下一篇会带你把源码搭建跑通、Web GUI 亮起来，并用--dump-config看清你自己的插件树长什么样。