@bolloon/bolloon-agent 0.1.13 → 0.1.14

package/src/agents/shell-tool.ts

@@ -0,0 +1,103 @@
+/**
+ * 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';
+
+export interface ShellExecResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+  exitCode?: number;
+  /** true 表示被护栏拒绝, AI 不应该重试 */
+  deniedByGuard?: boolean;
+}
+
+/**
+ * 在沙箱里跑一条命令
+ * @param cmd  可执行文件名, 必须命中白名单
+ * @param args 参数列表
+ * @param opts.timeoutMs 超时毫秒, 默认 30s
+ * @param opts.allowedWriteTargets 允许的写入路径, 命中禁区列表的路径会拒
+ */
+export async function shellExec(
+  cmd: string,
+  args: string[] = [],
+  opts: { timeoutMs?: number; allowedWriteTargets?: string[] } = {}
+): Promise<ShellExecResult> {
+  // 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 });
+      }
+    });
+  });
+}

package/src/agents/skill-loader.ts

@@ -0,0 +1,202 @@
+/**
+ * skill-loader.ts — 双 frontmatter 兼容的 SKILL.md 加载器
+ *
+ * 兼容两套 SKILL.md frontmatter：
+ *   A. Anthropic Agent Skills 标准 (2025-12): name / description / license / compatibility / keywords
+ *   B. bollharness 现有 frontmatter:           name / description / status / tier / triggers / outputs / truth_policy
+ *
+ * 字段映射规则（统一到内部 SkillMeta）：
+ *   description      ← 直接取
+ *   license          ← 取 A，没有则空
+ *   status           ← 取 B，没有则默认 'active'
+ *   tier             ← 取 B（"tier" 是 bollharness 概念）
+ *   triggers / keywords ← 合并 A.keywords 和 B.triggers 数组
+ *   body             ← 去掉 frontmatter 后的 Markdown 正文
+ *
+ * Skill 的 execute() 把 body 作为 Markdown 文档注入到 LLM context。
+ * 这是 Skills 协议的核心 — "告诉 agent 怎么做"，与 MCP "能调什么"互补。
+ */
+
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import type { Skill } from '@bolloon/constraint-runtime';
+
+/** 解析后的 SKILL.md 内部表示 */
+export interface SkillMeta {
+  /** 唯一名, 通常 = 目录名 = frontmatter.name */
+  name: string;
+  /** SKILL.md 绝对路径 */
+  sourcePath: string;
+  /** 去掉 frontmatter 后的 Markdown body */
+  body: string;
+  /** 原始 frontmatter 解析结果, 保留以备调用方取 license/compatibility 等 */
+  frontmatter: Record<string, unknown>;
+  /** 统一后的 description */
+  description: string;
+  /** 状态: active / archived / draft, 缺省 active */
+  status: 'active' | 'archived' | 'draft';
+  /** tier (bollharness 概念, 缺省 'utility') */
+  tier: string;
+  /** 触发条件 (合并 keywords + triggers) */
+  triggers: string[];
+}
+
+/** YAML frontmatter 最小解析器 — 避免引入额外依赖, 支持双格式 */
+function parseFrontmatter(raw: string): { frontmatter: Record<string, unknown>; body: string } {
+  // frontmatter 必须以 --- 开头, 紧跟换行, 再以 --- 闭合
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: raw };
+  }
+  const [, yamlBlock, body] = match;
+  const frontmatter: Record<string, unknown> = {};
+  const lines = yamlBlock.split(/\r?\n/);
+  let currentKey: string | null = null;
+  let currentArray: string[] | null = null;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line.trim()) continue;
+    // 数组项: "  - value"
+    const arrItem = line.match(/^\s+-\s+(.*)$/);
+    if (arrItem && currentKey && currentArray) {
+      currentArray.push(stripQuotes(arrItem[1]));
+      continue;
+    }
+    // 键值对: "key: value" 或 "key:"
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (kv) {
+      const [, key, value] = kv;
+      if (value === '') {
+        // 可能是数组开始 (下一行 "  - xxx")
+        currentKey = key;
+        currentArray = [];
+        frontmatter[key] = currentArray;
+      } else {
+        currentKey = key;
+        currentArray = null;
+        frontmatter[key] = stripQuotes(value);
+      }
+    }
+  }
+
+  return { frontmatter, body: body.replace(/^\r?\n/, '') };
+}
+
+function stripQuotes(s: string): string {
+  const t = s.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+/** 把 frontmatter 统一到 SkillMeta */
+function normalize(name: string, sourcePath: string, raw: string): SkillMeta | null {
+  const { frontmatter, body } = parseFrontmatter(raw);
+
+  // name 至少要有一个来源: frontmatter.name 或目录名
+  const fmName = typeof frontmatter.name === 'string' ? frontmatter.name : name;
+  const finalName = fmName || name;
+  if (!finalName) return null;
+
+  const description =
+    typeof frontmatter.description === 'string'
+      ? frontmatter.description
+      : '';
+
+  const statusRaw = typeof frontmatter.status === 'string' ? frontmatter.status.toLowerCase() : 'active';
+  const status: SkillMeta['status'] =
+    statusRaw === 'archived' || statusRaw === 'draft' ? statusRaw : 'active';
+
+  const tier = typeof frontmatter.tier === 'string' ? frontmatter.tier : 'utility';
+
+  // 合并两套触发字段
+  const triggers: string[] = [];
+  if (Array.isArray(frontmatter.triggers)) {
+    for (const t of frontmatter.triggers) if (typeof t === 'string') triggers.push(t);
+  }
+  if (Array.isArray(frontmatter.keywords)) {
+    for (const k of frontmatter.keywords) if (typeof k === 'string') triggers.push(k);
+  }
+
+  return { name: finalName, sourcePath, body, frontmatter, description, status, tier, triggers };
+}
+
+/** 解析单个 SKILL.md 文件 */
+export async function parseSkillFile(filePath: string): Promise<SkillMeta | null> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+  // 从路径推目录名作为 name 兜底
+  const dirName = path.basename(path.dirname(filePath));
+  return normalize(dirName, filePath, raw);
+}
+
+/** 扫描一个目录, 找所有 {name}/SKILL.md (一层嵌套结构) */
+export async function loadSkillsDir(dir: string): Promise<SkillMeta[]> {
+  const out: SkillMeta[] = [];
+  let entries: import('fs').Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+    const skillFile = path.join(dir, entry.name, 'SKILL.md');
+    const meta = await parseSkillFile(skillFile);
+    if (meta) out.push(meta);
+  }
+  return out;
+}
+
+/** 默认 skill 路径优先级 (后者覆盖前者同名 skill) */
+export function defaultSkillPaths(home: string = os.homedir(), cwd: string = process.cwd()): string[] {
+  return [
+    path.join(home, '.bolloon', 'skills'),     // 全局用户级
+    path.join(cwd, '.bolloon', 'skills'),       // 项目级
+    path.join(home, '.boll', 'skills'),         // 全局 (兼容 bollharness 旧用户)
+  ];
+}
+
+/** 把 SkillMeta 包成 @bolloon/constraint-runtime 期望的 Skill 对象 */
+export function skillFromMeta(meta: SkillMeta): Skill {
+  return {
+    name: meta.name,
+    description: meta.description || meta.tier,
+    execute: async (_params: Record<string, unknown>): Promise<string> => {
+      // Skills 协议: 把 body 当 Markdown 文档返回, 由调用方注入 LLM context
+      // 调用方 (use_skill tool) 拿到后会把 body 放到 tool result,
+      // LLM 下一轮对话看到这份指南, 按它执行
+      const header = `## Skill: ${meta.name}\n\n${meta.description ? `> ${meta.description}\n\n` : ''}`;
+      const triggersBlock = meta.triggers.length
+        ? `**触发条件**: ${meta.triggers.join('; ')}\n\n`
+        : '';
+      return `${header}${triggersBlock}${meta.body}`;
+    },
+  };
+}
+
+/** 加载多个目录, 同名 skill 后者覆盖前者 */
+export async function loadSkillsFromPaths(paths: string[]): Promise<Skill[]> {
+  const seen = new Map<string, Skill>();
+  for (const p of paths) {
+    const metas = await loadSkillsDir(p);
+    for (const m of metas) {
+      if (m.status === 'archived') continue; // 归档的跳过
+      seen.set(m.name, skillFromMeta(m));
+    }
+  }
+  return Array.from(seen.values());
+}
+
+/** 列出已加载的 skills (调试/UI 用) */
+export function describeSkill(s: Skill): string {
+  return `${s.name}: ${s.description}`;
+}

package/src/bollharness-integration/context-chain-router.ts

@@ -4,20 +4,20 @@
  * Integrates with existing ContextRouter and Judgment systems.
  *
  * Architecture:
- * - Session end → extract summary by work_type → store in .boll/state/context-chains/
+ * - Session end → extract summary by work_type → store in .bolloon/state/context-chains/
  * - Session start (Gate 0/3) → lookup related chains → inject summaries
  * - Work type: code_change | review | design | question | planning | debugging
  *
  * Integration points:
  * - Uses existing context-router-judgment.ts pattern (extends, not replaces)
  * - Gate injection via gate-judgment-inject.ts
- * - Storage in .boll/state/context-chains/
+ * - Storage in .bolloon/state/context-chains/
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
 
-export const CONTEXT_CHAINS_DIR = path.join('.boll', 'state', 'context-chains');
+export const CONTEXT_CHAINS_DIR = path.join('.bolloon', 'state', 'context-chains');
 
 export type WorkType = 'code_change' | 'review' | 'design' | 'question' | 'planning' | 'debugging';
 

package/src/bollharness-integration/context-router.ts

@@ -119,7 +119,7 @@ export class ContextRouter {
 
   constructor(fragmentsDir?: string) {
     this.fragmentsDir = fragmentsDir || FRAGMENTS_DIR;
-    this.injectedFile = path.join('.boll', 'guard', 'injected.json');
+    this.injectedFile = path.join('.bolloon', 'guard', 'injected.json');
   }
 
   /**

package/src/heartbeat/Watchdog.ts

@@ -126,12 +126,14 @@ export class Watchdog {
       return;
     }
 
-    // 检查内存使用
+    // 检查内存使用: 用绝对阈值, 不看 heapUsed/heapTotal 比例 (V8 内部比例不可靠, 经常 80-95% 误报)
     const usage = process.memoryUsage();
-    const heapUsedPercent = (usage.heapUsed / usage.heapTotal) * 100;
-    if (heapUsedPercent > 90) {
-      console.warn(`[Watchdog] Memory usage critical: ${heapUsedPercent.toFixed(1)}%`);
-      this.triggerRestart(1, `Memory usage ${heapUsedPercent.toFixed(1)}%`);
+    const heapUsedMB = usage.heapUsed / 1024 / 1024;
+    const rssMB = usage.rss / 1024 / 1024;
+    // 1.2GB heap 或 1.5GB RSS 才是真危险
+    if (heapUsedMB > 1224 || rssMB > 1536) {
+      console.warn(`[Watchdog] Memory usage critical: heapUsed=${heapUsedMB.toFixed(0)}MB, rss=${rssMB.toFixed(0)}MB`);
+      this.triggerRestart(1, `Memory usage heap=${heapUsedMB.toFixed(0)}MB rss=${rssMB.toFixed(0)}MB`);
     }
   }
 

package/src/heartbeat/index.ts

@@ -8,6 +8,7 @@ export * from './HealthMonitor.js';
 export * from './Watchdog.js';
 export * from './DaemonManager.js';
 export * from './StartupVerifier.js';
+export * from './self-improve-bus.js';
 
 import { createHealthMonitor, getHealthMonitor } from './HealthMonitor.js';
 import { createWatchdog, getWatchdog } from './Watchdog.js';

package/src/heartbeat/self-improve-bus.ts

@@ -0,0 +1,110 @@
+/**
+ * Self-Improve Event Bus
+ *
+ * 心跳事件 → 自改触发器 (解耦 watchdog)
+ *
+ * 设计原则:
+ *   - Watchdog 负责保活 (重启进程), 不知道"自改"是什么
+ *   - Self-Improve Bus 监听"信号事件" (CI 失败, 任务连续失败, 静默超时)
+ *   - 信号达到阈值 + 通过冷却期 → 触发 runSelfImproveLoop
+ *   - 触发时通过 SSE 广播给前端, 用户能在 UI 里看到
+ *
+ * 关键不变量:
+ *   1. 心跳**不**直接调自改 - 通过 emit() 异步触发
+ *   2. 触发频率受 SELF_IMPROVE_COOLDOWN_MS 限制
+ *   3. 同类事件 24 小时内只触发 1 次
+ *   4. 触发后不阻塞健康检查
+ */
+
+import { SELF_IMPROVE_COOLDOWN_MS } from '../agents/shell-guard.js';
+
+export type SelfImproveEvent =
+  | { kind: 'ci-failed'; details: string }
+  | { kind: 'task-failures'; details: string }
+  | { kind: 'silent-timeout'; details: string }
+  | { kind: 'user-requested'; details: string };
+
+interface EventRecord {
+  at: number;
+  count: number;
+}
+
+const EVENT_COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24 小时内同类型只触发 1 次
+
+const eventHistory: Map<SelfImproveEvent['kind'], EventRecord> = new Map();
+let lastTriggerAt: number | null = null;
+
+type Listener = (event: SelfImproveEvent, goal: string) => void | Promise<void>;
+const listeners: Set<Listener> = new Set();
+
+/**
+ * 订阅自改触发事件
+ */
+export function onSelfImproveTrigger(fn: Listener): () => void {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+
+/**
+ * 心跳事件 → 自改总线
+ *
+ * @returns { triggered: boolean, reason?: string }
+ */
+export function reportSelfImproveEvent(event: SelfImproveEvent): { triggered: boolean; reason?: string } {
+  // 1. 24 小时同类事件冷却
+  const prev = eventHistory.get(event.kind);
+  if (prev && Date.now() - prev.at < EVENT_COOLDOWN_MS) {
+    return { triggered: false, reason: `同类事件 ${event.kind} 在 24h 内已记录过, 跳过` };
+  }
+
+  // 2. 累加计数
+  eventHistory.set(event.kind, {
+    at: Date.now(),
+    count: (prev?.count || 0) + 1
+  });
+
+  // 3. 自改循环冷却
+  if (lastTriggerAt && Date.now() - lastTriggerAt < SELF_IMPROVE_COOLDOWN_MS) {
+    const waitHrs = Math.ceil((SELF_IMPROVE_COOLDOWN_MS - (Date.now() - lastTriggerAt)) / 3600000);
+    return { triggered: false, reason: `自改冷却中, 还需要约 ${waitHrs} 小时` };
+  }
+
+  // 4. 触发
+  lastTriggerAt = Date.now();
+  const goal = `信号事件: ${event.kind} - ${event.details}`;
+
+  console.log(`[self-improve-bus] 🚀 触发自改循环: ${goal}`);
+
+  // 异步触发所有 listener, 不阻塞调用方
+  Promise.resolve().then(async () => {
+    for (const listener of listeners) {
+      try {
+        await listener(event, goal);
+      } catch (err) {
+        console.error(`[self-improve-bus] listener 失败:`, err);
+      }
+    }
+  });
+
+  return { triggered: true };
+}
+
+/**
+ * 获取当前事件历史 (供调试 / UI 显示)
+ */
+export function getEventHistory(): Array<{ kind: string; at: string; count: number }> {
+  return Array.from(eventHistory.entries()).map(([kind, rec]) => ({
+    kind,
+    at: new Date(rec.at).toISOString(),
+    count: rec.count
+  }));
+}
+
+/**
+ * 强制重置 (仅供调试)
+ */
+export function resetSelfImproveBus(): void {
+  eventHistory.clear();
+  lastTriggerAt = null;
+  console.log('[self-improve-bus] 已重置');
+}

package/src/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 缺失类型模块的兜底声明 — 让 strict tsc 通过, 避免阻塞发布。
+ * 这些是项目里实际使用但 @types 包未安装或缺失的小依赖。
+ */
+declare module 'js-yaml' {
+  const yaml: {
+    load: (str: string) => any;
+    dump: (obj: any, opts?: any) => string;
+  };
+  export default yaml;
+  export = yaml;
+}

package/src/utils/auto-update.ts

@@ -283,27 +283,27 @@ function checkNpmOutdated(): OutdatedPackage[] {
  * 自动更新 npm 包
  */
 async function updatePackages(packages?: string[]): Promise<UpdateResult> {
-  try {
-    const args = packages && packages.length > 0
-      ? ['npm', 'install', ...packages, '--save']
-      : ['npm', 'install', '-g', '@bolloon/bolloon-agent'];
+  // 记录更新前的版本，用于事后判断"是否真的升级了"
+  // 与 getInstalledVersion 的"优先读全局"保持一致 —— install 也用 -g，
+  // 否则判断和执行落在不同的目录，永远改不到那个被读取的版本号。
+  const targets = packages && packages.length > 0 ? packages : ['@bolloon/bolloon-agent'];
+  const before = new Map<string, string | null>();
+  for (const p of targets) before.set(p, getInstalledVersion(p));
+
+  const isGlobal = !packages || packages.length === 0;
+  const args = isGlobal
+    ? ['npm', 'install', '-g', ...targets]
+    : ['npm', 'install', ...targets, '--save'];
 
-    log(`\n${CYAN}📦 正在更新包...${RESET}\n`, RESET);
+  log(`\n${CYAN}📦 正在更新包...${RESET}\n`, RESET);
 
-    // 执行 npm install
-    const result = execSync(args.join(' '), {
+  try {
+    execSync(args.join(' '), {
       encoding: 'utf-8',
       timeout: 300000, // 5分钟超时
       stdio: 'inherit',
       cwd: process.cwd()
     });
-
-    return {
-      success: true,
-      updated: true,
-      message: '更新成功',
-      updatedPackages: packages
-    };
   } catch (e: any) {
     return {
       success: false,
@@ -312,6 +312,37 @@ async function updatePackages(packages?: string[]): Promise<UpdateResult> {
       error: e.message
     };
   }
+
+  // install 退出码 0 并不等于"真的升上去了"（"up to date" 也是 0）。
+  // 重新读取磁盘版本，只有真的达到目标 latest 之一才算 updated。
+  const upgraded: string[] = [];
+  const failed: string[] = [];
+  for (const p of targets) {
+    const after = getInstalledVersion(p);
+    const was = before.get(p);
+    if (after && was && compareVersions(was, after) < 0) {
+      upgraded.push(p);
+    } else if (after && was && compareVersions(was, after) === 0) {
+      // 版本没变 —— install 跑过但没改动；不当作"刚升级"
+    } else {
+      failed.push(p);
+    }
+  }
+
+  if (upgraded.length > 0) {
+    return {
+      success: true,
+      updated: true,
+      message: `已更新: ${upgraded.join(', ')}`,
+      updatedPackages: upgraded
+    };
+  }
+  return {
+    success: true,
+    updated: false,
+    message: '已是最新版本，无需重启',
+    updatedPackages: []
+  };
 }
 
 /**