廷平律助的整体架构采用了哪些技术

一、项目背景:要解决什么问题

律师助理做网上立案,大部分时间花在「把材料里的信息抄到网页上」:当事人身份信息、诉讼请求、事实与理由、证据清单,一项项填进立案页面,再逐个上传附件。案子一多,重复劳动多,还容易填错、漏传,被退回后又要重来。

廷平律助是我们做的一个 Windows 桌面工具,目标是把这部分重复劳动交给程序,判断和提交仍然留给律师。主要功能:

• 材料识别:放进身份证、营业执照、授权委托书、合同、判决书、转账记录等材料,程序识别出当事人信息和关键事实,列出来让人核对、补充。
• 生成起诉状:按案由的模板生成民事起诉状、授权委托书等 Word 文书,律师在此基础上修改。
• 自动填写立案页面:打开法院网上立案页面,把核对过的信息逐项填好、上传附件,停在提交前,由律师看过后自己决定是否提交。
• 批量立案、批量转执行:同一类案件用 Excel 模板一次导入、逐件填写;判决后可以从已有的立案记录一键生成申请执行。
• 立案前自检:提前检查必填项、证件号校验位、附件是否齐全、是否重复,减少因为低级问题被退回。

下面重点讲它背后的技术架构。

二、整体架构

系统分三部分:

1. Windows 客户端:界面、材料识别、文书生成、浏览器自动化都在本机完成,案件数据默认保存在本地。
2. 服务端:登录、意见反馈、云端识别和大模型抽取、文书段落生成、规则和模板下发。
3. 运营后台:给我们自己用的管理页面,看反馈、诊断、版本和数据。

另外有一条在线升级通道,客户端从 CDN 拉取新版本。

三、客户端:PySide6 + 配置驱动

客户端用 Python + PySide6(Qt)写。主窗口是常见的「左侧导航 + 右侧页面栈」结构:左侧 QListWidget 分「立案」(单件立案、批量立案、立案进度、立案记录)和「工具」(立案材料、意见反馈、律师工具箱)两组,右侧用 QStackedWidget 切换页面。

1. 每个案由一套配置

不同案由要填的字段、页面流程、分支条件都不一样。如果每加一个案由就写一段代码,很快就维护不动了。我们的做法是配置驱动:每个案由一个目录,里面放几份配置文件:

文件	作用
fields.yaml	这个案由要采集哪些字段、类型和校验规则
rules.yaml	字段怎么落到页面上的哪个控件
process.json / branches.json	页面流程和条件分支(比如原告是自然人还是法人)
doc_template.yaml	起诉状模板和引用的法律条文
testdata.json	用于回归测试的样例数据

目前有 40 多个案由目录,覆盖民间借贷、金融借款、信用卡、房屋租赁、物业服务、劳动争议、离婚、交通事故,以及几类申请执行。加一个新案由,主要工作是写配置和样例数据,而不是改引擎。

2. 文书生成

起诉状的段落由服务端按模板组装,发送前把姓名、证件号等个人信息替换成占位符,服务端只看到占位后的文本;客户端拿回结果后再把真实信息填回去,用 python-docx 生成 Word 文件。模板里的法律依据部分标注为需要执业律师审核。

四、浏览器自动化:Playwright + CDP

1. 连接方式

客户端会找本机装的 Edge 或 Chrome,用 --remote-debugging-port 启动一个独立的浏览器窗口,再用 Playwright 的 connect_over_cdp 连上去。日常的点击、输入、等待用 Playwright 的接口;个别需要更底层控制的地方(比如识别页面元素身份)直接发 CDP 命令。

这样做的好处是:浏览器是用户自己装的正式版,登录、证书、插件都和平时一样;律师可以随时在窗口里看到程序在做什么,也可以接手操作。

2. 页面识别:DOM 树 + 配置匹配

立案页面是组件库写的单页应用,控件的 id 经常是动态生成的,直接写死选择器很脆弱。我们的做法是先把页面整理成一棵 DOM 树,按标签文字、控件类型、所在区域等特征,和 rules.yaml 里的配置做匹配,找到「这个字段对应页面上的哪个控件」。填完之后还要做一次动作校验:回读控件的值,确认真的填进去了,而不是只发了一次事件。

3. 停在提交前:两道守卫

「不替律师提交」是硬性要求,我们在两个层面保证:

• 配置层:有一项专门的测试扫描所有案由的规则配置,只要出现点击「提交」类按钮的步骤,测试就失败,配置合不进去。
• 运行层:所有点击都经过统一的守卫函数,目标是提交类按钮时直接抛异常,流程停下并提示「请律师核对后自己在平台上提交」。

4. 防重复和自检

网上立案时,平台一创建草稿,客户端就把草稿编号记下来。同一案件再次运行时,先打开原来的草稿或者询问用户,避免重复建草稿。批量导入时,运行前先做一轮自检:必填项、身份证和统一社会信用代码的校验位、附件是否齐全、表格里有没有重复行。

五、材料识别:本地 OCR + 云端 + 大模型

识别分两层:

• 文字识别:默认走本地 OCR,用 RapidOCR(基于 onnxruntime),也能调用 Windows 自带的 OCR。用户同意后可以改用云端 OCR,精度更高;云端不可用时自动回退到本地。PDF 用 PyMuPDF 解析,Word 用 python-docx,Excel 用 openpyxl。
• 信息抽取:证件类材料(身份证正反面、营业执照、律师执业证、授权委托书)格式固定,用规则直接解析。合同、判决书、转账记录这类格式不固定的材料,交给服务端的大模型按固定提示词抽取字段。

大模型的结果不直接采信:每个抽取出来的值都要附上它在原文中的出处,客户端检查这段原文是否真的出现在材料里,对不上就标成「需要人工确认」。最终所有字段都会列给用户核对。

六、服务端

服务端比较轻:Python 标准库 WSGI 应用,用 waitress 运行,前面挂 nginx;数据库用 SQLite;部署用一个 Dockerfile 加 systemd 服务。

主要接口:

• 账号登录(微信扫码);
• 意见反馈和诊断信息接收;
• 云端 OCR 代理、大模型抽取(接口按 OpenAI 兼容的 /chat/completions 封装,方便切换模型);
• 文书段落生成;
• 案由模板和规则的发布,客户端可以在不升级程序的情况下拿到新规则。

附件直传对象存储

反馈附件、复现包、截图、诊断包都可能比较大,不经过服务器中转:客户端先向服务端申请一个几分钟有效的预签名上传地址,再直接上传到对象存储(COS),服务端只记录对象的 key。这样服务器带宽压力很小,也不用在服务器上存大文件。

七、在线升级

安装包用 Inno Setup 制作。升级走「发布清单 + 整包下载」:

1. 客户端读取发布清单,里面有新版本整包的 SHA256 和大小;
2. 优先从 CDN / 对象存储下载,失败时换备用地址,下载中断可以从 .part 文件续传;
3. 下载完成后校验哈希和大小,一致才安装。

没有做差分升级,是有意为之:整包更简单,出问题也好排查,对桌面工具来说体积可以接受。

八、运营后台

后台是 React 18 + Ant Design 5 + ProComponents,图表用 Ant Design Charts,Vite 构建,产物作为静态文件由服务端直接提供。主要用来查看用户反馈和诊断、版本分布和使用数据。ProComponents 的 ProTable、ProForm 对这种「列表 + 筛选 + 详情」的后台页面很省事。

九、测试

项目用 pytest,测试文件有 600 多个。除了常规单元测试,比较有用的几类是:

• 每个案由用 testdata.json 跑一遍配置校验和字段映射;
• 前面提到的「配置里不能出现提交」守卫测试;
• 发版前的版本号一致性检查。

十、小结

回头看,这个项目最关键的几个决定是:

1. 案由配置化:把变化最多的部分放进配置,引擎保持稳定;
2. 人始终在环里:识别结果要核对,自动填写停在提交前,由律师做最后决定;
3. 能在本地做的就在本地做:识别、文书、数据默认留在用户电脑上,上云的部分先脱敏、先征得同意。

如果你也在做「把材料变成网页表单」这类工具,希望这些做法能提供一点参考。