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

# 項目配置 (defineConfig)

> 為項目配置 Theo，使用帶類型的設置項。

<Note>
  本頁是 SDK 輔助工具的說明。要了解完整的模式定義、合併語義以及僅支持 JSON 的沙箱設計理由，請參閱 [MCP / 項目配置](/mcp/project-config)。
</Note>

## `defineConfig(config)`

創建一個帶類型的 `TheoProjectConfig`，用於 `theo.config.ts`。MCP 服務器會自動讀取該配置。

```typescript theme={null}
// theo.config.ts
import { defineConfig } from "@hitheo/sdk";

export default defineConfig({
  persona: "You are Nova, an operations assistant for WarehouseOS.",
  skills: ["inventory-check", "data-extraction"],
  defaultMode: "auto",
  tools: [
    {
      name: "check_stock",
      description: "Look up current stock levels for a SKU",
      input_schema: {
        type: "object",
        properties: { sku: { type: "string" } },
        required: ["sku"],
      },
    },
  ],
  temperature: 0.7,
  metadata: { team: "warehouse-ops" },
});
```

## TheoProjectConfig

| 字段 | 類型 | 說明 |
| - | - | - |
| `persona` | `string` | 用於每次補全請求的自定義系統提示詞 |
| `skills` | `string[]` | 每次請求都會激活的技能 slug |
| `defaultMode` | `ChatMode` | 默認執行模式 |
| `tools` | `ToolDef[]` | 內聯工具定義 |
| `temperature` | `number` | 默認温度 |
| `metadata` | `Record<string, unknown>` | 附加到每個請求上的元數據 |

## 文件格式

MCP 服務器默認優先使用 **JSON** 配置：

1. `theo.config.json` — 存在時始終會被加載（安全：使用 `JSON.parse` 解析）。
2. `theo.config.js` / `theo.config.ts` — **默認會被忽略。** 加載這些文件會執行當前工作目錄中的任意代碼，當 IDE 在一個你並不完全信任的項目中啓動 MCP 服務器時，這是不安全的。

若要重新啓用 JS/TS 配置加載，請在啓動 MCP 服務器之前設置一個環境變量：

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

設置該標誌後，服務器會先加載 `theo.config.js`，再加載 `theo.config.ts`，最後才回退到 `theo.config.json`。如果在未設置該標誌的情況下發現了 JS/TS 配置文件，MCP 服務器會記錄一條警告日誌並跳過該文件。

<Warning>
  僅在你自己編寫或信任的目錄中啓用 `THEO_ALLOW_JS_CONFIG=1`。任何包含惡意 `theo.config.js` 的倉庫，都可能在 MCP 服務器啓動時在你的 shell 會話中執行任意代碼。
</Warning>

## 工作原理

當 `@hitheo/mcp` 服務器啓動時，它會：

1. 從環境變量中讀取 `THEO_API_KEY`
2. 加載 `theo.config.json`（如果已啓用，也可加載 JS/TS 配置）
3. 將 `persona`、`skills` 和 `tools` 注入到每一次 MCP 工具調用中
4. 使用 `defaultMode` 作為回退模式


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