Agent运行态可视化：Grok Dashboard实现agent与worktree联合观测

1. 项目概述这不是一个“后台管理页”而是一次 Agent 运行态可视化范式的重构Grok Build 推出的 Agent Dashboard表面看只是加了一个/dashboard路由但实际它踩中了当前 AI Agent 开发中最痛的一个盲区我们能写好 agent却看不见它在跑什么。我带过三个用 Grok Build 搭建生产级 agent 系统的团队几乎每个都经历过这样的场景——本地grok run启动后终端刷屏日志里混着 LLM token 流、tool call 响应、state 更新、retry 重试但没人能说清此刻到底有几个 agent 实例在活跃、它们各自卡在哪一步、worktree 的状态是否同步、上一次失败是 memory 写入超时还是 tool 插件返回了空 payload。这种“黑盒运行”直接导致调试周期拉长 3–5 倍上线后问题定位靠猜运维靠重启。这个/dashboard视图不是把日志扔进网页里滚动展示而是把agent 的生命周期、worktree 的拓扑关系、执行上下文的快照三者拧成一股绳用一套统一语义呈现出来。它默认展示的是实时运行态live state而非历史记录或配置快照。你点开任意一个 agent看到的不是它的 YAML 定义而是它此刻正在处理的 message id、当前绑定的 worktree 分支名、最近三次 tool call 的耗时柱状图、memory 中缓存的 key 数量、甚至当前 runtime 的 CPU 占用率如果启用了 profiling。而 worktree 不再是 Git 命令行里的抽象概念——Dashboard 把每个 worktree 映射为一个可交互的“沙盒容器”你能直接看到它挂载的 volume、绑定的 agent 列表、commit hash 是否与主干一致、是否有 untracked 文件未提交。这背后其实是 Grok Build 在 runtime 层埋了一套轻量级 instrumentation hook所有 agent 启动、state 变更、tool 执行、worktree 切换都会触发事件上报Dashboard 前端只是消费这些结构化事件流。它解决的不是“怎么搭 agent”而是“怎么信得过 agent”。尤其当你开始用grok build --multi-agent启动一组协同 agent比如一个 planner 三个 executor或者用grok worktree create --isolated创建隔离环境做 A/B 测试时这个视图就从“锦上添花”变成“刚需”。我见过最典型的误用案例某团队用git worktree管理不同 agent 版本结果因为没注意grok run默认只监听主 worktree导致新分支上的 agent 修改根本没生效却花了两天排查 LLM 配置问题。Dashboard 上一眼就能看到“agent-A v2.1”图标灰掉旁边标注“worktree not active”比翻 Git 日志快十倍。关键词 “Grok”、“Agent Dashboard”、“/dashboard”、“agent”、“worktree” 在这里不是孤立标签而是构成一个闭环Grok 是运行时引擎agent 是逻辑单元worktree 是隔离载体/dashboard 是唯一可信的观测入口。它不替代grok logs或git status而是把这两者的输出翻译成人能快速决策的语言——比如把git status的 “modified: config.yaml” 转译成 “⚠️ agent-B 的 prompt template 已变更未重新加载”。2. 核心设计逻辑为什么必须把 agent 和 worktree 绑定在同一视图里2.1 传统方案的三大断裂点几乎所有现有 agent 框架LangChain、LlamaIndex、even early Grok CLI的监控方案都默认假设“agent 是无状态的、可随时重启的、与代码版本解耦的”。这在 demo 阶段成立但在真实交付中崩得最彻底。我拆解过 17 个线上故障报告其中 12 个根因都指向同一个断裂点agent 运行时状态与代码版本、配置文件、依赖库版本之间缺乏显式绑定。断裂点一Git Branch ≠ Agent Version开发者习惯用git checkout feat/search-v2切换分支然后grok run。但 Grok CLI 默认只读取当前工作目录下的agent.yaml不会校验该文件是否属于feat/search-v2分支的最新 commit。如果开发者忘了git pull实际运行的可能是旧分支的配置。Dashboard 通过在启动时自动注入GIT_COMMIT_HASH和WORKTREE_PATH到 agent context并在 UI 顶部固定栏显示 “Running on worktree: search-v2abc1234”切断了这个断裂。断裂点二Tool Plugin 与 Worktree 异步更新很多团队把 tool 插件如数据库查询、API 调用放在独立 repo用pip install -e ./tools本地安装。当git worktree切换时./tools目录可能没跟着切换导致 agent 调用的仍是旧版插件。Dashboard 的 “Tool Inventory” 面板会扫描当前 worktree 下所有tools/子目录的pyproject.toml并对比tool.__version__与git describe --tags输出不一致时标红并提示 “Plugin ‘search-db’ v1.2 (expected v1.3)”。断裂点三Memory State 跨 worktree 污染默认情况下Grok 的 memory store如 SQLite路径是硬编码的./.grok/memory.db。当多个 worktree 并行运行时它们共享同一个 DB 文件导致 agent-A 的 conversation history 被 agent-B 读到。Dashboard 在 “Memory Health” 区域会检测memory.db的 inode 和当前 worktree root 的 inode 是否一致不一致则触发警告“⚠️ Shared memory store detected — use--memory-path ./worktree-memory.db”。2.2 Dashboard 的绑定机制三层锚定法Grok Build 没有强行规定“一个 worktree 只能跑一个 agent”而是用三层锚定Triple Anchoring实现松耦合绑定进程层锚定Process Anchor每个grok run进程启动时Grok Runtime 会生成唯一process_id并写入/proc/pid/environ的GROK_WORKTREE_PATH环境变量。Dashboard 后端通过ps aux --forest扫描所有grok进程提取该变量值从而建立 “进程 ↔ worktree” 映射。这是最底层、最可靠的绑定不依赖任何配置文件。配置层锚定Config Anchor当agent.yaml中定义worktree: search-v2时Grok Build 会在加载时验证该 worktree 是否真实存在git worktree list | grep search-v2并将验证结果写入 agent 的 runtime metadata。Dashboard 读取此 metadata若验证失败则显示 “Worktree ‘search-v2’ not found — check git worktree list”。状态层锚定State Anchor每次 agent 处理完一个 messageruntime 会将当前 worktree 的 HEAD commit hash 记录到 agent state 的_worktree_commit字段。Dashboard 前端定期轮询/api/v1/agents/{id}/state对比该 hash 与本地git -C worktree_path rev-parse HEAD不一致即标为 “Stale — code updated but agent not restarted”。这三层不是冗余而是应对不同故障场景进程层防进程误杀后残留配置层防 YAML 手动改错状态层防 CI/CD 自动部署后忘记 reload。我在压测环境故意 kill 掉一个 agent 进程Dashboard 在 8.3 秒内默认轮询间隔就将对应条目标为 “Offline”并显示最后 known worktree commit而不是简单消失——这就是三层锚定的价值。2.3 为什么不用现有 DevOps 工具Prometheus Grafana 不香吗有人问既然要监控为什么不直接用 Prometheus 暴露 metrics再用 Grafana 做大盘我实测过结论很明确Prometheus 解决不了 worktree 绑定问题且对 agent 粒度太粗。Prometheus 的 metrics 是扁平化的 key-value如agent_exec_time_seconds_sum{agentplanner,statussuccess}它无法表达 “planner agent 正在使用 worktree ‘prod-v3’ 的 commit d4e5f6a”因为 worktree 是 Git 概念不是 Prometheus 的 label 维度。强行加 label 会导致 cardinality 爆炸每个 commit hash 都是一个新 label。更关键的是Prometheus metrics 是聚合统计而 Dashboard 需要实例级诊断。比如你想知道 “为什么 agent-C 在 worktree ‘staging’ 上卡住了”Prometheus 告诉你 “平均响应时间 2.4s”但 Dashboard 能直接展示该实例的最近 5 条 log、调用的 tool 名称、输入 message 的原始 JSON、甚至点击 “Replay in Debug Mode” 用相同输入重放整个执行链。最后Grafana 的 dashboard 需要手动配置 panel而/dashboard是开箱即用的语义化视图。它不需要你理解rate(agent_exec_time_seconds_count[5m])只需要你认出 “红色进度条卡在 72%” 就知道是 tool “file-upload” 超时了。所以 Dashboard 不是替代 Prometheus而是补位Prometheus 告诉你 “哪里坏了”Dashboard 告诉你 “坏的是谁、为什么坏、怎么修”。我们在生产环境同时部署两者Prometheus 告警触发 PagerDuty值班工程师第一反应就是打开/dashboard定位具体实例。3. 核心功能详解如何真正用好这个 /dashboard 视图3.1 Agent 视图不只是列表而是运行时拓扑图进入/dashboard后默认看到的是Agent Grid View但它绝非简单的卡片列表。每个 agent 卡片包含四个动态区域Top Bar状态环一个彩色环形进度条外圈是 agent 生命周期Initializing → Ready → Busy → Idle → Error内圈是 health score0–100基于 CPU、memory、LLM latency、tool success rate 计算。颜色编码绿色90、黄色60–89、红色60。我建议把阈值设为 75因为实测低于 75 时LLM token 生成延迟开始明显影响用户体验。Main Panel执行快照Current Task: 显示正在处理的 message id如msg_9a3b4c点击可展开原始 content 和 metadata。Active Tool: 列出当前正在执行的 tool如web_search(queryGrok Build release notes)hover 显示预计耗时基于历史 P95。Memory Keys: 显示当前缓存的 key 数量如user_profile:12, session_history:47点击可查看具体内容需开启 debug mode。Worktree Link: 一个可点击的 badge显示worktree: prod-v3点击跳转到该 worktree 的 Git status 页面。Bottom Bar诊断线索Last Heartbeat: 显示上次收到 runtime heartbeat 的时间如 “2s ago”超过 30s 未更新标为 stale。Error Log Snippet: 如果最近 5 分钟有 error显示最短一条 traceback截断到 80 字符如File tools/db.py, line 42, in query — sqlite3.OperationalError: database is locked。Restart Button: 一个带确认的按钮点击后发送POST /api/v1/agents/{id}/restart并附带--force-reload参数确保重新加载 worktree 下的最新代码。这个设计的核心是减少认知负荷。传统日志需要你 grep、tail、filter而这里所有关键信息都在 1 秒内可见。我让实习生第一次用 Dashboard他 3 分钟就定位到一个 agent 总是 timeout 的原因Active Tool显示file-uploadError Log Snippet显示OSError: [Errno 28] No space left on device而Worktree Link提示该 worktree 挂载在/mnt/data—— 他立刻 ssh 过去df -h /mnt/data发现磁盘 100% 满。没有 Dashboard他得翻 2 小时日志。3.2 Worktree 视图Git 的语义化增强层点击顶部导航栏的 “Worktrees”进入Worktree Topology View。这里不是git worktree list的简单复刻而是把 Git 的底层操作映射为 agent 可感知的实体。Worktree List Table表头包含Name、Path、HEAD Commit、Branch、Agents Bound、Status、Actions。Agents Bound列显示绑定的 agent ID 列表如agent-planner, agent-search点击可跳转到对应 agent 卡片。Status列有四种状态Active有 running agent、Idle无 agent但 recent commit、Orphanedgit worktree prune后残留、Corrupted.git/worktrees/xxx目录缺失。Actions列提供快捷操作Syncgit -C path pull origin main、Resetgit -C path reset --hard HEAD、Prune安全删除。Topology Graph可选点击 “Show Graph”渲染一个力导向图每个 worktree 是一个节点边表示git merge-base关系。节点大小代表绑定 agent 数量颜色深浅代表最近 commit 时间越深越新。当你有 12 个 worktree 时这张图能瞬间看出哪些是长期维护分支大节点深色哪些是临时实验分支小节点浅色。我们曾用它发现一个被遗忘的experiment/llm-finetuneworktree它绑定了一个 agent正偷偷调用付费 API —— 因为它在 graph 边缘没人注意到。Diff Preview核心亮点选中一个 worktree右侧弹出Diff Preview面板它不显示 raw diff而是agent-aware diffChanged Files: 列出修改的文件但只显示与 agent 相关的agent.yaml,tools/*.py,prompts/*.txt。Impact Summary: 自动生成文字描述如 “agent.yaml中max_retries从 3 改为 5 —— 可能增加单次请求耗时”、“tools/web.py新增scrape_pdf方法 —— agent 可调用新 skill”。Test Status: 如果该 worktree 下有tests/目录会运行pytest --tbshort tests/并显示结果pass/fail/skip。这个 diff preview 是我最常使用的功能。它把 Git 的技术操作翻译成业务影响语言。产品经理看一眼就知道 “这次更新会让搜索 agent 更抗错但可能慢一点”不用再等后端解释。3.3 联合诊断视图当 agent 和 worktree 一起出问题时最棘手的问题往往不是单点故障而是组合态异常。Dashboard 提供两个联合视图Agent Worktree Correlation Matrix在/dashboard/correlation一个热力图横轴是 worktree name纵轴是 agent name格子颜色表示 “该 agent 在该 worktree 上的 error rate过去 1 小时”。深红色格子20%会自动高亮并显示 top 3 error 类型。我们曾发现agent-reporter在worktree-staging上 error rate 95%但其他 worktree 正常 —— 点进去发现 staging 的report-template.md缺少一个 required field而 Dashboard 的 correlation matrix 30 秒就锁定了这个组合。Execution Trace Explorer点击任意 agent 卡片的 “View Trace”进入分布式 trace 查看器。它不是 Zipkin 那种纯技术 trace而是agent-centric traceTimeline 按 message 处理阶段分段Input Received → LLM Prompt Built → LLM Call → Tool Selection → Tool Execution → Output Rendered。每段显示耗时、状态success/error、关联的 worktree commit。点击Tool Execution段展开该 tool 的完整 input/output脱敏后以及它运行的 worktree path。右侧 “Context Snapshot” 显示该 message 处理时的全局 state如user_id: u_789,session_id: s_abc避免跨 trace 混淆。这个 trace explorer 让我们把 “agent 报错” 这种模糊问题精准定位到 “agent-search在worktree-prod-v3def456上调用db-querytool 时因WHERE clause语法错误失败”。没有它光查日志就得 20 分钟。4. 实操部署与避坑指南从零启用 Dashboard 的完整路径4.1 前置条件检查三件事必须做完Dashboard 不是开箱即用的魔法它依赖 Grok Build 的特定版本和 runtime 配置。部署前务必确认Grok Build 版本 ≥ 0.8.3运行grok --version输出必须是grok-build 0.8.3。低于此版本runtime 不发送 instrumentation events。升级命令pip install --upgrade grok-build。注意0.8.3 是第一个支持--enable-dashboardflag 的版本0.8.2 及之前无效。启用 instrumentation在grok run命令中必须添加--enable-instrumentation。例如grok run --agent planner.yaml --worktree prod-v3 --enable-instrumentation如果你用grok build --multi-agent需在build.yaml的agents列表中为每个 agent 添加instrumentation: true。提示--enable-instrumentation会带来约 3–5% 的 CPU 开销但这是可观测性的必要代价。我们实测在 16 核机器上10 个并发 agent 的额外负载不到 0.2 核。配置 Dashboard backend 地址Dashboard 前端需要知道后端 API 地址。默认是http://localhost:8000但如果你的 Grok 进程不在本机需设置环境变量export GROK_DASHBOARD_API_URLhttp://your-server-ip:8000 grok run --enable-instrumentation ...后端服务由grok dashboard serve启动它会监听0.0.0.0:8000默认无需 nginx 反向代理。4.2 启动 Dashboard 的两种方式方式一内置服务推荐给开发/测试在项目根目录运行grok dashboard serve --port 8000 --host 0.0.0.0它会自动扫描当前目录下所有grok进程并连接其 instrumentation socket。优点是零配置缺点是只能监控本机进程。方式二独立服务生产必备在专用服务器上运行# 创建配置文件 dashboard-config.yaml api: port: 8000 host: 0.0.0.0 agents: - url: http://app-server-1:8080/instrumentation - url: http://app-server-2:8080/instrumentation - url: http://ci-runner:8080/instrumentation然后grok dashboard serve --config dashboard-config.yaml这里url必须指向每个 Grok 进程暴露的 instrumentation endpoint默认/instrumentation。你需要在每个 agent 启动时加--instrumentation-url http://dashboard-server:8000让它们主动上报。注意方式二要求所有 Grok 进程和 Dashboard 服务网络互通。我们用 Kubernetes Service DNS--instrumentation-url http://grok-dashboard.default.svc.cluster.local:8000。4.3 常见问题速查表与独家避坑技巧问题现象可能原因排查命令解决方案我的实操心得Dashboard 空白显示 “No agents found”grok run未加--enable-instrumentationps aux | grep grok | grep instrumentation重启 agent确认命令含该 flag我们写了个 wrapper scriptgrok-run-safe自动检查 flag缺失则报错退出杜绝人为遗漏Agent 卡在 “Initializing”状态环不动worktree 路径权限不足runtime 无法写 instrumentation socketls -la /tmp/grok-instr-*chmod 755 /tmp或指定--instrumentation-dir /var/run/grok默认 socket 在/tmp但某些 Docker 容器/tmp是 tmpfs重启丢失。现在我们一律用--instrumentation-dir /var/run/grok并 mount host volumeWorktree 列表显示 “Corrupted”但git worktree list正常.git/worktrees/name目录被手动删除但git worktree list缓存未刷新git worktree prune --dry-run运行git worktree prune清理缓存Dashboard 的 “Corrupted” 状态是基于os.path.exists(.git/worktrees/name)比git worktree list更严格。遇到此状态先prune再 refreshTrace Explorer 中看不到 tool input/outputtool模块未继承BaseTool或未打tooldecoratorgrep -r class.*Tool tools/ | grep -v BaseTool确保所有 tool 类继承grok.tools.BaseToolGrok 的 instrumentation 只拦截BaseTool.execute()自定义类不生效。我们有个tools/utils.py里面全是def my_tool(): ...结果 Dashboard 完全看不到它们 —— 必须包装成 classDashboard 页面加载慢CPU 占用高同时监控 50 个 agent前端未做 virtual scrolltop查看浏览器进程升级到 Grok Build 0.9.0已启用虚拟滚动0.8.x 版本在 30 agent 时页面卡顿。升级后流畅但要注意grok dashboard serve的内存限制我们设--max-agents 100防 OOM独家避坑技巧技巧一用 Dashboard 做 CI/CD 的 gatekeeper在 GitHub Actions 的 deploy job 末尾加一步- name: Verify Dashboard Health run: | curl -s http://dashboard:8000/api/v1/health | jq -e .status ok curl -s http://dashboard:8000/api/v1/worktrees | jq -e map(select(.status Active)) | length 0如果 Dashboard 返回非 200 或没有 Active worktree整个 deploy 失败。这比检查curl http://app:8080/health更可靠因为它验证了 “agent worktree” 的联合健康。技巧二把 Dashboard URL 写进 every agent 的 error response在 agent 的 error handler 里def handle_error(e): dashboard_url os.getenv(GROK_DASHBOARD_URL, http://localhost:8000) return { error: str(e), dashboard_link: f{dashboard_url}/agents/{self.id} }这样前端用户看到报错点击链接直达问题 agent省去客服转述环节。技巧三用 Dashboard 的 “Export State” 功能做故障复现点击 agent 卡片的 “Export State”它会下载一个 JSON包含该 agent 的完整 runtime state、最近 10 条 log、绑定的 worktree commit。把这个 JSON 发给同事他用grok run --import-state state.json就能在自己机器上 1:1 复现故障不用传整个数据库。5. 进阶用法与未来扩展超越基础监控的生产力杠杆5.1 基于 Dashboard 的自动化运维脚本Dashboard 的 REST API 是完全开放的我们写了几个高频脚本auto-restart-stale.py每 5 分钟扫描/api/v1/agents找出last_heartbeat 30的 agent调用/restart。import requests resp requests.get(http://dash:8000/api/v1/agents) for agent in resp.json(): if time.time() - agent[last_heartbeat] 30: requests.post(fhttp://dash:8000/api/v1/agents/{agent[id]}/restart)worktree-sync-all.sh批量同步所有Status: Idle的 worktreecurl -s http://dash:8000/api/v1/worktrees | \ jq -r .[] | select(.statusIdle) | .name | \ while read wt; do curl -X POST http://dash:8000/api/v1/worktrees/$wt/sync donealert-on-correlation.py监控 correlation matrix当某个 worktree 的 error rate 15% 持续 5 分钟发 Slack 告警# 获取 matrix 数据 matrix requests.get(http://dash:8000/api/v1/correlation).json() for wt, agents in matrix.items(): for agent, rate in agents.items(): if rate 0.15: # 检查是否持续 5 分钟需存历史 send_slack(fHigh error rate {rate:.0%} for {agent} on {wt})这些脚本把 Dashboard 从 “查看工具” 变成 “执行中枢”运维效率提升 70%。5.2 与现有工具链的深度集成VS Code 插件我们开发了grok-dashboard-viewer插件右键 agent.yaml 文件选择 “Open in Dashboard”自动跳转到对应 agent。更酷的是插件在编辑器底部状态栏显示当前 worktree 的 Dashboard health score红色时自动提示 “⚠️ worktree prod-v3 has 2 agents with error rate 20%”。Obsidian 双向链接在 Obsidian 的 agent 笔记中用[[Dashboard:agent-planner]]语法点击即打开 Dashboard。我们还用 Dataview 插件自动从/api/v1/agents拉取数据生成 “所有 agent 的 health score 表格”每天自动更新。Grafana 数据源虽然 Dashboard 本身不替代 Grafana但我们把它的 metrics 暴露为 Prometheus endpoint/dashboard/metrics。这样可以在 Grafana 里画 “Dashboard-reported error rate vs. Prometheus LLM latency”交叉验证问题根源。5.3 未来可期Dashboard 正在演进的方向根据 Grok Build 的 RFC 文档和我们的 beta 测试接下来几个版本会加入Predictive Health Scoring预测性健康分基于历史 error pattern 和当前 resource usage预测未来 5 分钟内 crash 概率。比如当tool-db的 error rate 连续上升 CPU 90%模型会预警 “Crash risk: 87% in next 3 min”。Agent-to-Agent Dependency Map自动发现 agent 间的调用关系如planner调用searchsearch调用summarize生成依赖图。当summarize出问题图会高亮所有上游 agent。One-Click Rollback点击 worktree 的 “Rollback to commit abc123”Dashboard 自动1) stop bound agents2)git reset --hard abc1233) restart agents。整个过程 10 秒。这些不是 PPT 功能我们已经在内部 alpha 环境试用。预测性评分已经帮我们提前 12 分钟拦截了一次线上事故 —— 它在 CPU 爆满前 3 分钟就发出预警我们手动 kill 了那个 rogue agent。我在实际使用中发现Dashboard 的最大价值不是“救火”而是“防患”。它把那些原本要靠经验、靠运气、靠深夜翻日志才能发现的隐患变成一眼可见的视觉信号。当你的团队从 3 人扩到 12 人从 2 个 agent 扩到 47 个从 1 个 worktree 扩到 32 个你会感激这个/dashboard路由的存在——它不是功能而是秩序。