prime-dev-cli 2.0.8 → 2.0.10

package/skills/prime-workspace/SKILL.md

@@ -1,258 +1,491 @@
 ---
 name: prime-workspace
-description: Use this skill to handle prime-dev-cli workspace operations through natural language, such as starting an env like icrc, checking one app's status, creating or editing mock APIs and Mock.js responses, managing mock scenes, switching proxy targets, and updating microapp bindings.
+description: prime-dev-cli 与它的本地工作台（packages/server，http://localhost:52741）的使用与操作说明。当用户提到 prime、prime-dev-cli、工作台/项目管理页面，或想用自然语言启动或停止某个环境（如 icrc）、查看运行状态与日志、切换代理目标、管理 Mock 场景、调整微应用绑定、切换项目或子仓库分支时使用。
 ---
 
 # prime-workspace
 
-This is the platform-neutral execution spec for `prime-dev-cli`.
+`prime-dev-cli` 用来管理「多个互相关联的前端项目 × 多个环境」。它由三部分组成：
 
-The goal is not to expose raw API endpoints to the user. The goal is to let the user speak naturally, for example:
-- 帮我启动 icrc
-- 停掉 ilink-icrc
-- 看看 iqc 在不在跑
-- 把 icrc 切到 sitnew
-- 给 isource 挂上 ilink-isource
-- 把 /api/user/info 切到异常场景
+| 组成 | 位置 | 作用 |
+| --- | --- | --- |
+| CLI | `bin/cli.mjs`，命令名 `prime` | 同步配置、启动本地工作台 |
+| 本地工作台 | `packages/server`，端口 **52741** | 可视化初始化工作区、配置代理/Mock/微应用、启停环境、批量 Git 操作 |
+| 浏览器插件 | `packages/prime-dev-browser-plugin` | 把页面里的 `<micro-app>` 指到本地 host；服务地址写死 `http://localhost:52741` |
+
+两个核心概念，别混：
+
+- **项目（project）**：`~/Documents/prime-workspace/` 下的一个前端仓库，如 `esource-fe`、`iqc-fe`、`isource-fe`。
+- **环境（env）**：项目内的一种运行形态，如 `icrc`、`idea`、`ilink`，各自有启动命令、本地 host、代理配置。
+
+用户口语里说的多半是**环境名**（「帮我启动 icrc」），而接口参数多数要的是**项目名 + 环境名**同时给出。
 
 ## Preconditions
 
-### Default local server
-- Base URL: `http://localhost:52741`
+### 默认本地服务与可达性
+
+- 工作台地址：`http://localhost:52741`
+- 动手前先确认可达，例如：
+  ```bash
+  curl -s -o /dev/null -w '%{http_code}' http://localhost:52741/api/admin-status
+  ```
+- 不可达时**不要编造结果**：
+  - 包安装用户 → 提示执行 `prime ui`
+  - 仓库开发者 → `pnpm run dev:server` 也行（Turbopack，同样占 52741）
+- 工作台只在本机运行，接口默认**没有鉴权**；`--admin` 只控制前端 UI 显隐，不是服务端权限（详见「工作台」一节）。
+
+### 关键路径速查
+
+| 用途 | 路径 |
+| --- | --- |
+| 运行时配置（服务端真正读取的那份） | `~/.prime-projects.json` |
+| 配置同步的远端 commit | `~/.prime-projects-commit` |
+| 项目工作区根目录（**硬编码，不可配置**） | `~/Documents/prime-workspace/<projectName>` |
+| 进程表 | `~/.prime-processes.json` |
+| 进程日志 | `~/.prime-process-logs/<projectName>-<envName>.log` |
+| Mock 文件 | `~/Documents/prime-workspace/<projectName>/.mock/<apiName>/<method>/<siteName>.cjs` |
+| 多项目编辑器工作区 | `~/.prime-workspaces/<项目名排序拼接>.code-workspace` |
+| 仓库内配置模板 | `config/projects.json`（从 GitLab 同步）、`config/projects.example.json`（离线兜底，**旧结构**） |
+
+### 配置来源
+
+把运行时配置当作唯一事实来源，不要依赖示例配置或旧文档。真实的 `~/.prime-projects.json` 是**以项目名为 key 的对象**（既不是数组，也没有 `workspace` / `selectedProjects` / `projects` 这些顶层字段）：
+
+```jsonc
+{
+  "esource-fe": {                          // key = 项目名 = 工作区目录名
+    "repo": "https://gitlab.../esource-fe.git",
+    "mockingIntercept": false,             // 项目级「Mock拦截」开关
+    "mockOpen": true,                      // 项目级「Mock开启」总开关（服务端会读，见 Mock 一节）
+    "envs": {
+      "icrc": {                            // key = 环境名
+        "host": "http://localhost:8806",   // 本地访问地址，端口由 URL 尾部解析
+        "envFileName": ".env.dev.c.local", // 代理变量写入哪个 env 文件
+        "subApps": ["360-icrc", "micro-components"],  // 环境名字符串数组，见「微应用」
+        "microPath": "/micro/360-icrc",    // 可选，共享宿主下用于识别身份
+        "startCommand": "npm run serve:c",
+        "apiProxies": [
+          {
+            "prefix": "/api",              // 必须以 / 开头，同环境内不可重复
+            "proxyKey": "PROXY_URL",       // 可选，缺省按 prefix 推导
+            "currentProxy": "sit",         // 当前选中的 proxyEnv key
+            "proxyEnv": {
+              "dev": "http://icrc.dev.healthprime.cn",
+              "sit": "http://icrc.sit.healthprime.cn",
+              "uat": "https://icrc-uat.primelifescience.com.cn",
+              "custom": "http://localhost:8828"   // 选 custom 时 URL 不能为空
+            },
+            "rewrite": { "mode": "none" }  // none | remove | replace(+targetPrefix)
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+`proxyKey` 推导规则：`/api` → `PROXY_URL`；其余 `/x-y` → `PROXY_X_Y_URL`（如 `/icrc-api` → `PROXY_ICRC_API_URL`）。
+
+## CLI 用法
+
+命令全集（全局参数只有 `--admin`，且**仅 `ui` 识别**）：
+
+| 命令 | 行为 |
+| --- | --- |
+| `prime init` | 从 GitLab 拉配置，**覆盖式**写入 `~/.prime-projects.json` |
+| `prime ui [--admin]` | 增量更新配置 → 把 `.mock` 下的 `.js` 重命名为 `.cjs` → 在 52741 启动工作台，输出 `Ready` 后自动打开浏览器 |
+| `prime update` | 与 `init` 完全相同（覆盖式更新） |
+| `prime version` | 打印 `prime-cli <版本>` |
+| `prime help` | 打印帮助；无参数或未知子命令也会落到这里 |
+
+`--admin` 必须跟在 `ui` 后面：`prime ui --admin`。它给 Next 进程注入 `PRIME_ADMIN=1`，工作台据此显示管理员 Git 操作流。
 
-### Reachability rule
-Before using any action, first verify that the local server is reachable.
+### 配置是怎么同步的
 
-If the local server is not reachable:
-- do not fabricate results
-- for packaged users, suggest `prime ui`
-- for repository developers, `pnpm run dev:server` is also acceptable
+- 源仓库：`https://gitlab.primelifescience.com.cn/prime-direct/fe/dev-config-source.git`
+- 源文件：仓库内 `prime-dev-cli/config/projects.json`
+- 临时克隆目录：`<系统临时目录>/prime-dev-config-source`
+- 流程：临时仓库不存在则 `clone`；存在则 `fetch` 比 `origin/master` 的 hash 与 `~/.prime-projects-commit`，不同则 `pull`。
+- 写入 `~/.prime-projects.json` 的策略**两种命令不同**：
+  - `prime ui` → `lodash.defaultsDeep(本地, 远端)`，**本地已有值优先**，远端只补缺失的 key；
+  - `prime init` / `prime update` → **整体覆盖**成远端内容。想保留本地改动就别用这两个。
+- 兜底：GitLab 拉取失败且本地配置不存在时，复制 `config/projects.example.json`。该文件是**旧结构**，不要拿它当字段参考。
 
-### Configuration source
-Treat the runtime workspace configuration as the source of truth:
-- current workspace/project/env structure comes from `~/.prime-projects.json`
-- do not rely on stale example config fields if runtime data differs
+### 相关 npm scripts（仓库开发者）
+
+| 命令 | 作用 |
+| --- | --- |
+| `pnpm run dev:server` | Turbopack 开发模式启动工作台 |
+| `pnpm run build:server` + `pnpm run postbuild:server` | 产出 `dist/server`，`prime ui` 依赖它 |
+| `pnpm run refresh:config` | 等价 `prime init` |
+| `pnpm run test:root` | 跑 skill 资产测试 |
+
+## 工作台（packages/server）
+
+启动后自动跳到 `/initialization`。**实际注册的页面只有三个**：
+
+| 路由 | 页面 | 用途 |
+| --- | --- | --- |
+| `/` | 6 行，直接 `redirect('/initialization')` | — |
+| `/initialization` | `ProjectInitializer` | 批量克隆/初始化工作区，admin 下有批量 Git 操作流 |
+| `/configuration?project=<项目名>&tab=<tab>` | 配置主控台 | 环境代理、MicroApp、Mock、启停环境的日常操作 |
+
+> `src/app/code-editor/` 目录存在但**里面没有 `page.tsx`**，该路由并没有注册。别把它当页面写进文档或指给用户。
+
+### 典型操作流程
+
+**一、初始化**
+1. 页面标题「项目初始化」，右上按钮先是「检查中...」，之后变「创建项目空间」。
+2. 点「创建项目空间」→ 按钮变「初始化中...」，出现全局进度条和「正在连接服务器...」。
+3. 项目卡片逐个显示状态：`待克隆 / 克隆中 / 已存在 / 成功 / 失败 / 不完整 / 重试中`。
+   失败卡片可点「重试」，不完整可点「清理项目」，完成后可用「在 Cursor 中打开」（可下拉切 VSCode / WebStorm）。
+4. 结束后出现汇总卡：「初始化完成 / 总项目数 / 成功 / 失败 / 耗时: Ns」。
+
+**二、进配置**
+5. 点项目名（`title="点击进入项目配置"`）→ 跳到 `/configuration?project=xxx`。
+6. 配置页头部：「{项目名} - 项目配置」、`切换项目:` 下拉、`BranchInfo` 分支条、「创建工作区」「在 Cursor 中打开」「返回初始化页面」。
+7. Tab 栏 = 各环境名 + 一个「Mock配置」。**运行中的环境名前有紫色脉冲点**。
+
+**三、配代理与 Mock**
+8. 环境 Tab 左侧「{envName} 环境配置」：设 `prefix`、选「代理环境」、切「路径重写」（none/remove/replace）、「新增前缀」、「保存配置」。
+9. 环境 Tab 右侧「MicroApp代理配置」：勾选要指向本地环境，点「保存配置」或「清空选择」；右上角有「实时/离线」状态点。
+10. Mock Tab：「Mock拦截」「Mock开启」两个开关；「Mock接口列表」支持「新建」「刷新」「一键关闭」「一键开启」、搜索框「搜索接口地址...」；表格列「接口地址/请求方法/当前场景/开启mock/操作」，行内可「编辑」「新增场景」「删除接口」。
+
+**四、启停与看日志**
+11. 环境 Tab 里的「开发服务器控制」：显示「启动命令:」、状态「运行中 (PID: xxx)」/「未运行」、按钮「启动」「停止」「查看日志」，有 host 时显示「访问地址:」。未配启动命令会提示「⚠️ 该环境未配置启动命令」。
+12. 「查看日志」打开对话框「进程日志 - {项目} - {环境}」，日志经 SSE 实时追加，显示「共 N 条日志」，可「重新连接」。
+
+### admin 模式
+
+`prime ui --admin` 只做一件事：让 `/api/admin-status` 返回 `isAdmin: true`，前端据此显隐整块 UI。**这些接口本身没有服务端校验**——admin 是 UI 显隐，不是权限。
+
+`--admin` 解锁（都在 `/initialization`）：
+
+- 「UAT上线前 Git 操作流」（基线固定 `main`）
+- 「武汉协和版本上线前 Git 操作流」（基线固定 `GWH`）
+- 「常用 Git 分支操作」下的批量**分支合并**、批量**新建分支**、批量**删除远端分支**、批量**探测远端分支**
+
+**不需要 admin** 也能用的：「常用 Git 分支操作」下的批量**切换分支**、批量**切换子仓库(submodules/common)分支**——这两个对普通用户开放。
+
+### 实时更新机制
+
+三个 SSE 端点，外加两处轮询：
+
+| 通道 | 端点 | 消费方 |
+| --- | --- | --- |
+| SSE | `GET /api/initialize-workspace` | 初始化页进度与日志（一次性流，完成发 `completion` 后关闭） |
+| SSE | `GET /api/process/logs/stream?projectName=&envName=` | 日志对话框（先推最后 100 行，再每 2 秒增量） |
+| SSE | `GET /api/microapp-proxy-change-stream?env=` | MicroApp 配置变更广播（断线 3 秒重连，每环境最多 10 连接） |
+| 轮询 | `GET /api/process/status` | 配置页每 **5 秒**，驱动运行状态与 Tab 脉冲点 |
+| 轮询 | `/api/current-branch` + `/api/submodule-info` | `BranchInfo` compact **15 秒** / 普通 **30 秒** |
 
 ## Intent-first action map
 
-Do not think in terms of endpoints first. Think in terms of user intent first.
+别从 endpoint 出发，先从用户意图出发。
 
-### 1. Workspace status
-Typical requests:
-- 看下工作空间状态
-- 哪些项目还没准备好
-- 项目空间现在什么情况
-
-Use:
-- `GET /api/check-workspace`
-- `GET /api/process/status`
-
-Return:
-- whether workspace exists
-- project counts
-- existing / pending / incomplete projects
-- currently running envs
-
-### 2. Project drill-down
-Typical requests:
-- 看下 esource-fe
-- 看下 esource-fe 分支
-- 打开 esource-fe
-- 给我建个 ilink-fe 和 iqc-fe 的工作区
+### 1. 工作区状态
+> 看下工作空间状态 · 哪些项目还没准备好 · 项目空间现在什么情况
 
-Use as needed:
-- `GET /api/project-config?project=<projectName>`
-- `GET /api/current-branch?project=<projectName>`
-- `POST /api/open-project`
-- `POST /api/workspace/create`
+- `GET /api/check-workspace` — 返回 `workspaceExists`、`projects[{name,status,message,needsCleanup}]`、`summary{total,existing,pending,incomplete}`
+- `GET /api/process/status` — 不传参返回全部环境的运行状态
 
-### 3. Start / stop / status / logs
-Typical requests:
-- 帮我启动 icrc
-- 停掉 ilink-icrc
-- 看看 iqc 在不在跑
-- 打开 isource 的日志
+回报：工作区是否存在、项目总数、已存在/待处理/不完整各多少、当前有哪些环境在跑。
 
-Use:
-- `POST /api/process/start`
-- `DELETE /api/process/start?projectName=<projectName>&envName=<envName>`
-- `GET /api/process/status?projectName=<projectName>&envName=<envName>`
-- `GET /api/process/logs?projectName=<projectName>&envName=<envName>&tail=100`
-
-When starting one env:
-- use that env's configured `startCommand`
-- report the access URL from that env's configured `host`
-- prefer output like:
-  - 已启动 icrc
-  - 访问地址：`http://localhost:8806`
-
-### 4. Mock project-level control
-Typical requests:
-- 打开 iqc-fe 的 mock 功能
-- 关闭 iqc-fe 的 mock 功能
-- 打开 iqc-fe 的 mock 拦截
-- 关闭 iqc-fe 的 mock 拦截
+### 2. 项目下钻
+> 看下 esource-fe · 看下 esource-fe 分支 · 打开 esource-fe · 给我建个 ilink-fe 和 iqc-fe 的工作区
 
-Use:
-- `GET /api/project-config?project=<projectName>`
-- `PUT /api/project-config`
+- `GET /api/project-config?project=<项目名>`
+- `GET /api/current-branch?project=<项目名>`
+- `GET /api/submodule-info?project=<项目名>&subPath=submodules/common`
+- `POST /api/open-project` body `{projectName, editor?}`（`cursor` | `vscode` | `webstorm`，默认 cursor）
+- `POST /api/workspace/create` body `{projects[], editor?}` — 生成 `.code-workspace` 并调起编辑器
+- `POST /api/retry-project` / `POST /api/cleanup-project` body `{projectName}`
 
-Project-level mock fields:
-- `mockOpen`
-- `mockingIntercept`
+### 3. 启动 / 停止 / 状态 / 日志
+> 帮我启动 icrc · 停掉 ilink-icrc · 看看 iqc 在不在跑 · 打开 isource 的日志
 
-### 5. Mock scene management
-Typical requests:
-- 看 mock 列表
-- 把 /api/user/info 切到异常场景
-- 新建一个超时场景
-- 打开这个场景
-- 关闭这个场景
-- 预览 GET /api/user/info 现在返回什么
-
-Use:
-- `GET /api/mock-file?project=<projectName>`
-- `POST /api/mock-file`
-- `GET /api/mock-file-content?project=<projectName>&apiName=<apiName>&method=<method>&siteName=<siteName>`
-- `PUT /api/mock-file-content`
-- `PUT /api/mock-setting`
-- `PUT /api/mock-open-status`
-- `GET /api/get-mock-data?project=<projectName>&url=<url>&method=<method>`
-
-### 6. Mock deletion and bulk toggles
-Typical requests:
-- 删除这个 mock 场景
-- 删除整个 /api/user mock 接口
-- 一键开启所有 mock
-- 一键关闭所有 mock
+- `POST /api/process/start` body `{projectName, envName, startCommand}`
+- `DELETE /api/process/start?projectName=&envName=`
+- `GET /api/process/status?projectName=&envName=`
+- `GET /api/process/logs?projectName=&envName=&tail=100`
 
-Use:
-- `DELETE /api/mock-file?project=<projectName>&apiName=<apiName>&method=<method>&siteName=<siteName>`
-- `DELETE /api/delete-mock-api?project=<projectName>&apiName=<apiName>`
-- `POST /api/open-all-mock`
-- `POST /api/cleanup-mock`
+`startCommand` 来自该环境的配置。启动成功后按 `host` 报访问地址，输出形如：
 
-### 7. Proxy viewing and editing
-Typical requests:
-- 看 icrc 现在走哪个代理
-- 把 icrc 切到 sitnew
-- 把 ilink 的 /icrc-api 切到 uat
-- 给 ispar 新增 /idea-api
+```
+已启动 icrc
+访问地址：http://localhost:8806
+```
 
-Use:
-- `GET /api/project-config?project=<projectName>`
-- `PUT /api/project-config`
+停止是「双保险」：先按 PID `SIGTERM`→`SIGKILL`，再用 `lsof -i :<端口>` 兜底杀掉占端口的进程。所以手工用 shell 起的服务，工作台也能关掉。
 
-### 8. MicroApp bindings
-Typical requests:
-- 看 icrc 挂了哪些微应用
-- 给 isource 挂上 ilink-isource
-- 清空 iua 的微应用代理
+### 4. Mock 项目级开关
+
+> 打开 iqc-fe 的 mock 功能 · 关闭 iqc-fe 的 mock 拦截
+
+- `GET /api/check-mock-intercept?project=<项目名>` — 同时读回 `mockingIntercept` 与 `mockOpen`
+- `PUT /api/project-config` body `{projectName, projectConfig: {mockOpen, mockingIntercept}}`
+
+两个开关**方向相反，别混**（工作台 UI 也是两个独立开关）：
+
+| 开关 | UI 文案 | 实际做什么 |
+| --- | --- | --- |
+| `mockOpen` | 「Mock开启」 | **用 Mock 顶掉后端**：请求被拦下直接返回 Mock 数据，根本不打到真实后端 |
+| `mockingIntercept` | 「Mock拦截」 | **把真实响应录下来**：放行请求，但把后端返回的 JSON 自动落盘成一个新 Mock 场景 |
+
+一个是「拿 Mock 当后端」，一个是「拿后端造 Mock」。想联调接口用 `mockOpen`，想攒测试数据用 `mockingIntercept`。
+
+两个开关的真实消费方都不在工作台里，而在目标项目 dev server 依赖的 `@prime-lifescience/dev-server`——它把 `http://localhost:52741` **硬编码**为服务地址，每次请求实时回查工作台。细节见下文「Mock 是怎么生效的」。
+
+
+### 5. Mock 场景管理
+> 看 mock 列表 · 把 /api/user/info 切到异常场景 · 新建一个超时场景 · 打开这个场景 · 预览 GET /api/user/info 现在返回什么
+
+- `GET /api/mock-file?project=` — 列目录树
+- `POST /api/mock-file` body `{projectName, apiName, method, siteName, content}` — 新建场景（自动建目录与 `setting.cjs`）
+- `GET/PUT /api/mock-file-content?...&siteName=` — 读写单个场景的 `.cjs` 源码
+- `PUT /api/mock-setting` body `{projectName, apiName, method, currentSite}` — 切换当前场景
+- `PUT /api/mock-open-status` body `{projectName, apiName, method, siteName, isOpen}` — 开关某场景
+- `GET /api/get-mock-data?project=&url=&method=` — 按当前场景执行并返回数据
+
+### 6. Mock 删除与批量
+> 删除这个 mock 场景 · 删除整个 /api/user mock 接口 · 一键开启所有 mock · 一键关闭所有 mock
+
+- `DELETE /api/mock-file?project=&apiName=&method=&siteName=` — 删单个场景（**不允许删到只剩一个**）
+- `DELETE /api/delete-mock-api?project=&apiName=` — 删掉整个接口目录
+- `POST /api/open-all-mock` body `{projectName}` — 所有场景并入 `open`
+- `POST /api/cleanup-mock` body `{projectName}` — 清空所有 `setting.cjs` 的 `open`
+
+### 7. 代理查看与修改
+> 看 icrc 现在走哪个代理 · 把 icrc 切到 sitnew · 把 ilink 的 /icrc-api 切到 uat · 给 ispar 新增 /idea-api
+
+- `GET /api/project-config?project=` — 读 `envs[envName].apiProxies`
+- `PUT /api/project-config` body `{projectName, envName, apiProxies[]}` — 整数组回写，同时重写 env 文件
+
+改动是**按整个 `apiProxies` 数组**回写的，所以要改单项就先读出来、改好、再整体写回。服务端会校验：`prefix` 必须以 `/` 开头且不重复、`currentProxy` 必须存在于 `proxyEnv`、`currentProxy: "custom"` 时 `proxyEnv.custom` 不能为空、`rewrite.mode` 只能是 `none|remove|replace` 且 `replace` 必须带以 `/` 开头的 `targetPrefix`。校验失败返回 400 且**不落盘**。
+
+### 8. 微应用绑定
+> 看 icrc 挂了哪些微应用 · 给 isource 挂上 ilink-isource · 清空 iua 的微应用代理
+
+- `GET /api/all-projects-envs` — 汇总所有项目×环境的 `{projectName, envName, host, repo, apiProxies, subApps, microPath}`
+- `PUT /api/microapp-proxy-config` body `{projectName, envName, selectedItems[]}`
+
+`selectedItems` 写进 `envs[envName].subApps`，语义是**当这个环境作为宿主运行时，把这些「环境」的微应用指向各自的本地 host**。数组元素是**环境名字符串**（如 `"ilink-isource"`），不是「项目/环境」复合标识。
+
+副作用要知道：对每个被选中的环境名，会**遍历所有项目**找出同名 env，把它的 `/api` 前缀代理改成 `currentProxy: "custom"` 且 `proxyEnv.custom` = 当前宿主的 host，并重写它们的 env 文件；同时经 SSE 广播给浏览器插件。注意只改 `/api` 这一个前缀，但**同名 env 若存在于多个项目会全部被改**。
+
+### 9. 分支操作
+> 看下 esource-fe 分支 · 批量切到 xxx 分支 · 批量新建分支 · 跑 UAT 上线流
+
+- 读：`GET /api/branches?project=&subPath=`、`GET /api/current-branch?project=`、`GET /api/submodule-info?project=&subPath=`
+- 单个切换：`POST /api/branch/switch` body `{projectName, branchName, subPath?}`
+- 批量：`POST /api/batch-list-branches`、`POST /api/batch-switch-branch`、`POST /api/batch-list-submodule-branches`、`POST /api/batch-switch-submodule-branch`
+- admin 批量：`POST /api/admin-git-batch-create-branch|delete-branch|merge|probe-remote-branch`
+- 流程：`POST /api/uat-git-flow`（基线锁 `main`）、`POST /api/gwh-git-flow`（基线锁 `GWH`），两者都有 `/abort`
+
+批量 git 接口入参是 `{projects[], ..., dryRun?}`，返回统一为 `operationLogs[]` / `feedbacks[]` / `projectResults[{projectName, success, reason?, rollbackActions?}]`。所有 git 执行都在**临时仓库**里做，`finally` 清理，不动用户的工作区克隆。
+
+分支名规则：不含空格、不以 `-` 开头。UAT 流的 `baseBranch` 必须是 `main`，GWH 流必须是 `GWH`，传错直接 400。
+
+## 机制说明
+
+理解了原理，很多问题就不用猜。
+
+### 代理是怎么生效的
+
+工作台**不转发任何流量**。改代理配置最终做的事是：把结果写进目标项目的 env 文件（`envFileName`），内容形如：
 
-Use:
-- `GET /api/all-projects-envs`
-- `PUT /api/microapp-proxy-config`
+```
+PRIME_PROXY_PREFIX_MAP={"/api":"PROXY_URL","/icrc-api":"PROXY_ICRC_API_URL"}
+PRIME_PROXY_REWRITE_MAP={"/icrc-api":"/api"}
+PROXY_URL=http://icrc.sit.healthprime.cn
+PROXY_ICRC_API_URL=http://...
+```
+
+真正读这些变量、做转发的是**目标项目自己的 dev server**。所以「切了代理但没生效」通常意味着：目标项目的 dev server 需要重启，或者它的 `envFileName` 指错了文件。
+
+`PRIME_PROXY_REWRITE_MAP` 只在存在非 `none` 的 rewrite 时才写入。
+
+### 微前端代理是怎么生效的
+
+微前端代理做的事：**把页面里 `<micro-app>` 元素指向的远端子应用，改成指向你本地的 dev server**。它和接口代理是两条独立链路——前者由浏览器插件改 DOM 属性，后者由 dev server 改请求去向。
+
+整条链路要三个角色齐活：工作台存 `subApps` 配置 → 插件在主世界改写 `url` → 页面加载本地子应用。
+
+**第一步：配置怎么存。** `PUT /api/microapp-proxy-config` body `{envName, projectName, selectedItems[]}`，`selectedItems` 是**环境名字符串数组**，写进 `envs[envName].subApps`。同时有个容易踩的副作用：对每个被选中的环境名，会**遍历所有项目**找出同名 env，把它的 `/api` 前缀代理改成 `proxyEnv.custom = <当前宿主 host>`——只改 `/api` 这一个前缀，但**同名 env 跨项目全改**。
+
+**第二步：插件怎么拿到配置。** 插件把 `http://localhost:52741` 硬编码为服务地址，`fetch /api/all-projects-envs` 拿全量项目×环境，存进 `localStorage` 的 `microapp-subapps-details`。注入方式是 `runAt: 'document_start'` 的 content script 把脚本注入页面**主世界**——必须在 `micro-app` 被 `customElements.define` 之前运行，因为核心手段就是劫持 `customElements.define`。
+
+**第三步：怎么决定改写到哪个 host。** 两级判定：
+
+1. **`microPath` 优先**：共享宿主（`micro-app.*` 域名）下兄弟子应用 **hostname 相同**，靠域名分不开，所以用 `microPath` 认身份——看元素的 `default-page` 或 `url` 是否**包含**该值，多个命中取**最长最具体**的（避免 `/micro/360-icrc` 误吸 `/micro/360-icrc-site`）。
+2. **hostname 兜底**：没有 microPath 命中时，用各环境 `proxyEnv`（新结构为 `apiProxies[].proxyEnv`）的 URL **只比域名**。
+
+两级都遵守同一条铁律：**只有该 env 在 `subApps` 里才改写**。而且 microPath 一旦识别出身份，若不在 `subApps` 里就**保持远端并直接返回，绝不回落到 hostname 兜底**——否则只勾 `micro-components` 时，`360-icrc-site` 会被同宿主下已勾选的兄弟子应用错误吸附。
+
+只处理三个标签：`micro-app` / `micro-app-ilink` / `micro-app-ijudge`。
+
+**第四步：怎么刷新。** 插件订阅 `microapp-proxy-change-stream?env=`，收到变更后提示「MicroApp配置已更新，页面将在3秒后刷新」，3 秒后 **`window.location.reload()` 整页刷新**。断线重连最多 5 次、间隔 3 秒。
+
+**排查顺序**（前两条是前提，别跳过）：
+
+1. 插件装了没 —— 没插件整条链路都不生效
+2. 工作台起着没 —— 地址硬编码，没起来就拉不到配置，插件直接跳过（日志 `[MicroApp Hack] 跳过：无有效配置`）
+3. 该环境在不在 `subApps` 里
+4. 控制台日志会明说结论：`[MicroApp] URL已替换: ...`、`[MicroApp] microPath识别为「X」但未勾选,保持远端: ...`
+
+完整的匹配算法、时序处理、`disable-patch-request` 规则和已知坑见 `references/microfrontend-proxy.md`。
+
+### Mock 是怎么组织的
+
+```
+<workspace>/<项目>/.mock/<apiName>/<method>/<siteName>.cjs   ← 一个场景
+<workspace>/<项目>/.mock/<apiName>/<method>/setting.cjs      ← 该接口的当前状态
+```
+
+- `apiName` = 接口 URL 去掉 query、去掉开头的 `/`、把 `/` 换成 `_`（`/api/user/info` → `api_user_info`，空则为 `root`）
+- `method` 段小写（`get` / `post`）
+- `siteName` 就是用户口语里的**「场景」**
+
+`setting.cjs` 长这样：
+
+```js
+module.exports = {
+  currentSite: 'success',          // 当前生效的场景（单选）
+  open: ['success', '异常场景']     // 允许生效的场景（多选）
+};
+```
+
+`/api/get-mock-data` 要求 `currentSite ∈ open`，否则报「当前场景 "X" 未开启Mock功能」；项目级 `mockOpen` 为 false 时报「Mock功能未开启」。
+
+场景文件里可以直接用 Mock.js，服务端已把 `mockjs` 注入 `Module.prototype.require`：
+
+```js
+const Mock = require('mockjs');
+module.exports = Mock.mock({
+  code: 200,
+  message: '请求成功',
+  data: { 'id|1-100': 1, name: '@cname', 'status|1': ['a', 'b'] }
+});
+```
+
+完整占位符规则见 prime-dev-cli 仓库的 `packages/server/MOCKJS_EXAMPLES.md`。
+
+> 「mock 文件必须叫 `.cjs`」是有原因的：场景文件用 CommonJS 写，而不少项目 `package.json` 里是 `"type": "module"`，`.js` 会 `require` 不了。所以 `prime ui` 每次启动都会把 `.mock` 下的 `.js` 递归重命名为 `.cjs`（幂等，失败只告警不阻断启动）。
+
+### Mock 是怎么生效的
+
+**工作台本身不拦截任何请求**，它只提供配置与数据。真正做拦截的是目标项目 dev server 里的 `@prime-lifescience/dev-server`，它把 `http://localhost:52741` 硬编码为服务地址，在代理链路上实时回查工作台：
+
+| 时机 | 读取 | 条件 | 行为 | 响应头信号 |
+| --- | --- | --- | --- | --- |
+| 请求发出前（`onProxyReq`） | `GET /api/check-mock-intercept?project=` | `mockOpen` 为真 | 再调 `/api/get-mock-data`，拿到数据就**直接返回并中断代理**，请求不会到真实后端 | `X-FROM-MOCK: true`、`Content-Type: application/json`、`X-Real-Origin: http://localhost:52741` |
+| 响应回来时（`onProxyRes`） | 同上 | `mockingIntercept` 为真 | 放行真实响应，把响应体转成 `module.exports = <JSON>;` **落盘成新场景** | `X-MOCK-FILE-CREATED: true` / 失败 `X-MOCK-FILE-CREATE-FAIL: true` |
+
+补充细节：
+
+- `mockingIntercept` 录制时，`apiName` 按同样的规则从请求路径推导，场景名固定为 **「默认场景」**。也就是说：「Mock拦截」开着时，你每刷新一次页面，真实接口的返回就会被记成一个叫「默认场景」的 Mock 文件。重复请求会不断覆盖同一个场景。
+- 只录制 JSON / text 类响应，带 `attachment` 的下载响应跳过。
+- `text/event-stream`（SSE）两类拦截都跳过，原样透传。
+- 代理环境也走这条链路：dev server 直接读 env 文件里的 `PRIME_PROXY_PREFIX_MAP` / `PRIME_PROXY_REWRITE_MAP` 自建代理，不经过工作台转发。
+
+**由此推出三条排查结论：**
+
+- 工作台没启动 → `check-mock-intercept` 请求失败 → 目标项目的 **Mock 和代理会一起静默失效**，且不报错。
+- 「Mock 没生效」 → 先看 `mockOpen`，再看该接口 `setting.cjs` 里 `currentSite` 在不在 `open` 数组里（不满足时报「当前场景 "X" 未开启Mock功能」）。
+- 想确认是不是 Mock 生效了 → 看响应头有没有 `X-FROM-MOCK: true`；想确认有没有被录制 → 看 `.mock` 下是不是多了「默认场景」，或响应头 `X-MOCK-FILE-CREATED`。
+
+### 进程是怎么管的
+
+- 进程表 `~/.prime-processes.json`，元素 `{key, projectName, envName, startTime, port, pid}`，`key` 为 `"<projectName>-<envName>"`。
+- 启动在 `~/Documents/prime-workspace/<项目>` 下 `spawn(cmd, {shell: true, env: {...NODE_ENV: 'development'}})`，端口取自 `envs[envName].host` 的尾部。
+- 启动后等 2 秒，若子进程已 `killed` 视为失败。
+- 状态判断靠 `process.kill(pid, 0)` + `lsof` 探端口，**没有心跳**。查询全部时会顺带探测配置里所有环境的端口，把「手工起的」项目也标成 `running: true, pid: 0`。
+- 日志 `~/.prime-process-logs/<项目>-<环境>.log`，单文件 5MB 轮转、保留 3 个历史、7 天过期。
 
 ## Natural-language routing rules
 
-### Project vs env interpretation
-Normalize both forms:
-- `project` / `projectName`
-- `env` / `envName`
+### 项目名 vs 环境名
+
+两种形态都要能识别：`project` / `projectName` 与 `env` / `envName`。
+
+解释优先级：
+
+- 启动 / 停止 / 日志 / 代理 / 微应用 → 优先当**环境**
+- 打开项目 / 看分支 / 创建工作区 → 优先当**项目**
+
+例子：
+
+- 「帮我启动 icrc」→ `icrc` 是环境
+- 「打开 ilink-fe」→ `ilink-fe` 是项目
+- 「打开 ilink」→ 有歧义，问一句是项目还是环境
+
+对不上时先去 `~/.prime-projects.json` 里找这个 key：能当项目名命中，就是项目；只在某个项目的 `envs` 下命中，就是环境。一个环境名可能对应多个项目，那就问。
 
-Interpretation priority:
-- start / stop / logs / proxy / microapp -> prefer **env**
-- open project / branch / workspace creation -> prefer **project**
+### 访问地址规则
 
-Examples:
-- `帮我启动 icrc` -> treat `icrc` as an env
-- `打开 ilink-fe` -> treat `ilink-fe` as a project
-- `打开 ilink` -> ambiguous, ask whether the user means the project or the env
+环境在跑或刚启动时，面向用户的 URL 取该环境的 `host`。进程接口即使也返回了 `port`，展示时仍以 `host` 为准。
 
-### Access URL rule
-When an env is running or has just been started:
-- derive the user-facing URL from that env's configured `host`
-- if process APIs also return a port, still prefer `host` as the primary display URL
+### 「项目空间」vs「工作区」是两个意图
 
-### Project workspace vs editor workspace
-These are different intents:
-- “创建项目空间” -> initialize/repair local repos
-- “创建工作区” -> create/open a multi-project editor workspace
+- 「创建**项目空间**」→ `POST /api/initialize-workspace`，克隆/修复本地仓库
+- 「创建**工作区**」→ `POST /api/workspace/create`，生成多项目编辑器工作区文件
 
-Do not collapse them into one action.
+别合并成一个动作。
 
 ## Confirmation matrix
 
-Always confirm before:
-- deleting one mock scene
-- deleting a whole mock API
-- opening all mock scenes
-- closing all mock scenes
-- changing microapp selections
-- changing proxies when multiple prefixes may match
+动手前必须先确认，并说清为什么：
 
-Also explain why confirmation is needed.
+| 操作 | 为什么 |
+| --- | --- |
+| 删除一个 Mock 场景 | 删了就没了，无法从工作台恢复 |
+| 删除整个 Mock 接口 | 上一条 × N |
+| 一键开启 / 一键关闭所有 Mock | 影响该项目全部接口的联调表现 |
+| 修改微应用绑定 | 有连带副作用（会改被选中环境的 `/api` 代理并重写 env 文件） |
+| 代理修改且存在多个可能匹配的 prefix | 改错前缀会让请求打到错误后端 |
+| 批量 Git 操作（切分支、新建、删除、合并、UAT/GWH 流） | 影响多个仓库甚至推送远端 |
+| 清理项目（`cleanup-project`） | 递归删除工作区内的项目目录 |
 
 ## Required input rules
 
-### Starting one env
-To start an env reliably, determine:
-- `projectName`
-- `envName`
-- `startCommand` from runtime config
-- `host` from runtime config
-
-If the env name maps cleanly to one configured env, proceed.
-If multiple matches exist, ask a follow-up question.
-
-### Proxy edits
-For proxy edits, determine:
-- `projectName`
-- `envName`
-- target prefix
-- target proxy name or custom URL
-- optional rewrite settings
-
-If the env has multiple prefixes and the user did not specify which one, ask.
-
-### Mock scene operations
-For mock scene operations, determine:
-- `projectName`
-- `apiName`
-- `method`
-- `siteName`
-
-Use “scene” as the user-facing term.
-
-### MicroApp edits
-For microapp operations, determine:
-- `projectName`
-- `envName`
-- `selectedItems`
-
-Important:
-- `selectedItems` are env-name strings
-- they are not full project/env identifiers
-- explain this if the operation may affect expectations
+### 启动一个环境
+
+要凑齐：`projectName`、`envName`、该环境的 `startCommand`、该环境的 `host`。环境名能唯一对上一个配置就往下走，多个匹配就问。
+
+### 代理修改
+
+要凑齐：`projectName`、`envName`、目标 `prefix`、目标 proxy 名或自定义 URL、可选的 rewrite 设置。环境里有多个 prefix 而用户没说哪个，就问。
+
+### Mock 场景操作
+
+要凑齐：`projectName`、`apiName`、`method`、`siteName`。对用户统一用「场景」这个词。
+
+### 微应用修改
+
+要凑齐：`projectName`、`envName`、`selectedItems`。注意 `selectedItems` 是**环境名**而不是完整标识，且会连带改代理——必要时主动说明。
 
 ## Request examples
 
-### Workspace status
+### 查工作区状态
+
 ```http
 GET /api/check-workspace
 ```
 
-### Project config
+### 查项目配置
+
 ```http
 GET /api/project-config?project=esource-fe
 ```
 
-### One env status
+### 查单个环境状态
+
 ```http
 GET /api/process/status?projectName=esource-fe&envName=icrc
 ```
 
-### Start one env
+### 启动一个环境
+
 ```http
 POST /api/process/start
 Content-Type: application/json
@@ -264,7 +497,32 @@ Content-Type: application/json
 }
 ```
 
-### Switch current mock scene
+### 切换代理目标
+
+```http
+PUT /api/project-config
+Content-Type: application/json
+
+{
+  "projectName": "esource-fe",
+  "envName": "icrc",
+  "apiProxies": [
+    {
+      "prefix": "/api",
+      "currentProxy": "sitnew",
+      "proxyEnv": {
+        "dev": "http://icrc.dev.healthprime.cn",
+        "sitnew": "http://icrc.sitnew.healthprime.cn",
+        "custom": "http://localhost:8828"
+      },
+      "rewrite": { "mode": "none" }
+    }
+  ]
+}
+```
+
+### 切换当前 Mock 场景
+
 ```http
 PUT /api/mock-setting
 Content-Type: application/json
@@ -277,19 +535,23 @@ Content-Type: application/json
 }
 ```
 
-### Update env proxy config
+### 新建一个 Mock 场景
+
 ```http
-PUT /api/project-config
+POST /api/mock-file
 Content-Type: application/json
 
 {
-  "projectName": "esource-fe",
-  "envName": "icrc",
-  "apiProxies": []
+  "projectName": "iqc-fe",
+  "apiName": "api_user_info",
+  "method": "get",
+  "siteName": "超时场景",
+  "content": "const Mock = require('mockjs');\nmodule.exports = Mock.mock({ code: 504, message: '超时' });"
 }
 ```
 
-### Update microapp bindings
+### 更新微应用绑定
+
 ```http
 PUT /api/microapp-proxy-config
 Content-Type: application/json
@@ -301,21 +563,35 @@ Content-Type: application/json
 }
 ```
 
+### 创建多项目工作区
+
+```http
+POST /api/workspace/create
+Content-Type: application/json
+
+{
+  "projects": ["ilink-fe", "iqc-fe"],
+  "editor": "cursor"
+}
+```
+
+完整路由契约（含 admin 批量 Git、UAT/GWH 流程、SSE 帧格式）见 `references/api-contracts.md`。
+
 ## Friendly usage examples
 
-### Workspace / project / branch
+### 工作区 / 项目 / 分支
 - 看下工作空间状态
 - 打开 esource-fe
 - 给我建个 ilink-fe 和 iqc-fe 的工作区
 - 看下 esource-fe 分支
 
-### Start / stop / status / logs
+### 启动 / 停止 / 状态 / 日志
 - 帮我启动 icrc
 - 停掉 ilink-icrc
 - 看看 iqc 在不在跑
 - 打开 isource 的日志
 
-### Proxy
+### 代理
 - 看 icrc 现在走哪个代理
 - 把 icrc 切到 sitnew
 - 把 ilink 的 /icrc-api 切到 uat
@@ -337,11 +613,31 @@ Content-Type: application/json
 
 ## Failure handling
 
-If an API fails:
-- name the exact action that failed
-- report whether the likely cause is missing project, missing env, missing local workspace, bad input, or server unavailability
-- do not invent missing values
+接口失败时：
+
+- 说清是哪个动作失败了
+- 判断原因属于哪一类：项目不存在 / 环境不存在 / 本地工作区没克隆 / 参数不合法 / 工作台没启动 / 目标项目 dev server 需要重启
+- **不要编造缺失的值**
+
+请求有歧义时：只问一个窄问题，优先在动手前把项目/环境/prefix/场景的歧义澄清掉。
+
+几个常见报错的含义：
+
+| 报错 | 含义 |
+| --- | --- |
+| `该环境已经在运行中` | 该 `projectName-envName` 已在进程表里 |
+| `项目目录不存在` | 工作区里还没克隆该项目，先去 `/initialization` 初始化 |
+| `未找到运行中的进程(端口未被占用)` | 进程表和端口都没探到 |
+| `Mock功能未开启` | 项目级 `mockOpen` 为 false |
+| `当前场景 "X" 未开启Mock功能` | `currentSite` 不在 `setting.cjs` 的 `open` 里 |
+| `不能删除最后一个场景，每个接口至少需要保留一个场景` | 每个接口至少保留一个场景 |
+| `缺少必要参数，请填写完整后重试。` | 批量 git 接口入参不全 |
+| `分支名称不合法，请避免空格或以 - 开头。` | 分支名校验失败 |
+
+## 参考
 
-If a request is ambiguous:
-- ask one narrow follow-up question
-- prefer clarifying project/env/prefix/scene ambiguity before doing anything destructive
+| 文件 | 内容 |
+| --- | --- |
+| `references/api-contracts.md` | 全部 API 路由的方法、参数、响应契约，以及三个 SSE 端点的帧格式 |
+| `references/microfrontend-proxy.md` | 微前端代理的完整实现：匹配算法、时序处理、`disable-patch-request` 规则、已知坑 |
+| prime-dev-cli 仓库 `packages/server/MOCKJS_EXAMPLES.md` | Mock.js 占位符与规则示例 |