@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/cli/commands/index.js

@@ -35,6 +35,7 @@ export const GROUPS_HELP = `
   bolloon task      list | status | result | retry | run | send|inbox|accept|reject|complete|cancel(未实现)
                     publish|board|claim   (任务对外发布 + 接单: 公告板)
                     announce|trail|post   (群聊通道 C7: 公告入群 / 过程留痕回看 / 交付·初筛·终审痕迹)
+                    group create|join|list|link|leave   (群管理: 建群/自助入群/看群/取链接/退群)
   bolloon wallet    status | policy | set-policy
   bolloon payment   pending | approve | reject
   bolloon trade     list | show | events | reconcile

package/dist/cli/commands/tasks.js

@@ -66,6 +66,18 @@ ${title('bolloon task')}
       交付只贴哈希 · 初筛逐条结果 · 终审结论; 群消息一律无钱包地址/DID/peerId/multiaddr/IP/私钥形态
       (命中任一条 → 拒发并报出命中的规则)
 
+  ── 群管理 (2026-09-24: 外部接单者的自助入群入口) ──
+  bolloon task group create --name <群名> [--from <短显示名>] [--json]
+      建群 → 打印**邀请链接** (发给要入群的人) + groupId; 落 ~/.bolloon/gateway-groups.json
+      (ACL write:['*'] = 成员可广播, 建群时写进 store manifest)
+  bolloon task group join <群链接|groupId> [--json]
+      用**链接**自助入群 (幂等: 已在群里 → already=true, 仍 exit 0);
+      store 拿不到区块 → 大声失败 (TRANSPORT_FAILED + storeCode=STORE_UNREACHABLE), 绝不显示成空群
+  bolloon task group list [--json]         本机已加入的群 (groupId · 群名 · 加入时间); 没有群 → 空列表
+  bolloon task group link <groupId|群名>   显式取回邀请链接 (list 里不放链接)
+  bolloon task group leave <groupId|群名>  退群 (只摘本机记录)
+      群管理输出不含原始 DID/钱包地址/peerId/节点 multiaddr/IP (脱敏口径与群消息同源)
+
 选项: --json · --quiet · --request-id <id> · --timeout <ms> · --resume <goalId> (同 bolloon task)
 说明: 收件箱落盘 ~/.bolloon/tasks/inbox/; 本机发出的任务台账 ~/.bolloon/tasks/local/;
       结果 ~/.bolloon/tasks/results/, 交付正文 ~/.bolloon/tasks/bodies/ (私有层, 不进 stdout);
@@ -169,6 +181,8 @@ export async function taskCommand(flags) {
         case 'announce': return taskAnnounce(flags);
         case 'trail': return taskTrail(flags);
         case 'post': return taskPost(flags);
+        // 2026-09-24: 群管理 (create/join/list/link/leave) —— 外部接单者的自助入群入口
+        case 'group': return taskGroup(flags);
         default:
             return {
                 envelope: failEnvelope('INVALID_ARGUMENT', sub ? `未知 task 子命令: ${sub}` : '缺少 task 子命令', { usage: plain(TASK_USAGE.trim()) }, [], 'needs_human'),
@@ -675,7 +689,7 @@ function parseInput(raw) {
 }
 // ── bolloon-task/1 真收发: send / inbox / accept / reject ────────────────────
 /** 人类单位 → 原子单位正整数串 (拒绝 0 / 负 / 超精度; 浮点模糊一律拒) */
-function toAtomic(human, decimals) {
+export function toAtomic(human, decimals) {
     const s = String(human ?? '').trim();
     if (!/^[0-9]+(\.[0-9]+)?$/.test(s))
         return null;
@@ -686,7 +700,7 @@ function toAtomic(human, decimals) {
     return n > 0n ? n.toString() : null;
 }
 /** `--deadline +2h` / `+30m` / `+45s` / `+1d`, 或未来毫秒时间戳 */
-function parseDeadline(v, now = Date.now()) {
+export function parseDeadline(v, now = Date.now()) {
     if (v === undefined)
         return now + 24 * 60 * 60 * 1000;
     const m = /^\+(\d+)(s|m|h|d)$/.exec(String(v).trim());
@@ -1837,6 +1851,340 @@ async function taskPost(flags) {
         ].join('\n'),
     };
 }
+// ── 群管理 (group create|join|list|link|leave, 2026-09-24) ────────────────────
+//
+// 为什么补这一段 (真缺口): `createGroup` / `joinGroup` / `listGroups` 一直只存在于
+// `src/agents/gateway-group.ts`, **CLI 里没有任何入口** —— 外部接单者拿到群链接后
+// 无法自助入群, 只能等对方把话转达。这里把它们接出来 (薄包装, 不重实现密钥学/存储),
+// 并补 `link` (取回邀请链接) 与 `leave` (退群)。
+//
+// 脱敏口径 (与群消息同一张表, 只去掉 orbitdb 那一档 —— 见 `TG.NODE_IDENTITY_RULES`):
+//   · 原始 DID · 钱包地址 · peerId · 节点 multiaddr (`/ip4` `/p2p` …) · IPv4/IPv6 · URL · 邮箱
+//     —— 一律不出现在群管理输出里;
+//   · 群 store 地址 (`/orbitdb/zdpu…`) 是**群自己的公开标识**, 邀请链接必须能打印
+//     → `list` 只出短事实 (groupId/群名/时间), 要链接就显式 `bolloon task group link <groupId>`。
+//   · `create` 的 `--name` 与 `list` 的**输出**都再过一遍 `scanNodeIdentity`: 命中 → 拒 (不静默脱敏)。
+const GROUP_ACTIONS = ['create', 'join', 'list', 'link', 'leave'];
+const GROUP_USAGE = `
+${title('bolloon task group')}
+  bolloon task group create --name <群名> [--from <短显示名>] [--json]
+      建一个可被邀请的群 (OrbitDB events store, ACL write:['*'] = 成员可广播);
+      打印**邀请链接** (把它发给要入群的人) 与 groupId; 落 ~/.bolloon/gateway-groups.json (重启不忘)
+  bolloon task group join <群链接|groupId> [--json]
+      用链接自助入群 (幂等: 已在群里 → already=true, 仍然 exit 0);
+      拿不到区块时**大声失败** (TRANSPORT_FAILED + storeCode=STORE_UNREACHABLE), 绝不把"读不到"说成"群里没东西"
+  bolloon task group list [--json]
+      本机已加入的群 (groupId · 群名 · 加入时间); 没有群 → 空列表 (不是错误)
+  bolloon task group link <groupId|群名> [--json]
+      显式取回邀请链接 (list 里不放链接: 群 store 地址只在你要分享时打印)
+  bolloon task group leave <groupId|群名> [--json]
+      退群 (只摘本机记录; 群 store 是公共 append-only, 别人那边不会因为你退出而改)
+
+选项: --json · --quiet; --name/--from 见上
+说明: 群管理输出不含原始 DID / 钱包地址 / peerId / multiaddr / IP (脱敏口径与群消息同源);
+      跨机**互相看见消息**仍需区块/日志复制 (bitswap + block broker, 不在本命令范围);
+      本机跨进程重开同一群链接读回既有消息已支持。
+`;
+/**
+ * 群管理输出过一遍节点身份闸 (命中 → 拒输出并如实报, 不静默脱敏后再当成没事)。
+ *
+ * `allow` = 本命令**故意打印**的群自身标识 (store 地址 / 邀请链接): 扫之前按**精确串**摘掉。
+ * 为什么要摘 (2026-09-24 想清楚的一个真坑): 群 store 地址是 base58 的 CID (`zdpu…`), 而 base58
+ * 字母表里**同时有 `Q` 和 `m`** —— 几十位里偶然出现 `Qm`, 后面又跟够 30 个 base58 字符时,
+ * 就会撞上 `Qm…` 这个 peerId 形状 → 建群**随机**被判成"输出泄漏了 peerId"。
+ * 摘掉的是"我们自己刚给出的那一个串", **规则一个字没放宽**: 别处再出现任何
+ * DID / 钱包 / peerId / 节点 multiaddr / IP 形状, 照样命中。
+ */
+async function guardGroupOutput(payload, allow = []) {
+    const TG = await import('../../agents/task-group.js');
+    let text = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    const tokens = allow.filter((t) => typeof t === 'string' && t.length > 0);
+    for (const t of tokens)
+        text = text.split(t).join('');
+    const hits = TG.scanNodeIdentity(text);
+    return hits.length ? { ok: false, hits } : { ok: true, exempted: tokens.length };
+}
+/** 群管理输出命中节点身份闸时的统一失败 (如实列出命中规则, 不回显被命中的原文) */
+function groupGuardFail(head, hits, extra = {}) {
+    return {
+        envelope: failEnvelope('POLICY_DENIED', `本机群列表里含节点身份形态, 拒绝输出 (${hits.map((h) => h.rule).join(', ')}) —— 已遮住原文, 不把标识符打出来`, { violations: hits, ...extra }, [], 'needs_human'),
+        human: [
+            title(head),
+            `  拒绝输出: 本机群记录里含 ${hits.map((h) => h.rule).join(', ')}`,
+            ...hits.map((h) => `    · ${h.rule} — ${h.why} (${h.masked}, ${h.chars} 字符)`),
+            '',
+            hint('群名/记录里被写进了标识符 → 改成不含标识符的名字 (本命令不静默脱敏: 脱敏后的群名不是你要看的那个)'),
+        ].join('\n'),
+    };
+}
+/** 群上下文解析: groupId 或群名 → 本机已加入的群 (都没有 → NOT_FOUND, 不猜) */
+async function resolveLocalGroup(raw) {
+    const GG = await import('../../agents/gateway-group.js');
+    const groups = await GG.listGroups();
+    const s = String(raw || '').trim();
+    const hit = groups.find((g) => g.id === s) || groups.find((g) => g.name === s) || null;
+    if (hit)
+        return { ok: true, group: hit };
+    return {
+        ok: false,
+        result: {
+            envelope: failEnvelope('NOT_FOUND', `本机没有这个群: ${s ? `${s.slice(0, 24)}${s.length > 24 ? '…' : ''}` : '(空)'} (既不是已加入群的 groupId, 也不是群名)`, {
+                joinedCount: groups.length,
+                howTo: '入群: bolloon task group join <群链接>; 看已加入的群: bolloon task group list',
+            }, [], 'needs_human'),
+            human: '',
+        },
+    };
+}
+async function taskGroup(flags) {
+    const action = String(flags.positionals[1] ?? '').trim();
+    // 用查表而不是 switch: `case 'create':` 这种字面量不属于 task 的**顶层**子命令,
+    // 免得将来有人把这段挪到 taskCommand 前面时被源级一致性门 (task-subcommands.test.ts) 误认。
+    const table = {
+        create: taskGroupCreate,
+        join: taskGroupJoin,
+        list: taskGroupList,
+        link: taskGroupLink,
+        leave: taskGroupLeave,
+    };
+    const fn = table[action];
+    if (fn)
+        return fn(flags);
+    return {
+        envelope: failEnvelope('INVALID_ARGUMENT', action ? `未知 group 动作: ${action}` : '缺少 group 动作 (create | join | list | link | leave)', { usage: plain(GROUP_USAGE.trim()), accepted: [...GROUP_ACTIONS] }, [], 'needs_human'),
+        human: GROUP_USAGE,
+    };
+}
+/** `task group create --name <群名>` —— 建群 + 打印邀请链接 */
+async function taskGroupCreate(flags) {
+    const head = 'bolloon task group create';
+    const TG = await import('../../agents/task-group.js');
+    const GG = await import('../../agents/gateway-group.js');
+    const name = String(opt(flags, '--name') ?? '').trim();
+    if (!name) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 --name (群名)', { accepted: ['--name 测试群'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    // 群名会进群消息与 list 输出 → 先过节点身份闸 (标识符形状的名字一律拒, 不静默改名)
+    const nameHits = TG.scanNodeIdentity(name);
+    if (nameHits.length) {
+        return {
+            envelope: failEnvelope('POLICY_DENIED', `群名含节点身份形态, 拒绝建群 (${nameHits.map((h) => h.rule).join(', ')})`, { violations: nameHits, accepted: ['--name 测试群'] }, [], 'needs_human'),
+            human: `${title(head)}\n  群名不能含 ${nameHits.map((h) => h.rule).join(', ')}\n\n${hint('群名是公开事实 (会进群消息与 list): 换个不含标识符的名字')}`,
+        };
+    }
+    const s = await TG.resolveSenderTag(opt(flags, '--from'));
+    if (!s.ok) {
+        return {
+            envelope: failEnvelope(s.code, s.message, { ...s.detail, group: { name }, created: false }, [], 'needs_human'),
+            human: `${title(head)}\n  群主标记定不下来: ${s.message}\n\n${hint('建群会写一条欢迎消息 (要一个诚实的发送者标记): 先 bolloon identity init 或 --from <短显示名>')}`,
+        };
+    }
+    const r = await GG.createGroup(name, { from: s.tag });
+    if (!r.ok || !r.group) {
+        return {
+            envelope: failEnvelope('TRANSPORT_FAILED', `建群失败: ${r.error ?? '未知原因'}`, { group: { name }, created: false, storeReachable: false }, [], 'needs_human'),
+            human: `${title(head)}\n  建群失败: ${r.error ?? '未知原因'}\n\n${hint('建群要写 OrbitDB store: 落盘目录不可写 / store 打不开都会在这里如实失败')}`,
+        };
+    }
+    const data = {
+        group: { id: r.group.id, name: r.group.name, link: r.group.link, createdAt: r.group.createdAt },
+        sender: { tag: s.tag, source: s.source, didPrinted: false },
+        file: '~/.bolloon/gateway-groups.json',
+        acl: { write: ['*'], note: '成员可广播: 入群的人都能往群里发消息 (建群时写进 store manifest)' },
+        created: true,
+        executed: false,
+        paid: false,
+        localFallback: false,
+    };
+    const guard = await guardGroupOutput(data, [r.group.id, r.group.link]);
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { group: { name }, created: true });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', `已建群「${r.group.name}」(${r.group.id.slice(0, 12)}…)`, data, [r.group.id], null),
+        human: [
+            title(head),
+            line('群名', r.group.name),
+            line('groupId', r.group.id),
+            line('邀请链接', r.group.link),
+            line('群主标记', `${s.tag} (${s.source === 'identity' ? '本机身份派生假名' : '--from 显式'}; 原始 DID 未进群)`),
+            line('本机记录', '~/.bolloon/gateway-groups.json (重启后仍记得这个群)'),
+            '',
+            hint(`把链接发给要入群的人: bolloon task group join "<链接>"`),
+            hint(`回看过程痕迹: bolloon task trail --group <链接>  ·  取回链接: bolloon task group link ${r.group.id.slice(0, 12)}…`),
+            '',
+            '  跨机**互相看见消息**仍需区块/日志复制 (bitswap + block broker, 不在本命令范围);',
+            '  本机跨进程用同一链接重开读回既有消息已支持。',
+        ].join('\n'),
+    };
+}
+/** `task group join <群链接|groupId>` —— 自助入群 (幂等) */
+async function taskGroupJoin(flags) {
+    const head = 'bolloon task group join';
+    const GG = await import('../../agents/gateway-group.js');
+    const raw = String(flags.positionals[2] ?? '').trim() || String(opt(flags, '--group') ?? '').trim();
+    if (!raw) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少群链接或 groupId', { accepted: ['bolloon task group join orbitdb:///orbitdb/<store>?type=group&name=<群名>', 'bolloon task group join <groupId>'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    // 链接 → 真入群 (打开 store); groupId/群名 → 必须已经在本地列表里 (不能凭 id 凭空入群)
+    if (!/^orbitdb:\/\//i.test(raw)) {
+        // 别的 scheme (`https://…` / `ipfs://…`): 这是**不是群链接**, 不是"本机没有这个群" —— 分开报
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+            return {
+                envelope: failEnvelope('INVALID_ARGUMENT', `这不是群链接 (${raw.split(':')[0]}://…) —— 群链接形如 orbitdb:///orbitdb/<store>?type=group&name=<群名>`, { scheme: raw.split(':')[0], accepted: ['bolloon task group join orbitdb:///orbitdb/<store>?type=group&name=<群名>'] }, [], 'needs_human'),
+                human: `${title(head)}\n  这不是群链接: ${raw.slice(0, 12)}…\n\n${hint('群邀请链接形如 orbitdb:///orbitdb/<store>?type=group&name=<群名> (bolloon task group create 会打印它)')}`,
+            };
+        }
+        const loc = await resolveLocalGroup(raw);
+        if (!loc.ok) {
+            return {
+                envelope: failEnvelope('NOT_FOUND', `本机没有这个群: ${raw} —— 用 id/群名**不能**入群, 只有群链接才能入群`, { accepted: 'bolloon task group join <群链接>', howTo: '拿到群链接后再试; 看已加入的群: bolloon task group list' }, [], 'needs_human'),
+                human: `${title(head)}\n  本机没有这个群: ${raw}\n\n${hint('id/群名只能引用**已加入**的群; 要入群请用邀请链接')}`,
+            };
+        }
+        const data = { group: { id: loc.group.id, name: loc.group.name }, already: true, joined: true, storeOpened: false };
+        return {
+            envelope: okEnvelope('OK', `已在群里「${loc.group.name}」(${loc.group.id.slice(0, 12)}…)`, data, [loc.group.id], null),
+            human: [title(head), line('群名', loc.group.name), line('groupId', loc.group.id), line('状态', 'already=true (早就加入过, 没有重复入群)')].join('\n'),
+        };
+    }
+    const r = await GG.joinGroup(raw);
+    if (!r.ok || !r.group) {
+        const unreachable = r.code === 'STORE_UNREACHABLE';
+        return {
+            envelope: failEnvelope(unreachable ? 'TRANSPORT_FAILED' : 'INVALID_ARGUMENT', unreachable ? `群 store 不可达: ${r.error ?? '未知原因'}` : `不是有效的群链接: ${r.error ?? '未知原因'}`, {
+                storeCode: r.code ?? null,
+                joined: false,
+                storeOpened: false,
+                localFallback: false,
+                why: unreachable
+                    ? '链接能解析但区块不在本机且没有 block broker → 如实失败 (绝不把"读不到"说成"群里没东西")'
+                    : '链接不是 orbitdb://…?type=group&name=… 形状 → 拒绝 (不猜你想进哪个群)',
+            }, [], 'needs_human'),
+            human: [
+                title(head),
+                `  ${unreachable ? '群 store 不可达' : '链接非法'}: ${r.error ?? ''}`,
+                '',
+                hint(unreachable
+                    ? '区块不在本机: 跨机同步 (bitswap/block broker) 还没接; 同机请确认对方的区块目录可读'
+                    : '群链接形如 orbitdb:///orbitdb/<store>?type=group&name=<群名>'),
+            ].join('\n'),
+        };
+    }
+    const data = {
+        group: { id: r.group.id, name: r.group.name },
+        already: !!r.already,
+        joined: true,
+        storeOpened: true,
+        linkKeptLocally: true,
+        note: '入群只改本机群列表 + 打开群 store: 不执行任务、不付款',
+    };
+    const guard = await guardGroupOutput(data, [r.group.id]);
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { joined: true });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', r.already ? `已在群里「${r.group.name}」(${r.group.id.slice(0, 12)}…)` : `已入群「${r.group.name}」(${r.group.id.slice(0, 12)}…)`, data, [r.group.id], null),
+        human: [
+            title(head),
+            line('群名', r.group.name),
+            line('groupId', r.group.id),
+            line('状态', r.already ? 'already=true (幂等: 早就加入过)' : '新加入'),
+            '',
+            hint(`现在可以: bolloon task trail --group ${r.group.id.slice(0, 12)}…  /  bolloon task claim <announcementId> --group <链接>`),
+        ].join('\n'),
+    };
+}
+/** `task group list [--json]` —— 本机已加入的群 (脱敏: 不出链接/地址/DID/peerId/IP) */
+async function taskGroupList(flags) {
+    const head = 'bolloon task group list';
+    const GG = await import('../../agents/gateway-group.js');
+    const groups = await GG.listGroups();
+    const rows = groups.map((g) => ({ id: g.id, name: g.name, createdAt: g.createdAt ?? null }));
+    const data = {
+        count: rows.length,
+        groups: rows,
+        note: '只出群标识/群名/加入时间: 邀请链接与 store 地址不进 list (要链接用 bolloon task group link <groupId>); '
+            + '本输出不含原始 DID/钱包地址/peerId/节点 multiaddr/IP',
+    };
+    const guard = await guardGroupOutput(data, rows.map((r) => r.id));
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { count: rows.length });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', rows.length ? `本机已加入 ${rows.length} 个群` : '本机还没有加入任何群 (空列表, 不是错误)', data, rows.map((r) => r.id), null),
+        human: [
+            title(head),
+            ...(rows.length
+                ? rows.map((r) => `  ${String(r.id).slice(0, 12)}…  ${String(r.name ?? '(无名)').padEnd(20)}  ${r.createdAt ?? '(无时间)'}`)
+                : ['  (本机还没有加入任何群)']),
+            '',
+            hint('建群: bolloon task group create --name <群名>  ·  入群: bolloon task group join <群链接>  ·  取链接: bolloon task group link <groupId>'),
+        ].join('\n'),
+    };
+}
+/** `task group link <groupId|群名>` —— 显式取回邀请链接 */
+async function taskGroupLink(flags) {
+    const head = 'bolloon task group link';
+    const raw = String(flags.positionals[2] ?? '').trim() || String(opt(flags, '--group') ?? '').trim();
+    if (!raw) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 groupId (或群名)', { accepted: ['bolloon task group link <groupId>'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    const loc = await resolveLocalGroup(raw);
+    if (!loc.ok) {
+        return {
+            envelope: failEnvelope('NOT_FOUND', `本机没有这个群: ${raw} (取不到链接)`, { howTo: '看已加入的群: bolloon task group list' }, [], 'needs_human'),
+            human: `${title(head)}\n  本机没有这个群: ${raw}\n\n${hint('先 bolloon task group list 看有哪些群 (或 join 入群)')}`,
+        };
+    }
+    const data = { group: { id: loc.group.id, name: loc.group.name, link: loc.group.link } };
+    const guard = await guardGroupOutput(data, [loc.group.id, loc.group.link]);
+    if (!guard.ok)
+        return groupGuardFail(head, guard.hits, { group: { name: loc.group.name } });
+    data.nodeIdentityGuard = { scanned: true, exemptedGroupTokens: guard.exempted };
+    return {
+        envelope: okEnvelope('OK', `群「${loc.group.name}」的邀请链接已取出`, data, [loc.group.id], null),
+        human: [title(head), line('群名', loc.group.name), line('groupId', loc.group.id), line('邀请链接', loc.group.link)].join('\n'),
+    };
+}
+/** `task group leave <groupId|群名>` —— 退群 (只摘本机记录) */
+async function taskGroupLeave(flags) {
+    const head = 'bolloon task group leave';
+    const GG = await import('../../agents/gateway-group.js');
+    const raw = String(flags.positionals[2] ?? '').trim() || String(opt(flags, '--group') ?? '').trim();
+    if (!raw) {
+        return {
+            envelope: failEnvelope('INVALID_ARGUMENT', '缺少 groupId (或群名)', { accepted: ['bolloon task group leave <groupId>'], usage: plain(GROUP_USAGE.trim()) }, [], 'needs_human'),
+            human: GROUP_USAGE,
+        };
+    }
+    const r = await GG.leaveGroup(raw);
+    if (!r.ok) {
+        return {
+            envelope: failEnvelope('NOT_FOUND', `退群失败: ${r.error ?? '未知原因'}`, { removed: false }, [], 'needs_human'),
+            human: `${title(head)}\n  ${r.error ?? '未知原因'}\n\n${hint('看已加入的群: bolloon task group list')}`,
+        };
+    }
+    return {
+        envelope: okEnvelope('OK', `已退出群 ${String(r.removed).slice(0, 12)}… (只摘本机记录)`, { removed: true, groupId: r.removed, localOnly: true, note: '群 store 是公共 append-only: 别人那边不会因为你退出而改 (本命令没有踢人/解散权限, 也不假装有)' }, [String(r.removed)], null),
+        human: [
+            title(head),
+            line('已退出', `${String(r.removed).slice(0, 12)}…`),
+            line('范围', '只摘本机记录 (~/.bolloon/gateway-groups.json)'),
+            '',
+            `  群 store 是公共 append-only: 别人那边不会因为你退出而改 (本命令没有踢人/解散权限, 也不假装有)`,
+        ].join('\n'),
+    };
+}
 // ── 仍未实现的两个 (任务书没点名; 如实报, 不假装) ────────────────────────────
 async function taskComplete(_flags) {
     const env = notImplemented('task complete 还没实现: 没有任务状态存储可写 (交易层有非法迁移保护, 不许绕过)', {

package/dist/cli/identity-command.js

@@ -0,0 +1,177 @@
+/**
+ * identity-command.ts — `bolloon identity init|show` (2026-09-24)
+ *
+ * 补的真缺口: 建本机身份以前**只有** `bolloon setup` —— 一个 readline 交互向导。
+ * 没有 TTY 的环境 (CI / 容器 / ssh 管道 / 第二实例的自动化) 跑它会
+ * `readline was closed` (ERR_USE_AFTER_CLOSE), 于是"新机器/第二个身份"根本建不出来,
+ * 而群/任务/签名这条链全靠 `~/.bolloon/identity.json`。
+ *
+ * 本模块只做薄包装 (不重实现任何密钥学):
+ *   · `init` — 幂等建 `~/.bolloon/identity.json` (复用 `setup-wizard.initLocalIdentity`,
+ *     它内部走 `KeyManager.generate/saveToFile`, 与 `src/index.ts:bootstrapIdentity` 同一条路径);
+ *     已存在 → **一个字不改** + `action:'reused'` + exit 0; 损坏 → **拒绝覆盖** (要 --force)。
+ *   · `show` — 只出 did / 公钥指纹 / 文件权限; **绝不打印私钥**。
+ *
+ * 红线: 本模块任何路径都不把 `privateKey` 写进 stdout / data / human。
+ * 兜底还有 `finalizeEnvelope` 的 `redactSecrets` (AUDIT_FORBIDDEN_KEYS 含 `privateKey`)。
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as crypto from 'crypto';
+import { okEnvelope, failEnvelope, line, title, hint, plain, has, } from './protocol-envelope.js';
+import { getLocalIdentityFile, initLocalIdentity } from './setup-wizard.js';
+import { AUDIT_FORBIDDEN_KEYS } from '../agents/task-contract.js';
+export const IDENTITY_USAGE = `
+${title('bolloon identity')}
+  bolloon identity init [--force] [--json]
+      非交互建本机身份 → ~/.bolloon/identity.json (文件模式 0600)
+      字段与既有完全一致: keyType='Ed25519' · privateKey · publicKey · did · createdAt · version
+      幂等: 已存在 → 一个字不改 (action=reused), 仍然 exit 0
+      损坏 (读不出 did) → 拒绝覆盖 (exit 1); 确认重来加 --force (会先备份成 .bak-<时间戳>)
+      **绝不打印私钥** (输出只有 did / 文件路径 / 文件权限)
+  bolloon identity show [--json]
+      看本机身份: did · 公钥指纹(sha256 前 16 位) · 文件权限 · 创建时间 (不含私钥)
+
+选项: --json · --quiet · --force (只对 init 有效)
+说明: 只建 identity.json; 供应商/API key 仍走 bolloon setup (或 bolloon setup --provider … --api-key …);
+      用户称呼/归属身份在 ~/.bolloon/identity/user.json (bolloon setup --name 写它)
+`;
+/** 公钥指纹 (sha256 前 16 位 hex) —— 不可逆, 不含密钥材料 */
+function fingerprint(pub) {
+    return `sha256:${crypto.createHash('sha256').update(String(pub || '')).digest('hex').slice(0, 16)}`;
+}
+/** 读现有身份文件 (只取**非私密**字段; privateKey 连读都不读出来) */
+async function readIdentityPublicFacts(home) {
+    const file = getLocalIdentityFile(home);
+    try {
+        const j = JSON.parse(await fs.readFile(file, 'utf-8'));
+        const pub = typeof j?.publicKey === 'string' ? j.publicKey : null;
+        return {
+            exists: true,
+            did: typeof j?.did === 'string' && j.did ? j.did : null,
+            keyType: typeof j?.keyType === 'string' ? j.keyType : null,
+            createdAt: typeof j?.createdAt === 'string' ? j.createdAt : null,
+            version: typeof j?.version === 'string' ? j.version : null,
+            fingerprint: pub ? fingerprint(pub) : null,
+            // 只报**非私密**字段名 (schema 一致性的证据落在测试里: 那边直接读文件比对 6 个键)。
+            // 私钥类字段名 (AUDIT_FORBIDDEN_KEYS: privateKey/…) 连名字都不出现在输出里 ——
+            // 免得"输出里有个 privateKey 字样"被当成可疑, 也让 `grep privateKey` 这种粗检查能直接过。
+            keys: Object.keys(j ?? {}).filter((k) => !AUDIT_FORBIDDEN_KEYS.includes(k)).sort(),
+        };
+    }
+    catch {
+        return { exists: false };
+    }
+}
+/** `bolloon identity init` —— 幂等建本机身份 */
+async function identityInit(flags) {
+    const head = 'bolloon identity init';
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const force = has(flags, '--force');
+    let r;
+    try {
+        r = await initLocalIdentity(home, { force });
+    }
+    catch (e) {
+        return {
+            envelope: failEnvelope('INTERNAL_ERROR', `建身份失败: ${String(e?.message || e).slice(0, 200)}`, { file: getLocalIdentityFile(home), created: false }, [], 'needs_human'),
+            human: `${title(head)}\n  建身份失败: ${String(e?.message || e).slice(0, 200)}`,
+        };
+    }
+    if (!r.ok) {
+        // 拒绝覆盖 (损坏 / force 下备份失败): 如实失败, 不静默重建
+        return {
+            envelope: failEnvelope('POLICY_DENIED', r.reason || '拒绝覆盖既有身份文件', { file: r.file, action: r.action, created: false, overwritten: false }, [], 'needs_human'),
+            human: `${title(head)}\n  ${r.reason || '拒绝覆盖'}\n\n${hint('静默盖掉一个可能还能救的身份 = 丢钥匙: 本命令宁可失败')}`,
+        };
+    }
+    const reused = r.action === 'reused';
+    const facts = await readIdentityPublicFacts(home);
+    const payload = {
+        action: r.action,
+        did: r.did ?? null,
+        file: r.file,
+        mode: r.mode ?? null,
+        created: !reused,
+        changed: false,
+        keyMaterialInOutput: false,
+        publicFields: facts.exists ? facts.keys : null,
+        fingerprint: facts.exists ? facts.fingerprint : null,
+        keyType: facts.exists ? facts.keyType : null,
+        createdAt: facts.exists ? facts.createdAt : null,
+        version: facts.exists ? facts.version : null,
+        nextSteps: reused
+            ? ['身份已存在, 未改动 (幂等); 直接用即可']
+            : ['跑任务/建群/签名现在有身份可用: bolloon task group create --name <群名>', '要配模型供应商/API key: bolloon setup'],
+    };
+    return {
+        envelope: okEnvelope('OK', reused
+            ? `本机身份已存在, 未改动 (${String(r.did).slice(0, 24)}…)`
+            : `已建本机身份 (${String(r.did).slice(0, 24)}…), 文件模式 ${r.mode}`, payload, [], null),
+        human: [
+            title(head),
+            line('动作', reused ? 'reused (已存在, 一个字没改 — 幂等)' : 'created (新建)'),
+            line('DID', r.did ?? '(无)'),
+            line('身份文件', r.file),
+            line('文件模式', r.mode ?? '(读不到)'),
+            line('字段', facts.exists ? facts.keys.join(' · ') : '(无)'),
+            line('公钥指纹', facts.exists ? facts.fingerprint : '(无)'),
+            '',
+            `  ${hint(reused ? '幂等: 第二个身份请换一个 HOME (HOME=/tmp/x bolloon identity init)' : '下一步')}`,
+            ...(reused
+                ? ['  要用第二个身份: `HOME=/tmp/second bolloon identity init` (每个 HOME 一对自己的密钥)']
+                : ['  建群: bolloon task group create --name <群名>', '  模型/API key: bolloon setup (交互向导)']),
+        ].join('\n'),
+    };
+}
+/** `bolloon identity show` —— 看本机身份 (不含私钥) */
+async function identityShow(flags) {
+    const head = 'bolloon identity show';
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const facts = await readIdentityPublicFacts(home);
+    const file = getLocalIdentityFile(home);
+    if (!facts.exists) {
+        return {
+            envelope: failEnvelope('NOT_FOUND', `本机还没有身份文件: ${file}`, { file, exists: false, howTo: 'bolloon identity init', keyMaterialInOutput: false }, [], 'needs_human'),
+            human: `${title(head)}\n  本机还没有身份文件: ${file}\n\n${hint('建一个: bolloon identity init (非交互, 0600, 幂等)')}`,
+        };
+    }
+    const payload = {
+        file,
+        exists: true,
+        did: facts.did,
+        keyType: facts.keyType,
+        createdAt: facts.createdAt,
+        version: facts.version,
+        fingerprint: facts.fingerprint,
+        publicFields: facts.keys,
+        keyMaterialInOutput: false,
+    };
+    return {
+        envelope: okEnvelope('OK', `本机身份: ${String(facts.did).slice(0, 24)}…`, payload, [], null),
+        human: [
+            title(head),
+            line('DID', facts.did ?? '(缺 did — 文件可能损坏)'),
+            line('身份文件', file),
+            line('keyType', facts.keyType ?? '(无)'),
+            line('version', facts.version ?? '(无)'),
+            line('createdAt', facts.createdAt ?? '(无)'),
+            line('公钥指纹', facts.fingerprint ?? '(无)'),
+            line('非私密字段', facts.keys.join(' · ')),
+            '',
+            '  私钥只在本机文件里 (0600), 不进任何输出/日志',
+        ].join('\n'),
+    };
+}
+/** 命令入口 (cli-entry 用 runCommand 包它: 统一 --json/--quiet/--timeout/异常兜底) */
+export async function identityCommand(flags) {
+    const sub = String(flags.positionals[0] ?? '').trim().toLowerCase();
+    if (sub === 'init')
+        return identityInit(flags);
+    if (sub === 'show' || sub === 'status')
+        return identityShow(flags);
+    return {
+        envelope: failEnvelope('INVALID_ARGUMENT', sub ? `未知 identity 子命令: ${sub}` : '缺少 identity 子命令 (init | show)', { usage: plain(IDENTITY_USAGE.trim()), accepted: ['bolloon identity init', 'bolloon identity show'] }, [], 'needs_human'),
+        human: IDENTITY_USAGE,
+    };
+}