1. 从零搭建 shenqiku.cn 的真实起点：开发者工具聚合平台到底难在哪
shenqiku.cn 是一个零广告、全免费的开发者工具聚合平台，把 JSON 格式化、Base64 编解码、时间戳转换、二维码生成、图片裁剪、正则测试这些高频小工具收进同一个入口，打开即用、不注册、不弹窗。它适合两类人：一类是日常被各种带广告工具站折磨的前后端开发者，另一类是想用 AI 辅助从零做一个聚合站、却卡在分类梳理和页面结构上的独立开发者。我这次把整个搭建路径拆开讲，重点放在「怎么用 AI 把工具分类、页面结构、检索入口一次性生成出来」，以及上线前必须跑一遍的自测清单。
先说清楚这类站点的核心难点，不然后面配置会没有方向。开发者工具聚合平台看着简单，实际有三个坑：第一是工具分类混乱，几十个工具如果按「编码类/转换类/图片类」硬分，用户根本找不到；第二是页面结构重复，每个工具都手写一个页面，维护成本爆炸；第三是检索入口弱，用户记不住工具名，只能靠搜索，而搜索又没做好关键词映射。我一开始也踩过，工具列表堆到 40 多个之后，自己都找不到某个功能放哪了。
AI 在这里的价值不是帮你写某个工具的算法，而是帮你做「结构化梳理」。你可以把需求丢给模型，让它输出一份带分类、关键词、路由路径的 JSON 清单，再拿这份清单去驱动页面生成。这样分类和检索入口是一次性设计好的，后面加工具只是往清单里追加一条。整个项目我实测下来，从梳理到能跑通首页，大概两个晚上，其中大部分时间花在调分类和自测上，而不是写代码。
这一节先建立整体认知：shenqiku.cn 的本质是一个「工具清单 + 动态路由 + 统一壳」的结构。工具清单决定有哪些功能，动态路由决定每个工具怎么被访问，统一壳决定导航、搜索、分类筛选怎么呈现。后面几节会分别给出可复制的目录结构、页面配置片段、验证请求方式，以及上线前的自测清单。你如果只想复现一个可用版本，跟着第 3 节的配置直接抄就行。
2. TaoToken 前置准备：给 AI 辅助开发配一个稳定的模型入口
用 AI 驱动开发，第一步不是写代码，而是把模型调用入口配好。我这次用的是 TaoToken 作为统一入口，它把多家模型的调用收敛成一个兼容接口，省得在项目里到处换 SDK。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api ，注意 API 这个地址不带 UTM 参数，配置的时候别抄错。
你需要准备三样东西：Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api ，API Key 在控制台的 API Keys 页面生成，Model ID 按你实际要用的模型填。这三件套是后面所有配置的基础，不管是 Claude Code、Cline 还是自己写的脚本，都绕不开。我建议你先把 Key 生成好放一边，后面第 3 节的配置文件里会直接引用。
生成 Key 的入口在控制台，路径是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，进去之后找 API Keys 那一栏。如果你只是想先验证模型能不能通，可以用模型对话页面直接试： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。这个页面适合快速确认 Key 和模型是否匹配，不用写代码。
如果你打算长期用 AI 辅助编码、甚至跑 Agent 类任务，可以看下 Coding Plan： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，里面会讲不同客户端的接法。Claude Code 相关的接入说明在 https://taotoken.net/claudecode-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite ，如果你用 Claude Code 做主力，这个页面值得先过一遍。
这里要提醒一点：TaoToken 是模型调用入口，不是编辑器替代品，也不是让你跳过本地开发环境。你的项目还是跑在本地 Vite 或 Node 里，TaoToken 只负责把模型请求转发出去。所以第 3 节的配置里，你会看到它出现在环境变量和客户端配置里，而不是出现在业务代码的 import 里。把这一层关系理清，后面排错会快很多。
3. 可复制配置：目录结构、工具清单 JSON 与 settings 片段
这一节是全文最干的部分，直接给可复制的配置。先看目录结构，我用的是 Vite + Vue 3 + TypeScript，工具按「纯前端」和「需后端」分开放，清单单独抽成一个 JSON，页面靠动态路由渲染。这样加工具只需要改 JSON，不用动路由文件。
shenqiku/ ├── public/ │ └── favicon.ico ├── src/ │ ├── assets/ │ ├── components/ │ │ ├── ToolCard.vue │ │ ├── SearchBar.vue │ │ └── CategoryNav.vue │ ├── data/ │ │ └── tools.json # 工具清单，核心 │ ├── pages/ │ │ ├── Home.vue │ │ ├── Category.vue │ │ └── Tool.vue # 动态工具页 │ ├── router/ │ │ └── index.ts │ ├── utils/ │ │ └── search.ts │ ├── App.vue │ └── main.ts ├── .env.local ├── index.html ├── package.json ├── tsconfig.json └── vite.config.ts工具清单 tools.json 是整个站点的骨架，每条记录包含 id、name、category、keywords、path、type。keywords 是给检索用的，用户搜「时间戳」和搜「timestamp」都能命中，靠的就是这里。下面是一个可直接用的片段：
{ "categories": [ { "id": "encode", "name": "编码转换", "icon": "swap" }, { "id": "image", "name": "图片处理", "icon": "image" }, { "id": "text", "name": "文本工具", "icon": "text" }, { "id": "dev", "name": "开发辅助", "icon": "code" } ], "tools": [ { "id": "json-format", "name": "JSON 格式化", "category": "dev", "keywords": ["json", "格式化", "压缩", "校验", "format"], "path": "/tool/json-format", "type": "frontend" }, { "id": "timestamp", "name": "时间戳转换", "category": "encode", "keywords": ["timestamp", "时间戳", "unix", "日期"], "path": "/tool/timestamp", "type": "frontend" }, { "id": "base64", "name": "Base64 编解码", "category": "encode", "keywords": ["base64", "编码", "解码", "encode"], "path": "/tool/base64", "type": "frontend" }, { "id": "image-crop", "name": "图片裁剪", "category": "image", "keywords": ["图片", "裁剪", "crop", "证件照"], "path": "/tool/image-crop", "type": "frontend" } ] }环境变量 .env.local 里放 TaoToken 的三件套，注意 Base URL 不要带 UTM：
VITE_TAOTOKEN_BASE_URL=https://taotoken.net/api VITE_TAOTOKEN_API_KEY=sk-你的Key VITE_TAOTOKEN_MODEL=你的ModelID如果你用 Claude Code 做辅助开发，settings 片段可以这样写，Base URL、Key、Model ID 三件套齐全：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key", "ANTHROPIC_MODEL": "你的ModelID" } }如果你用 Cline 或类似客户端，配置项名字不同但逻辑一样，都是 Base URL + Key + Model ID。Codex 的 auth.json 也是同样三件套，只是字段名换成对应的。这里不展开每个客户端的细节，接入文档里有对照表。关键是别把 Base URL 写成带 UTM 的官网地址，那会直接 404。
动态路由部分，router/index.ts 里只需要一条通配规则，把 /tool/:id 映射到 Tool.vue，然后在组件里根据 id 去 tools.json 里查。这样新增工具完全不用改路由：
import { createRouter, createWebHistory } from 'vue-router' const routes = [ { path: '/', component: () => import('../pages/Home.vue') }, { path: '/category/:id', component: () => import('../pages/Category.vue') }, { path: '/tool/:id', component: () => import('../pages/Tool.vue') } ] export default createRouter({ history: createWebHistory(), routes })检索入口用 search.ts 做关键词匹配，把 name 和 keywords 拼成一个可搜索字符串，用户输入后做 includes 匹配即可。不需要上全文索引，几十条数据用最朴素的方式就够快：
import tools from '../data/tools.json' export function searchTools(query: string) { const q = query.trim().toLowerCase() if (!q) return [] return tools.tools.filter(t => { const haystack = [t.name, ...t.keywords].join(' ').toLowerCase() return haystack.includes(q) }) }这套配置跑起来之后，首页渲染分类导航和工具卡片，搜索框实时过滤，点卡片进动态工具页。整个骨架不依赖后端，纯静态也能部署。需要后端的工具（比如大图压缩）再单独加 API 调用，不影响主体结构。
4. 验证请求与成功结果：确认模型入口和页面都能跑通
配置写完，先别急着写业务逻辑，分两步验证：先验证 TaoToken 入口通不通，再验证页面能不能正常渲染。这两步分开做，出问题好定位。
验证模型入口，最直接的方式是用 curl 打一次对话请求。把 Key 和 Model ID 换成你自己的：
curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "你的ModelID", "messages": [ { "role": "user", "content": "用一句话说明 JSON 格式化的作用" } ] }'成功的话你会拿到一个 JSON 响应，choices 数组里有模型返回的内容。如果返回 401，说明 Key 不对或没带上；如果返回 model not found，说明 Model ID 写错了；如果连接超时，检查 Base URL 是不是写成了带 UTM 的官网地址。这一步通了，说明三件套配置正确，后面 AI 辅助生成工具清单、生成组件代码都能走这条路。
验证页面，先跑本地开发服务器：
npm install npm run dev打开浏览器访问 http://localhost:5173 ，你应该看到首页的分类导航和工具卡片。点「JSON 格式化」应该跳到 /tool/json-format，页面能正常渲染。在搜索框输入「时间戳」，应该只筛出时间戳转换这一条。如果搜索没反应，检查 search.ts 有没有被正确引入，以及 tools.json 的 keywords 字段有没有拼写错误。
再验证一下动态路由的容错。手动访问一个不存在的路径，比如 /tool/not-exist，页面应该给出「工具不存在」的提示，而不是白屏。这个提示在 Tool.vue 里根据查询结果判断即可。我实测下来，这一步最容易被忽略，上线后用户乱输路径就会看到白屏，体验很差。
最后验证构建产物：
npm run build npm run preview构建成功后会生成 dist 目录，preview 起一个本地静态服务。访问 preview 地址，确认首页、分类页、工具页都能正常打开。如果构建报 TypeScript 错误，多半是 tools.json 的类型没定义好，加一个 interface 就能解决。这一步过了，说明整个骨架可以部署了。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
这一节按真实报错来，都是我在搭 shenqiku.cn 和配 TaoToken 时实际遇到或见别人问过的。每条给出原因和改法，你对照自己的报错直接查。
401 Unauthorized。最常见的原因是 Key 没带或带错。检查 .env.local 里的 VITE_TAOTOKEN_API_KEY 是不是完整的 sk- 开头字符串，有没有多余空格。如果你用的是 Claude Code 的 settings，检查 ANTHROPIC_API_KEY 字段名有没有写对。还有一种情况是 Key 生成了但没启用，回控制台确认一下状态。401 基本就是认证层的问题，和模型、和页面都无关。
local proxy failed。这个报错通常出现在客户端配置里 Base URL 指向了本地代理，但代理没起来。如果你没配本地代理，直接把 Base URL 改成 https://taotoken.net/api 就行。注意不要写成带 UTM 的官网地址，官网是给人看的，API 是给程序调的，两者路径不同。这个错我踩过，当时把官网地址填进了 Base URL，排查了半天。
reading choices 相关报错。典型表现是程序在解析响应时读不到 choices 字段，报 undefined 或 reading 'choices'。原因一般是响应体不是预期的 JSON，可能是返回了 HTML 错误页，也可能是请求根本没发出去。先确认 Base URL 和路径拼对，再确认请求头 Content-Type 是 application/json。如果返回的是 404 页面，解析时自然读不到 choices。用第 4 节的 curl 先验证一次，能快速区分是配置问题还是代码问题。
OAuth 相关报错。如果你在客户端里看到 OAuth 失败或 token 过期，先确认你用的是 API Key 模式而不是 OAuth 模式。TaoToken 的接入用的是 Key，不需要走 OAuth 流程。有些客户端默认走 OAuth，需要在设置里切换成 API Key 模式，然后把三件套填进去。切换之后重启客户端，一般就好了。
除了这四类，还有一个高频问题是模型名不匹配。报错可能是 model not found 或 invalid model。解决方式是回控制台确认可用的 Model ID，别凭记忆填。Model ID 通常区分大小写，抄的时候注意。把这几类排完，基本能覆盖 90% 的接入问题。
6. 上线前自测清单与后续接入建议
上线前把这份清单跑一遍，能省掉大部分线上尴尬。我按功能、体验、配置三类列，你逐条打勾。
功能类：首页分类导航能点，每个分类能筛出对应工具；搜索框输入中文和英文关键词都能命中；每个工具页能正常打开并完成一次核心操作；不存在的工具路径有友好提示；需要后端的工具在无后端时给出降级提示而不是报错。
体验类：首屏加载不卡顿，工具模块按需加载；手机浏览器打开布局不错乱；刷新任意工具页不 404（需要服务端配置 fallback 到 index.html）；复制、下载等操作有反馈提示。
配置类：Base URL 是 https://taotoken.net/api 不带 UTM；Key 和 Model ID 与当前环境匹配；构建产物里没有把 Key 硬编码进前端代码（前端只放公开配置，敏感 Key 走后端或客户端配置）；.env.local 没被提交到仓库。
后续接入建议：如果你想让站点支持「用自然语言生成正则」这类 AI 能力，可以在后端加一个接口，内部调 TaoToken 的对话接口，前端只传用户输入。这样 Key 不暴露在前端。如果你打算长期维护并加更多工具，建议把 tools.json 拆成按分类分文件，构建时合并，避免单文件过大。工具数量超过 100 之后，搜索可以升级成前缀树或轻量索引，但在此之前朴素匹配完全够用。
最后给一个实用技巧：每次加新工具，先往 tools.json 追加一条，跑一遍搜索和路由，确认能被检索到再写具体功能。这样清单和功能不会脱节。我试过先写功能后补清单，结果有三个工具上线后搜不到，只能回头补 keywords。顺序反过来，省事很多。
