企业官网建设流程全解析

1. 为什么你的 deep agent 加载不上 SKILL

如果你最近在 LangChain 里折腾 deep agent，大概率会遇到一个很具体的场景：代码里明明写了skills=["./skills"]，启动之后 agent 却像没看见一样，问它问题还是走通用推理，压根不调用你写好的 SKILL。更让人抓狂的是，控制台不报错，日志也不提示，你只能靠猜。

这个问题的核心在于，deep agent 加载 SKILL 不是「把文件夹路径塞进去」就完事。它依赖三个东西同时成立：SKILL 目录结构符合约定、backend 能真实访问本地文件、settings.json 里的模型通道配置正确。任何一环断了，SKILL 就是静默失效。

我这次要解决的就是「一次配置跑通」这件事。目标很明确：在本地开发环境里，用一份可复制的settings.json骨架，把 deep agent 和 SKILL 的加载链路打通，启动后能确认 SKILL 注册成功，并且 deep agent 真的能调用它。适合正在做本地 Agent 开发、被 SKILL 加载卡住的同学，也适合刚接触 deep agent、想先跑通最小闭环的人。

SKILL 这个概念本身不复杂，你可以把它理解成「给 agent 准备的能力卡片」——每个 SKILL 是一个文件夹，里面放一个SKILL.md描述这个能力干什么、怎么用，再配上需要的脚本。agent 在需要的时候按需加载，而不是把所有工具一次性塞进上下文。deep agent 对 SKILL 的支持，就是让这套机制原生跑起来。

但原生支持不等于零配置。下面我把整条链路拆开讲，从统一 Key 通道到 settings.json 骨架，再到验证和排障。

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

在写 settings.json 之前，先把模型通道这件事定下来。本地开发最容易乱的地方就是 Key 管理：今天用这个平台的 Key，明天换那个模型的 base_url，配置文件改来改去，最后自己都记不清哪个 Key 对应哪个通道。

我的做法是走一个统一的 API 通道，把模型调用收敛到一个入口。TaoToken 提供的就是这个能力，官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。它的作用是让你用一套 Key 去访问不同的模型，deep agent 里的ChatOpenAI只要把base_url指向这个通道，模型切换就不用动业务代码。

具体操作上，你需要先拿到一个 API Key。登录之后进控制台，在 API Keys 页面创建一个新的 Key，复制出来备用。这个 Key 后面会写进 settings.json 或者环境变量里。

这里有个细节要注意：deep agent 底层用的是ChatOpenAI这类兼容 OpenAI 协议的客户端，所以你的通道必须兼容 OpenAI 的/chat/completions接口格式。TaoToken 的 API 入口就是按这个协议来的，直接把base_url设成https://taotoken.net/api即可，不需要额外适配层。

如果你后面要长期跑编码类任务或者 Agent 工作流，可以考虑 Coding Plan，它在持续调用场景下更省心。但本篇先聚焦最小闭环，用按量 Key 就能跑通。

3. 可复制的 settings.json 配置骨架

现在进入正题。deep agent 加载 SKILL 的配置，我建议拆成两部分：一部分是settings.json，管模型通道和运行参数；另一部分是 agent 创建代码，管 SKILL 目录和 backend。这样职责清晰，出问题好定位。

先看settings.json骨架。放在项目根目录：

{ "model": { "provider": "openai-compatible", "base_url": "https://taotoken.net/api", "api_key_env": "TAOTOKEN_API_KEY", "model_name": "Doubao-Seed-2.0-pro", "temperature": 0 }, "agent": { "skills_dir": "./skills", "virtual_mode": true, "root_dir": ".", "checkpointer": "memory", "thread_id": "local-dev-1" }, "runtime": { "python_env": "auto", "log_level": "INFO" } }

逐项说明一下。base_url指向 TaoToken 的 API 入口，api_key_env表示 Key 从环境变量TAOTOKEN_API_KEY读取，不要把 Key 硬编码进文件。model_name按你实际要用的模型填，这里用豆包系模型举例，因为它兼容 OpenAI 协议，ChatOpenAI能直接调。

skills_dir是 SKILL 的根目录，virtual_mode和root_dir对应LocalShellBackend的参数，决定 backend 能不能访问本地文件。checkpointer设成memory表示用内存记忆，本地调试够用。thread_id是会话标识，invoke 时传给 config。

然后是 agent 创建代码，读取这份配置：

import os import json from dotenv import load_dotenv from deepagents import create_deep_agent from deepagents.backends import LocalShellBackend from langchain_openai import ChatOpenAI from langgraph.checkpoint.memory import InMemorySaver load_dotenv() with open("settings.json", "r", encoding="utf-8") as f: cfg = json.load(f) model_cfg = cfg["model"] agent_cfg = cfg["agent"] model = ChatOpenAI( api_key=os.getenv(model_cfg["api_key_env"]), model_name=model_cfg["model_name"], base_url=model_cfg["base_url"], temperature=model_cfg["temperature"], ) agent = create_deep_agent( model=model, backend=LocalShellBackend( root_dir=agent_cfg["root_dir"], virtual_mode=agent_cfg["virtual_mode"], ), skills=[agent_cfg["skills_dir"]], checkpointer=InMemorySaver(), system_prompt="你是一个智能助手，优先使用已注册的 SKILL 完成任务。", )

关键点有三个。第一，LocalShellBackend是加载本地 SKILL 的核心，没有它 agent 访问不到本地文件，SKILL 自然加载不了。第二，skills参数传的是目录列表，deep agent 会扫描这个目录下的 SKILL 文件夹。第三，system_prompt里明确提示优先用 SKILL，能提高调用命中率。

SKILL 目录本身要符合约定。每个 SKILL 是一个小写命名的文件夹，里面至少有一个SKILL.md：

skills/ query-course/ SKILL.md run.py convert-id/ SKILL.md convert.py

SKILL.md里写清楚这个技能的名称、用途、输入输出。deep agent 读取它来决定什么时候加载。文件夹名必须小写，大写命名目前识别不了，这是实测踩过的坑。

4. 验证请求与成功结果

配置写完，怎么确认 SKILL 真的注册成功了？不要靠感觉，用两个动作验证。

第一个动作，启动时打印已注册的 SKILL 列表。deep agent 创建后，可以检查 agent 的 skills 属性：

print("registered skills:", agent.skills)

如果输出里包含你目录下的 SKILL 名称，说明扫描和注册这一步过了。如果输出是空列表，说明目录结构或 backend 有问题，直接跳到下一节排障。

第二个动作，发一个必须依赖 SKILL 才能答对的请求。比如你有一个convert-id技能，负责把 ID 转成人名。构造一个只有调用该技能才能得到正确结果的输入：

results = agent.invoke( {"messages": [{"role": "user", "content": "查询 ID 1001 对应的名称"}]}, config={"configurable": {"thread_id": "local-dev-1"}}, ) for message in results["messages"]: message.pretty_print()

成功的结果长这样：agent 的中间步骤里会出现调用convert-id技能的动作，最终返回的是人名而不是原始 ID。如果它直接返回1001或者答非所问，说明 SKILL 没被调用。

这里有个经验：deep agent 和开箱即用的 Agent 产品不一样，它更像脚手架。同样的 SKILL，在封装好的产品里会自动做 ID 到人名的关联转换，但在 deep agent 里，如果你不写系统提示词引导，它可能只返回原始 ID。所以验证时要把system_prompt写清楚，明确告诉它「如果结果是 ID，就调用对应 SKILL 转换」。

跑通这两个动作，最小闭环就成了。启动无报错、SKILL 列表非空、请求能触发技能调用，三件事同时满足，才算真的加载成功。

5. 本篇常见错排查

下面这几个错，是我在本地环境里实际遇到过的，按出现频率排。

SKILL 列表为空，但目录明明存在。先查文件夹命名，必须全小写。QueryCourse这种驼峰命名识别不了，改成query-course。再查SKILL.md是否存在且文件名大小写正确，有些系统对大小写不敏感，但 deep agent 的扫描逻辑是敏感的。

agent 能启动，但请求时不调用 SKILL。大概率是system_prompt没引导。deep agent 不会无条件加载所有技能，它根据任务和提示词判断。在系统提示里明确「优先使用已注册 SKILL」「遇到 ID 先转换」这类指令，命中率会明显提升。

报错找不到模型或 401。检查TAOTOKEN_API_KEY环境变量是否真的注入了。load_dotenv()要在读取配置之前调用，.env文件里写TAOTOKEN_API_KEY=你的Key。另外确认base_url是https://taotoken.net/api，不要多加路径后缀。

Windows 下 SKILL 里的脚本跑不起来。MacOS 通常不用额外指定 Python 环境变量，但 Windows 必须手动配。如果 SKILL 里有 Python 脚本，确认python在 PATH 里，或者用绝对路径调用解释器。这一步不配，技能加载了也执行不了。

backend 访问不到文件。LocalShellBackend的root_dir要设成项目根目录，virtual_mode设true时路径解析走虚拟模式。如果你把root_dir设错，SKILL 目录相对路径就找不到。建议root_dir="."，skills_dir="./skills"，保持相对关系一致。

改了配置不生效。deep agent 创建时读取一次配置，改完settings.json要重启进程。热更新不适用于 SKILL 目录扫描，别指望改完文件就自动重载。

排障时如果卡在接入层，可以直接看接入文档，里面有通道配置的细节。验证模型通道是否通，用模型对话页面发一条测试消息最快，能排除是 Key 问题还是代码问题。

6. 下一步怎么走

最小闭环跑通之后，你可以往两个方向走。一个是把 SKILL 做厚，每个技能写清楚SKILL.md的输入输出契约，让 agent 判断更准。另一个是把模型通道固定下来，长期编码或 Agent 任务用 Coding Plan，省去反复换 Key 的麻烦。

回到最开始那个问题：deep agent 加载 SKILL 失败，本质不是代码写错，而是链路里某个环节静默断了。把 settings.json 骨架、backend、目录命名、系统提示这四件事对齐，一次配置就能跑通。我试过把这套骨架直接复制到新项目，改一下skills_dir和模型名就能用，省掉了反复试错的时间。

如果你还没拿到 Key，先去控制台创建一个，再回来对着骨架填。跑通之后，把agent.skills的输出截图存下来，下次换环境时对比一下，能快速判断是配置问题还是环境问题。