[设计] 收敛 Project 状态更新与持久化：确定性事件、按需摘要及 SQLite 迁移 #2182

Written-by: Codex

定位与关联

收敛已确认的 Project 持久化、状态更新时机及文档/上下文增长控制规则。
关联 #2171（Project 生命周期和治理）、#2175（持久化交接与咨询分离）、#2177（上下文预算与记忆整理）、#2179（Task 与子任务生命周期）。
本单是设计与实施拆分依据，非已实现/已上线声明，不自动启动开发、部署或打断现有前端执行。常规技术细节可独立设计，改变既定产品或权限边界再向用户提出具体方案。

核心结论

人和 Bot 提出状态变化，后端通过有权限的结构化接口校验并提交；正式事实由后端记录承载。
明确分开运行事实、可派生概览、语义摘要、项目定位：

• 不在每次操作后调用 Bot 询问“是否更新项目状态/定位”。
• 不因一次执行、交接、测试或聊天就重写 PROJECT.md、ROADMAP.md。
• 模型文字和记忆不能覆盖正式权限、执行证据或裁定。
• Effects 负责提交后的动作可靠派发/恢复，不代替业务状态、权限或上下文管理。
  借鉴 SuperAgent 的确定性领域更新与语义评估分离；不声称其具备与本项目相同的 Project 定位治理模型。

状态分层、写入主体与触发时机

1. 正式项目状态

目标、范围、成员权限、角色定义、仓库关联、生命周期、正式决策及最终记录。

• 按项目治理规则由有权的 Owner/Maintainer 决定，Chief 可以提议；Project 服务校验后写入。
• 项目定位/目标/范围仅在明确提出变更，或 Chief 发现实质冲突后提出建议并经相应权限确认时改变。
• 角色增删改保持 Chief 提议、Maintainer/Owner 同意的约定。
• Project 关闭仍由 Owner 二次确认；关闭与归档分开，保留历史与最终记录，未完成 Task 列入最终记录即可，不增加清空任务门槛。
• Project 与仓库多对多，不能将单一 repository 字段的现状固化为产品限制。

2. 工作运行事实

Task 入列/领取/交接/阻塞/执行结果、Attempt、worker、资源占用、输入/执行回执。

• 当前 Bot 提交结构化结果/交接，执行器或适配器提交实际事件；对应后端服务校验权限、当前代次、归属和证据后直接更新。
• 确定性转换由代码完成，不为每次转换额外调用 Chief/LLM。
• Task 接纳、最终完成等已约定需要 Chief 判断的节点仍保留，不以“减少调用”绕过裁定。
• 全部有效阻塞解除后，父 Task 由后端幂等重新入列，不等 Chief 想起来。
• 需要后续动作时，将状态与 Effect 意图在同一业务事务中提交，提交后执行，再记录回执。
• Chief 巡检发现停滞、异常与长期等待，不承担日常状态同步；巡检频率由定时任务配置，不硬编码到框架。

3. 可派生概览

活跃任务、阻塞清单、任务数量、近期交付等，从正式记录查询生成；需要时缓存。

• 不需要模型重述数据库已有事实，不另存一份可随意修改的权威 status。
• 缓存/读模型可重建，提供版本或更新时间，不能用旧概览覆盖新事实。

4. 语义摘要与文档

Chief 可在用户询问、阶段结束或配置的汇总时间，结合证据整理项目进展解释。

• 不是每次操作都触发；按需合并整理并控制调用成本。
• 摘要保留来源/更新时间/版本，事实冲突回到正式记录核对。
• 仓库内架构、规范、决策正文由执行 Bot 正常修改审查，后端可引用明确版本。
• 后端掌管结构化权限、生命周期和运行事实；仓库文档掌管相应正文，避免两处独立维护相同事实。

SQLite 持久化方向（用户已同意）

现有交付分支使用锁定 JSON 快照和提交后 Effects；基础已存在，不误报为 SQLite 已接入。

• 先明确 Project/Task/Handoff 等服务与存储接口，再渐进迁移项目正式状态、运行记录及 Effects 至 SQLite。
• 同一业务操作需原子提交的数据在同一数据库事务中更新，包含相应 Effect 意图/必要回执。
• 使用唯一约束、条件更新与版本/代次校验保证幂等和并发边界；SQLite 不替代权限、主动权、执行退出证明或外部结果核对。
• 日志、大文件、工作区、产物留文件系统，数据库保存引用、哈希和必要元数据。
• JSON 迁移要可校验、可回退；明确切换边界，不能长期保留两份可写事实来源。
• 保留现有未完成任务、会话、交接和待执行 Effects 的身份与恢复依据。
• 区分原子提交、进程重启恢复与断电持久性保证；配置/测试实际需要的数据库持久性设置，不作未经验证的保证。
• 不同时引入独立数据库服务或消息队列；后续拆分迁移 issue 与其他实施项的依赖。
• 核对 main 与 delivery/ai-centric-development-service 的实际差异，分别记录已有能力、待补齐项与发布范围。

防止状态文档与上下文膨胀

不建立无限追加的“项目状态大全”：

• PROJECT.md/ROADMAP.md：项目约定与当前计划，已完成事项移出活跃区并保留历史引用。
• Chief 摘要：固定栏目与长度/token 预算，替换当前摘要，历史版本另存。
• 决策与经验：按主题拆分、去重、标记替代关系；索引保留有效结论和引用。
• Task/Handoff/Attempt：结构化记录、分页查询；完成记录退出默认活跃视图，历史仍可追溯。
• 对话/工具输出/测试日志/产物：独立保存，摘要加引用，不整段复制进项目文档。
• 每轮仅加载角色约定、当前 Task 摘要、相关决策及交接增量；检索、日志/文件读取和工具结果均有上限。
• 达到可配置预算阈值提前整理，预留工具和模型输出空间；恢复原 Session，不能静默重开来掩盖溢出。
• 保留约束、未决问题、代码版本和证据；无法容纳必要内容明确报告。
• 观察各层上下文用量、摘要大小、检索来源和调用次数。历史存储增长与上下文预算分别管理，换 SQLite 本身不解决上下文超限。
  与 [设计] 统一 Chief 与工作角色的上下文预算、长期记忆整理及会话恢复机制 #2177 共用同一套上下文机制，不重复实现。

示例验收

Tester 提交测试通过：

1. 后端校验候选版本、执行归属和证据，保存测试结果；
2. 按 Handoff 契约更新归属/后续派发意图；
3. 查询/看板体现最新事实；
4. 若需要最终完成裁定，将结果提交 Chief；
5. 不额外询问 Chief 是否修改项目定位，不强制重写项目文档，不无条件触发摘要模型调用。

测试及交付要求

• 运行事实转换与概览查询不额外调用模型；需 Chief 接纳/裁定的语义节点保持有效。
• 定位/目标/范围无明确授权变更时不被日常事件、摘要或模型文字改写。
• 概览可重建、缓存失效正确；文档不因每个事件持续追加或重写。
• SQLite 原子性、重复/并发子任务完成、领取冲突、旧代次回调、持久化前后崩溃/重启与 Effects 恢复；无双执行授权、无重复有效入列。
• JSON 迁移校验、回退流程及未完成工作身份/会话/Effects 保留。
• 项目权限、关闭二次确认、历史/最终记录保留和私有记忆隔离。
• 长历史和大型工具结果下预算有效；原证据可追溯，摘要不虚构成功。
• 区分测试替身通过与真实 SDK/实际任务验证，报告准确提交、已执行及未覆盖项。
• 同步长期记忆、架构/子系统文档、接口与配置说明、迁移/恢复操作说明及变更记录。
• 后续拆为可审阅实施 issue，明确依赖；不重做 control-plane/UI，不擅自上线或中断现有任务。