这篇把完整流程记下来。只想换现成主题的话，前半部分几分钟就能完成；想自己做动态主题，再往后看 FFmpeg 那一段。

一、安装 DreamSkin

DreamSkin 是一款第三方 Codex 桌面端主题工具。它通过本地 CDP 注入主题，不需要修改 Codex 官方应用包。

先打开 DreamSkin 官网，或者直接进入 下载页面 下载安装包。

在 macOS 上安装时，建议先把 Codex（旧版本界面里可能显示为 ChatGPT）彻底退出。不是只关窗口，而是在菜单栏或程序坞中选择“退出”。否则旧进程还在运行，主题引擎可能无法正确安装或加载。

安装步骤很普通：

1. 下载并打开 DMG。
2. 将 DreamSkin 拖入“应用程序”。
3. 启动 DreamSkin，按提示授予必要权限。

二、安装或升级主题引擎

第一次启动后，打开 Mac 顶部菜单栏里的 DreamSkin 图标，依次选择：

维护 → 修复 / 重新安装引擎…

这一步会把当前版本的主题引擎装好。以后 Codex 更新后，如果主题突然失效，也可以先回到这里重新安装引擎，再重新应用一次皮肤。

三、一键应用主题

接着进入 DreamSkin 官方主题库。我做的这款主题已经发布，可以直接打开：

查看并安装这款 Codex 主题

在主题详情页点击“一键换肤”，然后回到 DreamSkin 应用皮肤即可。

如果页面按钮没有拉起 DreamSkin，先确认应用已经启动，再试一次。主题装好后通常不需要重启 Mac，重新应用皮肤或重开 Codex 就够了。

四、动态主题为什么要先转成 WebP

我后来又做了一版动态背景，源文件是一段 MP4。这里不能直接把视频改名成 background.webp，因为两种文件的内容格式完全不同。

DreamSkin 当前的主题包只识别 background.png、background.jpg 和 background.webp。引擎读取图片后，将它变成 Blob URL，再作为 CSS 背景交给 Codex 界面显示。MP4 是视频容器，现有链路里没有负责创建 <video>、自动播放和循环控制的代码。

动态 WebP 正好卡在中间：对引擎来说它仍然是一张图片，对用户来说它又能播放多帧动画。因此目前最省事的办法，就是用 FFmpeg 把 MP4 抽帧、缩放，再编码成动态 WebP。

五、我实际使用的 FFmpeg 命令

先安装 FFmpeg：

1

brew install ffmpeg

然后执行下面这条命令。把输入和输出路径换成自己的即可：

1
2
3
4
5
6
7
8
9
10

ffmpeg -y \
  -i "/path/input.mp4" \
  -an \
  -vf "fps=15,scale=1920:1080:force_original_aspect_ratio=increase:flags=lanczos,crop=1920:1080,setpts=PTS-STARTPTS" \
  -c:v libwebp_anim \
  -lossless 0 \
  -compression_level 4 \
  -q:v 92 \
  -loop 0 \
  "/path/background.webp"

这组参数的意思并不复杂：

• -an：去掉音频，桌面背景用不到声音。
• fps=15：每秒保留 15 帧。对壁纸来说通常够用，也能明显减小体积。
• scale 加 crop：先等比放大，再裁成 1920×1080，不拉伸画面。
• flags=lanczos：缩放时尽量保留细节。
• -q:v 92：有损 WebP 的画质参数，数字越高越清楚，文件也越大。
• -loop 0：无限循环播放。

我这次做出来的文件是 1920×1080、15 FPS、76 帧、质量 92，最终 8.66 MB，已经能在 Codex 里正常循环。

六、为什么必须小于 10 MiB

这个限制不是经验值，而是 DreamSkin 当前源码里的硬校验：背景图片最大允许 10 × 1024 × 1024 字节，也就是 10,485,760 字节。

超过这个大小，主题在导入或校验时就会被拒绝。所以不要盯着源视频是 40 MB、80 MB 还是 4K。最终文件大小主要由下面几项决定：

• 视频时长；
• 画面运动和细节多少；
• 输出分辨率；
• 帧率；
• WebP 质量。

同样是 4K 视频，5 秒的慢镜头和 30 秒的快速运动，压出来可能差很多。

如果生成结果超过 10 MiB，我一般按这个顺序调整：先把 q92 降到 q90 或 q88，再把 fps=15 降到 fps=12，最后才把 1920×1080 降到 1600×900。先降分辨率最伤观感，不建议一上来就做。

可以用下面这张表快速选参数：

这只是起点，不是万能公式。画面越复杂，越需要继续降低质量或帧率。

七、别忘了检查它是不是真的会动

有些 FFmpeg 构建虽然带有 libwebp_anim，实际输出却可能只有一帧。文件扩展名还是 WebP，但放进主题后只会显示静态画面。

安装 WebP 工具并检查帧数：

1
2

brew install webp
webpmux -info "/path/background.webp"

输出里的 Number of frames 必须大于 1。

如果只有一帧，可以改用更稳妥的两步法：先用 FFmpeg 导出序列帧，再交给 img2webp 合成。

1
2
3
4
5
6
7
8
9
10
11
12

mkdir -p /tmp/dreamskin-frames

ffmpeg -y \
  -i "/path/input.mp4" \
  -an \
  -vf "fps=15,scale=1920:1080:force_original_aspect_ratio=increase:flags=lanczos,crop=1920:1080" \
  "/tmp/dreamskin-frames/frame-%04d.png"

img2webp \
  -lossy -q 92 -d 67 -loop 0 \
  /tmp/dreamskin-frames/frame-*.png \
  -o "/path/background.webp"

-d 67 表示每帧大约停留 67 毫秒，对应约 15 FPS。生成后再跑一次 webpmux -info，确认帧数和文件大小。

最后，把生成的文件命名为 background.webp，覆盖主题目录中的同名文件，再从 DreamSkin 菜单选择“重新应用皮肤”。只要主题结构没变，后续换视频都可以沿用这套流程。

八、后面准备怎么改

WebP 方案能用，但画质、体积和帧率必须互相让步。尤其是 2K、4K 视频，为了塞进 10 MiB，损失会比较明显。

后续更合理的方向是直接改 DreamSkin 引擎：

1. 在主题包校验中允许 MP4、WebM 等视频资源；
2. 注入一个静音、循环、自动播放的 <video> 背景层；
3. 处理窗口切换、主题卸载和资源释放；
4. 再根据实际内存占用，决定是否放宽 10 MiB 限制。

只把 10 MiB 改大并不能解决 MP4 播放，因为“文件能通过校验”和“渲染器会播放视频”是两件事。原生视频支持的改动会比改一个数字大一些，但能绕开动态 WebP 的体积困境，画质和编码效率也会好得多。

现阶段如果只是想快速换一段动态背景，还是建议先用 5～8 秒的短视频、1080p、12～15 FPS。这个区间最容易把体积控制住，实际桌面观感也比较稳。

参考链接

• DreamSkin 官网
• DreamSkin 下载
• 本文使用的主题
• DreamSkin 开源仓库

下载 scrcpy-macos-aarch64-v4.1.tar.gz

它不是 .dmg 安装器，而是官方便携版压缩包。操作方法：

1. 下载并双击解压。
2. 打开“终端”，进入解压目录，例如：

1

cd ~/Downloads/scrcpy-macos-aarch64-v4.1

3. 连接安卓手机并打开 USB 调试，然后运行：

1

./scrcpy --video-bit-rate=16M --max-size=1920 --max-fps=60 --stay-awake

如果提示无法执行：

1
2

chmod +x scrcpy
./scrcpy

如果 macOS 阻止打开，到“系统设置 → 隐私与安全性”里允许，或者在 Finder 中右键 scrcpy，选择“打开”。

如果提示找不到 adb，再下载官方 Android Platform Tools：

下载 platform-tools for Mac

解压后执行：

1
2

cd ~/Downloads/platform-tools
./adb devices

看到手机后，用下面方式启动 scrcpy：

1
2
3
4
5
6

cd ~/Downloads/scrcpy-macos-aarch64-v4.1
PATH="$HOME/Downloads/platform-tools:$PATH" ./scrcpy \
  --video-bit-rate=16M \
  --max-size=1920 \
  --max-fps=60 \
  --stay-awake

如果想去掉上面点白边，ctrl+c结束后在执行

1
2
3
4
5
6

./scrcpy \
  --window-borderless \
  --video-bit-rate=16M \
  --max-size=1920 \
  --max-fps=60 \
  --stay-awake

如果想占满Mac整个屏幕，ctrl+c结束后在执行

1
2
3
4
5
6
7

./scrcpy \
  --window-borderless \
  --always-on-top \
  --video-bit-rate=16M \
  --max-size=1920 \
  --max-fps=60 \
  --stay-awake

你的直播链路直接这样即可：

1

安卓手机 USB → scrcpy → Mac 抖音直播伴侣窗口采集

如果只是 Homebrew 下载超时，直接下载官方压缩包通常更适合你当前情况。

我真正想省掉的，不是写作，而是写完之后那一串重复劳动。 维护一份 Markdown，就能得到一篇博客和一篇排好版的公众号草稿；某一步失败，也不必从头再来。

每次写完文章，我都要重复同一套动作：找封面、处理正文图、上传图床、检查博客，再去公众号后台重新排一遍。

写作只做了一次，搬运却像又写了一次。

于是我把这些步骤串成了一条个人内容工作流。它不替我按下最终发布按钮，但会把成品送到按钮前，并告诉我哪里通过了、哪里应该停。

一句话看懂：一份内容作为事实源，博客和公众号分别输出，失败从断点继续。

先看结果：我最终拿到什么

不是一堆中间文件，而是三个可以继续使用的结果。

博客成品：标题、摘要、封面、正文图片、来源和分类都完整，Hexo 构建通过后才进入发布流程。

公众号成品：不是裸 Markdown，而是适合手机阅读的内联样式 HTML；正文图和封面也会进入公众号素材流程。

恢复记录：文章、图片和草稿状态被保存下来。网络或接口出错时，下次只重试没完成的部分。

这张图就是整套流程：同一份原稿，走向两个发布端；每个关键步骤前都有检查点。

三个 Skill，不是三个“万能引擎”

我一开始也把它们讲复杂了。其实三个工具的关系非常简单：一个管全局，一个管排版，一个管送达。

总控｜wechat-article-generator

它像项目经理加质检员：理解选题、组织文章、规划图片、调用图床、生成 Hexo 文件，并判断下一步该调用谁。它关心的是整件事有没有闭环。

排版｜md2wechat

它把 Markdown 转成公众号兼容的 HTML，并负责主题、预览、封面和信息图等排版能力。文章已经写好、只想解决公众号排版的人，用这一段就够了。

送达｜baoyu-post-to-wechat

它处理正文图片、封面素材、账号配置和草稿创建。它只负责把成品安全送进编辑后台，默认不会替我发布或群发。

所以，真正的关系不是“三个 AI 一起写文章”，而是：

总控决定顺序，md2wechat 负责变好看，baoyu 负责放进草稿箱。

稳定，不等于“一键无脑跑完”

这套工作流真正有用的地方，是把容易忘、容易错的动作变成固定顺序。

先写清楚。 总控先确认读者、核心结论和信息来源。涉及新闻、项目数据和产品能力时，必须保留来源，不能猜数字。

再让图片解释内容。 封面负责让读者一眼看懂主题，正文图负责解释流程、架构或故障恢复，不拿无关“科技图”凑数。

图片先进入 OSS。 博客只引用真实线上地址。上传失败时，流程停止，不偷偷改成本地路径，也不拿默认图顶上去。

两个渠道分别渲染。 博客保留 Markdown，交给 Hexo；公众号生成全内联样式 HTML，避免进入编辑器后样式丢失。

最后才检查交付。 封面、正文图、移动端字号、HTML 兼容性和博客构建全部通过，才算完成。

自动化不是“什么都继续做”，而是该继续时继续，该停时明确停下。

图片不是装饰，它要先回答问题

我对封面的要求只有一个：用户只看这张图，也能知道文章在讲什么。

因此，系统先从标题、摘要和正文里提炼一个主题与两到四个要点，再决定画面结构。图片模型只负责无文字底图或视觉框架，准确中文最后由可控排版叠加。

主标题和关键信息保留 6% 到 8% 的安全边距，缩成手机封面后仍要看得清。

如果生成服务不可用，才会选择同主题、来源明确的真实素材。技术文章只看技术类候选，不会从动漫、风景和人物图里随机抽一张。

这不是“有图就行”，而是四道检查：主题相关、文字正确、画幅适配、来源可追溯。

真正遇到故障时，会发生什么

我把故障分成三种，不同故障有不同处理方式。

能替代：封面生成服务不可用，可以换成同主题的真实素材，但必须重新检查构图和授权。

能续跑：出口 IP 不在白名单，博客和微信 HTML 可以保留；网络恢复后，只重试草稿上传。

必须停：图片没上传到 OSS、文章检查没通过、草稿条件不满足。此时不能伪造 URL，也不能为了“看起来完成了”而静默降级。

state.json 记录文章哈希、素材和草稿结果。它不会让错误自动消失，但会让下一次清楚知道：哪些已经完成，哪些还没做。

9 月 13 日那次失败，反而说明它有用

那期 GitHub 周报第一次运行时，博客已经构建并推送成功，公众号却没有出现草稿。

问题不在文章，而在代理改变了出口 IP，公众号令牌接口返回 40164，当前地址不在白名单。

流程没有假装成功。文章、微信 HTML、封面和已上传图片都被保留下来。

关闭代理后，我只重试了草稿阶段：重新检查令牌，上传正文图与封面，创建草稿，再核对标题、正文和阅读原文链接。

没有重新研究，没有重新写稿，也没有再生成一篇博客。

这比“全自动”更重要：失败时知道停在哪里，恢复时知道从哪里接着走。

你不必复刻整套系统

只做公众号排版，就拿走 md2wechat：Markdown 写完后，用它生成适合公众号的 HTML 和预览。

已经有排好版的 Markdown 或 HTML，只差进入草稿箱，就用 baoyu-post-to-wechat。

同时维护 Hexo、Hugo 等博客和公众号，再借鉴总控思路：保留一份主稿，为两个渠道分别输出，并给图片、排版和构建设置硬检查。

如果只想改善封面，也只需要拿走一条原则：先让图片说清文章主题，再谈风格好不好看。

文末工具箱

• wechat-article-generator：我的总控 Skill
• md2wechat：Markdown 转公众号 HTML、预览与视觉生成
• baoyu-post-to-wechat：公众号草稿上传与多通道发布
• PicGo：图片上传与图床客户端
• Hexo：静态博客生成器

我最后留下的不是一个所有人都要照搬的方案，而是三个可以复用的原则：一份内容作为事实源，工具各做自己擅长的事，任何发布都要经过可验证的质量门。

如果你也在做内容，你最想先省掉哪一步：排版、配图，还是草稿上传？

前两篇讲了 Agent 的概念和架构，这一篇我们从头写一个能读文件、写代码、执行 Shell 的代码助手 Agent。跟着一步步来，大约 20 分钟能跑通。

环境准备

先装依赖。打开终端，一行搞定：

1

pip install "langchain<1.0" langchain-openai

⚠️ 版本说明： LangChain 1.0+ 移除了 create_tool_calling_agent 和 AgentExecutor（改用 LangGraph 的 create_agent()）。本文基于 0.3.x 版本，langchain<1.0 确保代码可直接运行。学习完成后建议查阅 LangGraph Agent 文档 了解最新用法。

然后创建 agent_demo.py，把 API key 配好：

1
2

import os
os.environ["OPENAI_API_KEY"] = "sk-your-key-here"  # 或从 .env 读取

如果你用的是其他模型（比如 DeepSeek、Claude），在创建 LLM 时指定 base_url 即可，后面会讲到。现在先把环境搭好。

定义三个工具

第二篇讲过，工具（BaseTool）是 Agent 的”手和眼睛”。LangChain 提供了一种极其简洁的方式来定义工具——@tool 装饰器。你只需要写一个普通函数，加上类型注解和 docstring，装饰器会自动把它包装成 BaseTool。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

from langchain_core.tools import tool

@tool
def read_file(path: str) -> str:
    """读取指定路径的文件内容。参数 path: 文件的绝对或相对路径"""
    with open(path, "r", encoding="utf-8") as f:
        return f.read()

@tool
def write_file(path: str, content: str) -> str:
    """写入内容到指定路径的文件。参数 path: 目标文件路径, content: 要写入的内容"""
    with open(path, "w", encoding="utf-8") as f:
        f.write(content)
    return f"已写入 {path}"

@tool
def run_shell(command: str) -> str:
    """执行 shell 命令并返回输出。参数 command: 要执行的 shell 命令。⚠️ 仅用于本地开发环境"""
    import subprocess
    result = subprocess.run(command, shell=True, capture_output=True, text=True)
    return result.stdout or result.stderr

tools = [read_file, write_file, run_shell]

⚠️ 安全提醒： run_shell 中使用了 shell=True，这意味着任何能调用此工具的人都可以在你的机器上执行任意命令。本文的代码仅用于本地开发学习，绝对不能部署到生产环境或暴露给不信任的用户。生产环境应使用沙箱（如 Docker 容器）或在 Agent prompt 中限制可执行的命令范围。

就这三段代码，Agent 就有了读文件、写文件、执行命令的能力。来拆一下每行在干什么。

@tool 装饰器做了什么

回忆第二篇讲的 BaseTool 四个核心属性：name、description、args_schema、_run()。@tool 装饰器做的事情就是把这四个属性从你的函数里自动提取出来：

• name：取函数名。read_file 函数 → 工具名就是 "read_file"
• description：取 docstring。LLM 读这个描述来决定”什么时候该用这个工具”
• args_schema：根据类型注解自动生成 Pydantic model。path: str → 参数定义为一个 str 类型的字段。有了这个 schema，LLM 才知道调用 read_file 需要传一个叫 path 的字符串参数
• _run()：就是你的函数体本身

run_shell 的 docstring 里加了一个 ⚠️ 仅用于本地开发环境 的安全提示。这不是给开发者看的注释，而是给 LLM 看的——Agent 在决策时会读到这段描述，相当于在 prompt 里内置了一条安全提醒。

最后，tools = [read_file, write_file, run_shell] 把三个工具装进列表。这就是后面要传给 Agent 的工具清单。

创建 Agent

有了工具，接下来创建 Agent 本身。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = ChatOpenAI(model="gpt-4o", temperature=0)

system_prompt = (
    "你是一个 Python 代码助手。你可以读取文件、写入文件、执行 Shell 命令。"
    "遇到需要操作文件或执行命令的任务时，使用提供的工具。"
    "如果执行命令出错，分析错误并尝试修复。"
    "完成任务后给出清晰的总结。"
)

prompt = ChatPromptTemplate.from_messages([
    ("system", system_prompt),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

不到 10 行，Agent 就创建好了。下面逐行解释。

为什么用 create_tool_calling_agent

第二篇我们对比过 Agent 的几种类型——ReAct、Tool Calling、OpenAI Tools、JSON/XML Agent。这里选 Tool Calling，因为 gpt-4o 原生支持 function calling，LLM 会直接返回结构化的 tool_calls 对象，不靠文本解析。比 ReAct 更可靠，比 OpenAI Tools 更通用。

create_tool_calling_agent 内部做的事情就是把 Prompt 模板、工具列表、LLM 和 OutputParser 串成一条完整的 Agent 管道——Agent 本身就是一个 Runnable。我们手动构建了 ChatPromptTemplate，其中 MessagesPlaceholder("agent_scratchpad") 是 Think→Act→Observe 循环中的”历史记录”插槽，每次迭代自动填充最新步骤。你不需要处理 tool_calls 解析，LangChain 都帮你了。

system_prompt 的作用

这四句话是 Agent 的”任务说明书”：

1. 定义角色：”你是一个 Python 代码助手”——告诉 LLM 它的身份
2. 告知工具：”你可以读取文件、写入文件、执行 Shell 命令”——让 LLM 知道它有什么能力
3. 错误处理指令：”如果执行命令出错，分析错误并尝试修复”——激活 Agent 的自我纠错机制
4. 输出要求：”完成任务后给出清晰的总结”——明确交付标准

AgentExecutor——Think → Act → Observe 的引擎

AgentExecutor 不参与推理，不执行工具。它是总调度器，职责就是跑循环：

1. 把 prompt 发给 LLM（Think）
2. 拿到输出，如果是 AgentAction，找到对应的工具执行（Act）
3. 把工具返回的结果作为 Observation 填回历史（Observe）
4. 判断：继续循环还是停止
5. 直到 LLM 输出 AgentFinish，返回最终答案

verbose=True 让每一步都打印出来——你会亲眼看到 Think → Act → Observe 的完整过程。这正是第二篇讲的 Callbacks 机制：on_agent_action、on_tool_start、on_tool_end 等钩子在每一步触发，把日志打印到控制台。

一点说明：AgentExecutor 在 LangChain v1 中已进入维护模式，官方推荐的新方案是基于 LangGraph 的 create_agent()。但 AgentExecutor 仍然是学习 Agent 循环机制的最佳选择——它把这个循环暴露得清清楚楚，每个步骤都能看到。理解了它，切到新 API 只是换个函数名。

跑起来——第一个示例

把上面的代码全部放到 agent_demo.py，底部加上：

1
2
3
4

result = executor.invoke({
    "input": "统计当前目录下所有 .py 文件的行数"
})
print(result["output"])

然后：

1

python agent_demo.py

你会看到类似这样的输出（这是我实际运行时 verbose=true 打印的日志，加了注释标注每个阶段）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

> Entering new AgentExecutor chain...

🧠 Think: 我需要先列出目录下的 .py 文件
🔧 Action: run_shell
📋 Action Input: {"command": "ls /Users/pengfanao/code/wwrtpfa.github.io/*.py"}

👁️ Observation: scripts/create_post.py scripts/fetch_github.py

🧠 Think: 有2个文件，现在统计每个文件的行数
🔧 Action: run_shell
📋 Action Input: {"command": "wc -l scripts/create_post.py scripts/fetch_github.py"}

👁️ Observation: 45 scripts/create_post.py, 102 scripts/fetch_github.py, 147 total

🧠 Think: 信息够了
✅ Final Answer: 当前目录下共 2 个 .py 文件，合计 147 行代码。

> Finished chain.

整个过程经历了 2 轮 Think → Act → Observe：

1. 第一轮：Agent 思考”需要先列出文件” → 执行 ls *.py → 拿到文件名列表
2. 第二轮：Agent 看到有 2 个文件，决定统计行数 → 执行 wc -l → 拿到统计结果
3. 信息足够，Agent 输出最终答案

注意 Agent 不是一次性想好所有步骤的——它每一步都观察上一步的结果，再决定下一步做什么。这和你在终端里手动操作没有区别：先 ls 看看有什么，再 wc -l 统计，最后汇总。

观察 Agent 自主纠错

前面的例子太顺利了。来看看 Agent 遇到错误时怎么办——这是它和普通 LLM 最根本的区别。

1
2
3
4

result = executor.invoke({
    "input": "写一个 Python 脚本 hello.py，打印'Hello World from Agent!'，然后执行它。"
})
print(result["output"])

Agent 的执行过程大概是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

> Entering new AgentExecutor chain...

🧠 Think: 用户要创建一个 Python 脚本并执行。我先写文件，再运行。
🔧 Action: write_file
📋 Action Input: {"path": "hello.py", "content": "print('Hello World from Agent!')"}

👁️ Observation: 已写入 hello.py

🧠 Think: 文件已创建。现在用 python 命令执行它。
🔧 Action: run_shell
📋 Action Input: {"command": "python hello.py"}

👁️ Observation: Hello World from Agent!

🧠 Think: 脚本成功创建并执行完毕。
✅ Final Answer: 任务完成。已创建 hello.py，内容为打印 'Hello World from Agent!'，并成功执行，输出无误。

> Finished chain.

三步完成：写文件 → 执行 → 确认结果。如果执行出错（比如脚本里有语法错误），Agent 的行为会是这样的：

1
2
3
4
5
6
7
8
9
10
11

👁️ Observation: SyntaxError: invalid syntax at line 3

🧠 Think: 脚本报语法错误了。让我读一下文件内容，找出问题。
🔧 Action: read_file
📋 Action Input: {"path": "hello.py"}

👁️ Observation: print('Hello World from Agent!'

🧠 Think: 发现少了一个右括号。修正后重新写入。
🔧 Action: write_file
📋 Action Input: {"path": "hello.py", "content": "print('Hello World from Agent!')"}

Agent 自己发现了错误 → 自己排查了原因 → 自己修复了 → 继续执行。整个过程不需要你插手。

这就是第二篇讲的反馈环的力量。普通 LLM 遇到同样的情况，只能输出一段代码然后说”你试试看能不能跑”——至于跑不跑得通，它不知道，也不关心。

普通 LLM 只是告诉你”怎么做”，Agent 是帮你”做出来并验证它真的能跑”。

总结：代码与架构的对应关系

写了这么多代码，现在我们把它映射回第二篇的架构概念。每一行代码，背后都有一个 LangChain 抽象在支撑：

三篇回顾

到这个系列结束的时刻了。回顾一下我们走过的路：

第一篇——概念篇：Agent 是什么。LLM 有大脑没身体，Agent = LLM + 工具 + 决策循环，核心是 Think → Act → Observe 的 ReAct 循环。

第二篇——架构篇：LangChain 内部怎么转。三层包结构（core / classic / v1），五大核心组件（Runnable、BaseTool、Prompt 模板、AgentAction/AgentFinish、Callbacks），Agent 类型怎么选。

第三篇——实战篇：从零搭建代码助手 Agent。三个 @tool 装饰器定义工具，create_tool_calling_agent 创建 Agent，AgentExecutor 驱动循环——不到 50 行代码，Agent 真的跑起来了，能读写文件、执行命令、自主纠错。

从概念到代码，从理解到上手——希望你读完这个系列后，不会再觉得 Agent 是什么神秘的黑魔法。它就是一套设计精巧的循环机制，而你现在已经知道怎么造一个出来了。

LangChain Agent 系列文章：

• (一) Agent 是什么？
• (二) LangChain Agent 内部怎么转的？
• (三) 从零搭建代码助手 Agent（本文）

Claude Code、Codex 明明已经停下来了，Mac 风扇却还在转，内存也迟迟不降。问题可能不在当前会话，而在一批没有正常收尾的 agent-browser daemon 与自动化 Chrome。

这次我在本机清理了 8 组遗留的 agent-browser / Chrome 后台实例及其子进程。普通 Chrome 标签页没有动，机器热量很快就降了下来。

这不是一个玄学问题，也不能简单归咎于“Chrome 太吃内存”。真正要理解的是：AI 编程工具、浏览器自动化工具、CDP、daemon 和 session 之间，到底是谁启动了谁，又该由谁负责关掉。

30 秒结论

先给赶时间的人答案：

• agent-browser 采用 CLI + 后台 daemon + Chrome 的架构，daemon 会故意跨命令常驻，以便下一条指令不用重新启动浏览器。
• 每个独立 session 都可能拥有自己的浏览器实例。Claude Code、Codex 并发执行多个 agent 或工具任务时，session 数量很容易叠加。
• 如果任务异常中断、会话被强制停止，或者调用方忘了执行 agent-browser close，后台进程就可能继续存在。
• CDP 只是控制通道，不是泄漏的根因。根因是 浏览器生命周期没有闭环。
• 最优先执行官方收尾命令：agent-browser close --all。只有正常关闭失败，才按特征匹配并发送 TERM，最后才考虑 KILL。
• 长期方案是设置空闲超时、复用 session，并要求每个自动化任务在 finally 或 shell trap 中关闭自己的 session。

目录

• 一、现象：AI 停了，浏览器却没停
• 二、根因：常驻 daemon 遇上并发 session
• 三、先确认，不要上来就 kill
• 四、三层清理：官方关闭、温和终止、强制清理
• 五、怎样保证不误伤普通 Chrome
• 六、从源头预防：让生命周期闭环
• 七、可直接收藏的排查清单

一、现象：AI 停了，浏览器却没停

典型场景是这样的：

• 你让 Claude Code 或 Codex 通过 skill、MCP、shell 工具打开网页；
• 自动化任务创建了多个命名 session，甚至并行跑了多个子 agent；
• 任务完成或会话终止后，终端已经安静；
• 但“活动监视器”里仍有多组 Chrome、Chrome Helper、GPU、Renderer 或 agent-browser 进程；
• 合上几次窗口也没用，Mac 继续发热，内存和 CPU 占用居高不下。

最迷惑的一点是：这些进程通常没有可见窗口。你看到的普通 Chrome 标签页可能只有几个，但后台自动化 Chrome 使用的是独立临时用户目录，它们和日常浏览器不是同一组实例。

因此，“我已经关掉 Chrome 窗口了”并不能证明自动化浏览器已经退出。

二、根因：常驻 daemon 遇上并发 session

以本机安装的 agent-browser 0.27.0 为例，官方说明明确写了两件事：

• 它采用 client-daemon 架构，Rust CLI 负责接收命令，Rust daemon 通过 CDP 控制 Chrome；
• daemon 会在第一次命令时自动启动，并在后续命令之间保持运行，以换取更快的响应。

与此同时，官方 session 文档也说明：每个 session 都有独立的浏览器实例、Cookie、存储、历史记录和认证状态。

这两点放到多 agent 场景里，就形成了下面的链路：

1
2
3
4
5
6
7
8

Claude Code / Codex
        │

        ├─ Agent A → session A → daemon A → Chrome A → Renderer / GPU / Network

        ├─ Agent B → session B → daemon B → Chrome B → Renderer / GPU / Network

        └─ Agent C → session C → daemon C → Chrome C → Renderer / GPU / Network

单看一组并不可怕。真正吃资源的是“多组浏览器进程树一起常驻”。一个 Chrome 主进程还会派生渲染、GPU、网络等子进程，所以 8 个遗留实例在活动监视器里看起来可能远不止 8 行。

CDP 是不是罪魁祸首？

不是。

CDP（Chrome DevTools Protocol）只是自动化工具与 Chrome 之间的控制协议。它负责导航、点击、读取 DOM、截图等操作，但不会替调用方决定“任务什么时候算结束”。

真正缺失的是这条生命周期：

1

创建 session → 使用浏览器 → 任务成功或失败 → 关闭 session → 回收 daemon 和 Chrome

如果最后两步没有执行，前面的资源就可能继续留在后台。

关键判断： 不是 AI “还在思考”，而是 AI 启动的外部进程已经脱离了当前对话的可见范围。

三、先确认，不要上来就 kill

清理前先分清三件事：有多少活动 session、有哪些 agent-browser daemon、哪些 Chrome 使用了 agent-browser 的临时用户目录。

1. 查看 agent-browser 自己记录的活动 session

1

agent-browser session list

如果版本支持 JSON：

1

agent-browser session list --json

这一步最可信，因为它从工具自己的会话视角回答“现在认为谁还活着”。

2. 查看 daemon 和自动化 Chrome

macOS 上可以使用：

1
2
3

pgrep -fl '/agent-browser/bin/agent-browser-darwin-(arm64|x64)( |$)'

pgrep -fl '[G]oogle Chrome.*--user-data-dir=[^ ]*/agent-browser-chrome-'

第二条命令的关键不是进程名“Google Chrome”，而是启动参数中的：

1

--user-data-dir=.../agent-browser-chrome-...

它说明这个 Chrome 使用的是 agent-browser 创建的隔离用户目录，而不是你日常使用的默认 Chrome Profile。

3. 按 CPU、内存和运行时间查看完整进程树

1
2

ps -axo pid,ppid,%cpu,%mem,rss,etime,command \
  | grep -E '[a]gent-browser-darwin|[a]gent-browser-chrome-'

字段含义：

• PID：当前进程编号，后续终止时使用。
• PPID：父进程编号，用来判断 daemon 与 Chrome 的父子关系。
• %CPU：CPU 占用，观察它是否持续让机器发热。
• %MEM / RSS：内存占用，确认多个实例是否不断叠加。
• ETIME：已运行时间，判断它是否早已超过当前 AI 任务时长。
• COMMAND：完整启动命令，确认是否带有 agent-browser 特征参数。

不要只看 ~/.agent-browser 下有没有 .pid、.sock 文件。它们可能只是过期的 sidecar 文件，并不等于进程仍然存活。进程是否活着，最终以 session list、ps 和 pgrep 为准。

四、三层清理：官方关闭、温和终止、强制清理

第一层：让 agent-browser 自己收尾

优先执行：

1

agent-browser close --all

然后清理过期的 pid、socket、version 等 sidecar 文件：

1

agent-browser doctor --offline --quick

当前版本的 doctor 会自动清理陈旧的 daemon sidecar 文件；--fix 还可能执行重装 Chrome、清理旧状态等破坏性修复，因此日常排查先不要加 --fix。

再次验证：

1
2
3
4
5

agent-browser session list

pgrep -fl '/agent-browser/bin/agent-browser-darwin-(arm64|x64)( |$)'

pgrep -fl '[G]oogle Chrome.*--user-data-dir=[^ ]*/agent-browser-chrome-'

如果没有输出，说明已经清干净。

第二层：发送 TERM，让进程有机会优雅退出

只有官方关闭失败时再执行：

1
2
3
4
5

pgrep -f '/agent-browser/bin/agent-browser-darwin-(arm64|x64)( |$)' \
  | xargs -n 1 kill -TERM 2>/dev/null || true

pgrep -f '[G]oogle Chrome.*--user-data-dir=[^ ]*/agent-browser-chrome-' \
  | xargs -n 1 kill -TERM 2>/dev/null || true

TERM 会给进程处理退出、关闭文件和回收子进程的机会。执行后等 3 秒，再跑一次检查命令。

第三层：只对仍残留的目标使用 KILL

1
2
3
4
5

pgrep -f '/agent-browser/bin/agent-browser-darwin-(arm64|x64)( |$)' \
  | xargs -n 1 kill -KILL 2>/dev/null || true

pgrep -f '[G]oogle Chrome.*--user-data-dir=[^ ]*/agent-browser-chrome-' \
  | xargs -n 1 kill -KILL 2>/dev/null || true

KILL 不允许进程执行清理逻辑，只适合处理已经卡死、无法响应 TERM 的残留。正在进行的自动化、下载、表单填写和未保存状态都会立即丢失。

仓库里放一个可重复使用的脚本

本文配套脚本已放在：

1

scripts_py/agent_browser_cleanup.sh

使用方式：

1
2
3

./scripts_py/agent_browser_cleanup.sh status
./scripts_py/agent_browser_cleanup.sh close
./scripts_py/agent_browser_cleanup.sh force

三条命令依次对应：只查看、官方关闭并清理 sidecar、官方关闭失败后的分级强制清理。

五、怎样保证不误伤普通 Chrome

不要使用下面这种“大锤”：

1
2

killall 'Google Chrome'
pkill -f 'Google Chrome'

它们会把普通 Chrome 窗口和日常标签页一起关掉。

本文脚本采用两层限制：

1. daemon 必须匹配 agent-browser-darwin-arm64 或 agent-browser-darwin-x64 的安装路径；
2. Chrome 必须带有 --user-data-dir=.../agent-browser-chrome-... 参数。

也就是说，它针对的是 agent-browser 创建的隔离 Chrome，不是所有名为 Google Chrome 的进程。

不过还有一个例外需要注意：如果你主动使用 --cdp 或 --auto-connect 连接了日常 Chrome，那么自动化 session 与普通浏览器之间的边界会变得更近。此时先用 session list 和完整命令行确认，不要直接执行强制清理。

六、从源头预防：让生命周期闭环

清理脚本只是灭火器。更好的办法是让每个任务都负责关掉自己打开的浏览器。

1. 设置 daemon 空闲自动退出

官方提供了 AGENT_BROWSER_IDLE_TIMEOUT_MS。例如 10 分钟无命令后自动关闭浏览器并退出 daemon：

1

export AGENT_BROWSER_IDLE_TIMEOUT_MS=600000

长期使用可以写入 ~/.zshrc：

1
2

echo 'export AGENT_BROWSER_IDLE_TIMEOUT_MS=600000' >> ~/.zshrc
source ~/.zshrc

10 分钟只是一个稳妥起点。频繁执行长任务可以设为 30 分钟；偶尔使用、机器资源紧张时可以设为 3 到 5 分钟。

2. 不要为每一步创建新 session

同一个任务尽量复用一个语义明确的 session：

1
2
3

agent-browser --session blog-research open https://example.com
agent-browser --session blog-research snapshot -i
agent-browser --session blog-research close

并发任务确实需要隔离时，可以创建多个 session，但每个任务结束后都要单独关闭。

3. 在 shell 脚本里用 trap 兜底

1
2
3
4
5
6
7
8
9
10
11
12

set -euo pipefail

SESSION="research-$$"

cleanup() {
  agent-browser --session "$SESSION" close >/dev/null 2>&1 || true
}

trap cleanup EXIT INT TERM

agent-browser --session "$SESSION" open https://example.com
agent-browser --session "$SESSION" snapshot -i

无论脚本正常结束、报错，还是收到中断信号，cleanup 都会尝试关闭对应 session。

4. 给 Claude Code / Codex 的浏览器 skill 加退出规则

长期指令里应明确写上：

1
2
3
4
5

浏览器自动化任务结束后，必须关闭本任务创建的 agent-browser session。

成功、失败、取消和超时都要执行清理；不得依赖用户手动回收后台进程。

并发任务必须记录各自的 session 名称，只关闭自己创建的 session。

这比“任务结束后记得关浏览器”更有效，因为它定义了成功、失败和取消三条路径。

5. 定期做轻量检查

如果你经常让多个 agent 并发操作网页，可以在结束工作前运行：

1
2

agent-browser session list
./scripts_py/agent_browser_cleanup.sh status

发现不认识、运行时间异常长的 session，再决定是否关闭。不要把 force 放进高频定时任务，因为它可能打断仍在工作的自动化。

七、可直接收藏的排查清单

遇到 Mac 突然发热、内存异常时，按这个顺序走：

• 打开“活动监视器”，确认是否有多组无窗口的 Chrome / agent-browser。
• 运行 agent-browser session list，确认活动 session。
• 用 pgrep -fl 或 ps 检查 daemon 与 agent-browser-chrome- 用户目录。
• 先执行 agent-browser close --all。
• 再执行 agent-browser doctor --offline --quick 清理陈旧 sidecar。
• 等待几秒并复查 CPU、内存和进程。
• 仍有残留时先 TERM，最后才 KILL。
• 设置 AGENT_BROWSER_IDLE_TIMEOUT_MS。
• 在每个自动化脚本或 skill 中加入 finally / trap 清理。
• 避免 killall Google Chrome 这类会误伤普通标签页的命令。

最后

浏览器自动化最容易被忽略的，不是“怎么打开网页”，而是“谁负责关闭网页背后的整棵进程树”。

Claude Code 和 Codex 能把网页操作拆成工具调用，却不会天然替所有第三方工具完成生命周期管理。只要调用链中存在 daemon、session 和独立 Chrome，就应该把清理当成任务的一部分，而不是任务结束后的家务。

真正可靠的自动化，不只要能启动，还要能在成功、失败和取消时都干净退出。

如果你的 Mac 也曾在 AI 会话结束后莫名发热，先别急着重启。跑一下本文的检查命令，很可能几分钟就能找到那批“已经下班，但进程还没打卡”的浏览器。

参考资料

• agent-browser 官方仓库
• agent-browser README：命令、Session 与 Architecture
• Chrome for Testing 官方介绍
• Chrome DevTools：远程调试

如果你读完了第一篇，你已经知道 Agent 的核心思想了：LLM 是大脑，工具是手和眼睛，决策循环让 Agent 不断思考、执行、观察、调整，直到任务完成。

但概念是概念，代码是代码。LangChain 到底用了哪些类、哪些抽象、哪些设计模式，把这些概念变成了能跑的代码？

本文拆解 LangChain 的三层包结构和 Agent 核心组件。读完你能看懂 Agent 的每一行代码在做什么。

三层包结构概览

先把 LangChain 的整体包结构看清楚。很多人一上来就对着几百个类头大，但其实 LangChain 的包结构有清晰的层次逻辑：

这三层是 LangChain 的核心架构，每一层有各自的定位：

基础抽象层（langchain-core） 是整个 LangChain 生态的地基。它只定义抽象接口和协议——Runnable 该怎么跑、BaseTool 长什么样、Message 有哪几种类型——但不绑定任何具体的模型提供商。这意味着你可以换模型、换工具实现、换拼接方式，只要接口对得上，别的代码不用动。

经典集成层（langchain-classic） 是 LangChain 历史最悠久的包，包含了 Chains 编排、100 多个第三方工具集成、各类 Agent 的具体实现、Document Loaders、Vector Stores 等等。注意，在 v1.0 发布后，langchain-classic 已进入维护模式（只修 bug，不添加新功能），活跃的集成开发已迁移到 langchain-openai、langchain-anthropic 等合作包和 langchain-community 中。但作为抽象概念的”经典层”仍然是最好的学习起点——它的代码量和覆盖面能让你看清一个完整的 Agent 生态长什么样。

新版 API（langchain v1） 是 LangChain 团队近年推行的新方向。”Agent 优先”意味着 Agent 不再是用 Chain 拼出来的”高级功能”，而是一等公民。v1 版本的 API 设计更精简——创建 Agent 更直观，配置项更集中，对工具和模型的绑定也更清晰。如果你是新项目，官方推荐优先考虑 v1。

为什么要拆三层？一句话：解耦。langchain-core 不依赖任何模型提供商，核心抽象极其稳定；langchain-classic 可以有大量的具体实现和集成，变更频繁也不影响核心抽象；langchain v1 作为”新家”，可以吸取经典层的教训，用更现代的 API 重新出发。

核心组件拆解

理清了包结构，我们来看 LangChain Agent 的核心组件。这些组件串在一起，就构成了 Agent 的执行引擎。

1. Runnable 协议——一切皆 Runnable

Runnable 是 LangChain 最底层的抽象。它的核心思想很简单：一切组件都是 Runnable，统一对外暴露 invoke()（同步执行）和 stream()（流式执行）两个执行入口。

除此之外，Runnable 还提供了 pipe() 方法（即 | 运算符），用于将多个 Runnable 串联成一个管道——这不是执行入口，而是组合手段。

在 LangChain 里，以下这些东西全都是 Runnable：

• LLM（比如 ChatOpenAI）是一个 Runnable——调用 invoke() 就发一次请求
• Prompt 模板（ChatPromptTemplate）是一个 Runnable——调用 invoke() 就填充变量生成最终 prompt
• Tool（BaseTool）是一个 Runnable——调用 invoke() 就执行工具逻辑
• Agent 本身 也是一个 Runnable——调用 invoke() 就跑完整条 ReAct 循环

这意味着你可以用 | 管道符把 Runnable 串起来，像 Unix 管道一样：

1

prompt | llm | output_parser

Agent 内部就是靠这种管道把 Prompt、LLM、OutputParser 串联起来的。你不需要在代码里手动编排每一步——LangChain 帮你把组件之间的数据流转处理好了。

2. BaseTool——工具的统一接口

第一篇我们说了”工具是 Agent 的手和眼睛”，在 LangChain 里，工具都被抽象成 BaseTool。每个 BaseTool 有四个核心属性：

• name：工具的唯一标识名。LLM 用这个名字来引用工具，比如 "read_file"。
• description：工具的功能描述。LLM 读这个描述来决策”当前应该用哪个工具”。描述写得越准确，LLM 选工具越不容易出错。
• args_schema：工具参数的 Pydantic 类型定义。有了它，LLM 就知道调用 read_file 需要传一个 file_path: str，类型不对 LangChain 会自动拦截。
• _run()：工具的实际执行逻辑。你写的业务代码就放在这里。

以 read_file 工具为例，它的结构大概是这样的：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

from langchain_core.tools import BaseTool
from pydantic import BaseModel, Field

class ReadFileInput(BaseModel):
    file_path: str = Field(description="要读取的文件路径")

class ReadFileTool(BaseTool):
    name: str = "read_file"
    description: str = "读取指定路径的文件内容"
    args_schema: type[BaseModel] = ReadFileInput

    def _run(self, file_path: str) -> str:
        with open(file_path, "r") as f:
            return f.read()

LLM 看到这个工具的 name 和 description，就知道”当用户要我读文件时，调用 read_file 工具，传一个 file_path“。args_schema 里的 Field 描述（"要读取的文件路径"）会一并发给 LLM，帮助它生成正确的参数值。

3. Prompt 模板——Agent 的”任务说明书”

Agent 的 prompt 跟普通 LLM 的 prompt 不一样。普通 prompt 就是一段话，Agent 的 prompt 是一个组装出来的复合结构，包含四个部分：

1. System prompt：定义角色。比如 “你是一个代码助手，可以用 Shell、文件操作等工具完成任务。遇到问题时先分析，再选择工具执行。”
2. Tool descriptions：可用工具的列表——每个工具的 name + description + args_schema。LLM 靠这段文本来决定”现在应该用哪个工具，传什么参数”。
3. User input：用户的原始输入，比如 “统计 .py 文件行数”。
4. Scratchpad：一个占位符（MessagesPlaceholder），用来存放历史步骤。每完成一轮 Think→Act→Observe，Agent 会把最新的 AgentAction 和 Observation 填进去，让 LLM 知道”到目前为止发生了什么”。

MessagesPlaceholder 是 Agent prompt 的核心机关。它不是写死的文本，而是一个每轮循环都会被更新的空位。第一轮它可能是空的；第二轮它就包含了”上一轮我调用了什么工具、返回了什么结果”。LLM 基于这个不断更新的上下文来决定下一轮该做什么。

4. AgentAction 与 AgentFinish——每步只有两种可能

Agent 每一步的输出，经过 OutputParser 解析后，只有两种结构化结果：

• AgentAction：Agent 决定再调用一个工具。包含两个字段：
  • tool：要调用的工具名，比如 "run_shell"
  • tool_input：传给工具的参数，比如 {"command": "ls *.py"}
• AgentFinish：Agent 认为任务已完成，返回最终答案。包含：
  • return_values：一个字典，通常键是 "output"，值就是给用户的回答

OutputParser 的职责就是把 LLM 原始文本输出解析成这两种结构之一。LLM 的输出可能是这样的文本：

1
2

Action: run_shell
Action Input: {"command": "ls *.py"}

OutputParser 需要把它解析成 AgentAction(tool="run_shell", tool_input={"command": "ls *.py"})。

或者 LLM 认为任务完成了，输出：

1

Final Answer: 共 3 个 Python 文件，合计 214 行代码

OutputParser 就解析成 AgentFinish(return_values={"output": "共 3 个 Python 文件，合计 214 行代码"})。

这个二选一的设计非常简洁——Agent 每步要么再动手，要么收工。AgentExecutor 拿到结果后判断类型：如果是 AgentAction，就执行对应的工具；如果是 AgentFinish，就停止循环返回答案。

5. Callbacks——横向贯穿的钩子机制

Callback 不属于”纵向串行”的组件，而是一个横向贯穿的钩子系统：它在 Agent 执行过程的各个节点插入钩子，让你能拦截和观察每一步。

核心的 callback 钩子包括：

• LLM 相关：on_llm_start、on_llm_end、on_llm_error——在 LLM 调用前后触发
• Tool 相关：on_tool_start、on_tool_end、on_tool_error——在工具执行前后触发
• Agent 相关：on_agent_action、on_agent_finish——在 Agent 决策点和结束点触发

这些钩子的用途很广：

• 打印日志：AgentExecutor 的 verbose=True 就是靠 Callback 实现的——每一步的 Think、Act、Observe 都能看到完整输出。
• 流式输出 token：on_llm_new_token 钩子让你逐 token 推送内容，实现打字机效果。
• 写入监控：记录每次 LLM 调用的耗时、工具执行的成功率，方便后期分析。

有了 Callback，你不需要修改 Agent 的核心逻辑，就能在关键节点插入自己的业务代码——这是一个典型的观察者模式。

Agent 类型一览

LangChain 提供了多种 Agent 类型，它们的主要区别在于如何让 LLM 表达”我要用哪个工具”。

这些类型的本质差异在于：LLM 如何输出”我要调用什么工具、传什么参数”这个决策。

ReAct 是最早的实现方式——它在 prompt 里告诉 LLM：”如果你要用工具，请严格按以下格式输出：Action: 工具名\nAction Input: 参数“。然后 OutputParser 用正则从文本里提取。这种方式最灵活，不依赖模型能力，但解析可能出错——LLM 要是没严格按格式来，正则就匹配不上。

Tool Calling / OpenAI Tools 则是利用模型的原生 function calling 能力。LLM 不再用文本表达工具调用，而是直接返回结构化的 tool_calls 对象——工具名、参数全部是结构化的，不靠文本解析。这种方式更可靠，也是当前推荐的主流做法。Tool Calling Agent 的优点在于它是跨模型的统一接口——ChatAnthropic、ChatVertexAI 等非 OpenAI 模型也可以用。

JSON / XML Agent 让 LLM 按严格的 JSON 或 XML Schema 输出决策。相比于 ReAct 的正则解析，结构化输出更鲁棒，但 prompt 更长，token 消耗更高。

Structured Chat Agent 则是在聊天场景中支持多参数复杂工具的调用，适合工具函数签名比较复杂的场景。

选型建议：如果你的模型支持原生 tool calling（目前大部分主流模型都支持），直接用 Tool Calling Agent。如果模型不支持或你用的是本地小模型，降级到 ReAct。

完整链路走一遍

现在我们把所有组件串起来，用第一篇的同一个例子——“统计目录下 .py 文件的行数”——完整走一遍 LangChain 的执行链路。

注意这套流程里几个关键的设计：

• Prompt 的 scratchpad 是动态增长的。每轮 Think→Act→Observe 后，新的 AgentStep 追加上去，LLM 始终能看到”从开始到现在发生了什么”，这就是 ReAct 循环的”记忆”。
• OutputParser 决定了循环的走向。它解析出来是 AgentAction 就继续执行工具，解析出来是 AgentFinish 就停止。这相当于循环的”交通指挥灯”。
• AgentExecutor 是整条链路的总调度。它不参与推理，不执行工具——它的职责就是：组装 prompt → 调 LLM → 解析输出 → 调工具 → 回填历史 → 判断继续还是停止 → 循环。

一点说明：AgentExecutor 在 LangChain v1.0 中已进入维护模式，官方推荐的新方案是基于 LangGraph 的 create_agent()。但 AgentExecutor 的概念模型——调度器 + 循环 + 组件管道——完全适用于新方案。理解了这个模型，你自然就理解了新 API 在做什么。

用一段话串联所有组件

我们把这些概念串起来的视角再回顾一遍：

Runnable 是最外层协议，保证每个组件都有统一的 invoke() 入口。AgentExecutor 这个总调度器，内部用管道把 Prompt 模板 → LLM → OutputParser 串联起来。每次循环，Prompt 模板组装 System prompt + Tool descriptions（来自 BaseTool 的 name/description/args_schema）+ User input + Scratchpad（通过 MessagesPlaceholder 动态填充历史步骤）。LLM 推理后，OutputParser 把结果解析成两种之一：AgentAction（继续调工具，包含 tool 名和参数）或 AgentFinish（任务完成，返回最终答案）。如果拿到 AgentAction，AgentExecutor 就找到对应的 BaseTool 执行 _run()，把结果作为 Observation 回填到 Scratchpad，然后进入下一轮。Callbacks 在整个流程中横向贯穿，在每个关键节点触发钩子——你不需要改核心代码就能插入日志、流式输出、监控逻辑。循环直到 OutputParser 吐出 AgentFinish，最终答案返回给用户。

下篇预告

本文拆解了 LangChain Agent 的内部实现：

1. 三层包结构——langchain-core 定义抽象，langchain-classic 提供实现，langchain v1 是未来方向
2. 五大核心组件——Runnable 协议、BaseTool、Prompt 模板、AgentAction/AgentFinish、Callbacks——分别承担了协议、工具、记忆、决策、监控的职责
3. Agent 类型选择——优先 Tool Calling，降级 ReAct
4. 完整执行链路——从 executor.invoke() 到最终答案，每一步对应的 LangChain 概念

但读完一篇可能还不够过瘾。下一篇文章，我们直接上手写代码——从零搭建一个可以读写文件、执行命令的代码助手 Agent。你会看到不到 50 行代码，Agent 就真的跑起来了。

LangChain Agent 系列文章：

• (一) Agent 是什么？
• (二) LangChain Agent 内部怎么转的？（本文）
• (三) 从零搭建代码助手 Agent

越是不确定的时候，越不要把人生押在单一答案上。真正的出路不是一句“加油”，而是把自己的抗风险能力一点点做厚。

这两年，很多年轻人都有一种共同感受：

工作没以前好找了，涨薪没以前确定了，行业变化越来越快，身边人谈论最多的词也从“机会”变成了“稳定”“降本”“收缩”。

这不是某个人不够努力的问题。

国家统计局发布的 2024 年国民经济和社会发展统计公报显示，全年城镇新增就业 1256 万人，就业总量仍在增长；但从普通人的体感看，岗位结构、薪资预期、行业流动和学历竞争都在重排。

所以，今天这篇文章不想讲空泛鸡汤。

我想聊一个更现实的问题：在经济下行周期里，年轻人到底该怎么给自己找出路？

一、先承认现实：难，不等于没路

很多焦虑来自一个误会：以为“出路”必须是某个确定答案。

比如考公、进大厂、读研、创业、出国、做自媒体。

但经济下行时，单一答案反而更脆弱。因为一旦这个答案被挤满、变窄、变慢，人的心态就容易崩。

更好的理解是：

出路不是一条路，而是一组能力组合。

你需要的不只是“找到一个岗位”，而是逐渐具备三种能力：

• 能养活自己的现金流能力
• 能持续升级的专业能力
• 能在变化中迁移的选择能力

这三件事合起来，才是年轻人在低增长环境里的底盘。

二、不要再迷信“稳定”，要区分两种稳定

经济越不确定，越多人会本能地追求稳定。

这当然没错。但问题是，很多人追求的是“外部稳定”，比如单位稳定、合同稳定、平台稳定。

真正更可靠的是“内部稳定”：

• 你是否掌握一门市场愿意付费的技能
• 你是否有持续学习和复盘的习惯
• 你是否有 6 到 12 个月的现金缓冲
• 你是否能从一个行业迁移到另一个行业
• 你是否能独立完成一个可交付成果

外部稳定会受周期影响，内部稳定才跟着你走。

如果只能选一个方向，我更建议年轻人把注意力从“我要进入一个永远安全的地方”，转成“我要成为一个不容易被替代的人”。

三、第一条路：把主业做成“可迁移资产”

很多人一谈出路，就急着辞职、转行、创业。

但大多数年轻人的第一现金流仍然来自主业。下行周期里，主业不是束缚，而是现金流基地。

真正的问题是：你有没有把主业经验沉淀成可迁移资产？

可以用这四个问题检查：

• 我现在做的事，离开这家公司后还值钱吗？
• 我能不能把工作成果讲成案例，而不是只写岗位职责？
• 我有没有一套自己总结的方法论、模板、流程或工具？
• 我做过的项目，能不能证明我解决过真实问题？

比如同样是运营岗位，一个人只会写“负责用户增长”，另一个人能讲清楚“如何用三周时间把私域转化率从低点拉回到可接受水平”，后者的经验就更可迁移。

同样是开发岗位，一个人只写“参与系统开发”，另一个人能讲清楚“如何把一个高频接口的响应时间和稳定性做下来”，后者就更像资产。

在经济下行时，简历上最值钱的不是头衔，而是可验证的成果。

四、第二条路：学习 AI，但别只学“提示词”

AI 确实是这一轮变化里最值得重视的变量。

但很多年轻人对 AI 的学习方式有点偏：收藏工具、复制提示词、看别人演示，却没有把它嵌进自己的工作流。

更实用的做法是，把 AI 当成一个“能力放大器”，而不是一个神奇按钮。

你可以从三个层次开始：

1. 用 AI 提升表达

写周报、写方案、写简历、写复盘、写邮件。

不是让 AI 替你思考，而是让它帮你把粗糙想法整理得更清晰。

2. 用 AI 提升交付

做调研、生成代码、整理表格、搭建自动化脚本、分析用户反馈。

关键是形成自己的固定流程：输入什么、校验什么、输出什么、怎么复用。

3. 用 AI 做作品

不要只停留在“我会用”。你要留下作品。

例如一个自动化小工具、一篇系统教程、一个可演示网页、一个数据分析模板、一个行业资料库。

作品比口头能力更抗周期。

五、第三条路：用副业练能力，不要用副业逃避现实

副业不是人人都要做。

尤其在经济压力大的时候，盲目副业很容易变成另一种消耗：白天上班已经很累，晚上再被“搞钱焦虑”追着跑，最后主业没做好，副业也没有结果。

更健康的副业逻辑是：

先让副业服务能力增长，再让能力带来收入可能。

适合年轻人的副业不一定是开店、带货、做号，也可以是更小的交付：

• 给熟人做一次简历优化
• 给本地小店做一页菜单或海报
• 给团队搭一个自动化表格
• 把自己的专业经验写成系列文章
• 接一个低风险的小项目练完整交付

副业的第一价值不是赚大钱，而是让你理解市场：别人为什么愿意付费，什么东西才叫交付，沟通成本在哪里，复购靠什么发生。

这些理解，会反过来滋养主业。

六、第四条路：降低生活杠杆，给选择留空间

年轻人的很多痛苦，不只是收入不高，而是选择空间太窄。

房租、贷款、消费分期、情绪性购物、无效社交，把人推到一个状态：只要一个月没收入，就立刻慌。

经济下行时，现金流安全感非常重要。

不是鼓励所有人过苦日子，而是建议你给自己留出缓冲：

• 先攒 3 个月生活费，再追求更高收益
• 少做长期绑定的大额支出
• 避免为了面子维持超出收入的生活方式
• 每月固定复盘钱花在哪里
• 把“自由现金流”当成一种能力

有缓冲的人，才有资格慢慢选。

没有缓冲的人，往往只能被动接受。

七、第五条路：别把自己困在同龄人比较里

经济越难，比较越伤人。

有人上岸了，有人进大厂了，有人创业赚到钱了，有人家里能托底。

但你看到的往往是别人的结果，不是别人的成本。

年轻人最该警惕的，不是暂时落后，而是因为比较失去自己的节奏。

你可以慢一点，但不能停在原地。

你可以普通一点，但要持续积累。

你可以没有光鲜标签，但要有可以拿出来的作品、技能、存款、信用和健康。

这些东西看起来不够刺激，却会在三五年后拉开差距。

八、一张简单路线图：未来 12 个月怎么做

如果你现在很迷茫，可以先按这个顺序来：

第 1 到 2 个月：止血

整理收支，砍掉不必要开销，建立最低 3 个月生活费目标。

同时复盘主业，把过往项目写成 3 个可讲述案例。

第 3 到 6 个月：升级

选一个能和主业结合的技能，不要贪多。

比如 AI 自动化、数据分析、写作表达、产品思维、销售转化、编程能力、行业研究。

每个月至少产出一个公开作品。

第 7 到 9 个月：试水

尝试小规模外部交付。

可以是接单、咨询、内容、开源项目、社群分享，目标不是马上赚钱，而是拿到真实反馈。

第 10 到 12 个月：选择

根据反馈判断：

• 主业是否还有成长空间
• 是否值得跳槽
• 是否需要转向新赛道
• 副业是否具备持续收入可能
• 自己的能力资产是否已经变厚

这套路线不性感，但可执行。

越是下行周期，越要相信复利，而不是幻想。

结尾：年轻人的出路，是重新获得主动权

经济周期不是普通人能控制的。

但我们仍然可以控制几件事：学习什么，交付什么，花多少钱，认识谁，留下什么作品，如何照顾身体，如何在低谷里保持行动。

我不想说“年轻人一定会越来越好”这种轻飘飘的话。

我更愿意说：

当外部世界变慢，一个人最重要的能力，是别让自己完全停下来。

经济下行时，年轻人的出路不是硬扛，也不是躺平。

是在现实里保持清醒，在压力里保留弹性，在一点点积累中重新拿回主动权。

这是普通 LLM 最尴尬的时刻——它很聪明，但被困在训练数据的牢笼里。

你或许有过这样的体验：问 ChatGPT 一个问题，它滔滔不绝，逻辑清晰；可一旦让它帮你查一下今天的天气、读一下你桌面上的文件、或者帮你调一下公司的 API——它立刻摊手：”抱歉，我无法访问外部信息。”

这不是它不想帮你，而是它没有手，也没有眼睛。

本文是 LangChain Agent 系列的第一篇。我们先用大白话讲清楚 Agent 到底是什么、为什么需要它，不写一行代码。读完你会理解 Agent 的核心思想，为后面的实战打好基础。

普通 LLM 的局限

普通 LLM（大语言模型）本质上是一个”超级知识库 + 文本生成器”。它读过的所有东西都压缩在模型参数里，但它有三个致命短板：

1. 无法触及真实世界

LLM 的知识截止于训练数据日期。它不能查文件、不能调 API、不能看天气、不能读数据库——因为它的输入只有一段文本，输出也只有一段文本。

你问它”帮我统计一下当前目录下所有 .py 文件的行数”，它只能说：

“我无法读取你的文件系统。你可以用 wc -l *.py 命令来统计。”

它能告诉你怎么做，但不能帮你做。

2. 复杂任务一步到位出错率高

对于需要多步推理的任务，LLM 必须一次性输出完整答案。没有中间检查，没有回调，没有试错——一步到位。就像让你闭着眼睛解一道数学大题，中间过程全在脑子里算，写错了也没机会改。

结果就是：问题越复杂，正确率越低。

3. 无法自我修正——错了就错了

当你指出 LLM 的错误，它可以道歉然后重新输出。但它不会主动发现自己错了，更不会自己去排查哪里出了问题。它只会根据你的反馈生成新回答，而不是像人一样回过头去检查自己的推理过程。

这三个局限性，用一句话总结就是：

LLM 有大脑，但没有身体。

Agent 的核心思想

那有没有办法给 LLM 装上”身体”？这就是 Agent 的由来。

Agent 的核心定义非常简单：

Agent = LLM + 工具 + 决策循环 可以类比成一个while循环♻️

类比一下：如果 LLM 是大脑，那工具就是手和眼睛，决策循环就是”先想、再做、再观察、再调整”的行为模式。

工具：Agent 的”手和眼睛”

工具赋予了 Agent 与外部世界交互的能力：

• 搜网页：获取最新信息
• 读文件：访问本地文件系统
• 执行代码：跑 Python、Shell 等脚本
• 调用 API：查天气、发邮件、操作数据库

有了工具，Agent 不再是被困在训练数据里的”嘴强王者”，而是能真正干活的执行者。

决策循环：Think → Act → Observe

如果把 Agent 比作一个实习生，你交给他的任务不会一步完成：

1. 你：”帮我查一下上周的销售数据”
2. 实习生思考（Think）：”我需要先找到数据库地址和表结构”
3. 实习生执行（Act）：打开数据库客户端，查看表结构
4. 实习生观察（Observe）：”哦，有个 sales 表，字段是……”
5. 继续思考：”那我需要写个 SQL 查询”
6. 继续执行：写 SQL → 运行 → 看结果
7. 满意了，整理答案交给你

Agent 的工作方式完全一样。它就是在一个循环里不断思考、执行、观察，直到任务完成。

这就是著名的 ReAct（Reasoning + Acting）模式。其中 Think 对应 Reasoning（推理），Act 对应 Acting（行动），而 Observe（观察）是环境返回的结果，它会触发下一轮 Think，这样就形成了闭环。

ReAct 循环详解

让我们用”帮我统计目录下 .py 文件的行数”这个任务，完整走一遍 ReAct 循环。

注意这个过程的核心特征：

• 每步有明确目标：不盲猜，每一步都建立在观察结果之上
• 结果可验证：工具的返回结果是真实的、可追溯的，不是 LLM 编造的
• 循环可中断：一旦信息足够，就停止循环给出答案

这和人类处理任务的方式几乎没有区别——你不可能看到问题就直接写出答案，你也是”想一想→查一查→看一看→再想想”。

Agent 的自我纠错

Agent 最厉害的地方，不是它能用工具，而是犯错了能自己发现并修复。这恰恰是普通 LLM 做不到的。

举个例子：

用户：”帮我连上公司的数据库，查一下今天的订单量。”

1. Agent 写了连接代码，执行 → Connection refused
2. Agent 思考：”连接被拒绝，可能是端口号写错了？或者是数据库没启动？”
3. Agent 读配置文件 → 发现写的端口是 3307，实际应该是 3306
4. Agent 修正端口 → 重新连接 → 成功
5. Agent 查询订单量 → 返回结果

整个过程不需要用户插手。Agent 自己发现问题、自己排查原因、自己修复、继续执行。

普通 LLM 遇到同样的情况，只能输出一段 SQL 给你，然后说”你自己试试看能不能连上”。至于连接失败怎么办——它不知道，也不关心。

这个差异的本质在于：Agent 有一个反馈环，LLM 没有。

反馈环让 Agent 的行为从”一次性的文本生成”变成了”持续的、可纠错的执行过程”。这也是 Agent 能做复杂任务的根本原因。

Agent 能做什么

用一张表对比 LLM 和 Agent 的能力差异：

一句话总结：

LLM 只能”告诉你”怎么做，Agent 可以”帮你去”做。

下篇预告

本文用大白话讲清楚了 Agent 的三个核心概念：

1. LLM 的局限——有大脑没身体
2. Agent = LLM + 工具 + 决策循环——给大脑装上身体
3. ReAct 循环——Think → Act → Observe 的持续执行模式

但概念弄清楚之后，下一个问题自然就是——LangChain 是如何实现这套机制的？

LangChain Agent 的架构可以拆成三层：核心引擎、工具生态、记忆系统。下一篇我们就拆开这座金字塔，看清每一层是怎么运转的。

LangChain Agent 系列文章：

• (一) Agent 是什么？（本文）
• (二) LangChain Agent 内部怎么转的？
• (三) 从零搭建代码助手 Agent

• 一、Comet Skill 是什么
• 二、从 Superpowers 到 OpenSpec：Spec Coding 的探索之路
  • Superpowers 的痛点
  • OpenSpec 的特点
  • 经典组合的摩擦
• 三、Comet Skill 的核心设计
  • 3.1 稳定的状态扭转：引入状态机思想
  • 3.2 意图识别：跨设备断点恢复
  • 3.3 人机确认机制：关键节点人工把控
  • 3.4 重叠 Spec 的交接：建立单向事实链
• 四、Harness Engineering：Skill 侧的工程化
• 五、总结

一、Comet Skill 是什么

在 AI 驱动开发的浪潮下，Spec Coding（规格驱动编码）成为了许多开发者探索的新范式。它的核心理念是：先写清楚”要做什么”（Spec），再让 AI Agent 按照规格执行。

Comet Skill 正是在这个背景下诞生的——它将 OpenSpec 和 Superpowers 最精华的部分串联起来，打造出更易用、更稳定的 Spec Coding 工作流。

几个关键数据：

• GitHub 400+ Star
• 120+ 分钟阅读量
• 4.5k+ 次下载
• 经过生产环境验证

二、从 Superpowers 到 OpenSpec：Spec Coding 的探索之路

Spec Coding 领域有许多优秀工具：Superpowers、Everything Claude Code、OpenSpec、GStack、Spec-kit 等，开发者或多或少都用过其中一两个。但它们各有优劣。

Superpowers 的痛点

Superpowers 作为老牌高星 Skill，核心能力在于优秀的头脑风暴和执行力，但在 Spec 文档管理方面存在明显短板：

1. 上下文压缩问题

当 Spec 文档内容过多时，会触发上下文压缩，导致 Agent 忘记回写文档。在多轮头脑风暴和文档生成过程中，大量 Token 消耗在”恢复现场”上，而实际的文档推进工作却未完成。

2. 文档管理混乱

同一天多次使用 Superpowers 会产生大量文档，这些文档没有明显的完成状态标识，打勾信息散落在文档细节中。开发者需要人肉扫描文档来识别完成情况。当存在多个同日期的 Spec 时，识别成本极高，甚至需要借助工具逐行阅读文档才能判断。

OpenSpec 的特点

OpenSpec 则是一条更轻量的路径。它在完成提案设计后，不采用 worktree 也不强制 TDD，而是更相信 Agent 的能力，让 Agent 根据 Task 一步一步执行。

相比 Superpowers，OpenSpec 的优势在于：

• 优秀的 Spec 资产管理：拥有非常好的归档能力
• 丰富的 CLI 命令：方便 Agent 获取信息

但在细节的头脑风暴体验上，它不如 Superpowers 强烈。

经典组合的摩擦

既然两者各有优劣，经典的使用方法是将它们的强项衔接起来：用 OpenSpec 做规划和 Spec 归档，用 Superpowers 做深度执行。

但这种组合也带来了新的摩擦：

三、Comet Skill 的核心设计

基于上述问题，Comet Skill 围绕四个核心设计展开。

3.1 稳定的状态扭转：引入状态机思想

Agent 状态管理和文档更新是 Spec Coding 最脆弱的一环。Comet 的解法是引入状态机思想。

具体做法：通过 CLI 实现和 bash 脚本，将校验状态和核心文件识别程序化。Agent 不需要知道文件状态的细节，只需按规则执行核心脚本。当需要退出某个阶段时，通过程序判断是否达到条件，而不是依赖 Agent 的”感觉”。

带来的收益：

• Skill 变得更轻量，需要描述的 Prompt 更少
• 稳定性大幅提升——程序判断代替模型判断

3.2 意图识别：跨设备断点恢复

Comet 支持跨设备的断点恢复，核心原理是”关键文件检测 + 意图识别”。

意图识别是一个四层漏斗，从粗到细收敛用户意图：

1

preset 探测 → 活跃 change 发现 → 状态快照读取 → 阶段判定链

设计约束很清晰：无歧义时自动推进，有歧义时等待用户确认。

这意味着当开发者重新回到工作区时，无论是否在同一台电脑、窗口是否包含上下文，都不需要重新解释背景。只需执行 comet 继续 命令，就能从核心文件恢复当前状态，继续推进需求。

3.3 人机确认机制：关键节点人工把控

Comet 并非”一跑到底”的全自动流程。在五阶段流程自动触发的过程中，以下关键节点仍需要人工确认：

• 分支选择
• 执行方式选择
• Spec 调整

Comet 的做法是提供默认推荐项，同时依赖 Agent 自主识别选项。这满足了开发者在生产级工作中对关键节点把控的需求，避免了”一跑到底”与 Vibe Coding 无差别的问题，确保代码的完整可靠性。

3.4 重叠 Spec 的交接：建立单向事实链

这是 Comet 最精妙的设计。OpenSpec 和 Superpowers 都会产生 Spec，为了消除两者功能重叠带来的歧义，Comet 在它们之间建立了单向事实链：

关键约束：Superpowers 的 design doc 不得自行补写需求。

两者的衔接通过 comet-handoff.sh 脚本实现。该脚本从 OpenSpec 产物中生成结构化的交接包，包含：

• 源文件路径
• 行范围
• SHA256 哈希
• 确定性摘录（而非 Agent 临场手写的 Summary）

并且明确声明 canonical_spec: openspec，表明需求定义权归属上游。

如果 Superpowers 在深度设计中发现 OpenSpec 遗漏了验收场景，不允许在 design doc 中自行补写，只能提出 Spec patch 回写到 OpenSpec 的 Delta Spec 中，最终覆盖到主 Spec，完成整个 Spec 生命周期的闭环。

1
2
3
4
5

OpenSpec（需求定义）
    ↓ comet-handoff.sh 交接包
Superpowers design doc（实现方案）
    ↓ 发现遗漏 → Spec patch
Delta Spec → 回写 → OpenSpec 主 Spec

四、Harness Engineering：Skill 侧的工程化

Comet 本质上做的是 Harness Engineering（Skill 侧的工程化），而非 SDK 代码层面的工作。

这也是为什么去年爆火的 deep research 应用都转化为了 deep research 的 skill——因为 skill 让写 prompt 的过程从 SDK 中跳了出来，变成了人人可写的工具。

在 Skill 编排方面，以 OpenSpec 为例，它允许一定的 Skill 编排能力。用户可以创建一个路由 Skill，在里面写上”先调用 A skill 再调用 B skill”，最简单的编排就完成了，甚至只需要一句话。随着数据积累，模型能够内化选择组合哪些 Skill、自行迭代哪些 Skill 的能力，而这些是可以通过 Benchmark 训练的。

真正的核心能力是让 Skill 变得更稳定，而这一过程就是在走 Harness Engineering 的路。

五、总结

Comet Skill 解决的核心问题是：把 Spec Coding 从”能用”变成”稳定可用”。

Comet Skill 的出现，为开发者在 AI 时代的 Spec Coding 提供了新的可能。它帮助开发者管理 Spec、专注执行，让大家能够在 AI 时代 Vibe Coding 出自己的创意。

• 一、为什么选 Claude Code
• 二、快速安装
  • 2.1 安装 Node.js
  • 2.2 安装 Claude Code
• 三、模型厂商与 Coding Plan 对比
  • 3.1 阿里百炼
  • 3.2 腾讯云混元
  • 3.3 百度千帆
  • 3.4 DeepSeek
  • 3.5 火山引擎（字节）
  • 3.6 MiniMax
  • 3.7 智谱 GLM
  • 3.8 月之暗面 Kimi
• 四、模型厂商切换：CC Switch
• 五、Skill：Claude Code 的核心扩展机制
  • 5.1 什么是 Skill
  • 5.2 常用 Skill 安装
  • 5.3 Skill 路径
  • 5.4 Skill 仓库与超市
• 六、辅助工具推荐
  • 6.1 Starship：终端美化
  • 6.2 gstack：工程团队工具集
  • 6.3 Claude HUD：可视化监控面板
  • 6.4 跳过权限确认
• 七、2026 年值得关注的新工具
• 八、总结
• 引用

一、为什么选 Claude Code

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手。相比 IDE 插件，它有几点核心优势：

1. 终端原生：直接在你的 shell 里运行，能操作文件系统、执行命令、管理 git，不需要 IDE 作为中间层。
2. Skill 机制：通过 Skill 文件扩展 Agent 能力，类似”给 Agent 写操作手册”，比传统插件更灵活。
3. MCP 协议：通过 MCP (Model Context Protocol) 连接外部工具和数据源，生态开放。
4. 多模型后端：官方使用 Claude 系列模型，但通过 CC Switch 等工具可以切换到国内模型厂商。

下面从安装开始，一步步配好你的 Claude Code 开发环境。

二、快速安装

2.1 安装 Node.js

Claude Code 是一个 npm 包，需要 Node.js 环境。推荐用 nvm 管理 Node 版本：

1
2
3
4
5
6
7
8
9
10
11
12

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# 加载 nvm
\. "$HOME/.nvm/nvm.sh"

# 安装 Node 24
nvm install 24

# 验证
node -v   # 应输出 v24.16.0
npm -v    # 应输出 11.13.0

2.2 安装 Claude Code

1
2
3
4
5
6
7
8

# 安装
npm install -g @anthropic-ai/claude-code

# 查看版本
claude --version

# 后续升级
claude update

安装完成后在终端输入 claude 即可启动交互式会话。官方文档：設定 Claude Code

三、模型厂商与 Coding Plan 对比

Claude Code 原生使用 Anthropic 的 Claude 系列模型，但国内用户可以通过第三方工具切换到国产模型。以下是主流模型厂商的 Coding Plan 概览：

3.1 阿里百炼

阿里云百炼平台提供 Qwen 系列等模型，支持 Coding Plan 订阅。

• 控制台：阿里云百炼

3.2 腾讯云混元

腾讯混元大模型提供 Coding Plan，适合腾讯云生态用户。

• 购买页：腾讯云混元

3.3 百度千帆

百度智能云千帆大模型平台，提供文心系列模型。

• 控制台：百度千帆

3.4 DeepSeek

DeepSeek 独立平台，以高性价比和强代码能力著称。

• 用量页：DeepSeek Platform

3.5 火山引擎（字节）

火山方舟 Coding Plan 支持的模型最丰富：DeepSeek-V4 系列、GLM-5.1、Doubao-Seed-2.0 系列、Kimi-K2.6、MiniMax-M2.7 等。订阅叠加 9.5 折，低至 38 元。

• 订阅链接：https://volcengine.com/L/ooEqNrnaXdU/
• 邀请码：KGRNLDMJ

3.6 MiniMax

MiniMax 提供 M2 系列模型，也有 Coding Plan 可供选择。

• 订阅方式同上（火山方舟渠道也支持 MiniMax 模型）

3.7 智谱 GLM

智谱 GLM Coding Plan 适配 20+ 主流工具，性价比突出。

• 拼好模活动：https://www.bigmodel.cn/glm-coding?ic=FVAXRFATIM

3.8 月之暗面 Kimi

Kimi 提供会员订阅模式，可在 Kimi 首页侧边栏进入。

• 定价页：Kimi 会员

四、模型厂商切换：CC Switch

Claude Code 默认对接 Anthropic API，要使用国内模型，需要借助 CC Switch 做 API 代理和模型映射。

• 项目地址：CC Switch Releases（当前最新 v3.16.2，2026-06-08 发布）

CC Switch 的核心原理是在本地启动一个代理服务，将 Claude Code 发往 Anthropic API 的请求拦截并转发到你配置的国内模型厂商 API，同时做请求/响应格式的兼容转换。目前 CC Switch 已不限于 Claude Code，同时支持 Codex、OpenCode、Gemini CLI 等工具。

基本使用流程：

1. 从 Release 页下载对应平台的二进制文件
2. 配置目标模型厂商的 API Key 和 Endpoint
3. 启动 CC Switch 代理
4. 设置环境变量让 Claude Code 走代理

这样 Claude Code 实际调用的就是国产模型，但交互体验保持一致。

五、Skill：Claude Code 的核心扩展机制

5.1 什么是 Skill

Skill 是 Claude Code 的扩展机制——本质上是给 Agent 注入一段专业领域的 System Prompt，告诉它”遇到某类任务时应该怎么做”。一个 Skill 就是一个 Markdown 文件，放在特定目录下即可被 Claude Code 自动发现和加载。

相比传统插件的优势：

• 声明式：不需要写代码，写清楚流程和规则即可
• 可组合：多个 Skill 可以同时生效
• 用户可控：Skill 优先级低于用户指令，用户始终拥有最终控制权

更多原理参考：

• Claude Code Skills 详解（一）
• Claude Code Skills 详解（二）

5.2 常用 Skill 安装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 前端设计
/plugin install frontend-design@claude-plugins-official

# 代码审查
/plugin install code-review@claude-plugins-official

# 代码简化
/plugin install code-simplifier@claude-plugins-official

# UI/UX 设计
claude plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
claude plugin install ui-ux-pro-max@ui-ux-pro-max-skill

# SDD (Superpowers Driven Development)
claude plugin install superpowers@claude-plugins-official

# agent-browser（浏览器自动化）
npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

# skill-creator（创建自定义 Skill）
npx skills add https://github.com/anthropics/skills --skill skill-creator

# Brave Search（搜索集成）
cp -r brave-search-skills/skills/* ~/.agents/skills/    # 用户级
cp -r brave-search-skills/skills/* .agents/skills/       # 项目级

5.3 Skill 路径

Skill 文件存放在以下位置：

用户级 Skill 对所有项目生效，项目级 Skill（.claude/skills/）只对当前项目生效。

5.4 Skill 仓库与超市

如果你不想自己写 Skill，可以从社区仓库找现成的：

• Awesome Claude Skills：GitHub — 精选 Skill 列表，涵盖开发、设计、运维等场景
• SkillsMP：skillsmp.com — Skill 超市，可直接浏览和下载

六、辅助工具推荐

6.1 Starship：终端美化

Starship 是一个跨 shell 的轻量级提示符，能让终端显示 git 分支、Node 版本、命令耗时等信息，Claude Code 场景下特别实用——一眼就能看到当前项目状态。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 先安装 Homebrew（如已安装可跳过）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 安装 Starship
brew install starship

# 配置 ~/.zshrc，在文件末尾追加
echo 'eval "$(starship init zsh)"' >> ~/.zshrc

# 生效
source ~/.zshrc

6.2 gstack：工程团队工具集

gstack 是一套面向工程团队的 Claude Code Skill 集合，提供 CEO 审查、设计评审、QA 测试、安全审计、部署等 23+ 个 Skill，远不止搜索功能。

前置要求： 需要安装 Bun v1.0+。

1
2
3
4
5
6

# 安装 Bun（如未安装）
curl -fsSL https://bun.sh/install | bash

# 克隆 gstack 并自动安装
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

详细使用参考：gstack 使用指南

6.3 Claude HUD：可视化监控面板

Claude HUD 是一个在终端内嵌的 HUD（抬头显示）面板，可以实时显示上下文用量、活跃工具、运行中的 Agent 和 Todo 进度，让你对 Claude Code 的运行状态一目了然。

1
2
3
4
5
6
7
8

# Claude Code 内执行
/plugin marketplace add jarrodwatts/claude-hud

# 安装插件
/plugin install claude-hud

# 初始化
/claude-hud:setup

详细使用参考：Claude HUD 介绍

6.4 跳过权限确认

Claude Code 在执行文件操作、运行命令时会弹出权限确认。如果你在安全环境下希望减少打断，可以：

1

claude --dangerously-skip-permissions

⚠️ 这个参数会跳过所有权限确认，只在完全信任的环境中（如个人开发机）使用。Claude Code 还提供了更温和的 --allow-dangerously-skip-permissions 参数，仅允许跳过权限但不默认开启，安全性更高。

七、2026 年值得关注的新工具

2026 年 Claude Code 生态涌现了不少新工具，这里推荐几个实用的：

八、总结

Claude Code 的核心理念是”终端即 IDE”——不是替代 VS Code，而是提供一种更轻量、更脚本化、更 Agent 友好的编程方式。配合 Skill 和 MCP，它能做的不只是补全代码，而是真正帮你完成多步骤的工程任务。

引用

• Claude Code 官方文档
• CC Switch
• Awesome Claude Skills
• SkillsMP
• gstack 使用指南
• Claude HUD 介绍
• Claude Code Skills 详解