@bolloon/bolloon-agent 0.1.34 → 0.1.36

package/src/bootstrap/context-hierarchy.ts

@@ -0,0 +1,283 @@
+/**
+ * Context Hierarchy — 4 级 Bolloon.md 查找 + 合并优先级
+ *
+ * 设计: 严格对齐 Claude Code 论文 4 级层次
+ *   1. Managed  — /etc/bolloon/Bolloon.md        (企业 IT 部署, 系统级)
+ *   2. User     — ~/.bolloon/Bolloon.md          (用户级, 跨项目)
+ *   3. Project  — <cwd>/Bolloon.md 或 .claude/rules/*.md
+ *   4. Local    — <cwd>/CLAUDE.local.md         (个人覆盖, .gitignore)
+ *
+ * 注入约定 (论文):
+ * - 拼到 system prompt 顶部 (作为 user context, 概率性遵守)
+ * - 不混入 user 消息 (避免 prompt injection)
+ * - 截断时反向砍 local → project → user → managed (优先保 managed, 因为是 bolloon 自身约束)
+ *
+ * 兼容:
+ * - 同时识别 Bolloon.md 和 Bolloon.md (论文用前者, bolloon 历史用后者)
+ * - 文件名按优先级: Bolloon.md > Bolloon.md
+ *
+ * 失败静默: 任何 IO 错误 → 返回 null, 不阻塞主流程.
+ */
+
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+
+// ============================================================
+// 4 级路径配置
+// ============================================================
+
+export interface HierarchyPaths {
+  managed: string;  // /etc/bolloon/Bolloon.md
+  user: string;     // ~/.bolloon/Bolloon.md
+  project: string;  // <cwd>/Bolloon.md
+  projectRulesDir: string;  // <cwd>/.claude/rules/
+  local: string;    // <cwd>/CLAUDE.local.md
+}
+
+export interface HierarchyChars {
+  managed: number;
+  user: number;
+  project: number;
+  local: number;
+}
+
+export interface HierarchyLimits {
+  paths?: Partial<HierarchyPaths>;
+  maxChars?: Partial<HierarchyChars>;
+}
+
+export const DEFAULT_PATHS: HierarchyPaths = {
+  managed: '/etc/bolloon/Bolloon.md',
+  user: '',  // 用 resolveUserPath 填
+  project: '',  // 用 resolveProjectPaths 填
+  projectRulesDir: '',
+  local: '',
+};
+
+/**
+ * 单层字符上限 (P-Action 4 收紧, 阶段 0 把 4 级层次控制在 ≤ 2KB).
+ * 反向截断策略保证 managed 优先, 单层超限由 truncate() 截断.
+ */
+export const DEFAULT_MAX_CHARS: HierarchyChars = {
+  managed: 700,   // 1500 → 700, 保 bolloon 自身约束
+  user: 500,      // 1500 → 500, 跨项目偏好
+  project: 500,   // 2500 → 500, 项目规则
+  local: 300,     // 1500 → 300, 个人覆盖
+};
+
+// ============================================================
+// 路径解析
+// ============================================================
+
+export function resolveUserPath(home?: string): string {
+  const h = home ?? process.env.HOME ?? os.homedir() ?? '/tmp';
+  return path.join(h, '.bolloon', 'Bolloon.md');
+}
+
+export function resolveProjectPaths(cwd: string): { project: string; projectRulesDir: string; local: string } {
+  return {
+    project: path.join(cwd, 'Bolloon.md'),
+    projectRulesDir: path.join(cwd, '.claude', 'rules'),
+    local: path.join(cwd, 'CLAUDE.local.md'),
+  };
+}
+
+// ============================================================
+// 单层读取 (优先 Bolloon.md, fallback Bolloon.md)
+// ============================================================
+
+/**
+ * 读 1 个文件路径, 失败/缺失返回 null.
+ * 字符上限由调用方截断 (这里只负责读全文).
+ */
+async function readRuleFile(filePath: string): Promise<string | null> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content.length > 0 ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 读 project 层: 优先 Bolloon.md, fallback Bolloon.md, 最后尝试 .claude/rules/*.md
+ */
+async function readProjectLayer(projectPath: string, projectRulesDir: string, maxChars: number): Promise<string | null> {
+  // 1. Bolloon.md
+  let content = await readRuleFile(projectPath);
+  if (content) return truncate(content, maxChars);
+
+  // 2. Bolloon.md (向后兼容)
+  const bolloonMdPath = path.join(path.dirname(projectPath), 'Bolloon.md');
+  content = await readRuleFile(bolloonMdPath);
+  if (content) return truncate(content, maxChars);
+
+  // 3. .claude/rules/*.md (合并所有)
+  try {
+    const entries = await fs.readdir(projectRulesDir, { withFileTypes: true });
+    const ruleFiles = entries
+      .filter((e) => e.isFile() && e.name.endsWith('.md'))
+      .map((e) => path.join(projectRulesDir, e.name))
+      .sort();
+    if (ruleFiles.length > 0) {
+      const parts: string[] = [];
+      let total = 0;
+      for (const f of ruleFiles) {
+        const c = await readRuleFile(f);
+        if (c) {
+          parts.push(`### ${path.basename(f, '.md')}\n${c}`);
+          total += c.length;
+          if (total >= maxChars) break;
+        }
+      }
+      if (parts.length > 0) return truncate(parts.join('\n\n'), maxChars);
+    }
+  } catch { /* dir 不存在 */ }
+
+  return null;
+}
+
+// ============================================================
+// 4 层收集
+// ============================================================
+
+export interface HierarchyLayers {
+  managed: string | null;  // /etc/bolloon/Bolloon.md
+  user: string | null;     // ~/.bolloon/Bolloon.md
+  project: string | null;  // <cwd>/Bolloon.md
+  local: string | null;    // <cwd>/CLAUDE.local.md
+}
+
+export interface CollectHierarchyOptions {
+  cwd: string;
+  limits?: HierarchyLimits;
+  /** 覆盖 HOME (测试用) */
+  home?: string;
+}
+
+/**
+ * 并行读 4 层, 任何一层失败 = null (不阻塞其他).
+ */
+export async function collectHierarchyLayers(opts: CollectHierarchyOptions): Promise<HierarchyLayers> {
+  const limits: HierarchyLimits['maxChars'] = { ...DEFAULT_MAX_CHARS, ...(opts.limits?.maxChars ?? {}) };
+
+  const home = opts.home ?? process.env.HOME ?? os.homedir() ?? '/tmp';
+  const managedPath = opts.limits?.paths?.managed ?? DEFAULT_PATHS.managed;
+  const userPath = opts.limits?.paths?.user ?? resolveUserPath(home);
+  const projectPath = opts.limits?.paths?.project ?? path.join(opts.cwd, 'Bolloon.md');
+  const projectRulesDir = opts.limits?.paths?.projectRulesDir ?? path.join(opts.cwd, '.claude', 'rules');
+  const localPath = opts.limits?.paths?.local ?? path.join(opts.cwd, 'CLAUDE.local.md');
+
+  const [managed, user, project, local] = await Promise.all([
+    readRuleFile(managedPath).then((c) => c ? truncate(c, limits.managed!) : null),
+    readRuleFile(userPath).then((c) => c ? truncate(c, limits.user!) : null),
+    readProjectLayer(projectPath, projectRulesDir, limits.project!),
+    readRuleFile(localPath).then((c) => c ? truncate(c, limits.local!) : null),
+  ]);
+
+  return { managed, user, project, local };
+}
+
+// ============================================================
+// 合并 + 截断
+// ============================================================
+
+export interface MergeOptions {
+  /** 总字符上限 (默认 8000, 之前 project-context.ts 用 4000) */
+  maxChars?: number;
+}
+
+/**
+ * 4 级合并总字符上限 (P-Action 4 收紧, ≤ 2KB ≈ 500 tokens).
+ * 反向截断 (local → project → user → managed) 保证 managed 不丢.
+ */
+export const DEFAULT_MERGE_MAX_CHARS = 2000;
+
+/**
+ * 按 4 级顺序 (managed → user → project → local) 拼接为 markdown 片段.
+ *
+ * 截断策略: 反向砍 (local → project → user → managed), 优先保 managed.
+ * - 总长 < maxChars: 不截断
+ * - 总长 ≥ maxChars: 按 (local, project, user) 顺序逐步砍到 firstParagraphs=1
+ * - 最后只保 managed (bolloon 自身约束不能丢)
+ */
+export function mergeHierarchyLayers(layers: HierarchyLayers, opts: MergeOptions = {}): string {
+  const maxChars = opts.maxChars ?? DEFAULT_MERGE_MAX_CHARS;
+  const parts: string[] = [];
+  const labels: Array<[keyof HierarchyLayers, string]> = [
+    ['managed', '管理规则 (Managed)'],
+    ['user', '用户规则 (User)'],
+    ['project', '项目规则 (Project)'],
+    ['local', '本地规则 (Local)'],
+  ];
+
+  for (const [key, label] of labels) {
+    const content = layers[key];
+    if (content) {
+      parts.push(`## ${label}\n\n${content}`);
+    }
+  }
+
+  if (parts.length === 0) return '';
+  let result = parts.join('\n\n---\n\n');
+  if (result.length <= maxChars) return result;
+
+  // 超限: 反向砍 (local → project → user), 二级回退到 firstParagraphs=1
+  return truncateMerged(layers, maxChars);
+}
+
+function truncateMerged(layers: HierarchyLayers, maxChars: number): string {
+  const order: Array<[keyof HierarchyLayers, string]> = [
+    ['local', '本地规则 (Local)'],
+    ['project', '项目规则 (Project)'],
+    ['user', '用户规则 (User)'],
+    ['managed', '管理规则 (Managed)'],
+  ];
+  const capped: HierarchyLayers = { ...layers };
+  // 反复压缩, 直到总长 ≤ maxChars
+  let depth = 0;  // 0=原始, 1=firstParagraphs=1, 2=砍半
+  while (depth < 3) {
+    const parts: string[] = [];
+    for (const [key, label] of order) {
+      const c = capped[key];
+      if (!c) continue;
+      let text = c;
+      if (depth === 1) text = firstParagraphs(c, 1);
+      if (depth === 2) text = firstParagraphs(c, 1, Math.floor(maxChars / 4));
+      parts.push(`## ${label}\n\n${text}`);
+    }
+    const joined = parts.reverse().join('\n\n---\n\n');  // 恢复 managed → user → project → local
+    if (joined.length <= maxChars) return joined;
+    depth++;
+  }
+  // 最后保 managed 一行
+  return `## 管理规则 (Managed)\n\n${firstParagraphs(layers.managed ?? '(无)', 1, maxChars - 50)}`;
+}
+
+// ============================================================
+// 工具
+// ============================================================
+
+function truncate(s: string, maxChars: number): string {
+  if (s.length <= maxChars) return s;
+  return s.substring(0, maxChars) + '\n... (truncated)';
+}
+
+function firstParagraphs(text: string, count: number, maxLen?: number): string {
+  const paragraphs = text.split(/\n\s*\n/).filter((p) => p.trim().length > 0);
+  let result = paragraphs.slice(0, count).join('\n\n');
+  if (maxLen && result.length > maxLen) {
+    result = result.substring(0, maxLen) + '...';
+  }
+  return result;
+}
+
+// ============================================================
+// 测试钩子
+// ============================================================
+
+/** 重置模块级状态 (供测试). 当前无状态, 保留为占位. */
+export function _resetHierarchyForTest(): void {
+  // no-op (collect 是纯函数, 但保留 API 一致)
+}

package/src/bootstrap/lifecycle-hooks.ts

@@ -0,0 +1,289 @@
+/**
+ * Lifecycle Hooks — SessionStart / Stop / PreToolUse
+ *
+ * 失败静默: 任意 hook 挂掉不抛错, 仅 console.warn.
+ * 任何调用方都可以放心 await, 不会阻塞主对话.
+ */
+
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { getCachedBolloonContext, clearBolloonContextCache } from './context-collector.js';
+import { formatContextForSystemPrompt } from './project-context.js';
+
+// ============================================================
+// SessionStart
+// ============================================================
+
+export interface SessionStartOptions {
+  /** channelId 暂时不传到 context (单 channel 维度, plan 范围) */
+  channelId?: string;
+  /** 工作目录, 默认 process.cwd() */
+  cwd?: string;
+  /** 强制重扫, 跳过 24h 缓存 */
+  force?: boolean;
+  /** system prompt 片段字符上限 */
+  maxChars?: number;
+}
+
+export interface SessionStartResult {
+  /** 拼到 system prompt 头部的 markdown 文本 */
+  systemAddition: string;
+  /** 收集耗时 ms */
+  collectMs: number;
+  /** 是否被截断 */
+  truncated: boolean;
+}
+
+let lastSessionStartAt = 0;
+const MIN_INTERVAL_MS = 5000; // 同一进程 5s 内最多触发一次, 防止循环
+
+export async function onSessionStart(opts: SessionStartOptions = {}): Promise<SessionStartResult> {
+  const start = Date.now();
+  if (start - lastSessionStartAt < MIN_INTERVAL_MS) {
+    // 限流: 返回空 (调用方已经有缓存, 不需要重算)
+    return { systemAddition: '', collectMs: 0, truncated: false };
+  }
+  lastSessionStartAt = start;
+
+  try {
+    const ctx = await getCachedBolloonContext(
+      { cwd: opts.cwd ?? process.cwd() },
+      opts.force ?? false
+    );
+    let systemAddition = formatContextForSystemPrompt(ctx, { maxChars: opts.maxChars });
+    // 在头部加 channel 标识 (供 LLM 知道当前对话归属)
+    if (opts.channelId) {
+      systemAddition = `# 当前 channel: ${opts.channelId}\n\n` + systemAddition;
+    }
+    return {
+      systemAddition,
+      collectMs: Date.now() - start,
+      truncated: systemAddition.length > 0 && systemAddition.includes('截断模式'),
+    };
+  } catch (err) {
+    console.warn('[lifecycle-hooks] onSessionStart failed (silent):', err);
+    return { systemAddition: '', collectMs: Date.now() - start, truncated: false };
+  }
+}
+
+export function clearSessionStartCache(): void {
+  lastSessionStartAt = 0;
+  clearBolloonContextCache();
+}
+
+// ============================================================
+// Stop
+// ============================================================
+
+export interface StopOptions {
+  channelId: string;
+  messages?: number;
+  durationMs: number;
+  /** 注入门使用过的 judgment ids (供审计) */
+  usedJudgmentIds?: string[];
+}
+
+export interface StopResult {
+  persisted: boolean;
+  path: string | null;
+}
+
+const STOP_LOG = (os.homedir() || process.env.HOME || '/tmp') + '/.bolloon/sessions';
+
+/**
+ * 把本次 session 摘要写 ~/.bolloon/sessions/<channelId>/last-stop.json
+ * 不重复写完整 session 持久化 (已由 createWebServer 内的 saveSession 处理)
+ */
+export async function onStop(opts: StopOptions): Promise<StopResult> {
+  try {
+    const dir = path.join(STOP_LOG, sanitizeChannelId(opts.channelId));
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, 'last-stop.json');
+    const entry = {
+      ts: new Date().toISOString(),
+      channelId: opts.channelId,
+      messages: opts.messages ?? 0,
+      durationMs: opts.durationMs,
+      usedJudgmentIds: opts.usedJudgmentIds ?? [],
+    };
+    await fs.writeFile(file, JSON.stringify(entry, null, 2), 'utf-8');
+    return { persisted: true, path: file };
+  } catch (err) {
+    console.warn('[lifecycle-hooks] onStop failed (silent):', err);
+    return { persisted: false, path: null };
+  }
+}
+
+function sanitizeChannelId(id: string): string {
+  // 防止路径穿越
+  return id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+
+// ============================================================
+// PreToolUse (P2: 4 步链式 validator + permission mode)
+// ============================================================
+
+import { resolvePermissionMode, type PermissionMode } from '../agents/permission-mode.js';
+import { validatePreToolUse } from '../agents/pre-tool-validator.js';
+
+export interface PreToolUseOptions {
+  tool: string;
+  args: Record<string, unknown>;
+  /** 可选, 不传则用 env BOLLOON_PERM_MODE 或 default */
+  permissionMode?: PermissionMode;
+}
+
+export interface PreToolUseResult {
+  allowed: boolean;
+  reason?: string;
+  /** P2: 哪一步拒绝的, 供 audit log */
+  rejectedBy?: 'mode' | 'blacklist' | 'shell-guard' | 'schema';
+  mode: PermissionMode;
+  shellGuardRetained?: boolean;
+}
+
+/**
+ * PreToolUse: 4 步链式 validator
+ *   1. modeGate         (bypassPermissions + 非 shell 直接放行)
+ *   2. blacklistGate    (6 模式危险命令)
+ *   3. shellGuardGate   (路径黑名单, 绕过 mode 永远生效)
+ *   4. schemaGate       (第一版 stub: always allow)
+ *
+ * 向后兼容: 不传 permissionMode → 默认 'default' (env BOLLOON_PERM_MODE 仍生效)
+ * 失败静默: 任何异常 → allowed: true (与原行为一致)
+ */
+export async function onPreToolUse(opts: PreToolUseOptions): Promise<PreToolUseResult> {
+  try {
+    const mode = resolvePermissionMode({ permissionMode: opts.permissionMode });
+    return validatePreToolUse(opts.tool, opts.args || {}, mode);
+  } catch (err) {
+    console.warn('[lifecycle-hooks] onPreToolUse failed (silent, allowing):', err);
+    return { allowed: true, mode: 'default' };  // 失败放行 (不阻塞)
+  }
+}
+
+// ============================================================
+// 测试辅助: 获取 STOP_LOG 路径 (供测试覆盖路径)
+// ============================================================
+
+export function getStopLogPathForTest(): string {
+  return STOP_LOG;
+}
+
+// ============================================================
+// PostToolUse (P+ : 工具调用后审计)
+// ============================================================
+
+export interface PostToolUseOptions {
+  tool: string;
+  args: Record<string, unknown>;
+  result: { success: boolean; output?: string; error?: string };
+  durationMs?: number;
+}
+
+export interface PostToolUseResult {
+  /** 是否允许继续 (false = abort 整个 ReAct 循环) */
+  continue: boolean;
+  reason?: string;
+}
+
+/**
+ * PostToolUse: 工具调用后审计
+ * 默认 always continue. 项目可挂 shell-guard audit log / judgment 注入门 / 监控门
+ * 失败静默: 任何异常 → continue: true (不阻塞主循环)
+ */
+export async function onPostToolUse(opts: PostToolUseOptions): Promise<PostToolUseResult> {
+  try {
+    // 审计日志: 写 ~/.bolloon/sessions/post-tool-audit.jsonl
+    const fs = await import('fs/promises');
+    const os = await import('os');
+    const path = await import('path');
+    const file = path.join(
+      process.env.HOME || os.homedir() || '/tmp',
+      '.bolloon', 'sessions', 'post-tool-audit.jsonl'
+    );
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const entry = {
+      ts: new Date().toISOString(),
+      tool: opts.tool,
+      success: opts.result.success,
+      durationMs: opts.durationMs ?? 0,
+      // 不写 args (可能含密钥), 只写 result 的 success/error
+      error: opts.result.error?.substring(0, 200) || null,
+    };
+    await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { /* ignore */ });
+    return { continue: true };
+  } catch (err) {
+    console.warn('[lifecycle-hooks] onPostToolUse failed (silent, allowing):', err);
+    return { continue: true };
+  }
+}
+
+// ============================================================
+// JudgmentInjected (bolloon 独有 : 注入门使用时审计)
+// ============================================================
+
+export interface JudgmentInjectedOptions {
+  judgmentIds: string[];
+  channelId?: string;
+  userInput?: string;
+}
+
+export async function onJudgmentInjected(opts: JudgmentInjectedOptions): Promise<void> {
+  try {
+    const fs = await import('fs/promises');
+    const os = await import('os');
+    const path = await import('path');
+    const file = path.join(
+      process.env.HOME || os.homedir() || '/tmp',
+      '.bolloon', 'sessions', 'judgment-injected.jsonl'
+    );
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const entry = {
+      ts: new Date().toISOString(),
+      channelId: opts.channelId || 'unknown',
+      judgmentIds: opts.judgmentIds,
+      userInputSnippet: (opts.userInput || '').substring(0, 200),
+    };
+    await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { /* ignore */ });
+  } catch (err) {
+    console.warn('[lifecycle-hooks] onJudgmentInjected failed (silent):', err);
+  }
+}
+
+// ============================================================
+// MonitorViolation (bolloon 独有 : 监控门审计违规)
+// ============================================================
+
+export interface MonitorViolationOptions {
+  channelId?: string;
+  judgmentId: string;
+  rule: string;
+  actualBehavior: string;
+  severity: 'low' | 'medium' | 'high';
+}
+
+export async function onMonitorViolation(opts: MonitorViolationOptions): Promise<void> {
+  try {
+    const fs = await import('fs/promises');
+    const os = await import('os');
+    const path = await import('path');
+    const file = path.join(
+      process.env.HOME || os.homedir() || '/tmp',
+      '.bolloon', 'sessions', 'monitor-violation.jsonl'
+    );
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const entry = {
+      ts: new Date().toISOString(),
+      channelId: opts.channelId || 'unknown',
+      judgmentId: opts.judgmentId,
+      rule: opts.rule.substring(0, 200),
+      actualBehavior: opts.actualBehavior.substring(0, 200),
+      severity: opts.severity,
+    };
+    await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8').catch(() => { /* ignore */ });
+  } catch (err) {
+    console.warn('[lifecycle-hooks] onMonitorViolation failed (silent):', err);
+  }
+}