Agent-System-Documents/docs/guides/team-storage.md

团队存储运行手册（协作存储 U1）

适用范围：协作存储与分布式方案 U1/U2 （已批准，2026-10-11）落地后的 team 部署档 运维与验证。个人 local 档（SQLite） 用法不变，见 usage。本文是 U1 的固定部署清单、配置合同、迁移映射、 容量合同、隔离测试方案与 KTD14 副本保护合同的单一事实源；实施状态以各任务卡为准。

1. 目标实例与固定部署清单

项	值	说明
部署形态	svc.sh 管理的 runtime/<name> 实例	非容器；单机多实例按名隔离
当前团队候选	runtime/dev（8788，SQLite）→ 目标切 team 档 PG	切换窗口与回退按方案 §6，须另行授权
数据库（本机验证）	PostgreSQL 18.6 + pgvector 0.8.7（brew）	本机验证用；正式实例待指定
数据库（CI 门禁）	Ubuntu 24.04 apt：postgresql 16 + postgresql-16-pgvector	版本以 CI job 输出为准
缓存/限流	Redis 8.10.2（本机）；CI apt redis-server	只存可重建状态（KTD10）
应用制品	agent-system 单二进制（make build）	拷贝即运行；team 档需 --tier team

未知项（正式实例主机、pgvector 正式启用版本、对象存储选型）在正式切换授权前 必须补齐；本清单不把本机验证环境当作正式部署事实。

2. team 档配置合同（U2 已实施）

启动语义（KTD1 fail-closed）：

• tier=team：必须配置 dsn 且认证开启（auth=on；auth=auto 随 DSN 自动开）； 任一缺失拒绝启动。PG 打开失败拒绝就绪，绝不回落 SQLite。未配置执行隔离 （disableExecTools 或 execBackend）时启动警告（多用户开放前必须补齐）。
• tier=local：SQLite；配置 dsn 是配置错误，拒绝启动。
• tier 缺省（auto）：现状语义——dsn 非空走 PG，否则 SQLite。

配置键（四源合并：默认 → 文件 → 环境 → 显式 CLI，与 usage §启动一致）：

键	env	CLI	语义（team 档）
tier	AGENT_SYSTEM_TIER	--tier	local / team / 空=auto
dsn	AGENT_SYSTEM_DSN	--dsn	PG 连接串；team 必填
auth	AGENT_SYSTEM_AUTH	--auth	team 档要求最终为 on
instance	AGENT_SYSTEM_INSTANCE	--instance	空=主机名:监听地址（多实例必须互异）
pgMaxOpen	AGENT_SYSTEM_PG_MAX_OPEN	--pg-max-open	每进程最大连接（默认 16）
pgMaxIdle	AGENT_SYSTEM_PG_MAX_IDLE	--pg-max-idle	每进程空闲连接（默认 8）
pgConnMaxIdleSec	AGENT_SYSTEM_PG_CONN_MAX_IDLE_SEC	--pg-conn-max-idle-sec	空闲回收（默认 300s）
pgConnMaxLifetimeSec	AGENT_SYSTEM_PG_CONN_MAX_LIFETIME_SEC	--pg-conn-max-lifetime-sec	连接寿命（默认不限）
pgQueryTimeoutSec	AGENT_SYSTEM_PG_QUERY_TIMEOUT_SEC	--pg-query-timeout-sec	statement_timeout 秒（默认不限）

连接预算（KTD12）：预算覆盖全部 API/Worker/LISTEN/migrator/监控连接； 100 在线用户 ≠ 100 连接。agent-system config explain 输出脱敏有效值 （DSN 密码打码）。启动日志打印 storage tier: team (dialect=postgres pool=… schema=v…)。

迁移（KTD8，U2 已实施）：DDL 与版本登记同事务（中途失败整体回滚，不存在 「表已建、账本未记」中间态）；PG 并发迁移者按会话咨询锁串行化；SQLite 写事务 _txlock=immediate 跨进程排队。库内出现比二进制新的 schema 版本时拒绝启动。

3. 迁移映射（SQLite → PG，U4 工具消费）

SQLite 侧	PG 侧	备注
agent-system.db（WAL）	同名逻辑库	活跃 WAL 不能只拷 .db；一致性备份用 VACUUM INTO
INTEGER 0/1 布尔列	BOOLEAN	v9/v10/v11 起双方言已分型
INTEGER PRIMARY KEY AUTOINCREMENT	BIGSERIAL/SERIAL	events、command_audit、audit_events
FTS5 虚表 + 触发器	tsvector 生成列 + pg_trgm GIN	v4；中文子串走 trigram
vec BLOB	BYTEA	pgvector 类型切换在 U6，不在本映射
<data>/artifacts/ 工件对象	本期仍本地目录 + PG 清单	共享对象存储在 U5/U9

RDM 独立业务库与旧 Agent-System 治理库不在本映射内；迁移工具（U4）只处理 Backend 库，非空目标拒绝、同快照才可续传。

4. 容量合同（验收目标，非性能结论）

方案 §3 的量化指标（100 在线 / 300 SSE / 20 执行中 Agent / P95≤300ms 等）是 待验证合同。区分两个计数：接纳的 run 数（进入队列）与执行许可 （同时真正执行，含子代理、初始全局 20、每用户 2、索引 4）；等待子代理/HITL 的 父 run 让出执行许可、保留会话所有权。压测在 U7 执行并绑定组件 SHA 出证。

5. 隔离测试库/目录/端口方案

资源	约定	生命周期
本机 PG 实例	scripts/svc.sh db create collabtest --port 8897 --tag test	svc.sh 管理；用毕 svc.sh collabtest stop + rm --purge
测试库/扩展	库 agent_test；pg_trgm 预装 public	测试辅助幂等预装；CI 启动步显式预装
用例 schema	t_* / pgbus_* 前缀，随机名	每用例建、Cleanup 级联删
本机 Redis	redis-server --port 6399 --save '' --appendonly no	纯内存、用毕即停
CI	job test-pg：apt 安装 PG16+pgvector+Redis，端口 5432/6399	每次 PR 必跑；缺服务失败不跳过

本地跑真实库门禁：

export AGENT_PG_TEST_DSN="$(scripts/svc.sh db dsn collabtest --db agent_test --reveal | tail -1)"
export AGENT_REDIS_TEST_ADDR=127.0.0.1:6399
make test-backend-pg

禁止对共享/现役实例（如 runtime/dev 的库）跑测试；DSN 不入命令历史与任务卡。

6. KTD14 副本保护与保留合同

• 备份/导出/WAL/测试副本使用专用数据库角色（非应用角色），存放于受限目录 （0700，非工作区）；传输与静态备份加密，解密材料存独立受管秘密存储。
• 保留期限：迁移演练副本用毕即删，最长 7 天；正式备份保留 30 天滚动 + 每月 1 份年度副本（待正式实例指定后确认）。
• 日志/报告只留统计与哈希：不落 DSN、密钥、文档正文；测试一律用脱敏数据。
• 恢复演练：每次演练恢复到新目标并核对应用可用与权限/文件完整性； 「备份命令成功」不等于可恢复。
• 阻塞项：正式导出前，未知 owner 的数据、未定位的权威文件、缺失的保留期限 任一存在即阻塞（不静默继续）。

7. 暂态 Worker 文件分类

类	内容	处置
可重建	构建产物 bin/、node_modules/、测试数据目录、__pycache__	随时删除重建
必须迁移	SQLite 库、artifacts/ 工件、.agentx/checkpoints.jsonl、Squad FileStore/续跑标记	U4 迁移 + 联合备份；U5 前禁止跨机接管
只读参考	svc.env（600）、history.jsonl	保留在实例目录，不入副本外流

8. 已知边界（诚实清单）

• CLI 子命令（apikey/user 等）不校验 tier；team 档语义只在 serve 入口强制。
• 迁移仍随启动执行（已原子 + 锁化）；完全独立的 migrator 入口留待 U4 工具。
• 多实例安全未因此声明（R4/U5）；本档只交付单实例 team 档与真库门禁。
• pgvector 扩展已安装 ≠ 启用；向量检索仍是应用内扫描（U6）。

9. 执行预算与动作授权（U3 切片 2 已实施）

执行许可（admission，R8）

• 设置键：runtime.execBudgetGlobal（全局并发执行上限，含子代理；0=不限， 默认）、runtime.execBudgetPerUser（每租户上限；0=不限）、 runtime.execQueueMax（待执行队列上限，默认 200）。数值为容量合同初值， U7 压测后调整。
• 语义：会话回合与子代理同池计数；账本在数据库（admission_leases，PG 咨询 锁下原子清点），多实例天然共享；队列满时 API 在落库前 429（不写数据）； 父 run 同步等待子代理或等待 HITL 时让出执行许可、保留会话所有权，恢复 执行重新获取——额度占尽时父子不互等。
• 接纳与执行分别计数：队列深度（接纳）与活跃租约（执行）是两个量， 诊断分别看 Manager.QueueDepth() 与 store.ActiveExecutionSlots()。

KTD13 动作授权矩阵与公开契约兼容计划

矩阵（宿主侧 server.ProjectAction）：

动作	语义	未注册 action-aware 时
read	读取项目资源（会话/消息/检索/下载）	回落旧 EXT-8 只读适配器（兼容现网）
edit	写入与修改	默认拒绝
approve	审批（HITL/命令确认）	默认拒绝
execute	触发执行	默认拒绝
admin	管理	默认拒绝

规则：action-aware 适配器（组合根注入 SetProjectActionAuthorizer）注册后 对全部动作权威、出错 fail-closed；旧只读适配器不得自动获得写入能力。

公开契约兼容计划（后续版本落地）：以版本化扩展把动作级判定并入 EXT-8 的 ProjectAuthz 公开契约（新增 action 参数的变体接口 + 契约版本号）， 下游适配器按动作逐一声明能力；未声明动作保持默认拒绝，与宿主侧矩阵同语义。 旧 bool 契约在该版本内继续可用（映射为仅 read）；Core/Host 与下游适配器 （RDM 的 ProjectAuthz 实现）一起验收，不另建成员权威。

10. SQLite → PostgreSQL 切换与恢复演练（U4 已实施）

工具：make build 产出 bin/storage-migrate（受管迁移入口；只处理 Backend 库， 不执行 SQLite dump 作为 PG SQL）。三个子命令：

# 1) 只读盘点：schema 版本、完整性、逐表计数、工件清单与哈希（§6.1）
storage-migrate inventory  --source runtime/dev/data/agent-system.db \
                           --artifacts runtime/dev/data/artifacts --out inv.json

# 2) 一致性快照：VACUUM INTO（在线安全含 WAL）+ 可打开校验 + 逐表计数对账（§6.2）
storage-migrate backup     --source runtime/dev/data/agent-system.db --out snap.db

# 3) 受管迁移：目标建 schema/扩展后按行复制；身份登记 + 逐表校验和 + 终验（§6.3）
storage-migrate migrate    --source snap.db --target "$DSN" \
                           --migration-id <名> --artifacts runtime/dev/data/artifacts --out report.json

迁移身份与续传：migration_id + source_snapshot_id（快照 SHA-256）+ source_schema_version 登记在目标 migration_control；仅同一冻结快照可续传 （换快照/换身份均拒绝）；目标业务表已有数据而身份为空即拒绝（不覆盖）。

校验与报告：逐表源/目标计数与主键序哈希链校验和（布尔列按目标 schema 对称 归一）；复制后推进 SERIAL 序列；未知 owner（users 之外，''/'local' 单租户默认 除外）阻塞迁移；报告只含计数/校验和/清单哈希——无 DSN、密钥与行正文（KTD14）。 类型映射以目标 schema 为准（SQLite 0/1→BOOLEAN、BLOB→BYTEA、生成列不迁、 FTS5 影子表不迁——PG 侧生成列与索引自动重建）；admission_leases 为运行态 不随迁。

切换顺序（正式窗口须另行授权；当前仅隔离演练已验证）

1. 固定源制品与路径，inventory 盘点；指定迁移 owner、窗口、回退判据。
2. backup 冻结快照（活跃 WAL 库不得只拷 .db 文件）。
3. 预演：独立测试目标 PG 上 migrate，核对报告全绿；预演库不作为正式目标。
4. 正式窗口：停新写 → 等待/收口在途 run（未知副作用记 recovery hold）→ 停旧写者 → 终快照 → 空正式目标 migrate → 报告全绿。
5. 单入口切 team 档冒烟（登录/项目/会话/审批/检索/下载）；fail-closed 不回 SQLite。
6. PG 接受新写入前可撤回；之后禁直切回旧 SQLite（向前修复或专项回迁）。

备份基线（正式目标启用后）：pg_dump 逻辑备份 + pg_basebackup 物理基础备份与 WAL 归档/PITR；pg_dump 不能作 WAL 回放基础。每次演练恢复到新目标并核对。