用 CatPaw 完成项目级重构与 JWT 接口开发

CatPaw 是美团推出的 AI 集成开发环境，定位不是「补全插件」，而是一个能读懂整个项目的编码协作方。它通过代码库索引建立多文件之间的关系，再让 Agent 模式在回答问题时自动收集相关文件，而不是要求你先把代码高亮出来。如果你正在维护一个文件数量多、调用链长的项目，或者刚接手一份陌生代码库，这类项目级理解能力比逐行补全更有价值。本文按「准备 → 安装 → 核心功能 → 完整示例 → 注意事项」的顺序，把 CatPaw 的实际用法讲清楚。站内也有对应的工具条目，可以先看 CatPaw 的简介再往下读。

需要先说明适用范围：CatPaw 目前面向 macOS 用户，支持 Python、C++、Java、JavaScript、TypeScript、Go、Rust 等语言，擅长 Web 应用与常规业务代码；3D 图形、游戏开发这类细分场景表现一般。它采用交互次数配额制，新账号有初始额度，用完需要申请增加。价格、配额、平台支持等易变信息请以官网当前信息为准。

准备工作

账号与邀请码

CatPaw 处于公测阶段，注册需要邀请码。流程是：访问 CatPaw 官网，通过二维码加入社区（需要微信），随后在几分钟内收到邀请码。拿到邀请码后才能在客户端完成登录。

系统与硬件要求

• 操作系统：macOS 10.15 或更高版本，x64 与 arm64 均可。
• 安装包体积约 180MB，属于完整 IDE 而非轻量插件。
• Windows 版本在公测初期尚未提供，官方给出的时间点是 2025 年 11 月中旬，具体以官网当前信息为准。

登录与配额确认

首次启动会进入设置向导，登录需要手机号验证。登录完成后建议先确认剩余额度：打开 Settings → General → Quota，可以看到当前剩余的交互次数。新账号的初始额度是 500 次交互。这个数字会随运营策略变化，以客户端内显示为准。

从已有编辑器迁移设置

设置向导里提供从 VS Code 或 Cursor 导入配置的选项。快捷键、主题、部分编辑器偏好可以直接带过来，省去重新配置的时间。如果你长期使用 VS Code 系快捷键，建议在首次启动时就完成导入，避免后续两套键位混用。

操作步骤

第一步：安装客户端

1. 从官网下载 macOS 安装包。
2. 打开 .dmg 文件，把 CatPaw 拖入「应用程序」文件夹。
3. 首次启动会触发设置向导，按提示完成邀请码校验、手机号登录、设置导入。

整个安装过程不涉及额外的依赖安装，正常情况下不会出现依赖缺失或安装失败。

第二步：打开或克隆项目

有两种进入项目的方式：

• 本地目录：菜单 File → Open Folder，选择项目根目录。
• 远程仓库：直接从 GitHub 克隆到本地后打开。

已经打开多个项目时，通过左上角的下拉菜单切换。切换项目会触发对应代码库的索引，项目越大，首次索引耗时越长。

第三步：建立代码库索引

索引是 CatPaw 项目级理解的基础。打开项目后它会自动开始索引，索引完成后 AI 才能准确回答「用户认证逻辑在哪里处理」这类跨文件问题，并在补全时引用你项目里的工具函数。

索引速度的参考量级：几百行的小项目在 5 秒内完成；一万两千行左右的 Node.js 项目约 45 秒。索引过程会自动遵循 .gitignore 规则。

如果项目里有大量构建产物、依赖目录或日志文件，建议在项目根目录新建一个 .catpawignore 文件，把不需要分析的内容排除掉。排除无关文件后，索引速度会有明显提升，同时也能减少 AI 被噪声文件干扰的概率。一个典型的排除清单如下：

node_modules/
dist/
build/
coverage/
*.log
.cache/

索引完成后，补全与问答的准确度都会提升：AI 会按名字引用你已有的工具函数，也能在你写出重复实现之前提示「这个功能已经存在」。

第四步：区分 Ask 模式与 Agent 模式

CatPaw 有两种主要交互模式，用错模式会同时浪费配额和时间。

对比项	Ask 模式	Agent 模式
适用场景	语法问题、单点疑问，例如「这个 async 函数为什么没有 await」	多文件重构、架构问题、跨文件调试
上下文来源	需要手动高亮相关代码	自动扫描项目并收集相关文件
配额消耗	较低	较高
简单问题准确度	较高	—
跨文件场景表现	一般	明显更好

判断标准很简单：问题只涉及一段代码，用 Ask；问题需要同时看多个文件，用 Agent。把单文件问题丢给 Agent 会白白消耗配额，把跨文件重构交给 Ask 则容易得到片面的答案。

第五步：使用 Tab 补全

Tab 补全在正常编码过程中提供方法级甚至整段实现建议，并且会跟随项目已有的代码风格。实际使用中有几个特点值得注意：

• 建议出现在自然的停顿点，而不是每次按键都弹出。
• 响应速度在 100–200 毫秒量级。
• 会沿用项目内的命名习惯，例如 camelCase 与 snake_case 的选择。
• 会参考你偏好的写法，例如列表推导式还是传统循环。

局限也很明确：高度专业化的算法（例如自定义 3D 物理）容易得到泛泛的建议。模型对常见模式掌握得好，对细分领域则不够深入。

第六步：用浏览器预览减少切换

CatPaw 内置浏览器预览面板，前端项目可以直接在 IDE 内看到渲染结果，改动后自动刷新，不需要手动切到浏览器再切回来。

更省事的是元素定位流程：

1. 在预览面板中切换到 Edit 模式。
2. 直接点选页面上任意 UI 元素。
3. AI 侧边栏会收到该元素的详细信息。
4. 直接描述修改需求，不必再去文件树里翻找对应组件。

常规 Web 框架下这套流程工作良好。但 3D 场景（例如 Three.js）在预览中会出现性能下降，做 3D 与游戏开发时不要指望这个面板。

第七步：写好提示词

提示词的具体程度直接决定输出质量。对比下面两种写法：

• 模糊写法：「改进这段代码」。
• 具体写法：「把这个函数重构为 async/await，并为网络请求失败补充错误处理」。

后者给出了目标形态和边界条件，生成的代码通常可以直接使用。另外，遇到不常见的第三方库时，把该库的文档内容贴进对话，能避免 AI 调用过时的方法签名。

第八步：建立自定义模式

除了默认模式，还可以按用途建立自定义模式。例如建一个「代码审查模式」，把关注点限定在安全与性能上，得到的分析会比默认设置更细。团队里如果有固定的审查清单，把它固化进自定义模式可以减少每次重复描述的成本。

一个完整示例

下面用 Agent 模式从零搭一个带 JWT 认证的 Express REST API，包含任务资源的增删改查。这个示例能同时检验项目级上下文收集、代码生成和错误修复三项能力。

目标与时间分配

• 初始搭建（package.json、目录结构）：约 2 分钟。
• JWT 认证实现：约 8 分钟。
• CRUD 路由：约 5 分钟。
• 测试与修 bug：约 10 分钟。

合计约 25 分钟，手工从零写同类项目通常在 60–90 分钟。这个对比只说明流程效率，实际耗时取决于项目复杂度和你的审查强度。

步骤一：初始化项目骨架

新建空目录并在 CatPaw 中打开，然后在 Agent 模式里描述需求：

创建一个 Express 项目骨架，使用 ES Module，
目录结构分为 routes/、controllers/、middleware/、config/，
入口文件为 src/index.js，监听端口从环境变量读取。

生成后确认 package.json 的依赖与脚本是否符合预期，再执行安装：

npm install
npm run dev

步骤二：实现 JWT 认证

继续在 Agent 模式中提出认证需求，明确 token 的签发、校验与过期策略：

实现 JWT 认证：
1. POST /auth/login 接收 email 与 password，校验后签发 access token；
2. 新增 middleware/auth.js，从 Authorization: Bearer 头解析并校验 token；
3. 未通过校验统一返回 401，响应体包含 code 与 message；
4. 密钥从环境变量 JWT_SECRET 读取，不要硬编码。

生成完成后重点检查三处：密钥是否真的来自环境变量、过期时间设置是否合理、401 分支是否覆盖了 token 缺失与 token 失效两种情况。

步骤三：生成 CRUD 路由

为 tasks 资源生成 CRUD 路由，全部挂在 auth 中间件之后：
GET /tasks、GET /tasks/:id、POST /tasks、PUT /tasks/:id、DELETE /tasks/:id。
数据先用内存数组模拟，字段为 id、title、done、createdAt。

Agent 模式会自动读取前面生成的认证中间件与目录约定，把路由挂载到正确的位置，不需要你手动指出文件路径。

步骤四：测试与修复

启动服务后逐个接口验证。生成代码在首次运行时大约 85% 可以直接工作，剩余部分通常需要小幅调整，集中在边界情况处理上。示例中遇到的一个真实问题是 token 刷新逻辑里的过期判断写错了：把报错信息原样贴回对话，一轮交互内就能定位并修正。

修复后重新跑一遍登录、携带 token 访问受保护路由、token 过期后访问这三条路径，确认行为一致。

步骤五：把重构场景也走一遍

项目级理解在重构时体现得最明显。例如把一个 15 个文件的 Express 应用从回调风格迁移到 async/await：在 Agent 模式下描述迁移目标，CatPaw 会扫描相关文件，列出所有回调函数、给出迁移顺序，并标出可能产生竞态的位置。这类任务如果手动做，光是找出所有回调点就要花不少时间。

注意事项

配额消耗

Agent 模式的复杂查询消耗的交互次数明显高于 Ask 模式。新账号的 500 次交互看起来不少，但如果习惯把所有问题都丢给 Agent，消耗会很快。建议定期在 Settings → General → Quota 查看余量，在接近耗尽前申请增加，而不是等到被中断。配额数值与申请方式以官网当前信息为准。

安全代码必须人工复核

AI 生成的认证、鉴权、输入校验代码必须逐行人工审查，尤其是要上生产的系统。示例中的 token 过期判断错误就属于这类问题：代码能跑，逻辑却是错的。不要因为「测试通过」就跳过审查。

索引与忽略规则

索引是项目级能力的前提，但索引范围过大会拖慢速度并引入噪声。除了自动遵循 .gitignore，还应主动维护 .catpawignore，把构建产物、依赖目录、日志排除在外。项目结构发生大变动后，重新索引一次能避免 AI 引用已经不存在的文件。

不擅长的场景

• 3D 图形与游戏开发：预览面板性能下降，补全对细分算法帮助有限。
• 高度专业化的领域算法：容易得到通用化的建议。
• 需要 SSO、离线部署、审计日志的企业环境：当前版本不覆盖这些需求。

平台与成熟度

公测阶段仅提供 macOS 版本，Windows 用户需要等待后续版本。与已经迭代多年的编辑器相比，CatPaw 在协作编辑、Git 集成深度、插件生态方面仍有差距。把它当作早期工具来评估，先在小项目上验证工作流是否匹配，再决定是否迁移主力开发环境。

第三方库的时效性

模型对不常见库的方法签名可能停留在旧版本。遇到调用报错时，先把该库当前文档的相关段落贴进对话，再让 AI 修改，比反复试错更快。