企业官网建设流程全解析

1. 为什么你的 AI 助手总是“读不懂”你的项目

你有没有遇到过这种场景：新开一个对话窗口，想让 AI 帮你改一个接口，结果它上来就给你编了一个根本不存在的目录结构，或者把 Vue2 的写法硬塞进你的 Vue3 项目里。你不得不花十几分钟把项目背景、技术栈、命名规范重新讲一遍，讲完它还是似懂非懂。

问题不在于模型不够聪明，而在于它缺少一份“项目说明书”。每次对话都是冷启动，AI 手里只有你的问题，没有你的上下文。skill 技能文件就是解决这件事的：它把项目结构、技术栈、关键约定、常用命令打包成一份 AI 能读懂的文档，放在项目里，让 AI 在对话开始前就“读过”你的代码库。

这篇内容面向的是个人项目开发者，尤其是那种“自己写、自己维护、偶尔让 AI 搭把手”的场景。我会用 TaoToken 统一 Key 做接入，交付一份可复制的 skill 配置骨架和 settings.json 片段，然后带你验证 AI 是否真的读懂了项目信息。整个过程不需要你改一行业务代码，只需要在项目根目录加几个 Markdown 文件。

先说清楚 skill 是什么。你可以把它理解成一份写给 AI 看的 README，但它比 README 更结构化：有触发条件、有文档导航、有代码模板索引。AI 在对话时如果命中触发条件，就会自动加载这份 skill，从而知道“这个项目用 PHP 8.1 + Vue3，接口统一走 ent 路由，控制器放在 app/controller 下”。它不是什么黑魔法，本质就是上下文注入，只不过注入的内容是你提前写好的、经过整理的。

我试过在三个不同规模的项目里加 skill，最直观的变化是：以前问“帮我加一个用户列表接口”，AI 会反问一堆问题；现在它会直接按项目规范生成 Controller、Service、Route 三件套，命名和目录都对得上。下面把完整流程拆开讲。

2. 用 TaoToken 统一 Key 接入 AI 助手

在写 skill 之前，先把接入层搞定。个人项目最烦的就是每个工具配一套 Key，TaoToken 的做法是给你一个统一的 API Key，兼容主流模型调用格式，你只需要在配置文件里填一次。

访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册后，进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，在 API Keys 页面点“新建密钥”，复制那串以 sk- 开头的字符串。这个 Key 就是你后面所有配置里要填的东西。

API 的基础地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 base_url 使用。如果你用的是 OpenAI 兼容的客户端，把 base_url 设成这个，api_key 设成你复制的 Key，就能直接调通。

这里有个细节：TaoToken 的 Key 是统一计费的，你不需要为不同模型分别充值。对于个人项目来说，这意味着你可以用同一个 Key 在对话窗口里问架构问题，在编码插件里生成代码，在脚本里跑批量任务，账单是一份。我实测下来，这种统一入口对“一个人维护多个小项目”的场景特别友好，不用记一堆 Key，也不用担心某个平台的额度突然用完。

如果你主要做长期编码和 Agent 任务，可以看一下 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有适合持续编码场景的套餐说明。如果只是偶尔验证模型效果，用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 就够了。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，遇到参数问题先翻这里。

Key 拿到后，先别急着写 skill，用一条 curl 确认接入是通的：

curl https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "回复 ok"}] }'

返回里如果有 choices 字段且 content 是 ok，说明 Key 和网络都没问题。这一步很重要，因为后面 skill 验证时如果 AI 没反应，你要能区分是接入问题还是 skill 没生效。

3. 可复制的 skill 配置骨架与 settings.json 片段

现在进入正题。skill 的目录结构建议放在项目根目录的.ai/skills/下，这样不污染源码目录，也方便 git 管理。一个最小可用的 skill 只需要两个文件：SKILL.md和README.md。前者给 AI 读，后者给人读。

先建目录：

cd 你的项目根目录 mkdir -p .ai/skills/my_project/{assets,references,scripts}

然后创建.ai/skills/my_project/SKILL.md，内容如下。这份骨架我刻意写得紧凑，你可以直接复制后改字段：

# my_project 项目技能 ## 1. 技能概述 **技能名称**: my_project **技能版本**: 1.0.0 **技能描述**: 个人项目开发技能包，覆盖技术栈、目录约定与常用命令 **触发条件**: - 当用户询问项目结构、技术栈、开发规范时 - 当用户打开或编辑 .php / .vue / .js 文件时 - 当用户要求新增接口、页面、组件时 **触发关键词**: - my_project - 项目结构 - 开发规范 - 新增接口 ## 2. 技术栈 | 层级 | 技术 | 版本 | |------|------|------| | 后端 | PHP | 8.1 | | 框架 | ThinkPHP | 6.0 | | 前端 | Vue | 3.2 | | 构建 | Vite | 4.0 | | 数据库 | MySQL | 8.0 | ## 3. 目录约定 - 控制器: app/controller/ - 服务层: app/service/ - 模型: app/model/ - 路由: route/ent.php - 前端页面: src/views/ - 前端组件: src/components/ ## 4. 文档导航 | 文档 | 说明 | 路径 | |------|------|------| | 项目概述 | 模块划分与职责 | references/01-overview.md | | 开发规范 | 命名与分层规则 | references/02-convention.md | | 常用命令 | 启动、构建、迁移 | references/03-commands.md | ## 5. 核心约定 - 接口统一返回 { code, msg, data } 结构 - 控制器不写业务逻辑，只做参数校验与调度 - 新增接口必须同时在 route/ent.php 注册路由 - 前端请求统一走 src/api/ 下的封装，不直接调 axios

再创建.ai/skills/my_project/README.md，这份是给人看的，写清楚怎么用：

# my_project 技能包 ## 简介 让 AI 助手快速了解本项目背景，减少重复解释。 ## 快速开始 1. 确保 .ai/skills/my_project/ 存在 2. 在 AI 对话中提及项目名或打开项目文件 3. AI 会自动加载 SKILL.md 中的约定 ## 目录说明 - SKILL.md: AI 读取的主文档 - references/: 详细参考文档 - assets/: 代码模板 - scripts/: 辅助脚本

接下来是 settings.json 片段。如果你用的编辑器或插件支持通过配置文件指定 skill 路径，把下面这段合并进去。以常见的 AI 编码插件为例，配置项通常长这样：

{ "ai.provider": "openai-compatible", "ai.baseUrl": "https://taotoken.net/api", "ai.apiKey": "sk-你的Key", "ai.model": "gpt-4o-mini", "ai.skills": { "enabled": true, "paths": [ ".ai/skills/my_project" ], "autoLoad": true } }

注意 baseUrl 填的是 https://taotoken.net/api ，不要在后面加 /v1，具体路径由客户端拼接。apiKey 就是你从控制台复制的那串。skills.paths 指向你刚建的目录，autoLoad 设为 true 表示对话时自动扫描。

如果你用的是 Claude Code 这类工具，配置方式略有不同，可以参考 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里的接入说明，把 base_url 和 api_key 对应填进去，skill 目录通过项目级配置挂载。

这里有个容易踩的坑：settings.json 里的路径是相对于项目根目录的，不是相对于配置文件本身。如果你把 settings.json 放在.vscode/下，paths 仍然写.ai/skills/my_project，不要写成../.ai/skills/my_project。

4. 验证 AI 是否正确读取项目信息

配置写完后，必须验证。不能只看“AI 回复了”就认为 skill 生效了，要设计几个能区分“读了 skill”和“没读 skill”的问题。

第一个验证：问一个只有 skill 里才有的约定。比如你的 SKILL.md 里写了“接口统一返回 { code, msg, data }”，那就直接问：

我们这个项目的接口返回结构是什么？

如果 AI 回答包含 code、msg、data 三个字段，说明它读到了 skill。如果它回答“通常 RESTful 接口返回 HTTP 状态码”，那就是没读到，走的是通用知识。

第二个验证：问目录约定。比如：

新增一个用户列表接口，控制器应该放在哪个目录？

正确回答应该指向app/controller/，并且提到需要在route/ent.php注册路由。如果 AI 说“放在 controllers 目录”或者“看你项目习惯”，说明 skill 没加载。

第三个验证：让它生成一段符合规范的代码。比如：

按项目规范写一个 UserController 的骨架。

观察生成结果里是否包含{ code, msg, data }返回结构，是否把业务逻辑留空只做调度。如果它生成了一个完整的、带 SQL 查询的控制器，说明它没遵守 skill 里的“控制器不写业务逻辑”约定。

如果三个验证都过了，说明 skill 生效。如果没过，按下面顺序排查：

先确认文件路径。在项目根目录执行ls .ai/skills/my_project/SKILL.md，确认文件存在且非空。然后确认 settings.json 里的 paths 没有拼错，注意大小写。再确认客户端的 skill 功能是开启状态，有些插件默认关闭，需要手动打开。

还有一个隐蔽问题：SKILL.md 的触发关键词如果写得太泛，比如只写“项目”，AI 可能在无关对话里也加载它，反而干扰。建议关键词至少包含项目名，再加两三个具体术语。触发条件里最好带上文件类型，这样打开对应文件时能精准命中。

验证通过后，你可以继续往 references/ 里加详细文档。比如把数据库表结构、API 接口清单、部署步骤分别写成 Markdown，然后在 SKILL.md 的文档导航里加链接。AI 在需要时会顺着链接去读，不需要时不会加载，这样既保证了上下文完整，又不会撑爆 token。

5. 本篇常见错排查

报错一：AI 完全无视 skill，回复和通用知识一样。

最常见的原因是 settings.json 没被客户端读取。检查配置文件的位置是否符合客户端要求，有些工具要求放在项目根目录，有些要求放在.vscode/或.idea/下。另外确认 JSON 格式合法，多一个逗号都会导致整个配置失效。可以用python -m json.tool settings.json验证格式。

报错二：AI 说“我无法访问该文件”。

这是权限或路径问题。确认 skill 目录在项目工作区内，如果客户端只允许访问特定目录，把.ai/skills/加进允许列表。另外确认文件编码是 UTF-8，有些编辑器默认 GBK，AI 读出来是乱码。

报错三：skill 加载了但内容不对。

检查 SKILL.md 里是否有重复的章节标题，或者表格格式错乱。Markdown 表格如果列数对不上，解析会出问题。建议用markdownlint过一遍，或者手动检查每个表格的分隔行|---|---|数量是否和表头一致。

报错四：API 调用返回 401。

Key 填错了或者过期了。去控制台 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 重新生成一个，注意复制时不要带空格。如果用的是环境变量，确认变量名和代码里读的一致。

报错五：返回 404 或 model not found。

baseUrl 或 model 名写错了。baseUrl 应该是 https://taotoken.net/api ，model 名要和你账号可用的模型一致。不确定的话，先用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 手动发一条消息，确认能通再写进配置。

报错六：skill 生效了但 AI 还是生成错误代码。

这通常是 skill 内容不够具体。比如你只写了“遵循项目规范”，但没写规范是什么。AI 只能猜。解决办法是把约定写成可执行的规则，比如“控制器方法名用驼峰，路由用蛇形”，而不是“命名要规范”。规则越具体，AI 执行越准。

6. 把 skill 变成项目的一部分

skill 不是一次性的配置，它应该跟着项目一起演进。每次你发现 AI 又犯了一个“本该知道”的错误，就把对应的约定补进 SKILL.md。比如它总是忘记在新增接口时注册路由，你就在核心约定里加一条“新增接口必须同时在 route/ent.php 注册路由”，下次它就会记得。

对于长期编码和 Agent 场景，建议把 skill 和 Coding Plan 结合使用。Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里有适合持续开发任务的方案，配合 skill 的上下文注入，AI 在长对话里不容易“失忆”。如果你只是偶尔让 AI 帮忙看代码，用模型对话页面就够了，Key 是同一个，不用切换。

最后给一个实用技巧：把 skill 目录纳入 git 版本管理，但把 settings.json 里的 apiKey 抽成环境变量。这样团队协作时，别人 clone 下来只需要配自己的 Key，skill 内容直接复用。环境变量读取方式因客户端而异，常见的是在 settings.json 里写"apiKey": "${TAOTOKEN_API_KEY}"，然后在系统里设置这个变量。

整个流程走下来，你得到的是一个“越用越懂你项目”的 AI 助手。第一次配置花二十分钟，后面每次对话省下的解释时间，累积起来相当可观。而且 skill 文件本身就是一份项目文档，哪怕不用 AI，新人（或者三个月后的你自己）翻一翻也能快速回忆起来。