@bolloon/bolloon-agent 0.3.1 → 0.3.3

package/dist/web/server.js

@@ -12,6 +12,7 @@ import { segmentChatReply } from '../agents/chat-segmenter.js';
 import { registerJudgmentsRoutes } from './routes-judgments.js';
 import { registerLlmConfigRoutes } from './routes-llm-config.js';
 import { registerTaskRoutes } from './routes-tasks.js';
+import { registerHearthRoutes } from './routes-hearth.js';
 // 2026-07-06: 类型抽到 ./server-types.ts (channel / session / task / sse client / iroh info / paths)
 import { SESSION_CACHE_PATH, IPFS_ENDPOINT, } from './server-types.js';
 // 同时也 re-export 出去 (其它地方可能从 './server.js' 引用)
@@ -1824,7 +1825,11 @@ export async function createWebServer(port = 3000, options = {}) {
     const app = express();
     const server = createServer(app);
     await ensureSessionDirs();
-    app.use(express.json());
+    // 2026-07-15 修 Bug 3 续: attachment 路由需要单独大 limit body parser.
+    //   关键: 必须挂在主 app.use(express.json()) 之前, 否则 4MB attachment 在主 100KB parser 阶段就被拒.
+    //   path-prefix 让它只对 /api/attachments/* 生效, 不污染其他端点的限制.
+    app.use('/api/attachments', express.json({ limit: '15mb' }));
+    app.use(express.json({ limit: '100kb' }));
     app.use((req, res, next) => {
         res.setHeader('Access-Control-Allow-Origin', '*');
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
@@ -1924,6 +1929,125 @@ export async function createWebServer(port = 3000, options = {}) {
             res.status(400).json({ ok: false, reason: e?.message ?? 'parse error' });
         }
     });
+    // 2026-07-15 修 Bug 3: 拖拽文件上传
+    //   - POST /api/attachments/upload  body: { filename, mimeType, content: base64 }
+    //   - 文件落到 ~/.bolloon/attachments/<YYYY-MM>/<uuid>__<safeName>
+    //   - 返回 { ok, attachmentId, url, size, mimeType, filename }
+    //   - 前端拿到 attachmentId 后, 在消息文本里插一个 [attachment:id] 标记
+    //     (这条消息发出去时 server 端 /message 把它解析成 contextHint + 行内下载链接)
+    //   没用 multer/formidable — 复用 base64 JSON 简化, 跟 existing /api/judgments/import 同样的传输方式
+    //   body parser 在上面 path-prefix 中间件已挂, 这里直接 handler 即可.
+    const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024; // 10MB 单文件硬上限
+    app.post('/api/attachments/upload', async (req, res) => {
+        try {
+            const body = req.body ?? {};
+            const filename = String(body.filename || '').trim();
+            const mimeType = String(body.mimeType || 'application/octet-stream');
+            const content = String(body.content || '');
+            if (!filename || !content) {
+                return res.status(400).json({ ok: false, error: 'filename 与 content 必填' });
+            }
+            // base64 → bytes
+            const buf = Buffer.from(content, 'base64');
+            if (buf.length === 0) {
+                return res.status(400).json({ ok: false, error: '文件为空' });
+            }
+            if (buf.length > ATTACHMENT_MAX_BYTES) {
+                return res.status(413).json({
+                    ok: false,
+                    error: `文件超过 ${ATTACHMENT_MAX_BYTES / 1024 / 1024}MB 上限`,
+                });
+            }
+            // safeName: 跟 safeChannelName 同样规则, 防路径穿越 + Windows 非法字符
+            //   注意: 把 . 也加进替换 (不然 "../../" 被转成 "..__" 还残留 .. 序列), 整个文件 base 安全
+            const safeName = filename
+                .replace(/[\\/:*?"<>|\x00-\x1f.]/g, '_')
+                .replace(/^_+|_+$/g, '')
+                .slice(0, 120) || 'unnamed';
+            if (safeName !== filename) {
+                console.log(`[attachments] safeName 转换: "${filename}" → "${safeName}"`);
+            }
+            const month = new Date().toISOString().slice(0, 7); // YYYY-MM
+            const attachmentsDir = path.join(process.env.HOME || '/tmp', '.bolloon', 'attachments', month);
+            await fs.mkdir(attachmentsDir, { recursive: true });
+            const attachmentId = `${Date.now().toString(36)}_${crypto.randomBytes(6).toString('hex')}`;
+            const storedFilename = `${attachmentId}__${safeName}`;
+            const fullPath = path.join(attachmentsDir, storedFilename);
+            await fs.writeFile(fullPath, buf);
+            const urlPath = `/api/attachments/${attachmentId}`;
+            console.log(`[attachments] 上传 ${filename} (${buf.length}B, ${mimeType}) → ${fullPath}`);
+            res.json({
+                ok: true,
+                attachmentId,
+                url: urlPath,
+                filename,
+                storedFilename,
+                size: buf.length,
+                mimeType,
+            });
+        }
+        catch (e) {
+            console.error('[attachments] upload failed:', e?.message || e);
+            res.status(500).json({ ok: false, error: e?.message || '上传失败' });
+        }
+    });
+    // GET /api/attachments/:id — 下载 (按 attachmentId 找当月目录; 月份遍历回退)
+    app.get('/api/attachments/:id', async (req, res) => {
+        try {
+            const id = String(req.params.id || '').replace(/[^a-zA-Z0-9_]/g, '');
+            if (!id)
+                return res.status(400).type('text/plain').send('invalid id');
+            const attachmentsRoot = path.join(process.env.HOME || '/tmp', '.bolloon', 'attachments');
+            // 先按当前月 → 前一月 → …→ 全部月份列表 (3 个月够历史用)
+            const candidates = [];
+            const now = new Date();
+            for (let i = 0; i < 6; i++) {
+                const d = new Date(now.getFullYear(), now.getMonth() - i, 1);
+                const month = d.toISOString().slice(0, 7);
+                try {
+                    const files = await fs.readdir(path.join(attachmentsRoot, month));
+                    for (const f of files) {
+                        if (f.startsWith(id + '__'))
+                            candidates.push(path.join(attachmentsRoot, month, f));
+                    }
+                }
+                catch { /* month dir 可能不存在, 跳过 */ }
+                if (candidates.length > 0)
+                    break;
+            }
+            if (candidates.length === 0) {
+                return res.status(404).type('text/plain').send('attachment not found');
+            }
+            const fullPath = candidates[0];
+            const stat = await fs.stat(fullPath).catch(() => null);
+            if (!stat || !stat.isFile()) {
+                return res.status(404).type('text/plain').send('attachment missing');
+            }
+            // 从文件名还原原 mimeType: 按扩展名猜
+            const fileBase = path.basename(fullPath);
+            const origName = fileBase.substring(id.length + 2); // 跳过 "<id>__"
+            const ext = path.extname(origName).toLowerCase();
+            const mimeMap = {
+                '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+                '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+                '.pdf': 'application/pdf',
+                '.txt': 'text/plain', '.md': 'text/markdown', '.json': 'application/json',
+                '.csv': 'text/csv', '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+                '.zip': 'application/zip',
+                '.mp3': 'audio/mpeg', '.mp4': 'video/mp4', '.webm': 'video/webm',
+            };
+            const mime = mimeMap[ext] || 'application/octet-stream';
+            const buf = await fs.readFile(fullPath);
+            res.setHeader('Content-Length', String(buf.length));
+            res.setHeader('Content-Type', mime);
+            res.setHeader('Content-Disposition', `inline; filename*=UTF-8''${encodeURIComponent(origName)}`);
+            res.send(buf);
+        }
+        catch (e) {
+            console.error('[attachments] download failed:', e?.message || e);
+            res.status(500).type('text/plain').send('download error: ' + (e?.message || ''));
+        }
+    });
     // 全局兜底: 任何 next(err) 走到这里, 给出结构化 4xx/5xx 而不是默认 HTML
     app.use((err, req, res, _next) => {
         console.error('[server] unhandled error on', req.method, req.path, '-', err?.message || err);
@@ -1955,10 +2079,29 @@ export async function createWebServer(port = 3000, options = {}) {
         });
     });
     app.post('/message', async (req, res) => {
-        const { text, channelId, channelDid } = req.body;
+        const { text, channelId, channelDid, attachments } = req.body;
         if (!text) {
             return res.status(400).json({ error: 'No text provided' });
         }
+        // 2026-07-15 修 Bug 3: 拖拽附件 — LLM 在 contextHint 里看到文件清单, 用户文本保持可读
+        //   替代方案: 把 [attachment:id] 标记塞 text 里, 这里解析回 attachments 数组
+        let parsedAttachments = [];
+        if (Array.isArray(attachments) && attachments.length > 0) {
+            parsedAttachments = attachments.filter((a) => a && typeof a.attachmentId === 'string' && a.attachmentId.length > 0);
+        }
+        else {
+            // 兼容老前端: 从 text 里抽 [attachment:<id>] 标记
+            const rx = /\[attachment:([a-zA-Z0-9_]+)\]/g;
+            let m;
+            while ((m = rx.exec(String(text))) !== null) {
+                parsedAttachments.push({ attachmentId: m[1] });
+            }
+        }
+        const attachmentContext = parsedAttachments.length > 0
+            ? `[系统上下文] 用户上传了 ${parsedAttachments.length} 个附件: ` +
+                parsedAttachments.map(a => `${a.filename || a.attachmentId} (id=${a.attachmentId}, mime=${a.mimeType || '?'}, size=${a.size ?? '?'}B, URL=/api/attachments/${a.attachmentId})`).join('; ') +
+                `\n你需要时可以调用文件读工具 (curl /api/attachments/<id>) 拉取真实内容。\n\n`
+            : '';
         if (!channelId) {
             return res.status(400).json({ error: 'No channelId provided' });
         }
@@ -1990,9 +2133,17 @@ export async function createWebServer(port = 3000, options = {}) {
         // per-channel queue 检查: 已在跑就入队, 等当前跑完自动接上
         const runState = getOrCreateRunState(channelId);
         if (runState.running) {
-            runState.queue.push({ channelId, text, boundWalletAddress, autoToolsEnabled });
+            // 2026-07-15 修 Bug 8: 入队时保留 attachments + channelDid, 否则下一轮执行时会丢附件
+            runState.queue.push({
+                channelId,
+                text,
+                boundWalletAddress,
+                autoToolsEnabled,
+                attachments: parsedAttachments,
+                channelDid,
+            });
             broadcastQueueUpdate(channelId);
-            console.log(`[queue] /message 入队 channel=${channelId}, queue len=${runState.queue.length}`);
+            console.log(`[queue] /message 入队 channel=${channelId}, queue len=${runState.queue.length}, attach=${parsedAttachments.length}`);
             return;
         }
         runState.running = true;
@@ -2267,7 +2418,8 @@ export async function createWebServer(port = 3000, options = {}) {
                     extraHint = hint + '\n\n';
                     nextPromptHints.delete(channelId);
                 }
-                const markedPrompt = `${extraHint}【本轮用户请求】\n${text}\n【请求结束】\n\n${contextHint}`;
+                // 2026-07-15 修 Bug 3: 拖拽附件 — attachmentContext 提到 contextHint 最前, LLM 第一眼看到文件清单
+                const markedPrompt = `${extraHint}【本轮用户请求】\n${text}\n【请求结束】\n\n${attachmentContext}${contextHint}`;
                 fullResponse = await agent.promptStream(markedPrompt, streamCallback, runState.abortController?.signal, channelId);
             }
             catch (err) {
@@ -2310,7 +2462,15 @@ export async function createWebServer(port = 3000, options = {}) {
             const session = existingSession || { channelId, sessionId: currentSessionId, messages: [], lastUpdated: new Date().toISOString() };
             session.sessionId = currentSessionId;
             // v3: 加 source 标记 (local = 内部 owner, remote = 远端访客)
-            session.messages.push({ id: crypto.randomUUID(), type: 'user', content: text, timestamp: new Date().toISOString(), source: 'local' });
+            // 2026-07-15 修 Bug 4: client.ts sendMessage 已经通过 persistLastMessageToServer PATCH /sessions/.../...
+            //   把 user msg 落盘一次 (立即落, 切走再切回不丢). 这里再 push 一次 → session.messages 出现两条相同的 user msg,
+            //   loadSession 重渲染时两条都上屏, 表现"每条 user 气泡重复两次".
+            //   修法: 持久化以 client PATCH 为准, /message 这边只 push ai 消息. 同时去重检查上次的 user 避免极端竞态 (并行 PATCH).
+            const lastMsg = session.messages[session.messages.length - 1];
+            const userAlreadyPushed = lastMsg && lastMsg.type === 'user' && lastMsg.content === text;
+            if (!userAlreadyPushed) {
+                session.messages.push({ id: crypto.randomUUID(), type: 'user', content: text, timestamp: new Date().toISOString(), source: 'local' });
+            }
             session.messages.push({
                 id: crypto.randomUUID(),
                 type: 'ai',
@@ -2499,12 +2659,26 @@ export async function createWebServer(port = 3000, options = {}) {
             //   能直接拿到引用.
             clearTimeout(forceTimeout);
             // queue dequeue: 跑完或失败都要清状态
-            // 当前实现: 自动接下一条需要把 ~200 行 try 块抽函数, 暂不抽.
-            // 替代: 用户点 [队列 +N] 按钮时, 客户端发起一个特殊的 HTTP 请求触发下一条
-            // (在 client.js 实现). 这里只清状态 + 广播.
             runState.running = false;
             runState.abortController = null;
             broadcastQueueUpdate(channelId);
+            // 2026-07-15 修 Bug 8: 队列自动 drain — 之前只清状态不抽下一条, 用户连续发的所有
+            //   第二轮起全卡在 queue 里出不来, 表现"第二轮没反应".
+            //   修复: finally 里查 queue, 非空就异步 fire-and-forget 起下一轮.
+            //   实现要点:
+            //     1. 用 setImmediate / Promise.resolve() 让 res.headersSent 干净
+            //     2. 不能 await (否则阻塞 finally 后面的 saveSession; 而且这就是 fire-and-forget)
+            //     3. 重新 build contextHint, 走相同 LLM 路径
+            if (runState.queue.length > 0) {
+                const next = runState.queue.shift();
+                console.log(`[queue-drain] channel=${next.channelId} text="${next.text.slice(0, 30)}" attach=${(next.attachments?.length ?? 0)}`);
+                // 异步跑下一条 (fire-and-forget)
+                setImmediate(() => {
+                    void runMessageFromQueue(next).catch((e) => {
+                        console.error('[queue-drain] error:', e?.message?.slice(0, 200));
+                    });
+                });
+            }
             // 2026-07-01 (v0.2.5): 持久化当前 messageHistory — 让 web 用户跨刷新保留对话.
             //   saveCurrentSession 失败静默, 不阻塞 channel 状态清理.
             //   saveCurrentSession 内部走 SessionStore (默认 ~/.bolloon/sessions/cache/<sessionKey>.json).
@@ -2514,7 +2688,7 @@ export async function createWebServer(port = 3000, options = {}) {
                     await agent.saveCurrentSession(sessionKey);
                 }
                 catch (saveErr) {
-                    console.warn(`[web] saveCurrentSession failed (non-fatal): ${saveErr?.message?.slice(0, 100)}`);
+                    console.warn(`[web] saveCurrentSession failed (non-fatal): ${saveErr.message?.slice(0, 100)}`);
                 }
             }
         }
@@ -2535,6 +2709,115 @@ export async function createWebServer(port = 3000, options = {}) {
         }
         return s;
     }
+    /** 抽离 attachment contextHint 出来 — 给 queue-drain 用; /message 主路径有 inline 等价版避免重复 hoist 错误 */
+    function buildAttachmentContextForQueue(parsedAttachments) {
+        if (!parsedAttachments || parsedAttachments.length === 0)
+            return '';
+        return `[系统上下文] 用户上传了 ${parsedAttachments.length} 个附件: ` +
+            parsedAttachments.map((a) => `${a.filename || a.attachmentId} (id=${a.attachmentId}, mime=${a.mimeType || '?'}, size=${a.size ?? '?'}B, URL=/api/attachments/${a.attachmentId})`).join('; ') +
+            `\n你可以调用文件读工具 (curl /api/attachments/<id>) 拉取真实内容。\n\n`;
+    }
+    /**
+     * 2026-07-15 修 Bug 8: 队列消息的执行器 — finally 排空 queue 时调这里
+     * 跑下一条 queued 消息.
+     *
+     * 设计: 这是个 fire-and-forget wrapper, 复用 /message 主路径的 broadcast / save / etc.
+     * 简化路径 (跟主路径 500 行 try 块相比):
+     *   - 不重新建载 judgment hint / persona / context — server.ts 这次明确把这些容
+     *     易"廉价放"在 /message 主路径, queue 路径只用基本标识
+     *   - 仍然是合法: agent.promptStream → broadcast(type:user) → broadcast(type:ai) → done
+     *   - 处理 attachments: 跟主路径一样
+     *
+     * 如果要 1:1 复刻主路径的所有 hooks (judgment hint / persona / manifest / etc),
+     * 后续可以把 /message 主路径的 try 块抽成 runPromptChannel 共享.
+     */
+    async function runMessageFromQueue(queued) {
+        const { channelId, text, attachments, channelDid: reqChannelDid, boundWalletAddress, autoToolsEnabled } = queued;
+        const runState = getOrCreateRunState(channelId);
+        if (runState.running)
+            return; // 防重入 — queue 已经并发去重
+        runState.running = true;
+        runState.abortController = new AbortController();
+        const currentSessionId = (await loadChannels()).find(c => c.id === channelId)?.currentSessionId || 'default';
+        const realChannelDid = reqChannelDid || (await loadChannels()).find(c => c.id === channelId)?.did || '';
+        const parsedAttachments = Array.isArray(attachments) ? attachments : [];
+        const attachmentContext = buildAttachmentContextForQueue(parsedAttachments);
+        const sessionKey = `${channelId}:${currentSessionId}`;
+        // 防 LLM hang 安全网
+        const PIVOT_FORCE_TIMEOUT_MS = 5 * 60 * 1000;
+        const forceTimeout = setTimeout(() => {
+            console.warn(`[server] queue-drain pivot 强制 timeout, aborting`);
+            runState.abortController?.abort();
+        }, PIVOT_FORCE_TIMEOUT_MS);
+        let agent = null;
+        try {
+            // 1) broadcast user 给前端 (跟主路径一致)
+            broadcast({ type: 'user', content: text }, channelId);
+            // 2) 取 agent + session
+            agent = await getAgentForChannel(channelId, currentSessionId).catch(() => null);
+            if (!agent) {
+                throw new Error(`No agent for channel=${channelId}`);
+            }
+            // 3) 重 build contextHint (基本版, 不全 500 行 hook)
+            //   原因: queue-drain 是常见调试路径, 全量 hooks 性能大. 关键是 attachments 带上.
+            const contextHint = attachmentContext + `[系统上下文] 队列消息 (auto-drain)\n`;
+            // 4) promptStream
+            const markedPrompt = `【本轮用户请求】\n${text}\n【请求结束】\n\n${contextHint}`;
+            const fullResponse = await agent.promptStream(markedPrompt, () => { }, runState.abortController?.signal, channelId);
+            if (!fullResponse.trim()) {
+                broadcast({ type: 'error', content: '⚠️ AI 未返回内容' }, channelId);
+            }
+            else {
+                broadcast({ type: 'ai', content: fullResponse }, channelId);
+                // 落 session
+                try {
+                    const existing = await loadSession(channelId, currentSessionId);
+                    const session = existing || { channelId, sessionId: currentSessionId, messages: [], lastUpdated: new Date().toISOString() };
+                    session.sessionId = currentSessionId;
+                    // 跟主路径相同: 不重复 push user (主路径已 broadcast/push), 只 push ai
+                    session.messages.push({
+                        id: crypto.randomUUID(),
+                        type: 'ai',
+                        content: fullResponse,
+                        timestamp: new Date().toISOString(),
+                        source: 'local',
+                    });
+                    session.lastUpdated = new Date().toISOString();
+                    await saveSession(session);
+                }
+                catch (e) {
+                    console.warn('[queue-drain] saveSession failed:', e?.message?.slice(0, 100));
+                }
+            }
+            broadcast({ type: 'done' }, channelId);
+        }
+        catch (err) {
+            console.warn('[queue-drain] failed:', err?.message?.slice(0, 200));
+            broadcast({ type: 'error', content: 'queue-drain: ' + (err?.message || 'failed') }, channelId);
+        }
+        finally {
+            clearTimeout(forceTimeout);
+            runState.running = false;
+            runState.abortController = null;
+            broadcastQueueUpdate(channelId);
+            // 递归 drain — 同 /message 主路径 finally 行为保持一致
+            if (runState.queue.length > 0) {
+                const next = runState.queue.shift();
+                console.log(`[queue-drain-recursive] channel=${next.channelId} text="${next.text.slice(0, 30)}"`);
+                setImmediate(() => {
+                    void runMessageFromQueue(next).catch((e) => {
+                        console.error('[queue-drain-recursive] error:', e?.message?.slice(0, 200));
+                    });
+                });
+            }
+            if (agent) {
+                try {
+                    await agent.saveCurrentSession(sessionKey);
+                }
+                catch { }
+            }
+        }
+    }
     function broadcastQueueUpdate(channelId) {
         const s = channelRunState.get(channelId);
         const queueLength = s ? s.queue.length : 0;
@@ -2855,6 +3138,41 @@ export async function createWebServer(port = 3000, options = {}) {
             channels.push(channel);
             await saveChannels(channels);
             await saveSession({ channelId: id, sessionId: 'default', messages: [], lastUpdated: new Date().toISOString() });
+            // 2026-07-15 修 Bug 6: 同步把 agent 定义写进 ~/.bolloon/agents/agents.json
+            //   之前 channel 只落 channels.json, 不会出现在 agents.json 里.
+            //   重新启动 server 时 loadLocalSubAgents 只读 agents.json — 用户以为"智能体没保存".
+            //   修法: 直接读 + append (idempotent) 写 agents.json, 用 channel.agentId 作为主键 (跟 channels.json 引用对齐).
+            //   不走 SubAgentManager.registerAgent 因为它会自己生成新 id, 跟 channel.agentId 对不上.
+            try {
+                const agentsPath = path.join(process.env.HOME || '/tmp', '.bolloon', 'agents', 'agents.json');
+                await fs.mkdir(path.dirname(agentsPath), { recursive: true });
+                let arr = [];
+                try {
+                    arr = JSON.parse(await fs.readFile(agentsPath, 'utf-8'));
+                }
+                catch { }
+                if (!Array.isArray(arr))
+                    arr = [];
+                const exists = arr.some(a => a && a.id === agentId);
+                if (!exists) {
+                    arr.push({
+                        id: agentId,
+                        name,
+                        did: `did:local:${id}`,
+                        description: `Agent ${name} (auto-registered from channel ${id})`,
+                        capabilities: Array.isArray(channelPersona?.capabilities) ? channelPersona.capabilities : [],
+                        status: 'active',
+                        createdAt: new Date().toISOString(),
+                        lastActive: new Date().toISOString(),
+                        channelId: id,
+                    });
+                    await fs.writeFile(agentsPath, JSON.stringify(arr, null, 2), 'utf-8');
+                    console.log(`[创建频道] agent 写进 agents.json: name=${name} id=${agentId}`);
+                }
+            }
+            catch (e) {
+                console.warn('[创建频道] 写 agents.json 失败 (非致命):', e?.message?.slice(0, 120));
+            }
             res.json(channel);
             // 后台生成 DID — 用统一的修复队列, 避免每个 POST 都启动独立 setTimeout
             console.log(`[创建频道] 加入 DID 修复队列...`);
@@ -2993,6 +3311,32 @@ export async function createWebServer(port = 3000, options = {}) {
                 }
                 catch { }
             }
+            // 2026-07-15 修 Bug 7: 同步清理 agents.json 里挂在这个 channel 下的 agent 定义
+            //   之前 v0.3.6 (Bug 6) 创建频道时同步往 agents.json append, 删频道却没删回来
+            //   → agents.json 里残留孤儿 agent, 重启后 loadLocalSubAgents 还能读到这些 — 看起来像"删不掉"
+            //   修法: 用 channel.agentId 找, 同步从 agents.json 删一条
+            try {
+                const agentsPath = path.join(process.env.HOME || '/tmp', '.bolloon', 'agents', 'agents.json');
+                const raw = await fs.readFile(agentsPath, 'utf-8').catch(() => '');
+                if (raw) {
+                    let arr = [];
+                    try {
+                        arr = JSON.parse(raw);
+                    }
+                    catch { }
+                    if (!Array.isArray(arr))
+                        arr = [];
+                    const before = arr.length;
+                    arr = arr.filter(a => !(a && (a.id === channel.agentId || a.channelId === channelId)));
+                    if (arr.length !== before) {
+                        await fs.writeFile(agentsPath, JSON.stringify(arr, null, 2), 'utf-8');
+                        console.log(`[删除频道] agents.json 清掉 ${before - arr.length} 条 orphan agent (channel=${channelId})`);
+                    }
+                }
+            }
+            catch (e) {
+                console.warn('[删除频道] 清理 agents.json 失败 (非致命):', e?.message?.slice(0, 120));
+            }
             res.json({ ok: true });
         }
         catch (err) {
@@ -4665,6 +5009,8 @@ export async function createWebServer(port = 3000, options = {}) {
     });
     // 2026-07-06: judgments / self-improve / permission-mode 路由抽到 ./routes-judgments.ts
     registerJudgmentsRoutes(app);
+    // 2026-07-15: judgeness · hearth 主路由 + peer 4 类写 API
+    registerHearthRoutes(app);
     // ==================== Self-Improve 端点 ====================
     // 查看当前策略 (白名单 / 黑名单)
     app.get('/api/self-improve/policy', async (_req, res) => {

package/dist/web/ui/message-renderer.js

@@ -60,7 +60,7 @@ function escapeHtml(s) {
     "'": "'"
   })[c]);
 }
-function addMessage(content, type, save = true, container, usedJudgmentIds = [], ctx = { messagesEl: null, messagesContainers: /* @__PURE__ */ new Map(), currentChannelId: null }) {
+function addMessage(content, type, save = true, container, usedJudgmentIds = [], ctx = { messagesEl: null, messagesContainers: /* @__PURE__ */ new Map(), currentChannelId: null }, timestamp) {
   const messagesEl = ctx.messagesEl || (typeof document !== "undefined" ? document.getElementById("messages") : null);
   const messagesContainers = ctx.messagesContainers || /* @__PURE__ */ new Map();
   const currentChannelId = ctx.currentChannelId;
@@ -129,9 +129,20 @@ function addMessage(content, type, save = true, container, usedJudgmentIds = [],
     return;
   }
   const rawContent = segments.filter((s) => s.type === "text" || s.type === "final").map((s) => s.content || "").join("\n");
+  let timeLabel = "";
+  try {
+    if (timestamp !== void 0 && timestamp !== null) {
+      const d = timestamp instanceof Date ? timestamp : new Date(timestamp);
+      if (!isNaN(d.getTime())) {
+        timeLabel = d.toLocaleTimeString("zh-CN", { hour: "2-digit", minute: "2-digit" });
+      }
+    }
+  } catch {
+  }
+  if (!timeLabel) timeLabel = (/* @__PURE__ */ new Date()).toLocaleTimeString("zh-CN", { hour: "2-digit", minute: "2-digit" });
   const time = document.createElement("div");
   time.className = "time";
-  time.textContent = (/* @__PURE__ */ new Date()).toLocaleTimeString("zh-CN", { hour: "2-digit", minute: "2-digit" });
+  time.textContent = timeLabel;
   if (type === "ai") {
     div.appendChild(buildMessageActions(div, rawContent, ctx));
   }

package/dist/web/util/dual-mode.js

@@ -0,0 +1,87 @@
+/**
+ * judgeness / dual-mode.ts
+ *
+ * Accept 协商 + JSON-LD 生成.
+ *   - 默认 `application/ld+json` 给 agent (头等公民)
+ *   - `text/html` 或 `?view=human` 给人类
+ *
+ * 复用 bolloon 现有 src/web/util/safe-name.ts (兜底防 undefined/null/NaN 渲染).
+ */
+const HEARTH_LD_CONTEXT = 'https://judgeness.bolloon.com/schema/v1';
+/** 最简 UA 检测: 已知 agent 名 / 字符串里含 'bot'/'agent' 视为 agent.
+ *  防御期 placeholder — 反攻期可接 allowlist UA detection. */
+function isLikelyAgentUA(ua) {
+    if (!ua)
+        return false;
+    const s = ua.toLowerCase();
+    return /bot|agent|crawler|spider/.test(s);
+}
+export function negotiateAudience(input) {
+    // ?view=human 显式
+    const v = input.query?.['view'];
+    if (typeof v === 'string' && v.toLowerCase() === 'human')
+        return 'human';
+    const accept = (input.accept ?? '').toLowerCase();
+    // text/html 优先
+    if (accept.includes('text/html') && !accept.includes('application/ld+json'))
+        return 'human';
+    // UA 启发式
+    if (isLikelyAgentUA(input.userAgent) && !accept.includes('text/html'))
+        return 'agent';
+    // 缺省: agent (头等公民)
+    return 'agent';
+}
+export function descriptionToJsonLd(d) {
+    return {
+        '@context': HEARTH_LD_CONTEXT,
+        '@type': 'JudgenessDescription',
+        '@id': `urn:judgeness:description:${d.descriptionId}`,
+        name: `Description ${d.descriptionId}`,
+        description: `Judgment ref: ${d.judgmentRef}`,
+        facets: d.facets,
+        scope: d.scope,
+        visibility: d.visibility,
+        openState: d.openState,
+        by: d.by,
+        createdAt: d.createdAt,
+    };
+}
+// ---------------------------------------------------------------------------
+// HTML 渲染 (人类视图, 极简, 防 XSS escape)
+// ---------------------------------------------------------------------------
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+export function renderHumanHtml(title, body) {
+    return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head><body><h1>${escapeHtml(title)}</h1>${body}</body></html>`;
+}
+export function descriptionToHumanHtml(d) {
+    const facetsLines = d.facets
+        ? Object.entries(d.facets)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `<li>${escapeHtml(k)}: ${escapeHtml(String(v))}</li>`)
+            .join('')
+        : '<li>(no facets visible at your access level)</li>';
+    const body = `<section><h2>Description ${escapeHtml(d.descriptionId)}</h2><p>Judgment ref: <code>${escapeHtml(d.judgmentRef)}</code></p><ul>${facetsLines}</ul><p>visibility: <strong>${escapeHtml(d.visibility)}</strong> · openState: <strong>${escapeHtml(d.openState)}</strong></p></section>`;
+    return renderHumanHtml(`Hearth · ${d.descriptionId}`, body);
+}
+export function dualRender(input, humanHtml, jsonLdProducer) {
+    const aud = negotiateAudience(input);
+    if (aud === 'human') {
+        return { status: 200, contentType: 'text/html; charset=utf-8', body: humanHtml() };
+    }
+    const obj = jsonLdProducer();
+    return {
+        status: 200,
+        contentType: 'application/ld+json; charset=utf-8',
+        body: JSON.stringify(obj),
+    };
+}
+export function dualRenderList(input, humanHtmlProducer, jsonLdProducer) {
+    return dualRender(input, humanHtmlProducer, () => jsonLdProducer());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli-entry.js",
@@ -48,7 +48,7 @@
     "src/constraint-runtime"
   ],
   "dependencies": {
-    "@bolloon/bolloon-agent": "^0.3.1",
+    "@bolloon/bolloon-agent": "^0.3.3",
     "@bolloon/constraint-runtime": "0.1.0",
     "@capacitor/core": "^8.4.1",
     "@capacitor/ios": "^8.4.1",