Coding Agent入门教程：开发者从零上手的实操步骤

你可能已经装好了某个编程客户端，登录也成功了，但让它改一个真实仓库的 bug 时，它要么乱改一通，要么根本读不到你的文件。这篇不聊概念，只走一遍从零到能用的顺序：先确认入口对不对，再把最小环境跑通，然后用一个自己熟的小任务验证它到底行不行，最后给自己留一条退路。

装好客户端、登录成功，只是把门推开了。真正的分水岭在第一次让它改你仓库里的东西：它要么乱改一通，要么根本读不到你的文件，于是你开始怀疑是不是工具不行。多数时候不是工具的问题，是入口选错、环境没对齐、任务给得太早。

这篇按顺序走一遍：先想清楚要哪种用法，再把 Key、模型、目录这三样对齐，然后拿一个你自己很熟的小任务分档试水，最后给自己留好退路，再决定要不要长期用。全程不讲概念，只给判断标准和能立刻做的动作。

第一步：先想清楚你要的是哪种用法，别一头扎进安装

不同的入口，能力边界差得非常远。命令行式 Agent 能在终端里列目录、读文件、跑命令、看报错；编辑器内置的多半是补全和局部改写；网页聊天式只能看你贴过去的那几段。选错入口，后面怎么调都别扭。

• 问语法、改一小段函数，直接用聊天式最省事，别为了它去装命令行工具
• 涉及多文件改动、跑测试、查依赖的活，才值得上命令行 Agent
• 先把自己的活拆一遍：是「一次改一个文件」还是「跨模块重构成一件事」，后者才需要 Agent 的自动循环能力
• 拿不准就先选轻的那条路，跑不动再往上加，反过来很浪费时间

第二步：把最小可用环境跑通，Key、模型、目录三样对齐

这一节的目标只有一个：让最简的一次调用真的跑起来。三样东西对齐了，后面的事才谈得上，不用急着研究高级配置。

1. 确认 Key 与环境变量查清它读的是哪个变量名，有没有被别处的同名配置覆盖。这是「配了但没生效」最常见的来源，改完重启客户端再试一次。
2. 选一个稳的编码向模型先挑你所在渠道稳定可用的编码模型，别一上手就追最新最强的。跑通比跑好重要，等流程顺了再换。
3. 在项目根目录启动让它能看到目录结构、依赖清单和现有代码风格。在空目录里跑，等于什么都没给它，它只能瞎猜。
4. 准备一个沙箱第一次别指向生产仓库，复制一份到临时目录，或者先建个分支。出问题直接丢，不动脑子。

装机流程和配置项建议按站内的说明核对一遍，比对着文档盲改省时间：到 /tools/speed-test 走一遍连通性检查，确认链路本身没问题。如果用的是中转渠道，先到 /sites 看一眼该渠道的当前状态，别把渠道问题误判成自己配错。

第三步：拿一个你熟的小任务试水，按这四档递进

别一上来就丢一个真实 bug 让它改。任务难度要分档，每一档只验证一件事，通过了再往上走。用你自己熟的代码试，这样它改没改对，你一眼能看出来。

• 第 1 档过不了，后面几档都别试，先回去查目录和读权限
• 第 3 档要求它改完跑一次测试或运行，把实际输出贴回来，而不是自己声称「已完成」
• 第 4 档才开始考察规划能力，前一档没过就跳，只会让你误判它不行
• 每一档都自己看一眼 diff 再确认，这是新手唯一必须养成的习惯，没有例外

第四步：给自己设好边界，再决定要不要长期用

Agent 会自己执行动作，所以边界要在动手前设好，不是出事后再补。回退、动作范围、成本这三件事想清楚，用起来才踏实。

• 跑之前先 commit 或建分支，让回退永远是一个命令的事，不用靠记忆手改回去
• 收紧它的动作范围：能改哪些目录、能跑哪些命令、要不要联网，能限制就限制
• 它自动执行的每一步都该在你预期内，出现你没预期的动作就停下来查，别放它继续跑
• 涉及密钥、客户数据、没有测试覆盖的核心逻辑，先人工拆清楚再交给它，这类活让 Agent 自己规划风险太大
• 成本节奏动手前先摸清：到 /price-watch 核对当时的计费口径和用量说明，别等账单出来才反应

判断要不要长期用，标准很简单：连续两三个任务你都能在几分钟内验收并合入，就值得留着；每次都要大改它写的东西，说明是任务类型或入口选错了，先退回去调这两样，而不是换工具。

另一个容易忽略的点是渠道本身。同一套配置换一个中转，表现可能完全不同。如果你怀疑是渠道质量问题，可以到 /rankings 看当时的对比，再决定要不要换。