@microi.net/cli 5.0.9 → 5.1.0

package/skills/ai-engine/SKILL.md

@@ -70,7 +70,7 @@ AI 业务统一实现在 `Microi.Server/Microi.AI`。`Microi.Server/Microi.net.A
 - PC 与移动端复用 `mci_ai_data_assistant`。`Bootstrap` 返回的 `Enabled`、`Models`、`AllowedDomains` 和 `Prompts` 是跨端共同事实源；快捷问题来自启用的 `mci_ai_data_domain.PromptExamples`，前端不能维护另一套固定文案。
 - 普通角色必须匹配启用的 `mci_ai_role_policy`。只有后端可信的 `V8.CurrentUser.Level >= 9999` 可以在新安装租户缺少角色策略时获得安全兜底：从目标租户动态读取已启用业务域和模型，范围为 `All`，仍保持 `AllowRawSql=false`、敏感字段默认关闭。不得相信客户端提交的 Level、角色名或账号名。
 - 当租户要求“所有角色均可使用 AI 助手”时，必须为 `sys_role` 中每个目标角色建立显式启用策略；受限角色使用 `Self`/`Department` 与最小业务域，管理角色才可使用经确认的 `All`。禁止把“人人可打开助手”实现成普通角色默认全库可读。
-- 开启 `Sys_Config.IsShowAiAssistant` 前后都要做策略覆盖验收：回读 `sys_role` 与 `mci_ai_role_policy`，断言每个目标角色都有唯一启用策略，`AllowedDomains`、`AllowedModels` 均非空且模型仍处于启用状态；再至少用超级管理员、普通员工和客户身份分别调用 `Bootstrap`，确认 `Enabled=true` 且返回范围符合角色。仅看到入口图标不算可用。
+- `Sys_Config.DisableAiAssistant` 是负向开关：缺失、空值或 `0/false` 都显示 AI 助手，只有显式 `1/true` 才关闭图标。商城升级应复用旧 `IsShowAiAssistant` 的字段元数据 Id 就地改名；兼容读取可以保留旧物理列，但旧字段元数据必须在 PC 与移动端隐藏，禁止同时暴露正向、负向两个开关。关闭该开关前后都要做策略覆盖验收：回读 `sys_role` 与 `mci_ai_role_policy`，断言每个目标角色都有唯一启用策略，`AllowedDomains`、`AllowedModels` 均非空且模型仍处于启用状态；再至少用超级管理员、普通员工和客户身份分别调用 `Bootstrap`，确认 `Enabled=true` 且返回范围符合角色。仅看到入口图标不算可用。
 - 角色策略存在但 `AllowedModels` 为空时，客户端最终仍会得到无可用模型；不得把它误判为前端角色拦截。应补齐当前租户启用模型白名单并回读，而不是删除 `mci_ai_role_policy` 校验或在客户端强制把 `Enabled` 改成 `true`。
 - 商城包不能携带发布租户的角色 Id、模型 Id 或密钥；应携带业务域定义和接口引擎，由安装后的目标租户动态发现自己的启用模型。发布后回读 `sys_microistore.AppVersion/AppPakcet`，并真实执行 `Bootstrap` 验证超级管理员可用、模型非空、快捷问题存在。
 

package/skills/app-store/SKILL.md

@@ -51,7 +51,7 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 
 安装中断后从 checkpoint 幂等恢复；不能依赖当前 API 节点内存。
 
-## 权限与租户
+## 权限与租户
 
 - 商城定义、安装、升级、卸载和应用源码只允许 `Level >= 9999`。
 - “吾码官方平台”不能只按 `OsClient`、域名或前端变量判断：服务端必须同时校验官方 `OsClient`，并确认当前节点固定只读挂载 `/app/microi_private.pem` 的公钥部分与内嵌官方 License 信任根匹配；本地源码开发可从私有子仓库兼容查找。任意自建私钥不能建立官方身份。官方平台前端隐藏安装、更新、重新安装、离线安装和批量安装入口，后端仍必须拒绝这些写操作。
@@ -65,6 +65,16 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 - MySQL 宽表触发 65,535 字节行内上限时，只允许把不参与索引的 `varchar` 配置列无损提升为 `mediumtext`，并把类型覆盖持久化到后台任务 checkpoint；索引列和非行宽错误必须失败关闭。发布包对长连接串、密钥、回调地址、域名/白名单等字段应直接使用 `mediumtext`，同时更新 `DiyFields` 与建表 DDL，不能长期依赖安装时猜测。
 - 卸载是破坏性操作，必须明确列出将删除/保留的资源、二次确认并优先软删除/归档业务数据。
 
+## 联邦商城源、公开范围与历史版本（强制）
+
+- 每个主租户和子租户都可以发布自己的应用；应用行用 `IsPublic` 表达公开范围，缺省/历史空值按公开兼容。公开应用允许未登录来源读取和安装，私有应用只允许来源登录成功后的授权身份读取，列表、详情、版本接口都必须重复执行这一权限判断。
+- 商城来源以 `ApiBase + OsClient` 唯一定位。添加来源先只读发现系统标题、验证码策略和公开应用数；需要私有应用时再登录。帐号、密码、Token 不能写浏览器配置或商城来源 JSON；密码只用于本次登录，长会话 Token 以 `MCP/Mobile` 非 PC 客户端签发，并由当前租户后端加密保存到 `mci_system_setting`，浏览器只持有不具备取密能力的凭据 Key。
+- 后端来源代理必须固定已保存的 `ApiBase + OsClient`，拒绝过期 Token、访问密钥会话、非超级管理员、非 HTTPS 外网地址、重定向漂移和超限响应；Token 不得返回浏览器、日志、审计或应用包。退出登录同步删除服务端密文。
+- 商城主页面统一承载应用市场、已安装、我发布的应用、安装离线包和来源管理，不能再通过独立菜单或路由割裂上下文。来源增删改启停逐项自动保存；来源管理、详情和复杂配置使用平台统一 `80%` 可拖动大圆角 Dialog，遮罩服从 `sys_config.DisableFormMaskBlur`。
+- 每张应用卡必须显示预览图、公开范围、分类、最新版本、当前租户已安装版本及状态色。来源卡必须显示其公开数和当前授权可访问总数；平台官方发布节点只显示“平台官方应用源”身份标记，不显示安装、更新或重新安装操作。
+- 安装可明确选择 `sys_microistore` 当前版本或 `mic_data_version` 中仍含完整包正文的历史快照；后台任务必须把 `StoreVersionId` 一直传到详情取包并把实际安装版本写回 `sys_microistoreversion`。回退旧版属于重新安装，不得静默换成最新版。
+- “我发布的应用”只读取当前登录用户拥有的记录，可以包含草稿和构建失败项；普通商城列表只读取已发布项。两者必须在服务端按 Owner 和发布状态过滤，不能依赖浏览器过滤后再分页。
+
 ## 发布版本与资源选择
 
 - 发布器必须把用户请求的精确版本传给资产准备器，并断言 `RequestedVersion == Prepared.PackageVersion == AppPakcet.PackageInfo.Version`；版本不存在就失败，禁止静默改用最新版本。

package/skills/microi-form-engine/SKILL.md

@@ -37,6 +37,10 @@ Config/Data、菜单查询列与缓存保持一致。
    `FormWidth=24`，且 `Config.CollapseGroup.ShowFieldCount` 默认补为 `true`。
 6. 绑定菜单后补齐/允许平台推断列表列、搜索列、隐藏列、排序列、移动端列和默认排序。
 7. 回读 `diy_field`、刷新 schema 缓存，再在真实新增/编辑/查看表单中验收。
+
+新建表/模块时，除非用户显式指定或表单达到极重阈值（约 36+ 业务字段、2+ 子表或同等
+重型控件密度），默认保存 `diy_table.FormOpenType=Dialog` 与 `FormOpenWidth=80%`。
+Drawer 只服务超长复杂表单，不能作为所有 CRUD 模块的模板默认值。
    若设计器显示而运行态不显示，先检查 `InFormV8`/字段 V8 是否调用
    `V8.FieldSet(..., 'Visible', false)`、`hideField` 或传入 `HideFields`，再判断前端源码。
 

package/skills/microi-form-layout/SKILL.md

@@ -13,6 +13,13 @@ Microi 吾码低代码提供 **三种** 表单分组能力，但每种都有明
 
 控件事实源：`Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json` 中 `Sort=1000` 附近的 `Divider`、`CollapseGroup`、`Tabs`、`Alert`、`StaticText`、`Html`、`RichText` 等都属于 Advanced 布局控件。
 
+表单遮罩统一使用负向开关 `diy_table.DisableFormMaskBlur`：字段缺失、空值或 `0/false` 时默认启用毛玻璃，只有显式 `1/true` 才关闭；`sys_config.DisableFormMaskBlur` 可以全局关闭。商城升级必须复用旧 `FormMaskBlur` 的字段元数据 Id 就地改名，允许暂留旧物理列供兼容读取，但旧字段元数据必须设置 `Visible=0`、`AppVisible=0`，不得同时向用户展示正向与负向开关。
+
+表单打开方式与分组是两个独立决策：新表默认 `FormOpenType=Dialog`、
+`FormOpenWidth=80%`。只有约 36 个以上业务字段、至少 2 个大型子表，或同等密度的重型控件
+才评估 Drawer；不能用 Drawer 代替 Tabs/CollapseGroup 的信息架构。Dialog 统一使用居中、可拖动、
+大圆角弹层；Drawer 贴边且不使用大圆角。
+
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=microi-form-layout-000 sha256=cade6a415454aa04f5fcf840e6d9df1323ac9751c0e3c8e1b07b360007413819 -->
 ## 1. 三种分组能力速查
@@ -118,7 +125,7 @@ Q1: 核心可见字段数、子表和强任务域？
 V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.ClickFormTab('tabId')` 动态控制 Tab 显隐和默认选中。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=microi-form-layout-003 sha256=eebf51aec08023443964d82e1140026ec7cef627b3d2ed6ead169e1fd14353a3 -->
+<!-- microi-progressive:chunk id=microi-form-layout-003 sha256=c737fc8b0d488548e5a3de616ff172b8b645553c818fb09e70a196f4e9c0e2ae -->
 ## 5. 必填与禁止
 
 ### 5.1 必填
@@ -127,6 +134,8 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 - 创建 CollapseGroup 分组时，必须设置 `Icon`（如 `fas fa-calculator` / `fas fa-info-circle`），不要默认空白。
 - 任何 Tab / CollapseGroup 都必须有 `Description` 解释分组用途，不要只放一个标题。
 - 每个 CollapseGroup 必须回读到 `FormWidth=24`；`Config.CollapseGroup.ShowFieldCount` 默认必须为 `true`。
+- 表级 Tab 与 CollapseGroup 的 `Description` 作为副标题显示；开启计数时统一追加 `x 项`，禁止继续显示 `x 个字段`。运行时动态显隐字段后必须重算计数，已有数字角标配置继续生效，不能被静态字段数覆盖。
+- 表级分组方向完整支持 `TabsPosition=left/top/right/bottom`；每个方向都要检查标题、副标题、动态角标和选中指示线，纵向指示线端点固定为直角。
 - 修改 `diy_table.Tabs` 或 `diy_field.Tab` / `Config.CollapseGroup` / `Config.FieldTabs` 后，必须调用 `microi_refresh_schema_cache`。
 - Tab 内嵌套 CollapseGroup 时，CollapseGroup 必须设 `DefaultCollapsed=true`（默认收起），避免 Tab 内继续被折叠分组抢首屏空间。
 - 新增布局节点后必须同时回读 `diy_field` 元数据和目标业务表结构，确认没有新增物理业务列；若当前工具不提供仅元数据能力，只报告设计建议，不得绕过后端直接写表。

package/skills/module-engine/SKILL.md

@@ -30,6 +30,16 @@ description: Microi 模块引擎与 sys_menu 配置指南。用于创建或修
    MCP 解析为字段 Id 和 `SelectFields/SearchFieldIds/...`。
 5. 同一次创建配齐业务按钮、FormBtns、PageTabs 和批量按钮。
 6. 写后回读模块，检查字段映射、按钮 JSON、路由和目标页面。
+
+### 新模块表单打开方式（强制默认）
+
+- AI 新建 `diy_table` / 业务模块时，`FormOpenType` 默认写 `Dialog`，`FormOpenWidth`
+  默认写 `80%`；缺省值也必须按这组语义处理，不能再把所有模块统一生成为 Drawer。
+- 只有表单确实非常庞大时才使用 `Drawer`：通常是 36 个以上业务字段、至少 2 个
+  `TableChild`、28 个以上字段且含大型子表，或 7 个以上子表/富文本/代码编辑/上传/地图等
+  重型控件。达到阈值仍应先用 `diy_table.Tabs` 与 CollapseGroup 整理信息架构。
+- 用户显式指定 `Dialog/Drawer/Page` 或宽度时以用户配置为准。Drawer 是贴边直角容器；
+  Dialog 使用平台统一大圆角、可拖动、居中弹层，遮罩服从 `sys_config.DisableFormMaskBlur`。
 7. 为管理员/目标角色分配菜单权限，并以真实登录用户验收。
 
 ## 绑定表菜单不能只写两个字段

package/skills/ui-design/SKILL.md

@@ -184,4 +184,21 @@ Microi 项目必须支持用户或项目级形态偏好：`data-mci-shape="round
 - [references/progressive-06-主题切换实现.md](references/progressive-06-主题切换实现.md)：主题切换实现；命名规范
 - [references/progressive-07-速查-从头搭建一个移动端页面.md](references/progressive-07-速查-从头搭建一个移动端页面.md)：速查：从头搭建一个移动端页面；🚨 移动端低代码项目落地踩坑（必读，2026.5）；🔗 关联字段：保存真实 Id，界面展示可读标签；表单布局规范（Column）
 - [references/progressive-08-表单分组规范-tabs-vs-collapsegroup-强制.md](references/progressive-08-表单分组规范-tabs-vs-collapsegroup-强制.md)：表单分组规范：Tabs vs CollapseGroup（强制）；缓存刷新（解决"我改了字段但页面不变"问题）；接口引擎匿名访问；MCI-UI 与第三方组件库策略；MCI-UI 源码落地位置；VitePress 中文文档布局规范
-<!-- microi-progressive:end -->
+<!-- microi-progressive:end -->
+
+## Microi 低代码工作台默认清爽体验（强制）
+
+`diy-form`、`diy-table`、模块卡片、设计器弹窗和框架导航默认采用清爽、紧凑、层次明确的现代视觉；经典样式只能作为显式兼容模式保留，不能继续作为新页面或未配置页面的默认外观。
+
+- **只升级呈现，不改变业务链路**：不得删除、合并或绕开页面 V8 按钮、行 V8 按钮、批量按钮、字段事件、表单事件、权限判断、校验、工作流与保存逻辑。按钮仍应出现在其业务语义对应的位置；只有原本属于“更多”的操作才进入更多菜单。
+- **普通表单使用连续画布**：弹窗/页面的表单区使用柔和底色，普通字段外壳透明、无独立边框和阴影，只有输入、选择、日期、文本域等真实控件使用白色/主题高亮表面；禁止把每个字段切成一张小卡片。系统设置、控制中心等明确配置为工作台的模式可以保留分区卡片。字段间距以一屏可读更多信息为目标，布局字段、富文本、上传、地图、代码编辑器、子表等重型控件不强制固定高度。
+- **尊重三种标签布局**：`left`、`right`、`top` 三种 `FormLabelPosition` 必须完整保留，标签宽度继续服从表单配置；移动窄屏允许回落到顶部标签，但不能破坏桌面配置语义。
+- **Label 与紧凑控件共用中心线**：左右标签布局下，普通字段 Label、输入控件、日期文字与日期前缀图标必须共用同一控件高度和垂直中心线；不得保留会把 Label 单独上抬/下压的底部外边距。多行文本、上传、子表等高控件才切换为顶部对齐。
+- **弹窗与抽屉边界有区别**：表单对话框采用中性细边界、柔和遮罩与模糊背景，标题顶部不加装饰色线；抽屉必须贴边且无圆角，可在顶部保留克制的 2–3px 主题色识别线。两者都使用连续的柔和表单画布和紧凑操作区；设计器双击字段弹窗必须可拖动，并继续提供控件专项配置入口。
+- **平台 Dialog 统一壳**：除 Drawer 外，框架弹层、微应用弹层、系统设置、商城、通知与业务表单默认使用 20–24px 大圆角、居中、标题栏可拖动的 Dialog；禁止页面自行恢复方角壳或顶部主题色粗线。遮罩默认毛玻璃，只有 `sys_config.DisableFormMaskBlur=1/true` 才全局关闭；`prefers-reduced-motion` 只能停止动画与过渡，不得关闭静态毛玻璃。
+- **Tabs 统一视觉**：顶部工作区、数据列表 PageTabs、表单 Tabs 与右侧关联数据 Tabs 使用同一套清爽、独立标签视觉。横向 Tabs 禁止铺设贯穿整行的有色轨道、边框底板、下划线或其它装饰线；未选项保持透明，悬停与选中只使用克制的文字色、浅色独立表面和轻阴影。纵向 Tabs 可使用截图式中性浅色分组容器，选中项是独立浅色卡片。数字角标放在标签文本之后且不得挤压标题；过渡只用于交互，并尊重 `prefers-reduced-motion`。
+- **表格与卡片行为完整**：桌面数据卡片采用连续白色表面、弱边界和轻阴影，操作区不得再叠加有色底板或硬分割线；表格模块门头的标题/副标题卡片与每个动态统计卡片必须彼此独立，父布局保持透明，禁止用一个大卡片或外框把标题和全部统计项包在一起。表格默认取消无意义的纵向网格，只保留浅表头与轻量横向行节奏，工具栏和分页不得层层套框。`PageBtns`、`BatchSelect`、行内/行外 V8 按钮均不可因改版丢失；需多选而当前未选中时，应先把当前记录纳入选中集再执行。
+- **启动状态可理解、可恢复**：Vue 挂载和业务就绪是两个状态。进度到 100% 后若仍在初始化，应显示“正在连接/后端响应较慢/仍在等待”等阶段文字；明确失败时提供原因摘要与刷新重试，禁止撤掉启动层后留下空白页。
+- **侧栏清爽但层级清晰**：压缩无效间距，保留足够点击区域、选中态、父子层级和键盘焦点；颜色、圆角、阴影必须来自主题 token。
+- **纵向导航使用短圆角侧标**：侧栏、纵向 Tab、分组导航等选中态的左/右侧强调线统一参照平台左侧菜单：宽 3–4px、高度约为选中项的 45%–60%，垂直居中，端点使用小圆角；禁止铺满 100% 高度，也禁止做折线或包边。右侧 Tab 镜像到右边；横向 Tabs 不使用这条侧标，也不额外增加上下指示线。
+- **主题与可访问性验收**：至少验证亮色/暗色、租户主题色、1366/1440/1920 桌面与 390px 移动宽度、三种标签对齐、慢接口和接口失败；动效必须服从 `prefers-reduced-motion`。

package/skills/v8-security/SKILL.md

@@ -12,17 +12,19 @@ description: Microi V8 安全指南。用于审查 DiyToken 与权限、可逆
 访问密钥由 `microi_list_my_access_keys`、`microi_create_my_access_key`、`microi_revoke_my_access_key` 管理，只允许当前用户、限期、最小 scope，明文仅创建时返回一次。外部身份回调固定为 `/api/ExternalLogin/Callback`，服务端校验租户、Provider、state、redirect 和回调域名，验证成功后仍签发 DiyToken。
 
 <!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=v8-security-000 sha256=5cf3d472c04eb49aee9dc8f251bdb825b73574e046c968547e51af7c8492b9b3 -->
+<!-- microi-progressive:chunk id=v8-security-000 sha256=683f6fb48592b050fc31caec6b45e39c8109b0a67baa48c0a2e6d1385a0e4ce1 -->
 ## 0. 租户动态系统设置与密钥边界
 
-第三方密钥（微信、支付宝、OpenAI、阿里云、ERP、SMTP）**禁止**硬编码在 V8 代码或前端。新增租户业务配置使用当前租户数据库的 `mci_system_setting`；数据库、Redis、MongoDB、MinIO、MQ 等部署控制面仍由主库 `sys_osclients` 托管，子租户不能修改。
+第三方密钥（微信、支付宝、OpenAI、阿里云、ERP、SMTP）**禁止**硬编码在 V8 代码或前端。公开的租户配置必须建成当前租户 `sys_config` 的实体字段；敏感或仅供后端使用的租户业务配置保存到 `mci_system_setting`。数据库、Redis、MongoDB、MinIO、MQ 等部署控制面仍由主库 `sys_osclients` 托管，子租户不能修改。
 
 ```javascript
-// ✅ 浏览器/前端 V8 只能读取管理员明确公开的普通设置，直接位于根对象
-var loginName = V8.SysConfig['Login.Gitee.Name'];
+// ✅ 浏览器/前端 V8 只读取 sys_config 的浏览器安全投影
+var sysTitle = V8.SysConfig.SysTitle;
+var githubVisible = V8.SysConfig.LoginGitHubDisplay;
 
-// ✅ 后端接口引擎/后端 V8 事件可读取当前租户完整配置（包括 Secret）
-var clientSecret = V8.SysConfig['Login.Gitee.ClientSecret'];
+// ✅ 后端接口引擎/后端 V8 事件从独立节点读取私密设置
+var privateSettings = V8.SysConfig.ServerPrivateSettings || {};
+var clientSecret = privateSettings['Login.Gitee.ClientSecret'];
 // 只能在后端使用，禁止 return、日志、审计或写入前端可读数据。
 
 // ❌ 危险：密钥泄漏 / 跨租户串号
@@ -31,9 +33,9 @@ var openaiKey = 'sk-xxxxxxxxxx';
 
 `V8.OsClientModel` 与兼容别名 `V8.ClientModel` 均为独立脱敏副本：数据库连接、AuthSecret、Redis、对象存储、MQ、MQTT、Search 的地址与凭据不会注入脚本。存量租户业务字段只作兼容，新增 Secret 不得继续依赖 `V8.OsClientModel`。
 
-`V8.SysConfig` 按运行端采用不同权限投影，且任何运行端都不存在 `PublicSettings` 属性。浏览器/前端 V8 只得到匿名 `GetSysConfig` 的独立脱敏副本；当前租户 `mci_system_setting` 中 `IsPublic=1` 的普通设置直接平铺到根对象，Secret 或 Key 命中 Password、Secret、Token、Credential、PrivateKey、AccessKey、ApiKey、ConnectionString、DbConn、Redis、MinIO、ClientSecret 等敏感片段时永远失败关闭。后端接口引擎和后端 V8 事件得到当前租户完整、独立的 `sys_config`，并在根对象中获得全部启用的 `mci_system_setting`，Secret 由可信后端按租户解密。子租户调用 `V8.FormEngine.GetSysConfig(...)` 时仍强制使用当前 `OsClient`，不能借缓存命中读取其它租户配置。
+`V8.SysConfig` 按运行端采用不同权限投影，且任何运行端都不存在 `PublicSettings` 属性。浏览器/前端 V8 只得到匿名 `GetSysConfig` 的独立脱敏 `sys_config` 投影；`mci_system_setting` 的任何记录都不会进入浏览器。后端接口引擎和后端 V8 事件得到当前租户完整、独立的 `sys_config`，全部启用的 `mci_system_setting` 则放在 `V8.SysConfig.ServerPrivateSettings`，Secret 由可信后端按租户解密。独立节点避免动态 Key 覆盖 `sys_config` 实体字段，也让前后端边界可审计。子租户调用 `V8.FormEngine.GetSysConfig(...)` 时仍强制使用当前 `OsClient`，不能借缓存命中读取其它租户配置。
 
-Secret 只通过租户管理员专用端点写入租户绑定的认证密文。列表不返回密文或原文；临时显示必须消费 Passkey/TOTP/严格人脸一次性票据，设置 `no-store`，30 秒清除，审计不含原文。前端 V8、普通 FormEngine HTTP、匿名请求和访问密钥会话不得读取 `SecretCipher` 或 Secret 原文；后端 V8 只能通过当前租户 `V8.SysConfig[ConfigKey]` 使用已解密值，不获得通用解密器，也不得返回或记录原文。
+Secret 只通过租户管理员专用端点写入租户绑定的认证密文。列表不返回密文或原文；临时显示必须消费 Passkey/TOTP/严格人脸一次性票据，设置 `no-store`，30 秒清除，审计不含原文。前端 V8、普通 FormEngine HTTP、匿名请求和访问密钥会话不得读取 `SecretCipher`、`ServerPrivateSettings` 或 Secret 原文；后端 V8 只能通过当前租户 `V8.SysConfig.ServerPrivateSettings[ConfigKey]` 使用已解密值，不获得通用解密器，也不得返回或记录原文。
 
 共享基础设施只能通过受控能力访问：`V8.Cache` 自动绑定 `Microi:{OsClient}:*`，文件路径绑定 `/{OsClient}/...`，RabbitMQ 队列绑定 `microi.{OsClient}.*`，MQTT Topic 绑定 `tenant/{OsClient}/...`，Search 索引绑定 `{OsClient}_*`。V8 不得获得 Redis `IDatabase`、HDFS `ClientModel` 或原始基础设施配置。
 

package/skills/v8-tcp-integration/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: v8-tcp-integration
+description: Microi 后端 V8 TCP 原始字节集成规范。用于通过 V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync 连接网络小票机、串口服务器、PLC 或其它 TCP 设备，处理 Byte/Base64/Hex/Text 载荷、GBK/GB18030、超时、响应、幂等与出站安全。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi V8 TCP 原始字节集成
+
+使用后端 `V8.Tcp` 完成一次性 TCP 连接、原始字节写入和可选的有界响应读取。典型场景是 RAW/JetDirect 9100 网络小票机、串口服务器和 PLC；具体协议帧、校验码与打印业务仍由接口引擎编排。
+
+文档维护时，只在 `microi.doc/docs/doc/v8-engine/v8-server.md` 原位更新后端 API；不要新建重复页面，也不要手工维护英文文档。改变公共契约时同步后端源码/测试、Microi.Client Monaco 定义、Microi.VSCode 类型与生成知识、AI Skill 镜像。
+
+## 先判断是否适用
+
+| 需求 | 选择 |
+|---|---|
+| 后端向设备 TCP 端口发送原始字节 | `V8.Tcp` |
+| HTTP/HTTPS API | `V8.Http`，不要用 TCP 重写 HTTP |
+| RabbitMQ/MQTT | `V8.MQ` 或 MQTT 引擎 |
+| 浏览器/5+App 蓝牙或 SPP 打印 | 前端 `V8.Print`，读取 `v8-frontend-events/references/bluetooth-print.md` |
+| 长连接、TCP 服务端监听、TLS、自定义连接池 | 当前 `V8.Tcp` 不提供；设计独立网关/Worker |
+
+平台已经提供可复用原子能力后，打印模板、设备选择、订单状态、幂等和审计优先写在接口引擎/表单事件；不要为单个打印业务再写 C# Controller。
+
+## API 契约
+
+| 方法 | 行为 |
+|---|---|
+| `V8.Tcp.Send({...})` | 连接、发送、关闭，返回 `DosResult` |
+| `await V8.Tcp.SendAsync({...})` | 当前请求内异步发送 |
+| `V8.Tcp.SendAndReceive({...})` | 发送后读取响应，再关闭 |
+| `await V8.Tcp.SendAndReceiveAsync({...})` | 当前请求内异步发送并读取响应 |
+
+必填目标参数：
+
+- `Host`：主机名或 IP；只允许主机，不传 `tcp://` URL。
+- `Port`：1-65535。
+
+发送内容必须且只能选择一组：
+
+- `Bytes`（别名 `RawBytes`、`ByteArray`）：每项为 0-255 的整数。
+- `ByteBase64`（别名 `BytesBase64`、`Base64`）。
+- `Hex`：允许空格、`0x`、`-`、`:`、逗号和下划线分隔。
+- `Text`：按 `Encoding` 编码。默认 `utf-8`，还支持 `ascii`、`gb18030`、`gbk/gb2312`、UTF-16/UTF-32 大小端。
+
+边界参数：
+
+| 参数 | 默认 | 范围 |
+|---|---:|---:|
+| `ConnectTimeout` | 10 秒 | 1-120 秒 |
+| `SendTimeout` | 10 秒 | 1-120 秒 |
+| `ReceiveTimeout` | 3 秒 | 1-120 秒 |
+| `MaxReceiveBytes` | 65536 | 1-1048576 |
+| `NoDelay` | `true` | 布尔值 |
+
+单次发送最多 4 MiB。`Send` 成功数据为 `{BytesSent, RemoteEndPoint}`。收发方法另有 `BytesReceived`、`RawBytes`、`ByteBase64`、`Hex`、`ReceiveEndReason`、`Truncated`；`ReceiveEndReason` 为 `RemoteClosed`、`Timeout` 或 `MaxReceiveBytes`。
+
+## 实现流程
+
+### 1. 固定并授权设备目标
+
+从 SaaS 可信配置或受行权限保护的设备表读取 `Host`、`Port`，按当前用户/门店/租户决定可用设备，再与精确白名单比较。禁止这样写：
+
+```javascript
+// 错误：匿名或普通调用者可扫描后端可达内网。
+return V8.Tcp.Send({
+  Host: V8.Param.Host,
+  Port: V8.Param.Port,
+  Hex: V8.Param.Hex
+});
+```
+
+### 2. 形成一个完整帧
+
+ESC/POS、Modbus TCP 或设备私有协议的命令、正文和校验码应先合成一个完整字节载荷。不要为了拼帧而打开多次连接；包含中文和控制命令时，优先在可信后端/上游把完整帧编码为 `Bytes`、`ByteBase64` 或 `Hex`。
+
+```javascript
+var result = V8.Tcp.Send({
+  Host: '192.168.1.88', // 示例；生产从可信配置读取
+  Port: 9100,
+  Bytes: [
+    27, 64,                         // ESC @ 初始化
+    77, 105, 99, 114, 111, 105, 10,
+    10, 10,
+    29, 86, 0                       // GS V 0 切纸
+  ],
+  ConnectTimeout: 5,
+  SendTimeout: 5
+});
+if (result.Code !== 1) return result;
+```
+
+只有纯文本时可使用打印机常见编码：
+
+```javascript
+var result = await V8.Tcp.SendAsync({
+  Host: '192.168.1.88',
+  Port: 9100,
+  Text: '吾码小票\n合计：12.00\n\n',
+  Encoding: 'gb18030'
+});
+if (result.Code !== 1) return result;
+```
+
+### 3. 需要协议响应时显式收取
+
+```javascript
+var result = V8.Tcp.SendAndReceive({
+  Host: '192.168.1.20',
+  Port: 4001,
+  Hex: '01 03 00 00 00 02 C4 0B',
+  ReceiveTimeout: 3,
+  MaxReceiveBytes: 4096
+});
+if (result.Code !== 1) return result;
+
+var bytes = result.Data.RawBytes;
+var hex = result.Data.Hex;
+```
+
+接收超时是整段接收的总时间。已收到部分数据后超时会返回成功和已有数据，并标记 `ReceiveEndReason='Timeout'`；未收到任何字节则失败。协议必须知道响应长度或结束条件，不能把超时默认当作完整帧。
+
+### 4. 分开判断写入、设备执行和实物结果
+
+- `Code=1` 只表示字节已写入 TCP 连接。
+- 设备协议回执可证明设备接受/处理到哪一步，但仍不一定证明机械动作完成。
+- “小票已打印”需要打印机状态、设备回执或实物/硬件验收证据。
+
+打印不是天然幂等。不确定失败时自动重试可能重复出纸；需要可靠打印时使用业务打印单号、设备回执、状态机以及 Job/MQ/outbox，且重试策略必须识别“尚未发送”和“结果未知”。
+
+## 安全与运行约束
+
+1. TCP 不经过 `V8.Http` 的 SSRF 防护。容器网络策略/防火墙只放行目标设备网段和端口；匿名接口不得暴露任意目标。
+2. 不把票据正文、设备口令、原始帧和响应秘密写入日志；日志只记录脱敏设备标识、业务单号、字节数、耗时和错误分类。
+3. `SendAsync` 只是在当前请求内等待 I/O，不能替代后台任务。不要遗留未等待 Promise、`setTimeout` 或 `Task.Run`。
+4. 每次调用都会创建并关闭连接；不能假设设备会保持会话状态。
+5. Docker 内的 `localhost` 指容器自身。验收前从实际后端容器验证到设备 IP/端口的路由和出站策略。
+6. 载荷、超时和响应均有硬上限；不要通过拆成无限循环规避限制。
+
+## 修改公共能力时的同步门禁
+
+- 源码：`Microi.Server/Microi.V8Engine/Extend/Tcp/V8Tcp.cs` 与 `V8Extend.cs`。
+- 测试：真实 Jint 注入、Byte/Base64/Hex/Text、回环收发、超时/上限/非法参数。
+- 编辑器：`Microi.Client/.../v8-api-server-definitions.js` 与 `Microi.VSCode/src/editor/typingsManager.ts`。
+- 文档与知识：官网中文后端 V8 页面、`microi.skills/README.md`、`v8-utilities` 索引、`Microi.AI/Resource` 镜像和向量资源列表。
+- 验收：目标测试、后端构建、精确重启与健康检查、独立 TCP 回环；真实打印机出纸必须单独报告，不能用回环测试替代。
+

package/skills/v8-tcp-integration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "V8 TCP 原始字节"
+  short_description: "通过后端 V8 安全发送和接收 TCP 原始字节数据"
+  default_prompt: "使用 $v8-tcp-integration 编写一个安全、可验证的 Microi 后端 V8 TCP 设备集成。"

package/skills/v8-utilities/SKILL.md

@@ -64,6 +64,7 @@ var clientDecoded = V8.Base64.decode(clientEncoded);
 |---|---|
 | 表单 CRUD、`_Where` | `v8-crud-api`、`v8-sql-query` |
 | HTTP/第三方接口 | `v8-http-integration` |
+| TCP 原始字节/网络小票机/设备 | `v8-tcp-integration` |
 | Redis/Hash | `v8-cache-pattern` |
 | 文件/HDFS | `v8-file-upload` |
 | 图片 | `v8-image-processing` |

package/skills/v8-utilities/references/server-api-index.md

@@ -90,8 +90,8 @@ MD5/SHA1 仅为兼容摘要；任何摘要都不能直接作为新密码存储
 
 ## 内置与自定义扩展
 
-`V8.Alipay`、`V8.AlipayV3`、`V8.WeChat`、`V8.Alidns`、`V8.System` 和
-`V8.Image` 由当前 `Microi.V8Engine/V8Extend.cs` 注册。扩展可被裁剪或二次
+`V8.Alipay`、`V8.AlipayV3`、`V8.WeChat`、`V8.Alidns`、`V8.System`、
+`V8.Image` 和 `V8.Tcp` 由当前 `Microi.V8Engine/V8Extend.cs` 注册。扩展可被裁剪或二次
 开发，调用前以目标部署源码和编辑器定义为准。
 
 - `V8.Alipay.CreatePay(...)` 创建支付宝支付参数；
@@ -109,6 +109,7 @@ MD5/SHA1 仅为兼容摘要；任何摘要都不能直接作为新密码存储
 |---|---|
 | 缓存 | `V8.Cache.Set/Get/Remove/Exists/KeyExist/HashSet/HashGet/HashGetAll/HashDelete/HashIncrement` |
 | HTTP | `V8.Http.Get/Post/Patch`、`GetResponse/PostResponse/PatchResponse` 及真实 `*Async` 版本 |
+| TCP | `V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync`；原始字节与出站安全见 `v8-tcp-integration` |
 | 图片 | `V8.Image.Create/Merge/Overlay/Watermark/Resize/Crop/Rotate/Flip/Draw/Convert/GetInfo/CreateQRCode` |
 | Office | `V8.Office.ExportExcel/ExcelToList/ExportWord/ExportPowerPoint/SendEmail` |
 | OCR | `await V8.OCR.Recognize({...})`；服务端租户配置与调用参数隔离，详见 `ocr-engine` |

package/skills/workspace-conventions/SKILL.md

@@ -58,7 +58,7 @@ Microi 平台后端功能必须默认按多节点部署设计：多个 API/Worke
 
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-003 sha256=5f3c011e88d1e36398a23a917949fcc8beaf6adee91e2a360d24bedd4ba322bb -->
+<!-- microi-progressive:chunk id=workspace-conventions-003 sha256=f11353ab84b85f319d592dac979e9a44fac3bc5aa50f827ad5aaa728f83fa18d -->
 ## 本地资源与 OOM 保护规范（强制）
 
 AI 在用户本机启动 Node.js、Vite、Webpack、dotnet build、Java、Docker build、浏览器自动化、压力测试或其他可能长时间占用 CPU/内存的进程前，必须先评估资源，不得为了“让构建跑过”无限抬高堆内存或 Worker 数。
@@ -70,6 +70,13 @@ AI 在用户本机启动 Node.js、Vite、Webpack、dotnet build、Java、Docker
 - 后台/长任务必须记录根 PID、子进程、启动时间和独立日志，每 15-30 秒监测一次进程树内存与全机可用内存。任务失败、中断或达阈值时必须停止整个子进程树，不得遗留孤儿 Node/dotnet/Java 进程。
 - 全量构建无法在上述阈值内完成时，先停止并改用定向 lint、类型检查、按模块构建或按测试文件验证。如仍必须进行全量验收，应明确报告资源瓶颈，交由 CI/专用构建机或经用户明确同意的独占时段执行，禁止在用户正在使用的 VS Code 会话里硬跑。
 
+### `Microi.Client` 框架前端构建频率（强制）
+
+- 修改吾码低代码平台框架前端 `Microi.Client/` 时，开发阶段必须优先复用已运行的 Vite 开发服务，通过热模块更新（HMR）、定向静态测试和浏览器回归验证改动。禁止把 `npm run build` 当作每轮修改后的常规检查，禁止因切换需求、修改单个组件或上下文压缩而重复执行全量构建。
+- 只有全部框架前端源码修改、定向测试和浏览器验收均已完成后，才允许在最终收尾阶段执行一次 `npm run build`，用于确认正式产物能否生成。执行前仍须按本节检查内存、同类进程和构建预算；已经成功且之后没有再修改框架前端源码时不得重复构建。
+- Vite 热更新未生效时，先检查页面、控制台、文件监听和当前 61500 开发服务归属；确需重启时按共享进程与发布锁规范精确停止本工作区原有 `npm run dev`，再重新执行 `npm run dev`。不得用 `npm run build` 代替开发服务重启，也不得结束所有 `node`、浏览器或其它对话的进程。
+- 本规则只约束 `Microi.Client/` 吾码框架前端源码。独立 MicroService、Web、UniApp 等应用源码仍按其交付 Skill 在发布前执行自身必要的构建；不得因为本规则跳过微服务正式产物生成。
+
 <!-- /microi-progressive:chunk -->
 <!-- microi-progressive:chunk id=workspace-conventions-004 sha256=5cd341a0dd0a827f16129a8587422b53c186d104a562ecb6640e6167567f9c0f -->
 ## 临时文件与 AI 产物放置规则（强制）

package/skills/workspace-conventions/references/progressive-01-/347/211/210/346/234/254/346/233/264/346/226/260/346/227/245/345/277/227/344/277/235/346/212/244/350/247/204/345/210/231-/345/274/272/345/210/266.md

@@ -30,7 +30,7 @@ AI 新增或修改 Microi 配置文件时，凡是面向开发者、部署人员
 - 修改后必须用源码测试扫描生产 `.cs`、API `appsettings.json` 及在线/离线 Compose，精确断言十项白名单。不能用注释约定代替自动化守卫。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-013 sha256=f71d409558e941597f9d66c10005885e228441df606e97011c798e41f91eff49 -->
+<!-- microi-progressive:chunk id=workspace-conventions-013 sha256=dbf22caaf1673270e6abf2277704505481f632c68c1da61df992c81a577e24df -->
 ## 身份、可逆业务秘密与敏感操作统一规范（强制）
 
 - DiyToken 是吾码多租户、多终端、V8 和低代码权限体系的唯一会话入口。新增密码、SSO、OAuth、Passkey、人脸或其它登录方式时，验证成功后必须继续签发 DiyToken，并复用现有角色、部门、菜单、表权限、数据范围、终端吊销和 Token 轮换；禁止整体替换为 ASP.NET Identity 或并行建立第二套用户/权限 Token。
@@ -39,7 +39,7 @@ AI 新增或修改 Microi 配置文件时，凡是面向开发者、部署人员
 - DES 是现有兼容格式，不得宣称能抵抗服务器所有者或代码执行者。新高价值秘密优先使用带版本的现代认证加密与集中密钥管理；基础设施密钥仍不得进入可编辑 V8。
 - 登录后的敏感操作优先用 `V8.Identity.Verify` 申请 Passkey、Authenticator TOTP 或严格人脸一次性票据，接口引擎从权威数据重算 `ActionHash` 后调用 `V8.Method.ConsumeIdentityVerificationTicket` 原子消费。票据不能代替菜单/表/行权限、状态机、幂等、事务或审计。
 - Windows Hello、Touch ID、Face ID 和 Android 设备验证优先采用 WebAuthn/Passkey；Microsoft/Google Authenticator 采用标准 TOTP，两者都不增加模型服务。只有服务端严格人脸与活体检测才接入独立 `Microi Face Gateway v1` 云服务或 Docker/集群。完整规范读取 `microi.skills/v8-security/SKILL.md` 与 `microi.doc/docs/doc/more/identity-verification.md`。
-- 外部登录统一在登录页【登录方式】中展示；Gitee、微信、GitHub 等 Provider 只登录个人中心已绑定的吾码用户，最终签发 DiyToken。Provider 固定协议端点，租户自己的 ClientId/ClientSecret 放 `mci_system_setting`；Secret 不进入浏览器/前端 `V8.SysConfig`，但后端接口引擎和后端 V8 事件可从当前租户根级 `V8.SysConfig[ConfigKey]` 使用，禁止回传或记录原文。
+- 外部登录统一在登录页【登录方式】中展示；Gitee、微信、GitHub 等 Provider 只登录个人中心已绑定的吾码用户，最终签发 DiyToken。Provider 固定协议端点，租户自己的 ClientId/ClientSecret 放 `mci_system_setting`；Secret 不进入浏览器/前端 `V8.SysConfig`，后端接口引擎和后端 V8 事件只能从当前租户 `V8.SysConfig.ServerPrivateSettings[ConfigKey]` 使用，禁止回传或记录原文。
 - 一键安装恢复客户旧库时只允许定位精确主租户三元组；缺失则幂等创建，重复则停止，不能批量重写其它子租户。新主租户行不得持久化数据库、MongoDB 或 Redis 连接，安装器对 MinIO/OCR 等业务配置的后续更新也必须带同一三元组、活动状态条件并做唯一回读。
 
 <!-- /microi-progressive:chunk -->