前言¶
用 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
