基本使用
掌握 CLI 参数、如何描述任务、如何给模型提供上下文、如何在多个任务之间切换。
启动方式
# 在当前目录启动 TUI
atomcode
# 指定工作目录
atomcode -C /path/to/project
# 指定 provider / 模型(一次性覆盖默认)
atomcode --provider claude --model claude-sonnet-4-6
# 继续上一次会话
atomcode -c
atomcode --continue
# 使用指定的配置文件
atomcode --config ./custom.toml
# 跳过所有权限确认,自动批准工具调用
atomcode -y
atomcode --dangerously-skip-permissionsCLI 参数总览
| 参数 | 简写 | 作用 |
|---|---|---|
--dir PATH | -C | 工作目录,不指定则使用当前目录 |
--continue | -c | 继续上一次会话,而不是新建 |
--provider NAME | — | 覆盖默认 provider |
--model NAME | — | 覆盖当前 provider 的 model |
--config PATH | — | 使用指定的配置文件 |
--prompt TEXT | -p | 非交互模式,单次执行并把回复写到 stdout |
--prompt-file PATH | — | 从文件读取 prompt(适合长文本,与 -p 互斥) |
--verbose | -v | 非交互模式下把工具调用、token 用量等信息打到 stderr |
--max-turns N | — | 强制限制 Agent 循环的最大轮数,防止无限跑下去 |
--disable-tools LIST | — | 逗号分隔,禁用某些工具。例如 --disable-tools bash,web_fetch |
--dangerously-skip-permissions | -y | 跳过所有权限确认,自动批准所有工具调用(bash、文件编辑、MCP 等)。TUI 模式下状态栏显示 ⚠ BYPASS 徽章 |
--disable-tools 让被禁用的工具对模型完全不可见(不会出现在 schemas 中),模型就不会重复尝试调用它。在沙箱评测、离线环境、禁止联网的 CI 等场景里非常实用。
-y / --dangerously-skip-permissions 会跳过所有权限确认,包括 bash 命令执行、文件写入和 MCP 工具调用等。Agent 可以不经确认直接执行任意操作。请仅在以下场景使用:
- CI/CD 流水线等自动化环境
- 沙箱或容器内的评测基准测试
- 你充分信任 Agent 内置安全约束的非关键项目
描述任务的原则
AtomCode 的 Agent 循环能力主要取决于你给出的任务描述的质量。几条经验:
- 说目标,不说步骤 —— "修复登录后跳 404 的 bug",而不是"打开 src/auth/callback.ts,删除第 27 行,再…"。模型有足够的探索能力。
- 点明约束 —— 当你有偏好时明确说出:"保持 API 兼容"、"不改动测试文件"、"用 TypeScript 而不是 JS"。
- 给出验证方式 —— "改完后跑
npm test确认通过",让模型完成自我验证闭环。 - 先问后改 —— 不确定方向时,先让它"分析这个模块的结构并提出重构方案",对齐之后再让它动手。
示例任务
# Bug 修复
> 修复 OAuth 回调后用户被重定向到 404 的问题,确保回调完整恢复原始路径
# 新增功能
> 在设置页增加深色模式切换,使用 Tailwind 的 dark: 前缀,并持久化到 localStorage
# 重构
> 把 src/db/*.ts 重构成使用连接池,保持公有 API 不变,改完后跑 npm test
# 测试
> 给 src/payment/processor.ts 写单元测试,覆盖所有异常分支
# 代码理解
> 简要说明这个仓库的目录结构、构建入口和核心模块职责多行输入
在 TUI 中:
Enter发送消息Shift+Enter/Ctrl+Enter/Ctrl+J换行(需要 Kitty 键盘协议: kitty / WezTerm / Alacritty / iTerm2 ≥3.5 / Windows Terminal ≥1.21)Alt+Enter换行(多数终端可用,但 Windows Terminal 默认绑给"切换全屏",需在设置里解绑)- 输入框高度会随内容自动增长
@ 引用文件
在输入框里敲一个 @(前面是空白或行首)就会弹出项目内文件/目录的候选菜单。这是把代码里某个具体路径"指给模型看"最快的方式 — 你只负责定位,要不要展开、读多少由模型按需调 read_file 决定。
交互
- 触发 ——
@前面是空白或行首才生效。email@host.com这种中间出现的@不会触发,避免误弹。 - 过滤 —— 继续敲字符做子串匹配(大小写不敏感)。例如
@cra能命中crates/;@toml能命中所有*.toml。 - 下钻 —— 敲
/进入某个目录,菜单收紧到该目录的内容。例如@crates/→@crates/atomcode-cli/→ ... - 导航 ——
↑/↓切换候选,Enter或Tab都可以选中。Esc关菜单不插入。 - 插入形式 —— 选中后,输入框里的
@xxx部分被替换为@完整相对路径(目录会带/)再加一个尾随空格,光标停在空格后,可以直接继续打字。 - 回退继续选 —— 删掉尾随空格后,菜单会就地重开,方便从当前目录继续往下钻。
候选来自哪里
- 项目根目录下的所有文件和目录 — 文件、目录都能选;目录用尾随
/标识。 - 尊重
.gitignore(以及全局 ignore、.git/info/exclude),被忽略的路径不会出现在菜单里。 .git/内部内容不出现在候选里 — 几乎没人想@引用 git 元数据。- 隐藏文件保留 —
.env、.atomcode.md这类点开头文件能正常命中(只要没被 gitignore 屏蔽)。 - 跨级模糊匹配 — 一旦你开始打过滤字符,匹配会穿透多级目录(不只是当前 scope 的直接子项)。空过滤时只显示当前 scope 的直接子项。
- 排序:当前 scope 的直接子项优先 → 目录优先于文件 → 字母序。
对模型意味着什么
提交时,@crates/atomcode-cli/src/main.rs 作为字面文本一同发给模型 — AtomCode 不会在前端预读文件内容并内联。模型看到这段路径后,会按需调用内置的 read_file 工具去读。这样:
- 大文件不会无脑塞进上下文,token 预算更可控。
- 引用目录时模型会先
list再决定读哪些。 - 多次复读不会重复内联同一份内容。
如果想强制把文件内容直接喂进对话(比如让模型针对某段代码做精读、不希望它再走一次 read_file),用粘贴 — 直接把内容粘进输入框,bracketed paste 会把它折叠成 [paste #N] 标记,提交时整段带入。
限制
- 候选菜单一次最多展示 30 条,继续打过滤字符可以缩小命中范围。
- 路径中含空格的文件不会出现在候选里 — 因为
@引用以空白作为终止符。 - 文件索引在会话内一次性构建,会话期间新建的文件不会自动出现在菜单里;切换会话或重启会重新扫描。
- 不跟随符号链接。
- 没有大小、类型过滤 — 所有未被 ignore 的文件都会出现。
粘贴长文本
AtomCode 支持 bracketed paste。当你粘贴一段很长的内容(比如一堆日志)时,TUI 会把它折叠成一个紧凑的 [paste #N · 132 lines] 指示器,避免输入框被撑爆。发送时会完整带入。
图片附件 / 截图
除了文本,你还能把图片带进对话 — 报错截图、UI mock、白板照片等。AtomCode 提供三条入口,任选其一:
- Ctrl+V — 系统剪贴板里有图片时(刚
Cmd+Shift+4截图、从浏览器复制图等),按 Ctrl+V 直接 attach。这是 macOS + iTerm2 等终端默认 Cmd+V 不传图给 PTY 时的兜底方案,任何终端都通用。 - Cmd+V(macOS / iTerm2,需简单配置) — iTerm2 → Settings → Profiles → Keys → Key Mappings,把
⌘V映射为Send Hex Codes: 0x16,之后 Cmd+V 就跟 Ctrl+V 等价。 - Finder 拖拽 / iTerm2 自动转路径 — 把一张图直接拖进终端窗口,iTerm2 / Wezterm 等会把文件路径以 plaintext 方式粘进来;AtomCode 识别到绝对路径 +
.png/.jpg/.jpeg/.gif/.webp扩展名 + 文件存在 + 大小 ≤ 20MB 时,会自动读取文件并 attach。原始路径字符串不会留在输入框里。
每次成功 attach 时,输入框会就地插入一个 [Image #N] 标记,提交时图片字节随消息一起发。状态栏右侧也会出现 Image in clipboard · ctrl+v to paste 的提示(剪贴板还有未粘的图时)。
非视觉模型怎么处理图片?
当前 active provider 不支持图片输入(比如 DeepSeek-V3 / Kimi 等纯文本模型)时,AtomCode 不会直接拒绝,而是会自动调用一个独立的 VL preprocessor(视觉模型,比如 Qwen3-VL / GLM-4V)对图片做 OCR + 描述,把结果作为文本 splice 到用户消息里再发给主模型。这样无论主模型支不支持图片,你都能"贴张截图问问题"。
- preprocessor 用哪个模型?由配置文件里的
vision_preprocessor_provider决定 — 详见 配置文件 · 视觉预处理器。 /login流程会自动从模型列表里挑一个 VL/OCR 模型自动设置进去。- VL 调用使用无进展超时(idle timeout):只要 stream 持续吐 chunk,不限总时长;30 秒没动静才算超时。失败时会以 VL 预处理失败 的警告呈现,图片识别失败但消息照常发。
如果当前模型本身就支持视觉输入(Claude 3+ / GPT-4o / Gemini / Qwen-VL 等),会直接发原始图片字节,不走 preprocessor。
切换会话和目录
/resume—— 在不同会话之间切换或恢复/session—— 新建一个干净会话/cd或直接输入cd /path—— 切换工作目录(状态栏实时更新)/clear—— 清空当前会话的消息/compact—— 压缩历史消息以腾出上下文预算
详细行为见 会话与撤销。
查看成本和 diff
/cost—— 本次会话输出 token 数和上下文用量(不支持 usage 的 API 会自动估算)/diff—— 当前工作目录未提交改动的 git diff/undo—— 回滚上一轮的所有文件编辑