项目配置 (defineConfig)

本页是 SDK 辅助工具的说明。要了解完整的模式定义、合并语义以及仅支持 JSON 的沙箱设计理由，请参阅 MCP / 项目配置。

`defineConfig(config)`

创建一个带类型的 TheoProjectConfig，用于 theo.config.ts。MCP 服务器会自动读取该配置。

// 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 配置：

theo.config.json — 存在时始终会被加载（安全：使用 JSON.parse 解析）。
theo.config.js / theo.config.ts — 默认会被忽略。 加载这些文件会执行当前工作目录中的任意代码，当 IDE 在一个你并不完全信任的项目中启动 MCP 服务器时，这是不安全的。

若要重新启用 JS/TS 配置加载，请在启动 MCP 服务器之前设置一个环境变量：

export THEO_ALLOW_JS_CONFIG=1

设置该标志后，服务器会先加载 theo.config.js，再加载 theo.config.ts，最后才回退到 theo.config.json。如果在未设置该标志的情况下发现了 JS/TS 配置文件，MCP 服务器会记录一条警告日志并跳过该文件。

仅在你自己编写或信任的目录中启用 THEO_ALLOW_JS_CONFIG=1。任何包含恶意 theo.config.js 的仓库，都可能在 MCP 服务器启动时在你的 shell 会话中执行任意代码。

工作原理

当 @hitheo/mcp 服务器启动时，它会：

从环境变量中读取 THEO_API_KEY
加载 theo.config.json（如果已启用，也可加载 JS/TS 配置）
将 persona、skills 和 tools 注入到每一次 MCP 工具调用中
使用 defaultMode 作为回退模式

​defineConfig(config)

​TheoProjectConfig

​文件格式

​工作原理

`defineConfig(config)`

TheoProjectConfig

文件格式

工作原理