mocode-ai 0.4.7 → 0.4.9

package/dist/project-skill/index.js

@@ -0,0 +1,129 @@
+/**
+ * 项目专属 Skill — 跨 session 持久化的项目开发知识。
+ *
+ * 每个项目可维护一个专属 skill 文件(.mocode/project-skill.md)，
+ * 记录开发约定、架构决策、常见坑点等。开关启用后:
+ *   1. 每次启动时内容注入系统提示词(buildProjectSkillSection)
+ *   2. Agent 可通过 project_skill_update 工具动态更新
+ *   3. 随着项目开发，skill 越来越了解项目，开发效率越来越高
+ *
+ * 存储位置: <cwd>/.mocode/project-skill.md
+ * 开关: MOCODE_PROJECT_SKILL 环境变量，默认 false(零侵入)
+ *
+ * 与现有功能的关系:
+ *   - 通用 skill(SKILLS_DIRS): 按需加载(use_skill);项目 skill: 始终注入
+ *   - memory: 碎片化 fact/decision; 项目 skill: 结构化知识总结
+ *   - snapshot: 静态文件缓存(只读); 项目 skill: 动态知识(可写)
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+/** 项目 skill 文件路径 */
+function skillPath() {
+    return path.join(process.cwd(), '.mocode', 'project-skill.md');
+}
+/** 备份文件路径 */
+function backupPath() {
+    return path.join(process.cwd(), '.mocode', 'project-skill.md.bak');
+}
+/** 读取项目 skill 内容。不存在/读失败 → null */
+export function readProjectSkill() {
+    const p = skillPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const content = readFileSync(p, 'utf8').trim();
+        return content || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 内容硬上限(字符数)。超限拒绝写入，防止系统提示词膨胀 */
+const MAX_SKILL_CHARS = 6000;
+/**
+ * 写入/更新项目 skill。先备份旧内容再写新内容。
+ * 返回 { ok, error? }: ok=false 时 error 说明原因(超限/IO 失败)。
+ */
+export function writeProjectSkill(content) {
+    const trimmed = content.trim();
+    if (trimmed.length > MAX_SKILL_CHARS) {
+        return {
+            ok: false,
+            error: `内容超过上限(${trimmed.length}/${MAX_SKILL_CHARS} 字符)。请精简后重试。`,
+        };
+    }
+    const p = skillPath();
+    const dir = path.dirname(p);
+    try {
+        // 备份旧内容(如果有)
+        if (existsSync(p)) {
+            copyFileSync(p, backupPath());
+        }
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(p, trimmed + '\n', 'utf8');
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: `写入失败: ${e.message}` };
+    }
+}
+/**
+ * 追加内容到项目 skill 末尾(以 \n\n 分隔)。
+ * 同样受 MAX_SKILL_CHARS 限制。
+ */
+export function appendProjectSkill(addition) {
+    const existing = readProjectSkill() ?? '';
+    const trimmed = addition.trim();
+    if (!trimmed)
+        return { ok: false, error: '追加内容为空' };
+    const separator = existing ? '\n\n' : '';
+    const merged = existing + separator + trimmed;
+    return writeProjectSkill(merged);
+}
+/**
+ * 生成系统提示词注入段。
+ * 开关关闭或文件不存在 → 空串(零行为变化)。
+ */
+export function buildProjectSkillSection() {
+    const content = readProjectSkill();
+    if (!content)
+        return '';
+    return [
+        '',
+        '',
+        '## Project Skill (project-specific knowledge)',
+        'The following is project-specific knowledge maintained across sessions. Use it as context for all tasks in this project.',
+        '',
+        '<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

@@ -0,0 +1,179 @@
+/**
+ * 项目 Skill 初始化器 - 派生子 agent 带工具深度探索项目，生成高质量的初始 skill
+ */
+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.
+
+## 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
+
+## Output Format
+When you're done exploring, 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 格式）
+- 数据流向或调用链（如果有明显模式）
+- 设计模式或架构模式（如果有）
+
+## 项目结构
+- 关键目录及其用途
+- 重要文件的位置
+
+## 开发流程
+- 构建、测试、lint、部署命令
+- 开发环境配置要点
+
+## 项目约定
+- 命名规范（如果有明显模式）
+- 代码风格（如果有 .eslintrc, .prettierrc 等）
+- 测试策略（如果有测试）
+
+## 常见坑点
+- 复杂的配置或构建步骤
+- 容易踩坑的 API 或行为
+- 需要特别注意的依赖版本问题
+
+## Guidelines
+- 保持精简，总长度控制在 4000-5000 字符（硬上限 6000）
+- 写可操作的内容，避免空泛描述（不要写"代码质量高"这种废话）
+- 用具体路径和例子（不要写"有多个模块"，要写"src/agent 负责 agent 循环"）
+- 如果某个 section 没有明显内容，可以省略或写"待补充"
+- 重点是：让未来的 agent 能立即理解项目并开始有效工作
+`;
+/**
+ * 生成初始项目 Skill（使用子 agent 深度探索）
+ * @param existingSkill 已有的 skill 内容（如果有，子 agent 会在其基础上优化）
+ * @param signal AbortSignal
+ */
+export async function generateInitialSkill(existingSkill, signal) {
+    const hasExisting = !!existingSkill;
+    let prompt;
+    if (hasExisting) {
+        prompt = `以下是当前的项目 Skill 内容，请深度探索项目并优化/完善它：
+
+\`\`\`markdown
+${existingSkill}
+\`\`\`
+
+## 优化方向
+1. 补充缺失的信息（架构要点、设计决策、调用链等）
+2. 修正过时或不准确的内容
+3. 让描述更具体（用实际路径和例子）
+4. 删除冗余或空泛的描述
+5. 如果发现新的坑点或约定，添加进去
+
+记住：保持精简，总长度控制在 4000-5000 字符。输出完整的优化后版本。`;
+    }
+    else {
+        prompt = `请深度探索当前项目，生成一份项目专属 Skill 文档。
+
+## 探索步骤
+1. 先用 glob 扫描项目结构（**/*.ts, **/*.json 等）
+2. 读取 package.json、README.md、tsconfig.json 等关键文件
+3. 用 codegraph 或 grep 找到主入口、核心模块、关键接口
+4. 理解架构模式、数据流向、调用关系
+5. 识别命名约定、代码风格、测试策略
+6. 找出可能的坑点（复杂配置、特殊依赖、构建陷阱）
+
+## 输出
+探索完成后，将完整的 skill 文档输出在 \`\`\`skill-start 和 \`\`\`skill-end 之间。
+
+记住：内容要精简、可操作、有具体路径和例子。总长度控制在 4000-5000 字符。`;
+    }
+    try {
+        const result = await spawnAgent({
+            prompt,
+            systemPromptSuffix: SKILL_INIT_SUFFIX,
+            tools: ['read_file', 'glob', 'grep', 'codegraph'],
+            maxSteps: 30,
+            signal,
+        });
+        if (!result.completed) {
+            return {
+                ok: false,
+                error: '子 agent 未完成（可能中断或超时）',
+                transcript: result.transcript,
+            };
+        }
+        if (!result.summary) {
+            return {
+                ok: false,
+                error: '子 agent 未返回内容',
+                transcript: result.transcript,
+            };
+        }
+        // 从 summary 中提取 skill 内容
+        const skillMatch = result.summary.match(/```skill-start\n([\s\S]*?)\n```skill-end/);
+        if (!skillMatch || !skillMatch[1]) {
+            // 如果没有找到 delimiters，尝试从最后一段 markdown 代码块提取
+            const codeBlockMatch = result.summary.match(/```(?:markdown|md)?\n([\s\S]*?)\n```/);
+            if (codeBlockMatch && codeBlockMatch[1]) {
+                return {
+                    ok: true,
+                    content: codeBlockMatch[1].trim(),
+                    transcript: result.transcript,
+                };
+            }
+            // 如果连代码块都没有，直接用 summary（但去掉开头的探索日志）
+            const lines = result.summary.split('\n');
+            const skillStartIdx = lines.findIndex((l) => l.startsWith('## '));
+            if (skillStartIdx > 0) {
+                return {
+                    ok: true,
+                    content: lines.slice(skillStartIdx).join('\n').trim(),
+                    transcript: result.transcript,
+                };
+            }
+            return {
+                ok: false,
+                error: '无法从子 agent 输出中提取 skill 内容',
+                transcript: result.transcript,
+            };
+        }
+        const content = skillMatch[1].trim();
+        // 检查长度
+        if (content.length > 6000) {
+            return {
+                ok: false,
+                error: `生成内容过长 (${content.length} 字符)，请手动精简后重试`,
+                transcript: result.transcript,
+            };
+        }
+        return {
+            ok: true,
+            content,
+            transcript: result.transcript,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: e instanceof Error ? e.message : '未知错误',
+            transcript: '',
+        };
+    }
+}

package/dist/project-snapshot/index.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync } 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，用作目录名（避免路径特殊字符） */
+export function hashRoot(root) {
+    return createHash('sha256').update(root).digest('hex').slice(0, 16);
+}
+/** 快照存储目录 */
+function snapshotDir() {
+    const root = getSandboxRoot() ?? process.cwd();
+    return path.join(process.cwd(), '.mocode', 'projects', hashRoot(root));
+}
+/** 快照文件路径 */
+function snapshotPath() {
+    return path.join(snapshotDir(), 'snapshot.json');
+}
+/** 从磁盘加载快照（不存在/损坏返 null） */
+export function loadSnapshot() {
+    if (currentSnapshot)
+        return currentSnapshot;
+    const p = snapshotPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = readFileSync(p, 'utf8');
+        const snap = JSON.parse(raw);
+        if (!snap || snap.version !== 1 || !snap.files)
+            return null;
+        currentSnapshot = snap;
+        return snap;
+    }
+    catch {
+        return null;
+    }
+}
+/** 构建/刷新快照：扫描静态文件 + 提取结构摘要 */
+export function buildSnapshot() {
+    const root = getSandboxRoot() ?? process.cwd();
+    const files = scanStaticFiles(root);
+    const structure = extractStructure(root, files);
+    const snap = {
+        version: 1,
+        root,
+        builtAt: new Date().toISOString(),
+        files,
+        structure,
+    };
+    // 落盘
+    const dir = snapshotDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(snapshotPath(), JSON.stringify(snap, null, 2), 'utf8');
+    currentSnapshot = snap;
+    return snap;
+}
+/** 获取当前快照（优先内存 → 磁盘 → 构建） */
+export function getSnapshot() {
+    return loadSnapshot() ?? buildSnapshot();
+}
+/** 清空内存缓存（调试/测试用） */
+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));
+}

package/dist/project-snapshot/static-files.js

@@ -0,0 +1,87 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * 静态项目文件白名单 + 扫描逻辑。
+ * 这些文件通常是项目元信息，变动频率低、体积小、跨 session 稳定。
+ */
+/** 静态文件白名单（文件名或模式） */
+const STATIC_FILE_PATTERNS = [
+    // 文档
+    /^README(\.[a-z]+)?(\.[a-z]+)?$/i, // README, README.md, README.zh-CN.md
+    'CHANGELOG.md',
+    'CONTRIBUTING.md',
+    'LICENSE',
+    'LICENSE.md',
+    'LICENSE.txt',
+    // Node.js
+    'package.json',
+    'tsconfig.json',
+    'jsconfig.json',
+    // Python
+    'pyproject.toml',
+    'setup.py',
+    'setup.cfg',
+    'requirements.txt',
+    'Pipfile',
+    // Go
+    'go.mod',
+    // Rust
+    'Cargo.toml',
+    // 环境变量模板
+    '.env.example',
+    '.env.template',
+];
+/**
+ * 判断文件名是否匹配白名单
+ */
+function matchesPattern(filename) {
+    for (const p of STATIC_FILE_PATTERNS) {
+        if (typeof p === 'string') {
+            if (filename === p)
+                return true;
+        }
+        else {
+            if (p.test(filename))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 扫描项目根目录，收集匹配白名单的静态文件。
+ * 只扫顶层（不递归），避免 node_modules 等大目录。
+ * @param root 项目根目录（绝对路径）
+ * @returns key = 相对路径（正斜杠），val = { mtime, content }
+ */
+export function scanStaticFiles(root) {
+    const result = {};
+    let items;
+    try {
+        items = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const item of items) {
+        if (!item.isFile())
+            continue;
+        if (!matchesPattern(item.name))
+            continue;
+        const absPath = path.join(root, item.name);
+        try {
+            const stat = statSync(absPath);
+            // 体积限制：单文件 > 64KB 跳过（避免 README 巨长拖慢快照）
+            if (stat.size > 64 * 1024)
+                continue;
+            const content = readFileSync(absPath, 'utf8');
+            result[item.name] = {
+                mtime: stat.mtimeMs,
+                content,
+            };
+        }
+        catch {
+            // 读取失败：跳过
+        }
+    }
+    return result;
+}

package/dist/repl/index.d.ts

@@ -0,0 +1,22 @@
+import { type ChatMessage } from '../llm/index.js';
+/**
+ * 把会话历史渲染成静态文本进内容区(回滚 / 续接 / --resume 后复显上下文,仿 Claude Code):
+ * user→❯ 回显、assistant→正文(+ tool_calls 折叠成 ● 摘要行)、tool→↳ 结果预览;system 跳过。
+ * 思考段不持久(history 只存正文),故无思考折叠。渲染后续写位在末尾,紧接 enterInputMode 画输入框。
+ * 内容长于屏时 viewport 显尾(最近轮次),PgUp 可看更早——与流式态一致。
+ * user 多模态:用 textOf 取 text parts;若侧 channel messageAttachments 有原文件名则追加 chip 行
+ * (避免 base64 解码不可逆,旧 session 没侧 channel 时只显文本,文件名 fallback 到 image/* mime)。
+ *
+ * 折叠策略:遇到 assistant + tool_calls 不立即打 ● 行,而是累积到 batchEntries;
+ * 跟随的连续 tool 消息按 tool_call_id 反查填 resultSummary;遇下一个非 tool 消息(或末尾)时,
+ * 用 batch.writeSummaryOnly 出单行摘要(与实时 runAgent 同一渲染器,UI 一致)。
+ * 回放默认全折叠;用户可鼠标点击摘要行展开(由 BatchRenderer 接管,见 ui/batch.ts)。
+ */
+export declare function renderHistory(history: ChatMessage[]): void;
+/**
+ * 交互式 REPL:全屏 TUI(alt screen + 固定底栏)。INPUT 态底栏=状态行+输入框(raw mode 等按键);
+ * 提交后 enterRunningMode(底栏改 dim 占位、光标回内容续写位),命令分发与 runAgent 的流式输出经
+ * contentWrite 落入内容区(滚动区域内自动滚动,底栏不动)。history 由本模块持有,在轮次间持久;
+ * agent 只读取并追加(+ 经 session/ 压缩)。每轮成功结束后自动落盘,退出后可用 --resume / /resume 续接。
+ */
+export declare function startRepl(initialHistory?: ChatMessage[], sessionId?: string, updateNotice?: string | null, sandboxRootOverride?: string): Promise<void>;