openharness-reader

OpenHarness Reader —— DeepSeek Harness Web 的工作区文件阅读/编辑器插件（平行项目，非壳功能）。

规划文档：000-file-editor-plugin.md（本仓库内跟踪）。

路线

里程碑	内容	状态
M1	骨架：package.json + cordis.patch.yml + host/client 两半 + esbuild；注册 details 面板（占位）	✅ 2026-08-14
M2	文件浏览：host fs RPC（list/stat/read）+ client 树/列表	✅ 2026-08-14（v0.2.0）
M3	编辑保存：CodeMirror 6 + ctx.fs 写回（版本守卫 + 冲突提示）	✅ 2026-08-14（v0.2.0）
M4	Markdown 渲染预览（GFM + 高亮）	✅ 2026-08-14（v0.2.0）
挂载方案改方案 1	彻底弃用 details 槽：client 改为 body portal + fixed 定位面板（照 DSH-better-sidebar）；per-session store 管布局；apply 全包 try/catch + 错误条兜底；唯一官方槽位 = settings.section（list 槽）	✅ 2026-08-14（v0.3.0）
M5	npm 发布 + 壳 AUTO_INSTALL_PLUGINS 预装	⏳

功能（v0.2.0 · M2–M4；v0.3.0 改挂载方案）

• 文件浏览：右侧 fixed 面板按当前会话 workspace（cwd）懒加载目录树；目录点击展开、文件点击打开；文件名过滤；目录优先排序；面板可拖拽调宽 / 收起 / 窄屏抽屉（per-session 布局）。
• 编辑保存：CodeMirror 6（JS/TS/JSON/Markdown/Python/CSS/HTML/XML + shell/yaml/toml/sql 等 legacy 模式）；保存走 ctx.fs.writeText，以读取时版本做 replaceIfVersion CAS —— 磁盘文件被外部（如 agent 工具）改动时弹出冲突对话框：重新加载 / 覆盖保存。
• Markdown 预览：marked（GFM：表格/删除线/自动链接）+ highlight.js 代码高亮；.md 文件支持 编辑 / 预览 切换；预览容器带 data-adhdgofly-highlight 属性契约，已装 adhdgofly-dsh-ext ≥ v0.1.2 时自动获得词性高亮（名绿/动红/形紫/其他灰，与对话共享色板/筛选/主题）。
• 树滚动（v0.3.3 修复）：浏览器视图为 flex 列（.ohr-browser），文件树 overflow:auto 真正生效，深目录可上下滚动；编辑器视图滚动不受影响。
• 挂载稳定（v0.3.4 修复）：面板 Shell 的 useSyncExternalStore 无条件调用（修复 hook 数量突变导致的 Uncaught TypeError: Cannot read properties of undefined (reading 'length')——sessions 服务晚就绪时面板不挂载/半挂载），会话何时就绪都能稳定显示。
• 只读保护：超过 maxReadBytes（默认 5 MB）的大文件与二进制文件（FS_NOT_TEXT）只读打开。
• 策略一致：host 读写全部走 ctx.fs 缝隙，并派发 fs/write-intent / fs/edit-intent / fs/observed 事件（actor 携带会话），与 agent 的 fs 工具共享观察状态与守卫。

架构

• host half（src/host/index.ts）：注册通用 Connection RPC 通道 /openharness-reader（ctx.connection.rpc.handle，authority loopback，与 /api 同款浏览器信任围栏）。端点：list / stat / read / write / edit。业务失败以稳定 FsErrorCode 结构化返回。entry 必须在 cordis.patch.yml 声明 inject: ['fs', 'connection']（v0.3.1 修复：插件 entry ctx 用 ctx.get 拿不到兄弟 entry 提供的服务，apply 静默 bail → 路由不注册 → 所有调用落静态 fallback 405）。
• client half（src/client/）：body portal（v0.3.0 方案 1）。apply() 自建 document.createElement('div')（带 data-openharness-reader）挂到 document.body，createRoot(host).render(<ReaderPanel/>)；面板 fixed 定位（默认右侧），与 DSH 三栏布局完全平行。布局状态（宽/折叠/窄屏抽屉）在 per-session store（src/client/layout.ts）；ctx.connection.rpc.call 调 host；ctx.sessions.list 取当前会话 workspace。
• 唯一官方槽位：settings.section（list 槽，id+order，见 src/client/settings.tsx）；绝不注册 details。
• 协议类型共享于 src/shared/protocol.ts。

开发

npm install
npm run build      # esbuild 双入口（lib/client.js + lib/index.js）
npm run typecheck  # tsc --noEmit
npm test           # 冒烟（bundle 形态）+ host RPC 行为测试（stub ctx）

安装进 web profile（已发布 npm：openharness-reader@0.3.4，公开安装）：

dsh plugin --profile web add openharness-reader
# pnpm ≥ 10 若报 ERR_PNPM_ADDING_TO_ROOT，末尾加 -w
# 重启 dsh web 生效

本地开发安装（本地 tarball / file: 链接）：

npm pack
dsh plugin --profile web add file:./openharness-reader-0.3.4.tgz
# 重启 dsh web 生效（host half 需进程重启；client bundle 页面刷新即可）

说明

• v0.3.0 挂载方案（方案 1，定案）：details 是 single slot（dsh-client-ui-layout 声明，kind: single / scope: session）——同一 priority 只允许一个注册，重复注册抛错，而 client web 的 boot sweep 对 apply 失败的 entry fail-loud（整机白屏 "HARNESS / Failed to load plugins"）。v0.2.1 的「priority 探测 − 1」只是规避，仍依赖与 details 占用者的博弈。v0.3.0 起彻底弃用 details 槽：改 body portal + fixed 定位面板（照 DSH-better-sidebar），对任何 details 占用者（含 x6）零交集、零冲突，不依赖 priority 探测、不依赖加载顺序；唯一官方槽位仅限 list/keyed 槽（settings.section，带 id+order，list 槽消费全部 entry、注册永不冲突）；整个 apply 包 try/catch，任何阶段失败只降级为「面板不显示 + console.error + 页面角落错误条」，绝不把错误抛出 apply 拖垮 boot。详见 000-file-editor-plugin.md §三/§五。
• 与 adhdgofly-dsh-ext 高亮的关系（方案 A′ 属性契约，v0.3.3 + adhdgofly v0.1.2 已落地）：代码内容与编辑器（contenteditable）天然被其跳过；MD 预览容器带 data-adhdgofly-highlight 属性，adhdgofly 每次处理自动采纳该容器（无需写 containers 配置、无需重载），未装 adhdgofly 时属性惰性无害。详见 000-file-editor-plugin.md §五。

我开发的 DSH 插件

我（zuoguyoupan2023）开发维护的一系列 DeepSeek Harness（dsh）插件，均可按需通过 dsh plugin --profile web add <name> 安装：

插件	作用	GitHub 仓库	安装
adhdgofly-dsh-ext	DSH Web 界面词性高亮（名绿/动红/形紫/其他灰）	zuoguyoupan2023/adhdgofly-dsh-ext	dsh plugin --profile web add adhdgofly-dsh-ext
openharness-reader	工作区文件浏览/编辑 + Markdown 预览	zuoguyoupan2023/openharness-reader	dsh plugin --profile web add openharness-reader
openharness-reply-in-cn	强制模型用简体中文回复，侧边栏「中文回复」项	zuoguyoupan2023/openharness-reply-in-cn	dsh plugin --profile web add openharness-reply-in-cn
openharness-rule-for-dsh-plugin	注入 DSH 插件开发的 CAN/SHOULD/MUST NOT 规范，侧边栏「插件开发规范」项	zuoguyoupan2023/openharness-rule-for-dsh-plugin	dsh plugin --profile web add openharness-rule-for-dsh-plugin