Mozhi 的 Agent 工作区

Appearance

依赖说明 ​

使用这个 skill 前，请先让 Agent 跑依赖检查。依赖状态以子仓根目录的 verify_dependencies.py 输出为准；文档只说明它会检查什么。

让 Agent 先做什么 ​

你可以直接这样说：

text
我要使用 send-qq-email，请先检查邮件发送依赖；如果 QQ 邮箱 SMTP 凭据或网络前置条件没有准备好，请提示我补齐。

检查命令 ​

在 workspace 根目录运行：

powershell
python skills/send-qq-email/verify_dependencies.py

它会检查什么 ​

类型说明
必需：Python使用 Python 3.11 或更高版本。发送脚本使用 datetime.UTC；只依赖 Python 标准库，不需要额外安装 SMTP 或 YAML 包。依赖检查脚本本身不检查 Python 版本。
必需：SMTP 配置检查 SMTP_USERNAME、SMTP_PASSWORD 和 SMTP_TO 是否存在；配置可来自环境变量、SEND_QQ_EMAIL_CONFIG 指向的文件或默认私有配置文件。
可选：SMTP 网络仅在传入 --check-network 时，尝试连接配置的 SMTP 主机和端口；默认值是 smtp.qq.com:587。

配置检查器读取的是顶层 smtp: 的简单 YAML 字段，不处理发送脚本的 --config 或 --to 参数（传入也会被忽略），也不解析 JSON 配置。检查指定私有 YAML 时，先设置 SEND_QQ_EMAIL_CONFIG；临时用 --to 覆盖收件人发送的任务，检查器仍会要求默认 SMTP_TO，不能据此判定发送脚本无法使用。

它不会扫描仓库文件、编译发送脚本、生成 .eml、执行 dry-run smoke test，也不会验证邮箱地址格式、授权码有效性、SMTP 登录或邮件投递。它检查端口能否转成整数，但不验证端口范围、超时和 STARTTLS 设置。网络检查只反映 TCP 连接是否可建立。

缺失时怎么补齐 ​

  1. 运行 python --version，确认 Python 至少为 3.11；如果版本过旧，从 Python 官方下载页 安装并重新打开终端。Windows 也可用 py -3.11 调用已安装版本。
  2. 打开 QQ 邮箱，登录后进入“设置 → 账户”，找到 POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务区域。界面名称可能随 QQ 邮箱版本变化。
  3. 开启 POP3/SMTP 或 IMAP/SMTP，由用户完成人工手机或扫码验证，再复制生成的授权码。Agent 不代替用户登录、验证或生成授权码。
  4. 在仓库外创建 %USERPROFILE%\.send-qq-email\email.yaml，把邮箱地址填入 username、授权码填入 password、默认收件人填入 to_address。不要把 QQ 登录密码填进 password，也不要把授权码贴到公开对话或仓库。
yaml
# %USERPROFILE%\.send-qq-email\email.yaml，仅示意填入位置
smtp:
  username: your-account@qq.com
  password: paste-qq-mail-authorization-code-here
  to_address: receiver@example.com

上面的值都是占位符，不能用于真实发送。环境变量 SMTP_USERNAME、SMTP_PASSWORD、SMTP_TO 会覆盖对应文件字段；修改私有文件后若结果仍不符，应检查是否残留了环境变量覆盖。脚本不会自动加载项目的 .env 文件，使用 .env 的项目需先自行加载它。

  1. 重新运行默认依赖检查。若需要排查网络，再从 workspace 根目录运行：
powershell
python skills/send-qq-email/verify_dependencies.py --check-network

网络检查失败时，核对私有配置的 host / port（默认 smtp.qq.com:587）以及本机网络、防火墙或代理是否允许该连接。TCP 可达后仍可能出现授权码错误或收件人被拒绝；这类结果由真实发送返回，不能用依赖检查通过代替投递成功证明。先按使用方式生成 dry-run 快照，确认内容和输出路径。

判断标准 ​

默认依赖检查通过，表示三个必需 SMTP 配置项已提供；只有使用 --check-network 并通过时，才同时表示目标 SMTP 地址在检查时可建立 TCP 连接。真实发送前，还需要让 Agent 确认 SMTP 用户名、授权码、收件人和发送意图。

默认检查成功退出码为 0，缺少必需配置或整数端口无效时为 1。输出的 required 条目和 ok 布尔值用于定位缺项；不要把授权码值加入日志。配置文件格式错误、文件读取失败等异常未统一转换成结构化失败，因此遇到 traceback 时也不能视为依赖已通过。