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