CLI-Agent-Manager：面向 Vibe Coding 的多 Agent 统一管理面板

CLI-Agent-Manager (AgentBoard)：为"氛围编程"而生的多 Agent 并行工作台

在可预见的未来，软件工程师将"分两班倒"：人类负责创造性、高层次的系统设计与产品决策，AI Agent 则作为勤勉的"数字员工"，承担起代码实现、测试、文档编写与研究分析等大量消耗性工作。

这句预测正加速成为现实。随着大模型能力的跃升，"氛围编程（Vibe-Driven Development）"或"意图驱动编程"不再是遥远的概念。我们越来越多地将模糊的想法（Vibe）交给 AI Agent，让它在命令行（CLI）中长时间运行，自主探索、实现、迭代。一个人同时"监工"多个并行的 AI Agent，已是许多开发者的日常。

但这种新的工作流也带来了新的"甜蜜烦恼"。

"氛围编程"时代的幸福烦恼

当我们习惯了把一个个长程任务（Long-running Task）------比如"帮我重构这个旧模块并补全测试"或"调研下 X 技术的最新进展并写个报告"------抛给 Claude Code、Aider、Cursor 或自定义的 GPT 脚本后，很快会发现自己的工作台陷入了一种新的混乱：

状态海洋，孤岛求生：终端窗口越开越多，每个窗口里都是一个正在埋头苦干的 Agent。哪个完成了？哪个卡住了需要我介入？哪个又因为 API key 限制而悄然挂掉？我们成了在信息孤岛间疲于奔命的"微操大师"，频繁的上下文切换不断打断着宝贵的心流。
配置各异，管理分散：不同的 Agent 有不同的配置文件、Skills 目录、MCP（Meta-level Control Policy）设定。想给 Aider 换个模型，或者给 Claude Code 加个新技能，都得找到对应的配置文件手动修改，缺乏统一的管理视图。
关键时刻，呼叫无门：最令人沮丧的是，当 Agent 需要我们进行关键决策（例如，批准一个高风险的文件修改）时，它只能在自己的终端窗口里默默等待。如果我们恰好没看到那条提示，整个任务就会被无限期阻塞，浪费了大量时间与计算资源。

我们需要一个"工头"，一个统一的管理面板，它能轻量、无侵入地接入我们现有的 CLI Agent 工作流，将这些并行的、长程的任务状态汇聚一处，并在关键节点主动提醒我们。

这，就是 CLI-Agent-Manager（我们称之为 AgentBoard）诞生的初衷。

AgentBoard：你的 CLI Agent 统一仪表盘

AgentBoard 的核心定位非常明确：一个轻量级、旁路聚合、面向多 Agent 协作的桌面端仪表盘与提醒中心。

它的设计哲学是"集中，但非侵入"。

集中（Centralize） ：将所有通过 AgentBoard 监视的 CLI Agent 会话（Session）汇集到一个统一的 UI 中。你可以一目了然地看到每个任务的实时状态（运行中、待审批、已完成、空闲等）、运行时长、最新进展摘要。
非侵入（Non-intrusive） ：你不需要改变原来使用 claude-code、aider 等工具的任何习惯。AgentBoard 通过在 CLI 工具的关键生命周期节点（如任务开始、结束、用户输入、请求权限）旁路（Sidecar） 挂载一个轻量级的 Hook 脚本，将事件上报给本地运行的 AgentBoard 服务。你的终端依然是你的主战场，AgentBoard 则像一个尽职的助理，默默记录和呈现。

它不是要取代你心爱的 CLI 工具，而是要成为它们的"僚机"，让"氛围编程"变得更从容、更高效。

架构设计：旁路 Hook 与最小侵入

为了实现"非侵入"的设计目标，AgentBoard 的架构选择了一条优雅而高效的路径：事件驱动、旁路聚合。整个系统分为终端、Hook 层、AgentBoard 应用（主进程与渲染进程）三大块，数据流清晰而解耦。

上图是由 Mermaid 生成的架构图，它清晰地展示了从用户在终端与 CLI Agent 交互，到事件通过 Hook 上报，最终在 AgentBoard UI 中呈现的完整数据流。

数据流动之旅

终端（保持原样） ：开发者像往常一样在终端中与 claude-code 等 CLI Agent 交互。无论是启动一个新项目，还是在现有项目中继续对话，一切操作都保持不变。
Hook 层（最小接入点） ：这是 AgentBoard 实现魔法的关键。
1. 对于像 Claude Code 这样支持 Hook 机制的工具，AgentBoard 提供了一键安装功能，能自动在配置文件中注入 agent-board-hook.sh 脚本。
2. 对于其他 CLI 工具，开发者可以手动或通过包装脚本，在适当的时机（如命令执行前后）调用通用的 agent-board-report.sh 脚本。
3. 这些脚本的职责只有一个：将当前事件（如 SessionStart, UserPromptSubmit）和上下文信息（如 Session ID, 当前工作目录, CLI 类型）打包成一个 JSON HookPayload，通过 HTTP POST 请求发送给本地的 AgentBoard 服务。
AgentBoard 主进程（后台中枢） ：这是一个常驻后台的 Electron 主进程，负责处理所有核心逻辑。
1. HTTP Server : 运行在本地 27420 端口，是所有 Hook 上报的唯一入口。
2. Session Manager: 系统的"大脑"，负责维护每个会话的生命周期状态机。当收到新事件时，它会更新会话状态、记录心跳、处理新旧会G话的自动关闭与恢复。
3. Database (SQLite) : 所有会话和事件的详细信息都被持久化到本地的 SQLite 数据库中，保证了数据的完整性和可追溯性。
4. Notification Manager : 当状态机流转到需要用户关注的节点时（如 PendingApproval），它会调用系统通知，确保你不会错过关键信息。
5. IPC Handlers: 作为主进程与渲染进程之间的桥梁，将后台的数据与状态安全地暴露给前端 UI。
AgentBoard 渲染进程（可视化前端） ：你所看到的仪表盘界面，由 React 和 Tailwind 构建。
1. 它通过 IPC 从主进程获取所有会话数据，并以直观的卡片形式（SessionCard）呈现在 SessionGrid 中。
2. 用户可以在这里进行筛选、查看会话详情、管理 CLI 工具配置，甚至通过 UI 操作触发后台的 Hook 安装或卸载。

这种架构的最大优势在于解耦。CLI Agent 本身完全不知道 AgentBoard 的存在，它只是在执行自己的逻辑。Hook 的引入如同一位旁观的"书记员"，只记录不干预，确保了 AgentBoard 的接入成本极低，且不会对现有工作流产生任何副作用。

状态机：定义 Agent 的生命周期

为了精确追踪每个并行任务的进展，AgentBoard 为每个会话（Session）都内置了一个健壮的状态机。这个状态机定义了从一个任务诞生到最终归档的完整生命周期。

上图是会话生命周期的状态机图。它详细描述了 Idle、PendingApproval、Running、Completed、Closed、Error 等核心状态，以及触发它们之间转换的关键事件。

我们来解读一下几个核心状态和转换逻辑：

Idle (空闲) ：这是会话的"静止"状态。当一个任务长时间（默认超过 3 小时）没有任何活动，或者被手动暂停时，就会进入此状态。它像一个随时待命的士兵，等待新的指令。当收到用户的下一次提示（UserPromptSubmit）时，它会立刻"苏醒"，切换到 Running 状态。
Running (运行中) ：表示 Agent 正在积极地思考或执行任务。这是最常见的工作状态。
PendingApproval (待审批) ：这是 AgentBoard 最具价值的状态之一。当 CLI Agent 执行到一个需要用户确认的步骤时（例如，它想修改一个敏感文件，或者执行一个高成本操作），Hook 会上报一个 PermissionRequest 事件。此时，会话状态切换为 PendingApproval，AgentBoard 会立刻弹出系统通知，提醒你进行决策。你不再需要时刻紧盯终端，等待那稍纵即逝的 [y/N] 提示。
Completed (已完成) ：当 Agent 明确表示任务完成时（例如，Aider 的 /done 命令），会话会进入此状态。这标志着一个工作单元的成功闭环。
Closed (已关闭) ：表示这个会话在当前 CLI 进程中已经结束。这通常发生在 CLI 工具退出，或者你手动在 AgentBoard 中归档一个会话时。值得一提的是，AgentBoard 的会话是可恢复的。即使一个会话被标记为 Closed，如果后续同一个 Session ID 又上报了新事件，它会自动"复活"，回到 Running 状态，确保了对话历史的连续性。
Error (错误) ：当发生异常，或者心跳长时间超时未能恢复时，会话会进入此状态，并以醒目的方式在 UI 上标示出来，等待你介入处理。

这个精巧的状态机，结合心跳检测机制 （自动识别并"冷却"僵尸会话）与智能会话管理（在同一项目下开启新任务时，自动关闭旧的活跃任务），构成了 AgentBoard 可靠、智能的追踪能力。

界面速览：一眼洞悉全局

理论说了很多，让我们通过几张 UI 截图，直观感受 AgentBoard 如何将复杂的状态管理变得简单优雅。

1. 工具接入与配置中心

这是 AgentBoard 的 Config 页面。左侧是主导航，中间是所有可识别的 CLI 工具列表，清晰地标注了"已接入"或"未接入"。右侧则展示了当前选中工具（这里是 Claude Code）的详细信息，包括：

安装与接入状态：让你明确知道此工具是否可用，以及 AgentBoard 是否已成功 Hook。
配置路径管理：你可以直接在这里看到甚至修改工具的配置文件和 Skills 目录路径，省去了在文件系统中翻找的麻烦。
一键式操作：通过"卸载接入"或"接入"按钮，可以轻松地启用或禁用 AgentBoard 对该工具的监控。

2. 会话仪表盘：状态卡片墙

这是你每天打交道最多的地方------Sessions 仪表盘。

全局统计：顶部是你所有会话的概览，例如"全部 17，活跃 1，已完成 16"，让你对当前的工作负载有一个宏观认知。
状态卡片：每个卡片都代表一个独立的会话。你可以清晰地看到：
- 归属：它属于哪个项目 (agent-board)，由哪个 CLI (claude-code) 驱动，以及它的唯一 Session ID。
- 状态：醒目的彩色标签（如"待审批"、"已完成"、"空闲"）让你瞬间抓住重点。
- 摘要：卡片上会显示最新的对话内容或任务描述，让你快速回忆起这个任务是关于什么的。
- 时间：显示任务已运行时长或最后活动时间。

这张"卡片墙"就像一个作战指挥室的态势图，所有 Agent 的动态尽在掌握。

3. 审批提醒与快速入口

当一个任务进入 PendingApproval 状态时，你会在系统通知中心看到类似这样的提醒。点击它可以唤出这个上下文菜单，提供快捷操作：

[需审批] Claude-code：明确告诉你哪个任务需要你。
打开主面板：一键跳转到 AgentBoard 的详细界面，查看完整上下文并作出决策。
退出：如果这是一个误报或不重要的请求，可以快速忽略。

这个小小的菜单，打通了从"被动等待"到"主动决策"的最后一公里。

接入实践：为你的 CLI Agent 穿上"数据背心"

AgentBoard 的魅力在于其极低的接入成本。无论你的 CLI 工具是否原生支持 Hook，总有办法为它"穿上"一件上报数据的"背心"。

上报数据格式：`HookPayload`

所有上报都遵循一个统一的 JSON 格式------HookPayload。它就像一张标准化的"事件报告单"。

perl 复制代码

{
  "hook_event_name": "UserPromptSubmit",
  "session_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "cwd": "/Users/zhifeng.wei/projects/my-awesome-app",
  "cli_type": "claude-code",
  "task_description": "Refactor the authentication module to use JWT.",
  "git_branch": "feature/auth-refactor",
  "git_repo_url": "git@github.com:EricOo0/my-awesome-app.git"
}

hook_event_name: 事件名称，对应状态机中的转换触发器（SessionStart, Stop, PermissionRequest 等）。
session_id: 任务的唯一标识符，需要你在多次上报中保持一致。
cwd, cli_type, task_description: 提供了丰富的上下文信息，用于在 UI 上展示和归类。

包装脚本示例：一个简单的 Shell 实践

假设你有一个自定义的 Python 脚本 my_agent.py，它本身不支持 Hook。我们可以用一个简单的 Shell 函数来包装它，实现自动上报。

将以下代码添加到你的 .zshrc 或 .bash_profile 文件中：

bash 复制代码

# 包装你的自定义 Agent
run_my_agent() {
    # 1. 优先使用已有的 Session ID，否则创建一个新的
    SESSION_ID=${AGENT_SESSION_ID:-$(uuidgen)}
    export AGENT_SESSION_ID=$SESSION_ID

    # 2. 上报任务开始事件
    agent-board-report.sh SessionStart $SESSION_ID $(pwd) "my-agent" "$*"

    # 3. 执行原始命令
    python my_agent.py "$@"

    # 4. 上报任务结束事件
    agent-board-report.sh Stop $SESSION_ID $(pwd) "my-agent"
}

# 你甚至可以创建一个别名来覆盖原命令
# alias my_agent.py='run_my_agent'

在这个例子中：

我们用 uuidgen 生成一个唯一的 SESSION_ID 并导出为环境变量，以便多次调用时复用。
在执行真正的 my_agent.py 之前和之后，我们分别调用了 agent-board-report.sh 来上报 SessionStart 和 Stop 事件。
"$*" 会将所有传递给 run_my_agent 的参数原封不动地传给 my_agent.py，保证了原有功能的完整性。

通过这种方式，只需几行 Shell 代码，任何 CLI 工具都可以轻松接入 AgentBoard 的监控体系，而无需修改其源代码。这就是"最小侵入"原则的实践。

立刻开始你的"氛围编程"新体验

AgentBoard 是一个开源项目，目前只完成初步功能，欢迎每一位对"人机协同"新范式充满热情的开发者帮忙完善这个工具以及提出宝贵意见。

GitHub 仓库 : github.com/EricOo0/CLI...

我们建议你从接入一个你最常用的 CLI 工具开始，例如 Claude Code，它拥有良好的 Hook 支持，可以让你在几分钟内就体验到 AgentBoard 带来的效率提升。然后，再逐步将你工作流中的其他 CLI 工具也纳入进来。

告别那个在终端窗口间手忙脚乱的自己吧。让 AgentBoard 成为你的"数字工头"，让你重新专注于创造性的工作，真正享受"氛围编程"带来的心流与乐趣。