@tianbuyu-wwx/dsh-formatforge
把任意文件拖进 DeepSeek Harness，立刻变成 AI 能读懂的数据。
这是 DSH-FormatForge 的 DSH 插件壳：
一个薄 bundle，把本地 Python 内核（python -m formatforge）包装成宿主原生工具。
支持 PDF、DOCX、XLSX、PPTX、EML、EPUB、TOML 等 30+ 种格式。
⚠️ 本包不含解析器。 它是壳，还需要一份可运行的 Python 内核，见下方「安装」。
兼容性
| |
|---|
| DSH | >=0.2.0-rc.1 <0.3.0-0（peerDependencies 会被宿主 evaluatePluginCompatibility() 检查） |
| Node | >=22.13.0 |
| Python | >=3.10（内核需要） |
| 协议 | protocol/v1（工具签名与返回 JSON 向后兼容） |
安装
# 1) 装插件壳
dsh plugin --profile desktop add @tianbuyu-wwx/dsh-formatforge
# 2) 准备 Python 内核（本包不自带）
git clone https://github.com/Tianbuyu-wwx/DSH-FormatForge.git
cd DSH-FormatForge && pip install -e .
setx FF_REPO_ROOT "D:\DSH-FormatForge"
# 3) 重启 DeepSeek Harness —— 0.2.0 起 add ≠ 激活
启动日志出现这一行即生效：
[dsh-formatforge v2.0.0] tools registered: ff_translate, ff_formats, ff_result, ff_batch, ff_diff
工具
| 工具 | 用途 |
|---|
ff_translate | 转换：path / paths（逗号分隔，支持 * **）/ text 三选一；format json·markdown·html·text；max_chars/offset 分页；quality 附质量报告 |
ff_formats | 列出支持的输入格式矩阵（可按 category 过滤） |
ff_result | 取回收件箱产物（list / id / ids 批量） |
ff_batch | 批量锻造目录或 glob（并发 workers、失败不中断） |
ff_diff | 两份文件 unified diff（合同/法规/版本对照） |
使用方式
- 拖拽：把非图片文件拖进窗口 → 自动上传锻造 → 收件箱产出
<名字>.ff.md（可读）+ <名字>.ff.json（完整协议），并向会话注入一条轻量通知。图片与文件夹一律放行：图片走宿主原生附件通道，文件夹由宿主自己变成 @路径 引用——插件不接管（v2.0.2 起，拖文件夹不再卡死）。拖动期间右上角常驻 × 退出拖拽，遮罩右上角也有 ×，按 Esc 等效：点一下就能清掉卡住的遮罩并复位宿主状态，不必刷新页面；× / Esc 之后这一段拖拽整体交回宿主（松手不会再被接管），下一次拖拽照常锻造。
- 右侧栏面板（v3.0.0）：宿主右侧栏的 FormatForge 页签（或侧栏底部按钮 / 内置 guide 页卡片进入）——搜索产物（中文子串可用）、看正文预览与元数据、复制路径、重新锻造、从列表移除；每页条数偏好持久化。面板是增强项：宿主插槽契约变化时只记日志，拖拽与工具不受影响。
- 收件箱索引库（v3.0.0）：
<DSH_HOME>/formatforge/index.db（SQLite）存元数据 + 全文索引 + 偏好；.ff.md/.ff.json 仍是真相源，删库可用 python -m formatforge inbox reindex 重建。工具侧可用 ff_result {search:"…"} / {stats:true} / {list:true, limit:20}。
- 路径：在对话里给本地路径，agent 会先
ff_translate 再回答。
- CLI：
python -m formatforge translate doc.pdf --format markdown（stdout 单行协议 JSON，退出码 0/2/3/4）；索引库另见 python -m formatforge inbox --help。
enhance 协议
插件不带任何 AI 客户端。纯规则转换不足以产出高质量结果时返回：
"enhance": { "needed": true, "reason": "image_only", "hint": "4/4 页无文字层（疑似扫描件）…" }
此时由当前会话模型按 hint 自行完成增强，零密钥配置。
配置
| 变量 | 默认 | 说明 |
|---|
FF_REPO_ROOT | 自动探测 | 含 formatforge/ core/ parsers/ 的仓库根 |
FF_PYTHON | 探测链兜底 PATH | 指定解释器（探测顺序 FF_PYTHON → <repo>/.venv-fg → PATH） |
FF_MAX_BYTES | 104857600 | 单文件上限（100MB） |
FF_TIMEOUT_S | 120 | 单次转换超时（秒） |
FF_INBOX_NOTIFY | true | 锻造完成后是否向会话注入轻量通知 |
FF_HOME | $DSH_HOME/formatforge → ~/.dsh/formatforge | 收件箱根目录 |
OCR_ENABLED | true | 启用本地 OCR（tesseract/paddleocr/easyocr 任一） |
链接
License
MIT
