dsh-workspace-combiner

dsh plugin --profile web add dsh-workspace-combiner

dsh-workspace-combiner

<p align="center">

<img src="./docs/images/hero.png" alt="工作区组合器 — 全栈前后端，一个会话搞定" width="900">

</p>

当前插件 manifest 已适配 DSH 0.2.0-rc.2 seam API，peer 版本用范围（>=0.2.0-rc.1 <0.3.0）而非精确锁定，同一 rc 线内的后续版本无需重新发布即可加载；pnpm smoke:dsh-compat 守住这一声明。DSH 宿主已经提供的服务不会重复打包进插件。

<p align="center">

<em>为全栈开发者而生：把前端仓库、后端仓库与文档锚点捆进同一个 AI 会话。绝对路径注入、沙盒可写根自动同步，接口变更在同一轮对话里前后端一起改。</em>

</p>

<p align="center">

<strong>中文</strong> · <a href="./README.md">English</a>

</p>

---

一个用于 DSH（DeepSeek Harness）的 Cordis 双面插件，把一组仓库组织成协同的 多工作区联合开发 上下文。

插件在左侧边栏注册一个 工作区组合器 面板。每个「工作空间」绑定一个主目录（工作区锚点——放文档与非代码资产）加一组有序的 代码项目 目录（例如一个后端仓库、一个前端仓库）。新建会话时，插件把所有生效目录的绝对路径注入 system prompt，并把可写目录同步进 dsh-write-protect 白名单。

为抑制注入上下文膨胀，插件提供 五层上下文控制：

1. 目录层 — 逐目录访问模式（readwrite / readonly / disabled）、主目录锚定、拖拽排序。

2. 配置层 — anchor / single 工作空间模式，以及可选的分组标签。

3. 加载层 — full / summary / tree 控制注入的文件细节量。

4. 命令层 — @ 指令动态范围（@dir/、@file、@功能名）。

5. 索引层 — 功能/接口索引（端点 ↔ 服务端 ↔ 前端落点）+ token 预算按目录配额 + 低信号优先截断。

---

功能特性

• 工作空间 — 新建 / 重命名 / 删除 / 切换命名工作空间；每个工作空间拥有一个主目录与有序的代码项目目录，并带逐目录访问模式。
• 工作空间就绪报告 — 顶部状态实时汇总目录有效性、前后端识别、沙盒写权限、Git 改动、接口配对、项目命令、上下文预算与关联会话；区分「已就绪 / 需关注 / 不可用」，点击可查看阻断问题和优化建议。
• 开始任务向导 — 输入业务目标并选择任务类型；只有高可信接口会自动收敛目录。可编辑启动/测试/构建/影响复核要求并查看命令覆盖；确认页会展示逐项目执行计划，并检查缺失目录、脏仓库、只读项目和验证缺口，阻断问题修复前不会创建会话。
• TaskMode 稳定工作流 — 功能开发、API 联调、Bug 修复、代码审查、跨仓重构和自定义任务由统一注册表驱动；每种模式都有明确的目录策略、上下文预设、必读数据块、验证、写权限和最终输出格式。
• 新建向导 — 填名称 + 基础路径，宿主创建同名主目录，并扫描识别 Java / Vue / React / Python / Go 等项目供多选；按技术栈自动分组、从真实项目脚本生成命令，并按项目数量建议加载模式。
• Monorepo 原生识别 — 支持 pnpm/npm/yarn/bun workspaces、Turbo、Nx、Lerna、Maven modules 与 Gradle multi-project；根目录只加载一次，同时把内部包边界和绝对路径注入会话。
• 三种添加目录方式 — 从 DSH 原生工作区选择、打开宿主目录选择器、或粘贴绝对路径。
• 目录三态访问 — readwrite（沙盒可写）、readonly（可见不可写）、disabled（不注入 prompt）。主目录恒为 readwrite。
• 工作空间模式 — anchor（主目录 = 文档锚点）与 single（主目录 = 核心业务代码）。
• 目录分组 — 可选分组标签（文档 / 后端 / 前端 / 参考 / 其他），在 prompt 中作为小标题渲染。
• 目录快照 — 保存 / 恢复 / 删除目录配置；恢复后立即重新同步沙盒白名单。
• 文件索引 + 加载模式 — 感知 .gitignore 的有界文件树扫描 + mtime 缓存；按工作空间选择加载模式控制注入细节。
• 功能/接口索引 — 从代码里抽取 HTTP 端点，并联结 服务端注册处 与 前端调用处 的 文件:行号；覆盖 TS/JS/TSX/JSX/Vue 与 Java/Kotlin/Go/Python/Ruby/C#。每条结果显示「精确 / 标准化 / 推断 / 单边」置信度，悬停可查看来源、匹配依据和索引时间。
• 符号级代码骨架 — 复用同一遍源码扫描抽取函数、类、接口、类型、枚举和常见组件，并保存压缩声明签名；任务胶囊只常驻命中的骨架，完整清单按会话隔离并按需查询，让 AI 先理解参数与类型边界，再决定是否读取源码。
• 最小依赖邻域 — 确定性解析本地导入，只把任务证据周围的一跳直接依赖与直接调用方常驻；完整依赖图按需查询，避免一个相关文件触发整模块读取。
• 精准测试映射 — 通过测试直接导入或保守的文件名规则关联源码与测试；任务胶囊只推荐相关测试，完整映射按需查询，验证先小范围执行再逐步扩大。
• 可解释端点关联 — 确定性优先、标准化匹配、启发式降级、结果可解释：/api/user/detail 与 /user/detail 可在剥一层 /api（可跟 /vN）后联结；Spring 类级与方法级路由会组合；命名端点引用则明确标为推断。动态或生成式路由仍应以实际代码为准。
• 本次变更涉及的端点 — 从 git 工作区变更出发，用同一遍扫描产出的「文件 → 端点」反向索引，列出这些改动文件声明或调用的端点及对端文件。这是「影响分析」的确定性版本：只查表，不预测。
• 逐项目命令手册 — 每个目录可填 run / test / build 三条命令（卡片内联编辑）；Node 项目读取包管理器、锁文件和真实 scripts，Java 识别 Maven/Gradle wrapper，Go/Python 使用保守默认值。命令带绝对路径注入 prompt，让模型知道在哪个目录自启与自证。
• AI 功能摘要（可选） — 开启后由模型为每个功能生成一句话摘要；按功能签名缓存并落盘，后台异步生成（不阻塞会话创建与首轮），任何失败静默降级。
• 上下文监控（估算） — 弹窗显示逐目录文件数、估算 token 与总预算：环形图总览 + 单行统计卡 + 横向可滚动条形图，超过 80% / 100% 给出警告。固定开销按 整块渲染量 − 各区块 推导，各项相加即实际注入量。
• 上下文预设 + 全局预算闸 — 新工作空间默认使用「平衡」，也可切换「省钱 / 深度分析 / 自定义」；预设统一调整加载模式和文件索引、功能索引、开发规范、项目命令预算。超出全局上限时优先保留任务、目录、显式 @ 引用与开发规范，并在面板和 prompt 中解释被截断或跳过的区块。
• 统一诊断中心 — 一次检查目录、沙盒白名单、DSH 服务、关联会话配置、索引缓存、token 偏差、项目命令、超大目录和配置版本；安全问题可一键刷新，复制报告会自动隐藏用户名和密钥。
• 真实 token 用量（实测） — 同一弹窗顶部显示模型上报的真实消耗：未命中输入 / 缓存读 / 缓存写 / 输出 / 缓存命中率 / 上下文占用条，以及 插件注入占比（注入估算 ÷ 最近一次请求的 prompt 总量）。估算与实测并排，差距大就意味着估算模型要修。
• @ 指令动态范围 — prompt 分节教会模型把 @ 前缀 token 解析为显式引用路径（@dir/、@file、@"含空格的路径"、@功能名），按需把文件纳入范围。
• 会话级按需上下文隔离 — 开发规范、项目命令和功能索引写入 ~/.dsh/dsh-workspace-combiner/sessions/<会话哈希>/；并行会话互不覆盖，关闭后自动清理。
• 任务上下文胶囊 — 开始任务后只常驻项目入口、配置、测试位置、当前改动、命中接口和建议读取顺序；完整文件树转为会话级按需文件，大型项目显著降低常驻 token。
• 沙盒联动 — 读写目录被推入 dsh-write-protect 的 writablePaths（写入 desktop profile 的 cordis.patch.yml，靠 patchReload: live 热生效）；底部图例显示实际进入白名单的目录数。
• 逐目录 Git 状态 — 每行显示分支，有未提交/未跟踪改动时以琥珀色 *N 标注，干净时为灰色，领先上游时 ↑N；非仓库目录不显示。
• 目录备注 — 任意目录可挂一段随手备注，行内编辑，随目录配置一起持久化。
• 目录角色徽标 — 主目录标记 Docs only、其余标记 Code，一眼区分锚点与源码（悬停有说明）。
• 注入 prompt 实时预览 — 展开只读区块，渲染当前配置将注入的 完整文本，可一键复制。
• 固定高度面板 + 局部滚动 — 面板填满侧栏，只有列表滚动，标题与「开始任务」按钮不会滚出屏幕。
• 紧凑入口卡 + 弹窗 — 高级配置、开发规范、注入预览、上下文预算都收成左栏入口卡，点开才是弹窗，不再长期占据面板高度。
• 键盘 — Cmd/Ctrl+N 打开开始任务向导、Cmd/Ctrl+K 命令面板、Esc 关闭；命令面板同时保留无任务范围的快速会话。

---

架构

~~~text

dsh-workspace-combiner/

├── package.json # dsh 字段：bundle.patch + client.inject

├── cordis.patch.yml # 注册补丁

├── tsconfig.json # 类型检查

├── tsdown.config.ts # 双入口构建：host + client

└── src/

├── invariant.ts # 共享常量（插件 id / API 路径 / prompt 排序 / 默认预算）

├── prompt.ts # 多工作区 prompt + 文件索引 + 功能索引渲染

├── store.ts # 宿主持久化（~/.dsh/dsh-workspace-combiner.json）

├── sandbox-sync.ts # dsh-write-protect 可写根同步

├── routes.ts # /api/dsh-workspace-combiner 路由（仅 loopback）

├── core/

│ ├── types.ts # 共享类型（WorkspaceRef / Workspace / CodeIndexEntry / ...）

│ ├── fileTree.ts # 平台无关的文件树类型与纯工具（计数/渲染/token 估算）

│ └── validate.ts # 共享的目录项校验

├── host/

│ ├── index.ts # host 入口：prompt 分节 + session/created + 路由 + 缓存

│ ├── projectDetector.ts # 扫描目录识别项目类型

│ ├── fileIndex.ts # 感知 gitignore 的有界文件树扫描 + 递归计数 + mtime/TTL 缓存

│ ├── codeIndex.ts # 功能/接口索引抽取 + 内存/磁盘缓存

│ ├── codeIndexSummary.ts # 可选：AI 功能摘要（后台生成 + 落盘缓存）

│ ├── gitStatus.ts # 逐目录 分支 / 改动 / 未跟踪 / 领先

│ └── contextStats.ts # token 估算 + 逐目录上下文统计

└── client/

├── index.ts # client 入口：侧栏图标 + 中心列面板

├── types.ts # client 侧镜像类型

├── locales.ts # 中英词典 + tt() 助手

├── api.ts # client -> host fetch API

└── panel/

├── WorkspaceCombinerPa

…(truncated)