v1.0.1 — Hotfix（description + argparse JSON 化）🔧

v1.0.1 — Hotfix（description + argparse JSON 化）🔧

发布日期：2026-08-31 · npm @tianbuyu-wwx/dsh-formatforge@1.0.1 (latest) · 测试 569 passed / 0 fail
主题：v1.0.0 发布后实测发现的小问题 + argparse UX 改进。

修复内容

1. description 字符串修正（npm 搜索结果一致性）

v1.0.0 npm 包 description 字段仍含 'v0.14.0' 字符串（被遗漏），影响 npm 搜索结果显示的版本号。

修法：description 字符串 v0.14.0 → v1.0.0。

2. argparse 错误 JSON 化（v0.14.1 候选 #1）

之前 argparse 错误（未知子命令、无效参数值）走 stderr + exit 2 —— 破坏"stdout 是唯一协议出口"约定。

dsh 调用方需要 redirect stderr 才能区分"协议输出"和"argparse 错误"，体验差。

修法：main() 在 parser.parse_args() 时临时替换 sys.stderr 为 _SilentStream（不写入），让 argparse usage 静默；SystemExit 时走 _fail("internal", ...) 输出协议 JSON 到 stdout。

实测：

• formatforge nonexistent → stdout JSON {ok:false, error.kind:internal}, stderr 静默, exit 70 ✓
• formatforge formats --category bad → stdout JSON, stderr 静默, exit 70 ✓
• formatforge --help → stdout 正常 usage, exit 0 ✓（不触发 error 路径）

3. 测试修正

• 新增 TestArgparseJsonOutput（2 测试）
• 修 test_category_invalid：旧断言依赖 argparse stderr 文本输出

升级

npm install @tianbuyu-wwx/dsh-formatforge@latest

API 完全向后兼容（无破坏性改动）。

测试

• 569 passed / 0 fail（v1.0.0 567 → v1.0.1 569，+2）
• ruff ✓ / format ✓ / mypy ✓
• CI 7/7 全绿

文件变更

• packages/dsh-formatforge/package.json（description 修正）
• formatforge/__main__.py（argparse JSON 化）
• test/unit/test_cli_protocol.py（新增 2 测试 + 修 1 测试）

---

完整变更见 CHANGELOG.md。

v1.0.0 — 首个 production-ready stable 🚀

v1.0.0 — 首个 production-ready stable 🚀

发布日期：2026-08-31 · npm @tianbuyu-wwx/dsh-formatforge@1.0.0 (latest) · 测试 567 passed / 0 fail
主题：v1.0 production-ready 里程碑——v0.14.0 stable 代码 + 协议冻结 + 5 项 audit 修复。

⚠️ 关于 v0.14.0

npm 上的 v0.14.0 缺 audit 修复（4 bug + 1 性能），已在 npm 上 deprecate 提示升级 v1.0.0。

升级指南

npm install @tianbuyu-wwx/dsh-formatforge@latest
# 或
npm update @tianbuyu-wwx/dsh-formatforge

API 完全向后兼容（v1.x 内不变更），无破坏性改动。

v1.0.0 增量（5 项 audit 修复）

1. Bug：translate.mjs 多文件分页用 inline 旧逻辑（v0.13.0 遗留）

文件：packages/dsh-formatforge/tools/translate.mjs line 152-160

• 之前 lastIndexOf('\n\n', windowEnd) 没保护 --- 边界
• 改法：用 _truncate.mjs::smartTruncate 替代 inline 截断

2. Bug：多文件分隔符 --- 与 markdown 水平线冲突

• translate 多文件拼接改用 <!-- ff-file-sep -->（HTML 注释）
• 之前 --- 第 1 页 --- 水平线被 smartTruncate 误识别为多文件分隔符
• 实测：cap=40/70 时单文件内容被切断到 --- 第 1 页 --- 之前
• HTML 注释：markdown 不解析、对模型可读

3. Bug：smartTruncate JS / Python 算法不一致（6 case 不一致）

• 修法：sep_len 跟踪避免 nxt 算法漂移
• Python 与 JS 现在完全对齐 13/13

4. Bug：--against-dir 触发 self-diff

文件：formatforge/diff.py::cmd_diff_against_dir

• 之前 glob(stem) 会匹配 new.txt 自身 → path_a=path_b → 假 negative
• 修法：candidates 加 if p != path_b and p.exists() 排除自身

5. 性能优化：inbox-watcher retention sha256 全量读

文件：packages/dsh-formatforge/services/inbox-watcher.mjs

• 之前 readFileSync(full).slice(0, 65536) 全量读 + slice
• 改法：openSync + readSync(64KB) + closeSync

包含 v0.14.0 stable 全部

见 v0.14.0 Release Notes（窗 B 7 项 P0+P1 + 窗 C 协议快照 + 死代码清理）。

测试

• 567 passed / 0 fail（基线 538 → 567，+29）
• 跨语言 truncate 一致性：13/13
• ruff ✓ / format ✓ / mypy ✓

文件变更（+128 / -61）

• core/utils.py（+27 / -13）
• formatforge/diff.py（+7 / -3）
• packages/dsh-formatforge/services/inbox-watcher.mjs（+14 / -4）
• packages/dsh-formatforge/test/test-truncate-consistency.mjs（+21 / -6）
• packages/dsh-formatforge/tools/_truncate.mjs（+30 / -27）
• packages/dsh-formatforge/tools/translate.mjs（+10 / -8）
• test/unit/test_cli_protocol.py（+18 / -0）

生产可用性

• ✅ 协议冻结（v1.x 内向后兼容）
• ✅ npm latest = 1.0.0
• ✅ CI 7/7 全绿（Python 3.10/3.11/3.12 × pytest、Node 22 × syntax、security scan、CLI e2e）
• ✅ 跨语言一致性测试（Python ↔ JS byte-equal）

下一步

• v0.14.1 / v1.0.1 hotfix：修复 description 字符串 + 7 项 UX 已知问题（argparse JSON 输出、retention Plan B、扩展名 fallback 等）
• v1.1：性能优化（parallel batch、streaming upload）
• v2.0：协议 v2（breaking changes）

---

完整变更见 CHANGELOG.md。

v0.14.0 — 窗 B 全收口（v1.0 stable 前最后一站）

v0.14.0 — 窗 B 全收口（v1.0 stable 前最后一站）

⚠️ 已被 v1.0.0 取代（npm deprecated）。请升级到 v1.0.0 stable（含 audit 修复）。

发布日期：2026-08-31 · npm @tianbuyu-wwx/dsh-formatforge@0.14.0 (deprecated) · 测试 566 passed / 0 fail
主题：完成 v0.14.0 计划全部 7 项（2 项 P0 + 5 项 P1）。v1.0 stable 直接复用此代码 + 窗 C 协议冻结。

⚠️ 重要：v1.0.0 已发布

v1.0.0 是首个 production-ready stable，包含 v0.14.0 stable 全部 + 5 项 audit 修复（4 bug + 1 性能）。

npm 上 v0.14.0 已 deprecate，请升级：

npm install @tianbuyu-wwx/dsh-formatforge@latest

API 完全向后兼容，无破坏性改动。

v0.14.0 内容（被 v1.0.0 包含）

2 项 P0（v0.14.0-rc.1 已发布）

1. ff_formats 能力元数据 — 新增 data.details[] 含 capabilities（pdf 有 [furniture_strip, ocr, table, two_column] 等）
2. ff_diff 增量模式 — --against-dir DIR 与 --since-mtime VAL 新增；_resolve_paths 容错

5 项 P1

1. retention 通知降噪 — 清理事件只 log 不广播
2. TTL 删除前 .ff.retired.log — sha256 + path + size + mtime + timestamp 写入
3. 质量评分动态权重 — 按 file_type 加权（纯文本 table_accuracy 归零等）
4. OCR enhance 漏判 — confidence < 0.5 OR ocr_confidence < 0.6 时 hint
5. markdown --- 分段保护 — 多文件分隔符不切断（v1.0.0 升级到 <!-- ff-file-sep --> HTML 注释）

窗 C 协议冻结

新增 packages/dsh-formatforge/protocol/v1/：6 个 schema snapshot + README，v1.x 内向后兼容。

测试基线

• v0.14.0: 566 passed（基线 538 → 566，+28）
• 跨语言 truncate 一致性：11/11（v1.0.0 升级到 13/13）
• ruff ✓ / format ✓ / mypy ✓

---

查看 v1.0.0 release notes

v0.14.0-rc.1 — 第二批 P0 RC 候选

v0.14.0-rc.1 — 第二批 P0 RC 候选

发布日期：2026-09-02 · 测试 555 passed / 0 fail
主题：会话模型发现能力（ff_formats capabilities）+ diff 增量模式（--against-dir / --since-mtime）

⚠️ Pre-release：本 RC 仅含 v0.14.0 计划的 2 项 P0，5 项 P1 下个工作窗继续。完整 v0.14.0 stable 才上 npm。当前不进 latest dist-tag，避免污染正式版引用。

✨ 新增

• ff_formats 能力元数据：每个 format 自带 capabilities 列表，让会话模型按能力选 format
  • 数据来源：自动扫描 parsers/*.py 类真实方法名，不依赖静态字典——自动反映代码真实能力
  • 新模块 core/format_capabilities.py
• ff_diff 增量模式：新增 --against-dir <dir> + --since-mtime <ts> 两个参数
• 新单测 17 项（B-P0-1 11 项 + B-P0-2 6 项）

🔄 变更

• CLI 顺序：formatforge diff 改 path_b path_a（argparse 限制）
• _resolve_paths 容错旧顺序
• 抽出 _compute_diff 共享函数（单文件模式 + 增量模式）

实测 capability 映射

format	capabilities
pdf	[furniture_strip, ocr, table, two_column]
pptx	[animation_order, speaker_notes, table]
epub	[chapter_split]
xlsx	[multi_sheet]
odt/ods/odp	[table]

🧪 验证

• 538 → 555 passed（+17）
• ruff ✓ / format ✓（55 files） / mypy ✓（49 files 0 issues）
• CI 7/7 全绿（run ID 33650351465）
• Node 4 测全过（test-local / test-inbox / test-manifest / test-truncate-consistency）

📦 Install

npm install @tianbuyu-wwx/dsh-formatforge@0.14.0-rc.1

或通过 npx @deepseek-ai/dsh plugin add 安装（注意：RC 版需显式 tag）。

---

完整变更见 CHANGELOG.md。下个工作窗继续 P1 五项（retention 降噪 / TTL 预览 / 动态权重 / OCR 漏判 / markdown 分段优先），然后发 v0.14.0 stable。

v0.13.0 — 封口批（v1.0 前 P0/P1 修复）

v0.13.0 — 封口批（v1.0 前 P0/P1 修复）

发布日期：2026-08-31 · npm @tianbuyu-wwx/dsh-formatforge@0.13.0 · 测试 538 passed / 0 fail
主题：清理 v0.10–v0.12 累积的协议不一致 + 文档漂移，为 v1.0 协议冻结做准备

✨ 新增

• tools/_truncate.mjs 共用模块：renderTruncate + smartTruncate，供 translate.mjs / result.mjs 共用
• batch 透传 --quality / --encoding / --language：与 ff_translate 对齐；批量产出的 markdown 现在带 enhance 提示
• 回归测试 test_builds_result_when_decision_noop：覆盖 conversion_needed=False 走 BuildResultStep 不崩
• SKILL.md frontmatter 同步：补 version: 0.13.0 + updated: 2026-08-31
• ConversionDecision.strategies 字段语义澄清：标明是「候选列表」而非「已执行」
• 跨语言一致性测试 test-truncate-consistency.mjs：JS ↔ Python smartTruncate 9/9 一致，未来漂移自动捕获

🔄 变更

• A1 多文件分页字段 meta.next_offset → paging.next_offset（与单文件路径统一）
• A3 cmd_translate_main 返回签名 (content, meta) → (content, meta, enhance | None)
• B1 ff_diff 复用 validateLocalFile 做 size clamp
• B2 KNOWN_EXT 移除 .doc（同步 inbox-watcher + batch）
• C1 render 截断走 renderTruncate（段落/行边界优先）
• C6 id 匹配删除 includes 兜底（防 id="abc" 误命中 xxxabcxxx.ff.json）

🐛 修复

• 测试健壮性：TestR11XlsxSchema / TestR11DocxRevisions / TestR11PptxAnimations 加 pytest.importorskip——venv 漂移从 fail-成-ERROR 降级为 skip
• dev.py hotfix：scripts/dev.py step_ruff() 不收 quick 参数的循环调用 bug 修

🧪 验证

• 537 → 538 passed（+1：B3 回归测试）
• ruff ✓ · format ✓（54 files） · mypy ✓（48 files 0 issues） · bandit 0 High
• Node test-local.mjs / test-inbox.mjs / test-manifest.mjs / test-truncate-consistency.mjs 全过
• scripts/dev.py --publish --no-mypy 全套通过 + npm publish 成功

📦 Install

npm install @tianbuyu-wwx/dsh-formatforge@0.13.0
# 或
npx @deepseek-ai/dsh plugin add --profile web @tianbuyu-wwx/dsh-formatforge

---

完整变更见 CHANGELOG.md。下一步工作窗 B：ff_formats 能力元数据 + ff_diff 增量模式。