minimal-agent 0.2.0 → 0.3.0

package/src/ui/textBuffer.js

@@ -0,0 +1,217 @@
+/**
+ * ============================================================
+ *  src/ui/textBuffer.ts —— 输入框文本缓冲（纯逻辑，无 React）
+ * ------------------------------------------------------------
+ *  把"光标 + 文本"建模成一对值 { text, cursor }：
+ *    - text 是 user-perceived 字符串（可含 \n，多行也行）
+ *    - cursor 是 **code-point 偏移**（非 UTF-16），保证不会切坏 emoji / 中日韩
+ *
+ *  所有 op 都是纯函数：返回新的 { text, cursor }，不改入参。
+ *  这样 React 端用 useState 包一下就行；测试也直接对纯函数断言、零依赖。
+ *
+ *  支持的操作：
+ *    - 插入：insert / setText / clear
+ *    - 删除：deleteBefore（Backspace）/ deleteAt（Delete）
+ *           / killToLineStart（Ctrl+U）/ killToLineEnd（Ctrl+K）
+ *           / deleteWordBefore（Ctrl+W）
+ *    - 移动：moveLeft / moveRight / moveWordLeft / moveWordRight
+ *           / moveLineStart / moveLineEnd
+ *           / moveBufferStart / moveBufferEnd
+ *           / moveUp / moveDown（按逻辑行，跨 \n，保持列位）
+ *
+ *  词边界定义（够用即可，不学完整 vim/emacs）：
+ *    [A-Za-z0-9_] 视为 word char；其他（空格、标点、CJK、emoji）都是 non-word。
+ *    word-jump 的语义对齐多数 emacs：先吃当前侧的 non-word，再吃 word。
+ * ============================================================
+ */
+export const EMPTY_BUFFER = { text: '', cursor: 0 };
+// ---------- 工具：code-point 视角操作字符串 ----------
+/** 把字符串拆成 code-point 数组（Array.from 自动处理 surrogate pair） */
+function toCps(s) {
+    return Array.from(s);
+}
+function fromCps(cps) {
+    return cps.join('');
+}
+function isWordChar(c) {
+    if (!c)
+        return false;
+    return /[A-Za-z0-9_]/.test(c);
+}
+/** 给定 code-point 数组与一个偏移，返回所在逻辑行的起点（指向 \n 之后或 0） */
+function findLineStart(cps, idx) {
+    let i = idx;
+    while (i > 0 && cps[i - 1] !== '\n')
+        i--;
+    return i;
+}
+/** 给定 code-point 数组与一个偏移，返回所在逻辑行的终点（指向 \n 或末尾） */
+function findLineEnd(cps, idx) {
+    let i = idx;
+    while (i < cps.length && cps[i] !== '\n')
+        i++;
+    return i;
+}
+/** 把 cursor 钳制到合法范围 */
+function clamp(cps, idx) {
+    return Math.max(0, Math.min(cps.length, idx));
+}
+// ---------- 插入 ----------
+export function bufInsert(s, content) {
+    if (content.length === 0)
+        return s;
+    const cps = toCps(s.text);
+    const ins = toCps(content);
+    cps.splice(s.cursor, 0, ...ins);
+    return { text: fromCps(cps), cursor: s.cursor + ins.length };
+}
+export function bufSetText(text) {
+    return { text, cursor: toCps(text).length };
+}
+export function bufClear() {
+    return EMPTY_BUFFER;
+}
+// ---------- 删除 ----------
+export function bufDeleteBefore(s) {
+    if (s.cursor === 0)
+        return s;
+    const cps = toCps(s.text);
+    cps.splice(s.cursor - 1, 1);
+    return { text: fromCps(cps), cursor: s.cursor - 1 };
+}
+export function bufDeleteAt(s) {
+    const cps = toCps(s.text);
+    if (s.cursor >= cps.length)
+        return s;
+    cps.splice(s.cursor, 1);
+    return { text: fromCps(cps), cursor: s.cursor };
+}
+/**
+ * Ctrl+W / M-DEL：先吃光标左侧的非词字符（空格 / 标点），再吃前一个词。
+ * 例：光标贴在 "world" 后 → 删 'world'，留 "hello   "。
+ *     光标在 "hello   " 之后 → 先吃 3 空格再吃 "hello"，留空。
+ */
+export function bufDeleteWordBefore(s) {
+    if (s.cursor === 0)
+        return s;
+    const cps = toCps(s.text);
+    let i = s.cursor;
+    while (i > 0 && !isWordChar(cps[i - 1]))
+        i--;
+    while (i > 0 && isWordChar(cps[i - 1]))
+        i--;
+    cps.splice(i, s.cursor - i);
+    return { text: fromCps(cps), cursor: i };
+}
+/** Ctrl+U：从光标删到当前逻辑行行首 */
+export function bufKillToLineStart(s) {
+    const cps = toCps(s.text);
+    const lineStart = findLineStart(cps, s.cursor);
+    if (lineStart === s.cursor)
+        return s;
+    cps.splice(lineStart, s.cursor - lineStart);
+    return { text: fromCps(cps), cursor: lineStart };
+}
+/** Ctrl+K：从光标删到当前逻辑行行末（不删 \n 自身） */
+export function bufKillToLineEnd(s) {
+    const cps = toCps(s.text);
+    const lineEnd = findLineEnd(cps, s.cursor);
+    if (lineEnd === s.cursor)
+        return s;
+    cps.splice(s.cursor, lineEnd - s.cursor);
+    return { text: fromCps(cps), cursor: s.cursor };
+}
+// ---------- 移动 ----------
+export function bufMoveLeft(s) {
+    return { text: s.text, cursor: Math.max(0, s.cursor - 1) };
+}
+export function bufMoveRight(s) {
+    const len = toCps(s.text).length;
+    return { text: s.text, cursor: Math.min(len, s.cursor + 1) };
+}
+export function bufMoveWordLeft(s) {
+    const cps = toCps(s.text);
+    let i = s.cursor;
+    while (i > 0 && !isWordChar(cps[i - 1]))
+        i--;
+    while (i > 0 && isWordChar(cps[i - 1]))
+        i--;
+    return { text: s.text, cursor: i };
+}
+export function bufMoveWordRight(s) {
+    const cps = toCps(s.text);
+    let i = s.cursor;
+    while (i < cps.length && !isWordChar(cps[i]))
+        i++;
+    while (i < cps.length && isWordChar(cps[i]))
+        i++;
+    return { text: s.text, cursor: i };
+}
+export function bufMoveLineStart(s) {
+    const cps = toCps(s.text);
+    return { text: s.text, cursor: findLineStart(cps, s.cursor) };
+}
+export function bufMoveLineEnd(s) {
+    const cps = toCps(s.text);
+    return { text: s.text, cursor: findLineEnd(cps, s.cursor) };
+}
+export function bufMoveBufferStart(s) {
+    return { text: s.text, cursor: 0 };
+}
+export function bufMoveBufferEnd(s) {
+    return { text: s.text, cursor: toCps(s.text).length };
+}
+/** ↑：上移一个逻辑行，保留列位（目标行短就贴行末） */
+export function bufMoveUp(s) {
+    const cps = toCps(s.text);
+    const lineStart = findLineStart(cps, s.cursor);
+    if (lineStart === 0)
+        return s; // 已在首行
+    const prevLineEnd = lineStart - 1; // 指向上一行末尾的 \n
+    const prevLineStart = findLineStart(cps, prevLineEnd);
+    const col = s.cursor - lineStart;
+    const prevLineLen = prevLineEnd - prevLineStart;
+    return { text: s.text, cursor: prevLineStart + Math.min(col, prevLineLen) };
+}
+/** ↓：下移一个逻辑行，保留列位 */
+export function bufMoveDown(s) {
+    const cps = toCps(s.text);
+    const lineStart = findLineStart(cps, s.cursor);
+    const lineEnd = findLineEnd(cps, s.cursor);
+    if (lineEnd === cps.length)
+        return s; // 已在末行
+    const nextLineStart = lineEnd + 1;
+    const nextLineEnd = findLineEnd(cps, nextLineStart);
+    const col = s.cursor - lineStart;
+    const nextLineLen = nextLineEnd - nextLineStart;
+    return { text: s.text, cursor: nextLineStart + Math.min(col, nextLineLen) };
+}
+/**
+ * 给定一个 BufferState，算出它的可视布局。
+ * 渲染端拿到 lines + cursorRow/Col 就能把光标绘制在正确位置。
+ */
+export function layoutBuffer(s) {
+    const cps = toCps(s.text);
+    const cursor = clamp(cps, s.cursor);
+    const lineStart = findLineStart(cps, cursor);
+    // 把 cps 按 \n 分行（保持 code-point 视角，避免 surrogate pair 撕裂）
+    const lines = [];
+    let buf = [];
+    let cursorRow = 0;
+    let charCount = 0;
+    for (const ch of cps) {
+        if (ch === '\n') {
+            lines.push(fromCps(buf));
+            buf = [];
+            if (charCount < lineStart)
+                cursorRow++;
+        }
+        else {
+            buf.push(ch);
+        }
+        charCount++;
+    }
+    lines.push(fromCps(buf));
+    const cursorCol = cursor - lineStart;
+    return { lines, cursorRow, cursorCol };
+}

package/src/utils/packageRoot.js

@@ -0,0 +1,37 @@
+/**
+ * ============================================================
+ *  src/utils/packageRoot.ts —— 定位 minimal-agent 包根目录
+ * ------------------------------------------------------------
+ *  问题：bundle 后 import.meta.url 指向 dist/main.js，
+ *  源码模式则指向 src/<deep>/*.ts，两者深度不同。
+ *  固定 `join(__dirname, '..', '..')` 在某一种模式下必然错。
+ *
+ *  方案：从调用方文件起向上找最近的 package.json，把那一层
+ *  当作包根。源码模式（src/prompts、src/tools/grep）、bundle
+ *  模式（dist/main.js）、全局安装（node_modules/minimal-agent/dist）
+ *  全都自动适配。
+ * ============================================================
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const cache = new Map();
+/** 向上最多翻 8 级；超过仍找不到视为环境异常。 */
+const MAX_DEPTH = 8;
+export function findPackageRoot(metaUrl) {
+    const cached = cache.get(metaUrl);
+    if (cached !== undefined)
+        return cached;
+    let dir = dirname(fileURLToPath(metaUrl));
+    for (let i = 0; i < MAX_DEPTH; i++) {
+        if (existsSync(resolve(dir, 'package.json'))) {
+            cache.set(metaUrl, dir);
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`packageRoot: 找不到 package.json（起点 ${metaUrl}）`);
+}

package/src/utils/resourcePaths.js

@@ -0,0 +1,49 @@
+/**
+ * ============================================================
+ *  src/utils/resourcePaths.ts —— 资源目录双源解析
+ * ------------------------------------------------------------
+ *  问题：skills/ 和 plugins/ 这类"资源目录"需要在两种场景下都能找到：
+ *    - 用户在 minimal-agent 源码仓库里跑（dev）：cwd === packageRoot
+ *    - 用户全局 npm install 后在自己项目里跑：cwd ≠ packageRoot
+ *      此时既要看 npm 包自带的资源，也要看用户在自己项目里新加的资源。
+ *
+ *  方案：返回 [cwd/<name>, packageRoot/<name>]，cwd 优先。
+ *    - 用 existsSync 过滤不存在的目录（保留静默降级）
+ *    - cwd 与 packageRoot 重合时去重（dev 场景）
+ *
+ *  消费者（commandRouter / skillList / 各插件 loader）按顺序扫描，先扫到的
+ *  同名条目胜出 —— 让用户能在自己项目里覆盖或扩展全局自带资源。
+ *
+ *  ResourceName 故意是开放 string：插件可以自由声明自己的资源名（如
+ *  workflow-runner 的 'workflows'），框架不预设资源名清单。
+ * ============================================================
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { findPackageRoot } from './packageRoot.js';
+/**
+ * 返回资源目录的搜索顺序数组（cwd 优先 + packageRoot fallback）。
+ *
+ * @param name     资源类别名（也作为子目录名）
+ * @param metaUrl  调用方 import.meta.url（用于定位 packageRoot）
+ * @returns        存在的搜索路径数组；都不存在则返回空数组
+ */
+export function getResourceSearchPaths(name, metaUrl) {
+    const paths = [];
+    const cwdPath = resolve(join(getWorkingDir(), name));
+    if (existsSync(cwdPath)) {
+        paths.push(cwdPath);
+    }
+    let pkgPath;
+    try {
+        pkgPath = resolve(join(findPackageRoot(metaUrl), name));
+    }
+    catch {
+        return paths;
+    }
+    if (pkgPath !== cwdPath && existsSync(pkgPath)) {
+        paths.push(pkgPath);
+    }
+    return paths;
+}

package/src/utils/zodToJson.js

@@ -0,0 +1,29 @@
+/**
+ * ============================================================
+ *  src/utils/zodToJson.ts —— Zod schema → JSON Schema 自动派生
+ * ------------------------------------------------------------
+ *  封装 zod-to-json-schema，统一清理输出格式。
+ *
+ *  设计原则：
+ *    - 单一数据源：每个工具只写一份 Zod schema
+ *    - 自动派生：parameters（给 LLM 看的 JSON Schema）由 Zod 自动生成
+ *    - 消除冗余：不再需要手写两份重复的参数定义
+ * ============================================================
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+/**
+ * 从 Zod schema 派生出 OpenAI tools[] 兼容的 JSON Schema 对象。
+ *
+ * 做了以下清理：
+ *   - 移除 `$schema` 元数据字段（LLM 不需要）
+ *   - `additionalProperties` 默认 false（防止模型传多余字段）
+ */
+export function toToolParameters(schema) {
+    const json = zodToJsonSchema(schema, {
+        target: 'openApi3',
+        $refStrategy: 'none',
+    });
+    // 移除 LLM 不需要的元数据
+    const { $schema, ...rest } = json;
+    return rest;
+}