前言¶

在 DeepSeek Harness（DSH）里，带视觉能力的模型可以直接处理附件图片；但若主对话用的是纯文本模型（例如 deepseek-v4-pro），智能体往往只能拿到磁盘上的图片路径，既看不见图，也无法按统一规范把「图里有什么」写进上下文。即便有人用视觉模型先转写一版文字，转写质量也没有固定契约：读者很难区分哪些是图上真实观察到的，哪些是模型补全或臆测。

竞赛物理题扫描图里常见与任何构件都不相连的墨点。人眼会当成扫描噪声；纯文本模型读不到原图时，可能把几像素污点当成质点或铰链，进而整题受力分析失真。README 中举过 CPhO 相关例子：题面会写明「当作扫描噪声，不要当作质点」——这类信息正是看不见图的模型最需要、也最容易漏掉的。read-figure 针对的是这条更窄的链路：把图交给视觉模型，按固定三段式协议产出可引用、可质疑、可审计的纯文本交接件，而不是替做题模型直接解题。

这是什么¶

read-figure 是 Amethyst-Leafs 维护的 DSH 插件（npm 包名 read-figure，当前版本 0.1.0，MIT 许可证）。它只向宿主贡献一个工具：read_figure。调用方传入本地图片路径后，插件请求配置好的视觉模型，按仓库内协议文件 prompts/figure-handoff.zh.md 生成识图交接件，并以纯文本形式返回上下文；物理解答仍由纯文本模型完成，交接件本身不含解答。

协议正文是独立的 Markdown 文件，而非散落在代码里的字符串；README 写明协议本身占插件价值的主要部分，HTTP 封装只是配套实现。社区目录页见 SkillHub，源码与文档见 GitHub。

核心功能¶

工具 read_figure¶

• 首轮识图：传入单张或多张图的本地路径，以及可选标签（如题号），得到完整三段式交接件。
• 定向追问：当交接件第三节列出不确定项时，不必整图重跑；可用 question 只问某一细节，视觉模型需结合位置与观测到的形状/像素量级作答，若两种读法都合理需并列说明及对物理图景的影响。
• 零安装试跑：CLI 与插件共用代码路径，可在不挂载插件的情况下先验证协议效果。

固定三段式输出¶

交接件标题与章节结构由协议固定，大致包括：

1. 图的结构：构件、标注、几何与坐标系等，要求具体、避免含糊表述。
2. 复述：一段物理情境，以及已知量、求解量、图中未给出条件的列表。
3. 读图置信度声明：区分高置信与不确定项；对噪声、污点等须写清位置、像素量级、判断理由，并附带 guard 句（例如明确告知纯文本模型勿因孤立墨点虚构质点或铰链）。

协议还附带「给纯文本模型的执行说明」，例如：勿用常识补全图中未给出的信息；结论若依赖「不确定」项须中止并说明；优先符号化求解等。仓库 examples/ 目录提供 2026-10-17 实际运行的样例（路径已脱敏），展示整图交接与定向追问两种模式。

设计原则（来自 README）¶

• 只转写、不解题：视觉模型一旦开始算题，交接件就不再是可审计的观察记录。
• 不确定项必须显式列出并带防护句：只写「此处有个污点」而不说明「视为噪声、勿加质点」时，纯文本模型更容易当真。
• 误报比漏报更危险：机械检测到的候选须经过误报抑制规则再交给 LLM。

安装与启用¶

推荐通过插件管理器安装 bundle，无需手改 profile 栈（安装命令以 README 为准）：

plugin_manager install_bundle  https://github.com/Amethyst-Leafs/dsh-read-figure
plugin_manager install_bundle  ./path/to/read-figure        # 本地目录，用于开发

install_bundle 会对 profile 执行 pnpm add，并根据包内 cordis.patch.yml 追加 bundle 行。安装完成后需要重启 DSH：宿主插件在进程启动时挂载，read_figure 仅在重启后出现。

也可在 profile 的 cordis.patch.yml 中手动增加一行，例如：

- id: read-figure
  name: read-figure
  config:
    model: deepseek-flash
    apiKey: sk-…            # 见下文「凭证」

不安装插件时，可用 CLI 直接生成交接件：

node bin/read-figure.mjs --img figures/1.jpg --img figures/2.jpg --out out/handoff.md

（需在克隆或解压后的仓库目录中执行；本文不涉及 git clone 步骤。）

配置说明¶

凭证：已在运行的 DSH 进程读不到之后才 export 的环境变量。若环境变量不生效，请将 apiKey 直接写入 cordis.patch.yml 对应行。

运行环境要求 Node.js >=20.0.0（见 package.json 的 engines）。

典型用法¶

首轮识图（单图）：

{ "imagePath": "output/…/figures/1.jpg", "label": "第 1 题" }

多图：

{"imagePaths": ["figures/1.jpg", "figures/2.jpg"], "label": "第 1、2 题"}

对交接件中某条「不确定」做定向追问（勿整图重跑）：

{
  "imagePath": "figures/1.jpg",
  "question": "The longest rope hanging from B's left side — does it end at m₂ or m₃? What difference would each reading make?"
}

自定义协议时，可修改 promptFile 指向自己的 Markdown，或用 extraInstruction 在每次调用末尾追加说明。

适用场景与注意¶

适合谁：在 DSH 里以纯文本模型为主力、又需要稳定、可审计地把扫描题图、示意图交给上下文的工作流；尤其是物理竞赛类图中噪声与标注易引发误读的场景。也适合在挂载插件前，用 CLI 和 examples/ 对照协议是否满足团队规范。

权限与安全：插件以当前 DSH 进程权限运行，会读取你传入的本地图片路径并向外网（或你配置的 baseUrl）发起视觉 API 请求。安装前应自行审阅源码与 MIT 许可证，妥善保管 apiKey，勿将密钥提交到版本库。

生态说明：DSH 采用「一切皆插件」的扩展方式；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

read-figure 不替模型解题，而是把「图里有什么」收敛成固定三段式、带置信度与防护句的交接件，让纯文本模型在可引用、可挑战的前提下继续推导。若你要在 Harness 里接这条链路，可从目录页了解收录信息，在 GitHub 查看完整 README、prompts/figure-handoff.zh.md 与 examples/ 样例，并按上文 plugin_manager install_bundle 安装后重启 DSH 启用 read_figure。

• 目录页：https://www.skillhub.cn/plugins/Amethyst-Leafs/dsh-read-figure
• 仓库：https://github.com/Amethyst-Leafs/dsh-read-figure