企业官网建设流程全解析

1. 为什么你的 Agent 总是“差点意思”

如果你正在用 deepagents 搭 Agent，大概率遇到过这种场景：模型本身能力不差，但一到具体任务就开始“自由发挥”——让它审查代码，它给你写一段泛泛而谈的点评；让它按团队规范生成文档，它按自己的理解来一套。问题不在模型，而在于你没有把“专业能力”以结构化的方式喂给它。

AI Skills 技能系统解决的就是这件事。你可以把它理解成给 Agent 装 App：每个 Skill 是一个独立的功能单元，里面封装了特定领域的指令、脚本和参考资料。Agent 在收到请求时，先扫描所有技能的元数据，做语义匹配，命中后把该技能的完整指令加载进上下文，再按步骤执行。整个过程对用户透明，你只管表达意图，Agent 自己找技能、用技能。

这套机制的核心载体是一个叫SKILL.md的文件。它由两部分组成：开头的 YAML Frontmatter 定义技能名称和描述，后面的 Markdown 正文写具体执行指令。描述字段尤其关键，它直接决定 Agent 能不能在正确的时机找到这个技能。一个写得好的 description 应该简洁、包含触发条件，让 Agent 一看就知道“什么场景下该用我”。

这篇文章面向正在使用 deepagents 和 FilesystemBackend 的开发者，我会从目录结构讲起，给出技能注册的配置骨架，然后通过 TaoToken 统一 Key/API 通道接入，最后演示 Agent 加载技能后自动增强的完整验证步骤。全程可跟做，代码可直接复制。

2. 前置准备：TaoToken 统一 Key 与 API 通道

在写 Skill 之前，先把模型接入这层理顺。deepagents 底层依赖 LangChain 的模型初始化，而很多开发者在多模型切换时最头疼的就是 Key 和 base_url 的管理。我的做法是用 TaoToken 做统一入口，一个 Key 走通所有模型调用，省去到处配环境变量的麻烦。

TaoToken 的 API 地址是https://taotoken.net/api，你需要在控制台创建一个 API Key。拿到 Key 之后，把它写进项目的.env文件，不要硬编码在代码里。下面是我实际使用的.env结构：

# .env TAOTOKEN_API_KEY=sk-你的key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=gpt-4o-mini

这里TAOTOKEN_MODEL可以换成你需要的任何模型标识，TaoToken 会根据模型名路由到对应的上游。如果你还没创建 Key，可以去控制台的 API Keys 页面生成一个，建议按项目分 Key，方便后续排查用量。

注意：deepagents 目前不支持通过init_chat_model直接构造的模型对象，需要调整初始化方式。下面第 3 节会给出可用的写法。

环境准备好之后，安装依赖：

pip install deepagents python-dotenv langchain langchain-community

装完之后先别急着写 Skill，我们先把目录结构定下来，这是整个技能系统能跑通的基础。

3. SKILL.md 目录结构与技能注册配置骨架

3.1 目录结构设计

一个 Skill 的标准目录长这样：

skills/ └── code-review/ ├── SKILL.md # 必需，技能指令和元数据 ├── scripts/ # 可选，可执行脚本 │ └── review.py └── references/ # 可选，参考文档、示例数据 └── rules.md

SKILL.md是唯一必需的文件。scripts/放 Python、Shell 等可执行脚本，Agent 可以在指令中调用它们。references/放辅助资料，比如团队编码规范、示例输入输出，Agent 需要时会读取。

3.2 SKILL.md 文件写法

Frontmatter 用 YAML 格式，定义name和description。description 要包含触发条件，这是 Agent 做语义匹配的依据。正文部分写具体执行步骤。

--- name: code-review description: 审查代码质量、检查常见问题。当用户要求代码审查、review 代码、检查代码规范时使用。 --- # 代码审查 审查代码文件，检查以下问题： - 语法错误和潜在 Bug - 代码风格和规范性 - 性能问题 - 安全隐患 ## 使用方法 当用户要求审查代码时，执行： python /skills/code-review/scripts/review.py <file_path> ## 输出格式 按严重程度分类： - 严重问题（必须修复） - 警告（建议改进） - 提示（可选优化）

description 里我特意加了“当用户要求代码审查、review 代码、检查代码规范时使用”，这三个短语覆盖了用户可能的表达方式，能显著提高匹配命中率。如果你只写“审查代码”，用户说“帮我看看这段代码有没有问题”时可能就匹配不上。

3.3 技能注册配置骨架

deepagents 的create_deep_agent通过skills参数指定技能目录。这里有个容易忽略的点：默认使用的是内存后端StateBackend，它读不到本地文件系统。要加载磁盘上的 Skill 文件，必须显式传入FilesystemBackend。

import os from dotenv import load_dotenv from deepagents import create_deep_agent from deepagents.backends import FilesystemBackend from langchain.chat_models import init_chat_model from langchain_core.tools import BaseTool from langchain_community.tools import WriteFileTool, ReadFileTool, ListDirectoryTool load_dotenv() # 使用 configurable_fields 创建可配置模型 model = init_chat_model( model_provider="openai", configurable_fields=["model", "api_key", "base_url"], config_prefix="TAOTOKEN" ).with_config({ "configurable": { "TAOTOKEN_model": os.getenv("TAOTOKEN_MODEL"), "TAOTOKEN_api_key": os.getenv("TAOTOKEN_API_KEY"), "TAOTOKEN_base_url": os.getenv("TAOTOKEN_BASE_URL") } }) os.environ["OPENAI_API_KEY"] = os.getenv("TAOTOKEN_API_KEY") os.environ["OPENAI_BASE_URL"] = os.getenv("TAOTOKEN_BASE_URL") model = f"openai:{os.getenv('TAOTOKEN_MODEL')}"

这里config_prefix设为TAOTOKEN，对应的环境变量就是TAOTOKEN_model、TAOTOKEN_api_key、TAOTOKEN_base_url。这样配置的好处是模型、Key、base_url 三者解耦，换模型时只改.env里的TAOTOKEN_MODEL即可，代码不用动。

接下来定义工具和创建 Agent：

class CalculateTool(BaseTool): name: str = "calculate" description: str = "计算数学表达式的值" def _run(self, expression: str) -> str: try: return f"计算结果: {eval(expression)}" except Exception as e: return f"计算错误: {str(e)}" async def _arun(self, expression: str) -> str: return self._run(expression) calculate = CalculateTool() write_file = WriteFileTool() read_file = ReadFileTool() list_dir = ListDirectoryTool() agent = create_deep_agent( model=model, tools=[calculate, write_file, read_file, list_dir], system_prompt="你是一个助手，会用工具计算、读写文件、列出目录。", skills=["skills"], backend=FilesystemBackend(root_dir=os.getcwd()), debug=True )

skills=["skills"]告诉 Agent 去skills目录下扫描所有SKILL.md。backend=FilesystemBackend(root_dir=os.getcwd())让 Agent 能读取当前工作目录下的文件。debug=True会打印技能匹配和加载的日志，调试阶段建议开着。

4. 验证请求：Agent 加载技能后自动增强

配置写好了，怎么确认技能真的被加载并生效？我设计了一组查询来验证，覆盖技能匹配、工具调用、文件读写三个维度。

queries = [ "审查 mcp_weather.py 代码", "计算 2024*12+500，然后把结果保存到 result.txt", "读取 result.txt 的内容", "列出当前目录文件" ] for q in queries: print(f"\n问：{q}") result = agent.invoke({"messages": [{"role": "user", "content": q}]}) print(f"答：{result['messages'][-1].content}")

跑起来之后，重点观察第一个查询。当输入“审查 mcp_weather.py 代码”时，Agent 会先扫描skills目录下所有SKILL.md的 Frontmatter，提取出code-review这个技能的 name 和 description，生成可用技能列表。然后把用户请求和列表里的 description 做语义匹配，命中code-review后调用load_skill方法，把该技能的完整 Markdown 指令加载到对话上下文中。最后 Agent 按照指令里的步骤，调用review.py脚本执行审查，返回结果。

如果你开了debug=True，控制台会打印类似这样的日志：

[Skill] Scanning skills directory... [Skill] Found: code-review - 审查代码质量、检查常见问题... [Skill] Matching query: 审查 mcp_weather.py 代码 [Skill] Matched: code-review [Skill] Loading skill: code-review [Skill] Executing: python /skills/code-review/scripts/review.py mcp_weather.py

看到Matched: code-review和Loading skill这两行，就说明技能系统正常工作了。第二个查询验证的是工具调用链：Agent 先调calculate算出结果，再调write_file写入文件。第三个查询验证read_file能读回内容。第四个验证list_dir。

实测下来，加了 Skill 之后最明显的变化是：以前让它审查代码，它会输出一段通用点评；现在它会按SKILL.md里定义的分类格式输出，严重问题、警告、提示分得清清楚楚，而且会真的去调用review.py脚本，而不是凭空生成。

5. 本篇常见错排查

5.1 技能没被匹配到

最常见的原因是 description 写得太窄。比如只写“审查代码”，用户说“帮我看看这段代码有没有问题”就匹配不上。解决办法是在 description 里补充同义触发词，用逗号分隔。另外检查skills参数路径是否正确，skills=["skills"]是相对路径，相对于FilesystemBackend的root_dir。

5.2 报错 “StateBackend cannot read local files”

这是没传FilesystemBackend导致的。create_deep_agent默认用内存后端，读不到磁盘文件。加上backend=FilesystemBackend(root_dir=os.getcwd())即可。注意root_dir要指向包含skills目录的父目录。

5.3 模型初始化报错 “init_chat_model object has no attribute”

deepagents 目前不支持直接传init_chat_model构造的模型对象。需要用configurable_fields方式创建，然后通过with_config注入配置，最后用f"openai:{model_name}"字符串形式传给create_deep_agent。上面第 3.3 节的代码就是可用的写法。

5.4 脚本执行权限问题

SKILL.md里写的python /skills/code-review/scripts/review.py是绝对路径。如果你的root_dir不是/，这个路径会找不到文件。建议改成相对路径python skills/code-review/scripts/review.py，或者用os.path.join动态拼接。另外确认脚本有可执行权限，Linux/macOS 下chmod +x review.py。

5.5 API 调用返回 401 或 404

检查.env里的TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL是否正确。base_url 应该是https://taotoken.net/api，不要多加/v1或结尾斜杠。如果用的是自定义模型名，确认 TaoToken 控制台里该模型可用。401 通常是 Key 无效，404 通常是 base_url 或模型名写错。

6. 把技能系统用起来

Skill 系统的价值在于模块化。你可以为团队常用的每个任务写一个 Skill：代码审查、文档生成、数据分析、接口测试。每个 Skill 独立开发、独立测试、独立复用。新成员加入时，不用口头传授规范，把SKILL.md给他看就行，Agent 会自动按规范执行。

如果你想让 Agent 在长期编码任务中持续变强，建议把常用 Skill 沉淀到项目仓库里，配合 TaoToken 的 Coding Plan 做统一模型调度。需要生成新 Key 或查看用量，去控制台的 API Keys 页面操作。接入文档里有更详细的参数说明和示例，遇到报错可以先对照排查。

最后留一个实用技巧：SKILL.md的 description 字段值得反复打磨。我通常会拿 10 条真实用户请求做测试，看命中率。如果某条没命中，就把那条请求里的关键词补进 description。迭代两三轮之后，匹配准确率会有明显提升。