Repository navigation
Releases
2.1.4 补齐 Windows 模板与路径回归测试版本记录
补齐 302291f 的测试改动记录。Windows 任务模板自测同时检查 PowerShell 退出码与完成标记,避免仅返回 0 的占位程序被误判为执行成功;失败时显示捕获的错误输出。补充默认同盘 runs 与 data/outbox 路径引用保持原格式的回归断言,并仅在该路径回归用例内忽略旧脚本的 ResourceWarning。该测试提交已通过 Linux、Windows 的 Python 3.9 与 3.12 CI;没有新增真实账号实测。
2.1.3 开放插件贡献与跨平台检查
贡献文件列出各插件的契约、schema、自测和证据要求。新增 PR、问题模板与关键文件所有者。CI 配置覆盖 Linux、Windows 和两个 Python 版本,运行完整测试、接口及 schema 校验、密钥形态扫描。扫描覆盖 Git 已跟踪文件及 UTF-16 文本,命中时仅报告数量;跨磁盘的 Windows 运行目录使用可定位的相对引用。本地证据为自测。v2.1/interfaces 的每次推送会触发托管作业,逐项结果见该提交的 GitHub Actions 检查及本批 REPORT。
2.1.2 DSH 宿主接入
DSH 技能、MCP 配置和三份入口说明如何把 AdsPilot 放在记忆仓库旁。handoff 工具只向 CURRENT.md 写一行运行摘要,同一轮可重复执行。证据为本地样例。 K3 使用方法列出十个 DSH stdio 配置字段和创造模式的一句话。已在离线的官方 DSH 客户端列出 36 个工具并调用本地判断。
2.1.1 IP 情报与循环验收工具
ipintel 首发 ipapi.is,提供过滤用的 country、数据中心与代理标志。日循环支持按样例模拟连续七天,验收器检查运行记录,校准工具从报告和账本输出阈值提议。另附 Windows 每日任务与小时哨兵模板。注册表纳入模拟、验收、校准与 IP 查询四项能力,CLI 与 MCP 均可调用。CJ 与 Impact 的 offers 筛选参数按提供者区分。证据为样例和自测,真实七天须在学员环境完成。
2.1.0 统一 JSON 接口与 MCP
schemas/interfaces.json 登记 9 项主干和 23 项插件动作;docs/接口盘点.md 对照原脚本参数及证据。CLI 和本地 MCP 共用同一份请求、响应和自测样例。对外执行要求调用者显式开启 apply,且本机配置同意。三份入口补充使用方法,严格检查使用钉版的 iLang 校验器。证据为离线自测。
2.0.21 首发 Impact 联盟插件
PR #12。
第二家联盟。plugins/affiliate/impact/:照 plugins/affiliate/契约.md 的四个动作,把 impact.com 伙伴 API(v16)翻译成主干认的形状;只用标准库,凭据 IMPACT_ACCOUNT_SID、IMPACT_AUTH_TOKEN 只住环境变量,HTTP Basic。
offers:GET /Campaigns?InsertionOrderStatus=Active 只列已加入项目,只留 Type=Performance 且合同 Active 的;GET /Contracts 取佣金率(DefaultPayoutRate 或 DefaultPayout)、锁定期(Locking.Period)、cookie 窗口(ValidReferrals 里 CLICKS 的 Window 折成天)、币种、特别条款原文(--with-terms);token 没勾 Contracts 作用域时回 403,合同字段填 null 并在 stderr 说明,不算失败。HasStandDownPolicy 为 true ⇒ brand_bidding_allowed false,政策文件说 true 也不放行;其余政策字段从 data/inbox/impact-offer-policy.json(按 CampaignId 键)读。epc 一律 null:Impact 伙伴 API 不给任何项目层面的 EPC 或转化率,不编数;选品第一条算不出来,开局第一轮只能用户 --pick,跑起来以后用 partner_performance_by_program 报表与自己的点击算。offer_ref 形如 impact:<AdvertiserId>:<CampaignId>,click_url 是项目的 TrackingLink。
link:追踪链接后追加 subId1=<token>(官方写法,vanity 链接也认),已有 subId1 不分大小写替换,其他参数保留;上限 255 位字母数字,主干 20 位 token 稳稳装下。
commissions:GET /Actions 按最后更新时间开窗(StartDate/EndDate 成对,跨度不超过 45 天,脚本切段并翻 @nextpageuri);按更新时间而不是事件时间开窗,是为了让状态变化也落进窗口。PENDING ⇒ new、APPROVED ⇒ closed,sub_id 装 SubId1,click_time 装 ReferringDate。Impact 没有负数的新记录,撤销是同一笔 Action 的 State 变 REVERSED:只出一行拒付 <Id>:rev(amount 为负,is_chargeback true,original_event_id 指向原 Id),金额优先取同窗口 GET /ActionUpdates?State=REVERSED 的 DeltaPayout,没有就取 Payout 或 IntendedPayout 的相反数;不出正数的 REVERSED 行,否则对账会把它灌成正向调整。offer_ref 要 AdvertiserId,先 GET /Campaigns 建 CampaignId → AdvertiserId 表。日常循环只调 commissions 一个动作,所以拒付行随佣金一起出。csv 退路读后台 Action Listing 导出,表头别名还没对着真实导出核过。
chargebacks:从 commissions 输出筛 is_chargeback 行;Impact 的原事件 id 永远可知,unlinked 只会是缺 ActionId 的坏数据。
公用 impact_common.py:Basic 认证、分页(跟 @nextpageuri,没有就按 @numpages 加 Page)、429 按 Retry-After 退避一次、403 抛 Forbidden 让调用方降级、401 抛 Unauthorized 退出码 4;报错信息里的 AccountSID 抹成 <SID>。
主干两处:core/launch/launch.py 写 offer 表时参数名改为取联盟插件 manifest 的 limits.sub_id_param(原来写死 sid),提示文字里的政策文件按插件名拼;core/lp/lp_check.py 认「直投联盟链接」除了域名表,再按路径形状 /c/数字/数字/数字 认 Impact 的追踪链接(它的追踪域名按品牌各不相同,列不完),自测加一例。其余主干不动,f_v5 冻结区逐字不变。
样例:tests/fixtures/impact.{campaigns,contracts,actions,action-updates}.json(字段名照 v16 文档逐字)与标准形状的 commissions.impact.json;tests/run.sh 加四行;plugins/README.md 首发列与 README 骨架一行加 impact。
自测:四个脚本 --selftest 只读 fixtures 全过(offers 12 项检查、commissions 9 项含 csv 退路、link、chargebacks);lp_check、launch 自测照过;validate.py --all 全过;tests/run.sh ALL OK(33 项)。
真实世界:2026-10-20 用老板的真凭据只读跑了一遍(全部 GET,没有写任何东西):认证通,Campaigns、Actions、ActionUpdates、Reports 回 200,限速头 1000/500/250 与文档一致;账号零个已加入项目,offers 出 0 行并在 stderr 提示去 Marketplace 申请,commissions --days 7 与 chargebacks --days 7 各 0 行,StartDate/EndDate 的写法被接受;link 用样例 TrackingLink 装上 subId1。Contracts、Ads、Deals 回 403,是 token 作用域没勾(token 卡片里补 Contracts 读权限即可),插件按设计降级。输出与代码里 grep 不到 token 与 SID。有项目后的真实 Actions 行、Contracts 字段取值、csv 表头,三样还没核。
CI:selftest 在 py3.9 与 py3.12 下绿(4 项检查)。
2.0.20 Windows 上能跑
PR #11。
第一次在 Windows 11 上跑 tests/run.sh:python3 是微软商店的占位别名,二十九项全 FAIL;换成真 Python(3.13)后还剩七项。四个原因,全在环境与仓库的接缝上,投放逻辑一行没动,f_v5 冻结区逐字不变。
一,解释器。tests/run.sh 先试 $PYTHON(没设就是 python3),不能用就依次退到 python、py,开头打印用的是哪一个;每行 run python3 改成 run "$PY"。
二,CRLF。系统级 core.autocrlf=true 加 .gitattributes 的 text=auto,把钉版本的 reference/ilang/ilang-latest.md 检出成 CRLF,整文件 sha256 与 .sha256 对不上(提交的 blob 哈希是对的,CI 在 Linux 上一直绿);ilang_runtime.py verify 与自检 ilang_runtime 失败,daily.py --selftest 因自检失败停在第一步。现在 .gitattributes 把 ilang-latest.md、.sha256 与所有 *.sh 钉成 text eol=lf;verify 与自检遇 sha 不符而文件里有 CRLF 时,按 LF 再核一次,核过算过,并提示重新检出可消除。
三,编码。GBK 控制台编不出「⇒」,judge.py --selftest 与 spec.py --selftest 打印用例名时 UnicodeEncodeError(其他文件里的「⇒」都在注释与文档字符串里,不打印)。judge.py 加 console_safe():输出流不是 UTF-8 时改成 errors=replace,编不出的字符打成 ?,不崩;judge、spec、daily、launch 的 main 开头各调一次。另一头加 child_env():daily.run_script、launch.run、judge.call_provider 拉起子脚本时带 PYTHONUTF8=1 并按 UTF-8 读回(原来按系统编码),平台报表与联盟数据里出现 GBK 之外的字符(商标符、表情)时子脚本不再崩在打印上。tests/run.sh 也开 PYTHONUTF8=1。
四,时区。Windows 的 zoneinfo 没有系统时区库,ZoneInfo("Asia/Tokyo") 抛 ZoneInfoNotFoundError,convert_export.tz_of 原来静默退回 UTC;两个转化脚本的自测要 +09:00,失败。现在 tz_of 退回 UTC 时在 stderr 说一句(时间列仍带偏移,时刻不变,只是不按配置的时区显示;装 tzdata 即可);自检加 timezone(快速模式第十二项,全部十四项),查不到 config.timezone 给 WARN 不给 FAIL,没有 config 查 example 里的;两个自测改用 selftest_tz():有 zoneinfo 用 Asia/Tokyo,没有就用固定 +09:00 核同一条格式化路径,输出里写明。
另修一处陈旧:Google Ads 插件 manifest.json 的 limits 还写着 max_cpc_default: 0.25 与 first_day_budget_default: 5,这两个常数 2.0.15、2.0.16 已从 SOUL 拔掉,代码里没有地方读它们,删掉。
使用方法:core/agent/使用方法.md 自检一节加 Windows 一段;core/loop/使用方法.md 任务计划一句加 python 与 PYTHONUTF8=1。README 状态表的自检数改为十四项(快速模式十二项)。
自测:Windows 11、Python 3.13.15、GBK 管道、未装 tzdata、CRLF 检出的工作区上,先按 2.0.19 跑出七项失败,修后 tests/run.sh ALL OK(自检 timezone WARN,ilang_runtime 走 CRLF 退路);重新检出为 LF 后 verify 不再走退路;同一机器装了 tzdata 的 venv 下 PYTHON=<venv>/python tests/run.sh ALL OK。既有用例一个没改。
真实世界:没有碰真实账号。
CI:selftest 在 py3.9 与 py3.12 下绿(4 项检查)。
2.0.19 补 2.0.18 的上限实测记录
PR #10。
只改文档,不动代码。2.0.18 那条写着「没核:改已有系列的每次点击上限要一条真系列才核得了」,09-26 当天老板点头后已经补核,这版把它写进仓库。
真实世界:2026-09-26 在真实账号上建一条日预算 1 港币、建好即暂停的尽可能多点击系列(只建预算与系列,不建广告组与广告),走日常循环同一条降价路(deploy_api.py --actions,系列动作带 bid_cap):每次点击上限 4.56 港币改 4.00,读回 4.00;再跑一次同样的动作,nothing to change,幂等成立。测完系列连预算删净,账号里没有测试系列;账号原有的 banking 系列没碰。到此 2.0.18 的降价路在真实账号上全核过,还没核的只剩 budget_api.py --campaigns(仍是 0 行,要一条跑起来的系列)。记录写进 plugins/traffic/google-ads/使用方法.md 的「实测记录」与 STEP 2a。
自测:没有代码改动,tests/run.sh ALL OK,selfcheck.py --quick PASS,既有用例不变。
自测:tests/run.sh ALL OK,selfcheck --quick PASS;CI selftest 在 py3.9 与 py3.12 下绿。
2.0.18 出价方式默认尽可能多点击
PR #9。
老板 2026-09-26 定的。第二轮真实账号核验查明:谷歌对手动 CPC 不给推荐预算,换成尽可能多点击(TARGET_SPEND)就给。预算照谷歌推荐,所以默认出价方式改成尽可能多点击,系列的每次点击上限就是出价上限(min(offer 的 bid_cap, caps.max_cpc),都没有用谷歌推荐出价),选品第一条的账不变。用户明确要手动出价就在 brief 写 bidding: manual_cpc,照旧,这时谷歌不给推荐预算,预算由用户定。
改动:traffic-spec schema 的 bidding.strategy 允许 maximize_clicks(默认)与 manual_cpc,样例 spec 改成默认。spec.build 读 brief.bidding:尽可能多点击时 max_cpc 是每次点击上限(用户写的,没写就是出价上限),广告组不写出价;不认的出价方式报问题。deploy_api 建系列时尽可能多点击发 targetSpend.cpcBidCeilingMicros,广告组与词不发出价。日常降价先查系列真实的出价方式:尽可能多点击把每次点击上限设成动作带的出价上限,已不高于它就不动(报表窗口是 7 天,改完几天里均价还会高于上限,设成同一个数不会一天天往下砍);手动 CPC 照旧降广告组出价;别的出价方式跳过。尽可能多点击的系列上词的降价跳过并写明原因。budget_api --new 的出价方式跟要建的系列一致(默认 TARGET_SPEND);谷歌会把请求里的当前预算也当一档返回,现在剔掉。判断:keyword.action 在系列是尽可能多点击时不看「高于出价上限 ⇒ 降价」这条(词级出价不生效,由系列的每次点击上限管);默认 SOUL 2.4.0 加「出价方式」一节,改 campaign.adjust 与 keyword.action 各一条规则,顺序守卫照过,f_v5 冻结区逐字不变。开局:尽可能多点击时不再拿第一个过线词的出价当上限(这段拆成 bid_defaults),data/inbox/campaigns.json 记 bidding。日常循环:词与系列的状态带 bidding(老系列没写就是手动),系列降价的动作带 bid_cap。契约与使用方法同步:manual 路在后台出价选「点击次数」并设每次点击费用上限。
另修一处:deploy_api --spec --validate-only 原来逐步校验,给系列填的占位预算 campaignBudgets/1 不存在,谷歌在引用上就退回 RESOURCE_NOT_FOUND,出价等字段根本没校验到。现在整条系列(预算、系列、地理语言与否定词、广告组、关键词、广告)放进一个 googleAds:mutate,用临时 ID 互相引用,一批校验。
自测:T7-a 到 T7-i 先在 2.0.17 上跑出失败再修(默认仍是手动、预算请求仍是 MANUAL_CPC、当前预算混在几档里、尽可能多点击的系列仍按词降价、validate 模式在预算引用上退回;手动出价的对照组在 2.0.17 上本来就过),修后全过。T7-i 有一处断言写宽了,把跟踪模板里 ValueTrack 的花括号也当成没填的占位符,改成只查步骤占位符。既有判断用例、用户用例与日常循环样例的判断逐行不变。
真实世界:2026-09-26 在真实账号上只读加 validate-only 核过,没建也没改任何东西。默认请求下谷歌给新系列推荐预算 84.76 港币(几档 67.81、84.76、101.71,当前预算已剔掉),带不带 isNewCustomer 一样,写 manual_cpc 时照旧不给;spec 出 {maximize_clicks,每次点击上限 4.56 港币};整条尽可能多点击的系列 validate-only 一批通过;降价要用的系列查询与词查询(带出价方式与每次点击上限字段)谷歌收下。没核的:改已有系列的每次点击上限要一条真系列才核得了;--campaigns 仍是 0 行,parse_existing 的取值还等有推荐时再核。
自测:tests/run.sh 在 py3.9 与 py3.12 下 ALL OK,CI selftest 绿。
2.0.17 谷歌推荐预算按真实账号核出的三处改
PR #8。
CC 在真实账号上只读核了 2.0.15 与 2.0.16 没核过的接口,核出三处,照改:budget_api.py --new 只给国家代码会被拒(CAMPAIGN_BUDGET_RECOMMENDATION_TYPE_REQUIRES_EITHER_POSITIVE_OR_NEGATIVE_LOCATION_IDS_FOR_SEARCH_CHANNEL),现在按国家查地区常量填 positiveLocationsIds;--campaigns 的查询单选了 campaign_budget_recommendation 的子字段,v25 报 UNRECOGNIZED_FIELD,现在整个选,从对象里取推荐值(只有一档没标推荐时取那一档);两个输出的 currency 原来取自 brief,现在查账户币种(谷歌返回的金额是账户币种)。开局与日常循环发现推荐预算的币种与 config.currency 不一致就不用,提示改配置。主流程拆成 run_new、run_campaigns,离线可测。
自测:T6-a 到 T6-d 先在 2.0.16 上跑出失败再修,修后全过;其余不变。
真实世界:CC 2026-09-26 核的结果:加上地区 ID 后建系列前的推荐能调通,那次谷歌没给推荐;已有系列的查询改成整个选后能过,0 行;报表的首页出价估计字段谷歌收下了,没退回,但账号近 7 天没有关键词数据,值没法核。本版改动后还要再核一轮。
自测:tests/run.sh 在 py3.9 与 py3.12 下 ALL OK,CI selftest 两个 job 通过。