@cc-monitoring/proxy-core 0.1.8 → 0.1.9

package/dist/utils/knowledge-store.js

@@ -0,0 +1,144 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { dataDir } from './paths.js';
+const docsDir = path.join(dataDir, 'docs');
+const TOPIC_RE = /^[a-z0-9][a-z0-9-]*$/;
+const CHUNK_RE = /^chunk-\d{3}$/;
+function assertTopic(topic) {
+    if (!TOPIC_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)`);
+    }
+}
+/** 解析 "- <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() : '';
+}
+export function createKnowledgeStore(root) {
+    async function listTopics() {
+        const indexPath = path.join(root, 'INDEX.md');
+        try {
+            const text = await fs.readFile(indexPath, 'utf8');
+            return parseRootIndex(text);
+        }
+        catch {
+            return [];
+        }
+    }
+    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,
+            sources: [],
+            chunks: parseChunkList(text),
+        };
+    }
+    async function searchChunks(query) {
+        if (!query.trim())
+            return [];
+        const hits = [];
+        const q = query.toLowerCase();
+        let entries;
+        try {
+            entries = await fs.readdir(root);
+        }
+        catch {
+            return [];
+        }
+        for (const topic of entries) {
+            if (!TOPIC_RE.test(topic))
+                continue;
+            const chunksDir = path.join(root, topic, 'chunks');
+            let files;
+            try {
+                files = await fs.readdir(chunksDir);
+            }
+            catch {
+                continue;
+            }
+            for (const file of files) {
+                if (!CHUNK_RE.test(file.replace(/\.md$/, '')))
+                    continue;
+                const text = await fs.readFile(path.join(chunksDir, file), 'utf8');
+                if (text.toLowerCase().includes(q)) {
+                    hits.push({ topic, chunkId: file.replace(/\.md$/, ''), title: parseChunkTitle(text) });
+                }
+            }
+        }
+        return hits;
+    }
+    async function readChunk(topic, chunkId) {
+        assertTopic(topic);
+        assertChunkId(chunkId);
+        const filePath = path.join(root, topic, 'chunks', `${chunkId}.md`);
+        // 二次校验：解析后路径必须在 root/<topic>/chunks/ 内
+        const resolved = path.resolve(filePath);
+        const expectedDir = path.resolve(root, topic, 'chunks');
+        if (!resolved.startsWith(expectedDir + path.sep)) {
+            throw new Error('access denied: chunk path escapes chunks dir');
+        }
+        return fs.readFile(resolved, 'utf8');
+    }
+    return { listTopics, getTopic, searchChunks, readChunk };
+}
+// 默认单例：绑生产 docsDir
+export const knowledgeStore = createKnowledgeStore(docsDir);

package/dist/utils/pi-browser-tools.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+/**
+ * 统一封装 ego-browser CLI：spawn 子进程 + 写入 Node 脚本 stdin，返回 cliLog 文本。
+ * 每次调用独立进程，靠 useOrCreateTaskSpace 在同一 task space 复用 tab。
+ */
+export declare function runEgoBrowser(scriptBody: string, opts?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<string>;
+export declare const browserTools: ToolDefinition[];

package/dist/utils/pi-browser-tools.js

@@ -0,0 +1,246 @@
+import { spawn } from 'node:child_process';
+import { Type } from 'typebox';
+/**
+ * 统一封装 ego-browser CLI：spawn 子进程 + 写入 Node 脚本 stdin，返回 cliLog 文本。
+ * 每次调用独立进程，靠 useOrCreateTaskSpace 在同一 task space 复用 tab。
+ */
+export function runEgoBrowser(scriptBody, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    return new Promise((resolve, reject) => {
+        // 头部自动注入 task space 复用调用
+        const script = `const task = await useOrCreateTaskSpace('knowledge-learn')\n${scriptBody}`;
+        const child = spawn('ego-browser', ['nodejs'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (err, out) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (err) {
+                // 把 stderr 附加到错误里，帮助排查
+                const detail = stderr.trim() ? `\n--- stderr ---\n${stderr.trim()}` : '';
+                reject(new Error(`${err.message}${detail}`));
+            }
+            else {
+                resolve(out ?? stdout);
+            }
+        };
+        const timer = setTimeout(() => {
+            finish(new Error(`ego-browser timed out after ${timeoutMs}ms`));
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        const onAbort = () => {
+            finish(new Error('ego-browser aborted'));
+            child.kill('SIGKILL');
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        const cleanup = () => {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onAbort);
+        };
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                finish(new Error('ego-browser CLI not found. Please install ego-browser first.'));
+            }
+            else {
+                finish(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            if (code === 0) {
+                finish(null, stdout);
+            }
+            else {
+                // 非 0 退出：stderr 可能含错误；stdout 仍作为错误消息的一部分返回
+                const detail = stdout.trim() ? `\n--- stdout ---\n${stdout.trim()}` : '';
+                finish(new Error(`ego-browser exited with code ${code}${detail}`));
+            }
+        });
+        child.stdin.end(script, 'utf-8');
+    });
+}
+// ---------- 工具实现辅助 ----------
+/** 把字符串参数安全注入脚本：JSON.stringify 自动处理引号 / 反斜杠 / 换行 */
+const jsLit = (v) => JSON.stringify(v);
+/** 构造 pi AgentToolResult（content + details 字段） */
+const ok = (text) => ({
+    content: [{ type: 'text', text }],
+    details: undefined,
+});
+const navigateSchema = Type.Object({
+    url: Type.String({ description: '目标 URL，必须是 http(s) 完整地址' }),
+    wait: Type.Optional(Type.Boolean({ description: '是否等待页面加载完成，默认 true' })),
+});
+const snapshotSchema = Type.Object({
+    scope: Type.Optional(Type.String({
+        description: "snapshotText 的 scope：'full_page'（默认）或 'only_within_viewport'",
+    })),
+});
+const screenshotSchema = Type.Object({});
+const clickSchema = Type.Object({
+    target: Type.String({
+        description: "点击目标：@N / CSS / 'xpath=...' / 'loc=...'，或 [x,y] 视口坐标数组",
+    }),
+    label: Type.Optional(Type.String({ description: '可选 3-6 字动作描述，用于高亮' })),
+});
+const typeSchema = Type.Object({
+    target: Type.String({ description: '输入框定位：@N / CSS / xpath=... / loc=...' }),
+    text: Type.String({ description: '要填入的文本内容' }),
+    submit: Type.Optional(Type.Boolean({ description: 'true 则填完后按 Enter，默认 false' })),
+});
+const scrollSchema = Type.Object({
+    direction: Type.String({
+        enum: ['down', 'up', 'bottom'],
+        description: "滚动方向：'down' / 'up' / 'bottom'（滚到底并触发懒加载）",
+    }),
+    amount: Type.Optional(Type.Number({ description: 'down/up 时的滚动像素量，默认 900' })),
+});
+const evaluateSchema = Type.Object({
+    expression: Type.String({
+        description: '页面内 JS 字符串。复杂逻辑用 IIFE：(() => { ... })()',
+    }),
+});
+const fetchSchema = Type.Object({
+    url: Type.String({ description: '要抓取的 URL' }),
+});
+const pressKeySchema = Type.Object({
+    key: Type.String({ description: "CDP 键名，如 'Enter' / 'Escape' / 'ArrowDown'" }),
+});
+export const browserTools = [
+    {
+        name: 'browser_navigate',
+        label: 'browser_navigate',
+        description: '在 ego-browser 的 knowledge-learn task space 中打开或复用 tab 到给定 URL。wait=true（默认）会等页面加载，timeout 20s。',
+        parameters: navigateSchema,
+        async execute(_id, params, signal) {
+            const url = jsLit(params.url);
+            const wait = params.wait ?? true;
+            const body = `
+await openOrReuseTab(${url}, { wait: ${wait}, timeout: 20 })
+const info = await pageInfo()
+cliLog(JSON.stringify(info))
+`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_snapshot',
+        label: 'browser_snapshot',
+        description: '获取当前页面的可访问性语义树（含 @N / loc= 引用），是后续 click/fillInput 定位元素的依据。默认 scope=full_page 覆盖整页。',
+        parameters: snapshotSchema,
+        async execute(_id, params, signal) {
+            const scope = params.scope ?? 'full_page';
+            const body = `cliLog(await snapshotText({ scope: ${jsLit(scope)} }))`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_screenshot',
+        label: 'browser_screenshot',
+        description: '对当前页面视口截图。返回 ego 输出的图片说明 / 路径文本。',
+        parameters: screenshotSchema,
+        async execute(_id, _params, signal) {
+            return ok(await runEgoBrowser('cliLog(await captureScreenshot())', { signal }));
+        },
+    },
+    {
+        name: 'browser_click',
+        label: 'browser_click',
+        description: '点击元素。target 支持 @N（来自最近一次 snapshotText）、CSS 选择器、xpath=...、loc=...（推荐长期稳定引用）。label 是 3-6 字动作描述，会触发高亮动画。',
+        parameters: clickSchema,
+        async execute(_id, params, signal) {
+            const target = jsLit(params.target);
+            const label = params.label ? `, { label: ${jsLit(params.label)} }` : '';
+            const body = `await click(${target}${label})\ncliLog('clicked: ${params.target}')`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_type',
+        label: 'browser_type',
+        description: '向输入框填充文本。target 同 browser_click（@N / CSS / xpath / loc）。submit=true 时填完后按 Enter（常用于搜索框）。',
+        parameters: typeSchema,
+        async execute(_id, params, signal) {
+            const target = jsLit(params.target);
+            const text = jsLit(params.text);
+            const submitBlock = params.submit ? `\nawait pressKey('Enter')` : '';
+            const body = `
+await fillInput(${target}, ${text})${submitBlock}
+cliLog('filled: ${params.target}')
+`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_scroll',
+        label: 'browser_scroll',
+        description: '滚动页面。direction=down/up 按 amount 像素滚动；direction=bottom 自动滚到底并尝试触发懒加载（最多 20 步）。',
+        parameters: scrollSchema,
+        async execute(_id, params, signal) {
+            let body;
+            if (params.direction === 'bottom') {
+                body = `
+await scrollToBottomUntil(
+  async () => false,
+  { step: 900, wait: 1, maxSteps: 20 }
+)
+cliLog('scrolled to bottom')
+`;
+            }
+            else {
+                const amount = params.amount ?? 900;
+                const signed = params.direction === 'down' ? amount : -amount;
+                body = `
+await scrollBy(${signed})
+cliLog('scrolled ${params.direction} ${amount}px')
+`;
+            }
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_evaluate',
+        label: 'browser_evaluate',
+        description: '在页面上下文执行 JS 字符串（等价于 Runtime.evaluate），返回序列化结果。多步逻辑请包成 IIFE：(() => { ... })()。不要把它当 Puppeteer page.evaluate(fn, ...args) 用。',
+        parameters: evaluateSchema,
+        async execute(_id, params, signal) {
+            const expr = jsLit(params.expression);
+            const body = `cliLog(JSON.stringify(await js(${expr})))`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_fetch',
+        label: 'browser_fetch',
+        description: '在当前浏览器页面上下文发起 fetch（复用登录态 / Cookie），返回响应正文文本。适合抓取需要鉴权的页面 JSON 或 HTML。',
+        parameters: fetchSchema,
+        async execute(_id, params, signal) {
+            const url = jsLit(params.url);
+            const body = `cliLog(await browserFetch(${url}))`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+    {
+        name: 'browser_press_key',
+        label: 'browser_press_key',
+        description: '在当前焦点元素按下键盘按键。key 用 CDP 键名，如 "Enter" / "Escape" / "Tab" / "ArrowDown" / "Control+A"。',
+        parameters: pressKeySchema,
+        async execute(_id, params, signal) {
+            const key = jsLit(params.key);
+            const body = `await pressKey(${key})\ncliLog('pressed: ${params.key}')`;
+            return ok(await runEgoBrowser(body, { signal }));
+        },
+    },
+];

package/dist/utils/pi-runtime.d.ts

@@ -0,0 +1,8 @@
+import { type AgentSession } from '@earendil-works/pi-coding-agent';
+export type PiSessionMode = 'chat' | 'learn';
+export interface CreatePiSessionOptions {
+    cwd?: string;
+    port: number;
+    mode: PiSessionMode;
+}
+export declare function createPiSession(options: CreatePiSessionOptions): Promise<AgentSession>;

package/dist/utils/pi-runtime.js

@@ -0,0 +1,236 @@
+// pi SDK 单例工厂：把 pi coding-agent 接到本地 ccm proxy 上。
+// - ModelRuntime 懒加载，全局单例
+// - registerProvider 注册一个 "ccm" provider，走 anthropic-messages 协议到本地 proxy
+// - createPiSession() 返回一个新 AgentSession，cwd 钉死在 docsDir
+// - 按 chat / learn 两种模式挂载不同工具集
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { Type } from 'typebox';
+import { createAgentSession, DefaultResourceLoader, ModelRuntime, createWriteToolDefinition, createEditToolDefinition, } from '@earendil-works/pi-coding-agent';
+import { dataDir } from './paths.js';
+import { sandboxWriteOps, sandboxEditOps, } from './pi-sandbox-ops.js';
+import { browserTools } from './pi-browser-tools.js';
+import { knowledgeStore } from './knowledge-store.js';
+// 知识文档目录：所有文件工具的 cwd 和沙箱白名单根
+const docsDir = path.join(dataDir, 'docs');
+// pi agent 目录（auth / models / system.md）
+const agentDir = path.join(os.homedir(), '.cc-monitoring', 'pi');
+let runtimePromise = null;
+let runtimePort = 0;
+async function getRuntime(port) {
+    if (!runtimePromise || runtimePort !== port) {
+        runtimePort = port;
+        runtimePromise = (async () => {
+            fs.mkdirSync(agentDir, { recursive: true });
+            const runtime = await ModelRuntime.create({
+                authPath: path.join(agentDir, 'auth.json'),
+                modelsPath: path.join(agentDir, 'models.json'),
+                refreshOnCreate: false,
+                allowModelNetwork: false,
+            });
+            const baseUrl = `http://localhost:${port}`;
+            runtime.registerProvider('ccm', {
+                name: 'ccm',
+                baseUrl,
+                apiKey: 'unused',
+                api: 'anthropic-messages',
+                models: [
+                    {
+                        id: 'placeholder',
+                        name: 'ccm placeholder',
+                        api: 'anthropic-messages',
+                        baseUrl,
+                        input: ['text'],
+                        cost: {
+                            input: 0,
+                            output: 0,
+                            cacheRead: 0,
+                            cacheWrite: 0,
+                        },
+                        reasoning: true,
+                        contextWindow: 200000,
+                        maxTokens: 8192,
+                    },
+                ],
+            });
+            return runtime;
+        })();
+    }
+    return runtimePromise;
+}
+// 默认 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.
+
+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
+
+CHAT MODE (answer questions):
+1. Call list_topics to see available topics
+2. If topic is unclear, call search_chunks(query) to find relevant chunks across topics
+3. Call get_topic(topic) to see that topic's chunk list
+4. Call read_chunk(topic, chunk_id) for relevant chunks — only read chunks you need
+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):
+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
+`;
+/** 从 ~/.cc-monitoring/pi/system.md 读取自定义 system prompt，不存在则用兜底文本 */
+function loadSystemPrompt() {
+    const mdPath = path.join(agentDir, 'system.md');
+    try {
+        return fs.readFileSync(mdPath, 'utf8');
+    }
+    catch {
+        return DEFAULT_SYSTEM_PROMPT;
+    }
+}
+/** 构造知识检索领域工具（chat / learn 共用） */
+function buildKnowledgeTools() {
+    const ok = (text) => ({ content: [{ type: 'text', text }], details: undefined });
+    const err = (e) => ({ content: [{ type: 'text', text: `error: ${e instanceof Error ? e.message : String(e)}` }], details: undefined });
+    return [
+        {
+            name: 'list_topics',
+            label: 'list_topics',
+            description: '列出所有知识主题及一句话摘要。检索知识时第一步调用，发现有哪些主题可用。',
+            parameters: Type.Object({}),
+            async execute() {
+                try {
+                    return ok(JSON.stringify(await knowledgeStore.listTopics(), null, 2));
+                }
+                catch (e) {
+                    return err(e);
+                }
+            },
+        },
+        {
+            name: 'get_topic',
+            label: 'get_topic',
+            description: '获取某主题的元数据与片段清单（描述级，不含正文）。读正文前先调用，看有哪些 chunk。',
+            parameters: Type.Object({ topic: Type.String({ description: '主题 slug，如 react-hooks' }) }),
+            async execute(_id, params) {
+                try {
+                    return ok(JSON.stringify(await knowledgeStore.getTopic(params.topic), null, 2));
+                }
+                catch (e) {
+                    return err(e);
+                }
+            },
+        },
+        {
+            name: 'search_chunks',
+            label: 'search_chunks',
+            description: '跨主题关键词检索片段，返回命中清单（不含正文）。主题不明时用。',
+            parameters: Type.Object({ query: Type.String({ description: '搜索关键词' }) }),
+            async execute(_id, params) {
+                try {
+                    return ok(JSON.stringify(await knowledgeStore.searchChunks(params.query), null, 2));
+                }
+                catch (e) {
+                    return err(e);
+                }
+            },
+        },
+        {
+            name: 'read_chunk',
+            label: 'read_chunk',
+            description: '读取单个知识片段正文。一次只读一片。读前先 get_topic 发现 chunk id。',
+            parameters: Type.Object({
+                topic: Type.String({ description: '主题 slug' }),
+                chunk_id: Type.String({ description: 'chunk id，如 chunk-001' }),
+            }),
+            async execute(_id, params) {
+                try {
+                    return ok(await knowledgeStore.readChunk(params.topic, params.chunk_id));
+                }
+                catch (e) {
+                    return err(e);
+                }
+            },
+        },
+    ];
+}
+/** 按模式构建工具集（ToolDefinition 数组，用于 customTools） */
+function buildModeTools(mode) {
+    const knowledgeTools = buildKnowledgeTools();
+    if (mode === 'chat') {
+        // chat：只用领域工具，移除通用 read/grep/find/ls（防全量灌入）
+        return knowledgeTools;
+    }
+    // learn：领域工具（查重/读现有）+ write/edit + browser
+    // 注意：createXxxToolDefinition 返回带具体 schema 的 ToolDefinition<TParams, ...>，
+    // 与无泛型的 ToolDefinition 在 renderCall 上不协变，需要 as ToolDefinition 抹平。
+    return [
+        ...knowledgeTools,
+        createWriteToolDefinition(docsDir, { operations: sandboxWriteOps }),
+        createEditToolDefinition(docsDir, { operations: sandboxEditOps }),
+        ...browserTools,
+    ];
+}
+/** 按模式构建工具白名单（tools 字段，全小写） */
+function buildToolAllowlist(mode) {
+    const base = ['list_topics', 'get_topic', 'search_chunks', 'read_chunk'];
+    if (mode === 'chat') {
+        return base;
+    }
+    return [...base, 'write', 'edit', ...browserTools.map((t) => t.name)];
+}
+export async function createPiSession(options) {
+    const runtime = await getRuntime(options.port);
+    const model = runtime.getModel('ccm', 'placeholder');
+    if (!model) {
+        throw new Error('pi runtime: ccm/placeholder model not registered');
+    }
+    // cwd 钉死 docsDir，忽略传入的 process.cwd()
+    const cwd = options.cwd ?? docsDir;
+    // 闭包捕获：pi 的 sessionId 在 createAgentSession 返回后才知道，
+    // 但 before_provider_headers handler 是每次上游请求时才触发，
+    // 所以先放一个可变变量，返回 session 后再填值。
+    let currentSessionId = '';
+    const systemPrompt = loadSystemPrompt();
+    const modeTools = buildModeTools(options.mode);
+    const toolAllowlist = buildToolAllowlist(options.mode);
+    const resourceLoader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        extensionFactories: [
+            (pi) => {
+                // 注入 x-claude-code-session-id header（保留原有逻辑）
+                pi.on('before_provider_headers', (ev) => {
+                    if (currentSessionId) {
+                        ev.headers['x-claude-code-session-id'] = currentSessionId;
+                    }
+                });
+                // 通过 before_agent_start 事件注入 system prompt
+                pi.on('before_agent_start', () => {
+                    return { systemPrompt };
+                });
+            },
+        ],
+    });
+    await resourceLoader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir,
+        modelRuntime: runtime,
+        model,
+        noTools: 'builtin', // 禁用 pi 默认 read/bash/edit/write，保留 customTools
+        customTools: modeTools,
+        tools: toolAllowlist, // 全小写工具名白名单
+        resourceLoader,
+    });
+    // 在 session.prompt() 之前填入真实 sessionId
+    currentSessionId = session.sessionId;
+    return session;
+}

package/dist/utils/pi-sandbox-ops.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 校验传入路径必须在 docsDir 内，并返回归一化后的绝对路径。
+ * 越界则抛错，阻断 fs 调用。
+ */
+export declare function assertInside(absPath: string): string;
+declare function access(absolutePath: string): Promise<void>;
+export declare const sandboxReadOps: {
+    readFile(absolutePath: string): Promise<Buffer>;
+    access: typeof access;
+    detectImageMimeType: () => Promise<string | null | undefined>;
+};
+export declare const sandboxWriteOps: {
+    writeFile(absolutePath: string, content: string): Promise<void>;
+    mkdir(dir: string): Promise<void>;
+};
+export declare const sandboxEditOps: {
+    readFile(absolutePath: string): Promise<Buffer>;
+    writeFile(absolutePath: string, content: string): Promise<void>;
+    access: typeof access;
+};
+export declare const sandboxGrepOps: {
+    isDirectory(absolutePath: string): Promise<boolean>;
+    readFile(absolutePath: string): Promise<string>;
+};
+export declare const sandboxFindOps: {
+    exists(absolutePath: string): Promise<boolean>;
+    glob(pattern: string, cwd: string, options: {
+        ignore: string[];
+        limit: number;
+    }): Promise<string[]>;
+};
+export declare function globMatch(relPosixPath: string, pattern: string): boolean;
+export declare const sandboxLsOps: {
+    exists(absolutePath: string): Promise<boolean>;
+    stat(absolutePath: string): Promise<{
+        isDirectory: () => boolean;
+    }>;
+    readdir(absolutePath: string): Promise<string[]>;
+};
+export {};