publish: 1.2.0

Author: x3zvawq

.github/workflows/publish.yml

@@ -1,22 +1,24 @@
-name: CI
+name: Publish
 
 on:
     push:
         branches: [main]
 
+permissions:
+    contents: read
+    id-token: write
+
 jobs:
     publish:
         runs-on: ubuntu-latest
 
         steps:
             - uses: actions/checkout@v4
-            - name: Use Node.js 20.x
+            - name: Use Node.js 24.x
               uses: actions/setup-node@v4
               with:
-                  node-version: 20.x
+                  node-version: 24.x
+                  registry-url: https://registry.npmjs.org
             - run: npm ci
             - run: npm run build
-            - uses: JS-DevTools/npm-publish@v3
-              with:
-                  access: public
-                  token: ${{ secrets.NPM_TOKEN }}
+            - run: npm publish --access public

AGENTS.md

@@ -1,36 +1,75 @@
 # paddleocr.js agent guide
 
-这个仓库是一个轻量 TypeScript PaddleOCR runtime，目标是在不引入大型运行时依赖的前提下，尽量贴合官方 PaddleOCR / PaddleX 的 ONNX 推理链路、模型 preset、模块能力和 examples 展示。
+这个仓库是一个轻量 TypeScript PaddleOCR / PaddleX ONNX runtime。目标是在不引入大型运行时依赖的前提下，尽量贴合官方 PaddleOCR / PaddleX 的预处理、后处理、模型 preset、模块能力、组合流水线和 examples 展示。
 
 ## 参考文档
 
-1. [docs/official-parity-roadmap.md](./docs/official-parity-roadmap.md)
-    - 当前已支持模块、官方证据、关键差异和下一步优先级都在这里。
-2. [assets/README.md](./assets/README.md)
-    - 本地 ONNX 资产来源、大文件放置规则、`assets/local/` 下载/转换说明。
-3. [examples/README.md](./examples/README.md)
-    - examples 的设计口径：像用户项目嵌入本库，而不是内部 CLI。
+1. [README.md](./README.md) / [README_zh.md](./README_zh.md)
+    - 用户入口、API 口径、模型加载边界、支持能力和官方实现差异说明。
+2. [examples/README.md](./examples/README.md) / [examples/README_zh.md](./examples/README_zh.md)
+    - examples 的设计口径、输入图片、结果图、模块示例和流水线示例。
+3. [paddleocr-js-onnx/README.md](./paddleocr-js-onnx/README.md) / [paddleocr-js-onnx/README_zh.md](./paddleocr-js-onnx/README_zh.md)
+    - Hugging Face 模型仓说明、官方 ONNX 链接、转换资产下载位置和 examples 目录约定。
 
-## 当前项目概况
+## 当前项目结构
 
-- Runtime 入口在 `src/`，按模块拆成 `processor/`、`presets/`、`utils/`。
-- 调用方负责传入像素，runtime 不解码 PNG/JPEG，不应新增图像 codec、大型 OpenCV、pyclipper 等运行时依赖。
-- 开发期脚本和验证用依赖可以放在 `tmp/` 或 examples 侧，但不能变成 runtime dependency。
-- 已真实可跑的主链路包括 PP-OCRv5 mobile、PP-OCRv6 tiny/small 的 det + rec。
-- 已有本地验证资产包括分类模块、seal detection、SLANet、UVDoc、PP-DocBlockLayout、RT-DETR table cell，以及本地转换后的 PP-FormulaNet_plus-M。
-- 大模型或转换后资产应放在忽略的 `assets/local/`，或后续发布到 Hugging Face；不要直接提交大二进制。
+- `src/core/`
+    - 轻量图像、输入像素、ONNX metadata、轮廓和 Clipper-style offset 工具。
+- `src/types/`
+    - 运行时、模块和流水线的公共类型定义。
+- `src/modules/`
+    - 单模块 service、preset、preprocess、postprocess。
+    - 当前包括 `text-detection`、`text-recognition`、`image-classification`、`object-detection`、`text-image-unwarping`、`table-structure`、`formula-recognition`。
+- `src/pipelines/`
+    - 高层组合流水线。
+    - 当前包括 `PaddleOcrService`、`TableRecognitionV2Service`、`PaddleStructureService`。
+- `examples/`
+    - 面向用户接入的模块与流水线示例。`input/` 放共享样例图，`result/` 放发布展示效果图。
+- `paddleocr-js-onnx/`
+    - Hugging Face 模型仓的说明文件和上传 ignore 规则。源码仓只跟踪 README、`.gitignore`、`.gitattributes`，不提交 ONNX 二进制。
+
+## 当前能力范围
+
+- OCR 主链路：PP-OCRv5 mobile、PP-OCRv6 tiny/small 的 det + textline orientation + rec。
+- 文本检测：DBPostProcess、quad/poly 输出、seal detection preset、轻量 polygon unclip。
+- 文本识别：CTC decode、字典校验、batch max width ratio、固定输入宽度、阅读顺序排序和低置信过滤。
+- 分类模块：文档方向、文本行方向、表格分类。
+- 目标检测模块：PP-DocBlockLayout、PP-DocLayout、RT-DETR wired/wireless table cell 的导出框解析、NMS、merge/unclip。
+- 文本图像矫正：UVDoc preprocess、raw service 和 DocTr 风格输出解码。
+- 表格结构：SLANet / SLANeXt preset、结构 token 解码、cell bbox restore、HTML-like 输出和 OCR-to-cell 文本填入。
+- 公式识别：PP-FormulaNet S/L、plus-S/M/L preset，UniMERNet 风格 preprocess，Nougat tokenizer id/logit decode。
+- 流水线：OCR、Table Recognition V2、类 PP-Structure 文档解析、reading order 和 markdown/table/formula 区域输出。
 
 ## 重要设计边界
 
-- 优先同步真实影响输出的逻辑：resize、normalize、channel order、DBPostProcess、CTC decode、排序、裁剪、unclip、NMS、table/formula/layout 后处理。
-- 轻量原则优先：如果官方依赖 pyclipper/OpenCV 的步骤需要近似实现，必须在文档中标明差异，不要伪装成 bit-exact parity。
-- 新 preset 应尽量从官方 `inference.yml` / `inference.json` / ONNX metadata 推导，不要凭相似模型猜默认值。
-- examples 应展示用户如何加载 ONNX、字典/label、选择 preset/模块服务、传入自有像素、处理输出对象。
-- README 和 examples 输出图应展示识别前后效果；生成 PNG 可以用开发期依赖，不要加入 runtime。
+- 调用方负责传入图片像素。runtime 不解码 PNG/JPEG/PDF 页面，也不应新增图像 codec、大型 OpenCV、pyclipper 等运行时依赖。
+- 模型文件由调用方加载为 `ArrayBuffer` 后传入。runtime 不读取固定模型目录，也不自动下载模型。
+- OCR 字典、分类 label、公式 tokenizer 等文本资产由调用方加载并显式传入。
+- 开发期脚本和验证依赖可以放在 examples 或 `tmp/`，但不能变成 runtime dependency。
+- 新 preset 优先从官方 `inference.yml`、`inference.json`、ONNX metadata 或已验证模型导出信息推导，不凭相似模型猜默认值。
+- 后处理遇到未知 tensor layout、缺失字典、输出 shape 不匹配时优先 fail-fast，不用模糊 fallback 掩盖设计问题。
+- 官方依赖 OpenCV / pyclipper 的步骤只要求轻量高层等价。不能把 TypeScript 近似实现说成 bit-exact parity。
+- 真实影响输出的逻辑优先同步：resize、normalize、channel order、DBPostProcess、CTC decode、排序、裁剪、unclip、NMS、table/formula/layout 后处理。
+
+## Examples 口径
+
+- examples 要像用户项目接入本库：加载 ONNX、加载字典/label/tokenizer、选择 preset 或 service、传入调用方像素、处理返回对象。
+- examples 可以使用 `fast-png` 读取样例图片；这只是 examples 依赖，不代表 runtime 会解码图片。
+- examples 通过 `PADDLEOCR_JS_ONNX_DIR` 查找外部模型目录，这是 examples 的运行约定，不是 runtime 约束。
+- 新增或调整模块时，优先补对应 `examples/module/*/run.ts`；新增组合能力时补 `examples/pipeline/*/run.ts`。
+- `examples/result/*.png` 是用户展示图，不是测试 golden snapshot。更新结果图时用 `bun examples/generate-results.ts`，必要时用 `--only` 或 `EXAMPLE_ONLY` 局部生成。
+
+## 模型资产规则
+
+- 源码仓和 npm 包不提交 ONNX 大文件。
+- 官方已发布 ONNX 的模型，README 中链接到 PaddlePaddle 官方 Hugging Face 仓库，避免重复上传。
+- 官方没有可用 ONNX 的转换资产放在独立 Hugging Face 仓 `paddleocr-js-onnx`。
+- 父仓库只跟踪 `paddleocr-js-onnx/README*`、`.gitignore`、`.gitattributes`；不要把模型二进制加进父仓库。
+- 本地验证模型可以放在被忽略的 `paddleocr-js-onnx/` 或 `assets/local/`，但不要作为 runtime dependency。
 
-## 提交习惯
+## 验证命令
 
-- 每完成一个独立点单独提交。
-- commit message 使用一行中文 conventional commit，例如：
-    - `fix(detection): 贴合印章弧形轮廓`
-- 不要 stage 或回滚用户已有的无关改动。
+- 常规文档或示例小改：至少运行 `npm run lint`。
+- 影响 runtime、preset、preprocess、postprocess 或流水线：运行 `npm run lint`、`npm run build`、`npm test`。
+- 影响 examples 结果展示：运行对应示例或 `bun examples/generate-results.ts --only <task>`，必要时重新生成 `examples/result/*.png`。
+- 当前测试入口是 `npm test`，使用 Bun test；不要继续使用已移除的旧 `test:node` 脚本。

README.md

@@ -47,7 +47,8 @@ Model binaries are not included in this source repository or the npm package.
 
 Download official ONNX models from PaddlePaddle's Hugging Face repositories when
 they exist. When official ONNX assets are not available, use the converted and
-locally verified assets from [`paddleocr-js-onnx`](./paddleocr-js-onnx/README.md).
+locally verified assets from
+[`x3zvawq/paddleocr-js-onnx`](https://huggingface.co/x3zvawq/paddleocr-js-onnx).
 
 The runtime does not read from a fixed model directory. Your application only
 needs to load ONNX models as `ArrayBuffer`s, load OCR dictionaries, labels, or

README_zh.md

@@ -45,7 +45,9 @@ Node.js、Bun 和浏览器中。
 源码仓库和 npm 包都不包含模型二进制。
 
 官方已经发布 ONNX 的模型，优先去 PaddlePaddle 的 Hugging Face 仓库下载；官方没有可用
-ONNX 的模型，可以从 [`paddleocr-js-onnx`](./paddleocr-js-onnx/README_zh.md) 下载本项目转换和验证过的版本。
+ONNX 的模型，可以从
+[`x3zvawq/paddleocr-js-onnx`](https://huggingface.co/x3zvawq/paddleocr-js-onnx)
+下载本项目转换和验证过的版本。
 
 runtime 不读取固定模型目录。你的应用只需要把 ONNX 模型读成 `ArrayBuffer`，把 OCR 字典、
 label 或公式 tokenizer 读成对应的数据结构，再传给 service 或模块 API。