本地AI任务编排工具AgentForge：从看板管理到多代理协作

1. 项目概述一个能调度AI编码代理的本地看板工具如果你和我一样日常开发中经常需要让Claude Code这类AI编码助手去执行一些重复性的代码审查、重构或者生成任务并且希望这些任务能像CI/CD流水线一样被编排、调度和监控那么你一定会对AgentForge这个项目感兴趣。它本质上是一个运行在你Mac本地的、轻量级的AI任务编排中心。你可以把它想象成一个专为AI编码代理设计的“看板”或“任务队列管理器”只不过这里的“工人”不是人类开发者而是Claude Code或OpenAI Codex CLI。这个工具解决的核心痛点非常明确将零散的、一次性的AI编码交互转变为可计划、可依赖、可观察的自动化工作流。比如你可以设置一个每天上午9点自动运行的代码审查任务让它扫描指定项目目录下的最新提交或者创建一个复杂的多步骤重构流水线让一个AI代理完成任务A后自动触发任务B和C并将A的结果作为B的输入。这一切都可以通过一个简洁的Web界面或直接调用REST API来管理任务状态和实时输出会直观地展示在看板Queue, Running, Done三列上。我最初是被它的“Agents that spawn agents”代理能创建子代理特性吸引的。这意味着你可以在一个Claude Code的对话中直接通过一个内置技能Skill去创建和管理新的AgentForge任务从而实现递归的、图状的工作流。这彻底打破了传统“一问一答”的线性模式让AI代理之间可以协作甚至构建出有依赖关系的任务链DAG。对于需要多步骤、多角度分析的复杂编码任务比如系统性的架构评估或竞品代码分析这种能力简直是降维打击。2. 核心架构与设计思路拆解2.1 为什么选择本地化、轻量级的架构AgentForge的架构选择非常务实完全围绕“个人开发者或小团队在本地高效使用”这一场景设计。整个系统由三部分组成一个用Python写的单文件HTTP后端服务器taskboard.py、一个基于Electron的桌面应用外壳、以及一个React构建的前端看板界面。后端Python是整个系统的大脑它基于Python标准库的BaseHTTPRequestHandler实现了一个RESTful API服务器。这种选择避免了引入Flask、FastAPI等重型框架让依赖极简启动飞快。所有任务数据、运行日志和流式输出都持久化在一个SQLite数据库~/.agentforge/tasks.db里。SQLite的零配置和单文件特性完美契合了“开箱即用、数据随身”的定位。任务调度器是一个简单的循环每2秒检查一次数据库看看是否有到期的任务需要执行立即、延迟、定时或Cron表达式。执行器则负责调用系统PATH上的claude或codex命令行工具并实时捕获它们的输出流写入数据库并推送给前端。前端Electron React负责提供用户界面。Electron外壳的作用主要是包装和生命周期管理启动时自动运行Python后端进程退出时干净地终止它。这样用户感知到的就是一个完整的macOS应用。界面本身是一个单页React应用核心就是一个看板组件通过轮询后端API来获取任务列表和实时日志用不同颜色区分状态等待、运行、成功、失败。这种架构的最大优势是部署简单、资源占用低、完全离线可控。所有计算和AI调用都发生在你的本地机器上任务数据和提示词不会离开你的环境这对于处理公司内部代码或敏感项目时至关重要。同时由于后端是独立的HTTP服务你完全可以脱离Electron外壳通过curl命令或自己写的脚本与之交互实现了很好的自动化集成能力。2.2 双Agent后端的设计考量与选型项目支持Claude Code CLI和OpenAI Codex CLI双后端这个设计背后有很实际的考虑。Claude CodeAnthropic出品和CodexOpenAI出品是目前最成熟的两个面向代码生成的AI命令行工具但它们各有侧重。Claude Code在代码生成、解释和重构上表现出色特别是对复杂逻辑的理解和生成代码的可读性。它的技能Skills生态系统是一个巨大优势AgentForge自带的“agentforge”技能就是基于此开发的实现了代理创建代理的魔法。OpenAI Codex CLI则可能在某些特定代码补全或快速原型生成场景下速度更快或者有些开发者已经对其工作流非常熟悉。AgentForge允许你按任务指定使用哪个后端也可以设置一个全局默认值。这个灵活性很重要。比如我通常将Claude Code设为默认用于大多数代码理解和生成任务。但对于一些简单的、模式固定的代码片段生成比如根据JSON Schema生成TypeScript接口我可能会在创建任务时显式指定使用codex因为它在某些时候响应更快。这种混合使用的策略能让你根据任务特性选择最合适的工具。实操心得后端选择的影响选择不同的后端不仅仅是换一个执行命令。它们对提示词Prompt的响应风格、输出格式尤其是流式输出可能略有不同。在设计复杂的、依赖上游输出作为下游输入的多代理流水线时最好先统一使用一个后端进行测试确保输出解析的稳定性。混用虽然可以但会增加流水线调试的复杂度。2.3 看板Kanban交互模型的价值为什么是看板而不是一个简单的任务列表这体现了项目对“状态可视化”和“流程管理”的深刻理解。软件开发中的看板能直观反映工作项在“待办”、“进行中”、“已完成”等状态间的流动。AgentForge借鉴了这一模型将AI任务的状态管理变得极其直观。Queue队列所有已创建但尚未到执行时间的任务都在这里。包括等待依赖项完成的DAG任务、设置了未来执行时间的定时任务。Running运行中当前正在执行的任务。这里最关键的是实时输出流。前端会持续从后端获取该任务的最新输出并追加显示让你能像在终端里一样实时看到AI“思考”和“操作”的过程。这对于调试复杂提示词或监控长时间运行任务至关重要。Done已完成执行完毕的任务根据成功或失败用不同颜色标识。你可以点击查看完整的输出日志和历史运行记录。这种视觉化的管理方式极大地降低了对多个并行、异步AI任务进行监控和管理的认知负荷。你一眼就能看清系统的全貌什么在等待什么正在跑什么已经结束。这是命令行工具难以提供的体验。3. 从零开始部署与深度配置指南3.1 环境准备与依赖安装的避坑要点根据官方要求你需要macOS 12.0、Python 3.12和Node.js 18。在实际操作中有几点需要特别注意Python环境管理强烈建议使用uv或pyenv来管理Python版本。项目推荐uv因为它同时也是一个快速的包管理器和运行器。安装uv后进入项目目录执行uv sync它会自动创建虚拟环境并安装所有Python依赖主要是croniter用于解析Cron表达式。这比手动处理pip和virtualenv要干净利落得多。Node.js与npm确保你的Node.js版本符合要求。对于国内用户npm install步骤可能是最大的障碍因为Electron的二进制包下载非常缓慢且容易失败。官方文档给出了明确的解决方案# 设置npm镜像源 npm config set registry https://registry.npmmirror.com # 设置Electron二进制包的镜像 export ELECTRON_MIRRORhttps://npmmirror.com/mirrors/electron/ # 然后进入前端目录安装 cd taskboard-electron npm install这个操作能有效解决网络超时问题。如果安装过程中出现关于原生模块native addons编译的错误通常是因为缺少macOS的开发命令行工具Command Line Tools在终端运行xcode-select --install即可。AI命令行工具这是项目的核心执行引擎。你必须至少安装其中一个。Claude Code CLI前往Anthropic官方文档安装并配置好API密钥。安装后在终端输入claude --version应能正常显示版本号。确保它在你的系统PATH中。OpenAI Codex CLI通过npm install -g openai/codex安装。同样需要预先配置好OpenAI的API密钥。3.2 三种安装方式的场景化选择项目提供了三种安装方式适用于不同场景方式一桌面应用推荐给大多数用户直接从GitHub Releases页面下载AgentForge-*.dmg文件拖入/Applications即可。这是最省心的方式适合想快速体验核心功能的用户。应用内部已经打包好了所有依赖包括Python后端和Node.js环境你只需要确保本机已安装Claude Code CLI即可。方式二从源码构建DMG如果你需要自定义一些配置或者想在发布前测试自己的修改可以使用这种方式。git clone https://github.com/hetaoBackend/agentforge.git cd agentforge make install-deps # 这会使用uv和npm安装所有依赖 make package-dmg # 构建并生成DMG安装包生成的DMG文件位于taskboard-electron/out/make/目录下。这种方式让你对构建过程有完全的控制权。方式三开发模式运行这是为贡献者或深度定制者准备的。它同时启动Python后端和前端开发服务器支持代码热重载。# 终端1启动Python后端 uv run taskboard.py # 终端2启动Electron和Vite开发服务器 cd taskboard-electron npm start此时Electron窗口会打开并加载本地开发服务器通常是http://localhost:5173。你在taskboard.py或前端React组件App.jsx中的修改保存后几乎能实时看到效果。这是调试和添加新功能的标准工作流。3.3 后台服务的持久化运行桌面应用在关闭时会连带退出Python后端。如果你希望后端作为一个常驻服务运行例如为了通过API持续接收来自聊天机器人的任务就需要将其设置为后台服务。项目提供了一个macOS LaunchAgent的plist配置文件示例。你需要修改其中的关键路径ProgramArguments确保/usr/local/bin/uv的路径正确可以通过which uv查看。/path/to/agentforge/taskboard.py必须替换为你本地仓库的绝对路径。WorkingDirectory同样替换为仓库的绝对路径。StandardOutPath和StandardErrorPath指定了日志输出位置方便排查问题。将修改好的plist文件保存到~/Library/LaunchAgents/com.agentforge.taskboard.plist然后执行launchctl load ~/Library/LaunchAgents/com.agentforge.taskboard.plist这样后端服务就会在系统启动时自动运行并且在崩溃后自动重启得益于KeepAlive键。你可以通过launchctl list | grep agentforge来检查服务状态通过查看/tmp/agentforge.log来监控日志。注意事项后台服务的资源管理将AgentForge作为后台服务运行时需要注意它本质上是一个轮询器每2秒检查一次任务。虽然单个任务不执行时资源占用极低但如果你创建了大量Cron定时任务调度器本身会持续工作。建议定期通过看板UI或API清理已完成的历史任务避免数据库文件无限制增长。对于非常重要的生产级流水线建议还是使用更健壮的任务队列如Celery但AgentForge的定位就是轻量、本地、个人使用在这个范围内它做得足够好。4. 核心功能实操任务创建、调度与聊天控制4.1 通过API创建多样化任务AgentForge的后端API是功能控制的核心。所有操作都围绕http://127.0.0.1:9712/api这个端点展开。创建任务是最基本的操作其灵活性体现在多个维度。基础立即任务这是最简单的形式指定标题、提示词和工作目录即可。curl -X POST http://localhost:9712/api/tasks \ -H Content-Type: application/json \ -d { title: 分析日志错误, prompt: 请分析~/projects/myapp/logs/error.log文件找出最近24小时内出现频率最高的前5个错误并给出修复建议。, working_dir: ~/projects/myapp, schedule_type: immediate }这里working_dir是关键它决定了AI命令行工具执行时的上下文路径。AI生成的任何文件操作命令如cat,grep,find都会基于此目录。延迟与定时任务schedule_type可以是delayed延迟指定秒数后执行或datetime在特定的ISO格式时间点执行。这对于非实时任务非常有用比如“在代码合并后半小时进行深度扫描”。# 延迟5分钟执行 schedule_type: delayed, delay_seconds: 300 # 在今天下午3点执行 schedule_type: datetime, scheduled_for: 2023-10-27T15:00:00Cron周期性任务这是实现自动化工作流的利器。你可以像配置crontab一样设置任务。{ title: 每日代码健康检查, prompt: 运行项目的单元测试检查测试覆盖率是否低于85%并列出最近3天新增的TODO和FIXME注释。, working_dir: ~/projects/myapp, schedule_type: cron, cron_expr: 0 9 * * *, # 每天上午9点 max_runs: 100 # 可选限制最大执行次数 }Cron表达式非常强大可以定义复杂的周期如*/30 * * * *每30分钟、0 18 * * 1-5每周一到周五下午6点。结合AI的能力你可以轻松构建一个自动化的代码质量守护机器人。4.2 聊天通道集成将AI助手放进你的IM工具这是AgentForge最具创新性的功能之一。它允许你通过Telegram、Slack、飞书Feishu/Lark或微信实验性来创建和管理任务。想象一下在团队群聊里一下机器人说“帮我看一下PR #123的代码风格问题”机器人就自动创建一个AgentForge任务去执行完成后将结果反馈到群里。这极大地降低了使用门槛。配置核心逻辑每个聊天通道都是一个独立的插件位于channels/目录。它们的工作原理是作为“客户端”主动连接或监听来自IM平台的消息将其转化为对AgentForge后端API的调用。因此配置的关键在于正确设置IM平台所需的认证信息Token、App ID/Secret等并确保AgentForge后端服务可达对于Webhook模式可能需要内网穿透对于Socket Mode或长连接则不需要。以Telegram为例这是设置最简单的通过BotFather创建机器人获得HTTP API Token。设置环境变量export TELEGRAM_BOT_TOKEN你的Token export TELEGRAM_ALLOWED_USERS你的Telegram用户ID # 可选用于权限控制重启AgentForge后端。机器人会自动开始轮询Telegram API获取新消息。当你在Telegram中向机器人发送/newtask 重构用户模块 | 检查代码耦合度提出重构方案时机器人会解析命令调用/api/tasks接口创建任务并在任务完成后将摘要或完整输出发送给你。飞书/钉钉的配置差异飞书采用了应用设置API的方式而不是环境变量。你需要先在飞书开放平台创建应用启用机器人并获取app_id和app_secret。然后通过一个特殊的API端点/api/feishu/settings将这些信息提交给AgentForge。飞书通道使用WebSocket长连接这意味着你的AgentForge服务不需要有公网IP非常适合在内网环境使用。实操心得聊天通道的安全与权限访问控制务必使用*_ALLOWED_USERS环境变量或类似配置将机器人命令权限限制在可信用户范围内。否则任何知道机器人账号的人都可以触发任务执行。提示词安全通过聊天创建任务时提示词可能包含敏感信息。虽然通信通常有加密但请避免在提示词中直接写入API密钥、密码等。可以考虑让AI从安全的配置文件中读取。输出控制AI任务的输出可能很长。在聊天通道中最好配置为只发送成功/失败状态和关键摘要并提供链接到Web看板查看完整日志。否则刷屏式的输出会严重影响聊天体验。4.3 多代理流水线DAG与技能集成这是AgentForge的“杀手级”功能。它通过一个内置的Claude Code技能实现了代理间的任务创建和依赖管理。技能安装与原理Claude Code的技能机制允许用户扩展其能力。AgentForge提供了一个技能包skills/agentforge/你需要将其软链接到Claude Code的技能目录下ln -s /path/to/agentforge/skills/agentforge ~/.claude/skills/agentforge安装后当你在Claude Code对话中使用特定指令例如/agentforge时就能触发该技能。该技能的本质是一组精心设计的提示词和逻辑它会让Claude Code理解如何与AgentForge的API进行交互包括创建新任务、查询状态、注入结果等。构建一个DAG工作流假设你想让AI分析一个项目流程是1) 先进行静态代码分析2) 然后基于分析结果运行测试3) 最后生成一份报告。你可以这样操作在Claude Code中你输入提示词“请使用agentforge技能创建一个名为‘静态分析’的任务分析~/projects/x目录的代码复杂度。”Claude Code会调用技能向AgentForge API发送请求创建任务A并返回任务ID比如task_abc。你继续输入“现在请创建一个名为‘运行测试’的任务它依赖于--depends-on刚才的任务AID:task_abc并在其提示词中注入--inject-result任务A的输出结果。工作目录相同。”技能会创建任务B并设置depends_on字段为task_abc同时将任务A的完整输出作为前缀添加到任务B的提示词中。任务A完成后调度器会自动触发任务B。任务B的AI在执行时就能看到任务A的分析结果作为上下文。通过这种方式你可以在一个Claude Code对话中动态地构建出一个有向无环图DAG的工作流。上游任务的失败会自动级联取消下游任务通过failure_propagation机制确保了流程的健壮性。高级模式扇出/扇入Fan-out/Fan-in技能还支持更复杂的模式。例如你可以让一个“主控”任务创建多个并行的“子研究”任务扇出等待所有子任务完成后再创建一个“汇总”任务来整合所有结果扇入。这非常适合需要多维度并行调研的场景比如竞品分析、多模块代码审查等。5. 高级使用技巧、问题排查与维护5.1 性能调优与资源管理随着任务数量的增长你需要关注几个性能点数据库优化SQLite在轻负载下表现优异但任务历史runs表和输出日志output表可能快速增长。建议定期归档或清理旧数据。AgentForge目前没有内置的清理机制你可以通过API (DELETE /api/tasks/:id) 手动删除已完成的任务或者编写一个定期的清理脚本这本身也可以作为一个AgentForge的Cron任务。并发执行默认情况下AgentForge的任务执行是串行的一个接一个。这是为了避免多个AI进程同时运行导致系统资源CPU、内存争抢以及可能的命令行上下文冲突。如果你确实需要有限的并发可以考虑修改taskboard.py中的AgentExecutor类引入一个带有限制如最多2个的线程池或进程池来执行claude/codex命令。但请注意这可能会使输出流和日志记录变得复杂。提示词优化任务的执行时间很大程度上取决于AI的响应速度。清晰、具体、有约束的提示词能获得更快、更准确的响应。避免让AI进行开放式、无休止的探索。对于复杂任务利用DAG将其拆分为多个步骤明确的子任务往往比一个巨型提示词更高效。5.2 常见问题与排查指南以下是我在长期使用中遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案任务创建成功但一直处于“Queue”状态不执行1. 后端调度器未运行。2. 系统时间/时区问题导致Cron表达式未触发。3. 任务有前置依赖depends_on未完成。1. 检查后端进程是否存活 (ps aux任务执行失败日志显示Command ‘claude’ not found1. Claude Code CLI未安装或不在PATH中。2. AgentForge运行环境如LaunchAgent的PATH与用户终端不同。1. 在终端直接运行claude --version测试。2. 对于后台服务在plist文件中使用keyEnvironmentVariables/key显式设置PATH包含/usr/local/bin等目录。聊天机器人无响应1. 对应的通道未启用或配置错误。2. Token/Secret无效或过期。3. 网络问题对于需要公网访问的Webhook。1. 检查后端启动日志确认目标通道初始化成功。2. 重新在IM平台申请Token/Secret并更新配置。3. 对于Telegram/Slack尝试在配置中启用更详细的日志查看消息接收情况。对于飞书检查WebSocket连接状态。前端看板无法加载或白屏1. 前端开发服务器未启动开发模式。2. 生产版本中静态资源路径错误。3. 后端API服务未启动或端口被占用。1. 开发模式确认npm start已运行并检查Vite服务器日志。2. 检查Electron开发者工具CmdOptI中的Console和Network标签页查看具体错误。3. 确认taskboard.py后端正在监听9712端口 (lsof -i :9712)。DAG任务中下游任务未接收到上游任务的结果1.--inject-result参数未正确传递或解析。2. 上游任务输出格式异常导致注入时出错。3. 技能在构造提示词时发生错误。1. 检查通过技能创建任务时命令格式是否正确。2. 查看上游任务的原始输出日志确认其是纯文本或可解析的格式。避免输出包含特殊字符或过长的行。3. 在Claude Code对话中手动模拟技能调用观察其生成的API请求体是否正确。5.3 扩展与自定义开发AgentForge的代码结构清晰非常适合扩展。以下是几个常见的自定义方向添加新的聊天通道参考channels/目录下的现有实现如telegram.py。核心是创建一个类实现start(),stop(),send_message()等方法负责与特定IM平台通信并将接收到的消息转化为对APIClient的调用。最后在taskboard.py的ChannelManager中注册这个新通道。集成其他AI后端除了Claude和Codex你可以集成任何提供命令行接口的AI工具。修改AgentExecutor类添加对新命令的支持并在创建任务时通过agent字段指定。你需要处理该CLI特有的参数传递和输出流解析。增强前端看板React前端App.jsx是一个相对独立的组件。你可以为其添加新功能比如任务输出搜索、图表化展示任务执行时间统计、更丰富的任务过滤和排序选项等。开发新的Claude Code技能AgentForge技能只是一个起点。你可以基于其模式开发更专业的技能。例如一个专门用于创建“代码安全扫描”任务的技能其提示词模板已经预置了相关的检查命令和输出解析逻辑。这个项目的魅力在于它用一个简洁的架构解决了一个切实的痛点并且每个部分都足够开放让你可以按需将其塑造成更适合自己工作流的形状。它不是一个大而全的企业级调度系统而是一个锋利、专注、可组合的瑞士军刀完美地嵌入了AI增强开发的流程之中。