BBAuto 操作指南
查看原始 Markdown 返回首页 业务指南
完整正文与本版本 /manual.md 一致。按目录查找步骤，或从业务指南选择操作路线。

BBAuto 用户操作指南

更新：2026-10-20。增加 AdsDoubler（AD）账号、渠道、Offer 与交易复核说明；保留 MCC v6、首次配置、Kookeey、状态监测等指南。页面入口仍随权限、内部版本和订阅规则变化。

AdsDoubler（AD）接入

在“联盟管理 → 联盟账号”选择 AdsDoubler（AD），填写账号名称、API Token、数字 Channel ID，先“检查连接”再保存。一个账号绑定一个渠道；多个渠道分别新增 AD001、AD002 等账号，相同 Token 共用查询频率。已有 Offer/任务的账号不能直接换绑渠道。

在外部 Offer 池选择 AD，可查看全部商家或筛选尚未申请、申请中、被拒、已批准。查询过程中可停止并操作已找到结果，再从原位置继续。合作申请请在 AD 后台完成；未批准或缺推广链接可以查看、按校验结果入库候选，但不能一键创建任务。“全球（WW）”不是具体投放国家，建任务前必须选择实际国家。

AD 返回的是当前渠道的合作状态，不提供独立上下架字段。详情的“正常 · 合作已批准”不代表实际推广链路已验证，也不等于获准品牌词竞价。分页不完整、限流、网络或授权异常不判断下架。手动 Offer 可以通过“设置状态检查”选择准确商家，只补充检查关联，不修改原链接。

任务链接副本写入 uid；交易必须同时符合任务 UID、AD 账号、渠道和商家身份才归因。金额按交易接口文档的 USD 处理；商品 quantity 不是订单数。同订单多条交易只记一单，不同渠道/商家的同号订单分开统计。

AD 交易接口按原交易日期读取，不能按更新时间过滤。系统分段获取近期交易并滚动复核历史状态（账号中默认 180 天，可调整）；更早的已知待确认交易继续复核，更早终态更正需扩大范围或补拉历史。同步未完成会保留分页进度，不把第 200 页截断当作成功。未配置渠道的数据不会记到其他账号，数据冲突单列为待核实。

MCP 提供 save_ad_alliance_account（Agent 侧确认后保存）、check_ad_alliance_connection（只读）及现有查询、停止/继续、入库工具。不会回显 Token。真实已批准推广链接与含 UID 的订单正例尚需实际样本验证；不保证佣金、收益或 PPC 合规。

完整说明见 AdsDoubler（AD）接入指南。

1. 从官网到首次登录

1.1 准备与安装

准备一台可 SSH 登录、可访问互联网的 Ubuntu VPS，使用具备管理员权限的账号连接。安装程序支持域名 HTTPS 和公网 IP HTTP 两种模式；域名 HTTPS 更适合生产使用。没有域名时也可选择 HTTP，但网页登录凭据和 Agent 令牌在公网传输时不加密。

在 VPS 执行以下固定安装命令。安装脚本从公开 stable 渠道选择镜像，不需要 GitHub PAT 或手动拉取应用仓库：

curl -fsSL -o /tmp/install_vps.sh https://raw.githubusercontent.com/wd9337812/bbexchange-installer/main/install_vps.sh
sudo bash /tmp/install_vps.sh

按终端提示选择访问方式，记录安装结束时显示的用户端地址。运行远程脚本前可先查看脚本内容。首次访问该地址，按页面指引初始化管理员并登录。

1.2 订阅与初始化

当前产品对外只展示“全功能版”，没有 Lite／Pro／Max 套餐选择。登录后进入“系统设置 → 订阅管理”查看状态、账单及续费入口。功能能否执行还取决于订阅是否生效、当前账号权限和所需外部服务配置。

建议先完成：联盟账户与 Offer、Google Ads 执行模式和账户、素材 API／AI 服务、告警与团队权限。涉及 Google Ads 真实写入的动作请先用测试任务核对账户和参数。

新装路径为“设置管理员账号 → 登录 → 开始使用”。管理员初始化只执行一次，不是密码重置入口；有效试用无需先付款。试用已到期时显示真实到期时间，不重新承诺 7 天试用；不足一天显示“剩余不足 1 天”。已有授权回跳或明确业务链接优先于引导。

续订前先预览计费周期、优惠、本次应付及生效日期，再确认建立订单。试用可用与订单是否付款是两件事；支付页的成功／取消回跳也不是付款凭证。以本次订单的支付确认和订阅应用记录为准；下周期生效会明确显示。刷新可恢复原订单，查询失败请勿重复付款。到期后也可在订阅页面登录以恢复已有订单；订阅生效后返回原业务页面，已有配置和任务保留。

到期限制当前后台与业务接口访问，不会自动删除任务或代你暂停 Google 广告；现有 Worker 不会因订阅到期自动停掉既有调度。请自行核对广告实际状态，续费不等于自动启动任务。

已登录管理员在原系统设置中修改密码。忘记密码时只能由具备 VPS 管理权限的人员在服务器本地执行恢复工具：docker exec -it bbexchange-api node apps/backend/scripts/recover_admin_password.js。工具要求明确确认并隐藏密码输入，先备份管理员配置；不提供公开重置接口，不重新初始化系统或清理业务数据。

1.3 已部署实例升级

升级与新装是两条路径。已部署用户在 VPS 执行下列固定更新命令；不要用新装命令代替升级，也不要传旧文档中的 latest 参数：

cd /opt/brandbidding && \
curl -fsSL https://raw.githubusercontent.com/wd9337812/bbexchange-installer/main/scripts/update_image.sh -o scripts/update_image.sh && \
chmod +x scripts/update_image.sh && \
bash scripts/update_image.sh

更新程序按公开 stable 指针拉取版本并执行自己的检查。运行前确认备份可用；更新后刷新页面，检查“总览看板”“任务列表”和系统日志。若安装目录不是默认的 /opt/brandbidding，先切换到实际目录。

2. 页面导航与第一次建任务

左侧菜单主要分为“总览看板”“任务管理”“联盟管理”“自动化”“系统设置”。没有相应权限或订阅未生效时，菜单和操作可能隐藏或不可用。

外部订阅版本新增“开始使用”：按订阅/权限、账户配置、一个内部 Offer、品牌词/素材与任务预检、首次执行、真实日报逐步检查。入口和卡片只查询当前配置与数据，不自动取词、生成素材、创建广告或启动任务。创建入口打开原任务表单，首次路线保存前调用只读预检；正式保存仍以原服务端校验为准。内部版本不显示“开始使用”和操作指南入口；系统初始化、配置入口与 MCP 机器安全指南仍保留。

系统只有一个全功能版，试用与订阅的区别是有效期，不是功能档位。有效试用直接进入配置；订阅与续费只需选择周期及支付方式。首次正常登录尚未建任务时会打开“开始使用”，可以选择“稍后配置”；总览顶部与侧边栏可继续配置。授权、支付回跳与明确业务链接优先，不被引导中断。

步骤分别显示“未配置”“已保存，待测试”“已验证可用”“检查未通过”或“请管理员配置”。动态 IP 通过当前配置的 HTTP 和浏览器实际出口核实才标记可用；保存或修改配置不等于测试通过。AI 测试在素材 API 配置页主动发起；品牌词、素材及广告不会由引导自动生成。联盟成功同步、广告账户成功请求或脚本当前账户心跳都是核实依据，不能仅凭存在密钥判定完成。第一份真实日报须有同任务的广告与联盟数据，没同步订单不代表零订单。

引导分为“连接账户、准备首任务、运行核对、查看日报”。创建或选择首任务后，仅核对这个任务的联盟账号、广告账户及 Offer 品牌词，不用其他账号的成功数据代替。主动点击“核对并记录进度”会由服务器核实证据，历史完成与当前可用状态分别保存；单纯查看或 Agent 查询不会改写人工进度。配置变更或数据过期可显示待复查，但不抹掉历史完成记录。

首次入口仍使用原任务表单，按“选择推广内容、准备广告内容、广告与运行设置、预检并确认”分组，高级设置保留原默认值。保存首任务后系统任务保持暂停，请查看创建结果再明确启动；普通任务管理的原创建行为不变。“同时创建广告”开启时会提交启用广告，Google 执行后可能产生消耗，任务暂停不等于广告暂停。脚本模式须等待对应 MCC 的成功回执，提交、领取或心跳不算已生效。

首份日报核对同一任务的广告日期及对应联盟账号的同步窗口；成功覆盖该日期且无订单时，零订单是有效结果。未同步、部分上报、失败和真实 0 分开显示。任务日报的 CPC、订单数及原归因口径不变。

2.1 配置联盟与 Offer

在“联盟管理 → 联盟／联盟账户／Offer”维护自己的联盟账户和内部 Offer。外部 Offer 池位于“自动化 → 外部Offer池”，默认查询联盟最新资料。名称与准确编号分开填写；同时填写须同时匹配。支持的联盟优先按编号直接查询；没有名称直查能力时，系统先用已知真实编号联网核实，其余可继续查找，随时可以停止并保留结果。搜索不调用 Google/AI，也不创建投放任务。“加入我的 Offer”沿用原入库流程；入库前核对商家、国家、Final URL 和品牌词。

在“系统设置 → 联盟交易同步”配置同步窗口和账户后，可查看同步记录及失败原因。不同联盟的数据口径和延迟可能不同。

2.2 配置 Google Ads 与素材来源

进入“系统设置 → Google Ads”，按实例当前执行模式配置服务账号、MCC 与广告账户，必要时查看账户、系列、请求治理和 Script 页签。API 模式的 Google Ads 请求走系统统一频控；MCC 脚本模式是异步执行，部分实时查询和 Google 关键词 Provider 不可用，不能把未知余额当成零。

进入“系统设置 → AI 与关键词”配置 AI／关键词来源。使用 Google Ads 品牌关键词时，系统从 Google 获取候选词后经 AI 筛选，按原顺序取品牌相关的 Top 10；生成失败或没有合格词时应检查配置，不要自行编造。广告标题、描述及可选 Sitelink／Callout 也须在保存前核对。

动态 IP：Kookeey 两种接入方式

入口“动态 IP”。选择 Kookeey 后，可明确选择“官方接入”或保留原高级自定义配置；系统不会自动覆盖已有网关、端口、Token 或密码。API 提取填写开发者 ID、API Token、住宅／移动产品、HTTP／SOCKS5；由服务端按官方协议签名并按目标国家提取，默认共享 5 QPS、最多 10 QPS。人工测试与任务共用账户限流，等待不会改用 VPS 裸 IP。账密也需确认代理产品；移动产品的网关／端口按供应商控制台填写，不套用住宅预设。基础密码为 8–24 位字母数字，不含国家、会话后缀；完整连接串可在本页拆分导入。指定国家的任务不能改用全球混播。

“代理连接检查”通过保存的代理，在任务执行环境访问一次内置的纯 HTTP 出口检测地址。不接受 Offer、推广链接或任意 URL；不启动浏览器、不占浏览器并发、不额外查询定位服务，也不自动跟随 HTTPS 跳转。检查消耗少量代理流量。检测地址故障、检查繁忙或工具异常表示本次未完成，不等于账号密码错误。

账密方式的用户名由用户 ID 和安全用户名组装，密码按基础密码、国家、会话和轮转规则生成。住宅默认网关 gate.kookeey.info:1000，移动默认 mobile.kookeey.info:1086；仅点击填入默认值时才修改。每轮访问使用独立会话，同一轮 HTTP、浏览器回退和重启接续保持会话；全球轮转与定向国家不同，测试应核对实际出口。

保存后主动点击“检查代理连接”。成功表示本次 HTTP 请求经代理完成并返回有效公网出口 IP，不代表 HTTPS、浏览器或具体 Offer 已通过。检查国家用于获取代理，不是测得国家；出口国家未检测时明确显示“本次未核实”。失败时看具体环节；检测地址不可用可选择备用地址。最近成功记录注明时间及范围，不代表本次通过。原自定义接入及其他服务商仍可使用。

Kookeey 官方 API 提取需要验证服务器白名单时，先在供应商后台添加本 VPS 的真实公网出口 IP，获取新的验证链接。在本页“白名单验证”中粘贴并点击“从本服务器访问验证链接”，后台只直接访问一次，不走 Worker 队列、不使用动态代理、不购买流量或修改白名单。访问返回 HTTP 200 不等于供应商确认成功，以页面业务结果为准；链接无效或可能过期时重新获取。验证成功后仍须单独检查代理连接，二者不会互相冒充成功。

后台可以继续使用 http://公网IP，无需域名或网站证书。Kookeey 验证链接和 API 本身是 HTTPS，服务器仍正常校验远端证书，不能关闭 TLS 校验。标准单 VPS 通常共用公网出口；若 API 与 Worker 分机或使用自定义路由，应分别核对实际出口。本页不长期保存完整验证链接，请勿公开分享；裸 HTTP 后台的提交不是加密连接，应在可信管理场景操作。

2.3 创建并检查首个任务

操作路径：“任务管理 → 任务列表 → 新建任务”。

  1. 选择任务类型、关联 Offer、国家、访问与换参设置。
  2. 若同时创建广告，选择正确的 Google Ads 绑定，核对预算、出价、品牌关键词、标题、描述和 Final URL。
  3. 先用小范围测试任务验证配置，再保存。保存后的执行状态不等于广告立即生效；脚本模式下广告指令可能仍在等待 MCC 脚本。
  4. 返回任务列表查看状态、运行记录和错误；需要一次创建多条时使用“任务管理 → 批量创建任务”。

任务访问（visit）与换参（replace）是不同动作。暂停本地任务或发出脚本模式广告暂停指令后，如需紧急停投，请直接在 Google Ads 中确认。

3. 业务功能

3.1 总览与报表

“总览看板”提供业务概览；“任务管理 → 任务报表”用于按任务、日期和其他筛选条件查看结果。联盟转化和 Google Ads 点击／花费可能存在不同时间口径及同步延迟，做决策前检查筛选条件和归因说明。

“总览看板”先展示今日与累计总数据，其后是经营待办、归因质量、趋势、排行榜和分日汇总，内部版本的联盟报表也保留。先选择日期范围，再看日表和排行榜；日行可下钻任务排行，Offer/账户行可下钻该范围内的任务汇总。排行榜先聚合完整筛选范围，再排序和分页，不只比较当前页。

“经营待办”默认统计当前任务：财务异常和 Offer 提醒统计运行中任务，执行失败统计运行中或执行错误任务。暂停任务通过“暂停任务历史”单独查看，不混入当前经营风险。“尚未设置状态检查”单独展示为设置提示，不是经营异常。财务异常显示 ROI 低于设定值、佣金久未确认、拒单佣金占比偏高；Offer 状态显示疑似下架、合作被拒、下架/终止/暂停、缺货/链接失效、近七天恢复或重新查到。任务执行与检查默认收起，非零的执行失败、状态待核对等数量仍显示在摘要中，点击摘要可展开明细。点击分类先打开汇总弹窗，从单条记录“查看任务”进入精确任务编码筛选；返回看板保留分类、分页，快照过期时刷新汇总。提醒数字的红、黄、绿分别辅助区分明确异常、需核对与恢复，灰色 0 仅表示当前分类没有匹配任务；未开启或数据待更新会显示文字，不当作正常。刷新失败保留上次结果并提示。

规则沿用“系统设置 → 告警配置”，不另建经营规则。ROI 按运行中任务累计账面佣金/广告消耗计算，拒单佣金占比按配置的最近 N 天“拒单佣金/账面佣金”计算，不是拒单订单占比。等待确认只统计仍待确认、有可靠原交易日期的去重订单；在待办弹窗点击“查看待确认订单”，可核对订单编号、原交易日期、等待天数、待确认佣金与超期情况，缺失日期单独说明；批准、拒单、缺失日期或状态不明确的记录不制造超期。未开启显示“未开启监测”，同步过期或缺汇率时不生成虚假的财务异常。没有飞书通知权益或 Webhook 不影响工作台查看，飞书发送仍受订阅控制。原自动化策略独立配置。

Offer 汇总中的近七日广告消耗只是关联任务的日累计消耗，不是异常造成的损失，也不能推算下架之后的实时消耗。

任务列表、任务汇总、任务日报、经营日报/排行榜、CSV 和对应 MCP 报表增加 CPC（USD）和订单数。CPC = 选择范围内广告美元消耗合计 / 广告点击合计，不平均各日 CPC；零点击或美元换算缺失时显示“—”。UI 保留四位小数，接口为六位。订单来自联盟交易，不是 Google Ads conversions；按联盟、联盟账户和业务订单号去重，缺订单号时按唯一交易号计数，覆盖待确认、确认、拒绝等状态，状态更新不把订单移到更新日。无广告/联盟同步记录不等于已观测到数值 0；接口的 dataQuality 和生成时间用于判断数据完整性，报表快照最多缓存十秒。

3.2 已创建任务的 Offer 状态

在“任务管理 → Offer 状态监测”查看 Offer、联盟账户、当前状态、合作状态、最近变化和检查时间。详情默认显示业务信息与状态变化，技术 ID 和错误码收在“高级检查信息”。列表只读本地快照，页面刷新不发起联盟批量实时请求。

“正常”要求查到对应 Offer、合作已批准且可用状态经过核实。“已下架”“合作被拒/终止/暂停”只根据明确枚举；曾查到后连续完整成功检查未查到，达到配置次数（至少两次）且相隔至少三十分钟才标“疑似下架”，第一次显示“本次未查到，等待复查”。没有历史基线不推断下架。401/403/429、超时或分页不完整保留上次业务状态，另标检查失败、等待查询额度、检查进行中或状态待更新。只有 Joined 或在库查询能力的联盟，无法从缺失判断真实合作状态。

只有此前已确认未查到、下架或合作异常后重新查到才记录恢复事件；仅一次未查到后又查到不制造“恢复”。但合作仍 rejected 时当前仍显示“合作被拒”，不会标成正常。“恢复上架”需要明确可用枚举，否则写“重新查到”；“发现时间”是系统检测时间，不是联盟实际变更时间。Amazon 按原 ASIN 和商品国家查询，GB 与 UK 按同一市场处理，多国家时需明确选国家。当前 Amazon 接口的清单可能只包含可投或有货商品，查不到只表示“当前可投清单未查到，原因待核实”，不能判下架、缺货或合作被拒。只有明确字段才能判断缺货／链接失效；单独链接状态不能证明商品仍在架。

直接新建 Offer 没有联盟 Offer 编号是正常情况，保存和投放不要求先设置监测。未设置时显示“尚未设置状态检查”，不判断为下架或异常。在“联盟管理 → Offer”点击“设置状态检查”，或保存 Offer 时选择“保存后设置状态检查”；任务 Offer 详情也提供同一入口。先按名称查找当前联盟账号下对应的 Offer，也可展开“填写联盟编号”。可以查已保存记录或主动从联盟实时查询，不要求管理员先同步外部池；名称只用于找候选，必须选中真实结果后确认，不按名称或域名自动绑定。保存只补充监测信息，并展示相关任务数量，不改推广链接、任务参数或投放设置。同一 Offer 可供相关任务复用；仅本人权限且 Offer 被多人使用时，只设置当前任务。改变账户、商品、国家或渠道后旧证据不沿用；清空品牌词流量表不会清掉独立身份与监测历史。

后台独立于 visit/replace 队列，每分钟最多处理一个账户来源组，运行任务目标间隔三十分钟、其他任务六小时，实际受来源接口、共享预算和排队情况影响。每次只读请求有间隔、每账户监测默认上限六十次/小时，前台读取优先；人工请求刷新五分钟冷却，排队不保证马上完成。监测不访问 Offer 跟踪链接、不生成联盟追踪链接、不触发 Google Ads 写入、不修改任务状态。飞书异常/恢复/授权提醒复用现有告警能力和订阅权限。

3.3 Agent 使用新增能力

经营监测规则与网页告警配置共用。有系统配置权限时，先用 get_business_alert_config 读取当前值，再用 update_business_alert_config 提交明确的 changes 和唯一幂等键；修改前展示前后差异，并由用户在 Agent 的确认表单中同意，不需要返回网页批准。此工具不能修改飞书凭据或任务自动停止设置。

任务报表、日/周/月汇总及排行榜可以按任务类型 merchant_site／amazon_product、投放状态“测试中／暂停中／跑正中／已停止”、日期和归因范围查询；CPC 与订单数排序使用 cpcUsd／orderCount。其他参数及取值以工具 inputSchema 为准，不支持的筛选会报错，不会静默忽略。汇总接口的 from／to 筛选累计期间，不改变“今日”口径。

系统设置 → Google Ads 显示实际 API 主版本。服务器及新生成的三个 v6 通用脚本统一使用 v25，低于 v25 的旧配置自动升级。已经粘贴到 Google Ads 后台的旧脚本不会自动替换：仅升级 API 主版本时替换原代码并保留计划；需要扩容时，可按三脚本协作指引新增同类脚本。Agent 可用 get_google_ads_api_runtime 查看版本与更新说明，此工具不会请求 Google。升级后刷新工具列表并重新读取机器指南。

Agent 首次接入或指南版本变化时先读取 get_agent_guide。get_operating_summary 返回分类与 snapshotId，list_operating_todos 按 category、snapshotId、page、pageSize 和 todoScope 读取明细；默认 current，暂停任务历史为 paused；409 时重取汇总。monitor_setup 是中性设置提示。list_task_overdue_orders 核对原交易日期、等待天数和待确认佣金。list_task_offer_status、get_task_offer_status 查看状态与历史；needsReview 的旧记录不能作为新风险依据。补充监测信息时，用 search_task_offer_candidates / search_offer_status_candidates 找当前账号下的结果，再用 setup_task_offer_monitor / setup_offer_status_monitor 提交返回的 candidateRef 和幂等键；写入必须在 Agent 确认表单逐次同意，禁止猜编号或跨账户关联。Amazon 同时提交明确国家，ASIN 来自原 Offer；不得生成新推广链接来检查状态。旧 list_task_offer_projects / select_task_offer_project 保留兼容，新客户端使用新工具。request_task_offer_refresh 只排队查询，不停任务。新增报表字段 cpcUsd、orderCount、dataQuality 与网页口径相同。内部版本隐藏人工引导不等于免除 Agent 的机器安全指南。

重型报表最多同时执行两条 SQL，等待队列最多八条；返回 503 REPORT_BUSY 时至少等待五秒再试，复用筛选或缩小日期，不要并发重试。默认缓存十秒，以响应 meta.cacheTtlMs 为准；缓存数据不会用来替代原自动化决策。

3.4 外部 Offer 池与自动化

“自动化 → 外部Offer池”包含独立站 Offer、Amazon 商品、待创建清单、品牌词 Offer 推荐。Google API 模式下，自动、手动、历史补全、修复及跨天续办共享全局“每日分析总上限”；0 或空值不能作为无限量。多个联盟账号每轮各安排一份，账号内补全和修复优先。推荐列表只增加有分析依据的新结果，已有结果补全后原地更新；失败或补全旧资料会使新增行数少于当日分析上限。一份分析可能包含多次 Google/AI 请求，失败的已发请求不退回名额。暂停和重启不重置已用额度；移出未开始项只释放预留。升级前当日使用量无法完整核验时，当日停止新增分析，次日恢复。查看、导出和纯离线重算不调用 Google/AI。推荐不保证投放收益；自动创建任务前请检查规则和副作用。

3.5 团队、告警与运维

“系统设置 → 权限管理”配置角色及数据范围；“审计日志”“系统日志”帮助追溯操作和排查失败。“告警配置”可设置通知渠道。“数据备份”用于确认备份状态；正式升级或重要变更前应检查最近一次备份。“动态 IP”用于代理与访问国家相关配置。

5.1 查看任务执行资源

有系统配置权限时，在“系统设置 → 系统日志 → 运行状态”查看 Worker 工作集、浏览器访问并发、等待名额、资源延期累计次数和近 30 分钟采样。打开运行状态页才读取资源，点击刷新获取最新缓存；后台每 15 秒采样。超过 60 秒为过期，未取得不是零。部署没有容器统计时会明确说明，不影响任务执行。

新装默认自动按资源配置：名义2/4/8/16/32GB建议1/2/6/8/12个浏览器上下文，且不超过有效CPU核数的两倍。4核8GB推荐6，8GB2核推荐4；容器限制与压力可减少实际准入，8个不是自动默认值。已有显式设置保持不变。代理与普通访问共用上限，每轮独立上下文，仅复用浏览器进程。资源不足时延后同一轮并保留代理、UA和访问参数，等待不计业务失败；在途访问先完成再回收。运行状态分别显示来源、建议、配置上限、当前准入和保护原因。

资源延期次数是本次 Worker 启动以来的累计次数，不是异常任务数。延迟队列还包含正常按计划等待的访问；历史失败作业不等于当前失败任务。内存容量看容器工作集，进程 RSS 包含共享页不能相加当整机实际内存；Docker Desktop 下 Linux 可用内存是虚拟机口径。8GB 能跑多少任务还取决于页面复杂度、访问频率与其他服务，不给固定保证。

Agent 升级后刷新工具列表并读取 get_agent_guide；有 system.config 权限时可使用 get_execution_resource_status 只读查看上述资源。它不提供 SSH、任意命令、重启或自动调参，采样过期时先刷新核对，不能自行改变访问策略或暂停任务。

访问频率与换参等待

脚本模式分别设置“访问频率（秒）”与“每N次换参脚本运行换参一次”。VPS按秒访问并保存最新有效参数，不因脚本未运行或等待回执停止正常Visit；只有换参到期才领取新近参数。新任务建议120秒访问、每1次有效运行换参；API模式原秒级访问与每访问N次换参不变。MCP对应字段为 scriptVisitIntervalSec 与 scriptReplaceEveryRuns。

脚本定时运行最小间隔为1小时；系统只为真实有效换参运行机会计次，同类副本、跨MCC可达和手动补跑不重复计次。达到N但本次未完成可立即补跑，不必重新等待N次；没有实际运行不按时间补次数。成功回执才增加换参成功次数；未知结果先核对、不盲目重发。领取当时取最新有效参数，不延长原始交接寿命。旧任务升级保留原实际访问间隔，不突然激活隐藏的10秒值；用户可明确调整访问秒数。

脚本监测默认看最近 24 小时，可切换 1 小时／7 天；旧 API 样本、手动执行及非生效时段不混入正常频率。少于 20 个有效样本不显示 P95。总览四类提醒为“广告脚本未按时运行”“换参等待过久”“换参失败／结果待核实”“广告报表待更新”；点击数字先看任务汇总，再查看单条进度或跳转筛选。普通等待不等于失败。

在 Google Ads → Script 的 MCC 详情填写 Google 后台已确认的运行间隔，例如每小时为 60 分钟；留空表示尚未确认，系统不报运行超期，也不会自动更改 Google 的计划。心跳和新一轮开始分开记录。原告警页可开启运行、等待和报表提醒，共用飞书设置，同一连接合并通知，恢复后关闭该次提醒。

API 模式的脚本页只提供“数据同步脚本”；广告创建、调整和换参仍走 API。脚本模式提供换参、广告管理、数据同步三类 v6 脚本，后台自动分配同类副本工作，无需手工分片。Google API 主版本仍为 v25。

本次数据同步模板修订为 script-status-20261021。更新用户端后，在需要同步的 Google MCC 替换“数据同步脚本”、保存授权并正式运行一次，再保留每小时计划；预览不等于实际同步。API 用户无需切换模式，另外两类脚本不因本次投放状态功能强制更换。旧 hourly 仍兼容原有统计，但不含新增投放状态，应以新版同步脚本替换，而非长期并跑两种上报。

广告系列投放状态由同一数据同步脚本独立读取，覆盖零消耗、暂停、移除和结束的已关联系列，不等待整个目录完成或目录过期。任务列表只读本地结果，不再为状态标签单独调用服务器 Google Ads API；原 API 广告操作不变。MCC 详情分别显示目录、报表和投放状态覆盖，成功工作项数不等于已同步系列数；部分完成后可补跑接续。旧脚本不能清空或续期新版状态。

报表按广告账户当地日期完整批次入库。未完成的页不冒充完整日报，迟到旧批次不覆盖新批次；旧脚本未核实批次与过期数据不参与低 ROI 判断。仍保留日数据及各维度排行，CPC 为总消耗／总点击，订单数来自联盟交易而不是 Google 转化。Agent 可用 list_task_script_operations 查询回执，每次至少间隔 30 秒；不要反复提交不确定写入。

脚本运行、换参等待与报表更新提醒沿用“告警配置”的总开关和飞书配置，可分别启停。管理员的 Agent 可通过 get_business_alert_config 读取、在你逐次确认后用 update_business_alert_config 修改 scriptMonitoring 的 run、wait、report 开关；省略的开关保留原值，不会改动通知渠道或自动停任务规则。

任务列表的“访问周期 / 执行节奏”展示设置周期与最近实际Offer请求启动间隔。点击查看最近1小时或24小时的计划访问、实际启动、延迟与浏览器等待/占用；至少20个正常样本才展示P95。成功访问间隔表示业务产出，不等于启动间隔。没有样本、历史未采集和监测过期不是0或正常。手动执行、暂停、非生效时段、脚本周期不纳入API秒级异常判定。

总览点击延迟/等待数量先打开汇总，再查看单任务或跳转任务列表。任务按计划时间错峰，同任务串行；迟到周期合并，不突发补跑。成功Visit后按原次数换参，等待Google准入时保留本轮参数，其他任务可继续访问；结果不确定先核实。告警配置的“访问持续延迟监测”沿用原飞书、冷却与权限，不自动暂停或修改周期。

Google Ads → 请求治理分开展示官方额度、系统保护预算、共享成员、本实例估算与全天需求上限。Basic为15,000操作/滚动24小时，不是所有接口统一1QPS；Explorer为2,880，Standard无官方日操作上限但仍受频控。关键词规划特定接口另受每广告账户1QPS约束，批量修改按操作数而不是HTTP请求数记账。同一项目/开发者凭据不能按服务账号数量乘额度，其他VPS或外部工具消耗不在本实例估算内。500任务120秒访问、每2次换参、全天生效且每次1操作约需180,000操作/天，查询和重试另计；硬件模拟压测不能证明单份Basic能全天支撑。

Agent工具：get_task_execution_cadence读取有权限任务节奏；list_execution_cadence_todos先取汇总和snapshotId，再分页取同一分类，过期409重取。管理员用get_google_ads_governance_usage核对共享用量与需求估算。不能绕过频控、擅自增加并发或猜测无数据代表健康。

4. Agent / MCP 接入

操作路径：“系统设置 → Agent / MCP 接入”。页面展示当前实例的 MCP 地址、Hermes 配置示例、连接状态、令牌与可用工具。只有具备相应权限且订阅有效的用户才能调用对应业务能力；Agent 不会获得高于网页端的权限，也不会直接得到 Google Ads API 凭据。

  1. 在页面复制实例的 /mcp 地址。支持 OAuth 的 HTTPS 客户端可按页面指引授权；HTTP 使用用户令牌。HTTPS 也可使用用户令牌。
  2. 将页面提供的配置加入 Hermes 或其他支持 Streamable HTTP 的客户端。HTTP 令牌有效期 30 天，到期需在页面确认续期并更新 Agent 中的令牌；HTTPS 用户令牌无固定到期日，但可随时撤销。
  3. 在 Agent 客户端测试连接；让 Agent 首先调用 get_agent_guide，读取结构化 JSON 的能力、参数与边界。权限或指南版本变化后应重新读取。
  4. 创建单个任务时，按指南依次获取建任务账号选项、生成品牌关键词、生成广告素材、调用 preview_create_task，再提交 create_task。新建广告必须有合格品牌词、标题与描述；生成失败或空结果时不要猜测 payload。
  5. 对要求确认的高风险动作，在 Agent 客户端逐次确认。预检不等于执行成功；结果仍须在任务列表和审计记录中核对。

公网 HTTP 会明文传输令牌和业务数据，应限制令牌接触范围并优先迁移 HTTPS。所有涉及 Google Ads 的 MCP 工具仍走系统统一请求治理；脚本模式不允许 Agent 绕道直连 Google API。

5. 常见问题与排查

5.1 页面或任务异常

先刷新页面并确认订阅状态；再查看对应任务运行记录、系统日志和审计日志。升级后仍看到旧页面时，可清除页面缓存再试。不要在不清楚范围时删除数据库或重置任务。

5.2 广告账户余额显示异常

网页所称“余额”通常是账户预算剩余的估算，不是现金余额。脚本模式无法获取余额；未知值不能按 0 处理。结合余额类型、说明和 Google Ads 后台核对。

5.3 品牌词或素材生成失败

核对服务账号、MCC、客户账号、执行模式及“AI 与关键词”配置。Google 品牌词 Provider 在脚本模式不可用；可按业务配置选择可用的第三方来源。生成失败或没有品牌词时不要自行补造关键词。

5.4 Agent 无法连接或工具不可见

核对页面显示的 MCP 地址和 HTTP／HTTPS 方式、令牌期限、当前用户权限及订阅；重新读取 get_agent_guide 和工具列表。HTTP 令牌续期后旧令牌立即失效。不要把令牌、授权链接或敏感任务数据发到公开频道。

5.5 需要帮助

先记录时间、页面、任务编码与脱敏后的错误信息。可在官网联系作者；不要发送服务账号私钥、令牌或数据库口令。

6. MCC 三脚本自动协作与本轮补跑

入口：系统设置 → Google Ads → Google Ads 脚本。页面只提供三个 v6 通用脚本，无需登记 MCC、创建实例或启用协作。

  • 换参脚本：执行原 Visit 产生的有效换参操作。
  • 广告管理脚本：执行新建广告、预算/出价调整、启停及相关核对。
  • 数据同步脚本：同步账户、已有广告清单、完整日报和已请求的历史数据；API 模式也可使用。

6.1 部署和升级

  1. 复制需要的脚本，原样粘贴到 Google MCC，授权并手动运行一次，再在 Google 设置定时运行。
  2. 同一类代码可以用于多个 MCC，也可以在同一 MCC 新建多份。后台自动发现、分配剩余工作，不需要修改实例编号或划分账户。
  3. 脚本模式升级时，停用同一广告原来的自动控制脚本，再运行新的三个脚本；不需要暂停广告，已有任务保留。在途结果和待核对操作不会被盲目重做。
  4. API 模式广告写操作仍走 API；可只部署数据同步脚本，最初仅上报广告数据的 hourly 旧脚本继续兼容。
  5. Preview 只进行接入检查，不领取正式工作或发布报表；无需另复制一份只读代码。复制、预览不代表已正式运行。

6.2 本轮没有完成时怎么做

点击首页提醒或 MCC 的“查看详情”，先看剩余工作弹窗，再从单条记录跳转任务。

  • 可以等原脚本本次结束后再次手动运行，也可以新增同类脚本并运行；必要时连续补跑，不必等下一小时。
  • 只领取仍有效、未成功、未占用的工作；已确认广告修改和已完成的同轮日报不会重复。原换参间隔不因补跑而缩短。
  • “结果待核对”先核对，不要直接重发。权限、Google 配额或同账户串行瓶颈不是增加脚本就能解决。
  • 数量建议来自实际满负荷成功样本，并预留20%余量；样本不足时不猜数量，不保证任意500户单次完成。
  • 页面中的实际运行次数不是 Google 已安装脚本份数；系统无法替你设置或直接读取 Google 的定时计划。
  • 本轮工作未完成时通过原飞书告警配置推送补跑提醒；其他同类执行仍在处理时不会重复催促。

管理员 Agent 可通过 get_google_ads_script_status 和 list_google_ads_script_remaining 读取同一套运行状态与剩余列表，不返回凭据，也不能代用户点击运行 Google 脚本。

6.3 已有广告系列、广告组与广告接管

先运行数据同步脚本，再创建任务并关闭“同时创建广告”。选择 MCC、广告账户及已有系列；广告组／广告级换参再按父级选择原资源。首次按需读取下级目录时，请运行同步脚本后再读取，不用新建广告绕过。不同父级的 ID 不能混用；同一广告换参目标不能被多个运行中任务重复接管。

账户已发现、系列完整同步、日报同步是三种进度。Google Ads 脚本页的 MCC 详情可以分别查看。系列目录保留最近一次完整结果，超过三小时只标记“数据待更新”，不会自动消失；“读取系列”读本地结果，“请求脚本更新”安排采集，仍需在 Google MCC 实际运行同步脚本。新批次失败或未完成时保留原完整目录；首次未同步不等于没有广告。

普通编辑只改任务配置，不修改 Google 的预算/CPC；资金调整请用独立的预算／出价入口。仅填写要改的字段；未填写出价表示不改，明确清除才清除上限。原已生效值保留到成功回执，预算待执行不阻止 Visit；同轮换参尚未交接或写入结果待核对时不会重复生成后缀。

本次脚本修订为 safe-20261014，请重新复制需要的三个 v6 脚本到 Google MCC；用户端升级不会替换 Google 后台代码。旧写脚本缺少执行前校验时会停止新领取，并提示升级；已提交结果仍保留审计。改绑、改推广来源或暂停遇到“广告修改已提交／结果待核对”时，先完成回执或只读核对；不要重发广告创建。名称、备注等不冲突修改不受影响。API 模式原 hourly 上报不要求替换。

6.4 RW 查找与状态核实

自动化全局配置中的每页抓取上限用于联盟单次请求，按供应商上限执行；列表页码只用于展示。RW 等已支持编号筛选的来源优先定向查询。缺少相应搜索能力时，初段按有限页数与时间查找，保留结果并等待你继续；停止后不自动恢复。查询未完成、遇到限流或达到上限，不能据此判断 Offer 不存在或下架。导出本次结果只导出已取得的数据，不额外扫描联盟。

推荐页只展示已有分析依据的结果与真实历史流量资料；后台发现来源不会立即增加列表条数。补全旧结果更新原行，只有新结果才新增行；没有可用结果的失败项可在今日进度查看。推荐后台读取所选账号实际开放的全部合作状态。Offer 状态核实保留原判定规则，复用已确认的编号筛选。主渠道使用主 Token；明确附加渠道失效时不替换 Token。来源不明确时由用户选择，不按名字自动关联。直接新建内部 Offer 无需先从外部池入库。Amazon 按 ASIN、国家和已有链接只读核实，每次商品读取最多 50 条；商品 ID 优先解析为对应 ASIN，不生成链接代查，未返回商品不直接判下架。

Agent 与网页使用同一查询。searching=true 时按 retryAfterMs 用相同条件继续，complete=false 不等于 Offer 下架。已有广告通过 list_google_ads_campaigns、list_google_ads_ad_groups、list_google_ads_ads 查询；高风险操作仍逐次在 Agent 侧确认。

2026-11-04 更新：推荐每天先按账号均分分析名额，小页轮流读取，只保存取得名额的来源记录；未到期的已完成资料不重复分析。到期更新和未完成资料占用同一每日上限。来源明确失效时保留历史依据并停止自动更新，查询暂未取得不能当作下架。系统重启后先恢复运行任务调度；广告创建确认后，首次访问与换参留有持久待办，MCC 换参仍由脚本执行。升级器可识别两种已知升级阻塞，其他异常保留真实失败原因。