dsh-workspace-alias
[English placeholder — see 中文 README below for the full design doc.]
DeepSeek Harness plugin: cross-device workspace path aliasing. When your
.dsh session store is synced between machines (Syncthing etc.) but the same
project lives at different paths (/Volumes/Data/notes on macOS,
F:\notes on Windows), this plugin makes synced sessions group into the
local workspace of the same project instead of staying ungrouped.
Install:
dsh plugin --profile web add https://github.com/lodfather/dsh-workspace-alias
Configure <dshHome>/workspace-alias.json:
{
"version": 1,
"groups": [["/Volumes/Data/notes", "F:\\notes"]]
}
dsh-workspace-alias（中文说明）
解决什么问题
.dsh 的会话按「工作区绝对路径」分组：/Volumes/Data/notes（Mac）和 F:\notes（Windows）永远对不上。用 Syncthing 同步 .dsh 后，另一台机器同步来的会话因 cwd 在本机不存在而变成「未分组」。
本插件在 workspace registry 的 cwd 归一化层加一个跨机别名表：外机 cwd → 本机同名项目的真实路径，同步会话即可正确归桶。
安装
dsh plugin --profile web add https://github.com/lodfather/dsh-workspace-alias
# 重启 dsh web
插件自带的 cordis.patch.yml 会禁用官方 workspace 行并挂载本包（同服务名 workspaceRegistry），workspace-controller / ui-workspace / 侧边栏全部无感。
配置
两种方式，任选其一，结果等价（workspace-alias.json 始终是唯一真源）：
方式一：DSH 设置界面（推荐，v0.4.0 起）。双半区插件：host 侧向 settings 服务注册 workspace-alias namespace；client 侧（lib/client.js，DSH client-module 格式）注册 settings.section slot，设置页出现「工作区别名」完整编辑区（别名组增删改 + autoAttach 开关，草稿式编辑、原子保存），保存即写回 JSON 文件、热生效。宿主无 settings 服务时自动退化为方式二，无需任何配置。
方式二：手工编辑 <dshHome>/workspace-alias.json（建议纳入你的 .dsh 同步白名单，一台维护、两端生效）：
{
"version": 1,
"groups": [
["/Volumes/Data/notes", "F:\\notes"]
],
"autoAttach": true
}
groups：每个数组是一组「同一个项目在不同机器上的路径」，≥2 项autoAttach：启动时把「仅靠别名解析成功的会话」挂入本地 workspace（默认 true；这类会话不可能被本机主动 detach 过，不会违背手动整理意图）- 修改后由文件 watcher 热加载；新同步进来的会话在下次重启 dsh 时归组
remarks：
- 设置界面编辑同样写回
workspace-alias.json，因此 Syncthing 同步语义不变（一端 UI 修改，另一端 watcher 热加载）
- UI 写回前会把上一版内容备份为
workspace-alias.json.bak（防误清空）
- 单成员组合法但只能告警（它永远无法 alias 到另一台机器）；坏组跳过、不毒化整表（v0.2.4 容错语义）
原理（为什么不用 fork）
- 会话归属 = header 的 canonical cwd（
fs.realpath）与 workspace path 字符串相等（官方 paths.ts："ONE uniqueness canon"）
- 归属校验只在两处读 cwd：
WorkspaceRegistry.indexHeader（构建 sessionPaths 索引）与 WorkspaceEntity.attachSession
- 本包
AliasWorkspaceRegistry extends WorkspaceRegistry，只覆写 indexHeader 的 cwd 归一化：本机 realpath 失败 → 查别名组 → 用本机存在的兄弟路径 realpath
- 持久化 domain（
workspace domain v2）与实体生命周期全部继承，零迁移
已知限制
- 需要
@deepseek-ai/dsh-workspace 的内部形态稳定（rc 期破坏性变更风险，已在 dsh.compatibility 声明 0.1.x）
- 只做「历史会话归组」；同步进行中的会话（dsh 运行时 Syncthing 写入）在下次重启时归组
- Windows 路径比较统一
/ 分隔 + 大小写折叠（对 NTFS 不区分大小写的语义是正确的；对 macOS 大小写敏感盘的极端别名可能过宽）
License
MIT
