@benz-ai-x/dsh-md-preview 0.4.0 → 0.6.0

package/README.md

@@ -1,110 +1,138 @@
+[English](README.md) | [中文](README.zh.md)
+
 # @benz-ai-x/dsh-md-preview
 
-DSH Web GUI 插件:点击对话中出现的 Markdown 文档,在对话右侧打开渲染后的预览面板。
+**DSH (DeepSeek Harness) Web GUI plugin — markdown preview, editing & workspace file browser beside the chat.** Preview rendered markdown and plain-text files, edit with conflict-guarded saves, and browse the session workspace tree without leaving the conversation.
 
 [![npm](https://img.shields.io/npm/v/@benz-ai-x/dsh-md-preview)](https://www.npmjs.com/package/@benz-ai-x/dsh-md-preview)
 [![GitHub](https://img.shields.io/badge/repo-benz--ai--x%2Fdsh--md--preview-24292e?logo=github)](https://github.com/benz-ai-x/dsh-md-preview)
 
-## 效果
+## Features
 
-- 回合产出文件 chip 行中的 `.md` / `.markdown` 文档:点击打开右侧预览面板,渲染 GFM、代码高亮和 TeX。
-- 每条助手消息的操作区新增「预览文档」按钮,列出该回合产出的 Markdown 文档。
-- 非 Markdown 产出文件保持原有行为(交给系统打开)。
-- 面板可关闭、可拖宽(320–1280 px,默认 500);拖出的宽度在本次应用会话内保持。
-- 没有预览目标时面板不渲染。
-- **编辑**:面板「编辑」进入 CodeMirror 编辑器(行号、GFM 高亮、Cmd/Ctrl-S 保存),「保存」写回工作区、显示「✓ 已保存」提示并回到渲染视图,「取消编辑」丢弃草稿;只编辑已存在的文件。保存失败(非冲突)会显示错误码并提供【重试】。
-- **冲突保护**:保存时若文件已被其它方(agent、其它会话、外部编辑器)修改,提示「文件已变化」,由你选择【重新加载】或【强制覆盖】;带未保存修改关闭面板会先询问。
-- **工作区浏览**:面板头部「工作区」进入目录树(懒展开、加载/空/失败三态);单击 `.md` 富渲染、`.txt` 等纯文本等宽展示、其它类型明确提示不支持;当前文档在树中高亮并自动定位;支持方向键/Enter 键盘遍历;头部路径面包屑。
+- Markdown chips in the produced-files row of a turn open a right-docked preview panel rendering GFM, syntax-highlighted code, and TeX.
+- A per-message "Preview documents" action lists that turn's markdown documents.
+- Non-markdown deliverables keep the shipped open-on-desktop behavior.
+- The panel is closable and draggable (320–1280 px, default 500); the dragged width persists for the app session.
+- The panel renders nothing while no preview target is set.
+- **Editing** — the panel's Edit action enters a CodeMirror editor (line numbers, GFM highlighting, Cmd/Ctrl-S save); Save writes back to the workspace, flashes a "Saved" toast, and returns to the rendered view; Cancel discards the draft. Only existing files edit. Non-conflict save failures show the failure code with a Retry action.
+- **Conflict guard** — saving over a file that changed elsewhere (another session, the agent, an external editor) prompts "the file changed elsewhere": Reload or Overwrite; closing with unsaved edits asks first.
+- **Workspace browser** — the panel header's Workspace action enters a directory tree of the session workspace (lazy expansion, loading/empty/failed states); single-click renders `.md` rich, `.txt` and other text monospace, other types a clear unsupported notice; the current document highlights and auto-reveals in the tree; full keyboard traversal (arrows/Enter); the header shows the path breadcrumb. Expanded directories silently revalidate on every re-entry (and from the tree's refresh button) — the agent keeps producing files mid-conversation, and a failed refresh never blanks what's on screen.
+- **Outline** — the header's outline popover lists the document's ATX headings (fenced code never counts); clicking scrolls the rendered heading in the view face and jumps the cursor to the source line in the edit face.
+- **Editor find** — the edit face carries a CodeMirror search panel (header button and Mod/Ctrl-F).
+- **Mermaid diagrams** — fenced ` ```mermaid ` blocks render as diagrams after the document settles; the block banner stays (copy still reads the source), and any failure falls back to the plain code block. Mermaid is inlined into the client bundle but evaluated lazily (first diagram pays the parse cost; bundle ~3.9 MB minified / ~1.1 MB gzip).
 
-## 安装
+## Install
 
-要求 DSH 基线 `0.1.2-alpha.3`(即 peerDependencies 所列版本)和 web profile。
+Requires DSH baseline `0.1.2-rc.1` (see peerDependencies) and a web profile.
 
 ```sh
 dsh plugin --profile <name> add @benz-ai-x/dsh-md-preview
-dsh --profile <name> --dump-config   # 应出现 id: md-preview 的行
-dsh --profile <name>                 # 打开 Web GUI;回合产出 .md 后点击 chip 预览
+dsh --profile <name> --dump-config   # expect the id: md-preview row
+dsh --profile <name>                 # open the Web GUI; click a chip after a turn produces .md
 dsh plugin --profile <name> remove @benz-ai-x/dsh-md-preview
 ```
 
-## 配置
+### Three install forms (per the [DSH publish spec](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/publish.md))
+
+| Form | Command | Status |
+| --- | --- | --- |
+| npm (recommended) | `dsh plugin --profile <name> add @benz-ai-x/dsh-md-preview` | ✅ prebuilt, works out of the box |
+| tarball | `dsh plugin --profile <name> add ./benz-ai-x-dsh-md-preview-<ver>.tgz` (from `pnpm pack:publishable`) | ✅ prebuilt, no build approval needed |
+| Git | `dsh plugin --profile <name> add github:benz-ai-x/dsh-md-preview#<sha>` | ✅ builds from source via the package's self-contained `prepare` (transpile-only; no type declarations ship on this form) — see below |
+
+Git installs fetch source, and pnpm refuses to run a git dependency's `prepare` until the package is explicitly allowed. After the first `add` fails, copy the package key pnpm printed into the profile's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  '@benz-ai-x/dsh-md-preview': true
+```
+
+then re-run `add`. Allowing a build executes the package's code on your machine at install time — allow only sources you trust, and pin a commit (`#<sha>`) so a later push cannot silently change what runs.
+
+## Configuration
 
 ```yaml
 - id: md-preview
   name: '@benz-ai-x/dsh-md-preview'
   config:
-    maxBytes: 1048576        # 单文件读取上限(字节)
+    maxBytes: 1048576        # per-file read/write cap in bytes
     allowedExtensions: ['.md', '.markdown']
 ```
 
-| 字段 | 类型 | 默认 | 说明 |
+| Field | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `maxBytes` | number | `1048576` | 单文件读/写上限,超出返回 `too-large` |
-| `allowedExtensions` | string[] | `[".md", ".markdown"]` | 可编辑的扩展名白名单 |
-| `previewExtensions` | string[] | `[".md", ".markdown", ".txt"]` | 可预览的扩展名(可编辑集的超集;纯文本成员只读展示) |
+| `maxBytes` | number | `1048576` | per-file read/write cap; exceeded returns `too-large` |
+| `allowedExtensions` | string[] | `[".md", ".markdown"]` | extensions eligible for editing |
+| `previewExtensions` | string[] | `[".md", ".markdown", ".txt"]` | extensions eligible for preview (a superset of the editable set; plain-text members render read-only) |
 
-## 失败码
+## Failure codes
 
-读取失败时面板显示 `md-preview/<reason>`。所有失败码:
+The panel shows `md-preview/<reason>` on failure. All codes:
 
-| 码 | 含义 |
+| Code | Meaning |
 | --- | --- |
-| `md-preview/bad-request` | path 为空或非法;或保存时既无指纹也未强制 |
-| `md-preview/unknown-session` | 会话不存在 |
-| `md-preview/no-workspace` | 会话没有工作目录 |
-| `md-preview/unsupported-extension` | 扩展名不在白名单 |
-| `md-preview/forbidden` | 路径超出会话工作区 |
-| `md-preview/not-found` | 文件不存在(编辑只针对已存在文件) |
-| `md-preview/too-large` | 文件(读取)或内容(写入)超过 `maxBytes` |
-| `md-preview/conflict` | 保存时文件已变化(指纹不匹配且未强制) |
-| `md-preview/unavailable` | 读/写过程发生 IO 错误 |
-
-## 已知限制
-
-- 正文中内联提到的 `.md` 文件名仍走系统打开(归 ui-deliverables 所有,不归本插件)。
-- 面板悬浮在对话右侧,不替换三栏布局。
-- 用户上传的文档附件不可预览(目前没有对应的会话面)。
-
-## 开发(source-linked)
+| `md-preview/bad-request` | path empty or unusable; or a save with neither fingerprint nor force |
+| `md-preview/unknown-session` | session does not exist |
+| `md-preview/no-workspace` | session has no working directory |
+| `md-preview/unsupported-extension` | extension outside the allowlist |
+| `md-preview/forbidden` | path escapes the session workspace |
+| `md-preview/not-found` | file does not exist (editing targets existing files only) |
+| `md-preview/too-large` | file (read) or content (write) exceeds `maxBytes` |
+| `md-preview/conflict` | file changed since the read backing the save (no force) |
+| `md-preview/unavailable` | IO error during read/write |
+
+## Known limits
+
+- Inline prose mentions of `.md` files still open on the desktop (owned by ui-deliverables, not this plugin).
+- The panel floats above the details column; it does not replace the three-column grid.
+- Uploaded document attachments are not previewable (no transcript surface today).
+- The outline lists ATX headings only (setext forms render but stay out of the popover).
+- Mermaid renders with its default theme; documents mixing indented code blocks with fenced ones skip the diagram pass entirely (order-parity safety check).
+
+## Development (source-linked)
 
 ```sh
 pnpm install
 pnpm verify                 # context:check:strict + typecheck + test + build + built:check
-pnpm context:sync           # Harness 检出移动后重写 link 并刷新 lockfile
-pnpm watch:client           # 客户端 bundle 热构建
+pnpm context:link           # source-linked development: rewrite link: at the harness checkout (registry by default)
+pnpm watch:client           # client bundle watch build
 ```
 
-### 结构
+### Structure
 
-| 部分 | 位置 | 说明 |
+| Part | Location | Notes |
 | --- | --- | --- |
-| Host Remote | `src/remote.ts` | `mdPreview/read(sessionId, path, signal)`;工作区限域、扩展名白名单、字节上限 |
-| Remote contribution | `src/typert/remote-client.ts` | 手工维护的浏览器端描述符(生成器产物的等价物) |
-| 浏览器入口 | `src/client/index.ts` | 挂载 Remote + 注册三个 Slot 贡献 |
-| 预览面板 | `src/client/PreviewOverlay.tsx` | `shell.overlay`(list,增量);编辑/冲突/未保存状态机 |
-| 编辑器 | `src/client/editor.tsx` | CodeMirror 6(精选扩展集,构建期内联,client bundle ~400 kB minified) |
-| chip 行接管 | `src/client/MdChips.tsx` | `conversation.chat.turnTail`(chain,仅认领含 Markdown 的回合) |
-| 消息操作 | `src/client/PreviewAction.tsx` | `conversation.chat.assistant-actions`(list,增量) |
-
-### 真实 profile 验证(本地检出)
+| Host Remote | `src/remote.ts` | `mdPreview/read(sessionId, path, signal)`; workspace scoping, extension allowlists, byte caps |
+| Remote contribution | `src/typert/remote-client.ts` | hand-maintained browser-side descriptors (generator-equivalent) |
+| Browser entry | `src/client/index.ts` | mounts the Remote + registers three Slot contributions |
+| Preview panel | `src/client/PreviewOverlay.tsx` | `shell.overlay` (list, additive); rendering + geometry only |
+| Session machine | `src/client/preview-session.ts` | pure reducer for read/edit/save/prompts |
+| Editor | `src/client/editor.tsx` | CodeMirror 6 (curated extensions incl. the search panel, inlined at build) |
+| Workspace tree | `src/client/WorkspaceBrowser.tsx` | lazy tree with highlight/auto-reveal/keyboard and silent revalidation |
+| Outline | `src/client/outline.ts` | ATX heading scan + rendered-heading resolution |
+| Diagram pass | `src/client/diagrams.ts` | post-render mermaid enhancement, fail-soft to the code block |
+| Chip row | `src/client/MdChips.tsx` | `conversation.chat.turnTail` (chain; claims markdown-bearing turns) |
+| Message action | `src/client/PreviewAction.tsx` | `conversation.chat.assistant-actions` (list, additive) |
+
+### Real-profile verification (local checkout)
 
 ```sh
 pnpm build
 dsh plugin --profile <name> add ./dsh-md-preview
 dsh --profile <name> --dump-config
-dsh --profile <name>        # 打开 Web GUI,写一个 README.md 产出并点击 chip
+dsh --profile <name>        # open the Web GUI, produce a README.md and click the chip
 dsh plugin --profile <name> remove @benz-ai-x/dsh-md-preview
 ```
 
-### 打包与发布
+### Pack & publish
 
 ```sh
-pnpm pack:publishable       # 打出净化 manifest 的 tarball 并复检(无 devDeps、无 link:/workspace:)
-pnpm publish:registry       # 以同一净化流程发布到 npm
+pnpm pack:publishable       # registry-clean tarball + self-check (no devDeps, no link:/workspace:)
+pnpm publish:registry       # publish via the same cleaned-manifest flow
 ```
 
-source-linked 验证证明与固定 Harness 检出(见 `dsh-reference.lock.json`)的兼容性;发布形态以 packed tarball 在干净 profile 中的安装/启动/移除冒烟为准。
+Source-linked verification proves compatibility with the pinned harness checkout (see `dsh-reference.lock.json`); the publish form is proven by the packed-tarball profile smoke.
 
-## 许可证
+## License
 
 MIT

package/README.zh.md

@@ -0,0 +1,138 @@
+[English](README.md) | 中文
+
+# @benz-ai-x/dsh-md-preview
+
+DSH Web GUI 插件:点击对话中出现的 Markdown 文档,在对话右侧打开渲染后的预览面板;支持受守卫编辑与工作区目录树浏览。
+
+[![npm](https://img.shields.io/npm/v/@benz-ai-x/dsh-md-preview)](https://www.npmjs.com/package/@benz-ai-x/dsh-md-preview)
+[![GitHub](https://img.shields.io/badge/repo-benz--ai--x%2Fdsh--md--preview-24292e?logo=github)](https://github.com/benz-ai-x/dsh-md-preview)
+
+## 效果
+
+- 回合产出文件 chip 行中的 `.md` / `.markdown` 文档:点击打开右侧预览面板,渲染 GFM、代码高亮和 TeX。
+- 每条助手消息的操作区新增「预览文档」按钮,列出该回合产出的 Markdown 文档。
+- 非 Markdown 产出文件保持原有行为(交给系统打开)。
+- 面板可关闭、可拖宽(320–1280 px,默认 500);拖出的宽度在本次应用会话内保持。
+- 没有预览目标时面板不渲染。
+- **编辑**:面板「编辑」进入 CodeMirror 编辑器(行号、GFM 高亮、Cmd/Ctrl-S 保存),「保存」写回工作区、显示「✓ 已保存」提示并回到渲染视图,「取消编辑」丢弃草稿;只编辑已存在的文件。保存失败(非冲突)会显示错误码并提供【重试】。
+- **冲突保护**:保存时若文件已被其它方(agent、其它会话、外部编辑器)修改,提示「文件已变化」,由你选择【重新加载】或【强制覆盖】;带未保存修改关闭面板会先询问。
+- **工作区浏览**:面板头部「工作区」进入目录树(懒展开、加载/空/失败三态);单击 `.md` 富渲染、`.txt` 等纯文本等宽展示、其它类型明确提示不支持;当前文档在树中高亮并自动定位;支持方向键/Enter 键盘遍历;头部路径面包屑。已展开目录在每次重进浏览脸时**静默重验**(树工具栏也有刷新按钮)——agent 会在会话中途持续产出文件,刷新失败绝不清空现有列表。
+- **大纲导航**:头部「大纲」弹层列出文档的 ATX 标题(代码围栏内的 `#` 不算);点击后查看脸滚动到渲染标题、编辑脸跳转光标到源行。
+- **编辑器查找**:编辑脸带 CodeMirror 搜索面板(头部按钮与 Mod/Ctrl-F)。
+- **Mermaid 图表**:` ```mermaid ` 围栏块在文档渲染定型后增强为图表;块横幅保留(复制仍取源码),任何失败回退纯代码块。mermaid 内联进 client bundle 但**惰性求值**(首个图表才付解析成本;bundle 约 3.9 MB minified / 1.1 MB gzip)。
+
+## 安装
+
+要求 DSH 基线 `0.1.2-rc.1`(即 peerDependencies 所列版本)和 web profile。
+
+```sh
+dsh plugin --profile <name> add @benz-ai-x/dsh-md-preview
+dsh --profile <name> --dump-config   # 应出现 id: md-preview 的行
+dsh --profile <name>                 # 打开 Web GUI;回合产出 .md 后点击 chip 预览
+dsh plugin --profile <name> remove @benz-ai-x/dsh-md-preview
+```
+
+### 三种安装形态(依 [DSH 打包与安装规范](https://github.com/deepseek-ai/deepseek-harness/blob/main/docs/user/develop/basic/publish.zh.md))
+
+| 形态 | 命令 | 状态 |
+| --- | --- | --- |
+| npm(推荐) | `dsh plugin --profile <name> add @benz-ai-x/dsh-md-preview` | ✅ 预构建产物,即装即用 |
+| tarball | `dsh plugin --profile <name> add ./benz-ai-x-dsh-md-preview-<ver>.tgz`(tarball 由源码 `pnpm pack:publishable` 产出) | ✅ 预构建产物,无需任何构建授权 |
+| Git 直装 | `dsh plugin --profile <name> add github:benz-ai-x/dsh-md-preview#<sha>` | ✅ 由包自带的自包含 `prepare` 从源码构建(纯转译,此形态不带类型声明)——见下文 |
+
+git 安装拉取的是源码,pnpm 在得到显式允许前拒绝运行 git 依赖的 `prepare`。首次 `add` 失败后,把 pnpm 打印的确切包键复制进该 profile 的 `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  '@benz-ai-x/dsh-md-preview': true
+```
+
+然后重新执行 `add`。授权构建 = 允许该包的代码在安装时于你的机器上执行 —— 只对可信源码授权,并用 `#<sha>` 锁定 commit,让后续推送无法悄悄改变实际运行的内容。
+
+## 配置
+
+```yaml
+- id: md-preview
+  name: '@benz-ai-x/dsh-md-preview'
+  config:
+    maxBytes: 1048576        # 单文件读取上限(字节)
+    allowedExtensions: ['.md', '.markdown']
+```
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `maxBytes` | number | `1048576` | 单文件读/写上限,超出返回 `too-large` |
+| `allowedExtensions` | string[] | `[".md", ".markdown"]` | 可编辑的扩展名白名单 |
+| `previewExtensions` | string[] | `[".md", ".markdown", ".txt"]` | 可预览的扩展名(可编辑集的超集;纯文本成员只读展示) |
+
+## 失败码
+
+读取失败时面板显示 `md-preview/<reason>`。所有失败码:
+
+| 码 | 含义 |
+| --- | --- |
+| `md-preview/bad-request` | path 为空或非法;或保存时既无指纹也未强制 |
+| `md-preview/unknown-session` | 会话不存在 |
+| `md-preview/no-workspace` | 会话没有工作目录 |
+| `md-preview/unsupported-extension` | 扩展名不在白名单 |
+| `md-preview/forbidden` | 路径超出会话工作区 |
+| `md-preview/not-found` | 文件不存在(编辑只针对已存在文件) |
+| `md-preview/too-large` | 文件(读取)或内容(写入)超过 `maxBytes` |
+| `md-preview/conflict` | 保存时文件已变化(指纹不匹配且未强制) |
+| `md-preview/unavailable` | 读/写过程发生 IO 错误 |
+
+## 已知限制
+
+- 正文中内联提到的 `.md` 文件名仍走系统打开(归 ui-deliverables 所有,不归本插件)。
+- 面板悬浮在对话右侧,不替换三栏布局。
+- 用户上传的文档附件不可预览(目前没有对应的会话面)。
+- 大纲只收 ATX 标题(setext 下划线式标题会渲染但不进弹层)。
+- Mermaid 用默认主题;混用缩进代码块与围栏块的文档整体跳过图表增强(顺序对齐安全检查)。
+
+## 开发(source-linked)
+
+```sh
+pnpm install
+pnpm verify                 # context:check:strict + typecheck + test + build + built:check
+pnpm context:link           # 需要源码联调时:重写 link: 指向 Harness 检出并刷新 lockfile(默认 registry)
+pnpm watch:client           # 客户端 bundle 热构建
+```
+
+### 结构
+
+| 部分 | 位置 | 说明 |
+| --- | --- | --- |
+| Host Remote | `src/remote.ts` | `mdPreview/read(sessionId, path, signal)`;工作区限域、扩展名白名单、字节上限 |
+| Remote contribution | `src/typert/remote-client.ts` | 手工维护的浏览器端描述符(生成器产物的等价物) |
+| 浏览器入口 | `src/client/index.ts` | 挂载 Remote + 注册三个 Slot 贡献 |
+| 预览面板 | `src/client/PreviewOverlay.tsx` | `shell.overlay`(list,增量);仅渲染 + 几何 |
+| 会话机器 | `src/client/preview-session.ts` | 纯 reducer:读取/编辑/保存/提示的完整状态代数 |
+| 编辑器 | `src/client/editor.tsx` | CodeMirror 6(精选扩展集含搜索面板,构建期内联) |
+| 工作区树 | `src/client/WorkspaceBrowser.tsx` | 懒树:高亮/自动定位/键盘遍历 + 静默重验 |
+| 大纲 | `src/client/outline.ts` | ATX 标题扫描 + 渲染标题定位 |
+| 图表增强 | `src/client/diagrams.ts` | 渲染后 mermaid 增强,失败回退代码块 |
+| chip 行接管 | `src/client/MdChips.tsx` | `conversation.chat.turnTail`(chain,仅认领含 Markdown 的回合) |
+| 消息操作 | `src/client/PreviewAction.tsx` | `conversation.chat.assistant-actions`(list,增量) |
+
+### 真实 profile 验证(本地检出)
+
+```sh
+pnpm build
+dsh plugin --profile <name> add ./dsh-md-preview
+dsh --profile <name> --dump-config
+dsh --profile <name>        # 打开 Web GUI,写一个 README.md 产出并点击 chip
+dsh plugin --profile <name> remove @benz-ai-x/dsh-md-preview
+```
+
+### 打包与发布
+
+```sh
+pnpm pack:publishable       # 打出净化 manifest 的 tarball 并复检(无 devDeps、无 link:/workspace:)
+pnpm publish:registry       # 以同一净化流程发布到 npm
+```
+
+source-linked 验证证明与固定 Harness 检出(见 `dsh-reference.lock.json`)的兼容性;发布形态以 packed tarball 在干净 profile 中的安装/启动/移除冒烟为准。
+
+## 许可证
+
+MIT