ysagc-agent 0.1.0

package/src/methods/skill.js

@@ -0,0 +1,347 @@
+/**
+ * skill.* RPC 方法（T-M1-17，需求 5.22 Skills 技能安装）
+ * - skill.list / skill.install / skill.uninstall / skill.setEnabled / skill.detail / skill.context
+ * - 技能目录：<配置目录>/skills/<name>/SKILL.md（frontmatter + 正文）
+ * - 启停状态：<配置目录>/skills/.state.json
+ * - 市场安装：Agent 直连后端下载 raw（ticket 一次性票据）→ 校验 → 写入
+ * - 本地导入：复制本机文件夹 → 校验
+ * - 安全：SKILL.md 大小 ≤8K 字符、技能名白名单 [a-z0-9-]、安装/卸载/启停记审计
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const https = require('https');
+const { RpcError } = require('../rpc');
+const { CONFIG_DIR } = require('../config');
+const logger = require('../logger');
+
+const SKILLS_ROOT = path.join(CONFIG_DIR, 'skills');
+const STATE_FILE = path.join(SKILLS_ROOT, '.state.json');
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_BODY_CHARS = 8000; // SKILL.md 正文 ≤ 8K 字符
+const MAX_FILES = 50;
+const MAX_TOTAL_BYTES = 10 * 1024 * 1024; // 技能包 ≤ 10MB
+
+function ensureRoot() {
+  fs.mkdirSync(SKILLS_ROOT, { recursive: true });
+  return SKILLS_ROOT;
+}
+
+function stateFile() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveState(state) {
+  try {
+    ensureRoot();
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+  } catch (e) {
+    logger.warn(`[skill] 状态保存失败: ${e.message}`);
+  }
+}
+
+/** 解析 SKILL.md：frontmatter + 正文 */
+function parseSkillDoc(content) {
+  const m = String(content || '').match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+  if (!m) return null;
+  const meta = {};
+  for (const line of m[1].split('\n')) {
+    const kv = line.match(/^([a-zA-Z_]+):\s*(.*)$/);
+    if (kv) {
+      let v = kv[2].trim();
+      if (v.startsWith('[') && v.endsWith(']')) {
+        v = v.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
+      }
+      meta[kv[1]] = v;
+    }
+  }
+  const name = String(meta.name || '').trim();
+  if (!NAME_RE.test(name)) return null;
+  const body = m[2].trim();
+  if (body.length > MAX_BODY_CHARS) return null;
+  return {
+    name,
+    description: String(meta.description || '').slice(0, 200),
+    version: String(meta.version || '1.0.0'),
+    author: String(meta.author || ''),
+    tags: Array.isArray(meta.tags) ? meta.tags : [],
+    body,
+  };
+}
+
+function readSkillInfo(dir) {
+  const p = path.join(dir, 'SKILL.md');
+  if (!fs.existsSync(p)) return null;
+  let content;
+  try {
+    content = fs.readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+  const parsed = parseSkillDoc(content);
+  if (!parsed) return null;
+  const st = stateFile();
+  return {
+    name: parsed.name,
+    description: parsed.description,
+    version: parsed.version,
+    author: parsed.author,
+    tags: parsed.tags,
+    enabled: st[parsed.name] === undefined ? true : !!st[parsed.name],
+    installedAt: (() => {
+      try {
+        return new Date(fs.statSync(dir).birthtimeMs).toISOString();
+      } catch {
+        return null;
+      }
+    })(),
+  };
+}
+
+/** 校验技能目录：路径穿越、大小、文件数 */
+function validateSkillDir(root, name) {
+  const errors = [];
+  let fileCount = 0;
+  let totalBytes = 0;
+  const walk = (dir, relBase) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      errors.push(`无法读取目录 ${relBase}`);
+      return;
+    }
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      const rel = relBase ? `${relBase}/${e.name}` : e.name;
+      if (rel.includes('..') || rel.startsWith('/')) {
+        errors.push(`非法路径: ${rel}`);
+        continue;
+      }
+      if (e.isDirectory()) walk(abs, rel);
+      else if (e.isFile()) {
+        fileCount++;
+        totalBytes += fs.statSync(abs).size;
+      }
+    }
+  };
+  walk(root, '');
+  if (fileCount > MAX_FILES) errors.push(`文件数超限（>${MAX_FILES}）`);
+  if (totalBytes > MAX_TOTAL_BYTES) errors.push(`体积超限（>10MB）`);
+  return { ok: errors.length === 0, errors, fileCount, totalBytes };
+}
+
+/** 获取技能目录下的所有文件（相对路径 → 内容），供市场安装落地用 */
+function readSkillFiles(dir) {
+  const out = [];
+  const walk = (d, relBase) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const abs = path.join(d, e.name);
+      const rel = relBase ? `${relBase}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(abs, rel);
+      else if (e.isFile()) out.push({ relPath: rel, content: fs.readFileSync(abs, 'utf8') });
+    }
+  };
+  walk(dir, '');
+  return out;
+}
+
+/** 写技能文件（含路径穿越校验） */
+function writeSkillFiles(name, files) {
+  const root = path.join(SKILLS_ROOT, name);
+  ensureRoot();
+  if (fs.existsSync(root)) throw new RpcError('E_SKILL_EXISTS', `技能 ${name} 已安装`);
+  for (const f of files) {
+    const rel = String(f.relPath || '');
+    if (!rel || rel.includes('..') || rel.startsWith('/') || rel.includes('\\')) {
+      throw new RpcError('E_SKILL_INVALID', `非法文件路径: ${rel}`);
+    }
+  }
+  fs.mkdirSync(root, { recursive: true });
+  try {
+    for (const f of files) {
+      const abs = path.join(root, f.relPath);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, String(f.content ?? ''));
+    }
+  } catch (e) {
+    // 失败回滚
+    try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* ignore */ }
+    throw new RpcError('E_SKILL_INVALID', `写入失败: ${e.message}`);
+  }
+  return root;
+}
+
+/** 市场下载：GET backendUrl/api/workspace/skills/market/:id/raw?ticket= */
+function fetchMarketRaw(backendUrl, skillId, ticket) {
+  return new Promise((resolve, reject) => {
+    let u;
+    try {
+      u = new URL(`${String(backendUrl).replace(/\/$/, '')}/api/workspace/skills/market/${encodeURIComponent(skillId)}/raw`);
+      if (ticket) u.searchParams.set('ticket', ticket);
+    } catch {
+      return reject(new RpcError('E_SKILL_MARKET_OFFLINE', '技能市场地址无效'));
+    }
+    const lib = u.protocol === 'https:' ? https : http;
+    const req = lib.get(u, { timeout: 15000 }, (res) => {
+      if (res.statusCode !== 200) {
+        let body = '';
+        res.on('data', (c) => (body += c));
+        res.on('end', () => {
+          let msg = `下载失败（HTTP ${res.statusCode}）`;
+          try { msg = JSON.parse(body).msg || msg; } catch { /* ignore */ }
+          reject(new RpcError('E_SKILL_MARKET_OFFLINE', msg));
+        });
+        return;
+      }
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(body);
+          if (json.code !== 0 || !Array.isArray(json.data.files)) {
+            reject(new RpcError('E_SKILL_MARKET_OFFLINE', json.msg || '技能数据异常'));
+            return;
+          }
+          resolve(json.data);
+        } catch {
+          reject(new RpcError('E_SKILL_MARKET_OFFLINE', '技能数据解析失败'));
+        }
+      });
+    });
+    req.on('error', (e) => reject(new RpcError('E_SKILL_MARKET_OFFLINE', `技能市场不可用: ${e.message}`)));
+    req.on('timeout', () => { req.destroy(); reject(new RpcError('E_SKILL_MARKET_OFFLINE', '技能市场下载超时')); });
+  });
+}
+
+function createSkillMethods(ctxRef) {
+  const cfg = () => ctxRef().config;
+
+  function audit(opType, target, result, errorCode) {
+    try {
+      const br = ctxRef().broadcast;
+      if (br) br({ jsonrpc: '2.0', method: 'event.audit', params: { opType, target, result, errorCode } });
+    } catch { /* ignore */ }
+  }
+
+  function register(reg) {
+    // ---- 已安装列表 ----
+    reg('skill.list', async () => {
+      ensureRoot();
+      const items = [];
+      for (const entry of fs.readdirSync(SKILLS_ROOT, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        const info = readSkillInfo(path.join(SKILLS_ROOT, entry.name));
+        if (info) items.push(info);
+      }
+      return { skills: items };
+    });
+
+    // ---- 详情 ----
+    reg('skill.detail', async (params = {}) => {
+      const name = String(params.name || '');
+      const dir = path.join(SKILLS_ROOT, name);
+      const p = path.join(dir, 'SKILL.md');
+      if (!NAME_RE.test(name) || !fs.existsSync(p)) throw new RpcError('E_SKILL_NOT_FOUND', '技能不存在');
+      const content = fs.readFileSync(p, 'utf8');
+      const parsed = parseSkillDoc(content);
+      if (!parsed) throw new RpcError('E_SKILL_INVALID', 'SKILL.md 格式非法');
+      return { ...parsed, files: readSkillFiles(dir) };
+    });
+
+    // ---- 安装（market / local）----
+    reg('skill.install', async (params = {}) => {
+      const source = String(params.source || '');
+      if (source !== 'market' && source !== 'local') throw new RpcError('E_VALIDATION', 'source 必须为 market 或 local');
+      let name = '';
+      if (source === 'market') {
+        const skillId = String(params.ref || '');
+        const ticket = String(params.ticket || '');
+        const data = await fetchMarketRaw(cfg().backendUrl, skillId, ticket);
+        const files = data.files || [];
+        // 取 SKILL.md 里的 name
+        const sm = files.find((f) => f.relPath === 'SKILL.md');
+        if (!sm) throw new RpcError('E_SKILL_INVALID', '技能包缺少 SKILL.md');
+        const parsed = parseSkillDoc(sm.content);
+        if (!parsed) throw new RpcError('E_SKILL_INVALID', 'SKILL.md 格式非法');
+        name = parsed.name;
+        writeSkillFiles(name, files);
+      } else {
+        // local：本机路径
+        const p = String(params.path || '');
+        if (!p) throw new RpcError('E_VALIDATION', '缺少技能路径');
+        const smPath = path.join(p, 'SKILL.md');
+        if (!fs.existsSync(smPath)) throw new RpcError('E_SKILL_INVALID', '目录缺少 SKILL.md');
+        const content = fs.readFileSync(smPath, 'utf8');
+        const parsed = parseSkillDoc(content);
+        if (!parsed) throw new RpcError('E_SKILL_INVALID', 'SKILL.md 格式非法');
+        name = parsed.name;
+        const files = readSkillFiles(p);
+        writeSkillFiles(name, files);
+      }
+      const dir = path.join(SKILLS_ROOT, name);
+      const check = validateSkillDir(dir, name);
+      if (!check.ok) {
+        try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+        throw new RpcError('E_SKILL_INVALID', `技能校验失败: ${check.errors.join('; ')}`);
+      }
+      audit('skill.install', name, 'ok');
+      logger.info(`[skill] 已安装技能 ${name}（来源 ${source}）`);
+      return { ok: true, skill: readSkillInfo(dir) };
+    });
+
+    // ---- 卸载（危险级：前端二次确认）----
+    reg('skill.uninstall', async (params = {}) => {
+      const name = String(params.name || '');
+      const dir = path.join(SKILLS_ROOT, name);
+      if (!NAME_RE.test(name) || !fs.existsSync(dir)) throw new RpcError('E_SKILL_NOT_FOUND', '技能不存在');
+      fs.rmSync(dir, { recursive: true, force: true });
+      const st = stateFile();
+      delete st[name];
+      saveState(st);
+      audit('skill.uninstall', name, 'ok');
+      return { ok: true };
+    });
+
+    // ---- 启用/禁用 ----
+    reg('skill.setEnabled', async (params = {}) => {
+      const name = String(params.name || '');
+      const dir = path.join(SKILLS_ROOT, name);
+      if (!NAME_RE.test(name) || !fs.existsSync(dir)) throw new RpcError('E_SKILL_NOT_FOUND', '技能不存在');
+      const st = stateFile();
+      st[name] = !!params.enabled;
+      saveState(st);
+      audit('skill.setEnabled', name, 'ok');
+      return { ok: true, enabled: !!params.enabled };
+    });
+
+    // ---- AI 上下文注入（≤2K token，5.22.4）----
+    reg('skill.context', async () => {
+      ensureRoot();
+      const st = stateFile();
+      const parts = [];
+      let budget = 2000; // 2K token ≈ 约 6000 字符（中文保守按 3 字/token）
+      for (const entry of fs.readdirSync(SKILLS_ROOT, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        if (st[entry.name] === false) continue; // 已禁用
+        const info = readSkillInfo(path.join(SKILLS_ROOT, entry.name));
+        if (!info) continue;
+        const snippet = `[技能 ${info.name}] ${info.description}（v${info.version}）`;
+        if (budget - snippet.length < 0 && parts.length > 0) break;
+        parts.push(snippet);
+        budget -= snippet.length;
+      }
+      return { skills: parts };
+    });
+  }
+
+  return { register };
+}
+
+module.exports = { createSkillMethods, SKILLS_ROOT };

package/src/methods/system.js

@@ -0,0 +1,82 @@
+/**
+ * system.* RPC 方法：system.ping / system.info / system.check
+ * （T-M0-14：系统信息 + git 检测 + 版本上报）
+ */
+'use strict';
+
+const os = require('os');
+const { execFile } = require('child_process');
+const path = require('path');
+
+const AGENT_VERSION = require('../../package.json').version;
+const PROTOCOL_VERSION = 1;
+const MIN_NODE_VERSION = 20;
+
+let startupAt = Date.now();
+
+function detectPlatform() {
+  return `${process.platform} ${process.arch}`;
+}
+
+/**
+ * git --version 检测（spawn 参数数组，绝不拼字符串命令）
+ */
+function gitVersion(timeoutMs = 5000) {
+  return new Promise((resolve) => {
+    try {
+      const child = execFile(
+        'git',
+        ['--version'],
+        { timeout: timeoutMs, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] },
+        (err, stdout) => {
+          if (err) return resolve({ installed: false, version: '' });
+          const m = String(stdout).match(/git version\s+([^\s]+)/i);
+          resolve({ installed: true, version: m ? m[1] : String(stdout).trim() });
+        }
+      );
+      child.on('error', () => resolve({ installed: false, version: '' }));
+    } catch {
+      resolve({ installed: false, version: '' });
+    }
+  });
+}
+
+/** 收集一次 gitVersion 结果并缓存 30s */
+let gitCache = null;
+let gitCacheAt = 0;
+async function gitVersionCached() {
+  if (gitCache && Date.now() - gitCacheAt < 30000) return gitCache;
+  gitCache = await gitVersion();
+  gitCacheAt = Date.now();
+  return gitCache;
+}
+
+function registerSystemMethods(register, ctxRef) {
+  register('system.ping', async () => ({ pong: true, time: Date.now() }));
+
+  register('system.info', async () => {
+    const cfg = ctxRef().config;
+    return {
+      agentVersion: AGENT_VERSION,
+      protocolVersion: PROTOCOL_VERSION,
+      platform: detectPlatform(),
+      nodeVersion: process.version,
+      hostname: os.hostname(),
+      uptimeSec: Math.floor((Date.now() - startupAt) / 1000),
+      port: cfg.port,
+      enableTerminal: !!cfg.enableTerminal,
+      terminalPermission: cfg.terminalPermission || 'ask',
+      trashEnabled: !!cfg.trashEnabled,
+    };
+  });
+
+  register('system.check', async (params = {}) => {
+    const checks = {};
+    if (params.git !== false) checks.git = await gitVersionCached();
+    checks.node = { installed: true, version: process.version, ok: Number(process.versions.node.split('.')[0]) >= MIN_NODE_VERSION };
+    checks.agent = { version: AGENT_VERSION, protocolVersion: PROTOCOL_VERSION, ok: true };
+    return { checks };
+  });
+}
+
+module.exports = { registerSystemMethods, AGENT_VERSION, PROTOCOL_VERSION, gitVersion };

package/src/methods/terminal.js

@@ -0,0 +1,234 @@
+/**
+ * terminal.* RPC 方法（node-pty）
+ * - terminal.spawn {shell?, cwd} → {sessionId, pid}
+ * - terminal.write {sessionId, data}
+ * - terminal.resize {sessionId, cols, rows}
+ * - terminal.kill {sessionId}
+ * 事件：event.terminal.data（二进制帧 + JSON 头）/ event.terminal.exit
+ * 安全：仅直连模式；会话上限、输出截断、空闲超时；高危命令黄色提示（前端做，Agent 透传 cwd）
+ */
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { RpcError } = require('../rpc');
+
+let pty = null;
+try {
+  pty = require('node-pty');
+} catch (e) {
+  pty = null;
+}
+
+const DEFAULT_SHELL = process.platform === 'win32' ? 'powershell.exe' : process.env.SHELL || '/bin/bash';
+
+const MAX_OUTPUT_PER_SESSION = 2 * 1024 * 1024; // 单会话输出缓冲 2MB（超出截断提示）
+const OUTPUT_TRUNCATE_NOTICE = '\r\n\x1b[33m[输出过长，已截断]\x1b[0m\r\n';
+const RECENT_BUFFER_LINES = 2000; // 断线重连恢复的最近输出行数（T-M2-10）
+
+function createTerminalMethods(ctxRef) {
+  /** @type {Map<string, {id, pty, pending:string, truncated:boolean, idleTimer, lastActivity, recent:string[]}>} */
+  const sessions = new Map();
+  /** "允许本次" 的会话级放行（重启 Agent 后失效，符合 5.6.2） */
+  let onceAllowed = false;
+
+  function pushData(ctx, sessionId, data) {
+    // 二进制分帧：4 字节头长 + JSON 头 {channel:'terminal', sessionId, type:'data'} + payload
+    const header = Buffer.from(JSON.stringify({ channel: 'terminal', sessionId, type: 'data' }), 'utf8');
+    const frame = Buffer.concat([Buffer.from([0, 0, 0, header.length]), header, Buffer.from(data)]);
+    if (ctx.sendBinary) ctx.sendBinary(frame, { binary: true });
+  }
+
+  /** 断线恢复缓冲：保留最近 N 行（T-M2-10） */
+  function appendRecent(s, data) {
+    if (!s.recent) s.recent = [];
+    const lines = String(data).split(/\r?\n/);
+    for (const ln of lines) {
+      s.recent.push(ln);
+      if (s.recent.length > RECENT_BUFFER_LINES) s.recent.shift();
+    }
+  }
+
+  function pushExit(ctx, sessionId, exitCode) {
+    ctx.send({ jsonrpc: '2.0', method: 'event.terminal.exit', params: { sessionId, exitCode } });
+  }
+
+  function getSession(sessionId) {
+    const s = sessions.get(sessionId);
+    if (!s) throw new RpcError('E_TERMINAL_NOT_FOUND', `终端会话不存在: ${sessionId}`);
+    return s;
+  }
+
+  function resetIdleTimer(ctx, s) {
+    if (s.idleTimer) clearTimeout(s.idleTimer);
+    const cfg = ctxRef().config;
+    const minutes = Number(cfg.terminalIdleTimeoutMin || 30);
+    s.idleTimer = setTimeout(() => {
+      const cur = sessions.get(s.id);
+      if (!cur) return;
+      pushData(ctx, s.id, `\r\n\x1b[33m[终端空闲超时(${minutes} 分钟)，会话已自动关闭]\x1b[0m\r\n`);
+      cur.pty.kill();
+    }, minutes * 60 * 1000);
+    s.idleTimer.unref && s.idleTimer.unref();
+  }
+
+  function register(reg) {
+    // ---- 终端权限（5.6.2：ask/allow/deny 三态，存 agent.json）----
+    reg('terminal.permission', async (params = {}) => {
+      const cfg = ctxRef().config;
+      const value = String(params.value || '');
+      if (value === 'get') {
+        return { permission: cfg.terminalPermission || 'ask' };
+      }
+      if (value === 'allow' || value === 'deny' || value === 'ask') {
+        const { saveConfig } = require('../config');
+        saveConfig({ terminalPermission: value });
+        ctxRef().config.terminalPermission = value;
+        if (value === 'allow') onceAllowed = true;
+        if (value === 'deny') onceAllowed = false;
+        return { permission: value };
+      }
+      if (value === 'once') {
+        onceAllowed = true;
+        return { permission: 'ask', once: true };
+      }
+      throw new RpcError('E_VALIDATION', 'value 必须为 get/allow/once/deny/ask');
+    });
+
+    reg('terminal.spawn', async (params = {}, ctx) => {
+      const cfg = ctxRef().config;
+      if (!cfg.enableTerminal) throw new RpcError('E_TERMINAL_DISABLED', '终端已由本机代理配置关闭');
+      if (!pty) throw new RpcError('E_TERMINAL_DISABLED', 'node-pty 不可用（未安装或平台不支持）');
+      // 权限检查（5.6.2：首次使用权限卡三选一）
+      const permission = cfg.terminalPermission || 'ask';
+      if (permission === 'deny' && !onceAllowed) {
+        throw new RpcError('E_TERMINAL_DENIED', '终端权限已被拒绝，可在设置中撤销');
+      }
+      if (permission === 'ask' && !onceAllowed) {
+        return { needPermission: true, permission: 'ask' };
+      }
+      if (sessions.size >= Number(cfg.terminalMaxSessions || 3)) {
+        throw new RpcError('E_TERMINAL_LIMIT', `终端会话数已达上限（${cfg.terminalMaxSessions}）`);
+      }
+      const shell = params.shell || DEFAULT_SHELL;
+      const cwd = params.cwd && typeof params.cwd === 'string' ? params.cwd : os.homedir();
+      const sessionId = crypto.randomUUID();
+      let p;
+      try {
+        p = pty.spawn(shell, [], {
+          name: 'xterm-256color',
+          cols: Number(params.cols) || 80,
+          rows: Number(params.rows) || 24,
+          cwd,
+          env: { ...process.env, TERM: 'xterm-256color' },
+        });
+      } catch (e) {
+        // pty 启动失败（如系统禁用了 ConPTY/管道）不得打崩 Agent
+        throw new RpcError('E_TERMINAL_SPAWN_FAILED', `终端启动失败: ${e.message}`);
+      }
+      const s = { id: sessionId, pty: p, pending: '', truncated: false, idleTimer: null, lastActivity: Date.now(), recent: [] };
+      sessions.set(sessionId, s);
+      resetIdleTimer(ctx, s);
+      p.onData((data) => {
+        s.lastActivity = Date.now();
+        resetIdleTimer(ctx, s);
+        appendRecent(s, data);
+        if (!s.truncated) {
+          const cur = (s.pending.length + data.length);
+          if (cur > MAX_OUTPUT_PER_SESSION) {
+            s.pending = s.pending.slice(-MAX_OUTPUT_PER_SESSION / 2) + OUTPUT_TRUNCATE_NOTICE;
+            s.truncated = true;
+            pushData(ctx, sessionId, s.pending);
+            s.pending = '';
+          } else {
+            pushData(ctx, sessionId, data);
+          }
+        }
+      });
+      p.onExit(({ exitCode }) => {
+        sessions.delete(sessionId);
+        if (s.idleTimer) clearTimeout(s.idleTimer);
+        pushExit(ctx, sessionId, exitCode);
+      });
+      return { sessionId, pid: p.pid };
+    });
+
+    reg('terminal.write', async (params = {}, ctx) => {
+      const s = getSession(params.sessionId);
+      if (typeof params.data === 'string' && params.data.length > 0) s.pty.write(params.data);
+      return { ok: true };
+    });
+
+    reg('terminal.resize', async (params = {}) => {
+      const s = getSession(params.sessionId);
+      try {
+        s.pty.resize(Number(params.cols) || 80, Number(params.rows) || 24);
+      } catch {
+        /* 部分 shell 不支持 resize，忽略 */
+      }
+      return { ok: true };
+    });
+
+    reg('terminal.kill', async (params = {}) => {
+      const s = getSession(params.sessionId);
+      try {
+        s.pty.kill();
+      } catch {
+        /* 已退出 */
+      }
+      sessions.delete(params.sessionId);
+      return { ok: true };
+    });
+
+    reg('terminal.list', async () => {
+      return {
+        sessions: [...sessions.values()].map((s) => ({ sessionId: s.id, pid: s.pty.pid })),
+      };
+    });
+
+    // ---- 一次性命令执行（T-M3-21：AI 触发，前端必须危险级确认后调用）----
+    // 返回命令输出尾部（≤50KB）；不创建持久会话；超时 30s
+    reg('terminal.exec', async (params = {}) => {
+      const cfg = ctxRef().config;
+      if (!cfg.enableTerminal) throw new RpcError('E_TERMINAL_DISABLED', '终端已由本机代理配置关闭');
+      const cmd = String(params.cmd || '').trim();
+      if (!cmd) throw new RpcError('E_VALIDATION', '命令为空');
+      if (cmd.length > 2000) throw new RpcError('E_VALIDATION', '命令过长');
+      const cwd = params.cwd && typeof params.cwd === 'string' ? params.cwd : os.homedir();
+      const execFile = require('child_process').execFile;
+      return new Promise((resolve, reject) => {
+        const shell = process.platform === 'win32' ? 'powershell.exe' : '/bin/sh';
+        const args = process.platform === 'win32' ? ['-NoProfile', '-Command', cmd] : ['-c', cmd];
+        const child = execFile(shell, args, {
+          cwd,
+          timeout: 30000,
+          maxBuffer: 64 * 1024,
+          windowsHide: true,
+          env: { ...process.env, TERM: 'dumb' },
+        }, (err, stdout, stderr) => {
+          const out = String(stdout || '').slice(-50000);
+          const errOut = String(stderr || '').slice(-50000);
+          resolve({
+            exitCode: err && typeof err.code === 'number' ? err.code : err ? -1 : 0,
+            stdout: out,
+            stderr: errOut,
+            output: (out + (errOut ? '\n[stderr]\n' + errOut : '')).slice(-50000),
+          });
+        });
+        child.on('error', (e) => reject(new RpcError('E_TERMINAL_EXEC_FAILED', `命令执行失败: ${e.message}`)));
+      });
+    });
+
+    // ---- 断线恢复：最近输出缓冲（T-M2-10）----
+    reg('terminal.buffer', async (params = {}) => {
+      const s = getSession(params.sessionId);
+      const n = Math.min(RECENT_BUFFER_LINES, Math.max(1, Number(params.lines) || RECENT_BUFFER_LINES));
+      return { sessionId: s.id, buffer: (s.recent || []).slice(-n).join('\r\n') };
+    });
+  }
+
+  return { register, sessions };
+}
+
+module.exports = { createTerminalMethods, DEFAULT_SHELL };