mirror of
https://github.com/slhaf/Partner.git
synced 2026-05-12 08:43:02 +08:00
docs(config): add config center lifecycle docs and split config reference into dedicated doc
This commit is contained in:
@@ -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/architecture/overview.md)
|
||||||
|
- [配置中心](doc/config/configuration.md)
|
||||||
|
|
||||||
### 待完成
|
### 待完成
|
||||||
|
|
||||||
@@ -145,7 +146,6 @@ Partner/
|
|||||||
- [行动系统](doc/action/action.md)
|
- [行动系统](doc/action/action.md)
|
||||||
- [记忆存储与组织](doc/memory/memory.md)
|
- [记忆存储与组织](doc/memory/memory.md)
|
||||||
- [模型提供商](doc/model/providers.md)
|
- [模型提供商](doc/model/providers.md)
|
||||||
- [配置说明](doc/config/configuration.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
281
doc/config/config-reference.md
Normal file
281
doc/config/config-reference.md
Normal file
@@ -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 模型路径。 |
|
||||||
@@ -1,26 +1,78 @@
|
|||||||
# 配置中心
|
# 配置中心
|
||||||
|
|
||||||
本章主要用于介绍 Partner 可用的配置内容。在 Partner 中，所有配置都通过 ConfigCenter、Configurable、以及配套的 ConfigRegistration 来承担，故大部分都借助文件监听，提供热重载能力。
|
本章主要用于介绍 Partner 配置中心的工作机制。在 Partner 中，所有配置都通过 `ConfigCenter`、`Configurable` 以及配套的 `ConfigRegistration` 承担。配置中心在启动阶段完成配置初始化，并在启动文件监听后为已注册配置提供热重载能力。
|
||||||
> 具体配置详情，参考[配置说明](#配置说明)章节。
|
|
||||||
|
> 具体配置文件、字段含义和示例，参考 [配置项说明](config-reference.md)。
|
||||||
|
|
||||||
## 运行流程
|
## 运行流程
|
||||||
|
|
||||||
|
`ConfigCenter` 的生效过程分为三个阶段：配置入口注册、启动期初始化、运行期监听与重载。
|
||||||
|
|
||||||
|
### 配置入口注册
|
||||||
|
|
||||||
|
`Configurable` 只负责声明自己管理哪些配置文件，以及每个配置文件对应哪个 `ConfigRegistration`。注册阶段不会读取配置文件，也不会触发配置生效。
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
A["Configurable.register()"] --> B["ConfigCenter.register(configurable)"]
|
||||||
|
B --> C["configurable.declare()"]
|
||||||
|
C --> D["获得 Path -> ConfigRegistration"]
|
||||||
|
D --> E["归一化配置相对路径"]
|
||||||
|
E --> F{"路径是否合法且不重复?"}
|
||||||
|
F -->|否| X["启动失败<br/>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["定位配置文件<br/>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["收集缺失配置说明<br/>ConfigDoc"]
|
||||||
|
G --> K["当前配置初始化完成"]
|
||||||
|
I --> K
|
||||||
|
J --> L{"是否存在缺失配置?"}
|
||||||
|
L -->|是| M["启动失败<br/>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。
|
||||||
|
|||||||
Reference in New Issue
Block a user