299 lines
8.0 KiB
Markdown
299 lines
8.0 KiB
Markdown
# Phase 4：流式交互
|
||
|
||
日期：2026-04-04
|
||
状态：待实施
|
||
|
||
依赖：Phase 3 完成
|
||
|
||
---
|
||
|
||
## 1. 本阶段目的
|
||
|
||
实现 PTY 终端 + WebSocket 流式输出：
|
||
- PTY 终端管理
|
||
- WebSocket 端点
|
||
- 流式输出集成
|
||
- 交互输入
|
||
|
||
---
|
||
|
||
## 2. 详细任务
|
||
|
||
### 2.1 PTY Terminal Engine
|
||
|
||
**新文件**: `backend/app/agents/tools/terminal_engine.py`
|
||
|
||
```python
|
||
import asyncio
|
||
import os
|
||
from dataclasses import dataclass, field
|
||
from typing import AsyncGenerator
|
||
|
||
@dataclass
|
||
class PTYSession:
|
||
session_id: str
|
||
process: asyncio.subprocess.Process
|
||
workspace_path: str
|
||
|
||
class PTYManager:
|
||
def __init__(self):
|
||
self._sessions: dict[str, PTYSession] = {}
|
||
self._output_queues: dict[str, asyncio.Queue] = {}
|
||
|
||
async def spawn(
|
||
self,
|
||
cli: str,
|
||
args: list[str],
|
||
cwd: str,
|
||
session_id: str | None = None
|
||
) -> str:
|
||
"""启动 PTY 会话"""
|
||
if session_id is None:
|
||
session_id = f"pty_{os.urandom(8).hex()}"
|
||
|
||
# 创建 PTY 进程
|
||
process = await asyncio.create_subprocess_exec(
|
||
*([cli] + args),
|
||
stdout=asyncio.subprocess.PIPE,
|
||
stderr=asyncio.subprocess.PIPE,
|
||
cwd=cwd,
|
||
env={**os.environ, "TERM": "xterm-256color"},
|
||
)
|
||
|
||
session = PTYSession(
|
||
session_id=session_id,
|
||
process=process,
|
||
workspace_path=cwd,
|
||
)
|
||
self._sessions[session_id] = session
|
||
self._output_queues[session_id] = asyncio.Queue()
|
||
|
||
# 启动输出读取协程
|
||
asyncio.create_task(self._read_output(session_id))
|
||
|
||
return session_id
|
||
|
||
async def _read_output(self, session_id: str):
|
||
"""读取 PTY 输出并放入队列"""
|
||
session = self._sessions.get(session_id)
|
||
if not session:
|
||
return
|
||
|
||
queue = self._output_queues[session_id]
|
||
|
||
while True:
|
||
line = await session.process.stdout.readline()
|
||
if not line:
|
||
break
|
||
await queue.put(line.decode())
|
||
|
||
# 同时推送给所有订阅者
|
||
await self._broadcast(session_id, line.decode())
|
||
|
||
await queue.put(None) # 结束标记
|
||
|
||
async def write(self, session_id: str, data: str):
|
||
"""写入 PTY（用户输入）"""
|
||
session = self._sessions.get(session_id)
|
||
if session and session.process.stdin:
|
||
session.process.stdin.write(data)
|
||
await session.process.stdin.drain()
|
||
|
||
async def read(self, session_id: str) -> AsyncGenerator[str, None]:
|
||
"""读取 PTY 输出"""
|
||
queue = self._output_queues.get(session_id)
|
||
if not queue:
|
||
return
|
||
|
||
while True:
|
||
line = await queue.get()
|
||
if line is None:
|
||
break
|
||
yield line
|
||
|
||
async def resize(self, session_id: str, rows: int, cols: int):
|
||
"""调整终端大小"""
|
||
# TODO: 实现 resize
|
||
pass
|
||
|
||
async def kill(self, session_id: str):
|
||
"""终止 PTY 会话"""
|
||
if session_id in self._sessions:
|
||
session = self._sessions[session_id]
|
||
session.process.terminate()
|
||
await session.process.wait()
|
||
del self._sessions[session_id]
|
||
del self._output_queues[session_id]
|
||
|
||
async def _broadcast(self, session_id: str, data: str):
|
||
"""广播输出到 WebSocket"""
|
||
# 实际推送由 router 层处理
|
||
pass
|
||
```
|
||
|
||
### 2.2 WebSocket 端点
|
||
|
||
**新文件**: `backend/app/routers/terminal.py`
|
||
|
||
```python
|
||
from fastapi import APIRouter, WebSocket, WebSocketDisconnect
|
||
from typing import dict
|
||
|
||
router = APIRouter(prefix="/ws/terminal", tags=["terminal"])
|
||
|
||
class ConnectionManager:
|
||
def __init__(self):
|
||
self.active_connections: dict[str, WebSocket] = {}
|
||
|
||
async def connect(self, session_id: str, websocket: WebSocket):
|
||
await websocket.accept()
|
||
self.active_connections[session_id] = websocket
|
||
|
||
def disconnect(self, session_id: str):
|
||
if session_id in self.active_connections:
|
||
del self.active_connections[session_id]
|
||
|
||
async def send(self, session_id: str, data: str):
|
||
if session_id in self.active_connections:
|
||
await self.active_connections[session_id].send_text(data)
|
||
|
||
manager = ConnectionManager()
|
||
|
||
@router.websocket("/{session_id}")
|
||
async def terminal_websocket(websocket: WebSocket, session_id: str):
|
||
await manager.connect(session_id, websocket)
|
||
|
||
# 获取 PTY Manager 实例
|
||
from app.agents.tools.terminal_engine import pty_manager
|
||
|
||
try:
|
||
# 订阅该 session 的输出
|
||
queue = pty_manager._output_queues.get(session_id)
|
||
if queue:
|
||
while True:
|
||
data = await websocket.receive_text()
|
||
# 接收用户输入
|
||
await pty_manager.write(session_id, data + "\n")
|
||
|
||
except WebSocketDisconnect:
|
||
manager.disconnect(session_id)
|
||
```
|
||
|
||
### 2.3 流式输出集成
|
||
|
||
**新文件**: `backend/app/agents/tools/stream_output.py`
|
||
|
||
```python
|
||
import json
|
||
from typing import AsyncGenerator
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class StreamEvent:
|
||
type: str # "output" | "error" | "status" | "complete"
|
||
session_id: str
|
||
data: str
|
||
timestamp: str
|
||
|
||
class StreamOutput:
|
||
def __init__(self, session_id: str, websocket_sender):
|
||
self.session_id = session_id
|
||
self.websocket_sender = websocket_sender
|
||
|
||
async def push(self, event_type: str, data: str):
|
||
"""推送事件到 WebSocket"""
|
||
event = StreamEvent(
|
||
type=event_type,
|
||
session_id=self.session_id,
|
||
data=data,
|
||
timestamp=datetime.now().isoformat(),
|
||
)
|
||
await self.websocket_sender(self.session_id, json.dumps(event.__dict__))
|
||
|
||
async def stream_execution(
|
||
self,
|
||
executor,
|
||
prompt: str
|
||
) -> AsyncGenerator[str, None]:
|
||
"""包装执行器，实现流式输出"""
|
||
async for line in executor.execute(prompt):
|
||
await self.push("output", line)
|
||
yield line
|
||
|
||
await self.push("complete", "")
|
||
```
|
||
|
||
### 2.4 交互输入
|
||
|
||
**新文件**: `backend/app/agents/tools/interactive_input.py`
|
||
|
||
```python
|
||
class InteractiveInputHandler:
|
||
def __init__(self, pty_manager: PTYManager):
|
||
self.pty_manager = pty_manager
|
||
self._pending_inputs: dict[str, asyncio.Event] = {}
|
||
|
||
async def wait_for_input(self, session_id: str, prompt: str) -> str:
|
||
"""等待用户输入（如 "y" 确认）"""
|
||
event = asyncio.Event()
|
||
self._pending_inputs[session_id] = event
|
||
|
||
# 发送提示
|
||
from app.routers.terminal import manager
|
||
await manager.send(session_id, f"\n{prompt}\n")
|
||
|
||
# 等待输入完成
|
||
await event.wait()
|
||
del self._pending_inputs[session_id]
|
||
|
||
return self._input_cache.get(session_id, "")
|
||
|
||
async def send_input(self, session_id: str, data: str):
|
||
"""用户发送输入"""
|
||
self._input_cache[session_id] = data
|
||
if session_id in self._pending_inputs:
|
||
self._pending_inputs[session_id].set()
|
||
|
||
# 同时写入 PTY
|
||
await self.pty_manager.write(session_id, data + "\n")
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心文件清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `terminal_engine.py` | 新增 | PTY 终端管理 |
|
||
| `routers/terminal.py` | 新增 | WebSocket 端点 |
|
||
| `stream_output.py` | 新增 | 流式输出封装 |
|
||
| `interactive_input.py` | 新增 | 交互输入处理 |
|
||
|
||
---
|
||
|
||
## 4. 验收标准
|
||
|
||
- [ ] PTY 会话可以启动、读写、终止
|
||
- [ ] WebSocket 可以建立连接并收发消息
|
||
- [ ] 执行输出实时推送到前端
|
||
- [ ] 用户输入可以传递到 PTY
|
||
|
||
---
|
||
|
||
## 5. 依赖关系
|
||
|
||
```
|
||
Phase 3（Agent 集成）
|
||
↓
|
||
本阶段 → Phase 5（前端集成）
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 备注
|
||
|
||
PTY 实现参考了 golutra 的 `src-tauri/src/runtime/pty.rs`：
|
||
- 使用 `portable-pty` 库
|
||
- Windows 路径兼容处理
|
||
- shim 机制用于信号处理
|