mocode-ai 0.1.0

package/dist/skills/discover.js

@@ -0,0 +1,139 @@
+// skills 发现子系统(对标 Claude Code 的 skill 自动发现)。
+// 仅依赖 node 标准库,是叶子模块:不依赖 config/agent/llm/tools,避免环。
+//
+// 约定:每个 skill 是一个目录 <skill-name>/SKILL.md,顶部 YAML frontmatter
+// (name / description 必需,version / license 可选)。元数据始终注入系统提示,
+// 正文由 use_skill 工具按需加载(渐进式披露)。
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** 把开头的 ~/ 或 ~ 展开为 home 目录(Windows 与 POSIX 通用)。 */
+function expandHome(p) {
+    if (p === '~')
+        return os.homedir();
+    if (p.startsWith('~/') || p.startsWith('~' + path.sep)) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+/**
+ * 解析 skill 目录列表。
+ * env SKILLS_DIRS 设则覆盖默认(用 path.delimiter 切分,与 PATH 同语义:
+ * win32 用 ';',POSIX 用 ':',规避盘符冒号问题);未设则默认三目录,
+ * 按优先级升序(低→高):~/.claude/skills → ~/.mocode/skills → <cwd>/.mocode/skills。
+ */
+export function resolveSkillsDirs() {
+    const env = process.env.SKILLS_DIRS;
+    if (env && env.trim()) {
+        return env
+            .split(path.delimiter)
+            .map((d) => d.trim())
+            .filter((d) => d.length > 0)
+            .map(expandHome);
+    }
+    const home = os.homedir();
+    return [
+        path.join(home, '.claude', 'skills'),
+        path.join(home, '.mocode', 'skills'),
+        path.join(process.cwd(), '.mocode', 'skills'),
+    ];
+}
+/**
+ * 极简 YAML frontmatter 解析(不引入 yaml 依赖)。
+ * 仅支持单行键值:按首个冒号切 key/value,trim,去首尾配对引号。
+ * 不支持块标量(| / >)与多行值——v1 限制(skill 的 description 实际多为单行)。
+ *
+ * 返回 { meta, body }:无 frontmatter 时 meta 为空、body 为原文。
+ */
+export function parseFrontmatter(content) {
+    const meta = {};
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    // 跳过前导空行,首行须是 ---
+    let i = 0;
+    while (i < lines.length && lines[i].trim() === '')
+        i++;
+    if (i >= lines.length || lines[i].trim() !== '---') {
+        return { meta, body: content };
+    }
+    i++; // 跳过开 ---
+    const fmLines = [];
+    let closed = false;
+    while (i < lines.length) {
+        if (lines[i].trim() === '---') {
+            closed = true;
+            break;
+        }
+        fmLines.push(lines[i]);
+        i++;
+    }
+    if (!closed)
+        return { meta, body: content }; // 无闭合:视为无 frontmatter
+    i++; // 跳过闭 ---
+    for (const line of fmLines) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        let value = line.slice(colon + 1).trim();
+        // 去首尾配对引号(" 或 ')
+        if (value.length >= 2 &&
+            ((value[0] === '"' && value[value.length - 1] === '"') ||
+                (value[0] === "'" && value[value.length - 1] === "'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key)
+            meta[key] = value;
+    }
+    const body = lines.slice(i).join('\n').replace(/^\n+/, '');
+    return { meta, body };
+}
+/**
+ * 扫描所有 skill 目录,解析 frontmatter,按目录优先级去重。
+ * 同步 fs + 全程静默容错(目录不存在 / 读失败 / 解析失败 → 跳过,不抛),
+ * 风格对齐 src/session/persist.ts。按 resolveSkillsDirs 升序遍历,
+ * Map.set 后设覆盖先设 → 项目级优先。
+ */
+export function discoverSkills() {
+    const dirs = resolveSkillsDirs();
+    const byName = new Map();
+    for (const dir of dirs) {
+        let entries = [];
+        try {
+            entries = readdirSync(dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name);
+        }
+        catch {
+            continue; // 目录不存在或无权限,静默跳过
+        }
+        for (const name of entries) {
+            const skillDir = path.join(dir, name);
+            const skillMdPath = path.join(skillDir, 'SKILL.md');
+            try {
+                if (!existsSync(skillMdPath))
+                    continue;
+                const content = readFileSync(skillMdPath, 'utf8');
+                const { meta } = parseFrontmatter(content);
+                const skillName = (meta.name || name).trim();
+                const description = (meta.description || '').trim();
+                if (!description)
+                    continue; // 缺 description 跳过(它是最触发机制)
+                byName.set(skillName, {
+                    name: skillName,
+                    description,
+                    version: meta.version?.trim() || undefined,
+                    license: meta.license?.trim() || undefined,
+                    dir: skillDir,
+                    skillMdPath,
+                });
+            }
+            catch {
+                continue; // 读 / 解析失败静默跳过
+            }
+        }
+    }
+    return Array.from(byName.values());
+}

package/dist/skills/index.js

@@ -0,0 +1,50 @@
+// skills barrel:缓存已发现的 skill、按需读正文、拼系统提示段。
+// 被 repl(注入 systemPrompt)与 tools/builtins/use-skill(加载正文)依赖;
+// 自身仅依赖 discover.ts + node:fs,是叶子级业务模块。
+import { existsSync, readFileSync } from 'node:fs';
+import { discoverSkills, parseFrontmatter } from './discover.js';
+let cache = null;
+/** 已发现的 skill 列表(懒加载,首次调用触发扫描;启动期 repl 调一次)。 */
+export function listSkills() {
+    if (cache === null)
+        cache = discoverSkills();
+    return cache;
+}
+/**
+ * 读取某 skill 的 SKILL.md 正文(去掉 frontmatter)。
+ * 纯函数:找不到 / 读失败返 null(错误字符串交给调用方工具层生成)。
+ */
+export function getSkillBody(name) {
+    const skill = listSkills().find((s) => s.name === name);
+    if (!skill)
+        return null;
+    try {
+        if (!existsSync(skill.skillMdPath))
+            return null;
+        const content = readFileSync(skill.skillMdPath, 'utf8');
+        const { body } = parseFrontmatter(content);
+        const trimmed = body.trim();
+        return trimmed || '(skill 正文为空)';
+    }
+    catch {
+        return null;
+    }
+}
+/** 拼进系统提示的 skill 段;无 skill 返空串(零行为变化)。 */
+export function buildSkillsSection() {
+    const skills = listSkills();
+    if (skills.length === 0)
+        return '';
+    const lines = skills.map((s) => `- ${s.name}: ${s.description}`);
+    return [
+        '',
+        '',
+        '## Skills(按需加载)',
+        '以下 skill 可用。只在任务相关时调用 use_skill 工具(传 skill 的 name)加载其完整指令,据此行动;不要无脑批量加载。',
+        ...lines,
+    ].join('\n');
+}
+/** base 系统提示 + skill 段;无 skill 时 === base。 */
+export function effectiveSystemPrompt(base) {
+    return base + buildSkillsSection();
+}

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

@@ -0,0 +1,34 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+// ---------- edit_file ----------
+export const editFileTool = {
+    name: 'edit_file',
+    description: '对文件做精确字符串替换。old_string 必须在文件中唯一出现且完全匹配(含缩进/换行)。新建文件请用 write_file。',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string' },
+            old_string: { type: 'string', description: '要被替换的原文,须精确匹配' },
+            new_string: { type: 'string', description: '替换后的新文本' },
+        },
+        required: ['path', 'old_string', 'new_string'],
+    },
+    async execute(args) {
+        const path = String(args.path);
+        const oldStr = String(args.old_string);
+        const newStr = String(args.new_string);
+        const full = resolve(path);
+        const data = await readFile(full, 'utf8');
+        const count = data.split(oldStr).length - 1;
+        if (count === 0) {
+            return `错误:在 ${path} 中未找到 old_string。请先 read_file 确认实际内容。`;
+        }
+        if (count > 1) {
+            return `错误:old_string 在 ${path} 中出现 ${count} 次,不唯一。请加入更多上下文使其唯一。`;
+        }
+        // 用函数形式替换,避免 new_string 里的 $ 被当特殊模式
+        const updated = data.replace(oldStr, () => newStr);
+        await writeFile(full, updated, 'utf8');
+        return `已在 ${path} 中完成 1 处替换。`;
+    },
+};

package/dist/tools/builtins/glob.js

@@ -0,0 +1,30 @@
+import fg from 'fast-glob';
+import { IGNORE } from '../constants.js';
+// ---------- glob ----------
+export const globTool = {
+    name: 'glob',
+    description: '按 glob 模式查找文件路径(如 **/*.ts)。返回匹配列表(自动排除 node_modules / .git)。',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'glob 模式,如 **/*.ts 或 src/**/*.json' },
+        },
+        required: ['pattern'],
+    },
+    async execute(args) {
+        const pattern = String(args.pattern);
+        const files = await fg(pattern, {
+            cwd: process.cwd(),
+            onlyFiles: true,
+            dot: true,
+            ignore: IGNORE,
+        });
+        if (files.length === 0)
+            return '无匹配文件';
+        const shown = files.slice(0, 200);
+        let out = shown.join('\n');
+        if (files.length > 200)
+            out += `\n... (共 ${files.length} 个,仅显示前 200)`;
+        return out;
+    },
+};

package/dist/tools/builtins/grep.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import fg from 'fast-glob';
+import { MAX_RESULTS, IGNORE } from '../constants.js';
+// ---------- grep ----------
+export const grepTool = {
+    name: 'grep',
+    description: '在文件内容里按正则搜索,返回 file:line: 匹配行。默认递归搜索当前目录(排除 node_modules/.git)。可选 glob 限定文件类型。',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: '正则表达式' },
+            glob: { type: 'string', description: '可选,限定文件 glob,如 *.ts' },
+        },
+        required: ['pattern'],
+    },
+    async execute(args) {
+        const pattern = String(args.pattern);
+        const g = String(args.glob ?? '**/*');
+        let re;
+        try {
+            re = new RegExp(pattern);
+        }
+        catch (e) {
+            return `错误:非法正则 ${pattern}: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        const files = await fg(g, {
+            cwd: process.cwd(),
+            onlyFiles: true,
+            dot: true,
+            ignore: IGNORE,
+        });
+        const results = [];
+        let scanned = 0;
+        for (const f of files) {
+            if (results.length >= MAX_RESULTS)
+                break;
+            let content;
+            try {
+                content = await readFile(resolve(f), 'utf8');
+            }
+            catch {
+                continue; // 跳过无法读的文件(二进制/权限)
+            }
+            scanned++;
+            const lines = content.split(/\r?\n/);
+            for (let i = 0; i < lines.length; i++) {
+                if (re.test(lines[i])) {
+                    results.push(`${f}:${i + 1}: ${lines[i].trim()}`);
+                    if (results.length >= MAX_RESULTS)
+                        break;
+                }
+            }
+        }
+        if (results.length === 0)
+            return `无匹配(扫描了 ${scanned} 个文件)`;
+        let out = results.join('\n');
+        if (results.length >= MAX_RESULTS)
+            out += `\n...(结果达到 ${MAX_RESULTS} 条上限)`;
+        return out;
+    },
+};

package/dist/tools/builtins/index.js

@@ -0,0 +1,24 @@
+import { readFileTool } from './read-file.js';
+import { writeFileTool } from './write-file.js';
+import { editFileTool } from './edit-file.js';
+import { runCommandTool } from './run-command.js';
+import { globTool } from './glob.js';
+import { grepTool } from './grep.js';
+import { webSearchTool } from './web-search.js';
+import { webFetchTool } from './web-fetch.js';
+import { useSkillTool } from './use-skill.js';
+/**
+ * 所有内置工具,按注册顺序排列。
+ * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。
+ */
+export const builtinTools = [
+    readFileTool,
+    writeFileTool,
+    editFileTool,
+    runCommandTool,
+    globTool,
+    grepTool,
+    webSearchTool,
+    webFetchTool,
+    useSkillTool,
+];

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

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { MAX_FILE_LINES } from '../constants.js';
+// ---------- read_file ----------
+export const readFileTool = {
+    name: 'read_file',
+    description: '读取文件内容,返回带行号的文本。改代码前先读。可选 offset(起始行,1-based,默认1)和 limit(行数,默认2000)。',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: '文件路径,相对工作目录' },
+            offset: { type: 'integer', description: '起始行号(1-based),默认1' },
+            limit: { type: 'integer', description: '最大读取行数,默认2000' },
+        },
+        required: ['path'],
+    },
+    async execute(args) {
+        const path = String(args.path);
+        const offset = Number(args.offset ?? 1);
+        const limit = Number(args.limit ?? MAX_FILE_LINES);
+        const data = await readFile(resolve(path), 'utf8');
+        const lines = data.split(/\r?\n/);
+        const start = Math.max(0, offset - 1);
+        const end = Math.min(lines.length, start + limit);
+        const body = lines
+            .slice(start, end)
+            .map((l, i) => `${String(start + i + 1).padStart(6, ' ')}\t${l}`)
+            .join('\n');
+        if (end < lines.length) {
+            return body + `\n\n... (${lines.length - end} 行未显示,共 ${lines.length} 行)`;
+        }
+        return body || '(空文件)';
+    },
+};

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

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+import { MAX_OUTPUT } from '../constants.js';
+// ---------- run_command ----------
+export const runCommandTool = {
+    name: 'run_command',
+    description: '执行 shell 命令,返回合并的 stdout+stderr。默认超时 120 秒。用于跑测试、构建、git 等。',
+    parameters: {
+        type: 'object',
+        properties: {
+            command: { type: 'string', description: '要执行的命令(单行)' },
+            timeout: { type: 'integer', description: '超时毫秒,默认120000' },
+        },
+        required: ['command'],
+    },
+    async execute(args) {
+        const command = String(args.command);
+        const timeout = Number(args.timeout ?? 120000);
+        return new Promise((done) => {
+            const isWin = process.platform === 'win32';
+            const child = spawn(isWin ? 'cmd.exe' : 'bash', isWin ? ['/c', command] : ['-c', command], { cwd: process.cwd() });
+            let out = '';
+            let finished = false;
+            const finish = (s) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                done(s);
+            };
+            const onChunk = (chunk) => {
+                if (out.length < MAX_OUTPUT)
+                    out += chunk.toString('utf8');
+            };
+            child.stdout.on('data', onChunk);
+            child.stderr.on('data', onChunk);
+            child.on('error', (e) => finish(`执行失败: ${e.message}`));
+            child.on('close', (code) => {
+                let r = out.trim();
+                if (out.length >= MAX_OUTPUT)
+                    r += '\n...(输出已截断)';
+                finish(`[退出码 ${code}]\n${r || '(无输出)'}`);
+            });
+            const timer = setTimeout(() => {
+                child.kill();
+                finish(`[超时,已终止]\n${out.trim()}`);
+            }, timeout);
+        });
+    },
+};

package/dist/tools/builtins/use-skill.js

@@ -0,0 +1,27 @@
+import { getSkillBody } from '../../skills/index.js';
+// ---------- use_skill ----------
+// 模型按需加载某 skill 的 SKILL.md 正文(渐进式披露第②层)。
+// 系统提示里已列出可用 skill 的 name + description(何时用),模型据此决定调用。
+export const useSkillTool = {
+    name: 'use_skill',
+    description: '加载并返回某个 skill 的完整 SKILL.md 指令。系统提示里列出了可用 skill(name + 何时用的 description)。只在任务相关时调用本工具传 skill 的 name,拿到完整指令后据此行动;不要无脑批量加载。',
+    parameters: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: '要加载的 skill 名(见系统提示里的 skill 列表,或 /skills 命令)',
+            },
+        },
+        required: ['name'],
+    },
+    async execute(args) {
+        const name = String(args.name ?? '').trim();
+        if (!name)
+            return '错误:缺少 skill 名。用 /skills 查看可用 skill 列表。';
+        const body = getSkillBody(name);
+        if (body === null)
+            return `错误:未找到 skill "${name}"。用 /skills 查看可用 skill 列表。`;
+        return `# Skill: ${name}\n\n${body}`;
+    },
+};

package/dist/tools/builtins/web-fetch.js

@@ -0,0 +1,125 @@
+import { MAX_OUTPUT } from '../constants.js';
+const FETCH_TIMEOUT_MS = 30000;
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36';
+// ---------- web_fetch ----------
+export const webFetchTool = {
+    name: 'web_fetch',
+    description: '抓取指定 URL 的网页内容并清洗成纯文本(去 HTML 标签/脚本/样式,保留正文)。用于读取搜索结果里的某个链接、或用户给出的具体 URL。注意:只能抓静态 HTML,JS 渲染的页面(正文靠脚本填充)可能拿不到内容——那种情况改用 web_search(其结果自带清洗后的 content)。',
+    parameters: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: '要抓取的完整 URL,须 http/https' },
+        },
+        required: ['url'],
+    },
+    async execute(args) {
+        const rawUrl = String(args.url ?? '').trim();
+        if (!rawUrl)
+            return '错误:url 不能为空。';
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            return `错误:URL 不合法: ${rawUrl}`;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return `错误:仅支持 http/https,收到 ${url.protocol}`;
+        }
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+        try {
+            const resp = await fetch(url.href, {
+                method: 'GET',
+                headers: {
+                    'User-Agent': UA,
+                    Accept: 'text/html,application/xhtml+xml,text/plain,application/json,*/*',
+                },
+                signal: ctrl.signal,
+            });
+            const contentType = resp.headers.get('content-type') ?? '';
+            const text = await resp.text();
+            if (!resp.ok) {
+                return `错误:抓取失败 HTTP ${resp.status} ${resp.statusText}\n${text.slice(0, 500)}`;
+            }
+            const isHtml = /html/i.test(contentType) ||
+                /^\s*<!doctype html/i.test(text) ||
+                /<html[\s>]/i.test(text.slice(0, 1000));
+            const body = isHtml ? htmlToText(text) : text;
+            const ct = contentType.split(';')[0].trim();
+            const prefix = `${url.href} (HTTP ${resp.status}${ct ? ', ' + ct : ''})\n\n`;
+            let out = prefix + body;
+            if (out.length > MAX_OUTPUT) {
+                out = out.slice(0, MAX_OUTPUT) + `\n...(已截断,原文 ${body.length} 字符)`;
+            }
+            return out;
+        }
+        catch (e) {
+            if (ctrl.signal.aborted) {
+                return `错误:抓取超时(${FETCH_TIMEOUT_MS}ms): ${url.href}`;
+            }
+            const msg = e instanceof Error ? e.message : String(e);
+            return `错误:抓取失败: ${msg}`;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+};
+/**
+ * 轻量 HTML→纯文本:优先取 <main>/<article> 正文区,再去 nav/header/footer/aside/form
+ * 等非正文块与脚本样式,块级/列表标签转换行,去剩余标签,解码实体,压缩空白。
+ * 不求精确解析,只取可读正文。
+ */
+function htmlToText(html) {
+    let s = html;
+    // 优先正文区:有 <main>/<article> 就只取其内容,避开整页 nav/header/footer 噪音
+    const main = s.match(/<main\b[^>]*>[\s\S]*?<\/main>/i);
+    if (main) {
+        s = main[0];
+    }
+    else {
+        const art = s.match(/<article\b[^>]*>[\s\S]*?<\/article>/i);
+        if (art)
+            s = art[0];
+    }
+    s = s.replace(/<!--[\s\S]*?-->/g, '');
+    s = s.replace(/<script[\s\S]*?<\/script>/gi, '');
+    s = s.replace(/<style[\s\S]*?<\/style>/gi, '');
+    s = s.replace(/<noscript[\s\S]*?<\/noscript>/gi, '');
+    s = s.replace(/<nav[\s\S]*?<\/nav>/gi, '');
+    s = s.replace(/<header[\s\S]*?<\/header>/gi, '');
+    s = s.replace(/<footer[\s\S]*?<\/footer>/gi, '');
+    s = s.replace(/<aside[\s\S]*?<\/aside>/gi, '');
+    s = s.replace(/<form[\s\S]*?<\/form>/gi, '');
+    s = s.replace(/<\/(p|div|li|tr|h[1-6]|section|article|header|footer|nav|aside|ul|ol|table|blockquote|pre|br)>/gi, '\n');
+    s = s.replace(/<br\b[^>]*>/gi, '\n');
+    s = s.replace(/<li\b[^>]*>/gi, '\n');
+    s = s.replace(/<[^>]+>/g, '');
+    s = decodeEntities(s);
+    s = s.replace(/[ \t\f\v]+/g, ' ');
+    s = s.replace(/\n[ \t]*/g, '\n');
+    s = s.replace(/\n{3,}/g, '\n\n');
+    return s.trim();
+}
+function decodeEntities(s) {
+    return s
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'")
+        .replace(/&#(\d+);/g, (_m, n) => safeFromCodePoint(parseInt(n, 10)))
+        .replace(/&#x([0-9a-f]+);/gi, (_m, h) => safeFromCodePoint(parseInt(h, 16)));
+}
+function safeFromCodePoint(n) {
+    if (!Number.isFinite(n) || n < 0 || n > 0x10ffff)
+        return '';
+    try {
+        return String.fromCodePoint(n);
+    }
+    catch {
+        return '';
+    }
+}