ii999/agentenv

# agentenv

`agentenv` 會讀取一個本機的 TOML 設定檔，該檔案中儲存了一般值與憑證的參考。憑證值存在於環境變數、平台憑證儲存庫或外部指令中——絕不會存在於檔案中。CLI 會讀取值、以保留格式的驗證寫入方式編輯檔案，並將選定的值注入到一個暫時的環境中來啟動目標程序。

請先使用 `command -v agentenv` 確認 CLI 可用再依賴它。如果缺少此指令，請告知並停止，不要透過直接讀取設定檔來重新建構其行為。

## 嚴格規則

- 絕不列印、記錄、持久化或總結已解析的憑證值。不要以會揭露其自身環境的目標來啟動 `agentenv run` —— 使用 `env`、`printenv`、`set`、`sh -c 'echo $VAR'` 或將環境寫入檔案都屬於違規。
- 絕不將機密值寫入設定檔。`set` 僅用於一般值；`credential add` 僅寫入定義；`credential set` 是唯一儲存值的路徑，且它將值儲存在平台憑證儲存庫中，而非檔案中。
- 如果某個設定檔、條目、欄位或憑證缺失，請明確回報。不要猜測欄位名稱、靜默切換設定檔或替代為其他憑證。
- 透過 CLI 而非直接開啟 TOML 檔案來讀取設定，這樣設定檔選擇、憑證間接引用和驗證才會生效。
- 在 `credential fill` 將一個值寫入瀏覽器欄位後，不要回讀該欄位、評估其值或拍攝顯示該值的螢幕截圖。填寫的結果是唯一可以回報的內容。

## 讀取設定

由上而下進行；跳過您在此會話中已經完成的步驟。

1. `agentenv project status --json` —— 在讀取依賴設定檔的設定之前，先發現最近的專案檔案及其信任狀態。其報告會寫入標準輸出，即使它以狀態碼 `5` 或 `6` 退出；退出碼 `2` 則會使標準輸出保持空白。
2. `agentenv list --json` —— 發現設定檔和條目。
   `agentenv list --profiles` 會列出設定檔名稱，而不選擇其中一個。
3. `agentenv show <entry> --json` —— 在使用一個不熟悉的條目之前先檢查它。憑證欄位會以一個 `reference` 成員（`credential://<name>` 或 `credential://<name>?as=<ENV>`）的形式出現，絕不會是值。
4. `agentenv get <path>` —— 讀取一個純量值。對於陣列或表格，請使用 `--json`。讀取一個憑證欄位會返回參考字串，而非機密。
5. `agentenv find <needle> --json` —— 在您不知道某個項目位於何處時，搜尋條目名稱、欄位名稱、描述和字串值。加上 `--all-profiles` 可搜尋所有設定檔。

路徑是所選設定檔內以點分隔的欄位片段，例如 `llm.model`。如果某個片段包含標點符號或空格，請加上引號：`servers."my host".port`。設定檔不屬於路徑的一部分；請使用 `--profile <NAME>` 來選擇它（優先順序：`--profile`，然後 `AGENTENV_PROFILE`，然後受信任的專案檔案固定設定，最後是檔案中的 `default_profile`）。這適用於讀取、`run`、`set` 和 `unset` 指令。`--create-profile` 需要明確的 `--profile`，且絕不會使用固定設定。

## 專案範圍的設定

`agentenv` 會從工作目錄向檔案系統根目錄搜尋，發現最近的 `.agentenv.toml` 檔案。該檔案具有封閉且僅供選擇的結構：`version = 1`、一個可選的非空 `profile`、以及可選的 `[requires.<entry>]` 表格，內容包含非空的 `reason` 和可選的條目相對 `fields`（如果存在則為非空）。其大小限制為 64 KiB，且不能包含值、憑證定義、`inject` 表格或 `credential://` 字串。

專案檔案在其確切內容被核准之前是不起作用的。請使用 `agentenv project status`、`agentenv project allow` 和 `agentenv project revoke` 來檢查、核准和撤銷核准。核准記錄儲存在使用者狀態目錄中，位於儲存庫之外；編輯檔案會使其再次變為不受信任。不受信任的檔案不會影響任何一般指令，除了在標準錯誤輸出中顯示一則通知。

使用 `--no-project` 或非空的 `AGENTENV_NO_PROJECT`，可以為 `project` 群組以外的指令繞過發現程序。此繞過絕不適用於 `project status`、`project allow` 或 `project revoke`，這些指令總是會發現最近的檔案。

`project status --json` 會特意將其報告寫入標準輸出，對於不可用、無效或不受信任的專案狀態，退出碼為 `5`；當需求未滿足或無法檢查時，退出碼為 `6`。這是對一般 JSON 失敗時標準輸出為空規則的例外。退出碼 `2` 涵蓋設定錯誤，包括專案檔案的驗證錯誤，並且會為此指令清空標準輸出。

## 執行需要憑證的指令

使用 `run` 並加上一個或多個 `--with <entry>` 旗標，目標指令放在 `--` 之後：

```bash
agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync

每個 --with 條目會貢獻其憑證參考及其 inject 表格（該表格將環境變數名稱對應到該條目的一般欄位）。一個憑證會以其 inject_as 名稱注入，除非該參考帶有 ?as=<ENV> 覆蓋。要了解目標將收到哪些環境變數名稱，請從 agentenv credential list --json 讀取 inject_as，並從 agentenv show <entry> --json 讀取 inject 表格和 reference 成員。

目標的標準輸入/輸出/錯誤會原封不動地傳遞，並返回其退出狀態。衝突的注入（兩個來源指向同一個環境變數名稱）會在解析或啟動任何東西之前，以退出碼 4 中止。

加上 --pure 可以讓目標在一個精心挑選的最小環境中啟動：一個固定的平台基礎（PATH、HOME、locale、AGENTENV_* 和類似的程序關鍵名稱），加上使用可重複的 --keep <NAME> 明確攜帶的變數，再加上注入的內容——除此之外沒有來自呼叫 shell 的任何東西。如果被保留的名稱在父程序中未設定，則會在標準錯誤輸出中回報，且程式會繼續執行。--pure 僅過濾目標的環境；它不是一個沙盒，且目標內部的巢狀 agentenv 呼叫仍然會解析相同的設定。--pure 不會改變憑證解析：一個 command 提供者的子程序會保留完整的父程序環境。

寫入設定

在使用者要求記錄設定時使用這些指令：

agentenv init                            # 建立設定檔；拒絕覆寫
agentenv set <path> <value>              # 寫入一個值；建立中介表格
agentenv set <path> <value> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "Default LLM."   # 也會建立條目
agentenv set <path> <value> --profile dev --create-profile "Dev profile."
agentenv unset <path>                    # 移除一個欄位或表格

每個條目都需要一個描述；建立一個新的頂層條目需要在同一個 set 指令中使用 --description。除非您使用明確的 --profile 加上 --create-profile，否則未知的設定檔會被視為錯誤。每次寫入都會先進行整個檔案的驗證，如果結果無效則拒絕，因此被拒絕的寫入會使檔案保持完全相同的位元組——請回報診斷訊息，而不是盲目地嘗試不同變體。

驗證會拒絕將純文字值放入名稱（或後綴）為 token、password、secret、api_key 或 private_key 的字串欄位：此類欄位必須包含一個 credential:// 參考。當使用者交給您一個機密要儲存時，請將其定義為一個憑證（下一節）並儲存它，然後再進行參考。

管理憑證

agentenv credential list --json          # 定義 + 淺層狀態；不解析任何內容
agentenv credential check <name>         # 解析一個憑證；僅回報可用性
agentenv credential add <name> --description "<text>" --provider env \
    --env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider keychain \
    --service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider command \
    --argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json  # 開啟本機輸入視窗；等待其結果

新憑證的順序：先使用 credential add 新增定義，然後對於 keychain 提供者，使用 credential set 儲存值，最後在條目欄位中將其參考為 credential://<name>。Env 和 command 憑證從其外部系統獲取值；credential set 不適用於它們。

對於本機 keychain 輸入，請在沒有 PTY 的情況下啟動 credential set <name> --input dialog --json。告訴使用者在本地視窗中輸入值並儲存。讓指令持續執行並等待其完成，包括跨工具會話的暫停；一個開啟的視窗並不代表儲存完成。絕不要檢查、捕獲、讀取或自動化正在運行的輸入視窗或剪貼簿。使用者在那裡輸入和檢查值，而指令僅返回完成的中繼資料。

僅在退出碼為 0 且 JSON 顯示 status: "stored" 時，才繼續執行依賴任務。status: "cancelled" 表示輸入在未確認儲存的情況下結束；請回報此事並停止依賴的動作。status: "failed" 會包含一個非機密的 reason；請回報診斷訊息。store-unconfirmed 表示可能已進行寫入，因此請不要聲稱先前的值未更改，也不要自動重試。啟動/設定錯誤可能在發出 JSON 之前就退出；請將非零退出碼或缺少結果的狀況視為失敗。如果儲存正在進行中，它會在指令返回前完成；即使使用者在該寫入期間要求關閉，已確認的寫入仍會回報為 stored。

此對話框需要在執行 agentenv 的機器上有一個圖形化會話。在遠端或無頭主機上，請解釋此限制，並讓使用者在該主機的終端機中自行執行 agentenv credential set <name> --input terminal，然後確認完成。請不要使用代理所擁有的 PTY 或標準輸入管道來替代。絕不要在聊天中詢問該值，也不要將其放入 argv、環境變數、指令管道或檔案中。終端機輸入支援本地顯示切換，因此其螢幕輸出必須保持在代理工具的範圍之外。

對於本機使用，建議優先使用 keychain 或 command 提供者；env 會將值暴露給繼承環境的每個程序，因此更適合 CI 環境。

Docker Compose 配對

將非機密的設定保留在 .env 中。僅將憑證注入給需要它們的程序，然後讓 Compose 接收注入的變數：

agentenv run --with llm -- docker compose up

services:
  app:
    image: alpine:3.20
    environment:
      - OPENAI_API_KEY

Compose 也支援 ${OPENAI_API_KEY} 插值。不要使用包含機密的 env_file:；這會將憑證持久化到檔案中。

將憑證填入瀏覽器欄位

當您正在驅動的頁面需要在一個輸入欄位中填入一個已儲存的憑證時，請使用 credential fill。它會透過瀏覽器的除錯協定寫入該值；您可以使用自己的瀏覽器工具繼續導航和提交。

agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
    --page-url <exact page URL> --selector '<css of the one input>' --json

步驟：

1. 使用 --capabilities 確認 cdp 後端列為可用。您的瀏覽器必須暴露一個迴環 Chrome DevTools Protocol 端點（使用 --remote-debugging-port 和非預設的 --user-data-dir 啟動的 Chromium，或您的瀏覽器工具已使用的端點）。如果沒有，請告知；不要啟動瀏覽器或貼上該值。
2. 使用您的瀏覽器工具導航到頁面，然後傳遞頁面的確切 URL 和一個僅匹配目標輸入的 CSS 選擇器。當 URL 帶有易變的查詢參數時，加上 --page-match origin-path；對於到達該欄位路徑上的每個 iframe，加上 --frame-selector；如果同一 URL 在多個上下文中開啟，加上 --context-index。
3. 在填寫時，關閉該分頁上的 DevTools，並保持追蹤、螢幕錄影、HAR 和影片錄製功能關閉；agentenv 只會在開啟的 DevTools 視窗上失敗，因為其他記錄器無法被偵測到。
4. 執行指令。成功時僅會輸出 {"version":1,"backend":"cdp","effect":"field-filled"}；該欄位先前的內容已被替換，且頁面收到了正常輸入事件。繼續使用您自己的工具來提交。

只有允許 environment 使用的憑證才能被填入；該值必須是單行，最多 8,192 位元組，且不含控制字元、行分隔符號或雙向控制字元（否則為 value-unsupported）。command 提供者在沒有終端機的情況下執行，其尾隨的一個換行符會被去除；空值、NUL 或非 UTF-8 的提供者輸出屬於憑證錯誤（退出碼 4）。整個操作，包括首次存取時的 keychain 授權對話框，都在 --timeout-ms（預設 30,000）下執行；當使用者必須點擊通過此類對話框時，請調高此值。credential fill 不會驗證欄位、提交表單或登入；請回報其效果，而不是您未觀察到的成功。

失敗原因會顯示在標準錯誤輸出中（credential-fill: <reason>: <message>）。退出碼 8，未發生任何更改：backend-unavailable、permission、connect-failed、version-unsupported、recording-conflict、context-absent、page-absent、page-ambiguous、frame-absent、frame-ambiguous、frame-invalid、target-absent、target-ambiguous、target-hidden、target-disabled、target-readonly、target-unfillable、target-changed、value-unsupported、timeout、cancelled。退出碼 11，欄位可能已包含該值：timeout、cancelled 或 delivery-failed（在值已發送後），以及 cleanup-unconfirmed（在值已送達後）。

特權執行

當請求使用已設定的 sudo-target 時，請在規劃、檢查、執行、建立或輪換該目標之前，先閱讀 references/sudo-execution.md。

…

[為翻譯而截斷]