pdd-skills 3.0.0

package/lib/vm/tui/components/table.js

@@ -0,0 +1,370 @@
+/**
+ * PDD Visual Manager - 表格组件 (VM-C011)
+ *
+ * 提供灵活的终端表格渲染能力：
+ * - 自动列宽计算
+ * - 多种对齐方式
+ * - 行高亮选择
+ * - 固定表头/表尾
+ * - 文本自动换行
+ * - 多种边框风格
+ *
+ * 纯 Unicode 绘制，零依赖。
+ */
+
+import { ANSI, BORDER_CHARS } from '../renderer.js';
+
+/** 默认对齐方式映射 */
+const DEFAULT_ALIGN = {
+  number: 'right',
+  default: 'left'
+};
+
+/**
+ * Table - 终端表格组件
+ *
+ * 功能丰富的表格渲染器，适用于数据展示场景。
+ */
+class Table {
+  /**
+   * 创建表格实例
+   * @param {string[]} headers - 表头数组
+   * @param {Array<Array<string|number>>} rows - 数据行二维数组
+   * @param {Object} options - 配置选项
+   */
+  constructor(headers = [], rows = [], options = {}) {
+    /** @type {string[]} 表头 */
+    this.headers = headers.map(h => String(h || ''));
+
+    /** @type {Array<Array<string>>} 数据行（已转为字符串） */
+    this.rows = (rows || []).map(row =>
+      (row || []).map(cell => String(cell ?? ''))
+    );
+
+    /** @type {Object} 配置选项 */
+    this.options = {
+      widths: null,            // 指定列宽数组
+      aligns: [],              // 对齐方式数组 ('left'|'right'|'center')
+      highlightRow: -1,        // 高亮行索引 (-1=无)
+      fixedHeader: true,       // 固定表头
+      fixedFooter: false,      // 固定表尾
+      maxWidth: 0,             // 最大表格宽度 (0=不限制)
+      wrapText: false,         // 是否换行文本
+      borderStyle: 'single',   // 边框风格 ('single'|'double'|'rounded')
+      title: '',               // 表格标题
+      footer: null,            // 表尾数据行
+      showRowNumbers: false,   // 显示行号
+      compact: false,          // 紧凑模式（减少内边距）
+      ...options
+    };
+
+    // 计算或使用指定的列宽
+    this._calculateColumnWidths();
+  }
+
+  /**
+   * 计算各列最佳宽度
+   * @private
+   */
+  _calculateColumnWidths() {
+    if (this.options.widths && Array.isArray(this.options.widths)) {
+      this.columnWidths = [...this.options.widths];
+      return;
+    }
+
+    // 初始化为表头宽度
+    this.columnWidths = this.headers.map(h => this._strWidth(h));
+
+    // 考虑每行的内容
+    for (const row of this.rows) {
+      for (let i = 0; i < row.length; i++) {
+        const cellWidth = this._strWidth(row[i]);
+        if (i < this.columnWidths.length) {
+          if (cellWidth > this.columnWidths[i]) {
+            this.columnWidths[i] = cellWidth;
+          }
+        } else {
+          this.columnWidths.push(cellWidth);
+        }
+      }
+    }
+
+    // 最小宽度 3
+    this.columnWidths = this.columnWidths.map(w => Math.max(w, 3));
+  }
+
+  /**
+   * 设置高亮行
+   * @param {number} index - 行索引 (-1 取消高亮)
+   */
+  setHighlight(index) {
+    this.options.highlightRow = index;
+  }
+
+  /**
+   * 渲染完整表格
+   * @returns {string} 格式化的表格字符串
+   */
+  render() {
+    const opts = this.options;
+    const c = BORDER_CHARS[opts.borderStyle] || BORDER_CHARS.single;
+    const widths = this.columnWidths;
+    const aligns = opts.aligns;
+
+    const lines = [];
+
+    // 标题
+    if (opts.title) {
+      lines.push(this._renderTitle(opts.title, widths, c));
+    }
+
+    // 顶边框
+    lines.push(this._makeBorder(c.tl, c.bt, c.tr, widths));
+
+    // 表头
+    lines.push(this._renderHeader(c, widths, aligns));
+
+    // 表头下分隔线
+    lines.push(this._makeBorder(c.lt, c.cross, c.rt, widths));
+
+    // 数据行
+    for (let r = 0; r < this.rows.length; r++) {
+      const isHighlighted = r === opts.highlightRow;
+      lines.push(this._renderDataRow(r, c, widths, aligns, isHighlighted));
+    }
+
+    // 表尾（如果有）
+    if (opts.footer) {
+      lines.push(this._makeBorder(c.lt, c.cross, c.rt, widths));
+      const footerRow = opts.footer.map(f => String(f ?? ''));
+      lines.push(this._renderCells(footerRow, c, widths, aligns, false));
+    }
+
+    // 底边框
+    lines.push(this._makeBorder(c.bl, c.bb, c.br, widths));
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 渲染紧凑版表格（无左右边框线）
+   * @returns {string}
+   */
+  renderCompact() {
+    const widths = this.columnWidths;
+    const aligns = this.options.aligns;
+    const lines = [];
+
+    // 表头
+    const headerCells = this.headers.map((h, i) =>
+      this._pad(String(h), widths[i], aligns[i] || 'left')
+    );
+    lines.push(headerCells.join('  '));
+
+    // 分隔线
+    lines.push(widths.map(w => '─'.repeat(w)).join('  '));
+
+    // 数据行
+    for (let r = 0; r < this.rows.length; r++) {
+      const cells = this.rows[r].map((cell, i) =>
+        this._pad(String(cell), widths[i], aligns[i] || 'left')
+      );
+      lines.push(cells.join('  '));
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 渲染标题行
+   * @param {string} title - 标题文本
+   * @param {number[]} widths - 列宽数组
+   * @param {Object} c - 边框字符
+   * @returns {string}
+   * @private
+   */
+  _renderTitle(title, widths, c) {
+    const totalWidth = widths.reduce((sum, w) => sum + w + 1, 0) + 1;
+    const titleStr = ` ${title} `;
+    const padding = Math.max(0, totalWidth - this._strWidth(titleStr) - 2);
+    const leftPad = Math.floor(padding / 2);
+    const rightPad = padding - leftPad;
+
+    return `${c.tl}─${' '.repeat(leftPad)}${titleStr}${' '.repeat(rightPad)}─${c.tr}`;
+  }
+
+  /**
+   * 渲染表头行
+   * @param {Object} c - 边框字符
+   * @param {number[]} widths - 列宽
+   * @param {string[]} aligns - 对齐方式
+   * @returns {string}
+   * @private
+   */
+  _renderHeader(c, widths, aligns) {
+    const cells = this.headers.map((h, i) => {
+      const padded = this._pad(String(h), widths[i], aligns[i] || 'center');
+      return ANSI.BOLD + padded + ANSI.RESET;
+    });
+
+    return this._joinRow(cells, c.v);
+  }
+
+  /**
+   * 渲染数据行
+   * @param {number} rowIndex - 行索引
+   * @param {Object} c - 边框字符
+   * @param {number[]} widths - 列宽
+   * @param {string[]} aligns - 对齐方式
+   * @param {boolean} highlighted - 是否高亮
+   * @returns {string}
+   * @private
+   */
+  _renderDataRow(rowIndex, c, widths, aligns, highlighted) {
+    const row = this.rows[rowIndex] || [];
+    const line = this._renderCells(row, c, widths, aligns, highlighted);
+
+    // 可选的行号前缀
+    if (this.options.showRowNumbers) {
+      const numStr = String(rowIndex + 1).padStart(3);
+      const prefix = highlighted
+        ? `${ANSI.REVERSE} ${numStr} ${ANSI.RESET}`
+        : ` ${ANSI.DIM}${numStr}${ANSI.RESET} `;
+      return prefix + line;
+    }
+
+    return line;
+  }
+
+  /**
+   * 渲染单元格
+   * @param {string[]} cells - 单元格数据
+   * @param {Object} c - 边框字符
+   * @param {number[]} widths - 列宽
+   * @param {string[]} aligns - 对齐方式
+   * @param {boolean} highlighted - 是否高亮
+   * @returns {string}
+   * @private
+   */
+  _renderCells(cells, c, widths, aligns, highlighted) {
+    const padded = cells.map((cell, i) => {
+      const w = i < widths.length ? widths[i] : 10;
+      const align = (aligns && aligns[i]) || 'left';
+      return this._pad(String(cell), w, align);
+    });
+
+    const rowStr = this._joinRow(padded, c.v);
+    return highlighted ? ANSI.REVERSE + rowStr + ANSI.RESET : rowStr;
+  }
+
+  /**
+   * 生成边框线
+   * @param {string} left - 左角字符
+   * @param {string} mid - 中间分隔字符
+   * @param {string} right - 右角字符
+   * @param {number[]} widths - 列宽数组
+   * @returns {string}
+   * @private
+   */
+  _makeBorder(left, mid, right, widths) {
+    return left + widths.map(w => (mid === '─' || mid === '═' ? mid : '─').repeat(w)).join(mid) + right;
+  }
+
+  /**
+   * 连接一行单元格
+   * @param {string[]} cells - 已填充的单元格
+   * @param {string} sep - 分隔符
+   * @returns {string}
+   * @private
+   */
+  _joinRow(cells, sep) {
+    return sep + ' ' + cells.join(' ' + sep + ' ') + ' ' + sep;
+  }
+
+  /**
+   * 文本填充到指定宽度
+   * @param {string} text - 文本
+   * @param {number} width - 目标宽度
+   * @param {string} align - 对齐方式
+   * @returns {string}
+   * @private
+   */
+  _pad(text, width, align = 'left') {
+    const displayLen = this._strWidth(text);
+    if (displayLen >= width) {
+      return this._truncate(text, width);
+    }
+    const pad = width - displayLen;
+    switch (align) {
+      case 'right':
+        return ' '.repeat(pad) + text;
+      case 'center':
+        return ' '.repeat(Math.floor(pad / 2)) + text + ' '.repeat(Math.ceil(pad / 2));
+      default:
+        return text + ' '.repeat(pad);
+    }
+  }
+
+  /**
+   * 截断文本
+   * @param {string} text - 文本
+   * @param {number} maxLen - 最大宽度
+   * @returns {string}
+   * @private
+   */
+  _truncate(text, maxLen) {
+    if (this._strWidth(text) <= maxLen) return text;
+    let result = '';
+    let currentW = 0;
+    for (const ch of text) {
+      const cw = this._strWidth(ch);
+      if (currentW + cw > maxLen - 1) break;
+      result += ch;
+      currentW += cw;
+    }
+    return result + '…';
+  }
+
+  /**
+   * 计算字符串显示宽度
+   * @param {string} text
+   * @returns {number}
+   * @private
+   */
+  _strWidth(text) {
+    let w = 0;
+    for (const ch of String(text)) {
+      w += ch.charCodeAt(0) > 0xff ? 2 : 1;
+    }
+    return w;
+  }
+
+  /**
+   * 快速创建简单表格的静态工厂方法
+   * @param {string[]} headers - 表头
+   * @param {Array<Array>} rows - 数据行
+   * @param {Object} options - 选项
+   * @returns {string} 渲染结果
+   */
+  static quick(headers, rows, options = {}) {
+    const table = new Table(headers, rows, options);
+    return table.render();
+  }
+
+  /**
+   * 创建键值对信息表（两列布局）
+   * @param {Array<[string, string]>} data - 键值对数组
+   * @param {Object} options - 选项
+   * @returns {string}
+   */
+  static keyValue(data, options = {}) {
+    const headers = options.headers || ['属性', '值'];
+    const rows = data.map(([label, value]) => [label, String(value ?? '')]);
+    return new Table(headers, rows, {
+      ...options,
+      aligns: ['left', 'left']
+    }).render();
+  }
+}
+
+export default Table;

package/lib/vm/tui/input.js

@@ -0,0 +1,335 @@
+/**
+ * PDD Visual Manager - 键盘输入处理器 (VM-C003)
+ *
+ * 处理终端原始键盘输入，支持：
+ * - Raw mode 模式捕获所有按键
+ * - 特殊键解析（方向键、Ctrl组合键、功能键等）
+ * - 终端 resize 事件监听
+ * - 可插拔的按键回调机制
+ *
+ * 纯 Node.js 内置模块实现，零外部依赖。
+ */
+
+import readline from 'readline';
+
+/**
+ * 特殊按键映射表
+ * 将原始字节序列映射为标准按键名称
+ */
+const KEY_MAP = {
+  // 控制键
+  '\x03': 'ctrl_c',       // Ctrl+C
+  '\x04': 'ctrl_d',       // Ctrl+D
+  '\x08': 'ctrl_h',       // Ctrl+H (Backspace)
+  '\x09': 'tab',          // Tab
+  '\x0a': 'enter',        // Enter (LF)
+  '\x0d': 'return',       // Return (CR)
+  '\x7f': 'backspace',    // Backspace
+  '\x1b': 'escape',       // Esc (单个)
+
+  // ESC 序列 - 光标键
+  '\x1b[A': 'up',
+  '\x1b[B': 'down',
+  '\x1b[C': 'right',
+  '\x1b[D': 'left',
+
+  // ESC 序列 - 功能/编辑键
+  '\x1b[F': 'end',
+  '\x1b[H': 'home',
+  '\x1b[2~': 'insert',
+  '\x1b[3~': 'delete',
+  '\x1b[5~': 'pageup',
+  '\x1b[6~': 'pagedown',
+
+  // Shift + 方向键
+  '\x1b[a': 'shift_up',
+  '\x1b[b': 'shift_down',
+  '\x1b[c': 'shift_right',
+  '\x1b[d': 'shift_left',
+
+  // Ctrl + 方向键
+  '\x1b[1;5A': 'ctrl_up',
+  '\x1b[1;5B': 'ctrl_down',
+  '\x1b[1;5C': 'ctrl_right',
+  '\x1b[1;5D': 'ctrl_left',
+
+  // Shift+Tab
+  '\x1b[Z': 'shift_tab',
+
+  // F1-F12
+  '\x1bOP': 'f1',
+  '\x1bOQ': 'f2',
+  '\x1bOR': 'f3',
+  '\x1bOS': 'f4',
+  '\x1b[15~': 'f5',
+  '\x1b[17~': 'f6',
+  '\x1b[18~': 'f7',
+  '\x1b[19~': 'f8',
+  '\x1b[20~': 'f9',
+  '\x1b[21~': 'f10',
+  '\x1b[23~': 'f11',
+  '\x1b[24~': 'f12'
+};
+
+/**
+ * InputHandler - 键盘输入处理器
+ *
+ * 管理 raw mode 终端输入，将原始字节流转换为结构化按键事件。
+ *
+ * 使用方式:
+ * ```js
+ * const handler = new InputHandler((key) => {
+ *   console.log('Key pressed:', key.name);
+ * });
+ * handler.setup();
+ * // ... 使用后 ...
+ * handler.teardown();
+ * ```
+ */
+class InputHandler {
+  /**
+   * 创建输入处理器
+   * @param {Function} onKeyPress - 按键回调函数，接收 { name, char, raw } 对象
+   */
+  constructor(onKeyPress = null) {
+    /** @type {Function|null} 按键回调 */
+    this.onKeyPress = onKeyPress;
+
+    /** @type {readline.Interface|null} readline 接口 */
+    this.rl = null;
+
+    /** @type {string} 输入缓冲区（用于多字节序列） */
+    this.buffer = '';
+
+    /** @type {boolean} 是否已激活 */
+    this.active = false;
+
+    /** @type {boolean} 是否已设置 raw mode */
+    this.rawModeSet = false;
+  }
+
+  /**
+   * 初始化输入处理器
+   * 设置 raw mode 和事件监听
+   */
+  setup() {
+    if (this.active) return;
+
+    // 创建 readline 接口（保持 stdin 引用活跃）
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+      prompt: ''
+    });
+
+    // 启用 raw mode 以捕获所有按键
+    try {
+      process.stdin.setRawMode(true);
+      this.rawModeSet = true;
+    } catch (e) {
+      console.error('[TUI] Warning: Cannot set raw mode:', e.message);
+    }
+
+    // 确保 stdin 处于 flowing mode
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    // 监听数据输入
+    process.stdin.on('data', (chunk) => {
+      this._handleChunk(chunk);
+    });
+
+    // 监听终端尺寸变化
+    process.stdout.on('resize', () => {
+      if (this.onKeyPress) {
+        this.onKeyPress({
+          name: 'resize',
+          char: '',
+          raw: 'resize',
+          columns: process.stdout.columns,
+          rows: process.stdout.rows
+        });
+      }
+    });
+
+    this.active = true;
+  }
+
+  /**
+   * 处理输入数据块
+   * @param {Buffer|string} chunk - 输入数据
+   * @private
+   */
+  _handleChunk(chunk) {
+    const data = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    this.buffer += data;
+
+    // 尝试从缓冲区提取完整的按键
+    while (this.buffer.length > 0) {
+      const key = this._parseNextKey();
+      if (!key) break; // 需要更多数据
+
+      if (this.onKeyPress) {
+        try {
+          this.onKeyPress(key);
+        } catch (e) {
+          console.error('[TUI] Key handler error:', e.message);
+        }
+      }
+    }
+  }
+
+  /**
+   * 从缓冲区解析下一个完整按键
+   * @returns {Object|null} 按键对象或 null（需要更多数据）
+   * @private
+   */
+  _parseNextKey() {
+    const buf = this.buffer;
+
+    // 直接查找已知按键序列（优先匹配长序列）
+    for (const len = Math.min(buf.length, 10); len > 0; len--) {
+      const seq = buf.substring(0, len);
+      if (KEY_MAP.hasOwnProperty(seq)) {
+        this.buffer = buf.substring(len);
+        return {
+          name: KEY_MAP[seq],
+          char: seq,
+          raw: seq
+        };
+      }
+    }
+
+    // 单个可打印字符
+    if (buf.length >= 1) {
+      const first = buf.charCodeAt(0);
+
+      // Esc 键特殊处理：如果是单独的 \x1b 且后面没有跟其他字符
+      // 这里我们采用简单策略：如果第一个是 \x1b 且不在已知序列中，
+      // 先等待一下看是否有后续字符。但为了简化，直接返回 escape
+      if (first === 0x1b) {
+        // 如果是单独的 esc 或未知转义序列
+        if (buf.length === 1 || buf[1] !== '[' && buf[1] !== 'O') {
+          this.buffer = buf.substring(1);
+          return { name: 'escape', char: '\x1b', raw: '\x1b' };
+        }
+        // CSI 序列，继续收集
+        if (buf[1] === '[' || buf[1] === 'O') {
+          // 等待完整序列 - 简单处理：最多等待 6 个字符
+          if (buf.length < 3) return null; // 需要更多数据
+
+          // 尝试匹配已知的 CSI 序列
+          const csiEnd = this._findCSIEnd(buf);
+          if (csiEnd > 0) {
+            const seq = buf.substring(0, csiEnd);
+            this.buffer = buf.substring(csiEnd);
+            const knownName = KEY_MAP[seq];
+            return {
+              name: knownName || 'unknown_csi',
+              char: seq,
+              raw: seq
+            };
+          }
+          // 如果还没结束且缓冲区不够长，等待更多数据
+          if (buf.length < 7) return null;
+          // 超过合理长度，当作未知序列消费掉
+          this.buffer = buf.substring(1);
+          return { name: 'unknown_sequence', char: buf[0], raw: buf[0] };
+        }
+      }
+
+      // 可打印 ASCII 字符 (32-126)
+      if (first >= 32 && first <= 126) {
+        this.buffer = buf.substring(1);
+        const char = buf[0];
+        return {
+          name: char,
+          char: char,
+          raw: char
+        };
+      }
+
+      // 其他控制字符，跳过
+      this.buffer = buf.substring(1);
+      return {
+        name: 'control',
+        char: String.fromCharCode(first),
+        raw: buf[0]
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * 查找 CSI 序列的结束位置
+   * @param {string} buf - 缓冲区
+   * @returns {number} CSI 序列结束位置（不包含），0 表示未找到
+   * @private
+   */
+  _findCSIEnd(buf) {
+    // CSI 序列格式: ESC [ 参数(可选) 中间符(可选) 最终字节
+    // 最终字节通常是 0x40-0x7E 范围内的可打印字符
+    let i = 2; // 跳过 ESC [
+    while (i < buf.length) {
+      const code = buf.charCodeAt(i);
+      // 参数: 0x30-0x3F (0-9:;<=>?)
+      // 中间符: 0x20-0x2F (空格!"#$%&'()*+,-./)
+      // 最终字节: 0x40-0x7E (@A-Z[\]^_`a-z{|}~)
+      if (code >= 0x40 && code <= 0x7e) {
+        return i + 1;
+      }
+      i++;
+    }
+    return 0;
+  }
+
+  /**
+   * 清理资源，恢复终端状态
+   */
+  teardown() {
+    if (!this.active) return;
+
+    // 恢复正常模式
+    if (this.rawModeSet) {
+      try {
+        process.stdin.setRawMode(false);
+      } catch (e) {
+        // 忽略错误
+      }
+      this.rawModeSet = false;
+    }
+
+    // 暂停 stdin
+    try {
+      process.stdin.pause();
+    } catch (e) {
+      // 忽略
+    }
+
+    // 关闭 readline
+    if (this.rl) {
+      try {
+        this.rl.close();
+      } catch (e) {
+        // 忽略
+      }
+      this.rl = null;
+    }
+
+    this.active = false;
+    this.buffer = '';
+  }
+
+  /**
+   * 检查是否处于活跃状态
+   * @returns {boolean}
+   */
+  get isActive() {
+    return this.active;
+  }
+}
+
+export default InputHandler;
+export { KEY_MAP };