工作资料经常分散在 Word、Excel、Markdown 和纯文本文件中。每周整理工作周报时，通常需要先逐个打开文件，再复制内容、归纳重点，最后手动整理成报告，过程比较耗时。

因此我写了一个小型 Python 项目：Work Inbox Agent。它可以扫描指定目录，读取常见工作文档，提取统一格式的内容，并调用 DeepSeek 生成带来源引用的工作周报。

项目已经上传到 AtomGit：

项目地址：
Work-Inbox-Agent:本地读取 Word、Excel、Markdown 和文本资料，调用 DeepSeek 生成带来源引用的工作周报。 - AtomGit

一、项目功能

目前项目支持以下文件格式：

• .docx：读取 Word 段落和表格
• .xlsx：读取 Excel 工作表、表头、行数和前 50 行内容
• .md：读取 Markdown 文本
• .txt：读取普通文本文件

对于暂不支持的文件格式，程序会记录为unsupported，不会因为单个文件无法读取而中断整个扫描过程。

项目会将不同文件解析成统一的数据结构，主要包含：

• 文件名
• 文件类型
• 文件内容
• 文档章节
• 表格内容
• 文件元数据

之后可以将这些内容交给 DeepSeek，生成 Markdown 和 JSON 两种格式的工作周报。

二、项目处理流程

整个流程可以分为五步：

扫描工作资料目录 ↓ 识别文件类型 ↓ 提取 Word、Excel、Markdown 和文本内容 ↓ 整理为统一的数据结构 ↓ 调用 DeepSeek 生成周报

这样做的好处是，文件读取和 AI 总结相互独立。后续如果需要增加 PDF、CSV 或其他文件格式，只需要增加对应的读取器，不需要修改整个工作流。

三、项目结构

项目的主要目录如下：

work-inbox-agent/ ├── examples/ │ └── work-files/ ├── tests/ │ └── test_readers.py ├── work_inbox/ │ ├── readers/ │ │ ├── base.py │ │ ├── docx.py │ │ ├── text.py │ │ ├── xlsx.py │ │ └── registry.py │ ├── skills/ │ │ └── weekly_report/ │ ├── workflows/ │ │ └── weekly_report.py │ ├── cli.py │ ├── model_client.py │ └── models.py ├── .env.example ├── launcher.py ├── pyproject.toml └── README.md

其中：

• readers负责读取不同类型的文件
• models.py定义统一的数据模型
• model_client.py负责调用 DeepSeek
• workflows负责组织周报生成流程
• tests保存读取器相关测试
• launcher.py提供简单的桌面启动入口

四、如何安装

项目要求 Python 3.10 或更高版本。

先克隆项目：

git clone https://gitcode.com/weixin_62375676/Work-Inbox-Agent.git cd Work-Inbox-Agent

创建虚拟环境：

python -m venv .venv

macOS 或 Linux 执行：

source .venv/bin/activate

Windows 执行：

.venv\Scripts\activate

安装项目依赖：

pip install -e .

项目使用了以下主要依赖：

openpyxl openai python-docx python-dotenv

五、配置 DeepSeek

先复制环境变量示例文件：

cp .env.example .env

然后打开.env，填写自己的配置：

DEEPSEEK_API_KEY=你的密钥 DEEPSEEK_BASE_URL=https://api.deepseek.com DEEPSEEK_MODEL=deepseek-flash

真实的 API Key 不应该提交到 Git 仓库中。项目的.gitignore已经忽略了.env文件，公开项目时只保留.env.example。

这一点比较重要，因为 API Key 一旦被提交到公开仓库，可能会被其他人复制使用，造成费用损失或账号风险。

六、命令行使用

扫描资料目录并输出提取结果：

work-inbox scan ./examples/work-files \ --output ./output/extracted_documents.json

生成指定周期的周报：

work-inbox weekly ./examples/work-files \ --period "2026-09-28 至 2026-10-02"

也可以不安装命令行入口，直接使用 Python 模块：

python -m work_inbox.cli scan ./examples/work-files

生成的结果会包含每个文件的来源信息，方便后续检查周报内容是从哪一个文件提取出来的。

七、实现过程中比较重要的几个问题

1. 不同文件格式如何统一处理

Word、Excel 和文本文件的结构差异比较大。

Word 主要是段落和表格，Excel 主要是工作表、行和列，而 Markdown 和 TXT 只有文本内容。如果直接把不同读取结果交给后续逻辑，代码会比较混乱。

因此项目使用统一的数据结构保存解析结果，让后续工作流不需要关心具体的文件格式。

2. 单个文件读取失败不能影响全部任务

实际工作目录中可能存在损坏文件、临时文件或者不支持的格式。

如果遇到一个文件就直接抛出异常，整个周报任务可能会失败。因此当前设计会尽量记录文件状态，让其他可读取的文件继续处理。

3. API Key 不能写死在代码中

项目需要调用 DeepSeek API，但密钥不能直接写在 Python 文件中。

目前支持两种方式：

• 写入.env
• 在 macOS 启动界面中临时填写

无论采用哪种方式，都不应该把真实密钥提交到公开仓库。

4. 模型返回结果需要校验

项目要求模型返回 JSON，但模型返回内容不一定总是完全符合预期。因此代码会检查：

• 返回内容是否为空
• 内容是否可以解析为 JSON
• JSON 顶层是否为对象

如果返回结果不符合要求，程序会给出错误提示，而不是继续生成错误报告。

八、测试情况

项目当前包含读取器测试，覆盖了 Word、Excel、Markdown 和文本等基本场景。

本地运行测试：

python -m pytest

目前测试结果为：

5 passed

这说明当前基础读取功能可以正常通过测试。但项目仍然是一个小型工具，后续还需要增加更多测试，例如：

• 空文件处理
• 损坏文件处理
• 大型 Excel 文件处理
• 模型接口超时
• 模型返回格式错误
• 不同操作系统下的启动脚本测试

九、开源说明

这个项目使用 MIT License 发布。

MIT License 允许其他人学习、使用、修改和再发布项目，但需要保留原作者的版权声明和许可证内容。

项目目前更适合作为个人工作资料整理工具和学习项目使用。如果要应用在正式生产环境中，还需要进一步考虑：

• 工作资料中的隐私和敏感信息
• API 调用费用
• 文件权限
• 网络异常和重试
• 日志脱敏
• 大文件处理
• 模型输出的人工审核

尤其是工作资料中可能包含客户信息、公司内部信息或个人隐私，使用 AI 总结前应先确认资料是否允许发送到第三方模型服务。

十、后续计划

后续计划包括：

1. 增加 PDF 和 CSV 文件读取支持。
2. 增加更详细的文件读取日志。
3. 增加模型调用失败后的重试和超时处理。
4. 增加周报模板配置功能。
5. 增加更多测试用例。
6. 完善 Windows 和 macOS 的启动方式。
7. 增加敏感信息识别和脱敏功能。

结语

这个项目并不是一个大型系统，而是我针对实际工作资料整理场景编写的一个小工具。

通过这个项目，我也重新梳理了几个比较基础但实用的问题：

• 如何设计不同文件格式的统一读取接口
• 如何管理环境变量和 API Key
• 如何让单个文件异常不影响整体任务
• 如何校验 AI 返回的结构化结果
• 如何为一个 Python 工具补充测试和 README

如果你也经常需要整理 Word、Excel 和 Markdown 文件，可以试试这个项目，也欢迎在 AtomGit 仓库中提出 Issue 或改进建议。

项目地址：

Work-Inbox-Agent:本地读取 Word、Excel、Markdown 和文本资料，调用 DeepSeek 生成带来源引用的工作周报。 - AtomGit

本文使用 AI 辅助整理文字结构，项目代码、功能说明和测试结果均以实际仓库内容为准。