把一个重复任务，
变成团队会用的 AI 工作流

现象

教程让你用某个 AI 工具（命令行调用的那种），你在终端敲 which 工具名（Mac/Linux）或 where 工具名（Windows）或 PowerShell 的 Get-Command 工具名，结果返回"找不到"。你心想"没装啊"，于是去 npm install -g 全局装一个。可装完发现还是用不对，甚至装错版本、跑偏了整个方案。

根因

关键认知：which/where 找不到，只代表"这个名字没注册成全局命令"，不代表"工具没装、不能用"。

很多现代工具根本不注册全局命令，而是靠别的方式调用，最典型的两种：

1. npx 临时拉取：工具通过 npx --package 某包 工具名 调用，npx 会临时下载/缓存到本地来跑，通常不往全局 PATH 注册命令。所以 which 工具名 找不到不能直接说明它不能用。
2. Python 模块入口：工具是 python -m 某模块 这种方式调，也没有独立的全局命令名。

你拿"全局命令名"去探测一个"本来就没有全局命令名"的工具，当然找不到——但这是探测方法的错，不是工具没装。

先判断（动手前先确认）

别一看到"找不到"就动手装。先用 30 秒确认工具到底是哪一种调用方式：

• 打开教程/官方文档，看它给的调用命令长什么样：是 npx ...？是 python -m ...？还是某个带后缀的包装脚本？
• 只要文档让你用 npx 或 python -m 调它，就不要先用全局命令名判断存在性——这类调用方式通常不依赖全局 PATH，which/where 找不到不能证明没装。
• 如果工具是某个 agent 执行器/框架在内部调的，那就更别用 which 判存在性了，直接去看框架的运行记录。

一句话：用 which 去探测 npx/python 模块类工具，方法本身就是错的。

一步一步做

1. 翻工具的安装说明 / 配置文件，确认它真实的调用方式（npx 包名？python -m 模块？某个包装脚本？）。
2. 用文档里的原始命令直接跑一次，不要自己改写成全局命令名。
3. 如果工具是被某个框架/执行器内部调用的，去翻该框架的运行结果记录（执行日志），看历史上有没有成功调用过这个工具——有成功记录 = 工具能用。
4. 命令能正常返回结果 → 工具能用，不用装；命令本身报错 → 按报错信息排查，仍然不是"没装"。
5. 只有当：文档规定的调用方式也对、历史也从没成功过，才考虑"真没装"——这时再严格按文档装。

常见误区

• 误区 1：看到 which/where 报"找不到"就以为没装。 错。npx 调用的工具通常不需要全局命令名，which 失败不能直接说明工具不能用。
• 误区 2：看到找不到就去 npm install -g。 结果可能装错版本、污染全局环境、甚至和方案要求的版本冲突，越装越乱。
• 误区 3：拿"全局命令名"去探测一个靠 python -m 调用的工具。 这种工具可能没有独立命令名，用全局命令名探测很容易误判。
• 误区 4：以为必须装成全局才能用。 很多工具就是按需临时拉取 / 模块调用，全局安装纯属多余。

交给 AI 助手时怎么说

"我要用 <工具名>，命令行 which/where <工具名> 显示找不到。但教程里它的调用命令是 <粘贴原始命令，比如 npx xxx 或 python -m xxx>。请帮我判断：这个工具是不是本来就不需要全局命令名？我该怎么用文档里的原始方式直接验证它能不能用，而不是去全局安装？"

适用 · 通用判别式

判别要点：which/where/Get-Command 找不到某工具 ≠ 工具没装。

• IF 工具是通过 npx 调用的 → 先按原始 npx 命令验证，不要把 which 失败等同于不可用。
• IF 工具是 python -m 模块 调用的 → 先按模块方式验证，不要强行找全局命令名。
• 判断可用性：看真实调用方式 + 运行历史记录（有没有成功跑过），而不是 which 的返回。
• 适用于所有"工具命令探测不到"的判断（npx 调用的 CLI、Python 模块入口、各种包装调用）。

验收标准

• ✅ 按文档原始调用方式（npx ... / python -m ...）直接跑，工具正常返回结果。
• ✅ 翻运行记录，历史上能找到该工具的成功调用记录。
• ✅ 全程没有新增全局安装（npm install -g 的包数没增加），问题却解决了。
• ✅ 你能向自己解释清楚"为什么 which 找不到但工具其实能用"。

现象

很多小白第一次用 Codex，会把两件事混在一起：

• 界面语言：菜单、按钮、侧边栏、状态栏显示英文。
• AI 回复语言：Codex 给你的解释、总结、代码注释、方案默认用英文。

最常见的坑是：明明想让 AI 用中文回复，却一直去找“界面语言设置”；或者在项目里临时说了一句“用中文”，下一次开新会话又变回英文。

这两件事要分开处理：界面语言归产品设置，回复语言归指令文件。

根因

关键认知：AGENTS.md 控制的是 Codex 做事和回复的指导原则，不等于 UI 语言包。

OpenAI Codex 官方 manual 里明确写了几件事：

• Codex 开始工作前会读取 AGENTS.md。
• 全局指导放在 Codex home 目录，默认是 ~/.codex/AGENTS.md。
• 项目指导放在项目根目录或更深层目录的 AGENTS.md。
• 越靠近当前工作目录的项目级指导，优先级越高。
• Codex App 里的 custom instructions 会更新个人 AGENTS.md。

所以，如果你要解决“AI 回复英文”，最稳的是写一条持久中文回复规则，而不是反复在每次对话里提醒。

先判断（动手前先确认）

先看你到底要改哪一种“英文”：

• Codex 的解释、总结、代码注释是英文：走 AGENTS.md，这是本卡重点。
• 某个项目必须中文，其他项目可以英文：在那个项目根目录放项目级 AGENTS.md。
• 所有项目都想默认中文：在用户 Codex home 里放全局 AGENTS.md。
• IDE 扩展或 App 的按钮/菜单英文：这属于 UI 设置，不能靠 AGENTS.md 保证；按当前产品设置处理。

一句话：想改“AI 怎么说话”，写 AGENTS.md；想改“界面怎么显示”，找产品设置。

一步一步做

### A. 让所有 Codex 会话默认中文回复

1. 找到你的 Codex home 目录：

• macOS / Linux：~/.codex/
• Windows：%USERPROFILE%\.codex\

1. 新建或编辑 AGENTS.md。
2. 写入：

## Communication

- Always respond in Chinese.
- 默认用中文解释、总结和写代码注释。
- 命令、API 名称、错误原文和文件路径保持原样，不要硬翻译。

1. 重新打开 Codex 会话，让它重新加载指导文件。
2. 问一句：“请总结你当前加载的沟通规则。”如果它能用中文说出规则，就说明生效。

### B. 只让某个项目默认中文

如果你只想让某个项目用中文回复，就在项目根目录放 AGENTS.md，写同样的 Communication 规则。

项目级 AGENTS.md 适合团队协作，因为它跟着仓库走；全局 ~/.codex/AGENTS.md 适合你个人所有项目默认中文。

### C. Codex App 里怎么改

如果你用 Codex App，可以在 Settings 里写 custom instructions。官方 manual 说明：编辑 custom instructions 会更新你的个人 AGENTS.md。

适合写：

默认用中文回复。解释、总结、代码注释用中文；命令、API 名称、错误原文和文件路径保留原文。

### D. IDE 扩展界面语言不要和回复语言混在一起

Codex IDE extension 有一个 chatgpt.localeOverride 设置，官方说明它是“Codex UI 的首选语言”；留空则自动检测。

注意：这类 UI 设置影响的是界面显示，不等于强制 AI 回复中文。AI 回复语言仍然建议用 AGENTS.md 固定。

常见误区

• 误区 1：改了界面语言，就以为 AI 一定中文回复。 不一定。界面语言和回复语言是两套东西。
• 误区 2：每次聊天都临时说“用中文”。 临时指令只管当前上下文，换项目或新会话容易丢；长期规则应写进 AGENTS.md。
• 误区 3：全局和项目级 AGENTS.md 放反。 想所有项目都中文，放 Codex home；只想一个项目中文，放项目根。
• 误区 4：规则太长太杂。 只写“默认中文 + 保留命令/API/错误原文”就够了，越短越稳。
• 误区 5：把错误信息也翻译掉。 排查问题时，错误原文、命令、API 名称要保留英文，否则复制搜索和定位会变困难。

交给 AI 助手时怎么说

"我想让 Codex 默认用中文回复。请先判断我应该改全局 ~/.codex/AGENTS.md，还是只改当前项目的 AGENTS.md。请帮我写一个最小规则：解释、总结和代码注释默认中文，但命令、API 名称、错误原文、文件路径保留原文。不要修改密钥或系统设置。"

适用 · 通用判别式

判别要点：先分清 UI 语言和回复语言。

• IF 问题是“AI 回复/总结/注释英文” → 写 AGENTS.md。
• IF 想所有项目默认中文 → 全局 Codex home 的 AGENTS.md。
• IF 只想当前项目中文 → 项目根目录 AGENTS.md。
• IF 问题是按钮、菜单、侧边栏英文 → 查当前 App / IDE extension 的 UI 设置；不要指望 AGENTS.md 改界面。

验收标准

• ✅ 新开 Codex 会话后，解释、总结和代码注释默认中文。
• ✅ 命令、API 名称、错误原文和文件路径没有被强行翻译。
• ✅ 全局规则放在 Codex home 的 AGENTS.md；项目规则放在项目根目录 AGENTS.md。
• ✅ Codex 能说清当前加载了哪些沟通规则，说明指导文件已被读取。

参考来源

• OpenAI Codex Manual：Custom instructions with AGENTS.md。
• OpenAI Codex Manual：Codex app settings 中 custom instructions 与个人 AGENTS.md 的关系。
• OpenAI Codex Manual：Codex IDE extension setting chatgpt.localeOverride。

本条为公开官方文档的脱壳重写；UI 设置名称可能随版本变化，实际操作以当前 Codex App / IDE extension 界面为准。

现象

跟着教程装 AI 工具，命令行敲 npm install 或 npm install -g 某个包，进度条卡死，最后报：

npm ERR! network context deadline exceeded

或者干脆挂在那儿十几分钟不动。明明开着科学上网，浏览器能打开网页，偏偏 npm 装不上。这是国内玩 AI 工具的头号拦路虎——Cursor、Claude Code、飞书 lark-cli、小程序自动化工具，装的时候几乎都会撞上。

根因

关键认知：npm 默认根本不走你的系统代理。

• 浏览器、部分软件会自动读系统的代理设置，但 npm 不会。
• npm 的 proxy / https-proxy 配置默认是空的（null）。
• 你在终端里设的 HTTP_PROXY 环境变量，npm 也不读。
• 结果就是：npm 直连国外的 npmjs.org 官方源，国内网络大概率超时。

所以"我明明开了代理"≠"npm 走了代理"。这是两回事。

先判断（动手前先确认）

国内 npm install 卡住 / 超时，很常见的原因是 npm 没走代理，而不是包本身有问题。先做两个确认：

• 确认浏览器能正常开网页（说明代理是开着的）——但 npm 不读系统代理，所以这跟"npm 能不能装"是两码事。
• 看报错关键词：含 context deadline exceeded / ETIMEDOUT / ENOTFOUND / 进度条十几分钟不动 → 锁定是代理问题，别去怀疑包损坏或版本不对。

一句话：只要在国内 npm 卡住，先按"代理没走"排查，通常最快定位。

一步一步做

1. 看一下本地代理地址和端口（在代理软件界面里看，形如 <你的代理地址:端口>；不要照抄别人的端口）。
2. 给这次安装显式带上代理参数重跑（把端口换成你自己的）：

npm install -g <包名>@latest --proxy http://<你的代理地址:端口> --https-proxy http://<你的代理地址:端口>

1. 带代理后如果秒装成功 → 确认就是代理问题，收工。
2. 想一劳永逸（不想每次都带参数）→ 换国内镜像源：

npm config set registry https://registry.npmmirror.com

1. 换完后普通的 npm install 不再需要代理参数（镜像源在国内，直连就快）。

常见误区

• 误区 1：我开了科学上网，npm 就该走代理。 错。npm 不读系统代理，必须显式带 --proxy 或在 npm config 里设。
• 误区 2：设了 HTTP_PROXY 环境变量以为 npm 会读。 新版 npm 默认不读环境变量里的代理配置，得用参数或 npm config set proxy。
• 误区 3：一直挂着等。 npm 网络超时默认要很久才报错，十几分钟才吐 context deadline exceeded，别干等，直接按代理处理。
• 误区 4：换国内镜像后还带着指向国外代理的 --proxy。 反而会拖慢国内镜像，镜像源直连最快，换源后就别再带代理参数了。

交给 AI 助手时怎么说

"我在国内用 npm install -g <包名>，报 context deadline exceeded / 一直卡住装不上。我开了代理（地址和端口是 <你的代理地址:端口>），浏览器能正常上网。请帮我生成一条带 --proxy 参数的安装命令，并说明怎么一劳永逸换成国内镜像源（registry.npmmirror.com）。"

适用 · 通用判别式

判别要点：只要你在国内用 npm install 出现 context deadline exceeded 或长时间卡住 → 优先怀疑 npm 没走代理。

• IF 命令带 --proxy 参数后秒装成功 → 确认就是代理问题。
• IF 你不想每次带参数 → 直接 npm config set registry 换国内镜像，根治。
• 这个规律同样适用于：lark-cli、miniprogram-automator、任何用 npm 分发的 AI 工具。

验收标准

• ✅ 带上 --proxy 参数后，原本卡十几分钟的安装在几秒到十几秒内完成。
• ✅ 不再出现 context deadline exceeded / ETIMEDOUT 报错。
• ✅（如换镜像）npm config get registry 显示国内镜像源，且普通 npm install 不带代理也快。

现象

用音频驱动口型的数字人方案（Musetalk / Wav2Lip / SadTalker 这类），生成出来的视频要么音频嘈杂、要么人物脸部变形扭曲、要么嘴巴动的跟说的话对不上。源视频明明是好的，配音也是好的，合在一起就崩了。

根因

关键认知：这类数字人是"音频驱动"的——它按音频的时长和节奏去驱动嘴型。 一旦音频时长和视频时长对不上，整个口型同步就会错乱。

最常见的情况：原始音频（比如 39 秒）在某个环节被裁剪 / 压缩成了很短的一段（比如 6 秒），而源视频是 64 秒。短音频去驱动长视频，引擎为了凑时长就会拉伸 / 错位，结果就是口型对不上、脸部变形、音频变质。

换句话说：不是模型不行，是你喂给它的音频被悄悄"瘦身"了。

先判断（动手前先确认）

所有"音频驱动口型"的数字人，只要出现口型错位 / 脸部变形 / 音频嘈杂，第一怀疑是音频时长 vs 视频时长不匹配，而不是模型参数或源视频质量。一条命令定性——分别取两边时长：

ffprobe -i <音频>
ffprobe -i <视频>

• 音频时长明显短于视频口型段（比如 6 秒音频驱动 64 秒视频）→ 高度可能口型错乱，先修音频完整性。
• 音频时长 ≥ 视频里需要口型的段落时长 → 时长没问题，再查别的（采样率、格式、源视频质量）。

一句话：口型崩了，先 ffprobe 对一下两边时长，别先调模型。

一步一步做

核心一条：保证驱动音频的时长完整，覆盖视频需要口型的整段，不要被裁剪。

1. 生成前先确认音频时长和视频时长：用 ffprobe 看一下两边各是多少秒。
2. 音频时长应≥ 视频里需要口型的段落时长，缺失部分口型会错位。
3. 如果发现音频被前面的流程（TTS 截断、转码压缩、格式转换）裁短了 → 回去修那个环节，把完整音频拿出来再用。
4. 不要为了省事手动把音频剪到很短再合成——短音频驱动长视频，很容易被拉伸 / 错位。

常见误区

• 误区 1：口型对不上 = 模型不行 / 源视频不好。 错。先查音频时长是不是被裁短了，这是音频驱动方案的命门。
• 误区 2：为了省事把音频剪得很短再合成。 短音频驱动长视频，很容易出现拉伸 / 错位，口型、脸部、音质一起受影响。
• 误区 3：源视频和配音各自没问题，就以为合成没问题。 问题恰恰出在"音频时长 vs 视频时长"的匹配上。
• 误区 4：忽略上游环节（TTS 截断、转码压缩）悄悄裁短了音频。 务必回溯取完整版。

交给 AI 助手时怎么说

"我用音频驱动口型的数字人（Musetalk / Wav2Lip / SadTalker 这类）生成视频，出现口型对不上、脸部变形、音频嘈杂。请帮我用 ffprobe 分别查看驱动音频和源视频的时长，判断是不是音频被裁短了；如果是，告诉我怎么回溯上游（TTS 是否截断、转码是否压缩）取完整音频重新合成。"

适用 · 通用判别式

判别要点：所有"音频驱动口型"的数字人，只要出现口型错位 / 脸部变形 / 音频嘈杂，第一怀疑音频时长 vs 视频时长不匹配，而不是模型参数或源视频质量。

• IF 音频时长明显短于视频口型段 → 高度怀疑口型错乱来自音频不完整，先修音频完整性。
• IF 音频被某环节裁剪过 → 用裁剪前的完整版本重新合成。
• 适用于 Musetalk / Wav2Lip / SadTalker 等所有音频驱动口型的数字人方案。

验收标准

• ✅ 用 ffprobe 确认：驱动音频时长 ≥ 视频中需要口型的段落时长。
• ✅ 改用完整时长音频（不再裁剪）重新合成后，口型与语音重新对齐、脸部变形消失、音频清晰。
• ✅ 回溯上游环节（TTS / 转码 / 格式转换），确认音频未被悄悄裁短。

本条截至发布日有效（音频驱动口型是这类方案的通用原理，长期稳定）。

现象

把一篇长文章（比如几千上万字的讲稿）一次性丢给 AI 配音，结果要么直接报错生成失败，要么"生成成功了"但听下来发现后半段内容没了——音频莫名其妙变短，结尾内容丢失。更坑的是有些接口不报错，直接静默裁剪，你以为成功了，其实交付的音频已经缺斤短两。

根因

关键认知：几乎所有 TTS 接口对"单次请求的文本长度"都有硬上限，超过就失败或被截断。

• 比如 MiniMax 等接口，单次请求文本上限常见在 10,000 字符左右（各家不同，以官方文档为准）。
• 你一篇 15,000 字的稿子整段塞进去 → 超限 → 要么报错，要么被悄悄截断。
• 静默截断最危险：没有报错提示，你以为成功了，实际交付的音频是残缺的。

先判断（动手前先确认）

TTS 处理长文本，凡是"失败"或"音频比预期短 / 内容缺失"，第一怀疑对象是超长被截断，而不是网络或模型问题。两个动作就能定性：

• 先算字数：len(text)，跟你所用接口的单次上限比一比。超了 → 基本确定会被接口拒绝、截断或要求分段。
• 看报错形态：直接报错 → 超限被拒；没报错但音频变短 → 大概率被静默裁剪，务必对一下"生成字数 vs 实际音频时长"。

一句话：长文本一次性塞必失败或残缺，先量长度，别赌一次成功。

一步一步做

生成前先量一下文本有多长，超限就分段，不要赌一次性成功。

1. 先算字数：len(text)。
2. 超过你所用接口的上限（查官方文档，常见 1 万字符左右）→ 主动切成几段，每段单独生成一个音频，最后拼接。
3. 切分时尽量在句号 / 段落处切，别从半句话中间切断，否则拼接处不自然。
4. 每段生成后核对：该段音频时长是否与文本长度匹配（防静默裁剪），缺失则补生成。

伪代码思路：

MAX = 10000  # 你所用接口的字符上限
if len(text) > MAX:
    chunks = split_at_sentence(text, MAX)  # 按句号切，每段不超 MAX
    audios = [tts(c) for c in chunks]
    final = concat(audios)
else:
    final = tts(text)

常见误区

• 误区 1：报错才叫失败，没报错就是成功。 错。静默截断不报错，交付的音频是缺斤短两的，必须核对时长。
• 误区 2：稿子整段塞最省事。 一超限要么报错要么截断，反而要返工，不如先分段。
• 误区 3：分段时从半句话中间切。 拼接处会断得突兀，要在句号 / 段落处切。
• 误区 4：只核对"生成成功"，不核对"音频时长 vs 文本长度"。 静默裁剪就这么漏过去了。

交给 AI 助手时怎么说

"我有一篇约 <字数> 字的讲稿要 AI 配音，用的 TTS 接口单次上限约 <上限字数> 字。请帮我写一段 Python：先 len(text) 判断是否超限，超限就按句号切成每段不超过上限的小段、逐段生成、最后拼接音频；并在每段生成后核对音频时长与文本长度是否匹配，以防静默截断。"

适用 · 通用判别式

判别要点：TTS 处理长文本时，凡是"失败"或"音频比预期短 / 内容缺失"，第一怀疑对象就是超长被截断，而不是网络或模型问题。

• IF 文本 > 接口字符上限 → 必须分段生成再拼接，别整段塞。
• IF 接口没报错但音频变短 → 大概率被静默裁剪，务必对一下"生成字数 vs 实际音频时长"。
• 适用于主流云 TTS 的批量配音、知识脚本生成、有声书制作 pipeline。

验收标准

• ✅ 加长度校验后，超长稿子不再被静默裁剪，而是被正确拦下并提示"分段生成"。
• ✅ 分段后每段音频内容完整，拼接处自然（在句号 / 段落处切分，没有半句断裂）。
• ✅ 每次生成后都核对"生成字数 vs 实际音频时长"，无内容缺失。

本条截至发布日有效（各 TTS 接口都有长度上限，具体数值以官方文档为准）。

现象

用 AI 配音（TTS）把文案转成语音，听下来总觉得"一顿一顿的"——每句话之间停特别久，整个音频拖沓、不连贯。明明文案读着挺顺，生成出来却像机器人一句一句往外蹦。更迷惑的是：同样一段话，只是换了个排版（比如把"一句一行"改成"一段连写"）重新生成，节奏居然差了一大截，停顿从十几秒缩到几秒。

根因

关键认知：TTS 引擎是按你文本里的"换行符"和"标点"来决定停顿时长的，不是按语义。 你以为只是排版好不好看，对引擎来说每个符号都是一条"停几秒"的指令：

• 换行符 \n：被当成"一句话结束"，产生长停顿（最狠的一个）。
• 句号 / 问号 / 感叹号：约 1.5–2 秒。
• 逗号：约 0.5–1 秒。
• 顿号：约 0.3–0.5 秒（最短）。

坑就在这：如果你习惯每写一句就敲回车（一句一行），6 个换行 = 累计约 12 秒的停顿堆在音频里。文案"看起来"很整齐，听起来却稀碎。

先判断（动手前先确认）

AI 配音出现"停顿过长 / 不连贯"，第一件事不是换模型、不是调参数，而是回去看文案的换行和标点。两个动作就能定性：

• 打开文案原文，看排版是不是"一句一行"（每句话后面都单独换行）。是 → 高概率命中本坑。
• 数一下换行符 \n 的数量。换行越密，累计停顿越长。

一句话：只要停顿怪，先查换行，别先怪模型。

一步一步做

记住一个排版原则：段落之间才空行，段落内部坚决不换行。

1. 段落和段落之间用空行（\n\n）隔开。
2. 段落内部一口气写完，不要每句一回车。
3. 冒号后面直接跟内容，不要再换行（很多人爱在"提示：\n"后换行，这就是停顿元凶）。
4. 并列的词用顿号代替逗号，节奏更紧凑（"苹果、香蕉、橘子"比"苹果，香蕉，橘子"快）。

如果想程序化批量优化，一句话搞定（把多余换行压成标点）：

optimized = raw_text.replace('\n\n', '。').replace('\n', '，')

改完后用新文案重新生成一遍 TTS，对比停顿时长。

常见误区

• 误区 1：停顿长 = 模型不好，换一个 TTS。 不一定。多数 TTS 都会受换行 / 标点影响，先改文案，再评估是否需要换引擎。
• 误区 2：文案一句一行更整齐、更好读，直接喂给 TTS。 看着整齐，听成稀碎。段内必须连写。
• 误区 3：冒号后面换行显得有条理。 换行 = 长停顿，冒号后直接跟内容才自然。
• 误区 4：把换行全删了。 过犹不及。段落之间还是要有空行区分层次，只是段内别换行。

交给 AI 助手时怎么说

"我有一段要 AI 配音的文案，生成出来停顿太长、一顿一顿的。请帮我按'段落之间空行、段落内部不换行、冒号后不换行、并列词用顿号'的规则重排这段文案，并给出一个 Python 一行命令把多余换行压成标点（\n\n→。，\n→，）。文案是：<贴你的文案>"

适用 · 通用判别式

判别要点：只要 AI 配音出现"停顿过长 / 不连贯"，第一件事不是换模型、不是调参数，而是回去看文案的换行和标点。

• IF 文案是"一句一行"的排版 → 改成"段落式"（段内不换行），停顿立竿见影变短变自然。
• IF 想要紧凑节奏 → 并列词用顿号、冒号后不换行。
• 适用于多数主流 TTS（MiniMax / 微软 / 阿里 / 字节等）、AI 配音、有声书制作、把 ASR 转写文本回炉做配音。

验收标准

• ✅ 同一份文案，从"一句一行"改成"段落式少换行"后，重新生成的音频停顿明显缩短（实测约从 12 秒降到 6 秒，更自然流畅）。
• ✅ 段落内部没有多余换行，冒号后直接跟内容；并列词用顿号、节奏紧凑。
• ✅ 整体听感连贯不拖沓，不再"一句一句往外蹦"。

本条截至发布日有效（标点 / 换行决定停顿是各 TTS 引擎的通用机制，长期稳定）。

现象

写了个 .bat 批处理脚本（比如一键启动某个程序），双击它，黑色命令行窗口"闪"一下就消失了，脚本根本没执行。你反复检查命令没写错，可就是跑不起来。用编辑器打开看内容明明好好的。

根因

关键认知：Windows 的 cmd 命令行对 .bat 文件有两个硬要求，现代编辑器默认都不满足。

1. 换行必须是 CRLF（\r\n），不能是 LF（\n）。

• 现在的编辑器（VSCode、各种代码工具）默认保存成 Unix 换行 LF。
• cmd 拿到 LF-only 的 .bat 会解析错乱，直接闪退。

1. 中文内容必须是 GBK 编码，不能是 UTF-8。

• cmd 默认用 936 代码页（GBK）。
• 编辑器默认存 UTF-8，cmd 读到中文就乱码/解析异常，也可能闪退。

两个坑任意一个都会让 .bat 双击秒退。

先判断（动手前先确认）

双击 .bat 黑框一闪就没，高频原因是换行或编码问题，也可能是命令本身报错。先做一步排除：

• 把 .bat 里的命令逐行复制到 cmd 窗口手动敲一遍：如果手动敲能正常跑 → 基本可以判断是文件保存格式（CRLF/GBK）的问题，跟命令本身无关。
• 看一眼编辑器右下角：换行是不是 LF？编码是不是 UTF-8？只要这两个里有一个不是 CRLF / GBK，就是元凶。

一句话：手动敲能跑、双击闪退 → 别改命令，去修换行和编码。

一步一步做

1. 把 .bat 里的命令行整理成一个列表（Python 的 lines），方便一次性生成。
2. 用 Python 强制 GBK 编码 + CRLF 换行重新生成，覆盖原文件：

lines = [
       "@echo off",
       "echo 正在启动...",
       "node 你的程序.js",
       "pause",
   ]
   content = ('\r\n'.join(lines) + '\r\n').encode('gbk')
   open('启动.bat', 'wb').write(content)

1. 抓两个关键点：'\r\n'.join(...) 让每行用 CRLF 换行；.encode('gbk') 让中文按 GBK 编码，wb 二进制写入（别用文本模式，否则又会被改回）。
2. 双击重新生成的 .bat，黑框应正常停留、命令执行、中文不乱码。
3. 不想写代码 → 在编辑器里手动把换行改 CRLF、编码改 GBK/GB2312 再保存（容易忘、下次保存又被打回，不推荐）。

常见误区

• 误区 1：双击闪退 = 命令写错了。 错。cmd 解析 LF-only 的 .bat 本身就会错乱闪退，跟命令对错无关；先手动敲验证命令。
• 误区 2：只改了换行没看编码。 换行要用 CRLF；如果脚本里有中文，再确认编码用 GBK/GB2312，避免 cmd 乱码。
• 误区 3：存成 UTF-8 with BOM。 cmd 读 BOM 头也会出问题，要的是纯 GBK。
• 误区 4：用编辑器手动改一次就万事大吉。 下次再用编辑器保存，换行/编码又被打回 LF/UTF-8。用脚本生成最稳，一劳永逸。

交给 AI 助手时怎么说

"我写了个 Windows .bat 脚本，双击黑框一闪就退、没执行。命令内容是这几行：<粘贴每行命令>。请用 Python 帮我生成一个强制 GBK 编码 + CRLF 换行的版本（wb 二进制写入覆盖原文件），保证中文不乱码、能正常双击运行。"

适用 · 通用判别式

判别要点：Windows 下双击 .bat 黑框一闪就没，常见原因是换行（LF vs CRLF）或编码（UTF-8 vs GBK）问题，但仍要先排除命令本身报错。

• IF .bat 双击闪退 → 先手动敲命令验证无误，再去检查换行是不是 CRLF、中文是不是 GBK。
• IF 不确定 → 直接用上面的 Python 片段重新生成一遍，覆盖原文件，通常立刻好转。
• 适用于所有给 Windows 双击运行的 .bat 启动脚本。

验收标准

• ✅ 双击 .bat 不再闪退，黑框正常停留并执行命令。
• ✅ 末尾 pause 让窗口停住，能看清输出。
• ✅ 有中文 echo 时内容不乱码。
• ✅ 文件换行为 CRLF；有中文时编码为 GBK/GB2312（编辑器右下角或 file 命令可辅助确认）。

现象

你改了某个服务的配置，或者装了东西要求"重启生效"，于是关机、再开机。结果发现：服务还是老样子、配置没读进去、问题依旧。你以为重启没用，甚至怀疑是配置写错了，反复折腾。查一下系统的"上次启动时间"，居然还是好几天前——根本没更新。

根因

关键认知：Windows 8 以后的"关机再开机"，其实不是真正的重启，而是"混合休眠"。

• Windows 默认开着快速启动（Fast Startup）。
• 你点"关机"，系统把内核状态写到硬盘（hiberfil.sys），开机时恢复这个状态，而不是从头启动。
• 所以"上次启动时间"不更新、服务进程状态基本保留、配置不会被重新读取。
• 只有"重启"（Restart）才是真正意义上的关机再开。

简单说：关机再开 ≈ 睡一觉醒来接着干；重启 ≈ 彻底重新开始。 它俩对系统来说不是一回事。

先判断（动手前先确认）

"重启后该生效却没生效"，先怀疑根本没真重启，而不是配置或软件问题。一条命令就能定性——查上次启动时间有没有更新到"刚才"：

(Get-CimInstance Win32_OperatingSystem).LastBootUpTime

• 这个时间还是几天前 → 你做的是"关机再开"（快速启动 = 混合休眠），不是真重启，服务/配置当然没刷新。
• 这个时间已经更新成刚刚 → 确实真重启了，那问题就另查（配置路径、服务是否读取了新配置）。

一句话：先看 LastBootUpTime 有没有更新，没更新就是快速启动的锅。

一步一步做

1. 查 LastBootUpTime（上面命令），确认系统到底有没有真启动过。
2. 若没更新 → 做真正的重启：开始菜单点"重启"（不是"关机"），或命令行执行：

shutdown /r /f /t 0

（/r = 重启，/s 才是快速启动式关机，别搞混。）

1. 如果不想重启整台机器，只想刷新某一个服务：用管理员 PowerShell 执行 Restart-Service <服务名>（需要管理员权限）。
2. 想一劳永逸关掉快速启动：控制面板 → 电源选项 → 选择电源按钮的功能 → 更改当前不可用的设置 → 取消勾选"启用快速启动"。之后关机再开就是真重启了。
3. 重启后再查一次 LastBootUpTime，应已更新为当前时间，服务/配置随即生效。

常见误区

• 误区 1：关机再开 = 重启。 错。快速启动下，关机再开 ≈ 休眠唤醒，内核状态保留，服务/配置不会重读。
• 误区 2：重启没用 → 怀疑配置写错，反复改配置。 其实是根本没真重启，配置再改也白搭，先确认 LastBootUpTime。
• 误区 3：以为关掉快速启动很麻烦。 其实控制面板几下就能关，关完一劳永逸。
• 误区 4：装了要求"重启生效"的东西，点了关机就走人。 回来发现没生效，又重装一遍，其实是休眠唤醒，白折腾。

交给 AI 助手时怎么说

"我在 Windows 上改了 <服务/配置名> 的配置，按要求重启后没生效。请帮我用 PowerShell 查 LastBootUpTime 确认到底有没有真的重启，并告诉我怎么真正重启（shutdown /r）或只刷新这一个服务（Restart-Service），以及怎么永久关掉快速启动。"

适用 · 通用判别式

判别要点：凡是"重启后应该生效却没生效"，先怀疑根本没真重启（快速启动捣鬼），而不是配置或软件问题。

• IF 服务表现"像没重启"（配置没重读/进程没换）→ 查 (Get-CimInstance Win32_OperatingSystem).LastBootUpTime 是否更新到当前时间。没更新 = 快速启动，你只是休眠唤醒了。
• 修复：用"重启"命令或关掉快速启动。
• 适用于所有 Windows 服务/进程需要"重启后生效"的场景（NSSM 服务、配置重读、自启动项等）。

验收标准

• ✅ LastBootUpTime 更新为本次重启的时间（不再是几天前）。
• ✅ 服务的配置被正确重新读取，新配置生效、问题消失。
• ✅（关掉快速启动后）之后每次"关机再开"都等同于真重启，不再出现"重启没生效"。

现象

电脑用着用着突然画面冻结、鼠标键盘全无反应，只能长按电源键强制断电重启。而且会反复发作。第一反应往往是："是不是 CPU 坏了？内存条故障？电源不行？过热？"于是跑去跑内存诊断、换驱动、刷 BIOS，折腾一圈没用。

根因

关键认知：这类"硬死机"（无蓝屏、只能断电）里，内存耗尽是很常见、也最值得先排查的原因之一。

典型元凶（尤其在装了一堆 AI 工具的电脑上）：

• 多个 AI 工具客户端各自启动一份后台服务，会话异常退出留下"孤儿进程"，实例越堆越多，每个吃 GB 级内存。
• WSL2（装 Docker/Linux 子系统才有）在部分配置下会占用大量主机内存，释放也可能不及时。
• 各种开发工具的后台守护进程（如 gradle、语言服务器），即使你没在用对应项目也常驻吃内存。
• 几个加起来，32GB 内存也能被吃光 → 桌面合成器崩溃 → 系统服务连锁崩溃 → 硬锁死。

先判断（动手前先确认）

第一步建议先做"定性"：先区分硬件证据和内存耗尽证据，别盲目送修。 硬件故障通常会留下一些线索，先排三项：

• 蓝屏了没？ 看 C:\Windows\Minidump\ 有没有 minidump 文件（有 = 真蓝屏）。
• 显卡崩了没？ 事件查看器有没有 TDR 错误（Event 4101）。
• CPU/内存/PCIe 报硬件错没？ 有没有 WHEA 错误。

三项全没有 → 硬件故障概率下降，转去查内存耗尽。一句话：无蓝屏的硬死机，先查内存，别急着判硬件、别急着送修。

一步一步做

1. 先排硬件三项：蓝屏 minidump（C:\Windows\Minidump\ 是否空）、显卡 TDR（Event 4101）、WHEA 硬件错误。
2. 三项全无 → 查内存耗尽诊断（这条命令会直接点名是谁吃了最多内存）：

Get-WinEvent -FilterHashtable @{LogName='System'; ProviderName='Microsoft-Windows-Resource-Exhaustion-Detector'} -MaxEvents 4 | Format-List TimeCreated,Message

事件 ID 2004 = 内存耗尽诊断，消息里会直接写出"某某进程占了多少字节"，一眼定位元凶。

1. 按 Event 2004 点名的进程，关掉或限制它（限 WSL2 内存、卸载不用的语言服务器扩展、给开发工具限内存）。
2. 装个内存看门狗（可用内存低于阈值时告警 / 自动清理大进程），防止再次悄悄吃满。
3. 治本：让后台服务改成"一个进程服务多个客户端"的形态，别每个客户端各起一份、留孤儿进程。

常见误区

• 误区 1：硬死机 = 硬件坏了。 不一定。无蓝屏的硬死机很常见的原因是内存被吃光，先排硬件三项再下结论。
• 误区 2：一上来就跑内存诊断、换驱动、刷 BIOS。 先查 Event 2004，一条命令就能定性是不是内存耗尽，省得白折腾。
• 误区 3：只加内存条治标。 根因是后台进程累积（孤儿进程、WSL2 占半内存不还），不清理源头，加了条子还会再满。
• 误区 4：忽略 WSL2。 WSL2 在部分配置下会占用大量内存且释放不及时，开 Docker/Linux 子系统的人尤其要检查并按需限内存。

交给 AI 助手时怎么说

"我的 Windows 电脑经常硬死机（画面冻结、鼠标键盘无反应，只能断电重启），没有蓝屏。装了不少 AI 工具和 Docker/WSL2。请帮我用 PowerShell 先排除硬件故障（查 C:\Windows\Minidump\ 蓝屏、显卡 TDR、WHEA 错误），再查 Event 2004 内存耗尽诊断，定位是哪个进程吃满了内存，并给出限制 WSL2 内存和清理后台孤儿进程的具体办法。"

适用 · 通用判别式

判别要点：电脑硬死机（无蓝屏、强制断电才恢复），先查内存耗尽（Event 2004），别急着判硬件。

• IF 没有蓝屏 minidump + 没有显卡 TDR + 没有 WHEA 硬件错 + 有 Event 2004 → 高度怀疑内存耗尽，硬件故障概率下降。
• IF Event 2004 点名了某进程 → 那个进程就是元凶，限流或关掉。
• 适用于所有"电脑死机/卡死"排查；尤其是装了多个 AI 工具、Docker/WSL2、开发工具的机器。

验收标准

• ✅ 硬件三项（蓝屏 minidump / 显卡 TDR / WHEA）均无异常。
• ✅ Event 2004 定位到具体吃内存进程，并已关掉或限制。
• ✅ 开发负载下内存占用稳定在 90% 以下。
• ✅ 一段时间内（如连续几天正常使用）硬死机不再复发。

现象

你用代码（Python 的 openai SDK / httpx）调用国内的大模型接口（智谱 GLM、通义、百度等，服务器都在国内，本来该很快），结果一次调用要等好几分钟，甚至等到连接超时被中断。但你用命令行 curl 直接调同一个接口，明明是秒回的。代码里也没设奇怪的超时，就是莫名其妙地慢。

根因

关键认知：openai SDK 底层用 httpx，httpx 默认会读系统的代理环境变量（HTTP_PROXY / HTTPS_PROXY）。

• 如果你的程序跑在一个设了系统代理的环境里（比如 Windows 上开着科学上网、或者程序作为服务继承了系统环境变量）。
• httpx 默认 trust_env=True，会乖乖地把请求绕到系统代理去。
• 而国内大模型接口本来直连最快，被强制绕去代理（尤其代理是给翻墙用的）→ 绕远路、甚至超时。
• curl 快是因为它对国内地址没走代理；你的代码慢是因为 httpx 偷偷走了代理。

换句话说：不是大模型慢，是你的请求被系统代理"绑架"去绕了一圈。

先判断（动手前先确认）

用 openai / httpx SDK 调国内大模型，凡是"代码慢、curl 快"，第一怀疑是被系统代理绕路。两个动作定性：

• 同一个接口，命令行 curl 秒回、代码里要等几分钟 → 锁定代理绕路。
• 看程序运行环境是否设了系统代理：Windows 上开着科学上网、或程序作为服务 / 容器继承了 HTTP_PROXY / HTTPS_PROXY 环境变量。

一句话：curl 快、SDK 慢，先查 httpx 是不是偷偷走了系统代理。

一步一步做

一行代码解决：让 httpx 忽略系统代理、直连国内大模型接口。

import os
import httpx
from openai import OpenAI

# 关键：trust_env=False → 不读系统代理，直连
http_client = httpx.Client(trust_env=False, timeout=60.0)
client = OpenAI(
    api_key=os.environ["MODEL_API_KEY"],  # 密钥只放本机环境变量，示例不写明文
    base_url="https://open.bigmodel.com/api/paas/v4",  # 以智谱为例
    http_client=http_client,
)

两个要点：

• httpx.Client(trust_env=False) → 忽略系统代理环境变量，直连。
• 顺手设 timeout=60.0（SDK 默认 600 秒，太长了），避免卡死干等。

常见误区

• 误区 1：代码慢 = 大模型接口慢 / 网络差。 错。curl 秒回说明接口很快，是 httpx 绕了代理。
• 误区 2：设了系统代理就以为只影响翻墙流量。 httpx 默认 trust_env=True，会把国内请求也绕去代理。
• 误区 3：只加 timeout 治标。 timeout 只能让你早点失败，根因是绕路，要 trust_env=False 直连。
• 误区 4：以为 openai SDK 不读环境变量。 它底层用 httpx，httpx 默认读，所以会被代理绑架。

交给 AI 助手时怎么说

"我用 Python 的 openai SDK（底层 httpx）调用国内大模型接口，一次调用要等好几分钟甚至超时，但命令行 curl 同一个接口是秒回。程序跑在 <带系统代理的 Windows / 服务 / 容器>。请帮我写一段代码：用 httpx.Client(trust_env=False, timeout=60.0) 忽略系统代理直连，传给 OpenAI(http_client=...)，并解释为什么 curl 快而 SDK 慢。"

适用 · 通用判别式

判别要点：用 openai / httpx SDK 调国内大模型，凡是"代码慢、curl 快"，第一怀疑被系统代理绕路。

• IF 程序跑在带系统代理的环境（Windows 服务、容器、开了代理的开发机）→ httpx 默认走代理 → 国内接口被绕远。
• 修复：httpx.Client(trust_env=False) 直连；如果根因确实是系统代理绕路，通常会明显变快。
• 适用于使用 openai SDK / httpx 且继承系统代理的国内 LLM 调用，尤其是程序作为 Windows 服务 / 容器运行的场景。

验收标准

• ✅ 设 trust_env=False 后，调用时长从分钟级降到秒 / 十几秒级（实测约从 357 秒降到 25 秒），无超时 drop。
• ✅ 顺手设了合理的 timeout（如 60 秒），不再卡死干等。
• ✅ 国内大模型接口直连，不再被系统代理绕远路（curl 与 SDK 速度对齐）。

本条截至发布日有效（httpx 默认 trust_env=True 是其长期行为）。

现象

你在某个 AI 编程工具里配置了自己的大模型（比如想用智谱 GLM 的套餐，便宜），结果出现怪事：要么配置完根本看不到自己加的模型；要么看到了但用的是工具内置的那个（走的是工具官方额度，不是你买的套餐，钱白花）；要么一调用上游就报"模型不存在"。明明填得没错，就是拧不到一起去。

根因

关键认知：这类问题往往是三个条件叠加造成的死结，工具配置层怎么调都解不开：

1. 工具把你填的"模型 id"直接当成 API 请求里的 model 名发出去，没有"id 不等于 API 名"的映射机制。
2. 工具的云端已经内置了一个同名的模型 id（比如内置名叫 <套餐方精确模型名>），优先级还高于你自定义的——你自定义的同名 id 会被云端压制。
3. 你的模型套餐方只认精确的 model 名（比如只认 <套餐方精确模型名>，你填个 <随手改的显示名> 它就说"模型不存在"）。

三者一对：id 不能跟内置重名（否则被压制），但又必须发套餐方认的精确名（否则报不存在）——矛盾，配置层无解。

先判断（动手前先确认）

在 AI 工具里配自定义大模型，凡是"看不到 / 看到内置的 / 走错额度 / 上游报模型不存在"，先查这四问：

• 工具是不是把"显示 id"直接当 API model 名发出去？（是 → 易撞名）
• 云端是否已经内置了同名 id？（是 → 你被压制，优先级低于内置）
• 套餐方是否只认精确 model 名？（是 → 你不能随便改名）
• 套餐 key 是不是直接填在工具配置里？（是 → 安全风险，应只放本地）

前三个同时命中 → 配置层无解，直接上本地中转，别在配置里死磕。

一步一步做

破解办法是加一层本地中转，把矛盾转移到中转层解决：

1. 写一个零依赖的本地中转脚本（Node / Python 都行），监听一个只在本机访问的中转地址（文档里写 <你的本机中转地址> 占位，不写真实端口）。
2. 工具里自定义模型 id 起个不跟内置重名的名字（比如 <不重名的显示ID>），URL 指向 <你的本机中转地址>。
3. 中转脚本收到请求后，把 model 名改写回套餐方认的精确名（<套餐方精确模型名>），注入只保存在本地的套餐 key，再转发给套餐方，结果原样流式返回。
4. 套餐 key 只写在本地中转脚本或本机环境变量里，工具的配置里用占位符（local-proxy 之类）。

这样：工具看到的是不重名的 id（不被压制），套餐方收到的是精确名（不报错），key 只留在本机中转层（安全）。

中转脚本核心逻辑（示意，key、地址与端口都用占位符，换成你自己的）：

# 仅示意：收到工具请求 → 改写 model 名 → 注入本地套餐 key → 转发 → 流式返回
LOCAL_KEY  = "<你的套餐KEY占位符>"        # 只放本机脚本或环境变量，不上传到工具配置
REAL_MODEL = "<套餐方精确模型名>"         # 套餐方认的精确名
UPSTREAM   = "https://<套餐方域名>/v1"    # 套餐方真实地址

def handle(request):
    request["model"] = REAL_MODEL        # 把显示 ID 改回套餐方精确模型名
    request.headers["Authorization"] = "Bearer " + LOCAL_KEY
    return stream_forward(UPSTREAM, request)  # 原样流式返回

常见误区

• 误区 1：在工具配置层反复改 id / 改 key 想绕过去。 三个条件叠加时配置层无解，越改越乱，直接上本地中转。
• 误区 2：自定义 id 跟内置同名，以为"我填了就用我的"。 内置优先级更高，你被压制，走的是工具官方额度，钱白花。
• 误区 3：套餐 key 直接填进工具配置。 一旦配置同步到云端或泄露，key 就裸奔，应只放本地中转脚本或本机环境变量。
• 误区 4：改写 model 名时没改回套餐方认的精确名。 套餐方只认精确名，发错就报"模型不存在"。

交给 AI 助手时怎么说

"我在 AI 编程工具里配自定义大模型，出现 <看不到 / 看到内置 / 走错额度 / 上游报模型不存在>。套餐方只认精确 model 名 <精确名>，但工具云端已内置同名 id 会压制我。请帮我写一个零依赖的本地中转脚本（Python / Node）：监听 <你的本机中转地址>，把工具发来的 model 名改写回 <精确名>，注入本地套餐 key（只放本机脚本或环境变量里），转发到套餐方并原样流式返回；并告诉我工具里自定义 id 起什么不重名的名字、URL 怎么填。"

适用 · 通用判别式

判别要点：在 AI 工具里配自定义大模型，凡是"看不到 / 看到内置的 / 走错额度 / 上游报模型不存在"，先查这四问：

• 工具是不是把"显示 id"直接当"API model 名"发？（是 → 易撞名）
• 云端是否内置了同名 id？（是 → 你被压制）
• 套餐方是否只认精确 model 名？（是 → 你不能随便改名）
• 四问同时命中 → 配置层无解，直接上本地中转，别在配置里死磕。

适用于所有"AI 工具接自定义 / 第三方大模型"撞内置 id 的场景。

验收标准

• ✅ 工具里能正常选到自己配置的、不重名的模型 id（不再被内置压制）。
• ✅ 调用走的是自己套餐的额度（不再走工具官方额度，钱没白花）。
• ✅ 上游不再报"模型不存在"，model 名被中转层正确改写回套餐方认的精确名。
• ✅ 套餐 key 只存在于本地中转脚本或本机环境变量，工具配置里是占位符。

本条截至发布日有效（各工具的模型配置机制会迭代，核心判别式长期适用）。