smart-page

name	smart-page
description	腾讯文档智能页面（Smart Page）是可交互在线汇报网页生成工具，适用于汇报、述职、周报、复盘、数据看板、课件、培训、调研报告、会议纪要和本地 HTML 上云。区别于 PPT 与普通网页，内置叙事骨架、动效模板，生成后可在线编辑、分享并沉淀到腾讯文档。
description_zh	腾讯文档智能页面，生成可编辑可分享的在线汇报网页内容
description_en	Create interactive Tencent Docs smart pages for reports and presentations
version	1.0.1
allowed-tools	Read,Write,Bash

腾讯文档智能页面 · Smart Page

腾讯文档新产品——智能页面 · Smart Page，打造下一代可交互的 AI 原生范式分享汇报网页。

工作模式分流（关键决策）

用户请求进来时，agent 自行判断走哪条路：

用户输入
  ├─ 已有 HTML：本地路径 / 「把 HTML 上传腾讯文档」      → 走【上云模式 · 本地 HTML 一键上云】
  ├─ 模板生成：明确命中 4 类已做好模板的场景               → 走【生成模式 · 模板化生成链路】
  │    （向上汇报/立项、周期同步/复盘、数据洞察、知识传播/技术分享）
  └─ 不在本 skill 范围：其他所有场景（邀请函、官网、Landing、
        简历、H5、画册、PRD、会议纪要、婚礼/年会/发布会邀请等） → 【退出本 skill，交给通用 agent】

---

上云模式 · 本地 HTML 一键上云

触发条件：

• 用户给出 .html 文件路径（或拖附件）
• 触发词：「把这个 HTML 导入腾讯文档」「上传本地 HTML」「.html 路径 + 上传/发布/上云」

跳过全部问卷流程，直接走「发布到腾讯文档」章节（不传 --title，自动从 HTML <title> 读取）。

---

生成模式 · 模板化生成链路（概览）

触发条件：用户意图命中 4 类场景之一（proposal 向上汇报/立项、sync 周期同步/复盘、insight 数据洞察、share 知识传播/技术分享）。

⚠️ 核心原则：agent 自行 best-guess scene（不确定就选最接近的），立刻起 serve.py start，场景确认/修正由用户在右侧面板完成。绝不使用 AskUserQuestion 或对话追问。

工作流总览：

阶段 1 场景初筛 → 阶段 2 问卷路由 → 阶段 3 模板选择 → 阶段 4 骨架 loading → 阶段 5 生成数据 + inject → 阶段 6 自检 → 阶段 7 发布

📖 完整流程见 references/generate-workflow.md：含 4 类场景细表、四区理念、三层架构、阶段 1–7 的全部命令、JSON 协议和数据契约。首次执行生成模式时必读。

阶段 7 走下方「发布到腾讯文档」章节。

---

发布到腾讯文档

所有模式最终上云都走 scripts/publish.sh（脚本内有完整 Usage，执行 publish.sh --help 可查看）。

行为约束：

• ⚠️ 禁止手动调用 MCP：不要自行拼接 pre_import / async_import 调用链，必须且只能通过 bash scripts/publish.sh --html <path> 完成发布。publish.sh 内部会自动完成 .aipage 打包、上传、轮询全链路。
• 拿到 FILE_URL 后必须独立发起 preview_url 工具调用，然后告诉用户「已完成，在线地址如下 ↓」
• 失败时重试最多 2 次（间隔 5s），仍失败则把 stderr 和 TRACE_ID（如有）告诉用户，建议检查 MCP 配置
• 不要静默吞掉错误

---

核心原则

1. 模式分流优先：先判断「上云模式 / 生成模式 / 不在本 skill 范围」，不要把所有场景都塞进生成模式的固定模板流
2. 不在本 skill 范围的请求不进管线：交给通用 agent 按当次意图自由生成
3. 生成模式四区必须都有：Overview / Controls / Charts / Logic 缺一视为 PPT 化
4. 叙事 ≠ 视觉：换皮肤不改 section 顺序，换叙事不改色值
5. 首屏给结论：不允许把 TL;DR 藏在折叠里
6. 腾讯系优先：司内汇报默认 tencent-blue，且 tone=tencent 时锁定单一皮肤
7. 单文件分发：inject.py 产物必须可独立打开
8. prefers-reduced-motion 必须降级
9. 等待用 shell 循环：for+sleep+test -f，禁止 heredoc 写长 python 脚本或自定义进程管理
10. data.js 必须同时读 narrative.md + mock-data.js 再写：narrative.md 提供字段契约，mock-data.js 提供值类型、嵌套结构和 compute 写法，两者都必读
11. 注入前必跑 validate_data.py：validate_data.py --scene --narrative --data 退出码 0 才允许注入，失败则修复后重跑（最多 2 次）

---

附录

外部依赖

依赖	用途	缺失时处理
tencent-docs MCP	阶段 7 / 上云模式发布环节	提示用户在 WorkBuddy 中授权 tencent-docs 连接器
tdocs-trace-query skill	发布异常时用 trace_id 查链路	可跳过，直接把错误信息告诉用户

参考文档

文档	何时读取
references/generate-workflow.md	首次执行生成模式时必读（含完整工作流和阶段细节）
references/command-reference.md	首次执行生成模式时必读（含完整等待协议和目录结构）
references/intent-mapping.md	模式分流 / scene 推断 / 「AI 帮我选」时查表（关键词 → scene/narrative/skin）
references/architecture.md	理解四区理念 / 三层正交（场景 × 叙事 × 皮肤）时按需读取
references/data-truthfulness.md	生成数据前必读（防捏造、信息补全规则）