minimal-agent 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/skills/config/SKILL.md

@@ -53,8 +53,11 @@ Read({ file_path: "~/.minimal-agent/config.json" })
 | moonshot | moonshot-v1-8k | 8000 |
 | moonshot | moonshot-v1-32k | 32000 |
 | moonshot | moonshot-v1-128k | 128000 |
+| volces | doubao-seed-2.0-pro / glm-5.1 / kimi-k2.6 / deepseek-v3.2 / minimax-latest | 204800 |
 | 其它 / custom | — | 128000 |
 
+⚠️ 火山方舟 ARK Coding Plan：一个 endpoint (`https://ark.cn-beijing.volces.com/api/coding/v3`) 后挂多个 model，**model 字段大小写严格匹配**（`glm-5.1` 而非 `GLM-5.1`）。常见 model id 见 `src/cli/configWizard.tsx::PRESETS` 的 `volces` 项；部分 model（如 `glm-5.1`）走 draft-2020-12 严校验，由 `src/utils/zodToJson.ts::modernizeExclusiveBounds` 透明兼容。
+
 ⚠️ 询问 `contextWindow` 时，**先按上表给出推荐值并明确告诉用户**（例：「按你选的 `MiniMax-M2.7`，推荐 `contextWindow = 204800`，直接回车采纳」）。**不要让用户裸填 token 数**；用户主要关心 `baseURL` / `apiKey` / `model`，contextWindow 应优先按 provider+model 推断。
 
 如果用户改了 model 但没改 contextWindow，**主动重新计算推荐值**并提示；用户旧 contextWindow 与新 model 不匹配时（如把 model 从 `moonshot-v1-8k` 改成 `moonshot-v1-128k`），明确建议同步更新。

package/src/cli/configWizard.js

@@ -37,6 +37,25 @@ const PRESETS = [
         models: ['MiniMax-M2.7', 'MiniMax-M1', 'abab6.5s-chat'],
         contextWindow: 204_800,
     },
+    {
+        // 火山方舟 ARK Coding Plan —— 一个 endpoint 后挂多个 model id，
+        // model 字段大小写严格匹配（'glm-5.1' 而非 'GLM-5.1'）。
+        // 部分 model（如 glm-5.1）走 draft-2020-12 严校验，靠 zodToJson 的
+        // modernizeExclusiveBounds 兼容。
+        name: 'volces',
+        label: '火山方舟 Coding Plan (ARK)',
+        baseURL: 'https://ark.cn-beijing.volces.com/api/coding/v3',
+        models: [
+            'doubao-seed-2.0-pro',
+            'doubao-seed-2.0-code',
+            'doubao-seed-code',
+            'glm-5.1',
+            'minimax-latest',
+            'deepseek-v3.2',
+            'kimi-k2.6',
+        ],
+        contextWindow: 204_800,
+    },
     {
         name: 'deepseek',
         label: 'DeepSeek',

package/src/prompts/system.js

@@ -32,6 +32,16 @@ export async function getSystemPrompt(cwd, tools) {
     return `你是 minimal-agent，一个最小化的 AI 编程助手。
 你运行在用户的本地终端里，可以读取、修改、创建文件，可以搜索文件名和文件内容，可以联网搜索最新信息。
 
+# 思维与立场（核心：像专家一样独立思考）
+- **你是工程协作者，不是奉承者**。不无条件夸赞、不为附和而附和、不同意时直说。不用"很好的问题"、"你说得对"、"完全同意"这类前缀——直接答内容。
+- **基于证据，不基于揣测用户想听什么**。没读过的代码先 Read，没验证过的行为先验证，不凭印象答。回答前先问自己：这个判断有具体证据吗，还是我在猜？
+- **不知道就说不知道**。明确边界："这个版本号我不确定"、"这个 API 我没看过文档"、"这部分行为我没验证过"。胡编一个看起来对的答案，代价远高于承认不知道。
+- **明示 confidence 分层**。结论按确定度分层表达——"已 verify / 高度确信"、"基于代码合理推测"、"未验证猜测"——让用户基于你的不确定程度决策，不要把推测说成事实。
+- **主动质疑用户的前提 / 方案 / 诊断**。发现方向不对时直说"这里我觉得不对，理由是 ..."，给出你的看法 + 证据 + 让用户拍板。不要为了维持氛围而顺着错的方向走。
+- **给根因不给表面答案**。bug 报告先定位 root cause 再给 fix，不要先给个让症状消失的 workaround 蒙混过去。修复要能解释"为什么这样改就对了"。
+- **任何方案都有代价**。主动说 trade-off（性能 vs 可读、激进 vs 保守、本期 vs 长期），让用户基于全貌决策，不要只夸方案的优点。
+- **被指出错误时直接承认 + 修正**。不解释、不防御、不找借口。承认 → 给出修正 → 避免下次。错误是 update prior 的信号，不是要消化的尴尬。
+
 # 工作环境
 - 当前工作目录: ${cwd}
 - 用户主目录: ${homedir()}
@@ -52,6 +62,7 @@ ${toolList}
 - 修改既有文件之前，必须用 Read 工具读取相关代码的最新内容。
   "我记得"、"我之前看过"、"应该差不多"都不算读过——必须在本轮任务中实际调用 Read。
   尤其当你要参考某个文件的写法来实现类似功能时，必须先重读该文件的关键部分（函数实现、判断逻辑、数据流），理解清楚后再动手。
+- Edit / MultiEdit 拦截 fallback：如果你忘了先 Read 就直接调 Edit/MultiEdit，错误响应里会**自动附带当前文件前 200 行 / 32KB 以内的 snippet**（带行号）。这种情况下**直接基于 snippet 重新构造 old_string 再发一次 Edit 即可，不要再额外调 Read**。只有当 snippet 显示"未注入内容"（文件过大或二进制）时才需要显式 Read。Write 不附带 snippet——整文件覆盖语义下必须先显式 Read，避免基于片段重写导致截断范围外内容丢失。
 - Edit 工具的 old_string 必须在文件中唯一；不唯一时请扩大上下文或显式 replace_all=true。
 - 同一文件需要修改多处（3 处及以上）时优先用 MultiEdit：所有 edit 按顺序在内存中应用，**全部成功才落盘**；任一失败磁盘不动，避免中间状态污染。单点修改继续用 Edit。
 - Write 覆盖既有文件前同样必须先 Read（与 Edit 对称，未先 Read 会被拒绝并提示"请先 Read"）；写新文件无此要求。

package/src/tools/edit/edit.js

@@ -17,7 +17,7 @@ import { dirname } from 'node:path';
 import { z } from 'zod';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
-import { resolveToolPath, findActualString, preserveQuoteStyle, detectLineEndingsForString, applyLineEnding, countOccurrences, splitReplaceAll, } from '../shared/fileUtils.js';
+import { resolveToolPath, findActualString, preserveQuoteStyle, detectLineEndingsForString, applyLineEnding, countOccurrences, splitReplaceAll, tryAutoSnapshot, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
 import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
 /** 编辑文件大小上限：1GB。防止模型试图 Edit 超大文件撑爆内存。 */
@@ -59,9 +59,33 @@ async function call(input) {
         return pathResult;
     const filePath = pathResult.resolvedPath;
     // 5a-bis. Pre-read guard：文件已存在则必须先 Read（创建新文件场景下 assertFresh 返回 ok:true）
+    // 拦截路径自动注入 snippet：让模型在同一轮 tool result 里看到当前内容，无需多绕一次 Read。
+    // 安全语义保留：模型必须显式重发 Edit 才会落盘；snippet 只是给模型看的，不静默放行。
     const freshness = assertFresh(filePath);
     if (!freshness.ok) {
-        return { ok: false, error: freshness.error };
+        const snap = await tryAutoSnapshot(filePath);
+        if (snap.ok) {
+            // 关键：truncated=true 时 wasTruncated 会守住 Write 路径，防止基于残缺 snippet 重写整文件
+            recordRead(filePath, { truncated: snap.truncated });
+            const tail = snap.truncated
+                ? `\n\n⚠️ 仅注入了前 200 行（文件共 ${snap.totalLines} 行 / 上限 32KB）。若要改的位置在范围外，请显式 Read offset=X limit=Y 后再 Edit。`
+                : '';
+            return {
+                ok: false,
+                error: freshness.error +
+                    `\n\n以下是当前文件${snap.truncated ? '前 200 行' : '全部'}内容（带行号），请基于此重新构造 old_string 后立即重试 Edit，不要再单独调 Read：\n\n${snap.snippet}` +
+                    tail,
+            };
+        }
+        const why = snap.reason === 'too-large'
+            ? `文件 ${((snap.sizeBytes ?? 0) / 1024).toFixed(1)} KB 超过 32KB 自动注入上限`
+            : snap.reason === 'binary'
+                ? '文件命中二进制扩展名黑名单'
+                : '文件读取失败';
+        return {
+            ok: false,
+            error: `${freshness.error}\n\n（${why}，未注入内容快照，请用 Read 工具显式读取后再 Edit）`,
+        };
     }
     if (old_string === new_string) {
         return { ok: false, error: 'old_string 与 new_string 完全相同，没有可改的内容。' };

package/src/tools/edit/multi-edit.js

@@ -18,7 +18,7 @@ import { existsSync } from 'node:fs';
 import { z } from 'zod';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
-import { resolveToolPath, detectFileLineEndings, applyLineEnding, findActualString, preserveQuoteStyle, countOccurrences, splitReplaceAll, } from '../shared/fileUtils.js';
+import { resolveToolPath, detectFileLineEndings, applyLineEnding, findActualString, preserveQuoteStyle, countOccurrences, splitReplaceAll, tryAutoSnapshot, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
 import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
 // ---------------- 1. Zod 输入 schema ----------------
@@ -58,10 +58,31 @@ async function call(input) {
     if (!pathResult.ok)
         return pathResult;
     const filePath = pathResult.resolvedPath;
-    // 4b. Pre-read guard
+    // 4b. Pre-read guard —— 入口处一次性检查 + 注入 snippet（循环内多个 edit 不重复注入）
     const freshness = assertFresh(filePath);
     if (!freshness.ok) {
-        return { ok: false, error: freshness.error };
+        const snap = await tryAutoSnapshot(filePath);
+        if (snap.ok) {
+            recordRead(filePath, { truncated: snap.truncated });
+            const tail = snap.truncated
+                ? `\n\n⚠️ 仅注入了前 200 行（文件共 ${snap.totalLines} 行 / 上限 32KB）。若要改的位置在范围外，请显式 Read offset=X limit=Y 后再 MultiEdit。`
+                : '';
+            return {
+                ok: false,
+                error: freshness.error +
+                    `\n\n以下是当前文件${snap.truncated ? '前 200 行' : '全部'}内容（带行号），请基于此重新构造各 edit 的 old_string 后立即重试 MultiEdit，不要再单独调 Read：\n\n${snap.snippet}` +
+                    tail,
+            };
+        }
+        const why = snap.reason === 'too-large'
+            ? `文件 ${((snap.sizeBytes ?? 0) / 1024).toFixed(1)} KB 超过 32KB 自动注入上限`
+            : snap.reason === 'binary'
+                ? '文件命中二进制扩展名黑名单'
+                : '文件读取失败';
+        return {
+            ok: false,
+            error: `${freshness.error}\n\n（${why}，未注入内容快照，请用 Read 工具显式读取后再 MultiEdit）`,
+        };
     }
     // 4c. 文件必须存在（MultiEdit 不做"创建新文件"语义）
     if (!existsSync(filePath)) {

package/src/tools/shared/fileState.js

@@ -39,6 +39,7 @@ export function assertFresh(absPath) {
         if (existsSync(absPath)) {
             return {
                 ok: false,
+                reason: 'never-read',
                 error: `文件 ${absPath} 已存在但未在本会话 Read 过。请先用 Read 工具读取，确认内容后再修改。`,
             };
         }
@@ -50,6 +51,7 @@ export function assertFresh(absPath) {
         if (st.mtimeMs > entry.timestamp) {
             return {
                 ok: false,
+                reason: 'mtime-drift',
                 error: `${absPath} 在 Read 后被外部修改（mtime 漂移）。请重新用 Read 工具读取最新内容。`,
             };
         }

package/src/tools/shared/fileUtils.js

@@ -9,6 +9,7 @@
  *    4. 引号风格保留（弯引号 ↔ 直引号归一化）
  * ============================================================
  */
+import { statSync } from 'node:fs';
 import { open, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { extname, resolve } from 'node:path';
@@ -129,6 +130,66 @@ export function hasBinaryExtension(filePath) {
     const ext = extname(filePath).toLowerCase();
     return BINARY_EXTENSIONS.has(ext);
 }
+// -------------------- 3.7 自动 snapshot（Edit/MultiEdit 拦截路径用） --------------------
+/**
+ * 自动读取文件前 N 行作为 snippet，给 Edit/MultiEdit 在 assertFresh 拦截时注入到错误响应里。
+ *
+ * 双限制：
+ *   - SNAPSHOT_MAX_LINES = 200 行（防止小行长文件吃 context）
+ *   - SNAPSHOT_MAX_BYTES = 32KB（防止超长单行 minified 文件撑爆 context）
+ *   两个阈值任一命中都拒绝读全量。
+ *
+ * 失败 reason：
+ *   - 'binary'      → 命中二进制扩展名黑名单
+ *   - 'too-large'   → 文件 > 32KB（不读全文，让模型走显式 Read）
+ *   - 'unreadable'  → stat 或 read 失败
+ *
+ * 调用方负责：
+ *   1. 在拿到 ok=true 后调 recordRead(filePath, { truncated: snap.truncated })
+ *   2. 把 snippet 拼到 error 字符串里
+ *   3. ok=false 时根据 reason 给模型可读的 fallback 消息
+ */
+const SNAPSHOT_MAX_LINES = 200;
+const SNAPSHOT_MAX_BYTES = 32 * 1024;
+export async function tryAutoSnapshot(filePath) {
+    // 1. 二进制扩展名拒绝
+    if (hasBinaryExtension(filePath)) {
+        return { ok: false, reason: 'binary' };
+    }
+    // 2. stat 拿大小
+    let sizeBytes;
+    try {
+        const st = statSync(filePath);
+        if (!st.isFile())
+            return { ok: false, reason: 'unreadable' };
+        sizeBytes = st.size;
+    }
+    catch {
+        return { ok: false, reason: 'unreadable' };
+    }
+    // 3. 字节阈值
+    if (sizeBytes > SNAPSHOT_MAX_BYTES) {
+        return { ok: false, reason: 'too-large', sizeBytes };
+    }
+    // 4. 读全文（已知 <= 32KB）
+    let content;
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return { ok: false, reason: 'unreadable' };
+    }
+    // 5. 行数阈值：超过 200 行截断
+    const allLines = content.split('\n');
+    const totalLines = allLines.length;
+    const truncated = totalLines > SNAPSHOT_MAX_LINES;
+    const lines = truncated ? allLines.slice(0, SNAPSHOT_MAX_LINES) : allLines;
+    // 拼带行号的 snippet（与 Read 工具输出风格一致）
+    const numbered = lines
+        .map((line, i) => `${String(i + 1).padStart(6, ' ')}\t${line}`)
+        .join('\n');
+    return { ok: true, snippet: numbered, truncated, totalLines };
+}
 /**
  * 读文件前 3 字节，返回 BOM 类型。
  * - EF BB BF → utf8-bom

package/src/utils/zodToJson.js

@@ -11,12 +11,55 @@
  * ============================================================
  */
 import { zodToJsonSchema } from 'zod-to-json-schema';
+/**
+ * 把 zodToJsonSchema 输出的 draft-04 boolean 形式 exclusiveMin/Max 升级为
+ * draft-2020-12 number 形式，让生成的 schema 在严校验 LLM provider 也能通过。
+ *
+ * 背景：`target: 'openApi3'` 走 OpenAPI 3.0 / JSON Schema draft-04 规范，
+ *   `.positive()` 之类的 Zod 约束生成 `{minimum: 0, exclusiveMinimum: true}`。
+ * 严校验 provider（如火山 ARK Coding 后挂的 GLM-5.1）按 draft-2020-12 要求
+ *   `exclusiveMinimum` 必须是 number，遇 boolean 直接 400 InvalidParameter。
+ *
+ * 转换规则：
+ *   {minimum: N, exclusiveMinimum: true}  →  {exclusiveMinimum: N}
+ *   {maximum: N, exclusiveMaximum: true}  →  {exclusiveMaximum: N}
+ *
+ * Fallback：boolean 形式但同级没有 minimum/maximum 时（理论 edge case），
+ *   静默删除 boolean 字段——避免污染 schema，运行时 Zod 兜底校验。
+ */
+function modernizeExclusiveBounds(node) {
+    if (Array.isArray(node))
+        return node.map(modernizeExclusiveBounds);
+    if (node === null || typeof node !== 'object')
+        return node;
+    const obj = node;
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (k === 'exclusiveMinimum' && typeof v === 'boolean') {
+            if (v && typeof obj.minimum === 'number')
+                out.exclusiveMinimum = obj.minimum;
+            continue;
+        }
+        if (k === 'minimum' && obj.exclusiveMinimum === true)
+            continue;
+        if (k === 'exclusiveMaximum' && typeof v === 'boolean') {
+            if (v && typeof obj.maximum === 'number')
+                out.exclusiveMaximum = obj.maximum;
+            continue;
+        }
+        if (k === 'maximum' && obj.exclusiveMaximum === true)
+            continue;
+        out[k] = modernizeExclusiveBounds(v);
+    }
+    return out;
+}
 /**
  * 从 Zod schema 派生出 OpenAI tools[] 兼容的 JSON Schema 对象。
  *
  * 做了以下清理：
  *   - 移除 `$schema` 元数据字段（LLM 不需要）
  *   - `additionalProperties` 默认 false（防止模型传多余字段）
+ *   - `modernizeExclusiveBounds` 把 boolean exclusiveMin/Max 升级 draft-2020-12 number 形式
  */
 export function toToolParameters(schema) {
     const json = zodToJsonSchema(schema, {
@@ -25,5 +68,5 @@ export function toToolParameters(schema) {
     });
     // 移除 LLM 不需要的元数据
     const { $schema, ...rest } = json;
-    return rest;
+    return modernizeExclusiveBounds(rest);
 }