@microi.net/cli 4.6.2

package/dist/microi.skills/microi-frontend-sdk/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: microi-frontend-sdk
+description: Microi 前端 SDK 使用规范，适用于 Vue 3、uni-app、H5、PC 网站与 Microi.Client 扩展。用于创建或修改前端请求、登录态、Token 续签、终端会话、上传、文件 URL、ApiEngine、FormEngine 或应用启动代码。
+---
+
+# Microi 前端 SDK
+
+所有 Vue 3 前端项目都应使用 `microi.skills/microi.v8.js` 作为统一的 Microi 前端 SDK。新项目不要复制旧版 Vue2/Vuex 请求封装，也不要重新手写 token、上传、文件 URL、ApiEngine 或 FormEngine 层。
+
+## 必须采用的模式
+
+将 SDK 复制到项目源码目录，通常是：
+
+- uni-app: `src/utils/microi.v8.js`
+- PC Vue 3 网站: `src/utils/microi.v8.js`
+- Microi.Client 扩展页面：如果已有平台请求层就复用；否则从本地工具模块引入 SDK。
+
+在项目请求模块里只创建一个已配置实例：
+
+```js
+import { createMicroiV8 } from './microi.v8.js';
+
+export const V8 = createMicroiV8({
+  apiBase: config.apiBase,
+  fileServer: config.fileServer,
+  webBase: config.webBase,
+  osClient: config.osClient,
+  tokenKey: 'microi_token',
+  userKey: 'microi_user',
+  formQueryEngineKey: 'mall_form_query',
+  maxConcurrent: 8,
+  appendOsClientQuery: true,
+  onAuthExpired: () => {
+    V8.clearToken();
+    uni.reLaunch({ url: '/pages/login/login' });
+  }
+});
+```
+
+在 Vue 3 启动入口挂载：
+
+```js
+import { V8 } from './utils/request.js';
+
+export function createApp() {
+  const app = createSSRApp(App);
+  V8.install(app);
+  return { app };
+}
+```
+
+页面和业务接口模块应从项目请求模块导入已配置实例或薄封装函数，不要直接从标准 skill 文件导入。
+
+## 必须委托 SDK 的能力
+
+- `ApiEngine.Run`：直接调用 `/apiengine/{key}` 时使用 `V8.ApiEngine.Run(key, data)`。
+- 旧版 `/api/ApiEngine/Run` 只有在老系统仍然需要时才使用 `V8.ApiEngine.RunLegacy(key, data)`。
+- FormEngine CRUD 使用 `V8.FormEngine.*`，或使用 `formEngineGet` 这类项目薄封装。
+- 上传使用 `V8.uploadFile`。
+- 图片、头像、富文本图片、二维码、付款凭证、证件和私有文件使用 `V8.assetUrl`、`V8.resolveFileUrl` 或 `V8.resolveAvatarUrl`。
+- Token 与用户缓存使用 `V8.getToken`、`V8.setToken`、`V8.clearToken`、`V8.getUser` 和 `V8.setUser`。
+- 公有 HDFS 上的 AI 应用使用 `microi-ai-app-auth.js` 统一桥接登录：页面和只读演示保持匿名可见，首次持久化 `app_*` 操作弹出登录框，登录成功后携带 Token 重试。后端必须再次识别写代码并以 `V8.CurrentUser.Id` 覆盖 `ClientKey`、`ActorKey`、`UserId`，禁止只靠前端按钮判断。
+- JavaScript 需要平台安全区数值时使用 `V8.getSafeArea`；CSS 仍使用 `env(safe-area-inset-*)`。
+
+`Microi.Client` 主后台运行时已内置前后端同构的 `V8.Http.Get/Post/Patch` 及对应 Response 方法；表单事件、按钮 V8 等宿主前端新代码必须优先使用 `V8.Http`，旧 `V8.Post/Get` 仅作兼容保留，其参数和兼容规则以 `v8-http-integration/SKILL.md` 为准。独立项目使用本 SDK、且不在主后台 V8 宿主中时，才使用 SDK 自身的小写 `V8.get/post`、`ApiEngine`、`FormEngine`；不要把它们与宿主旧版大写 `V8.Post/Get` 混为一谈，也不要假设浏览器可以绕过第三方接口的 CORS。
+
+## 登录与验证码封装
+
+SDK 或项目请求模块必须提供登录所需的系统配置和验证码薄封装，不要让页面散落手写。
+
+要求：
+- 提供 `isEnabledFlag(value)` 或等价工具，统一判断 `Sys_Config.EnableCaptcha`。它必须把 `true`、`1`、`'true'`、`'1'` 识别为开启，把 `false`、`0`、`'false'`、`'0'`、空值识别为关闭。
+- 提供 `getSysConfig()`，内部调用 `V8.GetSysConfig(true)` 或 `/api/DiyTable/GetSysConfig`，并保持当前租户 `OsClient` 一致。
+- 提供 `getCaptcha()`，内部调用 `GET /api/Captcha/GetCaptcha`，`responseType:'arraybuffer'`，从响应头读取 `captchaid`，返回 `{ CaptchaId, ImageSrc }`。
+- 提供账号登录封装时，只有在页面传入验证码时才追加 `_CaptchaId/_CaptchaValue`；不要在未开启验证码时提交空字段。
+- PC Vue、UniApp H5、微信小程序和 App 的账号密码登录都必须使用同一套验证码判断和登录参数契约。
+
+参考薄封装：
+
+```js
+export function isEnabledFlag(value) {
+  if (value === true || value === 1) return true;
+  if (typeof value === 'string') {
+    const text = value.trim().toLowerCase();
+    return text === '1' || text === 'true' || text === 'yes' || text === 'on';
+  }
+  return false;
+}
+
+export async function getSysConfig() {
+  return await V8.GetSysConfig(true);
+}
+
+export async function login(account, pwd, captcha = {}) {
+  return V8.Login({
+    Account: account,
+    Pwd: pwd,
+    _CaptchaId: captcha.CaptchaId || undefined,
+    _CaptchaValue: captcha.CaptchaValue || undefined
+  });
+}
+```
+
+## 请求头规则
+
+SDK 的 `buildHeaders` 必须集中处理所有请求头，不能让页面、业务 wrapper 或上传逻辑各自拼接租户和鉴权头。
+
+- `osclient` 必须作为唯一租户请求头键，值来自当前运行期租户，例如 `demo`。写入前删除已有 `OsClient` / `osclient` / 任意大小写变体。
+- `Authorization` 写入前也必须删除已有 `Authorization` / `authorization` 变体。需要同时兼容平台 Token 时，可以保留单独的 `Token` 请求头，但它也必须先做大小写去重。
+- 页面传入的 `headers` / `header` 要先合并，再统一去重；禁止 `headers.OsClient = ...` 和 `headers.osclient = ...` 同时存在。
+- 小程序授权登录、账号登录、刷新 Token、FormEngine、ApiEngine、上传都必须走同一套去重逻辑。
+- 验收时检查真实网络请求：不得出现 `osclient: demo, demo`、`Authorization: Bearer xxx, Bearer xxx` 这类逗号合并值。
+
+## Token、当前登录用户与当前终端登录协议
+
+Microi 后端不是只保存一个全局 Token。每个租户、每个 `sys_user` 在 Redis 中维护一份 `CurrentToken`，其中 `CurrentUser` 表示平台当前登录用户，`Tokens` 表示该用户的多个当前终端登录。每个终端项至少包含 `Token`、`ClientType`、`Did`、`IP`、`CreateTime`、`UpdateTime`；退出、管理员清除登录信息、同终端重新登录或 Token 轮换都会影响该列表。
+
+登录必须同时标记终端类型和稳定设备 Id：
+
+```js
+const V8 = createMicroiV8({
+  apiBase,
+  osClient,
+  clientType: 'Mobile', // PC / Mobile / H5 / App / WxMiniProgram / VSCode / MCP
+  didKey: 'microi_did'
+});
+
+const result = await V8.Login({
+  Account,
+  Pwd,
+  _ClientType: 'Mobile'
+});
+```
+
+- PC 后台传 `_ClientType:'PC'`，有效期读取 SaaS 引擎 `SessionAuthTimeout`，单位分钟，默认 20 分钟。
+- VS Code 传 `_ClientType:'VSCode'`，优先读取 `VSCodeAccessTokenLifetime`，否则读取 `AccessTokenLifetime`，单位天，默认 30 天。
+- MCP 传 `_ClientType:'MCP'`，优先读取 `McpAccessTokenLifetime`，否则读取 `AccessTokenLifetime`，单位天，默认 30 天。
+- Mobile、H5、App、各类小程序及其它非 PC 终端读取 `AccessTokenLifetime`，单位天，默认 30 天。
+- `did` 通过请求头发送，同一安装或浏览器配置必须稳定持久化；不要每次请求生成新值。标准 SDK 使用 `V8.getDid()` 自动生成和复用。
+- Token 优先从响应头 `authorization` 读取，并立即覆盖本地旧 Token；兼容接口才从响应体读取。每个受保护请求都要接收响应头中的新 Token，因为后端可能在普通请求中自动轮换。
+
+### 续签时机
+
+不要把本地固定 15 分钟当作所有终端的有效期。读取 JWT 的 `exp` 与 `MicroiTokenIssuedAt`，在到期前按以下规则触发以旧换新：
+
+```text
+提前量 = lifetime / 10
+最少提前 5 分钟
+最多提前 1 天
+```
+
+因此默认 PC 20 分钟会在约第 15 分钟续签；默认移动端、VS Code 30 天会在到期前 1 天进入续签窗口。调用：
+
+```js
+V8.startTokenMaintenance();
+
+// UniApp/App/小程序每次回到前台
+await V8.resumeAuthSession(false);
+
+// 主动以旧换新
+const result = await V8.refreshToken();
+```
+
+- Web 同时监听 `visibilitychange`、`focus`、`pageshow`。浏览器可能休眠后台标签页并暂停 `setInterval`，恢复可见时必须立即检查，不能等下一个定时周期。
+- UniApp/App/小程序在 `App.onShow` 调用 `resumeAuthSession(false)`。
+- VS Code 在扩展激活后维护 Token，并在 `vscode.window.onDidChangeWindowState` 恢复焦点时立即检查。
+- 多请求、多 Tab 续签必须 single-flight。PC 后台可使用 Web Locks；收到响应时，如果本地 Token 已被其它 Tab 更新，旧请求不得把旧 Token 覆盖回来或清掉新登录态。
+- 调用 `/api/SysUser/RefreshToken` 时同时传旧 `authorization`、当前 `OsClient`、原终端 `_ClientType`，请求头继续传稳定 `did`。不要频繁无条件换新。
+
+### 失效提示与租户边界
+
+受保护接口返回 `Code=1001/1002`，或 RefreshToken 返回登录失效时，必须原样展示后端 `Msg`，禁止覆盖成固定“登录已过期”。后端会返回 `DataAppend` 诊断：
+
+| `ReasonCode` | 处理方式 |
+|---|---|
+| `JwtExpired` / `SessionExpired` | 展示已过期分钟、小时或天以及过期时间，然后清理当前终端会话并重新登录 |
+| `TenantMismatch` | 提示 Token 所属租户与当前请求租户，切换租户或重新登录；禁止把该 Token 用于当前租户 |
+| `TokenReplaced` | 先检查本地 Token 是否已被其它 Tab/并发请求更新；有新 Token 时重试一次，否则重新登录 |
+| `SessionMissing` | 服务端登录态已退出、被管理员清除或缓存已重建；清理本地 Token 并重新登录 |
+| `AuthVersionChanged` | 后端安全版本已升级，必须重新登录 |
+| `MalformedToken` / `MissingClaims` | Token 无法继续使用，清理并重新登录 |
+
+不要显示完整 Token、用户密码或密钥。日志只记录 `ReasonCode`、终端类型、脱敏 `did`、请求租户和 Token 租户。`TokenOsClient` 只用于提示和诊断，真正鉴权仍以服务端签名、租户和 Redis 当前终端列表为准。
+
+### Token 验收
+
+- PC、移动端、VS Code 分别登录，回读 JWT `ClientType`、`Did` 和有效期，确认命中对应 SaaS 配置。
+- 模拟页面隐藏超过 PC 有效期后恢复，确认先执行续签；若已无法续签，提示精确显示过期时长。
+- 使用 A 租户 Token 请求 B 租户，确认返回 `TenantMismatch`，提示同时包含 Token 租户与当前租户且不泄漏 Token。
+- 同一旧 Token 并发调用两次 RefreshToken，确认复用同一新 Token，后续请求成功。
+- 管理员调用 `ClearUserLoginInfo` 后，旧 Token 返回 `SessionMissing` 或等价明确原因，前端不再循环续签。
+
+## 上传规则
+
+`V8.uploadFile` 是 Microi 前端唯一允许的上传入口。SDK 实现必须：
+
+- 使用 multipart 上传头。`uni.uploadFile` 或 `fetch(FormData)` 不得发送 `Content-Type: application/json`。
+- 租户请求头只发送一个键：`osclient`。添加配置租户前，先移除传入的 `osclient` / `OsClient` 重复键。
+- `formData` 中发送 `OsClient`；开启 `appendOsClientQuery` 时保留接口查询参数 `?OsClient=tenant`。
+- 上传 `Path` 统一从 `options.path`、`formData.Path` 或 `formData.path` 归一化。
+- 移动端上传路径必须是安全相对路径，例如 `mall/pay-proof` 或 `mall/member/avatar`。不要使用 `/mall/pay-proof`、完整 URL、磁盘路径、`..`、`:`、`//` 或 `~`。
+- 项目薄封装要通过 `{ ...options, path: options.path || defaultPath }` 透传全部选项，避免丢失页面级 `headers`、`action`、`anonymous`、`file`、`formData` 和 `silentError`。
+- H5 页面要保留 `uni.chooseImage` 返回的真实 `File` 对象（可用时为 `tempFiles[0].file`）。如果 H5 只返回 `tempFiles[0]` 或 `blob:` / `data:` 临时路径，也要继续传入，不要丢弃。调用 `V8.uploadFile(..., { file, preferFetch:true })`。SDK 必须识别 `File` / `Blob`、`file` / `raw` / `blob` / `originFileObj` 等常见嵌套字段，以及 `blob:` / `data:` 路径，然后优先使用 `fetch + FormData`，必要时在 `uni.uploadFile` 与 fetch 之间回退。
+- 上传提交处理不得使用空 `catch`。要用 `body.Msg` / `error.message` 提示用户，记录错误便于诊断，并在 `finally` 中重置上传状态。
+- 上传响应与普通请求一样可能通过 `Authorization` / `Token` 响应头轮换登录令牌；`fetch(FormData)` 和 `uni.uploadFile` 成功回调都必须先接收新 Token，再发起后续接口。
+
+当上传突然报 `移动端文件上传路径不合法！` 时，先检查实际 multipart 表单字段和请求头。在 Microi 移动端/会员 Token 流程中，后端会在 HDFS 上传前校验 `Path`；错误的 `Content-Type` 会导致后端读不到表单字段，并表现为路径错误。
+
+## 项目封装规则
+
+面向业务页面的函数名要保持稳定。如果已有项目导出 `callEngine`、`formEngineGet`、`getImageUrl`、`parseImages` 或 `uploadFile`，保留这些导出，内部委托给 `V8`。这样既能统一 SDK，又能避免大面积改页面。
+
+正确写法：
+
+```js
+export function callEngine(key, params = {}, options = {}) {
+  return V8.ApiEngine.Run(key, params, { checkCode: true, ...options });
+}
+
+export function getImageUrl(value) {
+  return V8.assetUrl(value);
+}
+```
+
+避免写法：
+
+```js
+uni.request({ url: apiBase + '/apiengine/' + key, header: { Token: token } });
+```
+
+## 仅支持 Vue 3
+
+新的 Microi 前端工作只支持 Vue 3。不要把 Vue2、Vuex、`Vue.prototype` 或 Vue2/uni-app 条件编译加入 `microi.v8.js`。状态管理属于项目本身，通常使用 Pinia 或本地组合函数；SDK 只负责平台访问、请求、鉴权、上传、资源 URL 和小工具。
+
+## Key-Value 枚举的跨端约定（强制）
+
+- PC、UniApp、小程序和 Web 页面遇到简单枚举时，应从字段元数据或业务接口返回的公开 `{Key,Value}` 选项获取数据源；`Value` 只负责展示，`Key` 才能进入表单值、URL、缓存键和接口筛选参数。
+- 不得把中文 `Value` 当作查询条件，也不得在各端复制维护互相漂移的中文/英文映射。若业务接口已返回选项投影，优先直接消费；本地常量只能作为接口暂时不可用时的同 Key 兜底。
+- 页面 URL 需要保存筛选状态时写入稳定英文 Key，返回页面后按 Key 恢复选中项；切换语言只替换 Value，不得改变 URL 和数据库值。
+- 兼容历史数据时，客户端可以短期识别旧 Value，但提交和新 URL 必须立即归一为 Key；长期迁移由服务端完成并回读验证。
+
+## 界面层独立
+
+SDK 不得导入 Element Plus、uni-ui、uView、TDesign、FirstUI、Pinia、Vue Router 或 axios。界面反馈通过可配置适配器提供：
+
+- `toast(message)`
+- `confirm(message)`
+- `onAuthExpired(body, V8)`
+- optional `requestAdapter(options)`
+
+这样同一个 SDK 才能同时用于 uni-app、PC 网站、后台扩展页面和文档演示。
+
+## 验证
+
+将项目改为使用 SDK 后：
+
+- 运行相关构建或类型检查。
+- 至少测试一次需要登录的 ApiEngine 调用和一次匿名调用。
+- 用 `assetUrl` 测试一个图片或上传 JSON 字段。
+- 如果任务涉及鉴权，测试 Token 过期行为。
+- 对 uni-app H5，同时验证移动视口和 PC 浏览器手机壳下 SDK 正常工作。
+
+### 复盘：生产构建被 `.env.local` 的 localhost 地址污染
+
+- 触发场景：本地开发通过 `.env.local` 指向 `localhost` API，发布后的官网仍请求开发者电脑的 loopback 地址，线上出现 `Failed to fetch`。
+- 根因：Vite 会在所有模式加载 `.env.local`；它不是仅开发模式文件。若生产模式没有更高优先级配置，loopback 地址会被编译进正式产物。
+- 通用规则：本地 API 只写入 `.env.development.local`；生产项目必须提供 `.env.production`。独立官网还要在统一 ApiBase 解析层拒绝“生产构建或非本地域名 + localhost/127.0.0.1/::1”，并安全回退到明确的正式 API。
+- 自动化检查：生产构建后扫描 JS 产物不得包含本地 ApiBase，并在正式域名上下文断言接口请求 origin 等于配置的生产 API；本地 `npm run dev` 仍应命中开发 API。
+
+## 搭配 MCI-UI
+
+SDK 负责平台能力，MCI-UI 负责产品界面。新的 Microi Vue3 项目应同时使用：
+
+- `microi.skills/microi.v8.js`：请求、Token、上传、文件 URL、ApiEngine/FormEngine。
+- `Microi.UI/src/theme`：`--mci-*` 设计变量。
+- `Microi.UI/src/uniapp`：移动端/UniApp 组件。
+- `Microi.UI/src/web`：PC 官网和响应式网站组件。
+
+不要在 SDK 内解决界面状态、骨架屏、富文本间距或安全区布局。这一层应使用 MCI-UI 组件处理。
+
+## MicroApp 宿主 Token 同步
+
+Vue3 前端微服务通过 `window.microApp.getData()` 接收主平台上下文时，不能只把 `token` 放进普通配置对象后假设请求会自动携带。标准 `microi.v8.js` 必须支持 `config.token`，且 `getToken()` 要优先读取运行时 token，再回退到 `storage[tokenKey]`。微服务必须复用同一个 V8 客户端实例，不能在每次按钮点击时重新 `createMicroiV8()`。
+
+`getData()` 中的 Token 是宿主传入的快照，只能用于首次引导或宿主确实下发了不同值时更新；不能在每次 `configureMicroiV8()` 时用旧快照覆盖 SDK 已从响应头取得的新 Token。推荐同时配置 `onTokenChanged`，把新 Token 与发起请求所用的旧 Token 回传宿主，宿主通过 `DiyCommon.ApplyAuthorizationToken(newToken, requestToken)` 接力并防止多标签页旧响应回写：
+
+```js
+const microiV8 = V8; // 模块级单例
+let appliedHostToken = '';
+
+microiV8.configure({
+  apiBase: ctx.apiBase,
+  osClient: ctx.osClient,
+  onTokenChanged: (token, requestToken) => {
+    window.microApp?.dispatch?.({ type: 'micro-app:token', data: { token, requestToken } });
+  }
+});
+if (ctx.token && ctx.token !== appliedHostToken) {
+  appliedHostToken = ctx.token;
+  microiV8.setToken(ctx.token);
+}
+```
+
+普通 `request`、浏览器 `fetch(FormData)` 上传和 `uni.uploadFile` 都必须读取响应头的新 Token。验收时必须连续执行至少两个需要登录态的请求（前一个允许发生 Token 轮换），确认后一个仍返回 `Code=1`；不能只看页面首屏渲染成功。

package/dist/microi.skills/microi-left-right-layout/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: microi-left-right-layout
+description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
+---
+
+# Microi 左右树表配置规范
+
+当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
+
+## 适用与禁用场景
+
+- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
+- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
+- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
+
+## 模块配置
+
+目标 `sys_menu` 必须配置：
+
+```json
+{
+  "ComponentName": "树形+表格",
+  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
+}
+```
+
+同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
+
+## `diy_LeftJoinRightView` 字段
+
+| 字段 | 必填 | 含义与写法 |
+| --- | --- | --- |
+| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
+| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
+| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
+| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
+| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
+| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
+| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
+| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
+| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
+| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
+| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
+| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
+| `ShumoHSS` | 否 | 模糊搜索开关。 |
+| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
+| `ShusouSAN` | 否 | 搜索按钮开关。 |
+| `ShushuaX` | 否 | 刷新按钮开关。 |
+| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
+| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
+| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
+| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
+| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
+| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
+
+## 初始化 V8 与分页契约
+
+左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
+
+```js
+var form = V8.Form || {};
+var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
+var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
+var keyword = String(form.inputText || '').trim();
+var query = {
+    _SelectFields: ['Id', 'Code', 'Name'],
+    _OrderBy: 'CreateTime',
+    _OrderByType: 'DESC',
+    _PageIndex: pageIndex,
+    _PageSize: pageSize
+};
+
+if (keyword) {
+    query._Where = [
+        ['Code', 'Like', keyword],
+        ['OR', 'Name', 'Like', keyword]
+    ];
+}
+
+var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
+
+if (result.Code !== 1) {
+    V8.Result = result;
+    return;
+}
+
+V8.Result = {
+    Code: 1,
+    Data: (result.Data || []).map(function (item) {
+        return {
+            Id: item.Id,
+            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
+            Code: item.Code,
+            Name: item.Name
+        };
+    }),
+    DataCount: Number(result.DataCount || 0),
+    PageIndex: pageIndex,
+    PageSize: pageSize
+};
+```
+
+对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
+
+加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
+
+## MCP 实施顺序
+
+1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
+2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
+3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
+4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
+5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
+
+## 移动端要求
+
+- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
+- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
+- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
+- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
+- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
+- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
+
+## 验收清单
+
+- 当前菜单只匹配一条配置，模块路径正确。
+- 左树标题无 `undefined`、`{}`、空白重复项。
+- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
+- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
+- 普通用户不出现仅管理员可用的“页面配置”。
+- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
+- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。

package/dist/microi.skills/microi-microservice/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: microi-microservice
+description: Microi 前端微服务 MicroService 开发与交付指南。用于创建、读取、修改、构建、发布或修复 Vue3 微应用，维护 microi.routes.json，绑定 sys_menu，使用 V8.OpenAppDialog，或通过 MCP 管理 Web、UniApp、MicroService 应用源码和运行时。
+---
+
+# Microi 前端微服务
+
+这里的 MicroService 是运行在吾码主站中的前端微应用，不是 .NET/Java 后端微服务。
+它适合复杂租户页面、多页面应用、完整表格/上传/步骤交互和独立版本交付；业务事务、
+权限和最终校验仍放接口引擎或可信后端。
+
+完整数据模型、文件/路由协议和宿主通信见 `references/runtime-delivery.md`。
+
+## 何时使用
+
+| 需求 | 选择 |
+|---|---|
+| 简单确认 | `V8.ConfirmTips` |
+| 标准单表新增/编辑/查看 | FormEngine / `V8.OpenAnyForm` |
+| 主前端已注册组件 | `V8.OpenDialog` |
+| 3 个以上字段、联动、上传、表格、Tab、步骤条、代码编辑 | MicroService + `V8.OpenAppDialog` |
+| 独立菜单、多页面、AI 在线编辑、本地 Vite、独立发布 | MicroService |
+
+## 默认发现顺序
+
+开始写代码前：
+
+1. `microi_list_applications` 盘点当前租户全部 Web、UniApp、MicroService 和文件清单。
+2. `microi_get_application_context` 默认只读取元数据、文件哈希、运行时和页面；需要少量正文时显式开启内容读取。
+3. 单个大文件按需使用 `microi_get_application_file`，不要为了查看清单把全量源码 Base64 拉入上下文。
+4. 合适应用存在时在其中新增页面/路由，不创建“一页一个微服务”。
+5. 没有合适应用时才脚手架/创建新 AppKey。
+
+所有读写必须使用同一 MCP、ApiBase 和 OsClient。写操作先 dry-run，再按用户授权确认。
+
+## 源码与产物分离
+
+- `sys_microistore`：应用主数据。
+- `mci_ai_app_file`：私有源码清单，内容在私有 HDFS。
+- `mci_ai_app_version`：构建版本。
+- `sys_microiservice`：已发布运行时。
+- `sys_microiservice_page`：页面路由。
+- 编译后的 HTML/JS/CSS/图片放公有 HDFS，源码不公开。
+
+不能从 `sys_microiservice` 公有产物反推完整源码，也不把大 JS/CSS 长期塞数据库 JSON。
+
+## 本地工程
+
+新建和整体升级项目的通用前端架构遵守 `microi-ai-application`：默认使用 Vue 3 单文件组件、Composition API、Vite 和严格 TypeScript。本 Skill 继续负责 MicroService 特有的 Manifest、页面路由、宿主上下文、菜单绑定与发布协议。
+
+项目至少有：
+
+```text
+.microi-micro-app.json
+microi.routes.json
+package.json
+package-lock.json
+tsconfig.json
+vite.config.ts
+index.html
+src/
+```
+
+AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，删除/新增路由后由
+发布流程同步 `sys_microiservice_page`，不要从 Vue 源码猜路由。
+
+构建前遵守本地 OOM 保护；已有 dev server 可复用时不重复启动。独立 Vite 预览缺少
+完整宿主 Token/OsClient/菜单/弹窗上下文，不能替代宿主验收。
+
+## 发布
+
+- 创建/更新元数据：`microi_create_microservice`。
+- 同步私有源码：`microi_sync_microservice_source`。
+- 真实编译目录优先 `microi_publish_application_directory_stream` 流式发布。
+- 只有服务器不支持流式端点且产物很小时，才兼容 `microi_publish_microservice`。
+- 正常发布支持最多 20,000 个文件、总计 20GB；逐文件从磁盘流入 HDFS，不生成整包 Buffer/Base64。几百 MB、1GB 级项目不得自动降级到旧 Base64 发布器。
+- `StorageMode=db` 仅是显式的小型应急恢复模式，不是正常发布容量；当前最多 256 文件/5MB。超过该边界必须修复租户 HDFS/网关并恢复流式文件模式，不能调大数据库内联上限来承载大项目。
+- 每次交付使用同一 `DeliveryBatchId`，并保存 `SourceManifestHash` 与 `RuntimeManifestHash`；源码同步、运行清单、页面切换和入口探测必须能关联到同一批次。
+- 发布后用 `microi_get_application_context`、`microi_get_microservice` 回读。
+- 回读成功还不等于页面可用：必须直接请求稳定入口、版本入口和清单内的 JS/CSS；入口 `502` 且运行时/清单存在时，优先检查 API 节点是否能通过租户 MinIO 内网端点读取公有桶对象。不要反复发布同一份产物掩盖存储读取故障。
+- 服务器暂未部署修复且产物很小时，可把 `StorageMode=db` 与内联 `ContentBase64` 作为短期恢复手段；必须明确记录为临时方案。修复部署后重新流式发布到公有 HDFS，并恢复 `StorageMode=file`，禁止长期把大 JS/CSS 放在数据库 JSON。
+- 子租户发布时，源码、版本资产、回读验签、页面与缓存全部绑定当前 Token 的 `OsClient`；禁止回退到主租户或宿主服务器默认租户。切换前必须由当前 API 节点通过该子租户 HDFS 配置读回每个版本文件并校验大小/SHA-256。
+
+## 菜单与弹窗
+
+菜单 `OpenType=MicroService` 时一次绑定 `MicroServiceId`、
+`MicroServicePageId`、`MicroServiceRoutePath`、`MicroServiceKey`。
+复杂弹窗用 `V8.OpenAppDialog`，业务参数放 `Data`，回调放顶层。
+
+微服务内部禁止调用浏览器原生 `alert/confirm/prompt`。优先复用宿主 `Tips`/`V8.ConfirmTips`；需要由子应用自行承载时，使用 teleport 到 `body` 的品牌化可访问弹层，固定在当前视口正中央并高于宿主滚动内容。长列表只允许一次性加载后在前端内存搜索时，不得随着关键词重复请求服务器。
+
+Token 只通过宿主上下文传递，不硬编码、不放 URL、不写日志。子应用回传成功/取消/
+错误事件，宿主负责提示、关闭和刷新。
+
+`sys_microiservice_page` 是友好路由的页面事实源，`sys_menu` 只负责导航和角色权限。
+无需出现在导航中的按钮页/详情页应在页面元数据设置 `InternalOnly=true`，不创建伪隐藏菜单。
+
+宿主必须提供 `--micro-app-available-width`、`--micro-app-available-height`、
+`--micro-app-safe-area-bottom`，并用 `ResizeObserver`/`visualViewport` 同步 `host:resize`。
+子应用根容器使用 `min-height: var(--micro-app-available-height, 100vh)`；`100vh` 只能作为脱离
+吾码宿主独立预览时的回退值。不得直接写死 `min-height: 100vh`、`calc(100vh - 100px)` 等
+只适配浏览器视口或某个主站布局的高度，否则嵌入 TagsView、弹窗或移动端时会被裁剪或产生双滚动。
+
+加载/协议/运行时异常只由宿主兜底显示；子应用业务错误标记 `handled=true` 后宿主不得重复提示。
+加载失败页至少显示 AppKey、PageKey、路由、版本、入口、HTTP 状态、发布状态、资产来源、挂载状态和安全原因码，并提供重试、返回与复制诊断。
+
+## 验收
+
+- 源码、构建文件、运行时、页面路由和菜单五层分别回读。
+- 直接刷新友好路由与连续切换多个微应用不 404、白屏或实例名冲突。
+- Dialog/Drawer 成功、取消、错误和关闭协议正确。
+- 宿主 API 请求携带当前 Token/OsClient/菜单上下文，普通用户权限正确。
+- 至少验证桌面和窄屏；上传、表格、滚动、弹窗底部操作不被截断。
+- 长弹窗滚动到顶部/中部/底部后，错误提示和确认层仍位于当前视口中央；自动化监听到原生 JavaScript 对话框直接判失败。
+- 本地构建、MCP 发布和真实浏览器验收分别说明，未执行的层不宣称通过。