CLI 代理
CLI 代理是 ADHDev 的主要工作流之一。目前 ADHDev 在目录中提供 8 个内置 CLI 提供方。在提供方于目标机器上被启用并检测到后，它们通过守护进程的 PTY/session-host 层运行，因此你可以观看终端输出、从仪表板输入，并在桌面或移动端持续推进会话。
WARNING
内置并不意味着已验证的支持。除非某个提供方在兼容性文档中被明确提升，否则请将其视为未验证。验证状态目前正处于全面重新验证阶段 —— 参见支持的提供方。
内置 CLI 提供方
| 代理 | 命令 | 验证情况 | 说明 |
|---|---|---|---|
| Antigravity CLI | adhdev launch antigravity-cli | 未验证 | Google 的 Antigravity 终端代理 |
| Claude Code | adhdev launch claude | 未验证 | Anthropic 的 Claude 编码代理 |
| Codex CLI | adhdev launch codex-cli | 未验证 | OpenAI 的 Codex 终端代理 |
| Cursor CLI | adhdev launch cursor-cli | 未验证 | Cursor 的终端代理工作流 |
| Grok CLI | adhdev launch grok-cli | 未验证 | xAI 的 Grok 终端代理 |
| Kimi | adhdev launch kimi | 未验证 | Moonshot 的 Kimi 编码代理 |
| OpenCode CLI | adhdev launch opencode | 未验证 | 开源终端编码代理 |
想要接入表中没有的 CLI 代理？参见 自定义提供方，了解如何通过提供方清单自行添加。
CLI 为何重要
CLI 代理往往是持续推进工作的最快方式，因为它们：
- 紧贴你的仓库和 shell 工作流
- 在远程终端控制下运行良好
- 避免 IDE 特有的 UI 损坏
- 让 ADHDev 流式传输精确的终端会话，而非重建的抽象
如果你想要当下最可靠的远程工作流，CLI 代理通常是首先要验证的路径。各个提供方的验证状态目前正在重新进行 —— 在依赖某个特定提升之前，请到支持的提供方查看当前状态。
启动一个 CLI 代理
# 稳健的默认路径
adhdev daemon
adhdev launch claude
adhdev launch codex-cli
adhdev launch cursor-cli
# 额外的内置 CLI 提供方
adhdev launch antigravity-cli
adhdev launch grok-cli
adhdev launch kimi
adhdev launch opencode启动前，请确保该提供方已在机器的 Providers 标签页中启用，并且对已配置的可执行文件 Detect 成功。如果二进制文件安装在默认 PATH 之外，请先在那里设置自定义可执行文件路径/参数。
守护进程用 PTY 生成 CLI 进程，把输出流式传输到仪表板，并把你的输入转发回进程。
普通启动被视为全新会话。如果你想要连续性，请使用显式的恢复路径，如历史或托管运行时恢复，而不是依赖隐式的自动恢复。
WARNING
每个 CLI 工具各自处理自己的认证。ADHDev 管理 PTY 会话和远程控制层，而不是上游工具的登录流程。
文件夹信任预授权
kimi、grok-cli、codex-cli、claude-cli 和 antigravity-cli 会向 ADHDev 注册一个文件夹信任方案，因此在新目录中的首次启动会跳过该工具的一次性“是否信任此文件夹？”提示，而不会卡在那里。信任是使用该工具在你首次交互式批准时自己会写入的同一个信任存储预先授予的。
终端工作流
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 代理都支持通过仪表板齿轮按钮配置的设置：
| 设置 | 说明 |
|---|---|
| 通知 | 显示状态变更通知 |
| 自动批准 | 在支持的地方自动批准工具执行 |
| 批准提醒 | 需要批准时通知 |
| 无进展提醒 | 当一个轮次长时间没有进展时发出警告（原名“长时间生成提醒”） |
| 无进展阈值 | 无进展提醒触发前的秒数阈值 |
自动批准模式（1.0.60+）
除了上面单一的开/关“自动批准”开关外，现在每个内置 CLI 提供方都声明了自己的一组启动时自动批准模式 —— 这是启动会话时显示的选择器，而不是齿轮按钮设置。每种模式都带有风险等级，让你在启动前就知道自己开启了什么：
| 风险 | 含义 |
|---|---|
| 安全 | 交互式 PTY 解析 —— ADHDev 回答它能识别的提示；在工具层面不会绕过任何内容 |
| 谨慎 | 传递提供方自己的“接受编辑”/“自动”标志 —— 更广泛的自动接受，但仍限定在该提供方范围内 |
| 危险 | 提供方完整的权限绕过标志（例如 Claude Code 的 --permission-mode bypassPermissions、kimi 的 --auto）—— 代理运行命令时完全不提示。ADHDev 在以此模式启动前会显示确认对话框。 |
可用模式因提供方而异（它们来自该提供方自己的 CLI 标志），默认始终是安全的交互模式。
模型发现（1.0.60+）
模型选择器的列表根据提供方以不同方式发现：
| 方式 | 提供方 |
|---|---|
| 在运行时执行该 CLI 自己的模型列出命令 | codex-cli、grok-cli、cursor-cli、antigravity-cli、opencode |
| 读取提供方的本地配置文件 | kimi |
claude-cli 的模型选项（opus/sonnet/haiku/fable）是稳定的别名，而非会漂移的版本化短标识，因此不会像被发现的列表那样漂移。
用量报告
adhdev quota <provider> 打印某个提供方当前的用量读数。adhdev quota refresh [providers...] 要求正在运行的守护进程实际重新获取并更新其缓存读数（路由和仪表板读取的正是这份数据），同时遵守任何生效中的速率限制冷却。
用量报告适用于：claude-cli、codex-cli、kimi、opencode、grok-cli、cursor-cli、antigravity-cli（全部 7 个内置 CLI）。
故障排除
代理无法启动
- 确认工具已在本地安装
- 在机器的 Providers 标签页中启用该提供方并运行 Detect
- 如果二进制文件在默认 PATH 之外，请设置自定义可执行文件路径/参数
- 检查上游认证或 API 密钥
- 使用
adhdev daemon:status检查本地健康状况
终端为空白
- 工具可能正在等待输入
- 在仪表板中检查连接状态
- 在启动重复会话之前，检查隐藏标签页、收件箱和历史
- 如果运行时幸存，请通过 Hosted Runtimes 恢复它，而不是立即重新启动
终端输出看起来不对
- 如果上游工具让终端处于不良状态，请重启会话
- 把终端视图视为 CLI 提供方的权威输出
- 如果问题持续，请将其视为提供方兼容性问题，并首先查看兼容性页面
会话显示批准提示但没有可批准的内容（1.0.60+）
有些 CLI 会在终端本身之外的步骤上阻塞 —— 最典型的例子是 grok-cli 的浏览器登录。ADHDev 现在在内部将其跟踪为一个独立状态，使这类会话进入你的批准收件箱，而不是被静默地读作空闲或生成中（它在那里显示为一个普通的等待你处理的条目，而非单独的徽章）。完成外部步骤（例如完成浏览器登录）后，会话会正常恢复。