OAuth v2 工作流程

安裝

npm install --global @anakonn/ankk@0.5.1
ankk --version

登入並選擇品牌

ANKK v2 透過瀏覽器 OAuth 使用您的使用者帳號。現有權限適用於每項請求。連接應用程式不會授予額外品牌權限。工作時再選擇品牌；OAuth 授權不會選定品牌。

使用 Node.js 24 以上版本及 CLI 0.5.1。以下公開用戶端 ID 用來識別 ANKK CLI，並非機密。

export ANKK_OAUTH_CLIENT_ID=ankk-cli-production

ankk --json auth login --environment production
ankk auth status --environment production --connection OAUTH_CONNECTION_ID
ankk --json brands list --environment production --connection OAUTH_CONNECTION_ID --all
ankk --json connections list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

以您自己的請求所傳回的 ID 取代大寫識別碼。OAuth 連線 ID 用來選擇登入連線。SNS 帳號 ID 識別發佈目標，與 OAuth 連線及供應商的帳號 ID 都不同。整個流程請使用相同環境與品牌。即使您已設定本機預設品牌，這些範例仍明確指定兩者。

若終端機沒有自動開啟瀏覽器，請使用 ankk auth login --environment production --device --no-open，並依照畫面上的驗證指示操作。權杖儲存在作業系統的憑證儲存區。若該儲存區無法使用，請先修復再登入；切勿將權杖貼進對話或存入發佈用的 JSON 檔案。

讀取成效與已儲存的貼文

ankk --json analytics get --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --from 2026-10-01T00:00:00Z --to 2026-10-02T00:00:00Z
ankk --json posts list --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --all

選擇實際報表期間。期間包含起始時間、不包含結束時間；時間戳記使用 UTC。查詢前，請將使用者的當地日期轉換為 UTC。加入 --sns-account SNS_ACCOUNT_ID 可將結果限制為單一帳號。

結果描述的是已儲存的觀測資料。比較期間前，請檢查涵蓋範圍與觀測時間。缺漏資料不等於零。最新帳號快照有自己的測量時間，不一定是期間總計。Instagram 精確期間洞察與累積觀測資料分開處理。讀取不會啟動供應商資料收集。posts refresh 是針對貼文／留言資料的獨立動作，不是重新整理分析的請求。

清單使用游標。--all 會逐頁讀取；分頁期間資料可能改變，因此結果不是同一時間點的快照。若游標過期，請回報結果不完整，並明確重新開始列出清單，不要悄悄與舊頁面合併。

發佈前準備檔案

ankk --json media create-upload --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file ./photo.jpg --idempotency-key UPLOAD_KEY
ankk --json media complete-upload MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --idempotency-key INSPECTION_KEY --wait --wait-timeout 180
ankk --json media get MEDIA_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID

第一個指令會登記並傳輸檔案。即使傳輸失敗或回應不明確，也請儲存其媒體 ID。第二個指令要求檢查；只有媒體最終狀態為 ready 時才能使用。這些步驟不會發佈內容。媒體可在所屬品牌內重複使用；其他品牌須另行上傳。

如果只有上傳 URL 過期，請以相同環境、登入連線與品牌使用 media refresh-upload MEDIA_ID。新 URL 不會延長原本的業務期限，也不會替換檔案。位元組內容不同時，須建立新的媒體上傳。請將簽署的傳輸 URL 視為憑證，不要放入共用的對話紀錄。無法傳輸檔案的用戶端可使用傳回的瀏覽器進度 URL，登入並選擇檔案，再以相同媒體 ID 返回檢查準備狀態。

檢視並發佈

發佈 AI 準備的內容前，請確認品牌、帳號、完整文字、串文段落順序、附件、供應商選項與執行時間。已有針對完全相同意圖的核准即可。只要求分析或撰寫草稿，不代表核准發佈。

將以下最小立即發佈輸入儲存為 publish.json。選擇支援預定文字與圖片組合的帳號；伺服器會再次檢查目前能力、媒體準備狀態與權限。

{
  "scheduled_at": null,
  "targets": [
    {
      "sns_account_id": "SNS_ACCOUNT_ID",
      "text": "The exact text you approved",
      "media_ids": ["MEDIA_ID"]
    }
  ]
}

ankk --json contents publish --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --file publish.json --idempotency-key PUBLICATION_KEY

送出前，請為此意圖選定並保留唯一金鑰。若回應不明確，請重用完全相同的金鑰與負載，即使切換 API、CLI 與 MCP 也一樣。不要只因連線逾時就建立另一筆發佈。相同金鑰搭配變更後的輸入會產生衝突。過期金鑰不會建立新工作：請先檢查舊結果，再明確開始新的意圖。

若要預約發佈，請將 scheduled_at: null 換成已核准的未來 UTC 時間，例如 2026-12-01T09:00:00Z。使用前請替換此示意日期，並確認仍在未來。登記完成會傳回獨立的 publish_operation_id；這不代表排程的 SNS 貼文已發佈。

追蹤結果

ankk --json operations get OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --wait --wait-timeout 180

立即發佈時，請追蹤傳回的操作 ID。預約發佈時，請在執行時間追蹤 publish_operation_id。等待是選用的本機行為。CLI 結束碼 10 代表等待上限已到；結束碼 130 代表等待中斷。兩者都不會取消伺服器工作。請繼續讀取相同操作。等待的結束碼 11 表示最終結果為失敗、取消或部分成功；請檢查各帳號結果。一般狀態查詢可能以 0 結束，但回報失敗的操作，因此指令碼也必須檢查回應狀態。

逐一回報各帳號。保留成功貼文及其 URL。有序的 posts 陣列包含串文中已確認的貼文；單一代表 post_url 未必能描述整串貼文。缺少 URL 或狀態尚未確定，不能證明供應商沒有建立任何內容。在既有工作提供證據之前，請保留仍在對帳及未知結果的未決狀態。

修改預約或從失敗復原

更改內容或時間前，請以相同環境、登入連線與品牌讀取 contents get CONTENT_ID。以 --expected-version 傳入目前版本。contents update 編輯符合條件且尚未開始的目標；contents reschedule 更改其 UTC 排程。版本衝突時必須重新讀取與檢視，不可默默覆寫。contents cancel 提出取消要求；請檢查傳回的發佈操作，直到確認取消。執行可能先於取消發生。

僅重試所選且目前標記為 can_retry 的失敗帳號：

ankk --json contents retry ORIGINAL_OPERATION_ID --environment production --connection OAUTH_CONNECTION_ID --brand BRAND_ID --accounts FAILED_SNS_ACCOUNT_ID --idempotency-key RETRY_KEY

這是新的執行意圖，除非已在核准範圍內，否則需要適當的新金鑰與使用者核准。回應不明確後，請保留該重試金鑰。重試使用已儲存的內容，並盡快執行；不會重新發佈成功或結果不明的目標。若要建立新的未來預約，contents duplicate 只會傳回可編輯的輸入。檢視後再提交新核准的發佈。

捨棄符合條件的失敗佇列項目，會將其從工作佇列隱藏；不會刪除貼文、抹除執行紀錄或重試任何工作。批次取消可能同時傳回接受與拒絕的群組；請追蹤每個已接受的發佈操作。批次捨棄同步完成：請檢查回執中已捨棄與拒絕的群組，不必等待新操作。兩種情況都應讀取完整回執，不要把結束碼當成全成或全敗的結果。

處理請求錯誤並中斷連線

讀取結構化錯誤碼、請求 ID、可取得時的操作 ID、next_action 與 retry_at。驗證復原後應返回原操作。權限錯誤需要合法存取權，而非改用另一個介面。必須遵守速率限制與能力限制。可重試的請求不代表獲准建立新發佈或替換金鑰。

ankk auth logout --environment production --connection OAUTH_CONNECTION_ID

登出會分別回報伺服器撤銷與本機憑證移除。如果尚未確認伺服器撤銷，請從 ANKK 設定或另一個有效連線撤銷舊連線。移除 OAuth 連線不會取消已接受的發佈，也不會刪除品牌所屬媒體。

使用 MCP 與 Skills

MCP 在 https://api.ankk.app/mcp/v2 使用使用者 OAuth。主機需要已註冊的用戶端；只輸入 URL 並不會完成連線。目前沒有 ChatGPT 與 Claude 官方目錄上架項目。卡片不可用時，請使用文字與結構化結果，並核對數值和觀測時間，不要只依賴對話摘要。

Skills 提供工作程序，不授予權限或提供憑證。安裝下列固定候選標籤，並確認品牌、授權及作業最終結果。

npx skills add https://github.com/Anakonn/ankk-skills/tree/v0.1.0-rc.1 --skill ankk-analyze --skill ankk-publish