@bolloon/bolloon-agent 0.1.35 → 0.1.37

package/dist/agents/pre-tool-validator.js

@@ -0,0 +1,194 @@
+/**
+ * Pre-Tool Validator — 4 步链式校验
+ *
+ * 严格对齐 Claude Code 论文 PreToolUse 4 步:
+ *   1. modeGate(tool, mode)         — bypassPermissions → 直接放行(除 shell)
+ *   2. blacklistGate(tool, args)    — 6 模式黑名单 (recursive rm, force push, dd 等)
+ *   3. shellGuardGate(tool, args)   — **完整** shell-guard (checkCommand + checkWritePath), 永远生效
+ *   4. schemaGate(tool, args)       — 第一版 stub: always allow (后续接入 tool-gate.ts)
+ *
+ * 每步独立 try/catch, 失败 = 跳过该步, 不阻塞 (与现有 lifecycle-hooks 风格一致)
+ *
+ * 失败静默: 任何 step 异常 → console.warn + 继续下一 step, 不抛错
+ */
+import { isShellTool } from './permission-mode.js';
+import { checkCommand, checkWritePath } from './shell-guard.js';
+const DANGEROUS_PATTERNS = [
+    { re: /\brm\s+(-[a-z]*f[a-z]*\s+)?-[a-z]*r[a-z]*\s+\//, reason: '禁止递归删除根目录' },
+    { re: /\bgit\s+push\s+.*--force\b/, reason: '禁止 force push' },
+    { re: /\brm\s+-rf\s+~\//, reason: '禁止递归删除 home' },
+    { re: /\bdd\s+if=.*\s+of=\/dev\//, reason: '禁止 dd 覆盖块设备' },
+    { re: /\bcurl\s+.*\|\s*(ba)?sh\b/, reason: '禁止 curl|sh 直执行' },
+    { re: />\s*\/dev\/sd[a-z]/, reason: '禁止写裸设备' },
+];
+/**
+ * Step 1: modeGate
+ * - bypassPermissions + 非 shell → 直接放行 (但保留 shellGuardRetained 标记)
+ * - 其他 → 继续
+ */
+function modeGate(tool, mode) {
+    try {
+        if (mode === 'bypassPermissions' && !isShellTool(tool)) {
+            return { allowed: true, mode, rejectedBy: undefined, shellGuardRetained: false };
+        }
+        return null; // 不在这一步决定
+    }
+    catch (err) {
+        console.warn('[pre-tool] modeGate failed (silent):', err);
+        return null;
+    }
+}
+/**
+ * Step 2: blacklistGate
+ * 6 模式黑名单 (现有 lifecycle-hooks.ts 行为)
+ */
+function blacklistGate(tool, args, mode) {
+    try {
+        if (!isShellTool(tool))
+            return null;
+        const cmd = String(args.command || args.cmd || '');
+        if (!cmd)
+            return null;
+        for (const { re, reason } of DANGEROUS_PATTERNS) {
+            if (re.test(cmd)) {
+                return { allowed: false, reason, rejectedBy: 'blacklist', mode };
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        console.warn('[pre-tool] blacklistGate failed (silent):', err);
+        return null;
+    }
+}
+/**
+ * Step 3: shellGuardGate
+ * 永远跑 (绕过 mode), 是 bolloon 自身的安全底线
+ *
+ * 接完整 shell-guard.ts (checkCommand + checkWritePath):
+ *   - checkCommand 走命令白名单 + 参数黑名单 (允许列表默认 git/node/npm/npx/tsx/tsc/vitest 等)
+ *   - checkWritePath 走路径黑名单 (硬编码: pi-sdk.ts, shell-guard.ts, .env, .git/, .bolloon/, package.json, dist/ 等)
+ *
+ * 失败静默: 任何异常 → 跳过这步, 不阻塞
+ */
+function shellGuardGate(tool, args, mode) {
+    try {
+        if (!isShellTool(tool))
+            return null;
+        // 1. 命令检查 (含白名单 + arg 黑名单)
+        const cmd = String(args.command || args.cmd || '');
+        let bin = '';
+        if (cmd) {
+            // shell-guard 期望 (cmd, args[]) 形式
+            // 简单 split: 第一个 token 是 cmd, 之后是 args
+            const parts = cmd.split(/\s+/).filter(Boolean);
+            bin = parts[0] || '';
+            const rest = parts.slice(1);
+            if (bin) {
+                const cmdResult = checkCommand(bin, rest);
+                if (!cmdResult.allowed) {
+                    return {
+                        allowed: false,
+                        reason: cmdResult.reason,
+                        rejectedBy: 'shell-guard',
+                        mode,
+                        shellGuardRetained: true,
+                    };
+                }
+            }
+        }
+        // 2. 写路径检查 — 从 2 个来源抽:
+        //    a) 结构化字段 (args.path / args.target / args.file)
+        //    b) 命令字符串里的 token (老测试传 args.command='cat pi-sdk.ts' 时也能拦)
+        const pathCandidates = [];
+        const structured = String(args.path || args.target || args.file || args.targetPath || args.destination || '');
+        if (structured)
+            pathCandidates.push(structured);
+        if (cmd) {
+            // 简单 tokenize: 按空白切, 取不含 shell 元字符的 token
+            const tokens = cmd.split(/\s+/).filter((t) => t && !/^[|>;&`$()<]/.test(t));
+            for (const t of tokens) {
+                if (t !== bin)
+                    pathCandidates.push(t); // 跳过命令本身
+            }
+        }
+        // 纯文件名 denylist (兜底 — checkWritePath 的 regex 要求 /src/xxx/ 锚定, 纯文件名拦不到)
+        // 只对**写/删/改**类命令生效 (rm, cp, mv, sed -i, echo >); 读类命令 (cat, head, tail, ls) 跳过
+        const READ_BINS = new Set(['cat', 'head', 'tail', 'wc', 'ls', 'echo', 'pwd', 'date', 'mkdir', 'touch', 'find', 'grep', 'git', 'node', 'npm', 'npx', 'tsx', 'tsc', 'vitest']);
+        const FILENAME_DENYLIST = [
+            'pi-sdk.ts', 'shell-guard.ts', 'shell-tool.ts',
+            '.env', 'package.json', 'tsconfig.json',
+        ];
+        const isReadOperation = READ_BINS.has(bin);
+        for (const candidate of pathCandidates) {
+            // 2a. checkWritePath 只对写操作调用 (读类命令绕开, 避免 cat pi-sdk.ts 误拦)
+            if (!isReadOperation) {
+                const pathResult = checkWritePath(candidate);
+                if (!pathResult.allowed) {
+                    return {
+                        allowed: false,
+                        reason: pathResult.reason,
+                        rejectedBy: 'shell-guard',
+                        mode,
+                        shellGuardRetained: true,
+                    };
+                }
+            }
+            // 2b. 纯文件名兜底 — 只对写操作生效
+            if (!isReadOperation) {
+                const baseName = candidate.split('/').pop() || '';
+                if (FILENAME_DENYLIST.includes(baseName)) {
+                    return {
+                        allowed: false,
+                        reason: `shell-guard: 禁止 ${bin} 操作 ${candidate} (命中文件名硬编码黑名单)`,
+                        rejectedBy: 'shell-guard',
+                        mode,
+                        shellGuardRetained: true,
+                    };
+                }
+            }
+        }
+        return null; // 通过
+    }
+    catch (err) {
+        console.warn('[pre-tool] shellGuardGate failed (silent):', err);
+        return null;
+    }
+}
+/**
+ * Step 4: schemaGate
+ * 第一版 stub: always allow
+ */
+function schemaGate(_tool, _args, mode) {
+    return null; // 不在这一步决定
+}
+/**
+ * 主入口: 4 步链式, 任何一步拒绝 → 返回, 否则最终放行
+ */
+export function validatePreToolUse(tool, args, mode) {
+    const steps = [
+        () => modeGate(tool, mode),
+        () => blacklistGate(tool, args, mode),
+        () => shellGuardGate(tool, args, mode),
+        () => schemaGate(tool, args, mode),
+    ];
+    for (const step of steps) {
+        const result = step();
+        if (result && !result.allowed)
+            return result;
+    }
+    // 全部通过 → 放行
+    // bypassPermissions + shell 走到这里 = shellGuardGate 已经放过, 但要标记 shellGuardRetained
+    return {
+        allowed: true,
+        mode,
+        rejectedBy: undefined,
+        shellGuardRetained: isShellTool(tool),
+    };
+}
+// ============================================================
+// 测试钩子
+// ============================================================
+export function _resetValidatorForTest() {
+    // validator 是 pure, 保留 API 一致
+}

package/dist/agents/workflow-pivot-loop.js

@@ -208,6 +208,19 @@ export class WorkflowPivotLoop {
                             type: 'error',
                             content: `❌ 未知工具: ${toolCall.name}`
                         });
+                        // 2026-06-15: step-timeline — 未知工具也开/关一个 step 节点
+                        this.emit({
+                            type: 'step_start',
+                            content: `未知工具 ${toolCall.name}`,
+                            tool: toolCall.name,
+                            args: toolCall.args || {},
+                        });
+                        this.emit({
+                            type: 'step_error',
+                            content: `未知工具 ${toolCall.name}`,
+                            tool: toolCall.name,
+                            error: 'Unknown tool',
+                        });
                         this.messageHistory.push({
                             role: 'tool',
                             content: JSON.stringify({ success: false, error: `Unknown tool: ${toolCall.name}` })
@@ -219,8 +232,26 @@ export class WorkflowPivotLoop {
                         content: `🔧 执行: ${toolCall.name}`,
                         tool: toolCall.name
                     });
+                    // 2026-06-15: step-timeline — 开节点
+                    this.emit({
+                        type: 'step_start',
+                        content: `调用 ${toolCall.name}`,
+                        tool: toolCall.name,
+                        args: toolCall.args || {},
+                    });
                     try {
                         const result = await tool.execute(toolCall.args ?? {});
+                        // 2026-06-15: step-timeline — 关闭节点 (success / error)
+                        this.emit({
+                            type: result.success ? 'step_done' : 'step_error',
+                            content: result.success
+                                ? `${toolCall.name} 成功`
+                                : `${toolCall.name} 失败: ${result.error}`,
+                            tool: toolCall.name,
+                            success: result.success,
+                            output: result.output,
+                            error: result.error,
+                        });
                         this.emit({
                             type: result.success ? 'status' : 'error',
                             content: result.success
@@ -305,9 +336,49 @@ export class WorkflowPivotLoop {
      */
     extractPendingToolUses(content) {
         const pending = [];
+        // Pattern 0: <tool_use>{...JSON...}</tool_use> (Anthropic 风格 + minimax 也用)
+        // 这次 LLM 输出: <tool_use>\n{"name": "read_document", "arguments": {"path": "/Users/.../README.md"}}\n</tool_use>
+        const toolUseRe = /<tool_use>\s*(\{[\s\S]*?\})\s*<\/tool_use>/g;
+        let match;
+        while ((match = toolUseRe.exec(content)) !== null) {
+            try {
+                const obj = JSON.parse(match[1]);
+                if (obj && obj.name && this.tools.has(obj.name)) {
+                    const args = this.normalizeArgs(obj.arguments || {});
+                    pending.push({ name: obj.name, args, description: '', parameters: {} });
+                }
+            }
+            catch (e) {
+                // JSON 解析失败, 继续下一 match
+            }
+        }
+        // Pattern 0b: <function_calls><invoke name="X"><parameter name="k">v</parameter>...</invoke></function_calls>
+        //   这次 minimax LLM 用这种 Anthropic 风格 XML
+        const fnCallsRe = /<function_calls>([\s\S]*?)<\/function_calls>/g;
+        while ((match = fnCallsRe.exec(content)) !== null) {
+            const block = match[1];
+            // 抓 <invoke name="X">...</invoke>
+            const invokeRe = /<invoke\s+name="(\w+)"\s*>([\s\S]*?)<\/invoke>/g;
+            let im;
+            while ((im = invokeRe.exec(block)) !== null) {
+                const name = im[1];
+                if (!this.tools.has(name))
+                    continue;
+                // 抓 <parameter name="k">v</parameter> 列表
+                const args = {};
+                const paramRe = /<parameter\s+name="(\w+)"\s*>([\s\S]*?)<\/parameter>/g;
+                let pm;
+                while ((pm = paramRe.exec(im[2])) !== null) {
+                    args[pm[1]] = pm[2].trim().replace(/^["']|['"]$/g, '');
+                }
+                // 避免重复添加
+                if (!pending.some(p => p.name === name)) {
+                    pending.push({ name, args, description: '', parameters: {} });
+                }
+            }
+        }
         // Pattern 1: Chinese format "调用工具: tool_name(args)"
         const pattern1 = /调用工具[：:]\s*(\w+)\s*\(([^)]*)\)/g;
-        let match;
         while ((match = pattern1.exec(content)) !== null) {
             const name = match[1];
             const argsStr = match[2];
@@ -357,22 +428,52 @@ export class WorkflowPivotLoop {
             return args;
         const pairs = argsStr.split(',').map(s => s.trim()).filter(Boolean);
         for (const pair of pairs) {
-            const colonIdx = pair.indexOf(':');
-            if (colonIdx > 0) {
-                const key = pair.substring(0, colonIdx).trim();
-                const value = pair.substring(colonIdx + 1).trim().replace(/^['"]|['"]$/g, '');
-                args[key] = value;
+            // 2026-06-15: LLM 实际输出 3 种格式 — 全支持
+            //   1) JSON 风格: {"key":"value"}     (服务器日志显示, 但 LLM 不会真输出完整 JSON)
+            //   2) key="value" 含双引号         (本次 read_document(path="/Users/..."))
+            //   3) key='value' 含单引号
+            //   4) key:value                    (老 Chinese 格式)
+            //   5) key value                    (positional 兜底)
+            let m = pair.match(/^["']?([\w-]+)["']?\s*=\s*["']([^"']*)["']$/);
+            if (m) {
+                args[m[1]] = m[2];
+                continue;
             }
-            else {
-                // No colon, try to parse as positional
-                const parts = pair.split(/\s+/);
-                if (parts.length >= 2) {
-                    args[parts[0]] = parts.slice(1).join(' ');
-                }
+            m = pair.match(/^["']?([\w-]+)["']?\s*[:=]\s*([^,]+)$/);
+            if (m) {
+                args[m[1]] = m[2].trim().replace(/^['"]|['"]$/g, '');
+                continue;
+            }
+            m = pair.match(/^["']?([\w-]+)["']?\s*[:]\s*["']?([^"']*)["']?$/);
+            if (m) {
+                args[m[1]] = m[2].trim();
+                continue;
+            }
+            // positional 兜底
+            const parts = pair.split(/\s+/);
+            if (parts.length >= 2) {
+                args[parts[0]] = parts.slice(1).join(' ');
             }
         }
         return args;
     }
+    /**
+     * 把 tool_use JSON 里的 arguments (已经是对象) 转成 Record<string, string>
+     *   JSON parser 直接给对象, 但 tool.execute 期望 Record<string, string>
+     *   非字符串值 JSON.stringify 一下
+     */
+    normalizeArgs(args) {
+        const out = {};
+        for (const [k, v] of Object.entries(args || {})) {
+            if (v == null)
+                continue;
+            if (typeof v === 'string')
+                out[k] = v;
+            else
+                out[k] = JSON.stringify(v);
+        }
+        return out;
+    }
     /**
      * Build context from message history
      */

package/dist/bollharness-integration/context-router.js

@@ -25,7 +25,7 @@ export const CONTEXT_MAP = {
     'src/bollharness-integration/': ['truth-source-hierarchy', 'artifact-linkage'],
     'docs/': ['truth-source-hierarchy', 'two-language'],
     'docs/decisions/': ['truth-source-hierarchy', 'artifact-linkage'],
-    'CLAUDE.md': ['truth-source-hierarchy', 'bridge-constitution'],
+    'Bolloon.md': ['truth-source-hierarchy', 'bridge-constitution'],
     'README.md': ['truth-source-hierarchy', 'general-dev-principles'],
 };
 /**
@@ -331,7 +331,7 @@ export const CONTEXT_FRAGMENTS = {
     'project-governance': `# Project Governance
 
 ## Truth Sources
-- CLAUDE.md: Project overview and norms
+- Bolloon.md: Project overview and norms
 - docs/: Architecture and decisions
 - code/: Implementation
 - issues/: Tracking and discussions

package/dist/bollharness-integration/guard-checker.js

@@ -36,7 +36,7 @@ export const GUARD_MAP = {
     'src/constraints/': ['check_api_types', 'check_versions'],
     'src/social/': ['check_api_types', 'check_versions'],
     'docs/': ['check_doc_freshness', 'check_doc_links'],
-    'CLAUDE.md': ['check_doc_freshness', 'check_artifact_link'],
+    'Bolloon.md': ['check_doc_freshness', 'check_artifact_link'],
     'README.md': ['check_doc_freshness'],
     'docs/decisions/': ['check_artifact_link', 'check_versions'],
     '.boll/': ['check_hook_installed'],

package/dist/bootstrap/bootstrap.js

@@ -25,6 +25,7 @@ export async function bootstrapBolloon(opts = {}) {
     };
     try {
         scanResult = await runAdaptiveScan();
+        const { suggestionHint } = await import('../pi-ecosystem-judgment/adaptive-scan.js');
         await logEvolution({
             ts: new Date().toISOString(),
             action: 'accept', // 用 accept 表示"系统记录" (跟 reject 区分)
@@ -35,6 +36,7 @@ export async function bootstrapBolloon(opts = {}) {
                 decision: 'Bolloon 启动扫描',
                 reason: `本次启动扫描了 ${scanResult.judgmentsTotal} 条原则, ${scanResult.usageEntriesScanned} 条使用记录, 生成 ${scanResult.suggestions.length} 条建议`,
                 action: 'review',
+                hint: suggestionHint('unused', 'review', { usage7d: 0, usage30d: 0, daysSinceLastUse: 0, totalUsage: 0 }),
                 metrics: { usage7d: 0, usage30d: 0, daysSinceLastUse: 0, totalUsage: 0 },
                 scannedAt: scanResult.scannedAt,
             },
@@ -50,6 +52,7 @@ export async function bootstrapBolloon(opts = {}) {
         projectRoot: opts.cwd ?? process.cwd(),
         projectName: 'unknown',
         bolloonMd: null,
+        hierarchy: { managed: null, user: null, project: null, local: null, merged: '' },
         git: null,
         persona: null,
         judgmentsSummary: { total: 0, active: 0, superseded: 0, rejected: 0, topValues: [] },

package/dist/bootstrap/context-collector.js

@@ -57,6 +57,20 @@ async function collectProject(cwd, bolloonMdMaxBytes) {
     const bolloonMd = await safeReadFile(path.join(cwd, 'Bolloon.md'), bolloonMdMaxBytes);
     return { projectName, bolloonMd };
 }
+async function collectHierarchy(cwd) {
+    // 动态 import 避免循环依赖
+    const { collectHierarchyLayers, mergeHierarchyLayers } = await import('./context-hierarchy.js');
+    try {
+        const layers = await collectHierarchyLayers({ cwd });
+        const merged = mergeHierarchyLayers(layers, { maxChars: DEFAULT_HIERARCHY_MERGED_MAX });
+        return { ...layers, merged };
+    }
+    catch (err) {
+        console.warn('[context-collector] collectHierarchy failed (silent):', err);
+        return { managed: null, user: null, project: null, local: null, merged: '' };
+    }
+}
+const DEFAULT_HIERARCHY_MERGED_MAX = 2000; // 4000 → 2000 (P-Action 4), 跟 context-hierarchy.ts DEFAULT_MERGE_MAX_CHARS 对齐
 async function collectGit(cwd, limit) {
     const branchOut = await safeExecFile('git', ['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
     if (!branchOut)
@@ -255,13 +269,14 @@ async function walkDir(dir, cb) {
 export async function collectBolloonContext(opts) {
     const { cwd, bolloonMdMaxBytes = 2000, gitCommitLimit = 5, topValuesLimit = 10, } = opts;
     // 并行收集 (除 judgments 因为要动态 import + 依赖其它)
-    const [project, git, persona, skills, env, pending] = await Promise.all([
+    const [project, git, persona, skills, env, pending, hierarchy] = await Promise.all([
         collectProject(cwd, bolloonMdMaxBytes),
         collectGit(cwd, gitCommitLimit),
         collectPersona(),
         collectSkills(),
         Promise.resolve(collectEnv()),
         collectPending(opts),
+        collectHierarchy(cwd),
     ]);
     // judgments 单独调 (内部 import)
     const judgmentsSummary = await collectJudgmentsSummary(topValuesLimit);
@@ -269,6 +284,7 @@ export async function collectBolloonContext(opts) {
         projectRoot: cwd,
         projectName: project.projectName,
         bolloonMd: project.bolloonMd,
+        hierarchy,
         git,
         persona,
         judgmentsSummary,

package/dist/bootstrap/context-hierarchy.js

@@ -0,0 +1,218 @@
+/**
+ * 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';
+export const DEFAULT_PATHS = {
+    managed: '/etc/bolloon/Bolloon.md',
+    user: '', // 用 resolveUserPath 填
+    project: '', // 用 resolveProjectPaths 填
+    projectRulesDir: '',
+    local: '',
+};
+/**
+ * 单层字符上限 (P-Action 4 收紧, 阶段 0 把 4 级层次控制在 ≤ 2KB).
+ * 反向截断策略保证 managed 优先, 单层超限由 truncate() 截断.
+ */
+export const DEFAULT_MAX_CHARS = {
+    managed: 700, // 1500 → 700, 保 bolloon 自身约束
+    user: 500, // 1500 → 500, 跨项目偏好
+    project: 500, // 2500 → 500, 项目规则
+    local: 300, // 1500 → 300, 个人覆盖
+};
+// ============================================================
+// 路径解析
+// ============================================================
+export function resolveUserPath(home) {
+    const h = home ?? process.env.HOME ?? os.homedir() ?? '/tmp';
+    return path.join(h, '.bolloon', 'Bolloon.md');
+}
+export function resolveProjectPaths(cwd) {
+    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) {
+    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, projectRulesDir, maxChars) {
+    // 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 = [];
+            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 层, 任何一层失败 = null (不阻塞其他).
+ */
+export async function collectHierarchyLayers(opts) {
+    const limits = { ...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 };
+}
+/**
+ * 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, opts = {}) {
+    const maxChars = opts.maxChars ?? DEFAULT_MERGE_MAX_CHARS;
+    const parts = [];
+    const labels = [
+        ['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, maxChars) {
+    const order = [
+        ['local', '本地规则 (Local)'],
+        ['project', '项目规则 (Project)'],
+        ['user', '用户规则 (User)'],
+        ['managed', '管理规则 (Managed)'],
+    ];
+    const capped = { ...layers };
+    // 反复压缩, 直到总长 ≤ maxChars
+    let depth = 0; // 0=原始, 1=firstParagraphs=1, 2=砍半
+    while (depth < 3) {
+        const parts = [];
+        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, maxChars) {
+    if (s.length <= maxChars)
+        return s;
+    return s.substring(0, maxChars) + '\n... (truncated)';
+}
+function firstParagraphs(text, count, maxLen) {
+    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() {
+    // no-op (collect 是纯函数, 但保留 API 一致)
+}