在 Claude Code 里让 frontend-developer 这个自定义 Agent 干活翻车点通常不在提示词写得漂不漂亮而在两件更底层的事Agent 定义里有没有把团队的技术栈和规范写死以及模型请求到底从哪条通道出去。TaoTokenhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_end解决的是第二件事——先把出口和 Key 定下来再谈角色人设顺序反了就会一直卡在限额和排队上。原教程《记忆系统与 Agent 定制完全指南四自定义 Agent 开发一》的 3.3 节给了个很干净的切入点写完.claude/agents/frontend-developer.md之后用frontend-developer触发让 Claude Code 按 Vue3 Composition API TypeScript 规范生成一个设备列表页。这段把角色怎么写讲透了却没有交代这次生成的模型请求从哪条通道发出去——默认情况下走官方通道额度见底就开始限流报错切模型、换 Key 的动作全堆在同一个地方。所以这篇按原教程的目录节奏往下走一遍先讲清楚内置 general-purpose 为什么不够用再拆 frontmatter 和角色正文然后给 Claude Code 换一条稳定的模型出口最后用设备列表页把frontend-developer完整跑通并验收。动手之前先做一件小事打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册账号并创建一把 API Key本文里统一记作YOUR_API_KEY后面的配置文件都要填它。1. Claude Code 内置 general-purpose 为什么写不出设备列表页1.1 它什么都会一点但不知道你们的技术栈general-purpose 是 Claude Code 的默认通用 Agent能力面铺得很宽读文件、搜索、改代码、跑命令都能接。问题恰恰出在这个全能上——它没有立场也就没有偏好。你让它做一个设备列表页它可能给你script setup也可能顺手写成 Options API可能用ref接整个表单对象也可能用reactive接一个需要整体替换的数组请求层可能老老实实调你们的request封装也可能在组件里直接fetch(/api/device/list)。这些选择单看都不算错但放进一个有既有约定的仓库里就是每次 review 都要返工的噪音。更要命的是它不认识你们的目录结构。组件放src/components/还是src/views/device/components/接口类型放src/types/还是跟接口同文件组合式函数叫什么名字——通用 Agent 会按自己的习惯猜猜错一次你就得手动搬一次文件。团队越大这种风格漂移的维护成本越高。1.2 3.3 节没交代的那一层模型请求从哪条通道出去原教程 3.3 节的演示停在Agent 按规范生成了页面这一步读者照着做也能看到产出。但只要你连着生成三五个页面很快就会撞上另一个问题这次调用的模型是谁、额度从哪扣、换模型要不要改代码。Claude Code 默认把请求发往官方通道ANTHROPIC_BASE_URL不配就走默认值。额度用完的表现不是一句清晰的报错而是超时、429、生成到一半断掉。这时候你去翻.claude/agents/frontend-developer.md是找不到答案的因为问题根本不在 Agent 定义里而在客户端的环境配置里。两件事得分开处理Agent 定义负责产出像不像你们团队的代码通道负责这次产出能不能稳定地跑完、消耗记在谁头上。通道这一层用 TaoToken 的兼容通道接管填一个 Base URL 就能继续用同一套 Claude Code 工作流不用改 Agent 文件里的任何一行。2. .claude/agents/frontend-developer.md 的 frontmatter 怎么填2.1 name、description、tools、model 四个字段各自管什么Agent 文件放在项目的.claude/agents/目录下会被团队共享跟着 Git 走放在~/.claude/agents/则是你自己的全局 Agent。同一个名字两处都有时项目级的通常优先所以团队规范建议一律放项目里。文件顶部的 frontmatter 只有四件事要交代字段作用填写要点name触发时用的标识小写加连字符与文件名保持一致触发写法是frontend-developerdescription决定这个 Agent 什么时候被选中写什么场景用它不是写它是什么把触发关键词放进去tools工具白名单前端生成任务给Read, Grep, Glob, Edit, Write就够别顺手把 Bash 也开出去model这个 Agent 用哪个模型可以写inherit跟随主会话也可以指定模型 ID具体 ID 以模型广场当时列表为准tools这一项值得多说一句。不少教程为了让 Agent更强大把 Bash 甚至写文件的权限全打开结果 Agent 会主动去跑npm run build、改.env甚至在没被要求的情况下尝试连远端环境。前端开发 Agent 的职责是产出代码构建、部署、连库这些动作应该由你自己在本地决定什么时候执行。2.2 description 写不对frontend-developer 就不会被选中很多人写 description 时会写成一个前端开发 Agent这等于没写。Claude Code 判断要不要把这个任务委派给某个 Agent靠的就是 description 里描述的场景和关键词。比较实用的写法是把触发条件和边界一起写进去比如用于生成或修改 Vue 3 TypeScript 前端页面、组件与组合式函数。当任务涉及列表页、表单页、详情页、接口封装、路由与状态管理时使用不负责后端接口实现、构建与部署。前半句是什么时候用我后半句是什么时候别用我。后者同样是提高命中率的关键——当你说帮我改一下接口返回结构时Claude Code 会根据边界判断这该由主会话处理而不是把这个活派给前端 Agent。还有一个高频失误是 YAML 语法冒号后面必须留空格值里出现中文冒号或双引号容易解析失败缩进用空格不要用 Tab。frontmatter 一旦解析失败这个 Agent 在列表里就是残缺状态半天也出不来。3. 角色正文把 Vue3 Composition API TypeScript 规范写死3.1 身份、技术栈、目录约定三段式frontmatter 下面的正文是 Agent 的岗位说明书。原教程演示的是生成设备列表页那我们就按这个任务把正文拆成三段身份、技术栈、目录约定。身份段一句话说明它是谁、对什么负责例如你是 XX 团队的前端工程师负责后台管理系统的页面与组件开发只产出代码和修改建议。这段决定了它说话的语气和边界感写得越具体它越不会越界去改构建配置。技术栈段要写死版本和写法Vue 3、script setup langts、Composition API、TypeScript strict、Pinia、Vue Router、统一封装的 Axios 实例。注意别写视情况使用 Options API这种留口子的句子Agent 一定会抓住这个口子。目录约定段是返工率下降最明显的一节。把页面、业务组件、接口、组合式函数、类型各自的落点写清楚它生成的路径才对得上你们的 import 别名。团队里有/别名就在这段里明确写出来否则它可能给你生成一堆../../..的相对路径。3.2 编码规范和禁忌清单规范部分用带序号的条目写比大段散文有效得多因为模型对列表结构的执行更稳定。可以参考这几条基本类型和需要整体替换的值用ref成组且不整体替换的表单对象用reactiveprops 用definePropsProps()事件用defineEmitsEmits()不要退回运行时声明组合式函数以use开头返回对象而不是数组异步逻辑一律async/await配try/catch错误提示走项目已有的 message 封装列表页必须实现 loading、空态、错误态三种状态。禁忌清单同样是提效项而且能当安全边界用。把这几条写进去不写 Options API、不混用this不在组件里直接fetch或新建 Axios 实例不修改src/api/request.ts、.env、vite.config.ts等公共配置不新增第三方依赖、不执行npm install不生成部署脚本、不连接任何数据库或服务器字段名和接口路径拿不准时先提问不要猜。最后一条拿不准就问很关键。设备列表页的状态字段到底是status还是state在不在线是用布尔还是枚举这些猜错了你就得从头改一遍。3.3 一份可以直接抄改的 Agent 文件把上面的内容拼起来.claude/agents/frontend-developer.md大致长这样--- name: frontend-developer description: 用于生成或修改 Vue 3 TypeScript 前端页面、组件与组合式函数。当任务涉及列表页、表单页、详情页、接口封装、路由与状态管理时使用不负责后端接口实现、构建与部署。 tools: Read, Grep, Glob, Edit, Write model: inherit --- # 角色 你是团队的前端工程师负责后台管理系统的页面与组件开发。只产出代码和修改建议不执行部署、不连接数据库、不运行构建脚本。 ## 技术栈 - Vue 3统一使用 script setup langts 与 Composition API - TypeScript 开启 strict禁止隐式 any - 状态管理 Pinia路由 Vue Router - 请求统一走 src/api/ 下的封装底层 Axios 实例已配置拦截器 - UI 组件库以项目现有依赖为准不引入新依赖 ## 目录约定 - 页面src/views/模块/index.vue - 业务组件src/components/模块/组件名.vue - 接口src/api/模块.ts - 组合式函数src/composables/use名称.ts - 类型优先与接口同文件跨模块复用的放 src/types/ ## 编码规范 1. 基本类型和需要整体替换的值用 ref成组且不整体替换的表单对象用 reactive 2. props 用 definePropsProps()事件用 defineEmitsEmits() 3. 组合式函数以 use 开头返回对象而不是数组 4. 异步逻辑用 async/await 配 try/catch错误提示走项目已有的 message 封装 5. 列表页必须有 loading、空态、错误态三种状态 ## 禁忌 - 不写 Options API不混用 this - 不在组件里直接 fetch 或新建 Axios 实例 - 不修改 src/api/request.ts、.env、vite.config.ts 等公共配置 - 不新增第三方依赖不执行 npm install - 不生成部署脚本不连接任何数据库或服务器 - 字段名和接口路径拿不准时先提问不要猜 ## 输出格式 先给出本次要新增或修改的文件清单和一句话说明再逐个文件给完整内容修改已有文件时只改必要部分并说明改了哪里。model写inherit是省事做法让这个 Agent 跟着主会话用同一个模型。想让它固定用某个更擅长写代码的模型就把inherit换成模型 IDID 从模型广场复制。4. 把 Claude Code 的模型出口切到 TaoToken4.1 创建 Key 和确认模型 ID注册和建 Key 都在 TaoToken 完成进控制台找到 API Keys新建一把复制出来存好这就是后面配置里的YOUR_API_KEY。Key 只在创建时完整展示一次复制的时候留意首尾有没有被截断字符串中间也不要有换行和空格。顺手做第二件事在模型广场里挑一个你要用的模型 ID。这个 ID 后面要原样填进配置所以别凭记忆手打。本文里统一用YOUR_MODEL_ID占位你实际填的值以模型广场当时列表为准。4.2 ~/.claude/settings.json 里的 env 怎么写Claude Code 读取模型出口的配置项是ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN和ANTHROPIC_MODEL。写进用户级配置文件~/.claude/settings.json的env字段里一次配好全局生效{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }三个值分别对应通道地址、你的 Key、默认模型。填完把YOUR_API_KEY换成 4.1 里复制的那串YOUR_MODEL_ID换成模型广场里真实存在的 ID。这里有一个必须记住的细节Base URL 填https://taotoken.net/api末尾不要加/v1。Claude Code 会自己在后面拼接具体路径你多写一段/v1就会拼出重复路径表现是请求 404 或者返回一堆看不懂的 HTML而不是明确的配置错误提示。4.3 环境变量方式以及别两处都写不想改配置文件的话用环境变量也能达到同样效果export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_MODEL_ID写进~/.zshrc或~/.bashrc就长期生效。Windows 上可以放进系统环境变量改动完记得重开终端旧终端读取的还是老值。要提醒的是环境变量和settings.json不要同时写两套不一样的值。两处都有时哪边生效取决于优先级一旦两边不一致你排查半天可能连自己改的是哪份配置都没搞清。建议只保留一处团队共享就走settings.json加 Git个人多环境就纯用环境变量。5. frontend-developer 触发设备列表页并验收5.1 触发语句怎么写配置保存后重开 Claude Code先确认 Agent 已经被识别——输入能看到frontend-developer出现在候选里就说明 frontmatter 没写坏。然后按原教程 3.3 节的思路下任务把要求写具体一点frontend-developer 在 src/views/device/ 下新增设备列表页 顶部关键字搜索表格列包含设备名、状态、最后在线时间分页每页 20 条 按项目规范实现 loading / 空态 / 错误态接口走现有 request 封装 完成后列出改动文件清单。触发之后模型请求就从https://taotoken.net/api这条通道出去了。Agent 读文件、写文件还是本地行为真正发往模型的那部分统一走 TaoToken 的兼容通道Token 消耗落在你自己那把 Key 上跟团队里其他人的用量互不干扰。5.2 对照产出规范有没有落地先看文件清单。如果它把接口类型写到src/api/device.ts、把列表逻辑抽到src/composables/useDeviceList.ts、页面落在src/views/device/index.vue说明目录约定那段起作用了。接口封装大概率长这样// src/api/device.ts import request from ./request export interface DeviceItem { id: string name: string status: online | offline | fault lastSeenAt: string } export interface DeviceListQuery { keyword?: string page: number pageSize: number } export interface DeviceListResult { list: DeviceItem[] total: number } export function fetchDeviceList(params: DeviceListQuery) { return request.getDeviceListResult(/device/list, { params }) }组合式函数应该把三态都带上而不是把 try/catch 摊在组件里// src/composables/useDeviceList.ts import { ref } from vue import { fetchDeviceList, type DeviceItem, type DeviceListQuery } from /api/device export function useDeviceList() { const list refDeviceItem[]([]) const total ref(0) const loading ref(false) const error ref() async function load(query: DeviceListQuery) { loading.value true error.value try { const res await fetchDeviceList(query) list.value res.list total.value res.total } catch (e) { error.value e instanceof Error ? e.message : 加载失败 list.value [] total.value 0 } finally { loading.value false } } return { list, total, loading, error, load } }如果你看到的是 Options API、组件里直接fetch、或者状态直接塞进reactive又整体赋值那就是规范没写死回到第 3 节补条目。5.3 一份简单的验收清单检查项期望结果文件落点页面、接口、组合式函数各自在约定目录语法风格全部script setup langts无this类型接口有显式类型无隐式any请求层调用src/api/下的函数没有裸fetch三态loading、空态、错误态都有对应渲染越界动作没有改.env、构建配置没有跑构建或部署命令任何一项不达标优先改 Agent 文件而不是在对话里反复纠正。Agent 文件是持久的对话里的纠正只对当前会话有效换个窗口就忘了。6. 三类报错Agent 不生效、401、路径 4046.1 不到 frontend-developer先看文件位置对不对项目级是.claude/agents/frontend-developer.md注意是agents复数、文件名用连字符。再看 frontmatter 有没有解析失败name和description是最容易被漏掉的两个字段缺了任意一个这个 Agent 就不会出现在候选里。冒号后没空格、缩进用了 Tab、值里带了没转义的引号都会导致解析中断。还有一种情况是 Agent 能出来但任务被主会话抢走了。这多半是 description 的场景描述太泛或者你的任务描述里几乎没有前端相关关键词。把触发条件写具体并在提问时明确带上组件、页面、接口这类词。6.2 401 和模型相关的报错按顺序查401 基本就是 Key 的问题排查顺序是ANTHROPIC_AUTH_TOKEN里填的是不是YOUR_API_KEY对应的真实 Key复制时有没有带进空格或换行这把 Key 是不是在控制台里被删了或者禁用了。顺手确认一下自己改的是哪份配置改了~/.zshrc却没重开终端是高频原因。模型相关的报错通常是 ID 写错。ANTHROPIC_MODEL必须填模型广场里真实存在的 ID别凭印象写一个带日期后缀的名字。这类报错的文案在不同工具里不一致最快的验证方式是拿同一把 Key 去模型对话页发一条测试消息能通说明 Key 和模型都对问题就只剩客户端配置。至于 404 或者收到一段 HTML九成是 Base URL 写错了。检查两点末尾是不是多加了/v1是不是误把官网落地页地址填进了ANTHROPIC_BASE_URL。填进工具的那个地址永远是https://taotoken.net/api不带查询参数。想拿 Key、看模型列表、查用量走官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_content 两个地址各管各的别混用。7. 跑通之后去控制台对一下这次生成的账7.1 用同一把 Key 做一次最小验证配置改完别急着上来就生成整个页面先在 模型对话 里用同一把 Key、同一个模型 ID 发一条最简单的消息。这一步能一次性排掉 Key、Base URL、模型 ID 三个变量里的两个剩下的问题基本都出在 Claude Code 本地配置上。回到 Claude Code让frontend-developer生成一个最小的组件然后去控制台看这次调用有没有记上账。看得见消耗说明请求确实从你自己的 Key 出去了而不是悄悄走了别的通道——这一步比能生成代码更能确认配置真的生效。7.2 长期写代码的下一步如果只是偶尔生成几个页面按量用就够要是一天到晚挂着 Claude Code 写业务代码可以打开 Coding Plan 看看套餐是不是更划算。需要多把 Key 分给不同项目或不同人用就在 控制台 API Keys 里分别创建一把 Key 一个用途排查问题时不至于互相牵连。ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL三个变量的完整对照和更多客户端写法可以翻 Claude Code 接入文档。文档里给的变量名和本文一致照着核对一遍比在终端里反复试错快得多。最后一句实在话Agent 定义和模型通道是两套独立的东西改完 Agent 文件觉得效果还是不稳先别怀疑提示词回头看看通道那一层有没有配对。规范写在文件里、请求走在自己 Key 上frontend-developer才会每次都用同一种方式干活。