@mingfuyun/star-allinone 0.2.0 → 0.3.1

package/README.md

@@ -17,9 +17,10 @@ pnpm add @mingfuyun/star-allinone
 公共 skill 由本仓库维护，随 `@mingfuyun/star-allinone` 发布。业务项目用 CLI 同步到自己的 `.agents/skills/shared-*` 并提交。Codex / Cursor 直接从业务仓库发现 skill，不写入 `~/.codex/skills`，团队成员也不需要本仓库源码。
 
 ```text
+AGENTS.md           ← 常驻约定，不要加 .cursor/rules
 .agents/skills/
-├── shared-*    ← npm 包同步，不能在业务项目直接改
-└── custom-*    ← 业务项目自己维护
+├── shared-*        ← npm 包同步，不能在业务项目直接改
+└── custom-*        ← 业务项目自己维护
 ```
 
 完整约定见 [skills/README.md](skills/README.md)。
@@ -32,9 +33,13 @@ pnpm add @mingfuyun/star-allinone
 pnpm exec star-allinone skills list
 pnpm exec star-allinone skills sync --dry-run
 pnpm exec star-allinone skills sync
+pnpm exec star-allinone gen service --operation "GET /api/v1/devices/"
+pnpm exec star-allinone gen page --feature Widgets --route /widgets --title 组件管理 --list-operation "GET /api/v1/widgets/"
 ```
 
-`list` 查看包内公共 skill。`sync` 把它们写入当前项目的 `.agents/skills/shared-*`，会整体替换过期的 `shared-*`，但不会改 `custom-*`。
+`gen service` 按 OpenAPI/Swagger 写一条 `MFRequest` 方法和对应类型。`gen page` 生成标准列表页骨架，并可先生成相关 Service。
+
+`list` 查看包内公共 skill。`sync` 把它们写入当前项目的 `.agents/skills/shared-*`，会整体替换过期的 `shared-*`，但不会改 `custom-*`。仓库根没有 `AGENTS.md` 时，会从 `examples/AGENTS.md` 补一份，已有文件不覆盖。
 
 ### 维护者：改公共 skill
 
@@ -72,26 +77,28 @@ StarLink 示例见 `examples/projects/`。
 pnpm exec star-allinone skills sync
 ```
 
-4. 把真正的业务特例放到 `.agents/skills/custom-*`。审查、提交、发布、Mock 和 Service 生成不要做成 `custom-*`。
+4. 把真正的业务特例放到 `.agents/skills/custom-*`。审查、提交、发布、单接口、页面生成不要做成 `custom-*`。全量契约重建（若需要）必须 `disable-model-invocation`，并在 `AGENTS.md` 写清命令。
+
+5. 仓库根放 `AGENTS.md`（可从包内 `examples/AGENTS.md` 复制）。`skills sync` 只在该文件缺失时补一份，不会覆盖已有内容。常驻约定只写这一份，不要加 `.cursor/rules`。
 
-5. 提交配置和 skill：
+6. 提交配置和 skill：
 
 ```bash
-git add .star-allinone.json .agents/skills
+git add .star-allinone.json AGENTS.md .agents/skills
 git commit -m "chore(skill): 接入公共 skill"
 ```
 
 ### 业务项目：日常调用
 
-在 Codex / Cursor 对话里用 `$skill-name` 显式调用，例如：
+只使用下面这些**用户入口**。
 
 ```text
 使用 $shared-api-to-service，为 GET /api/v1/devices/ 生成类型、Service 和 JSON Mock。
 ```
 
 ```text
-使用 $shared-design-to-page，根据我上传的设计稿生成页面。
-缺少的 Service、类型和 Mock 一并生成。
+使用 $shared-design-to-page，生成 /widgets 页面。
+标准列表接口 GET /api/v1/widgets/。
 ```
 
 ```text
@@ -103,7 +110,7 @@ git commit -m "chore(skill): 接入公共 skill"
 使用 $shared-publish-test，把当前分支发布到测试环境。
 ```
 
-公共流程用 `shared-*`，项目专属规则用 `custom-*`。业务定制 skill 需要复用公共流程时，在 `custom-*` 的 `SKILL.md` 里写明先读取对应的 `.agents/skills/shared-*/SKILL.md`。
+公共流程用 `shared-*`，项目专属规则用 `custom-*`。`custom-*` 不能再实现一遍 Service/页面生成/审查。全量契约重建若需要，写成不可调用的脚本，并在 `AGENTS.md` 写命令。业务定制需要复用公共流程时，读取对应的 `.agents/skills/shared-*/SKILL.md`，不要再抛一个入口。
 
 ### 业务项目：更新公共 skill
 

package/examples/AGENTS.md

@@ -0,0 +1,26 @@
+# Agent instructions
+
+This is a Umi Max + Ant Design 5 PC admin app. Shared skills live in `.agents/skills/shared-*` and are synced from `@mingfuyun/star-allinone`. Do not edit `shared-*`. Put project-only rules in `.agents/skills/custom-*` or `.agents/project/`.
+
+Always-on instructions are this file. Do not add `.cursor/rules`.
+
+## Default workflow
+
+User-facing shared entries only:
+
+- One endpoint: `pnpm exec star-allinone gen service --operation "METHOD /path/"` or `$shared-api-to-service`.
+- Pages: `$shared-design-to-page`. Standard lists run `pnpm exec star-allinone gen page` inside that skill.
+- Review and commit: `$shared-review-and-submit`. Wait for confirmation.
+- Test publish: `$shared-publish-test` after explicit pipeline confirmation.
+
+## Hard rules
+
+- For non-trivial changes, read `.agents/skills/shared-project-conventions/references/architecture.md`.
+- Pages use `import Service from '@/services'`. Do not call axios or `src/services/request.tsx` from pages.
+- Lists: `MFProTable`. Forms: `ProForm`. Overlays: `CustomDrawer`, `BaseModal`, `HocModal` from `@mingfuyun/star-allinone`.
+- Keep columns and actions in `const.tsx`. Empty cells render as `-`.
+- Keep DTOs in the domain `typings.d.ts` namespace. Preserve backend snake_case.
+- Do not edit `src/services/request.tsx` for a single endpoint.
+- Every `await` uses try/catch. Do not use `Modal.confirm`.
+- After TypeScript changes run `pnpm typecheck`.
+- If `.agents/project/conventions.md` or `.agents/project/review-rules.md` exists, apply them as additions only.

package/examples/projects/starlink-frontend.star-allinone.json

@@ -0,0 +1,7 @@
+{
+  "project": "starlink-frontend",
+  "publicSkillPrefix": "shared-",
+  "serviceDir": "src/services",
+  "openapi": "swagger.json",
+  "publishPipelineId": "5245265"
+}

package/examples/projects/starscope-frontend.star-allinone.json

@@ -0,0 +1,7 @@
+{
+  "project": "starscope-frontend",
+  "publicSkillPrefix": "shared-",
+  "serviceDir": "src/services",
+  "openapi": ".agents/project/openapi.json",
+  "publishPipelineId": "5108336"
+}

package/examples/skills/custom-domain-invariants/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: custom-domain-invariants
+description: Internal. Project domain extras for review. Do not invoke. Not a generate, page, or review entry.
+disable-model-invocation: true
+---
+
+# Domain invariants
+
+Not a user-facing entry. Pages, services, and review still go through `$shared-design-to-page`, `$shared-api-to-service`, and `$shared-review-and-submit`.
+
+Read this file only as extra checks after those shared skills. Do not generate pages, services, or mocks here.
+
+Example extras (replace with the project's real invariants):
+
+- IPv4 and IPv6 branches must both be checked.
+- Do not invent query param aliases that are missing from swagger.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingfuyun/star-allinone",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "星系运维前端能力包",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,9 @@
     "dist",
     "README.md",
     "scripts/cli.js",
-    "skills"
+    "scripts/gen",
+    "skills",
+    "examples"
   ],
   "scripts": {
     "build": "webpack --env format=umd --mode=none && webpack --env format=esm --mode=none",
@@ -39,7 +41,7 @@
     "skills:sync": "node scripts/cli.js skills sync",
     "skills:list": "node scripts/cli.js skills list",
     "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "node scripts/gen/fixtures/run.js",
     "dev": "webpack --mode=none --watch",
     "clean": "rm -rf dist"
   },

package/scripts/cli.js

@@ -17,11 +17,17 @@ function usage() {
   console.log(`Usage:
   star-allinone skills list
   star-allinone skills sync [--target <dir>] [--dry-run]
+  star-allinone gen service --operation "GET /api/v1/devices/" [--spec <file>] [--domain Devices] [--mock-file] [--dry-run]
+  star-allinone gen page --feature Widgets --route /widgets --title 组件管理 --list-operation "GET /api/v1/widgets/" [--create-operation ...] [--update-operation ...] [--delete-operation ...] [--dry-run]
 
-Run the command from a business project containing .star-allinone.json.
+Run from a business project containing .star-allinone.json.
 
-Sync writes package skills/shared/* to <project>/.agents/skills/shared-*.
-It never writes ~/.codex/skills and never modifies custom-* skills.`);
+skills sync writes package skills/shared/* to <project>/.agents/skills/shared-*.
+It never writes ~/.codex/skills and never modifies custom-* skills.
+If <project>/AGENTS.md is missing, it copies examples/AGENTS.md once.
+
+gen service writes one MFRequest method and types from OpenAPI/Swagger.
+gen page scaffolds a list + drawer + confirm page and can generate services first.`);
   process.exitCode = 1;
 }
 
@@ -33,8 +39,12 @@ function listSharedSkillNames() {
     .sort();
 }
 
+function hasSkillMarkdown(name) {
+  return fs.existsSync(path.join(skillsRoot, name, 'SKILL.md'));
+}
+
 function listSkills() {
-  const skills = listSharedSkillNames();
+  const skills = listSharedSkillNames().filter(hasSkillMarkdown);
   if (!skills.length) {
     console.log('No shared skills found.');
     return;
@@ -50,8 +60,12 @@ function parseArgs(args) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg === '--dry-run') options.dryRun = true;
-    else if (arg === '--target') options.target = args[++index];
-    else positional.push(arg);
+    else if (arg === '--mock-file') options.mockFile = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg.startsWith('--')) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+      options[key] = args[++index];
+    } else positional.push(arg);
   }
   return { options, positional };
 }
@@ -132,12 +146,14 @@ function pruneStaleShared(destination, prefix, syncedNames, options) {
 
 function selectedSharedSkills(config) {
   const available = listSharedSkillNames();
+  const support = available.filter((name) => !hasSkillMarkdown(name));
   if (!config.sharedSkills) return available;
   const missing = config.sharedSkills.filter((name) => !available.includes(name));
   if (missing.length) {
     throw new Error(`Unknown sharedSkills: ${missing.join(', ')}`);
   }
-  return available.filter((name) => config.sharedSkills.includes(name));
+  const selected = available.filter((name) => config.sharedSkills.includes(name));
+  return [...new Set([...support, ...selected])];
 }
 
 function syncProject(options) {
@@ -158,17 +174,40 @@ function syncProject(options) {
     copySkill(path.join(skillsRoot, skillName), destination, skillName, prefix, variables, options);
   }
   pruneStaleShared(destination, prefix, syncedNames, options);
+  seedAgentsMarkdown(target, options);
   console.log(`${options.dryRun ? 'Would sync' : 'Synced'} shared skills -> ${destination}`);
 }
 
+function seedAgentsMarkdown(target, options) {
+  const dest = path.join(target, 'AGENTS.md');
+  const source = path.join(root, 'examples', 'AGENTS.md');
+  if (fs.existsSync(dest) || !fs.existsSync(source)) return;
+  console.log(`${options.dryRun ? '[dry-run] ' : ''}AGENTS.md`);
+  if (!options.dryRun) fs.copyFileSync(source, dest);
+}
+
 function main() {
   const [group, command, ...rest] = process.argv.slice(2);
-  if (group !== 'skills') return usage();
-  if (command === 'list') return listSkills();
-  if (command !== 'sync') return usage();
-  const { options, positional } = parseArgs(rest);
-  if (positional.length) return usage();
-  syncProject(options);
+  if (group === 'skills') {
+    if (command === 'list') return listSkills();
+    if (command !== 'sync') return usage();
+    const { options, positional } = parseArgs(rest);
+    if (positional.length) return usage();
+    return syncProject(options);
+  }
+  if (group === 'gen') {
+    const { options, positional } = parseArgs(rest);
+    if (positional.length) return usage();
+    if (command === 'service') {
+      if (!options.operation) return usage();
+      return require('./gen/service').generateService(process.cwd(), options);
+    }
+    if (command === 'page') {
+      if (!options.feature) return usage();
+      return require('./gen/page').generatePage(process.cwd(), options);
+    }
+  }
+  return usage();
 }
 
 try {

package/scripts/gen/fixtures/run.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { generateService } = require('../service');
+const { generatePage } = require('../page');
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function makeProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'star-allinone-gen-'));
+  fs.writeFileSync(
+    path.join(root, '.star-allinone.json'),
+    JSON.stringify(
+      {
+        project: 'fixture',
+        serviceDir: 'src/services',
+        openapi: 'openapi.json',
+      },
+      null,
+      2,
+    ),
+  );
+  fs.copyFileSync(
+    path.join(__dirname, 'widgets.openapi.json'),
+    path.join(root, 'openapi.json'),
+  );
+  fs.mkdirSync(path.join(root, 'src/services'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'src/services/request.tsx'),
+    'const MFRequest = { get() {}, post() {}, patch() {}, delete() {} };\nexport default MFRequest;\n',
+  );
+  fs.writeFileSync(
+    path.join(root, 'src/services/index.ts'),
+    'export default {};\n',
+  );
+  fs.mkdirSync(path.join(root, 'config'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, 'config/route.ts'),
+    `export default [
+  { path: '/', redirect: '/home' },
+  { path: '/*', component: '@/pages/404', name: '404' },
+];
+`,
+  );
+  fs.mkdirSync(path.join(root, 'src/components/CommonTable'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'src/pages'), { recursive: true });
+  return root;
+}
+
+function main() {
+  const root = makeProject();
+  const first = generateService(root, {
+    operation: 'GET /api/v1/widgets/',
+    mockFile: true,
+  });
+  assert(first.fn === 'widgetsList', `fn ${first.fn}`);
+  assert(first.domain === 'Widgets', `domain ${first.domain}`);
+  const service = fs.readFileSync(first.servicePath, 'utf8');
+  assert(service.includes("MFRequest.get<WIDGETS_API.WidgetList>('/api/v1/widgets/', params)"), service);
+  const typings = fs.readFileSync(first.typingsPath, 'utf8');
+  assert(typings.includes('type Widget ='), typings);
+  assert(typings.includes('type WidgetList ='), typings);
+  assert(typings.includes('results?: Widget[]'), typings);
+  assert(typings.includes('status?: string | null'), typings);
+  assert(typings.includes('type WidgetsListQuery'), typings);
+  const mockFile = path.join(root, 'mock/api/v1/widgets/get.json');
+  assert(fs.existsSync(mockFile), 'missing mock file');
+  const index = fs.readFileSync(path.join(root, 'src/services/index.ts'), 'utf8');
+  assert(index.includes("from './Widgets/widgets'"), index);
+
+  const reused = generateService(root, { operation: 'GET /api/v1/widgets/' });
+  assert(reused.status === 'reuse', 'expected reuse on second run');
+
+  generateService(root, { operation: 'PATCH /api/v1/widgets/{id}/' });
+  const patched = fs.readFileSync(first.servicePath, 'utf8');
+  assert(patched.includes('widgetsPartialUpdate'), patched);
+  assert(patched.includes('MFRequest.patch<WIDGETS_API.Widget>'), patched);
+
+  generatePage(root, {
+    feature: 'Widgets',
+    route: '/widgets',
+    title: '组件管理',
+    listOperation: 'GET /api/v1/widgets/',
+    createOperation: 'POST /api/v1/widgets/',
+    updateOperation: 'PATCH /api/v1/widgets/{id}/',
+    deleteOperation: 'DELETE /api/v1/widgets/{id}/',
+  });
+  const page = fs.readFileSync(path.join(root, 'src/pages/Widgets/index.tsx'), 'utf8');
+  assert(page.includes('Service.widgetsList'), page);
+  assert(page.includes("rowKey=\"id\""), page);
+  const route = fs.readFileSync(path.join(root, 'config/route.ts'), 'utf8');
+  assert(route.includes("path: '/widgets'"), route);
+  fs.rmSync(root, { recursive: true, force: true });
+  console.log('codegen fixtures passed');
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.stack || error.message);
+  process.exit(1);
+}

package/scripts/gen/fixtures/widgets.openapi.json

@@ -0,0 +1,194 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "codegen fixture",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/api/v1/widgets/": {
+      "get": {
+        "operationId": "widgets_list",
+        "tags": ["Widgets"],
+        "summary": "获取组件列表",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "page",
+            "required": true,
+            "schema": { "type": "integer" }
+          },
+          {
+            "in": "query",
+            "name": "page_size",
+            "required": true,
+            "schema": { "type": "integer" }
+          },
+          {
+            "in": "query",
+            "name": "keyword",
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": { "type": "integer" },
+                    "message": { "type": "string" },
+                    "data": {
+                      "$ref": "#/components/schemas/WidgetList"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "widgets_create",
+        "tags": ["Widgets"],
+        "summary": "创建组件",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WidgetBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": { "type": "integer" },
+                    "message": { "type": "string" },
+                    "data": {
+                      "$ref": "#/components/schemas/Widget"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/widgets/{id}/": {
+      "patch": {
+        "operationId": "widgets_partial_update",
+        "tags": ["Widgets"],
+        "summary": "更新组件",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WidgetBody"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": { "type": "integer" },
+                    "message": { "type": "string" },
+                    "data": {
+                      "$ref": "#/components/schemas/Widget"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "widgets_destroy",
+        "tags": ["Widgets"],
+        "summary": "删除组件",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": { "type": "string" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": { "type": "integer" },
+                    "message": { "type": "string" },
+                    "data": { "type": "object" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Widget": {
+        "type": "object",
+        "required": ["id", "name"],
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "status": { "type": "string", "nullable": true },
+          "count": { "type": "integer" }
+        }
+      },
+      "WidgetBody": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string" },
+          "status": { "type": "string" }
+        }
+      },
+      "WidgetList": {
+        "type": "object",
+        "properties": {
+          "results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Widget"
+            }
+          },
+          "count": { "type": "integer" }
+        }
+      }
+    }
+  }
+}