为全栈开发者而生：把前端仓库、后端仓库与文档锚点捆进同一个 AI 会话。绝对路径注入、沙盒可写根自动同步，接口变更在同一轮对话里前后端一起改。
中文 · English
--- 一个用于 DSH（DeepSeek Harness）的 [Cordis](https://github.com/cordiverse/cordis) 双面插件，把一组仓库组织成协同的 **多工作区联合开发** 上下文。 插件在左侧边栏注册一个 **工作区组合器** 面板。每个「工作空间」绑定一个主目录（工作区锚点——放文档与非代码资产）加一组有序的 **代码项目** 目录（例如一个后端仓库、一个前端仓库）。新建会话时，插件把所有生效目录的绝对路径注入 system prompt，并把可写目录同步进 [dsh-write-protect](https://github.com/azazo1/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/ ├── WorkspaceCombinerPanel.tsx # 面板主体 + 图标 ├── controller.ts # 状态管理 ├── NewWorkspaceWizard.tsx # 新建工作空间向导 ├── typeBadge.tsx # 项目类型徽标 ├── naming.ts # 名称清洗 / 查重 └── styles.ts # 注入的 style 块（随主题适配） ~~~ ### 数据流 ~~~text [客户端面板] --POST /api/.../...--> [宿主 store] │ session/created（顶层新建会话） ▼ selectionBySession: sessionId -> { directories, mode, loadMode, tokenBudget, entries, codeEntries, codeIndexBudget } ▼ systemPrompt.section(text 函数按会话渲染；同会话快照复用已渲染文本) ▼ 注入「多工作区联合开发模式生效」+ 目录清单 + 文件索引 + 功能/接口索引 + @规则 ~~~ 目录变化时宿主会更新 desktop profile 的 `cordis.patch.yml` 中 `dsh-write-protect-policy` 的 `writablePaths`；DSH 以 `patchReload: live` 热加载， 无需重启即生效（不再依赖任何第三方私有远程服务）。 --- ## 安装（本地目录） > 前置：已安装 DSH，且依赖插件可用。 ~~~bash # 0) 依赖插件（必需） dsh plugin --profile desktop add dsh-write-protect # 1) 构建 lib/（host + client） cd /path/to/dsh-workspace-combiner pnpm install pnpm build # 2) 加载本插件 dsh plugin --profile desktop add file:./dsh-workspace-combiner # 3) 校验 dsh plugin --profile desktop ls dsh-workspace-combiner # 4) 重启 DSH Desktop（web profile 则重跑 dsh web） ~~~ 改动源码后：`pnpm build`，然后把构建产物同步到 profile 的插件副本目录并重启 （或移除插件后重新添加）。 --- ## 使用
