---
name: microi-ai-application
description: Microi 吾码 AI 应用的创建、迁移、工程化开发和交付规范。用于 Web、MicroService、UniApp、H5、响应式网站或游戏类 AI 应用，尤其是选择前端技术栈、生成 Vue 工程、维护 TypeScript 源码、接入登录与接口引擎、构建发布、二次开发和多端验收。
---

> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。

# 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}`，不得跨租户复用目录。

当前服务器、当前租户的 `AI应用/{appKey}` 是每个 Web、UniApp、MicroService 或平台 AI 应用的唯一源码根。界面源码、Manifest、接口引擎、资源策略、安装测试、离线包生成与应用商城上传素材都必须归入对应应用目录共同演进；禁止创建平行的 `microi.apps/` 发行根或在应用目录中嵌套第二份可编辑工程。纯平台应用即使没有前端运行时，也放在官方租户的 `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`。

## 调用平台 AI

- 运行在吾码表单、表格、按钮或接口引擎上下文中的代码优先使用第一等 `V8.AI`：普通对话用 `await V8.AI.Chat(param)`，真实打字机输出用 `await V8.AI.ChatStream(param, onChunk, { Signal })`。前端实现会复用当前 ApiBase、登录 Token、设备/语言头和 Token 轮换；后端实现会固定绑定当前 `OsClient` 与认证用户。
- 独立 Web、MicroService、UniApp 的工程代码在 `src/services/ai.ts` 建立薄适配，调用当前平台 `POST /api/Ai/Chat` 或 SSE `POST /api/Ai/ChatStream`；从标准 Microi SDK/宿主上下文取得认证，不在页面中拼 Token、Endpoint、供应商 ApiKey 或任意 Header。
- 请求只传业务白名单字段，如 `UserChatMsg`、`AiModel`、`AiModelId`、`RelayModel`、`ConversationId`、`Mode`、`ReasoningEffort`、`Attachments`。服务端身份、租户、模型 Endpoint 和密钥不可由页面覆盖；NL2SQL 必须走专用受控入口，不能把页面提交的表名当授权。
- 外部 Agent 使用 MCP 的 `microi_chat` 获取最终对话结果；它不提供逐 token MCP 流，也不等于平台在线模型已经获得其它 MCP Tool 的 Agent Loop。需要写平台数据时仍调用对应写 Tool，执行确认、幂等和远端回读。
- 服务器 License 在本机通过官方公钥验签；有效 License 不要求每次 AI 调用访问官网。官方中转模型还会单独校验 `sk-microi-*` 和账号额度，这两套授权不能相互替代。

## Vue 实现规则

- SFC 模板承担真实 DOM 结构；事件使用 Vue 绑定，状态使用 `ref/reactive/computed`，副作用在组合函数的生命周期内注册并清理。
- 组件以业务语义命名，如 `RoomLobby`、`GameTable`、`AudioMixer`、`SettlementDialog`，不要按颜色或位置命名。
- 长连接、轮询、音频上下文、动画帧、观察器和全局事件必须在卸载时释放；页面隐藏时暂停非必要工作。
- 响应式布局至少覆盖 1440px 桌面和 390px 移动视口；使用安全区、44px 触控目标、键盘焦点和 `prefers-reduced-motion`。
- 音频应用必须区分背景音乐、人声和效果音，分别调节、静音和持久化；浏览器首次用户手势前不得强制播放。
- 不使用原生 `alert/confirm/prompt`；使用宿主反馈或可访问的 MCI 弹层。

## 存量迁移

### Cocos/WebGL 清晰度和资源生命周期

- 独立棋子/角色要求独立几何与身份，并不要求每个 glTF 重复上传整张纹理图集。同时核验磁盘资源和引擎实际 Texture2D/GFX bytes；主题切换时按自有 addRef/decRef 生命周期释放非活动模型和材质，迟到加载不得复活已销毁页面。
- Cocos 3.8.8 普通 Material 资产的宏与 pipeline states 在 initialize/copy 时设置；不能调用仅对实例有效的 recompileShaders/overridePipelineStates 后就假定生效。实际浏览器要复核绑定的贴图、法线、透明混合和叠加照明，类型检查不替代像素检查。
- 分开记录原生图片尺寸、局部材质密度、渲染缓冲分辨率、截图及真机画质。不得把放大、局部贴图或多图组合标为原生整幅 4K 母版；保留旧收藏与原始溯源。
- 七类动作等视觉测试应采集连续变化的真实网格状态；暂停引擎定格截图仅用于画面复核。FPS 必须在不暂停、不截屏的连续渲染区间单独计量，记录分辨率、GPU/软件渲染器与后台负载。
- 选中、起势、接触和吃子音效按时间轴独立触发。不得选棋就播放炮击或把每种兵种做成同一个音效的简单变调；新声音保留旧母版，削波/循环接缝通过不等于最终听感通过。

采用绞杀式迁移，避免一次重写破坏已经验证的规则：

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. 每次创建、修改、升级或重新发布 AI 应用，必须在任何源码同步、stage、finalize 或商城制包之前，为目标精确 `AppVersion` 写入 `sys_microistore_changelog`。日志的 `StoreId / Version / Title / ChangeType / Content / ReleaseTime` 必须完整；发布工具显式传入含义一致且非空的 `changeSummary`，发布后同时回读商城子表与 `mci_ai_app_version.ChangeSummary`。缺日志或版本不一致必须停止发布。
6. Web/UniApp 使用 `/{OsClient}/ai-app-publish/{AppKey}/index.html`；MicroService 使用 `/micro-app/{OsClient}/{AppKey}/index.html`。不要因技术栈相同而混淆运行类型。
7. 官网、二维码、分享链接和商城“立即体验”只能使用不含 `/releases/`、`/requests/`、`/versions/` 与语义版本号的稳定当前入口；不得使用 `SharedPublicRuntime.EntryUrl` 或发布结果中的不可变版本 URL。固定入口必须以代理或全屏加载壳保持浏览器地址不变，不能用 30x、`meta refresh` 或 `location.replace` 把地址栏跳到版本产物。
8. `SharedPublicRuntime.EntryUrl` 和 `/versions/{Version}/index.html` 仅用于历史记录、回滚、摘要校验与审计。回读应用、版本、active 文件清单和 SHA-256；旧清单文件只能可逆归档，不能删除。再分别直接请求稳定当前入口、不可变版本入口及主要 JS/CSS，并断言前者完成加载后地址栏仍不含版本段。

## 完成定义

- `vue-tsc --noEmit`、单元测试和生产构建通过。
- 源码、lockfile、Manifest、构建版本和远端文件哈希一致。
- 匿名、登录、Token 失效、权限不足、弱网、重连和错误恢复有确定结果。
- PC 和移动真实浏览器截图通过，控制台无错误，刷新/分享 URL 可恢复状态。
- 多人或分布式功能必须使用不同账号和至少两个 API 节点验收；本地单进程或静态代码检查不能宣称生产多人闭环。