多根工作区 keatsyh/dsh-plugin-addir

dsh-plugin-addir

让 DeepSeek Harness 支持多根目录工作区与上下文动态注入灵感来自 OpenAI Codex --add-dir 与现代 AI IDE 多根目录工作区设计

💡 为什么需要 addir？

默认情况下，DeepSeek Harness 的工作区通常只绑定一个工作目录（Primary Root）。遇到下面这些复杂开发场景，就常常受限：

- 跨仓库 / 跨模块协作：前后端工程分离（如 frontend/ 与 backend/），智能体需要同时理解接口定义与业务实现；
- 共享代码与公共库：项目依赖独立的公共组件库（如 shared-ui/、core-lib/），需要跨目录检索却不想反复复制代码；
- 只读规格与文档参照：引入只读的设计规范、API 契约或第三方代码，需要智能体参考但绝不允许误改。

dsh-plugin-addir 彻底打破单一工作区限制！它支持在当前工作区下关联任意多个外部目录，配合直观的图形化管理界面、自动上下文注入与细粒度只读保护，让智能体自如跨目录协同工作。

✨ 核心特性

- 📁 多根目录关联（Multi-Root Workspaces） 支持为任意工作区挂载多个额外文件夹，为每个目录配置易记的别名（Alias）、描述信息及只读（Read-Only）标记。
- 🧠 上下文动态注入（Context Injection） 每轮对话自动将当前生效的目录树注入给大模型上下文。智能体可直接理解 [别名]/path 或 别名:path 路径简写。
- 🛡️ 细粒度只读防护（Read-Only Protection） 勾选 只读 的目录将被文件工具守卫拦截 write / edit 操作，彻底避免智能体误改公共依赖或文档。
- 🖥️ 无缝原生 UI（Native GUI Integration） 深度集成 DSH 工作区列表菜单（⋯ → 编辑）。弹窗支持调用系统原生目录选择器，体验丝滑自然。
- 💾 跨会话持久化（Auto Persistence） 关联关系按工作区根路径隔离并持久化至本地存储（$DSH_HOME/storages/addir.json），应用重启后自动恢复。
- 🤖 智能体自主管理（Agent Tools） 内置 addir_list、addir_add、addir_remove 工具，允许智能体在对话中动态扩展视野；也可一键关闭权限，由用户完全掌控。

🖥️ 界面展示

1. 工作区菜单入口

在工作区列表中点击目标项目的「⋯」按钮，选择「编辑」：

工作区菜单

2. 多目录图形化管理弹窗

支持修改工作区名称、使用系统原生目录选择器添加文件夹、配置个性化别名，并可单独勾选「只读」权限：

编辑项目弹窗

注入到模型的上下文示例

启用 enableContextInjection 后，插件会在每轮对话自动向大模型注入当前工作区的生效目录表：

Active Workspace Directories
- [primary] /Users/dev/repo/frontend (Primary root)
- [backend] /Users/dev/repo/backend - 核心 API 服务
- [specs] /Users/dev/repo/api-specs [Read-Only] - OpenAPI 契约定义

智能体能够据此识别每个目录的作用，并使用 [backend]/src/app.ts 或直接使用绝对路径进行高效分析。

🚀 快速上手

1. 安装插件（参考下方安装指南）；
2. 关联目录：在工作区列表点击「⋯」→「编辑」，点击「添加文件夹」选择本地目录，设置别名（如 backend）并保存；
3. 开始对话：直接对智能体说：
"请阅读 [backend] 目录下的路由定义，并在当前前端项目中生成对应的 API 请求函数。"

📦 安装指南

1. 通过 DSH 插件市场 / 设置面板安装

打开 DeepSeek Harness 桌面端或 Web 端，进入 设置 → 插件管理，搜索 dsh-plugin-addir，点击安装即可。

2. 通过命令行安装（推荐）

Web Profile（推荐在 Web 版使用）
dsh plugin --profile web add dsh-plugin-addir

桌面端 Desktop Profile 注意：桌面端首次使用请先启动一次应用以初始化 profile，完全退出应用后再执行安装命令，随后重新打开应用
dsh plugin --profile desktop add dsh-plugin-addir

Headless / 自定义 Profile
dsh plugin --profile headless add dsh-plugin-addir

[!NOTE]
本插件自带 bundle patch（cordis.patch.yml），安装时会自动向 profile 注册 id: addir，无需手动修改配置文件。

3. 从源码构建安装（开发者模式）

克隆仓库
git clone https://github.com/keatsyh/dsh-plugin-addir.git
cd dsh-plugin-addir

安装依赖并构建（prepare 会自动编译 lib/ 产物）
pnpm install

软链接安装到目标 profile
dsh plugin --profile web add "link:$PWD"

⚙️ 配置说明

所有配置项都有合理的默认值。你可以在 DSH 的插件设置页里直观调整，也可以在 profile 对应的 cordis.patch.yml 中覆盖配置：

| 配置项 | 类型 | 默认值 | 说明 |
| enableTools | boolean | true | 是否向智能体暴露 addir_ 工具（允许模型自己增删目录） |
| enableContextInjection | boolean | true | 是否在每轮对话开始前向系统提示词注入工作区目录表 |
| enforceReadOnly | boolean | true | 是否在底层工具拦截对标记为只读目录的文件写入与编辑 |
| defaultDirectories | Array | [] | 启动时预先关联的静态目录列表（包含 path, alias, description, readOnly） |

YAML 配置示例

- id: addir
config:
enableTools: false # 仅允许在 UI 界面中手动管理，禁止智能体自行增删 enableContextInjection: true # 保持提示词注入 enforceReadOnly: true # 开启只读保护 defaultDirectories:
- path: /data/docs/specs
alias: specs
description: API 规范文档 readOnly: true

[!TIP]
界面里所做的新增、编辑和删除操作，会实时持久化在 $DSH_HOME/storages/addir.json 中，按规范化工作区根路径索引，无需担心重启丢失。

🛠️ 智能体工具（Agent Tools）

当 enableTools 开启时，智能体可自主使用以下工具：

| 工具名称 | 参数 | 说明 |
| addir_list | — | 查看当前工作区已关联的所有目录（包括主根目录、别名、描述与只读标记） |
| addir_add | path (必填)alias (可选)description (可选)readOnly (可选) | 动态关联一个额外目录。支持传入绝对路径或相对工作区主目录的路径 |
| addir_remove | pathOrAlias (必填) | 解除关联指定目录（支持按绝对路径或别名查找，主根目录不可移除） |

如不希望智能体拥有自主挂载权限，只需将配置中的 enableTools 设为 false。

🧩 开发者 API

其他插件或扩展可以通过 Cordis 服务上下文直接调用 ctx.addir：

import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
// 获取当前会话下关联的目录列表 const dirs = ctx.addir.list(sessionId)

// 动态关联额外目录
ctx.addir.add({
path: '/path/to/shared-lib',
alias: 'shared',
description: 'Shared utilities',
readOnly: true,
}, sessionId)

// 解析带别名的路径为真实绝对路径（例如 '[shared]/utils.ts' -> '/path/to/shared-lib/utils.ts'） const resolved = ctx.addir.resolvePath('[shared]/utils.ts', sessionId)

// 检查某个路径是否归属于当前工作区或其关联目录 const isIncluded = ctx.addir.isUnderWorkspace('/path/to/file.ts', sessionId)

// 检查某个路径是否处于只读保护范围内 const isReadOnly = ctx.addir.isReadOnly('/path/to/file.ts', sessionId) }

❓ 常见问题 (FAQ)

Q: 桌面端（Desktop）安装后没有出现「编辑」菜单？

桌面端应用在首次安装插件时，需要完全退出应用进程（macOS 请使用 Cmd + Q，Windows 请从托盘或任务管理器完全退出），再次启动应用使客户端扩展脚本加载生效。

Q：标记为只读的目录，智能体还能阅读或搜索代码吗？

可以。只读保护只拦截 write、edit 这类修改文件的工具调用，代码阅读（read）、检索（grep / glob）等完全正常运作。

Q：可以在多个不同的工作区中使用相同的别名吗？

可以。目录关联数据严格按照各工作区的根目录路径隔离存储，不同工作区之间的别名互不影响。

Q：如何防止智能体自作主张关联新目录？

在 DSH 插件设置中将 enableTools 开关关闭（或在配置文件中设为 false），智能体就不再拥有 addir_ 工具，但你依然可以在 GUI 弹窗中手动管理目录。

💻 本地开发

安装依赖
pnpm install

运行单元测试与集成测试
pnpm test

类型检查
pnpm run typecheck

构建打包（含 client bundle 语法检查与 d.ts 生成）
pnpm run build

架构提示：客户端代码采用经典脚本与 DSH 共享模块加载器注册（window.__ModuleLoader__.load），使用宿主提供的 React 运行时。工作区菜单入口通过 DOM 适配器挂载（src/client/workspace-menu.ts）。

📄 License

本项目基于 MIT 许可证 开源。