dsh-ProjectModel

Readme

# dsh-ProjectModel · DeepSeek Harness 项目组插件

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

## 界面预览

![dsh-ProjectModel 界面预览](preview.png)

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

| 场景 | 原生 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](https://pnpm.io/installation)（`dsh plugin` 内部转发给 pnpm）
- 已初始化过目标 profile（不存在时会自动创建）

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

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

```bash
# 克隆后进入仓库目录，然后：
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` 追加：

```yaml
- 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