diff --git a/docs/design/topic11-multi-project-proposal.md b/docs/design/topic11-multi-project-proposal.md index d42b5f1..35554be 100644 --- a/docs/design/topic11-multi-project-proposal.md +++ b/docs/design/topic11-multi-project-proposal.md @@ -475,7 +475,48 @@ def _get_session_id(self, agent_id: str, task_id: str) -> str: | Agent 完成回调丢失 | 计数器不归零 | 超时兜底:working 任务超过 `task_timeout` 视为完成,计数器 -1 | | _registry.yaml 并发写入 | 数据损坏 | _registry.yaml 只在 CLI 操作时读写(非 tick 热路径),tick 状态用内存 dict | -## 6. CLI 变更 +### 5.5 启动状态恢复(v2 新增) + +Daemon 进程崩溃后由 PM2 自动重启。启动时需要恢复所有项目状态。 + +**持久化层**(已天然支持,无需额外处理): +- `_registry.yaml` → 项目列表、状态、配置 +- 每个 `blackboard.db` → 任务状态(pending/working/completed/failed...) +- SQLite WAL 模式 → 崩溃时未提交的事务自动回滚,数据完整性有保障 + +**内存层**(需要恢复): +- `ActiveAgentCounter` → 重启后归零 +- `DaemonHealth` → 重启后归零 + +**恢复流程**: + +```python +def start(self): + registry = load_registry() + for project_id, meta in registry["projects"].items(): + if meta["status"] != "active": + continue + # 启动 ProjectSlot + self._start_slot(project_id, meta) + # 第一次 tick 时,_check_working_tasks() 会扫描所有 working 任务 + # 超时的 → 视为完成(decrement 不需要,因为计数器从零开始) + # 未超时的 → 继续等待(计数器会在下次 tick 重新追踪) +``` + +**working 任务的幽灵问题**: + +Daemon 崩溃时可能有 Agent 正在执行。重启后这些任务在 blackboard.db 中仍是 `working` 状态,但 Agent 子进程已经死了(Daemon 重启不等于 Agent 重启,但 Daemon 崩溃通常意味着整个环境有问题)。 + +处理策略: +1. 启动时扫描所有 working 任务 +2. 检查 Agent 子进程是否还活着(如果有 PID 记录的话) +3. 进程已死 + 超过 `task_timeout` → 标记为 `failed`(原因:"Daemon restart, agent process lost") +4. 进程已死 + 未超时 → 标记为 `failed`(保守策略:Daemon 重启后不信任幽灵任务) +5. 不尝试重新执行——用户可以手动 `retry` + +**为什么保守**:Daemon 崩溃是不正常事件。此时 Agent 子进程的状态不可预测(可能写了半个 output.json),重新执行比尝试恢复更安全。 + +**task_attempts 表**的 `attempt_index` 会递增,retry 时从新的 attempt 开始,不覆盖之前的尝试记录。 ### 6.1 项目管理命令 @@ -623,7 +664,8 @@ Agent 不能跨项目读写黑板。这是安全边界——不同项目的数 | 1 | 项目目录结构 + _registry.yaml + project.yaml Schema | 无 | | 2 | ActiveAgentCounter(线程安全计数器 + 全局/per-agent 双重限制) | 无 | | 3 | ProjectSlot(独立线程 tick + SQLite 独立连接 + spawn 前检查计数器) | 1, 2 | -| 4 | Daemon 主循环(启动/监控/重启 ProjectSlot 线程) | 3 | +| 4 | Daemon 主循环(启动状态恢复 + ProjectSlot 线程监控/重启) | 3 | +| 4a | 启动时幽灵 working 任务处理(扫描+标记 failed) | 4 | | 5 | CLI project create/list/default/archive/delete 命令 | 1 | | 6 | CLI 所有操作增加 --project 参数 + 优先级解析 | 1, 3 | | 7 | L2 prompt_template 注入 project_context + session_id 命名规则 | 3, 6 |