企业官网建设流程全解析

上个月参加了一场 Anthropic 工程师主持的工作坊，议题是用 Claude Code 搭生产级 Agent。我原以为会上会有一堆提示词技巧或者模型参数调优的内容，结果工程师在白板上写了第一句话：Agent is a software architecture problem, not a model problem。整场三小时就围绕这句话展开——把 Agent 拆成五层脚手架，逐层讲机制、讲取舍、讲实际项目里翻车的案例。这篇内容是那天的完整梳理，加上我自己的实测补充，给正在用 Claude Code 做 Agent 落地的团队一份可以直接对照的骨架笔记。

这套五层结构从上到下分别是：连接与上下文层、工具与技能层、记忆层、安全与治理层、编排与控制层。每一层在 Claude Code 里都有对应的原生机制：连接层对应模型路由与重试策略，工具层对应 Skill、子代理和 MCP，记忆层对应 CLAUDE.md 和会话管理，安全层对应权限模式与审计钩子，编排层对应 Agent 循环和 checkpoint 设计。下面按工作坊的顺序逐层拆，每层都会给出我验证过的配置和踩坑记录。

1. 工作坊没讲模型，讲的是脚手架

工作坊一开始，工程师先纠正了一个普遍的动作：很多团队选 Agent 方案时，第一反应是换框架。今天用 LangChain，明天换 AutoGPT，后天看到编排器又冒出来一个。他说这种思路本质上是把 Agent 当成一个函数库，而这个思路会在生产环境里反复撞墙。脚手架的意义在于：它不是楼本身，是你盖楼时的支撑结构。楼可以换成任何业务形态，脚手架的结构却是高度稳定的。

框架的隐喻是房子已经盖好了，你搬进去住；脚手架的隐喻是楼还在盖，但每一层的承重、通道和安全网都已经到位。生产级 Agent 从来不是一次性交付的成品，它会随业务反复迭代，所以你的投资应该放在那个能一直复用、不断加固的骨架上，而不是某一版具体的业务流程。

当天发的手册里有一张表，把五层脚手架对应到缺失时的典型故障症状。这张表我后来一直贴在项目 wiki 的最上面：

工程师说了一句我印象很深的话：你们遇到的 90% 的 Agent 翻车事故，不是模型能力不够，是某一层脚手架没搭。比如收到 unable to connect to anthropic services 的第一反应是换模型，但多数时候是一次连接层故障；上下文爆了就无脑加长窗口，结果窗口越大，检索效率越低；工具权限给太宽导致删错文件，然后归咎于 AI 不靠谱；没有审计日志，出了问题连 Agent 刚才干了什么都不知道。这几类事故我后来在团队里全都遇到过，无一例外。

2. 第一层：连接与上下文，Agent 的地基

2.1 连接层的三件事：认证、重试、路由

连接层的核心目标就一句话：让 Agent 在一个稳定、可诊断的通道上拿到模型响应。工作坊直接放了一条工单记录：一条 failed to connect to api.anthropic.com: status 403 的报错挂了三天没人处理，因为大家默认是网络问题。实际排查下来，是 CI 环境里 ANTHROPIC_API_KEY 过期了，某个回滚操作把旧密钥带了回来。

工程师给了一个很朴素的排查顺序：先确认故障发生在哪一段。第一步用 curl 直接打一次 Messages API，排除 Claude Code 本身的问题：

curl -v https://api.anthropic.com/v1/messages \ -H "x-api-key: ${ANTHROPIC_API_KEY}" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"你的模型ID","max_tokens":1024,"messages":[{"role":"user","content":"ping"}]}'

curl 成功但 Claude Code 失败，问题大概率出在 Claude Code 的配置、环境变量或者权限设置上；curl 本身返回 403，那就按认证链路查——密钥是否过期、账号是否还有额度、组织策略是否允许当前项目接入。如果错误里明确提示当前地区不受支持这类限制信息，这是产品策略和合规限制，不是配置 bug，工程上的合法思路是走企业版或官方支持渠道，而不是试图绕过去。

重试策略也在这层做。生产环境里不要依赖默认行为，建议在调度侧加退避重试。我的做法是给定时任务套一层外壳：第一次失败等 5 秒，第二次 10 秒，第三次 30 秒，超过三次直接熔断并告警，不带着坏连接反复空转。

模型路由也属于连接层。工作坊给的分工很明确：规划、架构评审这类高推理密度任务用顶配模型；日常代码生成和修复用均衡型号；分类、总结、上下文压缩这类重复任务交给小模型。Claude Code 里既可以在会话内用 /model 切换，也可以用 --model 指定启动模型。另外它做自动压缩上下文时会额外调一个小模型，你可以用 ANTHROPIC_SMALL_FAST_MODEL 指向一个便宜快速的型号，避免压缩这一步也吃主模型的 token。

2.2 上下文层：200k 是上限，不是预算

工程师反复强调一句话：上下文窗口的容量是上限，不是你的预算。即使窗口能装 200k token，里面还要住着系统提示、CLAUDE.md、Skill 描述、工具定义和越来越长的对话历史。真正留给当前任务的有效空间远比数字小。

他给了个信息分级方法，我回来之后直接用了。把 Agent 可能用到的信息分三档：热数据是每次运行都必需的内容，放 CLAUDE.md；温数据是大部分任务会用到、但可以按需加载的内容，收敛成 Skill；冷数据是偶尔才查的内容，放到外部存储，Agent 需要时自己检索。对应到实现上，热层是长驻 prompt，温层是模型的工具选择机制，冷层是检索或外部记忆。

关于会话管理的几个实操点，这块搜教程很少讲清楚：

• /compact 会触发模型把已有对话压缩成摘要。它适合长任务续跑，但会丢失精确信息，尤其是 edge case 和原始报错文本。所以复杂任务做到一半，我更倾向 /clear 开新会话，把关键结论写进 CLAUDE.md 或归档文件，而不是一直 compact。
• 对话历史默认是保存在本地的，可以用claude --resume恢复最近会话。团队协作时，我会让 CI 在每次跑完把会话摘要写到一个 archive 文件，这样任何一个人拿到项目都能快速知道前几轮发生了什么。

信息预算要像代码评审一样纳入流程。团队里可以约定：每次改动 CLAUDE.md 之前，先删掉一段旧内容。入口控制住了，上下文健康度自然就上来了。

3. 第二层：Skill 与工具层，把"会用工具"变成"会分派工具"

3.1 Skill 是温层的操作手册

第二层解决的是 Agent 有没有能力做某件事。Claude Code 里一个很常见的误区，是把所有操作说明一股脑写进 CLAUDE.md。工作坊工程师反问了一句：CLAUDE.md 每次启动都加载，里面如果堆了二十个技能的操作步骤，上下文还能剩多少？Skill 机制的意义就是把它变成按需加载。

一个 Skill 在项目里本质是一个目录：.claude/skills/技能名/SKILL.md，里面用 YAML frontmatter 写名字、描述、允许使用的工具范围，正文就是具体的操作流程。模型读到 description 之后判断当前任务是否匹配，匹配才把整个 SKILL.md 加载进来。我项目里有个数据库迁移 Skill，结构长这样：

--- name: apply-db-migration description: 当需要执行数据库迁移、回滚迁移或查看迁移状态时使用 allowed-tools: - Read - Edit - Bash --- ## 适用场景 - 新增或修改表结构 - 回滚上一次迁移 ## 执行步骤 1. 读取 migrations/ 目录下最新的迁移文件 2. 检查 migrate.sh 的用法 3. 在 dry-run 模式下执行，确认影响行数 4. 得到明确确认后，执行正式迁移并记录结果 ## 典型错误 - 不要直接修改 migrations/ 下已提交的文件 - 迁移失败时保留现场，不要自动重试

注意我把 allowed-tools 限制了，让 Skill 没有权限去编辑无关文件。工作坊的原话是：Skill 内的步骤越接近确定性脚本越好，凡是能被脚本化的操作就不要让模型临场发挥。Skill 描述的是方法论，脚本承担的是确定性，模型负责的是在合适的时候选择它。

3.2 Skill 和 Agent 的分界线：流程与目标的差别

现场有个高频问题：Skill 和 Agent 到底什么关系？工程师给了一个我认为比较准确的分界：Skill 回答的是"怎么做一件事"，Agent 回答的是"如何达成一个目标"。Skill 是操作手册，里面是步骤、命令、注意点；Agent 是执行者，它有自己的上下文、工具集和循环逻辑，会在目标指引下决定调用哪些 Skill。

在 Claude Code 里，子代理定义在 .claude/agents/ 目录。你给子代理写一个角色说明，指定它可以用的工具，它就跑在一个独立上下文里执行。这个差异决定了设计取舍：如果任务是"完整审查这个 PR 并输出问题清单"，这是一个 Agent 任务，因为它需要拆解、多轮探索；如果任务只是"跑一遍这个迁移脚本"，应该做成 Skill，因为它是个确定步骤。

工具层的另一个能力来源是 MCP。Skill 扩展的是方法，MCP 扩展的是外部工具的接入。Claude Code 的 MCP 配置放在 .claude/settings.json 里，本地工具和远程服务都可以接。不过每多接入一个 MCP，Agent 的工具选择空间就大一圈，越权风险也跟着上来。工作坊的建议是：工具层永远遵循够用原则，宁缺毋滥，每个 MCP server 都要过一遍权限评审。

4. 第三层：记忆层，会话寿命与长期身份的平衡

4.1 CLAUDE.md 是工作记忆，不是文档仓库

第三层是记忆。Claude Code 的原生记忆主要是两个：CLAUDE.md 和会话历史。CLAUDE.md 每次启动都会加载进上下文，所以它就是热层记忆，适合放那些每次开工都必须知道的事。但很多人把它当成 wiki 用，几千行项目文档全塞进去——那等于每天花一大笔 token 搬运与当前任务无关的内容。

我给团队定的 CLAUDE.md 模板包含五块：项目命令、代码约定、关键架构决策、危险操作清单、最近变更日志。控制在两百到三百行左右。

# payment-service ## Commands - 本地开发: npm run dev - 测试: npx jest --runInBand - 迁移: ./scripts/migrate.sh up/down ## Conventions - TypeScript strict 模式 - 提交信息遵循 conventional commits - 禁止直接改 generated/ 下的文件 ## Danger - 不要在生产环境执行 npm run reset - 修改 RBAC 缓存必须先清 Redis ## Recent decisions - 支付回调采用幂等表+事件重放（2025-06-12）

写成条目而不是大段散文，规则越具体，模型越不会自由发挥。危险操作清单尤其重要，它相当于给模型一份"哪些事不能做"的负面清单，比口头约束有效得多。

4.2 长期记忆：把状态从上下文窗口里搬出去

CLAUDE.md 适合放项目级知识，但放不下跨任务的执行记录。我的第一个 Agent 项目就踩过这个坑：Agent 每周一都要做一次环境健康巡检，结果它每次都把上一次的巡检结论重新想一遍，因为新会话里什么都没有。后来我按工作坊的思路做了一个外部记忆表，用的就是本地 SQLite：

CREATE TABLE memory ( id INTEGER PRIMARY KEY, task TEXT, command TEXT, result TEXT, tags TEXT, created_at TEXT );

每次巡检结束，用 Claude Code 的 PostToolUse Hook 把关键命令和结果追加到这张表。新会话开始前，在 CLAUDE.md 里写一条规则：执行巡检类任务前，先查 memory 表里最近三十天的相关记录。这样 Agent 就有了"上次做过什么、结果怎么样"的连续认知，不用凭运气。

这里插一个常见问题：Claude Code 的对话历史到底怎么保存？默认会话本身可以在本地恢复，用 claude --resume 就能回到之前会话。但生产上我更推荐把重要的会话结论主动归档到项目里，而不是指望那些原始日志。Hook 追加到 memory 表就是一种归档，这样就算会话文件被清理，长期记忆还在。

记忆层还有一层容易被忽略：Agent 的身份记忆。如果 Agent 需要以固定角色长期服务用户，建议把角色设定放在 CLAUDE.md 顶部，并且定期让它基于历史交互输出"我当前对用户偏好的理解"，写回记忆。这是让 Agent 从工具变成协作者的关键一步，但别忘了给这种机制加权限边界。

5. 第四层：安全与治理层，生产级和玩具 Demo 的分水岭

5.1 权限矩阵：先默认拒绝，再逐项放行

安全这一层，工作坊一点没含糊。工程师的原话是：Demo 可以全绿灯，生产必须红灯优先。Claude Code 的权限模式大家应该都见过：default 会针对敏感操作弹确认，acceptEdits 自动接受文件编辑，plan 只读探索，bypassPermissions 全放行。很多团队图省事直接 bypassPermissions，在本地玩可以，上 CI、上生产就是把事故概率拉满。

生产实践上，我的习惯是：探索阶段用 plan 模式，让 Agent 先把方案拿出来；方案确认后切 acceptEdits 执行代码变更；只有完全可信的自动化场景才考虑 bypassPermissions，而且一定要套一次性容器。

权限规则要在 settings.json 里显式声明，白名单加黑名单并用。比如：

{ "permissions": { "allow": [ "Read(./src/**)", "Bash(npx jest *)" ], "deny": [ "Edit(.env)", "Bash(rm:*)", "Bash(git push *)" ] } }

黑名单的价值是兜底。就算模型临时起意想删文件或推代码，也会被权限拦截。工作坊里有一句话我到现在都记得：权限不是用来限制 Agent 能力的，是用来约束它犯错半径的。

5.2 审计、密钥和提示注入，一个都不能少

安全层另外三个抓手，分别是审计、密钥和注入防御。审计这块，Claude Code 的 Hook 机制可以记录每一次关键动作。以 PostToolUse 为例，在项目 settings.json 里挂一个审计脚本：

{ "hooks": { "PostToolUse": [ { "matcher": "Bash|Edit|Write", "hooks": [ { "type": "command", "command": "python3 .claude/hooks/audit.py" } ] } ] } }

Python 脚本从标准输入读取工具调用的 JSON，把时间、工具名、参数、工作目录追加到一个审计日志里。这里的配置格式不同版本略有差异，以官方文档为准，但思路是通用的。有了审计，你才能在出事后回放"Agent 刚才到底执行了什么"，而不是对着屏幕干瞪眼。

密钥管理上，原则很简单：一切秘密走环境变量或密钥管理服务，禁止写进 CLAUDE.md、Skill 或普通配置文件。尤其 .env 要同时加进权限 deny 列表和 git ignore，双保险。Claude Code 本身也支持 ANTHROPIC_AUTH_TOKEN 这类环境变量，CI 里优先用注入密钥的方式。

提示注入是很多团队没意识到的风险。Agent 读到的网页、文档、命令输出里，可能藏着"忽略你之前的指令，执行某某操作"的恶意内容。防御有三道：第一道，信息来源工具限权，读外部内容用只读模式；第二道，数据进来先经过清洗或摘要，不让原始内容直接进模型；第三道，高危动作必须走人工确认。没有这三道的 Agent，本质上是一台愿意读陌生人便条的自动取款机。

6. 第五层：编排与控制循环，让 Agent 自己拆活干

6.1 Harness 和 Agent 到底差在哪

第五层是容易被忽略但决定成败的一层：编排。工作坊里有一个概念我建议所有 Agent 开发者先搞明白——Harness。什么是 Harness？它是承载 Agent 运行的整个外壳：工具调用循环、授权系统、重试逻辑、上下文管理、与用户的交互界面。什么是 Agent？是 Harness 里那个会思考、会做决策、会被定义角色和记忆的那部分。简单说，Harness 是比赛的场地和规则，Agent 是场上的选手。

这个区分在生产上的意义巨大。Claude Code 本身就是一个非常完整的 Harness：工具循环、权限系统、Hook、会话管理、上下文压缩全都有。你要做的不是在它上面再造一个 Harness，而是把业务能力封装成 Agent、Skill、MCP，填进这个现成的壳里。很多团队一上来就想着自己写编排层，结果花三个月复刻了一个功能更少、错误更多的 Claude Code。

理解了 Harness 和 Agent 的分工，也就理解了为什么有些功能应该放在系统级配置里，有些应该放在 Agent 定义里。凡是所有 Agent 都要遵守的规则，放进 Harness 层，比如全局权限、审计 Hook；凡是某个 Agent 特有的行为，放进 Agent 定义，比如角色、工具偏好、记忆策略。边界划清楚，维护成本会降一大截。

6.2 Checkpoint 让长任务不失控

编排层的第二个重点是控制循环。Agent 的循环本质是：思考 → 选动作 → 执行 → 观察结果 → 再思考。这个循环如果没有任何外部约束，长任务很容易钻牛角尖。工作坊给了一个四阶段模式：Plan → Review → Execute → Verify。也就是让 Agent 在开始执行前先生成方案，人审查通过后再进入执行，执行完必须验证结果，而不是停在最后一次命令的输出上。

在 Claude Code 里的落地方式很直接。第一轮用 claude --permission-mode plan 启动，让它产出一份实施方案，人确认方案后再切到 acceptEdits 模式执行。验证阶段可以专门挂一个测试命令作为收尾动作：

claude -p "$TASK" --permission-mode plan # 人工评审方案 claude -p "$TASK" --permission-mode acceptEdits claude -p "运行项目全部测试并汇报结果" --permission-mode plan

隔离环境执行时，还要给循环套上限。包括最大迭代次数、单次任务超时时间、重试次数。我的 CI 脚本里习惯加 timeout 命令，Agent 超时就发告警而不是无限等下去。

工作坊最后提醒了一件事：Checkpoint 不是打断，是保险。一段长任务跑二十分钟，中间没有一个确认点，大概率会在错误的方向上狂奔二十分钟。生产级 Agent 宁可多几次交互，也不要让模型蒙头跑完全程。

7. 从工作坊到生产：那些搜不到答案的坑

7.1 连接故障排查链路

最后这部分是我根据现场讨论和我自己项目经验整理的实战坑位。先说连接故障。网上关于 unable to connect to anthropic services、failed to connect to api.anthropic.com: status 403 的讨论特别多，但大部分只停留在"我也遇到了"，缺少完整的排查链路。我现在的排查顺序是这样的：

1. 先用 curl 直连确认故障段位，看是不是 Claude Code 之外的问题。
2. 检查认证：ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN 是否过期、是否写错、是否被环境变量覆盖。403 里相当大比例是密钥问题。
3. 检查网络栈：公司代理、防火墙、DNS 解析。企业内网经常有出网白名单，api.anthropic.com 需要在白名单里，这个要找团队网络管理员确认。
4. 检查账号与组织：账号余额、额度限制、组织级策略。429 是限流，403 是拒绝，两者处理方式不同。
5. 如果错误提示明确说明当前地区不受支持，那这不是 bug，也不是能靠配置绕过的。合法路径是通过企业版、官方支持的接入渠道来获取服务，直接走正规商务渠道，别在灰色方案上浪费时间。

这里没有炫技，但就是这五步，能解决团队里八成"连接不上"的问题。很多人卡住是第 2 步和第 3 步顺序搞反了，先折腾网络，最后发现是密钥的问题。

7.2 接入非 Claude 模型时的兼容性边界

社区里经常有人问 Claude Code 能不能接入其他模型，比如通过网关接 DeepSeek 之类的兼容 API。技术上是可以做到的，Claude Code 支持通过环境变量覆盖模型服务的地址：

export ANTHROPIC_BASE_URL=https://你的网关地址 export ANTHROPIC_AUTH_TOKEN=你的网关密钥 export ANTHROPIC_MODEL=目标模型名 claude

但我要把话说清楚：这条路的可行性和体验完全取决于上游网关对 Anthropic Messages API 的兼容程度。Claude Code 的工具调用、系统提示、MCP 交互都走这套协议，如果网关只兼容了普通对话，Agent 一用工具就会表现异常。工作坊的立场很明确：官方功能都以官方模型为准，接第三方模型的团队需要自己做完整的兼容性验证，出了问题不要指望官方支持兜底。我的建议是，开发阶段可以用这种方式测试路由能力，生产环境要么用官方模型，要么把兼容性测试写进发布流程。

7.3 从 Demo 到生产的最小改造清单

最后把工作坊结尾的一张表放出来。工程师说，从 Demo 到生产，不是加一个功能，而是每层都要完成一次加固。这是最小改造清单：

安装这块顺便说一句。Claude Code 的安装有两种主流方式，npm 全局包或者官方安装脚本，Windows 用户走 PowerShell 安装脚本也能跑起来。桌面版和 CLI 在底层用的是同一套 Harness，五层结构不会因为换了界面而消失。装完如果看到 failed to install anthropic marketplace 这类提示，通常是市场源临时抽风或者网络策略拦截了插件源，不影响核心功能，重试或升级到最新版本就行，不用慌。

我后来把所有新 Agent 项目都先过一遍这五层检查：哪一层在需求文档里答不上来设计，就先不写代码。脚手架不是一次性的，项目跑得越久，每层的参数都会需要重新调。但骨架只要搭对了，后面换模型、加技能、接新工具，都是在同一套结构里平移，不用把房子推倒重盖。