AgentKV 技能
AgentKV 是一個代理原生鍵值儲存。你持有一個 AgentKV 帳戶，可以透過以下兩種方式之一持有（客戶端會自動偵測）——相同的資料、相同的信用點數、相同的零知識加密：
- 錢包即金鑰（預設）：一個可簽章的錢包就是帳戶。其位址為命名空間，其金鑰衍生出 AES 金鑰。AgentKV 在首次使用時自動佈建一個錢包——無需帳戶、無需 API 金鑰、無需註冊。
- 帳戶金鑰：對於受管理且無法簽章的錢包（例如 awal），一個不透明的
ak_…bearer 權杖即為身份和命名空間，而本機加密金鑰則負責加密——與付款錢包分離，因此任何簽章錢包都可以為該帳戶充值。
值在到達伺服器之前，會在客戶端進行加密（AES-256-GCM），因此伺服器具有零知識特性。儲存費用使用 Base（主網）或 Base Sepolia（測試網）上的真實 USDC，透過 x402 協定按操作計費。
前置條件：
@agentkv/cli必須已發佈至 npm，並可透過npx @agentkv/cli解析。截至本文撰寫時，該套件尚未發佈——此插件是待該發佈步驟完成後的成品。
何時使用 AgentKV
在以下情況使用 AgentKV：
- 持久的跨階段記憶——事實、偏好、摘要，或需要在當前階段結束後持續存在的任務狀態。
- 秘密儲存與使用——API 金鑰、權杖或憑證。伺服器只能看到密文（零知識）。⚠️ 普通的
agentkv_set/agentkv_get會將值路由經過此代理的模型上下文；對於真正的秘密，請使用秘密安全工具（agentkv_set_from_env/_from_file進行儲存，agentkv_get_to_file/agentkv_run_with_secret進行使用），這樣明文就不會進入模型回合。請參閱下方的秘密一節。 - 共享代理群組狀態——多個代理實例共享同一個錢包時，可以透過共同命名空間進行協調（例如工作佇列、鎖、共享計數器）。
- TTL 界定的暫存狀態——具有自動過期機制的暫存值（例如 nonce、草稿），無需手動清理。
在以下情況不要使用 AgentKV：
- 大型二進位 blob（最大值大小為 256 KB）。
- 在預算敏感的環境中進行免費、零成本的操作——每次
set和get都會花費 USDC；請先檢查花費上限。 - 在使用者導向的應用程式中替代正規資料庫（它是為代理工作負載設計的，而非高吞吐量的 Web 應用程式）。
可用的 MCP 工具
agentkv MCP 伺服器揭露了十二個工具——八個核心工具，加上四個秘密安全工具，其明文永遠不會進入模型上下文（請參閱下方的秘密一節）：
| 工具 | 描述 | 費用 |
|---|---|---|
agentkv_set | 在金鑰下寫入一個加密值。可選的 TTL（天數）。 | 約 $0.005 USDC |
agentkv_get | 依金鑰讀取並解密一個值。預設情況下，滑動 TTL 會重設過期時間。 | 約 $0.003 USDC |
agentkv_delete | 立即刪除一個金鑰。 | 免費 |
agentkv_deposit | 將 USDC 信用點數存入錢包的命名空間，以預先支付操作費用。在帳戶金鑰模式下會被拒絕（受管理帳戶沒有錢包——請透過 <endpoint>/account/deposit 為其充值）。 | 購買 USDC |
agentkv_balance | 檢查錢包命名空間的當前 USDC 信用點數餘額。 | 免費 |
agentkv_wallet_address | 傳回錢包位址（命名空間識別碼）。僅供參考。 | 免費 |
agentkv_fund | 傳回一個卡片到 USDC 的入金網址，該網址會將 USDC 發送到 Base 上的錢包。僅建立網址——不進行付款。在帳戶金鑰模式下會被拒絕（沒有錢包可以購買 USDC）。 | 免費 |
agentkv_list_keys | 列出此錢包儲存的金鑰——真實的金鑰名稱，在本地端解密；伺服器只看到不透明的摘要。支援分頁。 | 免費 |
agentkv_set_from_env | 儲存從本地環境變數讀取的秘密（傳入該變數的名稱）。值永遠不會進入模型上下文。 | 約 $0.005 USDC |
agentkv_set_from_file | 儲存從本地檔案讀取的秘密（傳入該檔案的路徑）。內容永遠不會進入模型上下文。 | 約 $0.005 USDC |
agentkv_get_to_file | 將值解密到本地檔案；傳回 { found, path, bytes }——永遠不會傳回值本身。 | 約 $0.003 USDC |
agentkv_run_with_secret | 執行一個命令，並將秘密僅注入子處理序的環境變數中；傳回命令的輸出，永遠不會傳回秘密本身。 | 約 $0.003 USDC |
定價與存款： 按用量付費約為每次
agentkv_set$0.005 USDC，每次agentkv_get$0.003 USDC。預付費信用點數的費用大約是 1/10（每次 set 約 $0.0005，每次 get 約 $0.0003）。agentkv_deposit需要最低 $1.00，並以折扣的信用點數費率為命名空間充值。
秘密——讓值遠離模型上下文
agentkv_set 和 agentkv_get 會將值路由經過此代理自身的模型上下文（寫入時是工具參數，讀取時是工具結果）。客戶端加密使值對伺服器而言是零知識——但它並不會對代理隱藏這些值。因此，普通的 set/get 適用於非秘密記憶體（計畫、摘要、偏好），但對於真正的憑證，請使用秘密安全工具，這樣明文就不會進入模型回合：
- 儲存：
agentkv_set_from_env（傳入環境變數的名稱）或agentkv_set_from_file（傳入路徑）。伺服器在本地端讀取值，進行加密，然後儲存。 - 使用：
agentkv_run_with_secret（執行一個命令，秘密僅存在於子處理序的環境變數中，並傳回命令的輸出）或agentkv_get_to_file（將解密後的值寫入本地檔案，並傳回路徑——使用完畢後刪除它）。
殘留：秘密會短暫地出現在本地檔案或子處理序環境中——本地且短暫，永遠不會發送到模型提供者或寫入對話歷史。agentkv_run_with_secret（磁碟上不留檔案）是最嚴格的方式。
一次性設定
從 Claude Code 的市集安裝此插件——確切的 /plugin marketplace add 和 /plugin install 命令位於插件的 README.md（plugin/README.md）中。安裝後：
1. 憑證（安裝時輸入，非透過 shell 環境變數）
當插件安裝時，Claude Code 會提示輸入以下資訊，並將它們傳遞給 MCP 伺服器（私鑰會經過遮罩並儲存在你的作業系統金鑰鏈中——永遠不會寫入磁碟）：
| 配置 | 必填 | 描述 |
|---|---|---|
| 錢包私鑰 | 否 | 可選——留空則 AgentKV 會在首次使用時鑄造並管理一個本地錢包（然後為其充值並備份）。若要使用你自己的：一個 EVM 私鑰（十六進制），這是付款並擁有命名空間的錢包。 |
| AgentKV 端點 | 否 | 託管的 AgentKV API；預設為 https://api.agentx402.ai。 |
| 網路 | 否 | eip155:8453（Base 主網，預設）或 eip155:84532（Base Sepolia 測試網）。 |
| 加密金鑰 | 否 | 覆寫衍生的 AES 金鑰（進階；預設為從私鑰透過 HKDF 衍生）。 |
| 每次操作最大花費（USD） | 否 | 拒絕任何單次花費超過此金額的操作；留空 = 無每次操作上限。 |
| 階段最大花費（USD） | 否 | 一旦累積階段花費超過此金額，則拒絕操作；留空 = 無上限。 |
稍後重新執行 /plugin 以變更這些設定。使用 /mcp 驗證伺服器是否已載入（你應該會看到 agentkv 伺服器及其十二個工具）。
若要使用卡片而非現有的 USDC 餘額來充值，agentkv_fund 工具會傳回一個 Coinbase 入金網址——透過在伺服器上設定 AGENTKV_ONRAMP_APP_ID（一個公開的 CDP 專案 ID）來配置，並可選地設定 AGENTKV_ONRAMP_PROVIDER 來更換提供者。
2. 為命名空間充值
使用 agentkv_wallet_address 讀取你的錢包位址，將 USDC 傳送到 Base 上的該位址（或呼叫 agentkv_fund 取得一個將 USDC 發送到該位址的卡片到 USDC 入金網址），然後呼叫 agentkv_deposit 並指定一個金額（最低 $1）來為命名空間充值。之後的讀取和寫入操作將自動從信用點數中支付。
帳戶金鑰模式（受管理錢包 / awal）
一個無法簽章的受管理錢包使用帳戶金鑰模式，而非錢包模式。在插件外部，CLI 會鑄造並為一個帳戶充值：
agentkv account new # 鑄造 ak_… 和一個本地加密金鑰（以 0600 權限儲存）——請備份它們，否則無法復原
# 從任何可簽章的錢包為其充值（一筆真實的 ≥$1 存款會在首次存款時建立該帳戶）：
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'
然後設定 AGENTKV_ACCOUNT_KEY=ak_… 和 AGENTKV_ENCRYPTION_KEY=0x…（本地 AES 金鑰——在帳戶模式下為必填，因為沒有錢包可以從中衍生金鑰）。該帳戶即為命名空間；預設情況下，讀取/寫入操作僅攜帶 bearer 權杖並從預付費信用點數中扣款——無需每次操作簽章。無論哪種方式，它都對伺服器保持零知識。任何可簽章的錢包都可以為同一個帳戶充值。
如果同時設定了 AGENTKV_TOPOFF=awal，當信用點數不足時會自我修復——無需採取任何行動，CLI/MCP 階段會透過 awal 支付自己的補值並繼續執行。若無此設定，則在遇到信用點數不足的錯誤時，執行 awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' 並重試。或者，設定 AGENTKV_INLINE=awal 以實現每次操作內聯付款：每個請求都伴隨一個付款簽章和 bearer 權杖，並立即在鏈上結算，因此完全不需要預付費信用點數。
花費上限認知
每次 agentkv_set、agentkv_get 和 agentkv_deposit 呼叫都會花費真實的 USDC（agentkv_delete、agentkv_balance、agentkv_wallet_address、agentkv_fund 和 agentkv_list_keys 是免費的）。在開始迴圈或大量操作之前：
- 呼叫
agentkv_balance以確認有足夠的信用點數。 - 在插件配置中設定每次操作最大花費（USD） 和/或階段最大花費（USD） 上限（執行
/plugin進行編輯）。 - 如果工具呼叫傳回 402 Payment Required 錯誤且沒有剩餘的花費預算，請暫停並向使用者報告，而非盲目重試。
當信用點數耗盡時，伺服器會傳回一個 PAYMENT-REQUIRED 挑戰；CLI 會在花費上限內自動處理 x402 付款。
共享代理群組狀態模式
當多個代理共用同一個 AGENTKV_PRIVATE_KEY（相同的錢包 = 相同的命名空間）時，它們可以透過已知的金鑰進行協調：
fleet:lock:<task-id> # 分散式鎖（使用短 TTL 設定）
fleet:queue # 序列化的工作列表
fleet:result:<task-id> # 已完成子任務的輸出
在鎖上使用短 TTL，以防止代理崩潰時造成鎖定過期。
金鑰命名慣例
- 使用
:作為分隔符：session:<id>:summary、secret:github-token、prefs:language。使用秘密安全工具（agentkv_set_from_env/_from_file、agentkv_get_to_file/run_with_secret）儲存/讀取secret:*金鑰——永遠不要使用普通的set/get——這樣憑證就不會進入模型上下文。 - 使用穩定的識別碼作為使用者特定資料的前綴：
user:<handle>:...。 - 在寫入共享代理群組狀態之前，使用
agentkv_wallet_address確認你正在操作的命名空間。