Agent 集成：作用域密鑰 axn_* 與最小權限實踐
讓 AI Agent 安全管理你的資源：作用域令牌按最小權限發放、憑據只走環境注入、工具調用面對齊錯誤契約、審計留痕。附完整的接入五步與一個「內容助理 Agent」的權限設計實例。
Agent 是新時代的運維實習生：能幹、不知疲倦、但給的權限必須像對實習生一樣摳。本篇講怎麼讓 Agent 安全地管理你的站內資源：作用域密鑰的發放紀律、憑據注入方式、工具面設計與審計閉環——五步接入，每步可驗證。本文屬於開發者中心欄目；接口全貌先讀API 參考總覽。
第一步：作用域令牌——最小權限不是口號
本站管理 API 幫助三類鑰匙（主密鑰/會話/作用域令牌），Agent 只用第三類：axn_* 作用域令牌——按 scope 詞表（articles/markets/courses/settings/tokens/ops/ugc 等）授權，可單獨吊銷、互不牽連。發放紀律三條：
- 一個 Agent 一把鑰匙：多個 Agent 共用令牌 = 審計失效 + 吊銷連坐；
- scope 按任務白名單：內容助理只給 articles，行情機器人只給 markets——「順手給全權限」是事故的首付款；
- 生命周期有人管：令牌寫進臺賬（誰、什麼 scope、何時發、何時輪換），90 天輪換是合理默認。
# 用主密鑰（環境變量注入，勿入命令行歷史）籤發一把文章域令牌：
curl -s -X POST https://axionserve-portal.aeronest-global.workers.dev/api/admin/tokens -H "Authorization: Bearer $AX_MASTER" -H "Content-Type: application/json" -d '{"name":"content-agent","scopes":"articles"}'
# 響應含明文令牌（僅此一次顯示）→ 立即寫入 Agent 運行環境的 secret 存儲
# 驗證作用域邊界（拿文章令牌碰設置 → 應 403）：
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $AXN_CONTENT" https://axionserve-portal.aeronest-global.workers.dev/api/admin/settings # 期望 403第二步：憑據注入——Agent 拿鑰匙的正確姿勢
- 環境變量或平臺 secret 存儲：令牌在運行時注入進程環境，不進代碼倉庫、不進日志、不進提示詞——三條紅線對 Agent 比對人更重要，因爲 Agent 的對話記錄與工具調用日志會被系統性留存；
- 提示詞裏永遠只有引用：系統提示寫「用環境變量 AXN_CONTENT 裏的令牌調用」，不寫令牌值本身——防提示注入攻擊的第一道牆（Agent 被誘導輸出上下文時，值不在上下文裏）；
- 懷疑即輪換：日志裏出現過令牌明文、Agent 行爲異常、第三方工具接觸過環境——三種情況都立即吊銷重發，成本是五分鍾，不做的成本無上限。
第三步：工具面設計——讓 Agent 的每個動作可預期
把 API 包裝成 Agent 工具（function calling / MCP tool 的描述層）時的四個設計點：
- 描述裏寫邊界：工具描述明確「這個工具會發布內容到生產」——讓模型的規劃層知道動作的重量級；
- 寫操作加確認層：發布/刪除類工具走「先草稿後發布」兩段式，或加人工確認參數——本站內容治理的 R5 紀律（AI 內容一律 draft 待人工審批）就是這一層的制度化；
- 錯誤契約直通模型：把 {error, code, requestId} 信封原樣回傳給模型——code 是機器可讀的，模型能按 40xxx（改參數重試）與 403xx（權限不足，別重試）正確分支；
- 速率自覺：工具描述裏寫明限速（寫操作 60 req/min 量級、批間隔 ≥2s），讓 Agent 的規劃自帶節流。
第四步：審計閉環——每個動作都能回放
本站管理端寫操作全部落審計日志（actor/IP/動作/對象），Agent 接入後的對賬節奏：每日看異常動作（非工作時間的寫操作、高頻失敗）、每周對臺賬（令牌使用與預期任務是否吻合）、每月輪換。Agent 側同樣留檔：工具調用記錄（哪個模型、什麼輸入、調了什麼、返回什麼）與站內審計對得上，事故回溯才是雙向的。審計數據的最低保留期建議 90 天（與本站管理端審計保留策略同量級）；對賬發現的三類異常要立即處置：越權嘗試（scope 設計有漏）、高頻失敗（工具描述或參數映射有問題）、非任務時段活動（令牌可能外流）——第三類直接觸發輪換。
第五步：實例——內容助理 Agent 的權限設計
| 任務 | 工具 | 所需 scope | 護欄 |
|---|---|---|---|
| 起草文章 | POST articles（status=draft） | articles | 只產 draft，發布走人工 |
| 體檢字數/圖/表 | GET admin articles（stats 字段） | articles | 只讀 |
| 修訂內容 | PUT articles/{slug} | articles | 已發布條目禁改（先轉 draft） |
| 行情建檔 | POST markets（null 語義） | markets | 無實測數據必須置 null |
| 發布上線 | —（不給） | — | 人工保留的最後一環 |
這張表就是最小權限的具象：Agent 拿到完成任務的剛好權限，發布權永遠在人手裏——本門戶自己的內容生產就按這張表運轉（46+ 篇草稿全部待人工審批，即本欄目的現場證據）。
接入驗證清單
# 五連驗證（接入完成後逐條跑；PORTAL=門戶 API 域名，令牌走環境變量）
# ① 作用域生效：越權訪問 → 期望 403
curl -s -o /dev/null -w "%{http_code}
" -H "Authorization: Bearer $AXN_CONTENT" $PORTAL/api/admin/settings
# ② 錯誤契約：壞參數 → 期望 40xxx 信封帶 requestId
curl -s -X POST $PORTAL/api/admin/articles -H "Authorization: Bearer $AXN_CONTENT" -H "Content-Type: application/json" -d '{"slug":"x"}'
# ③ 限速：快速連發寫請求觀察 429 與退避
for i in 1 2 3; do curl -s -o /dev/null -w "%{http_code} " -X POST $PORTAL/api/admin/articles -H "Authorization: Bearer $AXN_CONTENT" -d '{}'; done; echo
# ④ 審計：管理端審計日志裏能看到 Agent 的每次寫操作（actor 與 IP 對得上）
curl -s -H "Authorization: Bearer $AX_MASTER" "$PORTAL/api/admin/audit?limit=5"
# ⑤ 吊銷：控制臺吊銷舊令牌後 → 期望 401，Agent 應報告而非靜默失敗
curl -s -o /dev/null -w "%{http_code}
" -H "Authorization: Bearer $AXN_OLD_REVOKED" $PORTAL/api/admin/articles?limit=1相關文檔：API 參考總覽 · Webhook 與事件 · SDK 與庫。Agent 安全的攻擊面全景（提示注入/憑據/最小權限）在AI 與 Agent 安全（安全批次）；趨勢背景見未來 Web 與 Agent；欄目首頁回開發者中心。