@microi.net/cli 5.8.5 → 5.8.6

package/skills/email-engine/SKILL.md

@@ -1,81 +1,81 @@
----
-name: email-engine
-description: 开发、安装和使用吾码邮箱系统 mci-email。用于 QQ、163、126、企业或自定义 IMAP/SMTP 邮箱账号维护、自动与手动同步、邮件阅读、草稿、附件、回复转发、发送结果核对，以及邮箱 MCP 工具和 V8.Email 协议原子。
----
-
-# 吾码邮箱系统
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-邮箱系统是使用吾码 UI 的独立 Vue 3 微服务，商城 AppKey 为 `mci-email`，
-后台入口为「系统引擎 → 邮箱系统」，菜单路由 `/mci-email`。
-
-先读取 `../workspace-conventions/SKILL.md`；开发或发布时还需读取
-`../microi-microservice/SKILL.md`、`../app-store/SKILL.md`。
-先调用 `microi_list_applications`，再读取目标应用完整上下文，禁止覆盖未读取的源码。
-
-## 选择正确入口
-
-| 需求 | 入口 |
-| --- | --- |
-| 邮箱工作台 | 源码微服务 `mci-email` |
-| 账号配置 | 原表 `mic_email_server`，通过宿主 `openForm` 打开吾码表单 |
-| 全部业务 HTTP | 接口引擎 `mci-email`，请求参数 `Action` |
-| 手动同步 | `Action: Sync` 返回持久后台任务，使用 `SyncStatus` 回读终态 |
-| 自动同步 | 定时任务调用 `mci-email-auto-sync`，内部调度 `mci-email-sync-step` |
-| 协议、MIME、加密 | 最小后端原子 `V8.Email`，不新增业务 Controller |
-| 租户扩展 | `mci-email-hook`，商城策略 `CreateIfMissing` |
-| AI 操作 | `microi_email_query`、`microi_email_manage`、`microi_email_send` |
-
-当前版本沿用原邮箱配置表的平台管理员权限（`Level >= 9999`），
-并按当前用户检查账号和邮件所有权。不得因 AI 使用而绕过这些约束。
-各运行节点需要包含 `V8.Email` 的平台版本；仅安装前端源码不能补齐 .NET 协议能力。
-
-## 配置和同步
-
-1. 确认用户拥有或获准使用邮箱；在服务商处开启 IMAP/SMTP，取得客户端授权码。
-2. 打开账号表单，选择 QQ / 163 / 126 / 腾讯企业邮箱 / 自定义，填写地址与授权码。
-3. QQ、163 常用 IMAP 993 / SMTP 465，选择 `SslOnConnect`；
-   使用 SMTP 587 时选择 `StartTls`。具体端口以服务商配置为准。
-4. 授权码提交后由可信后端加密。编辑留空保留旧值；列表、导出、源码、日志和截图不含原文。
-5. 先检测连接，再手动同步。首次先显示最新一批邮件，再增量补齐历史并核对状态。
-6. 自动同步由平台定时任务运行，不依赖浏览器开着；每个账号设置同步间隔。
-
-目录路径作为服务商的不透明值保存，不能自行翻译或改写。
-去重键必须包含账号、目录、UIDVALIDITY 和 UID；UIDVALIDITY 改变时只重建该目录缓存。
-同步锁使用接口引擎分布式锁，检查点进入数据库；进程重启后继续执行。
-每批状态核对和近期摘要刷新都要先比较缓存，只更新实际变化的字段；未变化的 100 封邮件不能逐封重写。查询仅投影需要比较的标记/摘要字段，不加载正文或附件。跳过无变化写入仍须推进 UID 游标，保留远端删除、软删除恢复和已发送副本关联，并用同步回归测试验证。
-邮件正文按需读取，默认阻止脚本、表单提交与外部图片；不能直接在宿主使用 `v-html`。
-
-## MCP 使用
-
-先通过 `microi_codex action=profiles` 选择用户指定租户，再按工具 Schema 调用。
-
-```json
-{"action":"Overview"}
-```
-
-以上参数用于 `microi_email_query`，不会回传授权码。
-查询邮件用 `action: Messages`，可传 `accountId`、`folderKind`、`keyword`、
-`pageIndex` 和 `pageSize`；只在任务需要时读取正文或附件。
-
-维护工具先返回操作预览。用户已有明确授权后，`confirmExecution` 精确填写
-`Action:目标Id`；新账号为 `SaveAccount:new`，新草稿为 `SaveDraft:账号Id`。
-同步需要稳定的 `requestId`，恢复同一请求不得生成新值。
-
-发信先通过 `microi_email_manage(action: SaveDraft)` 保存确定的收件人、正文与附件，
-然后调用 `microi_email_send(draftId, confirmExecution: draftId)`。
-只有用户已授权发送给这些收件人时才执行；不要把读取邮件的请求当作发送授权。
-
-## 发送和结果边界
-
-- 一次发送意图绑定稳定草稿 Id 和 Message-Id；同一草稿重复请求不能再次 SMTP 投递。
-- `Sent` 表示 SMTP 服务器已接受；收件端可见需要实际收件验证。
-- `Unknown` 表示连接中断等情况导致结果不确定，保留在发件箱，禁止自动重发。
-  先按 Message-Id 检查服务商已发送目录；确需新发时由用户确认新的发送意图。
-- 远端已发送副本单独保存；副本或租户 Hook 失败不得回滚已发生的 SMTP 副作用。
-- 原子只解密当前租户的凭据，不能向 V8 暴露解密方法；必须校验 TLS 证书。
-
-协议方法和参数见 [V8.Email 原子参考](references/v8-email.md)。
-最终分别验证源码/构建、API 权限、连接、实际收件、附件字节、重复发送、
-自动同步、宿主表单、商城包与官网真实截图。
+---
+name: email-engine
+description: 开发、安装和使用吾码邮箱系统 mci-email。用于 QQ、163、126、企业或自定义 IMAP/SMTP 邮箱账号维护、自动与手动同步、邮件阅读、草稿、附件、回复转发、发送结果核对，以及邮箱 MCP 工具和 V8.Email 协议原子。
+---
+
+# 吾码邮箱系统
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+邮箱系统是使用吾码 UI 的独立 Vue 3 微服务，商城 AppKey 为 `mci-email`，
+后台入口为「系统引擎 → 邮箱系统」，菜单路由 `/mci-email`。
+
+先读取 `../workspace-conventions/SKILL.md`；开发或发布时还需读取
+`../microi-microservice/SKILL.md`、`../app-store/SKILL.md`。
+先调用 `microi_list_applications`，再读取目标应用完整上下文，禁止覆盖未读取的源码。
+
+## 选择正确入口
+
+| 需求 | 入口 |
+| --- | --- |
+| 邮箱工作台 | 源码微服务 `mci-email` |
+| 账号配置 | 原表 `mic_email_server`，通过宿主 `openForm` 打开吾码表单 |
+| 全部业务 HTTP | 接口引擎 `mci-email`，请求参数 `Action` |
+| 手动同步 | `Action: Sync` 返回持久后台任务，使用 `SyncStatus` 回读终态 |
+| 自动同步 | 定时任务调用 `mci-email-auto-sync`，内部调度 `mci-email-sync-step` |
+| 协议、MIME、加密 | 最小后端原子 `V8.Email`，不新增业务 Controller |
+| 租户扩展 | `mci-email-hook`，商城策略 `CreateIfMissing` |
+| AI 操作 | `microi_email_query`、`microi_email_manage`、`microi_email_send` |
+
+当前版本沿用原邮箱配置表的平台管理员权限（`Level >= 9999`），
+并按当前用户检查账号和邮件所有权。不得因 AI 使用而绕过这些约束。
+各运行节点需要包含 `V8.Email` 的平台版本；仅安装前端源码不能补齐 .NET 协议能力。
+
+## 配置和同步
+
+1. 确认用户拥有或获准使用邮箱；在服务商处开启 IMAP/SMTP，取得客户端授权码。
+2. 打开账号表单，选择 QQ / 163 / 126 / 腾讯企业邮箱 / 自定义，填写地址与授权码。
+3. QQ、163 常用 IMAP 993 / SMTP 465，选择 `SslOnConnect`；
+   使用 SMTP 587 时选择 `StartTls`。具体端口以服务商配置为准。
+4. 授权码提交后由可信后端加密。编辑留空保留旧值；列表、导出、源码、日志和截图不含原文。
+5. 先检测连接，再手动同步。首次先显示最新一批邮件，再增量补齐历史并核对状态。
+6. 自动同步由平台定时任务运行，不依赖浏览器开着；每个账号设置同步间隔。
+
+目录路径作为服务商的不透明值保存，不能自行翻译或改写。
+去重键必须包含账号、目录、UIDVALIDITY 和 UID；UIDVALIDITY 改变时只重建该目录缓存。
+同步锁使用接口引擎分布式锁，检查点进入数据库；进程重启后继续执行。
+每批状态核对和近期摘要刷新都要先比较缓存，只更新实际变化的字段；未变化的 100 封邮件不能逐封重写。查询仅投影需要比较的标记/摘要字段，不加载正文或附件。跳过无变化写入仍须推进 UID 游标，保留远端删除、软删除恢复和已发送副本关联，并用同步回归测试验证。
+邮件正文按需读取，默认阻止脚本、表单提交与外部图片；不能直接在宿主使用 `v-html`。
+
+## MCP 使用
+
+先通过 `microi_codex action=profiles` 选择用户指定租户，再按工具 Schema 调用。
+
+```json
+{"action":"Overview"}
+```
+
+以上参数用于 `microi_email_query`，不会回传授权码。
+查询邮件用 `action: Messages`，可传 `accountId`、`folderKind`、`keyword`、
+`pageIndex` 和 `pageSize`；只在任务需要时读取正文或附件。
+
+维护工具先返回操作预览。用户已有明确授权后，`confirmExecution` 精确填写
+`Action:目标Id`；新账号为 `SaveAccount:new`，新草稿为 `SaveDraft:账号Id`。
+同步需要稳定的 `requestId`，恢复同一请求不得生成新值。
+
+发信先通过 `microi_email_manage(action: SaveDraft)` 保存确定的收件人、正文与附件，
+然后调用 `microi_email_send(draftId, confirmExecution: draftId)`。
+只有用户已授权发送给这些收件人时才执行；不要把读取邮件的请求当作发送授权。
+
+## 发送和结果边界
+
+- 一次发送意图绑定稳定草稿 Id 和 Message-Id；同一草稿重复请求不能再次 SMTP 投递。
+- `Sent` 表示 SMTP 服务器已接受；收件端可见需要实际收件验证。
+- `Unknown` 表示连接中断等情况导致结果不确定，保留在发件箱，禁止自动重发。
+  先按 Message-Id 检查服务商已发送目录；确需新发时由用户确认新的发送意图。
+- 远端已发送副本单独保存；副本或租户 Hook 失败不得回滚已发生的 SMTP 副作用。
+- 原子只解密当前租户的凭据，不能向 V8 暴露解密方法；必须校验 TLS 证书。
+
+协议方法和参数见 [V8.Email 原子参考](references/v8-email.md)。
+最终分别验证源码/构建、API 权限、连接、实际收件、附件字节、重复发送、
+自动同步、宿主表单、商城包与官网真实截图。

package/skills/email-engine/references/v8-email.md

@@ -1,34 +1,34 @@
-# V8.Email 协议原子
-
-业务编排使用接口引擎，下面的方法只供可信后端调用。
-连接对象字段为 `Host`、`Port`、`Security`、`UserName`、`Credential`、`Timeout`。
-`Credential` 必须是 `V8.Email.ProtectCredential` 产生的当前租户密文。
-`Security` 仅允许 `SslOnConnect`、`StartTls`。超时默认 40 秒，最高 60 秒。
-
-| 方法 | 输入补充 | 返回 Data |
-| --- | --- | --- |
-| `V8.Email.ProtectCredential(value)` | 原文授权码 | 直接返回带版本前缀的租户密文字符串 |
-| `V8.Email.TestConnection(p)` | `Protocol: IMAP / SMTP` | `Connected, Protocol, Secure` |
-| `V8.Email.ListFolders(p)` | 无 | 最多 200 个 `Path, Name, Kind, Total, Unread` |
-| `V8.Email.Fetch(p)` | `Folder, AfterUid, UidValidity, Limit, Recent` | `NextUid, HasMore, Reset, UidValidity, Messages` |
-| `V8.Email.Inspect(p)` | `Folder, UidValidity, Uids`（最多 100） | `UidValidity, Messages`，含存在的 UID 和已读/星标/删除标志 |
-| `V8.Email.GetMessage(p)` | `Folder, UidValidity, Uid` | 信封、`TextBody, HtmlBody, Attachments` |
-| `V8.Email.GetAttachment(p)` | 上述字段及 `AttachmentIndex`（从 0 开始） | `FileName, ContentType, FileByteBase64` |
-| `V8.Email.SetFlags(p)` | `Folder, UidValidity, Uid, IsRead, IsStarred` | 结果状态 |
-| `V8.Email.Move(p)` | `Folder, UidValidity, Uid, DestinationFolder` | 移动结果；不得对整个目录执行无差别清空 |
-| `V8.Email.Send(p)` | SMTP 连接及下述 MIME 字段 | `DeliveryState, MessageId`，外层 `Code` 表示协议结果 |
-| `V8.Email.StoreSent(p)` | IMAP 连接及相同 MIME 字段 | 按 Message-Id 查重并保存已发送副本 |
-
-`Fetch.Recent=true` 读取末尾最多 `Limit` 封邮件，但保留历史 `AfterUid` 游标。
-常规 Fetch 按 UID 窗口分页，`Limit` 最高 100；即使窗口为空也推进游标。
-返回的 `Reset` 必须与 `UidValidity` 一起持久化，不能把旧代邮件指向新代同号 UID。
-
-MIME 字段：`To, Cc, Bcc, Subject, TextBody, HtmlBody, InReplyTo, MessageId, Attachments`。
-附件对象：`FileName, ContentType, FileByteBase64`，最多 10 个，总大小不超过 10MB；
-读取单封原始邮件上限 25MB，正文上限 2MB。超限应明确报错，不能静默丢内容。
-
-`Send` 的结果：`Accepted`、`Rejected` 或 `Unknown`。
-在业务层保存草稿及去重标记后才能调用；不要对 `Unknown` 自动重试 SMTP。
-`StoreSent` 与真正发信分开，不可将保存副本当作已经投递。
-
-相关源码：`Microi.Server/Microi.V8Engine/Extend/Email/V8Email.cs`。
+# V8.Email 协议原子
+
+业务编排使用接口引擎，下面的方法只供可信后端调用。
+连接对象字段为 `Host`、`Port`、`Security`、`UserName`、`Credential`、`Timeout`。
+`Credential` 必须是 `V8.Email.ProtectCredential` 产生的当前租户密文。
+`Security` 仅允许 `SslOnConnect`、`StartTls`。超时默认 40 秒，最高 60 秒。
+
+| 方法 | 输入补充 | 返回 Data |
+| --- | --- | --- |
+| `V8.Email.ProtectCredential(value)` | 原文授权码 | 直接返回带版本前缀的租户密文字符串 |
+| `V8.Email.TestConnection(p)` | `Protocol: IMAP / SMTP` | `Connected, Protocol, Secure` |
+| `V8.Email.ListFolders(p)` | 无 | 最多 200 个 `Path, Name, Kind, Total, Unread` |
+| `V8.Email.Fetch(p)` | `Folder, AfterUid, UidValidity, Limit, Recent` | `NextUid, HasMore, Reset, UidValidity, Messages` |
+| `V8.Email.Inspect(p)` | `Folder, UidValidity, Uids`（最多 100） | `UidValidity, Messages`，含存在的 UID 和已读/星标/删除标志 |
+| `V8.Email.GetMessage(p)` | `Folder, UidValidity, Uid` | 信封、`TextBody, HtmlBody, Attachments` |
+| `V8.Email.GetAttachment(p)` | 上述字段及 `AttachmentIndex`（从 0 开始） | `FileName, ContentType, FileByteBase64` |
+| `V8.Email.SetFlags(p)` | `Folder, UidValidity, Uid, IsRead, IsStarred` | 结果状态 |
+| `V8.Email.Move(p)` | `Folder, UidValidity, Uid, DestinationFolder` | 移动结果；不得对整个目录执行无差别清空 |
+| `V8.Email.Send(p)` | SMTP 连接及下述 MIME 字段 | `DeliveryState, MessageId`，外层 `Code` 表示协议结果 |
+| `V8.Email.StoreSent(p)` | IMAP 连接及相同 MIME 字段 | 按 Message-Id 查重并保存已发送副本 |
+
+`Fetch.Recent=true` 读取末尾最多 `Limit` 封邮件，但保留历史 `AfterUid` 游标。
+常规 Fetch 按 UID 窗口分页，`Limit` 最高 100；即使窗口为空也推进游标。
+返回的 `Reset` 必须与 `UidValidity` 一起持久化，不能把旧代邮件指向新代同号 UID。
+
+MIME 字段：`To, Cc, Bcc, Subject, TextBody, HtmlBody, InReplyTo, MessageId, Attachments`。
+附件对象：`FileName, ContentType, FileByteBase64`，最多 10 个，总大小不超过 10MB；
+读取单封原始邮件上限 25MB，正文上限 2MB。超限应明确报错，不能静默丢内容。
+
+`Send` 的结果：`Accepted`、`Rejected` 或 `Unknown`。
+在业务层保存草稿及去重标记后才能调用；不要对 `Unknown` 自动重试 SMTP。
+`StoreSent` 与真正发信分开，不可将保存副本当作已经投递。
+
+相关源码：`Microi.Server/Microi.V8Engine/Extend/Email/V8Email.cs`。

package/skills/job-engine/SKILL.md

@@ -1,176 +1,176 @@
----
-name: job-engine
-description: Microi 定时任务与可靠后台任务规范。用于配置 Microi.Job、Quartz 和接口引擎任务，设计多节点租约、幂等、重试、停机排空、恢复、进度与验收。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi Job 定时与后台任务
-
-## 何时使用
-
-- 周期扫描、补偿、归档：`Microi.Job`
-- 用户触发的长耗时安装/导入/同步：菜单后台任务
-- 可靠跨服务异步：MQ + outbox/inbox
-- 请求内等待外部结果：`await`，不要创建后台线程
-
-禁止用后端 `setTimeout`、`Task.Run`、`static bool` 或本机定时器承载可靠业务。
-
-## 持续模拟不使用秒级任务冒充
-
-需要50ms规则步长的持续模拟应使用已安装的通用受信后台宿主，规则留应用包、业务事务留接口引擎。`NextDelaySeconds:1` 或每秒Quartz任务只能扫描租约、恢复检查点与补偿；HasMore分片不等于20Hz实时tick。后台恢复必须拥有服务端可信作用域并重读主库，不可伪造成员DiyToken或复用已过期pump scope。无法证明实际后台连续推进时，只能报告请求触发/秒级补偿，不得声称已经提供持续权威模拟。
-
-## 平台对象
-
-Quartz 管理能力包含查询、添加、更新、暂停、恢复、删除任务。V8 中的 `V8.Method.ManageScheduleJob` 用于能力发现、任务查询和受控管理，必须绑定当前租户的管理员身份。任务配置、接口引擎代码和执行日志属于控制面，只允许 `Level >= 9999` 维护；业务用户只能触发明确授权的后台动作。
-
-任务通常调用稳定的 `ApiEngineKey`。接口引擎返回 `Code=1` 只表示本次执行成功，不代表调度系统可忽略重试与幂等。
-
-## 多节点设计
-
-### 执行日志与只读诊断
-
-- 新执行/失败/跳过记录使用 `ScheduleExecutionLog`，直接等待 MongoDB 确认写入 `sys_log_<tenant>/log_yyyyMM`；固定 `TargetType=ScheduledJob`、`TargetId=JobName`，`EventId` 幂等。MongoDB 确认失败才写当前租户的 `diy_schedule_job_log`，两者均失败不得改变业务结果。`AddSysLog` 仅代表异步入队，不能用作本能力的持久化确认。
-- 表单使用字段级 Tabs，分别放置“运行日志”和“历史日志”只读表格；仅显示的页签发起查询。历史 `diy_schedule_job_log` 保留，不自动删除、搬迁或清空。
-- `platform-schedule-job` 的 `logs/historylogs` 要求任务名、月份，每页最多 100 条，按时间+Id 游标多取一条判断 `HasMore`，不计算多年数据总数。Mongo 索引为 `(TargetType,TargetId,CreateTime,EventId)`；历史表索引 `(JobName,CreateTime,Id)` 通过声明式应用包交付并现场回读。
-- 用 `microi_query_job_runtime` 或 `microi_run_engine` 的 `Action=diagnostics` 核验启动、待机、实际执行数、领取进展、设置读取失败、触发器与心跳。一个租户的设置读取超时只能关闭该租户，不能拖住其它租户；每租户最多一个在途读，不能按轮询叠加请求。
-- `logs` 优先读 MongoDB，MongoDB 查询失败时自动读关系库；成功的空集合不回退。`historylogs` 固定读关系库。两个库都不可用必须显示查询失败，不能伪装为空日志。镜像更新不等于 Mongo 升级；后台系统日志队列的 spool 仍应在持久卷并验收恢复重放。
-
-### 运行时间刷新与配置版本分离
-
-- Quartz 周期同步 `LastTime/NextTime` 是运行状态投影，不能调用通用 `UptFormData` 生成配置版本或数据日志；用户保存名称、Cron、代码等配置仍走原表单事件和版本链路。
-- 只读取 Id、任务名和两个时间列；时间未变化时不写入。变化时由可信调度内核向同一租户主库执行固定两列参数化 CAS，匹配原时间、任务名、正常状态与未删除条件；并发/陈旧结果命中 0 行时不重放。
-- 编辑 Cron 重建触发器后，Quartz 的 PreviousFireTime 可能为空；同步时不得因此清空数据库已有的 `LastTime`，新的 `NextTime` 仍应更新。验收需覆盖“已执行任务改到当天已过时间，下一次排到次日”的场景，并分别核对新旧执行日志。
-- 历史版本保留不自动删除。持续高 CPU 时核对 `mic_data_version` 实际物理索引，不以应用包已声明索引推断旧库已安装；用 MCP 回读 `(TableId,TableRowId,CreateTime)`，并比较 MySQL digest 两次采样的执行数、扫描行数与耗时差值。
-- 此修复要求更新调度后端；既有 `platform-schedule-job`、任务元数据及 MCP 查询/保存协议保持兼容。验收覆盖两租户同名任务、两连接竞争、未变化、暂停/软删除/重命名后陈旧写入、主库选择和配置字段不变。
-
-### 新旧平台共库过渡：停用新版调度
-
-- 系统设置“开发配置”的 `DisableTaskScheduling`（停用任务调度）默认 `0`，缺字段、空值也按正常调度处理；只有已实现此能力的新版后端识别它。字段由“系统设置”应用和 SaaS 空库基础包交付，不写租户配置值，不逐条 Pause/修改任务状态。
-- 开启时在 Quartz 领取触发器、处理 Misfire 之前按租户过滤；领取后、真正触发前重新读取系统设置缓存。禁止仅在 `IJob.Execute`、Listener veto 或业务 V8 入口 return：共享 Quartz 可能已经推进 NextFireTime，造成旧版漏执行。
-- 集群故障恢复也不得清理停用租户的在途记录或创建其补偿触发器。Quartz 以故障节点为单位清理记录，所以同一故障节点混有被停用租户时，新版推迟该故障节点整组恢复，交给旧节点或关闭开关后处理；其它健康节点仍正常领取。
-- 正常保存系统设置在事务提交后失效缓存，下一次调度检查生效，不用重启；不是强制中断，已经开始的任务允许完成。缓存/配置读取失败拒绝该租户的新领取，不影响其它健康租户；Redis/失效通知异常时不能承诺硬实时。
-- 停用期间只读观察周期计划，不推进共享触发器；每个“租户 + Job + Trigger + 计划时间”持久化确定性事件，包含 `Status=Skipped`、`Executed=false`、`Reason=SystemTaskSchedulingDisabled` 和中文说明。Redis 原子预留与日志确定性主键共同防止多新版节点重复记录；日志说明仅代表新版未执行，旧版仍可能正常执行。不补跑业务、不补写进程停机历史；新增/修改计划的日志目录最多约 10 秒更新。
-- 普通接口调用、MQ 消费、升级/应用安装等持久后台任务不属于此开关的范围。手动触发 Quartz 任务仍经过门禁。
-- 交付顺序：先安装字段并打开开关，再让新版节点参与调度；确认旧版所有调度进程已停止且在途任务完成后，关闭开关交接。不同业务库分别设置，不能用一个租户的值控制全部租户。
-- 验收至少覆盖：默认兼容、开关实时读取、租户隔离、共享库旧节点继续领取、领取后开关变化不推进触发器、Misfire 不误推进、多节点日志去重；不得在真实生产任务上制造副作用做测试。
-
-每个任务必须同时具备：
-
-1. 分布式租约：Key 至少含 `OsClient + JobKey + 计划时间/业务分片`，有唯一持有者、TTL、续租和仅持有者释放。
-2. 业务幂等：稳定 `IdempotencyKey/EventId`、数据库唯一约束或条件状态迁移。
-3. 可恢复状态：待处理、处理中、成功、失败、下次重试时间写共享数据库/Redis/MQ。
-4. fencing：锁可能过期的资金、库存等任务使用版本号/条件更新拒绝旧持有者写入。
-
-锁只能减少并发，不能替代幂等。
-
-## 任务骨架
-
-```js
-// 接口引擎由 Job 调用；JobRunId/FireTime 由调度层传入
-var idempotencyKey = String(V8.Param.JobRunId || '');
-if (!idempotencyKey) return { Code: 0, Msg: '缺少 JobRunId' };
-
-// 推荐调用专用后端能力，以唯一约束抢占执行记录
-var claim = V8.FormEngine.AddFormData('job_execution', {
-  JobKey: 'daily_order_summary',
-  IdempotencyKey: idempotencyKey,
-  Status: 'Running'
-});
-if (claim.Code !== 1) return { Code: 1, Msg: '已执行或正在执行' };
-
-// 分页处理；每个业务副作用仍需自己的幂等键
-return { Code: 1, Data: { IdempotencyKey: idempotencyKey } };
-```
-
-实际项目优先由数据库唯一索引和接口引擎事务完成抢占，不能仅用“先查再新增”。该唯一索引必须声明在 Manifest `tables[].indexes`，并用 `microi_create_table_index` 创建、`microi_get_table_indexes` 回读；禁止在 Job/V8 内手写 `CREATE INDEX`。任务扫描还应按实际 SQL 建立 `(OsClient, Status, NextRetryTime)` 或 `(OsClient, JobKey, ScheduleTime)` 等组合索引。
-
-## 失败、重试与停机
-
-- 先证明任务真的在执行：读 `Scheduler.IsStarted`、`Scheduler.NumberOfJobsExecuted` 和 `Acquisition.LastAcquisitionError`，参考 `microi.doc/docs/doc/system-engine/job.md` 的“任务不执行”。`diy_schedule_job.Status=正常`、`diy_schedule_job.NextTime` 和“插件启动成功”都不能证明触发成功；列表/详情页的 `LastTime/NextTime` 来自运行时，直接查表看到的是库内快照。
-- 领取错误含 `Key 'IDX_microi_job_T_NFT_ST' doesn't exist` 时，是 Quartz 3.19 MySQL 方言依赖 `USE INDEX (IDX_{tablePrefix}T_NFT_ST)` 与 `IDX_{tablePrefix}T_NFT_ST_MISFIRE`，而触发器表缺少这两个索引（常见于历史租户库仍是旧 `QRTZ_` 前缀索引名）。平台调度器初始化会按前缀幂等补齐；人工抢修可直接执行文档中的两条 `CREATE INDEX`，索引名大小写不敏感，补完后无需重建任务或 Cron。
-- 失败记录错误分类、重试次数和 `NextRetryTime`，采用有上限退避；永久错误进入人工处理。
-- 外部调用设置超时；无法确认对方是否成功时用业务幂等号查询，不盲目重发。
-- 服务停机先停止接单，再在有限宽限期排空或持久化；重启扫描未完成任务。
-- 若要求 `kill -9` 前也零丢失，业务成功响应前必须获得共享 outbox/MQ/WAL 持久化确认。
-
-## 后台按钮
-
-满足任一条件即按后台任务设计：预计超过 2 分钟、500 条以上、1000 个以上扇出子操作、100 次以上外部调用、总量未知且可能持续运行，或安装/初始化/批量导入/批量生成/全量同步/迁移/备份。预计超过 10 分钟时，仅设置 `RunBackground=true` 仍不够，必须按 checkpoint 分片，每片独立事务。
-
-菜单按钮设置 `RunBackground/BackgroundTask/IsBackgroundTask=true` 和 `ApiEngineKey`，并配置 `BackgroundTaskOptions`：
-
-- `IdempotencyKey` 或 `IdempotencyKeyFields`：跨节点、重试和重复点击保持稳定。
-- `ConcurrencyKey`：DDL、安装等不能并行的工作使用同一租约组。
-- `BusinessTable + BusinessId`：关联业务记录。
-- `BusinessStatusField + BusinessTaskIdField`：业务记录至少标记“后台处理中”和任务 Id；推荐再配置 `BusinessProgressField + BusinessEtaField`。
-
-按钮提交成功后，平台前端会通过当前用户的 `V8.FormEngine` 权限把业务记录标记为“后台处理中”并写入任务 Id；后台服务不能直接相信客户端字段名而绕过表单权限。接口引擎仍必须在最后一片或异常补偿中把该业务记录改成“已完成 / 失败 / 已取消”，并保留任务 Id 供详情追溯：
-
-```js
-var task = V8.Param._BackgroundTask || {};
-if (task.BusinessTable && task.BusinessId) {
-  var patch = { Id: task.BusinessId };
-  patch[task.BusinessStatusField] = '后台处理中';
-  patch[task.BusinessTaskIdField] = task.Id;
-  V8.FormEngine.UptFormData(task.BusinessTable, patch);
-}
-```
-
-不得让通用后台服务按客户端传入的任意表名/字段名直接写库；需要脱离前端自动标记的专用任务，应在受控接口引擎中使用固定表名和固定字段名。
-
-接口通过 `V8.Method.UpdateBackgroundTask({Current,Total,Msg,Log})` 上报已提交的真实工作量，`Log`/`AppendLog` 用于追加任务详情（不得包含密码、Token 或密钥）。平台按实际吞吐计算 `EstimatedEndTime`；总量未知时不传 `Total`，通知中心显示“不定进度/估算中”，禁止用固定 10%、阶段占位或计时器伪造进度。失败和取消停在最后真实进度，不得显示 100%。
-
-分片接口在仍有后续工作时返回：
-
-```js
-return {
-  Code: 1,
-  Data: {
-    BackgroundTask: {
-      HasMore: true,
-      Checkpoint: { LastId: lastId },
-      Current: committedCount,
-      Total: totalCount,
-      NextDelaySeconds: 1,
-      Msg: '本批已提交，等待下一批'
-    }
-  }
-};
-```
-
-最后一片返回普通 `Code:1`。每个业务副作用还要用 `_BackgroundTaskIdempotencyKey + 业务行Id` 建唯一约束；`_BackgroundTaskFencingToken` 用于拒绝租约过期旧执行者的写入。
-
-## 长任务的 Jint 预算
-
-后台 Worker 最终仍调用接口引擎，因此每个执行片段都受 `Timeout`、`MaxStatements`、单层累计分配预算、根调用树累计分配预算、JavaScript 递归和接口嵌套深度限制。`LimitMemory=2048` 表示当前片段累计分配了多少托管字节，不表示实时占用或预留 2GB 物理内存。
-
-- 总任务运行 10 分钟、30 分钟或数小时是允许的；单个连续 Jint 调用不应承担全部时长。
-- 每片在预算内提交事务并返回 `HasMore + Checkpoint`；Worker 重新入队后会创建新的 Jint Engine，新片重新获得超时、语句和累计分配预算。
-- `V8.ApiEngine.Run` 的多层编排可以保留。新版父子单层分配隔离后，子接口不会被所有祖先重复计费，但根调用树仍有整体预算；循环调用由独立的嵌套深度上限终止。
-- 捕获失败时读取 `DataAppend.V8Limit.Code`。内存/调用树/语句/超时分别缩小批次，递归错误修复函数递归，嵌套深度错误检查循环编排；不要统一归因于服务器资源不足。
-- 可记录 `V8.Limits` 到脱敏诊断日志，但不要在每条业务数据上重复输出。
-- 接口引擎和表后端事件分别使用正向 `sys_apiengine.V8Limit`、`diy_table.V8Limit`；二者默认 `0`，不设置 Jint 单片预算，只有明确需要限制单片时才设为 `1` 并配置超时、语句、分配和递归值。后台任务仍优先 `HasMore + Checkpoint`，因为不限 Jint 预算不等于数据库长事务、进程常驻内存、取消、并发或节点故障风险消失。
-
-## MCP 工作流
-
-1. 读取表、接口引擎和现有任务。
-2. 先设计幂等键、状态机、租约和补偿。
-3. `microi_save_job` 保存任务，写入需明确确认。
-4. 回读任务 cron、启用状态、Key、接口引擎。
-5. 两节点同时触发、重复投递、持有者中止、Redis 故障和滚动升级验收。
-
-## 验收清单
-
-- [ ] 任务配置仅管理员可改
-- [ ] 两节点同一时刻触发，业务副作用仅一次
-- [ ] 重复消息/请求不会重复扣减或生成流水
-- [ ] 锁持有者退出后可恢复，无永久死锁
-- [ ] 失败可重试、可追踪、可人工补偿
-- [ ] 新旧版本滚动共存，状态和消息合约兼容
-- [ ] 未知总量不显示假百分比；已知总量由 Current/Total 唯一推导
-- [ ] ETA 来自真实吞吐，样本不足时明确显示“估算中”
-- [ ] 业务记录可通过 BackgroundTaskId 跳转通知中心排查
-- [ ] 超过 10 分钟的任务有 checkpoint，重启后从最后已提交批次恢复
-- [ ] 单片低于超时/语句/累计分配预算，任务总时长不依赖放大单次接口上限
-- [ ] 嵌套接口没有循环调用，且错误日志包含结构化 `V8Limit` 分类和调用路径
+---
+name: job-engine
+description: Microi 定时任务与可靠后台任务规范。用于配置 Microi.Job、Quartz 和接口引擎任务，设计多节点租约、幂等、重试、停机排空、恢复、进度与验收。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi Job 定时与后台任务
+
+## 何时使用
+
+- 周期扫描、补偿、归档：`Microi.Job`
+- 用户触发的长耗时安装/导入/同步：菜单后台任务
+- 可靠跨服务异步：MQ + outbox/inbox
+- 请求内等待外部结果：`await`，不要创建后台线程
+
+禁止用后端 `setTimeout`、`Task.Run`、`static bool` 或本机定时器承载可靠业务。
+
+## 持续模拟不使用秒级任务冒充
+
+需要50ms规则步长的持续模拟应使用已安装的通用受信后台宿主，规则留应用包、业务事务留接口引擎。`NextDelaySeconds:1` 或每秒Quartz任务只能扫描租约、恢复检查点与补偿；HasMore分片不等于20Hz实时tick。后台恢复必须拥有服务端可信作用域并重读主库，不可伪造成员DiyToken或复用已过期pump scope。无法证明实际后台连续推进时，只能报告请求触发/秒级补偿，不得声称已经提供持续权威模拟。
+
+## 平台对象
+
+Quartz 管理能力包含查询、添加、更新、暂停、恢复、删除任务。V8 中的 `V8.Method.ManageScheduleJob` 用于能力发现、任务查询和受控管理，必须绑定当前租户的管理员身份。任务配置、接口引擎代码和执行日志属于控制面，只允许 `Level >= 9999` 维护；业务用户只能触发明确授权的后台动作。
+
+任务通常调用稳定的 `ApiEngineKey`。接口引擎返回 `Code=1` 只表示本次执行成功，不代表调度系统可忽略重试与幂等。
+
+## 多节点设计
+
+### 执行日志与只读诊断
+
+- 新执行/失败/跳过记录使用 `ScheduleExecutionLog`，直接等待 MongoDB 确认写入 `sys_log_<tenant>/log_yyyyMM`；固定 `TargetType=ScheduledJob`、`TargetId=JobName`，`EventId` 幂等。MongoDB 确认失败才写当前租户的 `diy_schedule_job_log`，两者均失败不得改变业务结果。`AddSysLog` 仅代表异步入队，不能用作本能力的持久化确认。
+- 表单使用字段级 Tabs，分别放置“运行日志”和“历史日志”只读表格；仅显示的页签发起查询。历史 `diy_schedule_job_log` 保留，不自动删除、搬迁或清空。
+- `platform-schedule-job` 的 `logs/historylogs` 要求任务名、月份，每页最多 100 条，按时间+Id 游标多取一条判断 `HasMore`，不计算多年数据总数。Mongo 索引为 `(TargetType,TargetId,CreateTime,EventId)`；历史表索引 `(JobName,CreateTime,Id)` 通过声明式应用包交付并现场回读。
+- 用 `microi_query_job_runtime` 或 `microi_run_engine` 的 `Action=diagnostics` 核验启动、待机、实际执行数、领取进展、设置读取失败、触发器与心跳。一个租户的设置读取超时只能关闭该租户，不能拖住其它租户；每租户最多一个在途读，不能按轮询叠加请求。
+- `logs` 优先读 MongoDB，MongoDB 查询失败时自动读关系库；成功的空集合不回退。`historylogs` 固定读关系库。两个库都不可用必须显示查询失败，不能伪装为空日志。镜像更新不等于 Mongo 升级；后台系统日志队列的 spool 仍应在持久卷并验收恢复重放。
+
+### 运行时间刷新与配置版本分离
+
+- Quartz 周期同步 `LastTime/NextTime` 是运行状态投影，不能调用通用 `UptFormData` 生成配置版本或数据日志；用户保存名称、Cron、代码等配置仍走原表单事件和版本链路。
+- 只读取 Id、任务名和两个时间列；时间未变化时不写入。变化时由可信调度内核向同一租户主库执行固定两列参数化 CAS，匹配原时间、任务名、正常状态与未删除条件；并发/陈旧结果命中 0 行时不重放。
+- 编辑 Cron 重建触发器后，Quartz 的 PreviousFireTime 可能为空；同步时不得因此清空数据库已有的 `LastTime`，新的 `NextTime` 仍应更新。验收需覆盖“已执行任务改到当天已过时间，下一次排到次日”的场景，并分别核对新旧执行日志。
+- 历史版本保留不自动删除。持续高 CPU 时核对 `mic_data_version` 实际物理索引，不以应用包已声明索引推断旧库已安装；用 MCP 回读 `(TableId,TableRowId,CreateTime)`，并比较 MySQL digest 两次采样的执行数、扫描行数与耗时差值。
+- 此修复要求更新调度后端；既有 `platform-schedule-job`、任务元数据及 MCP 查询/保存协议保持兼容。验收覆盖两租户同名任务、两连接竞争、未变化、暂停/软删除/重命名后陈旧写入、主库选择和配置字段不变。
+
+### 新旧平台共库过渡：停用新版调度
+
+- 系统设置“开发配置”的 `DisableTaskScheduling`（停用任务调度）默认 `0`，缺字段、空值也按正常调度处理；只有已实现此能力的新版后端识别它。字段由“系统设置”应用和 SaaS 空库基础包交付，不写租户配置值，不逐条 Pause/修改任务状态。
+- 开启时在 Quartz 领取触发器、处理 Misfire 之前按租户过滤；领取后、真正触发前重新读取系统设置缓存。禁止仅在 `IJob.Execute`、Listener veto 或业务 V8 入口 return：共享 Quartz 可能已经推进 NextFireTime，造成旧版漏执行。
+- 集群故障恢复也不得清理停用租户的在途记录或创建其补偿触发器。Quartz 以故障节点为单位清理记录，所以同一故障节点混有被停用租户时，新版推迟该故障节点整组恢复，交给旧节点或关闭开关后处理；其它健康节点仍正常领取。
+- 正常保存系统设置在事务提交后失效缓存，下一次调度检查生效，不用重启；不是强制中断，已经开始的任务允许完成。缓存/配置读取失败拒绝该租户的新领取，不影响其它健康租户；Redis/失效通知异常时不能承诺硬实时。
+- 停用期间只读观察周期计划，不推进共享触发器；每个“租户 + Job + Trigger + 计划时间”持久化确定性事件，包含 `Status=Skipped`、`Executed=false`、`Reason=SystemTaskSchedulingDisabled` 和中文说明。Redis 原子预留与日志确定性主键共同防止多新版节点重复记录；日志说明仅代表新版未执行，旧版仍可能正常执行。不补跑业务、不补写进程停机历史；新增/修改计划的日志目录最多约 10 秒更新。
+- 普通接口调用、MQ 消费、升级/应用安装等持久后台任务不属于此开关的范围。手动触发 Quartz 任务仍经过门禁。
+- 交付顺序：先安装字段并打开开关，再让新版节点参与调度；确认旧版所有调度进程已停止且在途任务完成后，关闭开关交接。不同业务库分别设置，不能用一个租户的值控制全部租户。
+- 验收至少覆盖：默认兼容、开关实时读取、租户隔离、共享库旧节点继续领取、领取后开关变化不推进触发器、Misfire 不误推进、多节点日志去重；不得在真实生产任务上制造副作用做测试。
+
+每个任务必须同时具备：
+
+1. 分布式租约：Key 至少含 `OsClient + JobKey + 计划时间/业务分片`，有唯一持有者、TTL、续租和仅持有者释放。
+2. 业务幂等：稳定 `IdempotencyKey/EventId`、数据库唯一约束或条件状态迁移。
+3. 可恢复状态：待处理、处理中、成功、失败、下次重试时间写共享数据库/Redis/MQ。
+4. fencing：锁可能过期的资金、库存等任务使用版本号/条件更新拒绝旧持有者写入。
+
+锁只能减少并发，不能替代幂等。
+
+## 任务骨架
+
+```js
+// 接口引擎由 Job 调用；JobRunId/FireTime 由调度层传入
+var idempotencyKey = String(V8.Param.JobRunId || '');
+if (!idempotencyKey) return { Code: 0, Msg: '缺少 JobRunId' };
+
+// 推荐调用专用后端能力，以唯一约束抢占执行记录
+var claim = V8.FormEngine.AddFormData('job_execution', {
+  JobKey: 'daily_order_summary',
+  IdempotencyKey: idempotencyKey,
+  Status: 'Running'
+});
+if (claim.Code !== 1) return { Code: 1, Msg: '已执行或正在执行' };
+
+// 分页处理；每个业务副作用仍需自己的幂等键
+return { Code: 1, Data: { IdempotencyKey: idempotencyKey } };
+```
+
+实际项目优先由数据库唯一索引和接口引擎事务完成抢占，不能仅用“先查再新增”。该唯一索引必须声明在 Manifest `tables[].indexes`，并用 `microi_create_table_index` 创建、`microi_get_table_indexes` 回读；禁止在 Job/V8 内手写 `CREATE INDEX`。任务扫描还应按实际 SQL 建立 `(OsClient, Status, NextRetryTime)` 或 `(OsClient, JobKey, ScheduleTime)` 等组合索引。
+
+## 失败、重试与停机
+
+- 先证明任务真的在执行：读 `Scheduler.IsStarted`、`Scheduler.NumberOfJobsExecuted` 和 `Acquisition.LastAcquisitionError`，参考 `microi.doc/docs/doc/system-engine/job.md` 的“任务不执行”。`diy_schedule_job.Status=正常`、`diy_schedule_job.NextTime` 和“插件启动成功”都不能证明触发成功；列表/详情页的 `LastTime/NextTime` 来自运行时，直接查表看到的是库内快照。
+- 领取错误含 `Key 'IDX_microi_job_T_NFT_ST' doesn't exist` 时，是 Quartz 3.19 MySQL 方言依赖 `USE INDEX (IDX_{tablePrefix}T_NFT_ST)` 与 `IDX_{tablePrefix}T_NFT_ST_MISFIRE`，而触发器表缺少这两个索引（常见于历史租户库仍是旧 `QRTZ_` 前缀索引名）。平台调度器初始化会按前缀幂等补齐；人工抢修可直接执行文档中的两条 `CREATE INDEX`，索引名大小写不敏感，补完后无需重建任务或 Cron。
+- 失败记录错误分类、重试次数和 `NextRetryTime`，采用有上限退避；永久错误进入人工处理。
+- 外部调用设置超时；无法确认对方是否成功时用业务幂等号查询，不盲目重发。
+- 服务停机先停止接单，再在有限宽限期排空或持久化；重启扫描未完成任务。
+- 若要求 `kill -9` 前也零丢失，业务成功响应前必须获得共享 outbox/MQ/WAL 持久化确认。
+
+## 后台按钮
+
+满足任一条件即按后台任务设计：预计超过 2 分钟、500 条以上、1000 个以上扇出子操作、100 次以上外部调用、总量未知且可能持续运行，或安装/初始化/批量导入/批量生成/全量同步/迁移/备份。预计超过 10 分钟时，仅设置 `RunBackground=true` 仍不够，必须按 checkpoint 分片，每片独立事务。
+
+菜单按钮设置 `RunBackground/BackgroundTask/IsBackgroundTask=true` 和 `ApiEngineKey`，并配置 `BackgroundTaskOptions`：
+
+- `IdempotencyKey` 或 `IdempotencyKeyFields`：跨节点、重试和重复点击保持稳定。
+- `ConcurrencyKey`：DDL、安装等不能并行的工作使用同一租约组。
+- `BusinessTable + BusinessId`：关联业务记录。
+- `BusinessStatusField + BusinessTaskIdField`：业务记录至少标记“后台处理中”和任务 Id；推荐再配置 `BusinessProgressField + BusinessEtaField`。
+
+按钮提交成功后，平台前端会通过当前用户的 `V8.FormEngine` 权限把业务记录标记为“后台处理中”并写入任务 Id；后台服务不能直接相信客户端字段名而绕过表单权限。接口引擎仍必须在最后一片或异常补偿中把该业务记录改成“已完成 / 失败 / 已取消”，并保留任务 Id 供详情追溯：
+
+```js
+var task = V8.Param._BackgroundTask || {};
+if (task.BusinessTable && task.BusinessId) {
+  var patch = { Id: task.BusinessId };
+  patch[task.BusinessStatusField] = '后台处理中';
+  patch[task.BusinessTaskIdField] = task.Id;
+  V8.FormEngine.UptFormData(task.BusinessTable, patch);
+}
+```
+
+不得让通用后台服务按客户端传入的任意表名/字段名直接写库；需要脱离前端自动标记的专用任务，应在受控接口引擎中使用固定表名和固定字段名。
+
+接口通过 `V8.Method.UpdateBackgroundTask({Current,Total,Msg,Log})` 上报已提交的真实工作量，`Log`/`AppendLog` 用于追加任务详情（不得包含密码、Token 或密钥）。平台按实际吞吐计算 `EstimatedEndTime`；总量未知时不传 `Total`，通知中心显示“不定进度/估算中”，禁止用固定 10%、阶段占位或计时器伪造进度。失败和取消停在最后真实进度，不得显示 100%。
+
+分片接口在仍有后续工作时返回：
+
+```js
+return {
+  Code: 1,
+  Data: {
+    BackgroundTask: {
+      HasMore: true,
+      Checkpoint: { LastId: lastId },
+      Current: committedCount,
+      Total: totalCount,
+      NextDelaySeconds: 1,
+      Msg: '本批已提交，等待下一批'
+    }
+  }
+};
+```
+
+最后一片返回普通 `Code:1`。每个业务副作用还要用 `_BackgroundTaskIdempotencyKey + 业务行Id` 建唯一约束；`_BackgroundTaskFencingToken` 用于拒绝租约过期旧执行者的写入。
+
+## 长任务的 Jint 预算
+
+后台 Worker 最终仍调用接口引擎，因此每个执行片段都受 `Timeout`、`MaxStatements`、单层累计分配预算、根调用树累计分配预算、JavaScript 递归和接口嵌套深度限制。`LimitMemory=2048` 表示当前片段累计分配了多少托管字节，不表示实时占用或预留 2GB 物理内存。
+
+- 总任务运行 10 分钟、30 分钟或数小时是允许的；单个连续 Jint 调用不应承担全部时长。
+- 每片在预算内提交事务并返回 `HasMore + Checkpoint`；Worker 重新入队后会创建新的 Jint Engine，新片重新获得超时、语句和累计分配预算。
+- `V8.ApiEngine.Run` 的多层编排可以保留。新版父子单层分配隔离后，子接口不会被所有祖先重复计费，但根调用树仍有整体预算；循环调用由独立的嵌套深度上限终止。
+- 捕获失败时读取 `DataAppend.V8Limit.Code`。内存/调用树/语句/超时分别缩小批次，递归错误修复函数递归，嵌套深度错误检查循环编排；不要统一归因于服务器资源不足。
+- 可记录 `V8.Limits` 到脱敏诊断日志，但不要在每条业务数据上重复输出。
+- 接口引擎和表后端事件分别使用正向 `sys_apiengine.V8Limit`、`diy_table.V8Limit`；二者默认 `0`，不设置 Jint 单片预算，只有明确需要限制单片时才设为 `1` 并配置超时、语句、分配和递归值。后台任务仍优先 `HasMore + Checkpoint`，因为不限 Jint 预算不等于数据库长事务、进程常驻内存、取消、并发或节点故障风险消失。
+
+## MCP 工作流
+
+1. 读取表、接口引擎和现有任务。
+2. 先设计幂等键、状态机、租约和补偿。
+3. `microi_save_job` 保存任务，写入需明确确认。
+4. 回读任务 cron、启用状态、Key、接口引擎。
+5. 两节点同时触发、重复投递、持有者中止、Redis 故障和滚动升级验收。
+
+## 验收清单
+
+- [ ] 任务配置仅管理员可改
+- [ ] 两节点同一时刻触发，业务副作用仅一次
+- [ ] 重复消息/请求不会重复扣减或生成流水
+- [ ] 锁持有者退出后可恢复，无永久死锁
+- [ ] 失败可重试、可追踪、可人工补偿
+- [ ] 新旧版本滚动共存，状态和消息合约兼容
+- [ ] 未知总量不显示假百分比；已知总量由 Current/Total 唯一推导
+- [ ] ETA 来自真实吞吐，样本不足时明确显示“估算中”
+- [ ] 业务记录可通过 BackgroundTaskId 跳转通知中心排查
+- [ ] 超过 10 分钟的任务有 checkpoint，重启后从最后已提交批次恢复
+- [ ] 单片低于超时/语句/累计分配预算，任务总时长不依赖放大单次接口上限
+- [ ] 嵌套接口没有循环调用，且错误日志包含结构化 `V8Limit` 分类和调用路径

package/skills/job-engine/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "任务引擎"
-  short_description: "设计可幂等、可恢复并适用于多节点滚动部署的定时与后台任务"
-  default_prompt: "使用 $job-engine 设计并验收当前 Microi 定时或后台任务。"
+interface:
+  display_name: "任务引擎"
+  short_description: "设计可幂等、可恢复并适用于多节点滚动部署的定时与后台任务"
+  default_prompt: "使用 $job-engine 设计并验收当前 Microi 定时或后台任务。"