前言¶
在 DeepSeek Harness（DSH）裏讓 Agent 改 Typst，常見短板是：編譯報錯只有終端式輸出，模型很難對齊 file:line；版式問題又離不開「看見頁面再改」。純聊天裏反覆 typst compile、貼日誌，往往效率低、上下文也容易丟。
下面介紹維護者 Vncntvx 的客戶端插件 dsh-typst。它在帶右側停靠欄的 DSH Web 界面裏掛上 Typst 面板，用你本機安裝的 Typst 做 typst watch 式增量預覽；同時爲 Agent 提供檢查、看圖、指位置和導出 PDF 的工具，與倉庫 README 描述的工作流一致。
這是什麼¶
dsh-typst 是 DeepSeek Harness 的 Typst 插件（分類：客戶端）。版本 0.1.0，許可證 MIT。
預覽與終端裏 typst compile 對齊：由本機 Typst 驅動（你的字體、已下載的包、你的 Typst 版本）。文檔保存後（人工或 Agent 觸發保存），預覽增量重編譯、原地重繪，不閃爍、滾動位置保持。Agent 可讀取帶 file:line、源碼行、hint: 與調用鏈的診斷；可把渲染頁當圖分析；可在預覽裏標註位置；可導出 PDF；你在預覽中選中文字時，可把內容連同對應源碼位置一併交給 Agent。
插件自身不編輯 .typ 源文件；除 typst_export_pdf 向工作區寫入 PDF 外，不寫工作區。預覽 PDF 與渲染圖在私有緩存目錄 ~/.dsh/cache/typst。插件本體不聯網；Typst 首次使用 @preview 包時的下載行爲與終端一致。
前置條件¶
安裝包已含編譯產物，無需自行構建。README 與 package.json 對運行環境的要求如下：
- Node.js：README 要求 24+；
package.json的engines.node爲^22.19.0 || >=24.0.0。 - DeepSeek Harness：
package.json要求dsh >= 0.2.2-rc.1；界面需支持右側停靠欄。 - 本機 Typst：0.12 或更高。示例安裝方式：
# macOS
brew install typst
# Windows
winget install --id Typst.Typst
# 或通過 Cargo
cargo install --locked typst-cli
也可從 Typst releases 獲取二進制。
插件按順序查找 typst 可執行文件：插件設置中的路徑 → PATH → 常見安裝位置（Homebrew、Cargo、~/.local/bin、Nix、Snap、WinGet、Scoop）→ 登錄 shell（mise/asdf 等）。若裝在非標準路徑，在插件設置 Typst 路徑 填寫完整路徑。
核心功能¶
右側面板¶
從右側欄「+」菜單或引導頁打開 Typst 面板後，可獲得：
- 實時預覽：對主文件經
typst watch增量重編譯；縮放（適寬、適頁、百分比）、頁碼框。 - 主文件：可搜索、輸入相對路徑或包含隱藏目錄的索引；切換會重新編譯，選擇按工作區記憶。
- 狀態與問題：編譯階段、耗時、診斷數量；失敗時保留上次成功預覽；底部問題區可篩選、打開源碼並審閱修復請求。
- 文字與區域反饋：選中文字可追加到主輸入框；框選可截取真實頁面圖片，支持多頁區域與失敗重試。
- Agent 標註：位置請求可導航；展示引文與備註。
- 安裝引導：展示檢測事實與平臺相關命令；安裝請求需先審閱再提交。
Agent 工具與技能¶
倉庫 README 列出 7 個工具及配套技能 typst（教模型完整工作流：先 typst_status，編輯後 typst_check，佈局問題用 typst_render_pages 看圖，用 typst_show 指給用戶）：
| 工具 | 用途 |
|---|---|
typst_status |
Typst 版本與路徑、主文件、其餘 .typ、最近一次編譯結果 |
typst_set_main |
選擇主 .typ（按工作區記憶） |
typst_check |
等待已保存改動編譯完成，回報錯誤與警告（位置、源碼行、hint、調用鏈） |
typst_render_pages |
將至多 4 頁渲染爲 PNG 供 Agent 查看版式 |
typst_show |
查看預覽某頁，或高亮文本/源碼行 |
typst_clear_highlights |
移除 Agent 高亮 |
typst_export_pdf |
編譯 PDF 寫入工作區（可選 PDF 標準、頁選擇） |
權限與邊界：插件以工作區爲工作目錄運行你的 typst，與在終端手動執行一致。
安裝與啓用¶
DSH 生態按「一切皆插件」擴展；社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。該插件目錄頁給出的安裝指引是：在 Harness 中安裝 Vncntvx/dsh-typst（頁面文案爲「請安裝 DSH 插件 Vncntvx/dsh-typst」）。具體安裝步驟以你當前 Harness 版本的插件管理界面或 Agent 讀插件說明爲準；本文不拼接未在資料中出現的 dsh plugin add … 命令。
安裝並啓用後，建議先確認面板裏的安裝引導能檢測到 Typst，再在插件設置中必要時指定 Typst 路徑。安裝插件前，宜自行審閱 GitHub 源碼 與 MIT 許可證：插件以當前 dsh 進程權限在本機執行 typst。
典型用法¶
README 中的對話示例可直接復現：
- 「用 Typst 起一篇雙欄論文，帶標題塊和摘要。」
- 「修復我論文裏的錯誤，然後告訴我改了什麼。」
- 「第 3 頁的表格溢出了——讓它排進去。」
- 「把
paper.pdf導出成 PDF/A-2b。」
適用場景與注意¶
適合：已在 DSH 中用 Agent 編寫或修復 Typst 文檔；需要右側實時預覽、結構化診斷、按頁看圖改版式、工作區內導出 PDF。
注意：
- 必須具備本機 Typst 0.12+ 與符合要求的 Node、DSH 版本。
- 插件不代你改
.typ，修復仍由 Agent 在編輯器中完成（或你手動改）後保存觸發預覽。 - 緩存與導出路徑行爲見上文「權限、隱私與網絡」；敏感項目請先確認工作區邊界。
結尾¶
dsh-typst 把 Typst 排版放進 DSH 右側欄，並把編譯狀態、頁面圖像、預覽標註和 PDF 導出接到 Agent 工具鏈上，減少「只看日誌、不見版式」的來回。
