dsh-lan-peers 0.8.1 → 0.8.3

package/client/cli-code.test.mjs

@@ -0,0 +1,108 @@
+// dsh-lan-peers · M6 之后 `lan-peers code` 必须请本机 host 发码。
+//
+// 审计/产品口径：配对码只在 daemon 进程内存里，CLI 是独立进程 —— 它自己造的码对正在跑的
+// host 无效，用户抄走的是废码。所以 code 子命令改成打本机管理接口（带 token），
+// 本机没 host / 拿不到 token 时 exit 2 并说清怎么起 host，绝不本地造一个码。
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createAdmin } from '../lib/admin.mjs';
+import { makeTempStateDir } from '../host/test/helpers.mjs';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
+
+const run = (args) => new Promise((resolve) => {
+  execFile(process.execPath, [CLI, ...args], { encoding: 'utf8' }, (error, stdout, stderr) => {
+    resolve({ code: error ? error.code : 0, stdout: String(stdout || ''), stderr: String(stderr || '') });
+  });
+});
+
+/** 真 admin 挂在真 HTTP 上：token 文件由它启动时写进这个 stateDir（CLI 读同一份）。 */
+async function startAdmin(t, { dir, code = '246810' } = {}) {
+  const state = { instanceId: 'inst-self', name: 'self' };
+  const store = {
+    instanceId: 'inst-self',
+    stateDir: dir,
+    state,
+    listPeers: () => [],
+    getPeer: () => null,
+    issuePairingCode: () => {
+      const issued = { code, expiresAt: Date.now() + 600_000 };
+      state.pairingCode = issued;
+      return issued;
+    },
+  };
+  const admin = createAdmin({
+    server: { config: { logger: () => {} }, store },
+    nameOf: () => 'self',
+    rename: (n) => n,
+  });
+  const calls = [];
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      calls.push({ url: String(req.url || ''), method: String(req.method || 'GET'), headers: req.headers });
+      const url = new URL(String(req.url || '/'), 'http://127.0.0.1');
+      Promise.resolve(admin.handle(req, res, url)).then((handled) => {
+        if (!handled) {
+          res.writeHead(404, { 'content-type': 'application/json' });
+          res.end('{"error":"not-found"}');
+        }
+      }).catch((error) => {
+        res.writeHead(500, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: String(error && error.message ? error.message : error) }));
+      });
+    });
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => new Promise((resolve) => server.close(resolve)));
+  return { admin, calls, state, url: 'http://127.0.0.1:' + server.address().port };
+}
+
+test('code：请本机 host 发码并原样打印（与 admin 手里的码一致）', async (t) => {
+  const dir = makeTempStateDir('lanb-cli-code-');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const rig = await startAdmin(t, { dir, code: '246810' });
+
+  const out = await run(['code', '--state-dir', dir, '--url', rig.url]);
+  assert.equal(out.code, 0, out.stderr);
+  assert.match(out.stdout, /配对码: 246810/);
+  assert.doesNotMatch(out.stdout + out.stderr, /token/, '不能把 token 字样漏到界面上');
+
+  const issued = rig.calls.find((call) => call.url === '/api/lan-peers/code');
+  assert.ok(issued, '必须打 POST /api/lan-peers/code: ' + JSON.stringify(rig.calls.map((c) => c.url)));
+  assert.equal(issued.method, 'POST');
+  assert.equal(issued.headers['x-lan-peers-token'], rig.admin.token, 'token 从 <stateDir>/admin-token 读，只走请求头');
+
+  // 打印出来的码就是 host 手里的那一个：GET state 说「已生成」。
+  const state = await fetch(rig.url + '/api/lan-peers/state', { headers: { 'x-lan-peers-token': rig.admin.token } });
+  const body = await state.json();
+  assert.equal(body.pairing.active, true, 'CLI 打印的码必须是本机 host 活着的那一个');
+  assert.equal(JSON.stringify(body).includes('246810'), false, 'GET state 仍不回显码');
+});
+
+test('code：本机没有 host / 拿不到 token → exit 2，且绝不本地造码打印', async (t) => {
+  const dir = makeTempStateDir('lanb-cli-code-');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const rig = await startAdmin(t, { dir, code: '246810' });
+  // 拿掉 token 文件：等价于「本机 host 没起 / 不是同一个进程」。
+  fs.rmSync(path.join(dir, 'admin-token'));
+
+  const out = await run(['code', '--state-dir', dir, '--url', rig.url]);
+  assert.equal(out.code, 2, '拿不到码就是 exit 2: ' + out.stdout + out.stderr);
+  assert.match(out.stderr, /请先启动本机 host/);
+  assert.match(out.stderr, /token-required/, '失败原因要如实转述');
+  assert.doesNotMatch(out.stdout, /\d{6}/, '失败时不能在 stdout 吐出任何 6 位数字（那会被当成码）');
+  assert.equal(fs.existsSync(path.join(dir, 'admin-token')), false, 'CLI 不该自己去造 token');
+});
+
+test('code --help 说明「请本机 host 发码」，不再声称写 state.json', async (t) => {
+  const out = await run(['code', '--help']);
+  assert.match(out.stdout, /请本机 host 生成一次性配对码/);
+  assert.doesNotMatch(out.stdout, /同时写入 state\.json/, 'M6 之后 state.json 不再存码');
+});

package/client/cli-dispatch.test.mjs

@@ -0,0 +1,226 @@
+// dsh-lan-peers · CLI 的群内派单可见面（v0.8.2-α，契约 §1/§4/§5）。
+//
+// 真进程跑 cli.mjs：hub 在本进程里起（所以子进程必须异步跑），本机 host 的管理接口
+// 用一个小 HTTP 桩代替 —— 派单执行在 host 里（Lane X），CLI 只负责「发完消息再去触发」。
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPeerServer } from '../host/server.mjs';
+import { makeTempStateDir, peerFixture, seedPeers, writeJson0600 } from '../host/test/helpers.mjs';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
+const MEMBER = peerFixture('peer-cli-dispatch');
+
+function runAsync(args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI, ...args], { encoding: 'utf8' }, (error, stdout, stderr) => {
+      resolve({ status: error ? error.code : 0, stdout, stderr });
+    });
+  });
+}
+
+async function startHub(t, overrides = {}) {
+  const stateDir = makeTempStateDir();
+  seedPeers(stateDir, overrides.peers ?? [MEMBER]);
+  const server = createPeerServer({
+    listenHost: '127.0.0.1',
+    stateDir,
+    // 这个文件测的是 CLI 行为：quorum:none = 写本地即提交，不牵扯选举投票。
+    group: { enabled: true, autoJoin: true, quorum: 'none' },
+    ...overrides,
+  });
+  const info = await server.listen(0, '127.0.0.1');
+  t.after(async () => {
+    await server.close();
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  });
+  return { server, baseUrl: info.url, stateDir };
+}
+
+function memberStateDir(t, { baseUrl, hubInstanceId, identity = MEMBER, peerName = 'hub' }) {
+  const dir = makeTempStateDir('dsh-lan-peers-cli-dispatch-');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  writeJson0600(path.join(dir, 'state.json'), {
+    instanceId: identity.peerId,
+    name: identity.name,
+    createdAt: new Date().toISOString(),
+  });
+  writeJson0600(path.join(dir, 'peers.json'), {
+    peers: {
+      [hubInstanceId]: {
+        name: peerName,
+        baseUrl,
+        secret: identity.inboundSecret,
+        inboundSecret: 'unused-outbound',
+        addedAt: new Date().toISOString(),
+        lastSeen: null,
+      },
+    },
+  });
+  return dir;
+}
+
+/** 本机 host 的管理接口桩：只实现 group/dispatch 与 group/accept，记录每一次请求。 */
+async function startAdminStub(t, handler) {
+  const requests = [];
+  const server = http.createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', () => {
+      const payload = raw === '' ? null : JSON.parse(raw);
+      requests.push({ method: req.method, url: String(req.url), payload });
+      let answer = {};
+      try {
+        answer = handler({ url: String(req.url), payload }) || {};
+      } catch (error) {
+        answer = { status: 500, json: { error: String(error.message || error) } };
+      }
+      res.writeHead(Number(answer.status) || 200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(answer.json ?? {}));
+    });
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => new Promise((resolve) => server.close(resolve)));
+  return { requests, url: 'http://127.0.0.1:' + server.address().port };
+}
+
+/** 一条到 hub 的、已入群的成员 state-dir */
+async function joinedMember(t) {
+  const hub = await startHub(t);
+  const dir = memberStateDir(t, { baseUrl: hub.baseUrl, hubInstanceId: hub.server.store.instanceId });
+  const joined = await runAsync(['group', 'join', '--peer', 'hub', '--state-dir', dir]);
+  assert.equal(joined.status, 0, joined.stderr);
+  return { hub, dir };
+}
+
+const DONE = {
+  ok: true,
+  dispatch: { target: 'nas-box', targetName: 'nas-box', status: 'done', reason: '', elapsedMs: 1234, replyChars: 56 },
+};
+
+test('group --help 列出 dispatch 与 accept 两个新子命令', async () => {
+  const out = await runAsync(['group', '--help']);
+  assert.match(out.stdout, /dispatch <目标> <任务\.\.\.>/);
+  assert.match(out.stdout, /accept on\|off/);
+  assert.match(out.stdout, /@!名字 时作者侧自动派单/);
+});
+
+test('group dispatch <目标> <任务>：等价发一条 @!目标 任务，再触发本机派单并打印摘要', async (t) => {
+  const { hub, dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ url }) => (url.includes('/group/dispatch') ? { json: DONE } : { json: { ok: true } }));
+
+  const out = await runAsync([
+    'group', 'dispatch', 'nas-box', '跑', '回归', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(out.status, 0, out.stderr);
+  assert.match(out.stdout, /已发送 seq=\d+/);
+  assert.match(out.stdout, /派单 → nas-box：done（1234ms \/ 56字）/);
+
+  const dispatched = admin.requests.filter((request) => request.url === '/api/lan-peers/group/dispatch');
+  assert.equal(dispatched.length, 1);
+  assert.deepEqual(dispatched[0].payload, { target: 'nas-box', task: '跑 回归', extraTargets: 0 });
+
+  // 群消息先入库，且内容就是 "@!目标 任务"
+  const history = await runAsync(['group', 'history', '--peer', 'hub', '--state-dir', dir]);
+  assert.equal(history.status, 0, history.stderr);
+  assert.match(history.stdout, /@!nas-box 跑 回归/);
+  assert.ok(hub.server, 'hub 必须还活着');
+});
+
+test('group post --text "@!X 任务"：自动派单；普通消息一次都不打派单接口', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ url }) => (url.includes('/group/dispatch') ? { json: DONE } : { json: { ok: true } }));
+
+  const withBang = await runAsync([
+    'group', 'post', '--text', '@!nas-box 修 CI', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(withBang.status, 0, withBang.stderr);
+  assert.match(withBang.stdout, /派单 → nas-box：done/);
+  assert.equal(admin.requests.length, 1);
+  assert.deepEqual(admin.requests[0].payload, { target: 'nas-box', task: '修 CI', extraTargets: 0 });
+
+  const plain = await runAsync([
+    'group', 'post', '--text', '@nas-box 只是提及', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(plain.status, 0, plain.stderr);
+  assert.equal(admin.requests.length, 1, '没有 @! 就一次派单请求都不发');
+});
+
+test('本机没有 host：消息照发，但派单未触发要如实报错 exit 2（不静默当普通消息）', async (t) => {
+  const { dir } = await joinedMember(t);
+  // 默认 --url 指向 127.0.0.1:7788：本测试里那里没有 host
+  const out = await runAsync([
+    'group', 'post', '--text', '@!nas-box 跑回归', '--peer', 'hub', '--state-dir', dir,
+    '--url', 'http://127.0.0.1:1',
+  ]);
+  assert.equal(out.status, 2);
+  assert.match(out.stdout, /已发送 seq=\d+/, '群消息确实发出去了');
+  assert.match(out.stderr, /派单未触发/);
+  assert.match(out.stderr, /本机 host 未响应/);
+});
+
+test('skipped（没有 @! 目标）显示未派单，不算完成也不算失败', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, () => ({ json: { ok: false, dispatch: { status: 'skipped', reason: 'no-target' } } }));
+  const out = await runAsync([
+    'group', 'dispatch', 'nas-box', '任务', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(out.status, 0, '零动作不是失败');
+  assert.match(out.stdout, /未派单（消息里没有 @! 目标）: no-target/);
+});
+
+test('派单失败（failed）打印 reason 并 exit 1', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, () => ({
+    json: { ok: false, dispatch: { target: 'nas-box', status: 'failed', reason: 'not-accepting', elapsedMs: 12 } },
+  }));
+  const out = await runAsync([
+    'group', 'dispatch', 'nas-box', '任务', '--peer', 'hub', '--state-dir', dir, '--url', admin.url,
+  ]);
+  assert.equal(out.status, 1);
+  assert.match(out.stdout, /派单 → nas-box：failed（not-accepting \/ 12ms）/);
+});
+
+test('group accept off：打本机管理接口并打印新状态', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ payload }) => ({
+    json: { ok: true, acceptDispatch: payload.acceptDispatch, persisted: true },
+  }));
+  const off = await runAsync(['group', 'accept', 'off', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(off.status, 0, off.stderr);
+  assert.match(off.stdout, /本机接单：已关闭/);
+  assert.deepEqual(admin.requests[0].payload, { acceptDispatch: false });
+
+  const on = await runAsync(['group', 'accept', 'on', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(on.status, 0, on.stderr);
+  assert.match(on.stdout, /本机接单：接单中/);
+  assert.deepEqual(admin.requests[1].payload, { acceptDispatch: true });
+});
+
+test('group accept：host 未接线（501）→ exit 2 且说清原因', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, () => ({ status: 501, json: { error: 'accept-toggle-unsupported' } }));
+  const out = await runAsync(['group', 'accept', 'off', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(out.status, 2);
+  assert.match(out.stderr, /切换接单失败/);
+  assert.match(out.stderr, /accept-toggle-unsupported/);
+});
+
+test('group accept 参数必须是 on|off；persisted=false 要如实说「重启后回原值」', async (t) => {
+  const { dir } = await joinedMember(t);
+  const admin = await startAdminStub(t, ({ payload }) => ({
+    json: { ok: true, acceptDispatch: payload.acceptDispatch, persisted: false },
+  }));
+  const bad = await runAsync(['group', 'accept', 'toggle', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /group accept on\|off/);
+  assert.equal(admin.requests.length, 0, '参数不对时一个请求都不发');
+
+  const ok = await runAsync(['group', 'accept', 'off', '--state-dir', dir, '--url', admin.url]);
+  assert.equal(ok.status, 0, ok.stderr);
+  assert.match(ok.stdout, /重启后回到配置值/);
+});

package/client/cli.mjs

@@ -7,11 +7,9 @@
 //   node cli.mjs events --peer <peerId|name> --session <sessionId> [--duration 300] [--verbose]
 //   node cli.mjs unpair --peer <peerId|name> [--local-only] [--timeout 10]
 import crypto from 'node:crypto';
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import {
   DEFAULT_ANSWER_WAIT_MS,
   MAX_ANSWER_WAIT_MS,
@@ -23,6 +21,9 @@ import {
   probePeer,
 } from './peer-call.mjs';
 import { readPeerEvents } from './sse.mjs';
+// v0.8.2-α（契约 §1/§5）：@! 的解析口径与面板共用一份 —— 解析属于协议，不属于某一端。
+// 面板在管理接口里解析，CLI 在发完消息后解析，两边落在同一个函数上。
+import { parseGroupDispatchCommand } from '../lib/admin.mjs';
 import {
   GROUP_APPLY_POLL_INTERVAL_MS,
   GROUP_APPLY_POLL_TIMEOUT_MS,
@@ -79,9 +80,11 @@ const USAGE = [
 ].join('\n');
 
 const CODE_USAGE = [
-  '用法: dsh-lan-peers code [--state-dir <目录>]',
+  '用法: dsh-lan-peers code [--state-dir <目录>] [--url <本机管理接口>]',
   '',
-  '生成一次性配对码，同时写入 state.json（10 分钟有效，用后即焚）。',
+  '请本机 host 生成一次性配对码（10 分钟有效，用后即焚）。',
+  'M6 起码只活在 host 进程内存里：本命令是独立进程，自己生成的码对正在跑的 host 无效，',
+  '所以必须先启动本机 host（或直接用界面面板的「生成配对码」）。',
 ].join('\n');
 
 const PAIR_USAGE = [
@@ -137,6 +140,9 @@ const GROUP_USAGE = [
   '子命令:',
   '  state                     群信息 + 成员表（会拿到 groupKey，但不打印内容）',
   '  post --text "..."         发一条消息 [--kind chat|progress|result|system]',
+  '                            正文含 @!名字 时作者侧自动派单（由本机 host 执行并打印回执摘要）',
+  '  dispatch <目标> <任务...>  等价发一条 "@!目标 任务" 并派单，打印回执摘要',
+  '  accept on|off             切换本机接单（写 profile 配置，热生效）',
   '  history [--since N]       取历史消息 [--limit 1..200]',
   '  tail [--since N]          跟随事件流并逐条打印 [--duration 秒]',
   '  join [--name 显示名]      向 hub 自助加入（hub 开了 autoJoin 才成功）',
@@ -221,20 +227,40 @@ async function signedCall({ baseUrl, secret, senderId, method = 'GET', apiPath,
   return callPeer({ baseUrl, secret, senderId, method, apiPath, body, timeoutMs: 60_000 });
 }
 
+/**
+ * M6：配对码只活在 daemon 进程内存里（state.json 不再持久化它）。本命令是**独立进程**，
+ * 自己生成一个码打印出来，正在跑的 host 根本不知道 —— 用户抄走的是一条无效凭据
+ * （旧行为「另一个进程能写码」本身也正是要堵掉的植入路径）。所以这里改成请本机 host 发码：
+ * 它才是唯一该写这条的进程，也是唯一知道码的进程。
+ *
+ * 本机没有 host / 拿不到 token → exit 2 并说清怎么起 host，绝不本地造一个码糊弄过去。
+ */
 async function cmdCode(args) {
-  // The code lives in state.json, which the host process re-reads; issuing it via
-  // the host CLI keeps one writer instead of racing the running server.
-  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-  const out = execFileSync(process.execPath, [
-    path.join(pkgRoot, 'host', 'server.mjs'),
-    '--code',
-    '--state-dir',
-    stateDir(args),
-  ], { encoding: 'utf8' });
-  const match = /(\d{6})/.exec(out);
-  if (!match) throw new Error(out.trim() || 'no pairing code');
-  console.log('配对码: ' + match[1] + '   有效期: 10 分钟，一次性');
+  const dir = stateDir(args);
+  const url = String(args.url ?? '').trim() || ADMIN_DEFAULT_URL;
+  let out;
+  try {
+    out = await adminCall(url, 'code', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    }, dir);
+  } catch (error) {
+    const reason = String(error?.message ?? error);
+    process.stderr.write('生成配对码失败：本机 host 未接受 ' + url + '（' + reason + '）\n'
+      + '修法：请先启动本机 host（或用界面面板的「生成配对码」）—— 码只能在 host 进程里生成\n');
+    process.exitCode = 2;
+    return;
+  }
+  const code = String(out && out.code ? out.code : '').trim();
+  if (!/^\d{6}$/.test(code)) {
+    process.stderr.write('生成配对码失败：本机 host 未按契约回 6 位码\n');
+    process.exitCode = 2;
+    return;
+  }
+  console.log('配对码: ' + code + '   有效期: 10 分钟，一次性');
   console.log('对方把它填进「添加伙伴」里即可配对（地址填本机 http://<ip>:7788）');
+  console.log('提示: 这个码只在本机 host 进程里有效，重启 host 即失效');
 }
 
 async function cmdPair(args) {
@@ -703,8 +729,72 @@ async function cmdGroupState(dir, args) {
   console.log('groupKey: 已在 group-key.json（32B，不显示）');
 }
 
-async function cmdGroupPost(dir, args) {
-  const text = String(args.text ?? args._.slice(1).join(' ') ?? '').trim();
+/**
+ * 契约 §3 的回执摘要（CLI 口径，与面板同形）：派单 → 目标：done/failed（reason / 耗时 / 字数）。
+ * skipped 是第三种终态：这条消息没有 @! 目标 —— 零消息写入，不能说成完成也不能说成失败。
+ */
+function formatDispatchLine(dispatch) {
+  const data = dispatch && typeof dispatch === 'object' ? dispatch : {};
+  const status = String(data.status ?? '');
+  const who = String(data.targetName ?? '') || String(data.target ?? '') || '—';
+  if (status === 'skipped') return '未派单（消息里没有 @! 目标）: ' + String(data.reason ?? 'no-target');
+  // M1：同名歧义是「用户得先选一个」，不是网络错误 —— 给出可操作的重发语法。
+  if (status === 'failed' && String(data.reason ?? '') === 'ambiguous') {
+    return '派单 → ' + who + '：有多个同名成员，请用 @!名字 (短id) 重发';
+  }
+  const parts = [];
+  // done 也可能带 reason（契约 §1：多个 @! 只取第一个，reason=multi-target-ignored）。
+  const reason = String(data.reason ?? '');
+  if (reason !== '') parts.push(reason);
+  else if (status !== 'done') parts.push('error');
+  const elapsed = Number(data.elapsedMs);
+  if (Number.isFinite(elapsed) && elapsed >= 0) parts.push(Math.round(elapsed) + 'ms');
+  const chars = Number(data.replyChars);
+  if (Number.isFinite(chars) && chars >= 0) parts.push(Math.round(chars) + '字');
+  return '派单 → ' + who + '：' + (status === 'done' ? 'done' : 'failed')
+    + (parts.length ? '（' + parts.join(' / ') + '）' : '');
+}
+
+/**
+ * 契约 §5：作者侧派单的执行口 = 本机回环的 POST /api/lan-peers/group/dispatch。
+ * 派单要开 1:1 会话、要往群里写 progress/result，只有本机 host 做得到；CLI 直连 hub
+ * 发消息，所以这里必须再打一次本机管理接口。
+ *
+ * 本机没有 host（纯 CLI 节点、host 没起）→ **如实报错并 exit 2**：
+ * 静默把 "@!X 任务" 当成一条普普通通的群消息发出去，是最坏的一种失败。
+ */
+async function triggerDispatch(args, command) {
+  const url = String(args.url ?? '').trim() || ADMIN_DEFAULT_URL;
+  let out;
+  try {
+    out = await adminCall(url, 'group/dispatch', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        target: command.target,
+        task: command.task,
+        extraTargets: command.extraTargets,
+      }),
+    }, stateDir(args));
+  } catch (error) {
+    const reason = String(error?.message ?? error);
+    process.stderr.write('消息已发出，但派单未触发：本机 host 未响应 ' + url + '（' + reason + '）\n'
+      + '修法：先起本机 host（或对 --url 指向的管理接口重试 group dispatch）\n');
+    process.exitCode = 2;
+    return;
+  }
+  const dispatch = out && out.dispatch && typeof out.dispatch === 'object' ? out.dispatch : null;
+  if (!dispatch) {
+    process.stderr.write('派单未返回结果：本机 host 未按契约回 dispatch 摘要\n');
+    process.exitCode = 2;
+    return;
+  }
+  console.log(formatDispatchLine(dispatch));
+  if (dispatch.status === 'failed') process.exitCode = 1;
+}
+
+/** 发一条群消息（post 与 dispatch 共用）；作者侧在 POST 之后按契约 §1 解析 @! 并派单。 */
+async function postGroupText(dir, args, text) {
   if (!text) throw new Error(GROUP_USAGE);
   if (Array.from(text).length > GROUP_TEXT_MAX_CHARS) {
     throw new Error('text 超过 ' + GROUP_TEXT_MAX_CHARS + ' 字符上限（hub 会回 413 payload-too-large）');
@@ -726,6 +816,53 @@ async function cmdGroupPost(dir, args) {
     '已发送 seq=' + sent.seq + ' ts=' + new Date(Number(sent.ts)).toISOString()
       + (channel.mode === 'group' ? '（群级签名直连 ' + channel.key.baseUrl + '）' : ''),
   );
+  // 只有 chat 参与解析：progress/result 本身就是回执，再解析一遍等于自己派自己。
+  if (kind !== 'chat') return;
+  const command = parseGroupDispatchCommand(text);
+  if (!command) return;
+  await triggerDispatch(args, command);
+}
+
+async function cmdGroupPost(dir, args) {
+  const text = String(args.text ?? args._.slice(1).join(' ') ?? '').trim();
+  await postGroupText(dir, args, text);
+}
+
+/** 契约 §5：显式入口 —— 等价发一条 "@!目标 任务" 再派单（消息先入库，回执摘要打印出来）。 */
+async function cmdGroupDispatch(dir, args) {
+  const target = String(args._[1] ?? '').trim();
+  const task = args._.slice(2).join(' ').trim() || String(args.text ?? '').trim();
+  if (target === '' || task === '') {
+    throw new Error('用法: dsh-lan-peers group dispatch <目标> <任务...>\n' + GROUP_USAGE);
+  }
+  await postGroupText(dir, args, '@!' + target + ' ' + task);
+}
+
+/** 契约 §4/§5：切换本机接单开关（写 profile 配置、热生效；结果以 host 回的为准）。 */
+async function cmdGroupAccept(dir, args) {
+  const wanted = String(args._[1] ?? '').trim().toLowerCase();
+  const value = wanted === 'on' ? true : (wanted === 'off' ? false : null);
+  if (value === null) {
+    throw new Error('用法: dsh-lan-peers group accept on|off\n' + GROUP_USAGE);
+  }
+  const url = String(args.url ?? '').trim() || ADMIN_DEFAULT_URL;
+  let out;
+  try {
+    out = await adminCall(url, 'group/accept', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ acceptDispatch: value }),
+    }, dir);
+  } catch (error) {
+    const reason = String(error?.message ?? error);
+    process.stderr.write('切换接单失败：本机 host 未接受 ' + url + '（' + reason + '）\n'
+      + '修法：确认本机 host 在跑且群功能已启用（' + reason + ' 为 501 表示 host 还没接线）\n');
+    process.exitCode = /^(40[39]|501)\b/.test(reason) ? 2 : 1;
+    return;
+  }
+  const applied = !(out && out.acceptDispatch === false);
+  console.log('本机接单：' + (applied ? '接单中' : '已关闭')
+    + (out && out.persisted === false ? '（仅本进程生效，重启后回到配置值）' : ''));
 }
 
 async function cmdGroupHistory(dir, args) {
@@ -939,16 +1076,37 @@ async function cmdGroupClaim(dir, args) {
 
 const ADMIN_DEFAULT_URL = 'http://127.0.0.1:7788';
 const ADMIN_TIMEOUT_MS = 10000;
+// S3：管理接口要 X-Lan-Peers-Token。host 启动时把它写到 <stateDir>/admin-token（0600），
+// CLI 只读不写；token 本身绝不出现在 URL、日志或错误消息里（只说去哪读）。
+const ADMIN_TOKEN_FILE = 'admin-token';
+
+function readAdminToken(dir) {
+  try {
+    return fs.readFileSync(path.join(String(dir || DEFAULT_STATE_DIR), ADMIN_TOKEN_FILE), 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
 
 /** 打本机回环管理接口；非 2xx 抛 `<status> <error>` 形式的 Error（与 group-client 同款）。 */
-async function adminCall(baseUrl, apiPath, init) {
+async function adminCall(baseUrl, apiPath, init, dir) {
   const base = String(baseUrl || ADMIN_DEFAULT_URL).replace(/\/+$/, '');
+  const token = readAdminToken(dir);
+  const headers = { ...(init && init.headers ? init.headers : {}) };
+  if (token !== '') headers['X-Lan-Peers-Token'] = token;
   const reply = await fetch(base + '/api/lan-peers/' + apiPath, {
     ...init,
+    headers,
     signal: AbortSignal.timeout(ADMIN_TIMEOUT_MS),
   });
   const body = await reply.json().catch(() => ({}));
-  if (!reply.ok) throw new Error(reply.status + ' ' + String(body.error || 'admin-call-failed'));
+  if (!reply.ok) {
+    const status = reply.status;
+    const where = path.join(String(dir || DEFAULT_STATE_DIR), ADMIN_TOKEN_FILE);
+    // 401 一定是 token 缺失/不匹配：直接指路（host 启动时写入，权限 0600）。
+    const hint = status === 401 ? '（管理接口需要 token：确认本机 host 在跑，且 ' + where + ' 可读）' : '';
+    throw new Error(status + ' ' + String(body.error || 'admin-call-failed') + hint);
+  }
   return body;
 }
 
@@ -962,7 +1120,7 @@ function reportArchiveError(error) {
 async function cmdGroupArchives(dir, args) {
   let out;
   try {
-    out = await adminCall(args.url, 'group/archives');
+    out = await adminCall(args.url, 'group/archives', undefined, dir);
   } catch (error) {
     reportArchiveError(error);
     return;
@@ -998,7 +1156,7 @@ async function cmdGroupArchiveDelete(dir, args) {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ file: file, action: 'delete' }),
-    });
+    }, dir);
   } catch (error) {
     reportArchiveError(error);
     return;
@@ -1340,6 +1498,8 @@ async function cmdGroup(args) {
   const handlers = {
     state: cmdGroupState,
     post: cmdGroupPost,
+    dispatch: cmdGroupDispatch,
+    accept: cmdGroupAccept,
     history: cmdGroupHistory,
     tail: cmdGroupTail,
     join: cmdGroupJoin,