↕ 滚轮内滚动浏览
Open WebUI 用 Docker 起不来（镜像拉不动、端口被占、页面打不开、数据丢）
Docker 部署 Open WebUI 的四道坎实测——直连 ghcr.io 限时 25 秒没拉完，换 ghcr.nju.edu.cn 3 分 24 秒拉完 1.66GB；宿主端口被占报 address already in use；冷启动到首次 HTTP 200 用了 154 秒（容器内在下 embedding 模型）；不挂 volume 删容器即丢 webui.db。
open-webui-deploy-fail · 域：大模型本地部署 · 已验证
首次 npx ruflo init 很慢、npx 缓存约 2GB（磁盘敏感环境）
首次 npx init 约 5 分钟、缓存约 2GB 级——国内走 npmmirror 秒级下载；验证完可清 `~/.npm/_npx`（不影响已装项目）。
ruflo-4 · 域：多智能体编排 · 已验证
Windows 上 `hive-mind spawn --claude` 检测不到 claude CLI（PATH 检测失败）
Windows 上 spawn --claude 检测不到 claude CLI（#3071 closed，PATH 语义差异）——把 claude 目录加进 PATH 或用完整路径调用；Windows 路径未实测（如实标注）。
ruflo-3 · 域：多智能体编排 · 已验证
ruflo 安装被未发布依赖 pin 卡住（@claude-flow/mcp alpha 未发布）
ruflo 安装卡在依赖解析（@claude-flow/mcp alpha.10 未发布）——等上游发布后重试，或锁定已发布版本区间；本环境 2026-08-29 init 未复现（版本已满足，如实标注）。
ruflo-2 · 域：多智能体编排 · 已验证
`ruflo plugins install` 命令不存在（正确技能入口是 npx skills add）
`ruflo migrate status` 建议的 `ruflo plugins install` 并不存在——技能安装正确入口是 `npx skills add ruvnet/ruflo --all`；初始化用 `npx -y ruflo init`（实测 v3.38.20）。
ruflo-1 · 域：多智能体编排 · 已验证
pip 安装超时/下载慢（ReadTimeoutError / WARNING: Retrying ... Read timed out）
pip 下载慢/超时——临时换清华源：pip install <包> -i https://pypi.tuna.tsinghua.edu.cn/simple。
pip-mirror-source · 域：编码代理与终端 · 已验证
SSH 远程用 herdr 中文显示乱码/输入无效（终端编码与 locale）
SSH 远程 herdr 中文乱码/输入无效——属终端编码/远程 locale 问题；先让远程 `locale` 全为 UTF-8，再查 tmux 类终端面。本环境无远端会话未实测（如实标注）。
herdr-3 · 域：编码代理与终端 · 已验证
Windows 上 herdr 用 PowerShell 安装失败（下载被重置；改直下二进制）
Windows PowerShell 安装 herdr 失败——PowerShell 下载 GitHub release 易被重置；改直下对应二进制（国内走 gh-proxy），或升级到含修复的安装器。Windows 路径未实测（如实标注）。
herdr-2 · 域：编码代理与终端 · 已验证
`herdr server start` 无效 / 后台 server 未拉起（v0.8.2 没有 server start 子命令）
`herdr server start` 无效——v0.8.2 无该子命令；交互直接用 `herdr`（TUI 自动拉起 server），脚本化用 `nohup herdr server &` + `herdr status` 验证。
herdr-1 · 域：编码代理与终端 · 已验证
agent hooks 装不上/不生效（仓库 setup 只做 git hooks）
framework 仓库 setup 只安装 git hooks，agent hooks（pre-tool-call 等）需按 agent 平台规范单独注册（#3732 素材）；本环境未实测（如实标注）。
agent-framework-4 · 域：多智能体编排 · 已验证
MCP 连接只显示 Cancelled via...（真实 401 认证错误被掩盖）
2026-08：MCP HTTP 认证失败只显示 "Cancelled via..."，真实 401 被掩盖（#7699/#7704/#7656，open）——先按凭据/权限核对，或 curl -i 直连端点看 401/403；修复版发布后升级。本环境未实测（如实标注）。
agent-framework-3 · 域：多智能体编排 · 已验证
Python 3.14 装 agent-framework 全量卡死：resolution-too-deep（依赖图过深）
Python 3.14 全量（meta 包）解析约 20 分钟未收敛、pip 报 `resolution-too-deep`——改用最小核心 `agent-framework-core`（31MB / 9 依赖）实测装成；官方支持 Python 3.10–3.13。
agent-framework-2 · 域：多智能体编排 · 已验证
无本地文件读取权限 / 渠道不一致
无本地文件读取权限/渠道不一致——Codex 桌面端先在设置里授予本地文件读取权限，再按产品形态安装。
superpowers-7 · 域：技能管理 · 已验证
venv 移动/复制目录后失效（bad interpreter: No such file or directory / venv/bin/activate: No such file or directory）
venv 移动/复制后失效——venv 不保证可移植，别修 shebang，直接 freeze 依赖后删掉重建。
python-venv-move · 域：编码代理与终端 · 已验证
Ubuntu/Debian pip install 报 error: externally-managed-environment（PEP 668）
pip 报 externally-managed-environment（PEP 668）——建 venv 并在里面装：python3 -m venv .venv && source .venv/bin/activate。
pep668-externally-managed · 域：编码代理与终端 · 已验证
Open WebUI 忘记管理员密码 / 登录不进去怎么办
Open WebUI 忘记管理员密码——docker exec 进容器跑一条 python 重置密码脚本（bcrypt + sqlite3 直改 webui.db）。
open-webui-forgot-password · 域：大模型本地部署 · 已验证
模型都下到 C 盘/系统盘了，怎么把 Ollama 模型目录换到别的盘
模型占满 C 盘——停服务后把模型目录搬到新盘（先复制确认无误再删旧），systemd 用 systemctl stop ollama。
ollama-models-migration · 域：大模型本地部署 · 已验证
npm install -g 报 npm ERR! code EACCES permission denied（全局安装权限）
npm install -g 报 EACCES——推荐把全局 prefix 改到用户目录（npm config set prefix ~/.npm-global），一劳永逸。
npm-global-eacces · 域：编码代理与终端 · 已验证
Node 构建/打包报 FATAL ERROR ... JavaScript heap out of memory（内存溢出）
Node 构建报 heap out of memory——NODE_OPTIONS=--max-old-space-size=8192 临时提上限（按机器内存定）。
node-heap-oom · 域：编码代理与终端 · 已验证
git 报 fatal: detected dubious ownership in repository at（仓库属主与当前用户不一致）
dubious ownership——git config --global --add safe.directory <仓库绝对路径>；白名单按目录登记不递归，同盘其他仓库要再 add。
git-dubious-ownership · 域：编码代理与终端 · 已验证
Docker bind mount / volume 权限报错（Permission denied）：容器进程无法读写挂载目录
bind mount 权限被拒——把宿主目录属主改成容器内 uid（chown -R 1000:1000），或用 -u 1000:1000 匹配。
docker-volume-permission · 域：编码代理与终端 · 已验证
Docker Desktop 启动失败：The file cannot be accessed by the system / 孤儿 AF_UNIX socket
Docker Desktop 启动失败 The file cannot be accessed——停掉所有 Docker 进程后重命名（不能删）%LOCALAPPDATA%\Docker\run 父目录。
docker-desktop-orphan-socket · 域：编码代理与终端 · 已验证
crontab 任务报 command not found / 环境变量缺失（nvm、conda 装的东西跑不了）
crontab 报 command not found 是 cron 环境不继承 shell PATH——crontab 顶部显式声明完整 PATH 后重载。
crontab-env-path · 域：编码代理与终端 · 已验证
zip 解压后中文文件名乱码（Windows/360 压缩的文件在 Linux 上乱码）
zip 解压中文文件名乱码——Windows/360 压的是 GBK，unzip -O GBK 指定编码解压。
zip-gbk-filename · 域：编码代理与终端 · 已验证
WSL 里报 Temporary failure in name resolution / 连不上网，VPN 一连上 WSL 就断网
WSL 报 name resolution 失败/VPN 一连就断网——systemd 发行版给 stub 换可达上游（DNS=223.5.5.5 119.29.29.29）并重启 systemd-resolved。
wsl-dns-resolution-failure · 域：编码代理与终端 · 已验证
JDK 老项目升级 TLS 握手失败：Received fatal alert: protocol_version / No appropriate protocol
JDK 老项目升级 TLS 握手失败——客户端 java.security 里 jdk.tls.disabledAlgorithms 显式禁 SSLv3/TLSv1/TLSv1.1，强制走 TLS1.2+。
tls-jdk-upgrade · 域：安全与治理 · 已验证
安装后 hook error（Windows SessionStart hook fails）
Windows SessionStart hook fails——先升级两边版本（claude update + /plugin update），再手动跑 hook 看真实报错。
superpowers-4 · 域：技能管理 · 已验证
Plugin not found
Plugin not found——先加源再安装再验证：/plugin marketplace add obra/superpowers-marketplace 后 /plugin install。
superpowers-3 · 域：技能管理 · 已验证
只有个别网站打不开（其他网站都正常）——从 curl 超时到分层定位
个别站点打不开——curl 分层定位：getent 看 DNS 是否有解析 → 直连超时看 TCP 层 → --resolve 绕过 DNS 直连解析出的 IP → 区分「DNS 层坏」还是「网络路径层坏」，再对症（换 DNS / 换网络路径 / 加速）。
site-open-fail-others-ok · 域：编码代理与终端 · 已验证
Python 读文件报 UnicodeDecodeError（utf-8/gbk codec can't decode byte）——文件编码与默认编码不匹配
Python 读文件报 UnicodeDecodeError——先 file 看真实编码，再显式指定（如 encoding='gbk'）。
python-unicode-decode · 域：编码代理与终端 · 已验证
Open WebUI 知识库检索不生效 / embedding 配置错（上传文件报 Ollama embed 404）
知识库检索不生效/embed 404——embedding 配置错：管理 API 更新 retrieval/embedding 的 url 和模型名（裸名，别带 ollama/ 前缀）。
open-webui-rag-embedding · 域：大模型本地部署 · 已验证
Windows/ARM release 二进制加载外部扩展失败
Windows/ARM release 二进制加载外部扩展失败——升级到 >=17.1.5（18.0.9 已含修复）。
oh-my-pi-3 · 域：编码代理与终端 · 已验证
钩子未执行（hook 不触发 / Windows hook 报错）
hook 不触发/Windows hook 报错——最常见是缺执行权限：find ~/.claude/hooks -name '*.sh' -exec chmod +x {} +。
oh-my-claudecode-2 · 域：多智能体编排 · 已验证
npm install 慢/随机挂起/网络错误（ETIMEDOUT / ECONNRESET / hang forever）
npm install 慢/挂起——先关审计再装并加长超时：npm install --no-audit --no-fund --fetch-timeout 600000。
npm-mirror-registry · 域：编码代理与终端 · 已验证
训练时 loss 突然尖峰（spike）/ 数值发散（NaN、inf）怎么办
训练 loss 尖峰/数值发散——兜底梯度裁剪（clip_grad_norm_ max_norm=1.0），从最后健康 checkpoint 恢复并把学习率降到 1/3~1/10。
llm-training-loss-spike · 域：大模型本地部署 · 已验证
GitHub 直连慢/失败（clone 被重置、443 连不上、SSH 认证、Release 下载中断）
GitHub 直连慢/失败——分层诊断：curl 看网络通不通，匿名 HTTPS ls-remote 排除配置层，最后才是加速/代理。
github-direct-connect-fail · 域：编码代理与终端 · 已验证
Codex 沙盒报错 helper_unknown_error: setup refresh had errors（写权限/ACL）
Codex 沙盒报 setup refresh had errors——最常见是目录写权限/ACL：管理员 PowerShell 里 takeown /f <目录> /r /d y 改 owner 为当前用户。
codex-sandbox-setup-error · 域：安全与治理 · 已验证
第三方模型鉴权切换后 "No previous sessions found"
第三方模型鉴权切换后报 No previous sessions，把 BASE_URL/AUTH_TOKEN 写进 `~/.claude-mem/.env` 并 restart worker 即恢复。
claude-mem-6 · 域：会话与记忆 · 已验证
同名项目污染：pip 装到 ivanzwb / 国外多个同名 repo
pip 装到同名仿冒包——认准官方路径 npx -y skills add addyosmani/agent-skills，GitHub 认 addyosmani 组织。
agent-skills-3 · 域：技能管理 · 已验证
yfinance history 一直超时（Cookie/crumb fetch failed / curl 28）
yfinance history 一直超时——升级 >=1.7 并用 curl_cffi firefox 指纹会话走代理（yf.download(..., proxy='socks5h://...')）。
yfinance-history-timeout · 域：网关与路由 · 已验证
WSL 里 systemctl 报 System has not been booted with systemd / 服务起不来
systemctl 报 System has not been booted with systemd——/etc/wsl.conf 写 [boot] systemd=true，wsl --terminate 重启后 ps -p 1 应输出 systemd。
wsl-systemd-not-running · 域：编码代理与终端 · 已验证
WSL 启动发行版报 WslRegisterDistribution failed（0x800701bc / 0x80370102）
WslRegisterDistribution failed——0x800701bc 是内核缺失（Store 版 wsl --update，非 Store 装内核更新包）；0x80370102 是虚拟化没生效（bcdedit /set hypervisorlaunchtype auto）。
wsl-register-failed · 域：编码代理与终端 · 已验证
PowerShell 里调 wsl 输出乱码（每字符带空字节 / 每字符一行 / 中文变 �）
PowerShell 调 wsl 输出乱码——脚本开头设 WSL_UTF8=1（或 cmd /c set WSL_UTF8=1 && wsl ...）。
wsl-pipe-encoding · 域：编码代理与终端 · 已验证
WSL 里报 No space left on device，但 df 显示还有大量空间
WSL 报 No space left 但 df 显示还有空间——是 vhdx 文件把宿主盘占满，查 ext4.vhdx 位置和宿主盘剩余空间，清宿主盘即恢复。
wsl-no-space-left · 域：编码代理与终端 · 已验证
WSL 里运行 notepad.exe / cmd.exe 报 command not found（interop 失效）
WSL 里 notepad.exe 报 command not found——/etc/wsl.conf 开 [interop] enabled=true + appendWindowsPath=true，重启发行版生效。
wsl-interop-disabled · 域：编码代理与终端 · 已验证
wsl --import 迁移/重装后默认用户变成 root，whoami 变了、权限全乱
wsl --import 后默认用户变 root——/etc/wsl.conf 写 [user] default=用户名，然后 wsl --terminate 重启发行版生效。
wsl-default-user-root-after-import · 域：编码代理与终端 · 已验证
Vue3 + Vite history 路由部署后刷新白屏（404）
history 路由刷新白屏 404——nginx try_files 回退 SPA 入口（/app/index.html），静态资源单独暴露 404 不误回退。
vite-history-fallback · 域：构建与部署 · 已验证
前端发布后偶发白屏（ChunkLoadError / 版本错位）
发布后偶发白屏 ChunkLoadError——版本错位：先上传新 dist 资源、最后才覆盖 index.html，旧资源保留至少一个发布周期。
vite-chunkloaderror · 域：构建与部署 · 已验证
卸载后残留——共享配置不还原 / 命令仍在
卸载后残留——卸载前先备份共享配置（唯一后悔药），完整卸载=删包+删工具配置目录+手动还原共享配置段。
uninstall-leftover · 域：编码代理与终端 · 已验证
解压 tar 包多出顶层目录 / 文件散落一地 —— --strip-components 用法（macOS 报 Option not supported）
tar 解压多出顶层目录/散落一地——先 tar -tzf 看结构，再按需 --strip-components=1（macOS 不支持该参数）。
tar-strip-components · 域：编码代理与终端 · 已验证
本地/离线部署后插件显示不可用（感叹号）
本地/离线部署后插件显示不可用——当技能用最稳：cp -r skills ~/.claude/skills/superpowers（Codex 形态 cp 到 ~/.codex/skills）。
superpowers-6 · 域：技能管理 · 已验证
装完看不到技能
装完看不到技能——/plugin list 确认状态，完全退出重开新会话再 /find-skills。
superpowers-5 · 域：技能管理 · 已验证
ZIP / tarball 下载超时或中断
ZIP/tarball 下载超时中断——换 git clone 浅克隆通道：--depth 1 --branch v6.3.0，只拉最新提交体积小成功率高。
superpowers-2 · 域：技能管理 · 已验证
/plugin install 报 fatal: Failed to connect to github.com port 443
/plugin install 连不上 github 443——先 curl -sI codeload 探路（实测 1.7~1.9s），可达就走 tarball 直装，或给 git 显式配代理。
superpowers-1 · 域：技能管理 · 已验证
SSH 报 UNPROTECTED PRIVATE KEY FILE / Permissions ... are too open（私钥权限过宽）
UNPROTECTED PRIVATE KEY FILE——私钥 600、目录 700（chmod 600 key && chmod 700 ~/.ssh）；Windows 原生 OpenSSH 用 icacls。
ssh-key-permissions · 域：编码代理与终端 · 已验证
短信接口被狂刷（短信费用飙升/接口被打垮，怎么限流止损）
短信接口被狂刷——nginx 层 IP 限流止损：limit_req_zone（rate=5r/s）+ location 内 limit_req burst=10 nodelay，超限返回 503。
sms-api-rate-limit · 域：安全与治理 · 已验证
semantic_* 分析器警告（缺 API key）
semantic_* 分析器警告——缺 API key：不需要语义分析就 --no-llm 静态扫；要语义分析配 OPENAI_API_KEY 或 SKILLSPECTOR_PROVIDER。
skillspector-6 · 域：安全与治理 · 已验证
风险评分 >50 输出 DO NOT INSTALL
风险评分 >50 输出 DO NOT INSTALL——先看 Issues 明细（severity/confidence/rule/location）再下结论，别只看分数。
skillspector-5 · 域：安全与治理 · 已验证
依赖版本冲突警告
依赖版本冲突——隔离 venv 安装不污染系统 Python（venv 内 pip install skillspector，实测方式）。
skillspector-4 · 域：安全与治理 · 已验证
MCP 模式 stdio 挂起（可选依赖缺失）
MCP 模式 stdio 挂起——先 skillspector mcp --help 确认 CLI 层正常，再按项目文档装全可选依赖（pip install -U skillspector[mcp]）。
skillspector-3 · 域：安全与治理 · 已验证
Failed building wheel for yara-python（构建依赖缺失）
yara-python 构建失败——Debian/Ubuntu 装齐 build-essential python3-dev 后重试。
skillspector-2 · 域：安全与治理 · 已验证
pip install skillspector 找不到包（No matching distribution）
pip 找不到 skillspector——PyPI 没发布：下载 release wheel（gh-proxy 加速）后 pip 安装，依赖走清华镜像。
skillspector-1 · 域：安全与治理 · 已验证
bash: ./script.sh: Permission denied——脚本缺执行权限
bash: ./script.sh: Permission denied——脚本缺执行位，chmod +x 后运行。
script-permission-denied · 域：编码代理与终端 · 已验证
Python 3.12+ 报 ModuleNotFoundError: No module named 'distutils'
Python 3.12+ 缺 distutils——pip install setuptools（venv 里装 venv 的，系统 Python 用 sudo）。
python-distutils-removed · 域：编码代理与终端 · 已验证
python: command not found——Ubuntu 只有 python3，没有 python 命令
python: command not found——Ubuntu 只带 python3；装官方包 python-is-python3 即可无副作用。
python-command-not-found · 域：编码代理与终端 · 已验证
设置了代理环境变量却不生效——有的命令走代理有的不走（HTTP_PROXY 大小写坑）
设置了代理不生效——curl 只认小写 http_proxy/https_proxy（大写 HTTP_PROXY 被故意忽略），pip/npm 认大写；NO_PROXY 对两者都生效。
proxy-env-var · 域：编码代理与终端 · 已验证
pip install 报 SSL 证书错误（CERTIFICATE_VERIFY_FAILED）——信任链断了，别急着 --trusted-host
pip 报 CERTIFICATE_VERIFY_FAILED——根因是 CA 信任链不含该证书（自签/内网私有 CA/公司代理 MITM）；--trusted-host 只是临时跳过校验（实测 SSL 阶段通过），正规修=CA 导入系统信任库 + pip --cert 指向系统 bundle（实测通过，负对照成立）。
pip-ssl-cert · 域：编码代理与终端 · 已验证
Docker 里跑 Open WebUI 连不上 Ollama（页面显示 Ollama 未连接 / 模型列表为空）
容器里 Open WebUI 连不上 Ollama——重建容器指到宿主机 Ollama，Linux 显式加 --add-host host.docker.internal:host-gateway。
open-webui-ollama-connect · 域：大模型本地部署 · 已验证
ollama pull 卡住/超时（官方 registry 国内直连不稳定）
ollama pull 卡住/超时——官方 registry 国内不稳：ModelScope 下 GGUF 后用 ollama create 导入（示例 qwen2.5:0.5b）。
ollama-pull-timeout · 域：大模型本地部署 · 已验证
ollama 装不上/官方安装脚本国内拉不动（下载慢、超时）
官方安装脚本国内拉不动——gh-proxy 拉 GitHub Release tar.zst 解压到 /usr/local，验证版本（实测可行）。
ollama-install-slow · 域：大模型本地部署 · 已验证
ollama 命令报 "could not connect to a running Ollama instance"（服务没启动）
could not connect to a running Ollama instance——服务没启动：nohup ollama serve 后台起，curl http://127.0.0.1:11434/api/version 返回版本即就绪。
ollama-connect-failed · 域：大模型本地部署 · 已验证
名称混淆：oh-my-pi（omp）vs pi-mono（pi）
oh-my-pi(omp) 与 pi-mono(pi) 名称易混——按命令名认项目：装完执行 omp --version 的是 oh-my-pi。
oh-my-pi-4 · 域：编码代理与终端 · 已验证
命令混淆：omp install 与 omp plugin install
omp install 与 omp plugin install 是两回事——显式用子命令 omp plugin install <插件名> 最不易歧义。
oh-my-pi-2 · 域：编码代理与终端 · 已验证
安装成功但 omp --version 报 SyntaxError（旧版 bun）
omp --version 报 SyntaxError——旧版 bun 不兼容，升级 bun 到 >=1.3.14 再验证。
oh-my-pi-1 · 域：编码代理与终端 · 已验证
同名 fork 项目混淆
同名 fork 混淆——装前 npm view 确认版本，认准官方包 oh-my-claude-sisyphus@5.0.0，装完 omc --version 验证。
oh-my-claudecode-7 · 域：多智能体编排 · 已验证
Claude Code 本体环境类报错（OOM / Homebrew 冲突 / PowerShell 执行策略）
Claude Code 本体环境报错——WSL/Linux 走 npm 路径装 CLI 避免 brew 双写；Windows PowerShell 先放开执行策略 RemoteSigned。
oh-my-claudecode-6 · 域：多智能体编排 · 已验证
包名 / 插件名 / 命令名不一致
包名/插件名/命令名不一致——安装卸载认准 npm 包名 oh-my-claude-sisyphus，日常用 omc 命令。
oh-my-claudecode-5 · 域：多智能体编排 · 已验证
更新 / 配置异常（omc-doctor 诊断）
更新/配置异常——跑内置诊断 omc-doctor 定位问题点，保留输出（含版本号与 node 版本）再反馈。
oh-my-claudecode-4 · 域：多智能体编排 · 已验证
智能体未自动委托（任务没被分发）
智能体未自动委托——在正确项目根目录重跑 /omc-setup（CLAUDE.md 按项目生成），再检查规则是否加载。
oh-my-claudecode-3 · 域：多智能体编排 · 已验证
命令未找到（omc: command not found）
omc: command not found——确认已装（npm ls -g oh-my-claude-sisyphus），重装 5.0.0（走 npmmirror）后检查 PATH。
oh-my-claudecode-1 · 域：多智能体编排 · 已验证
npm install 报 npm ERR! code ERESOLVE / ERESOLVE unable to resolve dependency tree（peer 依赖冲突）
ERESOLVE peer 依赖冲突——npm install --legacy-peer-deps 跳过严格检查（旧项目过渡首选）。
npm-eresolve-peer-conflict · 域：编码代理与终端 · 已验证
npm run 报 Error: error:0308010C:digital envelope routines::unsupported（Node 新版本 + 老 webpack）
Node 新版 + 老 webpack 报 digital envelope unsupported——NODE_OPTIONS=--openssl-legacy-provider 过渡，长期升级构建工具。
npm-digital-envelope-unsupported · 域：编码代理与终端 · 已验证
Netty 直接内存 OOM：OutOfDirectMemoryError / Direct buffer memory（ByteBuf 泄漏 + MaxDirectMemorySize 未设）
Netty OutOfDirectMemoryError——显式 -XX:MaxDirectMemorySize 隔离堆与直接内存并给足容器限制（止血）；根治是请求体缓存加大小门槛 + 响应式链路释放兜底。
netty-direct-memory-oom · 域：编码代理与终端 · 已验证
MySQL 误删数据后如何恢复（binlog 闪回）
MySQL 误删数据——binlog 闪回：SHOW BINLOG EVENTS 定位误删事务起点，用 --stop-position=DELETE 起点导出并重放写入。
mysql-binlog-flashback · 域：构建与部署 · 已验证
MinIO 社区版停更归档，Docker 部署的文件服务怎么办（迁移 RustFS 数据零丢失）
MinIO 社区版停更——迁移 RustFS 可零丢失：先 docker inspect 记录数据目录，停旧容器（数据原样保留），再挂载同一目录起新服务。
minio-to-rustfs-migration · 域：构建与部署 · 已验证
升级后刷 Invalid type NoneType for attribute 'http.port' value 警告
升级后刷 Invalid type NoneType for http.port——第三方客户端（kiota/httpx）设置问题，该 warning 无害可忽略。
logfire-2 · 域：可观测性 · 已验证
FastAPI+SQLModel 测试报 sqlalchemy.exc.NoInspectionAvailable
FastAPI+SQLModel 报 NoInspectionAvailable——升级 logfire 到 >=2.11.1（4.41.0 已含修复）。
logfire-1 · 域：可观测性 · 已验证
Java OOM 六种报错签名速查：heap space / Metaspace / StackOverflowError / native thread / GC Overhead
Java OOM 六种签名各不同——先开 HeapDumpOnOutOfMemoryError 拿 dump，再看 GC 日志确认是哪种耗尽（heap/Metaspace/栈/线程/GC overhead），按签名对号入座调参。
java-oom-classify · 域：编码代理与终端 · 已验证
Hugging Face 模型下载卡住/超时（国内）——HF_ENDPOINT 切 hf-mirror，代码零改动
HF 模型下载卡住——huggingface.co 直连国内不可达（实测超时 000），设 HF_ENDPOINT=https://hf-mirror.com 后 hf_hub_download 秒级成功（1.2s/662B，代码零改动）。
hf-model-download · 域：编码代理与终端 · 已验证
go get/go mod download 超时（dial tcp ... i/o timeout）→ 换 GOPROXY 国内代理
go get 超时——临时换国内代理：GOPROXY=https://goproxy.cn,direct go mod download。
go-proxy-cn · 域：编码代理与终端 · 已验证
git clone 公开仓库报 fatal: Could not read from remote repository / Please make sure you have the correct access rights and the repository exists（网络正常）
git clone 公开仓库报权限错误——先用 GIT_CONFIG_GLOBAL=/dev/null git ls-remote 匿名 HTTPS 验证（能返回=配置问题），再删 git@ 改写规则。
github-clone-fail · 域：编码代理与终端 · 已验证
git 换行符混乱——diff 全部文件显示修改 / warning: LF will be replaced by CRLF / CRLF will be replaced by LF
git 换行符混乱——仓库根加 .gitattributes（* text=auto eol=lf）后 git add --renormalize . 一劳永逸。
git-crlf · 域：编码代理与终端 · 已验证
LLM Function Calling 不可控？AI 建议的危险调用必须过白名单（本地 qwen 实测）
LLM Function Calling 不可控——危险调用必须过白名单（只读函数放行，delete/refund/update 二次确认），本地 qwen 实测。
function-calling-guard · 域：大模型本地部署 · 已验证
程序偶发 SIGSEGV 崩溃，gdb 显示 best=DBL_MAX 且指针为空——浮点比较"恒不成立"时哨兵从未被覆盖
浮点比较恒不成立导致哨兵指针空——代码兜底过滤 NaN/Inf + 哨兵判空；环境根治是软浮点 ABI 重编译。
float-crash · 域：编码代理与终端 · 已验证
powershell 运行 .ps1 报「禁止运行脚本」——执行策略（ExecutionPolicy）限制
PowerShell 禁止运行脚本——进程级绕过最推荐：powershell -NoProfile -ExecutionPolicy Bypass -File script.ps1，不改注册表。
execpolicy-restricted · 域：编码代理与终端 · 已验证
docker system prune 到底删什么？容器/镜像/卷/缓存清理边界速查
prune 删除范围各不同——system prune 默认删停止容器+dangling 镜像+未用网络，不碰卷和 build cache；volume prune 默认只删匿名卷（named 卷要 -a）；删前先 docker system df 看占比，共享环境用 --filter label= 圈定。
docker-prune-scope · 域：编码代理与终端 · 已验证
docker run / compose up 报 port is already allocated / address already in use（端口被占用）
端口已占用——先 docker ps 看是不是容器占的，再看 ss -tlnp 宿主机进程，最后换端口。
docker-port-already-allocated · 域：编码代理与终端 · 已验证
docker pull 报 manifest for "xxx:latest" not found（镜像或标签不存在）
manifest not found——先 docker manifest inspect 确认远端存在，再拉明确 tag，别赌 latest。
docker-manifest-not-found · 域：编码代理与终端 · 已验证
docker 报 invalid reference format / repository name must be lowercase（镜像引用格式非法）
invalid reference format——看 docker 实际收到的镜像名，对照 docker run ubuntu 这类必过命令排查大小写/空格/引号残留。
docker-invalid-reference-format · 域：编码代理与终端 · 已验证
docker pull 报 ERROR: Get "https://registry-1.docker.io/v2/" ... connection reset by peer / 拉取镜像失败
docker pull 连接被重置——备份 daemon.json 后写入实测可用的 registry-mirrors 加速器并重启 docker。
docker-hub-pull-fail · 域：编码代理与终端 · 已验证
Docker 容器内连不上宿主机服务（localhost 是容器自己，不是宿主机）
容器内连不上宿主机服务——localhost 是容器自己；用 --add-host host.docker.internal:host-gateway 后容器内访问 host.docker.internal。
docker-host-access · 域：编码代理与终端 · 已验证
docker exec 报 the input device is not a TTY / container is not running / executable file not found
docker exec 报 not a TTY——非交互执行去掉 -t，用 docker exec <容器> sh -c "命令"。
docker-exec-tty · 域：编码代理与终端 · 已验证
docker 命令报 Cannot connect to the Docker daemon at unix:///var/run/docker.sock / failed to connect to the docker API（连不上 daemon）
Cannot connect to daemon——先 unset DOCKER_HOST 排除残留环境变量，再确认 Docker Desktop 真的启动着。
docker-daemon-connect · 域：编码代理与终端 · 已验证
容器里时间差 8 小时（date 显示 UTC）/ 中文乱码（UnicodeEncodeError）
容器时间差 8 小时/中文乱码——-e TZ=Asia/Shanghai（无 tzdata 的镜像用 TZ=UTC-8，符号相反）；乱码装 locale 或显式设 LANG。
docker-container-timezone-locale · 域：编码代理与终端 · 已验证
容器进程突然被杀（OOMKilled / exit code 137）——内存限制与排查
容器进程突然被杀 Exited(137)——先 docker inspect 确认 OOMKilled：true=内存超限要调限制，false=被人 kill -9 或其它原因。
docker-container-oom-killed · 域：编码代理与终端 · 已验证
docker 报 Conflict. The container name "/xxx" is already in use（容器名被占用）
容器名被占用报 Conflict——docker rm -f 删掉占名的旧容器（含已退出）再重新跑原命令。
docker-container-name-conflict · 域：编码代理与终端 · 已验证
Docker 容器内域名解析失败（wget: bad address / Temporary failure in name resolution / Could not resolve host）
容器内域名解析失败——用国内公共 DNS 重跑容器：--dns 223.5.5.5 --dns 119.29.29.29。
docker-container-dns · 域：编码代理与终端 · 已验证
docker compose 起栈失败——依赖服务没就绪（Connection refused / unhealthy / depends_on 不生效）
depends_on 只等容器启动不等就绪——给依赖服务加 healthcheck，app 用带 condition 的长写法 depends_on。
docker-compose-depends-not-ready · 域：编码代理与终端 · 已验证
docker-compose / docker compose 报 command not found（Compose 没装或没接线）
docker-compose command not found——Ubuntu/Debian 装 docker-compose-v2 插件即可（实测 2.40.3），然后 docker compose version 确认。
docker-compose-command-not-found · 域：编码代理与终端 · 已验证
Docker build 缓存不生效（每次改代码都重跑安装层）—— COPY 顺序与 .dockerignore
Docker build 缓存不生效是 COPY 顺序问题——依赖清单（package.json 等）先 COPY 再 RUN 安装，全量 COPY 放最后。
docker-build-cache · 域：编码代理与终端 · 已验证
装完跑 agent 无响应（需 init + provider 配置）
装完 agent 无响应——缺 init + provider 两步配置：deepcode init && deepcode provider 配模型与 key。
deepcode-6 · 域：多智能体编排 · 已验证
MCP client 起不来（Brave MCP WinError 2 / npx 未跑起来）
MCP client 起不来——先确认 npx 可用，手动预下载 MCP 包（npx -y <包名>）再配置进 deepcode。
deepcode-5 · 域：多智能体编排 · 已验证
旧 Python 装不上（requires-python）
旧 Python 装不上——requires-python 限制：3.10+ 直接 pip install deepcode-hku；<3.10 先用 pyenv/conda 升级（别动系统默认）。
deepcode-4 · 域：多智能体编排 · 已验证
curl 证书报错（--ssl-no-revoke）
Windows curl 下载报证书错——加 --ssl-no-revoke 跳过吊销检查。
deepcode-3 · 域：多智能体编排 · 已验证
git clone 连接被重置（源码安装路径）
源码安装 clone 被重置——清掉失效 git 代理后直接 pip install deepcode-hku，不需要 clone 源码。
deepcode-2 · 域：多智能体编排 · 已验证
大文件下载中断后无法续传（curl: (33) HTTP server does not seem to support byte ranges）
curl 大文件中断无法续传——先 Range 探测（206=支持续传），支持就 curl -C - 续传，不支持只能换源或整包重下。
curl-resume-break · 域：编码代理与终端 · 已验证
CSS 样式加载失败（页面无样式/布局错乱，控制台可能无报错）
CSS 样式加载失败——nginx 场景多半是没 include mime.types（.css 没被识别为 text/css），补上并 nginx -t 后 reload。
css-load-failure · 域：构建与部署 · 已验证
bash 脚本报 $'\r': command not found / bad interpreter: /bin/bash^M——Windows 换行符（CRLF）混入
bash 报 $'\r' command not found 是 Windows CRLF 换行符混入脚本——sed -i 's/\r//' 一行修复。
crlf-command-not-found · 域：编码代理与终端 · 已验证
Codex 桌面应用更新失败（应用内更新报错 / MSIX 手动安装）
Codex 桌面应用更新失败——先强制关掉所有 ChatGPT/Codex 进程（不关必失败），再手动 Add-AppxPackage 安装官方 MSIX 包。
codex-update-msix · 域：编码代理与终端 · 已验证
ChatGPT Windows 客户端打不开：Unable to locate the Codex CLI binary / 找不到 Codex CLI
ChatGPT 客户端找不到 Codex CLI——先 codex --version 确认装没装，没装用官方 PowerShell 脚本安装，再按真实路径设 CODEX_CLI_PATH（别照抄网上的）。
codex-cli-chatgpt-not-found · 域：编码代理与终端 · 已验证
GitHub 直连慢/失败（依赖 GitHub 的场景）
GitHub 直连慢——核心流程不碰 GitHub，code-review-graph build --repo . 离线可跑；pip 安装走清华镜像。
code-review-graph-4 · 域：代码审查 · 已验证
安装后「我的配置被改了」/ 与 omc、agt 疑似冲突
装完发现配置被改——这些写入是功能不是故障；不需要就 code-review-graph uninstall 官方清理。
code-review-graph-3 · 域：代码审查 · 已验证
名称混淆：juspay/code-review-graph-rescript 同名变体
同名变体混淆——PyPI 装 code-review-graph==2.3.8，输出 2.3.8 才对；看到 rescript 就是装错变体。
code-review-graph-2 · 域：代码审查 · 已验证
opencode 安装 API 不匹配
opencode 装 claude-mem 报 API 不匹配，先 `claude-mem doctor` 确认；opencode 场景优先等插件更新或换兼容实现。
claude-mem-7 · 域：会话与记忆 · 已验证
Chroma 进程泄漏 / zombie 链
Chroma 进程泄漏/僵尸链先 `pkill -f chroma` 清残留并重启 worker，升级插件 13.16.1 根治。
claude-mem-5 · 域：会话与记忆 · 已验证
npm 依赖安装失败
npm 依赖安装失败换 npmmirror 源重装，装完用 `claude-mem --version` 确认版本。
claude-mem-4 · 域：会话与记忆 · 已验证
首会话重复 SessionStart hook 错误（worker 竞态）
首会话重复报 SessionStart hook 错误是 worker 未预热竞态，开会话前先 `claude-mem start && claude-mem status`。
claude-mem-3 · 域：会话与记忆 · 已验证
worker/UI 端口占用："Is port 37777 in use?"
worker/UI 报端口占用时按安装输出实际端口（默认 37700，旧资料 37777）清理并重启，`kill -9` + `claude-mem start` 一条龙。
claude-mem-2 · 域：会话与记忆 · 已验证
marketplace 克隆失败：SSH 认证失败 / 克隆卡死
marketplace 克隆失败不是 key 问题——公开仓库匿名即可，强制 HTTPS + gh-proxy 加速，实测克隆 90 秒卡死变秒级。
claude-mem-1 · 域：会话与记忆 · 已验证
多个工具都写 ~/.claude.json，一起装会冲突吗？（实测兼容）
多个工具都写 ~/.claude.json 会不会冲突——实测兼容：按各自官方命令安装，装完 python3 -m json.tool 验证 JSON 可解析。
claude-json-multi-tool · 域：多智能体编排 · 已验证
JSON / API 配置错误导致服务启动失败
JSON 配置错误导致启动失败——先备份配置，jq empty 校验语法，OK 再 ccr restart（备份是唯一后悔药）。
claude-code-router-6 · 域：网关与路由 · 已验证
Docker 部署：端口 / volume / 权限
Docker 部署打不开/丢配置/权限错——按项目 docker/README.md 参数：-p 8080:8080 + named volume + -u 1000:1000。
claude-code-router-5 · 域：网关与路由 · 已验证
本地模型 api_base_url 配置错误（Ollama 等）
本地模型连不上——ollama list 确认模型名，api_base_url 写完整地址（http://localhost:11434/v1/chat/completions）后 ccr restart。
claude-code-router-4 · 域：网关与路由 · 已验证
首次运行 No available models / 网关起不来
首次运行 No available models——先 ccr start 启动网关，浏览器打开管理界面添加 provider。
claude-code-router-3 · 域：网关与路由 · 已验证
WSL 里 node: not found（npm 来自 Windows 侧）
WSL 里 node: not found——npm 来自 Windows 侧，WSL 内用 nvm 装原生 Node 22 并重装全局包。
claude-code-router-2 · 域：网关与路由 · 已验证
EBADENGINE：Node 版本不满足 engines
EBADENGINE 是 Node 版本不满足 engines——nvm 装 22 并切换后重装全局包。
claude-code-router-1 · 域：网关与路由 · 已验证
安装来源混淆：npm 同名包 / 其它 cc-switch 项目
npm 同名包是仿冒项目；认准官方仓库 farion1231/cc-switch，从 Release 下载 deb 安装。
cc-switch-5 · 域：会话与记忆 · 已验证
启动失败 / 白屏排查
启动失败/白屏先 `ldd /usr/bin/cc-switch | grep not found` 查动态库缺失，补依赖即恢复。
cc-switch-4 · 域：会话与记忆 · 已验证
架构不匹配（香橙派等 ARM 设备）
香橙派等 ARM 设备装 x86 包报架构不匹配，先 `dpkg --print-architecture` 查架构，再装对应 deb。
cc-switch-3 · 域：会话与记忆 · 已验证
GitHub Release 下载 TLS 断连 / 超时
GitHub Release 下载 TLS 断连/超时，用 gh-proxy 前缀加速，13.5MB 实测秒级；镜像不可用就去掉前缀直连。
cc-switch-2 · 域：会话与记忆 · 已验证
dpkg -i 依赖缺失：libwebkit2gtk 等（Linux 安装/启动失败）
dpkg 装 cc-switch 报缺 libwebkit2gtk 等依赖，`sudo apt install -f` 自动补依赖后重装即可（本地实测装/卸循环）。
cc-switch-1 · 域：会话与记忆 · 已验证
apt-get update 报 404 Not Found / 源失效（Err:1 ... 404）
apt-get update 报 404 是源失效——先看 Err: 行定位坏条目，curl 验证确实 404 后删/注释该源再 update。
apt-404-broken · 域：编码代理与终端 · 已验证
Agent 工具链全家桶能一起装吗？（17 工具 57 对实测兼容清单）
Agent 工具链全家桶能一起装——17 工具 57 对实测兼容，先跑 站内文档 --check 做冲突预检，按需安装无强制顺序。
agent-toolchain-coexist · 域：多智能体编排 · 已验证
装完看不到技能 / document-skills 安装问答
装完看不到技能——技能是目录复制：先 ls ~/.claude/skills/agent-skills 核对（应 24 目录），再完全退出重启 agent，最后查权限/版本。
agent-skills-4 · 域：技能管理 · 已验证
安装失败排查：Node 版本 / pnpm / npm 缓存
安装失败先查 Node 版本——npm 走 npmmirror 镜像重试（实测 PONG 0.32s），npx -y skills add addyosmani/agent-skills。
agent-skills-2 · 域：技能管理 · 已验证
官方 CLI 安装失败：GitHub clone 被重置/卡死（国内高频）
官方 CLI 装 agent-skills 因 GitHub clone 被重置失败——用方式 B：codeload tarball 走 gh-proxy 下载后手工复制（国内实测可行）。
agent-skills-1 · 域：技能管理 · 已验证