AI代理任务编排平台AgentForge：本地调度与自动化工作流实践

1. 项目概述：一个为AI编码代理设计的本地调度与编排平台

如果你和我一样，日常开发中重度依赖Claude Code这类AI编码助手，那你肯定遇到过这样的场景：想让它帮你做代码审查，但手头正在忙别的事，希望它能“排队”处理；或者有一个复杂的重构任务，需要先分析依赖，再生成测试，最后执行重构，你希望这些步骤能自动串联起来。手动在终端里一条条敲命令，不仅效率低下，还容易出错，更别提管理多个并行任务的状态了。AgentForge就是为了解决这些痛点而生的。

简单来说，AgentForge是一个运行在你Mac上的本地应用，它本质上是一个AI编码代理的任务调度与编排中心。你可以把它想象成一个专为Claude Code和OpenAI Codex CLI设计的“看板”或“工作流引擎”。通过它，你可以将AI任务（比如“审查这个PR的代码”、“为这个模块生成单元测试”）创建为可调度的任务项，设置立即执行、延迟执行，甚至是像cron job一样的定时任务。所有任务的状态（待处理、运行中、已完成）都会在一个可视化的看板界面上实时更新，任务执行过程中的输出也会像终端一样流式展示出来。

更酷的是，它支持多代理管道（DAG）。这意味着一个正在运行的AI代理，可以基于其执行逻辑，动态创建新的子任务，并指定它们之间的依赖关系。例如，一个“分析项目架构”的任务，可以派生出三个并行的子任务：“分析前端依赖”、“分析后端API”、“分析数据库模型”，等这三个都完成后，再触发一个“生成架构文档”的汇总任务。整个过程完全自动化，由AgentForge来负责调度、监控和结果传递。

它的核心价值在于，将一次性的、手动的AI交互，变成了可编排、可监控、可复用的自动化工作流。无论是想定时生成日报、自动化代码审查流水线，还是构建复杂的多步骤AI辅助开发流程，AgentForge都提供了一个轻量级但功能强大的本地解决方案。它尤其适合开发者、技术负责人以及任何希望将AI编码能力更深度、更自动化地集成到自己工作流中的人。

2. 核心架构与设计思路拆解

要理解AgentForge为什么这样设计，我们需要先拆解它要解决的核心问题：如何在一个本地环境中，可靠、灵活地调度和执行依赖于外部CLI工具（Claude Code/Codex）的长时间运行任务，并提供状态管理和用户交互。

2.1 技术栈选型背后的考量

AgentForge的技术栈是典型的“本地桌面应用”组合，但每个选择都有其明确的意图：

1. Python后端 (taskboard.py): 这是整个系统的大脑。选择Python而非Node.js或Go，首要原因是Claude Code和OpenAI Codex CLI本身就是命令行工具，Python在调用子进程、处理流式输出、解析命令行结果方面有天然优势，其subprocess模块非常成熟。其次，项目所需的轻量级HTTP服务器（BaseHTTPRequestHandler）、SQLite数据库操作、cron表达式解析（croniter）在Python生态中都有简单可靠的库，无需引入重型框架。用一个单文件实现所有后端逻辑（API、调度器、执行器），保持了极致的简洁和可维护性，也降低了部署复杂度。

2. Electron + React前端: 目标是提供跨平台的桌面应用体验（虽然目前仅限macOS）。Electron能打包成独立的.dmg安装包，用户双击即可安装使用，无需关心Python环境或命令行启动。React用于构建动态的看板UI，其组件化特性非常适合实时更新任务状态和流式输出内容。Vite作为开发服务器，提供了极快的热重载体验。这个组合确保了应用拥有现代桌面应用的交互和外观，而不仅仅是另一个命令行工具。

3. SQLite数据库: 所有任务定义、运行历史、日志输出都持久化在~/.agentforge/tasks.db中。SQLite是嵌入式数据库，无需单独部署服务，读写速度快，并且通过WAL模式可以很好地处理前端频繁轮询API带来的并发读操作。数据持久化意味着重启应用后所有任务历史和配置都不会丢失。

4. 进程间通信: 前端（Electron渲染进程）与后端（Python HTTP服务）通过localhost:9712的RESTful API进行通信。这是一种清晰、标准的解耦方式。Electron的主进程负责启动和守护Python后端进程。这种设计让后端可以独立运行（作为后台服务），也方便未来可能的架构演进，比如将后端替换为其他语言实现。

设计心得：对于这类工具型应用，技术选型的黄金法则是“用最合适的工具解决最核心的问题，并最大化用户体验和开发效率”。Python处理任务调度和CLI交互是“最合适的”，Electron提供原生应用体验是“用户体验最大化”，而两者通过HTTP API解耦，则兼顾了“开发效率”和“架构清晰度”。

2.2 核心工作流与数据流

让我们跟随一个任务的完整生命周期，看看数据是如何在系统中流动的：

1. 任务创建: 用户通过UI点击“新建任务”或通过Chat命令（如/newtask）发起请求。请求体包含title、prompt、working_dir、schedule_type等字段。
2. API接收与存储: 请求到达Python后端的POST /api/tasks处理器。处理器校验参数后，生成一个唯一的任务ID，将任务元数据（状态为queued）插入SQLite的tasks表。如果任务是immediate，它会被立即放入就绪队列；如果是delayed或cron，则计算下一次运行时间并存储。
3. 调度器轮询: 一个独立的TaskScheduler线程每2秒唤醒一次。它扫描数据库，找出状态为queued且计划运行时间<= now()的任务，将其状态改为running，并提交给AgentExecutor。
4. 代理执行:AgentExecutor根据任务配置的agent字段（或全局默认设置），在指定的working_dir下，构造命令行。例如，对于Claude Code，命令可能是claude --skill agentforge “{prompt}”。然后启动一个子进程，实时捕获其stdout和stderr。
5. 流式输出与状态更新: 执行器将捕获到的每一行输出，立即通过Server-Sent Events (SSE)或WebSocket（前端轮询GET /api/tasks/:id/output也是一种方式）推送到前端看板对应任务的输出面板。同时，输出内容也被追加写入数据库的task_output表，用于历史查看。
6. 任务完成与后续处理: 子进程退出后，执行器根据退出码更新任务状态为succeeded或failed。如果这个任务被其他任务depends-on，调度器会检查其依赖项是否全部完成，从而触发下游任务的执行。
7. 前端展示: React前端通过定时轮询GET /api/tasks获取所有任务的最新状态，并渲染到“Queue”、“Running”、“Done”三列看板中。用户点击任务可以展开查看实时或历史的流式输出。

这个流程的关键在于异步和非阻塞。HTTP API快速响应，繁重的CLI执行放在后台线程，状态和输出通过数据库和事件机制同步，确保了UI的流畅性。

3. 详细安装与配置指南

虽然项目README提供了安装步骤，但在实际搭建过程中，有很多细节和“坑”需要注意。这里我将提供一份更详尽、更具操作性的指南。

3.1 环境准备：不仅仅是安装包

在运行make install-deps或启动开发服务器之前，请确保你的系统环境是干净的。

1. 检查并安装基础命令行工具：

# 确认Xcode Command Line Tools已安装 xcode-select --install # 如果已安装，它会提示；如果需要安装，请同意许可协议。 # 安装Homebrew（如果尚未安装） /bin/bash -c "$$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 使用Homebrew安装Python和Node.js的指定版本 # AgentForge要求Python 3.12+和Node.js 18+ brew install python@3.12 brew install node@18 # 将新安装的版本加入PATH（对于zsh用户） echo 'export PATH="/usr/local/opt/python@3.12/bin:$PATH"' >> ~/.zshrc echo 'export PATH="/usr/local/opt/node@18/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # 验证版本 python3 --version # 应显示 Python 3.12.x node --version # 应显示 v18.x.x npm --version

2. 安装并配置UV包管理器：项目使用uv替代传统的pip，速度更快，依赖解析更可靠。

# 使用curl安装uv curl -LsSf https://astral.sh/uv/install.sh | sh # 安装后重启终端或 source ~/.zshrc uv --version

3. 安装AI代理后端（Claude Code / OpenAI Codex）：这是AgentForge能工作的前提。你必须至少安装其中一个。

• 安装Claude Code (推荐):

  # 访问 https://docs.anthropic.com/en/docs/claude-code 查看官方安装指南 # 通常是通过npm安装 npm install -g @anthropic-ai/claude # 安装后，你需要进行身份验证 claude auth # 按照提示在浏览器中完成登录 claude --version # 确保claude命令在终端中可以直接运行

• 安装OpenAI Codex CLI (可选):

  npm install -g @openai/codex # 同样需要配置API密钥 export OPENAI_API_KEY='your-api-key-here' # 可以添加到 ~/.zshrc 中持久化 codex --version

重要提示：请务必将claude和/或codex命令的安装路径加入到系统的PATH环境变量中，确保在任意目录下都能直接调用。你可以通过which claude来验证。

3.2 三种安装方式深度解析

方式一：桌面应用（推荐给绝大多数用户）这是最无脑的方式。从GitHub Releases页面下载.dmg文件，双击打开，将AgentForge图标拖入Applications文件夹即可。第一次打开时，macOS可能会提示“无法验证开发者”，你需要进入系统设置 -> 隐私与安全性，找到并允许运行。

• 优点：开箱即用，自动处理Python环境、依赖和后台进程。
• 缺点：无法进行二次开发或深度定制。

方式二：从源码构建（适合想定制或贡献代码的开发者）

git clone https://github.com/hetaoBackend/agentforge.git cd agentforge # 使用make命令安装所有依赖，包括Python和Node.js部分 make install-deps # 构建并打包成DMG文件 make package-dmg

• 构建过程详解：make package-dmg这个命令背后做了很多事情：
  1. 使用uv sync安装所有Python依赖到项目本地虚拟环境。
  2. 进入taskboard-electron目录，运行npm install安装所有前端和Electron依赖。
  3. 运行npm run build，使用Vite将React前端代码打包成静态文件。
  4. 使用electron-builder将Python后端、前端静态资源、以及Electron本身一起打包成一个签名（或未签名）的.app应用。
  5. 最后将.app打包进.dmg磁盘映像文件中。
• 可能遇到的问题：构建Electron应用可能需要下载特定版本的Electron二进制文件，如果网络不畅，可能会卡住。此时可以参考下一节的网络问题解决方案。

方式三：开发模式运行（适合开发者调试）这是我最常用的方式，因为可以实时看到代码改动效果。

git clone https://github.com/hetaoBackend/agentforge.git cd agentforge uv sync cd taskboard-electron && npm install && cd ..

然后你需要打开两个终端窗口：

• 终端1 (运行Python后端):

  # 在项目根目录下 uv run taskboard.py

  你会看到类似Starting server on port 9712的输出。
• 终端2 (运行Electron前端):

  # 在 taskboard-electron 目录下 npm start

  这会启动Electron窗口，并加载Vite开发服务器提供的页面。

实操心得：在开发模式下，前端的热重载（Hot Module Replacement）是生效的。你修改App.jsx等前端文件后，浏览器窗口会自动刷新。但修改Python后端文件taskboard.py后，需要手动重启终端1中的进程。我通常会使用nodemon或uvicorn的热重载功能来监控Python文件变化，但这需要稍微修改一下启动脚本。

3.3 网络问题与依赖安装故障排查

正如README所指出的，npm install卡住是最常见的问题，尤其是在网络环境不理想的情况下。这通常是因为在下载Electron的预编译二进制文件（体积约100MB）。

1. 使用国内镜像加速（最有效的方法）：

# 设置npm registry为淘宝镜像 npm config set registry https://registry.npmmirror.com # 设置Electron二进制文件的下载镜像 export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ # 可选：设置Electron构建工具的镜像 export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ # 进入前端目录重新安装 cd taskboard-electron rm -rf node_modules package-lock.json npm install

设置环境变量后，不仅npm install会从镜像站下载Electron，后续electron-builder打包时也会从镜像站获取资源。

2. 诊断安装卡住的原因：如果设置了镜像仍然很慢，可以查看npm install的详细日志。

npm install --verbose 2>&1 | tee install.log

然后查看install.log文件，搜索electron或downloading，看具体卡在哪一步。有时问题可能不是网络，而是本地需要编译原生模块（node-gyp），这需要你安装Xcode Command Line Tools和Python开发环境，我们在第一步已经做了。

3. 终极方案：手动下载并指定缓存如果镜像也不行，可以尝试手动下载Electron的二进制包。

• 从https://github.com/electron/electron/releases找到对应版本（查看package.json中的electron版本）的electron-vxx.x.x-darwin-arm64.zip（Apple Silicon）或electron-vxx.x.x-darwin-x64.zip（Intel）。
• 下载后，将其放入~/.npm/_cacache目录下（路径可能略有不同），或者更直接地，设置本地文件路径：

  export ELECTRON_CUSTOM_DIR="/path/to/your/downloaded/electron-zip"

  但这需要你对npm的缓存机制比较熟悉。通常，使用可靠的网络或镜像是最简单的。

4. 核心功能实操与高级用法

安装配置只是第一步，真正发挥AgentForge威力的在于如何用好它的核心功能。我们抛开基础操作，深入看看那些能提升效率的高级特性和实际应用场景。

4.1 看板任务管理：不仅仅是创建和运行

看板界面直观，但通过API，你能实现更精细的控制。

1. 创建复杂任务：除了基本的立即任务，延迟和定时任务非常有用。

# 创建一个5分钟后运行的延迟任务，用于代码审查 curl -X POST http://localhost:9712/api/tasks \ -H "Content-Type: application/json" \ -d '{ "title": "Review PR #123", "prompt": "作为资深工程师，请审查 ~/projects/myapp 目录下 feature/login-branch 分支的所有更改。重点检查：1. 安全性（密码哈希、SQL注入）。2. 代码风格是否符合项目规范。3. 是否有明显的性能问题。请给出具体的修改建议。", "working_dir": "~/projects/myapp", "schedule_type": "delayed", "delay_seconds": 300, "agent": "claude", "metadata": { "pr_number": 123, "reviewer": "alex" } }' # 创建一个每周一早上9点运行的周报生成任务 curl -X POST http://localhost:9712/api/tasks \ -H "Content-Type: application/json" \ -d '{ "title": "Weekly Code Summary", "prompt": "分析 ~/projects/myapp 仓库过去一周（从上周一到上周日）的所有git提交。总结：1. 新增了哪些主要功能？2. 修复了哪些关键bug？3. 代码库行数、文件数量的变化趋势。用Markdown格式输出。", "working_dir": "~/projects/myapp", "schedule_type": "cron", "cron_expr": "0 9 * * 1", # 分钟(0) 小时(9) 日(*) 月(*) 星期(1,周一) "max_runs": 52, # 最多运行52次（一年） "agent": "claude" }'

• metadata字段：这是一个非常有用的扩展字段，你可以存放任何JSON数据，用于在任务之间传递上下文，或者在前端进行自定义筛选和展示。

2. 任务查询与过滤：API提供了丰富的查询能力。

# 获取所有任务 curl http://localhost:9712/api/tasks # 获取特定状态的任务（例如，只查看失败的任务） # 这需要后端API支持过滤参数，如果原生不支持，可以结合jq工具处理 curl http://localhost:9712/api/tasks | jq '.[] | select(.status == "failed")' # 获取单个任务的详细信息，包括其所有运行历史 curl http://localhost:9712/api/tasks/<task_id> curl http://localhost:9712/api/tasks/<task_id>/runs # 获取任务的最新输出（流式接口，适合前端轮询） curl http://localhost:9712/api/tasks/<task_id>/output

3. 任务生命周期管理：

# 取消一个正在排队或运行的任务 curl -X POST http://localhost:9712/api/tasks/<task_id>/cancel # 重试一个失败的任务（会创建一次新的运行记录） curl -X POST http://localhost:9712/api/tasks/<task_id>/retry # 永久删除一个任务及其所有历史记录（谨慎操作！） curl -X DELETE http://localhost:9712/api/tasks/<task_id>

4.2 聊天通道集成：将AI助手融入IM工作流

这是AgentForge的杀手级功能之一，让你能在Telegram、Slack、飞书等日常聊天工具中直接创建和管理任务，实现真正的“随时随地，一句话触发AI工作流”。

以Telegram集成为例，深入配置：

1. 创建Bot与精细化权限： 除了从@BotFather获取token，你还可以为Bot设置更友好的描述和指令列表，让团队成员更容易使用。

   /setdescription - 描述：一个AI任务调度机器人，可以创建代码审查、生成报告等任务。 /setcommands - 设置命令列表： newtask - 创建新任务 list - 列出所有任务 status - 查看任务状态 cancel - 取消任务 help - 获取帮助

2. 环境变量与安全：

   # 在启动AgentForge前设置环境变量 export TELEGRAM_BOT_TOKEN="你的BotToken" # 强烈建议设置白名单，限制可操作Bot的用户，避免被滥用 export TELEGRAM_ALLOWED_USERS="你的用户ID,同事的用户ID" # 如何获取用户ID？先不设白名单，给Bot发条消息，然后访问： # https://api.telegram.org/bot<YourBOTToken>/getUpdates # 在返回的JSON中找到"from":{"id":123456789}，这个数字就是用户ID。

3. 高级命令用法： Telegram Bot支持自然语言解析。AgentForge的通道实现通常会将/newtask后的所有文本作为提示词。但你可以设计更结构化的输入。

   • 基础用法：/newtask 审查登录模块的代码
   • 带标题和目录（如果通道支持）：一些实现允许用|或换行分隔不同字段。你需要查看channels/telegram.py的具体实现。理想格式可能是：

     /newtask 标题：每日安全扫描 目录：~/projects/auth-service 提示：运行安全静态分析工具，检查是否有新的依赖漏洞。

   • 实际体验：在Telegram中直接发送“帮我看看上周末的提交有没有引入性能问题”，Bot将其转化为一个任务，几分钟后返回一个包含分析结果的链接，这种体验非常流畅。

飞书/钉钉集成的特殊优势： 对于国内团队，飞书集成的优势在于它使用WebSocket长连接，不需要公网IP或内网穿透。Bot可以运行在完全内网的环境中，只要它能访问飞书服务器即可。配置过程虽然需要在飞书开放平台创建应用、配置权限，但一旦完成，稳定性很高。

通道使用心得：我建议为不同类型的任务创建不同的聊天命令或关键词。例如，在Slack中，可以设置一个/codereview快捷命令，其背后固定了working_dir和一部分提示词模板，用户只需要输入PR号或分支名即可。这需要对通道的代码进行一些定制，但能极大提升使用体验。

4.3 多代理管道（DAG）：构建自动化AI工作流

这是AgentForge最强大的概念。它不仅仅是任务的简单队列，而是允许任务之间建立依赖关系，形成有向无环图（DAG）。

1. 技能（Skill）安装与原理：要让Claude Code能够创建AgentForge任务，你需要将项目中的skills/agentforge/目录链接到Claude Code的技能目录。

# 找到你的Claude Code技能目录，通常是 ~/.claude/skills ln -s /path/to/agentforge/skills/agentforge ~/.claude/skills/agentforge

这个技能本质上是一个Claude Code能理解的“插件”，它向Claude Code暴露了一组新的命令或能力。当Claude Code在执行任务时，如果它“决定”需要将工作拆解或委派，它就可以调用这个技能提供的功能，通过HTTP请求与本地运行的AgentForge后端通信，创建新的子任务。

2. 设计一个DAG工作流：假设我们有一个复杂任务：“为项目重构用户认证模块”。

• 手动创建初始任务（Task A）:

  curl -X POST http://localhost:9712/api/tasks \ -d '{ "title": "重构认证模块-总控", "prompt": "你是一个资深架构师。请分析 ~/projects/myapp 中的用户认证模块（位于 `src/auth/`）。你的目标是制定一个安全的、模块化的重构方案。请按以下步骤执行：1. 首先，创建一个子任务（Task B）来详细分析当前认证代码的所有安全漏洞和设计缺陷。2. 然后，创建一个子任务（Task C）来调研并推荐适合本项目的前沿认证方案（如OAuth 2.1、Passkey）。3. 最后，创建一个子任务（Task D），它依赖于B和C的完成，来生成最终的重构技术方案和PRD。请使用你内置的agentforge技能来创建这些子任务，并为它们建立正确的依赖关系。", "working_dir": "~/projects/myapp", "schedule_type": "immediate", "agent": "claude" }'

• AI驱动的子任务创建: Task A开始运行后，Claude Code会读取提示词，理解到它需要创建三个子任务。它会调用agentforge技能，发送类似如下的请求到AgentForge的API：

  # Claude Code内部调用（模拟） POST /api/tasks {"title": "安全分析", "prompt": "分析~/projects/myapp/src/auth/目录下的代码，找出所有安全漏洞...", "working_dir":"~/projects/myapp", "schedule_type":"immediate"} POST /api/tasks {"title": "技术调研", "prompt": "调研OAuth 2.1和Passkey...", "working_dir":"~/projects/myapp", "schedule_type":"immediate"} POST /api/tasks {"title": "生成重构方案", "prompt": "基于安全分析和技术调研的结果，生成重构方案...", "working_dir":"~/projects/myapp", "schedule_type":"immediate", "depends_on": ["<task_b_id>", "<task_c_id>"]}

  关键参数depends_on： 这个字段包含了Task D所依赖的父任务ID列表。AgentForge的调度器会监控这些父任务的状态，只有当它们全部成功完成时，Task D才会被放入就绪队列。

• 结果注入（--inject-result）: 在创建依赖任务时，可以使用--inject-result标志。这告诉AgentForge，将父任务的输出内容，自动添加到子任务提示词的开头。这样，子任务的Claude Code实例就能直接看到父任务的分析结果，无需手动复制粘贴，实现了上下文的无缝传递。

3. 实际应用场景举例：

• 自动化测试生成流水线:

  1. Task 1: 分析指定目录的代码变更（git diff）。
  2. Task 2 (依赖Task 1): 根据变更内容，为受影响的功能模块生成单元测试用例。
  3. Task 3 (依赖Task 2): 运行生成的测试，并报告通过率。
  4. Task 4 (依赖Task 3): 如果测试失败，分析失败原因并尝试修复或生成问题报告。

• 多语言代码翻译与同步:

  1. Task 1: 提取项目中的英文UI文本字符串。
  2. Task 2, Task 3, Task 4 (并行，都依赖Task 1): 分别调用AI将英文翻译成中文、日文、韩文。
  3. Task 5 (依赖Task 2,3,4): 将所有翻译结果合并，并生成对应的i18n资源文件。

DAG设计心法：设计DAG时，要遵循“单一职责”原则。每个任务应该只做一件定义明确的事情。任务间的依赖要清晰，避免循环依赖。合理利用并行任务（没有依赖关系的任务）可以显著缩短总流程时间。同时，要为关键路径上的任务设置更详细的提示词和更严格的超时机制。

5. 后台服务、监控与故障排查

对于需要7x24小时运行定时任务或聊天机器人的用户，将AgentForge作为后台服务运行是必须的。

5.1 配置LaunchAgent实现开机自启

README中提供了LaunchAgent的plist文件模板。这里补充一些关键细节和优化选项：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>com.agentforge.taskboard</string> <key>ProgramArguments</key> <array> <!-- 关键点1：使用uv的绝对路径，避免环境变量问题 --> <string>/usr/local/bin/uv</string> <string>run</string> <!-- 关键点2：使用taskboard.py的绝对路径 --> <string>/Users/你的用户名/Code/agentforge/taskboard.py</string> </array> <key>WorkingDirectory</key> <!-- 关键点3：工作目录设置为项目根目录，确保相对路径（如.db文件）正确 --> <string>/Users/你的用户名/Code/agentforge</string> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <dict> <!-- 关键点4：配置更智能的保活策略 --> <key>SuccessfulExit</key> <false/> <!-- 即使成功退出也重启，适用于定时任务服务 --> <!-- <key>Crashed</key> <true/> 默认就是true --> </dict> <key>StandardOutPath</key> <string>/tmp/agentforge.log</string> <key>StandardErrorPath</key> <string>/tmp/agentforge.err</string> <key>EnvironmentVariables</key> <dict> <!-- 关键点5：在这里设置所有需要的环境变量！ --> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> <key>TELEGRAM_BOT_TOKEN</key> <string>你的Token</string> <key>TELEGRAM_ALLOWED_USERS</key> <string>你的用户ID</string> <!-- 如果使用Codex，也需要设置OPENAI_API_KEY --> </dict> </dict> </plist>

配置与管理的常用命令：

# 1. 将plist文件放到正确的位置 cp com.agentforge.taskboard.plist ~/Library/LaunchAgents/ # 2. 加载服务（立即生效，并在下次登录时自动启动） launchctl load ~/Library/LaunchAgents/com.agentforge.taskboard.plist # 3. 查看服务状态 launchctl list | grep agentforge # 4. 查看实时日志（一个终端窗口持续监控） tail -f /tmp/agentforge.log # 5. 停止服务 launchctl unload ~/Library/LaunchAgents/com.agentforge.taskboard.plist # 6. 在修改plist文件后，需要先unload再load才能生效

5.2 常见问题与排查实录

即使配置正确，在实际运行中也可能遇到各种问题。以下是我在长期使用中总结的“排错清单”：

问题1：任务创建成功，但一直处于queued状态，不执行。

• 可能原因A：调度器线程未启动或卡住。
  • 排查：查看日志/tmp/agentforge.log，搜索“Scheduler started”或“Polling”字样。如果没有，可能是后端启动失败。
  • 解决：检查Python依赖是否完整（uv sync），端口9712是否被占用。
• 可能原因B：任务计划时间未到。检查任务的schedule_type和next_run_time。如果是cron任务，确认cron表达式解析正确。
• 可能原因C：依赖任务未完成。如果任务设置了depends_on，请检查其依赖的所有父任务是否都已成功（succeeded）。

问题2：任务状态很快变为failed，但没有输出。

• 可能原因A：AI代理CLI（claude/codex）未安装或不在PATH中。
  • 排查：在终端中直接运行claude --help，看是否报错。LaunchAgent的环境变量PATH可能和你的终端不同。
  • 解决：在plist的EnvironmentVariables中显式设置PATH，或使用AI CLI的绝对路径（需要修改taskboard.py中的AgentExecutor）。
• 可能原因B：工作目录（working_dir）不存在或无权限。
  • 排查：查看/tmp/agentforge.err错误日志，通常会有FileNotFoundError或权限错误。
  • 解决：确保working_dir是绝对路径，且运行AgentForge的用户对该目录有读写权限。
• 可能原因C：AI API调用失败（配额不足、网络错误）。
  • 排查：查看任务的具体输出。Claude Code或Codex CLI通常会返回详细的错误信息。
  • 解决：检查API密钥、网络连接，或等待配额重置。

问题3：聊天机器人（如Telegram Bot）不响应消息。

• 可能原因A：环境变量未正确设置。
  • 排查：确认启动AgentForge的进程环境中确实有TELEGRAM_BOT_TOKEN等变量。可以在taskboard.py开头加一句print(os.environ.get('TELEGRAM_BOT_TOKEN'))来调试。
  • 解决：如前所述，在LaunchAgent的plist中设置环境变量是最可靠的方式。
• 可能原因B：Bot未启动或通道初始化失败。
  • 排查：查看启动日志，搜索“Telegram channel started”或相应的错误堆栈。
  • 解决：Token格式是否正确？网络是否能访问Telegram API？对于飞书，检查App ID和Secret是否正确，以及是否开启了“企业自建应用”等权限。

问题4：前端看板无法连接或显示空白。

• 可能原因A：Python后端服务未运行。
  • 排查：在浏览器中访问http://127.0.0.1:9712/api/health，看是否返回{"status": "ok"}。
  • 解决：启动后端服务。
• 可能原因B：Electron前端连接的端口不对。
  • 排查：检查Electron开发者工具（Ctrl+Shift+I）中的Console和Network标签页，看是否有连接错误。
  • 解决：确保taskboard-electron中的API地址配置正确（开发模式下通常是localhost:9712）。

问题5：数据库文件损坏或增长过快。

• 现象：应用启动报错，或运行越来越慢。
• 解决：

  # 1. 备份当前数据库 cp ~/.agentforge/tasks.db ~/.agentforge/tasks.db.backup # 2. 尝试修复（SQLite命令） sqlite3 ~/.agentforge/tasks.db "PRAGMA integrity_check;" # 3. 如果数据不重要，可以删除旧文件，重启应用会自动创建新库 rm ~/.agentforge/tasks.db

  对于输出日志过多导致数据库过大的问题，可以考虑定期归档或清理旧任务记录。这需要手动执行SQL或编写一个清理脚本作为定时任务。

5.3 性能调优与稳定性建议

1. 调整调度器轮询间隔：默认每2秒轮询一次数据库对于大多数场景足够了。如果任务非常多（上千个），可以适当增加间隔以减少数据库压力。修改taskboard.py中的TaskScheduler类的POLL_INTERVAL。
2. 限制并行任务数：默认情况下，AgentForge可能会同时运行多个任务。如果机器资源有限，或者AI API有并发限制，可以在AgentExecutor中实现一个信号量（Semaphore）来限制最大并发数。
3. 为长时间任务设置超时：在创建任务时，可以增加一个timeout_seconds字段，并在AgentExecutor中实现超时控制，防止某些任务卡死占用资源。
4. 日志轮转：/tmp/agentforge.log文件会一直增长。可以使用系统的logrotate工具或简单的cron job来定期压缩和清理旧日志。
5. 监控与告警：虽然AgentForge本身没有告警功能，但你可以写一个简单的脚本，定期调用/api/health接口，或者检查日志中是否有大量ERROR，然后通过邮件、Slack等方式通知自己。

6. 扩展与定制开发指南

AgentForge的架构设计使其具有良好的可扩展性。如果你不满足于现有功能，可以对其进行定制。

6.1 添加新的聊天通道

假设你想添加Discord通道支持。

1. 在channels/目录下创建新文件，例如discord_channel.py。
2. 实现一个类，继承自基础的Channel类（如果存在），或者实现统一的接口。核心是实现start()、stop()和消息处理逻辑。

   # channels/discord_channel.py import os import discord from discord.ext import commands class DiscordChannel: def __init__(self, callback): self.callback = callback # 用于将收到的消息回调给主程序 self.token = os.getenv('DISCORD_BOT_TOKEN') self.allowed_channels = os.getenv('DISCORD_ALLOWED_CHANNELS', '').split(',') self.bot = commands.Bot(command_prefix='!') async def on_message(self, message): if message.author == self.bot.user: return # 检查是否来自允许的频道 if str(message.channel.id) not in self.allowed_channels: return # 处理命令，例如 !newtask 标题 | 提示 if message.content.startswith('!newtask'): _, args = message.content.split(' ', 1) title, prompt = args.split('|', 1) # 调用回调函数，创建任务 task_id = self.callback(title.strip(), prompt.strip()) await message.channel.send(f'Task created: {task_id}') def start(self): @self.bot.event async def on_ready(): print(f'Discord bot logged in as {self.bot.user}') self.bot.run(self.token) def stop(self): # 实现优雅关闭 pass

3. 在主程序taskboard.py中注册这个通道。找到通道初始化的地方（可能是一个ChannelManager），添加对新通道的加载逻辑，通常是通过环境变量开关。

   # 在 taskboard.py 中 if os.getenv('DISCORD_BOT_TOKEN'): from channels.discord_channel import DiscordChannel discord_channel = DiscordChannel(create_task_callback) discord_channel.start() channels.append(discord_channel)

4. 配置环境变量并测试。

   export DISCORD_BOT_TOKEN='your.discord.token' export DISCORD_ALLOWED_CHANNELS='123456789012345678' uv run taskboard.py

6.2 开发新的AI代理后端

除了Claude Code和OpenAI Codex，你可以集成任何提供命令行接口的AI代码助手。

1. 研究目标CLI：了解其如何调用、如何传递提示词、工作目录、如何捕获输出和退出码。
2. 在AgentExecutor类中添加新的代理类型。通常这里会有一个if-elif逻辑分支。

   class AgentExecutor: def execute(self, task): if task.agent == 'claude': cmd = ['claude', '--skill', 'agentforge', task.prompt] elif task.agent == 'codex': cmd = ['codex', '--prompt', task.prompt] elif task.agent == 'your_new_agent': # 实现新的命令行构造逻辑 cmd = ['your_agent_cli', '--model', 'special', '--input', task.prompt] else: raise ValueError(f"Unsupported agent: {task.agent}") # ... 通用的子进程执行和输出捕获逻辑 ...

3. 在任务创建API和前端UI中暴露这个新选项。需要修改API的请求验证逻辑和前端的任务创建表单。

6.3 修改前端看板样式与功能

前端代码位于taskboard-electron/src/renderer/目录下，使用React开发。

• 修改UI样式：直接编辑App.jsx中的JSX和CSS（可能是内联样式或单独的CSS文件）。例如，你可以改变任务卡片的颜色、调整列宽、添加动画效果。
• 添加新功能：比如，你想在看板上增加一个“批量重试失败任务”的按钮。
  1. 在App.jsx中增加一个按钮。
  2. 为这个按钮添加点击事件处理函数。
  3. 在处理函数中，调用后端的POST /api/tasks/:id/retry接口（可能需要循环调用）。
  4. 更新前端状态，刷新任务列表。
• 添加新的任务筛选或排序：目前前端可能只展示了所有任务。你可以增加一个下拉菜单，让用户按状态、创建时间、代理类型等进行筛选。这需要修改前端的状态管理和对GET /api/tasks接口的调用方式（可能需要后端支持查询参数）。

开发工作流建议：由于是Electron应用，修改前端代码后，在开发模式下（npm start）会自动热重载。修改Python后端代码后，需要重启uv run taskboard.py进程。建议使用nodemon或watchdog等工具监控taskboard.py文件变化并自动重启，提升开发体验。

# 安装nodemon (全局或项目内) npm install -g nodemon # 使用nodemon运行Python后端，监控.py文件变化 nodemon --exec "uv run taskboard.py" --watch *.py

经过以上从安装、配置、核心功能使用到高级定制、故障排查的完整梳理，相信你已经对AgentForge这个强大的AI代理编排工具有了深入的理解。它的魅力在于将离散的AI能力通过“任务”这个抽象组织起来，赋予了自动化、流程化和可视化的可能。无论是简单的定时脚本，还是复杂的多代理决策流水线，它都能提供一个坚实而灵活的基础。剩下的，就是发挥你的想象力，去构建属于你自己的AI增强工作流了。如果在使用中遇到任何问题，回顾一下第5节的排查清单，或者直接去项目的Git仓库寻找答案和灵感。