[CodFrm]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

N/A — 无关联 issue。测试与真实验证见下方「验证」；尚未经过人工审查。

背景

sctl 无法触发后台/定时脚本运行，也读不到脚本的运行日志：这两类脚本跑在 offscreen/sandbox 里，不是网页，sctl 也不能 attach 扩展页面。所以 AI 代理写完这类脚本后没法自己验证（见 #1824 的 scriptcat-userscript Skill）。sctl 侧新增了 sctl run / sctl logs 和 MCP scripts_run / scripts_logs（配对 PR：scriptscat/sctl#17）。本 PR 让脚本猫的外部接入 bridge 应答对应的两个新 JSON-RPC 方法。

Spec（在 sctl 仓库）：docs/specs/2026-11-04-script-run-logs.md。

本次改动

• scripts.run：复用脚本列表/编辑器“运行”的同一通路（RuntimeService.runScript，execOnce），只允许后台和定时脚本（启用与否不影响）。
  • 默认等到本次运行结束，返回 complete / error / running（超时，默认 60 秒，上限 240 秒）和本次产生的日志。
  • wait:false 时立即返回。
• scripts.logs：按 uuid 读取 LoggerDAO 日志，支持 since（默认 1 小时）、severity、text、limit（默认 100，上限 1000）。
  • 按时间从早到晚返回，超出 limit 时保留最新的并标 truncated；按帧大小上限截断。
  • 排除外部接入审计记录：审计记录也带 uuid，而且每次 logs 调用都会新增一条。
• 两个方法都不经审批，由维护者决定（理由见 spec 决策 1，sctl threat-model.md 已记录残余风险），并照常写入外部接入审计（不含日志正文）。
• external_access/generated/ 由 sctl make protocol-sync-scriptcat 生成。schemaVersion 保持 1.0.0：握手要求版本完全相等，升版本会让旧版连不上。

实现考虑

• scriptRunStatus 没有运行 id。重跑时会先发旧一次运行的 COMPLETE，再发新一次的 RUNNING。所以必须先看到本轮的 RUNNING，才认后面的终态。
• 同一脚本的多次外部运行串行触发：等上一次外部运行开始、结束、超时或被释放之后，才触发下一次，避免互相误认状态。
• 错误文本截断到 16K 字符（UTF-16 码元），并计入帧大小预算。否则超大的 reject 消息会让应答超过 4 MiB 帧上限，daemon 会断开连接。

已知限制

• 外部运行和编辑器“运行”或 cron 触发交叠时，仍可能把对方的状态当成自己的。根治需要 sandbox 发出运行 id，代码中已标注。
• 沙盒的 “exec script complete” 日志可能晚于终态写入，因此 run 返回的本次日志里可能缺这一行。
• 生产构建的日志级别是 info，所以 GM_log(..., "debug") 不会入库，run/logs 看不到它。这是原有行为，本 PR 没有改。

建议审查重点

• external_access/run_logs.ts 中等待本轮 RUNNING → 终态的状态机，以及每条退出路径上的订阅和定时器释放。
• 不经审批这一取舍是否接受（权限面与 sctl 已有的页面自动化、debug console 同级）。

关联

• 配对 PR：✨ 新增 sctl run / sctl logs：触发后台/定时脚本运行并读取脚本运行日志 sctl#17。sctl CI 的 SCRIPTCAT_REF 指向本分支的 373a117c（生成文件在 1570587c 中未变）。合并顺序：先合本 PR，再合 sctl PR。
• 后续：📝 新增 scriptcat-userscript Skill：指导 AI 编码代理编写页面/后台/定时脚本，并通过 sctl 安装与验证 #1824 的 Skill 改用 sctl run / sctl logs。

验证

base 6c0459b8…head bdc914d1。改动只在 src/app/service/service_worker/external_access/（含 generated/）和 service_worker/index.ts，共 7 个文件。

• pnpm exec vitest run --no-coverage src/app/service/service_worker/external_access src/app/service/service_worker/index.test.ts：9 个文件、187 个用例通过。新增用例先红后绿；另做过变异检查：分别去掉 RUNNING 守卫、审计排除、排序、错误转字符串，相应用例都会失败。
• pnpm exec tsc --noEmit、改动文件的 eslint 和 prettier：通过。
• 全量 vitest 以 CI 为准：本地全量在 origin/main 6c0459b8 上就不稳定地大面积失败（跨文件 mock 泄漏、超时），失败文件单独跑都能通过，CI 上同一提交是绿的。
• 真实验证：本分支构建的扩展在无头 Chromium 中加载，配对一个从 sctl 分支构建、隔离在 127.0.0.1:18643 的 daemon，覆盖 spec 的 18 项要求，全部通过：
  • complete、error、超时 running、--no-wait；
  • 定时脚本和禁用的脚本能运行；页面脚本返回 INVALID_REQUEST，未知 uuid 返回 NOT_FOUND；
  • 各过滤条件和上下限；审计记录被排除，且审计行里没有日志正文；
  • MCP 与 CLI 一致，没有审批进度消息；
  • Ctrl-C 和断开都是 exit 2，且已触发的运行不被撤回；
  • 用 6c0459b8 构建的旧版收到 METHOD_NOT_FOUND 和升级提示，已有命令照常可用。

审查修复（2026-11-05）

又做了一轮独立审查，确认的问题都已修复，先写失败用例再改：

• 4f7ccc1b sandbox：脚本被重跑或停用后，旧运行晚到的结束状态不再覆盖当前运行的状态，也不再给它安排重试。这个问题原本就存在，脚本列表上的运行状态同样受影响；scripts.run 依赖这个状态，所以在这里一并修复。
• 3b0038f5：
  • @run-in 与当前环境不符时，立即返回 INVALID_REQUEST，不触发运行，判断逻辑与 sandbox 共用 sandbox/utils.ts。
  • 截止时间从收到请求起算，覆盖排队和等待两段；wait:false 不再排队。
  • $/cancelRequest 或断开连接时，放弃还在排队的运行。
  • 日志字段遇到 BigInt 或循环引用也能编码，不会让整次查询失败。
  • LoggerDAO.walkNewestFirst 从最新往回读，够数就停，不再整表读取。
• spec 已同步修订（sctl 729a663）。

验证（head bdc914d1）：

• 相关测试 216/216 通过，tsc 与 eslint 均为 exit 0；每项都做了变异检查。

• 真实浏览器复测，三项都通过：

  • run-in 不符时立即报错；
  • BigInt 结果写进日志后，run / logs 正常；
  • 先用 --no-wait 启动运行 A，1 秒后启动运行 B；A 等待的本地延迟请求返回后，B 得到的仍是自己的结束结果，A 晚到的结束只记进日志。

• bdc914d1 ♻️ 新增 sandbox/utils.ts：run_in.ts 并入其中；runtime.execScript 里内联的 once 周期门控提成纯函数 isOnceRunDone，行为不变。补了 utils.test.ts（once 门控以前没有测试），做过变异检查。相关测试 225/225 通过，tsc 和 eslint 均为 exit 0。