droid-cli

Droid CLI 目标

协调器已将你路由到此处。在已加载的驱动技能基础上，叠加这些目标专用模式。

Droid 专用快捷键、模式和启动方式。

快捷键

操作	按键组合	结果
切换 Spec 模式	shift tab	开启或关闭 Spec 模式
切换自主级别	ctrl l	Off > Low > Med > High > Off
切换模型	ctrl n	切换可用模型
切换推理级别	tab	High > none > Low > Medium > High
取消 / 关闭 / 停止	esc	停止流式输出，关闭浮层
清除输入	ctrl u	清除当前行
切换 bash 模式	空输入时按 !	在 > 和 $ 之间切换提示符
帮助 / 快捷键	?	打开按键绑定帮助
多行输入	shift enter	插入换行符但不提交

对话框

当对话框显示 Use up/down to navigate... 时：按 up/down 移动高亮项，按 enter 选择，按 esc 关闭。

斜杠命令

命令	用途
/help	显示命令
/settings	打开设置菜单
/model	打开模型选择器
/clear 或 /new	开始新会话
/sessions	浏览先前的会话
/status	显示当前配置
/cost	显示用量 / 费用
/compress [prompt]	总结并转到新会话

文件提及

输入 @ 打开文件建议列表，输入文字进行筛选，按 tab 确认，按 esc 取消：

$TCTL -s demo type "review @"
$TCTL -s demo type "package.json"
$TCTL -s demo press tab

视觉提示

状态	观察内容
Spec 模式开启	输入框边框显示 Spec
Bash 模式开启	提示符为 $
空闲 / 就绪	提示符为 >，且没有加载动画
对话框打开	带有导航提示的方框菜单
文件建议	输入框下方的下拉列表
思考中	显示 Thinking... 和停止提示

启动 Droid

droid-dev 的工作方式

droid-dev 是位于 ~/.local/bin/droid-dev 的轻量 bash 封装脚本。它会针对 DROID_DEV_REPO_ROOT 所指向的任意检出目录运行 bun，并不使用预编译二进制文件。这意味着：

• 无需为每个分支单独构建。 在任意检出目录中运行一次 npm run setup 即可安装封装脚本。通过 --repo-root 切换分支是即时的。
• 前置条件： 目标工作树必须已安装 node_modules（在仓库根目录运行 npm install）。如果缺少该目录，bun 将无法启动。
• tctl --repo-root 会自动设置 DROID_DEV_REPO_ROOT，并将会话固定到该工作树。
• tctl --cwd 独立于 --repo-root：你可以在不同的项目目录中运行 Droid，使用某个工作树的代码（例如，包含自身 .factory/settings.json 钩子的临时项目）。未设置时默认为 --repo-root。

droid-dev

启动 droid-dev 时必须提供 --repo-root（或 --env DROID_DEV_REPO_ROOT=...）。tctl 会强制执行此要求，未提供时启动将失败：

# tuistory (default — virtual PTY)
$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36

# true-input (real terminal proof — headless Wayland compositor)
$TCTL launch "droid-dev" -s demo --backend true-input \
  --repo-root /path/to/worktree

功能分支 / 工作树

进行比较时，启动指向不同工作树的独立会话：

$TCTL launch "droid-dev" -s before --backend tuistory \
  --repo-root /path/to/baseline-worktree \
  --cols 120 --rows 36 --record /tmp/before.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

$TCTL launch "droid-dev" -s after --backend tuistory \
  --repo-root /path/to/candidate-worktree \
  --cols 120 --rows 36 --record /tmp/after.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

比较设置（前后对比演示）

进行前后对比时，需要两个工作树路径：一个用于基线版本，一个用于候选版本。

1. 查找现有工作树：在任意检出目录中运行 git worktree list。主克隆（通常位于 dev 或 main 分支）可用作有效的基线。
2. 如有需要则创建：运行 git worktree add /tmp/baseline-worktree dev（或相关的基线分支）。
3. 确保已安装 node_modules：在缺少该目录的工作树中运行 npm install。这是唯一需要的设置，无需按分支运行 npm run setup 或构建 CLI。
4. 使用 --repo-root 启动：每个 tctl launch 都会固定到一个工作树。

环境安全

tctl 的运行脚本通过 bash -lc 启动 droid-dev，这会加载一个干净的登录 Shell。父进程遗留的 FACTORY_* 环境变量通常会被运行脚本覆盖。如果怀疑环境受到污染，请通过 --env 传入显式覆盖值。

Exec 模式

非交互式单次执行：

droid exec "analyze this file"
droid exec --auto medium "run the tests"

日志记录

通过 --env 传入日志文件路径，以启用调试日志：

$TCTL launch "droid-dev" -s demo --backend tuistory \
  --repo-root /path/to/worktree \
  --env FACTORY_LOG_FILE=/tmp/droid-test.log
tail -f /tmp/droid-test.log