Merge pull request #49 from rongxinzy/techdebt/runtime-bridge-convergence

Converge engineering status docs

Author: hawkli-1994

AGENTS.md

@@ -142,29 +142,43 @@ swarmmind/                         ← Python package root
 ├── renderer.py                    ✅ LLM Status Renderer
 ├── agents/
 │   ├── base.py                    ✅ BaseAgent (abstract base with memory utilities)
-│   └── general_agent.py           ✅ DeerFlowRuntimeAdapter (DeerFlow-driven adapter, compat alias: GeneralAgent)
+│   └── general_agent.py           ✅ DeerFlowRuntimeAdapter (runtime orchestration shell, compat alias: GeneralAgent)
 ├── repositories/                  ✅ Repository layer (SQLModel + CRUD per domain)
 │   ├── agent.py
 │   ├── action_proposal.py
 │   ├── strategy.py
 │   ├── event_log.py
-│   ├── working_memory.py
 │   ├── memory.py
 │   ├── conversation.py
 │   ├── message.py
 │   └── runtime_catalog.py
+├── services/
+│   ├── conversation_execution.py  ✅ ChatSession send/stream orchestration
+│   ├── conversation_support.py    ✅ Message/title persistence helpers
+│   ├── conversation_trace_service.py ✅ conversation_id -> thread_id trace orchestration
+│   ├── lifecycle.py               ✅ startup lifecycle + cleanup scanner
+│   ├── runtime_bridge.py          ✅ sync/async bridge helpers for DeerFlow runtime calls
+│   ├── runtime_event_processing.py ✅ stream capture + event normalization helpers
+│   ├── runtime_support.py         ✅ runtime binding/model/runtime-option helpers
+│   ├── stream_events.py           ✅ DeerFlow event -> UI stream event translation
+│   ├── trace_checkpoint_storage.py ✅ raw checkpoint storage access
+│   ├── trace_provider.py          ✅ parsed checkpoint provider boundary
+│   └── trace_service.py           ✅ collaboration trace reconstruction
 ├── runtime/
 │   ├── bootstrap.py               ✅ DeerFlow Runtime bootstrap + config generation
 │   ├── profile.py                 ✅ RuntimeProfile management
 │   ├── models.py                  ✅ Runtime data models
 │   ├── catalog.py                 ✅ Model catalog for runtime profiles
 │   └── errors.py                  ✅ Runtime error types
 └── api/
-    └── supervisor.py              ✅ FastAPI supervisor REST API
+    ├── supervisor.py              ✅ FastAPI app assembly + supervisor/system endpoints
+    └── conversation_routes.py     ✅ conversation route registration and compatibility exports
 
 ui/                                ← Supervisor web UI (Vite + React + shadcn/ui)
 ├── src/
-│   └── App.tsx                    ✅ Full supervisor UI
+│   ├── App.tsx                    ✅ Full supervisor UI shell
+│   ├── components/workspace/      ✅ Split chat workspace components
+│   └── core/chat/                 ✅ Chat stream/scroll/types helpers
 ├── vite.config.ts
 └── tailwind.config.js
 
@@ -175,6 +189,10 @@ tests/
 ├── test_layered_memory.py         ✅ Layered memory tests
 ├── test_conversation_titles.py    ✅ ChatSession title generation
 ├── test_conversation_stream.py    ✅ Streaming conversation tests
+├── test_conversation_trace_service.py ✅ Conversation trace orchestration tests
+├── test_runtime_bridge.py         ✅ Sync/async bridge tests
+├── test_general_agent_stream_bridge.py ✅ GeneralAgent sync/async bridge regression tests
+├── test_general_agent_stream_events.py ✅ GeneralAgent stream event processing tests
 └── test_runtime_model_catalog.py  ✅ Runtime model catalog tests
 ```
 

docs/README.md

@@ -1,6 +1,6 @@
 # SwarmMind 文档总览
 
-> 日期：2026-04-08
+> 日期：2026-04-15
 > 用途：定义当前文档体系的主入口，区分前瞻性设计与工程实现状态
 
 ## 0. 文档分类体系
@@ -24,7 +24,8 @@
 
 - `AGENTS.md` — 当前工程状态总览（含 Phase A 实现清单）
 - `docs/README.md` — 本文档，文档体系元数据
-- `docs/chat-mainline-execution-plan.md` — 当前主路径执行计划（临时执行文档，完成后归档）
+- `docs/chat-mainline-execution-plan.md` — 主路径执行计划草案（当前大部分内容尚未启动）
+- `docs/technical-debt-repayment-plan.md` — 技术债收口结论与剩余低利息债项
 - `docs/archive/*` — 已完成的临时调研与执行文档（如 gap-analysis、migration-plan）
 
 **阅读场景**: 理解当前代码能做什么、如何运行、如何部署
@@ -101,10 +102,9 @@
 
 用途:
 
-- 记录当前迭代的主线优先级判断
-- 约束执行顺序, 避免同时横向铺多个半成品模块
-- 作为完成后归档到 `docs/archive/` 的临时执行文档
-- 记录主路径相关结构债、运行债和测试债的偿还顺序
+- `docs/chat-mainline-execution-plan.md` 保留主线路线草案, 但当前大部分事项尚未进入实施
+- `docs/technical-debt-repayment-plan.md` 记录本轮债务收口结论, 不再维护中间态执行步骤
+- 两者都属于工程状态文档, 需要随着现实状态更新, 但不应反向覆盖架构文档
 
 ## 3. 清理规则