@pactor-app/skills 1.24.0 → 1.26.0

package/README.md

@@ -1,39 +1,99 @@
 # @pactor-app/skills
 
-Agent skills for rapidly building [Pactor](https://github.com/426-330/pactor) Server-Driven UI applications. One install, all skills.
+面向 AI Agent 的 [Pactor](https://github.com/426-330/pactor) 开发技能集。技能目录均以 **`pactor-`** 为前缀，与 npm 脚手架包 `create-pactor-app` 区分。
 
-## Install
+本仓库路径：**根目录 `skills/`**（pnpm workspace 包 `@pactor-app/skills`）。
+
+| 目录 / skill id | 用途 |
+| --- | --- |
+| **`pactor-dsl`** | 框架与 `*.page.yaml` DSL 编写 |
+| **`pactor-project`** | 新建工程、`pnpm create pactor-app`、模板选型 |
+| **`pactor-prd`** | PRD / 线框图 → 完整可运行后台（含 `template/`） |
+
+## 在本仓库使用（Cursor / Claude Code）
+
+`pactor-prd` 须连同 **`references/`** 与 **`template/`** 一起可见。
+
+```bash
+mkdir -p .cursor/skills
+ln -sf ../../skills/pactor-dsl .cursor/skills/pactor-dsl
+ln -sf ../../skills/pactor-project .cursor/skills/pactor-project
+ln -sf ../../skills/pactor-prd .cursor/skills/pactor-prd
+```
+
+## 安装（业务仓库）
 
 ```bash
-npm install -D @pactor-app/skills
-# 或
 pnpm add -D @pactor-app/skills
 ```
 
-## Shipped skills
+```bash
+ln -s node_modules/@pactor-app/skills/pactor-dsl ~/.claude/skills/pactor-dsl
+ln -s node_modules/@pactor-app/skills/pactor-project ~/.claude/skills/pactor-project
+ln -s node_modules/@pactor-app/skills/pactor-prd ~/.claude/skills/pactor-prd
+```
+
+---
+
+## 技能一览
+
+| Skill | 典型触发 | 产出 |
+| --- | --- | --- |
+| **`pactor-dsl`** | 写/改 YAML 页面、表达式、动作、组件、主题、Chat | 规范与示例（不生成新仓库） |
+| **`pactor-project`** | 初始化项目、`pnpm create pactor-app` | next-app / spa 或最小 Vite 壳工程 |
+| **`pactor-prd`** | PRD/线框图 → 页面（**新工程**复制 template，**已有工程**线框图增量） | YAML + sitemap/mock/样式 + 验收 |
+
+关系：**`pactor-project`** 搭通用壳；**`pactor-prd`** 从自带 **`template/`** 批量铺页（勿用脚手架空起）；日常改页用 **`pactor-dsl`**。
 
-| Skill | Description |
+---
+
+## `pactor-dsl`
+
+- **入口**：`pactor-dsl/SKILL.md`，深参考 `pactor-dsl/references/dsl-authoring.md`
+- **能力**：DSL 语法；**按清单批量加页**（目录 A/B、`sitemap`/menus、`StaticDslLoader`）— `pactor-dsl/references/page-catalog-and-layout.md`；组件、dataSources、权限、Chat、`pactor validate`
+
+---
+
+## `pactor-project`
+
+- **入口**：`pactor-project/SKILL.md`，`references/templates.md`、`references/minimal-vite.md`
+- **能力**：`pnpm create pactor-app -t next-app|spa`（npm 包名仍为 **`create-pactor-app`**）、`pactor create`、starters 复制、脚手架后检查清单
+
+---
+
+## `pactor-prd`（PRD → 可运行应用）
+
+**版本**：见 `pactor-prd/SKILL.md` frontmatter。
+
+### 能力摘要
+
+- 输入：产品总览 README + 分页 Markdown 线框图（可选原产品仓抽样式）
+- 产出：Next + Pactor 工程 — `sitemap.yaml`、分模块 `*.page.yaml`、http 数据源 + `app/api/data/*` mock、懒加载页面 API、多套皮肤与验收清单
+- **新建工程**：解析 → 复制 `template/` → 按清单建 `yaml/<模块>/<id>.yaml` → mock → 样式 → 全站验收（`page-inventory-and-files.md`）
+- **增量**：摸底现状 → 线框图 **add/update** → 只改相关 yaml、sitemap、mock → 变更页验收 + 回归（`incremental-wireframe-delta.md`）
+- 红线：dataSources 仅 `http`；表单一律 `Form`；列表操作列规范；功能闭环；文案跟线框图
+
+### 捆绑资产
+
+| 路径 | 作用 |
 | --- | --- |
-| `pactor` | Pactor framework guidance: DSL authoring, custom components/actions/services, theming, routing, resources, permissions. See `pactor/SKILL.md`. |
-| `prd-to-app` | Generate a runnable pactor app from PRD documents and markdown wireframes (pages in YAML DSL, http dataSources + mock API routes). See `prd-to-app/SKILL.md`. |
+| `pactor-prd/template/` | 可运行模板工程（common + provider/route 参考模块） |
+| `pactor-prd/references/*.md` | 目录结构、组件映射、页模板、mock、主题、验收清单 |
+
+详见 [`pactor-prd/SKILL.md`](pactor-prd/SKILL.md) 与 [`pactor-prd/template/README.md`](pactor-prd/template/README.md)。
 
-## Usage
+---
 
-Each skill is a self-contained directory (`SKILL.md` + optional `references/` and `template/`). Copy or symlink the skill directory you need into your agent's skill directory (the `references/` subfolder must come along — `SKILL.md` points to it; `prd-to-app` additionally needs its `template/` starter project):
+## 校验与发布
 
 ```bash
-# 例如 Claude Code：~/.claude/skills/<skill-name>/
-ln -s node_modules/@pactor-app/skills/pactor ~/.claude/skills/pactor
-ln -s node_modules/@pactor-app/skills/prd-to-app ~/.claude/skills/prd-to-app
+cd skills && pnpm validate   # 目录名与 SKILL frontmatter、references、template 存在性
 ```
 
-Skills use standard YAML frontmatter (`name`, `description`, `version`) followed by markdown guidance.
-
-## Adding a skill
+## 新增技能
 
-1. Create `<skill-name>/` directly under the package root.
-2. Write `SKILL.md` with standard YAML frontmatter (`name` consistent with the directory name) and add `references/` if the skill needs deep documentation.
-3. The skill ships with the package automatically on next publish.
+1. 在 `skills/` 下新建 **`pactor-<topic>/`**，`SKILL.md` 的 `name` 与目录名一致。  
+2. 更新本 README 表格；`pnpm validate` 通过后发布 `@pactor-app/skills`。
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pactor-app/skills",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "Agent skills for rapidly building pactor Server-Driven UI applications",
   "keywords": [
     "pactor",
@@ -14,13 +14,22 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/426-330/pactor.git",
-    "directory": "packages/skills"
+    "directory": "skills"
   },
-  "homepage": "https://github.com/426-330/pactor/tree/main/packages/skills",
+  "homepage": "https://github.com/426-330/pactor/tree/main/skills",
   "bugs": "https://github.com/426-330/pactor/issues",
   "type": "module",
+  "files": [
+    "README.md",
+    "pactor-dsl",
+    "pactor-project",
+    "pactor-prd",
+    "scripts"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {}
+  "scripts": {
+    "validate": "node scripts/validate-skills.mjs"
+  }
 }

package/{pactor → pactor-dsl}/SKILL.md

@@ -1,18 +1,18 @@
 ---
-name: pactor
+name: pactor-dsl
 description: |
-  Use when working with Pactor — any @pactor-app/* package or the pactor-app meta package. Especially when writing, generating, editing, or debugging Pactor DSL files (*.page.yaml: pages, state, dataSources, components, events, actions, expressions); also when bootstrapping a Pactor app (createPactorApplication, StaticDslLoader), registering custom components/actions/services, building AI chat pages (Chat, ChatShell), configuring themes/layouts/routing/resources/permissions, or using @pactor-app/vite-plugin / @pactor-app/cli (pactor validate).
-version: 1.9.0
+  Use for Pactor DSL and runtime wiring inside an existing app (skill id pactor-dsl). Triggers: write/edit *.page.yaml, add N pages with module folders and sitemap/menus, state, dataSources, events, actions, expressions, custom components/actions/services, themes, permissions, Chat/ChatShell, vite-plugin, pactor validate. NOT for empty-repo scaffold (use pactor-project) or full PRD-to-repo generation (use pactor-prd).
+version: 2.0.0
 ---
 
 # pactor-app
 
 ## When to activate
 
-Activate this skill when the user works with **Pactor** — any `@pactor-app/*` package or the `pactor-app` meta package:
+Activate when the user works with **Pactor DSL or runtime APIs** in a project that already exists:
 
-- Building or extending a Pactor application
-- Using `createPactorApplication`, `@pactor-app/app`, or `StaticDslLoader`
+- Adding or changing **one or many** YAML pages and their **directory + sitemap/menu** relationships
+- Using `createPactorApplication`, `@pactor-app/app`, or `StaticDslLoader` **inside an existing codebase** (new repo → **`pactor-project`** first)
 - Writing YAML/JSON DSL pages, components, events, or actions
 - Creating or registering custom components / actions / services
 - Building AI chat pages (`Chat`, `ChatShell`, `ChatServicesProvider`)
@@ -25,7 +25,7 @@ Activate this skill when the user works with **Pactor** — any `@pactor-app/*`
 ## What you can do with this skill
 
 - Explain Pactor architecture, package boundaries, and dependency rules
-- Guide a user from zero to a running Server-Driven UI app
+- **Batch-create pages** from a page inventory: file paths (`yaml/<module>/<id>.yaml` vs `yaml/pages/*.page.yaml`), `sitemap.yaml` `pages`/`menus`, or `StaticDslLoader.pages` — see `references/page-catalog-and-layout.md`
 - Register custom components, actions, services, and capabilities
 - Design data flow, expressions, events, and action orchestration
 - Configure themes/skins, layouts, routing, resources, and permissions
@@ -54,7 +54,7 @@ Activate this skill when the user works with **Pactor** — any `@pactor-app/*`
 | `packages/cli` | `@pactor-app/cli` | DSL validation, inspection, scaffolding |
 | `packages/app` | `@pactor-app/app` | One-stop composition (`createPactorApplication`) |
 | `packages/pactor` | `pactor-app` | Meta package — depends on all modules, re-exports `@pactor-app/app` |
-| `packages/skills` | `@pactor-app/skills` | Agent skills collection (this skill lives at `pactor/`) |
+| `skills/` | `@pactor-app/skills` | Agent skills collection (this skill lives at `skills/pactor-dsl/`) |
 
 ## Dependency rules
 
@@ -125,7 +125,7 @@ For YAML imports add `@pactor-app/vite-plugin` to `vite.config.ts` and declare `
 
 The built-in shadcn-style UI (`@pactor-app/ui`) registers these DSL component types — reference them by `type` in pages:
 
-- **Page & layout**: `Page`, `Layout` / `Header` / `Sider` / `Content` / `Footer`, `Grid`, `Flex`, `Card`, `Sidebar`
+- **Page & layout**: `Page`, `Layout` / `Header` / `Sider` / `Content` / `Footer`, `Grid`, `Flex`, `Card`, `Sidebar`, `For`（数据驱动循环渲染，行作用域 `${row}`/`${rowIndex}`）
 - **Basic**: `Button`, `Alert`, `Statistic`, `Menu`, `Link`, `Text`, `Typography`, `Icon`
 - **Data**: `Table`, `Tabs`, `DataTable`, `Chart`
 - **Form**: `Form`, `Input`, `NumberInput`, `Select`, `Textarea`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Label`, `Field`, `ChatInput`, `DatePicker`
@@ -143,14 +143,18 @@ Notable behaviors:
 
 Component contracts and per-component props: see the docs site (`docs/src/content/docs/components/`).
 
-## Workflow: authoring DSL pages
+## Workflow: add or edit pages (single or many)
 
-When the user asks to build / generate / edit a Pactor DSL file (`*.page.yaml`):
+When the user asks for **N pages** or a **module tree**:
 
-1. Start from the page skeleton below — never invent the top-level shape.
-2. Declare `state` and `dataSources` first, then compose the `body` tree from registered component `type`s only.
-3. Wire interactions via `events` → standard actions; expressions `${...}` read the scope chain.
-4. Validate before delivering: `npx pactor validate <file>` (from `@pactor-app/cli`; inside this monorepo: `node packages/cli/dist/cli.js validate <file>`). Note: the validator checks schema shape only, not component props semantics — use the reference for correct props.
+1. Read `references/page-catalog-and-layout.md` — pick layout **A** (flat `pages/*.page.yaml`) or **B** (`<module>/<id>.yaml`) to match the project; output a **page inventory table** (id, path, file, menu, hidden).
+2. Create **one YAML file per row**; register all ids in `sitemap.yaml` (SitemapApp) or `StaticDslLoader` + `bootstrap.menus`.
+3. Per file: use the skeleton below — never invent the top-level shape; declare `state` / `dataSources`, then `body`; wire `events` → actions.
+4. Validate: `npx pactor validate '<glob>'` (`@pactor-app/cli`). Monorepo: `node packages/cli/dist/cli.js validate <file>`. Schema only — props见 `references/dsl-authoring.md`.
+
+When editing a **single** existing page, skip step 1 unless menus/paths change.
+
+## Workflow: authoring DSL pages (single-file skeleton)
 
 ```yaml
 dsl: '1.0'                      # required, DSL spec version
@@ -181,7 +185,7 @@ Facts that are NOT guessable and must be followed:
 - `navigate` takes `to`; `message` takes `text` + `messageType` (a `type` key in action `params` disables expression evaluation).
 - Query linkage = `onSubmit: [setState, reload]`; the data source's `params` referencing `${state.x}` pick up new values on reload.
 
-**Full DSL grammar, action catalog, expression/scopes tables, and copy-paste recipes: read `references/dsl-authoring.md` bundled next to this SKILL.md — read it before writing any non-trivial page.** In the monorepo, per-component props live in `docs/src/content/docs/components/` and the exhaustive DSL reference in `docs/src/content/docs/reference/dsl.md`.
+**Full DSL grammar, action catalog, expression/scopes tables, and copy-paste recipes: read `references/dsl-authoring.md`.** Page count, folders, and sitemap: **`references/page-catalog-and-layout.md`**. Component props: bundled dsl-authoring + [Pactor docs](https://github.com/426-330/pactor/tree/main/docs/src/content/docs/components) when online.
 
 ## Workflow: custom component
 
@@ -355,19 +359,15 @@ pnpm pactor create my-app
 - **Do not** put a `type` key in action `params` (see the events workflow pitfall).
 - **Do not** expect DslNode slots (sidebar / toolbar / inspector / …) to render outside a page runtime; in pure React hosts pass ReactNode instead.
 
-## References
+## References (bundled — works from npm install)
+
+- **Page inventory & directories**: `references/page-catalog-and-layout.md`
+- **DSL grammar & recipes**: `references/dsl-authoring.md`
+- **New repository**: sibling `pactor-project` (`../pactor-project/SKILL.md`)
+- **PRD full-site generation**: sibling `pactor-prd` (`../pactor-prd/SKILL.md`)
 
-- **DSL authoring reference (bundled)**: `references/dsl-authoring.md` — full page grammar, dataSources, expressions/scopes, action catalog, recipes, common mistakes. Read it before writing DSL.
-- Framework design specification: `docs/src/content/docs/framework-design.md`
-- Quick start: `docs/src/content/docs/guides/getting-started.md`
-- @pactor-app/app docs: `docs/src/content/docs/packages/app.md`
-- @pactor-app/chat docs: `docs/src/content/docs/packages/chat.md`
-- Component reference: `docs/src/content/docs/components/`
-- Example projects:
-  - `examples/vite-starter` — minimal starter
-  - `examples/admin` — shadcn admin dashboard with skin settings
-  - `examples/chat` — AI chat workspace (pactor-app assembly)
+Online (optional): [getting started](https://github.com/426-330/pactor/blob/main/docs/src/content/docs/guides/getting-started.md), [DSL reference](https://github.com/426-330/pactor/blob/main/docs/src/content/docs/reference/dsl.md), [framework design](https://github.com/426-330/pactor/blob/main/docs/src/content/docs/framework-design.md).
 
 ## How to use this skill
 
-This skill is maintained as `packages/skills/pactor/SKILL.md` together with `references/dsl-authoring.md`. AI agents can copy or link the whole `packages/skills/pactor` directory into their skill directory to provide contextual guidance when reading or editing Pactor projects.
+This skill is maintained as `skills/pactor-dsl/SKILL.md` together with `references/dsl-authoring.md`. AI agents can copy or link the whole `skills/pactor-dsl` directory into their skill directory to provide contextual guidance when reading or editing Pactor projects.

package/{pactor → pactor-dsl}/references/dsl-authoring.md

@@ -165,7 +165,7 @@ Global scope keys:
 | `actions` | results of named actions (by `id`) | `${actions.editResult.success}` |
 | `locale` / `t` | current locale / translate fn | `${t('menu.home')}` |
 
-Local scope keys (only where produced): `event` (event payload), `row` / `rowIndex` (Table `cell` templates), `parent` (parent page snapshot inside overlays).
+Local scope keys (only where produced): `event` (event payload), `row` / `rowIndex` (Table `cell` templates and `For` item templates), `parent` (parent page snapshot inside overlays).
 
 ## 6. Events and actions
 

package/pactor-dsl/references/page-catalog-and-layout.md

@@ -0,0 +1,67 @@
+# 页面清单、目录结构与 sitemap 关系
+
+在**已有 Pactor 工程**内按需求新增 **任意数量** 页面时，先产出「页面清单」，再按工程采用的 **YAML 布局模式** 创建文件并注册 `sitemap`（或 `StaticDslLoader`）。
+
+> 新建空仓库请用 **`pactor-project`**；从 PRD 批量铺全站请用 **`pactor-prd`**。本参考只覆盖「加页 / 改目录」。
+
+## 两种 YAML 磁盘布局（二选一，勿混用）
+
+| 模式 | 适用 | 路径规则 | 页面 id |
+| --- | --- | --- | --- |
+| **A. 演示平铺** | 官方 `pnpm create pactor-app -t next-app` / `starters/next-app-starter`；页面 ≤5、模块单一 | `src/server/yaml/pages/<id>.page.yaml` | `page.id` = 文件名去掉 `.page.yaml`（如 `home.page.yaml` → `home`） |
+| **B. 模块分目录** | `pactor-prd` 模板及多模块后台（模块 ≥2 或页面 >5） | `src/server/yaml/<模块>/<id>.yaml` | `page.id` = 文件名去掉 `.yaml`（**无** `.page` 后缀） |
+
+`src/server/sitemap.ts`（或等价加载器）递归扫描 `yaml/` 子目录建立 **id → 文件路径** 索引；**id 全局唯一**，且与 `sitemap.yaml` 里 `pages[].id`、`menus[].pageId` 一致。
+
+从模式 A 扩到模式 B：新建模块子目录，把新页放进 `<模块>/`；旧页可逐步迁移，同一时刻不要两个文件共用一个 id。
+
+## 页面清单（Agent 先输出，再写文件）
+
+对用户给的 N 个页面，先填表（N 任意）：
+
+| page id | 模块目录 | 文件路径（相对 `src/server/yaml/`） | path | 菜单分组 | 进菜单? | layout | permission |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| user-list | user | `user/user-list.yaml` 或 `pages/user-list.page.yaml` | `/users` | 系统管理 | 是 | admin | user:view |
+| user-edit | user | `user/user-edit.yaml` | `/users/:id/edit` | — | 否 hidden | admin | user:edit |
+
+约定：
+
+- **模块目录**：kebab-case 英文域（`user`、`order`、`report`），与 PRD 模块树对齐；模式 A 可填 `pages` 或 `-`。
+- **详情 / 编辑 / 新建**：`hidden: true` + `activeMenu` 指向列表菜单项 id；path 用 `:param` 与框架 Path Matcher 一致。
+- **page.id**：全局唯一 kebab-case；= DSL 内 `page.id` = 文件名（模式 B）。
+
+## 创建步骤（按数量批量执行）
+
+1. **定布局模式**：看工程现有 `yaml/` 是 `pages/*.page.yaml` 还是 `<模块>/*.yaml`，新页跟随现状；大规模新增优先模式 B。
+2. **按清单建文件**：每个页面一个 YAML；从 `references/dsl-authoring.md` 骨架 + 列表/详情/表单模板（`pactor-prd/references/page-templates.md` 可复用结构，数据源类型按工程约定 http 或 service）。
+3. **改 `sitemap.yaml`**（next-app / SitemapApp）：
+   - `pages` 数组：每个 id 一条，`lazy: true`（推荐懒加载）
+   - `menus`：group / page 树与模块一致；`pageId` 指向清单 id
+4. **StaticDslLoader 工程**（如 `examples/vite-starter`）：
+   - `import` 每个 yaml，`loader` 的 `pages: { [id]: doc }` 与 `bootstrap.menus` 的 `pageId` 与清单一致
+5. **校验**：`npx pactor validate 'path/to/**/*.yaml'`（或 monorepo 内 `node packages/cli/dist/cli.js validate …`）
+6. **重启 dev**：服务端加载 yaml 的 Next 模板常需重启 dev server 后才能在浏览器看到新页
+
+## sitemap 片段示例（模式 B，两页）
+
+```yaml
+pages:
+  - { id: user-list, path: /users, title: 用户列表, version: 1, lazy: true }
+  - { id: user-edit, path: /users/:id/edit, title: 编辑用户, version: 1, lazy: true }
+
+menus:
+  - id: system
+    type: group
+    title: 系统管理
+    icon: settings
+    children:
+      - { id: nav-users, type: page, pageId: user-list, title: 用户 }
+      - { id: nav-user-edit, type: page, pageId: user-edit, title: 编辑用户, hidden: true, activeMenu: nav-users }
+```
+
+## 与 `pactor-prd` 的分工
+
+| 场景 | 使用 |
+| --- | --- |
+| 已有工程加 1～N 页、改菜单 | **本参考** + `pactor-dsl` |
+| 从 PRD 目录一次性生成全站文件 + mock + 验收 | **`pactor-prd`** + `references/page-inventory-and-files.md` |

package/pactor-prd/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pactor-prd
+description: |
+  Use when PRD or markdown wireframes drive Pactor YAML pages (skill id pactor-prd). Greenfield: copy template/ into a new repo. Incremental: in an existing Pactor project, add or update pages from new/changed wireframe files (DSL, sitemap, menus, mock API, styles). Triggers: pactor-prd, prd-to-app, 线框图增量, 已有项目加页面, PRD 更新页面.
+version: 1.3.0
+---
+
+# PRD → YAML 页面应用生成
+
+把「产品文档 + Markdown 线框图」落到 **YAML 页面 + sitemap/mock/样式**；支持 **两种模式**（先选型再执行）：
+
+| 模式 | 何时用 | 脚手架 |
+| --- | --- | --- |
+| **新建工程** | 空目录 / 新仓库 / 首次从 PRD 出整站 | 复制 `template/` |
+| **增量（已有工程）** | 仓库已是 Pactor 后台，线框图新增或调整 | **不复制 template**；按 delta 改文件 |
+
+## 输入要求
+
+- PRD/线框图：总览 README（模块 × 页面 × 优先级）+ 分页线框 markdown（ASCII + 区域 + 交互）
+- **增量**：可只提供 **变更的线框图文件** 列表（或 PRD 目录 + 标明 diff 范围）
+- 原产品代码仓（可选）：抽设计令牌、自定义 CSS、交互
+- 目标：空目录（新建工程）或已有工程根目录（增量）
+
+输入格式不同时，先归纳「模块 → 页面 → 区域 → 交互」，再套用流程。
+
+## 红线（必须遵守）
+
+1. **dataSources 一律 `type: http`**，指向 `/api/data/...`，不写 `type: service`，便于后续替换真实接口
+2. **布局与间距以样板页为准**：新建工程时以 `template/` 同类页为准；**增量时以目标工程内同模块/同类型页**为准。线框图只提取结构与功能，不逐像素还原 ASCII
+3. **样式与原产品一致**：主题令牌（含深浅色）、自定义 CSS（如登录页）、换肤入口全部移植对齐，见 `references/theme-and-style.md`
+4. **功能与原产品一致**：线框图描述的筛选/搜索/跳转/弹窗/提交等交互必须经 events/actions 闭环可用，禁止只画静态骨架；错误分支（校验失败提示等）也要实现
+5. **表单一律用 `Form` 组件**：凡是一组「字段 + 校验 + 提交」的表单——独立表单页、页面内嵌的配置面板（如树/列表右侧的编辑表单）、弹窗/抽屉表单、**搜索栏（关键词 + 查询/重置 的筛选区，用 `Form layout: inline`）**——都必须用 `Form` 包裹，字段经 `props.name` 绑定，校验用字段级 `rules`（required + message），提交用 `submit: true` 的 Button 触发 `onSubmit`；**禁止**散放 `Input`/`Select` + `setState` 攒草稿 + `if` 动作手写校验。回填联动（如点击列表/树节点填充表单）用 `form.setValues` 动作，不要绑 `${state.x}` 到字段 value；即点即生效的 ChipFilter 快筛行没有提交语义，不属于表单
+6. **列表页操作列规范**：操作列按钮样式统一 `Button variant: link`；「编辑」与「新建」指向同一个表单（同一路由页或同一弹窗），唯一区别是编辑以行数据预填（路由页 `initialValues: ${data.detail}`，弹窗/内嵌面板 `form.setValues`）
+7. **文案以线框图为准**：标题、按钮、空态文案逐字取自线框图/PRD
+8. DSL 语法细节（组件 props、表达式、动作）以 `pactor-dsl` skill 与 packages/ui 当前导出为准，本 skill 只约定流程与产出物
+
+## 流程总览
+
+```text
+选型 → 1 解析 → 2 脚手架（仅新建工程）→ 3 页面 → 4 mock → 5 样式 → 6 验收
+增量：2 改为「摸底」；1/3 只处理 delta；6 变更页全验 + 少量回归
+```
+
+详细增量步骤：**`references/incremental-wireframe-delta.md`**。
+
+### 1. 输入解析
+
+- 读 README / 变更线框图：模块树、页面 id（kebab-case）、path、菜单、P0/P1/P2
+- 逐页读线框：页面类型、区域、字段、交互
+- **新建工程**：输出全量 **页面清单表**（`references/page-inventory-and-files.md`）
+- **增量**：扫描工程现状清单 + 输出 **delta 表**（add / update / deprecate，`references/incremental-wireframe-delta.md`）；P2 不建文件
+
+### 2. 脚手架
+
+**新建工程**
+
+- **整体复制 `template/`** 为新项目起点；不要用 `pnpm create pactor-app` 替代
+- 工程名：README 产品名 → kebab-case 英文名，创建前确认一次
+- `pnpm install` + dev 验证；核对 `references/project-structure.md`
+- 参考模块 provider/route 作样板；**全站生成完成后删除**参考模块及 mock
+
+**增量**
+
+- **跳过复制 template**；执行 `incremental-wireframe-delta.md` 的「摸底」
+- 确认 yaml 布局模式 A/B 与 `sitemap`、data API 接线完整；缺则先补壳或转新建工程
+
+### 3. 页面生成（按清单或 delta 改文件）
+
+- **新建工程**：清单一行 = 一个文件 `yaml/<模块>/<page-id>.yaml`（或工程既定 A/B 规则）；`mkdir` 模块目录；N = P0/P1 行数
+- **增量**：仅 **add** 新建文件；**update** 改已有 yaml；**deprecate** 删文件并改 sitemap（须用户确认）
+- 校验见 `page-inventory-and-files.md`（全量）或 `incremental-wireframe-delta.md`（增量）
+- 按 `references/component-mapping.md` 映射组件；按 `references/page-templates.md` 选列表/详情/表单模板；表单一律 `Form` 包裹
+- 同步更新 `sitemap.yaml` 的 `pages` + `menus`（hidden 详情/编辑带 `activeMenu`）
+- 每页 dataSources 全部 `type: http`；交互 events + actions 闭环
+
+### 4. mock 服务
+
+- 按 `references/mock-data-routes.md` 注册/更新路由表与 `src/pactor/mocks/`；**增量只动变更页涉及的接口**
+
+### 5. 样式移植
+
+- 按 `references/theme-and-style.md`；**增量**仅受影响页面/令牌（新建工程做全站对齐）
+
+### 6. 功能与视觉验收（必经，不可跳过）
+
+- `references/acceptance-checklist.md`：**新建工程**逐页全站验收；**增量**对 **所有变更页** 全项验收 + **至少 1～2 个未改页回归**（菜单可达、控制台无新增 error）
+
+## references 索引
+
+| 文件 | 何时加载 |
+| --- | --- |
+| `template/` | 阶段 2 **仅新建工程**：复制为新工程起点；增量勿用 |
+| `references/incremental-wireframe-delta.md` | **已有工程**：线框图 add/update/deprecate、改 sitemap/mock/样式 |
+| `references/project-structure.md` | 阶段 2：目录结构约定与 sitemap.yaml 骨架 |
+| `references/component-mapping.md` | 阶段 3：线框图区域 → pactor 组件映射 |
+| `references/page-templates.md` | 阶段 3：列表/详情/表单页 yaml 模板 |
+| `references/mock-data-routes.md` | 阶段 4：mock 路由表模板与命名约定 |
+| `references/theme-and-style.md` | 阶段 5：主题令牌提取、皮肤、自定义 CSS、换肤 |
+| `references/acceptance-checklist.md` | 阶段 6：验收清单与结果输出格式 |
+| `references/page-inventory-and-files.md` | 阶段 1–3：清单列 → 目录与文件批量创建、与 sitemap 对齐 |
+
+## Sibling skills
+
+- **`pactor-dsl`** — 无线框图的单页/清单加页；**有线框图 + mock/sitemap 联动**仍用本 skill 增量模式
+- **`pactor-project`** — `pnpm create pactor-app` 空壳（**不要**用其替代本 skill 的 template 复制）

package/{prd-to-app → pactor-prd}/references/acceptance-checklist.md

@@ -1,6 +1,8 @@
 # 验收清单
 
-验收是必经阶段。启动 dev server，用浏览器（playwright-cli / WebBridge 均可）逐页执行，输出验收结果表。**全部通过才算完成；任何一项不通过，修复后重验该页全部项。**
+验收是必经阶段。启动 dev server，用浏览器（playwright-cli / WebBridge 均可）执行，输出验收结果表。**全部通过才算完成；任何一项不通过，修复后重验该页全部项。**
+
+**增量（已有工程）**：对 **本次变更的每个 page id** 跑下方「每页检查项」；另抽 **1～2 个未改动的核心页**（如首页、任一列表）做路由可达 + 控制台无新增 error，作为回归。
 
 ## 每页检查项
 

package/pactor-prd/references/incremental-wireframe-delta.md

@@ -0,0 +1,76 @@
+# 已有工程：线框图增量（新增 / 调整）
+
+当目标已是 Pactor 工程（由 `pactor-prd/template`、或已对齐 PRD 约定的 next-app 扩展仓）时，**不要**再复制 `template/`。根据 **新增或变更** 的线框图 markdown（及 README 增量）更新 DSL 与配套文件。
+
+## 适用条件
+
+工程至少具备：
+
+- `src/server/yaml/sitemap.yaml`（或等价 sitemap 源）
+- 页面 yaml 目录（**模式 B** `yaml/<模块>/<id>.yaml` 或 **模式 A** `yaml/pages/*.page.yaml` — 见 `pactor-dsl/references/page-catalog-and-layout.md`）
+- PRD 风格 mock：`app/api/data/[...parts]/route.ts` + `src/pactor/mocks/`（若工程仍用 `type: service`，增量页 **仍须 http**，并迁移或仅对新页遵守红线）
+
+不满足时：先 **`pactor-project`** 或 **新建工程 `pactor-prd` 模式** 搭壳，再回来做增量。
+
+## 0. 摸底（只读）
+
+1. 扫描 `src/server/yaml/**`（排除 `sitemap.yaml`），建立 **现状清单**：`page id`、文件路径、`sitemap.pages` 的 path、`menus` 引用。
+2. 确认 `pageEndpoint` / 懒加载 API 路径（`src/pactor/config.ts`）与 `app/api/public/pages/[id]` 存在。
+3. 读工程内 **同类页** 一份（同模块列表页或表单页）作为排版样板（增量时红线「以模板为准」= **以本工程同类页为准**）。
+
+## 1. 解析线框图增量
+
+输入可以是：
+
+- 仅 **新增/修改** 的线框图 `.md` 文件列表；或
+- PRD 目录 + 用户标明「只处理这些文件」
+
+对 **每个** 线框图文件输出 delta 行：
+
+| 变更 | page id | 模块 | 文件路径 | path | 菜单 | 说明 |
+| --- | --- | --- | --- | --- | --- | --- |
+| add | order-list | order | yaml/order/order-list.yaml | /orders | 进菜单 | 新列表 |
+| update | order-list | order | （同上） | /orders | | 线框图改筛选区 |
+| add | order-edit | order | yaml/order/order-edit.yaml | /orders/:id/edit | hidden | 新编辑页 |
+| rename-id | order-detail → order-view | … | 需迁文件 + 改 sitemap | | | 少见，须用户确认 |
+| deprecate | old-page | | | | 下架 | 用户确认后删 yaml + 从 sitemap 移除 |
+
+**update** 不臆造新 page id；**deprecate** 必须用户明确，避免误删。
+
+## 2. 改哪些文件（按变更类型）
+
+| 变更 | 动作 |
+| --- | --- |
+| **add 页面** | `mkdir` 模块目录；新建 yaml；`sitemap.yaml` 增加 `pages` + `menus`；mock 路由表 + mocks 文件 |
+| **update 页面** | 改对应 yaml（结构/字段/交互/文案）；若 path 或 id 变则同步 `sitemap.yaml`、检查 `router.push` / 菜单 `pageId` |
+| **update 仅文案/字段** | 只改 yaml；mock 字段变更时改 `mocks/*` 与路由返回形状 |
+| **add 数据源** | yaml 内 `dataSources` + `app/api/data/...` 注册 + mock handler |
+| **样式** | 仅当线框图要求新页面级样式时改 `globals.css` / `login.css` / 皮肤；见 `theme-and-style.md` |
+| **deprecate** | 删 yaml；从 `pages`/`menus` 移除；删 mock 路由项；全局搜 `pageId` / 路径引用 |
+
+**禁止**：为增量在仓库根再复制一份 `template/` 覆盖工程。
+
+## 3. 与全量流程的差异
+
+| 阶段 | 新建工程 | 增量（已有工程） |
+| --- | --- | --- |
+| 脚手架 | 复制 `template/` | **跳过**；仅摸底 |
+| 页面 | 全量清单 N 文件 | 仅 **delta** 行对应文件 |
+| mock | 全表扩展 | 只加/改涉及接口 |
+| 样式 | 全站移植 | 仅受影响页面/令牌 |
+| 验收 | 全站清单 | **变更页全量验** + **抽 1～2 条旧页回归**（见 acceptance-checklist） |
+
+## 4. 交叉检查（增量）
+
+```text
+对每个 add：存在 yaml 且 sitemap.pages 含 id 且 menus 正确
+对每个 update：page.id 未变（除非走 rename 流程）且 validate 通过
+mock：变更页涉及的所有 http 路径在 Network 200
+```
+
+`npx pactor validate` 仅覆盖改动的 yaml 路径。
+
+## 5. 与 `pactor-dsl` 的分工
+
+- **单页小改**、无线框图、只改 DSL 语法：可用 **`pactor-dsl`**。
+- **线框图驱动**、含 mock/sitemap/多页联动：用 **本增量流程**（仍属 `pactor-prd`）。

package/pactor-prd/references/page-inventory-and-files.md

@@ -0,0 +1,65 @@
+# 按目录批量生成 DSL 文件与菜单关系
+
+`pactor-prd` 在阶段 1 产出 **页面清单** 后，阶段 3 必须 **按清单逐文件创建** YAML，保证「磁盘目录 ↔ 模块 ↔ sitemap ↔ 菜单」一致。
+
+## 清单 → 文件映射（核心规则）
+
+**一律采用模块分目录（模式 B）**：
+
+```text
+src/server/yaml/
+  sitemap.yaml
+  common/           # 可选：login、dashboard
+  <模块>/           # PRD 模块，kebab-case
+    <page-id>.yaml  # 一页一文件；page-id = 清单 id = page.id
+```
+
+| 清单列 | 写入位置 |
+| --- | --- |
+| 模块 `user` | 目录 `yaml/user/` |
+| 页面 id `user-list` | 文件 `yaml/user/user-list.yaml` |
+| 路由 `/users` | `sitemap.yaml` → `pages[].path` |
+| 菜单「用户」 | `menus` → `pageId: user-list` |
+
+**禁止**：清单 10 页只写 1 个合并 yaml；**禁止** id 与文件名不一致。
+
+## 批量创建流程
+
+1. **按模块建目录**：对清单中每个 distinct `<模块>` 执行 `mkdir -p src/server/yaml/<模块>`（生成时保持树形与 PRD 模块树一致）。
+2. **按行建文件**：清单每一行 → 一个 `yaml/<模块>/<id>.yaml`；内容类型从线框图判定（列表 / 详情 / 表单），套 `references/page-templates.md`。
+3. **一次更新 sitemap**：
+   - `pages`：清单中每一页一条（含 hidden 的详情/编辑）
+   - `menus`：仅「进导航」的页进 group；hidden 页带 `activeMenu`
+4. **mock 批量注册**：按 `references/mock-data-routes.md`，每个 http 数据源在 `app/api/data/[...parts]/route.ts` 路由表增加一项；`src/pactor/mocks/` 按域拆分文件。
+5. **交叉检查**（生成后必做）：
+
+```text
+清单行数 N
+  = yaml 业务页文件数（不含 sitemap.yaml）
+  = sitemap.pages 中业务页条数（含 hidden）
+  且 ∀ id: 存在文件 yaml/<模块>/<id>.yaml 且 DSL 内 page.id === id
+```
+
+## 清单模板（复制填充）
+
+```markdown
+| # | 模块目录 | page id | 文件路径 | path | 类型 | 菜单 | hidden | activeMenu | P |
+| 1 | provider | provider-list | yaml/provider/provider-list.yaml | /providers | 列表 | 是 | | | P0 |
+| 2 | provider | provider-edit | yaml/provider/provider-edit.yaml | /providers/:id/edit | 表单 | 否 | true | nav-providers | P0 |
+```
+
+- **P**：P0 必须生成；P2 只登记不建文件（在 SKILL 阶段 1 已约定）。
+- **类型**：决定用 page-templates 哪一节；同一业务域列表+编辑共用表单规范（见 SKILL 红线）。
+
+## 参考模块（模板内）
+
+复制 `pactor-prd/template/` 后，保留 `yaml/provider/`、`yaml/route/` 作写法样本；新模块 **照同样目录深度** 新增；全站生成完成后删除参考模块及其 mock 路由项。
+
+## 已有工程（增量）
+
+线框图只增改部分页面时：**不要**复制 `template/`。走 **`incremental-wireframe-delta.md`**（delta 表、只改涉及文件、验收变更页 + 回归）。
+
+## 与 `pactor-dsl` 的衔接
+
+单页 DSL 语法、组件 props、表达式：读 **`pactor-dsl`** + `pactor-dsl/references/dsl-authoring.md`。  
+本文件约束 **全量** 文件与 sitemap 对齐；增量见 **`incremental-wireframe-delta.md`**。

package/{prd-to-app → pactor-prd}/references/page-templates.md

@@ -1,6 +1,6 @@
 # 页面 YAML 模板
 
-三类常用页面模板。占位符：`{{kebab-id}}` 页面 id、`{{页面标题}}`、`{{模块名}}`、`{{resource}}` 数据接口名（单段，见 mock-data-routes.md）。DSL 语法细节以 pactor skill 与 packages/ui 当前导出为准。
+三类常用页面模板。占位符：`{{kebab-id}}` 页面 id、`{{页面标题}}`、`{{模块名}}`、`{{resource}}` 数据接口名（单段，见 mock-data-routes.md）。DSL 语法细节以 `pactor-dsl` skill 与 packages/ui 当前导出为准。
 
 ## 列表页（筛选 + 表格/卡片 + 操作列）
 

package/{prd-to-app → pactor-prd}/references/project-structure.md

@@ -72,7 +72,7 @@ layouts:
 
 - 页面按 PRD 模块树分目录：`yaml/<模块>/<id>.yaml`（如 `yaml/user/user-list.yaml`）；模块目录名用 kebab-case 英文域，按 PRD 模块树划分（如 user / order / report）
 - 页面 id kebab-case，= 文件名（不含 `.yaml`）；`pages:` 注册、`menus:` 引用、文件名三者一致
-- 模板自带的 `yaml/pages/*.page.yaml` 平铺写法仅适合页面极少的 demo；模块 ≥2 或页面 >5 时一律按模块分目录（模板目录可整体替换）
+- 模板自带的 `yaml/pages/*.page.yaml` 平铺写法仅适合页面极少的 demo；模块 ≥2 或页面 >5 时一律按模块分目录（模板目录可整体替换）。批量建文件与清单对齐见 **`page-inventory-and-files.md`**；与官方脚手架平铺模式对比见 **`pactor-dsl/references/page-catalog-and-layout.md`**
 - 列表/详情/编辑成组路径：`/projects`、`/projects/:code`、`/projects/:code/edit`、`/projects/new`
 - 详情/编辑页不进菜单（`hidden: true`），用 `activeMenu` 保持列表菜单高亮
 - 菜单图标仅一级菜单配置（目录 group 与「首页」这类独立页面项都要配），用 pactor Icon 白名单 kebab-case 名；二级及以下菜单项一律不配图标