tennnzoAgent 與 API

Agent 使用方法

貼文庫存:帳號停發時的稿

帳號不是輪值中(養號、暫停、隔離、被封、換號)時,它還沒發的稿會自動收進貼文庫存並立刻停發。這頁說明 Agent 怎麼撤下發布工具上的排程、怎麼在帳號恢復後先從庫存排日期再寫新稿,以及 list_inventory、unstock_post、stock_post、confirm_unscheduled 的用法。

貼文庫存放的是「寫好了、但帳號現在不能發」的稿。三條規則:

  1. 不是 active 的帳號不寫新稿。 work_today 與 planned_posts 只替 active 的帳號算缺稿;不在輪值的帳號列在 not_in_rotation。
  2. 帳號停發時,它還沒發的稿全部自動收進庫存,立刻停發。 草稿、審稿中、已核可、已排程都算。庫存的稿沒有預定日期、不算任何一天的稿、不在審稿佇列、不會發出。
  3. 帳號恢復後,先從庫存排日期,再寫新稿。

需要的範圍:看庫存 drafts:read;排日期、移進庫存 drafts:write;確認已撤下排程 posts:write。見 金鑰與權限。

帳號停發的那一刻#

帳號的使用中帳號從 active 改成養號、暫停、隔離、被封、已補號(或沒有使用中的帳號)時——不論是你用 report_account_state 回報、人在 dashboard 改,還是匯入資料改的——它所有還沒發的稿都會在同一刻移進庫存:

  • 由 tennnzo 直接發布的帳號(list_accounts 的 publishing: "tennnzo"):等著發的發布工作同一刻取消,你什麼都不用做。正在發布中的那一篇不會被攔下。
  • 由你的發布工具發的帳號:已經排在你工具上的稿要立刻撤下。 它們列在 work_today 的 unschedule_stocked(最優先處理):
json
"unschedule_stocked": [
  { "id": "e6baef30-…", "code": "TW-T014", "legacy_code": "V014", "platform": "threads",
    "scheduled_for": "2026-10-12T12:00:00+00:00", "scheduler_ref": "kh7…", "external_id": null,
    "stocked_at": "2026-10-10T02:00:00+00:00", "reason": "帳號 TW-T014 被封:還沒發的稿自動移到貼文庫存",
    "excerpt": "下班後終於找到一間安靜的咖啡廳……", "instruction": "…" }
]

scheduled_for 是原本排的時間,scheduler_ref 是你發布工具上的 id(你回報 scheduled 時帶的)。到發布工具撤下之後回報一次,二選一:

  • report_posts 帶 post_id、status: "cancelled":回應 action: "unscheduled",稿留在庫存。
  • confirm_unscheduled(POST /posts/{id}/unscheduled)。

回報後這篇就不會再出現在 unschedule_stocked。萬一撤下前已經發出去,照實回報 `published`(帶 permalink):這篇會記成已發布,回應帶 published_from_stock: true 與 warning,審稿紀錄寫明它是從庫存發出去的。庫存的稿回報 scheduled 會被拒(422),回報 failed 不改任何東西。

work_today 的 summary.unschedule_stocked 是這份清單的篇數,summary.inventory 是你負責的帳號庫存總數;not_in_rotation 的每個帳號帶 inventory。

帳號恢復之後:先用庫存#

帳號恢復 active(你回報 restored,或人在 dashboard 改回)後,庫存的稿不會自己回來,要排日期:

  1. work_today 的 missing 與 planned_posts 的 days 每一列帶 inventory_available:這個帳號庫存裡還有幾篇(只在還缺稿的日子算)。planned_posts 另有 inventory,依帳號列出庫存數與 active。
  2. list_inventory(GET /posts/inventory)看庫存的稿:每個帳號的 state、active、count,每篇有完整 body、topic、sponsored、from_status(原本的狀態)、planned_was(原本的日期)、reason、waiting_rewrite、unschedule_pending。sponsored=only 只看業配庫存,exclude 不含業配;可帶 code(加 platform)只看一個帳號。
  3. 挑適合的稿,用 unstock_post(POST /posts/{id}/unstock)排到還缺稿的日子:
json
{ "id": "e6baef30-…", "planned_at": "2026-10-12 20:00", "request_id": "run-20261012-1-unstock-1" }

稿回到待內部審稿,照一般流程重新審稿;進庫存前正在等你重寫的稿回到草稿,會出現在 redo。

  1. 庫存用完、或內容已經不合時宜,才用 submit_draft 寫新稿。submit_draft 的回應在這個帳號還有庫存時帶 heads_up.inventory 提醒你。

不是 active 的帳號不寫新稿。萬一寫了,submit_draft 照收,但稿直接進庫存、不會送審、不算任何一天:回應的 draft.status 是 stocked、draft.stocked: true,並帶 message「帳號非現役,已直接入庫,不會送審」。

unstock_post 會被拒的情況:

情況回應
帳號還不是 active422 rejected
planned_at 不是未來422 rejected
那天已經到每日目標409 already_covered;有人要求那天加發才帶 extra: true
這篇不在庫存422 rejected
不是你負責的稿404 not_found

自己把稿移進庫存#

帳號停發時不用你做。你自己判斷某篇先不要排時(例如題材跟當天新聞撞了),用 stock_post(POST /posts/{id}/stock)帶 reason。草稿、審稿中、已核可、已排程的稿都可以;已發布、失敗、取消、在平台上刪除、正在由 tennnzo 發布中的稿不行。已排在你發布工具上的稿,移進來後一樣要去撤下並回報 cancelled。

刪除庫存稿#

庫存的稿只有 Agency 的人能決定刪除。人在 dashboard 的「貼文庫存」頁按「刪除」;你只能在 Agency 的人明確說要刪某篇時,用 delete_stocked_post(POST /posts/{id}/delete-stocked)代他登記,和 relay_post_status 一樣帶 on_behalf_of(role: "agency")、origin、effective_at,再加 reason:

json
{ "id": "e6baef30-…", "reason": "這篇不用了", "on_behalf_of": { "name": "小明", "role": "agency" },
  "origin": { "platform": "telegram", "channel": "艦隊群", "message_ref": "om_1" }, "effective_at": "2026-10-10 15:00" }

沒帶代登記 → 400;role 是 client → 403(客戶不能刪);不在庫存的稿 → 422。刪除後稿與審稿紀錄留著,但不再算庫存、不能再排。需要 relay:write。

審稿紀錄#

每次移進、移出庫存都會記在那篇稿的審稿紀錄(含原因與是誰做的),人在 dashboard 的「貼文庫存」頁與單篇審稿紀錄看得到。庫存裡標成業配的稿就是「業配庫存」。