@microi.net/cli 4.8.7 → 4.8.8

package/skills/microi-microservice/references/runtime-delivery.md

@@ -62,13 +62,17 @@
 | `microi_get_application_file` | 读取单文件 |
 | `microi_get_microservice` | 回读已发布运行时 |
 | `microi_create_microservice` | dry-run/创建运行元数据 |
-| `microi_sync_microservice_source` | 同步私有源码 |
+| `microi_sync_microservice_source` | 同步私有源码；本地工程首选绝对路径 `directory` |
 | `microi_publish_application_directory_stream` | 流式发布真实构建目录 |
 | `microi_publish_microservice` | 小产物兼容发布 |
 
 `replace=true` 会清理源码清单外的旧元数据，属于覆盖性写入；必须先展示文件差异并
 获得明确确认。超时先回读，不重复发布。
 
+本地源码目录由 MCP 进程直接扫描和读取，AI 只看路径、大小、哈希与清单；禁止生成
+`.sync-seg-*`、`sync-source-files.json` 或手工 Base64 分段。单个源码超过模型读取上限时仍保持
+一个真实文件。`sourceFiles` 只保留没有本地目录时的旧调用兼容。
+
 真实构建目录一律使用逐文件 multipart 流：默认/硬上限为 20,000 文件、总计 20GB，
 文件体不进入 JSON、Base64 或 Jint。`StorageMode=db` 的 256 文件/5MB 仅用于小型
 应急恢复，不能作为大项目发布器。发布器必须持久化同一交付批次的
@@ -90,6 +94,7 @@
 - `MicroServiceRoutePath`
 - `MicroServiceKey`
 - `ComponentPath=/micro-app/host`
+- `ModuleEngineKey`（宿主权限上下文）
 
 无需导航的内部页面直接在 `sys_microiservice_page.RouteMetaJson` 设置
 `InternalOnly=true`；不再依赖伪造的隐藏 `sys_menu` 才能刷新友好路由。真正需要菜单
@@ -105,6 +110,7 @@ V8.OpenAppDialog({
   Width: 'min(960px, calc(100vw - 32px))',
   OpenType: 'Drawer',
   Data: { Id: V8.Form.Id },
+  ModuleEngineKey: 'authorized-module-key',
   OnSuccess: function (data) {
     V8.RefreshTable({ _PageIndex: -1 });
   },
@@ -124,8 +130,16 @@ V8.OpenAppDialog({
 const host = window.microApp?.getData?.() || {};
 ```
 
-常见字段：`apiBase`、`osClient`、`token`、`appKey`、`version`、
-`microRoute`、`dialog`、`dialogData`。只在内存中使用 Token。
+常见字段：`apiBase`、`osClient`、`token`、`menuId`、`moduleEngineKey`、`diyTableId`、
+`permissionContext`、`appKey`、`version`、`microRoute`、`dialog`、`dialogData`。只在内存中使用 Token。
+
+独立访问时没有宿主 Token：先配置清单中的 `apiBase/osClient`，读取 `V8.GetSysConfig(true)`，
+没有有效本地 Token 才显示吾码帐号密码登录；按 `EnableCaptcha` 动态请求验证码并向 `V8.Login`
+提交 `_CaptchaId/_CaptchaValue`。嵌入菜单或弹层时复用宿主身份，不显示第二套登录。
+
+`permissionContext={sysMenuId,moduleEngineKey,diyTableId}` 只帮助子应用选择正确的 FormEngine
+模块上下文，不能授予权限。无权限时依次核对 Token/OsClient、模块 Key、宿主上下文和角色授权；
+禁止去掉权限参数、改匿名接口或硬编码管理员 Token。
 
 页面根容器使用 `min-height: var(--micro-app-available-height, 100vh)`，让后台菜单、弹窗和
 移动端共享宿主实测高度；不要在嵌入模式直接固定 `100vh`。宿主高度变化时还会通过

package/skills/ui-design/SKILL.md

@@ -1583,7 +1583,7 @@ Microi 的 UI 规范不应该只停留在 skills 文档。面向品牌长期建
 - MCI-UI 应分层建设：`@microi/theme` 负责 tokens；`@microi/v8` 负责前端 SDK；`@microi/ui-mobile` 面向 UniApp；`@microi/ui-web` 面向官网和响应式站点；`Microi.Client` 后台则用 Element Plus + MCI theme。
 - `microi.doc` 作为 VitePress 官方文档站，应逐步成为 MCI-UI 的展示入口：组件演示、设计变量、移动端骨架屏、安全区、富文本、上传资源、主题切换都应该有可查看示例，而不是只写在 skill 中。
 
-## MCI-UI 源码落地位置
+## MCI-UI 源码落地位置
 
 MCI-UI 已在吾码源码根目录落地：`Microi.UI/`。
 
@@ -1593,4 +1593,17 @@ MCI-UI 已在吾码源码根目录落地：`Microi.UI/`。
 - `Microi.UI/src/theme/runtime.js` 是主题运行时入口；项目应通过 `initMciDesign()`、`setMciPalette()`、`setMciShape()`、`setMciTheme()` 统一设置黑白红橙黄绿青蓝紫主色、圆角/扁平、亮暗主题和动效偏好。
 - `MciPage` 默认带页面入场动效；业务页如果有特殊路由转场，可以关闭 `animated` 后使用项目级转场，但不能让动态页面无反馈地直接闪现。
 - `MciButton`、`MciCard` 必须保留 hover/pressed/focus/sheen 等基础反馈；业务组件可以封装样式，但不能删掉交互状态。
-- 第三方 UI 库只能作为底层能力或局部补充，不能绕过 MCI-UI 直接决定产品视觉。
+- 第三方 UI 库只能作为底层能力或局部补充，不能绕过 MCI-UI 直接决定产品视觉。
+
+## VitePress 中文文档布局规范
+
+`microi.doc` 不是纯文本仓库，而是 Microi 产品体验的一部分。创建或重构中文文档页时：
+
+- 页面首屏使用标题、简短价值说明和 2–4 个关键能力视觉分组，避免打开后先看到十几段连续正文。
+- 正文阅读宽度控制在约 `86ch`，代码、表格、架构图和案例截图可使用全宽；标题间距必须明显大于段落间距。
+- 卡片用于并列能力、选择和案例，表格用于精确对比，流程带用于阶段关系，截图用于真实结果；不要把相同信息在四种视觉里重复一遍。
+- 使用 MCI 主题变量，不在 Markdown 中散落硬编码颜色；亮/暗主题均保证文字、边框、代码和状态对比度。
+- 页面专属 CSS 独立存放并以 marker 限定范围；全站字体、段落、列表、`details`、图片与焦点样式归整站主题层。
+- 桌面使用多列时，980px 以下要能降为单列；表格和代码可横向滚动，普通正文与图片不得产生页面级横向滚动。
+- 图片必须有语义化 `alt` 与图注；纯装饰图标设置 `aria-hidden`。交互控件保留键盘焦点，动画遵守 `prefers-reduced-motion`。
+- 完成后同时跑中文文档可读性门禁、VitePress 构建，并用真实浏览器查看桌面/移动、亮色/暗色。只看 Markdown 源码或构建日志不能算视觉验收。

package/skills/v8-file-upload/SKILL.md

@@ -188,6 +188,14 @@ var extractResult = V8.Method.ExtractZip({
 - 安装脚本还必须同步当前有效 `sys_config`：`ApiBase` 使用对外可访问的 API 端口，`FileServer` 使用 `http://<访问IP>:<MinIO API端口>/mci-public`。`ApiBase` 不能误用 Web 前端端口，因为 V8 代码会直接在其后拼接 `/api/...` 或 `/apiengine/...`。
 - 安装验收必须使用真实登录 Token 分别执行一次 `Limit=false` 和 `Limit=true` 上传：公有文件匿名访问应返回 `200`，私有文件匿名访问应返回 `403`，私有文件通过签名 URL 访问应返回 `200`，并核对下载内容与上传内容一致。
 
+### 复盘：签名 HEAD 被代理转换为 GET 导致上传后回读误报
+
+- 触发场景：`PutObject` 已返回成功、对象可通过 GET 下载，但公有桶和私有桶的上传后 `StatObject` 均对桶根路径返回 `AccessDenied`；常见于启用严格回读校验后，MinIO Endpoint 前的 Nginx 同时启用了缓存与默认的 `proxy_cache_convert_head on`。
+- 根因判断：S3 SigV4 的签名包含 HTTP 方法；代理把客户端签名的 HEAD 转为上游 GET 后会造成签名不一致。另一个可能原因是对象级凭据缺少桶级 `ListBucket` / `GetBucketLocation` 权限，因此不能只凭 `AccessDenied /bucket/` 推断对象未落盘，也不能把空 Region 当作唯一原因。
+- 通用规则：优先在 MinIO 代理位置设置 `proxy_cache_convert_head off`；若仍使用缓存，缓存键需区分 `$request_method`。平台不得跳过上传后回读：当 HEAD/Stat 失败时，使用同一凭据生成签名 GET，并以 `Range: bytes=0-0` 回读；禁用重定向，非空对象必须同时验证期望总长度与首字节，空对象验证长度为零，`404` 判不存在，`403`、网络错误和证据不足继续失败关闭。禁止记录或返回带签名查询参数的 URL。
+- 配置边界：只有实时回读证明 Endpoint、桶名、Region 或凭据确实错误时才修改 SaaS 配置；对象 GET 正常而仅 HEAD 失败时应修复代理或兼容回读路径，不能猜测内网地址、降低校验强度或轮换正常凭据。
+- 自动化检查：覆盖签名 GET 的单字节 Range、期望总长度、首字节实际读取、空对象、长度不符、重定向、`403` 和 `404`；真实环境同时验证公有桶与私有桶的 `Put -> Range GET -> 内容一致`，并对比相同签名在 GET 与 HEAD 方法下的响应。
+
 ### 复盘：旧空库缺少可选字段导致 MinIO 初始化后中断
 
 - 触发场景：MinIO 容器、私有桶和公有桶均已成功创建，但安装器更新 `sys_osclients` 时因旧库缺少 `NetworkIsInternet` 返回 `Unknown column`，整套安装停在 API 部署之前。