PagePilot pagep Skill

核心规则

当用户要求生成网页、报告、仪表板、简历、可视化、Markdown 文档，或要求「发布到 PagePilot」「生成访问链接」「投放到屏幕」时，统一走本 Skill。

内容生成后必须发布到 PagePilot，并把服务端返回的 url、detailUrl 或 versionUrl 交给用户。不要只输出代码块让用户自己复制，也不要自行拼接最终公网链接。

安装和入口

下载地址固定为：

/skill/pagep.zip

安装后推荐使用命令名：

pagep version
pagep doctor --server https://pagepilot.example.com

如果环境没有独立 pagep 命令，但已经解压 Skill 包，则在 Skill 目录内运行：

python scripts/pagep.py version
python scripts/pagep.py doctor --server https://pagepilot.example.com

目标服务器优先使用 --server、PAGEPILOT_SERVER 或 pagep config set server <url> 保存的入口。用户用哪个 PagePilot 入口访问，就用哪个入口调用 API；路径模式下返回的应用链接会跟随这个入口。泛域名模式下，应用链接由后台的应用域名规则决定。

入口优先级

1. 能执行本地命令时，优先使用 pagep 或 python scripts/pagep.py。
2. 发布、追加或覆盖版本时，只要来源是目录、ZIP、图片、字体或大文件，优先走命令行 multipart 上传，避免把大段 base64 放进模型上下文。
3. 不能执行本地命令、只能使用 MCP 时，再调用 pagep-mcp 工具。
4. Skill、CLI、MCP 必须使用同一个 PagePilot 服务器地址和同一个用户 Token。
5. 所有入口都只展示服务端返回的链接，不按本地 host、端口或域名规则自行拼接。
6. 发布、追加或覆盖版本成功后，优先把命令输出里的「访问 URL」「详情 URL」「版本 URL」交给用户；这些链接来自服务端返回，同时保留 JSON 供自动化解析。

身份和权限

• 匿名 Agent 会在本地创建或复用 ~/.pagep/agent.json 和 ~/.pagep/session.json。
• 匿名 session 决定未登录发布的所有权；Agent 标识、IP 和 User-Agent 只用于后台展示和排查。
• 所有未登录发布都会记录为匿名会话。只创建 session 但从未发布的空会话，不展示在后台匿名列表。
• 匿名发布受额度限制，但可以发布、更新自己拥有的站点、删除自己的站点、设置或清除访问密码。
• 用户注册或提供 Token 后，应把当前匿名 session 认领到用户：

pagep claim-session

• Token 归属于注册用户。token create 默认创建长期 Token；临时 Token 使用 --expires-at 或 --ttl-seconds。
• Agent 需要长期复用身份时，先保存服务器，再用 --save 保存新 Token；后续命令会从 ~/.pagep/config.json 自动读取：

pagep config set server https://pagepilot.example.com
pagep token create ci-bot --save
pagep config show

• 屏幕绑定、投放、截图、刷新、休眠、唤醒和关机指令只允许注册用户 Token 使用。

发布前必须确认

• 先确认用户要「新建发布」还是「更新已有发布」。
• 如果用户要更新但不知道原 code 或 URL，先列出当前身份拥有的站点让用户选择，不要猜 code。
• 新建发布必须提供有意义的中文 --title，禁止使用 index.html、demo、test、未命名 这类名字。
• 必须提供 --description，控制在 240 字以内。
• 新建稳定项目建议使用可读的 --code。code 只能使用小写字母、数字和连字符。
• 首次发布前分别确认：是否进入创作市场、分类和标签、是否设置访问密码。
• 不要默认传 --filename index.html。filename 只是入口提示，普通粘贴源码、单文件、目录和 ZIP 都应省略，让服务端自动识别；只有用户明确入口路径，或接口返回多个候选入口/找不到入口时，才用 --filename <相对路径>。
• --visibility public 表示进入 PagePilot 创作市场，可搜索、可点赞；是否可下载源码和复用以详情接口返回的 allowDownload、allowReuse、policyNote 为准。--visibility unlisted 表示不进市场，只能通过链接访问。
• 匿名发布默认且只能使用 unlisted。
• 新公开作品发布前，先调用 market categories 获取服务端分类 slug，不要按文件后缀臆造分类。
• 访问密码只保护浏览器查看。匿名访客也可以输入密码访问；校验成功后获得 5 分钟、绑定目标版本的访问授权。站点改密码或切换当前版本后，旧授权需要重新验证。
• 追加版本或 --update 沿用原站点公开性和访问密码，除非用户明确要求修改。
• 覆盖版本只用于用户明确要求替换某个未锁定版本；默认更新使用追加版本。覆盖版本同样使用 multipart 上传本地文件、目录或 ZIP，目录会先临时打包成 ZIP；不要在覆盖版本时把文件塞进 JSON/base64。

内容生成规范

默认使用单 HTML

普通单页、报告、简历、名片、仪表板、简单可视化、活动页和工具页，优先生成单个自包含 HTML：

• CSS 放在 <style>。
• JS 放在 <script>。
• 少量图片可用 data URI 或在线 URL。
• 不要为了「看起来工程化」拆成 index.html + style.css + app.js。
• 不要把大型图片、视频、字体全部塞进 base64。

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>
</head>
<body>
</body>
</html>

中文字体使用系统字体栈：

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
  "Helvetica Neue", Arial, "PingFang SC", "Microsoft YaHei", sans-serif;

使用多文件或 ZIP

以下情况使用目录或 ZIP 网站包：

• 多页面应用。
• CSS、JS、图片、字体、视频资源较多。
• 用户已经提供项目目录或 ZIP。
• 需要离线稳定展示。
• Markdown 引用相对图片或附件。

多文件路径必须使用干净相对路径和 /。拒绝绝对路径、盘符、反斜杠、..、空路径片段、符号链接和源目录外文件。

目录或 ZIP 推荐结构：

site/
├── index.html
├── assets/
│   ├── app.css
│   └── app.js
└── images/
    └── cover.webp

多页面 HTML 使用相对链接，例如 settings.html 或 ./settings.html。不要在路径模式下写 /settings.html 这类根路径。

PagePilot 会在发布或覆盖版本时记录 Bundle 元数据，详情接口、CLI 和 MCP 会返回：

• single_html：单个 HTML 文件。
• markdown：Markdown 文档或以 Markdown 为入口的站点，使用平台 Markdown 渲染链路。
• zip_site：ZIP 解包后识别出的 HTML 静态站点。
• static_site：普通多文件静态站点。

Agent 不需要自行判断最终访问根目录；上传目录或 ZIP 后，以服务端返回的 URL、入口说明和文件树为准。不要为了“稳妥”给所有发布都补 --filename index.html，这会掩盖真实入口并误导用户。

ZIP / Bundle 失败时，先读取接口返回的 stage、errorCode 和 hint。stage=zip_bundle 表示服务端已经完成 ZIP 安全检查或入口识别，Agent 应直接把 hint 翻译成下一步操作，不要继续盲目重试同一个包。

常见 Bundle 错误：

• ZIP_UNSAFE_PATH：ZIP 中存在绝对路径、盘符、..、空路径段或路径穿越；重新打包，只保留干净相对路径。
• ZIP_AMBIGUOUS_ENTRY：包里像是多个独立网站；让用户选择其中一个站点目录，或拆成多个 ZIP 分别发布。
• ZIP_ENTRY_MISSING：没有发现 HTML 或 Markdown 入口；补充 index.html、README.md，或在确认真实入口路径后显式指定 --filename <相对路径>。
• ZIP_FILE_TOO_LARGE / ZIP_TOTAL_TOO_LARGE / ZIP_TOO_MANY_FILES：超过后台上传限制；压缩资源、删除无用构建产物，或请管理员调整限制。

Markdown 边界

PagePilot 支持 Markdown 作为一等入口发布，适合文档、教程、报告、README 和轻量知识页。Agent 可以直接上传 .md，不需要先转换成 HTML。

PagePilot Markdown 渲染链路内置以下能力：

• GFM：表格、任务列表、删除线、自动链接、代码块、相对图片。
• 代码高亮：服务端生成 Chroma / highlight.js 风格的高亮 HTML，明暗主题跟随页面。
• 数学公式：行内 $...$、单行块级 $$E=mc^2$$、多行块级 $$ ... $$，页面自动加载同源 KaTeX runtime 渲染。
• Mermaid：识别 mermaid 代码块，页面自动加载同源 Mermaid runtime，并用 CSP nonce 初始化。
• 安全策略：Markdown 页使用 nonce-only 脚本 CSP；同源 KaTeX、auto-render、Mermaid runtime 和平台初始化脚本都由 nonce 放行，不依赖 script-src 'self'，不允许 script-src 'unsafe-inline' / unsafe-eval。KaTeX / Mermaid 需要的运行时样式由 style-src-elem / style-src-attr 受控放行，不扩大脚本执行面。
• 主题：Markdown 页面默认 theme=auto，也支持访问 URL 追加 ?theme=light 或 ?theme=dark；PagePilot 的渲染缓存会按主题、入口、版本、内容 hash 和 renderer version 区分。

只有在用户需要复杂交互组件、第三方可视化库、完整前端状态管理或高度定制脚本时，才改用 HTML / ZIP / 多文件静态站点，并把额外运行时资源随站点一起打包。

创作市场复用

用户要求「参考这个作品」「用这个模板」「按这个风格再做一个」时，先查创作市场或读取作品详情，读取 reuse.allowDownload、reuse.allowReuse 和 reuse.policyNote。只有服务端明确允许时，才下载源文件作为参考。

pagep market search "报告" --sort hot --page-size 5
pagep market show project-home
pagep get project-home --download --output ./pagepilot-downloads
pagep deploy ./pagepilot-downloads/project-home \
  --title "参考项目官网的新作品" \
  --description "基于 project-home 的结构和风格二次创作。" \
  --template-source-code project-home \
  --template-source-version 1

如果用户明确要“更新我已有的发布”，必须先确认用户拥有的目标 code，再追加版本，不要创建新 code，也不要覆盖来源作品：

pagep get project-home --download --output ./pagepilot-downloads
pagep append existing-code ./pagepilot-downloads/project-home \
  --description "基于 project-home 的结构和风格更新已有发布。" \
  --template-source-code project-home \
  --template-source-version 1

管理员需要显式调整策略时使用：

pagep admin reuse-policy project-home --source-download deny --reuse deny
pagep admin reuse-policy project-home --source-download allow --reuse allow
pagep admin security-mode project-home --mode strict

安全模式可选：

• auto：使用 PagePilot 对 Bundle 的自动识别结果。
• strict：更严格的 CSP/sandbox，优先安全隔离，可能影响部分复杂交互。
• compatible：兼容模式，适合普通 HTML 应用。
• trusted：仅用于已审查可信内容，会放宽运行限制。

学习维度按优先级：

1. 布局结构：区域划分、信息组织、导航和视觉动线。
2. 色彩方案：主色、辅色、背景、文字色和状态色。
3. 字体排版：字号层级、行高、字重、留白。
4. 组件样式：按钮、卡片、表格、图表容器、标签。
5. 交互效果：动效、筛选、悬停、响应式。

只学习风格和结构，不复制原作品的具体文字、业务数据、密钥或私人内容。复用后默认发布为新 code，并在发布命令里带上 --template-source-code 和可用时的 --template-source-version，让 PagePilot 记录来源和复用计数；只有用户明确说要更新自己已有 code，并且已经确认目标 code 时才追加版本。

知道访问密码的用户可以浏览加密作品页面，但访问密码不等于源码下载权限。源码下载需要登录用户或已绑定注册用户的 Token；公开且未加密作品在登录 / Token 鉴权后默认可下载源码，加密、不公开、下架或策略受限的作品默认不能下载源码。加密作品即使策略设置为 allow，也不会提供源码下载；如需公开源码，应先清除访问密码，再由管理员调整策略。不要绕过 PagePilot 下载源码；应向用户说明 policyNote，请作品所有者或管理员先清除访问密码、登录或调整策略。

PagePilot 当前是创作市场复用能力，不要调用不存在的内容模板实例化工具。

常用命令

检查服务器：

pagep doctor --server https://pagepilot.example.com
pagep session --server https://pagepilot.example.com

新建发布：

pagep deploy ./site \
  --server https://pagepilot.example.com \
  --code project-home \
  --title "项目官网首页" \
  --category landing \
  --visibility public \
  --description "项目官网的首页展示。"

追加版本：

pagep deploy ./site-v2 \
  --code project-home \
  --update \
  --title "项目官网首页升级版" \
  --description "更新页面结构和文案。"

pagep append project-home ./site-v2 \
  --title "项目官网首页升级版" \
  --description "更新页面结构和文案。"

覆盖未锁定版本：

pagep overwrite project-home 2 ./site-fix \
  --title "项目官网首页修正版" \
  --description "替换第 2 个未锁定版本的页面文件。"

后台诊断：

pagep admin site-detail project-home
pagep admin audit-logs --site-code project-home --action site.visibility --page-size 20
pagep admin audit-logs --action auth.login --actor-id USER_ID --page-size 20
pagep admin audit-logs --action account.password --actor-id USER_ID --page-size 20
pagep admin security-mode project-home --mode compatible

pagep admin audit-logs 的普通输出会先给摘要表，再给每条日志的 User-Agent 和 Detail JSON；排查注册、登录、访问密码、源码下载、账号密码、CSP、投屏、版本或用户管理问题时，优先按 --site-code、--action、--actor-id、--since / --until 缩小范围。注册、登录、登出对应 auth.register / auth.login / auth.logout；账号密码修改对应 account.password；源码下载尝试对应 source_download。这些认证与权限审计只记录操作者、目标对象、结果和失败阶段，不记录明文密码或 Token。

访问密码：

pagep access project-home --password "change-me"
pagep access project-home --clear

Token：

pagep config set server https://pagepilot.example.com
pagep token create ci-bot --save
pagep token create temp-runner --ttl-seconds 86400 --save
pagep token list
pagep token save <existing-token>

管理员置顶：

pagep admin pin-site project-home
pagep admin pin-site project-home --unpin

屏幕投放：

pagep screen list --server https://pagepilot.example.com
pagep screen bind 123456 --name "大厅屏幕"
pagep screen assign screen_xxx --owner-user-id user_xxx --name "大厅屏幕"
pagep screen publish --screen screen_xxx --app project-home --expected-orientation landscape
pagep screen publish --screen screen_xxx --source ./site \
  --title "大厅展示页" \
  --visibility unlisted \
  --access-password "change-me" \
  --expected-orientation landscape \
  --description "大厅屏幕全屏展示页面。"
pagep screen screenshot screen_xxx --output ./screen-shot.jpg
pagep screen refresh screen_xxx
pagep screen sleep screen_xxx
pagep screen wake screen_xxx
pagep screen shutdown screen_xxx
pagep screen status screen_xxx
pagep screen unbind screen_xxx

屏幕投放规则

• 一个注册用户可以绑定多个屏幕。
• 投屏前先用 screen list 查看屏幕，多个屏幕时让用户选择。
• 管理员可以用 screen assign 将已连接但未配对的设备分配给注册用户；普通用户应使用屏幕端显示的配对码执行 screen bind。
• 投屏前确认页面预期方向：portrait、landscape 或 any。
• 使用屏幕返回的 deviceInfo.orientation、分辨率判断是否匹配。
• 如果页面方向和屏幕方向不一致，提醒用户可能裁切、缩放或留白；只有用户确认后才使用 --force-orientation。
• 屏幕投放发送的是播放清单和 PagePilot 应用 URL，不是把 raw HTML 字符串直接塞给硬件。
• 真正断电、定时开关机依赖设备和 OEM 能力，不要承诺所有硬件都支持。

MCP 工具对照

能用 pagep 时优先用命令行；只能使用 MCP 时，按下面工具名调用：

MCP 返回里的 URL 同样以服务端 API 返回值为准。

常见错误处理

安全红线

• 不要上传 .env、API key、Bearer Token、私钥、数据库、本地配置、日志、缓存、.git、node_modules、__pycache__。
• 不要把用户私有内容公开进创作市场，除非用户明确确认。
• 不要绕过访问密码读取加密作品源码。
• 不要把未知第三方脚本注入公开作品；必须使用时说明来源和风险。
• 不要为了兼容用户脚本直接建议关闭 CSP；先让管理员查看 security.csp_report 审计日志，再决定是否调整站点安全模式。
• 不要在总结中暴露源码、密码、Token 或敏感配置。