@bolloon/bolloon-agent 0.4.22 → 0.4.24

package/dist/llm/pi-ai.js

@@ -303,6 +303,28 @@ export class PiAIModel {
         };
         return modelMap[this.provider];
     }
+    /**
+     * 2026-09-15: 出网前把 messages 规整成 wire 形状.
+     *
+     * 背景 (真跑复现 + 逐项对照, 见 wiki log 2026-09-15): DeepSeek 思考模式 (deepseek-v4-*)
+     * 在**请求带 tools** 时, 任何 assistant 消息缺 `reasoning_content` 字段 →
+     * HTTP 400 "The `reasoning_content` in the thinking mode must be passed back to the API".
+     * 复现: 同一个 17 条消息的真实请求体, 不带 tools → 200; 带上 tools → 400;
+     *       给每条 assistant 补 `reasoning_content:""` → 带 tools 也 200。
+     * 表现: 多轮工具循环 (第 2 轮起) 直接断, 用户看到 "AI 服务调用失败"。
+     *
+     * 处置: 只对 deepseek 生效 (唯一实测过的 provider); 有原文用原文, 没有就补空串 —
+     *   空串已被官方接受, 且不改变语义 (思维链不是给模型看的历史内容)。
+     * 其他 provider 原样透传 (OpenAI 系对未知字段更敏感, 不做无证据的改动)。
+     */
+    prepareWireMessages(messages) {
+        const echoReasoning = this.provider === 'deepseek';
+        if (!echoReasoning)
+            return messages;
+        return messages.map((m) => m.role === 'assistant'
+            ? { role: 'assistant', content: m.content ?? '', reasoning_content: m.reasoningContent ?? '' }
+            : m);
+    }
     async callOpenAI(messages, temperature, maxTokens, signal, tools) {
         const apiKey = this.getApiKey();
         if (!apiKey) {
@@ -310,7 +332,7 @@ export class PiAIModel {
         }
         const requestBody = {
             model: this.mapModel(),
-            messages,
+            messages: this.prepareWireMessages(messages),
             temperature,
             max_tokens: maxTokens
         };
@@ -370,6 +392,15 @@ export class PiAIModel {
                 const errBody = await body.text().catch(() => '(no body)');
                 console.log(`[pi-ai DEBUG] OpenAI 错误 ${statusCode}: ${String(errBody).slice(0, 500)}`);
                 console.log(`[pi-ai DEBUG] 请求体: model=${requestBody.model}, messages=${requestBody.messages?.length}, max_tokens=${requestBody.max_tokens}, baseUrl=${this.getBaseUrl()}`);
+                if (process.env.BOLLOON_DUMP_BODY === '1') {
+                    try {
+                        const fsx = await import('fs');
+                        const p = `/tmp/bolloon-req-${Date.now()}.json`;
+                        fsx.writeFileSync(p, JSON.stringify(requestBody, null, 2));
+                        console.log(`[pi-ai DEBUG] 失败请求体已落盘: ${p}`);
+                    }
+                    catch { /* 调试用, 失败忽略 */ }
+                }
                 retryAgent?.destroy().catch(() => { });
                 throw new Error(`OpenAI API error: ${statusCode} ${String(errBody).slice(0, 300)}`);
             }
@@ -378,6 +409,8 @@ export class PiAIModel {
             const choice = data.choices?.[0];
             const content = choice?.message?.content || '';
             const toolCalls = choice?.message?.tool_calls;
+            // 2026-09-15: 思考模式思维链 — 原样存回 history, 下一轮必须回带 (见 prepareWireMessages)
+            const reasoningContent = choice?.message?.reasoning_content || undefined;
             lastFinishReason = choice?.finish_reason || '';
             // Bug 7: tool_calls 存在时不走重试 — LLM 选工具时 content 空是合法的
             if (content || (toolCalls && toolCalls.length > 0)) {
@@ -388,7 +421,7 @@ export class PiAIModel {
                 const promptBytes = JSON.stringify(messages).length;
                 console.log(`[pi-ai timing] total=${_tAfter - _t0}ms attempt=${attempt + 1} fetch=${_tResp - _tFetch}ms parse=${_tParse - _tResp}ms reply=${content.length}B toolCalls=${toolCalls?.length ?? 0} model=${this.mapModel()} prompt=${promptBytes}B`);
                 retryAgent?.destroy().catch(() => { });
-                return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined };
+                return { reply: content, toolCalls: toolCalls && toolCalls.length > 0 ? toolCalls : undefined, reasoningContent };
             }
             console.warn(`[pi-ai] attempt ${attempt + 1}/3: 空 content (finish_reason=${lastFinishReason}), 退避 1.5s 重试`);
             const _tSleep = Date.now();

package/dist/network/agent-network.js

@@ -10,6 +10,33 @@ const RELAY_RETRY_INTERVAL = 30000;
 const MAX_RELAY_HOPS = 3;
 const MESSAGE_TIMESTAMP_TOLERANCE = 24 * 60 * 60 * 1000;
 const SIGNED_MESSAGE_TYPES = ['task', 'response', 'discovery', 'address_broadcast'];
+/**
+ * 2026-09-15: did:key:z6Mk… 与 Ed25519 公钥字节是否一致。
+ *
+ * DID 由公钥派生 (did:key 规范: multibase base58btc of 0xed01 || rawKey), 所以首次接触时
+ * 自携公钥**无法伪造**: 冒充者换了公钥就解码不出同一个 DID。
+ * 返回: true 一致 / false 不一致 (疑似冒充) / null 非 did:key 形态 (无法判定, 不阻断, 交给签名验证)。
+ */
+export async function didKeyMatchesPublicKey(did, publicKeyHex) {
+    if (!/^did:key:z/.test(did))
+        return null;
+    try {
+        const { base58btc } = await import('multiformats/bases/base58');
+        const decoded = base58btc.decode(did.slice('did:key:'.length));
+        // 34 字节 = 2 字节 multicodec 前缀 (0xed01 = ed25519-pub) + 32 字节公钥
+        if (decoded.length !== 34)
+            return false;
+        if (decoded[0] !== 0xed || decoded[1] !== 0x01)
+            return false;
+        const claimed = Buffer.from(publicKeyHex, 'hex');
+        if (claimed.length !== 32)
+            return false;
+        return Buffer.compare(Buffer.from(decoded.slice(2)), claimed) === 0;
+    }
+    catch {
+        return null; // 解码失败 → 不判定 (不当成冒充, 也不放行: 签名仍要过)
+    }
+}
 export class AgentRegistry {
     agents = new Map();
     registryPath;
@@ -192,6 +219,7 @@ export class AgentRegistry {
             return null;
         }
         const relayAddr = p2pNetwork.getRelayAddress?.() || null;
+        const ownPublicKeyHex = Buffer.from(this.keyPair.publicKey).toString('hex');
         const broadcastData = JSON.stringify({
             type: 'address_broadcast',
             from: this.keyPair.did,
@@ -200,6 +228,7 @@ export class AgentRegistry {
             multiaddrs: this.ownEndpoint.multiaddrs,
             relayAddr: relayAddr || undefined,
             canRelay: relayAddr ? true : false,
+            publicKey: ownPublicKeyHex,
             timestamp: now
         });
         const signature = await this.signMessage(broadcastData);
@@ -213,6 +242,7 @@ export class AgentRegistry {
             multiaddrs: this.ownEndpoint.multiaddrs,
             relayAddr: relayAddr || undefined,
             canRelay: relayAddr ? true : false,
+            publicKey: ownPublicKeyHex,
             timestamp: now,
             signature: Buffer.from(signature).toString('hex')
         };
@@ -237,10 +267,35 @@ export class AgentRegistry {
             multiaddrs: broadcast.multiaddrs,
             relayAddr: broadcast.relayAddr,
             canRelay: broadcast.canRelay,
+            publicKey: broadcast.publicKey,
             timestamp: broadcast.timestamp
         });
         const signature = Buffer.from(broadcast.signature, 'hex');
-        const isValid = await this.verifySignature(broadcast.from, broadcastData, signature);
+        const known = this.agents.get(broadcast.from);
+        // 2026-09-15: 首次接触 (全球化去中心网络里全是陌生人) —— 原来只认「registry 里已有的公钥」,
+        //   陌生人第一次广播必然验签失败 → 广播被丢弃 → 陌生人永远发现不了彼此 (入网文档 §7 的链路实际不通).
+        //   现在: 未知 DID 时用广播自带 publicKey 自证 (TOFU: 首次接触信任自携公钥);
+        //   did:key 额外做 DID↔公钥 派生一致性检查 (DID 本身就是公钥, 自携公钥无法伪造).
+        let verifyKeyHex = known?.publicKey || undefined;
+        if (!verifyKeyHex) {
+            const claimed = String(broadcast.publicKey || '');
+            if (!claimed) {
+                console.warn(`[Registry] Unknown agent ${broadcast.from.substring(0, 20)}… 且广播未携带 publicKey → 无法验证, 拒收`);
+                return false;
+            }
+            const binding = await didKeyMatchesPublicKey(broadcast.from, claimed);
+            if (binding === false) {
+                console.warn(`[Registry] did:key 与自带公钥不匹配 (疑似冒充) from=${broadcast.from.substring(0, 24)}… → 拒收`);
+                return false;
+            }
+            verifyKeyHex = claimed;
+        }
+        else if (broadcast.publicKey && broadcast.publicKey !== verifyKeyHex) {
+            // 已认识这个 DID, 却报出另一把公钥 → 身份接管尝试, 拒收 (不覆盖已存公钥)
+            console.warn(`[Registry] ${broadcast.from.substring(0, 20)}… 广播的公钥与已知公钥不一致 → 拒收 (不覆盖)`);
+            return false;
+        }
+        const isValid = await this.verifySignatureWithKey(broadcast.from, verifyKeyHex, broadcastData, signature);
         if (!isValid) {
             console.warn(`[Registry] Invalid broadcast signature from ${broadcast.from.substring(0, 20)}`);
             return false;
@@ -253,7 +308,9 @@ export class AgentRegistry {
             registeredAt: Date.now(),
             lastSeen: broadcast.timestamp,
             lastBroadcast: 0,
-            publicKey: Buffer.from(this.keyPair.publicKey).toString('hex'),
+            // 2026-09-15 修复: 原来写的是**自己**的公钥 (this.keyPair.publicKey) →
+            //   对端后续任何签名消息都验不过 (拿我方公钥去验对方签名), 属于把对端身份写坏.
+            publicKey: verifyKeyHex,
             relayAddr: broadcast.relayAddr,
             canRelay: broadcast.canRelay
         };
@@ -261,15 +318,30 @@ export class AgentRegistry {
         if (existing) {
             entry.registeredAt = existing.registeredAt;
             entry.lastBroadcast = existing.lastBroadcast;
-            if (!existing.publicKey) {
-                existing.publicKey = entry.publicKey;
-            }
+            if (existing.publicKey)
+                entry.publicKey = existing.publicKey; // 已有公钥永不覆盖
         }
         this.agents.set(broadcast.from, entry);
         this.saveRegistry();
-        console.log(`[Registry] Verified broadcast from: ${broadcast.name} (${broadcast.from.substring(0, 20)}...) ${broadcast.canRelay ? '[Relay Capable]' : ''}`);
+        console.log(`[Registry] Verified broadcast from: ${broadcast.name} (${broadcast.from.substring(0, 20)}...) ${broadcast.canRelay ? '[Relay Capable]' : ''}${known ? '' : ' [首次接触 TOFU]'}`);
         return true;
     }
+    /** 用给定公钥 (hex) 验签 — 首次接触路径用 (未知 DID 时 registry 里没公钥) */
+    async verifySignatureWithKey(did, publicKeyHex, data, signature) {
+        try {
+            const publicKey = Buffer.from(publicKeyHex, 'hex');
+            if (publicKey.length !== 32) {
+                console.warn(`[Registry] publicKey 长度非法 (${publicKey.length} 字节, 期望 32): ${did.substring(0, 20)}…`);
+                return false;
+            }
+            const keyPair = { privateKey: new Uint8Array(32), publicKey, did };
+            return await KeyManager.verify(keyPair, new TextEncoder().encode(data), signature);
+        }
+        catch (e) {
+            console.warn(`[Registry] Verification with provided key failed:`, e);
+            return false;
+        }
+    }
     async createSignedMessage(type, payload) {
         if (!this.keyPair || !this.ownEndpoint)
             return null;

package/dist/web/agent-delegate-server.js

@@ -17,9 +17,10 @@
  */
 import express from 'express';
 import { buildAgentDelegateRequest, buildAgentResponse, buildManifestPayload, parseFrame, setLocalManifest, getLocalManifest, getRemoteManifests, cacheRemoteManifest, pickAgent, } from '../agents/agent-manifest-protocol.js';
-export function createAgentDelegateApp(transport) {
+export function createAgentDelegateApp(transport, options = {}) {
     const app = express();
     app.use(express.json({ limit: '2mb' }));
+    const executeTimeoutMs = options.executeTimeoutMs ?? 60_000;
     // ---- 本地 manifest ----
     app.get('/api/agent/local-manifest', (_req, res) => {
         res.json(getLocalManifest());
@@ -81,7 +82,10 @@ export function createAgentDelegateApp(transport) {
             }
             res.json({
                 ok: true,
-                targetAgent: targetAgent || { id: f.payload.delegatedTo, capabilities: [capability], status: 'active', name: f.payload.delegatedTo },
+                // 2026-09-15: 没缓存到对端 manifest 就如实给 null —— 旧版会编一个
+                // 「capabilities:[capability], name:<id>」的假目标, 让人以为已经知道对端是谁。
+                targetAgent: targetAgent || null,
+                targetAgentKnown: !!targetAgent,
                 response: f.payload,
             });
         }
@@ -104,18 +108,60 @@ export function createAgentDelegateApp(transport) {
             return null; // 不需要回包
         }
         if (f.type === 'agent_delegate') {
-            // 路由到本地匹配 agent
             const req = f.payload;
+            const capability = String(req?.capability || '');
+            // 2026-09-15: 严格按文档 §6 / §9 —— 只认 capabilities 含该能力且 active 的 agent。
+            //   旧实现 `|| local.agents[0]` 会把不匹配的指令塞给任意一个本地 agent,
+            //   与「pick 404 = 没有匹配能力」的语义自相矛盾。
             const local = getLocalManifest();
-            const target = local.agents.find((a) => a.capabilities.includes(req.capability) && a.status === 'active') || local.agents[0];
-            if (!target)
-                return buildAgentResponse({ ok: false, delegatedTo: 'none', summary: 'no local agent available' });
-            return buildAgentResponse({
-                ok: true,
-                delegatedTo: target.id,
-                resultCid: `mock-${Date.now()}`,
-                summary: `[${target.name}] 已处理任务: ${req.instruction?.substring(0, 30)}`,
-            });
+            const target = local.agents.find((a) => a.capabilities.includes(capability) && a.status === 'active');
+            if (!target) {
+                return buildAgentResponse({
+                    ok: false,
+                    delegatedTo: 'none',
+                    summary: `no local agent available for capability '${capability}'`,
+                    error: 'no-capability-match',
+                });
+            }
+            // 匹配到了, 但本节点没接执行器 → 如实说"干不了", 不假签收
+            if (!options.execute) {
+                return buildAgentResponse({
+                    ok: false,
+                    delegatedTo: target.id,
+                    summary: `matched agent '${target.name}' but this node has no executor wired`,
+                    error: 'no-executor',
+                });
+            }
+            try {
+                const raced = await Promise.race([
+                    options.execute({
+                        capability,
+                        instruction: String(req?.instruction || ''),
+                        docPath: req?.docPath ? String(req.docPath) : undefined,
+                        docContent: req?.docContent ? String(req.docContent) : undefined,
+                        fromAgentId: req?.fromAgentId ? String(req.fromAgentId) : undefined,
+                        fromPublicKey,
+                        targetAgentId: target.id,
+                        targetAgentName: target.name,
+                    }),
+                    new Promise((resolve) => setTimeout(() => resolve({ ok: false, summary: `executor timed out after ${executeTimeoutMs}ms`, error: 'executor-timeout' }), executeTimeoutMs)),
+                ]);
+                return buildAgentResponse({
+                    ok: !!raced.ok,
+                    delegatedTo: target.id,
+                    resultCid: raced.resultCid,
+                    summary: String(raced.summary || '').slice(0, 4000),
+                    error: raced.error,
+                });
+            }
+            catch (e) {
+                return buildAgentResponse({
+                    ok: false,
+                    delegatedTo: target.id,
+                    summary: `executor threw: ${String(e?.message || e).slice(0, 300)}`,
+                    error: 'executor-error',
+                });
+            }
         }
         return null;
     });

package/dist/web/mobile-agent.js

@@ -160,11 +160,205 @@ async function applyLlmConfigToBridge() {
     }
     catch { /* 注入失败不阻塞本地执行 */ }
 }
-// ============ 本地执行 (Kotlin AgentRuntime / 内置规则) ============
+// ============ 手机端「读入网说明 → 入网」(2026-09-15) ============
+//
+// 背景: 手机端「一键入网」发出的口令是 `read https://bolloon.cn/bolloon-gateway-join.md`
+// (mobile.js DEFAULT_JOIN_PROMPT), 但手机侧此前只会走到「已收到: "…"」的兜底回复 ——
+// 也就是说这句话在手机上是**空转**的: 既不读文档, 也不入网。
+// 现在手机自己就能走完: 读说明(校验 frontmatter) → 本机 DID → 服务登记
+// (桌面可达则登记进桌面的网络 registry, 否则本机登记并如实说明) → P2P 公告(尽力) → 落盘入网态。
+// 桌面不可达不是失败: 手机是自治节点; 但每一步都如实报 ok/note, 不假装入网。
+/** 入网口令识别 (与 mobile.js 的默认 prompt 同源) */
+export const MOBILE_JOIN_DOC_RE = /read\s+(https?:\/\/\S*bolloon-gateway-join\.md)/i;
+const MOBILE_JOIN_STATE_KEY = 'bolloon_gateway_join';
+export function detectJoinDocUrl(text) {
+    const m = MOBILE_JOIN_DOC_RE.exec(String(text || ''));
+    return m ? m[1] : null;
+}
+/** 极简 SKILL.md frontmatter 解析 (只认 name/version) */
+function parseFm(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''));
+    if (!m)
+        return {};
+    const out = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim());
+        if (!kv)
+            continue;
+        const k = kv[1].toLowerCase();
+        if (k === 'name')
+            out.name = kv[2].trim().replace(/^["']|["']$/g, '');
+        if (k === 'version')
+            out.version = kv[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+}
+export async function getMobileJoinState() {
+    try {
+        const raw = typeof localStorage !== 'undefined' ? localStorage.getItem(MOBILE_JOIN_STATE_KEY) : null;
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveMobileJoinState(s) {
+    try {
+        if (typeof localStorage !== 'undefined')
+            localStorage.setItem(MOBILE_JOIN_STATE_KEY, JSON.stringify(s));
+    }
+    catch { /* 忽略 */ }
+}
+/**
+ * 按入网说明文档入网 (手机端自足执行)。
+ * opts.desktopBaseUrl 可注入 (测试用); 默认读 mobile-gateway 持久化的桌面基址。
+ */
+export async function joinGatewayFromDoc(docUrl, opts = {}) {
+    const f = opts.fetchImpl || fetch;
+    const steps = [];
+    const url = String(docUrl || '').trim();
+    if (!/^https?:\/\//i.test(url)) {
+        return { ok: false, docUrl: url, steps, error: `入网说明地址必须是 http(s) URL (收到: ${url.slice(0, 60)})` };
+    }
+    // ① 读入网说明 + 校验
+    let docVersion;
+    try {
+        const r = await f(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 15000) });
+        if (!r.ok) {
+            steps.push({ step: '读入网说明', ok: false, note: `文档不可达 (HTTP ${r.status})` });
+            return { ok: false, docUrl: url, steps, error: `入网说明不可达 (HTTP ${r.status})` };
+        }
+        const text = await r.text();
+        const fm = parseFm(text);
+        if (fm.name !== 'bolloon-gateway-join' && !/加入网关|bolloon-gateway-join/.test(text)) {
+            steps.push({ step: '读入网说明', ok: false, note: `不是 Bolloon 入网说明 (name=${fm.name || '无'})` });
+            return { ok: false, docUrl: url, steps, error: '该文档不是 Bolloon 网关入网说明, 拒绝据此入网' };
+        }
+        docVersion = fm.version;
+        steps.push({ step: '读入网说明', ok: true, note: `${fm.name || 'bolloon-gateway-join'} v${fm.version || '?'} (${text.length} 字符)` });
+    }
+    catch (e) {
+        steps.push({ step: '读入网说明', ok: false, note: `读取失败: ${String(e?.message || e).slice(0, 120)}` });
+        return { ok: false, docUrl: url, steps, error: `入网说明读取失败: ${String(e?.message || e).slice(0, 120)}` };
+    }
+    // ② 本机 DID (手机端身份层; 可注入, 便于测试/无 IndexedDB 环境)
+    let did = String(opts.did || '');
+    if (did) {
+        steps.push({ step: 'DID 身份', ok: true, note: `${did} (注入身份)` });
+    }
+    else {
+        try {
+            const id = await ensureIdentity();
+            did = id.did;
+            steps.push({ step: 'DID 身份', ok: true, note: `${did} (手机端本机生成)` });
+        }
+        catch (e) {
+            steps.push({ step: 'DID 身份', ok: false, note: String(e?.message || e).slice(0, 120) });
+            return { ok: false, docUrl: url, docVersion, steps, error: '手机端 DID 生成失败' };
+        }
+    }
+    const name = String(opts.name || 'phone-agent');
+    const capabilities = ['chat', 'gateway-join'];
+    // ③ 服务登记: 桌面可达 → 登记进桌面(网络) registry; 否则本机登记并如实说明
+    let desktopBase = String(opts.desktopBaseUrl ?? '');
+    if (opts.desktopBaseUrl === undefined) {
+        try {
+            const g = await import('./mobile-gateway.js');
+            desktopBase = String(g.getDesktopBaseUrl() || '');
+        }
+        catch {
+            desktopBase = '';
+        }
+    }
+    desktopBase = desktopBase.replace(/\/+$/, '');
+    let registeredOn = 'local';
+    if (desktopBase) {
+        try {
+            const r = await f(`${desktopBase}/api/registry/register`, {
+                method: 'POST', headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    agentId: did, name, wallet: '',
+                    service: { name: 'chat', description: '手机端智能体 (自足节点)', price: { amount: '0', currency: 'USDC', per: 'task' }, endpoint: '' },
+                    capabilities,
+                }),
+                signal: AbortSignal.timeout(opts.timeoutMs ?? 15000),
+            });
+            if (r.ok) {
+                registeredOn = 'desktop';
+                steps.push({ step: '服务登记', ok: true, note: `已登记进电脑端网络 registry (${desktopBase}) —— 网络内其他智能体可按能力发现我` });
+            }
+            else {
+                steps.push({ step: '服务登记', ok: false, note: `电脑端 registry 拒绝 (HTTP ${r.status}); 已改为本机登记` });
+            }
+        }
+        catch (e) {
+            steps.push({ step: '服务登记', ok: false, note: `电脑端不可达 (${String(e?.message || e).slice(0, 80)}); 已改为本机登记` });
+        }
+    }
+    else {
+        steps.push({ step: '服务登记', ok: true, note: '未配置电脑端基址 → 只在本机登记 (手机是自治节点; 设置里填电脑端地址可登记进网络 registry)' });
+    }
+    // ④ P2P 公告 (尽力): 让已连接的对端知道本机服务; 没连上不是入网失败
+    try {
+        const p2p = await import('./mobile-p2p.js');
+        let peers = 0;
+        try {
+            peers = (p2p.getConnectedPeers?.() || []).length;
+        }
+        catch {
+            peers = 0;
+        }
+        if (peers > 0 && typeof p2p.sendMobileP2PMessage === 'function') {
+            const okAnnounce = await p2p.sendMobileP2PMessage('*', 'registry.register', JSON.stringify({ agent_id: did, name, capabilities }), did);
+            steps.push({ step: 'P2P 公告', ok: !!okAnnounce, note: okAnnounce ? `已向 ${peers} 个对端广播本机声明` : `广播失败 (对端 ${peers} 个)` });
+        }
+        else {
+            steps.push({ step: 'P2P 公告', ok: false, note: '当前无已连接对端 (浏览器/未连电脑端时正常) — 本机声明已就绪, 连上即生效' });
+        }
+    }
+    catch (e) {
+        steps.push({ step: 'P2P 公告', ok: false, note: `P2P 层不可用: ${String(e?.message || e).slice(0, 80)}` });
+    }
+    // ⑤ 落盘入网态 (幂等: 同 url 再次入网覆盖时间戳)
+    saveMobileJoinState({ url, did, name, capabilities, docVersion, registeredOn, desktopBaseUrl: desktopBase || undefined, joinedAt: new Date().toISOString() });
+    const state = await getMobileJoinState();
+    steps.push({ step: '落盘入网态', ok: !!state?.did, note: `localStorage:${MOBILE_JOIN_STATE_KEY}` });
+    return { ok: true, docUrl: url, docVersion, did, steps };
+}
+/** 把入网结果渲染成给用户看的回复 (与桌面工具的 steps 汇报风格一致) */
+export function formatMobileJoinResult(r) {
+    if (!r.ok) {
+        return `❌ 入网失败: ${r.error || '未知原因'}\n\n${r.steps.map((s) => `${s.ok ? '✓' : '✗'} ${s.step}: ${s.note}`).join('\n')}`;
+    }
+    const s = r.steps.find((x) => x.step === '服务登记');
+    return [
+        '✅ 已加入全球智能体网络 (手机端自足执行)',
+        '',
+        `DID: ${r.did}`,
+        `入网说明: v${r.docVersion || '?'} (${r.docUrl})`,
+        s ? `登记: ${s.note}` : '',
+        '',
+        ...r.steps.map((x) => `${x.ok ? '✓' : '✗'} ${x.step}: ${x.note}`),
+        '',
+        '用「网络 → Agent 网络」可查看成员; 设置里填电脑端地址可把本机登记进网络 registry。',
+    ].filter((l) => l !== '').join('\n');
+}
+// ============ 本地执行 (Kotlin AgentRuntime / 离线兜底) ============
 /** 手机端本地 agent 执行 (优先 Kotlin, 离线内置规则) */
 export async function runLocalAgent(goal) {
     const win = typeof window !== 'undefined' ? window : null;
     const cap = win?.Capacitor;
+    // 2026-09-15: 「读入网说明 → 入网」在手机端本地自足执行 (先于 Kotlin 桥: 原生工具集里没有入网能力,
+    //   交给它只会得到空转回复)。这样浏览器 / WebView / 真机三种环境行为一致。
+    const joinDocUrl = detectJoinDocUrl(goal);
+    if (joinDocUrl) {
+        _lastWorklog = [`🧩 识别为入网口令: ${joinDocUrl}`];
+        const r = await joinGatewayFromDoc(joinDocUrl).catch((e) => ({
+            ok: false, docUrl: joinDocUrl, steps: [{ step: '入网', ok: false, note: String(e?.message || e).slice(0, 120) }], error: String(e?.message || e),
+        }));
+        _lastWorklog = [..._lastWorklog, ...r.steps.map((s) => `${s.ok ? '✓' : '✗'} ${s.step}: ${s.note}`)];
+        return formatMobileJoinResult(r);
+    }
     const bridge = cap && cap.Plugins && cap.Plugins.RokidBridge;
     if (bridge && cap.isNativePlatform?.()) {
         try {