mocode-ai 0.4.9 → 0.5.0

package/README.md

@@ -18,6 +18,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.
 - **Automatic context compression** — As the context window fills up, a three-tier compression kicks in (trim individual results → compact older tool results in place → summarize older turns), so long sessions never overflow. `/context` shows live token usage; `/compact` triggers manual compression (optionally with a focus hint to preserve what matters).
 - **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 (Snapshot + Skill)** — Two complementary systems help the agent understand your project: **Project Snapshot** automatically scans files and generates LLM-enhanced summaries (project description, tech stack, commands, module responsibilities, directory tree); **Project Skill** is a manually maintained knowledge base capturing design decisions, architectural insights, pitfalls, and conventions. Snapshot provides *what/where* (facts), Skill provides *why/how* (insights) — no duplication, ~46% token savings.
 - **Working notepad (todolist)** — For complex multi-step tasks (≥3 file changes / ≥5 tool calls), the agent first writes a plan to `.mocode/plans/<id>.md` (file-based, survives context compression), then ticks each step as it goes. A live progress chip in the TUI status bar shows `plan: [title] (3/7) ▸ [current step]`. `finish` auto-archives completed plans to `plans/archive/`, with explicit `list / delete / unarchive` actions.
 - **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.
@@ -174,6 +175,8 @@ The five `memory_*` tools are gated on `MEMORY_ENABLED=true` at startup; toggle
 | `/pet`              | Toggle the optional desktop pet (floating window mirroring agent state) |
 | `/pet skin`         | Pick a pet skin (↑↓ · Enter)                                          |
 | `/pet quit`         | Fully shut down the pet process (not just disconnect)                 |
+| `/snapshot_refresh` | Refresh project snapshot (re-scan files + regenerate LLM summary)     |
+| `/snapshot`         | Toggle project snapshot on/off                                        |
 
 Type `/` to trigger the dropdown menu, keep typing to filter; Esc to cancel.
 
@@ -201,6 +204,21 @@ MoCode automatically scans the following directories for skills (each skill is a
 
 A skill's `description` is injected into the system prompt (progressive disclosure, tier 1); the model calls `use_skill` to load the full body (tier 2) only when the task is relevant. Use `/skills` to see discovered skills.
 
+## Project Context (Snapshot + Skill)
+
+MoCode uses two complementary systems to help the agent understand your project:
+
+- **Project Snapshot** (automatic + LLM-enhanced): Scans your project files and generates a structured summary including project description, tech stack, key commands, module responsibilities, and directory tree. Built automatically on startup (Phase 1: sync scan ~100ms, Phase 2: async LLM summary ~5s). Stored in `.mocode/snapshot.json`, reused across sessions. Refresh manually with `/snapshot_refresh` after major changes.
+- **Project Skill** (manual + AI-assisted): A knowledge base you maintain capturing insights the agent can't auto-discover — design decisions, architectural patterns, pitfalls, conventions, and development workflow notes. Initialize with `/init` (AI explores your project and drafts the initial content), then edit `.mocode/project-skill.md` to refine. Update via the `project_skill_update` tool during conversations.
+
+**Complementary principle**: Snapshot provides *what/where* (facts: files, structure, commands), Skill provides *why/how* (insights: decisions, behaviors, gotchas). No duplication, ~46% token savings compared to the previous approach.
+
+Both are enabled by default. Control via environment variables:
+- `MOCODE_PROJECT_SNAPSHOT=false` — disable snapshot
+- `MOCODE_PROJECT_SKILL=false` — disable skill
+
+See [docs/USAGE_SNAPSHOT_SKILL.md](./docs/USAGE_SNAPSHOT_SKILL.md) for detailed usage.
+
 ## Project memory (MOCODE.md)
 
 MoCode has a **two-tier memory** model distinct from skills:

package/dist/agent/core.js

@@ -74,10 +74,13 @@ function readDiffContext(tc, parsed) {
         }
     }
     if (tc.name === 'edit_file') {
-        const oldStr = String(parsed.old_string ?? '');
+        // 行尾归一化:LLM 生成的 old_string 用 LF(\n),但 Windows 文件可能是 CRLF(\r\n),
+        // 不统一则 indexOf 必败、editStartLine 恒为 1。与 edit-file.ts 保持一致归一化为 LF。
+        const oldStr = String(parsed.old_string ?? '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
         try {
             // jailResolve:同上,沙箱越界抛错 → catch 兜底,不泄露牢外内容
-            const data = readFileSync(jailResolve(p), 'utf8');
+            const raw = readFileSync(jailResolve(p), 'utf8');
+            const data = raw.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
             const idx = oldStr ? data.indexOf(oldStr) : -1;
             return {
                 preWriteOld: null,
@@ -190,6 +193,10 @@ export async function runAgentCore(opts) {
     let mode = 'idle';
     let gotText = false;
     let lastChar = '';
+    // 早退重探:本 turn 已执行过工具但模型突然返回无工具调用 + 极短/空文本 → 推一条提示让模型继续,
+    // 而非直接退出。每 turn 最多触发 1 次,防死循环。弱模型在探索中途偶尔"说完"即此兜底。
+    let nudgeCount = 0;
+    let hadToolsThisTurn = false;
     const onText = (s) => {
         hooks.onText?.(s); // 主 agent:走 markdown 渲染写内容区
         mode = 'text';
@@ -259,6 +266,7 @@ export async function runAgentCore(opts) {
             // lastUsage 已更新:触发状态行 context 用量条重算+重画,运行中不再冻结在轮首。
             onContextUpdate?.();
             if (result.toolCalls.length > 0) {
+                hadToolsThisTurn = true;
                 // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
                 if (mode !== 'idle' && lastChar !== '\n')
                     hooks.onTextEnd?.();
@@ -435,6 +443,19 @@ export async function runAgentCore(opts) {
             }
             if (mode !== 'idle' && lastChar !== '\n')
                 hooks.onTextEnd?.(); // 流式末尾补换行
+            // 早退保护:本 turn 已执行过工具调用,但模型突然返回无工具 + 极短/空文本 → 很可能是在探索中途
+            // 提前"说完了"。此时推一条 user 提示消息让模型继续探索,而非直接退出。每 turn 最多 1 次,防死循环。
+            // 判定标准:无 gotText(完全没输出)或正文极短(< 80 字符,通常是一句"我需要更多信息"级别的截断)。
+            const textLen = result.content?.trim().length ?? 0;
+            if (hadToolsThisTurn && nudgeCount < 1 && (!gotText || textLen < 80)) {
+                nudgeCount++;
+                history.push({ role: 'assistant', content: result.content });
+                history.push({
+                    role: 'user',
+                    content: 'You stopped before completing the task. Please continue investigating — call more tools if needed, or provide a complete answer based on what you have gathered so far.',
+                });
+                continue; // 带着提示再调一次 LLM
+            }
             // 没有工具调用:流式正文即最终回复(已实时打印)
             if (!gotText)
                 hooks.onNoReply?.();

package/dist/agent/index.js

@@ -47,7 +47,7 @@ function writeToolResult(tc, output, parsed, preWriteOld, editStartLine) {
         });
     }
     const preview = diff ? '' : summarizeToolResult(tc.name, output);
-    batch.recordResult(currentBatchId, tc.name, preview, diff);
+    batch.recordResult(currentBatchId, tc.name, preview, diff, output);
 }
 /**
  * agent 核心循环(主 agent,TUI 渲染版):

package/dist/config/index.js

@@ -90,9 +90,8 @@ function buildSnapshotSection() {
         const snap = loadSnapshot();
         if (!snap)
             return '';
-        const fileList = Object.keys(snap.files).join(', ');
-        const modules = snap.structure.modules.length ? snap.structure.modules.join(', ') : '(none)';
-        return `\n## Project Snapshot (cross-session cache)\n- A project snapshot is available with cached static files: [${fileList}]. read_file for these files will hit the snapshot cache (mtime-verified) — no disk read needed.\n- Project structure — top-level modules: [${modules}].\n- You already know the project skeleton; don't read_file these cached files just to "get an overview".\n- Use cached content directly: when a question can be answered from the cached files above (e.g. dependencies → package.json, compiler options → tsconfig.json, env vars → .env.example, project intro → README.md), answer from the snapshot without calling read_file.\n- The module list above is a navigation aid: when locating files, prefer targeted \`glob\` into the relevant module (e.g. \`src/**/*.ts\`) over broad top-level scans.\n`;
+        // 快照内容已经是完整的 markdown，直接返回
+        return `\n${snap.content}\n`;
     }
     catch {
         return '';
@@ -201,7 +200,7 @@ ${PLATFORM_NOTE}
 - Use glob to find file paths, grep to search content. **Don't use run_command for file-level checks** (existence / listing / type) — those have no clean cmd.exe equivalent and Windows path escaping fails often. Use \`glob\` to list, and just call \`read_file\` to test existence (returns ENOENT as a clean error string).
 - run_command has side effects on the host — state intent before invoking (delete, install, push, reset, etc.).
 - Call ask_human when you hit a decision point requiring user input (multiple implementation approaches, unclear intent, or needing extra info to proceed) — list options for the user to pick (they can also choose "custom input" to answer freely). Don't call it frequently when the task is clear and you can decide yourself; if the user cancels, switch approach or proceed with available info — don't re-ask the same question.
-- **Trim context when stale**: when an old tool result is dead weight (sub-goal done, no downstream consumer, or superseded by a later read), call drop_context to stub it; otherwise rely on automatic pruning.
+- **Trim context when stale**: when an old tool result is dead weight (sub-goal done, no downstream consumer, or superseded by a later read), call drop_context to stub it; otherwise rely on automatic pruning. **When your context gets too long, don't hesitate to use drop_context proactively** — it's cheap and designed to be called, not saved for emergencies.
 - **Batch writes and commands too, not just reads**: the executor runs ALL returned tool_calls (reads, writes, commands) before the next LLM call. Emit independent edit_file / write_file / run_command in one response when the chain is clear — don't serialize them across turns just because they have side effects. (The read-only batching note in Step Economy applies to writes the same way.)
 - **Chain shell workflows in a single \`run_command\`**: use \`&&\`, \`;\`, \`|\`, \`>\`, heredocs to fold multi-step scripts (\`mkdir -p x && cat > x/file.ts <<'EOF' ... EOF && npm test\`) into one call. Only emit a follow-up turn when the result forces a decision (error, ambiguous output, branching logic).
 
@@ -222,12 +221,12 @@ ${PLATFORM_NOTE}
 
 ${buildSnapshotSection()}${config.projectSkillEnabled ? buildProjectSkillSection() : ''}${memorySection}
 
-## Working notepad (todolist) — for multi-step tasks
-- For tasks spanning **≥2 independent modules** OR when the user asks for stepwise progress ("先计划再执行" / "plan then do" / "按步骤来"), call \`todolist create\` first; update as you go. Skip for single-file edits or quick lookups.
-- Plan is file-backed (\`todolist read\` to re-orient). See the tool description for the full action set.
+## Working notepad (todolist)
+- For genuinely complex tasks only: explore codebase → clarify with user → create plan → execute step by step. See tool description for details.
 
 ## Termination & Reporting
 - Stop immediately when no more tools are needed; give conclusions directly.
+- **Do not stop prematurely during exploration**: if you started investigating but haven't gathered enough information to answer the user's question, keep calling tools. Only stop when you have sufficient evidence or hit a dead end.
 - **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.`;
 }
@@ -347,3 +346,14 @@ export function updateProjectSkillConfig(enabled) {
     config.projectSkillEnabled = enabled;
     process.env.MOCODE_PROJECT_SKILL = enabled ? 'true' : 'false';
 }
+/**
+ * 切换项目快照开关(/snapshot on|off 调)。
+ * - 更新 config 单例字段(其它模块下次读 config.projectSnapshotEnabled 即拿新值:
+ *   buildSnapshotSection 现拼现读、read-file 每次 execute 现读)。
+ * - 同步 process.env.MOCODE_PROJECT_SNAPSHOT(下次启动 loadEnvFiles 不会被文件回填)。
+ * 持久化(写 ~/.mocode/config 的 MOCODE_PROJECT_SNAPSHOT 键)由调用方走 updateConfigKey。
+ */
+export function updateSnapshotConfig(enabled) {
+    config.projectSnapshotEnabled = enabled;
+    process.env.MOCODE_PROJECT_SNAPSHOT = enabled ? 'true' : 'false';
+}

package/dist/llm/index.js

@@ -354,6 +354,24 @@ async function chatOnce(messages, handlers, signal, toolsOverride) {
             buf = buf.slice(i);
         }
         if (delta.tool_calls) {
+            // 文本→工具转折点:若 buf 还残留普通文本的安全尾(为防跨 chunk 切分留的
+            // THINK_OPEN.length - 1 字符),立即 flush 到屏幕。否则这段尾巴会一直搁置到
+            // 流结束才由尾部防御输出,而那时 onToolCall 早已触发、TUI 已补换行+生成中
+            // spinner,用户看到「话没说完就去调工具」——history 完整但屏幕渲染顺序错位。
+            // inThink 段照旧丢弃(思考中模型不会同时吐 tool_call,理论上 buf 不会有思考段);
+            // 防御性保留 !inThink 判断。
+            if (buf && !inThink) {
+                visibleContent += buf;
+                // 给 onText 渲染时剥掉尾部 \n:md 渲染器(contentWriteMd)把尾部 \n 当段落分隔 → 产空行;
+                // 随后 onToolCall 检测到 lastChar !== '\n' 会经 contentWrite('\n') 补一个原始换行
+                // (不走 md,只是普通行分隔,无空行)—— 与改造前 onToolCall 补 \n 的行为一致。
+                // visibleContent 保留原 buf(含 \n),history 完整不受影响。
+                const tail = buf.replace(/\n+$/, '');
+                if (tail)
+                    handlers.onText?.(tail);
+                consumedAny = true;
+                buf = '';
+            }
             for (const tc of delta.tool_calls) {
                 const idx = tc.index ?? 0;
                 let entry = toolAcc.get(idx);
@@ -375,11 +393,14 @@ async function chatOnce(messages, handlers, signal, toolsOverride) {
         }
     }
     // 防御:循环内 buf.slice 已把可确认部分消费;此处覆盖流末尾的"安全尾":
-    //  - 普通段(stream 已结束,标签不会再出现):作为可见内容追加到 visibleContent(不再调 onText)
+    //  - 普通段(stream 已结束,标签不会再出现):作为可见内容追加到 visibleContent + 调 onText
+    //    (之前注释说"不再调 onText"是 bug——安全尾里的真实文本会被屏幕吞掉,用户看到模型
+    //     话没说完就去调工具 / 直接结束;history 有但显示缺。现在补上 onText 让屏幕与 history 一致。)
     //  - 思考段未闭合:丢弃,防 thinking 文本泄漏到 history
     if (buf) {
         if (!inThink) {
             visibleContent += buf;
+            handlers.onText?.(buf);
             consumedAny = true;
         }
         buf = '';

package/dist/project-skill/index.js

@@ -38,8 +38,8 @@ export function readProjectSkill() {
         return null;
     }
 }
-/** 内容硬上限(字符数)。超限拒绝写入，防止系统提示词膨胀 */
-const MAX_SKILL_CHARS = 6000;
+/** 内容硬上限(字符数)。超限拒绝写入，防止系统提示词膨胀。从 6000 降至 4000，与快照互补后内容更精简。 */
+const MAX_SKILL_CHARS = 4000;
 /**
  * 写入/更新项目 skill。先备份旧内容再写新内容。
  * 返回 { ok, error? }: ok=false 时 error 说明原因(超限/IO 失败)。
@@ -80,9 +80,88 @@ export function appendProjectSkill(addition) {
     const merged = existing + separator + trimmed;
     return writeProjectSkill(merged);
 }
+/**
+ * 调用 LLM 压缩内容。超限时自动精简，保留关键信息。
+ * 返回压缩后的内容，失败返回 null。
+ */
+export async function compressContent(content, signal) {
+    try {
+        // 动态导入避免循环依赖
+        const { chat } = await import('../llm/index.js');
+        const messages = [
+            {
+                role: 'system',
+                content: 'You are a technical writer. Compress the following project skill content to fit within ' +
+                    `${MAX_SKILL_CHARS} characters while preserving the most important information. ` +
+                    'Keep concrete examples, paths, and actionable insights. Remove redundancy and verbose explanations. ' +
+                    'Output ONLY the compressed content, no explanations.',
+            },
+            { role: 'user', content },
+        ];
+        const result = await chat(messages, {}, signal);
+        const compressed = result.content?.trim();
+        if (!compressed)
+            return null;
+        return compressed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 写入时自动压缩：超限则调用 LLM 压缩，最多尝试 maxAttempts 次。
+ * 返回 { ok, error?, compressed? }，compressed 标记是否经过压缩。
+ */
+export async function writeProjectSkillWithCompression(content, maxAttempts = 3, signal) {
+    let current = content;
+    let compressed = false;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const result = writeProjectSkill(current);
+        if (result.ok) {
+            return { ok: true, compressed };
+        }
+        // 非超限错误直接返回
+        if (!result.error?.includes('内容超过上限')) {
+            return result;
+        }
+        // 超限时调用 LLM 压缩
+        const compressedContent = await compressContent(current, signal);
+        if (!compressedContent) {
+            return {
+                ok: false,
+                error: `压缩失败: ${result.error}`,
+            };
+        }
+        current = compressedContent;
+        compressed = true;
+    }
+    // 多次压缩后仍超限
+    const finalCheck = writeProjectSkill(current);
+    if (finalCheck.ok) {
+        return { ok: true, compressed: true };
+    }
+    return {
+        ok: false,
+        error: `经过 ${maxAttempts} 次压缩仍超限: ${finalCheck.error}`,
+    };
+}
+/**
+ * 追加时自动压缩：合并后超限则调用 LLM 压缩，最多尝试 maxAttempts 次。
+ */
+export async function appendProjectSkillWithCompression(addition, maxAttempts = 3, signal) {
+    const existing = readProjectSkill() ?? '';
+    const trimmed = addition.trim();
+    if (!trimmed)
+        return { ok: false, error: '追加内容为空' };
+    const separator = existing ? '\n\n' : '';
+    const merged = existing + separator + trimmed;
+    return writeProjectSkillWithCompression(merged, maxAttempts, signal);
+}
 /**
  * 生成系统提示词注入段。
  * 开关关闭或文件不存在 → 空串(零行为变化)。
+ *
+ * 精简版：只注入 skill 内容本身，维护指南移到 project_skill_update 工具描述中。
  */
 export function buildProjectSkillSection() {
     const content = readProjectSkill();
@@ -97,33 +176,5 @@ export function buildProjectSkillSection() {
         '<project-skill>',
         content,
         '</project-skill>',
-        '',
-        '### Project Skill 维护指南',
-        '你可以（也应该）在开发过程中持续更新这个 skill，让它越来越了解项目：',
-        '',
-        '**何时更新**：',
-        '- 发现项目特有的架构模式、设计决策或数据流',
-        '- 踩坑后总结出避坑指南（命名冲突、API 行为、构建陷阱等）',
-        '- 学到新的命名约定、测试规范、代码风格',
-        '- 完成重要重构或引入新模块后',
-        '- 用户纠正了你对项目的错误理解',
-        '',
-        '**更新什么**：',
-        '- 项目概述、技术栈、核心模块职责',
-        '- 常见坑点和解决方案',
-        '- 开发流程（构建、测试、部署命令）',
-        '- 关键 API 的使用方式和限制',
-        '- 设计决策的 why（不只是 what）',
-        '',
-        '**如何更新**：',
-        '- `project_skill_update(action="read")` — 查看当前内容',
-        '- `project_skill_update(action="update", content="...")` — 全量替换（适合大改）',
-        '- `project_skill_update(action="append", content="...")` — 追加到末尾（适合加新发现）',
-        '',
-        '**注意事项**：',
-        '- 保持精简，硬上限 6000 字符（约 1500 token）',
-        '- 写可操作的内容，避免空泛描述',
-        '- 定期整理，删除过时信息',
-        '- 更新前建议先 `read` 看一下现有内容，避免重复',
     ].join('\n');
 }

package/dist/project-skill/initializer.js

@@ -5,64 +5,63 @@ import { spawnAgent } from '../agent/spawn.js';
 /**
  * 子 agent 的系统提示后缀：角色与输出格式约束
  */
-const SKILL_INIT_SUFFIX = `You are a project exploration agent. Your task is to deeply understand this project and generate a concise, actionable "Project Skill" document.
-
-## Your Mission
-Explore the project thoroughly using available tools, then produce a structured skill document that will help future AI agents work efficiently on this project.
+const SKILL_INIT_SUFFIX = `You are a project exploration agent. Your task is to deeply understand this project and generate a concise "Project Skill" document.
+
+## ⚠️ Complementary to Snapshot — CRITICAL
+The following information is ALREADY provided by Project Snapshot — **do NOT repeat**:
+- ✗ Project one-liner description (快照已有)
+- ✗ Module names and file locations (快照 srcTree 已有)
+- ✗ Tech stack names and versions (快照 techStack 已有)
+- ✗ Build/test commands (快照 keyCommands 已有)
+- ✗ File lists and directory structure (快照 srcTree 已有)
+
+**Your job is to capture INSIGHTS only:**
+- **WHY** — design decisions, trade-offs, reasons for choosing X over Y
+- **HOW** — module behaviors, data flows, call chains, non-obvious interactions
+- **GOTCHAS** — pitfalls, edge cases, non-intuitive behaviors
+- **CONVENTIONS** — naming patterns, code style, unwritten rules
 
 ## Exploration Strategy
-1. **Start broad**: Use \`glob\` to understand the project structure
-2. **Read key files**: package.json, README.md, tsconfig.json, any config files
-3. **Understand architecture**: Use \`codegraph\` or \`grep\` to find main entry points, core modules, key interfaces
-4. **Identify patterns**: Look for naming conventions, directory structure patterns, common abstractions
-5. **Find pitfalls**: Check for complex configs, unusual dependencies, build quirks
+1. Use \`codegraph\` to trace call chains and understand module interactions
+2. Read core modules to understand **behaviors** (not just names)
+3. Look for complex logic, error handling patterns, unusual configs
+4. Identify naming conventions, common abstractions
 
 ## Output Format
-When you're done exploring, output the skill document between these exact delimiters:
+Output the skill document between these exact delimiters:
 
 \`\`\`skill-start
-(your skill content here)
-\`\`\`skill-end
-
-The skill content should follow this structure (use Chinese for headings, adapt sections based on what you find):
-
-## 项目概述
-- 一句话描述项目是什么、做什么
-- 核心目标用户/场景
-
-## 技术栈
-- 主要语言、框架、工具（附版本号）
-- 关键技术选型理由（如果能从文档/代码推断）
-
 ## 架构要点
-- 核心模块及其职责（用 path/to/module 格式）
-- 数据流向或调用链（如果有明显模式）
-- 设计模式或架构模式（如果有）
+### 核心模块及职责
+- **\`path/to/module\`** — 行为描述（做什么 + 怎么做）
+...
 
-## 项目结构
-- 关键目录及其用途
-- 重要文件的位置
-
-## 开发流程
-- 构建、测试、lint、部署命令
-- 开发环境配置要点
+### 关键设计决策
+- 决策：原因
+...
 
 ## 项目约定
-- 命名规范（如果有明显模式）
-- 代码风格（如果有 .eslintrc, .prettierrc 等）
-- 测试策略（如果有测试）
+- 约定（具体的，有例子的）
+...
+
+## 开发流程
+- 命令 + 注意事项/坑点（命令本身快照已有，这里只写注意什么）
+...
 
 ## 常见坑点
-- 复杂的配置或构建步骤
-- 容易踩坑的 API 或行为
-- 需要特别注意的依赖版本问题
-
-## Guidelines
-- 保持精简，总长度控制在 4000-5000 字符（硬上限 6000）
-- 写可操作的内容，避免空泛描述（不要写"代码质量高"这种废话）
-- 用具体路径和例子（不要写"有多个模块"，要写"src/agent 负责 agent 循环"）
-- 如果某个 section 没有明显内容，可以省略或写"待补充"
-- 重点是：让未来的 agent 能立即理解项目并开始有效工作
+- 坑：解法
+...
+\`\`\`skill-end
+
+## Rules — MUST FOLLOW
+1. 禁止列出文件名清单或目录结构
+2. 禁止列出依赖名和版本
+3. 禁止写项目概述/一句话描述
+4. 禁止只写命令本身（快照已有），只写注意事项
+5. 每个模块描述必须包含行为（做什么 + 怎么协作），不只是名称
+6. **总长度目标 3000-4000 字符，硬上限 4000**
+7. 写可操作的内容，用具体路径和例子
+8. 如果某个 section 没有实质内容，省略它
 `;
 /**
  * 生成初始项目 Skill（使用子 agent 深度探索）

package/dist/project-snapshot/index.js

@@ -1,8 +1,7 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { getSandboxRoot } from '../sandbox/root.js';
-import { scanStaticFiles } from './static-files.js';
 /** 内存缓存：当前 session 的快照（避免重复 IO） */
 let currentSnapshot = null;
 /** 计算 sandboxRoot 的 hash，用作目录名（避免路径特殊字符） */
@@ -16,7 +15,7 @@ function snapshotDir() {
 }
 /** 快照文件路径 */
 function snapshotPath() {
-    return path.join(snapshotDir(), 'snapshot.json');
+    return path.join(snapshotDir(), 'snapshot.md');
 }
 /** 从磁盘加载快照（不存在/损坏返 null） */
 export function loadSnapshot() {
@@ -26,10 +25,17 @@ export function loadSnapshot() {
     if (!existsSync(p))
         return null;
     try {
-        const raw = readFileSync(p, 'utf8');
-        const snap = JSON.parse(raw);
-        if (!snap || snap.version !== 1 || !snap.files)
+        const content = readFileSync(p, 'utf8');
+        // 从 markdown 文件头部的 YAML front matter 提取元数据
+        const match = content.match(/^---\nroot: (.+)\nbuiltAt: (.+)\nversion: (\d+)\n---\n\n([\s\S]+)$/);
+        if (!match)
             return null;
+        const snap = {
+            version: parseInt(match[3]),
+            root: match[1],
+            builtAt: match[2],
+            content: match[4],
+        };
         currentSnapshot = snap;
         return snap;
     }
@@ -37,141 +43,43 @@ export function loadSnapshot() {
         return null;
     }
 }
-/** 构建/刷新快照：扫描静态文件 + 提取结构摘要 */
-export function buildSnapshot() {
+/** 获取当前快照（内存缓存优先，然后磁盘） */
+export function getSnapshot() {
+    return currentSnapshot ?? loadSnapshot();
+}
+export async function buildSnapshot(signal, force = false) {
+    // 检查缓存：已有快照且不强制刷新，直接返回
+    if (!force) {
+        const cached = getSnapshot();
+        if (cached)
+            return { snapshot: cached };
+    }
     const root = getSandboxRoot() ?? process.cwd();
-    const files = scanStaticFiles(root);
-    const structure = extractStructure(root, files);
+    // 动态导入避免循环依赖
+    const { generateLLMSnapshot } = await import('./llm-snapshot.js');
+    const result = await generateLLMSnapshot(root, signal);
+    if (!result.ok || !result.content) {
+        return {
+            snapshot: null,
+            error: result.error || 'LLM 未返回有效结果',
+            transcript: result.transcript,
+        };
+    }
     const snap = {
         version: 1,
         root,
         builtAt: new Date().toISOString(),
-        files,
-        structure,
+        content: result.content,
     };
-    // 落盘
+    // 落盘为 markdown 格式，带 YAML front matter
     const dir = snapshotDir();
     mkdirSync(dir, { recursive: true });
-    writeFileSync(snapshotPath(), JSON.stringify(snap, null, 2), 'utf8');
+    const mdContent = `---\nroot: ${snap.root}\nbuiltAt: ${snap.builtAt}\nversion: ${snap.version}\n---\n\n${snap.content}`;
+    writeFileSync(snapshotPath(), mdContent, 'utf8');
     currentSnapshot = snap;
-    return snap;
-}
-/** 获取当前快照（优先内存 → 磁盘 → 构建） */
-export function getSnapshot() {
-    return loadSnapshot() ?? buildSnapshot();
+    return { snapshot: snap };
 }
-/** 清空内存缓存（调试/测试用） */
+/** 清除内存缓存（强制下次重新加载） */
 export function clearSnapshotCache() {
     currentSnapshot = null;
 }
-/**
- * 从快照中查找文件（带 mtime 校验）。
- * 返回 null 表示：文件不在快照中 / mtime 已变 / 快照不存在。
- * 调用方应 fallback 到真实 readFile。
- */
-export function lookupSnapshotFile(absPath) {
-    const snap = loadSnapshot();
-    if (!snap)
-        return null;
-    // 转成相对路径（快照 key 是相对路径）
-    const root = snap.root;
-    if (!absPath.startsWith(root))
-        return null;
-    const relPath = path.relative(root, absPath).replace(/\\/g, '/');
-    const entry = snap.files[relPath];
-    if (!entry)
-        return null;
-    // mtime 校验：磁盘上的 mtime 必须与快照一致
-    try {
-        const st = statSync(absPath);
-        if (st.mtimeMs !== entry.mtime)
-            return null;
-    }
-    catch {
-        return null;
-    }
-    return { content: entry.content, mtime: entry.mtime };
-}
-/** 提取项目结构摘要（从静态文件 + 目录扫描） */
-function extractStructure(root, files) {
-    const modules = [];
-    const entries = [];
-    const configFiles = [];
-    // 配置文件：直接看 files keys
-    for (const relPath of Object.keys(files)) {
-        if (isConfigFile(relPath)) {
-            configFiles.push(relPath);
-        }
-    }
-    // 入口文件：从 package.json 提取
-    const pkgEntry = files['package.json'];
-    if (pkgEntry) {
-        try {
-            const pkg = JSON.parse(pkgEntry.content);
-            if (typeof pkg.main === 'string')
-                entries.push(pkg.main);
-            if (typeof pkg.module === 'string')
-                entries.push(pkg.module);
-            if (pkg.bin) {
-                if (typeof pkg.bin === 'string')
-                    entries.push(pkg.bin);
-                else if (typeof pkg.bin === 'object') {
-                    for (const v of Object.values(pkg.bin)) {
-                        if (typeof v === 'string')
-                            entries.push(v);
-                    }
-                }
-            }
-        }
-        catch {
-            // package.json 解析失败，跳过
-        }
-    }
-    // 模块：扫描顶层目录（排除 node_modules, .git 等）
-    try {
-        const items = readdirSync(root, { withFileTypes: true });
-        for (const item of items) {
-            if (!item.isDirectory())
-                continue;
-            if (item.name.startsWith('.'))
-                continue;
-            if (item.name === 'node_modules')
-                continue;
-            if (item.name === 'dist' || item.name === 'build')
-                continue;
-            modules.push(item.name);
-        }
-    }
-    catch {
-        // 目录扫描失败，留空
-    }
-    return { modules, entries, configFiles };
-}
-/** 判断是否为配置文件 */
-function isConfigFile(relPath) {
-    const configPatterns = [
-        'tsconfig.json',
-        'jsconfig.json',
-        '.eslintrc',
-        '.eslintrc.js',
-        '.eslintrc.json',
-        '.eslintrc.yml',
-        '.prettierrc',
-        '.prettierrc.js',
-        '.prettierrc.json',
-        '.env.example',
-        'jest.config.js',
-        'jest.config.ts',
-        'vitest.config.ts',
-        'vite.config.ts',
-        'next.config.js',
-        'next.config.ts',
-        'webpack.config.js',
-        'rollup.config.js',
-        'pyproject.toml',
-        'setup.py',
-        'go.mod',
-        'Cargo.toml',
-    ];
-    return configPatterns.some((p) => relPath === p || relPath.endsWith('/' + p));
-}