1. 为什么要把 React 页面拆给 Subagents 做一个中等复杂度的 React 页面从零到能跑通常要同时处理三件互相纠缠的事组件结构怎么切、状态放哪一层、接口什么时候调。如果全塞给一个对话窗口模型很容易在“改组件的时候顺手动了 store改 store 的时候又忘了接口字段”最后你拿到一堆看似能跑、实则耦合严重的代码。Subagents子智能体解决的正是这个问题。它本质上是把一个大任务拆成若干个有独立上下文、独立工具权限、独立系统提示的“小助手”每个小助手只干一类活。放到 React 前端场景里我习惯拆成三类组件生成、状态管理、接口联调。组件生成只关心 JSX 和 props 类型状态管理只关心 store 结构和 action接口联调只关心请求封装、错误处理和字段映射。三者通过约定好的接口契约通信而不是互相读对方的实现细节。这套玩法的关键不在于“拆”而在于“拆完之后怎么统一调度、怎么统一鉴权”。Python 调度层负责把任务分发给对应的 SubagentTypeScript 执行层负责落地具体代码两边都要调模型如果各配各的 Key管理成本会迅速失控。所以这篇会围绕 TaoToken 的统一 Key 接入来讲把 config.toml 和 settings.json 两套配置骨架都给出来你照着填就能跑。适合谁看已经在用多智能体协作、但被 Key 管理和任务路由搞烦的开发者或者刚接触 Subagents、想找一个真实前端场景练手的同学。下面所有配置和命令都可以直接复制改掉路径和 Key 就能用。2. TaoToken 前置统一 Key 与两套工具链的接入点TaoToken 在这里扮演的角色是“一个 Key 打通 Python 和 TypeScript 两条工具链”。你不需要在 Python 侧配一套、在 Node/TS 侧再配一套也不用担心两边模型版本对不上。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个就行。接入前先做两件事。第一在控制台创建一个 API Key建议按项目命名比如react-subagents-dev方便后面排查是哪个环境在调。第二确认你要用的模型名Subagents 场景下组件生成和状态管理对模型能力要求不同可以先用同一个模型跑通再按需分流。Python 侧我用的是openaiSDK 的兼容写法因为大多数调度层代码都是这么写的迁移成本最低。TypeScript 侧用openai的 npm 包同样是兼容模式。两边的 base_url 都指向https://taotoken.net/apiapi_key 填同一个值。这样调度层和执行层共享配额、共享日志出问题只看一个地方。有一点要提醒不要把 Key 硬编码进仓库。Python 用环境变量或.envTypeScript 用.env.local加dotenv下面配置骨架里都会体现。如果你在 CI 里跑用 secrets 注入别图省事写死在 config 里。3. 可复制配置config.toml 与 settings.json 骨架先给 Python 调度层的config.toml。这个文件定义了三类 Subagent 的路由规则、模型参数和工具白名单。注意tools字段是给执行层看的调度层只负责把任务和工具集一起下发。# config.toml —— Python 调度层配置 [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读取不写明文 timeout 60 max_retries 2 [subagents.component] model gpt-4o-mini system_prompt 你是 React 组件生成专家只输出函数组件和 TypeScript props 类型不碰状态管理和网络请求。 tools [read_file, write_file] max_tokens 4096 [subagents.state] model gpt-4o-mini system_prompt 你是 React 状态管理专家只负责 store 结构、action 和 selector不生成 JSX。 tools [read_file, write_file] max_tokens 3072 [subagents.api] model gpt-4o-mini system_prompt 你是接口联调专家负责请求封装、错误处理、字段映射输出 TypeScript 类型和 fetch 封装。 tools [read_file, write_file, run_shell_command] max_tokens 4096 [router] # 关键词路由命中即分发到对应 subagent component_keywords [组件, JSX, props, 样式] state_keywords [store, reducer, context, 状态] api_keywords [接口, 请求, fetch, axios, 字段]再给 TypeScript 执行层的settings.json。这个文件放在项目根目录被执行脚本读取决定用哪个 Subagent 的产物、写到哪个目录。{ taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: gpt-4o-mini }, subagents: { component: { outputDir: src/components, fileExt: .tsx, tools: [read_file, write_file] }, state: { outputDir: src/store, fileExt: .ts, tools: [read_file, write_file] }, api: { outputDir: src/api, fileExt: .ts, tools: [read_file, write_file, run_shell_command] } }, router: { fallback: component, logLevel: info } }两个文件里的apiKeyEnv都指向同一个环境变量TAOTOKEN_API_KEY这就是“统一 Key”的落点。Python 侧用os.environ读TypeScript 侧用process.env读值一样来源一样。你可以在 shell 里这样设置export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key。设置完可以用echo $TAOTOKEN_API_KEY确认一下别带着空值去跑否则报 401 会浪费你十分钟。4. 子任务路由与结果回传的验证动作配置写完先别急着接真实 React 项目用一个最小任务验证路由和回传是否正常。Python 调度层我写了一个精简版核心逻辑是读任务描述 → 关键词匹配 → 选 Subagent → 调 TaoToken → 把结果和元信息回传。# dispatcher.py import os, json, tomllib from openai import OpenAI with open(config.toml, rb) as f: cfg tomllib.load(f) client OpenAI( base_urlcfg[taotoken][base_url], api_keyos.environ[cfg[taotoken][api_key_env]], ) def route(task: str) - str: r cfg[router] for kw in r[api_keywords]: if kw in task: return api for kw in r[state_keywords]: if kw in task: return state for kw in r[component_keywords]: if kw in task: return component return component def dispatch(task: str): name route(task) sub cfg[subagents][name] resp client.chat.completions.create( modelsub[model], messages[ {role: system, content: sub[system_prompt]}, {role: user, content: task}, ], max_tokenssub[max_tokens], ) return { subagent: name, content: resp.choices[0].message.content, usage: resp.usage.total_tokens, } if __name__ __main__: result dispatch(生成一个带排序和过滤的表格组件) print(json.dumps(result, ensure_asciiFalse, indent2))跑python dispatcher.py你应该看到subagent字段是componentcontent里是组件代码usage有 token 数。如果subagent是api说明关键词命中了“接口”之类检查一下你的任务描述里有没有误触发的词。TypeScript 执行层验证更简单写一个runner.ts读settings.json把调度层回传的 content 写到对应目录// runner.ts import fs from fs; import path from path; import settings from ./settings.json; type SubagentName component | state | api; export function writeResult(name: SubagentName, content: string) { const conf settings.subagents[name]; const dir path.resolve(conf.outputDir); fs.mkdirSync(dir, { recursive: true }); const file path.join(dir, generated-${Date.now()}${conf.fileExt}); fs.writeFileSync(file, content, utf-8); return file; }验证动作在 Python 里把dispatch的返回值传给一个 Node 脚本或者直接手动把 content 贴进writeResult调用。跑通后你会看到src/components/generated-xxx.tsx被创建打开有内容说明“调度 → 生成 → 回传 → 落盘”整条链路通了。这里有个细节回传的usage字段建议记到日志里按 Subagent 分类统计。跑几天你就能看出哪类任务最费 token然后针对性调max_tokens或换模型。我试过把组件生成的max_tokens从 4096 降到 2048大部分组件够用省下来的额度留给接口联调。5. 本篇常见错排查401 Unauthorized九成是环境变量没生效。Python 里os.environ读不到就抛 KeyErrorTypeScript 里process.env读到 undefined 会拼成Bearer undefined。先在终端echo $TAOTOKEN_API_KEY确认再检查是不是在错误的 shell 会话里 export 的。用.env文件的话确认dotenv在 import 之前就调用了config()。路由总是落到 component检查config.toml里router段的数组顺序。我的实现是 api → state → component 依次匹配如果你的任务描述里同时出现“组件”和“接口”会优先命中 api。这不是 bug是设计如此——接口联调通常包含组件改动让 api Subagent 处理更安全。如果你希望组件优先把component_keywords的循环提到最前面。生成的代码写不进文件settings.json里的outputDir是相对路径取决于你从哪个目录跑 Node 脚本。建议在runner.ts里用path.resolve(__dirname, conf.outputDir)固定基准目录别依赖 cwd。另外mkdirSync要加recursive: true否则目录不存在会直接抛错。Subagent 之间字段对不上这是拆任务时最容易踩的坑。组件生成输出的 props 类型和接口联调输出的响应类型如果命名不一致粘到一起就报类型错误。解决办法是在调度层加一个“契约检查”步骤让 api Subagent 先输出 TypeScript interface把 interface 作为上下文传给 component Subagent。这样两边共享同一份类型定义而不是各写各的。超时或重试次数不够config.toml里timeout 60对大多数任务够用但接口联调如果涉及读多个文件可能超过。把max_retries 2保留同时给run_shell_command类工具加单独的更长超时。别把 timeout 设成 300 这种大值出问题时会卡很久才发现。6. 把 Key 和路由固定下来再谈扩展跑通上面这套之后你手里其实有了一个可复用的骨架TaoToken 统一 Key 管住两条工具链的鉴权config.toml 管住 Python 侧的路由和模型参数settings.json 管住 TypeScript 侧的落盘规则。三者职责清晰改任何一处都不会牵动另外两处。接下来要扩展的话方向有两个。一是加 Subagent 类型比如“测试生成”或“样式抽取”在 config.toml 和 settings.json 里各加一段路由关键词补上就行不用动调度代码。二是把调度层从单机脚本改成常驻服务用 FastAPI 包一层暴露/dispatch接口TypeScript 侧通过 HTTP 调用这样多人协作时 Key 只在服务端存在前端拿不到明文。如果你还在选模型或对比不同 Subagent 的输出质量可以先用模型对话页面手动跑几个任务把 prompt 调顺了再写进 config。等路由稳定、要长期跑编码任务时再考虑用 Coding Plan 把配额和并发管起来。接入文档里有完整的参数说明和错误码表遇到本文没覆盖的报错对着查比盲试快。最后留一个我踩过的坑别在 Subagent 的 system_prompt 里写“你可以调用任何工具”。工具白名单是在 config 里控制的prompt 里写这句话只会让模型产生幻觉以为能读数据库或发请求。把 prompt 写窄把工具配准比写一堆“你是一个有帮助的助手”有用得多。 【智能体设计】用 Subagents 拆分 React 前端任务：TaoToken 统一 Key 接入 Python/TypeScript 工具链
1. 为什么要把 React 页面拆给 Subagents 做一个中等复杂度的 React 页面从零到能跑通常要同时处理三件互相纠缠的事组件结构怎么切、状态放哪一层、接口什么时候调。如果全塞给一个对话窗口模型很容易在“改组件的时候顺手动了 store改 store 的时候又忘了接口字段”最后你拿到一堆看似能跑、实则耦合严重的代码。Subagents子智能体解决的正是这个问题。它本质上是把一个大任务拆成若干个有独立上下文、独立工具权限、独立系统提示的“小助手”每个小助手只干一类活。放到 React 前端场景里我习惯拆成三类组件生成、状态管理、接口联调。组件生成只关心 JSX 和 props 类型状态管理只关心 store 结构和 action接口联调只关心请求封装、错误处理和字段映射。三者通过约定好的接口契约通信而不是互相读对方的实现细节。这套玩法的关键不在于“拆”而在于“拆完之后怎么统一调度、怎么统一鉴权”。Python 调度层负责把任务分发给对应的 SubagentTypeScript 执行层负责落地具体代码两边都要调模型如果各配各的 Key管理成本会迅速失控。所以这篇会围绕 TaoToken 的统一 Key 接入来讲把 config.toml 和 settings.json 两套配置骨架都给出来你照着填就能跑。适合谁看已经在用多智能体协作、但被 Key 管理和任务路由搞烦的开发者或者刚接触 Subagents、想找一个真实前端场景练手的同学。下面所有配置和命令都可以直接复制改掉路径和 Key 就能用。2. TaoToken 前置统一 Key 与两套工具链的接入点TaoToken 在这里扮演的角色是“一个 Key 打通 Python 和 TypeScript 两条工具链”。你不需要在 Python 侧配一套、在 Node/TS 侧再配一套也不用担心两边模型版本对不上。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个就行。接入前先做两件事。第一在控制台创建一个 API Key建议按项目命名比如react-subagents-dev方便后面排查是哪个环境在调。第二确认你要用的模型名Subagents 场景下组件生成和状态管理对模型能力要求不同可以先用同一个模型跑通再按需分流。Python 侧我用的是openaiSDK 的兼容写法因为大多数调度层代码都是这么写的迁移成本最低。TypeScript 侧用openai的 npm 包同样是兼容模式。两边的 base_url 都指向https://taotoken.net/apiapi_key 填同一个值。这样调度层和执行层共享配额、共享日志出问题只看一个地方。有一点要提醒不要把 Key 硬编码进仓库。Python 用环境变量或.envTypeScript 用.env.local加dotenv下面配置骨架里都会体现。如果你在 CI 里跑用 secrets 注入别图省事写死在 config 里。3. 可复制配置config.toml 与 settings.json 骨架先给 Python 调度层的config.toml。这个文件定义了三类 Subagent 的路由规则、模型参数和工具白名单。注意tools字段是给执行层看的调度层只负责把任务和工具集一起下发。# config.toml —— Python 调度层配置 [taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY # 从环境变量读取不写明文 timeout 60 max_retries 2 [subagents.component] model gpt-4o-mini system_prompt 你是 React 组件生成专家只输出函数组件和 TypeScript props 类型不碰状态管理和网络请求。 tools [read_file, write_file] max_tokens 4096 [subagents.state] model gpt-4o-mini system_prompt 你是 React 状态管理专家只负责 store 结构、action 和 selector不生成 JSX。 tools [read_file, write_file] max_tokens 3072 [subagents.api] model gpt-4o-mini system_prompt 你是接口联调专家负责请求封装、错误处理、字段映射输出 TypeScript 类型和 fetch 封装。 tools [read_file, write_file, run_shell_command] max_tokens 4096 [router] # 关键词路由命中即分发到对应 subagent component_keywords [组件, JSX, props, 样式] state_keywords [store, reducer, context, 状态] api_keywords [接口, 请求, fetch, axios, 字段]再给 TypeScript 执行层的settings.json。这个文件放在项目根目录被执行脚本读取决定用哪个 Subagent 的产物、写到哪个目录。{ taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: gpt-4o-mini }, subagents: { component: { outputDir: src/components, fileExt: .tsx, tools: [read_file, write_file] }, state: { outputDir: src/store, fileExt: .ts, tools: [read_file, write_file] }, api: { outputDir: src/api, fileExt: .ts, tools: [read_file, write_file, run_shell_command] } }, router: { fallback: component, logLevel: info } }两个文件里的apiKeyEnv都指向同一个环境变量TAOTOKEN_API_KEY这就是“统一 Key”的落点。Python 侧用os.environ读TypeScript 侧用process.env读值一样来源一样。你可以在 shell 里这样设置export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key。设置完可以用echo $TAOTOKEN_API_KEY确认一下别带着空值去跑否则报 401 会浪费你十分钟。4. 子任务路由与结果回传的验证动作配置写完先别急着接真实 React 项目用一个最小任务验证路由和回传是否正常。Python 调度层我写了一个精简版核心逻辑是读任务描述 → 关键词匹配 → 选 Subagent → 调 TaoToken → 把结果和元信息回传。# dispatcher.py import os, json, tomllib from openai import OpenAI with open(config.toml, rb) as f: cfg tomllib.load(f) client OpenAI( base_urlcfg[taotoken][base_url], api_keyos.environ[cfg[taotoken][api_key_env]], ) def route(task: str) - str: r cfg[router] for kw in r[api_keywords]: if kw in task: return api for kw in r[state_keywords]: if kw in task: return state for kw in r[component_keywords]: if kw in task: return component return component def dispatch(task: str): name route(task) sub cfg[subagents][name] resp client.chat.completions.create( modelsub[model], messages[ {role: system, content: sub[system_prompt]}, {role: user, content: task}, ], max_tokenssub[max_tokens], ) return { subagent: name, content: resp.choices[0].message.content, usage: resp.usage.total_tokens, } if __name__ __main__: result dispatch(生成一个带排序和过滤的表格组件) print(json.dumps(result, ensure_asciiFalse, indent2))跑python dispatcher.py你应该看到subagent字段是componentcontent里是组件代码usage有 token 数。如果subagent是api说明关键词命中了“接口”之类检查一下你的任务描述里有没有误触发的词。TypeScript 执行层验证更简单写一个runner.ts读settings.json把调度层回传的 content 写到对应目录// runner.ts import fs from fs; import path from path; import settings from ./settings.json; type SubagentName component | state | api; export function writeResult(name: SubagentName, content: string) { const conf settings.subagents[name]; const dir path.resolve(conf.outputDir); fs.mkdirSync(dir, { recursive: true }); const file path.join(dir, generated-${Date.now()}${conf.fileExt}); fs.writeFileSync(file, content, utf-8); return file; }验证动作在 Python 里把dispatch的返回值传给一个 Node 脚本或者直接手动把 content 贴进writeResult调用。跑通后你会看到src/components/generated-xxx.tsx被创建打开有内容说明“调度 → 生成 → 回传 → 落盘”整条链路通了。这里有个细节回传的usage字段建议记到日志里按 Subagent 分类统计。跑几天你就能看出哪类任务最费 token然后针对性调max_tokens或换模型。我试过把组件生成的max_tokens从 4096 降到 2048大部分组件够用省下来的额度留给接口联调。5. 本篇常见错排查401 Unauthorized九成是环境变量没生效。Python 里os.environ读不到就抛 KeyErrorTypeScript 里process.env读到 undefined 会拼成Bearer undefined。先在终端echo $TAOTOKEN_API_KEY确认再检查是不是在错误的 shell 会话里 export 的。用.env文件的话确认dotenv在 import 之前就调用了config()。路由总是落到 component检查config.toml里router段的数组顺序。我的实现是 api → state → component 依次匹配如果你的任务描述里同时出现“组件”和“接口”会优先命中 api。这不是 bug是设计如此——接口联调通常包含组件改动让 api Subagent 处理更安全。如果你希望组件优先把component_keywords的循环提到最前面。生成的代码写不进文件settings.json里的outputDir是相对路径取决于你从哪个目录跑 Node 脚本。建议在runner.ts里用path.resolve(__dirname, conf.outputDir)固定基准目录别依赖 cwd。另外mkdirSync要加recursive: true否则目录不存在会直接抛错。Subagent 之间字段对不上这是拆任务时最容易踩的坑。组件生成输出的 props 类型和接口联调输出的响应类型如果命名不一致粘到一起就报类型错误。解决办法是在调度层加一个“契约检查”步骤让 api Subagent 先输出 TypeScript interface把 interface 作为上下文传给 component Subagent。这样两边共享同一份类型定义而不是各写各的。超时或重试次数不够config.toml里timeout 60对大多数任务够用但接口联调如果涉及读多个文件可能超过。把max_retries 2保留同时给run_shell_command类工具加单独的更长超时。别把 timeout 设成 300 这种大值出问题时会卡很久才发现。6. 把 Key 和路由固定下来再谈扩展跑通上面这套之后你手里其实有了一个可复用的骨架TaoToken 统一 Key 管住两条工具链的鉴权config.toml 管住 Python 侧的路由和模型参数settings.json 管住 TypeScript 侧的落盘规则。三者职责清晰改任何一处都不会牵动另外两处。接下来要扩展的话方向有两个。一是加 Subagent 类型比如“测试生成”或“样式抽取”在 config.toml 和 settings.json 里各加一段路由关键词补上就行不用动调度代码。二是把调度层从单机脚本改成常驻服务用 FastAPI 包一层暴露/dispatch接口TypeScript 侧通过 HTTP 调用这样多人协作时 Key 只在服务端存在前端拿不到明文。如果你还在选模型或对比不同 Subagent 的输出质量可以先用模型对话页面手动跑几个任务把 prompt 调顺了再写进 config。等路由稳定、要长期跑编码任务时再考虑用 Coding Plan 把配额和并发管起来。接入文档里有完整的参数说明和错误码表遇到本文没覆盖的报错对着查比盲试快。最后留一个我踩过的坑别在 Subagent 的 system_prompt 里写“你可以调用任何工具”。工具白名单是在 config 里控制的prompt 里写这句话只会让模型产生幻觉以为能读数据库或发请求。把 prompt 写窄把工具配准比写一堆“你是一个有帮助的助手”有用得多。