前言¶

在 DeepSeek Harness（DSH）里改 .pptx，常见路径是：右侧只读预览看一眼，回到对话里用自然语言描述「第几页、哪个标题、改什么」。Agent 要先猜你指的是哪一块形状，改错再开一轮，成本主要在「描述位置」而不是改内容本身。

DSH 内置 Office 预览会把 .pptx 转成 PDF 渲染，能看、不能对单个元素说话。社区插件 dsh-pptx-annotate（维护者 HiddenPuppy，分类为客户端）把同一类文件预览改成可点击批注的工作台：点元素写意见，一键生成结构化清单投进当前会话，Agent 按页码与元素编号逐条改，文件变更后预览自动刷新。

这是什么¶

dsh-pptx-annotate 是标准 DSH bundle：Host 提供形状树与幻灯片 PNG 接口，Client 注册 documentPreviews（pptx，priority: 'extension'），默认接管 .pptx；工具栏下拉仍可切回内置 PDF 预览。

一句话：在 DSH 预览面板里逐元素批注 PPT，一键把整轮修改意见交给 Agent。

• 仓库：HiddenPuppy/dsh-pptx-annotate
• 社区目录：skillhub.cn 插件页
• 许可证：MIT（README 与 package.json 一致）
• 包版本：0.1.0；README 标明依赖 DSH 0.2.1-rc.* 的内部 slot 契约

社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系；安装前请自行阅读源码与许可证。插件以当前 DSH 进程权限运行 Host 侧路由与子进程渲染。

和内置预览的差别¶

关键差异不在功能清单长度，而是 位置由点击决定，提交给 Agent 的是「第 X 页 · #N · 元素文案 · 修改意见」，而不是一段散文。

核心功能¶

可视化批注与结构化提交¶

1. 在右侧预览点击任意形状 → 高亮并编号。
2. 输入修改意见（例如「标题太大，缩到 40pt」）。
3. 点击「发送给 Agent」→ 生成带处理约定的清单，投入当前会话；输入框旁显示「N 条批注处理中…」。
4. Agent 按约定逐条改文件，每条用一行 ✅ 第 X 页 · 元素：改了什么 回报。
5. Host 通过 GET /api/pptx-annotate/version 感知文件变化，PNG URL 带 &v=<mtime>，预览自动更新。

提交消息示例（README 原文结构）：

【PPT 批注】`deck.pptx` · 共 3 条

- 第 2 页 · #3 · 三个工具，三种完全不同的结局：标题太大，缩到 40pt
- 第 3 页 · #8 · 表格：换成三列卡片
- 第 1 页 · #6 · 2026.10 · 内部技术分享：字号太小

处理约定（按这个顺序做，不要扩大范围）：
1. 先改后说。单点小改直接动手，不要先给方案、不要长篇分析；改完再汇报。
2. 只改批注点到的元素，其他元素一律不动。
3. 每改完一条，立刻用一行 ✅ 第 X 页 · 元素：改了什么 回报。
4. 汇报之后另起一段，给 1–3 条「可选优化建议」，标明是建议、尚未执行。

Host / Client 分工¶

Host（lib/index.js）提供鉴权路由：

• GET /api/pptx-annotate/deck — 形状树 → 每页元素盒（归一化 0..1）
• GET /api/pptx-annotate/slide — 该页 PNG（LibreOffice Kit 渲染，按文件版本缓存）
• GET /api/pptx-annotate/version — 仅 stat，用于判断 Agent 是否改完

Client（lib/client.js）挂到 sidebar.right.tab.document 与 conversation.composer.dock。几何在 Host 计算，浏览器只接收页码、盒与文字；命中规则为文字优先、面积最小优先，避免点标题时选中背后装饰框。

依赖与实现约束¶

• 不打包额外 npm 依赖：Client 手写 window.__ModuleLoader__.load({ factory })，仅 require("react")；Host 使用 node:zlib / node:child_process。
• PPTX 解析为纯 JS：src/zip.js、src/xml.js、src/pptx-geom.js；渲染走 src/render.js 调用捆绑的 LibreOffice Kit。

安装与启用¶

插件是一条 Loader 行同时加载 Host 与 Client。README 给出的两种方式如下（路径需换成你本机上的绝对路径）：

# 方式一：dsh 自带的插件安装命令（会写入 profile 的 bundles）
dsh plugin --profile web add /absolute/path/to/dsh-pptx-annotate

桌面版 desktop profile 若 CLI 无法管理，可手工 link：

cd ~/.dsh/profiles/desktop
ln -sfn /absolute/path/to/dsh-pptx-annotate node_modules/dsh-pptx-annotate
# 再把 "dsh-pptx-annotate": "link:/absolute/path/to/dsh-pptx-annotate"
# 加进 dependencies，并把包名加进 dsh.profile.bundles

改完 package.json 需重启应用；之后只改 lib/client.js 会热替换，改 lib/index.js 需触发一次 profile 重组（例如保存 cordis.patch.yml）。

卸载：从 dsh.profile.bundles 移除包名、删除软链即可，内置预览不受影响。

典型用法¶

一次批注闭环可概括为：

① 右侧预览里点元素          → 元素高亮 + 编号
② 输入意见                  → 「标题太大，缩到 40pt」
③ 点「发送给 Agent」        → 结构化条目进入当前会话
④ Agent 逐条改              → 每条一行 ✅ 回报
⑤ 文件变更被轮询到          → 预览换图，进度提示消失

仓库提供测试命令，用于验证解析与 UI 流：

npm test     # 35 个单元 + 集成用例（node:test）
npm run smoke  # 真实 client bundle 的浏览器端到端，900px / 500px 两个宽度

更细的设计说明见仓库内 docs/intro.zh.md。

适用场景与注意¶

适合谁

• 经常在 DSH 里让 Agent 改 .pptx、又厌倦「用文字指位置」的开发者或内容协作者。
• 需要在一轮对话里提交多条、可定位的幻灯片修改意见，并希望预览随文件自动刷新。

已知限制（README 原文）

• 只接管 .pptx；.ppt / .docx 仍走内置预览。
• 首次打开约 10 秒（LibreOffice 冷启动），同文件之后毫秒级。
• 批注发送后清空，不落盘（避免过期意见残留）。
• 文本溢出文本框时，热区可能略小于视觉范围。
• 进度提示以文件变化为结束信号；若只提问不改稿，约 10 分钟超时。
• 依赖 DSH 0.2.1-rc.* slot；大版本升级可能需要同步改插件。

Roadmap 包括批注持久化、逐条接受/忽略、.docx 段落级批注、用会话 turn 替代文件轮询等，均以仓库 Issue / README 为准。

结尾¶

dsh-pptx-annotate 把 DSH 对 .pptx 的只读预览扩展成「点选 → 批注 → 结构化交付 Agent → 自动回看」的闭环，减少位置歧义，把修改能力接进可视化界面。

• 社区目录：https://www.skillhub.cn/plugins/HiddenPuppy/dsh-pptx-annotate
• 源码与完整说明：https://github.com/HiddenPuppy/dsh-pptx-annotate
• 相关讨论：deepseek-ai/deepseek-harness#11564