你可能在同事的终端截图里看到过它，也可能被「命令行里写代码」这个说法劝退过。它到底是聊天机器人的另一种外壳，还是一个真的能改你仓库文件的工具？这篇不堆概念，先把定位讲清，再给一套能照着敲的上手顺序，最后说清什么情况下它并不合适。
你可能在同事的终端截图里看到过它，也可能被「命令行里写代码」这个说法劝退过。先别急着判断它是不是又一个聊天机器人外壳——关键看它到底能不能碰到你的项目文件。这篇先讲清定位，再给一套能照着敲的上手顺序，最后说清楚什么情况下它其实不合适。
结论前置：它不是聊天窗口的替代品，也不是 IDE 插件。它更像一个蹲在你项目目录里的助手，你把指令丢给它，它自己去找文件、改内容、跑命令，然后把结果拿回来给你看。理解这一点，后面的用法和踩坑逻辑就都顺了。
它到底是什么：一句话定位
用一句话概括：它本质是一个跑在本机终端里的编程代理。你在哪个目录启动它，它就把那个目录当成自己的工作范围，能读里面的代码、按你的指令改文件、执行命令，再把结果反馈给你。路径、文件名、报错信息都是它干活时的真实输入，不是凭空编出来的场景。
- 和网页聊天框的差别
- 聊天框只能看你粘贴进去的内容，它能直接读你磁盘上的文件、直接改、直接跑命令
- 和 AI 编辑器的差别
- 编辑器插件绑定在某个 IDE 里，它不挑编辑器，终端、远程服务器、SSH 连上去都能用
- 模型从哪来
- 它自己不训练模型也不托管模型，能力来自你配置的账号或接口，接哪条路直接决定它的表现
还有个常见的误解要提前拆掉：它不是「装完就自动变强」的工具。你给它接的线路、你给的上下文、你写的约束，三样东西决定产出质量。术语上如果对上下文窗口、工具调用这些概念还没底，可以先到 /ai-dict/category/basics 混个脸熟，再回来动手。
上手前先备齐三样东西
- 一个能跑命令的终端，外加一个准备让它折腾的项目目录；建议先拿一个能随时丢弃的练习仓库，别拿主力仓库开刀
- 一条可用的模型访问路径：官方账号登录、官方 API Key、或经中转站转发的 Key，三条路的差别到 /guides/four-access-routes 核对
- 一份边界约定：让它改哪些目录、要不要允许执行 shell 命令、要不要先看改动再落盘，这些在首次启动的确认环节都会问到你
环境变量怎么放、Key 怎么不写进代码里，照着 /guides/env-var-api-key-setup 做一遍就行。这一步别偷懒，Key 写进配置文件再顺手提交上去，是最常见的翻车方式。
| 准备项 | 做不到会怎样 | 怎么补 |
|---|---|---|
| 练习仓库 | 在主力仓库上试错，回滚成本高 | 新建一个空目录放几行示例代码 |
| 访问路径 | 启动就报认证失败 | 先确认账号或 Key 能用，再挑线路 |
| 边界约定 | 它改了不该改的文件，你还不知道 | 启动时逐项确认权限，别一路回车 |
第一次跑通的顺序
- 先问只读问题在练习仓库根目录启动，问一句「这个项目的目录结构是什么」。看它回答里出现的文件名跟你磁盘上的是否对得上，对不上说明工作目录没选对。
- 让它做一件小事加一个函数、补一段注释、改一个拼写都行。全程盯着它给出的改动，看完再决定接受还是拒绝。这一步的目的是建立「它会先说再改」的预期。
- 开始带约束第三条指令开始加限制：「只改这一个文件」「不要新增依赖」「改完告诉我改了哪几行」。约束写得清楚，比话说得长更有用。
- 自己核一遍跑完用 git diff 看实际改了什么，再决定提交还是丢弃。这一步不能省，也不能全信它的自我总结。
顺序上建议就按这个走：先确认它能看见文件，再确认它改得对，最后才谈改得多。跳过后两步直接让它大规模动代码，出问题时你连从哪里回滚都找不到头绪。
什么情况下别用它
它不是万能工具，下面这些场景先别用，或者至少先想清楚再说。判断标准很简单：看代码敏感程度、看团队有没有评审习惯、看任务本身是不是需要它碰文件。
- 代码涉及密钥、客户数据、未公开业务逻辑，而你还没搞清楚请求会发到哪条路径时，先别接
- 团队没有代码评审习惯、也没人看改动记录的情况下，让它批量改文件风险不小
- 你只想问一个概念、写一段与项目无关的片段，网页对话或编辑器补全更省事
- 把它当「自动完成整个需求」的按钮，多半会失望；产出质量跟你给的上下文和验收标准直接挂钩
它擅长的是「有明确范围的小改动加上快速验证」，不是「替我做完整个项目」。
用久之后保持可控的几个习惯
用顺了之后最大的风险不是它不干活，而是你越来越懒得看它改了什么。下面这几个习惯能让你在效率上来的同时，不把可控性丢掉。
| 习惯 | 具体怎么做 | 解决什么问题 |
|---|---|---|
| 写项目说明文件 | 把常用背景和编码规范写进仓库里的说明文件，让它每次自动读到 | 省去每次口述，减少它猜错方向 |
| 长任务拆小步 | 一次只让它改少量文件，每步都能单独验证 | 出问题时能快速定位，回滚也轻松 |
| 先估量再动手 | 关心花费就先估算用量，再决定走哪条计费路径 | 避免月底看到账单才后悔，具体入口见 /tools/token-price-calculator |
| 先量延迟 | 速度慢或时常断流时，先用 /tools/speed-test 测延迟基线 | 区分是网络问题还是账号侧问题，别瞎换线路 |
再补一句关于线路选择的：官方直连、官方 API、经转发的 Key，这几种在稳定性、计费口径、可控性上差异不小。哪条路当下更划算、更稳，这种数字型的结论别听别人转述，到 /price-watch 和 /rankings 看当时的记录更靠谱。
下一步先把练习仓库跑通，再决定要不要接到真实项目上；顺便到工具目录挑一个能帮你验证改动或估算用量的工具，上手会顺很多。→常见问题
它和 Cursor 这类 AI 编辑器是二选一的关系吗？
不是。编辑器负责你看代码、写代码的手感，它负责在终端里批量执行和改文件，很多人两个都用。如果你主要工作流就在编辑器里、很少开终端，那先把编辑器用熟更划算；反过来常年在 SSH、容器、远程机器上干活，命令行的价值会明显更大。
不用命令行的人有必要学吗？
看你的日常工作落在哪。写代码、管服务器、跑脚本的人值得花半小时摸一遍；纯做文档、运营、设计的人，学它的收益通常不如先把网页版对话用顺。它是效率工具，不是必修课，判断标准是「你一天有多少时间待在终端里」。
用它可以不花钱吗？
能不能免费取决于你接的是哪条路：有的账号档位自带额度，有的走按量计费，走中转站则看该站的政策。这些都随时间变，别听二手结论，直接到 /coding-plans 和 /plans 看当时的档位与额度口径，再决定要不要掏钱。
