DSH Development

任务路由

离线中文副本与路径映射：docs-official/INDEX.md。官方全文克隆：/Users/apple/dev/deepseek-harness/docs/。DSH 已开源：deepseek-ai/deepseek-harness（MIT，基于 Cordis，"Everything is a Plugin"）· 文档站。

快速开始

// lib/index.js — 最小工具插件
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'my-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_tool',
    description: 'What this tool does.',
    parameters: { arg: { type: 'string', required: true, description: '...' } },
    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
    async execute(args, exec) { return `result: ${args.arg}` },
  }))
}

注册分两条路（详见 plugins.md）：

工作流：写 apply → 按上表注册 → 按重启规则判断是否重启 → 会话调工具 / curl 路由复验（troubleshooting.md）。

原型阶段：dsh web --patch ./scratch-plugin/cordis.yml，patch 里 name 用绝对路径；验证通过后打包 bundle 再 plugin add。

重启 TL;DR

完整表、curl 验证宿主路由、settings 假成功 → restart.md。

Cordis 五概念（展开见 cordis.md）

DSH 版本与文档路由（防 API 腐化）

DSH 处于开发者预览期、持续发版（rc.1 → rc.2 → …），skill 静态参考必然滞后于已安装版本。铁律与机制：

1. API 实证协议：任何 ctx.* API 用法，先对照本机已安装源码验证（<DSH安装根>/node_modules/@deepseek-ai/<pkg>/ 的 README + 源码），或真机探针；skill 文本与安装源码冲突时以源码为准，并回写修正 skill。实测教训：ctx.settings.register 在教程里存在、在 rc.1/rc.2 里都不存在，mock 测试测不出，只有真机暴露。
2. 快照按版本路由：references/snapshots/dsh-<version>.md 记录各版本的 API 面（服务方法、事件、探针结果）。开工先 dsh --version：
   • 对应快照存在 → 读它，并留意文中标注的探针差异；
   • 不存在 → node tools/api-snapshot.mjs --out references/snapshots/dsh-<version>.md 现场生成（自动探测本机 DSH，或 --dir 指定安装根/容器内安装根）。
3. 快照 ≠ 上游原版：宿主侧打过补丁的安装（如 plugin-manager 的 -w）会进快照，标注「本机打过补丁」的行以上游 tarball 复核为准。

高频坑（展开见 troubleshooting.md）

• duplicate loader entry id：bundle 已 plugin add，patch 又 insert 同一 id → 只保留 - id: 改 config。
• GitHub 包名 alias：dependencies 键须与 bundle patch 的 name: 一致；bundles 只列一份。
• 升级后首页 400：profiles/node_modules 仍链旧 dsh → pnpm install + 查 dsh-host-webserver 软链。
• 宿主包被插件遮蔽：外部插件 import 的 @deepseek-ai/dsh-* 不应放在 dependencies；放入 peerDependencies，并以相同版本镜像到 devDependencies，详见 dependencies.md。
• 官方插件显示为“已安装”：先区分安装目录提供的 optional bundle 与 profile 的直接依赖；不要为安装目录已经提供的官方 bundle 再 pnpm add 到 profile。
• 卸载后仍有插件痕迹：同时检查 profile package.json、lockfile、dsh.profile.bundles、node_modules 链接和 --dump-config，再重启验证；不要只看 pnpm remove 的退出码。
• ctx.settings.register 不存在（真机必炸）：rc.1/rc.2 无此 API，照旧文档写宿主半区拒绝激活（mock 测不出）；真实接缝 = 插件自有路由 + ctx.settings.update(ctx.fiber.entry?.options.id, patch) + 可写字段 .volatile()（schemastery ≥3.18.4）→ client-ui.md。
• hybrid 插件 GUI 安装后不激活：无 dsh.bundle 的包经插件管理器只落普通依赖，宿主半区不挂载——package.json 必须声明 dsh.bundle.patch（plugins.md）。
• ERR_PNPM_ADDING_TO_ROOT（装插件）：profile 是 pnpm workspace root 而 plugin-manager 不带 -w（rc.1/rc.2 均如此）——CLI 加 -w 或宿主侧打补丁；GitHub spec 走 ssh 报 Host key verification 就 insteadOf 重写 https（troubleshooting.md）。
• 设置保存假成功：第三方 settingsScope 被白名单拒 → 走插件自有路由 + 宿主 ctx.settings.update(entry.options.id, patch)（client-ui.md）。
• curl 200 HTML：未注册路由回退 SPA 首页 → 看 content-type 是否为 application/json。
• agents.create 不传 setup = 空全局层：meta.agentPreset 只写 header 不挂载（创建成功不报错、无 bash/fs/skill）；必须 setup: (agentCtx) => ctx.agentPresets.mount(agentCtx, id?)，验证看会话日志 request/header 实际工具清单 → architecture.md。

本机环境（摘要）

完整表、参考插件路径 → environment.md。