Agent-System-Dev/.task/archive/feature-svc-db-bind.md

feature/svc-db-bind 任务卡

任务主记录：PR #182 https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/182（merge 5a791fd1c3）；状态：已完成（回填）；owner：weichen

基线与授权

• 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 3836ea88e3
• 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-svc-db-bind（worktree）；分支：feature/svc-db-bind
• 授权与交付终点：实现"服务↔数据库绑定"（svc.sh 服务级 db 子命令 + info/list 显示绑定）与 "服务配置文件更新/即时生效"（config 子命令），并修复 adjust_args_for_bin 单横线误判； 终点 = PR 合入 main（用户指示完成后一并合入；附 precheck / task-sync / 测试证据）

目标与非目标

目标：

• 数据库绑定：agent 服务可绑定/切换/解除数据库：svc.sh <name> db [pg名 [--db X] | --clear] [--no-restart]；缺省查看当前绑定与可用实例。绑定 = DSN 写入持久化 exec= + dbref=/<库> 登记，实例运行中缺库自动建，服务运行中自动重启生效；--clear 回内嵌 SQLite 档。
• 配置文件更新：svc.sh <name> config [file.json |--clear] [--no-restart]；缺省查看当前 配置文件（掩码内容 + agent-system config explain -config 视角的生效值）。切换前经二进制 schema 强校验（未知键/非法值拒绝，不把服务重启进坏配置），通过后把 --config <绝对路径> 写入 exec= + conffile= 登记，运行中自动重启即时生效（agent 无 SIGHUP 热重载，重启秒级）； --clear 移除回命令行参数形态。绑定后改文件内容 + restart（或重跑 config 同文件）即生效。
• 显示层全链路：list 表新增 DB 列（含配置文件 dsn 反查）；status 详情新增"数据库""配置 文件"行；info 数据库节新增"绑定服务"反向映射、配置节附配置文件内容快照（敏感值掩码， --reveal 明文）；无 dbref 的旧服务按 exec= --dsn 或配置文件 dsn 的 host:port 反查匹配实例 （外部 DSN 显示 外部@host:port）。
• 修复既有缺陷：adjust_args_for_bin 以 grep '--dsn' 检测旗标支持，Go flag 帮助打印单横线 -dsn，导致现役二进制的 --dsn/--auth 在 deploy 重建参数时被误删——改为"去横线旗标名 + 1-2 横线"匹配。
• record_state 跨重启保留 dbref/conffile；svc_del_key 辅助；db create 尾部提示绑定命令； usage/usage_short/help(lifecycle/config/db)/docs/svc.md（§2/§4.5/§4.6/§6/§10.1）同步。

非目标：不改 agent 二进制与部署/生命周期语义；不做 static/postgres 的绑定；不做运行中热切换 （切换经重启生效）；不做配置文件的编辑器（内容仍由用户维护，svc.sh 负责校验/切换/生效）。

同步记录

节点	sync_base_sha	tested_head_sha	checked_at
启动	3836ea88e3	3836ea88e3	2026-10-04T13:23:33Z

结果与验证

• 结果：已实现（数据库绑定与配置文件更新两块目标全部落地；<name> db/<name> config 服务级动作与顶层 db 命令、--config 旗标并存无冲突）。
• 验证（worktree runtime 实测，真实 agent 二进制 + PostgreSQL 18，2026-10-04）：
  • bash -n 通过；
  • 数据库绑定：t-app db bpg → exec= 写入 --dsn、dbref=bpg/agent、自动重启生效； record_state 重写 svc.env 后 dbref 保留；PG 的 agent 库出现 21 张表（服务真实 落库，非仅配置）；--db t2 切换自动建库（t2 库 21 张表）；--clear 干净回内嵌档； --no-restart 只改登记；错误路径（未登记实例/多余参数/postgres 服务）均 exit 2；
  • 配置文件更新：坏文件（未知键 bogus）被 schema 校验拒绝且不动 exec、不重启；合法文件 绑定后 cmdline 含 --config <abs>、conffile= 跨 record_state 保留；配置文件内的 dsn 真实生效（错误密码版本在日志中报 PG 认证失败=配置确已应用；正确密码版连上 PG、 agent 库 21 张表）；内容修改后重跑 config <同一文件> 再校验并重启（pid 更新）； --clear 移除 --config/conffile 并重启；错误路径（文件不存在/双文件）exit 2；
  • db + config 共存：exec= 同时带 --dsn 与 --config，重启健康；
  • 显示层：list DB 列（含"仅配置文件带 dsn"场景的反查 bpg/agent）、config 查看视图 （JSON 掩码 "dsn": "***" + explain 生效值 dsn 掩码）、status"数据库/配置文件"行、 info 配置节文件内容快照、info 数据库节"绑定服务"；手删 dbref 模拟旧部署 → 反查仍显示；
  • adjust 修复：正例（帮助含 -dsn 判支持）与负例（无 dsn 判不支持）均正确；
  • 回归：db dsn（掩码）/ db ls / info / history（新增 set ok db bind → / config → / config unbind 事件）/ --help 正常；测试现场（t-app/bpg、临时 JSON）已清除；
  • 正式验收（含配置文件更新提交）：make test 于 head ecfed7b exit 0 （boundaries/pins/libs/core/backend/frontend/ui/agentcmd 全过）；另有前次 843495e 全过记录。
  • 正式验收：make test exit 0（test-boundaries/pins/libs/core/backend/frontend/ui/agentcmd 全过）。
• 影响与剩余项：list 表加宽一列；老脚本无兼容性问题（dbref 缺省视为未绑定）； 发现并修复的 adjust_args_for_bin 缺陷影响既有 deploy --dsn/--auth 路径（此前被静默丢弃）。 剩余项无。 | 同步前验收 | 3836ea88e3 | 843495e0d0 | 2026-10-04T13:30:59Z | | 同步前验收 | 3836ea88e3 | dc7a255f31 | 2026-10-04T13:43:45Z |

闭合记录（card-autoclose 回填）

• 依据：merge 5a791fd1c37a40fcec8178e463c3f91b0153ac28（PR #182）已包含于 origin/main，分支成果已落盘；本段为合入后回填。
• 合并主题：Merge pull request 'Add per-service database binding and fix single-dash flag detection in svc.sh' (#182) from feature/svc-db-bind into main
• 归档：随闭合移入 .task/archive/；任务执行期的过程证据见原任务记录与 PR。