dsh-shape
Verified@belowthetree/dsh-shape · v0.8.0 · MIT · Web UI
A DeepSeek Harness plugin that adds a dynamic lightweight extension form for customizing DSH UI and functionality.
Install
dsh plugin add @belowthetree/dsh-shape Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-shape
dsh-shape 是 DeepSeek Harness 插件,提供一种动态轻量扩展形态:一个 shape(形态)就是一份清单加可选脚本,即时给 DSH 加上界面、聊天卡片和页面级快捷操作。
能做什么
- Shape 浏览器:在对话顶栏打开应用网格,浏览所有形态;按
Ctrl + .快速打开 - 独立视图:点击形态卡片,在第二个窗口展示该形态自己的界面
- 会话槽位:10 个槽位可选——输入框上方的卡片栈、下方的信息条、上方的浮窗(可固定、可自由浮动、靠近屏幕边缘自动吸附)、输入条左右与顶栏的状态 chip、New Session 选项、View 菜单行,以及覆盖全应用的全屏层(片头、命令面板这类);客户端模块还能用
api.mount()在受支持槽位里渲染自己的 DOM - 浮动面板:
api.panel()注册一个面板,open()后作为浮动窗口出现在会话输入区上方——可拖动、可吸附到屏幕边缘、自动记住位置,随形态停用一起消失 - 右侧页签:
api.tab()往右侧栏加一种页面,open()打开,同一页重复打开只聚焦不重复 - 边缘弹窗:
api.edge()注册一个从屏幕上/右/下/左边缘居中滑入的窗口,内容是形态views/目录里的页面;keys直接绑定快捷键,Esc关闭(esc: false关掉),拖动内边可调整大小并记住尺寸,width/height写'full'即可左右或上下占满,顶部窗口与占满的窗口会避开 Windows 顶栏 - 工作台:声明
shape.kind: "workbench"的形态用api.workbench()注册自己的界面,顶栏 shape 工作台 按钮或Ctrl + Alt + W打开约占 80% 视口的窗口;窗口没有标题栏,形态内容直接铺满,也没有关闭按钮,按Esc、点窗口外的空白处或再按一次快捷键关闭;窗口下方用标签列出所有工作台,圆点标记当前选中(空心未选中、白色实心选中),Ctrl + Alt + ←/→或点击切换;没有工作台形态时,窗口直接提示用 Shape Studio 预设新建 - 单个开关:每个形态独立启停;关闭后它的视图、槽位条目和客户端逻辑一起失效
- 客户端逻辑:形态可以注册页面级行为和快捷键,并按需读取已声明能力的接口
- 删除形态:卡片右上角的删除按钮,确认后把该形态目录从磁盘移除
- 能力依赖:形态声明需要的插件能力与版本,缺少依赖时不会启动,也不会显示槽位条目
- 能力目录:可以查看当前有哪些形态可用能力、版本、用途、用法和 API 方法名
- 内置能力:12 个内置能力覆盖工作区切换、文件读写、命令行执行、界面控制、快捷键、槽位、事件、存储、输入框、对话读取与 MCP 服务器管理,见下文内置能力
- 内置形态:随包提供
chat-search(对话内搜索,Ctrl+F)和workspace-tab-switch(工作区切换器,Ctrl+Tab),可在形态面板里启停或删除;用户目录下同 id 的形态会覆盖它们 - 即时生效:改完形态文件后在形态面板点刷新(或
POST /dsh-shape/api/refresh);客户端模块按内容签名寻址,只有文件真的变了的形态会在页内重启,页面不重载。面板每张卡片上还有「重启」,只重载那一个形态
内置形态
装好即可用,不用自己创建:
| 形态 | 触发 | 作用 |
|---|---|---|
chat-search |
Ctrl + F,或顶栏 🔍 |
在对话里查找文本:命中高亮、折叠的思考内容自动展开、滚动到命中;F3 / Shift + F3 上下一条,Esc 关闭 |
workspace-tab-switch |
按住 Ctrl 连按 Tab |
弹出工作区预览条,松手切到高亮项;Ctrl + Shift + Tab 反向,方向键移动,Esc 取消 |
两者都在包内 shapes/ 里,可在 Shapes 面板启停或删除。想改造就把目录复制到用户目录并保持同名 id——用户版本会覆盖内置版本,升级插件不会冲掉你的改动。
内置能力
形态在 package.json 的 shape.requires 里声明需要的能力,再用 api.require('dsh-shape', '<能力>') 取用;缺少能力或版本不匹配时形态不会启动。
| 能力 | 版本 | 方法 | 用途 |
|---|---|---|---|
dsh-shape#core |
1.0.0 | 字段 apiVersion |
判断形态 ABI |
dsh-shape#workspace |
1.0.0 | list current next previous |
切换工作区,并展开、滚动到目标分组 |
dsh-shape#files |
1.0.0 | workspace read write append replace list |
读写、追加、替换、列出当前工作区内的文件;read 支持按行/字节取片段,write 默认整体覆盖、可追加;路径相对工作区,读写上限 1 MB |
dsh-shape#shell |
1.0.0 | workspace run |
在当前工作区里执行命令行(走宿主 shell 服务与沙箱):cwd 相对工作区,mode 默认 workspace-write 也可 read-only,超时与输出上限可配;非零退出照常返回 exitCode、stdout、stderr 与沙箱摘要 |
dsh-shape#ui |
1.0.0 | openSession openWorkspace toggleSidebar selectPanel getTheme setTheme send cancelTurn notify openShapeBrowser |
控制 DSH 界面:导航、面板、主题、对话、通知、打开 Shapes |
dsh-shape#shortcuts |
1.0.0 | register list |
把形态动作注册成 DSH 命令,用户可在设置里重绑;regions 决定输入框聚焦时是否也触发 |
dsh-shape#slots |
1.0.0 | list mount entries |
查询 10 个槽位、运行时挂载、统计占用 |
dsh-shape#events |
1.0.0 | emit on |
形态之间收发事件 |
dsh-shape#storage |
1.0.0 | get set remove keys |
JSON 数据存到形态目录的 data/ 下 |
dsh-shape#composer |
1.0.0 | getText setText insert submit sessionId |
读写当前输入框草稿,可插入或直接发送 |
dsh-shape#conversation |
1.0.0 | messages find reveal subscribe |
读取已渲染的对话、搜索并跳转到某条消息 |
dsh-shape#mcp |
1.0.0 | available list projects get add update remove setMode setProjectTrusted session |
读取与修改 MCP 服务器:状态、工作区作用域、工作区配置信任、单会话清单(数据来自 dsh-mcp-setting) |
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
shape_capabilities 工具会列出当前所有能力、版本、用途、用法和 API 方法名。
文档
- 文档索引
- 架构:宿主插件、客户端 bundle、形态加载与能力系统
- 形态目录:清单字段、视图、槽位条目、客户端模块
- 能力参考:12 个能力的方法、返回值与失败行为
- 开发与发布:本地联调、发布前检查、client.js 拼接注意事项
- 已知问题:当前不可用的 API 与踩过的坑
仓库里有三份 skill:skills/shape-development/ 教 agent 写形态、skills/shape-playbook/ 是经验流程文档(已验证的各类形态做法,加上 UI 不渲染、快捷键被拒、搜索/展开/高亮、预设判定损坏这些坑),两份都随包发布并由 Shape Studio 预设注册;.dsh/skills/dsh-shape-contribution/ 教 agent 改这个包本身,放在 DSH 的项目级技能目录里,在本仓库工作时任何预设都能用。
演示

22 秒功能演示:1080p MP4 · 演示源码与复现步骤
Shape Studio 预设
安装后新增 Shape Studio 预设:在标准预设的基础上,去掉 shell 和通用文件读写,换成按形态限定的文件工具。
- 查看、检查、创建、校验形态:
shape_list、shape_inspect、shape_scaffold、shape_validate、shape_test - 按形态限定范围的文件访问:
shape_read、shape_write(必须指定形态 id,路径相对该形态目录) - 目录结构与文本检索:
shape_tree、shape_grep - 能力目录查询:
shape_capabilities;规范查询:shape_spec(含playbook经验流程主题) - 附带两份 skill:
shape-development(契约与写法)、shape-playbook(已验证的各类形态流程与踩过的坑) - 其余能力与标准预设一致:Web 搜索与抓取、后台任务、定时任务、目标与规划、子代理与工作流、待办、
present、插件管理
只有两处缺口:没有 bash/pwsh,也没有 tool-fs/tool-fs-search——所以形态目录之外的文件它读写不到,形态文件一律走 shape 工具。这些工具和 skill 只在 Shape Studio 中可见,其他预设不会看到。
安装
npm 包名:@belowthetree/dsh-shape
dsh plugin --profile <profile> add @belowthetree/dsh-shape
把 <profile> 换成要安装的 profile(如 desktop、web),然后重启该 profile。
其他安装方式:
- GitHub 仓库:
dsh plugin --profile <profile> add github:belowthetree/dsh-shape - 本地开发:
dsh plugin --profile <profile> add link:/path/to/dsh-shape - 插件管理器:在 DSH 的插件管理器中按包名
@belowthetree/dsh-shape或仓库belowthetree/dsh-shape安装
要求 DSH >= 0.2.2-rc.1。安装后点击对话顶栏的 Shapes,或按 Ctrl + . 打开。
从旧的无作用域包名
dsh-shape升级:先dsh plugin --profile <profile> remove dsh-shape,再按上面的命令安装,最后把 profile 的dsh.profile.bundles里的dsh-shape改成@belowthetree/dsh-shape。
