@bolloon/bolloon-agent 0.3.7 → 0.3.8

package/README.md

@@ -129,6 +129,37 @@ bolloon --help       # 所有命令
 
 详细打包 / 桌面 / iOS 流程见 [docs/BUILD.md](docs/BUILD.md).
 
+### 从 npm / GitHub 安装（终端用户）
+
+Bolloon 已发布到 npm，也可通过 GitHub 一键脚本安装（无需克隆仓库）。
+
+**方式一：npm（各系统通用，需先装 Node.js LTS）**
+
+```bash
+npm install -g @bolloon/bolloon-agent
+bolloon --version
+```
+
+**方式二：GitHub 一键脚本（macOS / Linux）**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/logos-42/bolloon/master/scripts/install.sh | sh
+```
+
+脚本优先从 GitHub Releases 下载预编译包，未提供对应平台包时自动回退 `npm install -g`。
+
+**各系统安装 Node.js（若尚未安装）**
+
+| 系统 | 命令 |
+|------|------|
+| macOS（Homebrew） | `brew install node` |
+| Linux（apt） | `sudo apt update && sudo apt install -y nodejs npm` |
+| Linux（dnf / yum） | `sudo dnf install -y nodejs npm` |
+| Windows（winget） | `winget install -e --id OpenJS.NodeJS.LTS` |
+| Windows（Chocolatey） | `choco install nodejs` |
+
+> 说明：bolloon 暂未上架 apt / yum / brew / winget / choco 原生仓库，统一经 npm 安装；上表命令仅用于安装 Node.js 运行时。
+
 ---
 
 ## 一、项目概述

package/dist/social/agent-heartbeat.js

@@ -0,0 +1,457 @@
+/**
+ * agent-heartbeat.ts — 智能体社交心跳 + 生命周期 (2026-07-21, 重构于 2026-07-21)
+ *
+ * 目的: 让本地智能体拥有"心跳", 周期性宣告存活/能力, 并自主决定跟哪个远端智能体发起对话,
+ *       形成本地↔远端智能体的顺畅自动交流.
+ *
+ * ⚠️ 设计核心: 智能体生命周期 (避免"一直社交却毫无效果")
+ *   社交不是目的, 而是达成"目标"的手段. 因此本模块以一个 **目标驱动的状态机** 管理智能体:
+ *
+ *     BOOTSTRAP ──start()──▶ DISCOVERING ──有存活 peer──▶ ENGAGING
+ *        ▲                        │                            │
+ *        │                        │ 无目标/无存活 peer         │ 目标达成 / 配额耗尽 / 无效果退避
+ *        │                        ▼                            ▼
+ *        └───────────────────── RESTING ◀─────────────────────┘
+ *                                     │ (goalReevalMs 后重新评估, 重置配额再试一轮)
+ *                                     ▼
+ *                                  ENGAGING (新一轮)
+ *
+ *   - 每个目标有配额 (maxInitiations) 与效果阈值 (effectThreshold): 达成即 RESTING, 不再闲聊.
+ *   - 若连续多次发起却"毫无效果" (noEffectWindowMs 内无有效回复), 进入退避 RESTING (noEffectBackoffMs),
+ *     防止无限互 ping / 烧 LLM.
+ *   - RESTING 不是消失: beacon 仍在发, 对端依旧能看到本智能体在线; 只是停止主动社交.
+ *   - goalReevalMs 之后会重新评估目标 (重置配额) 再给一轮机会, 让智能体"活着"但不失控.
+ *   - pause()/resume()/stop() 提供运行期控制; stop() 会清理全部定时器 (供全局 runtime 优雅关闭).
+ *
+ * 设计原则 (compile-first / 可测):
+ *   - transport / decide / getPeers / self / getGoal / assessEffect 全部可注入, 不依赖真实网络或 LLM.
+ *   - 生产环境: transport = p2p-outbox.sendOrQueue, decide = 本地 LLM 决策, getPeers = known_peers + remoteChannelCache.
+ *   - 测试环境: 全部用 mock, 验证"beacon → 自主发起 → 远端回复(效果) → 目标达成 → RESTING".
+ *
+ * 协议 (复用 v3 P2P 的 {v:3, op, payload} 信封):
+ *   - agent.heartbeat : 轻量 beacon, payload = {fromPublicKey, agentId, name, channels, ts}
+ *   - agent.chat.send  : 本地 agent 自主发起 (已有远端唤醒链路, server.ts:529 处理)
+ *   - agent.chat.reply : 远端回复发回 (已有 SSE 链路, server.ts:1494 处理)
+ *
+ * 与全局 runtime 生命周期的集成:
+ *   - stop() 清理定时器, 供 server.ts 的 cleanupAndExit (SIGTERM/SIGINT) 调用.
+ *   - onActivity 回调喂给 Watchdog.recordActivity, 避免 24h 看门狗误判卡死.
+ *   - 实例注册到 global.socialHeartbeat / global.agentHeartbeat, 供 HealthMonitor.checkHeartbeat 观测.
+ *   - 暴露 getDiscoveredAgents() / isAntColonyEnabled() 兼容 HealthMonitor 契约.
+ */
+const DEFAULTS = {
+    beaconIntervalMs: 30_000,
+    socialIntervalMs: 120_000,
+    cooldownMs: 10 * 60_000,
+    liveWindowMs: 3 * 30_000,
+    minAttemptsBeforeBackoff: 3,
+    noEffectWindowMs: 10 * 60_000,
+    noEffectBackoffMs: 30 * 60_000,
+    backoffFactor: 2,
+    maxSocialIntervalMs: 30 * 60_000,
+    goalReevalMs: 60 * 60_000,
+};
+const MAX_BACKOFF_LEVEL = 6;
+export class AgentHeartbeat {
+    opts;
+    peerLiveness = new Map();
+    lastInitiated = new Map();
+    beaconTimer = null;
+    socialTimer = null;
+    started = false;
+    // === 生命周期状态 ===
+    phase = 'BOOTSTRAP';
+    goalRT = null;
+    /** 内置兜底目标 (无 getGoal 时使用, 带配额, 保证不会一直社交) */
+    builtinGoalRT = null;
+    backoffLevel = 0;
+    noEffectBackoffUntil = 0;
+    constructor(options) {
+        this.opts = {
+            self: options.self,
+            getPeers: options.getPeers,
+            transport: options.transport,
+            decide: options.decide,
+            getGoal: options.getGoal,
+            assessEffect: options.assessEffect,
+            onReply: options.onReply,
+            onPeerAlive: options.onPeerAlive,
+            onActivity: options.onActivity,
+            onLifecycleChange: options.onLifecycleChange,
+            beaconIntervalMs: options.beaconIntervalMs ?? DEFAULTS.beaconIntervalMs,
+            socialIntervalMs: options.socialIntervalMs ?? DEFAULTS.socialIntervalMs,
+            cooldownMs: options.cooldownMs ?? DEFAULTS.cooldownMs,
+            liveWindowMs: options.liveWindowMs ?? DEFAULTS.liveWindowMs,
+            minAttemptsBeforeBackoff: options.minAttemptsBeforeBackoff ?? DEFAULTS.minAttemptsBeforeBackoff,
+            noEffectWindowMs: options.noEffectWindowMs ?? DEFAULTS.noEffectWindowMs,
+            noEffectBackoffMs: options.noEffectBackoffMs ?? DEFAULTS.noEffectBackoffMs,
+            backoffFactor: options.backoffFactor ?? DEFAULTS.backoffFactor,
+            maxSocialIntervalMs: options.maxSocialIntervalMs ?? DEFAULTS.maxSocialIntervalMs,
+            goalReevalMs: options.goalReevalMs ?? DEFAULTS.goalReevalMs,
+            enabled: options.enabled ?? true,
+            socialEnabled: options.socialEnabled ?? (options.enabled ?? true),
+        };
+    }
+    isEnabled() {
+        return this.opts.enabled;
+    }
+    isSocialEnabled() {
+        return this.opts.enabled && this.opts.socialEnabled;
+    }
+    // ===================== 启动 / 停止 / 暂停 =====================
+    start() {
+        if (this.started || !this.opts.enabled)
+            return;
+        this.started = true;
+        this.setPhase('DISCOVERING');
+        this.beaconTimer = setInterval(() => {
+            this.tickBeacon().catch((e) => console.warn('[heartbeat] beacon tick 失败:', e?.message));
+        }, this.opts.beaconIntervalMs);
+        if (this.isSocialEnabled()) {
+            this.scheduleSocial();
+        }
+        // 立即发一次 beacon, 让对端尽快看到自己
+        this.tickBeacon().catch(() => { });
+        console.log(`[heartbeat] 社交心跳已启动 (beacon=${this.opts.beaconIntervalMs}ms` +
+            `${this.isSocialEnabled() ? `, social=${this.opts.socialIntervalMs}ms, cooldown=${this.opts.cooldownMs}ms` : ', social=关闭'} )`);
+    }
+    /** 优雅停止: 清理全部定时器 (供全局 runtime 的 SIGTERM/SIGINT 清理调用) */
+    stop() {
+        if (this.beaconTimer)
+            clearInterval(this.beaconTimer);
+        if (this.socialTimer)
+            clearTimeout(this.socialTimer);
+        this.beaconTimer = null;
+        this.socialTimer = null;
+        this.started = false;
+        this.setPhase('PAUSED');
+        console.log('[heartbeat] 社交心跳已停止 (定时器已清理)');
+    }
+    /** 暂停社交循环 (beacon 仍发, 智能体依旧在线可见, 只是停止主动聊天) */
+    pause() {
+        if (!this.started)
+            return;
+        if (this.socialTimer)
+            clearTimeout(this.socialTimer);
+        this.socialTimer = null;
+        this.setPhase('PAUSED');
+        console.log('[heartbeat] 社交循环已暂停 (仅保留 beacon)');
+    }
+    /** 从 PAUSED 恢复社交循环 */
+    resume() {
+        if (!this.started) {
+            this.start();
+            return;
+        }
+        if (this.phase !== 'PAUSED')
+            return;
+        this.setPhase('DISCOVERING');
+        if (this.isSocialEnabled())
+            this.scheduleSocial();
+        console.log('[heartbeat] 社交循环已恢复');
+    }
+    // ===================== beacon =====================
+    /** 周期性 beacon: 向每个已知 peer 宣告存活 + 自身渠道/能力 */
+    async tickBeacon() {
+        const self = await this.opts.self();
+        const peers = await this.opts.getPeers();
+        const payload = {
+            fromPublicKey: self.publicKey,
+            agentId: self.agentId,
+            name: self.name,
+            channels: self.channels,
+            ts: Date.now(),
+        };
+        for (const p of peers) {
+            if (p.publicKey === self.publicKey)
+                continue;
+            const r = await this.opts.transport
+                .send(p.publicKey, 'agent.heartbeat', payload)
+                .catch(() => 'FAILED');
+            if (r !== 'FAILED')
+                this.peerLiveness.set(p.publicKey, Date.now());
+        }
+    }
+    // ===================== 社交决策 tick (生命周期感知) =====================
+    /** 自适应 social 间隔 (退避时指数增长, 有上限) */
+    currentSocialInterval() {
+        const mult = Math.pow(this.opts.backoffFactor, this.backoffLevel);
+        return Math.min(this.opts.socialIntervalMs * mult, this.opts.maxSocialIntervalMs);
+    }
+    scheduleSocial() {
+        if (!this.started || !this.isSocialEnabled() || this.phase === 'PAUSED') {
+            this.socialTimer = null;
+            return;
+        }
+        this.socialTimer = setTimeout(() => {
+            this.tickSocial()
+                .catch((e) => console.warn('[heartbeat] social tick 失败:', e?.message))
+                .finally(() => {
+                if (this.started && this.phase !== 'PAUSED')
+                    this.scheduleSocial();
+            });
+        }, this.currentSocialInterval());
+    }
+    /** 社交决策 tick: 先评估生命周期, 再决定是否对存活 peer 发起对话 */
+    async tickSocial() {
+        this.opts.onActivity?.();
+        const self = await this.opts.self();
+        const allPeers = (await this.opts.getPeers()).filter((p) => p.publicKey !== self.publicKey);
+        const now = Date.now();
+        const livePeers = allPeers.filter((p) => {
+            const seen = this.peerLiveness.get(p.publicKey) ?? p.lastSeen ?? 0;
+            return now - seen <= this.opts.liveWindowMs;
+        });
+        const goalRT = await this.resolveGoal();
+        // —— 生命周期评估: 决定本 tick 进入哪个阶段 ——
+        const evalResult = this.evaluateLifecycle(goalRT, livePeers.length, now);
+        if (evalResult.backoff) {
+            this.backoffLevel = Math.min(this.backoffLevel + 1, MAX_BACKOFF_LEVEL);
+            this.noEffectBackoffUntil = now + this.opts.noEffectBackoffMs;
+        }
+        if (evalResult.resetBackoff) {
+            this.backoffLevel = 0;
+            this.noEffectBackoffUntil = 0;
+        }
+        this.setPhase(evalResult.nextPhase);
+        if (this.phase === 'RESTING' || this.phase === 'PAUSED') {
+            console.log(`[heartbeat] 生命周期=${this.phase}, 跳过本次社交` +
+                `${this.noEffectBackoffUntil > now ? ` (无效果退避至 ${new Date(this.noEffectBackoffUntil).toLocaleTimeString()})` : ''}` +
+                ` (goal=${goalRT?.goal.description ?? '无'})`);
+            this.emitLifecycle();
+            return;
+        }
+        if (!this.opts.decide) {
+            this.setPhase('DISCOVERING');
+            this.emitLifecycle();
+            return;
+        }
+        if (livePeers.length === 0) {
+            this.setPhase('DISCOVERING');
+            console.log('[heartbeat] social tick: 没有存活 peer, 仅保持发现');
+            this.emitLifecycle();
+            return;
+        }
+        this.setPhase('ENGAGING');
+        const decision = await this.opts.decide({ self, peers: livePeers, goal: goalRT?.goal }).catch(() => ({ initiate: false }));
+        // 决策时即可声明目标达成
+        if (decision?.goalAchieved && goalRT) {
+            goalRT.achieved = true;
+            this.setPhase('RESTING');
+            console.log(`[heartbeat] 决策判定目标已达成 → RESTING: ${goalRT.goal.description}`);
+            this.emitLifecycle();
+            return;
+        }
+        if (!decision?.initiate) {
+            this.emitLifecycle();
+            return;
+        }
+        const { targetPeerPublicKey, targetChannelId, message } = decision;
+        if (!targetPeerPublicKey || !targetChannelId || !message) {
+            this.emitLifecycle();
+            return;
+        }
+        // 冷却: 避免对同一 peer 刷屏 / 无限互 ping
+        const last = this.lastInitiated.get(targetPeerPublicKey) ?? 0;
+        if (now - last < this.opts.cooldownMs) {
+            this.emitLifecycle();
+            return;
+        }
+        // 目标配额: 本目标已发起够多次则进入 RESTING
+        if (goalRT && goalRT.initiationsUsed >= goalRT.goal.maxInitiations) {
+            this.setPhase('RESTING');
+            console.log(`[heartbeat] 目标配额用尽 (${goalRT.initiationsUsed}/${goalRT.goal.maxInitiations}) → RESTING`);
+            this.emitLifecycle();
+            return;
+        }
+        const r = await this.opts.transport
+            .send(targetPeerPublicKey, 'agent.chat.send', {
+            channelId: targetChannelId,
+            text: message,
+            fromPublicKey: self.publicKey,
+        })
+            .catch(() => 'FAILED');
+        if (r !== 'FAILED') {
+            this.lastInitiated.set(targetPeerPublicKey, now);
+            if (goalRT) {
+                goalRT.initiationsUsed++;
+                goalRT.lastInitiateAt = now;
+            }
+            console.log(`[heartbeat] 主动发起对话 → ${targetPeerPublicKey.slice(0, 8)}… (channel=${targetChannelId}): "${message.slice(0, 40)}..."` +
+                `${goalRT ? ` [目标 ${goalRT.initiationsUsed}/${goalRT.goal.maxInitiations}]` : ''}`);
+        }
+        else {
+            console.warn(`[heartbeat] 主动发起失败 (peer ${targetPeerPublicKey.slice(0, 8)}… 不在线?)`);
+        }
+        this.emitLifecycle();
+    }
+    // ===================== 生命周期评估 =====================
+    makeGoalRuntime(g) {
+        return {
+            goal: { ...g, createdAt: g.createdAt ?? Date.now() },
+            initiationsUsed: 0,
+            effectfulReplies: 0,
+            achieved: false,
+            startedAt: Date.now(),
+        };
+    }
+    /** 解析当前目标: 复用未达成/未过期的目标; 否则尝试 getGoal(); 再否则用内置 discovery 目标 (带配额) */
+    async resolveGoal() {
+        if (this.goalRT && !this.goalRT.achieved) {
+            const ttl = this.goalRT.goal.ttlMs ?? Infinity;
+            if (Date.now() - this.goalRT.startedAt < ttl)
+                return this.goalRT;
+        }
+        const g = await this.opts.getGoal?.();
+        if (g) {
+            this.goalRT = this.makeGoalRuntime(g);
+            return this.goalRT;
+        }
+        // 兜底: 内置 discovery 目标, 保证不会"一直社交" (有配额)
+        if (!this.builtinGoalRT || this.builtinGoalRT.achieved) {
+            this.builtinGoalRT = this.makeGoalRuntime({
+                id: 'builtin-discovery',
+                description: '与已知 peer 建立并维持协作关系',
+                maxInitiations: 5,
+                effectThreshold: 2,
+            });
+        }
+        this.goalRT = this.builtinGoalRT;
+        return this.goalRT;
+    }
+    /**
+     * 生命周期转移决策.
+     * 返回下一个阶段 + 是否触发退避 + 是否重置退避.
+     */
+    evaluateLifecycle(goalRT, liveCount, now) {
+        // 无目标 → 用内置 discovery 兜底; 这里 goalRT 总有值
+        if (!goalRT)
+            return { nextPhase: 'RESTING', backoff: false, resetBackoff: false };
+        // 目标已达成 → 休息
+        if (goalRT.achieved)
+            return { nextPhase: 'RESTING', backoff: false, resetBackoff: true };
+        // 配额耗尽 → 休息
+        if (goalRT.initiationsUsed >= goalRT.goal.maxInitiations) {
+            return { nextPhase: 'RESTING', backoff: false, resetBackoff: false };
+        }
+        // 无效果退避中 → 保持休息
+        if (now < this.noEffectBackoffUntil) {
+            return { nextPhase: 'RESTING', backoff: false, resetBackoff: false };
+        }
+        // 连续多次发起却长时间无效果 → 进入退避
+        const sinceEffect = goalRT.lastEffectAt ? now - goalRT.lastEffectAt : now - goalRT.startedAt;
+        if (goalRT.initiationsUsed >= this.opts.minAttemptsBeforeBackoff && sinceEffect > this.opts.noEffectWindowMs) {
+            return { nextPhase: 'RESTING', backoff: true, resetBackoff: false };
+        }
+        // RESTING 重新评估: 超过 goalReevalMs 且有存活 peer → 重置配额, 给新一轮机会
+        if (this.phase === 'RESTING' && liveCount > 0) {
+            const sinceLast = goalRT.lastInitiateAt ? now - goalRT.lastInitiateAt : now - goalRT.startedAt;
+            if (sinceLast > this.opts.goalReevalMs) {
+                goalRT.initiationsUsed = 0;
+                return { nextPhase: 'ENGAGING', backoff: false, resetBackoff: true };
+            }
+        }
+        return { nextPhase: liveCount > 0 ? 'ENGAGING' : 'DISCOVERING', backoff: false, resetBackoff: false };
+    }
+    // ===================== 入站处理 =====================
+    /** 入站处理: 由 server.ts 的 data 事件处理器在收到 agent.heartbeat / agent.chat.reply 时调用 */
+    handleIncoming(op, payload, fromPublicKey) {
+        if (op === 'agent.heartbeat') {
+            this.peerLiveness.set(fromPublicKey, Date.now());
+            const info = {
+                publicKey: fromPublicKey,
+                name: payload?.name,
+                agentId: payload?.agentId,
+                channels: Array.isArray(payload?.channels) ? payload.channels : [],
+                lastSeen: Date.now(),
+            };
+            this.opts.onPeerAlive?.(info);
+            return;
+        }
+        if (op === 'agent.chat.reply') {
+            this.opts.onReply?.({
+                fromPublicKey,
+                channelId: payload?.channelId || '',
+                text: payload?.text || '',
+            });
+            // 效果度量: 一条有效回复推进目标 → 累计效果, 解除退避; 达阈值则目标达成 → RESTING
+            const goalRT = this.goalRT;
+            if (goalRT && !goalRT.achieved) {
+                const assessment = this.opts.assessEffect
+                    ? this.opts.assessEffect({ goal: goalRT.goal, fromPublicKey, replyText: payload?.text || '' })
+                    : { advanced: !!(payload?.text && String(payload.text).trim().length > 0), achievedGoal: false };
+                if (assessment.advanced) {
+                    goalRT.effectfulReplies++;
+                    goalRT.lastEffectAt = Date.now();
+                    this.backoffLevel = 0;
+                    this.noEffectBackoffUntil = 0;
+                    if (assessment.achievedGoal || goalRT.effectfulReplies >= goalRT.goal.effectThreshold) {
+                        goalRT.achieved = true;
+                        console.log(`[heartbeat] 目标达成 (效果 ${goalRT.effectfulReplies}/${goalRT.goal.effectThreshold}) → RESTING: ${goalRT.goal.description}`);
+                        this.setPhase('RESTING');
+                    }
+                }
+            }
+            return;
+        }
+    }
+    // ===================== 运行期控制 / 观测 =====================
+    /** 设定新目标 (owner 可通过 RPC 注入). 会重置运行期状态 */
+    setGoal(goal) {
+        this.goalRT = this.makeGoalRuntime(goal);
+        this.backoffLevel = 0;
+        this.noEffectBackoffUntil = 0;
+        if (this.started && this.phase === 'RESTING')
+            this.setPhase('DISCOVERING');
+        console.log(`[heartbeat] 设定新目标: ${goal.description} (配额 ${goal.maxInitiations}, 效果阈值 ${goal.effectThreshold})`);
+        this.emitLifecycle();
+    }
+    setPhase(p) {
+        if (this.phase === p)
+            return;
+        this.phase = p;
+        this.emitLifecycle();
+    }
+    emitLifecycle() {
+        this.opts.onLifecycleChange?.(this.phase, this.getLifecycle());
+    }
+    /** 当前生命周期快照 */
+    getLifecycle() {
+        return {
+            phase: this.phase,
+            started: this.started,
+            livePeers: this.peerLiveness.size,
+            backoffLevel: this.backoffLevel,
+            socialIntervalMs: this.currentSocialInterval(),
+            noEffectBackoffUntil: this.noEffectBackoffUntil,
+            goal: this.goalRT
+                ? {
+                    id: this.goalRT.goal.id,
+                    description: this.goalRT.goal.description,
+                    initiationsUsed: this.goalRT.initiationsUsed,
+                    maxInitiations: this.goalRT.goal.maxInitiations,
+                    effectfulReplies: this.goalRT.effectfulReplies,
+                    effectThreshold: this.goalRT.goal.effectThreshold,
+                    achieved: this.goalRT.achieved,
+                }
+                : undefined,
+        };
+    }
+    /** 调试: 当前 peer 存活表 */
+    getLiveness() {
+        return Array.from(this.peerLiveness.entries()).map(([publicKey, lastSeen]) => ({ publicKey, lastSeen }));
+    }
+    /** 调试: 上次主动发起时间 */
+    getLastInitiated(publicKey) {
+        return this.lastInitiated.get(publicKey);
+    }
+    // ===================== 兼容 HealthMonitor 契约 =====================
+    /** 供 HealthMonitor.checkHeartbeat 观测已发现的智能体 */
+    getDiscoveredAgents() {
+        return this.getLiveness().map((l) => ({ publicKey: l.publicKey, lastSeen: l.lastSeen, channels: [] }));
+    }
+    /** 供 HealthMonitor.checkHeartbeat 观测社交是否开启 */
+    isAntColonyEnabled() {
+        return this.isSocialEnabled();
+    }
+}

package/dist/web/client.js

@@ -2588,7 +2588,12 @@ ${data.error || "channel not found"}`, "error");
           const allPreviews = container.querySelectorAll(".message-ai.preview");
           allPreviews.forEach((el) => el.remove());
           currentPreviewBubble = null;
-          addMessage2(data.content || "", "ai", true, container, lastUsedJudgmentIds || []);
+          if (!MR_hasStreamingText()) {
+            addMessage2(data.content || "", "ai", true, container, lastUsedJudgmentIds || []);
+          } else {
+            MR_replaceStreamingText?.(data.content || "");
+            MR_finalizeTimelineAsMessage(getRendererCtx());
+          }
         } else if (data.type === "reply-preview") {
           const previewContent = data.content || "";
           const oldPreviews = container.querySelectorAll(".message-ai.preview");

package/dist/web/server.js

@@ -217,6 +217,8 @@ async function persistRemoteChannelCache() {
 loadRemoteChannelCacheFromDisk();
 // v3: P2PDirect 引用 (Hyperswarm 薄包装) - 模块级, 因为 web server 闭包里不可用
 let v3P2PRef = null;
+// 2026-07-21: 智能体社交心跳实例 (beacon + 自主决策发起对话), data 事件处理器会引用它
+let agentHeartbeat = null;
 // 2026-06-10: watchdog 提升到 module-level, 让 broadcast() / 模块级业务函数能埋点喂活动
 // 之前在 createWebServer 闭包内, 闭包外的 broadcast() 拿不到 → 误判 30min 无活动 → 自杀.
 let watchdogRef = null;
@@ -1239,6 +1241,13 @@ function cleanupAndExit(signal) {
         return;
     cleanupDone = true;
     console.log(`[server] 收到 ${signal}, 开始清理...`);
+    // 优雅停止社交心跳: 清理 beacon/social 定时器, 防止进程退出前仍一直社交
+    try {
+        agentHeartbeat?.stop();
+    }
+    catch (e) {
+        console.warn('[heartbeat] 停止失败:', e?.message);
+    }
     try {
         fsSync.unlinkSync(LOCK_PATH);
     }
@@ -1415,6 +1424,11 @@ export async function createWebServer(port = 3000, options = {}) {
                             }, 'p2p-global');
                             return;
                         }
+                        // 2026-07-21: 社交心跳 beacon — 远端智能体宣告存活/能力, 更新本地 liveness
+                        if (parsed.op === 'agent.heartbeat') {
+                            agentHeartbeat?.handleIncoming('agent.heartbeat', parsed.payload, evt.fromPublicKey);
+                            return;
+                        }
                         // v3 新增: B 端收到 A 的 thinking (开始 + 流式 token)
                         if (parsed.op === 'agent.chat.thinking') {
                             const phase = parsed.payload?.phase;
@@ -1621,6 +1635,158 @@ export async function createWebServer(port = 3000, options = {}) {
                     console.error('[v3-P2PDirect] 解析/处理消息失败:', err.message);
                 }
             });
+            // === 2026-07-21: 智能体社交心跳 (beacon + 自主决策发起对话) ===
+            // beacon 周期向已知 peer 宣告存活/能力; social 循环让本地 agent 自主决定跟哪个远端智能体发起对话.
+            // 远端唤醒/回复链路已存在 (agent.chat.send → server.ts:529 跑 LLM → agent.chat.reply → SSE remote-chat-reply).
+            try {
+                const { AgentHeartbeat } = await import('../social/agent-heartbeat.js');
+                const socialOn = process.env.BOLLOON_AGENT_HEARTBEAT_SOCIAL !== '0';
+                const myName = await (async () => {
+                    let n = process.env.BOLLOON_USER_NAME || process.env.USER || 'node';
+                    try {
+                        const { readFileSync, existsSync } = await import('fs');
+                        const cfgPath = `${process.env.HOME || '/tmp'}/.bolloon/config.json`;
+                        if (existsSync(cfgPath)) {
+                            const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+                            if (cfg.userName)
+                                n = cfg.userName;
+                        }
+                    }
+                    catch { }
+                    return n;
+                })();
+                agentHeartbeat = new AgentHeartbeat({
+                    enabled: true,
+                    socialEnabled: socialOn,
+                    beaconIntervalMs: Number(process.env.BOLLOON_HEARTBEAT_BEACON_MS) || 30_000,
+                    socialIntervalMs: Number(process.env.BOLLOON_HEARTBEAT_SOCIAL_MS) || 120_000,
+                    cooldownMs: Number(process.env.BOLLOON_HEARTBEAT_COOLDOWN_MS) || 10 * 60_000,
+                    self: async () => {
+                        const channels = await loadChannels();
+                        const myPk = v3P2PRef?.getPublicKey() || '';
+                        return {
+                            publicKey: myPk,
+                            agentId: channels[0]?.agentId,
+                            name: myName,
+                            channels: channels.map((c) => ({ id: c.id, name: c.name })),
+                        };
+                    },
+                    getPeers: async () => {
+                        const { listPeers } = await import('../network/known-peers.js');
+                        const kp = await listPeers();
+                        const myPk = v3P2PRef?.getPublicKey() || '';
+                        const peers = [];
+                        for (const p of kp) {
+                            if (p.publicKey === myPk)
+                                continue;
+                            const cached = remoteChannelCache.get(p.publicKey) || [];
+                            peers.push({
+                                publicKey: p.publicKey,
+                                name: p.name,
+                                channels: cached.map((c) => ({ id: c.id, name: c.name })),
+                            });
+                        }
+                        return peers;
+                    },
+                    transport: {
+                        send: async (pk, op, payload) => {
+                            const { sendOrQueue } = await import('../network/p2p-outbox.js');
+                            return sendOrQueue(pk, op, payload, v3P2PRef);
+                        },
+                    },
+                    decide: socialOn ? llmSocialDecide : undefined,
+                    // 目标: 社交服务于"与网络中的其他智能体建立并维持协作". 配额/效果阈值防止一直社交.
+                    // owner 可通过 env BOLLOON_AGENT_GOAL 覆盖描述; 也可经 RPC setGoal 运行时注入.
+                    getGoal: async () => ({
+                        id: 'owner-collab',
+                        description: process.env.BOLLOON_AGENT_GOAL || '与网络中的其他智能体建立并维持协作关系, 主动分享进展并获取所需信息',
+                        maxInitiations: Number(process.env.BOLLOON_HEARTBEAT_GOAL_MAX) || 8,
+                        effectThreshold: Number(process.env.BOLLOON_HEARTBEAT_GOAL_EFFECT) || 3,
+                    }),
+                    // 效果度量: 远端回了非空且有实质内容的消息, 视为推进了目标 (生产可换 LLM 判定 achievedGoal)
+                    assessEffect: ({ replyText }) => {
+                        const t = (replyText || '').trim();
+                        return { advanced: t.length > 0, achievedGoal: false };
+                    },
+                    onPeerAlive: (peer) => {
+                        broadcast({
+                            type: 'peer-heartbeat',
+                            fromPublicKey: peer.publicKey,
+                            name: peer.name,
+                            channels: peer.channels,
+                            ts: Date.now(),
+                        }, 'p2p-global');
+                    },
+                    // 每次社交 tick 喂给 24h 看门狗, 防止误判卡死重启
+                    onActivity: () => {
+                        try {
+                            watchdogRef?.recordActivity?.('agent-heartbeat');
+                        }
+                        catch { }
+                    },
+                    // 生命周期阶段变化 → 推 SSE 给前端展示
+                    onLifecycleChange: (phase, snap) => {
+                        broadcast({
+                            type: 'agent-lifecycle',
+                            phase,
+                            snapshot: snap,
+                            ts: Date.now(),
+                        }, 'p2p-global');
+                    },
+                });
+                agentHeartbeat.start();
+                // 注册到全局, 让 24h HealthMonitor.checkHeartbeat 能观测到本智能体 (getDiscoveredAgents/isAntColonyEnabled)
+                global.socialHeartbeat = agentHeartbeat;
+                global.agentHeartbeat = agentHeartbeat;
+            }
+            catch (hbErr) {
+                console.warn('[heartbeat] 启动失败 (non-fatal):', hbErr?.message);
+            }
+            // 社交决策: 让本地 agent (用第一个本地 channel 的身份) 判断是否主动联络某 peer
+            // 目标感知: ctx.goal 是当前要达成的目标, 决策应服务于它, 达成后可声明 goalAchieved 进入 RESTING
+            async function llmSocialDecide(ctx) {
+                try {
+                    const channels = await loadChannels();
+                    const local = channels[0];
+                    if (!local)
+                        return { initiate: false };
+                    const agent = await getAgentForChannel(local.id, local.did || '', local.name, local.didDocRef);
+                    const peerLines = ctx.peers
+                        .map((p) => `- ${p.name || p.publicKey.slice(0, 8)} (pk=${p.publicKey.slice(0, 12)}…): 渠道[${p.channels.map((c) => c.name).join(', ') || '无'}]`)
+                        .join('\n');
+                    const goalDesc = ctx.goal ? `当前目标: ${ctx.goal.description} (已发起 ${ctx.goal.initiationsUsed}/${ctx.goal.maxInitiations}, 有效回复 ${ctx.goal.effectfulReplies}/${ctx.goal.effectThreshold})` : '当前无明确目标';
+                    const prompt = `你是智能体「${ctx.self.name || '本地智能体'}」。你通过 P2P 网络认识以下其他智能体:
+${peerLines}
+
+${goalDesc}
+
+规则:
+1. 社交是为了达成上述目标, 不是闲聊。只在你有真正有价值的信息要分享/询问、且能推进目标时才主动发起。
+2. 不要重复最近已经聊过的话题, 不要每条心跳都发消息, 保持克制。
+3. 如果目标已经通过已有交流达成 (或你认为无需再聊), 输出 {"initiate": false, "goalAchieved": true}。
+4. 如果决定发起, 选一个最合适的目标渠道 (用对方渠道的真实 id)。
+
+现在是否要主动联系其中某个智能体? 只输出一个 JSON 对象, 不要任何其他文字:
+{"initiate": true 或 false, "goalAchieved": true 或 false, "targetPeerPublicKey": "对方 pk", "targetChannelId": "对方渠道 id", "message": "你要说的话"}
+若不想发起, 输出 {"initiate": false}。`;
+                    const raw = await agent.promptStream(prompt, () => { }, undefined, local.id);
+                    const m = raw.match(/\{[\s\S]*\}/);
+                    if (!m)
+                        return { initiate: false };
+                    const obj = JSON.parse(m[0]);
+                    return {
+                        initiate: !!obj.initiate,
+                        goalAchieved: !!obj.goalAchieved,
+                        targetPeerPublicKey: obj.targetPeerPublicKey,
+                        targetChannelId: obj.targetChannelId,
+                        message: obj.message,
+                    };
+                }
+                catch (err) {
+                    console.warn('[heartbeat] 社交决策 LLM 失败 (跳过本次发起):', err?.message);
+                    return { initiate: false };
+                }
+            }
             // 新连接进来 → 主动发我分享给 ta 的 channel 列表
             v3P2PRef.on('connection', (evt) => {
                 // 2026-06-10: 喂 watchdog —— 新连接到来是真实业务活动

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli-entry.js",
@@ -48,30 +48,30 @@
     "src/constraint-runtime"
   ],
   "dependencies": {
-    "@bolloon/bolloon-agent": "^0.3.6",
+    "@bolloon/bolloon-agent": "^0.3.3",
     "@bolloon/constraint-runtime": "0.1.0",
-    "@capacitor/core": "^8.4.2",
+    "@capacitor/core": "^8.4.1",
     "@capacitor/ios": "^8.4.1",
     "@chainsafe/libp2p-noise": "^17.0.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
     "@diap/sdk": "^0.1.10",
     "@libp2p/autonat": "^3.0.20",
-    "@libp2p/circuit-relay-v2": "^4.2.9",
+    "@libp2p/circuit-relay-v2": "^4.2.5",
     "@libp2p/dcutr": "^3.0.20",
     "@libp2p/identify": "^4.1.6",
     "@libp2p/kad-dht": "^16.2.6",
     "@libp2p/tcp": "^11.0.20",
-    "@libp2p/upnp-nat": "^4.0.24",
+    "@libp2p/upnp-nat": "^4.0.20",
     "@multiformats/multiaddr": "^13.0.3",
-    "@noble/hashes": "^2.2.0",
+    "@noble/hashes": "^1.3.0",
     "@rayhanadev/iroh": "^0.1.1",
     "b4a": "^1.8.1",
     "dotenv": "^17.4.2",
-    "esbuild": "^0.28.1",
+    "esbuild": "^0.24.0",
     "express": "^5.2.1",
     "libp2p": "^3.3.0",
     "mammoth": "^1.6.0",
-    "pdf-parse": "^2.4.5",
+    "pdf-parse": "^1.1.4",
     "platform": "^1.3.6",
     "react": "^18.3.0",
     "react-dom": "^18.3.0",