@huicai/cli 0.5.1

package/src/device.js

@@ -0,0 +1,88 @@
+// 设备授权码流（浏览器授权登录）：发起 → 引导用户在浏览器确认 → 轮询换取授权登录令牌。
+// 服务端在用户确认时签发带时限的登录令牌（JWT，默认 7 天）——不再为每次登录铸造 API 令牌，
+// 不占用会员 API 令牌数量额度；令牌过期或改密后需重新授权。响应字段名保留 apiKey 以兼容旧版。
+// 全程只用平台网关的 /v1/device/*（免签名/免登录），CLI 无需预置任何凭据。
+
+import { spawn } from 'node:child_process';
+import { c } from './colors.js';
+
+/** 尽力打开系统浏览器（失败静默，用户可手动打开）。HUICAI_NO_BROWSER 置位时跳过（无头/测试环境）。 */
+function openBrowser(url) {
+  if (!url || process.env.HUICAI_NO_BROWSER) return;
+  const platform = process.platform;
+  const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    /* 用户可手动打开 */
+  }
+}
+
+async function postJson(baseUrl, path, body) {
+  const res = await fetch(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body || {}),
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    throw new Error(`服务返回异常(${res.status})：${text.slice(0, 200)}`);
+  }
+  if (!res.ok) throw new Error(json?.message || `HTTP ${res.status}`);
+  // 平台统一包装 {code,message,data}
+  if (json && typeof json === 'object' && 'data' in json && 'code' in json) {
+    if (json.code !== 0 && json.code !== 200) throw new Error(json.message || '请求失败');
+    return json.data;
+  }
+  return json;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * 执行设备授权流，成功返回授权登录令牌（JWT，服务端响应字段仍名 apiKey）；失败/超时抛错。
+ * @param {string} baseUrl 平台网关地址
+ */
+export async function deviceLogin(baseUrl) {
+  const start = await postJson(baseUrl, '/v1/device/code', { client_name: `huicai-cli (${process.platform})` });
+  const { deviceCode, userCode, verificationUri, verificationUriComplete } = start;
+  const interval = Math.max(2, start.interval || 5);
+  const expiresIn = start.expiresIn || 600;
+
+  // 授权页地址：优先服务端返回；否则按同域部署由平台地址推导 {baseUrl}/device
+  const vUri = verificationUri || baseUrl + '/device';
+  const vComplete = verificationUriComplete || vUri + (vUri.includes('?') ? '&' : '?') + 'code=' + encodeURIComponent(userCode);
+
+  process.stdout.write('\n' + c.bold('请在浏览器中完成授权：') + '\n');
+  process.stdout.write('  1) 打开 ' + c.cyan(vUri) + '\n');
+  process.stdout.write('  2) 确认授权码 ' + c.bold(c.yellow(userCode)) + '\n');
+  process.stdout.write(c.gray('  （已尝试自动打开浏览器；未弹出请手动访问上面的地址）') + '\n');
+  openBrowser(vComplete);
+  process.stdout.write(c.gray(`\n等待授权中…（有效期约 ${Math.round(expiresIn / 60)} 分钟，Ctrl+C 取消）`) + '\n');
+
+  const deadline = Date.now() + expiresIn * 1000;
+  while (Date.now() < deadline) {
+    await sleep(interval * 1000);
+    let r;
+    try {
+      r = await postJson(baseUrl, '/v1/device/token', { device_code: deviceCode });
+    } catch (e) {
+      process.stdout.write(c.gray(`  轮询出错（将重试）：${e.message}`) + '\n');
+      continue;
+    }
+    if (r.status === 'approved' && r.apiKey) {
+      process.stdout.write(c.green('\n✓ 授权成功') + '\n');
+      return r.apiKey;
+    }
+    if (r.status === 'denied') throw new Error('用户在浏览器中拒绝了授权');
+    if (r.status === 'expired') throw new Error('授权码已过期，请重新登录');
+    process.stdout.write(c.gray('  · 仍在等待浏览器确认…') + '\n');
+  }
+  throw new Error('授权超时，请重新运行 huicai login');
+}

package/src/executors.js

@@ -0,0 +1,391 @@
+// 本地工具的执行实现（在用户本机的文件系统 / shell 上运行）。
+// 所有写操作强制限定在当前项目目录内（防误伤系统路径）；读/搜索可跨目录。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import * as ide from './ide.js';
+
+const MAX_READ_BYTES = 256 * 1024;
+const MAX_FILE_BYTES = 16 * 1024 * 1024; // 超过则要求用 offset/limit 或 grep
+const DEFAULT_READ_LINES = 2000;
+const MAX_LINE_CHARS = 2000;
+const MAX_GREP_MATCHES = 200;
+const MAX_LIST_ENTRIES = 400;
+const MAX_GLOB_RESULTS = 300;
+const BASH_DEFAULT_TIMEOUT = 120_000;
+const BASH_MAX_OUTPUT = 30_000;
+const FETCH_TIMEOUT = 30_000;
+const FETCH_MAX_BYTES = 2 * 1024 * 1024;
+const FETCH_MAX_CHARS = 80_000;
+
+const DEFAULT_IGNORES = new Set([
+  '.git', 'node_modules', 'dist', 'build', 'target', 'out', '.next', '.nuxt',
+  '.venv', 'venv', '__pycache__', '.idea', '.gradle', '.mvn', 'coverage', '.cache',
+]);
+
+/** 解析路径为绝对路径；mustBeInside 时强制落在项目目录内。 */
+function resolvePath(cwd, p, mustBeInside) {
+  if (!cwd || typeof cwd !== 'string') {
+    throw new Error('工作目录未设置：请在项目目录中运行（VS Code 中需先「打开文件夹」再对话）');
+  }
+  if (!p || typeof p !== 'string') throw new Error('缺少路径 path（工具参数里必须提供 path 字段）');
+  const abs = path.resolve(cwd, p);
+  if (mustBeInside) {
+    const rel = path.relative(cwd, abs);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`路径超出项目目录（写操作仅限当前项目内）：${p}`);
+    }
+  }
+  return abs;
+}
+
+function rel(cwd, abs) {
+  const r = path.relative(cwd, abs);
+  return r === '' ? '.' : r;
+}
+
+function isProbablyBinary(buf) {
+  const n = Math.min(buf.length, 4096);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/** 深度优先遍历文件（跳过忽略目录），产出绝对文件路径。 */
+function* walkFiles(dir, depth = 0, maxDepth = 14) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (DEFAULT_IGNORES.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (depth < maxDepth) yield* walkFiles(full, depth + 1, maxDepth);
+    } else if (e.isFile()) {
+      yield full;
+    }
+  }
+}
+
+/** 简易 glob → 正则：支持 **（跨目录）、*（同级任意）、?（单字符）。 */
+function globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if ('\\^$+.()|{}[]'.includes(ch)) {
+      re += '\\' + ch;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/**
+ * 读取文件：输出「行号→内容」格式（行号仅供定位，不属于文件内容），默认最多 2000 行。
+ * 大文件（>16MB）要求用 offset/limit 分段或 grep 检索，避免占满内存与上下文。
+ */
+export function readFile(cwd, args) {
+  const abs = resolvePath(cwd, args.path, false);
+  const st = fs.statSync(abs);
+  if (st.isDirectory()) throw new Error(`是目录而非文件：${args.path}`);
+  if (st.size > MAX_FILE_BYTES) {
+    throw new Error(`文件过大（${Math.round(st.size / 1024 / 1024)}MB）：请用 grep 检索，或用 run_bash 的 head/tail/sed 分段查看`);
+  }
+  const buf = fs.readFileSync(abs);
+  if (isProbablyBinary(buf)) return `（二进制文件，${st.size} 字节，未展示内容）`;
+  const text = buf.toString('utf8');
+  if (text === '') return '（空文件）';
+
+  const lines = text.split('\n');
+  // 尾部空行（文件以 \n 结尾产生）不计入展示行数
+  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();
+  const total = lines.length;
+  const from = Math.max(0, (Number.isFinite(args.offset) ? args.offset : 1) - 1);
+  const limit = Number.isFinite(args.limit) && args.limit > 0 ? args.limit : DEFAULT_READ_LINES;
+  const to = Math.min(total, from + limit);
+  if (from >= total) return `（起始行 ${from + 1} 超出文件总行数 ${total}）`;
+
+  const width = String(to).length;
+  const outLines = [];
+  for (let i = from; i < to; i++) {
+    let line = lines[i];
+    if (line.length > MAX_LINE_CHARS) line = line.slice(0, MAX_LINE_CHARS) + '…（行过长已截断）';
+    outLines.push(`${String(i + 1).padStart(width)}→${line}`);
+  }
+  let outText = outLines.join('\n');
+  if (from > 0 || to < total) {
+    outText += `\n…（文件共 ${total} 行，本次显示第 ${from + 1}-${to} 行，可用 offset/limit 继续读取）`;
+  }
+  return outText;
+}
+
+export async function writeFile(cwd, args) {
+  const abs = resolvePath(cwd, args.path, true);
+  const content = args.content == null ? '' : String(args.content);
+  // IDE 内联审阅：把拟写内容交扩展做 diff + 应用；仅传输失败时回退直接写
+  if (ide.isActive()) {
+    const d = await ide.proposeWrite(abs, content, cwd);
+    if (d.decided) {
+      return d.applied
+        ? `已写入 ${rel(cwd, abs)}（经 IDE 审阅应用）`
+        : `用户在 IDE 中拒绝了对 ${rel(cwd, abs)} 的修改${d.reason ? '：' + d.reason : ''}`;
+    }
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content, 'utf8');
+  return `已写入 ${rel(cwd, abs)}（${Buffer.byteLength(content)} 字节）`
+    + (ide.isActive() ? '（IDE 未响应，已直接写入）' : '');
+}
+
+export async function editFile(cwd, args) {
+  const abs = resolvePath(cwd, args.path, true);
+  const oldStr = args.old_string == null ? '' : String(args.old_string);
+  const newStr = args.new_string == null ? '' : String(args.new_string);
+  if (oldStr === '') throw new Error('edit_file 需要非空 old_string');
+  const content = fs.readFileSync(abs, 'utf8');
+  const count = content.split(oldStr).length - 1;
+  if (count === 0) {
+    throw new Error('未找到要替换的内容（old_string 未出现在文件中）。注意：old_string 必须是文件原文，不能包含 read_file 显示的「行号→」前缀');
+  }
+  if (count > 1 && !args.replace_all) {
+    throw new Error(`old_string 在文件中出现 ${count} 处，不唯一；请补充上下文使其唯一，或设 replace_all=true`);
+  }
+  const updated = args.replace_all ? content.split(oldStr).join(newStr) : content.replace(oldStr, newStr);
+  const times = args.replace_all ? count : 1;
+  if (ide.isActive()) {
+    const d = await ide.proposeWrite(abs, updated, cwd);
+    if (d.decided) {
+      return d.applied
+        ? `已编辑 ${rel(cwd, abs)}（经 IDE 审阅应用，替换 ${times} 处）`
+        : `用户在 IDE 中拒绝了对 ${rel(cwd, abs)} 的修改${d.reason ? '：' + d.reason : ''}`;
+    }
+  }
+  fs.writeFileSync(abs, updated, 'utf8');
+  return `已编辑 ${rel(cwd, abs)}，替换 ${times} 处` + (ide.isActive() ? '（IDE 未响应，已直接写入）' : '');
+}
+
+export function listFiles(cwd, args) {
+  const base = resolvePath(cwd, args.path || '.', false);
+  const out = [];
+  let count = 0;
+  const walk = (dir, depth) => {
+    if (count >= MAX_LIST_ENTRIES) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (count >= MAX_LIST_ENTRIES) break;
+      if (DEFAULT_IGNORES.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const r = path.relative(base, full);
+      if (e.isDirectory()) {
+        out.push(r + '/');
+        count++;
+        if (depth < 6) walk(full, depth + 1);
+      } else {
+        out.push(r);
+        count++;
+      }
+    }
+  };
+  walk(base, 0);
+  if (out.length === 0) return '（空目录）';
+  return out.join('\n') + (count >= MAX_LIST_ENTRIES ? '\n…（条目已截断）' : '');
+}
+
+export function glob(cwd, args) {
+  if (!args.pattern) throw new Error('缺少 pattern');
+  const re = globToRegex(args.pattern);
+  const results = [];
+  for (const abs of walkFiles(cwd)) {
+    const r = path.relative(cwd, abs).split(path.sep).join('/');
+    if (re.test(r)) {
+      results.push(r);
+      if (results.length >= MAX_GLOB_RESULTS) break;
+    }
+  }
+  if (results.length === 0) return '（无匹配文件）';
+  return results.join('\n');
+}
+
+export function grep(cwd, args) {
+  if (!args.pattern) throw new Error('缺少 pattern');
+  let re;
+  try {
+    re = new RegExp(args.pattern, args.ignore_case ? 'i' : undefined);
+  } catch (e) {
+    throw new Error(`无效的正则：${e.message}`);
+  }
+  const globRe = args.glob ? globToRegex(args.glob) : null;
+  const base = resolvePath(cwd, args.path || '.', false);
+  const maxMatches = Number.isFinite(args.max_results) && args.max_results > 0
+    ? Math.min(args.max_results, 500)
+    : MAX_GREP_MATCHES;
+  const matches = [];
+  const filesHit = [];
+  for (const abs of walkFiles(base)) {
+    if (matches.length >= maxMatches) break;
+    const r = path.relative(cwd, abs).split(path.sep).join('/');
+    if (globRe && !globRe.test(r)) continue;
+    let buf;
+    try {
+      buf = fs.readFileSync(abs);
+    } catch {
+      continue;
+    }
+    if (buf.length > MAX_READ_BYTES || isProbablyBinary(buf)) continue;
+    const lines = buf.toString('utf8').split('\n');
+    let hit = false;
+    for (let i = 0; i < lines.length; i++) {
+      if (re.test(lines[i])) {
+        hit = true;
+        if (args.files_only) break;
+        matches.push(`${r}:${i + 1}: ${lines[i].slice(0, 240)}`);
+        if (matches.length >= maxMatches) break;
+      }
+    }
+    if (hit) {
+      filesHit.push(r);
+      if (args.files_only && filesHit.length >= maxMatches) break;
+    }
+  }
+  if (args.files_only) {
+    return filesHit.length ? filesHit.join('\n') : '（无匹配）';
+  }
+  if (matches.length === 0) return '（无匹配）';
+  return matches.join('\n') + (matches.length >= maxMatches ? '\n…（结果已截断）' : '');
+}
+
+export function runBash(cwd, args) {
+  const command = args.command == null ? '' : String(args.command);
+  if (command.trim() === '') return Promise.resolve('（未提供命令）');
+  const timeout = Number.isFinite(args.timeout) ? Math.min(args.timeout, 600_000) : BASH_DEFAULT_TIMEOUT;
+  const isWin = process.platform === 'win32';
+  return new Promise((resolve) => {
+    let out = '';
+    let killed = false;
+    // POSIX 下 detached 让子命令自成进程组，超时可整组击杀（防止 shell 被杀而孙进程残留）
+    const child = isWin
+      ? spawn(process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', command], { cwd, windowsVerbatimArguments: true })
+      : spawn(process.env.SHELL || '/bin/sh', ['-c', command], { cwd, detached: true });
+    const killTree = () => {
+      try {
+        if (!isWin && child.pid) process.kill(-child.pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        try {
+          child.kill('SIGKILL');
+        } catch {
+          /* ignore */
+        }
+      }
+    };
+    const timer = setTimeout(() => {
+      killed = true;
+      killTree();
+    }, timeout);
+    const append = (d) => {
+      if (out.length < BASH_MAX_OUTPUT) out += d.toString();
+    };
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolve(`命令启动失败：${e.message}`);
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      let text = out.length > BASH_MAX_OUTPUT ? out.slice(0, BASH_MAX_OUTPUT) + '\n…（输出已截断）' : out;
+      if (text.trim() === '') text = '（无输出）';
+      const status = killed ? `【超时被终止】` : `退出码 ${code}`;
+      resolve(`${status}\n${text}`);
+    });
+  });
+}
+
+/** 抓取网页/接口并转为可读文本（HTML 去标签；JSON/纯文本原样）。仅 http/https GET。 */
+export async function fetchUrl(cwd, args) {
+  const url = String(args.url || '').trim();
+  if (!/^https?:\/\//i.test(url)) throw new Error('仅支持 http/https URL');
+  let res;
+  try {
+    res = await fetch(url, {
+      redirect: 'follow',
+      signal: AbortSignal.timeout(Number.isFinite(args.timeout) ? Math.min(args.timeout, 120_000) : FETCH_TIMEOUT),
+      headers: {
+        'User-Agent': 'huicai-cli',
+        Accept: 'text/html,application/json;q=0.9,text/plain;q=0.8,*/*;q=0.5',
+      },
+    });
+  } catch (e) {
+    throw new Error(`请求失败：${e?.cause?.message || e.message}`);
+  }
+  const buf = await readBodyCapped(res, FETCH_MAX_BYTES);
+  const ctype = (res.headers.get('content-type') || '').toLowerCase();
+  if (isProbablyBinary(buf) && !/text|json|xml|html/.test(ctype)) {
+    return `HTTP ${res.status} · ${ctype || '未知类型'} · ${buf.length} 字节（二进制内容未展示）`;
+  }
+  let text = buf.toString('utf8');
+  if (ctype.includes('html') || /^\s*<(!doctype|html)/i.test(text)) text = htmlToText(text);
+  text = text.trim();
+  if (text.length > FETCH_MAX_CHARS) text = text.slice(0, FETCH_MAX_CHARS) + '\n…（内容过长已截断）';
+  const head = `HTTP ${res.status}${res.url && res.url !== url ? ` · 重定向至 ${res.url}` : ''}`;
+  if (!res.ok) return `${head}\n${text || '（无内容）'}`;
+  return `${head}\n${text || '（无内容）'}`;
+}
+
+async function readBodyCapped(res, maxBytes) {
+  if (!res.body) return Buffer.alloc(0);
+  const reader = res.body.getReader();
+  const chunks = [];
+  let size = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    size += value.length;
+    if (size >= maxBytes) {
+      reader.cancel().catch(() => {});
+      break;
+    }
+  }
+  return Buffer.concat(chunks.map((u) => Buffer.from(u)), Math.min(size, maxBytes));
+}
+
+/** 极简 HTML→文本：去 script/style，块级标签换行，去其余标签，解码常见实体，压缩空行。 */
+function htmlToText(html) {
+  let s = String(html);
+  s = s.replace(/<(script|style|noscript|svg|head)[\s\S]*?<\/\1>/gi, '');
+  s = s.replace(/<!--[\s\S]*?-->/g, '');
+  s = s.replace(/<br\s*\/?>/gi, '\n');
+  s = s.replace(/<\/(p|div|li|tr|h[1-6]|section|article|blockquote|pre|ul|ol|table)>/gi, '\n');
+  s = s.replace(/<li[^>]*>/gi, '- ');
+  s = s.replace(/<[^>]+>/g, '');
+  s = s
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+  s = s.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n');
+  return s;
+}

package/src/ide.js

@@ -0,0 +1,53 @@
+// IDE 桥接客户端：当运行在 huicai VS Code 扩展启动的终端里（扩展经环境变量注入本地服务端口+令牌）时，
+// 把 write_file/edit_file 的「拟写入内容」发给扩展做「内联 diff 审阅 + 应用」，而非 CLI 直接落盘。
+// 未在 IDE 环境（无 HUICAI_IDE_PORT）则本模块不介入，CLI 照常直接写文件。
+
+import http from 'node:http';
+
+const APPLY_TIMEOUT = 120_000; // 用户审阅可能较久
+
+/** 是否处于 IDE 集成环境（由扩展注入端口）。 */
+export function isActive() {
+  return !!process.env.HUICAI_IDE_PORT;
+}
+
+/**
+ * 把拟写入内容提交给 IDE 扩展做内联 diff 审阅。
+ * @returns {Promise<{decided:boolean, applied?:boolean, reason?:string}>}
+ *   decided=false 表示传输失败（扩展未响应）——调用方应回退为直接写盘。
+ */
+export function proposeWrite(absPath, content, cwd) {
+  return new Promise((resolve) => {
+    const port = process.env.HUICAI_IDE_PORT;
+    const token = process.env.HUICAI_IDE_TOKEN || '';
+    const body = JSON.stringify({ path: absPath, content, cwd, token });
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        path: '/apply',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+      },
+      (res) => {
+        let d = '';
+        res.on('data', (c) => (d += c));
+        res.on('end', () => {
+          try {
+            const j = JSON.parse(d);
+            resolve({ decided: true, applied: !!j.applied, reason: j.reason });
+          } catch {
+            resolve({ decided: false });
+          }
+        });
+      },
+    );
+    req.on('error', () => resolve({ decided: false }));
+    req.setTimeout(APPLY_TIMEOUT, () => {
+      req.destroy();
+      resolve({ decided: false });
+    });
+    req.write(body);
+    req.end();
+  });
+}

package/src/input.js

@@ -0,0 +1,118 @@
+// 输入预处理与历史：
+//  - @文件 引用：消息中的 @路径 自动展开为文件内容（附在消息末尾），目录则展开为清单；
+//  - !命令 直通：以 ! 开头的输入直接在本机执行 shell 命令，输出加入对话上下文（不消耗模型调用）；
+//  - 输入历史：按项目目录持久化到 ~/.huicai/history.json，供 REPL/TUI 上下键翻阅。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { CONFIG_DIR } from './config.js';
+import { runBash } from './executors.js';
+
+const MAX_MENTIONS = 5;
+const MENTION_FILE_CHARS = 12_000;
+const HISTORY_PATH = path.join(CONFIG_DIR, 'history.json');
+const HISTORY_CAP = 1000;
+
+/**
+ * 展开消息中的 @文件/@目录 引用：原文保留，内容以引用块追加在末尾（模型可见全文）。
+ * @returns {{text:string, mentions:string[]}}
+ */
+export function expandAtMentions(text, cwd) {
+  const re = /(^|[\s("'`（【,，:：])@([~A-Za-z0-9_./\\-]+)/g;
+  const seen = new Set();
+  const blocks = [];
+  let m;
+  while ((m = re.exec(text)) && seen.size < MAX_MENTIONS) {
+    const raw = m[2].replace(/[.,;:。，；]+$/, ''); // 去句尾标点
+    if (!raw || seen.has(raw)) continue;
+    const abs = raw.startsWith('~') ? path.join(os.homedir(), raw.slice(1)) : path.resolve(cwd, raw);
+    let st;
+    try {
+      st = fs.statSync(abs);
+    } catch {
+      continue; // 不存在的路径按普通文本处理
+    }
+    seen.add(raw);
+    if (st.isDirectory()) {
+      try {
+        const entries = fs.readdirSync(abs).slice(0, 100).join('\n');
+        blocks.push(`【引用目录 @${raw}】\n${entries || '（空目录）'}`);
+      } catch {
+        /* ignore */
+      }
+      continue;
+    }
+    if (st.size > 512 * 1024) {
+      blocks.push(`【引用文件 @${raw}】\n（文件过大：${Math.round(st.size / 1024)}KB，未展开；可让我用 read_file 分段读取）`);
+      continue;
+    }
+    try {
+      const buf = fs.readFileSync(abs);
+      if (isBinary(buf)) {
+        blocks.push(`【引用文件 @${raw}】\n（二进制文件，未展开）`);
+        continue;
+      }
+      let content = buf.toString('utf8');
+      if (content.length > MENTION_FILE_CHARS) content = content.slice(0, MENTION_FILE_CHARS) + '\n…（已截断）';
+      blocks.push(`【引用文件 @${raw}】\n\`\`\`\n${content}\n\`\`\``);
+    } catch {
+      /* ignore */
+    }
+  }
+  if (!blocks.length) return { text, mentions: [] };
+  return { text: text + '\n\n' + blocks.join('\n\n'), mentions: [...seen] };
+}
+
+function isBinary(buf) {
+  const n = Math.min(buf.length, 4096);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/**
+ * 执行 !命令 直通：在 cwd 下跑 shell 命令，返回展示文本与写入对话的记录文本。
+ * @returns {Promise<{output:string, record:string}>}
+ */
+export async function runBangCommand(command, cwd) {
+  const output = await runBash(cwd, { command });
+  const capped = output.length > 8000 ? output.slice(0, 8000) + '\n…（已截断）' : output;
+  return {
+    output,
+    record: `我在终端直接执行了命令：$ ${command}\n${capped}`,
+  };
+}
+
+function readHistoryFile() {
+  try {
+    const j = JSON.parse(fs.readFileSync(HISTORY_PATH, 'utf8'));
+    return Array.isArray(j?.entries) ? j.entries : [];
+  } catch {
+    return [];
+  }
+}
+
+/** 读取某目录的输入历史（旧→新）。 */
+export function loadHistory(cwd, limit = 200) {
+  return readHistoryFile()
+    .filter((e) => e && e.cwd === cwd && typeof e.line === 'string')
+    .slice(-limit)
+    .map((e) => e.line);
+}
+
+/** 追加一条输入历史（连续重复不记）。best-effort，失败静默。 */
+export function appendHistory(cwd, line) {
+  const t = String(line || '').trim();
+  if (!t) return;
+  try {
+    let entries = readHistoryFile();
+    const last = [...entries].reverse().find((e) => e.cwd === cwd);
+    if (last && last.line === t) return;
+    entries.push({ cwd, line: t, ts: Date.now() });
+    if (entries.length > HISTORY_CAP) entries = entries.slice(-HISTORY_CAP);
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(HISTORY_PATH, JSON.stringify({ entries }), { mode: 0o600 });
+  } catch {
+    /* ignore */
+  }
+}