@bolloon/bolloon-agent 0.4.13 → 0.4.14

package/dist/agents/agent-gateway.js

@@ -0,0 +1,130 @@
+/**
+ * agent-gateway.ts — Agent Gateway 协调层 (2026-08-14)
+ *
+ * Agent Economy 的"经济路由器": 统一入口, 内部编排所有已有层.
+ * 定位: 入口层 + 协调层 + 安全边界 (不是新系统, 是把 Registry/DIAP/x402/Policy/Reputation/Treasury 粘起来).
+ *
+ * 简单用法 (入口要小):
+ *   gateway.registerAgent({ capability: "research", price: "0.05 USDC" })
+ *   gateway.callAgent({ task: "analyze paper", budget: 1, capability: "research" })
+ *   gateway.joinNetwork(link)   // 通过链接自动加入共享网络
+ *
+ * callAgent 自动闭环:
+ *   Discovery (registry) → Identity (DIAP) → Negotiation (价格/预算匹配)
+ *   → Policy (预算/白名单) → Payment (x402/审批) → Execution → Reputation
+ */
+import { getAgentRegistry, warmAgentRegistry } from './agent-registry.js';
+import { getEconomicPolicy } from './economic-policy.js';
+import { getPaymentGate } from './payment-gate.js';
+import { getApprovalStore } from './payment-approval.js';
+import { recordServiceOutcome } from './agent-reputation.js';
+// ============ 协调层 ============
+/**
+ * 注册本 Agent 为服务提供者 (身份 + Registry + 信誉初始化).
+ */
+export async function gatewayRegisterAgent(config, identity, deps) {
+    // 2026-08-14: 生产路径先 warm OrbitDB — 否则注册只落本地文件, 分享链接指向的 store 是空的.
+    // 离线/测试环境 warm 失败不阻塞 (注册仍落本地 fallback).
+    let registry = deps?.registry;
+    if (!registry) {
+        try {
+            await warmAgentRegistry();
+        }
+        catch { /* 离线模式 */ }
+        registry = getAgentRegistry();
+    }
+    const r = await registry.register({
+        agentId: identity.did || `did:local:${identity.name}`,
+        name: identity.name,
+        wallet: config.wallet || identity.wallet,
+        service: {
+            name: config.capability,
+            description: config.description || `${config.capability} 服务`,
+            price: {
+                amount: config.price,
+                currency: (config.currency || 'USDC').toUpperCase(),
+                per: config.per || 'query',
+            },
+        },
+        capabilities: [config.capability],
+    });
+    return { ok: r.ok, error: r.error };
+}
+/**
+ * 调用 Agent 服务 (自动闭环).
+ * Discovery → Policy → Payment gate → Approval → Execution → Reputation.
+ */
+export async function gatewayCallAgent(opts) {
+    const { task, budget, capability, url, privateKey } = opts;
+    // 1. Discovery: 从 Registry 找 provider
+    const registry = getAgentRegistry();
+    const providers = capability ? await registry.discover(capability) : await registry.list();
+    if (providers.length === 0) {
+        return { success: false, error: `未找到能力为 '${capability || 'any'}' 的 Agent (先 joinNetwork 或注册)` };
+    }
+    const provider = providers[0]; // 简版: 取第一个 (完整版按信誉/价格排序)
+    const price = parseFloat(provider.service?.price?.amount || '0');
+    // 2. Negotiation: 预算检查
+    if (price > budget) {
+        return { success: false, error: `价格 ${price} 超预算 ${budget}`, provider: provider.agentId };
+    }
+    // 3. Payment gate (YAML 验证门): allow/confirm/deny
+    const gate = getPaymentGate();
+    const verdict = gate.evaluate({ service: provider.service?.name, amount: price, recipient: provider.wallet });
+    if (verdict.decision === 'deny') {
+        return { success: false, error: `[payment-gate] ${verdict.reason}`, provider: provider.agentId, decision: 'deny' };
+    }
+    // 4. Policy (预算/白名单)
+    const policy = getEconomicPolicy();
+    const pol = await policy.check({ payTo: provider.wallet, amount: price, service: provider.service?.name });
+    if (!pol.allowed) {
+        return { success: false, error: `[policy] ${pol.reason}`, provider: provider.agentId, decision: 'deny' };
+    }
+    // 5. confirm → 创建人工审批 (不自动执行)
+    if (verdict.decision === 'confirm') {
+        const store = getApprovalStore();
+        const approval = await store.create({
+            service: provider.service?.name || capability || 'service',
+            amount: price,
+            recipient: provider.wallet,
+            reason: verdict.reason,
+            retryPayload: { task, url, privateKey, serviceName: provider.service?.name, args: { task } },
+        });
+        return {
+            success: false,
+            error: `需人工确认: ${verdict.reason} (approval=${approval.id})`,
+            provider: provider.agentId,
+            decision: 'confirm',
+            requiresApproval: true,
+            approvalId: approval.id,
+        };
+    }
+    // 6. Execution (x402 支付 + 调用服务)
+    try {
+        const { serviceCall } = await import('./agent-service-client.js');
+        const r = await serviceCall({
+            serviceName: provider.service?.name || capability || 'service',
+            args: { task },
+            privateKey,
+            url,
+            registry,
+        });
+        if (!r.success)
+            return { success: false, error: r.error, provider: provider.agentId, decision: 'allow' };
+        // 7. Reputation: 记录成功
+        await recordServiceOutcome(provider.agentId, provider.service?.name || 'service', 'success', registry).catch(() => { });
+        return { success: true, provider: provider.agentId, decision: 'allow', output: r.output };
+    }
+    catch (e) {
+        return { success: false, error: `执行失败: ${String(e?.message || e).slice(0, 200)}`, provider: provider.agentId };
+    }
+}
+/**
+ * 查询网络状态 (注册表 + 信誉概览).
+ */
+export async function gatewayStatus() {
+    const registry = getAgentRegistry();
+    const services = await registry.list();
+    const lines = services.slice(0, 20).map((s) => `  [${s.service?.name}] ${s.name} (${s.service?.price?.amount} ${s.service?.price?.currency}/${s.service?.price?.per}) rep=${s.reputation?.score ?? 'n/a'}`);
+    return `Agent 网络 (${services.length} 服务):\n${lines.join('\n') || '  (空, 先 joinNetwork 或注册)'}`;
+}

package/dist/agents/gateway-group.js

@@ -0,0 +1,261 @@
+/**
+ * gateway-group.ts — Agent Gateway P2P 群组 (2026-08-14)
+ *
+ * 群组 = OrbitDB events store (accessController write:'*'), 任何成员可广播消息,
+ * 全成员通过 OrbitDB pubsub 复制实时同步. 链接: orbitdb://<addr>?type=group&name=<群名>.
+ *
+ * 符合用户习惯: 群组 = 微信式群聊 — 加入链接即进群, 发消息全网同步.
+ * 持久化: ~/.bolloon/gateway-groups.json (重启后仍是群成员, 自动重开 store).
+ */
+import * as os from 'os';
+import * as path from 'path';
+import { getCIDDatabase } from '../orbitdb/cid-database.js';
+// ============ 依赖注入 (测试用, 避免单测起真实 OrbitDB 节点) ============
+let _dbOverride = null;
+/** 测试用: 注入 fake CIDDatabase */
+export function setGroupTestDb(db) { _dbOverride = db; }
+function getDb() { return _dbOverride ?? getCIDDatabase(); }
+/** 测试用: 清空 store 缓存 / 订阅 (避免测试间污染) */
+export function resetGroupState() {
+    storeCache.clear();
+    onChangeCallbacks.clear();
+}
+// ============ 持久化 ============
+const groupsFile = () => path.join(os.homedir() || '/tmp', '.bolloon', 'gateway-groups.json');
+async function loadGroups() {
+    try {
+        const { readFile } = await import('fs/promises');
+        const parsed = JSON.parse(await readFile(groupsFile(), 'utf-8'));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function saveGroups(list) {
+    try {
+        const { mkdir, writeFile } = await import('fs/promises');
+        await mkdir(path.dirname(groupsFile()), { recursive: true });
+        await writeFile(groupsFile(), JSON.stringify(list, null, 2), 'utf-8');
+    }
+    catch { /* 持久化失败静默 */ }
+}
+// ============ 链接解析 ============
+/** 解析群组链接: orbitdb://<addr>?type=group&name=<群名> (type 非 group 返回 null) */
+export function parseGroupLink(link) {
+    const l = String(link || '').trim();
+    if (!l.startsWith('orbitdb://'))
+        return null;
+    const [base, query] = l.split('?');
+    let params = null;
+    try {
+        params = query ? new URLSearchParams(query) : null;
+    }
+    catch { /* 忽略 */ }
+    if (params && params.get('type') === 'group') {
+        let address = base.slice('orbitdb://'.length);
+        if (!address.startsWith('/'))
+            address = `/${address}`;
+        return { address, name: params.get('name') || undefined };
+    }
+    return null;
+}
+/** 从消息文本检测群组链接 */
+export function detectGroupLink(text) {
+    const t = String(text || '');
+    const re = /(orbitdb:\/\/\/?orbitdb\/[^\s)'"<>，。；]*\?[^\s)'"<>，。；]*type=group[^\s)'"<>，。；]*)/;
+    const m = re.exec(t);
+    return m ? m[1].trim() : null;
+}
+// ============ store 缓存 (避免重复 open) ============
+const storeCache = new Map();
+/** 订阅回调注册 (server 层挂 SSE 广播) */
+const onChangeCallbacks = new Map();
+function groupIdOf(address) {
+    // /orbitdb/zdpu... → zdpu... (地址后 12 位做短 id)
+    const m = /\/orbitdb\/(.{8,})/.exec(address);
+    return m ? m[1] : address;
+}
+/** 打开群组 store (缓存) — 可写 (replica=false, write:'*') */
+async function openGroupStore(address) {
+    const id = groupIdOf(address);
+    if (storeCache.has(id))
+        return storeCache.get(id);
+    const db = getDb();
+    const store = await db.openStoreByAddress(address, 'events', {
+        replica: false,
+        accessController: { write: ['*'] },
+    });
+    if (!store)
+        return null;
+    storeCache.set(id, store);
+    // 订阅: 新消息 → 通知回调 (server SSE)
+    store.onChange(() => {
+        groupMessages(id, 5).then((msgs) => {
+            if (msgs.length === 0)
+                return;
+            const cb = onChangeCallbacks.get(id);
+            if (cb)
+                for (const fn of cb) {
+                    try {
+                        fn(msgs[msgs.length - 1]);
+                    }
+                    catch { /* 忽略 */ }
+                }
+        }).catch(() => { });
+    });
+    return store;
+}
+/** 注册群组消息回调 (返回退订函数) */
+export function onGroupMessage(groupId, fn) {
+    if (!onChangeCallbacks.has(groupId))
+        onChangeCallbacks.set(groupId, new Set());
+    onChangeCallbacks.get(groupId).add(fn);
+    return () => { onChangeCallbacks.get(groupId)?.delete(fn); };
+}
+// ============ 群组操作 ============
+/**
+ * 创建群组: 新 events store (write:'*') + 持久化 + 生成邀请链接.
+ */
+export async function createGroup(name, opts) {
+    const groupName = String(name || '').trim() || `group-${Date.now().toString(36).slice(-4)}`;
+    try {
+        const db = getDb();
+        const store = await db.openStore(`bolloon-gw-group-${groupName}`, 'events', {
+            accessController: { write: ['*'] },
+        });
+        const address = store.address;
+        const id = groupIdOf(address);
+        const link = `orbitdb://${address}?type=group&name=${encodeURIComponent(groupName)}`;
+        const info = {
+            id, name: groupName, address, link,
+            createdAt: new Date().toISOString(),
+            lastSyncAt: new Date().toISOString(),
+        };
+        storeCache.set(id, store);
+        // 欢迎消息 (群主自我介绍)
+        const from = opts?.from || 'group-owner';
+        await store.add({ from, text: opts?.hello || `📢 群主创建了群「${groupName}」, 分享链接邀请成员加入`, ts: Date.now() });
+        const groups = await loadGroups();
+        await saveGroups([...groups.filter((g) => g.id !== id), info]);
+        return { ok: true, group: info };
+    }
+    catch (e) {
+        return { ok: false, error: `创建群组失败: ${String(e?.message || e).slice(0, 160)}` };
+    }
+}
+/**
+ * 通过链接加入群组: 打开 store (可写) + 持久化 + 幂等.
+ * 失败静默返回错误, 不影响本地.
+ */
+export async function joinGroup(link) {
+    const parsed = parseGroupLink(link);
+    if (!parsed) {
+        return { ok: false, error: '不是群组链接 (需要 orbitdb://...?type=group&name=...)' };
+    }
+    // 幂等: 按地址去重
+    const existing = await loadGroups();
+    const id = groupIdOf(parsed.address);
+    if (existing.some((g) => g.id === id)) {
+        return { ok: true, already: true, group: existing.find((g) => g.id === id) };
+    }
+    const store = await openGroupStore(parsed.address);
+    if (!store) {
+        return { ok: false, error: '群组 store 不可达 (群主节点需在线), 稍后重试或让群主分享最新链接' };
+    }
+    const name = parsed.name || id.slice(0, 12);
+    const info = {
+        id, name, address: parsed.address,
+        link: `orbitdb://${parsed.address}?type=group&name=${encodeURIComponent(name)}`,
+        createdAt: new Date().toISOString(),
+        lastSyncAt: new Date().toISOString(),
+    };
+    await saveGroups([...existing, info]);
+    return { ok: true, group: info };
+}
+/** 列出已加入的群组 */
+export async function listGroups() {
+    return loadGroups();
+}
+/** 获取群组 store 的最新消息 (ts 升序, 取最后 N 条) */
+export async function groupMessages(groupId, limit = 50) {
+    let store = storeCache.get(groupId) ?? null;
+    if (!store) {
+        const groups = await loadGroups();
+        const g = groups.find((x) => x.id === groupId);
+        if (!g)
+            return [];
+        store = await openGroupStore(g.address);
+        if (!store)
+            return [];
+    }
+    const all = await store.all().catch(() => []);
+    const msgs = [];
+    for (const entry of all) {
+        const v = entry.value;
+        if (v && typeof v.text === 'string' && typeof v.from === 'string') {
+            msgs.push({ from: v.from, text: v.text, ts: typeof v.ts === 'number' ? v.ts : 0 });
+        }
+    }
+    msgs.sort((a, b) => a.ts - b.ts);
+    return msgs.slice(-limit);
+}
+/** 群成员: 从消息里提取 from 去重 */
+export async function groupMembers(groupId) {
+    const msgs = await groupMessages(groupId, 500);
+    return Array.from(new Set(msgs.map((m) => m.from)));
+}
+/** 发送群消息 (广播给所有成员) */
+export async function groupSend(groupId, text, from) {
+    const msg = String(text || '').trim();
+    if (!msg)
+        return { ok: false, error: '消息不能为空' };
+    let store = storeCache.get(groupId) ?? null;
+    if (!store) {
+        const groups = await loadGroups();
+        const g = groups.find((x) => x.id === groupId);
+        if (!g)
+            return { ok: false, error: '群组不存在 (先 joinGroup)' };
+        store = await openGroupStore(g.address);
+        if (!store)
+            return { ok: false, error: '群组 store 不可达' };
+    }
+    try {
+        await store.add({ from: String(from || 'anonymous'), text: msg, ts: Date.now() });
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: `发送失败: ${String(e?.message || e).slice(0, 160)}` };
+    }
+}
+/** 群组邀请链接 */
+export async function groupLink(groupId) {
+    const groups = await loadGroups();
+    return groups.find((g) => g.id === groupId)?.link ?? null;
+}
+/** 群组信息 (含成员数/消息数) */
+export async function groupInfo(groupId) {
+    const groups = await loadGroups();
+    const g = groups.find((x) => x.id === groupId);
+    if (!g)
+        return null;
+    const msgs = await groupMessages(groupId, 500);
+    const members = await groupMembers(groupId);
+    return { ...g, messageCount: msgs.length, memberCount: members.length };
+}
+/** 重启恢复: 重开所有已加入群组的 store (失败静默) */
+export async function restoreGroups() {
+    const groups = await loadGroups();
+    if (groups.length === 0)
+        return { restored: 0, failed: 0, total: 0 };
+    let restored = 0;
+    let failed = 0;
+    for (const g of groups) {
+        const store = await openGroupStore(g.address).catch(() => null);
+        if (store)
+            restored++;
+        else
+            failed++;
+    }
+    return { restored, failed, total: groups.length };
+}

package/dist/agents/gateway-network.js

@@ -0,0 +1,278 @@
+/**
+ * gateway-network.ts — Agent 网络加入 (2026-08-14 v2)
+ *
+ * joinNetwork(link): 通过链接自动加入共享 Agent 网络.
+ * 链接形式 (三选一):
+ *   - orbitdb://<storeAddress>   共享 registry store (主链路, OrbitDB 复制)
+ *   - ipns://<name>              IPNS 标识 (registry 静态快照)
+ *   - https://.../registry       HTTP 端点 (远程 registry JSON)
+ *
+ * v2 新增:
+ *   - orbitdb:// 真实可开 (CIDDatabase.openStoreByAddress, replica 只读)
+ *   - 成员身份持久化 ~/.bolloon/gateway-networks.json (重启后仍是家庭成员)
+ *   - detectGatewayLink / maybeAutoJoinGateway — 消息里收到链接自动加入 (入口要小)
+ *   - shareNetworkLink — 生成本机可分享的网络链接 (把 registry 发出去)
+ */
+import * as os from 'os';
+import * as path from 'path';
+import { getAgentRegistry, warmAgentRegistry } from './agent-registry.js';
+/** 解析链接字符串 → ParsedLink (剥离 ?name= query) */
+export function parseNetworkLink(link) {
+    const l = String(link || '').trim();
+    if (!l)
+        return null;
+    const [base, query] = l.split('?');
+    let networkName;
+    try {
+        networkName = query ? (new URLSearchParams(query).get('name') || undefined) : undefined;
+    }
+    catch { /* 忽略坏 query */ }
+    if (base.startsWith('ipns://'))
+        return { kind: 'ipns', name: base.slice('ipns://'.length), networkName };
+    if (base.startsWith('orbitdb://')) {
+        // orbitdb:///orbitdb/<addr> 或 orbitdb://orbitdb/<addr> → /orbitdb/<addr>
+        let address = base.slice('orbitdb://'.length);
+        if (!address.startsWith('/'))
+            address = `/${address}`;
+        return { kind: 'orbitdb', address, networkName };
+    }
+    if (base.startsWith('http://') || base.startsWith('https://'))
+        return { kind: 'http', url: base, networkName };
+    return null;
+}
+/** 从消息文本里检测 gateway 链接 (自动加入触发器用) */
+export function detectGatewayLink(text) {
+    const t = String(text || '');
+    // orbitdb:// 地址含 '/' 必须贪婪匹配到空白/引号; https 允许 /registry 后带 ?query
+    const re = /(orbitdb:\/\/\/?orbitdb\/[^\s)'"<>，。；]+|ipns:\/\/[^\s)'"<>，。；]+|https?:\/\/[^\s)'"<>，。；]*\/registry(?:\?[^\s)'"<>，。；]*)?)/;
+    const m = re.exec(t);
+    return m ? m[1].trim() : null;
+}
+// ============ 远端拉取 ============
+/** 从 HTTP 端点拉取远端 registry */
+async function fetchRemoteRegistry(url) {
+    try {
+        const r = await fetch(url, { signal: AbortSignal.timeout(15000) });
+        if (!r.ok)
+            return null;
+        const data = await r.json();
+        // 兼容: {services:[...]} 或 [...]
+        const services = Array.isArray(data) ? data : (data.services ?? null);
+        return Array.isArray(services) ? services : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 从 IPNS 拉取 registry (需本地 Kubo + 8080 gateway) */
+async function fetchIpnsRegistry(name) {
+    try {
+        const r = await fetch(`http://127.0.0.1:8080/ipns/${name}/registry.json`, { signal: AbortSignal.timeout(15000) });
+        if (!r.ok)
+            return null;
+        const data = await r.json();
+        return Array.isArray(data) ? data : (data.services ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+/** 从 OrbitDB 打开共享 registry store (replica 只读) */
+async function fetchOrbitdbRegistry(address) {
+    try {
+        const { getCIDDatabase } = await import('../orbitdb/cid-database.js');
+        const db = getCIDDatabase();
+        const store = await db.openStoreByAddress(address, 'keyvalue');
+        if (!store)
+            return null;
+        // 先立即读 (同节点 store 已有数据); 没有再等复制 (owner 在线时 pubsub 复制通常 <1s)
+        const first = await store.get('services').catch(() => null);
+        if (Array.isArray(first))
+            return first;
+        await new Promise((resolve) => {
+            let done = false;
+            const finish = () => { if (!done) {
+                done = true;
+                try {
+                    off();
+                }
+                catch { }
+                resolve();
+            } };
+            const off = store.onChange(finish);
+            setTimeout(finish, 4000);
+        });
+        // 单键 'services' (registry 的 OrbitDB 布局: 整个列表存单键)
+        const v = await store.get('services').catch(() => null);
+        if (Array.isArray(v))
+            return v;
+        // 兼容: 遍历 entries 找数组值
+        const all = await store.all().catch(() => null);
+        if (Array.isArray(all)) {
+            for (const entry of all) {
+                if (Array.isArray(entry.value))
+                    return entry.value;
+                const val = entry.value;
+                if (val?.services && Array.isArray(val.services))
+                    return val.services;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const networksFile = () => path.join(os.homedir() || '/tmp', '.bolloon', 'gateway-networks.json');
+async function loadNetworks() {
+    try {
+        const { readFile } = await import('fs/promises');
+        const parsed = JSON.parse(await readFile(networksFile(), 'utf-8'));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function saveNetworks(list) {
+    try {
+        const { mkdir, writeFile } = await import('fs/promises');
+        await mkdir(path.dirname(networksFile()), { recursive: true });
+        await writeFile(networksFile(), JSON.stringify(list, null, 2), 'utf-8');
+    }
+    catch { /* 持久化失败静默 */ }
+}
+/** 列出已加入的网络 */
+export async function listJoinedNetworks() {
+    return loadNetworks();
+}
+/**
+ * 通过链接加入共享网络: 拉取远端服务列表 → 合并到本地 registry (按 agentId+service 去重).
+ * 幂等: 已加入的网络直接返回 already=true.
+ * deps.registry 可注入 (测试用), 默认单例.
+ */
+export async function joinNetwork(link, deps) {
+    const parsed = parseNetworkLink(link);
+    if (!parsed) {
+        return { ok: false, joined: 0, total: 0, error: '无法解析链接 (支持 orbitdb:// / ipns:// / https://)' };
+    }
+    // 幂等: 已加入 (按解析后的网络身份 key 去重, 忽略 ?name 差异)
+    const existing = await loadNetworks();
+    const norm = String(link).trim();
+    const identityKey = parsed.kind === 'orbitdb' ? `orbitdb:${parsed.address}`
+        : parsed.kind === 'ipns' ? `ipns:${parsed.name}`
+            : `http:${parsed.url}`;
+    if (existing.some((n) => n.linkKey === identityKey || n.link === norm)) {
+        return { ok: true, joined: 0, total: 0, already: true, linkKind: parsed.kind, networkName: parsed.networkName };
+    }
+    // 拉取远端服务
+    let remote = null;
+    if (parsed.kind === 'http') {
+        remote = await fetchRemoteRegistry(parsed.url);
+    }
+    else if (parsed.kind === 'ipns') {
+        remote = await fetchIpnsRegistry(parsed.name);
+    }
+    else if (parsed.kind === 'orbitdb') {
+        remote = await fetchOrbitdbRegistry(parsed.address);
+    }
+    if (!remote || remote.length === 0) {
+        return { ok: false, joined: 0, total: 0, error: '远端网络无服务或不可达 (store owner 需在线)', linkKind: parsed.kind };
+    }
+    // 合并到本地 registry (按 agentId + service.name 去重)
+    const registry = deps?.registry ?? getAgentRegistry();
+    const local = await registry.list();
+    let joined = 0;
+    for (const svc of remote) {
+        if (!svc?.agentId || !svc?.service?.name)
+            continue;
+        const exists = local.some((l) => l.agentId === svc.agentId && l.service?.name === svc.service?.name);
+        if (!exists) {
+            await registry.register(svc).catch(() => { });
+            joined++;
+        }
+    }
+    // 记录成员身份 (持久化 → 重启后自动恢复)
+    await saveNetworks([
+        ...existing,
+        {
+            link: norm,
+            linkKey: identityKey,
+            kind: parsed.kind,
+            name: parsed.networkName,
+            joinedAt: new Date().toISOString(),
+            serviceCount: remote.length,
+            lastSyncAt: new Date().toISOString(),
+        },
+    ]);
+    return { ok: true, joined, total: remote.length, linkKind: parsed.kind, networkName: parsed.networkName };
+}
+/** 启动恢复: 重拉所有已加入网络 (失败静默, 保留记录). 返回恢复统计. */
+export async function restoreJoinedNetworks() {
+    const nets = await loadNetworks();
+    if (nets.length === 0)
+        return { restored: 0, failed: 0, total: 0 };
+    let restored = 0;
+    let failed = 0;
+    for (const n of nets) {
+        const r = await joinNetwork(n.link).catch(() => null);
+        if (r?.ok)
+            restored++;
+        else
+            failed++;
+        // 更新 lastSyncAt
+        if (r?.ok) {
+            const updated = (await loadNetworks()).map((m) => m.link === n.link ? { ...m, lastSyncAt: new Date().toISOString(), serviceCount: r.total || m.serviceCount } : m);
+            await saveNetworks(updated);
+        }
+    }
+    return { restored, failed, total: nets.length };
+}
+// ============ 分享链接 ============
+/**
+ * 生成本机可分享的网络链接: orbitdb://<registry storeAddress>?name=<网络名>.
+ * 对方收到链接 → 自动 joinNetwork → 拉取本机注册的服务.
+ * opts.registry 可注入 (测试用), 默认单例.
+ */
+export async function shareNetworkLink(opts) {
+    try {
+        let registry = opts?.registry;
+        if (!registry) {
+            await warmAgentRegistry();
+            registry = getAgentRegistry();
+        }
+        if (!registry.ready || !registry.storeAddress) {
+            return { ok: false, error: 'OrbitDB registry 未就绪 (离线模式). 备选: 把 registry 列表发布成 https://.../registry 端点分享' };
+        }
+        const name = encodeURIComponent(String(opts?.name || registry.storeName || 'bolloon-network'));
+        return { ok: true, link: `orbitdb://${registry.storeAddress}?name=${name}` };
+    }
+    catch (e) {
+        return { ok: false, error: `生成分享链接失败: ${String(e?.message || e).slice(0, 160)}` };
+    }
+}
+// ============ 自动加入 (消息触发) ============
+/**
+ * 自动加入入口: 文本里检测到 gateway 链接 → 幂等 joinNetwork.
+ * 返回给 agent 的通知字符串 (无链接 / 已在网络 → null, 静默).
+ * 设计: 加入是自由的 (只拉服务列表, 不花钱), 支付仍走 payment-gate 安全链.
+ * deps.registry 可注入 (测试用), 默认单例.
+ */
+export async function maybeAutoJoinGateway(text, deps) {
+    const link = detectGatewayLink(text);
+    if (!link)
+        return null;
+    try {
+        const r = await joinNetwork(link, deps);
+        if (r.ok && r.already)
+            return null; // 已在网络, 静默
+        if (r.ok) {
+            const netName = r.networkName ? `「${r.networkName}」` : ''; // URLSearchParams 已 decode
+            return `🆕 已自动加入 Agent 网络${netName} (${r.linkKind}): 拉取 ${r.total} 个服务, 新增 ${r.joined} 个。用 gateway_status 查看, gateway_call 调用网络里的服务。`;
+        }
+        return `⚠️ 检测到 Agent 网络链接 (${r.linkKind || 'unknown'}) 但加入失败: ${r.error}`;
+    }
+    catch (e) {
+        return `⚠️ 自动加入 Agent 网络失败: ${String(e?.message || e).slice(0, 160)}`;
+    }
+}