mocode-ai 1.6.10 → 1.7.1

package/README.md

@@ -49,6 +49,8 @@ MoCode is organized as a layered runtime: the terminal experience drives an auto
 
 Implementation entry points: [Agent core](src/agent/core.ts), [tool dispatch](src/agent/stages/tool-dispatcher.ts), and [tool execution](src/tools/tool-runtime.ts).
 
+<p align="center"><img src="./assets/architecture/system-overview.svg" alt="MoCode system overview: experience layer, autonomous runtime, capability plane, persistent intelligence" width="100%"></p>
+
 ### Autonomous execution loop
 
 Each model response is one step in a closed loop. Tool calls are classified by declared capabilities, safe reads can run in parallel, and writes acquire canonical resource locks. Tool evidence returns to history unchanged apart from a hard per-result safety cap. When the agent has no more tools to call, its response completes immediately; the framework does not run hidden validation or force another model turn.

package/README.zh-CN.md

@@ -40,6 +40,8 @@ MoCode 是一个分层的自治运行时：终端交互层驱动 Agent 内核，
 
 实现入口：[Agent 内核](src/agent/core.ts)、[工具派发](src/agent/stages/tool-dispatcher.ts)、[工具执行](src/tools/tool-runtime.ts)。
 
+<p align="center"><img src="./assets/architecture/system-overview-zh-CN.svg" alt="MoCode 系统全景：交互体验层、自治执行内核、受控能力平面、持久化认知层" width="100%"></p>
+
 ### 自治执行循环
 
 每次模型响应都是闭环中的一步。工具调用按能力声明分类，安全读取可以并行，写操作获取规范化资源锁。工具证据除单条 hard cap 外原样进入 history，用户与模型看到同一事实。agent 没有更多工具调用时立即完成；框架不会暗中运行验证，也不会强迫追加一轮模型调用。

package/dist/agent/run-coordinator.js

@@ -398,6 +398,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                                 callId: calls[index].id,
                                                 allowedToolNames: currentAllowedToolNames(),
                                                 delegation: delegationForOrchestrator(),
+                                                readDedup,
                                             });
                                         }
                                     }
@@ -559,6 +560,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                             callId: tc.id,
                                             allowedToolNames: currentAllowedToolNames(),
                                             delegation: delegationForOrchestrator(),
+                                            readDedup,
                                         }));
                                         // 完成即发:usage/onToolOutcome/trace 在各 outcome 落地瞬间发出(1s 的
                                         // grep 不再被 60s 的 web_fetch 卡住可见性);history 回灌严格按原序。
@@ -655,6 +657,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                                         callId: entry.tc.id,
                                                         allowedToolNames: currentAllowedToolNames(),
                                                         delegation: delegationForOrchestrator(),
+                                                        readDedup,
                                                         ...(hint ? { argumentErrorHint: hint } : {}),
                                                         onLockAcquired: (lockedArgs) => {
                                                             entry.diff = readDiffContext(entry.tc, lockedArgs, ctx.jailResolve);
@@ -742,6 +745,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                                 callId: entry.tc.id,
                                                 allowedToolNames: currentAllowedToolNames(),
                                                 delegation: delegationForOrchestrator(),
+                                                readDedup,
                                                 ...(hint ? { argumentErrorHint: hint } : {}),
                                                 onLockAcquired: (lockedArgs) => {
                                                     entry.diff = readDiffContext(entry.tc, lockedArgs, ctx.jailResolve);
@@ -836,6 +840,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                             callId: tc.id,
                                             allowedToolNames: currentAllowedToolNames(),
                                             delegation: delegationForOrchestrator(),
+                                            readDedup,
                                             ...(serialHint ? { argumentErrorHint: serialHint } : {}),
                                             onLockAcquired: (lockedArgs) => {
                                                 if (mutationParsed)

package/dist/llm/index.js

@@ -883,8 +883,35 @@ export function contentTokens(content) {
     }
     return estimateTokens(contentToText(content));
 }
-/** 估算单条消息的 token 数:结构开销 + content + tool_calls 参数。 */
+/** 单条消息的 token 估算缓存:命中键 = 该消息的「内容签名」(见 messageSignature)。 */
+const messageTokensCache = new WeakMap();
+/**
+ * 消息内容签名:content 引用 + role + 有无 tool_calls。
+ *
+ * **为什么签名里用 content 的「长度」而不是内容本身**:签名要在每次估算时算,必须是 O(1)。
+ * 用 `typeof content === 'string' ? content.length : -1` 兼顾 O(1) 与可判定性 ——
+ * string 不可变,原地改写(`msg.content = ...`)必然换成另一个字符串对象、长度通常也变;
+ * 长度相同而内容变了的情况(如 microcompact 截到同样长度)极少,且那种路径
+ * (compact / age-aware)本身会先 markContextChanged 走全量重估(见 scheduler)。
+ *
+ * **为什么不直接用对象身份当键**(即 WeakMap<ChatMessage, number>):有 4 处代码会
+ * **原地改写** message.content —— age-aware.ts:66、artifacts.ts:269(标 stale)、
+ * compact.ts:590/597(微压缩)。对象身份不变但内容已变,身份缓存会返回旧值 →
+ * token 低估 → 80% 压力线不触发 → prompt 实际已超窗口(llm/index.ts:1042-1044 注释
+ * 描述过这个失败模式:「模型突然抽风」)。签名方案让这4 处自动安全,无需挂失效钩子。
+ */
+function messageSignature(m) {
+    const c = m.content;
+    const tcs = m.tool_calls;
+    return `${m.role ?? ''}|${typeof c === 'string' ? c.length : -1}|${tcs ? 1 : 0}`;
+}
+/** 估算单条消息的 token 数:结构开销 + content + tool_calls 参数。内容签名命中则复用上次结果。 */
 export function messageTokens(m) {
+    const key = m;
+    const sig = messageSignature(m);
+    const hit = messageTokensCache.get(key);
+    if (hit !== undefined && hit.sig === sig)
+        return hit.tokens;
     const role = m.role;
     let structural = 4; // {role}\n{content}\n 框架基线
     if (role === 'system')
@@ -897,7 +924,9 @@ export function messageTokens(m) {
         for (const tc of tcs)
             body += estimateTokens(tc?.function?.arguments ?? '');
     }
-    return structural + body;
+    const tokens = structural + body;
+    messageTokensCache.set(key, { sig, tokens });
+    return tokens;
 }
 /** 估算整段 messages 的 token 数(不含工具 schema,含 priming 常数)。 */
 export function estimateMessagesTokens(messages) {

package/dist/rollback/store.js

@@ -54,6 +54,54 @@ const SCAN_CONCURRENCY = 16;
 const YIELD_EVERY = 64;
 const YIELD_BYTES = 1024 * 1024;
 const FRESH_WINDOW_MS = 2000;
+/**
+ * contentCache 的常驻字节上限(base64 后的长度和);0 = 不限。
+ *
+ * contentCache 是「上次扫描读到的内容」的跨扫描复用:命中则省一次 readFile,
+ * 这就是第 2 次及以后的 workspace 扫描只要 ~35ms 而首次要 500ms+ 的原因
+ * (实测 2026-10-05,2000 entries / 42.7MB base64)。它原先只增不减(唯一清理点是
+ * resetState),即一次扫描就把整个工作区文本永久常留内存。
+ *
+ * **默认保持不限(0)**:实测把上限压到 16MB 会把命中率打崩 —— 缓存从 664 条掉到 54 条,
+ * 扫描耗时从 ~67ms 反弹到 ~1000ms(涨 15倍)。原因是遍历顺序下累积的大文件会挤掉后续
+ * 所有条目,淘汰机制天然对「后访问的小文件」不友好。42.7MB 换每条命令 67ms 是划算的,
+ * 不值得为省内存牺牲 15 倍扫描速度。
+ *
+ * 保留这个旋门是为了「大工作区内存吃紧」的场景(比如 node_modules 被误纳入扫描),
+ * 可通过 MOCODE_ROLLBACK_CACHE_MB 收紧;不设则沿用无上限的既有行为。
+ */
+const CONTENT_CACHE_MAX_BYTES = (() => {
+    const mb = Number(process.env.MOCODE_ROLLBACK_CACHE_MB);
+    return Number.isFinite(mb) && mb > 0 ? Math.floor(mb) * 1024 * 1024 : 0;
+})();
+/**
+ * 把扫描产出的缓存裁到 CONTENT_CACHE_MAX_BYTES 以内,按插入序淘汰最旧条目。
+ *
+ * 仅在 CONTENT_CACHE_MAX_BYTES > 0(即用户显式设了 MOCODE_ROLLBACK_CACHE_MB)时生效;
+ * 默认无上限,保持既有行为。淘汰只影响性能,不影响正确性:被淘汰的条目下次扫描时
+ * stamp 不匹配 → 重新 readFile 而已(snapshot 记录的是**本次扫描当场读到**的内容,
+ * 见 scanWorkspace 的 `cached.stamp === stamp` 校验)。
+ */
+function trimContentCache(cache) {
+    if (CONTENT_CACHE_MAX_BYTES <= 0)
+        return cache;
+    let total = 0;
+    for (const entry of cache.values())
+        total += entry.data.length;
+    if (total <= CONTENT_CACHE_MAX_BYTES)
+        return cache;
+    // Map 保插入序 → 最旧的在最前。逐个删到回到预算内,单趟 O(n) 足够。
+    for (const key of cache.keys()) {
+        if (total <= CONTENT_CACHE_MAX_BYTES)
+            break;
+        const entry = cache.get(key);
+        if (!entry)
+            continue;
+        total -= entry.data.length;
+        cache.delete(key);
+    }
+    return cache;
+}
 /**
  * 一个完整、实例隔离的回滚事务存储。每个 runtime 可持有独立实例，使轮次、序号、
  * 快照、mutation generation 和扫描缓存互不干扰。
@@ -336,7 +384,7 @@ export class RollbackStore {
             }
         };
         await Promise.all(Array.from({ length: Math.min(SCAN_CONCURRENCY, Math.max(1, paths.length)) }, worker));
-        this.contentCache = nextCache;
+        this.contentCache = trimContentCache(nextCache);
         return entries;
     }
     async beginWorkspaceMutation() {

package/dist/session/store.js

@@ -66,6 +66,20 @@ export class SessionStore {
     currentSessionIdProvider;
     currentSessionIdSetter;
     currentSessionId;
+    /**
+     * 已确保存在的会话目录缓存(2026-10-05)。
+     *
+     * `mkdirSync(recursive)` 单次 0.20ms —— 比 existsSync+statSync(合计 0.009ms)贵 20 倍,
+     * 因为 recursive 模式要逐级向下 stat 每层路径。而 appendTrace 每 step 调 14 次
+     * (step_start/end + model_start/end + 每工具 2 个),每轮 20 step ≈ 280 次全花在
+     * 「确认目录已存在」上,一轮白烧 56ms。
+     *
+     * 缓存的是「已 mkdir 成功」这件事,不是路径存在性。**代价**:外部删掉目录后缓存会失真。
+     * 兜底是三个写盘方法统一的「失败 → invalidateEnsuredDir → 重试一次」模式
+     * (见 appendTrace / appendUsage / save),既保住性能又不丢数据。
+     * 护栏见 tests/session-dir-cache.test.ts 的「外部删除后自愈」三例。
+     */
+    ensuredDirs = new Set();
     constructor(options = {}) {
         if (typeof options.workspaceRoot === 'function') {
             const provider = options.workspaceRoot;
@@ -92,9 +106,26 @@ export class SessionStore {
     }
     sessionDir() {
         const root = this.sessionsRoot;
-        mkdirSync(root, { recursive: true });
+        this.ensureDir(root);
         return root;
     }
+    /**
+     * 幂等建目录:同一路径只在首次真正 mkdir(见 ensuredDirs 的成本说明)。
+     *
+     * 缓存意味着「外部删掉目录后不自愈」,故所有写盘方法都用
+     * {@link invalidateEnsuredDir} + 重试一次兜住(retention 归档后 rmSync、
+     * 用户手工清理等)。单靠这里的 Set 不会自愈,必须配对那个重试。
+     */
+    ensureDir(dir) {
+        if (this.ensuredDirs.has(dir))
+            return;
+        mkdirSync(dir, { recursive: true });
+        this.ensuredDirs.add(dir);
+    }
+    /** 让 ensureDir 下次真正 mkdir(用于 append 失败后的自愈重试)。 */
+    invalidateEnsuredDir(dir) {
+        this.ensuredDirs.delete(dir);
+    }
     createId() {
         return createTimestampId();
     }
@@ -119,22 +150,38 @@ export class SessionStore {
      * 然后清空当前文件。纯诊断数据,任何失败静默降级为普通追加。
      */
     appendTrace(id, value) {
-        try {
-            const dir = path.join(this.sessionsRoot, id);
-            mkdirSync(dir, { recursive: true });
-            const line = `${JSON.stringify(value)}\n`;
-            const tracePath = path.join(dir, 'trace.jsonl');
-            // env 覆盖仅供测试:MOCODE_MAX_TRACE_BYTES=200 可立刻触发轮转。
-            const envMax = Number(process.env.MOCODE_MAX_TRACE_BYTES);
-            const maxTraceBytes = Number.isFinite(envMax) && envMax >= 0 ? envMax : MAX_TRACE_BYTES;
-            const size = existsSync(tracePath) ? statSync(tracePath).size : 0;
-            if (size >= maxTraceBytes) {
-                this.rotateTrace(dir, tracePath);
+        const dir = path.join(this.sessionsRoot, id);
+        const line = `${JSON.stringify(value)}\n`;
+        const tracePath = path.join(dir, 'trace.jsonl');
+        // env 覆盖仅供测试:MOCODE_MAX_TRACE_BYTES=200 可立刻触发轮转。
+        const envMax = Number(process.env.MOCODE_MAX_TRACE_BYTES);
+        const maxTraceBytes = Number.isFinite(envMax) && envMax >= 0 ? envMax : MAX_TRACE_BYTES;
+        // 目录缓存可能因外部删除而失真(如 retention 归档后 rmSync):首次失败清缓存重试一次。
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                this.ensureDir(dir); // 缓存:每 step 14 次调用,省 14×0.20ms
+                // statSync 一次即可拿到「不存在 / 大小」两种答案,省掉 existsSync 那一跳
+                // (两者合计仅 0.009ms,但顺手消掉一次 TOCTOU 窗口)。
+                let size = 0;
+                try {
+                    size = statSync(tracePath).size;
+                }
+                catch {
+                    size = 0;
+                }
+                if (size >= maxTraceBytes) {
+                    this.rotateTrace(dir, tracePath);
+                }
+                writeFileSync(tracePath, line, { encoding: 'utf8', flag: 'a' });
+                return;
+            }
+            catch {
+                this.invalidateEnsuredDir(dir);
+                if (attempt === 1) {
+                    // Observability is best-effort and cannot block coding work.
+                    return;
+                }
             }
-            writeFileSync(tracePath, line, { encoding: 'utf8', flag: 'a' });
-        }
-        catch {
-            // Observability is best-effort and cannot block coding work.
         }
     }
     rotateTrace(dir, tracePath) {
@@ -174,13 +221,23 @@ export class SessionStore {
      * 与 appendTrace 同策略:纯诊断,失败静默,不做轮转(长会话的量级远小于 trace)。
      */
     appendUsage(id, value) {
-        try {
-            const dir = path.join(this.sessionsRoot, id);
-            mkdirSync(dir, { recursive: true });
-            writeFileSync(path.join(dir, 'usage.jsonl'), `${JSON.stringify(value)}\n`, { encoding: 'utf8', flag: 'a' });
-        }
-        catch {
-            // Metrics must never block coding work.
+        const dir = path.join(this.sessionsRoot, id);
+        const line = `${JSON.stringify(value)}\n`;
+        const file = path.join(dir, 'usage.jsonl');
+        // 同 appendTrace:目录缓存失真时清缓存重试一次。
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                this.ensureDir(dir); // 同appendTrace:每 step 1 次,省 0.20ms
+                writeFileSync(file, line, { encoding: 'utf8', flag: 'a' });
+                return;
+            }
+            catch {
+                this.invalidateEnsuredDir(dir);
+                if (attempt === 1) {
+                    // Metrics must never block coding work.
+                    return;
+                }
+            }
         }
     }
     /** 读取 <id>/usage.jsonl 全部记录;文件不存在或损坏行跳过。 */
@@ -202,6 +259,13 @@ export class SessionStore {
         }
         return out;
     }
+    /**
+     * 全量落盘会话(history + queryHistory + lastToolGroups),原子写(先 tmp 再 rename)。
+     *
+     * 与 appendTrace/appendUsage 的差别:**失败会抛给调用方**——这是用户数据,
+     * 静默丢失不可接受(那两个是诊断数据,静默降级是对的)。目录缓存失真时会
+     * 清缓存重试一次,仍失败则照旧抛出。
+     */
     save(history, id, queryHistory = [], lastToolGroups = []) {
         const meta = {
             id,
@@ -216,21 +280,33 @@ export class SessionStore {
         if (history.length <= 1 && queryHistory.length === 0 && !existsSync(currentPath) && !existsSync(legacyPath)) {
             return meta;
         }
-        mkdirSync(path.join(this.sessionsRoot, id), { recursive: true });
+        const dir = path.join(this.sessionsRoot, id);
+        const tmpPath = path.join(dir, 'session.json.tmp');
         const record = {
             ...meta,
             history,
             queryHistory: [...queryHistory],
             lastToolGroups: [...lastToolGroups],
         };
-        // 原子落盘:先写同目录 tmp 再 rename——全量重写(长会话可达数 MB)中途崩溃/断电
-        // 不会留下半个 JSON 把整个会话写坏(对齐 memory/store.ts writeAtomic)。
-        const tmpPath = path.join(this.sessionsRoot, id, 'session.json.tmp');
-        writeFileSync(tmpPath, JSON.stringify(record), 'utf8');
-        renameSync(tmpPath, currentPath);
-        if (existsSync(legacyPath))
-            unlinkSync(legacyPath);
-        return meta;
+        // 目录缓存失真时清缓存重试一次(与 appendTrace 同理);仍失败则照旧抛给调用方
+        // —— save 是用户数据落盘,失败必须可见(appendTrace/appendUsage 是诊断数据,静默)。
+        for (let attempt = 0;; attempt++) {
+            try {
+                this.ensureDir(dir);
+                // 原子落盘:先写同目录 tmp 再 rename——全量重写(长会话可达数 MB)中途崩溃/断电
+                // 不会留下半个 JSON 把整个会话写坏(对齐 memory/store.ts writeAtomic)。
+                writeFileSync(tmpPath, JSON.stringify(record), 'utf8');
+                renameSync(tmpPath, currentPath);
+                if (existsSync(legacyPath))
+                    unlinkSync(legacyPath);
+                return meta;
+            }
+            catch (error) {
+                this.invalidateEnsuredDir(dir);
+                if (attempt === 1)
+                    throw error;
+            }
+        }
     }
     load(id) {
         const currentPath = this.sessionPath(id);

package/dist/tools/builtins/index.js

@@ -54,8 +54,12 @@ export const CAPABILITIES = {
     browser: { effect: 'process', concurrency: 'serial', resources: workspaceResource },
     // glob/grep 不取任何资源锁:读枚举容忍命令执行期间的瞬时不一致(一次目录扫描的结果
     // 本来就无事务语义),换取「一条 run_command/dev_server 持 workspace 写锁期间,只读
-    // 枚举与并行子 agent 的读不被全面压制」。文件级一致性仍由 read_file 的 file:<path>
-    // 锁保证(与 file-locked 写互斥)。网络只读同理不锁。
+    // 枚举与并行子 agent 的读不被全面压制」。网络只读同理不锁。
+    //
+    // read_file 不在此列:它取 file:<path> 读锁(读单个**已知**文件,与目录枚举的
+    // 瞬时不一致不同层级)。2026-10-05 起 resource-lock 的 requestConflicts 放行了
+    // 「workspace 写锁 vs 资源读锁」这一格,所以 run_command 期间 read_file 不再排队;
+    // 但 read_file 仍与 write_file/edit_file 的 file 写锁互斥(见 resource-lock.ts 的冲突矩阵)。
     glob: { effect: 'read', concurrency: 'parallel', resources: () => [], supportsAbort: true },
     grep: { effect: 'read', concurrency: 'parallel', resources: () => [], supportsAbort: true },
     // 网络只读查询:无副作用,可安全重复执行 → idempotent 让 runtime 对瞬时失败(429/5xx/超时/

package/dist/tools/resource-lock.js

@@ -5,11 +5,48 @@ function abortError() {
     error.name = 'AbortError';
     return error;
 }
+/**
+ * 两个锁请求是否冲突。
+ *
+ * 冲突矩阵(workspace 锁 vs 资源锁):
+ *
+ * |左\右| workspace-write | resource-read | resource-write |
+ * |------|-----------------|--------------|----------------|
+ * | ws-write |冲突(命令互斥) | **不冲突** | 冲突(防命令与 Agent 写同文件) |
+ * | ws-read  | 不冲突 | 不冲突 | 冲突 |
+ * | res-read | 不冲突 | 同 key 不冲突 | 冲突 |
+ *
+ * **唯一放行的是「workspace 写锁 vs 资源读锁」**(表中加粗那格)。这条正是
+ * 「一条 run_command 期间所有 read_file 排队」的根因:run_command 声明
+ * `resources: () => ['workspace']` + `effect: 'process'` → resolveResourceLockRequests
+ * 恒返回 workspace 写锁(resource-lock.ts 的 workspaceWrite()),而 read_file 持
+ * `file:<path>` 读锁,旧判据「任一 write 即冲突」把两者判成互斥 —— 一条 60s 的
+ * `npm test` 会让同 step 的所有 read_file 全部阻塞排队,并行探查退化为串行。
+ *
+ * 放行的依据与 glob/grep 的 `resources: () => []` 豁免同源(见 builtins/index.ts 的
+ * CAPABILITIES 注释「读枚举容忍命令执行期间的瞬时不一致」):run_command **不通过
+ * ChangeSet 写文件**,它的工作区写入对 read_file 不构成事务性冲突 —— read_file 读的是
+ * 单个已知文件,与命令的写入在绝大多数情况下无关。若命令恰好在改这个文件,读到不一致
+ * 内容的后果由既有机制兜住:read_file 的输出带 content hash 记入 artifact,后续
+ * refreshArtifactFreshness / invalidateArtifacts 会把它标 stale。
+ *
+ * **保持冲突的边界(不可放宽)**:
+ * - workspace-write vs resource-write:run_command 与 write_file/edit_file 改同一文件
+ *   必须互斥,否则 ChangeSet 的 read-modify-write 会读到命令的半成品。
+ * - workspace-write vs workspace-write:命令之间互斥(文件句柄 / 端口 / 环境变量共享)。
+ */
 function requestConflicts(a, b) {
     if (a.scope === 'workspace' || b.scope === 'workspace') {
-        if (a.mode === 'write' || b.mode === 'write')
-            return true;
-        return false;
+        // 同为 workspace 锁(实践中只有 write):沿用「任一 write 即冲突」。
+        if (a.scope === 'workspace' && b.scope === 'workspace') {
+            return a.mode === 'write' || b.mode === 'write';
+        }
+        const workspaceReq = a.scope === 'workspace' ? a : b;
+        const resourceReq = a.scope === 'workspace' ? b : a;
+        // 放行格:workspace 写锁(命令)与资源读锁(读单个已知文件)不冲突。
+        if (workspaceReq.mode === 'write' && resourceReq.mode === 'read')
+            return false;
+        return workspaceReq.mode === 'write' || resourceReq.mode === 'write';
     }
     return a.key === b.key && (a.mode === 'write' || b.mode === 'write');
 }

package/dist/tools/validation.js

@@ -3,7 +3,10 @@ import Ajv2020 from 'ajv/dist/2020.js';
 const options = {
     allErrors: true,
     strict: false,
-    coerceTypes: false,
+    // 中转网关/弱模型常把 integer/number/boolean 序列化成字符串(如 "100"),
+    // 开启标量强转在校验前自动还原;类型完全不符("abc"→number)仍会被拦,
+    // minimum/maximum 等约束在转换后照常生效。
+    coerceTypes: true,
     useDefaults: false,
     removeAdditional: false,
     validateFormats: false,
@@ -69,7 +72,7 @@ function formatErrors(errors, schema) {
     }
     return body + hint;
 }
-/** Validate after tool-local normalization; AJV itself never coerces or mutates arguments. */
+/** Validate after tool-local normalization; AJV coerces scalar strings to declared types. */
 export function validateToolArguments(tool, args) {
     if (!args || typeof args !== 'object' || Array.isArray(args)) {
         return {

package/dist/ui/layout-internal/content-write.js

@@ -9,6 +9,44 @@ import { renderMarkdown } from '../markdown.js';
 import { state } from './state.js';
 import { esc, cup, getGeo, setRegion, runningCaretPos } from './screen.js';
 import { viewportAbsStart, repaintViewport } from './scroll.js';
+// ── 流式 markdown 渲染节流(2026-10-05)──
+// 背景:原实现每收到一个 onText chunk 就把**累积的整个 mdBuf** 重渲一遍(渲成自洽 ANSI 行
+// 替换缓冲段 + repaintViewport 全画)。这是 O(n²):实测一次 5879 字符的回复被切成~1960 个
+// chunk,累计扫描 5.5MB、纯 CPU ~900ms,且全程同步阻塞事件循环(TUI 的 spinner/输入都跟着卡)。
+// renderMarkdown 内有 LRU memo(key = 完整 text),但流式下每次 text 都是新串 → 必然 miss。
+// 分块归因实测:单次 render 仅 0.05ms 量级,带 lang 的代码块最贵(0.097ms),无 lang 近乎免费。
+// → 结论是「贵在次数,不在单次」,故按时间/内容节流降次数,而不是优化单次渲染。
+/**
+ * 两次渲染的最小间隔(ms)。
+ *
+ * 取 32ms(~30fps)而非 16ms:终端正文流式本来肉眼无法分辨更高帧率,32ms 把渲染次数压到
+ * 1/20 左右的量级而观感无差异。低于此值收益边际递减(受 pty 写吞吐约束),高于此值
+ * 长文本回复会有肉眼可见的「一段一段蹦」感。
+ */
+const MD_RENDER_INTERVAL_MS = 32;
+/**
+ * 两次渲染的最小字符增量(**仅用于防饿死**,不是常规触发路径)。
+ *
+ * 后端可能一次性吐出一个大 chunk(如整段代码 / 工具参数),此时距上次渲染可能才过去
+ * 1~2ms,纯按时间判定会把它推迟到下个间隔才上屏。攒够这么多字符就立刻渲,保证
+ * 「有实质进展就尽快上屏」,同时仍拦住小碎 chunk 的逐个重渲。
+ *
+ * **取值的关键**:必须**远大于**「一个节流间隔内正常 chunk 的累积量」,否则它会抢在
+ * 时间节流前面触发,节流退化成「每 N 个 chunk 渲一次」—— 时间维度失效。
+ * 高速后端(约 5ms/chunk、1~2 token ≈ 5 字符)在一个 32ms 间隔内约累积 30 字符,
+ * 取 512 留出 17 倍余量:突发大段能快速上屏,正常流里则几乎只由时间节流驱动。
+ */
+const MD_RENDER_BURST_CHARS = 512;
+/**
+ * 节流判定(纯函数,导出供单测 —— TUI 渲染路径本身需要真 TTY,无法在测试里驱动)。
+ *
+ * @param elapsedNow距上次渲染的毫秒数
+ * @param pendingChars 本次 chunk 累积后、尚未渲染的字符数
+ * @returns true=本次就渲染;false=只累积并挂补渲定时器
+ */
+export function shouldRenderMdSegment(elapsedNow, pendingChars) {
+    return elapsedNow >= MD_RENDER_INTERVAL_MS || pendingChars >= MD_RENDER_BURST_CHARS;
+}
 /**
  * 内容区正文写:CUP 到续写位 + 写出 + 按字符宽度/折行更新续写位 + 同步入 content 缓冲(供滚动回看)。
  * 滚动区域内写满自动在区域内滚动,底栏在区域外不被顶。非 TTY / 未激活:直接 stdout.write(内联退化)。
@@ -164,13 +202,25 @@ function beginMdSegment() {
     content.beginSegment();
     state.mdBuf = '';
     state.mdActive = true;
+    state.mdLastRenderAt = 0;
+    state.mdRenderedLen = 0;
 }
-/** 提交 markdown 段:清 accumulator + content.commitSegment(后续非 md 写不再被 setLines 截断)。 */
+/**
+ * 提交 markdown 段:清 accumulator + content.commitSegment(后续非 md 写不再被 setLines 截断)。
+ *
+ * 必须先 flushMdSegment:commitSegment 会清 segMark,此后 setLines 不再截断到段头——若此时
+ * mdBuf 还有未渲的 chunk,那部分内容将永远进不了缓冲(静默丢字)。故「收尾」语义在这里
+ * 兑现:任何离开 md 段的路径都先把累积内容渲上屏。这也是节流的安全网:定时器只是兜底,
+ * 真正的收尾由本函数保证。
+ */
 function commitMd() {
     if (!state.mdActive)
         return;
+    flushMdSegment();
     state.mdActive = false;
     state.mdBuf = '';
+    state.mdLastRenderAt = 0;
+    state.mdRenderedLen = 0;
     content.commitSegment();
 }
 // ── Banner(启动横幅/模式切换横幅)固定顶部行 ──
@@ -235,25 +285,18 @@ export function rewriteBanner(lines) {
 export function bannerHeight() {
     return state.bannerH;
 }
+/** 本段已渲染进缓冲的 mdBuf 长度(节流的内容判定用;md 段外无意义故返回 0)。 */
+function mdRenderedLen() {
+    return state.mdActive ? state.mdRenderedLen : 0;
+}
 /**
- * markdown 正文写(替代 contentWrite 用于 agent onText):累积 chunk 到 mdBuf,每 chunk 把整段
- * mdBuf 经 renderMarkdown 渲成自洽 ANSI 行,replace 缓冲段(content.setLines 截旧 + 写新),
- * repaintViewport 重画(仅尾 offset=0 且未暂停)。流式安全:未闭合 fence 照常 emit 进行中代码块;
- * renderMarkdown 内部 memo by text 使重复渲染命中缓存。非 TTY / 未激活:直接 stdout.write(与
- * contentWrite 一致,管道流式可见)。
+ * 把当前 mdBuf 渲成自洽行并 replace 缓冲段 + 重画 viewport。
  *
- * 续写位 = 段末下一行(段占 lines.length 行从 segmentStartRow 起);超可视区则滚动留 contentBottom。
- * 物理重画用 repaintViewport(全内容区,原子一次 write 无闪烁)— md 段是缓冲尾,viewport 显尾即显段。
- * 滚动回看(scrollOffset>0)只更新缓冲不物理写(回尾时显);打字中照常物理写——单次 write 结尾 cup 回输入框,IME 锚定不动。
+ * 从 contentWriteMd 抽出的独立步骤:节流路径在「攒够间隔」和「收尾强制补渲」两条路上
+ * 都要用到它。行为与原 contentWriteMd 渲染体逐行一致(滚动回看冻结、续写位推进、
+ * running 态光标归位都在此),调用方只负责决定**何时**调。
  */
-export function contentWriteMd(s) {
-    if (!state.active || !ui.isTTY) {
-        stdout.write(s);
-        return;
-    }
-    if (!state.mdActive)
-        beginMdSegment();
-    state.mdBuf += s;
+function renderMdSegment() {
     const g = getGeo();
     // 滚动回看冻结(同 contentWrite):scrollOffset>0 时 setLines 替换段会改缓冲行数,若 offset 不变,
     // 下次 scrollBy→repaintViewport 取漂移窗口、把流式正文画进历史视图。故 setLines 前后算 totalRows 差,
@@ -262,6 +305,7 @@ export function contentWriteMd(s) {
     const totalBefore = scrolled ? content.totalRows() : 0;
     const lines = renderMarkdown(state.mdBuf, g.cols);
     content.setLines(lines, state.mdBuf);
+    state.mdRenderedLen = state.mdBuf.length;
     const segRows = lines.length;
     const available = g.contentBottom - state.segmentStartRow + 1;
     state.contentRow = segRows >= available ? g.contentBottom : state.segmentStartRow + segRows;
@@ -273,6 +317,7 @@ export function contentWriteMd(s) {
             state.scrollOffset = Math.max(0, Math.min(state.scrollOffset + delta, maxOff));
         }
     }
+    state.mdLastRenderAt = Date.now();
     if (state.scrollOffset === 0) {
         repaintViewport(); // 单次 write 结尾 cup 回 runningCaretPos(运行态),IME 锚输入框;打字中不再暂停
         if (state.mode === 'running') {
@@ -281,6 +326,75 @@ export function contentWriteMd(s) {
         }
     }
 }
+/**
+ * 立即把mdBuf 渲进缓冲并重画,并撤销待补渲定时器。
+ *
+ * 所有「不能留待定时器补渲」的路径都必须走这里(收尾/ 换段 / resize / 清屏 / 退出):
+ * 缓冲内容是后续一切布局计算(contentInsertAfter 的 segMark 平移、contentRow 续写位、
+ * reflow 的 activeSegmentStart)的地基,留着未渲的 chunk 会让它们算错。
+ *
+ * 导出给 layout-internal/core 的 enterInputMode 用(轮末兜底补渲);core 只在 mdActive
+ * 时调,其余调用方是本模块内的 commitMd / clearContent。
+ */
+export function flushMdSegment() {
+    if (state.mdFlushTimer) {
+        clearTimeout(state.mdFlushTimer);
+        state.mdFlushTimer = null;
+    }
+    if (!state.mdActive)
+        return;
+    renderMdSegment();
+}
+/**
+ * markdown 正文写(替代 contentWrite 用于 agent onText):累积 chunk 到 mdBuf,**按节流节奏**
+ * 经 renderMarkdown 渲成自洽 ANSI 行,replace 缓冲段(content.setLines)+ repaintViewport 重画。
+ * 非 TTY / 未激活:直接 stdout.write(与 contentWrite 一致,管道流式可见)。
+ *
+ * **节流(2026-10-05)**:每 chunk 重渲整个累积 mdBuf 是 O(n²)(实测 5879 字符回复 →
+ * 1960 chunk → 累计扫描 5.5MB / ~900ms 纯 CPU),而 renderMarkdown 的 LRU memo 在流式下
+ * 必然 miss。改为:距上次渲染不足 MD_RENDER_INTERVAL_MS 时只累积 chunk 并挂补渲定时器。
+ *
+ * 渲染时机由**时间**主导(唯一正常路径的触发条件),内容增益只在「时间未到但已攒了
+ * 远超一帧正常量的字符」时放行:
+ *  - elapsed ≥ MD_RENDER_INTERVAL_MS:正常节流(约 30fps)
+ *  - 累积 ≥ MD_RENDER_BURST_CHARS:防单个超大 chunk 饿死。取 MD_RENDER_BURST_CHARS
+ *    远大于「一个间隔内正常 chunk 的累积量」是重点 —— 否则它会退化成「每 N chunk 渲一次」,
+ *    时间节流失效(实测取 64 时只降到 2x,因为高速流每 20ms 就攒够 64 字符)。
+ *    高速后端(约 5ms/chunk)一个 32ms 间隔约累积 6~7 个 token(~25 字符),故取 512:
+ *    既允许突发大段快速上屏,又不会在正常流里抢在时间节流前面触发。
+ *
+ * 续写位 = 段末下一行(段占 lines.length 行从 segmentStartRow 起);超可视区则滚动留 contentBottom。
+ * 物理重画用 repaintViewport(全内容区,原子一次 write 无闪烁)— md 段是缓冲尾,viewport 显尾即显段。
+ * 滚动回看(scrollOffset>0)只更新缓冲不物理写(回尾时显);打字中照常物理写——单次 write 结尾 cup 回输入框,IME 锚定不动。
+ *
+ * 收尾安全网:onToolCall / 轮末 / resize / 任何非 md 写都经 commitMd → flushMdSegment,
+ * 补渲定时器到点也会渲染,故不存在「最后一段丢失」。见 beginMdSegment/commitMd 的定时器清理。
+ */
+export function contentWriteMd(s) {
+    if (!state.active || !ui.isTTY) {
+        stdout.write(s);
+        return;
+    }
+    if (!state.mdActive)
+        beginMdSegment();
+    state.mdBuf += s;
+    const now = Date.now();
+    const elapsed = now - state.mdLastRenderAt;
+    if (shouldRenderMdSegment(elapsed, state.mdBuf.length - mdRenderedLen())) {
+        flushMdSegment();
+        return;
+    }
+    // 尚未到渲染节奏:挂一个补渲定时器(若已有则不重复挂——同一段内始终只有一个)。
+    // unref:该定时器不该让进程在退出时多留一帧;退出路径由 exitAltScreen 清理。
+    if (!state.mdFlushTimer) {
+        state.mdFlushTimer = setTimeout(() => {
+            state.mdFlushTimer = null;
+            if (state.active && state.mdActive)
+                renderMdSegment();
+        }, MD_RENDER_INTERVAL_MS - elapsed);
+        state.mdFlushTimer.unref?.();
+    }
+}
 /**
  * 把一段完整(非流式)assistant 文本渲染进独立 markdown 段(供 renderHistory /resume /
  * /rollback 回放)。与流式 contentWriteMd 的区别是一次完成 begin/set/commit，不累积 chunk；
@@ -321,6 +435,15 @@ export function clearContent() {
     state.scrollLockUntil = 0;
     state.mdActive = false;
     state.mdBuf = '';
+    // 清 md 段状态必须同时撤掉待补渲定时器:否则它在 content.reset() 之后才到点触发,
+    // 往已清空的 buffer 里 setLines(残留 mdBuf 的旧内容) —— /clear、/resume、/theme
+    // 都会走到这里,表现为清屏后凭空冒出几行旧正文。
+    if (state.mdFlushTimer) {
+        clearTimeout(state.mdFlushTimer);
+        state.mdFlushTimer = null;
+    }
+    state.mdLastRenderAt = 0;
+    state.mdRenderedLen = 0;
     // 清内容缓冲时必须同步重置 banner 状态:否则后续 writeBanner() 会走 rewriteBanner 路径,
     // 在已空的 content 上调 replaceHead(0, lines) → startIdx(0) >= committed(0) → 抛错 → REPL 退出。
     // /theme、/clear、/resume 等命令 clearContent 后紧接 writeBanner 的场景均依赖此重置。
@@ -465,6 +588,11 @@ export function dismissWelcomeBlock() {
 export function contentInsertAfter(after, lines, keepViewport = true) {
     if (!state.active || lines.length === 0)
         return;
+    // 节流后 mdBuf 可能仍有未渲 chunk:调用方给的 after 是按**当前 buffer** 算的绝对行索引,
+    // 而待渲 chunk 还没进buffer。不先补渲就会插到错误位置(展开行插进正文中间)。
+    // 故凡有活跃 md 段,插入前先把累积内容渲上屏,让 buffer 与 mdBuf 对齐。
+    if (state.mdActive)
+        flushMdSegment();
     const g = getGeo();
     const totalBefore = content.totalRows();
     const scrolled = state.scrollOffset > 0;
@@ -510,6 +638,9 @@ export function contentInsertAfter(after, lines, keepViewport = true) {
 export function contentDeleteFrom(startIdx, n) {
     if (!state.active || n <= 0)
         return;
+    // 同 contentInsertAfter:startIdx 是按当前 buffer 算的,先补渲让两者对齐。
+    if (state.mdActive)
+        flushMdSegment();
     const totalBefore = content.totalRows();
     const scrolled = state.scrollOffset > 0;
     content.deleteFrom(startIdx, n);
@@ -605,6 +736,12 @@ function remapLineForReflow(line, change) {
 }
 /** 终端尺寸变化后更新正文布局。列宽变化时先重排欢迎块、再重排 markdown 段;仅高度变化时只重算屏幕锚点。 */
 export function reflowContentForResize(cols, colsChanged) {
+    // 节流后 mdBuf 可能仍有未渲的 chunk:reflowMarkdown 拿 segment.source(上次 setLines 时
+    // 的 source)按新列宽重排,若 source 滞后于 mdBuf,重排的是旧文本,而紧接着的一次
+    // 补渲又会把新文本按新列宽整段渲一遍 —— 中间这拍白做,更糟的是 oldLines/newLines 的
+    // 选区映射基于旧文本,用户选中的位置会漂。先补渲,让 reflow 看到的 source 与 mdBuf 一致。
+    if (state.mdActive)
+        flushMdSegment();
     const oldTotal = content.totalRows();
     const oldViewportStart = viewportAbsStart();
     const oldViewportEnd = Math.max(oldViewportStart, oldTotal - state.scrollOffset - 1);

package/dist/ui/layout-internal/core.js

@@ -28,7 +28,7 @@ import { normalizeSelection, normalizeInputSelection, extractSelectionText, extr
 import { composePlanLines, drawStatusBar, startTurnTimer, stopTurnTimer } from './statusbar.js';
 import { paintInput, repaint } from './input-paint.js';
 import { WHEEL_LINES, screenRowToAbsLine, repaintViewport, scrollBy, scrollWheel, resetScroll, lockScrollToBottom, } from './scroll.js';
-import { contentWrite, contentInsertAfter, contentDeleteFrom, contentReplaceLine, reflowContentForResize, } from './content-write.js';
+import { contentWrite, contentInsertAfter, contentDeleteFrom, contentReplaceLine, reflowContentForResize, flushMdSegment, } from './content-write.js';
 export { isTuiActive, getGeo, setRegion, contentMode, isStreamingPaused } from './screen.js';
 export { drawStatusBar, setStatus, stopTurnTimer, startTurnTimerIfRunning, paintLiveAtCursor, clearLiveAtCursor, setLiveUsage, setStatusBase, } from './statusbar.js';
 export { paintInput, paintRunningInput, repaint } from './input-paint.js';
@@ -396,6 +396,12 @@ export function enterInputMode(status = t('repl.idle')) {
         if (state.active)
             repaintViewport();
     }
+    // 轮末补渲流式 md:节流后 mdBuf 可能仍有未渲的 chunk(下一次渲染的定时器还没到点),
+    // 而下面要画输入框、repaintViewport —— 画面会停在上一帧,看起来像「回复最后几句丢了」。
+    // 正常轮末会先经 commitMd(有 flush)走到这里,mdActive 应已是 false;此分支只兜
+    // 「异常路径直接进输入态」的情况,故只在 mdActive 时才动手。
+    if (state.active && state.mdActive)
+        flushMdSegment();
     if (state.active && state.base) {
         // 先按当前 base.planSummary 重算 planRows(可能从上次会话残留 stale 值),再据此 setRegion
         // 撑出正确脚栏高;否则 plan 撑 2 行时 setRegion(6) 会把 spinner 挤到 plan 第 2 行位置。
@@ -462,6 +468,12 @@ export function enterAltScreen() {
     state.scrollLockUntil = 0;
     state.mdActive = false;
     state.mdBuf = '';
+    if (state.mdFlushTimer) {
+        clearTimeout(state.mdFlushTimer);
+        state.mdFlushTimer = null;
+    }
+    state.mdLastRenderAt = 0;
+    state.mdRenderedLen = 0;
     state.selection = null;
     state.selecting = false;
     content.reset();
@@ -570,6 +582,11 @@ export function exitAltScreen() {
         clearTimeout(state.flushTimer);
         state.flushTimer = null;
     }
+    // 流式 md 补渲定时器同理:退出后再触发会往已退 alt screen 的终端写内容。
+    if (state.mdFlushTimer) {
+        clearTimeout(state.mdFlushTimer);
+        state.mdFlushTimer = null;
+    }
     state.userActiveUntil = 0;
 }
 /**

package/dist/ui/layout-internal/state.js

@@ -25,11 +25,23 @@ export const state = {
     contentRow: 1, // 续写位行(1-based,屏坐标,[1,contentBottom])
     contentCol: 1, // 续写位列(1-based)
     segmentStartRow: 1, // 当前 md 段起始屏行(供 contentWriteMd 定位段末续写位;段内行数由 content 段标记跟踪)
-    /** markdown 流式段:agent onText 的 chunk 累积到 mdBuf,每 chunk 把整段经 renderMarkdown
+    /** markdown 流式段:agent onText 的 chunk 累积到 mdBuf,按节流节奏经renderMarkdown
      *  渲成自洽行,replace 缓冲段(content.setLines)+ repaintViewport 重画。mdActive 期间任何
-     *  非 md 写(contentWrite)先 commitMd 收尾(清 segMark,后续写不再被 setLines 截断)。 */
+     *  非 md 写(contentWrite)先 commitMd 收尾(清 segMark,后续写不再被 setLines 截断)。
+     *
+     *  **为什么需要节流**(2026-10-05 实测):每 chunk 重渲整个累积 mdBuf 是 O(n²)——
+     *  一次 5879 字符回复被切成~1960 chunk,累计扫描 5.5MB、纯 CPU ~900ms。renderMarkdown
+     *  内部的 LRU memo(key=text)在流式下每次 text 都变,必然 miss,救不了。真正的成本是
+     *  **次数**而非单次(实测单次 render 仅 0.05ms 量级)。故改为「攒够一段时间或跨过行
+     *  边界才渲」,把渲染次数从 O(chunk数) 降到 O(耗时/节流间隔)。 */
     mdActive: false,
     mdBuf: '',
+    /** 流式 md 上次实际渲染的时刻(Date.now());0=本段尚未渲过。节流判定用。 */
+    mdLastRenderAt: 0,
+    /** 本段已渲进缓冲的 mdBuf 长度;内容节流判定「攒够多少」用。 */
+    mdRenderedLen: 0,
+    /** 节流到期的定时器;非 null 表示「还有未渲染的 chunk 待补渲」。 */
+    mdFlushTimer: null,
     bannerH: 0,
     welcomeStart: -1, // 块起点(content.committedRows 口径的绝对行索引)
     welcomeRows: 0, // 块行数(0 = 屏上无欢迎块)

package/dist/verification/discovery.js

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { discoverProjectProfile } from './profile.js';
 const COMPATIBILITY_PRIORITY = ['typecheck', 'test', 'build'];
-const LAYERED_ORDER = ['typecheck', 'build', 'test'];
+const LAYERED_ORDER = ['typecheck', 'lint', 'build', 'test'];
 const isWindows = process.platform === 'win32';
 function samePath(left, right) {
     const normalizedLeft = path.resolve(left);

package/dist/verification/prompt.js

@@ -18,7 +18,7 @@ function lineFor(profile, packageProfile) {
 /**
  * Deterministic project validation map injected into the system prompt: which package owns which
  * script, and the exact command plus cwd to run it. Commands are listed in increasing cost order
- * (typecheck → build → test) and are never executed here — this is evidence, not a completion gate.
+ * (typecheck → lint → build → test) and are never executed here — this is evidence, not a completion gate.
  *
  * Returns '' when no package exposes a validation script, or when discovery fails for any reason
  * (missing/invalid manifest, unreadable workspace): prompt construction must never break.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.6.10",
+  "version": "1.7.1",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 27 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {