Agent-System-Documents/docs/records/2026-09-30-dual-tier-implementation.md

实施记录：双档存储、多租户与规模化（2026-09-30）

按提案 D17–D24 完成四阶段实施。 验证证据见测试报告。

阶段记录

阶段	内容	关键提交
阶段 0：地基	Core 契约 owner 字段（Project/Conversation/Run/Artifact/KnowledgeDoc/AgentProfile + TS 镜像）；store 重构：dialect 方言收敛、版本化双方言迁移 v1–v5（基线→租户列/唯一约束/事件重建/设置重建→认证表→PG 全文→向量表）、INSERT OR REPLACE 全量改 ON CONFLICT、消息 seq 单语句分配+唯一约束重试、设置合并事务化（PG 咨询锁）、HITL 原子 resolve、工件临时文件+rename 且删除联动清索引、VACUUM INTO 备份接口与 POST /api/admin/backup；runmgr：单会话单 run 强制（409）、事件批处理器（150ms/64 条；立即事件先冲缓冲保序；停机冲净）；server：owner 管道、SSE 越权 404、/api/* 未匹配 404 不回落 SPA	Core 6f9e1a8/03ba8dd；Backend 00a0453
阶段 1：认证与 PG 档	users/api_keys 表与存储方法（SHA-256 摘要、撤销、last_used）；认证中间件（Bearer/?key=、auto/on/off）；apikey create/list/revoke 子命令；前端登录门 + 凭证感知 API/SSE 客户端；PG 方言：pgx 连接池、tsvector 生成列 + pg_trgm GIN（中文子串）、websearch_to_tsquery 混合检索、会话咨询锁；设置/密钥按租户隔离（scope PK=(owner,scope)）	Backend 00a0453；Frontend 6395cc9
阶段 2：向量 RAG	Core retrieval 契约（Chunker/EmbeddingProvider/VectorIndex/Reranker/Retriever/DocumentIndexer）；rag 包：段落感知分块（800/120）、OpenAI 兼容 /embeddings 与 /rerank 客户端（失败降级不阻断）、RRF 融合（k=60）、知识 ID 回写关联向量；store：knowledge_vectors（双方言 BLOB/BYTEA）+ 余弦扫描（租户+维度过滤）；upload/工件统一走索引入口；设置路由复用既有 embedding/rerank 类别	Core 019617e；Backend b3fbf1f
阶段 3：多实例地基	blobstore 抽象（本地目录档，原子 Put/覆写/删除；store 工件方法只依赖接口）；pgbus：NOTIFY agent_events（载荷 `会话	末seq）+ 每实例 LISTEN 按 seq 取回转发本地 bus；租户限流固定窗口中间件（进程内默认；runtime.redisAddr切原生 Redis 共享档，429）；设置新增runtime.rateLimitPerMin/runtime.redisAddr`；多实例契约=会话亲和路由（提案 D24）

偏差与说明

• 事件 seq 由全局自增改为会话内连续（v2 重建，按会话分区重编号）：老客户端的一次性游标语义变化（重放窗口内可能少量重复投递，UI 幂等），迁移说明见 v2 语句注释。
• 认证下 SSE/静态资源经 ?key= 兜底（EventSource 限制）；已在提案 §3 记录权衡。
• pgvector 扩展已随环境可用（本机原生 PG 含 vector/trgm），但列级 HNSW 索引未启用（D23 规模注记）。
• 曾观察到一次并行全量 PG 档运行中 store 单包失败（疑似瞬时连接争用，0.24s 快败），随后 3×PG -race、2×全量 -race、1×全量共 5 次复跑均通过；如复现按验证标准升级排查。

下一责任人/后续项

• 多实例上线前的会话亲和路由（网关或客户端择点）与共享卷 artifactsDir 指配 —— 部署设计，需立项。
• pgvector HNSW 优化（向量规模 ≥ 数万块时）；历史滚动压缩（设计 4.10 远期项不变）。
• 管理面：租户管理 UI/密钥自助（现为 CLI）。