前言¶
用 Agent 接 B 站三连投放 MAPI 时，常见做法是让模型直接拼 curl 或手写 HTTP：并行打多个账户、把 access_token 写进命令行、在没查清账户范围前就改广告。三连侧对 client_id 有共享配额，旧版三层（计划/单元/创意）与素材化 2.0（项目/素材）接口也不互通。下面介绍 SkillHub 上的 B站三连广告-授权与主流程（内部名 bilibili-sanlian-ads）：官方把它定位为任意三连广告任务的 Start-here 入口，先做意图澄清与授权，再按任务路由到投放、素材、报表等子 Skill。
这是什么¶
一句话：Bilibili Sanlian Ads MAPI 的全局授权、调用纪律与任务路由指南。
- 展示名称：B站三连广告-授权与主流程
- 包标识：
slug: sanlian-ads，name: bilibili-sanlian-ads - 维护者：SKILL 元数据标注作者为 Benjamin，MIT 许可证；当前包版本 3.0.4
- 分发：SkillHub 分类 business-ops（页面统计：评分 98707，下载 687 次）
- 官方页：https://api.skillhub.cn/user_b0010d5c/sanlian-ads
它不负责具体创编字段全集（那些在各子 Skill 的 references/ 里，源自哔哩开放平台 MAPI 文档），而是解决「有没有 token、管哪个 account_id、该走 v3 还是 v4、下一步打开哪个 Skill」。
核心功能¶
以下能力均来自该 Skill 的 SKILL.md 说明。
面向运营的非技术交互¶
- 用通俗中文澄清意图；不把 JSON、
curl、本地凭据路径甩给用户。 - 对可能产生线上影响的操作，先整理 operation brief（账户、
account_id、读/写、对象层级、时间范围等），写入前走分阶段确认（意图确认 → 执行确认 → 多对象时的金丝雀与批次检查点）。 - 细节见包内
references/operator-interaction-and-confirmation.md。
OAuth 2.0 与令牌生命周期¶
- 通过捆绑客户端完成授权 URL、
state校验、授权码交换、刷新；access_token有效期 24 小时，refresh_token30 天（刷新成功会重置 30 天窗口）。 - 本地凭据文件由
scripts/mapi_client.py管理：按操作系统固定路径、0700/0600权限、原子写入、跨进程锁；可用环境变量BILIBILI_MAPI_CREDENTIALS覆盖默认路径。 - 支持查询授权 User、主体、投放账户及账户详情；多授权记录按账户范围合并或分存。
- OAuth 与业务接口参考索引见
references/1846_开发者完整接入指南.md等。
保守的 MAPI 调用纪律（共享配额）¶
- 禁止并发：全局同时最多一个 MAPI 请求在飞；相邻请求启动间隔至少约 1 秒（客户端强制下限，不代表平台配额上限）。
- 频控类错误立即停；只读临时故障最多一次退避重试；写入结果未知时禁止盲重试，只能走文档化的查询回读。
- 每次请求需带
X-Call-Source: sanlian-skills与X-Sanlian-Skills-Version: 3.0.4；业务根域为https://cm.bilibili.com/takumi/api，并需Authorization: Bearer {access_token}与account_id。 - HTTP 200 仍可能包业务失败，须对照对应
references/判断成功形态（code: 0、code: 200或status: "success"等）。
旧版与 2.0 分流¶
| 结构 | API | 子 Skill |
|---|---|---|
| 计划 → 单元 → 创意（v3） | /open_api/cpc/v3/* |
bilibili-sanlian-ads-ad-management |
| 项目 → 素材（v4，邀请制白名单） | /open_api/cpc/v4/* |
bilibili-sanlian-ads-delivery |
两套数据模型与 ID 空间隔离，不能互读互写；白名单账户新建只能走 2.0，既有旧广告仍用 v3 管理。不确定是否白名单时，应在已有 token 与 account_id 后探测 GET /open_api/cpc/v4/promotion/list，并区分 401 与业务级拒绝。
任务路由¶
| 用户目标 | 子 Skill |
|---|---|
| 授权、令牌、账户范围（本 Skill） | bilibili-sanlian-ads |
| 2.0 项目/素材创编 | bilibili-sanlian-ads-delivery |
| 旧版计划/单元/创意 | bilibili-sanlian-ads-ad-management |
| 保存前可选枚举、定向、资源查询 | bilibili-sanlian-ads-metadata |
| 图片/视频素材 | bilibili-sanlian-ads-materials |
| 组织级资产、转化组件等 | bilibili-sanlian-ads-assets |
| 投放报表 | bilibili-sanlian-ads-reporting |
| 账户预算、钱包、流水 | bilibili-sanlian-ads-account-finance |
| RTA 策略 | bilibili-sanlian-ads-rta |
出错时按 references/error-triage-and-handoff.md 做冷复查与支持信息整理。
中文触发词（便于在 Agent 里唤起）：B站广告、哔哩哔哩广告、bilibili 广告、三连、三连投放、MAPI、开放平台、广告 API、授权、开发者、client_id、access_token、令牌、接入。
安装与启用¶
从 SkillHub 获取¶
在浏览器打开官方页并安装/导入到当前 Agent 环境（具体按钮以 SkillHub 页面为准）：
https://api.skillhub.cn/user_b0010d5c/sanlian-ads
三连广告是一组协作 Skill：WorkBuddy 场景下文档要求导入 完整的 Sanlian OAuth 技能包（含入口 Skill 与相关领域 Skill），缺包时不要对线上账户发起请求。WorkBuddy 操作路径见包内 references/workbuddy-getting-started.md（「专家·技能·连接器」→ 上传技能）；腾讯云 WorkBuddy 技能说明：https://cloud.tencent.com/document/product/1831/134432 。
Cursor、Codex CLI、Claude Code 的安装命令因产品集成方式不同，本稿未在官方页抓取到统一 CLI 语句，此处不臆造；以 SkillHub 页与各自产品的 Skill 导入能力为准。
运行依赖¶
- Python 3.8+，标准库即可（无第三方依赖）。
- macOS / Linux 使用
scripts/mapi.sh；Windows 使用py -3 scripts/mapi_client.py同等子命令。若可执行位丢失，可sh scripts/mapi.sh ...。 - 可选环境变量：
SANLIAN_PYTHON（指定解释器）、BILIBILI_MAPI_CLIENT_SECRET（交换令牌时从 stdin 以外提供 secret）、BILIBILI_MAPI_CREDENTIALS（凭据文件路径）。
默认凭据路径（节选）：
macOS: ~/Library/Application Support/bilibili-sanlian-ads/credentials.json
Windows: %LOCALAPPDATA%\bilibili-sanlian-ads\credentials.json
Linux: ${XDG_CONFIG_HOME:-~/.config}/bilibili-sanlian-ads/credentials.json
开发者 client_id / client_secret 需在 https://ad.bilibili.com/developer/onboard 完成资质与应用创建（Skill 内写明需销售/运营协助推进 MAPI 审核，周期约三个工作日量级）。
典型用法¶
建议的首轮流程（Agent 侧）¶
- 先
scripts/mapi.sh token-status，不要一上来就向用户要密钥。 - 无可用令牌（退出码 60）时收集
client_id、client_secret，走 OAuth。 - 查询主体与投放账户，写入操作前确认
account_id。 - 判断 legacy 或 2.0，再打开对应子 Skill 与其
references/。
OAuth 与探测命令¶
在 Skill 包根目录执行（Windows 将前缀换成 py -3 scripts/mapi_client.py）：
scripts/mapi.sh doctor
scripts/mapi.sh auth-url <client_id>
scripts/mapi.sh auth-exchange "<完整回调 URL>"
scripts/mapi.sh token-status
scripts/mapi.sh token-refresh
scripts/mapi.sh call GET <path> [--query-file q.json]
scripts/mapi.sh call POST <path> --body-file body.json
授权页形态（由 auth-url 生成）：
https://ad.bilibili.com/developer/developer-authorization?client_id={client_id}&state={state}
用户从浏览器地址栏复制完整回调 URL（例如 https://sanlian.com?code=...&state=...）交给 auth-exchange；client_secret 走 stdin 或 BILIBILI_MAPI_CLIENT_SECRET，不要放在命令行参数里。
call 仅接受 /open_api/ 前缀路径；非 MAPI 请求（如公开稿件查询、预签名上传）不得走该客户端。
端到端示例（文档中的工作流摘要）¶
查消耗（只读）
- 本 Skill：令牌与账户范围。
bilibili-sanlian-ads-reporting：自定义报表。- 仅当用户问余额、预算、流水时再用
bilibili-sanlian-ads-account-finance。
创建广告（旧版）
- 本 Skill：operation brief、账户确认。
bilibili-sanlian-ads-metadata：按creation-field-source-map.md拉可选值。bilibili-sanlian-ads-materials：备素材。bilibili-sanlian-ads-ad-management：计划 → 单元 → 创意，每步写入后查询核验。
创建广告（2.0 白名单账户）
- 本 Skill：确认白名单与意图。
- metadata →
bilibili-sanlian-ads-delivery（项目、素材、绑定），各写操作边界单独确认。
运营侧口语示例（来自 WorkBuddy 入门指引）：「查询账户 123456 昨天的消耗、曝光、点击和转化」「列出账户 123456 当前在投项目，只查询不修改」。
适用场景与注意¶
适合谁
- 需要在 Agent 里稳定接入三连 MAPI 的开发者或投放运营（尤其不希望模型手写 HTTP 的场景）。
- 任务会跨授权、创编、素材、报表、财务、RTA 等多模块，需要一个固定路由表的场景。
限制与坑
- 勿只装入口 Skill 就操作线上账户；缺子 Skill 或
references/时应停止并补全包。 - 勿把凭据写在 Skill 目录、项目仓库或云同步文件夹；勿在对话中回显 token 或完整回调 URL。
- 商品管理、代理商管理、账户资质、激励券、转化回传协议等不在本技能集覆盖范围内，应指向官方文档或商务对接。
- 修改
scripts/mapi_client.py后应跑scripts/mapi-test.sh做本地回归（不触网、不用真实凭据）。
结尾¶
B站三连广告-授权与主流程把 OAuth、账户范围、调用顺序和子 Skill 路由收在一个入口里，让后续创编与报表都在同一套安全约束下执行。任意三连广告相关任务建议先加载本 Skill，再按路由进入领域包。
官方地址：https://api.skillhub.cn/user_b0010d5c/sanlian-ads
