mocode-ai 1.2.5 → 1.2.7

package/dist/commands/skill.js

@@ -0,0 +1,230 @@
+// `mocode skill` CLI 子命令(skill 自进化 Phase 0/1 的用户入口)。
+//
+//   mocode skill eval <name> [--runs N] [--threshold x] [--timeout ms]
+//       触发评测:对 <skill-dir>/evals/trigger.json 的每条 query 跑单轮 agent,
+//       统计 use_skill/run_skill 触发率,输出 PASS/FAIL 报告并落盘 JSON。
+//
+//   mocode skill improve <name> [--runs N] [--threshold x] [--iterations N]
+//                     [--holdout x] [--timeout ms] [--apply]
+//       description 进化循环:train/holdout 切分 + LLM 提案 + 接受门,默认 dry-run
+//       只打印最佳 description;--apply 才写回 SKILL.md(写前显式确认;非 TTY 拒绝)。
+//
+//   mocode skill usage [name]
+//       展示使用台账(Phase 0):按 skill 的调用次数/成功率/最近失败。
+//
+// 由 index.ts 在 `mocode skill …` 时动态加载(与 mocode config 同模式):
+// 此时才引入 config 单例(LLM 配置)+ agent 依赖图,缺 LLM 配置时给友好报错而非崩。
+// 纯打印/非 TUI:本进程不进 alt screen,输出走 stdout。
+import * as readline from 'node:readline';
+import path from 'node:path';
+import { config, isModelConfigured } from '../config/index.js';
+import { listSkills } from '../skills/index.js';
+import { loadSkillForEval, loadTriggerEvalSet, triggerEvalTemplate, triggerEvalPath, runTriggerEval, renderTriggerReport, saveTriggerReport, validateEvalParams, } from '../skills/skill-eval.js';
+import { runImproveLoop, applyImprovedDescription } from '../skills/skill-improve.js';
+import { loadSkillUsage, aggregateSkillStats, skillStatsPath } from '../skills/stats.js';
+function usage() {
+    console.log(`mocode skill — skill 自进化(触发评测 / description 进化 / 使用台账)
+
+用法:
+  mocode skill eval <name> [选项]        触发评测(需要 <skill-dir>/evals/trigger.json)
+  mocode skill improve <name> [选项]     description 进化循环(默认 dry-run)
+  mocode skill usage [name]              展示使用台账
+
+eval 选项:
+  --runs <n>          每 query 运行次数(默认 3;1..10)
+  --threshold <x>     触发率判定阈值(默认 0.5;>0 且 ≤1)
+  --timeout <ms>      单 query 超时(默认 60000)
+
+improve 选项:
+  --runs <n>          同 eval(默认 3)
+  --threshold <x>     同 eval(默认 0.5)
+  --iterations <n>    迭代上限(默认 5)
+  --holdout <x>       holdout 比例(默认 0.4;0 禁用)
+  --timeout <ms>      单 query 超时(默认 60000)
+  --apply             把最佳 description 写回 SKILL.md(默认 dry-run,仅打印)
+
+eval 集格式(<skill-dir>/evals/trigger.json,非空数组):
+  [
+    { "query": "应该触发该 skill 的真实请求", "should_trigger": true },
+    { "query": "不应触发的相近请求", "should_trigger": false }
+  ]
+
+注: 进化对象仅限 ~/.mocode/skills 与 <cwd>/.mocode/skills 下的 skill(内置 skill 不可进化)。
+    没有 evals/trigger.json 的 skill 只能 eval 前手工补建,improve 一律拒绝(没验证门不优化)。`);
+}
+function numArg(args, name, fallback) {
+    const i = args.indexOf(name);
+    if (i === -1 || i + 1 >= args.length)
+        return fallback;
+    const v = Number(args[i + 1]);
+    if (!Number.isFinite(v) || v <= 0) {
+        throw new Error(`${name} 需要正数: ${args[i + 1]}`);
+    }
+    return v;
+}
+function parseCommon(args) {
+    const runs = Math.round(numArg(args, '--runs', 3));
+    const threshold = numArg(args, '--threshold', 0.5);
+    const timeoutMs = Math.round(numArg(args, '--timeout', 60_000));
+    const err = validateEvalParams(runs, threshold);
+    if (err)
+        throw new Error(err);
+    return { runs, threshold, timeoutMs };
+}
+function requireModel() {
+    if (!isModelConfigured()) {
+        console.error('未配置 LLM(缺 LLM_BASE_URL / LLM_API_KEY)。先运行 `mocode config` 或设置环境变量。');
+        process.exit(1);
+    }
+}
+/** 定位 eval 集;缺失时打印模板并退出(不猜、不自动建)。 */
+function requireEvalSet(skillName) {
+    const skill = loadSkillForEval(skillName);
+    const cases = loadTriggerEvalSet(skill);
+    if (!cases) {
+        console.error(`未找到触发评测集: ${path.relative(process.cwd(), triggerEvalPath(skill))}`);
+        console.error('手工创建该文件(格式):');
+        console.error(triggerEvalTemplate(skill));
+        process.exit(1);
+    }
+    return { skill, cases };
+}
+async function evalCommand(args) {
+    const rest = args.slice();
+    const name = rest.find((a) => !a.startsWith('--'));
+    if (!name)
+        throw new Error('缺少 skill 名。见: mocode skill eval --help');
+    requireModel();
+    const { skill, cases } = requireEvalSet(name);
+    const { runs, threshold, timeoutMs } = parseCommon(rest);
+    console.log(`评测 skill "${skill.name}" — ${cases.length} 条 query × ${runs} 次,模型 ${config.model}\n`);
+    const startedAt = Date.now();
+    const report = await runTriggerEval(skill, skill.description, cases, runs, threshold, {
+        timeoutMs,
+        onProgress: (_d, _t, line) => process.stdout.write(line + '\n'),
+    });
+    const saved = saveTriggerReport(report);
+    console.log(`\n${renderTriggerReport(report, { runsPerQuery: runs, threshold })}`);
+    console.log(`\n耗时 ${((Date.now() - startedAt) / 1000).toFixed(1)}s,结果已存: ${path.relative(process.cwd(), saved)}`);
+    if (report.summary.passed < report.summary.total) {
+        console.log('存在失败项。可用 `mocode skill improve ' + skill.name + '` 尝试自动优化 description(dry-run)。');
+        process.exitCode = 1;
+    }
+}
+function confirmApply(skillName) {
+    if (!process.stdin.isTTY) {
+        // 非 TTY fail closed:自动落盘必须有人在场。
+        console.error('非 TTY 环境拒绝 --apply 自动落盘。请在终端运行,或手工编辑 SKILL.md 的 description。');
+        process.exit(1);
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`确认把新 description 写回 skill "${skillName}" 的 SKILL.md?(y/N) `, (ans) => {
+            rl.close();
+            resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
+        });
+    });
+}
+async function improveCommand(args) {
+    const rest = args.slice();
+    const name = rest.find((a) => !a.startsWith('--'));
+    if (!name)
+        throw new Error('缺少 skill 名。见: mocode skill improve --help');
+    requireModel();
+    const { skill, cases } = requireEvalSet(name);
+    const { runs, threshold, timeoutMs } = parseCommon(rest);
+    const iterations = Math.round(numArg(rest, '--iterations', 5));
+    const holdout = (() => {
+        const i = rest.indexOf('--holdout');
+        const v = i === -1 ? 0.4 : Number(rest[i + 1]);
+        if (i !== -1 && (!Number.isFinite(v) || v < 0 || v > 0.9))
+            throw new Error('--holdout 需要 0..0.9 的数');
+        return v;
+    })();
+    const apply = rest.includes('--apply');
+    console.log(`进化 skill "${skill.name}" — ${cases.length} 条 query,train/holdout=${1 - holdout}/${holdout},${apply ? '将写回(--apply)' : 'dry-run(不落盘)'}\n`);
+    const result = await runImproveLoop(skill, cases, {
+        maxIterations: iterations,
+        runsPerQuery: runs,
+        threshold,
+        holdout,
+        timeoutMs,
+        onIteration: (_i, _max, line) => console.log(line),
+    });
+    console.log('');
+    if (!result.improved) {
+        console.log(`没有更优的 description(原 description 已是最佳或循环未产出改进)。`);
+        console.log(`原: ${result.originalDescription}`);
+        return;
+    }
+    console.log(`原 description: ${result.originalDescription}`);
+    console.log(`新 description: ${result.bestDescription}`);
+    if (apply) {
+        const ok = await confirmApply(skill.name);
+        if (!ok) {
+            console.log('已取消写回(dry-run 结果见上,可手工应用)。');
+            return;
+        }
+        applyImprovedDescription(skill, result.bestDescription);
+        console.log(`已写回: ${skill.skillMdPath}`);
+        console.log('提示: 内容哈希已变更,project 级 skill 下次 run_skill 会重新要求信任确认。');
+    }
+    else {
+        console.log('dry-run:未写文件。确认满意后加 --apply 重跑,或直接手工把新 description 写进 SKILL.md。');
+    }
+}
+function usageCommand(args) {
+    const filter = args.find((a) => !a.startsWith('--'));
+    const records = loadSkillUsage();
+    const summaries = aggregateSkillStats(records);
+    const list = filter ? summaries.filter((s) => s.skill === filter) : summaries;
+    if (list.length === 0) {
+        console.log(`(台账为空: ${path.relative(process.cwd(), skillStatsPath())})`);
+        console.log('台账在模型调用 use_skill / run_skill 时自动记录,跑几个会话后这里有数。');
+        return;
+    }
+    for (const s of list) {
+        const rate = s.runSuccessRate === null ? '' : ` run 成功率 ${(s.runSuccessRate * 100).toFixed(0)}%`;
+        console.log(`${s.skill}  ×${s.total}(use ${s.uses} / run ${s.runs})${rate}  最近 ${s.lastUsedAt}`);
+        if (s.lastFailure) {
+            console.log(`  最近失败: ${s.lastFailure.status}${s.lastFailure.code ? ` (${s.lastFailure.code})` : ''} @ ${s.lastFailure.ts}`);
+        }
+    }
+}
+export async function runSkillCommand(args) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        usage();
+        return;
+    }
+    try {
+        if (sub === 'eval')
+            await evalCommand(args.slice(1));
+        else if (sub === 'improve')
+            await improveCommand(args.slice(1));
+        else if (sub === 'usage')
+            usageCommand(args.slice(1));
+        else {
+            console.error(`未知子命令 "${sub}"。`);
+            usage();
+            process.exitCode = 1;
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (/aborted/i.test(msg)) {
+            console.error('\n已中断。');
+            process.exitCode = 130;
+        }
+        else {
+            console.error(`错误: ${msg}`);
+            process.exitCode = 1;
+        }
+    }
+}
+// 供 index.ts 判断子命令名集合(避免它 parse 我们的参数)。
+export const SKILL_SUBCOMMANDS = ['eval', 'improve', 'usage', 'help', '--help', '-h'];
+// listSkills 在 eval/improve 未命中时供报错文案复用(保持与 /skills 一致的名字集)。
+export function listSkillNames() {
+    return listSkills().map((s) => s.name);
+}

package/dist/config/index.js

@@ -3,8 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 import dotenv from 'dotenv';
 import { getCurrentSessionId } from '../session/state.js';
-import { getNotesFilePath } from '../session/notes.js';
+import { getNotesFilePath, extractActiveNotesSections } from '../session/notes.js';
 import { buildWorkDisciplineSection, inferModelFamily } from '../agent/work-discipline.js';
+import { buildValidationCommandsSection } from '../verification/prompt.js';
 import { detectLanguage, setLanguage, t, } from '../i18n/index.js';
 /**
  * 按优先级加载配置文件并回填 process.env:
@@ -40,11 +41,14 @@ export const languageFromShell = process.env.MOCODE_LANGUAGE !== undefined;
 // 在 loadEnvFiles 回填前捕获:哪些 LLM 键由 shell 设置(决定 /model 写文件是否下次启动生效)。
 // 仿 themeFromShell 模式:shell export 的环境变量在 loadEnvFiles 中不被回填(优先级最高),
 // 故 /model 写入 ~/.mocode/config 的同名键下次启动会被 shell 值覆盖——据此给 dim 警告。
-const LLM_ENV_KEYS = ['LLM_BASE_URL', 'LLM_API_KEY', 'LLM_MODEL', 'CONTEXT_WINDOW_TOKENS'];
+const LLM_ENV_KEYS = ['LLM_PROVIDER', 'LLM_BASE_URL', 'LLM_API_KEY', 'LLM_MODEL', 'CONTEXT_WINDOW_TOKENS', 'ANTHROPIC_PROMPT_CACHE'];
 export const DEFAULT_CONTEXT_WINDOW_TOKENS = 256000;
 const llmKeysFromShell = LLM_ENV_KEYS.filter((k) => process.env[k] !== undefined);
 loadEnvFiles();
 setLanguage(detectLanguage(process.env.MOCODE_LANGUAGE));
+export function normalizeLlmProvider(value) {
+    return typeof value === 'string' && value.toLowerCase() === 'anthropic' ? 'anthropic' : 'openai';
+}
 /**
  * 取环境变量;缺则返回空字符串(不退出)。
  * 历史上缺 LLM_BASE_URL/LLM_API_KEY 会 process.exit(1),但 /model 命令已能在 REPL 内配置模型,
@@ -214,20 +218,109 @@ export function reinjectActivePlanIntoSystem(history) {
     sys.content = `${content}${ACTIVE_PLAN_MARKER}${plan}\n`;
     return true;
 }
+/** compact 重注入用的幂等标记:history[0] 中夹住会话笔记段正文(Findings/Decisions/Open Questions/Risks),
+ *  重复注入只替换不累积。与 ACTIVE_PLAN_MARKER 独立,互不干扰。 */
+const NOTES_BODY_MARKER = '\n\n<!-- mocode:session-notes -->\n';
+/**
+ * 把会话笔记段正文重注入系统提示(history[0])。compact 后或本步改了 notes.md 时调用:
+ * 若 notes.md 有活跃笔记段(extractActiveNotesSections 返回非空,已按 5k token 预算裁剪),
+ * 则覆盖旧标记块写入最新内容;若无,则清掉残留标记块。直接改 history[0].content,
+ * 幂等,返回是否改动。与 reinjectActivePlanIntoSystem 独立:plan 段由后者管,笔记段由本函数管。
+ */
+export function reinjectSessionNotesIntoSystem(history) {
+    const sys = history[0];
+    if (!sys || sys.role !== 'system' || typeof sys.content !== 'string')
+        return false;
+    let content = sys.content;
+    const markerIdx = content.indexOf(NOTES_BODY_MARKER);
+    if (markerIdx >= 0) {
+        content = content.slice(0, markerIdx).replace(/\s+$/, '');
+    }
+    const notes = extractActiveNotesSections();
+    if (!notes) {
+        if (markerIdx < 0)
+            return false;
+        sys.content = content;
+        return true;
+    }
+    sys.content = `${content}${NOTES_BODY_MARKER}${notes}\n`;
+    return true;
+}
+/**
+ * 一次性重注入会话状态(plan 段 + 笔记段)到系统提示。返回任一 marker 是否改动。
+ *
+ * @deprecated 热路径已不再调用(#prompt-cache):往 history[0] 追加 plan/笔记会让
+ *   系统提示每次 plan_update / note_append 后变字节,前缀缓存整段失效(系统提示 6-8k token,
+ *   本轮后续每步全价重算)。现由 agent/core 每步在 requestHistory **末尾**注入
+ *   {@link buildSessionStateReminder} 的 ephemeral system 消息:模型看到的信息等价,
+ *   但变动落在前缀末端。本函数仅留给外部集成 / 旧测试,新增调用点请勿使用。
+ */
+export function reinjectSessionStateIntoSystem(history) {
+    const planChanged = reinjectActivePlanIntoSystem(history);
+    const notesChanged = reinjectSessionNotesIntoSystem(history);
+    return planChanged || notesChanged;
+}
+/**
+ * 构造"会话状态提醒"正文(活跃 `## Plan:` 段 + 活跃笔记段正文),供 agent/core 每步
+ * 拼进 requestHistory **末尾**的 ephemeral system 消息。
+ *
+ * 为什么在尾部而不是 history[0](prompt 缓存):plan_update / note_append 是设计上鼓励
+ * 高频调用的工具,一旦它们改写系统提示,支持自动前缀缓存的后端(OpenAI / DeepSeek /
+ * GLM / Qwen)就会从第一个 token 起全部 miss。放到历史末尾后,前面整段(系统提示 + 全部
+ * 已有对话)保持逐字节稳定,只有尾部这一小条随 notes.md 变化。
+ *
+ * 纯读函数:不改 history,也不写文件。notes.md 不存在 / 无活跃内容时返回 ''(零开销)。
+ */
+export function buildSessionStateReminder(sessionId = getCurrentSessionId()) {
+    const plan = extractActivePlanSection(sessionId);
+    const notes = extractActiveNotesSections(undefined, sessionId);
+    if (!plan && !notes)
+        return '';
+    const parts = [
+        '## Session state (current, from notes.md)',
+        'This block mirrors the live session notepad and is refreshed every step; treat it as the authoritative plan/notes state, and ignore any older copy earlier in this conversation.',
+        ...(plan ? [plan] : []),
+        ...(notes ? [notes] : []),
+    ];
+    return parts.join('\n\n');
+}
 const SYSTEM_PROMPT_MEMORY_SECTION = `
 ## Memory (cross-session facts)
 - The prompt may contain a title/summary index; retrieve details with memory_search or inspect all with memory_list. memory_search also surfaces knowledge-graph facts (relations between entities) alongside entry bodies.
 - Save only stable, non-obvious cross-session facts. Search before saving; update an existing entry instead of duplicating it, and archive stale entries.
 - A knowledge-graph layer links entities across memories: explore relations/neighbors with memory_graph (neighbors/add/stats), and attach meaningful links via the links parameter of memory_save when saving.`;
-/** Inject only retrieval guidance; MOCODE.md contents stay outside the prompt until read on demand. */
+/** AGENTS.md 自动导入正文上限:system 位于 history[0] 且 compactHistory 不压缩 system,超长需截断防占窗口(见 memory/README.md)。 */
+const MAX_AGENTS_IMPORT_CHARS = 20000;
+/**
+ * 工作区根 AGENTS.md 自动导入段:与 memory 开关完全无关——
+ * 只要 <cwd>/AGENTS.md 存在就把正文直接拼进 prompt(超 {@link MAX_AGENTS_IMPORT_CHARS} 截断+末尾提示),
+ * 不再只指路让模型按需 read_file。读失败静默跳过(返空串)。
+ */
+function buildAgentsImportSection() {
+    try {
+        const projectAgents = path.join(process.cwd(), 'AGENTS.md');
+        if (!fs.existsSync(projectAgents))
+            return '';
+        const content = fs.readFileSync(projectAgents, 'utf8').trim();
+        if (!content)
+            return '';
+        const body = content.length > MAX_AGENTS_IMPORT_CHARS
+            ? `${content.slice(0, MAX_AGENTS_IMPORT_CHARS)}\n…[AGENTS.md truncated: first ${MAX_AGENTS_IMPORT_CHARS} characters injected]`
+            : content;
+        return `\n## Project memory (AGENTS.md, auto-imported)\n${body}\n- AGENTS.md may be stale: current code and the user request override stale memory.`;
+    }
+    catch {
+        return ''; // 读失败静默跳过:不让导入破坏 prompt 构建
+    }
+}
+/**
+ * Memory 检索指导段(与 AGENTS.md 导入无关):开 isMemoryEnabled() 时才拼,
+ * 注入 memory_search/list/graph 的使用指导。默认关(新用户零侵入)。
+ */
 function buildMemoryPromptSection() {
     if (!isMemoryEnabled())
         return '';
-    const projectMocode = path.join(process.cwd(), 'MOCODE.md');
-    const mocodeHint = fs.existsSync(projectMocode)
-        ? '\n- `MOCODE.md` exists at the workspace root but is not preloaded. Read it with `read_file` only when the task may depend on project architecture, conventions, commands, prior decisions, or user preferences; skip it for greetings and unrelated simple requests. Current code and the user request override stale memory.'
-        : '';
-    return SYSTEM_PROMPT_MEMORY_SECTION + mocodeHint;
+    return SYSTEM_PROMPT_MEMORY_SECTION;
 }
 /**
  * plan 模式追加到系统提示末尾的指令(切到 plan 模式时由 repl 拼进 history[0])。
@@ -258,6 +351,7 @@ ${buildPlanResearchRules()}`;
 }
 /** 兼容旧名字:repl 的 buildSystemMessage 仍引 PLAN_MODE_SUFFIX(变量)。运行时按需现拼。 */
 export function buildBasePrompt(sessionId = getCurrentSessionId()) {
+    const agentsImportSection = buildAgentsImportSection();
     const memorySection = buildMemoryPromptSection();
     const notepadSection = buildNotepadSection(sessionId);
     // 静态主体:稳定段落集中在前,让支持 prompt caching 的后端能命中前缀缓存(#12)。
@@ -283,6 +377,7 @@ Complete programming tasks through an "analyze → call tool → observe result
 - Report: stop when done and give honest conclusions with path:line references (see Reporting).
 - Use web search only when freshness materially affects the answer.
 ${buildCodegraphSection()}
+${buildValidationCommandsSection()}
 
 ## Engineering principles
 ${buildWorkDisciplineSection(inferModelFamily(config.model))}
@@ -313,9 +408,9 @@ ${buildVoiceSection()}
 - **No flattery / no preamble in conclusions**: skip "Sure", "好的", "我已经完成了" and similar no-information prefixes — jump straight to substance.
 - Report honestly: say success when successful, say where you're stuck when failing, and mention anything skipped. Reference code in "path:line" format (e.g., src/index.ts:42). Keep it concise.
 ${t('assistant.languageInstruction')}`;
-    // 动态段(置于末尾):memory 索引 + notepad 索引 + notepad 使用说明。
+    // 动态段(置于末尾):AGENTS.md 项目记忆(无条件) + memory 索引(按开关) + notepad 索引 + notepad 使用说明。
     // 按需注入(#13):有内容的索引才拼对应标题,避免空标题噪声。
-    //   - "## Project context" 仅当 memorySection/notepadSection 非空(notepad 索引依赖 notes.md 存在);
+    //   - "## Project context" 仅当 agentsImportSection/memorySection/notepadSection 任一非空(notepad 索引依赖 notes.md 存在);
     //   - "## Session state" 使用说明**无条件**注入(放在动态尾段首位):否则会陷入"说明依赖 notes.md 存在 → 模型不知要建 → 文件永不存在"的鸡生蛋循环,功能对模型不可见。动态段在静态前缀之后,不影响 prompt 缓存。
     const dynamicParts = [];
     // 会话级私有尾段(子 agent 切片会丢弃):Session state 说明无条件注入在前,Project context 按需在后。
@@ -333,8 +428,10 @@ ${t('assistant.languageInstruction')}`;
         'Keep at most one step in_progress, and mark a step completed as soon as its work is done — do not batch updates to the end of the turn. ' +
         'Write each step so a teammate who lost the conversation could pick it up cold: name the file or symbol, the exact change, and the verification, so the plan survives context compaction. ' +
         'plan_update creates notes.md for you when the task warrants it; read_file the full notes.md whenever you need to recover context after compaction. ' +
-        'When every step is completed, plan_update settles the plan to `## Done:` automatically. Keep other notes concise and session-specific; use memory for stable cross-session facts.');
-    const ctxContent = `${memorySection}${notepadSection}`.trimEnd();
+        'When every step is completed, plan_update settles the plan to `## Done:` automatically. Keep other notes concise and session-specific; use memory for stable cross-session facts.\n' +
+        '## Session notes (resident memory)\n' +
+        'For non-obvious, lasting-value discoveries — subtle constraints, decisions with downstream impact, open questions blocking a choice, or risks affecting later steps — call `note_append` IMMEDIATELY when you make the discovery. The note is written to the same notes.md and its body is re-injected into the prompt automatically (within a 5k-token budget), surviving compaction so you keep remembering what you found/decided this session. Do NOT use it for routine progress (that is the plan) or stable cross-session facts (that is memory_save). Each call appends one item.');
+    const ctxContent = `${agentsImportSection}${memorySection}${notepadSection}`.trimEnd();
     if (ctxContent) {
         dynamicParts.push(`## Project context\n${ctxContent}`);
     }
@@ -382,6 +479,7 @@ export function getPlanModeSuffix() {
     return buildPlanModeSuffix();
 }
 export const config = {
+    provider: normalizeLlmProvider(process.env.LLM_PROVIDER),
     baseURL: requireEnv('LLM_BASE_URL'),
     apiKey: requireEnv('LLM_API_KEY'),
     model: process.env.LLM_MODEL || 'gpt-4o-mini',
@@ -393,6 +491,7 @@ export const config = {
     },
     contextWindowTokens: Number(process.env.CONTEXT_WINDOW_TOKENS) || DEFAULT_CONTEXT_WINDOW_TOKENS,
     includeUsage: process.env.LLM_STREAM_USAGE !== 'false',
+    anthropicPromptCache: process.env.ANTHROPIC_PROMPT_CACHE !== 'false',
     autoCompact: process.env.AUTO_COMPACT !== 'false',
     contextOptimize: process.env.MOCODE_CONTEXT_OPTIMIZE === 'true',
     contextRelprune: process.env.MOCODE_CONTEXT_RELPRUNE === 'true',
@@ -418,6 +517,21 @@ export const config = {
     permissionEnabled: process.env.MOCODE_PERMISSION !== 'false',
     permissionNonInteractiveAllow: process.env.MOCODE_PERMISSION_NON_INTERACTIVE_ALLOW === 'true',
 };
+/**
+ * 会话钉死模型：窗口/会话启动时由 pinSessionModel() 捕获一次。
+ * 运行中 agent 一律经 getActiveModel() 取模型，而非热切的 config.model——
+ * 这样某窗口 /model switch 改写全局 config 后，其它【已经打开】的窗口的
+ * 运行 agent 仍用各自启动时的模型，不会被影响；只有重启/新开窗口才会读全局 config。
+ */
+let sessionModel = null;
+/** 在 REPL 启动时调用一次，把当前模型钉成本会话的活跃模型。 */
+export function pinSessionModel() {
+    sessionModel = config.model;
+}
+/** 运行中 agent 实际使用的模型：优先钉死值，未钉(极早路径)则回退 config.model。 */
+export function getActiveModel() {
+    return sessionModel ?? config.model;
+}
 /**
  * 运行时更新模型相关配置(/model 命令调)。
  * - 更新 config 对象字段(即时生效:chat() 读 config.model,reconfigureClient 读 config.baseURL/apiKey)。
@@ -427,8 +541,16 @@ export const config = {
  * 重建 OpenAI 客户端(baseURL/apiKey 是构造时固化的实例字段)由调用方走 reconfigureClient。
  */
 export function updateModelConfig(opts) {
+    if (opts.provider !== undefined) {
+        config.provider = opts.provider;
+        process.env.LLM_PROVIDER = opts.provider;
+    }
     if (opts.model !== undefined) {
         config.model = opts.model;
+        // 钉死值同步更新：本窗口显式 /model switch 立即对本窗口运行 agent 生效；
+        // 其它已开窗口的 sessionModel 不受影响（各自启动时钉死）。
+        if (sessionModel !== null)
+            sessionModel = opts.model;
         process.env.LLM_MODEL = opts.model;
     }
     if (opts.baseURL !== undefined) {
@@ -443,6 +565,10 @@ export function updateModelConfig(opts) {
         config.contextWindowTokens = opts.contextWindowTokens;
         process.env.CONTEXT_WINDOW_TOKENS = String(opts.contextWindowTokens);
     }
+    if (opts.anthropicPromptCache !== undefined) {
+        config.anthropicPromptCache = opts.anthropicPromptCache;
+        process.env.ANTHROPIC_PROMPT_CACHE = opts.anthropicPromptCache ? 'true' : 'false';
+    }
 }
 /** 子 Agent 总开关；默认 false，关闭时 sub-agent 不进入模型工具表。 */
 export function isSubAgentEnabled() {

package/dist/config/presets.js

@@ -31,8 +31,8 @@ function filePathFor(name) {
     }
     return path.join(MODELS_DIR, `${name}.json`);
 }
-/** 把磁盘上的 raw JSON 解析并校验为 ModelPreset;非法字段抛错。 */
-function parsePreset(raw) {
+/** 把磁盘上的 raw JSON 解析并校验为 ModelPreset;旧预设缺 provider 时按 openai 读取。 */
+export function parsePreset(raw) {
     const obj = JSON.parse(raw);
     const { name, baseURL, apiKey, model, contextWindow } = obj;
     if (typeof name !== 'string' || !isValidPresetName(name)) {
@@ -50,7 +50,17 @@ function parsePreset(raw) {
     if (typeof contextWindow !== 'number' || !Number.isFinite(contextWindow) || contextWindow <= 0) {
         throw new Error(`预设 ${name}: contextWindow 必须为正数`);
     }
-    return { name, baseURL, apiKey, model, contextWindow: Math.floor(contextWindow) };
+    const provider = obj.provider === 'anthropic' ? 'anthropic' : 'openai';
+    const anthropicPromptCache = provider === 'anthropic' && obj.anthropicPromptCache !== false;
+    return {
+        name,
+        provider,
+        baseURL,
+        apiKey,
+        model,
+        contextWindow: Math.floor(contextWindow),
+        anthropicPromptCache,
+    };
 }
 /** 读单个预设;不存在抛错。 */
 export function getPreset(name) {
@@ -68,15 +78,21 @@ export function readPreset(name) {
         throw e;
     }
 }
-/** 写/覆盖一个预设(原子:写 tmp 再 rename)。 */
+/** 写/覆盖一个预设(原子:写 tmp 再 rename)。旧调用缺 provider 时仍按 openai 保存。 */
 export function savePreset(preset) {
     if (!isValidPresetName(preset.name)) {
         throw new Error(`非法预设名: ${JSON.stringify(preset.name)}`);
     }
+    const provider = preset.provider ?? 'openai';
+    const normalized = {
+        ...preset,
+        provider,
+        anthropicPromptCache: provider === 'anthropic' && preset.anthropicPromptCache !== false,
+    };
     fs.mkdirSync(MODELS_DIR, { recursive: true });
     const dest = filePathFor(preset.name);
     const tmp = `${dest}.tmp-${process.pid}-${Date.now()}`;
-    fs.writeFileSync(tmp, JSON.stringify(preset, null, 2), 'utf8');
+    fs.writeFileSync(tmp, JSON.stringify(normalized, null, 2), 'utf8');
     fs.renameSync(tmp, dest);
 }
 /** 删除一个预设;不存在返回 false,成功返回 true。 */
@@ -156,11 +172,15 @@ export function migrateCurrentToPreset(input) {
         return null;
     if (!Number.isFinite(input.contextWindow) || input.contextWindow <= 0)
         return null;
+    const provider = input.provider ?? 'openai';
+    const anthropicPromptCache = provider === 'anthropic' && input.anthropicPromptCache !== false;
     const existing = listPresets();
-    const dup = existing.find((p) => p.baseURL === input.baseURL &&
+    const dup = existing.find((p) => p.provider === provider &&
+        p.baseURL === input.baseURL &&
         p.apiKey === input.apiKey &&
         p.model === input.model &&
-        p.contextWindow === input.contextWindow);
+        p.contextWindow === input.contextWindow &&
+        p.anthropicPromptCache === anthropicPromptCache);
     if (dup)
         return null;
     // 'default' 已被占 → 用户已显式起过预设,无需老数据迁入;返回 null 让调用方跳过即可。
@@ -168,10 +188,12 @@ export function migrateCurrentToPreset(input) {
         return null;
     savePreset({
         name: 'default',
+        provider,
         baseURL: input.baseURL,
         apiKey: input.apiKey,
         model: input.model,
         contextWindow: input.contextWindow,
+        anthropicPromptCache,
     });
     return 'default';
 }

package/dist/context/artifacts.js

@@ -131,6 +131,26 @@ export function recordArtifact(state, history, idx, output, succeeded) {
     stateFor(state).artifacts.set(id, artifact);
     updateStats(state, stateFor(state));
 }
+/**
+ * 按读取时间倒序返回最近若干「仍新鲜的 read_file 目标」(path + hash)。
+ * 用途:文件编辑工具参数校验失败(如缺 path)时,把系统已知的候选直接回灌给模型照抄,
+ * 避免模型在长上下文里凭记忆复述出错、补一个字段丢另一个字段的乒乓重试。
+ * 只展示事实、不替模型填值——选哪个候选仍由模型判断。永不抛错。
+ */
+export function knownEditTargets(state, limit = 3) {
+    const artifacts = stateFor(state).artifacts;
+    const targets = [];
+    for (const artifact of artifacts.values()) {
+        if (artifact.freshness !== 'fresh' || artifact.source.type !== 'read')
+            continue;
+        const dependency = artifact.dependencies[0];
+        if (!dependency || dependency.path === '*' || !dependency.hash)
+            continue;
+        targets.push({ path: dependency.path, hash: dependency.hash, version: artifact.version ?? 0 });
+    }
+    targets.sort((a, b) => b.version - a.version);
+    return targets.slice(0, Math.max(1, Math.floor(limit) || 3)).map(({ path, hash }) => ({ path, hash }));
+}
 function affected(artifact, changed) {
     // '*' 依赖(无法解析出具体文件路径的诊断/搜索结果)不与任何具体写操作关联:
     // 任何文件写入都会作废全部 '*' artifact,等于每次 mutation 都销毁

package/dist/context/budget.js

@@ -54,8 +54,10 @@ export function userTurnBoundary(history, window) {
 /** 评估当前 history 的五区预算(纯函数,改不动 history)。
  * 传入 step 是当前所在 step 编号(agent 循环 step 变量),用于日志/调试。
  * correction:API 实测 / 估算的校正系数(默认 1);>1 表示粗估偏低,乘以系数后 actual 更接近真实值。
- * activeTools 必须与下一次 chat() 实际发送的工具集合一致，避免 plan/子 agent 误算 schema。 */
-export function evaluateBudget(history, window, step = 0, correction = 1, activeTools = chatTools) {
+ * activeTools 必须与下一次 chat() 实际发送的工具集合一致，避免 plan/子 agent 误算 schema。
+ * ephemeralTokens:本次请求会追加、但不在 history 里的尾部注入(会话状态提醒等)的裸 token,
+ *   必须传入,否则压力线看不见这部分开销(见 SystemCostBreakdown.ephemeral)。 */
+export function evaluateBudget(history, window, step = 0, correction = 1, activeTools = chatTools, ephemeralTokens = 0) {
     const layers = {};
     for (const k of BUDGET_LAYERS) {
         const budget = Math.floor(BUDGET_RATIO[k] * window);
@@ -66,12 +68,17 @@ export function evaluateBudget(history, window, step = 0, correction = 1, active
     // 裸总量(不乘 correction):硬闸用它判断,防止 correction 折扣否决真实溢出。
     let rawTotal = 0;
     const sysMsg = history[0];
+    const safeEphemeral = Number.isFinite(ephemeralTokens)
+        ? Math.max(0, Math.round(ephemeralTokens))
+        : 0;
     const systemCosts = {
         prompt: sysMsg ? msgTokens(sysMsg) : 0,
         toolSchemas: estimateToolSchemaTokens(activeTools),
+        ephemeralInjection: safeEphemeral,
     };
-    // 工具 schema 与 system prompt 同属请求固定开销；必须计入总量才能可靠触发压缩。
-    const systemRaw = systemCosts.prompt + systemCosts.toolSchemas;
+    // 工具 schema、system prompt 与尾部 ephemeral 注入同属请求固定开销；
+    // 必须计入总量才能可靠触发压缩(尾部注入不在 history 里,只能由调用方传入)。
+    const systemRaw = systemCosts.prompt + systemCosts.toolSchemas + systemCosts.ephemeralInjection;
     layers.system.actual = adj(systemRaw);
     rawTotal += systemRaw;
     // Summary 检测:role:'system' 且不是 history[0] 的,视为摘要(compact.ts 摘要插 index 1)。
@@ -143,7 +150,7 @@ export function scheduleActions(report) {
     const actions = [];
     const { layers } = report;
     if (layers.system.overBudget) {
-        const { prompt, toolSchemas } = report.systemCosts;
+        const { prompt, toolSchemas, ephemeralInjection } = report.systemCosts;
         const { actual, budget } = layers.system;
         const excess = actual - budget;
         const percent = ((actual / Math.max(budget, 1)) * 100).toFixed(0);
@@ -151,7 +158,9 @@ export function scheduleActions(report) {
             kind: 'warn',
             layer: 'system',
             reason: `固定开销 ${actual}/${budget} (+${excess}, ${percent}%)；`
-                + `提示 ${prompt} + 工具 ${toolSchemas}，×${report.correction.toFixed(2)}。`,
+                + `提示 ${prompt} + 工具 ${toolSchemas}`
+                + (ephemeralInjection > 0 ? ` + 尾部注入 ${ephemeralInjection}` : '')
+                + `，×${report.correction.toFixed(2)}。`,
         });
     }
     const pressureLine = DEFAULT_BUDGET_POLICY.pressureTriggerRatio * report.window;

package/dist/context/encoders/table.js

@@ -6,7 +6,7 @@
  *  顶部加 `# N entries · table-encoded` 计数头。
  *
  * 不变量(离线脚本断言):id/name/summary/type 全保留;仅 `active` 状态被省略(默认值,无信息损失)。
- *  正则锚定整行 + 要求 `id: ... — ... (type, active)` 形,不匹配的行原样返回(防误伤 MOCODE.md 等正文)。
+ *  正则锚定整行 + 要求 `id: ... — ... (type, active)` 形,不匹配的行原样返回(防误伤 AGENTS.md 等正文)。
  *  group1 贪婪捕获到 `(\w+` 为止,故 name/summary 内含 ` — ` 或 ` (` 也不影响(仅丢尾部 `, active)`)。
  */
 const ACTIVE_LINE_RE = /^(- [^:]+: .+ — .+ \(\w+), active\)$/;