@mingyuxu/core 0.1.0

package/README.md

@@ -0,0 +1,7 @@
+# @mingyuxu/core
+
+doccheck-agent 的通用 Agent 运行时，提供 Agent Loop、工具调用、审批门、Sandbox、工作空间、任务计划、会话持久化和子 Agent 调度。
+
+该包不包含核查领域知识；核查领域能力由 `@mingyuxu/check` 注入。使用完整产品请安装 [`doccheck-agent`](https://www.npmjs.com/package/doccheck-agent)。
+
+完整文档与源码：[doccheck-agent](https://github.com/Mingyu-Xu-98/doccheck-agent)

package/dist/coding/agent.d.ts

@@ -0,0 +1,64 @@
+import type { LLMClient, Message } from "@mingyuxu/ai";
+import { type CodingTool, type ApprovalGate, type ExecFn } from "./tools.js";
+export declare const CODE_AGENT_SYSTEM: string;
+export interface CodeAgentEvent {
+    kind: "text" | "tool_start" | "tool_end" | "stop" | "notice";
+    text?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+    result?: string;
+}
+export interface CodeAgentOptions {
+    llm: LLMClient;
+    root: string;
+    approve: ApprovalGate;
+    tools?: CodingTool[];
+    extraTools?: CodingTool[];
+    exec?: ExecFn;
+    instructions?: string;
+    maxSteps?: number;
+    historyPath?: string;
+    onEvent?: (e: CodeAgentEvent) => void;
+    stream?: boolean;
+    workerLlm?: LLMClient;
+    maxDepth?: number;
+    depth?: number;
+}
+export declare class CodeAgent {
+    private llm;
+    private root;
+    private ctx;
+    private toolMap;
+    private schemas;
+    private instructions;
+    private maxSteps;
+    private historyPath?;
+    private onEvent;
+    private stream;
+    private opts;
+    private depth;
+    private maxDepth;
+    messages: Message[];
+    constructor(opts: CodeAgentOptions);
+    /** 一次性 LLM 文本调用（无工具、单轮）；优先 worker 模型省钱。 */
+    private askModel;
+    /** 派一个子 agent（完整工具集、独立历史、共享审批门）跑完子任务，回其结论文本。 */
+    private runSubAgent;
+    /** 当前挂载的工具名（通用 + 领域），供 UI 展示。 */
+    toolNames(): string[];
+    /** 把长历史压成一个可恢复摘要；工作产物和工具轨迹仍保留在工作空间磁盘中。 */
+    compactHistory(): Promise<{
+        before: number;
+        after: number;
+        compacted: boolean;
+    }>;
+    private system;
+    private save;
+    /** 跑一整个用户回合：接一句话 → 自主调工具推进 → 直到模型只说话（收尾）或到步数上限。 */
+    turn(userMsg: string): Promise<{
+        stop: string;
+        steps: number;
+    }>;
+    private runTool;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/coding/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/coding/agent.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAc,MAAM,cAAc,CAAC;AAEnE,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,MAAM,EAAoB,MAAM,YAAY,CAAC;AAEzH,eAAO,MAAM,iBAAiB,QAOlB,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,SAAS,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,IAAI,CAAmB;IAC/B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAM;gBAEb,IAAI,EAAE,gBAAgB;IAwBlC,2CAA2C;YAC7B,QAAQ;IAStB,gDAAgD;YAClC,WAAW;IAiBzB,iCAAiC;IACjC,SAAS,IAAI,MAAM,EAAE;IAIrB,0CAA0C;IACpC,cAAc,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAoBtF,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,IAAI;IAMZ,mDAAmD;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;YA4CvD,OAAO;CAStB"}

package/dist/coding/agent.js

@@ -0,0 +1,179 @@
+/**
+ * CodeAgent —— Claude-Code 式通用对话循环。
+ * 维护 messages[]，每轮 llm.chat(messages, {tools})：模型要调工具就执行（写/bash 过审批）
+ * 把回执喂回再循环；只说话就流式输出、结束回合。会话历史可落盘，"继续"即恢复。
+ *
+ * core 不认识核查：领域能力（build/run/eval…）由 CLI 作为 extraTools 注入，与通用工具同槽。
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { BudgetExceeded, LLMError } from "@mingyuxu/ai";
+import { Sandbox } from "../sandbox.js";
+import { codingTools, defaultExec } from "./tools.js";
+export const CODE_AGENT_SYSTEM = [
+    "你是运行在用户仓库里的通用编码 agent（类似 Claude Code），用中文对话。",
+    "你能自由对话，也能用工具动手：读写/编辑文件、搜索、跑 shell 命令。需要时就调工具，不要凭空猜文件内容。",
+    "写文件、编辑、跑命令是危险动作，会经过人工审批门——被拒就换方案或问用户，别硬来。",
+    "动手前先简短说明你要做什么；完成后向用户总结结果。多步任务自己规划、连续调工具推进，直到目标达成再收尾。",
+    "需要额外 LLM 算力时按难度选：简单纯文本活（总结/分类/起草/抽取）用 ask_model 一次搞定；较复杂、要多步动手或想隔离的活用 spawn_agent 派子 agent。琐碎的活自己做，别为了用而用。",
+    "不清楚需求、或关键决策该用户拍板时，直接发问，不要自作主张做不可逆的事。",
+].join("\n");
+export class CodeAgent {
+    llm;
+    root;
+    ctx;
+    toolMap;
+    schemas;
+    instructions;
+    maxSteps;
+    historyPath;
+    onEvent;
+    stream;
+    opts; // 存构造参数，用于派生子 agent
+    depth;
+    maxDepth;
+    messages = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.llm = opts.llm;
+        this.root = opts.root;
+        this.instructions = opts.instructions ?? "";
+        this.maxSteps = opts.maxSteps ?? 40;
+        this.historyPath = opts.historyPath;
+        this.onEvent = opts.onEvent ?? (() => { });
+        this.stream = opts.stream ?? true;
+        this.depth = opts.depth ?? 0;
+        this.maxDepth = opts.maxDepth ?? 2;
+        const tools = [...(opts.tools ?? codingTools()), ...(opts.extraTools ?? [])];
+        this.toolMap = new Map(tools.map((t) => [t.schema.name, t]));
+        this.schemas = tools.map((t) => t.schema);
+        this.ctx = {
+            root: opts.root, sandbox: new Sandbox(opts.root), approve: opts.approve, exec: opts.exec ?? defaultExec,
+            askModel: (prompt, system) => this.askModel(prompt, system),
+            spawnAgent: this.depth < this.maxDepth ? (task) => this.runSubAgent(task) : undefined,
+        };
+        if (this.historyPath && existsSync(this.historyPath)) {
+            try {
+                this.messages = JSON.parse(readFileSync(this.historyPath, "utf-8"));
+            }
+            catch {
+                this.messages = [];
+            }
+        }
+    }
+    /** 一次性 LLM 文本调用（无工具、单轮）；优先 worker 模型省钱。 */
+    async askModel(prompt, system) {
+        const client = this.opts.workerLlm ?? this.llm;
+        const msgs = [];
+        if (system)
+            msgs.push({ role: "system", content: system });
+        msgs.push({ role: "user", content: prompt });
+        const res = await client.chat(msgs); // 不传 tools / onDelta → 纯文本
+        return res.text;
+    }
+    /** 派一个子 agent（完整工具集、独立历史、共享审批门）跑完子任务，回其结论文本。 */
+    async runSubAgent(task) {
+        const sub = new CodeAgent({
+            ...this.opts,
+            historyPath: undefined, // 子 agent 独立上下文，不污染主会话
+            stream: false,
+            depth: this.depth + 1,
+            onEvent: (e) => {
+                if (e.kind === "tool_start")
+                    this.onEvent({ ...e, tool: `▸${e.tool}` });
+                else if (e.kind === "tool_end")
+                    this.onEvent(e);
+                else if (e.kind === "notice")
+                    this.onEvent(e);
+            },
+        });
+        const r = await sub.turn(task);
+        const last = [...sub.messages].reverse().find((m) => m.role === "assistant" && m.content);
+        return last?.content || `（子 agent 结束于 ${r.stop}，未产出文本结论）`;
+    }
+    /** 当前挂载的工具名（通用 + 领域），供 UI 展示。 */
+    toolNames() {
+        return [...this.toolMap.keys()];
+    }
+    /** 把长历史压成一个可恢复摘要；工作产物和工具轨迹仍保留在工作空间磁盘中。 */
+    async compactHistory() {
+        const before = this.messages.length;
+        if (before < 6)
+            return { before, after: before, compacted: false };
+        const source = this.messages.map((m) => {
+            const calls = m.role === "assistant" ? m.toolCalls : undefined;
+            const tools = calls?.length ? ` [工具: ${calls.map((t) => t.name).join(", ")}]` : "";
+            return `${m.role}${tools}: ${m.content}`;
+        }).join("\n");
+        const summary = await this.askModel(`请压缩下面的 Agent 会话。必须保留：用户最终目标、验收标准、已确认决策、已改文件、工具结果、失败原因、未完成事项、审批状态。不要补造事实。\n\n${source}`, "你是会话压缩器，只输出供另一个 Agent 无损续接工作的中文结构化摘要。");
+        this.messages = [
+            { role: "user", content: `【此前会话已压缩，以下是可信续接上下文】\n${summary}` },
+            { role: "assistant", content: "已读取续接上下文，将基于该目标、决策、磁盘产物和未完成事项继续工作。" },
+        ];
+        this.save();
+        return { before, after: this.messages.length, compacted: true };
+    }
+    system() {
+        return this.instructions ? `${this.instructions}\n\n———\n${CODE_AGENT_SYSTEM}` : CODE_AGENT_SYSTEM;
+    }
+    save() {
+        if (!this.historyPath)
+            return;
+        mkdirSync(dirname(this.historyPath), { recursive: true });
+        writeFileSync(this.historyPath, JSON.stringify(this.messages, null, 2), "utf-8");
+    }
+    /** 跑一整个用户回合：接一句话 → 自主调工具推进 → 直到模型只说话（收尾）或到步数上限。 */
+    async turn(userMsg) {
+        this.messages.push({ role: "user", content: userMsg });
+        const convo = () => [{ role: "system", content: this.system() }, ...this.messages];
+        for (let step = 0; step < this.maxSteps; step++) {
+            let res;
+            try {
+                res = await this.llm.chat(convo(), {
+                    tools: this.schemas,
+                    onDelta: this.stream ? (t) => this.onEvent({ kind: "text", text: t }) : undefined,
+                    onNotice: (m) => this.onEvent({ kind: "notice", text: m }),
+                });
+            }
+            catch (e) {
+                const reason = e instanceof BudgetExceeded ? "budget_exceeded" : e instanceof LLMError ? "llm_error" : "chat_error";
+                this.onEvent({ kind: "stop", text: `${reason}: ${e.message}` });
+                this.save();
+                return { stop: reason, steps: step };
+            }
+            if (!this.stream && res.text)
+                this.onEvent({ kind: "text", text: res.text });
+            // 无工具调用 → 本回合收尾
+            if (!res.toolCalls.length) {
+                this.messages.push({ role: "assistant", content: res.text });
+                this.save();
+                this.onEvent({ kind: "stop", text: "reply" });
+                return { stop: "reply", steps: step + 1 };
+            }
+            // 有工具调用 → 记助手消息（含 tool_calls），逐个执行并把回执喂回
+            this.messages.push({ role: "assistant", content: res.text, toolCalls: res.toolCalls });
+            for (const call of res.toolCalls) {
+                this.onEvent({ kind: "tool_start", tool: call.name, args: call.arguments });
+                const result = await this.runTool(call.name, call.arguments);
+                this.onEvent({ kind: "tool_end", tool: call.name, args: call.arguments, result });
+                this.messages.push({ role: "tool", toolCallId: call.id, content: result });
+            }
+            this.save();
+        }
+        this.onEvent({ kind: "stop", text: "max_steps" });
+        this.save();
+        return { stop: "max_steps", steps: this.maxSteps };
+    }
+    async runTool(name, args) {
+        const tool = this.toolMap.get(name);
+        if (!tool)
+            return `未知工具：${name}（可用：${[...this.toolMap.keys()].join(", ")}）`;
+        try {
+            return await tool.run(args, this.ctx);
+        }
+        catch (e) {
+            return `工具 ${name} 失败：${e.name}: ${e.message}`;
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/coding/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/coding/agent.ts"],"names":[],"mappings":"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"}

package/dist/coding/tools.d.ts

@@ -0,0 +1,45 @@
+import type { ToolSchema } from "@mingyuxu/ai";
+import { Sandbox } from "../sandbox.js";
+/** 审批门：mutating 工具执行前询问；返回 false 则拒绝执行。TUI 弹 y/n，headless 按策略。 */
+export type ApprovalGate = (req: {
+    tool: string;
+    summary: string;
+    args: Record<string, unknown>;
+}) => boolean | Promise<boolean>;
+/** shell 执行器（可注入，测试用桩）。返回合并输出与退出码。 */
+export type ExecFn = (command: string, opts: {
+    cwd: string;
+    timeoutMs: number;
+}) => Promise<{
+    output: string;
+    code: number;
+}>;
+export interface ToolContext {
+    root: string;
+    sandbox: Sandbox;
+    approve: ApprovalGate;
+    exec: ExecFn;
+    /** 一次性 LLM 文本子调用（ask_model 用）。由 CodeAgent 注入；未注入则工具报"未启用"。 */
+    askModel?: (prompt: string, system?: string) => Promise<string>;
+    /** 派子 agent 跑一个多步子任务，返回结论（spawn_agent 用）。由 CodeAgent 注入。 */
+    spawnAgent?: (task: string) => Promise<string>;
+}
+export interface CodingTool {
+    schema: ToolSchema;
+    mutating: boolean;
+    run(args: Record<string, unknown>, ctx: ToolContext): Promise<string>;
+}
+export declare const READ_FILE: CodingTool;
+export declare const LIST_DIR: CodingTool;
+export declare const GLOB: CodingTool;
+export declare const GREP: CodingTool;
+export declare const WRITE_FILE: CodingTool;
+export declare const EDIT_FILE: CodingTool;
+export declare const BASH: CodingTool;
+export declare const ASK_MODEL: CodingTool;
+export declare const SPAWN_AGENT: CodingTool;
+/** 全部通用编码工具（含 LLM 子调用 ask_model / spawn_agent）。 */
+export declare function codingTools(): CodingTool[];
+/** 默认 shell 执行器：/bin/sh -c，合并 stdout/stderr。 */
+export declare const defaultExec: ExecFn;
+//# sourceMappingURL=tools.d.ts.map

package/dist/coding/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/coding/tools.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAoB,MAAM,eAAe,CAAC;AAE1D,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjI,sCAAsC;AACtC,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE9H,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,4DAA4D;IAC5D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AA8CD,eAAO,MAAM,SAAS,EAAE,UAyBvB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,UAiBtB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,UAclB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,UAiClB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,UAsBxB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,UAiCvB,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,UAqBlB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,UAmBvB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,UAkBzB,CAAC;AAEF,mDAAmD;AACnD,wBAAgB,WAAW,IAAI,UAAU,EAAE,CAE1C;AAED,gDAAgD;AAChD,eAAO,MAAM,WAAW,EAAE,MAOtB,CAAC"}

package/dist/coding/tools.js

@@ -0,0 +1,327 @@
+/**
+ * 通用编码工具集（Claude-Code 式）—— 让通用 agent 能读/写/编辑文件、搜索、跑命令。
+ * 读类自动放行；写/编辑/bash 是 mutating，执行前过 ApprovalGate（人工审批门）。
+ * 所有文件路径经 Sandbox 约束在工作根内，越界 fail-closed。bash 是唯一逃逸口（仍需审批）。
+ */
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { resolve, relative, join, dirname, isAbsolute } from "node:path";
+import { execFile } from "node:child_process";
+import { SandboxViolation } from "../sandbox.js";
+const MAX_OUTPUT = 30_000; // 单次工具结果上限，护住 agent 上下文
+const SKIP_DIRS = new Set([".git", "node_modules", "dist", ".vet", ".session"]);
+function clip(s) {
+    return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + `\n…（已截断，共 ${s.length} 字）` : s;
+}
+/** 解析并校验路径在工作根内，返回绝对路径；越界抛 SandboxViolation。 */
+function within(ctx, path) {
+    const abs = isAbsolute(path) ? resolve(path) : resolve(ctx.root, path);
+    if (!ctx.sandbox.contains(abs))
+        throw new SandboxViolation(`路径越界：${abs} 不在工作根 ${ctx.root} 内`);
+    return abs;
+}
+function walk(dir, root, out, cap) {
+    if (out.length >= cap)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (SKIP_DIRS.has(name))
+            continue;
+        const full = join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walk(full, root, out, cap);
+        else
+            out.push(relative(root, full));
+        if (out.length >= cap)
+            return;
+    }
+}
+/** glob 通配 → 正则（支持 ** / * / ?）。 */
+function globToRe(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i++;
+                if (glob[i + 1] === "/")
+                    i++;
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else if (".+^${}()|[]\\".includes(c))
+            re += "\\" + c;
+        else
+            re += c;
+    }
+    return new RegExp("^" + re + "$");
+}
+export const READ_FILE = {
+    mutating: false,
+    schema: {
+        name: "read_file",
+        description: "读取工作根内某个文件的内容。可选 offset/limit 按行截取。",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "相对工作根或绝对路径（须在工作根内）" },
+                offset: { type: "integer", description: "起始行（1 基），可选" },
+                limit: { type: "integer", description: "读取行数，可选" },
+            },
+            required: ["path"],
+        },
+    },
+    async run(args, ctx) {
+        const abs = within(ctx, String(args.path));
+        if (!existsSync(abs))
+            return `文件不存在：${args.path}`;
+        const raw = readFileSync(abs, "utf-8");
+        const lines = raw.split("\n");
+        const off = args.offset ? Math.max(1, Number(args.offset)) : 1;
+        const lim = args.limit ? Number(args.limit) : lines.length;
+        const slice = lines.slice(off - 1, off - 1 + lim);
+        return clip(slice.map((l, i) => `${off + i}\t${l}`).join("\n"));
+    },
+};
+export const LIST_DIR = {
+    mutating: false,
+    schema: {
+        name: "list_dir",
+        description: "列出目录下的条目（不递归）。",
+        parameters: { type: "object", properties: { path: { type: "string", description: "目录路径，默认工作根" } } },
+    },
+    async run(args, ctx) {
+        const abs = within(ctx, String(args.path ?? "."));
+        if (!existsSync(abs))
+            return `目录不存在：${args.path ?? "."}`;
+        const entries = readdirSync(abs).map((n) => {
+            let dir = false;
+            try {
+                dir = statSync(join(abs, n)).isDirectory();
+            }
+            catch { /* ignore */ }
+            return dir ? n + "/" : n;
+        });
+        return clip(entries.sort().join("\n") || "（空目录）");
+    },
+};
+export const GLOB = {
+    mutating: false,
+    schema: {
+        name: "glob",
+        description: "按通配模式查找文件（支持 ** / * / ?），返回相对路径列表。",
+        parameters: { type: "object", properties: { pattern: { type: "string", description: "如 src/**/*.ts" } }, required: ["pattern"] },
+    },
+    async run(args, ctx) {
+        const re = globToRe(String(args.pattern));
+        const all = [];
+        walk(ctx.root, ctx.root, all, 5000);
+        const hits = all.filter((p) => re.test(p)).slice(0, 500);
+        return clip(hits.join("\n") || "（无匹配）");
+    },
+};
+export const GREP = {
+    mutating: false,
+    schema: {
+        name: "grep",
+        description: "在文件内容里正则搜索，返回 文件:行号:内容。可选 glob 限定文件范围。",
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: { type: "string", description: "正则表达式" },
+                glob: { type: "string", description: "限定文件的通配，如 *.ts，可选" },
+            },
+            required: ["pattern"],
+        },
+    },
+    async run(args, ctx) {
+        let re;
+        try {
+            re = new RegExp(String(args.pattern));
+        }
+        catch (e) {
+            return `非法正则：${e.message}`;
+        }
+        const fileRe = args.glob ? globToRe(String(args.glob).includes("/") ? String(args.glob) : "**/" + String(args.glob)) : null;
+        const files = [];
+        walk(ctx.root, ctx.root, files, 5000);
+        const out = [];
+        for (const rel of files) {
+            if (fileRe && !fileRe.test(rel))
+                continue;
+            let text;
+            try {
+                text = readFileSync(join(ctx.root, rel), "utf-8");
+            }
+            catch {
+                continue;
+            }
+            const lines = text.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                if (re.test(lines[i])) {
+                    out.push(`${rel}:${i + 1}:${lines[i].slice(0, 200)}`);
+                    if (out.length >= 200)
+                        break;
+                }
+            }
+            if (out.length >= 200)
+                break;
+        }
+        return clip(out.join("\n") || "（无匹配）");
+    },
+};
+export const WRITE_FILE = {
+    mutating: true,
+    schema: {
+        name: "write_file",
+        description: "写入（覆盖）工作根内的文件，自动建目录。危险操作，执行前需人工审批。",
+        parameters: {
+            type: "object",
+            properties: { path: { type: "string" }, content: { type: "string" } },
+            required: ["path", "content"],
+        },
+    },
+    async run(args, ctx) {
+        const path = String(args.path);
+        const content = String(args.content ?? "");
+        const abs = within(ctx, path);
+        const existed = existsSync(abs);
+        const ok = await ctx.approve({ tool: "write_file", summary: `${existed ? "覆盖" : "新建"} ${path}（${content.length} 字）`, args });
+        if (!ok)
+            return `用户拒绝了写入 ${path}`;
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content, "utf-8");
+        return `✓ 已${existed ? "覆盖" : "写入"} ${path}（${content.length} 字）`;
+    },
+};
+export const EDIT_FILE = {
+    mutating: true,
+    schema: {
+        name: "edit_file",
+        description: "把文件里的 old 文本替换为 new。默认要求 old 唯一匹配；replace_all=true 则全替。执行前需人工审批。",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                old: { type: "string", description: "要替换的原文（含足够上下文以唯一定位）" },
+                new: { type: "string", description: "替换后的新文本" },
+                replace_all: { type: "boolean", description: "是否全部替换，默认 false" },
+            },
+            required: ["path", "old", "new"],
+        },
+    },
+    async run(args, ctx) {
+        const path = String(args.path);
+        const abs = within(ctx, path);
+        if (!existsSync(abs))
+            return `文件不存在：${path}`;
+        const oldStr = String(args.old);
+        const newStr = String(args.new ?? "");
+        const all = Boolean(args.replace_all);
+        const raw = readFileSync(abs, "utf-8");
+        const count = oldStr ? raw.split(oldStr).length - 1 : 0;
+        if (count === 0)
+            return `未找到要替换的文本，未改动 ${path}`;
+        if (count > 1 && !all)
+            return `old 文本在 ${path} 命中 ${count} 处，非唯一。补足上下文或设 replace_all=true。`;
+        const ok = await ctx.approve({ tool: "edit_file", summary: `编辑 ${path}（替换 ${all ? count : 1} 处）`, args });
+        if (!ok)
+            return `用户拒绝了编辑 ${path}`;
+        const next = all ? raw.split(oldStr).join(newStr) : raw.replace(oldStr, newStr);
+        writeFileSync(abs, next, "utf-8");
+        return `✓ 已编辑 ${path}（替换 ${all ? count : 1} 处）`;
+    },
+};
+export const BASH = {
+    mutating: true,
+    schema: {
+        name: "bash",
+        description: "在工作根内执行一条 shell 命令并返回输出。执行前需人工审批。",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string" },
+                timeout_ms: { type: "integer", description: "超时毫秒，默认 120000" },
+            },
+            required: ["command"],
+        },
+    },
+    async run(args, ctx) {
+        const command = String(args.command);
+        const ok = await ctx.approve({ tool: "bash", summary: command.slice(0, 200), args });
+        if (!ok)
+            return `用户拒绝了执行：${command}`;
+        const { output, code } = await ctx.exec(command, { cwd: ctx.root, timeoutMs: args.timeout_ms ? Number(args.timeout_ms) : 120_000 });
+        return clip(`[退出码 ${code}]\n${output}`);
+    },
+};
+export const ASK_MODEL = {
+    mutating: false,
+    schema: {
+        name: "ask_model",
+        description: "一次性调用 LLM 完成一个纯文本子任务（总结/分类/起草/翻译/抽取等），无工具、不读写文件、不多轮。适合简单、独立、给定输入就能出答案的思考活；默认走更省的 worker 模型。复杂或需要动手的活用 spawn_agent。",
+        parameters: {
+            type: "object",
+            properties: {
+                prompt: { type: "string", description: "交给模型的完整输入（把要处理的内容也带上）" },
+                system: { type: "string", description: "可选的系统指令（角色/输出格式约束）" },
+            },
+            required: ["prompt"],
+        },
+    },
+    async run(args, ctx) {
+        if (!ctx.askModel)
+            return "未启用 LLM 子调用（ask_model 需由 CodeAgent 注入）。";
+        const out = await ctx.askModel(String(args.prompt), args.system ? String(args.system) : undefined);
+        return clip(out || "（模型无输出）");
+    },
+};
+export const SPAWN_AGENT = {
+    mutating: false, // 委派本身不改文件；子 agent 的写/命令仍逐个走同一审批门
+    schema: {
+        name: "spawn_agent",
+        description: "派一个子 agent 独立完成一个多步子任务（它有完整工具集：读写/编辑/搜索/跑命令/再委派），跑完只把结论回给你。适合较复杂、需要动手、可隔离的活，能保持你自己的上下文干净。子 agent 的危险操作仍会向用户请求审批。简单纯文本活请用 ask_model。",
+        parameters: {
+            type: "object",
+            properties: {
+                task: { type: "string", description: "子任务的完整描述：要做什么、约束、期望产出。子 agent 看不到你当前对话，务必自足。" },
+            },
+            required: ["task"],
+        },
+    },
+    async run(args, ctx) {
+        if (!ctx.spawnAgent)
+            return "未启用子 agent（spawn_agent 需由 CodeAgent 注入，或已达嵌套深度上限）。";
+        const out = await ctx.spawnAgent(String(args.task));
+        return clip(out || "（子 agent 未产出结论）");
+    },
+};
+/** 全部通用编码工具（含 LLM 子调用 ask_model / spawn_agent）。 */
+export function codingTools() {
+    return [READ_FILE, LIST_DIR, GLOB, GREP, WRITE_FILE, EDIT_FILE, BASH, ASK_MODEL, SPAWN_AGENT];
+}
+/** 默认 shell 执行器：/bin/sh -c，合并 stdout/stderr。 */
+export const defaultExec = (command, opts) => new Promise((res) => {
+    execFile("/bin/sh", ["-c", command], { cwd: opts.cwd, timeout: opts.timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const output = (stdout ?? "") + (stderr ? (stdout ? "\n" : "") + stderr : "");
+        const code = err && typeof err.code === "number" ? err.code : err ? 1 : 0;
+        res({ output: output || "（无输出）", code });
+    });
+});
+//# sourceMappingURL=tools.js.map