用文心快码给 FastAPI 订单服务加 CSV 导出接口

文心快码（Comate）是百度推出的 AI 编程助手，提供三种产品形态：独立的 Comate 客户端、VS Code / JetBrains / Visual Studio / Xcode 等 IDE 的插件，以及面向终端的 Comate CLI。它要解决的问题很具体：让 AI 不只是补全一行代码，而是能读懂你项目里的多个文件，按一个可审阅的计划去改路由、改 service、补测试，并自己跑命令验证结果。这篇教程适合刚接触 AI 编程、希望把工具真正用进日常业务开发的人，也适合已经在用补全插件、但还没试过让 Agent 跨文件改动的开发者。站内可参考文心快码的工具条目了解基本信息。

全文围绕一个真实任务展开：给一个已有的 FastAPI 订单服务新增「导出订单为 CSV」的接口，要求带时间范围参数校验、大数据量流式返回，并补上对应的单元测试。这个任务会同时动到路由、service、schema 和测试文件，是典型的多文件改动，正好能把上下文引用、Plan 对齐、Spec 分阶段执行、自动跑测试这几件事一次练完。文中涉及的价格、额度、模型可用性等信息会随时间变化，请以官网当前信息为准。

准备工作

开始之前，先把下面几样东西备齐。缺任何一项，后面的步骤都会卡住。

项目	要求	说明
操作系统	Windows 10/11、macOS（Intel 与 Apple Silicon）、主流 Linux 发行版	客户端与插件均覆盖三端
IDE（走插件路径才需要）	VS Code、JetBrains 全家桶、Visual Studio、Xcode 等 10 余款主流 IDE	建议升到近两年的版本，过旧的 IDE 会导致插件面板挂载失败
账号	一个百度账号	个人免费额度即可跑通本文全部步骤
网络	能访问 comate.baidu.com	公司内网走代理的，先把代理信息准备好
磁盘	预留 2GB 以上	客户端本体加代码索引缓存

需要企业授权的只有三类能力：私有化部署、企业级 Agent Hub（包含 Agent、Plugin、Skill、MCP、Rules、Command、最佳实践等扩展组件，配套安全扫描与资产治理），以及成员管理与用量审计。个人学习和小项目开发用不到这些，直接往下走即可。

另外准备一个可以本地运行的 FastAPI 项目，至少包含订单路由文件、service 层、schema 定义和一个已有的接口作为风格参考。项目要能在本地装上依赖并跑起测试，否则后面 Agent 执行命令验证时会失败。

操作步骤

第一步：先选形态，别急着点下载

三种形态选错，是新手第一次上手不顺的常见原因。

形态	适合谁	能力覆盖
Comate 客户端	愿意把 AI 当主力工作台，任务偏复杂、跨多个代码库	Agent、Plan / Spec、多 Tab 对话、任务并行、网页预览等全套能力开箱可用
IDE 插件	不想换编辑器，只想在现有工程里加一个 AI 搭档	补全、行间指令、Agent 对话、上下文引用；与原有调试、Git、运行配置完全共存
Comate CLI	习惯在终端工作，要做脚本化调用或接入 CI	命令行内完成对话与任务执行，便于写进自动化流程

建议很直接：日常在 VS Code 或 JetBrains 里写业务代码，先装插件；想完整体验 Agent 自主跑任务的过程，装客户端。两者账号互通，装了一个之后再补另一个不需要重新配置。

第二步（路径 A）：安装 Comate 客户端

打开官网，首页有「下载客户端」入口，页面会自动识别系统并给出匹配的安装包。

macOS：下载 .dmg 后打开，把 Comate 图标拖进「应用程序」。首次启动被拦下提示「来自身份不明的开发者」时，去「系统设置 → 隐私与安全性」页面底部点「仍要打开」。Apple Silicon 机器请确认下载的是对应架构的包，装错架构会启动缓慢。
Windows：双击 .exe 按向导安装即可。SmartScreen 弹窗拦截时点「更多信息 → 仍要运行」。安装路径尽量别放在中文目录或 OneDrive 同步目录下，索引缓存写在同步目录里会拖慢首次打开项目的速度。
Linux：按发行版选择对应安装包，装完从应用菜单或命令行启动。

首次启动客户端会让你选择一个工作区目录，直接指向现有项目的根目录。它需要这个目录来建立代码索引，索引完成后才能做跨文件的分析和改动。第一次索引一个中型仓库通常需要几十秒到几分钟，期间可以先去登录。

第三步（路径 B）：在 IDE 里装插件

官网「下载插件」入口分别提供 VS Code、JetBrains、Visual Studio、Xcode 四条路径，也可以直接在 IDE 的插件市场里搜。

VS Code：侧边栏点扩展图标（Cmd/Ctrl + Shift + X），搜索 Comate 或文心快码，认准发布者为 Baidu 的官方插件，点 Install。安装后侧边栏会出现 Comate 图标；如果没出现，用命令面板（Cmd/Ctrl + Shift + P）执行 Reload Window 重载一次窗口。

JetBrains 系（IDEA / PyCharm / GoLand / WebStorm 等）：Settings/Preferences → Plugins → Marketplace，搜索 Comate 安装，点 Restart IDE 重启生效。重启后工具窗口会多出 Comate 入口。

Visual Studio 与 Xcode：从官网对应入口下载安装包，按引导安装后重启 IDE。这两个 IDE 的用户建议直接走官网入口，市场内的搜索结果容易混入同名的第三方扩展。

装好之后先别急着写代码，把编辑器里的其他 AI 补全插件临时禁用。两个补全插件同时抢 Tab 键是新手最容易遇到、又最难自己想明白的问题——表现是建议闪一下就消失，或者按 Tab 插入的是另一家的结果。

第四步（路径 C）：装 CLI，在终端里验证一次

CLI 的安装方式以官网下载页和官方文档给出的命令为准，不同系统的包管理方式不同，直接照文档执行最稳。安装完成后在终端执行 CLI 的入口命令，进入交互式会话，先输入一句「列出当前目录的项目结构并判断技术栈」作为连通性测试。

CLI 的价值在两个地方：一是可以写进 shell 脚本或 CI 流程，让代码检查、注释补齐、变更总结这类重复动作自动跑；二是在没有图形界面的远程开发机上，只有它能用。纯新手可以先跳过这一步，等插件用熟了再回来补。

第五步：登录，并确认你手上有多少额度

三种形态的登录方式一致：点面板里的登录按钮 → 浏览器自动拉起百度账号授权页 → 授权成功后回到客户端或 IDE，面板顶部出现你的账号信息即完成激活。

登录成功后马上做一件事：打开设置里的账号与模型页面，确认当前生效的模式与可用额度。个人用户可以使用 Auto 免费模式，具体是否限时、是否限量以官网当前说明为准，日常写业务代码、跑中小型 Agent 任务通常够用。想指定更强的模型跑复杂重构，在对话框上方的模型选择器里切换，不同模型的额度消耗不同。建议第一天就把额度看清楚：先用免费模式建立手感，遇到真正复杂的任务再切高配模型，比一上来就把额度烧在简单任务上划算。

登录卡住的处理办法：浏览器授权完成但客户端一直转圈，先确认网络能访问 comate.baidu.com，内网用户在设置里填好代理；仍然不行就清掉该站点的 Cookie 重新发起一次登录。

第六步：把上下文喂对，这一步决定输出质量

AI 看不到你的整个项目，它只看到你交给它的那部分内容，所以「给什么」比「问什么」更关键。文心快码把添加上下文的方式统一成了 @ 指令，在对话框里输入就会弹出可选的上下文类型：

单个文件或目录：改一个模块时最常用，精确到文件比丢整个项目更快也更准。
选中的代码片段：在编辑器里选中一段函数体再引用，适合「这段为什么慢」「帮我加异常处理」这类问题。
整个工程：让它先摸清项目结构时用，代价是响应变慢，别当默认习惯。
知识集 / 文档：把团队的接口文档、设计规范、数据库表结构说明挂进来，Agent 会自动检索相关内容再回答。内置的文档检索 Sub agent 会调用目录列表获取、文档读取、语义检索这些工具，在知识集里定位到具体段落，而不是笼统地凭训练记忆答题。
联网内容：需要查第三方库的最新用法时，Explore 能力支持网页搜索与网页抓取，把实时资料带进这一轮对话。

再花两分钟配一个 rules 文件，把项目里那些每次都要重复说明的约定写进去：用什么包管理器、日志怎么打、错误怎么抛、注释用中文还是英文、哪些目录不许改。规则写一次长期生效，比每轮对话粘贴一遍前提条件省事得多，也能显著降低生成结果跟项目风格打架的概率。对本文的 FastAPI 任务来说，rules 里至少要写清 Python 版本、依赖管理工具、测试命令（例如 pytest）以及数据库迁移目录不可自动修改。

第七步：跑通第一个真实任务

演示任务不用 Hello World，那种例子跑通了也说明不了什么。这里用一个贴近日常的需求：给已有的 FastAPI 订单服务加一个「导出订单为 CSV」的接口，要求带时间范围参数校验、大数据量流式返回，并补上对应的单元测试。

1. 先用 Plan 模式对齐，别让它直接开写

在对话面板切到 Plan 模式，把需求原样说清楚，然后引用相关文件：现有的订单路由文件、service 层、以及一个已有的接口作为风格参考。Plan 模式的行为和普通对话不同——它会主动提问澄清需求。比如它可能反问：导出的时间范围是按下单时间还是支付时间？超过多少条走流式返回？是否需要鉴权？这些问题恰好是新手写需求时最容易漏掉的部分。回答完之后，它基于目标给出任务规划，你确认计划再执行，整体结果会明显更贴合预期。

新手常犯的错是跳过这一步直接说「帮我加个导出接口」，结果拿到一个能跑但字段对不上、分页策略不对的实现，返工比自己写还慢。

2. 切到 Spec 模式，让过程变成可审阅的四段

方案对齐后切换 Spec 模式，开发过程会拆成四个明确阶段：

Doc（对齐方案）：先产出技术方案文档，写清改哪些文件、接口怎么定义、异常怎么处理。这份文档你可以直接改，改完再往下走。
Tasks（拆解任务）：方案确认后自动拆成可执行的任务列表，比如「新增 CSV 序列化工具」「扩展 schema 增加时间范围校验」「新增路由并接入 service」「补三条单测」。
Changes（按计划执行）：任务可以逐个执行也可以批量执行，随时暂停、调整或回滚。从右侧的单文件改动列表点进去会直接定位到对应文件，省掉来回找文件的切换成本。
Summary（总结复盘）：全部执行完自动生成变更总结，改了哪些文件、为什么这么改一目了然，提交 MR 时直接拿来写说明。

Spec 模式最大的价值不是快，而是把黑盒变白盒：每一步都看得见，风险在方案阶段就暴露，而不是等代码全写完才发现方向错了。多文件修改、复杂功能开发、架构重构这类任务都适合走这条路。做跨文件重构这类任务时，模型调用的 token 消耗会比日常补全高不少，可以在千帆大模型平台文档里查计费与配额说明，用来估算单次任务成本。

3. 让它自己验证

任务列表里一定要留一条「运行测试并修复失败用例」。Agent 可以自己执行命令，跑 pytest 看结果、读报错、改代码、再跑一遍，这个闭环是它和纯代码生成工具的分界线。你要做的是审代码，不是替它跑命令。

第八步：把工具接进来，让它从「会写代码」变成「能干活」

第一个任务跑通后，值得再花十分钟做扩展配置，这是拉开使用深度的地方：

Skill：把团队里那些有固定套路的活封装成技能，比如按公司规范生成接口文档、按模板补单测，之后一句话触发。
MCP：接入外部系统的标准协议，数据库、浏览器、内部工单系统都能挂进来。添加后会为所有官方 Agent 默认开启，不用逐个 Agent 配；需要在多个项目里复用的，直接创建跨 Workspace 的全局 MCP，装一次全局可用。
自定义 Agent：官方 Agent 覆盖问答、规划、编码等核心场景，可以切换也可以在对话内共享上下文；跑得多了之后，把你自己那套习惯沉淀成专属 Agent，配上对应的 rules 和工具，调用工具没有数量上限。

第九步：多任务并行与定时执行

单线程用 AI 是浪费。这几个能力配合起来才是真实工作节奏：

多 Tab 对话：在 Mission 模式下同时开多个会话各干一件事，一个跑重构、一个查 bug、一个写文档，对话多了支持滚动切换。
任务模式与多库绑定：同一工作区可以绑定多个代码库，同一时间并行推进多个任务，状态实时可见，前后端两个仓库的联动改动不用来回切窗口。
Spec 列表：所有 Spec 会话集中管理，昨天没跑完的任务今天点进去接着走。
定时自动化任务：把重复性的活配成定时任务，例如每天早上扫一遍新提交的代码风格问题、每周生成一次变更摘要。

做前端的话还有两个能力值得单独试：网页预览里可以直接点选页面元素、输入指令改样式，改完即时看到效果；打开 Figma 链接后能点选设计稿元素加入对话，由 Figma2Code 生成语义清晰、样式精准的前端代码，省掉反复对齐设计稿的沟通。想从零搭页面，Page Builder 智能体把需求描述清楚就能产出可用的页面。

一个完整示例

把上面的步骤串起来，一次完整的操作流程是这样的。

第 1 步：打开项目并等待索引。在 VS Code 里打开 FastAPI 订单服务仓库，确认侧边栏 Comate 图标已出现、面板顶部显示账号信息。首次打开时等待索引完成，索引没完成就发起跨文件任务，结果会明显变差。

第 2 步：写 rules。在项目根目录配置 rules 文件，内容大致如下（具体字段名以工具当前版本为准）：

包管理器：uv
Python 版本：3.11
测试命令：pytest -q
日志：使用项目内 logger，不要 print
注释语言：中文
禁止自动修改：alembic/ 目录、.env、生产配置文件

第 3 步：Plan 模式对齐需求。切到 Plan 模式，输入需求并引用文件：

给订单服务新增导出 CSV 的接口，要求：
1. 支持 start_time / end_time 查询参数，按下单时间过滤，格式为 ISO 8601
2. 参数校验失败返回 422
3. 数据量超过 10000 条时使用 StreamingResponse 流式返回
4. 补三条单元测试：正常导出、时间范围非法、空结果

参考文件：
@app/orders/router.py
@app/orders/service.py
@app/orders/schema.py
@app/orders/test_orders.py（作为风格参考）

它会反问澄清问题，例如时间范围是否包含边界、CSV 用逗号还是分号、是否需要鉴权。逐条回答后，它给出任务规划，你确认无误再进入下一步。

第 4 步：Spec 模式执行。切到 Spec 模式，先审 Doc 阶段产出的技术方案：新增哪个路由路径、schema 里加什么字段、流式返回怎么实现、异常怎么处理。方案有偏差就直接改文档，改完再让它拆 Tasks。Tasks 列表里应包含「新增 CSV 序列化工具」「扩展 schema 增加时间范围校验」「新增路由并接入 service」「补三条单测」「运行测试并修复失败用例」。

第 5 步：逐个执行并审阅。在 Changes 阶段逐个执行任务，每完成一个就点进右侧改动列表看具体 diff。涉及依赖或配置的改动不要批量跑，逐个验证。

第 6 步：看 Summary。全部执行完后查看自动生成的变更总结，确认改了哪些文件、为什么这么改，直接拿去写 MR 说明。

第 7 步：自查。拿下面七条对照，全部成立说明你已经能把它用进日常工作：

编辑器里输入代码时能看到灰色补全建议，Tab 可采纳，且没有和其他插件抢键。
面板顶部稳定显示你的账号，不会反复掉登录。
输入 @ 能弹出上下文选择，你知道什么时候引用单文件、什么时候引用整个工程。
Plan 模式下提出需求后，它会反问澄清问题，而不是直接开始写代码。
Spec 模式跑完一个任务后，能看到 Doc、Tasks、Changes、Summary 四段完整产出。
Agent 能自己执行命令跑测试，失败后能读报错并继续修。
你知道改错之后从哪里回滚，而不是靠 git checkout 兜底。

第 7 条最容易被忽略，但它决定你敢不敢把复杂任务交出去。回滚机制支持细粒度回退——可以退到某一次提示词执行之前，也可以退到某一次工具调用之前的代码状态。心里有这个底，才敢让 Agent 一次改十个文件。

注意事项

对话越聊越笨，长文件的回答被截断

现象：一开始回答很准，聊到七八轮之后开始答非所问，或者引用一个几千行的文件后回答明显不完整、只处理了文件开头的部分。

原因：上下文超限。单轮对话能携带的内容有上限，塞进去的内容越多，模型分给关键信息的注意力越少。

解法：

别用整个工程当默认上下文。改单个模块时用 @ 精确引用相关文件，甚至只选中要改的那个函数。
长文件先让它定位。先问「这个文件里负责订单状态流转的是哪几个函数」，拿到范围后只引用那几段代码。
一个任务一个 Tab。任务切换时开新对话而不是在旧会话里继续追问，把上下文重置干净。
复杂需求走 Spec 模式。它把任务拆成多个小步分批执行，每步的上下文压力都比一次性丢给它小得多。
长期约定写进 rules，而不是每轮粘贴。这既省上下文，也避免不同轮次说法不一致。

Agent 执行命令失败，但文件已经被改了一半

现象：任务跑到执行阶段报错——依赖没装、命令找不到、Python 或 Node 版本不对，此时部分文件已经写入改动，项目处于跑不起来的中间状态。

原因：Agent 默认按项目现状执行命令，本地环境缺依赖或版本不匹配时，命令自然失败。

解法：

先回滚到干净状态。用细粒度回滚退到出错那次工具调用之前，而不是手工一个个撤销改动。
让它先补环境。回滚后加一句「先检查依赖是否完整，缺失的先安装再继续」，把装依赖变成任务列表的第一项。
把环境信息写进 rules。包管理器、运行时版本、启动命令、测试命令都写清楚，之后每次执行都会按这份约定走。
高风险任务用单任务执行。Spec 模式下不要批量跑完所有任务，涉及数据库迁移、依赖升级、配置文件改动的任务逐个执行、逐个验证。
敏感文件放心一点。Agent 的工具安全机制会阻止对敏感文件的非法写入与修改，但生产配置这类文件，仍然建议在 rules 里显式标为不可改。

其他需要留意的点

过旧的 IDE 会导致插件面板挂载失败，装插件前先确认 IDE 版本。
Windows 上把安装路径放在中文目录或 OneDrive 同步目录会拖慢索引，首次打开项目尤其明显。
同时启用多个 AI 补全插件会争抢 Tab 键，装好后先禁用其他补全插件。
企业级能力（私有化部署、Agent Hub、成员管理与用量审计）需要单独授权，个人使用不必考虑。
模型额度、免费模式的时限与限量、各模型的消耗倍率会调整，使用前请以官网当前信息为准。

从下载到跑通第一个 Spec 任务，真正需要练的只有一件事：把「我自己一行行写」换成「我给一个清晰的目标、审它的产出」。补全、上下文引用、Plan 对齐、Spec 执行、回滚这五个动作各练一遍，工具就从玩具变成了生产力。