# 法条整理

**Repository Path**: furrybluequilt/laws-learning

## Basic Information

- **Project Name**: 法条整理
- **Description**: 本项目面向准备专利代理师考试的同事和专利代理行业的入门新人。公司可以利用本项目为员工生成知识库或 wiki，学员个人可以利用本项目生成 Anki 记忆卡片。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: patent, 专利, 法条

## README

# 法条整理

把从网页复制的法律条文，一键整理成结构化的知识库与记忆卡片。

本文档面向技术人员与开发者。如果你只是使用本工具整理法条或制作 Anki 卡片，请直接阅读 `USER_GUIDE.md`（操作手册）。

主要面向准备专利代理师考试的新人：公司可用它为员工批量生成知识库或 wiki，学员个人可用它制作 Anki 记忆卡片。

工作方式很直接：把网页上复制的条文存成 txt，工具先把它解析成规范化的 JSON，再由 JSON 生成 dokuwiki、markdown、asciidoc、Anki 与题库卡片等成品。

项目使用 [uv](https://docs.astral.sh/uv/) 管理，运行命令以 `uv run` 开头。

## 快速开始

三步即可完成第一次入库：

1. 把网页上复制的法条全文存成 txt，放进 `source/` 下（如 `source/laws/专利法.txt`）。文件的基本要求见下方[《新增或更新法条》](#新增或更新法条)。
2. 在项目根目录运行 `uv run python -m app`。
3. 到 `output/` 下查看生成的四种成品。

环境要求：Python ≥ 3.11，并已安装 [uv](https://docs.astral.sh/uv/)。

## 命令一览

所有命令都在项目根目录执行。

### 默认流程

不带子命令时，工具会先执行 `ingest` 再执行 `build`，一次完成法条入库与构建：

```
uv run python -m app
```

### 法条相关

`ingest` 把 `source/` 下的 txt 解析成 `data/` 下的规范化 JSON；`build` 把 JSON 渲染成指定法条输出格式。

```
uv run python -m app ingest                         # 仅 txt → JSON
uv run python -m app ingest --fmt                   # 同时把规范化 txt 写回 source/
uv run python -m app build                          # 仅 JSON → 默认法条输出格式
uv run python -m app build --targets anki,markdown,asciidoc  # 只构建指定法条格式
```

### 题库相关

题库命令管理 `questions/` 下的填空题与选择题，与法条构建相互独立。

初始化题库数据库：

```
uv run python -m app question init
```

从 JSON / TOML / YAML 导入题库。`import` 默认递归读取目录，可用 `--no-recursive` 关闭：

```
uv run python -m app question import ./questions/
uv run python -m app question import --no-recursive ./questions/
uv run python -m app question import ./questions/blanks.json ./questions/questions-*.json
```

把 Excel 题库转换为同名 YAML，默认递归。转换 Excel 前请先手动安装 `openpyxl`（`uv sync` 不会默认安装），运行 `uv sync --extra excel`：

```
uv run python -m app question convert ./questions/
uv run python -m app question convert --no-recursive ./questions/
```

同步 Excel 与 YAML 题库：Excel 更新时自动转换，随后导入全部 YAML。相当于 `convert + import`，默认递归：

```
uv run python -m app question sync ./questions/
uv run python -m app question sync --no-recursive ./questions/
```

构建题库输出到 `output/question/`。`question build` 总是先自动 sync，默认只生成 cloze：

```
uv run python -m app question build
uv run python -m app question build --targets cloze,choice
```

`uv run python -m app` 不含题库构建，题库需单独执行 `question build`。题库产物在 `output/question/` 下。

## 目录约定

| 目录 | 作用 |
| --- | --- |
| `source/` | 从网页复制的 txt 原文，仅供导入 |
| `data/` | 规范化 JSON，当前是 `ingest` 的派生缓存（不提交）；未来可切换为唯一原始数据 |
| `output/` | 构建产物，可随时重建。法条输出（`output/anki/` 等）由 `build` 产出；题库输出（`output/question/`）由 `question build` 产出（详见 [output-formats](docs/output-formats.md)） |
| `backups/` | 自动备份的旧 data / source，每类保留最近若干份 |
| `questions/` | 填空题题库（SQLite + 可导入的 JSON），与 `source/` 原文分离 |

`source/` 下可以按类别建任意层级的子目录（如 `source/laws/`），扫描是递归的。这套目录结构会在 `data/` 与 `output/` 中原样镜像，Anki 的牌组与层级标签也取自这些分类子目录（第一层目录作牌组，第二层及以下作标签前缀）。想了解完整的数据流与代码分层，请看 [architecture](docs/architecture.md)。

## 新增或更新法条

准备 txt 时，只需满足三条：

- **第一行**：标题，如「中华人民共和国专利法」；
- **第二行**（其间的空行会被忽略）：修订或施行说明，如「（2020年第4次修正）」；
- **其后**：正文。

行首行尾空白、空行、BOM 都会被自动清理，无需手工整理。存好文件后运行 `uv run python -m app` 即完成入库。

更新已有法条时，务必沿用原来的文件名和目录——文件名就是该法的唯一 ID，改名会导致它被当作一部新法。

进阶用法：`uv run python -m app ingest --fmt` 可在入库的同时，把规范化后的「干净」原文写回 `source/`。

## 备份与恢复

这是一道防误操作的安全网，平时无需关心。每次 `ingest`（含 `uv run python -m app`）会先把旧 `data/` 打包成 `backups/data-时间戳.tar.gz`；使用 `ingest --fmt` 时，旧 `source/` 同理备份为 `backups/source-时间戳.tar.gz`。每类前缀只保留最近 `MAX_BACKUPS` 份（默认 10），更旧的自动清理。

需要恢复时，解压对应的压缩包覆盖回去即可：

```
# Linux / macOS
tar -xzf backups/data-yyyymmdd-HHMMSS.tar.gz && rm backups/data-yyyymmdd-HHMMSS.tar.gz
```

```
# Windows（需安装 7-Zip）
7z x backups\data-yyyymmdd-HHMMSS.tar.gz -so | 7z x -si -ttar -odata && del backups\data-yyyymmdd-HHMMSS.tar.gz
```

`MAX_BACKUPS` 与 `BACKUP_DIR` 均可在 `app/config.py` 中调整。

## 把更新同步到 Anki

法条修订后重新构建，再把 `output/anki/` 下对应牌组文件重新导入 Anki（文件 → 导入，以 GUID 匹配字段，选择「更新已有笔记」）。由于每张卡片的 GUID 稳定不变，已有卡片会原地更新内容，复习进度不会丢失。

## 题库：填空题与选择题

题库独立于 `source/` 原文，存放在 `questions/` 目录。在 JSON / TOML / YAML / Excel 中用 `[[答案]]` 或 `{{答案}}` 标出要挖空的原文片段，程序构建时自动匹配到 `data/` 中的对应条文并生成 Anki Cloze 卡片。题型不存库、不手写，由空位数与干扰项的有无在构建时推断；选择题接口已预留。完整格式、字段说明、Excel 用法与架构设计见 [question-architecture](docs/question-architecture.md)，手写题库见 [question-writing-guide](docs/question-writing-guide.md)。

```
uv run python -m app question sync ./questions/  # 同步 Excel / YAML 并导入题库
uv run python -m app question build              # 生成 Anki Cloze（构建前自动 sync）
```

`sync` 会把更新的 Excel 转成同名 `.yaml` 再导入，无需手动 convert。`question build` 总是先自动 sync，产物在 `output/question/cloze/` 下，按第一层分类目录合并为牌组文件（如 `output/question/cloze/专利.txt`），可直接导入 Anki。导入前请确保 Anki 中存在 Cloze 笔记类型，并额外添加一个「顺序」字段设为排序字段。

## 进一步阅读

更详细的说明在 `docs/` 目录：

| 文档 | 讲什么 | 适合谁 |
| --- | --- | --- |
| [architecture](docs/architecture.md) | 数据流、source 与 data 谁是原始数据、设计要点 | 想改代码或理解全局的人 |
| [question-architecture](docs/question-architecture.md) | 题库系统设计要点：题型推断、法条更新与稳定性、tags 关系 | 想扩展题库或新增考试系统导出的人 |
| [question-writing-guide](docs/question-writing-guide.md) | 四种题库文件的字段说明、挖空与干扰项写法、完整示例 | 手写题库文件的人 |
| [data-spec](docs/data-spec.md) | `data/**/*.json` 的确切结构、重要度标记、GUID 与版本演进 | 手工修订 JSON 或改动数据结构的人 |
| [output-formats](docs/output-formats.md) | 各成品的人类使用要点（具体排版规则见 renderer 源码与实际产物） | 使用 Anki / 导出文件、想了解该看哪里的人 |