auto-sync: 2026-05-16 23:27:52

docs/design/technical-design-v2.6.md

@@ -240,10 +240,33 @@ def dispatch(task, action_type, project_config):
 - Full Agent：`subprocess.Popen`（非阻塞），不等返回，下次 tick 检查产出
 - Subagent：`sessions_spawn`（Gateway API），等返回
 
-### 4.3 ActiveAgentCounter（课题11）
+### 4.3 线程模型：纯 asyncio 单线程
+
+整个 Daemon 运行在单个 asyncio event loop 中（与 FastAPI 共享）。
+
+**关键设计决策**：Full Agent spawn 不用 `subprocess.Popen`（同步，会短暂阻塞 event loop），改用 `asyncio.create_subprocess_exec`（异步非阻塞）。这样 API 请求处理、SSE 推送、Daemon tick 三者互不阻塞。
 
 ```python
-class ActiveAgentCounter:
+async def spawn_full_agent(agent_id: str, message: str, new_session: bool = False) -> str:
+    """异步非阻塞 spawn，全程 asyncio"""
+    session_id = str(uuid.uuid4())
+    cmd = ["openclaw", "agent", "--agent", agent_id,
+           "--session-id", session_id, "--message", message, "--json"]
+    
+    proc = await asyncio.create_subprocess_exec(
+        *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+    )
+    # 不 await proc.wait()，让子进程独立运行
+    # 下次 tick 通过产出物检查完成状态
+    _register_session(agent_id, session_id, proc.pid)
+    return session_id
+```
+
+**Subagent spawn** 通过 OpenClaw Gateway 内部 API（`sessions_spawn`），天然异步。
+
+### 4.4 ActiveAgentCounter（课题11）
+
+纯 asyncio 实现（`asyncio.Semaphore`），与线程模型一致：
     """异步计数器，控制并发"""
     def __init__(self, max_global=5, max_per_agent=1):
         self._global = asyncio.Semaphore(max_global)