dsh-remote-agent 0.8.0 → 0.9.0

package/lib/node/share-service.js

@@ -0,0 +1,213 @@
+/**
+ * 工作区 SMB 共享（2026-10-17）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 这个模块做什么
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 在**副机**上把一个工作区目录通过 SMB 共享出去，让主机可以：
+ *
+ *     net use X: \\<副机IP>\dsh-work
+ *
+ * 像本地盘一样浏览/编辑 —— 这是"用本地 IDE 打开副机项目"的唯一现实路径。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ⚠ 安全模型变化（**必须让用户知情**，这是本模块存在的最大风险）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 开启共享后，**插件的安全边界被完全绕过**：
+ *
+ *   · `roots` 不再生效 —— Windows 内核直接读写，插件无法拦截
+ *   · `denyPaths` 不再生效 —— 同上
+ *   · 「清单先于字节」失效 —— 中间产物、日志、`.env`、`.git` 里的密钥
+ *     全部对主机可见（不再只有 `role:final` 能过河）
+ *   · **新增凭证面** —— 主机需要副机的 Windows 账号（或副机建一个共享账号），
+ *     这比模型 key 更敏感（能读写整个共享目录）
+ *
+ * 所以本模块的每个入口都要求**显式二次确认**（`confirm: 'yes'`），
+ * 且面板上必须显示完整风险说明。这是产品决策：**让用户知情地选择，
+ * 而不是偷偷放宽边界**。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 权限模型：只读 / 读写
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ *   `read`  → `New-SmbShare -ReadAccess`   只读：主机能看、不能改
+ *   `write` → `New-SmbShare -ChangeAccess` 读写：能看能改（不给 FullAccess ——
+ *             那会连共享的 ACL 一起给出，主机能改权限）
+ *
+ * **默认只读**：绝大多数"用 IDE 打开看代码"的需求，只读就够；写权限要额外
+ * 一次确认。这是最小权限原则的落点。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 需要管理员权限（**这是硬约束**）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * `New-SmbShare` / `Remove-SmbShare` 都需要管理员。而 DSH 通常以普通用户
+ * 运行。所以本模块**不自己提权**（在 Node 里弹 UAC 不可靠且会被杀软拦），
+ * 而是：
+ *
+ *   · 探测当前是否管理员 → 不是就返回一条**可复制的提权命令**
+ *   · 用户自己开管理员 PowerShell 跑那一条 → 再回来点「已开启」确认
+ *
+ * 这比"假装能一键"诚实：一次 UAC 提权失败的表现（静默失败、被拦、
+ * 权限半生效）比让用户手动跑一条命令难排查得多。
+ */
+
+import { spawnSync } from 'node:child_process'
+
+/** 共享名前缀 —— 固定前缀便于识别与清理（不会误删用户的其它共享）。 */
+export const SHARE_NAME_PREFIX = 'dsh-work'
+
+/** 共享名上限（Windows 限制 80 字符，留余量）。 */
+const SHARE_NAME_MAX = 64
+
+/** 访问级别。 */
+export const SHARE_ACCESS = Object.freeze({
+  READ: 'read',
+  WRITE: 'write',
+})
+
+/**
+ * 由工作区路径生成一个**稳定**的共享名。
+ *
+ * 为什么要稳定：用户可能对同一个目录反复开关共享，共享名必须一致，
+ * 否则每次都会留下一个孤儿共享。用路径的短哈希做后缀。
+ *
+ * @param {string} dir 工作区绝对路径
+ * @returns {string} 例如 `dsh-work-a1b2c3`
+ */
+export function shareNameFor(dir) {
+  const base = SHARE_NAME_PREFIX
+  // 简单稳定哈希（FNV-1a 32bit）—— 不需要密码学强度，只要同一路径同名
+  let h = 0x811c9dc5
+  const s = String(dir)
+  for (let i = 0; i < s.length; i += 1) {
+    h ^= s.charCodeAt(i)
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return `${base}-${h.toString(16).padStart(8, '0')}`.slice(0, SHARE_NAME_MAX)
+}
+
+/**
+ * 判断当前进程是否管理员（Windows）。
+ *
+ * 非 Windows 恒 false —— 本功能是 Windows 专属（SMB 共享）。
+ */
+export function isAdmin() {
+  if (process.platform !== 'win32') return false
+  try {
+    // `net session` 需要管理员，成功即管理员。比读 token 简单可靠。
+    const r = spawnSync('net', ['session'], { stdio: 'ignore', windowsHide: true, timeout: 5000 })
+    return r.status === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 列出本机所有 SMB 共享。
+ *
+ * `net share` 不需要管理员（只读查询），所以即使非管理员也能用于**展示**。
+ *
+ * @returns {Array<{name:string, path:string}>}
+ */
+export function listShares() {
+  if (process.platform !== 'win32') return []
+  try {
+    const r = spawnSync('net', ['share'], { encoding: 'utf8', windowsHide: true, timeout: 8000 })
+    if (r.status !== 0 || typeof r.stdout !== 'string') return []
+    const out = []
+    for (const line of r.stdout.split(/\r?\n/)) {
+      // 形如：`dsh-work-a1b2c3  D:\work                        `
+      const m = /^(\S+)\s+([A-Za-z]:\\[^\s]*)/.exec(line.trim())
+      if (m) out.push({ name: m[1], path: m[2] })
+    }
+    return out
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 查某个目录是否已被共享（返回共享名）。
+ * @param {string} dir
+ * @returns {string|null}
+ */
+export function findShareForDir(dir) {
+  const want = String(dir).replace(/[\\/]+$/, '').toLowerCase()
+  for (const s of listShares()) {
+    if (s.path.replace(/[\\/]+$/, '').toLowerCase() === want) return s.name
+  }
+  return null
+}
+
+/**
+ * 生成**可复制的提权命令**（非管理员时给用户）。
+ *
+ * 为什么返回命令而不是自己提权：
+ *   · Node 里弹 UAC 需要额外依赖或 PowerShell 间接调用，且被安全软件拦时
+ *     表现为静默失败 —— 比手动跑一条命令难排查得多
+ *   · 用户自己开管理员 PowerShell 跑一条命令，失败时**能看到真实错误**
+ *
+ * @param {object} o
+ * @param {string} o.dir 要共享的目录
+ * @param {'read'|'write'} o.access
+ * @returns {{shareName:string, command:string}}
+ */
+export function buildShareCommand({ dir, access = SHARE_ACCESS.READ }) {
+  const shareName = shareNameFor(dir)
+  const accessFlag = access === SHARE_ACCESS.WRITE ? 'ChangeAccess' : 'ReadAccess'
+  // 用户名：用当前用户（`$env:USERNAME`）。共享给"本机这个账号"，
+  // 主机侧用同一套凭证连（或副机另建账号 —— 那是用户的事，文档里说明）。
+  const cmd = [
+    'New-SmbShare',
+    `-Name '${shareName}'`,
+    `-Path '${String(dir).replace(/'/g, "''")}'`,
+    `-${accessFlag} "$env:USERNAME"`,
+  ].join(' ')
+  return { shareName, command: cmd }
+}
+
+/**
+ * 生成卸载命令。
+ * @param {string} shareName
+ */
+export function buildUnshareCommand(shareName) {
+  return `Remove-SmbShare -Name '${String(shareName).replace(/'/g, "''")}' -Force`
+}
+
+/**
+ * 生成主机侧的映射命令（面板展示给用户复制）。
+ *
+ * @param {object} o
+ * @param {string} o.host 副机地址（IP 或主机名）
+ * @param {string} o.shareName
+ * @param {string} [o.drive] 盘符，默认 X:
+ * @returns {string}
+ */
+export function buildMountCommand({ host, shareName, drive = 'X:' }) {
+  const d = String(drive).replace(/:?$/, ':')
+  return `net use ${d} \\\\${host}\\${shareName} /persistent:yes`
+}
+
+/**
+ * 探测状态：当前是否管理员 + 哪些 dsh-work 共享已存在。
+ *
+ * @param {object} [o]
+ * @param {string[]} [o.dirs] 要查的工作区目录
+ * @returns {{platform:string, admin:boolean, supported:boolean, shares:Array, perDir:object}}
+ */
+export function probeShareState({ dirs = [] } = {}) {
+  const supported = process.platform === 'win32'
+  if (!supported) {
+    return { platform: process.platform, admin: false, supported: false, shares: [], perDir: {} }
+  }
+  const shares = listShares().filter((s) => s.name.startsWith(SHARE_NAME_PREFIX))
+  const perDir = {}
+  for (const d of dirs) {
+    if (typeof d !== 'string' || d === '') continue
+    perDir[d] = findShareForDir(d)
+  }
+  return { platform: process.platform, admin: isAdmin(), supported, shares, perDir }
+}

package/lib/node/transport.js

@@ -68,6 +68,9 @@ const E2E_REQUIRED_TYPES = new Set([
   HUB_TO_NODE.ARTIFACT_CANCEL,
   // 远程文件请求（提案 #25）：目录结构与文件内容是敏感信息，必须加密。
   HUB_TO_NODE.FS_REQ,
+  // 工作区共享请求（2026-10-17）：帧里含工作区**绝对路径**（暴露副机的
+  // 目录结构），必须加密。
+  HUB_TO_NODE.SHARE_REQ,
 ])
 
 /** 副机侧永远明文的帧类型（握手/心跳/交换本身）。 */
@@ -111,6 +114,9 @@ export class NodeTransport extends EventEmitter {
     this.hello = o.hello
     this.heartbeatMs = o.heartbeatMs ?? HEARTBEAT_MS
     this.conn = undefined
+    // 并发闸门（2026-10-17 修 L1）：防 start() 被调两次时开两条 TCP 连接。
+    // 见 connectOnce 的说明。
+    this.connecting = false
     this.online = false
     this.attempt = 0
     this.stopped = false
@@ -170,6 +176,25 @@ export class NodeTransport extends EventEmitter {
 
   async connectOnce() {
     if (this.stopped) return
+
+    // ⚠ 并发闸门（2026-10-17 修 L1）：`start()` 可能被调两次（cordis effect
+    // 热重载会重跑 applyWorker）。没有这道闸门就会开两条 TCP 连接，随后陈旧
+    // 连接的 close 把 `this.conn` 清成 undefined —— 活着的新连接变成引用丢失
+    // 的孤儿，发送全失败，重连又被中继 duplicate-node 拒，副机永久失联。
+    //
+    // hub 侧的 `RelayLink` 早有这道闸门（那是用真中继动态测试查出来的），
+    // 副机侧当时没对称复制过来。
+    if (this.connecting) return
+    this.connecting = true
+    try {
+      await this.connectOnceInner()
+    } finally {
+      this.connecting = false
+    }
+  }
+
+  async connectOnceInner() {
+    if (this.stopped) return
     const url = this.resolveUrl()
     if (url === '') {
       this.emit('error', new Error(`transport: invalid url "${this.rawUrl}"`))
@@ -279,6 +304,17 @@ export class NodeTransport extends EventEmitter {
     })
 
     conn.on('close', (code, reason) => {
+      // ⚠ 陈旧连接校验（2026-10-17 修 L1，与并发闸门配套）。
+      //
+      // 只有"当前连接"的 close 才有权清理状态。否则陈旧连接的 close 会把
+      // 活着的新连接引用清掉（`this.conn = undefined`）→ 新连接变孤儿 →
+      // 发送全失败 + 重连被中继 duplicate-node 拒 → 副机永久失联。
+      //
+      // 这是 hub 侧 `RelayLink` 早已有的第二条不变式，副机侧当时没复制过来。
+      if (this.conn !== conn) {
+        // 不是当前连接：什么都不做（它的 close 与当前状态无关）
+        return
+      }
       const wasOnline = this.online
       this.online = false
       this.conn = undefined
@@ -384,7 +420,24 @@ export class NodeTransport extends EventEmitter {
           this.e2e = null
         }
         this.emit('e2e', 'reset')
-        if (!this.e2eOffer) this.beginE2EOffer()
+        // ⚠ 时间窗去抖（2026-10-17 修）：常量 `E2E_REOFFER_DEBOUNCE_MS` 原先是
+        // **死代码** —— 声明了 250ms 窗口但从未被引用，实际只在 `e2eOffer` 在途
+        // 时跳过。而 `e2eOffer` 在提议发出后很快就被清空（见 beginE2EOffer 的
+        // then 分支），所以 reset 风暴下**每次 reset 都会重发**一次提议。
+        //
+        // 现在按常量做时间窗：距上次提议不足 250ms 就不重发（等它自然完成）。
+        //
+        // ⚠ 常量是**实例字段**（`E2E_REOFFER_DEBOUNCE_MS = 250`，不是 static），
+        // 所以必须经 `this.` 读 —— 裸写会 ReferenceError（模块作用域里没有它）。
+        const debounceMs = typeof this.E2E_REOFFER_DEBOUNCE_MS === 'number'
+          ? this.E2E_REOFFER_DEBOUNCE_MS
+          : 250
+        const now = Date.now()
+        const last = typeof this.lastE2EOfferAt === 'number' ? this.lastE2EOfferAt : 0
+        if (!this.e2eOffer && now - last >= debounceMs) {
+          this.lastE2EOfferAt = now
+          this.beginE2EOffer()
+        }
         return
       }
       this.emit('error', new Error(`relay error: ${code} ${frame.d?.message ?? ''}`.trim()))

package/lib/protocol.js

@@ -31,6 +31,19 @@ export const HUB_TO_NODE = Object.freeze({
    * 必须加密（E2E_REQUIRED_TYPES）：目录结构 / 文件内容都是敏感信息。
    */
   FS_REQ: 'fs/req',
+  /**
+   * 工作区共享请求（2026-10-17）：hub → node 的 SMB 共享操作。
+   *
+   * 载荷 `{ op: 'probe'|'plan'|'unshare-plan', ...params }`。
+   *
+   * ⚠ 本帧**只做探测与生成命令**，不执行 `New-SmbShare` —— 那需要管理员，
+   * 而 DSH 通常以普通用户运行。执行由用户在提权 PowerShell 里手动做
+   * （面板给出可复制的命令）。这个设计是刻意的：Node 里提权失败的表现
+   * （静默失败 / 被安全软件拦 / 权限半生效）比让用户手动跑一条命令难排查。
+   *
+   * 必须加密（E2E_REQUIRED_TYPES）：帧里含工作区绝对路径。
+   */
+  SHARE_REQ: 'share/req',
   TASK_START: 'task/start',
   TASK_CANCEL: 'task/cancel',
   TASK_QUERY: 'task/query',
@@ -71,6 +84,11 @@ export const NODE_TO_HUB = Object.freeze({
    * { replyTo, ok, result?, code?, message? }。加密发送（node→hub 默认封密）。
    */
   FS_RES: 'fs/res',
+  /**
+   * 工作区共享响应（2026-10-17）：node → hub 的 share/req 结果。
+   * 载荷 `{ replyTo, ok, result?, code?, message? }`。加密发送。
+   */
+  SHARE_RES: 'share/res',
   PONG: 'pong',
   ERROR: 'error',
 })

package/lib/relay.js

@@ -633,9 +633,26 @@ export function createRelay(o = {}) {
         stats.upFrames += 1
         stats.upBytes += payload.length
         // 上行：原样推给所有 hub，附带来源
+        //
+        // ⚠ hub 方向**必须过背压**（2026-10-17 修）。
+        //
+        // C1-1 的背压修复只加在 `broadcastHubs`（229 行）与
+        // `broadcastHubsBinary`（673 行）两条路径上，这里是**第三条** hub 写
+        // 路径，当时漏网。而 `ws.js` 的 `overBudget` 只是查询属性、不自动断连
+        // （由调用方决定），所以这条路径的写缓冲**没有任何上限检查**。
+        //
+        // 触发形态：hub 连接停滞（标签页被挂起 / 调试器暂停 / 宿主挂起）+
+        // 副机持续上行（exec 输出行心跳、agent 事件流、资源遥测、产物分块）。
+        // 实测过的后果是单个停滞对端把 relay writableLength 推到 339.8 MiB、
+        // RSS 419 MiB —— 中继是 NAT 场景唯一的会合点、单进程常驻，OOM 即
+        // 全体断连。
+        //
+        // node 方向早已有防护，这是**方向对称性漏洞**：三条 hub 写路径必须
+        // 全部过同一道闸。改这里时请同时检查另外两条。
         const out = encodeFrame({ ...frame, from: boundId })
         for (const h of hubs) {
-          if (!h.closed) h.send(out)
+          if (!applyHubBackpressure(h)) continue
+          h.send(out)
         }
       })
 

package/lib/setup-routes.js

@@ -27,10 +27,14 @@
  * 围栏，所以必须自己补）。写盘走 `lib/setup.js` 的 `writePatchBlock()` ——
  * 它有冲突检测、备份、托管块、写后校验、失败回滚。
  */
+import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import { ERROR_CODE, RemoteAgentError } from './protocol.js'
 import { writePatchBlock } from './setup.js'
+// 角色解析必须**只有一份实现** —— 面板说"未配置"而插件实际在跑 hub，
+// 是最难排查的撕裂（v0.7.0 踩过）。所以这里直接复用 lib/index.js 的解析器。
+import { resolveRoleDetail } from './index.js'
 
 /** 引导路由的前缀。与 hub 的 `/api/remote-agent/ui` 分开 —— 未配置时后者不存在。 */
 export const SETUP_API_PREFIX = '/api/remote-agent/setup'
@@ -206,14 +210,21 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
   route(`${SETUP_API_PREFIX}/state`, (req, res) => {
     if (req.method !== 'GET') return writeJson(res, 405, { error: 'method' })
     const role = typeof config.role === 'string' ? config.role.trim().toLowerCase() : ''
-    const valid = role === 'hub' || role === 'worker' || role === 'both'
+    // 复用 lib/index.js 的解析器 —— 它已经处理了 auto 推断、大小写、非法值。
+    // 两处判据必须一致，否则会出现"面板说未配置、实际已在跑 hub"这种撕裂。
+    const detail = resolveRoleDetail(config)
+    // `configured` 的语义是"用户已经做过选择，不需要引导"。
+    // auto 也算已选择：它是个明确的工作模式（按 hubUrl 推断），不是"还没配"。
+    const configured = role === 'auto' || detail.unconfigured !== true
     writeJson(res, 200, {
       ok: true,
-      // 未配置 = role 为空或无法识别（与 lib/index.js 的 resolveRoleDetail 同判据）
-      configured: valid,
+      configured,
+      // 推断结果（面板据此显示"当前生效角色"）—— auto 时它是有值的
+      effectiveRole: detail.role,
+      inferred: typeof detail.inferred === 'string' ? detail.inferred : '',
       // 回显当前配置里已有的值，方便用户"改一个字段"而不是从头填
       current: {
-        role: valid ? role : '',
+        role: typeof config.role === 'string' ? role : '',
         nodeId: typeof config.nodeId === 'string' ? config.nodeId : '',
         transportMode: typeof config.transportMode === 'string' ? config.transportMode : 'relay',
         hubUrl: typeof config.hubUrl === 'string' ? config.hubUrl : '',
@@ -244,6 +255,9 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
       '- id: remote-agent',
       '  name: dsh-remote-agent',
     ]
+    // 非致命提示（如"已自动创建目录 X"）—— 随响应回给面板展示，
+    // 不打断写入流程。写入成功但目录没建出来，用户需要知道。
+    let applyWarnings = []
     // inject 必须跟着 role 走：
     //   hub  → 需要 webServer/tools/systemPrompt（注册路由与工具）
     //   worker → 需要 tools/agentLoop/sessions（agent 的 ctx 继承依赖声明，
@@ -281,8 +295,37 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
     }
     const roots = Array.isArray(body.roots) ? body.roots.map(str).filter((s) => s !== '') : []
     if (roots.length > 0) {
+      // ── 自动创建 roots 目录（2026-10-17，开箱即用）────────────────────
+      //
+      // 此前 roots 必须**已经存在**：用户填了 D:\work 但没建这个目录 →
+      // 任务全部报 workspace-denied，而错误信息在任务详情里，用户根本
+      // 不会往"目录不存在"这个方向想。
+      //
+      // 现在写入配置时顺手把不存在的目录建出来。这是安全的：
+      //   · 只 mkdir -p，不删不改任何已有内容
+      //   · 路径必须**绝对**（相对路径一律跳过，让 resolveRoots 去拒）
+      //   · 创建失败不阻塞写配置（只记进 warnings，面板能显示）
+      const warnings = []
+      for (const r of roots) {
+        try {
+          if (!path.isAbsolute(r)) {
+            warnings.push(`${r} 不是绝对路径，已跳过创建（roots 必须是绝对路径）`)
+            continue
+          }
+          if (!fs.existsSync(r)) {
+            fs.mkdirSync(r, { recursive: true })
+            warnings.push(`已自动创建目录：${r}`)
+          }
+        } catch (err) {
+          warnings.push(`无法创建 ${r}：${String(err?.message ?? err)}`)
+        }
+      }
       lines.push('    roots:')
       for (const r of roots) lines.push(`      - '${r.replace(/'/g, "''")}'`)
+      if (warnings.length > 0) {
+        // 记到响应里（面板可展示），不打断写入流程
+        applyWarnings = warnings
+      }
     }
 
     const blockYaml = `${lines.join('\n')}\n`
@@ -298,13 +341,16 @@ export function registerSetupRoutes(ctx, config = {}, log = () => {}) {
         file: result.file,
       })
     }
-    log('info', 'setup applied', { role, file: result.file, mode: result.mode })
+    log('info', 'setup applied', { role, file: result.file, mode: result.mode, warnings: applyWarnings })
     writeJson(res, 200, {
       ok: true,
       role,
       file: result.file,
       backup: result.backup,
       mode: result.mode,
+      // 非致命提示（自动建目录的结果等）—— 面板要显示，否则用户以为
+      // "目录已就绪"而实际没有
+      warnings: applyWarnings,
       note: '已写入配置。**重启 DSH 后生效**。',
     })
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-agent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "把另一台电脑变成你 DSH 的远程 Agent 同事：副机本地持久跑任务、独立 Agent 循环，只回传 handoff 摘要与产物清单，成品按需拉取。",
   "license": "MIT",

package/scripts/check-doc-drift.mjs

@@ -303,9 +303,15 @@ for (const [i, [file, why]] of MAINT_FILES.entries()) {
   check('29', 'profiles/worker.cordis.yml 里有 inject: []',
     /^\s*inject:\s*\[\]\s*$/m.test(workerProfile),
     'profiles/worker.cordis.yml（副机不清空 inject 会永远 PENDING）')
-  check('30', 'README 说明了副机为什么要写 inject: []',
-    /inject:\s*\[\]/.test(rootReadme) && /PENDING/.test(rootReadme),
-    'README.md（副机配置一节）')
+  // 2026-10-17 改：原断言锁的是 `inject: []`（README 教用户写这个）——
+  // **那是错的**：副机 agent 的 ctx 继承插件的依赖声明，`inject: []` 会让
+  // agent 没有任何 shell/文件工具，任务"跑完了但什么都没干"（实测踩过）。
+  // 正确写法是 worker 三件套。断言跟着改，否则文档会退回错误建议。
+  check('30', 'README 说明了副机 inject 的正确写法（tools/agentLoop/sessions，不是 []）',
+    /inject:\s*\[[^\]]*agentLoop[^\]]*\]/.test(rootReadme)
+    && /agentLoop/.test(rootReadme)
+    && /没有[^\n]*工具|无[^\n]*工具/.test(rootReadme),
+    'README.md（副机配置一节：inject 三件套 + 缺了会怎样的说明）')
   check('31', '包内 cordis.patch.yml 声明了 hub 需要的 inject',
     /inject:\s*\[[^\]]*webServer[^\]]*\]/.test(read('cordis.patch.yml')),
     'cordis.patch.yml')
@@ -886,6 +892,166 @@ check('65', 'eslint 严格档：lint script + 配置文件 + CI job 三件套齐
     'lib/node/index.js readAvailableModels（上报字段恰好 provider/id/name）')
 }
 
+/* ── 77~78. 环境体检（2026-10-17）──
+ *
+ * 这个插件最贵的失败全是**静默**的：
+ *   · webserver 绑 loopback → 副机永远连不上，主机侧毫无异常
+ *   · inject 缺服务 → hub 半死（路由活着但工具全丢）
+ *   · roots 不存在 → 任务全被 workspace-denied 拒绝
+ *
+ * 用户只能猜"地址错了？token 错了？防火墙？"。所以体检必须覆盖这些前置条件、
+ * 每条都给**具体修法**，且命令行与面板共用同一份逻辑（两处不一致更坏）。
+ *
+ * 另外钉住一条产品边界：**不代用户下载第三方软件**（零依赖是核心卖点，
+ * 代下载会让我们变成软件分发方）。
+ */
+{
+  const envLib = read('lib/env-check.js')
+  const uiSrc2 = read('lib/hub/ui-routes.js')
+  const clientSrc2 = read('lib/client.js')
+
+  check('77', '环境体检：共享模块 + 面板路由 + 面板按钮三处都在',
+    /export function envChecks/.test(envLib)
+    && /export function isLoopbackOrigin/.test(envLib)
+    && /export function renderEnvChecks/.test(envLib)
+    && /UI_API_PREFIX\}\/env-check/.test(uiSrc2)
+    && /apiGet\('\/env-check'\)/.test(clientSrc2)
+    && /'体检'/.test(clientSrc2),
+    'lib/env-check.js + ui-routes.js /env-check + client.js 体检按钮')
+
+  check('78', '环境体检：覆盖静默失败项 + 每条带修法 + 不代下载',
+    /'reachability'/.test(envLib)
+    && /'inject'/.test(envLib)
+    && /'roots'/.test(envLib)
+    && /'role'/.test(envLib)
+    && /fix:/.test(envLib)
+    && /不会代你下载/.test(envLib),
+    'lib/env-check.js（可达性/inject/roots/role + fix + 不代下载边界）')
+}
+
+/* ── 79~80. 开箱即用（2026-10-17）──
+ *
+ * 产品标准：用户装完就该能用，不该读文档、改 YAML、猜字段。
+ *
+ * 此前三道门槛：
+ *   1. `role` 默认 '' → 两台机器都要操作一次
+ *   2. `webserver` 没绑 0.0.0.0 → 副机永远连不上（且完全静默）
+ *   3. 副机表单 4 个字段 → 小白不知道节点 ID / 工作区填什么
+ *
+ * 核心设计：`role` 默认 **auto**，按 `hubUrl` 推断。
+ *   · 默认 hub → 副机装完以 hub 身份启动，注册无鉴权端点（**攻击面**）
+ *   · 默认 ''  → 两台都要操作，不是开箱即用
+ *   · 默认 auto → 主机零操作、副机贴完配对码零操作，且不给副机开错端点
+ */
+{
+  const indexSrc = read('lib/index.js')
+  const patchSrc = read('cordis.patch.yml')
+  const clientSrc3 = read('lib/client.js')
+  const setupSrc = read('lib/setup-routes.js')
+
+  check('79', '开箱即用：role 默认 auto + 包内 patch 绑 0.0.0.0:19387',
+    /\.default\('auto'\)/.test(indexSrc)
+    && /ROLE\.AUTO/.test(indexSrc)
+    && /config\.hubUrl/.test(indexSrc)
+    // 包内 patch 必须 override webserver（否则副机连不上）
+    && /^- id: webserver$/m.test(patchSrc)
+    && /host:\s*'0\.0\.0\.0'/.test(patchSrc)
+    && /port:\s*19387/.test(patchSrc)
+    // 必须披露安全影响
+    && /暴露/.test(patchSrc),
+    'lib/index.js（auto 推断）+ cordis.patch.yml（webserver 0.0.0.0:19387 + 安全披露）')
+
+  check('80', '开箱即用：副机表单简化 + 工作区自动创建 + 首次自动体检',
+    // 工作区预填
+    /function defaultRootsHint/.test(clientSrc3)
+    // 节点 ID 折叠
+    && /默认用主机名/.test(clientSrc3)
+    // 首次自动体检
+    && /autoChecked/.test(clientSrc3)
+    // 服务端自动建目录
+    && /mkdirSync\(r, \{ recursive: true \}\)/.test(setupSrc)
+    && /warnings: applyWarnings/.test(setupSrc),
+    'lib/client.js（预填/折叠/自动体检）+ lib/setup-routes.js（自动建目录）')
+}
+
+/* ── 81~82. 工作区 SMB 共享（2026-10-17）──
+ *
+ * 用户需求：想用本地 IDE 直接打开副机的项目目录 —— 唯一现实路径是把工作区
+ * 通过 SMB 共享出去，主机 `net use X: \\副机\dsh-work` 映射成盘符。
+ *
+ * ⚠ **这是本插件唯一主动放宽安全边界的功能**：
+ *   · roots / denyPaths 全部失效（Windows 内核直读，插件拦不住）
+ *   · 「清单先于字节」失效（.env / .git 密钥 / 中间产物全部可见）
+ *   · 新增凭证面（主机需要副机 Windows 账号）
+ *
+ * 所以产品要求（用户确认）：二次确认 + 只读/读写两选项 + 不代执行（需管理员）。
+ * 这两条断言把安全约束钉住 —— 它们比功能本身更重要。
+ */
+{
+  const shareSvc = read('lib/node/share-service.js')
+  const nodeIdx2 = read('lib/node/index.js')
+  const uiSrc3 = read('lib/hub/ui-routes.js')
+  const clientSrc4 = read('lib/client.js')
+  const transportSrc = read('lib/node/transport.js')
+
+  check('81', '工作区共享：协议帧 + E2E 强制 + 独立 pending 表 + 副机 handler 都在',
+    /SHARE_REQ: 'share\/req'/.test(read('lib/protocol.js'))
+    && /SHARE_RES: 'share\/res'/.test(read('lib/protocol.js'))
+    // 工作区绝对路径不许明文过中继
+    && /HUB_TO_NODE\.SHARE_REQ/.test(transportSrc)
+    // 两张 pending 表不能混（混了超时归因变模糊）
+    && /this\.sharePending = new Map\(\)/.test(read('lib/hub/node-registry.js'))
+    && /shareCancelForNode/.test(read('lib/hub/node-registry.js'))
+    && /handleShareRes/.test(read('lib/hub/registry-ingest.js'))
+    && /function handleShareReq/.test(nodeIdx2),
+    'protocol.js + transport.js + node-registry.js + registry-ingest.js + node/index.js')
+
+  check('82', '工作区共享安全：二次确认硬要求 + 只读默认 + 不代执行',
+    // 二次确认是硬要求（缺 confirm 必须 400，不能有默认通过）
+    /body\?\.confirm !== 'yes'/.test(uiSrc3)
+    && /confirm-required/.test(uiSrc3)
+    // 只读默认（最小权限）
+    && /React\.useState\('read'\)/.test(clientSrc4)
+    && /disabled: busy \|\| !ack/.test(clientSrc4)
+    // 读写用 -ChangeAccess，不用 -FullAccess（后者会把 ACL 也交出去）
+    && /ChangeAccess/.test(shareSvc)
+    && !/'-FullAccess'/.test(shareSvc)
+    // 不代执行（需管理员，Node 提权失败比让用户手动跑难排查）
+    && !/spawn.*New-SmbShare/.test(nodeIdx2)
+    && /admin: isAdmin\(\)/.test(nodeIdx2)
+    // 共享目录必须过 roots 边界
+    && /resolveWorkspace\(/.test(nodeIdx2),
+    'ui-routes.js（二次确认）+ client.js（勾选框/只读默认）+ share-service.js + node/index.js')
+}
+
+/* ── 83. README 声明的工具数量必须等于代码里实际注册的数量 ──
+ *
+ * 起因（2026-10-17）：README 写「7 个 remote_* 工具」，实际早已是 12 个
+ * （8 个 remote_* + 4 个 fs 工具）。这种数字漂移是最容易积累的文档债务 ——
+ * 每次加工具都忘了改 README，而读者会拿它当事实。
+ *
+ * 断言做法：数 `reg(` / `fsOp(` 的注册调用，与 README 里的声明比对。
+ * 两边任一变化都会立刻失败，逼着改的人同步另一处。
+ */
+{
+  const toolsSrc = read('lib/hub/tools.js')
+  const rootReadme2 = read('README.md')
+
+  // 数实际注册：`reg(` 与 `fsOp(` 的调用点（都是工具注册入口）
+  const regCount = (toolsSrc.match(/^\s{2}reg\(/gm) || []).length
+  const fsOpCount = (toolsSrc.match(/^\s{2}fsOp\(/gm) || []).length
+  const actual = regCount + fsOpCount
+
+  // 从 README 里抽声明（形如「12 个 remote_* 工具」或「工具速查（共 12 个）」）
+  const m = /(?:共\s*(\d+)\s*个|(\d+)\s*个\s*remote_\*)/.exec(rootReadme2)
+  const declared = m ? Number(m[1] ?? m[2]) : null
+
+  check('83', 'README 声明的工具数量等于代码里实际注册的数量',
+    declared !== null && declared === actual,
+    `lib/hub/tools.js（实际 ${actual} 个：reg=${regCount} + fsOp=${fsOpCount}）`
+    + ` vs README.md（声明 ${declared === null ? '未找到' : declared} 个）`)
+}
+
 /* ── 输出 ── */
 const failed = results.filter((r) => !r.ok)
 if (process.argv.includes('--json')) {