企业官网建设流程全解析

1. 先搞清楚你卡在哪：三个扩展机制到底解决什么问题

Claude Code 用了一段时间后，很多人会进入同一个困惑期：Agents、Skills、Hooks 这三个词反复出现在文档和社区讨论里，但真到自己的项目里，却不知道该把哪段逻辑写进哪个文件。结果就是配置越堆越多，上下文越来越臃肿，自动化该触发的时候不触发，不该跑的时候乱跑。

这个问题的本质不是"哪个更强"，而是三者的触发模型完全不同。Hooks 是事件驱动的强制回调，你不需要调用它，它在文件保存、命令执行、会话结束这些节点自动跑；Skills 是按需加载的流程手册，只有你输入/技能名或者 Claude 判断匹配时才注入上下文；Agents 是拥有独立思考循环和隔离上下文的专项代理，适合把复杂任务拆出去单独跑。

适合读这篇的人：刚接触 Claude Code、正在纠结要不要写CLAUDE.md、看到.claude/skills/和.claude/agents/目录不知道放什么、或者已经配了一堆但发现效果不对的开发者。下面我会用一套可复制的settings.json和config.toml骨架，配合逐项验证动作，帮你把三者的边界跑通。

2. 前置准备：TaoToken 接入与 Claude Code 环境确认

在配置三大扩展机制之前，先确保你的 Claude Code 能正常发起请求。我这边用的是 TaoToken 作为模型接入层，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 的接口格式，Claude Code 可以直接对接。

你需要先去控制台创建一个 API Key。打开https://taotoken.net/console，在 API Keys 页面生成一个密钥，复制保存好。这个 Key 后面会写进环境变量，不要直接硬编码到项目文件里。

环境变量配置方式（Linux/macOS）：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的密钥"

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的密钥"

配置完成后，用一条最简单的请求验证连通性：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回里能看到content字段和正常的文本内容，说明接入层没问题。这一步很关键，因为后面 Hooks 里的prompt类型校验、Agents 的独立循环，都依赖底层请求能正常走通。如果这里就报 401 或连接超时，先解决接入问题，别急着写扩展配置。

3. 可复制配置：settings.json 与 config.toml 骨架

Claude Code 的配置分两层：项目级的.claude/settings.json管权限和 Hooks，用户级的~/.claude/config.toml管模型和全局行为。下面给出一套能直接用的骨架。

3.1 settings.json 骨架

在项目根目录创建.claude/settings.json：

{ "permissions": { "allow": [ "Bash(pnpm prettier:*)", "Bash(pnpm eslint:*)", "Bash(pnpm test:*)", "Read(./src/**)", "Edit(./src/**)" ], "deny": [ "Bash(rm -rf:*)", "Bash(sudo:*)", "Read(./.env)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "pnpm prettier --write \"$CLAUDE_FILE_PATH\"", "statusMessage": "格式化修改的文件" } ] } ], "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo \"$CLAUDE_BASH_COMMAND\" | grep -qE 'rm -rf /|sudo rm' && exit 1 || exit 0" } ] } ], "Stop": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "pnpm test --run", "statusMessage": "任务结束运行测试" } ] } ] } }

这里有几个点要注意。permissions.deny里的规则优先级高于allow，所以即使你允许了Bash，rm -rf依然会被拦。hooks里的matcher决定触发范围，Edit表示只在编辑文件后触发，Bash表示在执行 shell 命令前触发，*表示所有情况。

3.2 config.toml 骨架

用户级配置放在~/.claude/config.toml：

[model] default = "claude-sonnet-4-20250514" max_tokens = 8192 [api] base_url = "https://taotoken.net/api" timeout = 120 [behavior] auto_approve_read = true auto_approve_edit = false context_window_warning = 0.8

context_window_warning设成 0.8 的意思是，当上下文用到 80% 时给出提醒。这个参数在你有多个 Agents 并行跑的时候特别有用，能提前发现上下文膨胀。

3.3 Skills 目录骨架

Skills 不写在 settings.json 里，而是独立目录。创建.claude/skills/deploy-docker/SKILL.md：

# Skill: deploy-docker ## 触发命令 /deploy ## 适用场景 Java 后端 Docker 镜像构建与推送 ## 执行流程 1. 校验根目录存在 Dockerfile 和 docker-compose.yml 2. 执行 docker build -t project-api:latest . 3. 本地启动测试容器 docker-compose up -d 4. 健康检测 curl http://127.0.0.1:8080/health 5. 检测通过后推送镜像，日志写入 ./deploy/log.txt ## 强制约束 - 构建失败立即终止，输出错误堆栈 - 禁止跳过健康检测 - 所有命令打印到控制台

3.4 Agents 目录骨架

创建.claude/agents/db-schema/AGENT.md：

# Agent: db-schema ## 任务边界 仅处理 src/db/ 目录下的表结构与 SQL 迁移 ## 权限 - 允许读写 src/db/、docs/sql/ - 仅可调用 /db-migration 技能 - 禁止修改前端与接口业务代码 ## 工作流程 1. 接收主 Agent 传入的库表需求 2. 读取项目数据库规范，生成 PostgreSQL 建表语句 3. 生成 ER 关系图写入 docs/db-er.md 4. 执行 sql-lint 校验 5. 返回 SQL 脚本与变更说明

4. 逐项验证：确认三者真的按预期工作

配置写完不代表生效，必须逐项验证。下面是我实际跑通的验证动作。

4.1 验证 Hooks 是否触发

先确认 PostToolUse 的格式化钩子。在 Claude Code 里让它编辑一个.ts文件，比如：

帮我把 src/utils/format.ts 里的 formatDate 函数改成支持时区参数

编辑完成后，观察终端是否出现格式化修改的文件这个 statusMessage。然后检查文件内容，如果 Prettier 生效，缩进和引号风格应该被统一了。如果没触发，检查matcher是否写成了Edit而不是edit，大小写敏感。

再验证 PreToolUse 的拦截。让 Claude Code 执行一条危险命令：

帮我执行 rm -rf /tmp/test

如果配置正确，这条命令会被拦截，终端提示权限拒绝。注意这里用的是command类型而不是prompt类型，因为高频事件用prompt会持续消耗 token，能用 shell 脚本判断的就别用 LLM。

4.2 验证 Skills 是否加载

在对话框输入/deploy，观察 Claude Code 是否读取了SKILL.md的内容。正常情况下，它会按文档里的步骤逐条执行，而不是自由发挥。如果它没有按流程走，检查SKILL.md的路径是否正确，必须是.claude/skills/技能名/SKILL.md这个层级。

你可以故意在SKILL.md里写一条约束，比如"禁止跳过健康检测"，然后看它执行时是否会遵守。如果它跳过了，说明 Skill 没被正确加载，可能被当成了普通上下文。

4.3 验证 Agents 是否隔离

输入@db-schema 设计订单表，观察它是否只操作src/db/目录。你可以故意让它改一个前端文件，比如：

@db-schema 顺便把 src/web/App.tsx 里的接口地址改一下

如果 Agent 边界配置正确，它会拒绝这个请求，因为它只被授权操作src/db/。这个隔离能力是 Agents 和 Skills 最大的区别，Skills 只是流程手册，没有权限边界；Agents 有独立的上下文和权限约束。

5. 本篇常见错排查

5.1 Hooks 不触发

最常见的原因是matcher写错。PostToolUse的 matcher 是工具名，比如Edit、Write、Bash，不是文件扩展名。如果你想按文件类型过滤，要在 hook 的 command 里自己判断$CLAUDE_FILE_PATH的后缀。

另一个原因是 settings.json 的 JSON 格式错误。Claude Code 对 JSON 语法很严格，多一个逗号就会整个文件失效。用jq . .claude/settings.json检查一下格式。

5.2 Skills 加载了但没按流程走

检查SKILL.md里是否有明确的步骤编号。Claude Code 对有序列表的遵循度比无序列表高。另外，如果 Skill 内容太长，可能会被截断，建议把核心流程控制在 50 行以内，详细说明放到同目录的其他文件里。

5.3 Agents 上下文溢出

如果你发现 Agent 跑着跑着开始重复或者丢失上下文，大概率是任务拆分不够细。一个 Agent 只做一件事，比如db-schema只管表结构，不要让它同时管迁移和查询优化。在AGENT.md里明确写"禁止"做什么，比写"可以"做什么更有效。

5.4 三者混用导致重复执行

典型错误是把部署流程写进 Hook。比如在PostToolUse里配置docker build，结果每次编辑文件都触发一次构建，速度慢到无法忍受。记住：Hook 只做轻量的、必须强制的校验和格式化；重流程放 Skill；需要独立思考和隔离的放 Agent。

6. 选型决策与后续接入

快速判断口诀：只要自动触发、强制校验，选 Hooks；固定标准化操作、一键执行流程，选 Skills；复杂独立专项任务、需要隔离上下文，选 Agents。

如果你还在调试接入层，先去https://taotoken.net/api-keys确认密钥状态，再对照https://taotoken.net/doc检查请求格式。模型对话相关的验证可以直接在https://taotoken.net/models里试。长期用 Claude Code 做编码和 Agent 编排的话，Coding Plan 的额度模型更适合高频调用场景，具体在https://taotoken.net/coding-plan看。

配置这东西，跑通一次比看十篇文档都管用。先把settings.json里的一个 Hook 验证通过，再加第二个，别一次性全堆上去。