Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2cec59016a | ||
|
|
52bf525ef8 |
@@ -8,10 +8,10 @@ product_contract_source: ce-plan-bootstrap
|
||||
|
||||
# 多人协作存储与分布式演进方案 - Plan
|
||||
|
||||
修订:r1;确认状态:**已批准(2026-10-11 用户指示「按方案开始改造」)**;推进状态:方案获批发布,实施自首选增量 U1+U2 启动;业务实施/迁移/压测/部署仍为 NOT_RUN,逐项以实施任务卡为准。
|
||||
修订:r2;确认状态:**已批准(2026-10-11 用户指示「按方案开始改造」)**;推进状态:U1–U7 **代码与测试已合入**(Backend [#164](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Backend/pulls/164);Dev [#410](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/410)/[#439](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/439)/[#442](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/442);闭卡 [#424](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/424) 等)。正确性矩阵 A1–A7 与 B1 冒烟已绿(CI/SELF);容量合同 B2/B3/B5 contract 与 C2 正式双实例负载 **测量中/待回填**;双主机 C3、运维演练 C4/C5 未做。**不承诺容量数字,不放行第二实例承接写请求**,直至检查单对应项有可复核证据。
|
||||
需求来源:2026-10-11 用户要求完善 SQLite、PostgreSQL/pgvector、Redis 分工;随后确认“10–100 人,多人多项目多会话并行,未来支持多服务分布式”。
|
||||
需求负责人:weichen;方案编制:Codex;实施及运维负责人:待指定。更新时间:2026-10-11(Asia/Shanghai)。
|
||||
关联任务:Dev `.task/feature-collaboration-storage-plan.md`(方案任务,已发布);后续 U1+U2 实施由独立任务承接。
|
||||
需求负责人:weichen;方案编制:Codex;实施及运维负责人:待指定。更新时间:2026-10-12(Asia/Shanghai)。
|
||||
关联任务:方案卡已归档 `.task/archive/feature-collaboration-storage-plan.md`;U1–U7 实施卡均已归档;当前收尾与容量窗口见 Dev `.task/feature-u7-capacity-wrap-measure.md`。放行检查单:Dev `docs/release-multi-instance.md`。
|
||||
正文中的源码路径以 Agent-System-Dev 为根;工作包中的 `internal/` 简写指 `modules/backend/internal/`;文内相对链接以本文为根。
|
||||
|
||||
## 1. 推荐结论与边界
|
||||
@@ -246,8 +246,8 @@ SQLite 本身支持可靠事务与多人经同一应用访问;WAL 提升读写
|
||||
|
||||
必需观测:API P95/P99与预期/非预期错误,DB pool wait/连接数/慢查询/锁等待,队列长度/最老年龄,run 租约/过期写拒绝/未知副作用,SSE cursor lag/补查次数,Redis 错误与降级,检索耗时/召回抽样,备份时间与恢复结果。日志只记录 request/run/owner 的安全标识,不记录 DSN、密钥或文档正文。
|
||||
|
||||
当前交付仅为 r1 方案与 SELF 调查记录。需求人数已确认;容量阈值、正式数据/部署目标、迁移窗口、灾难恢复等级和实施阶段尚待人工评审。没有业务测试 PASS、独立 REPLAY、CI GATE 或已部署声明。
|
||||
r1 为方案与 SELF 调查记录。r2 起:U1–U7 代码与测试已合入且正确性 CI 绿;容量阈值的正式测量、双主机部署目标、灾难恢复运维演练仍待窗口证据。本地 SELF 压测不能冒充 GATE/REPLAY 放行。部署与第二实例写流量仍未授权。
|
||||
|
||||
方案静态审阅及修订处置见[审阅记录](../records/2026-10-11-collaboration-storage-plan-review.md)。Agent 审阅不替代人工批准或实现验收。
|
||||
方案静态审阅及修订处置见[审阅记录](../records/2026-10-11-collaboration-storage-plan-review.md)。进程级黑盒相对库级 Manager 测试的漏检教训见[经验条目](../records/2026-10-12-lesson-http-multi-instance-vs-manager-tests.md)。Agent 审阅不替代人工批准或实现验收。
|
||||
|
||||
首选下一增量是 **U1 + U2 的详细实施与测试合同**:固定目标实例与 PG 测试环境,解决团队档、迁移原子性和真实数据库测试门禁。U6 的事件正确性修复可在单独授权后并行;不要先增加应用副本。各实现任务启动前复核在途 PR 与依赖 SHA,再按 Dev 的 evidence/task-sync/组合验证流程交付。
|
||||
首选下一增量是 **完成本机容量测量窗口并回填检查单**(`--seed contract` + 双实例 `ladder` / `sustained60m` / `sustained2h`,入口 `tests/load/collaboration/`;结果写入 Dev `docs/release-multi-instance.md` 与本仓容量报告)。其后候选项:**C3 双主机验证**(需用户指定第二主机)或 **C4/C5 运维演练**(PG/Redis 断连恢复与备份恢复)。不要在容量与双进程负载未过前开放第二实例写。各实现任务启动前复核在途 PR 与依赖 SHA,再按 Dev 的 evidence/task-sync/组合验证流程交付。
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# 经验:库级 Manager 测试通过 ≠ 跨实例 HTTP 路径正确——进程级黑盒才能抓住短路
|
||||
|
||||
- 状态:validated(三条缺陷均在 U7 双进程验收中复现、修复并入 CI 回归)
|
||||
- 触发条件/检索词:多实例 / 跨实例 HITL / cancel / 命令总线 / Manager 层单测 / HTTP 黑盒 / 假成功 200 / conversation_id 空 / 落卡短路命令 / U5 vs U7
|
||||
- 根因与来源:协作存储 U5 用真库直接调 `runmgr.Manager` 覆盖争抢/围栏/命令语义,**绕过 HTTP handler**。U7 `tests/integration/multi-instance/` 起两个真实 `serve` 进程共享 PG 后抓出三条生产路径缺陷(均已有 backend 回归):① HITL resolve 在非执行实例先把卡标 resolved,命令 fallback 的 `!card.Resolved` 判定被跳过,执行者永远等不到答案;② 跨实例 cancel 命令 `conversation_id` 传空串,消费侧执行权 JOIN 永不命中;③ `CancelRun` 在非执行实例无句柄时返回 nil,HTTP 层 200「假成功」吞掉命令路径。库级绿与进程级红可以同时为真。
|
||||
- 下次应做的检查:凡涉及「任意 API 实例发起、执行实例消费」的能力(取消、HITL、命令、租约接管),验收矩阵须含 **至少一条双进程 HTTP/SSE 黑盒**(或等价:经真实 handler + 命令总线落库再消费),不能只用 Manager/Store 直调冒充跨实例已过。写回归时优先钉住「非执行实例的 HTTP 状态码与执行者观测到的最终状态」成对断言。
|
||||
- 验证方法与防护:已落实——Dev `make test-multi-instance`(CI `test-pg` 必跑)覆盖跨实例读/SSE/409/HITL/取消/崩溃恢复/重启不变量;三条缺陷各有 backend 回归测试。建议保持:新增跨实例命令路径时先加进程级场景再声称 U5/U7 完成。
|
||||
- 适用与不适用:适用多实例共享权威存储、命令经 DB/总线投递的架构;不适用纯单实例本地句柄路径,也不替代库级语义单测(二者互补)。
|
||||
- 尚缺证据/防护:双主机(跨机网络)C3 与正式容量窗口不在本教训范围内;本条只固定「测试层级」缺口。
|
||||
- 复核人、日期、版本:weichen,2026-10-12;依据 Dev 放行检查单 A6/C1 与 `tests/integration/multi-instance/README.md`「已实测发现并修复的缺陷」
|
||||
- 替代/退役条件:若跨实例命令路径全部强制经同一 HTTP→命令总线集成测试门禁,且历史三条回归仍绿,可将本条降为参考;不得在无门禁时退役。
|
||||
Reference in New Issue
Block a user