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

# 资源

> 你的 IDE 代理可通过 @hitheo/mcp 获取的三个只读 theo:// URI。

在 MCP 中，\*\*资源（resources）\*\*是代理可以拉取以获取上下文、而无需调用工具的只读 URI。`@hitheo/mcp` 暴露了三个：

| URI | Mime 类型 | 描述 |
| - | - | - |
| [`theo://models`](#theo-models) | `application/json` | 可用的 Theo 模型及其路由配置 |
| [`theo://skills/installed`](#theo-skills-installed) | `application/json` | 当前 API 密钥上已启用的技能 |
| [`theo://health`](#theo-health) | `application/json` | 实时的服务商/引擎健康状况与版本信息 |

这三者都直接从 API 实时派生 —— 没有缓存，也没有转换。MCP 服务器只是以 `application/json` 的形式原样转发它们。如果底层调用失败，该资源会返回一个 `text/plain` 正文，格式为 `Error reading <uri>: <message>`，这样代理仍然能拿到有用的信息。

<Note>
  资源是一条**只读的上下文通道**。它们不会改变状态 —— 代理可以在需要获取背景信息时随时拉取，既不占用一次工具调用轮次，也不会消耗额外的令牌。（读取资源仍然会触发底层 API 调用，但不会发生任何 AI 推理。）
</Note>

## `theo://models`

返回你的账户可以路由到的模型数组，结构与 `GET /api/v1/models` 相同。

**使用场景：** 在要求 Theo 使用某个特定模型之前，或当代理想向用户说明*是哪个*引擎处理了这次请求时。

```json theme={null}
[
  {
    "mode": "auto",
    "model_id": "theo-1-flash",
    "label": "Theo Flash",
    "engine": "theo-core",
    "description": "Fast general-purpose model"
  },
  {
    "mode": "code",
    "model_id": "theo-1-code",
    "label": "Theo Code",
    "engine": "theo-core",
    "description": "Long-form code generation"
  }
]
```

由 [`theo.models()`](/sdk-reference/client) → [`GET /api/v1/models`](/api-reference/models/list) 提供支持。

## `theo://skills/installed`

返回当前 MCP 服务器所使用的 API 密钥上已安装的技能列表。结构与带 `filter="installed"` 参数的 `theo_skill_list` 相同。

**使用场景：** 在代理建议安装某个技能之前（这样就不会推荐用户已经拥有的技能），或在调用带 `skills` 数组的 `theo_complete` 之前（用于校验 slug）。

```json theme={null}
[
  {
    "id": "skill_a1b2c3",
    "slug": "deep-research",
    "name": "Deep Research",
    "description": "Multi-step research with citations",
    "version": "1.4.0"
  }
]
```

由 [`theo.skills("installed")`](/sdk-reference/skills) → [`GET /api/v1/skills?filter=installed`](/api-reference/skills/list) 提供支持。

## `theo://health`

实时系统健康状况 —— 引擎可用性、延迟、基础设施状态以及 API 版本。与 `GET /api/v1/health`（唯一一个无需鉴权的公开端点）完全一致。

**使用场景：** 在一个长任务开始时，或当某个工具开始返回错误、代理想要区分"Theo 挂了"和"我的提示词写得不对"时。

```json theme={null}
{
  "status": "healthy",
  "version": "2026-03-28",
  "providers": {
    "theo-core": { "status": "healthy", "latencyMs": 42 },
    "theo-vision": { "status": "healthy", "latencyMs": 88 },
    "theo-search": { "status": "healthy", "latencyMs": 130 }
  },
  "infrastructure": {
    "database": { "status": "healthy", "latencyMs": 3 },
    "redis": { "status": "healthy", "latencyMs": 1 }
  }
}
```

由 [`theo.health()`](/sdk-reference/client) → [`GET /api/v1/health`](/api-reference/health/check) 提供支持。

## 错误响应

如果底层 API 调用失败（网络中断、密钥过期等），该资源会返回：

```text theme={null}
Error reading theo://models: <fetch error>
```

并以 `mimeType: "text/plain"` 代替 JSON。代理可以选择重试，或回退到对应的工具（例如用 `theo_status` 代替 `theo://health`）。

## IDE 代理如何使用这些资源

一个典型的 Theo 感知代理提示循环：

1. 启动时，拉取 `theo://health` 以确认引擎已就绪。
2. 拉取 `theo://skills/installed`，了解已经加载了哪些领域知识。
3. 可选地拉取 `theo://models`，以获知可以请求使用的引擎名称。
4. 然后开始调用工具（`theo_complete`、`theo_code` 等）进行实际工作。

你可以把这个循环写入 `.theo/RULES.md`（由 `theo init` 生成），这样工作区里的每个代理都会遵循它。


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