@bolloon/bolloon-agent 0.1.13 → 0.1.14

package/src/agents/pi-sdk.ts

@@ -5,6 +5,7 @@
 
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { documentReader, DocumentContent } from '../documents/reader.js';
 import { getMinimax } from '../constraints/index.js';
@@ -14,6 +15,8 @@ import { WorkflowEngine, WorkflowStep, StepResult, Workflow } from './workflow-e
 import { DeepThinkingEngine, AgentCoordinator, type ThinkResult, type AgentResult } from '@bolloon/constraint-runtime';
 import { WorkflowPivotLoop, createDefaultPivotConfig, type PivotLoopConfig, type LoopResult } 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,
   SocialHeartbeat,
@@ -36,6 +39,7 @@ import {
   type GlobalSharedContext
 } from '../social/global-shared-context.js';
 import { Session, SkillRegistry, saveSession, loadSession, type Skill, type StoredSession } from '@bolloon/constraint-runtime';
+import { loadSkillsFromPaths, defaultSkillPaths, describeSkill } from './skill-loader.js';
 
 // Pi Ecosystem Integration (lazy imports - initialized on demand)
 // Functions from: createGoal, getCurrentGoal, completeCurrentGoal, failCurrentGoal, getGoalStats, getQueueSummary
@@ -46,6 +50,12 @@ export interface AgentSessionConfig {
   identityDoc?: IdentityDoc;
   usePivotLoop?: boolean;
   pivotLoopConfig?: PivotLoopConfig;
+  /**
+   * Skills 加载目录列表, 后者覆盖前者同名 skill.
+   * 留空时使用 defaultSkillPaths() 推断的默认路径
+   * ( ~/.bolloon/skills/ → <cwd>/.bolloon/skills/ → ~/.boll/skills/ )
+   */
+  skillsPaths?: string[];
 }
 
 export interface IdentityDoc {
@@ -575,9 +585,72 @@ class PiAgentSession implements AgentSession {
     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)
+   *
+   * 静默忽略不存在的目录.
+   */
+  private loadSkills(paths?: string[]): void {
+    let resolved: string[];
+    if (paths && paths.length > 0) {
+      resolved = paths;
+    } else {
+      resolved = [
+        ...defaultSkillPaths(os.homedir(), this.cwd),
+        // bolloon 仓库内置 skill (相对本 npm 包的位置)
+        this.findBolloonBuiltinSkillsPath(),
+      ].filter((p): p is string => 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 作为外部依赖安装时).
+   */
+  private findBolloonBuiltinSkillsPath(): string | null {
+    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;
+  }
+
   private async initHarness(): Promise<void> {
     try {
       const { createBollharnessIntegration } = await import('../bollharness-integration/index.js');
@@ -808,6 +881,86 @@ class PiAgentSession implements AgentSession {
     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)}` };
+        }
+      }
+    });
   }
 
   private async registerP2PDocumentReceiver(): Promise<void> {
@@ -1919,3 +2072,46 @@ export function resetAgentSession(): void {
   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: number | null = null;
+
+export async function runSelfImproveLoop(goal: string): Promise<{ success: boolean; output?: string; error?: string }> {
+  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/src/agents/shell-guard.ts

@@ -0,0 +1,417 @@
+/**
+ * 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: ReadonlySet<string> = new Set([
+  'git', 'node', 'npm', 'npx', 'tsx', 'tsc', 'vitest',
+  'cat', 'head', 'tail', 'wc', 'ls', 'echo', 'pwd', 'date',
+  'mkdir', 'touch'
+]);
+
+const FALLBACK_PATH_ALLOWLIST: readonly string[] = [
+  // 自由区: 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: ReadonlyArray<RegExp> = [
+  /(^|\/)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: ReadonlyArray<RegExp> = [
+  /^\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 绝对路径
+];
+
+// ============================================================================
+// 策略加载
+// ============================================================================
+
+export interface SelfImprovePolicy {
+  version: number;
+  commandAllowlist: string[];
+  commandDenylist?: string[];
+  pathAllowlist: string[];
+  pathDenylist: string[];
+  cooldownMs: number;
+  sandboxCwd: string;
+  branchPrefix: string;
+}
+
+let cachedPolicy: SelfImprovePolicy | null = null;
+let policyLoadedAt: number = 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(): SelfImprovePolicy {
+  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): SelfImprovePolicy | null {
+  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) as SelfImprovePolicy;
+
+    // 极简 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: 'allowed' | 'denied',
+  cmd: string,
+  args: string[],
+  reason?: string,
+  targetPath?: string
+): void {
+  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 {
+    // 审计失败不阻塞
+  }
+}
+
+// ============================================================================
+// 检查逻辑
+// ============================================================================
+
+export interface ShellCheckResult {
+  allowed: boolean;
+  reason?: string;
+  /** 触发的是哪条规则 (denylist / allowlist / fallback) */
+  matchedBy?: 'cmd-denylist' | 'cmd-allowlist' | 'arg-denylist' | 'path-denylist' | 'path-allowlist' | 'fallback-deny';
+}
+
+/**
+ * 把通配符模式编译成正则
+ * *  -> [^/]*
+ * ** -> .*
+ */
+function compileGlob(pattern: string): RegExp {
+  // 转义正则元字符, 但保留 * 和 **
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '__DOUBLESTAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__DOUBLESTAR__/g, '.*');
+  return new RegExp('^' + escaped + '$');
+}
+
+/**
+ * 检查命令
+ */
+export function checkCommand(cmd: string, args: string[]): ShellCheckResult {
+  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 as Set<string>;
+  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: string): ShellCheckResult {
+  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(): string {
+  const policy = loadPolicy();
+  return policy?.branchPrefix || 'agent/self-imp-';
+}
+
+/**
+ * 冷却期 (毫秒)
+ */
+export function getCooldownMs(): number {
+  const policy = loadPolicy();
+  return policy?.cooldownMs || 6 * 60 * 60 * 1000;
+}
+
+/**
+ * 沙箱工作目录
+ */
+export function getSandboxCwd(): string {
+  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: SelfImprovePolicy): boolean {
+  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;
+  }
+}