dsh-doc-preview 0.1.0 → 0.1.2

package/README.md

@@ -18,20 +18,37 @@ http://<host>/docs/<工作区id>/<相对路径>.md -> 渲染该工作区内的
 
 | 工作区目录 | 工作区 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` |
+| `/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）：
+  ```jsonc
+  { "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 形态适用。
+
 ## 安装
 
 ```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 不适用。
+依赖：必须运行在**已加载 `ctx.webServer`、`ctx.workspaceRegistry` 与 `ctx.tools`** 的 profile（即 `web`
+形态，dsh-web-app 自带这些服务）。headless / sdk 这类没有 web host 的 profile 不适用。
 
 ## 配置
 
@@ -44,10 +61,11 @@ dsh-web-app 自带这两个服务）。headless / sdk 这类没有 web host 的
 ## 文件结构
 
 ```
-src/index.ts          # 插件源（name/inject/apply，路由 + md 渲染）
+src/index.ts          # 插件源（name/inject/apply，/docs 路由 + md 渲染 + doc_preview_links 工具）
 lib/index.js          # 构建产物（Loader 实际加载）
-cordis.patch.yml      # 插入 doc-preview 行，inject webServer + workspaceRegistry
+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/render-test.mjs # md 渲染自测
 tests/logic-test.mjs  # 渲染边界 + 穿越防护自测
 README.md / ENABLE.md
@@ -56,7 +74,9 @@ README.md / ENABLE.md
 ## 自测
 
 ```sh
+npm test                                          # build + 全部四套自测
 node tests/drive-route.mjs                        # 工作区映射/隔离/404
+node tests/tools-test.mjs                         # doc_preview_links 工具
 tsx --tsconfig tsconfig.json tests/render-test.mjs
 tsx --tsconfig tsconfig.json tests/logic-test.mjs
 ```

package/cordis.patch.yml

@@ -6,12 +6,14 @@
 - insert:
     - id: doc-preview
       name: 'dsh-doc-preview'
-      inject: [webServer, workspaceRegistry]
+      inject: [webServer, tools, 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
+        # e.g. /Users/alice/work/project -> Users-alice-work-project.
+        # Example: /docs/Users-alice-work-project/docs/调研.md
+        # Additionally registers the host tool `doc_preview_links` (via ctx.tools)
+        # so the agent can report the current workspace's /docs links.

package/lib/index.js

@@ -17,7 +17,7 @@
 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'];
+export const inject = ['webServer', 'tools', 'workspaceRegistry'];
 const MIME = {
     '.html': 'text/html; charset=utf-8',
     '.md': 'text/html; charset=utf-8',
@@ -211,7 +211,7 @@ function page(title, body) {
  * /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),
+ * replaced by "-" (e.g. /Users/alice/work/project -> Users-alice-work-project),
  * derived from ctx.workspaceRegistry.list(). Only registered workspaces
  * resolve; each request is confined to that workspace's directory.
  */
@@ -268,6 +268,111 @@ function listWorkspaces(wsRegistry) {
         return [];
     }
 }
+/** Resolve the current session workspace by matching `cwd` against the registry. */
+function matchWorkspace(cwd, wsRegistry) {
+    if (!cwd)
+        return null;
+    let workspaces = [];
+    try {
+        workspaces = (wsRegistry?.list?.() ?? []).map(w => ({
+            slug: slugOf(w.path),
+            path: w.path,
+            title: w.title || w.path,
+        }));
+    }
+    catch {
+        return null;
+    }
+    // Exact path match first; fall back to a trailing-segment match so a cwd that
+    // is a descendant of a registered workspace resolves to the nearest workspace.
+    const exact = workspaces.find(w => w.path === cwd);
+    if (exact)
+        return exact;
+    const ancestor = workspaces
+        .filter(w => cwd === w.path || cwd.startsWith(w.path.endsWith(sep) ? w.path : w.path + sep))
+        .sort((a, b) => b.path.length - a.path.length)[0];
+    return ancestor ?? null;
+}
+/** Build a /docs URL for a workspace slug + optional relative path. */
+function docUrl(slug, rel) {
+    const root = `/docs/${slug}/`;
+    if (!rel)
+        return root;
+    return root + rel.replace(/^\/+/, '');
+}
+function renderJson(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+}
+function createDocPreviewLinks(wsRegistry) {
+    return {
+        name: 'doc_preview_links',
+        description: 'Return the /docs preview URLs for the current session\u2019s workspace (Web GUI only). ' +
+            'Use when the user wants to preview local Markdown/HTML documents: it reports the workspace\u2019s ' +
+            '/docs home URL and, when a `rel` path is given, the document links under that directory.',
+        parameters: {
+            rel: {
+                type: 'string',
+                description: 'Optional relative path under the workspace root whose document links to list.',
+                optional: true,
+            },
+        },
+        output: {
+            schema: { type: 'json' },
+            render: renderJson,
+        },
+        async execute(args, exec) {
+            const agent = exec.agent;
+            const cwd = agent?.session?.header?.cwd;
+            const ws = matchWorkspace(cwd, wsRegistry);
+            if (ws === null) {
+                return {
+                    workspaceUrl: null,
+                    workspace: null,
+                    docs: [],
+                    note: cwd
+                        ? 'workspace not registered for this cwd (doc-preview resolves via workspaceRegistry)'
+                        : 'no session cwd available (doc-preview links require the Web workspace registry)',
+                };
+            }
+            const result = {
+                workspace: ws,
+                workspaceUrl: docUrl(ws.slug),
+                docs: [],
+            };
+            if (args.rel) {
+                const entries = await listDocs(ws.path, args.rel);
+                result.docs = entries.map(e => ({ name: e.name, url: docUrl(ws.slug, e.rel) }));
+            }
+            return result;
+        },
+    };
+}
+/** List .md/.markdown/.html files under a workspace-relative directory. */
+async function listDocs(wsPath, rel) {
+    const dir = safeJoin(wsPath, rel);
+    if (dir === null)
+        return [];
+    try {
+        const info = await stat(dir);
+        if (!info.isDirectory())
+            return [];
+        const entries = await readdir(dir);
+        entries.sort();
+        const out = [];
+        for (const e of entries) {
+            if (e.startsWith('.'))
+                continue; // skip hidden entries
+            const ext = extname(e).toLowerCase();
+            if (ext !== '.md' && ext !== '.markdown' && ext !== '.html')
+                continue;
+            out.push({ name: e, rel: (rel ? rel.replace(/\/$/, '') + '/' : '') + e });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
 async function serve(req, res, config, wsRegistry) {
     const pathname = req.url.split('?')[0] ?? '/docs/';
     const { slug, rel } = splitWsRel(pathname);
@@ -331,4 +436,11 @@ export function apply(ctx, config) {
         path: '/docs',
         handler: (req, res) => serve(req, res, config ?? {}, wsRegistry),
     }));
+    // Host-side tool: let the agent report the current workspace's /docs links so
+    // the user can jump straight to previewing their docs. Registered globally;
+    // exec.agent is still the calling agent (injected by the agent loop).
+    // Guarded on ctx.tools so routes still work in hosts without a tool registry.
+    if (ctx.tools) {
+        ctx.effect(() => ctx.tools.register(createDocPreviewLinks(wsRegistry)));
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-doc-preview",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -63,6 +63,7 @@
     "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"
+    "tools:test": "node tests/tools-test.mjs",
+    "test": "node scripts/build.mjs && node tests/drive-route.mjs && node tests/tools-test.mjs && tsx --tsconfig ./tsconfig.json tests/render-test.mjs && tsx --tsconfig ./tsconfig.json tests/logic-test.mjs"
   }
 }