SnowLuma QQ 文件发送工具

让本机 AI Agent 把用户指定的文件，通过 SnowLuma 发给预先配置好的 QQ 收件人。

提供 stdio MCP + CLI：准备文件 → 发送 → 查询状态。文件内容由本机 QQ 后端读取上传；模型只接触文件名、大小、校验值和发送状态。工具不调用模型 API，也不需要模型密钥。

适合“生成报告后把文件发给我”这类个人秘书任务。v0.2.0 新增可选的 QQ 私聊找文件：本人说出关键词，在明确允许的电脑目录或群文件中查找，选中后发回自己。无需调用模型，不产生模型 token 费用。

MCP/CLI 可单独使用；QQ 查找入口默认关闭，开启后需要常驻事件监听。它不接收群聊指令，不提供群管理或聊天记忆功能。

需要什么

• Node.js 24+、npm。

• 已登录 QQ 且开启 OneBot HTTP 接口的 SnowLuma，在同一台电脑运行。

• 网关支持扩展动作 upload_private_file。它不是 OneBot v11 标准动作，后端版本会影响实际可用性。

• 网关进程能按相同绝对路径读取本工具的暂存文件；当前不做跨主机或容器路径映射。

本地原型已在 Windows + SnowLuma 2.1.1 完成真实 PDF 私聊发送，收件人确认能打开文件。公开版增加了配置通用化和边界检查，以自动化测试验证；其他网关、版本和操作系统的真实 QQ 传输尚未验证。

本仓库不包含 SnowLuma、QQ 或它们的安装器，也不负责启动、更新、登录这些程序。请自行安装并遵守各自许可。本工具是独立项目，与这些项目及腾讯无隶属关系。

Related MCP server: YAFL MCP Server

快速开始（PowerShell）

下载或克隆本仓库，进入目录：

npm ci --ignore-scripts
New-Item -ItemType Directory -Force D:\file-sender-home, D:\agent-output
Copy-Item .\secretary.example.json D:\file-sender-home\secretary.json

编辑 D:\file-sender-home\secretary.json：将 enabled 改为 true，recipientQQ 填成自己的收件 QQ 号字符串；gatewayUrl 填本机网关地址；sourceRoots 仅允许专门存放待发送产物的目录。

{
  "enabled": true,
  "recipientQQ": "YOUR_QQ",
  "gatewayUrl": "http://127.0.0.1:3000",
  "sourceRoots": ["D:/agent-output"]
}

YOUR_QQ 是占位符，必须替换才能运行。网关地址只接受 127.0.0.1 或 [::1] 的 HTTP 根地址，不接受域名、路径、查询参数或 URL 内凭据。

$env:FILE_SECRETARY_HOME = 'D:\file-sender-home'
$env:ONEBOT_ACCESS_TOKEN = '填入你本机网关的访问令牌'
node .\src\cli.js --file D:\agent-output\report.pdf --prepare-only

此时只创建文件副本，尚未发出。记录返回的 deliveryId，按用户发送指令继续：

node .\src\cli.js --send-id <deliveryId>
node .\src\cli.js --status <deliveryId>

也可以用 --file <绝对路径> 直接准备并发送。CLI 会在网络请求前打印记录 ID，中途退出后应先用该 ID 查状态。没有鉴权的网关可省略 ONEBOT_ACCESS_TOKEN；推荐启用网关鉴权。

Linux/macOS 的路径和环境变量语法需要相应替换。所有运行数据写在 FILE_SECRETARY_HOME；想节省系统盘空间，就把它和产物目录设在其他磁盘。

在 QQ 私聊中找文件（可选）

按 QQ 查找配置与操作流程 设置允许目录、群名单、search.enabled 和 search.receivePrivateMessages，在 SnowLuma 开启本机正向 OneBot WebSocket 事件接口，然后运行：

npm run listen

用配置的收件 QQ 私聊机器人：

找文件 项目报告 pdf
找群文件 高数 复习
发送第2个
文件状态
取消找文件

只有明确要求“发给我”、结果唯一且搜索完整时才直接发送，否则先列候选。按文件名匹配，不读取文档正文理解内容；多候选最多列 6 个，10 分钟内可选择。目录与群名单可以随时撤销；陌生人和群聊不能调用此入口。

接入 MCP

只向可信本机工作 Agent开放。不要挂载到任意群成员或陌生人可以触发的聊天 Agent。

支持通用 stdio MCP 配置的客户端可参考：

{
  "mcpServers": {
    "snowluma-file-sender": {
      "command": "node",
      "args": ["D:/tools/snowluma-qq-file-sender/src/mcp.js"],
      "env": {
        "FILE_SECRETARY_HOME": "D:/file-sender-home",
        "ONEBOT_ACCESS_TOKEN": "YOUR_LOCAL_GATEWAY_TOKEN"
      }
    }
  }
}

替换项目路径和令牌。客户端启动时须能找到 Node.js 24+；必要时把 command 写成 node.exe 的绝对路径。Codex 的 TOML 示例和 DeepSeek Harness 接入说明见 Agent 流程。

用户提示词示例：“把刚生成的 D:/agent-output/report.pdf 用 SnowLuma 发给我。”Agent 应准备并发送同一 ID，不能先把 PDF 读成文本或 base64 交给模型。此工具不保证任意客户端支持 MCP，也不能在客户端关闭时唤醒它。

状态和恢复

同一记录再次调用发送不会重复发起已开始或已完成的上传。异常退出留下的锁不会自动删除。这不是端到端“恰好一次”保证：换 ID、新建副本、删除状态目录都可能造成重复。unknown 或 sending 不能通过重新 prepare 绕过，必须先由人核实收件 QQ。

自动清理在下一次准备文件时运行：未发送副本保留 24 小时，已受理/过期记录保留 7 天；有发送锁、unknown、sending 记录继续保留。总计最多 64 条、128MiB，每个文件最多 32MiB。不确定记录长期占用额度时应人工核实后清理；本工具不提供一键重置或自动补发。

文件和隐私边界

• 源文件必须位于配置的允许目录内；真实路径也须在范围内，链接不能指向范围外。

• 配置、常见凭据文件、框架私有状态目录等名称被拦截。这只是额外护栏，不能识别任意文件内的秘密；只应将用户明确同意发送的产物放进允许目录。

• 准备时复制并计算 SHA-256，发送前复核副本；准备后的收件人或网关变更会阻止上传。

• 本地配置、暂存文件和元数据可能含有私人信息，应保护 FILE_SECRETARY_HOME，不要提交 Git。网关及 QQ 平台会处理实际文件内容。

• MCP 结果含文件名、大小、散列和收件人，可能被使用它的 AI 客户端记录；不返回文件正文、本地源路径或访问令牌。不收集聊天历史或遥测。

• 这不是抵御同一系统账号下恶意进程的沙箱；目录与配置应仅供可信用户维护。

同类项目与定位

这是一个范围较窄的可复用工具，不宣称首创 QQ 文件发送、防重发或文件校验。

比较依据为这些项目截至 2026-10-23 的公开文档，没有对全部项目做实机性能或可靠性排名。设计说明 记录接口依据与取舍。

开发与维护

npm ci --ignore-scripts
npm test

测试使用临时目录和模拟网关，不会发送真实 QQ 文件。维护者请先读 AGENTS.md、变更记录 和 设计说明。MIT 许可；来源与第三方边界见 NOTICE 和 LICENSE。