dsh-ProjectModel

August 23, 2026 · View on GitHub

在同一个会话里跨多个项目文件夹工作：把一组项目文件夹组织成一个「项目组」，agent 可以直接读写组内任意文件夹的文件、列出目录、运行命令（git / npm / 构建等）——无需手动切换、无需为每个项目另开会话，像 Codex 的多文件夹工作区一样自然。

界面预览

dsh-ProjectModel 界面预览

为什么用「项目组」模式？

场景原生 DSH（单工作区）项目组模式
跨项目工作一个会话绑定一个工作区目录，跨项目要另开会话一个会话内直接操作组内任意文件夹
上下文连续性每个会话独立记忆，A 项目的结论带不到 B 项目对话历史与理解全程保留，跨项目无缝衔接
文件夹切换需要手动切换工作区/目录无需切换——folderId 直接指定目标文件夹
项目范围控制工作区外不可操作（沙箱限制）只对已注册文件夹开放，越界拒绝，安全可控
配置持久化—settings 持久化，重启/换机迁移不丢

核心优势：

  1. 一个会话，多个项目 — 把相关项目放进一个组，在同一段对话里连续处理（改 A 的代码 → 跑 B 的测试 → 对比两者），上下文不中断、不用重复交代背景。
  2. 像 Codex 一样自然的多文件夹工作区 — 组即工作集合，agent 在对话中直接对任意文件夹读写文件、运行命令，无需"先选中"、无需手动切换。
  3. 安全地访问工作区之外的项目 — 会话沙箱只放行工作区目录；项目组提供受控通道：所有文件操作被限制在已注册文件夹内（fs.contains 越界拒绝），写入以目标文件夹为沙箱根，无需放开全局权限。
  4. 开箱即用的命令执行 — 在任意项目文件夹运行 git / npm / 构建等命令（自动探测 pwsh 与 Windows PowerShell 5.1，跨版本可用）。
  5. 上下文自动感知 — agent 的提示词自动带上项目组与全部文件夹列表，模型无需先探索就知道有哪些项目、该怎么选。
  6. 持久化、可迁移 — 配置存于 dsh settings（settings.yaml），重启不丢；复制 profile 即可换机迁移。
  7. 对界面零侵入 — 纯追加插槽（设置页 + 输入框状态条），不改动原始侧栏与对话框；一键安装、干净卸载。
  8. MIT 开源、一条命令安装 — dsh plugin --profile web add . 装到任意机器（官方插件机制，自动注册 bundle 层，无需手改配置）。

功能

  • 项目组：一个组 = 多个项目文件夹，可任意增删、重命名、设为默认（默认只是省略 folderId 时的回退，不是必需）
  • 项目说明：每个文件夹可设一句「项目说明」（desc），设置页直接编辑，list 与模型提示词都会带上（标题 路径（说明））——AI 看一眼就能判断该操作哪个目录
  • 跨文件夹工作：宿主端注册 project 模型工具，可对组内任意文件夹直接操作（通过 folderId 指定目标，无需切换）
    • list — 查看项目组与全部文件夹及其 folderId 与说明（返回当前工作区键）
    • readFile / writeFile / listDir — 对指定文件夹读写文件、列目录（路径限制在注册的文件夹内，越界拒绝）
    • run — 在指定文件夹运行命令（经 PowerShell，自动探测 pwsh / Windows PowerShell 5.1）
    • agents — 查看指定项目（folderId）的 AGENTS.md（缺省读项目根 AGENTS.md，缺失返回 found:false）
    • setFolderDesc — 设置某文件夹的项目说明（别名 setdesc）
  • 项目组跟随工作区：默认项目组与默认文件夹按工作区（会话 cwd）独立保存；新建工作区不继承旧工作区的选择，可分别设置（设置页顶部会显示当前工作区名）
  • 组内文件路径默认放行：v1.1 起，会话内标准文件工具（read/write/edit）命中项目组文件夹且处于 workspace-write 模式时默认允许读写，不再弹沙箱批准询问；命令执行仍走 project run
  • UI：
    • 设置 → 「项目组」管理页（创建组、添加/移除文件夹、设为默认、展开查看各项目 AGENTS.md）
    • 输入框上方的状态条（项目组名 + 文件夹标签；默认项目带 ★「默认」标识；点击标签展开查看 AGENTS.md）
  • 持久化：配置存于 dsh settings（settings.yaml），重启不丢
  • 上下文感知：agent 的提示词自动带上项目组与全部文件夹列表
  • 动作名兼容别名：read/write/list_dir/set_active/agents 等

为什么不在左侧栏？侧栏的「工作区区域上方」没有可追加的插槽——只有替换整个侧栏外壳才能放内容，会破坏原始侧栏样式（设置入口等）。因此本项目采用纯追加式插槽（设置页 + 输入框状态条），完全不改动原始界面。

架构

部分机制
宿主插件 lib/index.js状态注册表 + /api/project-groups HTTP API（webServer 路由）+ project 模型工具（tools）+ 提示词上下文（systemPrompt）+ settings 持久化
浏览器插件 lib/client.js__ModuleLoader__ bundle，注册 settings.section 与 conversation.input.dock 两个追加插槽，通过 fetch 调用宿主 API
安装dsh plugin --profile web add .：pnpm 安装 + 自动加入 dsh.profile.bundles（包声明 dsh.bundle.patch → 见 cordis.patch.yml）
通信浏览器 → /api/project-groups（GET 查询 / POST 变更，JSON）
依赖@deepseek-ai/dsh-tools、@deepseek-ai/schemastery、@deepseek-ai/dsh-settings（均随 dsh 安装提供）

宿主插件通过 inject: ['settings','webServer','tools','systemPrompt'] 等待核心服务挂载后再激活。

安装

前置条件

  • 已安装 DeepSeek Harness（dsh CLI，本插件按 web profile 编写）
  • pnpm（dsh plugin 内部转发给 pnpm）
  • 已初始化过目标 profile（不存在时会自动创建）

方式一：dsh plugin 官方安装（推荐）

本包声明了 dsh.bundle（见 cordis.patch.yml），所以 dsh plugin add 会把插件装成 profile 的正式依赖并自动加入 dsh.profile.bundles 层——不需要复制文件、不需要手写 junction、不需要手改 cordis.patch.yml。

# 克隆后进入仓库目录，然后：
dsh plugin --profile web add .

命令做了什么：

  1. 在 profile 目录（$DSH_HOME/profiles/web/）执行 pnpm add <本仓库路径>，把 dsh-ProjectModel 装进 node_modules（pnpm store）
  2. 自动把 dsh-ProjectModel 追加到 package.json 的 dsh.profile.bundles（因为它声明了 dsh.bundle.patch）
  3. 重启 dsh 后，bundle 的补丁层自动注册 project-groups 插件行（宿主 + 浏览器两侧都生效）

开发时想直接联动源码？ 用 link 方式安装，改完仓库代码重启即可生效，无需重新安装： dsh plugin --profile web add link:.

更新：dsh plugin --profile web update dsh-ProjectModel（link 方式安装无需更新，直接改源码） 卸载：dsh plugin --profile web remove dsh-ProjectModel

重启可以用仓库里的 node restart.mjs（自动找端口进程 → 停止 → 重启 → 验证 /api/project-groups），或手动在启动 dsh 的终端 Ctrl+C 后重新运行 dsh web。

方式二：手动放置（备用，不推荐）

如果你不想用 pnpm：把仓库复制到 $DSH_HOME/profiles/web/plugins/dsh-ProjectModel/，然后在 $DSH_HOME/profiles/web/cordis.patch.yml 追加：

- insert:
    - id: project-groups
      name: dsh-ProjectModel

并确保该路径能被 profile 侧的 Node 解析到（例如在 $DSH_HOME/profiles/node_modules/dsh-ProjectModel 建一个指向它的 junction）。手动方式不享受 dsh plugin 的依赖管理与自动 reconcile，仅作兜底。

验证安装

  • 浏览器打开 http://127.0.0.1:3080/api/project-groups，应返回 {"groups":[...],...}（未配置时为空列表）
  • 设置页出现「项目组」；输入框上方出现项目组状态条
  • 对话中 agent 的上下文出现「项目组：…」行

使用示例

在对话里直接说：

  • “把 E:\proj-a 和 E:\proj-b 加进项目组「后端」”
  • “在 QzoneDown-Go 里看下 go.mod”
  • “对 SSL-Assistant 跑一下 git status”
  • “同时对比一下 QzoneDown-Go 和 SSL-Assistant 的 go.mod”
  • “看看 QzoneDown-Go 的 AGENTS.md 里对代码风格有什么要求”（模型会调 project agents）
  • “把这个工作区的默认项目组设为 github”（新工作区首次关联，模型会调 project setActive）
  • “给 QzoneDown-Go 加一句说明：QQ 空间下载器主项目”（模型会调 project setdesc）

agent 会直接用 project 工具对相应文件夹操作（folderId 指定目标），全部在同一个会话内、无需手动切换。

卸载

  1. dsh plugin --profile web remove dsh-ProjectModel（卸载依赖并从 dsh.profile.bundles 移除）
  2. 重启 dsh 并刷新页面

若曾用旧版手动方式安装：删除 plugins\dsh-ProjectModel 目录、profiles\node_modules\dsh-ProjectModel junction，以及 cordis.patch.yml 里手写的 insert 块，再执行上面的官方命令。

配置（settings.yaml 里的 project-groups: 段）可手动删除。

常见问题

Q: 为什么普通文件工具（read/write/edit）访问项目文件夹不再弹批准了？ v1.1 起，项目组文件夹被当作额外的写入根：标准文件工具命中组内路径且会话处于 workspace-write 模式时默认放行，不再询问（只覆盖文件读写；bash/pwsh 命令仍以会话工作区为界，项目内跑命令请用 project run）。匹配先走规范的路径前缀（零开销），再以真实文件系统身份兜底。

Q: dsh plugin --profile web add . 后还要手动改配置吗？ 不用。本包声明了 dsh.bundle.patch，dsh plugin 的 reconcile 会自动把它加入 dsh.profile.bundles；启动时 bundle 补丁层自动注册插件行。link:. 方式安装时，改仓库代码后重启即生效。

Q: 为什么不在左侧栏显示？ 见上方「为什么不在左侧栏」：没有可追加的插槽，替换侧栏会破坏原始样式。

Q: 改代码后如何生效？ lib/ 改完 → 重启 dsh（宿主）→ 刷新浏览器（客户端 bundle 会以新 rev 下发）。

License

MIT