libp2p-mesh 2026.6.19 → 2026.6.20

package/README.md

@@ -75,6 +75,159 @@ The generated config shape is:
 }
 ```
 
+## 安装后配置流程
+
+推荐用户安装插件后按下面顺序配置。所有配置都通过 CLI 完成，不需要手动打开 `openclaw.json`。
+
+### 1. 安装或更新插件
+
+```bash
+openclaw plugins update libp2p-mesh@latest
+```
+
+如果是首次安装，也可以使用：
+
+```bash
+openclaw install libp2p-mesh
+```
+
+### 2. 运行网络和入站目标配置向导
+
+```bash
+openclaw libp2p-mesh setup
+```
+
+这个向导会写入：
+
+```text
+plugins.entries["libp2p-mesh"].config
+```
+
+不会写入 `channels["libp2p-mesh"]`。常见选择：
+
+- 同一局域网测试：选择 LAN / mDNS。
+- 跨网络或需要 relay：选择 bootstrap / relay 相关模式。
+- 需要把收到的 P2P 消息投递到飞书、QQ、Telegram 等 channel：配置 `inboundTargets`。
+- 暂时只需要工具能力、不接收消息：选择禁用入站投递，写入 `inboundTargets: []`。
+
+入站目标示例：
+
+```json
+{
+  "id": "feishu-main",
+  "channel": "feishu",
+  "target": "user:ou_xxx"
+}
+```
+
+QQ 单聊示例：
+
+```json
+{
+  "id": "qqbot-main",
+  "channel": "qqbot",
+  "target": "user:<senderId>"
+}
+```
+
+其中 `<senderId>` 可以从 QQ channel 日志里的 `senderId` 取得。
+
+### 3. 一键安装固定 Agent 提示词
+
+```bash
+openclaw libp2p-mesh prompt install
+```
+
+该命令会把内置的 P2P 中继助手规则写入：
+
+```text
+~/.openclaw/workspace/AGENTS.md
+```
+
+它不会覆盖整个文件，只维护下面两个 marker 之间的区块：
+
+```md
+<!-- libp2p-mesh:prompt:start -->
+# P2P 中继助手规则
+...
+<!-- libp2p-mesh:prompt:end -->
+```
+
+如果区块已经存在，命令会询问是否更新到插件内置的最新版。
+
+### 4. 可选：配置用户公开属性
+
+```bash
+openclaw libp2p-mesh profile
+```
+
+`USER.md` 中的公开 tag 会在 gateway 启动时只读提取，不会写回 `USER.md`。用户手动新增的结构化属性会保存到：
+
+```text
+~/.openclaw/libp2p/user-profile.json
+```
+
+例如：
+
+```json
+{
+  "kind": "structured",
+  "key": "group",
+  "value": "实验室",
+  "label": "实验室",
+  "source": "profile"
+}
+```
+
+之后按属性发送时使用 selector：
+
+```text
+group=实验室
+tag:P2P
+#P2P
+```
+
+`selector` 是发送工具调用时的临时匹配条件，不需要写入配置文件。
+
+### 5. 可选：配置 announce 日志级别
+
+```bash
+openclaw libp2p-mesh debug
+```
+
+推荐保持默认 `summary`。如果排查发现、属性或地址广播问题，可以临时切到 `payload` 查看完整 announce JSON；排查结束后再切回 `summary` 或 `off`。
+
+### 6. 可选：配置远端实例本地标签
+
+```bash
+openclaw libp2p-mesh labels
+```
+
+Labels are private local notes for remote instances you have already discovered. Use them when you want your own grouping to drive sends without asking the remote user to publish that attribute.
+
+### 7. 重启 gateway
+
+完成 `setup`、`prompt install` 或 `profile` 后，重启 gateway 让配置和提示词生效：
+
+```bash
+openclaw gateway restart
+```
+
+或者停止后重新运行：
+
+```bash
+openclaw gateway
+```
+
+启动后可以观察日志：
+
+```text
+[libp2p-mesh] Sent instance announce ... attrs=2
+[libp2p-mesh] Received instance announce ... changed=true
+```
+
+其中 `attrs` 是本次 announce 中携带的用户公开属性数量。
+
 ## Configuration
 
 Use the interactive setup command for first-time configuration and later edits:
@@ -471,7 +624,7 @@ Tools are not configured in `openclaw.json`; they are registered automatically b
 
 `libp2p-mesh` can announce user public attributes with instance route announcements. These attributes help agents find matching OpenClaw instances after those instances have already been discovered through the mesh.
 
-There are two sources:
+There are two public sources:
 
 - `USER.md` tags are extracted read-only at gateway startup. The plugin never edits `USER.md`.
 - `user-profile.json` stores manually managed structured attributes such as group, project, role, skill, or a custom key.
@@ -568,12 +721,54 @@ Remote attributes are cached in plugin-managed instance state under `instance-pe
 }
 ```
 
-Use `p2p_send_user_attribute_message` for attribute-based group messages. Always dry-run first. If the dry run matches targets, call the same tool again immediately with the same selector and `dryRun: false`:
+### Local peer labels
+
+Use local peer labels when you want to classify remote instances privately on this machine:
+
+```bash
+openclaw libp2p-mesh labels
+```
+
+The default labels path is:
+
+```text
+~/.openclaw/libp2p/peer-labels.json
+```
+
+When `OPENCLAW_STATE_DIR` is set:
+
+```text
+$OPENCLAW_STATE_DIR/libp2p/peer-labels.json
+```
+
+Example `peer-labels.json`:
+
+```json
+{
+  "version": 1,
+  "updatedAt": 1782180000000,
+  "peers": {
+    "alice-mac@AQIDBAUGBweI.7a3f9e2b": {
+      "labels": [
+        { "key": "group", "value": "实验室" },
+        { "key": "project", "value": "openclaw" }
+      ]
+    }
+  }
+}
+```
+
+Privacy boundary: `peer-labels.json` is local state for your gateway. It is not announced to peers, not written into remote `instance-peer.json.userPublicAttributes`, and not visible to the remote user through the mesh protocol. Public attributes in `USER.md` and `user-profile.json` are still broadcast with instance announce messages.
+
+Use `p2p_send_user_attribute_message` for attribute-based group messages. It defaults to public attributes only, equivalent to `scope="public"`. Always dry-run first. If the dry run matches targets, call the same tool again immediately with the same selector, scope, message, and `dryRun: false`.
+
+Public scope matches attributes that remote instances announced from their own `USER.md` or `user-profile.json`:
 
 ```text
 p2p_send_user_attribute_message({
   "selector": "project=openclaw",
   "message": "今晚同步一下进展",
+  "scope": "public",
   "dryRun": true
 })
 ```
@@ -584,11 +779,34 @@ After a matching dry run:
 p2p_send_user_attribute_message({
   "selector": "project=openclaw",
   "message": "今晚同步一下进展",
+  "scope": "public",
   "dryRun": false
 })
 ```
 
-Selectors use `key=value` for structured profile attributes. Tag matches use `tag:value` or `#value`. Bare selectors such as `实验室` are rejected because they are ambiguous; use `group=实验室` for a structured group or `tag:实验室` for a USER.md tag.
+Local scope, written as `scope="local"` in prompt instructions or `"scope": "local"` in tool JSON, matches only labels from your `peer-labels.json`:
+
+```text
+p2p_send_user_attribute_message({
+  "selector": "group=实验室",
+  "message": "我按本地归类发一个提醒",
+  "scope": "local",
+  "dryRun": true
+})
+```
+
+All scope matches both sources and deduplicates by instance:
+
+```text
+p2p_send_user_attribute_message({
+  "selector": "project=openclaw",
+  "message": "公开属性和本地标签都算",
+  "scope": "all",
+  "dryRun": true
+})
+```
+
+Selectors use `key=value` for structured profile attributes or local labels. Tag matches use `tag:value` or `#value` for public `USER.md` tags. Bare selectors such as `实验室` are rejected because they are ambiguous; use `group=实验室` for a structured group or `tag:实验室` for a USER.md tag.
 
 ```text
 p2p_send_user_attribute_message({

package/dist/src/agent-tools.d.ts

@@ -1,4 +1,7 @@
-import type { DeliveryTargetResult, InstanceRouter, MeshNetwork, UserPublicAttribute } from "./types.js";
+import type { DeliveryTargetResult, InstancePeerRecord, InstanceRouter, LocalPeerLabelAttribute, MeshNetwork, PeerLabelStore } from "./types.js";
+type BuildP2PToolsOptions = {
+    peerLabelStore?: Pick<PeerLabelStore, "listLabels">;
+};
 type SendUserAttributeToolParams = {
     selector?: unknown;
     match?: {
@@ -8,8 +11,9 @@ type SendUserAttributeToolParams = {
     };
     message?: unknown;
     dryRun?: unknown;
+    scope?: unknown;
 };
-export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter): ({
+export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter, options?: BuildP2PToolsOptions): ({
     name: string;
     label: string;
     description: string;
@@ -29,8 +33,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required: string[];
+        anyOf?: undefined;
     };
     execute(_toolCallId: string, params: {
         peerId: string;
@@ -78,8 +84,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required: string[];
+        anyOf?: undefined;
     };
     execute(_toolCallId: string, params: {
         topic: string;
@@ -121,8 +129,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required?: undefined;
+        anyOf?: undefined;
     };
     execute(_toolCallId: string): Promise<{
         content: {
@@ -163,8 +173,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required?: undefined;
+        anyOf?: undefined;
     };
     execute(_toolCallId: string): Promise<{
         content: {
@@ -214,8 +226,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required?: undefined;
+        anyOf?: undefined;
     };
     execute(_toolCallId: string): Promise<{
         content: {
@@ -258,8 +272,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required?: undefined;
+        anyOf?: undefined;
     };
     execute(_toolCallId: string): Promise<{
         content: {
@@ -279,18 +295,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             text: string;
         }[];
         details: {
-            instances: {
+            instances: (InstancePeerRecord & {
                 connected: boolean;
-                instanceId: string;
-                peerId: string;
-                instanceName?: string;
-                multiaddrs: string[];
-                pubkey?: string;
-                userPublicAttributes?: UserPublicAttribute[];
-                lastSeenAt: number;
-                lastAnnouncedAt: number;
-                source: "announce";
-            }[];
+                localLabels: LocalPeerLabelAttribute[];
+            })[];
             count: number;
             initialized?: undefined;
             error?: undefined;
@@ -326,8 +334,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required: string[];
+        anyOf?: undefined;
     };
     execute(_toolCallId: string, params: {
         instanceId: string;
@@ -377,7 +387,7 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
         }[];
         details: {
             found: boolean;
-            route: import("./types.js").InstancePeerRecord;
+            route: InstancePeerRecord;
             initialized?: undefined;
             error?: undefined;
             instanceId?: undefined;
@@ -404,8 +414,10 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
             selector?: undefined;
             match?: undefined;
             dryRun?: undefined;
+            scope?: undefined;
         };
         required: string[];
+        anyOf?: undefined;
     };
     execute(_toolCallId: string, params: {
         instanceId: string;
@@ -521,11 +533,19 @@ export declare function buildP2PTools(mesh: MeshNetwork, router?: InstanceRouter
                 type: "boolean";
                 description: string;
             };
+            scope: {
+                type: "string";
+                enum: string[];
+                description: string;
+            };
             peerId?: undefined;
             topic?: undefined;
             instanceId?: undefined;
         };
         required: string[];
+        anyOf: {
+            required: string[];
+        }[];
     };
     execute(_toolCallId: string, params: SendUserAttributeToolParams): Promise<{
         content: {

package/dist/src/agent-tools.js

@@ -23,7 +23,7 @@ function instanceTargetLabel(target) {
     return `${target.instanceId}${name} -> ${target.peerId}`;
 }
 function formatUserAttributeTargets(targets) {
-    return targets.map((target) => `${instanceTargetLabel(target)} [${attributeLabel(target.matchedAttribute)}]`);
+    return targets.map((target) => `${instanceTargetLabel(target)} [${target.matchSource}:${attributeLabel(target.matchedAttribute)}]`);
 }
 function formatUserAttributeResults(results) {
     return results.map((result) => {
@@ -37,6 +37,78 @@ function formatUserAttributeResults(results) {
         return `${instanceTargetLabel(result)}：${status}`;
     });
 }
+function formatPublicAttribute(attribute) {
+    if (attribute.kind === "tag") {
+        return [
+            "     - kind: tag",
+            `       value: ${attribute.value}`,
+            `       label: ${attribute.label}`,
+            `       source: ${attribute.source}`,
+        ];
+    }
+    return [
+        "     - kind: structured",
+        `       key: ${attribute.key}`,
+        `       value: ${attribute.value}`,
+        `       label: ${attribute.label}`,
+        `       source: ${attribute.source}`,
+    ];
+}
+function formatLocalLabel(label) {
+    return [
+        "     - kind: structured",
+        `       key: ${label.key}`,
+        `       value: ${label.value}`,
+        `       label: ${label.label}`,
+        `       source: ${label.source}`,
+    ];
+}
+function formatInstanceList(rows) {
+    if (rows.length === 0) {
+        return "No OpenClaw instances discovered yet.";
+    }
+    const lines = [`Discovered OpenClaw instances: ${rows.length}`];
+    rows.forEach((entry, index) => {
+        lines.push("", `${index + 1}. ${entry.instanceId}`, `   peerId: ${entry.peerId}`, `   instanceName: ${entry.instanceName ?? "(none)"}`, `   connected: ${entry.connected}`);
+        if ((entry.userPublicAttributes ?? []).length === 0) {
+            lines.push("   userPublicAttributes: none");
+        }
+        else {
+            lines.push("   userPublicAttributes:");
+            for (const attribute of entry.userPublicAttributes ?? []) {
+                lines.push(...formatPublicAttribute(attribute));
+            }
+        }
+        if (entry.localLabels.length === 0) {
+            lines.push("   localLabels: none");
+        }
+        else {
+            lines.push("   localLabels:");
+            for (const label of entry.localLabels) {
+                lines.push(...formatLocalLabel(label));
+            }
+        }
+    });
+    return lines.join("\n");
+}
+function normalizeUserAttributeScope(scope) {
+    if (scope === undefined) {
+        return undefined;
+    }
+    if (scope === "public" || scope === "local" || scope === "all") {
+        return scope;
+    }
+    return undefined;
+}
+function validateUserAttributeScope(scope) {
+    if (scope === undefined ||
+        scope === "public" ||
+        scope === "local" ||
+        scope === "all") {
+        return undefined;
+    }
+    return 'scope must be "public", "local", or "all".';
+}
 function normalizeUserAttributeSelector(selector) {
     const value = typeof selector === "string" ? selector.trim() : "";
     if (!value) {
@@ -82,7 +154,7 @@ function normalizeUserAttributeMatch(params) {
     }
     return 'match.kind must be "tag" or "structured".';
 }
-export function buildP2PTools(mesh, router) {
+export function buildP2PTools(mesh, router, options = {}) {
     return [
         {
             name: "p2p_send_message",
@@ -294,15 +366,15 @@ export function buildP2PTools(mesh, router) {
                 try {
                     const instances = await router.listInstances();
                     const connected = new Set(mesh.getConnectedPeers());
-                    const rows = instances.map((entry) => ({
+                    const rows = await Promise.all(instances.map(async (entry) => ({
                         ...entry,
+                        userPublicAttributes: entry.userPublicAttributes ?? [],
                         connected: connected.has(entry.peerId),
-                    }));
-                    const text = rows.length === 0
-                        ? "No OpenClaw instances discovered yet."
-                        : rows
-                            .map((entry) => `${entry.instanceId} -> ${entry.peerId}${entry.connected ? " (connected)" : ""}`)
-                            .join("\n");
+                        localLabels: options.peerLabelStore
+                            ? await options.peerLabelStore.listLabels(entry.instanceId)
+                            : [],
+                    })));
+                    const text = formatInstanceList(rows);
                     return {
                         content: [{ type: "text", text }],
                         details: { instances: rows, count: rows.length },
@@ -442,7 +514,7 @@ export function buildP2PTools(mesh, router) {
         {
             name: "p2p_send_user_attribute_message",
             label: "P2P Send User Attribute Message",
-            description: 'Send a user message to discovered OpenClaw instances matching a public user attribute selector. Use selectors like "group=实验室", "project=小龙虾", "tag:P2P", or "#P2P". First run a dry run with dryRun=true to preview targets; if targets match, call again immediately with dryRun=false and the same selector.',
+            description: 'Send a user message to discovered OpenClaw instances matching an attribute selector. scope controls the source: "public" for announced user attributes, "local" for local peer labels, or "all" for both; defaults to public. Use selectors like "group=实验室", "project=小龙虾", "tag:P2P", or "#P2P". First run a dry run with dryRun=true to preview targets; if targets match, call again immediately with dryRun=false and the same selector, scope, and message.',
             parameters: {
                 type: "object",
                 properties: {
@@ -493,8 +565,14 @@ export function buildP2PTools(mesh, router) {
                         type: "boolean",
                         description: "Preview matching instances without sending. Run this before group sending.",
                     },
+                    scope: {
+                        type: "string",
+                        enum: ["public", "local", "all"],
+                        description: "Attribute source to match: public announced attributes, local peer labels, or both. Defaults to public.",
+                    },
                 },
-                required: ["selector", "message"],
+                required: ["message"],
+                anyOf: [{ required: ["selector"] }, { required: ["match"] }],
             },
             async execute(_toolCallId, params) {
                 if (!router) {
@@ -505,9 +583,15 @@ export function buildP2PTools(mesh, router) {
                     };
                 }
                 const match = normalizeUserAttributeMatch(params);
+                const scopeError = validateUserAttributeScope(params.scope);
+                const scope = normalizeUserAttributeScope(params.scope);
                 const message = typeof params.message === "string" ? params.message.trim() : "";
-                if (typeof match === "string" || !message) {
-                    const error = typeof match === "string" ? match : "message is required.";
+                if (typeof match === "string" || scopeError || !message) {
+                    const error = typeof match === "string"
+                        ? match
+                        : scopeError
+                            ? scopeError
+                            : "message is required.";
                     return {
                         content: [{ type: "text", text: error }],
                         details: { error },
@@ -515,7 +599,8 @@ export function buildP2PTools(mesh, router) {
                     };
                 }
                 const dryRun = params.dryRun === true;
-                const result = await router.sendUserAttributeMessage(match, message, { dryRun });
+                const options = scope ? { dryRun, scope } : { dryRun };
+                const result = await router.sendUserAttributeMessage(match, message, options);
                 if (result.error) {
                     return {
                         content: [{ type: "text", text: result.error }],

package/dist/src/instance-router.js

@@ -1,4 +1,4 @@
-import { matchesUserAttribute, mergeUserPublicAttributes } from "./user-attributes.js";
+import { matchesUserAttribute, mergeUserPublicAttributes, normalizeAttributeKey, normalizeAttributeValue, } from "./user-attributes.js";
 const MAX_DELIVERY_CACHE_ENTRIES = 1000;
 function parsePayload(msg) {
     try {
@@ -34,6 +34,25 @@ function describeAttributeMatch(match) {
     }
     return `structured attribute ${match.key}=${match.value}`;
 }
+function effectiveAttributeMatchScope(scope) {
+    return scope ?? "public";
+}
+function matchesLocalPeerLabel(attribute, match) {
+    if (match.kind !== "structured") {
+        return false;
+    }
+    return (normalizeAttributeKey(attribute.key) === normalizeAttributeKey(match.key) &&
+        normalizeAttributeValue(attribute.value) === normalizeAttributeValue(match.value));
+}
+function buildUserAttributeTarget(record, matchedAttribute, matchSource) {
+    return {
+        instanceId: record.instanceId,
+        ...(record.instanceName ? { instanceName: record.instanceName } : {}),
+        peerId: record.peerId,
+        matchedAttribute,
+        matchSource,
+    };
+}
 function displayTargetId(target) {
     const id = typeof target.id === "string" ? target.id.trim() : "";
     return id && id.length > 0 ? id : undefined;
@@ -475,27 +494,36 @@ export function createInstanceRouter(options) {
             error: ack.error,
         };
     }
-    async function resolveUserAttributeTargets(match) {
+    async function resolveUserAttributeTargets(match, scope) {
         const records = await store.list();
         const targets = [];
         for (const record of records) {
-            const matchedAttribute = record.userPublicAttributes?.find((attribute) => matchesUserAttribute(attribute, match));
-            if (!matchedAttribute) {
+            const publicAttribute = scope === "local"
+                ? undefined
+                : record.userPublicAttributes?.find((attribute) => matchesUserAttribute(attribute, match));
+            const localAttribute = scope === "public"
+                ? undefined
+                : (await options.peerLabelStore?.listLabels(record.instanceId))?.find((attribute) => matchesLocalPeerLabel(attribute, match));
+            if (publicAttribute && localAttribute && scope === "all") {
+                targets.push(buildUserAttributeTarget(record, publicAttribute, "all"));
                 continue;
             }
-            targets.push({
-                instanceId: record.instanceId,
-                instanceName: record.instanceName,
-                peerId: record.peerId,
-                matchedAttribute,
-            });
+            if (publicAttribute) {
+                targets.push(buildUserAttributeTarget(record, publicAttribute, "public"));
+                continue;
+            }
+            if (localAttribute) {
+                targets.push(buildUserAttributeTarget(record, localAttribute, "local"));
+            }
         }
         return targets;
     }
     async function sendUserAttributeMessage(match, message, sendOptions = {}) {
-        const targets = await resolveUserAttributeTargets(match);
+        const scope = effectiveAttributeMatchScope(sendOptions.scope);
+        const targets = await resolveUserAttributeTargets(match, scope);
         if (targets.length === 0) {
             return {
+                scope,
                 matched: 0,
                 sent: 0,
                 delivered: 0,
@@ -505,6 +533,7 @@ export function createInstanceRouter(options) {
         }
         if (sendOptions.dryRun === true) {
             return {
+                scope,
                 matched: targets.length,
                 sent: 0,
                 delivered: 0,
@@ -538,6 +567,7 @@ export function createInstanceRouter(options) {
             }
         }
         return {
+            scope,
             matched: targets.length,
             sent: results.filter((result) => result.sent).length,
             delivered: results.filter((result) => result.delivered).length,