deskbuddy 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/gate.cjs

@@ -106,6 +106,7 @@ function argTool(argv) {
  * - Claude Code：见 isInteractiveClaude
  */
 function isInteractiveAgent(tool) {
+  if (process.platform === 'win32') return isInteractiveAgentWin(tool)
   if (tool === 'qoder') return hasAncestor((comm) => comm.includes('/Qoder CN.app/'))
   if (tool === 'claude_code') return isInteractiveClaude()
   // opencode 的窗口确认由插件发起，插件已排除 `opencode run`（hook/opencode.mjs isHeadless）
@@ -113,6 +114,43 @@ function isInteractiveAgent(tool) {
   return false
 }
 
+/** 窗口里 claude 的参数不带 -p / --print / stream-json：与 isInteractiveClaude 同一判据 */
+function claudeArgsInteractive(argsAfterArgv0) {
+  return !argsAfterArgv0.some(
+    (t) => t === '--print' || /^-[a-zA-Z]*p[a-zA-Z]*$/.test(t) || t === 'stream-json' || t.startsWith('--output-format=stream')
+  )
+}
+
+/**
+ * Windows 版（没有 ps）：进程表借 hook.cjs 的实现（同目录，随它一起装），判据同上。
+ * - Qoder CN 桌面端：祖先里有 `Qoder CN.exe`
+ * - Claude Code：原生版是 `claude.exe`，npm 版是 node 跑 `claude-code/cli.js`
+ * 取不到进程表 = 判不出来 = 不表态（窗口模式的兜底方向）
+ */
+function isInteractiveAgentWin(tool) {
+  if (tool === 'opencode') return true
+  if (tool !== 'qoder' && tool !== 'claude_code') return false
+  let winProc
+  try {
+    winProc = require(path.join(__dirname, 'hook.cjs')).winProc
+  } catch (_) {
+    return false
+  }
+  let pid = process.ppid
+  const seen = new Set()
+  for (let i = 0; i < 8 && pid > 4 && !seen.has(pid); i++) {
+    seen.add(pid)
+    const p = winProc(pid)
+    if (!p) return false
+    if (tool === 'qoder' && /qoder cn/i.test(p.name)) return true
+    if (tool === 'claude_code' && (/^claude(\.exe)?$/i.test(p.name) || p.name === 'claude-code/cli.js')) {
+      return claudeArgsInteractive(p.args.split(' ').slice(1))
+    }
+    pid = p.ppid
+  }
+  return false
+}
+
 function hasAncestor(match) {
   let pid = process.ppid
   for (let i = 0; i < 8 && pid > 1; i++) {

package/dist/hook.cjs

@@ -22,6 +22,11 @@ const { execFileSync } = require('node:child_process')
 const DEFAULT_API_BASE = process.env.DESKBUDDY_API_BASE || 'https://api.shifengintelli.com'
 const KEEPALIVE_MS = 2 * 60 * 1000
 const MAX_SESSIONS = 20
+/**
+ * 快照整包带的能力声明（前置 spec 2026-09-29 §4.4，服务端写 deskbuddy:caps:{clientId}）。
+ * 与 src/core/snapshot.ts 的 CAPS 一致
+ */
+const CAPS = ['cmd_result', 'window_inject']
 /** 状态文件里保留的最近事件条数，与 src/core/state.ts 的 RECENT_MAX 一致 */
 const RECENT_MAX = 8
 const REPORT_TIMEOUT_MS = 2000
@@ -331,11 +336,141 @@ function resolveTitle(sources, ctx) {
   return ''
 }
 
+// ---------- Windows 进程表 ----------
+// 🔴 与 src/core/winproc.ts 逐行同构：这里记下的 pidName 要由 daemon 拿同一个算法复核，改一边必须改另一边。
+// Windows 没有 ps，用 PowerShell 一次取全表在内存里走（一次 300ms 起，不能按 pid 一个个查）。
+
+const IS_WIN = process.platform === 'win32'
+const SCRIPT_HOSTS = ['node', 'bun', 'deno']
+const WIN_PS_SCRIPT =
+  '[Console]::OutputEncoding=[Text.Encoding]::UTF8;' +
+  'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine | ConvertTo-Json -Compress'
+
+function winSplitArgs(cmdline) {
+  const out = []
+  let cur = ''
+  let inQ = false
+  let has = false
+  const s = cmdline || ''
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i]
+    if (c === '\\') {
+      let n = 0
+      while (s[i + n] === '\\') n++
+      if (s[i + n] === '"') {
+        cur += '\\'.repeat(Math.floor(n / 2))
+        if (n % 2 === 1) cur += '"'
+        else inQ = !inQ
+        i += n
+        has = true
+      } else {
+        cur += '\\'.repeat(n)
+        i += n - 1
+        has = true
+      }
+    } else if (c === '"') {
+      inQ = !inQ
+      has = true
+    } else if (!inQ && (c === ' ' || c === '\t')) {
+      if (has) out.push(cur)
+      cur = ''
+      has = false
+    } else {
+      cur += c
+      has = true
+    }
+  }
+  if (has) out.push(cur)
+  return out
+}
+
+function isScriptHost(name) {
+  return SCRIPT_HOSTS.indexOf(String(name).replace(/\.exe$/i, '').toLowerCase()) !== -1
+}
+
+function hostedScript(argv) {
+  for (const a of argv.slice(1)) if (!a.startsWith('-')) return a
+  return ''
+}
+
+/** 原生程序取映像名；node / bun 跑的取脚本路径最后两段（再往上是用户目录，用户名可能撞智能体名） */
+function winEffectiveName(name, cmdline) {
+  if (!isScriptHost(name)) return name
+  const script = hostedScript(winSplitArgs(cmdline))
+  return script ? script.split(/[\\/]+/).filter(Boolean).slice(-2).join('/') : name
+}
+
+function winNormalizedArgs(name, cmdline) {
+  let argv = winSplitArgs(cmdline)
+  if (argv.length === 0) return ''
+  if (isScriptHost(name)) {
+    const script = hostedScript(argv)
+    if (script) argv = argv.slice(argv.indexOf(script))
+  }
+  return argv.map((a) => a.replace(/\s+/g, '_').replace(/\\/g, '/')).join(' ')
+}
+
+function parseWinProcJson(json) {
+  let d
+  try {
+    d = JSON.parse(String(json).replace(/^/, ''))
+  } catch (e) {
+    return []
+  }
+  const list = Array.isArray(d) ? d : d ? [d] : []
+  const out = []
+  for (const r of list) {
+    const pid = Number(r && r.ProcessId)
+    if (!Number.isInteger(pid) || pid <= 0) continue
+    const rawName = typeof r.Name === 'string' ? r.Name : ''
+    const cmdline = typeof r.CommandLine === 'string' ? r.CommandLine.replace(/[\r\n]+/g, ' ') : ''
+    out.push({
+      pid: pid,
+      ppid: Number(r.ParentProcessId) || 0,
+      name: winEffectiveName(rawName, cmdline),
+      args: winNormalizedArgs(rawName, cmdline),
+      cmdline: cmdline,
+    })
+  }
+  return out
+}
+
+let winProcCache
+/** 全表，本进程内只取一次。取不到返回 null —— 🔴 调用方必须当"不知道"，不能当"进程不在" */
+function winProcs() {
+  if (winProcCache !== undefined) return winProcCache
+  try {
+    const out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', WIN_PS_SCRIPT], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      maxBuffer: 32 * 1024 * 1024,
+      windowsHide: true,
+      timeout: 15000,
+    })
+    const procs = parseWinProcJson(out)
+    winProcCache = procs.length > 0 ? procs : null
+  } catch (e) {
+    winProcCache = null
+  }
+  return winProcCache
+}
+
+function winProc(pid) {
+  const procs = winProcs()
+  if (!procs) return null
+  for (const p of procs) if (p.pid === pid) return p
+  return null
+}
+
 // ---------- 进程探测 ----------
 
 function processName(pid) {
+  if (IS_WIN) {
+    const p = winProc(pid)
+    return p ? p.name : null
+  }
   try {
-    // macOS / Linux 通用。Windows 需要 tasklist，首期不支持
+    // macOS / Linux 通用
     const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
@@ -348,6 +483,10 @@ function processName(pid) {
 }
 
 function parentPid(pid) {
+  if (IS_WIN) {
+    const p = winProc(pid)
+    return p && p.ppid > 4 && p.ppid !== pid ? p.ppid : null
+  }
   try {
     const out = execFileSync('ps', ['-p', String(pid), '-o', 'ppid='], {
       encoding: 'utf8',
@@ -369,6 +508,8 @@ function isAlive(pid, expectName) {
     return false
   }
   if (!expectName) return true
+  // 🔴 Windows 进程表取不到时只能信 pid：当成"不在"会把所有窗口会话清掉
+  if (IS_WIN && !winProcs()) return true
   const name = processName(pid)
   return name != null && name.toLowerCase().includes(String(expectName).toLowerCase())
 }
@@ -467,7 +608,26 @@ function shouldReport(prev, next, nowMs) {
   return nowMs - (prev.lastReportAt || 0) > KEEPALIVE_MS
 }
 
-function buildSnapshot(states, tool, cfg, nowMs) {
+/**
+ * daemon 连着的 Codex app-server 里已加载的会话（切片 B，与 src/core/codexRemote.ts 一致）。
+ * daemon 进程不在了就不认；读不到返回 null
+ */
+/** daemon 每 30 秒重写一次；两个保活周期（2 分钟）没更新就当 daemon 卡住了，不认 */
+const CODEX_REMOTE_TTL_MS = 2 * 60 * 1000
+
+function readCodexRemote(now) {
+  try {
+    const r = JSON.parse(fs.readFileSync(path.join(deskbuddyHome(), 'codex-remote.json'), 'utf8'))
+    if (!r || typeof r.pid !== 'number' || !Array.isArray(r.threads) || !pidExists(r.pid)) return null
+    if (typeof r.at !== 'number' || Math.abs((now || Date.now()) - r.at) > CODEX_REMOTE_TTL_MS) return null
+    return new Set(r.threads.filter((x) => typeof x === 'string'))
+  } catch (e) {
+    return null
+  }
+}
+
+/** remote：给了就以它判 remoteWindow（Codex，切片 B），否则看状态文件（与 src/core/snapshot.ts 一致） */
+function buildSnapshot(states, tool, cfg, nowMs, remote) {
   const sessions = states
     .filter((s) => s.tool === tool) // 替换粒度是 (clientId, tool)，混进别的工具会冲掉对方
     .sort((a, b) => b.updatedAt - a.updatedAt)
@@ -481,8 +641,9 @@ function buildSnapshot(states, tool, cfg, nowMs) {
       startedAt: s.startedAt,
       updatedAt: s.updatedAt,
       interactive: s.interactive === true,
+      remoteWindow: remote ? remote.has(s.sessionId) : s.remoteWindow === true,
     }))
-  return { clientId: cfg.clientId, hostName: cfg.hostName, tool: tool, snapshotAt: nowMs, sessions: sessions }
+  return { clientId: cfg.clientId, hostName: cfg.hostName, tool: tool, snapshotAt: nowMs, sessions: sessions, caps: CAPS.slice() }
 }
 
 // ---------- 上报 ----------
@@ -603,7 +764,8 @@ async function reportIfAuthorized(tool, nowMs) {
   // clientId 为空说明还没 setup 过（服务端靠 clientId ↔ userId 绑定关系认人）：
   // 绝不能在这里现编一个，那等于凭空造出一台没人认领的机器
   if (!cfg.clientId || cfg.enabledTools.indexOf(tool) === -1) return
-  await postReport(cfg, buildSnapshot(readAliveStates(tool), tool, cfg, nowMs))
+  const remote = tool === 'codex' ? readCodexRemote() || new Set() : null
+  await postReport(cfg, buildSnapshot(readAliveStates(tool), tool, cfg, nowMs, remote))
 }
 
 /**
@@ -654,6 +816,10 @@ function pidExists(pid) {
 
 function detectInteractive(pid) {
   if (!pid) return false
+  if (IS_WIN) {
+    const p = winProc(pid)
+    return !!p && p.args !== '' && isInteractiveArgs(p.args)
+  }
   try {
     const args = execFileSync('ps', ['-ww', '-o', 'args=', '-p', String(pid)], {
       encoding: 'utf8',
@@ -772,6 +938,84 @@ function takeNotice(sessionId) {
   }
 }
 
+// ---------- 窗口接管（spec 2026-09-30 §3.2，与 src/core/wrapWindows.ts 同构） ----------
+
+const WINDOW_ID_RE = /^[a-f0-9]{32}$/
+/** 记进 .last 的事件。Notification 不记：闲置 60 秒的「等你输入」通知会把空闲窗口判成忙 */
+const WINDOW_EVENTS = {
+  SessionStart: 1,
+  UserPromptSubmit: 1,
+  PreToolUse: 1,
+  PostToolUse: 1,
+  PostToolUseFailure: 1,
+  PermissionRequest: 1,
+  Stop: 1,
+  SessionEnd: 1,
+}
+
+function windowsDir() {
+  return path.join(deskbuddyHome(), 'windows')
+}
+
+function readWindow(windowId) {
+  if (!WINDOW_ID_RE.test(windowId)) return null
+  try {
+    const r = JSON.parse(fs.readFileSync(path.join(windowsDir(), windowId + '.json'), 'utf8'))
+    return r && typeof r.pid === 'number' ? r : null
+  } catch (e) {
+    return null
+  }
+}
+
+/**
+ * 环境变量里的窗口是不是这个智能体进程的窗口。
+ * 🔴 窗口里的 claude 用 Bash 工具再起 claude 时 DESKBUDDY_WINDOW 会被继承：只认包装层直接起的那个进程（childPid）；
+ *    判不出 pid 时按是
+ */
+function windowOwns(rec, agentPid) {
+  if (!rec) return false
+  if (rec.childPid && agentPid && rec.childPid !== agentPid) return false
+  return true
+}
+
+function atomicWrite(file, text) {
+  const tmp = file + '.' + process.pid + '.tmp'
+  fs.writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600 })
+  fs.renameSync(tmp, file)
+}
+
+/** 写 by-session 映射（内容没变不重写）+ 本窗口最近一个状态型事件，供包装层判空闲 */
+function noteWindow(windowId, sessionId, event, now) {
+  const safe = String(sessionId).replace(/[^A-Za-z0-9_-]/g, '')
+  if (!safe || !WINDOW_ID_RE.test(windowId)) return
+  try {
+    const dir = path.join(windowsDir(), 'by-session')
+    let cur = ''
+    try {
+      cur = fs.readFileSync(path.join(dir, safe), 'utf8').trim()
+    } catch (e) {
+      cur = ''
+    }
+    if (cur !== windowId) {
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+      atomicWrite(path.join(dir, safe), windowId)
+    }
+  } catch (e) {
+    /* 映射写不了：设备指令退回后台路径 */
+  }
+  if (!WINDOW_EVENTS[event]) return
+  try {
+    atomicWrite(path.join(windowsDir(), windowId + '.last'), JSON.stringify({ ev: event, sid: sessionId, at: now }))
+  } catch (e) {
+    /* 同上：写不了就一直判不空闲，设备指令排队到过期 */
+  }
+}
+
+function codexRemoteHas(sessionId) {
+  const r = readCodexRemote()
+  return !!r && r.has(sessionId)
+}
+
 async function main(argv) {
   // 同一份 hook 被 Claude Code 与 Codex 复用，靠命令行参数区分是哪个工具
   const tool = (argv && argv[2]) || 'claude_code'
@@ -794,6 +1038,19 @@ async function main(argv) {
 
   const registry = loadRegistry()
 
+  // 窗口接管（spec 2026-09-30 §3.2）：包装层起的窗口带 DESKBUDDY_WINDOW。只在有这个变量时才多做一点事
+  let windowId = ''
+  const envWin = process.env.DESKBUDDY_WINDOW || ''
+  if (WINDOW_ID_RE.test(envWin)) {
+    const rec = readWindow(envWin)
+    if (rec) {
+      const p0 = readState(sessionId)
+      const agentPid = p0 && p0.pid && pidExists(p0.pid) ? p0.pid : resolveAgentPid(process.pid, agentNames(registry, tool))
+      if (windowOwns(rec, agentPid || undefined)) windowId = envWin
+    }
+    if (windowId) noteWindow(windowId, sessionId, event, Date.now())
+  }
+
   // /clear 改绑（二期 P2）：SessionStart 在映射表里是 ignore，要在那之前处理
   if (event === 'SessionStart' && payload.source === 'clear') {
     const pid = resolveAgentPid(process.pid, agentNames(registry, tool))
@@ -840,7 +1097,10 @@ async function main(argv) {
     pid: pid,
     pidName: pid ? (prevAlive && prev.pidName) || processName(pid) || undefined : undefined,
     // 二期 P1：窗口开着的会话，设备不能再往里下指令（两个进程会互相吞掉对话）。每个会话只判一次
-    interactive: prevAlive && typeof prev.interactive === 'boolean' ? prev.interactive : detectInteractive(pid),
+    interactive: windowId ? true : prevAlive && typeof prev.interactive === 'boolean' ? prev.interactive : detectInteractive(pid),
+    // 会话开在 DeskBuddy 窗口里（spec 2026-09-30 §3.2）：服务端据此放行 8348，指令由包装层写进窗口
+    // Codex（切片 B）：会话加载在 daemon 连着的 app-server 里 = 窗口开着且能往里发
+    remoteWindow: windowId || (tool === 'codex' && codexRemoteHas(sessionId)) ? true : undefined,
     lastReportAt: prev ? prev.lastReportAt : undefined,
     // daemon 靠它给窗口待批准撤卡（S10），与 src/core/state.ts 的 recent 同构
     recent: ((prev && Array.isArray(prev.recent) ? prev.recent : []).concat([
@@ -853,7 +1113,9 @@ async function main(argv) {
     ])).slice(-RECENT_MAX),
   }
 
-  if (!shouldReport(prev, next, now)) {
+  // 进 / 出 DeskBuddy 窗口不一定伴随状态跃迁（窗口里 --resume 一个已完成的会话），要立刻报，否则设备最长 2 分钟仍被 8348 挡
+  const windowChanged = !!(prev && prev.remoteWindow) !== !!next.remoteWindow
+  if (!windowChanged && !shouldReport(prev, next, now)) {
     writeState(next)
     return
   }
@@ -896,6 +1158,7 @@ module.exports = {
   buildGatewayBody,
   buildHeaders,
   buildSnapshot,
+  readCodexRemote,
   isAlive,
   loadConfig,
   loadRegistry,
@@ -919,4 +1182,14 @@ module.exports = {
   sign,
   titleSources,
   writeState,
+  winEffectiveName,
+  winNormalizedArgs,
+  winProc,
+  winSplitArgs,
+  parseWinProcJson,
+  CAPS,
+  WINDOW_EVENTS,
+  noteWindow,
+  readWindow,
+  windowOwns,
 }

package/docs/INSTALL.md

@@ -4,8 +4,12 @@
 > 你按顺序执行下面的步骤即可。每一步都给了**判定成功的依据**，不满足就按「排查」一节处理。
 > 需要用户本人动手的地方（扫码、Codex 授信）已经标出来了，到那一步要停下来告诉用户。
 
-DeskBuddy 把 Claude Code、Codex 等 AI 编码智能体**每个会话窗口**的状态，实时同步到桌面硬件屏幕。
-多开会话时不用挨个切窗口看哪个在等确认、哪个跑完了。
+DeskBuddy 让桌面硬件和电脑上的 AI 编码智能体（Claude Code、Codex、WorkBuddy、Qoder CN、opencode）配合：
+
+- **状态上屏**：每个会话窗口在干活、在等你确认、还是做完了，抬头看一眼桌上的屏就知道
+- **远程下指令**：在设备上对某个任务说一句话，电脑上的智能体接着干；也能在设备上新建任务
+- **在设备上批准**：智能体要跑命令、改工作目录外的文件时，设备上弹卡片等你按「允许 / 拒绝」
+- **窗口授权框同步到设备**：你自己在电脑窗口里用智能体、弹出授权框时，设备上也出一张卡片，两边谁先答算谁
 
 ---
 
@@ -15,76 +19,110 @@ DeskBuddy 把 Claude Code、Codex 等 AI 编码智能体**每个会话窗口**
 node -v    # 必须 ≥ 18
 ```
 
-不满足就先让用户升级 Node，别继续。
-
-**装完不会有任何常驻进程**：它只是往各智能体自己的 hook 配置里加了一条记录，由智能体在事件发生时调用。
+- 不满足就先让用户升级 Node，别继续
+- 支持 macOS、Linux、Windows 10/11（Windows 上 Claude Code 建议装 Git for Windows；命令在 PowerShell 或 Git Bash 里敲都行，`~` 即 `%USERPROFILE%`）
+- ⚠️ **当前是 beta，服务端只在测试环境**：下面所有命令都用 `deskbuddy@beta`，`setup` 必须带 `--api-base`
 
 ---
 
 ## 1. 授权（需要用户本人扫码）
 
 ```bash
-npx deskbuddy setup
+npx deskbuddy@beta setup --api-base https://test-api.shifengintelli.com
 ```
 
-终端会打印一个二维码和一行明文授权码，然后停在「等待授权中…」。
+1. 终端先问**远程新建任务默认在哪个目录做**（直接回车 = 桌面）
+2. 然后打印一个二维码和一行明文授权码，停在「等待授权中…」
 
-**这一步你（AI 助手）替代不了**，要告诉用户：
+**扫码这一步你（AI 助手）替代不了**，要告诉用户：
 
 > 用 DeskBuddy App 扫描终端里的二维码；扫不出来就在 App 里手动输入那行授权码。
 
 - 授权码 5 分钟内有效，过期就重新跑一次 `setup`
 - 终端字符画受字体/行高/深浅色主题影响，有些终端**扫不出来**，这时用明文码手输，不是故障
-- 成功后终端打印 `✅ 授权成功`，本机 `~/.deskbuddy/config.json` 里会多一个 `boundAt` 字段
+- 🔴 **不带 `--api-base` 会连到生产环境**，而 beta 的接口只在测试环境，授权会失败或后续功能报错
 
 **判定成功**：命令退出码为 0 且打印了 `✅ 授权成功`。
 
 ---
 
-## 2. 安装采集 hook
+## 2. 启用智能体
 
 ```bash
-npx deskbuddy enable claude_code,codex     # 只用其中一个就只写一个
+npx deskbuddy@beta enable claude_code,codex,opencode     # 用户用哪几个写哪几个，逗号分隔
 ```
 
-**判定成功**：每个工具各打印一行 `✅ <tool>：hook 已装进 <路径>`。
+可选：`claude_code`、`codex`、`workbuddy`、`qoder`（Qoder CN 桌面端）、`opencode`。
+
+`enable` 做三件事：往各智能体配置里装 hook / 插件、把脚本同步到 `~/.deskbuddy/`、**设好守护进程开机自启并启动它**。
+
+**判定成功**：每个工具各打印一行 `✅ <tool>：hook 已装进 <路径>`，最后一行附近有 `✅ 已设置开机自启`。
+
+装完要告诉用户：**已经开着的智能体窗口要关掉重开**，新的 hook / 插件才会生效。
+
+### 🔴 Codex 用户必读
 
-### 🔴 Codex 用户必读：还要在 Codex 里确认信任
+1. **要在 Codex 里确认信任 hook**：Codex 对 hook 定义做 sha256 校验，首次启动会要求确认，不确认就不执行。
+   现象是「装成功了但屏幕上一直没数据」，极容易被当成安装失败。告诉用户：
 
-Codex 对 hook 定义做 sha256 校验，**首次运行会要求你确认信任这个 hook，不确认它就不执行**。
-现象是「装成功了但屏幕上一直没数据」，极容易被当成安装失败。
+   > 下次启动 Codex 时会弹出确认信任 hook 的提示，请选择同意。
 
-所以装完 codex 之后要告诉用户：
+   **不要**用 `--dangerously-bypass-hook-trust` 替用户绕过这个确认。
 
-> 下次启动 Codex 时会弹出确认信任 hook 的提示，请选择同意。
+2. **窗口授权框同步到设备有前提**：只有 Codex 经 `codex --remote ws://127.0.0.1:<端口>` 连着一个常驻 `codex app-server` 使用时才生效
+   （守护进程作为第二个客户端连上去）。直接运行 `codex` 时，设备上只显示「待确认」，授权框仍在电脑上点。
 
-**不要**用 `--dangerously-bypass-hook-trust` 替用户绕过这个确认。
+### 各智能体的能力
+
+| 能力 | Claude Code | Codex | WorkBuddy | Qoder CN | opencode |
+|---|---|---|---|---|---|
+| 状态上屏 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 远程下指令 / 续会话 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 远程任务在设备上批准 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 窗口授权框同步到设备 | ✅ | 仅 `--remote` 常驻 app-server | ❌ | ✅ | ✅ |
+
+WorkBuddy 的授权框由它自己的「安全中心」弹出、不经过任何 hook，所以做不了；Codex 的 hook 会先卡住授权框（等 hook 返回才弹），所以只能走 app-server。
 
 ---
 
 ## 3. 验证
 
 ```bash
-npx deskbuddy status
+npx deskbuddy@beta status
 ```
 
-应该看到：账号已授权、已启用的工具都显示「hook 已装」、hook 版本与当前包一致。
+应该看到：第二行是**测试环境**、账号已授权、已启用的工具都显示「hook 已装」、hook 版本与当前包一致。
 让智能体随便跑个任务，再看一次 `status`，「当前本地会话」里就会出现内容。
 
----
+守护进程（远程指令、设备批准都靠它）：
 
-## 国内用户
+```bash
+tail -5 ~/.deskbuddy/daemon.log      # 应有「已连上」；用 Codex 常驻 app-server 的还应有「已连上 Codex app-server」
+launchctl list | grep deskbuddy      # macOS：有一行 com.deskbuddy.daemon 且第一列是进程号
+# Windows（PowerShell）：Get-Content ~\.deskbuddy\daemon.log -Tail 5；开机自启看「启动」文件夹里有没有 DeskBuddyDaemon.vbs
+```
 
-本机 npm 若走淘宝镜像，装最新版可能有几分钟同步延迟：
+---
+
+## 4. 升级
 
 ```bash
-npx --registry=https://registry.npmmirror.com deskbuddy setup
+npx deskbuddy@<新版本号> update
 ```
 
-装不到最新版就临时改用官方源：
+按本机已启用的工具把 hook 重装一遍、改写开机自启并把守护进程重启到新版本。**不用重新扫码**。
+
+- 版本号用 `npm view deskbuddy dist-tags` 查；写死版本号比写 `@beta` 稳：npx 有缓存，`@beta` 可能还拿到旧版
+- 只跑任意一个命令（如 `status`）也会把 `~/.deskbuddy/` 里的脚本同步到当前版本，但**不会**补装新 hook、也不会换掉守护进程——所以升级一律用 `update`
+
+---
+
+## 国内用户
+
+本机 npm 若走淘宝镜像，新版本可能有几分钟同步延迟，装不到就临时改用官方源：
 
 ```bash
-npx --registry=https://registry.npmjs.org deskbuddy setup
+npx --registry=https://registry.npmjs.org deskbuddy@beta setup --api-base https://test-api.shifengintelli.com
 ```
 
 ---
@@ -93,38 +131,44 @@ npx --registry=https://registry.npmjs.org deskbuddy setup
 
 | 文件 | 改动方式 |
 |---|---|
-| `~/.claude/settings.json` | **幂等合并**一条 hook 记录（你已有的 hook 一条都不动） |
-| `~/.codex/config.toml` | 在文件**末尾追加**一段带 `# >>> deskbuddy >>>` / `# <<< deskbuddy <<<` 标记的块；其余字节一个都不碰，也不重排、不丢注释 |
-| `~/.deskbuddy/` | 我们自己的目录：`config.json`（clientId、授权状态）、`hook.cjs`、`state/*.json`（每个会话一份）、`tool-registry.json` |
-
-写这两个用户文件时都是**原子写并保留原权限位**（`config.toml` 通常是 `0600`，不会被放宽）。
+| `~/.claude/settings.json` | **幂等合并**上报 hook 与窗口授权 hook（你已有的 hook 一条都不动） |
+| `~/.codex/config.toml` | 在文件**末尾追加**一段带 `# >>> deskbuddy >>>` / `# <<< deskbuddy <<<` 标记的块；其余字节一个都不碰 |
+| `~/.workbuddy/settings.json`、`~/.qoder-cn/settings.json` | 同 Claude Code，幂等合并 |
+| `~/.config/opencode/plugin/deskbuddy.js` | 新建一个几行的插件入口（同名文件不是我们生成的就拒绝覆盖） |
+| `~/Library/LaunchAgents/com.deskbuddy.daemon.plist`（macOS）/ systemd 用户单元（Linux）/ 「启动」文件夹里的 `DeskBuddyDaemon.vbs`（Windows，不需要管理员权限） | 守护进程开机自启 |
+| `~/.deskbuddy/` | 我们自己的目录：授权配置、hook 与授权关卡脚本、opencode 插件本体、每个会话的状态、待批准记录、守护进程日志 |
 
-**不碰** `~/.claude/fleet/`（那是用户自己的 fleet 系统）。
+写用户配置文件时都是**原子写并保留原权限位**（`config.toml` 通常是 `0600`，不会被放宽）。
 
 ---
 
 ## 卸载
 
 ```bash
-npx deskbuddy disable            # 移除全部 hook，保留授权与 clientId，随时可再 enable
-npx deskbuddy logout             # 移除 hook + 删除整个 ~/.deskbuddy（要确认，--yes 跳过）
+npx deskbuddy@beta disable codex     # 只移除某个工具
+npx deskbuddy@beta disable           # 移除全部 hook 与开机自启，保留授权，随时可再 enable
+npx deskbuddy@beta logout            # 移除 hook 与自启 + 删除整个 ~/.deskbuddy（要确认，--yes 跳过）
 ```
 
-`disable` 只摘掉我们自己那一条：Claude Code 侧按 hook 路径匹配，Codex 侧只删两个标记之间的行。
-用户自己的 hook 原样保留。
+`disable` 只摘掉我们自己那一条：JSON 配置按 hook 路径匹配，Codex 只删两个标记之间的行，opencode 只删带我们标记的入口文件。
+用户自己的 hook / 插件原样保留。
 
 ---
 
 ## 隐私边界
 
-**上报**：工具名、状态（进行中/待确认/已完成/失败）、会话标题、**项目目录名**（不是全路径）、时间戳。
+**状态上报**：工具名、状态（进行中 / 待确认 / 已完成）、会话标题、**项目目录名**（不是全路径）、窗口是否开着、时间戳。
+
+**等设备批准时**：要执行的命令或要改的文件（压成一行、截断到 200 字）会发到服务端、显示在设备卡片上——不然你没法判断该不该允许。
+
+**最近工作目录**（给设备「选目录新建任务」用）：只报目录名，全路径留在本机；目录用本机密钥做 HMAC 得到的编号来引用。
 
-**不上报**：prompt 原文、Bash 命令、文件完整路径、代码片段。
+**不上报**：prompt 原文、智能体的回复、代码片段、文件内容。
 
 会话标题的来源按顺序回落，都不涉及 prompt 内容：
 
-1. Claude Code 自己写在 transcript 里的 `aiTitle`（只读文件尾部 64KB，不遍历整个文件）
-2. Codex 的 `session_index.jsonl` 里的 `thread_name`（多数用户是空的，属于机会主义的一级）
+1. Claude Code 自己写在 transcript 里的 `aiTitle`（只读文件尾部 64KB）
+2. Codex 的 `session_index.jsonl` 里的 `thread_name`（多数用户是空的）
 3. 当前 git 分支名（读 `.git/HEAD`，向上找 5 层）
 4. 项目目录名
 
@@ -133,7 +177,8 @@ npx deskbuddy logout             # 移除 hook + 删除整个 ~/.deskbuddy（要
 客户端**不持有任何用户 token**：鉴权靠服务端的 clientId ↔ 用户绑定关系，绑定在 App 扫码时建立。
 源码里那个 `appSecret` 是随包公开的常量，不是密钥。
 
-随时用 `npx deskbuddy status` 查看当前采集到了什么 —— 它最后固定会打印上面这两行采集范围。
+**远程任务的安全边界**：设备下发的文字永远作为一个独立参数交给智能体，不拼进 shell；
+远程任务里除只读操作和工作目录内改文件外，每一步都要在设备上批准；授权关卡出任何错都按「拒绝」处理。
 
 ---
 
@@ -141,12 +186,15 @@ npx deskbuddy logout             # 移除 hook + 删除整个 ~/.deskbuddy（要
 
 | 现象 | 先查什么 |
 |---|---|
-| 屏幕上没数据 | `npx deskbuddy status`：先看「已启用」里是不是「hook 已装」 |
+| 屏幕上没数据 | `status`：「已启用」里是不是「hook 已装」；智能体窗口是不是装完之后才打开的 |
 | Codex 装了但没数据 | **十有八九是没在 Codex 里确认信任 hook**，重启 Codex 看有没有确认提示 |
-| 提示「还没有授权」 | 先跑 `npx deskbuddy setup` |
-| 刚扫完提示码失效 | 偶发一次是正常的，会自动重试；**连续失败多半是这台电脑已绑定其他账号**（一台电脑同时只能绑一个账号），先 `npx deskbuddy logout` 再重新 `setup` |
-| 提示「已绑定其他账号」 | 按提示先 `npx deskbuddy logout` 再 `setup`。注意 `logout` 只清本机数据，服务端那边的绑定要在 App 里撤销（暂未支持） |
-| 升级后旧 bug 还在 | 不用管，任意 `deskbuddy` 命令启动时会自动把 `~/.deskbuddy/hook.cjs` 校准到当前包版本；`status` 的「hook 版本」行会显示是否一致 |
-| 会话关了还挂在屏幕上 | 上报靠进程存活探测，通常几分钟内自己消失 |
+| 设备下指令没反应 / 批准卡片不出现 | `tail ~/.deskbuddy/daemon.log` 看有没有「已连上」；没有就 `npx deskbuddy@<版本> update` 重启守护进程 |
+| 下指令报「这个任务正在电脑上打开」 | 正常：窗口开着时不能远程续同一个会话（两边会互相吞对话）。在电脑上继续，或在设备上新建任务 |
+| Codex 窗口授权框没同步到设备 | 是不是经 `--remote` 连常驻 app-server 用的；`daemon.log` 里有没有「已连上 Codex app-server」 |
+| opencode 远程任务每一步都失败 | 插件不在：`ls ~/.config/opencode/plugin/deskbuddy.js`，没有就 `enable opencode` |
+| 提示「还没有授权」 | 先跑 `setup` |
+| 刚扫完提示码失效 | 偶发一次是正常的，会自动重试；**连续失败多半是这台电脑已绑定其他账号**，先 `logout` 再重新 `setup` |
+| `status` 第二行显示生产环境 | `setup` 时漏了 `--api-base`：`logout` 后带上它重新 `setup` |
+| 会话关了还挂在屏幕上 | 上报靠进程存活探测，通常 1～几分钟内自己消失 |
 
 联调用环境变量（正常用户用不到）：`DESKBUDDY_API_BASE`、`DESKBUDDY_HOME`、`DESKBUDDY_APPID`、`DESKBUDDY_APPSECRET`。