## 本机 3.0.9（2026-10-19，当前修复）

本轮修复对抗审查确认的问题，不增加跨脚本、ABA 导入或新 SDK。最新报表按任务/报告边界保留全部明细，数据库先选择范围再流式读取；旧无 runId 记录仍按独立报告处理。多值 in 筛选保存完整数组，between 才拆上下限。混合数值格式在新选字段时须确认读取方式，不转换原数据；已有明确模式保留。指定查询字段仍保留 runId。

设置 → MCP 新增已有能力的「数据授权」入口：全局查询默认关闭、逐表默认禁止，可选仅元信息/指定字段/全部业务字段。仅个人 Worker 在线只读通道；不恢复旧公共或本机 Bridge。权限保存校验管理页、当前账号/设备、原策略 CAS，只改当前数据表策略，不改备份/其他脚本，不依赖通知绑定。

数据结果的更多以「完整任务详情」替代原始报告中转；单批次直接打开原任务详情，全范围先选具体任务，取消或切号后迟到结果不打开弹窗。声明明细通过 resultArchiveOf 对应原数据表身份，不能按 history_ 名称漏选；用户手动选汇总仍保留。明确兼容 Amazon 19 站点 1.2.1–1.2.3 的旧汇总声明，新 v2 优先。仅剩旧汇总时提供「补全本机明细」明确操作，复用原本机恢复、删除保护及幂等流程；不自动重采集、回传、猜 Markdown 或恢复被删除记录。

本轮是本机补丁，不代表官网/GitHub 已发布。原脚本、数据、扩展 ID/key/原加载文件夹保持。验证记录见 output/patch-3.0.9 和 output/playwright/patch-3.0.9。

## 结构化输出 v2（2026-10-17，优先于下方历史规则）

新增会产生表格数据的功能，必须声明 `@sellerfeeds-local-data` v2。它是数据中心实际落库的规范，不靠脚本名称、AI、字段猜测或 Markdown 表格推断。`outputSchema` 继续描述完整 Tool 返回值；`local-data` 明确哪些内容成为独立表、行和列。只执行动作或只产生附件的功能可声明 `@sellerfeeds-data-center {"mode":"off"}`，原始任务报告和附件仍按各自机制保留。

官网目录的 8 个官方与 26 个社群脚本统一使用 v2 输出。新版源码删除飞书/钉钉回传逻辑、旧表格参数和远端回执字段；数据中心是唯一回传入口。采集业务参数、业务数据结构、数据集身份与完整报告保留。local_saved 等本机回执字段仅由插件实际归档成功后确认。旧定时任务或 JSON 输入若仍含已移除的表格参数，须按新表单重新保存；校验会拒绝多余字段，不猜测或静默删除用户配置。任意第三方脚本不按字段名称自动改写。

### 最小声明

```json
{
  "version": 2,
  "tables": [{
    "tool": "collect_products",
    "recordsPath": "data.products",
    "rowIdentity": "primaryKey",
    "dataset": {
      "name": "product-details-v1",
      "title": "商品明细",
      "version": 1,
      "mode": "snapshot",
      "primaryKey": ["asin"],
      "fields": [
        {"key":"asin","type":"string"},
        {"key":"title","type":"string"},
        {"key":"price","type":"number","nullable":true},
        {"key":"quantity","type":"number","nullable":true},
        {"key":"collectedAt","type":"datetime"}
      ]
    },
    "fieldPaths": {"quantity":"inventory.quantity"},
    "contextFields": {"collectedAt":"data.collectedAt"}
  }]
}
```

元数据中把 JSON 写为一行。返回值示例：

```json
{"data":{"collectedAt":"2026-10-17T00:00:00Z","products":[
  {"asin":"DEMO-001","title":"虚构商品一","price":12.5,"inventory":{"quantity":8}},
  {"asin":"DEMO-002","title":"虚构商品二","price":null,"inventory":{"quantity":null}}
]}}
```

结果必须是两行，不能保存成一行 `products` JSON 或一篇“完整报告”文本。完整可运行样例在 `examples/structured-products.user.js`，同时演示独立摘要表。v2 由插件校验、分批归档，脚本只返回结果，**不要再调用 `SellerFeeds.data.define/save/upsert` 重复保存**。旧版 SDK 流程仍兼容；不能把新旧写入方式混在同一 v2 功能里。

### 明确的数据语义

- `tables` 为 1–20 张表。不同明细数组分别声明，不能拼接成混合行，也不把两个数组做笛卡尔积。表名必须唯一。
- `recordsPath` 相对完整返回值；`$` 表示根。默认 `format:"rows"` 必须指向对象数组；`format:"object"` 明确把一个对象保存为一行。不存在的路径报错，空数组是合法的零行结果。
- `dataset.fields` 指定列名、类型及顺序，列名为顶层名称。`fieldPaths` 从每条记录映射嵌套字段，`contextFields` 从完整报告取站点、采集时间等上下文；同一列不能同时声明两种来源。
- `preserveExtraFields:true` 明确保留未声明的安全 JSON 字段，用于动态列和业务上下文；仍执行敏感字段及大小检查。`omitFields` 只能排除未声明的顶层辅助字段，例如执行回执，不得排除声明列或嵌套路径；完整任务报告不受影响。SellerSprite 的字段/数据继续按原格式存储、按业务行展示和回传。
- 必填字段缺失时报错。`nullable:true` 接受明确的 `null`；需要兼容可缺省字段时同时写 `optional:true`，缺省保存为 `null`。空值不变成 0，`0` 和 `false` 保持原值，数字字符串不自动转数字。
- 支持 string/text/number/currency/percent/boolean/date/datetime/url/image-url/enum/json/array。数字必须有限；日期须可解析；url/enum 当前校验文本类型，不代替网址可用性或枚举业务校验。`json/array` 是有意保留的单元格，例如标签或图片链接；要逐行展示的商品、评论等必须独立声明表。
- `rowIdentity:"primaryKey"` 需要 `primaryKey`，同批主键重复立即报错，不静默丢弃。只有业务明确唯一时才用 ASIN 等作为主键：同商品可多次出现时须加入站点/页码/位次等维度。
- 无可靠业务主键时使用 `rowIdentity:"position"`，不声明 `primaryKey`。插件以任务 ID 与行序号生成稳定键，保留重复值，重复保存同一任务不增行；它不代表跨任务的对象身份。
- 自动归档使用 snapshot：不同任务各自留存，不覆盖历史。表结构版本为正整数；已有数据的字段/主键/模式变化须换新 dataset.name，不能把版本号加一后强写旧表。
- 多 Tool 功能按表的 `tool` 区分；省略时适用于全部 Tool。每个 Tool 都须有对应声明。安装/更新及复用解析器的发布路径拒绝非法 v2 声明；运行时再次校验实际输出。
- 所有表完成结构、字段、主键和单行大小检查后才开始落库。每批最多 500 行、按字节拆批，单行上限 1 MiB（预留记录开销），单次返回值最多 100,000 行。多批/多表不是分布式原子事务：存储中途失败保留报告和已写数据，允许幂等补存，不能冒称全部成功。

### 新功能验收门禁

开发交付必须运行：

```sh
node scripts/verify-userscript.mjs --strict-output --output-fixture tests/fixtures/structured-output/new-products.json examples/structured-products.user.js
```

多 Tool 使用 `--tool <name>` 分别验证。`--strict-output` 拒绝没有 v2 的新结构化数据脚本（off 除外）；不带该参数保留旧脚本兼容并提示。样例验证会列出实际表名、行数和字段，可加 `--json` 输出机器可读结果。它不执行采集，不能替代真实站点验收。

验收不仅检查 JavaScript 能否运行，还必须经过生产归档和查询代码，确认：输入 N 条明细 → 数据中心 N 行；字段与类型正确；BI 和 Excel 使用同一份数据；空结果/缺字段/类型错误/重复键明确处理；重复补存不增行；跨账号隔离；删除数据不会被重新解析复活。新增回归在 `tests/structured-output.test.mjs`。

### 已有功能和历史数据

旧 v1、SellerSprite 紧凑 `字段/数据` 表和显式 SDK 数据集保持兼容。8 个已核对历史版本采用明确的 namespace、名称、版本和 Tool 映射：关键词 19 站点、类目 TOP100、New Releases TOP100、Alexa 自定义问题、Review 采集、搜索 AI 分析、库存监控、商品文案。新声明 v2 优先于兼容规则；未知未来版本不会套用旧映射。

TOP100 的兼容范围包含官网 1.4.1 与已有本地 1.5.0。既有 SDK 脚本的兼容修复（TOP100 1.5.1）可继续使用 v1 显式字段和 `data.榜单商品`，直接按商品写入新数据集，使旧插件也能保存明细；不能再把汇总行作为唯一的数据中心输出。此例不降低新功能的 v2 交付门禁。

在数据中心 → 对应功能 → 数据管理 → **重新解析明细**，可从仍保留的完整任务报告生成独立明细表，默认优先展示该表，原汇总表与原始报告保留。已完成相同解析的任务跳过；丢失的报告不能恢复。含删除记录的旧批次保守跳过，避免重建用户删除的数据；解析后单行删除也不会被重复解析复活。指定批次只处理该批次；全部范围处理该功能已完成任务。

解析不重新执行脚本，不读取网站，不写飞书/钉钉、不调用官方或个人 Cloudflare。落库属于真实本地变化，若用户已开启云盘数据备份，会遵循原有按变化备份策略；不能承诺新增数据永不备份。已有回传绑定不被复制到新明细表，需用户按需要选择新表的回传目标。

本轮经用户明确授权统一更新官网 34 个功能。安装新版插件后再更新功能。已有记录可主动重新解析，发布本身不修改本机历史数据。真实站点验收与模拟验证分别记录。

# 当前数据保存与输出公约

适用范围：2026-10-16 的 2.1.79 本地候选，包含第三十四轮回执迁移与使用引导；尚未代表官网发布版。以下现行规则覆盖后文历史章节中相冲突的参数、查重、写后读回及通知条件。接口和输出粒度仍须按用户实际安装能力核对。 官方账号备份服务已于 2026-10-16 经用户批准独立发布，私有 R2、D1 索引和清理接口已上线；这不表示本地插件候选或个人 MCP 服务升级已全量发布。

## 职责与数据流

### 第四十七轮：个人云备份与换机连接恢复（当前本地候选）

第四十七轮当前本地候选把个人资料备份迁回用户自己的 Cloudflare：功能/脚本、常用配置、书签、网站账号、邮箱及其他服务凭据先保存在本机，再按变化加密备份到个人 Worker 的独立存储。个人资料恢复密钥也保存在该用户服务；官方不再接收新的个人资料快照。官方仍加密保存通知机器人、百度网盘授权、Cloudflare 管理授权和服务连接信息，这些是换机恢复连接所需的资料，不等于个人资料正文。新电脑登录插件后，先从官方恢复连接，再发现并合并个人 Cloudflare 已有备份、取回恢复密钥；授权有效且浏览器权限齐备时不要求重新登录 Cloudflare 或百度网盘。明确在本机关闭备份的选择不会被自动发现覆盖；空服务不会自动开启备份。

未绑定 Cloudflare、百度或 WebDAV 也可安装和运行普通脚本。用户首次开启远程 MCP 或账号备份时，共用一次 Cloudflare 配置流程并准备两种服务能力，实际开关分别控制；仅开备份不会开启远程 AI 调用。任务、业务数据、附件和选中的邮件缓存仍按用户选择备份到百度/WebDAV，点击云盘备份才要求绑定。WebDAV 连接从个人资料备份恢复，业务恢复密钥保存在所选 WebDAV；百度授权和业务恢复材料沿官方账号恢复通道保留。Passkey 仍需要其独立解锁密码。

本机增改删先判断实际内容，连续修改合并；无变化为零备份 HTTP。查询、浏览、短期令牌刷新和恢复出的等价内容不制造新版本；不设周期上传。登录、实际启动和明确恢复按需发现远端，新电脑先合并再上传真实差异。失败只重试未完成工作，保持退避和每日失败预算。旧官方及旧个人云备份保留，只能在历史找回中明确选择读取，不自动删除或自动回退上传到官方。个人服务需升级到支持 /account-workspace 的 2.5.0；本轮代码、文档和本地包不表示线上 Hub 或用户 Worker 已更新。

### 第四十五轮：变化待办与联网边界（历史候选，备份归属以第四十七轮为准）

- 本机变化先写入持久待办，连续修改合并约 5 秒后处理；只读、短期令牌刷新、内容改回已确认版本不上传。空队列没有周期备份闹钟；重启继续尚未完成的待办。OAuth 长期刷新凭据变化仍纳入加密备份。
- 官方备份正文仍在私有 R2，D1 保存索引与版本。候选批量协议每请求最多 16 对象、客户端约 4 MB，正文先提交、清单最后提交，按摘要回执确认并保留版本冲突校验。批量减少 HTTP 往返，不承诺一次数据库操作，也不承诺跨 R2/D1 原子事务；旧服务继续走兼容路径。
- 自动备份网络故障按 30 秒、2 分钟、10 分钟、1 小时退避；同目标连续失败达到 5 次后等待 24 小时窗口。离线不请求，新数据不绕过已有退避；权限/配置错误暂停自动尝试。手动重试是用户明确操作，不计作无条件周期上传。
- Gmail 用 history 游标；Outlook 用各文件夹 delta 游标。Outlook 首次建立不加日期过滤的增量基线，避免过滤 delta 的 5,000 条限制，按本机保留日期筛选，每次最多推进 10 页。分页中断保留续页，游标失效重新建基线。远端删除只标记本机缓存，不等于授权删除本机历史。
- 可选本机 MCP 程序以 Native Messaging 和私有 Unix socket 连接桌面 AI，当前安装器支持 macOS/Linux、Node.js 22。工具调用不经过 Worker；授权过期时的实际使用仍检查官方授权。远程 MCP 只在开启时连接用户 Worker，20 秒保活帧与 HTTP 请求、D1 操作分开统计。
- 明确机器人指令本机解析；自然语言只直连用户选定的 AI。通知发送和指令接收独立，绑定通知不自动开启接收。新增本机接收方式应只在一台电脑启用；既有协调方式保留。
- 本机回收站、索引整理、浏览器定时任务继续运行；本地闹钟不等于云请求。用户配置的计划任务、收信和远程 AI 连接不静默取消。

上述候选代码未等同于生产发布；具体部署与验收见本轮实施记录。

新采集脚本默认负责业务采集、完整本机保存和任务报告；用户在数据中心确认绑定目标，插件负责字段准备、批量追加与写入重试，消息模块负责投递执行及回传结果。表格连接、机器人通知、网盘备份是三个独立目标，凭据与成功状态不能混用。

作者主动声明并获授权的 HTTP 表格调用和 `table.feishu.append/update` 仍可使用；输入字段完整展示，不能按 `baseUrl`、`baseToken` 等名字隐藏或丢弃。这里是兼容或专门业务能力，不要求每份新采集脚本重复实现写表。脚本直写与数据中心绑定目前没有统一互斥机制，迁移同一输出时须明确唯一写入方，不能把两条路径同时启用当成自动去重。

## 本机记录与表格行

- 有业务结果完整保存本机；纯动作可声明 `@sellerfeeds-data-center {"mode":"off"}`。报告存在、通知已发或表格有链接均不能替代落库回执。
- `SellerFeeds.data.define` / `save` / `upsert` 沿当前 SDK 校验；`@sellerfeeds-local-data` 用于声明报告到本地记录的映射。不要重复归档同一批数据。
- 明确一条记录是报告还是业务明细。紧凑报告的 `字段` 与二维 `数据` 对齐，缺值用 `null`，数字保留数字；数据中心写表时展开明细，并保留外层业务上下文。
- 每次监控需保留观测历史时使用带任务身份的快照或不可变新增记录。普通 `upsert` 对已有记录的修改不触发原表追加，不能把“本地更新成功”解释为“远端已更新”。插件维护的历史数据集会新增本次快照；历史表绑定后，该快照提交即唤醒同步，通知关联实际历史表。暂停期间保留待办，恢复只处理未确认数据。
- `outputSchema` 的业务字段应有用户能理解的 `title` / `description`，输入、结果说明展示业务含义；状态字段不应充当全部业务结果说明。

## 数据中心追加规则

每个数据集当前只有一项表格绑定，选择飞书或钉钉；不能承诺同一数据集同时向两个目标自动回传。用户首次确认连接后排入现有记录，随后新增数据提交本机事务即唤醒队列。没有待办不请求远端；普通编辑及同目标重绑不重放已确认记录。首次连接当前最多接受 20,000 条本地记录，不能宣传无限量历史初始化。

同数据集、同目标、同运行聚合：飞书每批最多 500 行，钉钉当前每批最多 100 行，源值估算体积超过 1.5 MB 时再分片。每批核对字段、复用兼容列、补建缺列；类型冲突另建同步列，不修改既有列。飞书当前支持文本、数字、复选框，钉钉支持文本、数字。复杂关系、人员、附件等字段不是现有写入能力。

追加不读取远端业务记录查重、比较或写后核对。成功以接口返回完整、有效且数量一致的记录 ID 为准；本机保存完成回执与报告进度，成功部分退出队列。专用文本标识列仍用于记录归属及用户明确执行的云端删除定位；显式删除是独立路径，仍有定位及删除确认。

失败请求的成员、源值、字段映射和飞书 `client_token` 在本机持久化，重试复用原批次。可重试错误依次等待 30 秒、1 分钟、2 分钟、5 分钟、10 分钟，随后每 10 分钟；明确参数或授权错误等待修正。运行依赖浏览器与有效账号会话，不是关闭浏览器后继续运行的云端服务。飞书令牌不保证无限期恰好一次；钉钉响应丢失后的追加重试可能重复，不作零重复承诺。

## 换机与写入回执

业务备份格式 v4 随每条本机记录保存“目标表指纹 + 成功回执 / 已确认明细进度”，以及用户执行云端删除后的排除标记。指纹绑定实际目标，不能只以连接的显示名称判定。换机恢复后，同一目标的成功记录不入队，部分成功报告从已确认位置继续；不同目标独立计算。已有目标连接时，恢复新增记录会进入该目标的待办；暂停连接仍暂停。无目标连接时需在数据中心重新选定同一张表，恢复备份本身不会新建凭据或远端授权。

成功回执或进度变化会改变自动业务备份的内容指纹，即使没有新增业务行，也会在下一次正常备份检查时更新；不新增远端业务记录轮询。备份期间进度变化则拒绝完成过期快照，交由原备份机制重试。合并恢复不会把旧成功状态附到内容不同的新本机记录；明确覆盖不同内容时，清除被替换内容的旧回执，再采用备份中对应内容的回执。

仍可读取 v3 备份，但旧格式没有成功证据，不能推断“已同步”。新格式需要支持 v4 的客户端恢复。最新备份之后发生的远端写入不在快照中；本轮不提供多设备同时写入锁，也不备份消息投递队列或恢复表格连接授权。未知响应的失败请求不作为成功证据，跨设备不承诺零重复。

## 后台备份与资源边界（第四十二轮本地候选）

本节覆盖前文旧失败重试描述：钉钉追加响应丢失、服务端 5xx 或成功响应不完整时标为待确认，停止自动追加；用户核实后才能手动决定重试。备份保留未确认批次的令牌与数量标记，换机遇到该标记也暂停自动追加，不能当成成功回执或另开新批次盲目重发。

资料有语义变化才触发备份，连续变化合并；空闲检查不读取云端正文或上传新版本。启动、登录、手动恢复与新目标首次连接可做远端发现，设备会话安全心跳独立存在。官方资料保留最近 10 份及近 30 天每日一份，私有 R2 保存密文、D1 保存有限索引；未完成对象经引用和活跃上传检查后回收。服务端尚未发布时不得宣称官方备份可用。

业务网盘自动备份按内容复用加密分片，每个清单是完整恢复点；上传失败保留本机工作包续传，手动旧格式仍可恢复。自动清单保留最近 10 份；通用网盘共享对象暂不自动回收，不能宣称总存储恒定。邮件备份逐邮箱失败隔离，缓存时间刷新不制造新版本。

普通附件确定失败按独立退避重试，成功文件不重传，空队列取消闹钟；百度写入结果不明单列待确认。网络错误、429 和明确可重试服务错误采用 30／60／120／300／600 秒加少量随机延迟并尊重 Retry-After；权限、地址、容量等错误暂停自动重试。每日请求计数只保存在当前设备，不上传新遥测，也不等于 Cloudflare 账单。

## 安装与字段说明

脚本介绍及示例由作者在脚本介绍页的“详细使用说明”维护，使用现有 `@sellerfeeds-readme` JSON 字符串承载 Markdown。官网介绍页、安装预览、首次安装完成页和管理功能的“说明与网站”展示同一份作者内容。插件只做安全排版，不解析输入／输出 Schema 或执行模式来拼写介绍、推断要求或制造示例。缺少正文时提示作者尚未提供；已有脚本从原元数据读取，不改源码、不猜含义。

作者正文应写明用途、使用要求、输入示例、结果示例与操作步骤；示例须标明虚构且不含秘密。介绍正文与运行契约分开维护，二者必须一致。详细说明为有效 JSON 字符串，最多 20,000 字；支持标题、列表、代码块和表格，原始 HTML 和链接作为文本展示，不执行说明中的代码。新安装才自动打开说明，更新不反复引导。

运行参数继续用作者填写的 title / description / default，Tool Schema 保持校验及 MCP 契约。可选布尔项说明勾选／不勾选的差异及额外要求，每行两个原生复选框，窄屏一列；必填、枚举、秘密和资源组保持原控件。这些字段说明不被重新组织为介绍页正文。

## 普通任务通知

`@sellerfeeds-notify` 的 `all` / `failure-only` / `off` 与渠道启用状态分别约束通知。MCP 和机器人入站任务不额外发送普通任务通知；机器人指令回复有单独出口。

| 结果 | 普通任务通知路径 |
| --- | --- |
| 任务执行失败 | 直接说明失败原因，不等写表 |
| 执行成功且本次有效绑定表格 | 等本次数据写入回执完成，再发送绑定的表格链接 |
| 执行成功且无有效绑定 | 飞书通知发送本机生成的 Excel；钉钉当前以文本通知，不承诺同等文件能力 |
| 表格写入失败 | 单独说明写表失败，保留本机结果和待办；写入恢复后再发链接 |
| 部分失败批次 | 直接说明成败数量并走报告路径，不等待所有成功项写表 |
| 同次数据有已绑定和未绑定部分 | 链接与未绑定部分所需报告并存 |

`wrote_feishu`、`table_url` 和 `@sellerfeeds-notification link-on-success` 仍可被历史脚本解析、保留，但不再决定普通任务通知的链接或附件路径。数据中心绑定及本次回执才是依据。

消息有独立、按账号持久化的投递队列，失败按 30 秒、1／2／5／10 分钟退避，随后每 10 分钟；不重新采集或写表。文字和文件、各渠道分别记回执，只重试未确认部分。完成回执留本机，释放报告副本。切号隔离，接收者或原会话变化时停止旧报告投递；响应丢失仍可能重复消息，不能承诺消息必达或零重复。手动、定时、批量共用状态记录，批量只发一份汇总并将回执关联各项任务。

飞书和钉钉入站指令复用相同的表格判定，等待回执后回复原授权会话，不加发普通通知。会话地址加密保存七天；钉钉群会话过期时不擅自改发私聊。已退役微信旧客户端不纳入新运行包。采集成功但本机保存失败时，摘要明确显示保存错误，并保留报告；有报告不等于保存或写表成功。

首次字段准备对明确的网络、限流错误退避重试，参数与授权错误等待修正。同目标字段与数据请求至少间隔 200ms；接口 Retry-After 优先于默认退避，同目标追加共享冷却期。

安装预览、安装提交、更新、官方与社区发布共用不执行源码的 Acorn 语法检查，最终分发正文再核对；语法通过不等于真实采集或写表验收。13 个仓库维护的趋势／关键词生成模板迁移为数据中心输出，原脚本身份保留、修订号递增；另有明确使用脚本直写的生成器保留兼容模式。本轮没有更新官网脚本，也没有静默修改用户已安装的脚本。

旧版输出契约标记为 `data-center-append-1`；本轮 v2 使用 `structured-output-2`，最低插件版本 2.1.85。在线手册只有在契约相同、适用插件版本不高于当前安装且修订不早于随包内容时才替换。数据、表格回执、消息投递独立验收；本轮只有隔离验证，未操作真实目标表或机器人。

## 历史开发约定

下文保留历史脚本的来源说明和兼容规则。凡要求所有新脚本提供回传参数、先查重再追加、依脚本成功标志选择通知的描述，均由上文现行规则覆盖。

> 2.1.2 历史规则：配置中心统一添加服务，脚本确认声明后按 Tool 绑定用途，不再逐服务授权。脚本可调用插件代办的 HTTP、AI、MCP、邮箱、账号/验证码填充与笔记功能，没有秘密读取接口。凭据沿用各自的用户自有云/本机存储；邮件内容仅本机与用户主动选择的网盘。

# 数据保存与输出开发公约

> 当前 1.9.63：Cloudflare 部署集中设置，记事本与普通书签无需主密码，验证器归入 Warden 密码库。实现与数据边界见[统一个人云](unified-personal-cloud.md)。这些管理能力不向脚本、MCP、AI 开放；旧版说明按历史理解。


修订日期：2026-09-28。适用于新开发、升级和 AI 生成的数据查询、采集、监控类脚本。本文规定交付要求；插件实现入口及仍待真实账号验收的行为见[近期功能交接](recent-features-handoff.md)，不能把文档更新当成运行时功能已经完成。

## 核心约定

**有业务结果的脚本默认完整保存本地；飞书多维表格与钉钉 AI 表格是相互独立的可选输出；机器人通知只负责告知结果。** 纯动作脚本可声明数据中心 `off`；数据脚本不得以远端表格或机器人消息替代本地保存。每个远端目标和通知分别记录状态。

手动、批量、定时任务是否通知由 `@sellerfeeds-notify` 的 `all`、`failure-only`、`off` 决定，还取决于用户绑定、启停和网站权限。MCP 与飞书／钉钉／微信入站指令任务不发送额外的普通任务通知。飞书机器人本机直发若因账号未登录、推送停用、缺少开放平台权限或凭据而未发送，必须把“未发送”及原因写入任务记录，并在完成提示和任务详情显示；不得把跳过发送显示为成功。已有账号绑定但本机凭据缺失时，先尝试同步一次再发送。任务采集成功与机器人通知成功分别记录，通知故障不得抹掉采集结果。

用户不配置远端表格，采集结果仍须进入当前浏览器的本地数据中心。配置飞书或钉钉后，本地保留同一份完整业务数据，各平台只保存各自确认写入的副本。任一平台写入失败、超时、没有通知渠道或通知发送失败，都不能取消本地保存。

本地保存指浏览器 Profile 内扩展 IndexedDB 的业务归档，可在数据中心按脚本、任务和业务字段查找。仅有任务历史、成功标记、返回的 `data` 对象、可下载报告、飞书表格链接或机器人消息，均不能作为业务数据已经落库的证据。

## 报告数量与明细数量分开

报告类脚本默认按“一次任务一份完整报告”组织本地结果和飞书输出。飞书一行代表一份任务报告，全部明细置于“完整报告”列；只有用户明确需要按明细逐行分析时，才另行采用明细表。不能直接把内部 `results[]` 的每个元素当成一份报告。

钉钉 AI 表格作为与飞书多维表格平级的可选写入目标。脚本可同时提供两组独立参数；不填某一组时不得请求该平台。写入顺序是先确认本地报告，再分别写入已配置的目标；一边失败不得撤销另一边已确认的写入或本地报告。每个目标独立记录成功状态与链接，通知时仅使用确认写入的链接。报告类脚本沿用一次任务一行的口径；同任务重试要先按任务编号和实际业务列查重，查询未完成时停止追加，避免重复行。钉钉应用凭据属于密钥，Tool Schema 应标记 `writeOnly`，不得进入报告或本地业务字段。

运行表单中同时存在飞书与钉钉回传参数组时，以“飞书多维表格 / 钉钉 AI 表格”Tab 切换显示；两组字段仍各自保留输入、分别校验和回传，切换时不得清空。`wrote_feishu`/`table_url` 与 `wrote_dingtalk`/`dingtalk_table_url` 分别证明两个平台的写入；通知摘要只列出已确认且有效的链接。若一个平台失败，摘要说明失败，同时保留另一平台的成功链接。MCP 任务先返回任务编号，AI 可通过 `get_report` 读取本地 JSON；本地 Excel 转换按需进行，不能阻塞 MCP 首次返回。

Alexa 默认问题一次只接收一个 ASIN。用户明确要求逐问展示后，版本 1.4.0 起任务 JSON 仍为一份紧凑报告，本地明细表、Excel 和飞书则一个已采集问题一行：7 个问题是 7 行。每行有自己的问题、完整答案、关联问题1至5独立列；缺失关联问题为空。历史脚本内飞书写入曾按任务编号、ASIN、问题编号和问题文本读回查重。当前 1.4.4 已删除该写入器，飞书/钉钉由数据中心按其回执和中断规则管理，不沿用旧脚本的重试逻辑。旧版一任务一行的汇总数据集保留为历史；新版结构见[Alexa 默认问题功能页](/scripts/alexa-default-question)。

### 多条明细的省 Token JSON

用户要求按明细逐行分析时，先分别确定**报告／本地记录的数量**与**Excel／飞书的行数**。SellerSprite 出单词反查采用一任务一份 JSON 报告、一条本地数据中心记录；Excel 和飞书则一个关键词一行。不得因为要逐行导出，就把 JSON 和本地数据拆成每个关键词一份报告。

对于字段相同的多条明细，JSON 和本地记录使用顶层 `字段` 字符串数组与 `数据` 二维数组：列名只声明一次；每行的值按 `字段` 的相同下标解释，长度必须一致，缺失值使用 `null` 占位。未选择的指标不进入 `字段`，也不在每行重复写键名。数字保留数字类型，不在 JSON 中预先文本化。示例：

```json
{"字段":["关键词","周搜索量","排名"],"数据":[["calculator",134565,697],["scientific calculators",65432,null]]}
```

Excel 转换层用 `字段` 作表头、`数据` 的每个内层数组作一行；飞书写入层才将对应位置展开成字段名到值的映射，并按目标表格类型处理。数据中心保留原紧凑结构。开发或修改这类脚本时同时更新 `outputSchema`、本地数据集字段、示例文档及测试；测试须核对列顺序、行宽、缺失值、Excel 行数与飞书行数，防止再次退回逐行对象数组。

### SellerSprite 明细脚本的统一出口

用户指定的 SellerSprite 明细脚本按上述规则处理，生成器共覆盖 21 个脚本。默认下载 Excel；JSON 下载和数据中心按一个任务保留一份报告，并以顶层 `字段`／`数据` 二维表表示明细。Excel 的数据工作表一条业务明细占一行；配置飞书后，一条业务明细写入一行，并带任务编号、站点和输入上下文。关键词综合查询的首条结果是数据表第一行，与关联关键词共用列定义；其他脚本的任务级商品信息可留在报告摘要。

MCP 调用先返回任务编号；任务完成后，客户端通过 `get_report` 读取保存在浏览器本机的 JSON 主报告。MCP 通道不等待 Excel 文件生成，也不向官方服务器上传报告。Excel／Markdown 仅在用户下载或相应通知确实需要文件时由插件本机转换。脚本内下载仍默认 Excel，一行一条明细。脚本的 MCP Tool 须写明用途、输入和输出；本仓库 61 个脚本的 Tool 描述已逐一核查。

明细粒度按业务含义确定：关键词列表按关键词，趋势按时间点，市场分布按“月份＋区间”，核心关键词趋势按“关键词＋月份”，留评率的月度记录与评分历史用“明细类型”区分。同一任务本地先保存完整紧凑报告，再开始可选飞书写入。飞书表格不创建“明细键”列；用任务编号筛选已有记录，按实际业务列及重复次数读回查重，重试只补缺失行。未配置飞书时不调用飞书 API；本地保存失败时停止飞书写入并报告错误。缺失指标用 `null`，数字在 JSON 中保持数字类型。

这些脚本的共用输出实现位于 `scripts/sellersprite-row-output-support.mjs`，各脚本仍由对应的 `scripts/generate-sellersprite-*.mjs` 生成。改动时须同步更新生成器、生成产物及测试；不能只编辑 `examples/`。浏览器插件本体的修改遵循项目协作约定，须先告知用户并得到该次修改的确认。

## 设计与开发顺序

1. 明确采集对象、每条业务记录的含义、必需字段、缺失值、唯一标识和父子关系。数据与排版分离，同一答案不重复拆成多份供用户阅读。
2. 明确本地数据集、追加／更新／快照语义、去重键及查询方式。本地完整保存是统一行为，不提供用户保存策略。
3. 用户填写业务参数；飞书与钉钉表格各有可整体留空的参数组。两组分别校验，部分填写须在采集前提示补齐或清空；切换运行表单 Tab 不得清空另一组。授权码和应用密钥在 Tool Schema 标记 `writeOnly`。
4. 采集后优先确认本地持久化，再处理可选飞书输出。长任务按可恢复的批次保存；已有部分成果应能在中断后查到。实现时先核实目标执行模式实际暴露的存储接口与提交回执；内部存储模块存在不等于脚本可以直接调用。不编造公开 API 或脚本元数据，也不绕过脚本间的数据隔离。
5. 各平台配置完整才读取目标表并按该平台契约写入；飞书字段处理见[飞书自动写表开发公约](/docs/development/feishu-contract)。用户已填参数不等于写入成功；同任务重试必须先读回查重，无法确认时停止追加。
6. 汇总采集、本地保存、飞书和钉钉写入各自状态，再按脚本通知声明及已启用渠道告知结果。最后验证数据中心能够实际读回业务记录。

所有已安装、新安装、升级和同步恢复的脚本均统一完整保存本地结果。旧的 `none`／`summary` 设置不再生效；不展示保存方式选择、不要求用户开启保存、不因旧设置阻止采集。

## 状态与通知矩阵

以下以脚本声明允许通知、用户已启用且实际具备机器人通知能力为前提；MCP 和各机器人入站指令任务不适用此普通任务通知矩阵。表中飞书可选写入示例不排除同任务同时写入钉钉 AI 表格；钉钉成功和失败须另外独立记录。

| 情况 | 本地数据 | 飞书表格 | 通知与完成状态 |
|---|---|---|---|
| 飞书参数全部留空 | 完整保存 | 不请求写表 API | 保留正常摘要／报告；不生成虚假的表格链接 |
| 飞书参数部分填写 | 不开始新采集 | 不写入 | 执行前提示补齐或清空整组 |
| 采集、本地保存、飞书写入全部成功 | 完整保存且可读回 | 确认写入成功 | 只发送任务摘要与有效飞书表格链接，不上传报告文件 |
| 飞书写入失败、部分成功或结果待确认 | 完整保留已采集数据 | 如实记录确认数量及待确认状态 | 明示飞书问题，保留报告，不发送“全部完成”通知 |
| 本地保存失败，其他环节成功 | 不能标成已保存 | 保留真实写入状态 | 明示本地失败与恢复入口，不能只发送飞书链接掩盖缺失 |
| 采集部分失败 | 保存已取得的数据和失败明细 | 按真实结果保存已取得的记录／状态 | 说明成功、失败数量，保留报告 |
| 通知发送失败 | 保持已存数据 | 不重放已成功写表 | 单独报告通知失败，仅重试通知 |

`link-on-success` 的成功门槛应代表本次所需环节全部完成。`wrote_feishu` 只表达飞书写入事实，不能用它冒充本地已保存；必要时使用独立的完成字段作为通知条件。无论飞书文件发送是否成功，本地原始数据、任务报告和用户主动下载入口仍须保留。

## 本地数据与恢复要求

- 本地完整保存不再是可选策略。覆盖 URL 安装、本地导入、同脚本升级和跨设备恢复，验证旧保存字段不再影响结果落库。
- 记录需可关联任务 ID、采集时间、来源站点和业务主键。问答需保留问题、上级问题／层级、完整答案及推荐追问；具体字段以业务需求为准，不要求所有脚本采用同一张表。
- 本地 JSON 保留数字、布尔、数组、对象和 `null` 等真实类型。飞书文本化仅在写表适配层进行。未知价格不能写成 `0`，没有回答不能伪造成功。
- 先确定任务报告与内部明细的层级，避免重复存入多份报告文件。报告类脚本按任务汇总，保留对象、时间、状态和明细数量等可筛选字段。说明单记录和单批限制；内部可以分批处理，但不能因此把一个任务拆成多份用户报告。汇总超限需明确报错并保留可恢复结果，不静默截断或擅自拆行。
- 区分采集结果、业务落库、任务报告保存和远端写入状态。归档异常需可见，不能仅记录日志；报告存在不等于业务数据存在。
- 本地补存只保存已有报告或缓存，不重新请求目标网站、不再次写飞书、不重复发通知。报告不完整或缺失时必须明示，不能假称补存成功。
- 飞书补写只处理未确认成功的记录。为每个输出目标定义去重键，并区分同任务重试与新采集快照；对不确定写入先查目标记录。不得盲目重放整个任务。
- 本地保存不自动授权云端备份或 MCP 查询。备份、账号配置同步、机器人通知与业务写表分别遵循已有权限和触发规则。Cookie、授权码、Token 等凭据不得混入业务数据、报告或日志。

## 参数和报告可用性

- 面向用户的参数 `title`、帮助文字和错误提示使用中文，内部稳定字段名可以保留英文；定时、批量和 MCP 复用相同的校验及保存规则。
- SellerSprite 脚本收到 HTTP 0、401、登录重定向或上游明确的登录失效代码／文案时，统一返回 `LOGIN_REQUIRED`，提示在运行插件的当前浏览器登录卖家精灵；不要显示泛化的网络或 HTTP 错误。真实的权限不足和其他上游错误仍按各自错误返回。生成器与手写脚本都要覆盖这一分支。
- 已有标识能够确定的内容自动生成，不增加重复输入。目标站点有歧义时先明确支持范围，不能从 ASIN 猜出站点。本次 Alexa 默认问题只支持美国站。
- 完整业务数据只定义一份。Markdown、Excel、JSON 和飞书是同一数据的不同表达，不应各自遗漏关键字段或形成互相矛盾的值。
- 问答阅读报告按“答案内容＋推荐追问”组织；商品图片、价格和链接属于答案内的表格内容，不重复输出多份清单。飞书文本列保存 Markdown 时，明确它不会自动变成带图片的嵌套表格。

### 网页上下文、消息指令与视频文件

- 想在网页悬浮运行窗预填输入，须在 `@sellerfeeds-tool` 显式声明 `pageContext`。目前支持 Amazon 商品／评论页的当前 ASIN 与站点白名单来源；展示来源并允许用户改值。页面商品变化后旧值不得直接执行。不得按字段名猜值、填竞品 ASIN、获取密钥或自动提交任务。
- 飞书、钉钉应用机器人和微信 ClawBot 的自然语言指令也调用同一 Tool。`description`、输入 Schema 和输出 Schema 要能让 Workers AI 在不读取脚本源码时判断调用场景；本机仍二次校验参数。消息正文和 Tool 目录可发往用户自己的 Worker AI，完整报告留本地；脚本不得把报告或授权码塞入 Tool 描述。入站来源任务不再触发普通任务通知。
- 视频保存另需 `@sellerfeeds-assets {"video":true}` 和 `SellerFeeds.assets.saveVideo({url,filename})`，只处理任务取得且已授权的 HTTPS 来源。用户选择文件同步位置后，插件沿该规则上传；未选时使用浏览器下载目录。数据中心显示媒体元数据与已确认路径，大视频正文不进普通文件库或报告。历史浏览器下载不会自动重新上传。旧 uploadVideoToBaidu 拒绝执行，需作者迁移。真实 Range/有效期/跨域需验证，不能把任意文件交给视频通道绕过限制。

## AI 交付前必须给出的证据

1. 参数表与结果示例，并说明任务报告和明细的层级、本地记录结构、支持站点、缺失值和去重语义。报告类脚本用 7 条明细示例验证本地一份、飞书一行、内容完整，分别核对报告数与明细数。
2. 对已安装脚本运行一次未配置飞书的任务，在数据中心按任务 ID 查到记录，刷新或重新打开后仍能读到。
3. 配置飞书后，同一任务既能在本地查到，也能在飞书查到；写表成功且按声明验证有效链接时，机器人只发送摘要与链接；未确认成功时仍按输出声明发送报告文件。
4. 飞书失败仍保留本地结果；本地失败显示具体错误并可补存；补存不会触发二次采集或二次写表。
5. 手动、批量、定时与 MCP 入口共用保存规则，批次计数和部分失败不被隐藏。
6. 分开列出静态检查、模拟测试、真实浏览器落库、真实飞书写入及通知验收的状态。只跑 Node 测试或只看到任务成功，不能宣称端到端验收完成。

## 已实现的接口与适用边界

插件精灵 1.8.2 新增受运行器识别的 `@sellerfeeds-local-data` 声明。声明指定 `dataset`、报告中的记录数组路径 `recordsPath`，以及可选的 `contextFields` 上下文字段映射。数据集必须使用 `snapshot` 和业务主键，字段名使用顶层字段；完整示例见开发指南及 Alexa 默认问题 1.3.2 源码。此声明用于业务结构和报告恢复，不是本地保存开关。

从插件精灵 1.8.3 起，未声明保存策略的旧脚本默认保存本地结果，不需要 `@sellerfeeds-local-data` 才能保存。该声明用于按业务行组织数据和补存；未声明脚本由运行器完整归档返回结果。操作型脚本正常返回 `null`／`undefined` 且没有写入业务数据时，仅保留任务执行记录，显示“无业务结果”，不创建空的业务行或报错。声明了报告业务路径却返回不符合契约的数据时，仍须报告具体错误。

新脚本须分别声明 `@sellerfeeds-notify {"mode":"all|failure-only|off"}` 与 `@sellerfeeds-data-center {"mode":"save|off"}`，实际元数据一次只选一个值。通知声明控制手动、批量、定时任务的机器人消息；MCP 始终不发任务通知。原有 `@sellerfeeds-notification {"mode":"link-on-success",...}` 只控制成功链接内容，不替代通知开关；没有该声明的旧脚本可用 `wrote_feishu === true` 和有效 `table_url` 确认链接。数据中心 `save` 表示保留默认自动归档和脚本主动业务写入；`off` 只供纯动作脚本使用，阻止两种写入，任务历史照常保留。`off` 与 `@sellerfeeds-local-data` 冲突。没有新声明的旧脚本继续按原有默认行为执行。

脚本通过实际公开的 `SellerFeeds.data.define(dataset)` 和 `SellerFeeds.data.save({dataset: name, records})` 保存业务记录；必须等待提交回执并核对数量。Alexa 1.3.2 在访问 Amazon 前检查数据接口和存储可用性，采集结束或可捕获的中断后将全部已有问答汇总成一份商品报告，本地保存尝试结束后再尝试可选飞书；本地失败仍允许飞书保留额外副本，但必须显示本地错误并保留报告，不能只通知成功链接。单批最多 500 条且受字节限制，单条记录仍受本地容量约束；超限须明确报错，不能截断原文。

Alexa 当前汇总实现不再每完成一问就持久化；强制关闭浏览器可能来不及保存内存中的问答。此限制必须如实说明，不得把内存进度称为已落库。其他长任务应按恢复要求设计持久化进度，同时保持对外一份报告的数量语义。

任务结束归档及“补存任务结果”按声明从报告提取业务行，以同一任务的快照主键跳过已存记录，补齐缺失记录。补存只读已有报告，不执行脚本、不请求 Amazon 或飞书、不重复通知。报告缺失时拒绝补存；旧报告没有声明路径时保留任务中的原始报告并明确报错，不退回整份报告归档后声称业务补存成功，也不猜测业务结构。脚本报告已声明本地失败时，正常结束流程保留失败状态，由用户通过补存入口恢复；补存后的最新状态以任务的数据保存状态为准，原报告仍保留当时的错误记录。

运行器归档失败会同步修正报告的本地状态和 `output_error`，阻止只发成功链接。通用兜底归档仍发生在脚本返回后；随 1.8.3 配套的 Amazon 商品、库存及 Review 写表脚本已在飞书调用前通过现有存储接口保存完整采集结果；本地失败时保留报告并停止该次飞书输出。第三方自行编写的外部输出仍需遵循这一调用顺序，插件不能替任意源码重排网络请求。

本地构建和模拟测试不会自动更新用户已加载的插件、已安装脚本或官网，也不等于真实浏览器、Amazon、飞书和机器人端到端验收。交付时必须分别说明这些状态。

任务列表只显示简短编号，完整任务 ID 放在任务详情中并支持复制。任务详情分别展示采集、本地业务数据和飞书输出状态。Alexa 的 `feishu_status` 使用 `skipped`（未启用）、`saved`（确认完成）、`incomplete`（未完整确认，可能部分写入）；不将未配置误报为写入失败。补存成功以任务最新 `dataSaveStatus` 为准，原报告中的错误只作为原任务记录展示。

普通无报告的操作型脚本允许正常完成；“从报告补存”必须有可恢复的报告。不能要求所有脚本都人为生成报告，也不能把缺少已声明业务记录的情况误报为成功保存。


## 数据中心展示约定

数据中心先按脚本分组，进入脚本后直接把历次任务的 `字段` 和 `数据` 汇总展开为明细表，每条业务明细一行。不同任务的相同 ASIN、关键词等业务值全部保留，以任务编号、脱敏后的输入参数摘要和采集时间区分，并支持筛选、分页与 Excel 下载。输入摘要只从任务输入生成，经 Tool Schema 的 `writeOnly` 与凭据字段规则脱敏后保存；不得把真实授权码、Token 或敏感表格链接放进总表或 Excel。点击任务编号或在任务中心点击“查看数据”，直接打开该次任务的弹窗；弹窗默认显示明细表，也可切换该次任务的原始报告 JSON。展示层转换不改变每次任务一份紧凑报告的本地保存，也不物理复制一份脚本汇总。脚本负责声明数据集名称、字段名称与类型、索引及业务记录提取规则，不必为数据中心选择列表布局。

数据中心的 Excel 主工作表按业务明细逐行汇总。单元格正文超过 32767 字符时，主表保留该位置的引用说明；“超长内容”工作表按主表行号、任务编号、原字段和片段序号分行存放完整正文。导出不改变本地归档，原始 JSON 仍保持紧凑报告结构。

已有 `display.type` 的 `cards`、`article-list`、`timeline`、`detail-list` 声明仍可被解析，已有记录无需迁移；这些值不再改变列表外观。`display.titleField` 和 `display.linkField` 仍用于记录详情的标题和原文链接。列表预览缩短长文本，存储、详情及原有导出流程不因此截断内容。

浏览界面只列出总记录数大于零的数据集，并按此计算数据集数量；筛选无匹配记录不会隐藏数据集。删除最后一条记录后隐藏空数据集，自动切换到有数据的数据集，仅剩一个时隐藏下拉框，全部为空时显示暂无数据。空数据集的字段定义保留在本地，后续写入后会重新出现。
## 历史存储与 MCP 通道（归属以本文顶部第四十七轮为准）

脚本、常用配置、任务历史及数据中心报告保存在浏览器本地；绑定百度网盘或 WebDAV 后，由插件直接备份到用户网盘。SellerFeeds Hub 不接收这些业务备份。旧 D1 脚本／配置快照及其表已按用户要求永久删除，不再提供迁移读取。

MCP 使用用户 Cloudflare 账号中的 Worker 与 Durable Object 实时转接到浏览器，不使用官方公共 MCP。Hub 仅加密保存该账号的 Worker 地址及连接密钥以便换机恢复；用户在新设备上点击启用并确认网站权限。Cloudflare 管理 OAuth 令牌不备份。MCP 任务不触发普通机器人成功／失败通知。

脚本向外部 MCP 服务写入数据时，先在配置中心添加 HTTPS Streamable HTTP 服务；脚本声明能力并按 Tool 绑定服务或用途。脚本在活动任务调用 `SellerFeeds.mcp.listTools({serverId})` 或 `SellerFeeds.mcp.callTool({serverId,name,arguments})`，只有 USER_SCRIPT 与 offscreen 执行模式可用。`listTools` 只展示获准 Tool；`callTool` 由插件后台再次核对脚本和 Tool，绝不把 Bearer Token 交给脚本。脚本仍须先保存本机报告，再明确处理远端成功或失败；报告只记录可验证的返回状态和链接，不含凭据。插件不代替脚本自动选 Tool，也不替外部 MCP 服务保证写入去重；脚本须为目标业务实现幂等确认。

网页悬浮 Logo 的红色脚标来自本机任务摘要，只统计新完成且未打开详情的任务；首次升级前任务默认已读。

## 邮箱与本机网页版 AI 输出边界（1.9.51）

脚本可显式声明 `@sellerfeeds-mail` 读取／发送或 `@sellerfeeds-web-ai` 文字／附件能力，经用户逐账号／网站授权后使用插件 API，MAIN world 均禁用。密码、OAuth、网页会话不得放入 Tool 输入、报告、日志或业务表。网页AI会话只在本机加密，邮箱连接凭据按账号加密存于官方 Cloudflare D1。邮件本机缓存不进入自动备份；脚本主动返回邮件内容／AI回答时，仍依该脚本真实输出结构保存一次任务一份报告，并沿用用户自有云备份规则，不自动抄送官方。接口和未验收项分别见 [邮箱说明](mail-foundation.md) 与 [本机网页版AI说明](local-web-ai.md)。


## 1.9.62 Warden 密码库边界

账号与两步验证使用用户自有 Warden Worker/D1；脚本可调用匹配网站的代填功能，不能读取密码或 TOTP 种子。原记事本、独立验证器和旧库保留，旧库可复制迁移但不删除。当前入口和真实验收状态以 `docs/development/warden-vault.md` 为准；本文旧版“暂无自动填充”只描述原库。


## 自动备份连接（2.1.75）

百度网盘和 HTTPS WebDAV 为同级完整备份目标；用户选择其一后，脚本、个人资料、任务、数据直接备份到该目标。邮件缓存单独管理。更换电脑先合并再上传，内容冲突保留副本而不覆盖本机；恢复的脚本、代理和定时规则不自动启用。WebDAV 必须支持 ETag，新电脑须先配置同一服务器。断开连接保留用户云端文件；无连接每日提示一次，可当天关闭。

### 兼容参数的界面展示

已停止使用但需要兼容旧任务的可选字段可以声明 `deprecated: true`。插件 2.1.86 起，手动、批量和定时表单不展示这些字段，官网参数介绍也不展示。字段仍保留在原始 Schema 和 JSON 输入中，旧定时任务与表单/JSON 往返不会丢失已有值；必填字段不会因为 deprecated 而隐藏。不能用字段名称猜测是否废弃，也不能借此删减仍有效的业务输入或输出。
## 3.0.12 本机补修（历史；身份适配在 3.0.34 移除）

旧版 Amazon 19 站点 1.2.1 的 `data.任务报告` 固定一条，商品数组位于 `data.商品明细`。同步/找回副本只改名称时，插件生成的「（同步副本） 八位小写十六进制 ID」及「（找回副本） 八位小写十六进制 ID」后缀不改变已审计的输出兼容身份；仍严格校验原名称、namespace、版本和 Tool。未知版本或自定义名称不自动套用，显式 v2 声明优先。

数据结果页签和全部范围显示已保存的数据批次数，一次运行产出多表或多行仍计一批。单批数据条数在表格和批次选项中说明。完成的空结果也是一批；未保存业务表的任务不计入数据批次。已有旧汇总须由用户主动「补全本机明细」，读取仍保留的结构化结果，不猜测 Markdown、不重新采集或回传，删除保护与原报告保持。

新增表格脚本继续使用通用 v2 声明：`recordsPath` 指向实际明细数组，每个元素保存为一行；字段类型与返回值匹配，使用 `rowIdentity:position` 或明确业务主键。v2 返回后由插件归档，不额外调用 `data.save`。这与脚本名称、业务维度和图表类型无关。只有一篇文本或汇总声明，不能保证自动拆成明细；使用 strict-output 和返回样例验证后交付。


### 3.0.34 声明是输出结构的唯一来源

插件不再根据脚本名称、namespace、版本、Tool 名或数据集名字替换 localData 或推导图表。旧版脚本需要作者更新 recordsPath/dataset 字段及显式 chartPresets，插件只验证和消费声明。既有归档、完整报告和已保存报表不删除；重新解析按当前有效声明执行，缺少明细路径应如实提示，不能静默猜测。历史样本的回归测试以明确作者声明作为测试输入，不在生产运行时保留身份适配目录。