ENTRY 004
Agent Key 與每 Agent 額度上限（規劃中）
需求一句話：在「MOKAGI 用量帳單」或「🛡️ Admin 會員管理後台」增加一頁，
能列出所有 agent key，並設定每個 agent 的用量上限額度。
現況：系統目前只有「方案（plan）級」的每月 Token 額度（
plans.monthly_tokens），
尚無「agent 級」額度，也沒有 agent key 的列表頁。本條目＝現有零件盤點 ＋ 待決規格 ＋ 建議方案。
狀態：⏳ 規劃中，程式碼尚未實作。
① 現有零件盤點（零件都在，只是分散）
| 用途 | 現有零件 | 位置 | 狀態 |
|---|---|---|---|
| 價格來源（唯一） | MOKAGI_PRICE_HKD_PER_MILLION ＝ HK$68／百萬 token | core/mok_price.py | ✅ 有 |
| 計費核心 | get_price / price_per_token / cost_of_tokens | core/mok_token.py | ✅ 有 |
| 用量帳單頁 | 標題「MOKAGI 用量帳單」，資料來自 /api/token_stats | html/webTools/token_billing.html | ✅ 有 |
| Admin 後台 | 整合管理後台，分頁 guard／files／svc／adv | html/webTools/admin.html | ✅ 有 |
| 會員與方案 DB | users / plans / settings / agent_owners | member.db | ✅ 有 |
| 方案級額度 | plans.monthly_tokens（後台欄位「每月 Token 額度」） | frontends/mok_web/Plans後台v2_202609231540/保丁.py | ⚠️ 僅「方案級」 |
| 對外 API 金鑰 | api_keys：key_hash／role／allowed_agents／allowed_tools／enabled | frontends/mok_web/對外API_20260907_0357/external_keys.db | ✅ 有（無額度欄） |
| 身分核心 | users.is_admin／agent_owners(agent,owner)；/api/identity/resolve、/api/agent/owner/<agent> | frontends/mok_web/身分核心_202609250200/保丁.py | ✅ 有 |
| GPU 計費 | per-agent 的 gpu_billing.db | core/gpu_billing.py | ✅ 有 |
② 「agent key」可能是指（需選一個）
| 選項 | 定義 | 要做的頁面 |
|---|---|---|
| A | 呼叫該 agent 用的對外 API 金鑰 | 列出 api_keys 全部金鑰（label／role／allowed_agents／last_used），可重發／停用 → 掛 Admin 後台 |
| B | agent 名稱／識別碼清單 | 就是「所有 agent」清單頁（agent 名稱即 key）＋每列一個額度輸入框 |
| C | 沿用現有 api_keys | 只補一個「金鑰管理頁」把它列出來（等於 A 的簡化版） |
③ 「上限額度」要定清楚的規格
| 項目 | 選項 |
|---|---|
| 單位 | token 數 ／ 金額（HK$） ／ 呼叫次數 |
| 週期 | 每日 ／ 每月 ／ 總量 |
| 對象 | 每個 agent 一個上限（不管誰在用）／「每會員 × 每 agent」各一個上限 |
| 超限行為 | 直接拒絕 ／ 只警告 ／ 只記錄 |
| 掛載位置 | 甲：帳單頁加分頁；乙：Admin 後台加 tab；丙：後台設定＋帳單頁唯讀 |
④ 建議方案（無特別指示時照此做）
建議＝「對外 API 金鑰（A）＋ 每 agent 每月 token 上限 ＋ 超過直接拒絕 ＋ 設定放 Admin 後台、帳單頁唯讀同步」。
做法沿用系統既有機制：以補丁（
*保丁.py）掛載，不改 mok_web.py / mokagi.py 核心；
新增一張 agent_quota(agent PRIMARY KEY, monthly_tokens, used_tokens, updated_at) 表，
在計費攔截點（process_message 掛鉤）比對用量後決定放行或拒絕。
⑤ 相關檔案位置
| 檔案 | 角色 |
|---|---|
| jobs/mokagiWIKI/index.html | 本說明書（單檔自含） |
| frontends/mok_web/保丁.py | 補丁載入器（掃描 *保丁.py 自動載入） |
| frontends/mok_web/Plans後台v2_202609231540/保丁.py | 方案／額度後台（plans.monthly_tokens） |
| frontends/mok_web/對外API_20260907_0357/保丁.py | 金鑰驗證、金鑰管理 API（/api/external/keys） |
| frontends/mok_web/身分核心_202609250200/保丁.py | 身分／擁有者（agent_owners） |
| html/webTools/token_billing.html | 用量帳單頁 |
| html/webTools/admin.html | 整合管理後台 |
※ 本條目為 2026-09-25 需求（對話 ID 255065）之盤點與規劃彙整；實作完成後請把狀態 ⏳ 改為 ✅ 並補上實測數據。