use-agent-pages

name	use-agent-pages
description	agent-pages 的引导纲要（bootstrap doctrine）。会话开始时自动注入，用以说明 /agent-pages 的入口、何时建议它、以及生成页面时的硬约束。在真正开始写页面 / 发布之前，先按本文挑入口；完整工作流见 agent-pages:agent-pages skill。

Using agent-pages

agent-pages 把当前会话中的主题/资料生成为一份独立可浏览的单文件 HTML 页面（结构清晰、化繁为简、由浅入深，重图形/表格/动效与精致 UI/UE），并发布到用户自己的站点仓库（一个独立 git 仓，部署到 GitHub Pages；首次由 setup.sh 从插件 templates/ 脚手架而来）。

本文档只负责入口判断——告诉你何时该用、何时只是建议、以及不可逾越的红线。具体的「准备 → 评估素材 → 从零设计 → 发布 → 校验」执行链路在 agent-pages:agent-pages skill 里，进入流程后以它为准。

入口（何时进入流程）

正常入口是用户输入以 /agent-pages 开头的命令：

命令	含义
/agent-pages <主题>	用该主题生成页面（分类由助手从固定分类集里推断）
/agent-pages 分类=<slug> <主题>	显式指定画廊分类（页面落到 <slug>/ 目录下）
/agent-pages 续写 <已有文件名>	在已有页面上迭代/补充

收到上述命令，即调用 agent-pages:agent-pages skill 按其工作流执行。

何时建议（不要直接动手）

当用户的请求做成一份自包含 HTML 工件，会比一长段 Markdown 更清楚时，先用一两句话建议 /agent-pages <主题>，并询问是否采用——不要未经确认就开始写文件/发布。典型适合场景：

• 并排对比的探索 / 方案规划、带注解的代码评审
• 设计系统 / 组件变体、交互原型、图示与调研地图
• 幻灯片/报告式表达、事故/状态/PR 复盘、小型自定义评审/编辑 UI

不要为以下场景建议：快速问答、简短解释、常规小改、或用户明显只想要纯文本。

硬约束（红线）

• 不自动造页面：用户没用 /agent-pages 也没确认，就不要写文件、不要发布。
• 不虚构：涉及外部事实（版本号、API、人物、数据）不确定时标 TODO 或停下问，宁可留白也不发布错误信息；素材稀薄先问用户（补料 / 授权联网 / 出大纲版），不要硬写成占位符页面。
• 每次从零设计：禁止读画廊里 index.html 或任何历史页面去「借鉴」配色/版式/动效；主题决定设计语言。
• 按分类组织：页面落在 <category>/<yyyyMMdd>-<slug>.html；category 必须是 data.json.categories 里的 slug（没有「项目」概念了）。难归类才用 other，不要擅自造新分类。
• 日期以脚本为准：用 new-page.sh 返回的日期，不要用 LLM 记忆里的「今天」。
• 路径不硬编码：脚本走插件目录 ${CLAUDE_PLUGIN_ROOT}/scripts/；配置/站点路径走插件持久数据 ${CLAUDE_PLUGIN_DATA}/config.env。配置不存在 → 站点尚未初始化，先跑 setup.sh（见下）。
• 发布只用 publish.sh：不要在站点里 git add -A；脚本只会 stage 页面 + index.html + data.json。

配置与脚本在哪

• agent-pages 以插件分发(marketplace 安装)。脚本在插件里 ${CLAUDE_PLUGIN_ROOT}/scripts/(setup.sh / new-page.sh / publish.sh)。
• 配置 + 状态在插件持久数据目录 ${CLAUDE_PLUGIN_DATA}/config.env(跨更新存活)：AGENT_PAGES_PATH(站点 git 仓目录) / AGENT_PAGES_REPO / AGENT_PAGES_BRANCH / AGENT_PAGES_SITE_BASE_URL / AGENT_PAGES_NAME。
• 首次使用：若 config.env 不存在,先跑一次 setup.sh——它从插件 templates/ 把站点脚手架拷到 AGENT_PAGES_PATH(默认 $HOME/agent-pages)、git init、写配置。站点是用户自己的独立 git 仓,部署到 GitHub Pages。
• 调脚本前 export AGENT_PAGES_CONFIG_FILE="${CLAUDE_PLUGIN_DATA}/config.env",脚本据此读配置。
• 本插件（agent-pages）分发能力 + 站点模板：agent-pages:agent-pages 工作流 skill、use-agent-pages 本文、session-start hook、scripts/、以及 templates/。站点内容在用户自己的独立站点仓 $AGENT_PAGES_PATH，配置/状态在 ${CLAUDE_PLUGIN_DATA}/config.env——都不在插件目录内（插件目录是临时的）。