> ## 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.