HHpetra/dsh-hk-craft--packages-dsh-hk-craft ↗★ 0
dsh-hk-craft
dsh-hk-craft — DeepSeek Harness native plugin. Installs into an existing dsh profile; no separate launcher, home, profile, or port.
安装
npx -p @deepseek-ai/dsh dsh plugin --profile web add 'github:HHpetra/dsh-hk-craft#888592dcb1dea0bf9316312ec0c49e0ff91d94e7&path:packages/dsh-hk-craft'说明文档
阅读完整 README ↗dsh-hk-craft
DeepSeek Harness(dsh)的原生插件(bundle)。装进你已有的 dsh profile(默认 desktop),在 dsh 现有的 Web UI 和会话里直接使用,不额外启动第二个应用。
两个核心能力:
- 多会话分屏:同一屏并排放多个会话,每个窗格独立运行、独立操作。
- TUI 命令切换对话:在输入框用
/命令快速恢复、替换、分叉当前对话。
插件不提供启动器、桌面外壳、独立
DSH_HOME、独立端口或第二套聊天界面;也不 fork@deepseek-ai/dsh*。
功能速览
| 能力 | 入口 | 说明 |
|---|---|---|
| 多会话分屏 | 插件加载后自动进入 | 当前会话落在第一格;每个窗格承载一个会话 |
| 新建窗格 | 标签条 +、Ctrl+Shift+E、/resume + Ctrl+Enter | 在焦点窗格右侧分栏 |
| 切换/恢复会话 | /resume | 搜索并打开当前工作区的历史会话 |
| 新会话 | /new、/clear、Ctrl+N | 在焦点窗格中开新会话,不新增窗格 |
| 分叉会话 | /fork | 复制当前会话,原会话不受影响 |
| 切换视图 | 窗格头部“对话 / 轨迹”按钮、/trace | 轨迹视图需开启 dsh 开发者工具 |
| 分屏上限 | 设置 → HK Craft | 默认每个工作区 4 格,0 表示不限制 |
| 侧栏工作区 | 侧栏“工作区”列表 | 五态灯、添加/删除、拖动排序 |
| 桌面通知 | 设置 → HK Craft → 桌面通知 | 五类通知,点击回到对应会话 |
| 原生右栏 / 终端 | 标签条右侧图标 | 打开文件、浏览器、终端等原生工具 |
安装与卸载
安装目标为 dsh 的 desktop profile。该 profile 由 Electron 应用独占管理,不能用 CLI dsh plugin --profile desktop ... 安装。
开发环境要求 Node.js ^22.19.0 || >=24.0.0、pnpm 12.5.1;engines.dsh 为 `>=0.2.1-rc.5 黄 > 绿 > 蓝 > 灰**。灰灯的含义是“没有已开始的对话”,不是“最近没有活动”;只在原生视图里打开过工作区不会点亮它,因为那不会创建分屏布局。查看亮绿灯的会话后,它的未读会被清除;工作区没有其它未读、运行或等待时,灯回到蓝。没有“失败”灯,因为 dsh 客户端没有可靠的“上一回合失败”字段。
添加、删除与排序
- 点击工作区行:切换到该工作区的窗格布局;布局为空时显示该工作区最近的会话,或空状态。
- 添加:列表底部的“添加工作区”打开 dsh 原生的目录选择器;取消不会创建记录,创建成功后自动切过去。失败原因显示在列表下方。
- 排序:按住工作区行拖动,插入线指示落点;顺序由 Host 持久化,插件不另存一份。失败时在列表下方提示。
- 删除:悬停行尾的
×,在确认框中确认。只删除工作区登记,不删除磁盘目录或会话历史,也不会中断正在运行的回合;确认框会先提示该工作区正在运行的会话数。删除失败会保留对话框并显示原因。
“未分组”会话:删除工作区后,它的会话仍保留在 dsh 数据中,原生侧栏会把它们归到“未分组”;本插件的精简侧栏只列工作区,不显示“未分组”,需要时可在卸载插件后回到 dsh 原生侧栏查看。
TUI 命令切换对话
这里的“TUI 命令”指 dsh 输入框里以 / 开头的命令面板,交互方式和终端 TUI 一致;它不是独立的终端程序。所有命令都由插件注册在客户端,不会发送给模型,也不会写入会话日志。
在对话输入框以 / 开头输入命令名,或从命令列表中选择。
| 命令 | 作用 |
|---|---|
/resume | 搜索并切换当前工作区的历史会话 |
/new、/clear | 在当前窗格开新会话(不新增窗格) |
/fork | 复制当前会话 |
/trace | 把焦点窗格切到轨迹视图 |
/resume:恢复 / 切换历史会话
打开 dsh 原生的选择浮层,列出当前工作区的历史会话:
- 按最近活动时间倒序;空白会话和已归档会话不显示;
- 支持模糊搜索,匹配标题和首条提问;
- 每行显示相对时间,以及
运行中/已在窗格 N徽标; - 选中一个已经在窗格中打开的会话时,直接聚焦那个窗格,不会重复打开。
打开方式:
| 操作 | 结果 |
|---|---|
Enter | 用所选会话替换焦点窗格的内容;旧会话仍在历史中 |
Ctrl+Enter(macOS 为 Cmd+Enter) | 在焦点窗格右侧新开一格打开所选会话 |
空工作区中 Ctrl+Enter | 直接打开第一格(第一格不经过分栏预算检查) |
新窗格受分屏上限约束。达到上限时不会创建窗格,也不会切换到别的格子;标签条 + 会说明上限原因。
/new 与 /clear:在焦点窗格开新会话
两个名字当前完全等价:在当前工作区新建一个会话,并放进焦点窗格。
- 旧会话不会被删除,仍留在历史中;
- 不会新增窗格。要并排开新会话,请用
+或Ctrl+Shift+E; - 分屏未激活时,退回 dsh 原生的“新建会话”行为;
- 分屏激活时,
Ctrl+N与/new、/clear等价;Ctrl+Shift+N也执行同一动作。未激活分屏时Ctrl+N仍是 dsh 原生快捷键。
/fork:复制当前会话
把当前会话复制成一个可继续的副本,原会话完全不受影响。
- 副本截止到最后一个已完成的回合,不包含正在进行的回合;
- 会话尚未开始、或没有已完成回合时不能分叉;
- 在分屏中,副本会自动在焦点窗格右侧打开;如果分屏已满,副本仍会出现在会话列表中,之后可用
/resume打开; - 分叉失败(例如会话正在迁移)只在控制台告警,不会弹出阻塞对话框。
/trace:把焦点窗格切到轨迹视图
- 仅在分屏激活、存在焦点窗格、且 dsh 开发者工具开启时可用;
- 只切换视图,不更换会话、不改变布局;
- 用窗格头部的“对话 / 轨迹”按钮可以切回来。
命令与分屏的配合
| 命令 | 分屏激活时 | 分屏未激活(原生视图)时 |
|---|---|---|
/resume + Enter | 替换焦点窗格的会话 | 按 dsh 原生方式打开 |
/resume + Ctrl+Enter | 在焦点窗格右侧新开一格 | 按 dsh 原生方式打开 |
/new / /clear | 在焦点窗格中开新会话 | dsh 原生“新建会话” |
/fork | 副本在焦点窗格右侧打开(满格时留在会话列表) | 副本进入会话列表 |
/trace | 焦点窗格切到轨迹视图 | 不可用 |
插件正常装载后默认就是分屏状态,“原生视图”只会在分屏未激活的降级场景中出现。
桌面通知
插件在 dsh 的渲染进程里调用系统 Notification API 发出通知;Windows 上显示为以 dsh 应用身份出现的 toast,不是 dsh 自带的应用内提示。
| 类型 | 触发 |
|---|---|
| 等待授权 | 工具调用请求审批 |
| 等待回答 | Agent 提问,等待你回答 |
| 计划待审阅 | Agent 提交计划 |
| 本轮完成 | 会话由运行转为空闲 |
| 本轮失败 | 会话报错 |
- 默认五类全开、播放声音、始终通知;可在设置页逐类开关、关闭声音和开启前台抑制。
- 同一会话只保留最新一条通知;等待类通知会请求系统保持显示并重新提醒。失败优先于紧随其后的完成:同一回合失败后 30 秒内的完成不再单独通知;子代理不单独通知。
- 点击通知会把 dsh 提到前台并定位到对应会话。分屏中已打开的会话直接聚焦;未打开的会话尝试在焦点窗格右侧新开一格(受分屏上限约束)。原生视图走 dsh 的打开会话。
- 开启“dsh 在前台且该对话可见时不再通知”后,焦点窗口里正显示的对话不弹 toast;其它工作区、或 dsh 不在前台时仍会通知。
- 系统未授权、被拒绝或环境不支持时通知安静降级;设置页可查看权限状态并发送测试通知。Windows 的通知开关也会影响结果。
通知不会改变侧栏五态灯,也不等同于“未读完成”状态。
快捷键
| 快捷键 | 作用 | 说明 |
|---|---|---|
Ctrl+Shift+E | 向右分栏,新会话 | 无焦点窗格时无操作 |
Ctrl+Shift+X | 关闭焦点窗格 | 运行中需确认后中断 |
Ctrl+Shift+N | 在焦点窗格开新会话 | 不新增窗格 |
Ctrl+1 ~ Ctrl+4 | 聚焦第 1 ~ 4 个窗格 | 超过 4 格时仍可点击标签聚焦 |
Ctrl+N | 等同于 /clear | 仅在分屏激活时接管;否则保持 dsh 原生行为 |
/resume 中 Ctrl+Enter | 在新窗格打开所选会话 | macOS 为 Cmd+Enter |
macOS 上实际按键为 Cmd,界面提示统一显示 Ctrl。所有快捷键在 dsh 的模态对话框打开时让位给对话框。
设置页
设置 → HK Craft 提供:
- 诊断:客户端是否加载、构建入口、
conversation.content探测结果、当前视图; - 分屏上限:每个工作区最多窗格数,
0表示不限制; - 桌面通知:启用开关、五类通知、声音、前台可见时抑制、系统权限和测试通知。
分屏上限写入失败时,这一次修改仍会在内存中生效,页面同时显示失败原因;读取失败或值非法时回落到默认值 4。设置页的修改即时生效,只有安装或更新 bundle 本身需要重启 dsh。
本地数据
| 存储键 | 内容 |
|---|---|
dsh.hkcraft.layout.v1. | 单个工作区的窗格布局树、会话、视图与焦点 |
dsh.hkcraft.settings.v1 | 分屏上限 |
dsh.hkcraft.notifications.v1 | 桌面通知设置 |
dsh.terminal.shell | 与 dsh 共用:终端记住的 shell;插件首次只把它改成 PowerShell(若可用) |
dsh.hkcraft.terminal.shell-default | 插件的一次性标记,避免覆盖之后在终端菜单里的手选 |
布局和设置都按浏览器源(origin)保存。卸载插件后,这些键不会被自动清理;需要彻底重置时可在 dsh 的开发者工具里删除对应键。
插件代码本身不发起网络请求,也没有遥测;布局、设置和通知偏好只写当前 origin 的 localStorage。会话内容、工作区目录与登录态仍由 dsh 管理,插件不复制。桌面通知通过系统 API 发送,是否显示最终由系统通知设置决定。
常见问题与排障
先看 设置 → HK Craft → 诊断:客户端是否加载、conversation.content 探测结果和当前视图都在那里。控制台里以 [dsh-hkcraft] 开头的日志通常能指出具体失败点。
| 现象 | 检查 / 处理 |
|---|---|
| 主区域空白,或显示“对话内容暂不可用” | 诊断里的 conversation.content 是否为“可用”。若显示“缺失”或“出错”,说明当前 dsh 构建没有提供或无法加载该组件;确认版本满足 engines.dsh,重启后再试。 |
| 没有自动进入分屏 | 诊断里的“客户端已加载”是否为 ✓、“当前视图”是否为“分屏窗格”;确认插件在 Plugins → Installed plugins 中启用,并重启 dsh。 |
+、Ctrl+Shift+E 或 /resume 的 Ctrl+Enter 不新建窗格 | 很可能到了分屏上限。到 设置 → HK Craft 把上限调大,或填 0;也可以先关闭一个窗格。 |
| 快捷键没有反应 | 先点击目标窗格使其获得焦点;关闭 dsh 的模态对话框;macOS 上使用 Cmd 而不是 Ctrl。 |
| 收不到桌面通知 | 检查总开关和五类开关、系统通知权限、Windows 通知设置;用设置页的“发送测试通知”验证。若勾选了“前台可见时不再通知”,正在看的对话不会弹。 |
新终端默认还是 cmd | 系统里没有发现 PowerShell 7 / Windows PowerShell,或之前已在终端菜单里手动选过 shell。用终端卡片的 shell 菜单选择;插件只应用一次默认值。 |
| 布局错乱或想重置分屏 | 在开发者工具的 Local Storage 中删除对应工作区的 dsh.hkcraft.layout.v1.,然后重启。只丢布局,不删会话。 |
| 升级 dsh 后功能异常 | 确认新版本仍在 engines.dsh 范围内;从源码重新执行 pnpm build、pnpm check、pnpm test,并按 docs/upstream-contracts.md 复验。 |
兼容性与降级
客户端运行在 dsh 的 Web 壳(Desktop 内置 Web UI)中。engines.dsh 为 >=0.2.1-rc.5 <0.3.0,安装器会校验;插件不 fork 上游,只通过公开服务扩展。
dsh 的可选能力缺失时,插件安静降级而不是让主区域崩溃:
| 能力 | 依赖 | 缺失时 |
|---|---|---|
| 分屏对话内容 | conversation.content | 窗格显示回退提示,分屏外壳仍可用 |
| 对话 / 轨迹视图 | uiConversation、开发者工具开关 | 只保留对话视图,不显示轨迹按钮 |
| 原生右栏 | sidebarRight、sidebarRightTabs | 隐藏右栏工具图标 |
| 斜杠命令 | commandUi、sessions、workspaces、uiWorkspace | 对应命令不注册 |
| 桌面通知 | uiSession、系统 Notification API | 不发送 toast,其余功能正常 |
| 工作区侧栏 | uiWorkspace、workspaces | 不注册精简工作区列表 |
| 模式名 / 子代理 | remote.agentPresets、sessions.refreshProjections | 模式名回退到内置名或原始 id;子代理刷新变为空操作 |
平台差异:桌面通知通过系统 Notification API 发送,Windows 上显示为 dsh 应用的 toast;Windows 还额外做了 PowerShell 7 的真实可执行文件发现与终端默认 shell 设置,其它平台按 dsh 实际列出的 shell 选择。
已知限制
- 分屏是插件唯一的主区域视图;只剩一个窗格时显示的仍是本插件的窗格,不是 dsh 原生会话面板。
- 窗格只渲染
conversation.content,不挂载原生 session header;标题、模式、子代理、视图切换和关闭由窗格头部自己承担。 - 同一会话只允许一个窗格;不支持同一会话并排对照。
- 快捷键固定,暂不支持自定义改键。
- 轨迹视图依赖 dsh 开发者工具设置;关闭时该视图和
/trace都不可用。 - 精简侧栏只列已注册工作区,不显示 dsh 的“未分组”会话;删除工作区后的历史需要回到原生侧栏查看。
- 布局、设置和通知偏好只存在当前浏览器 origin,不跨设备同步;清掉浏览器数据会丢失布局(会话和历史不受影响)。
- 桌面通知、Agent 预设名册、子代理目录、右栏等能力在对应 dsh 服务缺失时安静降级,不阻塞分屏。
- 上游契约集中在仓库的
docs/upstream-contracts.md,升级 dsh 时按该清单复验。
开发
pnpm install # 只在仓库根安装
pnpm build # esbuild 构建客户端 lib/client.js
pnpm check # 校验 manifest / patch / 入口 / 已构建 bundle 一致
pnpm test # 包内单元测试
check 依赖已构建的 lib/client.js,所以顺序是 build → check。lib/client.js 是构建产物,不入库。
测试使用 Node 原生 test runner(node --test --test-isolation=none),与实现同目录的 *.test.js 覆盖布局树、分屏预算、恢复列表、清单投影、状态灯等纯逻辑;客户端 bundle 的装载契约则由 pnpm check 校验。
包结构:
| 路径 | 作用 |
|---|---|
package.json | dsh.bundle.patch、dsh.client 与版本约束 |
cordis.patch.yml | 向 profile 插入 dsh-hk-craft 插件行 |
src/index.js | host 侧入口(终端默认 shell 偏好等宿主粘合) |
src/client/ | 浏览器侧:分屏、标签条、工作区、命令、设置页与通知 |
scripts/build-client.mjs | 客户端 bundle 构建脚本 |
仓库级架构、ADR 与领域术语见 docs/README.md、docs/adr/ 和 GLOSSARY.md。
许可
本项目采用 MIT License 开源,Copyright (c) 2026 HHpetra。完整协议见单独文件 LICENSE。