---
name: spider-engine
description: Microi 采集引擎规范。用于设计、维护、测试或调用 Microi.Spider、OpenClaw 本地 Worker、Chrome/Playwright 采集、验证码、MCP 建模、V8 入库与导出、可重复采集站点规则。
---

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

# 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 回读、导出、下载或页面测试。
- 每个用户编号需求的状态：完成、部分完成、阻塞，并写明证据。

最终回复前必须重新审计用户的编号清单。凡是还能继续执行的采集、入库、导出、上传、清理、回读、测试，不允许留到“下一步”。