mailcode 0.1.0__tar.gz

mailcode-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zsdfbb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailcode-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mailcode
+Version: 0.1.0
+Summary: Email ↔ AI Agent bidirectional remote command bridge
+License: MIT
+Requires-Python: >=3.9
+License-File: LICENSE
+Dynamic: license-file

mailcode-0.1.0/README.md

@@ -0,0 +1,151 @@
+# MailCode
+
+Python 邮件连接器，通过邮件远程操控 Claude Code。
+
+```
+收件箱 ──> IMAP 监听器 ──> claude -p 子进程 ──> SMTP 邮件通知
+```
+
+## 设计理念
+
+MailCode 的核心理念是**轻量化的人与 Coding Agent 直连**。
+
+市面上的 AI 工具链往往依赖飞书、钉钉等重型协作平台——建机器人、配 Webhook、在对话框里和 Agent 来回聊天。MailCode 反其道而行：直接用邮件，因为你本来就有一个邮箱。
+
+**人与 Agent 直连，而不是和机器人对话。** 回复邮件就是下达指令，收件箱就是控制台,不需要打开任何第三方应用。
+
+**轻量异步。** 不需要常驻复杂服务，不需要数据库，不需要消息队列。一个 Python 脚本 + 邮件协议，跑在任何能联网的机器上。Agent 在后台慢慢跑，你做别的事，完事了邮件通知你。
+
+MailCode 不做大而全的平台，只做一件事：**让你用最习惯的方式（邮件）和  Agent 对话。**
+
+## 安装
+
+### 系统依赖
+
+- **python3**（≥3.9）
+- **Claude Code**（`claude` 命令需在 `PATH` 中）
+
+Python 零第三方依赖，全部使用标准库（`imaplib`、`smtplib`、`email`、`subprocess`、`json`、`secrets` 等）。
+
+### pip 安装
+
+```bash
+pip install mailcode
+```
+
+### 源码安装
+
+```bash
+git clone <repo-url> && cd MailCode
+bash install.sh
+```
+
+`install.sh` 自动完成：安装 mailcode 包、初始化配置、创建 `~/.mailcode` 软链接、自动添加 PATH。
+
+从本地 wheel 安装：`bash install.sh --local dist/mailcode-*.whl`
+
+## 配置
+
+编辑 `~/.config/mailcode/config.json`，必填字段：
+
+```jsonc
+{
+  "mailcode_bot": {
+    "email": "your@qq.com",       // ← 你的邮箱，MailCode 监听此邮箱收件箱
+    "password": "邮箱授权码"          // ← 不是登录密码！
+  },
+  "security": {
+    "allowed_senders": ["your@qq.com"]  // 哪些邮箱能发命令？填你自己的
+  }
+}
+```
+
+SMTP 和 IMAP 配置由系统根据邮箱域名自动识别。支持：QQ 邮箱、163/126 邮箱、Gmail、Outlook/Hotmail。
+
+如需手动覆盖 SMTP/IMAP（如自建邮箱），可添加 `smtp` / `imap` 段，手动设置的值会覆盖自动识别结果。
+
+> 授权码获取：QQ 邮箱 → 设置 → 账户 → POP3/IMAP → 生成授权码；Gmail → Google 账户 → 安全性 → 应用密码。
+
+## 使用
+
+### CLI 概览
+
+| 子命令 | 用途 |
+|--------|------|
+| `mailcode serve` | 启动 IMAP 监听中继 |
+| `mailcode config <动作>` | 配置管理（`show` / `init` / `init-test` / `path` / `validate`）|
+| `mailcode health` | 邮件连通性检查（SMTP/IMAP）|
+| `mailcode session <动作>` | 会话管理（`list` / `show` / `delete` / `cleanup`）|
+| `mailcode --version` | 显示版本号 |
+
+### 启动中继
+
+```bash
+# 前台运行（IDLE 长连接模式）
+mailcode serve --idle
+
+# 干跑模式（仅打印邮件，不调用 claude）
+mailcode serve --idle --dry-run
+
+# 单次轮询后退出
+mailcode serve --once
+```
+
+查看日志：
+
+```bash
+tail -f ~/.config/mailcode/relay.log
+```
+
+### 配置管理
+
+```bash
+mailcode config show          # 查看当前配置（密码脱敏）
+mailcode config path          # 显示配置文件路径
+mailcode config init          # 初始化配置（已存在则跳过）
+mailcode config init --force  # 强制重新生成
+mailcode config validate      # 校验配置完整性
+```
+
+### 会话管理
+
+MailCode 默认按邮件主题维护多轮对话; 如需单次回复模式请设 `session.enabled = false`。
+
+```bash
+mailcode session list                # 列出所有 session
+mailcode session show <session_id>   # 查看单个 session 详情
+mailcode session delete <session_id> # 删除 session
+mailcode session cleanup             # 按 TTL 清理过期 session
+mailcode session cleanup --dry-run   # 仅预览，不实际删除
+```
+
+### 工作目录 (cwd 指令)
+
+在邮件正文**第一行**写 `cwd: <path>`，Claude 子进程会在该目录启动——适合「让 Claude 操作指定项目」。Session 模式下 cwd **粘性**：同一 session 内的后续邮件会沿用该目录，直到新邮件重新指定。
+
+```
+cwd: ~/Projects/my-app
+帮我看看 src/auth.py 里那段 JWT 校验逻辑
+```
+
+**路径解析规则**：
+
+- `~` / `~/foo` 走用户目录展开
+- 相对路径（`./foo`、`foo`）以 `Path.cwd()` 为基准
+- 路径必须存在且是目录（`is_dir()` 校验），否则忽略并回退默认（`$HOME`）
+- 写法不区分大小写，`Cwd:` / `CWD:` 等价
+
+**两种模式差异**：
+
+- **Session 模式**（`session.enabled = true` 默认）：cwd 粘性，整个 session 沿用；`mailcode session show <id>` 可查当前 cwd
+- **单次回复模式**（`session.enabled = false`）：cwd 不粘性，每封邮件独立解析
+
+cwd 行会在调用 Claude 前从 body 中剥离，不会污染 prompt。
+
+### 健康检查
+
+```bash
+mailcode health    # 检查 SMTP/IMAP 配置与连通性
+```
+
+检查项：SMTP 连接 / 登录 / 发信、IMAP 连接 / 登录 / 收件箱。

mailcode-0.1.0/mailcode/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mailcode-0.1.0/mailcode/channels/__init__.py

@@ -0,0 +1,3 @@
+from .email_channel import EmailChannel
+
+__all__ = ["EmailChannel"]

mailcode-0.1.0/mailcode/channels/email_channel.py

@@ -0,0 +1,144 @@
+import smtplib
+import logging
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from email.header import Header
+from typing import Optional
+import email.utils
+
+from mailcode.config import get_smtp_config, get_email_config
+
+logger = logging.getLogger(__name__)
+
+
+class EmailChannel:
+    def __init__(self, smtp_config=None, email_config=None):
+        self.smtp_config = smtp_config or get_smtp_config()
+        self.email_config = email_config or get_email_config()
+        self.smtp_user = self.smtp_config.get("user", "")
+        self.smtp_pass = self.smtp_config.get("pass", "")
+
+    def _create_connection(self) -> bool:
+        host = self.smtp_config.get("host", "smtp.gmail.com")
+        port = self.smtp_config.get("port", 587)
+        secure = self.smtp_config.get("secure", False)
+
+        try:
+            if secure:
+                self._server = smtplib.SMTP_SSL(host, port, timeout=15)
+            else:
+                self._server = smtplib.SMTP(host, port, timeout=15)
+                self._server.starttls()
+            return True
+        except Exception as e:
+            logger.error("SMTP 连接失败: %s", e)
+            return False
+
+    def send(
+        self,
+        to_email: Optional[str] = None,
+        subject: str = "",
+        body: str = "",
+        token: Optional[str] = None
+    ) -> bool:
+        from_email = self.email_config.get("from", self.smtp_user)
+        from_name = self.email_config.get("from_name", "Mailcode Remote")
+        to_email = to_email or ""
+
+        if not from_email or not self.smtp_user:
+            raise ValueError("SMTP 配置不完整，请检查配置文件中的 mailcode_bot.email")
+
+        msg = MIMEMultipart()
+        msg["From"] = f"{from_name} <{from_email}>"
+        msg["To"] = to_email
+        msg["Subject"] = Header(subject, "utf-8")
+
+        if token:
+            msg["X-MailCode-Remote-Token"] = token
+
+        msg.attach(MIMEText(body, "plain", "utf-8"))
+
+        try:
+            if not self._create_connection():
+                return False
+            self._server.login(self.smtp_user, self.smtp_pass)
+            self._server.sendmail(from_email, [to_email], msg.as_string())
+            return True
+        except Exception:
+            logger.exception("邮件发送失败")
+            return False
+        finally:
+            try:
+                if getattr(self, "_server", None):
+                    self._server.quit()
+            except Exception:
+                pass
+
+    def send_reply(
+        self,
+        to_email: str,
+        subject: str,
+        body: str,
+        in_reply_to_msg_id: Optional[str] = None,
+        references: Optional[str] = None,
+    ) -> tuple[bool, Optional[str]]:
+        """发送带线程追踪的回复邮件。
+
+        在 send() 基础上添加 In-Reply-To 和 References 邮件头，
+        实现邮件线程的层级追踪。
+
+        Args:
+            to_email: 收件人地址
+            subject: 邮件主题
+            body: 邮件正文
+            in_reply_to_msg_id: 被回复邮件的 Message-ID
+            references: 被回复邮件的 References 头内容（可选）
+
+        Returns:
+            (success: bool, message_id: Optional[str])
+        """
+        from_email = self.email_config.get("from", self.smtp_user)
+        from_name = self.email_config.get("from_name", "Mailcode Remote")
+        to_email = to_email or ""
+
+        if not from_email or not self.smtp_user:
+            raise ValueError("SMTP 配置不完整，请检查配置文件中的 mailcode_bot.email")
+
+        msg = MIMEMultipart()
+        msg["From"] = f"{from_name} <{from_email}>"
+        msg["To"] = to_email
+        msg["Subject"] = Header(subject, "utf-8")
+
+        # 生成当前邮件的 Message-ID
+        domain = from_email.split("@")[-1] if "@" in from_email else "mailcode"
+        message_id = email.utils.make_msgid(domain=domain)
+        msg["Message-ID"] = message_id
+        msg["Date"] = email.utils.formatdate(localtime=True)
+
+        # 设置线程追踪头
+        if in_reply_to_msg_id:
+            msg["In-Reply-To"] = in_reply_to_msg_id
+            ref_parts: list[str] = []
+            if references:
+                ref_parts.append(references)
+            ref_parts.append(in_reply_to_msg_id)
+            msg["References"] = " ".join(ref_parts)
+
+        msg.attach(MIMEText(body, "plain", "utf-8"))
+
+        try:
+            if not self._create_connection():
+                return False, None
+            self._server.login(self.smtp_user, self.smtp_pass)
+            self._server.sendmail(from_email, [to_email], msg.as_string())
+            return True, message_id
+        except Exception:
+            logger.exception("邮件发送失败")
+            return False, None
+        finally:
+            try:
+                if getattr(self, "_server", None):
+                    self._server.quit()
+            except Exception:
+                pass
+