deskbuddy 0.0.1 → 0.1.0

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`。