DSH 关联工作区
为一个 DSH 项目设置主工作区，并关联组件库、后端或参考项目。在同一会话中搜索和读取这些目录，保留文件来源与目录规则。
版本：0.3.0。兼容 DeepSeek Harness 0.2.1-alpha.4 和 0.2.1-rc.2，Node.js 22.19+。支持本机文件系统和 DSH Web 客户端；DSH 桌面端使用同一 Web 客户端，但当前自动化验收使用 Windows 官方发行版启动的独立 Web profile。
安装
从 GitHub Release 安装预构建包：
dsh plugin --profile web add https://github.com/NingTiAn-byte/dsh-linked-workspaces/releases/download/v0.3.0/dsh-linked-workspaces.tgz --ignore-scripts --config.auto-install-peers=false
web 应替换为实际使用的 profile。Windows 桌面发行版的启动器未加入 PATH 时：
$dshCli = Join-Path $env:LOCALAPPDATA 'Programs/DeepSeek Harness/resources/runtime/cli/bin/dsh.cmd'
& $dshCli plugin --profile web add https://github.com/NingTiAn-byte/dsh-linked-workspaces/releases/download/v0.3.0/dsh-linked-workspaces.tgz --ignore-scripts --config.auto-install-peers=false
按宿主提示重新启动相应 profile，并刷新页面。插件提供自己的 bundle patch，安装后无需手改 DSH 源码。发行版提供运行时 SDK peers；开发依赖不会打入安装包。
快捷使用
- 在 DSH 左侧项目名称上单击鼠标右键，选择 添加关联工作区…。
- 从已有工作区中选择一个，点击 添加此工作区；或者点击 选择本机目录…，在目录选择器中选中目录。
- 自动生成别名并保存，无需填写别名、用途或再进入管理页保存。新会话会自动继承配置；已有会话仍保留快照，可在管理页显式同步。
右键菜单中的 管理关联工作区 会直接定位到刚才点击的项目。原来的侧栏管理页保留，用于修改别名、移除关联和同步会话。取消选择不修改配置；已有目录不可重复添加；其他窗口的并发修改不会被覆盖。
桌面端优先使用桌面目录选择桥；Web 按宿主提供的目录浏览或原生选择能力工作。目录浏览支持逐级进入、上一级、主目录及可选的路径跳转。
详细管理
- 在 DSH 中添加主项目的工作区。在左侧进入「关联工作区」，选择该项目。
- 从「从已有工作区添加」选择组件库，或点击「添加目录」填写本机绝对路径。
- 设置稳定别名，例如
components、server。别名以小写字母开头，可含小写字母、数字、下划线和连字符，最多 32 字符。填写简短用途后保存。 - 在面板里搜索文件名或文本，点击结果读取带行号的预览和适用的
AGENTS.md。结果使用components/src/Button.tsx这类名称，避免同名文件混淆。 - 在主工作区中开始会话。模型首次处理请求时继承当时的项目配置，并获得目录清单。
- 项目配置变化后，已有会话保留旧快照。在面板选择空闲会话并点击「同步到所选会话」，下一次模型请求采用新快照。会话标题旁的关联目录按钮可以返回管理面板。
可以对模型说：“从 components 中找到 Button 的实现，阅读它的使用约束，再在主项目中复用。”关联目录不会自动成为主项目的包依赖；复制源码、本地包链接和修改构建配置仍由实际任务决定。
会话继续属于原来的主工作区。切换主工作区请通过 DSH 的工作区入口创建或打开相应会话。移除关联只更新配置，不删除磁盘文件。
模型工具
| 工具 | 功能 |
|---|---|
linked_workspace_list |
列出当前会话快照里的主目录、关联目录和当前可用状态 |
linked_workspace_search |
在指定别名或全部目录进行不区分大小写的字面文件路径/文本搜索 |
linked_workspace_read |
按相对路径读取带行号文本，同时返回根目录至文件父目录的 AGENTS.md |
工具不提供写入、删除、依赖安装或命令执行操作。原生工具模式和 PTC 使用同一注册工具；目录清单通过宿主 runtime context 进入模型历史。读取结果和目录规则通过正常工具结果记入日志，不会预先读取全部仓库内容。
规则均附带绝对适用目录，读取结果不会把关联项目规则提升为主项目的全局规则。规则发现目前只支持文件所在目录链中的 AGENTS.md，不额外加载 CLAUDE.md、用户全局规则或跨目录规则继承。
存储与权限
项目配置保存于 DSH storageDomain 的 local_linked_workspaces 域，使用宿主已配置的存储后端；JSON 后端下文件名是 local_linked_workspaces.json。配置使用工作区 ID 索引，不向用户仓库写入配置文件。保存带版本校验，其他窗口提交修改后，本窗口必须刷新再保存。
会话快照保存为 plugin:linked-workspaces/snapshot 可忽略记录，由注册的 linkedWorkspaces projection 恢复。继续会话和分叉继承已记录的快照；新的项目配置不会静默覆盖历史会话。首次使用前未创建快照的会话采用首次使用时的配置。与其他实验性插件记录一样，跨 Session 格式迁移的保留由 DSH 提供尽力支持。
管理与搜索 HTTP 接口挂在 DSH 已认证的 Connection exact Fetch route 上；两个支持版本只允许 owner Peer 调用此类路由。插件不创建额外监听端口。
“关联工具只读”指这些工具自身没有修改操作。 它不限制原有 shell、文件工具或其他插件，也不是新的文件系统沙箱。DSH 的现有 sandbox、提权和系统访问控制继续生效。不要把关联目录清单当作整台机器的读取白名单。
目录路径经过 realpath 规范化，拒绝重复、别名冲突和父子目录重叠。搜索跳过符号链接与 junction；读取拒绝最终文件符号链接，解析后的文件必须位于所选根目录内。配置的根目录目标变化后需要重新关联。不存在或不可访问的根目录会在面板和搜索结果里明确标注。
范围和限制
- 最多关联 16 个本机目录；不支持 SSH、容器路径或远端文件系统后端。
- 搜索排除隐藏文件/目录（
.github除外）、.env、常见私钥和凭据文件，以及.git、node_modules、dist、build、coverage、__pycache__、.next、vendor。排除规则不等同于完整秘密检测。当前不解析.gitignore。 - 文本工具不支持二进制文件。搜索有遍历、时长、单文件大小和结果数量上限；达到限制时返回
truncated，文件或根目录失败返回独立提示。 - 读取仅覆盖文件前
readMaxBytes字节，每次 1–300 行；超出前缀的内容需使用宿主现有工具在其权限下阅读。规则文件共享单次规则字节预算。 - 同一 DSH 实例内支持并发窗口的版本冲突检测。不要让多个独立 DSH 进程同时写同一个 JSON 存储目录；其多进程写入语义由宿主存储后端决定。
- 第一版不统一各仓库 Git 操作、不安装依赖、不建立构建联动，不增加跨目录写权限。
配置
在插件配置中覆盖这些整数值：
| 字段 | 默认值 | 含义 |
|---|---|---|
readMaxBytes |
65536 | 单次文件前缀读取上限 |
instructionMaxBytes |
16384 | 单次返回规则总字节预算 |
searchFileMaxBytes |
65536 | 文本搜索的单文件前缀上限 |
searchMaxResults |
40 | 单次搜索结果上限 |
searchMaxEntries |
10000 | 单次搜索遍历条目上限 |
searchMaxWarnings |
30 | 最多返回的文件提示条数，另保留提示总数 |
searchTimeoutMs |
5000 | 搜索合作式时间预算，文件系统调用返回后检查 |
previewChars |
240 | 单条搜索结果的文本预览字符上限 |
模型上下文只包含目录清单和使用说明，长度随关联数量增长。搜索、读取和规则内容按需进入工具历史，受上述配置限制。
开发与验收
npm ci --ignore-scripts
npm run check
npm test
npm pack --ignore-scripts --cache ./artifacts/npm-cache
单元与模型循环测试使用 rc.2 发布 SDK、真实 Session/projection 和 JSON storage；模型响应使用固定脚本，不需要 API Key。覆盖同名文件、来源、规则作用域、越界路径、链接、二进制文件、缺失目录、取消、截断、并发保存、会话恢复及显式同步。
真实页面验收使用独立 DSH home，避免改动用户 profile：
$env:DSH_HOME = Join-Path (Get-Location) 'artifacts/live-home'
& $dshCli --profile linked-workspaces-test --from-default-profile web --dump-config
node scripts/prepare-live.mjs
& $dshCli plugin --profile linked-workspaces-test add ./local-dsh-linked-workspaces-0.3.0.tgz --ignore-scripts --offline --config.auto-install-peers=false
& $dshCli --profile linked-workspaces-test --patch artifacts/live.overlay.yml --port 7362 --no-open
# 在另一个终端运行，使用上一条命令输出的认证 URL：
npm run test:live -- 'http://127.0.0.1:7362/?token=...'
node scripts/prepare-live.mjs 会生成带当前 checkout 路径的本地 overlay，生成文件不提交到 GitHub。fixture 只创建 artifacts/example 下的演示目录和隔离 profile 内的测试会话，不打入插件包。页面测试使用本机无头 Edge，可通过 DSH_TEST_BROWSER 指定浏览器，保存报告和宽窄屏截图到 artifacts/。
双版本兼容
同一个安装包适用于两个版本，项目配置和会话快照采用相同格式，无需转换。运行时使用宿主提供的共享 SDK，不自动安装另一版本宿主。安装时保留 --ignore-scripts --config.auto-install-peers=false，并选择实际使用的 profile；重启后刷新页面。
本版本只承诺 alpha.4 与 rc.2，不泛化为所有中间版本。开发时仍使用锁文件中的 rc.2 SDK；可通过 DSH_TEST_HOST_SOURCE 指向已构建的 alpha.4 源码后运行 npm run test:host，验证实际 alpha.4 SDK，而不是混用两个版本。
项目右键菜单的兼容方式
alpha.4 和 rc.2 尚未公开项目级菜单条目的插件插槽。插件在公开的 shell.overlay 插槽中挂载自己的菜单和对话框，通过这两个版本共同使用的 data-row-key="workspace:…" 识别目标项目。只处理项目行的右键事件，不替换宿主的项目“…”菜单，也不修改宿主源码。项目行结构变化的后续 DSH 版本需要重新验证；原管理入口可独立使用。
目录选择使用 uiWorkspace 的目录能力和桌面原生桥；保存继续走已有 owner-only API、目录边界检查和 revision 冲突检测，不增加磁盘写权限。弹出层支持 Escape、菜单方向键和 Tab 焦点约束，卸载时撤销监听和未完成请求。
开发者可用 DSH_TEST_URL 和 DSH_TEST_ARTIFACT_DIR 指向隔离测试服务及其 fixture，再运行 node tests/quick-live.mjs，检查右键、取消、自动别名、重复目录、真实目录浏览、并发保存、延迟选择结果及重载持久化。测试 fixture 不包含在安装包中。
