预览就地编辑 hh719509125/dsh-preview-editor

文档编辑（Document Editor）

在右侧栏的文档预览里直接编辑文本文件并保存。

内置的文档预览是只读的（它的 README 把 "Preview, not editing" 写成明确的已知取舍）， workspaceFiles 这个 Remote 也完全没有写入方法。本插件补上这条写入通路，并把编辑器注册成预览自己的一个渲染器，所以不需要替换任何内置渲染器。

在 DSH 侧边栏的文档预览里就地编辑文本文档。

DSH 自带的文档预览按设计就是只读的 —— 它自己的 README 把 "Preview, not editing" 列为有意为之的限制 —— 而 workspace-files Remote 根本没有暴露任何写入操作。本插件补上这条缺失的写入通路，并把编辑器注册成预览自己的一个渲染器，所以不会替换任何内置渲染器。

安装 —— 让你的 DSH 智能体执行，然后刷新页面一次：

plugin_manager { action: "install_bundle", target: "github:hh719509125/dsh-preview-editor" }

用 github:hh719509125/dsh-preview-editor#v1.0.0 锁定某个发布版本，或者用完整的 40 位 commit SHA（缩写形式无法解析）。

使用

1. 打开文件。 在右侧侧边栏按 Ctrl+P 打开文件树，点击 .txt、代码或 .json 文件 —— 也可以从对话里的文件引用打开，或者从已投递文件卡片打开。
2. 输入。 这些扩展名的文件会以本编辑器的形式打开，而不是只读预览。
3. 按 Ctrl+S 保存，或者点工具栏上的 Save 按钮。
4. 想回到只读视图，在渲染器下拉菜单里选 Plain text。

工具栏一眼就能看出状态：

| 指示 | 含义 |
| 绿点 · Saved | 缓冲区与磁盘一致 |
| 黄点 · Unsaved changes | 还没写入；关闭标签页或页面会先警告 |
| Saving… | 写入正在进行 |

Tab 缩进两个空格。.md 默认保留渲染后的 Markdown —— 编辑器在渲染器下拉菜单里以 Edit source 的形式提供，所以预览永远不会被拿走。

值得了解的行为

| 情况 | 会发生什么 |
| 保存前文件在磁盘上变了 | 弹出「changed on disk, nothing overwritten」提示，提供 Overwrite with mine 或 Discard mine and reload。绝不会静默覆盖 |
| 编辑过程中文件变了 | 出现「load disk version」提示；你的缓冲区绝不会在背后被替换 |
| 文件被删除 | 保存返回 404 并如实告知 —— 不会重新创建文件 |
| 文件超过一页预览 | 保存被禁用并给出说明：预览一次只读一页，写回会截断其余部分 |
| 文件在会话工作区之外 | 可读，但沙箱会拒绝写入，除非该会话是 danger-full-access |
| .docx / .xlsx / .pptx | 不适用 —— 这些会预览为转换后的 PDF，浏览器没有可编辑的文档模型 |
兼容性。 基于 DSH 0.2.0-rc.2 构建并验证。它依赖 DSH 的两份内部契约——Connection 精确的 /api Fetch 路由，以及预览的 documentPreviews 渲染器注册表——这两者在各候选版本之间不保证稳定。如果 Edit 渲染器始终不出现，先检查 DSH 版本。

本文档其余部分为中文，讲得更深：写路径如何鉴权、每个配置字段、以及实现说明。

使用

还没装？见下面的安装。

装好、并刷新一次页面之后：

1. 打开文件。 在右侧栏按 Ctrl+P（桌面默认快捷键，打开「文件」树），点一个 .txt / 代码 / .json / .yaml 文件；它会在右侧栏作为一个标签打开。从对话里的文件引用、或交付文件卡片点开也一样。
2. 直接改。 这些后缀的文件打开时就是这个编辑器，不再是只读预览——光标点进去就能打字。
3. 保存。 按 Ctrl+S，或点工具条上的「保存」。
4. 想切回只读预览：用标签工具条上的渲染器下拉，选「纯文本」。

正在编辑一个 .txt：工具条显示「有未保存改动」，右侧是保存与撤销改动按钮

上图就是编辑中的样子。注意三点：

- 第二行的窄工具条是本插件加的：文件路径 · 状态点 · 保存 · 撤销改动
- 状态点是黄色、写着「有未保存改动」——还没写盘
- 图里正在用输入法打字（可以看到候选词条），说明中文输入法在编辑器里正常工作

工具条上一眼能看到状态：

| 指示 | 含义 |
| 绿点 · 已保存 | 缓冲区与磁盘一致 |
| 黄点 · 有未保存改动 | 还没写盘；此时关标签或关页面会拦一下 |
| 保存中… | 正在写盘 |

还有几个顺手的：

- Tab 缩进两格（不跳出编辑区）
- 「撤销改动」把缓冲区退回磁盘上的版本
- 关标签/关页面时若有未保存改动会拦一下
- .md 默认仍然是渲染好的 Markdown，编辑器在下拉的「编辑源码」里——它不抢 Markdown 的默认位置

Markdown 文件的渲染器下拉里多出「编辑源码」一项，默认仍是 Markdown

上图是 .md 文件的渲染器下拉：打勾的仍是 Markdown（默认），「编辑源码」是本插件新增的选项。
所以打开 .md 不会失去渲染视图，想改源码时从下拉里切过去即可。

各种情况下的表现

| 情况 | 表现 |
| 保存时文件已被别处改动 | 提示「文件已在磁盘上变化，未覆盖」，并给两个选择：用我的覆盖 / 放弃我的改动并重新载入。默认绝不覆盖 |
| 编辑期间磁盘上又变了 | 提示条出现「载入磁盘版本」，你的缓冲区不会被自动替换 |
| 文件被删掉了 | 保存返回 404 并说明，不会把文件重新创建出来 |
| 文件大过一页预览 | 保存停用并说明原因：预览是一次一页读的，回写会把后面的内容截断，所以宁可不让存 |
| 工作区外的文件 | 读得到，写会被沙箱拦下（除非该会话是 full-access） |
| .docx / .xlsx / .pptx | 不适用——预览是转 PDF，浏览器里没有可编辑文档模型 |

效果

- 打开 .txt、代码、.json、.yaml 等文本文件时，默认就是这个编辑器（原来的「纯文本」仍在下拉里可切回）
- 打开 .md 时仍然渲染 Markdown，下拉里多一项「编辑源码」
- 编辑器上方一条窄工具条：文件路径、保存状态、保存、撤销改动
- Ctrl+S 保存；有未保存改动时关页面会拦一下
- 冲突保护：保存时带上打开那一刻的文件版本，磁盘上变了就返回 409 提示，不会静默覆盖
- 行尾保留：CRLF 文件存回去仍是 CRLF，并补回结尾换行 —— 未改动的缓冲区保存后磁盘内容逐字节不变

安装

插件由 agent 安装（plugin_manager 是 agent 工具，用户不直接调用）。把这条规格发给你的 DSH agent：

plugin_manager { action: "install_bundle", target: "github:hh719509125/dsh-preview-editor" }

github:<owner>/<repo> 是 pnpm 的 git 规格，不需要发布到 npm，也不需要手动克隆。安装后会写进 profile 的 package.json 和 dsh.profile.bundles 并热应用。

锁定版本：上面这条跟踪 main。要钉住版本，把 ref 接在 # 后面：

github:hh719509125/dsh-preview-editor#v1.0.0 # 钉到某个 release github:hh719509125/dsh-preview-editor#<完整 40 位 SHA> # 钉到确切提交

实测注意：必须用完整的 40 位 SHA，短 SHA 解析不了（git ls-remote 不返回缩写）。

- 权限：plugin_manager 需要 danger-full-access 或当次批准。装进来的 Host 代码在工作区沙箱之外、以你的用户身份在本进程内执行，装之前请先读一遍 index.js。
- 刷新页面：安装是热应用的，但浏览器侧需要刷新一次才能加载新的 client bundle。

想离线或改代码时，克隆后按绝对路径安装：

git clone https://github.com/hh719509125/dsh-preview-editor.git
plugin_manager { action: "install_bundle", target: "<克隆路径>" }
⚠️ 路径装法下 profile 只记录路径、不复制文件，装好之后不要移动或删除那个目录。

兼容性

为 DeepSeek Harness 0.2.0-rc.2 开发和验证。依赖两处 DSH 内部约定：Connection 的 /api 精确 Fetch 路由，以及预览的 documentPreviews 渲染器注册表。DSH 仍在 rc 阶段，这些不承诺跨版本稳定；装完看不到「编辑」渲染器就先确认 DSH 版本。

配置

都在 cordis.patch.yml 的 document-editor 那一行：

| 字段 | 默认 | 说明 |
| extensions | 65 个后缀 | 哪些后缀默认进编辑器。刻意不含 md/html/svg/csv/图片/PDF —— 它们各自有更好用的内置渲染器 |
| markdown | true | 是否为 .md 额外提供「编辑源码」渲染器（不改变 Markdown 仍是默认这一事实） |
| maxBytes | 8388608 | 单次保存的 UTF-8 字节上限，超过返回 413 |

Host 会把这份配置注入页面（__DSH_DOC_EDITOR_CONFIG__），改完刷新页面生效。

工作原理

写入不是走 Remote——@deepseek-ai/dsh-api-remotes 把 Client 的 ctx.remote 命名空间 固定在构建期，插件加不了新命名空间。所以插件改为在 Connection 的 /api 桥上认领一条 exact Fetch 路由：

ctx.connection.fetch.register({ path: '/api/dsh-doc-editor', methods: ['POST'], ... })

Connection 自己持有 /api 前缀路由，先跑信任闸（loopback/Origin，失败 403）和浏览器 session cookie 鉴权（失败 401），再交给 shared fetch handler；handler 先查 exact 路由表。
所以这条路由天然带着内置鉴权，插件一行信任检查都不用写。

写入落到 ctx.fs.writeText，并带上该 Session 的 standing sandbox policy——用和 dsh-tool-fs 完全一样的方式解析，所以就地保存受的约束和 agent 自己的 write 工具一致，不会成为绕过文件沙箱的口子。

保存前会 stat 一次：只保存已存在的文件。目标不见了返回 404，而不是被 create-or-overwrite 语义重新创建出来。

边界

| 情况 | 行为 |
| 工作区内的文本文件 | ✅ 正常 |
| 工作区外的文件 | 读得到，写被沙箱拦（除非该 Session 是 full-access） |
| .docx / .xlsx / .pptx | ❌ 预览是转 PDF，浏览器里没有可编辑文档模型。要编辑得在 Host 用 python-docx/openpyxl 做结构化写回 |
| 单页读不完的大文件 | ⚠️ 保存停用并给出说明。text-pages 是一次一页读的，回写会把后面的内容截断，所以宁可不让存 |

开发

插件包里的 cordis.patch.yml 刻意不含任何本机路径：bundle patch 会应用到每个安装它的 profile，一条绝对路径会跟着跑到别人机器上。热重载要写到安装方的 profile 层（<DSH_HOME>/profiles/<profile>/cordis.patch.yml，优先级高于所有 bundle 层）：

- id: hmr
name: '@deepseek-ai/dsh-hmr'
config:
root: ['.', '<本插件的绝对路径>']

配好后 index.js（Host 半边）改完不重启就生效；client.js（Client 半边）属于浏览器侧，改完刷新页面即可。

日常用 cordis.patch.yml 里的 extensions / markdown / maxBytes 就够了，不必改代码。

改动怎么验。 写入通路必须带鉴权地打真实路由，而 DSH 的 browser-session cookie 签名是 dsh-client-connection 的内部实现、并未承诺稳定，所以这里不附带测试。开发时用的是本机探针，覆盖下面这些行为：

| 类别 | 覆盖 |
| 鉴权 | 带会话 cookie → 200；无 cookie → 401 |
| 写入 | 内容正确落盘；返回新 version |
| 行尾 | CRLF 文件存回仍是 CRLF 且补回结尾换行；LF 文件保持 LF |
| 幂等 | 未改动缓冲区保存后磁盘内容逐字节不变 |
| 冲突 | 过期 version → 409 FS_STALE_VERSION，且文件原封不动 |
| 缺失目标 | → 404，且不会被重新创建 |
| 坏请求 | 请求体不是合法 JSON/对象 → 400 |
| 投递 | 页面 boot 载荷列出 client bundle，且该 bundle 能构建、内容含渲染器注册 |

卸载

plugin_manager { action: "remove_bundle", target: "@local/dsh-plugin-document-editor" }