@jpssff/vanor 0.1.0

package/base/tools/builtin.js

@@ -0,0 +1,221 @@
+// 内置工具（MVP）：read_file / write_file / edit_file / list_dir / exec。
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createI18n } from "../i18n/index.js";
+import { ensureDir } from "../utils.js";
+
+const MAX_OUTPUT = 100_000;
+const defaultI18n = createI18n("en");
+
+function ok(content) {
+  return { content: String(content) };
+}
+function fail(content) {
+  return { content: String(content), isError: true };
+}
+
+const readFile = {
+  name: "read_file",
+  description: "Read text content from a workspace file, optionally by line offset/limit.",
+  danger: "safe",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Relative workspace path or absolute path" },
+      offset: { type: "integer", description: "Start line (1-based)" },
+      limit: { type: "integer", description: "Number of lines to read" },
+    },
+    required: ["path"],
+  },
+  handler(args, ctx) {
+    const r = ctx.security.checkPath(args.path, { mustExist: true });
+    if (!r.ok) return fail(r.reason);
+    let text;
+    try {
+      text = fs.readFileSync(r.abs, "utf8");
+    } catch (e) {
+      return fail(ctx.t("builtin.readFailed", { message: e.message }));
+    }
+    if (args.offset || args.limit) {
+      const lines = text.split("\n");
+      const start = Math.max(0, (args.offset || 1) - 1);
+      const end = args.limit ? start + args.limit : lines.length;
+      text = lines.slice(start, end).join("\n");
+    }
+    if (text.length > MAX_OUTPUT) {
+      text = text.slice(0, MAX_OUTPUT) + `\n${ctx.t("builtin.truncatedContent")}`;
+    }
+    return ok(text || ctx.t("builtin.emptyFile"));
+  },
+};
+
+const writeFile = {
+  name: "write_file",
+  description: "Write or overwrite a workspace file and create parent directories automatically.",
+  danger: "confirm",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      content: { type: "string" },
+    },
+    required: ["path", "content"],
+  },
+  handler(args, ctx) {
+    const r = ctx.security.checkPath(args.path);
+    if (!r.ok) return fail(r.reason);
+    try {
+      ensureDir(path.dirname(r.abs));
+      fs.writeFileSync(r.abs, args.content ?? "");
+    } catch (e) {
+      return fail(ctx.t("builtin.writeFailed", { message: e.message }));
+    }
+    return ok(ctx.t("builtin.written", { path: args.path, bytes: Buffer.byteLength(args.content ?? "") }));
+  },
+};
+
+const editFile = {
+  name: "edit_file",
+  description: "Replace the unique occurrence of old_string with new_string in a file.",
+  danger: "confirm",
+  parameters: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      old_string: { type: "string" },
+      new_string: { type: "string" },
+    },
+    required: ["path", "old_string", "new_string"],
+  },
+  handler(args, ctx) {
+    const r = ctx.security.checkPath(args.path, { mustExist: true });
+    if (!r.ok) return fail(r.reason);
+    let text;
+    try {
+      text = fs.readFileSync(r.abs, "utf8");
+    } catch (e) {
+      return fail(ctx.t("builtin.readFailed", { message: e.message }));
+    }
+    const parts = text.split(args.old_string);
+    if (parts.length === 1) return fail(ctx.t("builtin.oldStringNotFound"));
+    if (parts.length > 2) return fail(ctx.t("builtin.oldStringNotUnique", { count: parts.length - 1 }));
+    try {
+      fs.writeFileSync(r.abs, parts.join(args.new_string));
+    } catch (e) {
+      return fail(ctx.t("builtin.writeFailed", { message: e.message }));
+    }
+    return ok(ctx.t("builtin.edited", { path: args.path }));
+  },
+};
+
+const listDir = {
+  name: "list_dir",
+  description: "List directory contents.",
+  danger: "safe",
+  parameters: {
+    type: "object",
+    properties: { path: { type: "string" } },
+    required: ["path"],
+  },
+  handler(args, ctx) {
+    const r = ctx.security.checkPath(args.path, { mustExist: true, dir: true });
+    if (!r.ok) return fail(r.reason);
+    let entries;
+    try {
+      entries = fs.readdirSync(r.abs, { withFileTypes: true });
+    } catch (e) {
+      return fail(ctx.t("builtin.readFailed", { message: e.message }));
+    }
+    const lines = entries
+      .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+      .sort();
+    return ok(lines.length ? lines.join("\n") : ctx.t("builtin.emptyDir"));
+  },
+};
+
+const exec = {
+  name: "exec",
+  description: "Run a shell command in the workspace and return its output. Subject to allowlist/denylist and approval.",
+  danger: "confirm",
+  exclusive: true,
+  parameters: {
+    type: "object",
+    properties: {
+      command: { type: "string" },
+      cwd: { type: "string", description: "Working directory, defaults to workspace root" },
+      timeout: { type: "integer", description: "Timeout in milliseconds, defaults to 60000" },
+    },
+    required: ["command"],
+  },
+  handler(args, ctx) {
+    let cwd = ctx.security.workspaceRoot;
+    if (args.cwd) {
+      const r = ctx.security.checkPath(args.cwd, { mustExist: true, dir: true });
+      if (!r.ok) return fail(r.reason);
+      cwd = r.abs;
+    }
+    return new Promise((resolve) => {
+      let child;
+      try {
+        child = spawn(args.command, { shell: true, cwd, signal: ctx.signal });
+      } catch (e) {
+        return resolve(fail(ctx.t("builtin.spawnFailed", { message: e.message })));
+      }
+      let out = "";
+      let truncated = false;
+      const onData = (d) => {
+        if (out.length < MAX_OUTPUT) out += d.toString();
+        else truncated = true;
+      };
+      child.stdout?.on("data", onData);
+      child.stderr?.on("data", onData);
+      const timer = setTimeout(() => child.kill("SIGKILL"), args.timeout || 60000);
+      child.on("error", (e) => {
+        clearTimeout(timer);
+        if (e.name === "AbortError") resolve(fail(ctx.t("builtin.commandAborted")));
+        else resolve(fail(ctx.t("builtin.execFailed", { message: e.message })));
+      });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        const note = truncated ? `\n${ctx.t("builtin.outputTruncated")}` : "";
+        resolve({
+          content: `${out || ctx.t("builtin.noOutput")}${note}\n${ctx.t("builtin.exitCode", { code })}`,
+          isError: code !== 0,
+        });
+      });
+    });
+  },
+};
+
+function withParameters(tool, properties) {
+  return {
+    ...tool,
+    parameters: {
+      ...tool.parameters,
+      properties: {
+        ...tool.parameters.properties,
+        ...properties,
+      },
+    },
+  };
+}
+
+export function builtinTools(i18n = defaultI18n) {
+  const { t } = i18n;
+  return [
+    withParameters({ ...readFile, description: t("builtin.readFileDescription") }, {
+      path: { ...readFile.parameters.properties.path, description: t("builtin.pathDescription") },
+      offset: { ...readFile.parameters.properties.offset, description: t("builtin.offsetDescription") },
+      limit: { ...readFile.parameters.properties.limit, description: t("builtin.limitDescription") },
+    }),
+    { ...writeFile, description: t("builtin.writeFileDescription") },
+    { ...editFile, description: t("builtin.editFileDescription") },
+    { ...listDir, description: t("builtin.listDirDescription") },
+    withParameters({ ...exec, description: t("builtin.execDescription") }, {
+      cwd: { ...exec.parameters.properties.cwd, description: t("builtin.cwdDescription") },
+      timeout: { ...exec.parameters.properties.timeout, description: t("builtin.timeoutDescription") },
+    }),
+  ];
+}

package/base/tools/index.js

@@ -0,0 +1,157 @@
+// 工具注册表、参数校验、审批与执行。
+
+import { EVENTS } from "../events.js";
+import { createI18n } from "../i18n/index.js";
+import { validateSchema } from "../utils.js";
+import { toolMessage } from "../transport/message.js";
+import { builtinTools } from "./builtin.js";
+
+const defaultI18n = createI18n("en");
+
+export class ToolRegistry {
+  constructor() {
+    this.tools = new Map();
+  }
+  register(tool) {
+    this.tools.set(tool.name, tool);
+    return this;
+  }
+  registerAll(list) {
+    for (const t of list) this.register(t);
+    return this;
+  }
+  get(name) {
+    return this.tools.get(name);
+  }
+  has(name) {
+    return this.tools.has(name);
+  }
+  /** 返回供 LLM 使用的 schema 列表。 */
+  schemas() {
+    return [...this.tools.values()].map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    }));
+  }
+}
+
+export function defaultRegistry(i18n = defaultI18n) {
+  return new ToolRegistry().registerAll(builtinTools(i18n));
+}
+
+/**
+ * 构造工具执行上下文。
+ * @param {object} o
+ * @param {object} o.security  createSecurity 的返回
+ * @param {object} o.logger
+ * @param {AbortSignal} [o.signal]
+ * @param {(msg:string)=>Promise<boolean>} [o.confirm] 交互式确认回调
+ */
+export function createToolContext({ security, logger, signal, confirm, i18n = defaultI18n }) {
+  return {
+    security,
+    logger,
+    signal,
+    confirm: confirm || (async () => false),
+    i18n,
+    t: i18n.t,
+  };
+}
+
+function describe(call, t) {
+  const a = call.arguments || {};
+  switch (call.name) {
+    case "exec":
+      return t("tools.describeExec", { command: a.command });
+    case "write_file":
+      return t("tools.describeWriteFile", { path: a.path });
+    case "edit_file":
+      return t("tools.describeEditFile", { path: a.path });
+    case "skills":
+      return t("tools.describeSkills", { action: a.action, name: a.name ? ` ${a.name}` : "" });
+    default:
+      return t("tools.describeGeneric", { name: call.name });
+  }
+}
+
+/** 审批决策：返回 true 放行，false 拒绝。 */
+async function approve(tool, call, ctx) {
+  const danger = typeof tool.danger === "function" ? tool.danger(call.arguments || {}) : tool.danger;
+  if (danger === "safe") return true;
+  const decision =
+    call.name === "exec"
+      ? ctx.security.checkCommand(String(call.arguments?.command || ""))
+      : ctx.security.approvalMode();
+  if (decision === "allow") return true;
+  if (decision === "deny") return false;
+  return ctx.confirm(describe(call, ctx.t));
+}
+
+/** 执行单个工具调用，始终返回一条 tool 消息。 */
+export async function runToolCall(call, registry, ctx) {
+  const tool = registry.get(call.name);
+  if (!tool) {
+    return toolMessage({
+      toolCallId: call.id,
+      name: call.name,
+      content: ctx.t("tools.unknownTool", { name: call.name }),
+      isError: true,
+    });
+  }
+
+  const errs = validateSchema(tool.parameters, call.arguments || {}, "", ctx.t);
+  if (errs.length) {
+    return toolMessage({
+      toolCallId: call.id,
+      name: call.name,
+      content: ctx.t("tools.invalidArgs", { errors: errs.join("; ") }),
+      isError: true,
+    });
+  }
+
+  const allowed = await approve(tool, call, ctx);
+  if (!allowed) {
+    ctx.logger.warn(EVENTS.tool.denied, { name: call.name });
+    return toolMessage({
+      toolCallId: call.id,
+      name: call.name,
+      content: ctx.t("tools.denied"),
+      isError: true,
+    });
+  }
+
+  ctx.logger.info(EVENTS.tool.call, { name: call.name, id: call.id });
+  try {
+    const res = await tool.handler(call.arguments || {}, ctx);
+    ctx.logger.info(EVENTS.tool.result, { name: call.name, isError: !!res.isError });
+    return toolMessage({
+      toolCallId: call.id,
+      name: call.name,
+      content: res.content,
+      isError: !!res.isError,
+    });
+  } catch (e) {
+    ctx.logger.error(EVENTS.tool.error, { name: call.name, error: e.message });
+    return toolMessage({
+      toolCallId: call.id,
+      name: call.name,
+      content: ctx.t("tools.exception", { message: e.message }),
+      isError: true,
+    });
+  }
+}
+
+/**
+ * 顺序执行多个工具调用（MVP 串行，保证审批与输出有序；v2 再做并行）。
+ * @param {(call,result)=>void} [onResult] 每条结果回调（用于 UI 展示）
+ */
+export async function runToolCalls(toolCalls, registry, ctx, onResult) {
+  const out = [];
+  for (const call of toolCalls) {
+    const msg = await runToolCall(call, registry, ctx);
+    if (onResult) onResult(call, msg);
+    out.push(msg);
+  }
+  return out;
+}