Page Generator

⚠️ .agents/ 是外部资源包路径，本机已不存在（Documents/Claude/Product/.agents/ 已删除）。 下文凡引用 .agents/knowledge/、.agents/agents/、.agents/agent-memory/ 的地方读不到文件， 按以下降级处理，不要因此中止：

• .agents/knowledge/**（内容规范、质量清单）→ 用本技能 references/ 下的模板与检查表；两者都缺时按通用工程规范执行并在产出里标注「无内容规范可依」
• .agents/agents/*.md（子 Agent 派发）→ 不派发，由当前会话直接执行该角色的工作
• .agents/agent-memory/**（跨会话记忆）→ 跳过读写，改为在产出里写清本次的决定
• .agents/rules/prd-to-srs-gate.md → 已迁到 ../common/prd-to-srs-gate.md（库内权威副本）

页面生成器工作流

每次生成功能页面，必须严格按以下 8 个步骤（步骤 0–7） 执行，每步都要有结果输出。

重要：本 skill 是通用工作流框架，不绑定任何特定项目或框架。 项目特有约定（目录结构、命名规范、路由方式、导航方式、全局样式、Mock 等） 由步骤 2 的 page-spec-loader 从 {PROJECT_PATH}/README-DEV.md 加载（优先）， 并辅以 {WORKSPACE_PATH}/.agents/knowledge/ 中的通用规范。 若 README-DEV.md 不存在，则通过读取项目文件自行推断。

多子项目说明：子项目一律在 dev/code/ 下（如 dev/code/admin/、dev/code/shadcn/、dev/code/mobile/； 存量项目可能仍在仓库根，那就按实际位置来）。若存在多个子项目， 步骤 1 必须先确定目标子项目，后续所有路径均以子项目根目录为 PROJECT_PATH； WORKSPACE_PATH 为含 .agents/ 的仓库根目录（通常为 PROJECT_PATH 的父目录）。

子项目选型参考：Vue + Element Plus 后台 → admin/；React + shadcn/ui 后台 → shadcn/；移动端 H5 → mobile/（按 SRS 端别与用户指令为准）。

交付模式：读取 AGENTS.md「交付模式」分技能默认及用户声明；本技能未声明时默认「快速」（可说「标准模式」升档）。步骤 1 记录 DELIVERY_MODE，步骤 6 按该模式选择审查范围。

步骤 0：SRS 真源门禁（必须先于步骤 1）

Read ../common/prd-to-srs-gate.md，执行检测：

1. Glob("dev/SRS/*.md")、Glob("docs/SRS/*.md")（旧根）、Glob("docs/01-需求与规划/*SRS*.md")（更旧的归档路径）或 Glob("**/*需求*说明书*.md") → 校验含功能清单 / 页面清单 / 字段级功能详细设计三部分（默认模板是 3.1 / 3.3 / 3.5；其他模板章节号不同，映射表见 ../common/prd-to-srs-gate.md §2）
2. 若 无合格 SRS 且存在 prd/PRD/*.md（或旧路径 docs/**/*-PRD.md）：
   • 用户 未 触发降级豁免词（见门禁 §4）→ 输出 §3 标准话术，中止，路由 req-doc Step F
   • 用户已触发降级 → 读 PRD 的功能清单与功能详细描述两部分，步骤 1 标注 ⚠ 降级模式。 按内容角色找，别死认 §4/§5——那是 prd-writer / prototype-to-prd 的结构； pm-prd-spec 出的 PRD 是「功能域 / 页面 / 页面内小节」结构，没有 §4/§5： 功能域与页面标题本身就是功能清单，各页的字段表与交互表就是详细描述
3. 有合格 SRS → 登记 SPEC_SOURCE=<SRS路径>，进入步骤 1

禁止：把 PRD 的功能清单/详细描述当作 SRS 那三部分读取（PRD 缺路由、数据源与字段类型）；禁止静默跳过门禁；禁止只因章节号不是 3.1/3.3/3.5 就判 SRS 不合格；也禁止只因 PRD 里找不到 §4/§5 就判它不可用——换个结构而已。

步骤 1：需求理解

目标：明确要实现什么，不能靠猜。

执行动作：

0. 判断触发模式：

下文的「交付计划」首选 issues/kanban.md 与 issues/ready/（task-breakdown 产出）。 用 Glob("issues/kanban.md") 找；未命中再试存量的 dev/plan/delivery-plan-*.md、 旧命名 dev/plan/delivery-plan.md（旧交付计划技能已删除，这些文件只读兼容）。 命中多个（一个 dev/SRS/ 下并行多个项目）时让用户选，不要自己挑第一个。

• 若用户说的是"按计划实现下一个功能"（批量模式自动触发）：
  • 读取交付计划，找到当前推荐功能（"当前推荐"章节）
  • 将该功能名作为目标功能，继续执行步骤 1
  • 记录触发模式为"批量模式"
• 若用户说的是"实现全部功能"/"连续实现"等批量指令：
  • 读取交付计划，找到第一个依赖已满足的 ⬜ 功能
  • 将该功能名作为目标功能，继续执行步骤 1
  • 记录触发模式为"批量模式"

交付计划不存在时（批量模式的前置）：不要中止，也不要自己猜实现顺序。 两个选择给用户挑：① 先跑 task-breakdown 拆任务（推荐，它按三源切片并排依赖顺序）； ② 直接从 SPEC_SOURCE 的 3.1 功能列表按顺序实现，此时没有依赖检查，可能先做了依赖别人的功能。 选 ② 时在每个功能的产出里标注 ⚠ 无交付计划，未做依赖校验。

• 若用户指定了具体功能名（"实现xxx"）：
  • 直接使用该功能名，记录触发模式为"单次模式"

批量模式铁律：YOU MUST NOT 在功能之间停下来询问用户。不问"继续吗？"，不问"是否继续？"，不输出任何等待确认的内容。完成一个立即开始下一个。

质量铁律：无论批量还是单次，每个功能必须：

1. 完整输出步骤 1 的需求理解清单（不能跳过，这是后续实现的对照基准）

2. 严格按需求清单逐项实现（不能因为"结构相似"就简化）

3. 必须调用 page-reviewer 做步骤 6 验收（不能跳过）

4. 每次只实现一个功能（不能把多个功能合并处理）

5. 探测子项目结构：先看 dev/code/ 下有哪些含 package.json（或 go.mod/pyproject.toml）的子目录 （dev/code/admin/、dev/code/shadcn/、dev/code/mobile/、dev/code/web/ 等）；dev/code/ 不存在时 再看仓库根（存量项目的旧布局）

   • 若存在多个子项目，根据功能名和需求文档判断目标子项目（PC Vue 后台→admin，PC React/shadcn 后台→shadcn，移动端→mobile）
   • 确定后，将该子项目目录作为后续所有步骤的 PROJECT_PATH
   • 若只有一个子项目或根目录本身就是项目，直接用根目录作为 PROJECT_PATH
   • WORKSPACE_PATH：若 {PROJECT_PATH}/.agents/knowledge/ 存在则等于 PROJECT_PATH；否则若 {PROJECT_PATH}/../.agents/knowledge/ 存在则取 PROJECT_PATH 的父目录；否则等于 PROJECT_PATH

6. 读取 SRS（步骤 0 已登记 SPEC_SOURCE 时直接用该路径；否则 dev/SRS/*.md、docs/01-需求与规划/*SRS*.md（旧归档路径）或 *需求*说明书*.md）

   • 有合格 SRS 时，按以下顺序读取对应章节（须为 req-doc 模板结构，非 PRD）：

   第一步：读取菜单结构（3.1 总体功能架构 的菜单结构文字说明）

   • 确认目标功能所属的一级菜单、二级菜单
   • 确认路由路径（从菜单层级推断，不能自己猜）

   第二步：读取页面功能清单（3.3 页面功能清单）

   • 找到目标功能对应的所有行
   • 提取该功能下的所有子功能（筛选、列表、新增、编辑、删除、导出、状态切换、特殊操作等）
   • 这是功能的完整清单，后续实现必须覆盖所有子功能，不能遗漏

   第三步：读取功能详细设计（3.5 功能详细设计 对应章节）

   • 逐字读取，提取每个子功能的完整设计：
     • 筛选字段（字段名、控件类型、数据源）
     • 列表字段（列名、字段类型、渲染方式）
     • 表单字段（字段名、控件类型、是否必填、长度限制、默认值、数据源）
     • 特殊交互（动态增删行、联动显隐、级联、文件上传等）
     • 操作反馈（成功/失败提示文案）
     • 业务规则（删除限制、状态联动、唯一性校验、关联关系等）
     • 边界与异常（空数据提示、权限控制、错误提示）
     • 业务逻辑关联（依赖哪些其他模块的数据）

   第四步：读取数据字典（6.1 数据字典，如有）

   • 提取相关枚举值定义（状态值、类型值等）

7. 无 SRS 且非步骤 0 降级模式 → 中止，路由 req-doc Step F（不得继续）

8. 降级模式 → 从 PRD 的功能清单与功能详细描述整理需求（两种结构的定位方式见步骤 0），输出须标注 ⚠ 降级模式：来源 PRD

9. 既无 SRS 也无 PRD → 根据用户描述整理以上信息，并主动询问不明确的功能点

输出格式：

需求理解
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
功能：[功能名称]
菜单层级：[一级菜单] > [二级菜单]
路由路径：[路径]
页面布局：[布局类型]

功能点清单：
  [x] [功能点1，如：列表展示，含字段：xxx | xxx | xxx]
  [x] [功能点2，如：按名称/状态筛选]
  [x] [功能点3，如：新增/编辑弹窗，表单字段：xxx（必填）、xxx（非必填）]
  [x] [功能点4，如：删除，有关联保护]
  [x] [功能点5，如：状态切换，停用后影响登录]
  [x] [功能点N，如：重置密码，确认弹窗，成功提示xxx]
  ...（需求里有多少写多少，不要遗漏）

数据依赖：
  - [依赖的外部数据，如：角色列表（/api/role/list，已存在）]
  - [依赖的外部数据，如：设备分类树（/api/device-category/tree，需新建）]

业务规则：
  - [规则1]
  - [规则2]

边界与异常：
  - [异常1]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[注意] 仅在**单次模式 + 严格交付**下，若有真正不确定的功能点，才列出并等待用户确认。
**标准/快速模式**或需求已从 SRS 完整读出时，**直接继续步骤 2**。
**批量模式下直接继续步骤 2，不等待用户确认。**

步骤 2：规范加载与组件规划

目标：调用 page-spec-loader agent 按需加载规范并规划组件，只读取当前功能实际需要的内容。

执行动作： 使用 Agent 工具，subagent_type: "page-spec-loader"，传入以下 prompt（将占位符替换为实际值）：

PROJECT_PATH：{子项目根目录绝对路径}
WORKSPACE_PATH：{工作区根目录绝对路径，含 .agents/}

功能需求：
{步骤 1 输出的完整需求理解内容}

page-spec-loader agent 定义在 .agents/agents/page-spec-loader.md， 它会自动检测 UI 库、按需加载对应规范、规划组件，返回结构化摘要。

输出格式：

规范加载与组件规划
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[page-spec-loader agent 返回的规范摘要，原样展示]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

2.1 设计令牌对齐（项目有设计稿时必读，没有就跳过）

设计稿把令牌定死在 design-system/。目录存在就必须读，不要另起一套样式：

三条硬规则：

1. 令牌不手抄：引用或生成自 tokens.json，代码里禁止出现魔数色值与 transition: .25s 这类裸数字。
2. 文案照 HANDOFF.md 第 6 节逐字抄（含标点），别自己润色。
3. HANDOFF.md 与 SRS 冲突时取 SRS——本技能的规格真源仍是 SRS（设计稿以 PRD 为主真源，两条链口径不同）； 取了 SRS 就在交付说明里记一行差异，别闷着改。

设计稿不存在时跳过本步，按步骤 2 加载的项目规范执行。

步骤 3：执行计划

目标：列出所有需要创建/修改的文件，确认无遗漏。

执行动作：

1. 根据需求和规范，确定需要创建/修改的文件清单
2. 判断路由归属（属于哪个模块，是否需要新建路由文件）
3. 判断导航是否需要更新（侧边栏/tabbar/顶部导航/路由配置等，取决于项目类型）
4. 判断是否需要新建目录

输出格式：

执行计划
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
功能：[功能名称]

任务清单：
  [ ] 1. [mock 文件路径]          Mock 数据
  [ ] 2. [api 文件路径]           API 接口定义
  [ ] 3. [views 文件路径]         页面组件
  [ ] 4. [router/modules/xxx.ts 路径]  路由模块（如需新建）
  [ ] 5. [router/modules/index.ts 路径] 在 routeModules 中注册路由
  [ ] 6. [locales 路径]                 菜单翻译（zh.json / en.json）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

步骤 4：任务清单生成

目标：用任务清单方式逐文件生成，主线程直接写，不用 Agent（避免重复加载上下文的开销）。

执行规则：

• 先展示完整任务清单，每个任务开始前更新状态为 [进行中]，完成后更新为 ✅
• 按顺序逐文件生成，每个文件写完后立即标记完成
• 所有具体路径、命名规范、代码风格，严格按步骤 2 加载的规范执行
• YOU MUST NOT 跳过步骤 6 验收检查。无论批量还是单次模式，每个功能必须经过 page-reviewer 审查后才能进入步骤 7。
• YOU MUST NOT 合并多个功能一起实现。每次只实现一个功能，完整走完步骤 1-7 后才能开始下一个。

任务清单格式：

生成任务清单
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] 1. mock/xxx.js              Mock 数据（持久化）
[ ] 2. src/api/xxx.ts           API 接口定义
[ ] 3. src/views/Xxx/index.vue  页面组件
[ ] 4. src/router/modules/xxx.ts  路由模块（如需新建）
[ ] 5. src/router/modules/index.ts 在 routeModules 中注册
[ ] 6. src/locales/langs/zh.json + en.json  菜单翻译
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

生成要求：

• Mock 数据：模块级变量持久化，初始数据用真实业务数据，增删改查全部实现
• API 文件：每个导出函数前写 JSDoc 注释
• 页面组件：
  • 严格遵循步骤 2 加载的组件库规范（Ant Design Vue / Vant / Element Plus 等）
  • 移动端页面必须：字体 ≥ 14px、触摸目标 ≥ 44px、有空状态、有加载状态、有底部安全区
  • 只加有实际功能的按钮，不加多余 UI 库自定义属性
  • 安全要求：无硬编码密钥/Token，用户输入渲染前转义（不用 v-html 渲染用户数据），权限控制用 v-if 不渲染（不是 disabled）
  • 代码质量：单函数不超过 80 行，单文件不超过 500 行，异步操作有 loading 状态和 finally 重置，表单关闭时重置
  • 无调试代码：不留 console.log，不留 TODO 注释
• 多功能时（如设备管理含3个子功能），按功能分组依次完成，每组内顺序：mock → api → views

步骤 5：路由与导航

目标：注册路由、更新导航，确保功能可访问。

执行顺序（必须串行，有依赖关系）：

5.1 路由注册

• 按步骤 2 加载的项目规范注册路由（通常为 src/router/modules/ + routeModules；菜单多从路由 meta 自动生成）
• 可能是：新建路由模块文件 → 在入口文件注册；或直接在单一路由文件追加；或文件路由（无需手动注册）

5.2 导航更新

• 按项目类型更新对应导航：
  • Web 管理后台：更新侧边栏菜单文件，按需求文档菜单结构确定归属，若分组不存在则新建
  • 移动端 H5：更新底部 tabbar 配置（如有），或仅通过路由跳转访问（无需更新 tabbar）
  • PC 前台网站：更新顶部导航配置（如有）
  • 无固定导航：跳过此步骤，通过路由直接访问
• 图标/图片资源按项目规范选择

输出格式：

后处理
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
路由：[操作描述]
导航：[操作描述，或"无需更新"]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

步骤 6：验收检查

目标：按交付模式调用 page-reviewer + code-reviewer，确保交付质量。

与 AGENTS.md 铁律的关系：本步骤已调用 code-reviewer（范围见下表），同一功能在本步骤 6 通过后，不得再重复调用 code-reviewer。后续若改动 >30 行或涉及 auth/加密，须重新审查。

6.0 三档审查范围

快速模式主流程轻量 grep（调 agent 前，对生成文件执行，命中即先修再审）：

• console.log / console.debug 残留
• v-html 渲染用户可控数据
• 硬编码 Token / API Key / 密码字符串

6.1 调用 page-reviewer

使用 Agent 工具，subagent_type: "page-reviewer"，传入以下 prompt（将占位符替换为实际值）：

交付模式：{DELIVERY_MODE}

项目路径：{当前项目根目录绝对路径}

功能需求：
{步骤 1 输出的完整需求理解内容}

规范摘要：
{步骤 2 page-spec-loader 返回的规范摘要}

生成的文件列表：
{步骤 4 任务清单中所有已完成的文件路径}

开发服务器端口：{从 vite.config.ts 读取，或默认 3000}

快速模式：prompt 首行 交付模式：快速 时，page-reviewer 只执行维度 2（需求完整性），维1/3/4 输出「⏭ 快速模式跳过」。

6.2 调用 code-reviewer

使用 Agent 工具，subagent_type: "code-reviewer"，传入以下 prompt：

交付模式：{DELIVERY_MODE}

审查以下新生成的文件：

生成的文件列表：
{步骤 4 任务清单中所有已完成的文件路径}

这是 page-generator 生成的页面代码。
只审查上述文件，不审查项目其他文件。

按模式的审查指令追加（写入 prompt 末尾）：

6.3 处理审查结果

标准 / 严格 — 并行调用 6.1 + 6.2（与现行为一致）：

• page-reviewer 有 ❌ → 立即修复 → 重新调用 page-reviewer（严格/标准最多 2 次）
• code-reviewer 有 CRITICAL/HIGH → 必须修复（修复后不必重审，除非改动 >30 行或涉及 auth/加密）
• code-reviewer 有 MEDIUM/LOW → 视情况修复

快速：

• page-reviewer 维2 有 ❌ → 修复 → 重审维2（最多 1 次）
• code-reviewer 有 CRITICAL 或 HIGH 安全类 → 必须修复
• 其余发现 记录但不阻断，不为此重跑 code-reviewer

全部必须修复项处理完，方可进入步骤 7。

步骤 7：更新交付计划

目标：验收通过后，更新项目交付计划，推荐下一步。

执行动作：

1. 检查计划是否存在（先 Glob("issues/kanban.md")；未命中再试存量 Glob("dev/plan/delivery-plan-*.md")、dev/plan/delivery-plan.md）

   • 命中 issues/：走 task-breakdown 的 Step E 流转——把该任务从 in-progress/ 移到 qa/、 改 frontmatter status: qa、追加日志、重算 kanban.md、扫 backlog/ 解除阻塞。不要自己改文件夹
   • 只命中存量交付计划：执行下方步骤 2-4（旧格式，只读兼容）
   • 都不存在：跳过本步骤，提示用户可用 /task-breakdown 拆任务

2. 读取交付计划，找到当前功能对应的条目（按功能名匹配）

3. 更新计划文件：

   • 将对应条目状态改为 ✅
   • 填写完成时间（当天日期，格式 YYYY-MM-DD）
   • 更新总进度表中 Phase 1 的"已完成"计数（+1）、"待实现"计数（-1）
   • 更新文件顶部"最后更新"日期

4. 计算下一个推荐功能：

   • 遍历 Phase 1 所有 ⬜ 条目
   • 找出依赖列中所有 ID 状态均为 ✅ 的条目
   • 优先推荐当前层级（与刚完成功能同层）中满足条件的条目
   • 当前层全部完成后，才推荐下一层的第一个满足条件的条目
   • 同层多个可选时，按 ID 顺序推荐最小的
   • 更新计划文件末尾"当前推荐"章节

5. 判断是否继续执行：

   如果用户触发时说的是"实现全部功能"/"按计划实现所有功能"/"连续实现"等批量指令：

   • 有下一个可执行功能 → 立即在当前会话中直接开始实现下一个功能，从步骤 1 重新执行
   • YOU MUST NOT 停下来问用户"继续吗？"。不询问、不等待、不暂停。直接继续。
   • 唯一允许停止的情况：所有依赖已满足的功能全部完成，或遇到无法自动解决的阻塞
   • 没有下一个可执行功能（依赖未满足或全部完成）→ DELIVERY_MODE=快速 时先执行 7.1，再输出暂停提示

   如果用户触发时说的是单个功能（"实现xxx"）：

   • DELIVERY_MODE=快速 时先执行 7.1
   • 输出完成提示，等待用户下一步指令

7.1 快速模式收口（仅 DELIVERY_MODE=快速）

任务完成（单次）或批量无可继续功能时，宣称完成前执行：

1. 在 {PROJECT_PATH} 运行 npm run build；若无 build script 则 npm run type-check 或 vue-tsc --noEmit
2. 失败 → 修复编译/类型错误后重跑，通过前不得输出「全部完成」
3. 通过 → 在进度摘要中注明「快速模式收口：build/type-check 已通过」

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[完成] {功能名} 已完成，继续执行下一个...

Phase 1 进度：{已完成}/{总数}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

批量模式暂停提示（无可执行功能时）：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[暂停] 当前可执行功能已全部完成

Phase 1 进度：{已完成}/{总数}
等待依赖的功能：
  - {功能名}（等待 {依赖ID} 完成）

继续执行：/page-generator 实现全部功能
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

参考资源索引

规范库位置：{WORKSPACE_PATH}/.agents/knowledge/（多子项目时 WORKSPACE 为仓库根，非 admin/ 内） 项目规范（优先）：{PROJECT_PATH}/README-DEV.md 加载方式：Step 2 通过 page-spec-loader agent 按需加载，不会一次性读取所有文件。 查看目录：调用 Read("{WORKSPACE_PATH}/.agents/knowledge/catalog.json") 获取所有可用 category。

新增 UI 库只需在 {WORKSPACE_PATH}/.agents/knowledge/ui-libs/ 下添加对应目录，page-spec-loader 会自动发现。