Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
运行中 Agent 视图(Agents → Running)— 需求设计稿 v3
状态:已定稿(需求层面)。两轮评审收敛(opus 4.8:feasible-with-changes → minor-fixes-then-done);§8 全部分叉已拍板。可据此进入实现规划(接口签名/落点)。 已锁决策:A4(Agents 页内
Definitions | Running子 Tab,A2 顶层 Activity 作兜底)· B1 轮询 · C1 只读 · D2 含 idle · E1 覆盖 IM · F1 session 中心 · G1 含 OpenCode · H1 orphan 单独成行 · I1 不可达明确态 · J1 默认进 Definitions · K2 Running badge 仅计 active。 范围:需求 / 产品层面。不含实现代码;定义"要什么、长什么样、数据从哪来、有哪些待拍板分叉"。
1. 背景与问题
avibe 现在能看到 agent 定义(Workbench → Agents)、定时与触发 Harness(Tasks/Watches/Webhooks/Runs 历史),但看不到"此刻正在运行的 Agent":
- 我现在有哪些 Claude Code / Codex / OpenCode 进程或会话在跑?
- 每个挂在哪个 session 上?这个 session 是 slack / discord / web / 定时触发哪种来源?挂在哪个 channel/thread/项目、哪个 workdir?
- 想点进去看它、跳到对应会话、(可选)停它怎么办?
数据基本都已存在,但分散在三层且跨进程,从未被聚合成一个"运行时视图"。
2. 目标 / 非目标
目标
- 一眼看清"当前正在运行/活跃"的所有 agent 实例,覆盖全部三个活后端:claude / codex / opencode(含未来后端,靠统一抽象自动纳入)。
- 每行能看到关键上下文:来源平台、触发源、所属 session、scope、workdir、模型、运行时长、状态。
- 每行提供可点击链接/操作:跳 Chat session、查看关联 Harness run、查看 scope、(可选)停止/驱逐。
- 嵌入现有 Web IA,移动端可用,且在 controller 不可达时优雅降级(不报 500、不假报"0 在跑")。
非目标(本期不做):历史分析/图表(Runs 已有);改 eviction/reaper 回收逻辑(只读快照);token/费用统计。
3. 信息架构:放哪?(§8-A 待拍板,评审倾向已变)
现有结构:Workbench CapabilityTabs:Agents | Skills | Harness | Vaults;HarnessPage 内部 Tab:Tasks | Watches | Webhooks | Runs。
已定(A4):在 AgentsPage 内新增子 Tab Definitions | Running。心智模型是"定义 vs 运行实例"(类比 镜像/容器、Deployment/Pod):Definitions = 现有 agent 配置(claude/codex/opencode 后端、系统提示、模型),Running = 此刻活着的 session/进程,通过 agent_sessions.agent_backend 关联回所用后端。
实现注意:
- AgentsPage 现仅用顶层
CapabilityTabs+WorkbenchPageHeader,没有内部子 Tab 机制,需照HarnessPage的TabKey/TAB_ORDER/counts/refresh/icon 模式新加一层子 Tab。 - 无需任何路由改动:
/agents仍是单一 route,子 Tab 纯属组件内部useState(与HarnessPage.tsx:67-90的TabKey/TAB_ORDER完全同构);把现有 AgentsPage 主体抽成<DefinitionsTab>,新增<RunningTab>,外面套 HarnessPage 式 tab row 即可。 Running行是 session 中心(非"某定义的严格实例");可按 backend/agent 分组与筛选,但不强行把每行绑回某条定义。- 评审曾倾向顶层
ActivityTab(理由:运行视图还含从不进 harness 的交互式会话,语义更宽)。该理由不否决 A4(一切在跑的都是"agent 在跑",放 Agents 自洽),故 A4 成立;仅当深评审发现子 Tab 机制或定义↔实例映射出现 blocker 时回退 A2 顶层 Activity Tab。
4. 实体模型:一行 = 一个"运行中单元"
行的粒度本身是一个待拍板分叉(§8-F):session 中心 vs 进程/transport 中心。下表按"session 中心、pid 作为属性"的推荐口径给出字段:
| 字段 | 含义 | 来源与注意 |
|---|---|---|
| backend | claude / codex / opencode | 内存 registry。opencode 无自有子进程(HTTP server + poll loop),无 pid |
| state | active(在途轮次) / idle(已连接空转) / orphan(脱钩进程) |
每后端 liveness 源不同,须各自明确定义(§7) |
| busy_for / idle_for | 当前轮次时长 / 空转时长 | 必须在 controller 内算成"已过秒数"再传;monotonic() 不可跨进程 |
| platform | slack / discord / telegram / feishu / wechat / avibe(web) | scopes.platform;"cron"不是 platform |
| trigger source | human / scheduled / watch / webhook / callback | harness 的 source_kind(与 platform 正交,单列)。兜底:无可靠关联 Harness run 时默认 human;scheduled/watch/webhook/callback 仅在能可靠关联到 run 时显示 |
| scope | channel / thread / dm / project + 显示名 | scopes.scope_type + display_name;cron/web 可能 scope_id=NULL,则平台回退用 anchor 前缀 |
| session | base_session_id + 标题 | composite_key 拆分(注意 subagent key 为 {platform}_{thread}:{agent}:{cwd} 三段,须按最后一段绝对路径切分)+ agent_sessions.title |
| workdir | 工作目录 | composite_key / agent_sessions.workdir(展示可缩略,见安全 §7) |
| model | 当前模型(可选/best-effort) | claude client._vibe_current_model 可能为 None;不保证有值 |
| pid | OS 进程号 + 墙钟运行时长(可选) | claude:reaper ClaudeOwnedProcess,仅 owner=="session"(排除 auth 进程);codex:一个 pid 对应一个 cwd,多 session 共享;opencode:无 pid |
| links | 见 §5 | 组合 |
"活"的口径(关键):以内存 registry + 实际进程为准(此刻真在跑)。agent_sessions.agent_status 只对 workbench/web session 写入,IM session 不写,故 DB 不能作可靠兜底——IM 在跑的真相只能来自 controller 内存快照。
5. 关联上下文 & 链接(每行可点)
- → 打开 Chat:跳
/chat/:sessionId。链接可用性规则(v4 修订):只要有持久化session_id就提供 Open Chat——IM(slack/discord/…)session 同样可用,与 Inbox/侧栏既有的/chat/<session_id>导航一致。无session_id(如 orphan)时直接不渲染链接,不显示 "unavailable" 占位。 - → 查看 Scope:IM → channel/thread;web → 项目。
- → 关联 Harness:若来自某 task/watch(
agent_runs.definition_id/source_kind),链到定义与该次 run。 - → 进程详情:pid、墙钟启动时间、native_session_id、是否 orphan。
- 操作(可选,§8-C,C1 默认不做):Stop 轮次(复用
POST /internal/cancel/{session_id}即internal_client.cancel_dispatch)/ Evict 空闲 session / Reveal workdir。
6. 交互与状态
- 实时刷新:轮询 3–5s(B1)。计数 badge 只数 active(在途轮次,K2),idle 不计;socket 不可达时 badge 显示 "—" 而非 "0"。
- 排序/筛选(v4 修订:稳定排序):先按 state(active→idle→orphan),band 内按稳定标识排序(非 elapsed),避免时长每轮跳动导致行乱跳;可按 backend / platform / source / state 筛选。
- 状态机:加载态 / 空态("当前没有 Agent 在运行")/ controller 不可达态("运行时不可达",区别于空态) / orphan 高亮(只提示不自动回收)。
- 移动端:行卡片化,
backend·platform·state·busy_for优先,其余折叠。
7. 数据来源 & 跨进程取数(佐证可行性 + 实现骨架)
架构前提(第 1 轮评审硬伤修正):UI 服务(vibe/ui_server.py,FastAPI)与 controller 是两个进程;活 registry 都在 controller 内存,UI 的 /api/... 读不到。唯一跨进程通道是 controller 的本地 Unix socket(core/internal_server.py,已有 /internal/turn-state、/internal/cancel 等,0o600 仅本机)。
取数链路(实现骨架):
- controller 侧新增
GET /internal/running-agents(与 controller 同 asyncio loop,直接读内存;在此处完成 DB join 与时长计算后再返回):- claude:扫
session_handler.claude_sessions.values(),读_vibe_runtime_base_session_id/_vibe_native_session_id/get_claude_client_pid(client);注意active_sessions、session_last_activity以composite_key为键(非 anchor),须先经 client 的_vibe_runtime_session_key/_vibe_runtime_base_session_id把 composite_key 解析到 base_session_id 再做 DB join(session_anchor=base_session_id);与 reaperclaude_processes.json对账标 orphan(仅owner=="session",排除 auth 进程)。 - codex:
_session_mgr.all_base_sessions()遍历 →get_cwd(bid)→get_thread_id(bid)、_turn_registry.get_active_turn(bid);pid 经_transports[cwd]取。CodexTransport目前只有is_alive/is_initialized公开,_process私有——需新增公开 pid 访问器;pid 是 cwd 级、多对一(多 session 共享)。 - opencode:状态来自
OpenCodeAgent.runtime_turn_keys()与_active_requests任务(HTTP server + poll,无子进程 pid)。 - 跨后端在途轮次:
core/session_turns.py的in_flight(键为 workbenchsession_idUUID)。 - 显示元数据 join:SQLite
agent_sessions(backend / workdir / title / scope_id,按session_anchor=base_session_id关联)+scopes(platform / scope_type / display_name)。
- claude:扫
vibe/internal_client.py新增list_running_agents(),捕获InternalServerUnavailable。vibe/ui_server.py新增GET /api/running-agents薄代理(沿用现有 AuthGuard 鉴权;controller 不可达时返回明确的 unreachable 而非 500)。- UI 侧(已定 A4):在
AgentsPage.tsx内照HarnessPage.tsx:67的TabKey/TAB_ORDER/useState模式新增Definitions | Running子 Tab——把现有主体抽成<DefinitionsTab>、新增<RunningTab>,无路由改动。 - CLI 侧可加
vibe ps复用同一/internal/running-agents。
registry 路径修正:{config.paths.get_runtime_dir()}/claude_processes.json(解析到 ~/.avibe/ 下),非 ~/.vibe-remote/。
安全:pid / 绝对 workdir / native_session_id 经浏览器 API 暴露需明确沿用 /api 现有鉴权;workdir 是否全量展示见 §8。
8. 偏好分叉 — 已决策(2026-06-24)
全部已拍板:A4(兜底 A2)· B1 · C1 · D2 · E1 · F1 · G1 · H1 · I1 · J1 · K2。下列保留选项与理由备查。
8-A. 视图落点(IA)
- A1:
Harness → Live子 Tab(改动最小)。 - A2(评审倾向):新增顶层 Capability Tab
Activity(语义最贴切:覆盖交互式 + 自动化全部来源)。 - A3:放进
Admin → Dashboard运维小部件。 - A4:
Agents页内Definitions | Running两子 Tab。
8-B. 刷新机制
- B1:轮询 3–5s(简单够用)。
- B2:SSE 实时推送(更实时、成本更高)。
8-C. 操作能力(v6 修订:统一 End)
C1:纯只读→C2:仅 Stop→ C3(已采纳):每行统一 "End",按 state 分派后端拆除:- active → 中断在途轮次 + 断开 client(claude
client.interrupt()+cleanup_session;codexturn/interrupt+清 thread/turn;opencode abort+cancel task)。文案 "Stop"。 - idle → 断开释放 client/transport。文案 "Disconnect"(无损可重建,免确认)。
- orphan → SIGTERM→SIGKILL 泄漏进程(先复用 reaper 校验:owner==session + 存活 + 启动时间匹配,绝不杀非 avibe-owned/复用 pid)。文案 "Kill process"。
- active → 中断在途轮次 + 断开 client(claude
- 链路:
POST /api/running-agents/end→/internal/running-agents/end(在事件循环上跑,因要 await 后端中断 + 改 loop 拥有的 registry,不能 to_thread)→end_running_agent(controller, target)分派。 - 破坏性二次确认:active/orphan 首点 arm(按钮变 "确认",3s 自动解除),再点执行;idle 立即。
- 无自杀护栏(产品决策):可终止当前会话 / avibe 自身;误杀手动重启。
8-D. "运行中"纳入范围
- D1:只显示真正持有活进程/在途轮次的实例。
- D2:也显示"已连接但空闲(idle)"的 session,便于了解资源占用。
8-E. IM session 可见性(评审新增)
IM(slack/discord…)的 agent_status 不写 DB,要显示其"在跑"必须完全依赖 controller 内存快照(实现更重)。
- E1:完整覆盖 IM 在跑 session(实现更重,但满足 Goal 1)。
- E2:暂不覆盖 IM(更轻,但与 Goal 1 矛盾)。
8-F. 行粒度(评审新增,核心建模分叉)
Codex 一个 transport(pid)对应一个 cwd、服务多 session。
- F1(推荐):session 中心——一行一个活 session,pid 作属性;多 session 共享同一 codex pid 时各自成行并注明。
- F2:进程/transport 中心——一行一个 OS 进程/transport,pid 维度聚合。
8-G. OpenCode 是否纳入 v1(评审新增)
OpenCode 已是一等活后端(进程模型不同、无 pid)。
- G1(推荐):v1 纳入,pid 列对 opencode 留空。
- G2:v1 显式延后,仅 claude/codex(须在 Goal 1 注明缺口)。
8-H. orphan 进程展示策略(已定 H1 + v4 存活校验修订)
- H1(已定):脱钩进程单独成行标 orphan。
- v4 关键修订:orphan 必须做存活+身份校验——只展示 pid 当前确实存活且启动时间与注册表
started_at匹配(±1s,防 pid 复用)的进程。原实现只读claude_processes.json(累积大量历史死 pid),会把早已退出的死 pid 当 orphan 刷屏;现复用 reaper 的_process_start_time过滤死/复用 pid。修订后多数时候 orphan 为 0,仅真有存活泄漏时出现。
8-I. controller 不可达时的 UX(评审新增)
- I1:显示"运行时不可达"明确态(推荐)。
- I2:显示上次已知 + 过期横幅。
- I3:显示空。
8-J. 子 Tab 默认落地(已定 J1;后续补充跨次记忆)
首次进入(全新浏览器 / 存储被清空 / 存储不可用)点 /agents 默认进
Definitions(保留现有肌肉记忆);Running 为并列项。
后续补充:J1 只定义"首次默认",不再定义"每次重置"。之后再进 /agents
(含侧边栏点击)会恢复上次离开时所在的子 Tab;停在 Running 时,其内部
活跃/含历史 视图选择也一并恢复(详见
agents-run-graph-and-session-visibility.md 的 Filters 段与
ui/src/lib/agentsViewMemory.ts)。记忆是本地浏览器级的 best-effort:
私密模式或存储被拦截时静默回落到首次默认。
带明确意图的入口(如 Chat Agent 选择器的"新建 Agent"、Harness 详情的
"Open in Agents")用 /agents?tab=definitions 指定落地 Tab,优先于记忆——
它是目的地而不是用户的选择,因此不写回记忆;只有用户真的点 Tab 才会改变
下次裸进 /agents 的落点。该参数消失(例如从带参 URL 再点侧边栏 Agents,
路由只改 URL 不重挂组件)即视为回到裸导航,重新按记忆落地。
8-K. Running 子 Tab 计数 badge 口径(已定 K2)
Running 子 Tab 的 badge 仅计 active(在途轮次);idle 实例仍在列表中可见但不计入 badge。须与 §6 口径统一:列表含 idle(D2),但所有"在跑计数"badge 一律只数 active。
9. 验收标准(草案)
- 有真实运行的 claude/codex/opencode 时,Tab 内列出对应行,platform/source/session/workdir/pid(如有)正确。
- 点击链接正确跳 Chat / Harness run / scope。
- 进程结束后该行在一个刷新周期内消失。只读观察口径:stuck-active 被既有 eviction 驱逐后,其行随之消失——视图只观察既有驱逐结果,不自行驱逐(C1)。 3b. 多个 codex session 共享同一 app-server pid 时(F1),各 session 各自成行、显示相同 pid 并标"共享进程"。 3c. controller 重启后"仅 reaper registry 有进程、内存 session 丢失"时,按 H1 显示为 orphan 行,其 session/scope/Chat 链接为空或 best-effort;badge 仍只统计 active。
- controller 不可达时显示明确"运行时不可达"态、不报 500、badge 显示 "—"。
- 移动端可读可用;空态/加载态/出错态完整。
附:评审日志
- Round 1(opus 4.8 + codex-expert*):双方均 feasible-with-changes。已折入:两进程取数链路、registry 路径、platform/source 拆分、monotonic→时长、codex pid 语义、agent_status 不可靠、OpenCode 纳入、安全与降级。新增分叉 8-E~8-I。
- Round 2(opus 4.8):minor-fixes-then-done,A4 可行无需回退。已折入:composite_key 与 base_session_id 解析、CodexTransport 需公开 pid 访问器、opencode 状态源(runtime_turn_keys/_active_requests,无 pid)、子 Tab 无需路由改动、codex 共享 pid 验收项。新增微分叉 8-J/8-K(已定 J1/K2)。
- Round 3a(opus 4.8):minor-fixes-then-done,无新分叉。修:§7 step4 去除 A1/A2 死代码改为 A4 目标、
/internal/cancel/{session_id}路径精确化。 - Round 3b(codex 后端,小上下文):minor-fixes-then-done,NEW_HUMAN_FORKS=none。修:§5 链接可用性规则(失效链接置灰/隐藏)、§4 trigger source 兜底(无关联默认 human)、§9 stuck-active 改为只读观察口径、controller 重启残留进程按 orphan 显示。
- ✅ 收敛定稿:codex + opus 双评审一致 minor-fixes-then-done / 无遗留 blocker / 无新人工分叉,全部修正已折入。需求设计完成。
- * codex 评审取数过程:
codex-expert(OpenAI Codex) 本区域不可用;用户配置的 codex 后端偶发 403 直连 api.openai.com(HKG),且读多文件的大型评审会触发 remote-compact,被中转上游以403 This account only allows Codex official clients拒绝。最终改用「不读文件、doc 正文内联」的小上下文单回合评审成功跑通。附带发现:上述 403(偶发直连 OpenAI + compact 被禁)很可能也是用户 codex 后端反复失败/"授权失效"的根因,建议单列排查model_provider/base_url路由与 compact 行为。
- * codex 评审取数过程: