CLI 代理
CLI 代理是 ADHDev 的主要工作流之一。目前 ADHDev 在目录中提供 7 个内置 CLI 提供方。在提供方于目标机器上被启用并检测到后，它们通过守护进程的 PTY/session-host 层运行，因此你可以观看终端输出、从仪表板输入，并在桌面或移动端持续推进会话。
诸如 Aider、Gemini CLI、GitHub Copilot CLI 和 Goose 之类的代理不是内置 CLI 提供方 —— 它们改为通过 Agent Client Protocol（stdio）连接。这些代理请参阅 ACP 代理指南。
WARNING
内置并不意味着已验证的支持。除非某个提供方在兼容性文档中被明确提升，否则请将其视为未验证。
内置 CLI 提供方
| 代理 | 命令 | 验证情况 | 说明 |
|---|---|---|---|
| Antigravity CLI | adhdev launch antigravity-cli | 未验证 | Google 的 Antigravity 终端代理 |
| Claude Code | adhdev launch claude | 部分 | Anthropic 的 Claude 编码代理 |
| Codex CLI | adhdev launch codex | 部分 | OpenAI 的 Codex 终端代理 |
| Cursor CLI | adhdev launch cursor-cli | 部分 | Cursor 的终端代理工作流 |
| Hermes | adhdev launch hermes-cli | 未验证 | Hermes 编码代理 |
| Kimi | adhdev launch kimi | 未验证 | Moonshot 的 Kimi 编码代理 |
| OpenCode CLI | adhdev launch opencode | 未验证 | 开源终端编码代理 |
CLI 为何重要
CLI 代理往往是持续推进工作的最快方式，因为它们：
- 紧贴你的仓库和 shell 工作流
- 在远程终端控制下运行良好
- 避免 IDE 特有的 UI 损坏
- 让 ADHDev 流式传输精确的终端会话，而非重建的抽象
如果你想要当下最可靠的远程工作流，CLI 代理通常是首先要验证的路径。在当前的公开提升中，Claude Code、Codex CLI 和 Cursor CLI 拥有最清晰的证据。
启动一个 CLI 代理
# 稳健的默认路径
adhdev daemon
adhdev launch claude
adhdev launch codex
adhdev launch cursor-cli
# 额外的内置 CLI 提供方
adhdev launch antigravity-cli
adhdev launch hermes-cli
adhdev launch kimi
adhdev launch opencode启动前，请确保该提供方已在机器的 Providers 标签页中启用，并且对已配置的可执行文件 Detect 成功。如果二进制文件安装在默认 PATH 之外，请先在那里设置自定义可执行文件路径/参数。
守护进程用 PTY 生成 CLI 进程，把输出流式传输到仪表板，并把你的输入转发回进程。
普通启动被视为全新会话。如果你想要连续性，请使用显式的恢复路径，如历史或托管运行时恢复，而不是依赖隐式的自动恢复。
WARNING
每个 CLI 工具各自处理自己的认证。ADHDev 管理 PTY 会话和远程控制层，而不是上游工具的登录流程。
终端工作流
ADHDev 中的 CLI 提供方现在以终端视图作为主要工作流。这意味着终端是以下内容的权威来源：
- 输出和进度
- 批准提示
- 工具执行流程
- 重连和滚动回看行为
终端视图
CLI 代理在仪表板中以一个由 xterm.js 驱动的完整交互式终端呈现：
- 完整 TUI 渲染 —— 颜色、光标移动、进度条和批准提示
- 远程输入 —— 直接从仪表板输入
- 滚动回看恢复 —— 重连后重放 PTY 缓冲区
- 移动友好控制 —— 适合快速批准和轻量监督
会话恢复
CLI 运行时不再被视为一次性的抛弃式启动。ADHDev 保留一个托管运行时层，因此会话通常可以在断开连接或守护进程重启后被恢复。
该恢复路径由操作者驱动：当用户想要连续性时，应显式选择“恢复 / 历史 / 托管运行时恢复”操作。正常的全新启动不应悄悄重新打开较早的会话。
如果某个 CLI 会话从主仪表板消失，请检查：
- 隐藏标签页
- 活动收件箱
- 历史
- 机器的 Hosted Runtimes 标签页
对于命令行恢复，请从主要的面向用户的运行时界面开始：
adhdev runtime list
adhdev runtime attach <runtimeTarget>
adhdev runtime recover <runtimeTarget>
adhdev runtime restart <runtimeTarget>
adhdev runtime snapshot <runtimeTarget><runtimeTarget> 接受会话 ID、运行时键、显示名称，或 adhdev runtime list 中显示的唯一前缀。
如果你更喜欢常见路径上更短的命令，adhdev attach <runtimeTarget> 和 adhdev recover|resume <runtimeTarget> 是指向同一运行时界面的直接快捷方式。
如果你需要底层诊断或显式的操作者控制，请使用：
adhdev daemon:session-host
adhdev daemon:session-host --session <sessionId> --resume
adhdev daemon:session-host --session <sessionId> --restart
adhdev daemon:session-host --prune-duplicates当运行时仍然存在但活动仪表板会话卡住或连接到错误的副本时，这是合适的路径。
历史和恢复的深度仍因提供方而异。一个内置 CLI 可以干净地启动，但在该路径被明确测试之前，其恢复流程仍可能保持 未验证 状态。
代理设置
每个 CLI 代理都支持通过仪表板齿轮按钮配置的设置：
| 设置 | 说明 |
|---|---|
| 通知 | 显示状态变更通知 |
| 自动批准 | 在支持的地方自动批准工具执行 |
| 批准通知 | 需要批准时通知 |
| 长时间生成提醒 | 当一个轮次运行过久时发出警告 |
| 长时间生成阈值 | 以秒为单位的阈值（30–600） |
CLI vs ACP
| 特性 | CLI 代理（PTY） | ACP 代理（stdio） |
|---|---|---|
| 接口 | 完整的终端会话 | 结构化聊天协议 |
| 渲染 | xterm.js / 原始终端 | Markdown / 内容块 |
| 最佳适配 | 真实 shell 工作流、TUI 工具、远程监督 | 具有结构化事件的协议原生代理 |
| 验证模型 | 默认未验证；按提供方逐一验证 | 默认未验证；按提供方逐一验证 |
故障排除
代理无法启动
- 确认工具已在本地安装
- 在机器的 Providers 标签页中启用该提供方并运行 Detect
- 如果二进制文件在默认 PATH 之外，请设置自定义可执行文件路径/参数
- 检查上游认证或 API 密钥
- 使用
adhdev daemon:status检查本地健康状况
终端为空白
- 工具可能正在等待输入
- 在仪表板中检查连接状态
- 在启动重复会话之前，检查隐藏标签页、收件箱和历史
- 如果运行时幸存，请通过 Hosted Runtimes 恢复它，而不是立即重新启动
终端输出看起来不对
- 如果上游工具让终端处于不良状态，请重启会话
- 把终端视图视为 CLI 提供方的权威输出
- 如果问题持续，请将其视为提供方兼容性问题，并首先查看兼容性页面