@adelie/csu-mail 0.0.0-stage → 0.4.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="CSU mail">
+  <rect x="6" y="14" width="52" height="36" rx="5" fill="#2f6fed"/>
+  <path d="M8 18.5 32 36 56 18.5" fill="none" stroke="#eaf1ff" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M8 46.5 25 33M56 46.5 39 33" fill="none" stroke="#eaf1ff" stroke-width="3.2" stroke-linecap="round"/>
+  <circle cx="49" cy="47" r="10" fill="#0b3ea8"/>
+  <path d="M44 47h10M49 42v10" stroke="#ffffff" stroke-width="2.6" stroke-linecap="round"/>
+</svg>

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@adelie/csu-mail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.2",
+  "description": "Manage a Coremail mailbox (CSU student mail, mail.csu.edu.cn) over IMAP/SMTP with a client app password instead of the unified auth portal — create the app password once, then list, search, read and send mail from the shell, with a copy kept in the Sent folder.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmliheng/Adelie.git",
+    "directory": "plugins/csu-mail"
+  },
+  "files": [
+    "plugin.json",
+    "icon.svg",
+    "skills",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/plugin.json

@@ -0,0 +1,9 @@
+{
+  "description": "Manage a Coremail mailbox (CSU student mail, mail.csu.edu.cn) without going through the unified auth portal: create a client app password once, then list, search, read and send mail over IMAP/SMTP from the shell, keeping a copy in the Sent folder.",
+  "description_zh": "绕开统一身份认证管理 Coremail 邮箱（中南大学学生邮箱）：生成客户端专用密码，再用 IMAP/SMTP 从命令行查信、检索、读信、发信，并在「已发送」留底。",
+  "short_description": "Coremail mailbox over IMAP/SMTP with an app password, no CAS.",
+  "short_description_zh": "Coremail 邮箱免 CAS 收发信：专用密码 + IMAP/SMTP，发信自动留底。",
+  "version": "2026.10.07.1",
+  "category": "office-productivity",
+  "preinstall": false
+}

package/skills/csu-mail/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: csu-mail
+description: Manage a Coremail mailbox (CSU student mail, mail.csu.edu.cn) over IMAP/SMTP with an app password instead of the unified auth portal — create the app password once, then list, search, read and send mail from the shell, with a copy kept in the Sent folder. Use whenever the task involves checking, sending or automating email on a CSU mailbox, or when a CAS login must be avoided.
+---
+
+# 中南大学邮箱管理（Coremail，绕开统一身份认证）
+
+## Before you start
+
+如果消息只是点名这个技能（比如「用 csu-mail」）而没有具体的事，先问清楚要做什么——查信、发信，还是
+做一次性引导。有具体任务时先自检凭据：`CSU_MAIL_ADDR` / `CSU_MAIL_AUTHCODE` 在不在环境里；不在就去
+第一节做引导，那是**起点**不是认证失败，别去重试登录。
+
+## 结论先行
+
+| 事项 | 做法 |
+| --- | --- |
+| 环境里没有 `CSU_MAIL_ADDR` / `CSU_MAIL_AUTHCODE` | 这是**起点**不是异常：先做一次性引导（**必须登录一次网页邮箱**），见第一节——`bash scripts/bootstrap.sh` 一条命令搞定 |
+| 收发信 | **客户端专用密码 + IMAP/SMTP**，不要为了邮件去登录统一身份认证（CAS） |
+| 为什么 | 短时间高频登录 CAS 会触发风控、甚至冻结账号（2026-10-02 真实发生过一次） |
+| 留底 | 用 SMTP 发信并 `APPEND` 到「已发送」；网页接口 `mbox:compose` **不留底** |
+
+## 一、起点：环境里没有 `CSU_MAIL_ADDR` / `CSU_MAIL_AUTHCODE` 时怎么办
+
+**这两个变量不是前提，是引导的产物。** 全新部署、换机器、或者专用密码丢了，环境里当然什么都没有 ——
+这时**必须登录一次网页邮箱**：专用密码只能在登录后的设置页生成，绕不过去。
+
+| 路径 | 需要什么 | 中南大学实测 | 怎么做 |
+| --- | --- | --- | --- |
+| ① CAS SSO（默认） | 统一身份认证账号 + 密码 | ✅ 可用 | `cas_login.py --mode cas` 换 sid，再驱动设置页生成专用密码。**只做这一次** |
+| ② 网页直登 | 邮箱**自己的**密码（≠ 统一密码） | ❌ `FA_UNAUTHORIZED`，还会开始要验证码 | `cas_login.py --mode direct`（POST `/coremail/index.jsp?cus=1`，先把表单隐藏字段原样回传）。只有邮箱有独立密码的部署才走得通 |
+| ③ 人工在浏览器里点 | 用户本人（Coremail 二次验证是**短信**，只有真人能收） | ✅ 最稳 | 用户自己登录 → 设置 → 个人信息 → 邮箱密码 → 生成专用密码 → **由用户自己**写进密钥库（别在聊天里贴密码） |
+
+自动化这两步用一条命令：
+
+```bash
+cd <插件目录>/skills/csu-mail/scripts
+CSU_MAIL_ADDR=学号@csu.edu.cn \
+CSU_CAS_USER=学号 CSU_CAS_PASS=密码 \
+PROJECT_ID=<App Data Dir 的最后一段> \
+PLAYWRIGHT_MODULE=/path/to/node_modules/playwright-core CHROME_PATH=/path/to/chrome \
+  bash bootstrap.sh
+```
+
+`bootstrap.sh` 做四件事：登录换 sid → 生成专用密码 → 把 `CSU_MAIL_ADDR` / `CSU_MAIL_AUTHCODE`
+写进**指定项目**的密钥库 → 销毁临时明文。`NO_VAULT=1` 只打印命令不写库；
+`SECRET_OUT=/path` 额外留一份 600 的明文（systemd 这类读不到密钥库的场景要用）。
+
+**账号密码从哪来**：问用户要，或放进密钥库（`CSU_CAS_USER` / `CSU_CAS_PASS`）——
+绝不写进代码或仓库；引导完成后这两个变量就该删掉，日常收发信用不到它们。
+
+**键名的别名**（2026-10-05 加）：脚本同时认 `CSU_CAS_ADDRESS`（= 邮箱地址）与 `CSU_CAS_PASSWORD`
+（= 统一身份认证密码）这两个名字 —— 密钥库里叫什么就用什么，不必为了对齐插件文档重抄一遍明文。
+引导写进密钥库的是插件自己的名字：`CSU_MAIL_ADDR` 与 `CSU_MAIL_AUTHCODE`。
+
+**登录只做一次，失败不要重试**：CAS 短时间高频失败会触发风控甚至冻结账号（2026-10-02 真实发生过一次）。
+
+## 二、系统事实（实测）
+
+| 项 | 值 |
+| --- | --- |
+| 邮件系统 | Coremail XT5，网页入口 `https://mail.csu.edu.cn` |
+| 地址 | `学号@csu.edu.cn`，另有别名 `拼音.csu@csu.edu.cn`，两者是同一邮箱 |
+| 二次验证 | 已开启（短信验证），所以第三方客户端只能用**客户端专用密码** |
+| IMAP | `imap.csu.edu.cn:993` SSL（`mail.csu.edu.cn:993` 同样可用） |
+| POP | `pop.csu.edu.cn:995` SSL |
+| SMTP | `smtp.csu.edu.cn:465` SSL；**587 关闭、25 不通** |
+| IMAP 证书 | CN = `mail.csu.edu.cn`，与主机名 `imap.csu.edu.cn` 不匹配，必须跳过证书校验，否则 `SSL: CERTIFICATE_VERIFY_FAILED` |
+
+链路实测（2026-10-02，非校园网出口）：
+
+- 两个端口都可达，**TLS1.3** 握手成功；IMAP 问候 `* OK Coremail System IMap Server Ready(...)`，
+  SMTP 问候 `220 csu.edu.cn Anti-spam GT for Coremail System (...)`；`imaplib`/`smtplib` 用跳过校验的 `SSLContext` 可直接建连。
+- 证书严格校验访问 `imap.csu.edu.cn` 必然 `Hostname mismatch`——这不是网络故障，别再往防火墙方向排查。
+
+认证的边界（都实测过）：
+
+- 统一身份认证密码**不能**登录 IMAP → `LOGIN Login error or password error`
+- 网页直登 `/coremail/index.jsp?cus=1`（明文 `uid`+`password`）→ `FA_UNAUTHORIZED`，还会弹验证码
+- 结论：第三方客户端只有**客户端专用密码**这一条路
+
+## 三、首次引导：两条路都走完的三步
+
+第一节决定「用哪条路登录」，这里是把结果落到密钥库的三步（`bootstrap.sh` 就是自动化了这三步）。
+
+1. 网页邮箱 → `设置 → 个人信息 → 邮箱密码` →「客户端专用密码」区块 → 点**虚线方框 “+”** → 填密码名称 →「生成」。
+   **不需要短信验证**，但密码串**只在生成时显示一次**；丢了就在同一页面「移除」后重建。
+2. 后端接口（想自动化时用）：`user:listAppPwds`（列表）、`user:addAppPwd`（创建，响应里带明文）、
+   `user:deleteAppPwds`（`{"ids":[102]}`）。请求走 `/coremail/s`，**`func` 与 `sid` 必须在 query string**。
+3. 本插件的脚本：
+
+```bash
+# ① CAS 登录换 sid（只做一次）
+CSU_MAIL_ADDR=学号@csu.edu.cn CSU_CAS_USER=学号 CSU_CAS_PASS=密码 \
+  python scripts/cas_login.py --out mail_session.json          # 产出 600 权限的 sid + cookies
+
+# ② 驱动网页邮箱生成专用密码（需要 Playwright）
+PLAYWRIGHT_MODULE=/path/to/node_modules/playwright-core \
+CHROME_PATH=/path/to/chrome \
+  node scripts/create_apppw.mjs mail_session.json agent-server --out secret.txt
+
+# ③ 存进密钥库并删掉明文
+#    必须显式带 --project-id / --agent-id：CLI 的默认项目是 default_project，
+#    不带就会写进别的项目的密钥库（密钥库里查得到，环境变量里永远没有）。
+#    项目 id = 运行环境 App Data Dir 的最后一段，如 /root/.adelie/data/asass -> asass
+P="--project-id <项目id> --agent-id default_agent"
+penguin config vault set $P --key CSU_MAIL_AUTHCODE --value "$(cat secret.txt)" && shred -u secret.txt
+penguin config vault set $P --key CSU_MAIL_ADDR --value "学号@csu.edu.cn"
+```
+
+> 写完后**当前会话仍然没有**这两个变量（见踩坑 2）；开一个新对话，或等本会话压缩后再用。
+
+> 引导用的 CAS 登录**不要重试**：失败就停下来问用户，别连续试密码。
+
+## 四、日常收发信：`scripts/mail.py`
+
+```bash
+export CSU_MAIL_ADDR=学号@csu.edu.cn CSU_MAIL_AUTHCODE=专用密码   # 或从密钥库注入
+V=python3
+
+$V scripts/mail.py check                     # IMAP + SMTP 自检
+$V scripts/mail.py list INBOX 10             # 最近 10 封
+$V scripts/mail.py list "Sent Items" 5       # 含空格的文件夹要加引号
+$V scripts/mail.py read 124                  # 读一封（正文）
+$V scripts/mail.py search 成绩                # 按标题检索
+$V scripts/mail.py send --to jcc@csu.edu.cn --subject "..." --body-file body.txt
+                                             # 发信，并自动存一份到「已发送」
+```
+
+依赖：`requests`（只有 `mail.py` 的核心收发用标准库 `imaplib`/`smtplib`/`email`，无需三方包）。
+
+**动手前先自检**：`check` 会依次登录 IMAP 与 SMTP，两条都通过才算通。若报「缺少邮箱地址 / 缺少 CSU_MAIL_AUTHCODE」，
+那是凭据没注入，不是认证失败——去查密钥库写没写错项目（见踩坑 9），别去重试登录。
+
+## 五、踩过的坑
+
+1. **「生成」按钮初始是 `disabled`**，弹出框里的密码名称输入框必须用**真实键盘事件**输入
+   （Playwright 的 `fill()` 不行，要 `click()` + `keyboard.type()`），否则点了没反应、也不报错。
+2. **专用密码只显示一次**：生成后立刻写进密钥库。密钥库变量在**会话开始**时注入，所以当前会话新加的变量当场读不到——
+   开一个新对话即可。若**换了会话**还是空的，那不是注入时机问题，是写错了项目（见踩坑 9）。
+   验证办法：在当前 shell 里 `echo ${#CSU_MAIL_AUTHCODE}`，非 0 才算注入成功（只输出长度，别打印明文）。
+3. **网页接口发信不留底**：`mbox:compose` 返回 `S_OK`，但「已发送」里查不到，事后无法核实送达。
+   要留底就用 SMTP 发送 + `IMAP APPEND` 到 `Sent Items`（本插件的 `mail.py send` 就是这么做的）。
+4. **文件夹名含空格要加引号**（`"Sent Items"`），否则 IMAP 报 `BAD Request not ending with ...`。
+5. **中文 `SEARCH SUBJECT` 命中不稳定**：查不到时改用 `list` 翻页，别下结论说「没有这封邮件」。
+6. 网页 API 的 `func` / `sid` 必须放在 **query string**，其余字段放 form body，否则 202/失败。
+7. IMAP 证书 CN 不匹配，连接时必须 `check_hostname=False; verify_mode=CERT_NONE`。
+8. **不要把账号、密码、专用密码写进代码或提交进仓库**——凭证只放密钥库/环境变量。
+9. **`penguin config vault set/list` 的默认项目是 `default_project`**：不带 `--project-id` 就会把凭据写进另一个项目的密钥库，
+   现象是「密钥库里查得到，Agent 的 shell 里却始终没有这个变量」。2026-10-02 真实踩到：专用密码落进了 `default_project`，
+   而 Agent 跑在别的项目里，于是 `mail.py check` 只报「缺少邮箱地址」——**别把它当认证失败去重试登录**。
+   查证方法：`penguin config vault list --project-id <项目id> --agent-id default_agent`，
+   项目 id = 运行环境 App Data Dir 的最后一段（`/root/.adelie/data/<项目id>`），列表里有、`env` 里没有就是这个问题。
+   修法：把值重新 set 到正确项目，并清掉写错的那份：`penguin config vault remove --key <KEY> --project-id default_project --agent-id <agent>`。
+
+## 六、边界
+
+- 本技能只覆盖**邮件**本身。Coremail 的通讯录、日程不在范围内。
+- 代用户发信前先确认收件人与措辞；不要群发、不要发垃圾邮件。
+- 邮箱是学校通知与个人信息的入口，读信时注意隐私，不要把邮件内容贴到无关的地方。

package/skills/csu-mail/scripts/bootstrap.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# csu-mail 引导：从「环境里没有 CSU_MAIL_ADDR / CSU_MAIL_AUTHCODE」到「两个变量都在密钥库里」。
+#
+# 这一步**必须登录一次网页邮箱**——专用密码只能在登录后的设置页生成，没有别的办法。
+# 走的是 CAS SSO（Coremail 开着二次验证时唯一可靠的路）；登录一次之后就再也不碰统一身份认证了。
+#
+# 用法：
+#   CSU_MAIL_ADDR=学号@csu.edu.cn \
+#   CSU_CAS_USER=学号 CSU_CAS_PASS=密码 \
+#   PROJECT_ID=<App Data Dir 的最后一段> \
+#     bash scripts/bootstrap.sh
+#
+# 可选环境变量：
+#   AGENT_ID         默认 default_agent
+#   PASSWORD_NAME    专用密码名称，默认 agent-server
+#   PYTHON           python 解释器，默认 python3（需要 requests / bs4 / pycryptodome）
+#   PLAYWRIGHT_MODULE / CHROME_PATH   Playwright 与本机 Chromium 的路径
+#   SECRET_OUT       额外把专用密码写到该文件（600，不删除）——给 systemd 这类读不了密钥库的场景用
+#   NO_VAULT=1       不写密钥库，只打印该执行的两条命令
+#   CSU_LOGIN_MODE   cas（默认）| direct（邮箱有自己的密码时才用；中南大学实测走不通）
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PYTHON="${PYTHON:-python3}"
+AGENT_ID="${AGENT_ID:-default_agent}"
+PASSWORD_NAME="${PASSWORD_NAME:-agent-server}"
+MODE="${CSU_LOGIN_MODE:-cas}"
+
+# 密钥库里的键名以实际写进去的为准，这里两套都认、一律折成插件原本的名字。2026-10-05 用户写的是
+# CSU_CAS_PASSWORD / CSU_CAS_ADDRESS；插件文档一直写的是 CSU_CAS_PASS / CSU_MAIL_ADDR。重命名要
+# 重新抄一遍明文，不值得 —— 兼容读一遍即可。
+CSU_MAIL_ADDR="${CSU_MAIL_ADDR:-${CSU_CAS_ADDRESS:-}}"
+CSU_CAS_PASS="${CSU_CAS_PASS:-${CSU_CAS_PASSWORD:-}}"
+
+die() { echo "✗ $*" >&2; exit 1; }
+
+[ -n "${CSU_MAIL_ADDR:-}" ] || die "请设置 CSU_MAIL_ADDR（或 CSU_CAS_ADDRESS）：邮箱地址，如 学号@csu.edu.cn"
+[ -n "${CSU_CAS_USER:-}" ] || die "请设置 CSU_CAS_USER（统一身份认证账号，通常是学号）"
+[ -n "${CSU_CAS_PASS:-}" ] || die "请设置 CSU_CAS_PASS（或 CSU_CAS_PASSWORD）：统一身份认证密码"
+
+[ -n "${CSU_MAIL_AUTHCODE:-}" ] && { echo "✓ 环境里已经有 CSU_MAIL_AUTHCODE（长度 ${#CSU_MAIL_AUTHCODE}），无需引导。"; echo "  直接自检即可：$PYTHON $HERE/mail.py check"; exit 0; }
+
+# 先验依赖：python 侧 requests/bs4/pycryptodome，node 侧供 create_apppw.mjs 用
+"$PYTHON" -c 'import requests, bs4, Crypto' 2>/dev/null \
+  || die "$PYTHON 缺依赖，先装：$PYTHON -m pip install requests beautifulsoup4 pycryptodome"
+command -v node >/dev/null || die "找不到 node（第②步生成专用密码要它）"
+
+TMP="$(mktemp -d)"
+cleanup() {
+  [ -f "$TMP/secret" ] && { shred -u "$TMP/secret" 2>/dev/null || rm -f "$TMP/secret"; }
+  rm -rf "$TMP"
+}
+trap cleanup EXIT
+
+echo "→ ① 登录网页邮箱换 sid（模式 $MODE，只这一次）"
+CSU_MAIL_ADDR="$CSU_MAIL_ADDR" "$PYTHON" "$HERE/cas_login.py" --mode "$MODE" --out "$TMP/session.json" \
+  || die "登录失败：不要重试，先找用户确认账号密码或账号状态（CAS 会被风控）。"
+
+echo "→ ② 在网页邮箱里生成一条客户端专用密码（名称：$PASSWORD_NAME）"
+PLAYWRIGHT_MODULE="${PLAYWRIGHT_MODULE:-playwright-core}" CHROME_PATH="${CHROME_PATH:-}" \
+  node "$HERE/create_apppw.mjs" "$TMP/session.json" "$PASSWORD_NAME" --out "$TMP/secret" \
+  || die "生成专用密码失败：确认已装 Playwright/Chromium（PLAYWRIGHT_MODULE、CHROME_PATH）。"
+
+echo "→ ③ 写进密钥库（长度校验：$(wc -c < "$TMP/secret" | tr -d ' ') 字节）"
+if [ "${NO_VAULT:-0}" = "1" ]; then
+  echo "  NO_VAULT=1，跳过。请自己执行（注意必须指定项目，否则写进 default_project，环境里永远没有）："
+  echo "    penguin config vault set --project-id <项目id> --agent-id $AGENT_ID --key CSU_MAIL_ADDR --value '$CSU_MAIL_ADDR'"
+  echo "    penguin config vault set --project-id <项目id> --agent-id $AGENT_ID --key CSU_MAIL_AUTHCODE --value \"\$(cat 专用密码文件)\""
+  [ -n "${SECRET_OUT:-}" ] && { install -m 600 "$TMP/secret" "$SECRET_OUT"; echo "  专用密码也写到了 $SECRET_OUT"; }
+  exit 0
+fi
+
+[ -n "${PROJECT_ID:-}" ] || die "请设置 PROJECT_ID（= 运行环境 App Data Dir 的最后一段，如 /root/.adelie/data/sjaaj -> sjaaj）；
+   否则凭据会落进 default_project：密钥库里查得到，Agent 的 shell 里却永远没有这个变量。"
+
+command -v penguin >/dev/null || die "找不到 penguin CLI：请手动写密钥库，或用 NO_VAULT=1 看命令。"
+
+penguin config vault set --project-id "$PROJECT_ID" --agent-id "$AGENT_ID" \
+  --key CSU_MAIL_ADDR --value "$CSU_MAIL_ADDR"
+penguin config vault set --project-id "$PROJECT_ID" --agent-id "$AGENT_ID" \
+  --key CSU_MAIL_AUTHCODE --value "$(cat "$TMP/secret")"
+
+[ -n "${SECRET_OUT:-}" ] && { install -m 600 "$TMP/secret" "$SECRET_OUT"; echo "✓ 专用密码副本写到 $SECRET_OUT（600）"; }
+
+echo "✓ 完成。当前会话里还没有这两个变量（注入发生在会话开始），先这么用："
+echo "    CSU_MAIL_ADDR=$CSU_MAIL_ADDR CSU_MAIL_AUTHCODE=<从密钥库读> python $HERE/mail.py check"
+echo "  下一个新会话起，环境里会自动带上 CSU_MAIL_ADDR / CSU_MAIL_AUTHCODE。"

package/skills/csu-mail/scripts/cas_login.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""登录网页邮箱，换取 Coremail 的 sid —— 只用于首次引导。
+
+日常收发信**不需要**这个脚本：有了客户端专用密码就能直接走 IMAP/SMTP（见 mail.py）。
+只有当邮箱里还没有专用密码、又必须进网页邮箱生成一条时才用它。
+
+两条登录路径（`--mode`）：
+
+  cas     走统一身份认证 SSO（默认）。Coremail 侧二次验证开着时，这是**唯一可靠**的路。
+  direct  直接用 `学号 + 密码` POST 网页登录表单 `/coremail/index.jsp?cus=1`。
+          只有当邮箱有自己的密码（≠ 统一身份认证密码）时才会成功。
+          中南大学实测：用统一身份认证密码直登返回 `FA_UNAUTHORIZED`，并开始要验证码 —— 走不通。
+
+无论哪条路：**不要重试**。失败就停下来问用户，别连续试密码（CAS 会被风控，邮箱会要验证码）。
+
+用法：
+    CSU_MAIL_ADDR=学号@csu.edu.cn CSU_CAS_USER=学号 CSU_CAS_PASS=密码 \
+        python cas_login.py [--mode cas|direct] [--out mail_session.json]
+
+产出：JSON（sid + cookies，权限 600），可直接喂给 create_apppw.mjs。
+"""
+import argparse
+import base64
+import json
+import os
+import random
+import re
+import sys
+
+import requests
+from bs4 import BeautifulSoup
+from Crypto.Cipher import AES
+
+CAS = os.environ.get("CSU_CAS_URL", "https://ca.csu.edu.cn/authserver/login")
+SERVICE = os.environ.get("CSU_MAIL_SSO", "https://mail.csu.edu.cn/coremail/cmcu_addon/sso.jsp")
+MAIL_BASE = os.environ.get("CSU_MAIL_BASE", "https://mail.csu.edu.cn")
+UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+      "(KHTML, like Gecko) Chrome/126.0 Safari/537.36")
+CHARS = "ABCDEFGHJKMNPQRSTWXYZabcdefhijkmnprstwxyz2345678"
+
+
+def _rand(n: int) -> str:
+    return "".join(random.choice(CHARS) for _ in range(n))
+
+
+def encrypt_password(password: str, salt: str) -> str:
+    """与 CAS 页面 static/common/encrypt.js 的 encryptAES 一致：
+    明文 = 64 位随机串 + 密码，AES-CBC（key = pwdEncryptSalt，iv = 16 位随机串），PKCS7，Base64。"""
+    text = _rand(64) + password
+    pad_len = AES.block_size - len(text) % AES.block_size
+    text += pad_len * chr(pad_len)
+    cipher = AES.new(salt.encode(), AES.MODE_CBC, _rand(16).encode())
+    return base64.b64encode(cipher.encrypt(text.encode())).decode()
+
+
+def cas_login(user: str, password: str, service: str = SERVICE) -> requests.Session:
+    s = requests.Session()
+    s.headers["User-Agent"] = UA
+    page = s.get(CAS, params={"service": service}, timeout=20)
+    div = BeautifulSoup(page.text, "lxml").find(id="pwdLoginDiv")
+    if div is None:
+        raise RuntimeError("CAS 页面结构变化，取不到 pwdLoginDiv（可能要求验证码）")
+    resp = s.post(CAS, params={"service": service}, timeout=25, data={
+        "username": user,
+        "password": encrypt_password(password, div.find(id="pwdEncryptSalt")["value"]),
+        "passwordText": "", "_eventId": "submit", "cllt": "userNameLogin",
+        "dllt": "generalLogin", "lt": "",
+        "execution": div.find(id="execution")["value"], "rmShown": "1",
+    })
+    if "/authserver/login" in resp.url and "ticket" not in resp.url:
+        raise RuntimeError("统一身份认证登录失败（账号或密码错误，或触发风控/需要验证码）")
+    return s
+
+
+def direct_login(user: str, password: str):
+    """网页直登，返回 (session, sid)：POST /coremail/index.jsp?cus=1（明文的 uid + password + 表单隐藏字段）。
+
+    要先把登录页上的隐藏字段原样回传（`loginType`、`locale`、`action:login` 等），
+    少了它们会被判非法请求。Coremail 的失败信息在页面的 #warnOrErrDiv 里，
+    同时 `CM.config.user.loginResultCode` 会给一个代码（如 FA_UNAUTHORIZED）。
+    """
+    s = requests.Session()
+    s.headers["User-Agent"] = UA
+    page = s.get(MAIL_BASE + "/", timeout=20)
+    html = page.text
+    fi = html.find('class="j-login-form')
+    if fi < 0:
+        raise RuntimeError("取不到登录表单：页面结构可能变了")
+    seg = html[fi: html.find("</form>", fi)]
+    data = {}
+    for m in re.finditer(r"<input([^>]*)>", seg):
+        attrs = m.group(1)
+        n = re.search(r'name="([^"]+)"', attrs)
+        v = re.search(r'value="([^"]*)"', attrs)
+        if n:
+            data[n.group(1)] = v.group(1) if v else ""
+    data["uid"] = user
+    data["password"] = password
+    resp = s.post(MAIL_BASE + "/coremail/index.jsp?cus=1", data=data, timeout=25,
+                  headers={"Referer": MAIL_BASE + "/"})
+    # 注意：失败页面里也会出现 "sid=" 字样（SSO 链接），必须先判错再用 sid 判成功
+    err = (re.search(r'id="warnOrErrDiv"[^>]*>\s*<label>([^<]+)', resp.text)
+           or re.search(r'class="[^"]*\berrMsg\b[^"]*"[^>]*>\s*<label>([^<]+)', resp.text))
+    code = re.search(r"loginResultCode:\s*'([^']+)'", resp.text)
+    m = re.search(r"sid=([A-Za-z0-9_\-]+)", resp.url) or re.search(r'sid="([A-Za-z0-9_\-]+)"', resp.text)
+    if err or not m:
+        detail = err.group(1).strip() if err else "没有返回可用的 sid"
+        if code:
+            detail += f"（loginResultCode={code.group(1)}）"
+        raise RuntimeError(f"网页直登失败：{detail} —— 邮箱有自己的密码才走得通，中南大学实测走不通；"
+                           "请改用默认的 --mode cas，或让用户在浏览器里手动生成专用密码")
+    return s, m.group(1)
+
+
+def mail_sid(s: requests.Session, resp) -> str:
+    m = re.search(r"sid=([A-Za-z0-9_\-]+)", resp.url)
+    if not m:
+        r = s.get("https://mail.csu.edu.cn/coremail/XT5/index.jsp", allow_redirects=True, timeout=25)
+        m = (re.search(r"sid=([A-Za-z0-9_\-]+)", r.url)
+             or re.search(r'name="sid"\s+value="([^"]+)"', r.text))
+    if not m:
+        raise RuntimeError("SSO 回调里没有 sid")
+    return m.group(1)
+
+
+def main():
+    ap = argparse.ArgumentParser(description="登录网页邮箱换 sid（仅引导时使用）")
+    ap.add_argument("--mode", choices=["cas", "direct"], default=os.environ.get("CSU_LOGIN_MODE", "cas"))
+    ap.add_argument("--user", default=os.environ.get("CSU_CAS_USER", ""))
+    ap.add_argument("--password", default=os.environ.get("CSU_CAS_PASS") or os.environ.get("CSU_CAS_PASSWORD", ""))
+    ap.add_argument("--service", default=SERVICE)
+    ap.add_argument("--out", default="mail_session.json")
+    a = ap.parse_args()
+    if not a.user or not a.password:
+        sys.exit("需要 CSU_CAS_USER / CSU_CAS_PASS（或 CSU_CAS_PASSWORD；也可用 --user/--password）")
+
+    if a.mode == "direct":
+        s, sid = direct_login(a.user, a.password)
+    else:
+        s = cas_login(a.user, a.password, a.service)
+        resp = s.get(a.service, timeout=25)
+        sid = mail_sid(s, resp)
+
+    with open(a.out, "w", encoding="utf-8") as f:
+        json.dump({"sid": sid, "cookies": s.cookies.get_dict()}, f)
+    os.chmod(a.out, 0o600)
+    print(f"sid 已写入 {a.out}（{sid[:4]}…{sid[-4:]}，模式 {a.mode}），接下来可用 create_apppw.mjs 生成客户端专用密码")
+
+
+if __name__ == "__main__":
+    main()

package/skills/csu-mail/scripts/create_apppw.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// 用 cas_login.py 产出的 mail_session.json 打开网页邮箱，生成一条「客户端专用密码」。
+// 专用密码只在生成时显示一次，生成后请立刻存进密钥库（不要写进代码/仓库）。
+//
+// 用法：
+//   PLAYWRIGHT_MODULE=/path/to/node_modules/playwright-core \
+//   CHROME_PATH=/path/to/chrome \
+//   node create_apppw.mjs mail_session.json <密码名称> [--out secret.txt]
+//
+// 两个坑（本脚本已处理）：
+//   1. 弹窗里的「生成」按钮初始带 disabled，输入框必须用**真实键盘事件**输入才会解除，
+//      Playwright 的 fill() 不够，要用 click + keyboard.type。
+//   2. 生成结果同时来自 user:addAppPwd 的响应体，正则取 password/pwd 字段最稳。
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+
+const PW_MODULE = process.env.PLAYWRIGHT_MODULE || "playwright-core";
+const CHROME = process.env.CHROME_PATH || "";
+// PLAYWRIGHT_MODULE 可以是包名（playwright-core），也可以是本机安装目录的绝对路径
+const require = createRequire(import.meta.url);
+let pw;
+try {
+  pw = require(PW_MODULE);
+} catch (e) {
+  pw = require(PW_MODULE.replace(/\/+$/, "") + "/index.js");
+}
+const chromium = pw.chromium;
+if (!chromium) {
+  console.error(
+    `没有从 ${PW_MODULE} 拿到 chromium：检查 PLAYWRIGHT_MODULE 是否指向 playwright / playwright-core`,
+  );
+  process.exit(2);
+}
+
+const [, , sessionFile, name, ...rest] = process.argv;
+if (!sessionFile || !name) {
+  console.error("用法: node create_apppw.mjs <mail_session.json> <密码名称> [--out secret.txt]");
+  process.exit(2);
+}
+const opts = {};
+for (let i = 0; i < rest.length; i += 2) opts[rest[i].replace(/^--/, "")] = rest[i + 1];
+
+(async () => {
+  const sess = JSON.parse(fs.readFileSync(sessionFile, "utf8"));
+  const browser = await chromium.launch({
+    executablePath: CHROME || undefined,
+    args: ["--no-sandbox", "--disable-dev-shm-usage"],
+  });
+  const ctx = await browser.newContext({
+    userAgent:
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126 Safari/537.36",
+    viewport: { width: 1280, height: 800 },
+  });
+  await ctx.addCookies(
+    Object.entries(sess.cookies || {}).map(([k, v]) => ({
+      name: k,
+      value: v,
+      domain: "mail.csu.edu.cn",
+      path: "/",
+    })),
+  );
+
+  const page = await ctx.newPage();
+  const bodies = [];
+  page.on("response", async (r) => {
+    if (!r.url().includes("/coremail/s")) return;
+    const func = decodeURIComponent((r.url().match(/func=([^&]+)/) || [])[1] || "");
+    if (!/AppPwd/i.test(func)) return;
+    try {
+      bodies.push({ func, text: await r.text() });
+    } catch (e) {
+      /* ignore */
+    }
+  });
+
+  await page.goto(`https://mail.csu.edu.cn/coremail/XT5/index.jsp?sid=${sess.sid}#setting`, {
+    waitUntil: "domcontentloaded",
+    timeout: 60000,
+  });
+  await page.waitForTimeout(6000);
+  await page.getByText("个人信息", { exact: true }).first().click({ timeout: 10000 });
+  await page.waitForTimeout(2000);
+  await page.getByText("邮箱密码", { exact: true }).first().click({ timeout: 10000 });
+  await page.waitForTimeout(4000);
+
+  await page.locator("li.j-add-item").first().click({ timeout: 10000 });
+  await page.waitForTimeout(2500);
+  const input = page.locator("input.j-input-name").first();
+  await input.click();
+  await page.keyboard.type(name, { delay: 60 }); // 必须真实键入，否则确认键仍是 disabled
+  await page.waitForTimeout(500);
+  await page
+    .locator(".u-dialog-btns button[data-role=confirm]")
+    .first()
+    .click({ force: true, timeout: 10000 });
+  await page.waitForTimeout(7000);
+
+  let secret = null;
+  for (const b of bodies) {
+    const m = b.text.match(/"(?:password|pwd|appPwd|altpwd|secret)"\s*:\s*"([^"]{6,64})"/i);
+    if (m) {
+      secret = m[1];
+      break;
+    }
+  }
+  if (!secret) {
+    const txt = (await page.innerText("body")).replace(/\s+/g, " ");
+    const m = txt.match(/专用密码[^A-Za-z0-9]{0,20}([A-Za-z0-9]{8,32})/);
+    if (m) secret = m[1];
+  }
+
+  if (!secret) {
+    console.error(
+      "没拿到专用密码：确认已在网页邮箱里点开了「客户端专用密码」区块，且密码名称未被占用。",
+    );
+    await page.screenshot({ path: "apppw-failed.png", fullPage: true });
+    await browser.close();
+    process.exit(1);
+  }
+
+  if (opts.out) {
+    fs.writeFileSync(opts.out, secret, { mode: 0o600 });
+    console.log(`专用密码已写入 ${opts.out}（len=${secret.length}，请立刻存进密钥库后删除该文件）`);
+  } else {
+    console.log("专用密码（只显示这一次）:", secret);
+  }
+  console.log("已创建的专用密码名称:", name, "| 后端接口:", bodies.map((b) => b.func).join(", "));
+  await browser.close();
+})().catch((e) => {
+  console.error("ERR", e.message);
+  process.exit(1);
+});

package/skills/csu-mail/scripts/mail.py

@@ -0,0 +1,195 @@
+"""Coremail 邮箱命令行工具 —— 走 IMAP/SMTP + 客户端专用密码，不经过统一身份认证（CAS）。
+
+凭证（环境变量）：
+    CSU_MAIL_ADDR        邮箱地址，如 1234567890@csu.edu.cn   ← 必填，不写死在代码里
+    CSU_MAIL_AUTHCODE    客户端专用密码（App Password）        ← 必填，放在密钥库里
+    CSU_MAIL_IMAP_HOST   默认 imap.csu.edu.cn
+    CSU_MAIL_SMTP_HOST   默认 smtp.csu.edu.cn
+
+没有专用密码就去网页邮箱「设置 → 个人信息 → 邮箱密码 → 客户端专用密码」点虚线 "+" 生成一个
+（密码串只在生成时显示一次，不需要短信验证）。
+
+用法：
+    python mail.py check                       # 连通性自检（IMAP + SMTP 登录）
+    python mail.py list [文件夹] [条数]         # 默认 INBOX 最近 10 封
+    python mail.py search <关键词> [文件夹] [条数]
+    python mail.py read <序号> [文件夹]         # 打印邮件正文
+    python mail.py send --to a@b.com --subject 主题 [--body 正文 | --body-file f]
+                       [--attach 文件]         # 发信并留一份到「已发送」
+"""
+import argparse
+import email
+import imaplib
+import os
+import ssl
+import smtplib
+import sys
+import time
+from email.header import decode_header, make_header
+from email.message import EmailMessage
+from email.utils import formatdate
+
+IMAP_HOST = os.environ.get("CSU_MAIL_IMAP_HOST", "imap.csu.edu.cn")
+IMAP_PORT = int(os.environ.get("CSU_MAIL_IMAP_PORT", "993"))
+SMTP_HOST = os.environ.get("CSU_MAIL_SMTP_HOST", "smtp.csu.edu.cn")
+SMTP_PORT = int(os.environ.get("CSU_MAIL_SMTP_PORT", "465"))
+SENT = os.environ.get("CSU_MAIL_SENT_FOLDER", "Sent Items")
+
+_ADDR = ""
+
+
+def addr() -> str:
+    a = _ADDR or os.environ.get("CSU_MAIL_ADDR", "").strip() or os.environ.get("CSU_CAS_ADDRESS", "").strip()
+    if not a:
+        sys.exit("缺少邮箱地址：设置环境变量 CSU_MAIL_ADDR（或 CSU_CAS_ADDRESS），或用 --addr 指定")
+    return a
+
+
+def code() -> str:
+    c = os.environ.get("CSU_MAIL_AUTHCODE", "").strip()
+    if not c:
+        sys.exit("缺少环境变量 CSU_MAIL_AUTHCODE（客户端专用密码）—— 在邮箱「设置 → 个人信息 → 邮箱密码 → 客户端专用密码」生成一条")
+    return c
+
+
+def _ctx() -> ssl.SSLContext:
+    # 学校 IMAP 证书的 CN 与主机名不一致，跳过校验（Coremail 自身仍是 TLS 加密）
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    return ctx
+
+
+def imap():
+    m = imaplib.IMAP4_SSL(IMAP_HOST, IMAP_PORT, ssl_context=_ctx())
+    m.login(addr(), code())
+    return m
+
+
+def dec(s) -> str:
+    if not s:
+        return ""
+    try:
+        return str(make_header(decode_header(s)))
+    except Exception:
+        return s
+
+
+def _mb(folder: str) -> str:
+    """IMAP 文件夹名含空格时必须加引号。"""
+    if folder.startswith('"') or not any(c in folder for c in " \t"):
+        return folder
+    return '"%s"' % folder
+
+
+def body_text(msg) -> str:
+    if msg.is_multipart():
+        for part in msg.walk():
+            if part.get_content_type() == "text/plain":
+                return part.get_payload(decode=True).decode(part.get_content_charset() or "utf-8", "ignore")
+        for part in msg.walk():
+            if part.get_content_type() == "text/html":
+                return part.get_payload(decode=True).decode(part.get_content_charset() or "utf-8", "ignore")
+        return ""
+    return msg.get_payload(decode=True).decode(msg.get_content_charset() or "utf-8", "ignore")
+
+
+def cmd_check(_):
+    m = imap()
+    print("IMAP ok:", [x.decode().split(' "/" ')[-1] for x in m.list()[1]][:8])
+    typ, d = m.select("INBOX", readonly=True)
+    print("INBOX 封数:", d[0].decode())
+    m.logout()
+    s = smtplib.SMTP_SSL(SMTP_HOST, SMTP_PORT, context=_ctx(), timeout=30)
+    s.login(addr(), code())
+    print("SMTP ok (登录成功，未发信)")
+    s.quit()
+
+
+def cmd_list(a):
+    m = imap()
+    m.select(_mb(a.folder), readonly=True)
+    typ, ids = m.search(None, "ALL")
+    ids = ids[0].split()[-a.limit:][::-1]
+    for i in ids:
+        t, data = m.fetch(i, "(BODY.PEEK[HEADER.FIELDS (DATE FROM SUBJECT)])")
+        raw = data[0][1].decode("utf-8", "ignore")
+        msg = email.message_from_string(raw)
+        print(f"[{i.decode()}] {dec(msg['Date'])} | {dec(msg['From'])} | {dec(msg['Subject'])}")
+    m.logout()
+
+
+def cmd_search(a):
+    m = imap()
+    m.select(_mb(a.folder), readonly=True)
+    typ, ids = m.search("UTF-8", b"SUBJECT", a.keyword.encode("utf-8"))
+    if typ != "OK":
+        print("检索失败:", ids)
+    ids = ids[0].split()[-a.limit:][::-1]
+    print(f"{a.folder} 命中 {len(ids)} 封")
+    for i in ids:
+        t, data = m.fetch(i, "(BODY.PEEK[HEADER.FIELDS (DATE FROM TO SUBJECT)])")
+        msg = email.message_from_string(data[0][1].decode("utf-8", "ignore"))
+        print(f"[{i.decode()}] {dec(msg['Date'])} | {dec(msg['From'])} -> {dec(msg['To'])} | {dec(msg['Subject'])}")
+    m.logout()
+
+
+def cmd_read(a):
+    m = imap()
+    m.select(_mb(a.folder), readonly=True)
+    t, data = m.fetch(a.uid, "(RFC822)")
+    msg = email.message_from_bytes(data[0][1])
+    print("From:", dec(msg["From"]))
+    print("To:", dec(msg["To"]))
+    print("Date:", dec(msg["Date"]))
+    print("Subject:", dec(msg["Subject"]))
+    print("-" * 60)
+    print(body_text(msg))
+    m.logout()
+
+
+def cmd_send(a):
+    body = a.body
+    if a.body_file:
+        body = open(a.body_file, encoding="utf-8").read()
+    msg = EmailMessage()
+    msg["From"] = addr()
+    msg["To"] = ", ".join(a.to)
+    msg["Subject"] = a.subject
+    msg["Date"] = formatdate(localtime=True)
+    msg.set_content(body)
+    for f in a.attach or []:
+        import mimetypes
+        ctype, _ = mimetypes.guess_type(f)
+        maintype, subtype = (ctype or "application/octet-stream").split("/", 1)
+        msg.add_attachment(open(f, "rb").read(), maintype=maintype, subtype=subtype, filename=os.path.basename(f))
+    raw = msg.as_bytes()
+    s = smtplib.SMTP_SSL(SMTP_HOST, SMTP_PORT, context=_ctx(), timeout=60)
+    s.login(addr(), code())
+    s.send_message(msg)
+    s.quit()
+    print("SMTP 已投递:", ", ".join(a.to))
+    # 自己留一份到「已发送」，否则在邮箱里看不到发送记录
+    m = imap()
+    m.append(_mb(SENT), "(\\Seen)", imaplib.Time2Internaldate(time.time()), raw)
+    m.logout()
+    print("已存入「已发送」")
+
+
+def main():
+    p = argparse.ArgumentParser(description="Coremail 邮箱 IMAP/SMTP 工具")
+    p.add_argument("--addr", default="", help="邮箱地址（默认取环境变量 CSU_MAIL_ADDR）")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("check").set_defaults(fn=cmd_check)
+    q = sub.add_parser("list"); q.add_argument("folder", nargs="?", default="INBOX"); q.add_argument("limit", nargs="?", type=int, default=10); q.set_defaults(fn=cmd_list)
+    q = sub.add_parser("search"); q.add_argument("keyword"); q.add_argument("folder", nargs="?", default="INBOX"); q.add_argument("limit", nargs="?", type=int, default=10); q.set_defaults(fn=cmd_search)
+    q = sub.add_parser("read"); q.add_argument("uid"); q.add_argument("folder", nargs="?", default="INBOX"); q.set_defaults(fn=cmd_read)
+    q = sub.add_parser("send"); q.add_argument("--to", action="append", required=True); q.add_argument("--subject", required=True); q.add_argument("--body", default=""); q.add_argument("--body-file"); q.add_argument("--attach", action="append"); q.set_defaults(fn=cmd_send)
+    a = p.parse_args()
+    global _ADDR
+    _ADDR = a.addr
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.