DeepSeek Harness SDK 怎么接：Python SDK、HTTP API 与网关三类入口

DeepSeek Harness 的开发者入口有三类：Python SDK、Typert 网关、CLI 进程调用。 它们面向的对象不同；选错入口，会在不该写代码的地方写代码，或在该用 SDK 的地方拼命令。

三个入口分别给谁

先看对象：你要驱动会话、写插件，还是跑脚本。

SDK 面向「程序调用」，Typert 网关面向「插件内部」，CLI 面向「一次性动作」。 在 Python 里创建会话、发消息、读结果，适合自动化与集成（来源）；网关解决 Host 与 Client 之间的方法暴露，不是对外 HTTP API，写插件 UI 时才会碰到；CLI 负责安装、启动、管理插件与跑命令，脚本里最省依赖。

Python SDK：最小可跑

SDK 的价值是结构化，不是替代 CLI。 先跑通最小示例，再加业务。

1. 安装 SDK：pip install deepseek-harness-sdk。
2. 准备运行环境与 DSH_HOME，确认目录可写。
3. 用 DeepSeekHarness 上下文管理器启动 sdk-minimal profile。
4. 创建一个会话，发一条测试消息。
5. 读取返回结果，确认会话日志落到 DSH_HOME/sessions 的 JSONL。

sdk-minimal 是刻意做小的 profile。 它减少插件与工具依赖，适合脚本化调用；需要完整能力时再换 profile。

日志是排查入口。 请求没回来、结果不完整，先看 JSONL 里的记录，比在代码里打印更可靠。

Typert 网关：插件前后端通信

网关不是对外接口，而是插件内部的桥。 理解它，才能写带界面的插件。

1. 在 Host 侧服务方法上加 @Remote 或 @RemoteScope，选择暴露范围。
2. 用 TypertLookupMap 声明 Host 对象与 wire identity 的关联。
3. 在 Client 侧通过生成的调用入口访问，不要手写协议。
4. 只暴露必要方法；暴露面越大，权限与安全风险越高。
5. 用日志确认调用是否到达 Host，区分「没调用」与「调用被拒」。

@Remote 控制「能不能被调用」，@RemoteScope 控制「在哪个范围可见」。 两者一起用，才能既可用又不越界（来源）。

不要把它当 REST 用。 它没有公开的 HTTP 路径与状态码语义；按插件机制理解，才不会写出脆弱代码。

CLI 进程调用：脚本与 CI

脚本里最稳的是「调用命令 + 看退出码」。 依赖少，行为可预测。

1. 用 dsh --version 确认环境可用。
2. 用 dsh plugin --profile web list 确认插件状态。
3. 需要触发任务时，调用对应命令并捕获退出码。
4. 需要结构化输出时，解析标准输出或改用 SDK。
5. 在 CI 里固定版本，避免每次拉到不同版本。

CI 里不要依赖交互式提示。 需要确认的操作要加非交互参数；否则流水线会卡在等待输入。

退出码是契约。 0 与非 0 代表成功与失败；不要只匹配输出文字，文字会随版本变化。

鉴权与超时

三个入口的鉴权方式不同，超时策略也要分别设。

1. SDK： 模型密钥通过环境变量或配置提供，不要写死在代码里。
2. 网关： 走宿主内部权限，不额外做 Token；但仍要控制暴露方法。
3. CLI： 复用本地配置与登录态；CI 里用环境变量注入，避免明文。
4. 超时： SDK 设置请求级超时；CLI 用进程超时兜底；网关调用设置调用级超时。
5. 重试： 只对可重试错误做有限重试，避免放大故障。

密钥不进代码库，超时也要分层。 环境变量、密钥管理服务、CI Secret，三种方式都比明文好。单次请求、整段任务、进程总时长三层各设上限；只设一层，容易在长任务里误杀。

错误码与日志

三个入口的错误表现不同，但排查都从日志开始。

先区分「没调用」与「调用失败」。 前者看入口配置，后者看错误内容；混在一起会改错地方。

日志要带上下文。 会话 ID、profile、版本号三样齐了，问题才能复现；只记一句「失败了」没有用。

选型表

按「谁在调用、要什么结果、能接受多少依赖」选。

能用 CLI 解决就不要上 SDK。 代码越多，维护成本越高；需要结构化与复用性时再用 SDK。

写插件才用网关。 它不是对外集成入口；拿它做外部调用，会把内部机制当公共 API。

下一步

先定入口，再写最小示例。 想看 Python SDK 的完整配置，看《DeepSeek Harness 怎么用 Python 调用》；想理解 @Remote 机制，看《DeepSeek Harness API 网关是什么》；想写第一个插件，看《照着插件市场写第一个 DSH plugin》。

来源：DeepSeek Harness 官方文档、dsh CLI README、deepseek-harness 仓库