dsh-formatforge
Verified@tianbuyu-wwx/dsh-formatforge · v3.0.0 · MIT · Web UI
FormatForge for DeepSeek Harness: forge any file format (pdf/docx/xlsx/pptx/eml/toml/...) into AI-readable structured data. v3.0.0: 收件箱升级为 SQLite 索引库（元数据/全文检索 trigram/内容去重/会话溯源）+ 宿主右侧栏面板（搜索、预览、重转）+ 只读 API/SSE；顺带修好 ff_result 字段错配。v2.0.2: 拖拽文件夹不再卡死。协议仍为 v1。
Install
dsh plugin add @tianbuyu-wwx/dsh-formatforge Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
@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 任一） |
链接
- 仓库 / 完整文档：https://github.com/Tianbuyu-wwx/DSH-FormatForge
- 适配说明（DSH 0.2.0-rc.2）：ADAPTATION_PLAN.md
- 更新日志：https://github.com/Tianbuyu-wwx/DSH-FormatForge/blob/main/CHANGELOG.md
License
MIT