最近手头的几个小项目都在写脚本GitHub Copilot 试用期一过收费又涨了一截肉疼。我就在开发者社区里翻各种免费的 AI 编程助手试了一圈下来Agnes Code 是我目前愿意长期留在 VS Code 里的一个。它支持对话式编程、代码补全、多模型切换还能接本地模型关键是免费额度给得大方没有太多套路。这篇文章就把我这几周的实际使用过程、配置方法和踩过的坑都写出来给想上手又怕折腾的朋友一个完整的参考。Agnes Code 适合谁如果你是 VS Code 的重度用户不想为了 AI 编程功能换到 Cursor 这种全家桶 IDE那它几乎是无痛迁移的选择。如果你在用 Copilot 但觉得订阅费太高或者对代码隐私有要求、想试试本地模型Agnes Code 也值得看一眼。下面我按安装、配置、核心功能、实操案例、问题排查的顺序展开内容偏经验向不是官方的说明书但保证每一条都是我真跑过的。1. Agnes Code 是个什么来头1.1 为什么我会注意到这个免费的 AI 编程助手先说背景。市面上叫得上名的 AI 编程助手要么按座位收费要么把代码偷偷送到云端做训练要么绑定自家的编辑器不让你走。我团队的几个同事早就把 Copilot 换成了各种开源方案但效果总差一口气尤其是项目上下文理解经常答非所问。后来我在一个开源社区帖子里刷到 Agnes Code从一开始就定位成免费、开源、可接入多种模型源的 AI 编程助手支持代码生成、解释、重构、测试用例生成这些常见场景并且不强制绑定某一家的大模型 API。这个定位很关键。它不是一个封闭的 IDE而是一个 VS Code 扩展装好之后只是你编辑器里的一个侧边栏面板和一组快捷键。你继续用你熟悉的编辑器、快捷键、插件体系AI 只是叠加进来的一层能力。对已经有自己工作流的老手来说这种侵入性低的设计比 Cursor 那种整套换掉的思路友好得多。而且它把底层模型做成可插拔的也就是说你可以接官方的免费模型额度也可以用自己的 OpenAI 兼容接口甚至可以接本地跑的模型这一点对隐私敏感的项目太重要了。1.2 它和 Copilot、Cursor 这类工具的差异我用 Copilot 两年用 Cursor 断断续续有大半年换成 Agnes Code 之后最明显的感受是“控制感”回来了。Copilot 的补全很聪明但它是个黑盒你不知道它用了什么模型、你的代码去了哪里出问题也只能干瞪眼。Cursor 很强大但它把整个编辑器都重构了一遍快捷键、插件兼容、配置同步都有学习成本团队协作时尤其麻烦你不能要求每个人都跟着你换 IDE。Agnes Code 的定位更像是“给 VS Code 加一个 AI 外挂”它不改变你的编辑习惯只增加 AI 能力。具体差异我用一个表格来说明这样比较直观对比维度Agnes CodeGitHub CopilotCursor收费模式免费 可选额度升级按月订阅按月订阅免费版有限制载体形态VS Code 扩展VS Code 扩展 / IDE独立 IDE模型绑定可插拔支持多模型源微软系模型为主自家模型 API本地模型支持原生支持不支持有限支持项目上下文可配置上下文规则依赖索引内置较强上手成本低保留原工作流低中高需适应新 IDE从表格能看出来它和 Cursor 最大的区别是“不绑架你的环境”。Cursor 的上下文理解确实强但它要求你把整个项目迁过去等于换了个家。Agnes Code 的思路是“我住进你家”你该干嘛干嘛我只在你需要的时候搭把手。对已经有完整工具链、不想推翻重来的开发者来说这个思路现实得多。2. 安装前的环境准备与安装过程2.1 需要准备什么环境Agnes Code 的安装门槛不高但有几个前置条件我还是想单独说一下免得你装到一半卡住。官方要求 VS Code 版本在 1.85 以上实际上我建议直接用最新稳定版因为新版本对扩展 API 的支持更稳定尤其是内联补全和 diff 视图相关的功能老版本容易出现兼容问题。除了 VS Code 本身我建议你装好 Git并且把 Git 用户信息配好。装好 Git 的原因有两个一是很多项目上下文需要通过 Git 变更记录来理解你改了什么二是后续如果想把生成的代码做成 Git 提交记录也会顺畅很多。然后是 Node.js虽然 Agnes Code 核心是纯前端扩展但部分功能模式比如某些代码分析和格式化工具会调用本地 Node 环境装一个 LTS 版本放着省得后续报错找不到环境。如果你打算接本地模型建议提前装好 Ollama。Ollama 是一个本地模型运行工具下载后可以直接把 Llama、Qwen 这类开源模型跑在本地。这步是可选中的可选不玩本地模型完全可以跳过但我觉得对 Agnes Code 来说这是个亮点功能装好之后随时能切体验很不一样。2.2 一步步把 Agnes Code 装好安装过程其实没有太多可讲的但有几个细节值得注意。打开 VS Code 的扩展面板直接在搜索框输入 Agnes Code第一个就是官方版本。点 Install 后等它装完重启窗口左侧活动栏会出现一个 Agnes Code 的图标点开就是 AI 聊天面板。这里要提醒一句扩展市场里偶尔会出现名字相似的山寨扩展尤其是前一阵 Copilot 改名之后名字蹭热度的插件越来越多了。安装前一定要点进详情页确认扩展的发布者名称和下载量认准官方发布者不要只看名字。我有个同事就是装了个名字类似的第三方扩展结果代码被偷偷传到一个不明服务器这件事之后他再也不敢随便装扩展了。装完之后第一次打开面板它会提示你登录账号或者选择一个模型源。Agnes Code 登录后才会分配免费的额度所以我建议先注册一个账号用邮箱登录就行很快。如果你不想注册也可以直接用本地模型源绕过登录但本地模型效果和云端模型差距太大纯体验可以实际干活还是建议登录。2.3 首次配置模型源这是 Agnes Code 和很多一键式 AI 插件不一样的地方它默认不会帮你绑定一个固定的模型而是让你自己选。打开设置面板找到“模型供应商”分类你会看到一个已配置的模型源列表。首次使用建议先选内置的免费模型它不需要填任何 Key登录账号后直接就能用额度对日常学习和小项目来说完全够了。如果你有自己的 OpenAI 兼容 API Key可以在模型供应商里选择自定义填写 API Base 和 API Key 两个字段即可。Agnes Code 兼容 OpenAI 的接口协议这点很实用意味着市面上大多数模型的 API 服务都能接进来甚至包括部分中转服务。配置界面的 JSON 大致长这样{ agnesCode.providers: { myProvider: { type: openai-compatible, apiBase: https://your-api-endpoint.com/v1, apiKey: sk-xxxxxx, models: [gpt-4o-mini, your-model-name] } } }配置文件修改后需要重载窗口才会生效。配置多个模型源之后聊天框输入/model命令可以在不同模型之间快速切换。我自己的习惯是日常对话和小需求用免费模型跑重要代码审查时切到配置好的强模型这样日常使用不心疼额度关键场景又有的选。3. 核心功能拆解这些功能值得优先使用3.1 对话式生成不是聊天框是代码编辑很多刚上手的人会把 Agnes Code 的侧边栏面板当成普通聊天窗口用丢一句“写一个登录接口”然后复制粘贴生成的代码。这么用没错但完全没发挥出它真正的能力。Agnes Code 的对话系统是深度绑定代码编辑器的你可以选中一段代码然后从右键菜单发起“解释选中代码”“优化选中代码”“为选中代码写测试”这类操作它会把你的代码作为上下文带入对话而不是像普通聊天窗口那样只靠文本描述猜你的意图。我日常用得最多的是行内对话模式。在代码文件里选中一个函数按CtrlI会在光标位置弹出一个行内输入框直接输入指令比如“把这个函数改成异步实现”它会把改动结果直接以 diff 形式预览确认后一键应用。这样交互链路短很多不需要在两个窗口之间来回切。这里要强调一个细节Agnes Code 的对话不是无状态的同一对话内的多次提问会保持上下文连贯。你可以先让它生成一段代码然后接着说“这里有个边界条件没处理帮我加上”它记得刚才的代码。这比每次都要从零开始描述需求强得多。3.2 补全与内联建议用起来舒服才是真舒服代码补全是 Agnes Code 的另一大核心能力。和 Copilot 那种几乎每打一行字都跳建议的模式不同Agnes Code 的触发策略内敛一些更倾向于在你写到一个逻辑断点或者空行时给出建议减少“打字打到一半被弹窗打扰”的烦躁感。更有意思的是它支持“补全下一处编辑”。假设你正在按某个规律修改多个位置的代码改完一个地方用快捷键可以让它预测你下一个改动点并自动跳到那里配合补全用特别顺手。我上个月做一个配置文件的批量迁移几十个字段要改同样的模式用这个功能省了不少时间。如果补全的建议你不想要按Esc直接忽略如果想接受按Tab就替换掉当前内容。如果你觉得补全太频繁或者太少可以在设置里调节触发灵敏度这个因人而异我自己的经验是先调低一点等熟悉了它的触发规律再慢慢调高一开始就用最灵敏的模式反而容易被建议搞得心烦。3.3 项目级上下文与会话规则Agnes Code 的几个斜杠命令里workspace和file是理解项目结构的关键。输入workspace后提问“这个项目的登录流程怎么实现的”它会根据项目里的文件内容和结构来回答而不是凭空想象。输入file后跟上文件路径可以指定某一份文件的上下文这在高耦合项目里特别有用。除了临时的上下文指定Agnes Code 也支持在项目根目录放一个规则文件比如AGENTS.md在里面写清楚这个项目的技术栈、编码规范、目录结构约定。只要这个文件存在每次对话时它都会自动读取并作为基础上下文。这个机制和很多大厂内部训练 AI 助手时的做法一致相当于你给 AI 立了一份“入职手册”回答质量会有质的提升。我自己维护的 Python 项目里AGENTS.md 就写了“所有数据库操作必须走 SQLAlchemy”“测试文件放在 tests/ 目录”“类型注解必须有”这几条之后让 Agnes Code 生成代码时它自动遵守这些规则出错的概率明显变低。3.4 多模型接入与成本控制Agnes Code 支持同时配置多个模型源这在日常使用中非常实用。我个人的习惯是日常对话、生成简单脚本用官方免费模型速度不错响应快不心疼额度。复杂代码审查、架构设计讨论切换到更强的模型输出质量和推理深度更好。涉及敏感代码或者离线环境直接切到本地模型代码不出本机。它的成本控制思路比较聪明你可以在设置里配置每个模型源的单次请求最大 Token 数以及每日额度提醒。我之前用某些 API 服务时最怕的就是哪天代码里有个大规模重构AI 一次调用烧掉几十万 Token账单直接爆炸。Agnes Code 的 Token 上限设置在聊天界面上就能拉非常直观。关于本地模型我建议至少是 7B 以上参数的量化版本才有点实用性更小的模型跑起来只能做简单问答生成高质量代码基本没戏。Ollama 拉取模型后在 Agnes Code 的模型源里选“本地模型”设置一下端口就可以用了。离线环境下这个功能是救命的。4. 实操我用 Agnes Code 从零写了一个小工具4.1 任务目标与提示词设计光说功能不实操等于纸上谈兵。这次我拿一个真实任务来跑一遍完整流程写一个批量重命名图片文件的 Python 脚本要求支持多种命名规则、自动处理文件名冲突、带日期前缀还要有命令行参数。这个任务难度适中既有常规逻辑又有边界情况很适合展示 Agnes Code 的完整工作流。我给它的初始提示词是这样的写一个 Python 脚本批量重命名某个目录下的图片文件。支持以下参数--directory 指定目录--prefix 自定义前缀--date 是否添加日期前缀--dry-run 预览效果不真正重命名。 要求处理文件名冲突比如新文件名已存在时自动加序号。需要支持 jpg、png、gif 格式。脚本要放在项目根目录的 scripts 目录下。任务拆解这块我有一点经验要分享AI 编程助手对“边界情况”的处理能力取决于提示词里是否提前补充约束。如果你只说“批量重命名图片”它生成的代码八成没有冲突检查因为冲突处理是你自己脑补的需求它不是读心术。所以提示词阶段先把格式、约束、边界情况想清楚后面生成出来的代码质量会高非常多。4.2 一步步生成、调试、完善Agnes Code 生成的代码初版比较规整结构清晰能用但确实有些细节没到位。我逐项验证后发现两个问题第一个是它没有处理“新文件名和旧文件名重复加入序号”的情况如果目录里已经有IMG_001.jpg这种名字直接重命名会覆盖原文件第二个是日期前缀用了本地时间但没有处理时区问题严格来说不算 bug但对跨时区环境不够健壮。这两个问题我没有手动改而是直接继续在对话里追加指令“文件名冲突时不要覆盖自动往后加序号比如遇到 IMG_001.jpg 已存在就改成 IMG_001_1.jpg”然后让它重新生成完整脚本。这就是用对话式编程的正确姿势有问题就在上下文里补而不是重新开一个空白对话。当 AI 有之前对话的全部记忆时你只需要描述增量需求它就能精准修改这个体验比复制粘贴再改代码顺滑得多。第二版生成后我在一个测试目录放了十几张图片包括一张故意制造的名字冲突运行python scripts/batch_rename.py --directory /tmp/test_images --prefix holiday --date --dry-run输出结果完全符合预期冲突文件自动变成了holiday_20250115_003_1.jpg这种形式。确认无误后去掉--dry-run正式执行所有文件都按规则重命名成功。4.3 这一轮实操里我验证出的提示词套路这一轮实操下来我验证了几个对 Agnes Code 相当有效的套路分享给大家第一任务描述里一定要写清楚“输入是什么、输出是什么、中间经过什么处理”。有些朋友习惯丢一句“帮我写个脚本”然后 AI 生成一堆泛泛的代码这不是 AI 笨是输入信息不够。信息密度越高输出质量越高这条反复被验证。第二把约束条件前置。比如文件格式限制、不得覆盖、输出日志格式、Python 版本兼容性这些条件在提问时就要给全否则后期改起来一步一个坑。第三需求变更时不要新开对话要在同一对话里继续追问。Agnes Code 的会话记忆很强新开对话意味着它忘了前文的约定很可能给你一版风格完全不同的代码。第四生成代码后要求它“解释关键逻辑”。这个技巧很好用一方面你自己能确认它写的逻辑是不是符合需求另一方面解释的过程也能发现潜在问题相当于白赚一次代码审查。5. 常见问题与排错实录5.1 我实际踩过的几个坑用 Agnes Code 这几周我至少踩了四五个坑挑几个有代表性的说一下。第一个坑是模型源配置成功后没生效。我改完 JSON 配置重载了窗口但聊天框里切换到自定义模型时一直报错提示模型不存在。排查了半天发现是模型名称写错了我写的名字和 API 服务商返回的模型列表对不上。解决方法是先调用一下 API 服务商的模型列表接口把返回的模型名原样填进去不要凭记忆写。第二个坑是本地模型连接失败。Ollama 默认监听 11434 端口但我配置代理环境变量后请求被代理拦截了。Agnes Code 请求本地模型时走了系统代理结果代理又没法访问本机地址就是localhost流量被代理劫持的经典问题。这个问题的排查思路比较绕最终我在终端里关掉了代理相关的环境变量才解决的。如果你也遇到本地模型一直连接失败先怀疑代理再去折腾配置。第三个坑是 AGENTS.md 文件不生效。我一开始把文件放在项目根目录但发现它读不到。后来查文档才发现 Agnes Code 对规则文件的命名和位置有约定文件名必须精确匹配不能加后缀。位置也要放在工作区根目录放在子目录里是读不到的。改了位置之后效果立竿见影。5.2 问题速查表为了方便大家对照排查我把这段时间遇到的问题汇总成一张速查表现象可能原因解决办法安装后没有侧边栏图标扩展未激活或版本过旧重启窗口检查扩展版本并更新对话面板一直转圈不回复网络问题或模型源 Key 失效检查网络连接检查 API Key 是否有效补全建议不出现触发灵敏度设置过低或语言不被支持调高灵敏度确认文件语言模式正确本地模型连接失败代理拦截 localhost 流量临时关闭代理或在本地请求中绕过代理自定义模型报“模型不存在”模型名称填写错误调接口确认模型列表原样填写名称AGENTS.md 不生效文件名或位置不对精确命名为 AGENTS.md放在工作区根目录生成代码不遵守项目规范缺少上下文规则配置 AGENTS.md或在提问时明确约束条件上下文丢失答非所问新开了对话尽量在同一对话内继续追问避免上下文断裂5.3 一些值得长期保留的使用习惯用了一段时间后我慢慢养成了几个固定习惯对工作流提升帮助很大。每次接一个新项目第一件事就是建好AGENTS.md把项目的技术栈、目录约定、编码规范写进去。这相当于在给 AI 做“岗前培训”虽然花半小时但后续 AI 生成的代码质量稳定下来节省的时间远超这半小时。重要对话我会用“分项目建会话”的方式管理。Agnes Code 的会话列表可以按项目归类每个项目一个会话这样上下文不会互相污染。我之前在同一个会话里既有公司项目的问题又有个人项目的需求结果 AI 经常把公司项目的目录结构带到个人项目的回答里问得多了才发现是两个项目串了。生成代码后我会先要求它“快速自查”再读代码。Agnes Code 支持让模型自己审查一遍自己生成的代码虽然不能完全替代人工审查但能过滤掉很多低级错误比如未定义的变量、缺失的 import、明显的逻辑漏洞。6. 免费额度够不够用以及后续还能怎么玩6.1 免费额度个人开发者完全够用很多人最关心的就是免费额度到底够不够用。以我这段时间的使用来看单纯写代码、改 bug、写测试日常的小项目强度完全够用。我一周大概有 3 到 4 个晚上写代码每次持续一两个小时用的是官方免费模型月底看额度统计基本还剩下一半左右。不过要留意的是免费额度有限流策略连续请求太频繁时会变慢。我的经验是生成几百行代码的大任务时建议拆分来问一次性让它生成一个完整的大文件响应时间会明显拉长而且生成质量也容易打折。拆成几个小函数分几次对话生成整体效果反而更好还不太消耗额度。6.2 它还能怎么玩自定义指令与协作场景Agnes Code 对高级玩法支持得不错不只是最简单的“问一句答一句”。你可以通过配置自定义指令把复杂的提示词模板保存成快捷键指令比如一键生成单元测试、一键补充函数注释、一键做代码重构。这样日常操作基本不用打字一个快捷键就能触发标准化的 AI 行为。其次它支持 CLI 模式可以在终端里直接调用这对那些习惯用 Neovim 或者 JetBrains 系列的用户来说是一个不错的补充路径。虽然它不是原生扩展但 CLI 方式能在不同编辑器里共用一套 AI 配置。团队协作场景Agnes Code 也给了很实用的支持。它支持会话分享可以把一次排错过程导成 Markdown 文件发给同事整个排查链路非常清晰。我上周帮同事排查一个诡异的线上问题就是用这种方式把 Agnes Code 的整个分析过程分享到群里大家一眼就看明白了问题所在省去了大量的口头描述成本。6.3 我对免费工具的态度不迷信但也不错过这几周用下来我的体感是 Agnes Code 已经在大部分日常场景里做到了“能用”而在接入方式和成本控制上做到了“好用”。它没有 Cursor 那么惊艳的自动补全也不像 Copilot 那样与编辑器深度耦合但一个免费、开放、可控的 AI 编程助手对独立开发者和中小团队来说已经是非常务实的方案。我个人的建议是别急着把主力工作流切到一个新工具上但可以把它作为 Copilot 之外的备选在个人项目或者非核心代码上先试一周。等你习惯了它的斜杠命令、行内对话这些操作方式再决定要不要全面切换。一个好的工具不是让你改变习惯而是让你现有的习惯变得更强。Agnes Code 至少在这个方向上做了不少扎实的事。 
长河君 · 2026/10/17 23:35:48 · 阅读 1.2k Agnes Code使用教程：免费AI编程助手VS Code插件配置与实操指南
最近手头的几个小项目都在写脚本GitHub Copilot 试用期一过收费又涨了一截肉疼。我就在开发者社区里翻各种免费的 AI 编程助手试了一圈下来Agnes Code 是我目前愿意长期留在 VS Code 里的一个。它支持对话式编程、代码补全、多模型切换还能接本地模型关键是免费额度给得大方没有太多套路。这篇文章就把我这几周的实际使用过程、配置方法和踩过的坑都写出来给想上手又怕折腾的朋友一个完整的参考。Agnes Code 适合谁如果你是 VS Code 的重度用户不想为了 AI 编程功能换到 Cursor 这种全家桶 IDE那它几乎是无痛迁移的选择。如果你在用 Copilot 但觉得订阅费太高或者对代码隐私有要求、想试试本地模型Agnes Code 也值得看一眼。下面我按安装、配置、核心功能、实操案例、问题排查的顺序展开内容偏经验向不是官方的说明书但保证每一条都是我真跑过的。1. Agnes Code 是个什么来头1.1 为什么我会注意到这个免费的 AI 编程助手先说背景。市面上叫得上名的 AI 编程助手要么按座位收费要么把代码偷偷送到云端做训练要么绑定自家的编辑器不让你走。我团队的几个同事早就把 Copilot 换成了各种开源方案但效果总差一口气尤其是项目上下文理解经常答非所问。后来我在一个开源社区帖子里刷到 Agnes Code从一开始就定位成免费、开源、可接入多种模型源的 AI 编程助手支持代码生成、解释、重构、测试用例生成这些常见场景并且不强制绑定某一家的大模型 API。这个定位很关键。它不是一个封闭的 IDE而是一个 VS Code 扩展装好之后只是你编辑器里的一个侧边栏面板和一组快捷键。你继续用你熟悉的编辑器、快捷键、插件体系AI 只是叠加进来的一层能力。对已经有自己工作流的老手来说这种侵入性低的设计比 Cursor 那种整套换掉的思路友好得多。而且它把底层模型做成可插拔的也就是说你可以接官方的免费模型额度也可以用自己的 OpenAI 兼容接口甚至可以接本地跑的模型这一点对隐私敏感的项目太重要了。1.2 它和 Copilot、Cursor 这类工具的差异我用 Copilot 两年用 Cursor 断断续续有大半年换成 Agnes Code 之后最明显的感受是“控制感”回来了。Copilot 的补全很聪明但它是个黑盒你不知道它用了什么模型、你的代码去了哪里出问题也只能干瞪眼。Cursor 很强大但它把整个编辑器都重构了一遍快捷键、插件兼容、配置同步都有学习成本团队协作时尤其麻烦你不能要求每个人都跟着你换 IDE。Agnes Code 的定位更像是“给 VS Code 加一个 AI 外挂”它不改变你的编辑习惯只增加 AI 能力。具体差异我用一个表格来说明这样比较直观对比维度Agnes CodeGitHub CopilotCursor收费模式免费 可选额度升级按月订阅按月订阅免费版有限制载体形态VS Code 扩展VS Code 扩展 / IDE独立 IDE模型绑定可插拔支持多模型源微软系模型为主自家模型 API本地模型支持原生支持不支持有限支持项目上下文可配置上下文规则依赖索引内置较强上手成本低保留原工作流低中高需适应新 IDE从表格能看出来它和 Cursor 最大的区别是“不绑架你的环境”。Cursor 的上下文理解确实强但它要求你把整个项目迁过去等于换了个家。Agnes Code 的思路是“我住进你家”你该干嘛干嘛我只在你需要的时候搭把手。对已经有完整工具链、不想推翻重来的开发者来说这个思路现实得多。2. 安装前的环境准备与安装过程2.1 需要准备什么环境Agnes Code 的安装门槛不高但有几个前置条件我还是想单独说一下免得你装到一半卡住。官方要求 VS Code 版本在 1.85 以上实际上我建议直接用最新稳定版因为新版本对扩展 API 的支持更稳定尤其是内联补全和 diff 视图相关的功能老版本容易出现兼容问题。除了 VS Code 本身我建议你装好 Git并且把 Git 用户信息配好。装好 Git 的原因有两个一是很多项目上下文需要通过 Git 变更记录来理解你改了什么二是后续如果想把生成的代码做成 Git 提交记录也会顺畅很多。然后是 Node.js虽然 Agnes Code 核心是纯前端扩展但部分功能模式比如某些代码分析和格式化工具会调用本地 Node 环境装一个 LTS 版本放着省得后续报错找不到环境。如果你打算接本地模型建议提前装好 Ollama。Ollama 是一个本地模型运行工具下载后可以直接把 Llama、Qwen 这类开源模型跑在本地。这步是可选中的可选不玩本地模型完全可以跳过但我觉得对 Agnes Code 来说这是个亮点功能装好之后随时能切体验很不一样。2.2 一步步把 Agnes Code 装好安装过程其实没有太多可讲的但有几个细节值得注意。打开 VS Code 的扩展面板直接在搜索框输入 Agnes Code第一个就是官方版本。点 Install 后等它装完重启窗口左侧活动栏会出现一个 Agnes Code 的图标点开就是 AI 聊天面板。这里要提醒一句扩展市场里偶尔会出现名字相似的山寨扩展尤其是前一阵 Copilot 改名之后名字蹭热度的插件越来越多了。安装前一定要点进详情页确认扩展的发布者名称和下载量认准官方发布者不要只看名字。我有个同事就是装了个名字类似的第三方扩展结果代码被偷偷传到一个不明服务器这件事之后他再也不敢随便装扩展了。装完之后第一次打开面板它会提示你登录账号或者选择一个模型源。Agnes Code 登录后才会分配免费的额度所以我建议先注册一个账号用邮箱登录就行很快。如果你不想注册也可以直接用本地模型源绕过登录但本地模型效果和云端模型差距太大纯体验可以实际干活还是建议登录。2.3 首次配置模型源这是 Agnes Code 和很多一键式 AI 插件不一样的地方它默认不会帮你绑定一个固定的模型而是让你自己选。打开设置面板找到“模型供应商”分类你会看到一个已配置的模型源列表。首次使用建议先选内置的免费模型它不需要填任何 Key登录账号后直接就能用额度对日常学习和小项目来说完全够了。如果你有自己的 OpenAI 兼容 API Key可以在模型供应商里选择自定义填写 API Base 和 API Key 两个字段即可。Agnes Code 兼容 OpenAI 的接口协议这点很实用意味着市面上大多数模型的 API 服务都能接进来甚至包括部分中转服务。配置界面的 JSON 大致长这样{ agnesCode.providers: { myProvider: { type: openai-compatible, apiBase: https://your-api-endpoint.com/v1, apiKey: sk-xxxxxx, models: [gpt-4o-mini, your-model-name] } } }配置文件修改后需要重载窗口才会生效。配置多个模型源之后聊天框输入/model命令可以在不同模型之间快速切换。我自己的习惯是日常对话和小需求用免费模型跑重要代码审查时切到配置好的强模型这样日常使用不心疼额度关键场景又有的选。3. 核心功能拆解这些功能值得优先使用3.1 对话式生成不是聊天框是代码编辑很多刚上手的人会把 Agnes Code 的侧边栏面板当成普通聊天窗口用丢一句“写一个登录接口”然后复制粘贴生成的代码。这么用没错但完全没发挥出它真正的能力。Agnes Code 的对话系统是深度绑定代码编辑器的你可以选中一段代码然后从右键菜单发起“解释选中代码”“优化选中代码”“为选中代码写测试”这类操作它会把你的代码作为上下文带入对话而不是像普通聊天窗口那样只靠文本描述猜你的意图。我日常用得最多的是行内对话模式。在代码文件里选中一个函数按CtrlI会在光标位置弹出一个行内输入框直接输入指令比如“把这个函数改成异步实现”它会把改动结果直接以 diff 形式预览确认后一键应用。这样交互链路短很多不需要在两个窗口之间来回切。这里要强调一个细节Agnes Code 的对话不是无状态的同一对话内的多次提问会保持上下文连贯。你可以先让它生成一段代码然后接着说“这里有个边界条件没处理帮我加上”它记得刚才的代码。这比每次都要从零开始描述需求强得多。3.2 补全与内联建议用起来舒服才是真舒服代码补全是 Agnes Code 的另一大核心能力。和 Copilot 那种几乎每打一行字都跳建议的模式不同Agnes Code 的触发策略内敛一些更倾向于在你写到一个逻辑断点或者空行时给出建议减少“打字打到一半被弹窗打扰”的烦躁感。更有意思的是它支持“补全下一处编辑”。假设你正在按某个规律修改多个位置的代码改完一个地方用快捷键可以让它预测你下一个改动点并自动跳到那里配合补全用特别顺手。我上个月做一个配置文件的批量迁移几十个字段要改同样的模式用这个功能省了不少时间。如果补全的建议你不想要按Esc直接忽略如果想接受按Tab就替换掉当前内容。如果你觉得补全太频繁或者太少可以在设置里调节触发灵敏度这个因人而异我自己的经验是先调低一点等熟悉了它的触发规律再慢慢调高一开始就用最灵敏的模式反而容易被建议搞得心烦。3.3 项目级上下文与会话规则Agnes Code 的几个斜杠命令里workspace和file是理解项目结构的关键。输入workspace后提问“这个项目的登录流程怎么实现的”它会根据项目里的文件内容和结构来回答而不是凭空想象。输入file后跟上文件路径可以指定某一份文件的上下文这在高耦合项目里特别有用。除了临时的上下文指定Agnes Code 也支持在项目根目录放一个规则文件比如AGENTS.md在里面写清楚这个项目的技术栈、编码规范、目录结构约定。只要这个文件存在每次对话时它都会自动读取并作为基础上下文。这个机制和很多大厂内部训练 AI 助手时的做法一致相当于你给 AI 立了一份“入职手册”回答质量会有质的提升。我自己维护的 Python 项目里AGENTS.md 就写了“所有数据库操作必须走 SQLAlchemy”“测试文件放在 tests/ 目录”“类型注解必须有”这几条之后让 Agnes Code 生成代码时它自动遵守这些规则出错的概率明显变低。3.4 多模型接入与成本控制Agnes Code 支持同时配置多个模型源这在日常使用中非常实用。我个人的习惯是日常对话、生成简单脚本用官方免费模型速度不错响应快不心疼额度。复杂代码审查、架构设计讨论切换到更强的模型输出质量和推理深度更好。涉及敏感代码或者离线环境直接切到本地模型代码不出本机。它的成本控制思路比较聪明你可以在设置里配置每个模型源的单次请求最大 Token 数以及每日额度提醒。我之前用某些 API 服务时最怕的就是哪天代码里有个大规模重构AI 一次调用烧掉几十万 Token账单直接爆炸。Agnes Code 的 Token 上限设置在聊天界面上就能拉非常直观。关于本地模型我建议至少是 7B 以上参数的量化版本才有点实用性更小的模型跑起来只能做简单问答生成高质量代码基本没戏。Ollama 拉取模型后在 Agnes Code 的模型源里选“本地模型”设置一下端口就可以用了。离线环境下这个功能是救命的。4. 实操我用 Agnes Code 从零写了一个小工具4.1 任务目标与提示词设计光说功能不实操等于纸上谈兵。这次我拿一个真实任务来跑一遍完整流程写一个批量重命名图片文件的 Python 脚本要求支持多种命名规则、自动处理文件名冲突、带日期前缀还要有命令行参数。这个任务难度适中既有常规逻辑又有边界情况很适合展示 Agnes Code 的完整工作流。我给它的初始提示词是这样的写一个 Python 脚本批量重命名某个目录下的图片文件。支持以下参数--directory 指定目录--prefix 自定义前缀--date 是否添加日期前缀--dry-run 预览效果不真正重命名。 要求处理文件名冲突比如新文件名已存在时自动加序号。需要支持 jpg、png、gif 格式。脚本要放在项目根目录的 scripts 目录下。任务拆解这块我有一点经验要分享AI 编程助手对“边界情况”的处理能力取决于提示词里是否提前补充约束。如果你只说“批量重命名图片”它生成的代码八成没有冲突检查因为冲突处理是你自己脑补的需求它不是读心术。所以提示词阶段先把格式、约束、边界情况想清楚后面生成出来的代码质量会高非常多。4.2 一步步生成、调试、完善Agnes Code 生成的代码初版比较规整结构清晰能用但确实有些细节没到位。我逐项验证后发现两个问题第一个是它没有处理“新文件名和旧文件名重复加入序号”的情况如果目录里已经有IMG_001.jpg这种名字直接重命名会覆盖原文件第二个是日期前缀用了本地时间但没有处理时区问题严格来说不算 bug但对跨时区环境不够健壮。这两个问题我没有手动改而是直接继续在对话里追加指令“文件名冲突时不要覆盖自动往后加序号比如遇到 IMG_001.jpg 已存在就改成 IMG_001_1.jpg”然后让它重新生成完整脚本。这就是用对话式编程的正确姿势有问题就在上下文里补而不是重新开一个空白对话。当 AI 有之前对话的全部记忆时你只需要描述增量需求它就能精准修改这个体验比复制粘贴再改代码顺滑得多。第二版生成后我在一个测试目录放了十几张图片包括一张故意制造的名字冲突运行python scripts/batch_rename.py --directory /tmp/test_images --prefix holiday --date --dry-run输出结果完全符合预期冲突文件自动变成了holiday_20250115_003_1.jpg这种形式。确认无误后去掉--dry-run正式执行所有文件都按规则重命名成功。4.3 这一轮实操里我验证出的提示词套路这一轮实操下来我验证了几个对 Agnes Code 相当有效的套路分享给大家第一任务描述里一定要写清楚“输入是什么、输出是什么、中间经过什么处理”。有些朋友习惯丢一句“帮我写个脚本”然后 AI 生成一堆泛泛的代码这不是 AI 笨是输入信息不够。信息密度越高输出质量越高这条反复被验证。第二把约束条件前置。比如文件格式限制、不得覆盖、输出日志格式、Python 版本兼容性这些条件在提问时就要给全否则后期改起来一步一个坑。第三需求变更时不要新开对话要在同一对话里继续追问。Agnes Code 的会话记忆很强新开对话意味着它忘了前文的约定很可能给你一版风格完全不同的代码。第四生成代码后要求它“解释关键逻辑”。这个技巧很好用一方面你自己能确认它写的逻辑是不是符合需求另一方面解释的过程也能发现潜在问题相当于白赚一次代码审查。5. 常见问题与排错实录5.1 我实际踩过的几个坑用 Agnes Code 这几周我至少踩了四五个坑挑几个有代表性的说一下。第一个坑是模型源配置成功后没生效。我改完 JSON 配置重载了窗口但聊天框里切换到自定义模型时一直报错提示模型不存在。排查了半天发现是模型名称写错了我写的名字和 API 服务商返回的模型列表对不上。解决方法是先调用一下 API 服务商的模型列表接口把返回的模型名原样填进去不要凭记忆写。第二个坑是本地模型连接失败。Ollama 默认监听 11434 端口但我配置代理环境变量后请求被代理拦截了。Agnes Code 请求本地模型时走了系统代理结果代理又没法访问本机地址就是localhost流量被代理劫持的经典问题。这个问题的排查思路比较绕最终我在终端里关掉了代理相关的环境变量才解决的。如果你也遇到本地模型一直连接失败先怀疑代理再去折腾配置。第三个坑是 AGENTS.md 文件不生效。我一开始把文件放在项目根目录但发现它读不到。后来查文档才发现 Agnes Code 对规则文件的命名和位置有约定文件名必须精确匹配不能加后缀。位置也要放在工作区根目录放在子目录里是读不到的。改了位置之后效果立竿见影。5.2 问题速查表为了方便大家对照排查我把这段时间遇到的问题汇总成一张速查表现象可能原因解决办法安装后没有侧边栏图标扩展未激活或版本过旧重启窗口检查扩展版本并更新对话面板一直转圈不回复网络问题或模型源 Key 失效检查网络连接检查 API Key 是否有效补全建议不出现触发灵敏度设置过低或语言不被支持调高灵敏度确认文件语言模式正确本地模型连接失败代理拦截 localhost 流量临时关闭代理或在本地请求中绕过代理自定义模型报“模型不存在”模型名称填写错误调接口确认模型列表原样填写名称AGENTS.md 不生效文件名或位置不对精确命名为 AGENTS.md放在工作区根目录生成代码不遵守项目规范缺少上下文规则配置 AGENTS.md或在提问时明确约束条件上下文丢失答非所问新开了对话尽量在同一对话内继续追问避免上下文断裂5.3 一些值得长期保留的使用习惯用了一段时间后我慢慢养成了几个固定习惯对工作流提升帮助很大。每次接一个新项目第一件事就是建好AGENTS.md把项目的技术栈、目录约定、编码规范写进去。这相当于在给 AI 做“岗前培训”虽然花半小时但后续 AI 生成的代码质量稳定下来节省的时间远超这半小时。重要对话我会用“分项目建会话”的方式管理。Agnes Code 的会话列表可以按项目归类每个项目一个会话这样上下文不会互相污染。我之前在同一个会话里既有公司项目的问题又有个人项目的需求结果 AI 经常把公司项目的目录结构带到个人项目的回答里问得多了才发现是两个项目串了。生成代码后我会先要求它“快速自查”再读代码。Agnes Code 支持让模型自己审查一遍自己生成的代码虽然不能完全替代人工审查但能过滤掉很多低级错误比如未定义的变量、缺失的 import、明显的逻辑漏洞。6. 免费额度够不够用以及后续还能怎么玩6.1 免费额度个人开发者完全够用很多人最关心的就是免费额度到底够不够用。以我这段时间的使用来看单纯写代码、改 bug、写测试日常的小项目强度完全够用。我一周大概有 3 到 4 个晚上写代码每次持续一两个小时用的是官方免费模型月底看额度统计基本还剩下一半左右。不过要留意的是免费额度有限流策略连续请求太频繁时会变慢。我的经验是生成几百行代码的大任务时建议拆分来问一次性让它生成一个完整的大文件响应时间会明显拉长而且生成质量也容易打折。拆成几个小函数分几次对话生成整体效果反而更好还不太消耗额度。6.2 它还能怎么玩自定义指令与协作场景Agnes Code 对高级玩法支持得不错不只是最简单的“问一句答一句”。你可以通过配置自定义指令把复杂的提示词模板保存成快捷键指令比如一键生成单元测试、一键补充函数注释、一键做代码重构。这样日常操作基本不用打字一个快捷键就能触发标准化的 AI 行为。其次它支持 CLI 模式可以在终端里直接调用这对那些习惯用 Neovim 或者 JetBrains 系列的用户来说是一个不错的补充路径。虽然它不是原生扩展但 CLI 方式能在不同编辑器里共用一套 AI 配置。团队协作场景Agnes Code 也给了很实用的支持。它支持会话分享可以把一次排错过程导成 Markdown 文件发给同事整个排查链路非常清晰。我上周帮同事排查一个诡异的线上问题就是用这种方式把 Agnes Code 的整个分析过程分享到群里大家一眼就看明白了问题所在省去了大量的口头描述成本。6.3 我对免费工具的态度不迷信但也不错过这几周用下来我的体感是 Agnes Code 已经在大部分日常场景里做到了“能用”而在接入方式和成本控制上做到了“好用”。它没有 Cursor 那么惊艳的自动补全也不像 Copilot 那样与编辑器深度耦合但一个免费、开放、可控的 AI 编程助手对独立开发者和中小团队来说已经是非常务实的方案。我个人的建议是别急着把主力工作流切到一个新工具上但可以把它作为 Copilot 之外的备选在个人项目或者非核心代码上先试一周。等你习惯了它的斜杠命令、行内对话这些操作方式再决定要不要全面切换。一个好的工具不是让你改变习惯而是让你现有的习惯变得更强。Agnes Code 至少在这个方向上做了不少扎实的事。