agtx：终端看板系统，实现AI编程代理的自动化编排与协同

1. 项目概述：一个能管理其他AI编程代理的终端看板

如果你和我一样，每天要在Claude Code、Cursor、Codex这些AI编程工具之间来回切换，同时处理多个功能需求，那你一定懂那种混乱感。每个工具一个终端窗口，每个任务一个对话，上下文支离破碎，想法来了只能手动复制粘贴到另一个地方，效率低得让人抓狂。我一直在寻找一个能把这些“单兵作战”的AI代理们组织起来，让它们像一支训练有素的开发团队一样协同工作的工具，直到我遇到了agtx。

agtx 的核心定位非常清晰：它是一个运行在终端里的看板（Kanban）系统，但它的“工人”不是人类，而是你配置的各种AI编程代理。你可以把它想象成一个AI代理的“项目经理”或“调度中心”。你只需要在看板的“待办事项（Backlog）”列里创建一个任务，写好描述，然后按一个键，agtx 就会接管后续的一切：一个“协调者（Orchestrator）”代理会分析这个任务，制定计划，然后将工作委派给运行在不同tmux窗口、不同git工作树中的多个编码代理，让它们并行工作。你可以走开去喝杯咖啡，回来时，任务可能已经推进到了“评审（Review）”列，代码变更已经准备好等你合并了。

更妙的是，它无缝衔接了你的“灵感迸发”时刻。当你在和某个AI代理（比如Claude）深入讨论一个功能时，突然有了新的想法分支，你不需要中断对话、复制文本、打开另一个工具。你只需要输入/agtx:brainstorm命令，让AI帮你自由探索这个想法；当讨论成熟后，再输入/agtx:sweep，agtx 会自动将整个对话的成果分解成具体的任务，并一键推送到看板上。想法直接转化为待办事项，中间没有任何摩擦。

这个工具特别适合独立开发者、小型技术团队负责人，或者任何需要同时管理多个AI辅助编码任务、追求自动化工作流的人。无论你是想用Gemini做前期调研、Claude做核心实现、Codex做代码审查，还是想尝试GSD、Spec-kit等规范驱动开发框架，agtx 都提供了一个统一的、可视化的操作界面和自动化流程。

2. 核心设计理念与架构拆解

agtx 的设计哲学建立在几个关键洞察之上，理解了这些，你就能明白它为何如此强大，以及如何最大限度地利用它。

2.1 核心理念：将AI代理视为可编排的“服务”

大多数AI编码工具的设计是“一个会话解决一个问题”。agtx 颠覆了这一点，它将每个AI代理会话视为一个可以按需调度、有明确生命周期和输入输出的“微服务”。看板上的每一列（Backlog, Planning, Running, Review, Done）对应着这个服务生命周期的不同阶段。通过插件系统，你可以为每个阶段定义精确的“服务契约”：启动时发送什么命令、等待什么产出物（Artifact）、产出后如何同步回主项目。

这种设计带来了几个巨大优势：

1. 并行化：每个任务在独立的git工作树和tmux窗口中运行，互不干扰，真正实现了多任务并行。
2. 状态持久化：任务的完整对话历史、代码变更都保存在其专属的工作树和tmux会话中，你可以随时中断、查看、恢复，上下文永不丢失。
3. 流程标准化：通过插件，你可以将团队的最佳实践（如先写Spec、再TDD、最后Review）固化为自动化流程，确保每个任务都经过相同的质量关卡。

2.2 核心架构：三层分离

agtx 的架构清晰地区分了三个层次，这让它既强大又灵活：

1. 展示层（TUI）：基于Rust的TUI（终端用户界面），提供直观的看板视图。这是你和系统交互的主要入口，负责渲染任务状态、接收键盘指令、展示实时会话。
2. 协调层（MCP Server & Orchestrator）：
   • MCP Server：这是agtx的“大脑”API。它遵循Model Context Protocol标准，将看板的所有操作（创建任务、移动任务、读取内容）暴露为一系列工具（Tools）。这使得任何兼容MCP的AI代理（如Claude Code）都能以编程方式与agtx交互。
   • Orchestrator（协调者代理）：这是一个特殊的AI代理（通常由Claude Code担任），它通过MCP Server“观察”看板。当它发现任务处于“空闲”或“可推进”状态时，会自动调用相应工具来推动任务前进，实现了部分流程的自动化。
3. 执行层（Tmux & Git Worktree）：
   • Tmux服务器：所有AI代理的实际会话都运行在一个名为agtx的独立Tmux服务器中。每个项目对应一个Tmux会话，每个任务对应一个Tmux窗口。这种隔离保证了会话的稳定性和可管理性。
   • Git工作树：每个任务都在一个从基础分支（如main）创建出来的独立Git工作树中执行。这确保了代码变更的隔离性，避免了任务间的污染，也使得合并前的冲突检查变得简单可靠。

实操心得：理解“隔离”的价值刚开始你可能觉得为每个任务创建独立的工作树和Tmux窗口有点“重”。但实际使用后会发现，这是agtx稳定性的基石。它彻底解决了AI编码中常见的“上下文污染”问题——一个任务中生成的临时文件、安装的依赖、甚至AI产生的一些错误假设，都不会影响到其他任务。合并时，你面对的是一个干净、独立的变更集。

2.3 插件系统：工作流引擎

插件（Plugin）是agtx工作流的灵魂。一个插件就是一个plugin.toml配置文件，它定义了：

• 阶段（Phases）：如Research, Planning, Running, Review。
• 每个阶段的命令：进入该阶段时，自动发送给AI代理的命令（如/gsd:plan）。
• 每个阶段的产出物：标志该阶段完成的文件（如plan.md）。agtx会持续轮询，一旦检测到该文件，任务状态就会更新（比如旋转图标变成对勾）。
• 阶段间的依赖关系：通过分析命令和提示词中是否包含{task}占位符，agtx能自动推断哪些阶段可以直接从Backlog进入，哪些阶段必须等待前置阶段完成。

内置的插件如gsd、spec-kit封装了成熟的规范驱动开发流程。你也可以创建自己的插件，将你个人或团队的独特工作方法固化下来。

3. 从零开始：安装、配置与初体验

3.1 系统准备与安装

agtx 是使用Rust编写的，安装非常简单。它依赖两个核心外部工具：

1. Tmux：这是agtx运行代理会话的容器。确保你的系统已安装。macOS用户可通过brew install tmux安装。
2. Git：显然，这是管理代码和创建工作树的基础。

安装agtx本身只需一行命令：

curl -fsSL https://raw.githubusercontent.com/fynnfluegge/agtx/main/install.sh | bash

这条命令会从GitHub下载安装脚本并执行。安装完成后，agtx命令就应该可用了。你也可以选择从源码编译，以获得最新特性：

git clone https://github.com/fynnfluegge/agtx.git cd agtx cargo build --release # 将编译好的二进制文件放到你的PATH中，例如 cp target/release/agtx ~/.local/bin/

3.2 基础配置与项目初始化

agtx 的配置分为全局配置和项目级配置。

全局配置位于~/.config/agtx/config.toml。这里可以设置一些默认值，比如你偏好的AI代理：

# ~/.config/agtx/config.toml default_agent = "claude" # 默认使用Claude Code [agents] # 可以为不同阶段指定不同的代理 research = "gemini" # 调研阶段用Gemini，它可能更擅长信息整合 planning = "claude" # 规划阶段用Claude running = "claude" # 执行阶段用Claude review = "codex" # 审查阶段用Codex，可能更擅长发现代码问题

项目级配置位于你的Git项目根目录下的.agtx/config.toml。这里的设置会覆盖全局配置，更适合定义项目特定的行为。一个非常实用的配置是copy_files：

# .agtx/config.toml # 当为每个任务创建新的工作树时，自动将这些文件从项目根目录复制过去 copy_files = ".env, .env.local, config/database.yml, docker-compose.override.yml"

这个功能解决了AI编码中的一个常见痛点：很多项目依赖环境变量或本地配置文件才能运行。如果没有这个配置，AI代理在新工作树中运行npm start或rails server可能会因为缺少配置而失败。通过预先复制这些文件，你确保了每个任务环境的一致性。

重要提示：添加到.gitignore在你第一次运行agtx的项目中，务必将.agtx/目录添加到.gitignore文件中。因为这个目录下存放着所有任务的工作树和本地数据，不应该提交到版本库。

echo ".agtx/" >> .gitignore

3.3 首次运行与界面导航

进入你的一个Git项目目录，直接运行agtx：

cd /path/to/your/project agtx

你会看到一个基于终端的看板界面，默认分为几列：Backlog, Planning, Running, Review, Done。界面是纯键盘操作的，掌握几个核心快捷键就能流畅使用：

创建你的第一个任务：按o，会弹出一个向导。你需要输入任务标题，选择插件（如果项目里只有一个插件配置，会自动跳过），然后编写详细的任务描述。任务描述是关键，它是AI代理的“需求文档”。写得越清晰，AI的表现越好。你可以使用#或@来模糊搜索并插入文件路径，用/插入技能命令，用!插入对其他任务的引用，这能极大地丰富上下文。

4. 核心功能深度解析与实战技巧

4.1 Brainstorm（头脑风暴）与 Sweep（清扫）技能：无缝捕捉灵感

这是agtx设计中最精妙的特性之一，它完美解决了“灵感记录”与“任务管理”之间的断层。

工作流程：

1. 你正在与Claude Code讨论一个复杂的用户认证模块。
2. 讨论中，你们提到了“是否要支持OAuth2.0”和“如何设计登录日志”这两个衍生话题。
3. 你不想打断当前关于核心认证流程的讨论，但又怕这些好点子稍纵即逝。
4. 此时，你在Claude的输入框中键入：/agtx:brainstorm。
5. AI会进入纯粹的“讨论模式”，它会帮你深入探讨OAuth2.0和登录日志的利弊、技术选型，但不会生成任何代码或具体计划。这就像在白板上自由书写。
6. 讨论充分后，你输入：/agtx:sweep。
7. AI会自动分析刚才的整个“头脑风暴”对话，将其提炼、分解成若干个具体的、可执行的任务（例如：“集成OAuth2.0提供商Google”，“设计登录日志数据库表”，“实现日志查询API”）。
8. agtx会弹出一个确认框，列出它建议创建的任务。你确认后，这些任务就会直接出现在你项目agtx看板的Backlog列中。

安装与集成： 要让这个功能生效，你需要在你使用的AI代理工具中安装agtx的MCP技能。以Claude Code为例：

# 1. 添加agtx插件市场 claude plugin marketplace add fynnfluegge/agtx # 2. 安装agtx插件 claude plugin install agtx@agtx-marketplace # 3. 添加agtx的MCP服务器（全局模式） claude mcp add --scope user agtx -- agtx mcp-serve

完成以上步骤后，在任何Claude Code会话中，你就可以使用/agtx:brainstorm和/agtx:sweep命令了。其他代理如Codex、Gemini CLI、Cursor的安装方式类似，详见项目文档。

实操心得：用好Sweep的确认步骤/agtx:sweep弹出的确认框非常重要。AI的分解不一定总是完美，你可能需要合并一些过于细碎的任务，或者修正一些描述。养成在确认前快速浏览并编辑任务列表的习惯，能节省后续很多调整时间。

4.2 多代理协作与自动切换

agtx允许你为工作流的不同阶段配置不同的AI代理。这背后的逻辑是充分利用不同模型的特长。

配置示例： 假设你在项目配置.agtx/config.toml中如下设置：

[agents] research = "gemini" planning = "claude" running = "claude" review = "codex"

实际运行过程：

1. 你将一个Backlog任务移动到“Planning”列。
2. agtx会为这个任务创建一个新的git工作树和tmux窗口。
3. 然后，它会启动Claude Code，并自动发送规划阶段的命令（例如/gsd:plan）。
4. 当规划完成（检测到规划产出物，如plan.md），你将任务移动到“Running”列。
5. agtx会自动结束Claude的会话，在同一个tmux窗口中启动Claude Code（因为Running阶段也配置为claude），并发送执行命令（如/gsd:execute）。这里虽然代理相同，但上下文（工作树）和阶段指令已切换。
6. 执行完成，移动到“Review”列。
7. agtx会关闭Claude，启动Codex，并发送审查命令。

这一切都是自动的。你只需要在看板上移动任务卡片，agtx负责在背后为你切换代理、发送正确的指令、管理会话生命周期。这实现了真正的“专业化分工”。

4.3 插件系统实战：以GSD插件为例

让我们深入看看内置的gsd(Get Shit Done) 插件是如何工作的。这能帮你理解插件机制的强大。

当你为一个项目选择gsd插件后（按P选择），每个任务的生命周期就被严格定义了：

1. Research (调研)：任务进入此阶段时，AI代理（如Gemini）会收到/gsd:research {task}命令。它会开始调研与任务相关的信息，最终产出物可能是一个research.md文件。
2. Planning (规划)：调研完成后，移动到Planning。AI代理（如Claude）收到/gsd:plan命令。它会基于调研结果，制定详细的实现计划，产出plan.md和可能的spec.md。
3. Running (执行)：规划完成后，移动到Running。AI代理（如Claude）收到/gsd:execute命令。它会根据规划文档开始编写代码，产出最终的代码变更。
4. Review (评审)：执行完成后，移动到Review。AI代理（如Codex）收到/gsd:review命令。它会审查代码变更，提出改进意见，产出review.md。

agtx 在每个阶段都会持续轮询，等待对应的产出物文件出现。一旦检测到，任务卡片上的状态图标就会变化（比如从旋转的加载图标变成绿色的对勾），提示你这个阶段已经完成，可以推进到下一阶段了。

创建你自己的插件： 如果你有一套自己的开发流程，完全可以将其封装成插件。只需在项目根目录创建.agtx/plugins/my-flow/plugin.toml：

name = "my-flow" description = "我的自定义TDD流程" [commands] planning = "/my-flow:write-spec {task}" # 规划阶段：先写测试规范 running = "/my-flow:implement" # 执行阶段：实现并通过测试 review = "/my-flow:refactor" # 评审阶段：重构代码 [artifacts] planning = "specs/{task_id}_spec.md" # 完成标志：生成了规范文件 running = "tests/{task_id}_test.js" # 完成标志：测试文件存在且通过 review = "refactor_report.md" # 完成标志：重构报告 copy_files = ["jest.config.js", "package.json"] # 每个工作树都需要这些文件

将这个插件目录放到~/.config/agtx/plugins/下，就可以在所有项目中使用了。agtx 会自动发现它，并在按P时出现在插件列表中。

4.4 协调者代理（Orchestrator）：让AI管理AI

这是agtx最“未来感”的功能，目前标记为实验性（--experimental）。启动协调者后，你可以从微观任务管理中解放出来。

启动方式：

# 在项目目录中启动agtx并开启实验功能 agtx --experimental

进入TUI后，按O键即可激活协调者代理。

它是如何工作的？

1. 你作为“产品经理”，负责将高层次的“需求”（任务）从Backlog拖拽到Planning或Running列，这相当于“分配任务”。
2. 协调者代理（一个一直在后台运行的Claude Code实例，通过MCP与agtx通信）会持续监控看板。
3. 当它发现某个任务在Planning列完成了规划（检测到plan.md），它会自动调用MCP工具的move_task，将该任务推进到Running列。
4. 同样，当Running列的任务完成执行，它又会将其推进到Review列。
5. 如果某个任务在某个阶段“卡住”了（超过1分钟没有活动且未产出目标文件），协调者会去“查看”那个任务的Tmux窗口内容，尝试诊断问题。它可能会自动发送一个“nudge”（轻推）消息，或者将任务标记为“需要人工介入”，并在看板上显示一个警告标志。

你的角色转变：从“操作员”（手动移动每个任务、触发每个阶段）变成了“监督员”和“决策者”。你只需要在开始时梳理任务，在结束时评审合并。中间的推进、等待、异常处理，都交给了另一个AI去操心。这极大地提升了管理大量并行任务时的效率。

注意事项：协调者的局限性协调者目前还是实验功能。它对于清晰、线性的任务流处理得很好，但对于复杂的、需要大量创造性决策或遇到意外错误的任务，可能还是会需要你手动干预。不要指望它完全取代你的判断，而是把它看作一个强大的自动化助手。

5. 高级配置、问题排查与性能调优

5.1 工作树与分支策略深度配置

agtx 的核心隔离机制依赖于Git工作树。理解其配置能帮你更好地管理代码。

# ~/.config/agtx/config.toml 或 .agtx/config.toml [worktree] # 1. 基础分支配置 base_branch = "develop" # 默认行为：自动检测 main -> master -> 当前分支。 # 明确设置后，所有新任务的工作树都将从 `develop` 分支创建。 # 这在你团队使用 `develop` 作为开发主干时非常有用。 # 2. 工作树目录位置 worktree_dir = ".my-worktrees" # 默认是 `.agtx/worktrees`。你可以修改它，比如你想让工作树目录更明显，或者符合现有项目结构。 # 3. 初始化与清理脚本（项目级配置更常见） # .agtx/config.toml init_script = "scripts/setup_task_env.sh" cleanup_script = "scripts/cleanup_task.sh"

init_script会在每个新工作树创建、且copy_files复制完成后执行。你可以在这里安装特定依赖、启动数据库、运行迁移等。cleanup_script在任务被删除、其工作树移除前执行。适合用来停止临时服务、清理进程。

5.2 常见问题与排查实录

即使工具设计得再好，实际使用中也会遇到问题。以下是我踩过的一些坑和解决方案：

问题1：启动agtx后看不到TUI界面，或者界面乱码。

• 可能原因：终端环境变量或Tmux兼容性问题。
• 排查：
  1. 检查TERM环境变量：echo $TERM。确保它是xterm-256color或tmux-256color。
  2. 尝试在启动agtx前设置：export TERM=xterm-256color。
  3. 如果使用Tmux或Screen，确保在它们内部启动agtx时TERM设置正确。
• 解决方案：在~/.bashrc或~/.zshrc中固定TERM变量，或使用兼容性更好的终端模拟器（如iTerm2, WezTerm）。

问题2：AI代理在工作树中启动失败，提示“command not found”。

• 可能原因：代理CLI（如claude、codex）没有安装在系统PATH中，或者工作树环境与主项目环境不同。
• 排查：
  1. 在主项目终端直接运行claude --version或codex --help，确认命令可用。
  2. 全屏附着到出问题的任务Tmux会话（Ctrl+f），手动尝试运行代理命令。
• 解决方案：
  1. 确保AI代理的CLI工具已正确安装并位于PATH。
  2. 检查项目级copy_files配置，确保没有遗漏代理自身的配置文件（如.claude/config.toml，但注意agtx通常会自动处理这些）。
  3. 在init_script中，可以显式地设置PATH或激活虚拟环境。

问题3：任务卡在某个阶段， spinner一直转，没有变成对勾。

• 可能原因：插件期待的“产出物（Artifact）”文件没有被创建，或者路径不匹配。
• 排查：
  1. 打开任务查看器（回车），看AI代理的最后输出是什么。它可能是在等待你的输入，或者遇到了错误。
  2. 检查工作树目录（如.agtx/worktrees/your-task-name/），看预期的文件（如plan.md）是否已经生成，但文件名或路径与插件配置不符。
  3. 确认你使用的插件阶段命令是否正确触发。例如，gsd插件需要AI执行/gsd:plan才会开始生成计划。
• 解决方案：
  1. 如果AI在等待，在全屏模式下输入所需信息。
  2. 核对插件.toml文件中[artifacts]部分的路径配置。路径是相对于工作树根目录的。
  3. 考虑使用更简单的void插件测试基础功能，排除插件配置问题。

问题4：使用/agtx:sweep时，提示“Project not found”或没有弹出任务确认。

• 可能原因：MCP服务器无法识别当前项目，或者项目尚未被agtx索引。
• 排查：
  1. 确保你已经在目标项目目录中运行过至少一次agtx命令（即使只是打开然后退出）。这会将项目注册到agtx的数据库中。
  2. 运行agtx mcp-serve并保持其运行，然后在另一个终端尝试使用技能。
• 解决方案：总是先通过agtxTUI“打开”一次项目，确保它被索引。对于全局技能调用，这是必要的初始化步骤。

5.3 性能与资源管理建议

• 并发任务数：虽然agtx支持并行运行多个任务，但每个任务都是一个独立的AI代理进程，会消耗显存/内存和API调用额度。请根据你的硬件和API预算合理控制同时处于“Running”状态的任务数量。我通常建议不超过3-5个。
• Tmux会话管理：所有任务都运行在后台的Tmux服务器中。如果遇到agtx异常退出，这些会话可能残留。可以使用tmux -L agtx list-sessions查看，并用tmux -L agtx kill-session -t session-name清理。
• 磁盘空间：每个任务的工作树都是完整的Git仓库副本。对于大型项目，大量任务可能会占用可观磁盘空间。定期使用agtx界面中的x键删除已完成（Done）或不再需要的任务，会同时清理其工作树。
• 数据库位置：agtx的状态数据（任务、看板布局）存储在~/.config/agtx/(Linux) 或~/Library/Application Support/agtx/(macOS)。如果遇到奇怪的UI状态问题，可以尝试退出agtx后备份并删除这个目录（注意：这会丢失所有项目任务数据），然后重新启动。

6. 融入现有工作流：场景化实战指南

agtx 不是一个孤立的工具，它应该融入你现有的开发流程。以下是几个典型场景：

场景一：个人Side Project快速迭代

• 目标：快速验证一个新产品想法，需要频繁添加小功能、修复bug。
• 配置：使用默认的agtx插件或轻量级的void插件。将default_agent设为你最熟悉的工具（如Claude）。
• 流程：
  1. 将大的产品想法拆成用户故事，作为任务放入Backlog。
  2. 每天早上，从Backlog拖2-3个最高优先级的任务到Planning。
  3. 启动协调者（--experimental+O），让它自动推进任务。
  4. 你专注于深度工作（如设计、复杂算法），间歇性查看Review列，合并通过审查的代码。
  5. 在编码中遇到灵感，随时用/agtx:brainstorm和sweep捕获。

场景二：团队规范驱动开发

• 目标：在团队中推行统一的、高质量的开发规范，确保代码风格和架构一致。
• 配置：为项目创建自定义插件，或使用gsd/spec-kit这类强规范插件。在项目级配置中，明确各阶段代理，并配置copy_files包含团队的代码规范、lint配置、测试模板等。
• 流程：
  1. 产品需求（Issue）转化为agtx任务，附带详细的AC（验收标准）。
  2. Planning阶段必须产出详细的设计文档（Spec），由资深工程师或Tech Lead在agtx的Review列进行“设计评审”（通过查看AI生成的plan.md）。
  3. 评审通过后，任务进入Running，AI开始编码，同时必须遵循预设的lint和测试规范。
  4. Running完成后，自动进入Review，另一个AI（或切换为人工）进行代码审查。
  5. 只有Review通过的任务才能合并。整个流程的产出物（Spec、代码、Review意见）都自动保存在工作树中，可作为知识沉淀。

场景三：开源项目贡献管理

• 目标：高效地处理GitHub Issues和PR，特别是作为维护者需要审查大量贡献时。
• 配置：结合GitHub CLI (gh)。可以考虑编写一个简单的脚本，将新的Issue自动同步为agtx的Backlog任务。
• 流程：
  1. 新的Bug报告或功能请求Issue出现。
  2. （手动或自动）在agtx中创建对应任务。
  3. 使用协调者或手动将任务推进。AI可以协助进行初步的Bug复现、提供修复思路、甚至直接生成修复代码。
  4. 在Review阶段，你（维护者）可以非常方便地全屏附着到任务的Tmux会话（Ctrl+f），与AI一起精细调整代码，确保符合项目标准。
  5. 代码满意后，直接从该任务的工作树创建分支并提交PR，关联原Issue。

agtx 的魅力在于它的灵活性。它没有规定你必须怎样工作，而是提供了一套强大的乐高积木（看板、多代理、插件、自动化），让你可以搭建出最适合自己当前项目和团队的工作流。从最简单的“待办事项清单”到复杂的“全自动AI开发流水线”，你可以自由探索和定义。