@bolloon/bolloon-agent 0.1.35 → 0.1.36

package/src/context-compaction/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Context Compaction — 类型定义
+ *
+ * 严格对齐 Claude Code 论文 5 层压缩流水线:
+ *   1. Budget Reduction   (单条消息大小限制)
+ *   2. Snip               (裁掉老历史, feature flag 关闭)
+ *   3. Microcompact       (cache-aware 细粒度压缩, 老 tool_result 折叠)
+ *   4. Context Collapse   (读时虚拟投影, 非破坏)
+ *   5. Auto-Compact       (LLM 摘要, 兜底)
+ *
+ * 关键不变量:
+ *   - 第 1-3 层不破坏 messageHistory 内存结构, 只改 buildContext 输出
+ *   - 第 4 层读时投影, 绝不改 messageHistory
+ *   - 第 5 层破坏 messageHistory, 把 N 对折叠成 1 条 summary
+ *
+ * 类型设计: Message 在本模块内独立定义, 靠 structural typing 与 pi-sdk.ts 的 Message 兼容.
+ * 不 import pi-sdk 避免循环依赖.
+ */
+
+export type Role = 'user' | 'assistant' | 'tool' | 'system';
+
+export interface Message {
+  role: Role;
+  content: string;
+  toolCall?: { name: string; args: Record<string, unknown> };
+  toolResult?: unknown;
+  toolName?: string;
+  [key: string]: unknown;
+}
+
+// ============================================================
+// 5 层 stage 共享的输入输出
+// ============================================================
+
+export interface StageOptions {
+  /** Token 预算 (默认 8000) */
+  maxTokens?: number;
+  /** 跳过本层 (per-stage 开关) */
+  skip?: boolean;
+  /** Snip 专用: 保留最近多少对 (默认 20) */
+  snipKeepPairs?: number;
+  /** Budget Reduction 专用: 单条消息上限 (默认 4000 字符) */
+  budgetReduceMaxChars?: number;
+  /** Microcompact 专用: 保留最近多少条完整 tool_result (默认 3) */
+  microcompactKeepRecent?: number;
+  /** Context Collapse 专用: 折叠前多少对 (默认 5) */
+  contextCollapseCollapsePairs?: number;
+  /** Auto-Compact 专用: 摘要前多少对 (默认 5) */
+  autoCompactCollapsePairs?: number;
+  /** Auto-Compact 专用: 注入 LLM 调用 (用于生成摘要) */
+  llmChat?: (systemPrompt: string, userPrompt: string, signal?: AbortSignal) => Promise<string>;
+  /** Auto-Compact 专用: 缓存 key 后缀 (通常 = channelId) */
+  cacheScope?: string;
+  /** Context Collapse 专用: 注入 LLM (虚拟投影需要 summary 文本) */
+  collapseLlmChat?: (systemPrompt: string, userPrompt: string) => Promise<string>;
+}
+
+export interface CompactionContext {
+  /** 输入: 原始 history */
+  inputHistory: Message[];
+  /** 当前已压缩的 history (经过前面 stage) */
+  history: Message[];
+  /** 估算的 token 数 */
+  estimatedTokens: number;
+  /** 选项 */
+  opts: StageOptions;
+  /** Pipeline 元数据, 记录每层做了什么 */
+  stages: Array<{ stage: string; applied: boolean; before: number; after: number; detail?: string }>;
+}
+
+export interface StageResult {
+  /** 压缩后的 history */
+  history: Message[];
+  /** 该 stage 是否做了改动 */
+  applied: boolean;
+  /** 详情 (供 audit / debug) */
+  detail?: string;
+}
+
+// ============================================================
+// Budget Gate
+// ============================================================
+
+export interface BudgetReport {
+  fit: boolean;
+  estimatedTokens: number;
+  /** 占用比例 0-1 */
+  ratio: number;
+  /** 触发了哪一层 (>=0.8 = next layer, >1 = all layers) */
+  triggerNextLayer: boolean;
+}
+
+export interface PipelineResult {
+  history: Message[];
+  estimatedTokens: number;
+  stages: CompactionContext['stages'];
+  /** 是否至少跑了一层 */
+  compacted: boolean;
+}

package/src/heartbeat/HealthMonitor.ts

@@ -257,9 +257,10 @@ export class HealthMonitor implements HealthCheckProvider {
   private async pingLLM(minimax: any): Promise<number> {
     const start = Date.now();
     try {
-      // 简单的 chat 测试
+      // 2026-06-15: signal 位置正确传 undefined (chat signature 是 (message, context?, signal?))
+      //   之前传 { maxTokens: 1 } 被当 signal, Node 22+ undici 强类型 AbortSignal 校验 throw
       if (minimax.chat) {
-        await minimax.chat('ping', 'test', { maxTokens: 1 });
+        await minimax.chat('ping', 'test', undefined);
       } else if (minimax.ping) {
         await minimax.ping();
       }

package/src/index.ts

@@ -1132,6 +1132,32 @@ async function runNonInteractive(
     return;
   }
 
+  if (tool === 'prompt' && prompt) {
+    // 2026-06-15: --prompt "text" 走直接调 a.prompt(prompt) 路径, 避开 runToolCommand
+    //   (case 'prompt' 内的 [text] = args 从 toolArgs 取值是空数组, 永远报"缺少 prompt 文本"是 CLI bug)
+    const startTime = Date.now();
+    const a = await getAgent();
+    try {
+      const response = await a.prompt(prompt);
+      const elapsed = Date.now() - startTime;
+      if (json) {
+        console.log(JSON.stringify({ success: true, response, elapsedMs: elapsed }, null, 2));
+      } else {
+        console.log(response);
+        console.log(`\n耗时: ${elapsed}ms`);
+      }
+    } catch (e: any) {
+      const error = e?.message || String(e);
+      if (json) {
+        console.log(JSON.stringify({ success: false, error }, null, 2));
+      } else {
+        console.log(`\n错误: ${error}`);
+      }
+      process.exit(1);
+    }
+    return;
+  }
+
   if (tool) {
     await runToolCommand(tool, toolArgs, !!json, comm);
   } else if (prompt) {
@@ -1565,7 +1591,9 @@ async function main() {
   s.section('系统初始化');
 
   const hasOpenAI = !!process.env.OPENAI_API_KEY;
-  const hasAnthropic = !!process.env.ANTHROPIC_API_KEY;
+  // 2026-06-15: 修复 — 之前 anthropic 401 是因为 shell env 残留的旧 ANTHROPIC_API_KEY 抢了 provider 选择
+  //   用 BOLLOON_LLM_PROVIDER env 显式覆盖, 否则还是按 env hasXxx 顺序自动选
+  const hasAnthropic = !!process.env.ANTHROPIC_API_KEY && !process.env.BOLLOON_LLM_PROVIDER;
   const hasMinimax = !!process.env.MINIMAX_API_KEY;
   const hasDeepSeek = !!process.env.DEEPSEEK_API_KEY;
   const hasKimi = !!(process.env.KIMI_API_KEY || process.env.MOONSHOT_API_KEY);
@@ -1649,10 +1677,16 @@ async function main() {
 
   if (mode === 'web') {
     const port = parseInt(process.env.PORT || '54188');
+    // 2026-06-16: BOLLOON_DEV_MODE=1 或 selfImprove=true 启动项 → 开发者模式, 启用自迭代 (健康监控+自改总线)
+    // 默认用户模式: 不自迭代, 自改卡片不自动出现, 仍可 POST /api/self-improve/trigger 手动触发
+    const selfImprove = process.env.BOLLOON_DEV_MODE === '1' || process.env.BOLLOON_DEV_MODE === 'true';
+    if (selfImprove) {
+      console.log('[startup] BOLLOON_DEV_MODE=1, 开发者模式: 自迭代已启用');
+    }
     const { createWebServer, openBrowser } = await import('./web/server.js');
 
     s.info(`启动 Web 服务端口 ${port}...`);
-    const { port: actualPort } = await createWebServer(port);
+    const { port: actualPort } = await createWebServer(port, { selfImprove });
 
     s.success(`浏览器已打开 → http://localhost:${actualPort}`);
     openBrowser(`http://localhost:${actualPort}`);

package/src/llm/llm-judgment-client.ts

@@ -7,10 +7,32 @@
 
 import { llmConfigStore, type ModelProvider } from './config-store.js';
 import { PiAIModel, type ChatMessage } from './pi-ai.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LAYERS_DIR = path.join(__dirname, 'system-prompt', 'layers');
+
+/**
+ * 从 layer 读 .md 文件作为系统 prompt
+ * 失败时降级到兜底字符串 (不挂)
+ */
+async function loadRoleLayer(layerId: string, fallback: string): Promise<string> {
+  const [group, ...rest] = layerId.split('.');
+  const path2md = path.join(LAYERS_DIR, group, `${rest.join('.')}.md`);
+  try {
+    return await fs.readFile(path2md, 'utf-8');
+  } catch {
+    return fallback;
+  }
+}
 
 export interface JudgmentPromptConfig {
-  // 系统 Prompt
+  // 系统 Prompt (静态字符串, 向后兼容)
   systemPrompt: string;
+  // 系统 Prompt resolver (优先于 systemPrompt; 异步从 layer 读)
+  systemPromptResolver?: () => Promise<string>;
 
   // 用户 Prompt 模板
   userPromptTemplate: string;
@@ -29,16 +51,8 @@ export interface JudgmentPromptConfig {
 export const JUDGMENT_PROMPTS: Record<string, JudgmentPromptConfig> = {
   // 默认判断 Prompt
   default: {
-    systemPrompt: `你是一个专业的 AI 任务分析专家。你的职责是深入理解用户的问题，并给出精准的判断。
-
-核心原则：
-1. 第一性原理：追问问题的本质，而非表面现象
-2. 多角度思考：考虑不同视角和影响因素
-3. 上下文感知：理解对话历史和隐含意图
-4. 动态评估：根据实际情况判断复杂性
-
-你的判断会影响后续的智能体协作方式，请认真分析。`,
-
+    systemPrompt: '',
+    systemPromptResolver: () => loadRoleLayer('role.expert', '你是一个专业的 AI 任务分析专家. '),
     userPromptTemplate: `【当前输入】
 {user_input}
 
@@ -95,17 +109,8 @@ export const JUDGMENT_PROMPTS: Record<string, JudgmentPromptConfig> = {
 
   // 架构相关问题
   architecture: {
-    systemPrompt: `你是一个经验丰富的系统架构师。你擅长：
-- 从需求中提取本质问题
-- 设计可扩展的系统架构
-- 权衡技术方案
-- 识别架构风险
-
-你相信：
-- 本质和实现必须分离
-- 好的架构从简单规则中生长
-- 复杂性应该被控制而非消除`,
-
+    systemPrompt: '',
+    systemPromptResolver: () => loadRoleLayer('role.architect', '你是一个经验丰富的系统架构师. '),
     userPromptTemplate: `【架构设计问题】
 {user_input}
 
@@ -133,12 +138,8 @@ export const JUDGMENT_PROMPTS: Record<string, JudgmentPromptConfig> = {
 
   // 代码相关问题
   code: {
-    systemPrompt: `你是一个高效的代码实现专家。你擅长：
-- 快速理解和实现需求
-- 编写清晰、可维护的代码
-- 遵循最佳实践
-- 处理边界情况`,
-
+    systemPrompt: '',
+    systemPromptResolver: () => loadRoleLayer('role.implementer', '你是一个高效的代码实现专家. '),
     userPromptTemplate: `【代码问题】
 {user_input}
 
@@ -162,12 +163,8 @@ export const JUDGMENT_PROMPTS: Record<string, JudgmentPromptConfig> = {
 
   // 安全相关问题
   security: {
-    systemPrompt: `你是一个严格的安全专家。你擅长：
-- 识别安全风险
-- 评估威胁模型
-- 设计安全方案
-- 遵循安全最佳实践`,
-
+    systemPrompt: '',
+    systemPromptResolver: () => loadRoleLayer('role.security', '你是一个严格的安全专家. '),
     userPromptTemplate: `【安全问题】
 {user_input}
 
@@ -300,8 +297,12 @@ export class LLMJudgmentClient {
 
     try {
       // 调用 LLM
+      // 优先用 systemPromptResolver (从 layer 读), fallback 静态 systemPrompt
+      const systemPrompt = this.promptConfig.systemPromptResolver
+        ? await this.promptConfig.systemPromptResolver()
+        : this.promptConfig.systemPrompt;
       const messages: ChatMessage[] = [
-        { role: 'system', content: this.promptConfig.systemPrompt },
+        { role: 'system', content: systemPrompt },
         { role: 'user', content: userPrompt }
       ];
 

package/src/llm/pi-ai.ts

@@ -29,6 +29,28 @@ export interface GenerateOptions {
   temperature?: number;
   maxTokens?: number;
   signal?: AbortSignal;
+  /** 工具 id 列表 — 代码侧 (src/llm/tool-manifest/) 查 schema, prompt 里只嵌 oneLine + callExample */
+  tools?: string[];
+}
+
+/**
+ * 外部 system 注入钩子.
+ * 调用方 (e.g. auto-evolve-loop) 用 setSystemPrependProvider() 注册一个返回字符串的函数,
+ * generateText 在拼 finalMessages 时, 把返回的字符串作为最前一个 system message.
+ *
+ * 用途: P2P 协作时把"行级 reserve 状态"实时塞给 LLM,
+ *       让 LLM 主动避开对方正在改的代码行.
+ *
+ * 返回 '' / null / undefined → 不注入.
+ */
+let _prependProvider: (() => string | null | undefined | Promise<string | null | undefined>) | null = null;
+export function setSystemPrependProvider(
+  p: (() => string | null | undefined | Promise<string | null | undefined>) | null
+): void {
+  _prependProvider = p;
+}
+export function getSystemPrependProvider(): typeof _prependProvider {
+  return _prependProvider;
 }
 
 export class PiAIModel {
@@ -41,7 +63,7 @@ export class PiAIModel {
   }
 
   async chat(message: string, context?: string, signal?: AbortSignal): Promise<ChatResult> {
-    const systemPrompt = this.buildSystemPrompt(context);
+    const systemPrompt = await this.buildSystemPromptAsync(context);
     const messages: ChatMessage[] = [
       { role: 'system', content: systemPrompt },
       { role: 'user', content: message }
@@ -51,6 +73,7 @@ export class PiAIModel {
       const response = await this.generateText({
         messages,
         temperature: 0.8,
+        maxTokens: 8192,  // 2026-06-15: 提到 8192, 避免长回答 (含表格/代码块) 被截断
         signal,
       });
       return { reply: response };
@@ -60,7 +83,14 @@ export class PiAIModel {
         throw error; // 上层 try/catch 处理
       }
       console.error('PiAI chat error:', error);
-      return { reply: '抱歉，AI服务暂时不可用。' };
+      // 2026-06-15: 真实 error 信息 + 明确告诉 LLM "这是 API 错, 不要 retry"
+      // 旧版: "抱歉，AI服务暂时不可用。" → LLM 看到 isTooShort=false(< 50 但 > 0),
+      //       needsMoreWork 不会触发, 但 hasError 模式 (含 "error" / "失败") 会判定要继续修
+      // 新版: 让 LLM 立即停止循环, 直接展示给用户
+      const errMsg = (error?.message || '').slice(0, 300);
+      return {
+        reply: `[AI 服务调用失败] ${errMsg}\n\n这是一个**底层 API 错误**（401 / 鉴权失败 / 网络中断 / 配额耗尽等），不是你的任务有问题。**请直接把这个错误消息回复给用户，不要再循环尝试。**`,
+      };
     }
   }
 
@@ -106,7 +136,40 @@ export class PiAIModel {
   }
 
   private async generateText(options: GenerateOptions): Promise<string> {
-    const { messages, temperature = 0.7, maxTokens = 4096, signal } = options;
+    const { messages, temperature = 0.7, maxTokens = 4096, signal, tools } = options;
+
+    // 工具清单: 代码侧 schema → 进 system prompt (作为额外 system message)
+    let finalMessages = messages;
+
+    // 1) 外部 prepend (e.g. P2P 行级 reserve 状态), 拼到最前
+    if (_prependProvider) {
+      try {
+        const pre = await _prependProvider();
+        if (pre && typeof pre === 'string' && pre.trim()) {
+          finalMessages = [{ role: 'system', content: pre }, ...finalMessages];
+        }
+      } catch (err: any) {
+        console.warn('[pi-ai] systemPrepend 失败:', err?.message?.slice(0, 100));
+      }
+    }
+
+    if (tools && tools.length > 0) {
+      try {
+        const { getToolManifest, formatForPrompt } = await import('./tool-manifest/index.js');
+        const manifests = tools
+          .map((id) => getToolManifest(id))
+          .filter((m): m is NonNullable<typeof m> => m !== undefined);
+        if (manifests.length > 0) {
+          const toolPrompt = formatForPrompt(manifests);
+          finalMessages = [
+            { role: 'system', content: toolPrompt },
+            ...messages,
+          ];
+        }
+      } catch (err: any) {
+        console.warn('[pi-ai] tool-manifest 加载失败:', err.message?.slice(0, 100));
+      }
+    }
 
     switch (this.provider) {
       case 'openai':
@@ -115,17 +178,17 @@ export class PiAIModel {
       case 'kimi':
       case 'glm':
       case 'qwen':
-        return this.callOpenAI(messages, temperature, maxTokens, signal);
+        return this.callOpenAI(finalMessages, temperature, maxTokens, signal);
       case 'anthropic':
-        return this.callAnthropic(messages, temperature, maxTokens, signal);
+        return this.callAnthropic(finalMessages, temperature, maxTokens, signal);
       case 'ollama':
-        return this.callOllama(messages, temperature, signal);
+        return this.callOllama(finalMessages, temperature, signal);
       case 'openrouter':
-        return this.callOpenRouter(messages, temperature, maxTokens, signal);
+        return this.callOpenRouter(finalMessages, temperature, maxTokens, signal);
       case 'gemini':
-        return this.callGemini(messages, temperature, maxTokens, signal);
+        return this.callGemini(finalMessages, temperature, maxTokens, signal);
       case 'local':
-        return this.callLocal(messages, temperature, signal);
+        return this.callLocal(finalMessages, temperature, signal);
       default:
         throw new Error(`Unsupported provider: ${this.provider}`);
     }
@@ -198,19 +261,23 @@ export class PiAIModel {
       throw new Error('OPENAI_API_KEY not set');
     }
 
+    const requestBody = {
+      model: this.mapModel(),
+      messages,
+      temperature,
+      max_tokens: maxTokens
+    };
     const response = await fetch(`${this.getBaseUrl()}/chat/completions`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
         'Authorization': `Bearer ${apiKey}`
       },
-      body: JSON.stringify({
-        model: this.mapModel(),
-        messages,
-        temperature,
-        max_tokens: maxTokens
-      }),
-      signal,
+      body: JSON.stringify(requestBody),
+      // 2026-06-15: signal 字段防御 — Node 22+ undici 强类型 AbortSignal, 非 AbortSignal 实例
+      //   (e.g. 误传的 { maxTokens: 1 } 对象) 会 throw "Expected signal to be AbortSignal".
+      //   若不是 AbortSignal, 退到无 signal 调用, fetch 自然支持 timeout 由外层控制.
+      signal: signal instanceof AbortSignal ? signal : undefined,
     });
 
     if (!response.ok) {
@@ -355,7 +422,35 @@ export class PiAIModel {
   private async callLocal(messages: ChatMessage[], temperature: number, signal?: AbortSignal): Promise<string> {
     return this.callOllama(messages, temperature, signal);
   }
+  // 注: callLocal 直接代理 ollama. 工具清单由 generateText 在外层拼到 messages, 这里 messages 已是 finalMessages.
+
+  private async buildSystemPromptAsync(context?: string): Promise<string> {
+    // 走 layer registry: 装配所有相关 layer (身份/行为/工具/角色/渠道)
+    try {
+      const { assembleSystemPrompt, SYSTEM_PROMPT_VERSION } = await import(
+        './system-prompt/registry.js' as any
+      ).catch(() => import('./system-prompt/registry.js'));
+      // channel = 本机 (PI SDK 直接调就是 local)
+      // role = 由 prompt context 决定 (默认 expert)
+      const ctx = context ? { channel: 'local' as const, role: 'expert' as const } : { channel: 'local' as const, role: 'expert' as const };
+      const result = await assembleSystemPrompt(ctx);
+      return `${result.text}\n\n## User Working Directory\n${context || process.cwd()}\n\n## bolloon-runtime\n${SYSTEM_PROMPT_VERSION} · layers: ${result.layerIds.join(',')}`;
+    } catch (err: any) {
+      // 降级: 旧硬编码 (layer registry 不可用时不挂)
+      console.warn('[pi-ai] layer registry 不可用, 降级:', err.message?.slice(0, 100));
+      const envDetails = this.getEnvironmentDetails();
+      return `You are a friendly AI assistant in a P2P document collaboration network.
+
+## User Working Directory
+${context || process.cwd()}
+
+## Environment
+${envDetails}`;
+    }
+  }
 
+  // 同步版: 旧调用点 (buildSystemPrompt 是同步)
+  // 保留但内部用 sync fallback; 后续可改成 async
   private buildSystemPrompt(context?: string): string {
     const envDetails = this.getEnvironmentDetails();
     return `You are a friendly AI assistant in a P2P document collaboration network.

package/src/llm/system-prompt/health.ts

@@ -0,0 +1,159 @@
+/**
+ * system-prompt health — 每层 lifecycle 状态扫描
+ *
+ * 严格对齐 deusyu 论文 "Harness Gardening 3-6 月" + walkinglabs Lifecycle 4-stage
+ * + 马书 ch05+ch13 systemPromptSection + 89 FF 的版本/owner 治理思想.
+ *
+ * 设计:
+ *   - 输入: 完整 layer list (assembleSystemPrompt 返回的 layers[])
+ *   - 输出: 每层 health 状态 (ok | stale | overdue-review | missing-frontmatter)
+ *   - 失败静默: 任何 layer 读失败 → 标 'missing-frontmatter' 而非抛错
+ *
+ * 决策 (cross-repo_caveats 选边):
+ *   - dynamic layers (function source) → 标 'ok' (last_reviewed_at = now), 视作 runtime-managed
+ *   - frontmatter author 拒绝 'llm-judge' 之外的不合法值 → 标 'missing-frontmatter'
+ */
+
+import type { PromptLayer, SectionMeta, AppliesTo } from './registry.js';
+
+export type LayerHealth = 'ok' | 'stale' | 'overdue-review' | 'missing-frontmatter' | 'dynamic';
+
+export interface LayerHealthEntry {
+  id: string;
+  health: LayerHealth;
+  ageDays: number;
+  ttlDays: number;
+  /** 距离过期还有多少天 (负数 = 已过期) */
+  remainingDays: number;
+  author: string | null;
+  lastReviewedAt: string | null;
+  notes?: string;
+  /** 该层是否在当前 context 下被装配 (assembleSystemPrompt 调用过) */
+  active: boolean;
+}
+
+export interface HealthReport {
+  scannedAt: string;
+  total: number;
+  okCount: number;
+  staleCount: number;
+  overdueCount: number;
+  missingCount: number;
+  dynamicCount: number;
+  entries: LayerHealthEntry[];
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** 兼容运行时: dynamic layer 没有 meta, 视作 'dynamic' (last_reviewed = now) */
+function isDynamic(l: PromptLayer): boolean {
+  return l.source === 'function';
+}
+
+/** 评估单层 health */
+export function evaluateLayer(l: PromptLayer, now: Date = new Date()): LayerHealthEntry {
+  if (isDynamic(l)) {
+    return {
+      id: l.id,
+      health: 'dynamic',
+      ageDays: 0,
+      ttlDays: -1,
+      remainingDays: -1,
+      author: l.meta?.author ?? 'runtime',
+      lastReviewedAt: now.toISOString(),
+      active: false,  // 由 caller (assembleSystemPrompt) 决定
+    };
+  }
+  if (!l.meta) {
+    // frontmatter 解析失败或缺失
+    return {
+      id: l.id,
+      health: 'missing-frontmatter',
+      ageDays: -1,
+      ttlDays: -1,
+      remainingDays: -1,
+      author: null,
+      lastReviewedAt: null,
+      active: false,
+    };
+  }
+  const reviewedAt = new Date(l.meta.lastReviewedAt).getTime();
+  if (isNaN(reviewedAt)) {
+    return {
+      id: l.id,
+      health: 'missing-frontmatter',
+      ageDays: -1,
+      ttlDays: l.meta.ttlDays,
+      remainingDays: -1,
+      author: l.meta.author,
+      lastReviewedAt: l.meta.lastReviewedAt,
+      active: false,
+    };
+  }
+  const ageMs = now.getTime() - reviewedAt;
+  const ageDays = Math.floor(ageMs / DAY_MS);
+  const remainingDays = l.meta.ttlDays - ageDays;
+  let health: LayerHealth;
+  if (remainingDays < 0) {
+    health = 'overdue-review';
+  } else if (remainingDays < l.meta.ttlDays * 0.2) {
+    health = 'stale';  // 剩余 < 20% ttl 触发告警
+  } else {
+    health = 'ok';
+  }
+  return {
+    id: l.id,
+    health,
+    ageDays,
+    ttlDays: l.meta.ttlDays,
+    remainingDays,
+    author: l.meta.author,
+    lastReviewedAt: l.meta.lastReviewedAt,
+    notes: l.meta.notes,
+    active: false,  // caller 决定
+  };
+}
+
+/** 评估整组 layer (输入: assembleSystemPrompt 返回的 layers[]) */
+export function evaluateLayers(layers: PromptLayer[], now: Date = new Date()): HealthReport {
+  const entries = layers.map((l) => evaluateLayer(l, now));
+  return summarize(entries, now);
+}
+
+/** 汇总: 给一批 entries 算 counts */
+function summarize(entries: LayerHealthEntry[], now: Date): HealthReport {
+  const counts = { ok: 0, stale: 0, overdue: 0, missing: 0, dynamic: 0 };
+  for (const e of entries) {
+    if (e.health === 'ok') counts.ok++;
+    else if (e.health === 'stale') counts.stale++;
+    else if (e.health === 'overdue-review') counts.overdue++;
+    else if (e.health === 'missing-frontmatter') counts.missing++;
+    else if (e.health === 'dynamic') counts.dynamic++;
+  }
+  return {
+    scannedAt: now.toISOString(),
+    total: entries.length,
+    okCount: counts.ok,
+    staleCount: counts.stale,
+    overdueCount: counts.overdue,
+    missingCount: counts.missing,
+    dynamicCount: counts.dynamic,
+    entries,
+  };
+}
+
+/** 标记当前 context 下激活的 layer (在 assembleSystemPrompt 调用后用) */
+export function markActive(report: HealthReport, activeIds: Set<string>): HealthReport {
+  return {
+    ...report,
+    entries: report.entries.map((e) => ({ ...e, active: activeIds.has(e.id) })),
+  };
+}
+
+// ============================================================
+// 测试钩子
+// ============================================================
+
+export function _resetHealthForTest(): void {
+  // 无内部状态, 保留 API 一致
+}

package/src/llm/system-prompt/layers/channel/local.md

@@ -0,0 +1,14 @@
+---
+added_at: 2026-06-15
+last_reviewed_at: 2026-06-15
+ttl_days: 180
+author: yuanjie
+---
+
+<!-- channel.local@1.0.0 -->
+# 本地渠道 (默认, bolloon 跑在用户本机)
+
+你跑在用户的本地设备上, 可直接读写用户文件系统. 信任度高.
+
+允许: 读写文件、执行命令、调用所有工具.
+边界: 仍遵守 core.refusal / core.wellbeing / 拒绝处理.

package/src/llm/system-prompt/layers/channel/p2p-agent.md

@@ -0,0 +1,18 @@
+---
+added_at: 2026-06-15
+last_reviewed_at: 2026-06-15
+ttl_days: 180
+author: yuanjie
+---
+
+<!-- channel.p2p-agent@1.0.0 -->
+# P2P 远程智能体 (另一个 bolloon 经 P2P 路由)
+
+你是远端 bolloon, 收到的是**另一个 bolloon 实例**的协作请求. 信任度高 (基于 P2P 节点身份验证, 不是基于人类).
+
+允许: 读 / 写, 协作推理, 共享上下文.
+
+边界:
+- 身份验证优先: 先确认对方节点 ID + 公钥签名
+- 共享上下文时避免把人类隐私数据 (judgment / persona) 外泄给未知节点
+- 协作冲突时回退到 snapshot 重新协商, 不强推修改