@microi.net/cli 4.6.2

package/dist/microi.skills/print-engine/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: print-engine
+description: 生成和审查 Microi 打印引擎 Print Engine 模板 JSON。用于创建 mic_print 模板、PageObj 布局、PrintObj 数据绑定、可打印报告、标签或合同。
+---
+
+# Microi 打印引擎（Print Engine）模板 JSON 生成
+
+你正在为 Microi 吾码平台生成打印引擎模板的 JSON 数据。打印模板包含 PageObj（模板定义）和 PrintObj（打印数据）。
+
+## 设计器源码事件
+
+扩展打印设计器源码时，可通过 `EventBus.on('savePrintJson', handler)` 接收
+保存后的模板 JSON，并在组件卸载时调用 `EventBus.off('savePrintJson')`。
+这是设计器内部生命周期接口，不属于运行时打印模板 JSON，也不能替代模板的
+服务端保存与回读。
+
+## 与蓝牙直连打印的边界
+
+本 Skill 负责 `mic_print`、`PageObj`、`PrintObj`、浏览器预览和模板化纸张输出。
+如果需求明确是蓝牙标签机/小票机、TSC/TSPL、ESC/POS 或
+`V8.Print.prepareSend`，应同时读取
+`../v8-frontend-events/references/bluetooth-print.md`：
+
+- Print Engine 决定“页面/模板如何排版”，适合 A4、PDF、浏览器打印和统一模板。
+- `V8.Print` 生成打印机原生命令并通过 BLE 写特征，适合标签和热敏小票。
+- 两者可以由同一个按钮按设备能力选择，但不能把 `PageObj` 直接交给
+  `V8.Print.prepareSend`，也不能把 TSC/ESC 字节当作 Print Engine JSON。
+
+## 数据模型
+
+打印模板存储在 `mic_print` 表中：
+
+| 字段 | 说明 |
+|------|------|
+| PageObj | 页面模板定义（面板 + 元素布局） |
+| PrintObj | 打印数据（运行时填充到模板中） |
+| DataApi | 关联的接口引擎 Id（动态数据） |
+
+## PageObj 模板结构
+
+```json
+{
+  "panels": [{
+    "index": 0,
+    "name": "面板名称",
+    "height": 297,          // mm，A4=297
+    "width": 210,           // mm，A4=210
+    "paperType": "A4",
+    "paperHeader": 49.5,    // 页眉底部位置（pt）
+    "paperFooter": 780,     // 页脚顶部位置（pt）
+    "printElements": []
+  }]
+}
+```
+
+### 常用纸张尺寸
+
+| 纸张 | 宽(mm) | 高(mm) |
+|------|--------|--------|
+| A3 | 297 | 420 |
+| A4 | 210 | 297 |
+| A5 | 148 | 210 |
+| B4 | 257 | 364 |
+| B5 | 182 | 257 |
+
+### 坐标系统
+- 单位：pt（磅，约 0.35mm）
+- 原点：面板左上角 (0, 0)
+- 栅格间距默认 7.5pt
+- A4 可用宽度约 571.5pt
+
+## 元素类型
+
+### text — 文本元素
+
+```json
+{
+  "options": {
+    "left": 60, "top": 30, "height": 13, "width": 120,
+    "title": "静态文本",
+    "field": "fieldName",
+    "testData": "预览数据",
+    "fontSize": 10.5,           // pt，9=小五, 10.5=五号, 12=小四, 14=四号
+    "fontFamily": "微软雅黑",    // SimSun(宋体), SimHei(黑体), KaiTi(楷体)
+    "fontWeight": "600",         // 400=常规, 600=半粗, 700=粗
+    "color": "#333333",
+    "textAlign": "left",         // left/center/right/justify
+    "textContentVerticalAlign": "middle",  // top/middle/bottom
+    "lineHeight": 18,
+    "hideTitle": false,          // field绑定时仅显示值
+    "fixed": false
+  },
+  "printElementType": { "type": "text" }
+}
+```
+
+### table — 表格元素
+
+```json
+{
+  "options": {
+    "left": 30, "top": 150, "height": 56, "width": 511.5,
+    "field": "tableData",
+    "columns": [[
+      { "title": "编号", "field": "id", "width": 80, "align": "center" },
+      { "title": "名称", "field": "name", "width": 150, "align": "left" },
+      { "title": "金额", "field": "amount", "width": 100, "align": "right", "tableSummary": "sum" }
+    ]]
+  },
+  "printElementType": { "type": "table" }
+}
+```
+
+列属性：`title`, `field`, `width`(pt), `align`, `colspan`, `rowspan`, `checked`, `tableSummary`(count/sum/avg)
+
+### image — 图片
+
+```json
+{
+  "options": {
+    "left": 60, "top": 30, "height": 80, "width": 80,
+    "field": "logoUrl",
+    "src": "默认图片URL",
+    "fit": "contain"           // contain/cover/fill/scale
+  },
+  "printElementType": { "type": "image" }
+}
+```
+
+### longText — 长文本（自动分页）
+
+```json
+{
+  "options": {
+    "left": 30, "top": 100, "height": 40, "width": 511.5,
+    "field": "contractContent",
+    "testData": "长文本预览...",
+    "fontSize": 10.5, "lineHeight": 18
+  },
+  "printElementType": { "type": "longText" }
+}
+```
+
+### html — 自定义 HTML
+
+```json
+{
+  "options": {
+    "left": 30, "top": 200, "height": 80, "width": 300,
+    "formatter": "function(t, e, d) { return '<div>' + (d.customField || '') + '</div>'; }"
+  },
+  "printElementType": { "type": "html" }
+}
+```
+
+### 条形码 / 二维码
+
+```json
+// 条形码（text + textType）
+{ "options": { "field": "barcodeNo", "testData": "XS888888888", "textType": "barcode", "hideTitle": true }, "printElementType": { "type": "text" } }
+// 二维码
+{ "options": { "field": "qrcodeUrl", "testData": "https://microi.net", "textType": "qrcode" }, "printElementType": { "type": "text" } }
+// SVG 版本（矢量不失真）
+{ "printElementType": { "type": "barcode" } }
+{ "printElementType": { "type": "qrcode" } }
+```
+
+### 辅助图形
+
+```json
+// 水平线
+{ "options": { "left": 30, "top": 80, "height": 9, "width": 511.5, "borderStyle": "solid", "borderWidth": 0.75 }, "printElementType": { "type": "hline" } }
+// 垂直线
+{ "printElementType": { "type": "vline" } }
+// 矩形
+{ "printElementType": { "type": "rect" } }
+// 椭圆
+{ "printElementType": { "type": "oval" } }
+```
+
+## PrintObj 打印数据
+
+```json
+{
+  "companyName": "吾码科技有限公司",
+  "orderNo": "ORD-2024-001",
+  "items": [
+    { "id": "1", "name": "商品A", "qty": "10", "price": "100", "total": "1000" }
+  ]
+}
+```
+
+**绑定规则：**
+- 简单字段：元素 `field: "companyName"` → `PrintObj.companyName`
+- 表格数据：表格 `field: "items"` → `PrintObj.items`（数组），列 `field: "name"` → `items[i].name`
+- 图片：`field: "logoUrl"` → URL 或 Base64
+- 条形码/二维码：`field` + `textType` 自动渲染
+
+## 表格函数属性
+
+| 属性 | 函数签名 | 说明 |
+|------|----------|------|
+| formatter2 | `function(title, field, row, index, options)` | 单元格渲染 |
+| styler2 | `function(value, row, index, options)` | 单元格样式 |
+| rowStyler | `function(row, index, options)` | 行样式 |
+| footerFormatter | `function(options, rows, data, el)` | 表尾渲染 |
+| tableSummaryFormatter | `function(column, data)` | 合计行渲染 |
+
+## 生成模板最佳实践
+
+1. **坐标计算**：A4 可用宽度约 571.5pt，从 left=30 开始留白
+2. **元素间距**：垂直间距 15-22.5pt
+3. **表格列宽**：所有列宽之和应等于表格 width
+4. **field 命名**：camelCase，与 PrintObj 键名一致
+5. **testData**：每个绑定字段必须提供 testData
+6. **PrintObj 值**：所有字段值应为字符串类型
+
+### 常用布局
+
+- **标题区（top: 15-60）**：居中大字号标题 + hline 分隔 + 右上角二维码/LOGO
+- **信息区（top: 60-120）**：单号、日期、客户信息
+- **数据区（top: 120+）**：表格元素，自动分页
+- **签章区（靠近页脚）**：签名线、日期线、印章图片
+
+## 接口引擎集成
+
+`DataApi` 字段关联接口引擎，返回的 `Data` 对象直接作为 PrintObj 注入模板：
+
+```javascript
+return {
+  Code: 1,
+  Data: {
+    orderNo: "ORD-2024-001",
+    items: [{ seq: "1", name: "商品A", qty: "10", price: "100", total: "1000" }]
+  }
+};
+```

package/dist/microi.skills/production-readonly-audit/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: production-readonly-audit
+description: Microi 正式环境只读业务巡检规范。用于在不改动线上数据的前提下，检查会员、余额、订单、库存卡、奖励、积分、兑换金额、日志和结算正确性等生产业务数据。
+---
+
+# Microi 正式环境只读业务巡检
+
+## 核心边界
+
+- 正式环境已有真实用户、余额、订单、卡券或收益数据时，线上巡检默认是只读任务。
+- 优先使用目标租户 MCP 的读表、查结构、查日志工具；不得调用新增、更新、删除、清库、重算、补发、扣减接口。
+- 如果用户要求“检查是否正常”，先输出异常证据、影响范围、建议修复方式和回读验证方式；没有明确授权前，不修线上业务数据。
+- MCP 不可用时，可使用官方后台登录 token + FormEngine `getTableData` 做只读兜底，但必须在结果中说明“非 MCP，只读 API 兜底”；不得调用 `add/upt/del/run` 维护接口。
+- 任何资金/资产异常即使明显，也只能先报告。获得修复授权后，必须小范围条件更新，并在方案文档留下 SQL/接口说明、执行时间、影响行数和回读结果。
+
+## 商城类固定巡检表
+
+- 会员与团队：`mall_member`
+- 提货卡与挂单：`mall_stock_card`、`mall_stock_card_listing`
+- 抢购/约单/商品订单：`mall_buy_order`、`mall_appointment_order`、`mall_redeem_order`
+- 积分/兑换金/奖励：`mall_point_log`、`mall_redeem_money_log`、`mall_reward_log`
+- 上架服务费：`mall_storage_fee_order`
+- 提货卡扣除/流转：`mall_stock_card_redeem`、`mall_stock_card_history`
+- 规则配置：`mall_system_config`
+
+## 固定检查项
+
+- 提货卡：`CardNo` 必须为 6 位大写字母+数字；金额不得为负；`OwnerId` 必须存在；同一卡只能有一条活跃挂单；状态机必须和挂单/订单一致。
+- 抢购订单：`PendingPay` 必须有关联锁定卡与付款截止时间；`Paid` 必须有支付凭证和付款时间；`Confirmed/Completed` 必须确认卡 OwnerId 已转为 BuyerId，并有对应流转历史。
+- 上架服务费：服务费应等于持有价 × `PlatformServiceRate`；已支付服务费必须有对应负数积分流水。
+- 推荐奖励：`Amount = BaseAmount × Rate / 100`；直推、间推、品牌补贴合计不得超过 `MaxPerformanceCommissionRate`；`Pending` 不得生成积分流水或增加余额；`Settled` 必须有积分流水并真实到账。
+- 商品支付：提货卡专区订单必须生成 `mall_stock_card_redeem` 并扣卡余额；兑换金专区订单必须生成负数 `mall_redeem_money_log` 并扣兑换金。
+- 会员资产：会员页展示的提货卡资产应以当前名下有效提货卡 `HoldPrice/StockValue` 汇总为准；如 `mall_member.StockValue` 是冗余字段，必须与实际资产保持一致。
+
+## 输出要求
+
+- 报告必须区分“硬错误”和“风险警告”。
+- 不输出密码、token、支付凭证图片原文、完整身份证等敏感信息。
+- 报告需包含巡检通道、读取表数量、状态分布、异常数量、核心异常证据、未覆盖范围。

package/dist/microi.skills/report-engine/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: report-engine
+description: Microi 报表引擎设计与验收规范。用于 Rpt_Report 虚拟表格、数据源、报表字段、查询/增删改接口替换、统计聚合、导出、行级权限和界面引擎图表。
+---
+
+# Microi 报表引擎
+
+## 定位
+
+报表引擎以 `Rpt_Report`、报表字段配置和数据源引擎组成虚拟表格。表格展示使用报表引擎；ECharts 图表和仪表盘使用界面引擎。报表字段是虚拟字段，不能假设存在同名物理表列。
+
+## 建模顺序
+
+1. 明确指标口径、时间粒度、维度、权限和导出上限。
+2. 创建只读数据源（SQL/V8/JSON），使用稳定 `DataSourceKey`。
+3. 创建报表并绑定数据源。
+4. 配置字段 `Name/Label/Component`、查询列、排序、格式和表内编辑。
+5. 如需写操作，为查询/新增/修改/删除分别绑定专用接口引擎。
+6. 菜单只暴露用户需要的报表入口，配置数据范围。
+
+## 权限与 SQL
+
+- 报表数据源必须应用当前租户和服务端用户数据范围。菜单权限不会自动保护任意聚合 SQL。
+- 聚合结果也可能泄露敏感信息；小样本、人员薪资、客户金额等需最小分组阈值或字段脱敏。
+- SQL 动态值参数化，维度/排序/指标使用白名单映射，不接收原始 SQL、列名或 `GROUP BY`。
+- 平台保护表不能作为普通用户报表数据源。
+
+## 写入型报表
+
+统计报表通常来自多表。新增、修改、删除必须调用接口引擎，在一个事务中完成校验与写入：
+
+```js
+var result = await V8.ApiEngine.Run('report_adjust_inventory', {
+  RowId: V8.Form.Id,
+  ExpectedVersion: V8.Form.Version,
+  Quantity: Number(V8.Form.Quantity || 0)
+});
+```
+
+接口引擎重新校验角色、记录范围、当前版本和业务状态。前端隐藏按钮、只读字段或报表行数据不能作为授权。
+
+## 性能
+
+- 默认分页，限制最大页数/每页行数/导出行数。
+- 大聚合在数据库建立合适索引或使用预聚合表；不要每次全表扫描。
+- 缓存 Key 包含 `OsClient + ReportId + 权限主体/授权版本 + 查询参数哈希`。
+- 导出走后台任务；生成文件放私有桶并绑定菜单、记录和字段访问上下文。
+
+## MCP 工作流
+
+1. `microi_get_db_schema` 读取 `Rpt_Report`、数据源、字段、菜单和业务表。
+2. `microi_save_data_source` 保存数据源并回读。
+3. 创建/更新报表及字段；复杂写操作先创建接口引擎。
+4. 设置菜单与角色权限。
+5. 用真实普通角色验收列表、筛选、汇总、详情、编辑与导出。
+
+## 图表
+
+界面引擎图表应调用返回稳定 `{Code, Data}` 的统计接口引擎，不在前端下载明细再聚合。统计接口设置时间范围、维度和最大点数，返回空数据时保持稳定结构。
+
+## 验收清单
+
+- [ ] 指标口径、时区和小数精度明确
+- [ ] 当前租户与行级范围在数据库查询中生效
+- [ ] 虚拟字段与物理字段没有混用
+- [ ] 写操作走事务接口引擎并校验并发版本
+- [ ] 分页、聚合、导出均有资源上限
+- [ ] 缓存按租户和权限隔离
+- [ ] 普通角色、无权限角色、跨租户负向测试通过

package/dist/microi.skills/report-engine/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "报表引擎"
+  short_description: "设计遵守菜单与行级权限的报表、聚合接口、写操作与导出验收"
+  default_prompt: "使用 $report-engine 设计并验收当前 Microi 报表。"

package/dist/microi.skills/search-engine/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: search-engine
+description: Microi 搜索引擎索引、同步、查询与安全规范。用于 Elasticsearch 表索引、增量同步、字段映射、SearchAfter 分页、租户与菜单数据范围、重建和多节点验收。
+---
+
+# Microi SearchEngine
+
+## 能力与事实源
+
+搜索引擎提供建索引/全量同步、单文档新增修改删除、字段映射、查询和 `SearchAfter` 深分页。数据库仍是业务事实源，搜索索引是可重建的读模型，不能直接作为权限、余额、库存或审批状态事实。
+
+## 租户隔离
+
+- 索引名必须包含规范化 `OsClient` 和表标识，禁止不同租户共用无过滤索引。
+- V8/HTTP 调用的 `OsClient` 必须由 Token/服务端上下文确定，不能信任 Query/Body。
+- 搜索服务连接、用户名和密码只从服务端 SaaS 配置读取，不进入前端 `SysConfig`、V8 返回或日志。
+
+## 索引流程
+
+1. 读取 `diy_table/diy_field` 确定可搜索字段、类型和分词需求。
+2. 先扩展索引映射，再开始双写/增量同步。
+3. 全量回填使用稳定游标或主键分页，记录 checkpoint。
+4. 对账数据库数量、抽样字段和删除记录。
+5. 切换读流量后保留旧索引回滚窗口。
+
+可用的服务端方法包括 `AsyncIndex`、`AsyncTableDataToIndex`、`AddDocument`、`UpdateDocument`、`DeleteDocument`、`AddField`、`GetSearchResponse`。
+
+## 查询安全
+
+- 用户关键词作为值参数，不允许决定索引名、任意字段、脚本或原始 DSL。
+- 排序字段从白名单映射；限制 `PageSize`、高亮长度和聚合桶数量。
+- 普通用户的菜单 `SqlWhere`/行级范围不会天然出现在 Elasticsearch 查询中。必须将服务端计算出的允许记录范围同步为可过滤字段，或先取得授权 Id 集合再查询；不能搜索后再在前端过滤。
+- 敏感字段不入索引，或使用独立受控索引；日志只记录 trace id、耗时和计数。
+
+## 同步可靠性
+
+数据库写成功、索引写失败时使用 outbox 事件，`EventId` 全局唯一。消费端按事件 Id 幂等；删除使用 tombstone。索引更新失败不能回滚已经提交的业务事务，应告警并重试。
+
+全量重建和增量消费可能在多个节点同时运行，需分布式租约与 checkpoint 条件更新；本机静态标志不能作为“正在重建”的事实。
+
+## 查询示例
+
+```csharp
+var result = await search.GetSearchResponse(new MicroiSearchEngineParam
+{
+    OsClient = osClient,
+    TableName = "Diy_Product",
+    Keyword = keyword,
+    PageSize = Math.Min(pageSize, 100),
+    Sorts = new List<MicroiSearchEngineSortModel>
+    {
+        new MicroiSearchEngineSortModel { Field = "UpdateTime", Order = "desc" }
+    }
+});
+```
+
+字段名与排序必须在进入此对象前经过服务端白名单。
+
+## MCP/交付流程
+
+- 先用 `microi_get_db_schema` 和菜单元数据确认字段与权限。
+- 搜索配置写入后回读实际索引名、字段映射和租户连接。
+- 用管理员、普通有权限用户、无权限用户和另一个租户验收。
+- 覆盖全量重建中断、重复事件、删除、滚动升级、搜索服务短暂故障。
+
+## 验收清单
+
+- [ ] 索引按租户隔离，跨租户搜索为零
+- [ ] 菜单/行级范围在查询前生效
+- [ ] 字段、排序、分页、聚合均有白名单和上限
+- [ ] 数据库与索引可对账、可重建
+- [ ] outbox 重试幂等，无永久漏同步
+- [ ] 密钥和敏感字段不进入前端/日志/索引

package/dist/microi.skills/search-engine/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "搜索引擎"
+  short_description: "配置租户隔离的索引、同步、查询、重建、权限过滤和故障恢复"
+  default_prompt: "使用 $search-engine 设计并验收当前 Microi 搜索能力。"

package/dist/microi.skills/spider-engine/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: spider-engine
+description: Microi 采集引擎规范。用于设计、维护、测试或调用 Microi.Spider、OpenClaw 本地 Worker、Chrome/Playwright 采集、验证码、MCP 建模、V8 入库与导出、可重复采集站点规则。
+---
+
+# Microi 采集引擎
+
+## 核心原则
+
+采集引擎是可重复执行的数据采集系统，不是一次性 AI 代采。完成交付后，用户应能在没有 AI 参与的情况下，使用同一套规则、账号、浏览器 Profile、保存引擎和导出引擎再次采集。
+
+处理采集任务前，必须同时读取并遵守：
+
+- `microi.skills/workspace-conventions/SKILL.md`
+- `microi.skills/microi-system-delivery/SKILL.md`
+- `microi.skills/spider-engine/SKILL.md`
+- 涉及 V8 入库、导出、文件上传、菜单按钮、前端页面或自动化测试时，对应读取 `v8-crud-api`、`v8-file-upload`、`v8-export-import`、`v8-menu-buttons`、`microi-client-frontend`、`playwright-e2e` 等相关 Skill。
+
+不能在最终回复里把仍可执行的用户需求写成“下一步继续采集”。如果任务被验证码、登录、限流或人工确认卡住，应保持 Worker/Chrome 会话可用，明确提示用户完成当前动作，然后继续采集、入库、统计和导出。只有所有用户编号需求已完成并验证，或外部阻塞经过多次尝试且有证据，才允许收尾。
+
+## 通用引擎与业务数据分层
+
+采集引擎必须保持通用，不要把某个业务项目的概念写进通用模块。
+
+- 通用引擎表统一使用 `mci_spider_*`，负责站点、规则、账号、浏览器会话、任务、步骤、产物、通用结果和通用导出记录。
+- 业务采集结果写入业务表，例如内容表、视频表、资料表、商品表等。
+- 每个站点规则通过规则专属 V8 保存引擎，把通用采集结果转换并写入业务表。
+- 每个站点规则通过规则专属 V8 导出引擎，生成该业务需要的 TXT、Word、ZIP、JSON、Excel、视频清单、法条包等格式。
+- 通用表字段、Tab、菜单名不能写死具体行业的主对象、分类或内容字段；这些业务含义应出现在业务表或规则配置中。
+
+## 标准表建议
+
+通用采集层推荐包含下列表：
+
+- `mci_spider_site`：采集站点或小程序元数据，包含入口地址、登录方式、验证码策略、平台类型。
+- `mci_spider_rule`：可重复采集规则，保存 `RecipeJson`、`CredentialSchemaJson`、`RetryPolicyJson`、`ExpectedPlanJson`、`SaveApiEngineKey`、`ExportApiEngineKey`、`ExportConfigJson`、目标业务表等。
+- `mci_spider_account`：具体账号/Profile 数据，保存登录账号、加密或私密密码字段、登录身份姓名、`ProfileKey`、`CredentialJson`、`CaptchaPolicyJson`、最大验证码识别次数、最大密码尝试次数。
+- `mci_spider_profile`：本地浏览器 Profile 或会话状态，由 Worker 写入和更新。
+- `mci_spider_worker`：Worker 心跳、机器标识、浏览器路径、当前任务、运行状态。
+- `mci_spider_task`：可执行任务和进度，必须支持应采集数、成功数、失败数、完成数、剩余数、人工提示。
+- `mci_spider_task_step`：步骤级执行日志，记录每一步输入、输出、耗时、异常和截图/响应引用。
+- `mci_spider_artifact`：采集产物，保存截图、验证码图片、HTML、HAR、API 响应、日志、本地文件或私有附件引用。
+- `mci_spider_result`：通用规范化结果，字段用 `ObjectName`、`CategoryName`、`SubType`、`SummaryText`、`DetailText`、`IsComplete` 等中性命名。
+- `mci_spider_export`：通用导出产物记录，字段用导出标题、导出格式、导出数量、完整数量、缺失数量、私有附件、业务表、业务记录等中性命名。
+
+## 可重复规则必备内容
+
+每条生产采集规则必须保存足够信息，保证后续能重复运行：
+
+- 站点入口地址、登录地址、采集入口地址。
+- 全量账号列表或账号选择策略；不得只取第一个账号或截图里可见账号。
+- 凭据结构和具体凭据存放位置；如果站点还需要姓名、手机号、身份证后几位等派生身份，也必须写入账号资料。
+- 浏览器 Profile 策略，通常按站点 + 账号生成稳定 `ProfileKey`。
+- 采集步骤配方，包括自动步骤、人工确认步骤、验证码步骤、网络响应捕获规则、DOM 选择器、分页/分类遍历规则。
+- 保存引擎 `SaveApiEngineKey`。
+- 导出引擎 `ExportApiEngineKey` 与导出配置。
+- 预期采集计划 `ExpectedPlanJson`，用于统计本应采集多少、已成功多少、失败多少、剩余多少。
+- 重试策略 `RetryPolicyJson`，包含验证码、密码错误、网络失败、接口空返回、重复数据的处理方式。
+
+## 全量账号与分类核验
+
+采集多账号、多分类、多入口站点时，启动采集前必须做“来源资料全量核验”：
+
+1. 从用户给出的 Excel、Markdown、TXT、截图、地址文件和历史资料中提取所有账号、密码、身份信息、登录地址、分类、模块和采集入口。
+2. 生成账号清单和采集计划，并与 `mci_spider_account`、`mci_spider_rule.ExpectedPlanJson`、`mci_spider_task` 回读结果逐项比对。
+3. 如果来源资料里有账号但规则表没有，必须补入规则和账号表后再采集。
+4. 如果某个账号能看到独有分类或模块，必须将该账号的身份和可见范围映射保存下来，不能因为其他账号已采集过相似内容就跳过。
+5. 判断“采集完成”必须以全量账号、全量分类、全量模块和全量内容条目均完成为准，不能用单账号、单模块成功替代整体完成。
+
+结构化内容交付还必须满足：
+
+- 用户要求分类或模块独立交付时，应分别生成对应的 TXT、Word、Excel 或其他格式导出。
+- 项目或来源层级应提供汇总包，便于一次性下载。
+- 业务表里应能直接查看主要内容、属性、来源和导出附件。
+- 业务主表、分类表和内容明细表应按实际数据关系建立关联，并能从主记录访问对应导出。
+- 统计接口应给出应采集、已采集、完整、缺失、失败和剩余数量。
+- 枚举值导出和后台展示不得直接输出无解释的 `1`、`0`、`true`、`false` 等机器值；必须结合字段配置或数据源映射为可读文本。
+- 统计首页不要用 `GetTableData` 分页扫描大表后直接汇总；数据量较大时必须使用 SQL 聚合、专用统计接口或已维护的统计字段，避免 `_PageSize=5000` 之类分页上限导致首页数据错误。
+- 业务主表的备注/说明字段可写入最新采集统计块，包含业务主体、后台项目、分类数、内容条目数、完整数、缺失数、导出产物、待执行、失败/阻塞和未完成原因；旧错误日志可保留在统计块下方用于追溯。
+
+## 批量站点交付
+
+当用户要求一次性交付多个业务主体、多个网站或多套站点规则时，不能由 AI 手工逐站抓取后临时打包。必须让采集引擎承担完整闭环：
+
+- 每个站点至少对应一条 `mci_spider_site` 和一条生产 `mci_spider_rule`；同站点多入口、多账号、多分类时，规则中必须保存完整 `ExpectedPlanJson`。
+- 每个站点的账号、姓名、密码密文字段、入口地址、验证码策略、人工兜底策略、浏览器 ProfileKey 都要写入 `mci_spider_account` 或规则配置，保证后续无 AI 参与也能复跑。
+- 任务执行、失败原因、人工确认、截图、接口响应、导出文件和 ZIP 包都必须由 Worker/V8 写入 `mci_spider_task`、`mci_spider_task_step`、`mci_spider_artifact`、`mci_spider_export`。
+- 交付包必须由规则导出引擎生成并上传为私有附件；业务主表和导出表都应保存 TXT、Word、ZIP 的私有附件路径，后台用户可随时重复下载。
+- 对失败站点不能只写“失败”。必须在任务和最终报告中写明失败阶段、账号/分类/模块范围、错误码或页面证据、是否可人工继续、下次复跑建议。
+- 最终交付报告必须按站点列出：规则是否存在、账号是否完整、应采集数量、成功数量、失败数量、剩余数量、导出附件、失败原因、是否达到可重复采集验收。
+- 交付报告应由接口引擎生成，例如 `<project>-spider-delivery-report`。报告必须按规则级判断，不要因为同一业务对象已由另一条规则交付，就把旧规则也算作已交付；旧入口应标记为“同对象已交付/当前规则未执行”或类似状态。
+- 当来源 Excel 的工作表、后台业务主体行、采集规则行不一一对应时，必须区分“业务主体”和“后台项目/规则”。不同入口、补充资料或重复别名可以是多个可复跑项目，但首页和总报告应按业务主体逻辑合并统计；除非用户明确要求迁移数据，不要物理删除项目行，以免丢失规则、账号、导出附件和错误日志。
+- 对“应该有 N 个业务主体”这类说法，必须回到原始资料和后台项目双向核验：列出原始资料条目数量、按业务主体合并后的数量、后台项目数量、重复或别名原因，再给出交付数和缺口数。
+- 交付类首页应以图表统计为主，显示业务主体交付率、内容完整率、导出产物覆盖、失败/待执行风险和按主体内容量等；不要默认添加本日/本周/本月/本年周期筛选，除非用户明确要求按时间分析。
+- 交付类首页发布前必须做界面回读验收：不得出现 `????` 乱码、`{a}/{b}/{c}/{d}` 图表模板占位符、默认 `More/更多` 入口、用户明确不要的周期按钮；彩色统计卡和图表说明必须使用高对比文字色，不能出现背景色与文字色接近导致不可读。若标准图表组件自动注入周期筛选或默认模板，可改用实时接口驱动的 `html` 组件承载图形化驾驶舱。
+- 采集交付首页的组件选择必须先区分“平台标准能力”和“项目定制区块”：指标卡、进度、状态分布、排行、时间线、描述列表等高频能力应优先使用或补强 Page Engine 标准组件；业务交付结论、特殊失败说明、客户交付口径等强业务组合区块可以用 `html` 组件承载。
+- 采集交付首页的长文本必须可读：失败原因、未完成来源、交付结论、风险说明不得用分号拼成一整行；应使用逐条列表、卡片或带 `white-space:normal`、`overflow-wrap:anywhere` 的块级布局，回读/截图验收时必须确认底部说明不挤压、不横向溢出。
+- 采集交付首页必须明确双口径：业务主体用于交付统计，后台项目/规则/别名用于保留不同入口、补充资料、账号规则、导出附件和错误日志。用户提出最低交付数量时，首页应展示原始资料条目数、主体合并数、后台项目数和口径差异说明，不要把后台项目数当成业务主体数，也不要只写“未交付 N 个”。
+- 业务内容列表通常不应按单一业务主体创建固定 PageTabs，也不要放“导出某主体 TXT/Word”这类固定主体按钮。项目、来源或业务主表的表单详情里才放“导出本项目 TXT+Word”“重导分类附件”等 FormBtns；列表页按钮只适合全局批处理且必须中性命名。
+- 业务主表的数字字段（应采、已采、剩余、失败、完整条目数等）在菜单列表上应配置 `StatisticsFields`，方便后台直接看汇总；统计字段要使用真实 `diy_field.Id`，写入后必须回读 `sys_menu.StatisticsFields` 验收。
+
+## 验证码与登录安全
+
+验证码识别必须保守，优先保护账号和 IP。
+
+- 同一个账号同一次登录，AI/OCR 自动识别最多允许 2 次失败或未确认。
+- 第 2 次仍失败、为空、置信度低或用户未确认时，必须弹出或聚焦真实 Chrome，让用户手动输入验证码。
+- AI/OCR 返回识别值后，界面应允许用户确认或修正；未经确认的低置信度结果不能继续无限尝试。
+- 密码错误默认只尝试 1 次。若凭据来自可信资料但登录失败，应停止该账号任务并记录失败原因，不要反复重试。
+- 登录后拿到的真实姓名、昵称、学号、租户身份等派生信息必须回写到 `mci_spider_account`，例如 `LoginIdentityName` 或 `CredentialJson`。
+- 评估新的验证码识别方案时，必须先准备带人工标注的样本集，对当前 AI 模型、开源 OCR、图像预处理方案分别统计准确率、空返回率、误读率和平均耗时。没有样本和数据证明更好，不要盲目替换生产方案。
+- 需要对比的候选方案可包括视觉大模型、`Tesseract + OpenCvSharp`、`Sdcb.PaddleOCR`、`DdddOCR` 本地服务或自训练 ONNX 模型。任何方案都必须先在目标站点真实样本上评测，达到站点规则要求后才能进入生产。
+- 生产规则推荐采用可插拔验证码策略，例如 `MiniMaxVision -> Manual`、`TesseractOpenCv -> Manual`、`DdddOcrLocalService -> Manual`。无论使用哪种自动识别，人工兜底规则都不能删除。
+- 后端统一验证码识别入口推荐为 `POST /api/Captcha/Recognize`，参数包含 `OsClient`、`Provider`、`ImageBase64`、`ExpressionText`、`AllowedChars`、`Endpoint`、`TimeoutSeconds`。`Auto` 先解析算术表达式，再调用配置的 HTTP OCR 服务，失败返回 `NeedManual=true`。
+- 生产配置可使用 `CaptchaOcr:Provider`、`CaptchaOcr:Endpoint`、`CaptchaOcr:<Provider>:Endpoint`、`CaptchaOcr:TimeoutSeconds` 指向 DdddOCR、PaddleOCR、Tesseract 或自训练模型服务；后端主进程不要直接加载重型 OCR 模型。
+
+## OpenClaw 本地 Worker
+
+需要 Windows/macOS 桌面能力、真实 Chrome 登录态、人工验证码或本地打包时，优先使用 OpenClaw 作为本地 Worker 外壳。
+
+OpenClaw Worker 应做到：
+
+- 连接用户配置的 Microi `ApiBase` 和 `OsClient`。
+- 登录 Microi 后调用后端 V8/API 引擎，不把复杂业务全部写死在本地前端。
+- 默认使用随包 Chrome 或用户配置 Chrome，不默认改用 Edge。
+- 按站点 + 账号使用持久化浏览器 Profile。
+- 将浏览器会话写入 `mci_spider_profile`。
+- 将截图、验证码图片、网络响应、HTML、日志和本地文件写入 `mci_spider_artifact`。
+- 通过通用任务上报引擎持续写入任务进度、步骤日志、成功失败数量和人工提示。
+- 遇到验证码、登录、限流或站点变化时，不隐藏问题；必须让用户知道当前卡在哪一步。
+
+## 服务端 V8.Spider 运行边界
+
+- SSRF 严格模式与 `V8.Http` 使用同一配置，默认关闭以兼容存量内网采集；开启后必须校验初始 URL、重定向和浏览器子资源。
+- V8 调用禁止传 `ExecutablePath`、`UserDataDir`，平台按 `OsClient + ApiEngineKey/EventName + SessionId/ProfileKey` 隔离浏览器目录。
+- 默认当前节点最多 32 个会话、每租户/引擎作用域最多 4 个；空闲 30 分钟或总生命周期 8 小时回收。
+- 抓包响应体默认最多 200,000 字符、硬上限 1,000,000，每会话保留最近 100 条。
+- 会话额度统一在 SaaS 引擎主租户配置 `SpiderMaxSessionsTotal`、`SpiderMaxSessionsPerScope`、`SpiderSessionIdleMinutes`、`SpiderSessionMaxHours`；不要为普通采集运行参数增加 API/Worker 环境变量。
+- 浏览器会话和会话数配额当前是节点内状态。多节点复用登录态必须使用粘性路由或独立 Spider Worker；任务状态、幂等键、checkpoint 和结果必须写共享数据库/MQ。
+- SSRF 默认兼容不等于任意用户都可提交 URL。采集目标仍应由受控规则/白名单决定，普通用户不能创建任意采集脚本。
+
+## MCP 建模流程
+
+通过 MCP 创建或修复采集引擎时：
+
+1. 先调用状态和 schema 工具，确认当前 API Server、`OsClient`、已有表、字段、菜单和角色权限。
+2. 写入前确认用户请求的租户与 MCP 绑定租户一致，避免写错库。
+3. 通用采集表使用 `mci_` 前缀，业务结果表使用业务前缀。
+4. 菜单默认规划两级：业务域或系统域父菜单 + 具体模块。
+5. 如果用户或项目明确把采集作为主产品，或已明确创建分组菜单，则保留三级结构，例如 `系统引擎 / 采集引擎 / 采集规则`。不得因为“两级推荐”而删除、扁平化用户故意创建的三级菜单。
+6. 添加字段前回读 `diy_field`，避免重复字段和组件不一致。
+7. 选项字段必须配置数据源。
+8. 写入后回读表、字段、菜单、权限、规则和关键业务数据，并刷新必要缓存。
+
+## V8 引擎分工
+
+建议保留通用引擎与规则专属引擎：
+
+- `mci-spider-task-next`：领取下一条可执行任务。
+- `mci-spider-task-report`：上报任务状态、步骤、产物、通用结果和计数。
+- `mci-spider-worker-heartbeat`：OpenClaw/本地 Worker 心跳。
+- 规则专属保存引擎：将某站点数据写入对应业务表。
+- 规则专属导出引擎：根据该业务规则生成 TXT、Word、ZIP、JSON、Excel 等产物并上传私有附件。
+
+通用上报引擎必须保持中性；业务字段映射、去重、清洗、导出格式放在规则专属引擎中。
+
+## 临时文件与交付产物
+
+采集任务常需要临时脚本、网络响应、截图和调试文件，必须遵守：
+
+- 一次性脚本、响应缓存、调试 JSON、临时 JS、截图、运行日志统一写到工作区根目录 `.tmp/` 下。
+- 严禁在根目录生成 `.tmp-xxx.js`、`.tmp-xxx.json`、`.tmp-xxx.txt` 这类散落文件。
+- 客户交付文件才能放入项目交付目录，例如 `<项目目录>/采集结果/`。
+- 临时文件不作为最终证据，最终证据应是后台数据、私有附件、导出文件、统计接口和可复跑规则。
+
+## 最终报告清单
+
+完成采集引擎任务时，必须按用户编号逐条汇报：
+
+- 完成了哪些功能、规则、数据、导出和页面。
+- 修改了哪些表、字段、菜单、接口引擎、按钮、前端文件、Skill、文档。
+- 创建或清理了哪些数据，哪些是真实有效数据，哪些是脏数据已作废。
+- 当前采集进度：应采集、已成功、失败、完整、缺失、剩余。
+- 验证码是否仍需要人工兜底，触发条件是什么。
+- 运行过哪些构建、接口、MCP 回读、导出、下载或页面测试。
+- 每个用户编号需求的状态：完成、部分完成、阻塞，并写明证据。
+
+最终回复前必须重新审计用户的编号清单。凡是还能继续执行的采集、入库、导出、上传、清理、回读、测试，不允许留到“下一步”。