AI 编程：系统学习路线与实战教程

数命令数会数漏：294 个 Tauri 命令与一个 grep 陷阱

cc-switch 的 Tauri 命令到底有多少个？按属性宏严格匹配数出来是 275，把带参数的写法一起算才是 294，差的 19 条全来自 `rename_all = "camelCase"`。这篇给出三条互相独立的计数路径，说清这个陷阱还会在哪些地方原样复现，以及 294 这个数能说明什么、不能说明什么。

README 说「50+ 预设」，八个预设文件里数出来 448 条

CC Switch 的预设到底有多少条？README 三处写「50+」，用户手册的表格只列几十行，而 src/config/ 下八个应用预设数组加起来是 448 条。这篇把三层口径各自的位置标出来，给出可复现的计数方法与一个会数错的 grep 陷阱，并说清 448 这个数究竟在数什么、不在数什么。

三个平台怎么装：msi / dmg / AppImage 与 brew、paru 的取舍

CC Switch 在 Windows、macOS、Linux 上各有两到三种安装方式。这篇按 README 与用户手册的原文把产物文件名、包管理器命令、系统要求逐条列清，重点标出一处会让你比对文件名时对不上的口径差：README 给的 Linux 包名没有架构后缀，而 CI 脚本拼出来的名字带架构。

README 说八个、用户手册只列七个：支持工具清单的三处口径差

CC Switch 到底管几个 AI CLI 工具？README 四处写「八个」，用户手册的三张清单都只有七个，而 package.json 与 Cargo.toml 的 description 只写了三个。这篇把三处口径的文件与行号标出来，给出可自己复核的比对动作，并说清为什么查「我的工具支不支持」不能只看标题行。

README 写 Rust 1.85+ 而 toolchain 钉的是 1.95：四条版本门槛的两层口径

想从源码构建 CC Switch，README 的「环境要求」给了 Node.js 18+、pnpm 8+、Rust 1.85+、Tauri CLI 2.8+ 四条。但这四条在仓库里各有第二个出处，其中三条对不上：Rust 在同一个仓库的两个文件里差了十个小版本。本文标出每一处的文件与行号，并给出可复现的比对动作。

测速的超时钳制：2 / 8 / 30 秒这三个数是怎么用的

CC Switch 的端点测速在源码里写死了三个常量：最小 2 秒、默认 8 秒、最大 30 秒。它们不是三档可选值，而是一个用 clamp 夹住的区间。这篇把三个常量所在的行、钳制发生的位置、以及「一次测速其实发两次请求」这件事讲清楚，并说明它们和代理转发的那套超时、和连通性检查的 8 秒是三套互不相干的配置。

27 个日志错误码与错误到 HTTP 状态的映射表

CC Switch 本地代理有两套互不重合的错误坐标系：`log_codes.rs` 里 27 个日志错误码打在日志文本里，`error_mapper.rs` 把内部错误折成十来个 HTTP 状态码返给客户端。这篇把两张表都摊开，说清为什么好几种完全不同的失败在客户端看来都是同一个 503，以及排查时该从哪一头往回查。

本地代理模式做什么：一条请求经过的完整管线

CC Switch 的本地代理不是把请求原样转出去。这篇按源码顺序把一条请求走过的每一站拆开：TCP 层为什么要在 hyper 解析前 peek 8192 字节、25 条路由为什么一个能力挂四个路径、请求体被加工过哪几道、响应回程怎么解压与计时、用量最后落在哪张表，并给出可自己复现的核查路径。

`ccswitch://` 一键导入：四类载荷与解析器的边界

CC Switch 的 ccswitch:// 深链只有一条固定骨架，但 provider / prompt / mcp / skill 四类载荷的参数契约互不相同。这篇把解析器每一道校验落到源码行号上，说清哪些参数要 Base64、用户手册与代码的四处口径差在哪，并给出你自己复核的方法。

模型定价表的三层来源与本地覆盖

CC Switch 算出来的那个花费数字，价格是从哪查到的？内置种子 189 条、修价表 34 条、本地覆盖文件三层各管一段，而最反直觉的一处是本地文件刻意不存全量。本文标出每一层的文件与行号，说清 INSERT OR IGNORE 为什么逼出第二张表，并给出可自行复现的核查动作。

CC Switch 后端四层：Commands → Services → DAO → Database 各自管什么

cc-switch 的 README 把后端画成 Commands → Services → DAO → Database 四层。我们按仓库快照逐目录核对了这四层的文件数、行数与职责边界，并指出「DAO 层其实不是一个对象」「箭头有一处是反向的」这两处容易读错的地方，以及注释目录树与实际模块数对不上的一处差异。

`category` 不只是个标签：它同时决定 UI 分组、路由判定和代理接管拦截

CC Switch 的预设里有个 category 字段，看着像给界面分组用的标签，实际上它在三个地方被当成开关读：分类筛选、providerNeedsRouting 的第一行早退、以及代理接管下的切换拦截。这篇给出八个取值的语义、八个应用的分类分布，并落到五条没填 category 的预设上，附可自己复现的计数方法。

格式转换层落在哪：三套协议适配器的位置与边界

CC Switch 的本地代理要同时伺候八个 AI CLI，但适配器只有 Claude、Codex、Gemini 三套实现。这篇把「协议转换」这件事在代理管线里拆成五段，指出真正调用适配器的那一行、它是按供应商而不是按工具开关的、以及三个 transform 大文件里我们没读到的部分，给出你自己就能跑一遍的核查动作。

「切回官方登录」是怎么实现的：CC Switch 里 official 类预设的机制

切回官方账号听上去像要写入一份官方配置，但在 CC Switch 的源码里恰恰相反：official 预设是一份刻意留空的配置，切过去之后还要专门擦掉残留的第三方凭据。本文按仓库快照逐处标出这套机制落在哪些文件的哪几行。

故障转移怎么挑下一家：候选队列与「忽略当前供应商」

CC Switch 的本地代理开启故障转移后，选下一家的依据不是「当前供应商失败了再找备胎」，而是完全按故障转移队列从头走一遍，当前供应商本身不参与起点判定。这篇把 provider_router.rs 的两条互斥分支、熔断器被问两次的不同语义、尝试次数上限与切换落盘的四道闸门逐行标出来，并给出可自行复现的核查路径。

切了供应商还是走老地址：CC Switch 的环境变量冲突检查在查什么

在 CC Switch 里切了供应商，命令行工具却像没变一样，常见嫌疑之一是系统环境变量。本文按 cc-switch 源码摊开冲突检查的关键词表、前缀与精确两种匹配语义、Windows 与非 Windows 各自扫哪些位置、删除前的强制备份规则，并给出可自行核对的判定动作与两处文档差异。

手册说能删、后端直接报错：当前供应商删除规则的两处矛盾

CC Switch 的用户手册写「当前启用的供应商可以删除」，而后端 delete 对非累加模式应用直接返回「无法删除当前正在使用的供应商」，README FAQ 的标题也是「为什么删不掉」。这篇把三处原文的行号标出来，说清这条规则为什么按应用类型分叉，并给出删不掉时的判定与排除动作。

Linux 上点不动、缩放黑屏：`CC_SWITCH_GDK_BACKEND` 这个逃生开关

CC Switch 在 Wayland + NVIDIA 下内容区点不动、缩放黑屏，README FAQ 的处置是环境变量 CC_SWITCH_GDK_BACKEND。本文对读 README 与 main.rs 的 Linux 分支，讲清它为何不叫 GDK_BACKEND、两个取值各对什么环境、怎么判定与验证。

MCP 配置校验拦住了哪些写法

CC Switch 里名叫 validation.rs 的那个文件只有 69 行、两个公开函数、四条规则，一个单测都没有。真正会拒掉你那份 MCP 配置的判断分散在深链层、转换层和写入层。这篇把四层各自拦什么、报什么话、落在哪个文件的哪一行标出来，并给出可以自己复现的核查动作。

双向同步与「应用没装就跳过」：CC Switch 里 MCP 同步的实际行为

在 CC Switch 的 MCP 面板里勾一个应用，落盘时到底发生了什么？这篇按 src-tauri/src/mcp/ 与 services/mcp.rs 的源码，拆开 should_sync_*_mcp() 守卫、DB→live 与 live→DB 两个方向、取消勾选时的反向删除，以及导入的容错口径。

一个面板管多个应用的 MCP：各自配置文件路径与格式差异

CC Switch 的统一 MCP 面板把一条服务器条目投影到多个 CLI 的本地配置里，但落盘的文件路径、承载键与字段写法各不相同。本文按源码行号梳理六个应用各自写到哪个文件、哪个键、要做哪些字段改名与类型换算，并指出往返转换里不守恒的那一处。

三种托管 OAuth 必须开路由：`OAUTH_PROVIDER_TYPES` 的判定链

CC Switch 里「这个供应商要不要开路由接管」不是看格式转换决定的。托管 OAuth 那三种 providerType 在判定链里排在 apiFormat 之前，一律返回 true。这篇把 providerNeedsRouting 的六步分支逐行标出位置，说清前端数组与后端方法的覆盖面差异，并给出复核动作。

`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`：三份文件的同步与回填保护

CC Switch 的 Prompts 功能把提示词写进各个 CLI 的真实配置文件。这篇按源码讲清文件名映射落在哪一行、切换时的回填保护把 live 文件内容存到了哪、全部禁用为什么会把文件写成空串，以及手动导入与首次自动导入的 enabled 默认值为何相反，并给出可自己复现的核查路径。

数据库怎么升级：迁移调度与建表注释里跳掉的三个编号

CC Switch 把所有可同步数据放在一个 SQLite 库里，版本一升就要动表结构。这篇讲清 SCHEMA_VERSION 与 PRAGMA user_version 是怎么配合的、逐版本递推的迁移循环长什么样、两道版本拒绝分别拦什么，并把建表注释里 13/14/15 三个跳掉的编号还原成可复现的核查动作。

CC Switch 的主进程在窗口出现之前要跑完一长串动作，而这串动作里有两处「必须早于」是靠顺序保证正确性的：旧配置校验早于建库、数据库版本预检早于任何写 schema。这篇把 lib.rs 的启动顺序、panic_hook 的崩溃日志、lightweight 的窗口销毁与重建、托盘的 ID 常量逐个落到文件与行号上，并给出在仓库快照 c39c903 里自己回查这些行号的办法，同时框清楚哪几个文件我们只读了常量与签名、主体并没有读完。

CC Switch 熔断器：三个状态、四个阈值，以及代码里同时存在的 4 和 5

cc-switch 的代理层用一个三状态熔断器决定某个供应商还要不要继续被打。这篇把 Closed / Open / HalfOpen 的五条转移边钉到具体行号上，并摊开同一个 failure_threshold 在代码默认、路由兜底、列级 DEFAULT、Claude seed 四层各不相同的取值。

会话管理器能读哪些来源，读到的又是什么

CC Switch 的 Session Manager 在代码里并发扫七个来源，用户手册的表只有六行；更要紧的是「能读到」不等于「能恢复」——七个来源里两个的 resume 命令是 None，而拉起终端的入口在非 macOS 上直接返回错误。本文按源码行号讲清七个根目录、两条读取分支与删除的路径校验。

一个桌面应用管八个 AI CLI：CC Switch 到底替你做了什么

CC Switch 不是挡在你和模型之间的常驻中间层，而是一个替你改写本机 CLI 配置文件的桌面应用，数据落在一份 SQLite 里。这篇从仓库源码与文档口径出发，说清它管的是哪一层、为什么「总有一个供应商删不掉」是设计推论、切换后哪些工具要重启，以及它把哪些敏感数据放在了你本机。

`~/.cc-switch/` 里有什么：一个库、一份设置、两种备份与一批软链

CC Switch 把数据落在 ~/.cc-switch/ 下，README FAQ 列了五条路径。这篇把五条路径逐个对到 src-tauri 里的拼接代码，重点讲清一件反直觉的事：目录里同时存在三套互不相干的备份保留策略，其中一个可配、两个硬编码，README、用户手册与代码对这个数的写法并不一致。

Skills 装成软链还是复制：两种策略的差别与 skill-backups

CC Switch 装 Skill 时，用户手册第 100 行写的是「复制到本地」，而代码里默认的同步方式是 Auto——优先软链、失败才复制。这篇把 SyncMethod 三个取值和 Auto 分支的判断顺序逐条读一遍，讲清那个最容易被忽略的前置条件，再把复制路径的临时目录加 rename、拒绝同步的 SKILL.md 闸门，以及卸载前自动备份的 skill-backups 目录命名、保留数量与恢复校验一并标到具体行号上，最后给出你可以自己复现的四步核查路径。

16 张表读一遍：所谓 SSOT 到底存了哪些东西

CC Switch 把「所有数据存在一个 SQLite 库」写进 README 的核心设计，但把 `schema.rs` 的 16 张表读完会发现 SSOT 是分域的：Skills 的事实源在文件系统，MCP 的事实源在表里而 live 文件只是投影，还有五张表在同步时被整个跳过。本文按建表顺序过一遍并给出核查命令。

文档说发真实请求，代码只探连通性：Stream Check 的三处口径差

CC Switch 的模型检查（Stream Check）在用户手册与源码里是两件不同的事：手册说发真实 API 请求验模型与 Key，代码模块自述只探 base_url 可达性，默认超时与重试次数两边也各写各的，熔断恢复归谁管更是相反。这篇把三处差异的文件与行号标出来，并给出你自己核一遍的动作。

三个 thinking 整流器分别在修什么：两个是事后补救，一个是事前改写

CC Switch 的 proxy 下三个带 thinking 的模块常被当成同一件事的三个档位。实际上两个 rectifier 靠上游错误文本触发、属事后补救，optimizer 是请求前改写、默认关闭且只对 Bedrock 生效。本文把三者的触发条件、改写动作与默认开关落到文件行号上。

universal 统一供应商：一份配置同步多个工具的边界在哪

CC Switch 的「统一供应商」把一份网关配置分发给多个 CLI，但它的覆盖面、同步时机与合并方式都有明确边界。本文按 src/config/universalProviderPresets.ts 与 src-tauri 后端源码，逐条讲清它能同步到谁、什么时候才同步、同步时怎么合并，以及关掉一个开关会发生什么。

切换之后配置少了一段：CC Switch 通用配置片段的提取与回填

在 CC Switch 里切换供应商后，把该供应商保存的配置和切换前的 live 文件逐字比对会发现少了一段。这不是丢失，而是 switch_normal 回填这一步先把可共享改动同步进通用配置片段再剥离写回的结果。本文按源码行号拆开这条路径，给出可复现的四步核查动作并说清哪三个应用不产出通用片段、哪三个应用不走回填。

7 种用量脚本模板与那个 QuickJS 沙箱

CC Switch 的用量查询脚本在代码里有 7 种模板类型，用户手册第 2.5 节却写「三种预设模板」。这篇标出两处的确切位置，再把执行侧那个 QuickJS 沙箱拆开看：5 秒超时、16 MiB 内存、256 KiB 栈这三道限额是防谁的，以及为什么一个查余额的小脚本值得上沙箱。

用量数字从哪来：代理请求日志 vs 本地会话文件

CC Switch 的用量统计有两条数据来源——本地代理记下的请求，和从各个 CLI 的会话文件里解析出来的记录。两者写进同一张表，靠一列 data_source 区分，靠 token 数四元组加十分钟时间窗去重。这篇把表名、列名、六个取值、五个解析器读的路径和去重条件逐个落到源码行上，并给出你自己的核查动作。

原子写入与自动备份：配置不被写坏靠的是哪两件事

CC Switch 把「不被写坏」拆成两条互不重叠的路径：JSON/TOML 文件走 config.rs 的 atomic_write（临时文件加重命名），SQLite 库不走这条路，而是靠 rusqlite 在线备份 API 加轮换。这篇标出两条路径各自的文件与行号，以及 Windows 侧的特殊分支。

云同步两条路线：共享协议层下的 S3 与 WebDAV

CC Switch 的云同步看起来是 S3 和 WebDAV 两套功能，源码里其实是一层共享协议加两个传输层。这篇标出协议常量、产物集合、上传与落地顺序，说清自动同步的真实触发条件是表变更而不是按间隔、并且只做上传不自动下载，也标出用户手册与代码对不上的那两处，最后给出你自己就能跑一遍的三条核查动作。

一条预设长什么样：`ProviderPreset` 的字段全集与各自作用

CC Switch 的 Claude Code 预设接口 ProviderPreset 定义了 21 个字段，但把 72 条预设逐个字段数一遍会发现：出现次数满格的只有 4 个，另有一半字段只服务于个位数条目。本文给出完整字段表与出现次数，说清每个字段落在哪一层、改它会牵动什么。

注册表 79 条、顶层 82 个目录：差的那几个是什么

CLI-Anything 的 registry.json 有 79 条记录，仓库根目录有 82 个目录，很多人会顺手一减得出「差 3 个」。这两个集合的交集其实只有 68 个名字，两侧各自还剩 11 个和 14 个。本文把两份差集逐个列出来，说清大小写比对的坑，并交代 79 条条目距离「79 个能用的能力」还差什么。

README 口径的安装与使用：先看清它装到哪

照着 CLI-Anything 的 README 敲一条 pip 命令，机器上并不会多出任何一个能操控软件的能力。本文按 README 原文把安装拆成三层：hub 本身、单个 harness 包、你得自己装的宿主软件，并落到 `registry.json` 的字段与那句最容易被跳过的前置提醒。

CLI-Anything 的 `<APP>.md` 里到底写什么：一层没有强模板的项目分析与 SOP

CLI-Anything 每个 harness 顶层都有一份写着「项目分析与 SOP」的文档。本文不复述 harness 四件套结构，只讲这一层：实读 67 份文件统计小节频次，对照三份样本的结构差异，说明它固定下来的不是模板而是三个必答问题，以及它与包内 README 的分工和读数口径。

blender harness：3D 场景是怎么被命令行捏出来的

CLI-Anything 的 blender harness 把 3D 场景做成一份 JSON 工程，再翻译成 bpy 脚本交给 blender 无头执行。本文落到源码行号上讲清这条链路，并把最容易理解反的一处讲透：`render execute` 这条命令其实不启动 Blender，只生成脚本并把命令行还给你。

`<app>_cli.py` 的入口模式与命令注册方式

CLI-Anything 的 `<app>_cli.py` 是 harness 里同构度最高的一层。本文拆它的入口模式与两级命令注册，讲透最反直觉的一处：不带子命令时它不打 help 而是进 REPL，而 REPL 又把输入喂回同一棵 Click 命令树，同一个错误在两种模式下退出行为不同。

comfyui harness：工作流软件的 harness 长什么样

CLI-Anything 的 comfyui harness 是我们精读的 12 个代表应用里非测试代码最少的一个，只有 1293 行：没有本地工程状态、不引用共享 REPL 皮肤、全靠 HTTP 打给一台已经在跑的实例。最反直觉的是，工作流软件的 harness 里，工作流那一组反而最小。

`core/` 与 `utils/` 的分工约定：这条线不是按「业务和工具」划的

CLI-Anything 的 harness 规范把 `core/` 和 `utils/` 都点了名，但真正的分界不是「重要的放 core、零碎的放 utils」。本文用四个样本 harness 的模块清单与行数对照，讲清这条线到底怎么划，以及那份「调用真实软件」的 backend 在依赖图上可以退到什么位置。

description 决定它会不会被触发：CLI-Anything 里 70 份 SKILL.md 的写法规律

解析 CLI-Anything 仓库（快照 39634a6）skills/ 下 70 份 SKILL.md 的 description 字段，看长度分布、开头三词频次、折叠标量比例，讲清只有 2/70 写成触发条件这处反差与生成器留下的截断痕迹，并给出想改这个字段该改哪一份文件的判定动作与可自行复现的核查清单。

SKILL.md frontmatter 字段全集：哪些必填

CLI-Anything 的 `skills/` 下 70 份 SKILL.md 共出现 17 个 frontmatter key，只有 `name` 与 `description` 是 70/70。本文给出字段全集与出现次数，说清「必填」由模板、生成指南与覆盖率三处约定，以及为什么没有任何脚本校验字段集合。

副本一致性：同一份 SKILL.md 在仓库里有几份

CLI-Anything 里一个 harness 的 SKILL.md 会同时落在仓库根 `skills/` 和包内两处，全仓 150 份。本文数清这 150 份的分布，说清 68 对副本里 43 对「字节不同」其实一个字都没差，以及真正有内容的差异藏在同步脚本扫不到的两份孤儿里。

一个 harness 的标准目录结构：四件套是哪四件

CLI-Anything 用一份 747 行的 HARNESS.md 规定了每个 harness 该长什么样。本文拆这棵目录树的每一层、说清四份文档分别写给谁看，并落到最容易记反的那一处：`cli_anything/` 目录被明令禁止放 `__init__.py`，而仓库里有 8 个目录放了。

kdenlive 与 freecad：剪辑与 CAD 的两种接法

同样是把桌面软件包成命令行，kdenlive 走的是「JSON 转 MLT XML 再交给 melt」，freecad 走的是「生成 Python 宏交给 FreeCADCmd 跑」。按源码行号拆两条链路的差别，落到最反直觉的一处：命令面接近 8 倍的 freecad，测试函数反而比 kdenlive 少 72 个。

`matrix_registry.json` 是什么：矩阵这层抽象干什么用

CLI-Anything 除了那张 79 条的 registry.json，还有一张只有 5 条的 matrix_registry.json（数字均为截至 2026-08-10 的仓库快照）。本文拆这张表的 15 个字段、5 条矩阵各引了哪些 CLI，并讲透它最反直觉的一处——注册表里专门有一个字段用来登记「这件事做不到」。

obs-studio harness：一个不启动 OBS 的直播场景操控面

CLI-Anything 里的 obs-studio harness 有一处和同仓其它 harness 都不一样：它的非测试代码里一处 subprocess、一处 HTTP 请求都没有，只读写场景集合 JSON。本文拆它的命令面、内置枚举、NaN 护栏与状态模型，并给出你可以自己复现的核对命令。

插件形态：装进 Claude Code 是怎么装的

CLI-Anything 的 Claude Code 插件目录 26 个文件 5865 行。本文拆清单，说清装进去不会多出一个能跑的工具，并落到四处对不上：`plugin.json` 缺 version、`verify-plugin.sh` 和 setup 脚本漏掉 `list.md`、HARNESS.md 位置两说。

`public_registry.json` 与 `registry.json` 差在哪

CLI-Anything 仓库根上并排放着两份 CLI 注册表，79 条和 22 条。本文把两份 JSON 的字段并集、来源口径与安装描述逐项摆开，并落到最容易踩的一处：public 那 22 条里，字段是稀疏的，有卸载命令的只有 5 条。

QGIS harness：地理信息这类专业软件怎么接

CLI-Anything 的 QGIS harness 是我们读过的 12 个代表应用里，唯一把宿主运行时直接 import 进自己 Python 进程的。本文落到 `utils/qgis_backend.py` 的具体行号，说清这条双通道怎么把前置条件从「装没装 QGIS」挪到「你用哪个解释器跑」。

其余宿主适配层各自对接谁

CLI-Anything 仓库根下并排着六个以 agent 宿主命名的适配目录，看着像同一件事的六份移植。本文逐个落到安装脚本的具体行，说清它们「装上」的含义分成复制快照、复制自身、只注册路径、上下文注入四类，以及为什么真正被移植的是路径而不是能力。

harness 怎么驱动宿主软件：四种方式与各自代价

同样一条 CLI-Anything 命令，最后可能是起子进程调二进制、调配套工具、发 HTTP 请求，也可能是连一个 MCP 服务器。本文按四个精读样本逐个落到 backend 文件与行号，说清各自要装什么、超时多久、失败长什么样，并拆开最反直觉的一处：backend 文件存在，不代表主命令路径真会调它。

同构度统计与缺件清单：哪些 harness 不齐

CLI-Anything 的 69 个 harness 看着高度同构，四件套全齐的却只有 51 个。本文把 25 项缺失逐一落到 18 个 harness 上点名，说清 sketch 为什么会被口径整排判红、被规范当范例的 browser 为什么缺 TEST.md，并给出可以自己跑一遍的核查命令与判定边界。

`registry.json` 的结构与那 79 条记录

把 CLI-Anything 仓库根目录的 registry.json 拆开看：顶层只有 meta 和 clis 两个键，clis 数组 79 条，15 个字段里只有 10 个是 79 条全覆盖的。三种 skill_md 取值分别指向哪里，字段缺失会让解析器在哪炸，以及为什么有一条记录不等于这软件你装上就能用。

生成、同步与校验：一个新 skill 是怎么来的

CLI-Anything 里的 SKILL.md 不是手写的，而是从 harness 目录生成、再同步到仓库根、最后由 CI 单向校验的一条流水线。本文拆开这三段各自的脚本、行号与判定规则，并说清最反直觉的那处：同步脚本自己制造了两份副本的差异，而校验只查一个方向。

让所有软件变得 agent-native：CLI-Anything 想解决什么

CLI-Anything 自述要「让所有软件变成 agent-native」，但它给出的答案不是一层通用协议，而是按软件逐个产出一份 CLI 加一份 SKILL.md。本文顺着这个选择讲清它想补的缺口在哪，并落到最容易误读的一处：`registry.json` 里的 79 条是供给侧计数，不等于 79 个装上就能用。文中最后还会讲清，「注册表登记」「仓库内有 harness 目录」「宿主软件已装」是三个各自独立的前提，不要混成一件事来判断。

skill 与 harness 是不是一一对应

CLI-Anything 仓库里 harness 目录 69 个、`skills/` 下的 `cli-anything-*` 包也是 69 个，看起来正好一一对应。本文把这两个 69 拆开：一个 harness 没有任何 SKILL.md，另一个 harness 出了两份 skill 包，两处偏差恰好抵消。

给 agent 读的那份 SKILL.md：字段与正文结构

CLI-Anything 每个 harness 都带一份 SKILL.md，是 agent 判断"这个 CLI 能干什么"的主要依据。本文按仓库快照拆开它的 frontmatter 字段、正文小节顺序，以及它是怎么被生成出来的——它不是运行时反射的结果，而是对源码文本做正则抽取再套模板，这一点决定了你该怎么读它。

`skills/` 目录清单与每个包的文件构成：70 个目录、70 个文件

CLI-Anything 的 skills/ 下有 70 个子目录，每个目录里恰好只有一个 SKILL.md，没有 scripts、没有 references、没有随包分发的脚本文件。本文数清这一层的目录清单与文件构成，说明这份「技能包」拿到手里等于什么，以及安装口径的两处不同写法。

`TEST.md` 与测试组织：它到底测了什么

CLI-Anything 规范要求每个 harness 的 tests/ 下放一份 TEST.md，我们采集时实到 57 份。它看着像测试报告，前半段其实是编码之前写的计划稿。本文拆它的两段结构，并落到最反直觉处：规范要求 E2E 必须调起真软件，而样本 harness 的 TEST.md 明写「不需要装宿主软件」。

安装策略与落点：cli-hub 会往你机器上写哪些目录

装一个 CLI-Anything harness，文件到底落在哪？本文按 installer.py 的行号拆开 cli-hub 的五种安装策略与默认推断规则，列全 ~/.cli-hub/ 下的账本、缓存与渲染产物，说清「安装记录」和「真实落点」为什么是两件事，并给出可自查的核对动作。

cli-hub 的矩阵机制与本地渲染：装完不等于能力齐了

cli-hub 的 matrix 层把一条工作流写成 capabilities × providers。本文拆 `matrix.py` 里 8 种 provider kind 为什么只有 2 种归 `matrix install` 管、capability 的「覆盖」怎么算，以及矩阵 skill 渲染的四级查找链。

meta-skill：给 agent 用的那层元技能

CLI-Anything 仓库里有一份不描述任何软件的 SKILL.md，只有 115 行，写给 agent 看的是「先 preflight 再装」和「别为一个能力整装一个 14-CLI 矩阵」。本文拆这份元技能的动作序列与退出码约定，并核对它第 85 行那句自我描述与 `installer.py` 的差异。

registry 的拉取与合并规则：117 行代码决定你看到多少条

cli-hub 的 registry 层只有 117 行，却同时管着两个远端清单、一份本地缓存和一个 `_source` 标记。本文拆它的拉取顺序、缓存回落条件与合并规则，说清 `_source` 为什么不只是显示字段，并给出你可以自己复现的核对命令。

cli-hub 做什么：从注册表到本机的那一段

cli-hub 是 CLI-Anything 的分发入口，把远端注册表里的条目装到你本机。本文按「拉表 → 合并 → 选策略 → 记账」四步拆这条链路，落到 installer.py 的五种安装策略与那个压根不装东西的 bundled，并说清「注册表有 79 条」为什么不等于「有 79 个能用」。

agents 层的划分：三块主线与 8 个子包

DeepTutor 的 agents 目录 docstring 自述分成 research / question / chat 三块，磁盘上却有 8 个子包。本文按文件数与行数把这一层数一遍，说清哪些是主线、哪些是渲染与辅助，以及为什么 agent 循环引擎根本不在这一层。

`AGENTS.md` 与 `SKILL.md` 是写给谁看的

DeepTutor 仓库根目录同时放着 AGENTS.md 和 SKILL.md，名字都带 agent，受众却不是同一批。本文按行号读这两份文件的定位差异，并列出它们与代码对不上的六处可核查差异，以及每一处该怎么自己核：例如默认 skill hub 在文档与代码里是两个名字、可开关工具数一处写 4 一处是 7。

DeepTutor 的 api 层：一个 FastAPI 实例、装配顺序与全部路由挂载点

DeepTutor 的 api 包有 40 个 py 文件、15796 行，但装配全部收在 main.py 一处。本文按行号读它的 app 构造参数、启动期漂移校验、lifespan 启停序列与全部路由挂载点，并给出把 322 这个数字自己数一遍的核查动作。

从早期版本到 1.5.11：`past_releases` 里的演进轨迹

DeepTutor 仓库里存着 65 份版本说明，其中 62 份在 assets/releases/past_releases 下。本文按文件名读这条演进线的形状，讲清版本号的单一来源与 CI 校验点，并指出 1.4.5 这个旧版本号至今还写在 pyproject 的依赖注释里、参与今天的 pip 解析。

`BaseAgent` 读一遍：模型解析优先级与两个 LLM 入口

DeepTutor 的 agents 目录顶层只有一个 769 行的 base_agent.py。本文按行号读它的四级模型解析优先级链、call_llm 与 stream_llm 两个入口，以及 response_format 那处会被静默跳过的能力检查。

book 模块怎么把一个知识库变成一本书：四段编译流水线读一遍

DeepTutor 的 book 目录有 58 个文件、7685 行 Python。本文按 engine.py 行号读它的四段生命周期、两道用户确认闸、单 worker 编译队列，以及那一页永远不走 LLM 的导览页；另说 24 个 API 路由与 3 条 CLI 子命令的落差，19 个块类型里 6 个未注册生成器。

book 的数据模型与章节结构：19 个 `BlockType` 与 13 个生成器

DeepTutor 的 book 模块把一本书拆成 Book / Spine / Chapter / Page / Block 五层对象。本文按 models.py 的行号读这套数据模型的字段、id 前缀与三个状态枚举，并讲清枚举里 19 个块类型对不上注册表里 13 个生成器这处差异。

capabilities 层：能力注册协议与五个能力的工具

DeepTutor 的 capabilities 目录里「能力」有两层不同含义，两个注册表一个 5 项一个 7 项。本文按行号读 LoopCapability 协议的六个成员、只加不减的工具面约定与它唯一的例外，以及五个能力各自拥有的工具。

`chat` 的 agent loop：一轮里发生了什么，工具是怎么挂上去的

DeepTutor 的一次 chat 对话不是「先探索再作答」两段式，而是一个循环。本文按行号读 agent_loop.py 的轮次判定、exploration+4 的真实轮数上限、四步工具组合顺序，以及那条针对文本格式工具调用的回退路径。

`chat` 的交互模式：一次对话里发生了什么

DeepTutor CLI 的 chat 是一个 REPL。本文按行号读它的入口注册方式、输入怎么被读进来、斜杠命令里那处「替换」而非「追加」的语义、工具输出的截断与 /show 环形缓冲，以及 README 与代码对不上的两处命令表；所有结论均可按文中行号回仓库自行核对。

重试与超时常量：请求失败之后它会怎么退

DeepTutor 的重试逻辑不在一个地方。全局 settings 给了 max_retries=8、base_delay=5.0，provider 基类另有一组 (1, 2, 4)，还有一个带熔断的子包在生产代码里没人引用。本文按文件行号把三层拆开，并把散在各模块的超时常量归到一张表里。

DeepTutor CLI 的命令树一次看完：命令组到底有几个，取决于你怎么数

DeepTutor 的命令行入口在 deeptutor_cli/ 下的 20 个文件里。本文按 main.py 的行号把命令组挂载表、四个顶层命令读一遍，并说清「命令有多少个」这个问题为什么会得出好几个不同的数字，以及 README 漏记了哪几组。

`co_writer` 的协作写作机制：623 行的包，与不在包里的那半套

我们 2026-08-10 采集的快照里，DeepTutor 的 co_writer 目录只有两个 Python 文件共 623 行，对应的 API 路由却有 618 行。本文按文件与行号读 EditAgent 的三种改写动作、gather_context 的静默降级、auto_mark 的标注配额，以及那半套实现在路由层而不在包里的选区 ReAct 编辑。

五个 compose 文件各自干什么，别拿错那一份

DeepTutor 仓库根目录躺着五个 compose 文件，名字长得像但服务数、目标运行时和挂载策略都不一样。本文按行数与服务清单逐份读它们的分工，讲清两份主文件为什么要求用脚本启动，以及哪两份根本不能单独用，并给出五个文件的行数与服务数对照表，以及可自己复现的核对动作。

`init` 向导每一步在问什么，答错了会怎样

DeepTutor 的 deeptutor init 是一个交互式向导，代码里 cli_only 走四步、完整模式走五步。本文按 init_cmd.py 与 init_wizard.py 的行号拆开每一步问什么、默认值是多少，以及跳过、选 none、探测失败、不确认保存各自会落到什么结果上。

间隔重复调度器：复习时间是按什么排的

DeepTutor 的 scheduler.py 只有 101 行，却决定了每个知识点下次什么时候再出现。本文按行号读它的四条间隔序列、答对答错时 interval_index 的不对称推进、复习队列的排序键，以及那个把一天变成一秒的调试开关。

鉴权机制：谁能调、怎么校验

DeepTutor 的鉴权分成总开关、令牌校验、路由闸门三层，最反直觉的一处是 require_auth 必须写成 async def，否则身份 ContextVar 会在工作线程里丢掉。本文按行号读这条链，说明 WebSocket 侧为何要另起一套鉴权，并给出可自查的核对动作。

文档解析引擎支持哪些格式，各走哪条路

DeepTutor 的 parsing 层用一张注册表挂了五个解析引擎。本文按行号读这五个引擎名常量定义在哪一行、分别一一对应哪五个类、为什么注册表里有名字不等于这条路在你机器上能跑通，新装默认走的是哪一条，以及 MinerU 那条支路上的云端模式与模型权重下载枚举各自意味着什么。

知识库存到哪里，名字为什么会被拒

DeepTutor 建知识库时名字被拒，多半是撞上了 naming.py 里那三行常量。本文按行号读四条校验规则、KB 目录的固定布局与平铺的 version-N 版本目录，以及 resolve_kb_dir() 为什么规定谁都不许自己拼路径、遗留目录为什么把状态改写成 needs_reindex。

`kb` 知识库命令：建、灌、查、删

截至 2026-08-10 我们采集时，DeepTutor CLI 的 kb 组有七个子命令，都在 deeptutor_cli/kb.py 这 286 行里。本文按行号读 create 为什么不能建空库、add 的去重开关、search 的默认 mode，以及知识库落在哪个目录下。

知识库的类型模型与 `manifest` 清单：一个拒绝回答「索引了几篇」的模块

DeepTutor 的知识库分默认 indexed 与五种 connected 指针型，`kb_types.py` 用一个 frozenset 决定谁跳过索引流水线。本文按行号读这套类型模型，以及 manifest.py 里那个显式声明「故意不报告进索引文档数」的设计与它给出的三条理由。

LLM 接入层：统一调用口与代码里出现的 provider 名单

DeepTutor 把 provider 元数据收在一个文件里，36 个名字最后只落到 5 种后端实现。本文按行号读 provider_registry.py 的 ProviderSpec 字段与 provider_factory 的分发、实例池，以及能力表对不齐、两套 provider 抽象并存这两处可核查的差异。

三层记忆：`memory` 目录的分层与落盘

DeepTutor 的 L1/L2/L3 记忆不是三个抽象概念，而是两条 Literal 类型和一组固定目录。本文按文件与行号读它的分层边界、落盘位置、两个记忆工具截然不同的挂载规则、清理命令按源码只删哪几处目录，以及「memory」这个词在仓库里指的三种不同东西。

多用户隔离与 `grant` 授权机制：四棵目录树和一个三态字段

DeepTutor 的 multi_user 包只有 14 个文件 2031 行，却把「谁能用什么」这件事拆成了目录隔离与 grant 授权两层。本文按行号读它的四棵数据树、grant v2 的字段清单、同一个 None 在不同资源上正好相反的语义，以及仓库自己写明的两处能力边界。

`skills/builtin`：内置技能的加载与注册

DeepTutor 内置技能只有五个目录、每个目录只有一份 SKILL.md。本文按行号读 skill/service.py 的 frontmatter 字段、user 遮蔽 builtin 的扫描顺序、一行清单与 always 整篇注入两条装载路径，以及 requires 那道会去查 PATH 与沙箱的可用性门。

判分与错误分类：答错之后系统认为你错在哪

DeepTutor 的判分只有 64 行代码，三种题型三条规则，错误分类只分两类。本文按行号读 grading.py 的判对边界、fail-closed 兜底、classify_error 的粗分类，以及答错之后 service 层那条固定流水线会牵动哪些状态。

partners 是一层 IM 渠道：它接到了哪些地方

截至 2026-08-10 快照，DeepTutor 的 deeptutor/partners 有 30 个 py 文件、12252 行，但包里并没有一个 partner 引擎。本文按行号读它的 16 个渠道模块、pkgutil 零导入的发现机制、allow_from 为空即全部拒绝的访问控制，以及 README 渠道清单与代码对不上的两处差异。

配置写到哪里去了：路径常量与读取优先级

DeepTutor 的配置落点由 get_runtime_home() 的三级优先级决定，最后一级兜底是当前工作目录。本文按行号读这条链，以及 data/user/settings 下各文件由谁创建、init --home 为什么要重置三个单例、容器里为什么又换了一套读取顺序。

`provider` 命令能配哪些字段：答案是一个都不配

DeepTutor CLI 有一个 provider 命令组，很多人以为 base_url、api_key、model 是在这里填的。按行号读完 provider_cmd.py 才会发现，这个组只有一个 login 命令、只认两个取值，真正的字段全部由 init 向导采集并落进 model_catalog.json。

切块与检索参数：这些数字写在哪一行

DeepTutor 的 chunk_size、chunk_overlap、top_k 这几个数字并不散落在各处，而是集中写在 runtime_settings.py 的两段里。本文按行号读默认值与夹取范围，讲清哪个参数被故意不暴露、改了为什么不追溯，以及同名 top_k 三个引擎三个默认值、第四个干脆没有。

question pipeline：出题这条线的阶段与判分

DeepTutor 的出题走的是一个 2161 行的 QuestionPipeline，三阶段 Explore→Plan→Quiz。本文按行号读它的标签协议、预算常量、探索阶段那次额外的摘要调用，以及 ask_user 被挂载却在这条线上没有恢复通路的那处设计。

rag 检索管线：52 个文件拆成了几段

DeepTutor 的 services/rag 是 7539 行 52 个文件的一层。本文按 rag/factory.py 的行号读它的六个管线常量、按名字懒 import 的分发、(kb_base_dir, provider) 缓存键，以及那处「配错名字不报错、直接落回默认管线」的设计。

2871 行的 research pipeline：阶段流怎么走

DeepTutor 的 research/pipeline.py 是 agents 目录里最大的一个文件，2871 行。本文按行号与常量读它的四阶段划分、八个标签词的两种用法、动态主题队列的三个默认上限、工具结果进报告前的两道削减，以及第三阶段为什么不是一趟走完的直线。

`SectionArchitect` 与 `SpineSynthesizer`：目录是被规划出来的

DeepTutor 的 book 模块里，章节目录和每页的块序列不是模型一次吐出来就完事。本文按行号读 SpineSynthesizer 的 Draft-Critique-Revise 循环与三步确定性后处理、SectionArchitect 的 LLM 层与静态模板层，以及那处失败即回落静态模板的分支。

65456 行的 services 层：26 个子领域怎么分工

DeepTutor 体量最大的一层是 services，占全包 Python 代码的四成多。本文按实读的行数分布、根目录七个文件、懒加载 __init__ 与跨层引用计数，讲清这 26 个子领域各管什么，以及它为什么不是依赖图最底下那一层。

`session` / `notebook` / `book` / `memory`：DeepTutor CLI 这四组命令各管什么

DeepTutor CLI 的这四个命令组加起来只有 382 行、16 个子命令，但完整度完全不在一个层级上。本文按文件行号读它们的子命令、默认值与落盘动作，重点讲 book 组那处「有命令组不等于能在 CLI 上做完」的反直觉设计，顺带说明为什么 README 里查不到 book 组。

DeepTutor 是什么：把「终身个性化辅导」拆成能跑起来的模块

DeepTutor 的自述是 Lifelong Personalized Tutoring，但这句定位说不清它到底是个什么形态的软件。本文按仓库快照把它拆成可核查的几块：版本号写在哪一行、能力清单在哪个文件里列、它会在你本机执行哪些东西，以及容器注释自己写明的那条信任边界。

四条安装路径怎么选：从 pip 到 compose

DeepTutor 的 README 明写「ships four installation paths」，但四条路的前置条件、发布状态与运行形态差别很大。本文按 README 与 pyproject 的原文逐条拆开，并把 CLI-only 那条路上四处口径不一致的位置标出来，给出一条能自己核的选择路径。

`skill` 与 `skill_login` 不是一回事

DeepTutor CLI 目录里 skill.py 和 skill_login.py 并排放着，看名字像两个命令模块，实际上后者一个命令都没注册。本文按行号读清这两个文件的分工、loopback OAuth 的两个纯函数与一段带副作用的流程，以及那条把登录令牌排在最后的取值优先级。

subagent 与 cli_apps：它会去驱动你本机的 agent CLI

DeepTutor 的 services 层里有两个目录不在服务端算东西，而是去启动你本机的外部程序：subagent 驱动已装的 agent CLI，cli_apps 安装并调用命令行工具。本文按行号读它们的后端注册表、探测规则、几组超时常量，以及那份写着"不要手改"的生成快照。

提示词为什么放在几十个 yaml 里而不是写死在代码中

DeepTutor 的 agents 目录里有 38 个提示词 yaml、en 与 zh 各 19 份，路径靠目录约定解析，加载失败只把 prompts 置为 None 并打一条 warning、不抛异常。本文按行号读这套约定的解析路径、语言回退链、运行时分块拼装，以及那份定义了却没有第二处引用的模块名列表。

两个前端目录是什么关系，技术栈各是什么

DeepTutor 仓库里有 deeptutor_web/ 和 web/ 两个看起来都像前端的目录，源码检出下前者只有一个 __init__.py。本文按行号读 launcher 的目录解析逻辑、web/ 的 package.json 与 next.config.js，以及前端连后端的那层 middleware。

Python 版本与依赖分组：`requirements/` 下每个文件管什么

DeepTutor 的 pyproject 把 Python 钉在 >=3.11,<3.14，定义了 15 个 optional-dependencies 分组，而 requirements/ 下只有 7 个文件。本文按行号读版本区间的理由、七个文件各自的条目数与引用关系，以及 8 个 extra 没有镜像文件。

硬编码默认值逐个看：DeepTutor 里哪些值你改不到

DeepTutor 的 services 层散着一批写在模块里的默认值。本文按行号分三类看：配置层能改的、只写在常量里的、以及你设了也会被按模型前缀改写的那一类——`gpt-5`、`o1`、`o3` 命中的强制温度 1.0 就属于最后这类。同时说明哪些常量自带环境变量开关，并给出可在自己 clone 上复跑的检索动作。

掌握度是怎么算出来的：`mastery.py` 与 `policy.py` 的闸门

DeepTutor 的 learning 层把「学没学会」压进了两个文件：40 行的 mastery.py 负责算分，295 行的 policy.py 负责判闸门。本文按行号读它的近因权重、置信封顶与 0.9 定量闸门，并把两者拼起来算给你看——为什么窗口里只要有一次答错就过不了闸。

16 种工具、16 个落点：一张表搞清装到哪去了

agency-agents 的 16 种工具各有各的落点，有的写进家目录，有的写进当前项目目录，有的把整份花名册合并成一个文件，还有一个压根不能按 agent 渲染。这篇把 tools.json 与 install.sh 注释里的落点整理成一张表，讲清 per-agent、roster、plugin 三种安装机制的区别，并给出先 dry-run 再落盘的完整命令写法、装完要检查哪几处、以及哪些场景不该整包装。文中事实均以 2026-08-09 的仓库源码与脚本注释口径为准。

`--parallel` 与 `--jobs`：多工具安装的并行控制

agency-agents 的 install.sh 提供了 --parallel 与 --jobs 两个开关，用来同时往多个 AI 编码工具的配置目录里铺 agent 文件。这篇从并行到底并行的是什么讲起，给出可直接复制的命令组合、产出物会落在哪些目录、装完人工要检查哪几处，以及哪几种情况下并行反而会让你更难定位问题、不如老老实实串行跑一遍。

把 agency-agents 装进 Claude Code：从 convert 到 install 的完整链路

agency-agents 进 Claude Code 只有两段：convert.sh 渲染产物，install.sh 拷进 .claude/agents。按脚本 USAGE 与 tools.json 契约讲清选择器、--dry-run、--link 怎么组合，Windows 走 Git Bash 还是 WSL，落盘后验收看哪三处。

Codex 的 TOML 转换：为什么正文要走 basic string

agency-agents 把 agent markdown 转成 Codex 能读的 TOML 时，只写 name、description、developer_instructions 三个字段，而正文一定要经过 TOML basic string 编码。本文按仓库源码讲清这条链路怎么跑：完整命令与每个选项的作用、产物落在哪个目录、装完人要检查哪几处、以及哪些场景根本不该这么装。

明明开头就是三个横杠，为什么报 missing frontmatter

在 agency-agents 里写或改一个 agent markdown，文件第一行明明就是三个横杠，校验却说 frontmatter 不存在。本文按现象、怎么确认、源码语义给出的处置、处置后怎么验证、什么情况不是这个原因五步，讲清 CRLF 行尾引起的误导性报错，给出可执行的单文件校验判定动作，并列出同样指向 frontmatter 却与行尾无关的几种根因，帮 Windows 侧读者少绕弯路。

Cursor 里装完没反应？看一眼 `alwaysApply: false`

把 agency-agents 装进 Cursor 后规则像没生效，多半不是脚本失败，而是 convert.sh 的 cursor-mdc 模板把 alwaysApply 写死为 false、globs 写死为空串。本文按现象、判定动作、源码语义、验证、排除五步给出排查路径，并列出五种说明另有原因的情况。

一份 JSON 管住五个脚本：单一真相源是怎么落地的

agency-agents 用 divisions.json 与 tools.json 当作目录和工具的唯一真相源，再用五个校验脚本把不一致直接变成构建失败。本文拆开这套机制：五个脚本各守什么、为什么原创性检查要去读 JSON 而不是在脚本里硬编码一份拷贝、installKind 与 format 这类契约字段为什么必须写进 JSON，以及新增一个 division 时官方给的四步顺序。给的是判断依据，你可以照着评估自己仓库里的配置有没有真正收敛。

`check-divisions.sh` 失败：四个地方要同步改

在 agency-agents 里新增或改名一个 division 目录后，check-divisions.sh 会让构建失败。这篇按「现象→判定→处置→验证→排除」五步走一遍：先确认失败是否真的来自 division 列表漂移，再照 divisions.json 里 _note 给的顺序把磁盘目录、convert.sh、lint-agents.sh、CI 工作流四处对齐，最后给出哪些报错其实归其它脚本管。

17 个 division 与那四个「不是 division」的目录

agency-agents 仓库根目录下摊着二十来个文件夹，但只有 17 个算 division，另外四个是转换产物、方法论文档、示例和脚本。这篇讲清楚 divisions.json 与 check-divisions.sh 认定 division 的机械标准是什么、255 个 agent 在 17 个 division 里怎么分布得极不均匀、为什么按目录整体拷贝在 engineering 这种大 division 上是钝器，以及要按题材找 agent 时该回哪份文件查，而不是照着目录名猜。

往 `~/.claude/agents/` 写 200 多个文件之前，先跑 `--dry-run`

agency-agents 花名册有 255 个 agent、17 个 division，安装脚本支持 16 种工具，多数是一个 agent 一个文件；裸调用 install.sh 等于全装。这篇讲 --dry-run 的命令怎么写、每个选项为什么在那里、计划打出来后人要盯哪几处、哪些场景它兜不住底。

同名 format 保证字节级相同输出：一条被写进注释的契约

agency-agents 的 tools.json 用 _note 写死一条约定：同一 format 名必须渲染出字节级相同的输出。本文拆开 format 与 installKind 两个正交维度，说明 Claude Code 与 GitHub Copilot 为何共用 identity，排查转换问题时该查几份内容。

agency-agents 的 agent 文件格式：name/description/color 是必填，emoji/vibe 不是

写或改一个 agency-agents 的 agent markdown，到底哪几个 frontmatter 字段是硬要求？本文从仓库 lint 脚本的必填字段列表出发，讲清 name、description、color 这三项为什么是 ERROR 级，emoji 与 vibe 为什么只是可选，字段值又分别被哪些转换器消费，顺带说明为什么你给正文起的章节标题其实是一条路由规则，原创性检查的两个默认阈值该怎么读，以及这套检查脚本管得到什么、管不到什么。

12 个环境变量：不想装进默认目录时改哪里

agency-agents 的 install.sh 默认写进 ~/.claude/agents/ 这类家目录，而 opencode、Cursor、Aider、Windsurf 写的是当前目录。本文梳理 12 个可覆盖落点的环境变量各管哪些工具、剩下 5 个只能靠 --path，以及怎么先 --dry-run 看计划。

per-agent、roster、plugin：三种安装机制决定了你能不能只装一个

agency-agents 的 tools.json 给 16 种工具各标了一个 installKind，它决定的不是装到哪，而是产物形态：per-agent 一 agent 一文件，roster 合并成一个文件，plugin 只能走命令行。本文讲清三者的判断依据、format 的字节级契约，以及家目录与当前目录的落点差异。

integrations/ 缺失或过期时到底发生了什么

agency-agents 的 integrations/ 是 convert.sh 写出的产物目录而不是源目录。本文梳理产物缺失或过期的表象、用 --dry-run 与 --list 不落盘确认的办法、脚本给出的处置与复核方式，以及哪些其实是 installKind、目录 scope 或 CRLF 导致的另一类问题。

交接文档、QA 失败反馈、升级报告：三个模板的用法

agency-agents 的 NEXUS 编排文档里放了三个协同模板——交接文档、QA 失败反馈、升级报告。这篇讲清楚它们分别在哪个环节触发、怎么落到自己的项目目录里、为什么必须写 agent 的 slug 而不是显示名，以及怎么做一次可执行的验收检查；同时说明它们不会被安装脚本装进任何工具，也没有代码会强制执行。

`--link` 符号链接模式：改动自动传播的好处与代价

agency-agents 的 install.sh 提供了 --link 开关，用符号链接代替拷贝，改动会自动传播。本文按仓库源码口径讲清它在 convert → install 这条链路的哪一段生效、命令该怎么组合、三种 installKind 下产出物形态有什么差别、装完要检查哪几处，以及哪些场景不该用它。

lint 报了一屏：哪些必须修，哪些可以先放着

写完一个 agency-agents 的 agent markdown，跑一遍仓库自带的 lint 脚本，输出里 ERROR 和 WARN 常常混在一起，让人不知道该先动哪一条、哪一条可以留到下次。这篇按 scripts/lint-agents.sh 的源码把五道检查逐条拆成阻塞项和建议项，指出其中哪一条 WARN 会直接影响转换产物的分流、应当按硬伤处理，并给出修完之后还要补跑哪几个一致性脚本，以及哪些症状其实跟校验完全无关、不该在这里浪费时间。

那段激活提示词逐句拆解：它到底在要求模型做什么

agency-agents 的 QUICKSTART.md 里给了一段 NEXUS-Full 激活提示词，很多人整段复制粘贴却说不清它在要求模型做什么。本文把这段提示词按行拆开，逐句对上仓库里的模式定义、七个阶段 playbook 与花名册 slug，给出激活前的准备命令、四个可执行的验收动作，以及哪些场景根本不该用这一段。

Phase 0 到 Phase 6：七个阶段的分工与产出

agency-agents 仓库的 strategy 目录里放着一套叫 NEXUS 的多 agent 编排方法论，把项目拆成 Phase 0 到 Phase 6 七个阶段，每个阶段有对应的 playbook 文档和参与角色。这篇按官方文档口径拆解七个阶段各自的分工、进场角色、交接契约与质量门设计，说清它是写在 markdown 里的方法论而非可执行调度器，并给出三种激活模式的选择依据，帮你判断自己的项目该保留哪几个阶段、哪几个可以直接砍掉。

Full、Sprint、Micro：三种模式各自适合什么活

agency-agents 的 NEXUS 给了 Full、Sprint、Micro 三种激活模式。这篇不复述文档表格，而是从交付物形态、官方四个 runbook 的模式归属、roster 的分组激活结构三个角度，给出能自己套用的判断依据：什么时候往上走一档，什么时候往下退一档，以及为什么大多数活落不到 Full。

NEXUS 是什么：写在 markdown 里的多 agent 编排方法论

agency-agents 的 strategy/ 目录里没有一个可安装的 agent，放的是一套叫 NEXUS 的多 agent 编排方法论。本文讲清它的全称、三种激活模式、七个阶段与四个场景 runbook 各自对应仓库里的哪些文件，以及它靠什么生效、又约束不了你什么。

255 个 agent 全装进全局目录，代价是什么

裸跑 agency-agents 的 install.sh，按脚本 USAGE 的说法就是把所有 team 装到所有检测到的工具，而仓库里带 frontmatter 的 agent 共有 255 个。本文按排查顺序讲清楚：怎么用 --dry-run 和 --list 在落盘前确认产物数量与目标目录，怎么按 tools.json 里的 installKind 判断产物形态，怎么用选择器把安装范围收窄，以及哪些症状其实和装多装少完全无关。

事故响应 runbook：为什么「修完」之后还有一组人

agency-agents 的 runbooks.json 里，只有 incident-response 走 NEXUS-Micro。它最值得看的是修完之后还单独挂着一组 post-fix agent：取证、接口回测、流程优化、重排优先级。本文讲这份名单怎么落到 install.sh 参数里、装完验收哪几处。

runbook 里的 slug 解析不到 agent 文件时怎么查

agency-agents 的 runbook 用 slug 引用 agent，而 slug 是 agent markdown 的文件名主干，既不等于显示名，也不保证带 division 前缀。本文按现象、判定动作、源码语义给出的处置、处置后怎么验证、什么情况说明不是这个原因五步，讲清 slug 解析不到文件时该从哪里下手，并列出几种看着像 slug 写错、实际是安装形态或目录 scope 造成的情形。

Startup MVP runbook：9 个常驻 agent 加两组按需

agency-agents 的 startup-mvp runbook 把一个 MVP 团队写成 18 个 slug：9 个常驻、3 个第三周起加入、6 个按需。本文把这份名单落成 agents-file，给出 install.sh 的完整命令、--dry-run 的用法、产出物落点与验收要点，以及什么情况下别照它装。

agency-agents 到底是什么：255 个 agent 的目录，不是一个框架

agency-agents 常被当成一套多智能体框架，实际上它是 255 个带 YAML frontmatter 的 agent markdown 文件加一组 shell 脚本组成的目录，本身没有运行时。本文按仓库源码口径讲清单个 agent 文件的三层结构、17 个 division 的划分规则、哪些顶层目录根本不是 division、convert 与 install 两步流水线，以及 per-agent、roster、plugin 三种安装形态的差别，帮你判断这个仓库要不要进自己的工作流、又该怎么收窄安装范围。

为什么 runbook 引用 slug 而不是显示名

agency-agents 的 runbooks.json 里，一个团队是由 engineering-frontend-developer 这样的 slug 拼出来的，而不是花名册里显示的 Frontend Developer。这篇讲清楚 slug 到底指什么、为什么显示名当不了引用键、check-runbooks.sh 守的是哪条边界，并用花名册里五组 slug 与显示名的真实对照说明这层映射为什么推不出来，最后给出一套判断标准：你自己项目里的跨文件引用，什么时候该写稳定 id，什么时候可以直接写名字。

`check-tools.sh` 失败：加一个工具要动三处

agency-agents 仓库里给花名册新增一种目标工具时，最容易挂在 check-tools.sh 这道校验上。这篇按「现象→判定→处置→验证→排除」五步拆开：这个脚本到底守 tools.json 与 install.sh、convert.sh 之间的哪些一致性，六个必填字段各是什么含义，format 的字节级契约和三种 installKind 怎么选，以及哪些失败其实归 lint-agents.sh、check-divisions.sh 管，不该往这里找原因。

一个 agent 文件长什么样：frontmatter、角色声明、分节正文

agency-agents 仓库里的 agent 全是同一套 markdown 模板，三层结构固定，看懂一个等于看懂两百多个。这篇按仓库校验脚本的源码讲清楚 frontmatter 必填哪三个字段、哪些只是可选、正文为什么要写成第二人称，以及最反直觉的一条：你给章节起的标题不只是排版，它决定这段内容被转换进 SOUL.md 还是 AGENTS.md，写模板之前就得照着这条路由规则起名，否则落点全错。

Windows 上怎么装：Git Bash、WSL 与 bash 3.2 的门槛

agency-agents 是一套 shell 脚本驱动的 agent 分发工具，Windows 用户第一步就会卡在「用什么终端跑」这个问题上。这篇按仓库脚本注释与 tools.json 的原文，梳理 Git Bash 与 WSL 到底该选哪个、判断依据为什么是安装落点、bash 3.2 这条版本下限怎么自查、先用 dry-run 看计划再落盘的完整命令该怎么写、行尾换行符这个 Windows 专属的坑，以及装完之后人要检查哪几处、什么情况下压根不该这么装。

agency-agents 安装选择器实战：--tool/--division/--agent/--agents-file 怎么组合

agency-agents 的 install.sh 裸调用会把整个花名册装进所有检测到的工具，多数人并不想要这个结果。这篇按官方 USAGE 段的参数语义，拆开 --tool、--division、--agent、--agents-file 四个选择器各自管什么，给出四种常见处境下可直接复制的完整命令，说明产出物会落在哪些目录、怎么用 --dry-run 和 --list 验收，以及 roster、plugin 两类工具为什么在目标端看不到一 agent 一份产物。

换个国家名就想混过去？8 词 shingle 重叠率不答应

把已有 agent 换个国家名或平台名提交上来，评审几乎看不出来。agency-agents 的 check-agent-originality.sh 用实体中性化后的 8 词 shingle 重叠率来抓这种换皮，默认 40 判失败、20 出警告，而源码注释给出的库内校准值是最差约 1.5%、中位数 0%。这篇拆开这套机制的判断依据：三组数字放在一起该怎么读、指定文件与全库审计两种模式分别用在哪、退出码 1 和 2 为什么必须分清，以及它和 lint 加起来仍然管不到的那部分。

给 agent 章节起标题其实是在写路由：agency-agents 的 SOUL.md / AGENTS.md 分流机制

在 agency-agents 里，agent markdown 的二级标题决定这段正文被转换到 OpenClaw 工作区的 SOUL.md 还是 AGENTS.md。本文按 lint-agents.sh 的 classify_header_target() 源码讲清六个命中关键词、默认落点，以及自己写 agent 时该怎么定标题。

agency-agents 排查：body seems very short，50 词这条线是怎么来的

agency-agents 的 lint-agents.sh 会对正文不足 50 词的 agent markdown 报一条 body seems very short 警告，可你的文件明明写了好几屏。这篇讲清这条线出自脚本第 4 步的取正文与词数统计，给出可执行的判定动作与处置，并说明它为何常与另外几条 WARN 结伴。

每个阶段之间都有质量门，所有评估都要有证据

agency-agents 的 NEXUS 激活提示词末尾有两句约束——阶段之间设质量门、所有评估都要有证据。这两句在仓库里分成两层落点：一层写在 markdown 方法论里靠模型自觉，另一层是 shell 脚本，跑起来真会让检查失败。本文拆开两层各自守什么，并给出判断依据：哪些门该写成脚本，哪些只能写成清单。

Codex CLI 用 `--add-dir` 让 agent 同时读写两个目录

代码在一个目录、产物要落到另一个目录，是 Codex CLI 日常最常见的跨目录需求。本文按命令怎么写、产出物落在哪、怎么验收、什么时候别这么干四段，讲清 --add-dir 与 -C 的分工、writable_roots 的配置写法，以及 Windows 沙箱下容易踩的坑。

Codex 的 AGENTS.md 该写什么、写多长、放在哪一层

AGENTS.md 是 Codex 读项目自定义指令的入口，但真正决定它「能不能被读到、能读多少」的是 config.toml 里的几个键。本文讲清控制项目文档读取的几个配置键，给出可直接改的配置块、验收要检查的四个位置，以及哪些约束根本不该写进 AGENTS.md。

Codex 审批策略拆解：三档字符串与五个细粒度开关怎么选

Codex CLI 的 approval_policy 既能写成 untrusted/on-request/never 三档字符串，也能写成带五个开关的表。这篇讲清两种写法各自能做到什么、never 为什么不等于放开权限、五个细粒度开关关掉之后到底是自动拒绝还是自动放行（哪些官方写了、哪些没写），以及怎么用 codex doctor 确认当前真正生效的是哪一档。文中给出可直接复制的 TOML 片段与命令行覆盖写法，并说明受管配置为什么会盖掉你本地的改动。

Codex CLI 有的功能桌面应用没有：两个面的版本不一致怎么查

终端里能用的能力，换到桌面应用就找不到，多数人第一反应是自己漏开了开关。官方排查页把这类现象归到「两个面的 Codex 版本不同」。本文给出可直接执行的判定命令、版本号会自己变化的一手实测、处置后如何验证，以及哪几种情况其实和版本无关，别一条道走到黑。

版本号自己变了：Codex CLI 自动更新与版本口径排查

昨天 codex --version 还是一个号，今天再敲就变了；文档里写的选项在你机器上找不到，特性阶段也和别人对不上。这篇按现象、判定命令、处置、验证、排除五步走，讲清楚 Codex CLI 的版本从哪来、该以什么为准、doctor 的哪几行能一眼看出装在哪、以及哪些症状其实和版本无关。

本地跑还是云端跑：Codex 选型先看模型可用性

决定 Codex 该在本地跑还是丢到云端跑，别从「哪个更强」入手。这篇按模型可用性、谁来改文件、有没有管理员权限、预算与会话同步五个岔口，把官方文档里的硬约束串成一条可以照着走的决策路径，并说明每一步判错之后会以什么形式反噬你。

Codex CLI 的 `-c` 到底覆盖了什么：四条规则与一次配置加载失败的实测

Codex CLI 的 -c 选项能在不改 config.toml 的前提下临时覆盖配置，但它的行为由四条规则叠加而成：覆盖用户配置、点号表示嵌套、值按 TOML 解析、解析失败则回落成字面字符串。最后一条最容易被读成「怎么写都不会报错」。本文用本机只读命令的实测输出，说明写错时错误会被推迟到哪一步、怎么用 doctor 一眼看出来，以及 --strict-config 拦不住什么。

侧栏冒出不是 Codex 改的文件？先把 diff 面板切到 Last turn 视图

用 Codex 改代码时，diff 面板里冒出一堆跟本轮任务无关的文件，很容易被误判成 AI 乱动了你的代码。官方给的原因是项目在 Git 仓库里、面板展示的是全部 Git 状态变更，做法是切到 Last turn 视图。本文给出判定命令、处置后的验证步骤，以及五种说明不是这个原因的情况。

在 CI 里跑 `codex exec`：非仓库、免配置与超时这三件事

把 Codex CLI 塞进流水线，绕不开三个坑：工作目录不是 Git 仓库会被拦、runner 上没有你本机那份 config.toml、以及跑到一半没人知道该等多久。本文按官方选项与配置键给出可直接复制的完整命令、产出物落点、验收检查项，以及哪些活儿根本不该交给非交互模式。

`~/.codex` 悄悄吃掉几个 GB：rollout 会话与 SQLite 日志的磁盘占用排查

系统盘越用越紧，别忘了翻一眼 Codex 的家目录。本文按排查顺序讲清怎么用 codex doctor 判定占用大头在 rollout 会话还是 SQLite 日志库，官方文档与本机只读命令给出的处置分别有哪些，改完怎么验证，以及哪些迹象说明磁盘满根本不是 Codex 的锅。

`codex doctor` 里那行 ✗ config 是什么意思：配置加载失败的判定与处置

改完 config.toml 却发现设置没生效，多数人第一反应是去翻文档找键名，其实应该先跑一次 doctor。本文讲清 doctor 输出里 config 那一行的四种状态符号各代表什么、配置加载失败时它会打出哪句原话、怎么分层定位是基础配置还是命令行覆盖出的问题、处置后如何确认修好，以及哪些情况说明问题根本不在配置加载这一环。

Codex `config.toml` 全景：它在哪、有几层、该先改哪几个键

Codex CLI 的配置项多到一屏放不下，新手最常见的问题不是「怎么写」而是「改哪个、改在哪一层、改完为什么没生效」。本文按官方 Configuration Reference 梳理配置文件的位置与叠加关系，给出四组优先该动的键，拆解三个名字容易理解反的开关，并附上本机 0.147.0 实测的两条验证路径。

Codex 订阅档位怎么选：先搞懂 5 小时窗口与消息数口径

选 Codex 订阅档位时，最容易被忽略的不是价格数字，而是官方的用量口径——计量单位是消息数不是 token，窗口是 5 小时滚动窗口，同一档位内的区间跨度还随模型变化。这篇按「要不要跑云端、按订阅还是按 token、预算多少、是不是团队」四个岔口给出决策路径，并说明 sol 与 luna 之间 25 倍的积分单价差距对「要不要上云」这个决定意味着什么。

Codex 接第三方模型怎么选：`model_providers` 与 `wire_api` 只支持 responses 这一关

想让 Codex 用自己的模型端点，很多人直接抄 model_providers 配置，结果卡在协议上。这篇按你的处境倒推该走哪条路：公司发席位、自己按 token 付费、要接自定义端点、还是本地跑；讲清 wire_api 默认且只支持 responses 意味着什么，以及配好之后用 doctor 的哪几行验收。

第一次用 Codex CLI：先把这五件事定下来

装完 Codex CLI 就直接敲第一句话，多半会在权限、模型、登录方式上返工。这篇按顺序讲清第一次使用前该定下来的五件事：确认你在用哪一个 codex、选登录方式、选沙箱模式、选审批策略、选模型，每一步都说明为什么这么做、做错了会在哪一环出问题，并给出可直接执行的只读检查命令。

看懂 `codex doctor` 的每一行：六个分组逐条读法与排查判定

Codex CLI 出问题时第一条该跑的命令是 codex doctor，但它一屏输出里哪一行是真故障、哪一行只是正常的空闲状态，很多人分不清。本文按本机实测到的六个分组逐行拆解 doctor 的输出结构、四种状态符号和结尾统计行，给出「配置没生效」「磁盘被吃光」「连不上」三类现象的判定命令、处置和验证方法，也说清什么情况下问题根本不在 doctor 报的这一行上。

`.codex` 文件夹放错位置：monorepo 里配置不生效的排查路线

队友说好的项目配置在你机器上就是不认，多半不是配置写错了，而是 .codex 文件夹没在项目根，或者你在 monorepo 的子包目录里启动了 Codex。这篇按现象、判定命令、官方处置、验证方法、排除项五步走一遍，顺带讲清楚项目里的 .codex 和用户目录下的 ~/.codex 完全是两码事，别把两边的键混着改。

用 `codex exec` 把任务写成可重复执行的命令

交互式对话跑完就散了，没法沉淀成团队资产。这篇讲怎么用 codex exec 把一次性对话固化成可复制、可进脚本的命令：完整命令怎么拼、顶层选项与 exec 选项分别写在哪、--json 与 -o 的产出物落在哪，以及哪些活儿压根不该这么干。

把 `codex exec --json` 接进自己的流水线：命令怎么写、产出怎么接、怎么验收

想让 Codex 在 CI 或本地脚本里跑完就把结果交给下一个程序，靠的是 codex exec 的 --json 与 -o 两个选项。这篇给出可直接复制的完整命令、Windows 与 Git Bash 两套写法、逐个选项为什么在这，以及产出物怎么接、上线前该检查哪几处、哪些活儿根本不该这么干。

Codex 特性开关的五个阶段：removed 不等于功能没了

codex features list 会把每个特性的阶段标成 stable、under development、experimental、deprecated、removed 五种之一，很多人看到 removed 就以为功能被删了，但本机实测里有 removed 项的生效值仍然是 true。这篇讲清五个阶段各自代表什么、阶段标签和生效值为什么会错位、开关该写在会话里还是写进配置文件，以及改完之后用哪两条命令验收。

GPT-5.4 八月三十一号从 Codex 退役：迁移前要改的五处，以及漏改会怎样

官方明确 GPT-5.4 与 GPT-5.4 mini 于 2026 年 8 月 31 日从 Codex 退役，并给定了替换模型。这篇按第一次做迁移的顺序，逐一讲清官方点名的五个位置该怎么改、每一步为什么要改，以及漏掉某一处之后会出现什么后果。

Codex 生命周期钩子怎么配：事件、匹配器组与 Windows 专属覆盖

Codex CLI 的生命周期钩子由 features.hooks 开关、hooks.json 或内联 hooks 表组成，事件下面还分匹配器组和处理器两层数组。本文按官方配置参考逐层拆开这套结构，说清事件名为什么不能靠猜、additionalContextLimit 默认 2500 带来的实际约束、Windows 专属的 commandWindows 覆盖为什么必须存在、钩子来源的信任边界在哪，以及改完配置之后该用哪几条只读命令确认它是不是真的生效了。

Codex 会话管理实战：归档、取消归档、删除与按名字找回

Codex CLI 的会话会一直落盘，本机 doctor 报出 405 个 rollout 文件占 3.07 GB。这篇讲清 resume、fork、archive、unarchive、delete 这几条命令各管哪一段，会话文件落在哪个目录，归档和删除之后拿什么验收，以及哪些场景根本不该指望它们兜底。

Codex IDE 扩展和 CLI 该怎么分工？从你的处境倒推一条决策路径

纠结 Codex 用 IDE 扩展还是命令行，问法本身就错了。这篇不罗列功能表，而是从四个真实处境倒推——任务要不要无人值守跑完、要不要改本地文件、有没有管理员权限、要不要上云端——逐条给出判断依据，说明官方文档在哪几处已经替你划好了界线，以及 CLI 与其它使用面之间实际存在的三个接缝和一个高频版本坑。

Codex 集成终端卡住不响应：官方给的处置动作与自查顺序

集成终端面板敲了命令没反应，多数人第一反应是重启整台机器。Codex 官方排查页对这条现象只给了一套很短的处置动作，没有给根因。这篇把官方原话讲清楚，再补上一套本机能跑的只读判定命令，帮你分清到底是面板卡了，还是配置没加载、沙箱没起来、登录掉了或者版本对不上，避免一条道走到黑。

Codex 积分单价里的三个比例：缓存 10 倍、输出 6 倍、档位 25 倍

Codex 官方积分单价表列了三个模型的 Input、Cached Input、Output 三列数字，与其背下这九个数，不如记住从表里直接算出来的三个比例。这篇按「要不要云端、任务复不复杂、预算卡在哪」的顺序把选型路径走一遍，说明这三个比例分别对应哪个动作，也说清它们管不了什么——比如它们算不出你的月账单。

Codex 计划任务堆出一大堆 worktree 的判定、清理与验证

用 Codex 跑计划任务一段时间后，仓库旁边冒出一堆 worktree 目录，磁盘越吃越多。这篇按排查路子走一遍：先用 git 自带的只读命令确认这些目录到底是谁建的，再看官方排查页给出的两条处置口径，处置完怎么验证，以及哪几种情况说明你遇到的根本不是这个问题、别在这条路上继续挖。

ChatGPT 登录还是 API Key：Codex 两种认证的边界

第一次给 Codex CLI 做认证时，最容易糊涂的不是命令怎么敲，而是这台机器上的 Codex 到底从哪个账户扣费、受谁的规则管。这篇按上手顺序讲清两种认证方式各自的登录命令、凭据落在哪、怎么验收、没浏览器的机器怎么办、登录失败先看哪个日志，以及团队想固定走某一条路时该动哪几个配置键。

Codex 在 Linux/WSL2 上沙箱不可用，先查 bubblewrap 装没装

Linux 与 WSL2 上的 Codex 沙箱依赖包管理器安装的 bubblewrap（bwrap），缺了它沙箱就起不来。本文按排查顺序走一遍：现象长什么样、用哪几条只读命令确认是不是这个原因、官方给出的处置、处置完怎么验证，以及哪些症状看着像沙箱问题、其实跟 bwrap 无关，免得在错方向上耗时间。

Codex 的六个使用面：一张图看懂该用哪个

第一次接触 Codex（OpenAI Codex）时最容易卡住的不是安装，而是不知道该从哪个入口进。本文按官方文档站的六个分面——桌面应用、CLI、IDE 扩展、Codex cloud、Web、Codex Remote——给出一条从你自己的处境倒推的选择路径，说明每一步为什么这么选、选错了会在哪里出问题，并标清哪些是本机实测、哪些只是官方文档口径。

MCP 工具列表少了几个：`enabled_tools` 与 `disabled_tools` 的生效顺序

配好 MCP server 却发现工具列表比预期少几个。这篇按排查顺序走一遍：先用只读命令分清少的是整台 server 还是单个工具，再看 `enabled_tools` 与 `disabled_tools` 这两张名单的生效顺序，再对照官方配置键排查 server 那一层，最后给出验证动作和说明不是这个原因的迹象。

给 Codex 接一个 MCP server 的完整流程：配置、启动超时与工具审批怎么调

把一个 MCP server 接进 Codex CLI，真正卡人的不是那段配置，而是默认只有 10 秒的启动超时、60 秒的工具超时，以及 disabled_tools 会盖掉 enabled_tools 这类顺序陷阱。这篇按官方配置参考逐键拆开怎么写，给出可直接复制的 stdio 与 HTTP 两种配置块，再用本机只读命令的实测输出说明接完之后去哪儿验收、哪一步最容易翻车、什么活儿不该这么干。

Codex MCP server 启动超时：默认只有 10 秒

MCP server 时好时坏、换台机器就挂，多半不是配置写错，而是撞上了 startup_timeout_sec 默认只有 10 秒这条线。这篇按排查顺序走一遍：怎么用只读命令确认是启动超时而不是别的毛病，官方配置参考里该改哪个键，改完怎么验证，以及哪几种症状明显不是超时、继续调这个值只会白费工夫。

MCP 服务器配了 `required = true`，整个 Codex 就起不来了

给 Codex CLI 的 MCP 服务器配上 required，它初始化失败就会拖着整个 Codex 起不来。本文讲怎么用 doctor 和 mcp list 定位到具体是哪一个服务器，怎么用 -c 临时覆盖而不动配置文件，处置后核哪几处，以及哪些症状其实跟 required 无关。

Codex Memories 的 11 个配置键：它为什么有时候不生成记忆

Codex CLI 的 Memories 不是「AI 自动记住了」，而是一条被总开关、两个读写开关、六个数值阈值和两个模型键卡住的流水线。本文逐个拆开这些键的含义与判断依据，给出「没生成记忆」时从总开关一路查到额度阈值的排查顺序，并说明哪些场景应该主动关掉它。

`never` 不等于放开权限：Codex 里最容易混的三组概念

把 Codex 的 never 当成放开权限是最常见的误解：审批策略管的是要不要问你，沙箱管的是能不能做，两套机制彼此独立、互不决定。本文拆开审批策略与沙箱模式、沙箱档位与网络边界、Windows 两种沙箱实现这三组最容易混的概念，逐组给出判断依据、可自查的诊断命令，以及一份从需求倒推该动哪个开关的决策清单。

用 `notify` 让 Codex 跑完主动叫你：配置写法、通知脚本与验收清单

交给 Codex 一个长任务之后盯着终端干等，是最浪费的一种等待。这篇讲清 config.toml 里 notify 这个键该怎么配、Windows 与类 Unix 的路径写法差在哪、通知脚本第一版为什么应该只做「把收到的内容原样落盘」而不是急着解析字段，最后给出一份照着走就能排掉八成问题的验收清单和不适用场景。

Codex `--oss` 接本地模型：lmstudio 与 ollama 怎么选

Codex CLI 的 --oss 只给了 lmstudio 和 ollama 两个取值，官方没说差在哪。这篇不比参数，而是按预算、数据要不要出本机、要不要让它动文件、有没有管理员权限四个问题，帮你在 ChatGPT 登录、API Key、--oss 本地提供方和自定义 model_providers 之间选出路径。

把回复变成脚本能解析的 JSON：`codex exec --output-schema` 实战

想让 Codex CLI 的产出直接进脚本、进流水线，靠正则去抠自然语言迟早翻车。这篇讲怎么用 codex exec 的 --output-schema 配合 -o 与 --json 拿到结构化产物：完整命令怎么写、每个选项为什么在这、产出物落在哪、验收要盯哪几行、以及哪些活儿压根不该这么干。

改完 `config.toml` 不生效：按这四层覆盖顺序往下查

你在 ~/.codex/config.toml 里改了键，重开会话行为却一点没变。这类问题九成不是键名写错了，而是覆盖层没理清。本文按配置加载、命令行一次性覆盖、profile 叠加、平台与版本差异四层顺序，给出可直接执行的判定命令，并说明每一步处置后该看哪条只读命令的输出来验证。

Codex 自定义权限档：按目录和域名给 AI 发通行证

沙箱三档只能选整体松紧，管不了「只让它写 src、只让它连一个域名」。这篇讲清 Codex CLI 里 permissions 权限档的配置结构：extends 继承链、filesystem 的三态取值、network 的三层开关，以及 -p 与 -P、权限与审批这两组最易混淆的概念怎么分辨。

Codex 插件实战：三个 marketplace 怎么读、插件怎么装怎么停

Codex CLI 的插件有三个 marketplace、四个子命令和好几层开关，装了不生效多半不是装错，而是被某一层关掉了。这篇讲：怎么用 codex plugin list 摸清家底、STATUS 列怎么读、features 与 config.toml 里的启停键各管什么、改完怎么验收。

Codex CLI 的 `--profile`：给不同项目挂不同配置层

一台机器上同时开着实验仓和生产仓，用同一份 config.toml 迟早出事。这篇讲清 Codex CLI 顶层选项 -p/--profile 的叠加机制、文件名规则，以及它和 -P/--permission-profile、-c 三者的分工边界，并给出用 doctor 验证配置到底有没有加载成功的实测方法和判断依据。

公司网络下 Codex 登录失败：TLS 代理与 `CODEX_CA_CERTIFICATE` 的排查顺序

家里能登、到公司就登不上，多半卡在办公网的 TLS 代理或私有根 CA。本文按 login status、doctor --summary、codex-login.log 的顺序定位问题层级，再给官方处置：登录前设置 CODEX_CA_CERTIFICATE、设备码登录与 1455 端口转发，并列出何时该掉头查别处。

从权限模型看 Codex 与其它编程 agent 的差别：选型前该问清楚的五个维度

选编程 agent 时最难比的不是谁代码写得好，而是它到底能碰你机器上的什么。本文用 Codex CLI 0.147.0 的沙箱模式、审批策略、平台实现、网络控制和权限档五个维度搭一套坐标系，按「只读还是可写、要不要云端、有没有管理员权限、是不是无人值守」五种处境倒推到具体配置，并给出可在本机执行的验收命令与横向选型时该问对方的问题清单。

Codex 会话续跑与分叉实战：resume、`--last` 与 fork 怎么用才不丢上下文

一次会话没干完就关了终端，第二天怎么接着跑？这篇把 Codex CLI 的会话续跑与分叉讲透：resume 默认选择器与 --last 的取舍、exec 里的非交互续跑、fork 用来做同一起点的多方案对比、resume 时工作目录归属由 tui.resume_cwd 决定，以及会话落盘在哪、怎么验收、哪些情况根本没法续。

`codex review` 的三种评审范围怎么挑：--uncommitted、--base 与 --commit

codex review 提供了三个划定评审范围的选项，选错范围会让评审结果整个跑偏。本文按实际场景讲清 --uncommitted、--base、--commit 各自覆盖什么、命令怎么写、产出物往哪里接、验收时要盯哪几处，以及哪些活儿不该指望这三个范围来兜底。

Codex 的日志、SQLite 状态库与 OTel 遥测：先分清三层，再决定开什么

Codex CLI 的运行痕迹分散在 log 目录、sessions 会话文件和几个 SQLite 库里，磁盘占用会悄悄涨到 GB 级。本文梳理 log_dir、sqlite_home、history.persistence 与整套 otel.* 导出键位，给出该查哪一层、该关哪一项、遥测要不要开的判断依据。

Codex 沙箱三种模式怎么选：从「能不能改我的文件」倒推

Codex CLI 的 read-only、workspace-write、danger-full-access 到底差在哪？本文不照抄官方释义，而是从「你允许它改哪些文件、要不要出网、有没有管理员权限」三个问题倒推出该选哪一档，顺带讲清沙箱与审批策略这对最容易混淆的概念，以及 Windows 上 elevated 与 unelevated 的取舍和排查入口。

Codex 沙箱里的命令连不上网：先搞清是哪个开关关的

在 Codex 沙箱里跑命令连不上网，多半不是网线坏了，而是某一层权限开关把出网关掉了。这篇按沙箱模式、network_access、权限档域名策略、Windows 原生沙箱权限模式四层往下排查，每层给出可直接执行的只读判定命令，并说明改完怎么验证生效、出现哪些迹象说明不是沙箱在拦你。

沙箱里文件写不进去：三种模式下的可写边界

Codex 说改好了文件，回头一看磁盘上什么都没变，这类问题九成出在沙箱的可写边界上。本文按排查顺序走一遍：先用 doctor 确认当前沙箱状态，再用 codex sandbox 跑一条无害命令判定写入到底有没有落盘，然后区分三种沙箱模式和三档审批策略的职责，给出扩大可写目录的官方做法，最后列出几种看着像沙箱、其实另有原因的情况。

给 Codex CLI 装上 shell 补全：一份不靠猜的落地清单

Codex CLI 自带 completion 子命令用来生成 shell 补全脚本，但支持哪些 shell、参数怎么写会随版本变，抄别人的命令很容易踩空。这篇给出先自查再落地的完整步骤、Windows 与类 Unix 侧分开的放置方式、拿子命令全表做验收对照的办法，以及自动升级后补全脚本变成旧版快照这个最容易被忽略的坑。

Codex shell 环境变量策略：哪些变量会被带进子进程

Codex CLI 的 shell 工具派生子进程时，究竟会把你终端里的哪些环境变量带过去？本文拆开 config.toml 里 shell_environment_policy 这一组键，讲清 inherit 三个取值怎么选、ignore_default_excludes 默认 true 为什么反而是保留带 KEY/SECRET/TOKEN 的变量、set 与旧版 exclude 的关系，以及在 Windows 上改完配置该用哪条命令确认它真的被加载。

Codex CLI 四种安装方式怎么选，装完第一件事是跑 doctor

官方给了独立安装脚本（macOS/Linux 与 Windows 各一条）、npm、Homebrew 四种装 Codex CLI 的方式。这篇按「你手上有什么」倒推该选哪一种，然后讲清楚装完为什么要先跑 codex doctor、登录该走 ChatGPT 还是 API Key，以及每一步做错了会在哪里翻车。

Codex 三档模型 sol / terra / luna 怎么选：从你的处境倒推，而不是比参数

gpt-5.6-sol、terra、luna 三档的差别不只是"强一点弱一点"：terra 和 luna 在 Codex cloud 上根本不可用，而三档之间的积分单价差到 25 倍。这篇按四个现实约束——要不要跑云端、要不要它改文件、订阅是哪一档、老配置里还写着什么模型——给出一条能走到底的选型路径，并说明配置该落在哪几个键上。

`--strict-config` 为什么没拦住我的拼写错误：配置校验的触发时机

在 config.toml 里把配置键拼错，加了 --strict-config 却没报错。本文用 codex-cli 0.147.0（Windows 11）的只读命令实测，说清这个开关的校验何时触发、哪些路径不触发，并给出判定命令：doctor 看配置加载没有，features list 核对生效值。

Codex 多代理配置怎么定：并发上限、子代理默认模型与角色定义

Codex CLI 的多代理由 agents 这一组配置键控制：并发线程上限、子代理默认模型与推理强度、每个角色的说明与独立配置层。本文按官方配置参考逐键说清取值与默认值，重点讲官方没给默认值的那几个键该怎么定、旧别名 max_threads 与新键的关系、子代理选便宜模型时的成本依据，以及改完配置后用 features list 和 doctor 验证生效的完整方法。

提交前自查工作流：`codex review --uncommitted` 到底该怎么写

提交代码前想让 Codex 先过一遍，但它到底看哪几类改动、沙箱要不要收紧、审批策略选哪个、结果落在哪、哪一步最容易翻车？本文给出可直接复制的命令与逐个选项的取舍理由，配上四个验收检查点与不适用场景，均基于 codex-cli 0.147.0 / Windows 11 的只读命令输出与官方文档口径。

Codex CLI 的 TUI 定制：状态栏、主题、快捷键与解绑到底怎么配

Codex CLI 的界面几乎每一处都能在 config.toml 的 tui 段里改。本文按官方配置参考逐条列出键名、取值与默认值，重点讲三处容易翻车的细节——alternate_screen 的 never 和审批策略的 never 不是一回事、解绑快捷键必须赋空数组而非删行、改完后用哪条命令确认配置真的加载了。

Codex 推理强度怎么选：UI 档位与配置取值是两套名字

Codex 的推理强度在界面上叫 Light、Medium、Extra High，写进 config.toml 却是 minimal 到 xhigh，我们核对的官方文档页里没有对照表。本文按「改哪一层、跑在哪、预算多少、有没有管理员权限」四个岔路口，把选档拆成一条能照着走的决策路径，并说明改完怎么确认配置真被加载。

用 `-i` 把截图和设计稿带进 Codex 首轮指令

UI 截图、设计稿、报错弹窗这类东西用文字转述很费劲，Codex CLI 的 -i 选项能把图片文件直接附在首轮指令上。本文给出交互式与 codex exec 两种可直接复制的命令写法，逐个解释选项为什么要加，说明 --json 与 -o 的产出物落在哪里，并给出四步验收顺序：先看 features list 里 view_image 的阶段与生效值，再用 doctor 确认配置真的加载成功，最后讲清哪些场景不该这么干。

拿不到管理员权限：Codex Windows 沙箱 unelevated 回退模式的取舍

公司电脑没有管理员权限、UAC 提示被策略拦掉，Codex 的 Windows 原生沙箱初始化不起来该怎么办。这篇按排查思路走一遍：先用 doctor 确认卡在哪一步，再看官方给的 elevated 与 unelevated 两种模式差别在哪、配置键怎么写、回退之后拿什么验证边界还在，最后列出几种看着像但其实不是这个原因的情况。

Codex 联网搜索的四种模式：默认 `cached` 既不是关闭也不是实时

Codex 的 web_search 默认值是 cached，既不是关闭也不是实时。本文讲清四档取值该怎么选、CLI --search 的真实作用范围与会话级边界、三个已弃用的 features 老开关怎么迁移，以及改完配置后用哪条命令确认它真的加载生效了。

Codex Windows 沙箱报错 1385：沙箱用户建好了，命令却跑不起来

Windows 上跑 Codex CLI，沙箱初始化看着走完了，一执行命令就撞上错误 1385。本文按官方口径拆解这个错误码的确切含义，给出可以直接复制的判定命令、两种沙箱模式各自的取舍与适用前提、官方给出的四步处置顺序及其注意点、处置完成后如何验证沙箱确实还在生效，以及五种看着像它、其实另有原因的情况。

Codex 在 Windows 上沙箱初始化失败：四个成因与官方排查顺序

Codex CLI 在 Windows 上跑的是原生受限沙箱，和 Linux 的 bubblewrap 完全是两套机制，排查步骤不能照搬。本文梳理初始化失败的四类成因：官方列的三条常见原因（UAC 提示被拒、本地用户创建被阻止、防火墙规则受限），加上单列的已知错误 1385。

`winget` 不可用时，Codex 的 Windows 沙箱为什么起不来

Windows 上 Codex CLI 沙箱初始化失败，很多人第一反应是去装 bubblewrap，方向就错了。这篇按「现象 → 判定命令 → 官方处置 → 验证 → 排除」的顺序，讲清 winget 这个硬性前置条件卡在哪，怎么用 doctor 和 sandbox.log 确认是不是它，以及哪些报错其实是另外几件事。

worktree 上代码跑不起来：`.worktreeinclude` 与初始化脚本怎么排

让 Codex 在 Git worktree 里干活，代码却编不过、跑不起来，多半不是模型的问题，而是 worktree 只继承了 Git 跟踪的文件，依赖和被忽略的本地文件都没跟过去。这篇按现象、判定命令、官方处置、验证、排除五步走一遍，并说清哪些情况根本不是这个原因，免得一条道走到黑。

服务器上没有浏览器怎么登录 Codex：`--device-auth` 与 1455 端口隧道

SSH 到一台没有图形界面的机器上装好 Codex CLI，登录这一步却卡住——因为 ChatGPT 登录要在浏览器里完成认证。这篇按排查顺序讲：先用哪几条只读命令确认问题真出在「没有浏览器」上，官方给的设备码登录、复制已缓存凭据、转发 1455 回调端口三条路各自适用什么处境，处置完怎么验证，以及哪些迹象说明你其实撞的是别的墙。

Codex 会话起错了执行目标：Local、Worktree、Cloud 三条路怎么认、怎么救

起会话时执行目标选错，改动就会落到你没预期的地方——本地工作树、另一个 Git worktree 目录，或者 OpenAI 托管的云端环境。本文按排查顺序给出可执行的判定命令、官方文档给出的处置口径和处置后的验证方法，并列出哪几种相似症状其实另有原因，免得一条道走到黑。

Codex 桌面应用还是 CLI？从四个处境倒推的选型路径，外加版本口径这个坑

官方对 Codex 桌面应用和 Codex CLI 各自推荐了什么场景，两者的差别不在功能多少，而在你的处境。本文按能不能装应用、要不要脚本化、要不要跨设备接着做、要不要精确控制改文件的权限这四个问题倒推结论，并解释官方排查页里那条「功能在 CLI 有、桌面应用没有」的版本口径差异到底该怎么查、怎么避免误判。

AMD 卡上 ComfyUI 跑不动的排查清单

AMD 卡上 ComfyUI 装不上、起不来或者卡在加载环节，同一句「跑不动」可能落在完全不同的层上。本文按官方 README 与 comfy/cli_args.py（v0.31.0）的口径，把排查拆成五步：先确认 torch 是否为 ROCm 构建，再选对稳定版还是 RDNA3、3.5、4 的实验性 nightly，然后是 HSA_OVERRIDE_GFX_VERSION 的两个取值、卡在加载时该逐个关掉哪几个开关、以及 Triton 后端在 AMD 上的自动默认，最后列出哪些常见现象其实与 AMD 无关，避免一条道走到黑。

ComfyUI 在 Apple Silicon 上的已知边界：先分清是 MPS 的限制，还是你装错了环境

在 Mac 上跑 ComfyUI，报错常被笼统归给「M 芯片不行」，排查就此停摆。本文按官方仓库与源码口径，梳理 Apple Silicon 这条安装路径官方给了什么、又没给什么，教你用启动日志里的两行和几个判定动作，把 MPS 已知限制、环境装错、自定义节点惹的祸分开，并说清哪些启动开关只能试、不能当解药。

ComfyUI 的五个注意力实现参数怎么选，以及 xformers 在里面扮演什么角色

ComfyUI 五个注意力实现参数互斥，其中两个的 help 明写「用了 xformers 就会被忽略」。本文按 v0.31.0 的 cli_args.py 原始 help，讲清这五个参数的关系、独立开关 --disable-xformers 站在哪一层、两个 upcast 开关怎么用，以及注意力后端连改两版后结论为何要带版本号。

ComfyUI 的版本关系：Core、前端、模板包、桌面版到底谁跟着谁

升级 ComfyUI 后界面变了、模板不见了、自定义节点报 import 失败，多半是同一次操作的连带结果。本文按官方 README 的 Release Process 与 v0.31.0 的 requirements.txt，讲清 Core、前端、模板包与桌面版谁跟着谁，以及跟 tag 还是跟 master 的判断依据。

采样预览不显示，先看这个参数

ComfyUI 采样时看不到预览图，多数时候不是装坏了，而是 --preview-method 这个开关在源码里的默认值本来就是 none，官方 README 要你自己显式加 auto。本文按 v0.31.0 的 comfy/cli_args.py 与 README，给出怎么确认参数有没有生效、四个取值该选哪个、TAESD 的四个解码器文件该放进哪个目录、改完之后怎么验证，以及出现哪几种迹象就说明问题根本不在这个参数上、该往执行模型和前端版本那边查。

ComfyUI 报 CUDA no kernel image is available：成因方向与判定路径

这条报错在 ComfyUI 上最常见的成因方向是显卡代次与 PyTorch 的 CUDA 构建对不上。本文按官方 README 的版本矩阵和 Windows portable 分包规则，给出一条可执行的判定路径：先定卡的代次、再定 torch 构建、最后才动手换包，并列出哪几类报错根本不该往这个方向查。

ComfyUI 报 CUDA OOM 时的排查顺序

ComfyUI 抛出 CUDA 显存不足时，多数人第一反应是加 --lowvram，但在当前版本这个开关很可能什么都不做。这篇按启动日志、dynamic VRAM 判定、保留显存三层给出可执行的排查顺序，讲清 --reserve-vram 与 --vram-headroom 的语义差别与 EXTRA_RESERVED_VRAM 的默认值，并列出哪些现象其实不是显存问题。

ComfyUI 多卡机器上的设备参数：`--cuda-device` 与 `--default-device` 到底差在哪

多卡机器上 ComfyUI 该怎么指定用哪张卡？按 v0.31.0 的 comfy/cli_args.py 对照 --cuda-device 与 --default-device 的 help 语义，讲清「其它设备不可见」与「仍可见」这条关键差别，并给出一卡一实例的启动命令、启动日志验收点与不适用场景。

读懂 DynamicVRAM：它什么时候会被悄悄关掉

ComfyUI 的 dynamic VRAM 不是一个你打开才生效的开关，而是由源码里的 enables_dynamic_vram() 按五个条件推算出来的状态，默认启动时它是开着的。本文按 v0.31.0 的 comfy/cli_args.py 逐条拆开这段判定逻辑，讲清 --highvram、--gpu-only、--novram、--cpu 这四个开关为什么会顺手把它一起关掉，为什么 --lowvram 在默认状态下什么都不做，--vram-headroom、--reserve-vram、--disable-nvml-pressure 三个参数各自管的到底是什么，以及你该怎么从启动命令和启动日志里确认自己当前处在哪一侧。

ComfyUI `--fast` 的四个优化项，开之前要知道的

ComfyUI 的 --fast 是官方自己写了三条警示的参数：未经测试、可能劣化质量、可能让 ComfyUI 崩溃。本文按 comfy/cli_args.py（v0.31.0）的口径讲清它的四个枚举值，以及「不写=不开、写了不带值=四项全开」这条三态逻辑，并给出按需单开、随时可回退的用法与判定排除路径。

把 ComfyUI 部署到服务器上：`--listen`、目录参数与日志落盘的完整启动命令

在服务器上跑 ComfyUI，绕不开监听地址、端口、上传体积、多用户存储、目录规划和日志落文件这几件事。本文按 ComfyUI v0.31.0 的 comfy/cli_args.py 逐个说清这些参数的语义与互相覆盖关系，给出一条可直接复制的完整启动命令和逐条理由，再给出起来之后该检查哪几处、最容易在哪一步出错，并把最容易被忽略的安全前提摆在前面：多用户参数只管存储分离不等于登录，用户名密码认证目前仍是一个 open 的 feature request，TLS 必须成对给参数才生效。

ComfyUI 五种缓存模式该选哪个：从 `--cache-ram` 的默认阈值倒推启动参数

ComfyUI 缓存这一组有五个互斥开关，默认是 RAM 压力缓存。本文按 v0.31.0 的 cli_args.py 讲清 --cache-ram 两个阈值怎么算、--high-ram 为何隐含旧式缓存、--cache-lru 的内存代价与 --cache-none 的取舍，并按内存大小给出选择路径。

unet / VAE / 文本编码器的精度参数各管什么

ComfyUI 的精度开关分成扩散模型、VAE、文本编码器三个互斥组，外加全局开关和几个独立参数，混着加最容易调错地方。这篇按 v0.31.0 的 comfy/cli_args.py 原始 help 把三组参数列全，讲清互斥组意味着什么、force-fp16 为什么会连带影响 unet、fp8 三种变体的 help 只说存储不说计算、fp16-vae 那句黑图警示该怎么用来排查、cpu-vae 为什么不在互斥组里，以及标了 Experimental 的参数要不要放进常驻启动脚本。

为什么改了参数它不重跑：ComfyUI 局部重执行机制怎么读

ComfyUI 里改了节点参数、点了排队，画面却纹丝不动，很多人第一反应是软件卡了。其实官方 README 的执行规则里写得很清楚：只有输入正确的那部分图会执行，且只有相对上一次发生变化的部分会执行。这篇按 v0.31.0 的 README 与 comfy/cli_args.py 拆开这两条规则，给出区分「缓存生效」和「图确实没变」的判定动作，并说明 --cache-none 该在什么时候用、什么时候不该常开。

别的机器打不开 ComfyUI 页面：先看 `--listen` 而不是查网络

局域网里别的机器打不开 ComfyUI，多半不是路由或防火墙的锅，而是服务端默认只绑 127.0.0.1。本文按 v0.31.0 的 comfy/cli_args.py 口径讲清 --listen 的三种写法、--port 默认值、--enable-cors-header 的真实作用，以及开放监听后的暴露面与验收动作。

老显卡启动就崩：cudaMallocAsync 这条线索

老显卡上 ComfyUI 装完就崩、连界面都打不开，很多人第一反应是重装驱动、重建环境，一晚上白折腾。这篇按官方参数语义给出一条更省事的排查线：先弄清 --cuda-malloc 这个开关在 torch 2.0 及以上其实是默认开着的，再用 --cpu、--disable-all-custom-nodes、--verbose 三步做减法定位，最后才轮到用 --disable-cuda-malloc 试一把；同时说清楚处置完该验证哪三处，以及出现哪些情况就说明根本不是这个原因，别在一条道上走到黑。

ComfyUI 在无 swap 分区的 Linux 上 pin 太多内存：v0.31.0 之前怎么判定与规避

没划 swap 分区的 Linux 机器上跑 ComfyUI，pinned memory 的上限要按一条把 swap 算进去的公式取值。本文按源码里的两套公式和两条与 swap 有关的告警文案，讲清楚怎么从启动日志判定自己是不是撞上了这件事、v0.31.0 修掉的到底是什么、旧版本上关 pin 与调缓存阈值该怎么用，以及哪几种情况说明不是这个原因。

ComfyUI 的 `--lowvram` 为什么不管用了

老教程里「显存小就加 --lowvram」这句话，在当前版本的 ComfyUI 上大概率什么都没做。原因写在 cli_args.py 的 help 原文和 enables_dynamic_vram() 这个判定函数里。这篇讲怎么用启动日志和参数对照确认自己是不是撞上了这件事、真正该动的是 --reserve-vram 与 --vram-headroom 里的哪几个、改完怎么验证，以及什么情况下说明你的问题根本不在这条线上。

启用 ComfyUI-Manager 与它的三个开关

ComfyUI-Manager 在 v0.31.0 上不是装完就能用，要先装 manager_requirements.txt 再用 --enable-manager 启动。本文按官方 README 与 comfy/cli_args.py 的口径讲清这两步命令、三个命令行开关各自的语义、互斥与隐含关系，说明为什么禁用界面不等于关掉扩展，并给出多用户与服务器场景下只保留后台任务、关掉 Manager 界面的组合写法、四步验收清单，以及离线机器和生产流水线上不该这么配的几种情形。

ComfyUI 改一次提示词就重载一次模型：缓存模式与局部重执行的排查路径

只改了提示词里的一个词，日志却又打出一遍 Requested to load。本文按 ComfyUI v0.31.0 的源码与 README 口径，讲清楚怎么用日志确认重载真的在发生、五种缓存模式的语义与 --cache-ram 的默认阈值算法、为什么 --cache-none 与 --high-ram 常帮倒忙，以及哪些迹象说明问题不在缓存策略上。

ComfyUI 模型加载慢：能调的几个开关

点了运行之后长时间停在 Requested to load 那一行，多数时候不是显卡不行，而是加载路径上的开关没配对。本文按 ComfyUI 官方仓库与源码口径梳理 v0.23.0 的多线程磁盘加载、v0.30.0 的 pinning 与 MRU 策略、--fast-disk 的适用前提，以及经常被混为一谈的 --mmap-torch-files 与 --disable-mmap，给出怎么判断是加载慢、该动哪个开关、改完怎么验证，以及什么情况说明问题根本不在加载路径上。

让 ComfyUI 和别的 UI 共享同一份模型目录

同一批模型被几个 UI 各存一份，硬盘很快就撑不住。ComfyUI 官方给的入口只有一个：把仓库里的示例配置改名成 extra_model_paths.yaml 再编辑。本文按 README 与 comfy/cli_args.py（v0.31.0）的口径讲清这个文件在哪、便携版里的位置、为什么启动参数能重复叠加多个配置，以及它和整体搬家用的两个目录参数分别该在什么时候用，最后给出四步验收顺序和几种不该这么干的场景。

ComfyUI 的六类目录与覆盖优先级：`--base-directory` 和五个单项参数谁说了算

ComfyUI 把模型、自定义节点、输入、输出、临时文件、用户配置分成六类目录，既能用 --base-directory 一次性搬家，也能用五个单项参数逐个覆盖。本文按 v0.31.0 的 comfy/cli_args.py 讲清这两套参数的优先级、哪些路径会在启动时被校验、哪些拼错了也不报错，以及模型搬家该选目录参数还是 extra_model_paths.yaml。

ComfyUI 报 memory leak 告警怎么办：先分清两条文案，再做二分排查

ComfyUI 控制台里冒出 Potential memory leak detected 和 WARNING, memory leak 两条告警时，多数人第一反应是重装或者回滚版本。本文按 v0.31.0 的源码日志文案逐字拆开这两条的差别与严重程度，给出先抄哪几行启动日志作为基线、怎么用 --disable-all-custom-nodes 配合白名单参数做二分排查、处置之后怎么验证告警是否真的消失，以及缓存策略、pinned memory 等哪几类内存占用偏高其实跟泄漏无关、不该顺着这条路一直走下去，最后说清什么时候才具备去仓库提 issue 的条件。

pinned memory 上限：Windows 和 Linux 不一样

ComfyUI 启动日志里那行 Enabled pinned memory 后面的数字是算出来的，Windows 和其它系统用的根本不是同一个公式。本文按 v0.31.0 源码原样列出两套公式，拆开非 Windows 那个 max/min 嵌套逐项解释，说清初始值 -1 代表什么、两条 swap 告警各自意味着什么，以及什么时候该考虑 --disable-pinned-memory；顺带给出几条判断依据，帮你确认日志里那行数字对不对得上，以及哪些症状其实和它无关。

四个 portable 包别下错：ComfyUI Windows 便携版的选包与落地流程

ComfyUI 的 Windows Portable 在官方 release 页上一次给出四个 7z 包，文件名只差一个后缀，下错了轻则起不来重则白折腾一晚上。这篇按官方 README 口径把四个包的完整文件名、适用 GPU 范围、cu126 包那句全大写警告、默认包自带的 Python 与 PyTorch CUDA 版本、解压与解除锁定的两个必检点、模型该放进哪个目录一次讲清，并给出下错之后怎么快速判定与回退的动作。

ComfyUI 的 Python 与 PyTorch 版本怎么定：照 README 版本矩阵倒推一条安装命令

装 ComfyUI 之前先把 Python 和 PyTorch 的版本定死，能省掉后面一大半自定义节点装不上、CUDA 起不来的麻烦。本文按官方 README 的版本矩阵，把 Python 3.14/3.13/3.12 三档的取舍、torch 2.7 这条最低线、cu130 在 20 系及以上的强制要求、以及各平台的原样安装命令捋成一条可执行路径，并给出验收清单和不适用场景。

ComfyUI 前端出问题该提到哪个仓库：三路分流规则与 `--front-end-version` 的用法

ComfyUI 的前端自 2024-08-15 起已迁到独立仓库，界面问题提到主仓容易被转走。本文讲怎么判定问题落在前端、核心还是工作流模板：看 requirements.txt 的 pin 行，用 --front-end-version 切换前端版本做对照，再按官方模板的三路分流规则提对地方，并说明哪些现象不算前端。

ComfyUI 启动日志逐行读懂：八行关键信息与 VRAM 状态机

ComfyUI 出问题时，线索大多藏在启动那二十来行日志里。本文按 v0.31.0 的源码文案，解释显存总量、VRAM 状态、pinned memory、异步卸载、xformers 版本这八行日志在说什么，以及 --verbose 的六个等级、日志默认走 stderr 该怎么抓全，并给出验证方法与不该在这层折腾的情况。

ComfyUI 日志分级、落文件与 DETAIL 等级：`--verbose` 的三种用法

ComfyUI 的 --verbose 可以不带值、给一个等级、也可以给「等级 + 文件名」，还能重复使用；等级枚举里多出来的 DETAIL 是 v0.30.0 才加的。本文按 v0.31.0 的源码口径讲清三种写法怎么组合、控制台等级由谁决定、日志默认走 stderr 会带来什么麻烦，以及配好后该检查哪几处。

ComfyUI 生成出黑图：官方口径里只有这三条线索

出图打开是一张纯黑，网上能搜到十几种说法，但在 ComfyUI v0.31.0 的源码与 README 里，明确写着 black images 的地方其实只有三处：`--fp16-vae` 的 help 警告、启动日志里那条 xformers 高分辨率黑图告警、以及 `--force-upcast-attention` 的 help 留下的上报入口。本文把这三条线索分别拆成怎么确认、官方给出的处置、处置之后怎么验证，以及什么情况说明不是它；其余原因官方文档里没有写，本文一条都不猜。

升级后坏了：ComfyUI 的版本回退策略

拉了一次更新，ComfyUI 就起不来、前端变样、自定义节点报错。这篇按官方 README 的 Release Process 规则讲清楚 core、desktop、frontend 三个仓库的关系，为什么回退要退到 stable tag 而不是某个 commit，requirements.txt 里三个被精确 pin 的包会跟着一起换，以及从 v0.22.0 到 v0.31.0 的版本时间线该怎么用来定位回退目标，最后给出判断「不是升级问题」的几条依据。

ComfyUI 是什么：一个节点式的生成引擎，以及它带来的一整套工程问题

它早就不是「Stable Diffusion 的前端」了，官方把自己定位成内容创作的模块化 AI 引擎，图像、视频、音频、3D 与文本生成都在里面。但它同时是一个每两周一个大版本、启动参数几十个、升级容易弄坏自定义节点的工程。这篇把定位、版本节奏、安装路径、执行模型、显存主线、扩展风险一次讲清，并给出整个专题的阅读路径。

ComfyUI 提示词语法全解：权重、转义、动态提示与 embedding 引用

ComfyUI 的提示词语法只有五条官方规则，但每条都容易读偏：括号权重的默认值是多少、反斜杠该转义谁、花括号的随机到底发生在哪一层、注释挂在哪一节下、embedding 引用为什么可以省掉扩展名。这篇按 README 原文逐条拆开，重点讲这些规则分别由前端还是节点执行，出问题时你该往哪个方向查。

给 ComfyUI 开 HTTPS：自签证书、`--tls-keyfile` 与它管不到的那些事

ComfyUI 的 TLS 开关只有 --tls-keyfile 与 --tls-certfile 成对给出才生效，官方 README 也明说自签证书不适合共享或生产使用。本文按官方 README 与 v0.31.0 的 cli_args.py 口径，给出证书生成命令原文、Windows 上的两条替代途径、容器相对路径挂载写法、验收该查哪几处，以及哪些场景不该这么干。

ComfyUI 报 Torch not compiled with CUDA enabled 怎么修

这条报错要修的是 torch 的安装，不是 ComfyUI 的启动参数。本文按官方 README 口径讲清楚：怎么确认确实是它、README 唯一给出的处置、各平台原样安装命令、cu130 对 20 系及以上为何必需、portable 与手动安装用户的动作差别，以及处置后怎么验证、什么情况说明不是这个原因。

让 ComfyUI 完全离线跑：`--disable-api-nodes` 之外还要关掉哪些出网路径

把 ComfyUI 放进不能出网的内网里跑，光拔网线是不够的。官方 README 说核心完全离线、不会主动下载任何东西，但像 --front-end-version 这样从教程里抄来的参数，按它自己的 help 说明本身就需要联网。本文按 v0.31.0 的 comfy/cli_args.py 口径，梳理 --disable-api-nodes、--disable-all-custom-nodes、--front-end-root、--comfy-api-base 各自管的到底是什么，组合成一条离线启动命令该怎么写，模型与预览解码器要提前落到哪几个目录，验收时人要盯哪几处最容易漏，以及哪些场景根本就不该这么干。

Windows 上装 ComfyUI 的四条路径：桌面版、portable、comfy-cli、手动装怎么挑

Windows 上装 ComfyUI 有四条常见路径，第一步就容易挑错——官方 README 对普通用户明确不推荐 portable 包。本文按官方仓库口径对照四条路径的定位、命令与 Python/torch 版本要求，讲清 portable 四个包别装错哪个、装完怎么验收、各自在什么场景下不适用。

用二分法定位是哪个自定义节点的锅：`--disable-all-custom-nodes` 与白名单放行

ComfyUI 升级后启动报错、界面加载不出来、日志里冒出内存泄漏告警，多半和某个自定义节点有关，但插件装了几十个，一个个删太慢。这篇按 v0.31.0 的 comfy/cli_args.py 讲清 --disable-all-custom-nodes 与 --whitelist-custom-nodes 的组合语义，给出先全关确认、再逐批放行的完整二分流程，以及处置后怎么验证、哪些现象其实和自定义节点无关。

Alpaca 格式：`instruction\ninput` 是怎么拼出用户提示词的

照着 alpaca 样例填了 instruction 和 input，却说不清它们最后变成了什么？本文按 LlamaFactory 的 data/README.md 原文，讲清监督微调数据各列角色、两列怎么拼成用户提示词、列名与 dataset_info.json 里 columns 映射的关系，以及它何时不够用。

源码、Docker、uv：三条安装路径分别适合谁

LlamaFactory 的 README 把安装拆成源码、Docker 镜像、uv 隔离环境三条路，还外加三条免装环境的云端入口。这篇按仓库当前文档逐条抄清每条路的命令、前置条件和它各自照顾的处境，讲清 Python 3.11 这条下限卡在哪、官方镜像里预置了什么、Windows 换下载源为什么要单写一行，以及为什么装法不改变显存那张估算表。

BAdam 的八个参数：mode、switch_mode、update_ratio 与 mask_mode

LlamaFactory 里的 BAdam 不是一个独立训练阶段，而是 finetuning_args.py 中八个带 badam_ 前缀的字段。本文逐个交代它们的确切名字与源码默认值、所在的参数层、与 GaLore/APOLLO 在参数形状上的差别，以及为什么默认值不等于推荐值、该设成多少官方并没有给通用答案。

表里 template 写 `-` 的四个模型：base 与 instruct 的取值规则

LlamaFactory 的支持模型表里有四行的 Template 列写着一个横杠，很多人把它当成「还没适配」。它其实对应表下注解里的一条规则：base 模型的 template 可以从通用取值里选，instruct/chat 模型必须用对应的那个。本文讲清这四行是哪四行、横杠与名字就叫 empty 的 template 有什么区别、判断依据在哪个源码文件里，以及为什么这条规则没法给出「推荐值」。

Day 0 / Day 1 支持表与更新日志：怎么读才不会读成承诺

LlamaFactory 的 Day 0 / Day 1 支持表和 README 更新日志常被当成路线图，于是「日志里写了支持 X」被理解成「我现在就能跑 X」。本文按官方仓库当前内容，讲清这两块记录的到底是什么、一条日志怎么落到可核查的字段与环境变量上、「支持」覆盖不到的三件事，以及该以仓库里的哪些位置为准。

`llamafactory-cli` 的八个子命令：一张表说清各自干什么

LlamaFactory 对外只暴露一个命令行入口，八个子命令分别管训练、推理、导出、两种 Web 界面和两条排查路径。本文照抄 launcher.py 里的 USAGE 原文表，讲清这八条各自对应什么、api 的端口为什么走环境变量、train 为什么是唯一会自己改写启动方式的那一条。

导出九个参数：`export_size` 5、`export_device` cpu

LlamaFactory 的导出这一步只有九个参数，全部定义在 model_args.py 里，而官方示例配置只显式写了其中四个。本文把九个参数名与源码默认值逐个对上，说清它们住在哪一层、示例 YAML 与源码默认是否一致、四个 export_quantization_ 字段和合并 LoRA 时那条全大写禁令的关系，以及哪些语义我们没有核实、只能以 -h 输出为准。

`dataset_info.json` 全字段：十一个顶层键与两组子字典

想在 LlamaFactory 里挂上自己的数据集，绕不开 dataset_info.json 这份描述文件。顶层键、columns 子字典、tags 子字典分属三层语义，填错一层就是白改。本文按官方 data/README.md 原文，把十一个顶层标量键和两组嵌套字典逐个对上默认值，说清哪些字段不写就不生效。

官方镜像里到底装了什么：Ubuntu 22.04 + CUDA 12.4 + PyTorch 2.6.0

LlamaFactory 官方 Docker 镜像的 README 只用一句话交代了里面装的五个版本号。本文把这句原文拆开，逐项对照 README 的 Requirement 依赖表，说清镜像锁住了哪几层、哪几格与 Recommend 对不上、镜像不负责什么，以及自建镜像与 Windows 侧环境变量该怎么写。

视觉塔冻结、投影层冻结、语言模型不冻结：LlamaFactory 多模态的三个默认值

LlamaFactory 里有三个名字很像的多模态冻结开关，默认值却不是一边倒。本文按源码实读，钉住这三个字段的确切写法与默认值，说清它们坐在哪个参数文件里、和另一组同样以 freeze_ 开头但完全不是一回事的字段怎么区分、为什么要连着输入侧那几行一起看，以及为什么这篇不给你任何"该设成多少"的建议。

视觉、音频、全模态：十几个独立命名的多模态 template

LlamaFactory 的多模态支持不是一个开关，而是模型表 Template 列里十几个各自独立命名的字符串。本文按官方仓库当前内容，把视觉、视频、音频、全模态这几类的 template 名逐类摘出来，讲清斜杠分档怎么读、抄错会牵动哪些配置，以及 template 之外那组多模态输入参数的源码默认值。

★★ `enable_thinking` 的三态：True、False 与那个「须谨慎」的 None

LlamaFactory 的 enable_thinking 不是一个开关而是三态字段，True、False 决定自动补出来的空 CoT 落在模型响应还是用户提示词、算不算损失，None 则让含 CoT 与不含 CoT 的数据走不同路径且官方明写「须谨慎」。本文按 data/README.md 与 data_args.py 的原文讲清三态各自的语义、那条训练推理必须一致的硬约束，以及怎么先确认自己的数据到底含不含 CoT。

`examples/` 的配方矩阵：18 个 extras 目录与算法开关一一对应

LlamaFactory 的 examples 目录常被当成一堆散配置来翻，实际上它是按四条互不相同的轴切开的。本文实读目录树，把 13 个一级目录归到「微调方式 / 生命周期 / 后端 / 算法」四条轴上，重点核对 extras 下 18 个子目录与 finetuning_args 里算法开关的对应关系，说清哪些能对上、哪几个在我们抽取的参数范围内找不到同名开关，以及找配置时该从哪条轴入手。

什么时候会自动走分布式：`launcher.py` 里的九个环境变量默认值

同一条 llamafactory-cli train 命令，在单卡和多卡机器上走的是两条启动路径，决定它的不是 YAML，而是 launcher.py 里的一段判断和九个只从环境变量读的值。本文按源码列出触发条件、九个默认值、Windows 与 Linux 的设法差异和判定方法。

GaLore 与 APOLLO 的参数表对照：同 rank 同间隔，scale 差 16 倍

LlamaFactory 把 GaLore 和 APOLLO 两组字段放在同一个参数文件里，默认值长得高度相似又有一处显眼差异。本文只做一件窄事：把两组字段的确切名字与源码默认值并排摆出来，指出哪几项完全对得上、哪一项相差 16 倍、APOLLO 多出的三个旋钮是什么，以及这张对照表能支撑到什么结论、到哪里就必须停。

下不动 Hugging Face：两个环境变量切到 ModelScope 与 Modelers

LlamaFactory 的 README 为「Hugging Face 下载有问题」这个场景准备了两个环境变量。本文按仓库当前内容讲清两个变量的写法、Windows 与 Linux/macOS 的差别、光设变量为什么不够、还要同步改哪个字段、三个 Hub token 各叫什么，以及什么情况说明你的问题不在下载源。

合并 LoRA 时那句全大写的 DO NOT 到底在禁什么

LlamaFactory 的 merge_lora 示例配置第一行就是一句 DO NOT 注释，禁止在合并 LoRA 适配器时使用量化模型或 quantization_bit。本文拆开这条禁令的两个对象，说清加载侧与导出侧量化是两组不同参数名，给出撞上它的判定动作、处置后的验证路径，以及什么情况说明问题不在这里。

`history` 里的历史回复也会被模型学习

很多人把 Alpaca 格式的 history 列当成"给模型看的上下文"，但 LlamaFactory 的 data/README.md 原文写得很清楚：监督微调时历史里的 response 也会被模型学习。本文按仓库当前文档与源码默认值，讲清这句话的准确范围、ShareGPT 侧对应的学习口径、同一条轴上的几个损失开关，以及一套可执行的自查动作。

量化五个参数，以及 NPU 场景为什么要关掉 `double_quantization`

LlamaFactory 的量化参数在 model_args 这一层只有五个，却常和导出侧那几个同前缀字段混为一谈。本文逐个照抄这五个字段的源码默认值，讲清它们坐在哪一层、和 export 前缀字段怎么分界，以及 README 在 Ascend NPU 那节让你写的 double_quantization false 与源码默认 True 的关系。

官方藏在 USAGE 里的短别名 `lmf`，以及不带参数时默认走 help

LlamaFactory 的 USAGE 帮助文本里有一句 Hint：`lmf` 是 `llamafactory-cli` 的短别名，但照 README 的 Quickstart 走一遍基本碰不到它。本文按源码讲清 Hint 在哪、`launcher.py` 里默认走 help 那行怎么读、短名不生效时怎么两步判定。

rsLoRA、DoRA、PiSSA、LoRA+：四个开关分别控制什么

LlamaFactory 把 rsLoRA、DoRA、PiSSA、LoRA+ 做成了同一个文件里的四组独立参数，默认全部关闭，且开关形态各不相同——有的是纯布尔，有的带配套数值，有的干脆没有 use_ 前缀的开关。本文按源码实读的默认值讲清这四组参数的确切名字、所在层次、彼此关系，以及为什么这篇不给你「该开哪个」的答案。

LlamaFactory 的 LoRA 参数：`lora_rank` 8、`lora_target` all，以及默认是 `None` 的 `lora_alpha`

很多人照着示例 YAML 跑 LoRA，却说不清那几行值是自己写的还是本来就有的。本文按 LlamaFactory 仓库当前源码，把 LoRA 这一圈参数的确切名字、确切默认值、它们各自住在哪个 hparams 文件里讲清楚，重点说明 `lora_alpha` 默认为 `None` 意味着什么、示例配置与源码默认值在哪几处不一致，以及为什么这篇不给你任何推荐值。

53 行模型表怎么读：为什么它不等于「100+ 模型」

LlamaFactory 的 README 顶部写着支持 100+ 模型，而 Supported Models 那张表实读只有 53 行，两个数字说的不是同一件事。本文讲清这张表三列各自的语义、第三列 template 才是要抄进 YAML 的值、表下六条注解里哪几条是硬规则，以及 `-`、`empty`、斜杠、`_nothink` 几种写法怎么读。

`_nothink` 后缀出现在哪三处，它在区分什么

LlamaFactory 的支持模型表里，Template 列有三个取值带 `_nothink` 后缀。这篇把这三行逐一找出来，讲清后缀在区分什么、它和 `enable_thinking` 参数分别坐在哪一层、为什么训练侧和推理侧必须填同一个值，以及表里那两处不成对的格子该怎么看待。

OFT 与 QOFT：三个参数与它们在训练矩阵里的位置

LlamaFactory 的训练方法矩阵里，OFT、QOFT 与 LoRA、QLoRA 并列成独立列头，但源码参数里 OFT 只有三个字段，且 oft_rank 默认值是 0 而不是 lora_rank 那样的 8。本文按仓库当前的参数定义，讲清这三个字段的名字、默认值、所在配置层，以及 QOFT 在参数表里对应到哪。

OpenAI 格式只是 sharegpt 的特例：`tags` 机制怎么做到的

手上一堆 OpenAI 风格的 messages/role/content 对话数据想喂给 LlamaFactory，第一反应往往是写转换脚本或把 formatting 填成 openai，两条都不对。本文按官方 data/README.md 原文拆开 tags 七个字段的两层结构，讲清 openai 为什么只是 sharegpt 的特例、改哪几个键能接上任意命名的对话数据。

`train/` 下没有 orpo 和 simpo 目录：它们是怎么被表达的

LlamaFactory 的训练方法矩阵列了 ORPO Training 和 SimPO Training 两行，但 src/llamafactory/train/ 下只有六个阶段目录，没有 orpo 和 simpo。本文按目录结构与 finetuning_args.py 的字段默认值，说清这两个名字落在哪一层、该去哪儿找代码。

`pref_beta` 0.1、`pref_loss` sigmoid：偏好对齐那一组参数

偏好对齐这一组参数很少出现在示例 YAML 里，但它们在源码里都有确切的默认值。本文按 LlamaFactory 仓库当前源码，逐个列出 pref_beta、pref_loss、simpo_gamma 等九个字段的名字与默认值，说清它们住在超参目录的哪一层、命名前缀能读出什么、默认 None 与默认 0.0 的区别，以及为什么这篇不给任何调参建议。

偏好数据集：`chosen` / `rejected` 与那个必须显式打开的 `ranking`

偏好数据集和监督微调数据集在 LlamaFactory 里的差别不只是多两列，还有一个默认关闭、必须手写打开的顶层开关 ranking。本文按 data/README.md 原文讲清 chosen 与 rejected 两列的默认值状态、ranking 字段所在的层级、alpaca 与 sharegpt 两种写法的对应关系，以及配置写漏时可以怎样逐项比对着查。

评测默认 5-shot、种子 42：LlamaFactory 的七个评测参数

LlamaFactory 把评测参数单独放在 evaluation_args.py 里，一共七个字段。本文按源码里读到的默认值逐个说清：task_dir 是裸目录名、batch_size 为 4、seed 固定 42、lang 默认 en、n_shot 默认 5、save_dir 为 None，以及这组参数不管的三件事。

LlamaFactory：PPO 的六个参数与四个参考/奖励模型字段

想在 LlamaFactory 里跑 PPO，先要搞清的不是算法，而是配置里有哪些字段、源码默认值是多少、分别住在哪一层。本文按 src/llamafactory/hparams/ 的实读结果，列出五个 ppo_ 前缀参数、stage 字段，以及参考模型与奖励模型那七个字段，并说清量化字段为什么在两个文件里各有一套。不给调参建议。

训练、推理、合并三条命令：README 唯一抬进 Quickstart 的闭环

README 只把 train、chat、export 三条命令抬进了 Quickstart，它们不是三个独立 demo，而是字段严格对齐的一条链。本文逐行对照三份 YAML，讲清靠哪几个标识串起来、哪些字段必须两侧一致、合并那步的大写禁令原文写的是什么，以及 Windows 侧的写法差异。

★ human 在奇数位、gpt 在偶数位：ShareGPT 的位置约束

LlamaFactory 的 ShareGPT 格式在 data/README.md 正文里夹着一条位置约束：human 与 observation 在奇数位、gpt 与 function 在偶数位，且 gpt 与 function 会被模型学习。本文讲清这条规则的文档口径、怎么按下标自查、它与 tags 的关系。

LlamaFactory 生成参数默认值：`temperature` 是 0.95、`top_p` 是 0.7，不是你以为的那组

很多人凭印象记得的生成默认值是温度 0.7、top_p 0.9，而 LlamaFactory 的 generating_args.py 里源码默认写的是 temperature 0.95、top_p 0.7。本文把这一层十个字段的默认值逐个列出来，说清它们写在 hparams 的哪个文件、和推理后端那几个同样是 0.7 的参数不是一回事，以及为什么这类数字必须回源码核而不是靠记。

LlamaFactory 到底是什么：零代码 CLI + Web UI 的微调工厂

LlamaFactory 常被当成一个微调脚本合集，它实际提供的是一层统一入口，把模型、数据格式、训练方法、实验跟踪和推理服务收进同一套命令行与界面。本文按官方仓库当前内容，讲清它的身份坐标、零代码具体指什么、八条特性各自收敛哪一层、三条免装环境的云端试用路径，以及它明确外包出去、不替你做的那几件事。

`report_to` 的五个取值与 SwanLab 的九个字段

LlamaFactory 的实验跟踪配置分散在两层：示例 YAML 注释里的 `report_to` 五个取值，和 `finetuning_args.py` 里成组的九个 SwanLab 字段。本文逐个核对它们的确切拼写、默认值与所在层级，讲清哪两个字段有非空默认、密钥字段怎么脱敏，以及哪些联动逻辑我们没读过因此不做推断。

`cutoff_len` 2048、`val_size` 0.0：数据侧 28 个参数的默认值

LlamaFactory 的数据侧参数定义在 hparams/data_args.py，一共 28 个，大多数人只显式写了其中三四个，剩下的都在按默认值跑。本文按仓库当前源码把这 28 个默认值列全，按「数据从哪来、截多长、哪部分算损失、切不切验证集、怎么打包」分组解释怎么读这张表，并指出 dataset_dir 在两处文档里写法不同这一处差异。

四个数据来源字段的覆盖链：谁指定了就忽略谁

LlamaFactory 的 dataset_info.json 里有五个字段都能指定数据从哪来，它们不是并列关系，而是官方字段说明里写死的四档覆盖链：上游一旦填了，下游几个字段按原文直接被忽略。本文按 data/README.md 原文逐档拆开这条链，讲清 file_name 什么时候才是必填、数据改了没生效该先看哪一行、验证时看什么，以及哪些问题根本不属于这条链。

`MAX_RESTARTS` / `RDZV_ID` / `MIN_NNODES`：被标为弹性启动的那组变量

LlamaFactory 的分布式行为不写在命令行参数里，而写在 launcher.py 读的一串环境变量里。本文逐个核对这组变量在源码中的确切名字与默认值，说清其中哪三个压根没有默认值、分布式路径要满足什么条件才会被触发、怎么从日志确认自己走的是哪条分支，以及为什么这篇不给任何推荐值。

训练和推理必须用同一个 `template`，这是 LlamaFactory 最容易翻车的一条

LlamaFactory 的 README 在模型表下方用一句全大写的注解要求训练与推理使用同一个 template，但这个参数分散在训练、推理、合并导出三份不同目录的 YAML 里。本文按仓库当前内容说明它出现在哪几层、三份示例配置怎么严格对齐、怎么逐项比对确认自己是不是踩了这条，以及哪些情况可以把这条排除掉。

LlamaFactory 的 `trust_remote_code`：源码默认 `False`，示例 YAML 全写 `true`

同一个开关，在 LlamaFactory 的源码默认值和官方示例配置里给出的是两个不同的取值。本文按仓库当前内容把这处差异摆清楚：它写在哪个文件、和哪些参数同住一层、为什么在训练推理合并三份配置里各出现一次、你怎么用一条命令确认自己当前跑的是哪一种取值，以及为什么这篇不给你「该不该开」的结论。

四个推理后端：huggingface、vllm、sglang、ktransformers

LlamaFactory 的 infer_backend 只有四个合法取值，它们散落在示例 YAML 的注释、model_args.py 的默认值和 README 的命令行示例里。本文把出处逐一钉死，讲清这个字段坐在哪一层、怎么在命令行覆盖它、四个后端各占几个专属参数，以及官方没给数据的维度我们为什么不比。

一个 `USE_V1` 环境变量背后：仓库里并存的两套实现

LlamaFactory 的入口文件 cli.py 除许可证头外只有十几行，核心是一个 if：环境变量 USE_V1 决定加载 v1 目录下的 launcher 还是旧的 launcher。本文逐行拆这段代码，实读 v1/ 的目录结构与配套的 tests_v1/、examples/v1/，说清双轨并存对查资料、对齐文件路径意味着什么。

vLLM 与 SGLang 的参数是对称设计的，差异只有四个字段

LlamaFactory 的 vLLM 与 SGLang 后端参数在 model_args.py 里成对出现：最大长度都默认 4096、显存占比都默认 0.7、各有一个默认 None 的配置口子，真正不成对的只有四个字段。本文核对这十个字段的名字与源码默认值，说清它们住在哪一层、哪些跨层同名词根不是一回事。

`llamafactory-cli webui` 与 LlamaBoard：它在这套体系里的位置

很多人把 LlamaFactory 的 Web UI 当成"另一个产品"，其实它只是同一个 CLI 入口下的一条子命令。本文按官方仓库当前内容，讲清 USAGE 里那一行原文写了什么、LlamaBoard 与 webchat 的分工、启动前必须先落地的安装与环境变量、以及为什么 API 那条的端口口径不能套到它头上。

★ 显存表怎么读：`* estimated` 这四个字与那个对不上的格子

LlamaFactory 的 Hardware Requirement 表被当成选卡依据，但表头上方那行 `* estimated` 说明它是官方标注的估算而非实测占用。本文逐格照抄这张表，讲清它的四个坐标轴怎么读、行为什么是「方法加精度」的组合、通用列的系数是什么意思，并如实指出 2-bit 那一格与通用列公式对不上的地方。

8 × 6 全打勾的训练方法矩阵：这张满表能读出什么、不能读出什么

LlamaFactory 的 README 里有一张 8 行训练阶段乘 6 列微调方式的矩阵，48 格全是对勾。这篇不复述那张表，而是讲清楚「全勾」这个声明的准确边界：它说的是可组合，不是同样成熟；并用 train/ 的目录结构、examples/ 的配方章节分布、显存表和 template 规则这三处可核实的旁证，说明这张表读不出来的东西该去哪里找。

八个必需依赖与五个可选依赖：版本下限和推荐值分别卡在哪

LlamaFactory 的 README 里有两张 Requirement 表，八条 Mandatory、五条 Optional，每条都分 Minimum 与 Recommend 两列。这篇逐格摊开这十三行，讲清哪一行是硬下限、哪几条只在你用到对应功能时才需要，以及为什么官方没给版本组合矩阵。

LlamaFactory 预训练数据：只用 `text` 列，以及 sharegpt 为什么不支持预训练

LlamaFactory 的预训练数据格式是 data/README.md 里最短的一节，一个 text 列就是全部；而 sharegpt 那侧的同名小节只有一句「尚不支持，请用 alpaca 格式」。本文按仓库当前文档讲清预训练数据长什么样、dataset description 怎么写、这条能力边界意味着什么。

H3 的 2K 为什么不是超分：H3-Regenerate-2K 的 in-context 重生成读法

MiniMax H3 的 2K 输出不是在 768p 结果后面接一个专用超分模块，而是把低分结果连同原始多模态上下文一起送回基础模型重新生成。本文按官方仓库口径讲清这条路径的两条理由、它与传统超分的差别究竟在哪一层、H3-Regenerate-2K 未开源只有 API 的现状，以及为什么不能把 ComfyUI 模板里 megapixels 2.0 那一档误当成 2K 来用，帮你分清「H3 支持 2K」和「开源版能出 2K」这两句话。

MiniMax H3 的原生立体声是怎么做出来的：H3-AudioVAE 与音视频联合预测

按官方仓库口径拆解 MiniMax H3 的音频路径：左右声道共用一套 encoder/decoder 但独立处理、每声道把 32kHz 压成 40Hz 的 latent 序列、config 里音频 latent 维度为 32，并说清「原生立体声」为何指联合预测而非后期配音。

本地部署 H3-Base 的完整路径：从下载范围到 SGLang 起服务

按 MiniMax H3 官方仓库 README（2026-08-09 快照）梳理本地部署 H3-Base 的路径：两条验证路径怎么选、两个 checkpoint 对应什么任务、hf download 为什么必须加 --include、requirements.txt 里 diffusers 分支的坑，以及起服务后该检查哪几处。

Ref2VA 的参考标签体系：<Subject N> / <Picture N> / <Video N> / <Audio N> 怎么用

MiniMax H3 的全参考模式 Ref2VA 靠一套参考标签把素材与提示词绑在一起。本文按官方 h3-prompt-writing skill 与 ComfyUI 官方 R2V 模板的口径，讲清四类标签的分工、六段式章节的固定顺序、subject_definitions 与 retention_analysis 的写法规则，以及「按连接顺序引用」这条工程约束。

音视频联合 latent 是怎么解码成一个 MP4 的

MiniMax H3 的 Omni-Transformer 联合预测视频与音频 latent，落到 ComfyUI 节点图上就是一根 LATENT 线同时接进 VAEDecode 与 VAEDecodeAudio，再由 CreateVideo mux 成 MP4。本文按官方模板与教程页口径拆开这条链路并给出选择依据。

MiniMax H3 的五个模型文件分别放哪：ComfyUI 侧的下载来源、目录对应与验收方法

在 ComfyUI 里跑 MiniMax H3 要准备五个模型文件，最常见的翻车不是放错目录，而是从 MiniMaxAI/MiniMax-H3 下了官方 BF16 权重。本文按官方教程与模板文件梳理五个文件与目录的对应关系、下载地址形态、fl2va 与 ref2va 两套权重的区别，以及放完之后怎么在节点里验收。

在 ComfyUI 里跑 MiniMax H3：版本门槛、模型放置与 R2V 模板节点链拆解

按官方文档口径梳理 MiniMax H3 在 ComfyUI 里的上手路径：0.30.0 版本门槛与 v0.31.0 的 H3 VAE 修复、五个模型文件该落到哪个目录、T2V/I2V/R2V 三个官方模板的区别，以及 R2V 节点链怎么读、怎么验收、什么情况别这么干。

用 diffusers 跑 MiniMax H3 的第一个坑：`pip install diffusers` 装到的版本可能没有 H3 模型类

MiniMax H3 官方仓库的 requirements.txt 注释里藏着一条很容易被跳过的信息：模型是作为 diffusers pipeline 发布的、通过 trust_remote_code 加载，而官方文档指向的是 diffusers 的 minimax-h3 分支。也就是说直接装 PyPI 版本，版本号能达标却可能不含 H3 的模型类，装成功不等于装对了。本文按官方仓库口径讲清这条依赖该怎么装、安装顺序为什么重要、transformers 与 accelerate 各自卡在哪一环，以及怎么一步步判断自己是不是已经装错了环境。

MiniMax H3 提示词里的 `<d>` 标记、说话人 ID 与旁白怎么写

拆解 MiniMax H3 官方 h3-prompt-writing skill 对白部分的硬规则：(S1)/(S2) 说话人 ID 如何跨镜头保持一致、身份描述为什么必须写在 <d> 之外、旁白为什么要固定短语加嘴唇闭合说明、台词跨切点时 <scenetrans> 与 <cutoff> 的用法。

为什么必须用 MiniMax H3 自带的 tokenizer：从 H3-Encoder 的接口说起

MiniMax H3 官方要求必须使用仓库自带的 tokenizer 与配置文件。按官方仓库口径讲清 H3-Encoder 与 Qwen3-VL-32B 的关系、model_index.json 里两个类名为何不对称、新增特殊 token `<d>` 承担的对白边界职责，以及下载与自查该看哪几个文件。

MiniMax H3 的 Full 2K Workflow：本地 SGLang 服务 + 官方 API 怎么串成一条链

拿到 MiniMax H3 开源权重后会发现，本地只能跑到 768p，2K 必须回到官方 API。这篇按官方仓库 README 口径拆解 Full 2K Workflow 的完整链路：权重下载范围怎么限定、SGLang 两个变体如何分端口起服务、三个环境变量和三个 API 端点分别对应哪一步、base_video 用 Base64 还是公开 URL、以及三个官方 case 的规格与验收要点。

十二种运镜怎么写进 MiniMax H3 提示词：Zoom 与 Push 到底差在哪

MiniMax H3 官方 h3-prompt-writing skill 把运镜拆成运动类型、幅度、速度三要素，给出十二种运动类型。本文讲清 Zoom 与 Push、Pan 与 Truck、Tilt 与 Pedestal 三组易混写法的区别，以及幅度速度何时该省、运镜和切镜怎么选、后续镜头时间戳格式怎么写才合规。

H3 开源了什么、没开源什么：三个模块的开放状态逐条拆开

MiniMax H3 放出权重，但开源的只是三个模块中间那一层，前后两层只提供 API。按官方仓库 2026-08-09 的 README 口径拆开 H3-Context-IR、H3-Base、H3-Regenerate-2K 的开放状态，说清为什么拿到权重不等于拿到官方效果，并给出走 API 还是本地权重的判断路径。

33B Omni-Transformer 的结构：MiniMax H3 里那 13B 参数为什么推理时不用加载

MiniMax H3 的 Omni-Transformer 是 33B 的 dense 单流结构，官方 README 说其中约 13B 参数位于 AdaLN 分支，调制输出可预先计算并缓存，仅推理的部署不需要加载。本文按官方仓库 README 与两份 config.json 逐条拆开：模态特定参数落在哪、MM-RoPE 为什么是三维、那张五十层五十六头的硬参数表怎么与文字互相印证，哪些数字看着像结论其实不能拿来做任何换算，以及为什么「原生支持稀疏注意力」和「开源版只能跑 full attention」必须分开说。

下载 MiniMax H3 权重时别下重了：`--include` 到底在挡什么

MiniMax H3 仓库把原始 checkpoint 与 diffusers 格式并排托管，不加限定条件全量拉会把两套都拖下来。本文按官方仓库口径讲清 FL2VA/ 与 Ref2VA/ 的结构、README 两条 hf download 命令里 --include 挡掉了什么、diffusers 用户为何不必手动下载，以及下完怎么验收。

用 SGLang 起 H3 服务：两条官方命令怎么抄、怎么验收

MiniMax H3 官方 README 给了 SGLang 的部署示例，FL2VA 与 Ref2VA 是两条独立命令、分别占用 30010 与 30011 端口。本文逐项拆解这两条命令里的每个选项、说明哪些选项我们只能照抄不能解释、权重该下哪些目录、起完服务人要检查哪几处，以及哪些场景根本不该走这条路。

H3 提示词的三个核心字段：对齐指令、字段顺序与 Ref2VA 的分工

MiniMax H3 官方 h3-prompt-writing skill 把提示词拆成一行对齐指令加三个顺序固定的核心字段。本文按官方仓库 2026-08-09 的快照，讲清五种输入模式各自要不要写对齐指令、三条指令的原文长什么样、时间为什么必须精确到两位小数、三个字段分别管哪一层画面与声音、字段名为什么一个字都不能改动，以及 H3-Context-IR 尚未开源时自建提示词流程的边界究竟在哪里。

H3-VisualVAE：f16t4d24 是什么意思

MiniMax H3 的视频自编码器被官方记作 f16t4d24，这串符号里藏着空间 16 倍、时间 4 倍、24 个 latent 通道三件事。本文拆开这个记号，讲清 patch size 1×2×2 如何把有效空间下采样推到 32 倍而时间仍是 4 倍，并用仓库里 config.json 的 in_channels 与 patch_size 做交叉印证，顺带说明额外训练的 ViT decoder 解决的是什么问题。

稀疏注意力：能力与发布状态是两回事

MiniMax H3 的 README 里有两句话挨在一起：模型原生支持稀疏注意力的训练与推理，以及首次开源发布只提供 full attention 的推理、稀疏实现将在未来更新中发布。很多转述把前半句留下、后半句丢掉，于是变成「开源版支持稀疏注意力」。这篇拆开讲清楚这两句分别在说什么、稀疏注意力对长多模态序列意味着什么，以及为什么不能顺手推出任何性能结论。

MiniMax H3 是什么：一个全模态生成系统

从官方仓库口径梳理 MiniMax H3 的系统骨架：它是什么定位、输出规格有哪些硬性上限、三个模块里哪一个开源了哪两个没有、两个 checkpoint 分别对应什么任务、参考输入最多能塞几个文件。看完你能自己判断该走官方 API 还是拿开源权重本地跑，以及下一步该去查哪份文档。

OpenCut Actions 系统：快捷键、按钮、右键菜单的统一触发层

OpenCut 旧版（classic）把键盘快捷键、界面按钮、右键菜单收拢到同一个 Actions 触发层。本文按官方 docs/actions.md 拆开这套机制，逐条给出你自己要做的判断：一条 action 定义包含哪四个字段、什么操作该登记进来、七个 category 枚举怎么选、什么时候该给 defaultShortcuts、用到特殊键为什么要动 getPressedKey，以及为什么改了默认快捷键就必须补一份 keybindings 迁移——快捷键持久化在 localStorage 里，新的默认值只对全新安装生效，这个坑在开发机上几乎不可能复现。

从 0.1.0 到 0.3.0：官方 changelog 记了些什么

OpenCut 重写版仓库的 changelog 里有 0.1.0、0.2.0、0.3.0 三份记录，条目数 14、19、52。本文不复述功能清单，只讲三件事：这些记录的归属为什么必须先存疑、new / improved / fixed 的分布怎么读、把它当成「某功能现在能不能用」的依据时会在哪一步翻车。

重写版的栈：TanStack Start、Vite、Cloudflare 与 Rust gpui

OpenCut 重写版换了整套技术栈：proto 加 moon 钉死 moon 2.3.3、bun 1.3.11、rust 1.97.0，web 端用 TanStack Start 加 Vite 部署到 Cloudflare，桌面端 Rust 加 gpui 0.2.2。本文按配置文件逐层拆开每层约束了什么。该版本尚未发布。

本地把 classic 跑起来：Bun、Docker 与四条命令

OpenCut 有两个仓库，能在本地跑起来的是已归档的 classic 旧版。这篇按官方 README 原文梳理它的启动路径：装什么前置、复制哪个环境变量文件、起哪三个容器、四条命令的先后顺序、服务落在哪个端口，以及桌面端与 WASM 这两条 opt-in 分支该不该碰。

一个已归档的仓库还能用吗：把话说清楚

OpenCut 旧版仓库 opencut-classic 已归档、不再维护，但官方 README 说 opencut.app 线上跑的仍是它。归档到底意味着什么、又不意味着什么？本文不罗列参数，而是从五种常见处境出发——只想在线用、想本地跑一份、想读代码学架构、想提 PR、想给团队做选型——把「还能不能用」拆成能自己判断的几步，同时划清「归档」这个词的边界，并交代哪些结论我们手里没有依据、不替你下。

classic 的技术栈：Next.js、Rust WASM 与浏览器里的媒体处理

拆开 OpenCut classic（旧版，已归档）的仓库结构：apps/web 的 Next.js 应用、rust/ 下六个 crate 与发布为 opencut-wasm 的 WASM 包，以及 60 个 web 依赖里媒体与 AI 相关的那几个。重点讲清 TypeScript 与 Rust/wgpu 的分工边界，帮你判断一个改动该落在哪一层、要不要装 Rust 工具链。

改 Rust 那部分：本地 WASM 开发的四步链路

OpenCut 旧版（classic）把 GPU 合成器、特效、蒙版都放在 rust/ 目录里，编译成 WASM 给浏览器用。如果你只改 TypeScript，这条链路完全不用碰；一旦要动 rust/wasm，就得先装 Rust 工具链和 wasm-pack，再走构建、注册包、链接、监听重建这四步。本文逐条拆解 README 给的命令、每一步的产出物落在哪个目录、验收时人要看哪几处，以及哪些情况根本不该走这条路。

为什么模糊要分两趟：单 pass、多 pass 与 buildPasses

OpenCut classic 的特效系统把一次渲染拆成 pass 数组。这篇按官方架构文档讲清三件事：判断一个特效必须写多 pass 的依据是什么，pass 数量随参数变化时怎么用 buildPasses，以及一条最容易踩空的规则——buildPasses 一旦存在，静态 passes 数组就完全不参与渲染。

关键帧系统的三层：数据模型、注册表、UI

拆解 OpenCut 旧版（classic）仓库 docs/keyframes.md 描述的关键帧分层：数据模型怎么存关键帧、注册表怎么声明哪些属性可动画、UI hooks 怎么在静态值与动画通道之间自动切换，并给出你要新增一个可动画属性时该在哪一层落笔的判断依据。

改了默认快捷键老用户拿不到，因为它存在 localStorage 里

在 OpenCut classic 里给一个 action 加了 defaultShortcuts，全新环境能用，已经用过编辑器的环境却没反应——这不是缓存没清，而是快捷键被持久化在 localStorage，新的默认值只对全新安装生效。本文按现象、怎么确认、文档给出的处置、处置后怎么验证、什么情况不是这个原因五步走，并说清它和特殊键没注册这条岔路的区别。

Editor API、插件、MCP server、无头渲染：五条承诺目前都还是承诺

OpenCut 重写版主仓 README 列出的 Editor API、第三方插件、跨端共用一套 Rust 核心、MCP server、无头批量渲染，目前全部是官方声明的计划，不是已有能力。本文按核对日 2026-08-09 的仓库快照，逐条对照重写版仓库里实际存在的目录、Cargo.toml workspace 成员与 moon 任务，给出一套你自己十分钟内就能重复一遍的核查动作，并说清现在该用哪个仓库、旧版 classic 已归档意味着什么、什么时候值得回头再看一眼。

inputs、outputs、deps：任务缓存的粒度是自己声明出来的

OpenCut 重写版仓库的 apps/web/moon.yml 用 inputs、outputs、deps 把任务缓存的粒度写成了声明。本文逐字段拆开这份配置，讲清 dev 为什么标 runInCI false、build 的 inputs 为什么只列五项、deploy 为什么用 deps，并给出自己项目该怎么写的判断顺序。

从 Next.js 到 TanStack Start：两份 package.json 的差异

OpenCut 旧版（classic）的 web 应用建在 Next.js 上，重写版换成了 TanStack Start 加 Vite。本文逐段核对两个仓库里能查到的依赖与脚本差异——框架、构建、部署、测试这四条线各自换到了什么，哪一层原封不动地平移了过来，Rust 核心的位置又落在哪里，以及端口和启动命令变成了什么样子，最后给出一套从依赖清单反推项目所处阶段的可操作读法。不猜动机，不比优劣，只陈述两份文件里写着的东西。

三行配置钉死整个团队的工具版本

OpenCut 重写主仓根目录的 .prototools 只有三行，把 moon、bun、rust 的版本钉死在仓库里。本文拆开这三行，给出从装 proto 到起服务的完整命令（Windows 与 Linux 分开），说明配套 moon.yml 的 inputs、outputs、deps 各解决什么，以及这套做法何时不适用。

六个 crate 的分工：compositor、effects、gpu、masks、time、bridge

OpenCut 旧版（classic）把 Rust 核心切成了六个 crate。这篇不翻译源码，而是回答一个更实用的问题：拿到这个目录，你怎么判断要改的东西该落在哪一层、哪些结论有依据、哪些只是名字带来的联想。附官方文档的 TypeScript 与 Rust 分工边界、gpu 的跨端线索与本地 WASM 链路。

OpenCut 现在有两个仓库，你该看哪一个

OpenCut 现在有两个 GitHub 仓库：主仓 OpenCut-app/OpenCut 正在从零重写、尚未发布，而已归档的 OpenCut-app/opencut-classic 才是 opencut.app 线上仍在跑的那个。这篇按仓库元数据、README 原文和实读目录结构，把两边的状态、技术栈、开发端口、工具链版本与官方路线图逐条分开摆清楚，并给出一条从你自己的处境（要剪片、要本地跑、要读架构、还是想提交贡献）倒推该看哪个仓库的判断路径，顺便说明为什么不能把官方声明的计划当成现成能力。

TypeScript 决定跑什么 shader，Rust 和 wgpu 负责怎么跑

OpenCut 旧版（classic）的特效文档写了一句很干脆的分工话：TypeScript 决定跑哪些 shader 标识符、传哪些 uniform，Rust 和 wgpu 拥有设备创建、纹理与 pass 执行。这篇文章拆开这条边界，讲清一个特效在代码里究竟由哪几个字段构成、判断需不需要多 pass 的标准是什么、`buildPasses` 一旦出现静态 passes 数组为什么会悄悄失效，以及你手上的这个改动到底该落在 TypeScript 一侧还是 Rust 一侧，顺带划清旧版与重写版的差别。

加一个可动画属性要动几个文件

想给 OpenCut 旧版（classic）的时间轴元素加一个能打关键帧的属性，到底要碰几个文件？本文按官方 docs/keyframes.md 的口径拆开：两处必须注册、两处必须读懂、UI 层两个 hook 怎么挑，附可直接复制的本地开发命令、改完后的验收清单，以及哪些情况根本不该走这条路。全文只依据仓库文档与源码结构，不含任何运行结果。

用 Rust 和 gpui 写桌面端：现在只有一个外壳和四个面板

尚未发布的 OpenCut 重写版桌面端用 Rust 加 gpui，但 apps/desktop/src 下只有三个顶层源文件和四个面板，根 Cargo.toml 里 crates/* 还被注释着。本文核对这个目录的真实内容、workspace 0.1.0 与 edition 2024 声明、proto 加 moon 钉死的工具链，并给出复核「Rust 核心到位没有」的动作。

「你的编码助手就是编排器」：十一步流程图逐段读

OpenMontage 的 README 首页有一张十一格的流程图，很多人当宣传图翻过去了。本文逐格把它对回仓库里的文件与字段：哪一格读 YAML manifest、哪一格读阶段导演 skill、哪几格才真有代码在执行、哪一格对应 config.yaml 的默认值，以及这张图与 Rule Zero 之间可核查的差异。

五个 agent 平台各有一个配置文件，都指向同一份契约

OpenMontage 为 Claude Code、Cursor、Copilot、Codex、Windsurf 各准备了一个配置文件，五份文件最后都指向同一份 AGENT_GUIDE.md。本文从这个设计讲起，说清它为什么必须这么做、契约里真正约束了什么、以及这种约束的性质是什么。

Backlot 活体故事板：把审批闸做成一块本地看板

OpenMontage 的 Backlot 是一块随流水线自我填充的本地看板，README 把它定位成「看制作实际在做什么」。本文按 README 原文拆它的三条命令、逐场景样片接触表这道真正的审批闸、上墙的成本数字性质，以及我们没有运行过它因而不能说的那部分。

从一段你喜欢的视频开始：参考视频入口给你回什么

OpenMontage 的 README 主推「从一段你已经喜欢的视频开始」。本文拆开这条入口的四项返回承诺，落到 documentary-montage 的 manifest 里 reference_input.supported 为 false 这个可核查的开关上，说清它在哪条流水线上不成立，以及成本估算该怎么读。

OpenMontage 的 `config.yaml` 全文逐键读：LLM、预算、检查点、输出、路径

OpenMontage 把流程写在 YAML 和 Markdown 里，唯一一份全局配置只有五段三十来行。本文逐键读这份 config.yaml：默认 provider 是谁、预算默认为什么是 warn 而不是 cap、checkpoint 策略与路径段里那处重复的默认值，以及哪些键 README 根本没提。

OpenMontage 的 `scoring.py` 里还有第二套评分，README 一个字没提

OpenMontage 的 README 只讲了 provider 选择那套 7 维评分，但 lib/scoring.py 里还有第二套加权求和，维度名完全不同。本文对照两处源码行号，说清我们能确认什么、不能确认什么，以及读这类「文档即产品」的仓库时该怎么把 README 当入口而不是全集。

检索优先的纪录片蒙太奇：不用付费视频模型也能出真素材片

OpenMontage 的 documentary-montage，是 README 那张流水线表里唯一一行把「检索」而不是「生成」写进产物描述的。本文照抄它 manifest 里的 description、预算、修订上限与第一个阶段的字段，说清「不用付费视频生成 API」这条路具体靠哪几个 provider 撑住、哪些环节仍然要你自己批。

三本风格 playbook 控制什么：排版、配色、动效、音频与质量规则

OpenMontage 的 Style System 给了三本内置 playbook 和一句职责清单，但 playbook 实际内容我们没读过。本文把排版、配色、动效、音频、质量规则五维对回可核查的位置：manifest 的 palette 与 music plan 字段、extensions 里唯一那个 false。

WhisperX 词级时间戳与 CLIP 检索：四个分析工具串起了哪些能力

OpenMontage 的 Analysis 一栏只有四行，却串起了字幕、素材检索和渲染后自检三条链路。本文从 README 的四行分析工具表出发，落到 documentary-montage.yaml 里的 budget_default_usd、custom_tools、reference_input 等具体字段值，说清词级时间戳和 CLIP 检索各自接的是哪一头。

渲染完还要自检：ffprobe、四点抽帧、音量分析与承诺核验

OpenMontage 把渲染完成当成新一道闸的开始。本文拆 README 列的渲染后自检五项——ffprobe 校验、4 个位置抽帧、音量分析、交付承诺核验、字幕存在性检查，并落到 lib/delivery_promise.py 里 min_motion_ratio 0.7 与 quality_floor 默认 presentable 这些真实数值上，说清它查什么、不查什么。

六个维度、0-5 分、四档判定：OpenMontage 怎么防「会动的 PPT」

OpenMontage 把「视频做出来像幻灯片」这个失败模式写成了一个打分模块。本文照抄 `lib/slideshow_risk.py` 的 docstring，逐条解释六个维度在问什么、2.0/3.0/4.0 四档判定怎么读、空场景为什么直接判 5.0 失败，以及这个分数在合成前的质量闸上卡在哪一步。

八种交付承诺：哪两种不许退回静图

OpenMontage 在选 provider 之前先把这条片子「承诺交付什么」写死。本文按 lib/delivery_promise.py 的实读内容拆开 PromiseType 的八个取值、PROMISE_RULES 的三列规则与 min_motion_ratio 的五档取值，说清哪两种承诺不允许退回静图。

OpenMontage 的七个阶段：research → proposal → script → scene_plan → assets → edit → compose

OpenMontage 的 README 用一行箭头写死了阶段流。本文把它落到 pipeline_defs/documentary-montage.yaml 的实读字段上：阶段靠 produces 与 required_artifacts_in 相连、一个阶段有哪几个键、打回与修订上限写在哪、命名哪里对不上。

一个阶段的八个字段：produces、review_focus 与 success_criteria

OpenMontage 的流水线 manifest 里，真正决定一个阶段怎么跑的是 stages 下那八个字段。本文以 documentary-montage 的 idea 阶段为样本，拆开 produces、tools_available、review_focus 与 success_criteria，说清后两者差在哪、阶段之间的 artifact 依赖靠什么串起来。

决策审计链路与 20 个 artifact 契约

OpenMontage 的决策日志跨阶段持久化，被取代的 checkpoint 会归档，降级必须显式批准。本文落到 slideshow_risk 的 render_runtime、delivery_promise 的 approved_fallback 三态与 schemas 目录 20 个 artifact 契约上。

零 API 密钥能做到哪一步：七行能力表逐行拆

OpenMontage 的 README 有一张「零 API 密钥能得到什么」的七行表，读起来很诱人，但边界藏在括号里。本文逐行拆这七行，说清哪一行其实要申请免费密钥、哪一行只是前置依赖、render_runtime 在提案阶段就被锁死意味着什么，以及为什么零密钥不等于零外部服务。

一份 manifest 有哪些字段：从 `stability: beta` 说起

OpenMontage 的流水线流程写在 pipeline_defs 下的 YAML manifest 里。本文以实读 documentary-montage.yaml 前 70 行为样本，拆开顶层元信息、reference_input、orchestration 与 required_skills 各自落到哪个具体值。

十四个可选密钥：每个解锁什么，不加会退到哪

OpenMontage 的 README 在 .env 段列了 14 行配置，原文强调 every key is optional。本文按注释逐行拆开这 14 行各自解锁什么能力，再回到零密钥能力表，说清每一类不加密钥时会退到哪条免费路径，以及为什么不能拿 .env 猜自己的真实能力边界。

★ `min_motion_ratio: 0.7` 那行注释：什么才算「真实动效」

OpenMontage 的 lib/delivery_promise.py 里，motion_led 这一行把动效比例下限定在 0.7，注释把「真实动效」反向定义为「不是 Remotion 幻灯片」。本文顺着这个数字，讲清它在哪、和另外三档差在哪、被谁在什么阶段拦一次，以及你该不该把片子标成 motion_led。

OpenMontage 的目录与 README 架构图对不上：五个 tools 子目录没写进去

照着 OpenMontage README 的目录树去仓库里找文件，会漏掉 tools/ 下的五个子目录和根目录下的两个目录。本文把 README 架构图与实读目录逐层摆在一起，指出差在哪几处、哪些计数吻合、哪些不吻合，以及为什么治理数值反而是对得上的。

两条命令查清你到底有什么：OpenMontage registry 的三个方法

OpenMontage 的 README 列了一长串 provider，但表上有的不等于你这台机器上能用的。本文按仓库文档拆开那两条 registry 查询命令、三个方法的调用形式、AGENT_GUIDE 里 preflight 的强制条款，以及几处 provider 计数口径的差异，说清为什么要用命令而不是读表。

OpenMontage 的 Node 版本口径：前置要求写 18+，HyperFrames 那行标的是 ≥ 22

OpenMontage 的 Quick Start 把 Node.js 18+ 列为前置条件，而 README 后面的合成运行时表里，HyperFrames 那一行标的是 Local (Node.js ≥ 22)。本文把这两处原文摆到一起，说清差异落在哪、什么时候真的会碰到它、动手前怎么确认自己处在哪一档。

八个平台档位其实只有五组分辨率

OpenMontage 的 README 列了 8 个平台输出档位，去重之后只有 5 组分辨率，竖屏三家完全共用一组。本文把这张表逐行拆开，对上 config.yaml 里 default_resolution / default_fps / default_crf 的实际默认值，说清这张表给了什么、没给什么。

Python 只提供工具和持久化：编排逻辑为什么不写在代码里

OpenMontage 把编排逻辑、创意决策、评审标准全部搬出 Python，放进 YAML manifest 和 Markdown skill。本文从 AGENT_GUIDE 的原文分工、lib/ 与 tools/ 的实读清单、723 个 skill 文件的计数，说清这条分界线划在哪里、改行为要改哪个文件，以及这种设计要你付出什么代价。

OpenMontage 七维评分权重 30/20/15/15/10/5/5：文档与代码逐项吻合

OpenMontage 的 README 说每次工具选择都跑一个 7 维评分引擎，权重 30/20/15/15/10/5/5，这一次它和 lib/scoring.py 第 38-44 行的实现逐项对得上。本文把两处源码摆出来，讲清这组权重表达了什么取向、同一文件里那套 README 没提的评分，以及「对得上」的边界。

四个前置条件与 `make setup`：从 clone 到出片的路径

OpenMontage 的 Quick Start 只有三条命令，但前置条件有四项，其中第四项不是环境依赖而是「你得有个 AI 编码助手」。本文按顺序拆四个前置条件、make setup 与两套手动安装串、Windows 已知问题，以及装完之后怎么自查、README 说接下来会发生什么。

不是每条流水线都吃参考视频：`reference_input.supported` 这个字段

OpenMontage 主推「从参考视频开始」，但 documentary-montage 的 manifest 里 reference_input.supported 为 false。本文说清这个字段在哪一层、怎么自己核查，以及同一份 manifest 里还有哪几处同样写死的能力边界。

Rule Zero：所有制作都必须走流水线，五步与五条禁令

OpenMontage 的 AGENT_GUIDE.md 里有一节 Rule Zero，要求任何视频制作请求都必须走流水线，给了五个必做步骤和五条禁令。本文逐条拆这十条，说清每一步要落到哪个文件、哪个字段，以及这些条文的性质——它们是写给模型看的约束，不是代码里的闸门。

三层知识架构：723 个 md 文件是怎么分层的

OpenMontage 把知识切成 Layer 1 tools/ + pipeline_defs/、Layer 2 skills/、Layer 3 .agents/skills/ 三层。本文按实读计数拆开这 723 个 md 文件的分布，说清每层回答什么问题、三层靠 agent_skills 字段和 Rule Zero 怎么串起来、以及你想改东西时该动哪一层。

OpenMontage 到底是什么：没有代码编排器的视频制作系统

OpenMontage 仓库里找不到主程序，因为它没有代码编排器：流程写在 YAML manifest 和 Markdown skill 里，Python 只提供工具和持久化。本文从仓库身份、实读目录、三层知识、Rule Zero 契约和 config.yaml 默认值切入，说清它是什么、不是什么、什么人不适合上手。

表里 11 行、正文说 12 条、目录里 13 个：OpenMontage 数字对不上的那条流水线

OpenMontage 的 README 表格列了 11 条流水线，正文却写 12 条，而 pipeline_defs/ 里躺着 13 个 yaml。这篇逐个数清三组数字，指出差额落在 framework-smoke 和 character-animation 两处，并给出按 manifest 字段自查流水线的动作。

15 个视频生成 provider：云 API、本地 GPU 与素材库三条路

OpenMontage 的 README 列了 15 个视频生成来源。本文把这张表按 Cloud API / Local GPU / Stock 三类拆开，说清网关型路径、Kling 为何出现两次、`VIDEO_GEN_LOCAL_MODEL` 的取值枚举，以及为什么查能力要跑 registry 而不是数这张表。

十一条流水线各产出什么：一张表配决策路径

OpenMontage 的 README 用一张十一行的表列出各条流水线的产出物与适用场景，但 Best For 一列有明显重叠，照着挑很容易挑错。本文把表原样摆出来，按「素材从哪来、画面里有没有人、手里有没有长素材」三个轴重排成决策路径，再落到 manifest 里能核实的字段上。

`skills/` 的四个分区：core / creative / meta / pipelines 各管什么

OpenMontage 的 skills/ 目录有 156 个 Markdown，分成 core、creative、meta、pipelines 四类。本文按实读的文件清单说清每个分区装什么，并落到 documentary-montage.yaml 的 required_skills 与阶段 skill 字段，看 manifest 怎么引用它们。

加一个工具四步、加一条流水线三步：OpenMontage 的扩展契约

OpenMontage 的 Contributing 只给了七行清单：加工具四步、加流水线三步。真正的门槛不在这七行里。本文把这两条清单放回三层知识、Rule Zero、registry 自动发现、预算审批默认值和渲染运行时锁定这几处可核查的锚点上，说清扩展时哪些是形式要求、哪些是契约文本约束。

OpenMontage 的 TTS 到底是 5 个还是 4 个：README 自己两处说法不一

OpenMontage 的 README 在折叠块里写 TTS 有 5 个 provider，架构图里 tools/audio/ 那行却写 4 TTS providers。本文把两处原文摆出来，顺便讲清这类计数差异该怎么读，以及决定用哪个 TTS 的其实是 lib/scoring.py 里那套七维权重，不是清单有多长。

11 个图像来源，以及为什么 ManimCE 被放进了这张表

OpenMontage 的 README 在图像生成一栏列了 11 个 provider，最后一行是做数学动画的 ManimCE。本文按 Type 把这 11 行拆成四类，说清 ManimCE 为什么算图像来源、这张表和架构图里的 9 个工具是两套计数口径，以及静态图在没有视频 provider 时会走到哪条渲染路径上。

十条「不要这么做」：一份写给 agent 的负面清单

OpenMontage 的 AGENT_GUIDE.md 最后一节叫 What Not To Do，十条全是禁止句。本文逐条拆开这份负面清单，说清每一条在拦什么行为、在仓库里对应哪个字段或哪个默认值，以及为什么这类系统的契约必须写成禁止式，而不是正面规范。

OpenMontage 的 Windows 手动安装串，以及那条 `ERR_INVALID_ARG_TYPE` 的已知问题

Windows 上没有 make，只能照 README 的 PowerShell 手动串一条条走。本文逐段拆开这串命令、说清它和 macOS/Linux 那串的差别，并按「现象—确认—处置—验证—排除」的顺序讲 README 单独记下的那条 npm install 报 ERR_INVALID_ARG_TYPE 的已知问题。

音乐三家、后期七件、增强四件：一直免费的那部分

OpenMontage 的供应商清单里，音乐只有 3 个云 API，后期 7 件被 README 标注为 always available、always free，增强与分析各 4 件点的是具体开源项目名。本文按 README 的表逐栏数清楚哪几栏需要密钥、哪几栏不需要，并指出架构图的 13/9/4 与三张表的 15/11/5 不是同一个计数口径。

静默切换运行时算治理违规：`render_runtime` 是怎么被锁住的

OpenMontage 把合成运行时当成需要锁定的决策，而不是可以随手改的配置项。本文从 README 那句 governance violation 原文出发，拆开 render_runtime 与 edit_decisions 的分工、两处 Node 版本标注的差异、config.yaml 的输出默认值，以及这条规则真实的约束力边界。

估算、预留、对账：$10 上限与 $0.50 阈值背后的四个配置键

OpenMontage 的 README 把预算控制讲成四步，仓库根目录的 config.yaml 里它其实是五行 YAML。本文逐行拆 budget 段的每个键、指出默认模式是 warn 不是 cap、补上 README 没写的两项，并说明为什么七维评分里 cost efficiency 只占 10%。

五道质量闸：从人类审批到渲染前拦截

OpenMontage 的 README 列了五道质量闸，但它们并不在同一个位置上咬合：素材探测在创意决策之前，人类审批落在 checkpoint 写入这一步，交付承诺和幻灯片风险在合成前拦截，自检在渲染之后。本文按它们在链条上的先后顺序逐道拆开，并落到源码里能查到的具体阈值上。

从 pip install 到第一次 serve：默认装了些什么

speech-to-speech 一行 pip install 就装上了，但默认拼出来的是 Parakeet TDT 做转写、responses-api 把请求打向 OpenAI 兼容接口、Qwen3-TTS 负责出声这一套组合。本文按官方 README 与 arguments_classes 目录下的参数定义，逐条拆开默认安装究竟装了什么、Linux 上 CUDA wheel 错配与 numpy 版本互斥这两个坑该怎么绕过去、第一次 serve 之后应该用哪条命令来验收结果，以及哪几类场景下这套默认组合从一开始就不适合你，需要提前换掉。

三条可以搬走的并发取消经验

speech-to-speech 的打断处理把「取消一个正在流式输出的响应」这件事拆成了世代计数、队列保留清单和当前世代放行三块。这三条不绑语音场景，任何有流式输出、又允许中途叫停的系统都能照着搬。本文按官方 README 的机制原文讲清每条的做法、它替掉了什么旧写法，以及你手上的系统要不要跟着改的判断依据。

用世代计数取消，比取消标志加时间窗健壮在哪

speech-to-speech 的 Realtime Engine 用一个 CancelScope 对象同时管住世代计数器与丢弃标志，取代了旧的双信号模式。本文按官方架构文档拆开这套取消机制：世代号怎么让旧响应瞬间过期、丢弃守卫在哪三种情况下清除、「当前世代永远放行」为什么能防住静默吞响应，以及你的流水线该不该照抄。

参数写错了不报错：非激活后端的选项只会带个警告被忽略

speech-to-speech 的 CLI 只为当前选中的后端构造配置，未激活后端的已知选项仍会被接受、只带一个警告就忽略掉。这篇按排查顺序讲清楚：怎么用带选择器的 -h 判定某个参数是不是根本没进配置、参数前缀和 arguments_classes 下的定义文件如何对应、处置后拿什么验证，以及哪些症状其实是钳制规则、平台级忽略或废弃开关造成的，不该往这个方向查。

384 与 192：为什么接续一轮的门槛只有开新轮的一半

speech-to-speech 的 VAD 参数里有一对反直觉的默认值：判定「开一个新轮次」需要 384 毫秒活跃语音，而「接续一个还能重开的旧轮次」只要 192 毫秒。这篇把这套迟滞机制拆开讲：可重开轮次是怎么来的、两个门槛为什么不对称、参数被钳制在什么区间、什么情况下你调它根本不会生效，以及遇到切分太碎时真正该动的是哪个参数。

Qwen3-TTS 装不上：那个 wheel 默认盯的是 CUDA 12.8

speech-to-speech 默认 TTS 是 Qwen3-TTS，非 macOS 平台默认走 GGML 后端，而它依赖的 qwentts-cpp-python 在 PyPI 上的默认 wheel 面向 CUDA 12.8。本文按官方 README 的口径，把这条安装期陷阱拆成怎么判定、怎么处置、处置后怎么验证、以及什么情况说明根本不是它，顺带列出容易被误认成同一个问题的几种情形。

用户一开口，服务端这八步依次发生

speech-to-speech 处理抢话不是「把音频停掉」这一个动作，而是 Realtime Engine 文档里写死的八个步骤：VAD 事件入队、终态事件补齐、世代递增与冲队列、打断门控、handler 自查过期、丢弃守卫、客户端主动取消、伪取消保护。本文逐步拆开这条链路，说明每一步在防哪类故障，以及你写客户端时该按什么顺序渲染这些事件。

96 个 Python 文件怎么读：按目录找到你要改的地方

speech-to-speech 的 src 下有 96 个 Python 文件、131 个 CLI 参数，从头读一遍不现实。这篇按「你想改什么」倒推该开哪个目录：调回合判定去 VAD、换中文识别去 STT、改工具调用去 LLM、改线上事件去 api/openai_realtime，另给参数名与事件名两条反查线索。

docker compose up 起来的是两个服务，不是一个

speech-to-speech 的 docker compose up 起来的不是一个服务：它同时拉起跑 Gemma 4 的 llama.cpp 服务与实时服务，暴露 8080 与 8765 两个端口。本文讲清两个端口各自对应仓库里哪段配置、怎么做协议层冒烟检查，以及并发数默认为 1、绑定地址默认走环回这两个最容易翻车的默认值。

七个 pip extras：哪些该装，哪些别碰

speech-to-speech 的 README 在可选组件小节列了一串 pip extras，装错的代价不是报错而是静默走回默认路径。这篇按「你的平台是什么、要不要中文、跑不跑 GPU」倒推出决策路径，逐个说清七个模型侧 extra 各自换掉流水线的哪一级、哪些在你的平台上根本是内置的不用装、哪两个之间存在 numpy 版本硬冲突，并给出装完之后怎么用 -h 验收、以及哪几个默认值会让你以为换了后端其实没换。

同一个功能，云端是协议原生，本地靠正则抠

speech-to-speech 的工具调用在两个 LLM 后端上走的是完全不同的两条路：OpenAI API 侧由 client.responses.create 直接返回结构化 function_call，本地 transformers / mlx-lm 侧要把 JSON Schema 转成 Python 函数签名注入系统提示词，再用正则从 code 块里把调用抠出来。本文按官方 README 与源码口径拆开这两条路、它们汇合的位置，以及选后端时真正该看的几条硬约束。

工具结果回流四步：为什么第 2 步不触发生成

把工具执行结果发回 speech-to-speech 之后助手一声不吭，不是服务挂了：conversation.item.create 只负责把结果注入上下文，这一步不触发生成。本文按仓库内 Realtime Engine 文档拆开工具结果回流的四步，讲清什么时候必须补发 response.create、什么时候可以就此收手，以及怎么从事件流判断卡在哪一步。

默认绑 127.0.0.1 是有道理的：改成 0.0.0.0 之前想清楚

speech-to-speech 的 serve 命令默认把 Realtime 服务绑在 127.0.0.1，官方 --host 的帮助文本里直接写着「显式传 0.0.0.0 才会把未认证的 API 暴露到网络上」。这篇按官方参数语义梳理 8765 端口上到底有哪些入口、改 host 之前必须确认什么、端口转发与显式暴露两条路各自怎么配、事后逐项怎么验收，以及哪些场景根本不该动这个默认值。文中毫秒与端口均为参数默认值，非实测数据。

什么情况下你非得自己架一台 TURN

speech-to-speech 同时提供 WebSocket 与 WebRTC 两种传输，只有走 WebRTC 才需要考虑 ICE 打洞。这篇按官方文档口径讲清楚：怎么确认自己在 WebRTC 这条路上、不配 ICE 时的默认行为、哪两种部署形态官方点名必须架 TURN，以及环境变量怎么写、按三段怎么验收。

断网也能跑：HF_HUB_OFFLINE=1 之前要先做的事

speech-to-speech 的 README 用几句话交代了离线运行，但真照着做很容易只离线了一半——环境变量只管模型资产的拉取，默认的 responses-api 后端照样往远程打。这篇把断网前要做的准备拆成可复制的命令：预热缓存、把 LLM 换成本地 llama.cpp、单独安置 Smart Turn 的 ONNX 检查点，并给出逐条验收动作与四类不适用场景。

--enable_llm_proxy：不认证、不限流，官方自己说的

speech-to-speech 的 --enable_llm_proxy 把服务端配好的远端 LLM 也暴露成一个 OpenAI 兼容端点，供摘要、起标题这类侧边任务并发调用。但官方 README 写得很直白：服务端自己不做认证，也不做限流。本文讲清它的开启条件、命令怎么组、两条路径分别对应哪个后端、怎么验收、什么情况别开。

`--mac-optimal-settings` 做了什么，又被什么覆盖

speech-to-speech 在 Apple Silicon 上提供了一个一键预设开关，官方 README 说它只做四件事，而且优先级排在所有显式参数之后。这篇把预设的四项内容、能覆盖它的六类参数、可直接复制的命令写法、验收时该看哪一行输出，以及哪些场景根本不该指望这个开关，按仓库文档与参数导出的口径逐条讲清楚。

老教程里的 --mode 为什么跑不通了

网上大量 speech-to-speech 的旧文都在用 `--mode realtime` 和 `--mode local` 起服务，照抄下来轻则打印一行警告，重则直接退出。这篇按排查的路子走一遍：先给出三种典型现象，再给可执行的判定动作（看 `-h` 输出、核对参数导出、看启动首行有没有警告），然后按官方迁移语义把老命令逐条改写成 `serve` / `talk` / `local`，最后单列一节说明哪些失败其实与 `--mode` 毫无关系（安装依赖冲突、并发上限、离线缓存、组件已下架），免得你把力气花错了地方。

名字里写着 local，默认配置的 LLM 却在云上

speech-to-speech 的仓库描述写着 Build local voice agents，但官方给出的默认等价命令里，LLM 那一环走的是 OpenAI Responses API 的 gpt-5.4-mini，真正跑在本机的只有 VAD、STT 和 TTS 三段。这篇把这套默认配置逐段拆开对号入座，给出四个「怎么确认自己这套到底连没连外网」的判定动作，再按你的处境倒推该走独立 llama.cpp 进程、进程内本地后端还是 macOS 预设，最后说清中文支持、并发数量与暴露服务这三个最容易连带踩的坑。

一条 serve 背后的 14 个默认参数，逐个说清楚

`speech-to-speech serve` 看着是一条裸命令，README 却给出了它等价的 14 个显式参数。这篇逐个拆开讲：默认 STT 只覆盖 25 种欧洲语言、默认 LLM 走的是云端 Responses API、六个 Qwen3-TTS 旋钮在不同平台各有几个不生效，再补上绑定地址、端口与并发数这三个没写进命令、却常决定成败的默认值。

`--num_pipelines` 默认是 1：多人用之前必须先动它

speech-to-speech 的实时服务默认只开一个流水线实例，也就是只承载一个并发会话，多出来的连接会被直接拒绝。这篇讲清 `--num_pipelines` 的语义、池化单元里装了什么、两种传输为什么共用一个池，并给出「该设多大、什么时候动它没用」的判断依据。

DeepFilterNet 要 numpy 小于 2，Pocket TTS 要大于等于 2

speech-to-speech 的 README 单列了一条依赖互斥：DeepFilterNet 要 numpy<2，Pocket TTS 要 numpy>=2，装进同一环境必然打架。按排查顺序讲透：用哪条命令看环境在哪一侧、文档给出的处置、改完怎么验证，以及哪些现象其实是 CUDA wheel 错配而非 numpy。

从一段 base64 PCM 到一段合成语音：六步数据流

speech-to-speech 的实时服务把客户端发来的一段 base64 PCM 变成一段合成语音，中间要经过重采样切块、VAD 定边界、STT 出转写、LLM 生成、TTS 回流、会话配置深合并六个环节。这篇按仓库内 Realtime Engine 架构文档的口径逐步拆开每一步的输入输出与交接队列，重点讲三个最容易把客户端写错的时机差异：`response.created` 的发出时点、助手转写为什么必须改到 delta 上渲染、以及注入上下文为什么不会触发生成，并给出 WebSocket 与 WebRTC 两种传输的选择依据。

5 个上行、15 个下行：Realtime 事件表怎么读

speech-to-speech 的 Realtime 协议只有 20 个事件，难的不是名字是时序：response.created 要等第一个音频块才发，被打断时三个终态事件排在 speech_started 前面，助手转写已从块级 done 改成 delta 拼接。本文按上行 5 个、下行 15 个拆表，讲清每类事件该绑客户端哪个状态，以及两种传输下哪几条不通用。

800、2000、7000：三个重开窗口的层级与钳制关系

speech-to-speech 里三个重开窗口的参数默认值分别是 800、2000、7000 毫秒，它们不是可以相加的延迟，而是三层管辖范围不同、彼此还带钳制关系的轮次可重开有效期。本文按官方参数 help 原文讲清三者的层级、两条会导致设置静默失效的钳制条件，以及想改变接续行为时到底该动哪一个参数。

serve、talk、local：三个命令分别在什么场景

speech-to-speech 的命令行只有 serve、talk、local 三个入口，但它们分的不是「运行方式」，而是「谁托管流水线」和「谁推音频」这两件事。本文按官方 README 与参数定义梳理三者的绑定地址、并发上限、预设优先级差异，给出一条可以自己走完的选择路径，顺带说清 --mode 弃用后老教程为什么全跑不通。

session.update 深合并进 RuntimeConfig：配置是处理时现读的

speech-to-speech 的 Realtime 服务把客户端发来的 session.update 深合并进一个共享的 RuntimeConfig，VAD、LLM、TTS 在处理时现读它，而不是重启才生效。本文按官方仓库的 Realtime Engine 架构文档梳理这条配置链路：深合并意味着只发要改的子树、生效与否以 session.updated 回读为准、哪些改动该走 response.create 的按响应覆盖、WebRTC 下 session.created 时机不同带来的客户端写法差异，以及会话级配置与进程级 CLI 参数之间那条容易踩空的边界。

speech-to-speech 是什么：一条能换掉每一段的语音代理流水线

speech-to-speech 是 Hugging Face 的开源语音代理流水线：VAD、STT、LLM、TTS 四段级联，每段后端都能用一个 CLI 参数换掉，对外暴露兼容 OpenAI Realtime 的 WebSocket 接口。本文按仓库 README 与参数源码讲清它的结构、三个反直觉的默认值，以及那些毫秒参数到底买的是什么。

两个长得很像的实时转写开关，别调错

speech-to-speech 里有两个名字几乎一样的实时转写开关：模块级的 --enable_live_transcription 默认开着，VAD 侧的 --enable_realtime_transcription 默认关着。很多人以为自己开了实时转写，其实动的是另一个。连它们各自的间隔参数和最小静音参数都撞脸。这篇按现象、判定动作、参数语义给出的处置、处置后怎么验证、以及什么情况说明不是这个原因五步走，把这两组参数的归属、默认值和作用范围一次拆开讲清楚。

VAD 到 STT 到 LLM 到 TTS：四个线程、三道队列

speech-to-speech 把语音代理拆成 VAD、STT、LLM、TTS 四段级联，每段跑在自己的线程里、用队列相连。这篇按官方 README 与源码口径讲清三道队列各自搬的是什么、六步数据流在哪一步分叉、世代计数为什么非有不可，以及排查问题时怎么按队列边界把现象定位到具体某一段，而不是笼统地抱怨"响应慢"。

Smart Turn：先干活再决定要不要认账

speech-to-speech 在 Silero 判定「说完了」之后又挂了一层 Smart Turn v3.2 端点判定，很多人把它当成延迟旋钮，于是要么关掉要么乱调阈值。这篇按仓库参数定义与 README 的机制描述，讲清推测性开工、完整轮次的提交窗、不完整轮次的两段延迟、修订版作废后输出怎么丢弃。

切得太碎怎么办：--short_segment_merge_ms 的补救逻辑

speech-to-speech 的 VAD 默认用 64 毫秒静音就切一刀，而短于 384 毫秒的语音段又不算有效语音，两个默认值撞在一起就会把一句话切成一堆被丢掉的碎片。本文按官方参数 help 的语义，拆解怎么判定自己撞上的是不是这个问题、--short_segment_merge_ms 这个默认关着的开关到底缝的是什么、开完之后从哪几个协议事件上验证，以及哪几种情况说明根本不该动它。

19 个 VAD 参数逐个讲：默认值背后的意图

speech-to-speech 的 vad_arguments.py 里有 19 个参数，光看 --help 很难判断该动哪个。这篇按「基础切分、迟滞、重开窗口、Smart Turn、实时转写」五组把默认值拆开，讲清 min_silence_ms 为什么只有 64 毫秒、384 与 192 为什么要分家、三个重开窗口谁钳制谁，并说明这些毫秒值是可配置等待而非真实链路耗时，不能相加当作端到端结论。

WebRTC 模式的三处不一样，尤其那个被拒绝的事件

speech-to-speech 的 serve 命令同时暴露 WebSocket 与 WebRTC 两种传输，官方文档说两者协议相同，却又单独列出了三处差异：上行的 append 事件会被服务端直接拒绝、output_audio_buffer.clear 只有 WebRTC 一侧支持、session.created 的发送时机从连接时挪到了数据通道打开时。本文按仓库文档与源码口径，讲清这三处差异各自的成因、对现有客户端代码的具体影响，以及什么处境下该选 WebRTC、什么部署必须先准备好 TURN 服务器再上线。

语音对话的延迟预算怎么拆：哪几段是配置，哪几段是算力

语音代理"说完半天不回话"，有的是参数里写死的等待，有的是模型推理在跑，两者的处置方式完全相反。本文按 speech-to-speech 仓库的参数默认值与 Realtime 架构文档，把一次回合拆成配置等待段与算力段，说明每段由谁决定、能从哪个协议事件划出边界、以及为什么这些毫秒数绝对不能相加。

老客户端要改：转写从 done 迁到 delta

speech-to-speech 的 Realtime Engine 文档单开一节说明了一个破坏性变更：助手转写以 response.output_audio_transcript.delta 流式发出，而终态 done 一个响应只发一次。老客户端如果仍把每个块级 done 当成渲染事件，升级之后字幕就会整轮憋到最后才刷出来，而且不报任何错。本文按排查五步走，给出可执行的确认动作、文档语义给出的处置方式、改完之后的验证办法，以及哪几种情况说明你遇到的问题根本不在这里。

13 个 skill 怎么挑：出代码的和只出图的是两回事

taste-skill 的 skills/ 目录下有十三份 SKILL.md，README 把它们分成「出代码」和「只出参考图」两类，但列在同一张表里很容易被当成十三个平级选项。这篇按输出物、职责层级和适用处境给出挑选路径，并把叠加多个 skill 时会撞上的几处口径差异先摊开讲清楚。

装不上是因为你用了文件夹名：taste-skill 十三个 skill 的 install name 对照

`--skill` 后面要填的是 SKILL.md frontmatter 里的 install name，不是 GitHub 上看到的文件夹名。taste-skill 十三个 skill 有十个两者对不上。本文给出完整对照表、为什么不能靠去后缀猜、填错时的自查动作，以及什么时候问题不出在名字上。

8 个区块至少 4 种布局：锯齿上限与 bento 格数精确规则

taste-skill 默认 skill 的 §4.7 Layout Discipline 里有几条能数出来的布局规则：一页 8 个区块至少要用 4 种布局家族、图文分栏最多连续 2 个、bento 格数恰好等于内容条数。本文给出原文口径，说清怎么数、跟哪些规则连动、什么场景不该套，以及它们为什么只是提示词不是校验。

★ 「创意需求就该用衬线」是被测最多的 AI tell

taste-skill v2 的 SERIF DISCIPLINE 是 §4 版式部分语气最重的一条规则，它封杀的不是衬线字体本身，而是模型「创意需求 = 衬线」这个默认反射。这篇拆开它的两道例外闸门、被点名的两款字体、同家族强调规则，以及唯一一条能机械核查的斜体下伸空间要求，帮你判断什么时候该照做、什么时候该走 override。

★ 零个 em-dash：为什么这条禁令被写成了二元规则

taste-skill 的默认 skill 里有一条完全不留余地的禁令：输出里出现一个 em-dash 就算没做完。这篇讲清这条规则的确切条文、它自己给出的立法理由（写成"少用"时模型会无视），它挂在 Pre-Flight 上的判定方式，以及这类二元表述什么时候值得抄进你自己的提示词、什么时候必须落到机械校验里。

★ 每三个区块最多一个 eyebrow：一条能机械计数的规则

taste-skill v2 把「区块标题上方那行小号大写标签」的数量写成了一条带公式的硬规则：count ≤ ceil(sectionCount / 3)。这篇讲清 eyebrow 指什么、规则的三个分句各管什么、公式的分母该怎么数，以及它终究只是写给模型的提示词而不是校验器。

让模型模拟一次 Python 随机：gpt-taste 的 `<design_plan>` 预检

taste-skill 里有个只有 74 行的 skill，要求模型写任何 UI 代码前先输出一个 <design_plan> 块，在里面「模拟执行」一段 Python 随机脚本来抽版式。这篇拆开五项预检各自在管什么、哪几项事后能人工核对、哪几项只能靠模型自述，以及它与仓库内其它 skill 的字体口径差在哪。

`start: "top top"` 写错就毁了：两个 GSAP 规范骨架逐行读

taste-skill 的 §5 给了两段可以直接粘贴的 GSAP 代码，一段做滚动卡片堆，一段做横向平移。这篇把这两段骨架逐行拆开，讲清每个字段在骨架里的位置、原文标出的关键点、为什么大多数滚动动效其实不该用 GSAP，以及这些规则的真实性质：它们是写给模型的提示词，不是会在你项目里执行的检查。

Hero 必须装进首屏：2 行标题、20 词副文本、4 个元素上限

taste-skill v2 的 §4.7 把 Hero 写成可数的硬规则——标题最多 2 行、副文本最多 20 词、文本元素不超过 4 个、顶部内边距最多 pt-24、导航最高 80px。这篇逐条拆这些数字卡的是什么、五类元素为什么被赶出首屏、哪些情况走 override，以及它们终究只是写给模型的提示词。

一个区块一张图：三个只出图不写代码的 skill 怎么分工

taste-skill 仓库里有三个 skill 明写「不写代码」，只产参考图。这篇按仓库文档口径讲清 imagegen-frontend-web、imagegen-frontend-mobile 和 brandkit 各自约束什么、章节结构差在哪，以及「一个区块一张图」这条硬输出规则会如何改变你和写代码那一步的交接方式。

没有 liquid-glass.css：审美潮流与官方设计系统的分界

客户说想要 Apple 那种 Liquid Glass 质感，你去搜官方 CSS 包，搜不到。taste-skill 的 §2 把这类需求单独划了一张表：有官方包的照官方包装，没有官方包的老实承认是近似。这篇讲清这条分界线画在哪、八种常见审美各自落在哪一侧，以及怎么判断你的需求该走哪一边。

默认技术栈：Tailwind v4、`motion/react`、四个图标库与 RSC 隔离

taste-skill 默认 skill 的 §3 定了一套默认技术栈：Tailwind v4、从 `motion/react` 引入的 Motion、四个允许的图标库与 RSC 交互隔离。本文拆开每条默认的原文口径、生效前提与仓库给出的 Override 路径，并说清哪些能落成工程检查、哪些只是提示词。

模型老是交半成品：full-output-enforcement 的禁用模式清单

让模型写 5 个组件，它给 3 个再补一句「剩下的照这个模式来」。taste-skill 里有个 49 行的 output-skill 专治这件事。这篇拆开它的三类禁用模式、三步执行流程和 token 上限断点协议，并说清哪些条目你能变成自己流程里的机械检查，哪些只能靠人眼看。

62 个复选框的 Pre-Flight Check：哪些是机械可查的

taste-skill 默认 skill 的 §14 是一张 62 个复选框的交付前检查表，原文要求逐个跑完。但这 62 条并不在同一个层级上：有的只看产物文本就能判定，有的要先把区块数、内容条数建模出来才能计数，还有一批只能靠人读一遍。这篇把它们分成三档，说清每一档能自动化到什么程度、卡在哪里。

米色 + 黄铜 + 浓缩咖啡：被逐个 hex 点名封杀的高端消费色板

taste-skill 默认 skill 的颜色一节里有一条很反常的规则，它不讲原则，直接把十六个十六进制值列出来逐个封杀。这篇讲清这条规则管的是哪类需求、七套替代色板怎么轮换、Override 的两个口子分别要满足什么，以及最要紧的一点：这些 hex 写得再具体，也只是写给模型看的提示词，不会有任何东西去替你做匹配。

改版不是重写：redesign-skill 的审计清单与七步修复优先级

taste-skill 仓库里的 redesign-skill 是少见的一份写给「已经有代码的项目」的规则文件，178 行，明写不要从零重写。这篇拆开它的九类审计清单该怎么读、七步修复优先级为什么排成这个顺序、哪几条在你的项目里应该走 override，以及它和 taste-skill v2 §11 Redesign Protocol 的分工在哪。

`research/` 目录讲了什么，以及为什么不能拿它当结论

taste-skill 仓库里有一个 research/ 目录，装着一整套关于「大模型为什么输出不完整」的分析，里面有实验编号、百分比和参数表，看起来很像论文综述。这篇先如实转述它写了什么，再说清三条不能拿它当结论的理由：出处清单没有出处、第三方 API 参数需要回官方核、以及原因分析推不出规则有效。

8 / 6 / 4 三个旋钮：推断表、预设表与分档定义

taste-skill 默认 skill 的核心配置只有三行，基线是 8/6/4。这篇把它的推断表、用例预设表和分档技术定义并排摆开，讲清这三个数字该怎么覆盖、哪一档的加减一分会真的改变实现手法、以及预设表与基线对不上的那两处差异。

写码之前先说一句「Reading this as…」：§0 的六个信号

taste-skill 默认 skill 的第 0 节要求模型动手写代码前先输出一行「Reading this as…」的设计读数，而这行话是从六个信号推出来的。本文拆开这六个信号各自在判断什么、需求含糊时为什么只允许问一个问题、被点名的六个「LLM 默认反射」是哪些，以及它们为什么只是提示词约束而非工程保障。

需求像 Fluent 就装 Fluent：§2 的十二行映射表与诚实规则

taste-skill 默认 skill 的 §2 给了一张十二行的映射表，把「需求读起来像什么」直接映射到具体的官方设计系统包，并配了两条硬规则：命中就装官方包不许手抄 CSS，一个项目只用一套体系。这篇讲清这张表该怎么读、什么时候该照做、什么时候它压根不适用，以及它作为提示词约束的性质边界。

taste-skill 到底是什么：一个没有 src/ 的纯 Markdown 规则仓库

很多人以为 taste-skill 是个前端库或 npm 包，克隆下来才发现里面既没有 src/ 也没有构建产物，核心资产就是十三份 SKILL.md。这篇讲清它的仓库结构、安装方式、install name 与文件夹名的关系，以及最关键的一点：这些规则是写给模型看的提示词，不是会在你项目里自动生效的工程保障。

落地页是视觉产品：图片优先级三档与被禁的 div 假截图

taste-skill v2 的 §4.8 给视觉资产排了一个三档优先级：有生成工具就必须生成、其次用真实图片、最后一档是明确告诉用户缺图，而不是拿 div 拼一个假仪表盘糊过去。这篇把三档的判定条件、logo 墙的 LOGO-ONLY 硬规则、手绘 SVG 的三种例外拆开讲，并说清它们在什么场景下该照做。

默认 skill 变成了 v2 (experimental)：怎么升、怎么钉回 v1

taste-skill 的默认 skill 已经换成了 v2，而 v2 在 CHANGELOG 里自标 pre-release。这篇讲清升级和回滚各自是哪一条命令、install name 与文件夹名在这件事上的对应关系、v2 相对 v1 具体多了哪些硬规则和技术栈主张，以及什么样的项目更该钉在 v1 上。

$200/月这一档值不值？编程 Agent 重度用户档横比与升档算法

$200 是编程 Agent 的另一个行业锚点，专供重度个人用户。本文横比 Kiro、Warp、Devin、Augment 在这一档的实际给量，算清只有一家真给了批量折扣，并给出「该不该升档、该不该锁年付」的两条可复算判断线。

都是 $20 一个月，各家给的完全不是一回事：编程 Agent 入门档横比

同样掏 $20，Kiro 给 1000 credits、Warp 给 1500、Devin 没写数量。这篇拆开各家入门档实际给了什么、为什么不能直接比大小，以及唯一可比的维度：额度用完后代价落在钱上还是时间上。

自带密钥还是买订阅？一棵能自己走完的决策树

BYOK 省下的是加成比例，付出的是管理成本。本文用一棵决策树把这个选择拆成几个能直接回答的问题，并给出各家 BYOK 路径的对照。

编程 Agent 额度用完之后会怎样？五种超额策略横比

有的加钱续着用，有的降级到慢速通道，有的只能等窗口重置，还有的按 API 原价计费。这五种超额策略决定了你的代价落在钱上还是时间上——这才是选型时真正该看的一列。

团队里的 AI 成本怎么摊？三种分摊口径与一条务实建议

分摊口径必须跟着计价结构走：纯人头价天然可按人归集，两段式定价里那笔固定费才是真问题，纯固定价加共享额度则常常连"谁烧了多少"都查不到。本文给出三种口径的适用场景与代价，算清固定费随规模摊薄的曲线，并给出一条比精细计费更省事的做法。

CLI 型还是 IDE 型编程 Agent？形态比模型能力更该先想清楚

编程 Agent 分成编辑器/IDE 型、CLI 型、终端替代型、免安装 Web 型四种形态。形态决定了接入成本、能干什么任务、以及团队推得动推不动。本文给出四类形态的对照表、接入成本排序、几条容易踩的环境门槛，以及一条三步决策路径。

公司网络装不上编程 Agent？代理与证书问题分层排查

公司电脑能上网、却装不上或登不进编程 Agent，八成不是工具坏了，而是代理没覆盖到登录环节，或者企业根证书没被运行时信任。这篇教你先把问题分成三类，再按类下手，并说明为什么绝对不要靠关闭证书校验来"解决"。

编程 Agent 登录不上怎么办？把登录拆成四个环节的通用分层排查法

编程 Agent 登录失败往往不是一个问题，而是出网、授权页、账号侧、回调四个环节里的某一个坏了。这篇给出一套跟具体品牌无关的分层排查框架，教你用交叉验证和 Web 形态先定位环节，再对症处理，避免在本地反复瞎试。

多家编程 Agent 混着用，到底省不省？

混用两家编程 Agent 的收益不是"更便宜"——两份订阅就是两份钱。真正买到的是额度用完时还有牌可打。这篇算清混用的成本代价、说明哪些组合天然不冲突，并给出"先撞限再考虑混用"的决策顺序。

编程 Agent 额度告警怎么设？哪些家必须设、哪些家根本不用设

额度告警不是每家都要做的事。代价落在时间上的（降级慢速、等窗口重置）天然不会超支，代价落在钱上的（固定单价续费、按需充值、按 API 价计费）才必须设。本文给出判断标准、两档水位建议、官方没有告警功能时的手动替代方案，以及团队场景的用量归属做法。

编程 Agent 的额度单位横比：credits、美元、请求、时间窗口有什么不同

各家用的额度单位根本不是一回事——有的按 credits 点数、有的直接用美元、有的按请求优先级、有的按时间窗口。单位不同就没法直接比价。本文给出五种范式的差别和统一到可比口径的方法。

AI 编程工具的额度单位有七种，它们互相不能换算

请求次数、任务数、并发、编辑预测、对话次数、credits、美元额度——七种单位同时存在。本文说清每种单位的大小由谁决定，以及为什么任何跨家换算都是编的。

编程 Agent 额度什么时候回血？三种刷新周期与你的排期节奏

额度用完后什么时候恢复，决定了你该怎么排任务。这篇把市面上的刷新方式归成总量池、滚动刷新、滚动时间窗口三类，讲清每一类对应的排期打法，并说明为什么六家里只有一家把刷新周期写进了官方页面。

编程 Agent 额度在最要紧的时候用完了怎么办？一份应急预案

deadline 前撞上额度上限，第一步不是找工具，是先搞清楚你这家属于"能加钱""能降速""只能等"三类中的哪一类。本文给出三类各自的应急动作、升档分界线的算法、等待期间不浪费时间的做法，以及事后复盘要问的三个问题。

你一个月要烧多少额度？一套自己就能跑完的编程 Agent 用量估算法

定价页只告诉你这一档给多少额度，从不告诉你一个额度单位能干什么。这篇给出五步实测法：记基线、照常干一天、算日均、乘真实工作日、对照档位表，并说清三个最容易算错的地方和升档分界线怎么定。

AI 编程工具的四种加价姿态：零加成、明码 +10%、送额度、BYOK 各适合谁

同样是按量付费，Kilo Gateway 写「零加成」、Zed 写「+10%」、OpenHands 写「成本价」、Kilo Pass 反过来送 bonus credits。本文横比这四种定价姿态的机制差异，并说清为什么不能直接比谁更便宜。

五家 AI 编程工具的免费档横比：不比大小，比能支撑什么

Gemini CLI、Jules、Zed、Kilo、OpenHands 的免费档给的东西完全不同。本文按「覆盖什么用法」「有没有上限」「要不要自己带密钥」三个维度对照，给出按习惯选的方法。

编程 Agent 的免费档到底能干什么？六家横比与一个尴尬发现

把六家的免费档摊开对比后发现一件事：真正把免费额度写清楚的只有一家，其余要么只写"免费"不写额度，要么干脆没提。本文讲清各家已知的部分，以及查不到时怎么自己摸清边界。

编程 Agent 该不该买年付？五家折扣横比与一条可执行的判断线

逐页核对五家编程 Agent 的定价页后发现，只有一家把年付价写在了明面上。这篇给出折扣公开情况的横比表、能公开核算的那家三档年付换算，以及"什么时候该转年付"的一条具体判断线和年付前必问的三个问题。

编程 Agent 的区域限制怎么看？下单前该确认的四件事

「这个 Agent 在我这儿能不能用」不是一个问题，而是四个：能不能下载、能不能登录、能不能付款、能不能调用到模型。本文只给排查方法与下单前的实测步骤，不给任何一家的可用性结论——那类信息以官方条款和你自己的实测为准。

编程 Agent 什么时候该升档、什么时候该降档？一条能直接算的分界线

升降档不该靠感觉。这篇把"留在低档补超额"和"直接升档"的成本写成一个等式，推导出可以直接套用的分界线公式，代入实际档位算出 500 / 1500 / 2500 三个临界值，并给出降档信号、判断周期，以及两种会让公式失效的计费方式。

编程 Agent 套餐性价比怎么算？月费最低的档常常不是花钱最少的档

只比月费选套餐，很容易多花钱。这篇用「档位月费 + 超额费用 = 真实成本」的算法，带你算出升档分界点、判断一家有没有批量折扣、识别哪些档位压根没法比价，最后用对比器一次算清所有档。

团队上编程 Agent 一年要多少钱？按用量分档能省一大笔

团队采购编程 Agent 最贵的习惯，是给所有人配同一个档位。这篇用一个十人团队的具体账算给你看分档能省多少、分档在什么前提下才成立，再拆解两段式定价的摊薄效应、席位上限的隐藏成本和年付该怎么判断，最后带你用测算器把自己的数填进去。

编程 Agent 的团队席位怎么算钱？四种计价结构横向对比与采购建议

团队采购编程 Agent 时，单价高低远不如计价结构重要。本文用 Kiro、Warp、Devin、Augment 四家 2026-08-08 的公开定价，拆出纯人头价、人头价加溢价、固定费加人头两段式、纯固定价四种结构，算清各自的人均成本曲线，并给出采购前必须问清的三个问题。

编程 Agent 新面孔盘点：六家不那么主流的产品，各自解决什么问题

把 Kiro、Warp、Devin、Augment Code、Amp、Antigravity 六家的形态、额度单位和超额机制逐家拆开，附一张总览表和可以自己复算的单价换算，并说明为什么「一次操作扣几个额度」多数家都查不到、你该怎么自己测基线。

编程 Agent 选型决策树：六个问题定下你该用哪一类

不做排名，只给流程。按形态、断供代价、预算可算性、用量规模、个人还是团队、要不要年付这六个顺序问下来，你会落到某一类编程 Agent 上，附一张总结表和三件不该当选型依据的事。

预付额度会不会作废？六家编程 Agent 的额度有效期条款横评

充值进去的 credits 放着不用会不会作废，是编程 Agent 采购里披露最少的一条。这篇把六家能查到的有效期条款摊开对照，讲清唯一写明条款的那家怎么触发过期，并给出预付量怎么定、自动充值怎么设防的判断。

终端里的 AI 和编辑器里的 AI，额度消耗模式差在哪？

终端 AI 和编辑器 AI 烧额度的方式完全不同：一个是高频小额，一个是低频大额。这篇讲清两类工具的消耗模式差异、各自的省钱着力点、风险等级为什么不一样，以及怎么分开测出自己的真实消耗基线。

Amp 怎么安装？三种方式与支持的编辑器清单（JetBrains 已废弃）

Amp 的三条官方安装命令（脚本、PowerShell、Homebrew）该怎么选，支持哪些编辑器，JetBrains 支持"已废弃但仍可用"意味着什么，以及装完之后余额在哪查、混合计费怎么算账。

Amp 的预付 credits 会过期吗？一年不活跃就作废，采购前必须读懂的条款

Amp 支持购买预付 credits，未使用的余额会在账户不活跃满一年后过期。这篇讲清「不活跃」和「买满一年」的区别、哪些人真会踩到、预付该买多少（3-6 个月可见用量），以及下单前必须向官方问清的四件事。

Amp 的「零加成」混合计费怎么算账？和 credits 制差在哪

Amp 采用月度订阅加超额按实际用量计费，对个人与非企业工作区零加成。这篇讲清零加成的含义、相对 credits 制的可比性优势、账单浮动这一代价，以及关联 ChatGPT 订阅、控上下文的省钱做法。

Amp vs Claude Code 怎么选？成本透明度和账单可预期性的取舍

Amp 走混合计费、个人与非企业工作区对供应商 API 定价零加成，你能看清每分钱花在哪；Claude Code 是订阅封顶，撞限只能等但账单不用操心。这篇按机制拆两者的记账方式差异，给出四类场景的选法和一条决策路径。

Amp 和 Kiro 怎么选？两家公开了不同的那一半信息

Kiro 把五档 credits 和超额单价全摆出来，却不说单次操作扣几个；Amp 把「零加成」写进文档，价格数字一个都查不到。这篇把两种公开方式摆在一起对照，讲清各自能算出什么、算不出什么，并给出按场景的选择路径。

Antigravity 免费到什么程度？官方没公布额度时怎么稳妥起步

Google Antigravity 官网只写了「Available at no charge」，额度和限速一个字没提，文档限制页还是 404。这篇讲清「免费」和「无限」的差别，给一套自己摸边界的可执行步骤，以及三条不被反噬的风险控制做法。

Google Antigravity 是什么、怎么装、免费吗？官网没写明的部分

把 Google Antigravity 官网上确实写着的几条摆出来逐字读一遍：定位、"Available at no charge"、两个下载选项、提到的 Flash 系列模型。更关键的是它没公布额度与限速，这篇讲清楚这件事对你意味着什么，以及免费工具该怎么进工作流。

Google Antigravity vs Cursor 怎么选？你买的其实是"确定性"

Antigravity 官网标注免费但额度与限速一个字没写，Cursor 要花钱但快慢两档的降级规则是明的。这篇从"额度政策是否公开"这一条主轴拆开两者的差别，给出四种场景的选法、自己摸清边界的三步土办法，以及三条把风险压住的做法。

Augment Cosmos 是什么？它的默认模型换了意味着什么

用官网与官方博客能核实到的少量硬事实，讲清 Augment Code 的 Cosmos 产品线定位、它按美元计费的额度口径，以及厂商更换默认模型时你该做的三件事：提示词版本化、重测消耗、别把模型特性写死进流程。

Augment 用美元当额度单位：$100 月费含 $100 用量额度是什么玩法？

Augment Code 的 BUSINESS 档是 $100/月固定价、含 $100 使用额度，额度单位直接是美元而不是 credits。这篇讲清楚「钱当额度」比点数制多出的可比性在哪、$100 含 $100 到底说明了什么、这笔额度覆盖哪三类消耗，以及 top-up 超额和 50 席位上限该怎么防。

Augment 只有两档套餐：Business 与 Enterprise 到底怎么选？

Augment Code 的定价页上只有 Business 和 Enterprise 两档，没有个人档。这篇讲清 $100 固定价里的 $100 美元额度怎么摊、50 席位上限意味着什么、什么情况下必须转 Enterprise，以及谈判前该准备哪三份数据。

Augment 超额 top-up 怎么控成本？美元额度制的三个刹车点

Augment BUSINESS 每月 $100 含 $100 美元用量额度，超出后走 Top-ups 按需充值。这篇讲清美元额度制为什么算账更省心、pay-as-you-go 为什么反而更容易失控，以及团队里能立刻落地的四个控成本动作和该转 Enterprise 的判断线。

Augment Code vs Amp 怎么选？两种「成本透明」其实是两回事

Augment 的额度单位直接是美元，$100/月含 $100 额度；Amp 则对供应商 API 定价零加成。一个让你知道扣了多少钱，一个让你知道没被加价——这两件事互相独立。本文拆开两种透明的机制差异、各自的适用边界与两条必须自己设防的风险。

Augment Code vs GitHub Copilot 怎么选？先看额度单位是不是美元

Augment 的 BUSINESS 是 $100/月含 $100 使用额度，额度单位直接是美元；Copilot 走多档套餐加抽象额度。这一条差别决定了你能不能算清账。本文拆开两种计价的适用场景，并给出按团队规模和身份的决策路径。

Augment Code vs Cursor 怎么选？先看有没有个人档

Augment Code 只有 BUSINESS 和 ENTERPRISE 两档、$100 起步，Cursor 有个人档。这篇把两家的额度机制摆在一起对照：额度用完时代价落在钱上还是时间上，以及一个人用、三五人团队、中型团队分别该怎么选。

Claude Code 报 exceeded the 32000 output token maximum 怎么解决

让它写一个大文件，写到一半报输出超上限。本文讲清 CLAUDE_CODE_MAX_OUTPUT_TOKENS 这个环境变量的默认值、上限和代价，以及为什么调高它未必是最优解。

Claude Code 报 401 认证失败怎么解决？六条认证类报错的分流表

401 authentication_error、Invalid API key、OAuth token revoked、Login expired 长得像但成因不同。本文按官方错误参考把认证族的六条报错分开，给出 /status 分流法和每条的具体处理。

Claude Code 一直报 529 Overloaded 怎么办？先分清是服务端还是你这边

529 overloaded_error 会带着「Retrying in N seconds（attempt X/10）」刷屏。本文讲清自动重试机制的三个可调参数、官方给的处理，以及怎么判断这次到底是不是服务端的问题。

Claude Code 报 Error during compaction 怎么解决？三种压缩报错要分开治

/compact 失败其实有三种不同的报错，成因和解法完全不一样。本文按官方文档的处理、社区在 issue

Claude Code 流式响应中断怎么办？Connection closed、Socket is closed、Stream idle timeout 三条分开看

回答写到一半断掉，是长任务里最烦的一类故障。本文按官方错误参考区分三条流中断报错——有的有明确版本修复，有的只能靠 continue 恢复，有的至今没有定论。

Claude Code 报 Prompt is too long 怎么解决？五个吃上下文的大户

上下文满了不只有「聊太多」一个原因。本文按官方处理逐条拆开五个吃上下文的地方——MCP 服务、CLAUDE.md、大文件粘贴、工具输出、历史对话，并给出用 /context 定位的方法。

Claude Code 启动就崩报 Invalid Version 怎么解决？一个 changelog 日期引发的事故

2.1.0 版本有一次启动崩溃，真因是缓存的 changelog 里带了日期导致 semver 解析失败。本文讲清社区在 issue

订阅明明没用完却报 Rate limit reached？先分清限流、配额和并发三件事

有人在 Max 订阅只用了 16% 的情况下持续撞限流。本文拆开 Claude Code 里三种「被拦住」的报错——短期限流、套餐配额、并发限制，给出各自的判断方法和官方处理。

Claude Code 搜不到文件、@file 不好使怎么解决？多半是 ripgrep 跑不起来

Search 工具、@file 提及、自定义 agent 和 skill 都依赖同一个底层组件。本文给出官方的换用系统 ripgrep 的完整步骤、验证方法，以及 WSL 上那个「显示正常但结果偏少」的特殊情况。

公司网里 Claude Code 报 SSL 证书错误怎么解决？以及为什么别关证书校验

企业代理拦截 TLS 会导致证书校验失败。本文给出官方的 NODE_EXTRA_CA_CERTS 配置方法、官方明确禁止的那个做法，以及企业网环境下一整套连接类报错的排查顺序。

Cline 在 JetBrains 里报 Healthcheck timed out、MCP hub not available 怎么解决

一个是 macOS 拦住了 IDE 启动子进程，一个是把面板挪到副侧边栏引起的。这两条的真因都在你想不到的地方，本文给出社区验证过的具体操作。

Codex 报 stream disconnected before completion 怎么办？先查是不是模型没解锁

登录之后发第一条消息就断流，可能不是网络问题。issue

Codex 的 /compact 一直失败怎么办？那个 150 秒不是巧合

Error running remote compact task 背后有个可推算的时间结构：30 秒超时乘 4 次重试。本文讲清这个数字的含义、issue 的修复状态，以及为什么「等了两分半才报错」本身就是最有用的线索。

Codex 在 VS Code 里看 Diff 报 Oops, an error has occurred 怎么解决

这条报错的社区办法是降级扩展到一个具体版本并关掉自动更新。本文给出那个版本号、操作步骤，以及原报告者试过但无效的五种做法——知道什么没用同样省时间。

Continue 报 Token limit reached 编辑失败怎么办？附官方排查入口速查

这条报错说的是编辑范围太大，而调大上下文窗口未必有用。本文给出社区已验证无效的做法、以及 Continue 官方文档里日志、预发布版、证书、MCP 路径几个排查入口的具体位置。

Copilot Agent 模式老报 Request Failed: 408 怎么解决？官方团队解释了触发条件

408 的报错文本里其实写了答案——上传聊天上下文和提示词的时间超限。GitHub Copilot API 团队在 issue 里给出了官方解释。本文按这个解释给出可操作的应对，并附上 Could not parse ov 的修复版本号。

Devin 常见问题排查：额度何时刷新、账单为何变高、Windsurf 用户入口去哪了

三类最常被问到的 Devin 使用问题一次讲清——用量额度按日/按周自动刷新意味着什么、超额按 API pricing 计费为什么账单难预估、原 Windsurf 用户访问定价页被 308 永久重定向到 devin.ai 后该做哪五件事。

Devin 超额按 API pricing 计费是什么意思？超支了怎么控成本

Devin 定价页写明超出套餐后购买的额外用量「按 API pricing 计费」。这和固定超额单价是两种不同的机制，成本可预测性差很多。本文讲清两者区别，并给出超额期间压低实际 token 消耗的四个具体动作。

Devin 的用量按日、按周自动刷新是什么意思？怎么排工作节奏

Devin 定价页写明用量额度按日、按周自动刷新。这篇讲清「刷新周期」和「月度总额度池」的机制差异，说明为什么省不下来也栽不狠，并给出把大任务拆到多天推进的具体排期方法，以及官方没写明的部分怎么自己观察出来。

Devin 五档套餐怎么选？Teams 的人均成本要这样算

Devin 五档套餐只公布了价格，没公布每档含多少额度。这篇讲清哪些能算、哪些算不了，把 Teams 档「$80 固定费 + $40 每座位」的人均摊薄算成表，并说明按日按周刷新对排期的影响。

Devin Teams 档「$80/月 + $40/座位」怎么算账？人均成本随规模怎么变

Devin 的 Teams 档不是简单的按人头收费，而是固定费加座位费的两段式结构。本文把 3 到 50 人的总价和人均成本逐档算出来，说清那 $80 固定费是怎么被摊薄的，也讲明白哪一部分账我算不出来、为什么算不出来。

Devin 和 Augment Code 怎么选？两种团队定价结构的账要分开算

Devin Teams 是固定费加人头费的两段式，Augment 的 BUSINESS 是纯固定价加美元额度。这篇把两种结构在 3 到 50 人规模下的人均成本算成表，说清各自算不清的地方，并给出按团队规模和核算需求的选择路径。

Devin vs Claude Code 怎么选？撞额度后一个能加钱、一个只能等

两家的额度都靠时间恢复，但 Devin 撞限后可以额外购买用量按 API pricing 计费，Claude Code 撞限只能等窗口滚过去。这篇从额度周期、撞限出路、代价形态、账单可预期性四条线拆开对照，并给出 Teams 两段式定价的人均算例与场景化选法。

Devin vs Cursor 怎么选？一个按时间刷新，一个降速接着用

两者的额度都会"用超"，但善后方式完全不同：Devin 的用量按日、按周自动刷新，超了得等下一个周期；Cursor 是把你降到慢速池里继续跑，账单封顶。本文按赶工期、卡预算、节奏间歇、长期高强度四类场景给判断路径。

Gemini CLI 装不上、命令找不到、MODULE_NOT_FOUND 怎么解决

安装期的三类问题——PATH 没配好、依赖没装全、npm 弃用警告吓人。本文按官方 troubleshooting 逐条给出处理，并说清哪一条警告其实可以直接忽略。

Gemini CLI 报 Cannot read properties of undefined (reading 'candidates') 怎么办

这条报错是客户端解析响应时崩了，不是模型说错话。本文讲清它的性质、为什么不该往配置方向瞎试、issue 的真实状态，以及能立刻用的排查与减损办法。

Gemini Code Assist 标准版和企业版怎么选？两档的每分钟上限完全一样

标准版 1500、企业版 2000，但每分钟都是 120。本文摆清两档官方给出的全部差别、说明为什么本文不给价格，以及在没有价格的情况下该怎么判断要不要升。

有 Google AI Pro 订阅，为什么第三方工具还报免费档限流？

订阅和 CLI 免费档可能是两套额度，走第三方插件时更容易搞混。本文讲清额度按什么维度计算、多个工具共用一个账号会发生什么，以及怎么定位额度被谁吃掉了。

Gemini CLI 额度怎么算？四档请求上限、双重限流与「一次请求」的真实含义

Gemini CLI 的额度单位是 model request 而不是 token，而且每日和每分钟是两条独立的上限。本文把四档的官方数字摆清楚，讲透哪个上限会先撞、哪些数字官方压根没给，以及该怎么自己测。

Gemini CLI 每分钟 60 次够用吗？分钟限流才是真正卡你的那条线

每日 1000 次听起来很宽裕，但很多人先撞上的是每分钟那条。本文算清 60 次/分钟在实际使用中意味着什么、哪些场景最容易撞、以及升级对两条线的收益差别。

Gemini CLI 报 Model stream ended 系列错误怎么办？三条流中断的判断方法

invalid chunk、empty response text、Premature close 这三条都是流式响应没正常收尾。本文说清它们各自对应的 issue 状态、为什么至今没有公认解法，以及能立刻用的判断方法和减损做法。

Gemini CLI 报 0 occurrences found for old_string 怎么解决？改文件失败的确定性排错

这条报错跟网络、额度、服务端都没关系，重试一百次也是同样结果。本文讲清它的成因、四类常见的匹配差异，以及怎么让它一次改对。

Gemini CLI 报 Operation not permitted / Permission denied 怎么解决？沙箱在拦你

这条报错不是文件权限不够，是沙箱在限制越界操作。本文讲清沙箱的边界在哪、退出码 44 的用法、EADDRINUSE 这类容易被误判的相关报错，以及排查顺序。

Gemini CLI 走 Vertex AI 划算吗？Express Mode 那 90 天和单位切换要先搞清楚

Vertex 这条路的额度单位从「请求次数」变成了 token，你在前面几档积累的经验全部作废。本文讲清 90 天的含义、单位切换带来的估算难题，以及什么情况下值得走这条路。

Gemini CLI 和 Claude Code 怎么选？两种额度形态决定了两种用法

一个按请求次数给明确上限，一个按订阅配额且用完要等重置。本文对比两者的额度形态、撞限时的处置差异，给出按场景的选择建议。

Gemini CLI 和 Codex 怎么选？一个额度写在明面上，一个文档是空白

除了额度机制，两者在「出问题时你能不能自救」这一点上差别很大。本文从官方文档完备度这个少有人比的角度切入，给出实际的选择建议。

Gemini CLI 和 Cursor 怎么选？终端和编辑器是两种工作方式

这两个不完全是竞品——它们对应的是两种不同的写代码方式。本文从工作形态切入，讲清各自适合什么场景，以及为什么很多人最后是两个都用。

同是 Google 的 Gemini CLI 和 Jules 怎么选？一个陪你干，一个替你干

两个都出自 Google，额度单位却完全不同——一个按请求次数，一个按任务数和并发。本文讲清这两种形态各自适合什么活，以及一条容易被忽略的账号门槛。

Gemini CLI 和 Zed 的免费档怎么比？一个给请求次数，一个给编辑预测

两家都有能长期用的免费档，但给的东西完全不同，没法比大小。本文从「免费档能支撑什么工作方式」这个角度对照，给出按习惯的判断。

Gemini CLI 报「必须是组织订阅的具名用户」怎么解决？个人账号被误判的三条登录报错

明明是个人 Google 账号，却被要求组织订阅授权——真因是两个环境变量触发了组织校验。本文按官方 troubleshooting 拆开三条登录族报错的区分方法与解法，并说清它们各自对应哪一档额度。

Jules 并发只有 3 个够用吗？并发才是异步 Agent 的真正瓶颈

免费 3 个、Pro 15 个、Ultra 60 个——这条线比每日任务数更容易成为瓶颈。本文讲清并发对异步 Agent 意味着什么、怎么判断自己卡在哪条线上。

Jules 额度怎么算？15、100、300 个任务分别意味着什么

Jules 用「任务数」当额度单位，这跟按 token、按请求、按 credits 的工具都不一样。本文讲清任务这个单位的特点、每天 15 个够不够用，以及为什么这个单位对使用习惯的要求最高。

Jules 付费档只支持个人 Gmail 账户？企业和团队要先看这条

官方文档明写付费计划目前仅适用于个人 Google 账户，其他账户类型的升级路径仍在开发中。这条限制对团队选型的影响，比任何额度数字都大。

Jules 三档怎么选？在官方没公布价格的情况下也能做的判断

免费、Pro、Ultra 三档的任务数、并发、模型访问都不同，但官方用量页没给价格。本文给出一套不依赖价格的评估流程，让你拿到报价时能立刻算清楚。

Jules 和 Claude Code 怎么选？派活给它 vs 坐在旁边一起干

一个是异步派任务，一个是同步交互。本文讲清这两种工作方式各自适合什么活、额度形态如何跟着变化，以及为什么很多人两个都需要。

Jules 和 Devin 怎么选？两个异步 Agent，额度形态完全不同

一个按任务数和并发给明确上限，一个按自己的计量口径走。本文对比两者的额度形态、免费档形态和账号门槛，给出按场景的判断。

Jules 和 OpenHands 怎么选？两个自主 Agent，一个绑账号一个能自部署

都是派活给它自己干，但一个有个人账号的硬门槛，一个有开源自部署的路。本文对比两者的额度形态、门槛和适用场景。

Kilo 买 credits 收 5% 手续费，年付有 50% bonus——这两条都在价格表之外

一个是充值时额外收的，一个是折扣方向的。本文讲清这两条对总成本的影响、预付制该先确认什么，以及为什么本文不替你做叠加推算。

Kilo Gateway 说零加成，这意味着什么？跟自带密钥比该选哪个

官方原文是 Pay exact provider rates with no markup。本文讲清零加成的实际含义、它跟自带密钥的真正区别在哪，以及零加成不等于免费这件事。

Kilo Pass 三档怎么选？那个 bonus 比例值得自己核一遍

官方标称 Up to 50% bonus credits，而页面给出的 19 美元对 26.60 美元算下来是 40%。本文照抄原始数字、把这个差异摆出来，并给出预付制该怎么判断的方法。

Kilo 的费用为什么算不清？平台、推理、云计算是三层叠加的

很多人只看到「Kilo Gateway 零加成」就以为便宜，漏掉了平台席位费和云计算按小时的费用。本文把三层拆开，说清它们是叠加而不是三选一，并附上官方域名迁移的实测记录。

Kilo 和 Cline 怎么选？两个 BYOK 插件，一个加了三层，一个只做一层

都是装在编辑器里、自己带模型密钥的插件，但 Kilo 在 BYOK 之外还有平台费和云计算层。本文对比两者的成本结构与排查体验。

Kilo 和 Jules 怎么选？一个装进编辑器，一个派活给它

一个是你手边的插件，一个是异步跑任务的 Agent，两者的额度形态和适用工作完全不同。本文讲清什么活该派给谁。

Kilo 和 Kiro 怎么选？一个把费用拆三层，一个用一个 credits 走到底

两家的名字像，计费思路完全相反。本文对比分层定价和统一 credits 两种结构的优劣，给出按用量形态的判断。

Kilo 和 OpenHands 都说零加成，差别在哪？

一个写 no markup，一个写成本价无加价，两家在模型费上都不赚差价。那它们靠什么赚钱、你该选哪个？本文从「付费墙在哪一层」切入对比。

Kilo 的云计算按小时收费，这层最容易被漏算

Gas Town 每小时 1.20 美元、Code Review 每小时 0.33 美元、Cloud Agent 每小时 0.60 到 1.20 美元，按秒计费无最低消费。本文讲清这层的成本形态和该怎么估。

Kiro 怎么安装、怎么登录？五种形态与四种登录方式的上手全流程

Kiro 有 IDE、CLI、Web、Mobile、Crew 五种形态，系统要求各不相同，登录也有四条路可走。这篇按「先选形态、再选登录、最后跑首次流程」的顺序讲清楚，并把公司代理环境下最容易踩的登录坑单独拎出来说。

Kiro 装不上、登不进、额度对不上？三类常见问题的排查顺序

按症状而不是按错误码来排查 Kiro：装不上先核系统要求（附五种形态的对照表），登不进优先查「浏览器登录绕过代理」这一条，新版本出问题可以直接降级止损，额度对不上则给出一套自测方法。

Kiro 的 credits 怎么省？六类实操技巧和一条超额分界线

Kiro 官方没公开单次操作扣几个 credit，也没写刷新周期，所以省额度不能靠避开某个贵操作。这篇给出六类可复制的实操做法、一套自测日均消耗的方法，以及一条用 $0.04 超额价算出来的「该省还是该升档」分界线。

Kiro 登录失败怎么排查？四层清单定位到底卡在哪一环

Kiro 登录卡住最常见的成因是代理：它支持 HTTP_PROXY 等环境变量，但浏览器登录这一步会绕过代理设置。本文给出网络、代理、登录方式、账号四层排查清单，帮你把问题定位到具体一环，而不是反复点重试。

Kiro 额度怎么算？五档 credits、超额单价与省额度实操

Kiro 用 credits 当额度单位，五档套餐从 50 到 10000 不等，超额按 $0.04/credit 续着用。本文把这套账摆清楚，讲清哪些数字官方写了、哪些没写，并给出选档和省额度的实操判断。

Kiro 五档套餐怎么选？每美元 credits 完全一样，按用量选档

Kiro 五档从 $0 到 $200，每美元都是 50 credits，高档位不给批量折扣。所以选档不是「买大更划算」，而是买刚好覆盖用量的那一档。本文给出五档表、每美元换算的复核、日均消耗的测法，以及从月用量直接对应到档位的决策路径。

Kiro 团队版怎么算钱？席位价格、额度分配与采购策略

Kiro 团队版四档都是「每用户每月」，credits 按人发放而不是团队共享池。本文用一个 10 人团队的完整算例，讲清为什么全员统一档位一定浪费钱，怎么按人配档、怎么用升档分界线做决策，以及第一个月该怎么摸清用量分布。

Kiro vs Claude Code 怎么选？看形态和额度恢复这两条轴

不比模型强弱，只比两件能核实的事：形态差异，以及额度用完那一刻的恢复方式——Kiro 按 $0.04/credit 继续买，Claude Code 只能等窗口滚过去。附四种场景的选法与一条决策路径。

Kiro vs GitHub Copilot 怎么选？先看额度能不能算清

不比谁的模型更强，只比一件事：额度体系能不能提前算清。Kiro 五档 credits 与超额单价全公开，升档分界线可以用除法算出来；Copilot 的价值有相当一部分绑在 GitHub 工作流里，换算不成 credits。本文给出四种场景的选择和一条决策路径。

Kiro vs Cursor 怎么选？额度用完那一刻的差别最关键

Kiro 用 credits 计费、超额按 $0.04 续着买；Cursor 用快慢两档、额度用完降级到慢速池。这两种机制决定了完全不同的使用体验。本文给出按场景选择的判断路径。

Kiro vs Devin 怎么选？超额成本能不能提前算准是分水岭

不比谁的模型强，只比一件真正影响你钱包的事：超出套餐额度之后，成本还能不能提前算出来。Kiro 是固定单价可以列公式，Devin 按 API 定价浮动只能事后看账单。附五档价目、升档分界线、Teams 两段式人均成本算例和分场景决策路径。

Kiro vs Trae 怎么选？打包额度与自带 API 两种成本承担方式

Kiro 卖明码标价的 credits，厂商替你调模型；Trae 走接自定义模型和中转 API 的路子，模型成本落到你自己的 API 账户上。本文拆开这两种成本承担方式的机制差别，给出按场景的选择路径和密钥管理提醒。

Kiro vs Warp 怎么选？同样用 credits，选档逻辑却完全相反

Kiro 四个付费档统一 50 credits/美元，往上买一分不省；Warp 的 Max 档比 Build 档每美元多给 20% 额度，用量大买大档真的划算。这篇算清两家的换算表、升档分界线和自动充值的风险，给出按场景的选择路径。

MCP error -32602 是什么意思？这个错误码有歧义，别只按「参数错了」查

-32602 官方叫 Invalid params，但它同时覆盖缺必填 _meta 字段和多种格式错误。本文讲清它的歧义在哪、必填字段有哪些、以及怎么跟 -32021、-32022 区分开。

MCP 服务出问题去哪看日志？Claude Desktop 的日志路径与 DevTools 开法

MCP 排查的第一步是看日志，但很多人不知道日志在哪。本文给出 macOS 与 Windows 的日志路径、实时跟看命令、DevTools 的开启方式，以及日志里该找什么。

MCP error -32000: Connection closed 怎么解决？客户端报连接关闭，真因多半在服务端

-32000、Server transport closed unexpectedly、Client Closed、Not connected 这几条报错说的往往是同一件事：服务端进程压根没起来。本文按官方调试文档给出排查顺序、五个高频真因和日志位置。

MCP Inspector 怎么用来排查问题？官方建议的第一站，能一刀切开客户端和服务端

在客户端里反复重启试错，是排查 MCP 最慢的方式。本文讲清 Inspector 在排查中的定位、能划清哪些界限、以及配合日志的完整开发调试循环。

MCP 配置为什么手动跑没问题、客户端一起就挂？工作目录和环境变量两个坑

同一条命令你在终端跑得好好的，客户端拉起来就失败——原因通常是这两个：工作目录可能是未定义的，环境变量只继承一个有限子集。本文给出官方的正确写法与自查方法。

MCP 服务加了一行日志就连不上了？stdout 是协议通道，不能往里打字

官方对 stdio 传输有一条明确警告：本地 MCP 服务绝不能往 stdout 打日志，会破坏协议通信。本文讲清这个坑的原理、正确的日志做法、以及 HTTP 传输下的差异。

OpenHands 说按成本价无加价，跟自带密钥比该选哪个

Individual 档给了两条超额路径，一条自带密钥、一条按成本价计费。本文拆开这两条的实际差别、成本价这个说法该怎么核实，以及它跟其他工具定价姿态的对照。

OpenHands 自己部署还是用 SaaS？本地无限制换的是你的运维精力

开源本地档没有额度限制，SaaS 个人档每天 10 次对话但省掉部署。本文把这个取舍拆成可判断的几条，并说明什么情况下自部署是必须而不是选择。

OpenHands 免费档每天 10 次对话够用吗？这个数字背后的取舍

个人 SaaS 档是免费的，但每天最多 10 次对话。本文讲清这个额度的性质、「对话」这个单位的特点，以及为什么它比看起来更够用（或更不够用）。

OpenHands 和 Devin 怎么选？开源可自部署 vs 闭源云服务

一个能把整套东西搬进自己的内网，一个是托管服务。本文讲清这个差别在什么场景下是决定性的，以及各自的成本结构。

Roo Code 报 did not provide any assistant messages 怎么办？先分清是版本回归还是接入层

空响应类报错在 BYOK 工具里特别常见，因为链路上多了一层。本文给出一个能快速定位的对照实验，以及 issue 里那条「旧会话正常、新会话全废」的关键线索。

Warp 用不下去了？额度、自动充值、账单与团队席位的排查手册

Warp 出问题往往不是报错，而是额度掉得比预期快、自动充值扣多了、团队加不进人。本文按症状拆四类常见情况，给出可自测的额度估算法、自动充值的三条防线、25 席位上限的采购判断，以及每美元额度的换算表。

Warp Business 的 25 席位上限意味着什么？团队采购必算的三笔账

Warp Business 每人每月 50 美元、含 1500 credits、最多 25 席位。这篇把它换算成「每美元多少 credits」，讲清 25 这条线对扩张中团队的实际约束，并给出按团队规模走的采购决策路径。

Warp AI 额度怎么算？四档 credits、年付折扣与自动充值

Warp 的额度单位是 credits，Build 档 $20 给 1500、Max 档 $200 给 18000——高档位每美元买到的额度多 20%。本文算清四档的真实单位成本、年付到底省多少，并说明哪些数字官方没写。

Warp 年付到底省多少？三档折扣都是 10%，但省下的钱差 10 倍

把 Warp 的月付价与年付价逐档换算成一年实际支出：Build 省 24 美元、Max 省 240 美元、十人 Business 省 600 美元。折扣比例都是 10%，绝对金额却差十倍，年付值不值因人而异。文末给一条能直接执行的判断标准。

Warp 上手：把 AI 装进终端之前，先想清楚这四件事

Warp 是终端本身而不是终端里的插件，换过去意味着替换你的日常工作台。本文讲清它的形态定位、四档额度结构、自动充值的双刃性，以及终端 AI 特有的消耗模式与安全边界。

Warp 套餐怎么选？把四档折算成「每美元多少 credits」就清楚了

Warp 的 Build、Max、Business 三档付费套餐单价差得很远：每美元能买到的 credits 分别是 75、90、30。这篇把四档换算成同一把尺子，讲清楚哪档是批量折扣、哪档买的根本不是额度，以及 25 席位上限对扩张中的团队意味着什么。

Warp vs Claude Code 怎么选？一个额度能买、一个只能等

两者都在终端里干活，但额度机制根本不同：Warp 的 credits 用完可以加钱买、还能自动充值；Claude Code 的时间窗口限额用完只能等重置，钱解决不了。本文按场景给判断路径。

Warp vs Cursor 怎么选？一个在终端、一个在编辑器

Warp 是终端本身，Cursor 是编辑器，两者压根不在同一个地方干活。额度用完的代价也不同：Warp 花钱买 credits、可自动充值，Cursor 降速排队、账单天然封顶。本文给出换算表、场景对照和决策路径。

Warp vs Devin 怎么选？额度池与自动刷新是两种节奏

Warp 给你一个月度 credits 池，用多用少自己分配，还能自动充值续上；Devin 的额度按日、按周自动刷新，攒不住但也不会整月停摆。这篇按工作节奏、成本可预测性和形态差异拆开讲，最后给出四个场景的选法和一条决策路径。

Windsurf 定价页跳到 Devin 了？308 重定向实测与老用户自查清单

windsurf.com/pricing 当前返回 308 永久重定向到 devin.ai/pricing，定价入口已经合并。本文只讲实测到的事实、Devin 现行五档定价，以及工具被并入后你该做的自查动作。

用 WorkBuddy 做周期性自动报表：周期边界、数据缺失与口径变更这三处最容易翻车

把每周每月手动做一遍的报表交给 WorkBuddy 定时跑，难点不在配置而在口径。本文只讲报表这类任务的特殊之处——数据源怎么锁定、"上周"到底指哪七天、数据没更新时怎么让它别编、口径变了怎么改，并给出可直接复制的完整指令与验收清单。

WorkBuddy 接入了 QQ、企微、微信、飞书、钉钉，机器人却不回复怎么办

WorkBuddy 端显示已注册、已绑定，但在 QQ、企业微信、微信、飞书、钉钉里发消息机器人不回复。本文按「电脑侧 → 连接状态 → 切换模型 → 平台侧配置」四步分诊，逐条对应官方文档给出的处理方式，并说明鸿蒙微信扫码、企微域名主体校验这类各平台独有的坑该怎么识别。

财务对账让 WorkBuddy 做？只让它出差异清单，别让它下结论

银行流水和内部台账对不上时，费时间的是逐条比对。本文给出把对账交给 WorkBuddy 的完整指令、差异清单的字段设计、必须由人定的六条匹配口径，以及总额勾稽的验收方法，并说清它找不出来的三类差异和三种不适用场合。

WorkBuddy 点了没反应、登录失败怎么解决？官方给的三类原因与排查顺序

WorkBuddy 打不开登录窗口或登录失败，官方文档归结为默认浏览器、目录权限、安全软件拦截三类原因。本文按从快到慢的顺序给出排查路径，附官方原文的 Mac 与 Windows 权限检查与授权命令，以及 ARM64 这个无解情况的识别方法。

电商运营用 WorkBuddy：详情文案、评价汇总与上下架清单怎么交出去

电商运营每天被三摊碎活占满：写详情页卖点、翻几百条买家评价找问题、整理上下架和库存清单。本文按 WorkBuddy 官方文档的四要素给出三份可直接复制的指令，重点讲参数为什么必须你自己提供、评价归类怎么防断章取义、绝对化用语为什么必须人工再扫一遍。

用 WorkBuddy 做调研报告：边界怎么划、指令怎么写、结论怎么验

让 AI 做开放式调研，最大的风险不是它查不到，而是它把查到的东西直接当成结论。本文按 WorkBuddy 官方文档给出可复制的调研指令、限定边界的三个维度、区分事实与观点的验收清单，以及四种明确不该交给它的调研。

WorkBuddy 接入钉钉机器人：三个权限、管理员前提与远程派活的验收方法

把 WorkBuddy 接到钉钉，就能在手机上给电脑派活。本文按官方平台接入指南梳理钉钉侧的建应用、加机器人、开三个权限的完整路径，说明"账号未加入组织"怎么解，并给出可复制的远程指令模板、交付物形态、四步验收和四种不适用的情况。

WorkBuddy 定时任务怎么设？六个配置项、上线前该跑通的两步与数量上限

WorkBuddy 的自动化能适合周期性重复任务。本文按官方文档拆开六个配置项各自的作用，给出"先手动跑通再定时"的两步上线法、提示词里必须写死的三件事，以及各档自动任务数量上限这个容易忽略的约束。

WorkBuddy 怎么写短视频脚本？口播文案指令、时长换算与四步验收

短视频脚本难的不是结构，是写出来的句子能不能开口念。本文按官方自媒体运营案例给出可直接复制的口播脚本指令，讲清口播文案与书面文案的区别、时长怎么换算成字数、分镜建议该怎么用，以及三种别交给它的情况。

用 WorkBuddy 合并多份表格：表头对不齐怎么办，指令、交付物与验收清单

分月、分部门的 Excel 汇总成一张，难点不是合并本身，而是同一个字段在各表里叫法不同、列序不同，以及重复记录该留几条。本文给出可直接复制的合并指令、字段映射写法、四步对账验收，以及三种明确别交给它的情况。

WorkBuddy 多少钱？中国站四档价格、年付折算与积分够不够用

WorkBuddy 中国站个人版分体验、标准、高级、旗舰四档，另有企业版两档。本文按官方定价页列出连续包月与连续包年的实际价格、四档积分与自动任务数差异，并说明限免权益和套餐不支持变更这两处最容易踩的坑。

用 WorkBuddy 写 Excel 公式：三类需求的指令模板与反算验收法

让 AI 写公式容易，让它写对不容易。本文拆开写公式、解释公式、排查算错的公式三类需求，给出可直接复制的指令模板，重点讲怎么用已知答案的数据反算验收边界情况，以及哪些表格不该交给它。

用 WorkBuddy 清洗 Excel 脏数据：规则怎么写死、指令怎么给、清洗完怎么对账

表格去重、补空值、统一日期格式、标异常值、拆合并单元格，交给 WorkBuddy 之前得先想清楚一件事——清洗是在改原数据。本文按官方任务四要素给出可直接复制的清洗指令、先看后改的两轮拆法、以行数对账为核心的验收清单，以及四种明确不该交给它的情况。

WorkBuddy 怎么整理发票？重命名预览、报销台账与必须人工核的三个字段

一堆命名混乱的 PDF 和扫描件发票，怎么交给 WorkBuddy 归类重命名并提取成报销台账？本文给出可直接复制的两段指令、台账七个字段的定法、四步对账验收清单，以及金额、税号、开票日期为什么必须人工逐张核对。

用 WorkBuddy 做合同初筛：把条款摆出来，对着审查清单查缺项

法务拿到一份合同，费时的是把该看的条款定位齐。本文讲怎么用 WorkBuddy 把单份合同拆成条款清单、拿公司内部审查清单逐条核有没有、把缺失项单独列出来，并按文本特征标出需要人工重点阅读的位置。含三轮可复制指令与四步验收，以及一条不能越的线。

WorkBuddy 接入飞书：先确认你有建应用的权限，再谈远程派活

飞书是 WorkBuddy 九个助理平台里最麻烦的两个之一，要企业账号加创建应用权限，还要批量导入一长串权限 JSON。本文按官方文档梳理完整配置顺序、权限清单意味着多大的授权范围、远程派活的指令怎么写与怎么验收，以及哪些企业环境根本不该走这条路。

用 WorkBuddy 批量转换文件格式：指令模板、试跑流程与验收清单

Word、PDF、Markdown、Excel、CSV 批量互转，难的不是转，是样式、页眉、公式、图片在转换中掉了。本文按官方文档给出可直接复制的批量转换指令模板、先拿一两个文件试跑再放开整目录的推荐流程、四步验收清单，以及三类明确不该交给它的文件。

WorkBuddy 做公众号选题：建一张能长期维护的选题库

公众号更不下去，卡住的往往不是写作而是选题。本文给出用 WorkBuddy 建一张长期可维护选题库的六个字段、可直接复制的建库与补库指令、判断「角度是否真的不同」的去重复查方法、把大主题拆成系列的做法，以及内容日历排期、验收四查、每周自动补库的边界和四种不该交给它的情况。

WorkBuddy 升级后工作空间和历史记录不见了？先分清是哪一种「消失」

WorkBuddy 更新或隔天重启后找不到原来的工作空间，官方文档里其实对应三种完全不同的情况：目录还在只是界面没显示、项目建在安装目录被更新清空、以及助理工作空间的历史会话本来就不全展示。本文按官方口径逐条给出找回路径与判断方法，并把「怎么才不会再丢」讲透。

WorkBuddy 两套定价对不上？中国站四档与官方文档美元档的差别

查 WorkBuddy 价格常会撞见两套对不上的说法——中国站是人民币四档，官方文档中文页是美元 Free/Pro/Team 三档。本文把两套原样并列，说明积分与自动任务数的差异，以及为什么不该把两边档位互相换算。

WorkBuddy 接入 Slack、Telegram、Discord：三个平台的配置步骤、凭证对照与验收清单

把 WorkBuddy 助理接到 Slack、Telegram、Discord 上，三个平台的准备工作差别不小。本文按官方平台接入指南逐字整理三条配置路径、需要的凭证数量对照、接入后第一条任务指令怎么写、怎么验收，以及三种明确不该走远程的情况。

用 WorkBuddy 梳理合同：批量提取条款、生成台账、比对多份差异

合同梳理真正费时的是把几十份文件里的关键条款抠出来对齐成一张表。本文给出可直接复制的台账指令与差异比对指令、扫描件读不出来的官方原因与处理办法、四步验收清单，以及必须由法务和律师兜底的边界。

HR 用 WorkBuddy 做简历初筛表：字段提取指令、隐私隔离与不能碰的红线

招聘旺季一批简历堆在文件夹里，逐份翻着抄字段最耗时间。本文按 WorkBuddy 官方文档的任务四要素给出可直接复制的简历字段提取指令，说明 PDF 与图片读不出来时官方怎么处理、简历这类个人信息该怎么隔离目录，并划清一条硬线：初筛表只能用来排序，不能用来淘汰人。

WorkBuddy 怎么整理会议纪要？官方示例指令、责任人对齐验收与三种别交给它的会

会议纪要卡人的不是写字，是把转写稿、聊天记录和零散笔记拼成一份能发出去的东西。本文给出 WorkBuddy 官方文档里整理纪要的原文示例指令、按四要素扩写的可复制版本、两轮推进的拆法，以及责任人与截止时间怎么逐条验收、哪些会议不该交给它。

WorkBuddy 积分加量包怎么买？五档价目、单位成本实算与三条硬规则

WorkBuddy 积分不够用时可以买一次性加量包。本文按官方文档列出 Pro 与 Team 两类加量包的美元价目与有效期，把五个档位的单位积分成本实际算一遍，说明加量包与升套餐该怎么选、六个月有效期该按什么方法估，以及中国站为什么查不到加量包价格。

教师用 WorkBuddy 备课：教案、练习题与学情统计表的指令与验收

备课交给 AI，难点不在写教案，而在对齐学情和教材版本。本文给出可直接复制的教案指令、配套练习题与脱敏学情统计表的做法，写清练习题必须逐题自算的验收流程，以及学生个人信息绝不进工作目录这条硬边界。

WorkBuddy 积分不够用了怎么办？五个省积分的办法和两条加量正路

WorkBuddy 积分月中就见底，先别急着升档。本文按官方口径讲清怎么查用量明细定位是哪类任务在吃积分，从官方给的三个影响因素反推出五条可执行的省法（模型分级、小步快跑、别硬撑长会话、慎用专家团、只开必要技能），再说明升级套餐与加量包该怎么选，以及积分当月有效不结转这个容易吃亏的规则。

WorkBuddy 积分怎么算？三个影响因素、扣除顺序与自测方法

WorkBuddy 的积分（Credits）是 AI 操作的统一用量单位，但官方只公布了影响消耗的三个因素，没有单任务价目表。本文讲清三因素怎么读、积分当月有效不结转的规则、Pro 与 Team 各自的扣除顺序、余额在哪里查，以及在没有价目表的情况下怎么用一周时间测出自己的真实消耗。

用 WorkBuddy 做竞品分析报告：搜集指令、来源回溯与四步验收

竞品分析真正耗时间的是搜资料和核对，不是排版。本文按 WorkBuddy 官方文档的任务四要素给出可直接复制的搜集与成稿指令，说明交付物落在哪里、怎么逐条回溯来源核价格与时间，以及三类明确不该交给它的活儿。

WorkBuddy 的记忆功能是什么？要不要开、该记什么、和任务上下文有何区别

WorkBuddy 的「生成对话记忆」默认开启，摘要每晚重新生成，仅本人可见，还支持从别的 AI 导入。但很多人把记忆和任务上下文搞混了，才会有"我明明说过"的困惑。本文按官方文档拆开这个开关的实际边界，并给出该记什么、什么时候该关掉的判断依据。

用 WorkBuddy 做考勤统计：规则怎么写死、月度汇总表怎么验收

考勤统计难的不是算术，是迟到、加班、跨天班次、缺卡、调休抵扣这些判定规则本身，而它们全都写在你们公司的制度里。本文给出把考勤制度原文作为上下文喂进去的做法、可直接复制的完整任务指令、月度汇总表的交付形态，以及总人天对账加抽查逐日核对的三道验收流程和四种不该交给它的情况。

WorkBuddy 连接器怎么用？支持哪些服务、怎么连、授权范围该给到哪一步

WorkBuddy 的连接器把外部服务接进 AI 工作流，目前支持 QQ邮箱、腾讯乐享、腾讯文档、TAPD、微云并可自定义。本文按官方文档拆开连接流程、四类使用场景，重点讲清 QQ 邮箱授权要授哪几项权限、哪一项是可选的、在哪里回收授权，以及断开连接的操作。

WorkBuddy 怎么配 MCP？用户级与项目级怎么选，状态灯红了查哪三处

WorkBuddy 把 MCP 配置做进了界面，不用写代码也不用手改配置文件。本文按官方《MCP》文档拆开两个配置级别的差别与选择原则、企业微信机器人的官方示例配置怎么读，以及状态灯变红时该按什么顺序排查配置内容、命令环境和地址这三处。

WorkBuddy 每日资讯简报怎么做？连邮箱、写指令、防编造与验收清单

每天早上八点收一份资讯简报，是官方文档里给了完整案例的场景。本文按官方步骤讲清连接器前置和先手动跑通再定时的两步法，重点补上简报这类任务的三个特殊约束——信息源怎么限定、信息密度怎么控、怎么逼它附来源，以及没内容可报那天该怎么处理。

WorkBuddy 免费版能做什么？限免括号里和括号外要分开算

WorkBuddy 中国站体验版与官方文档站 Free 版是两套独立体系的免费档，权益表里大量数字带着「限免」括号。本文把括号里的活动权益和括号外的常规额度拆开列，说明限免结束后会掉回什么额度，并给出一套判断自己该不该付费的具体方法。

WorkBuddy 的五个内置模型怎么选？按任务形态挂模型，比默认省一半积分

WorkBuddy 内置五个模型，官方给了明确的分工标注。本文按官方原表拆开每个模型的落点，给出手动切换与 Auto 自动模式的判断依据，并说明模型等级如何直接影响积分消耗，以及为什么"切模型"是官方 FAQ 里反复出现的一线排查动作。

WorkBuddy 该月付、连续包月还是连续包年？三种计费周期怎么选

WorkBuddy 中国站同一档位有月付、连续包月（7 折）、连续包年（5.6 折）三种计费周期，差价不小。本文按官方定价页列出三档的月付与年付实际数字，讲清连续包月和月付的官方区别，以及"已有生效套餐时不支持变更"这条规则为什么决定了新用户别一上来就包年。

WorkBuddy 怎么从 PDF 里提取内容：抽正文、抽表格、批量抽字段的指令与验收

PDF 提取难在两件事：扫描件根本不是文本，表格一抽就错位。本文按 WorkBuddy 官方文档的任务四要素给出抽正文、抽表格、批量抽字段三套可复制指令，讲清读不出文件时官方给的排查顺序，以及产出后必须人工核的四处。

WorkBuddy 批量重命名文件：先出预览再动手，附指令模板与验收清单

一堆 IMG_2831、微信图片、扫描件0032 想按内容重新起名，交给 WorkBuddy 之前得先想清楚一件事：重命名基本不可逆。本文给出带预览要求的完整指令、命名规则怎么定死、改名后三步对账验收，以及官方 FAQ 里那起真实的文件丢失案例。

WorkBuddy 接入企业微信：两种创建入口、长连接与回调怎么选，以及在群里派活的完整指令

把 WorkBuddy 接到企业微信智能机器人上，就能在企微里给电脑派活。本文按官方文档拆开管理员与普通成员两种创建入口、长连接与 URL 回调两种接入方式的凭证差别，给出可直接复制的远程指令、交付物落点、验收要点，以及哪些活儿不该这么干。

WorkBuddy 企业版怎么选？旗舰版与专享版的分界线，以及什么时候该从个人版升上去

WorkBuddy 企业版有旗舰版和专享版两档，价格分别是￥198/人/月和￥316/人/月。这篇按官方定价页把两档的共同特性和专享版独占的四项列清楚，说明两档真正的分界不在功能多少而在是否单租户，并给出从个人版升级的判断依据。

WorkBuddy 接入 QQ 机器人与元宝派：AppID/AppSecret 怎么配、坑在哪

QQ 机器人和腾讯元宝「派」的接入流程同属一个档位——去平台建个 Bot，拿一对 AppID 和 AppSecret 回填到 WorkBuddy。本文按官方平台接入指南写清两条路径的前提、步骤、两个必踩的坑（AppSecret 二次查看强制重置、元宝字段名错位），以及接完之后手机上的指令该怎么写、怎么验收、什么活儿别交给它。

WorkBuddy 的权限与工作目录怎么设？沙箱挡得住越界，挡不住改错

工作目录和权限档位是 WorkBuddy 动手前最该先定的两件事。本文按官方文档梳理工作目录机制、默认权限与完全访问权限的区别、任务隔离规则，以及官方声明的数据安全三层防御，并给出一份可直接照做的目录规划与授权判断清单。

WorkBuddy 任务卡住、跑很久没反应、回复乱码怎么办？先分清是「卡住」还是「慢」

WorkBuddy 任务长时间没动静，官方对「卡住」「运行缓慢」「回复乱码」给的是三套不同处置。本文先给一个判断依据帮你分清症状，再按官方做法排序处理，并说明为什么任务过重和会话过长是这类问题最常见的真因。

WorkBuddy 的日志在哪？反馈、退款、发票分别该找谁

WorkBuddy 出问题时日志文件在 Mac 和 Windows 上的位置、意见反馈入口怎么进、上传日志前要注意什么隐私提醒，以及积分异常、退款、发票、注销这几类账户问题为什么不走意见反馈、官方给的正确路径是什么。附一份提反馈时该附哪些信息的清单。

WorkBuddy 的问一问、做一做、想一想怎么选？三种模式的边界与踩坑点

WorkBuddy 提供 Ask/Craft/Plan 三种工作模式，区别不只是"能不能改文件"。本文按官方文档拆开三种模式的执行权限、适用任务与切换时机，并说明权限两档、工作目录设置和备份纪律这三处最该先搞清楚的配置。

WorkBuddy 是什么？一篇讲清桌面 AI 办公 Agent 的能力边界与上手顺序

WorkBuddy 是腾讯推出的全场景职场 AI 智能体桌面工作台，能读取授权目录并直接产出文件。本文按官方文档梳理它与传统 AI 对话的区别、三种工作模式、Skill 与专家的分层、积分机制，以及新手该按什么顺序上手。

用 WorkBuddy 做活动复盘：素材怎么收、指令怎么写、归因为什么必须单列

活动复盘难在素材散——投放后台的导出、群里的讨论、设计稿、当天临时改的东西各在一处。本文讲清开工前怎么把它们收进一个工作目录，给出两轮推进的可复制指令、五段式复盘报告结构、以对账和时间线为核心的验收清单，以及为什么效果归因必须单独标成待验证假设。

WorkBuddy 适合谁用、谁最好别用？五个判断依据与三类劝退情况

桌面 Agent 不是对所有人都划算。本文按官方文档给出的能力边界，梳理什么样的工作模式能真正吃到它的红利、哪三类情况装了也白装，并给一份下载前就能自己走一遍的判断清单。

WorkBuddy 怎么把数据做成图表？指令写法、图表选型与四处验收

让 WorkBuddy 出图不难，难的是它会替你选图表类型，而图表类型选错结论就会走样。本文给出按官方四项要素展开的可复制指令、什么数据配什么图的判断依据，以及交付后必须核的四处。

用 WorkBuddy 写述职报告：跨季度素材怎么收拢、指令怎么写、数字怎么验

述职比周报难的地方在于跨度——素材散在好几个月的目录里，而且要做取舍。本文给出两轮法的可复制指令、让它切换评委视角审稿的用法、以数字为核心的验收清单，以及三种必须自己动手的情况。

WorkBuddy 的技能（Skills）是什么：怎么装、怎么关、怎么自己造一个

WorkBuddy 的 Skills 是给 AI 装的工具能力。本文按官方文档拆开技能板块的两个区域、三种添加方式、启用与关闭的管理逻辑，重点讲清「仅启用当前任务所需技能」这条官方建议为什么比装多少个更重要，以及用自然语言创建自定义技能的完整做法。

用 WorkBuddy 写 SOP 和操作手册：指令模板、样本锚点与验收方法

部门里那套流程只存在老员工脑子里，一交接就断档。本文按 WorkBuddy 官方文档的任务四要素给出可直接复制的 SOP 生成指令，讲清为什么"给它看一份样本"比写十条格式要求管用，以及手册验收必须让没做过的人照着走一遍。

WorkBuddy 怎么识别图片内容：截图转文档、图里的表格转 Excel、批量票据整理

图片识别最麻烦的地方不是认不出来，是它认错了也不会告诉你，模糊、手写和断线表格会被静默猜过去。本文按 WorkBuddy 官方文档的任务四要素给出截图转文档、表格图转 Excel、批量票据名片整理三条可复制指令，说明交付物落在哪个目录、验收该逐项盯哪几类数字，以及哪三类活不该交给它。

WorkBuddy 和 CodeBuddy 是什么关系？两个产品的区别与该用哪个

名字像、同属一个体系、官网还放在一起卖，很多人分不清 WorkBuddy 和 CodeBuddy。本文按官方文档说清两者的定位、形态与人群差异，指出「办公 vs 编程」这个常见误解错在哪，并给出按任务选工具的判断。

WorkBuddy 接入微信：扫码就能绑，手机发一句话让电脑干活

微信是 WorkBuddy 九个助理平台里接入门槛最低的一个，官方明确无需 App ID、App Secret 等开发凭证，只要扫码。本文按官方文档写清版本要求、五步配置、绑不上时的三种情况、鸿蒙微信的已知不兼容，以及远程下发任务该怎么写、怎么验收、哪些活儿不该交给它。

WorkBuddy 读不出图片、PDF、Excel、Word 怎么办？先做这一步分诊

WorkBuddy 提示读不了图片或文档、生成的文件打不开、移动端传不了桌面文件、工作文件夹拖不进去——这几类故障看着像同一个毛病，解法完全不同。本文按官方文档给出的解法与官方承认但尚无修复方案两级分开讲，并补一条官方文档里没有的分诊路径。

WorkBuddy 做文件归档：目录树怎么设计、指令怎么写、索引清单怎么留

归档和一次性清桌面不是一回事，前者要建一套半年后还能用的结构。本文给出按项目/年份/类型三种目录树的取舍依据、可直接复制的三轮指令、必须一起产出的索引对照表，以及四步验收与四种不该交给它的情况。

用 WorkBuddy 分析销售数据：维度拆解指令、防编因果的写法与验收清单

让 AI 出几张销售图表不难，难的是让它把"降了多少"和"为什么降"分开说。本文按 WorkBuddy 官方文档的任务四要素，给出按月份、产品线、区域三维拆解的完整指令模板，讲清怎么在约束里禁掉编造的因果解释、分三轮推进怎么拆、合计对账与基期核对等五步验收怎么做，以及四种明确不该交给它的情况。

销售用 WorkBuddy 管客户跟进：汇成一张台账，重点抽出"我承诺过什么"

客户跟进最容易翻车的不是忘了联系，是答应过的事忘了做。本文按 WorkBuddy 官方文档的任务四要素，给出把邮件与本地笔记汇成客户台账的完整指令，讲清怎么单独抽出承诺事项、四步对账怎么验收、为什么客户资料必须单独建工作目录，以及离职换岗时这些资料该怎么处置。

行政人员怎么用 WorkBuddy：台账、登记表与通知草稿的指令模板和验收清单

行政的活杂而碎，台账每月一个样、通知写错一个字就得发更正。本文按 WorkBuddy 官方文档的任务四要素，给出固定资产台账与会议室、用品登记的可复制指令，讲清怎么用独立任务和独立工作目录把不同事务分开、台账字段为什么必须先定死、产出后验收查哪几处，以及为什么所有通知类产出只能当草稿、必须人工签发。

WorkBuddy 怎么处理邮件？连接器授权范围、待办抽取指令与只起草不发送的做法

把邮箱交给 AI 之前，得先知道它到底能读多少、能替你做什么。本文按 WorkBuddy 官方连接器文档讲清 QQ 邮箱的连接步骤与四项授权范围，说透「收件箱内近一个月」这条硬边界，并给出汇总收件箱、抽取待办、起草回复的可复制指令、四步验收清单，以及为什么建议只让它起草、不让它发送。

用 WorkBuddy 跟踪品牌与行业动态：指令怎么写、怎么验收、它做不到什么

把「定期搜集几个关键词的公开信息并汇总成简报」这件事交给 WorkBuddy 的完整做法：可直接复制的任务指令、先手动跑通再定时的两步上线、结果发到邮箱或企业微信群的三条通路，以及拿到简报后必做的五项验收检查。同时说清它替代不了专业舆情监测——覆盖面、时效性和召回率都没有保证，漏掉重要信息是常态。

WorkBuddy 的专家和专家团是什么？和 Skill 的区别，以及什么时候用哪个

WorkBuddy 侧边栏的「专家」里藏着两类东西：单个专家和多 Agent 的专家团。它们和 Skill 不是同一层的概念，选错了要么白花数倍积分，要么根本调不动需要的能力。本文按官方文档拆开三者的分工、选择依据，以及专家团产出该怎么验收。

用 WorkBuddy 整理桌面和下载目录：先看官方那条「文件疑似丢失」，再动手

整理桌面是 WorkBuddy 官方 FAQ 明确记录过「部分文件疑似丢失」的场景。本文先把这条风险和官方给的处置办法摆在前面，再给出只看不动、先出清单再移动、跑顺了才定时化的三步做法，附可直接复制的指令、四步验收清单和明确不该交给它的几种情况。

WorkBuddy 的「助理」怎么用：手机遥控电脑干活的九个入口与风险边界

WorkBuddy 的助理是把手机变成电脑的遥控器：手机发消息、电脑执行、结果回手机。本文讲清楚它支持哪九个平台、九个平台的接入难度怎么排、远程指令该怎么写、哪些活儿绝对不该远程下发，以及官方已知的几个坑。

WorkBuddy 怎么接自定义模型？Ollama 本地部署与自定义协议开关

除了内置模型，WorkBuddy 支持在可视化界面里接自定义模型，也支持用 Ollama 把模型跑在本机。本文按官方文档梳理提供商接入、Token Plan 与 Coding Plan、Ollama 离线方案，以及自定义协议开关什么时候要打开。

用 WorkBuddy 做小红书内容：选题指令、去 AI 味的写法与验收清单

AI 写小红书文案最大的毛病是"一看就是 AI 写的"。本文按 WorkBuddy 官方自媒体运营案例，给出可直接复制的选题与成稿指令，重点讲怎么把去 AI 味的约束写进指令、素材目录怎么分、成稿按哪四处验收，以及哪几类内容不该交给它、必须自己填。

自由职业者怎么用 WorkBuddy：报价单、交付清单、工时统计与客户目录隔离

一个人接单，谈单报价做事催款记账全得自己干。本文给出用 WorkBuddy 生成报价单、项目交付清单和工时统计的完整指令模板，以及按客户隔离目录的做法、交付前的自查清单和三类不该交给它的事。

WorkBuddy 怎么做 PPT？三轮拆解法、可复制指令与四步验收

做汇报 PPT 别指望一句话出成品。本文按 WorkBuddy 官方文档的任务四要素给出可直接复制的指令，把官方「小步快跑」技巧落成提炼结论、写大纲、扩展页面三轮流程，并说清交付物形态、四步验收和三种不该交给它的情况。

WorkBuddy 怎么写周报？指令模板、交付物验收与什么情况别交给它

周报难的从来不是写字，是把散在各处的素材凑齐。本文按 WorkBuddy 官方文档的任务描述四要素给出可直接复制的周报指令、两轮推进的拆法、四步验收清单，以及三种明确不该交给它的情况。

Zed 的 2000 个编辑预测够用吗？先搞清楚它是不是你的主要用法

Personal 档给 2000 个已接受的编辑预测，Pro 档改成无限。这两档之间真正的差别就在这里。本文讲清这个额度单位的特点、官方没写明的周期问题，以及怎么测自己够不够。

Zed 该自带密钥还是买订阅？三档里有两档支持 BYOK

Personal 和 Business 都能自带 API 密钥，Pro 则是预置额度加超额加成。本文拆开这两条路各自的成本结构与隐性代价，给出按处境对号的判断。

Zed 超额加 10% 贵不贵？比加成比例更该注意的是滚动扣款

额度用完后按 API list price + 10% 计费，而且每产生 10 美元超额就可能扣一次。本文讲清这两条机制的实际影响，以及怎么给自己设一个心理上的支出边界。

Zed 三档怎么选？两种额度单位并存、+10% 加成与「每满 $10 就扣一次」

Zed 的 Personal/Pro/Business 三档里同时存在两种额度单位——编辑预测次数和美元额度，混着看就会选错。本文按官方定价页拆开三档的真实差别、超额加成比例和结算节奏，给出场景化的判断。

Zed 和 GitHub Copilot 怎么选？一个卖编辑器，一个卖能力

Zed 是把 AI 做进自己的编辑器，Copilot 是把能力装进你现有的编辑器。本文讲清这个根本差别带来的迁移成本、计费差别，以及各自适合谁。

Zed 和 Cursor 怎么选？两种额度单位背后是两种产品思路

Zed 把编辑预测和对话额度分成两项单独计价，这个结构本身就说明了它的产品重心。本文从计费结构反推产品定位，给出按工作方式的选择建议。

Zed 和 Kilo 怎么选？换一个编辑器 vs 给现有编辑器装插件

一个是自带 AI 的编辑器，一个是装在你现有编辑器里的插件。本文讲清这个形态差别带来的迁移成本，以及两家计费结构的对照。

接自定义模型前先确认工具调用：三家 Agent 工具的不同处理方式

给 Agent 换自定义模型时最容易漏掉的不是端点填法，而是模型支不支持原生工具调用。本篇对照 Roo Code、Continue、Zed 三家官方文档在这件事上的处理方式，讲清各自的字段名与含义、该怎么核对、以及这一步管不到的部分。不写价格与模型清单。

aider 模型设置文件放哪一层生效：四个加载位置的优先级与全局设置

aider 的 .aider.model.settings.yml 有四个加载位置，官方文档写明按顺序加载、后加载的优先。本篇讲清这四层分别在哪、extra_params 怎么把参数透传下去、特殊模型名 aider/extra_params 如何让设置对所有模型生效，以及模型元数据文件的用法。不讲价格、额度和完整模型清单。

aider 不认识你的模型：用元数据文件注册上下文上限与单价

aider 遇到没见过的模型 ID 时，可以用 .aider.model.metadata.json 把上下文上限与单价注册进去。本文按官方文档逐个讲清这个文件里出现的字段名、模型设置文件的四处加载位置与优先级、extra_params 透传的用法，并说清这套做法管不了什么。不写价格、额度与模型清单。

base URL 填不填 /v1：几家 AI 编程工具的口径其实不一样

把自定义模型接进编辑器和终端 Agent 时，base URL 这一栏最容易卡住。本篇按官方文档逐家对照 Cline、Kilo Code、Zed、goose 的字段名与可接受形态，给出 Groq 这类真实端点的参照，讲清怎么自己复核、填错时该往哪查。不涉及价格、额度、限速与完整模型清单。

聊天能用补全不工作：补全模型要单独配，它和对话模型的要求不一样

编辑器里对话框答得好好的，行内补全却一个字都不出，多半不是端点没接通，而是补全在配置里是另一条独立的模型条目。这篇讲清「接入方式」和「模型能力」是两件事，用 Continue 的 config.yaml 字段说明补全角色要显式声明，并给出跨产品的字段对照、边界与避坑清单。不讲价格、额度和具体产品的界面长相。

公司网络下代理与证书报错：编辑器走的不是你终端那套代理设置

在公司网络里配 AI 编程工具，最常见的误判是拿终端里 curl 通了当作编辑器也通。这篇按 Continue、Kilo Code、aider、Zed、goose、Gemini CLI 等官方文档记录的配置字段，讲清 HTTP 层设置各家落在哪个文件、哪一项归你手填、怎么确认哪份配置真的生效。不讲链路层排查，也不讲超时重试策略。

模型接上了 Agent 却不动手：编辑器工具调用失效的四类成因与验证方法

自定义模型接进编辑器或终端 Agent 后，对话正常但它只写字不改文件、不跑命令。这篇把这类现象拆成模型能力、客户端能力声明、端点与凭据、手填的长度参数四类成因，逐类给出可自己复核的验证方法，并附各家 base URL 字段名对照表。不讲价格与额度，也不替你判断该选哪家。

编辑器里报 401 但 curl 正常：按三层顺序排查密钥、配置与端点

同一把密钥，终端 curl 通、编辑器里却 401。这篇按可执行的顺序拆开编辑器比裸调 API 多出来的三层——密钥来源、配置优先级、端点拼接，逐层给出该查什么、依据哪一条官方记载。只讲接入层排查，不讲价格、额度、限速和模型清单。

接完自定义模型别急着干活：一份十项验收清单，逐项跑一遍才算接通

把自定义模型接进编辑器或终端 Agent，填完地址和密钥只是第一步。这篇给出十项可逐条执行的验收动作，覆盖端点形态、字段归属、密钥落点、模型 ID 来源、原生工具调用、上下文窗口手填、能力开关、角色分工、配置优先级与特殊 provider 例外。不讲价格、额度和完整模型清单。

编辑器与终端 Agent 接自定义模型：四种配置形态怎么挑

把 Cline、Roo Code、Kilo Code、Continue、aider、Zed、Gemini CLI、goose、Crush 的接入方式归成图形表单、YAML、JSON settings、环境变量与子命令四类，讲清每类的字段落在哪、密钥怎么放、适合什么规模的团队。不讲价格、额度和模型效果排名。

编辑器里AI输出卡住不出字：分段定位是模型、网关还是客户端

流式输出停在半路或者干脆一个字不出，往往不是模型慢，而是链路某一段在等一个不会来的响应。这篇给你一套从端点到客户端配置的分段定位顺序，附各家自定义模型配置里那些要你自己填的字段对照表。不讲价格、不讲额度、不替任何产品断言内部行为。

你的 API key 躺在哪：keychain、配置文件、环境变量三种存法的泄露面对比

用一篇文章讲清编辑器和终端 AI 工具的密钥落在哪儿：系统 keychain、配置文件、环境变量三条路各自被谁能读到，以及配置想进版本库时该怎么把密钥摘出去。以 Zed、goose、Crush、Gemini CLI 官方文档记录的字段为准，不讲价格、额度和限速。

模型列表拉不出来怎么排查：自动拉取型与手写型工具的两条不同路径

接完自定义 API 却选不到模型，多数人第一反应是换密钥。这篇先教你判断手上的工具属于自动拉取型还是手写型，再分别给出排查顺序，并逐字对照 Kilo Code、Continue、Zed 三家官方文档里的字段名。不讲价格、不列模型清单，只讲配置层能自己复核的事。

明明改了配置却没生效：多层配置文件与环境变量的覆盖顺序怎么查

改了模型配置却没变化，多数时候不是改错了值，而是你改的那一层被更高优先级的一层盖住了。本篇按 Gemini CLI、aider、Crush、goose 官方文档记载的加载顺序，讲清多处同名配置文件与环境变量之间的覆盖关系，以及排查时该从哪一头往下查。不涉及价格、额度、限速数字与完整模型清单。

上下文窗口要你手填的那几家：这个数字从哪儿取、填错会怎样

接自定义模型时，Cline、Roo Code、Zed、aider 都有一处要你自己填上下文窗口相关的数值。这篇讲清这个数字的性质（它是客户端的一份声明，不是服务端的开关）、各家这一项逐字叫什么名字、该去哪里取值，以及填大填小分别可能在协议层引出什么后果。不讲价格、额度、限速，也不讲界面长什么样。

编辑器请求被截断或报超上下文：怎么定位是谁把窗口撑爆的

编辑器和终端 Agent 报超上下文、回答说到一半断掉时，先别急着换模型。这篇按「概念拆分—字段核对—请求体拆段」的顺序，讲清上下文窗口和最大输出是两个数、Cline/Roo Code/Zed/aider 各自要你手填哪一项，以及怎么把估算和真实请求对齐。不讲价格、限速数字，也不替任何产品断言它内部拿这些数字做什么。

自定义模型接入后 token 变贵：先分清上下文变多还是缓存没生效

把编辑器换到自定义 OpenAI 兼容端点后用量突然抬头，多数时候不是模型变馋，而是接入这一层的配置换了默认值。本文给出一套可复核的分刀排查顺序：先确认账单归谁算，再看是谁替你多带了上下文，最后判断缓存前缀有没有被打断。不讲价格、不讲额度，只讲你能自己动手查的东西。

编辑器接自定义模型后这笔钱怎么算：和订阅制的成本结构差在哪

把编辑器和终端 Agent 接到自己的模型端点之后，月度支出从固定订阅变成随用量浮动的可变成本。这篇讲清两种结构的差别、配置里哪些字段跟算钱有关、怎么按量估出月成本量级，以及这个做法明确不管的那些事。不含任何价格、免费额度与限速数字。

Cline 接自定义 OpenAI 兼容 API：三个必填项怎么填才不出错

讲清 Cline 里接自定义 OpenAI 兼容端点的完整判断链路：API Provider 为什么选 OpenAI Compatible，Base URL、API Key、Model 三个必填项各自的失败表现，为什么官方 OpenAI 那个地址填进去一定不对，以及 Model Configuration 里那几项手填参数意味着什么。不涉及价格、额度、限速数字和模型清单。

Cline 高级模型参数怎么填：上下文窗口、输出上限与价格填错会怎样

Cline 用 OpenAI Compatible 接第三方模型时，Model Configuration 区还有六项要你自己填。这篇讲清每一项分别是什么、该去哪儿查数、填错会以什么方式暴露出来，并给出一张配置速查表和一份避坑清单。不含任何价格、额度与限速数字，模型清单与最新字段以官方文档为准。

Continue 的 config.yaml 怎么写：models 块字段逐项拆解与取舍

逐项讲清 Continue 配置文件里 models 块的三个必填字段与常用可选字段各自回答什么问题，以及 roles、capabilities 这类开关意味着什么；顺带对比配置文件式接入相比图形界面表单的得失。不写价格、额度、限速与完整模型清单，这些请以官方文档为准。

Continue 的 roles 七种取值：补全、嵌入、重排该配哪个模型

Continue 的 config.yaml 里，models 块的 roles 字段有七种取值，默认只给四种。这篇讲清默认值是什么、七种取值分别对应哪块能力、拆分时哪些字段要一起动，以及拆开之后你放弃了什么。不讲价格、免费额度和完整模型清单，那些请以官方文档为准。

Crush 加自定义 provider：一条命令与两处 crushrc

讲清 Crush 接自定义模型服务商的三件事：配置文件是 bash 风格的 crushrc 而不是 JSON，加 provider 用的是 provider add 命令加 --type、--base-url 参数，以及项目级 .crushrc 与全局 crushrc 两处配置的先后顺序。也说明它明确不管什么、哪些内容本篇不写。

Gemini CLI 配置不生效：四层 settings 的优先级链

Gemini CLI 的 settings.json 有四个位置，再叠上环境变量和命令行参数，一共七级由低到高覆盖。这篇按官方文档记录的顺序把这条链条拆开，讲清每一级在哪、谁盖谁、密钥为什么该用插值而不是写死，并给出「改了没生效」的排查顺序。不写价格、额度、限速和完整模型清单，这些请以官方文档为准。

goose 怎么配模型 provider：向导、环境变量与配置文件

讲清 goose 接模型的三条线索：goose configure 交互向导每一步在问什么、GOOSE_PROVIDER 与 GOOSE_MODEL 这两个环境变量各管什么、以及官方文档说配置持久化在哪个文件。同时给出自建 OpenAI 兼容端点要设的变量、边界与避坑清单。不写价格、免费额度与完整模型清单。

goose 接自建端点：OPENAI_HOST 为什么要拆成两段

goose 接企业内部或自建网关的 OpenAI 兼容端点时，用的不是一整条 Base URL，而是 OPENAI_HOST 加上可选的 OPENAI_BASE_PATH 两项。这篇讲清这个拆分在解决什么问题、配置落在哪里、和其它工具的一整条 URL 有什么区别，以及它明确不管的事。不涉及价格、额度与限速数字。

Kilo Code 加自定义 provider：两种 Base URL 与自定义请求头怎么填

逐项拆解 Kilo Code 新建自定义 provider 的字段：Provider ID、Display name、Provider API、Base URL、API key、Models、Headers，讲清它为什么专门接受完整端点形态的 Base URL、模型列表从哪来、Headers 留给谁用，以及这套配置明确不负责的事。不含价格、额度与模型清单。

Kilo Code 模型列表拉不到：从哪个端点拉、手填要注意什么

Kilo Code 新建 OpenAI 兼容 provider 后模型下拉框是空的，先别急着换服务商。本文讲清模型列表来自哪个端点、Base URL 两种形态怎么选、手填模型 ID 的边界，以及官方文档对 Azure 的那条提醒。不写价格与完整模型清单。

Roo Code 接自定义 OpenAI 兼容 API：配置项与门槛

逐项讲清 Roo Code 用 OpenAI Compatible 接自定义端点时要填的 Base URL、API Key、Model 三个主参数，以及 Max Output Tokens、Context Window、Image Support、Computer Use、输入输出价格这几个可选项各自管什么、填错会怎样；再对照 Continue、Zed、Kilo Code、goose 说清各家在配置面上的差异。不涉及价格、免费额度和限速数字。

Roo Code 只认原生工具调用：选模型前你必须先确认哪几件事

Roo Code 官方文档写明它只支持原生工具调用、没有 XML 回退，这条限制直接决定了哪些模型能接进来。本文讲清什么是原生工具调用、接入前该按什么顺序确认、界面上那几栏各写明了什么，以及它明确不管的部分。不涉及价格、额度与完整模型清单。

团队统一编辑器模型配置：配置进版本库、密钥不进版本库怎么做

讲清团队怎么把 AI 编辑器的模型接入配置沉到代码仓库里、把密钥留在每个人自己机器上。逐条对照 Zed、Gemini CLI、aider、Crush、Continue 等工具在官方文档里给出的配置文件位置、优先级与密钥引用机制，给出可复核的字段对照表、边界与代价、避坑清单。不讲价格、额度与模型选型。

Zed 接 OpenAI 兼容端点：settings.json 该怎么写

把 Zed 的 settings.json 里 language_models → openai_compatible 那段结构逐层拆开讲：api_url 填什么、available_models 为什么必须手写、max_tokens 与 capabilities 各是哪一层、密钥为什么不能写进配置文件。读完你能照着官方示例写出一份可用的 provider 配置，并知道这套做法不管什么。不涉及价格、额度与模型清单。

Zed 为什么不让把密钥写进 settings.json：两条路怎么选

Zed 官方文档在自定义模型接入这一节写了一句很硬的话——不要把 API key 放进 settings.json。这篇拆开讲它给出的两条替代路径（系统 keychain 与环境变量），逐字段解释 settings.json 里该写什么、不该写什么，以及这个设计对团队共享一份配置意味着什么。不讲价格、额度和模型清单，也不替你做密钥治理方案。

自定义 provider 的 ID、显示名、模型名撞在一起：命名这件小事怎么把配置搞乱

接自定义模型时，一个 provider 至少要起三种名字：机器读的唯一标识、界面上给人看的显示名、真正发到服务端的模型标识。本篇对照 Kilo Code、Zed、Crush、Continue 官方文档里各自的字段，讲清哪个名字被谁消费、改一处会牵动什么，以及排查顺序。不讲价格、额度和模型清单。

API 报 401 / 403 怎么排查？鉴权失败的九个原因

大模型 API 鉴权类报错的完整排查路径：401 与 403 的语义区别、密钥格式与请求头写法、地域与产品线不匹配、额度与权限问题，以及一条从 curl 到 SDK 的定位顺序。

API 报 429 怎么办？限流的正确处理姿势与错误做法

429 不是错误而是流控信号。这篇讲清触发 429 的三类原因、响应头里该读什么、客户端限速为什么优于事后重试，以及五种会让情况更糟的错误做法。

模型下线、改名、涨价了怎么办？一套版本迁移的应对预案

模型版本迭代快，下线公告、别名失效、价格调整都会打到生产。这篇给一套可执行的预案：怎么早发现、怎么降低耦合、怎么做灰度切换、以及回归测试该测什么。

大模型 API 的并发怎么规划？从峰值流量倒推容量

并发不是设得越大越快。这篇讲清并发与速率的关系、怎么从峰值流量倒推所需容量、队列该怎么设计、以及并发调大反而变慢的三种典型情况。

大模型 API 降本十招：按性价比排好序，从不换模型开始

十个能实际落地的降本手段，按投入产出排序：砍输入、开缓存、控输出、模型分流、批处理、检索替代全文、结构化输出、并发与重试调优、监控埋点、最后才是换模型。

海外大模型 API 在国内怎么用？可达性与合规的现实考量

讲清企业接入海外模型时要面对的三层问题：网络可达性、服务条款、数据出境合规，以及国内厂商、云厂商官方渠道、纯国产替代三条路径的取舍。

提示缓存是怎么计费的？命中价、写入价、存活时间都要看

讲清 prompt caching 的计费结构：缓存命中价与写入价的区别、存活时间怎么影响成本、什么样的请求才命中，以及怎么判断开缓存到底赚不赚。

提示缓存命中率上不去？八个常见原因逐个排查

开了提示缓存却几乎不省钱，多半是前缀被污染了。这篇列出八个最常见的命中率杀手、对应的排查方法，以及把命中率做上去的请求结构设计。

提示缓存和批处理该用哪个？两种降本手段的适用边界

缓存优化重复前缀、批处理优化时效要求，两者省钱的机制完全不同。这篇讲清各自的适用场景、能不能叠加、以及选错时会付出什么代价。

大模型 API 的最新价格去哪查？别信没标日期的价格表

网上的价格表大多没标来源和核对日期，照着做预算很容易踩空。这篇给一套自己查最新价格的方法：官方定价页怎么找、要看哪几项、怎么建一份可维护的内部价格表。

流式输出中断了怎么办？断点、重发与幂等的三种处理

流式响应中途断开时，已生成的内容要不要保留、能不能续写、重发会不会重复计费。这篇给三种可落地的处理策略和各自的适用边界。

各家的免费额度怎么查、怎么比？五个必须看清的条款

免费额度的数字本身没有可比性，真正决定好不好用的是有效期、速率限制、覆盖模型和数据条款。这篇给一套自查方法和横向比较的口径。

OpenAI 兼容端点是什么？base_url 怎么填、能兼容到什么程度

讲清「OpenAI 兼容」到底兼容了什么、base_url 与路径拼接的常见错法、哪些能力通常不兼容，以及怎么设计一层薄封装让换厂商只改配置。

max_tokens 该设多大？输出长度控制的成本与体验平衡

输出单价通常是输入的几倍，max_tokens 是最直接的成本开关。这篇讲怎么按场景定上限、被截断怎么处理、以及用提示而不是硬截断来控制长度的方法。

大模型 API 的速度怎么测？首 token 延迟与输出速度分开看

讲清衡量推理速度的三个指标（首 token 延迟、输出速率、端到端耗时）、怎么设计一次公平的对比测试、以及影响速度的五个变量——别拿别人的跑分当自己的结论。

RPM 和 TPM 是什么？限流额度怎么估、并发怎么配

讲清大模型 API 的两种限流口径（每分钟请求数与每分钟 token 数）、为什么长请求撞的是 TPM 而不是 RPM、并发数该怎么算，以及被限流后正确的处理姿势。

大模型 API 月成本怎么算？一套能拿去排预算的估算方法

给一套从单次请求推月成本的完整算法：怎么估单次 token、怎么处理多轮累加与重试、并发峰值怎么留余量，以及为什么先估用量再选型才不会返工。附可直接填数的估算器。

用中转或网关调大模型，安全边界在哪？六个必须问清的问题

走第三方中转方便但把数据交了出去。这篇给六个决定能不能用的问题：数据流向、日志留存、密钥归属、可用性责任、计费透明度、合规资质，以及自建网关的取舍。

本地模型怎么接进编辑器？成本、硬件与适用边界

把本地跑的模型接进 AI 编程工具的通用做法：兼容端点怎么起、模型名怎么对、硬件与电费的真实成本，以及哪些任务适合本地、哪些不适合。

编辑器怎么接自定义 API？一套通用配置套路

AI 编程工具接第三方模型的通用方法：三种接入通道、base_url 与模型名怎么填、配置不生效时的排查顺序，以及各类工具的能力边界差异。

Cerebras API 怎么接入？base_url、密钥与 OpenAI 兼容调用

按官方文档核实的 Cerebras 推理 API 接入步骤：控制台在哪拿密钥、base_url 填什么、Bearer 鉴权怎么写、用 OpenAI SDK 直接调用的方式，以及接入前要确认的三件事。

长文本任务的四个成本陷阱：钱花在了你没注意的地方

长文档处理、长会话、长输出场景里最容易踩的四个成本陷阱：分档跳价、历史累加、整份重发、静默截断，以及每个陷阱对应的处理手段与自查方法。

DeepSeek API 的缓存计费怎么算？命中价与未命中价差多少

按官方定价页核实的 DeepSeek 缓存命中价与未命中价，讲清两档模型的价格结构、缓存能省到什么程度、以及官方公告的峰谷定价对成本估算的影响。

同一个任务在不同厂商要花多少钱？一个能自己套的实算模板

用一个具体任务把成本实算走一遍：怎么定义任务、怎么统计输入输出 token、怎么代入各家单价对比，以及为什么只有可核实单价才配进这张表。模板可套任意厂商。

Fireworks AI API 怎么接入？双兼容端点与模型 ID 写法

按官方文档核实的 Fireworks AI 接入步骤：base_url 填什么、Bearer 鉴权怎么写、同时提供 OpenAI 与 Anthropic 兼容端点意味着什么，以及模型 ID 的三段式命名怎么填。

Cerebras / Together / Fireworks 怎么选？三家推理平台的接入层对比

从可核实的接入事实出发对比三家托管推理平台：base_url 形式、鉴权方式、SDK 兼容性、模型 ID 命名、部署形态差异，以及为什么价格不该是第一判据。

模型输出的 JSON 解析失败怎么办？从提示到约束的五层防线

结构化输出不稳定是最常见的生产问题之一。这篇按成本从低到高给五层防线：提示约束、示例引导、schema 强约束、容错解析、校验重试，以及怎么把重试成本压下来。

大模型 API 的免费额度够用吗？按场景算一算就知道

免费额度到底能撑多久，取决于你的场景而不是额度数字本身。这篇给按场景估算的方法、免费额度常见的四类限制、以及从免费过渡到付费的时机判断。

大模型的输入价、输出价、缓存价怎么读？别只看一个数字

拆解大模型 API 价目表的读法：输入输出为什么分开定价、缓存命中价与写入价的区别、按长度分档与峰谷定价的坑、以及为什么两家单价一样实际账单可能差三成。

RAG 检索还是长上下文？先算一笔账再决定

把「文档整份塞进上下文」和「检索出片段再送进去」放在成本、效果、工程复杂度三个维度上对比，给出按场景选择的判断规则，以及两者叠加的常见架构。

上下文长度怎么选？窗口越大越好是个误会

讲清上下文窗口的选型逻辑：为什么大窗口是安全余量而不是使用目标、超长上下文的成本与召回代价、超出限制的三种处理办法，以及裁剪、检索、缓存的取舍顺序。

Together AI API 怎么接入？base_url、密钥与 OpenAI SDK 直连

按官方文档核实的 Together AI 接入步骤：base_url 填什么、Bearer 鉴权怎么写、如何用现有 OpenAI SDK 直接指过去，以及模型 ID 的命名形式与接入前要确认的事。

token 是怎么算的？中英文差在哪，账单为什么总对不上

讲清 token 的计数逻辑、中英文 token 密度差异、system prompt 和多轮历史这些看不见的输入，以及为什么自己估的数和账单总差一截——附一个能直接粘文本估算的计算器。

团队的大模型 API 预算怎么排？从功能清单到季度数字

给一套团队级 API 预算的编制方法：按功能拆用量、区分实验与生产、留重试与增长余量、设置告警阈值与分摊口径，以及预算超支时该先动哪一刀。

Block 开源的多 Agent 通信平台 buzz：用 ACP 把现成编码智能体接进去

拆解 buzz 仓库里的 buzz-acp 这个 crate——它如何把频道事件翻译成 ACP 的 JSON-RPC 请求，把 goose、codex-acp、claude-agent-acp 这类现成客户端挂进消息网；重点读那份编进二进制的基础提示词，以及默认权限模式带来的暴露面。不讲怎么部署中继，也不评价它比别的框架好在哪。

把 Agent 接进 buzz：Block 开源多 Agent 通信平台的三层结构

buzz 是 Block 开源的多 Agent 通信平台，建在 Nostr 协议之上。本文按仓库代码拆开一个 Agent 接入这张网络需要的三层——模型接入、进程配置、身份与发言通道，讲清每层管什么、代价在哪、上手时最容易踩哪几个坑。不涉及部署运维、不评测模型效果、不讨论商业化。

Block 开源多 Agent 通信平台 buzz 的工具来源：内置工具与 MCP 如何合并

拆开 Block 开源的多 Agent 通信平台 buzz，看它的 Agent 到底能调什么工具：内置工具与 MCP 服务器两条来源在哪一行合流、限定名怎么生成、提示里那层 hints 与技能清单起什么作用。读完你能自己判断某个工具为什么没出现在模型面前。不讲 MCP 协议本身怎么设计，也不讲怎么写工具描述。

Block 开源多 Agent 通信平台 buzz：从拉仓库到跑通中继

拆解 Block 开源的多 Agent 通信平台 buzz 的安装路径：它是 Rust workspace 外挂 Tauri 桌面端与 Flutter 移动端的多语言仓库，工具链由 hermit 垫片接管。读完你能知道 setup、build、dev 三步分别做了什么、要起哪些服务、哪些坑是这个仓库独有的。不解决功能选型与生产部署调优。

buzz 命令行怎么用：Block 开源的多 Agent 通信平台上手

buzz 是 Block 开源的多 Agent 通信平台，建在 Nostr 之上。这篇按「你想干什么」拆开它的命令行：22 个顶层子命令怎么分组、一条建频道命令背后发生了什么、哪些边界它明确不管。读完你能自己判断哪些活该交给 CLI。不讲桌面端使用，也不讲中继部署运维。

拆解 Block 开源 buzz 多 Agent 平台的 MCP 服务器

buzz 是 Block 开源的多 Agent 通信平台，它自带一个给写代码的 Agent 用的 MCP 服务器。本文逐个文件拆开它的工具集、进程模型、截断与超时策略，给你一份能照着抄的自建 MCP 服务器范本。不解决 Nostr 协议本身的教学，也不评价它比别的实现好在哪。

Block 开源 buzz：多 Agent 平台的 Git 仓库托管链路

buzz 是 Block 开源的多 Agent 通信平台，建在 Nostr 之上。这篇拆它的 Git 托管链路：凭据助手怎么用签名事件换掉密码、签名程序怎么给提交盖身份章、仓库本体怎么靠 manifest 指针加条件写落在对象存储上。读完你能判断这套设计的代价与不适用场景，不解决部署选型。

Block 开源多 Agent 通信平台 buzz 的四层排障顺序

buzz 是 Block 开源的多 Agent 通信平台，建在 Nostr 协议之上。这篇按窗口渲染、客户端到中继、中继到 Agent、Agent 回复回显四层拆开排查顺序，给出每层该看哪个文件、哪条命令、哪个指标，以及界面提示为什么可能本身就是假的。不覆盖模型效果调优与生产容量规划。

Block 开源多 Agent 平台 buzz：一张图上传的四道关

拆解 Block 开源的多 Agent 通信平台 buzz 的媒体链路，把上传编排、内容校验、缩略图生成、存储桶索引四段代码摆到一起看，讲清每段的输入输出、失败时留下什么残渣、以及边界外它明确不接管的事。读完你能照着这套分法审自己项目的附件链路，但它不解决内容审核判定与跨端播放兼容。

Block 开源多 Agent 平台 buzz：自建中继要想清的几件事

从 buzz 仓库的中继代码与单机部署包出发，讲清自建一个 buzz 中继要先想明白的三块：配置从哪来、准入怎么开关、数据落在哪又由谁清理。给出组件地图、边界说明和避坑清单，不涉及性能调优、集群容量规划与商业化选型。

buzz 是什么：Block 开源的多 Agent 通信平台全景图

buzz 是 Block 开源的多 Agent 通信平台，建在 Nostr 协议之上，人和 Agent 用同一套密钥、同一条事件日志协作。本文拆它的仓库结构、事件管线、Agent 接入方式和自建中继的暴露面，也讲清它明确不做的事：不做端到端加密、不做点对点分发、限流与审批门都还没打通。不含安装教程，不含性能实测。

Block 开源多 Agent 通信平台 buzz 的推送网关：授权、令牌与设备证明

拆解 Block 开源的多 Agent 通信平台 buzz 里那个单独部署的 APNs 推送网关，讲清设备证明、投递授权、令牌托管这三层各自挡住什么，以及为什么它不能和中继跑在一个镜像里。读完你能照着这套结构去审自己的凭据中间人。不解决消息匹配、内容推送与安卓通道。

Block 开源 buzz：多 Agent 通信平台的移动端为何重写协议

Block 开源的多 Agent 通信平台 buzz 建在 Nostr 之上，移动端用 Flutter 写，同一套协议被第三次实现。本文拆开 mobile 目录，讲清协议先行省了什么、要重复付出什么，并给出接手时的避坑清单。不覆盖桌面端 UI 与部署运维。

让 Agent 跑在集群里：Block 开源多 Agent 通信平台 buzz 的远程调度模型

拆开 Block 开源的多 Agent 通信平台 buzz 里那个专门的 Kubernetes 后端，讲清远程 Agent 这条线怎么起容器、怎么调和状态、怎么回收残留，以及它为什么故意不给自己留管理通道。读完你能看懂它的部署状态机、Pod 形状与垃圾回收口径，并知道该怎么排查启动卡住。它不讲 Agent 对话逻辑，也不讲集群本身的安全加固。

Block 开源多 Agent 平台 buzz：语音在中继与本地如何分工

拆解 Block 开源的多 Agent 通信平台 buzz 的实时语音链路：中继侧的音频房间只做字节扇出与准入仲裁，语音识别与语音合成全部压在客户端本地模型上。你会拿到这条线的完整分工图、可核对的常量与边界，以及一份上手避坑清单。不解决音视频编解码调优与自建中继的运维方案。

Block 开源多 Agent 通信平台 buzz 桌面端与中继分工拆解

拆 Block 开源多 Agent 通信平台 buzz 的桌面客户端：Vite 前端套 Tauri 壳，src/features 切成 29 个模块。讲清中继只管什么、桌面端补了什么，为什么桌面端文件数远多于内核 crate，以及三个自定义检查脚本的踩坑。不讲中继部署，不做评测。

OfficeCLI 开源项目上手：三种装法怎么选，第一次跑前先懂这件事

OfficeCLI 是给 AI Agent 用的开源 Office 读写命令行工具，单文件二进制，也能走 npm 装。这篇读一遍它的仓库结构，讲清一键脚本、包管理器、手动下载三种装法各自的适用面与代价，以及第一次运行前必须弄明白的落盘时机。不讲元素属性怎么设，也不替它背书。

OfficeCLI 开源项目常驻模式：进程不退，文档改动何时落盘

拆解开源项目 OfficeCLI 的常驻模式：为什么它把文档留在内存里不急着写回磁盘，两条命名管道和两个看门狗各管什么，四种落盘策略分别在什么时刻把改动写进你的 .docx/.xlsx/.pptx。读完你能判断什么时候该开常驻、交付前该按哪个按钮。不解决文档格式本身的读写细节。

开源项目 OfficeCLI 的查询与转储：Agent 先读懂再动手

拆解开源项目 OfficeCLI 读侧的 get、query、dump 三个命令，讲清它怎么把 Word/Excel/PowerPoint 文档变成可寻址路径与可回放脚本，以及读完整性契约怎么设计。读完你能判断 Agent 改文档前该读什么、怎么核对读全了。不讲写侧细节。

开源项目 OfficeCLI 排障：用它自带的体检命令定位文档问题

开源项目 OfficeCLI 自带两条诊断通道：validate 做 OOXML schema 体检，view issues 按三个桶加十四个子类型给文档问题分类。这篇讲清报错该按什么顺序查、每层能查出什么、哪些它明确不管。不讲排版审美，也不讲文档生成技巧。

开源项目 OfficeCLI 的 11 个技能包：里面写了什么，和命令行工具怎么分工

拆开 OfficeCLI 这个开源项目自带的 11 个技能目录，逐层看 SKILL.md 里到底写了哪几类内容：交付标准、领域约定、带坐标的版式配方、可直接跑的 QA 门。同时讲清技能包与 CLI 工具、与 schema 三者的边界。不讲怎么写 Word 排版，也不替你判断这套方案是否适合你的业务。

把开源项目 OfficeCLI 接进你的 Agent：内置 MCP 服务器与一键注册路径

OfficeCLI 是一个 Apache-2.0 的开源命令行套件，单个二进制就能读写 docx/xlsx/pptx。这篇拆它自带的 MCP 服务器：为什么只暴露一个工具一个参数，注册命令把哪条路径写进了哪个客户端配置，工具描述里塞进了什么，以及落盘时机、远程抓取、后台升级这些会咬人的边界。不讲文档格式细节，也不替你做选型。

开源项目 OfficeCLI 的命令面全景：一套动词打通三种文档

拆解开源项目 OfficeCLI 的命令面：add/set/get/query/remove 这几个动词如何在三种文档格式里保持同一语义。读完能拿到命令与仓库位置对照表、写盘时机与失败残留的判断依据、一份避坑清单。不讲 OOXML 底层格式，也不教你写 C#。

读开源项目 OfficeCLI 的源码：批量执行为什么快，以及失败时整批回滚这道坎

拆开源项目 OfficeCLI 的 batch 命令：一次调用跑几十条文档修改，省掉的是反复开包和反复序列化的开销；但它的失败语义和逐条调用完全不同，默认是任何一项失败就整批回滚。本文讲清批量项的结构、原子回滚在非常驻与常驻两条通路上各自怎么实现、以及边界在哪。不涉及 Office 文档格式本身的教学。

开源项目 OfficeCLI 的两套 SDK：什么时候别直接调命令

OfficeCLI 是一个给 AI Agent 用的开源 Office 文档读写套件，除命令行外还带 Node 和 Python 两套 SDK。本文按仓库源码梳理这两套 SDK 各自包了什么、常驻进程加命名管道这条快路径怎么走、批量写入失败会回滚成什么样，以及判断该用 SDK 还是逐条调命令的那条线在哪。不讲 Office 文档格式本身，也不替你判断要不要引入它。

OfficeCLI 是什么：给 AI Agent 用的开源文档读写套件

OfficeCLI 是一个 Apache-2.0 开源项目，把 Word、Excel、PowerPoint 的读写包成单个二进制，让 AI Agent 不装 Office 也能改文档。本篇给出仓库全景：目录怎么分、三层地址系统怎么用、渲染回路和常驻进程如何工作、它明确不管什么。不讲某一类文档的具体写法，也不做工具排名。

开源项目 OfficeCLI 的 watch 预览：让 Agent 改文档时你在浏览器里同步看到

拆解开源项目 OfficeCLI 的 watch 实时预览链路：改动命令怎么把渲染好的 HTML 经命名管道推给中继服务，中继服务怎么用块级与行级 diff 推给浏览器，以及这条链路的还原度边界在哪。读完你能判断它适合放进哪种 Agent 工作流，也知道它明确不管哪些事。不涉及价格与选型排序。

OfficeCLI 开源项目的选择器语法：三份解析实现与最常见的选错点

拆解开源项目 OfficeCLI 用来定位文档元素的那套选择器：路径式与选择器式两种写法、Word/Excel/PowerPoint 三份互相独立的解析实现、共用的顶层逗号扫描与尾部位置索引。读完你能判断一条选择器会命中什么、为什么明明写对了却选到别的元素，以及哪些写法在写操作上会被直接拒绝。不解决渲染、排版和模型侧提示词问题。

Pascal Editor 上手记：浏览器里的开源 3D 建筑编辑器，装起来要过多包仓库和显卡两道关

Pascal Editor 是一个跑在浏览器里的开源 3D 建筑编辑器，同时带一套让 AI Agent 直接建模的 MCP 服务器。这篇按仓库里的真实文件讲清它的包结构、为什么很多命令必须从根目录跑、渲染层如何在 WebGPU 与 WebGL2 之间降级、MCP 服务器把数据写在哪、以及它明确不管哪些事。不讲建模技巧，也不讲怎么设计房子。

Pascal Editor 3D 建筑编辑器排障：显卡回退与报错分类

Pascal Editor 是跑在浏览器里的开源 3D 建筑编辑器，自带一套让 AI Agent 直接建模的 MCP 服务器。这篇按浏览器、MCP 进程、场景语义三层拆排查顺序，讲清显卡起不来时它退成什么样、工具报错分几类怎么读，以及仓库里那份净空检查错误日志怎么当排查教材用。不讲怎么用它做设计，也不评测建模效果。

Pascal Editor 是什么：浏览器里的开源 3D 建筑编辑器，与它自带的建模 MCP 服务器

Pascal Editor 是一个跑在浏览器里的开源 3D 建筑编辑器，仓库里同时放着一个可以让 AI Agent 直接建模造房子的 MCP 服务器。本文从仓库结构、场景数据模型、MCP 工具面、边界与代价四个角度给出全景地图，并给出上手避坑清单。不讲建筑设计方法，也不评测它和其它建模软件谁更强。

Pascal Editor 开源 3D 建筑编辑器：MCP 服务器暴露出去前的风险面梳理

Pascal Editor 是一个跑在浏览器里的开源 3D 建筑编辑器，自带一套让 AI Agent 直接建模的 MCP 服务器。这篇按代码梳理它的三层防护：出网请求的 SSRF 拦截、HTTP 传输绑非本机时的强制令牌、编辑器场景接口的独立校验，并写清每层管什么、不管什么。不讲建模技巧，也不替你做部署决策。

开源浏览器端 3D 建筑编辑器 Pascal Editor：Agent 建的模型存在哪，本地 SQLite 与版本校验约定

拆解开源 3D 建筑编辑器 Pascal Editor 的 MCP 场景生命周期工具组：模型落在本机哪个路径、解析优先级、每次保存版本号怎么涨、expectedVersion 冲突怎么触发，以及编辑器与 MCP 进程共用一个库时的约定。不覆盖建模语义工具与渲染实现。

浏览器里的 3D 建筑编辑器 Pascal Editor：Agent 建完模型后的两条导出线

逐行拆解开源 3D 建筑编辑器 Pascal Editor 的两条导出路径：无头 MCP 侧的场景 JSON 序列化，以及浏览器侧基于 Three.js 渲染器的 GLB 烘焙。讲清每条线吐出什么、明确丢掉了哪些信息、分别该喂给谁，并给出跑这套服务器时数据落盘与端口暴露的代价。读完你能判断该让 Agent 拿参数化 JSON 还是拿三角形 GLB，也知道要 GLB 时该怎么绕。不解决建筑制图规范与 IFC（建筑信息模型的行业交换标准）交付合规问题。

开源 3D 建筑编辑器 Pascal Editor 的 MCP 工具全景：从建楼层到放家具

拆解开源 3D 建筑编辑器 Pascal Editor 自带的 MCP 服务器：它把建楼层、砌墙、开洞、放家具切成一组入参出参被 schema 定死的细粒度工具，同时保留一个通用批量补丁工具作为兜底。读完你能拿到这套切分逻辑的判断依据、可复用的校验分层做法，以及本地数据库与端口暴露的真实代价。不讲三维渲染实现，也不教你用它做建筑设计。

开源 3D 建筑编辑器 Pascal Editor 的 MCP 服务器：无头运行与两种传输方式怎么选

Pascal Editor 是一个跑在浏览器里的开源 3D 建筑编辑器，同时提供一台可无头运行的 MCP 服务器，让 Agent 直接建模。本文讲清它凭什么不需要浏览器和显卡、stdio 与 Streamable HTTP 各自的适用场景、绑定非本机地址时被强制要求的鉴权条件，以及场景数据落在哪。不讲建筑设计方法，也不教你怎么用它的图形界面画图。

开源三维建筑编辑器 Pascal Editor：让智能体自查碰撞与门净空

Pascal Editor 是一个跑在浏览器里的开源三维建筑编辑器，它在 MCP 侧配了碰撞检查、门净空、布局净空与场景校验四层自校验。本文顺着仓库源码拆开这四层各自判什么、判据的默认数值从哪来、失败原因怎么回传给智能体，也写清它的边界：只做平面包围盒近似，不碰结构受力与规范合规。

浏览器里的开源 3D 建筑编辑器 Pascal Editor：MCP 模板层怎样把一句需求变成户型

Pascal Editor 是一个跑在浏览器里的开源 3D 建筑编辑器，它的 MCP 侧准备了三个可直接实例化的场景模板，外加一条把自然语言需求转成工具调用的提示词路径。这篇拆开 create_house_from_brief 与 create_from_template 的实际逻辑，讲清模板层替你挡掉了什么、又把哪些落位问题与本地数据风险原样留给你，不讲建模技巧，也不做商业评价。

Pascal Editor 三维建筑编辑器的 Agent 实时同步链路

Pascal Editor 是跑在浏览器里的开源 3D 建筑编辑器，自带的 MCP 服务器让 Agent 直接建模，改动能实时出现在你的页面上。本文拆开这条链路：写入端做了什么、本地 SQLite 事件表长什么样、SSE 路由怎么推、浏览器怎么防回环，以及它不解决的协同编辑问题。

开源 3D 建筑编辑器 Pascal Editor：照片转场景的边界

Pascal Editor 是跑在浏览器里的开源 3D 建筑编辑器，其 MCP 服务器带一组视觉工具，把户型图和房间照片解析成结构化 JSON 再落成三维场景。本文按仓库代码拆这条链路每步做什么、三种失败态在哪抛出、它明确不管什么。不提供识图精度评测，也不替代人工复核。

开源交易 Agent Vibe-Trading 的四层安全边界拆解

按代码逐层拆开 Vibe-Trading 的安全设计：工作区路径校验、允许根目录、出网地址过滤、外部内容注入扫描各管到哪一段，哪几个文件其实只是兼容转发层。你会拿到一张模块与仓库路径对照表、一份避坑清单，以及它明确不管的部分。不含任何投资建议与策略结论。

Vibe-Trading 开源交易 Agent：三个入口与第一次配置

HKUDS 开源的 Vibe-Trading 装完之后给你三个可执行入口——交互命令行、FastAPI 服务、MCP 服务端。这篇按仓库代码梳理三者各自的信任边界，拆开首次配置向导的五步到底往磁盘上写了什么，列清哪些凭据可以先不给，以及这套设计明确不管的那些事。不讲怎么投资，只讲工程实现。

开源项目 Vibe-Trading 工具层：72 个文件与上下文预算

拆开 HKUDS 的开源交易 Agent 项目 Vibe-Trading 的工具目录，讲清 72 个文件靠哪几条正交规则分组、哪些是任何 Agent 都要有的通用底座、哪些是金融领域专用，以及它用什么手段让工具结果不把模型上下文冲垮。只讲工程实现，不涉及任何投资判断，也不评价策略好坏。

Vibe-Trading 开源项目跑不起来：自检表、限额与数据源降级

Vibe-Trading 是 HKUDS 开源的个人交易 Agent。本文按仓库代码梳理它跑不起来时的排查顺序：先读启动前自检表分清致命项与降级项，再看工具结果限额造成的假性故障，最后看 A 股数据源从主源到备源的兜底路径。只讲工程实现，不讲策略好坏，也不涉及任何投资判断。

Vibe-Trading 开源仓库的回测层：多引擎共用一个 runner

拆解 HKUDS 开源项目 Vibe-Trading 的回测层工程结构：一个 runner 怎么把配置校验、策略源码扫描、市场引擎路由串起来，约束层、指标层、验证层又怎么各自独立成模块。读完你能照着这套分层去接自己的市场规则；不解决策略好坏、参数怎么调、更不涉及任何投资判断。

开源项目 Vibe-Trading 的技能体系：88 个目录如何按需加载

拆解 HKUDS 开源交易 Agent Vibe-Trading 的技能组织法：88 个技能各一份 SKILL.md，系统提示词只放一行描述，全文靠 load_skill 按名取并分页。读完能拿到完整数据通路、分页信封的设计动机与避坑清单。只讲工程实现，不讲投资。

开源项目 Vibe-Trading 不装界面也能用：MCP 接入方式与边界

Vibe-Trading 是 HKUDS 放出的开源个人交易 Agent，它自带一个 MCP 服务端入口，不用装它的前端界面，就能把整套金融研究工具挂到你现有的 Agent 上。这篇讲清三种传输方式怎么选、工具面被砍掉了什么、凭据与安全护栏在哪一层，以及哪些事它明确不管。不讲怎么投资，也不给任何策略结论。

Vibe-Trading 开源项目怎么接大模型：能力表与登录态通道

拆开 HKUDS 开源项目 Vibe-Trading 的模型接入层：为什么把供应商差异拆成目录 JSON 与能力表两层，走 ChatGPT 登录态的那条通道为什么必须另起炉灶。读完你能照抄这套结构，也知道它明确不管什么。不讲价格额度与投资判断。

Vibe-Trading 的三层配置：结构 schema、环境变量 schema、路径与限额各管什么

拆开开源交易 Agent 项目 Vibe-Trading 的 agent/src/config 目录，讲清它为什么把配置切成结构校验、环境变量表、路径与限额三层，每层挡住什么错误、在哪个文件里、排查时该先看哪一个。只讲配置工程实现，不涉及任何投资判断，也不替你判断实盘合规。

Vibe-Trading 是什么：HKUDS 这个开源交易 Agent 项目的工程全景与边界

从仓库结构出发拆解 HKUDS 开源项目 Vibe-Trading：它把金融研究工作流切成技能、工具、多智能体编制三层可加载单元，挂在一个通用 Agent 循环上。读完你能画出它的全景地图、知道每层代码落在哪个目录、以及它明确不管的那些事。不提供任何投资建议，也不评价策略好坏。

Vibe-Trading 开源项目的数据源层拆解：一个注册表、一条回退链和一份路由技能文档

拆开 HKUDS 开源的 Vibe-Trading 个人交易 Agent，看它怎么把二十多个行情数据源收进一个注册表、按市场排出回退链，再用一份 data-routing 技能文档告诉模型该走哪条线。读完你能拿到一套可以搬到自己 Agent 上的多数据源路由与降级写法。不讲投资方法，不评价任何策略。

开源项目 Vibe-Trading 的 30 份多智能体编制怎么调

拆开 Vibe-Trading 仓库里 swarm 这一层：30 份 YAML 编制文件把角色、依赖、工具白名单写成静态 DAG，一句话经关键词路由变成一支队伍。读完你能看懂编制文件的三段结构、分层调度与上游上下文的传递方式，知道哪些坑是配置写法造成的。不讲投资方法，不评价任何输出结果的好坏。

开源项目 Vibe-Trading 渠道层：接进聊天软件的代价与新问题

拆解开源交易 Agent 项目 Vibe-Trading 的 channels 目录：靠扫包做渠道注册、两条队列做消息总线、权限与配对收在基类。读完知道接一个聊天渠道要写什么，以及 Agent 进群后的会话边界与凭据问题。不讲投资方法，只讲工程实现。

Vibe-Trading 开源仓库的 Web 层：一条时间线让长任务可见

Vibe-Trading 的 Web 那一侧被拆成了两半：FastAPI 端按会话、运行、设置等分组注册路由，再用一条 SSE 事件流把每一步推给浏览器；前端用一行可折叠的活动条把思考、工具调用与产出串起来。本文按仓库代码梳理这套让长任务可见的做法，并给出边界与避坑清单。不讲交易策略，不给任何投资判断。

开源交易 Agent 项目 Vibe-Trading 里怎么自己写一个技能：四个工具加一份范本

拆开源项目 Vibe-Trading 的技能机制：技能文档怎么被加载进上下文、写技能的 save_skill / patch_skill / delete_skill / skill_file 四个工具各管什么、一份叫 research-discipline 的技能文档为什么算能用的范本。给出仓库真实路径、边界代价与避坑清单。不讲交易策略，不给任何投资建议。

开源 Vibe-Trading 的 Alpha Zoo 因子库怎么调用

拆开开源项目 Vibe-Trading 的 Alpha Zoo：几百个因子文件如何靠一个注册表暴露成一条命令，AST 扫元数据的代价是什么，工具返回的每个字段该怎么读，以及最容易踩的 zoo 名与枚举值。只讲工程实现，不讲因子有效性。

开源终端 Agent 项目 opencode 的多 agent 怎么配

从 opencode 仓库源码出发，讲清一个 agent 由什么构成、权限规则表如何决定它能用哪些工具、子 agent 的模型从哪继承、主 agent 派活时子会话权限怎么推导，以及什么活值得单开一个 agent。不含安装教程，也不做产品排名。

opencode 安装上手：开源终端编码 Agent 的装法与避坑

opencode 是一个跑在终端里的开源 AI 编码 Agent。这篇按仓库文档梳理它的几种安装方式各自要付出什么代价、第一次启动它要你依次做完的鉴权与初始化动作，以及新手最容易卡住的模型引用、权限默认值、日志定位三处。不讲价格额度，不替你选模型。

终端编码 Agent opencode 命令行：交互模式与脚本化执行

拆开开源项目 opencode 的命令行入口，讲清楚不带参数进 TUI 和 opencode run 一次性执行到底差在哪：输出走 stdout 还是 stderr、权限请求在无人值守时会被怎么处理、会话怎么接续、什么时候该配 serve 常驻。不讲安装步骤，也不评价它和别的工具谁更强。

把开源编码 Agent opencode 挂到代码托管平台：权限与边界

opencode 是跑在终端里的开源编码 Agent。本文按仓库代码梳理它的 GitHub Action 与 GitLab 两条集成线：令牌从哪来、为什么要校验发起人权限、workflow 权限位怎么写、GitLab 侧要你自己补什么，以及它明确不管的事。不讲价格与额度。

opencode 读哪些规则文件：终端编码 Agent 的规则加载顺序

opencode 是跑在终端里的开源编码 Agent。本文按仓库代码梳理它从哪些位置读规则文件、AGENTS.md 与 CLAUDE.md 谁盖谁、子目录规则何时才注入，以及规则写太长为什么会稀释效果。读完能拿到一份可核对的加载顺序和一份避坑清单，不讲安装与模型选型。

开源终端编码 Agent opencode 跑不动：按模型、认证、Windows、代理证书的顺序排查

opencode 是跑在终端里的开源编码 Agent，出问题时报错往往指不到根因。这篇按连不上模型、认证失效、Windows 路径与 WSL、代理与证书四道关的固定顺序讲排查，配上仓库里日志与存储的真实落盘位置。读完你能拿到一份可照抄的自检顺序；它不解决模型答得好不好，也不替你调优提示词。

opencode 的诊断与格式化两条线：语言服务器怎么报错、格式化器何时跑

拆开开源终端编码 Agent opencode 的写文件后置流程：格式化命令先跑完、语言服务器再重新读盘出诊断，两条线为什么是串行而不是并行。你会拿到配置键对照、只报 error 且每文件二十条的回灌规则、多格式化器抢同一扩展名的排查方法。不涉及模型选型与提示词调优。

开源终端 Agent opencode 接 MCP：两类接法与认证避坑

从 opencode 仓库的 mcp 目录出发，讲清本地进程式与远程式两类接法的分界、OAuth 认证从 401 到令牌落盘的链路、工具名被怎样改写，以及接多个 server 后最先出问题的地方。读完能预判一份配置怎么跑、出错该看哪个文件；不解决选哪个服务、怎么写 server。

opencode 怎么接模型：终端编码 Agent 的供应商层与认证机制

拆解开源终端编码 Agent opencode 的模型接入机制：供应商这一层由哪些文件装配、认证方式分成哪几类、凭证落在哪里、换模型到底该改哪个键，以及接国产模型与本地模型分别要注意什么。读完你能自己定位配置不生效的原因。本篇只讲机制，不涉及各家价格、额度与限流阈值。

开源终端 Agent opencode 的配置从哪读，改错一处为何全变

把 opencode 这个跑在终端里的开源编码 Agent 的配置装配链路拆开：全局与项目两层文件怎么发现、八级来源按什么顺序合并、{env:} 与 {file:} 两种替换发生在解析之前意味着什么、schema 校验为什么只拦顶层键、以及全局配置坏掉时为何不报错只是静默失效。不讲模型选型，不讲价格。

终端 AI 编程 Agent opencode 的权限闸门怎么设

拆解开源终端编码 Agent opencode 的 permission 配置：三种动作、两级通配、最后匹配者胜的判定顺序、默认放行与默认询问的清单、always 记忆的作用范围，以及审批放太松和放太紧各自会付出什么代价。不覆盖模型选型、计费和它的其它子系统。

opencode 是什么：终端里的开源 AI 编程 Agent 全景地图

拆解开源项目 opencode 的整体结构：它是一个 CLI 里同时跑客户端和服务端的编码 Agent，把写代码拆成了会话运行时、工具层、权限层、上下文层几块。读完你能判断它适不适合你的工作方式，也知道该先动哪个配置。本文不教配置调参，也不比较各家工具优劣。

终端编码 Agent opencode 的 skills 用法与分工

拆开开源终端编码 Agent 项目 opencode 的技能机制：SKILL.md 放在哪六类位置会被扫到、命名与 frontmatter 的文档规则和实际校验差在哪、skill 工具加载时到底往上下文里塞了什么，以及技能与自定义命令、子 agent 的分工线。读完你能判断哪些内容值得写成技能、哪些不值得。不讲价格与额度。

开源终端 Agent opencode 界面用熟：键位、主题与区块含义

拆解开源终端编码 Agent opencode 的 TUI：底栏与侧栏各块在报告什么、leader 键与 which-key 面板怎么让你不用背键位、主题切换与自己写一份要动哪些文件。读完能把陌生机器上的界面快速调顺手，并认清哪些操作会真改你的代码。不做产品优劣对比。

开源终端 Agent opencode 的两条模型接入路线怎么选

opencode 自带一条由项目方维护的模型接入线（OpenCode Zen），和你自己在配置里填 API key 是并行的两条路。这篇按仓库文档与源码梳理两者各自省掉了什么、又把什么交给了别人：凭据落盘位置、模型目录从哪来、没连凭据时清单会被裁剪、小模型与数据边界，以及一份上手避坑清单。不含价格与额度，也不替你下选型结论。

给 opencode 写自定义命令：把重复指令固化成一条斜杠命令

opencode 是跑在终端里的开源 AI 编码 Agent。本文顺着它的命令加载、参数替换、shell 抓取与子代理路由读源码，讲清参数怎么传、占位符替换成什么、哪些重复动作值得固化成命令、哪些做了反而添乱，以及命令自动跑 shell 带来的风险。不覆盖插件与 MCP 开发。

OpenWork 开源桌面应用上手：三条安装路线与第一次配置要交出什么

OpenWork 是把技能、MCP 连接与外部服务打包成可共享能力的开源桌面应用。这篇拆开它的三条安装路线（下载桌面应用、命令行引导包、让 Agent 代装），逐条说清引导包做了哪几件事、首次配置要你交出哪些凭据与授权、哪些文件会落在你机器上，以及它明确不管的事。不解决模型效果调优与生产运维。

开源桌面应用 OpenWork：工作流、设置共享、团队模板各自漏在哪

把调好的一套设置交给同事，在开源桌面应用 OpenWork 里不是一个动作：会话工作流管本机组织方式，组织市场管技能分发，团队模板管新人起点。本文拆开讲每块怎么做、明确不管什么，并写清授权范围、凭据集中保管与许可证分层的代价。不提供法律意见，不做评测。

OpenWork 开源桌面应用连不上：先走网络自查线，再用诊断提示词

OpenWork 这个开源桌面应用连不上服务器时，仓库里备了两条互不重叠的排查线：一条是网络与证书自查（PowerShell 体检脚本、四个信任面、Den 出站诊断），一条是让 Agent 自己跑的分阶段诊断提示词。本文讲清两条线各自解决什么、按什么顺序走最省时间，以及它明确不管的那些事。不提供法律意见，也不涉及价格与套餐。

OpenWork 开源桌面应用：技能、插件与 MCP 各在哪一层起作用

拆开 OpenWork 这个开源桌面应用的仓库，把技能、插件、MCP 三者的作用层讲清楚：技能是磁盘上的 SKILL.md 约定，插件是安装与分发单元，MCP 是够到外部系统的连接方式。给出选层判断、边界代价与避坑清单。不提供法律意见，也不评测产品优劣。

OpenWork 开源桌面应用实操：把一次聊天变成可发布复用的技能

拆开源桌面应用 OpenWork 的技能链路：在聊天里说一句话生成技能、再由组织管理员发布给同事复制。读完你会知道技能文件落在磁盘哪里、扫描与去重规则怎么静默吞掉一个技能、发布为什么被挪到组织控制面，以及这条链路新增的维护负担。不讲模型效果调优，也不替你判断商用许可。

OpenWork 开源桌面应用的跨会话记忆：一层你能读能改的明文记忆

拆解开源桌面应用 OpenWork 的两条跨会话记忆通路：基于会话历史的现场查找，和服务端明文存储、词面检索、可列可删的记忆库。讲清数据表、检索方式、桌面面板与提示词约定，也讲清它不做的事——不做语义召回、不做自动回忆、不做落库加密。读完知道怎么用、会踩哪些坑，但不替你做合规判断。

给开源桌面应用 OpenWork 接外部服务：MCP 服务器、办公套件与搜索的授权边界

拆解开源桌面应用 OpenWork 的三条外部服务接入路径——组织托管的 Connect、自建 MCP 服务器、内置搜索开关，逐条说清各自要你授权到什么程度、凭据存在哪、组织侧能看到什么，并讲透个人连接与团队共享连接在账号归属上的根本差别。不含安装教程，也不做法律与合规判断。

开源桌面应用 OpenWork 让 Agent 开浏览器干活的两条路：内置面板与 macOS 屏幕操作

拆解开源桌面应用 OpenWork 的浏览器控制链路：内置浏览器面板怎么把标签页变成一个可交给 Agent 的 CDP 句柄，macOS 屏幕操作那条支线又卡在哪些系统权限上。读完你能判断它适合接哪类任务、代价在哪。不解决站点风控与合规判断。

开源项目 OpenWork 不装桌面应用也能用：两个 MCP 工具接进 Agent

OpenWork 是开源桌面应用，但它对外只暴露 search_capabilities 和 execute_capability 两个 MCP 工具。本文按仓库代码讲清这个门面怎么设计、能力从哪几路汇进来、接到 Claude Code / Codex / OpenCode 要改什么，以及它明确不管的事。不讲协议基础，不做选型排名。

OpenWork 开源桌面应用怎么接模型：三条路径的机制与代价

拆解开源桌面应用 OpenWork 接入模型的三条路径——手工粘贴 API key、在工作区配置里声明 OpenAI 兼容供应商、复用已有订阅的登录态，讲清每条路把凭据写到哪、由谁控制、放弃了什么。读完你能判断自己该走哪条，也能看清组织控制面会介入到什么程度。不含价格、额度与选型排名。

OpenWork 是什么：把技能与 MCP 打包成能力的开源桌面应用

OpenWork 是一个开源桌面应用，把技能、MCP 连接与已授权的外部服务收成可检索、可执行、可分发的「能力」，再通过一个远程 MCP 端点送进你已有的 Agent。这篇给出全景地图：它解决的搬配置问题、能力是怎么收口的、仓库分层许可证怎么读，以及它明确不管什么。不含安装教学与法律意见。

开源桌面应用 OpenWork：什么在烧 token，账单怎么长出来

拆解开源桌面应用 OpenWork 的两份官方文档：一份专讲哪些动作会触发模型请求、哪些不会，一份讲组织侧托管模型凭据后桌面端怎么导入。读完你能判断账单从哪一步开始长，以及团队统一模型入口时把哪些暴露面一起交了出去。不涉及价格、额度与套餐规则，也不给法律意见。

读懂 browser-use 用量统计层：算了什么、漏了什么、哪步最贵

拆开 browser-use 仓库里的 tokens 模块，讲清它怎么拦住每次模型调用、怎么把模型名折算成单价、以及成本为什么会莫名变成零。同时给出定位「哪一步最贵」的三种可行做法。它不解决账单对齐，也不提供步骤级归因，这两件事得靠外部手段补。

browser-use 命令行怎么用：交互入口、init 与配置从哪读

从 browser-use 仓库的 cli.py、init_cmd.py、config.py 出发，讲清这个开源项目的命令行到底做了什么：无参数进交互提示还是读 stdin、init 的模板从哪来、配置有几条互不相通的读取路径。读完你能判断什么活直接敲 CLI、什么活该写脚本，不涉及 Agent 效果调优与提示词写法。

browser-use 跑通第一个任务：三个官方入门示例里的最小运行骨架

拆开 browser-use 仓库 examples/getting_started 下的三个入门示例，指出它们共用的同一套四行骨架、这套骨架背后对应的仓库零件、任务描述该写到什么颗粒度，以及第一次运行最常卡住的八个位置。不覆盖云端托管方案、不讲反自动化对抗，也不替你判断目标站点是否允许被自动操作。

browser-use 容器化拆解：两个 Dockerfile 差在哪，基础镜像为何预装那么多

逐行读 browser-use 的 Dockerfile 与 Dockerfile.fast：两条路径装的浏览器来源根本不同、三层基础镜像各自预装了什么、容器里沙箱与启动参数如何自动切换，外加九条踩坑与规避。不讲云端托管，也不涉及绕过站点反自动化机制。

browser-use 结构化输出的 schema 约束与字段缺失排查

拆解开源项目 browser-use 的两条结构化输出链路：终局用 output_model_schema 换掉 done 动作，页面抽取把 JSON Schema 编译成 Pydantic 模型。读完能判断字段拿不到时该改哪一头，也清楚它明确不管哪些事。

browser-use 开源项目怎么让 Agent 登你的账号：敏感数据占位、域名限制与登录态存储三件套

拆开 browser-use 仓库里跟账号安全相关的三块代码：敏感数据占位替换、allowed_domains 域名门禁、storage_state 登录态落盘。讲清每块解决什么、各自漏在哪、为什么必须合起来用，以及上手时最容易踩的六个坑。不解决反爬绕过、验证码破解，也不替你判断目标站点的条款是否允许自动化。

browser-use 的 LLM 适配层怎么接国产模型与本地模型

拆 browser-use 仓库的 browser_use/llm/ 这一层：它为什么自己维护适配、一次请求在协议与序列化器之间怎么流转、接国产云端模型和本地 Ollama 各会撞到哪几行代码。读完能自己判断一个模型该走专属类还是 OpenAI 兼容入口。不讲价格与额度。

browser-use 是什么：让模型自己开浏览器点页面的开源项目

从仓库代码出发讲清 browser-use 干的是什么活：它把网页压成一份带编号的可操作元素清单，再让模型一步一决策地点、填、读。你能拿到组成部分与文件位置的对照地图、和写 Playwright 脚本的分工判断、以及边界与避坑清单。不讲它的云服务定价，也不教你绕过反自动化。

browser-use 跑不动时的排查顺序：异常类型、崩溃看护、CDP 超时与日志分层

从 browser-use 仓库源码出发，讲清一次失败该按什么顺序定位：异常类型本身能把故障分到哪一类、崩溃看护与每请求 CDP 超时分别兜住哪种死法、日志该从 agent 层还是 CDP 层开始看。给出模块地图表、边界说明与避坑清单，不涉及具体网站的自动化实现细节。

browser-use 的产物落盘：表格、PDF 与下载文件各走哪条路

拆开 browser-use 给 Agent 配的那层文件系统抽象，讲清内存文件对象与磁盘副本的双层结构，以及生成 CSV 表格、导出网页 PDF、浏览器下载文件这三类产物分别经过哪些代码路径落地、最后怎么交回调用方。不讲怎么写提示词，也不讲选型对比。

browser-use 本地跑不住时：远程浏览器与沙箱执行的分工与代价

拆解 browser-use 仓库里两条把浏览器任务挪出本机的路径——远程浏览器只搬走 Chromium，沙箱装饰器把整段函数搬走。读完你能对照仓库文件判断该走哪条、各自放弃了什么，以及登录态与密钥外迁前必须先想清楚的合规问题。不解决站点反自动化机制的规避，也不给价格与额度口径。

给 browser-use 加自定义动作：注册链路、动作过滤与取舍

从仓库代码出发，讲清 browser-use 里一个 Python 函数怎么被注册成模型可选的动作、domains 过滤在哪一步生效、以及哪些操作值得固化成动作、哪些该留给模型自己在页面上点。读完你能自己加一个动作并判断它的可见范围，不解决模型选型、反自动化对抗与站点条款问题。

开源自托管 Agent 项目 Hermes Agent 是什么：全景导读

从仓库结构讲清 Hermes Agent 这个开源自托管 Agent 项目：它常驻在一台机器上、从聊天软件里指挥、把做过的事沉淀成技能文件。读完你能判断它跟终端编码 Agent 是两类工具、适不适合你的场景、以及它明确不管什么。本文不覆盖逐项配置与安装细节。

开源自托管 Agent 项目 Hermes Agent 的三道闸门：审批模式、写入批准与路径安全怎么配

拆解 NousResearch/hermes-agent 里三套互不重叠的约束机制：命令审批门（含无条件拦截层与辅助模型判决）、记忆与技能的写入批准、以及路径包含校验。讲清各自防什么、代价在哪、怎么配才不是形式主义。不解决沙箱选型与合规审计。

开源自托管 Agent 项目 Hermes Agent 装机实录与必选配置

只盯着 NousResearch/hermes-agent 这一个仓库的上手记录。逐段读安装脚本到底改了你机器上的什么、配置文件里哪几项必须在第一次启动前就定下来、密钥为什么写了不生效、常驻与自我改写各自的代价在哪。不讲模型选型，不给任何价格与额度数字。

开源自托管 Agent 项目 Hermes Agent 常驻部署与缩容

逐行读 NousResearch/hermes-agent 的 Dockerfile、docker-compose.yml 与网关运行代码，讲清这个开源自托管 Agent 常驻一台小机器时进程怎么起、空闲怎么缩、运维要盯什么。不讲模型效果、不给部署成本数字，也不替你决定该不该上。

开源项目 Hermes Agent 里的四处成本旋钮各拦哪类失控

常驻在自己机器上的 Agent，花费失控往往不是一个原因。这篇按仓库代码拆开 Hermes Agent 中与成本相关的四处机制：工具结果的字符预算、迭代预算的消耗与退款、用量核算的口径、限流状态跟踪，说清各自拦的是哪一类失控、边界在哪。只讲机制与判断，不涉及任何价格与额度数字。

开源自托管 Agent 项目 Hermes Agent 的定时任务怎么跑

读 hermes-agent 的 cron 目录，讲清它的定时任务怎么定义、一次调度里发生了什么、结果往哪送，以及无人值守最容易失控的几处和它对应的拒绝式守卫。读完能判断这套设计适不适合你的场景，也知道自己动手时该在哪加锁、加台账。不含安装步骤与模型选型。

开源自托管 Agent 项目 Hermes Agent 起不来或断流：按这个顺序缩小范围

拆解开源自托管 Agent 项目 Hermes Agent 里的四处诊断设施——启动前的早期恢复、Windows 上的虚拟环境阻塞扫描、流式请求的断流诊断、常驻进程的退出取证，讲清每处告诉你什么、按什么顺序读，以及它们明确不管哪些故障。不提供性能调优与部署方案。

开源自托管 Agent 项目 Hermes Agent 的会话检索链路

拆解开源自托管 Agent 项目 Hermes Agent 的会话检索：本地 SQLite 加 FTS5 索引怎么拼成一条召回链路，中文与拉丁文查询各走哪条路，召回不准时该从哪一层查起。只讲仓库里读得到的机制，不含安装教程，也不替维护者预测后续行为。

开源自托管项目 Hermes Agent：技能怎么装、怎么被检索

hermes-agent 仓库里的 skills/ 并不是运行时目录，技能真正生效的位置是用户主目录下的那一份副本。这篇按仓库文件讲清两棵技能树的关系、装载与检索分几级发生、校验器画了哪些硬红线，以及什么时候值得自己写一个。不评价单个技能好不好用，也不做项目之间的排序。

自托管开源项目 Hermes Agent 的跨会话记忆由谁写入、何时写

拆解开源自托管 Agent 项目 hermes-agent 的持久记忆：两个 markdown 库谁在写、轮次计数器什么时候提醒模型去写、条目堆多了会付出什么代价、可插拔记忆后端的编排边界。读完你能判断要不要开它、开了以后哪些坑必踩。不解决模型推理能力问题，也不替你选云端后端。

用聊天软件指挥开源自托管 Agent 项目 Hermes Agent

拆解开源自托管 Agent 项目 hermes-agent 的聊天平台适配层：微信、Signal、QQ、WhatsApp 各自怎么收消息，消息又怎么被算成同一个会话，准入是几道门，以及把 Agent 挂到自己账号上要付什么代价。不含部署教学，也不替你判断某个平台的合规风险。

开源自托管 Agent 项目 Hermes Agent 怎么换模型与换供应商：元数据与切换动作拆解

拆开 hermes-agent 仓库里模型与供应商这条链：模型元数据实际来自哪里、上下文窗口怎么一层层解析出来、一次切换动作到底改了配置和运行时的哪几项、混用多家供应商时哪些地方会咬人。读完你能自己判断该改哪个键、该看哪个文件；不解决价格与额度选型问题。

自托管开源 Agent 项目 Hermes Agent 终端界面拆解

拆解 NousResearch/hermes-agent 的终端界面：它是独立的 TypeScript 前端进程，与 Python 主体只靠 stdio 上的 JSON-RPC 通信。读完你能判断多行编辑、斜杠补全、打断改口各自落在哪一层、该改哪个文件。不讲模型能力与部署运维。

开源自托管 Agent 项目 Hermes Agent 的并行派活机制

拆解开源自托管 Agent 项目 Hermes Agent 的委派链路：委派工具怎么建子 Agent 并剥掉危险工具、后台委派为什么把结果当成新一轮消息送回、插件侧生命周期服务管到哪一层。读完你能判断什么任务值得派出去、派出去之后从哪几个文件和日志盯进度。不解决模型选型与效果调优。

开源自托管 Agent 项目 Hermes Agent 的语音链路与代价

拆解开源自托管 Agent 项目 hermes-agent 的语音入口：唤醒词、录音与静音判定、转写、合成播放各是一块独立组件，它用什么方式串起来，代价落在哪里。读完你能判断这条链路要不要在自己机器上开，以及先改哪个配置项。不解决语音识别调参与音色训练。

开源自托管 Agent 项目 Hermes Agent 的终端后端怎么选

hermes-agent 的终端有本地、Docker、SSH、Singularity、Modal、Daytona、Vercel Sandbox 七条路。本文按源码梳理它们共同的执行契约，以及各自的隔离边界、文件同步、持久化与中断代价，帮你判断该用哪条；不讲价格额度，不做性能实测。

让 AI 生成接口设计，错误码分页幂等这三处默认答案为什么不能直接用

AI 写接口能省掉七成机械劳动，但错误码的可重试语义、分页的一致性保证、幂等键的作用域这三处它给的默认答案通常不够用。本文按环节顺序讲：先分清哪一步能交给它、哪一步必须你定，再给一张判别表和三处的具体做法与验收动作，最后给止损点。不解决线上已经出事之后的数据修复。

AI 写的办公自动化脚本总跑偏：批量改名、对账、报表该先动哪个

把批量改名、对账、汇总报表三类任务按可验证性排开，先讲每个环节 AI 能做到哪一步、哪一步必须你自己定规则，再给现象到成因的判别表、可执行的干跑与验收动作、止损与回滚判断。解决脚本半途失败、结果不可复现、数据被改坏的问题；不解决口径本身没人拍板的问题。

AI 写的表单校验前端好好的后端却收到脏数据，规则到底该写在哪一层

表单校验前后端各写一遍、写着写着就对不上，多数人归因成 AI 不懂业务，其实是规则没有单一落点。这篇按现象分因、判别、处置、兜底的顺序讲：怎么区分规则漂移、层级缺失、类型错位和绕过提交，哪些校验必须留给人定，怎么用一条 curl 验收，什么时候该停手回滚。不解决权限鉴权和业务风控。

用 AI 重构总是越改越乱：先固定行为再动结构，每一步都能退回去

让 AI 做重构，改完跑不起来或者行为悄悄变了，多数人以为是模型不懂架构。这篇按可执行的顺序排查：先判断你手上到底是重构还是改写，再定行为基线该怎么钉住、哪一步必须人来拍板，然后给分步提交与逐步回退的做法，最后给止损线。不解决架构选型，也不替你补业务测试。

AI 写的错误处理全在兜底：哪些该抛、哪些该兜、哪些必须让用户看见

AI 补的 try/except 大多是「吞掉异常、返回默认值」，线上表现是静默失败、数据变脏、告警不响。本篇按可执行顺序排查：先用现象判别成因，再画抛、兜、必须让用户看见这三条线，然后给改造与验收动作，最后给止损与回滚判断。不替你定义业务语义本身。

让 AI 出方案，它总给一个四平八稳的答案，怎么逼出真正不同的取向

你要三个方案，它给了三个换了标题的同一个方案。这篇按可执行顺序排查：先判别是模型能力问题还是你没给出分歧支点，再给指定分歧轴、拆两次问、强制标代价的具体做法和验收动作，最后给止损点。不解决方案本身对不对，那要靠你自己的工程判断和实测。

AI帮做国际化：抽文案能省事，占位符和复数最容易被悄悄改坏

这篇按「文案层 → 占位符层 → 格式化层」的顺序排查 AI 参与国际化后出现的界面异常，给出现象与成因的判别表、可直接跑的占位符校验脚本、伪本地化验收动作和回滚止损点。它解决的是资源文件从抽取到回填这一段的工程问题，不解决字符编码乱码和时间戳存储时区那两类问题。

AI 帮我加了缓存命中率很好看，可数据改了页面还是旧的

缓存出了问题，别急着清缓存。这篇把现象分成六类：没失效、多副本不同步、键缺维度、集体过期、缓存了失败结果、中间层还有一层，按顺序给判别方法、验证动作和处置手段，并写清哪些决定不能交给 AI、什么时候该回滚关掉这段缓存。不涉及构建缓存与 Agent 调用层缓存。

AI 画的架构图总跟真实系统对不上：文本生成图的排查与修法

用 Mermaid、PlantUML 这类文本语法让 AI 生成架构图与流程图，图不准往往不是模型画不好，而是描述源来自记忆而非仓库。这篇按环节排查：先判断图的类型是否错配，再用现象对照表定位成因，然后给出从代码取事实、人定边界、机器转语法的分工与验收动作。不解决美化排版、白板协作和设计稿还原。

告警配了一堆却没人看：让 AI 重写监控规则的排查顺序

告警群天天响、真出事的时候反而没人第一时间反应，多数团队会归因为"规则写少了"，于是继续加规则，噪音更大。这篇按可执行顺序拆：先用判别表把现象分因，再说清 AI 在告警这一环能替你做哪几步、哪几步必须人拍板，然后给验收动作和止损点。它不解决指标采集链路本身的故障，也不替你决定业务上什么算事故。

技术选型问 AI 靠谱吗：哪些结论能用，哪些必须自己验

问 AI 做技术选型，翻车的多数不是模型太笨，而是你把「时效敏感的事实」和「结构稳定的判断」混在一句话里问了。这篇按选型的工程环节拆开：每个环节 AI 能帮到哪一步、哪一步必须人来定，给出现象到成因的判别表、可执行的验收动作和止损点。不解决具体框架谁更好的问题。

接手没人维护的老系统，AI 该从哪三条线切进去

老系统没人能解释、文档早已失真时，先别急着让 AI 生成架构图。这篇按入口、数据流、副作用三条线给出可执行的排查顺序：每条线先说 AI 能推进到哪一步、哪一步必须人拿证据确认，再给验证动作与判别表，最后给止损点和回滚点。不解决业务规则本身对不对的问题。

AI 把 Java 翻译成 Go 后语义悄悄变了，怎么逐块验出来

跨语言迁移里 AI 最擅长的是字面翻译，最不擅长的是补齐两种语言在空值、整数溢出、时区、并发、异常传播上的语义差。本篇按可执行的排查顺序走：先用现象定位是哪一类语义差，再给逐块切分与对拍验收的做法，最后给止损点与回滚点。不解决架构重构选型，也不解决性能调优。

AI 写出来的东西总跑偏？多半是需求没问清就让它动了手

这篇按排查顺序拆需求模糊导致的返工：先用四类现象把成因分开（是你自己没想清、是它不肯问、是上下文缺了一块、还是目标中途漂了），再给让 AI 提问而不是猜的具体动作与验收方式，最后给止损点和回滚点。不解决需求定稿后的规格书写与交付物验收，那是另外两件事。

AI 写的数据迁移脚本跑一半断了，重跑就出重复数据怎么办

迁移脚本出事，多数不是 AI 代码写错了，而是断点、幂等、核对这三件事从一开始就没设计。这篇按可执行顺序讲：先用现象判别成因，再给断点续跑与幂等键的具体做法，再给上线前的核对动作和止损回滚判断。不解决数据库选型、双写切流、跨机房复制这类架构问题。

让 AI 设计权限模型，为什么角色资源动作说不清就一定漏

权限模型漏洞很少是编码错误，多数是需求阶段三要素没定清就交给了模型。这篇按可执行顺序排查：先用一张判别表把现象归到成因，再给三要素的落地写法与验收动作，最后给止损点和避坑清单。不解决具体框架的配置语法，也不替你做合规判定。

让 AI 帮着升级依赖：破坏性变更怎么找、升级顺序怎么排

依赖升级失败大多不是版本选错了，而是一次性动了太多层、又没人替这些变更定优先级。这篇按可执行顺序讲：先把升级动机分类，再找破坏性变更的四个信源，然后用依赖图排出升级批次，给出现象到成因的判别表，最后说清什么时候该回滚止损。不讲具体产品的额度规则，也不覆盖包名不存在的情况。

用 AI 做事故复盘，时间线拼得挺快，根因却总是写歪

事故复盘里 AI 能做的是把散在各处的日志、告警、提交记录、聊天记录对齐成一条可读时间线，做不了的是判定根因和拍板改进项。这篇按复盘的实际顺序讲：先分清哪一步交给 AI、哪一步必须人来定，再给判别表、可执行动作与验收方式，最后给止损点。不解决监控体系建设与告警策略调优。

让 AI 写数据分析脚本：口径没说清，算得再快也是错的

用 AI 写分析脚本，跑通不等于算对。这篇按可执行顺序排查：先把口径错、数据错、代码错三类问题分开判别，再给每一类的验证动作和处置手段，然后讲口径该怎么写才不会被模型自由发挥，最后给止损点和避坑清单。不解决业务指标本身该怎么定义，也不评测具体工具优劣。

让 AI 设计数据库表，为什么上线三个月就改不动了

一篇按工程环节切的排查指南：先判断表结构问题出在建模、约束还是索引，再给出每一步的可执行动作与验收方法，最后给止损点。适合已经让 AI 生成过建表语句、现在开始还债的团队。不解决具体数据库产品的调优参数问题，也不替代正式的容量规划。

AI 改了三轮还没修好？多半是你跳过了复现这一步

这篇按「先复现、再定位、最后才改」的顺序讲 AI 参与调试的正确用法：怎么把偶发变必现，怎么用一张判别表把现象归到成因，哪些判断必须人来下，改完怎么验收，什么时候该止损回滚。它不解决具体某个框架的疑难杂症，也不替代你对业务逻辑的理解。

AI 写的测试用例为什么大多没有鉴别力：怎么逼它写出真正的边界用例

让 AI 补测试，用例写了一堆却抓不到任何 bug。这篇按可执行顺序拆：先分清复述实现、断言空转、把逻辑 mock 掉、边界维度缺失这四种成因并给判别法，再讲哪一步必须人来定边界、哪一步交给 AI，然后给逼出边界用例的具体做法和变异验收动作，最后是止损点。不解决测试架构选型和端到端测试搭建。

AI 写的 CI 流水线跑起来总不稳：缓存键、并发取消、失败重跑怎么定

让 AI 生成 CI 配置很快，但真正让流水线不稳的是三处需要人拍板的语义：缓存键的边界、并发取消的粒度、失败重跑的前提。本文按可执行顺序排查：先用判别表把现象分因，再给逐项的定法与验收动作，最后给止损点和避坑清单。不解决具体测试用例本身的缺陷，也不替代对业务部署流程的评估。

AI 写的容器配置能跑，上线却被安全和健康检查卡住

让 AI 生成 Dockerfile 和 compose 配置，能跑起来不代表能上线。这篇按分层与缓存、运行身份、健康检查、启动依赖四段顺序拆开：先教你从现象反推是哪一层出错，再给可验证的动作和验收命令，最后给止损点。不解决业务代码本身的性能问题，也不替你做基础镜像的合规选型。

让 AI 写抓取脚本，跑之前该卡住哪几步：robots、频率与用途的边界

AI 十几秒就能给你一份能跑的抓取脚本，但能不能抓、抓多快、抓来干嘛这三件事它替你定不了。这篇按「场景归类 → 开跑前四个判断 → 跑起来后的现象判别表 → 止损换路」的顺序讲，帮你在脚本上线前把边界写成可验收的动作。不解决反爬对抗，也不讨论任何越权访问的做法。

让 AI 写 shell 脚本总在三处翻车：set -e、引号、路径空格怎么排查

AI 生成的 shell 脚本经常是「看着能跑，关键时刻不报错就往下走」。这篇按现象分因、验证、处置的顺序，拆解 set -e 失效、引号缺失、路径含空格这三类高频翻车，给出一张判别表、一套五分钟验收动作和止损点。不解决业务逻辑对不对，也不替代真实环境的联调。

AI 写的 SQL 跑得通却算错数：join、空值、时区、大表扫描怎么查

这篇按「先分因、再动手、最后兜底」的顺序讲 AI 生成 SQL 的四类高发失误：join 方向被 where 条件悄悄改写、空值让计数和过滤失真、时区在存与算之间错位、大表扫描把索引废掉。给出判别表、逐步验收动作、止损点和避坑清单。不解决业务口径本身对不对，也不替你做数据建模决策。

AI 写的 README 和接口文档看着挺像样，一核对全是错的

这篇按文档类型分因排查：先判断是喂的输入不够还是边界没定，再给 README、接口文档、运维手册各自必须喂进去的材料、可执行的写法和验收动作，最后给止损点与回滚点。解决的是文档内容和真实系统对不上的问题，不解决文档站选型、排版风格统一、多语言翻译一致性这类工程问题。

AI 写的正则总在边界上翻车：样本、规则、反例这三步到底该怎么排

让模型写正则，多数返工不是模型不会写，而是你只给了一段规则描述、没给样本集，更没拿反例过一遍。这篇按「先分清哪一步该人定 → 怎么组织样本与规则 → 怎么用反例做验收 → 什么时候停手换实现」的顺序讲，给可直接跑的校验脚本；不讲正则语法教学，也不讲已经上线之后的性能故障定位。

性能优化让 AI 参与到哪一步：它能读火焰图吗，什么必须你自己测

一篇按工程环节切分的性能优化协作手册。逐环节说清 AI 能帮到哪一步、哪一步必须人来定，给出把采样数据喂给模型的正确形态、一张现象对成因的判别表、验收动作与止损回滚依据，以及避坑清单。不解决容量规划、架构选型和线上事故的应急处置。

本地跑得好一上线就挂：按运行时、依赖、配置、数据四层逐层比

上线即挂多数不是代码写错，而是本地与线上在某一层的环境不同。这篇按「现象分因 → 判别表对号 → 运行时/依赖/配置/数据四层逐层比对 → 止损与回滚」的顺序走，给出可直接照抄的比对命令。它不解决业务逻辑缺陷、容量规划和性能调优，只负责把两边环境的差在最短时间里挖出来。

AI 写的并发代码总在偶发出错：竞态怎么稳定复现和修掉

双击提交多出一条记录、计数器少加、并行写同一份文件被写坏，这类问题不是模型写得差，而是它默认了单执行流。本文给一条可执行的排查顺序：先按现象分因，再用并发复现把偶发变必然，再按内存态、数据库、文件系统三层给处置动作，最后说清什么时候该停手回滚。不解决分布式一致性设计和性能调优。

重试之后发现同一件事做了两遍，幂等键该怎么设计

超时不等于失败，重试出来的重复扣款、重复发消息、重复建资源，多数是写操作缺幂等键加上错误的失败判定。本文按现象分因、判别表、幂等键设计、重试前必须先查的操作清单、止损点的顺序讲一遍，解决被调用方的防重问题，不解决调用方的退避策略和排队限流。

整个文件都显示被改过：换行符 CRLF 与 LF 的混乱怎么终结

一个字符没动，git 却说整文件都变了，评审界面还全是绿色新增。这篇按可执行的顺序排查：先用三条命令判定是不是行尾符，再定位是编辑器、git 配置、AI 工具还是 CI 改写了它，然后用 .gitattributes 收口并做一次规范化。不解决语法格式化风格之争，也不替你处理已经爆发的合并冲突。

定时任务有时不跑有时跑两遍：先分清漏跑和重复跑再动手

定时任务出问题时，多数人第一反应是加重试或加告警，方向往往是错的。这篇按可执行的顺序给出排查路径：先用现象把漏跑和重复跑分开，再定位是多实例、调度端还是执行超时，然后按收敛触发源、分布式锁、补偿扫描、幂等落库的次序上手段。也会说清哪些情况下该止损换路，以及它不解决业务逻辑本身写错的问题。

明明改了配置却连到错误环境：hosts、DNS 缓存与代理的排查顺序

同一个域名，在浏览器里是测试环境，在终端里是生产，在 AI 编程工具里又变成第三个结果。这篇按「先看实际出口、再分层定位、最后才动手清理」的顺序，讲清 hosts、DNS 缓存、代理三处配置如何各自劫持请求，以及怎样用只读命令确认谁在生效。不解决服务端路由错误和证书信任问题。

端口被占用、进程没退干净：到底是谁占着，重启为什么会掩盖真问题

端口起不来时，多数人只会换端口或重启。本篇按可执行顺序排查：先分清「谁在监听」「谁没退干净」「谁根本没资格绑」三类成因，给出跨平台查占用者的通用命令和一张判别表，再讲重启为什么会掩盖孤儿进程，最后给止损点与避坑清单。不解决容器编排层的服务发现问题。

开源 Agent 套件 ECC：67 个 agent 怎么分角色与选用

把 ECC 仓库里的 67 个 agent 按「能不能动你的文件」重新分组，讲清每一类适合接什么任务、命令与 agent 的对照关系怎么读、点名错了会出现哪几种典型故障，以及这套设计放弃了什么。不解决安装配置问题，也不评价它与其它套件孰优孰劣。

用开源 Agent 套件 ECC 扫一遍你的 Agent 配置：提示词、钩子与 MCP

ECC 这套装在编码 Agent 之上的开源增强件带了一条 security-scan 链路，专扫 CLAUDE.md、settings.json、mcp.json、hooks 和 agent 定义这类不像代码却真的会执行的文件。本文讲清它由哪几块拼成、实操怎么跑、报出来的条目按什么顺序处理，以及它明确不管哪些事。它不替代业务代码审计，也不管运行时行为。

开源 Agent 套件 ECC 的选择性安装：三层清单怎么挑最小集合

ECC 把「装什么」拆成 profile、module、component 三层清单，配合 dry-run 预览和 install-state 记账。本文按仓库里的真实清单文件和安装脚本，讲清这三层各自控制什么、依赖怎么算、换目标工具时哪些模块会被跳过，以及怎么给自己的项目挑一套最小集合。不讲内容质量评价，也不替代官方文档。

开源 Agent 套件 ECC 上手第一周：先开哪几样、第三天加什么、哪些先别碰

ECC 是一套装在编码 Agent 之上的增强件，仓库里有 67 个 agent、281 个技能、94 个命令，还有钩子、规则和多套安装清单。这篇把它的目录结构、profile/module 划分和运行期开关摊开，给出一条第一周的开合顺序，以及每一步的代价。不讲通用 Agent 方法论，也不替你判断该不该上。

开源 Agent 套件 ECC 装完不干活：自检脚本、钩子失灵与排查顺序

拆解开源套件 ECC 的故障排查路径：ecc doctor 能查出哪几类问题、它给出的报错码分别意味着什么、钩子不触发的已知坑长什么样，以及按什么顺序缩小范围最省时间。不讲通用的安装排错套路，只讲这个项目把排查落成了哪些真实脚本与文档。

开源 Agent 套件 ECC 值得装吗：多出来的能力与成本一起算

把开源套件 ECC 装在编码 Agent 之上，你得到的是流程产物化、审查隔离和一套可禁用的钩子运行时，付出的是常驻上下文、装机文件、供应链面和排错难度。本文给出组成结构表、四种典型情况的判断依据、明确不管的边界，以及九条上手避坑项。不讲安装教程，不评优劣排名。

开源 Agent 套件 ECC：281 个技能的放置规则与检索姿势

ECC 是装在编码 Agent 之上的一套增强件，仓库里有 281 个技能。这篇讲清楚技能被放在哪几个位置、命名遵循什么规律、按什么顺序检索才不会漏、以及找不到时怎么区分「仓库里真没有」和「你搜错了地方」。不讲技能内容本身好不好用，也不替它做功能推荐。

开源 Agent 套件 ECC 的记忆系统实操：什么该写进去，写多了会怎样

ECC 用一个本地 Memory Vault 承接跨会话上下文，把每条记忆钉在待核实状态、写入只增不改。这篇拆它的作用域与类型怎么分、哪些内容该进哪些绝不该进、会话启动注入与经验条目堆积会带来什么反效果，以及它明确声明不管的事。不重复通用记忆方法论，也不替你做选型。

你的 agent 和技能能不能换工具用：开源套件 ECC 的适配拆解

拆解开源 Agent 套件 ECC 的跨 harness 设计：哪些资产换工具时能原样带走、哪些只能降级成提示文本、哪些干脆带不走。读完你能判断一套自研工作流该把哪层沉淀成共享源，以及迁移时要验哪几件事。不解决模型选型和服务商配额问题。

开源 Agent 套件 ECC 的 94 个命令导航：分组线索与调用链

一份面向工程师的 ECC 命令导航：命令目录实际按什么线索分组、哪几条是你每天真会敲的、一条斜杠命令背后到底调起了 agent 还是技能还是脚本，以及机器生成的命令清单为什么不能全信。不讲通用的斜杠命令写法，也不解决安装与配置问题。

开源 Agent 增强套件 ECC 是什么：一张五类组件的全景地图

ECC 是一套装在 Claude Code 等编码 Agent 之上的开源增强件，往你的工作流里塞进 agent、技能、命令、规则、钩子五类东西。这篇拆开它的仓库结构，说清每类组件落在哪个目录、什么时候会触发、它放弃了什么，以及装它的人最常误解的那一点。不讲怎么写提示词，也不替你判断该不该上。

开源 Agent 套件 ECC 的四份示例工程拆解：哪些段落该抄，哪些只属于你的栈

把 ECC 仓库 examples 目录里 Django、Go、Rust、Rails 四份项目级 CLAUDE.md 摆在一起对读，拆出它们共用的八段骨架、四条硬交集规则，以及各自栈相关的部分。读完你能照着这套骨架写自己项目的规则文件，也能避开示例里指向已下线命令的坑。不讲通用写作方法论，只讲这一个项目怎么落到实处。

开源 Agent 套件 ECC 怎么管 token：上下文预算这条线上的可调旋钮

ECC 往编码 Agent 上挂了大量技能、命令与钩子，很多人第一反应是上下文会被吃光。这篇顺着它自己的 token 优化文档、context-budget 与 cost-aware-llm-pipeline 两个技能，梳理常驻开销来自哪里、有哪些真能拧的旋钮、哪些事它明确不管，以及安装时最容易踩的几个坑。不涉及价格与额度。

开源 Agent 套件 ECC 的根目录说明文件怎么写：一套可复制的结构

拆解开源 Agent 增强套件 ECC 仓库里的 CLAUDE.md、AGENTS.md、rules 目录与 examples 模板，反推一份项目级说明文件该有哪些块、规则写到什么颗粒度才有约束力，并给出这套写法的代价、失效方式和上手避坑清单。不解决具体框架选型与安装教程。

开源 Agent 套件 ECC 的多语言规则库怎么落到你的项目上

拆解开源编码 Agent 增强套件 ECC 的 rules 目录：通用层与语言层怎么分、规则文件顶部的路径声明起什么作用、项目技术栈通过哪张映射表换成规则与权限清单、规则太多时按什么顺序裁。读完你能自己判断该装哪几个目录。本篇不评价规则条文本身，也不教你从零写规则。

装开源 Agent 套件 ECC 之前：状态记在哪、写了什么、怎么卸干净

从 ECC 仓库的安装计划脚本、卸载脚本和安装状态 schema 出发，讲清这套编码 Agent 增强件把安装记录写在哪个文件、记了哪些字段、卸载时按什么规则回收，以及哪几类写入注定卸不干净。读完你能在装之前判断风险、在退出时验证残留。不涉及功能测评与效果承诺。

发版之后老用户白屏：旧资源 404、缓存与版本号的排查顺序

发布后只有发布前就打开页面的人白屏，多数团队第一反应是让用户清缓存，方向就错了。这篇按现象分因、验证动作、三层处置的顺序讲清楚旧 HTML 引用旧分包为什么会 404，给出判别表、止损与回滚判断、七条避坑清单。不讲构建产物本身出错，也不讲线上事故里 AI 能改到哪一步。

分页翻着翻着数据重复或漏掉：从偏移分页缺陷排查到游标分页改造

列表翻到第几页开始出现重复行、或者某些记录怎么都翻不到，多数人第一反应是查前端渲染，方向就错了。这篇按先分因、再动手、再兜底的顺序讲：怎么判别排序不稳定、并发写入、副本延迟还是前端重复追加，怎么最小改动止血，游标分页怎么落地。不解决跳页与总数展示的产品诉求。

对账差一分钱查了三天：金额存成浮点数，错到底出在哪一步

金额差一分钱，八成不是某段代码写错，而是金额全程用二进制浮点表示。这篇按可执行顺序排查：先分清表示误差、舍入口径不一致和逻辑写错，再用判别表定位误差在哪一段引入，然后给出整数分与十进制定点数的改法和最易漏的边界，最后讲止损与回滚。不替你决定业务舍入口径。

终端编程 Agent 选型五条线：以 pi 这个 Agent 框架为样本

开源终端编程 Agent 的差别不在功能列表，而在许可证、隔离能力、可嵌入性、模型自由度、可审计性这五条能自己查证的线上。本文以开源编程 Agent pi 的仓库与文档为样本，逐条演示每项该翻哪个文件、看哪句话、验哪个字段，并给出边界与避坑清单，不给产品排座次。

写死的示例数据混进了真实路径，上线才发现该怎么排查

生产冒出假姓名、恒为零的金额、永远成功的回执，多数人先去查数据库，方向就错了。本篇按先分因、再动手、最后兜底的顺序，讲清 mock、种子数据、演示分支三类假数据各自的指纹，给出判别表、三道闸门和止损回滚依据；不解决历史脏数据的清洗方案。

服务跑几天就越来越慢：内存泄漏的定位顺序与三个常见来源

一篇按排查顺序组织的长驻服务内存问题手册。先教你分清真泄漏、缓存膨胀和正常抖动，再用一张判别表把现象对上成因，然后分别给出监听器、缓存、连接三类来源的确证方法和处置动作，最后讲清什么时候该止损重启、什么时候该回滚。不覆盖单机调优参数选型和容器编排层面的资源规划。

测试配置指到了生产库：连错环境为什么没人报错

一篇按排查顺序写的多环境配置串环境指南。先教你用现象反推是加载顺序问题、默认值兜底问题还是凭据复用问题，再给分层切分、启动自检、连接指纹校验三步动作，最后给止损点和避坑清单。不覆盖环境变量读不到、也不覆盖数据误删后的数据恢复。

逐段读开源编程 Agent pi 的主循环：一轮里发生了什么，循环靠什么停

打开 pi 仓库里 packages/agent 的三个文件，把它的 Agent 主循环拆成可跟读的几段：一轮（turn）的边界在哪、工具调用在哪一步接回上下文、并行与串行怎么切、循环有哪几个出口。读完你能照着改自己的循环，也知道它有意不管哪些事。不讲提示词技巧，不讲模型选型。

开源编程 Agent pi 的统一模型接口：一套类型怎么盖住十种协议

拆解开源编程 Agent pi 的 @earendil-works/pi-ai 包，看它用哪几层类型把 Anthropic Messages、OpenAI Responses 等十种形态各异的接口收敛成同一份消息与事件模型，接缝落在 compat 位、签名回放和工具切分这三处。读完你能拿到一张组件对照表和一份避坑清单，不涉及价格、额度与选型排名。

开源编程 Agent pi 的安全边界：项目信任与输出防护分别拦住了什么

拆开 pi 仓库里真正跟安全沾边的两处代码——项目信任的判定链路和 stdout 接管机制，说清它们各自拦住什么、拦不住什么，并对照官方安全文档里承认的不设防地带。读完你能判断在什么场景下必须把 pi 关进容器，不解决模型侧越权和提示注入的根治问题。

开源编程 Agent pi 上手实录：从 npm 安装到跑通第一个任务

一篇只盯着 pi 这一个仓库的上手记录。讲清它的安装命令为什么带 --ignore-scripts、凭据的四条来源与优先级、第一次对话该给它哪些上下文、Windows 上必须先备好的 bash 和终端按键映射，以及它明确不管的那几件事。不讲模型选型，也不给任何价格与额度数字。

开源编程 Agent pi 的本地模型接入：路由服务器与自定义服务商

拆解开源编程 Agent pi 官方文档给出的本地推理接入形态：llama.cpp 路由服务器走的是内置扩展注册 Provider 的路子，models.json 走声明式配置，两者与自定义服务商机制是同一套接口的不同入口。读完你能判断自己该走哪条，也知道它不解决模型质量与显存问题。

开源编程 Agent pi 的仓库结构导读：七个包各管什么、依赖怎么排

拆解开源编程 Agent 项目 pi 的 monorepo：七个工作区各自的职责边界、依赖方向为什么是单向的、拿到仓库后按什么顺序读源码最省时间，以及它明确不管哪些事。不讲怎么用 pi 干活，也不做工具横评。

开源编程 Agent pi 的上下文压缩：源码级拆解触发时机与保留策略

从 pi 仓库里的 compaction.ts、branch-summarization.ts 和官方文档出发，拆开这套上下文压缩的三个入口、切分点规则、分裂轮次的双摘要、文件轨迹累积，以及分支摘要在解决什么问题。读完你能自己判断该怎么调那几个阈值、哪些信息注定会丢。不覆盖记忆检索与跨会话长期记忆。

开源编程 Agent pi 的可持久化运行：中断后能续上需要哪些前提

拆解 pi 仓库里关于可持久化 Agent 运行的设计文档，讲清楚半可持久化这个取舍是怎么来的、会话日志为什么被当成唯一的耐久状态树、恢复时宿主应用必须自己重建哪些依赖，以及默认保守恢复策略覆盖了哪些崩溃点。不解决具体的部署与存储选型问题，也不承诺该设计的落地时间表。

开源编程 Agent pi 的文件编辑：差异比对与写入排队各挡什么事故

从 pi 仓库里 edit、edit-diff、file-mutation-queue 三个文件出发，讲清它的编辑工具靠哪几道校验避免改坏文件，模糊匹配的代价被关在哪里，多个工具同时改一个文件时队列怎么排。读完能拿到一份可复用的设计与避坑清单，不涉及安装配置与模型选型。

开源编程 Agent pi 的评测包：它怎么给一个 Agent 建回归

拆开 pi 仓库里的 evals 包，看它怎么把一次 Agent 运行压成可断言的结构化结果、怎么用临时目录保证每次从干净状态开始、怎么把模型选择做成硬失败。读完你能拿到一套可以直接搬进自己项目的回归骨架，以及它明确不管的那几件事。不解决评分标准和线上质量监控。

开源编程 Agent pi 的基础工具层：四把工具的参数、边界与克制

逐个拆开 pi 内置的 bash、read、write、edit 四把基础工具，看清每把工具向模型暴露了哪几个参数、边界画在哪、超出边界时返回什么提示，以及默认工具集为什么只留四个而不是七个。读完你能照着这套取舍去审视自己的工具层。不涉及安装配置、模型接入与扩展开发。

开源编程 Agent pi 的钩子与可观测性：能插手哪些时机，又能看到哪些数据

拆解开源编程 Agent pi 的两套机制——可以改变执行结果的事件钩子，和只读不干预的观测事件契约。你会拿到完整的事件时机清单、能落到审计与成本归因上的数据来源，以及一份避坑清单。不解决怎么装 pi、怎么调模型，也不替你选 APM 方案。

开源编程 Agent pi 的会话存储：JSONL 追加树与恢复流程

拆解开源编程 Agent pi 的会话持久化：文件落在磁盘哪个位置、一行 JSONL 长什么样、追加写与 leaf 条目怎么配合出一棵可分叉的树、恢复一次会话时按什么顺序读文件并重建上下文。读完你能自己写脚本解析它的会话，也知道这套结构在哪些场景会吃亏。不讲价格与额度。

开源编程 Agent pi 的会话怎么存、怎么续、怎么翻回去看

从磁盘形态入手拆解 pi 的会话机制：JSONL 文件放在哪、每一行是什么条目、id 与 parentId 怎么拼成一棵树、压缩和分支摘要在文件里留下什么痕迹，以及这套设计让你能做哪些事、明确不管哪些事。不讲通用上下文方法论，只讲这个项目的落地做法。

开源编程 Agent pi 接入国产模型：目录、接入位与切换机制

从 pi 仓库的 provider 目录出发，讲清内置了哪些国内厂商条目、每条对应什么 API 与环境变量、切换模型时改动到底落在 auth.json 还是 models.json，以及凭据的解析优先级。只讲机制与配置位置，不讨论价格额度，也不替你做厂商选型。

开源编程 Agent pi 的扩展加载器：从被发现到被执行要过几层

拆解开源编程 Agent pi 的扩展加载链路，从目录发现、jiti 载入、注册期与运行期分离，到工具包装层做了什么。读完你能照着排查扩展没生效、动作方法报未初始化、快捷键被吞这类问题。不涉及扩展怎么写业务逻辑，也不讲 MCP 协议本身。

开源编程 Agent pi 的扩展、技能、提示词模板与包该怎么选

pi 把可扩展性拆成扩展、技能、提示词模板、包四个位置，各自装在不同的层，触发方式和能力边界完全不同。这篇讲清楚每一层解决什么问题、什么场景该用哪一个、选错会付出什么代价，并给出一份基于仓库文档的避坑清单。不涉及价格、额度与安装教程。

开源编程 Agent pi 的模型解析链路：从你写的名字到真正发出的请求

拆解开源编程 Agent pi 里模型名的解析过程：模式匹配怎么把模糊字符串变成具体模型、注册表的三层叠加如何决定候选集、组装器又往请求里塞了什么。读完你能定位「为什么选中的不是我要的那个模型」，但它不替你做路由与成本决策。

把开源编程 Agent pi 调顺手：配置、键位、主题、终端四处各改哪里

pi 把可定制的部分拆成四层：设置管行为、键位管按键、主题管配色、终端配置决定按键能不能传进来。这篇按仓库文档梳理每层的位置、生效方式与最该先改的几项，也说清哪些设置改了反而添乱。不讲怎么用 pi 干活，只讲怎么调顺手。

开源编程 Agent pi 的服务商层：模型清单从哪来，怎么加一家

拆解开源编程 Agent pi 仓库里的服务商层：Provider 接口与 Models 集合各管什么、内置模型目录由哪个脚本生成、动态清单怎么刷新和缓存，以及往仓库里加一家新服务商需要改哪些文件。读完能照着仓库定位每一处改动点，不涉及各家模型的价格与额度对比。

把开源编程 Agent pi 嵌进自己的程序：三条集成路线怎么选

pi 官方文档给了三条把 Agent 接进自己程序的路线：同进程 SDK、子进程 JSON-RPC、单次 JSON 事件流。这篇逐条拆开它们的形态、能力边界和适用场景，给出对照表、避坑清单和选型判据。不讲提示词技巧，也不评价 pi 与其它工具孰优孰劣。

开源编程 Agent pi 没有内置权限系统：三种隔离路线怎么选

pi 明说自己不提供限制文件系统、进程、网络、凭据的内置权限系统。这篇拆开它为什么这么设计、项目信任到底拦住了什么、Gondolin/Docker/OpenShell 三条隔离路线各挡住和挡不住什么、按风险怎么选。不解决提示注入，也不给合规方案。

开源编程 Agent pi 的服务端包：进程怎么拉起、怎么看住

拆解开源编程 Agent 项目 pi 的实验性服务端包，讲清它如何把 agent 拉起为子进程、如何用一条 stdin 送请求、如何在异常退出和守护进程重启后维持状态记账，以及它明确不负责的部分。读完你能判断这套结构值不值得借鉴，不涉及模型效果与价格。

开源编程 Agent pi 的上下文压缩：长会话崩掉前它做了什么

长会话失控不是模型变笨，是上下文账本溢出。这篇拆开源编程 Agent pi 的压缩机制：三种触发口径、切点怎么选、摘要里保留哪些结构化字段、文件追踪如何跨轮累计，以及它明确不管的那部分。读完你能判断自己的会话该不该手动压、参数该怎么调；源码级实现细节不在本篇。

开源编程 Agent pi 是什么：三个独立包拆出来的终端编码工具

从仓库结构出发讲清 pi 这个开源编程 Agent 项目：统一模型接口、Agent 运行时、终端界面各自被拆成独立 npm 包，一个请求从回车到模型返回要穿过哪几层，它明确不管权限与沙箱。读完你能判断它适不适合你的场景，但本文不覆盖逐个配置项的用法。

开源编程 Agent pi 的技能机制：怎么被发现、被筛选、装进上下文

拆开 pi 这个 Agent 框架的技能加载链路，讲清楚技能目录是怎么被扫出来的、重名和软链怎么裁决、进系统提示的到底是哪几个字段，以及这套设计把成本压在了描述行和一次额外读文件上。不讲怎么写好一个技能的正文，也不做工具优劣排序。

开源编程 Agent pi 的终端界面为什么不闪：差分渲染在管什么

pi 自带的终端 UI 库用差分渲染处理界面闪烁与错位。本文按仓库源码梳理它的渲染主循环、宽度硬校验、光标标记与覆盖层合成，说明哪些情况下它会退回整屏重画，以及你写扩展组件时哪几条约束不能商量。不涉及价格与模型选型，也不覆盖非终端形态的界面。

开源编程 Agent pi 的系统提示词是怎么拼出来的：固定段、动态段与替换位

逐行拆解开源编程 Agent pi 的系统提示词拼装逻辑：默认正文里写死了哪几块、工具清单和守则从哪来、项目上下文与技能清单怎么注入、替换与追加两条路径的差别在哪。读完你能自己定位每一段文本的来源文件，也知道哪些配置会让某一段静默消失。不涉及模型效果调优与提示词写法优劣。

给开源编程 Agent pi 接入自定义模型服务：填什么，哪里最容易配错

拆解开源编程 Agent pi 的自定义 provider 机制，讲清 models.json 与扩展注册两条入口分别要你提供哪些信息、字段的默认值和替换语义、值解析语法的坑，以及上下文溢出识别失灵这类隐蔽故障。读完你能照着填一份不返工的配置，但本篇不评测任何模型服务好坏。

日志里把密钥和用户手机号打出来了：脱敏放在哪一层，已写进去的怎么清

从现象倒推敏感信息是走哪条通道进的日志，给出一张判别表，再讲脱敏应该落在调用点、序列化层、日志管道还是采集端，以及已经落盘的日志按什么顺序收拾（先轮换凭据再画副本地图）。不解决合规条款解读，也不替你判断是否触发对外通知义务。

时间对不上：AI 生成的日期代码为什么总在时区和时间戳之间翻车

时间差 8 小时、日期整体早一天、本地对线上错、年末年份跳一年，这几类问题看着像不同的 bug，成因其实只有几种。这篇按「先分因、再动作、最后兜底」的顺序给出判别表和验证命令，帮你在一小时内定位到出错的那一层。它不解决业务口径争议，也不替你决定日报该按哪个时区切分。

数据被误删或误更新之后：先停手、再取证、最后才谈恢复

库里的数据被 AI 助手或一条手滑的语句改坏之后，最贵的不是那条语句，而是你紧接着做的第二件事。这篇按停手、判别、取证、恢复、止损的顺序讲清楚该怎么排，给出一张现象与成因的判别表，也说明它不解决哪些问题：不涉及硬件损坏的介质级修复，也不替代你本该有的备份策略。

AI 写的迁移脚本跑完才发现回不去，改表删列改类型前该准备什么

迁移不可回退的根因通常不是脚本写错，而是这条 DDL 本身会丢信息、而 down 只还原结构。这篇按「先判断当前处在哪一步、再判别现象成因、再给执行前的准备动作、再给跑完之后的补救与止损点」的顺序展开，解决改表删列改类型的可逆性设计，不解决数据库选型和分库分表本身的架构问题。

存进去是中文，取出来是一串问号：数据库字符集不一致怎么排

中文写进数据库变成问号或怪符号，问题很少出在库本身。这篇按「先分类型、再顺链路读编码、最后才动手改」的顺序讲：怎么用一条 HEX 查询区分「转换丢失」和「双重编码」，动作该从连接改还是从列改，存量脏数据什么时候能救、什么时候必须从上游重灌。不覆盖前端页面显示乱码和文件读写编码。

把 Agent 方法论框架 superpowers 装到你的工具上：多平台接入差异与不生效排查

superpowers 对 Claude Code、Cursor、Codex、Gemini CLI、Kimi Code、OpenCode、pi 等各有一套接入方式，装法差异全在会话开始那一次上下文注入上。本文按仓库源码梳理它的三个组成部分、四种接入形态、最容易装完不生效的几个位置，以及这套流程的代价。不解决模型选型与成本问题。

Agent 方法论框架 superpowers 怎么划并发派发的准入线

superpowers 把并发准入线定在无共享状态、无先后依赖两条上，同一仓库里却明令禁止并发派实现者。本文顺着它的决策图与技能文件，讲清这条线怎么划、为什么读代码可并发而写代码不行、并发省下的时间在哪一步还回去。不讲安装，也不给通用多 Agent 编排教程。

Agent 方法论框架 superpowers：先问再动手治哪类翻车

拆解 superpowers 仓库里的 brainstorming 技能：它用一条硬门禁把「写代码」挡在「设计被批准」之后，用「一次只问一个问题」逼出真实约束，最后落成一份带自查与人工复核的规格文档。读完你能照着这条轨道搭自己的提问流程。它不解决代码质量，也不替你做技术选型。

Agent 方法论框架 superpowers：请评审与接评审是两套技能

拆解开源项目 superpowers 里请求代码评审和接受代码评审的两份技能文件，讲清它派评审 Agent 时给什么上下文、评审模板强制哪些约束、收到一条你觉得不对的意见时该怎么核查和推回。只讲这个项目的具体做法，不解决评审规则集设计和静态检查工具选型。

Agent 方法论框架 superpowers 的七步工作流拆解

逐步拆开 superpowers 这套编码 Agent 技能框架的七步流程，讲清每一步交出什么文件、下一步凭什么接得住，以及设计闸门、计划自查、任务复审这几道关卡为什么不能跳。也会写明它放弃了什么、哪些场景不适用。不讲安装步骤，不做框架优劣排名。

Agent 方法论框架 superpowers：只给流程，不给新工具

拆解开源项目 superpowers 的构成与生效机制：它不提供新工具，而是在会话启动时注入一份强制性的技能索引，把头脑风暴、写计划、TDD、代码评审串成一条不许跳步的流水线。读完你能判断自己的项目该不该装，以及装了之后哪些环节会明显变慢。它不解决模型能力问题，也不替你选工具。

Agent 方法论框架 superpowers：实现与评审为何隔离

拆解开源项目 superpowers 的 subagent-driven-development 技能：实现者与评审者的提示词为何分开写死，简报、报告、diff 三份文件如何完成交接。读完你能拿到可照搬的角色隔离与修复循环设计，以及它明确不解决的那些问题。

Agent 方法论框架 superpowers 的 TDD 技能拆解

拆解开源项目 superpowers 里的 test-driven-development 技能：它用一条铁律和一份借口对照表把「先写失败测试」变成不可协商的流程，配套文档还规定了什么算好测试。读完你能拿到可直接搬用的验证动作和避坑点，但它不解决框架选型、覆盖率和 CI 搭建。

Agent 方法论框架 superpowers 完成前验证：不跑命令不许说做完

拆解 superpowers 仓库里的 verification-before-completion 技能，讲清它用铁律、五步门函数和两张对照表堵住 Agent 谎报完成的具体做法，以及它在整套技能库里的位置。读完你能照着在自己项目里立同类规则，也能看清它放弃了什么、哪些场景下不划算。

开工前先开隔离工作区：Agent 方法论框架 superpowers 的 worktree 流程与安全检查

拆解开源项目 superpowers 如何把 git worktree 从个人习惯变成流程里的固定动作——开工前的环境检测、征求同意、目录忽略校验、依赖安装与基线测试，收尾时按出身决定清理谁。读完你能照着搭一套自己的开工与收尾约定，也能看清它慢在哪、哪些事它明确不管。

Agent 方法论框架 superpowers 的写计划技能拆解

拆开 superpowers 仓库里 writing-plans 这个技能的三条硬要求——步骤粒度压到 2-5 分钟、每步必须可验证、任务描述要上下文自足，逐条讲清它各自防的是哪种失败，以及配套的计划评审提示词怎么兜底。读完你能照着改自己的计划模板，但它不解决需求从哪来、也不适合小改动。

先复现再找根因：Agent 方法论框架 superpowers 的系统调试流程拆解

拆解开源项目 superpowers 里 systematic-debugging 这套流程：它用一条铁律和四个阶段，把编码 Agent 从换个写法再试试的死循环里拽出来，配套的反向追踪、分层校验、条件等待各自解决什么。读完你能拿到可照搬的流程骨架和五条避坑经验，但它不负责替你写代码，也不会让开发变快。

装错的依赖已经进了仓库：先止血还是先清理，处置顺序怎么排

依赖已经装完、锁文件已改、可能已经跑过一遍 CI，这时候最怕的是顺手就删。这篇给出事故发生后的处置顺序：先划影响面，再按现象判别成因，然后做锁文件与产物的干净回退，说清哪些情况必须当作凭据已泄漏并轮换，以及哪几步是不可逆的。不讲安装之前怎么识破包名。

AI 写的正则把服务卡死：灾难性回溯怎么判、怎么改写、怎么加上限

一条看着人畜无害的正则，能让一个请求把整核 CPU 吃满、线程再也不回来。这篇按现象分因、判别验证、改写手法、兜底上限的顺序讲清灾难性回溯的排查路径，也给出什么时候该停手换实现。不涉及数据库慢查询、GC 抖动、下游超时这类别的性能问题。

AI 写的代码不敢直接上线：五类安全缺陷的自查顺序

AI 生成的代码出安全问题，多数人归因于模型不懂安全，真实原因是它在补全一份缺少约束的上下文。本文按密钥硬编码、输入未校验、依赖来源、权限过大、日志泄漏五类缺陷排出自查顺序，给出每类的判别方法、验证命令和处置动作，也说清哪些问题不该在自查阶段解决。

AI 代码评审工具怎么选：先想清楚你要它管什么

挑 AI 代码评审工具，比拼"谁更聪明"没有意义——各家都拿不出可交叉验证的公开基准。真正能提前判断的是机制差异：评审跑在本地还是 CI、定位精不精准、规则集覆盖哪类问题、模型供应商怎么接、按什么口径计费。本文以阿里开源的 open-code-review 为主线，把这几件事逐条摊开讲。

AI 说文件不存在，可它明明就在那里：四种成因的排查顺序

文件在磁盘上，路径也对，AI 工具却一口咬定读不到。这篇按工作目录不一致、文件名大小写、符号链接被拒、被忽略规则挡住四条线拆开，每条给出判别方法、验证命令和处置动作，并说明什么时候该停手换条路。它不解决检索没命中、上下文装不下这类软失败，那是另一类问题。

AI 改完配置文件服务就起不来了，缩进和环境覆盖到底错在哪

一篇按排查顺序写的配置事故手册。先教你把故障分成语法层、作用域层、取值来源层三类，给出现象与成因的判别表，再给落盘前后的四道护栏、止损与回滚的判断点，以及每条都写清成因的避坑清单。不讲某个具体工具的菜单怎么点，也不替你决定配置管理方案选型。

一句需求换来 30 个文件的改动，AI 的手怎么才能收回来

改动范围失控不是模型不听话，多数时候是任务边界、上下文供给和验收方式三处漏风。这篇按现象分因，给一张判别表定位到底哪一环松了，再给事前约束、事中拦截、事后收敛三段动作，以及该止损回滚的判断线。不解决模型能力问题，也不替你补测试。

AI 把能跑的代码改坏了：先止损再回滚的排查顺序

一套可执行的止损顺序：先固定现场保住可复现的坏状态与可回退的好状态，再按现象分因，然后分离改动定位真正的破坏点，最后决定回滚粒度是整批弃掉、挑拣保留还是只改配置。附现象与成因判别表、止损点判断依据和避坑清单。

AI 工具支出审计：先搞清钱花在哪

团队每月在 AI 工具上花的钱，往往连负责人自己也说不全。这篇给一套可执行的支出审计流程：怎么把清单拉全、怎么把订阅制和按用量两种口径换算到同一把尺上、怎么把钱拆到人和项目、怎么揪出没人用却一直在扣的沉默支出，并以 GitHub Copilot 2026 年转按用量计费后的计量规则为例说明审计口径为什么必须重做。

AI 基础设施选型：网关、工作流、协议层怎么搭

把个人和小团队的 AI 基础设施拆成网关层、工作流层、协议层三块来选型：网关层解决多家模型的统一入口与回退，工作流层解决任务怎么串，协议层解决工具怎么被调用。以开源网关 OmniRoute 为例讲清网关层的落地方式、免费档的真实边界、凭证与合规风险，以及三层之间该怎么划边界、哪些层现在还不值得投入。

AI 评审的规则集：通用大模型为什么容易漏

把 diff 直接丢给通用大模型做代码评审，漏检往往不是模型不够聪明，而是缺了文件筛选、规则匹配、行级定位这层确定性脚手架。这篇拆开 AI 代码评审工具的机制差异，讲清规则集为什么值得单独做，用阿里开源的 open-code-review 走一遍上手路径，并说明厂商自述的性能数字该怎么读。

把 AI 代码评审接进 CI：四个平台的路子

以阿里开源的 open-code-review（ocr）为例，讲清 AI 代码评审工具从本地跑通到接进 CI 的完整顺序：它支持哪四个 CI/代码平台、每个平台各自的接法和卡点、模型供应商与密钥怎么配、厂商自述的性能数字该怎么看，以及接进流水线之后噪音和成本要怎么控。

AI 代码评审的 token 成本：全量审和增量审差很多

AI 代码评审花掉的 token，绝大部分在"送进去多少代码"这一侧，而不是模型吐出来的那几段意见。这篇以阿里开源的 open-code-review（ocr）为例，拆开增量 diff 评审、分支对比、整文件审计三种动作的输入范围差异，讲清全量审被哪三个乘数放大、CI 里最容易漏算的触发次数怎么控、确定性筛选那一层省在哪，以及厂商自述的"省 token"数字该怎么看待。

AI 评审能替代人工评审吗：分层看，别问要不要，要问哪一层

把代码评审拆成机器规则、缺陷模式、设计意图、责任归属四层，逐层判断 AI 评审工具能接管到什么程度。以阿里开源的 open-code-review（ocr）为例讲清它的架构、命令、CI 集成边界，并说明为什么厂商自述的基准数字不能当成选型依据。

AI 评审意见定位不准是怎么回事：位置漂移的成因与应对

AI 代码评审经常出现"意见本身没错，但挂错了行"的情况。这篇拆开位置漂移的三种表现，讲清 diff 有三套行号坐标、模型为什么数不准行、上下文截断怎么把漂移变成漏审，再给出把定位交还给确定性代码的几条做法，以及怎么自己建一套回归集验证准确率。

AI 误删文件或清空了目录，四种情形分别怎么恢复

文件被 AI 删掉之后，能不能救、救到什么程度，取决于它当时处在 git 的哪一层。这篇按「先止血 → 用现象判别情形 → 已提交/已暂存/只在工作区/从未入库分别动手 → 兜底与止损」的顺序给排查路径，也说清哪些情形是真找不回来、只能重建，别再白折腾。

AI 项目的技术债：框架选错的代价比你想的大

多智能体框架选错，还款方式不是"改几个 import"，而是整套编排逻辑重写。这篇讲清 LangGraph / CrewAI / AutoGen 三种架构模型为什么不通约、AutoGen 进入维护模式对选型意味着什么、过期对比表怎么让人做出错误决策，以及一个更省钱的前置判断——很多项目根本不需要多智能体框架。

同一个 bug 让 AI 改了五轮还没好：怎么识别它在原地打转并强行换轨

多轮修不好通常不是模型能力问题，而是你和它共享了一个错的前提，且整轮对话没有新证据进来。这篇按现象分层反推成因，给出判别表、四个换轨动作（换假设、缩范围、要证据、人接手）和明确的止损点与回滚点。它不教你怎么写提问，也不替代最小复现的功夫。

接口超时、连接被重置：什么该重试，什么一重试就烧钱

超时和连接中断的排查顺序：先分清是连不上、请求没发出去，还是回包没回来，再决定重试、降级还是止损。给出现象判别表、重试白名单与黑名单、幂等键的落地写法，以及该换路的判断依据。不讲各家额度与计费口径，也不替代限流专题。

上游接口返回结构一变解析就崩：AI 写的解析代码为什么这么脆

上游返回结构一动，解析层就整片报错。这篇按可执行顺序排查：先分清是字段消失、类型变化、层级搬家还是语义漂移，再用判别表定位成因，然后给出边界解析、契约校验、降级兜底三层动作，最后讲止损与回滚点。不讲上游为什么改、也不替你做业务口径决策。

API 配额怎么规划：按峰值还是按均值

配额规划里最常见的错误，是把"一个月花多少钱"和"这一分钟能发多少请求"当成同一件事来算。这篇拆开金额预算与速率限制两条独立的线，讲清哪条按均值估、哪条必须按峰值留，怎么用真实的分钟级流量分布代替"日均除以天数"，输入输出单价不对称对峰值预算意味着什么，以及余量应该留在哪一层。

账单突然暴涨：怎么从调用日志一层层定位到哪一步在烧

费用一夜翻上去，多半不是有人偷用你的密钥，而是某条链路的单次输入被结构性放大，或失败重试在重复计费。这篇按可执行的顺序讲排查：先把曲线拆成三条分因，再用判别表把现象对上成因，最后给验证动作、止损点和避坑清单。它不负责教你搭日常监控，也不负责稳态降本。

AI 写的测试全绿却拦不住 bug：怎么验证测试本身是真的

测试套件一片绿，线上照样出事。这篇按可执行的顺序排查：先分清断言空转、把被测逻辑 mock 掉、只测 happy path、测试根本没跑这四类假通过，再用故意破坏被测代码的最小动作验测试是否有效，最后给止损点和回滚点。不解决测试设计能力和业务用例本身该覆盖什么。

本地测试全绿一上线就炸：四类差异怎么在上线前逼出来

本地跑得好、线上立刻报错，绝大多数落在数据形态、并发、时区、配置四类差异上。这篇按「三个问题分因 → 判别表对号 → 四组上线前动作 → 止损与回滚」的顺序给你一条可执行路径，也说清它不解决什么：真正的业务逻辑错误、性能容量规划、以及代码本身写错的部分，得靠别的手段。

几千行的单文件总是改不动：为什么整文件重写风险最高，怎么切片改

一个文件长到几千行以后，让 AI 改一处小逻辑经常返回一份"整文件重写版"，看起来漂亮，合并进去就出事。这篇按现象分因、动作、兜底三段排查：先判断你遇到的是定位不准、输出被截断还是模型自作主张，再给切片改写与逐刀验证的做法，最后给止损与回滚判断。不解决架构层面的长期拆分规划。

CI 挂了本地却全绿：先分清环境差异还是代码问题，再决定让 AI 改哪里

面向 CI 红、本地绿这一类断层的排查顺序：先用五类不一致把现象归因，再用判别表验证假设，然后讲清该把哪些失败信息喂给 AI、哪些喂了只会误导它，最后给止损点和避坑清单。本篇不解决测试本身写得对不对，也不替你决定要不要重构。

多个项目同时用 Claude Code，额度怎么分配才不打架

一个账号手里同时压着三五个项目时，Claude Code 的额度该怎么排。讲清额度是按账号算而不是按项目算这个前提、5 小时窗与周限额两层结构对多项目排期意味着什么、怎么用一天的节奏把重活和杂活错开、撞了限额之后有哪些真实可选路径，以及为什么不要把任何假定的重置周期写进自动化脚本。

团队一起用 Claude Code 的几条实践：额度、规则文件与协作纪律

一个团队同时用 Claude Code，麻烦往往不在工具本身，而在额度是按人算的、规则文件没进版本库、并行任务互相踩。这篇按团队真实会遇到的顺序讲清额度结构、CLAUDE.md 的共享方式、并行开工的边界、撞限额时的应对路径，以及必须提前讲明的准入前提。

团队的 Copilot credits 提前烧完了怎么办

月中就把 Copilot 的 AI Credits 烧光、整组人被挡在补全之外，这是 2026-06-01 转按量计费之后的高频事故。这篇给一份应急剧本：当月怎么止血、怎么定位是谁和哪条链路在烧、为什么没有自动降级可指望、额度不结转意味着什么，以及 2026-09-01 促销额度到期前该提前做的准备。

Copilot credits 怎么用才不浪费

Copilot 转按用量计费之后，credits 扣的是 token 不是次数，省额度的着力点也跟着变了。这篇拆解 credits 的消耗结构、四类最常见的隐性浪费、可以立刻上手的削减动作，以及为什么"等额度快没了再降级"这条退路根本不存在。

Agent 转圈卡住不动：先分清网络、索引、工具调用还是在等你确认

IDE 里的 Agent 停住不出字、光标一直转，多数人第一反应是重装或换模型，方向常常是错的。这篇按可执行顺序讲：怎么在半分钟内判断卡在传输、上下文构建、工具执行还是交互等待这四层，每层怎么验证、怎么处置，什么时候该止损回滚换条路。不解决模型答得对不对的问题。

仓库太大塞不进上下文，先别急着换模型：三种切片法和它们的代价

大仓库喂给 AI 编程工具时经常答非所问，多数人第一反应是窗口不够大。这篇按现象分因，给出按依赖、按任务、按接口三种切片方法的具体做法和各自要付的代价，附判别表、止损点和避坑清单。它不解决模型能力本身的问题，也不承诺让百万行代码一次性读完。

AI 改动把已有代码吞了：差异错位与部分应用，落盘前怎么拦

应用模型给的改动时，文件里的原有代码被覆盖、只落了一半、或者格式全变。这篇按现象分因、给判别表，再讲落盘前的四道闸和已经丢了之后的抢救顺序，最后划出止损点。不解决模型本身逻辑改错的问题。

同一个功能，AI 前后生成了三份实现，怎么发现和合并

重复实现不是模型记性差，多半是你没给它检索现有代码的机会。这篇按现象分因，给一张判别表帮你定位重复来自命名漂移、并行会话还是接口分裂，再给发现、合并、收口三段动作，以及该停手回滚的判断线。不解决架构分层问题，也不替你补测试。

DeepSeek 有没有免费额度？先把三个口径分清楚

网页版免费用、API 计费、第三方平台送的体验金，这三件事经常被混成一句"DeepSeek 免费"。这篇按官方定价文档能确认的部分讲清楚：V4 系列单价怎么看、缓存命中为什么能把输入成本砍掉九成以上、想低成本试跑该怎么估算、旧模型名弃用这个坑，以及赠送额度这类说法该怎么求证。

多个会话同时改一个仓库，代码互相覆盖、文件写了却不见了怎么排查

多会话、多 agent 并发改同一个仓库时，最常见的三类事故是互相覆盖、提交漏文件、文件根本没落盘。这篇按现象倒推成因给你一张判别表和排查顺序，再给独占共享文件、显式路径提交、落盘核实三条纪律。它不解决多分支的架构设计，也不替代代码评审。

越聊越忘：长对话被压缩后关键约束丢失该怎么排查

长会话被压缩后，之前说好的约束经常悄悄失效。这篇按先分因后动作的顺序给排查路径：判断是摘要丢失、窗口挤压还是约束表述本身有歧义，再把约束搬到仓库文件与机器检查里，并给出止损点与回滚点。不覆盖仓库整体上下文组织与模型选型。

额度当天就用完了：把手上任务重排，别让一整天停工

额度用尽的那一刻，先要判断到底是真用完了还是限流、鉴权、网络在冒充额度问题。这篇给一张现象与成因的判别表，再讲怎么把当天任务按需不需要强模型重排、四条降级路径各自的代价，以及什么时候该止损换条路。不解决怎么长期压低用量。

AI 又改了锁文件和构建产物：哪些文件必须标记为不可手改

模型手写 lock 文件、快照测试基线、dist 产物和二进制资源，往往不是它不听话，而是仓库没告诉它这些文件是生成物。这篇按现象定位成因、给出仓库层到 CI 层的四层标记动作，并说清什么时候该直接回滚而不是继续修。不解决依赖版本本身该怎么选，也不解决改动范围整体失控。

格式化器和 AI 互相打架：保存就重排，diff 全是噪声怎么定纪律

AI 改了三行，保存后 diff 却有两百行。这篇按可执行顺序拆：先用一张判别表把噪声分成配置不一致、局部重排、双格式化器互斥、版本与 CI 不一致、换行符与编码五类成因，再给收敛动作和已污染提交的补救手法，最后讲什么时候该止损回滚。不解决代码质量本身，也不替代评审。

让 AI 帮你解 git 冲突：哪些能交出去，哪些必须人来判

按「先分因、再动作、最后兜底」的顺序讲清 git 冲突该怎么处置：七类冲突现象各自的成因与验证方法、哪些可以放心交给 AI、哪些必须人拍板，以及解完之后必须做的三步验证。不解决分支拓扑本身被搞乱的问题，那种情况本文给的是止损判断。

改动死活提交不上去：被忽略、子模块、大文件三种情形怎么分

一篇按排查顺序组织的定位手册。先用三条命令把故障点钉在工作区、索引、本地提交还是远端推送这一段，再分别处理被 gitignore 吃掉、落在子模块里、以及大文件被 LFS 或服务端拦下三种成因。给出判别表、处置动作、止损点和避坑清单。不解决代码内容冲突与分支合并策略。

从云版迁到自托管前，先算清这几笔账

Dify、n8n 这类平台的自托管版本没有授权费，但"免费"只是账单的第一行。拆解迁移前该算的四笔账——服务器与运维、模型调用、功能差异、迁移本身的一次性成本，以及什么量级才真的划算。

代码改了却不生效：先别急着清缓存，按四层把改动追到运行现场

改完代码没反应，第一反应通常是清缓存重装，但多数情况根本没到缓存那一步。这篇按「先确认改动在不在跑 → 判别表对号 → 源码、构建、分发、运行时四层依次收敛 → 热更新失效单独排 → 止损与回滚」的顺序走，也说清它不解决什么：环境差异导致的线上报错、多机器行为不一致、以及代码逻辑本身写错。

Grok API 有没有免费额度？先把能核实的和不能核实的分开

围绕"Grok API 免费额度"这个问题给出诚实答案：官方模型页能核到的是一张按 token 计费的价目表，赠金类活动属于随时变动的运营策略，不该写进技术方案。文章拆解免费额度的四种常见含义、教你自己去控制台核实当前状态、按官方单价算一笔小成本试用账，并说明大陆准入这一关为什么比额度更早决定成败。

终端里跑得好好的，双击图标就找不到环境变量：GUI 进程环境继承排查

讲清为什么从图标启动的程序读不到你在 shell 里配的变量。先用现象判型（PATH 没了、版本管理器失效，还是密钥没传进去），再按 macOS、Windows、Linux 三条路给验证命令与补法，最后划出止损点。不解决网络连通与证书问题，也不替代密钥管理方案。

代码回滚了故障还在：迁移、缓存、队列里的旧状态怎么收拾

镜像换回上一个版本，错误率却没降，甚至换了一种错法。本文把回滚拆成五层状态，按先确认代码真回去了、再由现象反推成因、然后迁移缓存队列外部副作用依次动手、最后判断止损点的顺序排查，附一张判别表和一份避坑清单。不覆盖具体数据库产品的恢复操作，也不替代备份与演练。

IDE 或 CLI 内存暴涨到卡死：四个吃内存的地方怎么逐个排掉

编辑器越用越卡、风扇狂转、最后整机换页，多数人第一反应是加内存或换机器。这篇按可执行顺序讲：怎么先量出是索引、长对话、附件还是后台任务在吃内存，每一类怎么验证、怎么处置、怎么兜底，以及什么时候该停手重开而不是继续调。不解决模型答得对不对的问题。

Agent 跑命令跑一半没声了：多半是它在等一个永远不会来的回车

终端命令进了交互态，Agent 就会静静挂死，既不报错也不超时。这篇按可执行顺序讲：怎么在半分钟内自证这条命令是不是在等输入、哪些常见命令会等、每类对应的非交互写法是什么、通用的四种改造手法怎么选，以及什么时候该停手换人工。不解决权限被拒和模型答得对不对的问题。

要 JSON 却给了带包裹的文本，结构化输出不稳怎么治

模型返回的 JSON 时好时坏，多数人第一反应是换模型或改措辞，其实先要分清是解析层、约束层还是任务层的问题。这篇按解析器 → 输出约束 → 任务拆分 → 重试策略 → 兜底降级的顺序排查，给出判别表、重试怎么设、什么时候该止损换路，不解决模型本身的事实准确性问题。

怎么判断一个开源 AI 项目值不值得用：五道关的判断方法

挑开源 AI 项目不该只看 star 数和功能列表。这篇给一套可以照着走的判断方法：先确认你到底需不需要它，再依次过维护状态、架构模型是否匹配你的问题、生产维度的实测口径、你读到的对比结论有没有过期、互操作性这五道关，并用多智能体框架的公开对比资料做实例演示，最后诚实说明这套方法的局限。

流式输出错乱、重复或只吐半截，先别急着怀疑模型

流式回答顺序颠倒、整段重复、末尾缺字，八成不是模型生成有问题，而是客户端拼接、传输缓冲、并发写、上游重放这四层里的一层出了错。这篇按可执行顺序给出分因判别表、验证手法和处置动作，也说清哪些情况该止损换路。它不解决模型内容质量差、也不解决完全断流。

新旧 MCP 版本不兼容怎么办：12 个月弃用窗口怎么用

2026-07-28 的 MCP 新规范是协议发布以来最大的一次修订，新版 server 可能连不上旧版 client，反之亦然。这篇讲清破坏性变更到底改了什么、官方给的 12 个月弃用窗口该怎么排期、双版本并行怎么落地，以及个人用户和团队各自该做哪些动作。

MCP 连不上怎么排查：按这个顺序走六步

MCP server 连不上、连上了却没有工具、昨天还好用今天突然报错？这篇给出一套固定的六步排查顺序：从端点连通、协议版本握手、授权链路、远程路由，到能力清单和 server 本体核对，并结合 2026-07-28 发布的新规范说明哪些故障是这次修订带来的新变量。

同时接十几个 MCP server 会怎样？多 server 管理的真实代价

把十几个 MCP server 一起挂进客户端，最先出问题的不是连不上，而是工具清单变长之后模型选错工具、上下文被占满、故障来源难定位。这篇讲清多 server 场景下真正花钱花时间的几处，并结合 2026-07-28 发布的新规范说明无状态内核、授权加固和版本窗口分别改变了什么，最后给一套可操作的分组与裁剪做法。

MCP Extensions 框架：自己写扩展是怎么回事

2026-07-28 发布的 MCP 新规范把 Extensions 框架列为六块之一，Tasks 也从核心协议挪进了扩展。这篇讲清扩展机制到底改变了什么、官方扩展与自建扩展怎么共存、写扩展前该准备什么，以及新旧版本不兼容和 12 个月弃用窗口该怎么应对。

MCP 工具太多会让模型变笨吗？先分清是数量问题还是描述问题

挂的 MCP 工具一多，模型开始选错工具、绕远路、甚至放着现成工具不用。这篇讲清"变笨"到底发生在哪一步、工具清单每轮要付的上下文成本是怎么回事、怎么自己做一次实验区分数量问题和描述问题，再给几种可落地的裁剪做法，并说明 2026-07-28 新规范在这件事上帮得到和帮不到的地方。

官方 MCP Registry 怎么用：别再到处翻仓库找 server

MCP server 数量已经多到靠 GitHub 收藏夹管不住，官方注册表 registry.modelcontextprotocol.io 就是为解决这件事存在的。这篇讲清它是什么、不是什么，怎么按需求筛 server，2026-07-28 新规范带来的破坏性变更让"版本兼容"成了选型第一关，以及注册表解决不了哪些问题。

MCP server 一启动就退出：进程秒退怎么一层层定位

专门处理 MCP server 连进程都起不来的那一段：先按现象把秒退拆成找不到可执行文件、启动期校验失败、环境不一致、stdout 被污染四类，再给手工复跑、最小环境复现、绝对路径固化的动作顺序，最后给止损点。不涉及工具语义调试和参数设计。

升级到新 MCP 规范前，先过这份检查清单

2026-07-28 发布的 MCP 新规范是协议发布以来最大的一次修订：协议层无状态、Tasks 移出核心变 extension、授权按真实 OAuth 部署加固。这篇按"先盘点再动手"的顺序给出一份升级前检查清单，讲清哪些改动会直接打断新旧互通、12 个月弃用窗口该怎么用。

MCP 生态 2026：捐给 Linux 基金会之后发生了什么

MCP 交给 Linux 基金会下的 Agentic AI Foundation 之后，2026-07-28 发布了官方称为"自协议发布以来最大的一次修订"的新规范——协议层无状态化、Tasks 移出核心、Extensions 框架、授权加固、正式的弃用策略。这篇讲清每一块改了什么、为什么会不兼容、旧版本还有多长的窗口，以及升级该怎么排。

MCP 授权加固：客户端为什么必须校验 iss

2026-07-28 发布的新版 MCP 规范里，授权部分由 6 个 SEP 集中加固，其中一条要求客户端按 RFC 9207 校验授权响应里的 iss 参数（SEP-2468）。这篇讲清楚 iss 校验防的是哪一类攻击、为什么以前"照着 OAuth 库抄"不够、这轮破坏性变更对新旧 client/server 兼容意味着什么，以及升级排期该怎么安排。

MCP server 怎么挑：三条判断标准

公开的 MCP server 已经多到没法靠"看着眼熟"来选。这篇给出三条可执行的判断标准——来源能不能查证、协议版本站在 2026-07-28 新规范的哪一边、部署与授权形态撑不撑得住你的场景，并说清这三条各自管不到哪里。

密钥不小心提交上去了，先撤销还是先清历史，顺序错了等于白忙

密钥进了 Git 之后，真正决定损失大小的是处置顺序而不是清理得干不干净。这篇按吊销、换新、核对注入点、评估影响、最后才动历史的次序拆开讲，给出一张现象到成因的判别表、什么时候该停手不再改写历史的止损线，以及一份避坑清单。不解决如何从一开始就不泄漏，那是另一篇的事。

monorepo 里 AI 老是改错包，怎么把边界和路径说清楚

大仓里 AI 明明说改了 A 包，实际动的是 B 包。本篇按现象分因排查：先判是不是同名文件路径歧义、再判包边界描述缺失、再判构建过滤器与工作区解析对不上，然后给可执行的动作、判别表和止损点。不解决模型本身的推理能力问题，也不解决单仓小项目的上下文不足。

公司内网连不上 AI 编程工具：代理、证书链、DNS 三段排查法

内网环境下 AI 编程工具连不上，多数不是工具坏了，而是代理变量、企业自签证书链、内部 DNS 这三段里有一段没打通。本篇按可执行顺序组织：先用一张判别表把现象归因，再分段处置，最后给止损点、回滚点和避坑清单。不涉及绕过公司网络合规策略的做法。

OmniRoute 跑不起来？按这个顺序查

OmniRoute 装完不通、面板打不开、客户端报错，八成不是软件坏了，而是排查顺序反了。这篇按「进程/端口 → 自检 → 供应商连接 → 模型 ID → 客户端 base_url → 网络准入」六层依次往下剥，说清每一层怎么验证、验证通过意味着什么，以及哪些「不通」其实是免费档的正常表现。

open-code-review 上手：ocr 命令怎么用

阿里开源的 AI 代码评审 CLI open-code-review，装完之后命令名叫 ocr。这篇讲清安装、两条 config 命令怎么配、review / scan / delegate 四种评审模式各自适合什么场景、能接哪些 CI 平台，以及仓库自述的那些性能数字该怎么看待。

OpenRouter 路由失败怎么排查？五层剥洋葱式定位法

OpenRouter 调用失败时该按什么顺序查：先分清连不通、被拒绝、有响应但结果不对这三类现象，再从网络链路、鉴权与 base_url、模型命名空间前缀、余额与免费档限速，一路查到 provider 层的自动 fallback 到底管什么、不管什么，附一份可直接抄的日志字段清单。

OpenRouter 的免费模型能用到什么程度？限速、模型池与适用边界

OpenRouter 提供一档免费模型路由，但"免费"到底能撑住什么样的使用强度？这篇讲清免费档的每日/每分钟限速怎么分级、充值记录如何影响额度、免费池里大多是什么模型、哪些场景真的够用、哪些场景必须换付费档，以及大陆访问这个绕不开的前提。

OpenRouter 上怎么挑性价比模型？一套可复现的比价方法

OpenRouter 上能调的模型有上百个，光看每百万 token 单价挑不出真正划算的那个。这篇讲清楚性价比该怎么算：输入输出价为什么要分开看、充值手续费如何抬高真实单价、免费档适合做什么不适合做什么、代表模型的官方价目怎么读、以及怎么用一批固定样本把"感觉不错"变成可复现的结论。

几万行日志喂给模型总是没结果？先定位再截取而不是给全文

日志上万行时把全文粘给模型，大概率拿到一段听着合理却指错方向的结论。这篇按定位、截取、打包、验证的顺序讲怎么把几万行压到几百行有效上下文，含现象判别表、结构化打包写法和止损判断；不解决日志本身缺关键字段、以及必须靠分布式链路追踪才能还原的跨服务问题。

上下文被污染：一次错误假设留在历史里，后面全跟着错

同一个会话里，模型第一次判断错了，你纠正之后它嘴上认错、动手照旧。这篇按"先分因、再动手、最后兜底"的顺序讲怎么排查：如何用一次新会话对照实验确认是污染而不是遗忘或修复循环，污染的三个等级各自怎么处置，什么时候该直接清场重开。不解决模型本身能力不足和需求没想清楚的问题。

沙箱拒绝执行命令不是故障：不放开全部权限也能把活干完

AI 编程工具突然拒绝执行命令，多数人第一反应是关掉限制。这篇按可执行的顺序拆解：先把交互授权、沙箱硬拒、隔离写入、目录边界、出站拦截、TLS 拦截、凭据与限流七类现象分开，给出各自的验证手段和最小授权改法，再讲什么时候该止损换路。不解决具体产品的配置项写法，也不替你评估公司合规红线。

线上出事故时该不该让 AI 上手：哪几步能交给它，哪几步必须人来

事故期不按能力分工，按可撤销性分工。这篇按实战顺序讲：先给动作分只读、可逆写、不可逆写三类，再用现象与成因判别表缩小假设空间，然后划出交给 AI 的收敛类工作与必须人来的变更类操作，给出止损与回滚的判断依据，最后讲复盘阶段怎么用它。不讲具体产品的操作步骤，也不替你做定责。

生成到一半就断了：输出上限、上下文挤爆、网络中断还是工具超时

一篇按顺序走的排查手册。先教你从断口的长相反推成因，再给判别表把四类「中途停住」分开，然后是对应的处置动作和退避策略，最后写清什么时候该止损回滚、换条路走。它不解决模型答得不好的质量问题，也不替代额度规划。

每人一套规则文件：约定冲突、覆盖顺序不清，怎么收敛成一份

团队里每个人给 AI 编程工具配了自己的规则文件，同一个仓库里产出风格互相打架，谁压谁没人说得清。这篇按「先分因、再动作、再兜底」的顺序排查：怎么判断是真冲突还是根本没生效，怎么把散落的规则收敛成分层的单一来源，以及哪些约定压根不该写进规则文件。不解决模型本身的能力差异，也不替你做团队里的取舍决策。

网关的降级策略：主力模型挂了之后

主力模型不可用的时候，网关到底该做什么。这篇把"挂了"拆成额度耗尽、瞬时故障、供应商长时间不可用、模型下线四类，分别给出该重试还是该切换的判断；再讲降级链怎么按能力对齐来排、以开源网关 OmniRoute 为例配回退时实际要落地的几件事、降级之后应用会以什么方式变怪，以及怎么演练和这套做法的局限。

AI 网关的监控该看哪几个指标？五个维度与一份排障顺序

在网关后面挂了多家模型供应商之后，出问题时最难的不是修，而是分清是谁的锅。这篇把 AI 网关值得长期盯的五个指标拆开讲：按供应商拆的成功率、分首字与整段的延迟、按调用方归因的 token 成本、回退触发率与免费额度消耗、模型可用性与配置漂移，并给出一套从外往里的排障顺序和这套监控解决不了的事。

脚本第一行报错、字符串比不相等、diff 整文件变红：BOM 与换行符的排查

这三类怪现象常被当成语法错误或工具 bug，实际多数是文件开头的 BOM 字节和行尾的 CR 在作怪。本文按现象反推成因，给出用字节层面确认的验证命令、逐层修复动作和仓库级规范化方案，也说清哪些情况根本不该继续折腾、该在什么时候回滚重做。不涉及具体产品的收费与额度规则。

Windows 上文件被占用写不进去：先查谁锁了它，再决定重试还是绕开

一篇按排查顺序组织的 Windows 文件占用定位指南。教你从报错码和现象反推锁源属于哪一类（自己的残留进程、IDE 索引、安全软件瞬时扫描、云盘同步、正在运行的可执行文件），给出查句柄的具体办法、原地覆盖改原子替换的写法，以及什么时候该停手换路。它不解决权限模型配置、也不解决代码逻辑错误。

改完功能接口变慢：重复请求、N+1、全量拉取如何在评审阶段看出来

一篇按排查顺序写的性能退化处置手册。从确认「是不是真变慢」开始，分因判别重复请求、N+1 查询、无谓全量拉取三类高频退化，给出读 diff 时的固定动作、一张现象对成因的判别表、止损与回滚的判断依据，以及避坑清单。不解决架构级容量规划和模型侧质量问题。

AI 随手装的包把版本搞崩了：锁文件、传递依赖与重复安装的排查顺序

依赖冲突大多不是包管理器的毛病，而是锁文件被改坏加上传递依赖被顶版。这篇按现象给判别顺序：先分清直接依赖冲突、传递依赖顶版、同一包重复安装、锁文件与清单脱节四类，再给验证命令和处置动作，最后说清什么时候该回滚止损。不覆盖包名根本不存在的情况，也不讲具体产品的额度规则。

AI 编出来的包名装不上：幽灵依赖的识别顺序与供应链风险

AI 写的 import 装不上，多数人第一反应是改镜像或换版本，方向就错了。这篇按现象给出判别顺序：先分清名字不存在、包存在但函数是编的、网络与证书三类成因，再给验证命令和处置动作，并说明为什么编造包名会变成供应链安全问题。不覆盖具体产品的报错原文与配额规则。

AI 生成的代码只在我机器上能跑：按版本、路径、编码、依赖锁四步定位

一篇按排查顺序组织的环境差异定位指南。先教你从现象反推是版本、路径、编码还是依赖锁出的问题，再给出对应的验证命令和处置动作，最后划出止损点与回滚点。它不解决代码逻辑错误、也不替代评审和技术债治理，只负责把「换台机器就崩」这一类差异提前暴露出来。

装了 nvm/pyenv 之后 AI 工具找不到运行时或用错版本：按 PATH 继承链排查

版本管理器靠改 PATH 和 shim 生效，而 AI 编辑器、CLI 与它拉起的子进程未必读到同一份环境。这篇按顺序拆解：先用工具自己的视角打印出它眼里的运行时，再分清 shell 启动文件、GUI 进程继承、shim 顺序、多管理器叠加四类成因，给出验证命令与处置动作，最后划止损点。不解决包依赖冲突，也不讲产品配置项。

命令输出太长把上下文冲爆，分页器卡住日志刷屏怎么办

终端里跑一条命令，要么半天没反应，要么几千行刷屏把会话挤满。这篇按可执行顺序排查：先分清是分页器在等输入、是输出量真的大、还是缓冲导致的假卡，再给让命令少说话的具体开关、落盘后抽取证据的方法，最后给止损点。不解决模型本身理解代码的能力问题。

中文输出乱码怎么排查：终端代码页、文件编码、重定向落盘逐环节定位

中文乱码不是一个问题，而是三个不同环节的问题：终端显示层、文件本身的字节、重定向落盘时的转码。这篇按现象倒推成因，给出终端代码页、Python/Node 输出编码、管道与重定向三段的判别方法和处置动作，也说明哪些情况不该继续折腾，直接换传输方式。

AI 改完实现没同步注释和文档，怎么把不一致变成可检查的项

实现被 AI 改了、注释和文档还停在上一版，这篇按「先分因、再动作、再兜底」的顺序讲：怎么把四类漂移用现象区分开，怎么用签名对照、示例可执行、锚点引用三层手段把说明变成能被脚本和 CI 判定的东西，以及哪些陈旧说明不值得修、直接删更省事。不解决文档内容本身写得好不好。

AI 编程工具的额度机制横评：时间窗口、credits、按量计费怎么分

同样是"额度用完了"，在不同 AI 编程工具里含义完全不同。这篇把主流工具的计量方式归成三类——按时间窗口重置的配额、按预付信用点扣减的 credits、按 token 实时结算的用量计费——讲清各自怎么扣、扣完会怎样、预算怎么控，并以 GitHub Copilot 2026-06-01 转按量计费为例，拆一遍 credits 制的真实规则。

团队的 AI 编程预算怎么规划：三种计费模型下的算法

把团队 AI 编程支出拆成席位制、订阅含额度制、纯按量制三种计费模型，各给一套可以照着算的预算公式；讲清 GitHub Copilot 2026-06-01 转按用量计费后额度怎么折算、超额预算的四个层级怎么设、9 月促销额度回落这道坎该提前做什么，以及这套算法算不准的地方在哪。

AI 网关怎么选：自建、聚合平台与本地代理的取舍

把 AI 网关的三条路线讲清楚——自己部署开源网关、直接用托管聚合平台、在开发机上跑本地代理，各自解决什么问题、代价在哪、什么规模适合哪一条，并以开源项目 OmniRoute 为例说明本地代理这条路的真实形态与风险。

API 成本怎么监控：等账单出来就晚了

AI API 和 AI 编程工具的费用不是月底才产生的，是每一次请求都在产生。这篇讲清成本监控的三层结构——进程内的 token 记账、平台侧的预算闸门、日频对账与预测，并以 GitHub Copilot 2026 年转按用量计费后的真实计量规则为例，说明为什么"额度用完自动降级"这种想象并不存在。

直连、聚合平台、本地网关：三种 AI API 接入方式怎么选

把调用大模型 API 的三条路摆到一起对比——直接连厂商官方端点、走托管聚合平台、在本机跑一个开源网关（以 MIT 协议的 OmniRoute 为例）。讲清各自的责任边界、密钥交给谁、故障时找谁、什么规模适合哪一条，以及三条路都绕不开的大陆访问现实。

API Key 怎么管才不泄漏：开发者常犯的几个错

API Key 泄漏很少是被"黑"进来的，多数是自己交出去的——硬编码进前端、跟着 commit 进了公开仓库、被日志和报错打印出来、截图发进群里。这篇按真实泄漏路径逐条拆，给出环境变量、分环境分人发 key、提交历史清理、日志脱敏的具体做法，以及把凭证交给第三方工具或本地网关之前该问的三个问题。

API 密钥轮换：什么时候必须换，怎么无缝换

密钥轮换不是"到期换一次"的例行公事，而是分两种场景——已经泄漏的紧急吊销，和没出事时的定期更替，两者做法完全不同。这篇讲清哪些信号出现就必须立刻换、怎么用双密钥并存做到服务不中断、多渠道和网关场景下轮换要额外注意什么，以及轮换之后怎么确认真的换干净了。

API 重试和退避怎么写才不放大故障？

调用大模型 API 时，重试写不好会把小抖动放大成雪崩。这篇讲清哪些错误才值得重试、为什么固定间隔是危险的、指数退避加抖动怎么落地、超时预算和重试配额怎么设，以及网关自带的 fallback 和你自己的重试叠乘之后会发生什么。

Claude API 报错排查：密钥、额度与地区三类

把 Claude API 调不通的原因归到三类——密钥与参数写错、额度与限速被挡、地区准入根本不通。逐类给出定位顺序：怎么看 401 是不是环境变量没读到、429 的 retry-after 和 anthropic-ratelimit-* 头怎么读、模型 ID 拼日期后缀为什么会 400、缓存为什么静默不生效，以及大陆访问的真实前提。

Claude Code 的 5 小时窗到底怎么算？重置时刻、条数区间与实测争议

讲清 Claude Code 五小时滚动窗的计时起点为什么不是整点、周限额按账户固定时刻重置是什么意思、每窗能发多少条为何官方只给区间，以及 2026 年的两次官方调整和一份第三方实测与文档不一致的争议该怎么看。

Claude Code 限额在 2026 年的两次变化：翻倍、重置与那个没对上的重置周期

梳理 2026 年 Claude Code 用量限额发生的两次官方变化——5 月的永久翻倍与取消高峰时段缩减、6 月的一次性额度重置，并讲清 5 小时滚动窗与周限额的真实计时方式、第三方实测与官方文档对不上的重置周期，以及撞限额后哪些路可走、哪条路走不通。

Claude Code 额度用完了怎么办：客服帮不了你

额度耗尽当下最该做的三件事：先用 /status 分清撞的是 5 小时滚动窗还是周限额，再明白客服无法手动重置或延长配额，最后在等待恢复、开 usage credits、转按量付费、升档之间选一条。附 2026 年两次官方调整与一个实测与文档不一致的重置周期提醒。

用 /status 管住 Claude Code 的用量：两层限额怎么看、怎么省

Claude Code 的用量由 5 小时滚动窗和周限额两层构成，/status 是唯一能实时看到剩余额度的入口。这篇讲清两层限额各自的重置逻辑、2026 年官方做过的两次调整、第三方实测与文档不一致的地方，以及撞到上限后有哪些真正有用的路径。

并行子代理烧额度：一个被官方修过的坑

Claude Code 曾出现某些会话派生过多并行子代理、比预期更快烧掉用量的问题，官方在 2026 年 6 月修复后一次性重置了 Pro 与 Max 用户的额度。这篇讲清这个坑的来龙去脉、两层限额到底怎么算、为什么不要把假定的重置周期写进自动化脚本，以及日常怎么用 subagent 才不至于莫名其妙被卡住。

Claude Code 的"周限额"没那么简单：实测与文档不一致

拆解 Claude Code 的两层限额结构：5 小时滚动窗为什么不按整点重置、周限额官方说法是什么、有开发者实测记录到的重置周期为什么和文档对不上，以及撞了限额之后哪些路能走、哪些是白费力气。

Copilot 代码评审的隐藏成本：两个计量表

Copilot code review 不只扣一份账。2026-06-01 起 Copilot 全线转为 AI Credits 按用量计费，年付用户仍走 premium request 制（code review 模型倍率 13），而无论新旧制度，code review 自 2026-06-01 起还会同时消耗 GitHub Actions 分钟数。这篇讲清两个计量表怎么走、额度用完会发生什么、以及 2026-09-01 促销到期前团队该做的事。

Copilot 额度用完会怎样？没有自动降级这件事

GitHub Copilot 在 2026-06-01 改成 AI Credits 按量计费之后，额度用完的后果和很多人想的不一样：不会自动降级到便宜模型，而是直接阻断到下个计费周期。本文讲清 credits 的换算关系、预算的四个层级、Business/Enterprise 促销额度到期这个时间点，以及年付用户为什么还停在老制度上。

Copilot 换计费了：premium requests 变成 AI Credits

GitHub Copilot 从 2026-06-01 起转为按用量计费，用 AI Credits 替代原来的 premium request 计数。这篇讲清 1 credit = 1 美分怎么换算、各档包含多少额度、额度用完会不会自动降级、Business/Enterprise 的促销额度什么时候到期，以及哪些人现在还留在老制度上。

年付 Copilot 还在老计费上：倍率上调了哪些

GitHub Copilot 在 2026-06-01 转为按用量计费（AI Credits），但年付 Pro / Pro+ 用户在计划到期前仍留在旧的 premium request 制上，并且从同一天起模型倍率被上调。这篇讲清两套制度的分界线、年付用户需要盯住的两处变化（code review 倍率 13、额外消耗 Actions 分钟），以及到期切换时该怎么估算预算。

Copilot 团队预算怎么设：四个层级和踩坑点

GitHub Copilot 自 2026-06-01 起转为按用量计费、用 AI Credits 替代 premium request。这篇讲清团队管理员该怎么设预算：user / cost center / enterprise spending limit / organization 四个层级各管什么、$0 预算会直接阻断人、额度耗尽没有自动降级、促销额度 2026-09-01 到期这几个真实踩坑点。

Cursor 学生免费年已经关了：2026 年学生还能怎么低成本用上

Cursor 的学生免费一年 Pro 在 2026 年 6 月 25 日对新申请关闭。讲清已经领过的人会怎样、现在还剩哪些正规路径、中国大陆学生本来就卡在哪一步，以及为什么千万别去买所谓的“学生号”。

DeepSeek API 报 429 怎么办：并发限流不是配额用完

DeepSeek API 返回 429 时，多数人第一反应是"额度花光了"，其实官方标注的是并发上限——deepseek-v4-flash 2500、deepseek-v4-pro 500。这篇讲清并发数和配额的区别、怎么用信号量把在途请求压到阈值以下、退避重试该怎么写，以及哪些"429"其实根本不是限流。

deepseek-chat / deepseek-reasoner 报 404 了？7 月 24 日别名已经下线

DeepSeek 在 2026 年 7 月 24 日正式停用 deepseek-chat 和 deepseek-reasoner 两个模型别名，没有灰度也没有软跳转。讲清该换成哪个名字、reasoner 映射的其实是 Flash 而不是 Pro 这个坑，以及怎么把散落各处的旧名字一次排查干净。

豆包 API 接入常踩的几个坑：从推理接入点到分段计费

把豆包（火山方舟）API 接入过程中最容易卡住的几处集中说清楚——推理接入点这一层为什么绕不过去、model 字段到底填什么、base_url 少一截会怎样、分段计费为什么和别家不是一回事、免费额度能抵扣什么不能抵扣什么，以及一套从外往里剥的排查顺序。

豆包 API 的免费额度怎么看？50 万 token 能跑多少、哪些消费不给抵

把火山方舟送的免费推理额度讲清楚：50 万 token 是一次性还是按月、哪些花销明确不在抵扣范围内（插件、知识库、批量推理、缓存存储费）、选不同模型时同样 50 万 token 的实际价值差多少倍、额度耗尽前该验证什么，以及卡在"没实名"上的常见卡壳。

多模型回退怎么设计：别等主力挂了才想起来

多模型回退不是"配一个备胎"这么简单。这篇讲清回退该在哪一层做、什么信号才算"该切了"、回退链怎么排顺序、切换后上下文和输出格式怎么保证不崩，以及用开源网关 OmniRoute 落地一条链路的具体做法与它的边界。

多账号池化额度：能做，但要先想清楚这几件事

把多个订阅账号轮着用来绕开 Claude Code 的额度上限，技术上不难，难的是它到底能不能省事。这篇拆开讲：为什么"账号数 × 每窗条数"这个算法从一开始就不成立、把重置周期写死进调度脚本为什么是最危险的一步、2026 年两次官方调整暴露了什么，以及在动手池化之前更值得先做的几件事。

接了好几家模型 API，怎么统一封装才不乱？

项目里同时接了多家大模型 API 之后，代码很快会被 if-else 和各家 SDK 撑爆。这篇讲一套可落地的分层封装思路：把模型抽象成配置、只统一最小公共面、把重试降级和用量记账收敛到一处，并说明什么时候直接用 OpenRouter 这类聚合层更划算、什么时候不该自己封装。

Gemini API 接不通？按这个顺序查

把 Gemini API 的报错按"从外往里剥"的顺序排一遍：先看地区准入这一层能不能连通，再看密钥是不是真的被读到、项目权限够不够，然后才是 SDK 包名弃用、模型 ID 写错、免费层被限速，最后讲那个最容易让人莫名其妙开始扣费的计费开关。

GLM API 撞限流怎么办：并发和配额是两回事

智谱 GLM API 返回 429 时，先别急着去充值。这篇拆开并发上限、速率限制、按量计费余额、订阅套餐额度四件事的区别，给出用信号量压在途请求、指数退避重试、免费 Flash 分流、Batch 五折错峰的具体做法，并说明为什么智谱这边不适合"照着数字表算并发"。

GLM API 常见报错排查：密钥、模型名与配额

按"从外往里剥"的顺序排查智谱 GLM API 报错：base_url 填错、ZAI_API_KEY 没读到、模型名一字之差（glm-4-flash-250414 与 glm-4-flashx-250414）、上下文与最大输出超限、配额与限速、订阅套餐额度和按量计费混淆，以及为什么不要照抄网上的错误码解释。

GLM 有哪些免费模型？能用到什么程度

逐个说清智谱 GLM 当前哪几款模型是长期免费的（GLM-4.7-Flash、GLM-4-Flash-250414，以及已下线自动路由的 GLM-4.5-Flash），免费档和"新用户赠送额度"的区别，免费能撑住哪些真实场景、什么时候必须换付费型号。

国产大模型 API 报错横评：哪家的错误信息最有用

报错信息好不好用，决定你排查一个线上问题是十分钟还是一下午。这篇给出一张可自测的六维评分表（状态码是否用对、错误码是否稳定、message 是否指向具体字段、是否给下一步、限速与配额是否分得清、请求 ID 能否追溯），拆解国产平台常见的三类错误信息形态，并用智谱 GLM 的公开文档做一次完整实例演练，最后诚实说明为什么本文不给点名排行榜。

国产大模型 API 免费档横评：能白嫖到什么程度

用一套可复用的六维横评表来比国产大模型的免费档，先讲清"能白嫖到什么程度"取决于哪几条硬边界（上下文、最大输出、限速、是否绑卡、会不会下线），再用已核实到官方文档原文的智谱 GLM 免费 Flash 系列做样本演示怎么填表，其余厂商给自查路径而不替你猜数字。

腾讯混元 API 接不通？按这个顺序排查

混元 API 调不通，多半不是网络问题。按"走哪套体系 → 端点填对没 → 密钥拿错没 → 鉴权头对不对 → 模型名还在不在 → 额度用光没 → 参数语义差异"这个顺序往下剥，能覆盖绝大多数卡住的情况，附 Claude Code 接混元的专项排查。

腾讯混元的免费额度有多少？三套计费口径别搞混

把腾讯混元的免费额度和计费口径拆开讲：官方文档里 100 万 token 共用额度的完整条件、为什么不同渠道给出的数字互相打架、元器的额度为什么不能算进来，以及原生 API、智能体平台套餐、TokenHub 订阅这三套价格体系为什么不能放在一张表里比。

JetBrains 学生包里的 AI 到底给多少？免费边界、申请与续期讲清楚

JetBrains 学生包给的是「全家桶 IDE 长期免费 + AI 额度有限」，不是「AI 免费一年」。讲清 AI Free 档与 30 天 AI Trial 的区别、试用期结束后还剩什么、三种验证方式怎么选、纸质证明为什么不再收、每年续期与毕业后 40% 折扣，以及不在名单里的学生还有哪些路。

Kimi API 的限额怎么看？撞上了怎么处理

Kimi（Moonshot）API 说的"限额"其实是三件不同的事：上下文窗口、速率限流、账户余额与按次计费。这篇讲清各自在哪里看、撞上时分别是什么症状、对应的处理动作是什么，附退避重试写法、缓存与联网搜索计费的注意点，以及模型下线这种"隐形断供"怎么提前防。

Kimi Code CLI 上手：月之暗面的终端编码 Agent 怎么装、怎么登、和 Claude Code 差在哪

Kimi Code 是 Moonshot AI 开源的终端编码 Agent，单二进制不依赖 Node。讲清 macOS/Linux/Windows 的安装命令、OAuth 与 API Key 两种登录方式的取舍，以及它相比 Claude Code 多出来的子代理、视频输入和 ACP 这几处差异。

Kimi API 有没有免费额度？先把口径搞清楚

搜「Kimi API 免费额度」得到的答案为什么互相打架？这篇先拆清「免费」被混用的四种口径——网页版免费、平台赠额、缓存命中低价、工具调用另计费，再说清大陆站与国际站两套账户体系的差别、哪些老教程里的「免费模型」其实已经下线，以及怎么在控制台自己把当前政策核实清楚。

Kiro 学生免费一年：先看你的学校在不在那 11 所里

Kiro Students 给在读学生一年免费 Kiro Pro、每月 1000 credits、不要信用卡，但资格只开放给美加 11 所合作大学并要走 SheerID 验证。讲清这 11 所是哪些、申请三步怎么走、只能验证一次和额度不结转这两条硬限制，以及不在名单里的学生（含全部中国大陆高校）该把时间花在哪。

免费大模型 API 盘点：哪些是真免费，哪些只是试用额度

把"免费大模型 API"拆成长期免费档、新用户赠送额度、订阅套餐三类，用智谱 GLM 已核实到官方文档原文的免费 Flash 系列做样本，讲清怎么判断一个免费额度能不能写进技术方案，以及自己核价的具体流程。

别用模型别名：一次下线就能让线上全挂

模型别名（路由标签、滚动标识）看着省事，本质是厂商随时可以撤掉的一层映射。以 DeepSeek 在 2026 年 7 月 24 日停用 deepseek-chat / deepseek-reasoner 为例，讲清别名下线的杀伤面、模型标识该怎么在工程里收敛管理、迁移时为什么不能顺手升档，以及哪些场景用别名反而合理。

模型路由策略：什么任务该走哪一档

把"用哪个模型"从拍脑袋改成一套可执行的分档规则。按任务的可验证性、上下文长度、失败代价三个维度分出低中高三档，给出网关侧（以开源网关 OmniRoute 为例）的落地做法、auto 自动挑选的适用边界、回退链怎么排、成本怎么核，以及路由策略常见的三个翻车点。

用 OmniRoute 拼一套零成本模型组合：免费供应商怎么接、回退链怎么排

OmniRoute 是一个 MIT 协议的开源 AI 网关，装在本地跑起来后用一个端点接住各家供应商，让 Claude Code、Cursor、Codex 这类工具都指过来。这篇讲怎么用它的免费档拼一条能自动回退的零成本链路：从 npx 起步、加第一个免费供应商、排回退顺序，到什么情况下这条路不适合你。

OmniRoute 上手：一个本地端点接 290+ 供应商，AI IDE 统一走一处配置

OmniRoute 是 MIT 协议的开源 AI 网关，仓库自述一个端点聚合 290+ 供应商、500+ 模型，可让 Claude Code、Cursor、Cline 等工具统一指向 localhost:20128/v1。讲清它怎么装、怎么加供应商、免费档到底怎么回事、auto 路由与模型 ID 怎么写，以及凭证托管和大陆访问这两件必须先想清楚的事。

OpenAI API 常见报错排查顺序：从外往里剥的六层定位法

调 OpenAI API 报错时最忌讳一上来就改业务代码。这篇给出一套固定的排查顺序——网络与地域、鉴权、账单与准入、限速额度、请求参数、响应解析，逐层往里剥，并说明每一层该看什么证据、哪些结论必须回官方文档核对。

OpenRouter 额度怎么管才不超支？充值节奏、免费档限速与路由取舍

OpenRouter 用预充值 credits，钱花在哪、怎么控制是两件事。这篇拆开模型调用费、充值手续费、BYOK 平台费三笔账，讲清最低手续费与一年到期怎么夹住你的充值节奏、免费档的具体限速能干什么、自动 fallback 对成本口径意味着什么，最后给一份不超支的操作清单。

Pi Agent 工具包上手：多供应商 LLM 框架怎么装、怎么构建、能拿来干什么

earendil-works/pi 是 MIT 协议的 AI Agent 工具包，拆成统一 LLM API、Agent 运行时、编码 Agent CLI 三层。讲清它的几种安装与构建方式、三个包各自解决什么问题，以及它在供应链加固和沙箱隔离上具体做了哪几件事。

通义千问 API 报错排查：鉴权、端点、模型名、区域四类

把通义千问（阿里云百炼/DashScope）调用失败的原因归成四类：鉴权链路（API-KEY 没读到、base_url 新旧端点填错、WorkspaceId 缺失）、模型名（经典命名与 Qwen3 新系列并存、抄旧教程写了不存在的代号）、区域与额度（中国内地站与新加坡国际站独立核算、免费额度不覆盖 Batch 与缓存），并给出从外往里剥的排查顺序。

通义千问 API 的免费额度实测能撑多久？90 天与分模型额度池算账

把通义千问（阿里云百炼）新人免费额度掰开算：90 天有效期怎么起算、qwen-max 各 100 万 token 是什么概念、按对话/文档/代码三种用法分别能跑多少次、哪些消费不走免费额度、额度用完后按量付费一天多少钱。

SheerID 学生验证卡在哪一步：国内学生的现实

学生优惠申请失败，多数人以为是材料不合格，其实卡点往往在更早的一步。以 Kiro Students 的 SheerID 验证与 JetBrains 教育包的三条验证路为例，讲清资格名单、一次性验证、年度续期这几个真正决定成败的环节，以及国内学生该把时间花在哪。

硅基流动 API 报错排查：模型名、限速与余额三类问题

SiliconFlow 硅基流动的报错八成不是代码问题。按"从外往里剥"的顺序排查：base_url 有没有指向 api.siliconflow.cn/v1、模型 id 的命名空间前缀有没有写全、免费档模型撞并发被限速、余额与代金券没分清，以及从海外接口迁移过来最容易漏改的地方。

硅基流动的免费额度怎么用才不浪费？三种"免费"的区别与任务分层法

硅基流动上的"免费"其实有三种：¥0 单价的免费档模型、同一模型的免费版/Pro 双档、以及平台不定期发的代金券。分清这三者，再按任务分层把简单活交给免费模型、把复杂活留给付费模型，才是不浪费的用法。

Token 成本优化：比换便宜模型更有效的几招

大部分 token 账单不是被模型单价撑起来的，而是被重复前缀、塞满的上下文和无差别调用旗舰模型撑起来的。这篇按"先量再改"的顺序讲六招可落地的做法：拆账、稳定前缀吃缓存、瘦身上下文、按任务分层路由（含用 OmniRoute 这类开源网关做回退链）、控制输出长度、批处理与应用层缓存，并说清每一招的代价和不适用场景。

自己统计 token 用量：别等厂商账单出来才知道花了多少

厂商账单是滞后的、聚合的、口径不透明的。这篇讲怎么在自己这一侧把 token 用量记下来：从 API 响应的 usage 字段落盘，到网关层统一采集，再到订阅制工具（如按用量计费之后的 GitHub Copilot）该盯哪块面板，以及自己算的数和官方对不上时怎么排查。

文心 API 报错排查：鉴权与模型名两大类

千帆平台上调文心 ERNIE API，绝大多数报错都能归到两类：密钥体系新旧混用导致的鉴权失败，和模型 ID 写错导致的模型不存在。这篇按"网络—鉴权—参数"三层剥洋葱的顺序，讲清两套密钥怎么区分、base_url 该填哪个、模型名从哪儿抄才不会错，以及 OpenAI 兼容层转译带来的非标准报错怎么看。

文心 API 免费额度实测：能撑住什么规模

千帆平台的文心 ERNIE API 到底有没有免费额度？官方计费页并没有列出通用的新人赠送数额，本文先把"免费"这个词拆清楚，再用官方在架的最低价档位算一遍：几块钱能跑多少次对话、多少篇文档，以及批量、缓存、开源自部署这三个能继续压成本的开关。

AI 编程工具学生优惠盘点 2026：哪些还开着，哪些国内学生根本走不通

把 2026 年还在运行的 AI 编程工具学生优惠逐条摆开：Zed 学生计划为什么是目前国内学生最实际的一条、它的验证机制和硬限制是什么、Cursor 的免费年为什么已经关了、Kiro 与 ChatGPT Codex 为什么只对美加学生开放，以及申请前该按什么顺序做决定。

学生优惠为什么总是"仅限美加"：地域限制怎么绕不开

用 Kiro Students 只认美加 11 所合作大学、JetBrains 学生包三选一验证这两个真实规则，讲清 AI 工具学生优惠的地域限制卡在哪一层、为什么换邮箱和找人代验都不成立、身份只能验一次意味着什么，以及不在名单里的国内学生该按什么顺序做决定。

2026 学生优惠全图：哪些还开着、哪些国内能用

把 Zed、JetBrains、Kiro、Cursor、Codex 这几条学生优惠路线摆在一起看：谁还在收新申请、谁按国家卡人、谁对 .edu.cn 邮箱友好、给的到底是 IDE 免费还是 AI 额度免费。附申请前必做的准备、额度够不够用的判断、以及一年到期后会发生什么。

Zed 学生免费一年：国内 .edu.cn 也能过的那条路

Zed 学生计划给在读大学生 12 个月免费 Pro 加每月 $10 token credits，验证走 JetBrains 开源大学域名库而不是 SheerID，.edu.cn 大多可自动通过。讲清申请三步、GitHub 账号满 30 天这类隐藏门槛、$10 额度到底够不够用，以及一年到期后会发生什么。

终端编码 Agent 横评：Claude Code、Codex、Kimi Code 怎么选

三个跑在终端里的编码 Agent 该怎么选？这篇不比"谁更聪明"，而是从额度模型、可预测性、准入前提、退路设计四个真正影响日常使用的维度拆开讲，并给出按人群划分的选型建议和一套双工具兜底方案。

Claude API 怎么接入？密钥申请、SDK 调用、rate limit 一次讲清

手把手讲清 Claude API 怎么接入：从控制台申请密钥、Python 与 TypeScript SDK 最小调用、rate limit 与用量分级机制，再到缓存感知限速的提效点和大陆访问的真实情况，一篇看完能跑通。

Claude API 怎么计费？按 token 算钱、各模型价格、省钱调用法

讲清 Claude API 怎么计费：按 token 分输入输出分别算钱、各模型单价表、月成本怎么估算，以及 prompt caching 倍率、Batch API 五折、选对模型档位这三招省钱调用法，帮你把账算明白。

DeepSeek API 怎么直接调用？OpenAI 兼容端点接入教程

讲清怎么直接调用 DeepSeek 官方 API：申请密钥、OpenAI 兼容端点的 base_url 怎么填、用 openai 官方 SDK 跑通最小示例、模型 id 该用哪个，以及旧模型名弃用时间点要注意什么。

DeepSeek API 多少钱？token 单价、缓存折扣与成本对比

讲清 DeepSeek API 怎么算钱：V4 系列 flash/pro 单价表、中英文定价页币种口径别搞混、缓存命中折扣能砍掉九成多的账单，以及月成本怎么估、官方已经预告的涨价该怎么应对。

豆包 API 怎么接入？火山方舟密钥申请与 SDK 调用

讲清豆包 API 接入火山方舟平台的完整流程：为什么要先建"推理接入点"再拿 API Key、OpenAI 兼容 base_url 怎么用、Python 最小调用怎么写、新用户 50 万 tokens 免费额度怎么领，以及几个新手最容易卡住的坑。

豆包 API 怎么收费？火山方舟 token 单价与省钱用法

讲清豆包 API 在火山方舟上怎么算钱：分段计费怎么读、Seed 全系官方单价与缓存命中价、批量推理五折、方舟转售 DeepSeek/GLM 的价差有多大、Managed Agents 怎么计费，以及月成本怎么估算。

Gemini API 怎么接入？免费额度、密钥获取与区域限制说明

讲清 Gemini API 怎么接入：AI Studio 拿密钥的具体步骤、Python 与 TypeScript SDK（google-genai）最小调用、免费层的真实额度与那个容易踩坑的"账单陷阱"，以及区域限制的诚实现状。

Gemini API 收费吗？免费层额度、付费单价与省钱用法

讲清 Gemini API 收费规则：免费层与付费层的分界线在哪、各主力模型付费单价表、一个月成本怎么估算，以及 context caching、Batch API、选对 Flash 档这几招真正能压低账单的方法。

智谱 GLM API 怎么接入？密钥申请、SDK 调用与免费额度

讲清智谱 GLM API 怎么接入：开放平台注册拿密钥、OpenAI 兼容 base_url 与官方 zhipuai SDK 两种最小调用方式、哪几个 Flash 模型能长期免费用，以及新手常踩的坑。

智谱 GLM API 怎么收费？各模型 token 单价与省钱用法

讲清智谱 GLM API 的计费结构：GLM-5.2/5.1/5/4.7 全系官方单价与缓存命中价、已经改成分段计价这件事、GLM-4.7-Flash 长期免费怎么用、Batch 五折与 Coding Plan 订阅制的区别，以及月成本怎么估。

Grok API 怎么接入？xAI 密钥申请、SDK 与国内访问前提

讲清 Grok API 的接入全流程：从 console.x.ai 注册拿密钥、区分 accounts.x.ai / console.x.ai / api.x.ai / grok.com 四个域名各自的作用、用 OpenAI 兼容 SDK 把 base_url 指向 xAI 做最小调用，再到中国大陆访问的真实前提是什么、不能抱什么幻想。

Grok API 怎么收费？xAI 各模型 token 单价与成本估算

讲清 Grok API 的计费规则：token 计费单位怎么算、grok-4.3 和 grok-4.20 系列各档单价表、旧版 grok-4 系列价格为什么这篇不引用具体数字、专用代码模型 grok-build-0.1 单价、月成本怎么估算，以及省钱要注意哪几个方向。

腾讯混元 API 怎么接入？密钥申请与 SDK 调用

讲清腾讯混元 API 怎么接入：为什么新用户建议先去 TokenHub 而不是老控制台、密钥的两种形态怎么区分、OpenAI 兼容端点怎么调、以及能直接接 Claude Code 的 Anthropic 兼容端点怎么用。

腾讯混元 API 怎么收费？各模型 token 单价与免费额度

讲清腾讯混元 API 怎么算钱：实抓到的模型计费表、主力对话模型 turbos/T1 的价格现状为什么要标"未核实"、免费额度两种官方口径为什么互相矛盾，以及月成本怎么估算。

Kimi / Moonshot API 多少钱？K3、K2.7 等模型 token 单价与省钱用法

Kimi（Moonshot）API 怎么计费？这篇讲清旗舰 kimi-k3 与 kimi-k2.7-code、kimi-k2.6 等模型的单价表（区分缓存命中/未命中）、Batch 六折、大陆站与国际站的域名与币种差异、OpenAI 兼容调用示例，以及月成本怎么估算。

OpenAI API 怎么接入？密钥申请、SDK 调用与国内访问的现实前提

手把手讲清 OpenAI API 怎么接入：从 platform.openai.com 申请密钥、Python 与 TypeScript SDK 用 Responses API 做最小调用、rate limit 与用量分级机制的实际运作方式，再到中国大陆和香港访问的真实前提与三条现实路径分别是什么，一篇看完能跑通也不会白白折腾。

OpenAI API 怎么收费？GPT 各模型 token 单价与月成本估算

讲清 OpenAI API 怎么收费：按 token 分输入输出计价、GPT-5.x 各模型单价表、月成本怎么估算，以及缓存输入、Batch API 半价、选对模型档位这几招省钱法，帮你把账算明白。

OpenRouter API 怎么接入？一个 key 调 GPT/Claude 等上百个模型

讲清 OpenRouter API 怎么接入：它作为海外 LLM 聚合平台的定位、注册拿 key 的步骤、OpenAI 兼容 base_url 与 Python 最小调用、模型命名空间前缀怎么写、免费模型档的限速规则，以及中国大陆访问这件事的真实情况。

OpenRouter 怎么收费？信用金机制、加价与各模型单价

讲清 OpenRouter 的计费逻辑：预充值 credits 机制、官方声明的"不加价"透传规则、真正的收费点在充值手续费而不是模型调用、代表模型的实际单价、BYOK 免费额度两处官方口径的出入，以及月成本怎么估算。

通义千问 Qwen API 怎么接入？百炼平台密钥与 SDK 调用

讲清通义千问 API 怎么接入：阿里云百炼平台开通、拿 DashScope API-KEY、OpenAI 兼容模式的 base_url 该填哪一个、Python 最小调用示例，再到 90 天新人免费额度和几个容易踩的坑。

通义千问 API 多少钱？各模型 token 单价与成本估算

讲清通义千问 API 怎么算钱：阶梯计价规则、qwen3.8-max/qwen3.7-plus 等新主力与经典模型的单价表、上下文缓存命中一折、Batch 五折、90 天新人免费额度只在北京地域，以及月成本怎么估算。

SiliconFlow 硅基流动 API 怎么接入？一个 key 调多个开源模型

讲清 SiliconFlow 硅基流动的聚合平台定位、怎么注册拿 API Key、OpenAI 兼容 base_url 怎么填、Python 最小调用示例里模型 id 为什么要带命名空间，以及免费模型档和常见接入坑。

SiliconFlow 硅基流动怎么收费？各模型单价、免费额度与计费机制

讲清 SiliconFlow 硅基流动的计费机制：按底层模型分别计价、免费档模型怎么挑、充值余额和赠送余额的区别，以及网传"新用户送¥14"为什么不能当成确定事实来写。

百度文心 ERNIE API 怎么接入？千帆平台密钥与 SDK 调用

讲清百度文心 ERNIE API 怎么接入：千帆平台开通、密钥从 AK/SK 迁移到 bce-v3/ALTAK Bearer Token 的现状、OpenAI 兼容 base_url 该填哪个、Python 最小调用示例，再到免费模型选择和几个容易踩的坑。

文心 ERNIE API 多少钱？千帆各模型 token 单价与成本

讲清文心 ERNIE API 怎么算钱：千帆计费单位与在线价、ERNIE 5.1/5.0/4.5 三代模型的单价表、ERNIE 4.5 是否开源免费、免费额度现状，以及月成本怎么估算。

用 AI 7 天从 0 上线一个能收钱的网站

一份可照做的 7 天计划：用 AI 从选题、生成页面、改稿、接支付到买域名部署，把一个网站做到能真实收钱。重实战记录、给明确工具选型与避坑判断。

AI 编程接单实战：普通人怎么用 AI 接外包赚钱

不会写代码也想用 AI 接外包？这篇讲清 ai编程接单的完整路径——在哪接、接什么活、怎么用 AI 提效交付、怎么报价沟通，以及从 0 到第一单的避坑指南。

AI 生成的代码能上生产吗？production 改造经验

AI 写的代码到底能不能直接上线？本文讲清 AI 代码在安全、性能、可维护性上的真实短板，给出一份上生产前的检查清单（review/测试/密钥/错误处理），帮你把 demo 代码改造成能扛真实流量的生产代码。

程序员会不会被 AI 取代？2026 现状分析

AI 取代程序员是真焦虑还是伪命题？本文拆解 AI 能替代的编码部分、替代不了的核心能力，以及程序员该往哪升级，给你一个不贩卖焦虑的理性判断。

AI 编程接单报价表：不同项目该收多少钱

用 AI 编程接单到底该报多少？本文按落地页、小程序、工具、SaaS 四类项目给出报价区间思路、影响因素与避坑指南，帮你定价不踩坑、不内卷。

用 AI 把 Excel 表格工作自动化（给非程序员）

不会写代码也能用 AI 自动化 Excel：让 AI 帮你写公式、生成脚本批处理、清洗合并数据、一键出报表。本文教非程序员怎么把需求说清楚，让 AI 真正替你干活。

这些 AI 工具能做微信小程序吗？真相与替代方案

想用 AI 做微信小程序，却发现大多数 AI 建站工具只产出网页？这篇讲清现状、真正能做小程序的两条路径，以及常见误区，帮你少走弯路。

AI 做微信小程序全流程：从注册到上架

用 AI 做微信小程序，到底要走哪几步？本文按"注册账号→开发者工具→AI 生成代码→真机调试→提审上架"完整跑通一遍，尤其讲清新手最卡的提审上架环节。

仿小红书小程序：用 AI 从 0 复刻热门 App

想用 AI 复刻一个仿小红书小程序练手？本文拆解小红书的核心功能，教你用 AI 生成页面与业务逻辑、接后端数据、再小程序化的完整复刻思路。

用 AI 做问卷/表单工具：从生成到部署

想用 AI 做表单工具，又不想被问卷星、金数据的功能和数据归属卡死？本文带你用 AI 从生成表单、收集填写、存数据，到接后端、上线部署走通全流程，比传统表单工具更灵活可控。

用 AI 做一个 Chrome 浏览器插件实战

不会前端也能用 AI 开发浏览器插件：从 manifest 配置、AI 生成核心逻辑、本地加载调试到上架商店，手把手带你做出第一个能用的 Chrome 扩展，低门槛高成就。

用 AI 做一个微信/Telegram 机器人实战

想用 AI 做机器人却不知从哪下手？这篇从选平台、接大模型到部署上线，带你跑通一个能聊天的微信/Telegram 机器人，并讲清各平台的难易取舍。

用 AI 做一个网页聊天机器人实战

手把手教你用 AI 做聊天机器人：前端聊天界面 + 接大模型 API + 可选挂知识库（RAG），一步步搭一个能答业务问题的网页 bot，新手也能跑通。

用 AI 做数据看板/Dashboard：工具选型与实战

想用 AI 做数据看板又不会写前端？本文讲清 v0、bolt、lovable 三类工具怎么选，从接数据源到生成图表、部署上线的完整路径，并给出适合做内部 Dashboard 的实战建议。

用 bolt.new 做一个全栈工具站实战

手把手用 bolt 做工具站：从一句话生成全栈项目、在线运行调试、连 GitHub 到一键部署，并给出省 token 的实操技巧，适合想快速上线在线小工具的人。

用 Lovable 做一个管理后台/Admin 系统实战

手把手用 Lovable 做管理后台：从需求拆解、写提示词、生成 CRUD 界面、接 Supabase 真实数据到部署上线，并讲清它适合做哪类内部系统、哪些坑要避开。

用 Lovable 做一个 SaaS 产品（接支付）实战

手把手用 lovable 做saas：从生成应用、加登录、接 Stripe 订阅支付到部署上线，外加省积分技巧，带你把一个 AI 原型变成真正能收钱的产品。

用 Replit Agent 做待办/记账小工具实战

不装环境、不配服务器，用自然语言让 Replit Agent 帮你做一个能用的待办或记账小工具。本文带你从开项目到一键部署跑通全流程，并说清费用和避坑要点。

用 v0 做企业落地页/Dashboard 实战

手把手教你用 v0 做落地页和后台 Dashboard：从提示词或截图生成页面、迭代调整样式、导出代码一键部署到 Vercel，讲清它适合谁、不适合谁，少走弯路。

AI 编程工具订阅怎么选？个人 vs 团队成本对比与决策

AI 编程工具订阅怎么选才不浪费钱？本文讲清个人版与团队/企业版的计费逻辑、按席位付费的隐性成本，并给出独立开发者、小团队、企业三类场景的决策表与判断口诀。

AI 编程工具怎么选套餐？按用量估算成本的方法

不知道 AI 编程工具该买订阅制还是 API 按量付费？本文教你先评估自己的日均用量，再按轻度/中度/重度分档，给出一套可复用的成本估算思路，帮你选对套餐不踩坑。

AI 编程工具怎么选？一套通用选型框架

AI 编程工具太多挑花眼？这篇给你一套不依赖年度榜单的通用选型框架：按工具形态、使用人群、预算三步拆解，附决策树，帮你快速锁定最适合自己的那一款。

主流 AI 编程工具怎么接 DeepSeek？横向配置汇总

Cursor、Claude Code、Codex、Cline 各自怎么接入 DeepSeek？本文一篇讲清四款工具的接法、共性原理（OpenAI/Anthropic 兼容端点）和对比表，附排查清单，省钱又国产合规。

AI 建站工具横评：v0/bolt/lovable/replit 怎么选

ai建站工具对比实测：v0、bolt、lovable、replit 四款主流 AI 建站工具在定位、后端、部署、计费上的关键差别，按"做什么选什么"给出明确选型结论。

AI 设计稿转代码哪个工具强？多模态对比

把 Figma 设计稿或一张截图直接喂给 AI 生成前端代码，到底哪个工具还原度高、代码可编辑？本文横评 v0、Cursor、Trae 等多模态工具的设计转代码能力，给出按场景的选型结论。

用本地大模型跑 AI 编程：Ollama + 各工具接入教程

想在本地跑 AI 编程、把代码留在自己机器上？本文讲清 Ollama 拉代码模型、暴露 OpenAI 兼容端口，再接 Cursor、Cline、Continue 的完整配置，以及显存、速度与效果取舍。

bolt.new 怎么用？全栈应用一句话生成实战

bolt.new 怎么用？本文带你从打开浏览器开始，用一句话生成可运行的全栈应用、连 GitHub、一键部署，并讲清 token 怎么省、Plan 模式怎么用，新手少踩坑。

bolt vs lovable 哪个做全栈更好

bolt 和 lovable 都能用 AI 一句话生成全栈应用，但跑代码的方式、后端体系和适合的场景完全不同。本文分维度拆清两者差别，给出分场景选型结论，帮你少走弯路。

Claude Code 装不上、连不上怎么办？安装报错全排查

Claude Code 安装失败、连不上、命令找不到怎么解决？本文按 Node 版本、安装方式、网络代理、权限、自检五个环节系统排查，给可复制的命令和验证方法，长青不过时。

Claude Code 撞到用量限制怎么办？计费与额度说明

讲清 Claude Code 订阅额度与 API 按量两种计费的底层逻辑、撞到限额时的判断与应对，以及用错峰和精简上下文省额度的实操方法，让你不再莫名其妙被"卡住"。

给 Claude Code 一键接国产模型的懒人方案

claude code 接国产模型嫌手动改环境变量太麻烦？这篇讲一键切换的原理、用中转脚本和 shell alias 封装的懒人方案，以及多模型配置怎么管，照着配一次以后一行命令切换。

Claude Code Hooks 实战：在动作前后插自动化

手把手讲清 Claude Code Hooks 怎么用：在工具调用前后触发脚本，PreToolUse 拦危险命令、PostToolUse 自动跑格式化与 lint，附 settings.json 配置示例和常见排查。

Claude Code 接入 DeepSeek / Kimi / GLM：国产大模型配置教程

教你用环境变量把 Claude Code 的后端换成 DeepSeek、Kimi、GLM 等国产大模型，省钱又稳定。含通用三步配置、各家端点说明、验证方法与常见报错排查。

Claude Code 的 MCP 连不上、配置不生效怎么排查

Claude Code 配好 MCP 却连不上、用 /mcp 显示 failed？本文从配置文件位置、stdio 与 SSE 区别、Node/npx 路径、权限四个根因，给出一套可复制的排查清单，把 MCP 报错一步步定位掉。

Claude Code Plan 模式：省 token 的规划式编程

claude code plan 模式让 AI 先只读规划、审完计划再动手，避免乱改文件、节省 token。本文讲清它的原理、什么时候用、怎么进入与退出，以及常见坑。

Claude Code 上下文管理：/compact 与 /context 怎么用

讲清 Claude Code 的上下文窗口是怎么被吃满的，以及 /context、/compact、/clear 三个命令分别在什么时候用，帮你跑长任务时既省 token 又不让 AI 失忆。

Claude Code Skills 从零创建 SKILL.md 教程

手把手教你给 Claude Code 写第一个 Skill：SKILL.md 的 frontmatter 怎么填、渐进式加载怎么触发、和 subagent/command 有什么区别，附目录结构与排查清单。

Claude Code 自定义斜杠命令怎么写（含传参）

手把手教你写 Claude Code 斜杠命令：在 .claude/commands 放一个 markdown 文件就成了一个 /命令，再讲清 $1 $2 $ARGUMENTS 三种传参、项目级与用户级作用域差别，附常用命令模板。

Claude Code 自定义 Subagent 怎么写

手把手讲清 Claude Code subagent 写法：它是什么、放哪个目录、description/tools/model 怎么配、系统提示怎么写，以及什么时候该用 subagent 隔离上下文、并行跑任务。

Claude Code vs Codex：两大终端 AI 编程代理怎么选

Claude Code 和 Codex 都是在终端里干活的 AI 编程代理。本文从模型生态、审批与交互、扩展性、价格和中文支持五个维度实测对比，并按工作流和任务类型给出明确选型建议。

Claude Code vs GitHub Copilot 怎么选

claude code vs copilot 谁更适合你？从工作方式、改动质量、扩展性、生态、价格五个维度对比，给出分场景选型结论，帮你少走弯路、把钱花在刀刃上。

Claude Code 在 Windows 怎么装？原生 vs WSL 报错排查

Windows 上装 Claude Code 有原生和 WSL 两条路，本文讲清两种方式的取舍、Node/PATH/PowerShell 执行策略配置，以及路径分隔、git bash 等高频报错的排查解法。

Claude Code 配 git worktree 并行多开实战

用 git worktree 给 Claude Code 开多个隔离工作区，多终端各跑一个任务互不干扰。本文讲清原理、创建与清理的完整命令、踩坑排查，让你的 AI 编程效率翻倍。

CLAUDE.md 怎么写？给 AI 立项目规则

CLAUDE.md 是放在项目里给 AI 编程助手看的"项目说明书"。本文讲清它的作用、怎么用 /init 自动生成、该写什么、不该写什么，以及和 Codex AGENTS.md 的关系，附可复制模板。

腾讯 CodeBuddy 怎么用？Craft 模式一句话生成应用

CodeBuddy 教程：手把手讲腾讯 AI 编程助手的安装、Craft 自然语言生成应用的用法、与微信小程序生态的衔接，以及新手最容易踩的坑，看完就能上手做出第一个前端。

Codex CLI 安装失败、连不上怎么解决？排查全流程

Codex CLI 装不上、报错、连不上服务器？本文按 Node 版本、npm 权限、网络代理、卸载重装四个环节给你一套可复制的排查命令，从安装到验证一次跑通。

Codex 登录失败怎么解决？ChatGPT 账号与 API Key 排查

Codex 登录认证失败是新手最常踩的坑。本文讲清两种认证方式的区别、浏览器回调失败、API Key 配置位置、套餐没含额度等高频原因，给出可复制的排查步骤。

Codex 用量与计费：ChatGPT 套餐里的额度怎么算

讲清 Codex 的两套计费逻辑——ChatGPT 套餐内含额度走速率限制窗口、API key 按量计费走 token，以及怎么查用量、额度耗尽怎么办，帮你把账算明白不踩坑。

Codex 怎么用？从安装到跑通第一个任务的全流程教程

OpenAI Codex 是在终端里干活的 AI 编程代理。本文带你从安装、登录、审批模式到用 AGENTS.md 配置项目规则，一步步上手 Codex 并跑通第一个真实任务，附新手常见坑与答疑。

Codex 接入 DeepSeek 等国产模型配置教程

Codex 默认绑 OpenAI，想换成 DeepSeek 等国产模型省钱又稳定？本文讲清兼容端点的原理、配置文件改 provider 与 base_url 的通用步骤、效果取舍和常见报错排查。

Codex vs Cursor：终端 Agent 还是 IDE 怎么选

Codex 是终端里的自动化代理，Cursor 是边写边改的 AI 编辑器。这篇从交互方式、适用任务、生态价格逐项对比，给出分场景选型结论，并讲清两者怎么搭配用。

Codex 接入 Kimi、GLM 等兼容 API 模型怎么配

想给 Codex 换上 Kimi、GLM 等国产模型省钱又长上下文？本文讲清自定义 provider 的接入原理、配置文件改法、各家 base_url 与模型标识填法，以及连不上时的排查清单。

Context7 MCP 实战：消除 AI 编程的 API 幻觉

AI 写代码总瞎编方法名、用过时 API？Context7 MCP 给大模型实时灌最新库文档。本文讲清它的原理、在 Cursor/Claude Code 的安装配置与真实用法。

GitHub Copilot Agent Mode 实战：自主多文件改代码

Copilot Agent Mode 怎么用？本文讲清 Agent 模式与 Edits 的区别、在 VS Code 里如何开启、自主跨文件改代码与跑命令自我修正的完整流程，以及 premium request 怎么省。

GitHub Copilot 的 @workspace/@terminal 参与者怎么用

讲清 Copilot Chat 里 @workspace、@terminal、@vscode 三个参与者的区别和用法，教你什么时候该用哪个、怎么给精准上下文，让 AI 真正读懂你的整个项目。

GitHub Copilot CLI 怎么用？终端里的 AI 编程

GitHub Copilot CLI 教程，手把手教你在终端安装、登录并让 AI 解释命令、改代码、跑任务，讲清它和 IDE 版 Copilot 的区别和适用场景。

给 GitHub Issue 分配 @copilot 自动写 PR

GitHub Copilot coding agent 能接管整个 Issue：你把任务派给 @copilot，它自己开分支、写代码、提 PR。本文讲清它怎么工作、怎么开通、适合什么任务、有哪些坑。

GitHub Copilot Edits 多文件编辑会话实战

copilot edits 多文件编辑怎么用？本文讲清如何建工作集、跨文件批量改、逐条接受 diff，以及它和 Agent 模式的本质区别，帮你掌控 AI 改代码的节奏。

GitHub Copilot 怎么切换 Claude、Gemini 等模型

手把手讲清 GitHub Copilot 模型选择：在 Copilot Chat 里切换 Claude、Gemini、GPT 等模型的入口、各套餐可用模型差异、premium request 怎么算、企业策略限制与切换失败排查。

学生、教师、开源维护者怎么免费用 GitHub Copilot Pro

copilot pro 免费的三条正路：学生认证、教师认证、开源 maintainer 资格。一文讲清谁有资格、怎么申请、被拒怎么排查，长期保住资格的关键。

GitHub Copilot 报「error generating response」怎么修

GitHub Copilot 聊天报 error generating response 多半是网络代理、额度用尽或登录态失效。这篇按机制拆解六类原因，给可复制的排查清单，让你快速定位并修好。

GitHub Copilot 五档套餐怎么选？含「高级请求」额度说明

GitHub Copilot 套餐对比指南：讲清 Free、Pro、Pro+、Business、Enterprise 五档的核心差别与适合人群，并解释「高级请求（premium request）」额度怎么算、用超了会怎样，帮你按场景选对档位。

Cursor Background Agent 后台异步代理配置全解

讲清 Cursor Background Agent 是什么、和本地 Agent 有何区别，以及如何用 environment.json 配置云端环境、跑通后台异步任务，并给出常见坑的排查思路。

Cursor BugBot 自动 PR 代码审查怎么用

Cursor BugBot 是什么、怎么开、怎么在 GitHub PR 里读它的审查评论、怎么用「Fix in Cursor」一键跳回修复。一篇讲清团队用 BugBot 兜底代码质量的完整用法。

Cursor 补全不工作、AI 没反应怎么办

Cursor 代码补全突然不弹、AI 对话无响应？本文按"先看状态栏→排账号网络→查隐私模式与插件冲突→重登重启"的顺序，给一套可复制的排查清单，帮你快速定位卡在哪一环。

Cursor 的 @ 上下文引用全解（@codebase/@web/@docs）

cursor @符号用法一篇讲透：@codebase 喂全库、@web 联网查、@docs 拉文档、@file/@folder/@git/@terminal 各管什么。学会精准喂上下文，AI 回答立刻更准。

Cursor 接 DeepSeek 报 reasoning_content 缺失错误怎么解决

Cursor 接入 DeepSeek 推理模型时报 reasoning_content 缺失、解析失败？本文讲清推理模型返回格式与 OpenAI 兼容协议的冲突原理，给出换非推理模型、走中转代理、核对 base url 与模型名等可落地排查步骤。

Cursor 快速请求用完了怎么办？慢速池与省额度攻略

Cursor 额度用完不等于不能用——本文讲清快速请求与慢速池的机制、用完后的真实体验，并给出 5 类可复制的省额度技巧，让你的每月额度多撑一倍。

Cursor 国产平替盘点：封号、太贵用什么替代

Cursor 封号、订阅太贵想换国产工具？本文盘点 Trae、CodeBuddy、文心快码 Comate、Cline+国产模型四套方案，对比价格、模型、IDE 与中文体验，按需求帮你选对替代品。

Cursor 接入 DeepSeek 等国产模型配置教程

手把手教你在 Cursor 里接入 DeepSeek 等国产模型：自定义模型、填 OpenAI 兼容 Base URL 与 API Key、Verify 验证，以及补全与对话为什么不一样、配不通怎么排查。

Cursor Notepads 怎么用？可复用的上下文文档

讲清 Cursor Notepads 的定位、用法和与 .cursorrules 的区别，教你把常用规范、API 说明沉淀成可 @ 引用的上下文文档，让团队反复复用、少打重复字。

Cursor 从 .cursorrules 迁移到 .cursor/rules：四种 Rule Type 怎么用

老的 .cursorrules 正在被渐渐弃用，Cursor 主推 .cursor/rules 下的 .mdc 规则文件。本文讲清四种 Rule Type（Always / Auto Attached / Agent Requested / Manual）的区别、写法和拆分规则的最佳实践。

Cursor Rules 最佳实践：怎么写 AI 才听话

cursor rules 最佳实践全解——规则要短、要拆小、按需调用、用 glob 自动挂载。讲清 .cursor/rules 结构、写什么不写什么、给出可复制范例，让 Cursor 真正照你的规矩干活。

Cursor 代码库索引卡住、失败怎么解决

Cursor 索引失败、卡在 Indexing 不动、Codebase 同步报错？本文讲清索引机制，给出禁用 HTTP2、Resync Index、清缓存、用 .cursorignore 瘦身、大仓库分批等可复制的排查步骤。

Cursor Tab 跨文件智能补全与重构技巧

讲透 Cursor Tab 的预测式补全机制：怎么用连续 Tab 跨文件同步改、批量重命名与改函数签名，和普通自动补全有什么区别，以及什么时候该把它关掉。

Cursor vs GitHub Copilot 谁更适合你

Cursor 是 AI 原生编辑器，Copilot 是插进现有 IDE 的补全插件。本文从交互、模型、补全质量、价格、上手成本六个维度讲清两者差别，并按"重度 AI 编码 vs 已有 IDE 习惯"分场景给出明确选择。

Cursor 怎么接入任意第三方模型？自定义模型配置

Cursor 自定义模型怎么配？本文讲清在 Models 面板加自定义模型名、填 OpenAI 兼容 base url 和 key 的完整步骤，以及只对对话生效、不影响补全的注意点和切换排查方法。

.cursorignore 怎么写？缩小索引、省 Token、保护敏感文件

手把手讲清 .cursorignore 的语法、写法和实战模板：排除 node_modules/dist/build 缩小索引，保护 .env 密钥不被上传，以及它和 .cursorindexingignore 的区别。

GitHub Copilot 中文实战：安装、配置到高效用法

一篇讲透 GitHub Copilot 的中文教程：在主流 IDE 里安装补全、用好 Chat 与 Agent 模式、写 copilot-instructions.md 定制规则，附中文提问技巧、适合谁，以及和 Cursor 的区别。

什么是规格驱动开发 SDD？AI 时代的工程新范式

规格驱动开发（SDD）是先写清规格、再让 AI 实现的开发方法。本文讲透它的定义、工作流程、与 Vibe Coding 的区别，以及为什么它能显著提升 AI 编程的质量。

国产 AI 编程工具对比：Trae vs CodeBuddy vs 文心快码

国产ai编程工具对比怎么选？本文横向拆解 Trae、CodeBuddy、文心快码三款主流国产 AI 编程工具的出品方、模型、IDE 形态、中文能力与特色模式，按你的真实场景给出明确选型建议。

国内怎么付费订阅海外 AI 编程工具？虚拟卡与避坑攻略

国内信用卡刷不动海外 AI 工具？本文讲清付费订阅的底层逻辑、虚拟信用卡充值流程、拒付与封号风险，以及一份能少走弯路的合规避坑清单。

IDEA/JetBrains 装 Copilot 一直转圈、连接超时、授权失败怎么解

idea copilot 报错怎么排查？本文讲清登录转圈、连接超时、授权失败的真正原因，从网络代理、版本匹配、重新授权到证书与缓存，给一套可复制的排查顺序。

lovable 怎么用？中文全流程从提示词到上线

lovable 怎么用一篇讲透：从写第一句提示词，到生成全栈应用、接 Supabase 后端、一键部署上线的完整中文流程，附省积分技巧和新手避坑，让不会写代码的人也能做出能跑的产品原型。

Claude Code / Cursor 通用 MCP 配置教程

一篇讲清 MCP 配置文件放哪、stdio 与 SSE 两种连接怎么填、命令参数和环境变量怎么写，并带你装一个示例 server、验证连接成功的实操教程，Claude Code 和 Cursor 通用。

开发者必装的几个 MCP 推荐：装这几个就够

MCP 推荐别贪多，装太多反而烧 token、拖慢响应。这篇盘点查文档、浏览器测试、代码托管、深度思考等几类高频 MCP，给出必装清单和按需求的取舍判断。

Playwright MCP 让 AI 自动写 E2E 测试

Playwright MCP 是什么、怎么装、怎么让 AI 控制浏览器自动点页面、写 E2E 测试、复现 bug。一篇讲清前端测试自动化的接入与避坑。

Replit Agent 怎么用？从建应用到部署上线全流程

一篇讲清 Replit Agent 怎么用：用自然语言描述需求，让云端 IDE 帮你建应用、改代码、一键部署上线。适合零环境快速做原型，含计费注意事项与避坑指南。

什么是上下文工程 Context Engineering？

一文讲清上下文工程是什么、和提示词工程有什么区别，以及在 AI 编程里怎么把规则、检索、记忆、工具组织成喂给模型的完整上下文，让 AI 真正干对活。

GitHub Spec Kit 实战：规范→计划→任务→实现

spec kit 教程：手把手讲清 GitHub Spec Kit 的 specify、plan、tasks、implement 四阶段怎么用，配合 Claude Code、Cursor 把复杂功能从规范一路落到代码，附上手步骤与避坑。

Trae 怎么接自定义、中转 API？通过 Cline 插件配置

Trae 原生不支持改 Base URL，想接自定义模型或中转 API 怎么办？本文讲清原理，手把手教你在 Trae 里装 Cline 插件、配 OpenAI 兼容端点和 key，并附排查清单。

Trae vs Cursor 怎么选？5 维度实测对比

trae 对比 cursor 到底选哪个？从价格、模型、IDE 体验、中文支持、短板五个维度拆开讲，并按你的真实场景给出明确推荐，帮你少走弯路一次选对 AI 编程工具。

v0 怎么用？从提示词到页面（v0.app 新版）

v0 怎么用？这篇手把手带你从一句提示词或一张截图，生成可用的 React/Next.js 页面，再导出代码、部署上线，并讲清它和 Bolt、Lovable 的取舍与新手常见坑。

v0 vs bolt vs lovable：AI 建站工具怎么选

v0 vs bolt vs lovable 三款 AI 建站工具到底怎么选？本文按定位、能力边界、适合人群拆解三者差别，给出分场景推荐表，帮你做什么选什么，不绕弯子。

从 Vibe Coding 到工程化：AI 编程怎么避免翻车

Vibe Coding 上手快但容易失控，本文讲清它翻车的三大根因，并给出写规格、立规则、加测试、管上下文四步工程化解法，帮你把 AI 编程从玩具用成生产力。

文心快码 Comate 怎么用？安装配置与核心功能实战

文心快码 comate 教程：从 VSCode/JetBrains 插件安装、代码补全、AI 对话到 Zulu 智能体模式一步步带你跑通，讲清它对中文和国产模型友好在哪、适合谁，附常见坑排查。

AI 编程提示词怎么写？10 个实用技巧

想让 AI 写出更好的代码，提示词是关键。本文给出 10 个实用的 AI 编程提示词技巧，涵盖给上下文、分步、给示例、加约束、让它先说方案等，每条一句要点加一句说明。

AI 编程学习路线：从 0 到做出产品

一条阶段化的 AI 编程学习路线，从认知、工具上手、第一个项目，到工程化与进阶，每个阶段讲清该学什么、做什么，帮你从零一步步走到能独立做出产品。

不会编程，怎么用 AI 写代码？零基础起步路径

不会写代码也能用 AI 工具做出东西。本文讲零基础的人如何靠 Cursor、Claude Code 等用自然语言开发，重点是学会提需求、验证结果、不断迭代，并给一条最小起步路径。

Claude Code 使用教程：在终端里让 AI 帮你写代码

Claude Code 是运行在终端里的 AI 编程代理。本文讲清它的定位、适合什么人、典型工作流（描述任务→读写文件跑命令→你审阅），以及和编辑器派工具的差异。

Cursor 怎么用？从安装到写出第一个项目的保姆级教程

Cursor 是火爆的 AI 代码编辑器。本文从安装、对话生成、Tab 补全、Composer 多文件改动到 @ 引用上下文，带新手一步步上手 Cursor 并避开常见坑。

通义灵码使用教程：国产 AI 编程助手怎么用

通义灵码是阿里推出的国产 AI 编程助手，以 IDE 插件形式提供代码补全与对话。本文讲清它的定位、用法、适用场景，以及国内开发者使用的可用性优势。

Trae 使用教程：上手字节的 AI 编程工具

Trae 是字节跳动推出的 AI 原生 IDE。本文介绍 AI 原生编辑器的定位、对新手友好在哪、典型用法与上手建议，帮你快速判断它适不适合自己。

Vibe Coding 是什么？普通人怎么开始

Vibe Coding 指用自然语言"凭感觉"让 AI 生成并迭代代码。本文讲清这个概念、它适合与不适合的场景、一个可上手的流程，以及普通人最容易踩的坑。

用 AI 从 0 做一个个人网站（实战）

手把手用 AI 从零做出个人网站：选工具、描述需求、生成页面、调整细节、部署上线。结合 v0 与 Bolt 的实战流程，适合零基础也想拥有自己网站的人。