前言¶
DeepSeek Harness（DSH）通过插件拼装能力和界面，但当需求落在「多一个浮窗」「改输入区旁边的 chip」「给对话页绑一套快捷键」这类细碎交互时，往往要动宿主或写完整客户端插件，改动面大、回滚也麻烦。社区里也有用脚本或补丁改 UI 的做法，不过缺少统一的启停边界和与会话生命周期对齐的挂载点。
dsh-shape（npm 包名 @belowthetree/dsh-shape）由 belowthetree 维护，归类为客户端插件。它把扩展单元抽象成 shape（形态）：一份清单加可选脚本，装好后可以浏览、单独启停，并在 DSH 的固定槽位里挂界面或注册页面级行为。内置对话搜索与工作区切换两种形态，并暴露 10 组内置能力供自定义形态声明依赖。以下按「是什么 → 能做什么 → 安装 → 用法要点 → 适用与注意」说明。
这是什么¶
形态即插件包内或用户目录下的一棵目录：package.json 描述元数据与能力依赖，views/ 可放页面，客户端模块按需注册面板、页签、边缘窗和槽位内容。宿主负责加载、校验依赖版本、把条目投进会话 UI，并在关闭形态时一并卸掉其视图与逻辑。
与「整包 fork 客户端」相比，形态粒度更轻：改文件后刷新页面即可让已有文件生效；增删文件需在形态面板点刷新（或调用 POST /dsh-shape/api/refresh）后重载。
核心功能¶
Shape 浏览器与独立视图¶
对话顶栏有 Shapes 入口；也可用 Ctrl + . 打开应用网格，浏览全部形态。点击卡片可在第二个窗口展示该形态自己的界面。
会话槽位与浮动 UI¶
形态可把内容挂到 10 类槽位，例如输入框上方的卡片栈、下方信息条、可吸附浮窗、输入条与顶栏的 chip、New Session 选项、View 菜单行，以及全屏覆盖层。客户端模块在受支持槽位可用 api.mount() 渲染 DOM。
此外还有三类常见 API：
api.panel()：注册浮动面板，open()后在输入区上方出现，可拖动、吸附边缘并记住位置。api.tab()：在右侧栏增加页签，open()打开；同一页重复打开只聚焦。api.edge()：从上/右/下/左边缘居中滑入的窗口，内容来自views/；可绑快捷键，Esc关闭（可用esc: false关掉），width/height为'full'时可占满一侧。
每个形态可独立启停；关闭后其视图、槽位条目与客户端逻辑失效。卡片右上角可删除形态目录（需确认）。
能力依赖与内置能力¶
形态在 package.json 的 shape.requires 里声明能力，用 api.require('dsh-shape', '<能力名>') 取用；缺少依赖或版本不匹配时形态不启动，也不显示槽位条目。包内提供 10 个内置能力（工作区、界面、快捷键、槽位、事件、存储、输入框、对话读取、MCP 服务器管理等），版本均为 1.0.0。可通过 shape_capabilities 工具查看当前可用能力及 API 方法名。
示例（摘自 README）：
const ui = api.require('dsh-shape', 'ui')
const shortcuts = api.require('dsh-shape', 'shortcuts')
const store = api.require('dsh-shape', 'storage')
shortcuts.register({ id: 'summary', label: '显示 MCP 摘要', keys: 'Ctrl+Alt+M', run: () => ui.notify('3 个服务器') })
await store.set('collapsed', true) // → <shape>/data/collapsed.json
内置形态¶
| 形态 | 触发 | 作用 |
|---|---|---|
chat-search |
Ctrl + F 或顶栏搜索 |
对话内查找、高亮、展开折叠思考块、F3 / Shift+F3 跳转 |
workspace-tab-switch |
按住 Ctrl 连按 Tab |
工作区预览条，松手切换；Ctrl + Shift + Tab 反向 |
两者位于包内 shapes/，可在 Shapes 面板启停或删除。将同名 id 复制到用户目录可覆盖内置版本，升级插件不会覆盖你的改动。
Shape Studio 预设¶
安装后会增加 Shape Studio 预设：用 shape_list、shape_scaffold、shape_validate、shape_read、shape_write 等工具限定在形态目录内读写与校验，并附带 shape-development、shape-playbook 两份 skill。该预设没有 bash/pwsh 与通用 tool-fs，形态外文件需通过其他预设或宿主能力处理。
安装与启用¶
要求 DSH 版本 >= 0.2.2-rc.1。当前包版本为 0.4.39（MIT）。
在目标 profile 上执行（将 <profile> 换成例如 desktop、web）：
dsh plugin --profile <profile> add @belowthetree/dsh-shape
安装后重启该 profile。也可用插件管理器按包名 @belowthetree/dsh-shape 安装，或 add github:belowthetree/dsh-shape、add link:/path/to/dsh-shape 做仓库/本地联调。
从旧的无作用域包名 dsh-shape 升级时：先 remove dsh-shape，再安装作用域包，并把 profile 的 dsh.profile.bundles 里条目改为 @belowthetree/dsh-shape。
启用后点击顶栏 Shapes 或 Ctrl + . 即可管理形态。
典型用法¶
- 安装并重启 profile 后，在 Shapes 面板打开内置
chat-search、workspace-tab-switch体验槽位与快捷键。 - 新建形态时，在
package.json填写shape.requires，客户端里api.require取能力，按需调用panel/tab/edge/mount。 - 开发迭代：改已有文件后刷新页面；新增或删除文件后先在面板刷新或
POST /dsh-shape/api/refresh。 - 查契约与踩坑：仓库
docs/（架构、形态目录、能力参考、已知问题）及包内 skill；Shape Studio 下用shape_spec（含 playbook 主题）查规范。
更完整的交互演示见仓库 demo/ 目录（含 MP4 与复现步骤）。
适用场景与注意¶
适合：需要在 DSH 客户端上快速加浮窗、侧栏页、边缘命令面板、输入区旁状态 chip，或绑定页面级快捷键的开发者；希望用清单 + 轻量脚本迭代 UI、而不是每次改整包客户端的场景。
注意：
- 插件及形态客户端逻辑以当前 DSH 进程权限运行，安装与自定义形态前应查看 GitHub 源码 与 MIT 许可证，仅安装信任来源。
- 能力版本不匹配时形态不会启动，开发时需对照
shape_capabilities与docs/capabilities.md。 - 社区插件目录 SkillHub 条目 与 GitHub 仓库由维护者与社区提供，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-shape 把 DSH 客户端扩展收成「可启停的形态」：固定槽位、浮动面板、侧栏页签与边缘窗一套 API，再加 10 组内置能力与两个开箱形态。若要自己写形态，装上包后切 Shape Studio 预设，按 docs/shape-development 与 scaffold 工具从清单起步即可。
- 目录页：https://www.skillhub.cn/plugins/belowthetree/dsh-shape
- 仓库：https://github.com/belowthetree/dsh-shape
