WorkBuddy非开箱即用，需手动配置：前端NEXT_PUBLIC_API_BASE_URL须改为http://backend:8000，后端服务名必须为backend；模型仅支持GGUF格式并正确路径配置；RAG解析PDF需禁用pdfminer防死锁；参数与权限配置任一遗漏将导致功能异常。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy 不是开箱即用的“AI工作站”，它本质是一个需要手动组装、调优和持续维护的本地化工具链——直接拉镜像跑起来，大概率卡在 model loading 或 HTTP 502，根本进不了 UI。
为什么 docker-compose up 后访问 http://localhost:3000 显示空白或连接拒绝
这不是网络问题，而是 WorkBuddy 的前端（Next.js）和后端（FastAPI）默认不共享同一 host，且前端构建时硬编码了 NEXT_PUBLIC_API_BASE_URL。Docker 网络中，前端容器无法通过 localhost 访问后端。
- 必须在
.env.local（前端目录下）里把NEXT_PUBLIC_API_BASE_URL改成http://backend:8000，而非http://localhost:8000 - 后端服务在
docker-compose.yml中的 service name 必须叫backend，否则前端 DNS 解析失败 - 前端镜像构建前要先运行
npm run build，否则 Dockerfile 中的next export会因缺少.next目录而静默失败
llama.cpp 模型加载失败：报错 failed to load model: unknown file format
WorkBuddy 默认期望的是 GGUF 格式模型，但很多人误用了旧版 GGML 或 PyTorch 原生权重（.bin / .safetensors），这些格式 runtime 会直接拒载。
WorkBuddy 会议助手——会议价值不该散会就流失。它把会议的采集、提炼、确认、分发串成一条流水线：从腾讯会议 / IMA / 企业微信多端取料，按 15 类场景模板自动提炼成结构化纪要，你过目确认后一键分发到钉钉、飞书、腾讯文档或企业微信。全程由 workflow 工作流编排驱动，只抽取不编造、先预览后推群、自动去重。 触发：「把会议纪要做一下发钉钉」「总结 IMA 里的 XX 录音」「按面试模板整理这场会」「把这场复盘发飞书」「发到腾讯文档让我手动改」「整理企业微信里的会议纪要」。 能力：腾讯
- 只认
.gguf后缀，且需确认模型量化类型匹配——比如Q4_K_M可以跑，但Q2_K在某些 CPU 上会触发avx2 not supported - 模型文件必须放在
models/目录下，并在config.yaml中用完整相对路径声明：model_path: "models/phi-3-mini-4k-instruct.Q4_K_M.gguf" - 若用 Apple Silicon，记得加
LLAMA_METAL=1环境变量，否则 fallback 到慢速 CPU 推理，首次响应常超 90 秒
上传 PDF 后 rag_pipeline 卡住，日志反复输出 chunking document...
这是 RAG 模块默认启用了 unstructured + pdfminer 双引擎解析，而 pdfminer 在处理扫描件或含复杂表格的 PDF 时会死锁，且无 timeout 控制。
- 临时解法：在
rag/config.py中将PDF_PARSER_ENGINE显式设为"unstructured"，并确保已安装unstructured[all-docs] - 真正稳定的做法是预处理 PDF——用
pdf2image+pytesseract转成文本再喂给 RAG，但需额外启动 OCR 容器，WorkBuddy 官方 docker-compose 不包含此服务 - 注意
CHUNK_SIZE和CHUNK_OVERLAP若设得过大（如 >1024），会导致 embedding 向量维度溢出，Silicon 芯片上尤其容易触发bus error
WorkBuddy 的“高效”完全取决于你对它每个模块边界条件的理解程度——比如 llama.cpp 的线程数配多少、unstructured 是否启用 hi_res 模式、甚至 docker volume 的挂载权限是否允许 backend 写入缓存目录。漏掉其中任意一个，它就只是个能亮屏的玩具。
