Pictor — 文档转信息图工作台

[ English | 中文 ]

Pictor 把一份文档变成一组信息图。它是 DeepSeek Harness（dsh）的插件，已发布到 npm 包 dsh-pictor，源码仓库在 github.com/bandung-circuits/pictor。每新建一个项目，宿主创建一个连贯的会话作为项目会话，整个「提取 → 方案 → 渲染」流程都在这个会话里推进，GUI 只做两件事：查看信息、规整输入。设计文档见 docs/DESIGN.zh.md。

安装

已发布到 npm，包名 dsh-pictor。它的 GUI 入口在共享的应用坞里，所以 Pictor 依赖 dsh-app-dock 插件：先装坞，再装 Pictor。

npx @deepseek-ai/dsh plugin --profile web add dsh-app-dock
npx @deepseek-ai/dsh plugin --profile web add dsh-pictor

把 web 换成目标 profile 名（如 desktop、web），然后启动该 profile，dsh 左下角坞的图标网格里会出现「Pictor」按钮。只有坞缺席时，pictor 的 client 半才会在短暂宽限期后兜底自占一个 footer 按钮——上面的两步安装才是受支持的路径。首次使用自动生成 ~/.pictor 工作区（注册为 dsh 工作区，侧栏归组见「Pictor」）。开发安装（改动源码实时联调）见 docs/DESIGN.zh.md。

非技术用户可安装 DSH Desktop（社区维护项目，非 DeepSeek 官方产品，把 DeepSeek Harness 运行封装成可直接打开的桌面应用），然后让 dsh 里的 AI 帮装，发这一句即可：

帮我把共享坞插件 dsh-app-dock 和 Pictor 插件 dsh-pictor 依次装到当前 profile，需要的话重启，装好告诉我左下角的 app 网格里有没有 Pictor 入口。

适配的 DSH 版本

Pictor 以 DSH Desktop 0.7.2（内置 Harness 0.1.2-alpha.1）为适配与测试基准。DeepSeek Harness 的客户端 API（工作区/会话服务）演进很快，本月两个版本之间可能就面目全非，所以本插件只跟住一个 harness 世代。其他版本——无论更旧更新——可能能跑、也可能无预告地坏掉，都不在我们的支持范围内。DSH 升级后插件不工作，请先回到上面这个版本，而不是去排查版本差异。

使用

1. 打开工作台（左下角应用坞里的「Pictor」），点「新建项目」：上传文件（md/txt/docx/pdf/图片）或粘贴内容（从 Word/网页粘贴，格式保留，落盘为消毒 HTML）。
2. 会话读取并规整来源（docx/pdf/图片/HTML → document.md 由会话用 dsh 工具完成），提取候选结构。
3. 勾选结构，确认，会话进入方案设计；勾选方案，设画面比例，点「渲染所选方案」。
4. 结果网格里预览、下载；随时可展开讨论面板对会话说话，或点步骤条回到已有产物的步骤重做。

形态

• 安装后首次使用自动生成 ~/.pictor 工作区（注册为 dsh 工作区，侧栏归组见「Pictor」）。
• 唯一入口是左下角应用坞里的「Pictor」按钮（所有 Bandung 应用共用一个坞；坞缺席时才退回自持 footer 按钮），打开 shell.overlay 工作台：左栏列项目，右栏显示当前项目。
• 项目步骤固定三步：提取结构 → 方案设计 → 渲染出图。每步由你做决定后，会话在同一会话里接着执行（agent-loop 的 resume 语义），不重跑已有阶段。
• 项目名取文档首行，信息条内随时可改名，只动 index.json。
• 状态只由文件事实驱动；运行中判定以 dsh agent 注册表为权威；把你对 orchestration 的关心都留给会话。

两个模型

• 推理模型：extract 与 advise 用 dsh 当前默认模型，无需在 Pictor 配置。
• 画图模型：在工作台「设置」里配置（seedream / gemini / openai-compatible / mock）。密钥经 dsh 凭据子系统保存，配置只留引用。

开发与验证

npm run build         # esbuild 构建 host + 拼接 client
npm run verify        # L1 单元 + L2 host 集成（mock ctx，15 项）
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 第 7 节。

目录

pictor/
├── agents/                # 声明式蓝图（orchestrator/extractor/advisor/renderer）
├── references/domain/     # base-prompt + layouts/ + styles/ + diagram-types/ + visual-principles
├── src/host/              # 插件宿主：~/.pictor、项目会话、/pictor RPC、生图
├── src/client/            # 工作台 UI（React.createElement + 主题变量）
├── e2e/                   # L4a Playwright
├── verify.mjs             # L1+L2 离线冒烟
└── scripts/               # build + transport-smoke

数据目录 ~/.pictor/：index.json（项目索引）、pictor-config.json（画图模型配置）、<项目 id>/（自包含：agents/references 快照 + 10.input + 11.extraction + 12.advice + output）。

文档

• 设计与决策：docs/DESIGN.zh.md
• 验证清单：docs/verification-checklist.zh.md

许可证

MIT，见 LICENSE。第三方内容声明见 NOTICE.md。