mocode-ai 1.6.4 → 1.6.6

package/README.zh-CN.md

@@ -25,6 +25,15 @@ mocode 自己探索代码、读写改文件、执行命令、联网查资料,以
 
 <p align="center"><img src="./assets/demo-build-pomodoro.gif" alt="mocode 从零搭建番茄钟并通过浏览器截图自检" width="100%"></p>
 
+## 效率:更快、更省 token
+
+- **两级模型面板** — 裸 `/model` 先列厂商、Enter 进入后再选模型;搜索是作用域内过滤——顶层只匹配**厂商名**,厂商内只匹配**模型名**,不再把厂商和模型混在一个结果里。
+- **思考强度 `/effort`** — `off / low / medium / high / auto` 五档归一,按目标模型自动翻译成各家方言(Anthropic / OpenAI o·gpt-5 / Qwen3 / GLM / DeepSeek-R1 / 豆包);不认识的模型或第三方网关**不下发**未知字段,避免 400。
+- **用量统计 `/stats`** — 本会话缓存命中率、分层 token 用量与压缩次数,基于后端真实上报,不靠估算。
+- **缓存安全的压缩分叉** — 能整段复用旧对话时优先走 fork,保住 prompt-cache 前缀、减少重复计费;不满足条件再回落摘要(`MOCODE_COMPACT_FORK=false` 关闭)。
+- **重复读取去重** — 同一轮对同一文件的重复读取命中缓存,不再为相同内容重复付费(`MOCODE_READ_DEDUP=false` 关闭)。
+- **子 Agent 深度闸** — 递归派生默认最多 3 层(`SUB_AGENT_MAX_DEPTH` 可调),防止子 agent 无限膨胀。
+
 ## 架构
 
 MoCode 是一个分层的自治运行时：终端交互层驱动 Agent 内核，内核通过受控能力平面执行真实操作，持久化认知层则让长任务和跨会话工作保持连贯。
@@ -107,9 +116,15 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 - **流式输出 + 思考可见** — 回复边生成边显示;模型支持 reasoning 时思考过程实时可见,思考段自动折叠(不占屏)
 - **全屏 TUI** — 备用屏(alt screen)+ 固定底栏状态行 + 滚动回看(PgUp/PgDn),运行中可打字(typeahead),下一轮自动预填
 - **会话持久化** — 每轮自动落盘,`--resume` / `/resume` 续接历史会话
+- **后台任务** — `mocode run --bg "任务"` 派 detached 子进程,关终端不死;状态与日志落 `.mocode/jobs/`,`/jobs` 可列表/看日志/kill。设 `MOCODE_NOTIFY_WEBHOOK` 后,任务结束自动推送通知(ntfy/Bark/Telegram/generic)。无人值守任务遇到未授权的 confirm/dangerous 动作时会挂起(状态 `paused`)并通知你;在另一终端敲 `mocode approve <id>` 批准(`mocode deny` 拒绝,或 TUI 内 `/jobs approve`),任务在同一进程内续跑。用 `mocode attach <id>` 可实时跟随运行中(或已结束)的任务。长任务在每个工具批次后落 checkpoint;进程挂掉或机器重启后,`mocode resume-job <id>` 从最后 checkpoint 重放(在途动作会重跑)。`MOCODE_JOB_MAX_MS` / `MOCODE_JOB_MAX_TOKENS` 提供硬性时长/token 上限。
+- **具名 Bot** — `mocode bots add` 定义岗位 Bot(专属系统提示 + 可选工具白名单 + 沙箱范围),项目/全局两级;`--bot <name>` 按名运行,可与后台/schedules 组合。
+- **Arena 竞技场** — `arena` 工具把同一任务并行跑 N 遍(2-6,各自独立),再由 judge 模型按你给的标准对所有候选打分排序,返回排名和最优方案。适合设计/探索/解题这类“多跑几遍选最好”的场景。
+- **持久 Bot 消息协作** — `message_bus` 工具给具名 bot 提供持久的异步消息存储(`send`/`inbox`/`ack`/`history`):主管 bot 可把活交给当前没在运行的 bot;worker 之后(如被计划任务唤起)拉 inbox、干活、回复。身份随 `--bot` 走,每个 bot 只能看到/确认发给自己的消息。
+- **计划任务** — `mocode schedule add` 注册 cron / webhook 触发;本地 detached 守护(`schedule start`,仅回环)到点或被 `POST /trigger/<token>` 触发即派后台 job,分钟去重;另有 `schedule tick` 供系统任务计划调用。
+- **Headless 一次性执行** — `mocode -p "任务"` 或管道 `echo "任务" | mocode`,可选 `--json` 结构化输出;非交互下 confirm/dangerous 操作默认拒绝(`--dangerously-skip-permissions` 显式放开;`--verbose` 追加工具结果摘要、`--session-dir <目录>`、`--worktree` git 隔离工作树),会话仍自动落盘可 `--resume`
 - **Skills 系统** — 自动扫描 `~/.mocode/skills/` 等目录,description 注入系统提示,模型按需调 `use_skill` 加载完整指令(渐进式披露:先看简介,任务相关才加载正文)
 - **可选桌宠** — 独立悬浮窗(`/pet`)显示一个小角色,镜像 agent 活动(空闲 / 思考 / 跑工具 / 等人工),独立进程走 WebSocket,`/pet quit` 完全关闭。挂在终端外,绝不挡终端。
-- **斜杠命令** — `/exit` `/clear` `/cd` `/context` `/skills` `/compact` `/resume` `/rollback` `/memory` `/reflect` `/init` `/theme` `/model` `/plan` `/auto` `/pet`,输入时下拉过滤
+- **斜杠命令** — `/exit` `/clear` `/cd` `/context` `/skills` `/compact` `/resume` `/rollback` `/jobs` `/schedules` `/bots` `/memory` `/reflect` `/init` `/theme` `/model` `/effort` `/stats` `/plan` `/auto` `/pet`,输入时下拉过滤
 
 ## 使用文档
 
@@ -295,7 +310,9 @@ dev_server stop   id=srv-xxxx
 | `/memory`        | 看记忆库:条目数 + 近期索引                                          |
 | `/memory_switch` | 允许/禁止 memory 自动路由并切换 Memory Index；下一真实用户轮生效    |
 | `/reflect`       | 手动触发一次后台记忆反思 pass                                       |
-| `/model`         | 配置大模型(baseURL / apiKey / model / 上下文窗口),即时生效 + 持久化 |
+| `/model`         | 两级面板切换模型(先选厂商再选模型;顶层按厂商名、厂商内按模型名过滤);也可配置 baseURL / apiKey / 上下文窗口,即时生效 + 持久化 |
+| `/effort`        | 设置思考强度 off/low/medium/high/auto(如 `/effort high`);未识别模型不下发参数 |
+| `/stats`         | 本会话用量:缓存命中率 / 分层 token / 压缩次数 |
 | `/init`          | 扫描项目生成 `AGENTS.md` 项目记忆(发给 agent 执行)                  |
 | `/theme`         | 切换颜色主题(↑↓ · Enter,或 `/theme <name>` 直切)                    |
 | `/plan`          | 切到 plan 模式(只读探查 + 产出计划,审批后切 auto 执行)              |

package/dist/agent/model-turn.js

@@ -1,5 +1,8 @@
 import { estimatePromptTokens, estimateTokens, isContextLengthError, } from '../llm/index.js';
 import { visionBatch, visionKeep } from '../config/index.js';
+import { getActiveSessionStore } from '../session/store.js';
+import { getCurrentSessionId } from '../session/state.js';
+import { toUsageRecord } from '../session/usage-stats.js';
 /**
  * 沿 cause 链(≤3 层)取第一个 errno,供 trace 取证。
  * undici 把底层 errno 挂在 cause 上(`TypeError: fetch failed` → cause `read ECONNRESET`),
@@ -18,7 +21,7 @@ function traceCauseCode(err) {
 }
 /** Executes context preparation plus exactly one model step, including the single overflow retry path. */
 export async function runModelTurn(input) {
-    const { opts, ctx, history, historyManager, runtimeContextState, scheduler, contextTrimmer, modelRunner, activeTools, runPolicy, step, cacheState, turnLifecycle, cancellationLifecycle, rebuildHistoryIndexes, } = input;
+    const { opts, ctx, history, historyManager, runtimeContextState, scheduler, contextTrimmer, modelRunner, activeTools, runPolicy, step, readDedup, cacheState, turnLifecycle, cancellationLifecycle, rebuildHistoryIndexes, } = input;
     const { signal, onContextUpdate, hooks } = opts;
     const { usageMeter, emitTrace } = turnLifecycle;
     const requestBaseURL = ctx.config.baseURL;
@@ -37,6 +40,8 @@ export async function runModelTurn(input) {
     // 视觉滑动窗口**必须剪在 trim 之前**:contextTrimmer.trim() 拿的是 historyManager.snapshot(),
     // 若先 trim,预算口径还是未剪的旧数组,80% 压力线照旧被图像撑爆(design-notes/vision-window.md §2.1)。
     // 只在这一个地方剪;下面的 overflow 重试路径读同一个 snapshot,会自动受益。
+    runtimeContextState.currentStep = step;
+    readDedup.beginStep(step);
     const visionKeepN = visionKeep();
     if (visionKeepN > 0 && historyManager.pruneVisionWindow({ keep: visionKeepN, batch: visionBatch(), step })) {
         rebuildHistoryIndexes();
@@ -52,6 +57,8 @@ export async function runModelTurn(input) {
         signal,
     });
     historyRebuilt = trimResult.kind === 'rebuild';
+    if (trimResult.kind === 'rebuild' || trimResult.kind === 'content')
+        readDedup.markContextChanged();
     const trimStats = trimResult.kind === 'aborted' ? {} : trimResult.stats;
     if (scheduler && trimStats.compactHistoryCalled) {
         emitTrace('compact', {
@@ -244,6 +251,12 @@ export async function runModelTurn(input) {
     });
     runtimeContextState.lastUsage = result.usage;
     usageMeter.add(result.usage);
+    // P1:per-step 用量落盘(失败静默,见 appendUsage)。estimatedTotal 用本次裸估算,
+    // 供 /stats 校验估算偏差。
+    const record = toUsageRecord(step, 'main', result.usage, stepPromptEst);
+    const sessionId = getCurrentSessionId();
+    if (record && sessionId)
+        getActiveSessionStore().appendUsage(sessionId, record);
     if (result.usage) {
         cacheState.lastStepPromptTokens = result.usage.promptTokens;
         if (result.usage.cachedTokens > 0)

package/dist/agent/run-coordinator.js

@@ -13,6 +13,7 @@ import { runToolTurn } from './tool-turn.js';
 import { createTurnLifecycle } from './turn-lifecycle.js';
 import { parseArgs, argumentErrorHint, isParallelTool, isParallelOrchestrationCall, isResourceLockedCall, deniedOutcome, readDiffContext, pushToolResult, } from './tool-helpers.js';
 import { contextState, summarizeToolArguments } from '../session/index.js';
+import { createReadDedup } from '../tools/read-dedup.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
 import { invalidateArtifacts, rehydrateArtifacts } from '../context/index.js';
 import { createRelevancePruner } from '../context/relevance.js';
@@ -63,7 +64,10 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
     const turnLifecycle = createTurnLifecycle(opts, ctx, stages, savedMode);
     const { usageMeter, emitTrace, traceTurnId } = turnLifecycle;
     const toolTurnPlanState = { stepsSincePlanTouch: 0 };
-    historyManager.appendUserTurn(userInput);
+    if (!opts.continueFromHistory)
+        historyManager.appendUserTurn(userInput);
+    // P2:每用户 turn 一个重复读 scope,经 dispatcher → ToolContext 透传给 read_file。
+    const readDedup = createReadDedup();
     // The initial cancellation checkpoint is captured after the user turn and before any model/tool work.
     // Relevance and lifecycle collect provenance during normal work. Neither path
     // rewrites history; exact supersession is applied only by the pressure scheduler.
@@ -173,6 +177,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                     activeTools,
                     runPolicy,
                     step,
+                    readDedup,
                     cacheState: modelCacheState,
                     turnLifecycle,
                     cancellationLifecycle,
@@ -318,6 +323,7 @@ export async function runAgentCoreLegacy(opts, historyManager, stages) {
                                     isDenied: isToolDeniedForStep,
                                     currentAllowedToolNames,
                                     delegation: delegationForOrchestrator,
+                                    readDedup,
                                     argumentErrorHint: (name) => argumentErrorHint(name, runtimeContextState),
                                     ...(opts.toolPolicy
                                         ? {

package/dist/agent/spawn.js

@@ -10,6 +10,7 @@
 //  - 主屏渲染可选:TUI 激活时把子 agent 内部工具调用实时写入主内容区并复用 batch 折叠;
 //    TUI 未激活(host 嵌入 / 非 TTY)时纯静默,中间过程只缓冲进 transcript。
 //  - 独立 history 分支:子任务的工具噪声不回灌主对话,只有最终摘要回灌。
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { buildMocodeCorePrompt, isSubAgentHardDisabled } from '../config/index.js';
 import { getToolChatSchema } from '../tools/policy.js';
 import { effectiveSystemPrompt } from '../skills/index.js';
@@ -47,6 +48,11 @@ You are executing one delegated sub-task with the same engineering standards and
  * 中断:opts.signal 透传给子 runAgentCore——主 Ctrl+C 树杀子 agent(chat abort + 工具 abort)。
  * 子 agent 跑在主 signal 下,主 abort 即子 abort;子 agent 的 abortRestore 还原子 history + 模式。
  */
+/** 当前委派深度(P4 闸2):根 agent 无 store=0,每进一层 spawnAgent +1。 */
+const spawnDepthScope = new AsyncLocalStorage();
+function currentSpawnDepth() {
+    return spawnDepthScope.getStore() ?? 0;
+}
 export async function spawnAgent(opts) {
     const activeRuntime = opts.runtime ?? getActiveRuntime();
     const runtimeContext = opts.runtimeContext ?? activeRuntime?.context ?? getActiveAgentRuntimeContext() ?? defaultAgentRuntimeContext;
@@ -60,6 +66,20 @@ export async function spawnAgent(opts) {
             usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0, cachedTokens: 0, reasoningTokens: 0 },
         };
     }
+    // 深度闸:达上限直接结构化失败(模型看到后会改用直接工具完成)。执行层拦截,不裁 schema。
+    const depth = currentSpawnDepth() + 1;
+    if (depth > runtimeContext.config.subAgentMaxDepth) {
+        const msg = `Sub-agent depth limit ${runtimeContext.config.subAgentMaxDepth} reached ` +
+            '(nested delegation blocked to prevent fork-style recursion); complete the task directly with your own tools.';
+        return {
+            summary: msg,
+            completed: false,
+            transcript: msg,
+            status: 'failed',
+            usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0, cachedTokens: 0, reasoningTokens: 0 },
+            changedFiles: [],
+        };
+    }
     const maxSteps = opts.maxSteps ?? runtimeContext.config.subAgentMaxSteps;
     const requested = opts.tools === undefined ? null : new Set(opts.tools);
     const shared = opts.delegation && opts.delegation.history.length > 0 && opts.delegation.history[0]?.role === 'system'
@@ -172,8 +192,8 @@ export async function spawnAgent(opts) {
         const childIndex = parentId ? batch.getGroupChildIndex(opts.callId) : undefined;
         liveBatchId = batch.beginBatch(t('subagent.running'), {
             parentId,
-            // 子批摘要行缩进 = 两层 entry 缩进(随 ENTRY_INDENT 联动,不硬编码空格数)。
-            indent: parentId ? batch.SUB_BATCH_INDENT : undefined,
+            // 缩进由 beginBatch 按父层级自动推导:组容器批下 = 两层 entry 缩进;
+            // 普通子 agent 批下再嵌套 = 父缩进 + 两层(树状逐层加深)。
             groupChildIndex: childIndex,
             running: true,
         });
@@ -205,6 +225,8 @@ export async function spawnAgent(opts) {
             layout.contentWrite('\n');
     };
     let lastChar = '';
+    // P4 闸3:只收集本 agent 树自己产生的改动(钩子按真实执行触发),不靠整轮全局快照。
+    const nestedChangedFiles = new Set();
     const hooks = {
         onText: (s) => {
             writeBuf(s); // 缓冲流式正文(无 markdown 渲染,原始文本)
@@ -225,7 +247,10 @@ export async function spawnAgent(opts) {
             ensureQuietLine(opts.quietLabel ?? t('skill.executing', { name: opts.prompt.slice(0, 40) }));
             ensureLiveBatch();
             if (liveBatchId) {
-                batch.recordCall(liveBatchId, tc.name, summary);
+                // 登记内部调用的 tool_call id:子 agent 嵌套派生时,孙 spawnAgent 据此反查到
+                // 本子批,把孙批挂到对应的内部 sub-agent entry 下(而非游离到 buffer 末尾)。
+                batch.bindCall(tc.id, liveBatchId);
+                batch.recordCall(liveBatchId, tc.name, summary, tc.id);
                 // 默认折叠,只刷新摘要行计数(glob/read_file 数量),不展开明细列表。
                 batch.showLiveBatch(liveBatchId, liveLayout());
             }
@@ -237,7 +262,7 @@ export async function spawnAgent(opts) {
             if (liveBatchId) {
                 // 子 agent 批不展示 diff(其写入已直接落工作区,由主 agent 的当前回滚事务统一追踪);
                 // 空 preview 用占位标记 entry 已完成,避免折叠后摘要仍显示"运行中"。
-                batch.recordResult(liveBatchId, tc.name, preview || t('toolSummary.noOutput'), null, output, isToolErrorOutput(output));
+                batch.recordResult(liveBatchId, tc.name, preview || t('toolSummary.noOutput'), null, output, isToolErrorOutput(output), tc.id);
                 batch.showLiveBatch(liveBatchId, liveLayout());
             }
         },
@@ -286,7 +311,7 @@ export async function spawnAgent(opts) {
     // 与主 agent 完全同源:写操作直接落在工作区,进入主 agent 当前轮次的同一回滚事务
     // (spawn 不调 beginTurn)。没有 overlay 拷贝/ChangeSet 合并这一步——那是旧 read/write
     // 双模式的产物,子 agent 不再受限,也就不需要"先隔离再合并"。
-    const result = await runtime.run({
+    const runResult = () => runtime.run({
         turn: 'inherit',
         history,
         userInput,
@@ -296,11 +321,18 @@ export async function spawnAgent(opts) {
         toolsOverride,
         runtimeAllowedToolNames,
         contextState: localContextState,
+        // P4 闸3:run-coordinator 只消费顶层 onToolOutcome(非 hooks),在此收集本树真实改动。
+        onToolOutcome: (_tool, _args, outcome) => {
+            for (const f of outcome.changedFiles ?? [])
+                nestedChangedFiles.add(f);
+        },
         suppressOpeningAnalysis: true, // 子代理不注入「开场分析」:仅主线面对用户的首次响应用
         // 子代理不注入主会话「会话状态」(plan + 笔记):那是主 agent 的工作面,委派消息已带齐
         // 子任务所需上下文,重复注入只白付 token。
         suppressSessionState: true,
     });
+    // 深度 scope:子 agent 内再派生子 agent 时 ALS 读到此 depth。
+    const result = await spawnDepthScope.run(depth, runResult);
     const status = opts.signal?.aborted || result.terminationReason === 'aborted'
         ? 'aborted'
         : result.completed
@@ -318,5 +350,6 @@ export async function spawnAgent(opts) {
             cachedTokens: result.usage?.cachedTokens ?? 0,
             reasoningTokens: result.usage?.reasoningTokens ?? 0,
         },
+        changedFiles: [...nestedChangedFiles],
     };
 }

package/dist/agent/stages/model-runner.js

@@ -7,7 +7,7 @@ class ChatModelRunner {
         this.transport = transport;
     }
     run(request, signal) {
-        return this.transport(request.history.slice(), request.handlers, signal, request.tools.slice());
+        return this.transport(request.history.slice(), request.handlers, signal, request.tools.slice(), request.reasoningEffort ? { reasoningEffort: request.reasoningEffort } : undefined);
     }
 }
 class LegacyChatModelRunner extends ChatModelRunner {

package/dist/agent/stages/tool-dispatcher.js

@@ -46,6 +46,7 @@ class LegacyCompatibleToolDispatcher {
             callId: call.id,
             allowedToolNames: request.currentAllowedToolNames(),
             delegation: request.delegation(),
+            readDedup: request.readDedup,
             ...(hint ? { argumentErrorHint: hint } : {}),
             ...(onLockAcquired ? { onLockAcquired } : {}),
         });

package/dist/agent/tool-turn.js

@@ -78,6 +78,8 @@ export async function runToolTurn(input) {
         rebuildHistoryIndexes();
         throw error;
     }
+    // D3: batch committed (staged shadow pushed into backing) -> persist full history.
+    hooks.onCheckpoint?.(opts.history);
     hooks.onToolBatchEnd?.();
     cancellationLifecycle.checkpoint();
     const batchDecision = terminationPolicy.decide({

package/dist/agent/work-discipline.js

@@ -41,9 +41,11 @@ Call \`ask_human\` before coding only when repository evidence cannot resolve a
 3. multiple reasonable options that materially change product behavior;
 4. the request itself admits two or more materially different readings that lead to different deliverables (do not silently pick one and guess).
 
+When the request is ambiguous, vague, or missing key information, first load the \`brainstorming\` skill and clarify the need through a short dialogue (one question at a time) before starting work.
+
 For naming and implementation details, follow repository precedent and choose the safest reversible default. Disclose any consequential assumption.
 
-Budget: at most 2 \`ask_human\` calls per turn. Beyond that, use the safest reversible default and disclose it in the final reply.`;
+Budget: during requirement clarification (the \`brainstorming\` workflow) ask as many questions as genuinely advance understanding; during execution after requirements are clear, use at most 2 \`ask_human\` calls per turn, then fall back to the safest reversible default and disclose it in the final reply.`;
 /** Advisory guidance shared by main and sub-agents. */
 export function buildWorkDisciplineSection(_modelFamily) {
     return `${CORE_SECTION}\n\n${ASK_WHITELIST_SECTION}`;

package/dist/bots/bus.js

@@ -0,0 +1,117 @@
+// D1 持久 Bot 消息总线：bot 之间（以及 main 用户与 bot 之间）跨时间的异步消息。
+// 与同步 sub-agent 的区别：收发双方不必同时在线——消息落盘，worker bot 之后由
+// scheduler / bg 唤起时拉 inbox 处理并回结果。
+//
+// 存储（<sandboxRoot>/.mocode/bus/）：
+//   <msgId>.json            一条消息（只创建、永不改写 → 并发安全，无丢消息）
+//   <receiver>.read.json    该接收者已读消息 id 数组（低频 RMW，原子写）
+//
+// 身份用 AsyncLocalStorage 注入（runAsIdentity）：headless --bot X 时整段运行为 X，
+// 其内派生的 sub-agent 自动继承；缺省身份为 'main'（用户主会话）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+import { getSandboxRoot } from '../sandbox/index.js';
+export const DEFAULT_IDENTITY = 'main';
+const identityStorage = new AsyncLocalStorage();
+/** 在指定 bot 身份下执行 fn；子 agent / 工具内 getIdentity() 都返回该身份。 */
+export function runAsIdentity(identity, fn) {
+    return identityStorage.run(identity, fn);
+}
+export function getIdentity() {
+    return identityStorage.getStore() ?? DEFAULT_IDENTITY;
+}
+function busRoot() {
+    return path.join(getSandboxRoot() ?? process.cwd(), '.mocode', 'bus');
+}
+function messagePath(id) {
+    return path.join(busRoot(), `${id}.json`);
+}
+function readMarkerPath(receiver) {
+    // receiver 只允许安全文件名段，杜绝路径穿越。
+    const safe = receiver.replace(/[^a-zA-Z0-9_.-]/g, '_');
+    return path.join(busRoot(), `${safe}.read.json`);
+}
+export function sendMessage(input) {
+    const to = input.to.trim();
+    const body = input.body;
+    if (!to)
+        throw new Error('message recipient (to) is required');
+    if (!body)
+        throw new Error('message body is required');
+    const msg = {
+        id: `msg-${Date.now().toString(36)}-${randomBytes(3).toString('hex')}`,
+        from: (input.from ?? getIdentity()).trim() || DEFAULT_IDENTITY,
+        to,
+        body,
+        createdAt: new Date().toISOString(),
+        ...(input.inReplyTo ? { inReplyTo: input.inReplyTo } : {}),
+    };
+    fs.mkdirSync(busRoot(), { recursive: true });
+    const target = messagePath(msg.id);
+    fs.writeFileSync(`${target}.tmp`, `${JSON.stringify(msg, null, 2)}\n`, 'utf8');
+    fs.renameSync(`${target}.tmp`, target);
+    return msg;
+}
+function getReadSet(receiver) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(readMarkerPath(receiver), 'utf8'));
+        return new Set(Array.isArray(parsed) ? parsed.filter((x) => typeof x === 'string') : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+function saveReadSet(receiver, set) {
+    const target = readMarkerPath(receiver);
+    fs.writeFileSync(`${target}.tmp`, `${JSON.stringify([...set], null, 2)}\n`, 'utf8');
+    fs.renameSync(`${target}.tmp`, target);
+}
+function allMessages() {
+    let files;
+    try {
+        files = fs.readdirSync(busRoot());
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json') || f.endsWith('.read.json'))
+            continue;
+        try {
+            out.push(JSON.parse(fs.readFileSync(path.join(busRoot(), f), 'utf8')));
+        }
+        catch {
+            // skip corrupt
+        }
+    }
+    return out.sort((a, b) => (a.createdAt < b.createdAt ? -1 : 1));
+}
+/** 某身份的未读收件箱。 */
+export function inbox(identity = getIdentity()) {
+    const read = getReadSet(identity);
+    return allMessages().filter((m) => m.to === identity && !read.has(m.id));
+}
+/** 标记消息已读（ack）。只能 ack 发给自己的消息。 */
+export function markRead(ids, identity = getIdentity()) {
+    const read = getReadSet(identity);
+    const mine = new Set(allMessages()
+        .filter((m) => m.to === identity)
+        .map((m) => m.id));
+    const marked = [];
+    for (const id of ids) {
+        if (mine.has(id) && !read.has(id)) {
+            read.add(id);
+            marked.push(id);
+        }
+    }
+    if (marked.length)
+        saveReadSet(identity, read);
+    return marked;
+}
+/** 与某身份相关的全部消息（发出或收到），按时间排序。 */
+export function messageHistory(identity = getIdentity()) {
+    return allMessages().filter((m) => m.from === identity || m.to === identity);
+}

package/dist/bots/cli.js

@@ -0,0 +1,102 @@
+// `mocode bots …` 管理：
+//   add --name <n> (--prompt "<text>" | --prompt-file <path>) [--description <d>]
+//       [--tools "a,b,c"] [--sandbox-path <p>] [--global]
+//   list | show <name> | rm <name> [--global]
+// 作用域默认项目（.mocode/bots）；--global 写 ~/.mocode/bots。
+import fs from 'node:fs';
+import { saveBot, listBots, getBot, deleteBot } from './store.js';
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    if (i === -1)
+        return undefined;
+    const v = args[i + 1];
+    return v && !v.startsWith('-') ? v : undefined;
+}
+export async function runBotsCli(rawArgs) {
+    const sub = rawArgs[0] ?? 'list';
+    const args = rawArgs.slice(1);
+    switch (sub) {
+        case 'add': {
+            const name = flagValue(args, '--name');
+            const description = flagValue(args, '--description') ?? '';
+            const inline = flagValue(args, '--prompt');
+            const promptFile = flagValue(args, '--prompt-file');
+            const toolsRaw = flagValue(args, '--tools');
+            const sandboxPath = flagValue(args, '--sandbox-path');
+            const scope = args.includes('--global') ? 'global' : 'project';
+            if (!name) {
+                process.stderr.write('usage: mocode bots add --name <n> (--prompt "<text>" | --prompt-file <path>) ' +
+                    '[--description <d>] [--tools "a,b"] [--sandbox-path <p>] [--global]\n');
+                return 1;
+            }
+            let systemPrompt = inline ?? '';
+            if (promptFile) {
+                try {
+                    systemPrompt = fs.readFileSync(promptFile, 'utf8');
+                }
+                catch (e) {
+                    process.stderr.write(`mocode: cannot read prompt file: ${e instanceof Error ? e.message : String(e)}\n`);
+                    return 1;
+                }
+            }
+            if (!systemPrompt.trim()) {
+                process.stderr.write('mocode: bot prompt is empty (use --prompt or --prompt-file)\n');
+                return 1;
+            }
+            const tools = toolsRaw
+                ? toolsRaw
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                : undefined;
+            try {
+                const rec = saveBot({ name, description, systemPrompt, tools, sandboxPath, scope });
+                process.stdout.write(`Bot saved: ${rec.name} (${rec.scope})\n`);
+                return 0;
+            }
+            catch (e) {
+                process.stderr.write(`mocode: ${e instanceof Error ? e.message : String(e)}\n`);
+                return 1;
+            }
+        }
+        case 'show': {
+            const name = args[0];
+            if (!name) {
+                process.stderr.write('usage: mocode bots show <name>\n');
+                return 1;
+            }
+            const rec = getBot(name);
+            if (!rec) {
+                process.stderr.write(`mocode: bot "${name}" not found\n`);
+                return 1;
+            }
+            process.stdout.write(`${JSON.stringify(rec, null, 2)}\n`);
+            return 0;
+        }
+        case 'rm':
+        case 'remove': {
+            const name = args[0];
+            if (!name) {
+                process.stderr.write('usage: mocode bots rm <name> [--global]\n');
+                return 1;
+            }
+            const scope = args.includes('--global') ? 'global' : 'project';
+            const ok = deleteBot(name, scope);
+            process.stdout.write(ok ? `Removed bot ${name} (${scope})\n` : `mocode: bot ${name} (${scope}) not found\n`);
+            return ok ? 0 : 1;
+        }
+        case 'list':
+        default: {
+            const all = listBots();
+            if (all.length === 0) {
+                process.stdout.write('(no bots; create one with `mocode bots add …`)\n');
+                return 0;
+            }
+            for (const b of all) {
+                process.stdout.write(`${b.scope === 'global' ? 'g' : 'p'} ${b.name}` +
+                    `${b.tools && b.tools.length ? `  tools:${b.tools.length}` : ''}  ${b.description}\n`);
+            }
+            return 0;
+        }
+    }
+}

package/dist/bots/store.js

@@ -0,0 +1,100 @@
+// 具名 Bot 存储：一个 Bot = 岗位系统提示 + 可选工具白名单 + 可选沙箱范围。
+//
+// 两级存储（与 AGENTS.md 发现规则同风格）：
+// - 全局：~/.mocode/bots/<name>.json
+// - 项目：<sandboxRoot>/.mocode/bots/<name>.json
+// 合并时全局先、项目后，项目同名覆盖全局。
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { getSandboxRoot } from '../sandbox/index.js';
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+export function globalBotsDir() {
+    return path.join(os.homedir(), '.mocode', 'bots');
+}
+export function projectBotsDir() {
+    return path.join(getSandboxRoot() ?? process.cwd(), '.mocode', 'bots');
+}
+function botPath(dir, name) {
+    return path.join(dir, `${name}.json`);
+}
+function assertValidName(name) {
+    if (!NAME_RE.test(name)) {
+        throw new Error(`bad bot name "${name}": use 1-32 chars, lowercase letters/digits/dash, cannot start with dash`);
+    }
+}
+/** 校验并落盘一个 bot（scope 决定写全局还是项目）。 */
+export function saveBot(input) {
+    assertValidName(input.name);
+    if (!input.systemPrompt.trim())
+        throw new Error('bot systemPrompt must not be empty');
+    const scope = input.scope ?? 'project';
+    const record = {
+        name: input.name,
+        description: input.description ?? '',
+        systemPrompt: input.systemPrompt,
+        ...(input.tools && input.tools.length ? { tools: input.tools } : {}),
+        ...(input.sandboxPath ? { sandboxPath: input.sandboxPath } : {}),
+        scope,
+        createdAt: new Date().toISOString(),
+    };
+    const dir = scope === 'global' ? globalBotsDir() : projectBotsDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const target = botPath(dir, record.name);
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, target);
+    return record;
+}
+function readOne(dir, file) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readDir(dir) {
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        const rec = readOne(dir, f);
+        if (rec)
+            out.push(rec);
+    }
+    return out;
+}
+/** 列出全部 bot（全局 + 项目，项目同名覆盖）。 */
+export function listBots() {
+    const byName = new Map();
+    for (const b of readDir(globalBotsDir()))
+        byName.set(b.name, b);
+    for (const b of readDir(projectBotsDir()))
+        byName.set(b.name, b);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function getBot(name) {
+    // 项目优先（覆盖语义）：先找项目再找全局。
+    const project = readOne(projectBotsDir(), `${name}.json`);
+    if (project)
+        return project;
+    return readOne(globalBotsDir(), `${name}.json`);
+}
+export function deleteBot(name, scope = 'project') {
+    assertValidName(name);
+    try {
+        fs.rmSync(botPath(scope === 'global' ? globalBotsDir() : projectBotsDir(), name));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}