@pactor-app/skills 1.25.0 → 1.26.0

package/pactor-project/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: pactor-project
+description: |
+  Use when initializing or scaffolding a new Pactor application — empty repo, greenfield project, or "how do I start" (skill id pactor-project). Triggers: pactor-project, create-pactor-app, pnpm create pactor-app, pactor create, 初始化项目, 创建脚手架, 新建 Pactor 工程, next-app/spa starter, copy starters/. Guides template choice (next-app vs spa vs minimal Vite), exact CLI commands, post-scaffold verification, and when to use pactor-prd or manual StaticDslLoader instead.
+version: 1.1.0
+---
+
+# Pactor 工程初始化与脚手架
+
+帮助 Agent **从零创建可运行的 Pactor 业务工程**：选对模板、执行官方脚手架、安装依赖、启动 dev，并说明生成后的目录该改哪里。
+
+## When to activate
+
+- 用户要**新建 / 初始化** Pactor 项目，或问「怎么搭架子」
+- 提到 `pnpm create pactor-app`、`create-pactor-app`、`pactor create`
+- 要在现有空目录生成工程，或从 monorepo 的 `starters/` 复制模板
+- 在 **next-app（全栈）** 与 **spa（纯前端）** 之间选型
+- 用户**不是**从 PRD 批量生成多模块后台（那种场景用 `pactor-prd` skill）
+
+## What this skill does NOT cover
+
+| 场景 | 使用 |
+| --- | --- |
+| 写/改 `*.page.yaml`、组件 props、动作编排 | `pactor-dsl` skill + `pactor-dsl/references/dsl-authoring.md` |
+| 根据 PRD / 线框图生成整站页面与 mock API | `pactor-prd` skill（复制其 `template/`，不用本 skill 的 create 命令） |
+| 在已有 Vite 里只加几行 `createPactorApplication` | `pactor-dsl` skill「Quick start」+ 文档 manual-setup |
+
+## 选型（先问清楚再执行）
+
+```text
+需要自带 mock API + 登录 + sitemap 端点？
+  ├─ 是 → next-app（Next.js 全栈，dev :9011）
+  └─ 否，只要浏览器壳，接口已有或另起服务？
+        ├─ 接口形态已是 sitemap + /pages/{id} → spa（Vite，dev :9012，baseUrl 指后端）
+        └─ 单页原型 / 教学最小集 → pactor create（Vite + StaticDslLoader，见 references/minimal-vite.md）
+```
+
+**默认推荐**：不确定时用 **next-app**（与 `create-pactor-app` 默认模板一致）。
+
+## 标准流程（Agent 执行清单）
+
+1. **确认目标路径**：目录不存在或为空；脚手架**拒绝覆盖非空目录**（退出码 2）。
+2. **确认包管理器**：优先 `pnpm`（模板带 lockfile）；用户坚持用 npm/yarn 可改，但需说明 lock 差异。
+3. **运行脚手架**（在目标父目录执行）：
+
+```bash
+pnpm create pactor-app <dir-name>              # TTY 交互选模板；非 TTY 默认 next-app
+pnpm create pactor-app <dir-name> -t next-app  # Next.js 全栈 + mock API
+pnpm create pactor-app <dir-name> -t spa       # Vite SPA + SitemapApp
+```
+
+等价：`npx create-pactor-app <dir-name> [-t next-app|spa]`。
+
+4. **安装与启动**：
+
+```bash
+cd <dir-name>
+pnpm install
+pnpm dev
+```
+
+5. **验收**：
+   - **next-app**：打开 http://localhost:9011 ，用 `admin` / `pactor123` 登录
+   - **spa**：先在同一机器启动 next-app 或兼容的 sitemap 服务（:9011），再开 http://localhost:9012
+6. **告诉用户改哪里**：见 `references/templates.md` 中的「生成后首要修改点」。
+
+## 备选入口
+
+### `@pactor-app/cli` 最小 Vite 工程
+
+仅生成 **StaticDslLoader + 单页 YAML** 的瘦项目（无 sitemap、无 Next）：
+
+```bash
+pnpm add -D @pactor-app/cli
+pnpm pactor create my-app          # 模板 id 目前仅 app
+cd my-app && pnpm install && pnpm dev
+```
+
+细节见 `references/minimal-vite.md`。
+
+### 在 Pactor monorepo 内
+
+不跑 npm 发布包时，可直接复制源码模板（与 `packages/create-app/templates` 同步）：
+
+```bash
+cp -R starters/next-app-starter ../my-app    # 或 spa-starter
+cd ../my-app && pnpm install && pnpm dev
+```
+
+改框架包后若示例依赖 workspace `dist`，在 monorepo 根目录先 `pnpm build`。
+
+### 同步模板到 create-app
+
+维护者更新 `starters/*` 后，在 `packages/create-app` 执行 `pnpm sync-templates`（再发布 `create-pactor-app`）。
+
+## 红线
+
+1. **不要**对非空目录强行 `scaffold`；应新建子目录或让用户清空/换路径。
+2. **不要**在 spa 单独开发时忘记后端：默认 `apiBaseUrl` 指向 `http://localhost:9011`。
+3. **不要**把 PRD 整站生成与脚手架混用；PRD 流程从 `pactor-prd/template/` 复制。
+4. 使用内置 UI 时，入口必须 `import '@pactor-app/ui/styles.css'`（模板已包含；手动接入时勿漏）。
+5. 生成后加页：官方 next-app 默认 **`src/server/yaml/pages/*.page.yaml`**（平铺）；模块多或页面 >5 时迁到 **`yaml/<模块>/<id>.yaml`**，规则见 `pactor-dsl/references/page-catalog-and-layout.md`。spa 由远端 sitemap 声明 pageId，yaml 通常在 API 侧。
+
+## 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| 目标目录非空 | 换空目录名或新建文件夹 |
+| spa 白屏 / 接口失败 | 确认 :9011 sitemap 已启动、`src/pactor/config.ts` 的 `apiBaseUrl` 正确 |
+| CORS | spa 模板用 `createHttpHooks`；跨域需后端允许来源 |
+| 想改 dev 端口 | 改各模板 `package.json` scripts 或框架 dev 配置（next/vite） |
+
+更多结构说明：`references/templates.md`、`references/minimal-vite.md`。
+
+## References
+
+- `references/templates.md` — next-app / spa 目录树、端口、演示账号、首要修改点
+- `references/minimal-vite.md` — `pactor create` 与手写 Vite 接入对比
+- 官方文档：`docs/src/content/docs/guides/getting-started.md`
+- 脚手架实现：`packages/create-app`（`create-pactor-app`）
+- 生成后写页面：启用 `pactor-dsl` skill

package/pactor-project/references/minimal-vite.md

@@ -0,0 +1,39 @@
+# 最小 Vite 工程：`pactor create` 与手写接入
+
+## `pactor create`（@pactor-app/cli）
+
+```bash
+pnpm add -D @pactor-app/cli
+pnpm pactor create my-app
+cd my-app && pnpm install && pnpm dev
+```
+
+- 当前仅模板 id **`app`**（`-t app` 可省略）
+- 生成物：Vite + React + `@pactor-app/vite-plugin` + `StaticDslLoader` + 示例 `*.page.yaml`
+- 适合：单页或少量静态 DSL、原型、学习 Runtime，**不含** sitemap / Next / 登录 mock
+
+与官方 `create-pactor-app` 关系：
+
+| 命令 | 包 | 产出 |
+| --- | --- | --- |
+| `pnpm create pactor-app` | npm 包 `create-pactor-app`（skill：`pactor-project`） | next-app 或 spa（SitemapApp 驱动） |
+| `pnpm pactor create` | `@pactor-app/cli` | 最小 Vite + StaticDslLoader |
+
+## 手写接入检查表（已有 Vite 项目）
+
+1. 依赖：
+
+```bash
+pnpm add @pactor-app/app @pactor-app/ui @pactor-app/resource react react-dom
+pnpm add -D @pactor-app/vite-plugin
+```
+
+2. `vite.config.ts`：`plugins: [react(), pactor()]`
+3. 入口：`import '@pactor-app/ui/styles.css'`
+4. `StaticDslLoader` 的 `bootstrap.menus` + `pages` 与 YAML 里 `page.id` 一致
+5. 校验：`pnpm pactor validate 'src/**/*.page.yaml'`
+
+## monorepo 参考
+
+- `examples/vite-starter` — 与 CLI `app` 模板同思路的 workspace 示例（:5499）
+- 修改 `packages/*` 后需根目录 `pnpm build`，示例才读到新 dist

package/pactor-project/references/templates.md

@@ -0,0 +1,92 @@
+# 官方模板：next-app 与 spa
+
+由 `create-pactor-app`（`packages/create-app/templates`）与仓库 `starters/` 提供，内容同步。
+
+## 对比
+
+| | next-app | spa |
+| --- | --- | --- |
+| 模板 id | `next-app` | `spa` |
+| 栈 | Next.js App Router + React | Vite + React |
+| dev 端口 | 9011 | 9012 |
+| 自带 mock API | 是（`/api/sitemap`、`/api/pages/[id]`、登录 cookie） | 否（默认连 :9011） |
+| 路由 | Next 可选 catch-all + `SitemapApp` 内容区 | 框架内置 History 路由（不传 pathname/navigate） |
+| 适用 | 全栈起步、会话、sitemap 裁剪 | 纯前端部署、API 独立团队 |
+
+## next-app 目录要点
+
+```text
+app/
+  layout.tsx                 # Pactor 壳常驻
+  [[...slug]]/page.tsx       # catch-all（可为空）
+  api/
+    sitemap/route.ts         # 会话感知 sitemap
+    pages/[id]/route.ts      # 页面 DSL 懒加载（PageResource envelope）
+    auth/login|logout/       # 演示登录
+src/
+  pactor/
+    config.ts                # sitemapSources、apiBaseUrl（通常相对本机）
+    App.tsx                  # SitemapApp + Next pathname/navigate
+  server/
+    accounts.ts              # 演示账号
+    sitemap.ts               # mock 数据组装
+    yaml/
+      sitemap.yaml           # 布局、菜单、页面 id 声明
+      pages/*.page.yaml      # 页面 DSL（官方脚手架默认：平铺模式 A）
+```
+
+### YAML 布局：平铺 vs 模块目录
+
+| 模式 | 路径 | 何时用 |
+| --- | --- | --- |
+| **A 平铺** | `yaml/pages/<id>.page.yaml` | 本模板 / `create-pactor-app -t next-app` 默认；少量页面 |
+| **B 模块目录** | `yaml/<模块>/<id>.yaml` | 多模块后台；**`pactor-prd` 模板**；页面 >5 时建议从 A 迁到 B |
+
+规则与批量加页：`pactor-dsl/references/page-catalog-and-layout.md`。
+
+演示账号：
+
+| 账号 | 密码 | 说明 |
+| --- | --- | --- |
+| admin | pactor123 | 含 `report:view`，报表页懒加载 |
+| guest | guest123 | 仅首页 |
+
+## spa 目录要点
+
+```text
+src/
+  main.tsx
+  pactor/
+    config.ts                # sitemapSources + apiBaseUrl（默认 http://localhost:9011）
+    App.tsx                  # SitemapApp + createHttpHooks（跨域 + envelope 拆包）
+index.html
+vite.config.ts               # 通常无 pactor vite-plugin（页面由 API 下发）
+```
+
+本地联调：**先** `next-app`（或等价后端）**:9011`，**再** spa `:9012`。
+
+## 生成后首要修改点
+
+### 所有模板
+
+- `package.json` 的 `name`（脚手架已用目录名替换 `__APP_NAME__`）
+- 品牌与标题：`src/server/yaml/sitemap.yaml`（next-app）内 `app.name`、菜单文案
+- 换真实后端：保持端点契约不变，替换 `app/api/*` 或 spa 的 `apiBaseUrl`（见 `@pactor-app/resource` 文档）
+
+### 仅 next-app
+
+- 新增页面：模式 A 在 `yaml/pages/` 增加 `*.page.yaml`；模式 B 在 `yaml/<模块>/` 增加 `<id>.yaml`；均在 `sitemap.yaml` 注册 `pages` / `menus`（见 page-catalog-and-layout.md）
+- 权限演示：改 `accounts.ts` 与 sitemap 里菜单的 permission 字段
+
+### 仅 spa
+
+- 部署生产：把 `apiBaseUrl` 改为生产 API 原点；确保 sitemap / pages 接口 CORS 与 cookie 策略与宿主一致
+
+## API 契约（简记）
+
+前端 `SitemapApp` / `createPactorApplication({ api })` 期望：
+
+- **Sitemap 源**：返回合并后的 sitemap 对象（layouts、pages 元数据、menus、app、user、permissions…）
+- **页面懒加载**：`GET .../pages/{id}` 返回 PageResource envelope（含页面 DSL 正文）
+
+next-app 模板的 route 实现即参考契约；对接自有 Java/Go 等服务时按同样 JSON 形状实现即可。

package/scripts/validate-skills.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Validates @pactor-app/skills layout: directory name === SKILL.md frontmatter name,
+ * required references exist, pactor-prd ships template/.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const skillsRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const SKILL_DIRS = ['pactor-dsl', 'pactor-project', 'pactor-prd'];
+
+function readSkillName(skillDir) {
+  const skillPath = join(skillDir, 'SKILL.md');
+  const text = readFileSync(skillPath, 'utf8');
+  const block = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!block) return null;
+  for (const line of block[1].split('\n')) {
+    if (line.startsWith('name:')) {
+      return line.slice('name:'.length).trim().replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return null;
+}
+
+function listMdReferences(skillDir) {
+  const refDir = join(skillDir, 'references');
+  if (!existsSync(refDir)) return [];
+  return readdirSync(refDir).filter((f) => f.endsWith('.md'));
+}
+
+let failed = false;
+
+for (const id of SKILL_DIRS) {
+  const dir = join(skillsRoot, id);
+  if (!existsSync(dir)) {
+    console.error(`missing skill directory: ${id}`);
+    failed = true;
+    continue;
+  }
+  const name = readSkillName(dir);
+  if (name !== id) {
+    console.error(`${id}: frontmatter name "${name}" !== directory "${id}"`);
+    failed = true;
+  }
+  const refs = listMdReferences(dir);
+  for (const file of refs) {
+    if (!existsSync(join(dir, 'references', file))) {
+      console.error(`${id}: missing references/${file}`);
+      failed = true;
+    }
+  }
+  if (id === 'pactor-prd') {
+    const tpl = join(dir, 'template', 'package.json');
+    if (!existsSync(tpl)) {
+      console.error('pactor-prd: missing template/package.json');
+      failed = true;
+    }
+  }
+}
+
+if (failed) {
+  process.exit(1);
+}
+console.log(`skills OK (${SKILL_DIRS.join(', ')})`);

package/prd-to-app/SKILL.md

@@ -1,75 +0,0 @@
----
-name: prd-to-app
-description: |
-  Use when generating a complete pactor (pactor-app) project from product documents / markdown wireframes — pages described in YAML DSL (*.page.yaml). Triggers: 根据 PRD / 产品文档 / 线框图 (wireframe) 创建 / 生成管理后台或 Web 应用原型; turning a PRD directory (overview README + per-page ASCII wireframe markdown) into a runnable Next.js + pactor project, including sitemap.yaml, page yaml, http dataSources, mock API routes, theme/skin alignment with the original product, and browser acceptance.
-version: 1.1.0
----
-
-# PRD → YAML 页面应用生成
-
-把「产品文档 + Markdown 线框图」翻译成可运行的 pactor 项目：页面全部 YAML DSL 描述，数据一律 http 数据源 + mock 路由，样式与功能与原产品一致。
-
-## 输入要求
-
-- PRD/线框图目录：总览 README（模块 × 页面 × 优先级表格）+ 分页线框图 markdown（ASCII 线框 + 区域说明 + 交互描述）
-- 原产品代码仓（可选但强烈建议）：用于提取设计令牌、自定义 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 skill 与 packages/ui 当前导出为准，本 skill 只约定流程与产出物
-
-## 流程（六阶段）
-
-### 1. 输入解析
-
-- 读总览 README：提取模块树、页面清单（页面 id kebab-case、标题、路由路径、菜单分组、P0/P1/P2 优先级）
-- 逐页读线框图：提取页面类型（列表/详情/表单/仪表盘）、布局区域、组件清单、字段与数据需求、交互（跳转/弹窗/操作）
-- 输出一页纸页面清单供确认；P2 等未排期页面登记但不生成
-
-### 2. 脚手架
-
-- **整体复制 `template/` 目录作为新项目起点**（可运行的参考实现：完整接线 + 公共页面 + 两个参考模块），不要从空目录或 `pnpm create pactor-app` 开始
-- 确定工程名称：**用户未明确指定时，根据原型目录 README 中的产品名生成英文名**（kebab-case）：取 README 主标题/产品名（如「订单管理系统产品原型线框图」→ `order-console`），中文名先译为简洁英文；派生出的名称在创建前向用户确认一次
-- 改名并安装：package.json name、yaml/sitemap.yaml 的 app.name 与品牌改为新产品名；`pnpm install` + 启动 dev server 验证模板可运行
-- 按 `references/project-structure.md` 核对目录结构：`src/server/yaml/`（sitemap.yaml + 按模块分目录的页面 yaml）与 `app/api/` 路由（sitemap / public/pages/[id] / data/[...path]）
-- 模板中的 provider / route 两个模块作为页面写法参考保留在手边，新模块照其结构生成；确认全部页面生成完毕后删除参考模块及其 mock
-
-### 3. 页面生成
-
-- 按 `references/component-mapping.md` 把线框图区域映射为 pactor 组件
-- 按 `references/page-templates.md` 的三类模板逐页生成 `yaml/<模块>/<id>.yaml`：列表页（筛选 + 表格/卡片 + 操作列）、详情页（描述列表 + Tab/分区）、表单页（校验 + 提交闭环）；**所有表单（含页面内嵌的配置面板、弹窗/抽屉表单）一律 `Form` 组件包裹**，写法见 page-templates.md「内嵌表单面板」
-- 每页 dataSources 全部 `type: http`；交互经 events + actions 闭环（setState → reload dataSource → router.push 等）
-
-### 4. mock 服务
-
-- 按 `references/mock-data-routes.md` 在 `app/api/data/[...path]/route.ts` 注册路由表 handler，返回符合线框图字段的 mock 数据（含空态/多态数据各至少一条）
-
-### 5. 样式移植
-
-- 按 `references/theme-and-style.md`：提取原产品设计令牌写入皮肤文件（深浅色俱全）、移植页面级自定义 CSS 并挂载、对齐换肤入口与皮肤数量、确认图表随肤切换
-
-### 6. 功能与视觉验收（必经，不可跳过）
-
-- 按 `references/acceptance-checklist.md` 逐页浏览器验收并输出验收结果表：路由可达、数据源 200、渲染符合线框、交互逐项操作（含错误分支）、控制台无错、深浅色切换、与原产品同页面对比
-
-## references 索引
-
-| 文件 | 何时加载 |
-| --- | --- |
-| `template/` | 阶段 2：可运行的模板工程（完整接线 + 公共页面 + provider/route 两个参考模块），整体复制后按 PRD 改造，用法见其 README.md |
-| `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：验收清单与结果输出格式 |