【Agent进阶专题】按 Extension ID 装载初始化配置

本篇给 Extension 增加装载时的初始化配置:Extension 工厂用静态 id 表明身份,Kernel 按 id 注入配置,运行时从全局与 Workspace 两层 JSON 文件读取并合并配置。

能力介绍

之前的方案,main.ts 组装 sharedExtensions 和 Product 专属 Extension。插件初始化的时候,初始化参数只能在创建时写死,或者读环境变量(如 DEEPSEEK_API_KEY),数据路径则靠 process.cwd() 推导。

现在引入统一机制:按 Extension ID 装载初始化配置。配置文件放在 LLM_TO_AGENT_HOME 下,分两层——全局 config/extensions.json 和当前 Workspace 的 workspaces/{workspaceId}/config/extensions.json;同 Extension、同字段用 Workspace 覆盖全局。第一版只读:不创建缺失文件、不写默认值、不支持热更新。

实现思路

要让 Kernel 知道”哪份配置给哪个插件”,先得让 Kernel 认得出插件身份。旧实现里 id 在 Extension 实例上,use() 接收已经创建好的实例,配置无从注入。这次把身份提到工厂上:

1
createDeepSeekExtension.id = ExtensionId.DeepSeek;

工厂函数本身携带静态 id。use() 接收工厂,构造实例时按 id 取配置注入。Kernel 不关心配置文件的位置、作用域和合并规则,只负责”按 id 把配置片段传给工厂”。

配置的定位与合并放在 src/config.ts。loadRuntimeConfig() 计算 workspaceId,读取两份 extensions.json,合并后返回。

配置装载

workspaceId 由项目路径稳定推导:

1
2
3
export function workspaceIdFor(projectPath: string): string {
return createHash("sha256").update(resolve(projectPath)).digest("hex").slice(0, 16);
}

loadRuntimeConfig() 定位两个文件:

1
2
3
4
5
6
7
const home = resolve(
options.home ?? process.env.LLM_TO_AGENT_HOME ?? join(homedir(), ".llm-to-agent"),
);
const projectPath = resolve(options.projectPath ?? process.cwd());
const workspaceId = workspaceIdFor(projectPath);
const globalFile = join(home, "config", "extensions.json");
const workspaceFile = join(home, "workspaces", workspaceId, "config", "extensions.json");

Kernel 按 id 注入

use() 签名从”实例列表”改为”工厂列表”:

1
2
3
4
5
6
7
8
9
use(...factories: ExtensionFactory[]): this {
// ...ID 去重、created 状态检查...
const extensions = factories.map((factory) => ({
id: factory.id,
extension: factory({ ...this.#extensionConfigs[factory.id] }),
}));
this.#extensions.push(...extensions);
return this;
}

每个工厂拿到自己 id 对应的配置片段(可能为空对象)。片段怎么解释和校验,由工厂自己负责。

插件读取配置

以 DeepSeek 为例。工厂接收 ExtensionConfig,先做类型校验,再按”环境变量优先、配置兜底”读取:

1
2
3
4
5
6
7
8
const config = options as DeepSeekOptions;
const apiKey = process.env.DEEPSEEK_API_KEY ?? config.apiKey;
const baseUrl = (
process.env.DEEPSEEK_BASE_URL ??
config.baseUrl ??
"https://api.deepseek.com"
).replace(/\/+$/, "");
const model = process.env.DEEPSEEK_MODEL ?? config.model ?? "deepseek-v4-flash";

Workspace 的 home 和 projectPath 不用用户手写。main.ts 在装配时把 Runtime 解析出的值注入:

1
2
3
4
5
6
7
8
9
10
11
const runtimeConfig = await loadRuntimeConfig();
// ...
const extensionConfigs = {
...runtimeConfig.extensions,
[ExtensionId.Workspace]: {
...runtimeConfig.extensions[ExtensionId.Workspace],
home: runtimeConfig.home,
projectPath: runtimeConfig.projectPath,
},
};
const kernel = new Kernel({ extensionConfigs }).use(...factories);

配置机制就位后,一份典型配置长这样:

1
2
3
4
5
6
7
8
9
10
{
"version": 1,
"extensions": {
"models": {
"apiKey": "sk-xxx",
"baseUrl": "https://api.deepseek.com",
"model": "deepseek-v4-flash",
},
}
}

下一篇我们将把模型选择抽出来,做成独立的 Models Extension。