upload_private_file
Send a local file as a private chat attachment to a QQ friend by specifying their QQ ID, absolute file path, and display filename with extension. Use for documents, PDFs, or archives.
Instructions
将本机磁盘上的文件作为私聊附件发送给指定 QQ 好友 (NapCat OneBot 11: upload_private_file)。
适用场景:向个人 QQ 好友交付文档、表格、PDF 或压缩包等本地文件。不适用与替代:若需将文件上传至 QQ 群共享空间,请改用 upload_group_file;若仅需发送纯文本或图片消息段,请改用 send_private_msg。
参数约束与交互:file_path 必须为当前机器上已存在且可读的本地绝对路径(如 D:/Desktop/report.xlsx);file_name 应包含正确的文件扩展名以便接收方客户端识别打开。
行为与返回:非幂等外部文件传输操作(默认超时 120 秒以支持大文件上传);前置要求当前账号已在线且目标为好友,成功返回 status='ok',若本地文件不存在、超出大小限制或非好友则返回非 0 retcode。
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"user_id": "<user_id>",
"file_path": "<file_path>",
"file_name": "<file_name>"
},
"name": "upload_private_file"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | Yes | 接收方好友的 QQ 号(5~11 位正整数) | |
| file_name | Yes | 对方在私聊窗口中看到的显示文件名(须含扩展名,如 'report.xlsx') | |
| file_path | Yes | 待发送本地文件的完整绝对路径(文件必须真实存在且可读) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | 接口返回的业务负载数据(对象或数组,具体字段依工具而定) | |
| status | No | 执行状态标识,成功为 'ok'(或特定生命周期状态),失败为 'failed' 或 'error' | |
| message | No | 状态说明或错误诊断详情 | |
| retcode | No | OneBot 11 响应状态码,0 表示成功,非 0 表示协议端或网络错误 |