@microi.net/cli 4.6.2

package/dist/microi.skills/microi-ai-application/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: microi-ai-application
+description: Microi 吾码 AI 应用的创建、迁移、工程化开发和交付规范。用于 Web、MicroService、UniApp、H5、响应式网站或游戏类 AI 应用，尤其是选择前端技术栈、生成 Vue 工程、维护 TypeScript 源码、接入登录与接口引擎、构建发布、二次开发和多端验收。
+---
+
+# Microi AI 应用
+
+## 默认技术基线
+
+新建或整体升级的 Web、MicroService 和 H5 AI 应用默认使用：
+
+- Vue 3 单文件组件与 Composition API，优先 `<script setup lang="ts">`。
+- Vite 作为开发服务器和生产构建工具，`base: './'`。
+- TypeScript 严格类型检查；业务模型、接口入参、快照、事件和状态机不得长期使用散装 `any`。
+- 原生 ESM 继续作为模块标准。Vue 与 Vite 本身就在 ESM 之上工作，不能把“ESM”和“Vue + Vite”描述成互斥方案。
+- 依赖使用受支持的稳定版本并提交 lockfile。先验证 Node LTS、Vue、Vite、TypeScript 和插件的兼容范围，不盲目追随预发布版。
+
+Vue Router 只在有多个可分享路由时引入；Pinia 只在跨页面或跨组件共享复杂状态时引入。单页局部状态使用组合函数。后台数据录入可以使用 Element Plus；独立 Web、官网和游戏界面使用 Microi.UI / MCI-UI token 与项目组件。
+
+UniApp 使用 Vue 3 + TypeScript 的官方 Vite 工具链，并同时遵守 `microi-uniapp-frontend`。Canvas/WebGL 游戏仍让渲染循环保持独立模块，Vue 负责大厅、登录、房间、设置、HUD 和结算等 DOM 界面。
+
+仅在用户明确要求、目标运行环境不能构建，或内容确实是一次性且无状态的极小静态页时，才允许原生 HTML/JavaScript 例外；在交付说明中记录原因、升级路径和验收范围。
+
+详细目录、类型边界和配置样例见 [references/frontend-baseline.md](references/frontend-baseline.md)。
+
+## 开始前
+
+1. 调用 `microi_list_applications` 盘点目标 `ApiBase + OsClient` 的全部在线应用。
+2. 对目标应用调用 `microi_get_application_context`，核对类型、源码清单、版本和构建产物；只读清单不能代替源码完整性检查。
+3. 确认 `ApplicationType`：独立站点和游戏用 `Web`，宿主内多页面定制用 `MicroService`，跨端应用用 `UniApp`。
+4. 读取 `microi-frontend-sdk`、`ui-design`；MicroService 再读取 `microi-microservice`，UniApp 再读取 `microi-uniapp-frontend`，游戏或复杂媒体再读取 `ui-design/references/motion-and-media.md`。
+5. 在项目根目录维护 `.microi-micro-app.json`；源码必须位于当前租户的 `Microi-V8-Engine/.../AI应用/{appKey}`，不得跨租户复用目录。
+
+## 工程边界
+
+- `src/components` 保存可复用展示组件，`src/pages` 保存页面，`src/composables` 保存 UI 用例，`src/domain` 保存纯 TypeScript 业务规则，`src/services` 保存 API/实时通信适配，`src/platform` 保存 Microi 桥接。
+- 规则核心不得依赖 Vue、DOM、localStorage 或 SignalR，保持确定性并可单元测试。
+- 页面不得直接拼 `/apiengine`、Token、上传或文件地址；统一使用项目级 Microi SDK 实例和薄服务层。
+- 公有 HDFS 应用使用标准 `microi-ai-app-auth.js` 登录桥。服务端始终从 Token 恢复 `V8.CurrentUser`，覆盖客户端提交的用户标识。
+- 写操作、发牌、出牌、结算、库存或审批等业务事实走接口引擎或可信后端事务。通用 SignalR 只广播成功结果中 `DataAppend.RealtimeEvent` 的公共投影，私有或按用户裁剪的权威 Snapshot 继续走 HTTP 接口引擎；共享数据库、Redis 或状态机才是事实源。事件携带 `EventId` 与单调 `Version`，客户端检测版本缺口后重新拉取 Snapshot，断线重连按 EventId 幂等恢复。
+- 新业务使用平台通用 v2 `/api-engine-realtime`，以普通登录 Token 调用 `SubscribeChannel`。30 秒时隙租约必须按返回的 `RenewAfterMilliseconds` 重复订阅续租，每次续租由 `realtime_{channel_key}_authorize` 按 `V8.CurrentUser` 重新授权；现有 AccessKey 在没有 `realtime:subscribe` scope 时拒绝。不要为每个游戏或业务再新增专用 C# Hub；旧 `/game-realtime` 仅作兼容。
+- 环境配置从 `window.__MICROI_APP_CONTEXT__`、宿主上下文和模式文件解析。生产构建拒绝 localhost；开发地址只写 `.env.development.local`。
+
+## Vue 实现规则
+
+- SFC 模板承担真实 DOM 结构；事件使用 Vue 绑定，状态使用 `ref/reactive/computed`，副作用在组合函数的生命周期内注册并清理。
+- 组件以业务语义命名，如 `RoomLobby`、`GameTable`、`AudioMixer`、`SettlementDialog`，不要按颜色或位置命名。
+- 长连接、轮询、音频上下文、动画帧、观察器和全局事件必须在卸载时释放；页面隐藏时暂停非必要工作。
+- 响应式布局至少覆盖 1440px 桌面和 390px 移动视口；使用安全区、44px 触控目标、键盘焦点和 `prefers-reduced-motion`。
+- 音频应用必须区分背景音乐、人声和效果音，分别调节、静音和持久化；浏览器首次用户手势前不得强制播放。
+- 不使用原生 `alert/confirm/prompt`；使用宿主反馈或可访问的 MCI 弹层。
+
+## 存量迁移
+
+采用绞杀式迁移，避免一次重写破坏已经验证的规则：
+
+1. 先把纯规则、API、音频和实时客户端固定为可测试模块。
+2. 建立 Vue 3 + Vite + TypeScript 入口、SFC 页面壳和统一平台适配。
+3. 按登录/大厅、房间、牌桌或舞台、设置、结算的顺序替换命令式 DOM。
+4. 过渡代码只允许放在明确的 `legacy/` 目录，不得新增业务逻辑，并为剩余边界建立测试。
+5. 只有命令式 DOM 查询/写入和全局事件已迁移、类型检查通过，才能声明“完整 Vue 架构迁移”；仅用 Vue 挂载旧 HTML 不算完成。
+
+迁移期间保持接口引擎 Key、请求幂等键、版本字段、隐私投影和旧正式 URL 兼容。不要为追求框架统一重写已验证的游戏规则。
+
+## 构建与发布
+
+1. 先检查内存和已有 Node/Vite 进程，只运行一个高资源构建。
+2. 依次执行类型检查、单元测试、生产构建和产物静态扫描。
+3. 检查 `dist/build` 不含源码、Token、密钥、localhost、source map 或陈旧 chunk。
+4. 同步私有源码，再流式发布公有构建目录；源码同步失败不得继续发布。发布前回读并冻结应用的 `CurrentVersion` 与 `AppVersion`，stage 只上传不可变版本资产，finalize 必须同时提交 `ExpectedCurrentVersion` 与 `ExpectedAppVersion` 做 compare-and-set；缺一项、状态漂移或回读不一致都停止，不能自动覆盖较新发布。
+5. Web/UniApp 使用 `/{OsClient}/ai-app-publish/{AppKey}/index.html`；MicroService 使用 `/micro-app/{OsClient}/{AppKey}/index.html`。不要因技术栈相同而混淆运行类型。
+6. 回读应用、版本、active 文件清单和 SHA-256；旧清单文件只能可逆归档，不能删除。再直接请求稳定入口、不可变版本入口及主要 JS/CSS。
+
+## 完成定义
+
+- `vue-tsc --noEmit`、单元测试和生产构建通过。
+- 源码、lockfile、Manifest、构建版本和远端文件哈希一致。
+- 匿名、登录、Token 失效、权限不足、弱网、重连和错误恢复有确定结果。
+- PC 和移动真实浏览器截图通过，控制台无错误，刷新/分享 URL 可恢复状态。
+- 多人或分布式功能必须使用不同账号和至少两个 API 节点验收；本地单进程或静态代码检查不能宣称生产多人闭环。

package/dist/microi.skills/microi-ai-application/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Microi AI 应用开发"
+  short_description: "以 Vue 3、Vite、TypeScript 构建可维护的吾码 AI 应用"
+  default_prompt: "使用 $microi-ai-application 创建一个可维护、可发布并通过多端验收的吾码 AI 应用。"

package/dist/microi.skills/microi-ai-application/references/frontend-baseline.md

@@ -0,0 +1,164 @@
+# Microi AI 应用前端基线
+
+## 目录
+
+1. 技术选择
+2. 标准目录
+3. 最小配置
+4. 分层契约
+5. 通用实时通信
+6. 质量门
+
+## 技术选择
+
+“最主流”不是永远固定的单一框架。Microi 的默认标准选择 Vue 3 + Vite + TypeScript，是因为 Microi.Client、Microi.UI 和既有开发者能力均以 Vue 3 为主，同时 Vue 官方的新项目脚手架也是 Vite + TypeScript。需要 React/Next、Svelte 或其它框架时，用户必须明确选择，并仍遵守平台 SDK、租户、发布和验收契约。
+
+版本策略：使用 Microi 当前维护的脚手架版本并提交 `package-lock.json`；升级依赖时单独提交、重新构建和截图，不让普通业务修改顺带漂移工具链。
+
+## 标准目录
+
+```text
+AI应用/{appKey}/
+  .microi-micro-app.json
+  package.json
+  package-lock.json
+  tsconfig.json
+  vite.config.ts
+  index.html
+  src/
+    main.ts
+    App.vue
+    env.d.ts
+    components/
+    pages/
+    composables/
+    domain/
+    services/
+    platform/
+      microi.ts
+      microi.v8.js
+  tests/
+  dist/                  # MicroService 默认；Web 项目可按清单使用 build/
+```
+
+`node_modules`、`dist/build`、覆盖率和本地环境文件不进入私有源码包。接口引擎源码按应用 Manifest 维护，但不被打进浏览器产物。
+
+## 最小配置
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  base: './',
+  plugins: [vue()],
+  build: {
+    outDir: 'dist',
+    assetsDir: 'assets',
+    emptyOutDir: true,
+    target: 'es2020',
+    sourcemap: false,
+  },
+})
+```
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "useDefineForClassFields": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "tests/**/*.ts"]
+}
+```
+
+推荐脚本：
+
+```json
+{
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest run",
+    "build": "npm run typecheck && vite build",
+    "preview": "vite preview --host 0.0.0.0",
+    "verify": "npm run test && npm run build"
+  }
+}
+```
+
+没有浏览器业务测试时可以先用 Node 原生测试，但复杂应用应使用 Vitest；关键 UI 流程使用 Playwright。不要为了“看起来主流”无条件加入 Router、Pinia、Element Plus或大型渲染库。
+
+## 分层契约
+
+```text
+Vue SFC/pages
+    -> composables/use-cases
+        -> domain pure TypeScript
+        -> services (ApiEngine / Realtime / Audio)
+            -> platform Microi SDK and host context
+```
+
+- `domain` 只接收普通数据并返回普通数据。
+- `services` 负责协议和 DTO，不把 HTTP/SignalR 对象泄漏到页面。
+- `composables` 负责生命周期、忙碌态和错误恢复。
+- `components/pages` 只消费可显示状态和明确动作。
+
+## 通用实时通信
+
+需要订单进度、协同状态或多人房间等实时刷新时，默认使用接口引擎通用 SignalR v2 契约；不要为应用新建业务专用 Hub。业务命令、订阅授权、事务和按用户裁剪的 Snapshot 均由接口引擎实现，SignalR 只发送事务提交后的公共投影。
+
+- Hub 固定为 `/api-engine-realtime`，客户端调用 `SubscribeChannel({ ChannelKey, SubjectId })`，监听 `RealtimeEvent`。
+- 连接必须使用普通登录 Token。现有 AccessKey 没有 `realtime:subscribe` scope，平台会拒绝其连接；在平台正式增加并校验该 scope 前，不得绕过此限制。
+- 每次订阅或续租都会重新调用 `realtime_{channel_key}_authorize`，授权接口必须以 `V8.CurrentUser` 为准，不能信任客户端传入的用户、租户或接口 Key。
+- 订阅按 30 秒时隙租约管理。客户端以服务端返回的 `RenewAfterMilliseconds` 安排下一次 `SubscribeChannel`，不得写死续租周期；页面隐藏后仍需订阅时继续续租，退出资源、注销或组件卸载时调用 `UnsubscribeChannel` 并清理定时器。
+- 客户端按 `EventId` 去重、按 `Version` 忽略旧事件并检测缺口。连接失败、续租失败、重连或版本跳跃时，立即回退到业务 HTTP `Snapshot`，且始终保留有界轮询兜底。
+- 接口引擎只能在成功结果的 `DataAppend.RealtimeEvent` 中声明 `Data` 公共投影；私有手牌、Token、密钥、用户专属字段和完整服务端状态只能由鉴权后的 Snapshot 返回。
+
+续租应串行执行，避免一个页面产生重叠授权请求：
+
+```ts
+const subscription = { ChannelKey: 'room_updates', SubjectId: roomId }
+let renewTimer: ReturnType<typeof setTimeout> | undefined
+
+async function renewRealtimeLease() {
+  clearTimeout(renewTimer)
+  try {
+    const lease = await connection.invoke<{
+      ProtocolVersion: number
+      RenewAfterMilliseconds: number
+      LeaseExpiresAt: string
+    }>('SubscribeChannel', subscription)
+    renewTimer = setTimeout(
+      () => void renewRealtimeLease(),
+      Math.max(1_000, lease.RenewAfterMilliseconds),
+    )
+  } catch {
+    await refreshSnapshot()
+    renewTimer = setTimeout(() => void renewRealtimeLease(), 3_000)
+  }
+}
+```
+
+当前服务端还会在共享 Redis 中按租户和用户限制订阅授权频率，所有标签页和 API 节点共享计数。应用不得依赖单节点内存节流，也不得通过并发续租消耗限额。
+
+## 质量门
+
+- TypeScript 严格检查无错误；`any` 只能位于有说明的平台兼容边界。
+- 每个写接口有请求 Id、重复提交保护和服务端校验。
+- 构建资产使用相对路径，稳定入口与不可变版本入口均可打开。
+- stage 前冻结 `CurrentVersion + AppVersion`，finalize 同时提交两项前置条件；旧请求晚到、应用身份漂移或清单收缩对账失败时不切换稳定入口。
+- 生产 JS 不含 localhost、凭据、私有牌面、服务端源码或 source map。
+- 首屏、登录/未登录、加载、空、错误、权限、成功状态均有响应式截图。
+- Canvas/WebGL、音频和实时连接在隐藏/卸载时释放，并有低性能降级。
+- 实时客户端已验证续租会重复授权、Token/资格撤销后停止收到事件，以及 SignalR/Redis 暂不可用时可通过 HTTP Snapshot 收敛。