synapse-cli-agent 0.1.27__tar.gz → 0.1.29__tar.gz

{synapse_cli_agent-0.1.27 → synapse_cli_agent-0.1.29}/CHANGELOG.md

@@ -7,6 +7,51 @@ The release workflow automatically extracts the matching section as release note
 
 ---
 
+## v0.1.29
+
+### 新增功能
+
+- TUI 图片查看器：点击 transcript 中的图片可在模态窗口中放大查看，修复点击事件在模态栈切换时的误关闭问题。
+- TUI Mermaid 渲染优化：Mermaid 图片在后台线程渲染，渲染期间显示占位提示，避免原生渲染阻塞事件循环。
+- 后台会话结束时通知前台会话；跨事件边界携带取消原因。
+
+### 修复
+
+- 修复图片查看器点击关闭时可能移除默认 screen 并抛出 ScreenStackError 的问题。
+- 修复会话切换时 Mermaid 占位渲染的竞态，渲染结果仅在仍处于当前世代且已挂载时替换。
+
+### 工程改进
+
+- synapse-core-tool 原生扩展发布 0.1.2（修复 pyproject.toml 版本未同步导致的 PyPI 上传失败）。
+- 新增 `make_mermaid_widget_from_png`，将 PNG 渲染与 widget 构建解耦，明确 UI 线程边界。
+
+---
+
+## v0.1.28
+
+### 新增功能
+
+- TUI 支持终端内 LaTeX 数学公式渲染：transcript 中 display math（`$$...$$`）块经原生 RaTeX 内核渲染为 PNG 图片展示，支持前景/背景色、字号、padding 与 device pixel ratio，无需 Node.js、浏览器或系统 TeX。
+- TUI 图片渲染增强：粘贴图片可在终端内预览（textual-image），transcript 显示图片，点击图片可在模态窗口中放大查看。
+- 会话切换器：Ctrl+Tab 快速切换最近 10 个会话并高亮当前项，冷历史合并进 recents。
+- 项目抽屉（project drawer）绑定 F12 并支持交互，可读性与渲染稳定性改进。
+- 跨项目进程内切换与多会话并发支持（runtime 与 TUI 解耦重构）。
+
+### 修复
+
+- 修复退出死锁，新增退出耗时诊断。
+- 修复会话切换后 turn 轮换内容丢失、replay 终态关闭、断链渲染冻结等问题。
+- 修复事件渲染阻塞输入的问题。
+- 隔离各会话的 model 与 MCP 状态，避免跨会话切换串扰。
+- 修复 goal follow-up 轮次的 reservation/settlement 竞态。
+
+### 工程改进
+
+- runtime 与 TUI 解耦：stream parser 移出 UI 包，工具事件结构化输出并保留工具 item 生命周期。
+- synapse-core-tool 原生扩展新增 `render_math_png`（RaTeX 内核 + 嵌入 KaTeX 字体）。
+
+---
+
 ## v0.1.27
 
 ### 新增功能

{synapse_cli_agent-0.1.27 → synapse_cli_agent-0.1.29}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: synapse-cli-agent
-Version: 0.1.27
+Version: 0.1.29
 Summary: Local coding agent built on LangChain Deep Agents (LocalShell, no sandbox)
 Project-URL: Homepage, https://github.com/alex8224/synapse-agent
 Project-URL: Repository, https://github.com/alex8224/synapse-agent
@@ -208,6 +208,7 @@ Requires-Dist: langchain==1.3.14
 Requires-Dist: langgraph-checkpoint-sqlite==3.1.0
 Requires-Dist: langgraph==1.2.9
 Requires-Dist: mcp==1.28.1
+Requires-Dist: mmdr==0.3.0
 Requires-Dist: pydantic-settings==2.14.2
 Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: rich==15.0.0
@@ -215,6 +216,7 @@ Requires-Dist: synapse-core-tool<0.2.0,>=0.1.0
 Requires-Dist: termaid==0.7.1
 Requires-Dist: texicode==1.0.3
 Requires-Dist: textual-diff-view==0.1.5
+Requires-Dist: textual-image==0.13.2
 Requires-Dist: textual-serve==1.1.3
 Requires-Dist: textual==8.2.8
 Requires-Dist: typer==0.27.0
@@ -268,6 +270,24 @@ Then start the TUI from anywhere:
 synapse tui -w .
 ```
 
+Open a session in any registered project from the global catalog:
+
+```bash
+synapse --session <project_id>:<thread_id>   # global session reference
+synapse --project <ref>                      # project by id prefix, name, or path
+```
+
+Inside the TUI, click the topbar `≡` (or the workspace label) to open the
+floating project drawer: it lists every registered project, groups their
+sessions, marks live runtime status, and lets you switch sessions in place or
+jump to another project (the TUI restarts into that project).
+
+Press `Ctrl+Tab` for a lighter active-session switcher: it lists only sessions
+that are doing work right now (across projects), lets you `Tab` / `Shift+Tab`
+through them and `Enter` to switch — the old session keeps running in the
+background and is never cancelled.  Some terminals never forward `Ctrl+Tab` to
+the app; `Ctrl+O` is a drop-in alternative.
+
 <details>
 <summary><b>Or run from source</b></summary>
 

{synapse_cli_agent-0.1.27 → synapse_cli_agent-0.1.29}/README.md

@@ -39,6 +39,24 @@ Then start the TUI from anywhere:
 synapse tui -w .
 ```
 
+Open a session in any registered project from the global catalog:
+
+```bash
+synapse --session <project_id>:<thread_id>   # global session reference
+synapse --project <ref>                      # project by id prefix, name, or path
+```
+
+Inside the TUI, click the topbar `≡` (or the workspace label) to open the
+floating project drawer: it lists every registered project, groups their
+sessions, marks live runtime status, and lets you switch sessions in place or
+jump to another project (the TUI restarts into that project).
+
+Press `Ctrl+Tab` for a lighter active-session switcher: it lists only sessions
+that are doing work right now (across projects), lets you `Tab` / `Shift+Tab`
+through them and `Enter` to switch — the old session keeps running in the
+background and is never cancelled.  Some terminals never forward `Ctrl+Tab` to
+the app; `Ctrl+O` is a drop-in alternative.
+
 <details>
 <summary><b>Or run from source</b></summary>
 

synapse_cli_agent-0.1.29/docs/agent-runtime-decoupling/baseline-report.md

@@ -0,0 +1,79 @@
+# P0 Agent Stream 基线报告
+
+> 状态：P0 基线已固化  
+> 日期：2026-08-07  
+> 原则：只记录可重复测试和脱敏指标，不记录用户消息、密钥或私有配置正文。
+
+## 1. 当前行为基线
+
+当前生产链路：
+
+```text
+TurnController.submit
+  -> CodingAgentApp.run_turn (@work thread=True, exclusive=True)
+  -> TurnController.run_turn
+  -> stream_agent
+  -> _iter_stream_events
+  -> TextualStreamSink
+  -> TranscriptController
+```
+
+### 行为矩阵
+
+| 场景 | 当前语义 | 主要回归测试 |
+|---|---|---|
+| answer token + final update | delta 实时显示，完整消息只提交一次 | `test_runtime_streaming.py`, `test_stream_ui.py` |
+| reasoning + answer | reasoning 先闭合，再提交 answer | `test_textual_stream_sink.py`, `test_stream_ui.py` |
+| tool round | tool call/result 匹配并独立闭合 group | `test_stream_tool_items.py` |
+| parallel tools | 以 call id 优先匹配，不随结果顺序串项 | `test_stream_tool_items.py` |
+| nested subagents | nested item 归属对应 parent task | `test_stream_tool_items.py` |
+| steer | model-only steer 不进入可见 answer | `test_stream_tool_items.py` |
+| context compact | summary wrapper 隐藏，仅记录 compact | stream 相关测试 |
+| HITL | 保留结果并标记 `interrupted=True`，提示 approve/reject | `test_stream_semantic_fixtures.py` |
+| cancel | producer 被取消，checkpoint best-effort repair | `test_stream_cancel.py` |
+| sync saver fallback | async 不兼容时回退 sync stream | `test_stream_cancel.py` |
+| session switch late event | generation 变化后旧 renderer 丢弃回调 | `test_textual_stream_sink.py` |
+
+## 2. P1 新基线
+
+P1 引入 runtime-owned `TurnAccumulator` 后，增加以下契约：
+
+- `StreamResult` 不再读取 Rich/Textual renderer 的 answer/reasoning buffer。
+- runtime 事件携带 `thread_id`、`turn_id` 和严格递增 `sequence`。
+- observer 失败不影响 Agent turn。
+- `synapse.runtime.streaming` 不依赖 `synapse.ui` 或 Textual。
+- retry notifier 使用 `ContextVar` 隔离并发 turn。
+- 旧 `StreamSink` 和 `synapse.ui.stream` 调用方式保持兼容。
+
+## 3. 性能测量方法
+
+测试环境：Windows 11 `10.0.26200`、Python 3.12.9、AMD64 Family 23 Model 96。所有数据均为本机观测值，不作为跨平台硬阈值。
+
+| 指标 | 方法 | 结果 |
+|---|---|---|
+| stream 单元测试总时长 | 62 个针对性 pytest 用例 wall time | 2.80s |
+| 10k 字符事件累积 | `TurnAccumulator`，关闭网络和 DOM | 0.0175s，约 570k events/s |
+| 50k 字符事件累积 | `TurnAccumulator`，关闭网络和 DOM | 0.0955s，约 523k events/s |
+| runtime streaming 冷导入 | 独立 Python 进程，5 次 | 0.162-0.198s（不启用 tracemalloc） |
+| 导入后 Python 工作集 | `Get-Process`，2s 快照，5 次 | 约 5.12 MB；该 Windows 沙箱的工作集数值仅作相对参考 |
+| tracemalloc 当前/峰值 | 独立 Python 进程，导入 runtime streaming | 约 6.08/6.18 MB；启用追踪后导入 2.53-2.97s |
+| cancel 返回时间 | `test_stream_cancel.py`，含固定 0.12s 触发延迟 | 1.13s call wall time |
+| 文档构建 | `mkdocs build` wall time | 9.08s |
+
+当前没有无 provider、无用户配置且能代表真实产品的“Agent ready”和“TUI mounted”端到端基准，因此 P0 不把网络/provider 初始化混入可重复门禁。第一 answer token 的 runtime 增量由同步 fake-agent trace 覆盖，DOM 刷新次数继续由 Textual sink 测试约束。P5 创建多个 SessionRuntime 后再测量每会话增量，并在 P8 确定内存预算。
+
+## 4. 门禁命令
+
+```powershell
+uv run --no-sync pytest tests/test_runtime_streaming.py -q
+uv run --no-sync pytest tests/test_stream_cancel.py tests/test_stream_tool_items.py -q
+uv run --no-sync pytest tests/test_textual_stream_sink.py tests/test_turn_controller.py -q
+uv run --no-sync ruff check .
+uv run --no-sync pytest -q
+```
+
+## 5. 已知基线风险
+
+- 当前 `stream_agent()` 语义解析主循环仍位于 `synapse.ui.stream`；P1 先建立 runtime 契约、累积器和 adapter，再迁移主循环，避免一次性重写成熟状态机。
+- 当前 Textual worker 仍为 `exclusive=True`；这是 P3/P5 的目标，不在 P0-P1 提前开放并行。
+- 当前 GoalService、MCP pool 等单例尚未项目化；P6 处理。

synapse_cli_agent-0.1.29/docs/agent-runtime-decoupling/decisions.md

@@ -0,0 +1,87 @@
+# Agent Runtime 解耦架构决策记录
+
+> 状态说明：`Accepted` 表示当前实施基线；发生变化时追加新决策，不覆盖历史原因。
+
+## ADR-001：采用单进程双 loop，不采用每项目常驻进程
+
+- 状态：Accepted
+- 决策：保留 Textual 主线程 loop 和现有进程级 Agent `AsyncRuntime` loop；所有项目运行时共享该 Agent loop。
+- 原因：当前进程基线内存较高，每项目进程会重复加载 Python、DeepAgents、模型和中间件；同时还需引入高频流事件 IPC，成本与当前目标不匹配。
+- 影响：项目隔离必须通过显式 `ProjectRuntime` 和资源 registry 完成，不能依赖进程边界。
+- 重审条件：未来出现无法隔离的原生崩溃、高风险工具或明确的 daemon/RPC 产品需求。
+
+## ADR-002：先解耦 Agent turn，再实现多会话和多项目
+
+- 状态：Accepted
+- 决策：P0-P3 只建立 UI-independent turn runtime 和 Textual adapter，不同时引入跨项目。
+- 原因：当前 turn 生命周期、事件解析、DOM 更新和持久化交织；直接叠加多项目会扩大状态串线风险。
+- 影响：P3 完成前不实现“切换后继续运行”的用户功能。
+
+## ADR-003：Runtime 产生语义事件，TUI 负责展示策略
+
+- 状态：Accepted
+- 决策：运行层产生 answer、reasoning、tool、usage、activity 和终态事件；颜色、折叠、限频、DAG task 隐藏、Git chrome 刷新属于 UI renderer。
+- 原因：DOM 命令无法供 CLI、测试和未来前端复用，也会让无订阅者运行失效。
+- 影响：事件 payload 必须是纯领域数据，不能包含 Textual widget。
+
+## ADR-004：运行结果不能依赖事件消费者状态
+
+- 状态：Accepted
+- 决策：answer/reasoning 累积、去重、usage 和最终状态由 runtime accumulator 保存；不能再从 `TextualStreamSink.answer_buf` 推导结果。
+- 原因：消费者可能未订阅、丢弃预览事件或在会话切换时被替换。
+- 影响：P1 需要建立独立 accumulator 和 legacy adapter。
+
+## ADR-005：事件分为 turn-local 与 session-local 两层序号
+
+- 状态：Accepted
+- 决策：`AgentTurnRuntime` 产生 turn-local 单调序号；P4 的 SessionEventBroker 再分配 session-local 单调序号。
+- 原因：P1 不应提前依赖全局项目身份；P4 attach/reattach 又需要跨 turn 的稳定游标。
+- 影响：事件必须同时携带 `turn_id`，终态事件必须可去重。
+
+## ADR-006：Catalog 是发现投影，不是运行时或会话正文真源
+
+- 状态：Accepted
+- 决策：`~/.synapse/catalog.sqlite` 继续只保存项目与会话元数据；项目本地 `.synapse` 数据库是 checkpoint、transcript 和 session 真源。
+- 原因：避免全局库成为大体量单点，并保留项目可迁移和独立修复能力。
+- 影响：选择全局会话时必须回源验证 workspace 和 thread。
+
+## ADR-007：第一版并行会话使用独立 Agent graph，共享项目级昂贵资源
+
+- 状态：Accepted
+- 决策：P5 中每个正在运行的会话拥有独立 Agent graph、SteerQueue 和取消状态；同项目可共享 model client/cache、checkpointer 和 MCP scope。
+- 原因：当前 SteerQueue 和部分中间件状态绑定 Agent graph，直接共享 graph 容易串线。
+- 影响：P8 必须测量 graph 增量内存，并为 idle runtime 增加回收策略。
+
+## ADR-008：项目切换不修改进程 cwd 和全局环境
+
+- 状态：Accepted
+- 决策：backend 通过固定 `root_dir` 工作；项目 `.env` 解析为项目私有 mapping，不使用 `load_dotenv(..., override=True)` 在并行运行期间修改 `os.environ`。
+- 原因：进程 cwd 和环境变量是全局可变状态，无法支持并发项目。
+- 影响：P6 需要调整 Settings/bootstrap 和 backend 子进程环境构造。
+
+## ADR-009：迁移期保留兼容导出
+
+- 状态：Accepted
+- 决策：移动 `stream_agent`、`StreamResult`、normalizer 等实现时，保留现有 `synapse.ui.stream` 等公共导入路径的 re-export，直到调用方和扩展完成迁移。
+- 原因：项目指南将包导出视为公共 API；一次性破坏会扩大回归面。
+- 影响：每次删除兼容层必须有仓库搜索和迁移说明。
+
+## ADR-010：不在本计划中实现跨程序退出持续运行
+
+- 状态：Accepted
+- 决策：运行实例生命周期以当前 Synapse 进程为边界；退出程序统一取消和关闭所有任务。
+- 原因：daemon 需要进程管理、鉴权、IPC、重连和版本兼容，是独立产品能力。
+- 影响：P8 只验证可靠 shutdown，不实现后台服务。
+
+## 决策更新模板
+
+```text
+## ADR-NNN：标题
+
+- 状态：Proposed | Accepted | Superseded
+- 决策：
+- 原因：
+- 影响：
+- 替代方案：
+- 重审条件：
+```

synapse_cli_agent-0.1.29/docs/agent-runtime-decoupling/index.md

@@ -0,0 +1,323 @@
+# Agent Runtime 与 TUI 解耦及全局项目管理总体方案
+
+> 文档状态：Accepted<br>
+> 实施状态：已完成（P0-P8 及 P7 UI 收尾）<br>
+> 完成范围：Agent loop 与 TUI 的生命周期解耦、后台多会话、跨项目能力及稳定性收口均已完成。<br>
+> 权威进度台账：[progress.md](progress.md)<br>
+> 架构决策记录：[decisions.md](decisions.md)
+
+## 1. 结论
+
+本次演进采用以下总体架构：
+
+- 保持单进程，不为每个项目创建常驻进程。
+- 保持 Textual UI loop 与现有进程级 Agent `AsyncRuntime` loop。
+- Agent turn、session 和 project runtime 不由 TUI widget 或 Textual worker 拥有。
+- Agent runtime 只产生带明确归属和顺序的语义事件。
+- TUI 通过进程内事件桥订阅事件并在主线程渲染。
+- 项目是资源隔离域，会话是执行和取消域，TUI 是可随时 attach/detach 的客户端。
+- `catalog.sqlite` 只负责全局发现和定位；项目本地数据库仍是会话数据真源。
+
+第一阶段目标不是立即实现多项目，而是证明：
+
+> 即使没有 `CodingAgentApp`、Textual widget 或实时订阅者，一次 Agent turn 仍可完整运行、取消、持久化并产出标准事件。
+
+## 2. 背景与问题
+
+当前代码已经有部分可复用基础：
+
+- `src/synapse/runtime/async_runtime.py` 提供进程生命周期的后台 asyncio loop。
+- `src/synapse/ui/stream.py` 使用 `StreamSink` 抽象 CLI/TUI 输出。
+- `src/synapse/ui/turn/controller.py` 会冻结当前回合的 Agent 和 `thread_id`。
+- transcript generation 可以丢弃切换后的迟到 UI 回调。
+- `~/.synapse/catalog.sqlite` 已有项目和会话元数据投影。
+
+但是 Agent turn 的生命周期仍由 `CodingAgentApp` 和 Textual worker 控制：
+
+- `_busy`、`_cancel_event`、`_active_turn_agent`、`_active_turn_thread_id` 是 App 级状态。
+- `run_turn` 使用 Textual `@work(thread=True, exclusive=True)`。
+- `TextualStreamSink` 在运行过程中直接修改当前 transcript DOM。
+- 回合收尾、usage、goal、summary、catalog 投影依赖当前 App 状态。
+- `stream_agent()` 的结果还依赖 sink 的可变缓冲区。
+- retry notifier、GoalService、MCP pool 等存在进程级单例或单槽状态。
+
+因此，当前“切换 thread”不等于切换完整执行上下文，也无法让旧会话在 UI 切走后独立继续运行。
+
+## 3. 目标
+
+### 3.1 功能目标
+
+1. Agent turn 可在无 TUI 环境中独立执行。
+2. TUI 切换或暂时不订阅时不影响 Agent 执行。
+3. 同一项目的多个会话可独立运行、取消、steer 和恢复观察。
+4. Synapse 可在任意目录启动并浏览全部已注册项目及会话。
+5. 选择跨项目会话后，Agent 使用该会话所属 workspace、配置和数据库工作。
+6. 其他已启动会话继续运行，直到完成、单独取消或程序退出。
+
+### 3.2 架构目标
+
+- 运行层不导入 Textual，也不调用 `CodingAgentApp`。
+- UI 层不拥有 Agent task，只发送命令和消费事件。
+- 所有运行事件都有稳定归属、顺序和终态。
+- 持久化只依赖冻结的运行上下文和领域事件，不依赖 widget 状态。
+- 项目配置、Goal、MCP、backend 和数据库资源可按项目隔离。
+- 所有队列、缓存、搜索和历史读取均有界。
+
+## 4. 非目标
+
+本计划当前不包含：
+
+- 每项目一个进程或每会话一个进程。
+- TUI 退出后 Agent 仍跨进程继续运行的 daemon。
+- 网络 RPC 或 IPC 协议。
+- 将全部项目会话正文集中迁移到全局数据库。
+- 第一阶段直接开放无限并行。
+- 在运行时动态修改进程 `cwd`。
+
+未来如需要关闭 TUI 后仍继续执行，可在稳定的 RuntimeManager API 之外增加 daemon；不能让该需求反向污染当前解耦步骤。
+
+## 5. 当前与目标依赖方向
+
+### 5.1 当前方向
+
+```text
+CodingAgentApp
+  -> TurnController
+      -> stream_agent
+          -> TextualStreamSink
+              -> TranscriptController / DOM
+      -> goal / steer / persistence / catalog
+```
+
+### 5.2 解耦里程碑后的方向
+
+```text
+CodingAgentApp
+  -> TUI command adapter
+      -> AgentTurnRuntime
+          -> runtime streaming core
+          -> AgentEventSink
+
+AgentEvent
+  -> TextualEventRenderer
+      -> TranscriptController / DOM
+```
+
+### 5.3 最终方向
+
+```text
+Synapse 单进程
+├─ Textual UI loop（主线程）
+│  ├─ Global project/session views
+│  ├─ active SessionRef
+│  └─ TextualEventRenderer
+│
+└─ Agent AsyncRuntime loop（后台线程）
+   └─ RuntimeManager
+      ├─ ProjectRuntime A
+      │  ├─ SessionRuntime A/1
+      │  └─ SessionRuntime A/2
+      └─ ProjectRuntime B
+         └─ SessionRuntime B/1
+```
+
+## 6. 核心领域边界
+
+### 6.1 Turn
+
+一次用户提交或 HITL resume 对应一个不可变 `TurnContext`：
+
+```python
+@dataclass(frozen=True)
+class TurnContext:
+    thread_id: str
+    turn_id: str
+    agent: Any
+    settings: Settings
+    request: TurnRequest
+```
+
+运行开始后，TUI 的当前页面、活动 thread 或 model picker 都不能改变该上下文。
+
+### 6.2 Session
+
+会话是实际执行和取消域：
+
+```python
+class SessionRuntime:
+    ref: SessionRef
+    agent: Any
+    status: SessionStatus
+    active_turn: TurnHandle | None
+    cancel_token: CancelToken
+    steer_queue: SteerQueue
+    usage: SessionUsage
+```
+
+同一会话同时最多一个 graph run；不同会话可在受控并发限制内运行。
+
+### 6.3 Project
+
+项目是资源和配置隔离域：
+
+```python
+class ProjectRuntime:
+    project_id: str
+    workspace: Path
+    settings: Settings
+    session_store: SessionStore
+    checkpointer: Any
+    goal_service: GoalService
+    mcp_scope: McpScope
+```
+
+项目不是独立进程，也不是独立 event loop。
+
+### 6.4 UI
+
+TUI 只负责：
+
+- 查询项目和会话。
+- 向 RuntimeManager 发送 open/submit/steer/cancel 命令。
+- attach/detach 某个 `SessionRef`。
+- 从 snapshot 和有序事件恢复并实时渲染。
+- 展示状态，不决定运行是否继续。
+
+## 7. 事件模型原则
+
+Turn 层首先产出 turn-local 事件；SessionEventBroker 后续为其包装 session-local 序号。
+
+```python
+@dataclass(frozen=True)
+class TurnEvent:
+    thread_id: str
+    turn_id: str
+    sequence: int
+    kind: TurnEventKind
+    payload: object
+```
+
+最少事件集合：
+
+- `turn_started`
+- `activity_changed`
+- `reasoning_delta` / `reasoning_completed`
+- `answer_delta` / `answer_completed`
+- `tool_batch_started`
+- `tool_started` / `tool_updated` / `tool_finished`
+- `tool_batch_finished`
+- `usage_updated`
+- `context_compacted`
+- `info`
+- `turn_cancelled`
+- `turn_failed`
+- `turn_completed`
+
+约束：
+
+- payload 必须是 runtime 领域数据，不能是 Textual widget。
+- 运行结果不能依赖消费者是否存在或是否渲染了事件。
+- delta 可以合并显示，但 completed/failed/cancelled 终态不能丢。
+- UI 策略如 DAG task group 隐藏、Git chrome 刷新、颜色和折叠均留在 renderer。
+
+## 8. 实施阶段
+
+| 阶段 | 名称 | 核心产物 | 完成后的能力 |
+|---|---|---|---|
+| P0 | 基线与护栏 | 行为矩阵、回归 trace、依赖约束 | 可安全开始重构 |
+| P1 | Streaming core 与事件契约 | UI-independent 事件、accumulator、兼容 adapter | 流解析不再以 UI sink 状态为真源 |
+| P2 | AgentTurnRuntime | 无 TUI 的独立 turn 状态机与 API | headless turn 可完整运行 |
+| P3 | TUI 事件适配与切换 | Textual renderer、现有 TUI 接入 | Agent loop 与 TUI 解耦里程碑完成 |
+| P4 | SessionRuntime 与事件 Broker | task/cancel/goal/persistence 会话化 | 无订阅者时会话仍继续 |
+| P5 | 同项目多会话 | RuntimeManager、会话并发与 attach/detach | 切换后旧会话继续运行 |
+| P6 | ProjectRuntime | 项目配置和资源隔离 | 单进程内安全打开多个项目 |
+| P7 | 全局控制面 | 任意位置启动、项目分组会话与操作 | 达成全局项目/会话管理目标 |
+| P8 | 稳定性与性能收口 | 负载、内存、关闭、故障恢复验证 | 达到可长期运行标准 |
+
+详细方案：
+
+- [P0：基线与护栏](phase-0-baseline.md)
+- [P1：Streaming core 与事件契约](phase-1-streaming-core.md)
+- [P2：AgentTurnRuntime](phase-2-turn-runtime.md)
+- [P3：TUI 事件适配与切换](phase-3-tui-cutover.md)
+- [P4：SessionRuntime 与事件 Broker](phase-4-session-runtime.md)
+- [P5：同项目多会话](phase-5-multi-session.md)
+- [P6：ProjectRuntime](phase-6-project-runtime.md)
+- [P7：全局控制面](phase-7-global-control-plane.md)
+- [P8：稳定性与性能收口](phase-8-hardening.md)
+
+## 9. 阶段门禁
+
+每个阶段必须满足：
+
+1. 上一阶段验收项全部通过。
+2. `progress.md` 中不存在未处理的阻塞项。
+3. 新公共边界有类型标注和最小文档。
+4. 先运行最窄测试，再运行相关领域测试。
+5. 涉及导入路径移动时保留必要 re-export。
+6. 不允许通过关闭测试、放宽断言或吞异常绕过门禁。
+7. 行为或配置变化同步更新用户文档。
+
+P3 是首个强制停顿点：只有证明 Agent turn 在 TUI 无订阅时仍正确运行，才能开始 P4。
+
+P5 是第二个强制停顿点：只有同项目多会话不串线，才能开始跨项目资源隔离。
+
+## 10. 测试策略
+
+### 10.1 分层测试
+
+- 纯事件测试：fake LangGraph events -> ordered `TurnEvent`。
+- Turn runtime 测试：headless 运行、取消、错误、HITL、retry。
+- Adapter 合约测试：同一事件 trace 在 Rich/Textual 中语义一致。
+- Session 测试：detach、reattach、后台完成、按会话取消。
+- Project 测试：两个临时 workspace 的配置、文件和数据库不串线。
+- TUI pilot 测试：实时 token、工具组、状态栏和历史恢复。
+- 长时测试：并行任务、内存回收、程序关闭和异常恢复。
+
+### 10.2 常用验证命令
+
+```powershell
+uv run --no-sync pytest tests/test_stream_cancel.py -q
+uv run --no-sync pytest tests/test_stream_tool_items.py -q
+uv run --no-sync pytest tests/test_textual_stream_sink.py -q
+uv run --no-sync pytest tests/test_turn_controller.py -q
+uv run --no-sync pytest tests/test_project_catalog.py -q
+uv run --no-sync ruff check .
+uv run --no-sync pytest -q
+```
+
+具体阶段的最窄测试见对应阶段文档。
+
+## 11. 兼容与回滚策略
+
+- 旧导入路径如 `synapse.ui.stream.stream_agent` 在迁移期继续 re-export。
+- 每一阶段保持一个可工作的兼容 adapter，不允许同时重写 runtime 和所有 renderer。
+- 先建立新路径和契约测试，再切换调用方，最后删除旧路径。
+- 数据库 schema 变化必须向前迁移，不能要求用户删除本地状态。
+- P0-P3 不改变现有用户命令和会话数据格式。
+- 每阶段独立提交，出现回归时可按阶段回退。
+
+## 12. 进度与方案更新规则
+
+`progress.md` 是实施状态的单一真源：
+
+- 开始任务前，将对应任务标为 `in_progress` 并更新“当前工作”。
+- 完成任务后记录验证命令和结果，再标为 `completed`。
+- 阻塞时记录证据、影响和解除条件，不能仅写“有问题”。
+- 设计变化先更新 `decisions.md` 和对应阶段文档，再修改代码。
+- 阶段完成时更新阶段验收、风险余项和变更日志。
+- 阶段文档中的任务表定义范围，不重复维护实时状态。
+
+## 13. 整体完成定义
+
+只有同时满足以下条件，本计划才算完成：
+
+- Agent runtime 包不依赖 Textual。
+- TUI 切换订阅不会取消后台会话。
+- 不同会话的事件、usage、goal、取消和持久化不串线。
+- 不同项目的 workspace、配置、MCP、Goal 和数据库不串线。
+- 任意目录启动不污染该目录，仍能浏览和打开已注册项目。
+- 全局会话操作使用 `(project_id, thread_id)` 唯一定位。
+- 运行中的会话只在完成、单独取消或程序退出时终止。
+- 全量 Ruff、pytest 和文档构建通过。
+- 长时运行的内存和任务数量符合 P8 确定的预算。