DeepSeek Harness学习手册
0/33
阅读路径 / 阶段 2
Chapter 02 · Configuration

配置与形态

模型、Python SDK、插件安装、自动化、多模态与四种运行模式。

6 节 · 约 2.5 小时 · 前置：阶段 1每节含目标 / 前置 / 要点 / 任务 / 自检
本阶段进度 0 / 6
2.1

模型配置：官方、目录与自定义端点

约 35 分钟配置 原文 ↗ 仍然成立
审计依据 ·

提供方类型与存储路径来自教程；模型列表与可用模型以当前端点返回为准。 查看本节审计记录

学习目标

配好官方 + 一个自定义提供方，并说清密钥存在哪里、Provider ID 为什么不能改。

前置知识

完成 1.4；有一个可用的模型端点。

核心要点
  1. 三类提供方：DeepSeek 官方、已安装目录（Anthropic、OpenAI、Kimi、GLM 等）、自定义 OpenAI 兼容端点。
  2. 密钥是只写的，保存在 $DSH_HOME/.credentials.yaml；配置文件只保留凭据引用。
  3. 自定义提供方要填 Provider ID（永久）、baseURL、协议（openai-completions / openai-responses / anthropic-messages）与至少一个模型。
  4. 模型目录可以跟随发布列表，也可以手动维护；自定义视觉模型必须显式声明图片输入，否则发图会在发送前被拒绝。
  5. 推理等级由适配器/目录声明；自定义网关注意 thinkingFormat、supportsDeveloperRole、maxTokensField 等兼容项。
动手任务

配置官方 + 一个自定义提供方。记录：协议、baseURL、模型名、Provider ID。然后故意填错一次 baseURL，观察错误发生在保存、请求还是模型选择阶段。

跟着做

下面是自定义文本模型的配置示例。先在隔离的测试 profile 中操作；gateway.example 和 your-model-id 都是占位值，必须替换。

  1. 从模型设置打开当前 profile 的配置文件，并先备份。
  2. 把示例字段合并到现有 llm-pi-ai 配置；保留已有 providers 与其它字段，不要直接覆盖整份配置。
  3. 让启动 dsh 的进程获得 STUDY_GATEWAY_KEY 环境变量，或通过模型设置保存凭据；密钥不写入示例。
  4. 保存后选中 study-gateway 下的实际模型，发送一条简短文本请求。
cordis.patch.yml · 提供方配置
- id: llm-pi-ai
  config:
    providers:
      study-gateway:
        api: openai-completions
        baseURL: https://gateway.example/v1
        apiKeyEnv: STUDY_GATEWAY_KEY
        models:
          - id: your-model-id
            input: [text]

预期结果

模型选择器中能选中配置的模型，且一次真实请求成功返回。能保存配置本身不代表连接成功。

没有得到预期结果？
  • MISSING_CREDENTIAL：检查启动进程是否获得环境变量，或重新保存凭据。
  • UNKNOWN_MODEL：确认模型 ID 与端点提供的名称完全一致。
  • 连接或协议错误：替换示例地址，核对网关是否提供 Chat Completions 协议。

文档对照： · 官方示例与说明。示例未在你的环境或真实模型端点运行。

自检
Provider ID 为什么不能改？
它会被请求、已保存会话、模型默认值与凭据引用使用；改名会让旧记录找不到提供方。需要改名时，新增一个提供方并删除旧的。
密钥会写进配置文件吗？
不会。真实密钥存 .credentials.yaml，配置里是引用；环境变量与已存凭据同名时，已存凭据优先。
进度保存在本机浏览器
2.2

Python SDK：把 Agent 放进程序

约 40 分钟集成 原文 ↗ 仍然成立
审计依据 ·

PyPI 包存在（0.2.1rc2，requires Python >=3.10）；API 细节以 <code>deepseek_harness</code> 当前类型为准。 查看本节审计记录

学习目标

用 SDK 在 Python 里跑一次任务，并读懂 workspace 与 dsh_home 的隔离。

前置知识

Python 3.10+、Git、一个隔离工作区。

核心要点
  1. 安装：python -m pip install deepseek-harness-sdk；SDK 自带运行时，不需要系统 Node.js。
  2. DeepSeekHarness 是上下文管理器：进入时延迟启动内置运行时，退出时释放；同一个 harness 可以多次 run。
  3. workspace 与 dsh_home 必须是绝对路径；SDK 不会静默读取 ~/.dsh。
  4. 复用同一个 session id 会保留该会话的 Bash 进程，包括工作目录、环境变量与 shell 函数。
  5. 日志落在 $dsh_home/sessions/ 的 JSONL；profile 与插件也保存在 dsh_home 内。
动手任务

跑通仓库的 minimal.py，或写一个 20 行包装。然后检查：生成的 profile 名称、JSONL 路径、第一次与第二次 run 的 Bash 工作目录是否延续。

自检
为什么要隔离 dsh_home？
它保存 profile、插件与会话日志，属于可写状态；用专用目录能避免污染日常配置，也方便测试后整个删除。
session 复用有什么风险？
上一次的 cd、export 与 shell 函数会延续，可能让下一次调用在错误目录或错误凭据下运行。需要干净环境时换 session id。
进度保存在本机浏览器
2.3

插件：查找、安装、验证

约 30 分钟插件 原文 ↗ 仍然成立
审计依据 ·

安装命令与验证思路与教程一致；索引源与插件市场状态会变化。 查看本节审计记录

学习目标

安装一个插件，并用四个检查点验证它真的生效，而不是只看到「安装成功」。

前置知识

完成 1.4；知道 profile 与 bundle 的概念。

核心要点
  1. 基础能力已由当前 profile 提供，不需要为首次任务重复安装文件、Shell、模型接入。
  2. 发现页的索引校验只证明格式有效，不代表官方审核了作者、代码或安全性；安装前核对来源、版本、兼容性。
  3. CLI：dsh plugin --profile web add 包名@版本；只有声明 dsh.bundle 的包才贡献配置层。
  4. 四个验证点：兼容性、配置加载（dump-config）、依赖就绪、实际能力（工具被调用 / UI 完成任务）。
  5. 安装成功不等于已加载；普通依赖可以安装成功，但不会激活任何能力。
动手任务

安装或开发一个 hello 插件，逐项通过四个验证点。然后故意安装一个没有 dsh.bundle 的普通包，确认它只是依赖、没有层标记。

自检
发现页能刷新就安全吗？
不是。索引源只提供标题、作者、版本等元数据；代码是否可信要自己看仓库、权限与构建脚本。
安装后 UI 没入口，先查什么？
先看 dump-config 是否包含该层，再看依赖是否就绪（是否停在 PENDING），最后才看 UI。安装成功不代表加载成功。
进度保存在本机浏览器
2.4

自动化任务：会话级提醒

约 30 分钟自动化 原文 ↗ 仍然成立
审计依据 ·

调度规则与投递语义来自教程；具体保留窗口与 UI 以当前版本为准。 查看本节审计记录

学习目标

创建一个定时提醒，并说清投递语义、时区与不支持的操作。

前置知识

标准 / PTC / 创造模式；模型已配置。

核心要点
  1. 在会话里用一句话创建；模型调用 schedule_create / schedule_list / schedule_update / schedule_delete 四个工具。
  2. 六类规则：After、At、Every、Daily、Weekly、cron；涉及本地时间的规则要带 IANA 时区。
  3. 投递总是回到创建它的会话，不新建会话；宿主关闭时调度停止，重启后补投逾期的一次性提醒或最近一次重复任务。
  4. 没有暂停开关；删除会移除历史，但不会删除原对话；投递不保证恰好一次。
  5. 极简模式没有这些工具与时钟上下文；子代理也被 deny，无法创建提醒。
动手任务

创建一个「每天 23:00 提醒我查看天气」的任务，核对频率与时区；修改一次时间；再删除。记录页面上「已投递」与「已完成」的区别。

自检
为什么模型需要当前时间？
模型本身不知道「现在几点」，没有时钟上下文就无法把「每天晚上 11 点」换算成正确规则；时区也要显式提供。
能把它当 cron 用吗？
不建议。它绑定会话、没有外部通知渠道、不保证执行成功；对外通知类任务应把它当触发器，让 Agent 先检查再执行。
进度保存在本机浏览器
2.5

多模态：图片输入与视觉模型

约 30 分钟多模态 原文 ↗ 存疑待核实
审计依据 ·

视觉模型名、单图 token 上限与 benchmark 数字无法独立确证；以 DeepSeek 官方模型页与 API 文档为准。 查看本节审计记录

学习目标

用视觉模型读一张图表，并知道三种图片传法与输入类型声明。

前置知识

完成 2.1；有一个支持视觉的模型。

核心要点
  1. 图片先被视觉编码器切成 patch 并转成向量，再与文本 token 拼成同一序列；图片会消耗 token。
  2. 三种传法：base64 内联、外部 URL、Files API；分别对应「一次性小图 / 已有图床 / 多次复用」。
  3. 三种 API 风格：Chat Completions、Anthropic Messages、OpenAI Responses；图文混合输入都支持。
  4. 自定义提供方的模型默认按纯文本处理，必须显式勾选图片输入，否则附加图片会在发送前被拒绝。
  5. 多模态不是 OCR 替代品；金额、坐标、表格逐格还原等高风险读数要人工复核。
动手任务

传一张带坐标轴的图表，让它提取 3 个数据点，再追问「你最不确定的读数是哪一个，为什么」。对照你自己读图的结果，记录偏差来源。

自检
为什么一定要声明输入类型？
没有环节能询问端点接受哪些模态，dsh 采取「先声明后使用」；未声明的模型收到图片会在发送前被拒绝。
什么时候该用专用 OCR？
需要精确坐标、逐格还原表格、票据字段抽取时，专用文档解析或 OCR 更稳定、更便宜，也更容易审计。
进度保存在本机浏览器
2.6

四种运行模式：标准 / PTC / 极简 / 创造

约 30 分钟模式 原文 ↗ 存疑待核实
审计依据 ·

「2026 年 8 月开源」等时间与 PTC 并行上限来自教程，未在公开元数据中确证；以官方发布说明为准。 查看本节审计记录

学习目标

为四类任务选择模式，并解释切换模式改变的是插件组合，不是模型权限。

前置知识

完成 1.4。

核心要点
  1. 模式 = 一组预设插件，不是能力等级：标准干活、PTC 编排、极简测量、创造改造。
  2. PTC 把工具收拢为 run_code，模型写一段 TypeScript 程序组合调用；只读调用可并行（教程所称「默认 10 路」待核实，以所用版本为准），写操作按提交顺序。
  3. 极简模式只保留持久 bash 与 str_replace_editor，用于评测模型、复现问题，不是低配电脑的轻量版。
  4. 创造模式继承标准能力，并增加运行时检查、内存中试验插件与 preset 创作指引。
  5. 切换预设不改变文件权限；权限与沙箱是另一套策略，必须单独设置。
动手任务

为四个任务各选一种模式并写一句理由 + 一个风险：修一个 bug、批量重构 20 个文件、比较两个模型的编码能力、给团队做一套自定义预设。

自检
PTC 省的是什么？
省上下文：多步工具调用的中间结果留在程序里，只有返回值与日志回到对话；代价是模型要会写程序，调试也更复杂。
极简模式适合日常吗？
不适合。它是刻意做减法的评测环境，只保留两个工具；日常任务用标准模式，需要编排时再上 PTC。
进度保存在本机浏览器