@microi.net/cli 5.8.5 → 5.8.7

package/skills/microi-deployment/references/deployment-matrix.md

@@ -1,109 +1,109 @@
-# 部署矩阵与验收
-
-## 中文官网路由
-
-| 文档 | 主要用途 |
-|---|---|
-| `microi.doc/docs/doc/getting-started/docker-run.md` | Docker、Compose、离线包、依赖编排 |
-| `microi.doc/docs/doc/getting-started/win-install-microi.md` | Windows/IIS 安装 |
-| `microi.doc/docs/doc/getting-started/local-run.md` | 后端/前端源码运行、测试与构建 |
-| `microi.doc/docs/doc/getting-started/start-use.md` | 部署后创建表、表单、菜单的首条业务链路 |
-
-英文目录由中文生成，不作为本轮人工单独维护源。
-
-## 服务依赖
-
-| 依赖 | 作用 | 生产要求 |
-|---|---|---|
-| API/Worker | 后端、V8、任务与接口 | 至少双节点关键场景验证 |
-| Web/Nginx/IIS | 前端与反向代理 | HTTPS、上传体积、超时、静态缓存 |
-| MySQL/兼容业务库 | 平台与业务数据 | 备份、字符集、连接池、慢查询 |
-| Redis | 会话、缓存、租约、进度 | 持久化/高可用、按租户 Key |
-| MongoDB | 日志等文档数据 | 持久卷、容量与重放验收 |
-| MinIO/HDFS | 上传和应用资源 | 公私桶、持久卷、备份、CORS |
-
-可选依赖如翻译服务、Ollama、Qdrant 只在相应能力启用时部署，不把演示编排无条件
-带入生产。
-
-## 配置归类
-
-| 配置 | 原则 |
-|---|---|
-| 数据库连接 | 密钥管理/环境注入，不入库明文示例 |
-| Redis/Mongo/对象存储 | 全节点一致、网络可达、租户隔离 |
-| AuthSecret/JWT | 集群一致；变更会影响已有登录态 |
-| ApiBase/FileServer | 与反向代理外部地址一致 |
-| 上传上限 | API、代理、租户配置三层一致 |
-| 日志 spool | 每节点持久卷；Mongo 恢复后幂等重放 |
-| 容器内存 | 多服务共机时给每容器合理 limit |
-
-## Docker/Compose
-
-执行前：
-
-1. 固定目标目录和 compose 文件，解析所有 volume 的绝对宿主路径。
-2. 校验镜像 tag/digest、端口、网络、重启策略、healthcheck 和 secrets。
-3. 备份数据库、对象存储与配置，并验证备份可读。
-4. `docker compose config` 只作静态校验，不代表服务可运行。
-
-发布时一次只替换部分 API 节点；readiness 正常后再替换下一节点。数据库和对象存储
-卷不随应用容器重建删除。Watchtower/自动更新若启用，必须保证 AuthSecret、配置卷和
-健康检查不因容器替换漂移。
-
-离线安装包要包含精确镜像、校验和、compose、配置模板和安装说明；目标机导入后复核
-镜像 digest，不能只看文件解压成功。
-
-## Windows/IIS
-
-至少核对：
-
-- .NET Hosting Bundle 与应用目标框架匹配；
-- Application Pool 使用无托管代码并具备目录权限；
-- API 和 Web 站点绑定、HTTPS、反向代理与 WebSocket 配置；
-- 应用数据、上传、日志和 spool 目录不放临时发布目录；
-- Windows 服务/计划任务不会与 IIS 节点重复执行同一后台任务；
-- MySQL、Redis、MongoDB、MinIO 服务开机启动和恢复策略。
-
-IIS 进程启动不代表 API 可用，仍要检查 readiness 和真实登录路径。
-
-## 本地源码运行
-
-macOS 的一键发布探针通过 `run_with_timeout` 使用 GNU `timeout`、`gtimeout` 或仓库 Node 工具 `Microi.Server/tools/run-with-timeout.mjs`。缺少 GNU 命令不能据此判定 Docker 不健康；超时工具只停止自身创建的探针进程。官网专用选项 6 不发布 DLL/NuGet，后端发布的加密门禁保持有效。
-
-Obfuscar 路径转换只适用于 Git Bash/MSYS/Cygwin。macOS/Linux 的 `/Users`、`/usr` 等绝对路径直接传给工具；Windows 优先 `cygpath`，无该命令时只转换完整盘符根路径。修复后使用隔离副本验证五个 DLL 和指纹，再重新执行一键脚本的 Full 与最终加密产物冒烟。
-
-在线 AI MCP 的生产依赖和命令复制为完整、自足的运行快照，生产命令链接解析为真实文件，保留执行权限；损坏、越界及目录循环链接提前拒绝。临时构建目录清理后命令必须仍能运行，旧依赖不得残留；不放宽原制品门禁。
-
-前端构建的 macOS 可用内存按有界 `vm_stat` 的真实页大小计算空闲页加可回收文件页，不叠加匿名非活动、压缩或预读页。解析失败和探针超时回退原生空闲量；Windows/Linux 保持原统计方式。启动预算、95% 暂停、90% 恢复及连续五秒稳定门禁不变，正式发布不能跳过保护；统计错误应修正探针，并保留共享服务。
-
-后端：
-
-- 使用当前仓库规定的 .NET SDK；
-- 配置开发专用数据库/Redis/Mongo/对象存储；
-- 先跑定向测试，再按资源允许程度执行更大构建；
-- 不让本地调试连接生产写库。
-
-前端：
-
-- 使用仓库规定的 Node/npm/pnpm 版本；
-- 复用已有 Vite 服务，不重复启动；
-- `src/config.json` 的 `ApiBaseDev` 是默认值；本地 URL 可在 `#` 前用
-  `?OsClient=...&ApiBase=...` 以最高优先级覆盖 ApiBase 与租户；
-- 多组 `ApiBase + OsClient` 并行时按组创建独立浏览器 Profile/进程或 Playwright context，不能在
-  同一同源 context 的多个 Page 中混测；
-- 人工第二组至少使用无痕窗口，但多个 Chrome 无痕窗口可能共享临时会话，不能承担多组强隔离；
-- 从线上页面读取 `window.__MICROI_RUNTIME_ENDPOINT__`；旧版无该对象时按 URL、window 全局、
-  同源状态、域名解析/成功请求逐级确认，禁止猜测；
-- 本地页面成功不替代宿主 Token、OsClient、菜单权限和生产构建验收。
-
-## 最小上线验收
-
-- API liveness 200，readiness 200；依赖降级能在 readiness/日志中体现。
-- Web 首屏、登录、退出、Token 刷新正常。
-- 管理员与普通角色各验证一个菜单和数据权限。
-- FormEngine 新增/编辑/查询，ApiEngine 调用正常。
-- 公有/私有文件各上传、预览/下载一次，Range/HEAD 按需验证。
-- Redis/Mongo/对象存储短暂不可用后可恢复，无永久死锁或静默丢失。
-- 双节点同时触发同一 Job/消息，业务副作用仅一次。
-- 发布中终止一个节点，其余节点继续服务；恢复节点不重复初始化。
-- 回滚步骤和恢复点已实际验证或明确标记未验证。
+# 部署矩阵与验收
+
+## 中文官网路由
+
+| 文档 | 主要用途 |
+|---|---|
+| `microi.doc/docs/doc/getting-started/docker-run.md` | Docker、Compose、离线包、依赖编排 |
+| `microi.doc/docs/doc/getting-started/win-install-microi.md` | Windows/IIS 安装 |
+| `microi.doc/docs/doc/getting-started/local-run.md` | 后端/前端源码运行、测试与构建 |
+| `microi.doc/docs/doc/getting-started/start-use.md` | 部署后创建表、表单、菜单的首条业务链路 |
+
+英文目录由中文生成，不作为本轮人工单独维护源。
+
+## 服务依赖
+
+| 依赖 | 作用 | 生产要求 |
+|---|---|---|
+| API/Worker | 后端、V8、任务与接口 | 至少双节点关键场景验证 |
+| Web/Nginx/IIS | 前端与反向代理 | HTTPS、上传体积、超时、静态缓存 |
+| MySQL/兼容业务库 | 平台与业务数据 | 备份、字符集、连接池、慢查询 |
+| Redis | 会话、缓存、租约、进度 | 持久化/高可用、按租户 Key |
+| MongoDB | 日志等文档数据 | 持久卷、容量与重放验收 |
+| MinIO/HDFS | 上传和应用资源 | 公私桶、持久卷、备份、CORS |
+
+可选依赖如翻译服务、Ollama、Qdrant 只在相应能力启用时部署，不把演示编排无条件
+带入生产。
+
+## 配置归类
+
+| 配置 | 原则 |
+|---|---|
+| 数据库连接 | 密钥管理/环境注入，不入库明文示例 |
+| Redis/Mongo/对象存储 | 全节点一致、网络可达、租户隔离 |
+| AuthSecret/JWT | 集群一致；变更会影响已有登录态 |
+| ApiBase/FileServer | 与反向代理外部地址一致 |
+| 上传上限 | API、代理、租户配置三层一致 |
+| 日志 spool | 每节点持久卷；Mongo 恢复后幂等重放 |
+| 容器内存 | 多服务共机时给每容器合理 limit |
+
+## Docker/Compose
+
+执行前：
+
+1. 固定目标目录和 compose 文件，解析所有 volume 的绝对宿主路径。
+2. 校验镜像 tag/digest、端口、网络、重启策略、healthcheck 和 secrets。
+3. 备份数据库、对象存储与配置，并验证备份可读。
+4. `docker compose config` 只作静态校验，不代表服务可运行。
+
+发布时一次只替换部分 API 节点；readiness 正常后再替换下一节点。数据库和对象存储
+卷不随应用容器重建删除。Watchtower/自动更新若启用，必须保证 AuthSecret、配置卷和
+健康检查不因容器替换漂移。
+
+离线安装包要包含精确镜像、校验和、compose、配置模板和安装说明；目标机导入后复核
+镜像 digest，不能只看文件解压成功。
+
+## Windows/IIS
+
+至少核对：
+
+- .NET Hosting Bundle 与应用目标框架匹配；
+- Application Pool 使用无托管代码并具备目录权限；
+- API 和 Web 站点绑定、HTTPS、反向代理与 WebSocket 配置；
+- 应用数据、上传、日志和 spool 目录不放临时发布目录；
+- Windows 服务/计划任务不会与 IIS 节点重复执行同一后台任务；
+- MySQL、Redis、MongoDB、MinIO 服务开机启动和恢复策略。
+
+IIS 进程启动不代表 API 可用，仍要检查 readiness 和真实登录路径。
+
+## 本地源码运行
+
+macOS 的一键发布探针通过 `run_with_timeout` 使用 GNU `timeout`、`gtimeout` 或仓库 Node 工具 `Microi.Server/tools/run-with-timeout.mjs`。缺少 GNU 命令不能据此判定 Docker 不健康；超时工具只停止自身创建的探针进程。官网专用选项 6 不发布 DLL/NuGet，后端发布的加密门禁保持有效。
+
+Obfuscar 路径转换只适用于 Git Bash/MSYS/Cygwin。macOS/Linux 的 `/Users`、`/usr` 等绝对路径直接传给工具；Windows 优先 `cygpath`，无该命令时只转换完整盘符根路径。修复后使用隔离副本验证五个 DLL 和指纹，再重新执行一键脚本的 Full 与最终加密产物冒烟。
+
+在线 AI MCP 的生产依赖和命令复制为完整、自足的运行快照，生产命令链接解析为真实文件，保留执行权限；损坏、越界及目录循环链接提前拒绝。临时构建目录清理后命令必须仍能运行，旧依赖不得残留；不放宽原制品门禁。
+
+前端构建的 macOS 可用内存按有界 `vm_stat` 的真实页大小计算空闲页加可回收文件页，不叠加匿名非活动、压缩或预读页。解析失败和探针超时回退原生空闲量；Windows/Linux 保持原统计方式。启动预算、95% 暂停、90% 恢复及连续五秒稳定门禁不变，正式发布不能跳过保护；统计错误应修正探针，并保留共享服务。
+
+后端：
+
+- 使用当前仓库规定的 .NET SDK；
+- 配置开发专用数据库/Redis/Mongo/对象存储；
+- 先跑定向测试，再按资源允许程度执行更大构建；
+- 不让本地调试连接生产写库。
+
+前端：
+
+- 使用仓库规定的 Node/npm/pnpm 版本；
+- 复用已有 Vite 服务，不重复启动；
+- `src/config.json` 的 `ApiBaseDev` 是默认值；本地 URL 可在 `#` 前用
+  `?OsClient=...&ApiBase=...` 以最高优先级覆盖 ApiBase 与租户；
+- 多组 `ApiBase + OsClient` 并行时按组创建独立浏览器 Profile/进程或 Playwright context，不能在
+  同一同源 context 的多个 Page 中混测；
+- 人工第二组至少使用无痕窗口，但多个 Chrome 无痕窗口可能共享临时会话，不能承担多组强隔离；
+- 从线上页面读取 `window.__MICROI_RUNTIME_ENDPOINT__`；旧版无该对象时按 URL、window 全局、
+  同源状态、域名解析/成功请求逐级确认，禁止猜测；
+- 本地页面成功不替代宿主 Token、OsClient、菜单权限和生产构建验收。
+
+## 最小上线验收
+
+- API liveness 200，readiness 200；依赖降级能在 readiness/日志中体现。
+- Web 首屏、登录、退出、Token 刷新正常。
+- 管理员与普通角色各验证一个菜单和数据权限。
+- FormEngine 新增/编辑/查询，ApiEngine 调用正常。
+- 公有/私有文件各上传、预览/下载一次，Range/HEAD 按需验证。
+- Redis/Mongo/对象存储短暂不可用后可恢复，无永久死锁或静默丢失。
+- 双节点同时触发同一 Job/消息，业务副作用仅一次。
+- 发布中终止一个节点，其余节点继续服务；恢复节点不重复初始化。
+- 回滚步骤和恢复点已实际验证或明确标记未验证。

package/skills/microi-docs-coverage/SKILL.md

@@ -1,133 +1,133 @@
----
-name: microi-docs-coverage
-description: Microi 中文官网文档与 Skills 能力覆盖审计。用于全面分析 microi.doc/docs/doc 与 docs/case、核对官方能力和 V8 函数是否已进入 microi.skills、补充或重构 Skills、维护文档到 Skill 的责任映射，以及防止后续新增中文文档造成 AI 知识漏项。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi 中文官网文档与 Skills 覆盖审计
-
-当任务涉及“官网有但 AI 不知道”“全面同步官方文档到 Skills”“核对所有
-V8 函数”或新增、调整官方中文文档时，使用本 Skill。
-
-创始人源码工作区中的平台功能还必须执行 [工作区基础规范](../workspace-conventions/SKILL.md)
-的“平台功能四项同步检查”：本 Skill 负责文档与 AI 知识覆盖，不能替代官方应用包发布
-或 MCP 能力验收。既有页面、Skill 或 MCP 已完整覆盖时记录依据，不重复创建同义内容。
-
-## 范围与事实源
-
-- 能力映射扫描 `microi.doc/docs/doc/**/*.md`，但排除受发版规则保护的
-  `microi.doc/docs/doc/about/update-log.md`；视觉与可读性审计还必须包含
-  `microi.doc/docs/case/**/*.md`。
-- `index.md`、`apps.md`、`app-detail.md`、`profile.md`、`login.md` 与
-  `contact/index.md` 是由专用 Vue 组件承载的站点交互页，必须单独登记并按各自
-  页面契约验收，不能静默漏扫，也不能机械套用正文档排版。
-- 不扫描、不手工维护 `microi.doc/docs/en/`；英文站由中文站统一翻译。
-- `references/capability-map.md` 维护每篇中文文档的责任 Skill。
-- 文档描述能力边界，当前源码、接口定义、组件清单和 MCP Schema 决定真实签名。
-- 不把客户表名、业务字段、扩展数据库名称或示例返回字段误判为平台 API。
-
-## 审计流程
-
-1. 运行自动审计：
-
-   ```powershell
-   node microi.skills/microi-docs-coverage/scripts/audit-doc-skill-coverage.mjs
-   ```
-
-2. 先解决“未映射文档”和“无效责任 Skill”。每篇中文文档都必须在能力映射中
-   有明确负责人；宣传、培训、FAQ 等非 API 页面也要标明信息型覆盖。
-3. 查看“未覆盖 V8 API、其它具名 API、MCP 工具”。逐项回到中文文档和
-   当前源码确认：
-   - 真实平台 API：补到对应 Skill 或 `v8-utilities` 索引。
-   - 业务数据路径：归一为 `V8.Form`、`V8.Param` 等上下文对象。
-   - 动态扩展名：归一为 `V8.Dbs`，不要固化客户数据库名称。
-   - 文档旧名或错误：以源码为准，说明兼容边界；不要为让审计通过而虚构 API。
-4. 把高频决策和最小安全示例写进 `SKILL.md`；完整方法表、平台差异、硬件/
-   部署验收写进 `references/`，保持渐进披露。
-5. 更新 `references/capability-map.md`，重新运行审计，直到严格检查通过。
-6. 对每个新增或改动的 Skill 运行 `skill-creator` 的 `quick_validate.py`，
-   再执行 `git diff --check` 和相对链接检查。
-7. 修改已注册的后端内嵌知识时，运行
-   `node microi.skills/scripts/sync-embedded-skills.mjs <skill-name...>`，再带 `--check`
-   回读一致性；它只更新已在 `Microi.AI.csproj` 注册的快照，正文仍来自 canonical Skills。
-   修改渐进内容后先显式刷新本次 Skill 的校验清单，再按名称验证；全库检查发现历史漂移时
-   单独记录，禁止修改无关 Skill 的哈希来掩盖漏项。插件/CLI 使用现有构建器同步分发副本，
-   打包成功不等于已发布到用户安装渠道。
-
-## 中文文档视觉与可读性契约（强制）
-
-文档正确但密密麻麻仍属于未完成。修改 `microi.doc/docs/doc/**/*.md` 或
-`microi.doc/docs/case/**/*.md` 时同时遵守：
-
-- 正文使用清晰的 H1/H2/H3 层级和 80–90 字符左右的阅读宽度；连续长段落拆为短段、列表、对比表、步骤、流程或有语义的卡片。不要为了“丰富”把每句话都做成卡片。
-- 首屏先回答“这是什么、有什么价值、怎么选择”，再展开原理和完整参数；长篇高级细节可使用可访问的 `details/summary` 渐进披露。
-- 三个以上可比较能力优先使用表格或网格卡片；三步以上的依赖流程优先使用流程图/步骤带。图标必须帮助辨识，不能只作装饰噪声。
-- 颜色至少区分主能力、成功、警告、风险，但正文对比度必须满足易读要求；不能只靠颜色表达状态。亮色、暗色、窄屏和 `prefers-reduced-motion` 都要有样式。
-- 真实案例截图进入 `docs/public/images/...`，使用稳定英文文件名、有效 `alt` 和简短图注；图片不得代替关键文字说明，移动端不得横向撑破页面。
-- 整站共同规则优先落在 VitePress 主题层 `mci-site.scss` / `doc-readable.scss`，页面独有展示放独立 SCSS；禁止为几十篇 Markdown 机械复制内联 `<style>`。
-- 新页面可复用 `.mci-doc-grid`、`.mci-doc-card`、`.mci-doc-chip`；产品页需要独立视觉时使用页面 marker + `body:has(...)` 限定作用域，不能污染登录页、首页或英文生成页。
-- 改动后运行 `npm run check:readability` 与 `npm run check:content`，再在真实浏览器至少检查一个桌面宽度和一个移动宽度，覆盖亮/暗主题、代码块、表格、图片、侧栏与锚点。
-- `microi.doc/docs/en/` 由脚本生成，不手工同步样式化内容；日常文档工作继续禁止修改 `about/update-log.md`。
-
-自动可读性检查只能阻止缺少 H1、超长连续文字块或整站主题契约丢失，不能证明页面真正好看。最终仍要查看渲染结果，不能用构建成功替代视觉验收。
-
-全站任务必须进一步执行以下闭环，禁止把“扫描到若干 `/doc` 文件”等同于
-“全部中文阅读页已完善”：
-
-1. 在 `docs/.vitepress/theme/doc-visual-profiles.js` 为每个 `/doc` 与 `/case` 中文阅读页明确选择 `overview`、`guide`、`reference`、`policy` 或 `showcase`。新增、删除、移动文档时，页面清单与视觉档案必须同步闭环；专用站点交互页需显式登记为独立范围，英文路由不得进入该表。
-2. 运行 `npm run audit:visual` 查看逐页报告。强制检查应覆盖唯一 H1、首屏引导、章节密度、连续正文、页面类型对应的表格/列表/代码/图片/提示/自定义布局、图片 `alt` 和主题契约；交付前应达到 0 条阻断和 0 条密度建议。
-3. 中文样式若用 `html:lang(zh) { ... }` 包裹，根暗色选择器必须写成 `&.dark`，使 Sass 编译为 `html:lang(zh).dark`；写 `.dark` 会错误编译为后代选择器并导致暗色覆盖失效。所有自定义浅/暗背景都必须与前景、次要文字、边框成对切换，并用测试验证正文至少达到 WCAG AA 4.5:1。
-4. 在浏览器遍历全部中文阅读路由（包括 `/doc` 与 `/case`），检查页面类型类、唯一 H1、页面级横向溢出和明显低对比文字；再从五种视觉类型各选代表页，覆盖桌面/移动与亮色/暗色截图。专用站点交互页按自身组件测试与代表截图验收。只有已登记范围全部通过，才可描述为“全站视觉验收完成”。
-5. 静态脚本、Sass 编译、单元测试、VitePress 构建和浏览器截图是不同证据层。任何一层因资源保护或环境问题跳过，最终必须明确写出，不能用其它层替代。
-
-## 自动审计能证明什么
-
-脚本验证：
-
-- 中文文档清单与责任映射闭环；
-- 映射中没有已删除文档或不存在的 Skill；
-- 文档出现的标准化 `V8.*` 名称至少在某个 Skill Markdown 中出现；
-- 文档出现的 `System`、`DiyCommon`、`SqlFunc`、`SqlSubQuery`、
-  `V8ExtensionRegistry` 具名 API 至少在某个 Skill 中出现；
-- 文档出现的 `microi_*` MCP 工具名至少在某个 Skill 中出现；
-- 文档出现的平台 HTTP 路由和平台全局函数至少在某个 Skill 中出现；
-- 当前前端组件清单中的全部 `Control` 已进入表单组件参考；
-- `v8-print.js`、`ble/tsc.js`、`ble/esc.js` 的公开蓝牙入口和全部构建器方法，
-  已同时进入中文官方文档、蓝牙 Skills 与前端 Monaco API 提示；
-- `diy.common.js`、`diy-form.vue`、`diy-table.vue` 仍真实调用
-  `initV8Print`，且三处挂载范围已写入官方文档与 Skill；
-- 动态业务路径被单独列出，便于人工复核。
-
-脚本不能证明：
-
-- Skill 的语义、示例、安全约束一定正确；
-- 文档本身没有过时；
-- 浏览器、蓝牙设备、打印机、数据库或多节点部署已经实测。
-
-因此每轮全面同步还要做源码核对和按风险分层的真实验收，不能只追求字符串
-覆盖率。
-
-## 补充内容的归属
-
-- 前端通用 API、扫码、消息、表格/表单助手：`v8-utilities`、
-  `v8-frontend-events`。
-- 蓝牙直连运行、连接与批量语义：
-  `v8-frontend-events/references/bluetooth-print.md`；TSC/ESC 源码方法与编码：
-  `v8-frontend-events/references/bluetooth-print-api.md`；服务端模板打印仍归
-  `print-engine`。
-- 后端通用上下文、Method、Base64、加密：`v8-utilities`。
-- 表单设计器和字段组件：`microi-form-engine`。
-- 菜单、模块与页面入口：`module-engine`。
-- 部署、运行、配置和升级：`microi-deployment`。
-- Dos.ORM 与扩展数据库：`dos-orm`。
-- 微服务/前端微应用：`microi-microservice`。
-- 其它专项能力优先补到已有同名 Engine/V8 Skill，避免再建内容重叠的 Skill。
-
-## 禁止事项
-
-- 不复制整篇官网文档到一个巨型 Skill。
-- 不用叶子方法同名匹配掩盖对象归属错误。
-- 不把 `V8.Form.OrderNo`、`V8.Param.id` 等业务字段当成平台函数。
-- 不为了本次普通补充修改版本更新日志、英文文档或 Skills 版本清单。
-- 不声称静态审计等于真实硬件、浏览器、远端或生产验收。
+---
+name: microi-docs-coverage
+description: Microi 中文官网文档与 Skills 能力覆盖审计。用于全面分析 microi.doc/docs/doc 与 docs/case、核对官方能力和 V8 函数是否已进入 microi.skills、补充或重构 Skills、维护文档到 Skill 的责任映射，以及防止后续新增中文文档造成 AI 知识漏项。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi 中文官网文档与 Skills 覆盖审计
+
+当任务涉及“官网有但 AI 不知道”“全面同步官方文档到 Skills”“核对所有
+V8 函数”或新增、调整官方中文文档时，使用本 Skill。
+
+创始人源码工作区中的平台功能还必须执行 [工作区基础规范](../workspace-conventions/SKILL.md)
+的“平台功能四项同步检查”：本 Skill 负责文档与 AI 知识覆盖，不能替代官方应用包发布
+或 MCP 能力验收。既有页面、Skill 或 MCP 已完整覆盖时记录依据，不重复创建同义内容。
+
+## 范围与事实源
+
+- 能力映射扫描 `microi.doc/docs/doc/**/*.md`，但排除受发版规则保护的
+  `microi.doc/docs/doc/about/update-log.md`；视觉与可读性审计还必须包含
+  `microi.doc/docs/case/**/*.md`。
+- `index.md`、`apps.md`、`app-detail.md`、`profile.md`、`login.md` 与
+  `contact/index.md` 是由专用 Vue 组件承载的站点交互页，必须单独登记并按各自
+  页面契约验收，不能静默漏扫，也不能机械套用正文档排版。
+- 不扫描、不手工维护 `microi.doc/docs/en/`；英文站由中文站统一翻译。
+- `references/capability-map.md` 维护每篇中文文档的责任 Skill。
+- 文档描述能力边界，当前源码、接口定义、组件清单和 MCP Schema 决定真实签名。
+- 不把客户表名、业务字段、扩展数据库名称或示例返回字段误判为平台 API。
+
+## 审计流程
+
+1. 运行自动审计：
+
+   ```powershell
+   node microi.skills/microi-docs-coverage/scripts/audit-doc-skill-coverage.mjs
+   ```
+
+2. 先解决“未映射文档”和“无效责任 Skill”。每篇中文文档都必须在能力映射中
+   有明确负责人；宣传、培训、FAQ 等非 API 页面也要标明信息型覆盖。
+3. 查看“未覆盖 V8 API、其它具名 API、MCP 工具”。逐项回到中文文档和
+   当前源码确认：
+   - 真实平台 API：补到对应 Skill 或 `v8-utilities` 索引。
+   - 业务数据路径：归一为 `V8.Form`、`V8.Param` 等上下文对象。
+   - 动态扩展名：归一为 `V8.Dbs`，不要固化客户数据库名称。
+   - 文档旧名或错误：以源码为准，说明兼容边界；不要为让审计通过而虚构 API。
+4. 把高频决策和最小安全示例写进 `SKILL.md`；完整方法表、平台差异、硬件/
+   部署验收写进 `references/`，保持渐进披露。
+5. 更新 `references/capability-map.md`，重新运行审计，直到严格检查通过。
+6. 对每个新增或改动的 Skill 运行 `skill-creator` 的 `quick_validate.py`，
+   再执行 `git diff --check` 和相对链接检查。
+7. 修改已注册的后端内嵌知识时，运行
+   `node microi.skills/scripts/sync-embedded-skills.mjs <skill-name...>`，再带 `--check`
+   回读一致性；它只更新已在 `Microi.AI.csproj` 注册的快照，正文仍来自 canonical Skills。
+   修改渐进内容后先显式刷新本次 Skill 的校验清单，再按名称验证；全库检查发现历史漂移时
+   单独记录，禁止修改无关 Skill 的哈希来掩盖漏项。插件/CLI 使用现有构建器同步分发副本，
+   打包成功不等于已发布到用户安装渠道。
+
+## 中文文档视觉与可读性契约（强制）
+
+文档正确但密密麻麻仍属于未完成。修改 `microi.doc/docs/doc/**/*.md` 或
+`microi.doc/docs/case/**/*.md` 时同时遵守：
+
+- 正文使用清晰的 H1/H2/H3 层级和 80–90 字符左右的阅读宽度；连续长段落拆为短段、列表、对比表、步骤、流程或有语义的卡片。不要为了“丰富”把每句话都做成卡片。
+- 首屏先回答“这是什么、有什么价值、怎么选择”，再展开原理和完整参数；长篇高级细节可使用可访问的 `details/summary` 渐进披露。
+- 三个以上可比较能力优先使用表格或网格卡片；三步以上的依赖流程优先使用流程图/步骤带。图标必须帮助辨识，不能只作装饰噪声。
+- 颜色至少区分主能力、成功、警告、风险，但正文对比度必须满足易读要求；不能只靠颜色表达状态。亮色、暗色、窄屏和 `prefers-reduced-motion` 都要有样式。
+- 真实案例截图进入 `docs/public/images/...`，使用稳定英文文件名、有效 `alt` 和简短图注；图片不得代替关键文字说明，移动端不得横向撑破页面。
+- 整站共同规则优先落在 VitePress 主题层 `mci-site.scss` / `doc-readable.scss`，页面独有展示放独立 SCSS；禁止为几十篇 Markdown 机械复制内联 `<style>`。
+- 新页面可复用 `.mci-doc-grid`、`.mci-doc-card`、`.mci-doc-chip`；产品页需要独立视觉时使用页面 marker + `body:has(...)` 限定作用域，不能污染登录页、首页或英文生成页。
+- 改动后运行 `npm run check:readability` 与 `npm run check:content`，再在真实浏览器至少检查一个桌面宽度和一个移动宽度，覆盖亮/暗主题、代码块、表格、图片、侧栏与锚点。
+- `microi.doc/docs/en/` 由脚本生成，不手工同步样式化内容；日常文档工作继续禁止修改 `about/update-log.md`。
+
+自动可读性检查只能阻止缺少 H1、超长连续文字块或整站主题契约丢失，不能证明页面真正好看。最终仍要查看渲染结果，不能用构建成功替代视觉验收。
+
+全站任务必须进一步执行以下闭环，禁止把“扫描到若干 `/doc` 文件”等同于
+“全部中文阅读页已完善”：
+
+1. 在 `docs/.vitepress/theme/doc-visual-profiles.js` 为每个 `/doc` 与 `/case` 中文阅读页明确选择 `overview`、`guide`、`reference`、`policy` 或 `showcase`。新增、删除、移动文档时，页面清单与视觉档案必须同步闭环；专用站点交互页需显式登记为独立范围，英文路由不得进入该表。
+2. 运行 `npm run audit:visual` 查看逐页报告。强制检查应覆盖唯一 H1、首屏引导、章节密度、连续正文、页面类型对应的表格/列表/代码/图片/提示/自定义布局、图片 `alt` 和主题契约；交付前应达到 0 条阻断和 0 条密度建议。
+3. 中文样式若用 `html:lang(zh) { ... }` 包裹，根暗色选择器必须写成 `&.dark`，使 Sass 编译为 `html:lang(zh).dark`；写 `.dark` 会错误编译为后代选择器并导致暗色覆盖失效。所有自定义浅/暗背景都必须与前景、次要文字、边框成对切换，并用测试验证正文至少达到 WCAG AA 4.5:1。
+4. 在浏览器遍历全部中文阅读路由（包括 `/doc` 与 `/case`），检查页面类型类、唯一 H1、页面级横向溢出和明显低对比文字；再从五种视觉类型各选代表页，覆盖桌面/移动与亮色/暗色截图。专用站点交互页按自身组件测试与代表截图验收。只有已登记范围全部通过，才可描述为“全站视觉验收完成”。
+5. 静态脚本、Sass 编译、单元测试、VitePress 构建和浏览器截图是不同证据层。任何一层因资源保护或环境问题跳过，最终必须明确写出，不能用其它层替代。
+
+## 自动审计能证明什么
+
+脚本验证：
+
+- 中文文档清单与责任映射闭环；
+- 映射中没有已删除文档或不存在的 Skill；
+- 文档出现的标准化 `V8.*` 名称至少在某个 Skill Markdown 中出现；
+- 文档出现的 `System`、`DiyCommon`、`SqlFunc`、`SqlSubQuery`、
+  `V8ExtensionRegistry` 具名 API 至少在某个 Skill 中出现；
+- 文档出现的 `microi_*` MCP 工具名至少在某个 Skill 中出现；
+- 文档出现的平台 HTTP 路由和平台全局函数至少在某个 Skill 中出现；
+- 当前前端组件清单中的全部 `Control` 已进入表单组件参考；
+- `v8-print.js`、`ble/tsc.js`、`ble/esc.js` 的公开蓝牙入口和全部构建器方法，
+  已同时进入中文官方文档、蓝牙 Skills 与前端 Monaco API 提示；
+- `diy.common.js`、`diy-form.vue`、`diy-table.vue` 仍真实调用
+  `initV8Print`，且三处挂载范围已写入官方文档与 Skill；
+- 动态业务路径被单独列出，便于人工复核。
+
+脚本不能证明：
+
+- Skill 的语义、示例、安全约束一定正确；
+- 文档本身没有过时；
+- 浏览器、蓝牙设备、打印机、数据库或多节点部署已经实测。
+
+因此每轮全面同步还要做源码核对和按风险分层的真实验收，不能只追求字符串
+覆盖率。
+
+## 补充内容的归属
+
+- 前端通用 API、扫码、消息、表格/表单助手：`v8-utilities`、
+  `v8-frontend-events`。
+- 蓝牙直连运行、连接与批量语义：
+  `v8-frontend-events/references/bluetooth-print.md`；TSC/ESC 源码方法与编码：
+  `v8-frontend-events/references/bluetooth-print-api.md`；服务端模板打印仍归
+  `print-engine`。
+- 后端通用上下文、Method、Base64、加密：`v8-utilities`。
+- 表单设计器和字段组件：`microi-form-engine`。
+- 菜单、模块与页面入口：`module-engine`。
+- 部署、运行、配置和升级：`microi-deployment`。
+- Dos.ORM 与扩展数据库：`dos-orm`。
+- 微服务/前端微应用：`microi-microservice`。
+- 其它专项能力优先补到已有同名 Engine/V8 Skill，避免再建内容重叠的 Skill。
+
+## 禁止事项
+
+- 不复制整篇官网文档到一个巨型 Skill。
+- 不用叶子方法同名匹配掩盖对象归属错误。
+- 不把 `V8.Form.OrderNo`、`V8.Param.id` 等业务字段当成平台函数。
+- 不为了本次普通补充修改版本更新日志、英文文档或 Skills 版本清单。
+- 不声称静态审计等于真实硬件、浏览器、远端或生产验收。