Files

wandering 1b35f07fd7 refactor: 架构重组 — doc/bot → core/infra，新增 Agent 调度模块

- src/doc/ 拆分为 src/core/extraction/, matching/, validation/（核心业务逻辑）
- src/bot/ 重命名为 src/infra/browser/（浏览器自动化基础设施）
- fill_consumable_doc.py → src/infra/documents/consumable.py
- 新增 Agent 调度模块：coordinator.py, events.py, session.py，重构 orchestrator.py
- 更新 AGENTS.md、README.md 及所有子目录 README

2026-07-02 18:36:19 +08:00

3.9 KiB

Raw Blame History

description, alwaysApply

description	alwaysApply
	true

last_reviewed: 2026-07-02

AGENTS — 项目操作指南

本文件为 Agent 提供高信号量的项目操作知识，避免重复探索。

文档边界

禁止使用表情文字输出任何内容。
docs/ 目录存放面向开源用户、外部贡献者的公开文档。
.agents/ 目录存放维护规范、实施方案、经验总结等内部资料。
每个文件夹下都有 README.md 说明该文件夹的作用和重要信息。

开发命令（必须使用 uv）

项目使用 uv 管理依赖，所有包版本锁定在 uv.lock 中。

操作	Makefile (跨平台)	tasks.py (Windows)
安装依赖 + pre-commit	`make install`	`python tasks.py install`
代码检查（lint+format+typecheck+deptry）	`make check`	`python tasks.py check`
运行测试（含覆盖率报告）	`make test`	`python tasks.py test`
运行 CLI 全流程	`make run`	`python tasks.py run`
清理缓存和虚拟环境	`make clean`	`python tasks.py clean`

注意： tasks.py 中的 check 命令使用 && 连接，Windows PowerShell 不支持 &&，但 tasks.py 内部已处理为单行字符串。

代码质量工具链（执行顺序）

Ruff lint — uv run ruff check . (select: E, F, W, I, N, UP, B; ignore: E501)
Ruff format — uv run ruff format --check . (line-length: 120)
MyPy strict mode — uv run mypy src/main.py (strict=true, warn_return_any, ignore_missing_imports)
deptry — uv run deptry . (检测未声明、未使用、过时依赖)

pre-commit 钩子（仅 Ruff）

.pre-commit-config.yaml 配置了两个 hook：

ruff --fix — lint 并自动修复
ruff-format — 格式化

注意： MyPy 和 deptry 不在 pre-commit 中，需要手动运行 make check。

项目架构（Agent 调度模式）

核心入口：src/agent/orchestrator.py — Agent 是负责调度的中枢，协调以下模块：

extraction/extractor.py — 文件扫描 → LLM 多模态提取 → JSON 缓存
matching/matcher.py — 支付记录与发票金额匹配
validation/validator.py — 声明式校验器（规则配置与引擎分离）
infra/browser/travel.py / normal.py — 浏览器自动化填报

数据流关键产物

文件	生成阶段	作用
`.invoice_cache/*.json`	extractor 提取	单张发票/支付记录的结构化数据
`match_result.json`	matcher 匹配	支付截图与发票的关联关系
`travel_info.json` / `normal_info.json`	LLM 综合提取	差旅/普通报销所需的全部结构化数据
`invoice_summary.csv`	extractor 提取	普通发票汇总（用于生成易耗品出库单）

缓存机制

CLI 模式：scripts/data/.invoice_cache/
Web 模式：src/web/uploads/<session_id>/.invoice_cache/

缓存文件与源文件同名（如 发票1.pdf → .invoice_cache/发票1.json），后续步骤均从缓存读取。删除缓存后下次处理会重新提取。

重要约束

Windows-only：易耗品出库单填写依赖 Microsoft Word + COM (pywin32)，仅 Windows 可用
浏览器自动化：使用 Playwright，填报时会打开 Chromium，请勿手动干扰
敏感信息：scripts/config.json 含登录凭据，勿提交到公开仓库
发票类型区分：差旅发票（高铁票/酒店住宿）不生成易耗品出库单，走差旅报销流程；普通发票生成出库单

Web 服务

uv run python src/web/app.py
# 访问 http://localhost:5000

Web 端浏览器填报以无头模式运行。会话产物存放在 src/web/uploads/<session_id>/，每次上传生成独立会话。

测试

make test   # pytest + coverage report (term-missing)

测试目录：tests/，配置在 pyproject.toml 中 (testpaths = ["tests"], pythonpath = ["."])。

3.9 KiB Raw Blame History Unescape Escape