> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 安全性

> @hitheo/mcp 的威脅模型——哪些代碼在哪裏運行、純 JSON 沙箱如何保護你，以及如何驗證供應鏈。

`@hitheo/mcp` 有意設計成一個體量小、行為可預測的軟件。本頁將準確說明它做什麼、不做什麼，以及你還可以採取哪些措施來進一步加固安裝。

## 服務器運行在哪裏

| 屬性 | 值 |
| - | - |
| 進程所有者 | 啓動該 IDE 的同一用戶 |
| 傳輸方式 | Stdio（沒有入站網絡端口） |
| 出站流量 | 僅 HTTPS，目標為 `https://www.hitheo.ai` |
| 生命週期 | 按工作區劃分；由 IDE 負責啓動和終止 |
| 持久化狀態 | 無——服務器在多次運行之間是無狀態的 |

該服務器是以你本地用戶身份運行的 Node.js 進程。它沒有守護進程，沒有共享套接字,也沒有跨 IDE 的協調機制。你關閉工作區時,該進程就會退出。

由於傳輸方式是 stdio 而非 HTTP，**網絡上的任何東西都無法與它通信**。唯一能夠調用工具的實體,是作為其父進程、生成了該子進程的那個 IDE 進程。在出站方向上，它使用與任何 SDK 或 curl 調用相同的 TLS 1.2+ 協議訪問同一個 Theo API。

## API 密鑰保存在哪裏

```text theme={null}
shell 環境 → IDE 進程 → @hitheo/mcp 子進程 → 出站 HTTPS
```

密鑰的流轉過程：

1. 你在 shell 中導出 `THEO_API_KEY`（或為 GUI 應用啓動持久化保存它）。
2. IDE 讀取該值，並在生成 `@hitheo/mcp` 子進程時將其作為環境變量傳遞過去。
3. 服務器在啓動時讀取一次該值，並將其保存在進程內存中。
4. 每一次出站調用都會簽名 `Authorization: Bearer theo_sk_...`。
5. IDE 的智能體本身**永遠看不到該密鑰**——它只能看到工具的輸出結果。

這意味着：

* `@hitheo/mcp` 從不會把密鑰寫入磁盤。（你的 shell 配置文件或可選的 `~/.theo/credentials` 文件可能會持久化保存它，但那些是 CLI 產生的文件，與 MCP 無關。）
* 該密鑰不會傳輸給 IDE 廠商、模型提供方或任何第三方。它是直接發送到 `api.hitheo.ai` 的。
* 該密鑰不會被嵌入到智能體可以讀取的工具描述、schema 或資源內容中。

如果你不慎將密鑰泄露到了聊天記錄中，請[立即將其輪換](/security/authentication#key-rotation)。

## 純 JSON 配置沙箱

`@hitheo/mcp` 在啓動時會從當前工作目錄讀取 `theo.config.json`。它默認**不會**讀取 `theo.config.js` 或 `theo.config.ts`。

這樣設計的原因在於威脅模型：IDE 會在你打開的任何項目內部隨意啓動 MCP 服務器，其中包括你從互聯網上克隆下來的項目。如果自動加載 JS/TS 配置，那麼一個惡意的 `theo.config.js` 就可能在工作區打開的瞬間通過 `import()` 執行任意代碼——在你還沒讀過一行文件內容之前，就已經以你的用戶身份實現了完整的任意代碼執行。

JSON 配置涵蓋了所有文檔中記錄的用例（`persona`、`skills`、`defaultMode`、`tools`、`temperature`、`metadata`），且不存在上述風險。

如果你確實需要在一個你信任的目錄中使用 JS/TS 配置：

```bash theme={null}
export THEO_ALLOW_JS_CONFIG=1
```

此後服務器會先加載 `theo.config.js`，再加載 `theo.config.ts`，並保留同樣的 JSON 回退機制。

<Warning>
  只應在你自己編寫或信任的目錄中設置 `THEO_ALLOW_JS_CONFIG=1`。請把它當作 `--allow-scripts` 那樣對待——這是一個按項目單獨打開的開關,而不是全局開關。
</Warning>

## 供應鏈

從版本 `0.1.4` 起，npm 上每一個官方的 `@hitheo/*` 壓縮包——包括 `@hitheo/mcp`——都附帶[簽名的 npm 來源證明（provenance）](/security/authentication#supply-chain-verifying-npm-packages)。每一份認證都會將該壓縮包關聯回生成它的具體公開 CI 工作流和 git commit。

在安裝或鎖定新版本之前先進行驗證：

```bash theme={null}
npm audit signatures @hitheo/mcp
```

你也可以查看某個特定發行版的認證 URL：

```bash theme={null}
npm view @hitheo/mcp@latest dist.attestations
```

如果某個官方 Theo 軟件包的認證檢查未通過，**請不要安裝它**。請將該問題報告給 `security@opencharts.com`（參見[披露政策](/security/disclosure-policy)）。

## 鎖定一個已知可用的版本

`npx -y @hitheo/mcp` 會在每次安裝時解析最新發布的版本。如果你想在 CI 或共享的開發環境中鎖定某個特定版本，請在你的 IDE 配置中固定它：

```json theme={null}
"args": ["-y", "@hitheo/mcp@0.3.0"]
```

這樣可以讓升級變成一個明確的動作。重新運行 `theo init`（或手動編輯配置）即可切換到新版本。

## 智能體能做什麼、不能做什麼

IDE 智能體所能看到的**全部**接口，就是那 8 個[工具](/mcp/tools)和 3 個[資源](/mcp/resources)。該 MCP 服務器不會暴露：

* 你的文件系統
* 你的 shell
* 你本地的進程或環境變量
* 除已記錄的 HTTP 端點之外的任何 Theo 內部實現

智能體最終在本地執行的任何代碼（`theo_code` 返回的是代碼本身，而不是一個運行時）都是由*IDE*自行提供執行能力的。是否執行由你以及 IDE 自身的權限模型決定——`@hitheo/mcp` 本身相對於你的機器而言是隻讀的。

## 密鑰輪換、作用域與撤銷

`@hitheo/mcp` 完全繼承了[身份驗證](/security/authentication)文檔中記錄的密鑰模型：

* **靜態哈希存儲**——Theo 只保存 `theo_sk_*` 密鑰的 SHA-256 哈希值。
* **作用域權限**——每個密鑰都可以被限制到特定的能力範圍（補全、技能、工具、連接器、賬單）。沒有 `completions` 作用域的密鑰無法運行 `theo_complete`；該工具會向智能體返回 `403 missing_scope` 錯誤。
* **按密鑰限流**——限流是按密鑰生效的，因此一個失控的 IDE 智能體不會拖垮你其他的集成。
* **即時撤銷**——在[控制台](https://api.hitheo.ai/dashboard/api-keys)撤銷密鑰後，MCP 服務器會在幾秒鐘內停止工作（下一次調用會返回 `401 key_revoked`）。

輪換密鑰時：

1. 在控制台中創建新密鑰。
2. 更新 IDE 啓動所在的環境變量 / shell 配置。
3. 重啓 IDE。
4. 在同一個 shell 中通過 `theo verify` 進行確認。
5. 撤銷舊密鑰。

輪換過程中的寬限期意味着，在第 1 步到第 5 步之間，IDE 不會出現任何停機。

## 報告安全漏洞

在 `@hitheo/mcp` 或相關基礎設施中發現了安全問題？請參閱[披露政策](/security/disclosure-policy)。請發送郵件至 `security@opencharts.com`，而不要提交公開的 GitHub issue。

## 相關內容

* **[身份驗證](/security/authentication)**——完整的密鑰模型、作用域、輪換機制。
* **[數據隱私](/security/data-privacy)**——Theo 如何處理你的提示詞和生成內容。
* **[披露政策](/security/disclosure-policy)**——如何報告漏洞。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.