mocode-ai 0.4.7 → 0.4.9

package/dist/repl/index.js

@@ -1,7 +1,7 @@
 import readline from 'node:readline/promises';
 import { emitKeypressEvents } from 'node:readline';
 import { stdin, stdout } from 'node:process';
-import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, buildBasePrompt, getPlanModeSuffix, } from '../config/index.js';
+import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, isProjectSkillEnabled, updateProjectSkillConfig, buildBasePrompt, getPlanModeSuffix, } from '../config/index.js';
 import { updateConfigKey, writeConfigKeys, CONFIG_PATH } from '../config/file.js';
 import { deletePreset, getPreset, isValidPresetName, listPresets, migrateCurrentToPreset, savePreset, } from '../config/presets.js';
 import { runAgent } from '../agent/index.js';
@@ -24,6 +24,7 @@ import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots
 import { listSkills, effectiveSystemPrompt, } from '../skills/index.js';
 import { buildMemorySection, buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
 import { buildActivePlanSection, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from '../plan/index.js';
+import { buildSnapshot as buildProjectSnapshot } from '../project-snapshot/index.js';
 /**
  * readline 的 prompt 必须是纯文本(无 ANSI):readline 按字符数算光标位置,
  * 颜色码会让光标错位、编辑时漂移。颜色只用在直接 stdout.write 的横幅 / 工具行 / 回复。
@@ -41,6 +42,7 @@ const SLASH_COMMANDS = [
     { name: '/rollback', desc: '菜单选轮次回滚(↑↓·Enter)' },
     { name: '/memory', desc: '记忆库:条目计数与近期索引(关闭时提示先开 /memory_switch)' },
     { name: '/memory_switch', desc: '切换记忆子系统开关(无参=切换;/on 或 /off 显式;持久化 MEMORY_ENABLED)' },
+    { name: '/project_skill', desc: '项目专属 Skill 开关 + 查看/初始化(无参=切换;/on·/off·/view·/init)' },
     { name: '/memory_status', desc: '查看记忆子系统当前开关与原理' },
     { name: '/reflect', desc: '手动触发后台记忆反思 pass(需先开启记忆)' },
     { name: '/init', desc: '扫描项目生成 MOCODE.md 项目记忆(需先开启记忆)' },
@@ -49,6 +51,7 @@ const SLASH_COMMANDS = [
     { name: '/model switch', desc: '↑↓·Enter 在已配置预设间切换' },
     { name: '/model list', desc: '列出已经配置的模型' },
     { name: '/model delete <name>', desc: '删除已配置的模型' },
+    { name: '/refresh_snapshot', desc: '刷新项目快照(重新扫描静态文件,更新缓存)' },
     { name: '/plan', desc: '切到 plan 模式(只读探查+产出计划)' },
     { name: '/auto', desc: '切回 auto 模式(全工具执行)' },
     { name: '/pet', desc: '开关桌宠(独立悬浮窗,展示 agent 状态动画)' },
@@ -175,6 +178,8 @@ function runningStateFor(cmd) {
             return { status: '回滚', placeholder: '选择轮次…' };
         case '/init':
             return { status: '初始化', placeholder: '生成 MOCODE.md…' };
+        case '/refresh_snapshot':
+            return { status: '刷新快照', placeholder: '扫描项目文件中…' };
         case '/plan':
             return { status: '切 plan', placeholder: '…' };
         case '/auto':
@@ -191,6 +196,8 @@ function runningStateFor(cmd) {
             return { status: '切记忆开关', placeholder: '切换中…' };
         case '/memory_status':
             return { status: '查记忆状态', placeholder: '…' };
+        case '/project_skill':
+            return { status: '项目 Skill', placeholder: '处理中…' };
         default:
             // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由内联 spinner 承载(思考中/执行…),
             // 状态行只显走时——故常态 status 留空,不塞「处理」这种与内联重复的泛标签。
@@ -538,6 +545,14 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
     // 沙箱根:文件操作边界。优先级 --sandbox-root > SANDBOX_ROOT env > process.cwd()。
     // 纯边界记录(不 chdir),jail.ts 内部 resolve。子 agent 同进程继承全局 root。
     setSandboxRoot(sandboxRootOverride ?? config.sandboxRoot ?? process.cwd());
+    // 项目快照：sandboxRoot 设定后立即构建/加载（同步，小文件几十 ms）。
+    // 构建失败不阻断 REPL：snapshot 内部 catch 所有异常，此处再兜一层。
+    if (config.projectSnapshotEnabled) {
+        try {
+            buildProjectSnapshot();
+        }
+        catch { /* ignore */ }
+    }
     // 构造系统提示:auto 用 base;plan 在 base 后追加按当前开关现拼的 plan suffix。
     // 切模式时 applyMode 重算 history[0](history[0] 恒 system,compaction 保它,不破坏)。
     // 活跃 plan 摘要拼在 memory 段后(systemPrompt 的尾段),todo 工具变更后 listener 重写 history[0]。
@@ -1135,6 +1150,31 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
+        if (line === '/refresh_snapshot') {
+            if (!config.projectSnapshotEnabled) {
+                layout.contentWrite(`${ui.dim}(项目快照功能已关闭,MOCODE_PROJECT_SNAPSHOT=false)${ui.reset}\n`);
+                continue;
+            }
+            // buildProjectSnapshot 是同步操作(扫顶层小文件,几十 ms),不需要 spinner
+            try {
+                const snap = buildProjectSnapshot();
+                const fileCount = Object.keys(snap.files).length;
+                const moduleCount = snap.structure.modules.length;
+                const configCount = snap.structure.configFiles.length;
+                layout.contentWrite(`${ui.cyan}✓ 项目快照已刷新${ui.reset}: ${fileCount} 个静态文件 · ${moduleCount} 个模块 · ${configCount} 个配置文件\n`);
+                layout.contentWrite(`${ui.dim}文件: ${Object.keys(snap.files).join(', ')}${ui.reset}\n`);
+                layout.contentWrite(`${ui.dim}模块: ${snap.structure.modules.join(', ')}${ui.reset}\n`);
+                // 刷新 history[0]：buildSnapshotSection 内部 loadSnapshot() 会拿到新快照，
+                // buildSystemMessage 重新拼 system prompt，快照段落就更新了。
+                history[0] = { role: 'system', content: buildSystemMessage(getAgentMode() === 'plan') };
+                layout.contentWrite(`${ui.dim}(system prompt 已同步刷新)${ui.reset}\n`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                layout.contentWrite(`${ui.red}[错误]${ui.reset} 刷新快照失败: ${msg}\n`);
+            }
+            continue;
+        }
         if (line === '/sessions') {
             // /sessions:浏览全部已保存会话(慢路径,readdir+全量 JSON.parse,目录 N 大时会有可感知卡顿)。
             // 默认走 /resume(仅最近 10 条,瞬开);要翻历史续接更早的会话才用这条。
@@ -1665,6 +1705,124 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
             }
             continue;
         }
+        if (line === '/project_skill' ||
+            line.startsWith('/project_skill ')) {
+            // /project_skill — 项目专属 Skill 总开关 + 查看/编辑。
+            // 用法:
+            //   /project_skill              切换 on/off
+            //   /project_skill on|off       显式开关
+            //   /project_skill view         查看当前内容
+            //   /project_skill edit         打开编辑器修改
+            try {
+                const arg = line.startsWith('/project_skill ')
+                    ? line.slice('/project_skill '.length).trim().toLowerCase()
+                    : '';
+                // /project_skill view — 查看当前内容
+                if (arg === 'view') {
+                    const enabled = isProjectSkillEnabled();
+                    layout.contentWrite(`${ui.cyan}项目专属 Skill:${ui.reset} ${enabled ? `${ui.green}开启` : `${ui.yellow}关闭`}${ui.reset}\n`);
+                    if (enabled) {
+                        const { readProjectSkill } = await import('../project-skill/index.js');
+                        const content = readProjectSkill();
+                        if (content) {
+                            layout.contentWrite(`${ui.dim}--- 内容 ---${ui.reset}\n${content}\n${ui.dim}--- 结束 ---${ui.reset}\n`);
+                        }
+                        else {
+                            layout.contentWrite(`${ui.dim}(尚未创建,可用 /project_skill init 生成初始内容)${ui.reset}\n`);
+                        }
+                    }
+                    else {
+                        layout.contentWrite(`${ui.dim}(功能已关闭,用 /project_skill on 开启)${ui.reset}\n`);
+                    }
+                    continue;
+                }
+                // /project_skill init — 扫描项目并生成/优化 skill
+                if (arg === 'init') {
+                    if (!isProjectSkillEnabled()) {
+                        layout.contentWrite(`${ui.yellow}⚠ 项目专属 Skill 尚未开启${ui.reset}，请先运行 ${ui.cyan}/project_skill on${ui.reset}\n`);
+                        continue;
+                    }
+                    const { readProjectSkill, writeProjectSkill } = await import('../project-skill/index.js');
+                    const existing = readProjectSkill();
+                    if (existing) {
+                        layout.contentWrite(`${ui.cyan}⏳ 正在深度探索项目并优化现有 skill...${ui.reset}\n`);
+                    }
+                    else {
+                        layout.contentWrite(`${ui.cyan}⏳ 正在深度探索项目（子 agent 将使用工具扫描代码、架构、配置等）...${ui.reset}\n`);
+                    }
+                    layout.contentWrite(`${ui.dim}提示: 按 Ctrl+C 可中断${ui.reset}\n\n`);
+                    // 派生子 agent 深度探索项目
+                    const { generateInitialSkill } = await import('../project-skill/initializer.js');
+                    const result = await generateInitialSkill(existing ?? undefined, currentAbort?.signal);
+                    // 显示探索过程日志
+                    if (result.transcript) {
+                        layout.contentWrite(`${ui.dim}--- 探索过程 ---${ui.reset}\n`);
+                        layout.contentWrite(result.transcript);
+                        layout.contentWrite(`${ui.dim}--- 探索结束 ---${ui.reset}\n\n`);
+                    }
+                    if (result.ok && result.content) {
+                        const writeResult = writeProjectSkill(result.content);
+                        if (writeResult.ok) {
+                            layout.contentWrite(`${ui.green}✓ 项目 Skill 已生成${ui.reset}\n`);
+                            layout.contentWrite(`${ui.dim}内容预览:${ui.reset}\n${result.content.slice(0, 500)}${result.content.length > 500 ? '...' : ''}\n`);
+                            layout.contentWrite(`\n${ui.dim}文件: ${ui.cyan}.mocode/project-skill.md${ui.reset} (${result.content.length} 字符)\n`);
+                            layout.contentWrite(`${ui.dim}下次启动时会自动注入到系统提示词。Agent 也会在开发过程中持续更新。${ui.reset}\n`);
+                            layout.contentWrite(`${ui.dim}提示: 可用 ${ui.cyan}/project_skill view${ui.reset} 查看完整内容，或手动编辑文件完善。${ui.dim}${ui.reset}\n`);
+                        }
+                        else {
+                            layout.contentWrite(`${ui.red}✗ 写入失败:${ui.reset} ${writeResult.error}\n`);
+                        }
+                    }
+                    else {
+                        layout.contentWrite(`${ui.red}✗ 探索失败:${ui.reset} ${result.error}\n`);
+                        if (result.transcript) {
+                            layout.contentWrite(`${ui.dim}子 agent 输出了部分内容（见上方），但未能生成完整的 skill 文档。${ui.reset}\n`);
+                        }
+                    }
+                    continue;
+                }
+                // 开关切换
+                let nextEnabled;
+                if (arg === '') {
+                    nextEnabled = !isProjectSkillEnabled();
+                }
+                else if (['on', 'true', '1', 'yes', 'y', 'enable', 'enabled'].includes(arg)) {
+                    nextEnabled = true;
+                }
+                else if (['off', 'false', '0', 'no', 'n', 'disable', 'disabled'].includes(arg)) {
+                    nextEnabled = false;
+                }
+                else {
+                    layout.contentWrite(`${ui.yellow}/project_skill 用法:${ui.reset}\n` +
+                        `  /project_skill             切换(开↔关)\n` +
+                        `  /project_skill on|off      显式设值\n` +
+                        `  /project_skill view        查看当前内容\n` +
+                        `  /project_skill init        扫描项目生成/优化 skill（可重复运行）\n`);
+                    continue;
+                }
+                const prev = isProjectSkillEnabled();
+                if (nextEnabled === prev) {
+                    layout.contentWrite(`${ui.dim}(已是 ${nextEnabled ? '开启' : '关闭'},未变更 — 持久化字段未写入)${ui.reset}\n`);
+                    continue;
+                }
+                updateProjectSkillConfig(nextEnabled);
+                updateConfigKey('MOCODE_PROJECT_SKILL', nextEnabled ? 'true' : 'false');
+                const note = nextEnabled
+                    ? `${ui.green}已开启项目专属 Skill${ui.reset} — project_skill_update 工具进入工具表;` +
+                        `项目 Skill 内容会在下次拼 system message 时注入。工具表快照需重启 REPL 才完整刷新。`
+                    : `${ui.yellow}已关闭项目专属 Skill${ui.reset} — project_skill_update 工具将在下次拼 system message 时从工具表过滤;` +
+                        `项目 Skill 内容不再注入。重启 REPL 后工具表完全不出现。`;
+                layout.contentWrite(`${note}\n`);
+                layout.contentWrite(`${ui.dim}(写入 ${CONFIG_PATH}:MOCODE_PROJECT_SKILL=${nextEnabled ? 'true' : 'false'};${ui.reset}` +
+                    (process.env.MOCODE_PROJECT_SKILL
+                        ? `${ui.dim}同 session shell 未 export,文件写入即时生效)${ui.reset}\n`
+                        : `${ui.dim}下次启动仍生效)${ui.reset}\n`));
+            }
+            catch (e) {
+                layout.contentWrite(`${ui.red}/project_skill 失败:${ui.reset} ${e.message}\n`);
+            }
+            continue;
+        }
         const bubbleRows = input.length + 2 + pendingAttachments.length; // N 行 message + 2 行尾随空(含 \n\n 留下的 open current 行) + 每附件 1 行
         const shouldCommit = await awaitPendingRecall(input, pendingAttachments.length, placeholder);
         if (!shouldCommit) {

package/dist/rollback/index.d.ts

@@ -0,0 +1,79 @@
+import type { ChatMessage } from '../llm/index.js';
+/**
+ * 回滚子系统:`/rollback` 菜单(↑/↓)选轮次 → 选中第 X 轮 = 删该轮及之后 + 预填该轮 user 输入(仿 Claude Code
+ * rewind,Enter 重新跑);撤销被删轮次的文件改动(逐个「保留/撤销」询问)。
+ *
+ * 语义:选中下标 picked(0-based,= 第 picked+1 轮)→ `planRollback(picked)` 保 1..picked(删 picked+1 轮及之后),
+ * 预填 userTexts[picked](= 第 picked+1 轮 user 输入)。**不是**保 1..picked+1——选中第 X 轮即"从第 X 轮重跑"。
+ *
+ * 撤销方案 = 落盘快照(不用 git):write_file/edit_file 执行前由 executeTool 调
+ * recordMutation,把 before 内容存入快照(按轮次 turnId 打标)。回滚到第 n 轮时,
+ * 对每条选「撤销」的路径,恢复 turnId > cutoffTurnId 的最小 turnId 快照的 before
+ * (= 所选轮末状态;before===null = 当时不存在 → 删文件)。同文件多轮改动也能
+ * 精确回到所选轮边界,不误伤更早轮次。
+ *
+ * 快照 + 轮次日志随 saveSession 落盘到 <sessionDir>/<id>.snapshots.json,/resume 读回
+ * → 重启后仍可撤销。叶子模块:运行时只依赖 config(+ node:fs/path);ChatMessage
+ * 用 import type 擦除,不拉 llm 运行时;不反向依赖任何业务。
+ *
+ * v1 偏离 / 局限:
+ * - 撤销粒度 = 路径(非逐条 tool_call)——快照只能整路径回到轮末,无法只撤一条 edit。
+ * - run_command 不撤销(shell 可任意改文件,无法跟踪)。
+ * - 跨 /resume 后若文件被外部改过,恢复会用 before 覆盖(边缘情况,不处理)。
+ * - 快照文件随大文件多次改动膨胀;/clear 重置;日后可按「turn 已不可回滚」裁剪。
+ */
+export interface Turn {
+    turnId: number;
+    firstLine: string;
+}
+export interface Snapshot {
+    turnId: number;
+    path: string;
+    before: string | null;
+}
+export interface FileChange {
+    path: string;
+    ops: string[];
+    snapshotAvailable: boolean;
+}
+export interface RollbackPlan {
+    n: number;
+    cutoffIndex: number;
+    cutoffTurnId: number;
+    changes: FileChange[];
+}
+/** agent:runAgent 入口调——开新轮次。firstLine 已由调用方截断到 40。 */
+export declare function beginTurn(firstLine: string): void;
+/** tools/registry:write_file/edit_file 执行前调——记 before 快照(在 tool.execute 之前读)。 */
+export declare function recordMutation(p: string): void;
+/** 列出当前可回滚的轮次(1-based 序号由调用方显示)。 */
+export declare function listTurns(): Turn[];
+/**
+ * 规划回滚到第 n 轮(1-based):算截断点 + 被删轮次里涉及的文件改动(按 path 去重)。
+ * 调用方据 changes 逐 path 问保留 / 撤销;snapshotAvailable=false 的项无法撤销。
+ */
+export declare function planRollback(n: number, history: ChatMessage[]): RollbackPlan;
+/**
+ * 执行回滚:原地截断 history 到 cutoffIndex + 按选择恢复文件 + 裁剪 turns/snapshots。
+ * revertPaths 为选「撤销」的相对路径集合。返回删除消息数 + 撤销文件列表。
+ */
+export declare function applyRollback(plan: RollbackPlan, history: ChatMessage[], revertPaths: Set<string>): {
+    deletedMsgs: number;
+    revertedFiles: string[];
+};
+/** compact 摘要成功后调:按存活轮次数裁剪(M = 新 history 里 user 消息数)。 */
+export declare function pruneAfterCompaction(history: ChatMessage[]): void;
+/** /clear 调:清空全部状态。 */
+export declare function resetState(): void;
+/**
+ * 无 snapshots 文件时(/resume 旧会话)从 history 重建 turns(扫 user 消息,1..M,
+ * 无快照 → 那些轮次的文件改动不可撤销)。turnIdCounter = M,后续新轮次从 M+1 续。
+ */
+export declare function rebuildFromHistory(history: ChatMessage[]): void;
+/** 随 saveSession 调:把 turns + snapshots 落盘(turns 为空则跳过,不写空文件)。 */
+export declare function persistSnapshots(id: string): void;
+/**
+ * /resume / --resume 加载会话后调:读回 turns + snapshots。成功返 true(状态已覆盖);
+ * 失败 / 无文件返 false,调用方应改调 rebuildFromHistory(history) 兜底。
+ */
+export declare function loadSnapshots(id: string): boolean;

package/dist/sandbox/command.d.ts

@@ -0,0 +1,3 @@
+/** 返回 env 浅拷贝,删敏感键。 */
+export declare function filterEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function isCommandDenied(cmd: string): string | null;

package/dist/sandbox/index.d.ts

@@ -0,0 +1,4 @@
+export { getSandboxRoot, setSandboxRoot } from './root.js';
+export { jailResolve, jailGlobPattern, isInsideRoot } from './jail.js';
+export { filterEnv, isCommandDenied } from './command.js';
+export { SANDBOX_EXEMPT_TOOLS, SANDBOX_PATH_TOOLS, enforceSandbox, } from './policy.js';

package/dist/sandbox/jail.d.ts

@@ -0,0 +1,17 @@
+/**
+ * abs 是否在沙箱根内(含 == 根)。win32 下两边 toLowerCase 再比(node 的 path.relative 不做
+ * 大小写无关比较,盘符大小写差异会误判出圈)。**不做 realpath**——用于 glob/grep 结果后置过滤;
+ * 越界软链的拦挡靠 jailResolve 的 realpath。
+ */
+export declare function isInsideRoot(abs: string): boolean;
+/**
+ * 把输入路径解析为沙箱根内的绝对路径;越界(../、绝对外圈、符号链接出圈)抛错。
+ * 供 enforceSandbox 重写 args.path(读/写/改)、readDiffContext 预读旧内容用。
+ * 同步:realpathSync 仅做 fs 元数据查询(微秒级),与既有 readFileSync/existsSync 用法一致。
+ */
+export declare function jailResolve(input: string): string;
+/**
+ * glob pattern 校验:拒绝对路径(平台相关的 isAbsolute)与含 `..` 段的 pattern。
+ * 返 null = 通过;返 string = 拒绝原因。形如 *.ts 的正常 pattern 放行。
+ */
+export declare function jailGlobPattern(pattern: string): string | null;

package/dist/sandbox/policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 豁免 cwd 牢笼的工具:
+ *  - memory_*:操作 ~/.mocode 与 <cwd>/.mocode(CLAUDE.md 明确不进回滚、在外圈),本就该在外圈
+ *  - use_skill:读 ~/.claude/skills、~/.mocode/skills、<cwd>/.mocode/skills,部分在外圈
+ *  - web_*:跨网络,非文件路径
+ *  - ask_human / switch_mode:无文件路径
+ *  - codegraph:只读 cwd 下 .codegraph/ 索引(只读、不写盘)
+ *  - task:派生子 agent,继承全局 root(子 agent 同进程天然共享 getSandboxRoot)
+ */
+export declare const SANDBOX_EXEMPT_TOOLS: Set<string>;
+/**
+ * 路径类工具:enforceSandbox 集中把 args.path 重写为牢内绝对路径(默认安全;工具内
+ * resolve(absolutePath) 原样返回)。**新加带 path 参数的工具须列入此集**,否则不会被牢笼挡。
+ */
+export declare const SANDBOX_PATH_TOOLS: Set<string>;
+/**
+ * 工具执行前的沙箱校验。返 string = 拒绝(直接喂 LLM,不执行);返 null = 放行(可能已重写 args.path)。
+ * **不抛**——契约对齐「调度器永不抛错、永远返回字符串」(tools/registry.ts executeTool)。
+ * run_command 不在此处理(cwd / env / denylist 在其站点)。
+ */
+export declare function enforceSandbox(name: string, args: Record<string, unknown>): string | null;

package/dist/sandbox/root.d.ts

@@ -0,0 +1,5 @@
+/** 当前沙箱根(绝对路径)。未初始化返 null,调用方 ?? process.cwd() 兜底(防御)。 */
+export declare function getSandboxRoot(): string | null;
+/** 设置沙箱根。repl startRepl 启动时调一次(默认 process.cwd();--sandbox-root / SANDBOX_ROOT 可覆盖)。
+ *  返回之前的值,供未来 save/restore(子 agent worktree 隔离)用。 */
+export declare function setSandboxRoot(root: string | null): string | null;

package/dist/session/compact.d.ts

@@ -0,0 +1,92 @@
+import { type ChatMessage, type ChatUsage } from '../llm/index.js';
+/**
+ * 上下文压缩子系统(参考 Claude Code 的 auto-compact):
+ *  三层 —— ① push-time 单条上限(见 capToolResultForHistory,在 agent push 时调用)
+ *          ② 微压缩:旧工具结果原地截短(保 tool_call_id,无 LLM 调用)
+ *          ③ 摘要:旧的非工具消息由一次 chat() 压成一条 role:'system' 摘要(index 1)
+ *
+ *  不变量:
+ *  - 原地修改:用 history.length=0; push(...) 重建,repl 持有同一引用。
+ *  - tool_call_id 配对:按完整 group(assistant+其后连续 tool)切,永不劈开;
+ *    微压缩只改 .content 不删消息。
+ *  - history[0] 永远是当前 systemPrompt;摘要插 index 1。
+ */
+export interface CompactOptions {
+    window: number;
+    threshold: number;
+    /** 手动 /compact 的聚焦指令,会拼进摘要 prompt。 */
+    focus?: string;
+    /** 可注入的摘要器(测试用);缺省调 chat()。 */
+    summarize?: (older: ChatMessage[], focus?: string) => Promise<string | null>;
+    /** 手动触发(repl /compact)开关:强制走 microcompact/summarize,绕过 autoCompact 阈。
+     *  设为 true 后,即便无 ROI 触发(history 不超/totalOver=false)也压——对齐用户拍板的"真·强制"。
+     *  force:在 manual 基础上再绕过「oldGroups 空 → 直接 noop」的硬边界,允许降 keepBudget 强压。
+     *  默认 manual=false / force=false(自动路径行为完全不变)。 */
+    manual?: boolean;
+    force?: boolean;
+}
+export interface CompactResult {
+    compacted: boolean;
+    summarized: boolean;
+    estimateBefore: number;
+    estimateAfter: number;
+    reason: 'noop-empty' | 'noop-protected' | 'noop-ml-only' | 'noop-shrunk-too-large' | 'noop-noold-noop' | 'microcompact' | 'summarize';
+    /** 调试字段:保护区占比(0-1),供 /compact 显示"为什么没压"。force 时降 keepBudget 后可能更小。 */
+    protectedRatio?: number;
+    /** 调试字段:旧区可压组数,供 UI 显示。 */
+    oldGroupCount?: number;
+}
+/** 跨模块共享的上下文状态:agent 写 lastUsage,compact 写 lastEstimate,repl 的 /context 读。
+ *  scheduler.ts 写最近一次调度日志(可选,repl 可读不到时 no-op)。 */
+export declare const contextState: {
+    lastUsage?: ChatUsage;
+    lastEstimate: number;
+    schedulerLog?: import('./scheduler.js').SchedulerRunLog;
+};
+/** 中截:text 太长时保 head + 标记 + tail,总长 ≤ max。 */
+export declare function truncateMid(text: string, max: number): string;
+/**
+ * push-time 第一层:工具结果进 history 前裁到 MAX_HISTORY_RESULT。
+ * 显示层(summarizeToolResult)仍用原 output,不受影响。
+ */
+export declare function capToolResultForHistory(name: string, output: string): string;
+/**
+ * 把多模态 content 拍平成纯文本(供摘要 transcript 用):text parts 拼接;image_url parts
+ * 替换为 `[图片已剥离: <mime>]` stub,避免 base64 进摘要 prompt(LLM 看到也无意义,反而撑爆 token)。
+ * 其它情况(string / 其它形状)原样返回。
+ */
+export declare function stripImagesForSummary(m: ChatMessage): ChatMessage;
+/**
+ * 压缩 history(原地)。手动 /compact 与自动 maybeCompact 都走这里。
+ * 不检查阈值——调用方(maybeCompact)决定是否调;/compact 直接调以强制压缩。
+ */
+export declare function compactHistory(history: ChatMessage[], opts: CompactOptions): Promise<CompactResult>;
+/**
+ * 自动压缩门槛:agent 每步调 chat() 前调用。
+ * 用全量启发式估算(始终可用、安全侧、无 stale-usage 问题);超阈则压缩。
+ *
+ * 升级到 Budget Scheduler:可传 `report: BudgetReport`。传了就**按 ROI 调度**:
+ *   - 只有当 `report.layers.history.overBudget` 或 `report.totalOver` 时才压;
+ *   - 冷工具超(Cold Tool ROI 最低)→ 不压 history,留给调度器的 cold tools 路径处理。
+ * 这样 cold tools 路径(L1 中截 / L2 relevance / L3 age stub)能先动,history
+ * 摘要(最贵)只在 cold tools 解不开时才触发。
+ *
+ * 不传 report 时退化为原行为:仅看总占用是否超 `compactThreshold * window`——
+ * 兼容老调用方(子 agent / 测试直接调时),零行为变化。
+ *
+ * manual 选项(repl /compact 用):true 时旁路 autoCompact 开关与 ROI 阈,
+ * 强制走 compactHistory(manual/force 参数透传)。返 CompactResult 给 caller 文案展示。
+ * 默认 manual=false 自动路径完全不变。
+ */
+export declare function maybeCompact(history: ChatMessage[], report?: {
+    layers: {
+        history: {
+            overBudget: boolean;
+        };
+    };
+    totalOver: boolean;
+}, manualOpts?: {
+    manual?: boolean;
+    force?: boolean;
+    focus?: string;
+}): Promise<CompactResult | void>;

package/dist/session/drop.d.ts

@@ -0,0 +1,19 @@
+import type { ChatMessage } from '../llm/index.js';
+import { estimateTokens } from '../llm/index.js';
+import type { DropContextFilter, DropContextResult } from '../tools/types.js';
+/**
+ * 剔除历史里命中的旧 tool 结果(原地修改 history)。
+ *
+ * 筛选(各维度 AND 组合):
+ *  - toolNames:只剔除这些工具名的结果(空 = 不限)
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果(空 = 不限)
+ *
+ * 保护:history[0](system)+ 当前轮(最后一个 user 及其之后)永不剔除。
+ * 已是存根的 tool 消息(含「已剔除」标记)不重复剔除(幂等)。
+ *
+ * 永不抛错;无匹配返 dropped=0。
+ */
+export declare function dropContextFromHistory(history: ChatMessage[], filter: DropContextFilter): DropContextResult;
+/** 给 drop_context 工具结果格式化人类可读摘要(回灌给 agent)。 */
+export declare function formatDropResult(r: DropContextResult): string;
+export { estimateTokens };

package/dist/session/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * session/ 入口:上下文压缩 + 会话落盘。
+ *  - compact.ts:三层压缩(push-time 上限 / 微压缩 / 摘要)+ 自动门槛
+ *  - persist.ts:history 序列化到磁盘 + --resume / /resume
+ * 依赖方向:session → {llm(摘要复用 chat), config, ui};llm 不反向依赖 session。
+ */
+export { compactHistory, maybeCompact, capToolResultForHistory, truncateMid, contextState, } from './compact.js';
+export type { CompactOptions, CompactResult } from './compact.js';
+export { runScheduler, manualCompact, createBudgetScheduler, } from './scheduler.js';
+export type { BudgetScheduler, SchedulerRunLog } from './scheduler.js';
+export { dropContextFromHistory, formatDropResult, } from './drop.js';
+export { newSessionId, saveSession, loadSession, listSessions, sessionDir, } from './persist.js';
+export type { SessionMeta, SessionRecord } from './persist.js';

package/dist/session/persist.d.ts

@@ -0,0 +1,30 @@
+import type { ChatMessage } from '../llm/index.js';
+/**
+ * 会话落盘:把 history 序列化到 <cwd>/.mocode/sessions/<id>.json,支持 --resume / /resume。
+ * session = 「这次对话说了啥」;与 memory/(跨会话长期事实)区分。
+ * 同步 fs(小文件,匹配 config 的同步风格);任何读/解析失败都返 null,不抛。
+ */
+export interface SessionMeta {
+    id: string;
+    createdAt: string;
+    model: string;
+    firstUser: string;
+}
+export interface SessionRecord extends SessionMeta {
+    history: ChatMessage[];
+}
+/** 会话目录(确保存在)。 */
+export declare function sessionDir(): string;
+/** 新会话 id:YYYYMMDD-HHmmss(运行时 Date 可用)。 */
+export declare function newSessionId(): string;
+/** 保存会话到磁盘(history.length<=1 时跳过写盘,只返 meta)。 */
+export declare function saveSession(history: ChatMessage[], id: string): SessionMeta;
+/** 加载会话;不存在 / 损坏返 null(不抛)。 */
+export declare function loadSession(id: string): SessionRecord | null;
+/** 列出最近会话,按 createdAt 降序。损坏文件跳过。
+ *  - limit?: 仅返回前 N 条。会话文件名是 YYYYMMDD-HHmmss.json,字典序=时间序;
+ *    先按文件名降序取前 N,再只解析这 N 个文件(history 大字段全部跳过不读),避免
+ *    /resume 在 sessions 目录堆了几百个文件时 readdirSync + 全量 JSON.parse 慢。
+ *  - 不传 limit 时读全部(向后兼容,供裸 --resume 列全表用)。
+ */
+export declare function listSessions(limit?: number): SessionMeta[];

package/dist/session/scheduler.d.ts

@@ -0,0 +1,53 @@
+import { evaluateBudget, scheduleActions, formatReport, type BudgetReport, type ScheduleAction } from '../context/budget.js';
+import type { ChatMessage } from '../llm/index.js';
+/** 一次调度的执行日志(供 /context 命令显示与调试)。 */
+export interface SchedulerRunLog {
+    step: number;
+    report: BudgetReport;
+    actions: ScheduleAction[];
+    /** 实际触发的闸('compact_history' 调过 maybeCompact → true;其它已在 push-time 自动跑)。 */
+    compactHistoryCalled: boolean;
+    ts: number;
+}
+/** Scheduler 实例状态:压一份最近日志,方便 /context 看到上一次决策。 */
+export interface BudgetScheduler {
+    observePush: (history: ChatMessage[], idx: number) => void;
+    runStep: (history: ChatMessage[], step: number) => Promise<void>;
+    /** 暴露最近一次决策(供 /context)。 */
+    lastRunLog: SchedulerRunLog | null;
+}
+/** compact_history action 的执行明细(供 repl 文案展示"为什么没压")。 */
+export interface CompactHistoryDetail {
+    reason: 'microcompact' | 'summarize' | 'noop-empty' | 'noop-protected' | 'noop-ml-only' | 'noop-shrunk-too-large' | 'noop-noold-noop';
+    estimateBefore: number;
+    estimateAfter: number;
+    /** 保护区占比 0-1(系统 + 当前轮 / 总 history)。 */
+    protectedRatio?: number;
+    /** 旧区可压组数。 */
+    oldGroupCount?: number;
+    /** focus 透传。 */
+    focus?: string;
+}
+/** 创建 runAgentCore 闭包持有的 scheduler(每次 agent 启动一个新实例)。
+ *  observePush 当前只是占位:真正 L1/L2/L3 已由 cap / pruner / lifecycle 在 push 时跑;
+ *  保留接口为后续「调度器注入 hotBoundary 给 lifecycle」演进留接缝。 */
+export declare function createBudgetScheduler(): BudgetScheduler;
+/** 便捷:agent/core.ts 不需要每次 createBudgetScheduler,直接 runScheduler(history, step)。 */
+export declare function runScheduler(history: ChatMessage[], step: number): Promise<void>;
+/** 手动 /compact 入口(repl):与自动路径完全一致——五区 ROI 调度,但 history 摘要强制执行。
+ *  即便 layers.history.overBudget=false 或 totalOver=false,manual 仍产 compact_history action
+ *  把 focus 透传给 LLM 摘要 prompt。其它 ROI 决策(cold tools / cap hot / warn)按 scheduleActions 走。
+ *
+ *  关系:runScheduler 是「自动触发」,manualCompact 是「用户显式触发」,二者共享 scheduleActions。
+ *
+ *  force=true:即便 oldGroups 空(history 全在保护区)也强行把早期消息降级压一次。
+ *  适合"history 太长,自动阈值从未触发,但用户想强制压"的场景。
+ *
+ *  退化:config.contextBudget === false 时直接调 compactHistory(history, { focus }),与改造前等价。
+ *  返回 SchedulerRunLog + compactDetail 字段,供 repl 文案展示"为什么没压"。 */
+export declare function manualCompact(history: ChatMessage[], focus?: string, opts?: {
+    force?: boolean;
+}): Promise<SchedulerRunLog & {
+    compactDetail?: CompactHistoryDetail;
+}>;
+export { evaluateBudget, scheduleActions, formatReport };

package/dist/skills/discover.d.ts

@@ -0,0 +1,33 @@
+export interface Skill {
+    name: string;
+    description: string;
+    version?: string;
+    license?: string;
+    dir: string;
+    skillMdPath: string;
+}
+/**
+ * 解析 skill 目录列表。
+ * env SKILLS_DIRS 设则覆盖默认(用 path.delimiter 切分,与 PATH 同语义:
+ * win32 用 ';',POSIX 用 ':',规避盘符冒号问题);未设则默认三目录,
+ * 按优先级升序(低→高):~/.claude/skills → ~/.mocode/skills → <cwd>/.mocode/skills。
+ */
+export declare function resolveSkillsDirs(): string[];
+/**
+ * 极简 YAML frontmatter 解析(不引入 yaml 依赖)。
+ * 仅支持单行键值:按首个冒号切 key/value,trim,去首尾配对引号。
+ * 不支持块标量(| / >)与多行值——v1 限制(skill 的 description 实际多为单行)。
+ *
+ * 返回 { meta, body }:无 frontmatter 时 meta 为空、body 为原文。
+ */
+export declare function parseFrontmatter(content: string): {
+    meta: Record<string, string>;
+    body: string;
+};
+/**
+ * 扫描所有 skill 目录,解析 frontmatter,按目录优先级去重。
+ * 同步 fs + 全程静默容错(目录不存在 / 读失败 / 解析失败 → 跳过,不抛),
+ * 风格对齐 src/session/persist.ts。按 resolveSkillsDirs 升序遍历,
+ * Map.set 后设覆盖先设 → 项目级优先。
+ */
+export declare function discoverSkills(): Skill[];

package/dist/skills/index.d.ts

@@ -0,0 +1,13 @@
+import { type Skill } from './discover.js';
+export type { Skill };
+/** 已发现的 skill 列表(懒加载,首次调用触发扫描;启动期 repl 调一次)。 */
+export declare function listSkills(): Skill[];
+/**
+ * 读取某 skill 的 SKILL.md 正文(去掉 frontmatter)。
+ * 纯函数:找不到 / 读失败返 null(错误字符串交给调用方工具层生成)。
+ */
+export declare function getSkillBody(name: string): string | null;
+/** 拼进系统提示的 skill 段;无 skill 返空串(零行为变化)。 */
+export declare function buildSkillsSection(): string;
+/** base 系统提示 + skill 段;无 skill 时 === base。 */
+export declare function effectiveSystemPrompt(base: string): string;

package/dist/tools/builtins/ask-human.d.ts

@@ -0,0 +1,9 @@
+import type { Tool } from '../types.js';
+/** 单个选项:label 是选项本身,detail 是选它意味着什么/取舍(可选)。 */
+export interface ChoiceOption {
+    label: string;
+    detail?: string;
+}
+/** 公开以便 check-ask-human-options.ts 单元测试。 */
+export declare function coerceOptions(raw: unknown): ChoiceOption[];
+export declare const askHumanTool: Tool;

package/dist/tools/builtins/codegraph.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from '../types.js';
+export declare const codegraphTool: Tool;