@bolloon/bolloon-agent 0.2.11 → 0.2.13

package/dist/llm/tool-manifest/web.js

@@ -15,8 +15,8 @@ export const web_search = {
     parameters: [
         { name: 'query', type: 'string', required: true, description: '搜索查询 (1-6 词最佳)' },
     ],
-    callExample: `[TOOL:web_search]
-[P:query]S&P 500 current price
+    callExample: `[TOOL:web_search]
+[P:query]S&P 500 current price
 [ENDTOOL]`,
     layerId: 'tool.web_search',
 };
@@ -44,8 +44,8 @@ export const web_fetch = {
         { name: 'web_fetch_rate_limit_key', type: 'string', required: false, description: '速率限制键' },
         { name: 'web_fetch_rate_limit_dark_launch', type: 'boolean', required: false, description: '速率限制暗启动模式' },
     ],
-    callExample: `[TOOL:web_fetch]
-[P:url]https://example.com/article
+    callExample: `[TOOL:web_fetch]
+[P:url]https://example.com/article
 [ENDTOOL]`,
     layerId: 'tool.manifest',
 };

package/dist/network/local-inbox-bus.js

@@ -0,0 +1,73 @@
+/**
+ * local-inbox-bus.ts — 进程内 Agent 通信总线 (2026-06-19)
+ *
+ * 解决 bolloon "和另一个智能体发消息" 的本地场景:
+ *   - 同进程内多个 PiAgentSession 实例 (例如 nodeA / nodeB 测试) 互发消息
+ *   - 走 in-process EventEmitter, 不依赖 P2P 网络/Hyperswarm
+ *   - 远端通信仍走 p2pNetwork.sendMessage + onMessage
+ *
+ * 用法:
+ *   const bus = LocalInboxBus.getInstance();
+ *   bus.subscribe('nodeA', (msg) => console.log('nodeA got:', msg));
+ *   bus.deliver('nodeB', { from: 'nodeA', type: 'agent-message', payload: 'hi' });
+ *
+ * 角色标识: 默认从 process.env.BOLLOON_ROLE 读, 也可显式传
+ */
+import { EventEmitter } from 'events';
+class LocalInboxBus {
+    static _instance = null;
+    emitter;
+    /** 记录已注册的角色, deliver 时找不到会返回 false (避免 silent drop) */
+    registeredRoles = new Set();
+    constructor() {
+        this.emitter = new EventEmitter();
+        // 防止 listener 太多导致 memory leak
+        this.emitter.setMaxListeners(1000);
+    }
+    static getInstance() {
+        if (!LocalInboxBus._instance) {
+            LocalInboxBus._instance = new LocalInboxBus();
+        }
+        return LocalInboxBus._instance;
+    }
+    /**
+     * 订阅角色 inbox — 投递到该角色的消息会回调 fn
+     * 返回 unsubscribe 函数
+     */
+    subscribe(role, fn) {
+        this.registeredRoles.add(role);
+        this.emitter.on(`role:${role}`, fn);
+        return () => {
+            this.emitter.off(`role:${role}`, fn);
+            // 如果没人订阅, 移除 role (避免泄漏)
+            if (this.emitter.listenerCount(`role:${role}`) === 0) {
+                this.registeredRoles.delete(role);
+            }
+        };
+    }
+    /**
+     * 投递消息到指定角色
+     * 返回 true=已投递, false=角色未注册
+     */
+    deliver(role, msg) {
+        if (!this.registeredRoles.has(role)) {
+            return false;
+        }
+        this.emitter.emit(`role:${role}`, msg);
+        return true;
+    }
+    /**
+     * 列出当前进程所有已注册的角色
+     */
+    listRoles() {
+        return Array.from(this.registeredRoles);
+    }
+    /**
+     * 检查某角色是否已订阅
+     */
+    hasRole(role) {
+        return this.registeredRoles.has(role);
+    }
+}
+export { LocalInboxBus };
+export default LocalInboxBus;

package/dist/network/p2p-outbox.js

@@ -0,0 +1,161 @@
+/**
+ * p2p-outbox.ts — 离线消息队列管理 (基于 peer-fs.ts 落盘)
+ *
+ * 设计目的 (2026-07-05):
+ *   v3 P2PDirect 通道 sendTo 找不到 conn 就返回 false (消息扔进虚空).
+ *   这个模块给所有"发往远端"的 RPC 提供 outbox 兜底:
+ *     1) 发送前先 try sendToWithWait (3s 超时)
+ *     2) 失败 → enqueueOutbox 到 ~/.bolloon/peers/<pk>/outbox.jsonl
+ *     3) flushAllOutboxes() 周期跑 + 启动后跑, 检测到 peer 上线就批量重发
+ *
+ * 用法:
+ *   import { sendOrQueue } from '../network/p2p-outbox.js';
+ *   const r = await sendOrQueue(peerPk, 'agent.chat.send', { channelId, text }, v3P2PRef);
+ *   // r: 'SENT' | 'QUEUED' | 'FAILED'
+ */
+import * as crypto from 'crypto';
+import * as peerFs from './peer-fs.js';
+/**
+ * 发送或入队: 优先 sendToWithWait (3s), 失败 → 写 outbox.jsonl
+ */
+export async function sendOrQueue(publicKey, op, payload, p2p, opts = {}) {
+    if (!publicKey)
+        return 'FAILED';
+    const rpc = JSON.stringify({ v: 3, op, payload });
+    // 先尝试直发
+    if (!opts.forceQueue && p2p) {
+        try {
+            const r = await p2p.sendToWithWait(publicKey, rpc, 3000);
+            if (r === 'SENT')
+                return 'SENT';
+        }
+        catch (err) {
+            console.warn(`[outbox] sendToWithWait 抛错 (${publicKey.slice(0, 12)}...): ${err?.message?.slice(0, 100)}`);
+        }
+    }
+    // 直发失败 → 入队
+    try {
+        await peerFs.enqueueOutbox(publicKey, {
+            id: crypto.randomUUID(),
+            ts: new Date().toISOString(),
+            op,
+            payload,
+            attempts: 0,
+        });
+        console.log(`[outbox] ${op} → ${publicKey.slice(0, 12)}... 入队 (peer 当前不在线, 上线后自动重发)`);
+        return 'QUEUED';
+    }
+    catch (err) {
+        console.error(`[outbox] 入队失败 (${publicKey.slice(0, 12)}...): ${err?.message?.slice(0, 200)}`);
+        return 'FAILED';
+    }
+}
+/**
+ * 批量 flush 所有 peer 的 outbox — 对方上线后调用.
+ * 返回 { totalQueued, totalSent, totalFailed }.
+ */
+export async function flushAllOutboxes(p2p) {
+    if (!p2p)
+        return { peers: 0, totalQueued: 0, totalSent: 0, totalFailed: 0 };
+    let peers = 0, totalQueued = 0, totalSent = 0, totalFailed = 0;
+    try {
+        const all = await peerFs.listPeersFromDisk();
+        const myPk = p2p.getPublicKey();
+        for (const peer of all) {
+            if (peer.publicKey === myPk)
+                continue;
+            const outbox = await peerFs.readOutbox(peer.publicKey);
+            if (outbox.length === 0)
+                continue;
+            peers++;
+            totalQueued += outbox.length;
+            let sent = 0;
+            let failedEntries = [];
+            for (const entry of outbox) {
+                const rpc = JSON.stringify({ v: 3, op: entry.op, payload: entry.payload });
+                try {
+                    const r = await p2p.sendToWithWait(peer.publicKey, rpc, 3000);
+                    if (r === 'SENT') {
+                        sent++;
+                    }
+                    else {
+                        failedEntries.push({ ...entry, attempts: entry.attempts + 1, lastError: r });
+                    }
+                }
+                catch (err) {
+                    failedEntries.push({ ...entry, attempts: entry.attempts + 1, lastError: err?.message?.slice(0, 200) });
+                }
+            }
+            totalSent += sent;
+            totalFailed += failedEntries.length;
+            // 写回未发送的 (覆盖原文件)
+            if (failedEntries.length === 0) {
+                await peerFs.clearOutbox(peer.publicKey);
+            }
+            else {
+                // 重新写一份
+                const { writeFile, mkdir } = await import('fs/promises');
+                const path = await import('path');
+                const file = peerFs.getPeerOutboxPath(peer.publicKey);
+                await mkdir(path.dirname(file), { recursive: true });
+                const lines = failedEntries.map(e => JSON.stringify(e)).join('\n') + '\n';
+                await writeFile(file, lines, 'utf-8');
+            }
+            if (sent > 0) {
+                console.log(`[outbox] flush → ${peer.publicKey.slice(0, 12)}... 重发 ${sent}/${outbox.length} 条 ✓`);
+            }
+        }
+        if (totalQueued > 0) {
+            console.log(`[outbox] 累计处理: queued=${totalQueued}, sent=${totalSent}, failed=${totalFailed}`);
+        }
+    }
+    catch (err) {
+        console.warn('[outbox] flushAllOutboxes 失败:', err?.message?.slice(0, 200));
+    }
+    return { peers, totalQueued, totalSent, totalFailed };
+}
+/**
+ * 给单个 peer 入队一条 — 用于明确"对方一定不在线"的场景
+ */
+export async function queueOnly(publicKey, op, payload) {
+    await peerFs.enqueueOutbox(publicKey, {
+        id: crypto.randomUUID(),
+        ts: new Date().toISOString(),
+        op,
+        payload,
+        attempts: 0,
+    });
+}
+/**
+ * 查 outbox 状态
+ * 直接扫 ~/.bolloon/peers/ 子目录, 看每个目录里 outbox.jsonl 是否有内容 (不依赖 peer.json)
+ */
+export async function outboxStats() {
+    const fsPromises = await import('fs/promises');
+    const path = await import('path');
+    const byPeer = [];
+    let totalQueued = 0;
+    try {
+        const entries = await fsPromises.readdir(peerFs._debug.PEERS_ROOT);
+        for (const e of entries) {
+            const outboxFile = path.join(peerFs._debug.PEERS_ROOT, e, 'outbox.jsonl');
+            try {
+                const raw = await fsPromises.readFile(outboxFile, 'utf-8');
+                const cnt = raw.split('\n').filter(Boolean).length;
+                if (cnt > 0) {
+                    // 从目录名反推 publicKey (peerDirName 是 hash__prefix)
+                    const prefix = e.split('__').slice(1).join('__') || e;
+                    byPeer.push({ publicKey: prefix, count: cnt });
+                    totalQueued += cnt;
+                }
+            }
+            catch {
+                // 没 outbox.jsonl → 跳过
+            }
+        }
+    }
+    catch {
+        // PEERS_ROOT 不存在 → 空
+    }
+    return { totalPeers: byPeer.length, totalQueued, byPeer };
+}

package/dist/network/peer-fs.js

@@ -0,0 +1,420 @@
+/**
+ * peer-fs.ts — peer 目录读写 + agents 索引 + manifest 落盘
+ *
+ * 设计目的 (2026-07-05):
+ *   把"远程 P2P 节点"在本地物化成一份文件夹, 让本地所有 agent 都能"知道对方有什么":
+ *   ~/.bolloon/peers/<publicKey>/
+ *     peer.json               ← 对方基础信息 (name / publicKey / lastSeen / lastManifestTs)
+ *     user.md                 ← 对方用户画像 (本地维护)
+ *     _index.json             ← 对方 agent 列表 (轻量, 懒加载时优先读)
+ *     capability-index.md     ← ≤500 字摘要, 拼进 prompt
+ *     agents/<agentId>.md     ← 每个 agent 详细描述
+ *     groups/<groupId>.md     ← 群组
+ *     function/<cap>.md       ← 视频/音乐/图片
+ *     exportment/<game>.md    ← 游戏
+ *     science/<exp>.md        ← 实验记录
+ *     chat-<YYYY-MM>.md       ← 月度聊天记录归档
+ *     outbox.jsonl            ← 离线发送队列 (对方不在线时缓存)
+ *
+ * 写盘策略:
+ *   - 纯文本 md 文件, 人类可读, 便于调试
+ *   - JSON 仅用于 peer.json / _index.json / outbox.jsonl
+ *   - 全部操作 atomic (write tmp + rename), 避免半截文件
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+// ============== 路径常量 ==============
+const HOME = process.env.BOLLOON_HOME || path.join(os.homedir(), '.bolloon');
+const PEERS_ROOT = path.join(HOME, 'peers');
+/** publicKey hex → 短哈希, 用于目录名防超长 */
+export function peerDirName(publicKey) {
+    // 用 sha256 前 16 位 hex, 防 publicKey 改名冲突 + 文件名长度可控
+    const h = crypto.createHash('sha256').update(publicKey).digest('hex').slice(0, 16);
+    return `${h}__${publicKey.slice(0, 8)}`;
+}
+export function getPeerDir(publicKey) {
+    return path.join(PEERS_ROOT, peerDirName(publicKey));
+}
+export function getPeerIndexPath(publicKey) {
+    return path.join(getPeerDir(publicKey), '_index.json');
+}
+export function getPeerJsonPath(publicKey) {
+    return path.join(getPeerDir(publicKey), 'peer.json');
+}
+export function getPeerCapabilityIndexPath(publicKey) {
+    return path.join(getPeerDir(publicKey), 'capability-index.md');
+}
+export function getPeerChatPath(publicKey, yearMonth) {
+    const ym = yearMonth || currentYearMonth();
+    return path.join(getPeerDir(publicKey), `chat-${ym}.md`);
+}
+export function getPeerOutboxPath(publicKey) {
+    return path.join(getPeerDir(publicKey), 'outbox.jsonl');
+}
+export function getPeerUserMdPath(publicKey) {
+    return path.join(getPeerDir(publicKey), 'user.md');
+}
+export function getPeerAgentMdPath(publicKey, agentId) {
+    return path.join(getPeerDir(publicKey), 'agents', `${safeName(agentId)}.md`);
+}
+export function getPeerGroupMdPath(publicKey, groupId) {
+    return path.join(getPeerDir(publicKey), 'groups', `${safeName(groupId)}.md`);
+}
+export function getPeerFunctionMdPath(publicKey, capability) {
+    return path.join(getPeerDir(publicKey), 'function', `${safeName(capability)}.md`);
+}
+export function getPeerExportmentMdPath(publicKey, game) {
+    return path.join(getPeerDir(publicKey), 'exportment', `${safeName(game)}.md`);
+}
+export function getPeerScienceMdPath(publicKey, expId) {
+    return path.join(getPeerDir(publicKey), 'science', `${safeName(expId)}.md`);
+}
+export function currentYearMonth() {
+    const d = new Date();
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+/** 文件名安全化: 去掉 / \ : * ? " < > | 控制符 */
+function safeName(s) {
+    return s.replace(/[\/\\:\*\?"<>\|\x00-\x1f]/g, '_').slice(0, 64);
+}
+// ============== Atomic write helper ==============
+async function atomicWrite(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tmp = filePath + '.tmp.' + Math.random().toString(36).slice(2, 8);
+    await fs.writeFile(tmp, content);
+    await fs.rename(tmp, filePath);
+}
+async function atomicWriteJson(filePath, obj) {
+    await atomicWrite(filePath, JSON.stringify(obj, null, 2) + '\n');
+}
+async function readJsonSafe(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ============== peer.json ==============
+export async function upsertPeer(rec) {
+    const file = getPeerJsonPath(rec.publicKey);
+    const existing = await readJsonSafe(file);
+    const merged = {
+        publicKey: rec.publicKey,
+        name: rec.name ?? existing?.name,
+        addedAt: existing?.addedAt || rec.addedAt || new Date().toISOString(),
+        lastSeenAt: rec.lastSeenAt ?? existing?.lastSeenAt,
+        lastManifestTs: rec.lastManifestTs ?? existing?.lastManifestTs,
+        manifestCount: rec.manifestCount ?? existing?.manifestCount,
+        notes: rec.notes ?? existing?.notes,
+    };
+    await atomicWriteJson(file, merged);
+    return merged;
+}
+export async function getPeer(publicKey) {
+    return readJsonSafe(getPeerJsonPath(publicKey));
+}
+export async function listPeersFromDisk() {
+    try {
+        const entries = await fs.readdir(PEERS_ROOT);
+        const out = [];
+        for (const e of entries) {
+            const peerFile = path.join(PEERS_ROOT, e, 'peer.json');
+            const rec = await readJsonSafe(peerFile);
+            if (rec)
+                out.push(rec);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+// ============== _index.json (agent 清单) ==============
+export async function writePeerIndex(publicKey, idx) {
+    await atomicWriteJson(getPeerIndexPath(publicKey), idx);
+}
+export async function readPeerIndex(publicKey) {
+    return readJsonSafe(getPeerIndexPath(publicKey));
+}
+// ============== 单个 agent 详细描述 (markdown) ==============
+export async function writeAgentDescription(publicKey, agent, ownerDescription) {
+    const lines = [];
+    lines.push(`# ${agent.name || agent.id}`);
+    lines.push('');
+    lines.push(`- **ID**: ${agent.id}`);
+    lines.push(`- **状态**: ${agent.status}`);
+    if (agent.capabilities.length) {
+        lines.push(`- **能力**: ${agent.capabilities.join(', ')}`);
+    }
+    if (agent.description) {
+        lines.push('');
+        lines.push('## 描述');
+        lines.push('');
+        lines.push(agent.description);
+    }
+    if (ownerDescription) {
+        lines.push('');
+        lines.push('## Owner 备注');
+        lines.push('');
+        lines.push(ownerDescription);
+    }
+    if (agent.peerId || agent.irohNodeId || agent.sessionId) {
+        lines.push('');
+        lines.push('## 寻址');
+        if (agent.peerId)
+            lines.push(`- peerId: ${agent.peerId}`);
+        if (agent.irohNodeId)
+            lines.push(`- irohNodeId: ${agent.irohNodeId}`);
+        if (agent.sessionId)
+            lines.push(`- sessionId: ${agent.sessionId}`);
+    }
+    lines.push('');
+    lines.push(`> 自动生成于 ${new Date().toISOString()} (peer=${publicKey.slice(0, 12)}...)`);
+    lines.push('');
+    await atomicWrite(getPeerAgentMdPath(publicKey, agent.id), lines.join('\n'));
+}
+// ============== capability-index.md (≤500 字摘要, 进 prompt) ==============
+export function buildCapabilityIndex(idx) {
+    const lines = [];
+    lines.push(`# 远端节点能力索引 — ${idx.ownerName || idx.publicKey.slice(0, 12)}`);
+    lines.push('');
+    if (idx.ownerDescription) {
+        lines.push(idx.ownerDescription.slice(0, 200));
+        lines.push('');
+    }
+    lines.push(`## Agent (${idx.agents.length} 个)`);
+    for (const a of idx.agents.slice(0, 20)) {
+        const caps = a.capabilities.length ? ` [${a.capabilities.join('/')}]` : '';
+        const desc = a.description ? ` — ${a.description.slice(0, 60)}` : '';
+        lines.push(`- ${a.name}${caps}${desc}`);
+    }
+    if (idx.agents.length > 20)
+        lines.push(`- … 还有 ${idx.agents.length - 20} 个`);
+    if (idx.groups?.length) {
+        lines.push('');
+        lines.push(`## 群组 (${idx.groups.length})`);
+        for (const g of idx.groups.slice(0, 10))
+            lines.push(`- ${g.name}${g.description ? ' — ' + g.description.slice(0, 50) : ''}`);
+    }
+    if (idx.functions?.length) {
+        lines.push('');
+        lines.push(`## 可用功能 (${idx.functions.length})`);
+        for (const f of idx.functions.slice(0, 10))
+            lines.push(`- ${f.capability}${f.description ? ' — ' + f.description.slice(0, 50) : ''}`);
+    }
+    if (idx.exportments?.length) {
+        lines.push('');
+        lines.push(`## 娱乐 (${idx.exportments.length})`);
+        for (const e of idx.exportments.slice(0, 10))
+            lines.push(`- ${e.name}${e.description ? ' — ' + e.description.slice(0, 50) : ''}`);
+    }
+    const text = lines.join('\n');
+    // 截到 500 字
+    return text.length > 500 ? text.slice(0, 497) + '…' : text;
+}
+export async function writeCapabilityIndex(publicKey, idx) {
+    const text = buildCapabilityIndex(idx);
+    await atomicWrite(getPeerCapabilityIndexPath(publicKey), text);
+}
+export async function readCapabilityIndex(publicKey) {
+    try {
+        return await fs.readFile(getPeerCapabilityIndexPath(publicKey), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+// ============== chat-<YYYY-MM>.md 月度归档 ==============
+function formatChatEntry(e) {
+    const ts = e.ts.replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+    const src = e.source;
+    const chan = e.channelName ? ` [${e.channelName}]` : '';
+    const from = e.fromPublicKey ? ` (${e.fromPublicKey.slice(0, 12)}…)` : '';
+    return `### ${ts}${chan} — ${src}${from}\n\n${e.text}\n`;
+}
+export async function appendChat(publicKey, entry) {
+    const file = getPeerChatPath(publicKey);
+    // 如果文件不存在, 先写头
+    try {
+        await fs.access(file);
+    }
+    catch {
+        await atomicWrite(file, `# 与 ${publicKey.slice(0, 12)}… 的聊天记录\n\n> 自动归档; 详细消息存于 sessions/cache/, 这里按月滚动.\n\n`);
+    }
+    // append
+    await fs.appendFile(file, '\n---\n\n' + formatChatEntry(entry), 'utf-8');
+}
+export async function readChatArchive(publicKey, yearMonth) {
+    try {
+        return await fs.readFile(getPeerChatPath(publicKey, yearMonth), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function listChatMonths(publicKey) {
+    try {
+        const dir = getPeerDir(publicKey);
+        const entries = await fs.readdir(dir);
+        return entries
+            .filter(e => /^chat-\d{4}-\d{2}\.md$/.test(e))
+            .map(e => e.replace(/^chat-/, '').replace(/\.md$/, ''))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// ============== outbox.jsonl 离线队列 ==============
+export async function enqueueOutbox(publicKey, entry) {
+    const file = getPeerOutboxPath(publicKey);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.appendFile(file, JSON.stringify(entry) + '\n', 'utf-8');
+}
+export async function readOutbox(publicKey) {
+    try {
+        const raw = await fs.readFile(getPeerOutboxPath(publicKey), 'utf-8');
+        return raw.split('\n').filter(Boolean).map(line => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+export async function clearOutbox(publicKey) {
+    try {
+        await fs.unlink(getPeerOutboxPath(publicKey));
+    }
+    catch { }
+}
+export async function countOutbox(publicKey) {
+    return (await readOutbox(publicKey)).length;
+}
+// ============== user.md 本地维护的对方用户画像 ==============
+export async function readUserPortrait(publicKey) {
+    try {
+        return await fs.readFile(getPeerUserMdPath(publicKey), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeUserPortrait(publicKey, markdown) {
+    await atomicWrite(getPeerUserMdPath(publicKey), markdown);
+}
+// ============== 单个 group/function/exportment/science writer ==============
+// (peer-fs.ts 之前只有 reader — 现在补齐 4 类资源的 writer, 让 manifest.exchange.reply
+//  能落盘对方的群组/功能/娱乐/实验清单, 跟 agents/*.md 一样被本地 agent 看见.)
+function formatFrontmatter(fields) {
+    const lines = ['---'];
+    for (const [k, v] of Object.entries(fields)) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            lines.push(`${k}: [${v.map((x) => JSON.stringify(x)).join(', ')}]`);
+        }
+        else if (typeof v === 'string') {
+            lines.push(`${k}: ${JSON.stringify(v)}`);
+        }
+        else {
+            lines.push(`${k}: ${JSON.stringify(v)}`);
+        }
+    }
+    lines.push('---');
+    return lines.join('\n');
+}
+function mdBody(title, fields, description, extra) {
+    const parts = [];
+    parts.push(`# ${title}`);
+    parts.push('');
+    parts.push(formatFrontmatter(fields));
+    parts.push('');
+    if (description) {
+        parts.push(description.trim());
+        parts.push('');
+    }
+    if (extra?.length) {
+        parts.push(...extra);
+        parts.push('');
+    }
+    parts.push(`> 自动写入于 ${new Date().toISOString()} (peer 来源)`);
+    parts.push('');
+    return parts.join('\n');
+}
+export async function writeGroup(publicKey, g) {
+    const body = mdBody(g.name, {
+        id: g.id,
+        name: g.name,
+        visibility: g.visibility || 'invite',
+        memberCount: g.memberCount,
+    }, g.description);
+    await atomicWrite(getPeerGroupMdPath(publicKey, g.id), body);
+}
+export async function writeFunction(publicKey, f) {
+    const body = mdBody(f.capability, {
+        capability: f.capability,
+        mediaType: f.mediaType || 'text',
+        endpoint: f.endpoint,
+    }, f.description, f.examples?.length ? ['## 示例', '', ...f.examples.map((e) => `- ${e}`)] : undefined);
+    await atomicWrite(getPeerFunctionMdPath(publicKey, f.capability), body);
+}
+export async function writeExportment(publicKey, e) {
+    const body = mdBody(e.name, {
+        name: e.name,
+        genre: e.genre,
+        minPlayers: e.minPlayers,
+        maxPlayers: e.maxPlayers,
+    }, e.description);
+    await atomicWrite(getPeerExportmentMdPath(publicKey, e.name), body);
+}
+export async function writeScience(publicKey, s) {
+    const recordsBlock = s.records?.length
+        ? ['## 记录', '', ...s.records.map((r) => `- **${r.ts}**: ${r.note}`)]
+        : undefined;
+    const body = mdBody(s.title, {
+        id: s.id,
+        title: s.title,
+        status: s.status || 'planned',
+        tags: s.tags,
+    }, s.description, recordsBlock);
+    await atomicWrite(getPeerScienceMdPath(publicKey, s.id), body);
+}
+export async function listPeerResources(publicKey) {
+    const dir = getPeerDir(publicKey);
+    const out = { groups: [], functions: [], exportments: [], sciences: [] };
+    for (const [subdir, key] of [
+        ['groups', 'groups'],
+        ['function', 'functions'],
+        ['exportment', 'exportments'],
+        ['science', 'sciences'],
+    ]) {
+        try {
+            const entries = await fs.readdir(path.join(dir, subdir));
+            for (const e of entries) {
+                if (!e.endsWith('.md'))
+                    continue;
+                const content = await fs.readFile(path.join(dir, subdir, e), 'utf-8');
+                const id = e.replace(/\.md$/, '');
+                if (key === 'groups')
+                    out.groups.push({ id, content });
+                else if (key === 'functions')
+                    out.functions.push({ capability: id, content });
+                else if (key === 'exportments')
+                    out.exportments.push({ name: id, content });
+                else
+                    out.sciences.push({ id, content });
+            }
+        }
+        catch { }
+    }
+    return out;
+}
+// ============== 测试 / 调试 helper ==============
+export const _debug = {
+    PEERS_ROOT,
+    peerDirName,
+    getPeerDir,
+};