@mingfuyun/star-allinone 0.4.9 → 0.4.10

package/docs/README.md

@@ -1,15 +1,16 @@
 # star-allinone 文档
 
-技能相关说明**只维护在本仓库**，不要在业务仓复制长文。
+技能与编排口径说明**只维护在本仓库**，不要在业务仓复制长文。
 
-| 目录 | 内容 |
+| 路径 | 内容 |
 | --- | --- |
-| [skills/](skills/README.md) | 各 shared skill 的人读 / Agent 说明（唯一正文） |
+| [skills/](skills/README.md) | 各 shared skill 人读 / Agent 说明 |
+| [skills/dev-flow/](skills/dev-flow/) | 编排口径资产（方案模板、SwaggerGate、Verify、会话协议、门禁） |
 
-业务仓经 `pnpm exec star-allinone skills sync` 后，对应正文会出现在：
+业务仓经 `pnpm exec star-allinone skills sync` 后，`docs/skills/<name>.md` 等会写入：
 
 ```text
 .agents/skills/shared-<name>/references/guide.md
 ```
 
-业务仓**不维护**技能相关 `docs/`；只读 sync 后的 `.agents/skills/shared-*/references/` 副本。
+业务仓**不维护**技能相关 `docs/`；项目差异只写 `custom-entry/references/`。

package/docs/skills/README.md

@@ -6,7 +6,8 @@
 | --- | --- | --- |
 | [overview.md](overview.md) | 入口与 shared/custom 总览 | `.agents/skills/shared-project-conventions/references/skills-overview.md` |
 | [prism-mock.md](prism-mock.md) | `shared-prism-mock` | `.agents/skills/shared-prism-mock/references/guide.md` |
+| [dev-flow/](dev-flow/) | 编排口径（方案模板 / SwaggerGate / Verify / 会话协议 / 门禁） | 先随能力包 docs 维护；日后迁入 `shared-dev-flow/references` |
 
 配置示例（JSON）：`skills/shared/prism-mock/references/example-prism-config.json`（随 skill sync）。
 
-Agent 执行某 skill 时：先读该 skill 的 `SKILL.md`，再读其 `references/guide.md`（由本文档同步生成）。
+Agent 执行某 skill 时：先读该 skill 的 `SKILL.md`，再读其 `references/guide.md`（由 `docs/skills/<name>.md` 同步生成）。

package/docs/skills/dev-flow/gates.md

@@ -0,0 +1,12 @@
+# 确认门禁口令
+
+> 维护源：能力包 `docs/skills/dev-flow/gates.md`  
+> 跨仓统一；三道门禁**互不推断**。
+
+| 门禁 | 口令（须字面接近） | 不可替代为 |
+| --- | --- | --- |
+| 方案 | `确认方案` | 「确认」「OK」、提交/测发口令 |
+| 提交 | `确认提交` / `确认提交并推送` | 方案确认、测发确认、「确认」单字 |
+| 测发 | `确认推送流水线` / `发布测试环境` | push 成功、提交确认、方案确认 |
+
+`确认方案` ≠ `确认提交` ≠ `确认推送流水线`

package/docs/skills/dev-flow/plan-template.md

@@ -0,0 +1,62 @@
+# 实现方案模板（整单 flow）
+
+> 维护源：能力包 `docs/skills/dev-flow/plan-template.md`  
+> 适用：所有接入 `$custom-entry` 的业务仓。整单在改业务代码前须填齐并等待 `确认方案`。
+
+---
+
+## 必填字段
+
+| 字段 | 说明 |
+| --- | --- |
+| 需求摘要 | 一句话目标 + 关键验收点 |
+| 影响路径 | 预计改动的目录/模块（页面、Service、配置等） |
+| 契约结论 | `无` / `有` / `不确定`（不确定则先问，见 [swagger-gate.md](swagger-gate.md)） |
+| 有序 skill 清单 | 按执行顺序列出将委托的 skill / 动作（勿跳步） |
+| 验证点 | 对照 [verify-commands.md](verify-commands.md) 本仓行 + 业务手测项 |
+| 风险 | 公共组件、权限、数据兼容、测发范围等 |
+| 非目标 | 明确不做的事，防止范围膨胀 |
+| 门禁说明 | 本单将停在哪些确认点（方案 / 提交 / 测发） |
+
+---
+
+## 输出骨架（可直接粘贴）
+
+```markdown
+## 实现方案
+
+**需求摘要：** …
+
+**影响路径：**
+- …
+
+**契约结论：** 无 | 有 | 不确定
+- 若有：分支类型（单接口 gen / 全量或增量同步 / + Prism 刷新）→ 见该仓 project-rules
+
+**有序 skill 清单：**
+1. …
+2. …
+
+**验证点：**
+- [ ] …
+- [ ] 本仓 Verify 命令（见 verify-commands）
+
+**风险：** …
+
+**非目标：** …
+
+**门禁：** 确认方案 →（实现）→ 确认提交[并推送] →（可选）确认推送流水线
+```
+
+---
+
+## 试填示例（虚构，星链语境）
+
+**需求摘要：** 在 IP 回收列表增加「备注」筛选，对接已有 query 字段 `remark`。  
+**影响路径：** `src/pages/IPResource/IPRecycle/const.tsx`（及必要时页面）。  
+**契约结论：** 无（契约已含 `remark`，仅前端筛选项）。  
+**有序 skill 清单：** 1）直接改页面列配置（单点，非 flow 亦可）2）`pnpm typecheck`。  
+**验证点：** typecheck；列表搜索备注。  
+**风险：** 无 label 工具栏 placeholder 须符合 project-rules。  
+**非目标：** 不改公共 `MFProTable`；不测发。  
+**门禁：** 若走 flow 则 `确认方案`；入库时 `确认提交`。

package/docs/skills/dev-flow/session-protocol.md

@@ -0,0 +1,51 @@
+# 会话协议（编排输出字段）
+
+> 维护源：能力包 `docs/skills/dev-flow/session-protocol.md`  
+> 整单 / 长会话每轮至少带齐下列字段，便于人扫读与后续 `shared-dev-flow` 落状态。
+
+---
+
+## 字段
+
+| 字段 | 含义 |
+| --- | --- |
+| `phase` | 当前阶段枚举（见下） |
+| `done` | 本轮已完成的动作（短列表） |
+| `blocked` | 卡住原因；无则写 `无` |
+| `next_action` | 下一步由谁做、做什么（含是否等待口令） |
+
+---
+
+## `phase` 枚举
+
+| phase | 说明 |
+| --- | --- |
+| `intake` | 澄清需求 / 判定整单 vs 单点 |
+| `plan` | 输出实现方案 |
+| `await_plan` | 等待 `确认方案` |
+| `swagger_gate` | 契约判定与同步 |
+| `implement` | 按 skill 清单改代码 |
+| `verify` | 跑 Verify 命令与手测点 |
+| `await_commit` | 审阅提案后等待 `确认提交` |
+| `await_publish` | 等待测发确认词 |
+| `done` | 本单目标已完成（或用户终止） |
+
+单点任务可只用子集（如 submit → `await_commit`）。
+
+---
+
+## 示例
+
+```text
+phase: await_plan
+done: 已输出实现方案（契约结论=无；清单 2 步）
+blocked: 等待用户确认方案
+next_action: 用户回复「确认方案」后进入 implement
+```
+
+```text
+phase: await_commit
+done: typecheck 通过；已给出提交提案
+blocked: 等待确认提交
+next_action: 用户「确认提交」或「确认提交并推送」；勿推断测发
+```

package/docs/skills/dev-flow/swagger-gate.md

@@ -0,0 +1,45 @@
+# SwaggerGate（契约变更判定）
+
+> 维护源：能力包 `docs/skills/dev-flow/swagger-gate.md`  
+> 框架通用；**具体 skill 名、契约文件名见各仓** `custom-entry/references/project-rules.md`。
+
+---
+
+## 判定优先级
+
+1. **用户明确声明**（「契约没变」「swagger 已更新」「只 gen 这一个接口」）  
+2. **git diff / 工作区**是否改动本仓契约文件（见 `.star-allinone.json` → `openapi`）  
+3. 仍不确定 → **停问一句**，禁止猜测后跑全量脚本
+
+不确定话术示例：
+
+> 这次是「只生成单个 METHOD/path」还是「契约文件已更新，要全量/增量同步 Service」？
+
+---
+
+## 分支类型（通用）
+
+| 分支类型 | 何时 | Agent 动作 |
+| --- | --- | --- |
+| 跳过 | 契约结论 = 无 | 不跑契约同步 skill |
+| 单接口 gen | 仅一个 `METHOD /path`（或 operationId） | 委托 `shared-api-to-service`；**禁止**全量脚本 |
+| 全量或增量同步 | 整份契约更新 / 多接口重建 | 委托该仓「契约同步」custom skill |
+| 可选 Prism 刷新 | 仓已启用 Prism，且用户要本地 mock 对齐 | 在同步后委托 `shared-prism-mock`（保留 overrides） |
+
+---
+
+## 示例映射（本波试点，非能力上限）
+
+| 仓 | 契约文件 | 单接口 | 全量/增量 | Prism |
+| --- | --- | --- | --- | --- |
+| 星链 `starlink-frontend` | `swagger.json` | `shared-api-to-service` | `custom-swagger-to-markdown`；swagger-sync = 全量后再 Prism | `shared-prism-mock`（`prism.enabled`） |
+| 星眼 `starscope-frontend` | `openapi.json` | `shared-api-to-service` | `custom-openapi-update` | 本波未强制；有 runtime 后再接 |
+| （后续星系仓） | 填本仓 `openapi` | 通常同上 | 填本仓 custom | 按配置 |
+
+---
+
+## 硬约束
+
+- 禁止用「单 path」触发全量/增量同步脚本。  
+- 禁止把某一仓的 skill 名写进 shared 状态机当唯一路径；编排只认**分支类型**，再读 overlay。  
+- 细节冲突时以**该仓** project-rules + intents 为准，并回写能力包示例表（发版）。

package/docs/skills/dev-flow/verify-commands.md

@@ -0,0 +1,26 @@
+# Verify 命令表
+
+> 维护源：能力包 `docs/skills/dev-flow/verify-commands.md`  
+> **一行一仓**；新仓接入时追加行。失败默认**不允许**继续提交（除非用户明确豁免）。
+
+---
+
+## 本波实测（2026-10-14）
+
+| 仓 | 命令 | 硬门槛 | 大致耗时 | 备注 |
+| --- | --- | --- | --- | --- |
+| 星链 `starlink-frontend` | `pnpm typecheck` | 是 | ~4s | `tsc --noEmit`；本机通过 |
+| 星链 | `pnpm exec star-allinone doctor` | 建议 | ~0.5s | 0 error；可能有 skills stale WARN，跟版后 sync |
+| 星眼 `starscope-frontend` | `pnpm typecheck` | 是 | ~4–5s | 本机通过 |
+| 星眼 | `pnpm exec star-allinone doctor` | 建议 | ~0.5s | 0 error；stale WARN 同左 |
+| 星眼（规则补充） | `pnpm exec tsc --noEmit --baseUrl src/.umi` | 按需 | — | project-rules 写明；与 `pnpm typecheck` 二选一即可，编排优先 package script |
+
+| （预留）新星系仓 | `pnpm typecheck` 或项目等价命令 | 是 | — | 接入时实测填耗时 |
+
+---
+
+## 编排用法
+
+- 整单 Verify 阶段：至少跑该仓「硬门槛 = 是」的命令。  
+- `doctor` 有 error 则先修配置/sync，再提交。  
+- lint 是否硬门槛：由各仓 project-rules 声明；本表未列则默认不强制。

package/docs/skills/overview.md

@@ -4,9 +4,19 @@
 
 `shared-*` 来自 `@mingfuyun/star-allinone`，经 `skills sync` 写入业务仓 `.agents/skills/`，**不要在业务仓直接改**。`custom-*` 由业务仓维护。领域规则：`.agents/skills/custom-entry/references/project-rules.md`。
 
+## 整单 vs 单点
+
+| | 整单（flow） | 单点 |
+| --- | --- | --- |
+| 话术 | 「按流程做完：…」 | 「提交代码」「生成某接口」「发布测试环境」… |
+| 先出方案 | 是，等 `确认方案` | 否（submit/publish 自带提案/确认） |
+| 口径文档 | [dev-flow/](dev-flow/)（方案模板、SwaggerGate、Verify、会话字段、[gates.md](dev-flow/gates.md)） | 仍守各 skill 自身门禁 |
+
+口令：`确认方案` ≠ `确认提交` ≠ `确认推送流水线`（详见 [dev-flow/gates.md](dev-flow/gates.md)）。
+
 ## 用户入口
 
-只使用 **`$custom-entry`**。不要直接 `$shared-*`，不要直接调用内部 `custom-*`（如全量 swagger / Prism 实现层）。
+只使用 **`$custom-entry`**。不要直接 `$shared-*`，不要直接调用内部 `custom-*`（如全量 swagger / Prism 实现层）。适用**所有**接入能力包的星系业务仓；仓别差异在各仓 `custom-entry`。
 
 | 经入口委托到 | 用途 |
 | --- | --- |
@@ -15,7 +25,7 @@
 | `shared-review-and-submit` | 提交前审查，确认后再提交 |
 | `shared-publish-test` | 明确要求测发后再跑；`git push` 后不要自动调用 |
 | `shared-tracking` | 埋点接入与补齐 |
-| `shared-prism-mock`（内部，若已 sync） | 本地 Prism / `dev:mock` / overrides；说明见 [prism-mock.md](prism-mock.md) |
+| `shared-prism-mock`（内部，若已 sync 且 `prism.enabled`） | 本地 Prism / `dev:mock` / overrides；说明见 [prism-mock.md](prism-mock.md) |
 | 项目 `custom-*`（内部） | 如全量 swagger / OpenAPI 增量等，见各仓 `AGENTS.md` |
 
 ## 示例

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingfuyun/star-allinone",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "星系运维前端能力包",
   "main": "dist/index.js",
   "bin": {

package/scripts/gen/doctor.js

@@ -15,6 +15,21 @@ const KNOWN_CONFIG_KEYS = new Set([
   'publishPipelineId',
   'sharedSkills',
   'variables',
+  'prism',
+]);
+const PRISM_KNOWN_KEYS = new Set([
+  'enabled',
+  'mockPort',
+  'generatedSpec',
+  'overridesDir',
+  'authPathPrefixes',
+  'skipOpenapiPathPrefixes',
+  'skipServiceDirNames',
+  'devScript',
+  'genScript',
+  'proxyIntegration',
+  'envelope',
+  'mockSourceExtensionKey',
 ]);
 const IGNORE_DIRS = new Set([
   'node_modules',
@@ -167,6 +182,26 @@ function runDoctor(cwd, options = {}) {
     findings.push(check(true, 'ok', `publishPipelineId ${config.publishPipelineId}`));
   }
 
+  if (config.prism != null) {
+    if (typeof config.prism !== 'object' || Array.isArray(config.prism)) {
+      findings.push(check(false, 'error', 'Config "prism" must be an object'));
+    } else {
+      const unknownPrism = Object.keys(config.prism).filter((key) => !PRISM_KNOWN_KEYS.has(key));
+      if (unknownPrism.length) {
+        findings.push(check(false, 'warn', `Unknown prism keys: ${unknownPrism.join(', ')}`));
+      }
+      if (config.prism.enabled === true) {
+        findings.push(check(true, 'ok', 'prism.enabled true'));
+      } else if (config.prism.enabled === false) {
+        findings.push(check(true, 'ok', 'prism.enabled false'));
+      } else if (config.prism.enabled == null) {
+        findings.push(check(false, 'warn', 'prism present but "enabled" missing; shared-prism-mock will not edit code'));
+      } else {
+        findings.push(check(false, 'warn', 'prism.enabled should be boolean'));
+      }
+    }
+  }
+
   const tableFile = existsAny(root, [
     'src/components/CommonTable/MFProTable.tsx',
     'src/components/CommonTable/MFProTable.ts',