dsh-lan-peers 0.8.4 → 0.10.3

package/README.md

@@ -122,6 +122,27 @@ npx dsh-lan-peers ask --peer my-nas "在 /data/project 执行 pwd" --timeout 120
 
 对端会在自己的 `workspace` 里建真实会话、由对端模型执行，然后把最终回复加密回传。
 
+## 版本互通
+
+同一个群里允许混版本，但 **0.10 与 0.9.x / 0.8.4 之间有两条硬断裂**。下表是「两端各自正常工作时，用户实际看到的结果」。
+
+| 组合 | 私聊 ask | 群聊 chat | 群内派单 | 群纪要 | 群表决 | 引用行 |
+|---|---|---|---|---|---|---|
+| 0.10.x ↔ 0.9.x | WORKING | WORKING | BROKEN：老节点发的 `progress`/`result` 被 0.10 hub 判 `400 {"error":"bad-request"}`，群里没有「开始/结果」回执 | DEGRADED：老 hub 的 pull 不带 `notes`，成员面板一直空白、不报错 | DEGRADED：同理；成员提提案/投票打到老 hub 得 `404 {"error":"not-found"}` | DEGRADED：老 hub 的 meta 白名单没有 `quote`，静默丢弃，只少「引用 …」那一行 |
+| 0.10.x ↔ 0.8.4 | WORKING | WORKING | BROKEN：同上（0.8.4 的回执同样是 `progress`/`result`） | DEGRADED：同上 | DEGRADED：同上 | DEGRADED：同上 |
+
+**变在哪、为什么断**
+
+- **两条硬断裂**：① 群内派单整条线在 0.10.0 删除（`lan_group_ask`、管理面 `group/dispatch-options` / `group/accept`、执行器、回执），`GROUP_KINDS` 只剩 `['chat','system']`；② 于是老对端继续投 `progress`/`result` 回执一律 `400 {"error":"bad-request"}` —— 老节点那边只留一行 `[group] dispatch receipt failed …` 日志，群里从此看不到派单进度。**历史不会丢**：已有聊天记录里的 `progress`/`result` 仍照常显示成一行系统行。
+- **一条软断裂**：`meta.quote` 是 0.10 新增字段，老 hub 的 meta 白名单没有它，**静默丢弃、不报错**（HTTP 仍是 200）。代价是引用行消失，以及「首答胜」的去重判据在跨版本时失效。
+- **身份面不是断裂**：0.8.4 只有 v1 群级鉴权（`X-Peer-Auth: group` + groupKey HMAC），0.9 起有 v2（证书 + ed25519），0.10 默认两种都收（`allowLegacyGroupAuth` 默认 true）。
+- **私聊 ask 形状没变**：`/v1/answer` 三代一直是 `{status, reply|error, elapsedMs}`；0.10 只多一个错误码 `empty-reply`（对端跑完却没给正文），老调用方按 `peer error: …` 呈报即可。
+- `acceptDispatch` 双向安全：0.10 出站不再发 `X-Peer-Accept`，入站遇到老字段直接丢弃；老 hub 缺这个字段按「接单」处理。
+
+**升级口径**：hub 与所有成员**在同一个窗口内一起升到 0.10** —— 跨 0.10 线的群内派单双向都不工作，纪要与表决也要 hub 先到 0.10 才有数据。
+
+> 证据：每格都能追到代码或用例（`host/server.mjs`、`lib/group-*.mjs`、`host/test/group.test.mjs`、`lib/panel-group.test.mjs`）。`interop/run-interop.mjs` 的六行 A–F 目前只覆盖 **0.3.1 基线 ↔ 当前版本**，**不含**上面两组组合 —— 所以本表是代码路径结论，不是互通实跑结论。
+
 ## 安全模型
 
 - 配对码 6 位、10 分钟、一次性；每个伙伴两条独立密钥（我签给你的 / 你签给我的）。

package/client/cli-archives.test.mjs

@@ -5,6 +5,7 @@
 // 断言请求形状、stdout 文案与退出码（403/409 归「现在做不了」，其余算失败）。
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { listenOnRandomPort } from '../test-support/ports.mjs';
 import http from 'node:http';
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
@@ -12,6 +13,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { makeTempStateDir } from '../host/test/helpers.mjs';
 
+process.env.DSH_LAN_PEERS_LANG = 'zh';   // 语言钉死：断言写的是中文文案，不随机器 locale 漂移
+
 const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
 const MB = 1024 * 1024;
 
@@ -38,9 +41,7 @@ async function startAdmin(t, handler) {
       res.end(JSON.stringify(reply.body ?? {}));
     });
   });
-  const port = await new Promise((resolve) => {
-    server.listen(0, '127.0.0.1', () => resolve(server.address().port));
-  });
+  const { port } = await listenOnRandomPort(server);
   t.after(() => new Promise((resolve) => { server.close(() => resolve()); }));
   const dir = makeTempStateDir('dsh-lan-peers-cli-archives-');
   t.after(() => fs.rmSync(dir, { recursive: true, force: true }));

package/client/cli-code.test.mjs

@@ -5,6 +5,7 @@
 // 本机没 host / 拿不到 token 时 exit 2 并说清怎么起 host，绝不本地造一个码。
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { listenOnRandomPort } from '../test-support/ports.mjs';
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
 import http from 'node:http';
@@ -13,6 +14,8 @@ import { fileURLToPath } from 'node:url';
 import { createAdmin } from '../lib/admin.mjs';
 import { makeTempStateDir } from '../host/test/helpers.mjs';
 
+process.env.DSH_LAN_PEERS_LANG = 'zh';   // 语言钉死：断言写的是中文文案，不随机器 locale 漂移
+
 const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
 
 const run = (args) => new Promise((resolve) => {
@@ -59,7 +62,7 @@ async function startAdmin(t, { dir, code = '246810' } = {}) {
       });
     });
   });
-  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  await listenOnRandomPort(server);
   t.after(() => new Promise((resolve) => server.close(resolve)));
   return { admin, calls, state, url: 'http://127.0.0.1:' + server.address().port };
 }

package/client/cli-dispatch-settings.test.mjs

@@ -0,0 +1,300 @@
+// dsh-lan-peers · v0.8.5-α（契约 §5/§6，Lane H2）CLI：dispatch pending/approve/reject/settings
+// 与 dm <peer> <正文> --workspace/--perm。
+//
+// 全部只打本机回环管理接口（/api/lan-peers/dispatch*），所以这里起一个只实现那几条路由的
+// node:http 桩，真跑 cli.mjs 子进程，断言请求形状（含 token 头）、stdout 文案与退出码：
+// 401/403/409/501 归「本机现在做不了」（exit 2），其余算失败（exit 1）。
+// 铁律（契约 §0）：跨机只走 id+name；日志只记 id 前 8 位、权限档、工作区 id、字节数。
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { listenOnRandomPort } from '../test-support/ports.mjs';
+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 { makeTempStateDir, writeJson0600 } from '../host/test/helpers.mjs';
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
+const TOKEN = 'cli-dispatch-settings-token';
+const PEER_ID = 'peer-b-1234';
+
+function runAsync(args, env = {}) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI, ...args],
+      // 语言钉死：断言写的是中文文案，不能随机器 locale 翻成英文。
+      { encoding: 'utf8', env: { ...process.env, DSH_LAN_PEERS_LANG: 'zh', ...env } },
+      (error, stdout, stderr) => {
+        resolve({ status: error ? error.code : 0, stdout, stderr });
+      });
+  });
+}
+
+async function startAdmin(t, handler, { token = TOKEN } = {}) {
+  const seen = [];
+  const server = http.createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', () => {
+      const call = {
+        method: req.method,
+        url: req.url,
+        token: req.headers['x-lan-peers-token'] ?? '',
+        contentType: req.headers['content-type'] ?? '',
+        body: raw === '' ? null : JSON.parse(raw),
+      };
+      seen.push(call);
+      const reply = handler(call) ?? {};
+      res.writeHead(reply.status ?? 200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(reply.body ?? {}));
+    });
+  });
+  const { port } = await listenOnRandomPort(server);
+  t.after(() => new Promise((resolve) => { server.close(() => resolve()); }));
+
+  const dir = makeTempStateDir('dsh-lan-peers-cli-dispatch-');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  writeJson0600(path.join(dir, 'peers.json'), {
+    peers: { [PEER_ID]: { name: '书房', baseUrl: 'http://10.0.0.2:7788', secret: 's', inboundSecret: 'i' } },
+  });
+  if (token !== '') fs.writeFileSync(path.join(dir, 'admin-token'), token + '\n', { mode: 0o600 });
+  return { seen, url: 'http://127.0.0.1:' + port, dir };
+}
+
+const NOW = Date.now();
+const PENDING = [
+  {
+    approvalId: 'ap-1', from: 'peer-b-12345678', workspaceId: 'main', workspaceName: '主工作区',
+    permission: 'danger-full-access', promptBytes: 64, at: NOW, expiresAt: NOW + 120_000,
+  },
+];
+const PREFS = {
+  defaultWorkspaceId: 'main',
+  maxPermission: 'workspace-write',
+  workspaces: [
+    { id: 'main', name: '主工作区', path: 'D:/work/main' },
+    { id: 'docs', name: '文档', path: 'D:/work/docs' },
+  ],
+};
+
+test('dispatch pending：GET dispatch/pending，逐行 id/来源/工作区/权限/剩余秒数', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { items: PENDING } }));
+  const out = await runAsync(['dispatch', 'pending', '--url', admin.url, '--state-dir', admin.dir]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(admin.seen.length, 1);
+  assert.equal(admin.seen[0].method, 'GET');
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dispatch/pending');
+  assert.equal(admin.seen[0].token, TOKEN);
+  assert.match(out.stdout, /^ap-1\t来自 peer-b-1\t工作区 main\/主工作区\tdanger-full-access\t剩余 \d+s$/m);
+  assert.match(out.stderr, /待批准 1 条/);
+});
+
+test('dispatch pending：没有待批准时只打一行说明，空表头不出现', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { items: [] } }));
+  const out = await runAsync(['dispatch', 'pending', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(out.status, 0);
+  assert.equal(out.stdout.trim(), '');
+  assert.match(out.stderr, /（没有待批准请求）/);
+});
+
+test('dispatch approve <id>：POST { id } 并打印 state', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { ok: true, state: 'approved' } }));
+  const out = await runAsync(['dispatch', 'approve', 'ap-1', '--url', admin.url, '--state-dir', admin.dir]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(admin.seen[0].method, 'POST');
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dispatch/approve');
+  assert.deepEqual(admin.seen[0].body, { id: 'ap-1' });
+  assert.match(out.stdout, /^已批准 ap-1（state=approved）$/m);
+});
+
+test('dispatch reject <id>：POST { id }；未知 approval（404）exit 1，501 exit 2', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { ok: true, state: 'rejected' } }));
+  const ok = await runAsync(['dispatch', 'reject', 'ap-2', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(ok.status, 0, ok.stderr);
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dispatch/reject');
+  assert.deepEqual(admin.seen[0].body, { id: 'ap-2' });
+  assert.match(ok.stdout, /^已拒绝 ap-2（state=rejected）$/m);
+
+  const missing = await startAdmin(t, () => ({ status: 404, body: { error: 'unknown-approval' } }));
+  const notFound = await runAsync(['dispatch', 'reject', 'ap-3', '--url', missing.url, '--state-dir', missing.dir]);
+  assert.equal(notFound.status, 1, '404 是业务失败，不是「现在做不了」');
+  assert.match(notFound.stderr, /派单设置操作失败: 404 unknown-approval/);
+
+  const off = await startAdmin(t, () => ({ status: 501, body: { error: 'dispatch-unsupported' } }));
+  const unsupported = await runAsync(['dispatch', 'reject', 'ap-4', '--url', off.url, '--state-dir', off.dir]);
+  assert.equal(unsupported.status, 2, '501 = 本机还没有门面');
+});
+
+test('dispatch approve 缺 id：直接报用法，一个请求都不发', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { ok: true } }));
+  const out = await runAsync(['dispatch', 'approve', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(out.status, 1);
+  assert.match(out.stderr, /需要 approvalId/);
+  assert.equal(admin.seen.length, 0);
+});
+
+test('dispatch settings：只读时 GET dispatch/settings，打印默认/上限/工作区清单（含 path）', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: PREFS }));
+  const out = await runAsync(['dispatch', 'settings', '--url', admin.url, '--state-dir', admin.dir]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(admin.seen[0].method, 'GET');
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dispatch/settings');
+  assert.match(out.stdout, /^默认工作区 main\t最大授权 workspace-write\t工作区 2 个$/m);
+  assert.match(out.stdout, /^  main\t主工作区\tD:\/work\/main$/m);
+  assert.match(out.stdout, /^  docs\t文档\tD:\/work\/docs$/m);
+});
+
+test('dispatch settings --default X --max-perm Y：POST 只带改动的字段；非法档位在本地挡住', async (t) => {
+  const admin = await startAdmin(t, (call) => ({ body: { ...PREFS, ...call.body } }));
+  const out = await runAsync([
+    'dispatch', 'settings', '--default', 'docs', '--max-perm', 'read-only',
+    '--url', admin.url, '--state-dir', admin.dir,
+  ]);
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(admin.seen[0].method, 'POST');
+  assert.deepEqual(admin.seen[0].body, { defaultWorkspaceId: 'docs', maxPermission: 'read-only' });
+  assert.match(out.stdout, /^派单设置已保存: 默认 docs · 最大授权 read-only · 工作区 2 个$/m);
+
+  const bad = await runAsync([
+    'dispatch', 'settings', '--max-perm', 'root', '--url', admin.url, '--state-dir', admin.dir,
+  ]);
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /--max-perm 只能是 read-only \| workspace-write \| danger-full-access/);
+  assert.equal(admin.seen.length, 1, '非法档位不发第二个请求');
+});
+
+test('dm <peer> <正文> --workspace/--perm：body 带两个字段，打印实际生效的那组', async (t) => {
+  const admin = await startAdmin(t, () => ({
+    body: {
+      ok: true, id: 'm-5', sessionId: 's-1', reply: '只读跑完了', elapsedMs: 30, reused: true,
+      workspace: { id: 'docs', name: '文档' }, permission: 'read-only',
+    },
+  }));
+  const out = await runAsync([
+    'dm', '书房', '看下文档目录', '--workspace', 'docs', '--perm', 'read-only',
+    '--url', admin.url, '--state-dir', admin.dir,
+  ]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.deepEqual(admin.seen[0].body, {
+    peerId: PEER_ID, text: '看下文档目录', workspaceId: 'docs', permission: 'read-only',
+  });
+  assert.match(out.stdout, /workspace=docs perm=read-only$/m);
+  assert.doesNotMatch(out.stderr, /看下文档目录/, '正文不进 stderr');
+});
+
+test('dm 完全权限：202 待确认时打印「等待对方确认」而不是假装有回复', async (t) => {
+  const admin = await startAdmin(t, () => ({
+    status: 202,
+    body: { ok: true, pendingApproval: true, approvalId: 'ap-7', expiresAt: Date.now() + 600_000 },
+  }));
+  const out = await runAsync([
+    'dm', '书房', '把构建跑一遍', '--perm', 'danger-full-access',
+    '--url', admin.url, '--state-dir', admin.dir,
+  ]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.match(out.stdout, /^已发给 书房：等待对方确认这次派单（approval ap-7，剩余 \d+ 秒）$/m);
+  assert.match(out.stdout, /^approvalId=ap-7 state=pending-approval$/m);
+  assert.equal(/回复:/.test(out.stdout), false, '还没执行就没有回复可说');
+});
+
+test('dm 不带工作区与档位：请求体与以前一模一样（契约 §2 的「都不传」）', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { ok: true, id: 'm-6', sessionId: 's-1', reply: 'ok', elapsedMs: 3, reused: false } }));
+  const out = await runAsync(['dm', '书房', '在吗', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(out.status, 0, out.stderr);
+  assert.deepEqual(admin.seen[0].body, { peerId: PEER_ID, text: '在吗' });
+  assert.match(out.stdout, /^id=m-6 sessionId=s-1 reused=false elapsedMs=3$/m);
+});
+
+test('语言钉住：每个 client/cli*.test.mjs 都显式设了 DSH_LAN_PEERS_LANG=zh', async () => {
+  // 中文正则断言若依赖机器 locale，换到 en-US 机器会整体翻成英文而失败；
+  // 这里把「必须显式钉住」变成一条断言，防止以后新加的 CLI 用例又漂回去。
+  const dir = path.dirname(CLI);
+  const files = fs.readdirSync(dir).filter((name) => /^cli.*\.test\.mjs$/.test(name));
+  assert.ok(files.length >= 8, '至少覆盖现有的 8 个 CLI 测试文件');
+  for (const name of files) {
+    const text = fs.readFileSync(path.join(dir, name), 'utf8');
+    assert.match(text, /DSH_LAN_PEERS_LANG['\]]?\s*[:=]\s*'zh'/, name + ' 必须把语言钉成 zh');
+  }
+});
+
+// ---------------------------------------------------------------------------
+// v0.9.0-α：dispatch settings 的会话复用三元键（值与面板、管理接口同一份 config.json）。
+// 口径：不带参数就显示（含单位）；带了就只发那几个键；看不懂的输入本地挡住、非零退出。
+// ---------------------------------------------------------------------------
+const REUSE_PREFS = {
+  ...PREFS,
+  sessionReuseTtlMs: 86_400_000,
+  sessionNewApprovalWindowMs: 604_800_000,
+  sessionNewRequestAllowed: false,
+};
+
+test('dispatch settings：只读时打印会话复用三值（带单位），老宿主没有这三个键就不打这一行', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: REUSE_PREFS }));
+  const out = await runAsync(['dispatch', 'settings', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(out.status, 0, out.stderr);
+  assert.match(out.stdout, /^会话复用 24 小时 · 新建批准窗 7 天 · 接受新会话请求 否$/m);
+  // 既有的默认/上限/清单三行一个字都没变。
+  assert.match(out.stdout, /^默认工作区 main\t最大授权 workspace-write\t工作区 2 个$/m);
+  assert.match(out.stdout, /^  docs\t文档\tD:\/work\/docs$/m);
+
+  const old = await startAdmin(t, () => ({ body: PREFS }));
+  const oldOut = await runAsync(['dispatch', 'settings', '--url', old.url, '--state-dir', old.dir]);
+  assert.equal(oldOut.status, 0);
+  assert.equal(/会话复用/.test(oldOut.stdout), false, '老宿主没有这三个键，不假装是「关闭」');
+});
+
+test('dispatch settings --reuse-ttl/--approval-window/--allow-new-request：POST 只带这几个键并回显', async (t) => {
+  const admin = await startAdmin(t, () => ({
+    body: {
+      ...PREFS,
+      sessionReuseTtlMs: 604_800_000,
+      sessionNewApprovalWindowMs: 86_400_000,
+      sessionNewRequestAllowed: false,
+    },
+  }));
+  const out = await runAsync([
+    'dispatch', 'settings',
+    '--reuse-ttl', '7d', '--approval-window', '1d', '--allow-new-request', 'false',
+    '--url', admin.url, '--state-dir', admin.dir,
+  ]);
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(admin.seen[0].method, 'POST');
+  assert.deepEqual(admin.seen[0].body, {
+    sessionReuseTtlMs: 604_800_000,
+    sessionNewApprovalWindowMs: 86_400_000,
+    sessionNewRequestAllowed: false,
+  });
+  assert.match(out.stdout, /^派单设置已保存: 默认 main · 最大授权 workspace-write · 工作区 2 个$/m);
+  assert.match(out.stdout, /^会话复用 7 天 · 新建批准窗 24 小时 · 接受新会话请求 否$/m);
+
+  // off / 0 都是「关闭」，纯毫秒照收。
+  const off = await startAdmin(t, (call) => ({ body: { ...REUSE_PREFS, ...call.body } }));
+  const offOut = await runAsync([
+    'dispatch', 'settings', '--reuse-ttl', 'off', '--approval-window', '604800000',
+    '--url', off.url, '--state-dir', off.dir,
+  ]);
+  assert.equal(offOut.status, 0, offOut.stderr);
+  assert.deepEqual(off.seen[0].body, { sessionReuseTtlMs: 0, sessionNewApprovalWindowMs: 604_800_000 });
+  assert.match(offOut.stdout, /^会话复用 关闭 · 新建批准窗 7 天/m);
+});
+
+test('dispatch settings：看不懂或越界的会话复用输入本地挡住，非零退出且一个请求都不发', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: REUSE_PREFS }));
+  for (const args of [
+    ['--reuse-ttl', '45d'],
+    ['--reuse-ttl', 'abc'],
+    ['--approval-window', '12y'],
+    ['--allow-new-request', 'maybe'],
+  ]) {
+    const out = await runAsync(['dispatch', 'settings', ...args, '--url', admin.url, '--state-dir', admin.dir]);
+    assert.equal(out.status, 1, args.join(' ') + ' 必须以 1 退出');
+    assert.equal(out.stderr.includes('at '), false, '不许甩栈：' + out.stderr);
+    assert.match(out.stderr, /--reuse-ttl 只认|--approval-window 只认|--allow-new-request 只认/);
+  }
+  assert.equal(admin.seen.length, 0, '非法输入不发请求');
+});

package/client/cli-dm.test.mjs

@@ -0,0 +1,186 @@
+// dsh-lan-peers · v0.8.5-α（契约 §5，Lane G2）CLI：dm <peer> <正文> / dm log / dm sync。
+//
+// 三条命令都只打本机回环管理接口（/api/lan-peers/dm*），所以这里起一个只实现那几条
+// 路由的 node:http 桩，真跑 cli.mjs 子进程，断言请求形状（含 token 头）、stdout 文案与
+// 退出码：401/403/409/501 归「本机现在做不了」（exit 2），其余算失败（exit 1）。
+// 铁律（契约 §0）：正文可以进 stdout（用户自己要看的），但绝不进 stderr/日志。
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { listenOnRandomPort } from '../test-support/ports.mjs';
+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 { makeTempStateDir, writeJson0600 } from '../host/test/helpers.mjs';
+
+process.env.DSH_LAN_PEERS_LANG = 'zh';   // 语言钉死：断言写的是中文文案，不随机器 locale 漂移
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.mjs');
+const TOKEN = 'cli-dm-token';
+const PEER_ID = 'peer-b-1234';
+
+function runAsync(args, env = {}) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI, ...args], { encoding: 'utf8', env: { ...process.env, ...env } },
+      (error, stdout, stderr) => {
+        resolve({ status: error ? error.code : 0, stdout, stderr });
+      });
+  });
+}
+
+/** 只实现 /api/lan-peers/dm* 的管理接口桩；handler(call) 决定状态码与响应体。 */
+async function startAdmin(t, handler, { token = TOKEN } = {}) {
+  const seen = [];
+  const server = http.createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', () => {
+      const call = {
+        method: req.method,
+        url: req.url,
+        token: req.headers['x-lan-peers-token'] ?? '',
+        contentType: req.headers['content-type'] ?? '',
+        body: raw === '' ? null : JSON.parse(raw),
+      };
+      seen.push(call);
+      const reply = handler(call) ?? {};
+      res.writeHead(reply.status ?? 200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(reply.body ?? {}));
+    });
+  });
+  const { port } = await listenOnRandomPort(server);
+  t.after(() => new Promise((resolve) => { server.close(() => resolve()); }));
+
+  const dir = makeTempStateDir('dsh-lan-peers-cli-dm-');
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  writeJson0600(path.join(dir, 'peers.json'), {
+    peers: { [PEER_ID]: { name: '书房', baseUrl: 'http://10.0.0.2:7788', secret: 's', inboundSecret: 'i' } },
+  });
+  if (token !== '') fs.writeFileSync(path.join(dir, 'admin-token'), token + '\n', { mode: 0o600 });
+  return { seen, url: 'http://127.0.0.1:' + port, dir };
+}
+
+const AT = 1_760_000_000_000;
+const HISTORY = [
+  { id: 'm-1', ts: AT, from: 'self', text: '我叫你小助手', sessionId: 's-1', state: 'sent' },
+  { id: 'm-2', ts: AT + 900, from: 'peer', text: '好的，记住了', sessionId: 's-1', state: 'sent' },
+];
+
+// ---------------------------------------------------------------------------
+// dm <peer> <正文>
+// ---------------------------------------------------------------------------
+
+test('dm <peer> <正文>：POST dm/send 带 token，打印回复与 sessionId/reused', async (t) => {
+  const admin = await startAdmin(t, () => ({
+    body: { ok: true, id: 'm-3', sessionId: 's-1', reply: '还记得，你让我叫小助手', elapsedMs: 1227, reused: true },
+  }));
+  const out = await runAsync(['dm', '书房', '我刚才让你叫什么？', '--url', admin.url, '--state-dir', admin.dir]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.match(out.stdout, /^回复: 还记得，你让我叫小助手$/m);
+  assert.match(out.stdout, /^id=m-3 sessionId=s-1 reused=true elapsedMs=1227$/m);
+  assert.match(out.stderr, /发送中 → 书房 · 27 字节/, '先把「往哪发、多大」说清楚');
+
+  assert.equal(admin.seen.length, 1);
+  assert.equal(admin.seen[0].method, 'POST');
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dm/send');
+  assert.deepEqual(admin.seen[0].body, { peerId: PEER_ID, text: '我刚才让你叫什么？' }, 'CLI 传 peerId，不传名字');
+  assert.equal(admin.seen[0].token, TOKEN, '管理接口 token 从 state-dir 读出来带上');
+  assert.doesNotMatch(out.stderr, /我刚才让你叫什么/, '正文不得进 stderr（日志口径只记字节数）');
+});
+
+test('dm <peer> <正文>：本机就能拦下的错误不发请求（未知对端 / 空正文 / 缺参数）', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { ok: true } }));
+
+  const unknown = await runAsync(['dm', '不存在的伙伴', '在吗', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(unknown.status, 1);
+  assert.match(unknown.stderr, /未知对端: 不存在的伙伴/);
+
+  const blank = await runAsync(['dm', '书房', '   ', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(blank.status, 1);
+  assert.match(blank.stderr, /用法: dsh-lan-peers dm <peer> <正文>/);
+
+  const missing = await runAsync(['dm', '书房', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(missing.status, 1);
+  assert.match(missing.stderr, /用法: dsh-lan-peers dm <peer> <正文>/);
+
+  assert.equal(admin.seen.length, 0, '本地就能拦下的错误不发请求');
+});
+
+// ---------------------------------------------------------------------------
+// dm log <peer>
+// ---------------------------------------------------------------------------
+
+test('dm log <peer> --limit N：GET dm?peer=，只打印最近 N 条', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { peer: { peerId: PEER_ID, name: '书房' }, messages: HISTORY } }));
+  const out = await runAsync(['dm', 'log', '书房', '--limit', '1', '--url', admin.url, '--state-dir', admin.dir]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(admin.seen.length, 1);
+  assert.equal(admin.seen[0].method, 'GET');
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dm?peer=' + PEER_ID);
+  assert.equal(admin.seen[0].token, TOKEN);
+
+  const lines = out.stdout.trim().split('\n');
+  assert.equal(lines.length, 1, '--limit 1 只打印一条');
+  assert.equal(lines[0].split('\t')[1], '对方');
+  assert.equal(lines[0].split('\t')[2], 'm-2');
+  assert.match(lines[0], /好的，记住了$/);
+  assert.match(out.stderr, /共 2 条，打印最近 1 条/);
+});
+
+test('dm log <peer>：默认打印全部（不超过 20 条），没有记录时也给出确定输出', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { peer: { peerId: PEER_ID, name: '书房' }, messages: HISTORY } }));
+  const out = await runAsync(['dm', 'log', '书房', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(out.status, 0, out.stderr);
+  const lines = out.stdout.trim().split('\n');
+  assert.equal(lines.length, 2);
+  assert.equal(lines[0].split('\t')[1], '我');
+  assert.match(lines[0], /^\d{4}-\d{2}-\d{2}T/);
+  assert.match(out.stderr.trim(), /共 2 条$/);
+
+  const empty = await startAdmin(t, () => ({ body: { peer: { peerId: PEER_ID, name: '书房' }, messages: [] } }));
+  const none = await runAsync(['dm', 'log', '书房', '--url', empty.url, '--state-dir', empty.dir]);
+  assert.equal(none.status, 0, none.stderr);
+  assert.equal(none.stdout, '');
+  assert.match(none.stderr, /共 0 条/);
+
+  const bad = await runAsync(['dm', 'log', '书房', '--limit', 'abc', '--url', admin.url, '--state-dir', admin.dir]);
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /--limit 必须是正整数/);
+});
+
+// ---------------------------------------------------------------------------
+// dm sync <peer>
+// ---------------------------------------------------------------------------
+
+test('dm sync <peer>：POST dm/sync { peerId }，打印 added/total', async (t) => {
+  const admin = await startAdmin(t, () => ({ body: { ok: true, added: 3, total: 5 } }));
+  const out = await runAsync(['dm', 'sync', '书房', '--url', admin.url, '--state-dir', admin.dir]);
+
+  assert.equal(out.status, 0, out.stderr);
+  assert.equal(out.stdout.trim(), '已对齐 added=3 total=5');
+  assert.equal(admin.seen.length, 1);
+  assert.equal(admin.seen[0].url, '/api/lan-peers/dm/sync');
+  assert.equal(admin.seen[0].method, 'POST');
+  assert.deepEqual(admin.seen[0].body, { peerId: PEER_ID });
+});
+
+test('失败口径：501/409 归「本机现在做不了」exit 2，其余 exit 1，且都不把正文带上日志', async (t) => {
+  const unsupported = await startAdmin(t, () => ({ status: 501, body: { error: 'dm-unsupported' } }));
+  const unwired = await runAsync(['dm', '书房', '在吗', '--url', unsupported.url, '--state-dir', unsupported.dir]);
+  assert.equal(unwired.status, 2);
+  assert.match(unwired.stderr, /私聊失败: 501 dm-unsupported/);
+
+  const offline = await startAdmin(t, () => ({ status: 409, body: { error: 'peer-offline' } }));
+  const down = await runAsync(['dm', 'sync', '书房', '--url', offline.url, '--state-dir', offline.dir]);
+  assert.equal(down.status, 2);
+  assert.match(down.stderr, /私聊失败: 409 peer-offline/, '目标离线要原样给出 reason');
+
+  const broken = await startAdmin(t, () => ({ status: 500, body: { error: 'boom' } }));
+  const failed = await runAsync(['dm', '书房', '在吗', '--url', broken.url, '--state-dir', broken.dir]);
+  assert.equal(failed.status, 1);
+  assert.match(failed.stderr, /私聊失败: 500 boom/);
+  assert.doesNotMatch(failed.stderr, /在吗/, '正文不得进错误输出');
+});