第十五章　终端系统：PTY 与 Claude 集成

// apps/frontend/src/main/terminal/pty-daemon.ts（简化）

interface DaemonMessage {
  type:
    | 'create'    // 创建新 PTY
    | 'write'     // 向 PTY 写入数据（键盘输入）
    | 'resize'    // 调整窗口大小
    | 'kill'      // 终止 PTY
    | 'subscribe' // 订阅 PTY 输出
    | 'get-buffer'// 获取历史缓冲区
    | 'ping';     // 心跳检测
  id?: string;     // PTY 标识符
  data?: unknown;  // 消息体（create 时是 PtyConfig，write 时是字符串）
  requestId?: string; // 用于请求-响应配对
}

// 接收消息的方式：读取换行分隔的 JSON
socket.on('data', (chunk) => {
  buffer += chunk.toString('utf-8');
  const lines = buffer.split('\n');
  buffer = lines.pop() || ''; // 最后一段可能不完整，保留

  for (const line of lines) {
    if (!line.trim()) continue;
    const msg: DaemonMessage = JSON.parse(line);
    this.handleMessage(socket, msg);
  }
});

const SOCKET_PATH = isWindows()
  ? `\\\\.\\pipe\\auto-claude-pty-${process.getuid?.() || 'default'}`
  : `/tmp/auto-claude-pty-${process.getuid?.() || 'default'}.sock`;

interface ManagedPty {
  id: string;
  process: pty.IPty;    // 实际的 PTY 进程引用
  config: PtyConfig;    // 创建配置（shell、工作目录等）
  buffer: string[];     // 环形输出缓冲区
  bufferSize: number;   // 当前缓冲区总字节数
  clients: Set<net.Socket>; // 订阅此 PTY 的所有连接
  createdAt: number;
  lastDataAt: number;   // 最后收到数据的时间（用于存活检测）
  isDead: boolean;
}

// 最大缓冲区：100KB
const MAX_BUFFER_SIZE = 100_000;
// 最大缓冲块数：1000 块
const RING_BUFFER_MAX_CHUNKS = 1000;

ptyProcess.onData((data) => {
  managed.lastDataAt = Date.now();

  // 追加到环形缓冲区
  managed.buffer.push(data);
  managed.bufferSize += data.length;

  // 超出上限时，从头部移除旧数据（FIFO 淘汰）
  while (managed.bufferSize > MAX_BUFFER_SIZE && managed.buffer.length > 1) {
    const removed = managed.buffer.shift();
    if (removed) {
      managed.bufferSize -= removed.length;
    }
  }

  // 广播给所有订阅者
  for (const client of managed.clients) {
    this.send(client, { type: 'data', id: managed.id, data });
  }
});

private createPty(config: PtyConfig): string {
  if (this.isShuttingDown) {
    throw new Error('Cannot create PTY: daemon is shutting down');
  }

  // 时间戳 + 随机后缀：避免碰撞，人类可读
  const id = `pty-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;

  const ptyProcess = pty.spawn(config.shell, config.shellArgs, {
    name: 'xterm-256color',  // 声明终端类型，影响颜色和功能支持
    cols: config.cols,
    rows: config.rows,
    cwd: config.cwd,
    env: config.env,
  });

  // ...注册 onData/onExit 处理器
}

// 模块级变量，不使用类状态
let isShuttingDown = false;

export function setShuttingDown(value: boolean): void {
  isShuttingDown = value;
}

ptyProcess.onData((data) => {
  if (isShuttingDown) return; // 应用正在关闭，静默丢弃
  window.webContents.send(IPC_CHANNELS.TERMINAL_OUTPUT, data);
});

// Windows 需要更长的等待时间
const PTY_EXIT_TIMEOUT_WINDOWS = 2000;  // 2 秒
const PTY_EXIT_TIMEOUT_UNIX = 500;       // 500 毫秒

// 认证终端的 ID 格式：claude-login-{profileId}-{timestamp}
const AUTH_TERMINAL_ID_PATTERN = /^claude-login-([a-z0-9-]+)-(\d{13,})$/;

function extractProfileIdFromAuthTerminalId(terminalId: string): string | null {
  const match = terminalId.match(AUTH_TERMINAL_ID_PATTERN);
  return match ? match[1] : null;
}

function maskEmail(email: string): string {
  // 'john.doe@example.com' → 'j***@e***.com'
  const [local, domain] = email.split('@');
  if (!domain) return '***';
  const domainParts = domain.split('.');
  const maskedLocal = local[0] + '***';
  const maskedDomain = domainParts[0][0] + '***.' + domainParts.slice(1).join('.');
  return `${maskedLocal}@${maskedDomain}`;
}

// 存储位置：Electron userData 目录（跨平台）
const SESSIONS_FILE = path.join(app.getPath('userData'), 'terminal-sessions.json');
const BUFFERS_DIR = path.join(app.getPath('userData'), 'terminal-buffers');

// 会话过期时间：7 天
const MAX_SESSION_AGE_MS = 7 * 24 * 60 * 60 * 1000;

loadSessions(): TerminalSessionState[] {
  const data: TerminalSessionsFile = JSON.parse(
    fs.readFileSync(SESSIONS_FILE, 'utf8')
  );

  // 版本检查：文件格式变更时必须重置
  if (data.version !== 2) {
    console.warn('[SessionPersistence] Incompatible version, starting fresh');
    return [];
  }

  // 过滤过期会话
  const now = Date.now();
  return data.sessions.filter(
    (s) => now - s.lastActiveAt < MAX_SESSION_AGE_MS
  );
}

// lab15/ring-buffer.ts

export class RingBuffer {
  private chunks: string[] = [];
  private totalSize: number = 0;
  private readonly maxSize: number;

  constructor(maxSizeBytes: number = 100_000) {
    this.maxSize = maxSizeBytes;
  }

  /**
   * 追加数据，超出上限时从头部淘汰旧数据
   */
  append(data: string): void {
    // TODO Part A: 追加数据到 chunks
    // 当 totalSize > maxSize 且 chunks.length > 1 时，从头部移除
    // 注意：至少保留 1 块，即使单块超过 maxSize
  }

  /**
   * 获取所有缓冲内容（拼接）
   */
  getAll(): string {
    // TODO Part A: 拼接所有 chunks 返回
    return '';
  }

  /**
   * 获取当前字节数
   */
  getSize(): number {
    return this.totalSize;
  }

  /**
   * 清空缓冲区
   */
  clear(): void {
    // TODO Part A
  }
}

// 验证：
const buf = new RingBuffer(10); // 10 字节上限
buf.append('Hello');  // 5 字节
buf.append('World');  // 5 字节，总 10 字节（刚好）
buf.append('!!!');    // 超出，应淘汰 'Hello'
console.log(buf.getAll()); // → 'World!!!'（或类似，取决于实现）
console.log(buf.getSize()); // ≤ 10

// lab15/pty-session.ts
import { EventEmitter } from 'events';

export class PtySession {
  private id: string;
  private subscribers: Set<(data: string) => void> = new Set();
  private buffer: RingBuffer;
  private emitter: EventEmitter;

  constructor(id: string) {
    this.id = id;
    this.buffer = new RingBuffer();
    this.emitter = new EventEmitter();
  }

  /**
   * 订阅输出，返回取消订阅函数
   * 新订阅者会立即收到历史缓冲区内容
   */
  subscribe(callback: (data: string) => void): () => void {
    // TODO Part B:
    // 1. 立即发送历史缓冲（如果非空）
    // 2. 注册到 subscribers Set
    // 3. 返回取消函数（从 Set 中移除）
    return () => {};
  }

  /**
   * 模拟 PTY 输出：写入缓冲并广播给所有订阅者
   */
  receive(data: string): void {
    // TODO Part B:
    // 1. 追加到 buffer
    // 2. 广播给所有 subscribers
  }
}

// 验证：
const session = new PtySession('test-pty');
session.receive('历史输出\n');

const received: string[] = [];
const cancel = session.subscribe(data => received.push(data));

// 新订阅者应立即收到历史内容
console.log(received[0]); // → '历史输出\n'

session.receive('新输出\n');
console.log(received[1]); // → '新输出\n'

cancel(); // 取消订阅
session.receive('取消后\n');
console.log(received.length); // → 2（取消后不再收到）

// lab15/ndjson-parser.ts

export class NdJsonParser {
  private buffer: string = '';

  /**
   * 处理流式数据块，返回解析出的完整消息列表
   * 换行符作为消息分隔符，不完整的消息保留在内部缓冲
   */
  feed(chunk: string): unknown[] {
    // TODO Part C:
    // 1. 追加到 buffer
    // 2. 按 '\n' 分割
    // 3. 最后一段（可能不完整）保留在 buffer
    // 4. 对每个完整行尝试 JSON.parse，失败则跳过
    return [];
  }
}

// 验证：
const parser = new NdJsonParser();

// 分两次收到，第一次不完整
let msgs = parser.feed('{"type":"ping"}\n{"type":"cr');
console.log(msgs.length); // → 1（只有第一条完整）
console.log((msgs[0] as any).type); // → 'ping'

// 第二次完成第二条消息
msgs = parser.feed('eate","id":"pty-1"}\n');
console.log(msgs.length); // → 1
console.log((msgs[0] as any).type); // → 'create'