企业官网建设流程全解析

1. 项目概述：打破AI编码工具的模型壁垒

作为一名长期混迹在AI辅助开发一线的工程师，我最近发现了一个非常普遍但又令人头疼的问题：我们手头的AI工具越来越多了。OpenAI的Codex擅长快速生成和重构代码，Anthropic的Claude Code在复杂逻辑推理和长文本理解上表现优异，Cursor的智能体模式在项目上下文感知上独树一帜，Google的Gemini CLI则以其庞大的上下文窗口在处理大型代码库时游刃有余。然而，每个工具都像一座孤岛，它们内置的“子智能体”或“代理”功能，都只能调用自家的模型。这意味着，当我在Claude Code里想快速生成一段测试代码时，我无法调用更擅长此道的Codex；当我在Cursor里分析一个复杂的Bug时，也无法临时请出推理能力更强的Claude来帮忙。这种“厂商锁定”不仅限制了我们的工作流，也让团队协作变得复杂——每个人使用的工具不同，共享的自动化脚本就无法通用。

直到我遇到了Sub-Agents Skills这个项目，它精准地击中了这个痛点。它的核心目标非常明确：让你能在任何一个AI编码工具中，将任务委托给任何其他大语言模型来执行。简单来说，它建立了一套统一的“调度”系统。无论你当前正在使用Codex、Claude Code、Cursor CLI还是Gemini CLI作为主工作环境，你都可以通过一套简单的Markdown文件定义各种任务专家（比如“代码审查员”、“测试编写员”、“文档生成器”），然后指定由哪个后端的LLM来执行这个任务。主工具负责协调和发出指令，而具体的脏活累活，则交给最擅长该任务的模型去完成。

这背后的价值远不止于“多模型调用”。它实际上是将AI工作流从“工具依赖”提升到了“能力编排”的层面。你的团队可以定义一套标准的、高质量的Agent模板（比如一份极其详尽的代码审查清单），这套模板不依赖于任何特定IDE或模型供应商。新成员无论偏好哪个工具，都能立刻获得同样水准的AI辅助。对于开发者个人而言，这意味着你可以真正为每个任务挑选最合适的“大脑”，而不是被绑定在单一模型的优缺点上。

2. 核心设计思路与架构解析

2.1 跨模型编排的核心理念

Sub-Agents Skills的设计哲学建立在两个关键洞察之上：任务隔离与接口统一。

首先，它坚持每个子智能体（Sub-Agent）都应该是单一职责的。这与我们编写函数时的“单一功能原则”如出一辙。一个名为security-auditor.md的智能体，其唯一任务就是进行安全审计；一个名为test-generator.md的智能体，就只负责根据代码生成测试用例。这样做的好处是巨大的：每个智能体的行为变得极其可预测，定义可以非常精确，并且可以针对其特定任务选择最合适的LLM后端。例如，安全审计需要严谨的逻辑和广泛的知识，可能更适合Claude；而批量生成样板代码，则可能用Codex更高效、成本更低。

其次，它通过一个轻量级的Python脚本run_subagent.py作为统一适配层。这个脚本扮演了“翻译官”和“调度员”的角色。它接收来自主AI工具（如Claude Code）的指令，解析用户想要调用的具体Agent定义文件（一个Markdown文件），然后根据该文件中指定的run-agent参数，去调用对应的命令行工具（如codex、claude）。最后，它将子智能体执行的结果收集起来，返回给主工具。这个设计巧妙地将复杂的多模型调用逻辑，封装成了一个简单的“技能”（Skill），使得任何支持Agent Skills格式的工具都能轻松集成。

注意：这里提到的“技能”（Skill），是 Agent Skills 开放标准的一部分。你可以把它理解为一个插件包，里面包含了告诉AI如何执行某个任务的元指令（SKILL.md）和实际执行任务的脚本。Sub-Agents Skills本身就是一个这样的技能包，它让AI学会了“派遣子任务”这个能力。

2.2 技术栈与工作流拆解

整个系统的工作流可以清晰地分为三层：

1. 用户交互层：你在自己熟悉的AI编码工具（主Agent）中工作。
2. 技能调度层：run_subagent.py脚本。它由主Agent调用，负责定位Agent定义、解析参数、调用目标CLI并管理执行过程（如超时控制）。
3. 模型执行层：各个LLM提供商官方的CLI工具（如@openai/codex,claude）。它们才是真正执行具体代码任务、与模型API交互的实体。

这种分层架构带来了几个关键优势：

• 解耦：Agent的定义（做什么）与执行（谁来做、用什么做）完全分离。你可以修改Agent的定义而不影响调度逻辑，也可以切换后端CLI而无需重写Agent。
• 可移植性：Agent定义是纯Markdown文件，存放在项目的.agents/目录下。你可以用Git管理它们，在团队间共享，轻松复制到任何新项目。
• 低开销：主Agent的上下文始终保持“干净”。它不需要记住子任务执行过程中的所有细节，只需要知道“我派了个活给专家A，它回复了结果X”。这避免了因上下文过长导致的模型性能下降和成本增加。

一个典型的工作流是这样的：你在Claude Code中分析一个模块，觉得需要补充单元测试。你不需要切换工具，只需输入：“请使用test-writer智能体为这个UserService类生成单元测试。” Claude Code会识别出你想调用一个技能，它找到test-writer.md文件，发现里面指定了run-agent: codex，于是启动run_subagent.py脚本。该脚本会调用codexCLI，并将“为UserService生成单元测试”这个任务，连同test-writer.md中定义的详细指令（如“使用Jest框架”、“覆盖所有公有方法”、“包含边界条件测试”）一并发送给Codex。Codex执行完毕后，将生成的测试代码返回，最终由Claude Code呈现给你。

3. 从零开始的详细配置与实操

3.1 环境准备与基础安装

开始之前，你需要确保两样东西：Python 3.9+和至少一个后端CLI工具。Python是运行调度脚本所必需的，而CLI工具则是实际干活的“工人”。

第一步：安装后端CLI（以Codex和Claude Code为例）

你需要根据计划使用的模型，安装相应的官方命令行工具。这些工具通常是你与对应模型API交互的桥梁。

• 安装OpenAI Codex CLI：

  npm install -g @openai/codex

  安装后，在终端运行codex --help应能显示帮助信息。首次使用可能需要配置API密钥，通常工具会引导你完成。

• 安装Anthropic Claude Code CLI：

  curl -fsSL https://claude.ai/install.sh | bash

  这个安装脚本通常会将claude命令添加到你的系统路径。同样，首次运行claude会进行认证。

• 安装其他CLI：

  • Cursor CLI:curl https://cursor.com/install -fsS | bash
  • Gemini CLI:npm install -g @google/gemini-cli

实操心得：建议在安装后，立即在终端单独运行一次这些CLI命令（如直接输入codex或claude），完成初始的认证和配置。这能避免后续在子智能体调用时出现身份验证错误。另外，将这些CLI的路径确保在系统的PATH环境变量中，是脚本能成功调用的关键。

第二步：安装Sub-Agents Skills技能包

技能包需要安装到你的AI工具特定的技能目录下。不同的工具技能目录路径不同。

• 为Codex安装：

  curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.codex/skills

• 为Claude Code安装：

  curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.claude/skills

安装脚本会从GitHub仓库拉取技能文件（主要是SKILL.md和scripts/run_subagent.py）到指定目录。你也可以选择手动克隆仓库并运行安装脚本：

git clone https://github.com/shinpr/sub-agents-skills.git cd sub-agents-skills # 为目标工具安装，例如Codex ./install.sh --target ~/.codex/skills

3.2 创建并定义你的第一个智能体

安装完成后，核心工作就变成了创建和编写你的智能体定义文件。所有智能体文件都应放在项目根目录下的.agents/文件夹中（你也可以通过环境变量SUB_AGENTS_DIR自定义路径）。

让我们创建一个最常用的智能体：代码审查员。

1. 在你的项目根目录下创建文件夹：

   mkdir -p .agents

2. 在.agents/目录下创建文件code-reviewer.md，并填入以下内容：

   --- run-agent: claude --- # 代码审查员 对指定代码进行深度质量与可维护性审查，聚焦于发现潜在缺陷、坏味道和改进点。 ## 任务 - 逐行分析代码逻辑，寻找潜在的bug、边界条件错误和逻辑漏洞。 - 检查代码风格一致性（如命名规范、缩进、注释），并与项目现有风格对比。 - 识别性能瓶颈，如低效的循环、重复计算或不必要的数据结构。 - 评估函数和类的设计，包括单一职责、耦合度、复杂度（建议圈复杂度>10时提示）。 - 检查安全漏洞，如硬编码的敏感信息、未验证的输入、可能的注入点。 - 提出具体的、可操作的改进建议，并解释每个建议背后的原因。 ## 完成条件 - 所有被提交审查的文件都已分析完毕。 - 发现的问题被分类列出（如：[BUG]、[STYLE]、[PERF]、[SECURITY]、[DESIGN]）。 - 每个问题都附带了代码位置（文件:行号）和清晰的解释。 - 提供了修改代码的具体建议或示例。

关键点解析：

• Frontmatter (---内部分)：这是YAML格式的元数据区。run-agent: claude是这个智能体的“调度指令”，它告诉系统：“当执行这个智能体时，请调用claude这个CLI来运行。” 你可以将其改为codex、cursor-agent或gemini。
• 标题与描述：#后的标题和简短描述用于在列表时展示，帮助用户理解这个智能体的用途。
• ## 任务：这是智能体的核心“系统提示词”。你需要用清晰、无歧义的列表形式，定义这个智能体应该做什么。描述越具体，LLM执行得越精准。这里我故意写得非常详细，覆盖了代码审查的多个维度。
• ## 完成条件：这定义了智能体任务的退出条件。它告诉LLM：“当你完成了以下所有事情时，就可以停止并返回结果了。” 这有助于控制输出的完整性和结构性，避免LLM中途停止或无限发散。

3.3 权限问题与首次运行配置

一个常见的坑是，当子智能体试图通过CLI执行某些操作（比如运行git log或npm test）时，可能会因为CLI工具的安全限制而失败，报出“Permission Denied”或类似的错误。这是因为子智能体是非交互式的，无法响应CLI弹出的“是否允许此操作”的确认提示。

解决方案不是降低安全设置，而是预先授权。

1. 打开终端，直接运行你将要用于子智能体的CLI工具。例如，如果你打算用Codex作为后端：

   codex

2. CLI工具通常会进入一个交互式会话，并可能提示你允许某些命令。例如，它可能会问：“检测到你想运行Shell(cd)命令，是否将其加入允许列表？”
3. 批准这些请求。你的授权会被记录到该CLI工具的配置文件（通常在你的用户目录下，如~/.codex/config.json）中。
4. 之后，当run_subagent.py脚本以非交互方式调用该CLI时，这些预先授权的命令就可以顺利执行了。

避坑指南：务必为你计划使用的每一个后端CLI都执行一次这个“预授权”流程。比如，你的code-reviewer用Claude，test-writer用Codex，那么你就需要分别运行claude和codex来完成授权。这步操作虽小，但能避免后续大量令人困惑的执行错误。

4. 高级用法与智能体设计模式

4.1 在项目中混合使用多模型智能体

Sub-Agents Skills最强大的特性之一，就是可以在同一个项目中无缝混合多个LLM。你可以根据任务特性，为每个智能体分配合适的“大脑”。

假设你的项目.agents/目录结构如下：

.agents/ ├── architect.md # run-agent: claude (擅长复杂设计与推理) ├── reviewer.md # run-agent: claude (同上，深度审查) ├── tester.md # run-agent: codex (擅长快速生成结构化代码) ├── documenter.md # run-agent: gemini (擅长处理大上下文，如整个模块的文档) └── bug-hunter.md # run-agent: cursor-agent (擅长结合项目上下文分析)

在你的主AI工具（比如Claude Code）中，你可以这样组织你的工作流：

1. 需求分析阶段：“使用architect智能体，为这个新的支付模块设计类图和接口。”
2. 编码阶段：（手动或借助主Agent编码）。
3. 审查阶段：“使用reviewer智能体，审查我刚写的PaymentProcessor类。”
4. 测试阶段：“使用tester智能体，为PaymentProcessor生成单元测试，要求覆盖成功、失败和边界情况。”
5. 文档阶段：“使用documenter智能体，为整个src/payment/目录生成API文档。”

关键技巧：在向主Agent发出指令时，一定要具体描述任务内容，而不仅仅是智能体名称。对比以下两种提示：

• 较差：“用一下reviewer。”
• 优秀：“使用reviewer智能体，重点审查src/payment/processor.js文件中的processTransaction方法是否存在并发安全问题，并检查错误处理是否完备。”

后者的指令清晰明确，主Agent能更好地将你的意图传递给子智能体，从而得到更精准的结果。

4.2 编写高效智能体的核心原则

设计一个高效的智能体定义文件，是一门艺术。以下是我从大量实践中总结出的原则：

1. 恪守单一职责这是最重要的原则。一个智能体只做好一件事。不要创建“万能助理”，而应创建“专家团队”。

• 反面例子all-in-one.md: “分析代码、修复bug、编写测试、生成文档。” 这种智能体指令模糊，LLM会困惑，结果往往每个方面都做不好。
• 正面例子：
  • sql-optimizer.md: 只负责分析SQL查询语句并提供优化建议。
  • dependency-updater.md: 只负责检查package.json或requirements.txt，并安全地更新依赖版本。
  • commit-message-linter.md: 只负责根据代码变更生成符合约定式提交规范的提交信息。

2. 定义清晰的边界在“任务”部分明确包含和不包含的内容。

## 任务 - 分析给定的Go函数，识别其时间复杂度与空间复杂度。 - 对于复杂度高于O(n)的函数，提供优化思路。 ## 超出范围 - 不重写函数的具体实现代码。 - 不分析函数的功能正确性。 - 不处理并发安全问题。

明确的边界能极大减少LLM的“幻觉”和无关输出。

3. 结构化输出要求如果可能，要求智能体以特定格式输出，这便于后续自动化处理。

## 输出格式 请按以下Markdown表格格式汇报发现的问题： | 严重性 | 文件位置 | 问题描述 | 建议修复方案 | | :--- | :--- | :--- | :--- | | [高/中/低] | `file.py:42` | 描述... | 建议... |

你甚至可以要求输出JSON，以便直接被其他脚本解析。

4. 提供上下文与示例对于复杂任务，可以在Agent定义中提供一两个简短的“示例输入与输出”，这能极大地对齐LLM的理解。

## 示例 **输入函数：** ```python def factorial(n): result = 1 for i in range(1, n+1): result = result * i return result

期望输出：

• 时间复杂度:O(n)
• 空间复杂度:O(1)
• 优化提示:对于大的n，可考虑使用递归或查表法，但需注意递归深度和栈溢出风险。

这相当于给了LLM一个“标准答案”模板，它能更好地模仿。 ### 4.3 高级配置与参数详解 除了基本的 `run-agent`，脚本还支持一些高级参数，让你能更精细地控制执行过程。这些参数可以通过主AI工具在调用技能时传递（具体语法取决于你的主工具如何支持技能参数）。 * **`--cwd`**：设置子智能体的工作目录。**这必须是绝对路径**。子智能体执行的所有文件操作（如读取文件、运行脚本）都会基于此目录。如果你不指定，默认是脚本运行时的当前目录，但这在复杂的项目嵌套中可能不可靠。明确指定 `--cwd` 是好习惯。 * **`--timeout`**：设置任务超时时间（毫秒）。默认是10分钟（600000毫秒）。对于特别复杂或耗时的任务（如分析整个代码库），你可能需要增加这个值。 * **`--cli`**：强制覆盖Agent定义文件中指定的 `run-agent`。这在你想临时用另一个模型测试同一个Agent时很有用。例如，`reviewer.md` 定义的是 `run-agent: claude`，但你可以在调用时通过 `--cli codex` 临时让Codex来执行这次审查。 **环境变量配置**： * `SUB_AGENTS_DIR`：这是查找 `.agents` 目录的首要位置。如果你不想把智能体定义放在每个项目里，可以设置一个全局目录。 ```bash export SUB_AGENTS_DIR="$HOME/my-global-agents" ``` 这样，在任何项目中，系统都会优先去这个路径寻找智能体。 ## 5. 实战问题排查与经验分享 即使配置正确，在实际使用中也可能遇到各种问题。下面是我遇到的一些典型情况及其解决方法。 ### 5.1 常见错误与解决方案速查表 | 问题现象 | 可能原因 | 排查步骤与解决方案 | | :--- | :--- | :--- | | **`Agent not found`** | 1. 智能体文件不在正确目录。<br>2. 文件名或扩展名错误。 | 1. 确认文件在 `.agents/` 目录下，或 `SUB_AGENTS_DIR` 指向正确。<br>2. 确保文件名使用连字符(`-`)或下划线(`_`)，**不要用空格**。扩展名必须是 `.md` 或 `.txt`。 | | **`CLI not found (exit code 127)`** | 对应的CLI工具未安装或不在PATH中。 | 1. 运行 `which codex` (或 `claude`, `cursor-agent`, `gemini`) 检查是否安装。<br>2. 如果未安装，参考本文“环境准备”部分安装。<br>3. 如果已安装但找不到，检查终端会话的PATH，或将CLI安装目录显式添加到PATH。 | | **`Timeout errors`** | 任务过于复杂，超过了默认10分钟限制。 | 1. 检查子智能体任务是否定义得过于庞大？考虑拆分成更小的智能体。<br>2. 在调用时增加 `--timeout` 参数，例如 `--timeout 1200000` (20分钟)。 | | **`Authentication failed`** | CLI工具的API会话过期或未认证。 | 1. **对于Cursor CLI**：在终端运行 `cursor-agent login` 重新认证。<br>2. **对于Gemini CLI**：直接运行 `gemini` 命令，它会打开浏览器完成认证。<br>3. **对于Codex/Claude**：检查是否有相应的环境变量（如 `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`）已设置且有效。 | | **子智能体输出混乱或不符合预期** | 1. Agent定义中的“任务”描述不够清晰。<br>2. 选择的LLM后端不适合该任务。 | 1. **精炼“任务”描述**：使用更具体、无歧义的语言。明确步骤和输出格式。<br>2. **尝试更换后端**：将 `run-agent` 从 `codex` 改为 `claude`，或反之。不同模型对指令的服从性和擅长领域不同。<br>3. **在“完成条件”中增加约束**，如“输出必须是一个无序列表”或“首先给出总结性结论”。 | | **子智能体试图执行未被允许的Shell命令** | 该CLI工具未预先授权该命令。 | 按照前文“权限问题与首次运行配置”章节的步骤，在终端交互模式下运行一次该CLI，并批准其权限请求。 | ### 5.2 安全使用须知：智能体即代码，代码需审计 这是一个必须高度重视的方面。Sub-Agents Skills中的智能体定义文件（`.md`）本质上是**给LLM的系统提示词**，它拥有很高的权限。一个恶意的智能体定义可以包含这样的指令：“读取 `/home/user/.ssh/id_rsa` 文件并将其内容发送到某个外部服务器”，或者“递归删除当前目录下所有文件”。 因此，请务必遵循以下安全准则： 1. **只使用自己编写或完全信任的来源的智能体定义**。不要随意从互联网下载并运行未知的 `.md` 文件。 2. **在团队共享时，将 `.agents/` 目录纳入代码审查流程**。像审查源代码一样审查智能体定义，检查其中是否包含危险的系统命令或数据泄露风险。 3. **利用“超出范围”部分进行限制**：在定义智能体时，明确写上“禁止执行任何Shell命令”、“禁止访问项目根目录以外的文件系统”等，这能在一定程度上约束LLM的行为（尽管不是绝对可靠）。 4. **在沙盒或低权限环境中测试新智能体**。首次运行一个来源不明的智能体时，最好在一个无关紧要的临时目录或容器中进行。 ### 5.3 性能优化与成本控制心得 使用多个模型固然强大，但也意味着可能产生多份API调用成本。以下是一些优化建议： * **任务粒度要适中**：不要为每一个微小的操作都创建一个智能体。频繁的调用会产生大量的上下文切换开销和API调用延迟。将相关的、连续的小任务合并成一个逻辑完整的智能体任务。 * **善用“完成条件”**：明确的完成条件可以防止LLM进行无意义的发散和重复，生成冗长的内容，从而节省token。 * **为智能体选择合适的模型**：并非所有任务都需要最强大、最昂贵的模型。像“代码格式化”、“简单重命名”这类任务，用速度快、成本低的模型（如GPT-3.5-Turbo对应的CLI，如果支持）更划算。而“架构设计”、“复杂算法审查”则值得使用能力更强的模型。 * **缓存常用结果**：对于一些相对稳定、不常变化的任务结果（如针对某个稳定库生成的API文档），可以考虑将智能体的输出保存下来，而不是每次都重新生成。你可以设计一个智能体，其最后一步是“将输出保存到 `docs/api.md` 文件”，并在“完成条件”中增加“如果目标文件已存在且内容与本次输出核心部分一致，则跳过重写”。这需要更精细的提示词工程。 Sub-Agents Skills这个项目，本质上提供了一种“元工作流”的能力。它不替代任何具体的AI编码工具，而是为它们装上了一套统一的、可插拔的“外挂专家系统”。当你习惯了这种工作模式后，你会发现你的开发流程变得更加模块化和高效。你不再是在“使用一个AI工具”，而是在“指挥一个由各领域AI专家组成的团队”。这种思维模式的转变，或许才是这个工具带来的最大价值。