Files

T

wandering ceefe3c4eb feat(mcp): P3 联机验证通过，新增 browser_open_form 断点续填，修 4 个联机才暴露的真 bug

联机跑通 open→login→new_form→fill(basic)→page_state→close：财务系统真的落库（单据编号 202610020850，
basic 页点「下一步」即保存）。据此补上续填能力并把测试草稿清理干净（删除前后截图 + 复查 0 命中）。

- 新增第 25 个工具 browser_open_form：列表页 #seacher 定位 → 唯一命中 → 行内单选 → #update 修改，
  读回 #EXPENEXPLAIN 证明数据还在；preview_only 只定位不点开并回显 bill_no/state/amount；
  命中多张直接拒绝并回 candidates，不替用户猜单据
- 修 4 个真 bug（都是单元测试看不见的）：
  1) navigate_to_reimburse 单点硬等 5 秒偶发超时 → 全程轮询 + 失败带页面文字与截图；
     并查明直达报销 URL 不建立会话（会被踢「长时间未操作，请重新登录!」），门户点击链是必经
  2) actor.close_all 用 atexit 注册无效：concurrent.futures.thread 的钩子走 threading._register_atexit，
     比 atexit 早跑，executor 已 shutdown → close 提交不进去。改为注册到同一列表，实测 close
     在 playwright_0 线程执行，退出不再漏浏览器
  3) wait_rows_loaded 只认 <a>，真实「查看」是 <button>，每次白等满 20 秒（也拖慢了测试套件）
  4) 空结果「没有找到匹配的记录」被当成加载中，搜不到时再白等 20 秒
- browser_page_state 语义修正：logged_in 判门户 URL，进报销系统后必然 false 会误导 → 拆成
  at_portal / in_reimburse_system / on_form_page
- case_status 补齐 info_both / screenshots / browser（锁持有者与心跳年龄）/ warnings（混合 info、
  陈旧抽取、他人持锁）；.browser.lock 文件名由 cases.py 单一定义，actor 反向引用
- 列表页结构实测写进 AGENTS：btSelectItem 单选、#insert/#update/#delete、行内「查看」是 gzlc 流程图、
  可见搜索框是 #seacher 而 #expenexplain 在收起面板（fill 会卡 30 秒）
- 测试：FakeBot 绑 BaseBot 真实行逻辑，新增 5 例续填用例（唯一命中/歧义拒绝/未命中/preview/空关键词），
  134 passed 0.36s；文档 docs/MCP.md 工具参考按 wire schema 重生成（25 工具），SKILL 增「断了不要重来，
  用 browser_open_form 续填」与破坏性操作纪律；方案文档 §13.5 记录联机结果、4 个 bug 与未完成项

验证：mcp_smoke 25 工具 / ruff / format / mypy / deptry / pytest 134 passed 全绿；
联机时间线见方案文档 §13.5。仍用 --no-verify 提交并手跑等价检查（原因见 AGENTS 提交纪律）。

2026-10-20 10:44:57 +08:00

9.0 KiB

Raw Blame History

description, alwaysApply

description	alwaysApply
	true

last_reviewed: 2026-10-19

AGENTS — 项目操作指南

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

文档边界

禁止使用表情文字输出任何内容。
docs/ 目录存放面向开源用户、外部贡献者的公开文档。
.agents/ 目录存放维护规范、实施方案、经验总结等内部资料。
报销业务的操作纪律在 .agents/skills/reimbursement/SKILL.md；工具契约在 docs/MCP.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`
MCP stdio 自检（起子进程握手列工具）	`make mcp-smoke`	`python tasks.py mcp-smoke`
启动上传收件器	`make upload`	`python tasks.py upload`
打印 MCP 注册参数	`make mcp`	`python tasks.py mcp`
清理缓存和虚拟环境	`make clean`	`python tasks.py clean`

没有 CLI 产品入口，也没有 Web 界面：业务入口只有 python -m src.mcp.server（stdio），工具在宿主里表现为 mcp__arb__<tool>。

注意： tasks.py 的 check 用 && 连接（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 — uv run python -m mypy src（整个 src 都在 strict 下，不只是某个入口文件）
deptry — uv run deptry .（检测未声明、未使用、过时依赖）

uv run mypy 在本机偶尔报 "uv trampoline failed to canonicalize script path"，用 uv run python -m mypy 代替。

提交纪律（血的教训）

门禁退出码要单独确认再提交，别把"跑检查"和"提交"写在同一条命令链里——检查失败也能走完流程。
本仓库 pre-commit 只挂 ruff，但它会 stash 未暂存改动再跑，跑完才还原。若这个过程被中断（超时/杀进程），未暂存的文件会被回滚成 HEAD 版本且 git fsck 捞不回来。本项目改造过程中真发生过一次，四个文件的改动靠锚点重放才恢复。
因此：提交前先把工作区改动 git add 干净，或用 --no-verify 提交并手动跑完等价检查（在提交说明里写明）。

项目架构（MCP 服务器模式）

唯一业务入口：python -m src.mcp.server（stdio）。编排（读图判断、缺料追问、是否提交）由宿主 Agent 完成，本项目不调用任何大模型，只提供确定性工具与内核。

src/mcp/ — 工具与协议层：server.py 注册与启动，tools/ 按 materials / extraction / analysis / documents / browser 分模块， schemas.py 抽取字段定义（单一真源），envelope.py 统一 {ok, ...} / {ok:false, reason, next_action} 信封
src/cases.py — 会话目录 cases/<case_id>/ 的唯一实现：材料、收件箱、产物与阶段推导（阶段由产物推导，不存在状态机文件）
src/core/ — 确定性内核：extraction/（缓存读写、PDF 渲染与文本层、自动转正）、matching/（金额匹配 + runner.py 从缓存匹配）、validation/（声明式规则校验）
src/infra/ — 基础设施：browser/（Playwright 填报 + actor.py 单线程持有者与磁盘锁）、documents/（CSV、申购单 Excel COM）、com_thread.py（COM 单线程串行 actor）
src/upload/ — 上传收件器（独立进程 python -m src.upload.server）：手机扫码/PC 上传落 cases/<id>/inbox/，不含业务编排，绝不由 MCP 子进程拉起

已删除：src/agent/（手写状态机与 SSE）、src/web/（Flask 界面）、src/main.py+pipeline*.py（CLI/双管道）、 core/extraction/{extractor,llm_extractor}.py（内置 LLM 与事件日志）、infra/llm/（提示词迁到 .agents/skills/reimbursement/references/）、 infra/documents/consumable.py（Word 出库单下线）、依赖 llama-index* 与 python-dotenv。

宿主侧两条硬约定

调 MCP 工具路径一律正斜杠（D:/Code/...），反斜杠会被 DSH 的参数绑定层拒收。
required: true 的字段（含值为空串的备注类）必须存在于 info JSON 中——这是刻意约束，别改规则文件；用 mcp__arb__info_skeleton 取骨架再填值，别凭记忆造结构。

数据流关键产物

文件	生成者	作用
`pages/<stem>/p01.png` + `text.txt` + `meta.json`	`case_render_pages`	给宿主读的页面与 PDF 文本层（含转正角度）
`.invoice_cache/<stem><ext>.json`	宿主抽取 → `case_save_extraction` 规范化落盘	单张票据结构化数据（小改用 `case_patch_extraction`）
`match_result.json` / `invoice_groups.json`	`match_payments`	支付与发票的关联、差旅/普通分组
`invoice_summary.csv` / `payment_records.csv`	`match_payments`	发票级与支付级汇总（申购单取数）
`travel_info.json` / `normal_info.json`	宿主综合 → `save_info`	差旅/普通报销的全部结构化数据
`artifacts/*.xls`	`doc_requisition`	低值易耗品申购单
`screenshots/NNN-<步骤>.png`	`browser_*` 分步填报	过程截图，出问题时给用户看
`.browser.lock`	`browser_open`	谁拥有该会话的浏览器（PID + 心跳，180 秒可接管）

缓存机制

会话缓存在 cases/<case_id>/.invoice_cache/，文件名与源文件同名（发票1.pdf → .invoice_cache/发票1.pdf.json）。缓存 JSON 的 _source_file + 内容指纹决定"是否陈旧"，case_status 会报 stale 项；删缓存即重抽。

重要约束

Windows-only：申购单依赖 Microsoft Excel + COM（pywin32）。所有 Office COM 调用必须走 src/infra/com_thread.py 的单线程 actor——并发驱动 Word/Excel 会互抢 ActiveDocument 与模态框；申购单空白模板在 templates/，可用环境变量 REQUISITION_TEMPLATE 指向别处，产物只写会话目录 artifacts/
浏览器自动化：Playwright，会打开 Chromium（默认有头），期间不要手动干扰。Playwright sync API 有 greenlet 线程亲和，所有调用必须走 src/infra/browser/actor.py 的单线程 actor（与 COM actor 分开，套间要求不同）；浏览器归属用 cases/<id>/.browser.lock（PID+心跳）声明。返回 owned_by_other_process 时不要另开窗口，那会让 Agent 看到的截图和实际操作的页面不是同一个
财务系统列表页结构（联机实测，别再猜）：行选择是 input[name=btSelectItem] 单选框，工具栏 #insert 新增 / #update 修改 / #delete 删除都作用于选中行；行内那个「查看」按钮是 gzlc() 工作流程图，不是打开单据。关键字搜索用右上角可见的 #seacher；#expenexplain 那套高级查询在收起的面板里（元素存在但不可见，fill 会卡 30 秒）。表格是 AJAX 后加载的，用 wait_rows_loaded() 等，别拍脑袋 wait_for_timeout。直达报销 URL 不建立会话，会被踢回「长时间未操作，请重新登录!」
多进程共存：宿主会保留旧代 stdio 子进程，subagent/teammate 也会各起一条 transport—— observed 4 个 PID 并存。因此任何"独占资源"（浏览器、Office）都要有磁盘锁，别假设只有一个服务器实例
敏感信息：scripts/data/config.json 含登录凭据、cases/ 含身份证号与卡号，两者都已在 .gitignore，绝不要提交，也不要回显密码
发票类型区分：差旅发票（高铁票/酒店住宿）走差旅报销流程，不生成申购单；普通发票生成低值易耗品申购单

上传收件器

uv run python -m src.upload.server            # 0.0.0.0:5055，手机扫码可用
uv run python -m src.upload.server --local    # 只监听 127.0.0.1
uv run python -m src.upload.server --pin 1234 # 额外访问码

页面地址由 case_create 返回（含每会话令牌）。安全边界：令牌强制（无令牌 403）、只写不读（无列表无下载）、扩展名白名单、25MB/文件、200 文件/会话、PIN 可选。二维码由服务端用 segno 生成，零外部 CDN。

测试

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

测试目录 tests/，配置在 pyproject.toml（testpaths、pythonpath=["."]）。 COM 相关路径（申购单）不进单测——需要本机装有 Excel，改动后用真实生成验证（约 2-5 秒）。改完 MCP 工具记得 make mcp-smoke（它验的是 wire 上的工具清单，不是进程内对象）。

9.0 KiB Raw Blame History Unescape Escape