2.1.79 本地候选开发规则（2026-10-15）

3.0.41：执行许可与入口依赖约束

• page 与 offscreen 执行均使用 user-script-access.mjs 的真实 chrome.userScripts.getScripts() 探测。不得只检查命名空间存在，不得为后台沙箱豁免用户的浏览器许可。
• 在接收、取得队列名额和适配器派发前校验；已接收记录的失败沿用原账号收尾能力。前台的可用状态只是提示，不能代替后台守卫。
• 所有创建网页入口的路径都必须使用 PAGE_LAUNCHER_FILES 的完整有序列表。单例复用须核对贴边控制器就绪；禁止只注入 page-pet.js 后把不完整实例当成已加载。
• 默认展示方式为 edge，既有显式 floating 保留；不声明 chrome_url_overrides，不再接管新标签页。

本机 3.0.40：功能行提醒与任务图片（2026-10-21，最新覆盖）

覆盖旧文中“前台任务页签常驻”的规则：前台仅功能、书签和工作台，任务以功能行右侧聚合提醒展示。未匹配网页但有活动任务、未读报告或失败待查看的脚本显示只读任务入口；不授予运行权限。数字按未读报告份数，运行和失败单独表达。进入工作台任务列表只定位不已读，实际数据/报告或失败详情阅读才确认。

Tool 通过 taskPresentation.image 显式声明任务图片，支持 selection、inputPath、outputPath，详细约束见 AI 开发手册“3.0.40 通用任务图片声明”。插件不按脚本或字段名猜图片、不修改已安装源码。本轮基于现行 3.0.39 目录与公共参数能力增量更新。

本机 3.0.39：官网全目录脚本与插件公共能力（2026-10-21，最新覆盖）

本轮按官网实际目录整理 8 个官方及 26 个社群脚本，更新源码已在本机完成，尚未远端发布。新版统一移除脚本内飞书/钉钉回传、表格凭据参数和远端写入回执；脚本返回业务数据，由插件数据中心统一配置和回传。下方自行写表范例只用于既有第三方脚本兼容，不得重新加入这 34 份新版脚本。

公共页面身份识别、输入预填、商品选择、账号守卫、任务执行及数据回传放在插件；脚本保留业务参数和采集逻辑。16 个明确单商品输入的脚本声明 pageContext、站点及字段映射：从打开表单的原 Amazon 商品/评论标签页填入 ASIN，用户可修改；不能明确识别时保留手填，不替双商品对比或 ASIN/关键词混合查询猜测角色。换变体、导航、切号后不提交旧页面目标。

旧任务 JSON 若仍带已删除的回传字段，须按新表单重新保存，不静默删除配置。用户已安装脚本不会由此次本机文件更新自动覆盖。详细范围和验收见 docs/development/catalog-modernization-3.0.39.md。

本机 3.0.31：悬浮窗及交叉调用审查（2026-10-20）

现行源码仍在 /Users/vestiter/Documents/智多星/script，禁止旧树构建覆盖。悬浮球与贴边关闭统一卸载私有 iframe、清理选择和撤回页面让位，重新打开按需加载；保留同窗口展开状态和仅主动关闭。跨标签折叠读回不取消已开始的悬停展开；pet 单例 21；隐藏标签暂停入口身份扫描/未读读取，回到页面重新核对，迟到未读响应按请求、账号、URL 与销毁状态作废。

前台运行准备绑定原账号、表单代数及页面目标。切功能、切 Tool、离开表单、关闭或换账号取消尚未提交的连接引导，清理其定时器/监听并关闭本次引导窗；已经提交的任务按原任务引擎执行，旧响应不能占用新账号或改写其他表单。PAGE_LAUNCHER_RUN 必须带原 owner，后台独立核对并把本机实际 license 传给原任务引擎重验，非信任调用方自报 license。账号变化立即清旧参数/状态/列表；参数或商品选择声明变化先撤掉旧表单并提示重新打开。完成卡片按其真实 historyId 打开结果。分类列表单次分组，任务按脚本预建索引，移除重复分类读取/逐脚本全量筛选。

网页就绪不再自动打开第二个账号选择小窗；账号自动填充仍只按用户原有 opt-in，手动“填写账号”独立窗和输入框旁提示保留，不因保存过账号就宣称网站已登录。关闭标签只撤销该标签的填充临时票据与待办，账号切换仍清全部；不读取真实凭据。

只更新原两个本机加载目录并保留 inode/key/marker；不改 74 份示例或用户已装脚本，不重载日常 Chrome、不发布 GitHub/官网。证据见 output/patch-3.0.31 与隔离浏览器记录；合成账号/商品/RPC 验证不冒充真实网站或原生扩展端到端。详细审查见 docs/development/launcher-code-audit-3.0.31.md。

本机 3.0.30：通用密码读取与本地文件夹备份/恢复（2026-10-20）

现行源码继续在 /Users/vestiter/Documents/智多星/script，禁止旧树构建覆盖。密码保存读取与自动填充检测分离：显式读取支持密码明文切换、语义明确的密码文本框、只读已有值、动态表单、开放 ShadowRoot 与同源 iframe，不按网站域名适配，不改变旧密码向网页填充的严格守卫。新书签保留真实值/空值和状态，可在原私有编辑器主动重新读取；重试仍重验原 URL/活动标签/权限/账号/设备，普通读取一次性，迟到结果不覆盖用户输入。公开登录页只检查结构；未读取真实凭据。

设置“连接与备份”新增与云盘同级的本地备份，用户选择文件夹并设独立恢复密码后开启，有变化才自动写入。原生目录句柄仅在扩展 IndexedDB，不进 URL、消息、脚本、云同步或备份。按账号在所选目录的 SellerFeeds-Backups 子目录保存历史；数据库、任务、资料/配置/凭据和已缓存邮件分片加密，脚本附件原格式保存并校验。只备份插件已有内容，不读任意下载路径、不补远端下载。单次业务数据与脚本附件各 2 GiB、单附件 512 MiB、单邮箱缓存 64 MiB；超限/权限/磁盘/源数据变化不假报成功。最终清单最后写入并读回校验，未完成目录不作为恢复版本；不自动清历史。

恢复先选择原文件夹与历史版本，完整校验分片/附件/账号/结构并预览，确认后合并缺失记录，保留本机已有内容与删除守卫，不自动启用脚本或原授权。预览五分钟、绑定原账号和目录 revision，应用前重验清单与附件；部分恢复如实提示阶段并可重复补入。自动开关与手动备份独立；停用/移除不删文件。无需云连接，本地权限失效只由用户重新授权，浏览器关闭不能后台写盘。

仅本机更新原两个加载目录，保留 inode/key/marker；不改示例/用户已装脚本，不重载日常 Chrome，不发布 GitHub/官网。验证与旧包见 output/patch-3.0.30；隔离 HTTP/合成账号和原生 OPFS 不是用户真实电脑文件夹选择或真实登录端到端。

本机 3.0.29：书签紧凑位置与真实密码状态（2026-10-20）

现行源码在 /Users/vestiter/Documents/智多星/script。页面/分类/小组使用共享三列样式，窄书签编辑窗也同一行。管理页密码用真实输入值显示遮罩，并区分已保存、网页获取待保存、用户输入、加载/失败与空值；不默认写假星号。前台新建 HTTPS 书签在原完整编辑器中，一次性读取原活动网页当前同源登录表单；仅精确账号/URL/标签/iframe 授权的私有编辑器可消费两分钟内权限，异步重验原网页、权限、设备与账号，过期/导航/切标签/切号停止。URL、父窗口与 session 中不传/存密码，读取不落库，明确保存才写本机加密库。原有编辑、普通工作台新增与其他小工具不捕获；迟到响应不能覆盖用户已输入内容。旧登录保存窗仍只取得存在标志，账号 ID 不再冒充已存密码。浏览器自身密码库不读取，网页已经清空/不安全的表单不假报已获取。

保留原账号/密码/OTP/备注、位置、图标、Passkey 和本机保存/备份边界，保留 3.0.28 无脚本默认书签及前台入口规则。仅更新两个原本机目录，保留 inode/key/marker，不改示例或用户已安装脚本、不重载日常 Chrome、不发布 GitHub/官网。检查使用生产模块和合成账号/表单/Chrome 边界，不访问真实密码。详见 docs/releases/3.0.29.md 与 output/patch-3.0.29。

本机 3.0.28：无匹配脚本网页保留入口（2026-10-20）

现行源码继续在 /Users/vestiter/Documents/智多星/script。修复入口注册仍依赖已安装脚本匹配范围的遗漏：launcher-registration 按 chrome.permissions.getAll 当前已授予的 HTTP/HTTPS origins 注册顶层前台入口，并补注入已打开的授权普通网页；零脚本和不匹配页面也有入口。路径按 Chrome 网站权限语义归一化，<all_urls> 仅展开 HTTP/HTTPS，未授权 HTTP、内部页、file 等不扩权；权限变化沿原监听重建，读权限失败保留旧注册，单页受限不阻塞其他页。不新增权限申请、不放宽用户脚本注册或运行/商品选择范围。

pet 20：已注入的 HTTP/HTTPS 入口显示不再依赖脚本数量。无匹配脚本页面初开默认书签；即使分区设置此前隐藏书签也只在当前界面补出，不改持久偏好。SPA 从功能页切到无匹配页面时回书签；日常刷新不强迫离开用户已选任务/书签。保留任务、工作台、278px 连续列表、增强专用快捷开关、仅主动关闭与同窗口会话状态。浏览器禁止注入的内部页/商店等仍受 Chrome 限制。

只更新两个原本机加载目录，保留 inode/key/marker；不改 74 份示例或已安装脚本、不重载日常 Chrome、不发布 GitHub/官网。验证使用生产注册模块/前台与合成浏览器/RPC/权限边界，不冒充实际 Chrome 扩展和真实网站端到端。见 docs/releases/3.0.28.md 与 output/patch-3.0.28。

本机 3.0.27：连续列表、增强声明与原生侧栏退役（2026-10-20）

现行源码在 /Users/vestiter/Documents/智多星/script，本轮只更新本机。前台功能/任务/书签移除分页控件，功能和书签完整连续排列，任务按原游标在列表底部继续加载、按 ID 去重；刷新保留已读取范围，账号/切页迟到响应失效，错误保留原内容并提供重新读取。任务仍只展示未读及排队/运行，不提前确认已读。保留 278px 贴边宽度、悬停展开后仅主动关闭和同窗口展示状态守卫。

普通脚本没有前台快捷开关。仅源码元数据头显式声明一次 @sellerfeeds-page-enhancement {"enabled":true} 的页面增强脚本显示；畸形、重复和未知键拒绝安装。存储从源码派生标志，私有开关服务及原 setScriptEnabled 短存储事务重新核对声明，不能伪造缓存字段。普通工作台启停保持；旧脚本须作者主动更新，不猜名称、Tool 或执行模式，也不改任何已安装脚本。开关仍全局，旧 DOM 撤销仍由另点刷新当前页。

移除浏览器原生 sidePanel 的设置、manifest 权限/入口、后台 RPC 与分发页面；旧 sidebar 设置归一化 edge，保留其他偏好。工具栏图标打开工作台。悬浮球及贴边面板仍可切换，未改任务引擎、商品声明、MCP/账号/权限和输出契约。隔离 HTTP 验证使用生产 UI 和合成 RPC/浏览器边界，不冒充实际 Amazon 端到端。保留加载目录 inode/key/marker，不重载日常 Chrome、不发布 GitHub/官网。

本机 3.0.26：常驻贴边、全局快捷启停与窄面板（2026-10-20）

现行源码继续在 /Users/vestiter/Documents/智多星/script。用户最新确认覆盖 3.0.25 的自动收起：悬停/点击/原商品拖入展开后常驻，移开、滚动、失焦、拖动结束或返回功能列表均不关闭；只保留 160ms 入口延迟并在离开/隐藏/销毁时取消。移除自动关闭计时器、滚动续期监听、固定按钮及其焦点/选择保持消息。用户主动关闭继续卸载 iframe、结束选择和撤回正文让位；账号/方式/停用与跨标签权威恢复仍按原守卫清理。pet 单例 18。贴边宽度由 370px 缩至 278px，保留折叠入口 24px 滚动条间隔；不控制浏览器原生侧栏的窗口宽度。

各功能行右侧增加与工作台一致的全局启停开关。列出当前网页匹配且已有网站权限的功能，包括停用项及无 Tool 的页面增强；停用后保留行，运行/菜单不能使用，重启用无需从工作台找回。前台入口注册覆盖已安装且已有权限的匹配范围，不因全部功能停用而丢失入口；实际执行/商品选择继续仅接受启用且授权的脚本。原 setScriptEnabled 以账号短存储队列读取最新记录、校验可选 expectedEnabled 后窄修改，保留其余字段及注册/沙箱失效逻辑。

快捷启停与独立刷新只允许私有 launcher iframe 或原生侧栏适配器，复核当前账号、活动原标签、URL/公开 contextKey、当前授权列表与明确布尔目标；串行和状态预期拒绝迟到反向覆盖，不返回源码/配置。关闭不能通用撤销旧脚本已改 DOM，用户确认显示「刷新当前页」按钮而非自动刷新；一次性短期凭据绑定原账号/页/URL/脚本状态，仅明确点击才调用原页 reload，不刷新其他标签。普通 offscreen 工具不提示无必要刷新。未更改脚本声明、采集结构、用户已安装源码或结果未读规则。

保留同窗口会话展开/折叠共享、原权限和手动运行守卫，底部翻页与紧凑行距保持。两个原目录原位更新并保留 inode/key/marker，不重载日常浏览器、不发布 GitHub/官网。验证以生产组件的隔离 HTTP 和合成浏览器/RPC 边界为准，不冒充真实 Amazon/原生侧栏端到端；未测量整插件内存或声称常驻更省内存。详见 docs/releases/3.0.26.md 与 output/patch-3.0.26。

本机 3.0.25：滚动条避让与悬停宽限（2026-10-20）

现行源码继续在 /Users/vestiter/Documents/智多星/script。折叠入口从最右边向内留出至少 24px（并考虑 safe-area），点击区域由 20px 加宽到 24px、保留 64px 高度；独立圆角边框，不与浮现的浏览器滚动条重叠。只移动折叠入口，不修改网页滚动条、正文让位宽度或展开面板布局。pet 单例为 17，原孤立样式清理与页面宽度恢复保持。

普通悬停退出由 500ms 改为 2500ms。已打开且正在等待悬停收起时，网页 wheel/scroll 活动从最后一次活动重新计时；覆盖滚轮、惯性滚动、键盘/中键实际滚动和拖动滚动条。监听为被动、可中止，不拦截滚动、不新增轮询或业务请求，不唤醒已关闭入口。返回面板取消等待，商品选择、参数焦点、拖动和固定继续保持，显式关闭/切方式/销毁立即清理；隐藏标签和跨标签继承守卫不变。

保留同窗口、账号与展示方式隔离的展开/折叠同步、底部翻页、紧凑列表与商品选择/手动运行/未读规则。两个原目录原位更新并保留 inode/key/marker，不修改已安装用户脚本，不重载日常浏览器、不发布官网/GitHub。验证使用隔离 HTTP 的真实生产组件与合成浏览器/RPC 边界；22px 顶层条是覆盖型滚动条模型，不冒充读取或验收真实 OS 滚动条，也不是实际 Amazon/原生侧栏端到端。详见 docs/releases/3.0.25.md 与 output/patch-3.0.25。

本机 3.0.24：贴边面板残留空白修复（2026-10-20）

现行源码仍在 /Users/vestiter/Documents/智多星/script。已在隔离生产组件复现：旧扩展实例的闭包丢失、DOM 留在网页时，新入口移除旧面板，但 3.0.20–3.0.23 的独立让位样式仍在；面板折叠后 1360px 网页仍被压到 990px。此为布局生命周期缺陷，不能归因为已证实的内存不足。

page-dock 的文档样式现在挂在私有面板宿主的 light DOM，随宿主移除立即失效；新实例使用 UUID 作用域的独立根/固定元素属性，不覆盖网站原有通用属性。page-pet 单例升为 16，替换入口前独立清理旧实例残留；支持前版空样式标记与确切根 token/选择器的恢复，也支持新样式或根标记的恢复，不依赖旧 JS 闭包。正常收起/关闭/切方式/销毁仍撤回样式、标记和观察任务，宿主已断开时不重新保留布局。

保留 3.0.23 的同窗口、账号、展示方式隔离的会话展开/折叠共享及真实活动顶层写入守卫；只共享展示标志，不复制表单、商品或报告。未新增轮询或业务请求。紧凑列表、底部翻页、未读与商品选择规则不变。仅本机补丁，两个原目录原位更新并保留 inode/key/marker；不修改用户脚本、不重载日常浏览器、不发布官网/GitHub。验证为隔离 HTTP 的生产 DOM/样式和合成浏览器/RPC 边界，不能冒充真实 Amazon/原生侧栏端到端。见 docs/releases/3.0.24.md 与 output/patch-3.0.24。

本机 3.0.23：翻页栏置底与跨标签展示状态（2026-10-20）

现行源码仍在 /Users/vestiter/Documents/智多星/script。前台功能/任务分页页改为顶部工具区、可独立滚动的列表、底部翻页栏三段布局。浮窗与贴边 catalog/reports、原生侧栏 tasks 的翻页栏占独立底部空间，不使用覆盖列表的绝对/固定定位。短列表仍置底，长列表只滚动内容；窗口高度和原生页脚变化由 flex 布局适配。原生功能列表本来无分页，不新增按钮。

手动翻页与功能搜索重置对应列表 scrollTop，自动刷新不主动重置；页码、游标、查询、条目顺序、已读/任务动作和账号/网页/权限边界不变。任务入口常驻，无任务时沿用隐藏无用翻页的规则。书签仍用原 main 滚动区和实际高度图标分页；表单/Passkey 的原滚动方式保持。上一版紧凑行距、行内焦点和完整名称 tooltip 保持。

同一浏览器窗口的前台展开/折叠状态按当前账号和展示方式在本次浏览器会话内共享，保存于受限 storage.session；普通网页无存储读取通道。A 展开后激活 B/B 新加载时恢复展开，A 折叠后 B 恢复折叠；服务工作线程重启可恢复，但不上传账号备份、不同窗口独立。只同步布尔展示状态与版本，不同步表单/选中功能/商品清单/任务目标/私有内容。当前真实活动顶层标签才能写；后台旧标签的延迟折叠、旧账号/网址/展示方式响应不能覆盖。切标签时取消悬停折叠，继承的展开状态保持到用户实际进入/离开面板或主动关闭；原固定、输入和选择保持规则不变。原生浏览器侧栏继续浏览器原有窗口行为。

仅本机补丁，两个原加载目录原位更新、保留 inode/key/marker；不改用户脚本、不重载日常浏览器、不发布官网/GitHub。隔离 HTTP 合成组件检查不等同原生侧栏/真实 Amazon 端到端。见 docs/releases/3.0.23.md 和 output/patch-3.0.23。

本机 3.0.22：前台导航行距与焦点风格统一（2026-10-20）

现行源码仍在 /Users/vestiter/Documents/智多星/script。侧边/贴边/悬浮前台的功能列表、脚本菜单和任务标题按实际工作台导航统一：35px 行高、5px 垂直内边距、8px 图文间距、24px 图标与 12px/20px 常规文字，分类标题 26px/11px。移除旧多行卡片与跨两行图标占位、行底分隔线和外阴影。长名称单行省略，原完整文本与安全 title 保留，进入功能后显示全名；不是截断源码或记录。焦点为行内轮廓，滚动容器保留定位内距和滚动条空间，不让选中边缘/状态与名称相互遮盖。

原生侧栏操作数说明退到原行 tooltip，运行按钮与页面菜单保留。任务标题和状态同一紧凑行，编号/时间与结果/重试/任务进程操作在下方紧凑详情行，失败说明保留，窄窗允许详情换行。仅调整展示与任务 HTML 容器，不改 RPC、查询、重试/已读、账号/原活动标签/URL/声明/权限/revision/手动提交或商品识别。任务入口常驻、书签图标及其实际高度分页不变，上一版贴边让位/隐藏辅助层修复保持。

仅本机补丁，原两个加载目录原位更新并保留 inode/key/marker；不改用户脚本、不重载日常浏览器、不发布官网/GitHub。隔离 HTTP 组件使用实际工作台 CSS 做尺寸参照，不等同真实 Amazon/原生侧栏端到端。见 docs/releases/3.0.22.md 和 output/patch-3.0.22。

本机 3.0.21：贴边隐藏浮层与固定宽度页面修复（2026-10-20）

现行源码继续在 /Users/vestiter/Documents/智多星/script。用户报告的 Amazon 快捷键层已按同类屏幕外固定面板复现：旧让位逻辑会将 left:-10000px 的辅助层拉到 0。page-dock.js 现在只调整原本可见且与视口相交的固定控件，两轮调整使用同一可见集合；屏幕外、隐藏/透明/裁剪/aria-hidden/inert 节点不拉入。网站自己主动打开和关闭辅助层仍由网站控制，不删辅助功能、不发送快捷键或抢焦点。

功能列表移除「当前页面可用 / 更多本站脚本」两项及其范围筛选；原匹配、启用、网站权限内的 ready/manual 功能合并按置顶/自定义分类展示。任务页签继续常驻、内容只显示原未读与排队/运行记录，原商品显式声明与账号/标签/URL/权限/revision/手动提交守卫不变，不修改已安装脚本。

正文先以剩余宽度正常重排。固定宽度/100vw 内容仍溢出时，只对网页 body 使用可撤回 CSS zoom 适配剩余区域，私有插件 iframe 在 body 外保持原大小；商品勾选控件反向补偿缩放。固定控件按实际缩放坐标让位，屏幕外固定浮层不参与正文宽度测量。DOM/可见性/加载变化和窗口缩放重新核对，收起/关闭/切模式/销毁撤回样式和标记，保留原 inline、原 zoom 与历史属性。不伪造 viewport/innerWidth/媒体查询；这仍是网页内适配，并非浏览器原生侧栏改变视口。

仅本机补丁，原两个目录原位更新、保留 inode/key/marker；不重载日常浏览器，不发布 GitHub/官网。隔离 HTTP 合成验证覆盖复现模型，不能当真实 Amazon 或原生 sidePanel 端到端。见 docs/releases/3.0.21.md 与 output/patch-3.0.21。

本机 3.0.20：任务入口常驻、贴边让位与商品识别（2026-10-20）

最新用户纠正覆盖 3.0.19：任务页签始终保留，不按未读/运行数量隐藏，也不因清空列表强制跳回功能。内容仍按原未读基线展示未读与排队/执行中记录；空时只显示空态，隐藏无用翻页，历史在工作台。功能名称与工作台导航统一为 12px、20px 行高、常规字重；工作台按钮仅显示「工作台」并加粗。

贴边模式展开由 page-dock.js 以可撤回样式为正文预留面板宽度，常见视口固定导航/控件同步让位；收起、关闭、禁用、切模式和销毁撤回。保留原 inline 样式与历史 DOM 属性，变换祖先内固定元素不重复位移。网页内布局让位不等于浏览器原生 viewport 改变，不伪造 innerWidth 或媒体查询；写死宽度的内容可在其页面区域横向滚动。原生侧栏和悬浮球继续可选，选商品保持展开规则不变。

amazon-products.js 为通用公共 DOM 识别器，支持 data-asin/data-csa-c-asin、推荐轮播、排行/榜单、购物车及同站商品链接的单一身份卡片。当前商品/评论主体与推荐商品可并存；混合容器继续拆分，隐藏或不可见节点、外站链接、纯文本和重定向参数不猜。勾选控件不挂到商品链接/操作按钮内部，避免点选时导航。仍只给显式声明 selection/inputs/sites 的 Tool 使用，账号/原活动标签/URL/权限/声明/revision/手动运行/批量边界不变。Alexa 与其他示例/用户已安装脚本源码不修改。

现行源码继续在 /Users/vestiter/Documents/智多星/script。仅两个原本机目录原位更新、保留 inode/key/marker，不重载日常浏览器、不发布官网/GitHub。隔离 HTTP 合成验证不能当真实 Amazon/原生侧栏端到端；不绕过此前扩展协议工具限制。见 docs/releases/3.0.20.md 和 output/patch-3.0.20。

本机 3.0.19：商品选择稳定性与前台分类列表（2026-10-20）

现行源码继续在 /Users/vestiter/Documents/智多星/script。商品选择功能从进入开始保持贴边面板展开，不以商品数量判断；返回功能列表/切页签/明确关闭结束选择并释放保持状态。普通浏览仍按悬停收起，输入焦点与用户固定独立。只传选择流程布尔标志，原 iframe 来源检查保持。动态商品卡片内层替换时重新挂载原闭合 Shadow 控件；连续 DOM 更新用有界调度，旧发送/轮询迟到失败不清理新会话/新 revision；只恢复仍通过原守卫的会话控件，不清空已确认清单或自动提交。原账号、活动标签、URL、声明/权限、选择 revision 与手动运行边界不减弱；旧脚本继续须自行显式声明，不猜参数。

功能与报告改为工作台相同的置顶/自定义分类单行列表，工作台入口为明确按钮。用户确认前台任务只展示未读完成/失败与排队/执行中任务；无这两类记录隐藏任务页签，已读历史仍在工作台，导航不提前确认已读。查询沿用原未读基线、摘要库与账号守卫，不读业务行。书签保留图标，以实际宽高、列数与图标尺寸计算整行容量，搜索/分类/缩放/尺寸变化重新分页，不固定每页 24；原编辑/小工具能力保持。

仅本机补丁，不发布 GitHub/官网，不重载日常浏览器、不改用户已安装脚本。两个原加载目录原位更新保留 inode/key/marker；测试以生产模块的合成 HTTP 边界为准，不冒充真实 Amazon/原生 sidePanel 端到端，也不绕过此前扩展协议访问限制。验证见 docs/releases/3.0.19.md 与 output/patch-3.0.19。

3.0.18 紧凑前台与贴边悬停（本机候选）

网页入口增加 edge，保留 floating/sidebar 且不改变旧选择。page-edge.js 是隔离世界的展示控制器，由 page-pet.js 复用原插件来源 page-launcher iframe。悬停展开、离开延迟收起；软收起不重建 iframe、不清商品/普通输入。表单编辑、原生商品拖动或固定时保持；明确关闭卸载 iframe，选择由原 pagehide 清理。参数、秘密、账号和数据不发送到宿主页面，悬停/拖动不运行任务。Chrome 原生侧边栏仍按其原 API 与用户手势使用。

前台顶部只保留功能、任务、书签与工作台一行，书签搜索/加入/小工具紧凑排列。数据菜单、批次列表及其限定 RPC 已移除，业务存储不变。最近任务摘要包含已读和执行中任务，以 queryTaskHistory 的账号范围和游标读取；不传输入、报告或业务行。查看结果仍在插件页根据任务解析真实批次，保留可见行已读规则；浏览不需要通知目的地。

商品选择仅对脚本显式声明开放；旧脚本由作者按统一规范修改并由用户更新，不提供字段猜测或兼容绑定。Alexa 1.4.3 测试文件与正文保持，只有主动使用带声明版本才能看到网页商品选择。安装文件不等于用户浏览器的旧源码已被更新。

3.0.17 侧边栏入口与批次导航（本机候选）

侧边栏与悬浮窗「数据」先按功能列出本机数据批次，列表不展示业务明细。每批「查看数据」将 scriptId、canonical runId 与关联 taskId 交给原工作台入口，实际表格与已读判断仍在插件页。批次仅指已有本机数据归档，不把商品行数当批次，成功空结果保留；纯动作/仅附件任务仍可在任务/附件入口查看。

网页商品选择仍要求脚本自己在 pageContext 中显式声明 selection/inputs/sites。未声明的旧脚本必须由作者修改并由用户更新，插件不猜参数、不提供兼容绑定、不自动改写用户源码。Alexa 1.4.3 示例已有 US 选择声明；仅重载扩展不会更新用户安装的脚本。连接失败保留重试，无法识别商品时提示手动填写。

书签与小工具由侧边栏限定消息复用原 launcher-editor 私有小窗；不向网页开放编辑消息。原账号、标签/网址、活动标签与脚本权限检查保持。

3.0.16 网页商品选择（本机候选）

声明接收商品身份的 Tool 可在侧边栏、悬浮窗中使用通用待处理清单：进入功能后勾选网页商品，或拖入商品链接/图片；勾选多个后拖任意已选商品会携带整组。重复 ASIN 自动去重，可以移除或清空。单选提交一个手动任务，多选沿现有串行批量队列拆分任务，共用其余参数。选择、拖入和进入功能均不运行；必须核对后点击运行。数据结果仍在插件页。

Tool 在既有 pageContext 内显式声明，例如 Alexa 美国站的单值 ASIN 输入：

{"kind":"amazon-product","pageTypes":["product","reviews"],"inputs":{"asin":"amazon.asin"},"selection":true,"sites":["US"]}

选择层目前识别 Amazon 搜索结果卡片 data-asin，及能明确识别当前 ASIN 的商品/评论页。仅支持白名单的 Amazon HTTPS 站点；sites 可按脚本实际业务限制，不写则为已有 19 站点。输入映射只接受 Tool Schema 中非敏感的顶层字符串字段，来源为 amazon.asin、amazon.site，且必须映射 ASIN。未声明的脚本保持原手动表单，不按字段名称或脚本标题猜测。识别不到的页面继续手动填写，不声称支持所有广告卡片或页面版本。

每次最多 100 件；不把多个 ASIN 拼到单值输入。参数、秘密和结果不放入宿主页面或拖动载荷；页面只持有公共商品信息与短期选择令牌，插件来源面板展示清单。后台核对原账号、原标签/网址、当前活动标签、网站权限、Tool 声明及选择版本；切换功能、账号或网址后清除旧选择，不自动换到其他目标。采集逻辑和 v2 输出契约保持。源码示例已声明不代表用户已安装旧脚本自动更新；须由用户主动更新脚本声明。

3.0.15 数据统一在插件页展示

侧边栏与悬浮窗只提供任务状态和跳转入口，不读取或渲染数据表、汇总明细或原始报告 JSON。点击某次任务，后台根据当前账号的 taskId/dataRunId 解析真实批次，再由插件页复用原通用数据结果与已读规则。通用数据按钮打开插件页的数据结果，继续所选功能；脚本 SDK、输出结构和实际存储不变。

3.0.14 前台展示方式（本机候选）

新增浏览器原生侧边栏，与悬浮球由网页入口设置选择。运行参数仍由 Tool Schema 生成，原任务调度、能力授权和 v2 结构化输出保持；脚本不需要适配侧边栏。侧边栏只使用限定来源的 SIDE_PANEL 消息，不向宿主网页开放管理页或任务数据接口。界面不代表原生 Chrome/Edge 托管已完成用户端验收。

3.0.9 本机修复：历史表按原数据表身份初选明细；最新报告保留整次任务的行；数据结果「更多 → 完整任务详情」复用原任务弹窗。旧汇总只在用户点击补全时按保留报告恢复，不重新采集或回传。MCP 历史数据授权在设置中维护，默认关闭，账号与字段范围继续校验。官网/GitHub 是否发布以发布记录为准。

3.0.8 通用工作台（2026-10-19）

功能导航支持本机账号范围的置顶与自定义分类，不要求脚本额外适配。数据结果复用完整原生表格；报表依真实字段通用配置，名称与运行范围通过下拉框选择。数据管理及本次附件位于更多，单次任务查看仍核对真实任务并记录已读。功能配置沿用原资源与权限边界，表格/云盘设置由插件管理，脚本采集、参数和结构化输出契约不因 UI 改动而变化。

3.0.5 功能云盘回传（2026-10-19）

功能配置 → 云盘回传提供当前功能的独立开关与文件历史。用户已连接的网盘可直接用于本功能，无需打开全局文件备份，也不会开启其他功能；没有连接或需要处理权限时在当前页说明，用户另点连接入口。关闭保留本机和已上传文件。开关只表示回传选择，成功状态和时间取自实际文件回执；恢复文件仍遵循不自动重传规则。脚本接口和输出协议不变。

SellerFeeds 3.0 界面入口（2026-10-19）

功能按左侧已安装项进入，顶部五个页签分别处理介绍、任务、数据、附件和报表。当前功能配置按脚本 ID 与账号隔离适用资源和表格连接；参数继续遵循原 Tool Schema，不要求给新 UI 增加业务适配。全局连接在齿轮设置中维护，个人中心只展示资源。准备连接、启用回传、任务执行、本机保存、外部回传和通知状态分别确认。files.save 的活动身份仍为 execution task，归档附件按可信运行历史 ID 关联；不开放秘密读取接口。

2026-10-17：统一结构化输出和数据中心回传

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

新增表格型功能统一使用 @sellerfeeds-local-data v2，声明明细路径、表、字段类型、空值和行身份。数据中心据此逐行保存；原始报告另行保留。禁止只返回一篇汇总文本代替实际明细。v2 由插件自动归档，不重复调用 data.save。纯动作/附件功能可明确关闭数据中心保存。

开发者须提交输出样例并通过 node scripts/verify-userscript.mjs --strict-output --output-fixture <result.json> <script.user.js>，另验收真实归档、查询、导出和重复解析。完整规范见 [数据输出契约](development/data-output-contract.md)，可运行示例见 [结构化商品输出](../examples/structured-products.user.js)。下面旧 SDK 公约仅用于兼容，不覆盖 v2。

本地候选已升级为数据中心管理常规采集结果的表格绑定、字段准备、批量追加和失败重试，普通任务通知依据数据中心的本次写入回执选择链接或 Excel。新脚本默认完成采集、完整本机保存及报告；不必重复填写回传连接或实现写表。详见[数据保存与输出公约](development/data-output-contract.md)和[飞书写表公约](development/feishu-contract.md)的当前章节。

脚本作者主动声明、获授权的 HTTP 与 table.feishu.append/update 保留，原生输入不能隐藏；同一输出须明确由脚本或数据中心负责，当前尚无自动防双写机制。脚本通知标志不再决定普通通知路径，历史参数与元数据仍兼容解析。受保护连接密钥只由插件代用，脚本间调用仍停用。

第三十三轮补齐历史批次唤醒、暂停积压、独立通知重试、原会话回复与保存失败摘要。安装和发布共用非执行式语法门禁，公约随包与在线内容按输出契约匹配。13 个仓库维护的生成模板默认只落库，另有明确使用脚本直写的生成器保持兼容模式；不等于官网所有脚本已经迁移。详见[第三十三轮记录](development/product-local-preview-iteration-33.md)。

当前候选包含邮件并入网站书签、常用配置从数据中心进入、移除运行窗通用结果写入壳等变化。脚本实际需要的业务参数与 SDK 用途授权继续展示。当前手册和本地代码不代表官网、已安装插件及个人 Worker 自动升级；发布前核对各自版本与真实验收。

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

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

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

2.1.65 历史开发规则（2026-10-08）

本节是当前行为的优先说明。本文保留的旧版本记录用于追溯；旧记录中的“本地预览／不发布”、独立记事本或两步验证菜单、Cloudflare 个人资料主库、旧资料恢复入口及逐项旧服务配置流程，不作为当前开发要求。实际官网发布结果以发布记录为准。

• 资源与输入：常用配置管理普通参数与受保护服务连接；网站书签混放书签、两步验证和记事本，共用分类，账号按稳定 ID 关联；邮件在邮件中心。工具业务字段默认表单，JSON 在高级入口；按具名用途绑定原资料，不复制密码、令牌或配置。禁止把真实账号、地址、配置 ID 和密钥写进可分享脚本。
• 数据归属：本机是资料主库，百度保存加密个人资料备份；任务／数据可归档到百度或 WebDAV，邮件单独管理。官方加密托管恢复密钥，不能声称零知识或多设备实时双向同步。Cloudflare 按需提供 MCP、邮件转接和机器人服务，普通资料保存不依赖个人 D1。
• 脚本运行：Chrome 138+、MV3。普通 MAIN grant none、USER_SCRIPT GM API 与显式 sellerfeeds 内置任务分开授权；没有内置任务声明的脚本不能取得任务 SDK／RPC。已实现的 GM_* 与 GM.* 按 grant、来源、账号、启用状态检查，不宣称完整 Tampermonkey 兼容。SDK 按 Tool 功能、用途与原绑定逐次检查；script.call 仍停用，普通参数可被授权脚本读取，受保护凭据只由插件代用。
• 邮件：本机摘要查询与正文下载分开，正文保留 text/html，纯文本为默认阅读方式；附件按需获取，失败不清除已有正文。脚本使用现有 mail.* 功能与任务文件引用，不从阅读器 DOM 抓取凭据。HTML 在独立不透明沙箱渲染，外部图片需明确加载，不绕过授权或验证码。
• 安装与更新：Windows／macOS 共用 ZIP；只检查版本和经 SHA-256 校验后下载，不自动解压、覆盖或重载。nativeMessaging 与本机助手退出运行包，保留的旧源码和测试只供追溯。官网提供商店及 ZIP 入口。
• Passkey：使用浏览器 webAuthenticationProxy 安装权限声明，显式为当前 HTTPS 标签准备两分钟；来源由浏览器注入且重复核对，不接受网页伪造注册／签名消息。可信扩展弹窗验证独立密码，私钥 AES-GCM、PBKDF2-SHA256 600000 次；软件 ES256、none attestation、零签名计数器与备份资格，不伪装硬件证明。Passkey 队列在个人资料恢复锁最外层，取消／过期／切号后不签名。普通 GM、SDK、MCP 不提供私钥或通用签名接口。
• 验证与交付：区分自动测试、合成浏览器、隔离扩展、真实用户端到端和生产发布证据；不得把其中一种写成另一种。真实用户覆盖更新仍需验收。个人 MCP 新代码只进入安装包，不代表用户已有 Worker 被自动升级。所有源代码和设备文件按用户可检查处理，安全不依赖隐藏实现。

---

备份传输与残留回收（2.1.33，本地预览，最新覆盖）

个人资料新快照按内容边界分片、逐片压缩和 AES-GCM 加密。分片独立随机身份，快照清单带认证标签；同账号／同密钥下可复用经过远端读取、解密和明文摘要校验的分片。缓存与上传日志仅存本机设备加密库，不进入资料包。换恢复密码不复用旧密钥分片；旧格式备份正常恢复，未增加旧版专用入口。每份快照列出全部所需分片，不依赖逐版差分链。仍有 32 MiB 个人资料限制，首次新格式备份全量上传，重复内容并不保证固定节省比例。

新任务／数据归档先压缩再加密，压缩类型纳入认证，恢复限制解压大小；业务归档仍为完整归档，不宣称逐行增量。百度读取复用已列出的文件条目，仍核对 filemetas 路径、下载大小及上层密码学完整性。

个人资料上传先写两小时保护标记，单次上传超过一小时停止；历史清理发现活动上传暂缓。复用只限创建未满 23 小时的分片，或仍有创建未满 29 天的已确认快照保护的分片，避开 24 小时残留回收及 30 天历史到期窗口。上传前记所有权，删旧清单前记分片清理意图；中断后可重试。只清理本机日志确认、超过 24 小时且没有清单引用的残留，未知文件不清理，日志最多 4096 项，超出失去追踪的文件保留。目录变化／切号／清单损坏停止删除，不保证跨设备原子提交；依赖正常设备时钟。

历史清单每次最多并发读取三份，复用目录结果，避免每次下载重扫目录。无资料变化时最多每六小时维护一次，不另上传快照；清理失败与已完成备份分开显示。正常恢复仍分阶段补缺，无整库回滚。没有扩展 WebDAV 个人资料或逐条找回范围。仅本地模拟与隔离浏览器验证；真实网盘、真实安装、跨设备与实际网站／邮箱验收仍待用户配合，不部署或发布。见 docs/releases/2.1.33-local.md。

备份保留、误删找回与业务归档加密（2.1.32，本地预览，最新覆盖）

个人资料历史及同账号同类别的自动任务／数据归档，在新备份确认后保留最近 30 天且至少 10 份，每次最多清理 20 份过期版本。手动业务归档不自动清理；未知文件和无法证明归属的孤立分片不清理。清单损坏、最新副本无法确认、目录变化或切号停止清理，清理失败与备份成功分别显示。不是多设备事务删除或完整孤块回收。

个人资料提供历史条目预览和勾选找回，生成新 ID，保留已有资料与删除记录；脚本改为新身份、停用且清空绑定，账号填充关闭，AI/MCP/邮箱授权清空。仅已选账号能关联同次找回的网站。预览五分钟有效、切号和关窗清除；分组、布局、工作流及 WebDAV 连接不提供逐条找回。恢复仍分阶段，可重试但无整库回滚。

新百度／WebDAV 任务与数据归档及本地 .sfbe 备份统一用恢复密码包装的随机密钥 AES-GCM 加密，绑定账号、归档 ID、用途与分片序号；无密码配置不生成新归档。旧明文归档保留，不宣称已追溯加密；邮件内容仍独立备份。自动归档在最后一条记录删除后也生成空快照，恢复合并不据此删除本机数据。

更换恢复密码验证当前密码并生成新随机数据密钥，变化指纹包含密钥版本，无内容变化也生成新备份。历史备份仍用原密码，不批量重写。上传与导出期间密钥变化拒绝完成旧版本；不是跨设备密码轮换或撤回已下载副本。

仅本地模拟服务、隔离浏览器及自动回归，不操作真实网盘、不重载真实安装、不部署或发布。真实网盘灾备、断网续传和跨设备验收仍未完成。见 docs/releases/2.1.32-local.md 与 docs/development/adversarial-audit-2.1.32.md。

2.1.14 本地入口说明：脚本设置的“使用的资源”更名为“账号与服务”。这里按用途选择已有邮箱、AI 接口、表格或网站账号，只保存关联，不复制资料。普通运行参数仍在常用配置维护，无需资源的内置功能无需填写关联。网站书签与账号分类共用原账号；实际填充始终使用账号中确认的 HTTPS 登录来源。

2.1.31 本机删除与恢复、旧版入口收敛（最新覆盖）

脚本与普通配置按账号记录删除 ID，删除和记录写入同一存储队列／批次，随加密资料包保存并参与变化检测。恢复按真实源码身份检查脚本，已知删除不复活，已有活跃本机记录优先；用户主动重新安装或保存同 ID 可以重新建立记录。新设备从更早备份无法得知未来删除，不宣称全局删除一致性。

恢复记录完成阶段，部分脚本失败标记部分完成，失败保留已恢复部分，可重试补缺；恢复期间不提交自动资料备份。仍无整库回滚、历史快照回收或任务归档密码加密。

移除旧未分区本机资料、旧 Cloudflare 资料、旧官方邮箱及 Warden 原库恢复入口与后台路由；本机账号初始化不再读取旧 Warden。已迁入的当前记录和旧源文件保留。正常加密网盘备份、恢复、网站账号保存与填充继续保留。仅本地测试构建，不部署、不重载真实安装、不发布。

本机资料与百度备份、配置交互（2.1.27，本地预览，最新覆盖）

用户本轮明确改为本机资料主库、百度资料备份，Cloudflare 只按需承担 MCP 中转、邮箱转接、机器人 AI 指令；覆盖旧版要求自动写个人数据 Worker 的约定。日常资料读写、AI/MCP/WebDAV/邮箱凭据保存不再依赖 D1。Warden 自动同步和部署退出运行包，本机加密账号仓库保留填充安全检查，旧资料源不删除；旧本机可解密缓存离线接入，旧云资料仅用户明确找回时只读读取。

常用配置新增直接进编辑器。四种模板保留同页上下文，首次列表刷新不得关闭同账号编辑窗；迟到响应、切号仍拒绝。账号分类并入“网站书签”，数据仍为稳定 ID 关联，未关联账号和多账号不丢弃。看板布局比较规范化键顺序，真实多窗口修改仍阻止覆盖；刷新重读布局。旧普通飞书参数恢复可见、可用并标明脚本可读；不得从受保护连接自动提取密钥回填，也不自动改源。此项覆盖 2.1.25 对旧分组一律拒绝的描述。

个人资料使用本机设备加密；百度资料包以随机数据密钥 AES-GCM 加密，以用户至少 12 字符恢复密码经 PBKDF2 包装密钥。配置后变更约 30 秒触发、每分钟补查，无变化不上传，非实时协同。任务／数据仍为独立归档，保留原百度/WebDAV 目标，不得宣称其已经使用新的资料包密码加密。邮件内容独立备份。恢复保留本机同 ID 修改和墓碑，恢复脚本停用重审、服务授权清空、填充关闭。秘密批次有原值 CAS，其他元数据与源码分阶段恢复，失败可续但不保证整库事务回滚。个人资料包上限 32 MiB，旧快照暂不自动清理；新设备恢复后需设置后续备份密码。设备所有者可检查插件源码和本机数据，网页可读填入 DOM 的密码，不宣称零知识或绝对隔离。

仅本地构建、模拟服务及浏览器回归，不部署、重载真实安装或商店发布。真实网盘灾备、旧设备迁移与真实网站登录仍须验收。见 docs/releases/2.1.27-local.md。

2.1.79 local candidate: 文件流程：file.excel({fields,rows,filename}) 生成临时引用 → file.save({tempBlobId,filename}) 在任务结束前保存到数据中心文件库，返回 fileId、filename、size、savedLocally、status。用户在数据中心选择网盘并开启自动同步，插件上传新文件；脚本不能指定 baidu/webdav、取得网盘凭据或决定云端路径。状态 local/pending/uploading/synced/failed 与真实位置分别展示，连接不等于上传成功。临时文件只属当前任务，不读任意本机路径；单文件 20 MiB，任务合计 64 MiB，平台可能更小。报告不塞二进制或 Base64。

2.1.11 本地预览网络约束：后台沙箱中的联网使用 SellerFeeds.fetch／SellerFeeds.net 或声明并绑定的内置服务；原生 fetch、XHR、WebSocket、WebRTC、外部脚本/框架等不能用来绕过网络桥。HTTP／Token／AI／外部 MCP 共用管理地址保护。基础网络跳转不得把自定义请求头或正文转给另一来源；无此类内容的 GET 仍逐跳检查网站授权。个人资料与凭据不直接交给脚本。页面脚本的宿主原生网络不属于后台沙箱保证。此规则覆盖下方旧示例中直接使用原生网络的历史写法。

2.1.9 本地预览现行规则：停用 script.call／SellerFeeds.scripts.call，旧调用明确报错，不创建子任务；AI 必须在当前脚本中完成业务逻辑。个人中心原资源和用途绑定保留，新绑定不再把普通参数自动解释为 HTTP／表格连接。普通资源首屏只读取本机索引，摘要、同步状态及账号／验证码分开加载；敏感操作仍校验设备会话。旧记录不删除，个人数据 Worker 仍 v13，不代表官网已发布。此规则覆盖下方历史跨脚本调用说明。

2.1.8 本地预览现行规则：个人中心以一套分类／混合分组视图直接使用和管理原资源，取消“常用页面／全部资源”两标签。新分组保存 typed ID 引用，共享编辑；旧独立副本保留。从分组移除不删除原资料。使用情况列出脚本／Tool／用途和分组。布局沿 organizer workspace，Worker v13 才同步混合分组，旧云保留本机待同步。显示偏好按账号保存在当前设备。脚本仍声明内置功能并直接绑定原资源，无凭据读取接口；下方历史入口和自动复制规则以此为准。官网稳定版仍为 2.1.4。

2.1.7 本地预览现行规则：个人中心统一维护资料、连接与普通参数。脚本声明内置功能、具名用途和业务输入，用户直接绑定原资源，不新增个人资料引用配置。旧引用和旧接口兼容，旧章节中的“配置中心再建引用”仅用于理解历史版本，不适用于新操作。此补充优先于下方历史入口规则，本地更新不代表官网已发布。

插件精灵脚本开发说明

当前版本 2.1.4：个人资料在个人空间维护，配置中心只建立用途引用；邮件筛选由脚本参数传入。下方本地预览入口说明是历史，现行以本节及 SDK 公约为准。

邮件与个人资料：给 AI 的调用公约（2.1.4）

邮箱连接及密码等原资料在个人空间维护；配置中心只选已有资料生成引用配置，脚本在基础能力绑定配置。不得把用户邮箱、Token 或配置 ID 写死在可分享源码。邮件筛选在脚本调用参数中填写，不要求用户在邮箱或配置中心配置这些条件。用户可以给同一邮箱建立不同标题的用途引用，但引用不是独立邮箱或独立邮件副本。

查询返回 {messages,nextOffset,source:"local"}，摘要不含正文或凭据。远端刷新最多 20 页，每页 50；超上限报错，应缩小时间范围。省略 after 的远端刷新范围是最近 30 天；本机旧邮件不会被清空。读取正文使用返回的真实 messageId；已下载正文复用本机缓存。邮件内容仍只在本机或用户主动备份的云盘，不写入官方或个人 Cloudflare。

验证码示例（业务需核实发件人/时间/主题，不盲目取任意数字）：

// 元数据中声明 mail.query/mail.message，并给同一 mail 槽位声明两个操作：
// @sellerfeeds-modules {"enabled":true,"operations":["mail.query","mail.message"],"slots":[{"name":"verification_mail","title":"接收验证码的邮箱","operations":["mail.query","mail.message"]}]}
const after = new Date(Date.now() - 10 * 60 * 1000).toISOString();
const result = await SellerFeeds.sdk.call('mail.query', {
  slot: 'verification_mail', from: 'noreply@example.com', subject: '验证码',
  after, before: new Date().toISOString(), limit: 10, refresh: true
});
const candidates = [...result.messages].sort((a,b) => Date.parse(b.date) - Date.parse(a.date));
let code = null;
for (const message of candidates) {
  const body = await SellerFeeds.sdk.call('mail.message', {slot:'verification_mail', messageId:message.id});
  const match = String(body.text || '').match(/(?:^|\D)([0-9]{6})(?!\d)/);
  if (match) { code = match[1]; break; }
}
if (!code) throw new Error('指定发件人、主题和时间内没有找到验证码');
// 使用后不要把验证码或整封私信写入业务报告；返回不含敏感内容的执行摘要。

发信：SellerFeeds.sdk.call('mail.send',{slot:'sender_mail',to,cc?,bcc?,subject,text})，文字正文必填，发送需另声明 mail.send。accepted 是服务商接受，不等于实际投递成功；不得盲目重发。附件读取用 mail.attachment 返回当前任务的 tempBlobId；保存文件在任务结束前完成。网页版 AI 基础调用保持 webAi.chat 声明与本机会话验收，不自动开标签。

附件示例：在脚本的同一邮箱用途中声明 mail.query、mail.message、mail.attachment，另声明无需用途绑定的 file.save。用户绑定邮箱并授权这些操作后，脚本可获取附件并在当前任务结束前保存；无需先在邮件中心点击下载。读取邮件不会自动保存所有附件。

// @sellerfeeds-modules {"enabled":true,"operations":["mail.query","mail.message","mail.attachment","file.save"],"slots":[{"name":"incoming_mail","title":"读取附件的邮箱","operations":["mail.query","mail.message","mail.attachment"]}]}
const result = await SellerFeeds.sdk.call('mail.query', {
  slot: 'incoming_mail', subject: '订单', limit: 10, refresh: true
});
for (const item of result.messages) {
  const message = await SellerFeeds.sdk.call('mail.message', {
    slot: 'incoming_mail', messageId: item.id
  });
  for (const attachment of message.attachments || []) {
    // 按业务筛选附件；这里仅保存 PDF，跳过签名图片等内嵌内容。
    if (!/\.pdf$/i.test(attachment.filename || '')) continue;
    const file = await SellerFeeds.sdk.call('mail.attachment', {
      slot: 'incoming_mail', messageId: item.id, attachmentId: attachment.id
    });
    await SellerFeeds.sdk.call('file.save', {
      tempBlobId: file.tempBlobId, filename: file.filename, destination: 'local'
    });
  }
}

mail.attachment 返回文件名、类型、大小和当前任务专属的 tempBlobId，不返回邮箱密码，也不直接把附件字节放进普通 JSON 报告。临时文件上限沿文件模块执行（单项 20 MiB、任务合计 64 MiB）；邮件服务可能有更小限制。邮件中心默认点击下载正文并显示纯文本；阅读与收取设置可选择只看摘要或原文排版。附件列表逐项下载，正文下载不等于全部附件已保存。

网站引用使用 website.read 返回 {title,site,description}，不返回关联账号 ID 或密码。账号填充 account.fill 与验证码代填 account.totp 只能操作本任务的精确 HTTPS 页面；后台任务不选私人标签页。笔记引用 note.read/note.write 只读写那一条，笔记正文是脚本可见结果，不应把凭据写在普通笔记中。

配置中心管理普通参数、HTTP、AI API、MCP、飞书和云盘回传服务；邮箱、网站账号、两步验证与笔记的原资料在个人空间新增，配置中心只建立用途引用，脚本独立绑定。网站支持横向卡片与图标导航。网页版 AI 默认内置，仍需连接与能力验收。新脚本使用 [内置 SDK 与用途绑定](development/modules-v2.md)，没有手动组合动作要求。2.1.4 发布到 GitHub 和官网，1.9.73 独立回退包保留。本文后部带版本日期的章节用于旧接口兼容；与本节或 SDK 公约冲突时，以当前规则为准。

数据类脚本必读：数据保存与输出开发公约。本地完整保存是默认必达环节；飞书写表是可选附加输出；完成后应验证本地记录实际可读回。

飞书开发必读：自动写表公约。默认只需表格链接与授权码，脚本自动补齐文本列，无需复制表头或逐列设置。

本文是插件精灵的公开开发契约，面向脚本开发者和协助生成脚本的 AI。为兼容既有脚本，JavaScript 全局对象和元数据前缀继续使用 SellerFeeds 与 @sellerfeeds-*。平台实测差异与故障排查请同时参考《插件精灵脚本开发知识库》。

本文契约基线：基础运行时最早支持插件精灵 1.6.0，当前 SDK 为 2.1.4。当前使用 variables 与 @sellerfeeds-variable，不再使用旧 credential.data / @sellerfeeds-credential。使用 page 模式 SellerFeeds.fetch 的脚本要求 1.6.0 或更高版本。

接手 1.9.37 及近期插件功能时先读[近期功能交接](development/recent-features-handoff.md)和仓库根目录 AGENTS.md。本文后部保留部分历史版本说明；现行部署、数据边界和未完成验收以交接文档及[当前状态](current-state.md)为准。

新开发的数据查询、采集、监控类脚本，原则上应把飞书多维表格和钉钉 AI 表格视为平级、独立的可选回传目标。每组参数可整体留空；参数完整才写入对应平台，两组可同时填写，本地业务归档始终先完成。运行表单在两组同时存在时用标签切换，不清空另一组输入。飞书的具体写入规则见下文及表格配置实测记录、飞书授权码与写入接口；共同输出规则见数据保存与输出开发公约。

0. 给 AI 的单链接入口

只给 AI 本文 Markdown 地址 https://www.sellerfeeds.com/docs/development.md 和准确业务需求即可。AI 必须先根据任务类型继续读取下列资料，不能只复制本文的通用示例：

兼容的知识文章合集地址是 https://www.sellerfeeds.com/docs/knowledge.md；优先按下表读取与当前任务直接相关的独立文章，避免加载无关上下文。

开发顺序固定为：确认平台/页面/任务类型和证据状态 → 定义业务数据与本地保存流程 → 选择 page 或 offscreen → 声明最小权限与 Tool、可选输出参数 → 复用已验证解析逻辑 → 生成完整 .user.js → 静态检查 → 脱敏样本测试 → 验证本地落库 → 条件具备时验证真实采集、本地读回、可选写表与通知 → 给出分项验收证据。

能力边界：文档只保证当前框架契约；平台知识按文章中的证据等级生效。未覆盖或改版页面需要新的 DOM/响应证据，不能仅凭文字需求保证立即可用。本入口不会替 AI 部署官网、写生产数据库或发布 Chrome Web Store。

1. 先理解运行模型

插件精灵是 Chrome MV3 用户脚本运行器。脚本负责业务逻辑，插件负责安装、权限申请、任务调度、常用配置传递、任务历史和可选的 MCP 接入。

• 官方脚本和社区脚本使用同一套运行接口。
• 每个脚本可以声明一个或多个 Tool，但应优先把一个完整业务动作设计成一个 Tool。
• 插件运行表单按 Tool name 去重。单 Tool 脚本只显示紧凑名称，多 Tool 脚本只用一个下拉框选择；用途及输入输出说明在“查看 Tool 说明”中按需展开。为便于用户识别，多个 Tool 不应共用相同标题；若标题相同，选择框会附带 Tool ID。
• 手动、批量、定时和 MCP 调用最终都会进入同一个 SellerFeeds.onTask 处理器。
• 脚本负责已授权的业务 API 调用、结果整理、报告及链接返回；飞书／钉钉表格与网盘的结果同步由用户在数据中心配置，插件执行。
• 网站账号、邮箱与两步验证须由用户主动选择，脚本只能请求插件代为操作，不能获取这些资源的凭证。

视频保存到百度网盘、WebDAV 或本机

视频保存另需 @sellerfeeds-assets {"video":true} 和 SellerFeeds.assets.saveVideo({url,filename})，只处理任务取得且已授权的 HTTPS 来源。用户选择文件同步位置后，插件沿该规则上传；未选时使用浏览器下载目录。数据中心显示媒体元数据与已确认路径，大视频正文不进普通文件库或报告。历史浏览器下载不会自动重新上传。旧 uploadVideoToBaidu 拒绝执行，需作者迁移。真实 Range/有效期/跨域需验证，不能把任意文件交给视频通道绕过限制。

保存音频时显式声明 @sellerfeeds-assets {"audio":true}，并调用 SellerFeeds.assets.saveAudio({url, filename:'音乐.mp3', source:'page'})；可与 {"video":true} 合并声明。source:'page' 只适用于隔离世界的当前页面任务，来源和重定向仍检查脚本与浏览器网站权限。音频按实际格式使用 mp3、m4a、aac、wav、ogg 或 opus 扩展名。保存位置沿用用户在数据中心选择的文件同步设置，未选时下载到 SellerFeeds/audios；脚本不能直接选择百度或 WebDAV。不要把音频改名为 .mp4，不要把媒体字节放入报告。

需要调用用户自己配置的 AI API 时，先让用户在配置中心添加 AI API 服务、模型和密钥，脚本声明能力后按 Tool 选择配置。USER_SCRIPT 或 offscreen 脚本可在活动任务中调用 await SellerFeeds.ai.chat({ profileId, messages: [{ role: 'user', content: '请总结这段内容' }], temperature: 0.2 })；返回 {content,model,usage}。profileId 是配置 ID，不是 API Key。只支持文本 Chat Completions，消息角色为 system、user、assistant；不自动选择模型、调用 MCP Tool 或修改既有脚本。MAIN world 不能使用。调用结果是否写入报告由脚本决定，切勿在输入、日志或报告中保存密钥。AI API Key 与远程 MCP 连接凭据由 SellerFeeds 账号服务加密保存，换电脑登录后自动同步；新百度／WebDAV 配置快照不包含这些凭据。

脚本自动操作本机网页版 AI

网页版 AI 是默认内置的本机能力，不经 Worker；旧 /v1 网页代理已移除。声明 // @sellerfeeds-web-ai {"enabled":true,"files":true}（仅文字可省略 files），用户确认脚本能力声明、按 Tool 选择网站并完成本机连接验证后，可在活动任务内自动发提示词、上传附件、读取正式回答：

const first = await SellerFeeds.webAi.chat({
  providerId: 'deepseek-web',
  prompt: '请根据附件分析商品数据，区分事实与推测。',
  files: [{
    data: new Blob([JSON.stringify(report)], {type: 'application/json'}),
    filename: 'products.json'
  }]
});
const followup = await SellerFeeds.webAi.chat({
  providerId: 'deepseek-web', prompt: '基于刚才的数据列出三个可验证的建议。'
});

返回 {content,providerId,sessionId}；脚本自行决定保存报告或写表。当前仅实现 deepseek-web 的无标签页协议，使用 DeepSeek default 模型；Gemini、豆包、智谱清言已实现文字协议，具体开放以本机验证状态为准，附件仍不可用；Kimi 尚未验收，MiMo 已移除。USER_SCRIPT 与 offscreen 可用，MAIN world 禁用。用户首次打开插件专用登录页，明确保存最小会话字段后可以关闭；运行不打开标签页，不读取 Cookie 或私人聊天，会话只在本机加密、不上传官方。同任务复用真实会话与消息编号，不同任务独立、每站串行。失败不自动重发，登录失效、上传失败或超时明确报错。

用户本地文件只通过 Tool 的 {"type":"array","format":"web-ai-files","items":{"type":"object"},"maxItems":5} 字段明确选择，管理页和悬浮表单均支持；脚本把对应 input.files 传给 files。选择引用按账号／脚本暂存、绑定本次任务，不能保存为长期常用或定时配置；无人值守任务应由脚本生成附件。也支持 Blob/File 或 {data:Blob,filename}，拒绝任意路径、URL 和其他任务引用。最多 5 个附件，单文件 20 MiB、合计 64 MiB；提示词最多 100000 字符，SSE 回答流上限 4 MiB，须正式结束才返回成功，不截断冒充成功。

本版协议开放 DeepSeek 的 TXT、CSV、JSON、MD、PDF、DOCX、XLSX、PPTX、PNG、JPEG、WebP 适配，但新无标签页完整回环仍须真实账号验收；旧 DOM 控件测试不能作为此版证据。旧 DOC／XLS／PPT 与其他网站协议暂不可用。图片分析受网站自身 OCR／识图能力限制。示例为 examples/web-ai-local-analysis.user.js；完整接口、实现、真实验证和加载待验事项见 [本机网页版 AI 开发说明](development/local-web-ai.md)。

2. 最小可运行脚本

// ==UserScript==
// @name         示例商品查询
// @namespace    https://example.com/sellerfeeds
// @version      1.0.0
// @description  根据商品编号查询商品信息
// @match        https://www.example.com/*
// @run-at       document-idle
// @grant        none
// @sellerfeeds-execution-mode page
// @sellerfeeds-tool {"name":"example_query_product","title":"查询商品","description":"当用户需要查询 Example 网站中的单个商品信息时使用。读取商品标题与价格，不修改网站数据；需要用户已登录 Example。","inputSchema":{"type":"object","properties":{"productId":{"type":"string","title":"商品编号","description":"Example 网站中的商品编号，不能为空。","minLength":1}},"required":["productId"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"productId":{"type":"string","description":"商品编号。"},"title":{"type":"string","description":"商品标题。"},"price":{"type":"number","description":"商品价格；网页未返回时省略该字段。"}},"required":["productId","title"]}}
// ==/UserScript==

SellerFeeds.onTask(async ({ taskId, tool, input, variables, source }) => {
  if (tool !== 'example_query_product') throw new Error(`不支持的 Tool：${tool}`);
  if (!input.productId) throw new Error('请填写商品编号');

  return {
    message: '查询完成',
    data: {
      productId: input.productId,
      title: '网页返回的真实标题',
    },
  };
});

@sellerfeeds-tool 和 @sellerfeeds-variable 的 JSON 必须各自写在一行中；文档中的格式化 JSON 只用于讲解。

3. 元数据字段

3.1 标准 UserScript 字段

3.2 插件精灵扩展字段（@sellerfeeds-*）

脚本源码最大 2MB。安装和更新地址必须使用 HTTPS，并以 .user.js 结尾。

4. 选择执行模式

选择原则：必须操作网页就用 page；只做“请求 + 解析”就用 offscreen。

4.1 page 模式入口

// @sellerfeeds-execution-mode page
// @sellerfeeds-entry-url https://www.example.com/product/{input.productId}

占位符只能读取 input 顶层字段。缺少可选字段时，运行器会尝试回退到 @match 可推导出的首页，因此脚本仍需自行检查当前页面和输入。

4.2 offscreen 模式网络域

// @match   https://www.example.com/*
// @connect https://api.example.com/*
// @sellerfeeds-execution-mode offscreen

@match 表示目标网站及基础授权范围；@connect 只增加允许请求的 API 域，不会把脚本注入该域。初始 URL 和每一次重定向都必须处于脚本声明且用户已授权的范围内。

5. SellerFeeds 运行时 API

5.1 接收任务

SellerFeeds.onTask(async ({ taskId, tool, input, variables, source }) => {
  // source: manual | batch | scheduled | mcp
  return { message: '完成', data: {} };
});

处理器返回值必须可被 JSON 序列化。抛出 Error 会使任务失败，错误信息会进入任务历史和 MCP 报告。

5.2 受控网络请求

1.6.0 起，page 与 offscreen 脚本都通过以下接口请求自身 @match 或 @connect 域：

const response = await SellerFeeds.fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ keyword: input.keyword }),
});

if (!response.ok) throw new Error(`请求失败：HTTP ${response.status}`);
const result = await response.json();

限制如下：

• body 只支持字符串，JSON 对象必须先 JSON.stringify。
• headers 使用普通对象。
• 无论脚本传入何值，运行器都以 credentials: include 和 redirect: manual 代发；每一次重定向目标都重新校验。
• 初始 URL 和重定向只允许 HTTP/HTTPS，必须落在该脚本当前生效的 @match / @connect 且用户已授予网站权限的范围内。
• 默认禁止通过该桥访问 sellerfeeds.com 自家域，防止脚本借用扩展固定权限。
• offscreen 沙箱不能直接使用 chrome.*。
• 桥接请求不能真正中止；需要超时提示时可使用 Promise.race，并忽略迟到结果。
• 不要在日志、报告或错误消息中输出 Cookie、Token 或完整常用配置。

page 的 USER_SCRIPT 与 MAIN 世界都提供该接口。MAIN 世界脚本和网站共享 JavaScript realm，网站可能观察或干扰桥接消息；只有确实需要页面 JS 对象时才选择 MAIN，普通 DOM 读取应使用默认 content/USER_SCRIPT 世界。

5.3 日志与进度

SellerFeeds.log('开始查询', { productId: input.productId });
SellerFeeds.emit('task-progress', { current: 20, total: 100 });

日志只写必要的诊断信息，不要记录凭据和完整响应中的隐私数据。

6. Tool 与输入 Schema

6.1 Tool 声明结构

{
  "name": "amazon_collect_search_results",
  "title": "采集亚马逊搜索结果",
  "description": "当用户需要分析亚马逊关键词搜索结果时使用。读取自然位与广告位，返回商品列表和位置类型；需要浏览器已登录目标站点，只读取数据，不修改店铺。",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {}
  }
}

6.2 MCP 发布硬性要求

脚本能在本地运行，不代表它会自动成为 MCP Tool。安装后默认不发布到 MCP；只有用户开启全局 MCP，并在脚本中心单独打开该脚本的 MCP 开关，AI 才能看到它。

发布前必须满足：

1. name 匹配 ^[A-Za-z0-9_-]{1,128}$，不能使用保留名 get_report。
2. name 应稳定且具有业务前缀，推荐“平台_动作_对象”，如 amazon_collect_search_results。
3. description 明确回答：何时使用、做什么、作用范围、返回什么、需要什么前提、是否有副作用。
4. inputSchema 根节点必须是 {"type":"object"}。
5. 每个顶层参数必须有准确的 type 和 description；数组还必须声明 items.type。
6. required 只能引用 properties 中存在的字段。
7. 同名 Tool 会冲突，发生冲突的 Tool 都不会发布。

建议为 Tool 和参数提供普通用户能看懂的 title，并声明稳定的 outputSchema。

6.3 Schema 设计要求

支持常用 JSON Schema 约束，包括 type、enum、default、minimum、maximum、minLength、pattern、minItems、required 和 additionalProperties。

• 字段必须对应网页或接口真实存在的输入。
• 枚举只列出真实选项，不虚构“自动”等页面没有的值。
• 数值使用 number 或 integer，不要让用户填写带单位的字符串。
• 描述中写清单位、格式、示例、范围以及字段间关系。
• Schema 负责基础校验；登录状态、跨字段关系和业务错误仍由脚本检查。
• 没有获取到的数据返回 null 或省略，不得使用 0 或空字符串伪造真实值。

网页悬浮入口需要自动预填时，在 Tool JSON 中显式声明 pageContext，例如 {"kind":"amazon-product","pageTypes":["product","reviews"],"inputs":{"asin":"amazon.asin","site":"amazon.site"}}。当前只对白名单页面类型和来源字段预填，来源须展示给用户且允许修改；页面商品变化后旧预填不得直接提交。插件不会按字段名猜 ASIN、填竞品 ASIN、读取密钥或自动执行任务。脚本仍要校验页面与输入，定时、批量、MCP 不使用这项网页预填。

以下仅说明旧第三方脚本的参数组兼容。官网 34 份新版脚本不使用表格参数组；新采集脚本通过数据中心回传。旧脚本同时提供飞书与钉钉表格时，在 inputSchema 内用 x-sellerfeeds-input-groups 分别声明可整体留空的参数组；不要把两组字段加进根级 required。例如：

"x-sellerfeeds-input-groups": [
  {"id":"feishu","title":"飞书表格（可选回传）","fields":["baseUrl","baseToken"],"required":["baseUrl","baseToken"]},
  {"id":"dingtalk","title":"钉钉 AI 表格（可选回传）","fields":["dingtalkTableUrl","dingtalkAppKey","dingtalkAppSecret"],"required":["dingtalkTableUrl","dingtalkAppKey","dingtalkAppSecret"]}
]

这些字段还须在 properties 中逐一声明类型、中文说明，并给 baseToken、dingtalkAppKey、dingtalkAppSecret 标记 writeOnly:true。插件仅在两组都存在时用 Tab 切换视图；每组一旦填了任一项，就必须补齐该组要求字段或清空整组。Tab 切换不改变输入值，也不意味着用户只能选一个平台。验证入口为 extension/core/input-groups.mjs 与 tests/input-groups.test.mjs。

7. 常用配置与配置模板

“常用配置”让普通用户保存一组经常重复填写的名称和值，例如表格地址、授权码、店铺编号或固定筛选条件。它是通用参数库，不绑定某个脚本或平台。

7.1 自动匹配规则

用户为任务选择一项常用配置后：

• 与 Tool inputSchema 同名、同路径的值会自动填入 input。
• 用户在任务表单中手动修改的值优先。
• 不在 Schema 中的内容不会混入 input，但脚本仍能从完整的 variables 中读取。
• 未选择常用配置时，variables 为 {}。
• 手动、批量和定时任务都可以选择常用配置；定时任务运行时读取该配置的最新值。
• 悬浮窗和插件内手动执行会按账号、脚本和 Tool 记住上次选择的配置 ID，下次自动选中；定时和批量保留各自已保存的选择。页面识别参数与用户手动修改优先。

优先级为：用户手动填写 > 常用配置同名值 > Schema 默认值。

7.2 预制录入模板

脚本可声明一个或多个表单模板：

// @sellerfeeds-variable {"title":"飞书多维表格配置","description":"填写表格链接与授权码","schema":{"type":"object","properties":{"baseUrl":{"type":"string","title":"飞书多维表格链接"},"baseToken":{"type":"string","title":"飞书授权码","writeOnly":true}},"required":["baseUrl","baseToken"]}}

安装脚本时，用户可以选择模板或“稍后设置”。选中后，安装完成会打开对应表单。模板只改善录入体验，不绑定或过滤常用配置，也不限制开发者增加任意字段。

7.3 在脚本中读取

常用配置先填入本次 input，脚本再校验可选参数组。optionalFeishuConnection(input) 是示例脚本提供的辅助函数，不是平台内置 API；整组留空返回无连接，半填应在采集前报错。

完整执行顺序遵循数据保存与输出开发公约：采集 → 确认本地持久化 → 按完整配置写飞书 → 汇总各环节状态。飞书异常需单独捕获，保留完整数据、已确认写入数量和错误说明。不能把只包含“采集、写飞书、返回结果”的局部示例直接当成符合公约的完整脚本。

常用配置在本机维护，普通参数对选用它的脚本可读，内置连接凭据由插件代用。当前备份与换机规则以本文顶部第四十七轮为准：个人资料到用户 Cloudflare，业务归档到选择的百度/WebDAV；官方保存必要连接和账号信息。

设置页把百度网盘和 WebDAV 收进同一备份卡片的两个 Tab。切换 Tab 不会切换目标，必须在连接弹窗中明确选择；始终仅有一个自动备份目标。HTTP 代理卡片默认收起，右上角开关单独控制全浏览器代理；保存代理地址不自动启用，关闭开关仍保留本机配置与加密密码，并清除本插件的 Chrome 代理覆盖。

插件左下角帮助中心提供官网与脚本库链接、使用指南和可重新打开的新手指引。首次进入插件时，指引依次介绍安装脚本、常用配置、任务报告、数据查询和同步备份。管理员可彻底删除官方或社区脚本、删除用户并保留其公开社区作品、批量管理标签。删除用户后，同一微信身份可再次扫码注册为新账号；旧账号、绑定及私人数据不会恢复。后台可查看设备记录，不提供吊销设备操作。

8. 手动、批量与定时任务

同一个 Tool 不需要为三种任务模式编写三套代码。

• 手动任务：执行一次表单或 JSON 输入。
• 批量任务：选定一个批量字段，多行值会拆成多个任务；其余字段作为每项任务的公共输入。
• 定时任务：保存 Tool、输入、常用配置选择和时间规则，到点后自动调用。
• 运行时可通过 source 区分来源，但除非业务确实不同，不建议分叉核心逻辑。

脚本应保证重复执行的行为可预测。是否追加、覆盖、更新或去重必须由脚本根据业务要求明确实现，不要假设插件会代为处理。

9. 任务结果、报告和通知

脚本返回值可以同时包含结构化数据、摘要、链接和文件：

return {
  message: '采集和写入完成',
  data: { total: records.length, records },
  links: [{ title: '打开结果表格', url: tableUrl }],
  files: [
    { name: '结果.md', format: 'markdown', content: '# 结果' }
  ],
};

结果规则：

• message 用于任务摘要和通知文字。
• data 是结构化结果，会进入任务报告和 MCP public_report。
• links 是用户可打开的 HTTPS 链接。
• files 是脚本主动返回的文件；链接和文件可以同时存在。
• 飞书机器人在远端表格写入成功并取得有效链接时只发送任务摘要与确认后的表格链接；未写表或写入失败时发送实际报告文件，脚本声明 Excel 时优先发送 .xlsx。
• 通知是否附带文件不影响本地业务数据、任务报告及用户下载；未声明策略的旧脚本行为不能作为新脚本规范。
• 没有 files 不等于任务失败；报告形式由脚本结果和脚本声明共同决定。

业务数据中心与任务历史是两个独立的保存环节。当前 IndexedDB v3 的任务报告不按旧的 500 KB 阈值截断，实际写入受浏览器容量限制；业务数据另有单记录／单批限制。大结果应按记录拆分和分批保存，报告摘要可精简，但不能静默截断业务原文。不能用“报告可下载”代替“业务数据已落库”的验收。

9.1 本地保存是默认交付要求

数据类脚本默认要求保存完整业务数据，飞书是否配置不影响这一要求。未声明新策略的旧脚本继续自动归档；运行后在数据中心按任务 ID 读回验证。每份新脚本须明确声明通知与数据中心策略（JSON 写在同一行）：

// @sellerfeeds-notify {"mode":"all"}
// @sellerfeeds-data-center {"mode":"save"}

通知 mode 可选 all、failure-only、off，分别代表手动／批量／定时任务的完成与失败都通知、仅失败或部分失败通知、均不通知；MCP 无论声明为何值都不发送任务通知。本地保存失败和表格写入失败也会明确告知，不能只按采集成功跳过错误。数据中心 mode 可选 save、off；off 只适用于无业务数据的纯动作脚本，阻止自动归档与 SellerFeeds.data.define/save 主动写入，任务中心仍保留执行报告。不要把动作结果对象误当业务数据。既有 @sellerfeeds-notification 保留兼容解析，当前通知不再按它或脚本的成功标志选择链接；以数据中心绑定和本次写入回执为准。

插件精灵 1.8.2 支持以下业务结构元数据：

// @sellerfeeds-local-data {"dataset":{"name":"task-reports","title":"任务报告","version":1,"mode":"snapshot","primaryKey":["任务编号","商品ASIN"],"fields":[{"key":"任务编号","type":"string"},{"key":"商品ASIN","type":"string"},{"key":"问题数量","type":"number"},{"key":"完整报告","type":"text"}]},"recordsPath":"data.商品报告","contextFields":{}}

这里的 dataset 也是 SellerFeeds.data.define 的参数；示例的 data.商品报告 是仅含一份汇总报告的数组；主键使用任务编号和商品 ASIN，快照自动区分不同任务。字段名为顶层字段，recordsPath 和上下文来源支持点分路径。此声明用于组织业务行和补存，不控制是否保存；不能与数据中心 off 同时声明。未声明新策略的旧脚本仍完整归档返回结果。无结果的操作型脚本仅保存执行记录，不制造空业务记录。

脚本运行时先 await SellerFeeds.data.define(dataset) 检查接口及存储可用性，再采集；按业务行分批调用 await SellerFeeds.data.save({dataset: dataset.name, records})。校验返回的 datasetId、inserted、updated、skipped 和 errors；新采集脚本默认到此完成数据交付，由数据中心处理已绑定的表格，不再复制连接凭据、建列和重试代码。本地失败必须保留错误和报告，不得只发送成功链接。长任务的持久化进度应与对外报告数量分开设计，不能把只存在内存的进度说成已经保存。每次本机 save 最多 500 行且总量不超过 8 MiB，单记录不超过 1 MiB（含存储封装），脚本应留出封装空间，超限不能截断原文。这是本机存储限制，远端批量限制另见数据输出公约。

分别展示采集、本地落库、表格写入和消息投递状态。远端写入异常必须单独处理并保留结果。本地失败提示“补存任务结果”；运行器按声明从现有报告补齐业务记录，以同任务快照主键避免本机重复，不重新采集。补存产生的新记录会进入已绑定目标的待写队列，已确认写入的记录不重新排入；不能笼统承诺补存绝不触发写表。原报告保留失败时的事实，最新补存状态显示在任务数据保存状态。完整规则和验收矩阵见数据保存与输出开发公约。

10. MCP 调用模型

MCP 业务 Tool 使用异步任务模型，由用户自己的 Cloudflare Worker 与 Durable Object 实时中转到在线浏览器：

1. AI 调用脚本 Tool。
2. 在线插件经实时通道接收调用、校验输入并启动任务，先返回 task_id。
3. 插件执行并将任务与完整报告保存在本机；Worker 不以 D1/R2 保存业务结果。
4. AI 使用系统 Tool get_report 和 task_id 向在线插件查询状态及结果。

因此 Tool 的描述和 Schema 必须足够清楚，让 AI 在不阅读源码的情况下判断是否应该调用、怎样填写参数以及会产生什么结果。

每个可调用脚本的 @sellerfeeds-tool 均须提供明确的 name、title、description、inputSchema 和 outputSchema。描述应写出适用任务及前提；输入字段要说明必填、可选、默认值和可接受格式；输出字段要说明业务含义、缺失值与错误状态。不要只写“查询数据”之类的笼统标题。插件脚本中心的“MCP 说明”读取这份元数据展示给用户，MCP 客户端的 tools/list 将同一说明提供给 AI；客户端调用后须用返回的 task_id 调用 get_report，并处理运行中、成功和失败状态。更新脚本声明时提高版本号，生成脚本还需同步修改生成器和测试。

数据中心以脚本为入口展示历次任务的全部业务明细，相同业务值在不同任务中不去重；任务中心“查看数据”直接打开单任务明细表／原始报告 JSON 弹窗。此布局是本地查询投影，脚本仍遵守一任务一份紧凑 JSON 的保存规则。配置中心列表展示创建时间和配置项数，但不展示配置值或密钥。

从数据中心下载脚本总表时，Excel 主工作表保持一条业务明细一行。如果某个值超过单元格的 32767 字符上限，主表会指向第二张“超长内容”工作表；第二张表按主表行号、任务编号、原字段及片段序号保留全文。原始 JSON 和本地归档不因导出而改变。

控制规则：

• 脚本安装后 MCP 默认关闭。
• 全局 MCP 开关和脚本级 MCP 开关必须同时开启。
• 脚本不能替用户开启 MCP。
• 停用脚本后，它的 Tool 会退出 MCP 清单。
• 脚本更新保留用户原来的 MCP 选择。
• MCP 来源任务不发送普通任务通知，结果由 MCP 客户端通过 get_report 获取。

11. 权限和安全边界

• @match 和 @connect 应遵循最小范围原则，不要申请无关域名。
• 安装或更新增加新域名时，必须由用户确认网站权限。
• 脚本只能读取用户主动为任务选择的那一项常用配置。
• 脚本拿不到插件精灵 License、服务端密钥或其他脚本的数据。
• 不得把 Cookie、Token、授权码或用户业务数据上传到声明用途之外的第三方。
• 不要把完整凭据写入源码、日志、异常信息、任务返回值或报告。
• 使用 MAIN 世界、eval、new Function、Cookie、本地存储或页面跳转等能力会产生风险提示，应仅在确有必要时使用。
• 未登录、Cookie 失效、验证码、Robot Check、HTTP 401/403/429、超时和平台业务错误都必须真实报告，不得伪造成功。

12. 安装、更新和身份

• 脚本身份由稳定的 @namespace 与 @name 共同确定；修改其中任意一个会被视为新脚本。
• 更新必须提高 @version，并保持脚本身份不变。
• 更新新增网站权限时，用户需要重新授权。
• 本地修改过源码的脚本不会被无提示覆盖。
• 卸载脚本后，运行器会回收不再被其他脚本使用的网站权限。
• 社区脚本安装前应让用户审阅源码、网站范围和风险提示。

13. 开发与测试清单

提交脚本前至少确认：

1. 元数据块完整，@sellerfeeds-tool 和 @sellerfeeds-variable 均为单行 JSON。
2. @match、@connect 和执行模式符合真实需求。
3. Tool 名称稳定、唯一，描述能让普通用户和 AI 判断使用场景。
4. 所有输入字段都有准确类型、标题、说明、单位、范围或示例。
5. onTask 校验必填项、跨字段规则、登录状态和业务响应码。
6. 正常结果、空结果、未登录、限流、验证码、超时和接口错误均经过测试。
7. 批量和定时运行不依赖当前活动页面，或已正确提供 @sellerfeeds-entry-url。
8. 没有在源码、日志和结果中泄露 Cookie 或常用配置。
9. 返回字段来自真实网页或接口；缺失值不伪造为 0。
10. 手动、批量、定时和 MCP 共用同一个稳定业务入口。

仓库开发时运行：

pnpm run verify

14. 如何把文档交给 AI

生成或修改脚本时，只需向 AI 提供本开发说明 Markdown https://www.sellerfeeds.com/docs/development.md 和准确需求。需求应写清目标网站/页面、输入字段、预期输出以及是否允许写入外部系统；AI 应按本文第 0 节的索引自行继续读取知识与示例。

可以直接使用以下提示词：

请先完整阅读插件精灵脚本开发说明和知识库，再根据我的需求编写一个可安装的 .user.js。
必须遵守元数据、执行模式、常用配置、Tool Schema、MCP 描述、权限和结果契约；数据类脚本必须声明结构化输出并验证插件实际落库；飞书与钉钉回传由数据中心统一配置，不在脚本中复制发送逻辑或要求表格凭据。不能以任务成功代替本地落库证据。
对知识库没有确认的页面字段或接口行为，不要猜测，请明确列出需要我实测的信息。
我的需求是：……

知识库记录平台的实测事实；开发说明定义运行器契约。两份文档发生表述冲突时，以开发说明的运行器契约为准，以知识库中标注的最新实测结论解释目标平台行为。

作者自行写表的兼容契约与配置引导

以下参数组、表格模板及直写规范只用于作者明确选择自行写表的脚本。新采集脚本默认只交付本机数据，由数据中心绑定和批量回传；不要机械添加本节的飞书参数或 SDK 调用。兼容脚本与数据中心指向同一目标时须明确唯一写入方，当前没有自动防双写机制。

每个脚本可独立声明一个 @sellerfeeds-table，让详情页、安装预览和常用配置表单自动展示该脚本的模板、字段名称、类型与写入说明。先提供仅包含 baseUrl、baseToken 的中文 @sellerfeeds-variable 表单，再引用它的序号；App Token 与 Table ID 仅在内部解析：

// @connect https://base-api.feishu.cn/*
// @sellerfeeds-table {"provider":"feishu-bitable","title":"任务汇总报告","required":false,"autoCreateFields":true,"writeMode":"append","schemaVersion":"1","configTemplateIndex":0,"description":"一个任务一行，全部问答保存在完整报告列。","fields":[{"name":"任务编号","type":"text","description":"用于关联本次任务"},{"name":"商品ASIN","type":"text","description":"本次采集的商品"},{"name":"问题数量","type":"text","description":"本次问答明细数量","example":"7"},{"name":"完整报告","type":"text","description":"全部问题、完整答案、商品表格及推荐追问"}]}

• 将本脚本真实可复制的飞书模板地址填到同一个 JSON 的 templateUrl 属性中。每个脚本使用自己的地址；没有准备好的模板时省略，界面会提供复制表头和字段类型说明。
• 模板地址是给用户复制的公开入口。用户的实际表格地址、授权码只能由本次参数或用户选择的常用配置提供，不要放进脚本源码。
• fields 必须与脚本实际写入的字段一致；目前支持 text（文本）和 number（数字）。条件字段可用 condition 补充说明。
• writeMode 为 append、update 或 overwrite，只说明脚本的写入方式；数据写入逻辑仍由脚本实现。
• 采集类脚本的飞书输出必须设置 required:false，不可作为采集或本地保存的必选前提。运行器虽支持必选外部输出，新采集脚本不应采用该设置。结构变化时更新 schemaVersion 和字段说明。
• 配置页的检查仅读取字段，不会写入测试数据。请用独立测试表验证真实写入效果，再发布脚本及其模板。

可选目标参数组：完整填写即回传

本节是 1.7.0 的参数组契约，替代旧版单独的回传开关。飞书、金山文档、钉钉文档或其他目标都使用同一种参数组声明；平台负责完整性校验，脚本负责实际平台接口。常用配置仅保存并快速填入值，不决定是否回传，也不能覆盖用户在本次表单里清空或修改的值。

飞书开发公约：面向用户的 Tool 参数和常用配置模板只要求 baseUrl（飞书多维表格链接）与 baseToken（飞书授权码）。不得另设“写入飞书”布尔开关，不得要求手填 App Token 或 Table ID；脚本从 HTTPS 飞书 /base/ 链接及其 table 查询参数自动识别这两个内部 API 标识。链接无法解析时提示用户进入具体数据表后重新复制链接，不猜测目标。旧标识仅可用于内部兼容，不作为新表单输入。

自动表单保留作者声明的参数组及完整输入。插件不再注入通用“结果写入”模块，也不按飞书、钉钉字段名隐藏参数。开发者通过 x-sellerfeeds-input-groups 声明目标参数组及中文含义；字段位置以当前表单布局为准。

在 Tool 的 inputSchema 根节点声明 x-sellerfeeds-input-groups。例如：

{
  "type": "object",
  "properties": {
    "product": {"type":"string","title":"商品","description":"要采集的商品"},
    "baseUrl": {"type":"string","title":"飞书表格链接","description":"包含 /base/ 与 ?table= 的链接"},
    "baseToken": {"type":"string","title":"飞书授权码","description":"该目标表格的授权码","writeOnly":true}
  },
  "required": ["product"],
  "x-sellerfeeds-input-groups": [
    {"id":"feishu","title":"飞书表格（可选回传）","fields":["baseUrl","baseToken"],"required":["baseUrl","baseToken"]}
  ]
}

• 整组未填或只有空白：跳过该目标；不检查该组字符串格式，不请求该平台。
• 本组任意字段已填：必须补齐组内 required；只填一半时在对应字段显示错误，不能开始脚本。false 和 0 是有效填写值，不当作留空。
• 完整填写：根据本次输入自动回传；凭据实际有效性仍由平台 API 检查。
• fields 支持 Schema 中简单字段的点分路径；不能重复归组或使用危险路径。每组有唯一 id，可用 title 展示名称。
• required 省略时，本组所有字段均为必填；有可选项时显式列出必填字段。其他平台的参数组可用 requiredAnyOf 声明替代组合；其中的字段也必须属于 fields。飞书统一采用链接与授权码，不提供手填标识的替代入口。
• 组内字段不要同时放进根节点 required，否则会使整个输出成为强制必填。不要给可选组预填真实目标或凭据。
• 多组分别校验：完整填写哪组就回传到哪个目标。表单、JSON、批量、定时和 MCP 使用同一规则。writeOnly 字符串在自动表单中显示为密码框；不要在日志、报告或公开源码中返回 Token。
• 脚本仍须在采集或修改网页前复核参数，防止旧客户端绕过新校验。表格标识必须从链接内部解析。旧任务仍只有回传开关时，应提示重新填写并保存，不可默默写入某个历史配置。

参数组只决定是否执行远端写表。脚本仍须独立完成本地保存与错误恢复；配置读取方式见“7.3 在脚本中读取”，完整顺序及验收见数据保存与输出开发公约。调用写表辅助函数时必须接收确认数量和错误状态；远端异常不能丢弃已取得的业务结果。

自动补齐目标表字段

自行写表的脚本在写入飞书前须读取真实字段列表，按名称复用已有列，并按脚本声明创建缺失列，然后再写记录。 使用数据中心输出时由插件完成这些步骤，脚本无需重复实现。用户不必逐个填表头；模板与复制表头作为可选便利入口保留。

• 只新增缺失列，额外字段保留，既有字段不会因名称不同被自动删除或覆盖。
• 同名但类型不兼容时，按脚本明示支持的方式转换，或指出具体字段并停止；不自动修改已有列类型。
• 建列需表格结构编辑权限。建列失败、超时或响应不确定时，不继续写行、不盲目重试；重试前先重新读取表结构，复用已经创建成功的列。
• 同一目标的一次写入任务中复用已检查的结构，避免每一批都新建同名列。新建成功但后续写入失败时，保留已建列并准确报告结果。

通用飞书回传的固定开发规范

作者明确需要脚本自行写飞书时，先按数据保存与输出开发公约完成本地存储设计，再检查以下兼容要求。数据中心输出使用该公约的批量队列和重试规则，不采用下述旧脚本内重试次数：

• 声明 @sellerfeeds-table 且设置 required:false；Tool 使用 x-sellerfeeds-input-groups 声明可选目标参数组。
• 整组留空时不请求飞书；部分填写必须在采集前拒绝；完整填写时自动回传，并先自动补齐缺失字段。
• 新建表的业务字段默认全部声明为 text；Tool JSON 保留原生 number/boolean/null，只在飞书映射层转成字符串。只有用户明确要在飞书内做数值计算时才改用数字列。
• 批量追加使用 records/batch_create，脚本默认每批最多 500 行，相邻写入批次间等待 700ms，使单文档保持在约 2 QPS 以内。不要因为接口单次上限更大就取消批间节流。
• 对 HTTP 429、1254290 TooManyRequest、99991400 或明确的限流响应，按 1s、2s、4s 退避，最多重试 3 次；不允许无限或无等待重试。
• 同时检查 HTTP 状态和响应体 code/msg。字段类型冲突参照知识库处理 1254060/1254061，读取真实列类型后只重试当前未成功批次。
• 报告类脚本默认一个任务一行，全部明细汇总在“完整报告”列；只有用户明确要求明细表时才按明细逐行写入。历史 Alexa 默认问题 1.4.0 的脚本内写表是逐问明细例子（1.4.4 已改由数据中心回传）：一次只接收一个 ASIN，7 条问答对应 7 行本地、Excel 和飞书明细，任务 JSON 仍是一份报告。
• 使用已有任务编号和业务对象标识判断重复，不额外创建或写入“记录键”列。同任务重试跳过已确认记录，同一对象的新任务保留新报告。中途失败要返回已成功行数，不得把部分成功报成全部成功，重跑时不得盲目重复追加。
• 测试至少覆盖：整组留空时 0 次飞书请求、半填时 0 次采集/写入请求、完整参数自动回传、空白表自动补齐字段；报告类脚本须区分报告数与明细行数；历史 Alexa 默认问题 1.4.0 自行写表的 7／501 条问答须产生 7／501 行，501 行验证 500+1 拆批且中间等待 700ms；所有新表字段为文本；限流退避；字段转换失败；部分批次成功。

这是脚本自己写入用户指定多维表格的规范，与任务完成后把报告推送到飞书机器人是两个独立能力，不得混用开关或凭据。

机器人通知的条件附件策略

声明 @sellerfeeds-notification，由平台根据实际返回结果决定通知是否带文件，不以输入中是否有 Token 判断成功：

// @sellerfeeds-notification {"mode":"link-on-success","successField":"wrote_feishu","urlField":"table_url"}

successField、urlField 指向报告字段，可用点分路径。新脚本的整体成功门槛还必须覆盖本地保存；本例的 wrote_feishu 只说明旧有写表判定方式，不能单独作为本地落库证据。当前执行顺序及需补齐的门槛见通用公约。任务完成、写表成功字段严格为 true 且返回有效表格链接时，机器人只发摘要和已确认链接，不生成或上传 Excel 附件。多条批量结果只有全部确认写表成功时才省略报告文件；失败、未写入、缺失链接或部分成功都保留报告文件。飞书多维表格与钉钉 AI 表格各有独立的写入状态与链接；一方失败不能隐去另一方已确认的链接，也不能声称双方均成功。未声明的旧飞书脚本沿用 wrote_feishu 与 table_url 判定。

采集成功但远端写入失败时，应返回采集结果、wrote_feishu:false、output_error 和明确提示，保留用户数据；不要只抛异常而丢掉采集结果。对于可能已经部分写入的请求，不要声称写入零条或自动重放。四个 Amazon 写入示例实现此流程。这个策略只影响手动／批量／定时机器人通知，不取消任务中心按需下载，也不新增重复的 MCP 机器人推送。个人 MCP 任务入队即返回 task_id，AI 随后可调用 get_report 读取本地 JSON；Excel 仅在用户下载或确实需要向飞书发送文件时生成。排查长耗时应分别计量页面采集与远端文件上传。

消息机器人与账号登录

插件账号继续由“插件精灵”微信公众号扫码、发送 6 位验证码登录。微信 ClawBot 是独立的可选消息机器人，扫码所得 Bot token 加密保存在本机，不替代账号登录。飞书应用机器人、钉钉应用机器人及微信 ClawBot 可在各自平台接收绑定者的自然语言指令；插件在本机按平台事件 ID 去重，向用户自己的 MCP Worker 发送消息正文与 Tool Schema，由 Workers AI 选择 Tool，再经现有 Durable Object 实时通道调用本机插件。完整报告保存在本机，由机器人直接回复用户；不经过 SellerFeeds 业务服务器。机器人来源任务不得再次触发普通任务通知。

机器人设置的开关位于各自配置 Tab 右上角。飞书通知和指令接收共用一个开关，绑定后默认开启意向；网站权限或本机凭据缺失时展示待授权状态。钉钉应用机器人保存后、微信 ClawBot 扫码确认后也默认开启接收意向；微信只有取得会话上下文并实际发送测试成功，才显示主动通知可用。飞书多电脑场景由用户个人 Worker 的 Durable Object 选主设备：主设备执行 MCP 并连接飞书消息，其他设备待命。旧 Worker 未重新部署时 MCP 调用仍可用，但飞书多设备接收保持关闭；主设备离线后待命设备接管。Worker 仅短期在内存保留事件 ID 哈希，防止切换期间重复执行，不保存消息正文或报告。

钉钉应用机器人需要企业应用的 Client ID、Client Secret 和 Stream 模式；首次启用后，用户私聊发送设置页给出的绑定口令，插件只接受已绑定者的指令。钉钉自定义机器人 Webhook 仍可用于任务通知，但不接收指令。应用机器人一旦启用通知，同一任务不再重复发送到旧 Webhook。微信 ClawBot 必须先收到绑定者的一条消息，拿到会话上下文令牌并成功发送测试消息后，才标记主动通知可用。两类机器人凭据与会话令牌只在本机加密保存，不进入 Tool 输入或报告。浏览器关闭时长连接/轮询不可接收指令。

MCP 与飞书／钉钉通知绑定相互独立；机器人未绑定不会成为 MCP Tool 的前置条件。手动、定时和批量任务仍按脚本声明归档业务数据，是否发送普通任务通知取决于脚本 @sellerfeeds-notify、渠道绑定、启停与实际权限。不要把通知可用性误写成脚本执行或本地数据读回的条件。

1.7.0 飞书自动写表公约

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

1.9 连接 API

二进制与 Multipart 请求使用 SellerFeeds.net.request()，SSE/分块读取使用 SellerFeeds.net.stream()；详细类型、上限与授权边界见 [Binary / Multipart / Stream](development/network-binary-stream.md)。

需要自然登录页面上下文的 offscreen 脚本必须声明 @sellerfeeds-session-bridge true， 页面捕获与后台读取 API 见 [Session Bridge](development/session-bridge.md)。不得用任务输入、 变量库或日志传递 Cookie/Token。

本机邮箱和无标签页网页 AI（1.9.51）

• [邮箱基础能力](development/mail-foundation.md)：脚本声明、逐邮箱读取／发送授权、附件格式、用户自有D1凭据同步及本地邮件数据边界。
• [无标签页网页AI](development/local-web-ai.md)：首次会话捕获、DeepSeek协议与任务附件；其他网站尚未开放后台协议，不能静默改用标签页或API。
• USER_SCRIPT与offscreen都有SellerFeeds.mail；MAIN world拒绝邮箱、网页AI、外部MCP和AI API等敏感能力。凭据不放Tool参数、日志、报告。
• 0030迁移、官方Worker发布、用户个人Worker重新部署和Chrome插件重载是独立步骤；本地打包不能替代线上部署或真实账号验收。
• 1.9.53 的 mailOAuthFailure 区分刷新、授权码兑换与浏览器回调失败，只输出安全错误类别和 AADSTS 编号。原始 OAuth 错误描述及令牌不进入消息／日志／报告。先取得真实编号再决定客户端兼容修复，不能凭 invalid_request 推断令牌过期或浏览器跨域限制；详见邮箱开发说明。
• 1.9.54 的 Outlook 刷新请求明确发送 https://graph.microsoft.com/.default，选择原已授权的 Graph 权限，不混合动态 scope；不更改 Gmail 或浏览器授权码兑换。90023 已知描述仅转换成固定诊断分类，不能用于自动重试／变更网络路径。用户已实测 90023，但具体原描述与修复后的真实收发仍待验证。

• 1.9.55 Outlook 可选 oauth.tokenMode=desktop 兼容导入的桌面凭据；默认 browser，浏览器登录成功恢复 browser。精确令牌刷新请求使用本插件临时 DNR rule 21801，串行执行并清理，不自动重试；成功轮换先保存，邮件仍本机／代理直连。该模式随账号 D1 加密同步，不新增迁移。见 [邮箱开发说明](development/mail-foundation.md)，真实账号仍待验收。

Outlook 两字段添加（1.9.56）

Outlook 默认只需公共 Client ID 和 Refresh Token，保存时识别邮箱地址；权限不足可补填地址。密码、两步验证资料和辅助邮箱是折叠的可选账号资料，不是脚本参数，不参与 OAuth 登录。脚本继续通过 SellerFeeds.mail 使用获授权的账号 ID；不能取出上述资料。插件将轮换的新 Refresh Token 先本机加密保存再同步账号，身份识别或同步失败也保留新版本。完整规则与验收边界见[邮箱开发说明](development/mail-foundation.md)。

邮箱 UI 自 1.9.57 使用账号列表 → 单账号收发工作区，配置在共享弹窗，标准文件夹仅在展示层中文化；详见 [邮箱基础能力](development/mail-foundation.md)。脚本 SellerFeeds.mail 调用契约和 OAuth 轮换保存规则不因布局变化而改变。

邮箱基础字段自 1.9.58 起始终可见；名称默认用地址，完整 IMAP 登录邮箱可补全地址。旧失败配置作为可编辑草稿保留，不能让一条空配置阻塞所有同步；详见 [邮箱基础能力](development/mail-foundation.md)。

邮箱自 1.9.59 默认进入本机历史。统一自动收取设置默认关闭，只收摘要；正文和附件明确读取后缓存，不因摘要更新覆盖。脚本 getMessage／getAttachment 复用缓存但仍须活动任务及逐邮箱授权。大邮箱分页续取和 IMAP MIME 传输限制见[邮箱基础能力](development/mail-foundation.md)。邮件缓存不自动上传官方或四个中心备份。

邮箱凭据云与内容备份（1.9.60）

邮箱连接和逐脚本授权改到用户自己 Cloudflare D1，官方 kind=mail 只用于显式迁移与条件清理，当前不接收新邮箱凭据。邮件摘要／正文／附件仍本机，手动内容备份仅本人百度／WebDAV，不进入Cloudflare持久化。脚本 SellerFeeds.mail 契约、邮箱ID与活动任务授权不改变；无需在脚本中写Cloudflare地址、密码、OAuth或备份通道。开发细节和真实验收边界见 [邮箱基础能力](development/mail-foundation.md)。

私密空间能力边界（1.9.61）

当前记事本可由声明并绑定用途的脚本读写，账号与两步验证可由插件代填；旧版仅管理页使用的限制属于历史规则。密码与验证密钥仍没有读取 API。不得把密码、TOTP 种子、恢复密钥复制进 Tool 输入、报告、官方同步或宿主网页。用户自有个人数据云只保存密文，与脚本任务云、邮箱本机内容分开。入口、加密、同步冲突、QR 构建依赖和真实验收限制见 [个人私密空间开发文档](development/personal-library.md)。

1.9.62 Warden 密码库边界

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

1.9.65 脚本基础能力与个人空间

新脚本先阅读 [脚本基础能力与个人空间](development/script-capabilities-and-personal-space.md)。声明 AI、MCP、邮箱、网页版 AI、文件保存或凭据代用，安装时确认，并按 Tool 选择服务。不得把秘密作为参数，不能读取密码、验证码种子、API Key 或 Token。示例和后台身份校验、文件格式及网站边界以该文档为准；原授权按钮说明仅适用于历史版本。

图表建议声明（2.1.16 本地预览）

可选的 @sellerfeeds-charts 帮用户直接查看报告图表。插件仅读取当前脚本已经保存的本机报告；声明本身不运行脚本、不调用 AI、不联网，也不自动把图表加入用户看板。没有声明仍可在数据中心手动选择指标。

// @sellerfeeds-charts [{"id":"price-trend","dataset":"prices","title":"商品价格变化","metric":"price","time":"date","objectField":"sku","aggregate":"last","chart":"line","bucket":"day"}]

只声明一次，值为最多 12 个对象的 JSON 数组：

声明使用字段名，不写配置 ID、密钥、地址、可执行代码或跨脚本引用。dataset 必须对应 SellerFeeds.data.define 中的 name 或 @sellerfeeds-local-data 的 dataset.name；由运行器自动归档的普通返回值使用 archive-<Tool 名>（非字母数字下划线连字符替换为下划线，Tool 部分最多 65 字符）。紧凑报告使用 字段 数组里的名称；其他报告使用实际顶层字段。

插件校验建议格式，并只展示数据集和实存字段匹配的建议。校验不能证明作者声明的业务口径一定正确：每日新增销量可求和，累计销量通常不能相加。不要仅凭字段叫“销量”就写 sum；价格/排名按对象取最后一次采集，必要时说明业务日期与采集日期的差别。

这些是展示建议，不属于新增执行权限。既有用户图表保存的是独立的配置，不随脚本更新自动改变统计口径。用户需要先预览，再主动添加到看板。所有统计仍在本机进行，不补造被覆盖的历史或缺失日期。

图表的 X / Y 轴与无时区报告（2.1.17）

管理页直接让用户选择图表类型、X 轴、Y 轴。折线图以日期为横轴；柱状图按字段类别比较；散点图以两个数值字段为坐标，每条有效明细一个点，不求和、不连线、不按对象去重。散点超过 1000 个时明确要求缩小范围，不返回不完整抽样。指标卡继续保留。数值缺失不补零。

@sellerfeeds-charts 建议可增加 timeMode: "calendar" 与 report: "latest"。默认分别为 "utc" 与 "all"。日历模式只接受有效 YYYY-MM-DD 或无时区 YYYY-MM-DD HH:mm[:ss]（分隔符也可为 T），保留原报告日期，不声称转换到 UTC；其他格式不猜。report: "latest" 只读取采集时间最新的一份完整记录，空报告不会回退到旧记录。用户可在管理页改为固定任务或合并全部报告，合并时重新确认统计方式。日历模式的 last 在同一报告内按业务时间选择最后有效数值，与数组顺序无关。日期范围仍按所选时间模式解释，近 7/30/90 天的日期端点以当前 UTC 日期计算。

例如 SellerSprite 历史趋势声明：

// @sellerfeeds-charts [{"id":"bsr-history","dataset":"sellersprite-competitor-history-trend-reports","title":"BSR 排名趋势","metric":"BSR","time":"时间","aggregate":"last","timeMode":"calendar","report":"latest"}]

已有同格式历史报告有内置展示适配，不需要重新采集或复制数据。报告选择展示原记录里的站点、ASIN、任务与采集时间；缺失元信息不推测。固定任务保存后不会跳到另一个任务；“最新一次”明确随新的任务更新。散点图为管理页用户选项，本轮脚本建议声明仍只接受 line / bar / metric。

时间横轴（2.1.18）

管理页的 X 轴保留实际报告字段；无法识别的时间列仍可选，解析失败提示选择“调整图表 → 时间格式”，不会改读采集时间。散点图支持时间或数值横轴，时间散点每条明细一个点，保留时分和原始时间标签，不按日汇总。2026-09-15 06:59 使用原始日期时间模式，不推测报告时区。绘图用的数字坐标仅用于排列点，不代表报告时间已经转换为 UTC。

用户可明确选年月、Unix 秒或 Unix 毫秒。年月记录保持月份标签、按月汇总，日期筛选包含范围涉及的月份，不伪造某日观测值。数字不能自动推断为 Unix 时间；秒/毫秒转换后按 UTC 表示。此处格式选项为管理页功能，不扩大脚本 @sellerfeeds-charts 的声明枚举。刷新会更新字段列表并保留当前选项；未识别或消失字段不静默替换。

3.0.12 本机补修（2026-10-20）：带未读提醒的功能点击后打开最新结果批次；数据结果统计以批为单位，表格保留行数。已审计旧脚本的同步/找回副本保留输出兼容，原始结果仍须包含结构化明细。功能介绍、基本信息与完整 Tool 说明集中在介绍与管理；配置保留权限和开关。本机包与生产发布分别记录。