Agents Explorer — Agent Sessions

在 VS Code 活动栏一处全局观察本机所有 claude CLI 会话，通过 Claude Code hook 写状态文件点亮四态徽标 + 标注来源。

是什么 / 不是什么

核心诉求：机器上任何地方跑的 claude（别的 VS Code 窗口、macOS 自带终端、iTerm 里的 cc-*）散落各处看不全、原生终端又看不出状态。本扩展把它们全部汇到一处列表，一眼看出哪个在跑、哪个在等我、哪个跑完了，以及它来自哪个终端。

VS Code 原生 Terminal 接口图标/颜色创建后不可改（vscode.d.ts 全 readonly），要动态显示状态必须自建 TreeView——这是本扩展存在的理由。

做：活动栏全局会话列表（活跃 + 历史两视图）+ 四态图标 + 来源标注 + New Session 开裸终端 + 点击 claude --resume 恢复历史会话 + 选中终端左侧行高亮联动 + waiting 提醒 + 防休眠。

刻意砍掉：项目化分组、multi-root、模型切换 UI、codex 端到端；跟随终端 tab 顺序（VS Code API 做不到，见 AGENTS.md）；远程会话跨窗口点击（本窗口无 Terminal 对象）。New Session 只开裸终端，你自己敲 cc-glm——扩展不维护网关清单。

四态

状态只来自 hook 写的状态文件，从不解析终端输出。

工作原理（全局文件真源，无 HTTP server）

1. 激活时把 agents-explorer-hook.sh + agents-explorer-hook.py 写到 globalStorage，并全局 append 到 ~/.claude/settings.json 各事件（与 Orca 等已有 hook 并存，带备份、幂等）
2. 任何终端里跑 claude → Claude Code 触发全局 hook → .sh 把 stdin payload 管道喂给 .py
3. .py 解析 payload 的 session_id / cwd / 事件名 + 读环境变量 $TERM_PROGRAM（来源）/ $SSH_CONNECTION（远程）→ 原子写 globalStorage/sessions/<session_id>.json
4. 扩展 fs.watch 该目录 → 防抖重扫所有会话文件 → 映射四态 + 归一化来源 → TreeView 刷新

为什么是文件不是 server：globalStorage 是扩展级共享目录，多个 VS Code 窗口读同一份真源、列表天然一致；文件系统跨窗口/跨进程，没有 HTTP 端口的多实例冲突。hook 写盘任何失败一律 exit 0，绝不阻塞 claude。

会话消失：hook 报 SessionEnd，或超 6h 未更新 → 扫描时删文件、移出列表。

开发 / 调试

npm install
npm run compile     # 或 F5 自动 watch 编译

按 F5 启动扩展开发宿主 → 活动栏「智能体资源管理器」图标 →「活跃会话」/「历史会话」两视图 → 顶栏 ＋ 新建会话。

注意：首次激活会真写 ~/.claude/settings.json（带 .agents-explorer-backup-<ts> 备份）。若该文件含注释（非纯 JSON），扩展会拒绝自动安装并提示，不破坏文件。

验证

不用真跑 claude：往 globalStorage/sessions/ 丢一个 <uuid>.json，列表即刻出现一行：

DIR="$HOME/Library/Application Support/Code/User/globalStorage/adaex.vscode-agents-explorer/sessions"
mkdir -p "$DIR"
# 变黄（等待）——字段见 src/hook/sessionFile.ts
printf '%s' '{"sessionId":"demo-1","event":"PermissionRequest","cwd":"/tmp","termProgram":"Apple_Terminal","isRemote":false,"transcriptPath":"","title":"","ts":0,"shellPid":0}' > "$DIR/demo-1.json"
# 改 event 为 Stop → 变绿；删掉文件 → 行消失

端到端：在任意终端（含本扩展外的）敲 cc-glm 发 "1+1" → 列表出现该会话 idle→working→done + 来源标注；触发一次权限 → waiting（黄）。

事件→四态映射

照搬本机 Orca relay.js 的 claude 映射（src/hook/stateMap.ts）：

• working ← UserPromptSubmit / PreToolUse / PostToolUse / PostToolUseFailure / PreCompact / SubagentStart
• waiting ← PermissionRequest / Notification
• done ← Stop / StopFailure / SubagentStop / TeammateIdle
• idle ← SessionStart（会话开始/恢复/清空，就绪未活动）
• SessionEnd → 删除会话（不是一种状态）

hook API 会演进，确切事件名以当前 Claude Code 版本为准。