Litigation Hub

---
name: litigation-hub
homepage: https://github.com/leahlu0124-creator/litigation-hub
author: 陆凌燕（北京德恒（无锡）律师事务所）
original_author: 杨卫薪律师
version: 2.4.7
license: MIT
description: 诉讼信息中枢系统。接收法院短信、送达链接、纸质文书照片，自动 OCR 识别、下载、归档、归类到标准案卷目录。基于 12 种期限规则库自动匹配，通过系统日历 + QQ 邮件（微信送达）+ 本机电脑提醒（系统通知 + 桌面 Markdown 文件）三条线提醒，支持 macOS / Windows / Linux 全平台。
slug: litigation-hub
displayName: 诉讼信息中枢系统
---

# 诉讼信息中枢系统

> 💡 **默认模型：DeepSeek V4 Pro**。处理长工作流和浏览器交互时最稳定。
>
> 💰 日常 zxfw 短信（80% 场景）可切 **DeepSeek V Flash** 省钱——脚本承担了 90% 工作量，模型只做调度。非 zxfw 平台切回 V4 Pro。

## ⚡ Quick Start（模型执行指南）

**默认全自动，零停顿。** 收到用户输入后，一条命令推到底：

```bash
# 短信
python3 scripts/court_full_pipeline.py --sms "原文"
# 照片
python3 scripts/court_full_pipeline.py --photo 照片路径
# 直接给链接
python3 scripts/court_full_pipeline.py --url "https://zxfw.court.gov.cn/..."
```

脚本自动完成全部 7 步：解析 → 下载 → PDF解析 → 通讯录保存（同号合并去重、存完整案件描述）→ 归档 → 日历提醒 → 通知+桌面MD → QQ邮件。模型只需呈报最终结果。

> 需要暂停确认时加 `--no-remind`，提醒单独跑 `--remind`。

**一次命令覆盖全部三条渠道**：系统日历 + 本机通知/桌面MD + QQ邮件——脚本内置，模型无需参与。

**非 zxfw 平台（gdems / 集约送达 / 湖北 / 司法送达网）**：脚本自动识别并在 `actions_needed` 中返回 `browser_download`。加载 `agent-browser` 技能用 Playwright 打开链接下载。

> **对比**：传统分步模式每步一个对话回合（5-8 回合），一键模式 **1 回合完成**。
> **JSON 过长时**：用 `--remind-file /tmp/court_report.json` 替代 `--remind '<JSON>'`。

**什么时候才用分步模式**：①非 zxfw 平台需浏览器交互 ②用户明确要求分步控制。

## 功能概述

处理法院文书的完整流程：**粘贴短信 / 发链接 / 上传照片 → 解析内容（OCR 或文本）→ 匹配案件 → 下载/归档文书 → 开庭日历提醒（传票自动写入系统日历 + 本机电脑提醒 + QQ 邮件（微信送达））→ 法院人员通讯录保存（传票/受理通知书自动提取法官、书记员姓名电话写入 macOS 通讯录）**。

---

## 一、首次使用：案卷目录设置（必须执行）

**用户第一次使用本技能时，必须先确认案卷存放目录。** 没有事先确认目录，后续搜遍整台电脑都找不到案卷。这一步一劳永逸。

**判断是否首次使用**：

1. 读取 `config/case-root.json`，检查 `case_root` 字段是否为有效路径
2. 文件不存在或 `case_root` 为空 → **首次使用**，按 [`references/首次使用引导.md`](references/首次使用引导.md) 的话术询问
3. `case_root` 已配置且路径存在 → 跳过，直接进入正式工作流

**用户回复后**：验证路径是否存在（`ls` / `dir`），不存在则创建 → 写入 `config/case-root.json`（结构见引导文件）→ 显示确认信息 → 继续执行正式工作流。

**后续使用**：

- 每次技能触发时从 `config/case-root.json` 读取路径，**仅在该目录下搜索已有案卷**
- **新建案卷始终放在桌面**，与 `case_root` 无关。桌面上的新案卷用户一眼就能看到，整理后自行移入搜索目录即可
- 用户搬移了案卷目录，说"更新案卷目录"即触发重新设置

---

## 二、执行模式

### 模式 A：一键全链路（默认 · 全自动零停顿）

用户粘贴短信 / 链接 / 照片时，**优先跑 `court_full_pipeline.py`，中间不暂停**。命令见 Quick Start。

脚本返回结构化 JSON，模型只需要做三件事：①解析 JSON，向用户展示报告 ②`actions_needed` 里有日历提醒需求时，询问用户是否确认创建 ③有浏览器下载需求时，提示用户打开链接。

### 模式 B：三种手动触发方式

用于需要逐步交互控制的场景。

| 方式 | 输入 | 处理路径 |
| --- | --- | --- |
| 方式一 | 粘贴短信原文 | 完整解析 → 下载 → 归档 |
| 方式二 | 直接发送送达链接 | **跳过短信文本解析**，从 URL 提取 `qdbh`、`sdbh`、`sdsin` 参数，进入第三步下载 |
| 方式三 | 上传纸质文书照片 / 扫描件 | 双级 OCR → 解析 → 复核 → 归档 + 日历提醒 |

三种输入形态的原文样例见 [`references/短信样例库.md`](references/短信样例库.md)。

### 模式 C：分步模式（四步）

第一步输入解析 → 第二步确定归档目录 → 第三步文书下载 → 第四步归档保存，另设第五步开庭日历提醒、第六步 PDF 后处理。

---

## 三、工作流

### 第一步：输入解析

1. 读取 `references/sms-patterns.json` 作为解析参考
2. **判断输入类型**：完整短信（法院签名 + 正文 + 链接）走完整解析；纯链接直接进第三步
3. **a) 短信分类**：根据关键词判断类型

   | 类型 | 特征 | 含下载链接 | 处理方式 |
   | --- | --- | --- | --- |
   | 文书送达 | 含送达平台链接 + 案号 | 是 | 下载文书并归档到案件目录 |
   | 立案通知 | 含"已立案"、"立案通知"等关键词 | 可能有 | 展示解析结果 |
   | 信息通知 | 无链接，纯信息 | 否 | 展示解析结果 |
4. **b) 案号提取**：正则 `[（(〔[]\d{4}[）)〕]]` 匹配标准案号，如 `（2025）苏0981民初1234号`、`(2024)粤0604执保5678号`、`〔2025〕京0105民初901号`
5. **c) 当事人提取**：从短信文本初步识别，最终以文书内容为准
   - ⛔ 短信中的称呼（如"张三，您好"）仅为短信接收人，**不作为案件当事人**
   - 公司名称：`xx有限责任公司`、`xx有限公司`、`xx股份有限公司`
   - 诉讼对峙：`A与B`、`A诉B`、`原告A 被告B`；角色前缀：`原告：xxx`、`被告：xxx`
   - 下载文书后，以起诉状、传票中的当事人信息为准，**覆盖短信阶段的初步判断**
   - **排除列表**：法院名称、法官姓名、地名、法律术语不应作为当事人提取，详见 `sms-patterns.json` → `party_extraction.exclude_keywords`
6. **d) 下载链接提取**：识别平台与参数

   | 平台 | 域名 | 下载方式 | 提取参数 |
   | --- | --- | --- | --- |
   | 全国法院统一送达平台 | `zxfw.court.gov.cn` | curl API 直连 | qdbh, sdbh, sdsin |
   | 广东法院电子送达 | `sd.gdems.com` | 浏览器自动化 | 路径中的送达标识码 |
   | 集约送达平台 | `jysd.10102368.com` | 浏览器自动化 | key |
   | 湖北电子送达 | `dzsd.hbfy.gov.cn` | HTTP API（免账号）/ 浏览器（账号模式） | 免账号：msg；账号模式：账号+密码 |
   | 司法送达网 | `sfpt.cdfy12368.gov.cn` | 纯 Playwright（无 API） | 验证码（手机尾号后6位 / 短信验证码） |

   同一平台可能使用不同域名（**同构异域名**），通过 URL 路径特征识别平台。

7. **e) 发送时间提取（P0）**：用于后续上诉期限计算
   - **优先来源**：zxfw API 响应中的 `dt_cjsj` 字段（送达记录创建时间，ISO 8601）
   - 短信网关时间：匹配 `发送：YYYY-MM-DD HH:mm`
   - 无法提取时展示"送达时间待确认"，不阻塞流程；记录到归档 JSON 的 `document.sent_at`

**输出格式**：

```text
📋 短信解析结果：
- 类型：文书送达
- 案号：（2025）苏0981民初1234号
- 当事人：张三、xx有限公司
- 下载链接：已提取（zxfw.court.gov.cn）
```

#### 照片 / 扫描件输入（方式三）

1. **双级 OCR 降级**：`scripts/court_photo_ocr.py` 按 Tesseract → MinerU 顺序自动尝试，每级结果经**质量门控**判断（综合中文字符数+占比+文本长度+案号+法院关键字，满分 100，**≥50 分通过**），通过即停止降级
   - 自动：`python3 scripts/court_photo_ocr.py /path/to/传票照片.jpg`
   - 指定引擎（调试）：`--ocr-tier tesseract` / `--ocr-tier mineru`
   - 评分细则、引擎对照、输出模板见 [`references/照片OCR分级.md`](references/照片OCR分级.md)
2. **结构化解析**：提取文字经正则匹配得到案号、案由、当事人、开庭时间/地点等，附带置信度标记
3. **后续流程**：识别到传票/出庭通知 → **跳过下载步骤** → 归档 + 日历提醒；识别到判决书 → 计算上诉期限
4. **自动归纳**：按 案号匹配（🥇）→ 当事人姓名匹配（🥈）→ 新建案卷（🥉）的优先级匹配已有案卷
   - ⚠️ **匹配到已有案卷必须经过律师确认，绝不自动写入**（理由与操作见第四步归档铁律）

### 第二步：确定归档目录

1. **扫描桌面**：识别目录结构，找到与短信案号或当事人匹配的案件目录
2. **查找归档子目录**：在匹配到的案件目录下查找法院文书相关子目录（如 `01*`、`法院送达`、`court` 等）
3. **匹配结果分两种情况**：
   - **未找到匹配案件** → **自动在桌面新建**（新建不污染既有案卷，故不询问），随后直接归档
   - **找到匹配案件** → **不自动归档**，立即向律师展示：①匹配到的文件夹路径 ②命中依据（案号/姓名）③同名同姓误归风险提示，请律师确认后再归档。确认后带 `--to-folder <路径>` 重新运行脚本完成归档

#### 确认代理方（首次接触案件时）

> ⛔ **每个案件第一次处理时必须确认代理方，否则后续无法区分「我方提交资料」和「对方提交资料」。**

1. **读取 `config/case-parties.json`**，检查该案号是否已记录代理方：已记录 → 直接使用；未记录 → 提问
2. **向用户提问**（从解析结果中提取已知当事人）：
   ```
   ⚖️ 案件 (2025)苏0981民初1234号，原告：张三，被告：xx有限公司。
   请问您是代理哪一方？
     → 原告 张三（我方）
     → 被告 xx有限公司（我方）
     → 暂时不确定
   ```
3. **记录答案**到 `config/case-parties.json`：

   ```json
   {
     "cases": {
       "（2025）苏0981民初1234号": {
         "represented_party": "原告",
         "party_name": "张三",
         "configured_at": "2026-07-13"
       }
     }
   }
   ```

4. **影响后续分类**：已知代理方 → 非法院文书归档时自动区分「02 我方提交资料」vs「03 对方提交资料」；选"暂时不确定" → 暂不区分，后续可通过"更新代理方 (2025)苏0981民初1234号 原告"手动补充

### 第三步：文书下载

> **⛔ 降级铁律**：严格串行，**禁止并行**。当前方案成功即停止，绝不降级。禁止"双保险"并行尝试多个方案。
> 降级链：zxfw 走 方案一（API 直连）→ 方案二（无头浏览器）→ 方案三（交互式浏览器）；gdems / jysd 跳过方案一。

- 依赖：`curl`（系统预装）、`jq`（可选）、Playwright（仅方案二/三需要）
- 各平台接口、命令、湖北两条链路、SFDW 验证码流程、三级全失败兜底话术，全部见 [`references/平台下载流程.md`](references/平台下载流程.md)
- **自动下载失败**（三级全失败）时，向用户展示原始链接请其手动下载，并创建待处理记录；兜底话术同样见该 references

### 第四步：归档保存

> ⚠️ **归档铁律：匹配到已有案卷必须经律师确认，绝不静默写入。** 同名同姓在中国极为普遍，错误归档会污染他人案卷，"找到即归档"是禁止行为。

1. **确定目标目录**：扫描桌面匹配案号或当事人
   - **未找到匹配案件** → **自动在桌面新建** `{原告}诉{被告} {案由}/`（安全，不询问），随后归档
   - **找到匹配案件** → **暂停，请求律师确认**：展示文件夹路径、命中依据、同名同姓风险提示；确认后带 `--to-folder <路径>` 重新运行脚本再归档
   - **如目标目录不存在，自动创建**
2. **获取当前日期**：`date "+%Y%m%d"`
3. **确定文书标题**：API 返回标题 → `sms-patterns.json` 的 `document_titles` 映射 → 原始文件名 → 兜底 `未知文书`
4. **构建文件名**：`{title}（{case_name}）_{YYYYMMDD}收.pdf`
   - 示例：`受理通知书（张三与李四合同纠纷）_20260404收.pdf`
   - 清理非法字符：`< > : " | ? * \ /`；如同名文件已存在，追加 `_2` 后缀
5. **按送达批次打包（强制执行）**：所有法院送达材料一律用日期子文件夹打包，**不得直接散放在 `01 法院送达文书/` 根目录**。法院可能分批发送不同文书，散放会导致批次混乱、无法区分送达时间
   - **哪怕是只有一份传票，也放进子文件夹里**
   - **文件夹命名**：`{命名文书}_{送达日期}送达/`。`送达日期` 取 API 响应中 `dt_cjsj` 的日期部分（如 `20260119`）或文书落款日期
   - **命名优先级**（所有文书地位并列，以下仅用于选文件夹名）：判决书 → 裁定书（不含判决）→ 传票 → 受理案件通知书 → 其他（举证通知、应诉通知等），对应 `一审法院判决书_20260318送达/`、`一审法院裁定书_20260401送达/`、`传票_20260601送达/`、`受理案件通知书_20260119送达/`、`举证通知书_20260520送达/`。**谁最"重"就用谁命名**，与文书本身的法律效力无关
   - **文件夹内文件保持 API 返回的原始文件名**，不重命名、不合并

   ```
   A公司诉B公司/01 法院送达文书/受理案件通知书_20260119送达/
   ├── 受理案件通知书.pdf
   ├── 交纳诉讼费用通知书.pdf
   └── ...

   李某诉C公司/01 法院送达文书/传票_20260601送达/
   └── 传票.pdf
   ```

6. **移入目标目录**：将子文件夹整体移入 `01 法院送达文书/`
7. **写入内部记录**：保存本次处理完整信息到**本技能目录下的 `archive/`**（即 `~/.workbuddy/skills/litigation-hub/archive/`），格式见 [`references/archive-format.md`](references/archive-format.md)
8. **自动归纳到桌面案卷**（短信/链接方式同样适用）：没有该案号文件夹 → 自动在桌面创建 `{原告}诉{被告} {案由}/` 再放入；已有 → **不自动放入**，展示匹配结果 + 同名同姓风险提示，请律师确认后带 `--to-folder <路径>` 重新运行
   - **当事人名称必须缩写至≤5字**：公司取简称（"A建设集团有限公司"→"A建设"、"B房地产开发有限公司"→"B公司"），自然人取姓名或简称
   - 标准案卷目录结构（**新建案卷时用这些固定名称，不得自行编造**）：

     ```
     {原告}诉{被告} {案由}/
     ├── 01 法院送达文书/     ← 传票、判决书、裁定书、通知书等所有法院来源材料
     ├── 02 我方提交资料/     ← 我方向法院递交的材料
     ├── 03 对方提交资料/     ← 对方通过法院送达的材料
     ├── 04 案件原始材料/     ← 从当事人收到的原始材料
     ├── 05 律师工作文本/     ← 法律意见、庭审提纲等
     ├── 06 委托签署材料/     ← 委托合同、授权书等
     ├── 07 邮件收寄记录/     ← 邮件往来记录
     ├── 08 法规类案检索/     ← 法律法规、类案报告
     ├── 09 法院庭审笔录/     ← 庭审、听证笔录
     └── 10 案件保全资料/     ← 财产、证据保全文书
     ```

   - 法院文书归入 `01 法院送达文书/` 对应子目录；照片原文件与 OCR 识别文本均保存到案卷下对应文书类型子目录
9. **基础文书解析**：法院 PDF 通常带文字层，提取首页文本快速识别文书类型
   - **传票**：提取开庭时间、地点、法庭、案号
   - **通知书/告知书**：提取缴费期限、举证期限等关键日期
   - **起诉状/答辩状**：提取案由、当事人、诉讼请求概要
   - **判决书**：识别为一审判决书，记录文书类型，触发上诉期限计算（P1）
   - **裁定书**：识别裁定类型。**⛔ 如正文含「冻结」「查封」「扣押」任一关键字，必须强制执行下面第 13 条期限规则匹配，不得因开庭日期已过、案件状态待定等任何理由跳过**
   - 其他文书：展示标题和法院名称
   - 一次下载多份则逐一解析，汇总为一份报告
   - > 深度分析（判决书解读、合同审查）**不在此技能范围内**，请使用专用分析技能
10. **向用户汇报**：按 [`references/report-format.md`](references/report-format.md) 输出结构化报告——归档完成信息（案号、法院、当事人、案由、文件数、位置）→ 文书清单 → 如含传票**高亮提醒开庭时间**、地点、审理程序 → 如含判决书展示上诉期限 → 如含传票/出庭通知/应诉通知书自动进入第五步 → 部分失败则列出失败文书和原始链接
11. **归档确认（P0 — 必须执行）**：展示归档结果，等待确认后才能进入提醒步骤
    - 输出归档清单：`文件 → {案卷路径}/{子目录}/文件名`；展示重复检测结果
    - **阻止后续操作**：在用户回复"确认"之前，**不得创建日历事件、系统通知、或发送邮件**
    - 用户可修改归档位置或报错
12. **❄️ 重复文件检测**：归档前检查目标目录是否已有同名或大小相似的文件
    - 文件名匹配：同名 → 提示"已存在，是否覆盖？"
    - 文件大小匹配：大小差异 **< 5%** → 提示"可能存在重复，是否跳过？"
    - 用户选择：跳过 / 覆盖 / 保留两个
13. **期限规则匹配（P0）**：识别到任何有期限要求的文书时，自动查表 `references/deadline-rules.json` 匹配对应规则
    - 规则库覆盖 **12 种文书类型**：民事/行政/刑事判决书、民事/行政/刑事裁定书、冻结银行存款、查封不动产、举证通知、答辩、执行、再审、管辖异议、缴费。**新增文书类型只需在 JSON 的 `rules` 数组追加条目，无需改代码**
    - **匹配逻辑**：文书类型 + 关键字标签（如"冻结""银行存款"）精确匹配
    - **提醒生成**：调用 `scripts/court_deadline_reminder.py` 统一设置 日历 + 本机电脑提醒 + QQ 邮件
    - **⚠️ 提醒确认（P0 — 必须执行）**：创建任何提醒前，必须先展示提醒计划并等用户确认（案号 / 规则 / 各条提醒时间与渠道），**回复「确认」创建提醒**，或指出需要修改的项。用户确认前不得调用任何提醒创建脚本；用户可改提醒时间、可加自定义提醒
    - **🔴 保全裁定强制处理（P0 — 不可跳过）**：文书为「裁定书」且内容含保全关键字（冻结、查封、扣押）时，无论开庭日期是否已过、案件状态是否待定，都执行：
      1. **提取保全详情**逐项展示确认：保全金额、保全方式、被申请人名称、裁定日期、审判员姓名
      2. **计算到期日**：**到期日 = 裁定日期 + 期限 - 1日**（期限对照表与法律依据见 [`references/保全期限计算.md`](references/保全期限计算.md)）
      3. **创建全部提醒（逐条核对）**：按 `deadline-rules.json` 匹配到的规则，**逐条创建所有 `reminders` 数组中的提醒**。⛔ **禁止部分创建**——规则里写了几个就必须全部创建，不允许只创建30天和到期日、漏掉14天和7天。到期日当天额外创建「🔴 保全到期」事件作为最后兜底
      4. **汇总确认**：展示完整提醒时间线，让用户一目了然
14. **📋 未处理文件追踪**：OCR 失败或无法归类的文件记入 `references/pending-items.json` 待处理清单；每次启动时检查并汇报还有多少未处理；用户指定归类位置后自动从清单移除
15. **📂 非法院文书智能归类**：对非法院发布的文件（代理词、委托书、合同、证据等），按文件名与内容关键词自动归类
    - `02 我方提交资料`：起诉状、答辩状、代理词、证据清单（**仅当文件涉及代理方时**）
    - `03 对方提交资料`：对方起诉状、对方答辩状、对方代理词（**仅当文件涉及对方当事人时**）
    - `04 案件原始材料`：合同、协议、借条、银行流水
    - `06 委托签署材料`：委托代理合同、授权委托书
    - 完整映射见 `scripts/court_utils.py` → `FILE_CATEGORY_MAP`
    - **代理方感知**：归类前先读 `config/case-parties.json`；已知代理方时，涉及代理方的诉讼文书优先归 `02 我方提交资料`，涉及对方的归 `03 对方提交资料`；未确认代理方时，归属不明的先暂存桌面待确认
16. **📅 法定节假日感知**：期限截止日如落在周末或法定假期，自动顺延至最近工作日
    - 数据源 `references/china-holidays.json`（来自国务院办公厅通知）
    - 每年 1 月 1 日后首次调用时，主动提醒检查当年节假日数据是否已更新
    - 期限内含长假（春节、国庆等）时，提示"实际可用工作日可能不足"

### 第五步：开庭日历提醒（macOS / Windows）

> **触发条件**：第四步解析出**传票 / 出庭通知 / 应诉通知书**时自动执行，无需用户操作。
> **重复安全**：写入前自动删除同一案号的旧事件和邮件提醒，不会重复创建。

下载 PDF 并解析出开庭信息后，自动完成三项工作（按系统平台选择实现）：

1. **系统日历事件**（macOS Apple Calendar / Windows Outlook "工作"分组）
2. **QQ 邮件（微信送达）通知**（跨平台，提前1天发送）
3. **本机电脑提醒**（系统通知中心弹窗 + **桌面 Markdown** 提醒文件，双保险）
   - 桌面文件 `开庭提醒_YYYY-MM-DD_HHMM.md` 写明日期/时间/案由/案号/地点及**需准备材料清单**（传票、证据原件、委托手续等）。即使系统通知被勿扰屏蔽，回到桌面也能看到——这是本机提醒的持久化兜底

| 平台 | 日历 | 定时提醒 | 本机电脑提醒 |
| --- | --- | --- | --- |
| macOS | Apple Calendar (AppleScript) | launchd plist | 系统通知 + 桌面 Markdown 文件 |
| Windows | Outlook COM → 失败则 .ics 兜底 | schtasks | MessageBox 弹窗 + 桌面 Markdown 文件 |
| Linux | .ics 日历文件（双击导入） | ❌ | 桌面 Markdown 文件 |

- 判定规则：文书标题或类型含 **传票 / 出庭通知 / 开庭 / 应诉通知书** 任一关键词即触发
- 去重由脚本 `delete_court_events()` 负责，写入前先清理同案号旧事件再重建
- 提取正则、`court_calendar.py` 命令、AppleScript 事件字段、QQ 邮件模板、异常处理分支（含 pypdf 未安装）、用户侧汇报模板，全部见 [`references/日历与邮件提醒.md`](references/日历与邮件提醒.md)

### 第六步：PDF 后处理（可选）

> **不默认启用**。仅在检测到文件拆分时主动提示用户。

归档完成后扫描目标目录中的 PDF，检测同一文书是否被拆分为多个文件。

1. **读取偏好**：`config/user-preferences.json`（不存在则用默认值，参考 `config/user-preferences.example.json`）
2. **触发检测**：读取 `sms-patterns.json` → `post_processing.trigger`，按规则分组——证据类按编号分组（证据1、证据2…）、其他文书按文书类型分组；任一组文件数 > 3（**threshold**）即触发提示（如"证据3 下有 10 个 PDF"）
3. **用户确认**：用 `AskUserQuestion` 列出拆分情况，选项为「是，合并所有 / 让我选择（逐个确认） / 跳过」
4. **执行**：按 `merge_strategy` 选策略——`per_evidence`（默认，按单个证据编号分别合并）或 `unified`（合并为一个 PDF 并加书签）
5. 具体做法（两策略细节、A4 页面标准化、精简文件名 `strip_patterns` 与特殊映射）见 [`references/PDF后处理.md`](references/PDF后处理.md)

---

## 四、内部归档格式

每次处理完成后在 `archive/` 下创建 JSON 记录，格式详见 [`references/archive-format.md`](references/archive-format.md)。

> ⚠️ **发布前清空**：`archive/` 目录在运行时自动写入真实案件记录，对外发布前必须清空所有 `.json` 文件（保留 `.gitkeep` 和目录结构），确保案件数据不外泄。

---

## 五、故障排除

| 问题 | 解决方案 |
| --- | --- |
| 短信无法识别类型 | 展示原文，请用户确认类型后继续 |
| 案号提取失败 | 手动输入案号 |
| 当事人识别不准 | 提示用户确认/修正当事人列表 |
| 无匹配案件 | 自动在桌面新建（缩写至≤5字，不询问） |
| 找到已有案卷 | **不自动归档**：展示匹配路径 + 命中依据 + 同名同姓风险，确认后带 `--to-folder <路径>` 重新运行 |
| 目标目录不存在 | 自动创建对应目录 |
| Playwright 下载超时 | 检查网络连接，尝试刷新页面重试 |
| 页面需要验证码 | 通知用户，暂停等待手动处理 |
| 下载文件损坏 | 清理临时目录，重新尝试下载 |
| SFDW 验证码验证失败 | 手机尾号后6位与短信验证码都试，均失败提示用户联系法院 |
| 日历创建失败 | pypdf 未安装则提示安装并跳过；再查 Calendar 自动化权限（系统设置→隐私与安全性→自动化） |
| 日历事件重复或报 -600 | 已内置去重；-600 多为冷启动假失败，先查事件是否已存在再决定降级 .ics；如仍有残留 plist 查 `ls ~/Library/LaunchAgents/com.mm.court-*` |
| QQ 邮件（微信送达）未收到 | 查 `~/.court-email/*-err.log`；检查是否被归入垃圾箱；确认授权码未过期（腾讯授权码通常 90 天） |
| launchd 邮件提醒未触发 | 查 `~/.court-email/*.log`；确认 plist 已加载：`launchctl list \| grep court-email` |
| 联系人未写入通讯录 | 检查"自动化"权限是否允许访问"通讯录"；手动测试 `python3 scripts/court_contacts.py check 13800138000` |
| 联系人提取不完整 | 法院文书格式差异大，无法保证 100% 提取。手动补充：`python3 scripts/court_contacts.py add '[{"name":"张三","phone":"13800138000","role":"审判员","case_no":"(2025)苏XXXX民初XXXX号","court":"XX法院"}]'` |
| 照片文字识别不准 | 系统自动双级降级（Tesseract 预处理 → MinerU）；可手动指定 `--ocr-tier tesseract` / `--ocr-tier mineru` |

---

## 六、配置

- **解析规则**：`references/sms-patterns.json`。添加新文书标题、调整正则等，编辑该 JSON 即可
- **期限规则**：`references/deadline-rules.json`。新增文书类型只需追加 JSON 条目，**无需改代码**
- **代理方记录**：`config/case-parties.json`。每个案件首次处理时自动询问并记录，可用"更新代理方 <案号> <原告/被告>"手动修改
- **案卷目录**：`config/case-root.json`。首次使用询问并缓存案卷根目录路径
- **用户偏好**：`config/user-preferences.json`。合并策略、重命名偏好、收件邮箱
- **变更记录**：完整版本历史见 `CHANGELOG.md`；本文件只放规则，不放变更史

---

> 法律科技实务工具 · 维护者陆凌燕律师（北京德恒·无锡）· 关注公众号「鹿鸣于野 UMU」获取更多内容