mingdao-harness 0.1.54

package/src/tools/fs-tools.js

@@ -0,0 +1,346 @@
+// 文件系统工具：read / write / edit / ls / glob / grep。
+// 所有工具返回 { ok, output? | error? }，由 agent 序列化后交给模型。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_SCAN_FILES = 20000;
+const MAX_GLOB_RESULTS = 1000;
+const MAX_GREP_MATCHES = 250;
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+function resolvePath(cwd, p) {
+  if (path.isAbsolute(p)) return path.normalize(p);
+  return path.resolve(cwd, p);
+}
+
+function isProbablyBinary(buf) {
+  const head = buf.subarray(0, 8192);
+  for (let i = 0; i < head.length; i++) {
+    if (head[i] === 0) return true;
+  }
+  return false;
+}
+
+// —— undo 备份（会话级，每文件最多 10 份） ——
+function backup(ctx, p) {
+  try {
+    const store = ctx?.undoStore?.backups;
+    if (!(store instanceof Map)) return;
+    const buf = fs.readFileSync(p);
+    const list = store.get(p) || [];
+    list.push({ time: Date.now(), content: buf });
+    if (list.length > 10) list.shift();
+    store.set(p, list);
+  } catch {}
+}
+
+export function undo(args, ctx) {
+  const store = ctx?.undoStore?.backups;
+  if (!(store instanceof Map) || !store.size) return { ok: false, error: '没有可撤销的修改。' };
+  const p = args.path ? resolvePath(ctx.cwd, args.path) : null;
+  if (p) {
+    const list = store.get(p);
+    if (!list?.length) return { ok: false, error: `${p} 没有可撤销的修改记录。` };
+    const last = list.pop();
+    try {
+      fs.writeFileSync(p, last.content);
+      return { ok: true, output: `已撤销 ${p} 的最近一次修改（该文件剩余备份 ${list.length} 个）。` };
+    } catch (err) {
+      return { ok: false, error: `撤销失败：${err?.message || err}` };
+    }
+  }
+  let latestFile = null;
+  let latestTime = 0;
+  for (const [file, list] of store) {
+    const last = list[list.length - 1];
+    if (last && last.time > latestTime) {
+      latestTime = last.time;
+      latestFile = file;
+    }
+  }
+  if (!latestFile) return { ok: false, error: '没有可撤销的修改。' };
+  const list = store.get(latestFile);
+  const last = list.pop();
+  try {
+    fs.writeFileSync(latestFile, last.content);
+    return { ok: true, output: `已撤销 ${latestFile} 的最近一次修改。` };
+  } catch (err) {
+    return { ok: false, error: `撤销失败：${err?.message || err}` };
+  }
+}
+
+export function read(args, ctx) {
+  try {
+    const p = resolvePath(ctx.cwd, args.path ?? '');
+    if (!p) return { ok: false, error: '缺少 path 参数。' };
+    const st = fs.statSync(p);
+    if (st.isDirectory()) return { ok: false, error: `"${p}" 是目录，请使用 ls 查看。` };
+    if (st.size > MAX_FILE_BYTES) {
+      return {
+        ok: false,
+        error: `"${p}" 大小 ${(st.size / 1024 / 1024).toFixed(1)}MB，超过 ${MAX_FILE_BYTES / 1024 / 1024}MB 上限。请用 grep 搜索或 bash 分块查看。`,
+      };
+    }
+    const buf = fs.readFileSync(p);
+    if (isProbablyBinary(buf)) return { ok: false, error: `"${p}" 疑似二进制文件，无法按文本读取。` };
+    const lines = buf.toString('utf8').split('\n');
+    const offset = Math.max(1, Number(args.offset) || 1);
+    const limit = Math.max(1, Number(args.limit) || 400);
+    // 审计质量项：offset 超出文件行数时明确提示，而非返回空内容让模型误以为文件为空
+    if (offset > lines.length) {
+      return { ok: true, output: `（offset=${offset} 超出文件总行数 ${lines.length}，文件已读完）`, totalLines: lines.length };
+    }
+    const end = Math.min(lines.length, offset - 1 + limit);
+    const out = [];
+    for (let i = offset - 1; i < end; i++) out.push(`${i + 1}\t${lines[i]}`);
+    const truncated = end < lines.length;
+    return {
+      ok: true,
+      output:
+        out.join('\n') + (truncated ? `\n…[共 ${lines.length} 行，已显示第 ${offset}-${end} 行]` : ''),
+      totalLines: lines.length,
+    };
+  } catch (err) {
+    return { ok: false, error: `读取失败：${err?.message || err}` };
+  }
+}
+
+const MAX_WRITE_BYTES = 2 * 1024 * 1024; // write 单次内容上限（防模型输出超大文件打爆磁盘）
+
+export function write(args, ctx) {
+  try {
+    const p = resolvePath(ctx.cwd, args.path ?? '');
+    if (!p) return { ok: false, error: '缺少 path 参数。' };
+    const content = String(args.content ?? '');
+    if (Buffer.byteLength(content) > MAX_WRITE_BYTES) {
+      return { ok: false, error: `内容超过 ${MAX_WRITE_BYTES / 1024 / 1024}MB 上限，请分多次写入。` };
+    }
+    if (fs.existsSync(p)) {
+      const st = fs.statSync(p);
+      if (st.size > MAX_FILE_BYTES) {
+        return { ok: false, error: `目标文件 ${p} 超过 5MB，请改用 edit 精确修改。` };
+      }
+      backup(ctx, p);
+    }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+    return { ok: true, output: `已写入 ${p}（${Buffer.byteLength(content)} 字节）。` };
+  } catch (err) {
+    return { ok: false, error: `写入失败：${err?.message || err}` };
+  }
+}
+
+// 提取替换区域（含上下文），供 TUI 渲染变更预览
+function regionAround(text, lineStart, lineCount, context = 2) {
+  const lines = text.split('\n');
+  const from = Math.max(0, lineStart - context);
+  const to = Math.min(lines.length, lineStart + lineCount + context);
+  return lines.slice(from, to).join('\n');
+}
+
+export function edit(args, ctx) {
+  try {
+    const p = resolvePath(ctx.cwd, args.path ?? '');
+    const oldString = String(args.old_string ?? '');
+    const newString = String(args.new_string ?? '');
+    const replaceAll = Boolean(args.replace_all);
+    if (!p) return { ok: false, error: '缺少 path 参数。' };
+    if (!oldString) return { ok: false, error: '缺少 old_string 参数。' };
+    try {
+      if (fs.statSync(p).size > MAX_FILE_BYTES) {
+        return { ok: false, error: `文件 ${p} 超过 5MB，请先 read 定位后用更小的改动。` };
+      }
+    } catch {}
+    const text = fs.readFileSync(p, 'utf8');
+    const count = text.split(oldString).length - 1;
+    if (count === 0) {
+      return { ok: false, error: `在 ${p} 中未找到 old_string 匹配。文件可能已变化，请先 read 确认最新内容。` };
+    }
+    if (count > 1 && !replaceAll) {
+      return { ok: false, error: `old_string 匹配到 ${count} 处。请提供更精确的上下文，或设置 replace_all=true。` };
+    }
+    const next = replaceAll ? text.split(oldString).join(newString) : text.replace(oldString, newString);
+    backup(ctx, p);
+    fs.writeFileSync(p, next);
+    const idx = text.indexOf(oldString);
+    const lineStart = text.slice(0, idx).split('\n').length - 1;
+    const before = regionAround(text, lineStart, oldString.split('\n').length);
+    const after = regionAround(next, lineStart, newString.split('\n').length);
+    return {
+      ok: true,
+      output: `已编辑 ${p}（替换 ${count} 处）。`,
+      diff: { before, after },
+    };
+  } catch (err) {
+    return { ok: false, error: `编辑失败：${err?.message || err}` };
+  }
+}
+
+export function ls(args, ctx) {
+  try {
+    const p = resolvePath(ctx.cwd, args.path || '.');
+    const entries = fs.readdirSync(p, { withFileTypes: true });
+    const rows = entries
+      .map((e) => {
+        const full = path.join(p, e.name);
+        if (e.isDirectory()) return `${e.name}/`;
+        let size = '';
+        try {
+          size = ` (${fs.statSync(full).size}B)`;
+        } catch {}
+        return e.name + size;
+      })
+      .sort((a, b) => {
+        const ad = a.endsWith('/') ? 0 : 1;
+        const bd = b.endsWith('/') ? 0 : 1;
+        return ad - bd || a.localeCompare(b);
+      });
+    return { ok: true, output: rows.join('\n') || '(空目录)' };
+  } catch (err) {
+    return { ok: false, error: `列目录失败：${err?.message || err}` };
+  }
+}
+
+function globToRegExp(pattern) {
+  let re = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        if (pattern[i + 2] === '/') {
+          re += '(?:.*/)?'; // **/ 匹配零层或多层目录
+          i += 2;
+        } else {
+          re += '.*';
+          i += 1;
+        }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if (/[.+^${}()|[\]\\]/.test(ch)) {
+      re += '\\' + ch;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function walkFiles(root, visitor) {
+  const stack = [root];
+  let scanned = 0;
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (scanned++ > MAX_SCAN_FILES) return scanned;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === '.git' || e.name === 'node_modules') continue;
+        stack.push(full);
+      } else if (e.isFile()) {
+        if (visitor(full) === false) return scanned;
+      }
+    }
+  }
+  return scanned;
+}
+
+export function glob(args, ctx) {
+  try {
+    const pattern = String(args.pattern ?? '*');
+    const root = resolvePath(ctx.cwd, args.path || '.');
+    if (!fs.existsSync(root)) return { ok: false, error: `目录不存在：${root}` };
+    const re = globToRegExp(pattern);
+    const matchRel = pattern.includes('/');
+    const results = [];
+    let truncated = false;
+    walkFiles(root, (full) => {
+      if (results.length >= MAX_GLOB_RESULTS) {
+        truncated = true;
+        return false;
+      }
+      const rel = path.relative(root, full).split(path.sep).join('/');
+      if (re.test(matchRel ? rel : path.basename(full))) results.push(rel);
+    });
+    let output = results.join('\n');
+    if (!results.length) output = '(无匹配)';
+    if (truncated) output += `\n…[结果超过 ${MAX_GLOB_RESULTS} 条，已截断]`;
+    return { ok: true, output };
+  } catch (err) {
+    return { ok: false, error: `glob 失败：${err?.message || err}` };
+  }
+}
+
+export function grep(args, ctx) {
+  try {
+    const pattern = String(args.pattern ?? '');
+    if (!pattern) return { ok: false, error: '缺少 pattern 参数。' };
+    if (pattern.length > 500) return { ok: false, error: 'pattern 过长（>500 字符）。' };
+    // 拒绝嵌套量词类灾难回溯模式（如 (a+)+b），避免同步 ReDoS 卡死事件循环
+    if (/\([^)]*[+*][^)]*\)[+*{]/.test(pattern)) {
+      return { ok: false, error: 'pattern 疑似灾难性回溯（嵌套量词），请改写为等价安全形式。' };
+    }
+    let re;
+    try {
+      re = new RegExp(pattern);
+    } catch (e) {
+      return { ok: false, error: `无效的正则表达式：${e.message}` };
+    }
+    // 单行截断：超长行（如压缩的 JS/日志）截到 20KB 再匹配，防止正则开销失控
+    const MAX_LINE = 20 * 1024;
+    const testLine = (line) => (line.length > MAX_LINE ? re.test(line.slice(0, MAX_LINE)) : re.test(line));
+    const root = resolvePath(ctx.cwd, args.path || '.');
+    const include = args.include ? globToRegExp(String(args.include)) : null;
+    const matches = [];
+    let truncated = false;
+    let scannedFiles = 0;
+    walkFiles(root, (full) => {
+      if (include && !include.test(path.basename(full))) return;
+      if (matches.length >= MAX_GREP_MATCHES) {
+        truncated = true;
+        return false;
+      }
+      scannedFiles += 1;
+      let stat;
+      try {
+        stat = fs.statSync(full);
+      } catch {
+        return;
+      }
+      if (stat.size > MAX_FILE_BYTES) return;
+      let text;
+      try {
+        text = fs.readFileSync(full, 'utf8');
+      } catch {
+        return;
+      }
+      const rel = path.relative(root, full).split(path.sep).join('/');
+      const lines = text.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (testLine(lines[i])) {
+          matches.push(`${rel}:${i + 1}: ${lines[i].trimEnd()}`);
+          if (matches.length >= MAX_GREP_MATCHES) {
+            truncated = true;
+            return false;
+          }
+        }
+      }
+    });
+    let output = matches.length ? matches.join('\n') : '(无匹配)';
+    output += truncated
+      ? `\n…[匹配超过 ${MAX_GREP_MATCHES} 条，已截断；已扫描 ${scannedFiles} 个文件]`
+      : `\n[已扫描 ${scannedFiles} 个文件]`;
+    return { ok: true, output };
+  } catch (err) {
+    return { ok: false, error: `grep 失败：${err?.message || err}` };
+  }
+}

package/src/tools/index.js

@@ -0,0 +1,287 @@
+// 工具注册表：模型可见的工具 Schema（OpenAI function-calling 格式）与执行分发器。
+// 文件/命令工具 + 智能体工具（skill 技能加载 / task 子代理 / todo 任务清单 / undo 撤销）。
+
+import { read, write, edit, ls, glob, grep, undo } from './fs-tools.js';
+import { runBash } from './bash.js';
+import { listSkills, loadSkill } from '../skills.js';
+
+// 只读工具集合的单一来源：permissions.js 引用此导出，新增只读工具时只需改这里
+export const READONLY_TOOLS = new Set(['read', 'glob', 'grep', 'ls', 'skill']);
+
+const READ_SCHEMA = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: '要读取的文件路径（相对或绝对）。' },
+    offset: { type: 'integer', description: '起始行号，默认 1。' },
+    limit: { type: 'integer', description: '最大返回行数，默认 400。' },
+  },
+  required: ['path'],
+};
+
+const WRITE_SCHEMA = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: '要创建或覆盖的文件路径。' },
+    content: { type: 'string', description: '完整文件内容（UTF-8）。' },
+  },
+  required: ['path', 'content'],
+};
+
+const EDIT_SCHEMA = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: '要修改的文件路径。' },
+    old_string: { type: 'string', description: '文件中真实存在的原文片段，必须逐字符完全一致。' },
+    new_string: { type: 'string', description: '替换后的文本。' },
+    replace_all: { type: 'boolean', description: '是否替换所有匹配处，默认 false。' },
+  },
+  required: ['path', 'old_string', 'new_string'],
+};
+
+const LS_SCHEMA = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: '目录路径，默认当前工作目录。' },
+  },
+};
+
+const GLOB_SCHEMA = {
+  type: 'object',
+  properties: {
+    pattern: { type: 'string', description: '通配符模式，如 src/**/*.js、*.md。' },
+    path: { type: 'string', description: '搜索根目录，默认当前工作目录。' },
+  },
+  required: ['pattern'],
+};
+
+const GREP_SCHEMA = {
+  type: 'object',
+  properties: {
+    pattern: { type: 'string', description: '正则表达式。' },
+    path: { type: 'string', description: '搜索根目录，默认当前工作目录。' },
+    include: { type: 'string', description: '文件名通配符过滤，如 *.js。' },
+  },
+  required: ['pattern'],
+};
+
+const BASH_SCHEMA = {
+  type: 'object',
+  properties: {
+    command: { type: 'string', description: '要执行的 shell 命令。执行前会请求用户授权。' },
+    timeout: { type: 'integer', description: '超时秒数，默认 120。' },
+  },
+  required: ['command'],
+};
+
+const SKILL_SCHEMA = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', description: '技能名；省略时列出所有可用技能。' },
+  },
+};
+
+const TASK_SCHEMA = {
+  type: 'object',
+  properties: {
+    description: { type: 'string', description: '子任务一句话描述（用于进度展示）。' },
+    prompt: { type: 'string', description: '交给子代理的完整任务说明（它没有当前对话上下文）。' },
+    readOnly: { type: 'boolean', description: '只读调研任务（不写文件不执行命令）。多个 readOnly 子任务会并行执行。' },
+  },
+  required: ['prompt'],
+};
+
+const TODO_SCHEMA = {
+  type: 'object',
+  properties: {
+    todos: {
+      type: 'array',
+      description: '完整任务清单（全量替换）。',
+      items: {
+        type: 'object',
+        properties: {
+          content: { type: 'string', description: '任务描述。' },
+          status: { type: 'string', enum: ['pending', 'in_progress', 'completed'], description: '任务状态。' },
+        },
+        required: ['content', 'status'],
+      },
+    },
+  },
+  required: ['todos'],
+};
+
+const UNDO_SCHEMA = {
+  type: 'object',
+  properties: {
+    path: { type: 'string', description: '要撤销的文件；省略时撤销最近一次修改的文件。' },
+  },
+};
+
+const TOOLS = [
+  {
+    type: 'function',
+    function: {
+      name: 'read',
+      description: '读取文本文件，返回带行号的内容。修改文件前务必先读取。',
+      parameters: READ_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'write',
+      description: '创建新文件或完全覆盖已有文件（自动创建父目录）。',
+      parameters: WRITE_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'edit',
+      description: '对文件做精确文本替换。old_string 必须与文件内容完全一致；匹配多处时需 replace_all=true 或提供更精确上下文。',
+      parameters: EDIT_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'ls',
+      description: '列出目录内容，目录以 / 结尾。',
+      parameters: LS_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'glob',
+      description: '按通配符模式查找文件路径（支持 * 与 **）。',
+      parameters: GLOB_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'grep',
+      description: '在文件内容中按正则表达式搜索，返回「文件:行号: 内容」。',
+      parameters: GREP_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'bash',
+      description: '执行 shell 命令并返回输出（stdout/stderr/退出码）。需要用户授权。',
+      parameters: BASH_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'skill',
+      description: '加载指定技能的 SKILL.md 全文；省略 name 时列出可用技能。任务与技能匹配时应先加载。',
+      parameters: SKILL_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'task',
+      description: '把独立子任务委托给一个全新上下文的子代理，返回其汇报。适合搜索调研、独立实现、复核验证等可并行的工作。',
+      parameters: TASK_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'todo',
+      description: '维护任务清单（全量替换）。多步骤任务开始前建立清单，完成一项更新一项。',
+      parameters: TODO_SCHEMA,
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'undo',
+      description: '撤销 write/edit 造成的最近一次文件修改；指定 path 则撤销该文件。',
+      parameters: UNDO_SCHEMA,
+    },
+  },
+];
+
+export function toolSchemas() {
+  return TOOLS;
+}
+
+function runSkill(args, ctx) {
+  const name = String(args.name ?? '').trim();
+  const skills = listSkills(ctx.workingDir);
+  const label = (s) => `${s.name}${s.source === 'user' ? '（用户级）' : s.source === 'builtin' ? '（内置）' : ''}`;
+  if (!name) {
+    return {
+      ok: true,
+      output: skills.length
+        ? skills.map((s) => `- ${label(s)}：${s.description || '（无描述）'}`).join('\n')
+        : '（未安装任何技能。目录：~/.mingdao/skills/、<项目>/.mingdao/skills/）',
+    };
+  }
+  const s = loadSkill(ctx.workingDir, name);
+  if (!s) {
+    return { ok: false, error: `未找到技能 "${name}"。可用：${skills.map((x) => x.name).join(', ') || '（无）'}` };
+  }
+  return { ok: true, output: `技能 ${name}${s.source === 'builtin' ? '（内置）' : ''}（${s.path}）：\n\n${s.content}` };
+}
+
+async function runTask(args, ctx) {
+  const prompt = String(args.prompt ?? '');
+  const description = String(args.description ?? '');
+  if (!prompt) return { ok: false, error: '缺少 prompt 参数。' };
+  if (typeof ctx.spawnTask !== 'function') return { ok: false, error: '当前环境不支持子代理。' };
+  try {
+    const out = await ctx.spawnTask(prompt, { description, readOnly: args.readOnly === true });
+    return { ok: true, output: out };
+  } catch (err) {
+    return { ok: false, error: `子任务失败：${err?.message || err}` };
+  }
+}
+
+function runTodo(args, ctx) {
+  const list = Array.isArray(args.todos) ? args.todos : [];
+  if (Array.isArray(ctx.todos)) {
+    ctx.todos.splice(0, ctx.todos.length, ...list);
+  }
+  return {
+    ok: true,
+    output:
+      `任务清单已更新（${list.length} 项）：\n` +
+      list.map((t) => `- [${t.status || 'pending'}] ${t.content}`).join('\n'),
+    todos: list,
+  };
+}
+
+export async function dispatch(name, args, ctx) {
+  switch (name) {
+    case 'read':
+      return read(args, ctx);
+    case 'write':
+      return write(args, ctx);
+    case 'edit':
+      return edit(args, ctx);
+    case 'ls':
+      return ls(args, ctx);
+    case 'glob':
+      return glob(args, ctx);
+    case 'grep':
+      return grep(args, ctx);
+    case 'bash':
+      return runBash(args, ctx);
+    case 'skill':
+      return runSkill(args, ctx);
+    case 'task':
+      return runTask(args, ctx);
+    case 'todo':
+      return runTodo(args, ctx);
+    case 'undo':
+      return undo(args, ctx);
+    default:
+      return { ok: false, error: `未知工具：${name}` };
+  }
+}