DeepSeek Harness 研究理念：用 CLI 构建可复现的 Agent Runtime 实验-北京尧图网络

1. 为什么我要用 CLI 拆解 DeepSeek Harness 的 Agent RuntimeDeepSeek Harness 是一套开源的 Agent Runtime 工程底座它把模型推理之外的所有事情——工具调度、会话状态、权限控制、沙箱隔离、失败恢复、插件扩展——都收进了一个可运行、可观测、可复现的系统里。它适合谁适合那些不满足于“调个 API 写个 prompt”的开发者尤其是想系统验证 Agent 行为、需要做对照实验、要把 Agent 从 demo 推进到工程系统的人。我关注它不是因为它多了一个 CLI 界面而是因为它把“模型之外的世界”暴露成了可研究的对象一次运行里模型看到了什么上下文、哪些工具被允许调用、工具结果和错误如何回流到下一轮推理、进程重启后状态怎么恢复、新能力挂在哪个扩展点。这些问题单靠 prompt 永远解决不了必须靠 Runtime 来回答。而 CLI 是研究 Runtime 最合适的入口。Web 界面会隐藏装配细节SDK 封装会吞掉中间状态只有 CLI 能把 Profile、Bundle、Patch、Loader、Agent Loop、Session Event Log 这些环节一层层摊开给你看。你可以用一条命令启动用固定输入跑出固定输出改一个参数再跑一遍对比差异。这就是“可复现实验”的最小闭环。我试过用不同 Runtime 参数跑同一组输入发现输出差异往往不来自模型本身而来自上下文裁剪策略、工具可见性、权限决策和会话恢复逻辑。这些才是 Agent 行为的关键变量。所以这篇不是产品评测而是一份可跟做的 CLI 实验手册从环境准备到配置片段从运行命令到结果对比再到常见报错排查全部围绕“可复现”三个字展开。核心检索词先明确DeepSeek Harness 研究理念、Agent Runtime 可复现实验、CLI 配置、固定输入对比输出。下面所有步骤都服务于这个目标。2. TaoToken 前置把模型接入层固定下来做可复现实验第一件事是把模型接入层固定住。如果每次实验换一个模型供应商、换一个 endpoint、换一套鉴权方式那输出差异里就混入了太多无关变量实验结论不可信。我的做法是用 TaoToken 作为统一的模型接入层把 Base URL、API Key、Model ID 三件套写进配置文件让 Runtime 只认这套配置。TaoToken 在这里的角色是“模型网关”它提供 OpenAI 兼容的接口你可以在 CLI 里把 base_url 指向https://taotoken.net/api然后用同一个 Key 切换不同模型做对照。这样 Runtime 层的实验变量上下文策略、工具权限、会话恢复和模型层的变量模型能力就能分开控制。你需要先拿到 API Key。访问 API Keys 管理页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建一个 Key 并保存好。注意这个 Key 只显示一次丢了只能重建。然后确认你要用的 Model ID。不同模型在工具调用、长上下文、指令遵循上的表现差异很大做 Agent Runtime 实验时建议先固定一个模型把 Runtime 变量跑清楚再换模型对比。模型列表和对话测试可以在模型对话页面验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 先发一条简单消息确认 Key 和网络都通。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 endpoint 说明和参数格式。如果你打算长期跑编码类 Agent 实验Coding Plan 页面值得看一下https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对高频编码场景做了额度优化。这一步的目标不是“注册账号”而是把模型接入层变成一个常量。常量固定了实验才有意义。接下来所有 CLI 配置都会引用这套 Base URL Key Model ID。3. 可复制配置CLI 环境与 Runtime 参数文件这一节给出可以直接复制的配置片段。路径和字段名按实际工程习惯来你按自己的目录结构调整即可。核心原则是所有影响 Agent 行为的参数都写进配置文件不靠命令行临时传参这样每次实验的配置可以版本化、可以 diff、可以复现。先建实验目录mkdir -p ~/agent-lab/{configs,runs,logs} cd ~/agent-lab第一个配置文件是模型接入层命名为configs/model.toml[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_id deepseek-chat timeout_seconds 120 max_retries 2 [provider.headers] Content-Type application/json注意api_key_env指向环境变量不要把 Key 明文写进文件。设置环境变量export TAOTOKEN_API_KEYsk-你的Key第二个配置文件是 Runtime 实验参数命名为configs/runtime.toml[runtime] profile headless session_log runs/session.jsonl max_turns 12 context_window 32000 compaction_threshold 0.75 [tools] enabled [read_file, write_file, run_shell, search] shell_timeout 30 sandbox true [policy] require_approval [run_shell, write_file] auto_approve [read_file, search] [reproducibility] seed 42 temperature 0.0 top_p 1.0 fixed_system_prompt configs/system.md第三个文件是固定输入命名为configs/system.md内容保持简短且稳定你是一个实验用 Agent。只使用被允许的工具。每次工具调用前说明理由。遇到不确定时停止并报告。第四个文件是实验任务输入命名为configs/task.json{ task_id: exp-001, input: 读取 runs/input.txt统计行数把结果写入 runs/output.txt, expected_tools: [read_file, write_file], max_turns: 6 }如果你用的是 Claude Code 或类似 CLI 工具做接入实验配置结构会略有不同但三件套不变Base URL 指向https://taotoken.net/apiKey 走环境变量Model ID 固定。Claude Code 接入可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。配置写完后用一条命令校验 TOML 语法python3 -c import tomllib; tomllib.load(open(configs/runtime.toml,rb)); print(runtime.toml OK) python3 -c import tomllib; tomllib.load(open(configs/model.toml,rb)); print(model.toml OK)两个都输出 OK 再往下走。配置文件有语法错误时Runtime 启动会直接失败报错信息通常指向行号按行号改即可。4. 验证请求固定输入跑出可对比结果配置就绪后跑第一次实验。准备输入文件printf alpha\nbeta\ngamma\ndelta\n runs/input.txt wc -l runs/input.txt预期输出4 runs/input.txt。然后启动 Runtimedsh --profile headless \ --config configs/runtime.toml \ --model-config configs/model.toml \ --task configs/task.json \ --log runs/exp-001.jsonl如果你的 CLI 参数名不同以dsh --help为准。关键是三个东西都要传进去Runtime 配置、模型配置、任务输入。运行结束后检查输出cat runs/output.txt cat runs/exp-001.jsonl | head -20output.txt应该包含行数统计结果。exp-001.jsonl是会话事件日志每一行是一个事件包含 turn 编号、模型请求、工具调用、工具结果、策略决策。这个日志是可复现实验的核心证据它记录了模型看到了什么、调用了什么、被允许或拒绝了什么。现在做对照实验。复制一份配置只改一个参数cp configs/runtime.toml configs/runtime-no-sandbox.toml sed -i s/sandbox true/sandbox false/ configs/runtime-no-sandbox.toml再跑一次dsh --profile headless \ --config configs/runtime-no-sandbox.toml \ --model-config configs/model.toml \ --task configs/task.json \ --log runs/exp-002.jsonl对比两次日志diff (jq -S . runs/exp-001.jsonl) (jq -S . runs/exp-002.jsonl) | head -40你会看到沙箱开关影响了工具执行路径和策略决策事件。如果两次输出完全一致说明这个参数在当前任务下没有触发差异换一个会触发沙箱的任务再试。可复现性的验证方法是同一份配置连续跑三次日志中除时间戳外的字段应完全一致。把时间戳字段排除后再 difffor i in 1 2 3; do dsh --profile headless --config configs/runtime.toml \ --model-config configs/model.toml --task configs/task.json \ --log runs/repro-$i.jsonl done diff (jq -S del(.timestamp) runs/repro-1.jsonl) (jq -S del(.timestamp) runs/repro-2.jsonl)没有输出就说明可复现。有输出就检查temperature和seed是否真的生效有些 Runtime 会把这两个参数透传给模型有些会在本地做采样行为不同。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth实验过程中最容易卡住的不是 Runtime 逻辑而是接入层报错。下面按真实报错逐条排查。401 Unauthorized。最常见原因是 Key 没设进环境变量或者设了但当前 shell 没生效。检查echo $TAOTOKEN_API_KEY | head -c 8如果输出为空说明环境变量没设。重新 export 后确认。如果输出有值但仍 401检查 Key 是否被删除或过期去 API Keys 页面重建https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。还有一种情况是配置文件里写了api_key字段但值为空字符串覆盖了环境变量检查model.toml里不要出现空的api_key。local proxy failed。这个报错通常出现在 Runtime 尝试通过本地代理转发请求时。检查你的base_url是否被错误地写成了http://localhost:xxxx或某个本地端口。正确值应该是https://taotoken.net/api。另外检查环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY指向不可用的地址env | grep -i proxy如果有unset 掉再跑。注意不要使用任何非官方的网络转发工具直接用官方 endpoint 即可。Error reading choices / reading choices。这个报错说明 Runtime 收到了响应但解析choices字段失败。常见原因是响应体不是预期的 JSON 结构可能是 endpoint 路径写错比如漏了/v1或多了/v1也可能是模型返回了流式格式但 Runtime 按非流式解析。检查你的请求路径TaoToken 的兼容接口基址是https://taotoken.net/api具体路径以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。先用 curl 单独验证一次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:8} | jq .choices[0].message.content如果 curl 能拿到结果但 Runtime 报 reading choices说明 Runtime 的解析逻辑和实际响应格式不匹配检查 Runtime 版本和配置里的stream字段。OAuth 相关报错。如果你用的是 Claude Code 类工具它可能默认走 OAuth 流程而不是 API Key。这时需要在配置里显式指定 API Key 模式把 Base URL 指向https://taotoken.net/api并在 settings 里关闭 OAuth。Claude Code 的接入配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。三件套必须写全Base URL、Key、Model ID缺一个都会回退到默认 OAuth 或报鉴权失败。排查顺序建议先 curl 验证接入层再跑 Runtime 最小任务最后加实验参数。接入层不通的时候不要动 Runtime 配置否则会把两个问题混在一起。6. 把实验变成习惯从 CLI 到可复现的 Agent Runtime 研究跑通一次对照实验之后真正有价值的是把实验流程固定下来。我的做法是每个实验一个目录目录里放四样东西配置文件、任务输入、运行日志、结论笔记。配置文件进 git日志不进 git 但保留最近若干次结论笔记记录“改了什么参数、观察到什么差异、是否可复现”。具体操作上写一个run.sh把启动命令封装起来#!/usr/bin/env bash set -euo pipefail EXP_ID${1:?usage: run.sh exp-id} mkdir -p runs/$EXP_ID dsh --profile headless \ --config configs/$EXP_ID/runtime.toml \ --model-config configs/model.toml \ --task configs/$EXP_ID/task.json \ --log runs/$EXP_ID/session.jsonl每次实验复制一份配置目录改参数跑对比。这样实验之间不会互相污染回看时也能清楚知道每个结论对应哪份配置。验证可复现性的标准流程是三步同一配置跑三次排除时间戳后日志一致改一个参数再跑差异只出现在与该参数相关的字段换回原配置结果回到第一次的状态。三步都通过这个实验结论才可信。如果你要长期做 Agent Runtime 研究建议把模型接入层单独抽出来管理用环境变量或独立的 secrets 文件不要和 Runtime 实验配置混在一起。TaoToken 的 API Key 管理页面可以创建多个 Key 用于不同实验线https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。需要验证模型行为时用模型对话页面快速测试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 。最后一步是闭卷复述关掉所有文档用自己的话解释一次运行里 Profile 怎么装配、Agent Loop 怎么流转、Session Event Log 记了什么、工具权限在哪一层决策。讲不清楚的地方就是下一轮实验要补的洞。CLI 只是入口可复现的实验流程才是研究 Agent Runtime 的真正方法。

DeepSeek Harness 研究理念：用 CLI 构建可复现的 Agent Runtime 实验

相关推荐

Manus Metaglove数据手套遥操作Tesollo机械手：调试成功视频背后的配置复盘

LangChain 与 LangGraph 实战入门：从链式调用到图状态编排

嘉立创PCB产品介绍二维码制作教程（零废话）

更多资讯

Windows Codex Computer Use 电脑操控问题修复

OpenShell 深度解析：Windows 开始菜单与任务栏定制框架的部署与实战

Superpowers安装指南：用可视化IDE快速构建Chrome扩展

智能体skills工程化实践：GKE部署、Workload Identity权限与OpenAPI契约

STM32控制板结构解析：从最小系统到外设引脚映射

day45复盘：业余时间从零开发并上线每日计划复盘Web工具

今日更新

基于sEMG与IMU的手语手势识别：从数据采集到实时部署避坑指南

装配车间MES落地指南：SimpleMES工单流转、BOM与齐套检查实战

AI获客怎样减少重复线索？意客AI的原文复用与版本筛选

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？