From ff80d6bbc4b9beedd2f1f1a0178acda07ade5852 Mon Sep 17 00:00:00 2001 From: slhafzjw Date: Tue, 28 Apr 2026 22:13:12 +0800 Subject: [PATCH] docs(config): add config center lifecycle docs and split config reference into dedicated doc --- README.md | 4 +- doc/config/config-reference.md | 281 +++++++++++++++++++++++++++++++++ doc/config/configuration.md | 76 +++++++-- 3 files changed, 347 insertions(+), 14 deletions(-) create mode 100644 doc/config/config-reference.md diff --git a/README.md b/README.md index b202c148..bee69908 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ export PARTNER_DEFAULT_MODEL="your-model-name" } ``` -> 其余详细配置信息参考 [相关文档#配置说明](doc/config/configuration.md) +> 其余详细配置信息参考 [配置项说明](doc/config/config-reference.md) #### 启动 @@ -138,6 +138,7 @@ Partner/ ### 已完成 - [整体架构与运行流](doc/architecture/overview.md) +- [配置中心](doc/config/configuration.md) ### 待完成 @@ -145,7 +146,6 @@ Partner/ - [行动系统](doc/action/action.md) - [记忆存储与组织](doc/memory/memory.md) - [模型提供商](doc/model/providers.md) -- [配置说明](doc/config/configuration.md) --- diff --git a/doc/config/config-reference.md b/doc/config/config-reference.md new file mode 100644 index 00000000..1505142e --- /dev/null +++ b/doc/config/config-reference.md @@ -0,0 +1,281 @@ +# 配置项说明 + +本文介绍 Partner 当前已注册配置文件的路径、字段含义、默认值、是否必须以及示例。 + +配置中心的注册、初始化和热重载机制见 [配置中心](configuration.md)。 + +## 目录 + +Partner 的工作目录由 `PARTNER_HOME` 环境变量决定： + +- 如果设置了 `PARTNER_HOME`，则使用该路径作为工作目录。 +- 如果未设置，则默认使用用户目录下的 `.partner`。 + +配置中心会在工作目录下创建以下目录： + +| 目录 | 含义 | +|--------------|-------------------------------------| +| `config/` | 配置文件目录，`ConfigCenter` 监听该目录。 | +| `workspace/` | 运行时工作区目录。 | +| `state/` | 状态持久化目录。 | +| `resources/` | 外部资源目录，例如外部模块目录 `resources/module`。 | + +所有配置文件路径都相对于 `config/` 目录声明。例如 `runtime.json` 实际对应： + +```text +${PARTNER_HOME}/config/runtime.json +``` + +如果 `PARTNER_HOME` 未设置，则对应： + +```text +~/.partner/config/runtime.json +``` + +## AgentGateway + +| 项目 | 内容 | +|---------|------------------------------| +| 配置文件 | `gateway.json` | +| 注册方 | `AgentGatewayRegistry` | +| 是否必须 | 必须。当前没有默认配置。 | +| 是否支持热重载 | 支持。修改后会重新 reconcile channel。 | + +`gateway.json` 用于声明启用哪些 Gateway channel，以及默认响应通道。当前 Partner-Core 默认注册了 `websocket_channel`。 + +```json +{ + "default_channel": "websocket_channel", + "channels": [ + { + "channel_name": "websocket_channel", + "params": { + "hostname": "127.0.0.1", + "port": "29600", + "heartbeat_interval": "10000" + } + } + ] +} +``` + +字段说明： + +| 字段 | 必填 | 含义 | +|---------------------------|----|--------------------------------------------------------| +| `default_channel` | 是 | 默认响应通道。必须出现在 `channels` 列表中。 | +| `channels` | 是 | 要启用的通道列表，不能为空。 | +| `channels[].channel_name` | 是 | 通道名称，必须对应已经注册的 `AgentGatewayRegistration.channelName`。 | +| `channels[].params` | 否 | 通道参数，按具体 Gateway 解释。 | + +`websocket_channel` 支持的参数： + +| 参数 | 默认值 | 含义 | +|----------------------|-------------|------------------------| +| `hostname` | `127.0.0.1` | WebSocket 服务监听地址。 | +| `port` | `29600` | WebSocket 服务端口，必须大于 0。 | +| `heartbeat_interval` | `10000` | 心跳间隔，单位为毫秒，必须大于 0。 | + +## ModelRuntime + +| 项目 | 内容 | +|---------|--------------------------------------------------------------------------------------------------------| +| 配置文件 | `model.json` | +| 注册方 | `ModelRuntimeRegistry` | +| 是否必须 | 通常必须。若同时提供 `PARTNER_DEFAULT_BASE_URL`、`PARTNER_DEFAULT_API_KEY`、`PARTNER_DEFAULT_MODEL`，可使用环境变量生成默认配置。 | +| 是否支持热重载 | 支持。修改后会重建 provider 映射，失败时回滚到旧配置。 | + +`model.json` 用于声明模型供应商，以及特定模块使用哪个 provider。当前支持的 provider 类型为 `OPENAI_COMPATIBLE`。 + +```json +{ + "providerConfigSet": [ + { + "name": "default", + "type": "OPENAI_COMPATIBLE", + "defaultModel": "gpt-4.1-mini", + "baseUrl": "https://api.example.com/v1", + "apiKey": "example-api-key" + } + ], + "runtimeConfigSet": [ + { + "modelKey": "communication_producer", + "providerName": "default", + "override": { + "model": "gpt-4.1", + "temperature": 0.7, + "topP": 1.0, + "maxTokens": 2048, + "extras": {} + } + } + ] +} +``` + +字段说明： + +| 字段 | 必填 | 含义 | +|------------------------------------|----|--------------------------------------------------------| +| `providerConfigSet` | 是 | 基础 provider 集合。必须包含名为 `default` 的 provider。 | +| `providerConfigSet[].name` | 是 | provider 名称。 | +| `providerConfigSet[].type` | 是 | provider 类型。当前支持 `OPENAI_COMPATIBLE`。 | +| `providerConfigSet[].defaultModel` | 是 | 该 provider 的默认模型。 | +| `providerConfigSet[].baseUrl` | 是 | OpenAI-compatible API base URL。 | +| `providerConfigSet[].apiKey` | 是 | API key。 | +| `runtimeConfigSet` | 是 | 模块级 provider 配置集合。可以为空数组。 | +| `runtimeConfigSet[].modelKey` | 是 | 模块使用的模型 key。实现 `ActivateModel` 的模块通过该 key 解析 provider。 | +| `runtimeConfigSet[].providerName` | 是 | 要 fork 的基础 provider 名称。 | +| `runtimeConfigSet[].override` | 否 | 模块级覆写配置。 | +| `override.model` | 是 | 覆写模型名称。当前结构中该字段不可为空。 | +| `override.temperature` | 否 | 覆写 temperature。 | +| `override.topP` | 否 | 覆写 top_p。 | +| `override.maxTokens` | 否 | 覆写 max_tokens。 | +| `override.extras` | 否 | 额外 provider 参数。 | + +如果某个 `modelKey` 没有出现在 `runtimeConfigSet` 中，则会使用名为 `default` 的基础 provider。 + +## AgentRuntime + +| 项目 | 内容 | +|---------|------------------------------------------------| +| 配置文件 | `runtime.json` | +| 注册方 | `AgentRuntime` | +| 是否必须 | 否。存在默认配置。 | +| 默认配置 | `masked_modules = []`，`debounce_window = 300`。 | +| 是否支持热重载 | 支持。修改后会刷新运行模块分组。 | + +`runtime.json` 用于控制 Running module 的运行时行为。 + +```json +{ + "masked_modules": [], + "debounce_window": 300 +} +``` + +字段说明： + +| 字段 | 必填 | 含义 | +|-------------------|----|-------------------------------------------| +| `masked_modules` | 是 | 运行时屏蔽的模块名集合。被屏蔽模块不会进入 Running module 调度链。 | +| `debounce_window` | 是 | 输入后的等待窗口，单位为毫秒。同一 source 的连续输入会在该窗口内合并。 | + +## LogAdvice + +| 项目 | 内容 | +|---------|-----------------------| +| 配置文件 | `advice_logging.json` | +| 注册方 | `LogAdviceProvider` | +| 是否必须 | 否。存在默认配置。 | +| 默认配置 | `logLevel = NONE`。 | +| 是否支持热重载 | 支持。 | + +`advice_logging.json` 用于控制框架内 `LogAdvice` 的日志详细程度。 + +```json +{ + "logLevel": "NONE" +} +``` + +字段说明： + +| 字段 | 必填 | 可选值 | 含义 | +|------------|----|--------------------------------|----------------------------------------------------------------| +| `logLevel` | 是 | `NONE` / `ABSTRACT` / `DETAIL` | `NONE` 不记录 advice 日志；`ABSTRACT` 记录摘要；`DETAIL` 记录更详细的输入输出或异常信息。 | + +## ExecutionPolicy + +| 项目 | 内容 | +|---------|------------------------------------------------------------| +| 配置文件 | `action/runner_policy.json` | +| 注册方 | `ExecutionPolicyRegistry` | +| 是否必须 | 否。存在默认配置。 | +| 默认配置 | `provider = direct`，`mode = DIRECT`，`net = ENABLE`，继承环境变量。 | +| 是否支持热重载 | 支持。 | + +`runner_policy.json` 用于控制 Action Runner 执行命令时的执行策略。 + +```json +{ + "provider": "direct", + "mode": "DIRECT", + "net": "ENABLE", + "inheritEnv": true, + "env": {}, + "workingDirectory": null, + "readOnlyPaths": [], + "writablePaths": [] +} +``` + +字段说明： + +| 字段 | 必填 | 含义 | +|--------------------|----|--------------------------------------------| +| `provider` | 是 | 执行策略 provider 名称。当前默认 provider 为 `direct`。 | +| `mode` | 是 | 执行模式，可选 `DIRECT` / `SANDBOX`。 | +| `net` | 是 | 网络策略，可选 `ENABLE` / `DISABLE`。 | +| `inheritEnv` | 是 | 是否继承当前进程环境变量。 | +| `env` | 是 | 追加或覆盖的环境变量。 | +| `workingDirectory` | 否 | 命令工作目录。 | +| `readOnlyPaths` | 是 | 只读路径集合，主要供 sandbox 类 provider 使用。 | +| `writablePaths` | 是 | 可写路径集合，主要供 sandbox 类 provider 使用。 | + +当前默认 `direct` provider 主要使用命令、工作目录和环境变量；`mode`、`net`、路径隔离字段是否生效取决于具体 provider 实现。 + +## VectorClient + +| 项目 | 内容 | +|---------|--------------------------------------------------| +| 配置文件 | `vector.json` | +| 注册方 | `VectorClientRegistry` | +| 是否必须 | 否。存在默认配置。 | +| 默认配置 | `enabled = false`，`type = null`。 | +| 是否支持热重载 | 当前 registry 未覆写 `onReload()`，因此运行期修改不会重新启动向量客户端。 | + +`vector.json` 用于控制向量客户端。未启用时，配置可以省略。 + +关闭向量客户端： + +```json +{ + "enabled": false, + "type": null +} +``` + +使用 Ollama 向量服务： + +```json +{ + "enabled": true, + "type": "OLLAMA", + "ollamaEmbeddingUrl": "http://127.0.0.1:11434", + "ollamaEmbeddingModel": "nomic-embed-text" +} +``` + +使用本地 ONNX 模型： + +```json +{ + "enabled": true, + "type": "ONNX", + "tokenizerPath": "/path/to/tokenizer.json", + "embeddingModelPath": "/path/to/model.onnx" +} +``` + +字段说明： + +| 字段 | 必填 | 含义 | +|------------------------|---------------------|-------------------------------| +| `enabled` | 是 | 是否启用向量客户端。为 `false` 时不会启动客户端。 | +| `type` | 启用时必填 | 向量客户端类型，可选 `OLLAMA` / `ONNX`。 | +| `ollamaEmbeddingUrl` | `type = OLLAMA` 时必填 | Ollama 服务地址。 | +| `ollamaEmbeddingModel` | `type = OLLAMA` 时必填 | Ollama embedding 模型名。 | +| `tokenizerPath` | `type = ONNX` 时必填 | tokenizer 文件路径。 | +| `embeddingModelPath` | `type = ONNX` 时必填 | ONNX embedding 模型路径。 | diff --git a/doc/config/configuration.md b/doc/config/configuration.md index 6316f03b..4726a1a0 100644 --- a/doc/config/configuration.md +++ b/doc/config/configuration.md @@ -1,26 +1,78 @@ # 配置中心 -本章主要用于介绍 Partner 可用的配置内容。在 Partner 中，所有配置都通过 ConfigCenter、Configurable、以及配套的 ConfigRegistration 来承担，故大部分都借助文件监听，提供热重载能力。 -> 具体配置详情，参考[配置说明](#配置说明)章节。 +本章主要用于介绍 Partner 配置中心的工作机制。在 Partner 中，所有配置都通过 `ConfigCenter`、`Configurable` 以及配套的 `ConfigRegistration` 承担。配置中心在启动阶段完成配置初始化，并在启动文件监听后为已注册配置提供热重载能力。 + +> 具体配置文件、字段含义和示例，参考 [配置项说明](config-reference.md)。 ## 运行流程 + +`ConfigCenter` 的生效过程分为三个阶段：配置入口注册、启动期初始化、运行期监听与重载。 + +### 配置入口注册 + +`Configurable` 只负责声明自己管理哪些配置文件，以及每个配置文件对应哪个 `ConfigRegistration`。注册阶段不会读取配置文件，也不会触发配置生效。 + ```mermaid - +flowchart TD + A["Configurable.register()"] --> B["ConfigCenter.register(configurable)"] + B --> C["configurable.declare()"] + C --> D["获得 Path -> ConfigRegistration"] + D --> E["归一化配置相对路径"] + E --> F{"路径是否合法且不重复?"} + F -->|否| X["启动失败
AgentStartupException"] + F -->|是| G["保存到 registrations"] + G --> H["等待 ConfigCenter.initAll()"] ``` -> ConfigCenter 生效流程 -## 配置说明 +需要注意，`ConfigCenter.register(configurable)` 只能在监听启动前调用。`ConfigCenter.start()` 之后再注册新的 `Configurable` 会被视为启动期错误。 -### 目录 +### 启动期初始化 -### AgentGateway +启动初始化发生在 `Agent.launch()` 的后半段。此时框架内置和应用传入的 `Configurable` 已完成注册，`ConfigCenter.initAll()` 会遍历所有已注册的 `ConfigRegistration`，按声明的相对路径从配置目录读取 JSON 文件。 -### ModelRuntime +```mermaid +flowchart TD + A["Agent.launch()"] --> B["ConfigCenter.initAll()"] + B --> C["遍历 registrations"] + C --> D["定位配置文件
configDir / relativePath"] + D --> E{"配置文件是否可读取并解析?"} + E -->|是| F["json.toJavaObject(type)"] + F --> G["registration.init(config, json)"] + E -->|否| H{"是否存在 defaultConfig()?"} + H -->|是| I["registration.init(defaultConfig, null)"] + H -->|否| J["收集缺失配置说明
ConfigDoc"] + G --> K["当前配置初始化完成"] + I --> K + J --> L{"是否存在缺失配置?"} + L -->|是| M["启动失败
AgentStartupException"] + L -->|否| K + K --> N{"是否还有未处理 registration?"} + N -->|是| C + N -->|否| O["initAll() 完成"] +``` -### AgentRuntime +读取成功时，JSON 会被转换为对应的 `Config` 类型，并传入 `ConfigRegistration.init(config, json)`。读取失败或文件不存在时，如果 registration 提供了 `defaultConfig()`，则使用默认配置执行初始化；如果没有默认配置，则启动失败，并根据配置类型上的 `ConfigDoc` 输出缺失配置说明。 -### LogAdvice +### 运行期监听与重载 -### ExecutionPolicy +`ConfigCenter.start()` 会在启动初始化完成后启动配置目录监听。运行期监听只处理已经注册过的配置路径，不会为新路径创建 registration。 -### VectorClient +```mermaid +flowchart TD + A["ConfigCenter.start()"] --> B["创建 DirectoryWatchSupport"] + B --> C["监听 configDir"] + C --> D{"文件事件"} + D -->|create / modify| E["reloadIfRegistered(file)"] + D -->|delete| F["跳过 reload"] + D -->|overflow| G["reconcileAll()"] + E --> H["计算相对配置路径"] + H --> I{"路径是否已注册?"} + I -->|否| J["忽略"] + I -->|是| K{"配置文件是否可读取并解析?"} + K -->|是| L["registration.onReload(config, json)"] + K -->|否| M["上报加载失败"] + G --> N["扫描 configDir 下所有 JSON 文件"] + N --> E +``` + +运行时重载发生在 `ConfigCenter.start()` 之后。配置中心会监听配置目录，对创建和修改事件执行 `reloadIfRegistered(file)`。只有已注册路径对应的 JSON 文件会被处理，解析成功后调用 `ConfigRegistration.onReload(config, json)`。删除事件不会触发默认配置回退，当前实现只记录并跳过 reload；监听溢出时会通过 `reconcileAll()` 扫描配置目录中所有 JSON 文件，并对已注册配置重新执行 reload。