# 生成脚本验证流程

本文规定 AI 生成 `.user.js` 后的最低验证顺序。静态检查、样本测试、真实采集、本地落库和可选飞书／通知验收必须分开写，不能用“代码已生成”或“任务成功”代替端到端可用。数据类脚本必须先读[数据保存与输出开发公约](/docs/development/data-output-contract)。

新增结构化数据功能须使用 local-data v2，并交付输出 JSON 样例；多 Tool 使用 `--tool` 分别检查。旧脚本不加 `--strict-output` 时保留兼容。输出样例通过不代表真实站点采集通过。

## 1. 静态检查

在仓库根目录运行：

```bash
pnpm run verify:userscript -- --strict-output --output-fixture path/to/result-fixture.json path/to/script.user.js
```

该命令先对完整 `.user.js` 做 JavaScript 语法解析，再检查 UserScript 元数据、执行模式、`@match`/`@connect`、Tool 与输入 Schema 的 MCP 就绪度、飞书声明，以及可选飞书脚本是否有可整体留空的目标参数组。只解析元数据而不解析完整 JavaScript 不算静态通过。静态通过只说明源码可加载且契约可被当前框架识别，不说明选择器或接口仍然有效。

## 2. 模拟或脱敏样本测试

把解析逻辑拆成纯函数，至少覆盖：正常样本、字段缺失、登录/验证挑战或已知失败页面。预期结果必须逐字段断言；缺失价格保持 `null`，不得填 `0`。

首期 Amazon 样本测试：

```bash
node --test tests/amazon-product-detail.test.mjs
```

样本必须记录来源类型、适用站点、页面状态和日期。`static_fixture_only` 只能称为“脱敏样本测试”，不能称为线上实测。

## 3. 实际网站验证

条件具备时，在用户允许访问的真实页面完成：

1. 确认站点、登录状态、页面类型和当前变体；
2. 运行 Tool，对照页面逐字段核验；
3. 切换至少一个变体，确认 ASIN/价格更新；
4. 对页面插件确认按钮不重复、样式不污染页面、动态 DOM 更新后仍正确、离页时监听清理；
5. 未配置飞书运行一次，在本地数据中心按任务 ID 读回完整记录，刷新／重开后仍可查到；
6. 分别测试飞书整组留空、部分填写与完整填写；留空无写表 API 请求但仍落本地，半填不能开始采集，完整则本地和飞书均保存；验证缺失字段自动创建且不改动已有列；
7. 验证采集、本地保存、写表全部成功时机器人只发摘要和链接，异常时提示具体环节并保留报告；
8. 记录验证日期、URL 形态、浏览器/插件版本、结果和失败样本。

若遇到改版、A/B 页面、Robot Check、地区配送弹窗或未覆盖页面，应停止承诺可用，并索取脱敏 DOM、截图、页面诊断或可复现 URL。不要凭文字猜 CSS 选择器。

## 4. 安装验收

- 在插件精灵“安装脚本”中导入完整 `.user.js`；
- 检查权限预览只包含业务需要的站点；
- 检查 Tool 名称、描述、输入与返回结构；
- 核实新安装、升级及同步恢复均完整保存，旧 `none`／`summary` 设置不能再阻止落库；
- 运行单条任务，再运行批量、定时或 MCP 入口，按脚本支持范围分别验证本地保存；
- 对可选飞书脚本，先整组留空运行并确认本地落库，再完整填写两项自动写表，不另设写入开关；
- 验证飞书失败不丢本地结果；本地失败可见且能补存，补存不会重新采集、写表或通知；
- 最终报告分别列出“静态检查”“样本测试”“真实采集”“本地落库读回”“飞书写入”“机器人通知”的状态、证据和未覆盖范围。

## 5. 数据保存与恢复的最低验收矩阵

必须覆盖[通用公约的状态矩阵](/docs/development/data-output-contract)：未配飞书、飞书半填、全部成功、飞书失败／部分成功／响应不确定、本地保存失败、采集部分失败、通知失败。使用模拟故障验证恢复行为，条件具备时再用真实浏览器验证存储读回。至少断言：

- 任务报告存在与业务记录存在分别检查，不能只断言 `return.data`、成功徽章或下载按钮；
- 本地与飞书保存同一批业务结果，原始类型与缺失值正确，统计包括所有层级和批次；
- 分别验证报告数和明细数：报告类任务按任务 ID 查到 1 份本地报告、飞书新增 1 行，完整报告包含实际采集的全部明细，不以数据库行数代替明细数；同任务重试不新增，新任务新增；
- 对普通汇总报告脚本，7／501 条明细仍只生成 1 行完整报告；Alexa 默认问题 1.4.0 已由用户明确要求逐问展示，应分别验证 7／501 行本地明细、Excel 与飞书，以及 500+1 拆批；重试幂等和历史补存不触发额外采集或写表；
- 不创建或写入“记录键”列，使用已有任务编号和业务对象标识判断重复；旧列保留但不依赖其类型；
- 完整报告保留问题、答案、推荐追问、商品表格及正常段落格式；超限明确报错并保留结果，不能截断或擅自拆行；
- 本地失败时禁止声称整体完成，通知成功也不能覆盖落库错误。

如果浏览器、真实账号或持久化策略尚未核验，必须注明“未验收”和具体缺项，不能把模拟通过当成已经满足本地默认保存要求。


## 1.7.0 飞书自动写表公约

必须遵循[飞书自动写表开发公约](/docs/development/feishu-contract)：用户只填表格链接与授权码，脚本通过 API 自动识别表格、补齐文本列并写入，不要求复制表头、手填 App Token 或 Table ID、逐列设类型。全文本仅限飞书落表层，Tool 参数与本地业务数据保留真实类型。不得自动删除或强改已有字段与记录。

## 1.9.34 MCP 授权与视频直传验收

改 MCP 授权后运行 `node --test tests/mcp-entitlements.test.mjs tests/mcp-entitlement-client.test.mjs`，至少检查首次试用不可重置、试用／付费到期、同账号重复核销、跨账号不能复用、未核销码停用、账号隔离缓存、24 小时后核对以及本机到期断连。管理接口仍须经现有后台身份验证；这些单元测试不能代替真实微信公众号消息与生产账号核销。生产库只执行确实未应用的迁移，不因历史迁移登记缺口批量重放。

改视频上传桥后运行 `node --test tests/baidu-assets.test.mjs tests/script-registry.test.mjs`，验证活动任务和站点权限限制、HTTPS 来源、Range 响应、4 MiB 分片顺序及哈希、来源变化、百度返回值校验、任务取消与无整文件落地。脚本通过 `SellerFeeds.assets.uploadVideoToBaidu({url, filename})` 调用；脚本应把返回的网盘文件元数据放入任务报告，失败则明确向用户报告，不伪称上传成功。自动化中的模拟视频来源和百度 API 只证明协议逻辑；真实 TikTok 来源是否支持 Range、有效期和浏览器跨域权限，必须用获授权的真实账号单独验证。当前仓库尚无 TikTok 视频脚本接入。

合并验收命令为 `npm test`、`npm run check`、`npm run build`；构建后核对 `dist/extension` 与安装包版本。打包完成不等于浏览器已重载、官网／GitHub 安装包已发布，发布状态以 [官网下载页](/download) 为准。

## 1.9.36 近期功能验收补充

- **Tool 表单**：单 Tool 仅见紧凑名称，多 Tool 仅有一个选择框；同名 ID 不重复，同标题不同 ID 能区分；展开说明仍可读用途与输入输出。运行后 Tool ID、参数和结果须与选择一致。相关自动化：`tests/run-modal-picker.test.mjs`、`tests/manager-ui.test.mjs`。
- **表格双目标**：在自动表单切换飞书／钉钉 Tab 后原值保留，整组留空、半填、双组完整分别验证；每个平台独立记录写入状态与有效链接，重试先查重。样本测试不能替代真实平台表结构和权限验收。
- **消息机器人**：分别验证飞书消息事件、钉钉 Stream 私聊绑定和微信扫码后的首条消息，检查同事件仅执行一次、来源正确、报告只在本机且回到原会话；再用两台真实电脑验证飞书活动设备断线交接。仅握手或扫码成功不能判为收发成功；Worker 内存去重不承诺实例重启后的绝对一次。
- **本机与云边界**：无网盘时本机报告可读；绑定百度网盘或 WebDAV 后四类资料由浏览器直传用户目标，切换设置 Tab 不改变选定目标；个人 MCP Worker 离线时 `get_report` 不伪造报告。核对请求目的地，不能只靠界面文案判断数据是否经过官方。
- **代理与视频**：代理先保存不启用、开启后测试、关闭后恢复 Chrome 控制权，凭据不进入备份或报告；视频测试 HTTPS 来源、脚本和 Chrome 权限、Range/哈希失败、4 MiB 分片与任务取消。真实来源和百度网盘需另做端到端验收。

以上功能的代码入口、存储边界和当前未验收项见[近期功能交接](recent-features-handoff.md)。文档更新本身不触发插件打包或重载；修改 `extension/` 与覆盖本地构建须先按根目录 `AGENTS.md` 获得用户对该次操作的确认。