dsh-codex-project

DSH 工作区共享子目录插件 —— 源自 Codex 的项目处理思想：一个工作区可以挂载任意数量的共享子目录（可跨盘符），该工作区的 DSH 会话可以像对待自己的工作区一样读写这些目录——全程保持 workspace-write 权限，永远不需要 danger-full-access。

设计思想

Codex 处理项目时，一个"项目"往往横跨多个目录：主代码库、共享库、文档、数据目录。传统做法要么给模型 full access（危险），要么逐个授权（繁琐）。

本插件的模型是 Codex 式的项目共享：

一个共享配置（记录）= 一个主根（该工作区自身的 path）+ 任意数量的共享子目录（跨盘符）
命中该配置的会话 → 可读写该配置的全部可写根（主根 ∪ 现存共享子目录）

• 单配置模型：会话的可写集合 = 其 cwd 命中的那一条配置的可写根（无并集、无叠加），行为可预期；
• 单边命中：会话 cwd（规范路径）== 某条记录的 path 即命中该条记录（锚定）；共享子目录里的会话不会仅因该目录出现在别人配置里而命中；
• 不强制注册：共享子目录可以是裸目录，不必是 DSH 注册的工作区；
• 不升级权限：仍在 workspace-write 权限级内，只是把可写集合从单根扩展为多根（Windows ACL 受限令牌 + 空间级 SID）。

功能特性

架构总览

┌─────────────────────────── DSH web ───────────────────────────────────┐
│  (client half)                                                        │
│  侧边栏工作区「…」菜单 ──注入「打开本地目录」+「管理工作区」──▶ 本地动作/弹窗  │
│        │ fetch()                                                      │
│        ▼                                                              │
│  /codex-project/api  (CRUD + 项目目录树，loopback 守卫)                │
└───────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────┐
│  (host half)  四个独立钩子，共用命中判定 matchingWorkspace              │
│                                                                       │
│  ① ctx.webServer.register    ─── HTTP 路由（CRUD / 文件读写）         │
│  ② ctx.on('agent/pre-step')  ─── 折叠 <system-reminder> 目录清单     │
│  ③ ctx.tools.register        ─── add-dir 模型工具                    │
│  ④ sandbox.confine wrap      ─── 多根 runner（lib/runner.js）        │
│                                                                       │
│  ⑤ ctx.fs 提供者（bundle patch 替换核心 fs-sandbox）                  │
│     └── lib/fs.js 多根 fence（与 ④ 共用命中判定）                    │
│                                                                       │
│  配置外 / 单根 / 无 cwd 的会话 → 四个钩子全部纯透传（零影响）         │
└───────────────────────────────────────────────────────────────────────┘

工作原理

本插件通过 Cordis（DSH 的 IoC 框架）提供的四个钩子切入 DSH 的运行循环，不侵入 DSH 源码。

1. HTTP 路由 — client/host 之间的桥梁

ctx.webServer.register({ kind: 'prefix', path: '/codex-project/api', handler: ... })

DSH 启动时，插件把 /codex-project/api/* 路由挂到宿主 HTTP 服务器上。client 的 api.ts 通过 fetch() 调用这些路由，host 侧处理后返回 JSON。配置 CRUD、文件读写、目录列表全部走这条路。

2. agent/pre-step 事件 — 折叠上下文提醒

ctx.on('agent/pre-step', async ({ agent, messages }, next) => {
  const decision = await next()
  return foldWorkspaceContext(decision, messages, agent.session)
})

DSH 的 agent 循环是：收消息 → pre-step 事件链 → 模型推理 → 工具执行 → 输出。agent/pre-step 是推理前的最后一道关卡。

插件在这里计算当前会话的共享目录清单，生成 <system-reminder> 消息插入模型上下文。提醒只在附加目录集合变化时重新折叠：新会话首次播种一次，add-dir / 管理弹窗改动目录后才在下一轮重新注入，目录未变时跨轮不重复叠加。提醒列出主目录与附加目录，并注明附加目录与主目录权限一致——它们处在同一个 workspace-write 边界下（插件在每个存活根上授予工作区级 SID，附加目录绝不超出主根权限），模型可统一对待。

3. ctx.tools.register() — 注册 add-dir 工具

ctx.tools.register(defineAddDirTool(deps))

注册后模型在推理时可以看到 add-dir 工具的 schema，并主动调用它添加新目录。执行流程：

模型调用 add-dir(path)
  → 插件通过 ctx.approval.request() 请求用户确认
  → 用户批准 → 写入 dirs.json
  → 目录立即进入可写集合（无状态重校验）

4. sandbox.confine 包装 — 劫持进程沙箱

const original = sandbox.confine
sandbox.confine = (argv, policy) => {
  // 非 Windows / 非 workspace-write / 无匹配记录 / 单根 → 透传原逻辑
  // 有多根共享目录 → 返回插件 runner.js 的 ConfinedArgv
  return { argv: [node, runner.js, --bind root1, --bind root2, --, ...原命令], ... }
}

DSH 在执行 shell 命令时调用 sandbox.confine(argv, policy) 决定如何隔离进程。插件 wrap 了这个方法：无共享目录时行为与 DSH 原生完全一致；有多根时路由到 runner.js，由它在 Windows 上创建受限令牌、给每个存活根授予 Write ACE、在该令牌下 spawn 子进程。

数据流全景

用户在 GUI 输入命令
  ↓
DSH agent 循环启动
  ↓
pre-step 事件触发 → 插件折叠 <system-reminder>（钩子 2）
  ↓
模型推理（已看到共享目录清单）
  ↓
模型决定执行 shell 命令
  ↓
sandbox.confine → 插件 wrap 决定路由（钩子 4）
  ↓
  ├─ 无共享目录 → 核心 runner（单根 workspace-write）
  └─ 有多根共享目录 → 插件 runner.js（多根受限令牌 + SID）
  ↓
子进程执行，fs 操作经过 ctx.fs（插件的 CodexProjectFileSystem）
  ↓
fs fence 按可写根集合放行/拒绝（与 runner 共用同一命中判定）

安全模型

• 权限不升级：多根 runner 仍是 workspace-write 受限令牌（拒绝列表 + 空间级 SID 写授权），只是 Write ACE 覆盖配置的可写根；
• 空间级 SID：每条配置一个专属 SID（config 目录 + workspace id 摘要）——核心单根会话的 SID 无法沿着共享目录的 ACE 进入其他根，空间会话的令牌也无法使用别的根的 ACE；
• 失败契约：runner 任何失败输出 codex-project-run: <detail> 并以 127 退出，绝不以非受限方式 spawn 子进程；
• 失效根收窄（narrowing）：配置里某个共享子目录事后被删除（被动失效）时，可写集合收窄到现存根——死根本身物理上已不可写，其存在性失败不阻塞其余根，也不影响任何无关会话；上下文提醒给死根加 (⚠ directory missing) 标注，host 日志对每个空间首次 warn 一次、之后 debug；root 目录恢复后无需重启或改配置即可重新进入可写集合（无状态重校验）；
• 权限提示不升级：上下文提醒说明附加目录与主目录权限一致——即所有根共享同一个 workspace-write 边界，绝不暗示高于该边界（如 full access）。[sandbox: …] 拒绝标记不变；实际读写仍以沙箱实测为准。

已知边界（设计取舍）

• 重叠根歧义：同一目录同时是两条记录的 path 时，cwd 落在该目录的会话匹配配置文件中靠前的那条（可写集合随配置顺序漂移）。建议共享子目录互不重叠；
• standing ACE 常驻：runner 在每个根上物化的空间 SID Write ACE 是常驻的（跨会话复用缓存，dispose 只回收私有 temp）。删除配置不会回收已打上的 ACE（孤立 ACE 无令牌携带，无害但会累积）；
• 无只读共享：所有根都授予读写——想"只读共享"（如只允许读 DSH 源码树）需要后续特性；
• 提醒不重注入：每会话一次性；恢复的会话若已有相同提醒不再折叠（带着旧文案恢复的会话会在下一条 user 消息后折叠进当前文案）；
• 增删仍校验存在性：通过 API 保存的共享子目录要求存在（主动操作 fail loud）；只有目录事后消失的被动失效会被收窄，不阻塞其余根。

配置文件

默认 ~/.dsh-codex-project/dirs.json（环境变量 DSH_CODEX_PROJECT_CONFIG 可覆盖），形状：

{
  "workspaces": {
    "<workspaceId>": {
      "path": "主根（该工作区自身的路径）",
      "dirs": ["共享子目录1", "共享子目录2"]
    }
  }
}

• path 恒为该工作区自己的主根（锚定，记录键即工作区 id）；dirs 为额外可写目录；
• 缺省文件 = 无配置 = 纯透传；
• 失效根不自动清理：目录消失不会改写配置文件（对齐 DSH 核心"被动失效保留记录、降级显示"策略）；通过「管理工作区」弹窗或 API 显式移除。

HTTP API

/codex-project/api 前缀（loopback Host 守卫），全部 JSON：

错误：400 非法输入、403 项目根之外（fence）、404 未知工作区、405 未知方法/路由。

安装

前置：已装好 DSH（dsh web 能正常运行），Node.js ≥ 20、pnpm ≥ 10。

dsh plugin --profile web add @luoxunhao/dsh-codex-project

装完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到「项目文件夹」tab 和管理工作区入口。client 改动无需重启 DSH；host 改动需重启。

git clone <repo-url> && cd dsh-codex-project
pnpm install && pnpm build
dsh plugin --profile web add <本仓库绝对路径>

dsh --profile web --patch <本仓库绝对路径>/dev.patch.yml

开发

pnpm typecheck          # 类型检查（tsc --noEmit）
pnpm test               # 单元测试（vitest，12 个文件）
pnpm build              # 构建 lib/（tsc types + tsdown：host ESM + client CJS + runner + fs）
pnpm proto:verify       # 多根 runner 原型实证（Windows ACL，需先 build）

架构约束：

• client bundle 禁止 value-import 其他插件的运行时符号（纯度门）；与 DSH 源码的集成只走公开/只读 API；
• browser bundle 无 node:path——路径运算放 src/client/paths.ts；
• 「项目文件夹」tab 通过 betterSidebar.registerTab 接入（仅在 better-sidebar 安装时注册），client 侧用结构化再声明消费；
• fence 只改一处：复用 dirs-api.ts 的 fenceFor，不要另写一份 roots 推导。

测试

tests/（vitest，browser 组件用 jsdom）：

• dirs-api.spec.ts — CRUD + 锚定 + 失效根 + 项目解析 + 目录列表（排序/fence 403/跨盘根）+ 读/写/文件字节与下载 disposition
• project-tab.spec.tsx — 无配置回退单根、根行（主/共享/缺失）、懒加载、点击即内联预览、右键菜单
• file-reference.spec.ts — @ 引用源注册 / 注入 / 序列化
• client-apply.spec.tsx / client-components.spec.tsx — 插件形态、菜单注入、管理弹窗
• fs-fence.spec.ts / seam-wiring.spec.ts — 多根 fence 收窄/隔离/自愈、runner 接线
• context-injection.spec.ts — 上下文提醒（文本组成/折叠位置/去重/缺失标注）
• add-dir.spec.ts — add-dir 工具（校验/审批/持久化）
• plugin-shape.spec.ts — 插件导出形态

新增 API 面（如 SpacesApi 加方法）时，记得同步更新各测试里的 fake，否则 typecheck 会因缺方法失败。