@loom-framework/core 0.1.0-alpha.165 → 0.1.0-alpha.167

package/builtin-skills/loom/SKILL.md

@@ -35,7 +35,7 @@ Loom 是**配置驱动的 AI 平台开发框架**——你描述需求，AI 通
 npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>
 ```
 
-项目初始化时自动生成系统管理页面（模型管理、技能管理、用户管理、过程管理），并以子菜单形式接入导航。同时自动安装以下内置 Skill：
+项目初始化时自动生成系统管理页面（模型管理、技能管理、用户管理、过程管理、通知中心），并以子菜单形式接入导航。同时自动安装以下内置 Skill：
 
 | Skill | 触发场景 | 说明 |
 |-------|---------|------|
@@ -107,7 +107,7 @@ loom generate capabilities
 1. **询问需求**：是否需要登录功能？有哪些角色？每个角色能做什么？
 2. **编辑配置**：在 `loom.config.ts` 中添加 `auth` 字段（Schema 见上方）。至少定义一个 `admin` 角色
 3. **设置密钥**：`secret` 推荐 `env:JWT_SECRET`，不要硬编码。提醒用户设置环境变量 `export JWT_SECRET=your-secret`
-4. **生成认证页面**：`loom generate system-settings user` — 自动生成用户管理页、登录页，并接入 AuthProvider 路由守卫
+4. **生成认证页面**：`loom generate system-settings user` — 自动接入用户管理页和登录页的 npm import，并接入 AuthProvider 路由守卫
 5. **重启后端**：auth 配置需要重启后端生效（**必须先询问用户**）
 6. **首次登录**：默认创建 admin 用户（密码 `admin123`），**提醒用户立即修改密码**
 7. **生成 app-skill**：`loom generate capabilities` 更新 Skill 中的 auth.md
@@ -153,6 +153,10 @@ loom generate page <Name> --model <model-name> --force
 
 **恢复备份**：`--force` 覆盖的文件自动备份到项目 `.loom/backup/<时间戳>/` 目录（每次 --force 生成独立时间戳目录，同一天多次执行互不影响），如需恢复：`cp .loom/backup/<时间戳>/XXX.tsx frontend/src/components/pages/XXX.tsx`
 
+### 6. 系统页面定制（Eject）
+
+系统管理页面默认以 npm 组件接入，无法直接修改。需要定制时 eject 为本地文件，恢复时 uneject。详见 `references/eject.md`。
+
 ### 内置 Skill 使用原则
 
 - 涉及前端页面开发 → 先用 `/antd` 查询组件 API，不要凭记忆写代码
@@ -170,11 +174,10 @@ loom generate page <Name> --model <model-name> --force
 | `loom generate capabilities` | 生成应用 Skill（`references/models.md` + `references/data-semantics.md`，`SKILL.md` 仅首次创建不覆盖） |
 | `loom generate dashboard <name>` | 从 loom.config.ts dashboards 生成 Dashboard 页面 |
 | `loom generate dashboard <name> --force` | 重建 Dashboard 页面（自动备份旧文件到 `.loom/backup/`） |
-| `loom generate system-settings <model\|skill\|user\|process>` | 生成系统管理页面（模型管理、技能管理、用户管理或过程管理），首次调用创建子菜单，后续调用追加子页面；`user` 类型同时生成登录页和 AuthProvider 接线 |
-| `loom generate system-settings <model\|skill\|user\|process> --force` | 重建系统管理页面（自动备份旧文件到 `.loom/backup/`） |
+| `loom generate system-settings <type>` | 将系统页面接入 App.tsx（npm import 接线），type: `model`/`skill`/`user`/`login`/`process`/`notification`；`user` 同时接入 AuthProvider 路由守卫，`notification` 同时接入 NotificationCenterProvider |
 | `loom generate skill <name>` | 生成自定义 Skill 脚架 |
-| `loom eject system-settings <type>` | 将系统页面从 npm 组件切换为本地文件（可自由编辑），type: `model`/`skill`/`user`/`login`/`process`/`notification` |
-| `loom uneject system-settings <type>` | 删除本地文件，恢复为 npm 组件（修改过的需 `--force`，操作前自动备份） |
+| `loom eject system-settings <type>` | 将系统页面从 npm 组件切换为本地文件（可自由编辑），type: `model`/`skill`/`user`/`login`/`process`/`notification`。详见 `references/eject.md` |
+| `loom uneject system-settings <type>` | 删除本地文件，恢复为 npm 组件（修改过的需 `--force`，操作前自动备份）。详见 `references/eject.md` |
 | `loom data read <model>` | 查询数据（`--filter` 筛选、`--limit` 限制条数、`--sort` 排序） |
 | `loom data write <model> --data '<json>'` | 创建记录 |
 | `loom data update <model> <id> --data '<json>'` | 更新记录 |

package/builtin-skills/loom/references/eject.md

@@ -0,0 +1,130 @@
+# System Page Eject — 定制化参考
+
+系统管理页面默认以 npm 组件形式接入 App.tsx，不支持直接修改。Eject 机制将页面输出为本地 .tsx 文件，切换 import 来源，使页面可自由定制。
+
+## 页面类型
+
+| type         | 组件名              | npmComponent              | 接线方式      | 说明                              |
+|--------------|---------------------|---------------------------|---------------|-----------------------------------|
+| model        | ModelManagement     | ModelManagementPage       | sidebar-nav   | 系统配置子菜单                    |
+| skill        | SkillManagement     | SkillManagementPage       | sidebar-nav   | 系统配置子菜单                    |
+| user         | UserManagement      | UserManagementPage        | sidebar-nav   | 自动接入 AuthProvider             |
+| login        | Login               | LoginPage                 | auth-fallback | AuthGuard 的 fallback，无导航入口 |
+| process      | ProcessManagement   | ProcessManagementPage     | sidebar-nav   | 系统配置子菜单                    |
+| notification | NotificationCenter  | NotificationCenterPage    | skip-nav      | 通知铃铛触发，无导航入口          |
+
+notification eject 时同时生成 NotificationCenter + NotificationDetail 两个文件。
+
+## 命令
+
+```bash
+# eject: npm 组件 → 本地文件（可编辑）
+loom eject system-settings <type>
+
+# uneject: 本地文件 → npm 组件（已修改需 --force）
+loom uneject system-settings <type> [--force]
+
+# 接入 App.tsx（npm import 接线，init 时自动执行）
+loom generate system-settings <type>
+```
+
+## Eject/Uneject 对 App.tsx 的影响
+
+### eject 前
+
+```tsx
+import { ModelManagementPage } from '@loom-framework/frontend-antd';
+// ...
+case 'model-management': return <ModelManagementPage />;
+```
+
+### eject 后
+
+```tsx
+import ModelManagementPage from './components/pages/ModelManagement';
+// ...
+case 'model-management': return <ModelManagementPage />;
+```
+
+本地文件出现在 `frontend/src/components/pages/<PascalName>.tsx`。
+
+### uneject 后
+
+本地文件删除，import 恢复为 npm 路径。
+
+## 定制化操作指南
+
+### 修改页面布局或样式
+
+1. 执行 `loom eject system-settings <type>`
+2. 编辑 `frontend/src/components/pages/` 下的 .tsx 文件
+3. 运行 `loom dev` 查看效果
+
+### 使用框架子组件
+
+eject 后的文件 import 来自 `@loom-framework/frontend-antd`，可直接使用框架子组件：
+
+```tsx
+import { ProcessTree, ProcessOverview, ProcessLogs, ProcessMetrics } from '@loom-framework/frontend-antd';
+```
+
+可用的 hook：`useData`, `useSchema`, `useLocale`, `useModels`, `useChartData`。
+
+### 替换子组件
+
+将 import 替换为自定义实现：
+
+```tsx
+// 替换前
+import { ProcessTree } from '@loom-framework/frontend-antd';
+// 替换后
+import { MyCustomTree } from './MyCustomTree';
+```
+
+### 添加自定义管理页面
+
+内置的 6 种系统页面 type（model/skill/user/login/process/notification）由框架预定义，用户无法新增 type。如需框架未提供的管理页面，根据场景选择：
+
+**数据驱动页面**（对应一个数据模型，需要增删改查）→ 在 `loom.config.ts` 中添加模型定义，然后 `loom generate page <Name> --model <model>` 生成 CRUD 页面 + API + 导航
+
+**纯 UI 页面**（不对应数据模型，如审批流程、配置向导）→ 手动创建 `frontend/src/components/pages/MyPage.tsx`，然后在 App.tsx 中添加 import、导航项和路由
+
+## 安全机制
+
+- eject 时自动保存校验和到 `.loom/checksums/`
+- uneject 时校验：未修改可直接删除，已修改需 `--force`
+- 所有操作前自动备份到 `.loom/backup/`
+
+## WiringMode 说明
+
+- **sidebar-nav**: 添加到系统配置子菜单，有导航入口、switch case、breadcrumb
+- **auth-fallback**: 作为 `<AuthGuard fallback={<Login />}>` 注入，无导航入口
+- **skip-nav**: 无导航入口（通过其他 UI 触发），但有 switch case 和 breadcrumb
+
+## 构建时模板生成
+
+模板文件由 `pnpm build` 自动从 `frontend-antd/src/` 源码生成到 `templates/`。不需要手动运行 `pnpm generate-templates`（build 已自动调用）。
+
+- import 路径自动从 relative 转换为 `@loom-framework/frontend-antd` barrel import
+- `validateBarrelExports()` 自动校验模板中所有 import 在 `frontend-antd/src/index.ts` 中存在，缺失导出会导致构建失败
+- `validateCompleteness()` 自动校验 `template-source-mappings.ts` 与 `SYSTEM_PAGE_CONFIG` 一致，不一致会报错退出
+- 模板文件头部含版本号：`GENERATED by scripts/generate-templates.ts — v0.1.0-alpha.166 — DO NOT EDIT MANUALLY`
+
+## 版本对齐警告
+
+eject 时如果模板 GENEREATED header 中的版本与安装的 `@loom-framework/frontend-antd` 版本不一致，会显示黄色警告：
+
+```
+⚠ Template for "ModelManagement" was generated for v0.1.0-alpha.166, but installed frontend-antd is v0.1.0-alpha.168. Ejected code may differ from npm version.
+  Run "pnpm build" in the framework repo to regenerate templates, or update frontend-antd.
+```
+
+这不阻止 eject 操作，仅提示可能存在的不一致。
+
+## 新增系统页面清单
+
+1. 在 `packages/frontend-antd/src/` 创建 .tsx 组件（含 per-page `registerMessages`）
+2. 在 `packages/frontend-antd/src/index.ts` 导出组件
+3. 在 `packages/core/src/cli/helpers/system-page-config.ts` 的 `SYSTEM_PAGE_CONFIG` 中添加配置
+4. 在 `packages/core/scripts/template-source-mappings.ts` 添加源文件映射
+5. 运行 `pnpm build` — 模板自动生成 + barrel export 自动校验

package/dist/cli/commands/eject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eject.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/eject.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwYzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0I3D"}
+{"version":3,"file":"eject.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/eject.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0MzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmH3D"}