1. 先想清楚 Personal Toolbox 到底要解决什么问题个人工具箱 Personal Toolbox 这个词听起来很大但落到个人开发者手里它其实就是一个「自己用着顺手的小工具集合」。我在动手写第一行代码之前花了整整一个下午做需求分析原因很简单上一个 AI 项目就是没做这一步功能越加越乱最后卡在半路不想继续了。这次我决定反过来先把边界画清楚再让 GPT-5.6 和 Codex 帮我落地。Personal Toolbox 能做什么说白了就是把那些零散的小需求收拢到一个统一入口里。比如 JSON 格式化、时间戳转换、文本去重、Base64 编解码、正则测试、颜色转换这类东西。它们单个都不复杂但平时要用的时候要么去搜在线工具要么忍受强制注册和广告。适合谁首先适合我自己这种经常写代码、处理文本、又对隐私有点在意的人。其次如果某个工具稳定了也可以开放给其他开发者用。需求分析阶段最核心的动作有两个第一列出工具清单并排优先级第二确定哪些能力走本地、哪些走 API。这两个动作决定了后面的目录结构、技术选型和接入方式。我试过跳过这一步直接开写结果就是每加一个工具都要改一遍公共布局非常痛苦。所以这次我把需求模板先写出来再让 Codex 按模板生成骨架。在工具清单上我按「使用频率 × 实现成本」做了个简单矩阵。高频低成本的是第一批比如 JSON 格式化、URL 编解码、时间戳转换高频高成本的是第二批比如正则可视化、Diff 对比低频的往后放。优先级不是拍脑袋而是回忆自己过去一个月到底打开过哪些在线工具。这个回忆过程本身就很值钱因为它暴露了真实需求而不是想象中的需求。本地还是 API 的判断标准也很直接纯计算、纯字符串处理、不依赖外部知识的一律走本地前端需要模型理解、生成、总结、翻译的才走 API。比如「把这段 JSON 转成 TypeScript 类型」可以本地做「把这段中文润色成技术文档风格」就得走 API。这条线画清楚之后Personal Toolbox 的架构就自然分成了两层本地工具层和 AI 能力层。2. TaoToken 在 Personal Toolbox 里的接入点规划Personal Toolbox 的 AI 能力层需要一个稳定的模型入口。我选择把 Codex 和 GPT-5.6 的调用统一走 TaoToken原因是它同时提供 OpenAI 兼容的 API 和 Claude Code 这类编码工具的接入方式配置一次就能在多个场景复用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。在需求分析阶段我要确定的接入点有三个。第一个是 Codex 的 auth.json它决定了 Codex 在仓库里执行任务时调用哪个模型端点。第二个是 Personal Toolbox 自身的 AI 工具页它通过 OpenAI 兼容接口调用 GPT-5.6。第三个是 Coding Plan用于长期编码和 Agent 类任务。这三个接入点对应不同的使用场景但共享同一套 Base URL 和 Key。先说 Codex 的 auth.json。Codex 在本地运行时会读取用户目录下的配置文件。默认它指向官方端点我需要把它改成 TaoToken 的地址。这个改动只影响模型请求的走向不影响 Codex 读取仓库、修改代码、跑测试的能力。改完之后Codex 依然能正常执行任务只是模型请求走了 TaoToken。再说 Personal Toolbox 里的 AI 工具页。这部分我会用 TypeScript 写一个轻量的请求封装Base URL 指向 https://taotoken.net/api Model ID 用 GPT-5.6 对应的标识。请求格式遵循 OpenAI 兼容规范所以不需要引入额外的 SDK用 fetch 就够了。这样做的另一个好处是本地工具层和 AI 能力层可以共用同一套错误处理和加载状态。第三个接入点是 Coding Plan。当 Personal Toolbox 进入长期迭代阶段我会用 Coding Plan 来处理那些需要多轮对话、跨文件修改的任务。它的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需求分析阶段不需要立刻开通但要在文档里标记出来避免后面忘记。这里有个关键决策AI 能力层不要和本地工具层耦合。我的做法是在目录结构里单独放一个src/ai/目录里面只放请求封装、模型配置和错误处理。本地工具放在src/tools/下每个工具一个文件夹。这样即使以后换模型端点也只改src/ai/里的配置不用动任何工具代码。这个边界在需求分析阶段就要定下来否则后面一定会乱。3. 可复制的需求模板与目录结构草案需求分析不能只停留在脑子里得写成可复制的模板。我给自己定了一个需求模板每次新增工具都按这个格式填一遍。模板包含六个字段工具名称、解决的问题、输入、输出、本地还是 API、验收标准。填完这六个字段基本就能判断这个工具值不值得做、怎么做。下面是我实际在用的需求模板你可以直接复制到自己的仓库文档里## 工具需求卡 - 工具名称 - 解决的问题一句话 - 输入 - 输出 - 处理位置本地 / API - 验收标准 - [ ] 输入合法时返回正确结果 - [ ] 输入非法时给出明确提示 - [ ] 不依赖登录 - [ ] 有对应的单元测试目录结构草案我也在需求阶段就定好了。核心思路是「工具之间互不依赖公共能力单独抽离」。具体结构如下personal-toolbox/ ├── AGENTS.md ├── package.json ├── vite.config.ts ├── tsconfig.json ├── src/ │ ├── main.ts │ ├── App.vue │ ├── router/ │ │ └── index.ts │ ├── layouts/ │ │ └── ToolLayout.vue │ ├── tools/ │ │ ├── registry.ts │ │ ├── json-formatter/ │ │ │ ├── index.vue │ │ │ ├── logic.ts │ │ │ └── logic.test.ts │ │ └── timestamp/ │ │ ├── index.vue │ │ ├── logic.ts │ │ └── logic.test.ts │ ├── ai/ │ │ ├── client.ts │ │ └── config.ts │ └── views/ │ ├── Home.vue │ └── NotFound.vue └── tests/这个结构里有两个关键文件。一个是src/tools/registry.ts它负责注册所有工具首页和路由都从这里读数据。新增工具时只需要在 registry 里加一行不用改首页代码。另一个是src/ai/config.ts它集中管理 Base URL、Model ID 和 Key 的读取逻辑。这两个文件是需求分析阶段就要确定下来的「扩展点」。AGENTS.md 也要在需求阶段写好它是给 Codex 看的仓库级约束。我的 AGENTS.md 内容大致如下# 仓库规则 - 使用 Vue 3 TypeScript Vite - 仅使用 Composition API 和 script setup langts - 禁止 Vue 2、Options API - 不得未经要求增加框架或依赖 - 不进行无关的大规模重构 - 新增工具必须放在 src/tools/ 下并注册到 registry.ts - AI 请求统一走 src/ai/client.ts有了这个模板和结构Codex 在后续开发时就有明确的边界不会今天用 Options API、明天又引入一个新框架。需求分析的价值就在这里它不是写给人看的文档而是写给 AI 和未来的自己看的约束。4. 把 Codex auth.json 与 Base URL 改到 TaoToken 的配置片段配置这一步是需求分析落地成可运行环境的关键。Codex 的 auth.json 通常位于用户目录下的.codex文件夹里。不同系统路径不同macOS 和 Linux 一般是~/.codex/auth.jsonWindows 是%USERPROFILE%\.codex\auth.json。改之前先备份一份这是踩过的坑改错了还能还原。auth.json 的核心字段是 API Key 和 Base URL。把 Base URL 指向 TaoToken 的 API 地址Key 换成在控制台生成的 Key。配置片段如下{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }注意 Base URL 后面不要多加/v1具体以接入文档为准。Key 的生成入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 生成后复制保存页面上不会再次完整显示。Personal Toolbox 自身的 AI 请求封装放在src/ai/config.ts内容如下export const aiConfig { baseUrl: https://taotoken.net/api, modelId: gpt-5.6, apiKey: import.meta.env.VITE_TAOTOKEN_KEY as string, }; export const aiHeaders { Content-Type: application/json, Authorization: Bearer ${aiConfig.apiKey}, };Key 不要硬编码在代码里用 Vite 的环境变量注入。在项目根目录建一个.env.local文件VITE_TAOTOKEN_KEYsk-你的TaoToken密钥然后把.env.local加进.gitignore避免提交到 GitHub。这一步在需求分析阶段就要写进安全规范否则后面很容易泄露。src/ai/client.ts里封装一个最小的请求函数import { aiConfig, aiHeaders } from ./config; export async function chat(prompt: string): Promisestring { const res await fetch(${aiConfig.baseUrl}/v1/chat/completions, { method: POST, headers: aiHeaders, body: JSON.stringify({ model: aiConfig.modelId, messages: [{ role: user, content: prompt }], }), }); if (!res.ok) { throw new Error(请求失败${res.status}); } const data await res.json(); return data.choices?.[0]?.message?.content ?? ; }这段代码里Base URL、Key、Model ID 三件套都齐了。Base URL 是https://taotoken.net/apiKey 从环境变量读Model ID 是gpt-5.6。这三个值在需求分析阶段就要确定后面所有 AI 工具都复用这一套。如果你用的是 Claude Code 这类工具接入方式类似Base URL 和 Key 的填法参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有针对不同工具的配置示例照着填就行。需求分析阶段不需要把所有工具都配一遍但要把「统一走 TaoToken」这个决策写进技术选型文档。5. 一次连通性验证与常见报错排查配置写完下一步是验证。验证不需要写复杂代码一个最小的请求就能确认 Base URL、Key、Model ID 是否都对。我一般用 curl 先测排除前端代码的干扰curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: gpt-5.6, messages: [{role: user, content: 回复 ok}] }如果返回的 JSON 里有choices字段并且内容里包含ok说明连通性没问题。这时候再去跑 Personal Toolbox 里的 AI 工具页基本不会出问题。如果 curl 就失败了那问题一定在配置不在代码。下面是我实际遇到过的几个报错以及对应的排查方向。第一个是 401。返回{error:{message:Invalid API key}}或者类似内容。原因通常是 Key 复制不完整、Key 前后有空格、或者 Key 已经失效。排查方法是重新在控制台生成一个 Key复制时注意不要带上多余字符。还有一种情况是环境变量没生效Vite 需要重启 dev server 才能读到新的.env.local。第二个是 local proxy failed。这个报错通常出现在 Codex 或类似工具里意思是本地代理层没能把请求转发出去。排查方向是检查 auth.json 的 Base URL 是否写错、网络是否能访问该地址、以及是否有其他代理配置冲突。注意这里说的是工具自身的网络配置不是让你去搞什么特殊网络手段纯粹是检查地址拼写和本地环境。第三个是 reading choices 相关报错比如Cannot read properties of undefined (reading choices)。这说明请求返回了但返回结构里没有choices字段。常见原因是 Model ID 写错了或者请求体格式不对。排查方法是先用 curl 确认返回结构再对照client.ts里的解析逻辑。如果返回的是错误对象data.choices自然是 undefined。第四个是 OAuth 相关报错。有些工具默认走 OAuth 登录流程如果你已经改成 Key 认证但工具还在尝试 OAuth就会报错。排查方向是确认工具的认证模式已经切换到 API Key并且 auth.json 里的字段名和工具要求的一致。不同工具字段名可能不同以接入文档为准。排查的时候有个通用思路先 curl再工具最后代码。curl 通了说明配置没问题工具报错说明工具配置有问题代码报错说明解析逻辑有问题。这个顺序能帮你快速定位问题在哪一层不用瞎猜。6. 需求分析做完之后下一步怎么走需求分析做完Personal Toolbox 的骨架其实已经清晰了工具清单有了优先级本地和 API 的边界画好了目录结构定了Codex 的 auth.json 和项目里的 Base URL 都指向了 TaoToken连通性也验证过了。接下来就是按优先级一个个实现工具每完成一个就复盘一次。我的建议是第一个工具选最简单的比如 JSON 格式化。它的逻辑纯本地不依赖 API能快速跑通「注册工具 → 路由 → 布局 → 测试 → 构建」这条完整链路。等这条链路跑顺了再去做需要调用 API 的工具比如文本润色。这样即使 AI 请求出问题你也能确定是 AI 层的问题而不是整个架构的问题。长期编码和 Agent 类任务可以走 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。模型对话类的调试可以用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 快速验证提示词效果。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 用来管理 Key 和查看用量。最后说一个实用技巧每次让 Codex 改代码之前先把当前任务写进一个TASK.md内容包括目标、涉及文件、验收标准。Codex 读完这个文件再动手改出来的东西会贴合很多。这个习惯我从需求分析阶段就开始用比每次在对话里重复描述边界要省事得多。需求分析不是一次性动作它是贯穿整个项目的约束机制写下来、存进仓库、让 AI 读到才算真正落地。