qmd embed hangs at 'Gathering information' step - infinite loop

[glorywuma-cmd]

问题描述

qmd embed 命令在 "Gathering information" 步骤卡住，无限输出终端控制码，无法完成。

环境

• qmd 版本: 2.0.1
• Node 版本: v22.22.0
• 平台: macOS Darwin 25.3.0 (arm64)
• 安装方式: npm install -g @tobilu/qmd

复现步骤

1. 创建任意 collection: qmd collection add <path> --name test --mask "*.md"
2. 运行 qmd embed 或 qmd embed -c test
3. 程序卡在 "Gathering information" 步骤

测试结果

• 就算是 1 个只有 4 个字符的文件，还是卡住
• 重定向输出到文件 (> log.txt 2>&1) 也一样
• 不是网络/模型下载问题（无网络活动）
• 不是输入文件问题（最小测试也卡住）

日志/输出

⠋ Gathering information
[2K[1A[2K[G⠙ Gathering information
[2K[1A[2K[G⠹ Gathering information
... (无限循环)

临时解决方案

用 qmd search（关键词搜索）代替，不需要 embed

[glorywuma-cmd]

补充测试结果

清除缓存后测试：

• 清除了 ~/.cache/qmd/ 缓存
• 创建全新 collection，只有 2 个干净的纯 UTF-8 英文文件：
  • test.md (14 bytes)
  • readme.md (35 bytes)
• 结果：仍然卡在 "Gathering information"

结论： 不是文件编码/内容问题，是 qmd embed 在分块阶段本身的 bug。

[glorywuma-cmd]

问题已解决！✅

根本原因： 模型下载卡住（国内访问 HuggingFace 慢/超时），但进度条在无限刷新，表现为 "Gathering information" 无限循环。

解决方案：

# 设置 HuggingFace 镜像
export HF_ENDPOINT=https://hf-mirror.com

# 永久生效
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.zshrc
source ~/.zshrc

然后重新运行 qmd embed 即可。模型会通过镜像加速下载。

复盘教训：

1. "Gathering information" 意味着模型下载/加载，别急着判断是 bug
2. 国内访问 HuggingFace 慢/超时时，会卡在下载但进度条在刷新
3. 先试镜像/代理等常见解决方案，再考虑报 bug
4. 可以问 AI（百度 DeepSeek 这次帮了大忙）

感谢百度 DeepSeek！🙏