From abc1a6d7849cb2e2ab1ec84c230024ca40eaf980 Mon Sep 17 00:00:00 2001 From: weichen Date: Wed, 30 Sep 2026 04:15:03 +0000 Subject: [PATCH] Design the startup configuration surface and instance conventions 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 --- .../2026-09-30-configuration-surface.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/proposals/2026-09-30-configuration-surface.md diff --git a/docs/proposals/2026-09-30-configuration-surface.md b/docs/proposals/2026-09-30-configuration-surface.md new file mode 100644 index 0000000..abd3712 --- /dev/null +++ b/docs/proposals/2026-09-30-configuration-surface.md @@ -0,0 +1,39 @@ +# 配置面设计：来源层级、字段与多实例约定 + +状态：已批准（随实现交付）；主任务：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 | 空（=/artifacts） | AGENT_SYSTEM_ARTIFACTS | PG 档共享工件卷 | +| auth | auto | AGENT_SYSTEM_AUTH | on/off/auto | +| mock | false | AGENT_SYSTEM_MOCK（true/false） | 演示模式 | + +配置文件：`--config ` 显式传入（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` 实际解析。