第 7 卷

web）

dsh --profile headless "任务"一次性任务，打印结果退出

dsh plugin --profile <name>给 profile 安装插件 add <pkg>

dsh --dump-config打印合成配置树

dsh --profile tuiTUI 模式（需先安装 tui 插件，官方未内置）

dsh --version版本

2.8 排障速查

现象原因与解法

dsh: profile "tui" does not existtui profile 需插件创建（dsh plugin --profile tui add <pkg>）

置 + API Key

插件装不上（404）rc.1 依赖断裂：确认依赖用 ^0.1.0-rc.6 线（第 3 章常见坑

#1）

升级后行为变了rc 阶段破坏性变更正常，看官方 changelog

---

**下一章**：[第 3 章：profile 与插件系统](./03-profiles.md) —— 理解可定制骨架。

---

> **headless 长任务看不到进度？** headless 默认只打印最终答案，长任务（几分钟以上）看不出卡在哪/剩多久——可用社区 dsh-progress-viz（live stage/ETA 仪表盘，#2442）或

headless 搭配 `--verbose`/审计日志观察。

> **源码方式启动慢的根因（#1424 社区实测确认）**：`pnpm dsh web` 每次启动用 tsx/esbuild **现场转译整个 TS 源码图**（非全量构建），叠加机械盘/大文件数时冷启动可达数

分钟。**实测计时**：tsx 热缓存 ~40s / 冷缓存 ~5min / 编译产物 `lib/bin.js` 版 ~12s（页面响应 5ms）。解决：① 启动命令改用 `node apps\cli\lib\bin.js web`（走编译产物）② 或先

`pnpm build` 全量构建一次 ③ 或直接用 `npx @deepseek-ai/dsh web`（发布版）。

> **Windows 通用坑 1——极简模式起不来**（#1889 实测）：报 `terminal inspection is unsupported on platform win32` 时，**和 node-pty 无关**——调用顺序是先解析平台

inspector 再 spawn，inspector 在前。重装 node-pty/换 Node/装 VS Build Tools 都没用；需 dsh-win32 类补丁。

> > **Windows 通用坑 2——当天发布的插件版本装不上**：profile 的 `pnpm-workspace.yaml`

里 `minimumReleaseAgeExclude` 只写了接线时的版本，插件发布新版后约一天内 `dsh plugin add <pkg>@latest` 回 `Already up to date`。要立刻装：`--

config.minimumReleaseAge=0`。

动手练习（10 分钟内完成）

1. **安装**：`npx -y @deepseek-ai/dsh --version` 确认版本
2. **Web 对话**：启动 `dsh web`，新会话发"你好"，观察回复与界面布局
3. **Headless**：`dsh --profile headless "1+1 等于几"`，确认打印结果后退出
4. **推理档位实验**：把 settings.yaml 的 `reasoningEffort` 改为 `off`（官方

provider）或 `low`（第三方网关），重新跑一个简单任务，感受速度差异

1. **排障演练**：模拟"端口被占"（先起一个占用 3080 的服务），用 `netstat` 排查

> 全部通过后，进 [第 3 章](./03-profiles.md) 理解"为什么能这样改"。

第 3 章：profile 与插件系统

> 本章目标：理解 dsh 的可定制骨架——profile 怎么组织、插件怎么挂载、host/client 双半是什么。**这是从"用户"变成"开发者"的分水岭。**

TL;DR（本章核心，30 秒版）

1. **profile = 一种可启动形态**：`~/.dsh/profiles/<name>/` 目录，由

`package.json`（插件清单）+ `cordis.patch.yml`（补丁层）组成

1. **挂载插件只需两步**：`package.json` 加依赖 + `cordis.patch.yml` 加挂载行，然

后 `pnpm install` 重启

1. **host 半跑在 Node，client 半跑在浏览器**：一个 npm 包通过 `exports["."]` 和

`exports["./client"]` 同时携带两副面孔

1. **改行为找扩展点，别 fork 核心**：`agent/request` waterfall、

`conversationEvents`、`ctx.slots.inject`、`settings` 服务是四大常用钩子

1. **rc 阶段三大坑**：依赖版本用 `^0.1.0-rc.6` 线、`next()` 必须 await、client 测试需

要 dsh 运行时 <details><summary>本章导航</summary>

• [3.1 profile：一个可启动的配置栈](#31-profile一个可启动的配置栈)
• [内置 Agent 预设：标准 / PTC / 极简 / 创造](#内置-agent-预设标准-ptc-极简-创造)
• [3.2 挂载一个插件：两处改动](#32-挂载一个插件两处改动)
• [3.3 host 半与 client 半：一个包，两副面孔](#33-host-半与-client-半一个包两副面孔)
• [3.4 扩展点：改行为优先找钩子，别 fork 核心](#34-扩展点改行为优先找钩子别-fork-

核心)

• [3.5 常见坑（真实踩过）](#35-常见坑真实踩过)
• [依赖解析坑](#依赖解析坑)
• [插件安装格式坑](#插件安装格式坑)
• [其他常见坑](#其他常见坑)

</details>

3.1 profile：一个可启动的配置栈

dsh 用 **profile** 表示"一种可启动的形态"。官方内置两个，其余用插件创建：

• 工具）

headless一次性 CLI 任务dsh --profile headless "任务"