dsh-pictor 0.2.0 → 0.2.1

package/NOTICE.md

@@ -0,0 +1,18 @@
+# NOTICE — 第三方内容声明
+
+本仓库包含以下源自第三方的内容，请在分发或再使用时留意相应许可：
+
+## references/paper/
+
+- `2601.23265v1.md`：arXiv 预印本 2601.23265v1 的正文提取（仅文本，不含 PDF），
+  作为研究背景资料随源码仓库分发。
+- `paperbanana-prompts.md`：同一 arXiv 预印本附录 G、H 中提示词原文的忠实提取与中文翻译。
+
+两者均**不随发布包分发**（package.json 的 files 仅含 `references/domain`），
+只存在于源码仓库。再分发请以 arXiv 原文及其作者声明的许可为准。
+
+## 免责声明
+
+除上述文件外，本仓库其余内容（agents/ 蓝图、references/domain/ 模板与规范、
+src/、fixtures/ 示例文档）均为作者原创。样式与布局模板的早期版本
+曾参考 PaperBanana（arXiv:2601.23265v1）的设计思路，但经重写已不包含其原文。

package/README.md

@@ -20,6 +20,10 @@ Replace `<profile>` with the target profile name (e.g. `desktop`, `web`) and sta
 
 > Install the Pictor plugin from the npm package `dsh-pictor` into the current profile, restart if needed, and confirm when a Pictor button appears at the bottom left.
 
+## Supported dsh version
+
+Pictor is built and tested against **DSH Desktop 0.7.2** (bundled Harness **0.1.2-alpha.1**). The DeepSeek Harness client API moves quickly — the workspace/session services it exposes keep changing — so this plugin intentionally tracks one harness generation. Other versions (older or newer) may work or may break without notice, and are outside our support scope. If something stops working after a DSH update, update dsh to the version above rather than debugging the mismatch.
+
 ## Usage
 
 1. Open the workbench via the **Pictor** footer button and click **New project**: upload a file (`md` / `txt` / `docx` / `pdf` / image) or paste content (from Word or the web; formatting is kept, stored as sanitised HTML).
@@ -47,10 +51,15 @@ Replace `<profile>` with the target profile name (e.g. `desktop`, `web`) and sta
 ```bash
 npm run build                # esbuild build of host + bundled client
 npm run verify               # L1 unit + L2 host integration (mock ctx, 15 items)
-npm run verify:integration   # L3 transport smoke against a real dsh web
+npm run verify:integration   # L3 transport smoke against a real dsh web (hermetic temp home)
+npm run test:pack            # package integrity: tarball carries lib/, agents/, references/, assets/
+npm run test:install         # L5: README install path (dsh plugin add) → real dsh web boot
 npm run test:e2e             # L4a browser e2e (fixture data, deterministic)
+npm run hooks:install        # one-time: enable the pre-push hook (git config core.hooksPath .githooks)
 ```
 
+The pre-push hook runs `npm run verify` + `npm run test:install` before every push; all smoke layers are hermetic (temp `DSH_HOME`, never the live `~/.dsh`).
+
 Test-layer definitions and rationale: [docs/DESIGN.zh.md](docs/DESIGN.zh.md) §7.
 
 ### Layout

package/README.zh-cn.md

@@ -20,6 +20,10 @@ dsh plugin --profile <profile> add dsh-pictor
 
 > 帮我把 Pictor 插件装上，从 npm 包 dsh-pictor 装到当前 profile，需要的话重启，装好告诉我左下角有没有 Pictor 入口。
 
+## 适配的 DSH 版本
+
+Pictor 以 **DSH Desktop 0.7.2**（内置 Harness **0.1.2-alpha.1**）为适配与测试基准。DeepSeek Harness 的客户端 API（工作区/会话服务）演进很快，本月两个版本之间可能就面目全非，所以本插件只跟住一个 harness 世代。其他版本——无论更旧更新——可能能跑、也可能无预告地坏掉，都不在我们的支持范围内。DSH 升级后插件不工作，请先回到上面这个版本，而不是去排查版本差异。
+
 ## 使用
 
 1. 打开工作台，点「新建项目」：上传文件（md/txt/docx/pdf/图片）或粘贴内容（从 Word/网页粘贴，格式保留，落盘为消毒 HTML）。
@@ -47,10 +51,15 @@ dsh plugin --profile <profile> add dsh-pictor
 ```bash
 npm run build         # esbuild 构建 host + 拼接 client
 npm run verify        # L1 单元 + L2 host 集成（mock ctx，15 项）
-npm run verify:integration   # L3 transport 冒烟（真实 dsh web）
+npm run verify:integration   # L3 transport 冒烟（真实 dsh web，封闭临时 DSH_HOME）
+npm run test:pack     # 打包完整性：tarball 必带 lib/、agents/、references/、assets/
+npm run test:install  # L5：README 安装路径（dsh plugin add）→ 真实 dsh web 启动
 npm run test:e2e      # L4a 浏览器 e2e（fixture 数据，确定性）
+npm run hooks:install # 一次性启用 pre-push 钩子（git config core.hooksPath .githooks）
 ```
 
+pre-push 钩子在每次 push 前依次跑 `npm run verify` 与 `npm run test:install`；所有冒烟层都是封闭式（临时 `DSH_HOME`，不碰真实 `~/.dsh`）。
+
 测试分层的定义与理由见 [docs/DESIGN.zh.md](docs/DESIGN.zh.md) 第 7 节。
 
 ## 目录

package/lib/client.js

@@ -487,10 +487,23 @@ function sanitizePaste(html) {
 // 会话创建与驱动走 dsh 的 workspace 流程（照 pomasa 的 driveSession）：
 // 宿主只出 prompt，客户端经 workspaces.connectWorkspace 建会话（自然归入
 // 「Pictor」工作区、继承 profile 默认模型），再经 sessions.prompt 驱动。
+// dsh ≥ 0.1.2-alpha.1（DSH Desktop 0.7.2）把 connectWorkspace 从
+// `workspaces` 服务移到了 `uiWorkspace` 服务上：这里两个形态都尝试，哪个
+// 在就调哪个，老版本前端不受影响。
+function sessionConnectFn(ctx, ws) {
+  let uiWs = null
+  try { uiWs = ctx.uiWorkspace || ((ctx.get && ctx.get('uiWorkspace')) || null) } catch { /* ignore */ }
+  return (uiWs && typeof uiWs.connectWorkspace === 'function')
+    ? uiWs.connectWorkspace.bind(uiWs)
+    : (ws && typeof ws.connectWorkspace === 'function') ? ws.connectWorkspace.bind(ws) : null
+}
+
 async function pictorWorkspace(ctx) {
   const ws = ctx.workspaces || (ctx.get && ctx.get('workspaces'))
   const base = await rpc(ctx, 'config.get').then((c) => (c && c.dataRoot) || '')
-  if (!ws || typeof ws.connectWorkspace !== 'function') throw new Error('会话服务不可用（workspaces）')
+  // 这里只用 list/create/delete/rename，新旧 services 都有；connectWorkspace
+  // 的可用性由 driveProjectSession 检查。
+  if (!ws) throw new Error('会话服务不可用（workspaces）')
   const items = () => {
     try {
       const snap = ws.list && typeof ws.list.getSnapshot === 'function' ? ws.list.getSnapshot() : null
@@ -531,14 +544,29 @@ async function pictorWorkspace(ctx) {
 async function driveProjectSession(ctx, prompt) {
   const ws = ctx.workspaces || (ctx.get && ctx.get('workspaces'))
   const sessionsSvc = ctx.sessions || (ctx.get && ctx.get('sessions'))
+  const connect = sessionConnectFn(ctx, ws)
+  const canCreate = !!(sessionsSvc && typeof sessionsSvc.create === 'function')
+  if (!(connect || canCreate) || !(sessionsSvc && typeof sessionsSvc.binding === 'function')) {
+    let uiWs = null
+    try { uiWs = ctx.uiWorkspace || ((ctx.get && ctx.get('uiWorkspace')) || null) } catch { /* ignore */ }
+    const diag = { ws: !!ws, ses: !!sessionsSvc && typeof sessionsSvc.binding === 'function', uiws: !!uiWs, conn: !!connect, create: canCreate }
+    console.warn('[pictor] session services unavailable', diag)
+    try { window.__pictor_diag = diag } catch { /* ignore */ }
+    try { pictorDiag(ctx, 'drive:fail') } catch { /* ignore */ }
+    throw new Error(`会话服务不可用（workspaces） [ws:${diag.ws},ses:${diag.ses},uiws:${diag.uiws},conn:${diag.conn},create:${diag.create}]`)
+  }
   const wid = await pictorWorkspace(ctx)
   let sessionId
-  try { sessionId = await ws.connectWorkspace(wid) }
+  try {
+    const created = connect ? await connect(wid) : await sessionsSvc.create({ workspaceId: wid })
+    sessionId = created && typeof created === 'object' && created.id ? created.id : created
+  }
   catch (e) { throw new Error('创建会话失败：' + String((e && e.message) || e)) }
   const bound = sessionsSvc && typeof sessionsSvc.binding === 'function' ? sessionsSvc.binding(sessionId) : null
   const sess = bound && bound.session
   if (!sess || typeof sess.prompt !== 'function') throw new Error('会话无 prompt 通道')
   await sess.prompt([{ type: 'text', text: String(prompt || '') }], 'queue')
+  try { pictorDiag(ctx, 'drive:ok') } catch { /* ignore */ }
   return sessionId
 }
 
@@ -945,7 +973,17 @@ function fileSlug(s) {
   return String(s || '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'infographic'
 }
 
-function ResultsPanel({ outputs, images, renderErrors, proposals, lay, renderBatches }) {
+// 结果图直出走同源 HTTP（data URL 在新版 DSH Desktop WebView 可能被拦），
+// 失败时回退到 RPC 返回的 data URL。
+const imgUrlFor = (projectId, name) => {
+  const base = '/pictor/asset/project/' + encodeURIComponent(projectId) + '/' + encodeURIComponent(name)
+  try {
+    const tok = new URLSearchParams(window.location.search || '').get('token')
+    return tok ? base + '?token=' + encodeURIComponent(tok) : base
+  } catch { return base }
+}
+
+function ResultsPanel({ projectId, outputs, images, renderErrors, proposals, lay, renderBatches }) {
   const [big, setBig] = React.useState(null)
   const [collapsed, setCollapsed] = React.useState({})
   if (!outputs.length && !renderErrors.length) {
@@ -967,7 +1005,7 @@ function ResultsPanel({ outputs, images, renderErrors, proposals, lay, renderBat
         h('div', null, h('h3', { className: 'pt-option-title', style: { margin: 0 } }, bigInfo.title)),
         h('button', { className: 'pt-modal-close', onClick: () => setBig(null), title: t('close'), 'aria-label': t('close') }, '×')),
       h('div', { className: 'pt-modal-body', style: { textAlign: 'center' } },
-        h('img', { src: images[big], alt: bigInfo.title, style: { maxWidth: '100%', maxHeight: '70vh', borderRadius: 10 } }),
+        h('img', { src: imgUrlFor(projectId, big), alt: bigInfo.title, style: { maxWidth: '100%', maxHeight: '70vh', borderRadius: 10 }, onError: (e) => { if (e && e.currentTarget) e.currentTarget.src = images[big] } }),
         bigInfo.actualLayout ? h('p', { className: 'pt-meta', style: { marginTop: 10 } }, t('layoutLabel') + ': ' + layoutLabel(bigInfo.actualLayout)) : null)))
     : null
 
@@ -991,7 +1029,7 @@ function ResultsPanel({ outputs, images, renderErrors, proposals, lay, renderBat
     const dlName = info.prop ? (fileSlug(info.prop.title || layoutLabel(info.actualLayout || info.prop.suggested_layout)) + '-' + info.pid + '.png') : name
     return h('figure', { key: name, className: 'pt-img-card' },
       images[name]
-        ? h('img', { className: 'pt-img', src: images[name], alt: info.title, style: { cursor: 'zoom-in' }, onClick: () => setBig(name) })
+        ? h('img', { className: 'pt-img', src: imgUrlFor(projectId, name), alt: info.title, style: { cursor: 'zoom-in' }, onClick: () => setBig(name), onError: (e) => { if (e && e.currentTarget) e.currentTarget.src = images[name] } })
         : h('div', { className: 'thumb', style: { width: '100%', height: 140 } }),
       h('figcaption', null,
         h('div', { className: 'pt-fig-title' }, info.title),
@@ -1405,7 +1443,7 @@ function DetailPane(props) {
       ratios, setRatio, onRender: renderSelected, renderBusy,
       hasImageKey: Boolean(imageCfg && imageCfg.hasKey), running: Boolean(data.running),
       renderState: data.renderState, renderRunning: Boolean(data.renderRunning) }),
-    render: h(ResultsPanel, { outputs: data.outputs, images, renderErrors, proposals, lay: layOv, renderBatches: data.renderBatches }),
+    render: h(ResultsPanel, { projectId, outputs: data.outputs, images, renderErrors, proposals, lay: layOv, renderBatches: data.renderBatches }),
   }[step]
 
   return h('div', null,
@@ -1670,7 +1708,30 @@ function selectedLabel(ids) {
   return ids.join('、')
 }
 
+// 最佳努力诊断：上报此 ctx 上工作区/会话服务的暴露情况（DSH Desktop 0.7.2
+// 调整了客户端 API），host 落盘 ~/.pictor/diag.jsonl，无需 DevTools 即可排查。
+function pictorDiag(ctx, phase) {
+  let ws = null, ses = null, ui = null
+  try { ws = ctx && (ctx.workspaces || (ctx.get && ctx.get('workspaces'))) } catch { /* ignore */ }
+  try { ses = ctx && (ctx.sessions || (ctx.get && ctx.get('sessions'))) } catch { /* ignore */ }
+  try { ui = ctx && (ctx.uiWorkspace || (ctx.get && ctx.get('uiWorkspace'))) } catch { /* ignore */ }
+  const body = {
+    phase,
+    ws: !!ws, ses: !!ses, ui: !!ui,
+    wsMethods: ws ? Object.keys(ws).slice(0, 40) : null,
+    sesMethods: ses ? Object.keys(ses).slice(0, 40) : null,
+    uiMethods: ui ? Object.keys(ui).slice(0, 40) : null,
+    connectWs: !!(ws && typeof ws.connectWorkspace === 'function'),
+    connectUi: !!(ui && typeof ui.connectWorkspace === 'function'),
+    bind: !!(ses && typeof ses.binding === 'function'),
+    href: typeof location !== 'undefined' ? location.href.slice(0, 80) : '',
+  }
+  try { fetch('/pictor/diag', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }).catch(() => {}) } catch { /* ignore */ }
+  console.warn('[pictor] diag', body)
+}
+
 function apply(ctx) {
+  try { pictorDiag(ctx, 'apply') } catch { /* ignore */ }
   console.info('[dsh-pictor] apply 被调用', { hasSlots: Boolean(ctx && ctx.slots) })
   if (typeof document !== 'undefined') {
     const styleId = 'dsh-pictor-style'

package/lib/index.js

@@ -702,6 +702,52 @@ function apply(ctx, config = {}) {
         } });
       }
     }
+    const PREFIX = "/pictor/asset/project";
+    wsA.register({ kind: "prefix", path: PREFIX, handler: (req, res) => {
+      try {
+        const pathname = new URL(req.url || "/", "http://x").pathname;
+        const rest = pathname.slice(PREFIX.length + 1);
+        const slash = rest.indexOf("/");
+        if (slash <= 0) {
+          res.writeHead(404);
+          res.end("not found");
+          return;
+        }
+        const id = rest.slice(0, slash);
+        const file = rest.slice(slash + 1);
+        if (id.includes("..") || /[\\/]/.test(id) || !/^[0-9a-zA-Z_.-]+$/.test(file) || !file.endsWith(".png")) {
+          res.writeHead(400);
+          res.end("bad request");
+          return;
+        }
+        const buf = readFileSync(join(projectDir(id), "output", file));
+        res.writeHead(200, { "content-type": "image/png", "cache-control": "public, max-age=300" });
+        res.end(buf);
+      } catch {
+        res.writeHead(404);
+        res.end("not found");
+      }
+    } });
+    wsA.register({ kind: "exact", path: "/pictor/diag", handler: (req, res) => {
+      let body = "";
+      try {
+        req.on("data", (c) => {
+          body += c;
+        });
+        req.on("end", () => {
+          try {
+            mkdirSync(base, { recursive: true });
+            appendFileSync(join(base, "diag.jsonl"), JSON.stringify({ t: Date.now(), ...JSON.parse(body || "{}") }) + "\n");
+          } catch {
+          }
+          res.writeHead(204);
+          res.end();
+        });
+      } catch {
+        res.writeHead(204);
+        res.end();
+      }
+    } });
   }
   return { dataRoot: base };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pictor",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pictor：文档转信息图工作台。每项目一个连贯 dsh 会话，GUI 为 shell.overlay 工作台（左栏项目、右栏三步：提取/方案/渲染），行为全部交给 DSH 智能运行时。",
   "type": "module",
   "repository": {
@@ -46,12 +46,16 @@
     "docs",
     "README.md",
     "LICENSE",
-    "assets"
+    "assets",
+    "NOTICE.md"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
     "verify": "node scripts/build.mjs && node verify.mjs",
     "verify:integration": "bash scripts/transport-smoke.sh",
+    "test:pack": "bash scripts/package-integrity.sh",
+    "test:install": "bash scripts/install-smoke.sh",
+    "hooks:install": "git config core.hooksPath .githooks",
     "test:e2e": "playwright test --config e2e/playwright.config.ts --project chromium",
     "verify:live": "playwright test --config e2e/playwright.config.ts --project live",
     "prepare": "node scripts/build.mjs"