{"id":51174966,"url":"https://github.com/zsdfbb/mailcode","last_synced_at":"2026-06-27T03:04:12.473Z","repository":{"id":364090216,"uuid":"1220955378","full_name":"zsdfbb/mailcode","owner":"zsdfbb","description":"Use email to connect your coding agnets！ I use mailcode to develop mailcode.","archived":false,"fork":false,"pushed_at":"2026-06-23T15:15:20.000Z","size":370,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-23T17:15:40.770Z","etag":null,"topics":["agent","ai","claude","code","email","llm","mail","opencode"],"latest_commit_sha":null,"homepage":"http://www.mailcode.site","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zsdfbb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-25T15:04:28.000Z","updated_at":"2026-06-23T15:15:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zsdfbb/mailcode","commit_stats":null,"previous_names":["zsdfbb/mailcode"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zsdfbb/mailcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsdfbb%2Fmailcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsdfbb%2Fmailcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsdfbb%2Fmailcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsdfbb%2Fmailcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zsdfbb","download_url":"https://codeload.github.com/zsdfbb/mailcode/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zsdfbb%2Fmailcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34839893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","claude","code","email","llm","mail","opencode"],"created_at":"2026-06-27T03:04:11.561Z","updated_at":"2026-06-27T03:04:12.465Z","avatar_url":"https://github.com/zsdfbb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MailCode\n\nPython 邮件连接器，通过邮件远程操控 AI 助手（Claude Code / OpenCode）。\n\n```\n收件箱 ──\u003e IMAP 监听器 ──\u003e claude -p 子进程 ──\u003e SMTP 邮件通知\n```\n\n## 设计理念\n\nMailCode 的核心理念是**轻量化的人与 Coding Agent 直连**。\n\n市面上的 AI 工具链往往依赖飞书、钉钉等重型协作平台——建机器人、配 Webhook、在对话框里和 Agent 来回聊天。MailCode 反其道而行：直接用邮件，因为你本来就有一个邮箱。\n\n**人与 Agent 直连，而不是和机器人对话。** 回复邮件就是下达指令，收件箱就是控制台,不需要打开任何第三方应用。\n\n**轻量异步。** 不需要常驻复杂服务，不需要数据库，不需要消息队列。一个 Python 脚本 + 邮件协议，跑在任何能联网的机器上。Agent 在后台慢慢跑，你做别的事，完事了邮件通知你。\n\nMailCode 不做大而全的平台，只做一件事：**让你用最习惯的方式（邮件）和 Agent 对话。**\n\n## 邮箱账户架构\n\nMailCode 需要 **两个邮箱账户**——一个当 Bot，一个当用户：\n\n- **Bot 邮箱**（例：`mailcode_bot@xxx.com`）—— MailCode 监听它的收件箱，AI 处理完任务后通过它把结果发回给你\n- **用户邮箱**（你的私人邮箱，例：`your@qq.com`）—— 你从这个邮箱向 Bot 邮箱发邮件下达指令\n\n工作流：\n\n```\n[用户邮箱]  ──发指令邮件──▶  [Bot 邮箱收件箱]\n  your@qq.com                  mailcode_bot@xxx.com\n                                      │\n                                      ▼\n                                 IMAP 监听\n                                      │\n                                      ▼\n                                 AI 处理\n                                      │\n                                      ▼\n  [用户邮箱]  ◀──回复邮件──  [Bot 邮箱发件箱]\n```\n\n\u003e **为什么是 Bot 邮箱而不是你自己的主邮箱？** MailCode 要登录一个邮箱才能收信和发信，所以需要一个专用 Bot 邮箱；它和你日常使用的邮箱是分开的，配置 `allowed_senders` 限制只有你自己的私人邮箱能给它发指令。\n\n## 安装\n\n### 系统依赖\n\n- **python3**（≥3.9）\n- **Claude Code** 或 **OpenCode**（`claude` / `opencode` 命令需在 `PATH` 中）\n\nPython 零第三方依赖，全部使用标准库（`imaplib`、`smtplib`、`email`、`subprocess`、`json`、`secrets` 等）。\n\n### pip 安装\n\n```bash\npip install mailcode\n```\n\n### 源码安装\n\n```bash\ngit clone \u003crepo-url\u003e \u0026\u0026 cd MailCode\nbash install.sh\n```\n\n`install.sh` 自动完成：安装 mailcode 包、初始化配置、创建 `~/.mailcode` 软链接、自动添加 PATH。\n\n从本地 wheel 安装：`bash install.sh --local dist/mailcode-*.whl`\n\n## 配置\n\n编辑 `~/.config/mailcode/config.json`，必填字段。**两个邮箱要分清楚**——`mailcode_bot.email` 是 Bot 邮箱，`security.allowed_senders` 是允许给它发指令的邮箱（通常是你自己的私人邮箱）：\n\n```jsonc\n{\n  \"mailcode_bot\": {\n    \"email\": \"mailcode_bot@xxx.com\",    // ← Bot 邮箱：MailCode 登录此邮箱收信/回信\n    \"password\": \"Bot 邮箱授权码\",          // ← Bot 邮箱的授权码，不是登录密码\n    \"check_interval\": 60                  // ← 轮询间隔(秒); 163/126 推荐 60-120\n  },\n  \"security\": {\n    \"allowed_senders\": [\"your@qq.com\"]    // ← 允许发指令的邮箱（你的私人邮箱）\n  }\n}\n```\n\nSMTP 和 IMAP 配置由系统根据 Bot 邮箱的域名自动识别。支持：QQ 邮箱、163/126 邮箱、Gmail、Outlook/Hotmail。\n\n如需手动覆盖 SMTP/IMAP（如自建邮箱），可添加 `smtp` / `imap` 段，手动设置的值会覆盖自动识别结果。\n\n\u003e 授权码获取：QQ 邮箱 → 设置 → 账户 → POP3/IMAP → 生成授权码；Gmail → Google 账户 → 安全性 → 应用密码。\n\n## 使用\n\n### CLI 概览\n\n| 子命令 | 用途 |\n|--------|------|\n| `mailcode serve` | 启动 IMAP 监听中继（含定时任务调度器、控制台实时事件输出）|\n| `mailcode chat` | 终端交互模式，直接与 AI 对话（不经过邮件）|\n| `mailcode schedule \u003c动作\u003e` | 定时任务管理（`list` / `show` / `add` / `enable` / `disable` / `delete` / `run-now` / `validate`）|\n| `mailcode config \u003c动作\u003e` | 配置管理（`show` / `init` / `init-test` / `path` / `validate`）|\n| `mailcode health [--send]` | 邮件连通性检查（SMTP/IMAP；`--send` 发送测试邮件验证发信）|\n| `mailcode session \u003c动作\u003e` | 会话管理（`list` / `show` / `delete` / `cleanup` / `stats`）|\n| `mailcode --version` | 显示版本号 |\n\n### 启动中继\n\n```bash\n# 前台运行（默认 IMAP IDLE 长连接, 单连接撑全场, 实时收信）\n# 运行中有实时事件输出: 📬 收到邮件  →  🤖 调 AI  →  ✅ 回复已发送\nmailcode serve\n\n# 干跑模式（仅打印邮件, 不调用 AI）\nmailcode serve --dry-run\n\n# 强制走轮询（不用 IDLE; 部分老旧邮箱要求）\nmailcode serve --no-idle\n\n# 单次轮询后退出\nmailcode serve --once\n```\n\n**IMAP IDLE 支持按邮箱而异**——MailCode 启动时检测 `IMAP CAPABILITY`, 没有 IDLE 就自动回退到轮询:\n\n| 邮箱 | IDLE | 行为 | 推荐 `check_interval` |\n|------|------|------|----------------------|\n| QQ 邮箱 (`imap.qq.com`) | ✅ | 实时推送, 秒级响应 | 60s（轮询时）|\n| 163/126 邮箱 (`imap.163.com` / `imap.126.com`) | ❌ | 自动回退到轮询, warning 日志告知 | **60-120s**（频率过高会被反滥用限速, 严重时封 IP）|\n| Gmail / Outlook | ✅ | 实时推送 | 60s（轮询时）|\n\n网易系邮箱**不支持 IDLE 扩展**, 频繁 IMAP 登录会触发反滥用。Bot 邮箱若用 163/126, 务必把 `mailcode_bot.check_interval` 调到 60-120 秒, 否则几小时内可能被临时封禁。\n\n查看日志：\n\n```bash\ntail -f ~/.config/mailcode/relay.log\n```\n\n### 配置管理\n\n```bash\nmailcode config show          # 查看当前配置（密码脱敏）\nmailcode config path          # 显示配置文件路径\nmailcode config init          # 初始化配置（已存在则跳过）\nmailcode config init --force  # 强制重新生成\nmailcode config validate      # 校验配置完整性\n```\n\n### 终端对话（Chat）\n\n无需经过邮件，直接在终端启动交互式 REPL 与 AI 对话：\n\n```bash\nmailcode chat                    # 启动新对话\nmailcode chat --session-id \u003cid\u003e  # 恢复已有 session 继续对话\nmailcode chat --cwd ~/my-project # 指定工作目录\n```\n\n适合快速调试或不想走邮件链路的场景。支持恢复 `serve` 中创建的 session（反之亦然）。\n\n### 会话管理\n\nMailCode 默认按邮件主题维护多轮对话；如需单次回复模式请设 `session.enabled = false`。\n\n```bash\nmailcode session list                          # 列出全部 session\nmailcode session list --wide                   # 不截断显示（完整发件人/主题）\nmailcode session list --filter \"关键词\"        # 按发件人或主题过滤\nmailcode session show \u003csession_id\u003e             # 查看单个 session 完整邮件流\nmailcode session delete \u003csession_id\u003e           # 删除 session\nmailcode session stats                         # 统计信息（总数 / 活跃 / 过期）\nmailcode session cleanup                       # 按 TTL 清理过期 session\nmailcode session cleanup --dry-run             # 仅预览，不实际删除\n```\n\n### 工作目录 (cwd 指令)\n\n在邮件正文**第一行**写 `cwd: \u003cpath\u003e`，AI 子进程会在该目录启动——适合「让 AI 操作指定项目」。Session 模式下 cwd **粘性**：同一 session 内的后续邮件会沿用该目录，直到新邮件重新指定。\n\n```\ncwd: ~/Projects/my-app\n帮我看看 src/auth.py 里那段 JWT 校验逻辑\n```\n\n**路径解析规则**：\n\n- `~` / `~/foo` 走用户目录展开\n- 相对路径（`./foo`、`foo`）以 `Path.cwd()` 为基准\n- 路径必须存在且是目录（`is_dir()` 校验），否则忽略并回退默认（`$HOME`）\n- 写法不区分大小写，`Cwd:` / `CWD:` 等价\n\n**两种模式差异**：\n\n- **Session 模式**（`session.enabled = true` 默认）：cwd 粘性，整个 session 沿用；`mailcode session show \u003cid\u003e` 可查当前 cwd\n- **单次回复模式**（`session.enabled = false`）：cwd 不粘性，每封邮件独立解析\n\ncwd 行会在调用 AI 前从 body 中剥离，不会污染 prompt。\n\n### 健康检查\n\n```bash\nmailcode health        # 检查 SMTP/IMAP 配置与连通性\nmailcode health --send # 额外发送一封测试邮件验证发信通道\n```\n\n检查项：SMTP 连接 / 登录 / 发信、IMAP 连接 / 登录 / 收件箱、**发件人白名单是否为空**（serve 时白名单为空会拒绝所有邮件）。\n\n### 定时任务\n\nMailCode 内置轻量定时任务引擎，无需外部 cron 或 systemd timer——直接在 `mailcode serve` 内跑，配置持久化到 `~/.config/mailcode/schedules.json`。\n\n支持四种调度类型：\n\n| 类型 | 参数 | 示例 |\n|------|------|------|\n| `interval` | `--interval-seconds \u003c秒\u003e` | 每 3600 秒运行一次 |\n| `daily` | `--time \u003cHH:MM\u003e` | 每天 09:00 运行 |\n| `weekly` | `--time \u003cHH:MM\u003e --day-of-week \u003c0-6\u003e` | 每周一 09:00（0=周日） |\n| `monthly` | `--time \u003cHH:MM\u003e --day-of-month \u003c1-31\u003e` | 每月 1 号 09:00 |\n\n定时任务会调用 `claude -p \u003cprompt\u003e` 执行指定指令，并将响应邮件发送给指定收件人。所有调度基于本地时间，错过触发窗口的任务自动跳过（不会追赶补跑）。\n\n```bash\n# 创建定时任务\nmailcode schedule add morning-digest --type daily --time 09:00 \\\n  --prompt \"总结 GitHub 通知, 列出今天待办\" \\\n  --to-email your@qq.com \\\n  --subject-prefix \"[晨间摘要]\"\n\n# 列出所有任务\nmailcode schedule list\n\n# 查看任务详情\nmailcode schedule show morning-digest\n\n# 立即执行一次（不污染调度统计）\nmailcode schedule run-now morning-digest\n\n# 启用 / 禁用\nmailcode schedule enable morning-digest\nmailcode schedule disable morning-digest\n\n# 删除\nmailcode schedule delete morning-digest\n\n# 校验所有任务配置\nmailcode schedule validate\n```\n\n**配置**（`~/.config/mailcode/config.json`，可选）：\n\n```jsonc\n{\n  \"schedule\": {\n    \"enabled\": true,         // 全局开关\n    \"tick_seconds\": 30       // 调度器轮询间隔\n  }\n}\n```\n\n**特点**：\n\n- **热加载**——通过 CLI 增删改任务后，运行中的 `serve` 进程立即生效，无需重启\n- **并发防护**——同一任务的上次执行未完成时，不会重复触发\n- **错误通知**——AI 调用或邮件发送失败时，自动通知收件人\n- **独立运行**——`mailcode schedule run-now` 不依赖 `serve` 进程，可单独使用\n- **干跑兼容**——`mailcode serve --dry-run` 下标记执行结果但不真实调用\n\n---\n\n[English version](README.en.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzsdfbb%2Fmailcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzsdfbb%2Fmailcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzsdfbb%2Fmailcode/lists"}