mocode-ai 0.4.8 → 0.4.10

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;

package/dist/tools/builtins/codegraph.js

@@ -10,8 +10,9 @@ import { MAX_OUTPUT } from '../constants.js';
 function hasCodegraphIndex() {
     return existsSync(path.join(process.cwd(), '.codegraph'));
 }
-/** 跑 codegraph CLI 子进程,返回合并 stdout+stderr(带退出码),超时 60s。 */
-function runCodegraph(args) {
+/** 跑 codegraph CLI 子进程,返回合并 stdout+stderr(带退出码),超时 60s。
+ *  signal 透传(用户 Ctrl+C)→ 即时杀子进程,不等 60s 超时。 */
+function runCodegraph(args, signal) {
     return new Promise((done) => {
         const isWin = process.platform === 'win32';
         // win32 必须走 cmd.exe /c:Node 自 CVE-2024-27980 修复后,shell:false 直接 spawn
@@ -26,6 +27,7 @@ function runCodegraph(args) {
                 return;
             finished = true;
             clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
             done(s);
         };
         const onChunk = (chunk) => {
@@ -46,6 +48,17 @@ function runCodegraph(args) {
             child.kill();
             finish(`[超时,已终止]\n${out.trim()}`);
         }, 60000);
+        // abort(用户 Ctrl+C,经 executeTool ctx.signal 透传)→ 杀子进程 + 返[已中断]
+        const onAbort = () => {
+            child.kill();
+            finish(`[已中断]\n${out.trim()}`);
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
     });
 }
 export const codegraphTool = {
@@ -84,7 +97,7 @@ export const codegraphTool = {
         },
         required: ['action', 'query'],
     },
-    async execute(args) {
+    async execute(args, ctx) {
         if (!hasCodegraphIndex()) {
             return ('当前目录无 .codegraph/ 索引。codegraph 工具不可用。\n' +
                 '建索引:运行 `codegraph init`(需要 codegraph CLI:`npm i -g @colbymchenry/codegraph`)。\n' +
@@ -110,6 +123,6 @@ export const codegraphTool = {
         else {
             return `错误:未知 action "${action}",可选 explore 或 node。`;
         }
-        return runCodegraph(cliArgs);
+        return runCodegraph(cliArgs, ctx?.signal);
     },
 };

package/dist/tools/builtins/drop-context.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from '../types.js';
+/**
+ * 运行中上下文剔除工具:agent 检索到大量无关信息后,主动把历史里无关的 tool 结果替换为存根,
+ * 释放上下文空间(保 tool_call_id 配对不变量,只改 content)。
+ *
+ * 与 compact 的区别:compact 是阈值触发的整体压缩(微截 + 摘要);drop_context 是 agent 主动、
+ * 精准剔除"已判定无关"的具体 tool 结果。
+ *
+ * 保护:history[0](system)与当前轮(最后一个 user 及其之后)永不剔除——agent 还在用。
+ * 已是存根的不重复剔除(幂等)。永不抛错。
+ *
+ * 筛选(各维度 AND 组合,全部可选;不传 = 剔除所有可剔除的旧 tool 结果):
+ *  - toolNames:只剔除这些工具名的结果(如 ["grep","read_file"])
+ *  - contains:只剔除内容包含所有这些词(AND、大小写不敏感)的结果
+ *
+ * plan 模式不禁用:纯上下文管理,无文件 / 命令副作用。
+ */
+export declare const dropContextTool: Tool;

package/dist/tools/builtins/edit-file.d.ts

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

package/dist/tools/builtins/edit-file.js

@@ -4,6 +4,7 @@ import { resolve } from 'node:path';
 export const editFileTool = {
     name: 'edit_file',
     description: 'Replace a string in a file. old_string must occur exactly once and match exactly (including indentation/newlines). Use write_file for new files.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

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

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

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

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

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

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

package/dist/tools/builtins/index.js

@@ -18,6 +18,7 @@ import { memoryUpdateTool } from './memory-update.js';
 import { memoryForgetTool } from './memory-forget.js';
 import { taskTool } from './task.js';
 import { todolistTool } from './todolist.js';
+import { projectSkillUpdateTool } from './project-skill-update.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
@@ -41,6 +42,11 @@ const _memoryTools = _memoryEnabledAtBoot
         memoryForgetTool,
     ]
     : [];
+/** 项目专属 Skill 工具:仅在 MOCODE_PROJECT_SKILL=true 时注册,与 memory 同模式。 */
+const _projectSkillEnabledAtBoot = process.env.MOCODE_PROJECT_SKILL === 'true';
+const _projectSkillTools = _projectSkillEnabledAtBoot
+    ? [projectSkillUpdateTool]
+    : [];
 export const builtinTools = [
     readFileTool,
     writeFileTool,
@@ -56,6 +62,7 @@ export const builtinTools = [
     switchModeTool, // plan↔auto 自切(两模式都可见,不进 PLAN_DISABLED_TOOLS;副作用控制工具→串行分支)
     dropContextTool, // 运行中剔除无关 tool 结果(上下文管理,无副作用;两模式都可见,串行分支)
     ..._memoryTools,
+    ..._projectSkillTools,
     taskTool, // 派生子 agent(独立 history + 可受限工具集);plan 模式禁用(见 PLAN_DISABLED_TOOLS)
     todolistTool, // 工作记事本(plan 文件:复杂任务 checklist,落盘抗压缩);plan 模式可用(便于「先 plan 再 auto」时落地执行清单)
 ];

package/dist/tools/builtins/memory-forget.d.ts

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

package/dist/tools/builtins/memory-forget.js

@@ -4,6 +4,7 @@ import { forgetEntry } from '../../memory/store.js';
 export const memoryForgetTool = {
     name: 'memory_forget',
     description: 'Forget a memory entry: default archive (hidden, revivable via memory_update); mode=delete hard-deletes. Pinned entries can\'t be deleted (unpin first).',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-list.d.ts

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

package/dist/tools/builtins/memory-save.d.ts

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

package/dist/tools/builtins/memory-save.js

@@ -5,6 +5,7 @@ import { saveEntry } from '../../memory/store.js';
 export const memorySaveTool = {
     name: 'memory_save',
     description: 'Save a cross-session long-term memory entry. Store only non-obvious, useful facts/decisions/pitfalls. Title enters the startup index; retrieve body via memory_search.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/memory-search.d.ts

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

package/dist/tools/builtins/memory-update.d.ts

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

package/dist/tools/builtins/memory-update.js

@@ -4,6 +4,7 @@ import { updateEntry } from '../../memory/store.js';
 export const memoryUpdateTool = {
     name: 'memory_update',
     description: 'Update a memory entry in place (id unchanged). Use when facts changed / correcting outdated info / toggling pinned. Get id from memory_list or memory_search.',
+    risk: 'confirm',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/project-skill-update.js

@@ -0,0 +1,104 @@
+import { readProjectSkill, writeProjectSkillWithCompression, appendProjectSkillWithCompression, } from '../../project-skill/index.js';
+/**
+ * 项目专属 Skill 更新工具。
+ * 支持三种操作:
+ *   - read: 读取当前 skill 内容
+ *   - write: 全量覆盖(适合重构整个 skill)
+ *   - append: 追加到末尾(适合发现新坑点/约定时增量更新)
+ *
+ * 使用场景:
+ *   - 开发过程中发现项目特有的架构模式、命名约定
+ *   - 踩坑后记录避坑指南
+ *   - 总结项目关键决策和设计理由
+ *   - 随着项目开发，skill 越来越了解项目，开发效率越来越高
+ */
+export const projectSkillUpdateTool = {
+    name: 'project_skill_update',
+    description: 'Update the project-specific skill file (.mocode/project-skill.md). ' +
+        'Use this to record architectural patterns, naming conventions, common pitfalls, ' +
+        'and key decisions specific to this project. The skill persists across sessions and ' +
+        'is injected into the system prompt when MOCODE_PROJECT_SKILL=true. ' +
+        'Actions: "read" (view current content), "write" (replace all), "append" (add to end). ' +
+        '\n\n' +
+        '## Skill 维护指南\n' +
+        'Skill 专注 Snapshot 无法自动提供的洞察知识（why/how/gotchas）。Snapshot 已提供文件结构和静态文件内容——Skill 不要重复这些信息。\n' +
+        '\n' +
+        '**Skill 该写什么（Snapshot 不能替代的）**：\n' +
+        '- 设计决策的 why（为什么这样设计、取舍是什么）\n' +
+        '- 模块行为和职责描述（怎么工作、数据流、调用链）\n' +
+        '- 常见坑点和解决方案（踩过的坑、非直觉行为、边界条件）\n' +
+        '- 项目约定（命名规范、代码风格、测试策略）\n' +
+        '- 开发流程（构建/测试/部署命令及注意事项）\n' +
+        '- 关键 API 的使用限制和特殊行为\n' +
+        '\n' +
+        '**Skill 不该写什么（交给 Snapshot）**：\n' +
+        '- 文件列表和目录结构（Snapshot 自动扫描 src 树）\n' +
+        '- 静态文件内容摘要（依赖、编译器选项等 → package.json / tsconfig.json）\n' +
+        '\n' +
+        '**何时更新**：发现新架构模式、踩坑后总结、学到新约定、完成重要重构、用户纠正理解时。\n' +
+        '\n' +
+        '**注意事项**：\n' +
+        '- 保持精简，硬上限 4000 字符（约 1000 token）\n' +
+        '- 写可操作的内容，避免空泛描述\n' +
+        '- 用具体路径和例子（不要写"有多个模块"，要写"src/agent 负责 agent 循环"）\n' +
+        '- 定期整理，删除过时信息\n' +
+        '- 更新前建议先 `read` 看一下现有内容，避免重复\n' +
+        '\n' +
+        '**自动压缩**：内容超限时会自动调用 LLM 压缩（最多 3 次），无需手动精简。',
+    risk: 'safe',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['read', 'write', 'append'],
+                description: 'Action to perform: "read" to view current content, "write" to replace all, "append" to add to end',
+            },
+            content: {
+                type: 'string',
+                description: 'Content to write or append (required for "write" and "append" actions, ignored for "read")',
+            },
+        },
+        required: ['action'],
+    },
+    execute: async (args, ctx) => {
+        const action = String(args.action ?? '').trim();
+        const content = String(args.content ?? '');
+        const signal = ctx?.signal;
+        switch (action) {
+            case 'read': {
+                const current = readProjectSkill();
+                if (!current) {
+                    return 'Project skill is empty or does not exist yet.';
+                }
+                return `Current project skill:\n\n${current}`;
+            }
+            case 'write': {
+                if (!content.trim()) {
+                    return 'Error: "write" action requires non-empty content parameter.';
+                }
+                const result = await writeProjectSkillWithCompression(content, 3, signal);
+                if (!result.ok) {
+                    return `Error: ${result.error}`;
+                }
+                return result.compressed
+                    ? 'Project skill updated successfully (full replacement, auto-compressed to fit limit).'
+                    : 'Project skill updated successfully (full replacement).';
+            }
+            case 'append': {
+                if (!content.trim()) {
+                    return 'Error: "append" action requires non-empty content parameter.';
+                }
+                const result = await appendProjectSkillWithCompression(content, 3, signal);
+                if (!result.ok) {
+                    return `Error: ${result.error}`;
+                }
+                return result.compressed
+                    ? 'Project skill updated successfully (appended, auto-compressed to fit limit).'
+                    : 'Project skill updated successfully (appended).';
+            }
+            default:
+                return `Error: Unknown action "${action}". Use "read", "write", or "append".`;
+        }
+    },
+};

package/dist/tools/builtins/read-file.d.ts

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

package/dist/tools/builtins/run-command.d.ts

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

package/dist/tools/builtins/run-command.js

@@ -5,6 +5,7 @@ import { getSandboxRoot, filterEnv, isCommandDenied } from '../../sandbox/index.
 export const runCommandTool = {
     name: 'run_command',
     description: 'Run a shell command, merging stdout+stderr. Default timeout 120s. For tests, builds, git, etc.',
+    risk: 'dangerous',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/switch-mode.d.ts

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

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

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