# 263 企业邮箱 × Codex：Windows 11 上手项目

[![Offline checks](https://github.com/DeritnesS/263-mail-codex-windows/actions/workflows/tests.yml/badge.svg)](https://github.com/DeritnesS/263-mail-codex-windows/actions/workflows/tests.yml)

让 Codex 快速查找 263 企业邮箱中的发票、对账单、付款通知及往来记录。面向 Windows 11 和不熟悉电脑操作的会计同事。**默认方案：本地邮件索引 + 只读增量同步，不部署知识蒸馏。**

**给同事的 Codex：先读 [AGENTS.md](AGENTS.md)，再读 [部署指令](docs/CODEX_HANDOFF.md)。先交付本地快速检索和及时同步，不要先搭大型知识库。**

本项目来自一套实际使用的邮件工作知识库的设计经验，但 Windows 版本是独立的轻量实现。公开仓库只包含通用代码、教程和虚构测试数据，不包含任何真实邮件、客户资料或凭据。

## 先分清三个东西

| 层次 | 用途 | 本仓库状态 | 会计同事默认需要吗 |
|---|---|---|---|
| A 只读增量同步 | 连接 263，保存指定范围内的新增邮件原件 | 已实现；每次只下载尚未缓存的 UID | **需要** |
| B 本地索引 | 邮件文字快速检索、离线查询、原件核对 | 已实现 SQLite 中文检索和只读 MCP | **需要，与 A 一起部署** |
| C 知识蒸馏 | 把跨邮件的项目、关系、规则和决策变成带来源的长期记忆 | 提供原理、数据契约和验收方案，尚未实现 | 通常不必；由她的 Codex 结合实际任务判断 |

日常查询走本地，不必每次登录 263。可设置登录期间每 5 分钟增量同步；问“现在最新的邮件”时，Codex 先调用刷新再查本地。**这是近实时同步，不是秒级推送。** 电脑关闭、休眠、网络断开或同步未完成时，必须显示最后成功同步时间和覆盖范围。首次建库分批进行，未同步部分不能冒充已覆盖。

## 她只需要从这里开始

1. 打开本仓库，点击 **Code → Download ZIP**，下载后右键 **全部解压缩**。也可以请她的 Codex 克隆仓库。
2. 把解压后的文件夹作为本地项目交给 Windows 上的 Codex。
3. 将下面这段话发给她的 Codex：

> 请阅读这个项目的 AGENTS.md 和 docs/CODEX_HANDOFF.md。我用 Windows 11 和 263 企业邮箱，是会计，不熟悉电脑操作。请帮我部署本地邮件索引和只读增量同步，让日常查询快速，需要最新邮件时能先刷新。能由你完成的安装、检查和配置请直接做；需要我操作时，一次只教一个动作，告诉我点哪里、应看到什么，等我完成再继续。密码或客户端授权码由我在本机遮蔽输入，不发到聊天中。先不要部署知识蒸馏，后续由你结合我的实际需求判断是否必要。

具体操作见 [Windows 新手教程](docs/WINDOWS_SETUP.md)。SQLite 随 Python 提供，无需单独安装数据库服务、WSL、Docker 或向量模型，也无需为这个连接器另填 OpenAI API Key；Codex 本身按她现有的账户和公司政策使用。

## 能做什么

- 列出邮箱文件夹，包括可访问的中文文件夹；从实际列表选择收件箱、已发送等目录。
- 在指定文件夹和日期范围内本地查询，可用中文关键词匹配标题、正文、发件人和附件名；未读筛选走专门的在线查询，避免使用过期的本地已读状态。
- 读取原邮件和附件清单，保留邮箱目录、UIDVALIDITY、UID、Message-ID、邮件哈希等定位信息。
- 首次同步保存完整 MIME 原件（其中包含附件）；之后按需提取允许类型的附件，交给 Codex 的文件工具分析。

它不发送、不删除、不移动邮件，也不主动设置已读。当前本地索引不搜索附件内部文本；PDF、Excel、扫描发票需在提取后另行读取，OCR 数字应对照原件。默认单封原件上限 25 MiB，超限会明示为覆盖缺口。具体示例见 [会计日常用法](docs/USAGE.md)。

## 文件导航

- [给 Codex 的部署指令](docs/CODEX_HANDOFF.md)：如何带电脑新手一步步完成，而不是让她自己排错。
- [Windows 安装与接入](docs/WINDOWS_SETUP.md)：安装、263 设置、凭据、MCP、验收和卸载。
- [故障排查](docs/TROUBLESHOOTING.md)：按失败环节检查，不反复猜密码。
- [实现与原项目关系](docs/ARCHITECTURE.md)：原系统如何工作，Windows 版做了哪些替换。
- [可选索引与知识蒸馏](docs/OPTIONAL_KNOWLEDGE.md)：为何需要、何时不需要，以及后续如何实施。
- [测试与现场验收](docs/ACCEPTANCE.md)：自动测试能证明什么、同事电脑还需要验证什么。
- [资料来源](docs/SOURCES.md)：官方配置和开发文档。

## 数据与边界

凭据仅存当前 Windows 用户的凭据管理器。配置、邮件原件、本地索引和提取附件默认存 `%LOCALAPPDATA%\Mail263Codex`，不放在 Git 仓库。邮件缓存和附件是本机明文文件，仍受公司电脑和文件管理制度约束；空间主要由原邮件及附件决定。

**本机连接器不等于模型离线运行。** 邮件正文、附件摘要等一旦提供给 Codex，就会进入该 Codex 账户使用的模型服务。部署前确认公司允许这种使用；不允许时由公司 IT 选择合规环境，不把真实资料放进 GitHub 或问题反馈。

工程测试与她的 263 现场登录是两回事。请以 [验收记录](docs/ACCEPTANCE.md) 和 GitHub Actions 为准，完成她本人电脑上的验收后再称为“已部署”。