@mingfuyun/star-allinone 0.4.8 → 0.4.10

package/docs/README.md

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

package/docs/skills/README.md

@@ -0,0 +1,13 @@
+# Skills 文档索引
+
+> **维护约定：** 技能说明只改本目录。业务仓删除技能相关 `docs/`，只读 sync 副本。
+
+| 文档 | 对应 skill / 主题 | sync 后业务仓路径 |
+| --- | --- | --- |
+| [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`（由 `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

@@ -0,0 +1,63 @@
+# 研发 Skills 使用指南
+
+> 维护源：能力包 `docs/skills/overview.md`。业务仓勿复制长文。
+
+`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-api-to-service` | 单个 `METHOD /path/` → 类型、Service、可选 JSON Mock |
+| `shared-design-to-page` | 页面（标准列表内部跑 `gen page`） |
+| `shared-review-and-submit` | 提交前审查，确认后再提交 |
+| `shared-publish-test` | 明确要求测发后再跑；`git push` 后不要自动调用 |
+| `shared-tracking` | 埋点接入与补齐 |
+| `shared-prism-mock`（内部，若已 sync 且 `prism.enabled`） | 本地 Prism / `dev:mock` / overrides；说明见 [prism-mock.md](prism-mock.md) |
+| 项目 `custom-*`（内部） | 如全量 swagger / OpenAPI 增量等，见各仓 `AGENTS.md` |
+
+## 示例
+
+```text
+使用 $custom-entry，为 GET /api/v1/devices/ 生成类型、Service 和 JSON Mock。
+```
+
+```text
+使用 $custom-entry，根据设计稿实现管理页面；缺少的 Service、类型一并生成。
+```
+
+```text
+使用 $custom-entry，对当前变更执行提交前审查。等我确认后再提交。
+```
+
+```text
+使用 $custom-entry，把当前分支发布到测试环境。
+```
+
+```text
+使用 $custom-entry，为 GET /api/v1/users/me 写 Prism mock override。
+```
+
+```text
+使用 $custom-entry。契约已更新，请重建相关 Service 并刷新 Prism mock（保留 overrides）。
+```
+
+本地 Prism 详见 [prism-mock.md](prism-mock.md)。接口契约使用**本仓库**自己的 OpenAPI / Swagger，不要复用其他项目的快照或流水线。
+
+## 规范源
+
+- 常驻：业务仓根 `AGENTS.md`
+- 技能正文：能力包 `docs/skills/`（sync 副本在 `.agents/skills/shared-*/references/`）
+- **禁止** `.cursor/rules`；**禁止** `~/.codex/skills` 全局 skill 作业务入口

package/docs/skills/prism-mock.md

@@ -0,0 +1,219 @@
+# Prism Mock
+
+> **维护源（唯一正文）：** 能力包 `docs/skills/prism-mock.md`  
+> sync 后业务仓副本：`.agents/skills/shared-prism-mock/references/guide.md`  
+> 范围：仅 Prism 能力；**不含**整单 workflow / `shared-dev-flow`。  
+> 业务仓不维护 `docs/` 技能文档。
+
+对话经 `$custom-entry` 委托本能力（收口完成后为 `shared-prism-mock`；过渡期星链可能仍为 `custom-prism-mock`）。人读与 Agent 均以本文为准。
+
+---
+
+## 1. 目标
+
+| 目标 | 说明 |
+| --- | --- |
+| 契约前置 | 后端未就绪时，按正式契约 + Service 类型把页面跑通 |
+| 少侵入 | 不改页面 / `MFRequest` / `request.tsx`；只动 proxy 与 mock 产物 |
+| 可协作 | 假数据进仓库（overrides）或可复现生成，不靠本机插件 |
+| 可混跑 | 登录仍走真实 SSO；未进契约的接口仍打真实服务 |
+
+非目标：替代完整联调、模拟有状态审批流、覆盖未进契约的模块。
+
+### 分层
+
+| 层 | 归属 | 内容 |
+| --- | --- | --- |
+| 共享 skill + 本文 | 能力包 | Agent 流程、配置契约、（后续）接入模板 |
+| 项目配置 | `.star-allinone.json` → `prism` | 端口、路径、信封、脚本名 |
+| 运行时 | 业务仓 | proxy、gen、`dev:mock`、overrides **业务数据** |
+| 入口 overlay | `$custom-entry` | 意图委托 |
+
+---
+
+## 2. 日常怎么用
+
+脚本名以配置 `prism.devScript` 为准（默认 `dev:mock`）：
+
+```bash
+pnpm dev:mock    # 生成契约 + Prism + 前端（MOCK=1）
+# 全量真实后端：用项目既有脚本（如星链 pnpm test）
+```
+
+典型会：
+
+1. 跑 `prism.genScript` → 写出 `prism.generatedSpec`（gitignore，勿手改）
+2. 启动 Prism 读该文件
+3. 以 MOCK 启动前端，按规则分流 `/api`
+
+---
+
+## 3. 分流模型（`proxyIntegration: umi`）
+
+```text
+浏览器 → /api/...
+         ↓
+应用 proxy（MOCK=1）
+         ↓
+  ├─ authPathPrefixes 命中     → 真实后端
+  ├─ path ∈ 正式契约（openapi） → Prism 127.0.0.1:<mockPort>
+  └─ 其它 /api/**              → 真实后端
+```
+
+| 组件 | 典型路径 | 作用 |
+| --- | --- | --- |
+| 分流 | `config/prism.ts` + 应用 proxy | Prism vs 真实 |
+| 生成 | `prism.genScript` | TS / overrides → 生成契约 |
+| 启动 | `package.json` → `prism.devScript` | 一键 |
+| 人工数据 | `prism.overridesDir/**` | 定制接口 |
+| Agent | `shared-prism-mock`（经 entry） | 见下文 A–E |
+
+依赖：`@stoplight/prism-cli`、`concurrently`（通常为 devDependencies）。
+
+兼容：前置依赖接口用 overrides；半 mock（同页 Prism + 真实）；Chrome 插件不作为团队主路径。
+
+---
+
+## 4. `.star-allinone.json` → `prism`
+
+未配置或 `enabled !== true` → Agent **不改业务代码**（可说明如何启用）。
+
+复用顶层：`openapi`（正式契约）、`serviceDir`、`project`。
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `enabled` | — | 启用必为 `true` |
+| `mockPort` | `4010` | 可用 `MOCK_PORT` 覆盖 |
+| `generatedSpec` | `swagger.prism.json` | gen 输出 |
+| `overridesDir` | `mock/overrides` | 人工假数据根目录 |
+| `authPathPrefixes` | `[]` | 始终真实 |
+| `skipOpenapiPathPrefixes` | — | 不写入生成契约 |
+| `skipServiceDirNames` | `[]` | 扫描服务目录跳过 |
+| `devScript` | `dev:mock` | |
+| `genScript` | `scripts/prism/gen-prism-mock.mjs` | |
+| `proxyIntegration` | `umi` | `umi` \| `other` |
+| `envelope.*` | code/msg/data/`0` | 响应信封 |
+| `mockSourceExtensionKey` | `x-mock-source` | 星链现状可用 `x-starlink-mock-source` |
+
+示例 JSON：能力包内 `skills/shared/prism-mock/references/example-prism-config.json`。
+
+### Agent 读配置
+
+1. 先读 `.star-allinone.json`；无 `prism.enabled === true` 则停止写代码。  
+2. 契约路径只用顶层 `openapi`。  
+3. overrides：`{overridesDir}/<path-without-leading-slash>/<method>.json`，`{param}` → `id`。  
+4. 禁止抄他仓 `authPathPrefixes` / pipelineId。
+
+---
+
+## 5. 假数据优先级与 overrides
+
+生成时：`override` > Service 返回类型（TS）> 契约 `schema`。  
+生成可去掉 `security`、放宽 required，**不会**改正式契约。
+
+路径：
+
+```text
+{overridesDir}/<api-path>/<method>.json
+```
+
+例（默认 overridesDir）：
+
+| 接口 | 文件 |
+| --- | --- |
+| `GET /api/v1/system-configs` | `mock/overrides/api/v1/system-configs/get.json` |
+| `GET /api/v1/users/me` | `mock/overrides/api/v1/users/me/get.json` |
+| `GET /api/v1/ip-pools/{id}` | `mock/overrides/api/v1/ip-pools/id/get.json` |
+
+完整信封推荐；也可只写 `data`。列表枚举等须与页面约定一致。
+
+**不要：** 手改生成物；在正式契约写 mock examples；在页面/Service import 假数据；清空 overrides「刷新」。
+
+查看：有 override 打开 JSON；否则看生成契约 examples；或 `curl` mock 端口。
+
+---
+
+## 6. 与 `shared-api-to-service` mock 的边界
+
+| | Prism | api-to-service mock |
+| --- | --- | --- |
+| 目的 | 本地 Prism + 代理 | 单接口对话/文件 JSON |
+| 假数据主路径 | `overridesDir` + 生成契约 | 非 Prism |
+
+历史 `mock/api/**`（非 overrides）不得当作 Prism 源。
+
+---
+
+## 7. Agent 流程（A–E）
+
+### A. 说明 / 排查
+
+`pnpm <devScript>`；按分流表解释；不建议改页面/Service/插件主路径。
+
+### B. 定制接口
+
+确认 path 在正式契约 → 写 override → 重跑 devScript；可用 gen 校验来源标记。
+
+### C. 刷新生成物
+
+改 typings / `MFRequest` 泛型 → 重跑 gen/devScript。
+
+### D. 初始化 / 接入
+
+对齐清单：`prism` 配置、分流文件、proxy、gen/devScript、overrides、entry 委托。  
+（模板拷贝：后续迭代；当前以业务仓已有落地为准。）
+
+验收：devScript 可起；契约接口可 curl；非 mock 脚本仍全真实。
+
+### E. 契约更新后刷新
+
+正式契约与 Service 已更新 → gen → **保留** overrides → 汇报计数与可能过期 path。
+
+### 硬约束
+
+- 禁止把流程抄进 `custom-*` 再改一版；差异用 `prism` + entry。  
+- 禁止改 `shared-*`。  
+- 单接口 Service → `shared-api-to-service`。
+
+---
+
+## 8. 对话示例（经 `$custom-entry`）
+
+```text
+使用 $custom-entry。契约已更新，请重建 Service 并刷新 Prism mock（保留 overrides）。
+```
+
+```text
+使用 $custom-entry，检查并补齐本仓 Prism 能力（config/proxy/gen/devScript/overrides/委托），不要改业务页面。
+```
+
+```text
+使用 $custom-entry，为 GET /api/v1/users/me 增加/更新 Prism override，数据如下：{ ... }
+```
+
+---
+
+## 9. 验收清单
+
+- [ ] `pnpm <devScript>` 可启动  
+- [ ] curl 契约内接口有预期 JSON  
+- [ ] 登录 / SSO 仍打真实服务  
+- [ ] 未进契约的接口仍打真实  
+- [ ] 非 mock 脚本行为与接入前一致  
+- [ ] 业务代码无新增 mock 分支  
+
+---
+
+## 10. 收口步骤（仅 Prism）
+
+| 步骤 | 动作 | 状态 |
+| --- | --- | --- |
+| P0 | 本文进 `docs/skills/`；skill 骨架；sync 写入 `references/guide.md` | ✅ |
+| P1 | 业务仓写入 `prism` 配置段 | 待做 |
+| P2 | 能力包 `templates/` 参数化运行时 | 待做 |
+| P3 | 发版 → 业务仓升级 + sync | 待做（本地已可 sync） |
+| P4 | entry 委托 `shared-prism-mock` | 待做 |
+| P5 | 业务仓删除 `docs/` 技能文档，只读 sync 副本 | ✅ |
+| P6 | 删除/瘦身 `custom-prism-mock`；回归 | 待做 |
+
+**不做：** 整单 workflow、禅道、强制星眼接入。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingfuyun/star-allinone",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "星系运维前端能力包",
   "main": "dist/index.js",
   "bin": {
@@ -28,6 +28,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
     "scripts/cli.js",
     "scripts/gen",

package/scripts/cli.js

@@ -24,6 +24,8 @@ function usage() {
 Run from a business project containing .star-allinone.json.
 
 skills sync writes package skills/shared/* to <project>/.agents/skills/shared-*.
+If docs/skills/<name>.md exists, it is copied to shared-<name>/references/guide.md.
+docs/skills/overview.md is copied to shared-project-conventions/references/skills-overview.md.
 It never writes ~/.codex/skills and never modifies custom-* skills.
 If <project>/AGENTS.md is missing, it copies examples/AGENTS.md once.
 
@@ -121,6 +123,39 @@ function copyTree(source, target, variables, options, relativeRoot) {
   }
 }
 
+function skillGuideSource(skillName) {
+  return path.join(root, 'docs', 'skills', `${skillName}.md`);
+}
+
+/** Copy pack docs/skills/<name>.md into synced skill as references/guide.md (single doc source). */
+function copySkillGuideDoc(skillName, skillTarget, variables, options, relativeRoot) {
+  const source = skillGuideSource(skillName);
+  if (!fs.existsSync(source)) return;
+  const targetPath = path.join(skillTarget, 'references', 'guide.md');
+  const relativePath = path.relative(relativeRoot, targetPath);
+  console.log(`${options.dryRun ? '[dry-run] ' : ''}${relativePath} (from docs/skills/${skillName}.md)`);
+  if (options.dryRun) return;
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const banner =
+    `<!-- 维护源：能力包 docs/skills/${skillName}.md — 勿在业务仓改此副本 -->\n\n`;
+  fs.writeFileSync(targetPath, banner + render(fs.readFileSync(source, 'utf8'), variables));
+}
+
+function copySkillsOverviewDoc(destination, options) {
+  const source = path.join(root, 'docs', 'skills', 'overview.md');
+  if (!fs.existsSync(source)) return;
+  const conventions = path.join(destination, `${DEFAULT_PREFIX}project-conventions`);
+  if (!fs.existsSync(conventions) && !options.dryRun) return;
+  const targetPath = path.join(conventions, 'references', 'skills-overview.md');
+  const relativePath = path.relative(destination, targetPath);
+  console.log(`${options.dryRun ? '[dry-run] ' : ''}${relativePath} (from docs/skills/overview.md)`);
+  if (options.dryRun) return;
+  if (!fs.existsSync(conventions)) return;
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const banner = '<!-- 维护源：能力包 docs/skills/overview.md — 勿在业务仓改此副本 -->\n\n';
+  fs.writeFileSync(targetPath, banner + fs.readFileSync(source, 'utf8'));
+}
+
 function copySkill(source, destination, skillName, prefix, variables, options) {
   const publicName = publicSkillName(skillName, prefix);
   if (publicName.startsWith(CUSTOM_PREFIX)) {
@@ -132,6 +167,7 @@ function copySkill(source, destination, skillName, prefix, variables, options) {
     fs.mkdirSync(skillTarget, { recursive: true });
   }
   copyTree(source, skillTarget, { ...variables, sharedSkillName: publicName }, options, destination);
+  copySkillGuideDoc(skillName, skillTarget, { ...variables, sharedSkillName: publicName }, options, destination);
 }
 
 function pruneStaleShared(destination, prefix, syncedNames, options) {
@@ -178,6 +214,7 @@ function syncProject(options) {
   for (const skillName of skills) {
     copySkill(path.join(skillsRoot, skillName), destination, skillName, prefix, variables, options);
   }
+  copySkillsOverviewDoc(destination, options);
   pruneStaleShared(destination, prefix, syncedNames, options);
   writeSyncStamp(destination, prefix, syncedNames, options);
   seedAgentsMarkdown(target, options);

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',

package/skills/README.md

@@ -50,17 +50,23 @@ Cursor / Codex 的常驻说明只放仓库根 `AGENTS.md`（模板见 `examples/
 
 ```text
 @mingfuyun/star-allinone/
+├── docs/skills/                   # 技能说明唯一维护源（人读 + Agent）
+│   ├── overview.md
+│   └── prism-mock.md
 └── skills/
     └── shared/
-        ├── api-to-service/          # 单接口；mock 规则在 references/
-        ├── design-to-page/          # 页面；标准列表内部跑 gen page
-        ├── review-and-submit/       # 审查并提交；步骤在 references/
-        ├── publish-test/            # 测发
-        ├── tracking/                # 埋点接入
-        ├── project-conventions/     # architecture / component-contract / mfprotable / review-checklist / quality-checklist
-        └── i-have-adhd/             # 用户输出格式
+        ├── api-to-service/
+        ├── design-to-page/
+        ├── review-and-submit/
+        ├── publish-test/
+        ├── tracking/
+        ├── prism-mock/              # SKILL；正文 sync 自 docs/skills/prism-mock.md
+        ├── project-conventions/
+        └── i-have-adhd/
 ```
 
+技能长文只改 `docs/skills/`。`skills sync` 会把 `docs/skills/<name>.md` 写入业务仓 `shared-<name>/references/guide.md`，把 `overview.md` 写入 `shared-project-conventions/references/skills-overview.md`。业务仓不要再维护 `docs/prism-mock.md` 等长文副本。
+
 公共入口写死两边已对齐的硬规则，例如：页面走 `MFRequest`、DTO 放 namespace typings、表格用业务仓 `@/components/CommonTable/MFProTable`（不要从包里找 `MFTablePro`）、`ProForm`、弹层从 `@mingfuyun/star-allinone` 导入 `BaseModal` / `CustomDrawer` / `HocModal`、`await` 必须 try/catch、禁止无说明的 `any`、React 18。
 
 接入或升级后跑 `pnpm exec star-allinone doctor`。

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

@@ -0,0 +1,36 @@
+---
+name: {{sharedSkillName}}
+description: >-
+  Internal. Local Prism mock: proxy routing, generated prism spec, mock/overrides, init scaffolding, and post-contract refresh. Prefer project $custom-entry. Use when user asks for Prism, dev:mock, 定制 mock, overrides, 初始化 Prism, swagger/OpenAPI 更新后刷新 mock, 契约前置, or Chrome mock 替代.
+disable-model-invocation: true
+---
+
+# Prism Mock（共享）
+
+不是用户入口。业务仓对话经 `$custom-entry` 委托本 skill。
+
+## 唯一文档
+
+| 场景 | 路径 |
+| --- | --- |
+| **维护源（只改这里）** | 能力包 [`docs/skills/prism-mock.md`](../../../../docs/skills/prism-mock.md) |
+| 业务仓 sync 后 | `.agents/skills/{{sharedSkillName}}/references/guide.md` |
+
+配置示例：[references/example-prism-config.json](references/example-prism-config.json)
+
+## 执行前
+
+1. 完整 Read 上方「唯一文档」（业务仓读 `references/guide.md`；能力包开发读 `docs/skills/prism-mock.md`）。  
+2. 读业务仓 `.star-allinone.json`；仅当 `prism.enabled === true` 才改 Prism 相关代码。  
+3. 契约用顶层 `openapi`；脚本/目录用 `prism.*`。
+
+## 硬约束（摘要）
+
+- 禁止在业务仓维护技能 `docs/`；只读 sync 后的 `references/guide.md`。  
+- 禁止改 `shared-*`；禁止页面/Service 写死 mock 主路径；禁止手改生成物、清空 overrides。  
+- 单接口 Service → `shared-api-to-service`。  
+- **不包含**整单 workflow / `shared-dev-flow`。
+
+## User-facing output
+
+需要时可读 `.agents/skills/shared-i-have-adhd/i-have-adhd.md`。

package/skills/shared/prism-mock/references/example-prism-config.json

@@ -0,0 +1,26 @@
+{
+  "project": "example-frontend",
+  "publicSkillPrefix": "shared-",
+  "serviceDir": "src/services",
+  "openapi": "swagger.json",
+  "publishPipelineId": "REPLACE_ME",
+  "prism": {
+    "enabled": true,
+    "mockPort": 4010,
+    "generatedSpec": "swagger.prism.json",
+    "overridesDir": "mock/overrides",
+    "authPathPrefixes": ["/api/v1/auth/", "/oauth2/"],
+    "skipOpenapiPathPrefixes": ["/api/v1/auth/", "/oauth2"],
+    "skipServiceDirNames": ["SystemManagement"],
+    "devScript": "dev:mock",
+    "genScript": "scripts/prism/gen-prism-mock.mjs",
+    "proxyIntegration": "umi",
+    "envelope": {
+      "codeField": "code",
+      "messageFields": ["msg", "message"],
+      "dataField": "data",
+      "successCode": 0
+    },
+    "mockSourceExtensionKey": "x-mock-source"
+  }
+}