deskbuddy 0.0.1 → 0.2.0-beta.0

package/dist/opencode.mjs

@@ -0,0 +1,329 @@
+// DeskBuddy 的 opencode 插件本体（二期 P9）。
+// `deskbuddy enable opencode` 在 opencode 的插件目录放一个入口文件 import 本文件；
+// 本文件随 hook.cjs / gate.cjs 一起同步到 ~/.deskbuddy/，CLI 升级即生效。
+//
+// 做的事只有翻译：把 opencode 的事件翻成 cc-hook 同构的输入，喂给同目录的 hook.cjs（状态上报）
+// 和 gate.cjs（授权关卡）。状态机、关卡、和设备打交道全在它们和 daemon 里，这里不重复。
+//
+// 实测依据（opencode 1.18.32；1.4.3 远程关卡与窗口确认同样实测通过，spec 2026-09-27-DeskBuddy二期 §P9 O1–O8）：
+// - 插件的 `permission.ask` 钩子不会被调用；授权只能从事件流的 permission.asked / permission.replied 拿
+// - `tool.execute.before` 在权限判断之前触发、可以 await 任意久、抛错 = 这次调用失败
+// - `opencode run` 遇到 ask 立即自动拒绝
+// - `config` 钩子原地改 permission 能生效（整对象替换不行）
+//
+// 🔴 远程任务（环境变量 DESKBUDDY_GATE_RUN）的安全模型，三层：
+//    ① daemon 起进程前确认插件装在 opencode 会读的位置（daemon/index.ts）；
+//    ② OPENCODE_CONFIG_CONTENT 把 OC_GATED_KEYS 逐项压成 deny（全局 + build agent 两级）。
+//       opencode 按"最后一条匹配的规则"生效且配置是深合并：只写 `*: deny` 挡不住用户配置里排在后面的
+//       `bash: allow`（评审 2026-09-28 实测），逐项写才会把同名键的值覆盖掉；
+//    ③ 本插件加载后才在 config 里放开、并在 tool.execute.before 里等设备。
+//    残余：用户给清单外的权限名写了 allow，且插件恰好加载失败 —— 那一项会放行。远程模式下本文件任何失败都必须走"拒绝"。
+// 🔴 窗口模式反过来：任何失败都不表态，授权框照常由人处理。
+
+import { spawn } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const HOOK = join(HERE, 'hook.cjs')
+const GATE = join(HERE, 'gate.cjs')
+const TOOL = 'opencode'
+
+/** 设备允许过的工具调用，后续同一调用的第二个授权框直接代答（O6：rm /tmp/x 会连问 external_directory 和 bash） */
+const APPROVED_CALL_TTL_MS = 60 * 1000
+/** 工具调用参数的缓存时长：tool.execute.before 记下，随后的授权框靠它显示真实命令 */
+const CALL_TTL_MS = 10 * 60 * 1000
+/** hook.cjs 自己有 2 秒上报超时，这里再兜一层：一次卡死不能堵住后面所有状态 */
+const HOOK_KILL_MS = 10 * 1000
+
+/**
+ * 远程模式要压成 deny、插件加载后再放开的权限名。与 src/daemon/executor.ts 的 OPENCODE_GATED_KEYS 必须一致（有测试）。
+ * 新版本 opencode 多出来的权限名不在这里时，只剩 `*` 兜，见顶部"残余"
+ */
+export const OC_GATED_KEYS = [
+  '*', 'bash', 'edit', 'write', 'read', 'glob', 'grep', 'list', 'task', 'webfetch', 'websearch', 'codesearch',
+  'external_directory', 'todowrite', 'todoread', 'lsp', 'skill', 'doom_loop', 'patch', 'apply_patch',
+]
+
+function runIdFromEnv() {
+  const v = process.env.DESKBUDDY_GATE_RUN || ''
+  return /^[0-9a-zA-Z_-]{1,64}$/.test(v) ? v : ''
+}
+
+/**
+ * `opencode run` 是非交互（O2），其余（TUI、`opencode <目录>`）当窗口。编译版 argv = [bun, 入口, 子命令…]。
+ * 子命令前可能有全局参数（`--print-logs run`），所以看 `--` 之前有没有 `run`；误判成非交互只是少一个确认渠道
+ */
+export function isHeadless(argv = process.argv) {
+  const args = argv.slice(2)
+  const end = args.indexOf('--')
+  return (end >= 0 ? args.slice(0, end) : args).includes('run')
+}
+
+/** opencode 工具 → cc-hook 同构的 tool_name / tool_input（daemon 的 classify 按 Claude Code 的工具名判断） */
+export function toCcTool(tool, args) {
+  const a = args && typeof args === 'object' ? args : {}
+  const s = (v) => (typeof v === 'string' ? v : '')
+  switch (tool) {
+    case 'bash':
+      return { tool_name: 'Bash', tool_input: { command: s(a.command) } }
+    case 'read':
+      return { tool_name: 'Read', tool_input: { file_path: s(a.filePath) } }
+    case 'edit':
+      return { tool_name: 'Edit', tool_input: { file_path: s(a.filePath) } }
+    case 'write':
+      return { tool_name: 'Write', tool_input: { file_path: s(a.filePath) } }
+    case 'glob':
+      return { tool_name: 'Glob', tool_input: { pattern: s(a.pattern), path: s(a.path) } }
+    case 'grep':
+      return { tool_name: 'Grep', tool_input: { pattern: s(a.pattern), path: s(a.path) } }
+    case 'list':
+      return { tool_name: 'LS', tool_input: { path: s(a.path) } }
+    case 'webfetch':
+      return { tool_name: 'WebFetch', tool_input: { url: s(a.url) } }
+    case 'task':
+      return { tool_name: 'Task', tool_input: {} }
+    case 'todowrite':
+    case 'todoread':
+      return { tool_name: 'TodoWrite', tool_input: {} }
+    case 'patch':
+    case 'apply_patch':
+      return { tool_name: 'apply_patch', tool_input: { patch: s(a.patchText) || s(a.patch) || s(a.input) } }
+    default:
+      // 不认识的工具（MCP 等）原名原参数交出去：classify 对不认识的一律推设备
+      return { tool_name: String(tool || ''), tool_input: a }
+  }
+}
+
+/** permission.asked → PermissionRequest 的 tool_name / tool_input，给设备卡片生成摘要 */
+export function askToCc(props) {
+  const md = (props && props.metadata) || {}
+  if (typeof md.command === 'string' && md.command) return { tool_name: 'Bash', tool_input: { command: md.command } }
+  const file = md.filepath || md.filePath
+  if (typeof file === 'string' && file) return { tool_name: 'Edit', tool_input: { file_path: file } }
+  const patterns = Array.isArray(props && props.patterns) ? props.patterns.join(' ') : ''
+  return { tool_name: String((props && props.permission) || 'permission'), tool_input: { path: patterns } }
+}
+
+/**
+ * 远程模式：关卡改由 tool.execute.before 把，放开权限。🔴 必须原地改（整对象替换不生效，O8）。
+ * - OC_GATED_KEYS 是 daemon 压成 deny 的，放成 allow（用户原来在这些键上写的值已被覆盖，找不回来 —— 每一步都要过设备）
+ * - 其余键上的 ask 放成 allow（run 下 ask = 立即拒），用户显式的 deny 保留
+ * 全局与 build agent 两级都放（daemon 两级都压了）
+ */
+export function openPermissions(cfg) {
+  if (!cfg || typeof cfg !== 'object') return
+  const open = (perm) => {
+    const walk = (obj) => {
+      for (const k of Object.keys(obj)) {
+        const v = obj[k]
+        if (v === 'ask') obj[k] = 'allow'
+        else if (v && typeof v === 'object') walk(v)
+      }
+    }
+    walk(perm)
+    for (const k of OC_GATED_KEYS) perm[k] = 'allow'
+  }
+  if (!cfg.permission || typeof cfg.permission !== 'object') cfg.permission = {}
+  open(cfg.permission)
+  const build = cfg.agent && cfg.agent.build
+  if (build && build.permission && typeof build.permission === 'object') open(build.permission)
+}
+
+/** 活着的子进程；opencode 退出时一并结束，不留孤儿 gate 挂着设备卡片（评审） */
+const LIVE = new Set()
+process.on('exit', () => {
+  for (const c of LIVE) {
+    try {
+      c.kill('SIGTERM')
+    } catch (_) {
+      /* 已经退了 */
+    }
+  }
+})
+
+/** 起 node 子进程跑 hook.cjs / gate.cjs，stdin 喂 JSON。返回子进程句柄与结束结果（起不来 = code -1）。killMs > 0 时到点结束 */
+function startChild(node, script, args, input, killMs = 0) {
+  let child = null
+  const done = new Promise((resolve) => {
+    let out = ''
+    let err = ''
+    try {
+      child = spawn(node, [script, ...args], { stdio: ['pipe', 'pipe', 'pipe'] })
+    } catch (e) {
+      resolve({ code: -1, out, err: String(e) })
+      return
+    }
+    LIVE.add(child)
+    const timer = killMs > 0 ? setTimeout(() => child.kill('SIGKILL'), killMs) : null
+    const finish = (r) => {
+      LIVE.delete(child)
+      if (timer) clearTimeout(timer)
+      resolve(r)
+    }
+    child.stdout.on('data', (c) => (out += c))
+    child.stderr.on('data', (c) => (err += c))
+    child.on('error', (e) => finish({ code: -1, out, err: String(e) }))
+    child.on('close', (code) => finish({ code, out, err }))
+    child.stdin.on('error', () => {})
+    child.stdin.end(JSON.stringify(input))
+  })
+  return { child, done }
+}
+
+const runChild = (node, script, args, input, killMs) => startChild(node, script, args, input, killMs).done
+
+export function make(opts = {}) {
+  return async function DeskBuddy(ctx) {
+    const node = process.env.DESKBUDDY_NODE || opts.node || 'node'
+    const client = ctx && ctx.client
+    const cwd = (ctx && (ctx.directory || ctx.worktree)) || process.cwd()
+    const runId = runIdFromEnv()
+    const headless = isHeadless()
+
+    // ---- 状态上报：串行喂 hook.cjs，保证 PreToolUse / PostToolUse / Stop 的先后 ----
+    let queue = Promise.resolve()
+    const report = (event, sessionID, extra) => {
+      if (!sessionID) return
+      const input = { hook_event_name: event, session_id: sessionID, cwd, ...extra }
+      queue = queue.then(() => runChild(node, HOOK, [TOOL], input, HOOK_KILL_MS)).catch(() => {})
+    }
+
+    // ---- 窗口确认 ----
+    const pending = new Map() // requestID → gate 子进程
+    const approvedCalls = new Map() // callID → 允许时间
+    const calls = new Map() // callID → { cc, at }：这次工具调用的真实参数
+    const prune = () => {
+      const now = Date.now()
+      for (const [k, v] of calls) if (now - v.at > CALL_TTL_MS) calls.delete(k)
+      for (const [k, at] of approvedCalls) if (now - at > APPROVED_CALL_TTL_MS) approvedCalls.delete(k)
+    }
+
+    const reply = async (sessionID, id, response) => {
+      try {
+        await client.postSessionIdPermissionsPermissionId({ path: { id: sessionID, permissionID: id }, body: { response } })
+      } catch (_) {
+        /* 已被人答复过等，无所谓 */
+      }
+    }
+
+    const toast = async (message) => {
+      try {
+        await client.tui.showToast({ body: { message, variant: 'info' } })
+      } catch (_) {
+        /* 没有 TUI（web / acp）就不提示 */
+      }
+    }
+
+    const onAsked = async (p) => {
+      const { id, sessionID } = p || {}
+      if (!id || !sessionID) return
+      prune()
+      const callID = p.tool && p.tool.callID
+      // 🔴 卡片用这次工具调用的真实参数（tool.execute.before 先于授权触发，O3）。
+      //    external_directory 的 ask 自己不带命令，按它出卡片设备只看到"访问 /tmp/*"（评审）
+      const call = callID ? calls.get(callID) : null
+      const cc = call ? call.cc : askToCc(p)
+      report('PermissionRequest', sessionID, cc)
+      if (runId || headless || !client) return
+      // 同一调用的后续授权框直接代答：只在设备那张卡显示的就是真实参数时（approvedCalls 只在那时写入）
+      const at = callID && approvedCalls.get(callID)
+      if (at && Date.now() - at < APPROVED_CALL_TTL_MS) {
+        await reply(sessionID, id, 'once')
+        return
+      }
+      const input = { hook_event_name: 'PermissionRequest', session_id: sessionID, cwd, ...cc }
+      const { child, done } = startChild(node, GATE, ['--window', '--tool', TOOL], input)
+      if (child) pending.set(id, child)
+      const r = await done
+      pending.delete(id)
+      if (r.code !== 0 || !r.out) return
+      let out
+      try {
+        out = JSON.parse(r.out)
+      } catch (_) {
+        return
+      }
+      const d = out && out.hookSpecificOutput && out.hookSpecificOutput.decision
+      if (!d) return
+      if (d.behavior === 'allow') {
+        if (callID && call) approvedCalls.set(callID, Date.now())
+        await reply(sessionID, id, 'once')
+      } else if (d.behavior === 'deny') {
+        await reply(sessionID, id, 'reject')
+      } else return
+      if (typeof out.systemMessage === 'string' && out.systemMessage) await toast(out.systemMessage)
+    }
+
+    const onReplied = (p) => {
+      // 人先在窗口里答了：结束 gate 子进程，daemon 随之撤掉设备上的卡片
+      const child = p && pending.get(p.requestID)
+      if (child) {
+        pending.delete(p.requestID)
+        try {
+          child.kill('SIGTERM')
+        } catch (_) {
+          /* 已经退了 */
+        }
+      }
+    }
+
+    return {
+      config: async (cfg) => {
+        if (runId) openPermissions(cfg)
+      },
+
+      'chat.message': async (input) => {
+        report('UserPromptSubmit', input && input.sessionID)
+      },
+
+      'tool.execute.before': async (input, output) => {
+        const cc = toCcTool(input && input.tool, output && output.args)
+        if (input && input.callID) calls.set(input.callID, { cc, at: Date.now() })
+        report('PreToolUse', input && input.sessionID, cc)
+        if (!runId) return
+        // 远程关卡：等设备。任何失败都拒（见顶部）
+        const r = await runChild(node, GATE, ['--run', runId], {
+          hook_event_name: 'PreToolUse',
+          session_id: (input && input.sessionID) || '',
+          cwd,
+          ...cc,
+        })
+        let decision = ''
+        try {
+          decision = JSON.parse(r.out).hookSpecificOutput.permissionDecision
+        } catch (_) {
+          decision = ''
+        }
+        if (r.code === 0 && decision === 'allow') return
+        throw new Error((r.err || '').trim() || '用户在设备上拒绝了这一步')
+      },
+
+      'tool.execute.after': async (input) => {
+        if (input && input.callID) calls.delete(input.callID)
+        approvedCalls.delete(input && input.callID)
+        const cc = toCcTool(input && input.tool, input && input.args)
+        report('PostToolUse', input && input.sessionID, cc)
+      },
+
+      event: async ({ event }) => {
+        const p = (event && event.properties) || {}
+        switch (event && event.type) {
+          case 'permission.asked':
+            onAsked(p).catch(() => {})
+            break
+          case 'permission.replied':
+            onReplied(p)
+            break
+          case 'session.idle':
+            report('Stop', p.sessionID)
+            break
+          case 'session.deleted':
+            report('SessionEnd', (p.info && p.info.id) || p.sessionID)
+            break
+          default:
+        }
+      },
+    }
+  }
+}

package/docs/INSTALL.md

@@ -0,0 +1,152 @@
+# DeskBuddy 安装指南（给 AI 助手照做的操作手册）
+
+> 这份文档是写给**用户的 AI 编码助手**读的。用户会说「照着这个文档把 DeskBuddy 装上」，
+> 你按顺序执行下面的步骤即可。每一步都给了**判定成功的依据**，不满足就按「排查」一节处理。
+> 需要用户本人动手的地方（扫码、Codex 授信）已经标出来了，到那一步要停下来告诉用户。
+
+DeskBuddy 把 Claude Code、Codex 等 AI 编码智能体**每个会话窗口**的状态，实时同步到桌面硬件屏幕。
+多开会话时不用挨个切窗口看哪个在等确认、哪个跑完了。
+
+---
+
+## 0. 前置条件
+
+```bash
+node -v    # 必须 ≥ 18
+```
+
+不满足就先让用户升级 Node，别继续。
+
+**装完不会有任何常驻进程**：它只是往各智能体自己的 hook 配置里加了一条记录，由智能体在事件发生时调用。
+
+---
+
+## 1. 授权（需要用户本人扫码）
+
+```bash
+npx deskbuddy setup
+```
+
+终端会打印一个二维码和一行明文授权码，然后停在「等待授权中…」。
+
+**这一步你（AI 助手）替代不了**，要告诉用户：
+
+> 用 DeskBuddy App 扫描终端里的二维码；扫不出来就在 App 里手动输入那行授权码。
+
+- 授权码 5 分钟内有效，过期就重新跑一次 `setup`
+- 终端字符画受字体/行高/深浅色主题影响，有些终端**扫不出来**，这时用明文码手输，不是故障
+- 成功后终端打印 `✅ 授权成功`，本机 `~/.deskbuddy/config.json` 里会多一个 `boundAt` 字段
+
+**判定成功**：命令退出码为 0 且打印了 `✅ 授权成功`。
+
+---
+
+## 2. 安装采集 hook
+
+```bash
+npx deskbuddy enable claude_code,codex     # 只用其中一个就只写一个
+```
+
+**判定成功**：每个工具各打印一行 `✅ <tool>：hook 已装进 <路径>`。
+
+### 🔴 Codex 用户必读：还要在 Codex 里确认信任
+
+Codex 对 hook 定义做 sha256 校验，**首次运行会要求你确认信任这个 hook，不确认它就不执行**。
+现象是「装成功了但屏幕上一直没数据」，极容易被当成安装失败。
+
+所以装完 codex 之后要告诉用户：
+
+> 下次启动 Codex 时会弹出确认信任 hook 的提示，请选择同意。
+
+**不要**用 `--dangerously-bypass-hook-trust` 替用户绕过这个确认。
+
+---
+
+## 3. 验证
+
+```bash
+npx deskbuddy status
+```
+
+应该看到：账号已授权、已启用的工具都显示「hook 已装」、hook 版本与当前包一致。
+让智能体随便跑个任务，再看一次 `status`，「当前本地会话」里就会出现内容。
+
+---
+
+## 国内用户
+
+本机 npm 若走淘宝镜像，装最新版可能有几分钟同步延迟：
+
+```bash
+npx --registry=https://registry.npmmirror.com deskbuddy setup
+```
+
+装不到最新版就临时改用官方源：
+
+```bash
+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/fleet/`（那是用户自己的 fleet 系统）。
+
+---
+
+## 卸载
+
+```bash
+npx deskbuddy disable            # 移除全部 hook，保留授权与 clientId，随时可再 enable
+npx deskbuddy logout             # 移除 hook + 删除整个 ~/.deskbuddy（要确认，--yes 跳过）
+```
+
+`disable` 只摘掉我们自己那一条：Claude Code 侧按 hook 路径匹配，Codex 侧只删两个标记之间的行。
+用户自己的 hook 原样保留。
+
+---
+
+## 隐私边界
+
+**上报**：工具名、状态（进行中/待确认/已完成/失败）、会话标题、**项目目录名**（不是全路径）、时间戳。
+
+**不上报**：prompt 原文、Bash 命令、文件完整路径、代码片段。
+
+会话标题的来源按顺序回落，都不涉及 prompt 内容：
+
+1. Claude Code 自己写在 transcript 里的 `aiTitle`（只读文件尾部 64KB，不遍历整个文件）
+2. Codex 的 `session_index.jsonl` 里的 `thread_name`（多数用户是空的，属于机会主义的一级）
+3. 当前 git 分支名（读 `.git/HEAD`，向上找 5 层）
+4. 项目目录名
+
+⚠️ 第 3 级意味着**分支名会显示在桌面屏幕上**。如果分支名本身敏感（含客户名等），注意这一点。
+
+客户端**不持有任何用户 token**：鉴权靠服务端的 clientId ↔ 用户绑定关系，绑定在 App 扫码时建立。
+源码里那个 `appSecret` 是随包公开的常量，不是密钥。
+
+随时用 `npx deskbuddy status` 查看当前采集到了什么 —— 它最后固定会打印上面这两行采集范围。
+
+---
+
+## 排查
+
+| 现象 | 先查什么 |
+|---|---|
+| 屏幕上没数据 | `npx deskbuddy 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 版本」行会显示是否一致 |
+| 会话关了还挂在屏幕上 | 上报靠进程存活探测，通常几分钟内自己消失 |
+
+联调用环境变量（正常用户用不到）：`DESKBUDDY_API_BASE`、`DESKBUDDY_HOME`、`DESKBUDDY_APPID`、`DESKBUDDY_APPSECRET`。