🩺 8.14 手搓 Agent 常见问题与故障排查指南 (Troubleshooting & FAQ)

“在成为造物主的路上，调试与排障是智能体进化的必经之路。”
当我们亲手撕开大模型框架的黑盒、一行行手搓 Agent 时，可能会遇到各种网络假死、界面错乱、权限拦截或环境冲突问题。别慌！本手册为你梳理了 8.1 ~ 8.13 全流程最常见的疑难杂症与实战避坑指南，带你从“一脸懵圈”到“秒级定位”。

🚑 5 秒急救自检树 (Quick Decision Tree)

当你遇到任何异常情况时，请先对照下方故障自检决策树，快速定位问题根源：

🚨 专题一：很久没反应怎么办？（卡死、转圈、假死无回包）

💡 生活化比喻

这就好比你在餐厅点了外卖等了半小时没动静：
到底是 “大厨在慢工出细活（深度思考）”？
还是 “外卖小哥被暴雨堵在路上了（网络超时/代理阻断）”？
还是 “你的账户余额不足店家没接单（欠费/Key失效）”？
亦或是 “小区保安死守大门非要你报暗号才放行（权限门禁在后台等终端输入）”？

🔍 深度归因与逐项排查

1. 原因 A：模型开启了「🧠 深度思考」或正在执行「多步工具调用/子代理协作」

排查依据：
- 在 8.13 个人 Mini-Agent 中勾选了 “🧠 深度思考”；
- 或者是运行 8.10 Subagents 多智能体（4 个专家串行流转）或 8.2 ReAct 循环（多步反复搜索）。
底层原理：
- 深度思考模型（如 GLM / DeepSeek 推理模式）会在输出答案前生成数千 Token 的隐式思维链（Chain-of-Thought），在大脑内部推演规划，耗时通常在 10~30 秒；
- 同样，Subagents 需要依次调用“搜索专家 ➔ 代码专家 ➔ 评测专家 ➔ 总结主厨”，总用时等于 4 次 LLM 调用的总和。
解决方案：
- CLI 端：--repl 模式的每个动作都会实时打印状态行（🤔 模型思考中 → ⚙️ 调用工具 → 🛡️ 权限门禁 → 🏁 完成），一眼看到卡在哪步；
- Web 端：展开右侧 “📡 实时状态时间线” 或底部 “🔍 决策流与权限门禁审计 Trace” 面板，观察 Agent 当前处于哪一步；
- 调试阶段若追求极速响应，可在 8.13 界面中取消勾选“🧠 深度思考”，切换为极速直出模式。

2. 原因 B：触发了权限安全门禁（HITL），后台终端正在等待人类审批 `[y/N]`

排查依据：
- 运行了 s06_permissions_hitl.py、s05_terminal_and_edit.py，或在 Agent 中触发了高危指令（如修改系统文件、执行终端命令）；
- 网页界面一直在转圈，没有任何报错。
底层原理：
- 在第 8.6 节中，我们手搓了 PermissionGuard 风险门禁。当遇到中高风险操作（如 str_replace 修改代码、执行未在白名单的 Bash 命令）时，代码会调用原生 input("⚠️ 是否允许执行？[y/N]: ") 阻塞主线程，等待人类审批。
解决方案：
- 切回到你的命令行终端窗口，查看是否有黄色拦截提示；
- 在终端中输入 y 并按回车，Agent 会立即解除挂起，继续向前执行。

3. 原因 C：本地开启了全局科学上网代理 (VPN / Clash)，导致国内 API 网关被绕路或阻断

排查依据：
- 终端运行脚本报错 ConnectTimeout、ReadTimeout、SSLError，或没有任何输出长达 60 秒后抛出 APIConnectionError。
底层原理：
- 智谱 BigModel API（open.bigmodel.cn）服务器部署在中国大陆国内机房。如果你的电脑开启了全局科学上网代理（Global Proxy），请求会被强制绕道境外节点再尝试访问国内，极易触发网络握手超时、证书阻断或直接被节点拒接。
解决方案：
- 测试连通性：在终端执行：
  bash
```
curl -I https://open.bigmodel.cn/api/paas/v4/chat/completions
```
  若返回 HTTP/1.1 401 Unauthorized 或 405 Method Not Allowed 即代表网络通畅；若一直无响应卡住，则证明被代理阻断。
- 代理设置规则：将代理软件切换为 “规则模式 (Rule)”，并将 *.bigmodel.cn、*.volces.com 加入DIRECT 直连白名单。

4. 原因 D：API Key 欠费、未生效或单秒请求超限 (RateLimit 429)

排查依据：
- 控制台输出包含 429 Too Many Requests 或 Insufficient Balance。
解决方案：
- 登录智谱 BigModel 开放平台控制台，检查账户余额与实名认证状态；
- 在 .env 中配置备用灾备 Key（如火山方舟 ARK_API_KEY），ZhipuGLMClient 会在主力接口异常时自动无缝降级。

5. 原因 E：极速验证最小连通性脚本

当你搞不清楚到底卡在哪一步时，不要先跑复杂的 Web 工作台，先跑 8.1 的 10 行最小原生测试：

bash

cd 08_手搓Agent/code
uv run python s01_env_setup.py

如果 1 秒内能看到终端彩色打字机逐字吐出 Token，说明模型与网络基建 100% 正常，问题仅在具体交互逻辑或输入参数上。

🎨 专题二：打开 `app.py` 排版很乱（文字挤压、重叠、三栏变一栏）

💡 生活化比喻

这就好比把一台“三开门豪华大冰箱”硬塞进 10 平米的单身公寓：
我们的工作台是按照现代专业 IDE（如 VS Code / Cursor）的 「左侧导航 + 中间源码 + 右侧沙箱」 三栏宽屏标准精心调教的；
如果你的屏幕太小（如 13 寸小屏轻薄本），或者浏览器默认把网页放大了 125%~150%，页面宽度放不下三栏，浏览器就会把它们强行折叠、挤压变形。

🔍 深度归因与快速处理

1. 核心原因 1：浏览器缩放比例过大或屏幕物理分辨率有限

根因说明：
- app.py 内部采用了高沉浸感的 gr.Row() 响应式三栏布局（Sidebar: 2 + CodeViewer: 5 + Playground: 5），并设置了固定对齐高度 height: 740px。
- 当屏幕宽度低于 1280px（或系统开启了 125%/150% 缩放导致逻辑像素不足）时，CSS 布局会自动触发保底流式换行，导致界面看起来挤压重叠。
🚀 1 秒恢复完整布局：
- 缩放浏览器：在浏览器页面中按下 Cmd + - (Mac) 或 Ctrl + - (Windows)，将页面缩放调整为 80% ~ 90%；
- 窗口最大化：双击浏览器顶部标题栏全屏放大窗口；
- 按下 Cmd + 0 / Ctrl + 0 可随时恢复默认 100% 比例。

2. 核心原因 2：第三方暗黑模式扩展（如 Dark Reader）色彩冲突

根因说明：
- 工作台的源码视窗采用了标准的 Pygments OneDark 极客黑配色，而右侧沙箱卡片采用了明晰高对比度的浅色卡片。
- 如果浏览器安装了 Dark Reader、Super Dark Mode 等插件，插件会强行反转所有颜色，把深色背景的代码文字也反色为深灰色，导致“黑底黑字”或“白底白字”无法看清。
解决方案：
- 点击浏览器右上角扩展栏的 Dark Reader 图标；
- 点击开关，将 http://127.0.0.1:7860 或 localhost 加入禁用名单 (Disable for this site)。

3. 核心原因 3：浏览器缓存了旧版本 CSS 样式

解决方案：
- 强制清除缓存硬刷新：
  - Mac 用户：按下 Cmd + Shift + R；
  - Windows / Linux 用户：按下 Ctrl + F5。

4. 🛠️ 进阶：小屏轻薄本适配（自定义 CSS 响应式微调）

如果你日常使用的是 13 寸轻薄本，希望页面更紧凑，可以直接在 app.py 中微调两处参数：

调小视窗固定高度：将 custom_css 中的 height: 740px 调整为 height: 620px；
调整导航栏宽度：将 Column(scale=2, min_width=200) 中的 min_width=200 调整为 min_width=160。

🛠️ 专题三：环境依赖与 Python 解释器常见报错

1. 报错 `ModuleNotFoundError: No module named 'openai'` / `'gradio'` / `'rich'`

bash

# ❌ 错误现场：
Traceback (most recent call last):
  File "app.py", line 19, in <module>
    import gradio as gr
ModuleNotFoundError: No module named 'gradio'

根因：直接使用了操作系统全局的 Python（如系统自带的 Python 3.9/3.10），而没有进入由 uv 管理的 .venv 虚拟环境。

正解（二选一）：

方案 1（极力推荐）：使用 uv run 免手动激活虚拟环境：

bash

cd 08_手搓Agent/code
uv sync                   # 安装全部依赖到 .venv
uv run python app.py      # 由 uv 自动加载 .venv 环境

方案 2（传统手动激活）：

bash

# macOS / Linux
source .venv/bin/activate
python app.py

# Windows PowerShell
.venv\Scripts\Activate.ps1
python app.py

2. VS Code / Trae 编辑器中代码整页黄色波浪线标红

根因：IDE 默认将解释器关联到了系统全局 Python，未能识别到 08_手搓Agent/code/.venv。
快速修复：
1. 在编辑器中按下快捷键 Cmd + Shift + P (Mac) 或 Ctrl + Shift + P (Win) 打开命令面板；
2. 搜索并点击 Python: Select Interpreter (选择解释器)；
3. 选择 ./.venv/bin/python（或点击“输入解释器路径”浏览选中 08_手搓Agent/code/.venv/bin/python）；
4. 瞬间所有模块标红与警告全部消失！

🔑 专题四：环境变量与 API Key 配置避坑指南

1. 报错 `AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API Key'}}`

排查自检清单：
- [ ] 是否创建了 .env 文件？ 检查 08_手搓Agent/code 目录下是否存在 .env 文件（注意不是 .env.example，需要通过 cp .env.example .env 复制生成）。
- [ ] Key 字符串两端是否有多余空格或单双引号？
  bash
```
# ❌ 错误写法 (带有多余引号或空格)：
ZHIPU_API_KEY=" 68abc123.xyz456 "

# ✅ 正确写法 (纯文本直接赋值)：
ZHIPU_API_KEY=68abc123.xyz456
```
- [ ] Key 格式是否正确？ 智谱 BigModel 的标准 API Key 通常是由一段数字字母加英文点号组成的哈希值（例如 xxxxxxxxxxxx.yyyyyyyyyyyy）。

2. 跨厂商灾备机制（智谱 GLM-5.3-Flash + 火山方舟 DeepSeek-V4-Flash）

在第 8.1 节手搓的 ZhipuGLMClient 中，我们设计了工业级双引擎跨厂商灾备架构：

配置方法：在 .env 中同时填入智谱 Key 与火山方舟 Key：
ini
```
# 主力引擎
ZHIPU_API_KEY=你的智谱APIKey
ZHIPU_MODEL=glm-5.3-flash

# 灾备引擎
ARK_API_KEY=你的火山方舟APIKey
ARK_FALLBACK_MODEL=deepseek-v4-flash
```
这样即使遇到智谱机房网络波动，你的 Agent 也能自动切换到备用模型继续工作，绝不宕机。

💻 专题五：终端执行 (8.5) 与权限门禁 (8.6) 跨平台疑难

1. Windows 环境下运行 `s05_terminal_and_edit.py` 提示 `FileNotFoundError: 'ls' is not recognized`

根因：run_bash 模块底层默认调用了 POSIX 标准终端命令（如 ls、pwd、cat、grep）。Windows 系统默认命令解释器为 cmd.exe 或 PowerShell，命令语法与 Linux 存在差异。
解决方案：
- 推荐方式：在 Windows 终端（Windows Terminal）中使用 Git Bash 或 WSL2 (Ubuntu) 运行代码；
- 原生 PowerShell 替代：在 Windows 原生环境中，可将测试 Prompt 中的 ls -la 替换为 dir 或 Get-ChildItem。

2. 精准行替换 `str_replace` 报错：“未找到精确匹配的代码行”

根因：
- str_replace 是借鉴 Claude Code 的精密手术刀式代码编辑工具，要求 old_str 必须与目标文件中的内容 100% 严格一致（包括每一处空格缩进与换行符）；
- Windows 环境换行符为 \r\n (CRLF)，而 macOS / Linux 为 \n (LF)，跨平台剪切板复制时可能会混入不可见换行符。
解决方案：
- 确保编辑代码前，先通过 view_file 读取目标文件的真实内容并带行号对照；
- 在 s05_terminal_and_edit.py 的实现中，我们已加入了 .replace('\r\n', '\n') 自动归一化清洗逻辑。

🗜️ 专题六：上下文压缩 (8.8) 与记忆持久化 (8.9) 常见疑难

1. 为什么在 8.8 工作台中点击“压缩”后，Token 数量没有变化？

根因：
- 在 s08_context_compact.py 中，我们设计了防抖阈值保护。如果当前对话历史的总 Token 数尚未超过设定的安全阈值（例如低于 1000 Token），系统判定无需浪费算力进行压缩，会直接跳过。
体验方法：
- 在 8.8 工作台中点击预设按钮 “📦 注入超长对话测试用例 (模拟 20 轮代码调试)”；
- 注入后消息达到 3000+ Token，此时点击 “🗜️ 触发 /compact 深度提炼”，即可瞬间看到 Token 从 3000+ 骤降至 300~500，且关键上下文无损保留。

2. 长期记忆文件 `gradio_agent_memory.json` 报错或数据混乱如何重置？

根因：多次并发调试或手动修改 JSON 文件导致格式损坏（JSONDecodeError）。
快速重置：
- 直接删除该本地文件即可，系统在下一次对话时会自动重新初始化：
  bash
```
rm -f gradio_agent_memory.json
```

3. 8.9 技能勾选项是空的，或勾了名字却拼不进 Prompt

根因：工作台扫描的是 08_手搓Agent/code/skills/*.md。旧版仓库这个目录是空的，界面勾选项就是空列表；更糟的是 8.13 曾经把 git_expert / python_cleaner 写死在复选框上，勾了也加载不到正文。
现在怎么处理：
- 仓库自带 code/skills/git_expert.md 与 code/skills/python_cleaner.md；
- SkillLoader 按脚本所在目录解析相对路径，从任意 cwd 启动 app.py 都能扫到；
- 勾选项来自 list_skills()，自己再丢一个 .md 进去，刷新页面即可。
零 Key 验收：uv run python -m unittest discover -s tests -v 里的 SkillPackTests 会断言这两个包能被扫到。

4. 没配 API Key 时，单独跑 `s02` / `s03` / `s04` / `s10` / `s13` 会不会红屏 Traceback？

不会。本地纯函数 / Mock 段会先跑完；需要真实模型的后半段会打印 ⚠️ 真实引擎自测跳过 后正常退出。s13_mini_agent.py 没 Key 时直接提示去填 .env，并建议先跑单元测试。
真正要对话、ReAct、Function Calling，仍然必须在 .env 里填 ZHIPU_API_KEY。

👥 专题七：Subagents 协作 (8.10) 与 Mini-Agent (8.13) 进阶疑难

1. Subagents 多智能体流水线执行耗时较长（约 20~40 秒）

现象分析：
- 子代理不再另套一层更短的线程闸门。超时和灾备都交给 ZhipuGLMClient（HTTP 默认 60 秒，环境变量 TIMEOUT_SECONDS）。旧版写死 30 秒时，带思考的真实模型经常被掐成「该阶段已跳过」，终稿是空的。
- 在 8.10 演示中，DeepResearchPipeline 会依次调度 4 个具备完全独立上下文的专家智能体：
  1. 🔍 检索专家 (Searcher) ➔ 抓取最新资讯与数据；
  2. 💻 代码专家 (Coder) ➔ 编写并验证原型代码；
  3. ⚖️ 审校专家 (Critic) ➔ 审查代码质量与安全性；
  4. ✍️ 报告主厨 (Synthesizer) ➔ 综合提炼为全景技术报告。
- 由于每个专家都有独立的 Prompt 与思考推理过程，单次完整流水线会发起 4 次连续的 LLM 调用，耗时 20~40 秒属于完全正常的工业级推演开销。

2. DuckDuckGo 免费联网搜索超时或返回空列表

根因：
- 本项目教学代码为了让大家零门槛开箱即用、无需付费购买任何第三方搜索 API Key，内置了基于 DuckDuckGo HTML 的免 Key 轻量抓取机制；
- 当本地网络访问 DuckDuckGo 不稳定或触发其反爬频控时，可能返回空列表（实测国内裸连常见 HTTP 202 反爬挑战页，页面无真实搜索结果）。
降级容灾设计：
- 在 s13_mini_agent.py 中，我们为联网搜索内置了诚实兜底机制：当网络搜索失败时，Agent 会明确报告"搜索失败，不能凭空编造实时信息"，再基于自身训练知识推理作答（不伪造结果），保障对话链路永不崩溃中断；
- 有科学上网环境时搜索成功率显著更高。

快速自检：

bash

# 直接验证搜索连通性（返回结果列表即为正常）
cd 08_手搓Agent/code && uv run python -c "from s13_mini_agent import WebSearch; print(WebSearch().search('python')[:100])"

3. LoopGuard 熔断器触发："🚨 检测到连续 2 次重复调用相同工具，主动熔断！"

根因：
- 当大模型在解决复杂难题遇到挫折时（例如搜索结果为空或代码运行报错），可能会陷入"反复调用同一个工具查询相同关键词"的无休止死循环。
防死机设计：
- 在 8.2 / 8.13 中，我们手搓了 LoopGuard 守护线程。一旦检测到连续 2 次重复调用相同工具且入参一致，或总步数超过 6 步，会立即主动掐断循环并返回错误引导，防止无限消耗用户的 API 额度。

4.（新）8.13 CLI 的 `--repl` 模式：输入 `/` 没有弹出命令菜单，或显示 `Warning: Input is not a terminal`

根因：
- 命令菜单（↑↓ 选择 / Tab 补全）由 prompt_toolkit 提供，只在真实交互式终端（TTY）中生效；
- 如果你用管道喂命令（如 echo "/quit" | python s13_mini_agent.py --repl）或在部分 IDE 内置输出面板中运行，stdin 不是 TTY，程序会自动降级为普通 input() 模式——功能完全可用，只是没有弹出菜单。
解决方案：
- 在系统的真实终端（Terminal / iTerm2 / Windows Terminal）中直接运行 uv run python s13_mini_agent.py --repl 即可。

5.（新）CLI 启动后想找回完整命令清单

说明：
- 启动屏仿 Codex 风格做了极简设计：只有 ASCII Logo 加一行操作提示（💡 输入 / 即弹出命令菜单，↑↓ 翻历史记录，Tab 补全），命令不再全部印在启动屏上；
找回方式（二选一）：
- 输入任意 / 开头的字符，弹出菜单会列出全部命令与说明；
- 输入 /help 查看完整命令清单（含 /deep /search /sessions /resume /clear /quit）。

6.（新）回答是"一次性蹦出来"而不是逐字流式输出？

排查顺序：
- [ ] Web 工作台是否为旧页面缓存：app_s13.py / app.py 的 8.13 对话已接入 8.1 chat_stream 流式输出（气泡逐字增长），按 Cmd + Shift + R 强刷页面后重试；
- [ ] 是否处于工具调用轮：流式仅对"纯正文回答轮"生效；Agent 决定调用工具的中间轮会静默执行工具（观察右侧时间线滚动），拿到结果后的最终回答轮才逐字输出——这是当前实现的已知取舍（流式接口不透出工具调用片段，工具轮自动降级为非流式重放）；
- [ ] CLI 终端是否支持 rich Live 渲染：部分极简终端或不支持 ANSI 动画的输出面板中，打字机效果可能退化为一次性输出，内容不受影响。

7.（新）Web 工作台会话切换相关问题（下拉列表为空 / 恢复后上下文"断片"）

下拉列表为空：
- 会话存档在每轮对话结束后自动写入 code/sessions/<session_id>.json；全新环境（或刚清空过目录）还没有任何存档时列表为空，先进行一轮对话再点 🔄 刷新列表；
- 手动删过 sessions/ 目录里的文件对应存档即消失，不可恢复。
恢复会话后模型"忘了"某件事：
- 恢复的是会话内的消息历史（8.11 SessionStore），跨会话的长期偏好依赖 💾 保存偏好（8.9 MemoryStore 写入 agent_memory.json）——若当初保存偏好时未勾选"允许本轮保存偏好"（审批回调会拒绝 save_preference），该偏好就从未写入长期记忆，换会话自然无从记起。这是权限最小化的正确行为，不是 Bug；
- agent_memory.json 是全局共享的单一记忆文件（本项目尚未实现按会话/项目分区的记忆隔离），跨会话记忆互通属于已知设计。

📊 综合排障矩阵速查表 (Quick Diagnostic Matrix)

故障现象	常见原因	核心排查命令 / 动作	预期修复耗时
发送后一直转圈没动静	深度思考推演中 / 代理阻断 / 终端等审批	查看 Trace 面板 / `curl` 测网关 / 切终端输 `y`	10 秒
网页排版挤压变形/重叠	浏览器缩放过大 (125%+) / 窗口太小	按 `Cmd -` 缩小至 80%~90% / 最大化窗口	3 秒
界面黑底黑字/文字看不清	Dark Reader 等第三方暗黑扩展色彩反转	将 `127.0.0.1:7860` 加入暗黑插件白名单	5 秒
ModuleNotFoundError	未使用 `uv` 虚拟环境，跑到了全局 Python	`uv run python app.py` 或激活 `.venv`	10 秒
401 Invalid API Key	`.env` 不存在 / 复制了多余引号空格	`cp .env.example .env`，填入纯净 Key 文本	20 秒
Windows 下 Bash 命令报错	系统为 Windows，缺少 Linux 命令解释器	使用 Git Bash / WSL2，或改用跨平台命令	1 分钟
代码视窗未找到源码文件	未在 `code/` 根目录下启动 `app.py`	必须先 `cd 08_手搓Agent/code` 再启动	5 秒
Token 未压缩	历史总 Token 未达到压缩触发阈值	在 8.8 工作台中点击预设超长测试用例	5 秒
记忆持久化文件解析报错	`gradio_agent_memory.json` 损坏	删除该 JSON 文件让系统自动重建	3 秒
CLI 输入 `/` 没弹命令菜单	管道/IDE 面板中 stdin 非 TTY，已降级为普通输入	在真实终端（Terminal/iTerm2）中运行 `--repl`	5 秒
找不到完整命令清单	启动屏极简设计，命令不印在横幅上	输入 `/` 看弹出菜单，或输入 `/help`	3 秒
回答不是逐字流式输出	页面缓存 / 工具调用轮静默执行 / 终端不支持 Live 渲染	强刷页面；看时间线是否在滚工具轮；换主流终端	10 秒
会话下拉列表为空	尚无任何存档（存档在每轮对话结束后写入 `sessions/`）	先对话一轮，再点 🔄 刷新列表	5 秒
恢复会话后模型"忘了"偏好	当初未授权保存偏好（审批回调拒绝 `save_preference`）	勾选 💾 允许保存偏好后重新告知一次	10 秒
联网搜索一直返回空结果	DuckDuckGo 反爬/网络不通（国内裸连常见 202 挑战页）	用科学上网，或跑 `WebSearch` 单测自检连通性	1 分钟

留下一份最小复现记录

排查时不要同时更换模型、密钥、依赖版本和网络。先记录运行命令、当前版本、错误全文、发生时间、最小输入和预期结果，再从最靠近错误的一层开始验证。若问题无法稳定复现，至少保留请求编号和关键日志，便于区分偶发服务故障与本地代码问题。

修复之后还要用同一输入重跑，并补一个能够覆盖该问题的检查。删除缓存或重装环境可以作为定位手段，但如果没有找到触发条件，问题仍可能再次出现。

🔗 官方权威参考与支持通道

智谱 BigModel 开放平台：https://open.bigmodel.cn/
智谱 API 在线调试台：https://open.bigmodel.cn/dev/api
Gradio 官方文档：https://www.gradio.app/docs
uv 官方文档：https://docs.astral.sh/uv/
OpenAI Python SDK 官方仓库：https://github.com/openai/openai-python
learn-claude-code 开源项目：https://github.com/shareAI-lab/learn-claude-code
Hello-Agents 开源项目：https://github.com/datawhalechina/hello-agents

💡 小贴士：如果在实际实战中遇到了本手册尚未收录的全新边界情况，欢迎扫码加入本项目交流群或在 GitHub 提交 Issue，我们将持续更新并丰富本排查手册！

🩺 8.14 手搓 Agent 常见问题与故障排查指南 (Troubleshooting & FAQ) ​

🚑 5 秒急救自检树 (Quick Decision Tree) ​

🚨 专题一：很久没反应怎么办？（卡死、转圈、假死无回包） ​

💡 生活化比喻 ​

🔍 深度归因与逐项排查 ​

1. 原因 A：模型开启了「🧠 深度思考」或正在执行「多步工具调用/子代理协作」 ​

2. 原因 B：触发了权限安全门禁（HITL），后台终端正在等待人类审批 [y/N] ​

3. 原因 C：本地开启了全局科学上网代理 (VPN / Clash)，导致国内 API 网关被绕路或阻断 ​

4. 原因 D：API Key 欠费、未生效或单秒请求超限 (RateLimit 429) ​

5. 原因 E：极速验证最小连通性脚本 ​

🎨 专题二：打开 app.py 排版很乱（文字挤压、重叠、三栏变一栏） ​

💡 生活化比喻 ​

🔍 深度归因与快速处理 ​

1. 核心原因 1：浏览器缩放比例过大或屏幕物理分辨率有限 ​

2. 核心原因 2：第三方暗黑模式扩展（如 Dark Reader）色彩冲突 ​

3. 核心原因 3：浏览器缓存了旧版本 CSS 样式 ​

4. 🛠️ 进阶：小屏轻薄本适配（自定义 CSS 响应式微调） ​

🛠️ 专题三：环境依赖与 Python 解释器常见报错 ​

1. 报错 ModuleNotFoundError: No module named 'openai' / 'gradio' / 'rich' ​

2. VS Code / Trae 编辑器中代码整页黄色波浪线标红 ​

🔑 专题四：环境变量与 API Key 配置避坑指南 ​

1. 报错 AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API Key'}} ​

2. 跨厂商灾备机制（智谱 GLM-5.3-Flash + 火山方舟 DeepSeek-V4-Flash） ​

💻 专题五：终端执行 (8.5) 与权限门禁 (8.6) 跨平台疑难 ​

1. Windows 环境下运行 s05_terminal_and_edit.py 提示 FileNotFoundError: 'ls' is not recognized ​

2. 精准行替换 str_replace 报错：“未找到精确匹配的代码行” ​

🗜️ 专题六：上下文压缩 (8.8) 与记忆持久化 (8.9) 常见疑难 ​

1. 为什么在 8.8 工作台中点击“压缩”后，Token 数量没有变化？ ​

2. 长期记忆文件 gradio_agent_memory.json 报错或数据混乱如何重置？ ​

3. 8.9 技能勾选项是空的，或勾了名字却拼不进 Prompt ​

4. 没配 API Key 时，单独跑 s02 / s03 / s04 / s10 / s13 会不会红屏 Traceback？ ​

👥 专题七：Subagents 协作 (8.10) 与 Mini-Agent (8.13) 进阶疑难 ​

1. Subagents 多智能体流水线执行耗时较长（约 20~40 秒） ​

2. DuckDuckGo 免费联网搜索超时或返回空列表 ​

3. LoopGuard 熔断器触发："🚨 检测到连续 2 次重复调用相同工具，主动熔断！" ​

4.（新）8.13 CLI 的 --repl 模式：输入 / 没有弹出命令菜单，或显示 Warning: Input is not a terminal ​

5.（新）CLI 启动后想找回完整命令清单 ​

6.（新）回答是"一次性蹦出来"而不是逐字流式输出？ ​

7.（新）Web 工作台会话切换相关问题（下拉列表为空 / 恢复后上下文"断片"） ​

📊 综合排障矩阵速查表 (Quick Diagnostic Matrix) ​

留下一份最小复现记录 ​

🔗 官方权威参考与支持通道 ​

🩺 8.14 手搓 Agent 常见问题与故障排查指南 (Troubleshooting & FAQ)

🚑 5 秒急救自检树 (Quick Decision Tree)

🚨 专题一：很久没反应怎么办？（卡死、转圈、假死无回包）

💡 生活化比喻

🔍 深度归因与逐项排查

1. 原因 A：模型开启了「🧠 深度思考」或正在执行「多步工具调用/子代理协作」

2. 原因 B：触发了权限安全门禁（HITL），后台终端正在等待人类审批 `[y/N]`

3. 原因 C：本地开启了全局科学上网代理 (VPN / Clash)，导致国内 API 网关被绕路或阻断

4. 原因 D：API Key 欠费、未生效或单秒请求超限 (RateLimit 429)

5. 原因 E：极速验证最小连通性脚本

🎨 专题二：打开 `app.py` 排版很乱（文字挤压、重叠、三栏变一栏）

💡 生活化比喻

🔍 深度归因与快速处理

1. 核心原因 1：浏览器缩放比例过大或屏幕物理分辨率有限

2. 核心原因 2：第三方暗黑模式扩展（如 Dark Reader）色彩冲突

3. 核心原因 3：浏览器缓存了旧版本 CSS 样式

4. 🛠️ 进阶：小屏轻薄本适配（自定义 CSS 响应式微调）

🛠️ 专题三：环境依赖与 Python 解释器常见报错

1. 报错 `ModuleNotFoundError: No module named 'openai'` / `'gradio'` / `'rich'`

2. VS Code / Trae 编辑器中代码整页黄色波浪线标红

🔑 专题四：环境变量与 API Key 配置避坑指南

1. 报错 `AuthenticationError: Error code: 401 - {'error': {'message': 'Invalid API Key'}}`

2. 跨厂商灾备机制（智谱 GLM-5.3-Flash + 火山方舟 DeepSeek-V4-Flash）

💻 专题五：终端执行 (8.5) 与权限门禁 (8.6) 跨平台疑难

1. Windows 环境下运行 `s05_terminal_and_edit.py` 提示 `FileNotFoundError: 'ls' is not recognized`

2. 精准行替换 `str_replace` 报错：“未找到精确匹配的代码行”

🗜️ 专题六：上下文压缩 (8.8) 与记忆持久化 (8.9) 常见疑难

1. 为什么在 8.8 工作台中点击“压缩”后，Token 数量没有变化？

2. 长期记忆文件 `gradio_agent_memory.json` 报错或数据混乱如何重置？

3. 8.9 技能勾选项是空的，或勾了名字却拼不进 Prompt

4. 没配 API Key 时，单独跑 `s02` / `s03` / `s04` / `s10` / `s13` 会不会红屏 Traceback？

👥 专题七：Subagents 协作 (8.10) 与 Mini-Agent (8.13) 进阶疑难

1. Subagents 多智能体流水线执行耗时较长（约 20~40 秒）

2. DuckDuckGo 免费联网搜索超时或返回空列表

3. LoopGuard 熔断器触发："🚨 检测到连续 2 次重复调用相同工具，主动熔断！"

4.（新）8.13 CLI 的 `--repl` 模式：输入 `/` 没有弹出命令菜单，或显示 `Warning: Input is not a terminal`

5.（新）CLI 启动后想找回完整命令清单

6.（新）回答是"一次性蹦出来"而不是逐字流式输出？

7.（新）Web 工作台会话切换相关问题（下拉列表为空 / 恢复后上下文"断片"）

📊 综合排障矩阵速查表 (Quick Diagnostic Matrix)

留下一份最小复现记录

🔗 官方权威参考与支持通道