weichen
abc1a6d784
Why: the backend startup layer had only defaults and CLI flags; the configuration standard's baseline (file, env, CLI layers, read-only explain, instance isolation) requires the full pipe for dev/test/prod operation. Evidence: fields and categories mapped one-to-one onto the existing app Options; runtime settings API kept as the separate business-policy layer. Impact: design record only; implementation follows in the backend repo. Refs: standards/configuration.md; backend feature/config-surface
40 lines
2.6 KiB
Markdown
40 lines
2.6 KiB
Markdown
# 配置面设计：来源层级、字段与多实例约定
|
||
|
||
状态：已批准（随实现交付）；主任务：Agent-System-Backend feature/config-surface。
|
||
规范依据：Development-Guidelines standards/configuration.md（单一解析管道/启动依赖/独立实例），本记录是其项目级消费，不复制其正文。
|
||
|
||
## 目标与非目标
|
||
|
||
目标：Agent-System 的**启动层**配置支持 内置默认 → 显式配置文件 → 环境变量 → 显式 CLI 四源合并，并提供只读 `config explain` 诊断；给出 dev/test/prod 实例约定。
|
||
非目标：运行时业务设置（/api/settings 的 user/project scope、profiles 模型路由）——那是配置类别表中的"产品业务策略"层，归授权服务读写，不参与启动合并；两者字段不重叠。
|
||
|
||
## 字段与类别（全部启动部署连接类）
|
||
|
||
| 字段 | 默认 | 环境变量 | 说明 |
|
||
|---|---|---|---|
|
||
| addr | 127.0.0.1:8787 | AGENT_SYSTEM_ADDR | 监听入口 |
|
||
| data | ./data | AGENT_SYSTEM_DATA | 工作区根目录（SQLite+工件默认根） |
|
||
| plugins | ./plugins | AGENT_SYSTEM_PLUGINS | 插件资产目录 |
|
||
| dsn | 空（嵌入式档） | AGENT_SYSTEM_DSN | PostgreSQL 档连接（explain 输出脱敏） |
|
||
| artifacts | 空（=<data>/artifacts） | AGENT_SYSTEM_ARTIFACTS | PG 档共享工件卷 |
|
||
| auth | auto | AGENT_SYSTEM_AUTH | on/off/auto |
|
||
| mock | false | AGENT_SYSTEM_MOCK（true/false） | 演示模式 |
|
||
|
||
配置文件：`--config <path>` 显式传入（JSON，键同上驼峰式）；无自动发现、不从 cwd 猜（configuration.md"路径按明确 config root 解析"）。未知键/类型错误须报出字段名；显式传入而缺失即报错。只有实际传入的 CLI 参数参与覆盖（flag.Visit 判定"显式"）。
|
||
|
||
## dev / test / prod 实例约定（独立实例核对单）
|
||
|
||
| 维度 | dev | test | prod |
|
||
|---|---|---|---|
|
||
| 档位 | 嵌入式 SQLite | 嵌入式 SQLite | PostgreSQL（dsn） |
|
||
| data 根 | ./data-dev | ./data-test | 独立卷 + artifacts 共享卷 |
|
||
| addr | 127.0.0.1:8787 | 127.0.0.1:8788 | 按部署 |
|
||
| mock | true | false | false |
|
||
| auth | auto(=off) | off | on |
|
||
|
||
隔离要求（configuration.md 独立实例）：三环境 data 根/artifacts/DB **不得目录重叠或同库**；实例身份来自 config 文件内容而非目录名/cwd；示例文件 `envs/{dev,test,prod}.json` 随仓提供，prod 示例不含真实 DSN。
|
||
|
||
## 验收
|
||
|
||
internal/config 单测覆盖：四源优先级、未设置 CLI 不覆盖、mock 布尔解析、未知键定位报错、缺文件报错、explain 源标注与 DSN 脱敏；`config explain` 只读（不建 DB、不写业务目录）；三示例文件可被 `--config` 实际解析。
|