@cc-monitoring/proxy-core 0.2.0 → 0.2.2

package/dist/utils/knowledge-store.js

@@ -14,84 +14,107 @@ function assertChunkId(chunkId) {
         throw new Error(`invalid chunk id: ${chunkId} (expect chunk-NNN)`);
     }
 }
-/** 解析 "- <slug>: <摘要>" 行（自然 markdown 列表） */
-function parseRootIndex(text) {
-    const out = [];
-    const re = /^- ([a-z0-9][a-z0-9-]*):\s*(.+?)\s*$/m;
-    for (const line of text.split('\n')) {
-        const m = line.match(re);
-        if (m)
-            out.push({ slug: m[1], title: m[1], summary: m[2].trim() });
-    }
-    return out;
-}
-/** 解析主题 INDEX.md 的 "## 元数据" 区块：`- 名称: xxx` / `- 标签: a, b, c` */
-function parseTopicMeta(text) {
-    let title = '';
-    let tags = [];
-    const nameRe = /^- 名称:\s*(.+?)\s*$/m;
-    const tagsRe = /^- 标签:\s*(.+?)\s*$/m;
-    const nameM = text.match(nameRe);
-    if (nameM)
-        title = nameM[1].trim();
-    const tagsM = text.match(tagsRe);
-    if (tagsM) {
-        tags = tagsM[1].split(',').map(s => s.trim()).filter(Boolean);
-    }
-    return { title, tags };
-}
-/** 解析片段清单行 "- chunk-NNN: <标题> — <描述>" 或 "- chunk-NNN: <描述>" */
-function parseChunkList(text) {
-    const out = [];
-    const re = /^- (chunk-\d{3}):\s*(.+?)\s*$/m;
-    for (const line of text.split('\n')) {
-        const m = line.match(re);
-        if (!m)
-            continue;
-        const rest = m[2].trim();
-        const dashIdx = rest.indexOf(' — ');
-        let title;
-        let summary;
-        if (dashIdx >= 0) {
-            title = rest.slice(0, dashIdx).trim();
-            summary = rest.slice(dashIdx + 3).trim();
-        }
-        else {
-            title = rest;
-            summary = rest;
-        }
-        out.push({ id: m[1], title, summary });
-    }
-    return out;
-}
 /** 从 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;
+    }
+}
 export function createKnowledgeStore(root) {
     async function listTopics() {
-        const indexPath = path.join(root, 'INDEX.md');
+        const indexPath = path.join(root, 'index.json');
+        const parsed = await readJsonOr(indexPath, { topics: [] });
+        return Array.isArray(parsed.topics) ? parsed.topics : [];
+    }
+    async function getTopic(topic) {
+        assertTopic(topic);
+        const indexPath = path.join(root, topic, 'index.json');
+        let meta;
         try {
             const text = await fs.readFile(indexPath, 'utf8');
-            return parseRootIndex(text);
+            meta = JSON.parse(text);
         }
-        catch {
-            return [];
+        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`);
         }
-    }
-    async function getTopic(topic) {
-        assertTopic(topic);
-        const indexPath = path.join(root, topic, 'INDEX.md');
-        const text = await fs.readFile(indexPath, 'utf8');
-        const meta = parseTopicMeta(text);
         return {
             title: meta.title || topic,
-            tags: meta.tags,
+            tags: Array.isArray(meta.tags) ? meta.tags : [],
             sources: [],
-            chunks: parseChunkList(text),
+            chunks: Array.isArray(meta.chunks) ? meta.chunks : [],
         };
     }
+    async function upsertTopic(input) {
+        assertTopic(input.slug);
+        const { slug, title, summary, tags } = input;
+        // 1. 更新根 index.json
+        const rootPath = path.join(root, 'index.json');
+        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 = path.join(root, slug);
+        const topicPath = path.join(topicDir, 'index.json');
+        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 } = input;
+        const topicPath = path.join(root, topic, 'index.json');
+        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;
+        }
+        else {
+            topicIdx.chunks.push({ id: chunkId, title, summary });
+        }
+        await fs.writeFile(topicPath, JSON.stringify(topicIdx, null, 2), 'utf8');
+    }
     async function searchChunks(query) {
         if (!query.trim())
             return [];
@@ -138,7 +161,7 @@ export function createKnowledgeStore(root) {
         }
         return fs.readFile(resolved, 'utf8');
     }
-    return { listTopics, getTopic, searchChunks, readChunk };
+    return { listTopics, getTopic, searchChunks, readChunk, upsertTopic, upsertChunkRef };
 }
 // 默认单例：绑生产 docsDir
 export const knowledgeStore = createKnowledgeStore(docsDir);

package/dist/utils/pi-runtime.js

@@ -61,13 +61,13 @@ async function getRuntime(port) {
 }
 // 默认 system prompt 兜底（system.md 不存在时使用）
 const DEFAULT_SYSTEM_PROMPT = `You are a knowledge management AI operating inside a sandbox.
-Your knowledge directory (~/.cc-monitoring/docs) stores structured knowledge.
+Your knowledge directory (~/.cc-monitoring/docs) stores a **dictionary**: concise, distilled entries a future reader can look up. You do NOT copy source text — you digest it.
 
 STRUCTURE:
 - Each topic is a subfolder: docs/<topic-slug>/
-- Each topic has INDEX.md (metadata + chunk list, NO body)
-- Bodies live in docs/<topic-slug>/chunks/chunk-NNN.md (300-500 words each)
-- Root INDEX.md lists all topics with one-line summaries
+- Each topic has docs/<slug>/index.json (metadata + chunk list, NO body)
+- Bodies live in docs/<topic-slug>/chunks/chunk-NNN.md
+- Root docs/index.json lists all topics as JSON
 
 CHAT MODE (answer questions):
 1. Call list_topics to see available topics
@@ -77,13 +77,37 @@ CHAT MODE (answer questions):
 5. Prefer answering from knowledge base chunks when relevant content exists; cite which chunks you used
 6. If no relevant chunk exists, answer from your general knowledge; if you truly don't know, say so
 
-LEARN MODE (distill web pages into knowledge):
+LEARN MODE (distill material into a dictionary — NOT a copy of the source):
+0. First READ all input material end-to-end. Do NOT start writing chunk-by-chunk as you read. Before writing, internally outline the distinct concepts you extracted. Only then begin.
 1. Call list_topics first to check for existing similar topics — reuse, don't duplicate
-2. Use browser tools to read web pages
-3. Distill into 300-500 word chunks, one point per chunk
-4. Write chunks to docs/<topic-slug>/chunks/chunk-NNN.md (include source URL + quote)
-5. Update docs/<topic-slug>/INDEX.md chunk list + metadata
-6. Update root INDEX.md topic line if new topic
+2. Use browser tools to read web pages if the input is a URL
+3. For each concept, produce a dictionary entry. An entry is a STAND-ALONE, retrievable note — the future reader has NO access to the source document. It must make sense alone.
+4. Write each chunk as markdown with this structure (write in the source document's language):
+
+   \`\`\`
+   # <term or concept name>
+
+   - 定义 / Definition: <one sentence, in your own words>
+   - 是什么 / What it is: <2-4 bullets, the core idea>
+   - 不是什么 / What it is NOT: <common confusions, if any>
+   - 关键点 / Key points: <3-6 bullets, the load-bearing facts>
+   - 适用场景 / When to use: <where this applies>
+   - 误区 / Pitfalls: <common mistakes, edge cases>
+   - 来源 / Source: <url>
+   \`\`\`
+
+5. RULES — these are hard constraints:
+   - NO large quotes. A short quote (≤2 sentences) is allowed ONLY as evidence under a bullet you already wrote in your own words.
+   - Every bullet must be YOU re-expressing the idea. If you find yourself copying sentences, stop and rephrase.
+   - One concept per chunk. Do not bundle unrelated ideas into one entry.
+   - If the material is thin on a concept, write what exists; do NOT invent content to fill sections. Omit empty sections.
+6. Write chunks to docs/<topic-slug>/chunks/chunk-NNN.md (number sequentially from 001)
+7. Call add_topic(slug, title, summary, tags) to register/update the topic in the index
+8. Call add_chunk(topic, chunk_id, title, summary) for each chunk you wrote
+9. Do NOT write or edit index.json files directly — use add_topic/add_chunk tools
+
+FINISHING:
+- After all chunks are written, output a plain summary: the topic created/updated, and the list of chunk titles. Do NOT ask the user what to deepen next. The learning task is complete.
 `;
 /** 从 ~/.cc-monitoring/pi/system.md 读取自定义 system prompt，不存在则用兜底文本 */
 function loadSystemPrompt() {
@@ -159,6 +183,51 @@ function buildKnowledgeTools() {
                 }
             },
         },
+        {
+            name: 'add_topic',
+            label: 'add_topic',
+            description: '注册或更新一个知识主题（原子读改写 index.json）。LLM 不要直接写 index.json 文件。',
+            parameters: Type.Object({
+                slug: Type.String({ description: '主题 slug，小写连字符，如 react-hooks' }),
+                title: Type.String(),
+                summary: Type.String(),
+                tags: Type.Array(Type.String()),
+            }),
+            async execute(_id, params) {
+                try {
+                    await knowledgeStore.upsertTopic(params);
+                    return ok('topic added');
+                }
+                catch (e) {
+                    return err(e);
+                }
+            },
+        },
+        {
+            name: 'add_chunk',
+            label: 'add_chunk',
+            description: '登记或更新一个 chunk 在主题索引中的引用（原子读改写）。写完 chunk-NNN.md 正文后调用。',
+            parameters: Type.Object({
+                topic: Type.String(),
+                chunk_id: Type.String({ description: '如 chunk-001' }),
+                title: Type.String(),
+                summary: Type.String(),
+            }),
+            async execute(_id, params) {
+                try {
+                    await knowledgeStore.upsertChunkRef({
+                        topic: params.topic,
+                        chunkId: params.chunk_id,
+                        title: params.title,
+                        summary: params.summary,
+                    });
+                    return ok('chunk ref added');
+                }
+                catch (e) {
+                    return err(e);
+                }
+            },
+        },
     ];
 }
 /** 按模式构建工具集（ToolDefinition 数组，用于 customTools） */
@@ -184,7 +253,7 @@ function buildToolAllowlist(mode) {
     if (mode === 'chat') {
         return base;
     }
-    return [...base, 'write', 'edit', ...browserTools.map((t) => t.name)];
+    return [...base, 'add_topic', 'add_chunk', 'write', 'edit', ...browserTools.map((t) => t.name)];
 }
 export async function createPiSession(options) {
     const runtime = await getRuntime(options.port);

package/dist/utils/pi-sandbox-ops.js

@@ -16,6 +16,15 @@ export function assertInside(absPath) {
     }
     return resolved;
 }
+/**
+ * 守卫：index.json 由 add_topic/add_chunk 工具原子维护，
+ * 禁止 LLM 通过 write/edit 直接改写。
+ */
+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');
+    }
+}
 // 统一 access：校验可读性
 async function access(absolutePath) {
     const p = assertInside(absolutePath);
@@ -35,6 +44,7 @@ export const sandboxReadOps = {
 export const sandboxWriteOps = {
     async writeFile(absolutePath, content) {
         const p = assertInside(absolutePath);
+        assertNotManagedIndexJson(p);
         await fs.writeFile(p, content, 'utf8');
     },
     async mkdir(dir) {
@@ -50,6 +60,7 @@ export const sandboxEditOps = {
     },
     async writeFile(absolutePath, content) {
         const p = assertInside(absolutePath);
+        assertNotManagedIndexJson(p);
         await fs.writeFile(p, content, 'utf8');
     },
     access,

package/package.json

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