@code2rich/jpage 1.5.0 → 1.5.1

package/public/js/pages/preview.js

@@ -3,7 +3,7 @@
 import { api, API_BASE } from '../api.js';
 import { toast } from '../components/toast.js';
 import { dialogModal } from '../components/dialog.js';
-import { escapeHtml, formatSize, relativeTime, buildSkeletonCards } from '../utils.js';
+import { escapeHtml, formatSize, relativeTime } from '../utils.js';
 import { state, navigate } from '../app.js';
 import { closeTemplateSelect } from './home.js';
 

package/public/js/utils.js

@@ -41,15 +41,23 @@ function formatDate(iso) {
 
 function esc(s) { const d = document.createElement('div'); d.textContent = s || ''; return d.innerHTML; }
 
-function buildSkeletonCards(n) {
+function buildSkeletonCards(n, viewMode) {
   let html = '';
   for (let i = 0; i < n; i++) {
-    html += '<div class="skeleton-item" aria-hidden="true">'
-      + '<div class="skeleton-icon"></div>'
-      + '<div class="skeleton-lines">'
-      + '<div class="skeleton-line skeleton-w60"></div>'
-      + '<div class="skeleton-line skeleton-w40"></div>'
-      + '</div></div>';
+    if (viewMode === 'card') {
+      html += '<div class="skeleton-item skeleton-card" aria-hidden="true">'
+        + '<div class="skeleton-card-thumb"></div>'
+        + '<div class="skeleton-line skeleton-w60"></div>'
+        + '<div class="skeleton-line skeleton-w40"></div>'
+        + '</div>';
+    } else {
+      html += '<div class="skeleton-item" aria-hidden="true">'
+        + '<div class="skeleton-icon"></div>'
+        + '<div class="skeleton-lines">'
+        + '<div class="skeleton-line skeleton-w60"></div>'
+        + '<div class="skeleton-line skeleton-w40"></div>'
+        + '</div></div>';
+    }
   }
   return html;
 }

package/routes/skills.js

@@ -1,5 +1,6 @@
-// Skills 与 MCP 配置路由。从 server.js 提取，行为保持不变。
-// 挂载点：/api（内部路径 /skills、/skills/:name、/skills/:name/download、/mcp/config）
+// Skills、MCP 配置、CLI 指南路由。从 server.js 提取，行为保持不变。
+// 挂载点：/api（内部路径 /skills、/skills/:name、/skills/:name/download、/mcp/config、/cli/guide）
+// 设计：CLI 与 MCP 是并列的两个客户端入口（REST / MCP），各有独立端点与 UI 入口，不互相嵌套。
 
 const express = require('express');
 const { dbAll } = require('../lib/db');
@@ -41,6 +42,63 @@ function buildServerConfig(url, token) {
   };
 }
 
+// 生成 CLI 用法文档 Markdown。
+// baseUrl 预填进示例（从 /mcp URL 去掉 /mcp 后缀得到），方便用户复制即用。
+// token 用占位符 <YOUR_TOKEN>，不泄露真实 token。
+function buildCliGuide(baseUrl) {
+  return `# jpage CLI
+
+\`jpage\` 是即页的命令行工具，通过 REST API 上传/列出/管理文件。与 MCP 是**对称的两个入口**：
+
+- **有 Bash 的场景**（Claude Code/ZCode 等 agent、脚本、CI、人工操作）→ 用 **CLI**：multipart 二进制流式上传，大文件/ZIP 不进 token 流，快且省
+- **纯 MCP 客户端**（Claude Desktop 等无 Bash）→ 用 **MCP**
+
+## 安装
+
+\`\`\`bash
+npm install -g @code2rich/jpage
+jpage --help
+\`\`\`
+
+## 配置 token
+
+CLI 需要一个 token（\`jp_\` 用户 token 或全局 \`MCP_TOKEN\`）。优先级：
+
+\`--token\` > \`JPAGE_TOKEN\` 环境变量 > \`.env\` 里的 \`MCP_TOKEN\`
+
+在本系统的 **API 令牌** 页创建或复制你的 token。服务地址默认 \`${baseUrl}\`，可用 \`--base\` 覆盖。
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| \`upload <路径> [--public] [--overwrite ID]\` | 上传（ZIP 自动判 bundle/batch） |
+| \`ls [--page --limit --kw --cat --tag]\` | 列出文件 |
+| \`cat <id>\` | 输出文件内容 |
+| \`url <id>\` | 打印 /s/:key 预览链接 |
+| \`mv <id> <新名> [--public|--private]\` | 改名 / 公开性 |
+| \`rm <id> [--yes]\` | 删除 |
+| \`star <id>\` / \`unstar <id>\` | 收藏 / 取消收藏 |
+| \`tags <id> [add|set|clear] [名,名,...]\` | 标签（追加/替换/清空） |
+| \`skills ls | get <名> | download <名>\` | Skill 包 |
+| \`whoami\` | 校验 token 是否有效 |
+
+## 示例
+
+\`\`\`bash
+jpage upload ./report.html --public --base ${baseUrl}
+jpage ls --kw 季度
+jpage cat 8
+jpage tags 8 add Q3,财报
+jpage url 8
+\`\`\`
+
+> 首次使用需先设 token：\`export JPAGE_TOKEN=<YOUR_TOKEN>\`，或在命令后加 \`--token <YOUR_TOKEN>\`。
+>
+> 完整说明：\`jpage --help\`
+`;
+}
+
 router.get('/mcp/config', requireAuth, async (req, res) => {
   const enabled = !!process.env.MCP_TOKEN || true; // 现在总是可以用用户级 Token
   const host = req.headers.host || `localhost:${process.env.PORT || 8858}`;
@@ -55,7 +113,8 @@ router.get('/mcp/config', requireAuth, async (req, res) => {
 
   const globalToken = process.env.MCP_TOKEN && req.userRole === 'admin' ? process.env.MCP_TOKEN : null;
 
-  // 所有客户端共用同一配置对象；差异仅在目标文件路径/说明文字
+  // 所有 MCP 客户端共用同一配置对象；差异仅在目标文件路径/说明文字。
+  // CLI 不属于 MCP 客户端（它是 REST 命令行入口），走独立的 /api/cli/guide 端点，不混在此处。
   const config = buildServerConfig(url, globalToken);
   const configs = [
     { id: 'claude-code',    label: 'Claude Code',    path: '.mcp.json（项目根）或 ~/.claude.json', config },
@@ -75,6 +134,21 @@ router.get('/mcp/config', requireAuth, async (req, res) => {
   });
 });
 
+// CLI 用法指南。CLI 与 MCP 是并列的两个客户端入口（都架在同一套 REST API 上），
+// 故独立成端点，供「CLI 工具」菜单/弹窗取用，不挂在 MCP 配置之下。
+router.get('/cli/guide', requireAuth, (req, res) => {
+  const host = req.headers.host || `localhost:${process.env.PORT || 8858}`;
+  const protocol = req.protocol || 'http';
+  const baseUrl = `${protocol}://${host}`;
+  const guideText = buildCliGuide(baseUrl);
+  res.json({
+    enabled: true,
+    baseUrl,
+    guideText,
+    guideHtml: marked.parse(guideText, { gfm: true, breaks: false, async: false })
+  });
+});
+
 router.get('/skills/:name/download', requireAuth, (req, res) => {
   const archive = createZipStream(req.params.name);
   if (!archive) return res.status(404).json({ error: 'Skill 不存在' });

package/server.js

@@ -67,7 +67,9 @@ const app = express();
 app.set('trust proxy', 1);
 
 // helmet：关闭内置 CSP（由下方手写中间件 + render.js 分级下发），
-// 显式 frameguard=deny 与 CSP frame-ancestors 'none' 对齐，消除头冲突。
+// frameguard 默认 deny（全局 X-Frame-Options: DENY），但渲染端点需被同源 iframe 嵌入（文件列表卡片缩略图），
+// 故在下方 CSP 中间件里对渲染端点移除该头，改由 lib/render.js 显式下发 X-Frame-Options: SAMEORIGIN + CSP frame-ancestors 'self'，
+// 只允许同源嵌入、外站仍被拒。
 // crossOriginEmbedderPolicy 关闭：渲染端点会加载用户内容（可能含未带 CORP 的子资源）。
 app.use(helmet({
   contentSecurityPolicy: false,
@@ -77,9 +79,14 @@ app.use(helmet({
 
 // CSP 中间件：管理界面下发严格 APP_CSP；渲染端点（render/asset/短链）跳过，
 // 由 lib/render.js 的 renderFile 按内容类型分级下发 Markdown/HTML 策略。
+// 渲染端点还需被同源 iframe 嵌入（文件列表卡片缩略图），故移除 helmet 全局下发的
+// X-Frame-Options: DENY，改由 render.js 下发 SAMEORIGIN（仅同源可嵌入）。
 const { APP_CSP, isRenderPath } = require('./lib/csp');
 app.use((req, res, next) => {
-  if (isRenderPath(req.path)) return next();
+  if (isRenderPath(req.path)) {
+    res.removeHeader('X-Frame-Options'); // 由 render.js 按需下发 SAMEORIGIN
+    return next();
+  }
   res.setHeader('Content-Security-Policy', APP_CSP);
   next();
 });
@@ -244,7 +251,7 @@ app.get('*', (req, res) => {
 });
 
 // --- 全局错误处理 ---
-app.use((err, req, res, next) => {
+app.use((err, req, res, _next) => {
   logger.error({ type: 'app', message: err.message, stack: err.stack });
   if (err instanceof multer.MulterError) {
     if (err.code === 'LIMIT_FILE_SIZE') return res.status(400).json({ error: '文件大小超过50MB限制' });

package/skills/jpage-presentation/INSTALL.md

@@ -0,0 +1,50 @@
+# 安装 jpage-presentation Skill
+
+本 Skill 适用于支持 **SKILL.md 开放标准** 的 AI 客户端（Claude Code、Claude Desktop、OpenAI Codex CLI、Cursor 等）。
+
+## 前置条件
+
+- AI 客户端已配置即页的 MCP 端点（`/mcp`），且 `upload_file` 工具可用
+- 若要用 curl multipart 上传（推荐）：运行环境有 Bash 能力
+
+## 方式一：从即页 Web UI 下载 ZIP（最简单）
+
+1. 打开即页首页，找到 Skills 区块
+2. 点击 `jpage-presentation` → 下载 ZIP
+3. 解压到客户端的 skills 目录（见下方各客户端路径）
+
+## 方式二：从仓库直接复制
+
+```bash
+cp -r /path/to/jpage/skills/jpage-presentation ~/.claude/skills/
+```
+
+## 各客户端 skills 目录
+
+| 客户端 | 路径 |
+|---|---|
+| Claude Code | `~/.claude/skills/` |
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/skills/` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\skills\` |
+
+## 验证安装
+
+1. 重启 AI 客户端（让它重新扫描 skills 目录）
+2. 对 AI 说：「做一个关于 X 的 5 页 PPT，商务风格」
+3. AI 应触发本 Skill，生成 reveal.js 幻灯片并上传到即页
+
+## assets 目录说明
+
+本 Skill 的 `assets/` 目录已随包下发 reveal.js 5.x 引擎、基础 CSS、四套主题、notes/highlight 插件骨架。生成幻灯片时，AI 会把这些文件复制到目标 `deck/assets/`，**不需要额外下载**（除非要用代码高亮，见 SKILL.md「highlight.js 按需获取」）。
+
+## 更新 reveal.js
+
+`assets/reveal.js` 和 `assets/reveal-base.css` 是 reveal.js 5.2.1 的官方产物。升级时：
+
+```bash
+npm pack reveal.js@5
+tar -xzf reveal.js-5.*.tgz --strip-components=1 -C assets package/dist/reveal.js package/dist/reveal.css
+mv assets/reveal.css assets/reveal-base.css
+```
+
+插件同理，从 `package/plugin/` 复制对应文件。

package/skills/jpage-presentation/README.md

@@ -0,0 +1,71 @@
+# jpage-presentation
+
+用自然语言生成基于 [reveal.js](https://revealjs.com/) 的自包含幻灯片，上传到即页后返回分享链接。
+
+支持四套主题：
+
+| 主题 | 文件 | 主色 | 适用场景 |
+|---|---|---|---|
+| 商务 | `assets/themes/business.css` | 深蓝 + 白底 | 季度汇报、商业提案、年终总结 |
+| 学术 | `assets/themes/academic.css` | 深灰 + 米白、衬线标题 | 论文答辩、学术分享、研究报告 |
+| 创意 | `assets/themes/creative.css` | 高饱和深底渐变 | 产品发布、创意提案、活动 keynote |
+| 极简 | `assets/themes/minimal.css` | 黑白 + 蓝色强调 | 极简主义、keynote/苹果风 |
+
+## 为什么用 Bundle 模式
+
+reveal.js 引擎 ~112KB。若内联进每个幻灯片 HTML，10 个 PPT 就要重复 10 份引擎代码。即页的 **Bundle 机制**（ZIP 解压成目录 + `<base>` 注入）让 reveal.js 作为公共资源放一次，多张幻灯片复用，且**离线可预览**（不依赖 CDN）。
+
+## 工作流
+
+```
+用户："做一个 Q3 汇报 PPT，商务风格"
+  ↓
+1. 选商务主题
+2. 规划结构（封面 / 内容 / 分隔 / 总结）
+3. 生成 deck/（index.html + assets/，assets 含 reveal.js + 主题 CSS）
+4. 打 ZIP 上传到即页（bundle 自动识别）
+5. 返回 /s/<share_key>
+```
+
+## 目录结构
+
+```
+jpage-presentation/
+├── SKILL.md                    # AI 工作流指令（核心）
+├── README.md                   # 本文件
+├── INSTALL.md                  # 安装说明
+└── assets/                     # 随包下发的 reveal.js 资源
+    ├── reveal.js               # reveal.js 5.x 引擎（112KB）
+    ├── reveal-base.css         # reveal.js 基础布局（54KB，必须）
+    ├── themes/
+    │   ├── business.css        # 商务主题（CSS 变量驱动）
+    │   ├── academic.css        # 学术主题
+    │   ├── creative.css        # 创意主题
+    │   └── minimal.css         # 极简主题
+    └── plugin/
+        ├── highlight/          # 代码高亮（monokai 主题 + 加载器；highlight.js 按需获取）
+        └── notes/              # 演讲者备注
+```
+
+## 关键技术决策
+
+- **`embedded: true`**：reveal.js 必须配置此项，适配即页预览的 iframe 沙箱（父页面会抢方向键/空格，`embedded` 让 reveal 依赖容器点击聚焦）。
+- **禁用 CDN**：所有资源打进 `assets/`，保证内网/断网可预览。
+- **两个 CSS**：`reveal-base.css`（基础布局，必须）+ `theme.css`（四选一，覆盖 CSS 变量）。顺序：base 在前，theme 在后。
+- **上传通道**：有 Bash 时走 curl multipart（二进制流式，快）；纯 MCP 走 `upload_file` 的 base64（体积大时慢且费 token）。
+
+## 验证状态
+
+| 验证项 | 结果 |
+|---|---|
+| Bundle 分类（flat 结构）| ✅ 通过（根级 index.html + assets/ 判为 bundle）|
+| Bundle 分类（wrapped 结构）| ✅ 通过（套顶层目录也能判 bundle）|
+| `<base>` 注入 + 资源 200 | ✅ 通过（reveal.js / theme.css / reveal-base.css 全 200）|
+| wrapped 包资源 404 bug | ✅ 已修复（`<base>` 指向 entry 所在目录而非 bundle 根）|
+| 测试套件回归 | ✅ 173/173 通过 |
+| iframe 内 embedded 翻页 | ⏳ 需浏览器实测（设计上 `embedded:true` 规避抢键）|
+
+## 致谢
+
+- [reveal.js](https://revealjs.com/) by Hakim El Hattab（MIT 许可）—— 幻灯片引擎
+- [ryanbbrown/revealjs-skill](https://github.com/ryanbbrown/revealjs-skill) —— 脚手架思路与结构语法的灵感来源

package/skills/jpage-presentation/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: jpage-presentation
+description: 当用户要"生成 PPT""做幻灯片""演示文稿""做一个 deck""答辩 slides"时，生成基于 reveal.js 的自包含幻灯片网站包（Bundle）并上传到即页，返回分享链接。支持商务/学术/创意/极简四套主题。区别于普通 HTML：必须用 Bundle 模式（ZIP 含 index.html + assets/），不要单文件内联 reveal.js。
+version: 1.0.0
+author: jpage
+---
+
+# 核心规则
+
+用户要幻灯片 / PPT / 演示文稿时，按下面的 **Bundle 工作流**生成并上传，不要生成单文件 HTML。
+
+# 触发场景
+
+- 用户说"生成 PPT""做幻灯片""演示文稿""做一个 deck"
+- 用户说"Q3 汇报""产品发布""答辩 slides""培训课件"
+- 用户给一份文档/笔记，要求"转成幻灯片""做成 PPT"
+
+# Bundle 工作流（必须遵守）
+
+reveal.js 引擎 ~85KB，单文件内联会让每个 PPT 膨胀。即页有 **Bundle 机制**（ZIP 解压成目录，资源共用，离线可预览），必须走这条路。
+
+## 1. 规划结构
+
+先规划幻灯片结构，再动手生成。常见结构：
+
+- **简单式**：封面 → N 张内容 → 总结
+- **章节式**：封面 → 章节分隔页 → 内容页（可垂直堆叠）→ 下一章节分隔 → 内容 → 总结
+
+结构语法（可选，用于脚手架脚本）：`1` = 单张水平页，`N` = N 张垂直堆叠，`d` = 居中大字的分隔页。
+例：`1,d,3,d,2,d,1` = 封面 / 分隔 / 3 页内容 / 分隔 / 2 页内容 / 分隔 / 总结。
+
+## 2. 选主题
+
+根据用户语气选主题（用户没指定时默认**商务**）：
+
+| 用户说 | 主题 | 主色 |
+|---|---|---|
+| 商务 / 汇报 / 正式 / 提案 / 季度 / 年终 | 商务 (business) | 深蓝 #0a4d8c + 白底 |
+| 学术 / 论文 / 答辩 / 研究 | 学术 (academic) | 深灰 + 米白，衬线标题 |
+| 创意 / 产品 / 发布 / 活泼 / 设计 | 创意 (creative) | 高饱和渐变 |
+| 极简 / 简约 / keynote 风 / 苹果风 | 极简 (minimal) | 黑白 + 一个强调色 |
+
+## 3. 生成多文件网站包
+
+写到磁盘，目录结构推荐如下（**根级直接是 index.html + assets/**，即 flat 结构）：
+
+> 💡 实测：套顶层目录（如 `deck/index.html`）也能正确识别为 bundle 并渲染，但 flat 结构更简洁，推荐。
+
+```
+deck/
+├── index.html          # reveal.js 容器，<div class="reveal"><div class="slides">...</div></div>
+├── assets/
+│   ├── reveal.css      # 从本 Skill 的 assets/themes/<主题>.css 取（已下发）
+│   ├── reveal.js       # reveal.js 引擎（见下文"获取 reveal.js"）
+│   └── plugin/         # markdown / highlight / notes 插件（按需，见下文）
+```
+
+### index.html 必须满足
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>幻灯片标题</title>
+  <link rel="stylesheet" href="assets/reveal-base.css">   <!-- reveal.js 基础布局（必须） -->
+  <link rel="stylesheet" href="assets/theme.css">          <!-- 选定的主题（覆盖 CSS 变量） -->
+  <link rel="stylesheet" href="assets/plugin/highlight/monokai.css">  <!-- 代码高亮主题，按需 -->
+</head>
+<body>
+  <div class="reveal">
+    <div class="slides">
+      <section><h1>标题</h1><p>副标题</p></section>
+      <section>水平页</section>
+      <section>
+        <section>垂直堆叠页 1</section>
+        <section>垂直堆叠页 2</section>
+      </section>
+    </div>
+  </div>
+  <script src="assets/reveal.js"></script>
+  <script src="assets/plugin/highlight/highlight.js"></script>
+  <script>
+    Reveal.initialize({
+      embedded: true,        // ★ 必须 true：iframe 内兼容，依赖容器聚焦而非全局键盘
+      hash: true,
+      controls: true,
+      progress: true,
+      slideNumber: true,
+      transition: 'slide',
+      plugins: [RevealHighlight]
+    });
+  </script>
+</body>
+</html>
+```
+
+**关键约束**：
+- ⚠️ `Reveal.initialize` 必须设 **`embedded: true`**——即页预览在 iframe 里，父页面会抢方向键/空格，`embedded:true` 让 reveal 依赖容器点击聚焦，避免抢键冲突。
+- ⚠️ **不要引用任何 CDN**（jsdelivr/unpkg/cdnjs 都不行）。即页核心卖点是离线可预览，走 CDN 会让内网/断网用户看到空白。所有 reveal.js 资源必须打进 `assets/`。
+- ⚠️ 每页 `<section>` 内容精简。reveal.js **不自动滚动**，内容溢出会被裁切。一张幻灯片讲一个要点。
+- 中文字体用系统栈：`-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif`。
+
+## 4. 获取 reveal.js 资源
+
+reveal.js 引擎 + 基础 CSS + 4 套主题 + notes/highlight 插件骨架**已随本 Skill 包下发**（`assets/` 目录，~312KB）。生成幻灯片时直接复制这些文件到目标 `deck/assets/`：
+
+```bash
+# 假设本 Skill 已安装到 ~/.claude/skills/jpage-presentation/
+SKILL=~/.claude/skills/jpage-presentation
+
+mkdir -p deck/assets/plugin/notes deck/assets/plugin/highlight
+cp "$SKILL/assets/reveal.js"           deck/assets/
+cp "$SKILL/assets/reveal-base.css"     deck/assets/        # reveal.js 基础布局（必须）
+cp "$SKILL/assets/themes/business.css" deck/assets/theme.css  # 选定主题，见第 2 步
+cp "$SKILL/assets/plugin/notes/notes.js" deck/assets/plugin/notes/   # 演讲者备注，可选
+cp "$SKILL/assets/plugin/highlight/plugin.js" deck/assets/plugin/highlight/  # 代码高亮加载器
+cp "$SKILL/assets/plugin/highlight/monokai.css" deck/assets/plugin/highlight/ # 高亮主题
+```
+
+**必须引入的两个 CSS**：`reveal-base.css`（reveal.js 基础布局）+ `theme.css`（四套主题之一，覆盖 CSS 变量）。顺序：base 在前，theme 在后。
+
+### highlight.js 按需获取（可选）
+
+本 Skill 默认**不含** highlight.js 全量文件（940KB，太重）。若幻灯片需要代码高亮：
+```bash
+npm pack highlight.js@11 && tar -xzf highlight.js-*.tgz --strip-components=1 -C deck/assets/plugin/highlight package/es/highlight.min.js package/styles/monokai.css
+```
+不需要代码高亮时，不要引入，省体积。
+
+### 找不到本 Skill 包时
+
+若运行环境没有本 Skill 的 `assets/`（如只贴了 SKILL.md），从 npm 拿稳定版：
+```bash
+npm pack reveal.js@5
+tar -xzf reveal.js-5.*.tgz --strip-components=1 -C deck/assets package/dist/reveal.js package/dist/reveal.css package/plugin/
+mv deck/assets/reveal.css deck/assets/reveal-base.css
+# 主题则用本 SKILL.md 里第 5 节的 CSS 变量自定义，或参照 themes/ 目录手写
+```
+
+## 5. 上传（Bundle 模式）
+
+打包 ZIP 并上传。推荐 **flat 结构**（ZIP 根级直接是 index.html + assets/）。
+
+### 有 Bash（Claude Code）→ curl multipart（推荐，快）
+
+```bash
+TOKEN=$(grep -E '^MCP_TOKEN=' .env 2>/dev/null | cut -d= -f2-)
+[ -z "$TOKEN" ] && TOKEN=$(grep -oE 'Bearer [A-Za-z0-9_]+' .mcp.json 2>/dev/null | head -1 | awk '{print $2}')
+BASE="${JPAGE_BASE:-http://localhost:8858}"
+
+# 打 ZIP：优先系统 zip 命令（flat 结构，根级直接 index.html）
+if command -v zip >/dev/null 2>&1; then
+  ( cd deck && zip -rq ../deck.zip index.html assets/ )
+else
+  # 无 zip 命令时用 Node + JSZip（即页已依赖 jszip）
+  node -e '
+    const JSZip=require("jszip"),fs=require("fs"),path=require("path");
+    (async()=>{
+      const z=new JSZip();
+      (function add(root,base=""){for(const n of fs.readdirSync(root)){const a=path.join(root,n),r=base?base+"/"+n:n;
+        if(fs.statSync(a).isDirectory())add(a,r);else z.file(r,fs.readFileSync(a));}})(process.cwd()+"/deck");
+      fs.writeFileSync("deck.zip",await z.generateAsync({type:"nodebuffer"}));
+    })();
+  '
+fi
+
+curl -sS -X POST "$BASE/api/files/upload" \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "file=@deck.zip" \
+  -F "isPublic=true"
+```
+
+服务端自动判定为 bundle（根级有 index.html + assets 子目录），返回 `{id, share_key, ...}`。
+（套了顶层目录的 ZIP 也能识别为 bundle，但 flat 更简洁。）
+
+### 纯 MCP（Claude Desktop 无 Bash）→ upload_file base64
+
+```python
+upload_file(
+  name="ai-trends-deck.zip",
+  content="<ZIP 的 base64>",   # base64(文件二进制)
+  isPublic=True
+)
+```
+
+⚠️ 体积提示：reveal.js ~85KB 经 base64 约 113KB，作为 tool 参数流经模型 token 流，比 curl multipart 慢且费 token。有 Bash 就别走这条。
+
+## 6. 返回并提示翻页方式
+
+上传成功后向用户展示 `/s/<share_key>` 链接，并附一句提示：
+
+> 幻灯片打开后，**点击幻灯片区域聚焦**，再用 ← → 翻页（或点右下角控件）。若键盘不响应，点预览页右上角"新窗口打开"按钮全屏查看。
+
+# 内容规范
+
+- **封面页**：大标题 + 副标题 + 作者/日期。用 `class="fit-text"` 或 `<h1>` 默认样式。
+- **分隔页**：居中大字，标识新章节。`<section><h2 class="r-fit-text">章节名</h2></section>`。
+- **内容页**：一个要点 + 3-5 条要点列表或一张图。不要堆字。
+- **代码页**：用 `<pre><code class="language-js">...</code></pre>`，配 highlight 插件。
+- **图表**：用 Mermaid（`<pre class="mermaid">...</pre>` 需引入 mermaid 插件）或内联 SVG。避免引入 Chart.js（增加体积）。
+- **结尾页**：感谢 + 联系方式 / Q&A。
+
+# 风格学习（可选）
+
+若用户说"参照某风格"，先 `list_content_templates(scene="presentation")` 取样例，学习其：
+1. 配色方案 → 映射到四套主题之一或微调 CSS 变量
+2. 版式（标题大小、留白） → 调 `--r-heading-font-size` 等
+3. 装饰元素（分隔线、页码样式）
+
+**学风格，不抄内容**。
+
+# 常见坑
+
+| 现象 | 原因 | 解决 |
+|---|---|---|
+| 上传后被当成多个独立文件（batch）而非一个幻灯片包 | ZIP 里没有 index.html，或有多个并列 HTML 且无共享资源目录 | 确保根级有 index.html + assets/ 子目录；只一个 HTML 时也会判 bundle |
+| 幻灯片打开是空白 | 引用了 CDN 的 reveal.js | 所有资源必须本地 `assets/`，禁止 CDN URL |
+| 翻页键不响应 | iframe 父页面抢键 | 已用 `embedded:true` 规避；提示用户先点击聚焦，或用新窗口打开 |
+| 文字被裁切 | 一页内容太多 | 拆页，每页一个要点 |
+| 主题样式没生效 | 只引入了 theme.css 没引入 reveal-base.css，或顺序反了 | 必须 `<link href="assets/reveal-base.css">` 在前，`<link href="assets/theme.css">` 在后，两者都在 reveal.js 之前 |
+
+# 复用
+
+上传环节**统一走 `jpage-upload` 的 `upload_file` 工具**，本 Skill 不另造上传逻辑。

package/skills/jpage-presentation/assets/plugin/highlight/monokai.css

@@ -0,0 +1,71 @@
+/*
+Monokai style - ported by Luigi Maselli - http://grigio.org
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 0.5em;
+  background: #272822;
+  color: #ddd;
+}
+
+.hljs-tag,
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-literal,
+.hljs-strong,
+.hljs-name {
+  color: #f92672;
+}
+
+.hljs-code {
+  color: #66d9ef;
+}
+
+.hljs-class .hljs-title {
+  color: white;
+}
+
+.hljs-attribute,
+.hljs-symbol,
+.hljs-regexp,
+.hljs-link {
+  color: #bf79db;
+}
+
+.hljs-string,
+.hljs-bullet,
+.hljs-subst,
+.hljs-title,
+.hljs-section,
+.hljs-emphasis,
+.hljs-type,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-selector-attr,
+.hljs-selector-pseudo,
+.hljs-addition,
+.hljs-variable,
+.hljs-template-tag,
+.hljs-template-variable {
+  color: #a6e22e;
+}
+
+.hljs-comment,
+.hljs-quote,
+.hljs-deletion,
+.hljs-meta {
+  color: #75715e;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-literal,
+.hljs-doctag,
+.hljs-title,
+.hljs-section,
+.hljs-type,
+.hljs-selector-id {
+  font-weight: bold;
+}