Agents Explorer — Agent Sessions

中文 UI 显示名:智能体资源管理器

在 VS Code 活动栏一处全局观察本机所有智能体会话（Claude Code / Codex），通过 CLI hook 记事件流点亮五态徽标 + 标注来源。

是什么 / 不是什么

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

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

做：活动栏全局会话列表（活跃 + 历史两视图，Claude Code 与 Codex 双智能体）+ 五态图标 + 来源标注 + 新建终端开裸终端 + 点击恢复历史会话（claude --resume / codex resume）+ 选中终端左侧行高亮联动 + 点行按文件夹编排编辑器区终端 + 收起其他文件夹的终端 + SCM 选中联动 + 他窗终端接管 + waiting 提醒 + 防休眠 + 噪音会话全局过滤（子会话默认隐藏，命令面板可切换）。

「继续」与「接管」是两件事，别混：

刻意砍掉：multi-root、模型切换 UI、活跃视图项目化分组、跟随终端 tab 顺序等——完整清单与理由见 AGENTS.md「需求边界」。新建终端只开裸终端，命令由你自己在终端里敲。

快速上手

前置条件

• macOS（核心组件与防休眠仅 macOS 本地窗口可用；关窗保活只对远程会话成立；列表/状态/历史在远程 Linux 也正常）
• VS Code stable 1.137+（engines 声明 ^1.137.0；Insiders 未适配）
• Claude Code CLI 已安装并登录（claude 命令在 PATH 里）。Codex CLI 可选

安装

VS Code Marketplace 搜「智能体资源管理器」或「Agents Explorer」安装，或命令面板 ext install adaex.vscode-agents-explorer。

装完会发生什么（按顺序）

1. 同意门弹窗 → 点「启用」。这会向 ~/.claude/settings.json 与 ~/.codex/hooks.json 各注入一条 hook command（与已有配置并存，改前自动备份）。想撤销：命令面板运行「移除事件采集 Hook」（或健康详情页末尾那一行），它会删掉注入项并记住你的选择，不会在下次启动时装回来。同时扩展会调整 VS Code 全局设置：会话持久化两条 + SSH 断线宽限（这三条受 agentsExplorer.manageGlobalSettings 管，完整清单见下「设置」节），外加 Ctrl+V 贴图要用的 terminal.integrated.commandsToSkipShell（受 agentsExplorer.pasteImage.enabled 管，关了就不抢这个键位）；不想让它改就把对应开关关掉——健康详情照样告诉你哪条不符合预期、不改会怎样，只是不动手
2. macOS「App 管理」授权弹窗 → 点「允许」。核心组件要写 VS Code 应用程序包，首次触发系统授权；点了不允许则跨窗口接管、贴图等桥能力不可用，显式关闭终端也不会被拦截（列表/状态不受影响；关窗保活的主体是服务端 patch，不依赖桥）
3. 核心组件自动装好的通知 → 完全退出 VS Code（Cmd+Q）再重开，桥与防休眠才生效
4. Codex 用户：第一次跑 codex 时在弹出的 Hook 审查里选「Trust all and continue」，否则 Codex 会话不会出现

验证

1. 活动栏点「智能体资源管理器」图标（$(agent)），看到「活跃会话」「历史会话」两个视图
2. 在任意终端（VS Code 终端、iTerm、系统终端均可）跑 claude 发一条消息
3. 会话出现在列表，状态从 idle（空心圈）→ working（转圈）→ done（绿勾）
4. 点左下角 homeBar（$(agent) 字样）看健康详情，各子项 ✓ 即正常

常见问题

• 列表永远空：点 homeBar 看健康详情。「事件采集」红 = 同意门没启用（点修法一键启用）；「Codex Hook 信任」黄 = 上面第 4 步没做
• 核心组件装不上：仅 macOS 本地窗口自动装（远程窗口的桥在客户端，够不到）。命令面板「安装核心组件」可手动重试
• 关窗保活不生效：健康详情「会话保活」子项看状态；只对远程会话成立（本地终端随 VS Code 退出结束，架构上无解）
• hook 改坏了配置：每次改动都有备份（~/.claude/settings.json.agents-explorer-backup-*），回滚即可

核心组件（必选）与会话保活

核心组件是必选核心（2026-09-09 起）：不装时列表、五态、历史恢复照常，但跨窗口接管、贴图、右键精确定位、关终端确认门分档等桥能力不可用，健康检查会报红。关窗保活的主体是服务端 bundle patch、不依赖桥，桥只补上「显式杀终端也杀不死」这一条路径：

• 核心组件：注入客户端 workbench 的一小段脚本，用来调 VS Code 的内部能力（跨窗口接管终端、读终端真实位置、精确清理树选中）。仅本地 macOS 窗口能自动安装，会修改 VS Code 应用程序包，首次触发 macOS「App 管理」授权（点允许即可）；VS Code 每次升级会冲掉，扩展会自动重装。命令面板「安装核心组件」可手动触发
• 会话保活：让远程会话在关窗后不被回收（关窗从 0 秒变成「保活时长」，默认 5 天，改设置 agentsExplorer.keepAlive.days，改完需重启远程 server），重连接回原对话。三条硬边界：① 只对远程会话成立（本地终端进程随 VS Code 退出结束，架构上无解）；② 远程机重启会丢（布局是 server 内存态、不落盘）；③ VS Code 跨版本升级接不回 pty（上游握手要求版本严格一致），升级必然损失正在跑的那一轮，但历史对话仍在、可 resume

设置

只有四项，都在设置里搜 agentsExplorer 可见。其余行为（分组/平铺、历史时段、噪音过滤、静默）是每台机器共享的偏好，走视图按钮与命令面板，不进设置。

那三条全局设置分别是 terminal.integrated.enablePersistentSessions、terminal.integrated.persistentSessionReviveProcess、remote.SSH.reconnectionGraceTime——注意它们的影响面溢出本扩展（对所有终端与远程窗口生效），这也是给出开关的原因。

五态

图标形状 = 状态，颜色 = 行级统一色（图标与文字永远同色）：

• 图标与文字同色（统一取 rowColor）：完成态（done/error）未读=整行亮（绿/红，含行尾 ●）、查看后回默认色；waiting 非无响应时整行亮黄（由 ⚠ 徽标无条件催促）；working/idle 默认色。
• 无响应（进程崩溃/被杀/休眠回收）：working/waiting 降级为圆圈斜杠（circle-slash），不再转圈/黄警那种"进程还在"的假象。
• 无本窗口终端的会话（他窗/外部）整行灰化（图标一起灰），但未读仍亮绿/红、waiting 仍亮黄（注意力信号优先于灰）。

状态只来自 hook 记的事件流，从不解析终端输出。

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

1. 激活时把 agents-explorer-hook.sh（双智能体共用，纯 POSIX shell 无依赖）写到 ~/.local/state/agents-explorer/（机器级共享目录，可被 $XDG_STATE_HOME 覆盖），并把 command 注入两处（均与已有 hook 并存，带备份、幂等）：~/.claude/settings.json（Claude Code）与 ~/.codex/hooks.json（Codex）。Codex 的 hooks 默认未信任，首次启动 Codex 时在弹出的 Hook 审查中选「Trust all and continue」一次即生效
2. 任何终端里跑 claude / codex -> CLI 触发 hook -> command 里 exec /bin/sh 启动 helper（进程替换后 $PPID 即 CLI pid；agent 标记经实参传入，claude/codex 一视同仁无特判）
3. helper 只做一件事：无脑 append 一行 JSON 到 ~/.local/state/agents-explorer/events/<session_id>.jsonl（每会话一个 append-only 文件），行内含 ts + CLI pid + agent + 来源 env 快照，payload 原样透传
4. 扩展 EventStore fs.watch 该目录 -> 纯函数 reduce（通知收窄 / 子任务终态守卫 / backgroundActive）+ 派生（transcript/rollout 提取 / shellPid）-> 判定层映射五态 -> TreeView 刷新。各家 CLI 的 vendor 事件名在解析边界经 descriptor eventMap 翻译成扩展自有的规范事件（canonical），状态机/判定层只认规范事件；差异全部收敛在 src/agents/ 的 descriptor（事件映射、安装目标、transcript 解析、历史扫描源、resume 命令）--新增智能体 = 加一个 descriptor 文件 + 注册两行，其余模块注册表驱动

为什么是文件不是 server：事件流放在机器级固定目录（不是扩展的 globalStorage —— 那是 per-实例的），同一台机器上的多个 VS Code 窗口消费同一份真源、天然收敛一致；文件系统跨窗口/跨进程，没有 HTTP 端口的多实例冲突。hook 任何失败一律静默 exit 0，绝不阻塞 CLI。

会话消失：只认存活/确证信号，不做时间推测——hook 报 SessionEnd，或进程确证已退出（且结果已读）。进程还在就一直展示。扩展全关期间 hook 照写，下次启动重放恢复；事件文件超 7 天轮转（活进程豁免）。

开发 / 调试

npm install
npm run compile     # 或 F5 自动 watch 编译
npm test            # tsc + 全部 headless 测试(hook E2E / 单元 / hook 安装 / 桥 / waiting 通知)

按 F5 启动扩展开发宿主 → 活动栏「智能体资源管理器」图标 →「活跃会话」/「历史会话」两视图 → 空态「新建终端」链接或命令面板新建。

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

验证

不用真跑 claude：往事件目录丢一个 <sid>.jsonl，列表即刻出现一行：

# 机器级固定路径，mac 与 Linux 一致（可被 $XDG_STATE_HOME 覆盖）
DIR="${XDG_STATE_HOME:-$HOME/.local/state}/agents-explorer/events"
mkdir -p "$DIR"
# 变黄（等待）--行格式见 src/hook/eventFile.ts（与 hook 落盘同款）
# 毫秒时间戳用「秒*1000」：BSD(GNU) date 通用（GNU 专有的 %3N 在 macOS 会输出坏值）
printf '{"ts":%s,"pid":0,"agent":"claude","env":{"TERM_PROGRAM":"Apple_Terminal"},"payload":{"session_id":"demo-1","hook_event_name":"PermissionRequest","cwd":"/Users/demo/project"}}\n' "$(( $(date +%s) * 1000 ))" > "$DIR/demo-1.jsonl"
# 追加一行 hook_event_name 为 Stop 的事件行 -> 变绿；删掉文件 -> 行消失

cwd/entryCwd 在 /tmp（含 /private/tmp）下的会话会被当作后台测试任务全局过滤，不进列表

批量造数（五态 + 多来源 + 多文件夹）用 node scripts/seed-sessions.mjs seed，另有 waiting/end/clear 子命令

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

事件->五态映射

规范事件（canonical，src/hook/canonicalEvents.ts）-> 五态的完整映射与守卫见 docs/state-machine.md「五态映射」。vendor 事件名（Claude/Codex 各家）在 agent descriptor 的 eventMap 里翻译成规范事件；未收录的归一 unknown（不改状态），扩展升级无需改 helper。