---

description: "为 DeepSeek Harness Web 增加 Monaco 文件管理与编辑视图。" kind: "package-bundle"

dsh-file-manager

dsh-file-manager 是 DeepSeek Harness 的外部 Bundle。它在 Web Session 的 conversation.view 中增加 File，提供工作区文件树、文本查看与编辑、Monaco 语法高亮、明暗主题、中英文文案、Cmd/Ctrl+S 保存、外部修改冲突保护和 Session 状态恢复。

File Manager 使用当前 Session 的权威工作目录。它不会修改 DSH 源码、替换 provider 或改变其他 Agent 预设；安装到任意兼容 DSH 的 Web Profile 后即可使用。

环境要求

• Node.js ^22.19.0 或 >=24.0.0
• pnpm 11.7.0
• Git，且克隆时初始化 submodule

本项目固定使用仓库内 upstream/deepseek-harness 指向的 DSH 版本。该 submodule 只参与开发和打包，发布归档不包含 upstream/。

从克隆到启动 Web

git clone --recurse-submodules <repository-url> D:\dsh-file-manager
Set-Location D:\dsh-file-manager
pnpm install --frozen-lockfile
pnpm dev

pnpm dev 会完成以下工作：

1. 在需要时安装并构建 upstream/deepseek-harness。
2. 生成 Remote 合约并构建本插件的 Host、Client 和 Monaco 资源。
3. 首次运行时把当前仓库稳定链接到隔离的 .tmp/dsh-home；后续构建复用该链接。
4. 启动 DSH Web。

打开或创建一个 Session，然后切换到 File 即可。File Manager 使用该 Session 的工作目录；切换 Session 时文件树和编辑状态相互隔离。

如果克隆时没有携带 submodule，先执行：

git submodule update --init --recursive

常用命令

命令	用途
pnpm dev	构建、确保本地开发链接并启动隔离的 DSH Web
pnpm dev:install	构建、打包并执行一次真实 tarball 安装，但不启动 Web
pnpm dev:web	启动已经安装好的隔离 Web，不重新构建
pnpm dev:remove	从隔离 Web Profile 移除开发插件
pnpm build	先准备 DeepSeek Harness，再生成并构建本插件
pnpm build:embedded-codex	构建、打包本插件，并安装到同级 dsh-embedded-codex 仓库的隔离开发 Web Profile
pnpm test	执行 build、Vitest、lint、文档检查、开发链接和 tarball 隔离安装测试
pnpm pack	生成可安装的 .tgz；pnpm 会通过 prepack 自动先执行 build

调试单个测试不需要额外的 package script，例如：

pnpm exec vitest run tests/package-contract.spec.ts

开发链接与真实安装

日常开发使用 pnpm dev。首次运行会通过稳定的 link: 依赖把本仓库注册进隔离的 DSH Web Profile；以后修改插件代码只会重新构建 lib，不会再次执行 pnpm add。插件运行时直接使用仓库根目录中由 pnpm install --frozen-lockfile 安装并由 pnpm build 准备好的固定 DSH 依赖。

需要验证发布包时使用：

pnpm dev:install
pnpm dev:web

pnpm dev:install 会生成带内容哈希文件名的真实 .tgz，只删除并重建 .tmp/dsh-home/profiles/web/node_modules，然后通过固定版本的 DSH CLI 安装 tarball。Profile 配置、lockfile、用户 patch 和 Session 数据不会被删除。这样既验证真实发布边界，也避免同一版本号复用旧插件内容。再次执行 pnpm dev 会把 Profile 切回本地链接模式。

切换模式或重新安装前必须先停止正在运行的 DSH Web。Windows 会阻止删除正在使用的 node_modules；脚本会重试短暂的文件占用，仍无法处理时会提示停止 Web，不会扩大删除范围。

与 Embedded Codex 联调

默认情况下，dsh-file-manager 和 dsh-embedded-codex 应位于同一个父目录。先停止正在运行的 Embedded Codex Web，然后在本仓库执行：

pnpm build:embedded-codex
cd ../dsh-embedded-codex
pnpm dev

如果 Embedded Codex 位于其他位置，请通过绝对路径覆盖默认目录：

DSH_EMBEDDED_CODEX_ROOT=/absolute/path/to/dsh-embedded-codex pnpm build:embedded-codex

PowerShell 使用 $env:DSH_EMBEDDED_CODEX_ROOT = 'D:\\dsh-embedded-codex' 设置该变量。

build:embedded-codex 会把 File Manager 构建成内容哈希 tarball，重建 Embedded Codex 临时 Web Profile 的 node_modules，再安装到目标仓库的 .tmp/dsh-home。Profile 配置和 Session 数据不会删除。这里有意不使用跨仓库 link:：两个独立 checkout 各自拥有一份 DSH 依赖，源码链接会让 Cordis、文件系统和 Typert Remote 出现重复运行时。每次修改 File Manager 后重新执行该命令即可更新联调版本。

安装到现有 DSH

先生成本地 tarball：

pnpm pack

然后通过任意兼容 DSH 的 Web Profile 安装并启动：

dsh plugin --profile web add .\dsh-file-manager-0.1.0.tgz
dsh web

移除插件：

dsh plugin --profile web remove dsh-file-manager

包发布到 npm 后，也可以直接按包名安装：

dsh plugin --profile web add dsh-file-manager
dsh web

构建说明

父仓库的 Git submodule gitlink 是唯一的 DSH commit 来源，不额外维护 commit 或源码摘要文件。pnpm build 会检查本地 submodule 是否与 gitlink 一致，并使用 .tmp/upstream-build.json 缓存已经完成的 DSH 构建；首次构建、gitlink 变化、产物缺失或 submodule 有源码修改时会重新构建 DSH。

完整构建顺序：

DeepSeek Harness dependencies and build
  -> DSH Remote prerequisite contracts
  -> File Manager Host declarations and Typert Remote codec
  -> File Manager Client declarations
  -> embedded Monaco styles and workers
  -> runtime and Web client bundles
  -> package structure and size verification

构建输出位于 lib/。发布包包含 Host、Client、Typert Remote、类型声明、cordis.patch.yml 和许可证文件，不包含 src/、upstream/、node_modules/ 或 .tmp/。

Bundle 与配置

package.json 通过 dsh.bundle.patch 声明包内的 cordis.patch.yml。执行 dsh plugin --profile web add ... 后，DSH 会把 dsh-file-manager 加入 dsh.profile.bundles，并插入：

- insert:
    - id: file-manager
      name: dsh-file-manager

可以在更晚的 Profile patch 中覆盖 file-manager 条目：

- id: file-manager
  config:
    maxFileBytes: 4194304
    maxEntriesPerDirectory: 3000
    showHiddenByDefault: true
    editable: true

字段	默认值	用途
maxFileBytes	2097152（2 MiB）	单次完整读取和保存的 Host 硬上限
maxEntriesPerDirectory	2000	单层目录最多返回的可见条目数
showHiddenByDefault	false	是否默认显示点文件
editable	true	设为 false 后只允许浏览和查看

Cordis patch 会替换该 row 的完整 config，不会深度合并，所以覆盖时应写全需要保留的字段。

已实现能力

• 文件树逐层加载、目录优先排序并支持键盘导航；目录复用 DSH Workspace 的开合图标与箭头交互，文件按常见类型显示图标；隐藏文件是否展示由 showHiddenByDefault 配置决定。
• 紧凑文件栏与轨迹筛选栏使用相同的按钮规格，可同时打开、切换和关闭多个文件 Tab；每个 Tab 独立保留未保存内容、光标、选区和滚动位置。
• TypeScript/JavaScript、JSON、HTML、CSS 系列使用 Monaco worker 语言服务；Markdown、YAML、Shell、Python、Go、Rust、Java、C/C++ 等常见语言支持语法高亮。
• Monaco 样式与五类 worker 在构建期内联到 client.js，运行时不访问 CDN。
• 保存使用读取版本令牌和原子 replaceIfVersion，不会静默覆盖 Agent、Git 或外部编辑器已经修改的文件。
• 所有浏览与编辑均严格限制在当前 Session 的权威 cwd 中。
• 二进制、无效 UTF-8、超限、权限、路径和版本冲突均有稳定错误码与 UI 状态。

V1 暂不包含新建、删除、重命名、二进制预览、全局搜索和工作区级 LSP。

常见问题

Web 仍显示旧的 File Manager

执行 pnpm dev:install 后必须重启正在运行的 Web 进程：先按 Ctrl+C，再执行 pnpm dev:web。必要时在浏览器中按 Ctrl+F5。

真实安装使用内容哈希 tarball 文件名，避免 pnpm 因版本号没有变化而复用旧插件内容。日常 pnpm dev 使用稳定链接，不经过 tarball 缓存。

提示 submodule 未初始化或 commit 不一致

git submodule update --init --recursive

构建不会自动切换或更新 submodule commit。

端口已占用或 Windows 提示文件正在使用

先在运行 DSH Web 的终端按 Ctrl+C，再执行 pnpm dev、pnpm dev:install 或 pnpm dev:remove。这些命令会调整隔离 Profile 的依赖，不应与运行中的 Web 同时执行。

维护文档

详细设计、Remote API 和验收记录见 实现方案。

许可证见 LICENSE，第三方声明见 THIRD_PARTY_NOTICES.md 和 THIRD_PARTY_NOTICES.txt。