media-center/ref/tencent-docs/references/aipage_references.md

本地 HTML 一键上云（.aipage 导入）

本文档定义「把本地 HTML 打包成 .aipage 并上传到腾讯文档」的标准工作流， 适用场景：

• 上游 skill（如 smart-page）只产出 HTML 目录 / 单文件，打包与导入由本 skill 接手完成。
• 用户直接给出本地 .html 路径并要求「上传 / 导入 / 上云 / 发布到腾讯文档」。

⚠️ 上游 skill 禁止自行实现 prepare-pack / pack / 拼接 pre_import + async_import 的逻辑；必须改为调用本工作流。

---

触发条件

任一满足即触发：

1. 用户输入包含本地 .html 文件路径，且语义包含「上传 / 导入 / 上云 / 发布 / 同步到腾讯文档」。
2. 上游 skill（典型为 smart-page）显式声明「HTML 已生成，请用 tencent-docs 打包并导入」， 并提供：
   • 单文件入口：html_path（推荐）
   • 或目录入口：html_dir（目录内必须有 index.html，或唯一一个 *.html）
   • 可选：title（缺省时自动从 <title> 标签或文件名推导）

---

标准链路（4 步）

Step 1：本地打包成 .aipage

调用本 skill 自带的脚本 aipage_pack.js（纯 Node.js，零 npm 依赖，跨平台：macOS / Linux / Windows 原生 cmd / PowerShell 直接可用，不需要 bash / Git Bash / WSL）：

# 单文件模式（最常见）
node scripts_path/aipage_pack.js --html "<html_path>" [--title "<title>"]

# 目录模式（含 assets/ 等附属资源时）
node scripts_path/aipage_pack.js --dir  "<html_dir>"  [--title "<title>"]

scripts_path 为本 SKILL 文件所在目录，例如： backend/application/open/mcpserver/tencent-docs/aipage_pack.js

运行环境要求：Node.js >= 14（同 ocr.js）。Windows 上可直接 node aipage_pack.js ...。

脚本以稳定格式输出，可直接 grep / 正则解析：

AIPAGE_PATH=/tmp/xxx.aipage
AIPAGE_SIZE=123456
AIPAGE_MD5=abcd1234...
AIPAGE_TITLE=立项方案

退出码：0 成功；1 参数错；2 源 HTML 不合法；3 打包失败 / 工具缺失。

Step 2：调用 manage.pre_import 获取 COS 上传链接

mcporter call "tencent-docs" "manage.pre_import" --args \
  '{"file_name": "<basename(AIPAGE_PATH)>", "file_size": <AIPAGE_SIZE>, "file_md5": "<AIPAGE_MD5>"}'

返回字段中需要：upload_url、file_key、task_id。

也可以直接复用 import_file.sh（位于本 skill 同目录），它已封装 Step 1 之后的 「pre_import + PUT 上传 COS」两步，输出 IMPORT_READY + 关键字段。 推荐写法：先用 node aipage_pack.js 打出 .aipage，再 bash import_file.sh <AIPAGE_PATH>。

Step 3：PUT 上传到 COS

curl -sS -X PUT \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@<AIPAGE_PATH>" \
  "<upload_url>"

HTTP 2xx 视为上传成功。

Step 4：触发异步导入并轮询

# 触发
mcporter call "tencent-docs" "manage.async_import" --args \
  '{"task_id":"<task_id>","file_key":"<file_key>","file_name":"<file_name>","file_md5":"<AIPAGE_MD5>","file_size":<AIPAGE_SIZE>}'

# 轮询（建议每 3s 一次，最多 60s）
mcporter call "tencent-docs" "manage.import_progress" --args '{"task_id":"<task_id>"}'

progress=100 时视为成功，从返回中拿 file_id / file_url，必要时用 ?_fid=<file_id> 拼接到 file_url。

---

推荐执行模板（agent 内复用）

# ① 打包（跨平台：macOS / Linux / Windows 通用，零依赖）
PACK_OUT=$(node <skill_dir>/aipage_pack.js --html "$HTML_PATH" --title "$TITLE")
AIPAGE_PATH=$(echo "$PACK_OUT" | awk -F= '/^AIPAGE_PATH=/{print $2}')
AIPAGE_SIZE=$(echo "$PACK_OUT" | awk -F= '/^AIPAGE_SIZE=/{print $2}')
AIPAGE_MD5=$( echo "$PACK_OUT" | awk -F= '/^AIPAGE_MD5=/{print $2}')

# ② + ③ pre_import + PUT（直接复用 import_file.sh）
IMPORT_OUT=$(bash <skill_dir>/import_file.sh "$AIPAGE_PATH")
TASK_ID=$( echo "$IMPORT_OUT" | awk -F: '/^TASK_ID:/{print $2}')
FILE_KEY=$(echo "$IMPORT_OUT" | awk -F: '/^FILE_KEY:/{print $2}')
FILE_NAME=$(echo "$IMPORT_OUT" | awk -F: '/^FILE_NAME:/{print $2}')

# ④ async_import + 轮询
mcporter call "tencent-docs" "manage.async_import" --args \
  "{\"task_id\":\"$TASK_ID\",\"file_key\":\"$FILE_KEY\",\"file_name\":\"$FILE_NAME\",\"file_md5\":\"$AIPAGE_MD5\",\"file_size\":$AIPAGE_SIZE}"
# 然后轮询 manage.import_progress 至 progress=100

---

行为约束

• 必须用 aipage_pack.js 打包：禁止 agent 自己 zip / 写 manifest.json / 写 janus.manifest.json； 打包脚本是唯一真相源，避免与 aicanvas 后端结构契约漂移。Windows 等无 bash 环境必须使用本 node aipage_pack.js，不要回退到手写 zip。
• 失败重试：pre_import / async_import / 轮询失败时最多重试 2 次（间隔 5s）， 仍失败则把 stderr 与 trace_id（如有）回报用户，不要静默吞掉错误。
• 成功输出：拿到 file_url 后，独立发起一次 preview_url 工具调用， 然后告知用户「已完成，在线地址如下 ↓」。
• 常见错误码 参见主 SKILL 的「问题定位指南」，鉴权失败优先看 references/auth.md。