前言¶
在 DeepSeek Harness（DSH）里让模型「生成一个二维码」，往往不止导出一张图。同一串 URL 用数字模式还是字节模式、纠错选 L 还是 H、版本 1 还是版本 40，会直接决定能不能放下、印出来多大才扫得动。若工具只提供「生成」而没有「先算清楚」，失败后再猜原因会浪费多轮对话。
下面介绍社区插件 dsh-tool-qrcode（维护者 yuehancn，分类：模型推理）。它在 DSH 中提供四个工具：先规划符号容量，再用内置编码器零依赖出 SVG；可选配置外部程序出 PNG 或读码。插件在 GitHub 上标注与 dsh 0.2.0-rc.2（preview）构建测试；apply(ctx) 规范相对稳定，若你使用更新版本需自行核对兼容性。
这是什么¶
dsh-tool-qrcode 是面向 DeepSeek Harness 的自建工具插件：内置从零实现的 QR 编码器，不安装额外依赖即可生成 SVG；同时把「能不能放下、用什么模式、纠错等级、余量多少」拆成独立的规划工具，与出图步骤分开。
- 仓库：yuehancn/dsh-tool-qrcode
- 社区目录页：SkillHub 插件页
- 许可证：MIT（package.json 版本 1.0.0）
DSH 生态理念是「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
插件暴露四个工具，长任务前可先查环境，再规划，再出图或读码。
qrcode_status¶
汇报当前能力：内置 SVG 编码器始终可用；并说明是否配置了外部编码器（用于 PNG 等）和解码器（用于读码）。避免等到调用失败才发现未安装 qrencode 等。
qrcode_plan(text, level?)¶
只算不画。返回自动判定的编码模式（numeric / alphanumeric / byte / kanji）、能放下的最小版本、纠错等级、容量余量，以及放不下时的补救建议。模式选择会显著影响体积（例如 README 举例：纯数字 36 位可塞进版本 1，同样内容按字节模式只能塞 17 位）。
qrcode_make(text, level?, …)¶
出图，默认 SVG，使用内置编码器，零外部依赖。
| 参数 | 说明 |
|---|---|
level |
l / m / q / h，默认 l；放不下会自动降级并在 notes 中说明 |
outputName |
文件名，默认按内容生成 |
scale |
每模块像素，默认 8 |
quietZone |
静区模块数，默认 4（标准要求，不宜改小） |
lightColor / darkColor |
前后景色，默认 #ffffff / #000000 |
margin |
是否留白 |
需要 PNG/JPEG 须配置外部编码器；未配置时插件会明确报错并说明如何配置，而不是静默返回改名的 SVG。
qrcode_read(path, format?)¶
将二维码图片读回文本，需配置解码器（如 zbarimg、zxing）。失败时会列出可能原因（静区被裁、图太小或模糊、颜色反相等），便于模型在看不到图的情况下调整参数。
设计要点：qrcode_plan 是独立工具，不是 qrcode_make 的参数——「能不能放下、印多大」属于决策，生成属于执行。
安装与启用¶
支持的 profile：desktop（桌面版）、web（Web 版）。安装后重启 dsh。
dsh plugin --profile desktop add github:yuehancn/dsh-tool-qrcode
Web 版将 --profile desktop 换成 --profile web 即可。
可选配置写在 ~/.dsh/profiles/<profile>/cordis.patch.yml 中，例如：
- id: tool-qrcode
config:
outputDir: C:/Users/you/Pictures/qrcode-output
encodeCommand: qrencode # 可选：要出 PNG 才需要
encodeArgs: ["-o", "{output}", "-t", "PNG", "-l", "{level}", "{text}"]
decodeCommand: zbarimg # 可选：要读码才需要
decodeArgs: ["--raw", "-q", "{input}"]
常用配置字段（其余见仓库 README）：
| 字段 | 默认 | 说明 |
|---|---|---|
outputDir |
qrcode-output |
产物目录 |
encodeCommand |
"" |
外部编码器，空则仅 SVG |
decodeCommand |
"" |
外部解码器，空则 qrcode_read 不可用 |
scale |
8 |
默认每模块像素 |
quietZone |
4 |
默认静区模块数 |
timeoutMs |
60000 |
单次调用超时 |
status/plan/make/read |
true |
可按需关闭单个工具 |
encodeCommand 可写成解释器加脚本（如 node + 脚本路径）；qrcode_status 会穿透解释器探测脚本能力。
典型用法¶
README 中的调用关系可概括为两步：先规划，再生成。
qrcode_plan(text="https://...") → byte 模式 / 版本 3 / 纠错 L / 还剩 12 bit 余量
qrcode_make(text="https://...") → 29×29 的 SVG，无外部依赖
在 DSH 对话中，让模型先调用 qrcode_status 确认环境，对长 URL 或中文 payload 先 qrcode_plan，再按需要的 level、scale 调用 qrcode_make。读已有图片时配置好 decodeCommand 后使用 qrcode_read。
适用场景与注意¶
适合谁：需要在智能体工作流里稳定产出可扫描二维码的开发者；希望模型在出图前就知道版本与纠错是否合适；默认只要 SVG、不想为编码单独装系统工具的场景。
运行与安全（来自 README）：
- 外部命令仅通过
spawn(command, argsArray)调用，不拼接 shell 字符串。 - 内置编码器不出网；SVG 为纯文本写盘；覆盖已存在产物会被拒绝（除非文件名不冲突）。
- 插件以当前 dsh 进程权限运行；安装前请自行查看源码与 MIT 许可证，确认外部编解码命令路径与参数符合你的环境策略。
实现与质量：编码遵循 ISO/IEC 18004；仓库提供 Node 测试套件（README 称 268 条断言）及 Python 独立校验脚本 _test/verify-qr.py，可与 OpenCV、qrcode 库对照。
结尾¶
dsh-tool-qrcode 把 QR 的容量规划与 SVG 生成拆开，内置编码器保证零依赖出图，可选外部工具扩展 PNG 与读码。若你在 DSH 里频繁处理链接、Wi-Fi 口令或短文本入码，可先装插件、用 qrcode_plan 看清约束再 qrcode_make 出图。
- 目录页：https://www.skillhub.cn/plugins/yuehancn/dsh-tool-qrcode
- GitHub：https://github.com/yuehancn/dsh-tool-qrcode
