pty-architecture
PTY-based multi-session architecture for Code Quest. Covers three-layer design, node-pty spawn config, and worktree isolation. Use when implementing or modifying session management, PTY spawning, or terminal integration.
来源信息
- 仓库
- recca0120/code-quest
- 最近来源活动
- 2026年3月28日 13:24
- 检测到的 SKILL.md 语言
- 英语
- 星标
- 11
- 分支
- 2
安装方式
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
检查来源文件
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
正在显示 SKILL.md
SKILL.md
来源说明 · 只读预览- name
- pty-architecture
- description
- PTY-based multi-session architecture for Code Quest. Covers three-layer design, node-pty spawn config, and worktree isolation. Use when implementing or modifying session management, PTY spawning, or terminal integration.
# PTY Architecture
## Three-Layer Design
```
React UI (xterm.js) ←→ Socket.IO ←→ Battle Server (node-pty) ←→ Claude CLI
```
- **UI Layer**: xterm.js renders terminal output, Socket.IO for real-time events
- **Server Layer**: BattleBridge manages PTY sessions, OutputParser converts stream-json to events
- **CLI Layer**: Each session = independent PTY process running Claude CLI
## Key Design Decisions
### Why node-pty over child_process.spawn?
| Feature | node-pty | child_process |
|---------|----------|---------------|
| ANSI colors | Full support | Claude disables colors |
| Terminal resize | `pty.resize()` | Not supported |
| Session isolation | Simple per-process | Complex |
### PTY Spawn Config
```typescript
spawn(command, args, {
name: 'xterm-256color',
cols: 120, rows: 30,
cwd: workingDir,
env: { ...process.env, TERM: 'xterm-256color', FORCE_COLOR: '1', COLORTERM: 'truecolor' }
});
```
### Circular Buffer (10KB)
Output buffer capped at 10KB, sliced to last 5KB on overflow. Prevents memory leaks in long sessions while keeping recent output for late-joining viewers.
### Graceful Shutdown
SIGTERM → wait 5s → SIGKILL. Allows CLI to save state before forced termination.
### Worktree Isolation
Worktree battles use isolated `cwd` paths (e.g., `/worktrees/feature-branch`), preventing concurrent sessions from conflicting on the same working directory.
## Troubleshooting
- **`posix_spawnp failed`**: `chmod +x node_modules/node-pty/build/Release/spawn-helper`
- **No ANSI colors**: Ensure `TERM=xterm-256color` and `FORCE_COLOR=1` in env
- **Zombie process**: Use SIGTERM→SIGKILL pattern with 5s timeout
在 GitHub 查看