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

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 | 空（=<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` 实际解析。