@mingfuyun/star-allinone 0.1.6 → 0.1.8

package/skills/README.md

@@ -0,0 +1,297 @@
+# Skills
+
+公共 skill 和业务定制 skill 都保存在业务项目仓库中，但通过目录命名和来源规则明确区分。
+
+不使用 Codex 全局目录 `~/.codex/skills`，也不要求团队成员拥有 `star-allinone` 源码。
+
+## 推荐目录
+
+以 `starscope-frontend` 为例：
+
+```text
+starscope-frontend/
+├── .star-allinone.json
+└── .agents/
+    ├── skills/
+    │   ├── shared-api-to-service/
+    │   ├── shared-api-mock/
+    │   ├── shared-design-to-page/
+    │   ├── shared-verify/
+    │   ├── shared-review-and-submit/
+    │   ├── shared-publish-test/
+    │   └── custom-device-management/
+    └── project/
+        ├── conventions.md
+        ├── review-rules.md
+        └── openapi.json
+```
+
+StarLink：
+
+```text
+starlink-frontend/
+└── .agents/
+    └── skills/
+        ├── shared-api-to-service/
+        ├── shared-api-mock/
+        ├── shared-design-to-page/
+        ├── shared-verify/
+        ├── shared-review-and-submit/
+        ├── shared-publish-test/
+        └── custom-node-management/
+```
+
+命名约定：
+
+```text
+shared-*   公共 skill，由 star-allinone 提供，经 CLI 同步后提交到业务仓库
+custom-*   业务定制 skill，由业务项目维护
+```
+
+这样所有 skill 都在业务项目中，Codex 可以直接发现；同时通过名称可以清楚区分来源。
+
+## npm 包的职责
+
+`@mingfuyun/star-allinone` 包中保存公共 skill 源文件。每个 skill 包含可执行规则，细节放在同目录 `references/`：
+
+```text
+@mingfuyun/star-allinone/
+└── skills/
+    └── shared/
+        ├── api-to-service/
+        │   ├── SKILL.md
+        │   └── references/
+        │       ├── service-conventions.md
+        │       └── api-artifact-generation.md
+        ├── api-mock/
+        ├── design-to-page/          # page-conventions.md + overlays.md
+        ├── project-conventions/     # architecture / review-checklist / quality-checklist
+        ├── verify/
+        ├── review-and-submit/
+        ├── impact-analysis/
+        ├── ai-review/
+        ├── commit-current-changes/
+        └── publish-test/              # 流水线 ID 从 .star-allinone.json 读取
+```
+
+公共 skill 写死两边已对齐的硬规则，例如：页面走 `MFRequest`、DTO 放 namespace typings、`MFProTable` + `ProForm`、弹层用 `BaseModal` / `CustomDrawer` / `HocModal`、`await` 必须 try/catch、禁止无说明的 `any`。
+
+业务项目的 `.agents/project/` 只写差异：路径、权限体系、OpenAPI 位置、领域特例。项目文件可以补充，但不能削弱公共硬规则。
+
+CLI 只做同步：
+
+```text
+npm 包中的 skills/shared
+        ↓
+业务项目 .agents/skills/shared-*
+```
+
+不会写入：
+
+```text
+~/.codex/skills
+```
+
+也不会管理业务项目的 `custom-*` skill。
+
+## CLI 使用方式
+
+在业务项目目录执行：
+
+```bash
+pnpm exec star-allinone skills sync
+```
+
+CLI 根据当前业务项目的 `.star-allinone.json`，直接将公共 skill 写入当前项目：
+
+```text
+当前项目/.agents/skills/shared-*/
+```
+
+例如：
+
+```bash
+cd /path/to/starscope-frontend
+pnpm exec star-allinone skills sync
+```
+
+结果：
+
+```text
+.agents/skills/
+├── shared-api-to-service/
+├── shared-api-mock/
+├── shared-review-and-submit/
+├── shared-publish-test/
+└── custom-*/
+```
+
+公共 skill 的更新不会影响业务定制 skill。同步会整体替换 `shared-*` 目录，并删除包中已不存在的过期 `shared-*`，但不会改动 `custom-*`。
+
+## 新增或修改公共 skill
+
+管理者操作：
+
+```text
+修改 star-allinone/skills/shared/api-to-service/SKILL.md
+→ 发布新版本 @mingfuyun/star-allinone
+```
+
+业务项目操作：
+
+```bash
+pnpm update @mingfuyun/star-allinone
+pnpm exec star-allinone skills sync
+git add package.json pnpm-lock.yaml .agents/skills/shared-*
+git commit -m "chore(skill): 更新公共 skill"
+```
+
+团队成员只需要：
+
+```bash
+git pull
+pnpm install
+```
+
+由于公共 skill 已经提交到业务仓库，所以团队成员不需要手动安装全局 skill，也不需要拥有 `star-allinone` 源码。
+
+## 新增或修改业务定制 skill
+
+业务项目直接维护：
+
+```text
+.agents/skills/custom-device-management/SKILL.md
+```
+
+提交即可：
+
+```bash
+git add .agents/skills/custom-device-management
+git commit -m "feat(skill): 增加设备管理 skill"
+```
+
+不需要修改 `star-allinone`，也不需要重新发布 npm。
+
+审查、提交、测试环境发布、Mock 和 Service 生成都走公共 skill。只有流水线 ID 放在业务项目的 `.star-allinone.json`。`custom-*` 只用于真正的业务特例，例如设备管理或节点管理。
+
+## 公共部分和业务定制组合
+
+例如业务定制 skill 需要复用公共 API 生成流程：
+
+```text
+.agents/skills/custom-device-service/SKILL.md
+```
+
+内容中引用公共 skill：
+
+```md
+---
+name: custom-device-service
+description: Generate StarScope device service code.
+---
+
+本任务需要结合公共 skill `shared-api-to-service` 执行。
+
+先读取并遵循：
+
+`.agents/skills/shared-api-to-service/SKILL.md`
+
+再读取当前项目的：
+
+- OpenAPI 文件
+- Service 约定
+- 项目类型和权限规则
+
+只生成符合当前项目结构的设备相关 service。
+```
+
+公共 skill 负责通用流程，业务 skill 负责具体业务规则。
+
+## 项目配置
+
+项目差异配置放在业务项目中，例如：
+
+```text
+starscope-frontend/
+├── .star-allinone.json
+└── .agents/
+    ├── skills/
+    └── project/
+        ├── conventions.md
+        ├── review-rules.md
+        └── openapi.json
+```
+
+```json
+{
+  "project": "starscope-frontend",
+  "publicSkillPrefix": "shared-",
+  "serviceDir": "src/services",
+  "openapi": ".agents/project/openapi.json",
+  "publishPipelineId": "5108336"
+}
+```
+
+StarLink 使用：
+
+```json
+{
+  "project": "starlink-frontend",
+  "publicSkillPrefix": "shared-",
+  "publishPipelineId": "5245265"
+}
+```
+
+完整示例见 `examples/projects/`。
+
+可选字段 `sharedSkills` 用于只同步部分公共 skill；省略时同步 `skills/shared` 下的全部公共 skill。
+
+## 公共规则写在哪里
+
+| Skill | 规则位置 | 覆盖内容 |
+| --- | --- | --- |
+| `shared-api-to-service` | SKILL + `references/service-conventions.md`、`api-artifact-generation.md` | 指定 operation、`MFRequest` 映射、namespace 类型、snake_case、schema 闭包、禁止改 transport |
+| `shared-api-mock` | SKILL + `references/mock-conventions.md` | 对话 JSON 默认、完整响应信封、分页/空列表/错误场景、禁止 handler 和随机数 |
+| `shared-design-to-page` | SKILL + `references/page-conventions.md`、`overlays.md` | 页面分层、`MFProTable`、`ProForm`、权限、异步、`HocModal` 弹层合同 |
+| `shared-project-conventions` | SKILL + `references/architecture.md`、`review-checklist.md`、`quality-checklist.md` | 架构边界、质量禁令、审查清单；其他 skill 会引用这些文件 |
+| `shared-verify` | SKILL | 成套产物检查、await/loading/弹层、验证命令和报告格式 |
+| `shared-impact-analysis` | SKILL | 只读影响分类和回归路径 |
+| `shared-ai-review` | SKILL | Hooks、契约、权限、性能、安全的 P0–P3 审查 |
+| `shared-commit-current-changes` | SKILL | 确认门禁、中文 Conventional Commit、禁止未确认就提交 |
+| `shared-review-and-submit` | SKILL | impact → verify → commit review 编排 |
+| `shared-publish-test` | SKILL + `scripts/publish-current-branch.sh` | 云效测试流水线发布；只从 `.star-allinone.json` 读取 `publishPipelineId` |
+
+以下内容**不**写进公共 skill 源码：
+
+- 流水线 ID：放在业务项目 `.star-allinone.json` 的 `publishPipelineId`
+- OpenAPI 快照：业务仓库数据文件，路径由 `.star-allinone.json` 的 `openapi` 指向
+- 真正的业务特例：权限常量名、Clear Cache 登记、IP 校验、设备/节点领域规则，放 `custom-*`
+
+## 最终推荐流程
+
+公共 skill：
+
+```text
+star-allinone 修改
+→ 发布 npm
+→ 业务项目升级 npm
+→ 执行 skills sync
+→ 提交 .agents/skills/shared-*
+```
+
+业务定制 skill：
+
+```text
+业务项目直接新增或修改 custom-*
+→ 提交业务项目
+```
+
+最终结构和责任边界：
+
+```text
+.agents/skills/
+├── shared-*    ← npm 包同步，不能在业务项目直接维护
+└── custom-*    ← 业务项目自己维护
+```
+
+这比全局安装更适合团队协作，也比把公共 skill 藏在 `node_modules` 中更可靠，因为公共 skill 最终会进入业务项目仓库，团队成员拉取代码后即可直接使用。

package/skills/shared/ai-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: {{sharedSkillName}}
+description: Review frontend changes for correctness, API and permission contracts, React lifecycle, performance, maintainability, security, accessibility, and test gaps. Use for a standalone review without commit. Do not modify files.
+---
+
+# AI Code Review
+
+This skill is fully shared. Review the current diff plus relevant callers and types. Before reviewing, read:
+
+1. `.agents/skills/shared-project-conventions/references/review-checklist.md`
+2. `.agents/skills/shared-project-conventions/references/quality-checklist.md`
+
+Do not require a project-local review-rules file. If `.agents/project/review-rules.md` exists, apply extra domain checks only; do not weaken shared hard rules.
+
+## Required checks
+
+1. React Hooks: stale closures, incomplete dependencies, request races, updates after unmount, unnecessary rerenders.
+2. API contracts: method/path/params, response unwrapping, pagination, nullability, enum drift, error handling, DTO mismatch.
+3. Permissions: route access, button visibility, mutation authorization, client-only enforcement.
+4. Forms/tables: validation, reset, duplicate submit, refresh after mutation, column-state, long text, empty/error.
+5. Performance: eager `xlsx`/editor imports, duplicate libraries, large lists without virtualization, unstable columns/handlers, avoidable requests.
+6. Security/privacy: tokens, user data, URLs, unsafe HTML, sensitive logs, environment config.
+7. Tests and accessibility: critical paths, failure states, keyboard labels, disabled/loading semantics.
+
+## Output
+
+Lead with findings ordered `[P0]`–`[P3]`, with file and line. Separate blocking issues from recommendations. Do not report style preferences as bugs.
+
+If none, write `No issues found.` Always include validation performed and gaps. Do not modify files unless the user explicitly asks for fixes.

package/skills/shared/api-mock/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: {{sharedSkillName}}
+description: Generate deterministic API mock responses matching the active frontend project's OpenAPI contract and service types. Use when the user asks for JSON fixtures, proxy-ready mock data, empty or error scenarios, or mock files for a specified endpoint.
+---
+
+# API Mock
+
+This skill is fully shared. Read [references/mock-conventions.md](references/mock-conventions.md), `.star-allinone.json`, the related service types, and the OpenAPI file from `openapi` in `.star-allinone.json` (or the document provided in this conversation).
+
+If the service contract is missing, first follow `.agents/skills/shared-api-to-service/SKILL.md`.
+
+## Hard rules
+
+- OpenAPI and existing namespace types are authoritative. Do not invent undocumented fields.
+- Default output is labeled conversation JSON. Write `mock/<api-path>/<method>.json` only when the user explicitly asks for files.
+- Keep the complete backend envelope. Service callers see unwrapped `data`; mocks must not drop `code` / `message` / `data`.
+- Preserve snake_case, required fields, enums, nullability, and pagination totals.
+- Never add runtime handlers, `defineMock`, Faker, current timestamps, or unseeded randomness without an explicit request.
+- Cover requested scenarios only. Success is the default; empty, overflow, zero, validation, and permission cases need an explicit ask or a documented contract.
+
+## Handoff
+
+For every endpoint, report HTTP method, path, scenario label, and one strict parseable JSON block. If files were written, list the paths and confirm they parse as JSON.

package/skills/shared/api-mock/references/mock-conventions.md

@@ -0,0 +1,90 @@
+# Mock Conventions
+
+Default output is conversation JSON. Do not create files, Umi routes, JavaScript, TypeScript, handlers, or server configuration unless the user explicitly asks for files.
+
+## Conversation output
+
+Label each response with HTTP method, API path, and scenario, then provide one strict JSON code block.
+
+```text
+GET /api/v1/devices/ — success
+```
+
+Rules:
+
+- Return the default success scenario unless the user requests another scenario.
+- Use separate labeled JSON blocks for success, empty, validation error, or permission error responses.
+- Preserve OpenAPI placeholders such as `{id}` in the label while using realistic concrete IDs in response data.
+- Do not mention an output filename unless writing a file was requested.
+
+When files are requested, write pure JSON at `mock/<api-path>/<method>.json`. Never generate `defineMock`, Umi imports, handlers, Faker, current timestamps, or unseeded randomness.
+
+## Response shapes
+
+Use the actual OpenAPI response schema even when it differs from these common envelopes.
+
+Ordinary success:
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "device-001",
+    "hostname": "edge-shanghai-001"
+  }
+}
+```
+
+Paginated list. Follow the nearest domain; common shapes are `{ results, count }` or `{ list, total }`:
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "results": [
+      {
+        "id": "device-001",
+        "hostname": "edge-shanghai-001"
+      }
+    ],
+    "count": 1
+  }
+}
+```
+
+Business error:
+
+```json
+{
+  "code": 400,
+  "message": "参数校验失败",
+  "data": {
+    "hostname": ["该字段不能为空"]
+  }
+}
+```
+
+`MFRequest` unwraps `data` for service callers. Mock JSON must keep the complete backend envelope.
+
+## Scenario coverage
+
+- Default successful detail or operation response.
+- Normal list containing representative status and enum variants.
+- Empty list when requested: empty collection and matching total/count `0`.
+- Very long names and remarks for overflow testing.
+- Zero numeric values so UI code does not confuse zero with missing data.
+- Nullable and optional fields only where the contract permits them.
+- Validation and permission errors only when requested or documented.
+
+Static JSON cannot implement pagination, filtering, mutation continuity, or upload parsing. Represent those as separate labeled responses.
+
+## Contract checks
+
+1. Copy the exact path and method from OpenAPI and the service module.
+2. Resolve every `$ref` used by the selected response schema.
+3. Include every required property and preserve snake_case.
+4. Keep enum values, nullability, number/string types, and nested arrays consistent.
+5. Keep pagination totals consistent with the represented collection unless the fixture intentionally shows another page.
+6. Ensure every fenced JSON block is strict, parseable JSON: double-quoted keys and strings, no comments, no trailing commas.

package/skills/shared/api-to-service/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: {{sharedSkillName}}
+description: Generate frontend TypeScript API types, MFRequest service methods, aggregate exports, and contract-aligned mock artifacts for an explicitly selected API operation. Use when the user names an endpoint or operationId and asks to generate or update service, types, or mock data.
+---
+
+# API to Service
+
+This skill is fully shared. Generate only the requested `METHOD /path/` or `operationId`. Do not guess undocumented fields or change unrelated endpoints.
+
+Read before editing:
+
+1. `.star-allinone.json`
+2. [references/service-conventions.md](references/service-conventions.md)
+3. [references/api-artifact-generation.md](references/api-artifact-generation.md)
+4. `.agents/skills/shared-api-mock/references/mock-conventions.md` before producing JSON
+
+OpenAPI lookup order:
+
+1. `openapi` in `.star-allinone.json`
+2. A Swagger/OpenAPI file the user provided in this conversation
+3. Nearest existing domain `typings.d.ts` plus the live endpoint, reported as incomplete if no schema exists
+
+`serviceDir` defaults to `src/services` unless `.star-allinone.json` sets it.
+
+## Workflow
+
+1. Resolve one exact operation. If a path has multiple methods and intent is unclear, ask for the method. Never infer a destructive method.
+2. Recursively resolve parameters, request body, responses, and local `$ref`s. Neighboring methods that share a path are out of scope.
+3. Build the target matrix in `api-artifact-generation.md`. Compare existing types, methods, exports, and mocks. Classify create / update / reuse / conflict.
+4. Report contract conflicts before overwriting deployed behavior.
+5. Update `src/services/<Domain>/typings.d.ts`, the thin `MFRequest` method, and `src/services/index.ts` when the domain export is missing.
+6. Produce the default successful JSON mock. Add empty or error variants only when requested.
+7. Verify formatting, TypeScript, JSON parsing, exact method/path, and a focused diff.
+
+## Hard rules
+
+- Preserve backend snake_case, documented optionality, and `| null` nullability.
+- Type callers against unwrapped `data`. Do not model the transport envelope inside `T`.
+- Prefer named types. Do not use `Record<string, any>` or unexplained `any`.
+- Do not modify `src/services/request.tsx` for one endpoint without explicit approval.
+- Do not generate pages, hooks, or extra mock scenarios unless requested.
+- Never refresh a checked-in OpenAPI snapshot with `cp` or full-file replacement.
+
+## Verification
+
+```bash
+pnpm exec prettier --check <changed-service-and-json-files>
+pnpm exec tsc --noEmit
+```
+
+Parse changed JSON files. Search generated names, operationId, and exact API paths for omissions and collisions. Run `pnpm lint` for broad service changes. Cite the OpenAPI path, method, operationId, and schema names in the handoff.

package/skills/shared/api-to-service/references/api-artifact-generation.md

@@ -0,0 +1,70 @@
+# Specified API Artifact Generation
+
+## Accepted selectors
+
+Resolve a request using one of these forms:
+
+```text
+GET /api/v1/devices/
+PATCH /api/v1/devices/{id}/
+operationId: api_v1_devices_list
+```
+
+Preserve the documented path, including placeholders and trailing slash. Never infer a destructive method.
+
+If a path has multiple methods and intent does not identify one, stop and request the method.
+
+## Target matrix
+
+Before editing, establish this matrix for every requested operation:
+
+| Field            | Value                                              |
+| ---------------- | -------------------------------------------------- |
+| Method and path  | Exact OpenAPI operation                            |
+| operationId      | Documented identifier                              |
+| Domain           | Existing service domain or tag-derived domain      |
+| Parameters       | Path, query, header, and cookie schemas            |
+| Request body     | Content type and resolved schema                   |
+| Success response | Selected status, content type, and resolved schema |
+| Error responses  | Only those needed by the requested artifacts       |
+| Service method   | Existing or proposed public method name            |
+| Types            | Existing types to reuse and new types to create    |
+| Mock output      | Conversation JSON, or `mock/<api-path>/<method>.json` when files are requested |
+
+## Default artifacts
+
+Unless the user narrows the scope, generating `GET /api/v1/devices/` means:
+
+- Request, query, and path-parameter types.
+- Response, item, detail, pagination, enum, and nested object types required by that operation.
+- One thin `MFRequest` method.
+- Domain aggregate export when missing.
+- One deterministic successful JSON response.
+
+Do not generate a page, hook, model, component, test server, or extra mock scenario unless requested.
+
+## Schema closure
+
+Starting from parameters, request bodies, and selected responses:
+
+1. Collect every local `$ref`.
+2. Read the referenced component schema.
+3. Repeat for nested properties, items, `allOf`, `oneOf`, and `anyOf`.
+4. Stop only when all leaves are primitive, inline, or unsupported external references that are explicitly reported.
+
+Generate types only for schemas used by the selected operation. Reuse an existing project type only after verifying required fields, optionality, nullability, enums, and formats.
+
+## Existing artifact decisions
+
+- **Create:** no matching service, type, or mock exists.
+- **Update:** the artifact represents the selected operation but differs from the current contract.
+- **Reuse:** the existing artifact matches semantically; do not rewrite it for formatting or naming.
+- **Conflict:** deployed behavior intentionally differs or sources contradict; report before destructive changes.
+
+Never regenerate an entire service namespace because one endpoint changed.
+
+## OpenAPI snapshot
+
+Treat the project's OpenAPI/Swagger file as authoritative. Lookup order: `openapi` in `.star-allinone.json`, then a document provided in the conversation.
+
+Never refresh a checked-in snapshot with `cp`, full-file replacement, or unconditional formatter output. Report the delta and wait for confirmation before rewriting the snapshot.

package/skills/shared/api-to-service/references/service-conventions.md

@@ -0,0 +1,89 @@
+# Service Conventions
+
+Read `.star-allinone.json` first. `serviceDir` defaults to `src/services`. Overlay extra domain paths only when `.agents/project/conventions.md` exists.
+
+## Layout
+
+```text
+src/services/<Domain>/
+├── <domain>.ts
+└── typings.d.ts
+```
+
+Import the domain default export in `src/services/index.ts` and spread it into the aggregate object. Update an existing domain instead of creating a duplicate.
+
+Pages must not call axios or `src/services/request.tsx` directly. Consume methods through `import Service from '@/services'`.
+
+## Request mapping
+
+Inspect the project's `MFRequest` helper before generating. The common mapping is:
+
+| Contract              | Call                            |
+| --------------------- | ------------------------------- |
+| GET query             | `MFRequest.get(url, params)`    |
+| POST JSON             | `MFRequest.post(url, body)`     |
+| PATCH JSON            | `MFRequest.patch(url, body)`    |
+| PUT JSON              | `MFRequest.put(url, body)`      |
+| DELETE query          | `MFRequest.delete(url, params)` |
+| GET blob export       | `MFRequest.export(url, params)` |
+| POST multipart import | `MFRequest.import(url, params)` |
+
+Do not modify the shared request module for a single endpoint unless the transport capability is missing and the user approves the cross-cutting change.
+
+## Types
+
+- Put DTOs in `src/services/<Domain>/typings.d.ts` using the project's `declare namespace DOMAIN_API` pattern.
+- Pages must not redefine service DTOs.
+- Preserve backend snake_case.
+- Mark a field optional only when the contract may omit it. Use `| null` when it is present but nullable.
+- Prefer named types over `Record<string, any>` when the contract is known.
+- Use `Partial<T>` only for genuinely partial update or filter contracts.
+- Path parameters are explicit function arguments, not fields on the query type.
+- Service callers are typed against the unwrapped `data` payload. `MFRequest` resolves the outer envelope; do not duplicate `code`, `message`/`msg`, or `data` inside `T`.
+- Add concise Chinese JSDoc matching nearby services.
+
+```ts
+import MFRequest from '../request';
+
+/**
+ * 获取设备列表
+ */
+const getDevicesList = (params: DEVICES_API.IDevicesListForm) => {
+  return MFRequest.get('/api/v1/devices/', params);
+};
+
+export default { getDevicesList };
+```
+
+```ts
+declare namespace DEVICES_API {
+  type IDevicesListForm = {
+    page: number;
+    page_size: number;
+    keyword?: string;
+  };
+
+  type IDevicesListResponse = {
+    results: IDevicesListItem[];
+    count: number;
+  };
+}
+```
+
+If the nearest domain uses `{ list, total }` instead of `{ results, count }`, follow that domain. Do not invent a third pagination shape.
+
+## Endpoint checklist
+
+- Exact HTTP method and trailing slash.
+- Path variables and their types.
+- Query versus JSON body versus multipart.
+- Required, optional, and nullable fields.
+- Enum values and display fields.
+- Date/time and numeric units.
+- List pagination and sorting fields.
+- Download filename/content behavior.
+- Empty response semantics for create/update/delete.
+
+## MFRequest side effects
+
+Ordinary requests typically strip `undefined`, `null`, and empty strings. PATCH may convert `undefined` to `null`. Confirm the local wrapper before using `undefined` to mean “unchanged.”