mqc-timeline-master · diff
v2.0.0 to v2.0.1
225 added, 5 removed. Audit A to A.
---
name: mqc-timeline-master
+ tags: [法律, 诉讼可视化, 律师, 时间轴, 案件经过, 制图]
metadata:
author: 缪奇川
- version: 2.0.0
- last_updated: 2026-08-19
+ version: 2.0.1
+ last_updated: 2026-08-23
description: >-
Turn raw case materials into a faithful, court-ready case timeline (SVG + PNG +
PPTX + VSDX + drawio, plus a traceability index in Word). Use this whenever the
user hands over litigation materials — a judgment, complaint, defence, evidence
list, contract, bank or Alipay statement, WeChat screenshots, scanned exhibits,
photos, or just a spoken account — and wants the chronology drawn: 时间轴,
案件经过时间轴, 事实经过, 时间线, 梳理时间, 把经过画出来, 做一张时间轴图,
诉讼时效时间轴, 履约经过, 付款经过, 供货经过, 催告与送达经过, 两方主张对读.
Also trigger when the user says 帮我梳理一下这个案子的经过, 把这些材料做成图,
这些证据整理成时间轴, or supplies scanned/photographed materials with no text
layer and expects them read. Handles multiple materials at once, mixed formats
(docx / txt / text-layer PDF / scanned PDF / images), and declares which events
came from reading images. Default scenario is Chinese litigation; internal
instructions are in Chinese because the constraints they encode were written
and argued in Chinese.
---
+ # 新诉讼可视化 · 时间轴大师
+
+ 时间轴大师，用数学，画准一张时间轴。
+
+ ## 它替你解决的那件事
+
+ 律师手上的材料是散的。一份判决书、几份合同、一叠证据目录、一段微信记录、
+ 几张手机拍的照片，时间散落在其中。要把这些变成一张能交出去的图，难的从来不是画，
+ 是两件事：该上图的事有没有抽全，抽全了排不排得下。
+
+ 这个模块把这两件事分开做。前半段读材料，判断哪一句写的是已经发生的事实，把它们
+ 归成事项；后半段接过这份清单，用纸张的物理尺寸算出每一个模块该摆在哪里、能有多宽、
+ 能写多少字。两段之间只交接一个数，交接完就互不干涉。
+
+ 材料怎么顺手怎么给：判决书、起诉状、答辩状、代理意见、合同、证据目录、银行与
+ 支付宝流水、微信聊天记录、扫描件、手机照片，甚至一段口述。不必先整理，不必改格式，
+ 也不必自己先画一张。没有文字层的扫描件与照片同样读得出来，做法是先逐页探测可读
+ 字符数，再按 150 DPI 栅格化，然后逐页看图；交付时会声明哪几份出自读图，那几项请你
+ 自己回原件复核一遍。
+
+ ## 为什么能画准：位置、尺寸、容量全部是算出来的
+
+ 一张 A4 有多宽是定死的。绘图宽 958 px，来自 A4 横版的 1070 减去两侧各 56 的留白。
+ 这个数不由人改，后面所有的数都从它推出来。
+
+ 推的顺序是一环扣一环的。时间轴上有几个时点，轴就被分成几段，每一段的长度决定了模块
+ 落在哪里；位置定住，才知道相邻两个模块之间还剩多少空；剩多少空，决定一个模块能有
+ 多宽；宽度定了，才知道这个模块能写几个字。所以先定位置，再定尺寸，最后才定能写
+ 多少字，不能倒过来。
+
+ 这些数不是查表得来的，换一份材料就换一组。编号型的卡宽由事项数压出来：八个事项时
+ 189 px、十二个时 121 px、十六个时 96 px，卡片跟着变矮变窄，列距也从 110 收到 58。
+ 日期型不一样，它的卡宽固定 214 px，因为时点多了是轴上挤、不是卡片变窄，正文至多
+ 六行、约 84 字。期间型更特别，它的容量不是一个数而是每段各一个，条身长度由那一段的
+ 真实天数决定，同一张图上各段差别可以从一个字到三十九个字。
+
+ 放得下几个模块，同样是算的。第一道是一条不等式：
+
+ 模块宽 × n ≤ 绘图宽 × 层数
+
+ 全部模块的横向总宽不许超过绘图宽乘层数。它抓的是逐字段比对抓不住的那一类错，也就是
+ 每个数看着都对、合起来却自相矛盾。
+
+ 参数交出来之后还有第二道，用一组恒成立的关系把它验算一遍：
+
+ 图宽 = 2 · 边距 + (n−1) · 列距 + 最小模块宽
+
+ 等式两边只要差 0.5 像素就当场报错，并指名是哪一处尺寸算漏了。四项、八项、十二项、
+ 十六项、二十项五档实测，差全部是 0.00。这一列不是差不多，是精确相等。
+
+ 交接的顺序也是定死的：前端交出事项清单，后端按这一档的几何算出每个模块能写多少字，
+ 把这个数交回去，前端再按这个数把字写到位。反过来先写好再排，就只剩两条路，
+ 把字截掉或者把版面挤坏。
+
+ 抽事实那一段没有公式可用。哪一句是事实、哪几句属于同一件事，是读懂内容之后的判断，
+ 正则拿不到（试过一版按日期与文书名切分的正则切割器，在真材料上切出三组同名、一组
+ 吞掉六成句子）。所以那一段交给模型做，代价是每一条判断都要能对回原句去核。
+
+ ## 图上的字，回得去原句
+
+ 卡片上每一段文字，都必须是原句删掉一些字之后剩下的样子。以原句「2021年3月5日，
+ 双方签订设备采购合同」为例：写成「双方签订设备采购合同」通过；写成「双方签署」
+ 换了词，拦住；写成「设备采购合同由双方签订」调了词序，拦住；补一个原句没有的字，
+ 同样拦住。所以图上的每一句都指得回材料里的哪一句。
+
+ 不进主轴的有三类：合同条款是约定，诉请是主张，付款计划是承诺。要画到期未付，
+ 材料里得另有记载，比如一笔付款回单、一份催告函、一次对账。它不评价证据，
+ 不认定事实，不给法律意见。
+
+ ## 三种形态，由材料的性质定
+
+ 编号型（`numbered_point_timeline`）的轴上距离只表先后，等距排开。时点密集、或者
+ 没有精确日期时用它。它是阶梯的底，永远画得出。
+
+ 日期型（`dated_point_timeline`）的轴按等长单位格铺开，距离本身在说话。时效届满与
+ 起诉之间隔了多久、催告之后沉默了多久，这一类论点不在事情本身、在事情之间的距离上。
+ 只有日期型能让空白成为证据。
+
+ 期间型（`proportional_gantt`）把几段有长度的期间画成条，条长与重叠位置就是主张。
+ 诉讼时效、保证期间、借款与计息起止、工期顺延与停工、租赁期、代持期，都属于这一档。
+ 它还能同时承载时点，落在轴上画成虚线竖线加标注，所以不必另造一种混合型。
+
+ 形态不由人选。判定顺序是期间型、日期型、编号型，材料的性质满足哪一档的硬条件就走
+ 哪一档。
+
+ ## 泳道：有几方各自的主张，就分几道
+
+ 单侧用于只有一方叙述的材料，全部事项落在轴的一侧。这一档是有讲究的：一方转述对方的
+ 话仍然带着这一方的身份，所以只有一方的材料就是单侧，不许分两侧标上原告主张与被告
+ 主张。
+
+ 双泳道用于两方各自的材料对读，比如判决书里的诉称与辩称、起诉状对答辩状。原告在上、
+ 被告在下，这个上下是材料给的语义，不许翻转。
+
+ 同一侧还可以再拆成多条横带，每侧最多三条、两侧共六条。它用来体现层级关系，
+ 比如集团与子公司与项目公司、一审与二审与执行、主债务与保证与反担保。要说明的是，
+ 横带是几何上的错开，泳道是语义上的分方，两件事不是一件：同一方的内容始终放在一起，
+ 所以侧标签始终只有两个，上方一个、下方一个。
+
+ 侧标签只写百分百确认得了的东西：材料上写着的身份或角色，比如原告与被告、甲方与乙方、
+ 供货方与采购方、支出与收入、公司名。自认、违约、抗辩这类法律定性一律不写，说不准就
+ 不出侧标签。
+
+ ## 排不开的时候它不硬画
+
+ 不缩字号，不截断，不硬塞。横向放得下几个事项由这一档的几何算出来，字越多每张卡越高，
+ 能叠的层就越少，上限跟着降。走不通就自动落到下一档：日期型排不开就走编号型，横向排
+ 不开就转成纵向长图并分页，纵向的事项数没有上限。所以它总归给得出一张图，或者当场
+ 指名是哪一条约束不成立。
+
+ 同一份材料，换谁跑、跑几次，出来都是同一张图。难的那部分不在模型手里，所以换一个更
+ 弱的模型，出来仍是同一张。
+
+ ## 它只画时间轴
+
+ 流程图、当事人关系图、层级树、A/B 对比表不在这里，柱状图折线图饼图这类数据图表
+ 也不做。那三类共七种由同一个插件里的 `mqc-litigation-visual-redraw`（诉讼可视化重画）
+ 负责，它同时也能把你已经有的一张图重画得更好看。
+
+ ## 你会拿到什么
+
+ 一次交出五个文件，全部转写自同一份母版，位置与尺寸逐元素对齐，不是各画一遍：
+
+ | 文件 | 用什么打开 | 给谁用 |
+ | --- | --- | --- |
+ | `.svg` | Illustrator · Figma · 浏览器 | 主交付物，插进 Word 再编辑 |
+ | `.pptx` | PowerPoint · WPS | 讲课与庭前演示，每个方框双击就能改字 |
+ | `.vsdx` | ProcessOn · Visio · WPS · Edraw | 在你本来就在用的那个工具里接着改 |
+ | `.drawio` | draw.io | 同上 |
+ | `.png` | 任何看图工具 | 定稿位图，插进 Word 直接打印、微信发 |
+
+ 除 `.png` 是位图之外，另外四种都能继续编辑，方框选得中、文字改得动，不是把图片贴
+ 进容器。
+
+ 三种视觉风格共用同一套几何，变的只是表达。奇川风以灰阶为底、一处深红标重点，交
+ 当事人与客户；白描是纯黑白线稿，为打印、复印与卷宗附件准备；歸藏风用克莱因蓝，
+ 适合讲课与对外传播。
+
+ 另附一份溯源索引，是一份 Word 三线表，五列：序号、图上的元素、出自哪一份材料、
+ 哪一句、核验方式。文字层材料标逐字，读图来的那几项标读图并单独说明它们没有文字层
+ 可以逐字比对，请你自己回原件复核。打印出来夹在卷宗里，逐项对得回去；哪一项不对，
+ 当场指得出来。
+
+ ## 重画那一套的优势，整套继承下来
+
+ 时间轴大师不是从零起步的。同一个插件里的第一个模块诉讼可视化重画已经开源并冻结，
+ 它的四样东西这里原样继承，一个字都没重写：同一套几何（圆角、拐角、箭头、连线，
+ 一个数都没重新拍过）、同一套视觉（三档风格、灰阶分层、深红是唯一的重音）、同一套导出
+ （五种格式的转写器，逐元素对齐）、同一套纪律（只许删不许改写，排布走不通就落档、
+ 不硬画）。
+
+ 所以它一上手就是成品的样子：同样的审美、同样的克制、同样能直接打印。新增的那一半是
+ 把材料读成事实、把排布算准，这两件重画本来不做。
+
+ ## 装在哪都能用
+
+ 这是一个标准的 `SKILL.md` 目录，没有任何产品特定的胶水代码。凡是能读 skill 指令的
+ agent 都装得上：Claude Code 用两行命令从插件市场装（`/plugin marketplace add` 加
+ `/plugin install`），Codex 放进 skills 目录，DeepSeek Harness 挂 `customSkillDirs`
+ 即可、不必构建，Cursor 与 Aider 等读的是同一份 `SKILL.md`。同一份仓库，不维护两套。
+
+ 两个模块都不联网、不调外部接口、不需要任何凭据，只读你给的材料，只往你指定的目录
+ 写文件。
+
+ ## 你要做的只有勾选
+
+ 最多五个问题：材料用哪几份、时间取哪一段、这张图呈报给谁、整份还是取其中几段、深红
+ 标在哪一处。报个编号就行，不写代码，不改配置，不学语法。
+
+ 该问的才问，三处会自己跳过：只有一份材料时不问第一问；材料里日期不足八个、或者只
+ 覆盖一小段时间时不问第二问；风格不是奇川风时不问标红那一问，因为白描是单色、
+ 歸藏风有自己的视觉规则。不回答就走默认。
+
+ 其余的一律不问：图种、层数、卡宽、字数、分页，那些是算出来的。
+
+ ## 质量
+
+ 排布的五条产出路径各有一套常驻穷举，合计 2476 种情形：期间型 1260、期间型形态 360、
+ 日期型 640、纵向 180、分页 36。每一组的结局只许两种，要么拒绝并给出机械理由，
+ 要么画出来且十项全过，中间那种一组都不许有。此外还有横向容量附表 44 格逐格实际
+ 渲染核对、阶梯兜底 6 组（四个到一百二十个事项，必须永远给得出图）。不是抽样，
+ 不是挑几组跑给人看，每改一次全跑一遍，碰坏任何一种当场就红。
+
+ 两百多条回归判据，每一条都做过故意改坏必须报错的验证。约束表分 C、D、M、P 四个
+ 系列，每条约束带编号，代码里执行它的那一行带同样编号的标记，守卫比对两边的编号
+ 集合，缺一个多一个都报错，所以文档与实现漂开会被当场抓住。
+
+ 零第三方依赖，纯 Python 3 标准库。
+
+ ## 装完先跑一次自检
+
+ Python 3。出 PNG 需要 LibreOffice 或 poppler，读扫描件需要 poppler 的 `pdftoppm`，
+ 溯源索引需要 node。装完跑一次环境自检，它会逐项告诉你缺什么、缺了会退化成什么样。
+ 没有一项是装不上，都是少一种格式。
+
+ 自检脚本属于共享内核。在完整仓库里，它在同级的重画模块下：
+
+ python3 ../mqc-litigation-visual-redraw/scripts/doctor.py
+
+ 在 SkillHub 那种单目录分发包里，内核随包带上，直接跑：
+
+ python3 scripts/doctor.py
+
+ 完整文档、约束表与决策记录：https://github.com/MiaoQichuan/new-litigation-visualization
+
+ ---
+
+ 以下为供 AI 读取的操作说明，请勿改写。
+
# 时间轴大师
这个 skill 是 **`mqc-timeline-master`** ——**新诉讼可视化 · New Litigation
Visualization**（把法律画出来）的时间轴模块。它把律师手上的原始材料**忠实还原**成一张
案件经过时间轴。
与 v1（`mqc-litigation-visual-redraw`，重画既有图）的分工：**v1 重画，本模块从材料还原。**
v1 已冻结，本模块复用它的渲染内核与五种格式导出器，不改它一个字。
## 这个 skill 的立场
**它不是一个通用图表工具，是一个还原工具。**
图上的每一个字都要能追回材料原文。所以这里的全部约束都指向一件事：**模型可以答错，
但不许错得无声**。凡是模型的判断，都要能对句子逐一核验。
三条最要紧的红线，违反其一这张图就不能交：
| 绝不 | 改为 |
| --- | --- |
| 手写 SVG 坐标、凭眼睛摆位置 | 写 JSON，几何全部由脚本算 |
| 改写材料的字（换词、调顺序、补字、概括） | 只许删减；卡片每段文字**必须是原句的子序列** |
| 把没发生的事画成发生了（承诺、约定、诉请、我的判断） | 只画客观发生过的事；说不准就不画 |
## 先读什么
**总是先读这一份。** 然后按需要打开，不要全部预载：
| 你要做的 | 读这个 |
| --- | --- |
| 判哪句是事实、抽事项、写正文（模型那一半的活） | `references/model-steps.md` |
| 前后端怎么对接、容量握手、读图、侧标签怎么起名 | `references/front-end.md` |
| 图为什么长这样、每个数从哪来（C / D / M / P 约束表） | `references/layout-constraints.md` |
+ | 报错了、卡住了、不确定某句提示是不是失败 | `references/troubleshooting.md`（**一处查完，不用翻别处**） |
| 一件事**为什么这么定**、当时否掉了哪些做法 | `docs/adr/`（**动手改之前先读**） |
| 四份 JSON 的形状与判据 | `python scripts/pipeline.py shape verdicts.json` |
`docs/adr/` 那一条要认真：几十轮接力里，同一件事被重新讨论过多次（扫描件能不能读三轮、
侧标签怎么定两轮）。**你想到的做法多半已经被试过并写了失败原因。**
## 黄金律：模型读懂意思，代码算和验
- **模型做**：读材料（含读图）、判哪句是已发生的事实、划分、抽事项、按容量把字写到位。
- **代码做**：算容量、验模型的输出、出图。**代码不做拆解** —— 哪几句属于同一件事，
是读懂内容之后的判断，正则拿不到（试过一版正则切割器，在真材料上切出三组同名、
一组吞掉六成句子）。
所以这条路是**两趟**，不是猜一趟：先定骨架 → 代码算出容量 → 再按容量写字。
- ## 工作流（九步，四轮交互都在前段）
+ ## 工作流（agent 的执行管线）
+ **下面这张表是给你（agent）看的，不是用户要做的步骤。** 用户那一侧只有一句话加几次
+ 勾选：他把材料丢进来、说一句「把这些材料画成时间轴」，然后在你问的时候报个编号。
+ 这些命令由你来跑，他不需要敲任何一条，也不需要知道它们存在。
+
python scripts/pipeline.py next # 现在走到第几步、下一步跑什么、缺哪个文件
python scripts/pipeline.py steps # 随时打印这张表
**中途接手就先跑 `next`。** 换了会话、跑错顺序、文件写坏之后，不要靠猜 —— 它按产物
而不是自称判断走到了哪一步。
- **没有「一键出图」，这是故意的**：下面九步里有四步必须等用户回答，
- 一口气跑完等于替他答了那四轮，而那四轮是这个 skill 的设计核心。
+ **没有「一键跑完」，这是故意的**：表里标着「用户」的那几步必须等他回答，一口气跑完
+ 等于替他答了，而那几轮勾选是这个 skill 的设计核心。对用户来说这不是几个步骤，是几次
+ 勾选 —— 该问的才问，不回答就走默认。
| 命令 | 谁做 | 做什么 | 要先写的文件 |
| --- | --- | --- | --- |
| `read <材料...>` | 代码 | 读材料、切句、认叙述块 | |
| `pick` | **用户** | 第一轮：勾材料来源（可全选；只有一份时自动跳过） | |
| `span <编号\|全部>` | **用户** | 第二轮：勾时间段（粒度按跨度自适应：多年按年、半年按季度） | |
| `style <1-4>` | **用户** | 第三轮：呈报给谁 → 白描 / 奇川风 / 歸藏风 / 让我定 | |
| `offer` | 模型 | 划分并给勾选清单 | `verdicts.json` + `parts.json` |
| `budget <编号\|all>` | **用户** | 勾哪几个部分 | |
| `capacity` | 代码 | 按真实骨架算形态与容量 | `skeleton.json` |
| `title '…'` | 模型 | 图名（容量内） | |
| `render <出图.svg>` | 代码 | 校验 → 出图 → 顺带写溯源索引 | `items.json` |
+ 表里没有 `mark`（第五轮：深红标在哪一处，0 = 不标）—— 它在抽取完事项之后、出图之前问，
+ 且只有奇川风才问，所以不在主序里。`python scripts/pipeline.py steps` 会一并打印它。
+
第三轮的三档对应三种风格：**法官**（开庭、提交法院）→ 白描；**当事人与客户**（当面讲、
微信发）→ 奇川风；**同行、讲课、公众号** → 歸藏风。
## 扫描件与照片：读图三步
律师给的材料几乎总有扫描件与照片，对方提交的那部分尤其如此。**不读图就永远只看得见
一方，而只看见一方的时间轴恰恰是最危险的产物** —— 它看起来完整，实际是单方陈述。
python scripts/read_image.py probe 材料.pdf # ① 逐页量可读字符
python scripts/read_image.py rasterize 材料.pdf pages/ # ② 150 DPI 栅格化
# ③ 你逐页看图，写转写稿
python scripts/read_image.py check 转写账目.json # ④ 页数账 + 编号缺号
用的全是 poppler 自带命令，**不装模型、不调 API**。判据是「逐页可读字符数」，
不是「`pdffonts` 有没有字体」（真材料上有反例）。
转写稿要**存档**（Markdown，每页一节、标页码、写明「这是转写不是原件」），并**作为材料**
进管线 —— 这样全套忠实判据原封不动生效。图像来源的事项标 `medium: "image"`、
`locator` 用「第 N 页」、`image_docs.json` 列出读了图的材料，出图时会打印
「这些事项未经逐字核验」。细节见 `references/front-end.md` 与 ADR 0001、0002。
## 交付什么
一次出五种可编辑格式加一份溯源索引：
| 格式 | 给谁用 |
| --- | --- |
| SVG | 主交付物，插进 Word、再编辑 |
| PNG | 预览、归档、微信发 |
| PPTX | 讲课、庭前演示，每个对象可改 |
| VSDX | ProcessOn / Visio / WPS |
| drawio | draw.io 内继续改 |
| 溯源索引 docx | 图上每个元素出自材料何处（五列三线表） |
pptx 与 vsdx 是**读最终那张 SVG** 逐元素转出来的，所以「交付的就是那张图」。
## 集中红线
| 绝不 | 改为 |
| --- | --- |
| 手写 SVG 坐标 | 写 JSON，几何由脚本算 |
| 改写材料的字 | 只许删减，卡片每段必须是原句的**子序列** |
| 编造日期，或把「2020 年」判成 2020/1/1 | `certainty` 四档按材料精度填；`raw` 必须逐字可查 |
| 把**承诺或约定的时点**当事实（付款计划的付款日、合同交货期限） | 不进主轴；要画「到期未付」，材料里得另有记载 |
| 把**诉请、申请事项、法律评价**当事实 | 那是要什么，不是发生了什么 |
| 侧标签写法律定性（自认、违约、抗辩…） | 只写材料上写着的身份；说不准就不出侧标签 |
| 一方材料却分两侧，标「原告主张 / 被告主张」 | **只有一方叙述就是单侧** —— 一方转述对方的话有身份性 |
| 图上出现省略号、截断、缩字号 | 超容量在出图前**拒绝**并要求改短 |
| 为了好看等距画不等距的时间 | 那会宣称一个材料没有的精度；比例轴不成立就走编号型 |
| 自己拍视觉决定（颜色、字号、要不要标记） | 视觉决定归作者，问他 |
## 三种图种，由材料决定
| 图种 | 什么时候用 |
| --- | --- |
| 编号型 | 时点密、跨度不成比例、或无确切日期。轴上距离只表先后。**它永远画得出**，是阶梯的底 |
| 日期型 | 全部时点精确到日、且在轴上分得开。轴按等长单位格铺开，**距离本身在说话** |
| 期间型 | 争点是几段有长度的期间，且互相重叠或包含 —— 条身长度与重叠位置就是论点 |
**图种不由人选，由材料的性质按几何算出**，走不通就自动落到下一档（`render_figure.deliver`
永远给得出一张图）。事项多到横向排不下时自动转纵向并分页。
## 环境
Python 3，零第三方依赖（读 docx 时用 `python-docx`，出 PNG 与栅格化用 poppler /
LibreOffice，溯源索引用 node 的 docx 库）。全部脚本在 `scripts/`，全部守卫在
`tests/run_checks.py`（跑一次约半分钟，两百多条判据；确切条数看它自己，**不要在这里写死数字** —— 写死就会漂）。
+ **若这是 SkillHub 的分发包，`tests/` 不在其中** —— 回归套件需要若干二进制样本，那个平台不允许上传；要跑回归请取完整仓库：https://github.com/MiaoQichuan/new-litigation-visualization
改动之前跑一次 `python tests/run_checks.py`，改完再跑一次 —— **它红了就是你改坏了**。