dsh-doc-preview

dsh-doc-preview

在 DeepSeek Harness Web 里按工作区预览文档的 dsh bundle 路由插件。

它复用 dsh-web-app 已挂载的 ctx.webServer 服务注册 /docs 前缀路由，并用 ctx.workspaceRegistry 读取 dsh 真实登记的工作区，把 /docs/<工作区id>/… 映射到对应工作区目录。每个工作区独立命名空间， 文档不会跨工作区混杂，也无法越界访问系统目录。

地址规则

http://<host>/docs                          -> 所有已登记工作区的索引页
http://<host>/docs/<工作区id>/              -> 该工作区根目录列表
http://<host>/docs/<工作区id>/<相对路径>.md -> 渲染该工作区内的文档

<工作区id> = 工作区真实目录路径去掉前导 /、/ 改 -。例如：

工作区目录	工作区 id	示例地址
/Users/alice/work/project	Users-alice-work-project	/docs/Users-alice-work-project/docs/调研.md
/Users/alice/work/reports	Users-alice-work-reports	/docs/Users-alice-work-reports/报告.md

• 工作区列表来自 ctx.workspaceRegistry.list()（持久化于 storages/workspace.json），新登记的工作区自动出现，无需改插件。
• 隔离：请求被限制在对应工作区目录内；未知工作区、路径穿越（..）、畸形多斜杠一律 404。

宿主端工具 doc_preview_links

插件还会注册一个宿主端工具 doc_preview_links，让模型在会话中调用即可拿到「当前会话工作区」的 /docs 链接，用户在 Web 里点开即预览。

• 解析当前工作区：工具通过 exec.agent.session.header.cwd 感知当前会话，再与 ctx.workspaceRegistry.list() 匹配（精确 path 匹配优先，其次最长祖先匹配）—无需模型传参。
• 返回（JSON）：

  { "workspace": { "slug": "Users-alice-work-project", "path": "/Users/alice/work/project", "title": "project" },
    "workspaceUrl": "/docs/Users-alice-work-project/",
    "docs": [ { "name": "调研.md", "url": "/docs/Users-alice-work-project/docs/调研.md" } ] }
  

  传可选参数 rel 时，docs 列出该相对目录下 .md/.markdown/.html 的链接；不传则只给工作区根链接。
• 优雅降级：缺 cwd / 当前 cwd 未登记 / 无 registry 时不抛错，返回 { workspaceUrl: null, note: '…' }。
• 相对路径：返回 /docs/... 相对路径（前缀由宿主 Web 提供）；仅 Web 形态适用。
• 输出 schema 约束：doc_preview_links 通过 ctx.tools.register 以原始 ToolDefinition 注册，其 output.schema 必须使用 dsh 的强制 JSON-Schema 子集（object/array/string/number/integer/boolean/null）， 不能写作者 DSL 的 type: 'json'（那只在 defineTool() 里合法，会先编译成 annotation-only 节点； 原样传给 register 会触发 assertSupportedJsonSchema 报错、导致宿主启动失败）。这里用的是 annotation-only schema（不写 type = 任意 JSON），语义与 json 节点编译后完全一致。

安装

dsh plugin --profile web add /path/to/docs-preview-plugin

依赖：必须运行在已加载 ctx.webServer、ctx.workspaceRegistry 与 ctx.tools 的 profile（即 web 形态，dsh-web-app 自带这些服务）。headless / sdk 这类没有 web host 的 profile 不适用。

配置

无需配置即可工作。可选字段（cordis.patch.yml 的 config）：

字段	说明
base	保留的旧字面路径兜底根目录，默认 /（有 workspaceRegistry 时一般用不到）

文件结构

src/index.ts          # 插件源（name/inject/apply，/docs 路由 + md 渲染 + doc_preview_links 工具）
lib/index.js          # 构建产物（Loader 实际加载）
cordis.patch.yml      # 插入 doc-preview 行，inject webServer + tools + workspaceRegistry
tests/drive-route.mjs # 路由自测（mock workspaceRegistry）
tests/tools-test.mjs  # doc_preview_links 工具自测（mock registry + exec.agent）
tests/schema-test.mjs # 输出 schema 防回归自测（拒绝非法 type:'json'）
tests/render-test.mjs # md 渲染自测
tests/logic-test.mjs  # 渲染边界 + 穿越防护自测
README.md / ENABLE.md

自测

npm test                                          # build + 全部五套自测
node tests/drive-route.mjs                        # 工作区映射/隔离/404
node tests/tools-test.mjs                         # doc_preview_links 工具
node tests/schema-test.mjs                        # 输出 schema 防回归
tsx --tsconfig tsconfig.json tests/render-test.mjs
tsx --tsconfig tsconfig.json tests/logic-test.mjs

说明 / 限制

• 这是宿主端 HTTP 路由，/docs 无会话上下文；工作区由 URL 首段显式指定，索引页列出全部登记工作区。
• 渲染器为精简 Markdown 实现（标题/列表/表格/代码块/引用/粗斜体/行内代码/链接/复选框/分隔线）。
• 依赖 workspaceRegistry（@deepseek-ai/dsh-workspace，web profile 默认携带）。
• 当前为 private: true 的本地 bundle；如需分发给他人，可去掉 private 并补齐 files，或直接用 dsh plugin add <路径|git地址>。