1. 项目概述一个为AI辅助开发而生的“驾驶舱”如果你和我一样每天都在和AI编程助手比如Claude、Cursor、GPT Engineer等打交道那你一定对那种“精神分裂”般的工作状态深有体会。左手边是终端bd命令在滚动右手边是Telegram或Discord和AI的对话窗口闪烁不停中间还得开着浏览器和IDE随时准备审查AI生成的代码。信息被切割在不同的应用和窗口里来回切换不仅打断心流更糟糕的是你很容易就忘了某个任务的具体上下文或者错过了AI在另一个会话里完成的关键提交。AgentBoard就是为了终结这种混乱而生的。它不是一个简单的聚合器而是一个专为AI辅助开发工作流设计的原生macOS应用一个真正的“驾驶舱”。它将任务看板基于Beads、与AI的实时对话通过OpenClaw网关、以及运行中的编码会话监控无缝整合进一个统一的、高性能的SwiftUI界面。简单来说它让你在一个窗口里就能看到所有AI代理在干什么、跟它们对话、并管理它们的工作产出。这对于管理多个并行项目、依赖多个AI代理协作的复杂开发场景来说效率提升是颠覆性的。2. 核心设计理念与架构拆解2.1 为什么是“驾驶舱”模式传统的IDE或项目管理工具其交互模型是围绕“人类开发者”单点操作设计的。但在AI辅助开发中工作主体变成了“人类多个AI代理”的混合团队。这带来了几个根本性变化异步与并行多个AI代理可能同时在处理不同任务。状态分散任务状态在git提交里对话在聊天工具里运行日志在终端里。上下文依赖AI需要精确的任务描述Bead和项目上下文才能有效工作。AgentBoard的“驾驶舱”设计正是为了应对这些变化。它将三个核心维度——任务What、沟通How、执行Where——并置呈现。任务维度看板基于Beads这个git-backed的issue tracker所有任务变更本身就是一次git提交天然具备版本追溯能力。看板不是数据库的UI而是文件系统.beads/issues.jsonl的实时视图。沟通维度聊天集成OpenClaw网关让你可以直接在应用内与AI对话。关键优化在于“Bead链接”——AI回复中提及的Bead ID会被自动识别并高亮点击即可在看板上定位该任务实现了对话与任务的无缝跳转。执行维度监控通过tmux会话监控实时展示每个AI编码代理的运行状态、输出终端内容。你可以看到它是正在运行、卡住了还是出错了甚至可以直接从UI向卡住的会话发送一个“回车”指令进行干预。这种三位一体的设计确保了管理者你对整体工作流的全局感知和精细控制。2.2 技术栈选型背后的考量AgentBoard的技术选型充分体现了macOS原生应用的优势和对现代Swift生态的拥抱SwiftUI macOS 15这保证了应用能充分利用最新的系统API如强化后的WKWebView、更精细的快捷键API并拥有顶级的性能和原生交互体验。使用Observable宏而非旧的ObservableObject是紧跟Swift 6严格并发性Strict Concurrency的要求从框架层面减少数据竞争的风险。无状态架构State-less应用本身不维护核心数据库。Beads文件是唯一的事实来源。AgentBoard通过DispatchSource文件监视器BeadsWatcher监听issues.jsonl的变化实时更新UI。这种设计带来了巨大优势你完全可以用任何其他工具甚至是vim修改Beads文件AgentBoard的看板会立刻同步。它也避免了数据同步的复杂性因为git本身就是同步机制。Actor模型处理并发与OpenClaw网关的WebSocket通信、文件监视、会话轮询都是高并发的I/O操作。AgentBoard使用Swift的Actor如OpenClawService来封装这些服务确保了跨线程访问的状态安全代码更清晰更不容易出现难以调试的并发bug。依赖最小化核心依赖只有两个SwiftTerm用于终端渲染swift-markdown用于解析。这降低了维护成本也使得应用更轻量、启动更快。实操心得文件监视的坑使用DispatchSource做文件系统监听时一个常见的坑是监听符号链接symlink或临时文件。Beads的issues.jsonl是稳定路径这没问题。但在实现类似功能时如果监听目录要特别注意FSEvents的回调可能会非常频繁需要进行防抖debounce处理否则UI会频繁刷新导致卡顿。AgentBoard这里因为监听的是单个明确文件且变更频率不会极高所以直接处理是可行的。3. 核心功能深度解析与实操要点3.1 看板Kanban Board不只是拖拽看板是AgentBoard的信息中枢。其核心价值在于将Beads的纯文本issue可视化为具有明确工作流Open, In Progress, Blocked, Done的卡片。元数据驱动每张卡片展示的标题、类型Task/Bug/Feature/Epic/Chore、优先级P0-P4、负责人、标签都直接来自Beads的元数据。这意味着你可以通过编辑Beads文件来批量修改这些属性看板会自动响应。Epic联动这是项目管理的关键。一个Epic史诗卡片可以关联多个子任务。在Epic视图下你能看到一个清晰的进度条如“3/5”点击展开即可看到所有子任务的状态。这对于用AI拆解和实现大型功能模块至关重要——你可以先创建一个Epic然后让AI根据描述拆分成具体的子Beads。实时同步的魔法很多人会好奇UI是怎么实时更新的。关键在于BeadsWatcher服务。它创建了一个DispatchSourceFileSystemObject监听issues.jsonl文件的写入和重命名事件。一旦文件发生变化比如AI代理完成了一个任务并提交了更改监视器会收到事件解析新的文件内容并更新Observable的AppStateSwiftUI视图随之刷新。整个过程在毫秒级完成。操作技巧快速创建使用CmdN快捷键在任何地方快速弹出新建Bead的窗口。养成给新任务立即分配类型和优先级的习惯。上下文菜单右键点击卡片除了编辑删除最关键的是“Assign to agent”。这会将Bead ID复制到剪贴板方便你在聊天窗口中直接引用为AI提供精确上下文。从提交反查看板卡片上显示的最近提交SHA和分支名是可点击的。点击后右侧画布会直接加载这次提交的diff让你快速Review AI的代码改动。3.2 聊天Agent Chat有上下文的对话集成聊天功能不是为了替代Telegram而是为了绑定工作上下文。会话管理顶部下拉框可以切换不同的OpenClaw网关会话。这意味着你可以同时保持与Claude、GPT-4等不同模型的对话并在同一个界面管理无需切换应用。流式响应与中断AI回复是流式streaming输出的伴有打字机效果。如果发现AI的回答方向错了可以立即点击旁边的“停止”按钮中断这比在聊天软件里刷屏“停下”要高效得多。Thinking Levels这是一个高级功能。你可以选择“Low/Medium/High”的思考深度这实质上是向网关发送不同的推理参数对于复杂问题要求AI进行更深度的链式思考Chain-of-Thought可能得到更优解。Bead自动链接这是杀手级特性。当AI在回复中说“我已经完成了任务[bead:abc123]”这里的abc123会被自动识别并渲染成一个可点击的链接。点击后主看板会立即滚动并高亮对应的Bead卡片。这彻底打通了沟通与任务管理。配置要点网关连接首次启动AgentBoard会尝试读取~/.openclaw/openclaw.json来自动配置。如果网关运行在其他机器上你需要在设置中手动填入WebSocket URL例如ws://192.168.1.100:18789。设备配对首次连接一个新设备即新的AgentBoard实例时需要在运行OpenClaw网关的机器上执行命令进行授权openclaw devices approve device-id。这个设备ID基于存储在~/.agentboard/device-identity.json中的Ed25519密钥对生成确保了连接的安全性。3.3 会话监控与终端视图给AI装上“仪表盘”这是让你感知AI“生命体征”的功能。它通过轮询tmux会话和进程列表来监控所有由OpenClaw网关启动的编码代理如Claude Code、Aider等。状态可视化绿色运行中代理正在积极输出或思考。黄色空闲会话存在但近期没有输出。可能卡在某个交互提示。灰色已停止会话正常结束。红色错误进程意外退出或发生错误。终端视图点击任意会话右侧可以打开一个只读的终端视图实时显示该会话的所有输出。这对于调试AI行为、查看它具体执行了哪些命令至关重要。“Nudge”按钮当会话长时间处于“空闲”黄色状态时很可能是AI在等待一个确认比如git diff后等待y/n。这时你可以点击“Nudge”按钮它本质上是通过tmux向该会话发送一个回车Enter键事件推动流程继续。从UI启动会话你不仅可以监控还可以直接配置并启动一个新的编码会话。指定项目、选择代理类型、关联一个Bead ID、并提供一个初始提示Seed Prompt然后点击启动。AI代理就会在后台的tmux会话中开始工作并自动出现在监控列表里。注意事项tmux是必须的会话监控重度依赖tmux。确保你的OpenClaw网关配置的编码代理都是在tmux会话中运行的。同时AgentBoard需要有权限访问这些tmux会话通常意味着需要在同一个用户环境下运行。如果监控不到会话首先检查tmux ls命令是否能列出目标会话。4. 详细配置与高级使用指南4.1 项目发现与管理AgentBoard默认扫描~/Projects目录下所有包含.beads/子目录的文件夹并将其识别为一个项目。自定义项目路径 如果你项目不在~/Projects下有两种方式添加通过UI设置在应用的Settings中可以手动添加项目路径。通过配置文件创建或编辑~/.agentboard/config.json按如下格式配置{ projects: [ { name: 我的iOS项目, path: /Users/username/Development/MyApp, icon: }, { name: 后端服务, path: /Volumes/Work/backend, icon: ⚙️ } ] }重启应用后即可生效。图标字段是可选的但能帮助你在侧边栏快速识别。4.2 远程网关连接方案你的开发机运行AgentBoard和运行AI模型/网关的机器性能更强可能是分开的。AgentBoard支持多种远程连接方式连接方式适用场景配置要点局域网直连网关和AgentBoard在同一局域网。在网关配置中设置gateway.bind: 0.0.0.0然后在AgentBoard中填入ws://网关IP:18789。Tailscale等VPN机器位于不同网络但通过VPN组成虚拟局域网。使用网关在VPN中的IP地址如ws://100.xx.yy.zz:18789。确保VPN网络内端口可访问。SSH端口转发最通用、安全的方式尤其适合云服务器。在本地执行ssh -L 18789:localhost:18789 usergateway-host。然后在AgentBoard中连接ws://127.0.0.1:18789。所有流量通过加密的SSH隧道传输。安全建议对于暴露在公网的网关务必使用强令牌认证并考虑通过SSH隧道或VPN访问避免将WebSocket服务直接暴露。4.3 画布Canvas多功能输出面板右侧面板的画布是一个强大的内容渲染器它不仅仅是聊天记录的展示区。支持的内容类型Markdown/HTMLAI回复的标准渲染。图片可以直接拖拽图片到聊天输入框或画布区域进行上传和显示。代码Diff点击Bead卡片上的提交SHA后画布会通过GitService获取并渲染diff语法高亮清晰。Mermaid图表如果AI生成了Mermaid代码块画布会将其渲染成图表。这对于理解AI设计的架构图、流程图非常有用。终端输出从会话监控点击打开的终端内容也会在这里显示。工具栏操作画布顶部工具栏提供前进/后退历史导航、缩放控制以及导出功能可将当前内容导出为HTML或图片。三种布局模式通过右上角按钮切换。仅聊天专注于对话。仅画布全屏查看代码Diff或图表。分屏默认60%画布 40%聊天中间分隔条可拖动。这是最高效的模式一边看代码改动一边给AI下一步指令。5. 开发、构建与贡献指南5.1 本地构建环境搭建确保你的环境符合要求这是成功构建的第一步系统与工具macOS 15 (Sequoia) 或更高版本。Xcode 16.2并确保命令行工具已安装xcode-select --install。安装 XcodeGen brew install xcodegen。这个工具用于通过project.yml生成Xcode项目文件避免手动修改容易冲突的pbxproj文件。依赖服务安装 Beads brew install beads。确保有一个正在运行的 OpenClaw 网关实例。tmux通常系统已自带确保可用。获取代码并生成项目git clone https://github.com/jbcrane13/AgentBoard.git cd AgentBoard xcodegen generate # 解析 project.yml生成 AgentBoard.xcodeproj open AgentBoard.xcodeproj之后就可以在Xcode中正常编译运行了。5.2 项目结构与核心服务剖析理解项目结构有助于你进行二次开发或排查问题AgentBoard/ ├── App/AppState.swift # 核心全局可观察状态所有视图的数据源 ├── Models/ # 数据模型定义 │ ├── Bead.swift # 任务模型与Beads文件结构对应 │ ├── CodingSession.swift # 编码会话模型状态、进程信息等 │ └── ... ├── Services/ # 后台服务是应用的引擎 │ ├── OpenClawService.swift # Actor管理WebSocket连接和RPC调用 │ ├── BeadsWatcher.swift # 文件系统监视器驱动看板实时更新 │ ├── SessionMonitor.swift # 轮询tmux和进程更新会话状态 │ ├── CanvasRenderer.swift # 利用WKWebView渲染复杂内容 │ └── GitService.swift # 封装git命令获取提交和diff信息 └── Views/ # 所有SwiftUI视图 ├── Board/ # 看板相关视图 ├── Chat/ # 聊天界面 └── ...关键服务交互流程应用启动时BeadsWatcher开始监听项目目录下的issues.jsonl。用户点击一个Bead卡片AppState中当前选中的Bead ID更新。ChatView观察到选中ID变化可能在输入框中预填充上下文。用户发送消息ChatView调用OpenClawService这个Actor的方法。OpenClawService通过GatewayClient发送WebSocket消息并处理流式返回更新AppState中的消息列表。CanvasView观察到新消息调用CanvasRenderer将其渲染到WKWebView。同时SessionMonitor每隔几秒检查一次tmux会话更新AppState中的会话列表驱动UI状态图标变化。5.3 代码规范与质量保证项目采用了较高的代码质量标准严格并发检查在项目的Build Settings中设置了SWIFT_STRICT_CONCURRENCYcomplete。这意味着编译器会强制检查所有并发代码的安全性杜绝数据竞争。在编写任何新代码特别是服务层代码时必须正确使用actor、MainActor、Sendable等关键字。SwiftLint作为构建阶段Build Phase自动运行。提交代码前最好手动运行swiftlint lint检查是否有风格违规。规则定义在.swiftlint.yml中。SwiftFormat项目也配置了SwiftFormat用于代码格式化。虽然构建时不强制但建议在提交前运行swiftformat .来统一代码风格。强制代码风格使用SwiftUI新范式ObservableState。禁止强制解包!必须使用guard let、if let或提供默认值??。模型遵循Sendable协议以安全地在并发上下文间传递。开发工作流提醒 永远不要手动修改AgentBoard.xcodeproj/project.pbxproj文件。所有项目配置添加文件、调整构建设置等都应在project.yml中完成然后运行xcodegen generate重新生成。这是团队协作中避免Xcode项目文件冲突的最佳实践。5.4 如何贡献代码如果你发现了Bug或者有很棒的新功能想法非常欢迎贡献代码Fork仓库并基于main分支创建你的特性分支feat/add-xxx或修复分支fix/yyy-bug。在编码前先阅读设计文档DESIGN.md和docs/ADR.md架构决策记录。这能帮你理解项目的设计哲学和过往的技术决策确保你的贡献与项目方向一致。实现你的修改并确保遵循上述代码规范。充分测试# 运行所有测试 xcodebuild -project AgentBoard.xcodeproj -scheme AgentBoard build test # 也可以运行特定测试类 swift test --filter YourFeatureTests提交信息使用约定式提交例如feat: 添加多窗口支持、fix: 修复会话监控内存泄漏、docs: 更新快速开始指南。这有利于自动生成变更日志。发起Pull Request提供清晰的描述说明变更内容、动机以及测试情况。6. 常见问题排查与使用技巧6.1 连接与网络问题问题现象可能原因排查步骤无法连接到OpenClaw网关1. 网关未运行。2. 地址或端口错误。3. 防火墙阻止。1. 在网关机器运行openclaw status确认。2. 在AgentBoard设置中检查URL如ws://127.0.0.1:18789。3. 尝试curl -v http://网关IP:18789/health测试连通性。设备配对失败首次连接新设备需要授权。1. 在AgentBoard弹出的配对指南中复制设备ID。2. 在网关机器上运行openclaw devices approve 设备ID。3. 返回AgentBoard点击“重试连接”。聊天消息发送失败WebSocket连接已断开或令牌失效。1. 检查顶部连接状态指示器。2. 尝试重新启动AgentBoard应用。3. 检查网关日志查看是否有认证错误。6.2 数据与显示问题问题现象可能原因排查步骤看板不更新1. Beads文件监视器未启动。2. 项目路径未正确配置。1. 确认项目目录下有.beads/issues.jsonl文件。2. 尝试在终端手动修改该文件看应用是否响应。3. 检查~/.agentboard/config.json或UI设置中的项目路径是否正确。会话监控为空1.tmux不可用或会话名不匹配。2. OpenClaw网关未启动编码会话。1. 在终端运行tmux ls查看是否有OpenClaw创建的会话名称通常含openclaw或coding。2. 确认网关配置中编码代理的session_runner配置为tmux。3. 检查AgentBoard是否有权限访问当前用户的tmux会话。画布无法渲染Diff/Mermaid1. Git命令执行失败。2. 网络阻止加载Mermaid JS库。1. 确认项目是一个有效的git仓库。2. 对于Mermaid画布需要联网加载CDN上的库检查网络连接。6.3 性能与使用技巧快捷键是效率核心尽快熟记核心快捷键Cmd1~4切换标签页CmdN新建BeadCmdL聚焦聊天。这能让你手不离键盘保持流畅操作。合理使用分屏模式默认的60/40分屏模式是最佳工作布局。你可以将重要的代码Diff固定在画布左侧同时在右侧聊天区持续给AI反馈。利用Epic进行任务分解面对一个复杂需求不要直接扔给AI一个庞大的Bead。先在AgentBoard创建一个Epic然后让AI或你自己将其分解为多个具体的子任务Bead。这样看板上的进度条能给你清晰的全局概览。“Nudge”功能的使用时机当会话监控中某个会话长时间显示“空闲”黄灯且其终端视图停留在某个命令行提示符时才使用“Nudge”。不要滥用否则可能打断AI的正常思考过程。历史视图用于复盘在一天工作结束时打开历史视图按时间线回顾所有Bead状态变更、会话启动/完成和git提交记录。这是复盘AI工作效率、发现问题模式的宝贵工具。这个工具彻底改变了我与AI协作的方式从被动的、碎片化的响应转变为主动的、全局化的 orchestration编排。它带来的不仅是窗口管理的便利更是一种工作范式的转变——你不再是多个工具的使用者而是整个AI开发团队的指挥中心。