@h-ai/tools 0.0.0-stage → 1.0.0-beta.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +202 -0
  2. package/README.en.md +37 -0
  3. package/README.ja.md +37 -0
  4. package/README.md +36 -2
  5. package/dist/chunk-UA7MOYTT.js +413 -0
  6. package/dist/chunk-UA7MOYTT.js.map +1 -0
  7. package/dist/index.d.ts +16 -0
  8. package/dist/index.js +3 -0
  9. package/dist/index.js.map +1 -0
  10. package/dist/server/index.d.ts +306 -0
  11. package/dist/server/index.js +1051 -0
  12. package/dist/server/index.js.map +1 -0
  13. package/dist/tools-types-CM0lGuJr.d.ts +199 -0
  14. package/jobs/.dockerignore +4 -0
  15. package/jobs/README.md +223 -0
  16. package/jobs/archives.py +56 -0
  17. package/jobs/browser/Dockerfile +20 -0
  18. package/jobs/browser/operation.py +17 -0
  19. package/jobs/browser/render.mjs +90 -0
  20. package/jobs/browser_policy.py +36 -0
  21. package/jobs/documents/Dockerfile +23 -0
  22. package/jobs/documents/generate.py +165 -0
  23. package/jobs/documents/operation.py +84 -0
  24. package/jobs/documents/requirements.txt +3 -0
  25. package/jobs/hyperframes-runtime.mjs +73 -0
  26. package/jobs/media_files.py +78 -0
  27. package/jobs/ocr/Dockerfile +19 -0
  28. package/jobs/ocr/operation.py +18 -0
  29. package/jobs/office/Dockerfile +21 -0
  30. package/jobs/office/office_job.py +65 -0
  31. package/jobs/office/operation.py +43 -0
  32. package/jobs/preview_build/Dockerfile +19 -0
  33. package/jobs/preview_build/build.mjs +552 -0
  34. package/jobs/preview_build/operation.py +62 -0
  35. package/jobs/preview_build/package.json +11 -0
  36. package/jobs/tests/image-smoke.mjs +83 -0
  37. package/jobs/tests/requirements.txt +4 -0
  38. package/jobs/tests/test_documents_generate.py +107 -0
  39. package/jobs/tests/test_hai_tool.py +82 -0
  40. package/jobs/tests/test_media_jobs.py +449 -0
  41. package/jobs/tests/test_preview_build.py +213 -0
  42. package/jobs/tool.py +145 -0
  43. package/jobs/video_render/Dockerfile +20 -0
  44. package/jobs/video_render/operation.py +109 -0
  45. package/jobs/video_render/render.mjs +36 -0
  46. package/jobs/web_capture/Dockerfile +20 -0
  47. package/jobs/web_capture/capture.mjs +122 -0
  48. package/jobs/web_capture/operation.py +65 -0
  49. package/package.json +62 -3
package/jobs/README.md ADDED
@@ -0,0 +1,223 @@
1
+ # 独立文档、Office、网页与视频工具
2
+
3
+ 这些镜像使用同一个 JSON 协议。工具以非 root 用户执行一次请求,由部署方选择镜像并分配资源。文档、Office 和 OCR 支持通过受管 MCP 作业调用,应用也可直接提交这些作业。网页与视频镜像提供独立作业协议;上层需要登记实际操作及权限后才能开放给用户。远程导航与采集需先验收下文的代理和出网限制。
4
+
5
+ | 镜像 | 操作 | 输入与输出 |
6
+ | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
7
+ | `documents` | `documents.extract` | TXT、Markdown、CSV、TSV、文本 PDF、DOCX、XLSX → 文本。XLSX 读已有单元格值与缓存,公式重算使用 Office |
8
+ | `documents` | `documents.generate` | 有界 JSON 标题、段落、表格或幻灯片 → 真实 DOCX、XLSX、PPTX;表格文字保持字符串,不执行公式 |
9
+ | `office` | `office.convert` | DOCX、ODT、XLSX、ODS、PPTX、ODP → PDF |
10
+ | `office` | `office.recalculate` | XLSX、ODS → 同格式文件。LibreOffice 重新计算公式 |
11
+ | `ocr` | `ocr.recognize` | PNG、JPEG、TIFF → 文本。可选 `language` 为 `eng`、`chi_sim`、`jpn`、`eng+chi_sim` 或 `eng+jpn` |
12
+ | `browser` | `browser.navigate` | 访问受控代理允许的 HTTPS 地址,输出 1280 × 720 PNG。关闭 JavaScript、下载和 Service Worker |
13
+ | `preview_build` | `preview.build` | 受支持的本地 HTML/JS/TS/CSS/Svelte 项目 ZIP → 自包含 HTML;离线固定工具链,不执行项目脚本或安装依赖 |
14
+ | `web_capture` | `web.capture` | HTTPS 网页 → 包含来源、正文、截图、品牌颜色与实际素材的 ZIP;固定 HyperFrames 0.9.56,支持动态页面 |
15
+ | `video_render` | `video.render` | 自包含 HTML 动画项目 ZIP → H.264 MP4;固定 HyperFrames 0.9.56,离线逐帧渲染并用 FFprobe 校验 |
16
+
17
+ ## 快速开始
18
+
19
+ 在仓库根目录构建,选择需要的镜像。发布时应为每种镜像独立版本化,并在执行环境中登记产物 digest。
20
+
21
+ ```sh
22
+ # 输入 documents 的 Dockerfile 与共用构建目录,输出可由 Podman 启动的本地镜像。
23
+ podman build -f packages/tools/jobs/documents/Dockerfile -t localhost/hai-tools-documents:local packages/tools/jobs
24
+ ```
25
+
26
+ 入口 `/usr/local/bin/hai-tool` 从标准输入读取一个 UTF-8 JSON 对象,在 EOF 后运行。每次请求最多 64 KiB。文件名最多 128 个 ASCII 字符,可用字母、数字、点、下划线和连字符,首字符必须是字母或数字。挂载独立的 `/input` 只读目录和空的 `/output` 目录,UID 1000 必须能够读取输入及写入输出。输入单文件和产物上限 50 MiB,抽取文本上限 256 KiB,文本 PDF 上限 100 页。
27
+
28
+ 文本结果形如 `{"success":true,"data":{"text":"..."}}`。产物结果形如 `{"success":true,"data":{"artifact":{"name":"report.pdf","bytes":1234}}}`。业务失败返回 `success: false` 和稳定的 `error.code`;调用方须检查结果和实际产物。每个进程只处理一个请求,成功后回收工作环境。
29
+
30
+ ## 功能
31
+
32
+ ### 提取文档文字
33
+
34
+ 使用 `documents` 镜像读取 `/input/report.pdf`,文件中已有的文本通过标准输出返回。例如包含单行 `Release checklist` 的文本 PDF 会得到 `data.text` 中的 `Release checklist`。扫描图像交给 OCR。
35
+
36
+ ```json
37
+ { "operation": "documents.extract", "input": "report.pdf" }
38
+ ```
39
+
40
+ ### 生成可编辑的 Office 文档
41
+
42
+ 使用 `documents` 镜像。部署侧把已授权的 UTF-8 JSON 文件放入 `/input/source.json`,输入不超过 256 KiB。下面的内容可分别生成带标题、段落和表格的 DOCX、XLSX 或单页 PPTX;选择输出扩展名决定格式。
43
+
44
+ ```json
45
+ {
46
+ "title": "工具平台说明",
47
+ "paragraphs": ["工具定义、受管执行与可复用产物。"],
48
+ "table": {
49
+ "headers": ["模块", "用途"],
50
+ "rows": [["Tools", "验证与授权"], ["Runner", "隔离执行"]]
51
+ }
52
+ }
53
+ ```
54
+
55
+ ```json
56
+ { "operation": "documents.generate", "input": "source.json", "output": "report.docx" }
57
+ ```
58
+
59
+ 将 `output` 改为 `report.xlsx` 或 `report.pptx` 可生成相应文件,成功返回实际 `data.artifact`。XLSX 固定使用 `Report` 工作表,标题、段落和表格依次写入;所有用户文字显式设为字符串,包括以 `=`、`+` 或 `@` 开头的内容。
60
+
61
+ 标题最多 200 字符,段落可省略或最多 100 项、每项 2000 字符;表格必须提供 1~20 个 `headers`,`rows` 可省略或最多 200 行,每行列数与表头一致,单元格最多 2000 字符。输入拒绝未知字段、重复 JSON 字段和 XML 不支持的控制字符。
62
+
63
+ 多页 PPTX 使用 `slides`,每页提供 `title` 和可选的 `paragraphs`、`table`。提供 `slides` 时,顶层只保留文档 `title` 与 `slides`,不要再传顶层段落或表格。最多 20 页;每页标题最多 100 字符,正文最多 6 段、每段 160 字符、合计 800 字符。带表格的页最多 6 列、6 行数据,单元格最多 32 字符,并最多附一段 120 字符的说明,避免生成无法阅读的拥挤页面。
64
+
65
+ ```json
66
+ {
67
+ "title": "工具平台",
68
+ "slides": [
69
+ { "title": "一个入口", "paragraphs": ["直接业务和 AI 复用同一工具。"] },
70
+ { "title": "受管执行", "paragraphs": ["Runner 负责容量、隔离与取消。"] }
71
+ ]
72
+ }
73
+ ```
74
+
75
+ 镜像复用 Debian 的 DOCX、XLSX 和 XML/图像支持库,PPTX 使用固定的 `python-pptx` 1.0.2;额外 wheel 及其 SHA-256 在 [requirements.txt](documents/requirements.txt) 维护,构建时校验并安装,运行时不下载依赖。
76
+
77
+ ### 转换 Office 文档与重算公式
78
+
79
+ 使用 `office` 镜像。第一个请求读入 `/input/report.docx`,成功写出 `/output/report.pdf`,返回 `data.artifact.name` 和实际字节数。第二个请求读入 `/input/budget.xlsx`,成功写出 `/output/calculated.xlsx`,重新计算公式缓存并返回同样的产物元数据。两次请求各自启动一个容器。
80
+
81
+ ```json
82
+ { "operation": "office.convert", "input": "report.docx", "output": "report.pdf" }
83
+ ```
84
+
85
+ ```json
86
+ { "operation": "office.recalculate", "input": "budget.xlsx", "output": "calculated.xlsx" }
87
+ ```
88
+
89
+ ### 识别扫描图像
90
+
91
+ 使用 `ocr` 镜像。此例识别 `/input/label.png` 中的英文和简体中文,成功返回 `data.text`,如 `Warehouse 仓库`。`language` 省略时使用 `eng`,支持的组合见上表。图像由部署侧按文件授权提供。
92
+
93
+ ```json
94
+ { "operation": "ocr.recognize", "input": "label.png", "language": "eng+chi_sim" }
95
+ ```
96
+
97
+ ### 从受控网站生成截图
98
+
99
+ 使用 `browser` 镜像。代理允许访问示例地址且页面返回成功时,生成 `/output/page.png`,返回 `data.artifact.name: "page.png"` 和字节数。截图固定为 1280 × 720,应用在交付产物前复核归属。
100
+
101
+ ```json
102
+ { "operation": "browser.navigate", "url": "https://example.com/", "output": "page.png" }
103
+ ```
104
+
105
+ ### 构建多文件网页预览
106
+
107
+ 使用可选 `preview_build` 镜像,在 Runner 登记 `preview.build` 能力及 `networkPolicy: offline`,再将环境 ID 传入 `tools.createJobTools` 的 `environments.preview`。Agent 的对应工具名为 `preview_build`,属于 `web` 组;只构建本地项目不需要出网代理。构建方式与其他镜像相同,将 Dockerfile 路径改为 `packages/tools/jobs/preview_build/Dockerfile`。
108
+
109
+ ```json
110
+ { "operation": "preview.build", "input": "project.zip", "output": "preview.html" }
111
+ ```
112
+
113
+ ZIP 根目录必须有 `index.html`,允许一个模块入口及其本地 JS/TS/JSX/TSX/JSON、CSS 和 Svelte 浏览器组件。例如 HTML 使用 `<div id="app"></div><script type="module" src="/src/main.ts"></script>`,入口通过固定 `svelte` 运行时的 `mount` 加载本地 `App.svelte`。站点根引用映射到 ZIP 根,不能访问宿主路径。CSS 导入、图片/字体/音视频、本地组件静态 `src/poster` 会内联;动态组件资源先 import,再作为属性使用。组件 `srcset` 等不支持的资源形式明确失败,不发布缺少素材的预览。
114
+
115
+ 固定版本为 esbuild 0.28.2、Svelte 5.57.3、parse5 8.1.0、acorn 8.19.0,使用镜像内的 lockfile 安装并核验。用户项目的 package.json、Vite/Svelte/TypeScript 配置可存在,但一律不执行或采纳;不安装用户依赖,不支持 SvelteKit、任意 npm 裸导入、运行期动态 import 或远程构建素材。`import.meta.env` 只提供固定的生产字段,不支持 `import.meta.url`。归档不要包含 node_modules、Git、环境或凭据点文件。
116
+
117
+ 预览项目展开合计最多 8 MiB,单源码与最终 HTML 各最多 1 MiB,沿用最多 256 个安全归档条目的限制;编译最多 60 秒。建议从 CPU 1 核、内存 512 MiB、PID 128、临时盘 128 MiB 开始实测。成功返回真实 HTML 产物,应用发布为 `kind: html`、`mediaType: text/html`,直接交现有隔离工作台显示。作业结束即销毁构建容器;没有常驻开发服务器或预览网关。修改源码后重新构建得到新产物,构建失败不会发布旧输出;关闭预览卸载 iframe。
118
+
119
+ ### 采集网页正文与制作素材
120
+
121
+ 使用 `web_capture` 镜像。部署代理必须先允许访问目标网站和需要的素材来源。此请求生成 `/output/capture.zip`;其中 `capture.json` 记录原始 `sourceUrl`、标题、正文 `text`、颜色、截图和素材相对路径。成功响应的 `data.summary` 同时返回这些内容,调用方可以直接将来源文本交给后续文案和分镜工具。`capture-status.json` 记录实际 HTTP 状态、缺失素材数量及警告,其他目录保留捕获到的文件。网页正文为空、HTTP 请求失败或没有截图时不发布成功产物。
122
+
123
+ ```json
124
+ { "operation": "web.capture", "url": "https://example.com/", "output": "capture.zip", "maxScreenshots": 4 }
125
+ ```
126
+
127
+ `maxScreenshots` 省略时为 4,支持 1~8 个主截图;HyperFrames 还可能生成素材联系表。协议不接受请求级代理、凭据或命令。素材可能因源站限制而缺失,上层应读取状态文件后再决定是否能够完成视频。
128
+
129
+ 打包时仅排除 HyperFrames 自动生成的根 `AGENTS.md`、`CLAUDE.md`、`.cursorrules` 助手指令文件;网页正文、截图、素材和素材缺失报告保留。其他未知点文件仍按原有归档规则拒绝,不会作为素材静默丢弃。
130
+
131
+ ### 渲染真实 HTML 动画视频
132
+
133
+ 使用 `video_render` 镜像。输入 `/input/project.zip` 必须在根目录包含 `index.html`,并携带所引用的本地脚本、图片、字体和音频。根合成元素必须声明 `data-composition-id`、`data-duration`、`data-width`、`data-height`;`data-start` 省略或为 0。项目声明时长大于 0 且不超过 30 秒,宽高为 16~1920 的偶数,总像素不超过 1920 × 1080,支持等像素量的竖屏。静态资源引用必须位于项目内,远程脚本、图片与字体应在采集或准备阶段本地化。
134
+
135
+ ```json
136
+ { "operation": "video.render", "input": "project.zip", "output": "intro.mp4", "fps": 30 }
137
+ ```
138
+
139
+ `fps` 省略时为 30,支持 24、25、30。成功后写出 `/output/intro.mp4`,返回实际文件名和字节数。工具调用固定版本 HyperFrames 渲染时间轴,再核验 H.264 视频流、尺寸及实际时长与项目声明一致;不把项目校验通过或任务已启动当作视频生成成功。
140
+
141
+ 项目 ZIP 最多 256 项、解包后合计 100 MiB、单文件 50 MiB;拒绝路径逃逸、符号链接、特殊文件、重复路径和加密条目。容器无外网,不能依靠在项目中安装依赖或动态下载媒体完成渲染。脚本、分镜、语音合成和字幕编排由上层复用 LLM 与 Audio;渲染器只消费已准备的项目。
142
+
143
+ ## 配置
144
+
145
+ 部署时将文件工具连接到无网络的独立作业容器,使用只读根文件系统、受限临时目录、PID/CPU/内存上限。LibreOffice 使用每次新建的 profile,以 UNO 设置禁用宏执行和链接更新,且拒绝包含外部关系、嵌入对象、宏及超限 ZIP 的输入。需要访问外部资源的文档应事先在受控流程中移除这些引用。[LibreOffice 宏执行模式](https://api.libreoffice.org/docs/idl/ref/namespacecom_1_1sun_1_1star_1_1document_1_1MacroExecMode.html) · [文档更新模式](https://api.libreoffice.org/docs/idl/ref/namespacecom_1_1sun_1_1star_1_1document_1_1UpdateDocMode.html)
146
+
147
+ 应用可将文档、Office、OCR 环境登记到 Runner,再在 `mcp.servers` 用 `transport: job` 绑定环境和工具白名单。任务只传授权文件 ID,执行节点通过 `mcpJobFiles` 复核权限后读入对象和暂存产物。Runner 用独立的工具容量领取作业,服务的 `pool.maxRunning` 控制所有执行节点上的并发上限。应用按产物所有者验证下载权限。配置示例见 [MCP 配置](../../../docs/usage/configuration/ai.md#mcp和a2a)。
148
+
149
+ 部署配置可设置 `pool.minReady` 和 `pool.maxTotal`。预热实例为空容器,每次只交给一个作业,完成后销毁。工具实例准备、领取和销毁期间持续占用资源额度。
150
+
151
+ 浏览器镜像要求部署提供 `HAI_TOOL_BROWSER_PROXY=http://<代理的 IPv4 地址>:<端口>`。作业网络必须只允许连接该代理的地址和端口。代理逐个校验 CONNECT 目的地,执行任务授权、DNS/IP、内网限制及重定向和子资源策略。镜像启用 Chromium 沙箱,启动失败时由上层报告环境错误。部署未提供这些边界前保持操作停用。[Chromium 代理规则](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md)
152
+
153
+ `browser.navigate` 保持 JavaScript、下载和 Service Worker 禁用,只对 `page.goto` 首行精确返回当前 URL 的 `net::ERR_NETWORK_CHANGED` 重试一次。两次导航共用最多 20 秒预算,整体使用 40 秒单调截止时间,另为截图保留最多 10 秒及关闭时间;Python 外层仍在 45 秒兜底回收。HTTP 403、沙箱失败、其他网络错误及截图失败不重试。失败时删除本次图片并关闭页面和浏览器,不发布旧图,也不公开原始 stderr。
154
+
155
+ `web_capture` 复用相同部署代理校验,并将其传给 HyperFrames 自身的受控采集器;它允许页面 JavaScript,必须使用独立的受限容器,不能放进应用主进程。包装固定传入 `HYPERFRAMES_CHROME_SANDBOX=1`,禁止 HyperFrames 在检测到容器后自动关闭 Chromium sandbox;宿主环境的 `=0` 不能覆盖。Runner 使用非 root UID 1000,部署还须允许该用户创建 Chromium 需要的用户命名空间,并在 seccomp/AppArmor 策略中明确允许必要操作。不能通过增加 `CAP_SYS_ADMIN`、关闭整个安全策略或传入 `--no-sandbox` 让验证通过。环境拒绝 Chromium sandbox 时返回 `SANDBOX_UNAVAILABLE`,操作保持失败且不发布产物。
156
+
157
+ 部分 Podman 默认 seccomp 策略在外层容器移除 `CAP_SYS_CHROOT` 后同时拒绝 `chroot` 系统调用,但 Chromium 的嵌套用户命名空间仍需要该调用。应先用实际启动诊断确认原因;若确为这一条件规则,可从当前默认策略复制,只调整 `chroot` 的规则,保留所有其他规则和内核能力检查,再使用标准 `CONTAINERS_CONF_OVERRIDE` 为专用执行节点进程指定 `[containers] seccomp_profile`。不修改宿主全局策略,不授予额外 capability;实际 Runner 作业也必须通过该配置验收,独立探测容器成功不能代替正式执行成功。
158
+
159
+ 采集只对浏览器已启动、导航阶段明确返回 `net::ERR_NETWORK_CHANGED` 的只读请求重试一次;两次尝试及退避共用 170 秒内部截止时间。HTTP 403、沙箱启动失败和其他错误不重试。每次尝试使用独立临时目录,完整成功后原子发布;`capture-status.json` 的 `retries` 只记录固定阶段、错误码和次数,不包含 URL 或原始 stderr。再次导航失败返回 `NAVIGATION_RETRY_FAILED`,外层不会发布失败尝试残留的内容。
160
+
161
+ `video_render` 使用离线 Runner 环境,其隔离边界是无网络、非 root、只读根文件系统及容器资源限制;不声称所有离线渲染都启用了 Chromium 自身的 sandbox。两者不接收用户指定的程序路径或环境变量;镜像内部校验 HyperFrames 精确版本为 `0.9.56`,关闭自动更新、可选依赖安装和项目 `.env` 读取。生产使用时记录最终镜像 digest,同时固定浏览器、字体与 FFmpeg 的实际版本。
162
+
163
+ 本轮媒体验收采用以下有界起测预算;应在实际站点、画幅和宿主上复测后调整,不能当作所有部署的性能保证:
164
+
165
+ | 环境 | CPU 核 | 内存 MiB | PID | 临时盘 MiB | 网络 |
166
+ | ----------------- | ------ | -------- | ---- | ---------- | -------------------- |
167
+ | web | 1 | 1024 | 512 | 512 | internal,经受控代理 |
168
+ | video | 1 | 1536 | 512 | 6144 | offline |
169
+ | 节点 toolCapacity | 2 | 3072 | 1024 | 8192 | 不适用 |
170
+
171
+ `toolMaxRunning: 1` 可用于先验证串行作业,host 编排使用独立的 default 容量;节点物理预算还须额外覆盖该 host 容量。PID 128 的浏览器起测已出现线程创建失败,不能沿用旧的轻量作业 PID 配额。采集子进程上限 180 秒,渲染子进程上限 300 秒,上层作业期限需要另外留出产物读取与清理时间。这些是工具预算,不会自动修改 Runner 默认配置。
172
+
173
+ HyperFrames `0.9.56` 在渲染前要求临时目录和输出目录各至少有 1024 MiB 可用空间。含输入文件的 Runner 会把 `scratchMiB` 分给 state、workspace、output 和 tmp,tmp 仅占四分之一;因此视频的 6144 MiB 总临时盘给 tmp 1536 MiB,不等于进程已经占用这些内存。不能把总预算 512 MiB 当成可运行的视频配置,也不跳过工具原有磁盘检查;实际内存占用和输出大小仍须在目标视频上验收。
174
+
175
+ ## 错误处理
176
+
177
+ 校验 `success` 后再读 `data.text` 或 `data.artifact`。输入或输出文件名不合规时返回 `INVALID_REQUEST`。浏览器没有可用的部署代理配置时返回 `NETWORK_POLICY_REQUIRED`,工具子进程失败时返回 `TOOL_FAILED`。容器未返回成功时,宿主丢弃本次工作目录及未确认产物。
178
+
179
+ 媒体作业还会返回 `UNSAFE_PROJECT`(归档不安全或超限)、`INVALID_PROJECT`(合成参数或本地资源不符合要求)、`INVALID_OUTPUT`(捕获或渲染结果不完整)、`OUTPUT_LIMIT`(采集素材超限)、`SANDBOX_UNAVAILABLE`(无法启用远程网页所需的 Chromium sandbox)及 `TIMEOUT`。生成文档时缺少库返回 `ENVIRONMENT_UNAVAILABLE`。取消与进程树回收继续由 Runner 负责。
180
+
181
+ ## 开发测试
182
+
183
+ ```sh
184
+ python3 -B -m unittest discover -s packages/tools/jobs/tests
185
+ ```
186
+
187
+ 用已构建的文档和 Office 镜像复测受管工具。测试包含真实的 MCP HTTP 入口、Runner、离线容器以及 PDF 产物提交。
188
+
189
+ ```sh
190
+ HAI_TOOL_IMAGE_DOCUMENTS=localhost/hai-tools-documents:local \
191
+ HAI_TOOL_IMAGE_OFFICE=localhost/hai-tools-office:local \
192
+ pnpm --filter @h-ai/ai exec vitest run tests/ai-mcp-services.test.ts
193
+ ```
194
+
195
+ `HAI_TEST_CONTAINER_ENGINE=docker` 可选择 Docker,缺省使用 Podman。构建环境应先明确准备两种镜像。未设置对应镜像时,Vitest 会跳过其真实容器测试。
196
+
197
+ 在根目录构建各镜像后执行只读、禁网的镜像启动检查。
198
+
199
+ ```sh
200
+ for kind in documents office ocr browser; do
201
+ podman build -f "packages/tools/jobs/$kind/Dockerfile" -t "localhost/hai-tools-$kind:local" packages/tools/jobs || exit 1
202
+ done
203
+ HAI_TOOL_IMAGE_DOCUMENTS=localhost/hai-tools-documents:local \
204
+ HAI_TOOL_IMAGE_OFFICE=localhost/hai-tools-office:local \
205
+ HAI_TOOL_IMAGE_OCR=localhost/hai-tools-ocr:local \
206
+ HAI_TOOL_IMAGE_BROWSER=localhost/hai-tools-browser:local \
207
+ node packages/tools/jobs/tests/image-smoke.mjs
208
+ ```
209
+
210
+ 工具验收需用实际镜像补齐代表性输入、输出内容、离线与网络边界。`office` 还需验证宏、链接和外部数据源不会执行,`browser` 需用受控 HTTPS 站点及代理核对最终截图和拒绝访问的场景。单元测试覆盖请求协议、文件范围与上限、文档链接、OCR 参数和浏览器代理前置条件。
211
+
212
+ 网页与视频镜像按需构建:
213
+
214
+ ```sh
215
+ podman build -f packages/tools/jobs/web_capture/Dockerfile -t localhost/hai-tools-web-capture:local packages/tools/jobs
216
+ podman build -f packages/tools/jobs/video_render/Dockerfile -t localhost/hai-tools-video-render:local packages/tools/jobs
217
+ ```
218
+
219
+ Python 媒体协议测试用替换子进程验证产物发布、权限前置、归档与项目限制,不能替代真实媒体验收。真实验收应核对网页内容、截图、缺失素材报告、可播放视频、实际时长和解码后的运动变化,并验证受控网络、取消与资源回收。
220
+
221
+ ## 许可证
222
+
223
+ Apache-2.0
@@ -0,0 +1,56 @@
1
+ """对 Office ZIP 容器执行解包配额和主动内容筛查。"""
2
+ import pathlib
3
+ import xml.etree.ElementTree as ET
4
+ import zipfile
5
+ from tool import ToolError
6
+
7
+
8
+ class OfficeArchive:
9
+ def __init__(self, path):
10
+ self.archive = zipfile.ZipFile(path)
11
+ try:
12
+ files = self.archive.infolist()
13
+ names = [item.filename for item in files]
14
+ if len(files) > 2048 or len(names) != len(set(names)) or sum(item.file_size for item in files) > 100 * 1024 * 1024:
15
+ raise ToolError('UNSAFE_DOCUMENT', 'Document exceeds the archive limits')
16
+ for item in files:
17
+ name = item.filename.lower()
18
+ parts = pathlib.PurePosixPath(name).parts
19
+ if (name.startswith('/') or '\\' in name or '..' in parts or item.flag_bits & 1
20
+ or 'vbaproject' in name or '/embeddings/' in name or '/activex/' in name
21
+ or '/externallinks/' in name or name.startswith(('basic/', 'scripts/'))):
22
+ raise ToolError('UNSAFE_DOCUMENT', 'Document contains unsupported active content')
23
+ except BaseException:
24
+ self.archive.close()
25
+ raise
26
+
27
+ def __enter__(self):
28
+ return self
29
+
30
+ def __exit__(self, *_):
31
+ self.archive.close()
32
+
33
+ def xml(self, name):
34
+ info = self.archive.getinfo(name)
35
+ if info.file_size > 16 * 1024 * 1024:
36
+ raise ToolError('UNSAFE_DOCUMENT', 'Document XML exceeds the size limit')
37
+ source = self.archive.read(info).decode('utf-8-sig')
38
+ if '<!DOCTYPE' in source or '<!ENTITY' in source or '\x00' in source:
39
+ raise ToolError('UNSAFE_DOCUMENT', 'Document XML must not define entities')
40
+ return ET.fromstring(source)
41
+
42
+ def reject_external_links(self):
43
+ for name in self.archive.namelist():
44
+ if name.endswith('.rels'):
45
+ for link in self.xml(name):
46
+ if link.get('TargetMode', '').lower() == 'external':
47
+ raise ToolError('UNSAFE_DOCUMENT', 'Document references an external resource')
48
+ if name in ('content.xml', 'styles.xml', 'settings.xml'):
49
+ for element in self.xml(name).iter():
50
+ link = element.get('{http://www.w3.org/1999/xlink}href', '')
51
+ if link.startswith(('.', '/', '\\')) or ':' in link:
52
+ raise ToolError('UNSAFE_DOCUMENT', 'Document references an external resource')
53
+
54
+
55
+ def office_archive_error():
56
+ return ToolError('INVALID_INPUT', 'Invalid office document')
@@ -0,0 +1,20 @@
1
+ FROM docker.io/library/node:24.22.1-bookworm-slim@sha256:be8204d4bd327363357f532187b752ff62759c31bedf98e9e18fc08c9cbd605c
2
+ RUN mkdir -p /etc/ssl/certs && node -e "require('node:fs').writeFileSync('/etc/ssl/certs/ca-certificates.crt', require('node:tls').rootCertificates.join('\\n'))"
3
+ ARG DEBIAN_MIRROR=https://deb.debian.org/debian
4
+ ARG DEBIAN_SECURITY_MIRROR=https://deb.debian.org/debian-security
5
+ RUN set -eu; \
6
+ sed -i -e "s|http://deb.debian.org/debian-security|${DEBIAN_SECURITY_MIRROR}|g" -e "s|http://deb.debian.org/debian|${DEBIAN_MIRROR}|g" /etc/apt/sources.list.d/debian.sources; \
7
+ apt-get -o Acquire::Retries=2 -o Acquire::https::Timeout=20 update; \
8
+ apt-get install -y --no-install-recommends python3 chromium fonts-liberation fonts-noto-cjk; \
9
+ rm -rf /var/lib/apt/lists/*
10
+ RUN mkdir -p /opt/hai-tools /input /output && chown 1000:1000 /output
11
+ COPY tool.py /usr/local/bin/hai-tool
12
+ COPY browser_policy.py /opt/hai-tools/browser_policy.py
13
+ COPY browser/operation.py /opt/hai-tools/operation.py
14
+ COPY browser/render.mjs /opt/hai-tools/render.mjs
15
+ RUN npm install --prefix /opt/hai-tools --no-audit --no-fund --ignore-scripts playwright-core@1.65.0
16
+ RUN chmod 0555 /usr/local/bin/hai-tool
17
+ USER 1000:1000
18
+ ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1
19
+ WORKDIR /tmp
20
+ ENTRYPOINT ["/usr/local/bin/hai-tool"]
@@ -0,0 +1,17 @@
1
+ import pathlib
2
+ from tool import ToolError, publish, run_command
3
+ from browser_policy import deployment_proxy, parse_url
4
+
5
+
6
+ def navigate(request, _source, artifact, workspace):
7
+ url = parse_url(request['url'])
8
+ if artifact.suffix.lower() != '.png':
9
+ raise ToolError('INVALID_REQUEST', 'Browser screenshot must be PNG')
10
+ proxy = deployment_proxy()
11
+ result = workspace / 'screen.png'
12
+ worker = pathlib.Path(__file__).with_name('render.mjs')
13
+ run_command(['node', str(worker), proxy, url, str(result)], 45, workspace)
14
+ return publish(result, artifact, b'\x89PNG\r\n\x1a\n')
15
+
16
+
17
+ commands = {'browser.navigate': ({'url', 'output'}, set(), navigate)}
@@ -0,0 +1,90 @@
1
+ import { rm } from 'node:fs/promises'
2
+ import process from 'node:process'
3
+ import { setTimeout as delay } from 'node:timers/promises'
4
+ import { chromium } from 'playwright-core'
5
+
6
+ async function render() {
7
+ const [proxy, inputUrl, output] = process.argv.slice(2)
8
+ const url = new URL(inputUrl).href
9
+ const deadline = performance.now() + 40_000
10
+ const remaining = (maximum, reserve = 0) => {
11
+ const budget = Math.floor(deadline - performance.now() - reserve)
12
+ if (budget <= 0)
13
+ throw new Error('Browser deadline exceeded')
14
+ return Math.min(maximum, budget)
15
+ }
16
+ let browser
17
+ let page
18
+ const timer = setTimeout(() => {
19
+ void browser?.close().catch(() => {})
20
+ }, 40_000)
21
+ timer.unref()
22
+ try {
23
+ browser = await chromium.launch({
24
+ executablePath: '/usr/bin/chromium',
25
+ chromiumSandbox: true,
26
+ proxy: { server: proxy, bypass: '<-loopback>' },
27
+ args: ['--disable-quic'],
28
+ timeout: remaining(10_000, 12_000),
29
+ })
30
+ const context = await browser.newContext({
31
+ javaScriptEnabled: false,
32
+ acceptDownloads: false,
33
+ serviceWorkers: 'block',
34
+ viewport: { width: 1280, height: 720 },
35
+ })
36
+ await context.route('**/*', async (route) => {
37
+ const target = new URL(route.request().url())
38
+ if (target.protocol !== 'https:' || target.port || target.username || target.password) {
39
+ await route.abort()
40
+ return
41
+ }
42
+ await route.continue()
43
+ })
44
+ page = await context.newPage()
45
+ // 两次只读导航共用二十秒,同时为截图和关闭保留总预算。
46
+ const navigationDeadline = Math.min(deadline - 12_000, performance.now() + 20_000)
47
+ const navigationRemaining = () => {
48
+ const budget = Math.floor(navigationDeadline - performance.now())
49
+ if (budget <= 0)
50
+ throw new Error('Navigation deadline exceeded')
51
+ return budget
52
+ }
53
+ let response
54
+ for (let attempt = 0; attempt < 2; attempt++) {
55
+ try {
56
+ response = await page.goto(url, {
57
+ waitUntil: 'domcontentloaded',
58
+ timeout: navigationRemaining(),
59
+ })
60
+ break
61
+ }
62
+ catch (cause) {
63
+ if (attempt !== 0 || !(cause instanceof Error)
64
+ || cause.message.split('\n', 1)[0] !== `page.goto: net::ERR_NETWORK_CHANGED at ${url}`) {
65
+ throw cause
66
+ }
67
+ await delay(Math.min(100, navigationRemaining()))
68
+ }
69
+ }
70
+ if (!response?.ok() || new URL(page.url()).protocol !== 'https:')
71
+ throw new Error('Navigation failed')
72
+ await page.screenshot({
73
+ path: output,
74
+ timeout: remaining(10_000, 2000),
75
+ })
76
+ remaining(2000)
77
+ }
78
+ finally {
79
+ try {
80
+ await page?.close({ runBeforeUnload: false }).catch(() => {})
81
+ await browser?.close()
82
+ }
83
+ finally { clearTimeout(timer) }
84
+ }
85
+ }
86
+
87
+ render().catch(async () => {
88
+ await rm(process.argv[4], { force: true }).catch(() => {})
89
+ process.exitCode = 1
90
+ })
@@ -0,0 +1,36 @@
1
+ """网页作业共用的 URL 和部署出网代理校验。"""
2
+ import ipaddress
3
+ import os
4
+ import re
5
+ from urllib.parse import urlsplit
6
+ from tool import ToolError
7
+
8
+ HOST = re.compile(r'(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z][A-Za-z0-9-]{1,62}\Z', re.ASCII)
9
+
10
+
11
+ def parse_url(url):
12
+ if not isinstance(url, str) or len(url) > 2048 or any(ord(c) <= 32 or c == '\\' for c in url):
13
+ raise ToolError('INVALID_REQUEST', 'Expected an HTTPS URL')
14
+ try:
15
+ parsed = urlsplit(url)
16
+ if (parsed.scheme == 'https' and parsed.username is None and parsed.password is None
17
+ and parsed.hostname and HOST.fullmatch(parsed.hostname) and parsed.port in (None, 443)):
18
+ return url
19
+ except ValueError:
20
+ pass
21
+ raise ToolError('INVALID_REQUEST', 'Expected HTTPS with a DNS hostname and default port')
22
+
23
+
24
+ def deployment_proxy():
25
+ # 代理身份来自部署环境;作业参数不能替换它。
26
+ try:
27
+ proxy = urlsplit(os.environ.get('HAI_TOOL_BROWSER_PROXY', ''))
28
+ if (proxy.scheme != 'http' or proxy.username is not None or proxy.password is not None
29
+ or proxy.path not in ('', '/') or proxy.query or proxy.fragment or not proxy.port):
30
+ raise ValueError
31
+ host = ipaddress.IPv4Address(proxy.hostname)
32
+ if host.is_loopback or host.is_unspecified or host.is_multicast or host.is_link_local:
33
+ raise ValueError
34
+ return f'http://{host}:{proxy.port}'
35
+ except (TypeError, ValueError):
36
+ raise ToolError('NETWORK_POLICY_REQUIRED', 'A deployment-controlled egress proxy is required') from None
@@ -0,0 +1,23 @@
1
+ FROM docker.io/library/node:24.22.1-bookworm-slim@sha256:be8204d4bd327363357f532187b752ff62759c31bedf98e9e18fc08c9cbd605c AS trust
2
+ RUN mkdir -p /etc/ssl/certs && node -e "require('node:fs').writeFileSync('/etc/ssl/certs/ca-certificates.crt', require('node:tls').rootCertificates.join('\\n'))"
3
+ FROM mcr.microsoft.com/mirror/docker/library/debian:bookworm-slim@sha256:b4aa902587c2e61ce789849cb54c332b0400fe27b1ee33af4669e1f7e7c3e22f
4
+ COPY --from=trust /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
5
+ ARG DEBIAN_MIRROR=https://deb.debian.org/debian
6
+ ARG DEBIAN_SECURITY_MIRROR=https://deb.debian.org/debian-security
7
+ RUN set -eu; \
8
+ sed -i -e "s|http://deb.debian.org/debian-security|${DEBIAN_SECURITY_MIRROR}|g" -e "s|http://deb.debian.org/debian|${DEBIAN_MIRROR}|g" /etc/apt/sources.list.d/debian.sources; \
9
+ apt-get -o Acquire::Retries=2 -o Acquire::https::Timeout=20 update; \
10
+ apt-get install -y --no-install-recommends python3 poppler-utils python3-docx python3-openpyxl python3-pip python3-pil python3-xlsxwriter; \
11
+ rm -rf /var/lib/apt/lists/*
12
+ RUN mkdir -p /opt/hai-tools /input /output && chown 1000:1000 /output
13
+ COPY tool.py /usr/local/bin/hai-tool
14
+ COPY documents/operation.py /opt/hai-tools/operation.py
15
+ COPY documents/generate.py /opt/hai-tools/documents/generate.py
16
+ COPY documents/requirements.txt /tmp/document-requirements.txt
17
+ RUN python3 -m pip install --no-cache-dir --no-deps --only-binary=:all: --require-hashes --target /opt/hai-tools -r /tmp/document-requirements.txt
18
+ COPY archives.py /opt/hai-tools/archives.py
19
+ RUN chmod 0555 /usr/local/bin/hai-tool
20
+ USER 1000:1000
21
+ ENV HOME=/tmp PYTHONDONTWRITEBYTECODE=1
22
+ WORKDIR /tmp
23
+ ENTRYPOINT ["/usr/local/bin/hai-tool"]
@@ -0,0 +1,165 @@
1
+ """从有界结构化内容生成 Office 文档,不执行用户代码或公式。"""
2
+ import json
3
+ from tool import TEXT_LIMIT, ToolError, no_duplicates, publish
4
+
5
+
6
+ def invalid(message):
7
+ raise ToolError('INVALID_REQUEST', message)
8
+
9
+
10
+ def text(value, maximum, required=False):
11
+ if (not isinstance(value, str) or len(value) > maximum or (required and not value.strip())
12
+ or any((ord(item) < 32 and item not in '\t\n\r') or 0xD800 <= ord(item) <= 0xDFFF
13
+ or ord(item) & 0xFFFF in (0xFFFE, 0xFFFF) for item in value)):
14
+ invalid('Document text has an unsupported type, character or length')
15
+ return value
16
+
17
+
18
+ def paragraphs(value):
19
+ if not isinstance(value, list) or len(value) > 100:
20
+ invalid('Document paragraphs exceed the supported limits')
21
+ return [text(item, 2000) for item in value]
22
+
23
+
24
+ def table(value):
25
+ if not isinstance(value, dict) or not {'headers'} <= set(value) <= {'headers', 'rows'}:
26
+ invalid('Document table fields are invalid')
27
+ headers = value['headers']
28
+ rows = value.get('rows', [])
29
+ if not isinstance(headers, list) or not 1 <= len(headers) <= 20 or not isinstance(rows, list) or len(rows) > 200:
30
+ invalid('Document table exceeds the row or column limits')
31
+ result = {'headers': [text(item, 2000) for item in headers], 'rows': []}
32
+ for row in rows:
33
+ if not isinstance(row, list) or len(row) != len(headers):
34
+ invalid('Document table rows must match the headers')
35
+ result['rows'].append([text(item, 2000) for item in row])
36
+ return result
37
+
38
+
39
+ def content(value):
40
+ if not isinstance(value, dict) or not {'title'} <= set(value) <= {'title', 'paragraphs', 'table'}:
41
+ invalid('Document content fields are invalid')
42
+ return {
43
+ 'title': text(value['title'], 200, True),
44
+ 'paragraphs': paragraphs(value.get('paragraphs', [])),
45
+ 'table': table(value['table']) if 'table' in value else None,
46
+ }
47
+
48
+
49
+ def slide_content(value):
50
+ result = content(value)
51
+ items = result['paragraphs']
52
+ if len(result['title']) > 100 or len(items) > 6 or any(len(item) > 160 for item in items) or sum(map(len, items)) > 800:
53
+ invalid('Presentation text exceeds the slide layout limits')
54
+ grid = result['table']
55
+ if grid:
56
+ if (len(grid['headers']) > 6 or len(grid['rows']) > 6 or len(items) > 1
57
+ or sum(map(len, items)) > 120
58
+ or any(len(cell) > 32 for row in [grid['headers'], *grid['rows']] for cell in row)):
59
+ invalid('Presentation table exceeds the slide layout limits')
60
+ return result
61
+
62
+
63
+ def specification(source, suffix):
64
+ if source.suffix.lower() != '.json' or source.stat().st_size > TEXT_LIMIT:
65
+ raise ToolError('INVALID_INPUT', 'Document generation requires a JSON specification up to 256 KiB')
66
+ try:
67
+ value = json.loads(source.read_text(encoding='utf-8'), object_pairs_hook=no_duplicates)
68
+ except (json.JSONDecodeError, UnicodeDecodeError):
69
+ invalid('Document specification must be UTF-8 JSON')
70
+ if not isinstance(value, dict):
71
+ invalid('Document specification must be an object')
72
+ if suffix == '.pptx' and 'slides' in value:
73
+ if set(value) != {'title', 'slides'} or not isinstance(value['slides'], list) or not 1 <= len(value['slides']) <= 20:
74
+ invalid('Presentation slides cannot be combined with top-level paragraphs or table')
75
+ return {'title': text(value['title'], 200, True), 'slides': [slide_content(item) for item in value['slides']]}
76
+ document = slide_content(value) if suffix == '.pptx' else content(value)
77
+ return {'title': document['title'], 'slides': [document]} if suffix == '.pptx' else document
78
+
79
+
80
+ def write_docx(value, destination):
81
+ from docx import Document
82
+
83
+ document = Document()
84
+ document.core_properties.title = value['title']
85
+ document.add_heading(value['title'], level=0)
86
+ for paragraph in value['paragraphs']:
87
+ document.add_paragraph(paragraph)
88
+ if value['table']:
89
+ grid = value['table']
90
+ rows = [grid['headers'], *grid['rows']]
91
+ target = document.add_table(rows=len(rows), cols=len(grid['headers']))
92
+ target.style = 'Table Grid'
93
+ for row, values in zip(target.rows, rows):
94
+ for cell, item in zip(row.cells, values):
95
+ cell.text = item
96
+ document.save(destination)
97
+
98
+
99
+ def write_xlsx(value, destination):
100
+ from openpyxl import Workbook
101
+
102
+ workbook = Workbook()
103
+ workbook.properties.title = value['title']
104
+ sheet = workbook.active
105
+ sheet.title = 'Report'
106
+ rows = [[value['title']], *[[item] for item in value['paragraphs']]]
107
+ if value['table']:
108
+ rows.extend([value['table']['headers'], *value['table']['rows']])
109
+ for row_number, row in enumerate(rows, 1):
110
+ for column_number, item in enumerate(row, 1):
111
+ cell = sheet.cell(row=row_number, column=column_number, value=item)
112
+ # 用户文本即使以等号开头也保持文本,不写入公式元素。
113
+ cell.data_type = 's'
114
+ workbook.save(destination)
115
+ workbook.close()
116
+
117
+
118
+ def write_pptx(value, destination):
119
+ from pptx import Presentation
120
+ from pptx.util import Inches, Pt
121
+
122
+ presentation = Presentation()
123
+ presentation.slide_width = Inches(13.333)
124
+ presentation.slide_height = Inches(7.5)
125
+ presentation.core_properties.title = value['title']
126
+ for content in value['slides']:
127
+ slide = presentation.slides.add_slide(presentation.slide_layouts[6])
128
+ title = slide.shapes.add_textbox(Inches(0.6), Inches(0.4), Inches(12.1), Inches(0.9)).text_frame
129
+ title.word_wrap = True
130
+ title.paragraphs[0].text = content['title']
131
+ title.paragraphs[0].font.size = Pt(30)
132
+ title.paragraphs[0].font.bold = True
133
+ body = slide.shapes.add_textbox(Inches(0.6), Inches(1.55), Inches(12.1), Inches(1 if content['table'] else 5.2)).text_frame
134
+ body.word_wrap = True
135
+ for index, item in enumerate(content['paragraphs']):
136
+ paragraph = body.paragraphs[0] if index == 0 else body.add_paragraph()
137
+ paragraph.text = item
138
+ paragraph.font.size = Pt(20)
139
+ paragraph.space_after = Pt(10)
140
+ if content['table']:
141
+ grid = content['table']
142
+ rows = [grid['headers'], *grid['rows']]
143
+ top = 2.65 if content['paragraphs'] else 1.55
144
+ target = slide.shapes.add_table(len(rows), len(grid['headers']), Inches(0.6), Inches(top), Inches(12.1), Inches(min(4.2, len(rows) * 0.6))).table
145
+ for row_number, values in enumerate(rows):
146
+ for column_number, item in enumerate(values):
147
+ cell = target.cell(row_number, column_number)
148
+ cell.text = item
149
+ for paragraph in cell.text_frame.paragraphs:
150
+ paragraph.font.size = Pt(13)
151
+ presentation.save(destination)
152
+
153
+
154
+ def generate(_request, source, artifact, workspace):
155
+ suffix = artifact.suffix.lower()
156
+ writers = {'.docx': write_docx, '.xlsx': write_xlsx, '.pptx': write_pptx}
157
+ if suffix not in writers:
158
+ invalid('Document output must be DOCX, XLSX or PPTX')
159
+ value = specification(source, suffix)
160
+ destination = workspace / ('result' + suffix)
161
+ try:
162
+ writers[suffix](value, destination)
163
+ except ImportError:
164
+ raise ToolError('ENVIRONMENT_UNAVAILABLE', 'The document generator dependencies are unavailable') from None
165
+ return publish(destination, artifact, b'PK\x03\x04')