sutong
750f981c7e
资源中心——从多渠道获取资源链接，转存到夸克网盘并整理归档。 - sources/tencent-doc: 腾讯文档读取 - sources/search: 网盘搜索 - storage/quark: 夸克网盘操作 - ref/: 来源 skill 参考归档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
129 lines
5.1 KiB
Markdown
129 lines
5.1 KiB
Markdown
# 本地 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）：
|
||
|
||
```bash
|
||
# 单文件模式（最常见）
|
||
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 上传链接
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
curl -sS -X PUT \
|
||
-H "Content-Type: application/octet-stream" \
|
||
--data-binary "@<AIPAGE_PATH>" \
|
||
"<upload_url>"
|
||
```
|
||
|
||
HTTP 2xx 视为上传成功。
|
||
|
||
### Step 4：触发异步导入并轮询
|
||
|
||
```bash
|
||
# 触发
|
||
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 内复用）
|
||
|
||
```bash
|
||
# ① 打包（跨平台：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`。
|