前言¶
在 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 工具链上，减少「只看日志、不见版式」的来回。
