dsh-doc-preview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek Harness plugin authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# 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 | 示例地址 |
+|---|---|---|
+| `/home/lc/deepseek-no1` | `home-lc-deepseek-no1` | `/docs/home-lc-deepseek-no1/docs-design/调研.md` |
+| `/root/documents` | `root-documents` | `/docs/root-documents/报告.md` |
+
+- 工作区列表来自 `ctx.workspaceRegistry.list()`（持久化于 `storages/workspace.json`），**新登记的工作区自动出现**，无需改插件。
+- **隔离**：请求被限制在对应工作区目录内；未知工作区、路径穿越（`..`）、畸形多斜杠一律 404。
+
+## 安装
+
+```sh
+dsh plugin --profile web add /path/to/docs-preview-plugin
+```
+
+依赖：必须运行在**已加载 `ctx.webServer` 与 `ctx.workspaceRegistry`** 的 profile（即 `web` 形态，
+dsh-web-app 自带这两个服务）。headless / sdk 这类没有 web host 的 profile 不适用。
+
+## 配置
+
+无需配置即可工作。可选字段（`cordis.patch.yml` 的 `config`）：
+
+| 字段 | 说明 |
+|---|---|
+| `base` | 保留的旧字面路径兜底根目录，默认 `/`（有 workspaceRegistry 时一般用不到） |
+
+## 文件结构
+
+```
+src/index.ts          # 插件源（name/inject/apply，路由 + md 渲染）
+lib/index.js          # 构建产物（Loader 实际加载）
+cordis.patch.yml      # 插入 doc-preview 行，inject webServer + workspaceRegistry
+tests/drive-route.mjs # 路由自测（mock workspaceRegistry）
+tests/render-test.mjs # md 渲染自测
+tests/logic-test.mjs  # 渲染边界 + 穿越防护自测
+README.md / ENABLE.md
+```
+
+## 自测
+
+```sh
+node tests/drive-route.mjs                        # 工作区映射/隔离/404
+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地址>`。

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-doc-preview bundle patch: add a /docs route that previews local docs.
+# It ONLY adds a new row; it does not redefine the existing `webserver` row
+# (that is owned by dsh-web-app). The plugin injects the already-present
+# `ctx.webServer` service and registers a prefix route on it.
+
+- insert:
+    - id: doc-preview
+      name: 'dsh-doc-preview'
+      inject: [webServer, workspaceRegistry]
+      config:
+        # /docs routes by real workspace, resolved from ctx.workspaceRegistry
+        # (the dsh-host-workspace service, present in every web profile).
+        #   /docs/                -> index of registered workspaces
+        #   /docs/<workspaceId>/<rel>  -> confined to that workspace directory
+        # workspaceId = workspace path with leading "/" dropped and "/" -> "-",
+        # e.g. /home/lc/deepseek-no1 -> home-lc-deepseek-no1.
+        # Example: /docs/home-lc-deepseek-no1/docs-design/调研.md

package/lib/index.js

@@ -0,0 +1,334 @@
+/**
+ * dsh-doc-preview — serve & preview local Markdown/HTML documents in the
+ * Web GUI through a /docs prefix route on ctx.webServer.
+ *
+ * This is a function plugin: it exports `name`, `inject`, `Config` and `apply`.
+ * It registers a `prefix` HTTP route on the already-present `ctx.webServer`
+ * service (mounted by dsh-web-app), so it composes into the `web` profile
+ * without redefining the webserver row.
+ *
+ * Route behavior under /docs:
+ *   /docs                       -> directory listing (HTML)
+ *   /docs/<x>.md                -> rendered HTML page
+ *   /docs/<x>.html              -> served raw
+ *   /docs/<x> (any other file)  -> served raw with an inferred content type
+ * Traversal outside `root` is rejected (404).
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, extname, resolve, sep } from 'node:path';
+export const name = 'doc-preview';
+export const inject = ['webServer', 'workspaceRegistry'];
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.md': 'text/html; charset=utf-8',
+    '.markdown': 'text/html; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.cjs': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.woff2': 'font/woff2',
+    '.yaml': 'text/plain; charset=utf-8',
+    '.yml': 'text/plain; charset=utf-8',
+};
+// ---------------------------------------------------------------------------
+// Minimal dependency-free Markdown -> HTML. Rooms for headings, lists, tables,
+// code fences, blockquote, bold/italic, inline code, links, hr, checkboxes.
+// ---------------------------------------------------------------------------
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function inline(s) {
+    return s
+        .replace(/`([^`]+)`/g, (_, c) => `<code>${esc(c)}</code>`)
+        .replace(/\*\*([^*]+)\*\*/g, (_, b) => `<strong>${esc(b)}</strong>`)
+        .replace(/\*([^*]+)\*/g, (_, i) => `<em>${esc(i)}</em>`)
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, t, u) => `<a href="${esc(u)}">${esc(t)}</a>`);
+}
+function renderTable(rows) {
+    const head = rows[0] ?? [];
+    const body = rows.slice(1);
+    let h = '<table><thead><tr>' + head.map(c => `<th>${c}</th>`).join('') + '</tr></thead><tbody>';
+    for (const r of body)
+        h += '<tr>' + r.map(c => `<td>${c}</td>`).join('') + '</tr>';
+    return h + '</tbody></table>';
+}
+export function markdownToHtml(md) {
+    const lines = md.split('\n');
+    const out = [];
+    let i = 0;
+    let inCode = false;
+    let codeBuf = [];
+    let inTable = false;
+    let tableRows = [];
+    let listStack = [];
+    let paraBuf = [];
+    const flushPara = () => {
+        if (paraBuf.length) {
+            out.push(`<p>${paraBuf.join(' ')}</p>`);
+            paraBuf = [];
+        }
+    };
+    const closeLists = () => { while (listStack.length)
+        out.push(`</${listStack.pop()}>`); };
+    const closeTable = () => { if (inTable) {
+        out.push(renderTable(tableRows));
+        tableRows = [];
+        inTable = false;
+    } };
+    for (; i < lines.length; i++) {
+        const line = lines[i];
+        if (inCode) {
+            if (/^```/.test(line)) {
+                inCode = false;
+                out.push(`<pre><code>${codeBuf.join('\n')}</code></pre>`);
+                codeBuf = [];
+            }
+            else
+                codeBuf.push(line);
+            continue;
+        }
+        if (/^```/.test(line)) {
+            inCode = true;
+            codeBuf = [];
+            continue;
+        }
+        if (line.trim() === '') {
+            flushPara();
+            closeTable();
+            if (listStack.length && !/^\s*(?:[-*]|\d+\.)\s/.test(lines[i + 1] ?? ''))
+                closeLists();
+            continue;
+        }
+        if (/^\s*(?:---|\*\*\*)\s*$/.test(line)) {
+            flushPara();
+            closeTable();
+            closeLists();
+            out.push('<hr>');
+            continue;
+        }
+        if (/^\s*\|/.test(line)) {
+            flushPara();
+            const parse = (l) => l.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => inline(c.trim()));
+            tableRows.push(parse(line));
+            inTable = true;
+            while (i + 1 < lines.length && /^\s*\|/.test(lines[i + 1])) {
+                i++;
+                if (/^\s*\|?[\s:|-]+\|?\s*$/.test(lines[i]) && tableRows.length >= 1)
+                    continue;
+                tableRows.push(parse(lines[i]));
+            }
+            continue;
+        }
+        const h = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (h) {
+            flushPara();
+            closeTable();
+            closeLists();
+            out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`);
+            continue;
+        }
+        if (/^>\s?/.test(line)) {
+            flushPara();
+            closeTable();
+            out.push(`<blockquote>${inline(line.replace(/^>\s?/, ''))}</blockquote>`);
+            continue;
+        }
+        const ul = /^\s*[-*]\s+(.*)$/.exec(line);
+        if (ul) {
+            flushPara();
+            closeTable();
+            if (listStack[listStack.length - 1] !== 'ul') {
+                out.push('<ul>');
+                listStack.push('ul');
+            }
+            const item = ul[1];
+            const cb = /^\[([ xX])\]\s+(.*)$/.exec(item);
+            if (cb)
+                out.push(`<li><input type="checkbox" ${cb[1].toLowerCase() === 'x' ? 'checked' : ''} disabled> ${inline(cb[2])}</li>`);
+            else
+                out.push(`<li>${inline(item)}</li>`);
+            continue;
+        }
+        const ol = /^\s*(\d+)\.\s+(.*)$/.exec(line);
+        if (ol) {
+            flushPara();
+            closeTable();
+            if (listStack[listStack.length - 1] !== 'ol') {
+                out.push('<ol>');
+                listStack.push('ol');
+            }
+            out.push(`<li>${inline(ol[2])}</li>`);
+            continue;
+        }
+        paraBuf.push(inline(line));
+    }
+    flushPara();
+    closeTable();
+    closeLists();
+    if (inCode)
+        out.push(`<pre><code>${codeBuf.join('\n')}</code></pre>`);
+    return out.join('\n');
+}
+function page(title, body) {
+    return `<!DOCTYPE html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>
+  :root{--bg:#fafaf8;--fg:#1a1a1a;--accent:#1e6fd9;--code:#f1f1ee;--border:#e2e2dd}
+  *{box-sizing:border-box}
+  body{font-family:-apple-system,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;background:var(--bg);color:var(--fg);line-height:1.7;margin:0;padding:24px}
+  main{max-width:900px;margin:0 auto;background:#fff;border:1px solid var(--border);border-radius:10px;padding:24px 32px}
+  h1,h2,h3{line-height:1.3}
+  h2{border-bottom:1px solid var(--border);padding-bottom:6px}
+  code{background:var(--code);border-radius:4px;padding:1px 5px;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:.9em}
+  pre{background:var(--code);border-radius:8px;padding:14px;overflow-x:auto}
+  pre code{background:none;padding:0}
+  table{border-collapse:collapse;width:100%;margin:14px 0;font-size:14px}
+  th,td{border:1px solid var(--border);padding:7px 10px;text-align:left;vertical-align:top}
+  th{background:#f3f3f0}
+  blockquote{border-left:4px solid var(--accent);background:#f5f8fd;padding:4px 14px;margin:12px 0}
+  a{color:var(--accent)}
+  ul,ol{padding-left:26px}
+  .breadcrumb{color:#666;font-size:13px;margin-bottom:12px}
+  .breadcrumb a{text-decoration:none}
+</style></head><body><main>${body}</main></body></html>`;
+}
+// ---------------------------------------------------------------------------
+// Route plumbing
+// ---------------------------------------------------------------------------
+/**
+ * Workspace-namespaced routing over the real dsh workspace registry.
+ * /docs/                    -> index of all registered workspaces
+ * /docs/<workspaceId>/      -> directory listing of that workspace root
+ * /docs/<workspaceId>/<rel>.md -> rendered doc
+ * `<workspaceId>` is the workspace path with the leading "/" removed and "/"
+ * replaced by "-" (e.g. /home/lc/deepseek-no1 -> home-lc-deepseek-no1),
+ * derived from ctx.workspaceRegistry.list(). Only registered workspaces
+ * resolve; each request is confined to that workspace's directory.
+ */
+function decodeSeg(p) {
+    try {
+        return decodeURIComponent(p);
+    }
+    catch {
+        return p;
+    }
+}
+function slugOf(path) {
+    return path.replace(/^\/+/, '').replace(/\//g, '-');
+}
+function splitWsRel(pathname) {
+    let raw = decodeSeg(pathname.replace(/^\/docs/, ''));
+    if (raw.startsWith('/'))
+        raw = raw.slice(1); // normalize the single "/" after /docs
+    if (raw.startsWith('/'))
+        return { slug: '\u0000', rel: '' }; // repeated slash -> malformed
+    if (raw === '')
+        return { slug: '', rel: '' };
+    const first = raw.indexOf('/');
+    if (first === -1)
+        return { slug: raw, rel: '' };
+    return { slug: raw.slice(0, first), rel: raw.slice(first + 1) };
+}
+function safeJoin(basePath, rel) {
+    if (rel === '')
+        return resolve(basePath);
+    const target = resolve(basePath, rel);
+    const baseResolved = resolve(basePath);
+    if (target === baseResolved)
+        return target;
+    const prefix = baseResolved.endsWith(sep) ? baseResolved : baseResolved + sep;
+    if (!target.startsWith(prefix))
+        return null;
+    return target;
+}
+/** Build the absolute href for an entry inside the current directory path. */
+function relHref(dirPath, entry) {
+    const base = (dirPath === '/docs' || dirPath === '' ? '/docs' : dirPath.replace(/\/$/, ''));
+    return `${base}/${entry}`;
+}
+function listWorkspaces(wsRegistry) {
+    try {
+        return (wsRegistry?.list?.() ?? []).map(w => ({
+            slug: slugOf(w.path),
+            path: w.path,
+            title: w.title || w.path,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+async function serve(req, res, config, wsRegistry) {
+    const pathname = req.url.split('?')[0] ?? '/docs/';
+    const { slug, rel } = splitWsRel(pathname);
+    const workspaces = listWorkspaces(wsRegistry);
+    if (slug === '') {
+        const items = workspaces.length
+            ? workspaces.map(w => `<li><a href="/docs/${esc(w.slug)}/">${esc(w.title)} <code>(${esc(w.path)})</code></a></li>`).join('\n')
+            : '<li><em>(未登记任何工作区)</em></li>';
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(page('Document workspaces', `<h1>Document workspaces</h1><ul>${items}</ul>`));
+        return;
+    }
+    const ws = workspaces.find(w => w.slug === slug);
+    if (ws === undefined) {
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Unknown workspace');
+        return;
+    }
+    const target = safeJoin(ws.path, rel);
+    if (target === null) {
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Not found');
+        return;
+    }
+    try {
+        const info = await stat(target);
+        if (info.isDirectory()) {
+            const entries = await readdir(target);
+            entries.sort();
+            const items = entries
+                .map(e => `<li><a href="${relHref(pathname, e)}">${esc(e)}${e.indexOf('.') === -1 ? '/' : ''}</a></li>`)
+                .join('\n');
+            const up = `<div class="breadcrumb"><a href="/docs/">workspaces</a> / <a href="/docs/${esc(slug)}/">${esc(slug)}</a>${rel ? ' / ' + esc(rel) : ''}</div>`;
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(page(`Directory: ${slug}/${rel}`, `${up}<h1>${esc(slug)}/${esc(rel)}</h1><ul>${items}</ul>`));
+            return;
+        }
+        const ext = extname(target).toLowerCase();
+        const raw = await readFile(target);
+        if (ext === '.md' || ext === '.markdown') {
+            const html = markdownToHtml(raw.toString('utf8'));
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(page(basename(target), html));
+            return;
+        }
+        res.writeHead(200, {
+            'content-type': MIME[ext] ?? 'application/octet-stream',
+            'content-length': raw.byteLength,
+        });
+        res.end(raw);
+    }
+    catch {
+        res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end('Not found');
+    }
+}
+export function apply(ctx, config) {
+    const wsRegistry = ctx.workspaceRegistry;
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'prefix',
+        path: '/docs',
+        handler: (req, res) => serve(req, res, config ?? {}, wsRegistry),
+    }));
+}

package/lib/types/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * dsh-doc-preview public type surface.
+ *
+ * Dependency-free: the `Context` type here is a narrow structural shape so
+ * consumers do not need to resolve `@deepseek-ai/cordis` just to type-check
+ * imports of this package. At runtime nothing from this file is required.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** A workspace projected from ctx.workspaceRegistry.list(). */
+export interface WorkspaceLike {
+  readonly path: string
+  readonly title?: string
+}
+
+/** Route registration surface this plugin consumes from ctx.webServer. */
+declare interface WebServerLike {
+  register(route: {
+    kind: 'exact' | 'prefix'
+    path: string
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+  }): () => void
+}
+
+/** Minimal cordis Context shape this plugin depends on. */
+export interface ContextLike {
+  webServer: WebServerLike
+  workspaceRegistry: { list(): WorkspaceLike[] }
+  effect(fn: () => void): void
+}
+
+/** Plugin row identity. */
+export declare const name: 'doc-preview'
+/** Cordis services this plugin injects. */
+export declare const inject: ['webServer', 'workspaceRegistry']
+
+export interface Config {
+  /**
+   * Reserved legacy literal-path fallback root (default "/"). Ignored when the
+   * workspace registry is available.
+   */
+  base?: string
+}
+
+/** Render Markdown to an HTML fragment (headings/lists/tables/code/quote/links). */
+export declare function markdownToHtml(markdown: string): string
+
+/** Cordis plugin entry point. */
+export declare function apply(ctx: ContextLike, config?: Config): void

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "dsh-doc-preview",
+  "version": "0.1.0",
+  "description": "A dsh bundle plugin: preview local Markdown/HTML documents per workspace in the Web GUI via a /docs route on ctx.webServer + ctx.workspaceRegistry.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "plugin",
+    "document-preview",
+    "markdown",
+    "web"
+  ],
+  "engines": {
+    "node": ">=22.6"
+  },
+  "author": "DeepSeek Harness plugin authors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cong543/dsh-doc-preview.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cong543/dsh-doc-preview/issues"
+  },
+  "homepage": "https://github.com/cong543/dsh-doc-preview#readme",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "prepublishOnly": "node scripts/build.mjs",
+    "render:test": "tsx --tsconfig ./tsconfig.json tests/render-test.mjs",
+    "logic:test": "tsx --tsconfig ./tsconfig.json tests/logic-test.mjs",
+    "route:test": "node tests/drive-route.mjs",
+    "test": "node scripts/build.mjs && node tests/drive-route.mjs && tsx --tsconfig ./tsconfig.json tests/render-test.mjs && tsx --tsconfig ./tsconfig.json tests/logic-test.mjs"
+  }
+}