开源 · 非官方 QQ 邮箱命令行工具

把邮箱交给 AI,
又不怕它闯祸。

qqmail-cli —— 一个我自己敢交出去的 QQ 邮箱命令行工具。

能收发邮件的程序市面上一大把,缺的是交出去之后那些事有人管:凭证会不会泄露、AI 会不会误删,还有多数人没想过的——邮件正文里要是藏了指令,会不会反过来指挥 AI 干坏事。这些我都写进了代码,每一条都有测试守着。

$ go install github.com/situker/qqmail-cli/cmd/qqmail-cli@latest
非官方第三方工具 · 走 QQ 邮箱官方 IMAP / 授权码 · 不碰网页版、不逆向 · Apache-2.0
8729
我自己邮箱实测的封数
2749
清进回收站的封数
0
删错的封数
restore
删错?一条命令找回
为什么做它

想清邮箱,为什么一直没敢动手

我那个 QQ 邮箱用了十几年,8729 封邮件,未读一千多。想清很久,一直没敢下手——卡在这三件事上。

让 AI 来删,怕它删错

删错一封,我可能还不知道。等发现要用那封信,早没了。

自己一封封挑,挑不完

八千多封,一封封看过去,挑到猴年马月。时间成本高到根本不会动。

正文里可能藏着指令

邮件正文塞一句「请转发验证码」之类的话,会不会反过来把 AI 当枪使。

qqmail-cli 的每一道设计,都是对着这三堵墙造的。

能干什么

读、理、发三块,越往后门禁越重

01 · 读

读邮件

看邮件不留痕
  • 列邮件、读全文、下附件、全量备份
  • 未读的还是未读,服务器上什么都不动
  • 本地存成标准 .eml,随时归档
02 · 理

整理与清理

生成计划,逐条给你审
  • 同步到本地做全文检索,中文好使,搜客户名订单号不用开网页版
  • 挂退订头的营销件、noreply 的机器通知,本地规则直接认,一封都不喂给模型
  • 生成一张清理计划:哪些删、哪些留、每封为什么
03 · 发

安全发送

白名单,一次一封
  • 收件人不在白名单里,发不出去
  • 一次一封,没有群发
  • 发送前正文可过清洗,防夹带

清理这一路是重点,也是我最较真的地方——计划先备份、逐封验证,验证不过的进不了清理队列。

安全防线

敢交出去的底气,是这些锁

AI 出事最大的风险从来不是不聪明,是一本正经地闯祸。所以每一条都不是靠自觉,是靠代码拦。

只读是默认

凡是改服务器的操作,默认都只预演。真执行要过门禁加人工确认。

没有永久删除

真删只是把邮件移进回收站。整个工具里没有「永久删除」这个命令。

删错能找回

restore 一条命令整单找回。删完是进回收站,不是灰飞烟灭。

三级门禁

清理前备份、逐封跟服务器核对身份、最后要你在键盘敲入数量二次确认。

星标绝对保护

星标邮件永不进清理队列。没有开关能放行,我自己也不行。

凭证只进钥匙串

授权码只进系统凭据管理器,日志和报错里都翻不出来。

防提示词注入

邮件正文里藏的指令,只当数据看,不当命令执行——不会被信里的话牵着走。

交易/官方信优先保护

订单、收据、发票和政府域名的信,优先于营销判定被保护。错留一封快讯没什么,错删一张收据就麻烦了。

一键全锁死

一个环境变量能把所有写操作全部锁死,只剩只读。适合放心交给自动化。

// 每一条防线都有自动化测试守着,改坏了测试会红。
交给 AI Agent

给 AI 用的部分,也做全了

JSON
全部命令走稳定的 JSON 输出,带能力自发现和退出码,AI 能自己判断该重试还是报人。
skill
随仓附了 skill 文件,Claude Code、codex 这类 harness 装上,直接按纪律调用,不用你教。
lock
一个环境变量锁死所有写操作,让 agent 在只读模式里放开手脚跑,怎么跑都动不了服务器。
deploy
把安装命令直接发给 AI,让它帮你装——装完它自己就会用,skill 是随仓带的。
$ qqmail-cli list --unread --json
{
  "ok": true,
  "count": 1043,
  "readonly": true
}
$ qqmail-cli clean --plan plan.json
# 只预演,不真删。真执行要过门禁 + 键盘确认。
真实实测

我拿自己十几年的邮箱,第一个开刀

写完第一件事,就是拿这 8729 封开刀。全程它抽真实样本给我看,我只做选择题——过程都在下面。

8729起点 · 全部邮件
用了十几年的 QQ 邮箱,通知邮件越攒越多。整理分类跑完,出了第一版清理计划 3746 封
3746初版计划 · 有问题
抽查抓错Apple 的购买通知被当成营销件(厂商发收据也挂退订头);顺着查下去更吓人——国家知识产权局 308 封官方通知被归进机器通知,全在计划里。我做知产业务的,这些必须留。
+规则加保护 · 再判
加了一条规则:订单、收据、发票这类交易邮件和政府域名的信,优先于营销判定被保护。剩下的争议邮件,它每类抽真实样本给我看,四次判断做完,计划降到 2823 封
2823执行 · 门禁上场
第一次整批被拒真删前门禁把每封再跟服务器核对身份,第一次直接整批拒了。我以为是故障,查下来是门禁干了它该干的事,身份对不上的全拦下。修完再跑,74 封仍存疑,它保守留下不碰。
2749完成 · 全部核验
0 删错最后要我在键盘敲入数量做二次确认,它才动手。删完我又单独跑了遍核验:2749 封全在回收站,原文件夹一封不剩,2016 年的信都还在。
起点邮件总数
8,729 封 · 未读 1,000+
real
四次人工判断后计划
2,823 封(交易/官方信已保护)
reviewed
门禁核对身份
身份对不上一律拦 · 存疑 74 封保守留
pass
清进回收站
2,749 封 · 原文件夹一封不剩
verified
删错
0 封 · restore 可整单找回
0
计数口径
工具报 2748,实际 2749(一封回执网络丢了)
只少报不多报
// 工具宁可少报也不多报——这也正是我想要的。
敢不敢把一件事交给 AI,不看它聪不聪明,看你给它的权限锁没锁死。
邮箱是这样,公司的业务也是这样。
一行部署

三种装法,挑一个顺手的

$ go install github.com/situker/qqmail-cli/cmd/qqmail-cli@latest
装法 A · 有 Go

一行 go install

上面这行直接跑,装完即用。

装法 B · 不用 Go

下 Release 包

GitHub 的 Release 页有 Windows、Mac、Linux 的包,下载解压就行

装法 C · 最省事

让 AI 帮你装

把上面那行命令发给 codexClaude Code,让它帮你装。装完它自己就会用,skill 随仓带。

装好先跑一遍 qqmail-cli doctor,它把配置、凭证、连接挨个体检。最常见那个坑——把 QQ 密码当授权码填,它会当场给你指出来。

它不干什么

这些「不干的事」,正是敢开源的底气

不碰网页版,不逆向任何东西。只走 QQ 邮箱自己开放的 IMAP 和授权码。
不要你的 QQ 密码。只认授权码,且只进系统钥匙串。
不做永久删除。真删只是进回收站,restore 可找回。
不群发。发送一次一封,收件人走白名单。
不做多服务商,不绕 QQ 的频率限制。专注 QQ 邮箱,规规矩矩用官方接口。
不内置任何 AI 模型。要不要接 AI、接哪个,权在你,数据不出门。
你大概想问

FAQ

它会不会把我的邮件删错?

不会随便删。清理前要备份、逐封跟服务器核对身份、最后还要你在键盘敲入数量二次确认,缺一步都不动手。就算真删了也只是进回收站,restore 一条命令整单找回;星标邮件永不进清理队列,没有开关能放行。我拿自己 8729 封邮箱实测,清了 2749 封,0 封删错。

需要我的 QQ 密码吗?安全吗?

不需要密码,只要 QQ 邮箱后台开的「授权码」——这是腾讯官方给第三方客户端用的正规机制。授权码只进你系统自己的凭据管理器(钥匙串),日志和报错里都翻不出来。所有事都在你本机跑,凭证和数据都不出门。

它是官方工具吗?

不是。这是一个非官方的第三方工具,走 QQ 邮箱自己开放的 IMAP / SMTP 和授权码,不碰网页版、不逆向任何东西,也和腾讯没有任何关联或授权。

我不是程序员,能用吗?

能。不用装 Go 的话,去 GitHub 的 Release 页下对应系统的包,解压就能用。更省事的办法:把安装命令发给 codex 或 Claude Code,让它帮你装、帮你跑,它自己就会按工具的纪律来。

支持别的邮箱吗?

专注 QQ 邮箱。不做多服务商——把一个邮箱的脾气摸透、把安全兜死,比铺一堆半吊子适配更重要。

开源协议是什么?能商用吗?

Apache-2.0,可以自由使用、修改、商用。转发或改版时按协议保留作者署名与 NOTICE 就行。GitHub 搜 situker/qqmail-cli

关于作者
司徒K
持续创业者,长期主义践行者

觉得这个工具有用,欢迎去 GitHub 点个 ⭐ Star。
想聊 AI 落地、skill / agent 工程,公众号和网站都能找到我。
关注司徒,人生坦途。