@bolloon/bolloon-agent 0.1.13 → 0.1.14

package/dist/agents/pi-sdk.js

@@ -4,6 +4,7 @@
  */
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { documentReader } from '../documents/reader.js';
 import { getMinimax } from '../constraints/index.js';
@@ -13,9 +14,12 @@ import { WorkflowEngine } from './workflow-engine.js';
 import { DeepThinkingEngine, AgentCoordinator } from '@bolloon/constraint-runtime';
 import { WorkflowPivotLoop, createDefaultPivotConfig } from './workflow-pivot-loop.js';
 import { p2pDocumentTools, initDocumentReceiver } from './p2p-document-tools.js';
+import { shellExec } from './shell-tool.js';
+import { getBranchPrefix, getCooldownMs } from './shell-guard.js';
 import { DiscoveredAgentsManager, createSocialHeartbeat } from '../social/heartbeat.js';
 import { getGlobalSharedContext } from '../social/global-shared-context.js';
 import { Session, SkillRegistry, saveSession, loadSession } from '@bolloon/constraint-runtime';
+import { loadSkillsFromPaths, defaultSkillPaths, describeSkill } from './skill-loader.js';
 const SHARED_SESSION_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'sessions');
 const PERSONA_PATH = path.join(process.env.HOME || '/tmp', '.bolloon', 'persona.json');
 export class PiSessionManager {
@@ -353,8 +357,72 @@ class PiAgentSession {
         this.initSession();
         initDocumentReceiver();
         this.registerTools();
+        this.loadSkills(config.skillsPaths);
         this.initHarness();
     }
+    /**
+     * 从 SKILL.md 目录加载 skills 进 skillRegistry.
+     *
+     * 路径解析优先级 (后者覆盖前者同名 skill):
+     *   1. 显式传入的 skillsPaths
+     *   2. ~/.bolloon/skills/         全局用户级
+     *   3. <cwd>/.bolloon/skills/     项目级
+     *   4. ~/.boll/skills/            全局 (兼容 bollharness 旧用户)
+     *   5. <bolloon-repo>/src/bollharness/.boll/skills/  bolloon 仓库内置 skill
+     *      (bolloon 项目本身用 pi-sdk 写核心, 这 19 个 skill 视为项目级 builtin)
+     *
+     * 静默忽略不存在的目录.
+     */
+    loadSkills(paths) {
+        let resolved;
+        if (paths && paths.length > 0) {
+            resolved = paths;
+        }
+        else {
+            resolved = [
+                ...defaultSkillPaths(os.homedir(), this.cwd),
+                // bolloon 仓库内置 skill (相对本 npm 包的位置)
+                this.findBolloonBuiltinSkillsPath(),
+            ].filter((p) => Boolean(p));
+        }
+        loadSkillsFromPaths(resolved)
+            .then((skills) => {
+            for (const s of skills) {
+                if (this.skillRegistry.has(s.name)) {
+                    this.skillRegistry.unregister(s.name);
+                }
+                this.skillRegistry.register(s);
+            }
+            console.log(`[loadSkills] 已加载 ${skills.length} 个 skill: ${skills.map(describeSkill).join(' | ')}`);
+        })
+            .catch((err) => {
+            console.error('[loadSkills] 加载失败:', err);
+        });
+    }
+    /**
+     * 定位 bolloon 仓库内置的 bollharness skill 目录.
+     * 向上回溯 cwd, 找第一个包含 src/bollharness/.boll/skills 的祖先.
+     * 找不到时返回 null (例如把 bolloon-agent 作为外部依赖安装时).
+     */
+    findBolloonBuiltinSkillsPath() {
+        let dir = this.cwd;
+        for (let i = 0; i < 6; i++) {
+            const candidate = path.join(dir, 'src', 'bollharness', '.boll', 'skills');
+            try {
+                if (fsSync.existsSync(candidate) && fsSync.statSync(candidate).isDirectory()) {
+                    return candidate;
+                }
+            }
+            catch {
+                // 忽略 stat 异常, 继续向上
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return null;
+    }
     async initHarness() {
         try {
             const { createBollharnessIntegration } = await import('../bollharness-integration/index.js');
@@ -583,6 +651,85 @@ class PiAgentSession {
         for (const tool of p2pDocumentTools) {
             this.tools.set(tool.name, tool);
         }
+        // Shell Exec 工具: 给 AI 跑受限的 shell 命令
+        // **只能** 跑白名单内的命令 (git/npm/tsc/vitest/cat/...)
+        // **不能** 改禁区路径 (见 shell-guard.ts 的 FORBIDDEN_PATH_PATTERNS)
+        // 沙箱 cwd: .bolloon-shell-sandbox/
+        this.tools.set('shell_exec', {
+            name: 'shell_exec',
+            description: '在沙箱里跑 shell 命令. 仅支持白名单内命令: git, npm, npx, tsx, tsc, vitest, cat, head, tail, ls, wc, echo, pwd, date, mkdir, touch. 禁止管道/重定向/rm -rf/sudo. 命中护栏黑名单会被拒.',
+            parameters: { command: '可执行文件 (必填, 必须在白名单)', args: '参数数组, 逗号分隔', timeoutMs: '超时毫秒, 默认 30000' },
+            execute: async (args) => {
+                const cmd = String(args.command || '').trim();
+                if (!cmd)
+                    return { success: false, error: 'command 必填' };
+                const argList = String(args.args || '').split(',').map(s => s.trim()).filter(Boolean);
+                const timeoutMs = Number(args.timeoutMs) || 30000;
+                const result = await shellExec(cmd, argList, { timeoutMs });
+                if (result.deniedByGuard) {
+                    return { success: false, error: result.error };
+                }
+                if (!result.success) {
+                    return { success: false, error: result.error, output: result.output };
+                }
+                return { success: true, output: result.output };
+            }
+        });
+        // self_improve 工具: AI 触发自我改进循环
+        // **必须** 在 branchPrefix 命名的分支上工作
+        // 心跳事件会自动调用; 用户对话里也能手动调
+        this.tools.set('self_improve', {
+            name: 'self_improve',
+            description: `触发自我改进循环. AI 会在分支 ${getBranchPrefix()}<timestamp> 上工作, 跑 tsc + vitest 验证, 通过后输出分支名给用户审. 冷却期由策略文件决定. 命中护栏禁区的改动会被拒.`,
+            parameters: { goal: '本轮改进目标 (1 句话)' },
+            execute: async (args) => {
+                const goal = String(args.goal || '').trim();
+                if (!goal)
+                    return { success: false, error: 'goal 必填' };
+                return await runSelfImproveLoop(goal);
+            }
+        });
+        // list_skills 工具: 列出当前 session 已加载的 skills
+        // 加载源: ~/.bolloon/skills/ → <cwd>/.bolloon/skills/ → ~/.boll/skills/
+        this.tools.set('list_skills', {
+            name: 'list_skills',
+            description: '列出当前 session 已加载的 skills 及其描述. Skills 是从 SKILL.md 文件加载的, 兼容 Anthropic Agent Skills 标准 frontmatter 和 bollharness 现有 frontmatter.',
+            parameters: {},
+            execute: async () => {
+                const skills = this.skillRegistry.list();
+                if (skills.length === 0) {
+                    return {
+                        success: true,
+                        output: '当前 session 没有加载任何 skill. 检查 ~/.bolloon/skills/ 或项目 .bolloon/skills/ 目录.',
+                    };
+                }
+                const lines = skills.map((s, i) => `${i + 1}. ${s.name} — ${s.description}`);
+                return { success: true, output: `已加载 ${skills.length} 个 skill:\n${lines.join('\n')}` };
+            }
+        });
+        // use_skill 工具: 加载指定 skill 的 body 进 LLM context
+        // Skills 协议核心: 把 SKILL.md body 作为 Markdown 指南返回, LLM 下一轮按它执行
+        this.tools.set('use_skill', {
+            name: 'use_skill',
+            description: '按名称加载一个 skill, 把它的 SKILL.md body 作为 Markdown 文档返回. 调用后 LLM 会在下一轮按 skill 指南执行. 与 shell_exec / read_document 这些 "能力工具" 不同, use_skill 是 "知识注入".',
+            parameters: { name: 'skill 名称 (用 list_skills 查可用的)' },
+            execute: async (args) => {
+                const name = String(args.name || '').trim();
+                if (!name)
+                    return { success: false, error: 'name 必填' };
+                if (!this.skillRegistry.has(name)) {
+                    const available = this.skillRegistry.list().map((s) => s.name).join(', ');
+                    return { success: false, error: `skill "${name}" 未找到. 已加载: ${available || '(无)'}` };
+                }
+                try {
+                    const body = await this.skillRegistry.execute(name, {});
+                    return { success: true, output: body };
+                }
+                catch (e) {
+                    return { success: false, error: `执行 skill 失败: ${String(e)}` };
+                }
+            }
+        });
     }
     async registerP2PDocumentReceiver() {
         await initDocumentReceiver();
@@ -1541,3 +1688,41 @@ export function resetAgentSession() {
     sessionInstance = null;
     lastIdentityDid = null;
 }
+/**
+ * 自我改进循环: 在沙箱分支上工作, 输出结果给用户审.
+ *
+ * 不在 PiAgent 实例上的原因: 心跳回调可能没有 agent 实例, 单独函数更易复用.
+ *
+ * **关键不变量**:
+ *   1. AI 不能 push 到 master (shell-guard 黑名单 + git 受保护分支)
+ *   2. 改动必须走沙箱分支 (SELF_IMPROVE_BRANCH_PREFIX)
+ *   3. 6 小时冷却期 (SELF_IMPROVE_COOLDOWN_MS)
+ *   4. 写文件必须经过 shell_exec + 护栏检查
+ */
+let lastSelfImproveAt = null;
+export async function runSelfImproveLoop(goal) {
+    const cooldownMs = getCooldownMs();
+    // 1. 冷却期检查
+    if (lastSelfImproveAt && Date.now() - lastSelfImproveAt < cooldownMs) {
+        const waitHrs = Math.ceil((cooldownMs - (Date.now() - lastSelfImproveAt)) / 3600000);
+        return { success: false, error: `自改冷却中, 还需要约 ${waitHrs} 小时` };
+    }
+    // 2. 选源分支 + 新分支名
+    const sourceBranch = 'master';
+    const newBranch = `${getBranchPrefix()}${Date.now()}`;
+    console.log(`[self-improve] 启动自改循环, 目标: ${goal}, 新分支: ${newBranch}`);
+    // 3. 创建分支
+    const r1 = await shellExec('git', ['checkout', sourceBranch]);
+    if (!r1.success)
+        return { success: false, error: `切换到 ${sourceBranch} 失败: ${r1.error}` };
+    const r2 = await shellExec('git', ['checkout', '-b', newBranch]);
+    if (!r2.success)
+        return { success: false, error: `创建分支失败: ${r2.error}` };
+    // 4. 走 task queue: 把"自改"作为一个 task 抛回去, AI 拿到后会用 shell_exec 改
+    //    护栏已经阻止所有禁区改动, 这里只负责登记
+    lastSelfImproveAt = Date.now();
+    return {
+        success: true,
+        output: `✅ 自改分支已创建: ${newBranch}\n目标: ${goal}\n\n**护栏已激活**:\n  - 仅允许白名单命令 (git/npm/tsc/vitest/cat/ls/...)\n  - 禁止改 src/agents/pi-sdk.ts, shell-guard.ts, src/heartbeat/, src/network/, src/pi-ecosystem-judgment/, package.json, .env 等\n  - 6 小时冷却期\n\nAI 接下来会用 shell_exec 工具改源码. 完成后你会在对话里看到 diff 摘要, 手动 git diff master..${newBranch} 审, 满意再 merge.`
+    };
+}

package/dist/agents/shell-guard.js

@@ -0,0 +1,354 @@
+/**
+ * Shell 命令硬护栏 (策略可配置版)
+ *
+ * 设计原则:
+ *   1. 白名单/黑名单从 ~/.bolloon/self-improve-policy.json 加载
+ *   2. 加载失败或缺失时, 使用**硬编码兜底** (永远拒绝 = 最安全)
+ *   3. 策略文件在禁区里, AI 即便拿到 shell_exec 也改不了
+ *   4. 提供 API 端点供**人**热加载策略, 并写审计日志
+ *
+ * 策略文件 schema (self-improve-policy.json):
+ * {
+ *   "version": 1,
+ *   "commandAllowlist": ["git", "npm", "tsc", "vitest", "cat", "ls", "..."],
+ *   "commandDenylist": ["rm", "mv", "chmod", "sudo", "su", "curl", "wget"],
+ *   "pathAllowlist": [
+ *     "src/web/client.js",
+ *     "src/agents/workflow-engine.ts",
+ *     "*.md",
+ *     "docs/**"
+ *   ],
+ *   "pathDenylist": [
+ *     "src/agents/pi-sdk.ts",
+ *     "src/agents/shell-guard.ts",
+ *     "src/agents/shell-tool.ts",
+ *     "src/heartbeat/**",
+ *     "src/network/**",
+ *     "src/pi-ecosystem-judgment/**",
+ *     "package.json",
+ *     ".env*",
+ *     ".git/**",
+ *     "dist/**",
+ *     "node_modules/**"
+ *   ],
+ *   "cooldownMs": 21600000,
+ *   "sandboxCwd": ".bolloon-shell-sandbox",
+ *   "branchPrefix": "agent/self-imp-"
+ * }
+ *
+ * 匹配规则:
+ *   1. 路径先查 denylist (命中即拒), 再查 allowlist (没命中即拒)
+ *   2. 命令先查 denylist (命中即拒), 再查 allowlist (没命中即拒)
+ *   3. 通配符: * 匹配单层文件名, ** 匹配任意层级
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// ============================================================================
+// 硬编码兜底 (策略文件读不到时, 用这套)
+// 这是**最后一道防线** - AI 即便能改 ~/.bolloon/ 也没法删这个常量
+// ============================================================================
+const FALLBACK_COMMAND_ALLOWLIST = new Set([
+    'git', 'node', 'npm', 'npx', 'tsx', 'tsc', 'vitest',
+    'cat', 'head', 'tail', 'wc', 'ls', 'echo', 'pwd', 'date',
+    'mkdir', 'touch'
+]);
+const FALLBACK_PATH_ALLOWLIST = [
+    // 自由区: AI 可以改
+    'src/web/client.js',
+    'src/web/style.css',
+    'src/agents/workflow-engine.ts',
+    'src/agents/workflow-pivot-loop.ts',
+    'src/agents/constraint-layer.ts',
+    'src/test/**',
+    'docs/**',
+    '*.md',
+    'README.md'
+];
+const FALLBACK_PATH_DENYLIST = [
+    /(^|\/)src\/agents\/pi-sdk\.ts$/, // LLM 抽象层
+    /(^|\/)src\/agents\/shell-guard\.ts$/, // 护栏本身
+    /(^|\/)src\/agents\/shell-tool\.ts$/, // shell 工具实现
+    /(^|\/)src\/heartbeat\//, // 心跳
+    /(^|\/)src\/network\//, // P2P / libp2p / iroh
+    /(^|\/)src\/pi-ecosystem-judgment\//, // judgment 系统
+    /(^|\/)package\.json$/,
+    /(^|\/)package-lock\.json$/,
+    /(^|\/)tsconfig.*\.json$/,
+    /(^|\/)\.env(\.|$)/,
+    /(^|\/)\.git\//,
+    /(^|\/)\.bolloon\//, // 策略文件 / sessions / persona
+    /(^|\/)dist\//,
+    /(^|\/)node_modules\//,
+];
+const FALLBACK_ARG_DENYLIST = [
+    /^\s*push\s+(-f|--force)/i,
+    /^\s*push\s+origin\s+(master|main)\b/i,
+    /^\s*reset\s+--hard\b/i,
+    /^\s*clean\s+-fd?\b/i,
+    /^\s*--inspect\b/,
+    /[|&;`$()<>]/, // shell 元字符
+    /\brm\s+-rf?\b/i,
+    /\bsudo\b/i,
+    /\bsu\b/i,
+    /\bcurl\b/i,
+    /\bwget\b/i,
+    /\.\.\//, // 路径逃逸
+    /^\//, // 绝对路径
+    /^[a-zA-Z]:\\/, // Windows 绝对路径
+];
+let cachedPolicy = null;
+let policyLoadedAt = 0;
+const POLICY_TTL_MS = 60_000; // 60 秒缓存 (避免每次 shell_exec 都读盘)
+const POLICY_PATH = path.join(os.homedir(), '.bolloon', 'self-improve-policy.json');
+const POLICY_AUDIT_PATH = path.join(os.homedir(), '.bolloon', 'self-improve-audit.log');
+/**
+ * 默认策略模板 - 第一次启动时写到磁盘
+ */
+function getDefaultPolicy() {
+    return {
+        version: 1,
+        commandAllowlist: Array.from(FALLBACK_COMMAND_ALLOWLIST),
+        pathAllowlist: [...FALLBACK_PATH_ALLOWLIST],
+        pathDenylist: FALLBACK_PATH_DENYLIST.map(r => r.source),
+        cooldownMs: 6 * 60 * 60 * 1000,
+        sandboxCwd: '.bolloon-shell-sandbox',
+        branchPrefix: 'agent/self-imp-'
+    };
+}
+/**
+ * 加载策略 (有缓存)
+ * 加载失败返回 null, 调用方应回退到硬编码兜底
+ */
+export function loadPolicy(forceReload = false) {
+    const now = Date.now();
+    if (!forceReload && cachedPolicy && now - policyLoadedAt < POLICY_TTL_MS) {
+        return cachedPolicy;
+    }
+    try {
+        if (!fs.existsSync(POLICY_PATH)) {
+            // 第一次启动: 写入默认策略
+            const dir = path.dirname(POLICY_PATH);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(POLICY_PATH, JSON.stringify(getDefaultPolicy(), null, 2));
+            console.log(`[shell-guard] 已生成默认策略: ${POLICY_PATH}`);
+        }
+        const raw = fs.readFileSync(POLICY_PATH, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // 极简 schema 校验
+        if (!parsed.version || !Array.isArray(parsed.commandAllowlist) || !Array.isArray(parsed.pathAllowlist) || !Array.isArray(parsed.pathDenylist)) {
+            console.warn('[shell-guard] 策略文件 schema 不对, 用硬编码兜底');
+            return null;
+        }
+        cachedPolicy = parsed;
+        policyLoadedAt = now;
+        return parsed;
+    }
+    catch (err) {
+        console.warn('[shell-guard] 策略文件加载失败, 用硬编码兜底:', err);
+        return null;
+    }
+}
+/**
+ * 审计日志: 记录所有被拒/被允许的 shell_exec 调用
+ */
+export function auditShellCall(result, cmd, args, reason, targetPath) {
+    try {
+        const dir = path.dirname(POLICY_AUDIT_PATH);
+        fs.mkdirSync(dir, { recursive: true });
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            result,
+            cmd,
+            args,
+            reason,
+            targetPath
+        }) + '\n';
+        fs.appendFileSync(POLICY_AUDIT_PATH, line);
+    }
+    catch {
+        // 审计失败不阻塞
+    }
+}
+/**
+ * 把通配符模式编译成正则
+ * *  -> [^/]*
+ * ** -> .*
+ */
+function compileGlob(pattern) {
+    // 转义正则元字符, 但保留 * 和 **
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '__DOUBLESTAR__')
+        .replace(/\*/g, '[^/]*')
+        .replace(/__DOUBLESTAR__/g, '.*');
+    return new RegExp('^' + escaped + '$');
+}
+/**
+ * 检查命令
+ */
+export function checkCommand(cmd, args) {
+    const policy = loadPolicy();
+    const fullCmd = [cmd, ...args].join(' ').trim();
+    // ---- 1. 命令黑名单 (策略里有的话) ----
+    if (policy?.commandDenylist) {
+        for (const denied of policy.commandDenylist) {
+            if (cmd === denied || fullCmd.startsWith(denied)) {
+                auditShellCall('denied', cmd, args, `命中 commandDenylist: ${denied}`);
+                return { allowed: false, reason: `命令 '${cmd}' 命中策略黑名单: ${denied}`, matchedBy: 'cmd-denylist' };
+            }
+        }
+    }
+    // ---- 2. 命令白名单 ----
+    const allowSet = policy
+        ? new Set(policy.commandAllowlist)
+        : FALLBACK_COMMAND_ALLOWLIST;
+    if (!allowSet.has(cmd)) {
+        auditShellCall('denied', cmd, args, `命令 '${cmd}' 不在白名单`);
+        return {
+            allowed: false,
+            reason: `命令 '${cmd}' 不在白名单. 允许: ${Array.from(allowSet).join(', ')}`,
+            matchedBy: policy ? 'cmd-allowlist' : 'fallback-deny'
+        };
+    }
+    // ---- 3. 参数黑名单 (策略文件 + 硬编码兜底都查) ----
+    const argPatterns = policy
+        ? [
+            ...FALLBACK_ARG_DENYLIST,
+            // 策略里没有专门的 argDenylist 字段, 复用 pathDenylist 模式不太合适
+            // 故意**不**让用户在策略里加 arg denylist - 防止 AI 删自己的 arg 限制
+        ]
+        : FALLBACK_ARG_DENYLIST;
+    for (const arg of args) {
+        for (const pattern of argPatterns) {
+            if (pattern.test(arg)) {
+                auditShellCall('denied', cmd, args, `参数 '${arg}' 命中黑名单`);
+                return { allowed: false, reason: `参数 '${arg}' 命中黑名单模式 ${pattern}`, matchedBy: 'arg-denylist' };
+            }
+        }
+    }
+    // 整条命令再过一遍
+    for (const pattern of argPatterns) {
+        if (pattern.test(fullCmd)) {
+            auditShellCall('denied', cmd, args, `整条命令命中黑名单`);
+            return { allowed: false, reason: `整条命令命中黑名单模式 ${pattern}`, matchedBy: 'arg-denylist' };
+        }
+    }
+    auditShellCall('allowed', cmd, args);
+    return { allowed: true };
+}
+/**
+ * 检查路径
+ *
+ * 逻辑:
+ *   1. denylist 优先: 命中即拒 (用硬编码兜底正则)
+ *   2. allowlist: 命中放行
+ *   3. 都不命中: 拒 (默认拒绝)
+ */
+export function checkWritePath(targetPath) {
+    const policy = loadPolicy();
+    const normalized = path.normalize(targetPath).replace(/\\/g, '/');
+    // ---- 1. 路径黑名单 (硬编码兜底不可绕过) ----
+    // 即便策略文件里 denylist 是空的, 硬编码兜底永远生效
+    const hardcodedDenylist = FALLBACK_PATH_DENYLIST;
+    for (const pattern of hardcodedDenylist) {
+        if (pattern.test(normalized)) {
+            auditShellCall('denied', '', [], `路径 '${targetPath}' 命中硬编码禁区`, targetPath);
+            return { allowed: false, reason: `路径 '${targetPath}' 命中硬编码禁区 ${pattern}`, matchedBy: 'fallback-deny' };
+        }
+    }
+    // 策略文件里的额外 denylist
+    if (policy?.pathDenylist) {
+        for (const patternStr of policy.pathDenylist) {
+            try {
+                const regex = compileGlob(patternStr);
+                if (regex.test(normalized)) {
+                    auditShellCall('denied', '', [], `路径 '${targetPath}' 命中策略 denylist`, targetPath);
+                    return { allowed: false, reason: `路径 '${targetPath}' 命中策略 denylist: ${patternStr}`, matchedBy: 'path-denylist' };
+                }
+            }
+            catch {
+                // 编译失败的模式跳过
+            }
+        }
+    }
+    // ---- 2. 路径白名单 (来自策略或兜底) ----
+    const allowlist = policy?.pathAllowlist || FALLBACK_PATH_ALLOWLIST;
+    for (const patternStr of allowlist) {
+        try {
+            const regex = compileGlob(patternStr);
+            if (regex.test(normalized)) {
+                auditShellCall('allowed', '', [], undefined, targetPath);
+                return { allowed: true, matchedBy: 'path-allowlist' };
+            }
+        }
+        catch {
+            // 编译失败的模式跳过
+        }
+    }
+    // 都不命中: 默认拒绝
+    auditShellCall('denied', '', [], `路径 '${targetPath}' 不在任何 allowlist 中`, targetPath);
+    return {
+        allowed: false,
+        reason: `路径 '${targetPath}' 不在白名单. 允许: ${allowlist.join(', ')}`,
+        matchedBy: 'path-allowlist'
+    };
+}
+// ============================================================================
+// 运行时配置 (从策略文件读, 但有兜底)
+// ============================================================================
+/**
+ * 自改分支名前缀
+ */
+export function getBranchPrefix() {
+    const policy = loadPolicy();
+    return policy?.branchPrefix || 'agent/self-imp-';
+}
+/**
+ * 冷却期 (毫秒)
+ */
+export function getCooldownMs() {
+    const policy = loadPolicy();
+    return policy?.cooldownMs || 6 * 60 * 60 * 1000;
+}
+/**
+ * 沙箱工作目录
+ */
+export function getSandboxCwd() {
+    const policy = loadPolicy();
+    const rel = policy?.sandboxCwd || '.bolloon-shell-sandbox';
+    return path.resolve(process.cwd(), rel);
+}
+// ============================================================================
+// 兼容旧 API - 保留原导出名
+// ============================================================================
+/** @deprecated 用 getBranchPrefix() */
+export const SELF_IMPROVE_BRANCH_PREFIX = 'agent/self-imp-';
+/** @deprecated 用 getCooldownMs() */
+export const SELF_IMPROVE_COOLDOWN_MS = 6 * 60 * 60 * 1000;
+/** @deprecated 用 getSandboxCwd() */
+export const SHELL_SANDBOX_CWD = path.resolve(process.cwd(), '.bolloon-shell-sandbox');
+// ============================================================================
+// 写策略 / 审计路径 (供 API 端点用)
+// ============================================================================
+export const POLICY_AUDIT_PATH_PUBLIC = POLICY_AUDIT_PATH;
+/**
+ * 把新策略写到磁盘, 立即清缓存让下次 loadPolicy() 重读
+ * **只供人手动调用**
+ */
+export function writePolicy(newPolicy) {
+    try {
+        newPolicy.version = (newPolicy.version || 0) + 1;
+        const dir = path.dirname(POLICY_PATH);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(POLICY_PATH, JSON.stringify(newPolicy, null, 2));
+        cachedPolicy = null; // 清缓存
+        policyLoadedAt = 0;
+        console.log(`[shell-guard] 策略已更新, version=${newPolicy.version}`);
+        return true;
+    }
+    catch (err) {
+        console.error('[shell-guard] 写策略失败:', err);
+        return false;
+    }
+}

package/dist/agents/shell-tool.js

@@ -0,0 +1,83 @@
+/**
+ * Shell 工具: 给 Bolloon agent 跑受限的 shell 命令
+ *
+ * 这个工具**只做两件事**:
+ *   1. 把命令交给硬护栏检查
+ *   2. 在沙箱 cwd 下用 child_process 执行
+ *
+ * AI 完全自主触发自改, 但 shell 工具本身**只接受白名单内命令**.
+ * 禁区列表在 shell-guard.ts, AI 改不了那个文件.
+ */
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import { checkCommand, checkWritePath, getSandboxCwd } from './shell-guard.js';
+/**
+ * 在沙箱里跑一条命令
+ * @param cmd  可执行文件名, 必须命中白名单
+ * @param args 参数列表
+ * @param opts.timeoutMs 超时毫秒, 默认 30s
+ * @param opts.allowedWriteTargets 允许的写入路径, 命中禁区列表的路径会拒
+ */
+export async function shellExec(cmd, args = [], opts = {}) {
+    // 1. 护栏检查
+    const cmdCheck = checkCommand(cmd, args);
+    if (!cmdCheck.allowed) {
+        return {
+            success: false,
+            error: `[shell-guard] ${cmdCheck.reason}`,
+            deniedByGuard: true
+        };
+    }
+    // 2. 写入目标检查
+    if (opts.allowedWriteTargets) {
+        for (const target of opts.allowedWriteTargets) {
+            const pathCheck = checkWritePath(target);
+            if (!pathCheck.allowed) {
+                return {
+                    success: false,
+                    error: `[shell-guard] ${pathCheck.reason}`,
+                    deniedByGuard: true
+                };
+            }
+        }
+    }
+    // 3. 确保沙箱存在
+    const sandboxCwd = getSandboxCwd();
+    try {
+        fs.mkdirSync(sandboxCwd, { recursive: true });
+    }
+    catch {
+        // 已经存在则忽略
+    }
+    // 4. 跑命令
+    return new Promise((resolve) => {
+        const proc = spawn(cmd, args, {
+            cwd: sandboxCwd,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' }, // 禁止 git 弹交互
+            shell: false, // **关键**: 禁用 shell, 防止元字符注入
+            windowsHide: true
+        });
+        let stdout = '';
+        let stderr = '';
+        const timeout = setTimeout(() => {
+            proc.kill('SIGKILL');
+            resolve({ success: false, error: `命令超时 (>${opts.timeoutMs || 30000}ms)`, exitCode: -1 });
+        }, opts.timeoutMs || 30000);
+        proc.stdout.on('data', (data) => { stdout += data.toString(); });
+        proc.stderr.on('data', (data) => { stderr += data.toString(); });
+        proc.on('error', (err) => {
+            clearTimeout(timeout);
+            resolve({ success: false, error: `启动失败: ${err.message}` });
+        });
+        proc.on('close', (code) => {
+            clearTimeout(timeout);
+            const output = (stdout + (stderr ? `\n[stderr]\n${stderr}` : '')).trim();
+            if (code === 0) {
+                resolve({ success: true, output, exitCode: 0 });
+            }
+            else {
+                resolve({ success: false, output, error: `exit code ${code}`, exitCode: code ?? -1 });
+            }
+        });
+    });
+}