企业官网建设流程全解析

1. 为什么需要构建自己的 AI Agent 发行版

1.1 从“能用”到“好用”之间的鸿沟

大多数人接触 AI Agent 的路径都差不多：先拿一个开源框架跑通 Demo，再接入几个工具，最后发现每次换项目都要重新配一遍环境、重新调一遍参数、重新写一遍系统提示词。这个过程重复三次以上，你就会开始想一件事——能不能把这些东西打包成一个“发行版”，像装 Linux 发行版一样，装完就能用，换台机器也能快速复现。

这就是“AI Agent 发行版”要解决的问题。它不是某个具体的 Agent 产品，而是一套可复用、可分发、可版本管理的配置集合。你可以把它理解成一份“Agent 的操作系统镜像”：里面预置了 Profile（配置文件）、工具链、权限策略、日志方案和部署脚本。换项目时只需要切换 Profile，而不是从零开始搭。

我最初做这件事的动机很实际：手上有三个不同场景的 Agent 项目，一个做代码审查，一个做数据分析，一个做客服问答。每次切换项目，光是环境变量和工具权限就要调半小时。后来我把公共部分抽出来做成基础镜像，差异部分做成 Profile，切换成本直接降到一条命令。

1.2 发行版的核心组成：Profile 是灵魂

一个 AI Agent 发行版通常包含四层：

• 基础运行时层：Python/Node 版本、依赖包、模型 SDK、向量库客户端
• Profile 配置层：模型选择、温度参数、系统提示词、工具白名单、上下文窗口策略
• 工具与插件层：文件读写、网络请求、数据库连接、代码执行沙箱
• 部署与运维层：容器镜像、启动脚本、日志采集、健康检查

其中 Profile 是最关键的一层。它决定了 Agent 的“人格”和“能力边界”。同一个运行时，加载不同的 Profile，就能变成完全不同的 Agent。比如webProfile 偏向信息检索和摘要，codeProfile 偏向代码生成和审查，dataProfile 偏向 SQL 生成和图表解释。

提示：Profile 不要做成一个大而全的 JSON，而是按“基础 Profile + 覆盖 Profile”的方式分层。基础 Profile 放通用配置，覆盖 Profile 只写差异项。这样维护成本最低。

1.3 适合谁来参考这套流程

这套流程适合三类人：一是已经用过至少一个 Agent 框架、想提升复用效率的开发者；二是团队里需要统一 Agent 配置规范的技术负责人；三是想把 Agent 部署到生产环境、但被环境差异和权限问题困扰的运维同学。如果你还没跑通过任何一个 Agent Demo，建议先跑通一个最小闭环再回来看发行版设计，否则容易过度设计。

2. Profile 定制：从零设计一份可复用的配置

2.1 Profile 的目录结构与字段设计

我试过很多种 Profile 组织方式，最后稳定下来的结构是这样的：

profiles/ base/ agent.yaml prompts/ system.md tools.yaml web/ agent.yaml prompts/ system.md tools.yaml code/ agent.yaml prompts/ system.md tools.yaml

agent.yaml放模型和运行时参数，prompts/system.md放系统提示词，tools.yaml放工具白名单和权限。加载时先读base，再用目标 Profile 覆盖同名字段。

agent.yaml的核心字段我一般这样写：

model: provider: openai-compatible name: deepseek-chat temperature: 0.3 max_tokens: 4096 context: max_rounds: 20 summary_threshold: 0.8 runtime: timeout_seconds: 120 retry: 2

这里有几个参数值得展开说。temperature在代码类 Profile 里我通常设 0.1 到 0.3，因为需要稳定输出；在创意类 Profile 里会设 0.7 到 0.9。summary_threshold是上下文压缩的触发比例，0.8 表示当对话历史达到上下文窗口的 80% 时触发摘要压缩。这个值设太低会导致频繁压缩、丢失细节，设太高又容易超限，0.75 到 0.85 是比较稳的区间。

2.2 系统提示词的分层写法

系统提示词不要写成一大段散文。我习惯分成四块：角色定义、能力边界、输出格式、禁止事项。以代码审查 Profile 为例：

## 角色 你是一名资深代码审查员，专注于发现逻辑错误、边界问题和性能隐患。 ## 能力边界 - 只审查用户提供的代码片段或文件 - 不执行代码，只做静态分析 - 不确定的问题必须标注“需人工确认” ## 输出格式 按严重程度分级：阻塞、警告、建议。每条包含行号、问题描述、修复建议。 ## 禁止事项 - 不评价代码风格偏好 - 不生成与审查无关的重构方案

这种写法的好处是可测试。你可以针对每一块写断言，比如“输出中必须包含严重程度分级”“不确定问题必须带人工确认标记”。Profile 的质量不是靠感觉，而是靠这些可验证的约束。

2.3 工具白名单与权限最小化

工具配置是安全的重灾区。我的原则是：默认全部关闭，按 Profile 显式开启。tools.yaml大概长这样：

tools: file_read: enabled: true allowed_paths: - ./src - ./docs file_write: enabled: false shell: enabled: false http_request: enabled: true allowed_domains: - api.internal.example.com

file_write和shell在大多数 Profile 里我都默认关闭。需要开的场景单独做 Profile，并且加上路径限制和命令白名单。我踩过的坑是：早期为了图方便把shell全开，结果 Agent 在一次调试中执行了一条删除临时目录的命令，虽然没造成损失，但那次之后我就把权限收紧了。

注意：工具白名单要配合运行时校验，不能只靠配置文件。Agent 发起工具调用时，运行时必须再检查一次路径和域名，防止提示词注入绕过配置。

3. 生产部署：把 Profile 变成可运行的镜像

3.1 容器化方案与基础镜像选择

生产部署我推荐容器化，原因很简单：环境一致性。本地跑通的 Profile，打包成镜像后在任何支持容器的环境都能跑。基础镜像我一般选python:3.11-slim或node:20-slim，取决于 Agent 运行时用什么语言。

Dockerfile 的关键不是装依赖，而是分层缓存和 Profile 注入：

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY runtime/ ./runtime/ COPY profiles/ ./profiles/ ENV AGENT_PROFILE=base CMD ["python", "-m", "runtime.main", "--profile", "${AGENT_PROFILE}"]

这里AGENT_PROFILE用环境变量注入，同一个镜像可以通过-e AGENT_PROFILE=code切换成代码审查 Agent。这样你只需要维护一个镜像，而不是每个 Profile 打一个镜像。镜像体积也能控制住，因为 Profile 只是文本配置，不增加层大小。

3.2 启动参数与资源限制

生产环境和本地最大的区别是资源限制。本地你可以让 Agent 随便跑，生产环境必须设上限。我通常设三组限制：

超时设置要结合模型响应时间。如果用的是推理型模型，首次响应可能超过 30 秒，超时设太短会导致大量失败。我的经验是：先测 P95 响应时间，再把超时设成 P95 的 2 倍左右。

3.3 日志、监控与健康检查

Agent 的日志和普通服务不一样，它需要记录对话轮次、工具调用、token 消耗和错误堆栈。我一般用结构化日志，每条记录包含session_id、profile、round、tool_calls、tokens_used、latency_ms。

健康检查分两层：一层是进程存活检查，一层是模型连通性检查。进程存活用 HTTP 端点/healthz返回 200 即可。模型连通性检查稍微复杂一点，我通常发一个极短的测试请求，比如“回复 OK”，如果 5 秒内返回就认为健康。这个检查频率不要太高，否则会浪费 token，我一般设 60 秒一次。

提示：健康检查的测试请求要单独走一个低优先级队列，不要和正常请求抢配额。否则高峰期健康检查失败会触发误告警。

4. 常见问题与排查技巧实录

4.1 Profile 加载失败与字段覆盖问题

最常见的问题是 Profile 覆盖不生效。原因通常是 YAML 合并策略写错了。浅合并只会替换顶层字段，嵌套字段会整个丢掉。比如base里model.temperature=0.3，codeProfile 里只写了model.name，浅合并后temperature就没了。

解决办法是用深合并。Python 里可以用deepmerge库，Node 里可以用lodash.merge。但深合并也有坑：数组字段是替换还是追加？我的做法是数组一律替换，需要追加的场景在 Profile 里写完整数组。这样行为可预测，不会出现“以为追加了其实替换了”的问题。

4.2 工具调用超时与重试策略

工具调用超时在生产环境很常见，尤其是网络请求类工具。我的重试策略是：只对幂等操作重试，比如读文件、查数据库；写操作和 shell 命令不自动重试，而是返回错误让上层决定。

重试次数设 2 次，间隔用指数退避，第一次 1 秒，第二次 2 秒。超过 2 次还失败就放弃，记录错误日志。这里有个细节：重试时要带上原始request_id，方便日志关联。否则一次请求产生三条日志，排查时对不上。

4.3 上下文溢出与摘要压缩失效

上下文溢出通常发生在长对话场景。摘要压缩失效的原因一般是摘要提示词写得太泛，比如“总结以上对话”，结果摘要丢掉了关键的工具调用结果。

我的改进方法是：摘要时强制保留三类信息——已确认的事实、未解决的问题、已调用的工具及结果。摘要提示词里明确写“不要总结寒暄和重复内容，只保留事实和待办”。这样压缩后的上下文虽然短，但关键信息不丢。

4.4 常见问题速查表

5. 从发行版到团队规范：一些落地经验

5.1 版本管理与变更记录

Profile 要像代码一样做版本管理。每次修改agent.yaml或系统提示词，都要写变更记录：改了什么、为什么改、影响哪些场景。我见过团队因为没记录，导致某次提示词改动让客服 Agent 的回答风格突变，排查了两天才定位到。

版本号我建议用语义化版本：主版本号在 Profile 结构不兼容时递增，次版本号在新增工具或字段时递增，修订号在提示词微调时递增。这样回滚时能快速定位到具体版本。

5.2 团队协作中的 Profile 评审

Profile 变更应该走代码评审。评审重点不是格式，而是三件事：权限有没有扩大、提示词有没有引入歧义、参数调整有没有依据。尤其是权限扩大，必须有人明确批准。我通常要求权限变更单独提交，不和提示词调整混在一起，方便追溯。

5.3 后续扩展方向

这套发行版结构后续可以扩展的方向不少。比如加一个 Profile 市场，团队内部共享常用配置；或者加一个 A/B 测试机制，同时跑两个 Profile 对比效果；还可以把 Profile 和评估集绑定，每次变更自动跑一遍回归测试。这些扩展都不需要改运行时核心，只需要在 Profile 层加约定。

我个人在实际操作中的体会是：发行版的价值不在于技术多复杂，而在于把重复劳动变成一次配置。前期多花两小时设计 Profile 结构，后期每个项目能省半天。这笔账怎么算都划算。