前言¶

在 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