mocode-ai 1.2.5 → 1.2.6

package/README.md

@@ -79,7 +79,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 - **Plan / Auto dual mode** — In `plan` mode the agent is read-only (reads code, queries indexes, searches — never writes to disk, runs commands, or spawns sub-agents) and produces a plan; `auto` mode unlocks the full toolset. The agent can switch between the two on its own — scope out an unfamiliar codebase first, then start making changes.
 - **Pressure-driven context compression** — Normal history keeps full tool evidence. At 80% occupancy, one scheduler event runs all enabled cleanup and always follows with a history summary. `/context` shows live usage and `/compact` remains an explicit manual override.
 - **Cross-session long-term memory** — The agent can save project architecture, conventions, and lessons learned as long-term memory, auto-loaded in future sessions. A background process periodically reflects on conversations to mine things worth remembering. Memories can be created, searched, updated, and forgotten, with recall-based decay.
-- **Project context (`MOCODE.md`)** — A single project-level memory file at `MOCODE.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Loaded automatically into the system prompt on every turn.
+- **Project context (`AGENTS.md`)** — A single project-level memory file at `AGENTS.md` captures both static facts (project description, commands, module list, directory tree) and human/AI-written insights (conventions, architectural decisions, pitfalls). Generate it once with `/init`, then keep it up to date by hand or by asking the agent to refresh it. Loaded automatically into the system prompt on every turn.
 - **Session notepad (notes.md)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent maintains a working notepad at `.mocode/sessions/<sessionId>/notes.md` (file-based, survives context compression). It records the execution plan with the dedicated `plan_update` tool — a three-state step machine (`pending`/`in_progress`/`completed`, at most one `in_progress`) that auto-settles to `## Done:` when finished. The active plan is re-injected into the system prompt after compaction and re-synced into context whenever notes.md changes, and a gentle reminder nudges the agent if it goes several tool-steps without updating the plan. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`.
 - **Interruptible and reversible** — Ctrl+C interrupts the current turn at any time (kills child processes recursively, rolls history back to before the turn started, leaves no half-finished tool calls). `/rollback` restores file changes from per-turn snapshots, with a per-file keep/undo choice — no git dependency required.
 - **Sandbox protection** — File reads/writes go through a sandbox that blocks out-of-bounds paths (`../../`, absolute paths outside the root, symlink escapes, etc.), so the agent never touches files outside your working directory.
@@ -96,7 +96,7 @@ MoCode isn't a chat box with a coat of paint — it's an agent that actually get
 ## Documentation
 
 - [中文使用指南](./docs/usage.md) — 菜单式快速上手、命令速查、模式、会话、项目上下文与排障。
-- [Project context](./docs/usage.md#项目上下文) — `MOCODE.md` and Skills.
+- [Project context](./docs/usage.md#项目上下文) — `AGENTS.md` and Skills.
 
 ## Installation
 
@@ -218,7 +218,7 @@ The agent operates in **the working directory it was launched from** — to have
 | `memory_update`     | Edit a memory in place (id unchanged; correct stale facts / update summary / toggle pin) |
 | `memory_forget`     | Forget a memory: archived by default (recoverable), `mode=delete` for a hard delete (pinned memories can't be deleted) |
 
-The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle at runtime with `/memory_switch` (REPL restart required, by design — see Skills section for the difference between Tier-1 `MOCODE.md` and Tier-2 memory).
+The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle at runtime with `/memory_switch` (REPL restart required, by design — see Skills section for the difference between Tier-1 `AGENTS.md` and Tier-2 memory).
 
 The four frontend tools — `browser`, `dev_server`, `screenshot`, `view_image` — are **off by default** (they depend on the Playwright binary, spawn long-lived processes, or capture the desktop). Enable the whole cluster at runtime with `/fe on`; the model only sees them once enabled. Toggle with `/fe on|off|status`.
 
@@ -254,7 +254,7 @@ dev_server stop   id=srv-xxxx
 | `/memory_switch`   | Toggle Tier-2 memory on/off (REPL restart required — by design)       |
 | `/reflect`          | Manually trigger a background memory reflection pass                  |
 | `/model`            | Configure the LLM (baseURL / apiKey / model / context window), applied immediately + persisted |
-| `/init`             | Scan the project and generate `MOCODE.md` project memory (dispatched to the agent) |
+| `/init`             | Scan the project and generate `AGENTS.md` project memory (dispatched to the agent) |
 | `/theme`            | Switch color theme (↑↓ · Enter, or `/theme <name>` directly)         |
 | `/plan`             | Switch to plan mode (read-only exploration + plan output, approve to switch to auto) |
 | `/auto`             | Switch back to auto mode (full toolset execution)                     |
@@ -293,11 +293,11 @@ A skill's `description` is injected into the system prompt (progressive disclosu
 
 The system prompt provides lightweight guidance rather than a framework gate: inspect only what matters, make focused changes, avoid repeated stale reads, and report uncertainty honestly. The agent decides whether validation is useful for the task and chooses the scope itself. Broad test/build suites are not run by default, and lack of validation never blocks completion or triggers an extra model turn.
 
-## Project memory (MOCODE.md)
+## Project memory (AGENTS.md)
 
 MoCode has a **two-tier memory** model distinct from skills:
 
-- **Tier-1 — `MOCODE.md` (auto-loaded every session):** Markdown project memory that gets concatenated into the system prompt on every turn. Discovery walks `~/.mocode/MOCODE.md` → every `MOCODE.md` from the cwd up to the filesystem root (far→near, near wins). On overflow the body is truncated with a marker pointing back at the files. Generate or refresh one with `/init`, or write it by hand — it's plain Markdown, no schema. `MOCODE.md` is also where the agent itself persists "next-session facts" it deduces (architecture, conventions, pitfalls).
+- **Tier-1 — `AGENTS.md` (auto-loaded every session):** Markdown project memory that gets concatenated into the system prompt on every turn. Discovery walks `~/.mocode/AGENTS.md` → every `AGENTS.md` from the cwd up to the filesystem root (far→near, near wins). On overflow the body is truncated with a marker pointing back at the files. Generate or refresh one with `/init`, or write it by hand — it's plain Markdown, no schema. `AGENTS.md` is also where the agent itself persists "next-session facts" it deduces (architecture, conventions, pitfalls).
 - **Tier-2 — `memory_*` tool library (agent-driven, opt-in):** Discrete tagged records (`decision` / `fact` / `pitfall` / `reference` / `feedback`) with recall-count-based decay (30-day → archived; 90-day → GC). The agent saves / searches / updates / forgets via tools; titles go in the system-prompt index (≤50), bodies fetched on demand via `memory_search`. Off by default; toggle with `MEMORY_ENABLED=true` at startup or `/memory_switch` (REPL restart required).
 
 ## Type checking

package/README.zh-CN.md

@@ -95,7 +95,7 @@ mocode 不是一个套壳聊天框,而是一个能真正动手干活的 agent:
 ## 使用文档
 
 - [菜单式使用指南](./docs/usage.md) — 快速上手、命令速查、模式、会话、项目上下文与排障。
-- [项目上下文：`MOCODE.md` 与 Skills](./docs/usage.md#项目上下文)
+- [项目上下文：`AGENTS.md` 与 Skills](./docs/usage.md#项目上下文)
 
 ## 安装
 
@@ -257,7 +257,7 @@ dev_server stop   id=srv-xxxx
 | `/memory_switch` | 切换 Tier-2 记忆开关(需重启 REPL,刻意为之)                  |
 | `/reflect`      | 手动触发一次后台记忆反思 pass                                   |
 | `/model`        | 配置大模型(baseURL / apiKey / model / 上下文窗口),即时生效 + 持久化 |
-| `/init`         | 扫描项目生成 `MOCODE.md` 项目记忆(发给 agent 执行)               |
+| `/init`         | 扫描项目生成 `AGENTS.md` 项目记忆(发给 agent 执行)               |
 | `/theme`        | 切换颜色主题(↑↓ · Enter,或 `/theme <name>` 直切)            |
 | `/plan`         | 切到 plan 模式(只读探查 + 产出计划,审批后切 auto 执行)              |
 | `/auto`         | 切回 auto 模式(全量工具执行)                                  |
@@ -296,11 +296,11 @@ skill 的 `description` 注入系统提示(渐进式披露第①层),模型只
 
 system prompt 提供轻量建议而不是框架硬门：只检查支持下一步决策的内容，做最小完整改动，避免重复读取，并诚实说明不确定性。agent 自主决定是否需要验证以及验证范围；框架不会因为未验证阻止完成或追加模型轮次。
 
-## 项目记忆(MOCODE.md)
+## 项目记忆(AGENTS.md)
 
 mocode 的**双层记忆**模型,跟 Skills 是两件事:
 
-- **Tier-1 — `MOCODE.md`(每轮自动加载):** Markdown 项目记忆,每轮拼进 system prompt。发现路径:`~/.mocode/MOCODE.md` → 从 cwd 往上逐级 `MOCODE.md`(远→近拼接,近的覆盖更突出);超长截断并标注原始文件。运行 `/init` 生成或刷新,纯 Markdown,可手写,无 schema。agent 自己推得的「下次要记住的事实」(架构/约定/坑位)也写在这里。
+- **Tier-1 — `AGENTS.md`(每轮自动加载):** Markdown 项目记忆,每轮拼进 system prompt。发现路径:`~/.mocode/AGENTS.md` → 从 cwd 往上逐级 `AGENTS.md`(远→近拼接,近的覆盖更突出);超长截断并标注原始文件。运行 `/init` 生成或刷新,纯 Markdown,可手写,无 schema。agent 自己推得的「下次要记住的事实」(架构/约定/坑位)也写在这里。
 - **Tier-2 — `memory_*` 工具库(agent 主导,需启用):** 离散带标签条目(`decision` / `fact` / `pitfall` / `reference` / `feedback`),按召回计数衰减(30 天 → archived,90 天 → 硬删 GC)。agent 用工具存 / 搜 / 改 / 删;索引(标题)进系统提示(≤50 条),正文按需 `memory_search` 取。默认关,启动 `MEMORY_ENABLED=true` 或 REPL 内 `/memory_switch`(需重启 REPL,刻意为之)。
 
 ## 类型检查

package/dist/agent/core.js

@@ -7,7 +7,7 @@
 import { readFileSync } from 'node:fs';
 import { getNotesMtime } from '../session/notes.js';
 import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
-import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } from '../tools/registry.js';
+import { executeToolOutcome, findTool, getToolCapabilities, isFileMutationTool, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
 import { validateToolArguments } from '../tools/validation.js';
 import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
@@ -18,7 +18,7 @@ import { createBudgetScheduler } from '../session/scheduler.js';
 import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, } from '../context/index.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
-import { config, extractActivePlanSection, reinjectActivePlanIntoSystem } from '../config/index.js';
+import { config, extractActivePlanSection, reinjectSessionStateIntoSystem } from '../config/index.js';
 import { t } from '../i18n/index.js';
 import { jailResolve } from '../sandbox/index.js';
 import { createLifecycleEngine } from '../context/lifecycle.js';
@@ -42,13 +42,13 @@ function parseArgs(raw) {
 }
 /** 只有显式声明 parallel 且无需权限确认的工具才进入普通并发组。 */
 function isParallelTool(name) {
-    const tool = tools.find((candidate) => candidate.name === name);
+    const tool = findTool(name);
     return !!tool && (tool.risk ?? 'safe') === 'safe' &&
         getToolCapabilities(tool).concurrency === 'parallel';
 }
 /** resource-locked 工具先顺序完成权限预检，再依赖 canonical resource lock 并发执行。 */
 function isResourceLockedTool(name) {
-    const tool = tools.find((candidate) => candidate.name === name);
+    const tool = findTool(name);
     return !!tool && getToolCapabilities(tool).concurrency === 'resource-locked';
 }
 function isResourceLockedCall(call) {
@@ -326,8 +326,8 @@ export async function runAgentCore(opts) {
                         runtimeContextState.lifecycleStats = lifecycle.stats();
                     }
                     rehydrateArtifacts(runtimeContextState, history);
-                    // ② compact 后把活跃 plan 重注入系统提示，避免 agent 因上下文压缩丢失执行计划。
-                    reinjectActivePlanIntoSystem(history);
+                    // ② compact 后把会话状态(活跃 plan + 笔记段)重注入系统提示，避免 agent 因上下文压缩丢失计划与笔记。
+                    reinjectSessionStateIntoSystem(history);
                 }
                 hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
                 mode = 'idle';
@@ -602,7 +602,7 @@ export async function runAgentCore(opts) {
                             for (let k = 0; k < batch.length; k++) {
                                 const tc = batch[k];
                                 const parsed = parseArgs(tc.arguments);
-                                const tool = tools.find((candidate) => candidate.name === tc.name);
+                                const tool = findTool(tc.name);
                                 const argumentsValid = tool && parsed !== null
                                     ? validateToolArguments(tool, parsed).valid
                                     : false;
@@ -693,7 +693,7 @@ export async function runAgentCore(opts) {
                             // 权限预检查:在渲染 ● 头之前弹确认面板(体验:先问再执行,而非执行完再问)。
                             // 拒绝时只渲染拒绝结果,不渲染执行头;放行则继续走 header → start → executeTool 流程。
                             const parsed = parseArgs(tc.arguments);
-                            const tool = tools.find((t) => t.name === tc.name);
+                            const tool = findTool(tc.name);
                             const argumentsValid = tool && parsed !== null
                                 ? validateToolArguments(tool, parsed).valid
                                 : false;
@@ -768,7 +768,7 @@ export async function runAgentCore(opts) {
                     // B(nag 提醒):连续 N 步有工具活动但没更新 plan,在当前步第一条 tool_result 前注入提醒。
                     const notesMtimeAfter = getNotesMtime();
                     if (notesMtimeAfter !== notesMtimeBefore) {
-                        reinjectActivePlanIntoSystem(history);
+                        reinjectSessionStateIntoSystem(history);
                         stepsSincePlanTouch = 0;
                     }
                     else {

package/dist/config/index.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import dotenv from 'dotenv';
 import { getCurrentSessionId } from '../session/state.js';
-import { getNotesFilePath } from '../session/notes.js';
+import { getNotesFilePath, extractActiveNotesSections } from '../session/notes.js';
 import { buildWorkDisciplineSection, inferModelFamily } from '../agent/work-discipline.js';
 import { detectLanguage, setLanguage, t, } from '../i18n/index.js';
 /**
@@ -214,20 +214,81 @@ export function reinjectActivePlanIntoSystem(history) {
     sys.content = `${content}${ACTIVE_PLAN_MARKER}${plan}\n`;
     return true;
 }
+/** compact 重注入用的幂等标记:history[0] 中夹住会话笔记段正文(Findings/Decisions/Open Questions/Risks),
+ *  重复注入只替换不累积。与 ACTIVE_PLAN_MARKER 独立,互不干扰。 */
+const NOTES_BODY_MARKER = '\n\n<!-- mocode:session-notes -->\n';
+/**
+ * 把会话笔记段正文重注入系统提示(history[0])。compact 后或本步改了 notes.md 时调用:
+ * 若 notes.md 有活跃笔记段(extractActiveNotesSections 返回非空,已按 5k token 预算裁剪),
+ * 则覆盖旧标记块写入最新内容;若无,则清掉残留标记块。直接改 history[0].content,
+ * 幂等,返回是否改动。与 reinjectActivePlanIntoSystem 独立:plan 段由后者管,笔记段由本函数管。
+ */
+export function reinjectSessionNotesIntoSystem(history) {
+    const sys = history[0];
+    if (!sys || sys.role !== 'system' || typeof sys.content !== 'string')
+        return false;
+    let content = sys.content;
+    const markerIdx = content.indexOf(NOTES_BODY_MARKER);
+    if (markerIdx >= 0) {
+        content = content.slice(0, markerIdx).replace(/\s+$/, '');
+    }
+    const notes = extractActiveNotesSections();
+    if (!notes) {
+        if (markerIdx < 0)
+            return false;
+        sys.content = content;
+        return true;
+    }
+    sys.content = `${content}${NOTES_BODY_MARKER}${notes}\n`;
+    return true;
+}
+/**
+ * 一次性重注入会话状态(plan 段 + 笔记段)到系统提示。调用点(core.ts compact 后 /
+ * 本步改 notes.md、repl compact 时)统一用本函数替代 reinjectActivePlanIntoSystem,
+ * 让笔记段享有与 plan 段完全对称的常驻 + 恢复时机。返回任一 marker 是否改动。
+ */
+export function reinjectSessionStateIntoSystem(history) {
+    const planChanged = reinjectActivePlanIntoSystem(history);
+    const notesChanged = reinjectSessionNotesIntoSystem(history);
+    return planChanged || notesChanged;
+}
 const SYSTEM_PROMPT_MEMORY_SECTION = `
 ## Memory (cross-session facts)
 - The prompt may contain a title/summary index; retrieve details with memory_search or inspect all with memory_list. memory_search also surfaces knowledge-graph facts (relations between entities) alongside entry bodies.
 - Save only stable, non-obvious cross-session facts. Search before saving; update an existing entry instead of duplicating it, and archive stale entries.
 - A knowledge-graph layer links entities across memories: explore relations/neighbors with memory_graph (neighbors/add/stats), and attach meaningful links via the links parameter of memory_save when saving.`;
-/** Inject only retrieval guidance; MOCODE.md contents stay outside the prompt until read on demand. */
+/** AGENTS.md 自动导入正文上限:system 位于 history[0] 且 compactHistory 不压缩 system,超长需截断防占窗口(见 memory/README.md)。 */
+const MAX_AGENTS_IMPORT_CHARS = 20000;
+/**
+ * 工作区根 AGENTS.md 自动导入段:与 memory 开关完全无关——
+ * 只要 <cwd>/AGENTS.md 存在就把正文直接拼进 prompt(超 {@link MAX_AGENTS_IMPORT_CHARS} 截断+末尾提示),
+ * 不再只指路让模型按需 read_file。读失败静默跳过(返空串)。
+ */
+function buildAgentsImportSection() {
+    try {
+        const projectAgents = path.join(process.cwd(), 'AGENTS.md');
+        if (!fs.existsSync(projectAgents))
+            return '';
+        const content = fs.readFileSync(projectAgents, 'utf8').trim();
+        if (!content)
+            return '';
+        const body = content.length > MAX_AGENTS_IMPORT_CHARS
+            ? `${content.slice(0, MAX_AGENTS_IMPORT_CHARS)}\n…[AGENTS.md truncated: first ${MAX_AGENTS_IMPORT_CHARS} characters injected]`
+            : content;
+        return `\n## Project memory (AGENTS.md, auto-imported)\n${body}\n- AGENTS.md may be stale: current code and the user request override stale memory.`;
+    }
+    catch {
+        return ''; // 读失败静默跳过:不让导入破坏 prompt 构建
+    }
+}
+/**
+ * Memory 检索指导段(与 AGENTS.md 导入无关):开 isMemoryEnabled() 时才拼,
+ * 注入 memory_search/list/graph 的使用指导。默认关(新用户零侵入)。
+ */
 function buildMemoryPromptSection() {
     if (!isMemoryEnabled())
         return '';
-    const projectMocode = path.join(process.cwd(), 'MOCODE.md');
-    const mocodeHint = fs.existsSync(projectMocode)
-        ? '\n- `MOCODE.md` exists at the workspace root but is not preloaded. Read it with `read_file` only when the task may depend on project architecture, conventions, commands, prior decisions, or user preferences; skip it for greetings and unrelated simple requests. Current code and the user request override stale memory.'
-        : '';
-    return SYSTEM_PROMPT_MEMORY_SECTION + mocodeHint;
+    return SYSTEM_PROMPT_MEMORY_SECTION;
 }
 /**
  * plan 模式追加到系统提示末尾的指令(切到 plan 模式时由 repl 拼进 history[0])。
@@ -258,6 +319,7 @@ ${buildPlanResearchRules()}`;
 }
 /** 兼容旧名字:repl 的 buildSystemMessage 仍引 PLAN_MODE_SUFFIX(变量)。运行时按需现拼。 */
 export function buildBasePrompt(sessionId = getCurrentSessionId()) {
+    const agentsImportSection = buildAgentsImportSection();
     const memorySection = buildMemoryPromptSection();
     const notepadSection = buildNotepadSection(sessionId);
     // 静态主体:稳定段落集中在前,让支持 prompt caching 的后端能命中前缀缓存(#12)。
@@ -313,9 +375,9 @@ ${buildVoiceSection()}
 - **No flattery / no preamble in conclusions**: skip "Sure", "好的", "我已经完成了" and similar no-information prefixes — jump straight to substance.
 - Report honestly: say success when successful, say where you're stuck when failing, and mention anything skipped. Reference code in "path:line" format (e.g., src/index.ts:42). Keep it concise.
 ${t('assistant.languageInstruction')}`;
-    // 动态段(置于末尾):memory 索引 + notepad 索引 + notepad 使用说明。
+    // 动态段(置于末尾):AGENTS.md 项目记忆(无条件) + memory 索引(按开关) + notepad 索引 + notepad 使用说明。
     // 按需注入(#13):有内容的索引才拼对应标题,避免空标题噪声。
-    //   - "## Project context" 仅当 memorySection/notepadSection 非空(notepad 索引依赖 notes.md 存在);
+    //   - "## Project context" 仅当 agentsImportSection/memorySection/notepadSection 任一非空(notepad 索引依赖 notes.md 存在);
     //   - "## Session state" 使用说明**无条件**注入(放在动态尾段首位):否则会陷入"说明依赖 notes.md 存在 → 模型不知要建 → 文件永不存在"的鸡生蛋循环,功能对模型不可见。动态段在静态前缀之后,不影响 prompt 缓存。
     const dynamicParts = [];
     // 会话级私有尾段(子 agent 切片会丢弃):Session state 说明无条件注入在前,Project context 按需在后。
@@ -333,8 +395,10 @@ ${t('assistant.languageInstruction')}`;
         'Keep at most one step in_progress, and mark a step completed as soon as its work is done — do not batch updates to the end of the turn. ' +
         'Write each step so a teammate who lost the conversation could pick it up cold: name the file or symbol, the exact change, and the verification, so the plan survives context compaction. ' +
         'plan_update creates notes.md for you when the task warrants it; read_file the full notes.md whenever you need to recover context after compaction. ' +
-        'When every step is completed, plan_update settles the plan to `## Done:` automatically. Keep other notes concise and session-specific; use memory for stable cross-session facts.');
-    const ctxContent = `${memorySection}${notepadSection}`.trimEnd();
+        'When every step is completed, plan_update settles the plan to `## Done:` automatically. Keep other notes concise and session-specific; use memory for stable cross-session facts.\n' +
+        '## Session notes (resident memory)\n' +
+        'For non-obvious, lasting-value discoveries — subtle constraints, decisions with downstream impact, open questions blocking a choice, or risks affecting later steps — call `note_append` IMMEDIATELY when you make the discovery. The note is written to the same notes.md and its body is re-injected into the prompt automatically (within a 5k-token budget), surviving compaction so you keep remembering what you found/decided this session. Do NOT use it for routine progress (that is the plan) or stable cross-session facts (that is memory_save). Each call appends one item.');
+    const ctxContent = `${agentsImportSection}${memorySection}${notepadSection}`.trimEnd();
     if (ctxContent) {
         dynamicParts.push(`## Project context\n${ctxContent}`);
     }

package/dist/context/encoders/table.js

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

package/dist/i18n/index.js

@@ -18,7 +18,7 @@ const zhCN = {
     'commands.memoryOff': '关闭记忆子系统',
     'commands.memoryStatus': '查看当前开关与原理',
     'commands.memoryReflect': '手动触发后台记忆反思',
-    'commands.memoryInit': '扫描项目生成 MOCODE.md 项目记忆',
+    'commands.memoryInit': '扫描项目生成 AGENTS.md 项目记忆',
     'commands.subagent': '子 Agent 开关（默认关闭）',
     'commands.subagentOn': '开启子 Agent',
     'commands.subagentOff': '关闭子 Agent',
@@ -69,7 +69,7 @@ const zhCN = {
     'running.rollback': '回滚',
     'running.chooseTurn': '选择轮次…',
     'running.init': '初始化',
-    'running.generateMemory': '生成 MOCODE.md…',
+    'running.generateMemory': '生成 AGENTS.md…',
     'running.plan': '切 plan',
     'running.auto': '切 auto',
     'running.clear': '清空',
@@ -277,7 +277,7 @@ const en = {
     'commands.memoryOff': 'Disable the memory subsystem',
     'commands.memoryStatus': 'Show current state and behavior',
     'commands.memoryReflect': 'Run background memory reflection',
-    'commands.memoryInit': 'Scan project and generate MOCODE.md',
+    'commands.memoryInit': 'Scan project and generate AGENTS.md',
     'commands.subagent': 'Sub-agent controls (disabled by default)',
     'commands.subagentOn': 'Enable sub-agents',
     'commands.subagentOff': 'Disable sub-agents',
@@ -328,7 +328,7 @@ const en = {
     'running.rollback': 'Rollback',
     'running.chooseTurn': 'Choose a turn…',
     'running.init': 'Initialize',
-    'running.generateMemory': 'Generating MOCODE.md…',
+    'running.generateMemory': 'Generating AGENTS.md…',
     'running.plan': 'Plan mode',
     'running.auto': 'Auto mode',
     'running.clear': 'Clear',

package/dist/llm/index.js

@@ -180,7 +180,6 @@ export function refreshChatTools() {
     // MCP 协议没有可靠的副作用注解；plan 模式绝不暴露外部工具，保留只读探查保证。
     planChatTools.splice(0, planChatTools.length, ...next.filter((t) => !t.function.name.startsWith('mcp__') && !getPlanDisabledTools().has(t.function.name)));
 }
-refreshChatTools();
 /**
  * 多 provider 兼容的 cache / reasoning 字段提取。
  * 不同后端报 cached 字段名差异巨大,这里按"最常见的几种"顺序 probe,

package/dist/memory/discover.js

@@ -1,23 +1,23 @@
-// memory 发现子系统:加载项目记忆 MOCODE.md(对标 skills/discover.ts 的叶子模式)。
+// memory 发现子系统:加载项目记忆 AGENTS.md(对标 skills/discover.ts 的叶子模式)。
 // 仅依赖 node 标准库,是叶子模块:不依赖 config/agent/llm/tools/skills,避免环。
 //
-// 约定:纯 MOCODE.md(mocode 是独立工具,有自己的工具集与约定)。
-// 项目级从 cwd 向上逐级找,全局 ~/.mocode/MOCODE.md。全量注入 systemPrompt(超长截断);
+// 约定:纯 AGENTS.md(mocode 是独立工具,有自己的工具集与约定)。
+// 项目级从 cwd 向上逐级找,全局 ~/.mocode/AGENTS.md。全量注入 systemPrompt(超长截断);
 import { existsSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 /**
- * 返回要查找的 MOCODE.md 路径列表,按「远→近」顺序(合并时近的在后,更突出):
- * 全局 ~/.mocode/MOCODE.md → 项目级从根到 cwd 逐级 MOCODE.md。
+ * 返回要查找的 AGENTS.md 路径列表,按「远→近」顺序(合并时近的在后,更突出):
+ * 全局 ~/.mocode/AGENTS.md → 项目级从根到 cwd 逐级 AGENTS.md。
  * 向上遍历 cwd 到根收集 [cwd..root],反转为 [root..cwd](远→近),前拼全局。
  */
 export function resolveMemoryFiles() {
-    const globalPath = path.join(os.homedir(), '.mocode', 'MOCODE.md');
+    const globalPath = path.join(os.homedir(), '.mocode', 'AGENTS.md');
     const projectFiles = [];
     let dir = process.cwd();
     const root = path.parse(dir).root; // win32 'C:\\', POSIX '/'
     for (;;) {
-        projectFiles.push(path.join(dir, 'MOCODE.md'));
+        projectFiles.push(path.join(dir, 'AGENTS.md'));
         if (dir === root || dir === path.dirname(dir))
             break; // 到根:dirname 自身
         dir = path.dirname(dir);
@@ -26,7 +26,7 @@ export function resolveMemoryFiles() {
     return [globalPath, ...projectFiles];
 }
 /**
- * 读取所有存在的 MOCODE.md,返回 { path, content }(content 已 trim)。
+ * 读取所有存在的 AGENTS.md,返回 { path, content }(content 已 trim)。
  * 全程静默容错(不存在 / 读失败 → 跳过,不抛),风格对齐 skills/discover.ts 与 session/persist.ts。
  */
 export function loadMemoryFiles() {

package/dist/memory/index.js

@@ -1,6 +1,7 @@
 // Memory barrel: Tier-2 JSONL store + knowledge-graph layer + background reflection.
-// MOCODE.md is intentionally not loaded here: the system prompt only tells the agent
-// to read the workspace file on demand, keeping its full body out of every request.
+// AGENTS.md is intentionally not loaded here either: config/index.ts
+// (buildAgentsImportSection) auto-imports the workspace-root AGENTS.md body into the
+// system prompt — independent of the memory switch — truncating it when it exceeds the cap.
 export { buildMemoryIndexSection, loadAll, gcMemories, } from './store.js';
 export { addTriple, upsertEntity, findEntity, searchGraph, neighborsOf, pathBetween, graphStats, } from './graph.js';
 export { kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, runReflection, } from './reflect.js';

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, isSubAgentEnabled, updateSubAgentConfig, isFrontendToolsEnabled, updateFrontendToolsConfig, updateLanguageConfig, languageFromShell, buildBasePrompt, getPlanModeSuffix, hasCodegraphIndex, reinjectActivePlanIntoSystem, DEFAULT_CONTEXT_WINDOW_TOKENS, } from '../config/index.js';
+import { config, updateModelConfig, isModelConfigured, updateMemoryConfig, isMemoryEnabled, isSubAgentEnabled, updateSubAgentConfig, isFrontendToolsEnabled, updateFrontendToolsConfig, updateLanguageConfig, languageFromShell, buildBasePrompt, getPlanModeSuffix, hasCodegraphIndex, reinjectSessionStateIntoSystem, DEFAULT_CONTEXT_WINDOW_TOKENS, } from '../config/index.js';
 import { getLanguage, normalizeLanguage, t, } from '../i18n/index.js';
 import { DEFAULT_BUDGET_POLICY } from '../context/budget.js';
 import { updateConfigKey, writeConfigKeys, CONFIG_PATH } from '../config/file.js';
@@ -66,9 +66,9 @@ function buildSlashCommands() {
                 { name: 'off', value: '/memory_switch off', desc: d('commands.memoryOff') },
                 { name: 'status', value: '/memory_status', desc: d('commands.memoryStatus') },
                 { name: 'reflect', value: '/reflect', desc: d('commands.memoryReflect') },
-                { name: 'init', value: '/init', desc: d('commands.memoryInit') },
             ],
         },
+        { name: '/init', desc: d('commands.memoryInit') },
         {
             name: '/subagent', desc: d('commands.subagent'), children: [
                 { name: 'on', value: '/subagent on', desc: d('commands.subagentOn') },
@@ -173,7 +173,7 @@ function maskKey(k) {
     return `${'='.repeat(Math.min(k.length - 4, 20))}${k.slice(-4)}`;
 }
 /**
- * /init 指令:发给 agent 扫描项目并生成 MOCODE.md。已存在则让 agent 读后更新(不丢失事实)。写完供 memory 子系统下轮加载。
+ * /init 指令:发给 agent 扫描项目并生成 AGENTS.md。已存在则让 agent 读后更新(不丢失事实)。写完供 memory 子系统下轮加载。
  *
  * 函数化(非 const):.codegraph/ 索引是否存在的探测放在调用瞬间,没索引时不提 codegraph,
  * 避免 LLM 调出失败。/init 是冷启动动作,IO 开销可忽略。
@@ -182,14 +182,14 @@ function buildInitPrompt() {
     const cg = hasCodegraphIndex()
         ? '- 若有 .codegraph/:用 use_skill 加载 codegraph skill 后用 run_command 调 codegraph explore "<架构或入口符号>" 一次拿相关源码+调用路径,别逐文件读！！！\n'
         : '';
-    return `分析当前项目(process.cwd()),生成 MOCODE.md 项目记忆文件,供 mocode 后续会话自动加载——目标是让后续会话无需重新摸索就能上手。
+    return `分析当前项目(process.cwd()),生成 AGENTS.md 项目记忆文件,供 mocode 后续会话自动加载——目标是让后续会话无需重新摸索就能上手。
 
 先探查(尽量少调用拿全貌):
 ${cg}- read_file package.json(或 Cargo.toml/pyproject.toml/go.mod 等):scripts、依赖、入口、模块类型。
 - glob 顶层目录;read_file 入口文件 + 各子系统 index.ts/README。
-- 若 MOCODE.md 已存在:read_file 读它,在其基础上更新(补缺、修正过时),不丢已有准确事实。
+- 若 AGENTS.md 已存在:read_file 读它,在其基础上更新(补缺、修正过时),不丢已有准确事实。
 
-MOCODE.md 按以下结构写(每节简短,只写稳定、非显然的事实):
+AGENTS.md 按以下结构写(每节简短,只写稳定、非显然的事实):
 ## 项目
 一两句:是什么、技术栈、运行环境。
 ## 命令
@@ -204,7 +204,7 @@ install / dev / build / test / typecheck / lint 等——从 package.json script
 硬要求:
 - 从实际代码提炼,引用具体文件名/命令/符号;不编造、不泛泛。
 - 总长 ≤ 3000 字;只写后续会话有用的稳定事实,不写易变项(当前 bug、临时文件、未决 TODO)。
-- 用 write_file 写入项目根 MOCODE.md。
+- 用 write_file 写入项目根 AGENTS.md。
 - 写完简述:写了哪几节 + 从代码里发现的 2-3 条非显然关键约定(供用户校验)。`;
 }
 /** 临时 readline 读一行(cooked,用于子提问;主输入走 promptWithSlashMenu)。 */
@@ -768,7 +768,7 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
     //
     // 与开关联动:① base 用 buildBasePrompt() 取代 config.systemPrompt(后者是启动时一次性
     // 求值的常量,运行时 /memory_switch 不会刷新);② plan suffix 走 getPlanModeSuffix() 现拼;
-    // ③ MOCODE.md 只在 base 中提示按需 read_file，不注入正文；④ Memory Index 按开关注入。
+    // ③ AGENTS.md 存在工作区根时由 base 无条件自动导入正文(超长截断，与 memory 开关无关)；④ Memory Index 按开关注入。
     const buildSystemMessage = (planMode) => effectiveSystemPrompt(buildBasePrompt(currentSessionId) +
         (planMode ? getPlanModeSuffix() : '') +
         buildMemoryIndexSection(isMemoryEnabled()));
@@ -1199,7 +1199,7 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             continue;
         }
         if (line === '/init') {
-            // /init:把 init 指令当 user 输入发给 agent(扫描项目 + 生成 MOCODE.md),fall through 走 runAgent
+            // /init:把 init 指令当 user 输入发给 agent(扫描项目 + 生成 AGENTS.md),fall through 走 runAgent
             joined = buildInitPrompt();
         }
         if (line === '/upgrade' || line.startsWith('/upgrade ')) {
@@ -1438,7 +1438,7 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
                 layout.contentWrite(`  ${ui.accent}${e.id}${ui.reset}  ${ui.dim}${e.name} — ${e.summary}${ui.reset}\n`);
             }
             if (active.length === 0)
-                layout.contentWrite(`${ui.dim}(无 active 记忆;用 memory_save 存,或 /init 生成 MOCODE.md)${ui.reset}\n`);
+                layout.contentWrite(`${ui.dim}(无 active 记忆;用 memory_save 存,或 /init 生成 AGENTS.md)${ui.reset}\n`);
             layout.contentWrite(`${ui.dim}(详情用 memory_search;启动索引已注入 systemPrompt)${ui.reset}\n`);
             continue;
         }
@@ -1545,9 +1545,9 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
             // focus 透传到 compact_history action 的 LLM 摘要 prompt。
             // 返回 SchedulerRunLog 给 UI 显示决策;退化路径(开关关时)在 manualCompact 内部走 compactHistory。
             const log = await manualCompact(history, focus, { force });
-            // ② compact 后把活跃 plan 重注入系统提示（history[0]），避免 agent 因上下文压缩丢失执行计划。
+            // ② compact 后把会话状态(plan + 笔记段)重注入系统提示（history[0]），避免 agent 因上下文压缩丢失计划与笔记。
             if (log.compactHistoryCalled)
-                reinjectActivePlanIntoSystem(history);
+                reinjectSessionStateIntoSystem(history);
             const d = log.compactDetail;
             appendCurrentSessionRuntimeEvent('compact', {
                 source: 'manual',

package/dist/session/notes.js

@@ -105,3 +105,236 @@ export function writePlanToNotes(plan, sessionId = getCurrentSessionId()) {
     }
     return { path: p, settled: plan.steps.length > 0 && plan.steps.every((s) => s.status === 'completed') };
 }
+// ── Session notes(单会话永久记忆):note_append 写入,reinject 常驻 system ──────
+// 设计:notes.md 不止放 Plan。note_append 往预设笔记段追加一条 finding/decision/
+// open_question/risk;extractActiveNotesSections 读出活跃笔记段正文(排除 Plan/Done),
+// 按 5k token 预算裁剪后由 reinjectSessionStateIntoSystem 注入 system prompt——compact
+// 后仍能恢复,让 agent 始终记得本会话做过什么、发现过什么(单会话永久记忆)。
+/** note_append 接受的预设段 key → 渲染标题。 */
+const NOTE_SECTION_TITLES = {
+    findings: 'Findings',
+    decisions: 'Decisions',
+    open_questions: 'Open Questions',
+    risks: 'Risks',
+};
+/** 预设段 key 列表(供工具 schema enum 与校验用)。 */
+export const NOTE_SECTION_KEYS = Object.keys(NOTE_SECTION_TITLES);
+/** 段注入优先级:数值越大越先占预算、越后丢弃正文。Risks 最重要。 */
+const SECTION_PRIORITY = {
+    risks: 4, findings: 3, decisions: 2, open_questions: 1,
+};
+/** 常驻笔记正文总预算(token)。5k:占百万级 context 的 0.5%,可常驻相当量笔记。 */
+const NOTES_INJECT_BUDGET_TOKENS = 5000;
+/** 单段正文上限(token):防单段独占预算。 */
+const NOTES_PER_SECTION_TOKENS = 2000;
+/** 单条笔记上限(token):防一条过长吃掉整段预算。 */
+const NOTES_PER_ENTRY_TOKENS = 800;
+/**
+ * 轻量 token 估算(启发式,不依赖 tokenizer):CJK ≈ 0.6 token/字,
+ * ASCII ≈ 0.25 token/字。对 GLM/DeepSeek/Qwen 等中文偏多的后端略偏保守
+ * (估算略高于实际 → 注入实际 token 略低于预算 → 安全侧)。仅供笔记 cap 用,
+ * 不替换 llm/estimatePromptTokens 的主口径。
+ */
+function estimateTokens(text) {
+    let cjk = 0;
+    let other = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if ((c >= 0x3000 && c <= 0x9fff) || (c >= 0xff00 && c <= 0xffef))
+            cjk++;
+        else
+            other++;
+    }
+    return Math.ceil(cjk * 0.6 + other * 0.25);
+}
+/** 把标题映射回预设 key(非预设段返 '',优先级 0,最后注入)。 */
+function matchSectionKey(title) {
+    const t = title.trim().toLowerCase();
+    for (const [k, v] of Object.entries(NOTE_SECTION_TITLES)) {
+        if (v.toLowerCase() === t)
+            return k;
+    }
+    return '';
+}
+/**
+ * 往 notes.md 的指定笔记段追加一条。段存在则在其末尾追加(保留其它段不动);
+ * 段不存在则在文件末新建。返回 { path } 或 { error }。
+ */
+export function appendNoteToSection(section, entry, tag, sessionId = getCurrentSessionId()) {
+    const title = NOTE_SECTION_TITLES[section];
+    if (!title)
+        return { error: `unknown note section "${section}"` };
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return { error: 'no active session' };
+    const line = tag ? `- **[${tag}]** ${entry}` : `- ${entry}`;
+    let existing = '';
+    try {
+        existing = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+    }
+    catch {
+        existing = '';
+    }
+    const header = `## ${title}`;
+    const lines = existing.split('\n');
+    const start = lines.findIndex((l) => l.trim() === header);
+    let next;
+    if (start >= 0) {
+        // 段末 = 下一个 ## 或文件末
+        let end = lines.length;
+        for (let k = start + 1; k < lines.length; k++) {
+            if (/^##\s/.test(lines[k])) {
+                end = k;
+                break;
+            }
+        }
+        const before = lines.slice(0, start).join('\n').replace(/\s+$/, '');
+        const sectionLines = lines.slice(start, end);
+        // 去段尾空行后追加新条目
+        while (sectionLines.length && sectionLines[sectionLines.length - 1].trim() === '')
+            sectionLines.pop();
+        sectionLines.push(line);
+        const section = sectionLines.join('\n');
+        const after = lines.slice(end).join('\n').replace(/^\s+/, '');
+        next = [before, section, after].filter((s) => s.length > 0).join('\n\n') + '\n';
+    }
+    else {
+        // 新建段:放文件末,与已有内容以空行分隔
+        const rest = existing.trim();
+        const newSection = `${header}\n${line}`;
+        next = rest ? `${rest}\n\n${newSection}\n` : `${newSection}\n`;
+    }
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, next, 'utf8');
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    return { path: p };
+}
+/** 按字符二分截断条目到 token 上限,加省略标记。条目不长,线性二分足够。 */
+function truncateEntry(entry, maxTokens) {
+    if (estimateTokens(entry) <= maxTokens)
+        return entry;
+    let lo = 0;
+    let hi = entry.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (estimateTokens(entry.slice(0, mid)) <= maxTokens)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return entry.slice(0, lo).replace(/\s+$/, '') + ' …[truncated]';
+}
+/** 把单段正文按条目分割,从末尾(最近)保留,丢最旧,裁到 token 预算内。 */
+function trimSectionToBudget(body, budgetTokens) {
+    if (budgetTokens <= 0)
+        return null;
+    const bodyLines = body.split('\n');
+    const header = bodyLines[0] ?? '';
+    const rest = bodyLines.slice(1);
+    // 分条目:以 "- " 开头为一条起始,后续非 "- " 行归入该条
+    const entries = [];
+    let cur = [];
+    for (const ln of rest) {
+        if (/^-\s+/.test(ln)) {
+            if (cur.length)
+                entries.push(cur.join('\n'));
+            cur = [ln];
+        }
+        else {
+            cur.push(ln);
+        }
+    }
+    if (cur.length)
+        entries.push(cur.join('\n'));
+    const kept = [];
+    let used = estimateTokens(header);
+    for (let k = entries.length - 1; k >= 0; k--) {
+        let e = entries[k];
+        if (estimateTokens(e) > NOTES_PER_ENTRY_TOKENS) {
+            e = truncateEntry(e, NOTES_PER_ENTRY_TOKENS);
+        }
+        const t = estimateTokens(e);
+        if (used + t > budgetTokens)
+            break;
+        kept.unshift(e);
+        used += t;
+    }
+    if (kept.length === 0)
+        return null;
+    return `${header}\n${kept.join('\n')}`;
+}
+/**
+ * 读 notes.md,提取所有活跃笔记段正文(排除 `## Plan:` 与 `## Done:`),
+ * 按 NOTES_INJECT_BUDGET_TOKENS 裁剪后返回——供 reinject 注入 system prompt。
+ * 裁剪策略:段按优先级排序(Risks>Findings>Decisions>Open Questions>自定义),
+ * 逐段注入累计 token;单段超 per-section 则段内从最近条目保留丢最旧;
+ * 总预算用尽则后续段不注入正文(其标题仍由 buildNotepadSection 索引常驻,
+ * agent 可 read_file 取细节)。这样 5k 预算内"写了就常驻",超出降级为索引+按需 read。
+ */
+export function extractActiveNotesSections(budget = NOTES_INJECT_BUDGET_TOKENS, sessionId = getCurrentSessionId()) {
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return '';
+    let content = '';
+    try {
+        content = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+    }
+    catch {
+        return '';
+    }
+    const lines = content.split('\n');
+    const sections = [];
+    let i = 0;
+    while (i < lines.length) {
+        const m = lines[i].match(/^##\s+(.+?)\s*$/);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const title = m[1];
+        // 跳过 Plan/Done 段(Plan 有专属 ACTIVE_PLAN_MARKER 重注入;Done 是归档不常驻)
+        if (/^Plan:/.test(title) || /^Done:/.test(title)) {
+            i++;
+            while (i < lines.length && !/^##\s/.test(lines[i]))
+                i++;
+            continue;
+        }
+        const start = i;
+        i++;
+        while (i < lines.length && !/^##\s/.test(lines[i]))
+            i++;
+        const body = lines.slice(start, i).join('\n').trim();
+        if (body)
+            sections.push({ key: matchSectionKey(title), body });
+    }
+    // 按优先级降序(优先级高的先占预算)
+    sections.sort((a, b) => (SECTION_PRIORITY[b.key] ?? 0) - (SECTION_PRIORITY[a.key] ?? 0));
+    let used = 0;
+    const out = [];
+    for (const s of sections) {
+        const remaining = budget - used;
+        if (remaining <= 0)
+            break;
+        const bodyTokens = estimateTokens(s.body);
+        if (bodyTokens <= Math.min(remaining, NOTES_PER_SECTION_TOKENS)) {
+            out.push(s.body);
+            used += bodyTokens;
+            continue;
+        }
+        // 段超预算:段内裁条目(从最近保留)
+        const cap = Math.min(remaining, NOTES_PER_SECTION_TOKENS);
+        const trimmed = trimSectionToBudget(s.body, cap);
+        if (trimmed) {
+            out.push(trimmed);
+            used += estimateTokens(trimmed);
+        }
+        // 预算用尽则后续段不再注入正文(降级为索引)
+        if (used >= budget)
+            break;
+    }
+    return out.join('\n\n');
+}

package/dist/skills/runner.js

@@ -144,7 +144,6 @@ const WRITE_TOOLS = new Set(['write_file', 'edit_file', 'run_command']);
  * fork 子 agent 模式:`agent:` 显式声明优先;否则按工具面推断——
  * 未声明 allowed-tools(完整工具集)或白名单含写工具 → 'write',纯只读白名单 → 'read'。
  * 避免写类 skill 因缺省字段被静默降级为只读。
- * 导出仅供 scripts/check-skills.ts 离线断言。
  */
 export function resolveSpawnMode(skill, tools) {
     if (skill.agentMode)

package/dist/tools/builtins/index.js

@@ -14,6 +14,7 @@ import { useSkillTool } from './use-skill.js';
 import { runSkillTool } from './run-skill.js';
 import { askHumanTool } from './ask-human.js';
 import { planUpdateTool } from './plan-update.js';
+import { noteAppendTool } from './note-append.js';
 import { memorySaveTool } from './memory-save.js';
 import { memorySearchTool } from './memory-search.js';
 import { memoryListTool } from './memory-list.js';
@@ -68,6 +69,8 @@ const CAPABILITIES = {
     // plan_update 只写内部 notes.md(session 工作面),不作为用户代码 mutation 追踪/回滚/diff;
     // 串行即可(调用不频繁),固定资源键让并发调用排队。
     plan_update: { effect: 'write', concurrency: 'serial', resources: () => ['session-notepad'] },
+    // note_append 与 plan_update 同款:只写内部 notes.md 笔记段,不作 project mutation 追踪/diff/回滚;串行 + 固定资源键排队。
+    note_append: { effect: 'write', concurrency: 'serial', resources: () => ['session-notepad'] },
     memory_save: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_search: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_list: { effect: 'read', concurrency: 'serial', resources: memoryResource },
@@ -103,6 +106,7 @@ const rawBuiltinTools = [
     runSkillTool,
     askHumanTool,
     planUpdateTool,
+    noteAppendTool,
     ..._memoryTools,
     subAgentTool,
 ];

package/dist/tools/builtins/note-append.js

@@ -0,0 +1,103 @@
+import { appendNoteToSection, NOTE_SECTION_KEYS } from '../../session/notes.js';
+/**
+ * note_append:往会话笔记 notes.md 的预设笔记段追加一条 finding/decision/
+ * open_question/risk。与 plan_update 的边界:
+ *  - plan_update 维护执行计划(步骤进度),写 `## Plan:` 段;
+ *  - note_append 记发现/决策/问题/风险,写 `## Findings` 等笔记段。
+ * 写入的笔记正文会由 reinject 注入 system prompt 并常驻(5k token 预算内),
+ * compact 后仍可恢复——构成单会话永久记忆。与 memory_* 的边界:
+ *  - note_append 记本会话内、抗 compact 的笔记;
+ *  - memory_* 记跨会话稳定事实(另一系统,默认关)。
+ *
+ * 仿 plan_update:risk=safe,免权限/免 diff/免回滚;capabilities 由 builtins/index.ts
+ * 声明为 session-notepad 资源串行(与 plan_update 同款)。
+ */
+function err(message) {
+    return { status: 'error', code: 'INVALID_ARGUMENTS', retryable: false, output: `错误:${message}` };
+}
+/** 归一化 section:兼容单复数、下划线/空格/连字符、大小写偏差。 */
+function normalizeSection(raw) {
+    const s = String(raw ?? '').trim().toLowerCase().replace(/[-\s]+/g, '_');
+    if (NOTE_SECTION_KEYS.includes(s))
+        return s;
+    // 单数/别名归一
+    if (['finding', 'find', 'insight', 'insights'].includes(s))
+        return 'findings';
+    if (['decision', 'decide', 'choice', 'choices'].includes(s))
+        return 'decisions';
+    if (['open_question', 'question', 'questions', 'openquestion', 'openquestions'].includes(s))
+        return 'open_questions';
+    if (['risk', 'hazard', 'caveat', 'caveats'].includes(s))
+        return 'risks';
+    return null;
+}
+export const noteAppendTool = {
+    name: 'note_append',
+    description: 'Append a decision-grade note (a finding, decision, open question, or risk) to the session notepad ' +
+        '(`.mocode/sessions/<id>/notes.md`) so it survives context compaction and stays resident in the prompt. ' +
+        'Use this for NON-OBVIOUS, lasting-value discoveries — subtle constraints, decisions with downstream impact, ' +
+        'open questions that block a choice, or risks that affect later steps. Do NOT use it for routine progress ' +
+        '(that is the plan via `plan_update`) or for stable cross-session facts (that is `memory_save`). ' +
+        'Notes you write here persist across compaction within this session and are re-injected into the prompt ' +
+        'automatically, so the agent keeps remembering what it found/decided. Call it the moment you make the ' +
+        'discovery or decision — do not batch to the end.',
+    risk: 'safe',
+    parameters: {
+        type: 'object',
+        properties: {
+            section: {
+                type: 'string',
+                enum: NOTE_SECTION_KEYS,
+                description: 'Note category: findings (a non-obvious discovery/constraint), decisions (a choice with ' +
+                    'lasting impact), open_questions (a blocker needing resolution), risks (a hazard affecting later work).',
+            },
+            entry: {
+                type: 'string',
+                description: 'The note text. One concise, self-contained item: what was found/decided and why it matters. ' +
+                    'Keep each call to one item — call again for a second item.',
+            },
+            tag: {
+                type: 'string',
+                description: 'Optional short label for grouping (e.g. "parser-bug", "api-shape"). Rendered as **[tag]**.',
+            },
+        },
+        required: ['section', 'entry'],
+        additionalProperties: false,
+    },
+    // 兼容模型的 section 命名偏差:单复数/分隔符/别名归一到预设 key。
+    normalizeArguments(args) {
+        const s = normalizeSection(args.section);
+        if (s)
+            args.section = s;
+        if (typeof args.tag === 'string')
+            args.tag = args.tag.trim();
+    },
+    async execute(args) {
+        const section = normalizeSection(args.section);
+        if (!section) {
+            return err(`section 非法:"${String(args.section ?? '')}"(仅 ${NOTE_SECTION_KEYS.join('/')} 或常见别名)。`);
+        }
+        const entry = String(args.entry ?? '').trim();
+        if (!entry)
+            return err('entry 不能为空。');
+        if (entry.length > 2000) {
+            return err(`entry 过长(${entry.length} 字符,上限 2000)——拆成多条 note_append 或精简。`);
+        }
+        const tag = typeof args.tag === 'string' && args.tag.trim() ? args.tag.trim() : undefined;
+        const result = appendNoteToSection(section, entry, tag);
+        if ('error' in result) {
+            return { status: 'error', code: 'EXECUTION_ERROR', retryable: false, output: `错误:写入 notes.md 失败: ${result.error}` };
+        }
+        // note_append 写内部 notes.md,不作为用户代码 mutation 上报 changedFiles(与 plan_update 一致)。
+        const titleMap = {
+            findings: 'Findings', decisions: 'Decisions', open_questions: 'Open Questions', risks: 'Risks',
+        };
+        const rendered = tag ? `- **[${tag}]** ${entry}` : `- ${entry}`;
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            output: `已追加笔记到 ## ${titleMap[section]} 段(将常驻 prompt,抗 compact):\n${rendered}`,
+        };
+    },
+};

package/dist/tools/registry.js

@@ -11,6 +11,11 @@ import { isToolErrorOutput } from './result.js';
  */
 const extensions = new Map();
 export const tools = [...builtinTools];
+/** 名字 → 工具 的 O(1) 索引，与 tools 数组在每次 rebuild 时同步重建；findTool 走此索引。 */
+let toolIndex = buildToolIndex(tools);
+function buildToolIndex(list) {
+    return new Map(list.map((tool) => [tool.name, tool]));
+}
 export function registerToolsExtension(sourceOrAdditions, maybeAdditions) {
     const source = typeof sourceOrAdditions === 'string' ? sourceOrAdditions : 'external';
     const additions = typeof sourceOrAdditions === 'string' ? (maybeAdditions ?? []) : sourceOrAdditions;
@@ -35,13 +40,14 @@ function rebuildTools() {
         next.push(tool);
     }
     tools.splice(0, tools.length, ...next);
+    toolIndex = buildToolIndex(next);
 }
 const DEFAULT_CAPABILITIES = Object.freeze({
     effect: 'unknown',
     concurrency: 'serial',
 });
 export function findTool(name) {
-    return tools.find((tool) => tool.name === name);
+    return toolIndex.get(name);
 }
 /** 缺少声明或找不到工具时返回保守能力，绝不把未知扩展并发执行。 */
 export function getToolCapabilities(toolOrName) {
@@ -58,10 +64,13 @@ export function getToolResourceKeys(toolOrName, args) {
     }
 }
 /** resource-locked write 是可生成文件 diff/按路径记 rollback 的文件 mutation。 */
-export function isFileMutationTool(name) {
-    const capabilities = getToolCapabilities(name);
+export function isFileMutationCapabilities(capabilities) {
     return capabilities.effect === 'write' && capabilities.concurrency === 'resource-locked';
 }
+/** 按工具名判定(兼容入口);热路径请直接复用已解析的 capabilities 走 isFileMutationCapabilities。 */
+export function isFileMutationTool(name) {
+    return isFileMutationCapabilities(getToolCapabilities(name));
+}
 function isStructuredOutcome(value) {
     return typeof value === 'object' && value !== null &&
         typeof value.status === 'string' && typeof value.code === 'string' &&
@@ -144,7 +153,7 @@ async function executeToolOnce(tool, args, signal, opts) {
             mutationVersionBefore = mutationBefore.version;
             // Transactional tools own their full write-set capture inside ChangeSet commit.
             const pathCapture = !capabilities.delegatesResourceLocks &&
-                isFileMutationTool(tool.name) && typeof args.path === 'string' && args.path
+                isFileMutationCapabilities(capabilities) && typeof args.path === 'string' && args.path
                 ? beginPathMutation(args.path)
                 : null;
             capturedPath = pathCapture?.path;

package/dist/ui/diff.js

@@ -254,7 +254,7 @@ export function renderFileChange(opts) {
 /** 头行 + 计数行 + 正文(折叠 + 截断 + 行号),每行尾 \n。 */
 function renderBody(head, counts, items, padW, startLine, lang) {
     const lines = [head, counts];
-    const metaPrefix = `${BODY_INDENT}${' '.repeat(padW)}   `; // 对齐到代码列(num + 空格 + gutter + 空格)
+    const metaPrefix = `${BODY_INDENT}`; // 与正文行左对齐(batch 展开时还会再加外层 indent,避免双重缩进导致提示行突兀)
     let oldLine = startLine;
     let newLine = startLine;
     let shown = 0;

package/dist/ui/layout.js

@@ -1936,7 +1936,7 @@ function renderDimInputRow(prompt, text, placeholder, cols) {
 /**
  * 单行运行态滑窗:以光标为中心,向左右扩展填满 contentW-1(留 1 cell 给光标),
  * 返回可见子串与光标在子串内的显示列。保证光标恒可见,且不软折行(运行态输入框恒单行,
- * 不触发 setRegion/ED,避免流式期间底栏抖动——见 scripts/check-layout.ts 断言)。
+ * 不触发 setRegion/ED,避免流式期间底栏抖动)。
  */
 function windowSingleLine(text, cursor, contentW) {
     const n = text.length;

package/dist/ui/render.js

@@ -2,7 +2,13 @@ import { stdout } from 'node:process';
 import { createRequire } from 'node:module';
 import { ui } from './theme.js';
 import { t } from '../i18n/index.js';
-const VERSION = createRequire(import.meta.url)('../../package.json').version;
+let VERSION = '0.0.0';
+try {
+    VERSION = createRequire(import.meta.url)('../../package.json').version;
+}
+catch {
+    // 非标准布局(测试编译产物、自定义打包)不含 package.json:版本号回落,不阻断模块加载。
+}
 /**
  * 清空整屏 + 滚动缓冲(向上滚动可见的历史输出),光标归位。
  * 进入会话时调用,让终端只剩当前 agent 对话。非 TTY 时空操作。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {
@@ -21,7 +21,8 @@
   "scripts": {
     "start": "tsx src/index.ts",
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit && tsc -p evals/tsconfig.json",
+    "test": "tsc -p tsconfig.test-build.json && node --test --experimental-test-isolation=none \"dist-tests/tests/*.test.js\"",
+    "typecheck": "tsc --noEmit && tsc -p tests/tsconfig.json && tsc -p evals/tsconfig.json",
     "eval:smoke": "tsx evals/smoke.ts && tsx evals/coding/smoke.ts",
     "eval:coding": "tsx evals/coding/runner.ts",
     "eval:coding:list": "tsx evals/coding/runner.ts --list",