Record the parallel-duplication lesson, follow-ups, and startup config usage
Why: boot-config 重复交付事故须按 documentation.md 经验闭环沉淀：根因与 检查动作入经验条目、处置与后续项入过程记录；使用指南启动节仍是纯 CLI 旧文案，需反映已上线配置面（PR#4/PR#12）。 Evidence: 经验条目按 lesson 模板（candidate 状态、事故时间线与完整 SHA 回链）；usage §1.3 与已合入实现实测一致（config explain 逐字段来源与 DSN 脱敏、serve --config envs/dev.json 落 data-dev）。 Impact: docs/records/ 新增 lesson-parallel-session-duplication 与 boot-config-followups 两条；docs/guides/usage.md §1.3 重写为四源合并 + 多环境启动说明；无代码影响。 Refs: Agent-System-Backend PR#4（66b4bbf5）与 PR#5（8270acf5，已关闭留 差异清单）；本仓 PR#6（配置面设计）；Agent-System-Dev PR#12（a58f85e）。
This commit is contained in:
+17
-3
@@ -28,16 +28,30 @@ make test # 全量测试
|
||||
make demo # 一键演示（构建 + mock 模式启动）
|
||||
```
|
||||
|
||||
### 1.3 启动
|
||||
### 1.3 启动与配置（配置文件 / 环境变量 / 命令行）
|
||||
|
||||
```bash
|
||||
agent-system serve [--addr 127.0.0.1:8787] [--data ./data] [--plugins ./plugins] [--mock]
|
||||
agent-system serve [--config envs/dev.json] [--addr 127.0.0.1:8787] [--data ./data] [--plugins ./plugins] [--mock]
|
||||
agent-system config explain [--config envs/prod.json] # 只读诊断：逐字段生效值与来源，DSN 脱敏
|
||||
agent-system version
|
||||
```
|
||||
|
||||
- `--data`：SQLite 数据库与工件对象目录（默认 ./data）。
|
||||
启动参数四源合并，优先级从低到高：**内置默认 → 配置文件（`--config`，显式 JSON，无自动发现）→ 环境变量（`AGENT_SYSTEM_ADDR/DATA/PLUGINS/DSN/ARTIFACTS/AUTH/MOCK`）→ 命令行**；未显式传入的命令行参数不参与覆盖，删除 override 恢复继承。字段：`addr`（监听）、`data`（工作区根目录）、`plugins`、`dsn`（空 = 嵌入式 SQLite 档，非空 = PostgreSQL 档）、`artifacts`、`auth`（auto/on/off）、`mock`；未知键与类型错误在启动时定位报错，不静默失效。
|
||||
|
||||
**多环境启动**——仓库自带隔离示例 `envs/{dev,test,prod}.json`（data 根与 DB 互不重叠）：
|
||||
|
||||
```bash
|
||||
agent-system serve --config envs/dev.json # mock 开、./data-dev
|
||||
agent-system serve --config envs/test.json # 127.0.0.1:8788、./data-test
|
||||
agent-system serve --config envs/prod.json # PostgreSQL 档、auth on、独立卷
|
||||
AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve # 环境变量定位文件
|
||||
```
|
||||
|
||||
- `--config`：显式配置文件（平面 JSON，键同上）；单点覆盖仍可用 `--addr`/`--dsn` 等同名参数压过文件。
|
||||
- `--data`：工作区根目录（SQLite 数据库与工件对象目录；默认 ./data）。
|
||||
- `--plugins`：插件目录（声明资产热加载，见 §6）。
|
||||
- `--mock`：演示模式——不调用任何模型，按脚本回放完整交互（首次体验推荐）。
|
||||
- 模型、检索、限流等**运行时设置**在设置页（§2），属业务策略层，不进启动配置文件——设计边界与实例隔离约定见[配置面设计](../proposals/2026-09-30-configuration-surface.md)。
|
||||
|
||||
浏览器打开 `http://127.0.0.1:8787` 即三栏工作台（开发期前端热更新：Dev 仓 `make dev`）。
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# 记录：boot-config 并行重复交付的处置与配置面后续项
|
||||
|
||||
日期：2026-09-30；任务主记录：Agent-System-Backend PR#5（已关闭，评论区留完整差异清单）。
|
||||
|
||||
关联（完整提交，跨仓可追）：
|
||||
|
||||
- 已合入实现：Agent-System-Backend PR#4（66b4bbf55a6cf24b60a6d1d945825b0b44503f5f，main 1e621887097b3ac9524d7a272f03671b15f65d1e）
|
||||
- 已批准设计：本仓 PR#6（abc1a6d7849cb2e2ab1ec84c230024ca40eaf980，[配置面设计](../proposals/2026-09-30-configuration-surface.md)）
|
||||
- 组合钉入：Agent-System-Dev PR#12（a58f85e0d0ade6e8b4da3afe9985985a38bae47a）
|
||||
- 重复候选（已关闭）：Agent-System-Backend PR#5（8270acf5e085be2177cc211ff31dd70891d3b538，分支 feature/boot-config）
|
||||
|
||||
## 处置
|
||||
|
||||
- 重复实现按协作规则"拒绝陈旧候选"处置：Backend PR#5 关闭（差异清单在评论区），Dev 任务 `task-finish --abandon` 回收（原因：与 feature/config-surface 重复交付）。
|
||||
- 重复根因与预防动作见 [2026-09-30-lesson-parallel-session-duplication](2026-09-30-lesson-parallel-session-duplication.md)。
|
||||
- 本记录合入后删除 Backend 远端分支 feature/boot-config（差异要点已沉淀至下节，不再依赖分支存续）。
|
||||
|
||||
## 代码级后续项（小改，待拍板后各自走任务）
|
||||
|
||||
1. **apikey 子命令支持 `--config`**：当前 prod 档管理密钥需手抄 DSN 与 data 目录；与 serve 同管道解析存储档定位即可。
|
||||
2. **`--mock` 粘性残留**：mock（CLI/文件/环境）经 app 组合根 `MergeUser` 写入 user 设置并落库——重启不带参数仍保持 mock；建议改为启动注入（系统层，位于 defaults 与 user 之间），不落库。注意存量库可能已有 user 层 `runtime.mock=true` 残留，迁移时需处理。
|
||||
3. **`GET /api/settings` 不含启动注入层**：API 消费方无法还原 defaults → system → user → project 完整覆盖链；建议附加脱敏 `system` 字段（向后兼容）。
|
||||
|
||||
## 设计级选项（与已批准配置面设计的非目标条目冲突，须先修订设计再实施）
|
||||
|
||||
1. **环境段式单文件 + `--env`**：单个 JSON 承载 dev/test/prod 多段，`--env` 显式选段（当前设计为 envs/ 多文件）。重复候选中已实现并单测验证（含段间 data 目录重叠告警），未采纳。
|
||||
2. **配置文件携带 settings 子树**：模型密钥/检索/限流等经文件下发、注入系统层（不落库、设置页掩码显示，租户层仍可覆盖）。重复候选中已实现并验证（按设置 schema 校验、未知键定位报错），未采纳（设计明确非目标："运行时业务设置……不参与启动合并"）。
|
||||
|
||||
任一选项若采纳：先在 proposals/ 修订配置面设计（含非目标条目与实例隔离约定），再立实施任务；PR#5 评论区与分支存续期间可直接比对可用实现。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 经验：并行会话同一需求重复交付——worktree 只隔离文件现场，不隔离任务认领
|
||||
|
||||
- 状态：candidate（根因已由事故证实；检查动作已定义但未机制化、未在后续任务演练）
|
||||
- 触发条件/检索词：并行会话 / 重复实现 / 同一需求两个 PR / task-start 后上游合入同名功能 / 陈旧候选重复候选 / 检出里看不到刚合入的设计 / submodule 钉住旧版看不到新提案 / 需求去重
|
||||
- 根因与来源：2026-09-30 boot-config 任务，两会话自共同基线（Dev main dca932c，04:09 合入）出发：并行会话 04:15 合入配置面设计（Documents PR#6，abc1a6d7849cb2e2ab1ec84c230024ca40eaf980）、04:19 合入实现（Backend PR#4，66b4bbf55a6cf24b60a6d1d945825b0b44503f5f）、04:27 钉入组合（Dev PR#12，a58f85e0d0ade6e8b4da3afe9985985a38bae47a）；本会话 04:10 task-start（R0=dca932c，precheck 必读清单生成时设计尚不存在），04:25 提交等价实现（Backend PR#5，8270acf5e085be2177cc211ff31dd70891d3b538），判定重复后关闭。两个机制性缺口：① precheck/task-start 是**工作区完整性**门禁（树净/基线/子仓漂移），不做**需求去重**；`.task/` 任务卡提交在各任务自己的分支上，合入前互相不可见。② 父仓 gitlink 纪律使任务 worktree 的 documents 物化在钉住 SHA（2205138），刚合入 documents main 的设计对在途任务不可见，直到父仓钉入（04:27）才出现在检出里。
|
||||
- 下次应做的检查：实施类任务**动手写代码前**三查（合计一分钟内）：① Dev main `.task/` 在途任务卡主题（状态"进行中"）；② documents **origin/main**（fetch 后看，不信检出的钉住版本）`docs/proposals/` 是否有本需求的已批准提案——非目标条目同样有约束力；③ 目标子仓 origin/main 近 1–2 小时的合入主题。命中重叠立即停手向负责人确认分工，不要试图把自己的变体硬合进去。
|
||||
- 验证方法与防护：已落实——本次按协作规则"拒绝陈旧候选"处置（Backend PR#5 关闭并在评论区留差异清单，Dev 任务 task-finish --abandon 回收），处置路径本身正例验证；建议未落实——① task-start 把任务卡推到共享 registry（或建 Gitea issue 认领），precheck 输出在途任务清单；② precheck 增加"碰撞雷达"：fetch 并列出近 N 小时 Dev + 各子仓合入主题与 documents 新提案。
|
||||
- 适用与不适用：适用多会话并行 + 父仓 gitlink 钉版本的多仓组合（本组合 11 仓）；不适用单会话串行开发，也不适用于平台级工作区隔离已上线后的场景。
|
||||
- 尚缺证据/防护：认领登记与碰撞雷达均未机制化（task.sh 未改造，属防护缺口）；"三查"动作尚未在后续真实任务中演练验证有效。
|
||||
- 复核人、日期、版本：weichen，2026-09-30，组合 main a58f85e0d0ade6e8b4da3afe9985985a38bae47a
|
||||
- 替代/退役条件：task-start 认领登记 + precheck 碰撞雷达上线并以正负例验证后，本条目升级 validated 并将"三查"并入机制；若迁移到平台级每任务独立环境亦可退役检查动作。
|
||||
Reference in New Issue
Block a user