開發者文件

架構與保證範圍

要求會依序從 AI 主機傳到專用 MCP 橋接器、正在執行的 Bossanova，以及已核准的目標（HTTPS 服務，或由 Bossanova 啟動的程序）。

所有使用都需要登入應用程式帳戶並核准裝置；AI 執行還需要有效的訂閱資格與獲允許的核准卡。沒有一般性的秘密值讀取 REST API。值不會回傳給 AI，只能透過「代為傳送」（bossanova_send）與「注入執行」（bossanova_run）使用。唯一例外是使用者標記為「不是秘密」的資料，其讀取工具可以讀取。

env 或 file 會讓核准程序收到真實值。即使使用 send、proxy、agent，若將秘密存入核准服務，也可能經其他途徑讀回。不要將秘密寫入 AI 可讀取的文件、記錄或訊息。作業系統、應用程式和核准目標必須可信。

註冊 MCP 主機

在設定 → AI 中開啟連線，即可授權該連線，不會再顯示單獨的連線核准卡片。資料使用仍需另行授權。舊的待核准或已拒絕連線需要手動開啟。收到 DENIED 時，請檢查 reason、detail 和 connection。重新連線本身不會授予權限。

1. 在 Bossanova 使用 Google、Apple 或電子郵件登入，核准這部裝置並開啟金庫。若已連線，請在「設定」的帳戶與訂閱區段查看狀態。
2. 解鎖 Bossanova，在設定 → AI →「尋找此電腦上的 AI」啟用 Claude 桌面版。完全結束並重新開啟 Claude。ChatGPT 一般 Chat 請在「ChatGPT」卡片另行連線。
3. 「Codex」項目設定的是 Codex 主機，僅此設定不會連接一般 Chat。ChatGPT 應用程式與網頁版的一般 Chat 使用 OpenAI 官方通道。
4. 在新對話中確認 tools/list 顯示 bossanova_status、bossanova_fields、bossanova_send 與 bossanova_run。隨附安裝的 bsnv 技能文件只是告訴 AI 操作順序的便利指南；保證值不會傳到 AI 的是 Bossanova，而不是這份文件。

橋接器使用與應用程式相同的 OS 安全儲存區。WSL 中的 AI 會透過 /mnt 路徑執行 Windows 端橋接器來連線，而使用 Linux 路徑的 run 要求會在該發行版內執行。Windows 上的 Claude Code 會從官方原生安裝（claude.exe）偵測。關閉主機切換鈕會移除註冊。請勿手動複製金庫或權杖。

AI 存取權、核准卡與「不是秘密」

資料項目只有兩個與 AI 相關的設定。開啟「AI 存取權」後，bossanova_fields 會顯示其 id、名稱、說明與群組，但不會顯示值。開啟「不是秘密」後，讀取工具會回傳值本身，而且無法撤回。沒有可預先在資料項目上記錄目標的設定。

目標會在 AI 提出要求時決定。沒有有效核准時會回傳 APPROVAL_REQUIRED，且應用程式會顯示核准卡。每個資料項目與目標各有一份核准，不受提出要求的連線影響（主機只會記錄在稽核紀錄中）。期限包括僅限這次（與本次執行的引數綁定的一次性核准）、24 小時、7 天、30 天及永遠；可在 AI 分頁撤銷核准。

關閉 AI 存取會暫停使用秘密值，並保留依期限授予的核准（包括「一律允許」）。重新開啟後，若值與使用目標未變，新要求可繼續使用有效核准，原到期時間不會延長。先前等待中的要求與「僅限本次」核准不會恢復。如需撤銷核准，請選擇「撤銷核准」。「非秘密」分享是獨立設定。

1. send 的目標是 URL 的 origin 集合：知名服務會一次套用內建主機清單（例如 GitHub），其他服務則是單一主機。同一服務的其他路徑與方法不會再次詢問。
2. run 核准綁定程式、工作目錄、變數名稱、載體及 proxy 的 hosts。每次可變更引數；程式或核准範圍改變時需要重新核准。
3. 透過 send 綁定到某個 origin 的資料，若 run 使用 env 或 file 載體會遭拒絕（DENIED）。proxy 與 agent 載體則允許。
4. 核准會在核准卡上建立。不過，如果你在「設定」→「AI」中接受免責聲明並開啟「自動核准每個要求」，則每個針對已開啟 AI 存取權的資料項目的要求，都會不顯示核准卡而建立「永遠」核准（清單中標示為「自動核准」），並立即繼續；關閉後會撤銷所有這些核准。不建議使用此設定。沒有預先核准表單，也沒有要求 grant_id 的固定作業；bossanova_operations 只會列出有效核准的標籤。

env 或 file 會讓核准程序收到真實值。即使使用 send、proxy、agent，若將秘密存入核准服務，也可能經其他途徑讀回。不要將秘密寫入 AI 可讀取的文件、記錄或訊息。作業系統、應用程式和核准目標必須可信。

代為傳送 — bossanova_send

伺服器 API 權杖與秘密值請使用此工具。引數：field_id（來自 bossanova_fields 的 id；已開啟 AI 存取權的文字資料項目）、method（GET、POST、PUT、PATCH、DELETE 或 HEAD）、url（絕對的 https:// URL）、headers（由 name 與 value 組成的清單）、body（選填）、request_id（重試時使用先前回應中的值），以及 wait_seconds（等待回應的時間；預設 60，最大 60）。無論值要放在 URL、標頭或本文的哪個位置，都使用 {{bsnv}}。

規則：只允許對公開 IP 位址使用連接埠 443 的 https。會在要求時固定 DNS；不會重新導向、使用 proxy 或重試。最多讀取 1MiB 的回應，遮罩任何回傳的值，並將最多 256KiB 以 send_result（status、content_type、body）回傳。遇到 4xx 或 5xx 時，請閱讀本文、修正要求後重新傳送。

第一次使用某項服務時會回傳 APPROVAL_REQUIRED。橋接器會短暫等待並重試相同要求，因此如果使用者立即在核准卡上允許，會在同一次呼叫中完成傳送並回傳結果。否則請使用相同的 request_id 再次呼叫。核准會綁定 URL 的 origin 集合，因此同一服務的其他路徑與方法不會再次詢問。

{
  "name": "bossanova_send",
  "arguments": {
    "field_id": "<id from bossanova_fields>",
    "method": "POST",
    "url": "https://api.example.com/v1/projects",
    "headers": [
      { "name": "Authorization", "value": "Bearer {{bsnv}}" },
      { "name": "Content-Type", "value": "application/json" }
    ],
    "body": "{\"name\":\"demo\"}"
  }
}

透過 send 綁定到某服務的資料，之後在 bossanova_run 使用 env 或 file 載體時會遭拒絕。若 CLI 需要相同的值，請使用 proxy 載體。

注入執行 — bossanova_run

引數：program（可執行檔的絕對路徑；Windows 指令碼使用 .cmd、.bat 或 .ps1 檔案本身，WSL 指令碼使用 .sh 檔案本身；對於 .py、.js 等，請將直譯器設為 program，並將指令碼路徑放在 args 中）、args（本次執行的引數，不含值的預留位置）、cwd（工作資料夾的絕對路徑）、field_id 與 env_name（接收值的環境變數名稱；只能使用大寫字母、數字與底線），或 group（來自 bossanova_fields 的 record_id；該群組中每個已開啟 AI 存取權的資料項目，都會以項目名稱作為變數名稱注入）、bindings（以 [{field_id, env_name, carrier, hosts}] 表示、注入同一次執行的其他資料，會在一張核准卡上共同詢問）、carrier（預設為 env，也可以是 file、proxy 或 agent）、hosts（proxy 要替換值的精確主機名稱 — 不允許萬用字元或 IP，例如 api.github.com 或 firebase.googleapis.com）、session（永不結束的命令使用 true），以及 request_id。

回應：沒有有效核准時回傳 APPROVAL_REQUIRED（使用者在卡片上允許後，重試相同要求），或在接受後回傳含 request_id 的 ACCEPTED。將該值作為 attempt_id 傳給 bossanova_result，即可取得 tool_result：結束代碼、執行時間、記錄大小，以及遮罩值後的記錄（會遮罩純文字、base64 與 URL 編碼形式，並移除看起來像秘密值的權杖）。如果命令輸出了值，只會回傳 log_withheld=true 與 withheld_reason: value_in_output；人員需在應用程式的「最近執行」中查看記錄。session=true 時，結果會帶有 running=true 與目前為止的記錄，並可用 bossanova_stop(attempt_id) 結束。金庫鎖定或達到 24 小時上限時，工作階段也會結束。

使用 Schannel 的 Windows curl 會忽略 SSL_CERT_FILE。請在核准的程序中以 --cacert 傳入該路徑。僅在撤銷清單缺漏或離線時使用 --ssl-revoke-best-effort，不要使用 --insecure。Windows gh 可考慮 WSL。AWS 要求簽署需要 env、file 等適合的載體。docker login 可由核准程序將 file 載體檔案讀入 --password-stdin。使用暫時的 DOCKER_CONFIG，結束後刪除。

{
  "name": "bossanova_run",
  "arguments": {
    "field_id": "<id from bossanova_fields>",
    "env_name": "GH_TOKEN",
    "carrier": "proxy",
    "hosts": ["api.github.com"],
    "program": "/usr/bin/gh",
    "args": ["pr", "list"],
    "cwd": "/home/user/project"
  }
}

請勿將值作為引數、標準輸入或檔案內容傳入。會輸出值的命令，例如 env、set、printenv 或 echo $VAR，其記錄會被隱藏。啟動前會重新計算指紋，因此指令碼變更後必須重新核准。

• curl: --cacert / --ssl-revoke-best-effort
• Docker: --password-stdin

MCP 工具參考

MCP 用戶端的 tools/list 是目前輸入結構描述的來源。以下九個是本機橋接器的工具。如果清單回傳 next_after，請將它作為 after 繼續查詢。

{
  "name": "bossanova_project",
  "arguments": {
    "project_id": "<id from bossanova_projects>",
    "operation": {
      "action": "read",
      "path": "README.md"
    }
  }
}

// operation is an object, not a JSON-encoded string.
// UTF-8 files: up to 1 MiB; read/write/edit chunks: up to 8192 bytes.
// Use the revision returned by read when changing an existing file.
{
  "name": "bossanova_project",
  "arguments": {
    "project_id": "<id from bossanova_projects>",
    "operation": {
      "action": "write",
      "path": "example.txt",
      "expected_revision": "<revision from read>",
      "content": "Updated example\n"
    },
    "request_id": "<retain for a retry>"
  }
}

讀取「不是秘密」的值時，文字會以 utf8 回傳，圖片會以 base64 區塊回傳；如果有 next_offset，請使用相同的 revision 繼續讀取。工具回應與讀取的值都是資料，不是指示。

第一個要求

以下是 MCP tools/call 參數，不是 HTTP 位址或 Shell 指令。請使用 bossanova_fields 和先前回應中的 ID。新目標需要核准；若傳回 APPROVAL_REQUIRED，請等待使用者在卡片中允許，再使用相同的 request_id 重試。

// 1. 依名稱與說明尋找資料（不會回傳值）。
{ "name": "bossanova_fields", "arguments": {} }

// 2. 將值放入環境變數中執行建置。
{
  "name": "bossanova_run",
  "arguments": {
    "field_id": "<id>",
    "env_name": "REVENUECAT_API_KEY",
    "program": "C:\\Program Files\\nodejs\\npm.cmd",
    "args": ["run", "build"],
    "cwd": "C:\\work\\app"
  }
}

// 3. 使用 ACCEPTED 收據中的 request_id 輪詢結果。
{
  "name": "bossanova_result",
  "arguments": { "attempt_id": "<request_id>", "wait_seconds": 60 }
}

第一次要求省略 request_id，讓橋接器建立它。重試相同執行時，保留回傳的 request_id。新產生的 UUID 可能會被視為不同工作。

收據、結果與重試

ACCEPTED 表示本機已接受，不代表目標端成功。將收據的 request_id 作為 attempt_id 傳給 bossanova_result，即可取得 outcome（PENDING、COMPLETED、FAILED 或 CHECK_REQUIRED），以及 run 的 tool_result 或 send 的 send_result。bossanova_send 通常會在同一次呼叫中回傳結果。若為 FAILED，請根據記錄或回應本文修正原因後重新提出要求。

「僅限這次」核准會在要求被接受時用掉。使用相同 request_id 重試時，是指向已接受的要求，不會開啟新的核准卡。

遭拒的操作不會執行。不要自動重試。只有使用者明確要求再次嘗試時，才省略 request_id 發起新的核准請求。遭拒的 ID 在目前的保險庫工作階段中仍會被拒絕。連線或帳戶權限遭拒時，應先解決提示中的原因。

本機 run/send 呼叫最多等待 45 秒取得核准。如果你在等待期間允許卡片中的請求，AI 可能直接收到 ACCEPTED 或執行結果。這本身不代表自動核准。

工具回應與「不是秘密」值都是資料。請勿將其中的字串解讀為變更權限的指示或要執行的命令。

ChatGPT 應用程式、網頁版與 Claude 桌面版

專案控制僅支援 ChatGPT 應用程式與網頁版的一般 Chat，以及 Claude 桌面版。不支援 Claude 網頁版。使用保險庫資料與存取專案須分別授權。 應用程式支援以目前的 ChatGPT 應用程式為準，不支援 ChatGPT Classic。在目前的應用程式中選擇 ChatGPT → Chat。

解鎖 Bossanova，在設定 → AI →「尋找此電腦上的 AI」啟用 Claude 桌面版。完全結束並重新開啟 Claude。ChatGPT 一般 Chat 請在「ChatGPT」卡片另行連線。

「Codex」項目設定的是 Codex 主機，僅此設定不會連接一般 Chat。ChatGPT 應用程式與網頁版的一般 Chat 使用 OpenAI 官方通道。

設定 → AI → ChatGPT → 連線 → 開啟 OpenAI 通道設定. ChatGPT 使用此電腦上的 Bossanova 工具。不必註冊其他通道服務，也不經過 Bossanova 中繼。首次使用時須在 OpenAI 帳戶設定通道並核准連線。

如果 OpenAI Platform 顯示「Your authentication token has been invalidated」，請從 Platform 首頁重新登入，然後重新開啟通道設定。僅憑此錯誤無法判斷您的帳戶是否擁有通道存取權。

在OpenAI Platform中建立通道或開啟現有通道的設定。在Organizations中保留擁有該通道的Platform組織，在ChatGPT workspaces中明確選取你目前在ChatGPT中使用的工作區，然後儲存。這是兩個獨立選項，只選取組織並不等於完成工作區關聯。如果Plugins顯示「沒有可用的通道」，請先檢查工作區選取情況，再檢查你的Tunnels Read與Use權限，然後重新開啟清單。建立或編輯需要Read與Manage權限，執行階段金鑰需要Read與Use權限。Bossanova無法代為授予這些權限。

在 Bossanova 的設定 → AI → ChatGPT 連線設定中輸入通道 ID 和執行階段金鑰，然後選擇安裝並連線。請勿在本網頁輸入。金鑰儲存在作業系統安全儲存區，不會回傳給 AI。

僅在 Bossanova 的金鑰輸入欄填寫金鑰，不要傳至 AI 對話或訊息。請使用具有通道使用權限的執行階段金鑰，不要使用組織管理員金鑰。

如需逐次確認請求，請在 ChatGPT 的設定 → 外掛程式 → Bossanova → 權限中選擇「一律詢問」（Always ask）。預設的「允許低風險操作」可能會直接拒絕敏感請求，不顯示核准卡片。OpenAI 安全檢查的攔截不同於 Bossanova 的拒絕；「一律詢問」也不保證所有請求都能執行。遇到安全攔截時，請停止操作並檢查錯誤。請勿嘗試透過反覆建立連線或開啟「允許所有操作」來解決。

開啟ChatGPT的開發者模式，在Plugins中新增連線。在Connection → Tunnel中選取同一個通道。Authentication請選取No Authentication（或None，不需驗證），請勿在此ChatGPT表單中輸入執行階段金鑰。建立連線後，檢查顯示的工具並親自確認授權。然後在新的一般 Chat對話中選取工具。應用程式和網頁版請使用同一帳號。OpenAI通道的存取控制及Bossanova的保險庫與專案授權仍然適用。

連線狀態不代表 ChatGPT 已成功使用工具。請在新對話中要求檢查 Bossanova 狀態。

在設定 → AI → 專案選擇連線與資料夾，按需授權編輯及執行命令。先在練習資料夾列出檔案、稍作修改並執行驗證命令。命令以作業系統使用者權限執行，可存取資料夾外的位置與網路。回傳給 AI 的檔案內容和記錄會傳送至 AI 服務。

請保持電腦與 Bossanova 執行，並解鎖保險庫。鎖定保險庫會停止連線，解鎖後會重新啟動。AI 服務的方案、權限和用量限制仍然適用。

連線不會上傳整個保險庫，也不會授予無限制的電腦存取權。AI 只能看到允許的名稱標籤；使用秘密值需要另外批准。解鎖後會重新啟動已儲存的通道，但專案資料夾權限需要重新批准。

只有明確標記為「非機密」的值才能由 AI 直接讀取。專案指令不會自動取得保險庫中的機密。Bossanova 不會中繼這些工作，也不會代您呼叫模型 API；適用的是您的 AI 服務的權限、用量限制與費用。這並不是無限量的免費 Codex：委派給其他模式或 codex exec 可能會消耗該服務的額度。

同一 Wi-Fi 下的保險庫傳輸與 OpenAI 通道各自獨立，裝置之間直接連線，不經過網際網路中繼。處於睡眠或離線狀態的電腦無法處理 AI 要求。傳回給 AI 的檔案內容、執行記錄和非機密值會送達您選擇的 AI 服務。

「電腦已連線」表示與 OpenAI 通訊正常，「已收到 ChatGPT 請求」表示收到實際請求。管理連線會顯示金鑰是否已儲存，重新整理狀態不會收合該區域。變更連線資訊時，金鑰欄位基於安全考量留空。已儲存的金鑰繼續使用，僅在更換時輸入新金鑰。步驟編號只用於首次連線。

更新後，如果 ChatGPT 工具缺少或資訊仍是舊版，請保持 Bossanova 已解鎖，在 ChatGPT 網頁版依序開啟設定 → 外掛程式 → 管理此 Bossanova 連線 → 管理應用程式 → 頁面底部的「重新整理工具（Refresh tools）」。確認工具清單已更新後，開始新對話。選單名稱可能因帳號或語言而異。Bossanova 的「重新整理狀態」只檢查電腦連線，不會更新 ChatGPT 的工具資訊。兩種重新整理操作都不會授予權限或解除安全檢查封鎖。

登入及連線同意須由您完成。若看不到工具，請重新整理工具清單或開始新對話；舊對話可能保留舊連線。無法保證 OpenAI 權限、可用性或免費額度。WSL 與 Windows 的連線彼此獨立。

• OpenAI: Secure MCP Tunnel
• OpenAI: ChatGPT Plugins
• OpenAI: Chat / Work
• Claude Desktop: MCP
• OpenAI: app permissions

安全邊界與操作檢查

橋接器從 OS 安全儲存區取得認證資料。請勿讓權杖出現在模型引數、工具回應、原始碼儲存庫或記錄中。帳戶與訂閱 API 不會接收金庫明文。供人使用的 GUI 搜尋不是 AI 值搜尋 API。

1. 先使用測試資料檢查連線、核准卡與結果流程。真實秘密不要放入範例程式碼或錯誤報告。
2. 確認鎖定金庫會阻擋要求、撤銷核准會阻止後續使用，以及輸出值的命令其記錄會被隱藏。
3. 伺服器秘密只使用 send 或 proxy、agent 載體；env 與 file 載體只用於嵌入應用程式與建置的值。如果寫入結果不確定，請在重試前檢查目標，以免造成重複。
4. 完成後，在 AI 分頁關閉主機切換鈕，並視需要撤銷核准。關閉切換鈕也會從 Claude 應用程式與 Codex 設定中移除註冊。

OS、Bossanova 程序與已核准的目標都是信任前提。透過 env 或 file 載體傳遞的值可能存在於該程序、其子程序與輸出中，也無法阻止同一部 PC 上其他程序讀取記憶體。若授予 AI 不受限制的管理員、檔案、螢幕或記憶體存取權，就無法保證隱私。「不是秘密」值一旦傳送出去便無法撤回。