diff --git a/docs/guides/usage.md b/docs/guides/usage.md index 9a684e9..6629adc 100644 --- a/docs/guides/usage.md +++ b/docs/guides/usage.md @@ -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`）。 diff --git a/docs/records/2026-09-30-boot-config-followups.md b/docs/records/2026-09-30-boot-config-followups.md new file mode 100644 index 0000000..eed0857 --- /dev/null +++ b/docs/records/2026-09-30-boot-config-followups.md @@ -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 评论区与分支存续期间可直接比对可用实现。 diff --git a/docs/records/2026-09-30-lesson-parallel-session-duplication.md b/docs/records/2026-09-30-lesson-parallel-session-duplication.md new file mode 100644 index 0000000..ccbd04c --- /dev/null +++ b/docs/records/2026-09-30-lesson-parallel-session-duplication.md @@ -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 并将"三查"并入机制；若迁移到平台级每任务独立环境亦可退役检查动作。