feat: init media-center skill

资源中心——从多渠道获取资源链接，转存到夸克网盘并整理归档。 - sources/tencent-doc: 腾讯文档读取 - sources/search: 网盘搜索 - storage/quark: 夸克网盘操作 - ref/: 来源 skill 参考归档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-05-16 18:28:23 +08:00
commit 750f981c7e
37 changed files with 7847 additions and 0 deletions
@@ -0,0 +1,128 @@
+# 本地 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`。