@cc-monitoring/proxy-core 0.3.1 → 0.4.1

package/dist/utils/vault.js

@@ -0,0 +1,434 @@
+// vault：learn 文件型知识库（~/.cc-monitoring/docs）的深 module。
+// 物理布局：
+// - index.json 根索引 {"topics":[TopicSummary]}
+// - <slug>/index.json 主题索引 TopicIndex（元数据 + chunks 引用）
+// - <slug>/outline.json、<slug>/sources/source-NNN.md、<slug>/chunks/chunk-NNN.md
+// - <slug>.old/ 旁挂备份
+// 所有路径解析、slug/chunk-id 校验、物理读写均以本 module 为唯一权威。
+import { promises as fs } from 'node:fs';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { dataDir } from './paths.js';
+// 合法 slug：小写字母数字开头，仅含小写字母数字与连字符
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const CHUNK_RE = /^chunk-\d{3}$/;
+export function isValidSlug(slug) {
+    return SLUG_RE.test(slug);
+}
+export function createVault(docsDir) {
+    // ---- 路径解析（单一权威）----
+    const rootIndexPath = () => path.join(docsDir, 'index.json');
+    const entryDir = (entry) => path.join(docsDir, entry);
+    const entryIndexPath = (entry) => path.join(docsDir, entry, 'index.json');
+    const entrySubdir = (entry, subdir) => path.join(docsDir, entry, subdir);
+    function assertTopic(topic) {
+        if (!SLUG_RE.test(topic)) {
+            throw new Error(`invalid topic slug: ${topic}`);
+        }
+    }
+    function assertChunkId(chunkId) {
+        if (!CHUNK_RE.test(chunkId)) {
+            throw new Error(`invalid chunk id: ${chunkId} (expect chunk-NNN)`);
+        }
+    }
+    /** 从 chunk 正文首行 `# xxx` 提取 title（用于 searchChunks） */
+    function parseChunkTitle(text) {
+        const m = text.match(/^#\s+(.+?)\s*$/m);
+        return m ? m[1].trim() : '';
+    }
+    /** 读 JSON 文件，不存在或解析失败时返回 fallback */
+    async function readJsonOr(file, fallback) {
+        try {
+            const text = await fs.readFile(file, 'utf8');
+            return JSON.parse(text);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    // ============================================================
+    // 读 / 查（原 knowledge-store，逐字保持）
+    // ============================================================
+    async function listTopics() {
+        const parsed = await readJsonOr(rootIndexPath(), { topics: [] });
+        return Array.isArray(parsed.topics) ? parsed.topics : [];
+    }
+    async function getTopic(topic) {
+        assertTopic(topic);
+        const indexPath = entryIndexPath(topic);
+        let meta;
+        try {
+            const text = await fs.readFile(indexPath, 'utf8');
+            meta = JSON.parse(text);
+        }
+        catch (e) {
+            if (e && e.code === 'ENOENT') {
+                throw new Error(`topic not found: ${topic}`);
+            }
+            throw new Error(`topic index corrupt: ${topic}, fix or delete ${topic}/index.json`);
+        }
+        return {
+            title: meta.title || topic,
+            tags: Array.isArray(meta.tags) ? meta.tags : [],
+            sources: [],
+            chunks: Array.isArray(meta.chunks)
+                ? meta.chunks.map(c => ({
+                    id: c.id,
+                    title: c.title,
+                    summary: c.summary,
+                    tags: Array.isArray(c.tags) ? c.tags : [],
+                }))
+                : [],
+        };
+    }
+    async function upsertTopic(input) {
+        assertTopic(input.slug);
+        const { slug, title, summary, tags } = input;
+        // 1. 更新根 index.json
+        const rootPath = rootIndexPath();
+        const rootIdx = await readJsonOr(rootPath, { topics: [] });
+        if (!Array.isArray(rootIdx.topics))
+            rootIdx.topics = [];
+        const existingRoot = rootIdx.topics.find(t => t.slug === slug);
+        if (existingRoot) {
+            existingRoot.title = title;
+            existingRoot.summary = summary;
+            existingRoot.tags = tags;
+        }
+        else {
+            rootIdx.topics.push({ slug, title, summary, tags });
+        }
+        await fs.writeFile(rootPath, JSON.stringify(rootIdx, null, 2), 'utf8');
+        // 2. 更新主题 index.json（不动 chunks 数组）
+        const topicDir = entryDir(slug);
+        const topicPath = entryIndexPath(slug);
+        const topicIdx = await readJsonOr(topicPath, { slug, title, summary, tags, chunks: [] });
+        topicIdx.slug = slug;
+        topicIdx.title = title;
+        topicIdx.summary = summary;
+        topicIdx.tags = tags;
+        if (!Array.isArray(topicIdx.chunks))
+            topicIdx.chunks = [];
+        await fs.mkdir(topicDir, { recursive: true });
+        await fs.writeFile(topicPath, JSON.stringify(topicIdx, null, 2), 'utf8');
+    }
+    async function upsertChunkRef(input) {
+        assertTopic(input.topic);
+        assertChunkId(input.chunkId);
+        const { topic, chunkId, title, summary, tags } = input;
+        const topicPath = entryIndexPath(topic);
+        let topicIdx;
+        try {
+            const text = await fs.readFile(topicPath, 'utf8');
+            topicIdx = JSON.parse(text);
+        }
+        catch (e) {
+            if (e && e.code === 'ENOENT') {
+                throw new Error(`topic not found: ${topic}, call add_topic first`);
+            }
+            throw e;
+        }
+        if (!Array.isArray(topicIdx.chunks))
+            topicIdx.chunks = [];
+        const existing = topicIdx.chunks.find(c => c.id === chunkId);
+        if (existing) {
+            existing.title = title;
+            existing.summary = summary;
+            existing.tags = tags;
+        }
+        else {
+            topicIdx.chunks.push({ id: chunkId, title, summary, tags });
+        }
+        await fs.writeFile(topicPath, JSON.stringify(topicIdx, null, 2), 'utf8');
+    }
+    /** 匹配词集合：整体 query + whitespace 分割的长度 >1 的 token，去重 */
+    function buildTerms(query) {
+        const q = query.toLowerCase();
+        const terms = new Set([q]);
+        for (const tok of q.split(/\s+/)) {
+            if (tok.length > 1)
+                terms.add(tok);
+        }
+        return [...terms];
+    }
+    /** 扫描所有 topic/chunk，返回打分候选（searchChunks / queryKnowledge 共用） */
+    async function scanChunks(query) {
+        const q = query.toLowerCase();
+        if (!q.trim())
+            return [];
+        const terms = buildTerms(query);
+        const candidates = [];
+        // topic index 本函数作用域缓存，避免每个 chunk 重复读
+        const topicIndexCache = new Map();
+        let entries;
+        try {
+            entries = await fs.readdir(docsDir);
+        }
+        catch {
+            return [];
+        }
+        for (const topic of entries) {
+            if (!SLUG_RE.test(topic))
+                continue;
+            if (!topicIndexCache.has(topic)) {
+                const idx = await readJsonOr(entryIndexPath(topic), null);
+                topicIndexCache.set(topic, idx);
+            }
+            const topicIdx = topicIndexCache.get(topic) ?? null;
+            const topicTags = topicIdx && Array.isArray(topicIdx.tags) ? topicIdx.tags : [];
+            const chunkRefs = topicIdx && Array.isArray(topicIdx.chunks) ? topicIdx.chunks : [];
+            const topicTagHit = (term) => topicTags.some(t => t.toLowerCase().includes(term));
+            const chunksDir = entrySubdir(topic, 'chunks');
+            let files;
+            try {
+                files = await fs.readdir(chunksDir);
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                const chunkId = file.replace(/\.md$/, '');
+                if (!CHUNK_RE.test(chunkId))
+                    continue;
+                const text = await fs.readFile(path.join(chunksDir, file), 'utf8');
+                const textLc = text.toLowerCase();
+                const ref = chunkRefs.find(c => c.id === chunkId);
+                const refTitle = (ref?.title ?? '').toLowerCase();
+                const refSummary = (ref?.summary ?? '').toLowerCase();
+                const refTags = ref && Array.isArray(ref.tags) ? ref.tags : [];
+                let score = 0;
+                for (const term of terms) {
+                    // 每个字段每词只计一次分，body 不按出现次数刷分
+                    if (refTitle.includes(term))
+                        score += 3;
+                    if (refTags.some(t => t.toLowerCase().includes(term)))
+                        score += 2;
+                    if (topicTagHit(term))
+                        score += 2;
+                    if (refSummary.includes(term))
+                        score += 1;
+                    if (textLc.includes(term))
+                        score += 1;
+                }
+                if (score === 0)
+                    continue;
+                const wholeQueryHit = textLc.includes(q) ||
+                    refTitle.includes(q) ||
+                    refSummary.includes(q) ||
+                    topicTagHit(q) ||
+                    refTags.some(t => t.toLowerCase().includes(q));
+                candidates.push({ topic, chunkId, title: parseChunkTitle(text), score, wholeQueryHit });
+            }
+        }
+        return candidates;
+    }
+    async function searchChunks(query) {
+        if (!query.trim())
+            return [];
+        return (await scanChunks(query))
+            .filter(c => c.wholeQueryHit)
+            .map(({ topic, chunkId, title }) => ({ topic, chunkId, title }));
+    }
+    async function queryKnowledge(query, limit = 3) {
+        const capped = Math.min(Math.max(limit, 1), 5);
+        const candidates = (await scanChunks(query))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, capped);
+        const hits = [];
+        for (const c of candidates) {
+            const body = await readChunk(c.topic, c.chunkId);
+            hits.push({ topic: c.topic, chunkId: c.chunkId, title: c.title, body });
+        }
+        return hits;
+    }
+    async function readChunk(topic, chunkId) {
+        assertTopic(topic);
+        assertChunkId(chunkId);
+        const filePath = path.join(entrySubdir(topic, 'chunks'), `${chunkId}.md`);
+        // 二次校验：解析后路径必须在 root/<topic>/chunks/ 内
+        const resolved = path.resolve(filePath);
+        const expectedDir = path.resolve(docsDir, topic, 'chunks');
+        if (!resolved.startsWith(expectedDir + path.sep)) {
+            throw new Error('access denied: chunk path escapes chunks dir');
+        }
+        return fs.readFile(resolved, 'utf8');
+    }
+    // ============================================================
+    // 主题索引（async；缺失/坏 → null）
+    // ============================================================
+    async function readTopicIndex(slug) {
+        try {
+            const raw = await fs.readFile(entryIndexPath(slug), 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function readSidecarIndex(slug) {
+        try {
+            const raw = await fs.readFile(entryIndexPath(`${slug}.old`), 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    // ============================================================
+    // 物理操作（sync）
+    // ============================================================
+    function assertSlug(slug, field = 'slug') {
+        if (!SLUG_RE.test(slug)) {
+            throw new Error(`invalid ${field}: ${slug}`);
+        }
+    }
+    /** 重建 topic 目录：sources/（抓取/上传原料）+ chunks/（后续产物） */
+    function prepareTopic(slug) {
+        const dir = entryDir(slug);
+        fsSync.rmSync(dir, { recursive: true, force: true });
+        fsSync.mkdirSync(path.join(dir, 'sources'), { recursive: true });
+        fsSync.mkdirSync(path.join(dir, 'chunks'), { recursive: true });
+    }
+    /** 写一份原料到 <slug>/sources/source-NNN.md */
+    function writeSourceFile(slug, index, url, text) {
+        const dir = entrySubdir(slug, 'sources');
+        fsSync.mkdirSync(dir, { recursive: true });
+        const name = `source-${String(index + 1).padStart(3, '0')}.md`;
+        fsSync.writeFileSync(path.join(dir, name), `Source: ${url}\n\n${text}`, 'utf8');
+    }
+    /** 数 <slug>/sources 下 .md 文件数量；目录不存在按 0 */
+    function countSourceFiles(slug) {
+        try {
+            return fsSync.readdirSync(entrySubdir(slug, 'sources')).filter((f) => f.endsWith('.md')).length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    function readSourceBodies(slug) {
+        const dir = entrySubdir(slug, 'sources');
+        const files = fsSync.readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+        return files.map((f) => fsSync.readFileSync(path.join(dir, f), 'utf8'));
+    }
+    function writeOutline(slug, items) {
+        assertSlug(slug, 'slug');
+        const topicDir = entryDir(slug);
+        if (!fsSync.existsSync(topicDir))
+            throw new Error(`topic dir not prepared: ${slug}`);
+        if (!fsSync.existsSync(path.join(topicDir, 'sources')))
+            throw new Error(`sources missing for topic: ${slug}`);
+        fsSync.writeFileSync(path.join(topicDir, 'outline.json'), JSON.stringify({ slug, source: 'sources/', items }, null, 2));
+    }
+    function readOutlineItems(slug) {
+        const outlinePath = path.join(entryDir(slug), 'outline.json');
+        if (!fsSync.existsSync(outlinePath))
+            throw new Error('outline 未生成');
+        const outline = JSON.parse(fsSync.readFileSync(outlinePath, 'utf8'));
+        return outline.items;
+    }
+    function parkTopic(slug) {
+        fsSync.renameSync(entryDir(slug), entryDir(`${slug}.old`));
+    }
+    function restoreTopic(slug) {
+        fsSync.renameSync(entryDir(`${slug}.old`), entryDir(slug));
+    }
+    function renameTopic(slug, newSlug) {
+        fsSync.renameSync(entryDir(slug), entryDir(newSlug));
+    }
+    function readEntryIndexSync(entry) {
+        return JSON.parse(fsSync.readFileSync(entryIndexPath(entry), 'utf8'));
+    }
+    function writeEntryIndexSync(entry, idx) {
+        fsSync.writeFileSync(entryIndexPath(entry), JSON.stringify(idx, null, 2));
+    }
+    function readRootIndexSync() {
+        return JSON.parse(fsSync.readFileSync(rootIndexPath(), 'utf8'));
+    }
+    function writeRootIndexSync(root) {
+        fsSync.writeFileSync(rootIndexPath(), JSON.stringify(root, null, 2));
+    }
+    /** 列出 dir 下的 .md 文件名（排序）；目录缺失视为空 */
+    function listEntryMd(entry, subdir) {
+        try {
+            return fsSync.readdirSync(entrySubdir(entry, subdir)).filter(f => f.endsWith('.md')).sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    function mkdirEntrySubdir(entry, subdir) {
+        fsSync.mkdirSync(entrySubdir(entry, subdir), { recursive: true });
+    }
+    function readEntryFile(entry, subdir, file) {
+        return fsSync.readFileSync(path.join(entrySubdir(entry, subdir), file));
+    }
+    function writeEntryFile(entry, subdir, file, body) {
+        fsSync.writeFileSync(path.join(entrySubdir(entry, subdir), file), body);
+    }
+    function unlinkEntryFile(entry, subdir, file) {
+        fsSync.unlinkSync(path.join(entrySubdir(entry, subdir), file));
+    }
+    function removeEntry(entry) {
+        fsSync.rmSync(entryDir(entry), { recursive: true, force: true });
+    }
+    // 阻断：docsDir 下存在任何 .old 旁挂目录时抛错，要求人工先处理。
+    // docsDir 本身缺失时直接让 readdirSync 抛错（调用方本就应在已初始化的库上学习）。
+    function assertNoOldSidecars() {
+        const oldDir = fsSync.readdirSync(docsDir).find(name => name.endsWith('.old'));
+        if (oldDir) {
+            throw new Error(`检测到未清理的旁挂目录 ${oldDir}，请手工处理后再学习`);
+        }
+    }
+    // ============================================================
+    // 沙箱判定
+    // ============================================================
+    function assertInside(absPath) {
+        const resolved = path.resolve(absPath);
+        if (resolved !== docsDir && !resolved.startsWith(docsDir + path.sep)) {
+            throw new Error(`Access denied: ${absPath} is outside the knowledge directory ${docsDir}`);
+        }
+        return resolved;
+    }
+    function assertNotManagedIndexJson(absPath) {
+        if (path.basename(absPath) === 'index.json') {
+            throw new Error('index.json is managed by add_topic/add_chunk tools, do not write directly');
+        }
+    }
+    return {
+        root: docsDir,
+        listTopics,
+        getTopic,
+        searchChunks,
+        queryKnowledge,
+        readChunk,
+        upsertTopic,
+        upsertChunkRef,
+        readTopicIndex,
+        readSidecarIndex,
+        assertSlug,
+        prepareTopic,
+        writeSourceFile,
+        countSourceFiles,
+        readSourceBodies,
+        writeOutline,
+        readOutlineItems,
+        parkTopic,
+        restoreTopic,
+        renameTopic,
+        readEntryIndexSync,
+        writeEntryIndexSync,
+        readRootIndexSync,
+        writeRootIndexSync,
+        listEntryMd,
+        mkdirEntrySubdir,
+        readEntryFile,
+        writeEntryFile,
+        unlinkEntryFile,
+        removeEntry,
+        assertNoOldSidecars,
+        assertInside,
+        assertNotManagedIndexJson,
+    };
+}
+// 默认单例：绑生产 docsDir
+export const vault = createVault(path.join(dataDir, 'docs'));

package/ecosystem.config.cjs

@@ -15,7 +15,8 @@ module.exports = {
     exec_mode: 'fork',  // Use fork mode for ESM compatibility
     autorestart: true,
     watch: false,
-    max_memory_restart: '200M',
+    // 进程 baseline ~184MB 贴近 200M 线导致频繁 OOM kill，内存增长另排查
+    max_memory_restart: '600M',
     env: {
       NODE_ENV: 'production',
       CONFIG_PATH: configPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cc-monitoring/proxy-core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Claude Code 代理工具 + Token 消耗监控面板",
   "keywords": [
     "claude-code-proxy",