mocode-ai 0.4.7 → 0.4.9

package/dist/agent/core.d.ts

@@ -0,0 +1,112 @@
+import type OpenAI from 'openai';
+import { type ChatMessage, type ChatUsage, type ToolCallRef } from '../llm/index.js';
+/** 解析工具 arguments JSON;非法或空返 null(调用方据此降级到普通 preview)。 */
+declare function parseArgs(raw: string): Record<string, unknown> | null;
+/** 只读工具集:一轮多个时,连续的只读工具成组 Promise.all 并行(无副作用、互不依赖)。 */
+declare const READ_TOOL_NAMES: Set<string>;
+/** mutation 工具:写盘 + 在 executeTool 内记回滚 before 快照,必须串行保快照序。 */
+declare const isMutationTool: (name: string) => boolean;
+/** 工具调用 ● 头所需信息(交给 hooks 渲染;core 不直接写屏)。 */
+export interface ToolCallView {
+    name: string;
+    arguments: string;
+    id: string;
+}
+/** mutation 执行前读旧内容供 diff:write_file 取整文件旧内容(不存在→null=新建),
+ * edit_file 取 old_string 起始行号(供 diff 显示真实文件行号)。读不到则 diff 退化为相对行号。
+ * 非 mutation 或参数非法返 { preWriteOld: null, editStartLine: 1 }。失败不阻断。 */
+declare function readDiffContext(tc: ToolCallRef, parsed: Record<string, unknown> | null): {
+    preWriteOld: string | null;
+    editStartLine: number;
+};
+/**
+ * agent 循环的展示副作用接缝。主 agent 注入 TUI 渲染实现;子 agent 注入静默/摘要实现。
+ * 所有方法可选——core 对 undefined hooks 安全跳过。
+ */
+export interface AgentHooks {
+    /** 流式正文增量(主 agent:走 markdown 渲染写内容区)。 */
+    onText?: (delta: string) => void;
+    /** 模型开始生成某 tool_call 的参数(主 agent:补换行 + 启「生成中」spinner)。 */
+    onToolCall?: (name: string) => void;
+    /** 每步开始,spinner 启「思考中」(主 agent:spinner.start)。 */
+    onStepStart?: () => void;
+    /** chat 返回后停 spinner(主 agent:spinner.stop)。 */
+    onChatDone?: () => void;
+    /** 流式正文末尾补换行(若 onToolCall 已补则 no-op);防 ● 行黏在正文行尾。 */
+    onTextEnd?: () => void;
+    /** 工具调用 ● 头渲染(主 agent:工具名 + 参数摘要)。 */
+    onToolHeader?: (tc: ToolCallRef) => void;
+    /** 启「执行 工具」spinner(主 agent:spinner.start)。 */
+    onToolStart?: (name: string) => void;
+    /** 工具执行完停 spinner(主 agent:spinner.stop)。 */
+    onToolDone?: () => void;
+    /** 工具结果渲染(主 agent:mutation 走 diff 块;其余走一行 preview)。 */
+    onToolResult?: (tc: ToolCallRef, output: string, parsed: Record<string, unknown> | null, preWriteOld: string | null, editStartLine: number) => void;
+    /** 工具步末尾补一空行(与下一轮思考/正文分隔)。 */
+    onToolBatchEnd?: () => void;
+    /** 无回复提示(模型既无文本也无工具调用)。 */
+    onNoReply?: () => void;
+    /** 达到最大步数提示。 */
+    onMaxSteps?: () => void;
+    /** 中断还原:停 spinner + 补换行 + (已中断)提示 + history 还原 + 模式还原。 */
+    onAbort?: () => void;
+    /** 跑完(正常/达上限)在回复末尾打耗时摘要行;中断不调。
+     *  usage 是本轮 chat 调用累计的 token 用量(未开启 include_usage 或全失败时为 undefined)。 */
+    onDone?: (elapsedMs: number, usage?: ChatUsage) => void;
+}
+/** runAgentCore 的运行选项。 */
+export interface AgentRunOptions {
+    history: ChatMessage[];
+    /** 纯文本字符串,或多模态 parts 数组(OpenAI content 数组,text + image_url)。 */
+    userInput: string | ContentPart[];
+    signal?: AbortSignal;
+    /** 每步 chat() 返回后回调:repl 据此重算并重画状态行 context 用量条。 */
+    onContextUpdate?: () => void;
+    hooks: AgentHooks;
+    /** 步数上限;缺省 = config.maxSteps。子 agent 可传更低值。 */
+    maxSteps?: number;
+    /** 工具 schema 覆盖;plan 模式传 planChatTools(只读子集)。子 agent 可传受限子集。
+     *  缺省 = 按 getAgentMode() 自动选(auto=全量 / plan=只读)。 */
+    toolsOverride?: OpenAI.Chat.Completions.ChatCompletionTool[];
+    /** 跳过回滚快照记录(子 agent 逻辑隔离用)。true = 本 agent 的 write_file/edit_file 改动
+     *  不进主回滚链,主 /rollback 不撤销。透传给 executeTool。 */
+    skipRollback?: boolean;
+}
+/** OpenAI content array 的子集(text + image_url);repl 构造 user 多模态消息用。 */
+export type ContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+};
+/** runAgentCore 的运行结果。 */
+export interface AgentRunResult {
+    /** 正常完毕 / 达上限 true;中断 false。 */
+    completed: boolean;
+    /** 最终 assistant 文本回复(content);无回复或中断为 null。 */
+    finalText: string | null;
+    /** 本轮累计 token 用量(各 chat 步 prompt+completion 之和);后端不开 include_usage 或全失败则 undefined。 */
+    usage?: ChatUsage;
+}
+/**
+ * agent 核心循环(纯逻辑):
+ *  流式调 LLM(经 hooks.onText 实时渲染)→ 有 tool_calls 就分组执行并回灌
+ *  → 否则流式正文即最终回复。history 在调用间持久,由调用方持有。
+ *  步前经 session/maybeCompact 自动压缩(接近窗口上限时三层压缩);
+ *  工具结果进 history 前经 Context Optimization Pipeline(optimizeToolResult:类型化编码 + 长度裁剪)。
+ *
+ *  中断语义:signal 经 executeTool(name, args, signal) 串进工具;run_command/web_fetch 等 abort 即时杀
+ *  (树杀子进程 / 取消 fetch),循环顶 if(signal.aborted) 兜底还原。不会留下未配对的 tool_call_id。
+ *  abort 时 history 还原到本 turn 前(savedHistory 浅拷贝),模式还原,调 hooks.onAbort。
+ *
+ *  所有展示副作用经 hooks 注入;core 自身不直接调 layout / spinner(不依赖 ui/layout.ts)。
+ *  但 core 仍依赖 ui/render.ts 的纯函数(summarizeToolCall / truncateDisplay / fmtElapsed)——
+ *  这些是纯字符串格式化,无副作用,共享安全。
+ */
+export declare function runAgentCore(opts: AgentRunOptions): Promise<AgentRunResult>;
+export { parseArgs, readDiffContext, isMutationTool, READ_TOOL_NAMES };
+export type { ChatMessage, ToolCallRef, ChatUsage } from '../llm/index.js';

package/dist/agent/core.js

@@ -6,7 +6,8 @@
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
 import { chat, planChatTools, } from '../llm/index.js';
-import { executeTool } from '../tools/registry.js';
+import { executeTool, tools } from '../tools/registry.js';
+import { checkPermission } from '../permissions/index.js';
 import { getPlanDisabledTools } from '../tools/constants.js';
 import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, dropContextFromHistory } from '../session/index.js';
@@ -328,15 +329,38 @@ export async function runAgentCore(opts) {
                         while (j < calls.length && calls[j].name === 'task')
                             j++;
                         const batch = calls.slice(i, j);
-                        const started = batch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext }));
-                        // 先批量打印所有头 + 启 spinner(多 task 并发,spinner 只显一个,但 ● 头都打出来)
+                        // 权限预检查:逐个 task 弹确认面板(在启动子 agent 之前,体验:先问再执行)。
+                        // 拒绝的 task 直接跳过,不启动子 agent;放行的收集到 allowedBatch。
+                        const allowedBatch = [];
                         for (const tc of batch) {
+                            const parsed = parseArgs(tc.arguments);
+                            const tool = tools.find((t) => t.name === tc.name);
+                            if (tool) {
+                                const perm = await checkPermission(tool, parsed ?? {}, signal);
+                                if (perm === 'deny') {
+                                    hooks.onToolHeader?.(tc);
+                                    const err = `错误:用户拒绝了工具 ${tc.name} 的执行。`;
+                                    hooks.onToolResult?.(tc, err, null, null, 1);
+                                    const hint = recordAndHint(tc.name, tc.arguments);
+                                    pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
+                                    continue;
+                                }
+                            }
+                            allowedBatch.push(tc);
+                        }
+                        if (allowedBatch.length === 0) {
+                            i = j;
+                            continue; // 全部被拒绝,跳过执行
+                        }
+                        const started = allowedBatch.map((tc) => executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext }));
+                        // 先批量打印所有头 + 启 spinner(多 task 并发,spinner 只显一个,但 ● 头都打出来)
+                        for (const tc of allowedBatch) {
                             hooks.onToolHeader?.(tc);
                         }
-                        hooks.onToolStart?.(batch[0].name); // spinner:多 task 共用一个「执行 task…」
+                        hooks.onToolStart?.(allowedBatch[0].name); // spinner:多 task 共用一个「执行 task…」
                         // 逐个 await 出结果(按 tool_calls 原序,保 tool_call_id 配对);结果到即渲染 ↳
-                        for (let k = 0; k < batch.length; k++) {
-                            const tc = batch[k];
+                        for (let k = 0; k < allowedBatch.length; k++) {
+                            const tc = allowedBatch[k];
                             const output = await started[k];
                             hooks.onToolResult?.(tc, output, null, null, 1); // task 结果是摘要,无 diff
                             // Thrashing:同上
@@ -361,15 +385,31 @@ export async function runAgentCore(opts) {
                             i++;
                             continue;
                         }
+                        // 权限预检查:在渲染 ● 头之前弹确认面板(体验:先问再执行,而非执行完再问)。
+                        // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
+                        const parsed = parseArgs(tc.arguments);
+                        const tool = tools.find((t) => t.name === tc.name);
+                        if (tool) {
+                            const perm = await checkPermission(tool, parsed ?? {}, signal);
+                            if (perm === 'deny') {
+                                hooks.onToolHeader?.(tc);
+                                const err = `错误:用户拒绝了工具 ${tc.name} 的执行。`;
+                                hooks.onToolResult?.(tc, err, null, null, 1);
+                                const hint = recordAndHint(tc.name, tc.arguments);
+                                pushToolResult(history, tc, hint ? `${err}${hint}` : err, relprune, lifecycle, scheduler);
+                                i++;
+                                continue;
+                            }
+                        }
                         hooks.onToolHeader?.(tc);
-                        const parsed = isMutationTool(tc.name)
-                            ? parseArgs(tc.arguments)
+                        const mutationParsed = isMutationTool(tc.name)
+                            ? parsed
                             : null;
-                        const { preWriteOld, editStartLine } = readDiffContext(tc, parsed);
+                        const { preWriteOld, editStartLine } = readDiffContext(tc, mutationParsed);
                         hooks.onToolStart?.(tc.name);
                         const output = await executeTool(tc.name, tc.arguments, signal, { skipRollback, dropContext });
                         hooks.onToolDone?.();
-                        hooks.onToolResult?.(tc, output, parsed, preWriteOld, editStartLine);
+                        hooks.onToolResult?.(tc, output, mutationParsed, preWriteOld, editStartLine);
                         // Thrashing:同上(history 附 hint,UI 干净)
                         const hint = recordAndHint(tc.name, tc.arguments);
                         pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler);
@@ -378,7 +418,7 @@ export async function runAgentCore(opts) {
                         // 非 mutation 工具(run_command/use_skill/memory_* 等)此处 path="" 不触发。
                         // 观察者生命周期:mutation push 后通知 lifecycle 把同 path 的旧 read 标 REFERENCED。
                         if (relprune && isMutationTool(tc.name)) {
-                            const mp = parsed?.path;
+                            const mp = mutationParsed?.path;
                             if (typeof mp === 'string' && mp) {
                                 relprune.observeMutation(history, mp);
                                 if (lifecycle)

package/dist/agent/index.d.ts

@@ -0,0 +1,19 @@
+import type { ChatMessage } from '../llm/index.js';
+import { type AgentRunResult, type ContentPart } from './core.js';
+/**
+ * agent 核心循环(主 agent,TUI 渲染版):
+ *  流式调 LLM(onText 实时写内容区)→ 有 tool_calls 就执行并回灌
+ *  → 否则流式正文即最终回复。history 在调用间持久,由 REPL 持有。
+ *  步前经 session/maybeCompact 自动压缩(接近窗口上限时三层压缩);
+ *  工具结果进 history 前经 capToolResultForHistory 裁到单条上限。
+ *
+ *  所有正文写经 layout.contentWrite(保证落在内容区、跟踪续写位、底栏不被顶);
+ *  spinner 经 onFrame 回调刷状态行(layout.drawStatusBar),等待时内容区静止、底栏转圈。
+ *  思考期间不写思考内容,只让 spinner 持续转「思考中…」(首个正文 / tool_call token 到达才停)。
+ *
+ *  循环逻辑委托 runAgentCore;本函数只注入 TUI 渲染 hooks(layout + spinner + diff + 回滚轮次)。
+ *  开新轮次(beginTurn)在入口调——core 不依赖 rollback,回滚轮次是主 agent 的展示副作用。
+ */
+export declare function runAgent(history: ChatMessage[], userInput: string | ContentPart[], signal?: AbortSignal, 
+/** 每步 chat() 返回后回调:repl 据此重算并重画状态行 context 用量条(运行中实时刷新,不冻结在轮首)。 */
+onContextUpdate?: () => void): Promise<AgentRunResult>;

package/dist/agent/mode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * agent 模式的共享状态(零依赖纯叶子)。
+ *
+ * 把 `agentMode` 从 repl 的模块变量提到这里,让三方都能用、且不破坏依赖单向:
+ *  - `tools/builtins/switch-mode.ts` 写它(setAgentMode)——LLM 在 agent 循环里自切 plan↔auto。
+ *  - `agent/index.ts` 每步读它(getAgentMode)——决定 chat() 用全量 chatTools 还是 planChatTools 只读子集,
+ *    以及串行分支的 plan 防御 backstop。这样 LLM 中途切模式后,下一次 chat() 立即看到新工具集。
+ *  - `repl/index.ts` 读写它 + 注册 onModeChange 监听器(做 applyMode 重写 history[0] + refreshStatusBase
+ *    刷状态行 modeTag)。
+ *
+ * 依赖方向无环:本模块不 import 任何业务模块。`agent/index → tools/registry → tools/builtins/switch-mode
+ * → agent/mode` 链终点是本叶子,不回到 agent/index。`tools → agent/mode` 与既有 `tools → ui`(ask-human)、
+ * `tools → rollback`(registry)同性质——都是引叶子。
+ *
+ * listener 同步触发:setAgentMode 在变更模式后同步调 listener(无 async)。switch_mode 工具在 executeTool
+ * 内调 setAgentMode → listener 同步 applyMode(重写 history[0])+ refreshStatusBase;execute 返回字符串后,
+ * agent 串行分支继续,下一步 chat() 读到新模式 + 新系统提示,一致。
+ */
+export type AgentMode = 'auto' | 'plan';
+/** 当前 agent 模式。auto=全工具执行;plan=只读探查 + 产出计划(写盘/命令/记忆写入工具被 schema 剔除)。 */
+export declare function getAgentMode(): AgentMode;
+/**
+ * 设置 agent 模式。同模式 no-op(不触发 listener)。变更时同步触发 onModeChange 注册的监听器
+ * (repl 在 startRepl 注册:applyMode 重写 history[0] + refreshStatusBase 刷状态行)。
+ * 返回之前的模式,供调用方(如 runAgent 中断恢复)还原。
+ */
+export declare function setAgentMode(m: AgentMode): AgentMode;
+/** 注册模式变更监听器(单一,后注册覆盖先注册)。repl 在 startRepl 启动时注册一次。 */
+export declare function onModeChange(cb: (m: AgentMode) => void): void;

package/dist/agent/spawn.d.ts

@@ -0,0 +1,36 @@
+/** 子 agent 运行选项。 */
+export interface SpawnOptions {
+    /** 子任务指令(作为子 agent 的 user 消息)。 */
+    prompt: string;
+    /** 附加系统提示(角色/约束),拼在 SUBAGENT_SUFFIX 后。 */
+    systemPromptSuffix?: string;
+    /** 允许的工具名白名单(可选)。无 = 全量工具;给则从 chatTools 过滤。 */
+    tools?: string[];
+    /** 步数上限(可选,默认 config.subAgentMaxSteps ?? 50)。 */
+    maxSteps?: number;
+    /** 主 agent 的 abort signal(可选)。透传给子 runAgentCore → chat/executeTool,
+     *  主 Ctrl+C 树杀子 agent(chat 流式 abort + run_command/web_fetch 即时取消)。 */
+    signal?: AbortSignal;
+}
+/** 子 agent 运行结果。 */
+export interface SpawnResult {
+    /** 子 agent 最终文本回复;中断或无回复为 null。 */
+    summary: string | null;
+    /** 正常完毕 true;中断 false。 */
+    completed: boolean;
+    /** 子 agent 中间过程的人类可读日志(工具调用 + 结果摘要 + 流式正文片段)。主 agent 通常不看,调试用。 */
+    transcript: string;
+}
+/**
+ * 派生一个子 agent 执行独立子任务。
+ *
+ * 行为:
+ *  - 构造独立 history:[{system: 主系统提示 + SUBAGENT_SUFFIX + 自定义后缀}, {user: prompt}]
+ *  - 工具子集:按 opts.tools 白名单过滤 chatTools;无白名单 = 全量。
+ *  - 静默 hooks:流式正文 / 工具头 / 结果缓冲到 transcript;不写主屏(layout)。
+ *  - 返回 { summary, completed, transcript }。summary 给 task 工具回灌主 history。
+ *
+ * 中断:opts.signal 透传给子 runAgentCore——主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)。
+ * 子 agent 跑在主 signal 下,主 abort 即子 abort;子 agent 的 abortRestore 还原子 history + 模式。
+ */
+export declare function spawnAgent(opts: SpawnOptions): Promise<SpawnResult>;

package/dist/attachments/image.d.ts

@@ -0,0 +1,22 @@
+export type ImageMime = 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp';
+export interface ImageAttachment {
+    id: string;
+    path: string;
+    name: string;
+    bytes: number;
+    mime: ImageMime;
+    dataUrl: string;
+}
+export declare const MAX_INLINE_BYTES_DEFAULT: number;
+export declare function detectMime(p: string): ImageMime | null;
+export declare function renderChip(att: ImageAttachment): string;
+export type LoadImageResult = {
+    ok: true;
+    att: ImageAttachment;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function loadImageAttachment(input: string, opts: {
+    maxBytes: number;
+}): Promise<LoadImageResult>;

package/dist/commands/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 首跑配置向导:交互填 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL,写 ~/.mocode/config。
+ * 只交互三键、保留文件里其它键(MAX_TOKENS / CONTEXT_WINDOW_TOKENS / MOCODE_THEME 等)。
+ * prompt 全纯文本(readline 光标按字符算,不能含 ANSI)。
+ * 由 index.ts 在 `mocode config` 时动态加载,故不 import config/index.ts(避免触发 config 单例初始化 / loadEnvFiles,
+ * 直接退出);只 import config/file.ts(纯 I/O 叶子,无 env 校验 / process.exit)。
+ */
+export declare function runConfigWizard(): Promise<void>;

package/dist/config/file.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ~/.mocode/config 全局 dotenv 配置的读写叶子(纯 node:fs / node:os / node:path + dotenv)。
+ *
+ * 独立于 `config/index.ts`——**不**触发 config 单例初始化 / loadEnvFiles,故 `commands/config.ts`
+ * (首跑向导,刻意不 import config/index.ts)与 `repl/index.ts`(`/theme` 持久化)都能安全共享。
+ * 主题等 UI 偏好走 `updateConfigKey` 单键写;向导多键一次性写走 `writeConfigKeys`。
+ */
+/** ~/.mocode/config:全局配置(与 ~/.mocode/skills 同目录,任意终端 / 任意目录生效)。 */
+export declare const CONFIG_PATH: string;
+/** 读已有配置(没有则空对象),用于回填默认值与保留其它键。 */
+export declare function readConfigFile(): Record<string, string>;
+/**
+ * 读-合并-写:把 entries 覆盖进 ~/.mocode/config,保留文件里其它键。
+ * mkdirSync 兜底(首跑无 ~/.mocode)。不吞 I/O 异常——向导路径让其抛(与历史行为一致);
+ * UI 偏好路径用 `updateConfigKey`(自带 try/catch 静默)。
+ */
+export declare function writeConfigKeys(entries: Record<string, string>): void;
+/**
+ * 单键持久化(主题等 UI 偏好):写失败静默——下次启动读不到则回退默认,不阻断 REPL。
+ * 注意:shell env 设了同名键时,`config/index.ts` 的 loadEnvFiles 只 backfill undefined 的
+ * process.env,故文件写对**下次启动**可能被 shell 盖——调用方据此给 dim 警告。
+ */
+export declare function updateConfigKey(key: string, value: string): void;

package/dist/config/index.d.ts

@@ -0,0 +1,114 @@
+export interface Config {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    maxTokens?: number;
+    systemPrompt: string;
+    /** 模型上下文窗口(token)。须对齐真实模型窗口(GLM-4.6≈128k,DeepSeek-V3≈64k,Qwen 视版本)。 */
+    contextWindowTokens: number;
+    /** 自动压缩触发阈值(占窗口比例)。默认 0.85,保守偏早以吸收估算误差与下一步增长。 */
+    compactThreshold: number;
+    /** 流式请求里带 stream_options.include_usage 拿真实 usage。后端不认 stream_options 时关掉。 */
+    includeUsage: boolean;
+    /** 自动压缩总开关。关掉则只靠手动 /compact。 */
+    autoCompact: boolean;
+    /** Context Optimization Pipeline 总开关(工具结果进 LLM 前的类型化编码:tree/search/log/…)。
+     *  关掉则工具结果原样进 LLM(仅长度裁剪),零行为变化。默认 true。 */
+    contextOptimize: boolean;
+    /** 相关性裁剪总开关(read_file 跨条裁剪:同 path 旧 read + 已被 mutation 覆写的旧 read
+     *  自动替换为存根)。纯静态、不调 LLM;关掉则保留所有 read 结果(只受 capToolResultForHistory
+     *  单条上限与 microcompact 旧区截短影响)。默认 true;
+     *  设 MOCODE_CONTEXT_RELPRUNE=false 全局回退。 */
+    contextRelprune: boolean;
+    /** 观察者生命周期总开关(LIVE→REFERENCED→OBSOLETE→STUB 四态机;grep/glob/codegraph
+     *  producer ↔ read/edit/write consumer 引用追踪;孤立+老化非观察类工具自动 STUB;
+     *  观察类工具永远只到 REFERENCED,不自动 STUB)。与 contextRelprune 并列,纯静态、不调 LLM。
+     *  默认 true;设 MOCODE_LIFECYCLE=false 全局回退。 */
+    contextLifecycle: boolean;
+    /** Context Budget Scheduler 总开关(五区分账 + ROI 排序调度)。
+     *  关掉则 agent 步前退化为 maybeCompact(history) 老路径(只看总占用 0.85 阈值),
+     *  零行为变化。默认 true;设 MOCODE_BUDGET_SCHEDULER=false 全局回退。 */
+    contextBudget: boolean;
+    /** 后台反思 pass 总开关。关掉则只靠手动 /reflect + 机会主义 memory_update。 */
+    autoReflect: boolean;
+    /**
+     * 记忆子系统总开关。关闭时:5 个 memory_* 工具不进工具表,buildSystemPrompt
+     * 里的 Memory Index 段 + memory_* 工具使用说明整段不出现,plan 模式提示词里的
+     * 工具名也跟着消失。运行时 /memory_switch 改;持久化 MEMORY_ENABLED。
+     * 默认 false:新用户零侵入,想用记忆功能显式打开。
+     */
+    memoryEnabled: boolean;
+    /** 每 N 个轮次触发一次后台反思 pass(与 agent 并发,不阻塞)。默认 5。 */
+    reflectEveryN: number;
+    /** 每轮 agent 循环最大步数(防无限循环)。默认 25。 */
+    maxSteps: number;
+    /** 子 agent(task 工具派生)默认步数上限。防子任务失控耗尽配额。默认 50。 */
+    subAgentMaxSteps: number;
+    /** 会话落盘目录(cwd 下)。 */
+    sessionDir: string;
+    /** AnySearch 联网搜索 API key(可选)。不配则走匿名免费额度(按 IP 限流)。 */
+    searchApiKey?: string;
+    /** 沙箱根目录(文件操作边界,可选)。未配则 startRepl 用 process.cwd() 兜底。优先级:--sandbox-root > 本项 > cwd。 */
+    sandboxRoot?: string;
+    /** AnySearch API base,默认官方端点。 */
+    searchBaseUrl: string;
+    /** 单张图片内联字节上限(base64 前的原始字节);超此大小拒绝并提示 TODO 走 URL 上传。默认 4MB。 */
+    maxImageBytes?: number;
+    /** 主题名(对应 src/ui/theme.ts 的 THEMES 表键)。默认 default;shell env MOCODE_THEME 覆盖文件。 */
+    theme: string;
+    /** MOCODE_THEME 是否由 shell 环境变量设置(非文件回填)。若是,/theme 写文件下次启动仍被 shell 盖。 */
+    themeFromShell: boolean;
+    /** 由 shell 环境变量设置的 LLM 键名列表(非文件回填)。若含某键,/model 写该键下次启动仍被 shell 盖。 */
+    llmKeysFromShell: string[];
+}
+/**
+ * 模型是否已配置(baseURL + apiKey 非空)。REPL 开场据此决定是否提示 /model。
+ * 未配置时 config.model 仍回退 'gpt-4o-mini',但发消息会因 baseURL/apiKey 空而失败——由 runTurn catch 友好提示。
+ */
+export declare function isModelConfigured(): boolean;
+/** 兼容旧名字:repl 的 buildSystemMessage 仍引 PLAN_MODE_SUFFIX(变量)。运行时按需现拼。 */
+export declare function buildBasePrompt(): string;
+/**
+ * plan 模式追加到系统提示末尾的指令。
+ * 历史曾是 `export const PLAN_MODE_SUFFIX`(顶层字面量);现改为按 isMemoryEnabled()
+ * 动态拼:false 时不出现 memory_* 工具名,避免 LLM 想调不存在的工具。
+ *
+ * 注意:已改为 getter(每次访问现拼),让运行时切 /memory_switch 后立即生效。
+ * 旧 import `PLAN_MODE_SUFFIX` 路径不变;repl 推荐改用 getPlanModeSuffix()(语义更清晰)。
+ * 不能直接 `export const PLAN_MODE_SUFFIX = buildPlanModeSuffix()`:
+ * 该表达式在模块初始化时立即求值,而 buildPlanModeSuffix 内部读 config,config 还未求值 → TDZ。
+ */
+export declare function getPlanModeSuffix(): string;
+export declare const config: Config;
+/**
+ * 运行时更新模型相关配置(/model 命令调)。
+ * - 更新 config 对象字段(即时生效:chat() 读 config.model,reconfigureClient 读 config.baseURL/apiKey)。
+ * - 同步 process.env(保持内存一致:其他读 process.env 的路径也拿到新值;且使新值在下次启动的
+ *   loadEnvFiles 中被视为"已设",不被文件回填覆盖——即"优先拿这里的")。
+ * 持久化(写 ~/.mocode/config)由调用方走 writeConfigKeys,此处只管内存 + env。
+ * 重建 OpenAI 客户端(baseURL/apiKey 是构造时固化的实例字段)由调用方走 reconfigureClient。
+ */
+export declare function updateModelConfig(opts: {
+    model?: string;
+    baseURL?: string;
+    apiKey?: string;
+    contextWindowTokens?: number;
+}): void;
+/**
+ * 记忆子系统总开关:单一来源。/memory_switch、/memory_status、buildSystemPrompt、
+ * tools/builtins/index.ts、tools/constants.ts 的 plan-mode 列表都从这里查。
+ * 默认 false(新用户零侵入)。
+ */
+export declare function isMemoryEnabled(): boolean;
+/**
+ * 切换记忆子系统开关(/memory_switch on|off 调)。
+ * - 更新 config 单例字段(其它模块下次调 isMemoryEnabled() 即拿新值)。
+ * - 同步 process.env.MEMORY_ENABLED(下次启动 loadEnvFiles 不被文件回填)。
+ * 持久化(写 ~/.mocode/config 的 MEMORY_ENABLED 键)由调用方走 writeConfigKeys。
+ *
+ * 注:开关切换对当前会话的 tool list / 已拼好的 systemPrompt 不会自动重算 —
+ * 工具表在 REPL 启动时构建,systemPrompt 在每轮 chat() 拼时按 isMemoryEnabled()
+ * 现查现拼(关掉时该轮拼出来的 prompt 即不带 memory_* 段)。所以切换在「下一轮
+ * agent 调用」起即时生效,本轮已发出的请求不会回滚。
+ */
+export declare function updateMemoryConfig(enabled: boolean): void;

package/dist/config/index.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import dotenv from 'dotenv';
+import { loadSnapshot } from '../project-snapshot/index.js';
+import { buildProjectSkillSection } from '../project-skill/index.js';
 /**
  * 按优先级加载配置文件并回填 process.env:
  *   候选(后者覆盖前者,优先级升序):<cwd>/.env(兼容旧用法,最低)→ ~/.mocode/config(全局)→ <cwd>/.mocode/config(项目级覆盖,最高)。
@@ -77,6 +79,31 @@ const PLATFORM_NOTE = (() => {
  * 默认关(新用户零侵入):这段 + 工具表里的 5 个 memory_* + 系统提示尾部的 Memory Index
  * 都不出现;打开 /memory_switch 后下一次新建 system message 才注入。
  */
+/**
+ * 项目快照段落：开 isProjectSnapshotEnabled() 且有快照时才拼。
+ * 告诉 LLM 项目已有哪些静态文件可 cache hit，减少无谓 read_file。
+ */
+function buildSnapshotSection() {
+    if (!config.projectSnapshotEnabled)
+        return '';
+    try {
+        const snap = loadSnapshot();
+        if (!snap)
+            return '';
+        const fileList = Object.keys(snap.files).join(', ');
+        const modules = snap.structure.modules.length ? snap.structure.modules.join(', ') : '(none)';
+        return `\n## Project Snapshot (cross-session cache)\n- A project snapshot is available with cached static files: [${fileList}]. read_file for these files will hit the snapshot cache (mtime-verified) — no disk read needed.\n- Project structure — top-level modules: [${modules}].\n- You already know the project skeleton; don't read_file these cached files just to "get an overview".\n- Use cached content directly: when a question can be answered from the cached files above (e.g. dependencies → package.json, compiler options → tsconfig.json, env vars → .env.example, project intro → README.md), answer from the snapshot without calling read_file.\n- The module list above is a navigation aid: when locating files, prefer targeted \`glob\` into the relevant module (e.g. \`src/**/*.ts\`) over broad top-level scans.\n`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * 项目快照总开关查询器（read-file 工具用）。
+ */
+export function isProjectSnapshotEnabled() {
+    return config.projectSnapshotEnabled;
+}
 const SYSTEM_PROMPT_MEMORY_SECTION = `
 ## Memory (cross-session long-term facts)
 - A "memory index" (id/title/summary only) is injected into the system prompt. Retrieve full body via memory_search (pass id or keyword); use memory_list to see the entire index.
@@ -193,7 +220,7 @@ ${PLATFORM_NOTE}
 - Confirm with the user before irreversible or outward-facing operations (delete, overwrite existing files, push, request external services), unless explicitly authorized.
 - Operate only within authorized scope; when unsure, ask — don't guess.
 
-${memorySection}
+${buildSnapshotSection()}${config.projectSkillEnabled ? buildProjectSkillSection() : ''}${memorySection}
 
 ## Working notepad (todolist) — for multi-step tasks
 - For tasks spanning **≥2 independent modules** OR when the user asks for stepwise progress ("先计划再执行" / "plan then do" / "按步骤来"), call \`todolist create\` first; update as you go. Skip for single-file edits or quick lookups.
@@ -250,6 +277,9 @@ export const config = {
     theme: process.env.MOCODE_THEME || 'default',
     themeFromShell,
     llmKeysFromShell,
+    projectSnapshotEnabled: process.env.MOCODE_PROJECT_SNAPSHOT !== 'false',
+    permissionEnabled: process.env.MOCODE_PERMISSION !== 'false',
+    projectSkillEnabled: process.env.MOCODE_PROJECT_SKILL === 'true',
 };
 /**
  * 运行时更新模型相关配置(/model 命令调)。
@@ -300,3 +330,20 @@ export function updateMemoryConfig(enabled) {
     config.memoryEnabled = enabled;
     process.env.MEMORY_ENABLED = enabled ? 'true' : 'false';
 }
+/**
+ * 项目专属 Skill 总开关:单一来源。/project_skill、buildBasePrompt、
+ * tools/builtins/index.ts 都从这里查。默认 false(零侵入)。
+ */
+export function isProjectSkillEnabled() {
+    return config.projectSkillEnabled;
+}
+/**
+ * 切换项目专属 Skill 开关(/project_skill on|off 调)。
+ * - 更新 config 单例字段(其它模块下次调 isProjectSkillEnabled() 即拿新值)。
+ * - 同步 process.env.MOCODE_PROJECT_SKILL(下次启动 loadEnvFiles 不被文件回填)。
+ * 持久化(写 ~/.mocode/config 的 MOCODE_PROJECT_SKILL 键)由调用方走 writeConfigKeys。
+ */
+export function updateProjectSkillConfig(enabled) {
+    config.projectSkillEnabled = enabled;
+    process.env.MOCODE_PROJECT_SKILL = enabled ? 'true' : 'false';
+}

package/dist/config/presets.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 多模型预设(`/model save <name>` 保存的命名配置)的纯 I/O 叶子。
+ *
+ * 存储:每个预设一个独立 JSON 文件 `~/.mocode/models/<name>.json`。
+ *   - 选用 per-file 而非单一 index.json:写不需要读-合并-写整本,天然原子(单文件 rename),
+ *     符合 memory/store.ts 的惯例;并发写多个预设互不打架。
+ *   - 路径前缀与 CONFIG_PATH 共享 `~/.mocode/`,保证权限/位置一致。
+ *
+ * 不读 process.env、不触发 config 单例初始化——repl(/model 子命令)与 commands/config.ts
+ * 之外的脚本都能安全 import。错误一律抛(写失败属异常路径,调用方决定怎么提示用户)。
+ *
+ * 命名约束:[a-zA-Z0-9_-]{1,32}。理由:
+ *   - 排除路径分隔符与 .. 防止越权写文件。
+ *   - 与 dotenv key 风格一致,便于未来扩展到同名 env override。
+ *   - 32 位上限防极长名撑爆文件名系统。
+ */
+/** 预设目录:`~/.mocode/models/`(按需创建)。 */
+export declare const MODELS_DIR: string;
+/** 单个预设的内容:与 updateModelConfig 的可选字段对齐。 */
+export interface ModelPreset {
+    name: string;
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    contextWindow: number;
+}
+/** 名字是否合法(调用方复用,避免在多处重复同一正则)。 */
+export declare function isValidPresetName(name: string): boolean;
+/** 读单个预设;不存在抛错。 */
+export declare function getPreset(name: string): ModelPreset;
+/** 读单个预设;不存在返回 null(供列表/可选切换场景)。 */
+export declare function readPreset(name: string): ModelPreset | null;
+/** 写/覆盖一个预设(原子:写 tmp 再 rename)。 */
+export declare function savePreset(preset: ModelPreset): void;
+/** 删除一个预设;不存在返回 false,成功返回 true。 */
+export declare function deletePreset(name: string): boolean;
+/**
+ * 重命名一个预设(原子:link+unlink,跨设备时退化为 copy+unlink)。
+ * 用于 /model rename <old> <new>;不存在的旧名 / 已存在的新名返回 false,具体由调用方决定提示文案。
+ */
+export declare function renamePreset(oldName: string, newName: string): boolean;
+/** 列出全部预设(按 name 升序);目录不存在返回空数组。 */
+export declare function listPresets(): ModelPreset[];
+/**
+ * 把当前 config 的 LLM 四键(baseURL/apiKey/model/contextWindow)迁为命名预设。
+ * 用于启动时一次性兜底老用户:加 /model 之前就已经在 ~/.mocode/config 写过的配置,
+ * /model list 应该立刻能看到,而不是空。已有同名预设则不重复写。
+ *
+ * 返回新建的预设名;若未配置完整(baseURL/apiKey 缺失)或已有同名则返回 null。
+ * 设计为幂等:重启调用一次也只会生效一次。
+ */
+export declare function migrateCurrentToPreset(input: {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    contextWindow: number;
+}): string | null;