实测避坑笔记dshworks/howto-dsh

howto-dsh

关于 DeepSeek Harness（dsh，DeepSeek 的 agent harness）的经核实实地笔记。陷阱、技能、钩子、配置文件。

这里的每一条断言都经过真实运行验证，并附有源码路径，以便你重新核实。 每个页面都注明了其验证所依据的版本和日期；本 README 的笔记来自 0.1.0-rc.5（2026-08-13），下面的页面来自 0.1.0-rc.6（2026-08-15）。2026-08-25 针对 dsh-v0.1.1-rc.2 进行了结构性复查：全部 32 条引用的源码路径仍然可解析，陷阱 9 和 10 已重新运行 — 10 不再复现，并已在原处说明。行为类陷阱尚未针对 rc.2 重新运行，仍保留其原始日期；只升版本号而不做这件事，就是那种不诚实的半吊子做法。dsh 是开发者预览版，团队承诺会有破坏兼容性的变更，所以请把这里的一切视为有日期的，而非永恒的。

欢迎提交带核实修正的 PR。与 DeepSeek 无隶属关系。

AI agents / LLMs：组织索引位于 dsh.works/llms.txt。

页面

start/ — 每篇一次坐定读完，运行每一条命令。

| | English | 中文 |
|---|---|---|
| 你的第一个小时：启动、一个有两个失败测试的真实仓库、diff、轨迹、账单 | first-hour.md | first-hour.zh.md |
| 从 Claude Code 或 Codex 过来：哪些能沿用、哪些被改名、哪些根本不存在 | coming-from-claude-code.md | coming-from-claude-code.zh.md |

fix/ — 每页一个症状，写之前先复现。

| | English | 中文 |
|---|---|---|
| 启动失败，满屏 AggregateError | boot-fails-with-a-wall-of-aggregateerror.md | .zh.md |
| 每个 /api/ 请求都返回 403 | every-api-call-returns-403.md | .zh.md |

build/（编写插件）和 run/（为他人运行 dsh）是接下来的两条线。它们目前是空的；这张表就是本仓库的诚实状态。

0.1.0-rc.8 中的变更

0.1.0-rc.8 于 2026-08-19 发布，比上面的页面晚两个版本。以下四条笔记是从 rc.8 源码树中读出的，而非在机器上重新运行——这一区别正是本仓库的全部意义所在，所以它被明说而非含糊带过。这些页面本身仍写着 rc.6，直到有人重新运行它们。

- dsh web 现在会打开你的浏览器。 它会等待整个 Loader 树稳定下来，然后把规范主机 URL 交给操作系统。--no-open 可将其关闭，而非空的 SSH_CONNECTION 或 SSH_TTY 会自动抑制它，因为在 SSH 下，转发地址属于你的客户端。交接失败会打印原因，并让服务器继续运行。
（apps/cli/reference/README.md）
- Claude Code 和 Codex 子代理现在是独立的可选 Bundle。
dsh plugin --profile  add @deepseek-ai/dsh-subagent-codex —— 以及那个陷阱：bundle 成员关系在 Profile 启动时就固定了。 添加或移除一个 bundle 会改变磁盘上的 manifest，而正在运行的 Profile 仍保留它启动时的那一组，因此你必须重启该 Profile。对 Profile 或主目录 cordis.patch.yml 的普通编辑仍会热重载；这一个不会。下次启动时每个 Bundle 会注册一个休眠*的 provider，而复制过来的 Preset 仍然必须自己启用匹配的工具行。
（apps/cli/reference/README.md、packages/subagent/subagent-claude-code/README.md）
- SubagentReportDelivery 将 'wakeup' 重命名为 'next-step'，语义也随之改变：它现在使用 Agent.steer()，唤醒空闲的父级或加入正在运行的父级最近的一步边界。任何传入字符串 'wakeup' 的代码都会失效。（docs/subsystems/subagent.md）
- SQLite 会话存储的格式发生了不兼容变更，涉及读、写和 fork 性能。在升级一台有你关心的会话的机器之前，先为此做好预算。（release notes；docs/subsystems/persistence.md）

下面这些页面依赖的两件事在 rc.6 和 rc.8 之间没有变动，已逐文件核对：/api 浏览器信任围栏（packages/client/connection/src/{index,api-request-trust,loopback-hostname}.ts 逐字节相同）以及 docs/user/develop/basic/publish.md 中的 bundle 与普通依赖规则。因此下面的 403 页面和组合模型仍然成立。

60 秒上手

npx @deepseek-ai/dsh web

Web UI 会在 http://127.0.0.1:3080 启动——从 rc.8 起，除非你传入 --no-open，否则会在你的浏览器中打开。在 Settings > Models 中设置 API key（热应用，无需重启）。要在不启动的情况下对组合做健全性检查：dsh --profile  --dump-config。

何时使用，何时跳过

当某个教程失败而你怀疑其底层的 harness 发生了变化时，或者在你发布第一个 bundle 之前，请使用这些笔记。如果你想要稳定的参考文档，请跳过它们：那是官方文档的职责，这里的任何内容都不保证在其每项声明所验证的版本之后仍然有效。

30 秒看懂组合模型

- 一切都是 Cordis 插件。bundle 是你编写和分发的东西（package.json 中带 dsh.bundle 的 npm 包）；profile 是用户启动的东西（dsh --profile ）。没有东西两者兼具。
- Patch 层按顺序应用：bundle patches，然后是 profile cordis.patch.yml，然后是 $DSH_HOME/cordis.patch.yml，然后是每个 --patch 标志。按行后者胜出。

陷阱
1. .dsh-plugin 清单格式已废弃。 于 2026-08-09 移除，且无迁移方案（.agents/notes/implemented/simplification/2026-08-09-remove-repository-plugin.md）。任何教授 .dsh-plugin 或 dsh-plugin-prepare 的教程都早于此次移除。当前路径：package.json 中的 dsh.bundle.patch。
2. --patch 路径必须是绝对路径。 相对路径会失败（docs/user/develop/basic/index.md）。
3. Git 安装会在安装时于你的机器上执行代码，且不受任何沙箱限制。 文档原文如此。作者必须提供 prepare 脚本；用户必须通过配置文件 pnpm-workspace.yaml 中的 allowBuilds 将构建加入允许列表，并应固定提交 SHA（docs/user/develop/basic/publish.md）。这并非边缘情况：在 awesome-dsh-plugins 于 2026-08-13 验证的 18 个 bundle 格式插件中，只有 4 个在 npm 上；其余均通过 dsh plugin --profile  add github:owner/repo 安装（#path:/subdir 后缀可访问 monorepo 子包）。
4. 补丁会替换某一行的整个 config，不会进行深度合并。 覆盖一个字段意味着要重新声明该行的整个配置。
5. 没有 dsh.bundle 的包会作为普通依赖安装，不会激活任何层；你会收到警告，而不是错误。
6. cordis.yml YAML 标签： !!js 仅允许出现在插件的 config 和条目的 disabled 下。绝不能使用 !js，也绝不能出现在其他位置。
7. 仓库描述滞后于迁移；请以清单为准。 2026-08-13 在实际环境中发现：AshesofPlato/whale-girl 的描述仍在教授已移除的 .dsh-plugin + config.yaml 安装方式，而该仓库本身已迁移到 dsh.bundle（其 README 通过 dsh plugin add github:... 安装）。请对照 package.json 验证，而不是仓库卡片。
8. dsh.plugin.json 不是 harness 清单。 omdsh-dev 插件系列在每个仓库根目录都附带一个；harness 源码中没有任何内容读取该文件。它是供 better-sidebar 自身标签注册表使用的第三方元数据。真正的安装路径仍然是 package.json 中的 dsh.bundle。
9. npm 版本在 monorepo 中碎片化。 这一点仍然成立，且有更新的数据 — 于 2026-08-25 重新核查：harness 标签 dsh-v0.1.1-rc.2 与 @deepseek-ai/dsh 在 0.1.1-rc.2 上匹配，但 @deepseek-ai/dsh-agent 仍停留在 0.1.0-rc.6，落后四个版本。（首次记录于 2026-08-13，对照标签 0.1.0-rc.5，当时 dsh 本身显示为 0.0.1-rc.5。）请将兼容性声明锚定到 harness 发布标签，而不是 npm 显示给你的某个依赖版本。
10. 最新发布版本并不是 npx 安装的版本。 截至 2026-08-25 未复现 — npm view @deepseek-ai/dsh dist-tags 现在返回 { latest: '0.1.1-rc.2', next: '0.1.1-rc.2' }，因此 latest 就是最新发布版本，npx 给你的就是它。保留此条是因为它至少真实存在过一天，而且导致它的机制并未消失：一次仅发布到 next 的操作只差一个发布脚本的决策，仓库中没有任何东西阻止它。下面的检查仍然是应当运行的真实检查。
检查于 2026-08-20：@deepseek-ai/dsh 已发布 0.1.0-rc.8 —— 位于 next dist-tag 上，自 2026-08-19 起 —— 而 latest 仍指向 0.1.0-rc.7。因此，在 rc.8 已有发布说明、GitHub 标签和变更日志的那一天，npx @deepseek-ai/dsh 给你的却是 rc.7。阅读公告的插件作者和运行安装命令的用户处于不同版本。npm view @deepseek-ai/dsh dist-tags 是“我会得到什么”的唯一诚实答案；如果你指的是 rc.8，请显式使用 @next。

技能：Claude 兼容

dsh 读取 Anthropic 格式的 SKILL.md 技能，因此为 Claude Code 编写的技能可以原样使用。发现根目录，按优先级从高到低排列（packages/skill/skill-filesystem/README.md）：

| 优先级 | 路径 |
|---|---|
| 100 | /.dsh/skills |
| 200 | /.agents/skills |
| 300 | Config.customSkillDirs |
| 400 | /skills |
| 500 | ~/.agents/skills（或 $DSH_AGENTS_HOME） |

规则：/SKILL.md 目录包或扁平的 .md 文件；不进行嵌套发现。Frontmatter 需要 name + description（可选的 whenToUse、disable-model-invocation、user-invocable）。名称必须是 kebab-case；camelCase 名称会静默丢弃整个技能。根目录会被实时监视；在会话中途编写的技能会立即出现。

带上你的 Claude Code hooks

dsh 附带一个官方桥接，可忠实运行现有的 hooks.json：

- dsh-hooks-claude-code:
configPath: ./.claude/hooks.json
pluginRoot: ./.claude/plugins/my-plugin
projectDir: .

支持的事件映射到 harness 点：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStart、SubagentStop。${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PROJECT_DIR} 替换可用，并且 CLAUDE_PROJECT_DIR 会导出到 hook 进程。

限制（按当前发布版本）：仅运行 type: "command" shell hooks；http / mcp_tool / prompt / agent hooks 会被解析并跳过，同时给出警告。updatedInput 重写会被记录但不会被采纳。配置是进程级的（每次运行一个 hooks.json，而不是每个会话一个）。默认超时 10 分钟。

也存在一个 Codex 桥接：仅正则匹配器、snake_case 载荷、仅采纳阻断性决策。

原生替代方案：harness 自有的类型化拦截点（tools/pre-execute、ctx.tools.guard()、agent/turn-stopping 等）是规范接口；桥接的存在是为了兼容性（packages/hooks/README.md）。

主题：差距
存在一个主题注册 API（packages/client/ui-theme），但第三方主题 id 不会持久化到设置中：内置偏好仅有 Light/Dark/System，并且没有验证覆盖集是否完整。社区的变通做法是将皮肤作为插件发布，在加载时重新注册（参见 zhu1090093659/dsh-web-ui）。在向用户承诺其主题能在重启后保留之前，请先了解这一点。关于目前已有的内容，请参见 awesome-dsh-themes。

沙箱说明

@deepseek-ai/node-addon-landlock-run 是一个独立的约 300 行 C11 Landlock 启动器（静态 musl），单独发布，可在 dsh 之外用于任何运行不受信任命令的 harness。设计上采用故障关闭（fail-closed）：没有平台包意味着探测会报告 unusable，消费者会关闭失败。退出码 125 表示启动器失败，不过子进程也可能合法地返回 125。

链接

- 官方：repo · docs · landing · Cordis paper · Discord
- 社区：dsh.works · awesome-dsh-plugins · awesome-dsh-themes · dshthemes.com
- 徽章：官方可选加入的 "powered by dsh" 徽章位于 packages/skill/skill-badge（品牌蓝 #4D6BFE；不要重新设计它，资源本身已说明）。

许可证

CC BY 4.0。署名：dshworks/howto-dsh。