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

一个按钮四种意思：CC Switch 的供应商主按钮

CC Switch 的供应商操作区只有一个主按钮，但它在不同被托管应用下分别代表切换、加入原生配置、加入故障转移队列三种完全不同的动作。本文按 v3.20.1 快照拆开 ProviderActions.tsx 的状态机，讲清优先级链、缺回调时的语义合并，以及禁用按钮为什么解释不了自己。

CC Switch 的共享凭据文件没身份标记会怎样

一个「model not found」的报错，倒推回去落在 ~/.codex/auth.json 只有一个凭据槽位、槽位上没写归属这件事。本文顺着 v3.20.1 的三条修复，讲清共享可变状态缺少所有权标记会长出什么形状的问题，以及 reconcileCodexLiveAuth 用什么办法绕开它。

CC Switch 的预设怎么决定表单长什么样：四个开关

同一个供应商表单，选不同预设时渲染出来的输入框集合完全不同。本文按 v3.20.1 源码拆开这套机制：category、templateValues、providerType、apiFormat 四条互不干涉的判定路径分别控住哪几块，以及「没渲染的字段保存时也不写进 meta」是怎么逐个 case 兑现的。

CC Switch 点两下就并发跑了两个安装

升级按钮被连点两下，会不会真的并发跑起来两个全局安装？这篇按 CC Switch v3.20.1 的源码，把探测阶段等三个并发窗口、堵住它们的那把入口锁、以及检测到多处安装时的知情确认对话框逐层拆开，并给出「怎么判定是这个原因、处置后怎么验证、哪些情况说明根本不是它」的完整排查链路。

不猜是一种功能：CC Switch 的自定义配置取舍

配置工具要不要替用户推断模型能力，CC Switch 管理 Pi 的这条路径给了否定答案，写成「预设完整可靠、自定义配置不猜测」的原则。本文顺着 v3.20.1 的需求文档与源码，拆开这条原则落到能力字段、空值语义、表单规则与界面取舍上的具体形态，也说清它的代价落在了谁身上。

CC Switch 切到第三方，Codex 仍显示官方账号是不是串账了

切走第三方供应商后客户端仍显示官方账号，是不是把账单记到官方头上了？这篇按 CC Switch v3.20.1 的仓库文档与源码，拆开 auth.json 与 config.toml 的职责分离、代理层那段账号一致性校验的判据与三态设计，并给出逐步的判定动作和「不是这个原因」的排除清单。

CC Switch 绑多个官方账号，怎么不切一次串一次

v3.20.0 起 Codex 官方卡可以逐张绑定 ChatGPT 账号并共存，随之而来的问题是请求会不会记到别的账号头上。这篇按 v3.20.1 快照，把绑定卡与空官方卡的差别、代理层那段账号一致性校验的判据、官方卡退出故障转移的取舍，逐处落到文件与行号上。

CC Switch 一键导入链接点了没反应怎么排

别人发来一条 ccswitch:// 一键导入链接，点下去毫无动静。本文按「确认框弹没弹」把这个现象切成协议层和载荷层两段，给出各自的判定动作、源码里能查到的处置依据、处置后怎么确认，以及什么情况说明根本不是这个原因；并指出手册在协议注册与必填字段两处都没有回指，读者得自己翻回去比对。

CC Switch 发布说明里的数字不能直接当事实用

CC Switch v3.20.1 的发布说明顶部写着「26 commits | 66 files changed」，可你自己 git log 数出来是 28 和 74。这篇把同一份文档里的数字拆成三类：换个口径就能严丝合缝复现的、仓库里连测量脚本都找不到的、以及跟着版本走一年就会过期的，并给出判断依据。

CC Switch 的 i18n 测试守错了方向：参照系是 en 的代价

CC Switch 有一个专门校验多语言完整性的 vitest 用例，三条断言都能通过，但代码里仍有两个键在四种语言中全都没有定义。本文从 localeCoverage.test.ts 的参照系那一行出发，讲清这类测试为什么抓不到「代码要的键 en 也没有」，以及白名单写错一个键名为什么不会让测试变红。

CC Switch 的环境变量冲突检测：前缀还是精确匹配

CC Switch 会扫描系统里的环境变量并弹出冲突横幅，但「什么算冲突」有一条写死在 Rust 里的判定规则。本文顺着 env_checker.rs 的关键词枚举、单元测试钉死的一组反例，以及前端那份硬编码应用清单，讲清这套检测覆盖到哪里、又从哪里开始失效。

CC Switch 恢复提示词后，没被管理的文件不见了

从云端下载或导入备份之后，本地手写的 AGENTS.md、CLAUDE.md 变成了空文件。这不是同步没下全，而是恢复路径上的一次"写空"。本文按源码定位这行代码在哪、怎么判断你遇到的就是它、v3.20.1 改了什么，以及哪五种情况说明根因不在这里。

CC Switch 会话不见了的六种解释

用 CC Switch 管理 Codex 供应商时，历史会话列表突然少了一大截。本文按 v3.20.1 的仓库文档与源码梳理这类症状的六种成因，给出每一种的判定动作、处置方式与验证办法，并指出其中只有一种是真限制、其余五种都是分组标签造成的误解，同时说清判断会话是否真的丢失应该以文件总数为准。

CC Switch「连续失败三次就熔断」这说法是错的

CC Switch 的用户手册在三个章节给了三套健康徽章说法，其中「连续失败 3 次触发熔断」与它自己给出的失败阈值默认值直接打架。本文按源码把徽章的三条分支、熔断器的三个状态和两条触发路径捋清楚，并给出你自己动手判定的办法。文中行号与默认值均对应 v3.20.1 快照，只静态读源码，不涉及界面观感与运行表现。

CC Switch 怎么把几百个 IPC 调用收进一层封装

Tauri 应用里前端调后端靠的是字符串命令名，编译器管不住。CC Switch v3.20.1 把绝大多数 invoke 收进 src/lib/api 一层薄封装，这篇顺着源码讲清楚截断点选在哪、封装体只做哪三件事、哪几处刻意破例，以及那些注册了却在前端搜不到引用的命令该怎么描述。

终端能跑的 CLI，CC Switch 却检测不到

命令行里明明能跑的 AI CLI，桌面端却报未安装，或者更新完还显示旧版本。根因通常不在检测逻辑，而在这个进程继承到的环境和你登录 shell 的环境不是同一份。本文按 v3.20.1 的源码拆开三种独立成因，给出三种对应的判定动作与验证口径，并说明哪些表现看着像是检测问题、其实要挂版本口径去别处排查。

给 CC Switch 接一个新的 AI CLI，要改多少处

CC Switch 在 v3.20.1 里多托管了一个 AI 编程 CLI。本文沿仓库改动把「接一个新应用」拆成注册表、能力常量、预设数据、表单、命令层、测试夹具、翻译七类改点，逐类给出文件与标识符位置，并指出哪几处是同一件事抄了好几遍、又是哪一处已经对不上。

CC Switch 的 keep-last-good：查询失败不抹掉上次成功值

额度查询一次网络抖动就被判成失败，一律掩盖失败又会让换过 Key 的人一直拿到过期数字。CC Switch v3.20.1 用一个白名单加一个纯决策函数把失败分成两类分别处置。本文按行号拆开这段逻辑，重点讲失败路径为什么也必须回写快照，并把它放回全站的轮询节律里看。

CC Switch 的可逆性五件套：迁移会话历史怎么做到能退回去

一个第三方工具去改 Codex 自己的会话历史文件，出错就是用户资产受损。CC Switch v3.20.1 用只改一个字段、改前必备份、原子替换、悲观跳过、幂等可重试这五件事把风险压下去，本文逐条落到源码常量、原因码与函数位置上，并说清哪一段是这套设计覆盖不到的。

CC Switch 的跨年折线图为什么会错位

CC Switch 用量看板的趋势图曾在跨年区间上出现「高亮的点和提示框描述的不是同一天」。根因是拿本地化的 MM/DD 文本当 Recharts 分类键，不同年份的桶撞成同一个值。这篇把 v3.19.2 与 v3.20.1 两版的 UsageTrendChart.tsx 对上，讲清键、刻度、提示为什么必须分家。

CC Switch 的设置页为什么有两套保存语义

同一个设置页里，有的开关改完立刻落盘，有的要等你点保存按钮。这不是随手写出来的差异。本文顺着 SettingsPage.tsx 的即时保存函数读到它的回滚分支，讲清楚为什么这里非回滚不可，落到实现上其实是三份各写各的乐观更新代码，以及这套结构在这一版一行未动。

CC Switch 里「应用」这个概念有六套枚举

在 CC Switch 的前端代码里问「哪些应用支持某个功能」，会得到好几个互不相同的答案。这篇把 appConfig.tsx 与 usage.ts 里那几个应用集合逐个摊开，讲清每一套服务的是哪一层判定，以及为什么把它们合并成一套反而会造出假成员。

CC Switch 五个功能面板共用一副骨架

skills、prompts、mcp、proxy、universal 五个目录管的事完全不搭界，代码却不是各写各的。本文按共享组件、命令式句柄、忙碌态冒泡、写操作串行锁四层，拆开 CC Switch v3.20.1 前端的复用梯度，并解释为什么 proxy 一件共享件都不用、universal 只用一件。

CC Switch 编辑框显示的密钥不是当前生效的

打开 Codex 供应商的编辑表单，里面填着的密钥可能来自另一张卡，保存一次就固化进数据库。这篇按源码位置拆开成因：共享的 auth.json 没有供应商身份，而表单播种时优先读它。给出判定动作、v3.20.1 的处置写法，以及哪几种情况说明你遇到的其实是别的问题。

CC Switch 报 model not found 该查哪几层

模型 ID 一个字都没抄错，请求却被打回 model not found。本文按 CC Switch v3.20.1 的源码与用户手册，把这类报错拆成共享凭据文件、模型目录指针、模型 ID 清洗三层，逐层给出可执行的判定动作、源码里的处置依据，以及什么情况下说明根因其实不在这里。

CC Switch 用量看板里 N/A 与 0 不是一回事

用量统计里最容易看错的就是空数字。CC Switch 在 v3.20.1 的源码里把「协议不上报」「真的是零」「解析失败」「价目表里没这个模型」拆成四条互不相同的渲染分支，本文逐条落到具体文件与行号，并说明混用两系 API 时它为什么只给口径标注而不给一个合计数。

CC Switch 的两种用量来源：会话回读与代理记账

用量看板里同一张表混着两类行——请求真的走过本地网关当场记下的，和事后去读 AI CLI 会话文件补记的。本文从 data_source 这一列出发，讲清两类来源的写入位置、去重账本、覆盖仲裁，以及为什么每新接一个没有本地网关的应用，就得多出一个来源值。

CC Switch 接进第九个受管应用，动了一百多个文件

给一个配置管理工具接入一个新的 AI 编程 CLI，成本到底落在哪里？沿着 v3.19.2 到 v3.20.1 的仓库改动，把这次接入触及的前端组件、数据层、Rust 服务层、命令层、会话管理、数据库与国际化逐层拆开，并记录同一份仓库里三处文档给出三个不同应用数的现状。

CC Switch 首次导入既有配置：哪些碰哪些不碰

以 v3.20.1 快照里的 Pi 接入为例，逐条对照源码讲清 CC Switch 首次启动会导入哪些既有供应商、会回填什么用量、明确声明不动的又是哪几样，顺带拆开 models.json 的三层写保护，看它把哪几类冲突挡在了真正写入之前，以及数据库迁移那一步实际做了什么。

CC Switch 的批量开关为什么必须串行跑

CC Switch 的批量开关没有并发发请求，而是过一个只有三十来行的 runSequentialBulkAction 逐条 await。理由写在代码注释里：多个应用适配器是整文件重写配置，并行写会互相覆盖。本文按文件行号拆开这条约束在工具层、hook 层、面板层各留下了什么痕迹。

CC Switch 启动失败时该退出还是自救：两套渲染树

桌面应用启动期出错，是直接退出还是降级渲染一个恢复界面？CC Switch v3.20.1 的 main.tsx 把两种收场都写进了同一个文件，并且给恢复分支刻意砍掉了两层 Provider。本文按行号拆开这条分岔的判据、依赖边界与三档处置。

CC Switch 向系统要了哪些权限：capability 白名单逐条对账

权限清单漏掉一条会怎样？不是报错也不是崩溃，而是按钮在、代码在、什么都不发生。本文按 CC Switch v3.20.1 的快照，把 capabilities/default.json 里的每条权限对到前端调用点上，讲清 capability 约束的到底是谁，以及新增的 process:allow-exit 修的是什么。

CC Switch 的崩溃日志怎么才能不写进你的 API Key

一个管着本机 API Key 的桌面应用，前端一崩就要写日志，而异常对象里最容易夹带的恰恰是密钥。本文顺着 CC Switch v3.20.1 的 frontendLogger 读它的两层脱敏链、截断护栏、跨引擎栈处理，以及那份把「该留的留下了」也一并锁死的脱敏契约测试。

CC Switch 只加一张表，schema 版本却跳两级

v3.20.0 的发布说明写「schema 从 v16 迁到 v17」，但 v3.20.1 的源码里常量已经是 18，而基线建表只多了一张。这篇把三个数字各自的口径、两次迁移分别做了什么、以及「为什么第二次不能补进上一个版本号」的源码注释逐条摊开。

CC Switch 删除报错，东西其实已经删掉了

在 CC Switch 里删一条 Skill 备份，收到的是删除失败的提示，可那条备份其实已经不在了。这篇把 UnifiedSkillsPanel 里专门为此写的三重错误处理逐条拆开，标到具体行号上，给出一个不用翻磁盘就能做的判定信号组合，并给出处置与验证的落点，最后列出四种「不是这个原因」的情况。

CC Switch 手册说能点，代码里其实没这个入口

CC Switch 的用户手册里描述了一些在 v3.20.1 源码里找不到接线的交互，比如点击请求日志行看详情，照着找会白费时间。这篇把用量看板与会话页几处对不上的地方逐条摆出来，给出一套只靠读文件就能完成的判定动作，并说明哪些情况其实是前置条件没满足、平台分支或双方各缺一块，不该归到文档滞后上。

CC Switch 怎么防首帧白闪：内联脚本与 CSP 哈希

拆开 CC Switch v3.20.1 防首屏闪烁的做法——index.html 第 7 行的内联主题脚本、tauri.conf.json 的 CSP 白名单为什么多一串 SHA-256、Windows 侧 on_page_load 延后显示窗口的钩子、React 起来后 ThemeProvider 如何接管，并给出哈希复算方法。

CC Switch 里有两个页面没有任何入口

在 v3.20.1 的 App.tsx 里，agents 与 universal 两个视图凑齐了类型成员、运行时清单、渲染分支和顶栏标题，唯独缺一处把它们传给 setCurrentView 的调用。本文给出行号与复核命令，说明这两个视图唯一的到达路径来自哪个浏览器存储键，并对照 v3.19.2 确认它不是新引入的。

CC Switch 的搜索为什么把凭据字段排除在外

一个本地搜索框要先决定把记录的哪些字段拼成可匹配文本。CC Switch 的 MCP 列表页用显式白名单把 env 与 headers 挡在搜索之外，而同一个仓库的提示词列表页把正文也纳入了搜索。本文从 v3.20.1 的源码逐行讲清这组对照、白名单与黑名单的默认待遇差别，以及这段代码没有承诺的事。

读一百条提交能读出什么：CC Switch 的版本体检

追一个开源项目的升级，不该只读发布说明。这篇用 CC Switch 从 v3.19.2 到 v3.20.1 的提交区间做示范：先把「一百条提交」这个数的口径钉死，说明同一个区间为什么会数出三个不同的值；再按类型、scope、文件、时间四个维度分桶，看清改动压在哪几个面上；最后反过来问哪些模块一行都没动，以及代理层那三块基础设施为什么是升级风险的关键。

CC Switch 的升级：退出码 0 不等于升级成功

命令返回 0 就报「升级成功」，是一类很常见的误报。CC Switch 升级被管理的 AI CLI 时不认退出码，而是在命令返回后重新读一次版本再判一次，并把「版本没变」与「装上却跑不起来」单独归成软失败。本文按 v3.20.1 的源码行号拆解这套二次判定的写法、它的缓存前提与边界。

CC Switch 的页面切换：一个联合类型管住十几个视图

CC Switch 没有装任何路由库，整个应用的页面切换靠一个字符串联合类型、一份手抄的运行时清单和一个 switch 完成。本文顺着 src/App.tsx 的源码讲清这套结构怎么运转、把状态记在哪、非法值怎么兜底，以及想新增一个视图要动哪几处。

CC Switch 用一万行代码删掉文档里那句「不支持」

CC Switch v3.20.1 里有一次改动，九个文件净增一万行，其中三份路由攻略每份只改两行——改掉的是「GPT 路由下没有网页搜索」这一句。这篇拆开这一万行落在哪、桥只搭在哪条路径上，以及它确立的那条原则：协议翻译层碰到对面表达不了的约束时，为什么选择报错而不是放宽。

CC Switch 文档漂移的三种形态：语言数、安全前提、参数表

同一个仓库里，贡献指南说三种语言、验收清单说四种；安全策略声明的 CSP 已被一次前端修复改掉；代理指南的参数表整表对不上建表默认值。用 CC Switch v3.20.1 快照里的三组实例，讲清文档漂移的三种形态各自长什么样、成因差在哪、分别该用什么动作现场核对。

CC Switch 在 Windows 上启动闪白屏怎么办

桌面应用启动时先闪一下未着色的页面，根因通常不在显卡也不在开机速度，而在「窗口什么时候显示」与「主题什么时候生效」这两件事的先后顺序。本文按 CC Switch v3.20.1 的源码，拆开这条链路的三处改动，给出自查动作，以及哪些现象说明根因不在这里。

把配置目录放在 WSL 的 UNC 路径上时，新建供应商能存、改已有的却一直失败。这个症状在 v3.19.2 上出现，根因是 Windows 原子写换成 ReplaceFileW 之后，rename 回退的触发条件只写了 NotFound。本文按源码给出三条不需要运行程序的判定动作、发布说明给的处置口径、以及可以拿来当自查清单的三条回归测试与两级持续集成门禁，同时写清哪几种看着沾边的症状其实另有根子。

没有桌面的 CI 里怎么测 CC Switch 的前端

CC Switch 是个 Tauri 桌面应用，但它的前端测试跑在没有窗口、没有 Rust 进程的 CI 容器里。本文顺着 v3.20.1 的 tests/msw/ 目录，讲清楚它把 invoke 翻译成 HTTP 的那一招，以及 MSW、API 层、invoke 层三个截断点各自的收益和代价。

CC Switch 把「信任渲染进程」写成可证伪的决定

CC Switch 的 SECURITY.md 把「打包的渲染进程属于信任边界之内」写成一项范围划定决策，附上四条能用搜索命令复核的支撑事实和五条提前写死的失效条件；其中 CSP 那一条，在文档最后一次改动的 18 天后被一个前端修复推翻。本文按 v3.20.1 快照，把这套写法与那处差异逐条落到确切的行号与提交上。

CC Switch 环境检查卡住不动怎么排：子进程挂死的四个原因

CC Switch 的升级预检或工具检查迟迟不结束、又不报错，多半不是网络慢。本文按 v3.20.1 的源码把子进程挂死拆成四个成因——进程组、控制终端、作业控制与超时缺失，先给出分清是哪条环境检查链路的判定动作，再逐件说明对应改动落在哪一行、Windows 侧为什么要单独看，最后列出四种看着像挂死其实并不是的情况。

CC Switch 把行号游标换成字节游标：什么算增量读

一个「跳过前 N 行」的增量扫描，为什么既没省掉 IO，又会永久丢掉正在写入的那一行。本文顺着 CC Switch v3.20.1 的会话日志扫描改动，逐行对照新旧两版源码，讲清字节游标、尾部指纹与「宁可少算不多算」这条取舍是怎么写进注释里的。

NewAPI 部署教程：从零到能跑通的完整步骤与上线前必做的检查

按官方文档梳理 NewAPI 的六种部署方式怎么选，给出 Docker Compose 与单容器两条路线的官方命令、SQLite 与 MySQL 的取舍、数据持久化写法，以及上生产前必须完成的默认密码更换与合规义务清单。

NewAPI 常见报错与排查顺序：从额度到渠道逐层定位

NewAPI 常见报错怎么排查？按网关自身、额度、渠道、客户端、数据库五层给出排查顺序，逐条对应官方 FAQ 与配置文档里写明的检查项，把「无可用渠道」「额度不足」「倍率未配置」这类提示定位到具体设置页。

NewAPI 接入 Claude Code 的配置方法：令牌、环境变量与验证

按 NewAPI 官方文档梳理 Claude Code 的接入路径——先在控制台建令牌拿接口地址，再按 Windows/macOS/Linux 各自的官方步骤装好 CLI，最后用官方一键脚本改环境变量，并说清官方文档里到底写了什么、哪些细节它没写。

NewAPI 接入 Codex 的配置方法

把 Codex CLI 指到自建的 NewAPI 网关上，需要准备接口地址和令牌两样东西。本文按官方文档梳理三个系统的安装步骤、一键改配置脚本、CC Switch 一键导入这条备选路径，以及令牌字段、计费公式和接不通时的排查顺序，只讲机制不列价格数字。

NewAPI Docker 部署怎么做：镜像、编排与数据持久化

按 NewAPI 官方文档与仓库文件拆解 Docker 部署的三件事——镜像怎么选怎么升级回滚、docker-compose.yml 到底编排了哪些服务、数据持久化有哪几个落点。附官方仓库版与文档版编排文件的差异、健康检查写法、多节点编排要改的行，以及上生产前必须处理的默认密码与端口暴露。

NewAPI 分组倍率是怎么算的？计费公式与配额扣费流程解读

按官方文档拆解 NewAPI 的三层倍率体系——分组倍率、模型倍率、补全倍率各自作用在公式的哪个位置，分组同时决定计费和渠道权限，以及预消费与后消费的差额调整流程、倍率没配会怎样、扣费对不上时去哪几个页面核对。

NewAPI 令牌管理：额度、分组与权限怎么设

NewAPI 的令牌自带过期时间、剩余额度、无限额度、模型限制、IP 白名单和分组六个维度。本文讲清令牌额度与账户额度为什么是两套数、分组同时管渠道权限和计费倍率、以及令牌能调哪些管理接口，全部依据官方文档。

NewAPI 日志怎么看：定位请求失败在哪一环

自建 NewAPI 网关后请求失败，日志要分三层看：控制台的用量日志、容器进程日志、以及默认关闭的错误日志开关。本文按官方文档梳理各类日志各能回答什么问题、upstream_request_id 怎么用来向上游追溯，以及常见报错文本对应哪一环出了问题。

NewAPI 是什么？自建中转网关能解决什么问题

NewAPI 是一套自己部署的大模型网关，把多家厂商的接口聚合成 OpenAI 兼容格式。本文按官方文档梳理它的定位、渠道令牌分组三个核心对象、配额公式的构成、部署形态与合规边界，帮你判断自建中转网关到底能解决什么问题、不能解决什么问题。

NewAPI 怎么用：渠道、令牌与分组的基本概念

NewAPI 装好之后该从哪配起？本文按官方文档梳理渠道、API 令牌、用户分组三个核心对象的关系与配置项，讲清令牌额度与账户额度为什么分开、分组怎么同时管权限和倍率、以及无可用渠道该按什么顺序排查。

OpenRouter 报错 401 是什么原因？鉴权失败的排查顺序

OpenRouter 返回 401 只说明一件事——鉴权没过。本文按官方错误码定义把 401 与 402、403、429 彻底分开，讲清 key 缺失、无效、已吊销三种情形怎么区分，以及 Authorization 头、key 轮换、第三方客户端各自会在哪一步出问题。

OpenRouter 报错 403 怎么解决：权限不足与 guardrail 拦截的区分

OpenRouter 返回 403 不是"不认识你"也不是"没钱了"，而是"这件事不让你做"。本文按官方错误码定义拆开 403 的几条成因，讲清怎么用 openrouter_metadata 的 pipeline 一眼判断是不是被 guardrail 拦的，以及权限、作用域、BYOK 各自会在哪一步返回 403。

OpenRouter 429 速率限制触发了怎么办：机制与退避策略

OpenRouter 报 429 时，先分清是平台侧限流还是上游供应商限流，再决定退避还是换路由。本文按官方文档梳理 429 的两个来源、X-RateLimit 与 Retry-After 头的出现条件、流式请求里 429 的特殊形态，以及模型级与供应商级两层兜底怎么配。

OpenRouter 报错 500 是谁的问题？上游与网关错误的区分

OpenRouter 的 500 有一个别的状态码没有的特点——官方会主动把信息删掉：message 被换成通用串，provider_code 和 openrouter_metadata 都不返回。本文按官方文档讲清 500 与其他 5xx 的差别、流式请求为什么出错还是 200、以及事后怎么用 X-Generation-Id 把责任方查出来。

OpenRouter API Key 怎么管理：创建、限额、轮换与泄漏处置

OpenRouter API Key 管理的四件事：创建时能一次定好哪些字段、单 key 限额靠哪三个字段生效、用 Management API 做零停机轮换的三步，以及 key 泄漏后官方给的处置路径。只讲机制不列价格数字。

OpenRouter 充值开发票怎么办？官方票据能拿到什么

OpenRouter 充值后能拿到的票据是 Stripe 出具的 invoice，官方文档里有明文路径的只有 Tax ID 挂载和企业侧 invoicing 两条。这篇把开票入口、税号类型、税额怎么算、组织账户谁有权限、以及官方没说明的部分讲清楚，避免报销时才发现票开错了。

OpenRouter 充值教程：从开通到到账的完整流程与每步会卡在哪

按官方文档梳理 OpenRouter 充值的完整流程：账号开通、Credits 页面的账单地址与支付方式、官方支持的支付方式、手动充值与自动补额、到账延迟的官方排查顺序、退款窗口与组织账户的权限边界，只讲机制不列价格数字。

OpenRouter 充值失败怎么办：常见拒付原因与官方排查顺序

OpenRouter 充值失败、扣了款额度没到账、卡被拒该怎么处理？按官方文档给出的排查顺序逐步拆解：先等多久、怎么判断是不是真被扣款、卡被拒后能换成哪些官方支付方式、加密支付与组织账户各有什么坑，以及退款窗口的边界在哪里。

OpenRouter 充值手续费是怎么产生的？费用构成与自己估算的方法

OpenRouter 的钱分两层收：充值时的平台手续费，和调用时按供应商原价透传的推理费。本文讲清手续费在哪个环节产生、加密支付和 BYOK 为什么是单独的账、以及怎么自己把月成本估出来，不列具体价格数字。

OpenRouter 充值有效期规则：额度会不会过期、怎么查剩余

OpenRouter 充值的额度到底有没有有效期？官方条款怎么写、余额和剩余额度该用哪个接口查、哪些情况会让额度提前作废。按官方文档梳理有效期规则与查询口径，只讲机制不列数字。

OpenRouter 充值支付宝能用吗？官方支持的支付方式说明

OpenRouter 充值到底能不能用支付宝？答案在官方 FAQ 的支付方式条目里已经写死了。这篇把官方接受的支付方式原文、充值入口在哪一步、收款方是谁、付款成功却没到账时官方给的排查顺序，以及文档里压根没写的部分，一次讲清楚。

OpenRouter 接入 Claude Code 怎么配：配置项、常见坑与验证方法

OpenRouter 接入 Claude Code 只有三个环境变量真正起作用，剩下的坑几乎都出在「配了但没送进会话」。本文按官方文档梳理配置项、写在哪个文件、旧登录态怎么清、/status 该显示什么，以及模型指定与 fast 模式的两处反直觉设计。

OpenRouter 接入 Cursor 的配置方法与生效验证

OpenRouter 接入 Cursor 走的是 Cursor 的 Override OpenAI Base URL，且必须指向官方的专用端点而不是通用的 v1。这篇按官方文档拆开四步配置、模型 ID 的写法、生效之后怎么验证请求真的走了 OpenRouter，以及哪几个功能官方明说不会或可能不会走你的 key。

OpenRouter 国内充值：官方支持哪些方式、卡在哪一步

国内用户给 OpenRouter 充值，官方文档明确接受的支付方式包含信用卡、支付宝与 USDC 加密货币。这篇按官方原文梳理充值前要填什么、钱扣了额度没到怎么按官方顺序排查、加密支付的接口变动，以及退款与额度过期的规则边界。

OpenRouter 连接失败的排查清单：从网络到鉴权逐层定位

OpenRouter 连接失败往往不是网络断了，而是鉴权、余额、路由偏好或流式解析出了问题。本文依据官方文档的错误响应结构，给出一份从传输层、鉴权层、账户层、路由层一直到 error_type 判据的逐层排查清单，帮你在几分钟内把故障锁定到具体那一层，而不是盲目折腾网络环境。

OpenRouter Auto Router 是怎么选模型的？路由机制与可控项

拆解 OpenRouter Auto Router 的路由机制：任务分类、按社区花费份额排名、cost_tier 成本档与带 fallback 的落地顺序，并讲清 allowed_models、excluded_models、session 粘性、账号默认值这些可控项，以及怎么确认它实际选了哪个模型。

OpenRouter 免费 API 怎么拿？从注册到第一次调用

想白嫖 OpenRouter 免费 API 的完整路径：新用户免费额度和免费模型是两回事、去哪建 key、:free 变体与 openrouter/free 路由器怎么选、第一次调用怎么发、怎么用 GET /api/v1/key 确认自己还剩多少、第一次失败又该按哪个字段分诊。

OpenRouter 免费额度是怎么给的？额度规则与用完之后的选择

OpenRouter 说的"免费"其实是好几件不相干的事：新账户试用额度、模型 ID 后缀 :free 的免费变体、openrouter/free 路由器，以及 BYOK 的套餐内免费额度。本文按官方文档对齐四者的规则、查询字段、耗尽后的报错形态与官方给出的出路。

OpenRouter 免费吗？免费层与付费层的边界到底在哪

OpenRouter 免费吗，答案要拆成账号、模型、平台费三层来看。本文按官方文档梳理免费模型的两个入口、免费层请求上限的分档机制、GET /api/v1/key 里判断自己在哪一层的字段，以及联网搜索、BYOK、隐私设置这几处容易被忽略的免费与付费边界。

OpenRouter 免费层速率限制怎么应对：触发条件与降级策略

OpenRouter 免费层的速率限制到底由什么触发、怎么确认自己撞的是哪一道闸、又该按什么顺序降级。本文按官方文档的 Limits 与路由章节梳理触发条件、响应头判据、GET /api/v1/key 的监控字段，以及退避、换模型、模型回退这几条降级路径，只讲机制不列数字。

OpenRouter 免费模型限制有哪些：速率、上下文与可用性机制

OpenRouter 免费模型限制不是一条规则，而是额度、速率、上下文、可用性四层叠加。本文按官方文档讲清每一层由什么字段决定、触发后返回什么错误、在哪里查自己的剩余量，以及为什么换账号和多开 key 都绕不过去。

OpenRouter 免费模型推荐：与其看榜单，不如按任务自己挑

网上的 OpenRouter 免费模型推荐清单过期得比你想象中快。这篇不排榜，只讲官方提供的挑选手段：模型清单接口有哪些过滤维度、哪三个字段决定一个免费模型能不能干你的活、openrouter/free 随机路由的取舍，以及免费模型选型里最容易被漏掉的数据政策与余额变量。

OpenRouter 免费转付费的临界点怎么判断：三个官方信号

OpenRouter 免费转付费不是感觉问题，官方文档里有明确口径：credit limits 与 rate limits 是两堵不同的墙，管的东西和解法都不一样。本文讲清怎么用 GET /api/v1/key 的字段在撞墙之前算出自己的临界点，以及转付费之后哪些事会变、哪些不会。

OpenRouter 模型不可用：下线、限流与路由失败的区分

OpenRouter 报模型不可用时，可能是模型已经从目录里消失，可能是上游供应商挂了或在限流，也可能是你自己的 provider 偏好把候选筛空了。本文按官方错误码、error_type 字段与路由元数据，给出一条能把这三类原因分开的排查顺序。

OpenRouter 报 No allowed providers are available 怎么恢复

OpenRouter 返回 No allowed providers are available for the selected model 时，问题几乎总在你自己设的筛选条件上。这篇按官方文档拆解这条报错的完整语义、会把候选池筛空的那一批 provider 字段、账户级白名单与请求级 only 的叠加关系，以及用路由元数据头把筛选过程打印出来的排查办法。

OpenRouter 请求超时怎么排查：超时到底发生在哪一段

OpenRouter 的请求超时不是一个点，而是一条链上的好几段：你的客户端超时、OpenRouter 到上游供应商的 fetch 超时、供应商自己的读超时。本文按官方文档拆开这几段，讲清 error_type 为 timeout 时到底是谁没响应、第一个 token 前后为什么处理方式完全不同，以及客户端超时之后计费还会不会继续走。

OpenRouter 是什么？它在模型调用链里到底解决了什么问题

OpenRouter 是什么、它在你的模型调用链里到底插在哪一层。本文按官方文档梳理它的统一端点与 OpenAI 兼容层、供应商路由与模型级 fallback、额度扣费口径、模型名变体后缀这四层机制，以及它明确不解决、却最容易被想当然搞错的那几件事。

OpenRouter 退款规则怎么算？官方政策与申请路径

OpenRouter 的退款只覆盖未使用额度，且要在交易处理后的 24 小时窗口内自己在 Credits 页面申请。本文讲清这条政策的四道条件、平台手续费与加密支付为什么不退、怎么先把"未使用"的口径查准，以及三类被误当成退款的情况该走哪条官方路径。

OpenRouter 信用卡被拒的几种原因与官方给的处理办法

OpenRouter 充值时信用卡被拒，官方文档并没有给出拒付原因码，只给了一条从「有没有扣款、有没有收据」反推的判定路径。本文按官方原文拆开「卡真被拒」「支付成功但额度延迟」「根本不是卡的问题」三种情形，讲清每一步该确认什么、官方支持哪些支付方式、重复重试踩到退款窗口怎么办。

OpenRouter 余额和用量怎么查：控制台、API 与账单口径的区别

OpenRouter 查余额和查用量不是一件事。这篇拆开四个入口：响应里的 usage 对象、GET /api/v1/key 的单 key 口径、要 management key 的 credits 与 Analytics 接口、Activity 页导出，说清它们为何天然对不上账。

OpenRouter 怎么用：从第一次调用到接进现有项目

OpenRouter 怎么用的完整路径：先在账户里备好额度和 API key，用官方文档给的端点发出第一个请求，再按三种集成方式选一条接进现有项目，最后把额度与限额监控挂上。全文只讲机制不列价格数字。

OpenRouter 最低充值门槛是怎么定的？额度机制与首充注意事项

OpenRouter 官方文档里找不到"最低充值金额"这样的条款，真正起门槛作用的是另外三个判定：是否付过费、累计购买量、余额是否为正。本文讲清这三层机制、首充比后续充值多出来的两步，以及决定首充充多少时该看的规则，不列具体金额。

硅基流动 401 鉴权失败怎么排查：官方错误码与检查顺序

硅基流动返回 401 时，官方文档给出的原因只有一条：API Key 没有正确设置。这篇按官方错误码表和官方通用排查步骤，梳理一条从读 message、看鉴权头、核对 key 与账户归属、curl 复现到关代理的顺序，并说清 401 与 402、403、429 的分工，以及哪些细节官方文档确实没有说明。

硅基流动 API 地址怎么填？端点、兼容层与常见填错

硅基流动的 API 地址其实有两个形态：给 SDK 填的基址，和给 curl 用的完整端点。这篇说清两者的区别、鉴权头怎么写、OpenAI 兼容层到底兼容到哪一层，以及地址相关的填错怎么按官方错误码表倒推。

硅基流动的 API 接口与 OpenAI 兼容层差异在哪

硅基流动的 API 接口兼容 OpenAI 对话协议，改一个 base_url 就能跑通，但模型命名、错误码语义、限流维度和 max_tokens 的含义都跟原来不一样。这篇按迁移时真实会踩到的顺序，逐条讲清兼容层帮你省掉了什么、又有哪些地方必须单独适配。

硅基流动接入 Claude Code 的配置与验证顺序

硅基流动接入 Claude Code，难点不在环境变量怎么写，而在两边官方口径的交界处。本文对齐硅基流动的端点与鉴权头和 Claude Code 的 ANTHROPIC_BASE_URL、凭据变量，给出从 curl 到 /status 的验证顺序，并标出官方没说的部分。

硅基流动接入 Cursor 怎么配？基址、模型名与报错对照

硅基流动接入 Cursor，平台这一侧只需要基址、API Key、模型名三样填对。本文按官方文档讲清 OpenAI 兼容基址怎么填、Pro 前缀命名规则为什么会让模型名填错、以及配完调不通时按 HTTP 状态码倒推是哪一栏出了问题。

硅基流动代金券怎么用？赠费余额抵扣规则与失效排查

硅基流动代金券的领取入口与面额规则，官方文档目前并没有成章节地写出来。真正能查到出处、也真正决定你那笔钱能不能抵扣掉的，是「赠费余额」和「充值余额」这两套余额的区分，以及模型名前面那个 Pro/ 前缀。这篇把有出处的部分讲透，把没出处的部分照实说明。

硅基流动免费模型有哪些？怎么查当前可用清单

硅基流动官方文档并没有维护一份"免费模型清单"，它给的是一条命名规则和一个查询入口。这篇讲清怎么从模型名判断免费版与收费版、免费版限额为什么不随账户等级涨、实名认证卡住的是哪一步，以及调不通时按错误码怎么分流。

硅基流动模型清单怎么查：模型广场、命名规则与选型注意

硅基流动的模型清单不是一张表就能看完的东西。这篇讲清官方文档给出的查询入口、模型名里的 Pro 前缀规则、名字写错时平台会回哪个错误码，以及选模型时除名称之外还要核对的几个字段，帮你在调用前就把清单确认到位。

硅基流动速率限制机制与触发后的处理

讲清硅基流动速率限制的七种指标、任一指标达峰即触发的判定方式、限额挂在账户而非 API Key 上的设计，以及收到 429 之后按什么顺序排查和重试，附易混错误码的区分方法。

硅基流动统一登录是怎么回事？账号体系与常见登录问题

硅基流动官方文档里其实没有"统一登录"这个说法，官方写明的登录方式只有短信和邮箱两种。这篇把账号体系的真正主干讲清楚：实名认证决定了能不能充值开票、能不能用全免费模型，限额和余额都挂在账号上而不是某把 API Key 上，以及登录之后仍然报 401/403/402 时该按什么顺序排查。

硅基流动用量和额度怎么查：余额、限额与用量级别分开看

硅基流动的「用量」和「额度」其实是三本互不相通的账：余额分充值余额和赠费余额、限额有七种速率指标且按模型单独设、用量级别按月消费额自动升降。这篇讲清各查哪里、怎么用报错码快速定位，以及充值和消耗为什么对不上。

Gemini Batch API 的两种提交形态怎么选

Gemini Batch API 只有内嵌请求和 JSONL 输入文件两种提交形态。这篇按官方文档讲清两者的分工边界、上传链路、对账用的 key 字段、独立于常规调用的那套限流约束，以及跑批时要特别留意的那个计费环节，帮你在开工之前就把形态选对。

Gemini 批量任务怎么把响应对回请求：key 字段的用法

Gemini Batch API 提交上千条请求后，结果回来怎么知道哪条对哪条？官方给出的对账机制是用户自定义的 key 字段，响应会用同名 key 标注。本文讲清 key 在内嵌与 JSONL 两种提交形态下的位置、输出结构的差异，以及批量对账最容易翻车的几个点。

Gemini 的层级体系怎么升：限流跟着结算账号走

Gemini API 的免费层与三个付费层级到底挂在哪一层对象上、每一级的门槛是什么条件、升级之后限流怎么变、付了钱层级却没动该往哪查，以及哪几种操作会让层级掉回去。全文只讲官方文档写明的机制与判定口径，不写任何金额与限流数值。

Gemini API 错误码三大族怎么分、怎么对号入座

Gemini API 的错误码不是一张平表，而是请求级、生成被阻止、生成结构三族，各自的判定位置和处置方式都不一样。本文按官方错误参考页把三族拆开，讲清 code 字段怎么读、哪些码重试有用、流式请求为什么会漏掉错误。

哪些 Gemini 模型的推理是关不掉的：思考参数怎么设

用 OpenAI 库调 Gemini，reasoning_effort 映射到 thinking_level 或 thinking_budget。官方明文：2.5 系列可设 none 关闭思考，2.5 Pro 与 Gemini 3 系列关不掉。本篇讲互斥规则、默认行为与账单口径。

Gemini 的缓存存储时长要单独计费：估成本时容易漏掉的一项

Gemini API 官方把计费依据列成四项，其中一项是缓存 token 的存储时长——它按时间走而不是按调用次数走。这篇讲清这项支出从哪儿来、官方文档对两种缓存交代到哪一层、用哪个字段查缓存命中量，以及估月成本时该怎么把这一项补上。

Interactions API 用不了 Gemini 显式缓存：只能走隐式那条路

Gemini 有隐式与显式两套缓存，但官方文档写明 Interactions API 仅支持隐式缓存，要用显式缓存必须改用 generateContent API。这篇讲清这条限制卡在接口这一层、留在 Interactions API 上怎么抬高隐式命中率、靠哪个字段确认命中。

Gemini 的两种 429 完全不是一回事：退避重试救不了哪一种

Gemini API 的 429 至少对应两个语义不同的错误码，rate_limit_exceeded 靠指数退避能恢复，quota_exceeded 退避再多次也没用。本文讲清怎么从 error 对象里分辨、各自该怎么处置，以及流式请求为什么只看状态码会漏掉它们。

Gemini 流式请求的错误不走 HTTP 状态码：只判状态码会漏掉它

Gemini 官方错误参考（Interactions API）里，标准与流式请求的错误走两条通道：非流式设置 HTTP 状态码并在 JSON 体返回 error 对象，流式则通过 SSE 发送 event_type 为 error 的事件。本文讲清分叉与只判状态码会漏掉什么。

用 OpenAI 库调 Gemini：官方说只改三行

Gemini 官方给 OpenAI 库用户的迁移说法是只改 api_key、base_url、model 三处。这篇讲清这三行分别改成什么、鉴权头与原生接口的差别、思考参数怎么映射、流式错误为什么可能不在状态码里，以及官方自己为什么反过来劝新项目别走兼容层。

Gemini API 迁移到企业平台：Vertex 后端只改客户端这几行

Google 的 Gemini 有两条产品线，Developer API 与 Gemini Enterprise Agent Platform 共用同一套 Gen AI SDK。这篇讲清迁移时改哪几行客户端初始化、调用层为什么不用动，以及代码之外必须重新核对的账号侧机制。

Gemini API 的区域可用性怎么看：官方给的替代路径是什么

Gemini API 的可用区域以官方 available-regions 页为准，该列表不包含中国大陆，官方给出的替代路径是 Gemini Enterprise Agent Platform。本文讲清区域判定依据、两条非区域准入条件、Colab 判定口径与国内合规方向。

Gemini 的 reasoning_effort 和 thinking_level 怎么对应

用 OpenAI 库调 Gemini 时，reasoning_effort 会被映射成 thinking_level 或 thinking_budget。本文讲清这层映射的四个档位、为什么两者不能同时传、哪些模型关不掉推理，以及思考 token 落在账单的哪一栏。

Gemini 的 recitation 和 spii 是什么错：内容被拦了怎么办

Gemini API 的生成被阻止码是一族独立的错误，safety、recitation、spii、blocklist、content_blocked 都归在这里。这篇讲清它和请求级错误、输出结构错误的边界，官方给的统一处置是什么，以及为什么把它塞进指数退避重试里是错的。

Gemini 工具调用报 malformed_function_call 怎么办

Gemini 官方 Interactions API 错误参考里，malformed_function_call 不属于请求级错误码，而是「生成结构错误码」这一族，说明模型输出结构有问题。本文讲清这一族官方分别写了什么、怎么和 400 请求错误区分开、流式下为什么会被漏掉。

Gemini 限流是按项目算的，不是按 API 密钥算的

很多人撞到 Gemini API 的 429 后第一反应是再签几把密钥，但官方文档写明速率限制按项目应用、密钥没有独立结算设置。这篇把 Gemini 限流的计数维度、项目与结算账号的层次关系、配额重置时点和两种 429 的区别讲清楚，顺带说明哪些流量不走这套计数。

Gemini 隐式缓存怎么才能命中：官方给的两个办法

Gemini 的隐式缓存对 2.5 及更新型号默认启用，不用你写一行代码，但也不保证命中。本文按官方文档讲清提高命中率的两个办法、那道因模型而异的最低输入门槛、用 usage.total_cached_tokens 确认命中量的方法，以及什么时候该改用显式缓存。

Gemini 预付款余额归零，名下所有密钥会同时停摆

Gemini 预付款余额一旦归零，官方明确该结算账号下所有项目的所有 API 密钥同时停止工作。这篇按排查顺序讲清爆炸半径、余额被吃光的几条隐蔽路径、充值后服务什么时候才恢复，以及官方文档在哪几处根本没说。

Gemini 预付款和后付费怎么选：切过去就回不来了

Gemini API 的结算方案分预付款与后付费两种，本文按官方结算文档讲清两者的扣款方式、支出上限的两级结构、第 3 层级那道不可逆的切换门，以及预付款余额归零会连累整个结算账号的运维风险，帮你在开工前把方案定对。

Gemini 账单有结算延迟：长任务怎么就超出预算了

Gemini API 的结算流水线、层级升级、费用明细图表各有各的延迟，支出上限因此不是即时断路器。这篇按排查顺序讲清楚批量与 Agent 类长任务为什么会在预算之外继续消耗，以及账单高于预期时先核哪几项。

用 Anthropic SDK 接入 MiniMax：官方推荐的接法

MiniMax 官方把 Anthropic SDK 列为推荐接入方式。本文按官方文档走完整条链路：两个环境变量怎么配、返回的内容块列表怎么读、多轮工具调用为什么必须原样回带、哪些 Anthropic 参数会被忽略、usage 与错误码怎么对照排查。

MiniMax 充值、发票与余额预警怎么设

MiniMax 开放平台的钱分成账户余额和订阅额度两个池子，充错了 Key 就用不上。这篇把充值的两条路径、余额预警的设置位置、发票"按已消耗金额开票"的规则，以及子账号的账务边界一次讲清，只讲机制不列价格。

在 Claude Code 里配 MiniMax：环境变量、模型名与额度切换

把 Claude Code 指向 MiniMax 的 Anthropic 兼容端点，官方给的配置只有三步，卡住人的却是环境变量优先级、两页对不上的模型 ID、以及要单独装的网络搜索 MCP。本文按操作顺序逐字段拆解，并附上验证命令与错误码对照。

在 Cursor 和 Trae 里配 MiniMax：两种接法与官方警告

按 MiniMax 官方文档拆解 Cursor 与 Trae 接入 MiniMax-M3 的完整步骤，讲清订阅 Key 与按量计费 Key 的区别、Override OpenAI Base URL 的全局副作用、Tab 补全为什么用不上自定义模型，以及两个工具各自的验证方式。

MiniMax 的 Prompt 缓存怎么用：命中条件与字段怎么查

MiniMax 的 Prompt 缓存是自动生效的被动缓存，不用改调用方式，但它有前缀匹配规则和最小 token 门槛。本文按官方文档讲清它和 Anthropic 主动缓存的分界、命中要满足什么条件、两套 SDK 各自从哪个 usage 字段读缓存 token，以及计费口径上最容易被忽略的那一条。

MiniMax 同时兼容 OpenAI 和 Anthropic 两套 API：怎么选

MiniMax 的语言模型同时提供 OpenAI 兼容和 Anthropic 兼容两套接口，官方把 Anthropic 一侧标为推荐。本文逐条对照两套 API 的入口地址、thinking 默认值、被忽略的参数清单、多模态与缓存差异，给出该按什么条件选、切换时该改哪几处。

MiniMax Token Plan 和按量付费怎么选

从订阅 Key 与按量计费 API Key 的分工讲起，梳理 MiniMax Token Plan 的额度扣减规则、双层窗口、触顶后的四条出路，以及按量付费这边的余额、限速与发票口径，帮你判断自己该走哪条计费路线。

MiniMax 限流机制与错误码对照：报错先看哪一层

MiniMax 的错误分散在三个不同的返回位置，限流也不止 RPM 和 TPM 两个维度。这篇按排查顺序梳理 MiniMax 官方文档里的限流规则、错误码含义与对应处理动作，帮你在拿到一串数字时先判断该改代码、该等窗口，还是该联系官方。

MiniMax 主动缓存怎么显式设置：cache_control 断点放在哪

MiniMax 主动缓存需要在 Anthropic 兼容接口里显式设置 cache_control 断点。本文按官方文档讲清断点该加在哪一块内容的末尾、缓存前缀按什么顺序逐级累积、回溯窗口与断点数量上限各自意味着什么、三个缓存用量字段该怎么读，以及缓存命中率不对时的排查顺序。

在 Cherry Studio 和 Zed 里配阶跃星辰：Base URL 与模型 ID 怎么填

按阶跃星辰官方接入指南，把 Step 模型分别配进 Cherry Studio 桌面客户端和 Zed 编辑器。讲清 Step Plan 专用 Base URL 与普通 API 地址的区别、模型 ID 填哪个、检测按钮报错怎么查，以及 Credit 月池额度和错误码之间的对应关系。

在 Claude Code 里配阶跃星辰：Base URL 与模型名怎么填

在 Claude Code 里接入阶跃星辰 Step Plan 的配置路径：settings.json 三个键怎么写、Base URL 带不带 /v1 的官方区别、模型名填什么、/status 怎么自查，以及 model does not exist、401、402 各自的成因。

在 Cline 和 Roo Code 里接入阶跃星辰：Base URL 与参数怎么填

阶跃星辰官方给了 Cline 和 Roo Code 两份接入指南，字段几乎一样，坑却不在同一处。这篇按官方文档梳理 Base URL、Model ID、参数建议的填法，以及 Connection error 与 401 各自该查哪几项。

阶跃星辰错误码对照：HTTP 异常与 finish_reason 怎么排

按阶跃星辰官方文档梳理 400/401/402/404/429/451/5XX 各自的原因与处置方向，讲清 429 为什么有速率限制和组织额度两种来源、要靠错误标识区分，以及请求成功后还要看 finish_reason 的四种取值。

阶跃星辰 API 怎么接：OpenAI 兼容形态

阶跃星辰大模型兼容 OpenAI 的 API 规范，改 key、改 base_url、改模型名就能接上。这篇按官方文档梳理兼容接口清单、SDK 与 LangChain 的参数名差异、请求与返回里多出来的字段，以及 429 和 503 各自的两种含义怎么区分。

阶跃星辰 JSON mode 与工具调用怎么写：字段、回传与踩坑

按阶跃星辰官方文档梳理 JSON mode 与工具调用的写法：response_format 的三种取值、json_schema 的严格模式、tools 的字段约束、tool_calls 回传规则，以及 Chat Completions 与 Responses 两套接口的结构差异和容易踩的坑。

阶跃星辰 Prompt 缓存怎么用：命中条件与 usage 字段排查

阶跃星辰的 Prompt 缓存是自动生效的前缀缓存，不需要手动声明缓存点。这篇按官方文档讲清它在什么条件下启用、哪些内容会进缓存、怎么从 usage 里读出命中长度、没命中该怎么一步步排查，以及官方明确回答过的几个边界。

阶跃星辰企业组织与额度管理怎么配：项目、成员与 Credit

讲清阶跃星辰企业组织的搭法：个人空间与组织空间怎么分、项目和成员怎么建、两级 Credit 月度上限怎么设、单次调用最多能扣多少、额度打满时返回哪个状态码与错误标识，以及主账号和成员分别去哪查用量明细。只讲机制，不列具体价格数字。

阶跃星辰 Step Router 智能路由是什么：路由规则与计费口径

讲清阶跃星辰 step-router-v1 智能路由到底路由了什么、只在哪条通道可用、命中 DeepSeek 引擎时哪些字段会变、计费怎么换算，以及官方文档里明确没有说明的几处空白，帮你判断这个智能路由值不值得接。

GLM 错误码含义与处置对照

智谱 GLM 的 API 返回码分 HTTP 状态码和业务错误码两层，同一个 429 背后可能是欠费、限速、平台过载或套餐额度耗尽。这篇按官方错误码表逐段拆开每个 GLM 错误码的真实含义，给出对应的处置动作，并说明流式调用下错误码为什么会"消失"。

GLM Batch 任务失败怎么排查：从状态字段到错误文件

GLM Batch 批量任务失败，先要分清是整个任务没通过校验，还是任务里的个别请求出错。本文按官方文档的状态枚举、Batch 对象字段和错误文件机制，把提交前、执行中、拿结果三个阶段的排查路径逐段拆开，并说明过期批次的计费口径。

GLM Batch 批量接口什么时候值得用

GLM Batch 批量接口按低于标准价计费、并发额度独立，但只适合能等结果的离线任务。这篇按官方文档拆开 jsonl 构造、文件上传、任务状态机与结果下载，说清什么任务值得改成 Batch，什么任务改了反而更麻烦。

GLM 兼容 Anthropic Claude API：怎么接、哪里不一样

智谱 GLM 提供了 Anthropic Claude API 兼容层，改 base_url、API Key 和模型编码就能把现有 Anthropic SDK 代码切过来。这篇按官方文档梳理接入步骤、鉴权头差异、端点怎么选、思考强度在两种场景下的不同规则，以及易忽略的限制。

GLM 编程套餐常见问题逐条拆解：额度、扣费与报错

把智谱官方 GLM Coding Plan 常见问题页里的坑逐条拆开：为什么买了编程套餐还提示余额不足、额度按什么周期刷新、哪些工具和场景不算在套餐里、MCP 工具是否单独计费、升级续订有哪些不可逆的动作，以及怎么确认一笔消耗到底扣的是谁。

在 Claude Code 里用 GLM 编程套餐：完整配置步骤

把 GLM Coding Plan 接进 Claude Code，卡住的地方几乎都不在安装，而在 Key 拿错、Base URL 填错、settings.json 里模型编码没改。本文按官方文档梳理从取 Key 到 /status 验收的完整顺序，并给出被扣账号余额时的排查方向。

GLM 编程套餐自带的四个 MCP 服务怎么用

GLM Coding Plan 套餐附带联网搜索、网页读取、开源仓库、视觉理解四个专属 MCP 服务。这篇按官方文档梳理它们各自暴露的工具名、远程与本地两种接入形态、Claude Code 里哪些已内置哪些还要手动装、以及四个 MCP 在积分抵扣上的口径差异和连不上时的排查顺序。

GLM 编程套餐和按量计费怎么选：两种付费方式的适用边界

GLM 编程套餐（GLM Coding Plan）和标准 API 按量计费不是同一条计费链路，端点、额度单位、耗尽后的行为、适用场景全都不同。这篇按官方文档把两者的边界讲清楚，并给出判断自己该走哪一边的方法。

GLM 编程套餐团队版怎么用：席位分配与用量归集

GLM 编程套餐团队版按席位订阅，每位成员拿的是独立的团队套餐 Key，用量以积分方式按席位单独归集。这篇按管理员的真实操作顺序讲清席位规则、积分怎么扣、超额按量付费怎么开、订阅怎么改，以及哪些行为会触发平台风控。

GLM 编程套餐的用量怎么算：什么情况会被判为超额

拆解 GLM Coding Plan 的积分抵扣公式、5 小时与每周双额度、高峰与非高峰的抵扣差异，并说清哪些情况其实不是超额而是压根没走套餐——配错 Base URL、用了非指定工具、以及会触发风控的违规用量。

GLM 发票申请与企业采购授权怎么走

智谱 GLM 开放平台按实际消耗金额开票，不按充值金额开票，赠送类金额一律开不出来；模型商用授权是面向开源模型权重的另一条独立流程，只对企业用户开放。这篇按财务和法务两条线，把开票口径、欠费影响、主体变更顺序、商用授权申请条件讲清楚。

GLM 按输入长度分段计价是什么意思：怎么把单次输入量算准

官方文档里关于 GLM 分段计价能核到的只有一条：部分推理模型会配置阶梯定价，用户权益的价格优惠对这类模型不生效，分几档、边界在哪都没有公开说明。这篇讲你自己能做的部分：用官方分词器接口把单次请求的输入 token 量算准，以及哪些内容会被算进输入。

GLM function calling 怎么写：从工具定义到结果回传

按官方文档梳理 GLM function calling 的完整写法：tools 里每一层字段的含义、tool_choice 只支持 auto 这个容易踩的限制、tool_calls 响应怎么解析、函数结果用什么结构塞回 messages，以及第二轮请求为什么还得带上 tools。

什么写法会打断 GLM 的缓存命中

GLM 上下文缓存是隐式触发的，没有开关，所以命不中的时候也没有报错。这篇按排查顺序拆开五类会打断 GLM 缓存命中的写法，从响应里的 cached_tokens 字段读起，到系统提示词里的时间戳、临时拼接的模板、被改写的思考内容，最后说清哪些情况官方文档根本没有说明。

GLM 上下文缓存怎么才能命中：触发条件与写法

GLM 的上下文缓存是隐式缓存，不用开关也没有手动声明的接口，命中与否完全取决于你把 messages 摆成什么样。这篇讲清楚触发条件、判断命中的那个响应字段、三种容易命中的写法，以及缓存对计费口径的影响边界。

GLM 鉴权失败逐条排查：从 API Key 到 JWT 签名

GLM 鉴权失败时该看哪一层：智谱开放平台把 401 拆成了四个业务错误码，分别对应请求头缺失、Key 无效、Token 过期和二次认证。这篇按真实排查顺序走一遍，顺带说清哪些看起来像鉴权问题其实不是。

GLM 接入 LangChain 怎么配：从 base_url 到 Agent

智谱 GLM 接入 LangChain 走的是 OpenAI 兼容路径，用 ChatOpenAI 换掉 base_url 就能跑。本文按官方文档梳理装包、配 Key、提示模板、对话记忆、Agent 与流式输出的完整配置顺序，并说清哪些地方官方没写、需要自己兜底。

GLM 的 OpenAI 兼容层边界：哪些参数它不认

智谱 GLM 提供 OpenAI 兼容接口，但兼容不等于等价。本文按官方文档梳理 OpenAI 兼容层的三类边界：查不到的参数、只能靠 extra_body 透传的原生字段、同名但约定不同的参数，以及响应侧多出来的取值，帮你把迁移风险提前挖出来。

GLM 限流字段怎么读：并发、频次与提额路径

智谱 GLM 的速率限制核心是并发请求数，不是每分钟请求数。这篇讲清楚限额在控制台哪几个页面看、通用 API 与 Coding Plan 两套口径的区别、撞限流时几个 429 错误码分别代表什么，以及提额申请该怎么走、什么情况下根本不支持申请。

GLM 流式输出下的工具调用怎么拼装：分片合并与踩坑清单

GLM 开启流式后工具调用参数分片下发，官方文档明说这些分片不做缓冲也不做 JSON 校验。本文讲清 stream 与 tool_stream 两个开关的关系、delta 三个字段的归属、按 index 归并分片的写法，以及边收边解析、丢失 tool_call_id 两个高频坑。

GLM 流式输出中断了怎么办：先看 finish_reason 再谈重试

GLM 流式输出中断时别急着抓错误码：官方文档说明推理过程中异常终止不返回业务错误码，异常原因写在 finish_reason 里。本文按排查顺序讲清连接层断开、服务端异常终止与安全审核拦截怎么区分，各取值该不该重试。

GLM 结构化输出怎么保证格式不跑偏

GLM 的结构化输出靠 response_format 开启 JSON 模式，但只开这个字段并不足以保证格式稳定。这篇按官方文档梳理字段取值、结构声明位置、客户端校验、finish_reason 截断识别与思考模式下的解析边界，给出一条能落到生产的防跑偏链路。

GLM 的思考 token 算不算钱：怎么把它控制住

GLM 开启深度思考后，思维链内容会不会计入账单？这篇按官方文档梳理 thinking、reasoning_effort、clear_thinking 三个开关的实际作用，以及 usage 字段该怎么读、账单变高该从哪几个方向排查，只讲计费机制不列价格数字。

GLM 思考模式怎么开怎么关：参数与适用场景

GLM 的思考模式不是「加个开关就完事」——新一代模型默认就在思考，有的型号还关不掉。这篇按官方文档梳理 thinking.type、reasoning_effort、reasoning_content 三个关键点，以及交错式、保留式、轮级思考各自的适用场景与写错会踩的坑。

GLM 账单突然变高怎么排查：五个常见原因

GLM 账单比上个月高出一截，先别猜。这篇按官方文档能查到的机制，把智谱开放平台账单异常拆成缓存失效、思考 token、搜索结果计入输入、按次计费模型、非调用型扣费五类原因，给出可执行的排查顺序与止血动作。

Grok 的数据处理与安全政策怎么读：从默认保留到 ZDR

逐条拆 xAI 官方安全 FAQ 里关于 Grok API 的数据处理条款：默认审计保留与训练政策的边界、Zero Data Retention 开启后会失效的功能清单、怎么用响应头确认 ZDR 生效、审计日志能查到什么、密钥泄漏的官方处置路径，以及企业合规资质走哪条口子问。

Grok 异步请求和延迟补全有什么不同：两种模式怎么选

Grok 的 async 异步请求和 deferred 延迟补全经常被当成一回事，其实一个在客户端并发、一个把请求拆成提交与取回两步。本文按官方文档梳理两者的调用形态、状态码语义、限流归属与适用场景，并给出和 Batch API 的分工判断。

Grok Batch API 怎么用：适用场景与提交形态

从官方文档出发讲清 Grok Batch API 的两种提交形态（SDK 攒请求与 JSONL 文件上传）、批状态计数器怎么读、结果怎么分页取回、成本字段在哪，以及哪些活值得改走 Batch、哪些不值得。

Grok 成本追踪怎么做：从单次请求拆到团队账单

Grok（xAI API）的成本追踪分三层：响应自带的 cost_in_usd_ticks 字段、控制台 Usage Explorer 的分组与过滤、Management API 用量接口。本文讲清每层能拆出什么维度、字段在哪、agentic 与流式请求的成本怎么归集。

Grok 上下文压缩机制怎么理解

拆解 Grok 官方文档里的 Context Compaction：它把长对话折叠成一个不透明的 compaction item，保留什么、丢掉什么、什么条件下才该调用、返回的 usage 字段怎么读、接回对话时有哪些官方点名的禁忌，以及它和提示缓存之间到底是什么关系。

Grok function calling 与工具体系怎么用

Grok 的工具体系分成 xAI 服务端自动执行的内置工具和要你自己跑的 function calling 两类，两者混用时的暂停点、max_turns 重置、类型判定字段最容易搞错。本文按 xAI 官方文档梳理工具定义、调用循环、tool_choice、并行调用与用量口径。

多轮对话里怎么让 Grok 的缓存一直保持命中

Grok 的提示缓存从 messages 数组开头逐条比对，多轮对话只要回头改一个字就整段落空。这篇按排查顺序讲清会话 ID 怎么固定、哪三类动作会打断前缀、推理模型为什么必须回传 reasoning_content，以及怎么用 cached_tokens 确认命中。

Grok 缓存怎么影响计费：省在哪、怎么看命中

Grok 的提示缓存自动生效，但省下来的钱到底记在哪个字段、命中率怎么核、账单怎么对，很多人没搞清。本文按官方文档梳理 Grok 缓存的计费口径、cached_tokens 的三种取值、cost_in_usd_ticks 的读法，以及命中长期为零时的排查顺序。

怎么把 Grok 的缓存命中率做上去

Grok 的提示缓存是自动开的，但命中率高低取决于你怎么组织请求。这篇按实际操作顺序讲清楚：cached_tokens 在三套 API 里分别读哪个字段、x-grok-conv-id 和 prompt_cache_key 怎么设、推理模型为什么最容易掉缓存，以及命中率上不去时的排查顺序。

Grok 提示缓存是怎么工作的

从 xAI 官方文档出发，讲清 Grok 提示缓存的前缀匹配机制、命中与未命中的判定、cached_tokens 字段在三套接口里怎么读、x-grok-conv-id 为什么能提高命中率，以及编辑、删除、重排历史消息为什么会把缓存整段打掉。

Grok 提示缓存最佳实践清单：六条官方建议逐条拆开讲

xAI 官方文档给 Grok 提示缓存列了六条最佳实践，这篇把每一条拆成可执行的动作：会话 ID 怎么传、消息数组为什么只能追加、推理模型多出哪一条硬要求、cached_tokens 从哪个字段读、命中不了该怎么排。附官方 FAQ 里最容易被误解的几个点。

通过 Microsoft Foundry 调用 Grok 模型：部署、鉴权与排错

拆解 xAI 官方文档里 Grok 模型在 Microsoft Foundry 上的接入路径：资源与项目怎么建、部署名为什么等于 model 参数、Entra ID 无密钥鉴权怎么配、报错该看哪几个请求 ID，以及从直连 xAI API 迁过来要改哪些地方。

Grok 模型退役了怎么迁移：官方给的重定向路径怎么读

xAI 在 2026 年 5 月 15 日退役了一批 Grok 模型，但退役后旧 slug 不会报错而是自动重定向。这篇讲清楚重定向落到哪个模型、推理档位被谁替你选了、账单口径怎么核，以及主动迁移该改哪几个字段。

Grok 的 mTLS 双向认证怎么配：企业网关接入实操

讲清 Grok（xAI）API 的 mTLS 双向认证怎么开通、换哪个端点、客户端证书怎么挂、两道校验分别返回什么错误码、证书轮换要不要联系官方，以及它和 API Key、团队权限、审计日志的关系。只讲机制，不列价格数字。

Grok 优先处理是什么：什么时候值得开

Grok 的优先处理（Priority Processing）就是在请求体里加一个 service_tier 字段，把请求排到标准流量前面。这篇讲清它改变的是调度顺序而不是容量保证、响应回执怎么确认是否授予、按更高单价计费的边界在哪，以及哪些调用路径开了才划算。

Grok 推理强度怎么控制：reasoning_effort 四档与推理 token 计费

讲清 Grok 的推理强度控制机制：reasoning.effort 与顶层 reasoning_effort 的优先级、四个档位官方各自的定位、推理无法关闭的说法差异、推理 token 在 usage 里怎么看，以及哪些参数和推理模型不兼容。

Grok 结构化输出怎么写：json_schema 与工具调用两条路

Grok 结构化输出有两条路：response_format 传 json_schema，或走工具调用的入参 schema。本文按官方文档梳理支持的 JSON Schema 子集、会被拒掉的写法、pattern 正则的语义差异，以及 parse 与 stream 两种取法怎么选。

Grok 团队管理与成员权限怎么设

从 xAI Console 的 Personal Team 讲到 Admin 与 Member 的权限边界、成员进出与 API key 归属、邮箱域名自动入队、Management API 建 key 与 ACL 授权，以及审计日志怎么查，帮你把 Grok 团队管理和成员权限一次配对。

通过 Google Cloud Vertex AI 调用 Grok 模型：启用与接入步骤

按 xAI 官方文档梳理 Grok 在 Google Cloud Vertex AI 上的接入路径：前置权限与 ADC 配置、Model Garden 启用步骤、模型 ID 以哪里显示的为准、两种调用形态、端点怎么选，以及从直连 xAI API 迁过来要改哪几处。

Grok WebSocket 模式怎么用：长连接续轮与断线重连

Grok 的 Responses API 可以跑在一条长连接上，每轮只发新输入。这篇按官方文档讲清楚 WebSocket 模式的开连接、warmup、previous_response_id 续轮、连接级缓存与 store 的关系，以及两个专属错误码怎么接。

Grok 限流字段怎么读、怎么申请提额

Grok 的限流按 RPS 和 TPM 两个维度、逐模型逐团队分配，档位由累计消费自动升。这篇讲清限流字段到底在哪读、哪些 token 会算进 TPM、撞上 429 之后官方给的处理路径，以及官方文档里写明的三条提额途径分别适合谁。

Grok 账单常见问题逐条解答：扣费时点、额度线与发票

把 xAI 官方文档里关于 Grok 账单的问题按排查顺序串了一遍：钱在哪一刻扣、预付点数和月结开票怎么并存、请求被拒到底是额度线还是限流、发票信息填错能不能补救、token 数为什么对不上，以及用哪些接口自己把账拆开看。

把 Agent 当成一个要上岗的员工来带：这个专题讲什么

我手上有三条在跑的 Agent 线，这篇给出贯穿全专题的一条判据——验收要回查目标状态，而不是看调用有没有报错——并交代七个阶段各讲什么、哪些是我真做过的、哪些至今没做通。

给 Agent 写「本期不做」：为什么这一段必须单独列

岗位卡里最容易被合并掉的就是「本期不做」。这篇给出三个当场能用的判据，说明哪些约束必须单独列成一段、怎么落到卡上的具体条目；不覆盖岗位卡其它段落的写法。

Agent 产物的自检要看内容特征，不是看文件名

我这条流水线上的封面文件名叫 .png，文件头却是 JPEG，本地一路不报错。这篇复盘它是怎么被发现的、为什么会这样、我把校验挪到了哪一步，以及从中带走的那条判据。本文不覆盖其它类型的静默失败，只扳「名实不符」这一类。

Agent 的成功标准要写成两组：做对了和做错了

岗位卡里的成功标准如果只写成一串目标，就验不出「事办成了但过程错了」这一类失败。这篇给出把成功标准拆成「做对了」和「做错了」两组的三个自检问法，以及我自己那份岗位卡里对应的段落长什么样。不覆盖指标怎么定阈值，也不覆盖上线之后的效果归因。

自用 Agent 走向可移交：要拆掉哪些东西

我把自己那个写公众号文章的 Agent 从「只有我能跑」改到「换个人也能跑」时，实际拆掉的三类东西：写死的本机路径、只在我脑子里的判断、只有我知道的验收标准。本文只写到「可移交」，不涉及接单、报价与对客户交付。

承认单个 Agent 的成功率明显低于 1

批量派活时，如果默认每个子代理都会把活干完，整条流水线的验收就会建立在假设上。这篇给出我判断「哪一步的成功是我假设的」的问法，以及我在编排里加的几处补偿动作；不覆盖模型选型和提示词写法。

第二个 Agent 岗位从哪开始：先写岗位卡还是先接工具

我开第二个 Agent 岗位时又一次从写岗位卡开始、而不是先接工具，这篇复盘我为什么停在「拆工序」这一步没往下走，以及我给自己定的开工条件。不覆盖这个岗位怎么实现——它还不存在。

Agent 的人工兜底和人工闸门不是一回事

岗位卡里「人工兜底」那一段常常被写成一张十来条的大清单。这篇给出一条决策路径，帮你把手上的每一条分到「常规必经」还是「异常触发」那一栏，以及混写之后最容易发生什么。本文不讨论闸门具体该卡在哪一步。

多个 Agent 会话并发在同一个仓库会互相踩踏

我在同一个内容仓库里同时开多个会话带子代理干活，撞出过两类踩踏：构建崩在别人的半成品文件上，共享的构建输出目录互相覆盖导致扫描结果失真。这篇写这两次是怎么被发现的、我把分工改成了什么、以及从中带走的那条并发边界判据。不覆盖多机分布式与团队协作的分支策略。

Agent 老出错：什么时候该改流程，什么时候该改提示词

派出去的活交回来不对，改提示词还是改工序？给两个当场能自己跑的判据——失败能不能重现、是不是压在同一步，并说明三种判据失效的情况。不覆盖模型选型和参数调优。

给 Agent 写岗位卡：六个必须写清的段落

一份岗位卡该按什么顺序写、每一段回答什么问题、漏掉会出什么事。读完能拿到一份可以照着填的段落清单和当场自检的问法。本文不讲判断依据怎么写，那是工作流卡片的事。

Agent 工序的边界该切在哪：三类位置

把一个 Agent 的活儿拆成工序时，每一刀落在哪里？本文给出我自己在用的三类切分位置和当场可自问的三个问题，并说明它们在什么情况下不成立。不展开失败回退边的逐条推导。

Agent 的关键外部能力要预留降级路径

我带的那个写公众号文章的 Agent 读不到原文，换一条路后读到了。这篇讲我怎么判断一次降级是合法的、什么时候必须停下来交给人；不讲怎么搭抓取工具链。

用固定红线扫描，不要求 Agent 每次去查最新规则

我给那个写公众号文章的 Agent 定的风险判断口径是一份固定红线清单，而不是每篇现查最新渠道规则。这篇讲我怎么判断哪些规则适合固定下来、这条取舍的代价是什么、以及什么情况下它不成立。不覆盖具体平台的规则内容。

什么时候该把一个 Agent 拆成两个岗位

手上已经跑通一个 Agent，又冒出一个相邻的新需求，是加个分支还是新开一个岗位？这篇给出我自己在用的两条判据——输入形态和成功标准——以及怎么落到岗位卡上；不覆盖多个岗位之间怎么协作调度。

Agent 批量生产：把核实从生产里拆出来单独做

复盘我这条批量写作流水线上的一次调整：为什么我不再让每个子代理自己去核事实，而是先把硬事实固化成一张卡再开工。只讲事实来源怎么组织，不讲编排代码怎么写，也不讲怎么变现。

Agent 的核实结果要分等级记录，不是核过和没核过两档

我在自己的流水线上把事实核验的记录从「核过／没核过」两档改成三档的一次复盘：怎么发现二值标记会把两种可信度完全不同的结论压成一样，改成什么，以及能带走的判据。不覆盖具体核验工具的选型，也不涉及自动化核验的实现。

Agent 失败之后退回哪一步：回退目标决定了工序怎么切

拆 Agent 工序时不知道该在哪里下刀，可以反过来从失败回退目标推。本文给出一句当场能问的判据，逐条讲我那条内容流水线上四条回退边为什么各退到那一步，以及这条判据在什么情况下给不出答案。本文不覆盖工序内部怎么写提示词。

Agent 的交付物不该只有终稿

我给自己那个写公众号文章的 Agent 定的交付形态不是一篇终稿，而是一个编号目录，把每个人工确认节点的输入与输出都单独落盘。这篇复盘为什么会变成这样、以及我实际改动过的是哪一处。本文不覆盖如何做内容质量评估。

Agent 产线的校验脚本：覆盖范围本身要写进清单

我这条内容产线上，新建聚合页漏登记了一处，而校验脚本全绿——复盘「脚本通过」怎么被我误当成了「全部检查过」，以及把脚本覆盖范围写进清单这个改法。本文不覆盖脚本的具体实现，也不讨论该用哪种校验工具。

Agent 干活里的静默失败：退出码 0 是怎么骗过所有人的

复盘我这条流水线上五类「没报错但事情没办成」的工程失败——它们长得不一样，骗人的方式却是同一种。读完能拿到我给自己定的四条回查纪律，以及一个反直觉的判断。本文不覆盖内容写作侧的失败模式，也不给通用架构建议。

Agent 不报错也不超时的失败，要怎么才能发现

我这条流水线上几次事故都属于「没报错、没超时、也没有任何红字」的那一类，本文复盘它们各自是被什么动作发现的、为什么天生没有信号，以及我把哪几处改成了回查目标状态。不覆盖监控告警系统的搭建。

没核实的要显式列出来，并禁止 Agent 推测

我这条内容流水线上，事实卡里空着的那几项被下游自己填满了。这篇写我是怎么发现的、留白为什么必然被填、以及我把"未核实"改成显式清单之后落下的三条写法。不覆盖核实等级本身怎么划分。

Agent 产物的命名要按峰值频次设计，不是按平均频次

我给一条内容流水线的产物目录改过一次命名规则，起因是同一天出的几个目录彼此认不出来。这篇讲我当时是怎么发现的、为什么日期粒度会失效、改成了什么，以及我从中带走的那条判断。不覆盖具体的目录结构设计方案。

Agent 写的东西：哪些段落可以口语化，哪些必须严谨

给 Agent 下「写得口语一点」或「写得严谨一点」都会把整篇拉向一端，本文给出我在写作判断卡里用的分区判据——开场、过渡、解释、个人观点可以松，事实、风险、承诺必须紧，以及它在哪些场景下不适用。本文不讲选题、不讲排版。

Agent 核验资料：哪些必须查证，哪些可以直接删掉

给写作 Agent 的资料核验定一条当场能用的分流判据——按「是否影响核心结论或读者决策」分流，并给出查证、删除、换角度三种处置；不覆盖检索工具与搜索词怎么选。

给 Agent 定目标：内部目标和对外承诺是两套口径

我给一个写公众号文章的 Agent 写岗位卡时，成功标准里放了流量方向的目标，后来在对外说明书里又写下「不承诺结果」。这篇复盘这两处口径为什么可以并存、我后来怎么把它们分开管，不覆盖具体指标怎么定。

Agent 的能力清单该怎么列

一个已经能干活的 Agent，它的能力清单该按哪几个维度分栏、每一格该写到什么程度，才能在出故障和交接时真正派上用场。本文只讲清单怎么列，不讲工具怎么选、也不讲怎么把某个能力接进来。

Agent 的判断点要成对写：怎么判，和为什么这么判

只写规则，Agent 遇到规则没覆盖的情况就会僵住或者乱来。这篇讲我给每条判断补一栏「判断依据」的做法、一个检验依据写没写到位的土办法，以及它在什么情况下会失效。不覆盖提示词的具体组织方式。

给 Agent 的判据要能当场执行，不能只给标准

规格里写「要准确、要中立」没用，因为执行者站在正文某一句前面判断不了这一句算不算。这篇讲我把标准改写成可当场执行的问句和动作的做法，以及哪些标准我至今找不到对应判据。不讲规则该配什么依据。

评审 Agent 必须有权质疑事实卡本身

我在自己的内容流水线上给评审 Agent 加了一个「对事实卡提异议」的返回字段，随后它连续查出我写的卡有问题。这篇讲这个权限口子为什么必须开、发现过程是什么、以及它改变了我对审查者职责的理解；不讲事实卡本身怎么写。

Agent 的 Profile 该分成哪几节

岗位卡写完之后 Agent 还是不知道下一步干什么，这篇给出我实际在用的 Profile 十节结构、每节的职责，以及判断一段话该放岗位卡还是放 Profile 的归位问法；不覆盖提示词写法与模型选择。

哪些权限不该给 Agent：按副作用划分，不按能力划分

多个 Agent 同时干活时，权限该怎么分？这篇给一条当场能用的判据——不看谁有能力做，只看动作会不会碰共享状态，以及判出来之后的两种处置。不覆盖单个 Agent 该配哪些工具。

把主语去掉，Agent 写的东西还成立吗

批量交上来的稿子看着都没错，但彼此能互换——本文给一条当场能做的自检动作：把主语删掉看文章塌不塌，以及它为什么比「内容要具体」有效。不覆盖事实是否正确的核对。

给 Agent 的任务书要当代码来维护

我给子代理写的一份内容规格被改了好几轮，每一轮都对应一次真实翻车。这篇复盘我怎么判断「是代理没干好」还是「是规格没写到」，以及规格该怎么改；不覆盖提示词写法本身。

同一个 Agent 的三份文档，颗粒度不必对齐

我给那个写公众号文章的 Agent 写了岗位卡、工作流卡片和 Profile 三份文档，步骤数对不上。这篇复盘我怎么发现的、为什么不去对齐，以及三份文档各自该管什么。不覆盖怎么从零写第一份岗位卡。

用删除测试压 Agent 写的提纲：删掉之后读者会失去什么

提纲阶段最难的不是挑错，是没法回答「这条要不要」。这篇给出我在自己那条内容流水线上用的替代问法——删掉之后读者会失去什么，以及配套那条防误删的限定。不覆盖正文写法与事实核验。

给评审 Agent 划权限：审查者不应该大于被审查者

给流水线加独立评审 Agent 之后，评审员能干什么、不能干什么需要单独设计。这篇给出我判断权限边界的三个问法，和我在评审员任务书里实际写死的那几条约束；不覆盖脚本层质量门的设计。

排查 Agent 接不上消息：身份授权和消息通道是两件事

我那条写作流水线在人工确认那一步静默停住过一次，提纲没到我手上。这篇复盘当时是怎么发现的、为什么身份和授权检查全绿也说明不了消息走通了，以及闸门那一处后来改成了什么。不覆盖任何平台接口的具体接法。

什么活值得交给 Agent，什么活交了反而更慢

拿我手上两条已经在跑的 Agent 线做对照，倒推出一条判据：人该站在流程中间还是两端，取决于单次产出的返工代价和批量规模。本文不比较快慢与成本，也不给通用的任务清单。

实现者和评审员必须是两个 Agent

批量交付时把「写」和「审」拆成两个互不通气的 Agent，本文给出当场可判的四个问题、落到编排里的具体写法，以及这条判据不适用的场景；不覆盖单篇创作和人工逐篇确认的场景。

把 Agent 的输出结构写死：每种词形各有固定段落

一批一批地生产内容时，最先塌的不是文笔而是骨架。这篇讲我怎么把每种词形的段落顺序写进任务书，以及那些标了「不许省」的段落为什么要单独点名。不覆盖选题、事实核验和内链回填。

Agent 调用没报错，不等于这件事办成了

我在三条互不相干的线上踩到了同一个形状的坑：脚本说已上线、编排说已完成、接口返回成功，实际上事情都没办成。这篇讲我是怎么发现的、为什么会这样，以及后来我给每个外部动作补的那道回查。不覆盖具体的重试与幂等实现。

给 Agent 分权：同步草稿和公开发布必须拆成两级

给 Agent 授权时，「哪些动作它自己做、哪些必须回来问我」不该按重要程度划，而该按可逆性划。这篇给出我在一条内容流水线上用的分级判据和它的三处边界，不覆盖闸门该设在流程哪一步的推导。

把通用约束抽成简报，每次给 Agent 派活只描述差异

我这条内容流水线的派活提示曾经长到自己都挑不动，后来按「下一批还用得上吗」把约束拆成三层，单次任务书只留差异。写的是分层的判据，不覆盖「翻车之后怎么回写规格」那一步。

文件落盘不等于子代理写完了

我在自己那条批量写作流水线上，把「文件出现了」当成子代理写完的信号，结果提交进去的是半成品。这篇复盘怎么发现的、为什么会这样、改成了什么。不覆盖版本管理工具本身的用法，也不覆盖单篇人工精修的场景。

让 Agent 判断选题值不值得做：三个硬门槛

我在写作 Agent 的工序里给「选题是否值得写」这一步定了三个当场能判的硬门槛，这篇讲三条门槛各挡掉什么、不合格之后往哪退、以及想加第四条时怎么自问；不覆盖选题怎么找、也不覆盖内容分发。

Agent 的验收样本要按失败分支覆盖，不是按成功次数累计

我给自己那个写公众号文章的 Agent 补验收样本时，发现样例全是同一条顺利路径的副本。这篇写我当时是怎么发现的、把待补场景按什么维度重列的，以及一条未必适用于你的判断。不覆盖测试框架与自动化用例的写法。

验证 Agent 产物的手段自己失效了怎么办

我这条产线上撞到过四类「检查返回通过、但检查本身已经不成立」的情况，这篇复盘它们是怎么暴露的、我把口径改成了什么。不覆盖如何写检查脚本，也不覆盖内容质量本身的判断。

给 Agent 写一句话岗位定义：把触发、范围、交付终点压进一句

岗位卡第二段那句话怎么写才不落空——用触发、处理范围、交付终点三个成分自查，并解释为什么这句写的是目标态而不是现状。不覆盖工序拆分和权限分级。

自用 Agent 走向可移交：硬编码路径是第一批要拆的

复盘我自己那条内容流水线上的一件事：成果目录曾写死成本机绝对路径，自用时一次都没出过问题，直到准备让别人也能跑才浮出来。本文只讲这一项——它是怎么被发现的、为什么改、以及为什么它总是第一个卡住人；不覆盖可移交要拆的其它部分。

多 Agent 协作：有副作用的动作要收归单点串行

我这条产线上把子代理并行起来之后遇到的一次构建崩溃，以及后来定下的分工——子代理只写各自的内容文件，构建与提交由主导者独占串行。本文只写这一次的经过与改法，不展开怎么给动作分级。

给 Agent 设人工闸门：该卡在返工成本跳变的位置

我给一个写作 Agent 画完流程图，把人工节点上色之后才发现闸门不是均匀分布的，而是密集地卡在几个特定位置。这篇是我事后反推出来的规律，以及为什么发布权要单独拆一道闸。不覆盖闸门的具体交互实现。

Agent 质量门的误报比漏报更危险

我这条内容流水线上，一道机械质量门首轮报出的问题全部是误报，同一道门先后修了至少三次修的都是误报。这篇讲我当时是怎么发现的、判据为什么要写窄，以及为什么误报的代价不是多花时间。不覆盖具体脚本实现和事实级核验怎么做。

Kimi 流式输出断了怎么自动重连：判据、续写与账单

Kimi API 流式输出中途断开时，怎么判断到底传完没有、怎么重连、怎么用 Partial Mode 从断点接着写，以及重连之后 Tokens 用量该怎么补算。按官方文档给出的判据、错误类型和排查顺序整理，附上重连救不了的几种情况。

Kimi 余额查询与用量监控怎么做：接口字段、项目预算与账单对账

Kimi 开放平台的余额查询接口返回哪三个字段、available_balance 归零后会报什么错、项目日月预算和消费提醒各管什么、账单跟客户端记录对不上时按什么顺序查。全部按官方文档口径讲机制，不列价格数字。

Kimi Batch API 怎么提交和查询

讲清 Kimi Batch API 的完整链路：JSONL 输入文件的四个必填字段、purpose 与 completion_window 怎么填、八种任务状态各代表什么、结果文件和错误文件怎么取回，以及官方文档里两处对不上的地方。

Kimi 批量推理适合什么场景：Batch API 的门槛与取舍

从官方文档拆解 Kimi 批量推理的适用边界——Batch API 锁死了哪些参数、completion_window 决定了什么、状态机怎么轮询、结果文件怎么回连业务主键，以及哪些任务根本不该丢进批量推理。

在 Claude Code 里配置 Kimi：环境变量、模型档位与排错

按 Kimi 官方文档梳理 Claude Code 接入 Kimi 的完整步骤：先清理旧配置，再选终端变量或 settings.json 两种方式之一，配齐各档位模型变量，用 /status 验证生效，并给出 401、model not found、思考未开启等常见报错的对照排查。

在 Codex CLI 里配置 Kimi K3：CC Switch 路由完整步骤

Codex CLI 走 Responses API，Kimi 给的是 OpenAI 兼容的 Chat Completions，协议对不上才要 CC Switch 转换。本文按官方文档拆在 Codex 里配置 Kimi 的四步流程、高级配置取值，以及配完不生效怎么按错误码定位。

Kimi 错误码对照与处置：401/403/429/504 分别怎么查

按 Kimi 官方错误码文档整理的排查路径，讲清 error.type 比 HTTP 状态码更重要的原因，401 的平台隔离、403 的三种权限拒绝、429 的三类成因、504 与 Connection 错误的处理，以及账单异常该带哪些材料反馈。

Kimi 动态工具加载是怎么回事：按需注入工具与前缀缓存

Kimi 动态工具加载允许在对话中途用一条携带 tools 字段的 system 消息按需注入工具声明，缓解工具定义膨胀。本文按官方文档讲清注入格式、可见性规则、与前缀缓存的叠加条件，以及模型支持范围和 400 报错这两处最容易踩的限制。

Kimi 计算 Token 接口怎么用：调用前把 token 数和成本估出来

Kimi 开放平台的计算 Token 接口（estimate-token-count）能在发起对话补全之前算出这组 messages 要占多少输入 token。本文讲清它的入参出参、官方推荐的用法、成本估算算式，以及预估值和实际账单对不上的几种原因。

在 Hermes Agent 里用 Kimi 模型：配置字段与常见问题

按 Kimi 官方文档梳理 Hermes Agent 接入中国区 Kimi 开放平台的四步路径：选中国区 Provider、写自定义 Provider 配置、启用视频工具，以及模型列表没有 kimi-k3、连错 Endpoint、429 这几类问题官方给的判法。

Kimi 上下文缓存怎么用：自动命中的条件与失效场景

Kimi API 的上下文缓存没有"创建缓存"这一步，它对所有模型请求自动启用、按前缀匹配命中。这篇讲清命中的条件、messages 该怎么摆、怎么用 cached_tokens 确认命中、prompt_cache_key 是干什么的，以及动态加载工具时哪些改动会把前缀缓存打碎。

Kimi JSON mode 与 response_format 怎么用

Kimi 的 response_format 有 json_object 和 json_schema 两种模式，即 JSON Mode 与 Structured Output。本文按官方文档讲清机制差异、strict 与 MFJS 规范、字段缺失的表达，及解析失败的排查顺序。

用 MoonPalace 调试 Kimi API 调用

MoonPalace 是 Moonshot AI 官方提供的 Kimi API 调试工具，启动后把 base_url 指向本地即可截获完整请求。本文按官方文档梳理安装、启动、日志字段、三种检索 ID 的对应关系、重复输出检测与强制流式两个选项，以及导出 Case 的完整流程。

在 OpenClaw 里用 Kimi 模型：K3 配置与排错

按 Kimi 官方文档梳理在 OpenClaw 中接入 Kimi K3 的完整路径：装官方 Moonshot Provider、跑 onboard 向导选中国区认证、模型列表里没有 K3 时怎么手改配置，以及 401、认证选项缺失这些常见问题的官方处置说法。

在 OpenCode 里配 Kimi K3：内置认证、选模型与推理强度

按 Kimi 官方文档梳理 OpenCode 接入中国区 Kimi 开放平台的完整路径：先确认余额与 IP 白名单前提，再用 opencode auth login 选 Moonshot AI (China) 填 Key，用 /models 选 Kimi K3、用 /variants 调推理强度，并给出配完仍报 401、404、429 的官方排查顺序。

Kimi 的 Partial Mode 是什么：怎么让它按你给的开头往下写

Kimi API 的 Partial Mode 就是在 messages 末尾追加一条 partial 为真的 assistant 消息，让模型强制以你给的内容开头继续生成。本文讲清它的开启方式、拼接前缀的必要动作、续写被截断输出的完整流程、name 字段的作用，以及它和 JSON 模式混用时的官方限制。

Kimi 的 reasoning_effort 怎么调：low/high/max 三档怎么选

Kimi K3 的思考关不掉，reasoning_effort 是唯一能调推理深度的旋钮。这篇讲清它放在请求哪一层、三档官方怎么定性、为什么中途换档会破坏前缀缓存，以及从 K2.x 和 OpenAI 代码迁过来分别要改什么。

Kimi 思考模型怎么用：和普通模型的调用差异

Kimi 思考模型比普通模型多出一个 reasoning_content 字段，还多出 thinking.type、thinking.keep、reasoning_effort 三个控制入口。这篇按官方文档梳理各模型的参数差异、reasoning_content 的正确读法、多步工具调用的配置要求，以及保留式思考对上下文与计费的影响。

Kimi 的 tool_choice 怎么控制模型调不调工具

讲清 Kimi API 里 tool_choice 的四种取值怎么选：auto 默认自行判断、required 强制走工具链路、none 只出纯文本、传函数对象强制指定工具，并说明哪些 Kimi 模型不支持 required、和思考开启冲突时会报什么错、以及它对前缀缓存的影响。

Kimi 的限流机制怎么读：并发、RPM、TPM、TPD 四道闸

Kimi API 的限流由并发、RPM、TPM、TPD 四道闸共同衡量，任意一道先到就触发 429。本文按官方文档讲清限速额度与账户等级的关系、网关按 max_completion_tokens 预扣额度这条反直觉规则，以及收到 429 后怎么按 error.type 分诊。

哪些平台兼容 Anthropic API：这条路怎么走，坑在哪

智谱 GLM、MiniMax、Kimi、阶跃星辰都提供了 Anthropic Messages 协议的兼容端点，xAI 则已把这层标为废弃。本文按官方文档对照兼容层的接入方式、参数取舍、模型名映射与鉴权变量，讲清 Anthropic 兼容到底兼容到哪一步、哪里会静默出错。

Batch 批量接口机制对照：GLM、Kimi、Grok、Gemini 差在哪

把智谱 GLM、Kimi、Grok、Gemini 四家 Batch 批量接口的官方文档摊开对照，讲清提交形态、请求对账字段、单批能不能混模型混端点、状态机结构、结果拉取方式、超时过期后谁付费，以及限流账本为什么是分开的一本，帮你在写批量任务代码前先选对平台。

编程场景选模型平台要看哪几件事：套餐、宿主工具与额度窗口

编程场景选模型平台，真正决定体验的不是模型名字，而是套餐额度窗口的形状、能不能在你的宿主工具里用、Base URL 与 Key 怎么分叉、额度耗尽后会发生什么。本文按官方文档逐条对照 GLM、MiniMax、阶跃、Kimi 与 xAI 的机制差异，给出一张可以照着过的选型检查表。

从 OpenAI 迁到国产模型平台：一份可执行的迁移检查清单

各家都说改 api_key 和 base_url 就能迁过来，但真正让线上出事的是被静默忽略的参数、拿不到的思考内容、搬不动的 JSON Schema 和完全不同的错误码体系。这份从 OpenAI 迁移的检查清单按真实改造顺序列出每一项该核什么，全部对照官方文档。

模型 API 各家错误码风格不一样：怎么做一层统一封装

智谱 GLM、Kimi、MiniMax、阶跃星辰、Grok、Gemini 六家的错误码放在不同层、用不同键、同一个 HTTP 状态码底下含义还完全不同。这篇按官方文档逐家拆开错误码结构，给出一层统一封装该保留哪些字段、怎么分类、哪些类别才允许退避重试。

多厂商模型网关怎么设计：把 API 差异挡在业务代码之外

接了两家以上模型 API 之后，差异会顺着业务代码到处渗。这篇按官方文档逐条对照智谱 GLM、Kimi、MiniMax、阶跃星辰、xAI 与 Gemini 的接入形态、思考参数、错误语义、流式异常和限流维度，给出多厂商网关该在哪几层做隔离。

结构化输出对照：GLM、Kimi、Grok、阶跃星辰的 response_format 差异

同样叫 response_format，各家支持的档位并不一样。这篇按官方文档对照 GLM、Kimi、Grok、阶跃星辰的结构化输出实现，讲清 json_object 与 json_schema 的分界、strict 与 additionalProperties 的默认方向差异，以及跨家迁移时最容易翻车的几处。

各家的 OpenAI 兼容到底兼容到什么程度：六个平台的兼容层对照

OpenAI 兼容不是一个开关。本文按 base_url、端点清单、参数取舍、专有能力出口四层，把智谱 GLM、Kimi、阶跃星辰、MiniMax、Gemini、xAI 六家官方文档里明写的兼容边界摆出来，说明为什么跑通 hello world 不等于兼容。

换模型平台之前，这份迁移检查清单先过一遍

换模型平台不是改一行 base_url 那么简单。这份迁移检查清单按真实操作顺序排了八项：兼容层形态、Key 归属、模型名下线、思考参数、缓存字段、限流维度、错误码封装、切流前回归，每一项都标明各家官方文档的具体差异点在哪。

思考 token 算不算钱：GLM、Kimi、Grok、Gemini 计费口径对照

推理模型的思考内容到底算不算 token、算在输入还是输出、能不能关掉，六家平台的官方口径并不一致。这篇把 GLM、Kimi、Grok、Gemini、MiniMax 与阶跃星辰的思考 token 计费与控制机制逐条对照，只讲机制不列价格。

各家限流维度不一样：RPM、TPM、RPD 之外还有什么

把六家模型平台的官方限流文档摊开对照，会发现 RPM、TPM、RPD 只是其中一部分口径：并发数、每秒请求数、每日 token、每小时窗口积分、最大并行任务数、请求爬坡速率都在被限。这篇讲清各家限流维度的结构差异、触发关系与归属主体。

大模型 API 的国际站和大陆站怎么选？账号、域名、模型都不通用

同一个厂商的国际站与大陆站往往是两套独立体系：API Key 不通用、接入点不同、可用模型不是一套、定价表分开、免费额度还可能只在某一个地域有。按官方文档梳理五条差异和一套决策顺序。

换一家大模型 API，除了 base_url 还要改什么？迁移自查清单

OpenAI 兼容层能让你只改一行配置就调通新厂商，但调通不等于迁移完成。专有参数的挂载位置、用量字段名、限流尺子、缓存模式、错误码语义、计价形态这六样都会变。这篇给一份逐条对照的迁移清单。

大模型 API 的免费额度和赠金有什么区别？四个容易踩的口径

免费额度、赠送余额、代金券、资源包看着都是「不用花钱的钱」，但扣费顺序、算不算消费、有没有地域限制、用完会不会自动转付费这四条规则各不相同。按官方文档逐条对齐，附一份开户当天就该填的自查清单。

标点恢复：ASR 输出没有句号该怎么办

语音识别的声学模型通常不吐标点，标点得靠一个独立的后处理模型补。这篇讲清它常见的序列标注建模方式、流式场景里"标点要看后文、输出却要立刻给"的根本矛盾，以及中文逗号用法宽松带来的评测困难，并附一张断句错误的排查表。

ASR 服务的并发与批处理：请求该怎么排队

流式语音识别是长连接，一路对话从接通到挂断始终占着资源，容量模型和 Web 服务那套按每秒请求数估算的方法完全不同。这篇讲清楚为什么要按并发路数算容量、实时与批量两类请求为什么必须分开调度、攒批在两边的取舍差在哪，以及并发打满时为什么明确拒绝远好过让所有人一起卡顿。

自建 ASR 测试集：数据怎么选、标注怎么做

用公开数据集给自己的业务打分，几乎一定会得到虚高的成绩。这篇讲怎么用真实业务录音搭一个能指导决策的 ASR 测试集：按真实分布采样、规模够不够怎么判断、必须先定死的标注规范清单、双人标注的质控流程，以及建好后怎么用才不会失效。

长音频怎么切：切分点选错会吃掉哪些字

两小时的会议录音不能整段丢给识别模型，必须先切成片段。这篇讲为什么必须切、按什么切、切坏了有哪些症状：切点落在语音中间会吞字，重叠区不去重会重复，漏了回加时间戳偏移会让字幕整体错位。附流程与故障对照表。

两个人同时说话，语音系统怎么办

真实会议里抢话、附和、插话时时刻刻在发生，但多数说话人分离系统的聚类假设是"同一时刻只有一个人"。这个假设被打破时，重叠段会被硬指派给其中一人，另一人的话直接消失——转写读起来依然通顺，你根本不知道少了东西。这篇讲清重叠语音难在哪，以及检测、分离、产品降级三条处理路径各自的代价。

说话人分离和声纹识别，不是一回事

说话人分离、声纹识别、语音分离，这三个词在中文里被混用得很厉害，但它们回答的是完全不同的问题。这篇用一张对照表把三者钉死，讲清楚为什么分离给出的只是"说话人1、说话人2"这种匿名标签、为什么认出"这是张三"必须先注册，以及在会议纪要这类真实场景里它们是怎么串成一条链的。

端侧离线语音识别：手机上为什么跑得动

端侧 ASR 靠更小的模型结构、量化和算子融合压缩计算量，再配合专为端侧优化的推理引擎与 NPU 加速跑起来。这篇讲清它换来的三样真收益——隐私不出设备、无网可用、无按次费用，以及必须接受的代价：精度与词表受限、模型更新只能随 App 走。

多人会议分轨：先分离说话人还是先识别

会议转写要的不只是文字，还得知道每句话是谁说的。说话人分离和语音识别谁先谁后，是两条工程路线的分岔口。这篇讲清 diarization 的经典流程、两种顺序各自的代价、为什么边界问题谁都躲不掉，以及说话人数未知时聚类会怎么出错。

ITN 逆文本规范化：把「二零二五年」变成「2025 年」

ITN 是语音识别最后一环里的文本改写步骤，方向是口语形式转书面形式。这篇讲清它和 TTS 前端 TN 的镜像关系、规则与神经网络两条实现路径，以及为什么歧义是它最难啃的骨头——还有一个容易被忽略的事实：ITN 出错常被误当成识别不准。

降噪和回声消除，该放在 ASR 前面还是交给模型

回声消除必须放在管道最前面，因为它要拿到设备正在播放的参考信号；但降噪不一样，它未必是净收益，用力过猛会削掉语音本身的谐波结构。这篇讲清两者的摆位逻辑、四类噪声的不同对策，并给出一张"要不要降噪"的判断表和一份先测再降的验证清单。

梅尔频谱和 fbank：ASR 的输入为什么不是原始波形

语音识别系统吃进去的不是波形，而是梅尔滤波器组特征。这篇讲清三件事：为什么要先分帧、为什么频率轴要按梅尔刻度重新划分、fbank 和 MFCC 差在哪一步又为什么现在主流用 fbank，并给出一张可以直接照着做判断的对照表。

热词怎么配：让 ASR 认出你的专有名词

日常对话识别得挺好，一到公司名、产品名、人名就翻车，这是语音识别落地最常见的痛点。本文讲清热词（上下文偏置）改的到底是什么、三类做法的适用面、热词表怎么整理与验证，以及权重开太大导致误触发的副作用。

RTF 实时率怎么读：多快才算够快

RTF 等于处理耗时除以音频时长，是衡量语音识别快慢最常被引用的指标，也是最容易被误读的一个。这篇讲清 RTF 能回答什么、不能回答什么：为什么从 RTF 推出的并发数只是理论上限，为什么流式场景真正该盯的是首字延迟而不是 RTF，以及看到一个 RTF 数字时你必须追问哪几件事。

声纹识别的两个阶段：注册与验证

声纹识别不是"听一段就知道是谁"，它必须先注册后比对。这篇讲清注册阶段采集了什么、验证阶段比的是什么、1:1 验证和 1:N 辨认为什么难度不同，以及最关键的那个工程决策——相似度阈值该调高还是调低，两个方向各自会付出什么代价。

字级时间戳是怎么来的：ASR 的对齐机制

字幕跟不跟得上嘴、点一句能不能跳到对应位置，靠的都是时间戳。这篇讲清楚字级时间戳的三种来源——CTC 峰值定位、强制对齐、注意力权重推断，各自的原理、前提和精度差异，以及工程上最容易踩的那个偏移坑。

语音识别是怎么工作的：从声波到文字的四个环节

语音识别不是一个模型从头干到尾，而是音频前处理、特征提取、声学建模解码、文本后处理四个环节接力。这篇把每一环的职责、常用做法和它出错时的典型症状讲清楚，让你听到一段转写结果不对劲时，能直接判断问题出在哪一环，而不是笼统地说"这个模型不行"。

VAD 是什么：ASR 前面为什么总要挂个断句器

VAD 判断音频里哪些段有人在说话，把连续音频切成语音片段。这篇讲清它的三个职责、静音时长阈值与前后 padding 各自管什么、能量阈值型和神经网络型的边界，并给出一张调参后果表，看到吞字、切碎、粘连这类症状时知道该动哪个旋钮。

WER 怎么算：一个公式说清语音识别的准确率

WER 是衡量语音识别错误率的标准指标，公式看着简单，真正容易出错的是分母取谁、三类错误怎么对齐出来、以及它为什么能超过 100%。这篇带你手算一遍完整例子，把替换、删除、插入逐个标出来代入公式，同时讲清这个单一数字掩盖了什么。

采样率、位深、声道：喂给 ASR 的音频该长什么样

识别不准，有时候不是模型的问题，是喂进去的音频本身就不合格。这篇讲清 ASR 对采样率、声道、位深、增益和编码格式的具体要求，说透电话音频为什么升采样也救不回来，并给出一张从症状反推音频参数问题的排查表。

中文语音识别为什么看 CER 不看 WER

中文书面语没有天然词边界，换一个分词器就能让同一次识别算出不同的 WER，指标因此不可比。这篇讲清楚中文为什么改按字算 CER、中英混说该怎么定口径，以及 CER 自己掩盖了哪些差异，并给一张检查清单：拿到一个错误率数字时，你该追问哪几件事才能判断它值不值得信。

识别准确率被高估的三种常见情况

报告里的准确率好看，拿业务音频一试就崩，落差多半来自评测方法的口子。这篇讲清测试集重叠、评测前归一化、音频裁剪三种情况的机制，外加只报平均值的陷阱，并给出一份追问清单。

Claude Code 报 Connection lost mid-response 怎么办？写了一半的回答其实还能接着用

完整报错是 API Error: Connection lost mid-response. The response above may be incomplete. 它和 Connection closed mid-response、Response stalled mid-stream 是同一族——官方文档写明 v2.1.227 前后改过名。本文说清这几种形态各自意味着什么、为什么它偏偏不重试、已经写出来的那半截还能不能用、以及怎么让它接着往下走。

Codex 无法归档对话、归档失败怎么办？先分清是命令没找到会话，还是文件没挪成

Codex 无法归档对话的报错，其实分得很清楚：一类是命令压根没找到你要归档的那条会话，一类是找到了但文件挪不动。这篇按 openai/codex 仓库里的归档实现，把归档失败的每种报错原文、触发条件和验收方法列出来，包括 /archive 在子会话里不可用、选择器里 Ctrl+A 不出现、以及取消归档为什么可能比归档更容易失败。

Cursor 的 Ctrl+K 怎么用？行内编辑和 Chat 的分工

Cursor 的 Ctrl+K 是行内编辑，选中代码直接就地改，不用开侧边面板；本文讲清基本用法、Alt+Enter 切到提问模式、怎么追加指令继续改，以及什么时候该按 Ctrl+L 换成 Agent。

Cursor 以前的对话怎么找回？聊天记录搜索和分享

Cursor 的历史对话可以在 Agents 窗口用命令面板全局搜索，长会话内部用查找键跳转匹配；本文还讲清共享转录怎么发、能被谁看到、脱敏为什么不能全指望它，以及哪些档位才有这个功能。

Cursor 突然多扣钱了？花费上限和超额提醒怎么设

Cursor 账单超出订阅费，多半是开了按量付费；本文讲清 on-demand 的触发条件、Spending 面板里花费上限怎么设、触顶后会发生什么、团队和企业的多层上限怎么叠加，以及提醒和上限的区别。

Cursor 快捷键有哪些？常用键位和改键方法

Cursor 快捷键沿用 VS Code 那一套，另外加了几个 AI 专用键；本文列出官方文档给的 AI 快捷键、讲清改键面板怎么打开、按键冲突从哪里查，以及主题和字体在哪调。

Cursor 怎么取消订阅？退款和 iOS 内购的处理办法

Cursor 取消订阅在 dashboard 的 billing 页走 Stripe 门户完成；本文讲清取消后还能用多久、找不到取消按钮的四种账号状态、iOS 内购为什么只能找苹果，以及退款审核看的是哪两个条件。

Cursor 怎么自动生成 commit message？Git 功能全解

Cursor 在源代码管理面板上加了 AI 能力，暂存改动后点提交框里的星标图标就能按 diff 生成 commit message；本文还讲清合并冲突怎么交给 Agent、AI 提交署名怎么关、以及 Cursor Blame 在标什么。

Cursor 团队版怎么开通、怎么邀请成员和踢人

Cursor 团队版在 dashboard 点 Create Team 建起来，邀请成员选管理员或成员角色；本文讲清席位怎么计费、中途加人退人的账怎么算、不占席位的管理员是什么、以及管理员跑路了怎么办。

Cursor 会拿我的代码去训练吗？隐私模式怎么开

Cursor 隐私模式（Privacy Mode）开了之后代码不会被用于训练；本文讲清它在哪开、团队怎么强制、代码到底发给了谁、零数据保留在什么情况下不成立，以及自带 API key 时规则为什么变了。

豆包 API Key 怎么申请？从火山方舟拿到 key 再跑通第一次调用

豆包 API Key（写成 api key 或 apikey 都是它）到底在哪申请：火山方舟控制台的申请入口、key 在请求里长什么样、model 字段填接入点 ID 还是模型名、调不通时 401/403/404/429 各指向什么，以及用量账单在哪看。只讲机制，不写会变的数字。

GLM API Key 怎么申请？在哪找、怎么用、额度在哪看

GLM API Key 申请全过程：按智谱开放平台官方文档走一遍从注册账号到第一次调用，讲清 glm apikey 在控制台哪个入口新建、放进代码的正确姿势、编程套餐 Key 和通用 API Key 为什么不通用，以及常见的几种「key 用不了」分别对应哪个错误码、额度和账单该去哪个页面查。

Kimi API 怎么接入？从拿 Key 到第一次调用跑通

按官方文档梳理 Kimi API 的接入路径：服务地址与认证方式、OpenAI 兼容能覆盖到哪、哪两个专有参数必须换写法、新账户第一次调用最容易卡住的四个地方，以及接入后立刻要做的三件事。

minimax_h3_fl2va_int8_convrot.safetensors 是什么文件、该放哪个目录

把 minimax_h3_fl2va_int8_convrot.safetensors 这一串粘进搜索框的人，多半是在下载页或工作流里看到了它却不知道它是什么。本文按 Hugging Face 仓库 API 返回的文件清单，讲清它与 minimax_h3_fl2va_pruned_int8_convrot.safetensors 的关系、文件名里 fl2va / pruned / int8 / convrot 各是什么意思、该落到 ComfyUI 的哪个目录，并说明 pt_h3concatavlatent 这个串我们在官方仓库里没能核实到。

阿里云百炼上能调 Qwen3.8-27B 吗：核实结果和替代路径

很多人默认「千问的模型去百炼调就行」，但开源的 Qwen3.8-27B 和百炼上架的型号并不是一回事。本文核实百炼当前的 qwen3.x 型号清单，说明官方商业服务与开源权重的分工，并给出想用 27B 时的几条实际路径。

只想用 Qwen3.8-27B 的文本能力：纯文本入口存在，但权重得换一份

三个推理框架都注册了纯文本入口类，config.json 里也有一个 language_model_only 字段。但官方发布的权重走的是多模态那条路，想真正跑纯文本，关键不在启动参数而在你用的是哪份 checkpoint。

Qwen3.8-27B 的图像怎么变成 token：从 16 像素的块到 5120 维的向量

视觉塔输出 5120 维，正好等于语言模型的隐藏维度——这不是巧合，是让图像特征能直接拼进文本序列的前提。本文按 vision_config 的字段走一遍装配路径，并数一数那几个视觉特殊 token 的编号。

Qwen3.8-27B 的线性注意力用哪个内核：vLLM 按显卡代次三选一

那 48 层线性注意力在 vLLM 里有三套预填充内核实现，选哪一套取决于显卡架构、CUDA 版本和一个恰好等于 128 的配置字段。其中一套是即时编译的，这解释了为什么首次运行可能特别慢。

Qwen3.8-27B 支持哪些推理框架：四家的核实结果与核实方法

vLLM、SGLang、transformers、llama.cpp 对 Qwen3.8-27B 的支持状况逐一核实，附上具体的文件位置与注册项。更重要的是给出核实方法——因为分发平台的支持标签会骗人，命名风格差异也会让你误判成不支持。

llama.cpp 转 Qwen3.8-27B 时改了什么：48 个 V 头要重新排队

把这个模型转成 GGUF 不是格式平移。因为 16 个 K 头配 48 个 V 头，而 ggml 的广播顺序与 HF 权重的存储顺序不一致，转换脚本要对六类张量做 V 头重排，还要给一个上游可能缺失的字段补零。

Qwen3.8-27B 能加 LoRA 吗：框架声明了七个可适配模块

推理框架的源码里明确列出了这个模型支持 LoRA 的模块清单。看清单能知道哪些位置能挂适配器、哪些不能，其中线性注意力的融合投影在列而另一个相关模块不在，这个差别值得留意。

ModelScope 上的千问3.8-27B：和 Hugging Face 那份是不是同一个

国内下载 Qwen3.8-27B 通常走 ModelScope。本文用两边的公开 API 逐字段核对架构、许可与更新时间，确认是不是同一份权重，并解释那个「后端支持」字段为什么全是 null——以及为什么不能据此判断框架不支持。

Qwen3.8-27B 的 MTP 在推理时干什么：一个拼接、一次降维、一层全注意力

配置文件里 MTP 只有一层，看不出它怎么工作。读 vLLM 的实现会发现它有自己的词嵌入、一个把两份向量拼起来再降维的线性层，以及一层被硬编码成全注意力的解码层——这三件东西合起来就是多 token 预测的全部结构。

用 Ollama 本地跑 Qwen3.8-27B：标签写着 256K，你拿到的可能只有 4K

拉下来能跑只是第一步。Ollama 的默认上下文长度是按显存自动分档的，最低一档只有 4k——哪怕模型标签上写着 256K。本文讲这条规则、怎么改、以及怎么用一条命令确认自己实际拿到了多少。

Ollama 上 qwen3.8 的十二个标签：默认拉到的是哪一个

Ollama 官方库里 qwen3.8 有十二个标签，但只有八个不同的 digest。本文把标签、digest 与体积逐一对照，指出三个标签共享同一份内容、以及默认拉到的其实是带 MTP 的版本这两件事。

OpenRouter 上的 Qwen3.8-27B 怎么调：八家供应商给的参数并不一样

同一个 qwen3.8-27b，在 OpenRouter 的八家供应商那里量化精度、上下文上限、最大输出长度都不同，其中一家报的上下文是别家的近四倍。本文讲怎么用 endpoints 接口把这些差异查出来，而不是照着首页那个数字下单。

Qwen3.8-27B 的权重名字怎么对上框架：三类映射规则各管一段

checkpoint 里的张量名和推理框架里的模块名对不上是常态。vLLM 用三类规则来抹平这段差距——前缀改写、堆叠融合、打包映射。读懂它们能解释为什么有的权重会被丢弃、有的会被拼起来。

Qwen3.8-27B 的 RoPE 维度 64 是怎么来的：一个乘法和一次求和

config.json 里没有任何字段直接写着 64。但 partial_rotary_factor 乘 head_dim 等于 64，mrope_section 三段之和的两倍也等于 64。两条互相独立的路径指向同一个数，顺带说明为什么 rope_type 写的是 default 而不是 yarn。

SGLang 为什么给 Qwen3.8-27B 写了三个文件：入口拆分不是功能拆分

SGLang 的 qwen3_5 有三个文件，其中一个只有 225 行。读下来会发现拆分依据是模型入口而不是功能，而且它对混合注意力的组织方式与 vLLM 明显不同——一个拆成两个类，一个用一个类按参数分支。

Qwen3.8-27B 的思考模式为什么老是关不掉：三层各管一段，别在错的层找开关

模板层、框架层、API 层各有一套控制思考行为的机制，参数名还长得很像。搞不清哪一层管什么，就会出现「参数传了但没生效」的情况。本文把三层的职责分开摆清楚。

transformers 里的 Qwen3.5 建模代码：28KB 的定义展开成 88KB 的实现

同一个模型在 transformers 里有两份代码，一份用继承写、只有 28KB，一份是完整独立的实现、有 88KB。读前者能一眼看清这个模型继承了谁、改了什么，比啃后者高效得多。

Qwen3.8-27B 的 64 层在 vLLM 里怎么分流：一个字符串决定走哪条路

config.json 里的 layer_types 是 64 个字符串，但字符串本身不干活。本文读 vLLM 的 qwen3_5.py，看它怎么按下标取出这个字符串、二选一构造出线性注意力层或全注意力层，以及线性那一支为什么落在了 Mamba 的代码目录下。

Qwen3.8-27B 要多少显存：把这笔账拆成四份分别算

「27B 模型要多少显存」没有单一答案，因为它至少是四笔账：权重体积、KV cache、线性注意力状态、运行时开销。本文给出每一笔的算法与可核实的官方标注值，并解释为什么这个模型的 KV cache 只由 64 层里的 16 层产生。

Qwen3.8 系列有几个型号：27B、2.4T-A95B 和 Max 各自去哪儿拿

Qwen3.8 这个名字下面挂着三个差别很大的型号，一个稠密开源、一个稀疏开源、一个闭源旗舰。本文用各平台的公开接口把三者的架构类别、分发渠道和获取方式对照清楚，包括一个能一眼分辨开源与否的字段。

长文本合成怎么切：按章节、句子还是标点

一本书不能一次性丢给 TTS。这篇讲长文本合成的切分策略：为什么必须切、按句子边界还是按固定字数切、跨片段的音色漂移与拼接爆音怎么缓解、段落停顿为什么必须自己插静音。附一张拼接故障与成因的排查表。

TTS 缓存策略：哪些句子值得缓存

最快的语音合成是不合成。但缓存不只是"把结果存下来"：哪些句子存了有用、拼接式缓存省下的成本要拿什么体验来换、缓存键漏掉一个字段会引发怎样的生产事故，这篇一次讲清楚。

声音克隆的授权与合规：哪几条线不能碰

声音克隆的技术门槛已经很低，真正的门槛变成了"你有没有权利用这个声音"。这篇从本人授权、用途限定、可识别性、平台条款四条原则出发，给出一份动手前的自查清单，帮你在开工之前把该问的问题问清楚。

流式 TTS：首包延迟为什么是最该盯的指标

很多人拿"合成一段话要几秒"来衡量 TTS 快不快，这个口径在流式场景下会把你带偏。这篇讲清首包延迟由哪几段构成、为什么它比总耗时更决定体验、生成速率跟不上播放速率时会发生什么，以及压缩首包的五个具体着手点和一套自己就能做的测量方法。

MOS 是什么：语音合成的主观评分怎么打

语音合成好不好听，最终裁判是人耳，MOS 就是这套人耳打分的标准做法。这篇讲清 MOS 的定义与量表、它为什么是相对值而不能跨论文横向比较、CMOS 与 SMOS 各自适合什么场景，并给出一份组织可信主观评测的操作清单。

TTS 前端文本处理：多音字、数字、英文缩写怎么读对

合成音听着别扭，问题常常不在声学模型，而在前端。这篇讲清中文 TTS 前端的四类难题——多音字消歧、数字读法依赖语义、英文缩写没有通法、断句决定可懂度，并给出一张「读错类型 → 成因 → 怎么修」的排查表和三个立刻能用的修法。

语音合成的情感和语气怎么控

让合成语音带上情绪，工程上主要有三条路：选预设标签、给参考音频、用一句话描述。这篇讲清三者的可控粒度、稳定性与适用场景，并把最容易被忽略的那条规律说透——控制信号给得越硬，语音越容易僵，可控性和自然度往往此消彼长。

语音合成是怎么工作的：从文本到波形的三段流水线

语音合成不是一个模型把文字直接变成声音，而是前端文本分析、声学模型、声码器三段接力。这篇讲清每一段的职责、它们之间为什么要停在梅尔频谱这个中间站，并给出一张"症状到段落"的定位表，让你听到合成音不对劲时能直接判断该修哪一段。

声学模型和声码器：TTS 两段式结构讲清楚

语音合成为什么要在文字和声音之间插一张梅尔频谱？这篇讲清声学模型和声码器各自在解决什么问题，重点讲透声码器为什么难——频谱丢掉了相位，从频谱恢复波形是个欠定问题，并给出声码器三条技术路线的对照表。

声音克隆是怎么做到的：零样本与微调两条路

声音克隆的技术核心是把音色和内容解耦——模型从参考音频里抽出说话人嵌入，再用这个音色去说任意文本。这篇讲清解耦为什么让零样本成为可能，零样本与微调各自的输入、优点、代价和适用场景，以及实践中最容易被忽略的两件事：参考音频的缺陷会被一起学走，"像"和"好听"根本不是一回事。

合成语音听起来像机器的五个具体原因

说合成语音"听着不自然"等于什么都没说。这篇把它拆成韵律、停顿、音色、非语言现象、情感匹配五个具体问题，说清每一个出在前端、声学模型还是声码器，并给出一张从症状定位到流水线环节的对照表。

语速、停顿、多音字：合成结果怎么精细调

合成音大体能听，但语速偏赶、某处该停没停、一个专名读错——这篇讲拿到一段不满意的音频后，怎么一处处调回来。含一张「不满意的地方 → 优先试哪个手段 → 还不行试什么」的分级修法表，以及调不动时的务实退路。

WorkBuddy 崩了、崩溃闪退怎么办？先分清是进程退了还是界面卡住

WorkBuddy 崩溃、闪退、白屏、点不动，用户嘴里都叫「崩了」，但在官方那里是四类不同的问题。本文给一张三十秒分诊表，再按官方更新日志里真实修过的诱因逐类展开，说明日志该去哪里取、崩完之后会话和产物还在不在，以及哪几种是官方已经承认暂时无解、只能等版本的。

微软 AI Agent 入门课第 11 课：WorkflowBuilder 怎么串起三个 Agent

拆 ai-agents-for-beginners 第 11 课的 A2A 示例代码：三个专职 agent 各自的角色定义写在哪、WorkflowBuilder 怎么把它们连成一条边、事件流按什么字段分段，以及这份 notebook 与真正的 A2A 协议之间隔着什么。顺带对照同一课 MCP 示例，看两个协议在代码里落在了不同的参数位。

Agentic RAG 检索谁来决定：微软 AI Agent 入门课第 5 课的 @tool 封装

ai-agents-for-beginners 第 5 课把检索封装成 tool 交给 agent 调用，而不是在生成前固定跑一遍。本文顺着 05-agentic-rag 的 Python notebook 走一遍：搜索函数怎么用 @tool 装饰、要不要检索的决定权落在哪、Python 与 .NET 两份示例接文档源的路子有何不同，以及冒烟测试断言了什么。

签名票据的防护拦在哪一层：微软 AI Agent 入门课第 18 课

ai-agents-for-beginners 第 18 课用签名票据给 agent 的工具调用留审计痕迹。把它接进自己的项目后，最常见的困惑是分不清验证失败到底卡在签名、链接还是授权哪一层。本文顺着 sample_receipts 里三个 fixture 的数据形态，把课程演示的几条攻击路径和它们各自的拦截点拆开，并说明哪几层这套代码压根不拦。

Agent 安全防哪几类风险：微软 AI Agent 入门课第 18 课的 verify_chain

ai-agents-for-beginners 第 18 课讲的不是提示注入清单，而是「审计员凭什么相信你的日志没被改过」。本文沿着 18-securing-ai-agents 的两个 notebook 走一遍，把课程真正设防的几类风险与它们在 verify_receipt、verify_chain、verify_envelope 里对应的那几行检查一一对上，并交代收据明确不证明什么。

AzureSearch.md 的 Python 与 .NET 两份代码：微软 AI Agent 入门课

ai-agents-for-beginners 的 00-course-setup 里给了 Azure AI Search 的 Python 与 .NET 两份建索引示例，字段定义写法并不一样。本文把索引与字段定义、连接配置项、两种语言的写法逐项对上，并交代仓库里写明的边界与验证点。

微软 AI Agent 入门课第 17 课：本地 Agent 不连云端怎么跑

ai-agents-for-beginners 第 17 课把 Agent 从云端搬到单机。本文顺着这一课的 README 与 notebook，讲清 FoundryLocalManager 怎么接出本地端点、工具调用循环为什么要手写、Chroma 那段本地 RAG 的代码与文档不一致在哪，以及它跟第 4 课云端示例差在哪几处。

微软 AI Agent 入门课第 15 课：browser-use 接入与任务描述

ai-agents-for-beginners 第 15 课把 Browser-Use、Playwright 和 CDP 串在一起跑浏览器自动化。这篇按仓库里的 15-browser-use/README.md 与 15-browser-user.ipynb，讲清它的接入链路、Agent 任务描述的写法、结构化抽取用的 Pydantic 模型，以及课程自己划出的边界和几处源内不一致。

微软 AI Agent 入门课第 16 课：自带 skill 写了哪些部署步骤

ai-agents-for-beginners 的 .agents/skills/deploying-scalable-agents/SKILL.md 把第 16 课压缩成一份可执行清单。本文沿着这份 skill 逐块拆开它列的步骤、它指向的部署产物（hosted agent、smoke-test workflow、测试目录），以及 notebook 里那几个真正管伸缩的配置项，并标出 skill、课程 README 与代码三处对不上的地方。

对话越滚越长：微软 AI Agent 入门课第 12 课的摘要接在哪一步

ai-agents-for-beginners 第 12 课给了一个 summarize_preferences 摘要工具，但照着加完会发现历史一点没变短。本文沿着 12-chat_summarization.ipynb 的代码，把摘要的触发位置、被摘走的内容范围、摘要结果的回填形式三件事逐一定位，并给出排除其它原因的判定动作。

01-python-agent-framework.ipynb 拆解：微软 AI Agent 入门课

第一课的 notebook 只有寥寥几个 cell，真正卡住人的是三处：client 用什么参数初始化、agent 由谁构造出来、run 的调用形态为什么有两种。本文对着仓库里的这个文件逐块拆，并把依赖版本上那处容易踩的不一致标出来。

微软 AI Agent 入门课的 .NET 示例跑不起来：SDK 版本与包引用对一遍

ai-agents-for-beginners 的 .NET 示例是单文件应用形态，没有 csproj，靠文件头的

微软 AI Agent 入门课第 8 课的多智能体：角色、消息与终止条件怎么写

ai-agents-for-beginners 第 8 课把多智能体讲成了设计模式，但真正动手时卡住的是三件事：角色到底写在哪个参数里、一条消息怎么从上一个 agent 走到下一个、什么时候算跑完。本文沿着该课 code_samples 下的 Python notebook 与 .NET 示例，把这三处在代码里的确切位置找出来。

在 Azure AI Foundry 里建 Agent：微软 AI Agent 入门课给的完整步骤

ai-agents-for-beginners 的第 02 课带了一份门户建 Agent 的动手练习，从建 hub、部署模型一路走到 playground。这篇把练习文档里写明的每一步拆开说清在改什么，补上课程环境配置那一课要求的权限与依赖，并指出门户产物与 notebook 代码之间到底靠哪两个变量对接、哪些地方仓库里没有给说明。

Azure AI Foundry 权限报错：微软 AI Agent 入门课的前置条件

跟着 ai-agents-for-beginners 第 2 课建 Agent，卡在建 hub 或建项目的权限上是最常见的一类中断。这篇按仓库里 azure-ai-foundry-agent-creation.md 与 00-course-setup 白纸黑字写明的角色与资源要求，把「先确认哪一层」「缺什么补什么」「哪些报错其实不是权限」逐条拆开。

GitHub Models 跑微软 AI Agent 入门课示例：token 报错

从旧教程或旧 fork 里抄来的 GITHUB_TOKEN 配置，在 ai-agents-for-beginners 当前版本上跑不通。本文按仓库里的 .env.example、00-course-setup/README.md、各课 notebook 与迁移 skill，把「缺哪个环境变量」「权限范围是什么」「哪条报错对应哪个配置项」逐条对上号，并说清哪些报错跟 token 根本没关系。

微软 AI Agent 入门课第 7 课的规划：TravelPlan 在哪一步被推翻

ai-agents-for-beginners 第 7 课讲规划设计，但课程正文与配套 notebook 给的计划结构并不是同一个。本文沿着 07-planning-design 的 README 与 07-python-agent-framework.ipynb 走一遍：计划的字段怎么定义、response_format 怎么把它变成硬约束、concierge 怎么执行、以及重规划的触发点写在哪里。

微软 AI Agent 入门课环境配置：requirements.txt 与 .env 怎么填

ai-agents-for-beginners 的 notebook 打开就跑不通，多半卡在依赖版本、环境变量少填、或者 Python 与 .NET 两条路线的准备步骤串了。本文按仓库 00-course-setup/README.md 与各章代码样例，把依赖、变量清单、两条路线的差异和验证方式逐条对上。

微软 AI Agent 入门课第 6 课：人工介入的中断点设在哪一行

ai-agents-for-beginners 第 6 课的 README 片段把审批放在模型输出之后，配套 notebook 06-human-in-the-loop.ipynb 把它挪到了动作执行之前。本文沿 run_with_revision、tiered_gate、gate_action 这条调用链，说清中断点落在哪一行、驳回后什么被回传。

记忆写进去读不出来：微软 AI Agent 入门课第 13 课两种实现的存取键

第 13 课给了两份记忆实现，一份用进程内字典，一份用 Cognee 知识图谱。两份都存在写的时候好好的、换个会话就读不出来的坑，但坑的位置完全不同。本文按现象、判定动作、处置、验证、排除的顺序，把两份 notebook 里的键构造、作用域和清理时机逐行对出来。

微软 AI Agent 入门课第 13 课的记忆结构：两种实现的抽象不同

ai-agents-for-beginners 第 13 课给了两个 notebook，一个把长期记忆存成进程内的 dict，一个交给 Cognee 的知识图谱。本文沿着两份代码走一遍：数据写进去时是什么形状，取出来时走的是哪条路，以及两处仓库里白纸黑字的不一致。

微软 AI Agent 入门课怎么定义 Agent：第 1 课划的最小构成

ai-agents-for-beginners 第 1 课没有用形容词定义 Agent，而是把它压成三个部件，再用一份 notebook 把这三个部件落到几行代码上。本文沿着 01-intro-to-ai-agents 的 README 与 Python/.NET 两份示例走一遍，指出「聊天机器人」与「Agent」在代码里究竟差在哪一个参数上，以及第 1 课埋了哪个没解释的开关。

可信 Agent 怎么写：微软 AI Agent 入门课第 6 课的系统消息框架

ai-agents-for-beginners 第 6 课里最能直接搬走的，是「用 LLM 生成 system message」的四步框架。本文沿该课 README 与 06-system-message-framework.ipynb 逐格走一遍：meta 提示词、产出的结构化骨架、鉴权与四个可选参数，以及校验环节究竟在哪。

Client/Agent/Tools/Session 四层：微软 AI Agent 入门课第 2 课全景

第 2 课给了三份代码示例，很多人当成三条并列教程去读。本文按课程自己给出的 Client、Agent、Tools、Session 四层视角，把一次「查目的地是否可订」的请求沿着代码走一遍，标出每层在哪个文件、对应哪个类名与配置项，并指出 notebook 说明文字与可执行 cell 之间的一处不一致。

接 MCP：微软 AI Agent 入门课第 11 课的 client 与 server 最小实现

以 ai-agents-for-beginners 第 11 课的 mcp-agents 示例为准，逐段拆开 server 端怎么用装饰器暴露工具、client 端怎么发现工具并把参数填进去，以及一次 tools/call 在两端代码里各经过哪些对象。附前置条件、Windows 侧启动方式、示例代码里明确写死的边界，以及连上之后该看哪几行输出确认配对成功。

MCP 连不上：微软 AI Agent 入门课 client 端连接流程逐步核

ai-agents-for-beginners 第 11 课的 mcp-agents 示例跑不通时，别急着怀疑网络。本文顺着 client/client.py 的代码把一次连接拆成取 token、建传输、建 session、initialize、list_tools 五段，指出每段对应的报错长什么样、怎么定位，以及哪些现象说明问题根本不在连接上。

MCP 会话断了怎么续：微软 AI Agent 入门课的 resumable client

ai-agents-for-beginners 的第 11 课带了一套可续跑的 MCP 客户端与服务端示例。这篇按排查顺序拆开看：事件存到哪张表、重放时到底重放哪一段、以及重启客户端后「说是在恢复但什么都没发生」时该看哪几行日志、哪几个文件。

两个 notebook 的记忆存取路径：微软 AI Agent 入门课第 13 课

ai-agents-for-beginners 第 13 课给了两份记忆实现，一份把偏好塞进进程内的字典，一份挂在 Cognee 知识图谱上。本文顺着两个 notebook 的代码，逐个指出存储后端在哪、写入调用点在哪、召回调用点在哪，以及 README 与代码对不上的几处。

Microsoft Agent Framework 从哪抄起：微软 AI Agent 入门课第 14 课

ai-agents-for-beginners 第 14 课把同一个订房场景写了好几遍，条件路由、middleware、人工介入各占一份。本文沿着 code-samples 目录里的代码走一遍：一次工具调用从 @tool 到 yield_output 经过哪几层，几个示例分别在这条骨架上加了什么，以及同目录两份写法不一致时该照哪一份抄。

basic/sequential/concurrent 差在哪：微软 AI Agent 入门课第 8 课

第 8 课 workflows-agent-framework 目录下的三个 Python notebook，正文铺陈很长，真正的差别集中在 WorkflowBuilder 那几行。本文按仓库代码逐个拆开 add_edge、add_fan_out_edges、output_executors 的连接方式与结果汇聚差异，并指出 README 与 notebook 之间几处对不上的地方。

notebook 依赖装不上或版本打架：微软 AI Agent 入门课的三处依赖源

ai-agents-for-beginners 的依赖不止 requirements.txt 一处，每课 notebook 第一格还会自己 pip install，个别课还带精确钉版。本文按仓库里的三处依赖来源梳理冲突从哪来、怎么用仓库自带的判定动作确认，以及哪些报错其实跟依赖无关。

Agentic RAG 检索为空：微软 AI Agent 入门课第 5 课三层排查

跑 ai-agents-for-beginners 第五课的 Agentic RAG 示例时，Agent 一本正经地说知识库里没有这条信息。本文按工具返回结构、查询字段对应、索引字段声明三层拆开，逐层给出可在 notebook 里执行的判定动作，依据全部来自课程仓的 05 章代码与 Azure AI Search 配置文档。

微软 AI Agent 入门课第 12 课：summarize_preferences 落在五块里的哪块

ai-agents-for-beginners 第 12 课把 Agent 要管的上下文拆成五类，并配了一个 Python notebook 做摘要示例。本文沿着 12-context-engineering/README.md 与 12-chat_summarization.ipynb 走一遍：五类分别对应代码里的哪一行，summarize_preferences 这个工具究竟压缩了哪一块，以及仓库里那个 scratchpad 文件为什么和 notebook 对不上。

微软 AI Agent 入门课第 3 课的 Agentic 设计模式：notebook 里是哪三个

ai-agents-for-beginners 第 3 课的 README 讲的是人机交互层面的设计原则，而同一课的 Python notebook 落地的是另外三个代码模式。本文沿着 03-python-agent-framework.ipynb 从 provider 初始化走到两个单一职责 agent 的手工串联，标出每个模式对应的类名、装饰器与配置项。

微软 AI Agent 入门课第 10 课：报销 demo 里可观测与评估落在哪几行

ai-agents-for-beginners 第 10 课讲的是把 Agent 送进生产环境需要的可观测与评估，但同章那个报销单 demo 打开后并没有 tracer。这篇沿着 10-expense_claim-demo.ipynb 的代码路径走一遍，指出可观测、错误处理、评估这三块在这个 notebook 里实际落在哪几处、哪一块干脆不在这里。

.agents/skills/：微软 AI Agent 入门课怎么固化一套工作流

ai-agents-for-beginners 仓库里藏着一个 .agents/skills/ 目录，把「验证课程 notebook」「迁移到 Responses API」这类反复要讲的流程写成了文件。本文沿着 SKILL.md 的结构约定、frontmatter 里的触发写法、以及 references 子目录的分工走一遍，顺带指出仓库里两处对不上的地方。

工具注册了却不被调用：从微软 AI Agent 入门课的插件测试文件反查

工具都传给 agent 了，模型却始终用自然语言糊弄过去，一次 tool call 都不发。本文按 ai-agents-for-beginners 第四课 04-tool-use 的测试文件与 Python notebook，给出一条从「工具对象在不在」到「描述与参数注解写没写」的反查路径，并说明哪些现象不属于这个原因。

微软 AI Agent 入门课第 4 课的工具注册：函数怎么变成能调的工具

沿着 ai-agents-for-beginners 第 4 课的 Python notebook 走一遍工具注册：@tool 装饰器把普通函数变成工具时读走了哪些信息，Annotated 参数注解落到哪里，tools 该挂在 as_agent 还是 run 上，以及这一课里 response_format 的说法与代码对不上的那处落差。

workflow 条件分支不走：微软 AI Agent 入门课第 8 课的判定写在哪一行

第 8 课的条件工作流示例最常被问到两种症状——该拦的稿子进了发布分支，或者审完之后整条流程没了下文。这篇沿着 04.python-agent-framework-workflow-aifoundry-condition.ipynb 把条件节点的定义位置、判定值的来源、以及分支未命中时图上会发生什么，逐处指到具体函数与具体那一行。

MCP 与 A2A 的代码入口在哪：微软 AI Agent 入门课第 11 课

ai-agents-for-beginners 第 11 课同时讲 MCP、A2A、NLWeb 三个协议，但代码目录里能跑协议的只有一条链。本文顺着 11-agentic-protocols/code_samples 走一遍：两个 notebook 分别模拟了什么、真正的 MCP 客户端与服务端在哪个文件、一次 travel_agent 调用经过哪些回调，以及三个协议在代码层面的落差。

微软 AI Agent 入门课第 9 课的元认知：自评插在哪、评完给谁用

ai-agents-for-beginners 第 9 课讲元认知，但真正要落地只有两个问题：自评这一步写在流程的哪个位置，以及评估出来的那段文字被谁消费。本文顺着 09-metacognition 的 notebook 一行行走，标出两个自评插入点、评估结果的去向，并对照第 16 课里那个真的会拦住发布的 evaluation_gate。

Claude Code 的 advisor 与 ultrareview：两个容易被忽略的机制

Claude Code 里有两个都在「叫一个更强的脑子来看一眼」的机制，但触发权不在同一个人手里，产出也落在不同的地方。本文按官方文档梳理 advisor 与 ultrareview 各自的触发条件、生效前提与结果形态，以及各自在什么时候会静默不生效。

Agent 循环里每一轮发生了什么：Claude Agent SDK 的 agent loop 拆解

用 Claude Agent SDK 写 agent，最常见的困惑是「它到底什么时候停」。本文按官方文档《How the agent loop works》一页，把一次会话拆成轮，说清一轮由哪几个阶段构成、每个阶段吐出哪种消息、以及循环终止的几条互不相同的路径与对应字段。

Claude Code 的 agent teams 跑不起来：成员、视图与任务分派的前置条件

你让 Claude 开一支 teammate 团队，面板里确实多了几行，可按名字发消息对不上、共享任务列表也找不到。官方文档写明 agent teams 是 experimental 且默认关闭，还有一串前置条件。这篇按「现象—判定—处置—验证—排除」把开关、目录、成员表、任务分派与显示模式逐条对回文档原文，Windows 侧单列。

让 Claude Code 走 Amazon Bedrock：环境变量、区域与凭证怎么对

按 Claude Code 官方文档梳理接入 Amazon Bedrock 的完整链路：开关变量 CLAUDE_CODE_USE_BEDROCK、区域解析的四级顺序、跨区域推理配置文件前缀、五种凭证来源与 IAM 权限项，并说明哪些能力在 Bedrock 上明确不可用、配完之后怎么验证。

Claude Code 的 channels 怎么用、怎么排查：reference 页的字段表怎么读

channels 让外部事件直接推进正在运行的 Claude Code 会话。本文按官方文档梳理 channel 的字段语义——capabilities 声明、notification 的 content 与 meta、permission_request 的四个字段——并把「事件不到达」「回复不生效」这几类常见配置错误拆成可执行的判定动作与处置步骤。

Claude Code 的检查点回滚不回来：checkpointing 存了什么、没存什么

回滚之后文件还是改过的样子，往往不是 checkpointing 坏了，而是那次修改根本没被记进去。本文按官方文档梳理检查点的覆盖范围、文档明写的五类不可恢复情形，以及怎么用 /debug 日志和跳过计数把「没记进去」和「回滚失败」区分开。

Claude Code 配置改了不生效：配置优先级与官方给的诊断动作

改了 settings.json 却像没改过，多半不是 bug，而是同一个键被另一层覆盖了。本文按 Claude Code 官方文档梳理五级配置优先级、managed 层内部的取用顺序，以及 /context、/status、/doctor、safe-mode 这几个能直接跑的判定动作，并说明什么情况下说明问题不出在优先级上。

Claude Code 的上下文窗口是怎么被填满的：构成拆解

新开一个会话、还没输入第一句，上下文里就已经装了一批东西；干活之后涨得也比"读了两个文件"要快。这篇按 Claude Code 官方文档把占用来源逐类拆开——启动即装载的六类、干活中的增量、subagent 的独立窗口、压缩后哪些回得来，并给出 /context 与 InstructionsLoaded hook 这两个可执行的判定动作。

Claude Code 跨会话消息发不出去：cross-session messaging 的前置与限制

让一个 Claude Code 会话给另一个会话捎句话，看着是开箱即用，实际卡在版本、操作系统、provider、feature flag、接收侧 crossSessionInbound 这一长串前置上。本文按官方文档梳理一套可执行的判定顺序，以及什么情况说明问题根本不在这条链路上。

Claude Code 桌面版在 Linux 与 WSL 上的已知限制

桌面版的 Code 标签页在 Linux 与 WSL 上都缺一部分能力，官方文档把这些限制分散写在三页里。本文按「现象→怎么判定→文档给出的处置→怎么验证→什么情况说明不是这个原因」逐条拆开，帮你区分「这个平台本来就没有」和「你的环境配坏了」。

在 devcontainer 里用 Claude Code：容器内的权限与网络前置

按 Claude Code 官方文档梳理 dev container 的接入路径——feature 怎么加、重建后为什么会掉登录、managed-settings.json 放在哪、出口防火墙需要哪些 capability，以及容器边界到底管不管得住什么。含 Windows 侧差异与验证清单。

Claude Code 报错速查：官方 errors 页把错误分成了哪几类

终端里蹦出一行英文报错，直接拿整句话去搜往往搜不到。Claude Code 官方文档的 Error reference 页其实自带一张索引表和一套分类，本文只做分类与分流：这一页把运行时错误分成了哪几类、每一类的第一步该做什么、怎么确认自己分错了类，以及哪些症状根本不该在这一页找。

Claude Code 的 LLM 网关协议长什么样：gateway 这一层替你挡了什么

自建网关接 Claude Code，最难的不是把流量代过去，而是搞清楚哪些请求头和 body 字段必须原样转发、哪些可以自己消费。本文沿着官方 Gateway protocol reference 走一遍一次请求的路径，标出格式选择变量、attribution block 的位置性剥离、header 与 body 的成对失效，以及模型发现的过滤规则。

在 GitHub Actions 里跑 Claude Code：workflow 怎么写、密钥怎么给

按 Claude Code 官方文档梳理 claude-code-action 的接入过程：workflow 文件里哪些字段是必须的、两种鉴权 secret 分别对应哪个输入、交互模式与自动化模式由什么决定，以及走 Bedrock / Agent Platform / Foundry 时凭证怎么通过 OIDC 接进来。附边界与验证方法。

在 GitLab CI/CD 里跑 Claude Code：与 GitHub Actions 不通用的那几处

手上是 GitLab，搜到的教程却全是 GitHub Actions 的写法，照抄一定跑不通。这篇按 Claude Code 官方文档的 GitLab CI/CD 页，逐个说清 GitLab 侧真正要写的配置字段——masked 变量、job 里的 image 与 rules、before_script 装 CLI 后为什么要改 PATH、AI_FLOW_* 从哪来、id_tokens 怎么换云厂商凭证，以及哪些能力在这一页里根本没有对应说明。

Claude Code 到底怎么工作：官方文档画出的那条主循环

你敲一句「把失败的测试修好」，中间几十次动作只剩滚动的输出。这篇按 Claude Code 官方文档《How Claude Code works》与《Extend Claude Code》两页写明的路径走一遍主循环，标出工具在哪一步介入、扩展层挂在循环的哪个点、上下文满了先丢什么、你能在哪几个位置插手，以及文档在哪些地方根本没给答案。

大仓库里 Claude Code 变慢、找不到文件：官方 large codebases 页给出的做法

大仓和 monorepo 里，Claude Code 常把上下文花在与任务无关的说明和文件读取上。按排查顺序走一遍官方文档写明的做法：怎么用 /context 与 /status 判定，claudeMdExcludes、Read 拒绝规则、worktree.sparsePaths、additionalDirectories 各管什么，以及哪些现象说明不是这个原因。

让 Claude Code 走自建 LLM 网关：connect 与 rollout 的两阶段

公司要求模型流量统一从自建网关出去，Claude Code 这边到底要配哪几个变量、管理员那边要按什么顺序放量？本文按官方文档梳理 connect 页的配置项与 rollout 页的五步检查点，含 Windows/PowerShell 写法与不支持的场景。

Claude Code 托管 MCP 与自配 MCP 冲突了怎么办：接管边界划在哪

公司发了托管配置之后，自己加的 MCP 服务器不见了、claude mcp add 直接报错、甚至启动就退出。这篇按 Claude Code 官方文档梳理 managed-mcp.json 的接管规则：它覆盖掉哪些来源、哪些设置还能继续过滤它、三句错误文案分别对应哪种机制，以及哪些症状说明根本不是托管策略在拦你。

Claude Code 的记忆没被读到：memory 的加载位置与优先级

写在 CLAUDE.md 里的规则像没生效、auto memory 明明存过却没被引用、/compact 之后指令又消失了。这三类现象在官方文档里对应的是不同的加载路径。本文按官方文档梳理记忆文件的存放位置、加载顺序、可执行的判定动作，以及什么情况说明问题根本不在加载上。

公司网里 Claude Code 连不上：network config 页列的代理与放行项

在有代理、有防火墙的公司网络里跑 Claude Code，最常见的卡点是代理变量写法不对、放行清单漏了主机、或者变量根本没送到进程里。本文按官方 network config 页的字段逐条讲：怎么判定、怎么改、改完怎么验证，以及哪些现象其实不是代理造成的。

Claude Code 的权限模式选错会怎样：六档各自放开了什么

很多人以为 Claude Code 的权限模式只有「问」和「不问」两种。官方文档的模式表里其实列了六档，每一档放开的动作范围各不相同。这篇按排查思路走一遍：模式没按你设的生效、切了 acceptEdits 还在被问、dontAsk 下什么都跑不动、auto 模式挡了正常动作，分别怎么确认、文档给的处置是什么，以及什么情况说明根本不是模式的问题。

Claude Code 插件装了不加载：依赖、提示与相关性三层各卡在哪

插件「没出现」其实是三件不相干的事：依赖没满足被禁用、CLI 发的安装提示没触发、marketplace 声明的 relevance 建议没显示。本文按官方文档梳理每一层的判定动作、处置方式，以及什么情况说明根本不是这一层的问题。

Claude Code 的提示缓存是怎么命中的：缓存边界在哪一段

从「会话中途换了模型，下一轮忽然变慢」这个现象出发，沿 Claude Code 官方文档描述的请求拼装路径走一遍：请求分成哪几层、哪些东西不在提示文本里却算进缓存键、哪些动作会把整段前缀作废、哪些只是往末尾追加。全文只写机制与字段名，不涉及价格与命中率数值。

Claude Code 的远程控制连不上：Remote Control 与 deep links 的两条链路

「远程连不上 Claude Code」常常是两件不同的事：一条是 Remote Control 的会话链路，一条是 claude-cli:// deep link 的系统注册链路。本文按官方文档，把两条链路各自的前置条件、判定动作、错误文案对应的处置以及验证方法分开讲清楚，并给出「什么情况说明不是这个原因」。

Claude Code 的 routines 怎么写：把重复流程固化下来

逐项拆解 Claude Code 官方文档里 routine 的定义结构——prompt、仓库、环境、connectors、triggers 五块分别在改什么，三类触发方式各自的配置口径与限制，以及 research preview 阶段必须照实知道的边界与验证方法。

Claude Code 沙箱相关的报错怎么分流：是沙箱拦的还是权限拦的

一条 Bash 命令失败了，到底是操作系统层的 sandbox 边界挡住的，还是权限规则在命令跑起来之前就拦下的？这两层的拦截时机不同，留下的现象也不同。本文按官方文档写明的机制，给出可执行的判定动作、分层处置和验证方式，并单独交代 Windows 侧的情况。

Claude Code 的沙箱到底隔离了什么：别把「有沙箱」当成「安全」

顺着 Claude Code 官方文档把沙箱边界走一遍：它只管 Bash 子进程，默认可读整台电脑，网络代理默认不解 TLS，protected paths 无法用 allowWrite 豁免。写清楚每一层管什么、不管什么，以及文档自己列出的绕过路径。

Claude Code 的定时任务怎么配：桌面端与命令行两处入口

把 Claude Code 官方文档里「定时」相关的两页拆开讲：命令行侧 /loop 与 CronCreate 接受哪些参数、桌面端本地任务要填哪四个字段、cron 表达式支持到哪一层语法、任务在什么条件下才真的被触发，以及哪些漏跑文档明说不会补。

给 Claude Agent SDK 写自定义工具：入参 schema、返回值与报错怎么设计

Claude Agent SDK 用 in-process MCP server 让你把自己的函数交给 Claude 调用。本文按官方文档梳理工具定义的四个组成部分、handler 返回值里 content / structuredContent / isError 三个字段的语义，以及报错该抛异常还是自己组装消息，并标出 Python 侧几处能力缺口。

Claude Agent SDK 从零跑通第一个 Agent：quickstart 里那几步分别在干什么

按 Claude Code 官方文档的 Agent SDK quickstart 走一遍，从建目录、装包、设环境变量到第一次工具调用，逐步说清每一步动的是哪个 API、哪个配置项；含 Windows 侧的虚拟环境与环境变量写法，以及文档写明的限制与验证方式。

把 Claude Agent 部署成服务：hosting 与 secure deployment 写明的前置条件

本地跑通一个 Agent 脚本，和把它托管成一个长期在线的服务，是两件事。这篇按 Claude Code 官方文档的 Hosting the Agent SDK 与 Securely deploying AI agents 两页，把部署形态的选择、运行时与网络的前置条件、多租户隔离必须显式关掉的几处默认行为，以及文档自己标出的已知限制，逐条对照着讲清楚。

在 Claude Agent SDK 里接 MCP：和 CLI 里配 MCP 是两套写法

在命令行里用 claude mcp add 配好的服务器，搬到 Claude Agent SDK 里未必生效。这篇按官方文档梳理 SDK 侧 MCP 的两个声明位置（options.mcpServers 与 .mcp.json 加 settingSources）、三类传输的连接时机差异、哪些服务器会拖住第一轮，以及怎么从 init 消息读出每个服务器的状态。

Claude Agent SDK 侧的权限怎么配：不是把 CLI 的权限模式照搬一遍

用 Claude Agent SDK 写自动化时，很多人把 canUseTool 回调当成万能闸门，结果发现它压根没被触发。这篇按官方文档梳理权限评估的六个步骤、回调到底在哪一步介入、能拒绝到什么粒度，以及 Windows 侧路径规则该怎么写，最后给出一个文档写明的自检信号。

Claude Agent SDK 的 Python 版怎么用：与 TypeScript 版对不上的地方

Claude Agent SDK 的示例大多是 TypeScript 写的，照搬进 Python 常常改不通。本文按官方文档梳理 Python 版安装前置条件（含 Windows PowerShell 一侧）、query() 与 ClaudeSDKClient 的分工，以及文档写明的跨语言差异：命名风格例外、hook 事件缺项、sandbox 默认行为不同。

Claude Agent SDK 的会话怎么存、怎么续：session 与 session storage 分别管什么

Claude Agent SDK 里 session 是自动落盘的对话记录，SessionStore 是把这份记录镜像到自己后端的适配器。本文按官方文档梳理会话 ID 从哪里取、continue/resume/fork 各自怎么找会话、transcript 存在哪个路径、以及跨主机恢复时哪一份副本才是唯一持久副本。

让 Agent 稳定吐出结构化 JSON：Claude Agent SDK 的 outputFormat 怎么配

把 agent 的输出直接喂给下游程序，最怕的是拿回一段自由文本再写正则解析。Claude Agent SDK 提供了 outputFormat / output_format 选项，用 JSON Schema 声明想要的形状，结果消息里回 structured_output。本文按官方文档梳理 schema 的声明方式、draft-07 这个容易踩的版本约束，以及校验失败时结果消息会变成什么样、该怎么分支处理。

Claude Agent SDK 的报错怎么查：官方 troubleshooting 页的分支

Claude Agent SDK 官方 troubleshooting 页是按报错原文编排的，目前只覆盖三条条目：CLI 找不到、Windows 拒绝执行批处理脚本、以及 structured_output 为空但结果标成功。本文按现象、判定动作、文档给出的处置、处置后的验证、以及什么情况说明不是这个原因五步逐条拆开，并说明这页没覆盖的报错该往哪走。

Claude Code 的安全模型：三份安全文档各自管的是哪一层

Claude Code 官方文档里有三处都叫「安全」，但管的完全不是一回事：一份讲权限与信任边界，一份讲边写边查的漏洞审查插件，一份讲按需深扫已有代码库。本文从「Claude 改了一个文件并提交」这一条路径走一遍，标出每一层的触发点、配置项与文档写明的边界。

Claude Code 自托管环境怎么搭：quickstart 到 deploy 的顺序不能颠倒

官方文档把自托管环境拆成 quickstart、deploy、configuration 三页，顺序是有讲究的：quickstart 只负责把最小环路跑通，接真实仓库和内部系统之前必须先做完 deploy 页那一串硬化项。本文按文档给的先后顺序梳理前置条件、每一步在改什么、必配的配置项清单，以及哪些能力还标着 public beta。

Claude Code 自托管环境的身份接入与验证：identity 与 testing 两页说明的步骤

自托管环境里的会话跑在你自己的网络中，可以直接调内网服务，于是内网服务需要一种办法确认「这个请求确实来自本环境的一个 Claude Code 会话，且是某人创建的」。本文按官方文档的 identity 与 testing 两页，梳理 CLAUDE_CODE_SESSION_ACCESS_TOKEN 这枚 JWT 的字段语义、服务端与会话内两条验证路径，以及配完之后怎么跑一趟端到端回路把它验一遍。

流式与单次两种模式怎么选：Claude Agent SDK 把差异划在哪

Claude Agent SDK 官方文档里有两页都叫「流式」，一页讲输入模式，一页讲输出的增量事件，很多人把它们当成一个开关。这篇沿着一次请求的路径走一遍，标出两种输入模式各自的适用条件、单次模式文档明说不支持的四项，以及开了输出流式仍然拿不到的东西。

改 Agent 的系统提示：Claude Code 官方允许改到什么程度

从「我想让它换个角色」这个具体诉求出发，沿着 Claude Code 官方文档写明的路径走一遍系统提示的改法，标出追加、整体替换、分块替换三档的分界线，以及 CLAUDE.md 为什么根本不在这条路上、改完什么时候才生效。

Claude Code 终端显示乱、快捷键不响应：terminal-config 与 keybindings 怎么调

终端画面闪烁、滚动位置乱跳、Shift+Enter 直接提交、Option 或 Alt 组合键毫无反应——这几类症状在 Claude Code 官方文档里分属两页，处置方式完全不同。本文按官方文档的口径把判定动作、配置项与按键绑定表逐条列清楚，并写明什么情况说明不是这个原因。

Claude Agent SDK 的待办追踪机制：todo 不只是给人看的

从「监听代码突然收不到 TodoWrite 了」这个具体问题出发，沿 Claude Agent SDK 官方文档《Todo Lists》页走一遍待办的状态流转：四个状态节点怎么切换、TodoWrite 全量重写与 Task 工具增量更新的差别在哪、任务 ID 从哪个消息块里拿、键名修复为什么在流里看不到。只讲文档写明的字段语义与配置项。

工具太多会拖垮 Agent：Claude Agent SDK 的 tool search 解决的是什么问题

挂了七八个 MCP server 之后，工具定义会先把上下文吃掉一大块。Claude Code 的 tool search 把这些定义从上下文里撤下来、按需检索加载。本文沿官方文档走一遍：它默认在什么条件下生效、哪几种部署形态会退回一次性加载、ENABLE_TOOL_SEARCH 的几个取值各自改变了什么，以及被检索出来的工具会在什么时候从上下文里消失。

让 Claude Code 走 Google Vertex AI 与 Microsoft Foundry：两条云上接入路径的配置差异

同样是把 Claude Code 接到云厂商的托管端点上，Google Cloud 与 Microsoft Foundry 两条路径要填的配置项并不对称。本文按官方文档逐项对齐前置条件、环境变量、认证方式与验证方法，只比两边文档都写明的维度，一方没写的地方照实说没写。

Claude Code 的零数据保留与数据使用：ZDR 开了之后哪些东西还在

组织拿到 ZDR 之后，最常见的误会是「以为什么都不留了」。这篇沿着 Claude Code 官方文档写明的路径走一遍：一次推理请求要满足什么条件才算被 ZDR 覆盖，文档列出的五类不覆盖项和五个被后端禁用的功能分别是什么，本机上还有哪些明文数据，以及第三方平台与违规留存这两条例外怎么读。

Cursor 账号异常了怎么办：官方文档给出的处置顺序

怀疑 Cursor 账号被别人登录时，先做什么、后做什么是有讲究的。本文按官方帮助文档《Compromised account》与《SSO and authentication》两页的原文，把判定动作、撤销顺序、SSO 组织的特殊路径、API key 的处理，以及"哪些迹象其实不是账号被盗"逐条对齐，并标出文档没有说明的部分。

Cursor CLI 的 ACP 是什么：接第三方客户端时卡在哪

按 Cursor 官方文档梳理 ACP（Agent Client Protocol）在 Cursor CLI 里的用途、接入前置与消息流向，并逐条排查自建客户端最常卡住的几个位置：权限请求没人回、blocking 扩展方法没人应、team-level MCP 在 ACP 模式下不支持，以及几处文档口径对不上的地方。

Cursor Agent Review 机制：改动在合进去之前过了哪一道

从「一批本地改动在提交前被谁看过一遍」这个具体问题出发，沿 Cursor 官方文档写明的路径走一遍 Agent Review 的三种触发方式、两档深度、规则来源与合并顺序，再看这段评审对话被分享出去时哪些信息会跟着走、哪些不会。

Cursor 的自动化任务怎么写：automations 的触发与产物

把一件重复的活交给 Cursor Automations 之前，得先搞清楚两件事：它到底被什么事件叫醒，跑完的东西又落到哪里去。这篇按官方文档梳理触发器的分档与各 Git 供应商的差异、产物端的工具与默认开关、仓库与权限三档的连带影响，以及文档明说不支持的那几种情况和配好后怎么验证。

Cursor 的 Browser 工具怎么用、卡在哪：能力边界与前置条件排查

让 Agent 自己开浏览器点页面，听起来省事，真用起来常见的是动作停在审批、网络请求怎么都读不到、企业账号下工具压根不出现、登录态换个项目就没了。本文只依据 Cursor 官方文档写明的内容，把这四类现象的判定动作、文档语义给出的处置、验证方式，以及「什么情况说明不是这个原因」逐条写清楚。

Cursor 的 Canvas 是干什么的：不是又一个编辑器窗口

从「让 agent 做一次依赖审计，产物落在哪」这个具体问题出发，沿 Cursor 官方文档《Canvases》页描述的路径走一遍：canvas 什么时候被创建、产物以什么形态保存、在哪里重新打开、分享要过哪几道闸、以及怎么用 skills 把产物形状固定下来。只写文档写明的能力，不描述界面。

把 Cursor CLI 接进 GitHub Actions：workflow 字段与凭证怎么给

按 Cursor 官方文档梳理 Cursor CLI 在 GitHub Actions 里的接法：安装步怎么把可执行文件加进 PATH、CURSOR_API_KEY 用哪个字段注入、仓库级与组织级 secret 怎么建、两种自主度对应的 workflow 写法差异，以及权限配置该放在哪个文件里。含 Windows runner 的差异与文档未说明之处。

Cursor CLI 的无头模式：接进脚本要先把输出格式定死

把 Cursor CLI 接进 shell 脚本或 CI 之前，先搞清楚 --print、--output-format 和 --stream-partial-output 这三个开关各自管什么、失败时输出长什么样。本文按官方文档梳理无头模式的参数、三种输出格式的字段结构与事件类型，以及文档明确写出的边界，并单独说明 Windows 侧的缺口。

Cursor CLI 的权限怎么配：允许清单与拒绝清单的优先级

把 Cursor CLI 的权限配置从头理一遍：五类权限令牌的写法、allow 与 deny 的匹配优先级、配置文件在 Windows 与 macOS/Linux 上的落点，以及官方文档写明与没写明的边界在哪。

Cursor CLI 上手：安装之后第一件事是把认证和权限理清

按 Cursor 官方文档梳理 Cursor CLI 的安装命令、两条认证路径（浏览器登录与 API key）、以及第一次跑起来必须先想清楚的配置项：配置文件放在哪、权限 token 怎么写、Run Modes 三档各自放行什么，并标出文档之间口径不一致的地方。

Cursor CLI 的斜杠命令与参数：reference 两页怎么查

Cursor CLI 的能力分散在斜杠命令和命令行参数两套入口里，官方文档也拆成了 slash-commands 与 parameters 两页。本文按这两页的原文，梳理命令清单的规模、别名关系、子命令分组与参数语义，标出文档里 hidden、legacy 的措辞，以及 Windows 原生环境下文档没有说明的部分。

用 API 驱动 Cursor Cloud Agent：endpoints 页的调用链

按「建 agent → 追加 run → 读状态 → 接 SSE → 取产物」的顺序过一遍 Cursor 官方文档《Cloud Agents API》的端点与请求字段，再对照 VM 内那套只读的任务元数据键位表。文中标出 public beta、preview 与「暂不支持」的位置，也标出几处容易读漏的返回值口径差异。

Cursor Cloud Agent 的身份与隔离：它以谁的身份动你的仓库

Cloud Agent 跑在 Cursor 云端的虚拟机里，会 clone 仓库、跑命令、开 PR，还可能去调你的云账号。这篇沿着官方文档写明的路径走一遍：仓库访问权限从哪来、VM 里的进程拿什么身份去换云端凭证、JWT 里有哪些 claim 可以用来收紧授权，以及 trust model 那一段为什么必须读两遍。

Cursor Cloud Agent 访问不了内网服务：网络隔离与私有连接

Cursor 的 Cloud Agent 跑在云端 VM 里，连不上你 VPC 或内网的数据库与私有制品库时，问题通常出在两层：出站域名白名单，或没有私有连接通路。本文按官方文档梳理三种网络访问模式与继承优先级、Tailscale 与 Cloudflare Tunnel 接入，以及 Enterprise private connectivity 的验证动作。

Cursor Cloud Agent 怎么配起来：环境、构建与设置三处

Cloud Agent 能开起来不等于能干活，真正决定它跑不跑得动测试的是三处配置：环境定义（.cursor/environment.json 与解析顺序）、Build（install / start / terminals 各管哪一段）、以及仪表盘上的默认项与网络、安全开关。本文按官方文档把这条配置链路的字段与边界逐处写清楚。

Cursor 的 Debug 模式与 Design 模式：两个专门化模式各自改了什么

手里一个复现得出来却看不出原因的 bug，和一个"这块间距不对"的界面问题，在 Cursor 里走的是两条完全不同的通道。本文按官方文档把 Debug Mode 与 Design Mode 的介入方式、上下文来源、适用场景与边界各走一遍，并标出文档里几处口径不一致的地方。

Cursor 的 deeplink 打不开：链接格式与系统关联

同事发来一条 cursor:// 开头的链接，点了没反应，或者打开了却是空的。本文按 Cursor 官方文档《Deeplinks》页写明的链接结构，逐段拆开这类链接的四个组成部分，给出可执行的判定动作，并说明哪些现象其实是文档写明的正常行为、不必去查。

把 Cursor 的使用数据导进你的可观测平台：OTel 导出与 wire 格式

团队想知道 token 花在哪些会话上，靠 Cursor 的 OpenTelemetry Export 能做到什么程度？本文沿官方文档走一遍这条链路：destination 怎么配、metrics 与 logs 各带哪些属性、四个 id 分别用来 join 什么，以及交付语义上哪几处会咬到你。

扩展装了不工作、互相打架：Cursor 的 extensions 两页合起来看

Cursor 官方帮助里，扩展相关的说明拆在「Extension conflicts」和「Extensions」两页，一页讲怎么判定冲突，一页讲扩展从哪来、团队怎么管。本文把两页合起来，按现象、判定动作、处置、验证、排除的顺序梳理扩展冲突的判定与禁用顺序，并写清哪些症状文档归给了别的原因。

Cursor Hooks 怎么写：能挂的时点与能改的东西

按 Cursor 官方文档梳理 hooks 的可挂载事件点清单、配置文件位置与优先级、命令型与 prompt 型两种执行方式，以及每个事件点到底能读到什么字段、能改回去什么字段。含云端 Agent 不支持的那几个事件点、schema 收了但不生效的返回字段，以及 Windows 侧的路径差异。

.cursorignore 不生效：忽略规则的作用范围与优先级

写了 .cursorignore，敏感目录的内容还是出现在对话里，这未必是规则没匹配上。本文按 Cursor 官方文档的口径梳理这条规则到底管住了哪些通道、明确管不住哪些通道，给出可执行的判定动作、文档语义下的处置办法，以及哪些情况说明根本不是忽略规则的问题。

Cursor 装不上、装完打不开：install issues 页的处置

把 Cursor 官方帮助中心 Installation and startup 一页拆成四类现象——启动空白、macOS 提示已损坏、更新装不上、本地占空间，逐类给出怎么判定是这个问题、文档给了什么处置、处置后怎么确认，以及什么情况说明根本不是这一类。Windows 侧单独列，并标出文档没有说明的部分。

装插件前先看这一页：Cursor 官方文档对 Marketplace 安全的说明

Cursor 的 Marketplace 安全页把插件风险的边界写得很直白：插件是第三方软件，装不装由你自己承担风险。这篇按排查的路子走一遍——插件装上了但它带的 MCP server 一个调用都发不出去，该怎么判定是被 allowlist 拦了，文档给出的处置和验证动作是什么，以及什么情况说明根本不是这个原因。

Cursor 的 MCP 配置不生效：配置位置与作用域先分清

MCP 服务器在 Cursor 里没出现、工具调不动，多数时候不是配置写错了，而是写在了错的那一层。本文按 Cursor 官方文档梳理项目级、全局级、团队分发与 Cloud Agents 四处配置位置的合并与优先规则，再给出一条按顺序执行的排查路径：从日志判定、开关状态、环境变量与插值范围，到审批模式与企业侧 allowlist，每一步都写明怎么确认、怎么处置、以及什么情况说明不是这个原因。

Cursor 连不上、请求超时：官方 network 排查页的分支怎么走

公司网络里 Cursor 的 AI 功能时断时续、请求卡住不返回，多半不是账号问题。本文照官方 network 排查页与企业网络配置页的原文，梳理诊断入口、三条 curl 连通性测试、需放行的域名范围、SSH 与 VPN 两条分支，以及哪些现象说明根本不是网络的锅。

Cursor Origin 上手：把仓库放到它自己的托管上

Origin 是 Cursor 自己的 git 托管，官方文档标注为 early beta。这篇按官方文档梳理启用前提、建仓与克隆的完整步骤、Origin CLI 的安装与登录（Windows 侧只给了 WSL 路径）、仓库 Settings 的四个分区，以及哪些能力在 beta 期明确受限、配完之后怎么验证。

Cursor 卡顿、吃内存：performance 页给的判定顺序

Cursor 官方帮助文档的 performance 页只把性能问题分成三类，给出的处置手段翻来覆去就是禁用扩展和 `.cursorignore` 两条。这篇按「现象—判定—处置—验证—排除」的顺序把这份分类拆开，并说清哪些看着像卡顿的症状其实归属于安装、网络或 Tab 那几页，别在错误的方向上折腾。

Cursor Plan 模式在做什么：计划这一步省下的是哪一部分

从「计划阶段结束后到底留下了什么东西」这个问题出发，沿 Cursor 官方文档把 Plan 模式的入口、产物、保存位置和它对后续执行的约束方式走一遍，顺带标出文档没有写明的那几处，避免把计划当成权限机制来用。

Cursor 插件机制：plugin 与 VS Code 扩展不在同一层

想把一套团队规则、技能和 MCP server 分发给全组，在 Cursor 里该做 plugin 还是做扩展？本文按官方文档梳理 plugin 的两种清单格式、装在哪个目录、在桌面端与 CLI 上分别怎么装，以及它和走 Open VSX 的 extension 在分发链路上的分层关系与边界。

给 Cursor 报 bug 要带哪些信息：官方文档写明的八项材料与获取方式

提交 Cursor 问题反馈后长时间没有进展，多数时候不是没人看，而是材料不全、对方查不动。本文按官方帮助文档《Reporting a bug》逐项拆解需要附上的八项材料、每一项在 Mac 与 Windows/Linux 上分别怎么取，以及 Privacy Mode 的按请求生效规则为什么会让「事后补交」失效。

Cursor Router 在替你决定什么：路由这一层的机制

选了 Auto 之后，这一次请求到底由谁决定用哪个模型？本文沿着 Cursor 官方文档写明的路径，把 Cursor Router 的决策链拆成套餐门槛、优化模式、分类器、团队模型访问控制四层，并对齐 SDK 里 `auto-smart` 与 `optimize_for` 的实际契约。

Cursor 的 run modes：每一档各自放开了什么

从「agent 想跑一条 shell 命令，Cursor 在哪一步决定要不要问你」这个具体问题出发，沿 Cursor 官方文档《Run Modes》页描述的检查顺序走一遍三档模式，标出 permissions.json、sandbox.json 的分工、平台前提与文档明说的能力边界，并说明 Windows 侧文档没有覆盖到什么。

Bugbot、Security Agents 与 PR Routing & Approval：Cursor 三类托管代理各管一段

一个 PR 从打开到合并，Cursor 的三个托管代理分别在哪一刻插手、各自留下什么产出。沿官方文档把触发时机、CI check 结论、策略文件发现顺序走一遍，说清为什么它们不是三个同类工具。

Cursor Skills 怎么组织：与 rules 的分工别搞混

从 SKILL.md 的定义结构和加载条件入手，讲清楚 Cursor 的 skills 是怎么被发现、怎么被作用域限制、什么时候才会进入 Agent 上下文，以及官方文档给出的 rules 与 skills 分工口径和迁移条件，顺带标出两页文档写法不一致的地方。

Cursor 子代理怎么定义：任务分派与上下文隔离

按 Cursor 官方文档《Subagents》页梳理自定义 subagent 的定义方式：文件放在哪几个目录、YAML frontmatter 有哪几个字段、model 字段的方括号参数怎么写、上下文隔离的粒度到底隔到哪一层，以及配置好之后怎么确认它真的被识别了。

Agent 用终端出问题：Cursor terminal 工具的权限与确认机制

Cursor 的 Agent 跑 shell 命令时，一条命令要先后过 Run Mode、sandbox、分类器和几层额外保护。本文按官方文档梳理这些前置与拦截点，给出频繁弹批准、命令行为异常、输出错乱三类现象的判定动作与处置口径，并单列 Windows 侧的文档缺口。

微软生成式 AI 入门课第 17 课：Agent 怎么讲给刚入门的人

把 generative-ai-for-beginners 第 17 课拆开看：它给 Agent 下的定义只有「LLM + state + tools」三件，然后拿这把尺子去量几个框架。本文沿着 17-ai-agents/README.md 走一遍，标出各框架承载 state 与 tools 的具体对象，指出这一课与仓库其它部分对不上的地方，以及它和另一门 Agent 课的定位差别。

微软生成式 AI 入门课第 13 课的应用安全：重点盯的是哪几类攻击面

generative-ai-for-beginners 第 13 课通篇没有代码，只给了攻击面分类；真正的防护动作散在 shared/python/input_validation.py 和 docs/SECURITY_GUIDELINES.md 里。这篇沿着仓库文件走一遍，说清课程把攻击面切成哪几类、代码里到底拦了什么、哪些其实是通用 Web 安全。

微软生成式 AI 入门课的 api_utils.py：它替你挡了哪些麻烦

generative-ai-for-beginners 的 shared/python/api_utils.py 只有四个函数，却把超时、重试、缺 key 的报错和 Azure v1 端点拼接都收进去了。本文沿着函数签名、异常分支和 tests/test_api_utils.py 的断言走一遍，说清它挡了什么、没挡什么，以及哪些分支根本没被测到。

微软生成式 AI 入门课接 Azure OpenAI：endpoint、部署名、版本

把 generative-ai-for-beginners 的课程示例从 OpenAI 切到 Azure OpenAI，卡住的往往不是代码而是四个环境变量的语义。本文按仓库里的 .env.copy、aoai-app.py 与 shared/python/api_utils.py，逐个讲清 endpoint 要拼成什么、部署名为什么不等于模型名、API 版本字段在新旧两条路线里各是什么处境，以及怎么验证配对了。

聊天应用的多轮历史在哪一层拼：微软生成式 AI 入门课第 7 课

照着 generative-ai-for-beginners 第 7 课跑完第一个聊天示例，多半会发现模型"记不住"上一轮。这篇沿着仓库里的 notebook 逐行看清楚：历史列表到底在哪一层拼、系统消息为什么必须排第一条、简版与完整版差在哪几行，以及 store=False 与 previous_response_id 之间那条被课程绕开的岔路。

跟微软生成式 AI 入门课写第一个文本生成应用：oai-app.py 逐段拆开

generative-ai-for-beginners 第 06 课的 python 目录里同时躺着 oai、aoai、githubmodels 三套示例，选错一套就会在配置上卡住。本文只走 OpenAI 那一条线，把 oai-app.py 这二十来行从客户端初始化、input 的消息结构、参数含义一直拆到 output_text 的取值路径，并交代仓库里写明的边界。

embedding 维度对不上导致检索报错：微软生成式 AI 入门课从写入端查起

语义检索突然报向量维度不匹配，或者查什么都返回空，多半不是查询代码写错了，而是写入索引时用的 embedding 模型和查询时用的不是同一个。本文沿着 generative-ai-for-beginners 第八课的写入脚本与查询 notebook，讲清楚这条链路上哪几处把模型名写死了、换模型后为什么必须重建基线。

Azure OpenAI 报 404：微软生成式 AI 入门课的 endpoint 与部署名

跑 generative-ai-for-beginners 的 Azure OpenAI 示例时，最常卡住的不是代码而是三个环境变量。本文顺着仓库里 aoai-app.py 的 base_url 拼接、.env.copy 的 endpoint 形态注释、以及 api_version 字段在两种客户端之间的错位，给出一套能自己走一遍的判定动作。

.env 写了却读不到：读一遍微软生成式 AI 入门课的 env 加载逻辑

generative-ai-for-beginners 的示例脚本报「缺少环境变量」，多数时候不是 .env 写错了，而是这一段代码根本没加载它。本文顺着 shared/python/env_utils.py、tests/test_env_utils.py 和 00-course-setup 的三份配置文档，把加载顺序、文件查找位置、测试覆盖到与没覆盖到的边界情况理一遍，并给出可执行的判定动作。

JSONL 数据格式、提交与轮询：微软生成式 AI 入门课第 18 课微调

拆开 generative-ai-for-beginners 第 18 课的微调作业：训练文件的 JSONL 每行长什么样、files.create 与 fine_tuning.jobs 这条提交与轮询链路怎么写、README 的格式要求和仓库自带样本文件在哪一点上对不上，以及 RESOURCES.md 该按什么顺序翻。

微软生成式 AI 入门课里函数定义了却不调用：schema 与消息结构两头查

工具定义写完了，模型却当没看见，或者调了一次之后第二轮接不上。本文照着 generative-ai-for-beginners 第 11 课的 Python notebook 与 README，把 tool schema 的顶层形状、必填字段、描述写法，以及工具结果在消息里的摆放位置逐处对一遍，并指出仓库里几处正文与代码不一致的地方。

函数调用的完整往返：微软生成式 AI 入门课第 11 课的工具定义与回传

顺着 generative-ai-for-beginners 第 11 课的 python 笔记本，把一次函数调用拆成三段：工具 schema 里每个字段是什么、模型返回的 function_call 项长什么样、结果怎么以 function_call_output 回传给模型。同时指出课程正文与代码不一致的几处，以及照抄示例代码会踩的两个坑。

微软生成式 AI 入门课的 githubmodels-app.py 连的是 Foundry Models

generative-ai-for-beginners 同一节课常有 oai、aoai、githubmodels 三份示例。本文只盯 githubmodels 这一条：要填哪两个环境变量、client 怎么初始化、它和 OpenAI 那份代码差在哪几行，以及为什么这个前缀现在名不副实。全部依据仓库内的文件，未运行过代码。

本地跑通微软生成式 AI 入门课：Python 版本、依赖与 .env 字段

搭 generative-ai-for-beginners 的本地环境，卡人的从来不是概念，是 Python 版本对不对、依赖装哪一份 requirements、`.env` 放哪一层、字段名叫什么。本文以仓库 `00-course-setup` 下两份 setup 文档为主，并核对根目录 `.env.copy`、`.gitignore` 与 `.devcontainer/` 配置，把前置条件、四条安装路径与 `.env` 字段逐条落到文件上。

不想装环境：用 Codespaces 跑微软生成式 AI 入门课的完整步骤

generative-ai-for-beginners 提供了一条浏览器里的云端启动路径。本文按仓库 00-course-setup 下的三个文件把步骤拆开：fork 之后容器里到底跑了哪几条命令、密钥用 Codespaces secret 还是 .env、云端与本地在取值方式上差在哪一行代码，以及哪些说明仓库里其实没有给。

第 9 课的图像生成应用：微软生成式 AI 入门课里请求怎么发、结果怎么取

generative-ai-for-beginners 第 9 课给了 Azure OpenAI 与 OpenAI 两份图像生成示例，同一个接口在两份代码里的写法并不一样。本文对着 09-building-image-applications 目录下的 aoai-app.py 与 oai-app.py，把请求参数、返回结构、结果落盘这条链路拆开，并标出仓库里几处容易踩的不一致。

图像生成请求被内容策略挡下：微软生成式 AI 入门课示例怎么处理

跑 generative-ai-for-beginners 第 09 课的图像生成示例时，请求被挡下往往看不到任何报错，控制台只留一行 completed。本文顺着仓库里 aoai-solution.py 的 try/finally、notebook 里的 except 分支、README 的 metaprompt 小节，把判定动作、处置方式与验证方法逐条对上，并说明哪些症状其实不是内容策略造成的。

拦住了什么、没拦住什么：微软生成式 AI 入门课自带的输入校验

generative-ai-for-beginners 的 shared/python/input_validation.py 提供了一组输入校验与清洗函数，很多人接进自己的应用就当成了防注入。本文逐条读它的规则、看 tests 覆盖了哪些输入形态，指出从正则字面语义就能读出的几处绕过口，并给出仓库文档自己写明的处置顺序。

第 1 课怎么划生成式 AI 的范围：微软生成式 AI 入门课的概念地基

generative-ai-for-beginners 的第 1 课没有一行代码，却把整门课的定义边界、教学案例和术语口径全定死了。这篇沿着 01-introduction-to-genai/README.md 走一遍它划的四条线，并指出其中的 temperature 一说到了第 6 课要打折扣。

微软生成式 AI 入门课报认证错误：三条 provider 路线密钥字段不同

generative-ai-for-beginners 的同一课往往备有 oai、aoai、githubmodels 三个版本的示例，它们读的环境变量名不是一套，报错形态也不一样。本文按仓库里的 .env.copy、03-providers.md、shared/python/env_utils.py 与三个示例脚本，把「报错文本 → 该配哪个字段」这条映射理清楚。

微软生成式 AI 入门课第 14 课的应用生命周期：从原型到上线中间少了哪几步

generative-ai-for-beginners 第 14 课把生成式 AI 应用的生命周期切成三大步加一个贯穿环。本文沿课程正文把每一步的产出物、评估环节落在哪个位置捋一遍，并对照仓库里 shared/python 与 tests 目录真正给了代码的部分，指出哪几项在这个课程仓里只有概念、没有可执行的评估脚本。

微软生成式 AI 入门课第 2 课怎么给大模型分类：五个维度对到选型问题

generative-ai-for-beginners 第 2 课在「理解不同类型的 LLM」下挂了五个并列小节，很多人当成一份分类学背下来。这篇不复述课程，只做一件事：把这几个维度还原成选型时各自回答的那个问题，并顺着仓库里的 .env 变量、embeddings 调用和 provider 标签，指出维度在代码里长什么样。

微软生成式 AI 入门课第 10 课低代码：不写代码能走到哪一步

generative-ai-for-beginners 第 10 课整节没有代码目录，也是全课唯一带 assignment.md 的一节——而这个文件是空的。这篇沿着 10-building-low-code-ai-applications/README.md 走一遍它给的两条流程，说清 Copilot 生成之后还要手工补哪些步骤、AI Builder 的能力分在哪几个产品里，以及这一课的边界到底划在哪。

微软生成式 AI 入门课第 21 课 Meta 模型：调用路径与作业设计

generative-ai-for-beginners 第 21 课的练习文件叫 githubmodels-assignment.ipynb，代码里却一个 GitHub Models 的变量都没有。这篇沿着这个文件从环境变量、两段 client.complete 调用一路读到「这一课到底怎么算做完」，把仓库里写明的验收依据和仓库里根本没写的部分分开讲。

githubmodels- 前缀连的其实是 Foundry：微软生成式 AI 入门课第 20 课

generative-ai-for-beginners 第 20 课只留了一份 githubmodels-assignment.ipynb，但文件名里的前缀和它实际读的环境变量已经对不上了。本文沿着这个 notebook 的三段代码走一遍调用链，并把它和第 04、06、07、21 课的同名前缀文件逐处比对，说清哪些写法是这一课独有的、哪些不能往前面的课上套。

微软生成式 AI 入门课的 notebook 跑不起来：内核、依赖、环境三层排查

打开 generative-ai-for-beginners 的 .ipynb，第一个单元就 ModuleNotFoundError，或者内核干脆连不上。这篇按依赖清单在哪、内核选到了谁、虚拟环境和内核有没有绑上三层顺序排查，每一层都给可执行的判定动作，并说明什么情况下说明问题根本不在环境上。

微软生成式 AI 入门课第 16 课的开源模型：给的是尺子不是清单

generative-ai-for-beginners 第 16 课讲开源模型，很多人翻完只记住了几个模型名字。这篇沿着 16-open-source-models/README.md 走一遍课程真正给出的东西：术语怎么被换掉、判断一个模型算不算开源的那几条信息、选型时课程让你从哪几个入口看，以及跟着 00-course-setup/03-providers.md 把模型真正接进来的三条路径与 Windows 侧的写法。

微软生成式 AI 入门课的 Phi 加载失败：依赖、权重、设备三层排查

照着 generative-ai-for-beginners 的 19-slm 课跑 Phi 系列 notebook，最常卡住的地方是 from_pretrained 那一行。本文按依赖、权重来源、设备三层拆开，逐层给出可执行的判定动作，并把仓库里 19-slm/python 下几个 notebook 的原始写法、requirements.txt 的实际覆盖范围以及 device_map 的三种写法一一对上号。

Phi-3.5 三个 demo notebook 差在哪：微软生成式 AI 入门课第 19 课

generative-ai-for-beginners 第 19 课的 19-slm/python/ 下挂着三个 Phi 演示 notebook，看着像同一份代码换了个模型名，实际加载的类、输入形态和依赖都不一样。本文逐字对读这三份文件，说清各自从哪个路径加载、prompt 怎么拼、哪些依赖仓库根本没有写进 requirements，以及照抄时最容易踩到的几处不一致。

微软生成式 AI 入门课第 4 课：提示工程的地基是哪几件事

generative-ai-for-beginners 第 4 课配了三份 notebook，练习内容完全一样，只换客户端接线。本文顺着这三份文件走一遍，看课程是怎么把「验证配置」「验证编造」「验证技法」拆成三个可判定的探针的，以及采样参数那条已经变过的分界线。

七种高级技法只有一种落进 aoai-solution.py：微软生成式 AI 入门课第 5 课

generative-ai-for-beginners 第 5 课列了 zero-shot、few-shot、chain-of-thought、self-refine 等一串提示技法，但这一课的 python 目录下只有 assignment 与 solution 两个文件。本文顺着 05-advanced-prompts/python/aoai-solution.py 逐处对，看看哪条技法真的落到了代码里、落在哪一行，以及 temperature 那一节现在已经和第 6 课的说明对不上了。

跑微软生成式 AI 入门课报模型不存在：多半是 provider 选串了

generative-ai-for-beginners 的同一课往往有 oai-、aoai-、githubmodels- 三套示例，凭据变量、客户端类和 model 的取值来源都不一样。本文按仓库文件把这三条线拆开，给出判定动作、处置方式和验证办法，并说明哪些报错其实不属于这一类。

跑微软生成式 AI 入门课示例被限流：仓库自带的重试封装做了什么

generative-ai-for-beginners 的 shared/python/api_utils.py 里有个 make_safe_request，很多人以为它会替课程示例兜住限流。本文按排查顺序读一遍这个函数：它捕获哪些异常、退避有没有实现、中间几次失败去哪了，以及课程示例其实根本没走它，你该在哪一层自己补。

微软生成式 AI 入门课第 15 课 RAG：向量库那段 notebook 逐块读

逐块拆 generative-ai-for-beginners 第 15 课的 RAG notebook，看清 split_text 的切块条件、写进 DataFrame 的字段到底有哪些、Cosmos DB 客户端连上之后发生了什么，以及检索到的片段在 chatbot 函数里被拼到提示词的哪个位置。含 README 与 notebook 两处写法不一致的对照，以及跑之前要先核对的前置条件。

Azure OpenAI 迁到 Responses API：微软生成式 AI 入门课的迁移 skill

generative-ai-for-beginners 仓库里藏着一个专门做 API 迁移的 skill，把 Chat Completions 换成 Responses API 的每一处改动都列成了对应表。本文拆解它的触发方式、cheat-sheet 里的新旧写法映射、以及仓库自身没有被这套规则覆盖的那两课。

微软生成式 AI 入门课第 3 课的负责任 AI：不是口号，是可执行动作

generative-ai-for-beginners 第 3 课整章没有一行代码，但它列的风险类型与缓解层，在这个仓库里都能找到对应的落点。本文沿着「风险 → 缓解层 → 具体文件」走一遍，指出各层缓解分别落在哪个文件的哪个函数上，哪一层在仓库里根本没有代码，以及同一课两条 provider 路线里同名校验函数的行为差异。

微软生成式 AI 入门课第 8 课：从 transcript 到 embedding

generative-ai-for-beginners 第 8 课把「一堆视频字幕」变成能用自然语言检索的索引，中间隔着五个 enrich 脚本。本文按仓库里的代码把这条链路走一遍：每个脚本改了哪个字段、索引最终存成什么结构、检索时相似度到底怎么算，以及这套脚本里有哪些会静默吞数据的地方。

微软生成式 AI 入门课的测试跑不过：先看 conftest 与 fixture

generative-ai-for-beginners 仓库根目录下有一个 tests/ 目录，CI 里跑 pytest tests/，但按课程的本地安装步骤装完依赖后不一定能顺利收集。本文只依据仓库文件本身，梳理 conftest.py 到底注册了什么、这套测试对环境变量的依赖到底有多少、以及它在断网环境下的结构，并给出逐步的判定动作与排除条件。

六个 transcript 脚本串成一条流水线：微软生成式 AI 入门课第 8 课

generative-ai-for-beginners 第 8 课直接给了一份现成的 embedding 索引，但真要换成自己的数据，就得看懂 scripts 目录下那六个 Python 脚本的先后顺序、各自读写哪个文件、以及中间那份 JSON 在每一步被加了什么字段。本文沿着仓库里的编排脚本走一遍这条流水线，把每一步的产出、字段变化和几处代码与文档对不上的地方标出来。

微软生成式 AI 入门课第 12 课的应用 UX：哪些交互问题是必答题

generative-ai-for-beginners 的 12-designing-ux-for-ai-applications 只有一篇 README、没有代码，很容易被当成鸡汤跳过。这篇把它列的信任、解释性、控制权、反馈四条原则，逐条对到仓库里真实存在的文件上——shared/python 的校验函数、06 课的 persona prompt、07 课的 UX 小节，看它们在界面前一层各自管了什么。

OpenRouter 的批量 API：什么任务适合走批量

OpenRouter 的 Batch API 用一个内联的 requests 数组提交，用同一个批次 ID 轮询，完成后结果直接内联返回，没有单独的下载端点。本文按官方文档梳理提交格式、三个必填字段、状态流转与结果取法，以及它明说不支持的那几类请求。

把 OpenRouter 的调用日志推到你的可观测平台：Broadcast 怎么接

OpenRouter 的 Broadcast 会把每次 API 请求的 trace 自动推到外部可观测平台。本文按官方文档梳理它的配置层次、请求侧可带的 trace 字段，以及 OTLP 目标端、Webhook、S3 三类落地端在字段映射上的实际差异，并写清哪些是文档明说不保证、哪些是文档根本没说的部分。

BYOK 自带密钥怎么接：用自己的供应商账号走 OpenRouter

按 OpenRouter 官方文档梳理 BYOK 的配置流程与生效范围——密钥放在哪一层、Prioritized 与 Fallback 两个分区怎么排序、三种 key filter 何时生效、为什么 BYOK 会盖过你写的 provider order、以及它跟数据策略和预算的关系。附 Azure / Bedrock / Vertex 三种凭据格式与排错入口。

Agent 跑进死循环：OpenRouter 的 doom-loop detection 怎么判

一个 agent run 反复调同一个工具却不推进，怎么确认它是死循环、而不是别的毛病？本文按 OpenRouter 官方文档的字段语义，梳理 doomLoop 的检测条件、ladder 各档动作、loopKey 的三种写法，以及 stopWhen 这条兜底线各自负责什么，最后说清哪些情况根本不归它管。

在 OpenRouter 上做嵌入与重排：RAG 那一段怎么拼

按 OpenRouter 官方文档的《Embeddings》与《RAG with Embeddings & Rerank》两页，把嵌入、重排、生成这三段的请求字段、响应字段与上下文拼接顺序对齐一遍：input 的三种形状、rerank 的 documents 与 results 结构、两页示例里不一致的取值方式，以及文档明说不支持的部分。

OpenRouter 报错怎么定位：官方 errors 页把错误分成了哪几层

拿到一个 OpenRouter 的报错，只看 HTTP 状态码往往会走偏。本文按官方 Errors and Debugging 页的写法，把错误拆成状态码、error 对象、error_type 词表、provider_code、openrouter_metadata 五层，说清每层能回答什么问题、下一步该做什么，以及哪些情况根本不是报错。

护栏与提示注入检测：OpenRouter 在请求链路上加的那道闸

从一条含注入短语的用户消息出发，沿 OpenRouter 官方文档描述的路径走一遍：guardrail 的检测在什么位置介入、扫的是请求的哪些部分、命中后 flag/redact/block 三档动作各自发生什么、403 响应里能拿到哪些排查字段，以及文档自己写明的漏网与误报边界。

OpenRouter 的延迟从哪来：把排队、路由与生成分开看

同一个 model slug、同一段 prompt，两次调用的首字返回快慢差很多，该查哪一段？本文按 OpenRouter 官方文档的口径，把一次请求拆成边缘接入、余额检查、路由与回退、router pipeline、供应商生成几段，给出每段可核查的判定动作与文档写明的可调字段，并说明什么情况下问题不在这一层。

OpenRouter 的各种限制项：撞上哪一条会返回什么

把 OpenRouter 官方文档里散落在两页的「限制」拆成可判定的几类——额度类、速率类、长度类、内容策略类、路由可用性类，各自对应什么状态码、什么 error_type、去哪个字段确认，以及哪些情况说明你排错了方向。全文不涉及任何额度与限流的具体数值。

用 OpenRouter 管理型 API key 自动化管密钥：轮换与作用域

OpenRouter 的 Management API key 和平时发请求用的那把 key 不是一回事，官方文档明确写了它调不了补全端点。这篇把两页文档合在一起讲清楚：管理 key 的权限边界在哪、`/api/v1/keys` 上有哪几个动作、零停机轮换的三步各自在改什么、哪些地方文档压根没说明，以及删掉旧 key 之前该怎么确认流量已经迁走。

OpenRouter 把你的消息改写了：message transforms 在你不知道时做了什么

发给 OpenRouter 的对话，中间几轮可能在到达模型之前就被删掉了。这篇按排查顺序走一遍：怎么用官方文档写明的 openrouter_metadata 与 debug 字段确认压缩确实发生过，触发它的三个条件分别是什么，怎么在单次请求里关掉，关掉之后怎么验证，以及哪些现象说明问题不在这里。

给 OpenRouter 模型配回退链：主模型挂了自动换下一个

线上调模型最怕的不是慢，是主模型突然返回错误、整条链路一起断。OpenRouter 官方文档的《Model Fallbacks》页写明了 `models` 数组与 Anthropic Messages 端点上 `fallbacks` 参数的字段语义、默认会触发回退的错误类型，以及三条会直接返回 400 的限制。这篇按文档把这些字段逐个讲清楚，并说明哪些部分文档并没有交代。

OpenRouter 模型名后面的后缀改变了什么：nitro、floor、exacto 各自换掉路由的哪一段

同样一段请求体，只在 model 字段后面多了个冒号后缀，走的路就不一样了。本文按 OpenRouter 官方文档，把七个变体后缀逐个落到它实际改写的那一项上：哪些改的是你在寻址哪个模型条目，哪些改的是选定模型之后供应商怎么排序，以及哪一个已经被标了 deprecated。

给你的应用接 OpenRouter 登录：OAuth PKCE 流程怎么走

让用户自带 OpenRouter 账号、你的应用只拿一把归用户所有的 key，靠的是 PKCE 流程。这篇按官方《OAuth PKCE》页把每一步拆开：/auth 上挂哪些查询参数、回调回来的 code 长在哪、换 key 的那个 POST 要带哪三个字段、localhost 与 headless 两种形态各自的限制，以及四个错误码分别对应哪一步配错了。

OpenRouter 的插件机制：plugin 与 server tool 不是一回事

同样是给模型加一项能力，OpenRouter 的 plugin 写在 plugins 数组里、启用就跑一次，server tool 写在 tools 数组里、由模型决定调不调。这篇沿官方文档把两者的介入点走一遍：谁决定、谁执行、跑几次、配置写在哪一层，以及 Fusion 与 Response Healing 这两个例子怎么把差异摆到明面上。

OpenRouter presets 怎么用：把一整套参数收成一个名字

OpenRouter 的 preset 允许把模型、系统提示、provider 路由偏好和 tools 收进一个带 slug 的命名配置，请求里用 @preset/slug 引用。本文按官方文档梳理 preset 能存哪些字段、三种引用写法、从已有请求体反向建 preset 的三个端点，以及请求字段与 preset 字段之间的覆盖优先级——包括 tools 数组那条与其它字段不一样的合并规则。

OpenRouter 把自己定位成什么：principles 与 models 两页的自述

OpenRouter 的 Principles 页用六条价值主张给自己定了位，Models 页则把这些主张落成了可以被程序读到的字段。本文顺着一次 /api/v1/models 请求走一遍，逐条对上「官方自述」与「接口里真能核到的字段语义」，也标出哪几条自述在这两页里找不到对应字段，帮你判断该信哪个字段做模型选择与成本口径。

提示缓存在 OpenRouter 上怎么用：缓存断点打在哪

OpenRouter 的提示缓存有三种声明形态——顶层 cache_control、逐块 cache_control、OpenAI 风格的 prompt_cache_breakpoint。本文按官方文档梳理这三种断点写在请求体的哪一层、彼此怎么互转、哪些接口不支持，以及怎么从 usage 字段确认缓存真的命中了。

在 OpenRouter 上你的数据被哪一层记了：data collection 与 provider logging 的口径

合规同事问「我们发给模型的内容被谁留了」，很多人一句话答不上来。OpenRouter 官方文档把这件事拆在两页里讲：平台自己这一层、各 provider 那一层、还有一条只记 metadata 的旁路。本文按排查顺序把三层的开关位置、默认状态和文档明确划出的边界过一遍。

OpenRouter 的 provider 路由怎么配：把请求钉在你想要的那家

同一个模型 slug 背后可能挂着多家供应商，默认是按价格做负载均衡。这篇按 OpenRouter 官方《Provider Routing》页把 provider 对象里的字段一个个过一遍：order、only、ignore 怎么筛，sort 与 partition 怎么排序，哪些字段是硬过滤、哪些只是软偏好，以及配错时会以什么形式炸出来。

OpenRouter 推理 token 排查：思维链拿不到、用量算不清

接 OpenRouter 的推理模型时，reasoning 字段有时是空的，usage 里报的推理 token 数又跟看到的文本对不上。本文按官方文档梳理 reasoning / reasoning_details 的返回位置、三种 detail 类型与 format 标记，给出逐步判定动作、处置方式，以及哪些现象其实不是这个原因。

OpenRouter 的响应缓存怎么开：命中与不命中的判定

OpenRouter 的响应缓存作用在请求转发给 provider 之前，开关有请求头和 preset 两条路。本文按官方文档梳理缓存键由哪几样东西拼成、哪些改动会让它失效、优先级规则怎么算，以及命中之后从响应头和用量字段怎么看出来确实命中了。

OpenRouter 的 response healing 插件在修什么：不是所有畸形输出都能救

结构化输出偶发解析失败时，很多人挂上 OpenRouter 的 response-healing 插件就当问题解决了。这篇按官方文档把它的激活条件、文档列出的可修类型、以及文档明确写明修不了的情况拆开，给出一套能自己走一遍的判定顺序，避免把「文档写明不覆盖」误当成「插件坏了」。

OpenRouter Responses API 的错误处理：与 Chat Completions 不是一套

把 OpenRouter 的调用从 Chat Completions 换成 Responses API 之后，原来的错误分支会大面积失灵——两套接口的 error 结构不一样，error.code 一个是数字一个是字符串，error_type 所在的层级也不同。本文按官方文档的字段语义，讲清怎么判定自己踩的是不是这个坑、改哪里、怎么验证，以及哪些症状其实是别的原因。

OpenRouter 响应里的路由元数据怎么读：这次到底走了谁

OpenRouter 默认不告诉你一次请求最终落到哪个 provider、中途有没有被压缩或拦截。本文按官方文档《Router Metadata》页，把 `X-OpenRouter-Metadata` 开关、`openrouter_metadata` 的字段语义、pipeline 阶段的读法，以及错误响应里它出现在哪一层，逐个走一遍，重点放在排障时怎么用它做判断。

OpenRouter 的几种 router 分别按什么挑模型

把 model 字段填成一个 router slug，模型就不是你选的了。本文沿着 OpenRouter 官方文档 routers 一节的六页，逐个说清每个 router 拿什么当选择依据——市场消费份额、编码百分位、能力过滤后随机、家族最新版——以及怎么从响应里回读它到底挑了谁。

服务端工具体系：让工具跑在 OpenRouter 那边而不是你这边

一次请求里到底是谁在执行工具？本文按 OpenRouter 官方文档的《Server Tools》一节，把服务端工具、插件与用户自定义工具的职责边界走一遍，重点讲 apply_patch 的人在回路验证、shell 的托管沙箱执行，以及 subagent 把执行权交回客户端的那条路径。全部为 beta 阶段能力。

服务分级是怎么回事：OpenRouter 的 service_tier 影响的是哪一段体验

从「请求里写了一个档、响应里报回来另一个档」这个具体现象出发，沿 OpenRouter 官方文档《Service Tiers》页把一次请求的分档路径走一遍：请求侧怎么选档、两种选法的差别、priority 与 flex 的回退规则各不相同、响应字段在三种 API 里放的位置不一样。只讲字段语义与机制，不涉及价格与额度数值。

OpenRouter 流式响应中断怎么查：SSE 这一层能看到什么

流式输出写到一半停了，客户端却什么都没报——这类问题绝大多数能在 SSE 原始行里看出来。本文按 OpenRouter 官方文档《Streaming》页写明的事件形态，梳理正常流、注释行、中止事件与两类错误各自的可见信号，给出逐层判定动作、文档语义下的处置，以及哪些现象说明不是这个原因。

在 OpenRouter 上要结构化输出：不是所有路由路径都支持

OpenRouter 的结构化输出靠 response_format 里的 json_schema 声明，但官方文档写明支持与否是按 endpoint 判定的，同一个模型换个 provider 就可能不生效。本文按官方文档梳理 schema 的写法、strict 的实际含义、require_parameters 的兜底方式，以及不支持时会得到什么。

OpenRouter 的工具调用怎么写：跨供应商的统一层在哪

换一个模型，工具调用就回不来了？本文按 OpenRouter 官方文档梳理 tools 定义里每个字段的含义、tool_choice 与 parallel_tool_calls 的取值、请求为什么每一轮都要重发 tools，以及跨供应商差异是靠 require_parameters、参数软偏好和 Auto Exacto 这三层处理的，最后给出几处文档自身不一致的地方与验证办法。

OpenRouter 可用性配置越加越脆：uptime optimization 页那套组合怎么排查

按官方文档《Uptime Optimization》与《Provider Routing》的字段语义，梳理一次「参数加得越多、失败得越干脆」的排查路径：先用 X-OpenRouter-Metadata 把路由决策打开看候选端点数，再按收窄程度重排 order、allow_fallbacks、only、data_collection 这些过滤项，最后区分哪些错误跟路由配置根本无关。

OpenRouter 的 API 变更怎么跟：versioning 与 changelog 怎么读

接入 OpenRouter 之后，客户端某天开始解析失败，或者 changelog 上挂着 Breaking 标签却不知道要不要改。这篇按排查顺序走一遍：怎么定位版本、官方把哪几类改动算破坏性、null 字段为什么算破坏、以及哪些症状根本不该去翻 changelog。

OpenRouter 工作区与预算：把团队的花销切开

一个账号下多个项目共用密钥，出了账单谁也说不清是谁花的。这篇按 OpenRouter 官方文档梳理 workspace 的隔离范围、预算上限的四个 interval 与严格递减规则、管理 API 的三个端点，以及切换工作区时会咬人的几处边界。

OpenRouter 的零数据保留与主权 AI：两个常被混为一谈的开关

OpenRouter 文档里的 ZDR 与 Sovereign AI 经常被当成同一件事，但它们约束的是两个不同维度——数据请求结束后还在不在，和数据在哪个辖区被处理。本文沿着一次请求的路径，把两者各自的字段、生效层级与覆盖边界拆开讲清楚。

OpenRouter 的空补全保险是什么：返回空内容时的计费与重试口径

调用 OpenRouter 拿到一次空返回，最先担心的是这次白跑要不要付钱。本文按官方文档《Zero Completion Insurance》页的原文，梳理这层保护的两个触发条件、覆盖到哪几类 token、文本转语音与图像生成各自怎么算「有效输出」，以及哪些附加服务费用不在覆盖范围内，并说明文档里没有写的部分。

Playwright 的 click 做哪些检查：actionability 拆开看

Playwright 的 click 在真正按下鼠标之前会跑一串可操作性检查。本文沿着仓库里的文档与源码走一遍这条路径，说清五项检查各自对应什么 DOM 判定、它们的实际执行顺序为什么和文档表格不完全一致、哪些动作会跳过哪几项，以及 force 与 trial 分别关掉了什么。

用 Playwright 做接口测试：不开浏览器也能跑

同一套 Playwright 工程里，request fixture、playwright.request.newContext() 和 page.request 是三个不同的东西，cookie 归属和生命周期都不一样。本文按仓库文档与源码梳理它们的分工，重点讲鉴权头到底该放在哪一层、beforeAll 里拿到的 request 为什么不能带进 test，以及配置项是通过哪段代码补进请求上下文的。

Playwright ARIA 快照怎么读：YAML 结构与截图快照的边界

从一次 toMatchAriaSnapshot 断言出发，沿 Playwright 仓库的文档与源码走一遍：YAML 节点的三段结构从哪来、role 与 accessible name 在 roleUtils 里怎么算、模板一侧的 /children 与 /url 是怎么被解析的，以及它和截图基线在存储与适用范围上的分界。

Playwright web-first 断言的重试：toHaveText 到 Frame.expect

同样是判断元素可见，写成 expect(await locator.isVisible()).toBe(true) 会偶发失败，写成 await expect(locator).toBeVisible() 就不会。本文沿着 Playwright 仓库里的文档与源码走一遍这条路径，说清哪些断言会重试、哪些不会、重试发生在进程的哪一侧、超时到底从哪一层取值，以及 expect.poll 与 expect.toPass 各自补在什么位置。

Playwright 登录态突然失效：storageState 过期与作用域排查

跑了几周好好的 storageState 突然全线未登录，多半不是 Playwright 坏了，而是 token 过期、cookie 的 domain/path 对不上、或者几个 project 共用了同一份状态文件。本文按仓库文档与 API 签名，给出逐条可执行的判定动作与处置边界。

每个用例都重新登录太慢：用 Playwright storageState 存下登录态复用

从 Playwright 仓库 docs/src/auth.md 与 docs/src/api/class-browsercontext.md 出发，讲清 storageState 的存与读、setup 项目与 globalSetup 两种挂载方式的差别、多角色场景怎么分文件，以及文档里明说不支持的那几处边界。

Playwright 的自动等待到底等什么：为什么大多数 sleep 是多余的

顺着 Playwright 仓库里的文档与服务端源码走一遍一次点击的完整路径，说清自动等待覆盖了哪些动作、哪些状态检查、断言侧的重试怎么工作，以及仓库明确留给显式等待的那几种场景。

playwright install 下载浏览器失败：Playwright 在离线与代理环境怎么装

公司网络或离线机器上跑 playwright install 卡住、报证书错误、超时时，怎么用 --dry-run 先确认它到底要去哪儿下、下到哪儿，再用下载镜像与代理变量改掉来源，或者干脆指向一份已有的浏览器。所有依据来自 Playwright 仓库的文档与源码。

Playwright BrowserContext 隔离边界：什么共享什么不共享

从「新建一个 context 之后到底什么被清空了」这个问题出发，沿 Playwright 仓库里 BrowserContext 的 API 文档走一遍：cookie、localStorage、IndexedDB、权限授予、HTTP 缓存各自挂在哪一层，哪些能在 page 级覆盖，哪些根本不归 context 管，以及多开 context 与多开 browser 的成本差在哪里。

Playwright 没封装的能力：用 CDPSession 直接发 CDP 命令

Playwright 的高层 API 覆盖不到的浏览器能力，可以通过 CDPSession 直接发原始 Chrome DevTools Protocol 命令。这篇沿着仓库文档与源码走一遍：会话从哪两个入口建立、为什么只有 Chromium 能用、四种语言绑定订阅事件的写法差在哪，以及它和 page、context 混用时在域状态、生命周期和超时上的几处坑。

本机全过 CI 全挂：把 Playwright 的环境差异按五层拆开逐层对

本机跑绿、推上 CI 全红，是 Playwright 用户最常撞的一类问题。这篇把本机与 CI 的差异拆成浏览器版本、系统依赖与字体、并发度、视口、网络五层，每层给出仓库文档里写明的判定动作与处置方式，并说明哪些现象说明问题不在环境层。

把 Playwright 接进 CI：从跑得起来到出报告

本地测试全绿、推到 GitHub Actions 就红一片，多半是浏览器和系统依赖没装对，或者失败现场没被上传出来。这篇按 Playwright 仓库 docs/src/ci.md 与 ci-intro.md 写明的三步走一遍：装依赖、装浏览器、跑测试，再把 HTML 报告和 trace 用 upload-artifact 带出来，并说清 Windows 侧与 Linux 侧的差别。

Playwright Clock API 把时间捏在手里：setFixedTime 与 runFor

倒计时、无操作自动登出、每秒刷新的时钟组件，用真实等待去测既慢又不稳。Playwright 的 Clock 提供了四个语义完全不同的入口，本文按仓库文档与源码把它们的差别、适用场景、调用顺序限制与报错条件讲清楚，并说明为什么固定了时间断言字符串仍可能对不上。

用 Playwright codegen 录制生成测试代码：哪些必须自己改

Playwright 的 codegen 能把你在浏览器里的点击录成测试代码，但生成的定位器有一套打分规则，落到 nth 和 CSS 兜底上时必须手改。本文按仓库文档与源码讲清录制命令的常用选项、定位器为什么要改、以及录制登录态的 --save-storage / --load-storage 做法与它的边界。

Playwright 组件测试：在真实浏览器里挂载单个组件

想只测一个按钮组件，却得先启动整个应用、一层层点进去。Playwright 的 mount fixture 把组件测试做成了普通的端到端测试：你自己的 dev server 提供一张 gallery 页，测试导航过去挂载一个 story。本文按仓库文档梳理初始化命令、mount() 用法，以及与端到端共用一份配置时哪些开关不能放在顶层。

Playwright 的配置优先级链：同一个选项在四个地方都能设

同一个 locale 可以写在全局 use、项目 use、文件或 describe 里的 test.use，还能被命令行参数顶掉，最后到底谁生效？本文顺着 Playwright 仓库里配置合并与 fixture 池的那几行代码走一遍，标出决定顺序的函数名与文件位置，并说明命令行到底能改哪几个键、describe 级为什么改不动某些选项。

弹出确认框后用例卡死：Playwright 里 dialog 的默认处置是什么

点击按钮触发 confirm 后用例再也不往下走，多半是注册了 dialog 监听却没有在监听里 accept 或 dismiss。本文按仓库文档与源码梳理无监听时的默认处置、监听的注册时机、beforeunload 的特殊之处，并给出判定动作与排除条件。

在 Docker 里跑 Playwright：官方镜像与自建镜像的取舍

本机跑得好好的用例，进了容器就报浏览器起不来。这篇按 Playwright 仓库里的 docker.md、browsers.md 与 utils/docker/Dockerfile.noble，讲清官方镜像里到底预装了什么、自建镜像需要补哪些系统依赖，以及容器里跑 headed 为什么要 Xvfb。

触发下载后拿不到文件：Playwright 的 download 事件与保存路径

点击了下载按钮，脚本却拿不到文件，或者拿到路径后文件又消失了。本文按 Playwright 仓库里 docs/src/downloads.md 与 docs/src/api/class-download.md 写明的语义，梳理 download 事件的触发时机、四种语言绑定各自的等待写法、saveAs 与临时文件的关系，以及 context 关闭后文件的去向，并给出可执行的判定动作与排除条件。

Playwright 点不到页面上的元素：actionability 卡在哪一项

Playwright 点击超时时，真正卡住的往往不是定位器，而是可见、稳定、可接收事件、可用、可编辑这五项检查中的某一项。本文按仓库文档与源码，讲清每一项的判定语义、怎么从日志里读出卡在哪一步，以及 force 到底关掉了什么、代价是什么。

模拟设备、语言、时区、权限：Playwright 的 emulation 能改哪些环境变量

Playwright 的 emulation 把设备参数、语言、时区、地理位置和浏览器权限都做成了 context 级选项，但这几组选项的作用范围并不一样：有的只能在建 context 时定死，有的运行中还能改，有的只能整个 context 一起改。本文按仓库文档与源码，逐组说清它们改的是什么、边界在哪、怎么验证真的生效了。

Playwright fixture 的生命周期：test 级和 worker 级到底差在哪

从一个具体问题出发——自己写的 fixture 到底跑几次、重试之后会不会重跑。沿着 Playwright 仓库里的文档与 fixture 注册源码走一遍 scope 的两个取值、初始化时机、依赖方向、worker 复用的判定，以及 worker 级 fixture 在测试失败重试时的行为。

自定义 fixture：把 Playwright 用例里的重复准备工作抽出去

用例越写越多，beforeEach 里的登录、建数据、跳页面就越堆越厚，afterEach 还得写一遍对应的清理。Playwright Test 的 test.extend 把这两半合到一个函数里，用 use() 划开 setup 与 teardown。本文按 Playwright 仓库文档与源码，讲清 test.extend 的写法、fixture 函数的参数解析规则、use() 前后各干什么，以及哪些写法会在加载阶段直接报错。

Playwright 用例时好时坏：retries 是止血不是治本，先分清三类

一个用例本地全绿、CI 偶尔红，加一行 retries 就没人再看了。本文按 Playwright 仓库文档梳理 retries 的配置层级与 retryStrategy 的两种取值，讲清 trace 的七种模式里哪些根本不录首跑，以及 test.fixme 与 test.fail 各自适用于哪种失败，最后给出「不是这个原因」的排除条件。

Playwright iframe 里元素定位不到：frameLocator 怎么串

用例在 iframe 上超时，报错却只说找不到元素。这篇按 Playwright 仓库里 FrameLocator 的文档与测试用例，讲清楚 frameLocator 与 frame() 的分工、嵌套 iframe 的链式写法、pierceFrames 的边界，以及哪些报错其实不是 iframe 引起的。

跑完还剩一堆浏览器进程：Playwright 资源没释放的几处常见原因

脚本跑完了，任务管理器里还挂着一排浏览器进程。本文按 Playwright 仓库文档里写明的关闭语义，把 Test Runner、library、launchPersistentContext、connect 四种用法下 context 与 browser 的关闭责任归属讲清楚，并给出可执行的判定与验证动作。

Playwright 定位器入门：七个 getBy 方法该先用哪个

从 Playwright 仓库 docs/src/locators.md 出发，逐个讲清 getByRole、getByLabel、getByPlaceholder、getByText、getByAltText、getByTitle、getByTestId 各自的适用条件与文档给出的取舍原则，每个都附仓库里的原始示例，并交代严格模式、Shadow DOM 例外、filter 相对性这些边界。

Playwright 报 strict mode violation：定位器怎么收窄

一条 click 忽然报 strict mode violation，说定位器解析到了多个元素。这篇顺着 Playwright 仓库的文档与源码，讲清楚 strict 到底在什么时机判定、报错里的每一行怎么读，以及 filter()、链式、first()/nth()、and()/or() 这几种收窄手段各自改了什么、文档对它们的态度差在哪里，最后给出判定「不是这个原因」的几种情形。

Playwright Locator vs ElementHandle：查询还是句柄

同一段点击代码，用 page.$ 拿到的句柄会偶发报 Element is not attached to the DOM，换成 getByText 就不会。本文沿着 Playwright 仓库里的文档与客户端、服务端源码走一遍这条路径，说清惰性求值与即时求值差在哪、元素脱离 DOM 时两条路径的处置为什么不同，以及官方把 ElementHandle 标成 discouraged 时给出的原话理由。

Playwright 页面跳转后操作报错：导航等待到底等的是什么

Playwright 用例里点完按钮页面跳走了，下一句操作却报 Execution context was destroyed，或者 waitForURL 明明写了却像没等。这篇按仓库文档与源码梳理自动等待到底覆盖了什么、waitForURL 与 waitForLoadState 差在哪、SPA 路由和 BFCache 这两类跳转仓库是怎么定性的，并给出可执行的判定动作与排除条件。

Playwright route 不生效：Service Worker 或时序绕过

写好的 page.route 一行都没被调用，页面照样打到真接口。这篇按 Playwright 仓库文档里写明的语义，拆开三个最常见的原因：Service Worker 接管了请求、拦截注册的时机与层级不对、匹配与优先级被后注册的 handler 吃掉，并给出可执行的判定动作与反向排除条件。

用 Playwright route 拦截网络请求：测试不依赖后端

后端接口没就绪、返回值天天变、测空列表要造数据，端到端测试就卡在这。Playwright 的 page.route 把请求截在浏览器和网络之间，可以直接造响应、放行、掐断，也可以用 HAR 文件回放。本文按仓库文档梳理匹配规则、三种处置方式和 HAR 的录制回放，并交代文档写明的边界。

并行跑就互相干扰：Playwright 哪些用例必须串行、怎么划范围

本地一个个跑全绿，一到 CI 并行就随机红几个。这篇按排查顺序走一遍：怎么先确认问题确实出在并发上，Playwright 的 worker 隔离到底隔了什么、没隔什么，test.describe.configure 的作用域怎么算，什么时候该用 lock 而不是 serial，以及哪些现象说明根本不是并发的锅。

用 Playwright 的 projects 配置多浏览器多环境：一份配置跑出多套组合

同一批用例要在 chromium/firefox/webkit 上跑、又要分别打到 staging 和 production，很多团队的做法是复制好几份配置文件。Playwright 的 projects 数组把这件事收进一个配置里，本文按仓库文档梳理 projects 的字段语义、dependencies 串联顺序，以及怎么按项目过滤运行。

Playwright Python 版入门：和 JS 版不一样的那几处

网上的 Playwright 教程绝大多数是 JS 版的，照着抄到 Python 里会卡在几个地方：装的包不一样、没有 playwright.config、同步和异步是两套 import、异步测试还要另装一个包。这篇按仓库里 Python 专属文档的写法，把安装、fixture、CLI 参数和 Windows 侧的坑一次讲清楚。

Playwright 报告器配置：内置几种怎么选、怎么同时输出多份

从仓库文档出发，讲清 Playwright Test 内置报告器各自产出什么形态的东西、怎么用数组式配置同时输出终端可读与机器可读的两份结果，以及自定义 reporter 需要实现哪些钩子方法、这些钩子按什么顺序被调用、有哪些文档写明的边界。

Shadow DOM 里的元素定位：Playwright 哪些选择器能穿透

用了 Web Components 的页面上，同一个元素用 CSS 能定位，换成一条看起来等价的 XPath 就查不到。本文对着 Playwright 仓库的 locators.md、other-locators.md 与 packages/injected/src 下的选择器引擎源码，说清哪些定位方式会穿透 open shadow root、XPath 为什么不行、getByRole 在 shadow 边界上的两种表现，以及怎么判断问题根本不出在这里。

用例太多跑太久：Playwright 的 sharding 分片并行怎么切

一条 CI 流水线跑几十分钟的端到端用例，靠单机加 worker 已经压不下去了。这篇沿着 Playwright 仓库里的 sharding 文档与 runner 源码，讲清 --shard=x/y 的参数语义、fullyParallel 对切分粒度的影响、blob 报告器为什么是分片的必需品，以及 merge-reports 合并时最容易踩的跨系统 rootDir 报错。

视觉快照换台机器就挂：Playwright 跨平台渲染差异怎么处理

本地跑绿的视觉快照一进 CI 就红，多半不是页面变了，而是快照文件名里的平台后缀对不上。本文按仓库文档与源码，讲清快照路径怎么拼出来、阈值选项各自管什么、以及把基线生成固定到容器里的做法，并给出「什么情况说明不是这个原因」的排除条件。

Playwright TestInfo 里能拿到什么：把用例上下文用起来

用例在 CI 上挂了，报告里只有一行报错，想把当时的日志和接口返回塞进去。本文沿着 Playwright 仓库的 class-testinfo.md 与 worker/testInfo.ts 走一遍：TestInfo 上有哪些字段、attach 到底做了什么、在 fixture 里什么时候读才读得到。

Playwright 超时报错分层排查：到底是哪一层的 timeout 触发的

同样是超时，Playwright 里至少有五个不同的 timeout 会把用例打挂，报错文本各不相同。本文按仓库文档给的错误样例和配置项，讲清楚怎么先判定是哪一层触发的，再去改对应的那一个开关，以及哪些现象说明问题根本不在超时配置上。

一个 Playwright trace 文件里到底存了什么

把 Playwright 的 trace.zip 拆开，沿着仓库源码走一遍：zip 里有哪些条目、每一类条目由哪个开关决定、快照与网络与控制台与源码与附件分别落在哪个目录、以及为什么脚本响应体默认不进档案。全部依据仓库内的文档与源码，讲清开关与体积的对应关系。

Playwright Trace Viewer 上手：一个 trace 文件怎么看出用例挂在哪一步

CI 上失败的用例本地复现不了，日志只剩一行超时。这篇按 Playwright 仓库文档梳理 trace 的开启方式与取值语义、打开 trace 的两条路径，以及界面上时间轴、左侧导航与右侧各个标签页分别对应 trace 里的哪部分数据，并交代文档写明的限制与验证方法。

Playwright 的 TypeScript 类型报错：fixture 扩展后类型对不上

自定义 fixture 之后，编辑器提示参数上没有这个属性、worker fixture 赋值类型不匹配、配置文件里的自定义 option 不认——这几类报错的根源都在 test.extend 的两个泛型参数和 tsconfig 的支持范围上。本文按仓库里的类型定义与文档，给出判定动作、处置写法和排除条件。

Playwright UI Mode 怎么用：把改一行跑一次的循环缩短

写端到端用例最耗时间的不是写，是改一行、跑一次、盯终端。这篇按 Playwright 仓库里的文档与源码，讲清 UI Mode 的启动参数（--ui / --ui-host / --ui-port）、watch 模式盯的到底是哪些文件、按 @tag 与 project 过滤怎么落到命令行上、pick locator 的用法，以及源码里几处会咬人的边界。

视觉回归怎么做：Playwright toHaveScreenshot 的基线与阈值

从首次运行生成基线、用 --update-snapshots 的四种模式更新基线，到 threshold/maxDiffPixels 两级阈值怎么配、动态区域用 mask 与 stylePath 怎么挡，全部依据 Playwright 仓库里的文档与源码，并说明这套能力的适用边界。

Playwright webServer 没等服务就开跑：url、port、wait

Playwright 的 webServer 把 dev server 拉起来之后，到底凭什么判断「可以开跑了」？本文沿着仓库里 webServerPlugin.ts 的代码路径，把 url 的 HTTP 探活、port 的 TCP 探活、wait 的日志匹配三种语义拆开，给出用 DEBUG=pw:webserver 判定的可执行动作、对应的处置写法，以及哪些报错说明根本不是这个原因。

Playwright 的 worker 进程模型：一个 worker 里跑几个用例

从「我配了 workers 为什么进程数对不上」这个问题出发，沿着 Playwright 仓库里 createTestGroups、workerHash 与 dispatcher 的调度代码走一遍，说清 worker 什么时候被复用、什么时候被推倒重建、失败之后新 worker 怎么接着跑，以及 workers 这个配置项到底在配什么。

装 VibeVoice 依赖时对不上：先看 pyproject.toml 写了什么

按文档装完 VibeVoice，换一个模型的路线就报版本不符，或者 extra 写上去像没生效。这篇不猜原因，直接翻仓库根目录的 pyproject.toml，把声明的依赖、唯一的可选依赖组、Python 版本要求和几处文档与配置对不上的地方一条条对出来，并给出可执行的判定动作与排除条件。

服务中断后自动恢复：VibeVoice 仓库自带的恢复脚本覆盖了什么

VibeVoice 的 vLLM ASR 插件带了一份名字叫 auto_recover 的测试脚本。它到底模拟了哪种故障、重试时断言了什么恢复行为、又有哪几类中断根本不在它的覆盖范围内——本文沿着脚本源码把这三件事分清楚，并给出可执行的判定动作。

VibeVoice 的 modeling_vibevoice_asr.py：ASR 和 TTS 差在哪

沿着 VibeVoice 仓库里 modeling_vibevoice_asr.py 的代码走一遍，看清 VibeVoiceASRModel 与 VibeVoiceASRForConditionalGeneration 的分层、encode_speech 的两条分支、语音特征怎么按 mask 塞进 inputs_embeds，以及这份文件与 TTS 侧 modeling_vibevoice.py 在类继承、组件与 loss 上的结构差别。

VibeVoice-ASR 上手：文档给的调用路径与输出结构

从仓库文档与源码出发，梳理 VibeVoice-ASR 的输入怎么准备、调用怎么写、结构化转写结果里说话人与时间戳落在哪几个字段上，并把几处容易踩的默认值差异和解析失败的兜底行为标出来。全文只转述仓库里写明的内容，不涉及任何运行表现。

注意力实现选择报错：VibeVoice 里 _attn_implementation 相关配置怎么看

VibeVoice 各个 demo 与微调脚本对注意力实现的处理方式并不一致，有的会自动回退到 sdpa，有的直接硬编码 flash_attention_2。这篇沿着仓库里的 argparse 定义、config 类构造函数和 PreTrainedModel 的支持标志，梳理这个参数到底在哪几处被决定，报错时该从哪一行开始查。

VibeVoice 仓库结构导览：四个模型、五份文档、一个 vLLM 插件

克隆下 VibeVoice 之后，最容易卡住的不是环境，而是目录名和模型名对不上。这篇按仓库实际内容梳理 docs 下五份文档与 README 里四个模型的对应关系、vibevoice 包里各子目录的职责，以及三层 `__init__.py` 各自导出了哪些符号、哪些类根本不在导出清单里。

长音频怎么被切：VibeVoice ASR 的 processor 分块逻辑排查

一段一小时的会议录音送进 VibeVoice ASR，到底在哪一层被切开、切完靠什么把上下文接回去？本文顺着仓库里的 processor 与模型代码把这条链路走一遍，给出可执行的判定动作，并说明哪些异常其实跟分块无关。

在 Colab 上跑官方 notebook：VibeVoice 仓库给的那份怎么用

VibeVoice 仓库里 demo/vibevoice_realtime_colab.ipynb 只有两个大单元，但卡住的位置很集中：环境检查只警告不中断、克隆单元第二次执行会短路、端口和隧道要对上、实验音色必须在启动服务之前下好。本文按单元顺序逐个说清判定动作与处置依据。

VibeVoice 的 configuration_vibevoice.py：五个配置类各管哪一段

下载一份 VibeVoice 权重，打开 config.json 会看到一层套一层的字典，很难判断某个键归哪个类解析、改了会被谁读到。这篇沿着 vibevoice/modular/configuration_vibevoice.py 走一遍，把里面的字段按声明位置和消费位置分组，并指出几处代码与权重配置对不上的地方。

VibeVoice 的 diffusion head 在代码里长什么样：语音 latent 的生成路径

顺着 VibeVoice 仓库里 modular_vibevoice_diffusion_head.py 这一个文件读下去，看清 diffusion head 的模块结构、三个入参的前向流程，以及它怎么被主干模型装配、训练侧与推理侧分别怎么调用，顺带指出几处配置字段与代码对不上的地方。

dpm_solver.py 在 VibeVoice 里做什么：扩散采样的调度那一段

顺着 VibeVoice 仓库的代码读一遍：一次语音潜变量的扩散采样，从 set_timesteps 到 step 各自做了什么，DPMSolverMultistepScheduler 由谁构造、吃了哪些 config 字段，timestep_sampler.py 里那两个采样器又落在哪。只讲代码里写明的东西。

按官方文档搭 VibeVoice 的 Gradio demo：依赖、启动参数与页面怎么暴露

VibeVoice 仓库里有两个 Gradio 脚本，一个连 vLLM 服务、一个直接加载模型，参数和依赖并不通用。本文按仓库文档与脚本源码把依赖准备、启动参数、页面暴露方式这三件事逐条落到具体文件上，并标出文档与代码对不上的几处。

VibeVoice 的 Gradio demo 起不来：按仓库文档的前置条件逐条核

VibeVoice 仓库 docs/setup_gradio_demo.md 给的是一条 Docker + vLLM ASR 服务 + Gradio 前端的链路，中间任何一环没起来，表现都是「demo 打不开」。这篇把前置条件、端口与参数、日志里的判定信号拆开，按仓库文档与 vllm_plugin 源码里写明的语义，给出一套从下往上的排查顺序，以及哪些现象说明问题根本不在这条链上。

VibeVoice 的架构总述：LLM 加扩散头这条路线怎么走

沿着 VibeVoice 仓库的源码走一遍连续语音 tokenizer、SpeechConnector 与 diffusion head 三块的分工，说明音频在哪一步被压成连续 latent、latent 怎么接进 LLM 的词嵌入序列、扩散头又是拿什么当条件的，同时交代 TTS 代码在该仓库中的当前状态。

VibeVoice 流式 demo 拆解：vibevoice_realtime_demo.py 的调用链

VibeVoice 仓库里的实时 demo 只有十几行，真正的链路藏在 demo/web/app.py 与 index.html 里。本文按初始化、流式送入、音频输出回调三段读这份代码，标出关键类名、函数名与配置项，并交代仓库写明的边界与 TTS 代码移除状态。

LoRA 微调数据准备踩坑：VibeVoice ASR 的 README 对格式的要求逐条看

VibeVoice 仓库 finetuning-asr 目录下的 LoRA 脚本对训练数据有一套不太显眼的要求，样本对不上时多数是被 warning 静默跳过而不是报错。本文按 lora_finetune.py 的读取顺序，把 JSON 字段、必填与选填的分界、校验发生在哪一行、以及几种常见不匹配的判定动作理一遍。

LoRA 微调完怎么推理：VibeVoice 的 inference_lora.py 加载路径

VibeVoice ASR 的 LoRA 训练跑完之后，输出目录里只有适配器权重，不是一个能直接加载的完整模型。这篇沿着仓库里 finetuning-asr/inference_lora.py 的代码走一遍：适配器怎么挂到基座上、哪些层被改了、生成出来的文本又是怎么被解析成结构化字段的。

给 VibeVoice-ASR 做 LoRA 微调：官方微调代码怎么用

手上有一批带转写稿的行业录音，想让 VibeVoice-ASR 更贴合自家术语。本文按仓库 finetuning-asr 目录的代码，讲清训练数据要摆成什么样、JSON 标注有哪些字段、训练脚本的参数从哪来、产物落在哪里，以及代码里写死了哪些你在命令行改不动的地方。

VibeVoice 的 processor 家族：一段输入在四个类之间怎么流转

VibeVoice 仓库的 processor 目录下躺着四个都叫 processor 的类，但包的 __init__ 只导出三个。这篇沿着代码把一段音频与一段脚本各自走过的路径读一遍，标出每个类的输入输出、调用顺序，以及 text tokenizer 究竟插在哪一步。

VibeVoice-Realtime-0.5B 上手：流式文本输入到底怎么喂

从仓库代码出发，梳理 VibeVoice-Realtime-0.5B 的两条上手路径、processor 与 generate 的接口怎么对接、生成循环里文本窗口与语音窗口如何交替，以及「流式文本输入」当前落到哪一步、实验性音色放在哪个脚本里。

转写结果里说话人标记不对：VibeVoice-ASR 的热词与上下文定制怎么传

转写出来的段落里说话人一列是 N/A，或者专有名词被听成了别的词，多半不是模型的问题，而是热词根本没进到 prompt 里。本文沿着 VibeVoice 仓库里 ASR processor 的代码，把 context_info 的几条传入通路、它拼进 prompt 的确切形状、以及它对输出 JSON 结构的影响一处处对上，最后说清哪些情况和热词无关。

AudioStreamer 与 AsyncAudioStreamer 在 VibeVoice 里怎么分工

VibeVoice 仓库里 vibevoice/modular/streamer.py 篇幅不长，却决定了生成循环怎么把音频块交给消费端。本文沿着 put/end 的生产端与 get_stream 的消费端走一遍，说清同步版与异步版在队列类型、线程桥接和迭代器语义上的差别，以及仓库里实际用了哪一个。

VibeVoice 流式版配置差在哪：configuration_vibevoice_streaming.py

model_type 写着 vibevoice_streaming 的 config，比 VibeVoice 另一份多了 tts_backbone_num_hidden_layers、少了整块 semantic_tokenizer_config。本文顺着流式配置类 VibeVoiceStreamingConfig 的源码，把这两处差异落到具体代码行。

VibeVoice 流式推理完整链路：900 多行 inference 怎么读

调用方只写了一句 generate()，音频却是一块块从队列里冒出来的。本文沿 VibeVoice 仓库里的流式推理文件走一遍：主循环怎么切文本窗口、四套状态各自怎么推进、latent 怎么变回喂给模型的 embedding，以及 generate 与 AudioStreamer 到底在哪三行交接。

VibeVoice 连续语音 tokenizer：acoustic 与 semantic 两路怎么分工

顺着 VibeVoice 仓库里 modular_vibevoice_tokenizer.py 走一遍：一段波形进来之后，acoustic 与 semantic 两个 tokenizer 类各自走哪条路、编码与解码分别落在哪些模块上、流式缓存类用什么键存状态、以及分段推理时这些缓存在哪里被真正创建和传下去。只讲代码结构，不涉及运行表现。

generate_tokenizer_files.py 做了什么：VibeVoice 上 vLLM 部署

VibeVoice 仓库里有个不起眼的小脚本，负责给 vLLM 部署准备 tokenizer 文件。这篇按源码把它生成哪几个文件、每个文件被改了什么、什么时候需要重新生成讲清楚，并标出脚本里几处容易踩到的边界。

transformers 版本不兼容：VibeVoice 的 ALL_PARALLEL_STYLES 兜底补丁

VibeVoice 的四个 modeling 模块顶部都写了同一段 modeling_utils.ALL_PARALLEL_STYLES 兜底赋值。本文顺着这段代码，把它补的属性、触发条件、与 tp_plan 的对应关系，以及仓库里另一处 transformers 版本兼容层放在一起看，给出一套可以照着执行的判定与排除动作。

想跑 VibeVoice-TTS 却发现状态特殊：仓库到底还剩什么

照着旧教程导入 VibeVoice 的 TTS 类却对不上，多半不是你环境的问题。本文按排查思路走一遍：怎么在仓库里确认 TTS 代码的移除记录、当前模块的导出边界与社区 fork 来源注释，处置后怎么复核，以及哪些报错其实是另一码事。

用 vLLM 跑 VibeVoice-ASR：官方文档给的完整路径

从 VibeVoice 仓库的 vLLM 插件文档与源码出发，把插件怎么注册、模型怎么加载、请求长什么样、文档写明的限制在哪，逐条对着文件讲清楚。只转述仓库里写了什么，不涉及任何实际运行表现。

vLLM 插件注册不上：VibeVoice 的 vllm_plugin 入口在哪

VibeVoice 的 vLLM 部署走的是插件注册，不改 vLLM 源码。本文按仓库里的 pyproject.toml 入口声明、vllm_plugin/__init__.py 的注册函数、model.py 上的多模态 processor 装饰器，把「插件没加载」这类现象的判定动作、处置依据、验证方式和排除条件逐条对上，并指出源码里几处版本耦合与静默吞异常的地方。

VibeVoice 的 vLLM server 怎么起：start_server.py 逐段读

把 VibeVoice ASR 变成一个 HTTP 服务，仓库给的入口是 vllm_plugin/scripts/start_server.py。这篇按脚本里的五步流程逐段读：命令行参数各自控制什么、写死在 _build_vllm_cmd 里的那串 vllm serve 选项、plugin 靠 entry point 怎么注册进 vLLM，以及多副本时 nginx 那条分支的边界在哪。

VibeVoice 自带的 Web demo：demo/web/app.py 怎么组织

VibeVoice 仓库里带了一个 FastAPI + WebSocket 的网页 demo，只有 app.py 和 index.html 两个文件。这篇把它的三条路由、二进制音频帧与 JSON 日志帧的双通道设计、后台生成线程与 asyncio 的衔接方式逐段读一遍，并列出启动前必须准备的环境变量、音色目录，以及仓库文档自己写明的边界与部署注意事项。

从文件直接推理：VibeVoice 两个 *_from_file.py 的差别

VibeVoice 仓库的 demo 目录下有两个名字都以 _from_file.py 结尾的脚本，一个吃文本、一个吃音频，参数、处理链路和落盘行为完全不同。这篇沿着两份源码走一遍，把各自的输入假设、依赖前置和边界条件说清楚，避免照着文档复制命令时用错脚本。

音频输入格式不对：VibeVoice 的 audio_utils.py 对采样率和声道要求什么

同一个多声道、非 24kHz 的音频，走文件路径进 VibeVoice 不报错，换成 numpy 数组传进去就出问题。本文顺着仓库里 vibevoice/processor/audio_utils.py 与两个 processor 的代码，把三条入口分支各自做了什么重采样与声道处理讲清楚，并给出可执行的判定动作与验证方法。

DeepSeek Harness 的用户审批是怎么弹出来的：谁发起、谁应答、拒绝之后发生什么

沿着 DeepSeek Harness 仓库里 ctx.approval 的调用路径走一遍：一次工具调用在哪一步变成审批请求、never 策略在哪里被提前判掉、四种 outcome 分别映射成什么拒绝文案，以及没有任何应答者时为什么结果是拒绝而不是放行。

DeepSeek Harness 怎么存一张图：持久图片附件的落盘、引用与清理

沿着 DeepSeek Harness 仓库里 attachment 这条路走一遍：一张图从提交到落盘要过几道准入检查、四个默认上限分别是多少、引用里到底存了什么、读回时怎么校验，以及为什么"删会话"并不等于"删图"。全部依据仓库源码与子系统文档，不含任何本机运行结论。

DeepSeek Harness 的 dsh-code-review skill 是怎么维护的

团队里那份代码评审提示词写完就没人动过，是很常见的结局。DeepSeek Harness 把自己的 dsh-code-review skill 交给一套周期维护流程，本文沿着仓库里的 cookbook、Agent Note 与门禁脚本走一遍：文件在哪、谁改它、采纳证据怎么算、哪几道门禁真的读到了它，以及文档自己标出来的未完成部分。

DeepSeek Harness 的代码运行时：模型写的代码在哪儿跑、能碰到什么

顺着 DeepSeek Harness 仓库里 run_code 的调用链走一遍，说明模型写的那段程序被塞进哪个 worker、看得到哪些全局对象、被哪两个预算掐掉、超出输出上限会得到什么结果，以及仓库自己承认的边界在哪里。

DeepSeek Harness 的用户命令系统：斜杠命令从注册到执行的一条线

从输入框里敲下的一行斜杠命令出发，沿着 deepseek-harness 仓库的代码路径走一遍：解析正则怎么划边界、注册时校验哪些字段、command/run 与 command/done 这对日志在什么时刻落盘、取消信号能管到哪里，以及为什么命令的输出不会进入模型上下文。

DeepSeek Harness 的配置目录：所有能配的项都在这张自动生成的表里

docs/config-catalog.md 是脚本从源码生成并有校验闸门的配置总表。本文从「想改一个超时值该去哪查」出发，说明这张表收了哪 105 个包、三类没收进来的包在哪、默认值为什么常常不在表里，以及 cordis.yml 与 settings.yaml 两条配置轴的关系。

DeepSeek Harness 把你的 API Key 放在哪：凭据子系统的存取与作用域

从一次模型请求取 key 的调用路径出发，沿 DeepSeek Harness 的 credentials seam 与本地提供方走一遍：四层来源的优先级、set 为什么会被环境变量挡回来、`.credentials.yaml` 的严格格式与 0600 权限检查，以及仓库自己写明的安全边界与已知限制。

DeepSeek Harness 的防御式模式：他们踩过的坑写成了编码约定

DeepSeek Harness 仓库里有一份只有几百词的 defensive-patterns 文档，七条规则按文档自述全是这个项目实际发布过或差点发布出去的缺陷。这篇沿着一条 bash 命令的超时结果往下走，把这七条规则逐条对回 packages 下的实现：ShellRunResult 的字段为什么拆成那样、3000 毫秒的 graceMs 写在哪一行、环境变量清理的正则长什么样、spill 文件为什么要随机名加 0o600 打开。

DeepSeek Harness 团队怎么在堆叠 PR 上回应评审意见

评审意见落在依赖堆叠的中间那一层时，改哪一层、怎么往上传、推送之后凭什么说这条意见还处于已解决状态，都容易做反。这篇沿着 deepseek-harness 仓库里的堆叠评审指南、堆叠落地 skill 与推送前 skill 走一遍，把五条基本规则、七个处置步骤对应到 `gh stack` 命令与 `scripts/change-scope.ts` 里的具体校验，包括 worktree 隔离、lease 保护推送、同步后立即验证这几处，也照实标出仓库文档没有说明的部分。

DeepSeek Harness 的扩展开发手册：一个扩展的完整生态位

顺着 deepseek-harness 仓库里的扩展手册与 packages/extensions 源码走一遍，看清一个扩展从「挑哪种形态」到「挂在哪个扩展点」再到「运行时能不能看见它」的完整位置，并逐处标出文档与源码对不上的地方。

DeepSeek Harness 的扩展体系：packages/extensions 里到底装了什么

从「模型自己写一个插件、当场装进正在运行的进程」这条路径出发，沿 deepseek-harness 仓库的 packages/extensions 走一遍：四个包各自的分工、cordis_define 到 node:vm 的调用链、vmTimeoutMs 默认 5000 的确切含义，以及 README 与源码对不上的三处口径差异。

DeepSeek Harness 的消息反馈通道：模型跑着的时候你插一句 /feedback 会怎样

从「模型正在跑，我打一句反馈会不会打断它、会不会被模型看见」这个问题出发，沿 DeepSeek Harness 仓库里 feedback 家族的两条通道走一遍代码路径，落到 recordFeedback、recordInput、maxNoteBytes、ifVersion 这些具体字段与默认值上，并如实标出文档与源码口径不一致的两处。

DeepSeek Harness 的「同会话目标」：goal 是什么、跟计划模式是什么关系

从「会话恢复后它还会不会自己接着干」这个问题出发，沿 packages/goal 走一遍：四个持久 phase 与 armed/disarmed 两态怎么分工、一个 Goal Round 由谁放行、defaultMaxGoalRounds 256 与 blockedAfterConsecutiveRounds 3 这两个默认值分别管什么，以及 goal 与 plan mode 在源码里到底有没有关系。

DeepSeek Harness 的运行时不变式：一份写死的「不许出现」清单

从一条没有配对的授权事件出发，沿 DeepSeek Harness 的 invariants 注册表源码走一遍：Config 三个字段各自的默认值、包名正则不锚定与配置写错就启动失败的坑、包名被提前保留的语义、219 个工作区包里只有 35 个可执行检查，以及标准组合实际只挂了 4 个这件事，顺带记一处文档与源码的数量差异。

DeepSeek Harness 架构全图：host、client、runtime 这三段到底切在哪一刀

很多人拿到 deepseek-harness 会先按目录名把它理解成 host、client、runtime 三层。翻过源码就会发现这条线不是按目录走的：真正的硬切只有两个 face，写在 tsconfig.json 和 tsdown.config.ts 里，而且它是从包内部穿过去的。本文沿这条线走一遍，标出关键文件与数值。

DeepSeek Harness 后台任务运行时：ctx.jobs 怎么托住一个跑很久的活

一次 20 分钟的后台命令，工具调用早就返回了，是谁还记着它、谁负责杀它、结果又怎么回到模型手里。本文顺着 deepseek-harness 仓库里 packages/jobs 三个包的源码走一遍：start 的预检顺序、每 owner 默认 10 个的并发闸、settle 的先来先赢、以及完成通知那条 wakeup 预算为 3 的链路。

DeepSeek Harness 流式输出：一个 token 到屏幕上要经过几层

沿着 deepseek-harness 仓库的代码路径，把模型吐出的一个字从 SSE 字节到浏览器渲染之间经过的每一层拆开：SSE 解析、chunk 翻译、空闲 watchdog、llm/stream waterfall、agent loop 的双写、日志打包、推送帧与客户端二次折叠，逐层标出文件与默认值。

DeepSeek Harness 接了 LSP：语言服务给 Agent 带来了什么、又限制了什么

沿着 DeepSeek Harness 仓库里 lsp 工具的调用路径走一遍：一基坐标在哪一行转成零基、workspace 从哪里取、进程按什么粒度池化、结果被哪两个默认值截断，以及这条链路明确不做的那几件事。

DeepSeek Harness 的模块依赖图：哪个包被依赖得最狠、哪个是叶子

从 docs/module-graph.md 这张生成图出发，数清 packages/*/* 下 219 个包与 1089 条边，找出唯一叶子 invariants，对比「直接入度」与「传递影响面」两张榜为什么排序不同，并指出这张图只读 peerDependencies、看不见 bundle/base 那 75 条 dependencies 边的口径边界。

DeepSeek Harness 到底往磁盘写了多少种东西：持久化目录逐条看

一次对话结束后本机上留下了什么？本文按 deepseek-harness 仓库的持久化事件目录与 packages/storage 源码，数清会话日志的 44 种事件类型、磁盘上另外 4 种非事件行标签，以及非会话存储的三个领域、两个后端各自的落盘方式与版本号。

DeepSeek Harness 的会话持久化：一次对话在磁盘上留下哪些东西

顺着 deepseek-harness 仓库的源码走一遍会话落盘路径：目录根怎么解析、项目目录名怎么编码、日志文件叫什么、第一行 header 有哪些字段、事件什么时候才真正写进去、崩溃之后那半截轮次会被怎么处理，以及除了会话日志之外磁盘上还多出什么。

DeepSeek Harness 的计划模式：进入、退出与「不许动手」的边界

从一次 /plan 命令出发，沿 dsh-plan-mode 的源码走完进入、待生效、追加、退出的整条路径，标出 plan/mode 事件、order 50 的 plan:policy 段落、exit_plan_mode 的标题正则等具体位置，并说清「不许改文件」这句约束到底由谁执行。

一个 export default 让依赖注入失效：DeepSeek Harness 的 ACP 事故完整还原

DeepSeek Harness 仓库里有一份编号 0001 的事故复盘：ACP 服务器在编辑器连上的一瞬间崩溃，报错是「拿不到 agents，因为没有 inject」。本文沿着 Loader 的 unwrapExports、Cordis 的 fiber 遍历一路走到 AgentLoop.resume，标出每一处能自己回仓库核的文件与行号，并对照今天源码里还剩下什么守卫。

Web Agent 自己跟自己较劲：GUI 反馈闭环那次事故

DeepSeek Harness 仓库里的 postmortem 0003 记录了一次 Web agent 改完 GUI 源码却验收错对象的事故。本文沿着它的修复路径读源码，把 window.__DSH_BOOT__ 注入点、apps/web 拒启动的那一行、app:web-surface 提示词区段和 DSH_WEB_URL 变量逐个落到文件上，并指出文档口径与当前代码不一致的两处。

一个 !!js 表达式把文件系统工具全禁掉了：DeepSeek Harness 0002 号复盘

DeepSeek Harness 仓库里 0002 号事故复盘讲的是：一行写在 disabled 上的 !!js 表达式没有被求值，read/write/edit 三个工具在所有模式下都没注册，而快照测试却全绿。本文沿着配置、Loader 语义、守卫脚本走一遍，并指出复盘文档与当前仓库口径不一致的两处。

Landlock 部分强制执行被误判：0004 号事故与沙箱归因的真实边界

DeepSeek Harness 的 0004 号事故复盘里，一条无害的 Landlock 通知行让 ripgrep「没搜到」被报成沙箱不可用。本文沿 launcher 契约、RunnerFailureRule 三字段与 classifyRunnerFailure 的判定顺序走一遍代码路径，标出退出码 125 与 127，并说明哪些后端仍只靠签名匹配。

DeepSeek Harness 的事故复盘制度：他们把哪些事写成了案卷

deepseek-harness 把 bug 故事单独关在 docs/postmortem 一个目录里，全站其余文档明令禁止叙事。本文沿 docs/AGENTS.md 的分层表、postmortem/README.md 的准入三条件和四份案卷的实际节序走一遍：什么样的 bug 才配写成案卷，时间线为什么锚事件序号，防护措施为什么必须落到能在树里翻到的文件，以及案卷里有一条口径已经和今天的源码对不上了。

DeepSeek Harness 的会话投影：事件流怎么变成客户端看到的那个值

沿着 DeepSeek Harness 仓库里 session-projection 这条链路走一遍：一个 ProjectionDefinition 单元长什么样、注册表怎么把每个已提交事件折叠进每个单元、快照的 asOfSeq 从哪来、客户端为什么只认「seq 大的赢」，以及持久化投影缓存的两个强制写点与冷读阶梯。

DeepSeek Harness 的会话查询服务：历史会话是怎么被翻出来的

顺着 deepseek-harness 仓库 packages/session-query 下的源码走一遍：会话语料库怎么把 live 与持久化两个来源合成一条记录、全文搜索为什么在默认组合里是关闭的、哪些事件压根不会进索引，以及搜不到内容时该按什么顺序排查。

DeepSeek Harness 收不收数据：遥测子系统记了什么、记在哪、拿什么关

在公司机器上跑 dsh，会话内容会不会被传出去？顺着 deepseek-harness 仓库里 session-telemetry 这一对包的源码走一遍：默认 mode 为 DISABLED、DSH_TELEMETRY_DISABLED 任意非空值即硬关、一条记录带哪些字段、脱敏 waterfall 为何自带零规则。

DeepSeek Harness 的会话标题是谁起的：自动命名的触发时机与来源

会话列表里那行标题，在 DeepSeek Harness 里有三个可能的作者：确定性回退、注册的模型提供方、用户改名。本文沿着 packages/session/session-title 的代码路径走一遍，标出触发时机、字节上限、默认配置行与两条只写日志的事件，让你能自己回仓库里定位。

DeepSeek Harness 的设置分几层：用户设置的读取顺序与覆盖规则

顺着 DeepSeek Harness 仓库里 settings 子系统的代码路径走一遍：一个配置值要经过 schema 默认值、组合 base、用户文档三层，合并时对象递归、数组整体替换，删除只能走 replace 或 mutate。文中标出解析函数、默认文档路径与默认值，并按四个岔口给出改了没生效时的排查顺序，最后照实列出仓库自述的已知边界。

DeepSeek Harness 的 Bash 执行器：一条命令从下发到回显的完整链路

顺着 deepseek-harness 仓库里 packages/shell/ 下的源码，把模型发出的一条 bash 命令从参数校验、工作目录解析、resolve 补默认值、交给 bash -c 落地，一直走到退出码标记被解析回退出状态的完整过程串一遍。途中逐个标出超时默认值与上限、每条流的输出上限、环境变量的三层合并顺序这些能直接回仓库查到的位置，也说清后台任务这条分叉、Windows 上换成哪一套，以及两处文档与源码对不上的口径。

DeepSeek Harness 的存储层：storage 包统一了什么、又没统一什么

从一条 workspace 记录的写入出发，沿 deepseek-harness 仓库的 storage 家族走一遍代码路径，标出后端约定统一在哪一层，以及 json 与 sqlite 两个后端在配置字段、版本戳、耐久实现、错误码上各自岔开的位置，最后看装配文件里实际挂的是哪一个。

DeepSeek Harness 的子进程管理：起、管、杀这三件事分别归谁

从「命令超时了，孙进程还活着」这个具体麻烦出发，沿着 DeepSeek Harness 的 subprocess seam 走一遍源码路径，说清楚 spawn spec 为什么一个默认值都不给、terminate() 为什么是唯一的终止动词、以及超时判定为什么被刻意留在调用方手里。

DeepSeek Harness 的系统提示词是拼出来的：order 数值、可插入的位置与几处撞车

想给 dsh 插一句自己的提示词，order 该填几？本文沿着 assemble 到 renderPrompt 的调用路径，把仓库里三十处 section 注册的真实 order 数值、五个插入口、严格插值规则，以及 105、106、115、190 上的四处同序撞车逐一标出来。

DeepSeek Harness 的工具执行管线全图：从模型出参到结果回填

模型吐出一个 tool-call 块之后、会话日志里出现 tool/result 之前，DeepSeek Harness 里到底经过了几道关口。本文沿 packages/core/tools 的源码走一遍：参数冻结、pre-execute、单调守卫、审批、环绕分发、post-execute、finalizeContent，并标出 ABORTED 与 TOOL_TIMEOUT 这些错误码分别在哪一层产生。

DeepSeek Harness 的 Typert：一套自己写的远程调用是为了解决什么

从「Host 上新加一个方法、怎么让浏览器端调到它」出发，沿 DeepSeek Harness 仓库里的 Typert 代码路径走一遍：装饰器标记存在哪、InvocationDescriptor 有哪些字段、lookup 参数怎么换成 wire 字段、取消信号为什么不进 args，以及 hasSeen 这个边界。

DeepSeek Harness 的「反问用户」：ask_user_question 这条路是怎么铺的

从模型看到的 ask_user_question 参数表出发，沿着 tool-ask-user、ctx.userQuestions 和 Web 宿主 provider 走一遍，标出 ask() 的五道闸门、九个错误码的出处、plan-review 意图的认领条件，以及回答批次在宿主侧要过的逐条校验。

DeepSeek Harness 的 HTTP 服务器：dsh web 起来之后都开了哪些口

从浏览器打开本地页面这一个动作出发，沿 deepseek-harness 仓库的源码走一遍：谁在监听、监听在哪个地址、路径按什么顺序匹配、shipped Web 组合里到底注册了哪几条具名路由与 upgrade 路径，以及 fallback 席位的四条固定语义分别落在哪一行代码上。

DeepSeek Harness 的 workflow 包：它跟 Agent 自己规划有什么不一样

同样是把活拆给一堆 subagent，让模型一轮一轮委派和让模型写一段编排脚本，在 DeepSeek Harness 里走的是两条完全不同的路径。本文沿着 packages/workflow 下的四个包读一遍：脚本在哪校验、并发上限怎么算出来、取消之后谁负责收尸，以及哪些默认值只是默认值。

DeepSeek Harness 的工作区概念：workspace 划出来的那条线在哪

把 deepseek-harness 里的 workspace 注册表拆开看：它是宿主侧的一条持久记录，对模型完全不可见；会话属不属于某个工作区由「账本里有 id」加「header 的规范 cwd 相等」两个条件同时决定。沿源码走一遍成员资格、attach 拒绝路径、删除语义与两次写入的恢复标记，并标出文档与源码口径不一致的那一处。

给 DeepSeek Harness 的 Web 端加一个会话节点：前端这条链怎么接

想在 dsh 的 Web Chat 流里插一行自己的业务内容，官方 cookbook 只给了实现路径。本文顺着 Definition 注册、Assembler 装配、Chat 快照排序这条链把关键文件和写死在代码里的约束逐个标出来，包括那几条会直接抛异常的规矩。

给 DeepSeek Harness 接一个新模型：LLM 适配器怎么写

从「我要接一个自家网关」这个具体需求出发，沿 DeepSeek Harness 仓库的 packages/llm 走一遍：什么时候只改配置就够、什么时候得写适配器包、registerAdapter 会在哪几行把你的注册打回来、StreamChunk 那几条协议义务落到参考实现的哪一段代码上，以及密钥与默认值的口径。

给 DeepSeek Harness 塞一个 vendored 包：为什么要这么麻烦

从「我想再引一个上游 Cordis 插件」这个具体需求出发，沿着 deepseek-harness 仓库里 vendor/ 的复制、改 scope、注册进两处 tsconfig、过 pre-commit 守卫和 hygiene 检查的路径走一遍，标出每一步落在哪个文件的哪个字段，并列出 cookbook 与源码口径对不上的三处。

给 DeepSeek Harness 加一个 workspace 包：官方实操手册在管什么

照着 docs/cookbook/adding-a-package.md 建一个新包，很容易在 pnpm run constraints 这一步栽跟头。本文沿着 scripts/check-workspace-constraints.ts 的判断顺序，把这份手册里哪几条是脚本会真的拦你、哪几条与仓库实况对不上，逐条落到具体文件、行号与数值上。

给 DeepSeek Harness 加一个工具：官方工具编写参考逐步拆

从二十几行的最小工具出发，沿着 defineTool 与注册表的代码路径走一遍：output 为什么是必填、timeoutMs 被校验了两次、presentCall 校验失败为什么不抛异常、后台任务发布 id 之后该听谁的取消信号，以及工具目录的完整性守卫怎么防止新工具漏文档。

DeepSeek Harness 是什么：建仓三天、13 万 star 的 Agent 框架

DeepSeek Harness 自称是「一切皆插件」的 agent harness，跑在内联进仓的 Cordis 上；但截至 2026-08-16 它建仓只有三天、版本停在 0.1.0-rc.5、一个 Release 都没发。本文只依据仓库快照能核对的文件与数字，讲清它自述是什么、49 个组目录与 219 个真实包怎么切、三条运行路径各带什么前置条件，以及几处文档与磁盘对不上的地方。

DeepSeek Harness 的 219 个包版本全是 0.1.0-rc.5：发布口径怎么读

deepseek-harness 的 packages 下有 219 个真实 npm 包，截至 2026-08-16 它们的 version 全是 0.1.0-rc.5，而 GitHub 上一个 Release 都没有。本文拆开讲怎么数包、版本号统一到什么程度、哪些包不走这套口径，并给出可自行复核的统计脚本。

DeepSeek Harness 到底有多少个包：49 是数错了，真实是 219 个

在包目录下一眼数出 49 个文件夹，很多人据此写成「49 个包」。但工作区 glob 是两层的 packages/*/*，那 49 个只是组目录、自己没有 package.json，真正的 npm 包在第二层，截至 2026-08-16 共 219 个。本文给出复核脚本，以及几个容易搞混的数字。

DeepSeek Harness 的 AGENTS.md 分组清单：两个目录不存在、漏 17 个

按 2026-08-16 快照，把 DeepSeek Harness 根 AGENTS.md 的 Repository layout 清单与 packages/ 真实目录逐行比对：两个组名没有对应目录，17 个真实组没列进去，它指向的 packages/README.md 分组表少两个组。本文标出每处差异位置与复核法。

npx @deepseek-ai/dsh web 是做什么的？默认端口 3080 与 Node 版本门槛

这条命令是 DeepSeek Harness 的 README 里唯一一条不用克隆仓库的路径，跑起来会启动 Web UI，默认服务在 127.0.0.1:3080。但 README 只说「装 Node.js」，根 package.json 声明的却是 ^22.19.0 || >=24.0.0，而这条门槛不会随发布出去的包被 npm 校验到。本文把这条路和从源码构建、Python SDK 两条路的前置条件、默认值出处与已写明的限制逐条对上。

DeepSeek Harness 的 bash 工具参数：目录五个，源码再展开两个

DeepSeek Harness 仓库自带的工具目录里，bash 工具的 JSON Schema 只列了五个参数；而源码里另有两个参数是条件展开的，只在挂载的执行器带沙箱模式时才加进 schema。本文沿着生成器口径与源码分支把这处差异讲清楚，并给出自己回仓库核对的具体动作。

DeepSeek Harness 的隔离边界：仓库三处明写「这不是安全边界」

DeepSeek Harness 的 code-runtime、fs-sandbox 与 isolation 字段旁边，各有一句「不是安全边界」的原文。这篇把三处出处列出，再顺着 sandbox 的模式枚举、enforcement 取值与几条不过沙箱的执行路径，说清仓库自述的隔离词汇管到哪一层、哪些东西不在词汇表里。

DeepSeek Harness 能力接缝图：四个包名在 packages 下找不到

deepseek-harness 的 docs/capability-seams.md 里有四个包名在 packages/ 树下没有对应目录。这篇沿着这四个名字，走一遍从生成脚本到改名台账的定位路径，说清它们各自登记在哪一行、哪些名字只是组前缀差异不算失效，以及这条判定在什么情况下不成立。

DeepSeek Harness 的 llm 包测试行数多于源码：适配层怎么测住的

在 deepseek-harness 快照 47f9438 里数 packages/llm：src 46 个文件 8040 行，tests 41 个文件 12349 行。本文给出可复现的统计口径，再沿源码讲清这层被测住的结构：封闭判别联合、七条适配器契约、三张 drift gate 清单、配置解析期的点名报错。

DeepSeek Harness 插件开发与发布：dsh-plugin 话题约定与官方流程

从写完一个 DeepSeek Harness 插件到别人能装上，中间隔着 bundle 与 profile 两个概念、四层配置叠加顺序，以及一条 git 安装的构建脚本陷阱。本文逐条对照仓库里的 publish 文档与 CLI 参考，说明 `dsh-plugin` 这个 GitHub 话题到底是约定还是机制。

DeepSeek Harness 的重试与超时默认值：退避、抖动与流式空闲

DeepSeek Harness 的 LLM 重试与超时默认值只落在几处常量上：retry-policy.ts 的四个默认值加一份可重试错误码清单，超时由两个适配器各自的空闲常量控制。本文沿代码讲清退避公式、抖动系数、错误码来源、供应商 retry-after 的处置与配置该写在哪层，依据 2026-08-16 快照。

DeepSeek Harness 的 Cordis 事件派发：文档四种、源码是五种

DeepSeek Harness 的 Cordis 入门文档说事件派发模式有四种，而 tutorial、生成的 API 文档与 vendor/cordis 源码里的 DispatchMode 类型都是五种，多出来的是 bail。本文标出这四处的行号，给出自己核对的动作，并说明生成的事件矩阵里为什么看不到 bail。

DeepSeek Harness 的 Cordis scope：术语表说扁平，源码是父子链

DeepSeek Harness 的术语表把 agent scope 写成「两层、扁平、不向下继承」，而 scope 包源码的 JSDoc 写的是一条同时向下继承注册视图、向上扩展事件准入的父子链，还带环检测。本文摆出这两处原文与确切行号，并给出你自己回仓库核对的四步动作。

DeepSeek Harness 的服务注册与取用：inject 声明与 ctx 服务约定

DeepSeek Harness 的插件不靠 import 找彼此，而是把能力挂到 context 上、用 inject 声明依赖。本文照着 vendored Cordis 的源码与仓库自带的教程，走一遍服务从注册到 ctx.tools 取用的路径，说清 PENDING 是什么、依赖缺失为何不报错、诊断该看哪几个字段。

DeepSeek Harness 最小插件怎么写：apply、ctx 与插件生命周期

顺着 deepseek-harness 仓库里 Cordis tutorial 第一章的三行代码往下读，把最小插件的入口函数 apply、被传进来的 ctx 到底是什么、以及一个插件从 PENDING 到 DISPOSED 的完整状态流转讲清楚，途中标出每一处的文件与行号，方便你自己回仓库核对。

DeepSeek Harness 的 core 有几个子包：三份文档分别说 6、7、8

DeepSeek Harness 的 packages/core 有几个子包？目录里是 8 个，组 README 的表列 7 行，docs/subsystems/core.md 首句写「六个包」，架构页那张 7 行表还混进了别组的包。本文给出这几处的确切位置与包名清单，说明组目录与真实子包为什么得分开数。

DeepSeek Harness 的 Node 门槛：230 份 manifest 没一份写 engines

DeepSeek Harness 的 README 只说「装个 Node.js」，全仓写死版本范围的只有根 package.json，而根包标着 private。本文数清这 230 份 manifest，把这个门槛在 manifest、AGENTS、开发文档与 CI 矩阵四层的口径摆到一起，并给出起不来时的判定路径。

DeepSeek Harness 的文件搜索：打包 ripgrep 与 unconfined spawn

DeepSeek Harness 的 glob 与 grep 不走 ctx.fs、也不注入 sandbox，而是 spawn 随包发布的 ripgrep 二进制。本文从 tool-fs-search 的 inject 读起，说清 README 里「unconfined」指什么、这条路径上还剩哪些约束、搜索上限是多少。

DeepSeek Harness 的工具调用管线：从 pre-execute 到结果落盘

DeepSeek Harness 把一次工具调用拆成了十九个节点。本文按仓库里的流程图与源码顺序走一遍这条管线，标出审批在何处插入、guard 为什么只能降权、结果被冻结在哪一步，以及目录文档与源码在 bash 参数上的一处口径差异，供你回仓库自查。

DeepSeek Harness 支持哪些供应商：清单不在仓库，只有一份快照

想在 deepseek-harness 的源码里找出「它到底支持哪些模型供应商」，会发现这份清单压根不在仓库中——它来自一个未随仓提供的外部依赖。本文按快照 47f9438 梳理这条线索：清单从哪来、为什么读不到、仓库里唯一能直接读到的等价证据是哪个文件、那 36 个选项该怎么读，以及两处名单对不上的地方各在哪一行。

DeepSeek Harness 的 --host 0.0.0.0：笔记说已实现，代码直接报错

DeepSeek Harness 仓库里关于 dsh web 的绑定地址，Agent Note、CLI 参考与子系统文档给出了三种不同说法，其中一处标着 implemented 却与源码里的判断相反。本文逐条列出三处的文件路径与原文，说明该去哪一层找权威口径，并给出可自查的判定动作与排除条件。

DeepSeek Harness 的会话生命周期：事件、投影与持久化三层

DeepSeek Harness 把一次会话拆成三层：只增不改的事件日志、从日志派生的模型可见消息、负责落盘的持久化 seam。本文沿 turn/step 时序走一遍这三层，标出 seq 契约、44 个已知事件类型、200 毫秒写批处理窗口与崩溃恢复补边界的位置，依据 2026-08-16 的仓库快照整理。

DeepSeek Harness 中英文档怎么防漂：1078 组配对与 blob hash 校验

DeepSeek Harness 把中英双语文档的一致性做成了可机器校验的事：每对文档配一个 .i18n.yaml，记两侧的 git blob hash。本文沿仓库里的 i18n 契约文档与校验脚本走一遍：它记的是什么、为什么用 blob hash 而不用 commit hash、这个 gate 又承认管不到什么。

DeepSeek Harness 的模型接入分层：adapter、provider 与手写路由

顺着 DeepSeek Harness 仓库里 packages/llm 的源码走一遍模型接入层：ctx.llm 只管注册表与类型词汇，适配器只被要求实现一个 stream 方法，provider route 才是主键；再看目录路由与手写路由在协议、模型发现、模态声明上的分界线，以及凭据为什么不在这一层。

DeepSeek Harness 的工具审批：没找到默认发起 ask 的策略插件

DeepSeek Harness 的工具管线里有 ask 决策、有审批服务、有四值封闭词表，但顺着源码找一圈，非测试代码里注册 tools/pre-execute 的七个文件中没有一个是通用询问插件。这篇记录查找动作、可复现的判定命令，以及仓库里 ask 的两个已知来源，供你回仓核对。

DeepSeek Harness 的权限预设命名：README 与源码三处都不一样

DeepSeek Harness 的权限预设包里，事件名、斜杠命令名、settings 命名空间这三处，包 README 写的是 permissionPresets，而源码写的是 permission。本文逐处标出两边的文件与行号，给出可自己复核的检索动作，并说明为什么这三个名字值得逐个回源码核对。

DeepSeek Harness 为什么要七份 vitest 配置：测试分层怎么切的

DeepSeek Harness 仓库根目录躺着七个 vitest 文件与五个 tsconfig 文件。本文按快照 47f9438 逐个读它们的文件头注释、行数与关键常量，讲清这套分层是按「每条 lane 花什么代价」切开的，以及 npm scripts、CI gate 与 Windows 侧各自能核到哪一步。

DeepSeek Harness 的权限预设有几档：源码两档、出厂组合三档

DeepSeek Harness 的权限预设有两份表：permission-presets 包的 Config 默认值是两档，出厂组合 cordis.patch.yml 里配的是三档。本文对齐两处的确切位置与字面值，说明 custom 为何不算一档、构造期哪两种配法会抛错，以及你自己怎么在仓库里核一遍。

DeepSeek Harness 的 Agent 轮次上限：包默认 256、出厂组合配 64

DeepSeek Harness 的 tool-ralph 在包源码里把 maxRounds 默认值写成 256，出厂组合的 cordis.patch.yml 里却配着 64。本文以此为线索，沿仓库文档记录的四层配置层叠顺序，说明一个默认值可能出现在几层、整行替换而非深合并意味着什么，以及看最终生效值该做哪个动作。

DeepSeek Harness 的代码执行残留：terminate 只结束线程

DeepSeek Harness 的 run_code 在 Node worker 线程里跑模型写的 TypeScript，computeMs 与 maxWallMs 到期都收敛到 worker.terminate()，而它只结束线程。本文回到源码标出这条限制的出处、它与 bash 路径进程组终止的差异，以及怎么判定。

DeepSeek Harness 手写路由支持的三种线协议分别是什么

DeepSeek Harness 的 pi-ai 适配器里，手写 provider 的 api 字段只有三个合法取值。本文回到 provider.ts 的 PROTOCOLS 表，讲清这三个名字各自对应什么、顺序为何不随意、为什么 Bedrock 这类不在表里，以及它与模型发现、目录路由的关系。

DeepSeek Harness 的定时调度：文档写 cron，协议与源码里没有

DeepSeek Harness 的 extension-cookbook 机制表把定时任务一行写成 cron 语义，而 schedule 子系统文档与包 README 都写明协议里没有 Cron 表达式。本文标出这三处文件的具体位置，说明 schedule 协议实际支持哪三种规则，以及怎么自己动手核对。

DeepSeek Harness 的沙箱默认策略：schema 只读、示例可写工作区

DeepSeek Harness 的 sandbox-policy 在 schema 里把 mode 默认成 read-only，而 acp-agent 示例组合把同一字段设成 workspace-write 或 danger-full-access。本文标出两处位置，说清取值牵动哪些代码路径，以及如何核对生效值。

DeepSeek Harness 的审批顺序：为什么排在 monotonic guards 之前

DeepSeek Harness 的工具执行管线把用户审批排在 monotonic guards 之前。本文按仓库里生成的流程图分支边、子系统文档的 guard 类型定义与注册表源码行序读一遍这段顺序：人点过同意后为何还要再过一遍 guard，审批的四个取值各落到哪条分支，发起询问的来源只核到哪两处。

DeepSeek Harness 里四个都叫 version 的数字：0、15、8、1

DeepSeek Harness 仓库里有四个含义完全不同的版本号：会话格式 0、会话持久化 SQLite 15、会话查询 SQLite 8、通用 storage SQLite 1。本文按 2026-08-16 的仓库快照标出它们各自的常量名、所在文件与版本化的对象，并给出一套区分四条线的排查动作。

DeepSeek Harness 的 skill 是什么格式、怎么被装载

从 DeepSeek Harness 的 packages/skill/ 源码出发，讲清一个 skill 文件长什么样：目录 bundle 与扁平 Markdown 两种形态、frontmatter 必填项与两个 kebab-case 开关、六个发现根及其 rank 数值，附一份 skill 没被认到时的排查顺序。

DeepSeek Harness 的 spill：上下文放不下时溢出到哪、边界在哪

工具吐出几十万字节输出时，DeepSeek Harness 会把它写到磁盘、会话里只留头尾预览加一行引用。本文沿着 packages/spill 下三个包的源码，讲清 spill 的唯一开关 maxInlineBytes 从哪来、触发为何是严格大于、预览预算怎么被通知行先扣一刀，以及这条 seam 明确不做的事。

DeepSeek Harness 的六个 subagent provider：只有两个能续接

DeepSeek Harness 有六个子代理 provider，按 2026-08-16 快照读源码，只有 spawn 与 fork 两个带 prepareContinuable。本文讲清两套并存的能力发现机制、可续接背后的 Session 与 Activation 结构，以及出厂组合实际配了哪几行。

DeepSeek Harness 的 terminal 工具：README 说 pty，代码是 terminals

DeepSeek Harness 的 terminal-bash 插件，README 第 9 行写它注入 pty、sandboxPolicy、subprocess，src/index.ts 第 25 行的 inject 首项却是 terminals。并列两处原文，给出可自己核对的检索动作，并列出同仓其它几处同类差异。

DeepSeek Harness 的 token 计量：文档两种 baseline，源码三元联合

DeepSeek Harness 的 token-meter 文档页只讲了 usage 与 estimated 两种 baseline，而源码里 TokenMeasurementBaseline 是三元联合，多一个 kind 为 none 的分支。本文把差异落到文件与行号，说清它何时产生、谁在读它，以及怎么自己核对。

DeepSeek Harness 注册了几个工具：README 五个、源码七个

DeepSeek Harness 的 tool-cordis 包，README 与源码有四处对不上：工具数五还是七、cordis_inspect 在源码里搜不到、服务键 ctx.dynamic 还是 dynamicCordisRunner、只在 README 出现的 ackTimeoutMs。本文逐条给出位置与行号。

DeepSeek Harness 里的 TurnTrigger：文档还留着，packages 里搜不到

在 deepseek-harness 快照里查 TurnTrigger 这个类型名：三处子系统文档和两个生成脚本的映射表里都还写着它，而 packages 目录下所有 TypeScript 文件里一次都搜不到。本文给出可复现的检索动作、它现在还出现在哪几行、以及同一仓库里另外几处同类落差的核对方法。

DeepSeek Harness 的 vendor 九个包：版本号与实读全对不上

DeepSeek Harness 把 Cordis 全家桶源码放进 vendor/，并在 vendor/README.md 维护了一张九行 manifest 表。本文逐个打开这九个 package.json，记录表中版本号与实读 version 的九行差异、两处文档写到却缺席的 private 字段，并给出自查脚本。

DeepSeek Harness 的压缩事件有几个：文档三种、源码四个

DeepSeek Harness 压缩子系统文档写着 three event types 且只列三行表格，源码 types.ts 的 declare module 块却声明了四个，多的是 compaction/prune。本文标出两处口径的文件与行号，说明该事件在注释里的影子定价用途，并给出回仓库自己核对的动作。

DeepSeek Harness 的「一切皆插件」：Cordis 到底承担了什么

「一切皆插件」是 DeepSeek Harness 的 GitHub 简介原文。本文回到 2026-08-16 的仓库快照，看这句话在 README、AGENTS.md 与架构文档里怎么写，vendored 进来的 Cordis 内核有多大，packages 下的包为什么全都依赖它，以及这套范式带来的三种静默失败。

Qwen3.8-27B 是什么：一个模型仓里有哪些文件、各自负责什么

Qwen3.8-27B 的 Hugging Face 仓库不是代码工程，而是权重仓：18 个 safetensors 分片加十来个配套文件。本文按文件说清各自负责什么，把 model card 的说法与 config.json、chat_template.jinja 的字面值逐条对照，并记下几处名字对不上的位置。

Qwen3.8-27B 的权重怎么组织：18 个分片、索引文件与 crc32

以 2026-08-16 的仓库快照为准，列出 Qwen3.8-27B 在 Hugging Face 上的文件构成：18 个 safetensors 分片、分片索引、校验清单与各配置文件。同时说清边界——我们只取到 8 个文本文件，分片与索引没有读过，这篇讲的是清单与可核对处，不是权重内部。

Qwen3.8-27B 的上下文长度：256K、262144 还是 1M，四处口径

Qwen3.8-27B 的 model card 把上下文长度写成了四个数：评测脚注 256K、配置 262144、自述可扩到 1,000,000、托管版本默认 1M。本文逐行对回 config.json 与 tokenizer_config.json，说清哪个是开箱值、哪个得自己改配置、哪个还没上线。

Qwen3.8-27B 的 64 层怎么排：全注意力恰好 16 个，下标全是 4k+3

Qwen3.8-27B 的 model card 用一行公式描述了 64 层的排布，而随仓配置文件里真正落到磁盘上的，是一个六十四元素的字符串数组。这篇把数组逐项打印出来数一遍，给出十六个全注意力层的下标与等间距规律，核对它与间隔字段的数值是否自洽，并指出那行公式里有哪两样东西是这个数组根本核不出来的。

Qwen3.8-27B 的许可实读：Apache-2.0 标准文本与那行版权

Qwen3.8-27B 的仓库把协议标成 apache-2.0，但元数据标注与 LICENSE 正文是两回事。本文把该仓库根目录的 LICENSE 当成文本文件读一遍：多少字节多少行、版权行填的是谁、结构是否为 Apache 2.0 标准正文，并用一段可复现的关键词检索确认有没有夹带模型专属的附加使用条款。

Qwen3.8-27B 的文本调用示例逐行读：哪些参数是官方写的

逐行拆开 Qwen3.8-27B model card 的纯文本 Chat Completions 示例：每个参数出自 README 哪一行、哪些带官方 on by default 注释、哪些 README 未作说明，以及示例写入的 reasoning 字段与 chat_template.jinja 读取条件的差异。

Qwen3.8-27B 的 Benchmark 加粗口径：VL 表没说明却粗了 18 处

Qwen3.8-27B 的 model card 并排放着 Text 与 VL 两张 Benchmark 表，结构对称、脚注各八条，但「每行最高值加粗」这句读表说明只写在表一脚注里，表二没有对应说明却用了 18 处加粗。本文给出两张表的确切行号、加粗与破折号的计数口径，以及三处读表陷阱，只陈述差异，不推断原因。

Qwen3.8-27B 的 Benchmark 原表照搬：两张表 25 行与确切出处

把 Qwen3.8-27B model card 的 Text Performance 与 VL Performance 两张表原样转写下来，一格不改、一位小数不动，给出每一行在 README.md 里的确切行号、16 条脚注原文、25 个评测行与 23 个 `--` 的统计口径，并说明这张表能怎么引、不能怎么引。

Qwen3.8-27B 官方推荐的采样参数，配置文件里一个都找不到

Qwen3.8-27B 的 model card 在 Best Practices 里按模式给了两组共六个采样参数，但把权重仓随附的配置文件逐个翻一遍会发现，只有三个真的写进了文件，另外三个连一次命中都没有。本文按文件列出这条落差分布在哪几层、每一层的原文与行号是什么，以及可以用哪条命令自己核一遍。

Qwen3.8-27B 的 chat_template 逐段拆：四类消息分别怎么渲染

Qwen3.8-27B 权重仓的 chat_template.jinja 共 170 行，决定 system、user、assistant、tool 四类消息各被拼成什么文本。本文按行号逐段拆这四条分支，标出思考块、工具调用格式与生成提示的位置，并记录模板与 model card 几处口径不同之处。

Qwen3.8-27B 评测表里的 CI 是什么：model card 全文从未展开

Qwen3.8-27B 的 model card 在 VL Performance 表里把三行分数拆成 Without CI 与 With CI 两种口径报出，但整份 README 没有一处解释 CI 是什么。本文给出这三行的行号与原表数值、一条可复现的全文检索命令、脚注说了什么，以及遇到未展开的缩写该怎么引用。

Qwen3.8-27B 的词表 248,320 与特殊 token：padded 是什么意思

Qwen3.8-27B 的 model card 把词表写成 248,320 (Padded)，config.json 里却只有一个 vocab_size。本文核对这个数字的三处出处、33 个新增 token 的连续 id 区间，以及 bos、eos、pad 在三份配置文件里对不上的地方。

Qwen3.8-27B 的 Citation：bibtex 标题写的是另一个型号

Qwen3.8-27B 的 model card 末尾有一段可直接复制的 bibtex，其 title 写的是 Qwen3.8-Max，与一级标题和 Hugging Face 仓库 ID 上的 27B 不是同一个名字。本文把两处原文摆出来并标明位置，再并列仓库里其它几处世代名对不上的地方，给出你自己动手核对的办法。

Qwen3.8-27B 评测表的对比列：有一列在多数行上是空的

Qwen3.8-27B 的 model card 里那两张 Benchmark 表看着是五列并排，但逐格数下来，五列填了多少格差别很大：有一列在 VL 表的 13 行里只有 3 行有数值，其余全是 --。这篇把每一列的「有值 / --」计数逐列摆出来，说明 -- 的官方释义，并给出引用这两张表之前必须做的核对动作。

Qwen3.8-27B 的 eos / bos / pad：三个配置文件里是三套值

Qwen3.8-27B 权重仓里，eos、bos、pad 这三个 token 在 config.json、generation_config.json、tokenizer_config.json 里的字段名与取值各不相同。本文把三处并列摆出来，标明文件与行号，并给出可以自己复核的 Python 命令。

Qwen3.8-27B 的视频 fps：README 说默认 2，配置里没有这个键

Qwen3.8-27B 的 model card 在视频输入示例的注释里写着默认 fps=2、do_sample_frames=True，但随仓的两个预处理配置与 config.json 里都检索不到这两个键。本文给出可复现的核对命令、两个预处理配置的完整字段表，以及这条差异说到哪里必须停。

Qwen3.8-27B 的 GQA：24 个 Q 头配 4 个 KV 头、head_dim 是 256

把 Qwen3.8-27B 的「24 个 Q 头、4 个 KV 头、head_dim 256」逐个落回 config.json 的字段与行号：这一组只作用于 64 层里的 16 个 full_attention 层，model card 写的 RoPE 维度 64 在配置里并没有对应字段，以及哪些语义在本仓核不出来。

Qwen3.8-27B 的工具调用协议只写在模板里，README 全文 0 提及

Qwen3.8-27B 的 model card 里搜不到 tool_call 这个词，而随仓的 chat_template.jinja 从第 57 行起定义了工具清单注入、函数调用格式与工具返回的渲染方式。本文按 2026-08-16 的仓库快照记录这套协议写在哪几行、长什么样，以及哪些东西模板里有、文档里没有。

Qwen3.8-27B 的 Hidden Layout 公式怎么跟 layer_types 对上

Qwen3.8-27B 的 model card 用一行公式概括 64 层排布，随仓 config.json 里则是一个 64 元素的 layer_types 数组。本文把公式拆成块数、比例、顺序三个可核对的断言逐条对到数组上，并说清两处核不动的边界：FFN 在数组里没有对应元素，那两个名词在配置文件里一次都没出现。

Qwen3.8-27B 的混合注意力：由 config 里哪几个字段承载

Qwen3.8-27B 的 model card 用一行公式描述层的排布，配置里承载这套结构的却是另一批字段。本文按 2026-08-16 的仓库快照，列出 layer_types、full_attention_interval 与两组头维度字段各在哪一行、值是多少，并把公式与数组排布逐项对上，标明哪几处核不出来。

Qwen3.8-27B 的评测表里，有一行两列同时被加粗

Qwen3.8-27B 的 model card 里，VL Performance 表的 ClawEval-MM 一行，Pass@3 的 57.4 在两列同时带加粗；而「每行最高值加粗」这句说明只写在 Text Performance 表的脚注里。本文只陈述差异，给出可回原文核对的行号与口径，并说明引用这张表时的规矩。

Qwen3.8-27B 的 config.json 里全是 qwen3_5：代际关系怎么读

model card 标题是 Qwen3.8-27B，随仓 config.json 的 architectures 却写着 Qwen3_5ForConditionalGeneration，顶层与两个子配置的 model_type 也都是 qwen3_5。本文按行号摊开这些字面值，并核对参数表与配置的对应关系。

Qwen3.8-27B 的 MTP：自述多步训练，配置里只有一层

Qwen3.8-27B 的 model card 参数表里，MTP 那行只写「trained with multiple steps」，没有数字；而随仓 config.json 的 mtp_num_hidden_layers 是 1。本文并排摆出两处原文与行号，说明训练步数与配置层数为何不能互相换算，核对该停在哪一步。

Qwen3.8-27B 的 preserve_thinking 控制什么、在哪一层生效

Qwen3.8-27B 权重仓里 preserve_thinking 不在采样配置中，唯一实现处是 chat template 的一行 Jinja 条件。本文按 2026-08-16 快照拆开这行条件、它依赖的 last_query_index，以及 README 与模板的措辞差异和两套参数传法。

Qwen3.8-27B 的 reasoning_effort 三档：模板里只有两档有分支

Qwen3.8-27B 的 model card 把 reasoning_effort 写成 xhigh、medium、low 三档，而随仓 chat_template.jinja 只有 xhigh 与 low 两档会注入提示词。本文逐行读模板 45-56 行，说清两处各写了什么、怎么核对、这个参数在本仓的唯一落点。

Qwen3.8-27B 的 RoPE 维度 64：config.json 里找不到对应字段

Qwen3.8-27B 的 model card 写着 RoPE 维度为 64，config.json 里却没有承载它的字段。本文按 2026-08-16 快照核对 rope_parameters 的五个键与 head_dim、partial_rotary_factor 的关系，说明在配置里搜 64 为何先撞上层数。

Qwen3.8-27B 怎么部署：Serving 那一节一条启动命令都没有

Qwen3.8-27B 的 model card 里有个「Serving Qwen3.8」小节，多数人会直接去那里找启动命令。截至 2026-08-16 的快照，这一节只有一个提示块、一句话和三条框架外链，没有一条可执行命令。本文逐行核对它写了什么、真正的 serve 命令在哪一节、为什么那三条也不能直接复制运行。

Qwen3.8-27B 的视觉塔 27 层：patch 16 与那个空的 deepstack 数组

Qwen3.8-27B 的 model card 没给过一个视觉编码器参数，视觉侧数字只在 config.json 的 vision_config 这十四个键里。本文逐键抄出，与两个 preprocessor 配置交叉核对，并照实记录那个存在但为空的 deepstack_visual_indexes。

Qwen3.8-27B 的视频输入怎么传：那段被整体注释掉的抽帧示例

逐行拆开 Qwen3.8-27B model card 里 Video Input 这段示例：会执行的请求只有 video_url 加一句提问，讲抽帧的十三行以井号开头处于注释状态；并把 fps、do_sample_frames、num_frames 在 README 里说了什么、在随仓配置文件里查不查得到逐条对照。

Qwen3.8-27B 的 thinking 默认开着：怎么按请求关掉

Qwen3.8-27B 的思考模式默认开启，关掉它靠的不是模型内部开关，而是 chat template 里的一个变量。本文沿 chat_template.jinja 的分支条件走一遍：enable_thinking 为 false 时哪段推理档位提示词不再注入、生成提示预填的字符串换成什么，以及两处判定写法的差异。

Qwen3.8-27B 的图像输入怎么传：示例字段与预处理配置的对应

把一张图片喂给 Qwen3.8-27B，要同时对上三层字面：请求体的字段名、chat_template.jinja 的分支判定、preprocessor_config.json 的参数。本文按快照 1d4bf0f 逐层照抄原文并标出行号，记录图像与视频判定条件不对称等文本差异，不做推断。

Qwen3.8-27B 的 vllm serve 启动命令：藏在 YaRN 那一段里

Qwen3.8-27B 的 model card 里名为 Serving 的小节没有启动命令，只有三条框架文档外链；全文唯一的 vllm serve 在 Best Practices 的超长文本条目下且带省略号。本文按行号还原这处结构，并列出 README 建议值与仓库 config.json 实际值对不上的几处。

Qwen3.8-27B 的线性注意力参数：卷积核宽度与 key/value 头数

Qwen3.8-27B 的 config.json 里有六行以 linear_ 和 mamba_ 开头的字段挤在一起，model card 的参数表只覆盖其中三个数字。本文照录这六行的取值与行号，与 Gated DeltaNet 那两行、全注意力那组头数字段逐项对照，说清哪些对得上、哪些没有对应表述。

Qwen3.8-27B 的 YaRN 长上下文：三处配置对不上

Qwen3.8-27B 的 model card 让你把 rope_parameters 的 rope_type 改成 yarn，而发布的 config.json 里这个值是 default，README 建议的另两个键在发布配置里不存在，示例 JSON 末尾还多一个逗号。本文逐键摆出这三处文本差异，并给出核对动作。

Qwen3.8-27B 的两份 preprocessor 配置：尺寸上限与归一化参数

Qwen3.8-27B 权重仓里管图像与视频预处理的只有两个 21 行的小文件。本文逐字段列全它们的键与值，指出两者仅有三处不同、四处完全一致，交叉核对 config.json 里 vision_config 的同名字段，并照实记录 README 建议值与仓库发布值对不上的几处差异与自查方法。

WorkBuddy 的文件都存在哪？五个官方路径一次说清，重装前先看这篇

WorkBuddy 的程序、工作空间、账号配置、日志分别在不同目录，搞混了会导致更新时误删文件或找不到历史记录。本文汇总官方文档给出的全部路径，说明哪个目录更新时会被清空、哪些文件夹必须保留，以及重装前该先移走什么。

WorkBuddy 装不上怎么办？官方 FAQ 只覆盖两种情况，其余按这个清单自查

WorkBuddy 安装包双击没反应、装到一半中断、装完找不到程序，官方常见问题页只写了 ARM64 与更新目录两条相关说明。本文如实标出官方覆盖范围，并给出系统要求、安装包架构、安全软件、磁盘空间四项自查清单与提工单该带的信息。

WorkBuddy 支持 ARM64 的 Windows 吗？两处官方说法不一致，先这样判断

WorkBuddy 产品页把 Windows 安装包标注为「x64（兼容 ARM64）」，官方常见问题页却有一条「当前版本暂不支持 ARM 64 架构的 Windows 11」。两处口径不同，本文并列陈述并给出装之前怎么确认自己的设备架构、装不上时该怎么办。

WorkBuddy 机器人时好时坏、老是掉线？官方对这类给的第一招还是切模型

接入完成后机器人偶发断开、首次可用之后再打开就失联，官方给的做法是先确认连接状态是否在线、优先切换模型再测试、微信场景可断开重连、并记录复现时间与平台类型。本文按这四步展开并补上最容易被忽略的前提。

WorkBuddy 的补偿积分要手动领，不领不到账

官方说明补偿积分需要在个人主页用量管理里手动领取，不领不会自动到账——很多人以为积分没给，其实是躺在那儿没点。本文给出领取路径、用量管理这一个页面能办的三件事，以及积分对不上时该走哪条渠道。

用 WorkBuddy 做采购比价：做出一张口径统一的对比表，但别让它推荐供应商

采购比价最花时间的不是比，是把各家格式不一的报价拉齐到同一个口径。本文给出比价表的指令模板、询价要素清单，以及采购场景独有的一条红线——不做供应商推荐。

WorkBuddy 接入选长连接还是 URL 回调？没有公网 IP 就别犹豫

企业微信、钉钉、飞书三个平台都提供长连接与 URL 回调两种接入方式，官方对适用人群写得很清楚。本文横向对比两种模式各自要填什么凭证、要不要回填地址、会踩到哪些独有的坑，以及为什么长连接能规避掉一整类问题。

WorkBuddy 和 CodeBuddy 共用一份积分，两边混用该怎么规划额度

官方明确同一账号积分共享，这意味着你在编程侧消耗的积分会让办公侧可用的变少。本文讲清积分的扣减顺序、有效期规则、加量包的买法，以及两边混用时怎么把额度算清楚。

买了 WorkBuddy 会员能用 CodeBuddy 吗？官方原话是同一账号积分共享

官方定价文档开头第一句就写明「CodeBuddy 和 WorkBuddy 同一账号积分共享，无需分别订阅」。本文给出这句原话的完整含义、共用套餐表里哪些行属于哪个产品、以及 2026 年 7 月起的订阅升级与老用户过渡方案。

WorkBuddy 处理大文件老失败？官方给的思路是拆，不是等

几十兆的表格、上百页的文档交给它，经常跑很久然后失败。官方对这类问题给的做法是减少一次性过长过大的复合任务、拆分成多个独立任务、必要时切换模型。本文给出按文件类型的拆分策略和一套可复制的分步指令。

钉钉接 WorkBuddy 的四个凭证在哪拿？两个页面，别只拿了一半

Client ID 和 Client Secret 在「凭证与基础信息」页，AES Key 和 Token 要去「开发配置-事件订阅」选 HTTP 推送后刷新生成。本文给出四个凭证的确切位置、三个必开权限的准确名称、以及两种连接模式各自要填什么。

WorkBuddy 钉钉机器人配好了却不响应？多半是应用没发布，官方这一步很容易跳过

钉钉接入 WorkBuddy 时，凭证填对、注册显示已连接，群里却搜不到机器人或它不回消息——官方文档写明「应用必须发布后才能在钉钉中使用」。本文讲清发布这一步怎么做、跳过它会出现哪些症状，以及归属组织和 HTTPS 这两个连带的坑。

WorkBuddy 的定时任务没按时跑？先查电脑那时候醒着没有

自动任务到点没执行，最常见的原因不在配置里——官方明写使用助理时电脑需要保持开机并运行客户端，而自动任务同样跑在你的机器上。本文给出四步排查顺序、历史执行记录该怎么看，以及怎么让定时任务更可靠。

WorkBuddy 的自动任务和 CodeBuddy CLI 的定时任务不是一回事

WorkBuddy 的自动化是持久配置、按档位限数量；CodeBuddy CLI 的定时任务是会话级的，退出即清除、3 天自动过期、每会话最多 50 个。两者机制差别很大，本文并列双方官方文档写明的规则。

Discord 接 WorkBuddy 不开 Message Content Intent 就收不到消息

Discord 接入要开三个 Privileged Gateway Intents，其中 Message Content Intent 不开的话 bot 在线但不回复。本文给出完整五步、Bot Token 只显示一次这条硬规则、邀请链接的权限怎么勾，以及权限勾错了怎么补救。

WorkBuddy 能几个人共用一个吗？先搞清楚它连的是谁的电脑

把机器人拉进群，就等于把自己那台电脑的操作权交给了群里所有人。本文讲清个人版与企业版在多人场景下的能力差异、企业微信的可见范围与企业版的管控层、以及真要多人用该怎么划边界。

WorkBuddy 改了好几轮还是不对？官方给了停止信号和一个更快的做法

反复迭代最常见的问题不是改不好，是陷进去出不来——修好一处坏掉另一处。官方明确给了停止信号：会话过长出现前说后忘、越聊越跑偏时不要硬撑。本文给出四轮迭代法与换会话的正确姿势。

WorkBuddy 发票怎么开？个人版和企业版两条路，苹果支付要找苹果

WorkBuddy 的发票不在客户端里开，个人版走官网个人主页转腾讯云控制台，企业版走企业管理后台。本文给出两条官方路径的完整步骤、腾讯云实名这个前置条件、苹果支付渠道的例外，以及企业开票要用哪个账号登录。

飞书接 WorkBuddy 要四个凭证，分别在两个页面拿

App ID、App Secret、Encrypt Key、Verification Token——飞书接入需要四个凭证，分散在「凭证与基础信息」和「事件与回调」两个页面。本文给出各自位置、填进 WorkBuddy 的哪些框、事件回调怎么配，以及发布这一步为什么不能漏。

飞书接 WorkBuddy 要开多少权限？官方给的是一段 JSON 批量导入

飞书这条接入路径的权限不是一条条勾的，官方直接给了一段 JSON 让你批量导入，涵盖消息、文档、表格、日历、任务、知识库等一百多条。本文讲清导入步骤、这些权限各自对应什么能力，以及企业推行前该怎么向管理员解释。

飞书配 WorkBuddy 提示「无法检查链接」？官方说别重复填同一个地址

飞书配置 Webhook 时提示无法检查链接，官方说明这可能出现在重复输入同一地址之后，做法是重新创建或重新填写一次配置、避免重复输入同一地址。本文讲清怎么执行、为什么它跟企业微信那条方向相反，以及飞书接入的权限前提。

WorkBuddy 更新失败提示「安装目录下存在用户项目目录」？官方给了完整处理步骤

更新 WorkBuddy 时提示检测到应用安装目录下存在用户项目目录，是因为更新会清空安装目录重写文件。官方给出了安装目录位置、该保留哪四个文件夹、个人文件怎么先移走，本文按步骤拆解，并说明为什么工作目录不该建在安装目录里。

WorkBuddy 的工作空间该怎么划？官方给了四个命名示例，照抄就行

工作空间是当前任务读写文件的那个文件夹，也是权限判断和文件系统隔离的边界。官方建议每类任务建独立文件夹并给了四个命名示例。本文讲清怎么规划、三个不该选的位置，以及为什么划得越小确认框越少。

WorkBuddy 工作文件夹拖进去没反应？这条官方文档明说了没有修复方案

拖拽文件夹到 WorkBuddy 里导入无效，官方常见问题页承认这个现象，但明确写了当前文档未提供明确修复方案，只给了记录信息后提交排查的路径。本文如实说明这一点，并给出三条不依赖拖拽的替代做法。

WorkBuddy 怎么接 Google 日历和云盘？官方实践里有一条建议值得抄

官方给了 Google Calendar 与 Google Drive 的实践案例——连接授权、用自然语言描述目标、确认结果。其中「授权时只授予完成任务所需的权限」和「在任务描述中明确时间范围」两条建议对所有连接器都适用。本文拆解完整流程与四条使用建议。

WorkBuddy 国内站和国际站是一个账号吗？两套定价体系，别用汇率换算

codebuddy.cn 与 workbuddy.ai 共享同一份文档，但定价是两套互不通约的体系：国内四档人民币、国际三档美元，档数档名积分数全不同。本文并列两套体系的官方事实，说明发票、企业版、私有化部署各自走哪条路，以及为什么不能做档位对应。

鸿蒙手机扫码连不上 WorkBuddy 微信助理？官方说鸿蒙 6 存在不兼容

官方常见问题页明确记录鸿蒙 6 的微信扫码当前存在不兼容情况，已知鸿蒙 4 可以正常连接，并给了一个临时方案——先用安卓手机完成首次扫码，再切回鸿蒙微信继续使用。本文拆解这个方案怎么执行与它的边界。

WorkBuddy 会拿我的资料去训练模型吗？「帮助优化模型」默认开启，关掉只管新对话

WorkBuddy 官方英文隐私文档写明「Help Improve WorkBuddy（帮助优化模型）」默认是开启状态，你的对话可能被用于训练模型；关闭后只对新对话生效。本文给出桌面端与手机端的关闭路径、记忆与本地记忆两个开关的区别，以及企业环境下该找谁。

WorkBuddy 交出来的东西怎么验收？五步检查，第一步最容易跳过

拿到结果之后大多数人只看「读起来顺不顺」，但真正该查的是数据对不对、有没有编的内容、红线有没有越。本文给出一套通用的五步验收法，以及怎么在指令里预先埋下可验收的锚点。

WorkBuddy 九个平台接入哪个最省事？按要不要开发凭证分成三档

微信助理只要扫码不用任何凭证，企微钉钉飞书要去开发者后台申请凭证，QQ 还要实名。本文按「配置成本」把官方支持的九个平台排成三档，列出各自要准备什么、卡在哪一步，帮你在动手之前选对平台。

配 WorkBuddy 接入之前，先按这张清单准备一遍

九个平台的接入前提各不相同——有的要企业管理员权限，有的要实名认证，有的只要版本号够。本文按平台整理出动手前该确认的账号、权限、凭证与版本，以及所有平台共同的三条前提，省掉配到一半发现没权限的返工。

WorkBuddy 积分掉得太快或者没到账？官方给的是查明细加发邮箱

积分未到账或消耗异常，官方给的做法是先在个人主页用量管理查询余额和用量明细，确认异常后把截图发送至官方支持邮箱。本文讲清怎么自查、哪些消耗其实是正常的、限免角标怎么影响你的判断，以及上报要带什么。

WorkBuddy 能把你在别的 AI 上的使用习惯导进来，还能直接编辑记忆

官方记忆功能支持从其他 AI 产品导入使用习惯——复制官方给的示例提示词到别的 AI 里，把结果粘回来即可。记忆摘要每晚重新生成，点开可以查看和编辑，也能用对话告诉它记住或忘记什么。本文讲清这三件事怎么用。

WorkBuddy 的对话记忆怎么关、怎么删？两个开关的区别先搞清楚

WorkBuddy 有生成对话记忆和本地记忆两个开关，管的不是同一件事，而且本地记忆仅在云端模式下可用。本文给出桌面端与手机端的设置路径、怎么查看和管理已经生成的记忆、以及关记忆和关模型训练是两回事。

WorkBuddy 的记忆和 CodeBuddy 的 Memory 是一回事吗？两边文档是独立的

两个产品都有叫「记忆」的能力，但官方给的是两套独立文档。WorkBuddy 侧强调偏好与习惯、摘要每晚重生成、可从其他 AI 导入；CodeBuddy 侧有自己的 Memory 文档体系。本文并列双方官方表述，说明为什么不该把它们画等号。

WorkBuddy 记住了你什么？点开记忆卡片就能看，还能直接改

记忆摘要每晚重新生成，点击已生成的记忆可以查看和编辑，也能通过对话告诉它记住或忘记什么。多数人从没看过自己被记住了什么。本文给出查看路径、该重点检查哪五类内容，以及一套可执行的清理节奏。

开源自托管还是商业订阅？按四个问题判断你该选哪种形态

WorkBuddy 是商业闭源桌面产品，OpenClaw 是 MIT 开源的自托管网关。本文不比谁更好，而是把两种形态在数据、成本、运维、支持四个维度上的官方事实并列出来，帮你按自己的约束条件判断。

用 WorkBuddy 整理客服工单：做出一张能开会用的分类统计表

客服工单整理最有价值的产出不是「总结一下」，而是一张按问题类型分好、条数对得上、能追回原文的统计表。本文给出指令模板、验收要点，以及客服场景独有的一条红线——不代客户做承诺。

跨境电商用 WorkBuddy 做多语言素材：合规判断必须留给人

官方场景包提到跨语言素材改编。跨境电商做多语言内容时，最大的风险不是翻译质量，是不同市场的合规规则完全不同。本文给出素材改编的指令模板与合规标注法。

WorkBuddy 的连接器目前有哪五个？QQ 邮箱、乐享、腾讯文档、TAPD、微云

连接器是官方封装好的外部服务对接入口，目前支持 QQ 邮箱、腾讯乐享、腾讯文档、TAPD 和微云五个，另可配置自定义连接器。本文列出各自能做什么、授权流程、怎么断开与撤销，以及连接器和 MCP 该怎么选。

WorkBuddy 的历史会话找不到了？官方说别把「助理」当工作空间

助理工作空间里只有最近产生对话的任务会在「助理」中展示，其他任务只在工作空间列表里能看到——这是历史会话找不到的常见原因。官方明确建议电脑端新建任务时不要把助理作为工作空间。本文给出两种找回路径与正确的工作空间用法。

Mac 装 WorkBuddy 要注意什么？两个 dmg 别下错，加上一条容易漏的目录权限

WorkBuddy 的 macOS 版分 Intel 与 Apple 芯片两个安装包，系统要求 macOS 12.0 以上。本文讲清怎么确认自己该下哪个、安装后程序与数据分别在哪三个目录、登录卡住时官方给的 Mac 侧权限检查与授权命令，以及日志怎么取。

WorkBuddy 的 MCP 配置分用户级和项目级，配置文件路径不一样

MCP 有两个配置级别——用户级放在 ~/.workbuddy/mcp.json 所有项目复用，项目级放在项目目录下的 .workbuddy/mcp.json 只对当前项目生效。本文讲清两级怎么选、官方给的最佳实践、以及配置文件的位置意味着什么。

WorkBuddy 的 MCP 显示红灯怎么办？官方给了三个排查方向

MCP Server 状态红灯表示配置异常，官方指出要检查配置内容、命令环境或地址三个方向，并强调配置失败时优先确认 JSON 的括号引号是否完整。本文把三个方向拆成可执行的自查顺序。

WorkBuddy 的 MCP 和 CodeBuddy 的 MCP 配置方式一样吗？路径和入口都不同

两边都支持 MCP，但配置入口、配置文件路径、分级方式各不相同。WorkBuddy 走侧边栏插件里的可视化配置，用户级路径是 ~/.workbuddy/mcp.json；CodeBuddy CLI 有独立的 mcp 文档体系。本文并列双方官方写明的内容。

WorkBuddy 的连接器和 MCP 有什么区别？一个是成品一个是接口

连接器是官方封装好的现成服务对接，点一下授权就能用；MCP 是底层协议，可以接任何支持它的服务。官方明确说明连接器基于 MCP 这类标准化协议实现，自定义连接器的配置方式也与 MCP 类似。本文讲清两者的分工与选择顺序。

WorkBuddy 怎么加第一个 MCP？官方拿企微机器人做了完整示范

官方以企业微信群机器人为例给了完整的 MCP 接入流程——拿 WebHook URL、进插件里的 MCP 服务器、粘一段 mcp.json、看状态灯。本文按这四步走一遍，说明每步容易错在哪，以及配好之后怎么用自然语言调用。

WorkBuddy 提示要写入敏感路径？这是在拦密钥和凭证，不是在为难你

写入受保护或敏感路径是默认权限的四类确认条件之一，官方给的理由是避免覆盖密钥、凭证或安全设置。本文讲清哪些位置属于敏感路径、为什么任务会跑到那里去、怎么用工作空间把作业范围框住，以及企业环境下该找谁。

WorkBuddy 运行脚本被拦下来了？看懂这三件事再决定点确认还是取消

运行脚本、命令或外部程序是默认权限四类确认条件之一。官方说明了为什么单看脚本文本判断风险不够，也给了看到确认框该检查的三件事和四句可以直接说的替代要求。本文拆解怎么判断该放行还是该取消。

WorkBuddy 切模型是排查第一招？官方在五类问题里都这么说

任务卡住、回复乱码、机器人不回复、QQ 频繁断开、读不了文件——官方对这几类问题给的第一步都是切换模型。本文汇总官方在哪些条目里推荐了这个动作、为什么它性价比最高、以及怎么切才有诊断价值。

WorkBuddy 读不了我的图片或 PDF？官方说是模型不支持或没装插件

无法读取图片、PDF、Excel、Word，官方给的常见原因是当前模型不支持对应文件类型，或未安装相关插件与 Skill。本文讲清怎么判断是哪一种、官方给的三条做法怎么用，以及别把它误当成权限问题查。

WorkBuddy 的「内容创作团队」模式覆盖哪些？官方写了多模态和跨语言改编

官方 OPC 场景包里的另一条典型任务是内容创作团队，覆盖视频生成、图文创作、智能剪辑和跨语言素材改编。本文拆解这套能力对应的用法、内容类任务独有的合规红线，以及成本上该怎么控。

WorkBuddy 和 OpenClaw 能互相替代吗？先看你用的是哪几项能力

两者形态不同，能不能替代取决于你实际依赖哪些能力。本文把常见的十项使用需求逐条对照双方官方文档写明的支持情况，给出可以按图索骥的判断表，不做整体优劣判断。

WorkBuddy 的「OPC 一人公司」场景包是什么？官方给的岗位覆盖与落地方式

官方产品页把「OPC 一人公司」列为三个场景包之一，推荐用户是个体创业者、自由职业者、小微团队负责人，能力描述是召唤 AI 专家团覆盖运营、设计、财务、法务、开发等核心岗位。本文拆解这个场景包怎么落地、指令怎么写、什么时候别用。

用 WorkBuddy 备课做培训材料：大纲、练习题、学情表，但学员信息别进目录

培训教研的材料生产适合交出去——大纲、练习题、讲义结构都能批量做。但学员个人信息不该进工作目录，这是培训场景独有的一条红线。本文给出三类材料的指令模板与验收要点。

WorkBuddy 打开后白屏、点了没反应？先分清是没启动还是没登录

WorkBuddy 双击图标没动静、窗口一片空白、点登录毫无反应，看着像同一个问题，处理方式完全不同。本文按「进程有没有起来 → 窗口有没有内容 → 登录能不能拉起浏览器」三层拆开，给出官方对应的处理方式和该收集哪些信息去提工单。

企业微信接 WorkBuddy 走哪条路？两个入口两种模式，官方推荐长连接

企业微信接入有管理员和普通成员两个不同入口，API 模式下又分长连接与 URL 回调两种接入方式。官方明确推荐长连接——配置更简单、无需回填 Webhook URL。本文讲清怎么按你的角色和网络条件选，以及两种模式各自要准备什么凭证。

企业微信接入怎么比？WorkBuddy 接的是智能机器人，CodeBuddy CLI 接的是群机器人

两边都能接企业微信，但接的不是同一种机器人——WorkBuddy 走企业微信的智能机器人（API 模式），CodeBuddy CLI 官方文档给的是群机器人 Webhook 配置。本文并列双方官方写明的机制与前提。

WorkBuddy 企业版和 CodeBuddy 企业版是同一套吗？共用体系，但有两处官方口径不一致

两边共用同一套企业版体系（SaaS 企业版与专有云企业版），积分团队内共享。但官方两处文档对专享版的起购坐席数说法不同，一处写 100 个、一处写 10 个。本文并列全部官方事实，不替官方裁决。

公司要用 WorkBuddy，数据合规该怎么问？个人开关不是最终策略

官方英文隐私文档明确写了企业部署与 API 使用请联系所在组织的管理员——员工在客户端里切的开关未必是最终生效的策略。本文给出企业版独有的管控能力清单、评估时该向官方确认的问题清单，以及内部落地规范该写哪几条。

WorkBuddy 接 QQ 为什么要实名？还有一条 AppSecret 只有一次机会

QQ 开放平台要求账号完成实名认证才能创建机器人，而 AppSecret 官方明确说明不支持明文保存、二次查看将强制重置。本文讲清 QQ 接入的完整流程、这条一次性凭证怎么保管，以及配好之后断开不回复该怎么排查。

WorkBuddy 默认权限和完全访问怎么选？官方两种权限模式的边界与五条禁用红线

WorkBuddy 有默认权限与完全访问两种权限模式，官方英文文档给了切换位置、拦截的四类操作、沙箱三层保护，以及五种绝不能开完全访问的情形。中文文档站目前没有这一页，本文按官方原文梳理，并给出把哪类任务放进哪种模式的判断法。

WorkBuddy 老弹确认框太烦？先别关权限，这四招能真正减少打断

默认权限下高风险操作会停下来等确认，弹得太频繁往往不是产品问题，是工作空间划得太大或指令写得太粗。本文给出减少确认次数的四个办法、官方建议在弹窗里检查的三件事，以及哪些确认是绝对不该嫌烦的。

WorkBuddy 两种权限模式 vs CodeBuddy CLI 的七种，形态不同粒度也不同

WorkBuddy 桌面端给的是默认权限与完全访问两档，同门的 CodeBuddy CLI 则有 default、acceptEdits、auto、dontAsk、plan、bypassPermissions、delegate 等多种模式。本文并列双方官方文档写明的机制，说明粒度差异的由来，不做优劣判断。

WorkBuddy 在群里怎么用？各平台的入群方式和触发方式都不一样

钉钉要注意群的归属组织、企业微信在通讯录的企业创建的分组下找、元宝派可以添加到已有的派、Discord 和 Slack 在频道里 @ 提及。本文汇总各平台的入群方式与触发方式，以及群聊场景下必须先想清楚的一件事。

WorkBuddy 的大任务怎么拆？官方给了反面例子和三轮做法

官方使用技巧里的「小步快跑」给了一个很典型的反面例子——一句话套了三个任务。本文拆解怎么判断该不该拆、按什么维度拆、每一步该确认什么，以及拆完之后怎么把结果串起来。

WorkBuddy 一个任务跑半天？官方给的三步是查网络、减复合、切模型

任务执行很久、运行缓慢，官方给的做法是先确认网络是否稳定、减少一次性过长过大的复合任务、必要时切换模型或拆成多个独立任务并行处理。本文按这三步展开，并给出判断该等还是该停的信号。

WorkBuddy 的日志里有什么？官方说可能包含对话记录，提交前先想一下

提交反馈时那个「上传日志」的勾选项很多人随手就勾了。官方明确写了日志可能包含对话记录、设备信息等数据。本文讲清日志在哪、里面可能有什么、什么时候该勾什么时候该谨慎，以及怎么用测试数据复现问题来规避风险。

WorkBuddy 的「软件开发团队」模式是什么？官方给了四个角色和一个快速模式

官方 OPC 场景包里的典型任务之一是软件开发团队——产品经理定需求、架构师设计拆任务、工程师批量实现、QA 验证质量，小需求支持快速模式。本文拆解这套怎么用、成本怎么控，以及同门还有更对口的形态。

WorkBuddy 的命令跑不起来是被沙箱拦了吗？三种情况先分清

命令执行不了可能是沙箱约束、可能是权限确认被取消、也可能根本是环境问题。官方说明命令先在沙箱约束下运行、文件系统只能访问授权的工作空间目录、启动时仅拥有只读权限。本文教你分清三种情况并给出对应做法。

WorkBuddy 把文件删没了怎么办？先查回收站和目标目录，再看删除保护这层做了什么

官方文档记录了整理桌面后部分文件疑似丢失的情况，也说明了删除保护通过安全删除或回收站保护降低误删风险。本文给出发现文件不见后的四步找回顺序、删除保护的覆盖范围与盲区，以及批量操作前必做的两件事。

给 WorkBuddy 喂上下文的四种方式，样例是性价比最高的那个

同样的任务，给不给上下文、怎么给，结果差很远。本文梳理四种喂上下文的方式——给文件、给样例、给身份、给背景，说明各自适合什么，以及给多了反而变差的情况。

WorkBuddy 生成的文件打不开？官方说原因通常是你没指定输出格式

生成的文件双击打不开、提示格式错误，官方给的常见原因是下达任务时没有明确指定输出文件类型。本文讲清该怎么在指令里写死格式、四种常见格式各自适合什么场景，以及打不开时的四步自查顺序。

WorkBuddy 买了套餐还显示体验版？官方已确认是前端显示异常，仍在修复中

升级后客户端或网页仍显示体验版，官方常见问题页明确说明这是已知的前端显示异常、当前仍在修复中。本文讲清怎么先确认订单真的成功了、哪里能查到真实的权益与积分、该保留什么信息，以及怎么区分显示问题和真的没生效。

什么时候不该把活交给 WorkBuddy？七类任务的判断标准

会用是一回事，知道什么时候别用是另一回事。本文按官方文档里的提示与边界，梳理出七类不该交出去的任务，每类给出判断标准和替代做法。

社群运营用 WorkBuddy 做内容日历和答疑库，但别让它代表官方发言

社群运营的重复劳动集中在内容排期和重复问题答疑，这两块适合交出去。但社群里发出去的每一句话都代表官方立场，这是这个岗位独有的一条红线。本文给出两类材料的指令模板与发布前的检查。

WorkBuddy 给的结果不是我要的？官方给了四种调整方式，别急着重开

结果不对的时候多数人直接重新描述一遍需求，其实官方给了四种更有效的调整方式：直接指出问题、换角度重述、补充限制条件、切换角色视角。本文拆解这四种各自适合什么情况，以及什么时候该果断开新任务而不是继续改。

用 WorkBuddy 处理的资料都去了哪？五条数据流向逐条查

文件在本地、日志可能含对话记录、服务端按官方说明仅处理片段、记忆可能被存储、还有一个默认开启的模型优化开关。本文把 WorkBuddy 涉及的五条数据流向逐条列出来，标明各自的官方依据与你能控制的部分。

WorkBuddy 能私有化部署吗？官方有这条方案，但页面没给价格

国内定价页底部有 WorkBuddy Enterprise 私有化部署方案，官方描述是本地部署、全栈自主可控；同门 CodeBuddy 企业版文档对私有化写得更具体——自有 IDC 完全离线部署、支持国产化显卡与服务器满足信创要求。本文并列两处官方表述与该问清楚的问题。

WorkBuddy、CodeBuddy IDE、CLI、插件——同一家四种形态怎么选

腾讯这套 Buddy AI 系列有桌面工作台、IDE、命令行、IDE 插件几种形态，共用同一账号与积分。本文并列各形态的官方定位、系统与环境要求、以及官方自述的适用人群，帮你按工作方式选，不做优劣判断。

WorkBuddy 的技能和 CodeBuddy 的 Skills 是同一套吗？文档独立，安装方式也不同

两边都有叫 Skills 的能力，但官方给的是各自独立的文档。WorkBuddy 侧是技能市场（上传/查找/创建三条路），CodeBuddy 侧 CLI 与 IDE 各有 Skills 文档。本文并列双方官方表述，并说明装第三方技能前该做的安全检查。

WorkBuddy 能帮你创建技能？描述一下任务就行

技能市场的「添加技能」里有一个「创建技能」选项——输入任务描述，WorkBuddy 会自动创建相关技能。本文讲清什么活值得固化成技能、描述该怎么写、以及创建出来之后怎么管理和分发。

WorkBuddy 的技能怎么装？官方给了上传、查找、创建三条路

技能市场分已安装和推荐两个区域，添加技能有三种方式——导入本地技能包、描述任务让它查找、描述任务让它创建。本文讲清三条路各自适合什么、启用与关闭的建议，以及为什么官方建议只开当前任务需要的技能。

WorkBuddy 接 Slack 用的是 Socket Mode，不需要公网地址

Slack 接入通过 Socket Mode 建立连接，官方明确说明无需公网 Webhook 地址。要准备两个 Token（xapp- 开头的 App Token 和 xoxb- 开头的 Bot Token）、六个 Bot 权限、两个事件，最后还要在私聊里发一个配对码。本文按官方六步走完整流程。

WorkBuddy 接 Telegram 只要一个 Token，是九个平台里最短的流程

Telegram 接入通过 BotFather 创建 bot 拿一个 Bot API Token 就行，没有权限申请、没有事件订阅、没有发布审核。本文给出完整三步、bot 用户名必须以 bot 结尾这条硬规则、Token 怎么重置，以及为什么必须先发一次 /start。

WorkBuddy 的问题该找谁？三条官方渠道各管一摊，别走错

功能问题走客户端反馈入口、积分异常发官方邮箱、退款走腾讯云工单——三条渠道各管一摊，走错就是绕远路。本文给出各自的官方路径、日志怎么取、上传日志前要注意什么，以及一份能少来回几轮的提交模板。

WorkBuddy 怎么申请退款？官方给的是腾讯云工单流程，两个工作日处理

WorkBuddy 的退款不在客户端里操作，走的是腾讯云官网提交工单的流程。本文按官方 FAQ 拆解完整六步、说明客服处理时限与退款到账后在哪查，并如实指出官方未列出退费条件这一空白该怎么处理。

WorkBuddy 和 CodeBuddy IDE 插件是什么关系？同一账号下的两种形态

CodeBuddy 有独立的 IDE 与 IDE 插件形态，与 WorkBuddy 共用同一账号和积分。本文并列官方文档写明的定位差异、下载入口怎么区分、以及混用时该注意的积分与权益问题。

WorkBuddy 和 CodeBuddy CLI 是什么关系？共用账号，但形态和受众完全不同

两者共用同一账号与积分，但一个是桌面工作台、一个是终端里的命令行工具。本文并列双方官方文档写明的定位、安装方式、核心能力与适用人群，并说明同名能力在两边未必是同一套实现。

WorkBuddy 免部署装了就用，OpenClaw 要自己跑一个网关——两种运维负担并列

WorkBuddy 官方产品页写的是「免部署·安装即用」；OpenClaw 官方文档列了 Ansible、Docker、Kubernetes 以及十余种云托管方式。本文并列双方官方文档写明的安装、部署与运维要求，帮你判断你愿意承担哪一种。

接入渠道谁覆盖得广？WorkBuddy 九个平台，OpenClaw 一长串外加插件生态

WorkBuddy 官方支持九个即时通讯平台；OpenClaw 文档列出的渠道更多，还能通过渠道插件扩展。本文并列双方官方文档写明的渠道清单、各自独有的部分、以及接入方式的机制差异，不做优劣判断。

QQ 接入怎么比？WorkBuddy 要实名且 AppSecret 只有一次机会

两边都能接 QQ，但 WorkBuddy 侧有两条硬约束——QQ 开放平台要求账号实名认证，且官方明确 AppSecret 不支持明文保存、二次查看将强制重置。本文并列双方官方写明的机制与前提。

海外三家怎么比？Slack、Telegram、Discord 在两边的接入方式并列

Slack、Telegram、Discord 是两边都支持的三个海外渠道。WorkBuddy 各有独立官方指南（Slack 走 Socket Mode 且要发配对码、Discord 要开三个 Intents）；OpenClaw 把它们列在核心渠道里。本文并列双方官方写明的机制。

微信接入怎么比？WorkBuddy 扫码即用，OpenClaw 走腾讯维护的外部插件

WorkBuddy 的微信助理官方明确无需任何开发凭证、只需扫码；OpenClaw 的微信渠道通过腾讯微信团队维护的外部插件 @tencent-weixin/openclaw-weixin 实现，需要装插件、重启网关、命令行登录。本文并列双方官方文档写明的机制与限制。

腾讯元宝在两边都能接，但一个是内置集成一个是渠道插件

WorkBuddy 的元宝派接入是产品内置的双向流程，要回 App 点「我已操作」确认；OpenClaw 的腾讯元宝在中文区渠道分组里，走渠道插件路径。本文并列双方官方写明的机制与容易漏的步骤。

WorkBuddy 的自动化和 OpenClaw 的 Cron 怎么比？一个图形配置，一个网关调度器

WorkBuddy 的自动化是客户端里的表单配置、按订阅档位限数量；OpenClaw 的 Cron 是 Gateway 网关的内置调度器，任务持久化到 SQLite、用命令行创建。本文并列双方官方文档写明的机制，不做优劣判断。

WorkBuddy 和 OpenClaw 是一类东西吗？两边官方文档的定位、部署方式与费用结构并列看

WorkBuddy 是腾讯云 CodeBuddy 团队的商业桌面 AI 工作台，OpenClaw 是 MIT 许可的自托管 Gateway 网关。两者常被放在一起讨论，但形态前提完全不同。本文只并列双方官方文档写明的定位、系统要求、安装方式、渠道覆盖与费用结构，各标来源与核对日，不做优劣判断。

用 WorkBuddy 做行业调研和竞品分析，指令该怎么写才不出假信息

官方把「外部信息调研与内容生成」列为三大场景包之一，能给一个主题就自动搜集分析并生成调研报告或 PPT。这类任务最大的风险是编造信息，本文给出可复制的指令模板、五步验收法与三条硬约束。

WorkBuddy 的完全访问什么时候不能开？官方列了五条，最后一条最容易被忽略

完全访问会关闭高风险操作的确认流程。官方明确写了它并不更安全，并列出五种绝不该开启的情形与三种合理场景。本文逐条拆解这五条红线，说明怎么搭一个真正隔离的环境，以及用完为什么必须切回来。

企业微信提示 Webhook 域名主体校验未通过？先核对地址是否完整

企业微信侧会对 Webhook 地址做域名主体校验，官方给的做法是核对地址是否完整、是否与当前配置要求一致，仍不通过则保留报错截图提交排查。本文讲清这个校验发生在哪一侧、地址最常出错的三个地方，以及为什么优先选不需要公网地址的连接方式。

WorkBuddy 微信助理怎么绑？不用任何凭证，但版本号要够

微信助理是九个接入平台里唯一不需要开发凭证的——官方明确说明只需扫码。但它有两条硬版本要求：WorkBuddy 需 4.6.4 以上、微信需 8.0.70 以上。本文给出完整绑定流程、官方的三条排查，以及鸿蒙用户要注意的一条。

WorkBuddy 的文件备份为什么只有 Windows 有？Mac 用户要补上这一层

官方权限模式文档写明「文件备份」这层保护目前仅 Windows 支持——修改已有文件前自动存副本。Mac 上没有这层兜底。本文说明这层保护的确切范围与三个盲区、Mac 用户该用什么习惯补齐，以及 Windows 用户也不能只靠它的原因。

Windows 装 WorkBuddy 卡住？先处理安全软件，再看这三个目录

Windows 上装 WorkBuddy，官方原文写明它常被安全软件误拦截。本文按 Windows 用户的动线梳理系统要求、安装目录、账号配置目录与工作空间三个路径、登录失败时官方给的 PowerShell 权限检查与授权命令，以及日志与反馈入口。

项目经理用 WorkBuddy 维护进度台账和风险清单，但风险定级得自己来

项目经理最花时间的是把散在各处的进度信息汇成一张台账。本文给出进度台账与风险清单的指令模板、周会前的三步准备，以及项目管理场景独有的一条红线——风险由人定级。

WorkBuddy 定价页上的「限免生效中」是什么意思？看权益别被括号骗了

国内定价页多项权益带着限免生效中的角标，括号里的数值是活动态不是常规权益。本文逐条列出哪些项目带限免、常规值与限免值分别是多少、活动结束后会有什么变化，以及买之前该按哪个数字算。

WorkBuddy 的自动任务能推到小程序，但结果会同步到云端

自动化配置里有一项「推送到小程序」，开启后任务结果会通过安全链路同步到云端，以便在小程序端接收。本文讲清这个开关的实际含义、小程序怎么连、以及哪些任务开这一项之前要先想清楚。

WorkBuddy 从哪下载？官方叫「腾讯龙虾」，Mac 两个包别选错

WorkBuddy 的官方下载入口在腾讯云 CodeBuddy 国内站，按钮上标的中文名是「腾讯龙虾」。Mac 提供 Intel 与 Apple 芯片两个 dmg，Windows 只有一个 x64 包。本文讲清入口位置、四个安装包怎么选、国内站与国际站的关系，以及下载前要确认的系统版本。

把业务数据交给 WorkBuddy 分析，官方场景包怎么用才靠谱

官方「业务数据洞察与自动化响应」场景包面向运营、客户成功、管理角色，典型任务是用户反馈舆情分析与销售业绩洞察。本文给出这两类任务的指令模板、数据进目录前必做的脱敏、以及归因这件事为什么不能交出去。

手机上让 WorkBuddy 传桌面文件提示无法完成？官方建议改成指定路径

通过飞书、企微、QQ、钉钉、微信移动端让它上传电脑桌面的文件时提示无法完成，官方说明这个能力受设备权限、路径访问方式与平台能力限制，建议改为在本机侧明确指定文件路径后再执行。本文讲清怎么改指令、远程用法的边界在哪。

WorkBuddy 怎么接元宝派？AppID 要填进「App Key」那个框

元宝派接入需要在腾讯元宝 App 里创建 Bot 拿到 AppID 和 AppSecret，再填进 WorkBuddy 的注册对话框——但两边的字段名对不上，AppID 要填进「App Key」。本文给出完整双向流程、最后那步「我已操作」的作用，以及怎么把 Bot 加进群聊。

WorkBuddy 走 IM 遥控，CodeBuddy CLI 走网页——两条远程路线的机制差异

WorkBuddy 的助理通过九个即时通讯平台接入；CodeBuddy CLI 的远程控制启动一个本地 Gateway，通过 Cloudflare Tunnel 或局域网暴露 Web UI。本文并列双方官方文档写明的机制，含 CLI 那条「远程任务自动以 bypassPermissions 运行」的重要说明。

WorkBuddy 的数据安全机制有哪些？官方三层纵深防御逐条看，附两处口径的对照

WorkBuddy 官方常见问题页给出了技术防御、管理管控、合规审计三层安全机制，包括沙箱隔离、allow/ask/deny 分层权限、数据本地执行不上传等。本文逐条梳理官方声明，并对照英文文档的两种权限模式，说明这两套描述各自管什么。

WorkBuddy 怎么注销账号？官方入口在个人主页，注销前先把这五件事处理完

WorkBuddy 的账号注销走官网个人主页的账号管理入口，不在客户端里。本文给出官方路径，并梳理注销之前必须先处理的订阅、发票、积分、本地文件与记忆数据五件事，以及官方文档没有说明的部分。

WorkBuddy 指令最常见的六种写法错误，对照官方正反示范逐条改

官方给了一组正反示范，差别不在措辞而在信息完整度。本文把常见的六种指令写法错误逐条列出，每条给出为什么会出问题和改法，都对照官方的三要素公式与技巧文档。

WorkBuddy 指令怎么写才不返工？官方三要素公式 + 四个必填项，附可直接套的模板

同一件事交给 WorkBuddy，有人一次拿到能用的结果，有人来回改五轮。差别不在模型，在指令。本文拆解官方的「做什么＋有什么＋怎么样」三要素公式与任务描述四要素，给出可复制的模板、六个典型反例的改法，以及什么时候该开新任务而不是继续改。

WorkBuddy 回复乱码、胡乱输出怎么办？官方给的第一招是切模型

回复出现乱码、内容跑飞、长时间没响应，官方归因为模型异常、任务过重或网络不稳定三类，给的做法是先切换模型测试、把复杂任务拆小、记录是否伴随错误码或超时。本文按这三类展开，并给出该收集哪些信息去提工单。

WorkBuddy 的专家团和 CodeBuddy 的子代理是一回事吗？都是多角色，但配置方式完全不同

WorkBuddy 的专家团是产品内置的角色库，点一下召唤、团长自动拆解分配；CodeBuddy CLI 的子代理有独立的 sub-agents 文档体系，还有一个专门的 delegate 权限模式。本文并列双方官方表述，说明为什么不能画等号。

WorkBuddy 的专家怎么挑？先看卡片上的擅长领域和任务示例

专家中心里每位专家都有独立的人设、方法论和工具链，专家团则是有团长有分工的多 Agent 团队。本文讲清挑选时该看卡片上的哪几栏、Skill 与专家与专家团的选择标准，以及官方那条「无法替代专业判断」的提醒意味着什么。

WorkBuddy 的专家团比单个专家贵多少？官方原话是「通常为数倍」

专家团会调用多位专家协同执行，官方明确提示积分消耗通常是单个专家的数倍。本文讲清 Skill、专家、专家团三者的区别与选择标准、什么任务值得动用专家团、以及积分不够时该怎么退回单专家。

WorkBuddy 的助理为什么不能改默认文件夹？官方说它是专给远程用的

助理功能不支持修改默认文件夹，官方也明确建议电脑端新建任务时不要把助理作为工作空间。本文讲清这两条限制背后的设计意图、拿助理当工作空间会带来什么副作用，以及远程场景下该怎么规划目录。

WorkBuddy 什么任务适合配成自动化？官方给了三条判据

官方对自动化的适用判据是重复性高、规则明确、无需实时人工干预，并给了五个具体例子。本文按三条判据逐项判断、列出五类不该配成自动化的任务，以及从模板起步的四个现成方向。

WorkBuddy 的自动任务模板有哪几个？新闻推送、周报、体检预约、学习计划

不想从零写提示词，官方提供了任务模板，覆盖新闻推送、周报生成、体检预约以及学习计划等常见场景，选择后按需修改即可。本文讲清四个方向各自怎么改、改哪几处，以及为什么第一个自动任务应该从模板起步。

WorkBuddy 各档能配几个自动任务？常规值是 3/15/30/99，别按限免那个数规划

国内定价页的自动任务数量各档不同，页面上还挂着「限免 99 个」的角标。限免是活动态不是常规权益，按它规划流程会在活动结束时塌掉。本文给出各档常规值、怎么按用量选档，以及自动任务不够用时的三条替代思路。

WorkBuddy 的自动化任务怎么建？六个配置项逐个说，还有现成模板

自动化任务有名称、工作空间、提示词、模型与技能、定时规则、推送到小程序六个配置项，官方还提供了新闻推送、周报生成、体检预约、学习计划等任务模板。本文逐项讲清怎么填、默认工作空间在哪，以及哪些任务不该配成自动化。

WorkBuddy 的「自动化响应」怎么落地？先分清哪些能自动、哪些只能自动一半

官方场景包提到把业务数据交给它自动完成分析并生成指导方案。但「响应」这两个字里，能自动的只有前半段。本文拆解自动化响应的四层结构，说明每层的边界在哪。

用 WorkBuddy 做复盘，最难的一步是让它别替你下结论

复盘的价值在于找到真正的原因，而 AI 最擅长的恰恰是给一个听起来合理的解释。本文给出复盘材料的指令模板、事实与推断的分离方法，以及为什么归因这一步必须自己做。

用 WorkBuddy 做会议议程和会后跟进：官方实践里有一条建议特别值钱

官方在 Google 日历实践里给了一条建议——对重要会议，让它输出「待确认事项」和「风险点」。这一条把会议材料从信息汇总变成了带优先级的提示。本文给出会前议程与会后跟进的完整指令模板。

用 WorkBuddy 整理客户名单，第一件事是把不需要的字段删掉

客户名单是最敏感的一类办公数据，整理它的第一步不是写指令，是决定哪些字段根本不该进工作目录。本文给出脱敏清单、去重与合并的指令模板，以及这类任务独有的三条红线。

用 WorkBuddy 起草需求文档，先出结构再填内容

PRD 最怕的是结构没定就开始写细节，改一轮就要重排一次。本文给出两步走的写法、需求文档里哪些部分能交出去哪些必须自己写，以及验收时该重点看的三处。

用 WorkBuddy 做月报，跟做周报的写法不一样在哪

月报不是四份周报拼起来。它要的是趋势、是月度维度的对比、是能支撑决策的口径。本文给出月报专用的指令模板、素材该怎么组织、以及月报最容易出的那类错误怎么防。

CC Switch 有多少个 Tauri 命令：294 到 304 与一个 grep 陷阱

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

CC Switch 有多少条预设：README 说 50+，我们数出 448 条

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

CC Switch 安装：msi / dmg / AppImage 与 brew、paru 怎么选

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

CC Switch 支持哪些 AI CLI：README 说八个、手册只列七个

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

CC Switch 的版本门槛：README 写 Rust 1.85+，toolchain 钉 1.95

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

CC Switch 的测速超时：2 / 8 / 30 秒这三个数怎么用

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

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

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

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

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

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

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

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

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

CC Switch 后端四层架构：Commands、Services、DAO 与数据库

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

CC Switch 的 category 不只是标签：它还决定路由与代理拦截

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

CC Switch 的格式转换层：三套协议适配器的位置与边界

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

CC Switch 的「切回官方登录」是怎么实现的

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

CC Switch 的故障转移：候选队列怎么挑下一家供应商

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

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

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

CC Switch 当前供应商删不掉：手册说能删、后端直接报错

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

CC Switch 在 Linux 上点不动、缩放黑屏：那个逃生环境变量

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

CC Switch 的 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 两个方向、取消勾选时的反向删除，以及导入的容错口径。

CC Switch 用一个面板管多个应用的 MCP：路径与格式差异

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

CC Switch 的三种托管 OAuth 必须开路由：判定链怎么走

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

CC Switch 同步 CLAUDE.md 等三份文件：回填保护怎么做

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

CC Switch 的数据库迁移：调度机制与跳掉的三个编号

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

CC Switch 启动时干了什么：启动序列、崩溃日志与托盘

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 的会话管理器能读哪些来源，读到的是什么

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

CC Switch 是什么：一个桌面应用管住多个 AI 客户端的配置

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

CC Switch 的数据落在哪：一个库、一份设置与两种备份

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

CC Switch 装 Skills 是软链还是复制：两种策略的差别

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

CC Switch 的 SQLite 表：所谓 SSOT 到底存了哪些东西

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

CC Switch 的 Stream Check：文档说发真实请求，代码只探连通

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

CC Switch 的三个 thinking 整流器分别在修什么

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

CC Switch 的 universal 统一供应商：边界在哪

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

CC Switch 切换后配置少了一段：通用配置片段怎么回填

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

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

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

CC Switch 的用量数字从哪来：代理日志还是本地会话文件

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

CC Switch 的配置不被写坏：原子写入与自动备份两件事

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

CC Switch 的云同步两条路线：S3 与 WebDAV

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

CC Switch 的一条预设长什么样：ProviderPreset 字段全集

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

CLI-Anything 的注册表 79 条、顶层 82 个目录：差的是什么

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

CLI-Anything 怎么安装与使用：先看清它装到哪

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

CLI-Anything 的 APP.md 写什么：一层没有强模板的项目分析

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

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

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

CLI-Anything 的 CLI 入口模式与命令注册方式

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

CLI-Anything 的 comfyui harness：工作流软件怎么接

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

CLI-Anything 的 core 与 utils 分工：这条线不是按业务划的

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

CLI-Anything 的 description 决定会不会被触发：写法规律

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

CLI-Anything 的 SKILL.md frontmatter 字段全集：哪些必填

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

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

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

CLI-Anything 的 harness 标准目录结构：四件套是哪四件

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

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

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

CLI-Anything 的 matrix_registry：矩阵这层抽象干什么用

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

CLI-Anything 的 obs-studio harness：不启动 OBS 的操控面

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

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

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

CLI-Anything 的 public_registry 与 registry 差在哪

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

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

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

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

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

CLI-Anything 的 harness 怎么驱动宿主：四种方式与各自代价

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

CLI-Anything 的同构度与缺件清单：哪些 harness 不齐

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

CLI-Anything 的 registry.json 结构与那 79 条记录

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

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

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

CLI-Anything 是什么：让所有软件变得 agent-native

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

CLI-Anything 的 skill 与 harness 是不是一一对应

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

CLI-Anything 给 agent 读的 SKILL.md：字段与正文结构

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

CLI-Anything 的 skills 目录清单：70 个目录、70 个文件

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

CLI-Anything 的 TEST.md 与测试组织：它到底测了什么

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

CLI-Anything 的 cli-hub 装到哪：它会往你机器上写哪些目录

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

CLI-Anything 的 cli-hub 矩阵机制：装完不等于能力齐了

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

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

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

CLI-Anything 的 registry 拉取与合并：117 行决定你看到多少条

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

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

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

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

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

DeepTutor 的 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 这个数字自己数一遍的核查动作。

DeepTutor 的版本演进：past_releases 到 1.5.11 的轨迹

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

DeepTutor 的 BaseAgent：模型解析优先级与两个 LLM 入口

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

DeepTutor 的 book 模块：把知识库变成一本书的四段流水线

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

DeepTutor 的 book 数据模型：19 个 BlockType 与 13 个生成器

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

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

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

DeepTutor 的 chat agent loop：一轮里工具是怎么挂上去的

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

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

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

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

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

DeepTutor CLI 命令树一次看完：命令组取决于你怎么数

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

DeepTutor 的 co_writer 协作写作：623 行与不在包里的那半套

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DeepTutor 知识库的类型模型与 manifest 清单

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

DeepTutor 的 LLM 接入层：统一调用口与 provider 名单

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

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

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

DeepTutor 的多用户隔离与 grant 授权：四棵目录树

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

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

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

DeepTutor 的判分与错误分类：答错之后它认为你错在哪

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

DeepTutor 的 partners 层：它接到了哪些 IM 渠道

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

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

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

DeepTutor 的 provider 命令能配哪些字段：一个都不配

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

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

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

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

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

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

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

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

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

DeepTutor 的 SectionArchitect：目录是被规划出来的

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

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

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

DeepTutor CLI 的 session、notebook、book 与 memory 各管什么

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

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

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

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

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

DeepTutor 的 skill 与 skill_login 不是一回事

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

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

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

DeepTutor 的提示词为什么放在几十个 yaml 里

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

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

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

DeepTutor 的 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 上复跑的检索动作。

DeepTutor 的掌握度怎么算：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 服务器再上线。