教程：你的第一个真实任务
快速开始让你在五分钟内完成安装并开始聊天。本教程是下一步：一次亲手实践，走一遍 ADHDev 真正用来做什么 —— 运行一个真实的编码代理，掌控它所做的事，并（可选地）通过 Repo Mesh 跨机器协调工作，让 Refinery 把它落地到 main。
你将全程亲手操作，以便看到每个部分如何运作。到最后，你会理解 ADHDev 为你提供的四件事 —— Refinery、任意代理、你的机器、远程控制 —— 不是作为一堆要点，而是通过亲自驱动它们。
你需要什么
- 已安装
adhdevCLI（若未安装，参见快速开始）。 - 在你的机器上至少安装并认证了一个 CLI 代理 —— Claude Code、Codex CLI、Gemini CLI 或其他。ADHDev 不管理代理自己的登录；代理各自保留自己的认证。
- 一个你愿意让代理做小改动的 git 仓库。
整个教程在 Standalone 模式（无账户）下工作。结尾的 Repo Mesh 部分是仅 Cloud —— 它有清晰标注，而在它之前的一切都是自包含的。
步骤 1 —— 启动 standalone 并打开仪表板
adhdev standalone这会同时启动内嵌守护进程（localhost:3847）和本地仪表板（localhost:3000）。打开 http://localhost:3000。
你会看到： 仪表板中你的本地机器列为 online。没有登录界面 —— standalone 完全在本地。
📸 [截图：standalone 仪表板，一台机器在线，空会话列表]
为什么重要： 这就是控制平面。从这里开始代理所做的一切 —— 聊天、工具调用、批准 —— 都在这个浏览器和你的守护进程之间点对点流动。仪表板是你对每个会话的单一视图，稍后它就会有一个会话可展示。
检查
如果仪表板为空或机器显示离线，请在另一个终端运行 adhdev doctor。它会检查守护进程进程、本地连接和提供方注册表，并指出具体的修复方法。
步骤 2 —— 查看 ADHDev 能驱动什么
启动前，先看看这台机器上检测到什么：
adhdev detect你会看到： 一个已知提供方的列表，带有 installed: yes/no。任何 yes 的都可以启动。
为什么重要： 提供方是 ADHDev 针对某个代理的适配器，共有四种 —— 你会在这里从第一种中选择：
| 类别 | 传输 | 示例 |
|---|---|---|
| cli | PTY（终端） | Claude Code、Codex CLI、Gemini CLI、Hermes CLI |
| ide | Chrome DevTools Protocol | Cursor、VS Code、Windsurf、Kiro、PearAI、Trae |
| extension | CDP webview | Antigravity |
| acp | stdio（Agent Client Protocol） | ACP 兼容代理 |
在本教程中我们使用一个 cli 提供方 —— 它是通往一个可用会话最快的方式，且无需重新启动编辑器。
步骤 3 —— 启动一个 CLI 代理会话
选择一个显示 installed: yes 的 CLI 代理。例如：
adhdev launch claude # Claude Code
# 或：adhdev launch codex / adhdev launch gemini守护进程在 PTY 下启动代理，并把终端流式传输到仪表板。
你会看到： 仪表板中出现一张新的会话卡片。点击它以打开一个底部带输入框的实时终端视图。
📸 [截图：会话卡片 + 带输入框的已打开终端视图]
为什么重要： 代理运行在你的机器上、你的工作目录中、用它自己的认证 —— ADHDev 只是给你一个窥视它的窗口。代理的行为没有任何改变；你只是在其之上加了一个控制平面。
工作目录
会话在你启动它的目录中运行。把它指向你想让代理工作的 git 仓库 —— 要么在 adhdev launch 之前 cd 到那里，要么从仪表板的启动流程中打开该仓库。
步骤 4 —— 聊天，并掌控批准
在会话的输入框中，让代理做一件小而真实的事。例如：
查看这个仓库，并在 README 顶部添加一行描述，说明它是做什么的。
像在本地终端里一样输入并按 Enter。
你会看到：
- 代理的响应实时流式传输到仪表板 —— 与你在本地终端中看到的相同 token。
- 当代理想运行某个工具或编辑某个文件时，会出现一个带 Approve 和 Reject 按钮的 ACTION REQUIRED 横幅。
📸 [截图：带 Approve / Reject 的 ACTION REQUIRED 批准横幅]
点击 Approve 让编辑通过（或点击 Reject 拒绝它）。该决定通过点对点通道传到守护进程，代理继续。
为什么重要： 这就是人在环路中的控制。代理绝不会悄悄运行一个你没看到的命令 —— 每一次工具调用和文件编辑都会作为你拥有的批准浮现出来。正是这个横幅让你可以离开键盘却仍然掌控全局，而这恰恰是下一步所构建的基础。
附加图片
聊天输入接受图片附件（最多 5 张图片，每张 10 MB）—— 便于粘贴一个 bug 的截图或你想让代理匹配的设计。
步骤 5 —— 从手机批准（Cloud）
步骤 4 中的批准横幅并不与代理运行所在的机器绑定。在云端模式下，用手机浏览器在 adhf.dev 登录，同样的 Approve / Reject 横幅会在那里出现 —— 响应式布局，相同的点对点批准流程。
📸 [截图：移动端批准横幅]
你会看到： 一个代理在你桌前的某个工具调用上暂停；批准出现在你的手机上；你点按 Approve；代理继续。
为什么重要： 你可以启动长时间运行的工作然后离开。代理会在每个决策点停下并等待你，无论你在哪里。（手机接收并回应批准；分派新任务仍然是桌面/CLI 操作。）
步骤 6 —— 用 Repo Mesh 跨机器协调（Cloud）
仅 Cloud
Repo Mesh 协调同一账户的多个守护进程，仅在 Cloud 版本中可用。它是单个仪表板之上的一层 —— 一个协调者把工作交给多台机器（或多个隔离工作树）上的代理并收敛结果。概念请参见完整的 Repo Mesh 指南；这里我们只连接一个。
到目前为止你在一个会话中驱动了一个代理。Repo Mesh 就是把这变成一个人协调许多代理的东西。下面是最小的端到端版本。
1. 为你的仓库创建一个 mesh。 在仓库内部（以便自动检测 git 远程）：
adhdev mesh create my-project --add-current--add-current 还会把你当前的工作区注册为该 mesh 的第一个节点。该命令会打印一个 mesh ID（例如 mesh_abc123）。
你会看到： 一条确认信息，包含 mesh ID、检测到的仓库身份和分支，随后是“后续步骤”提示。
2. 添加另一个节点。 在第二台机器上（或作为一个隔离工作树），把它添加到同一个 mesh。工作树可防止并行代理踩踏彼此的工作树：
adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli--provider-priority 告诉节点当某个任务未指定代理时该启动哪个代理 —— 未设置优先级的节点会拒绝自动启动，而不是去猜测。
3. 确认 mesh 的形态。
adhdev mesh show mesh_abc123 # 节点、策略、每个节点的启动就绪状态
adhdev mesh status mesh_abc123 # 实时的每个节点 git 健康状况（分支、脏、领先/落后）📸 [截图：adhdev mesh status 输出，节点带分支 + clean/dirty]
为什么重要： 现在你有不止一个工作区注册在一个协调者之下。从云端仪表板的 Repo Mesh 页面（/mesh），你针对一个任务群入队任务，然后空闲节点自主拉取工作 —— 一个节点上运行 Claude Code，另一个上运行 Codex。你不会把一个任务推送给某台特定机器再盯着它；快速的空闲节点会清空队列，协调者监视完成事件而不是轮询。每个任务经历 pending → assigned → completed（或 failed）。
步骤 7 —— 让 Refinery 落地工作（Cloud）
仅 Cloud
Refinery 作为 Repo Mesh 收敛的一部分运行。
生成并行代理是容易的部分。合并它们产出的东西才是难的部分 —— 而这正是 ADHDev 存在的意义。
当一个任务在隔离的工作树分支上完成时，Refinery 会把该分支收敛回其基线，从不 force-push。它运行一系列关卡：加载仓库的收敛配置，引导工作树，运行你仓库自身的验证（类型检查 / 测试 / lint），应用一个 no-op 守卫和一次补丁等价性检查，发布任何子模块提交，向基线执行一次仅 fast-forward 的合并，并清理工作树。
每个被触及的分支都恰好落入一个最终状态，因此不会有任何东西被悄悄留在游离分支上：
| 最终状态 | 含义 |
|---|---|
merged_to_main | 已收敛并干净合并。 |
pushed_feature_branch_needs_merge | 已推送，等待你去执行合并。 |
blocked_review | 保留待人工处理 —— 例如子模块提交尚无法从子模块的 origin 到达。 |
cleanup_candidate | 工作已落地；工作树可被移除。 |
not_mergeable | 无法 fast-forward。Refinery 会拒绝并请求你处理，而不是盲目解决冲突。 |
📸 [截图：以 merged_to_main 结束的 Refinery 收敛日志]
为什么重要： 这就是“十个代理运行了”和“十个分支安全落地了”之间的区别。Refinery 是 git 原生的，并且有意保守 —— 它针对你的关卡验证，并且只做 fast-forward。任何它无法干净落地的东西（真实的冲突、无法到达的子模块提交）都会作为 not_mergeable 或 blocked_review 返回给你，而非一次悄悄的合并。你获得并行性，而没有合并日的宿醉。
你刚刚做了什么
你通过 ADHDev 运行了一个真实的代理，并全程保持掌控：
- 远程控制 + HITL —— 你从仪表板驱动了一个实时会话，并批准了每一次工具调用（在云端模式下从你的手机）。
- 任意代理 —— 你通过一个提供方适配器启动了一个 CLI 代理；同样的流程适用于 Codex、Gemini、通过 CDP 的 IDE 以及 ACP 代理。
- 你的机器 —— 代理运行在你自己的硬件上，用它自己的认证，在你的仪表板之下。
- Refinery —— （云端）你把节点注册进一个 mesh，并看到已完成的工作如何通过验证关卡收敛到
main，且每个分支都有清晰的最终状态。