dsh-archive-check

dsh-archive-check — Archive filing register completeness and retention period check

English · 简体中文 · Español · Português · हिन्दी

dsh-archive-check reads one 归档登记表 (filing register) — the items with the columns the register carries, plus the fonds and the year it covers — and checks what a register can be held to mechanically: that each item carries the description fields you configure, that 档号 is unique within the register, that 件号 runs without gaps, that 保管期限 uses a term from your own schedule, that 形成日期 parses and matches the register's year, and that items past the transfer deadline you configure are surfaced.

Install

dsh plugin --profile <name> add dsh-archive-check
dsh --profile <name> --dump-config | grep 'dsh-archive-check'

What it looks like

*Workflow overview: document → rule pack → findings. The examples below use the real command surface.*

What it answers

Examples

The table below is the example set: the first row is the detailed walkthrough, the remaining rows are short cases.

Detailed output

Tool archive_check

Input

~~~json {"fonds":"某单位","year":2026,"items":[{"档号":"A-2026-001","题名":"","保管期限":"永久", ...}]} ~~~

Output

~~~json { "id": "dsh-archive-check.AR-001.de09b5a6", "ruleId": "AR-001", "severity": "info", "locator": { "row": 1 }, "found": "第 1 行缺少 题名", "expected": "按本机构配置，归档条目应著录 档号、题名、保管期限", "fix": "补齐著录项目；本条只核对字段是否存在，不判断著录内容是否准确" } ~~~

*Observed from dsh-archive-check/tests/fixtures/AR-001/AR-001-unsafe.json; dsh-archive-check/tests/fixtures/AR-001/cases.json; dsh-archive-check/rules/archive-check.yaml; dsh-archive-check/tests/index.test.ts*

You ask · What it answers I have configured no required description fields. Is the description check passing silently? · No. While requiredFields is empty, AR-001 reports itself in skipped, so an empty difference list is not read as “nothing is missing”. Once you list your own column names, it checks only that each field is filled on every item — an empty string counts as unfilled — and it does not judge whether the description is accurate. Two items carry the same 档号, but one of them has a space in the middle. Is that still a duplicate? · Yes. AR-002 compares 档号 ignoring whitespace, so 「A-2026-001」 and 「A-2026- 001」 count as the same number. It is capped at warn because the clause it cites states uniqueness as a compilation principle rather than as a verbatim ban on duplicates in one register, and a hit usually means duplicate registration or a mistyped 档号 that a person still has to confirm. The 保管期限 column says something our retention schedule does not list. What does the check report? · AR-003 keeps two cases apart: a value the parser cannot read as a retention term at all (it recognises 「永久」, 「长期」, 「定期N年」 and 「N年」), and a recognisable term that is not in the retentionTerms list you configure. The two need different corrections, so they are reported as different messages. The rule never decides which retention period a document deserves, and a period longer than the national framework is not an error — the provisions the pack cites make the enterprise figures a minimum. The 件号 run 1, 2, 4 — is the missing 3 reported? · Yes, but only for 件号 written as pure digits: AR-004 checks continuity only for those; a 件号 containing letters or spaces is left out of the comparison and reports no difference at all. A gap is not by itself a defect — the number may simply be unused — so a hit only asks you to confirm whether an item went unregistered. With checkSequence: false the rule does not run. The 形成日期 is written 「二〇二六年三月十五日」. Will that be read? · No. AR-005 reports it as “cannot parse”, which is a different message from a date whose year disagrees with the register's year — the two point at different corrections. Filing across year boundaries is allowed, and the rule does not decide which year a document should be filed under. How does the check know that a transfer is due? · AR-007 compares each item's 形成日期 with the transferAfterYears you configure and reports only whether that deadline has already passed under the years you set. The parameter ships as 0, meaning unconfigured, so the rule reports itself in skipped until you set it; with requireFormedAt: true, items that have no 形成日期 are reported separately, because no due date can be worked out from a missing date. The rule does not judge whether a transfer should be brought forward or postponed.

Standards it follows

Document · Number · Cited by rules 《归档文件整理规则》 · DA/T 22—2015 · AR-001, AR-002, AR-004, AR-005, AR-006 《中华人民共和国档案法实施条例》 · 国务院令第772号 · AR-001, AR-003, AR-007 《机关文件材料归档范围和文书档案保管期限规定》 · 国家档案局令第8号 · AR-003 《企业文件材料归档范围和档案保管期限规定》 · 国家档案局令第10号 · AR-003 《中华人民共和国档案法》 · 2020年修订（主席令第四十七号） · AR-007

Boundary: this plugin checks one 归档登记表 (filing register) for the things a register can be held to mechanically — that each item is described completely enough to be filed and found again, that 档号 is unique, that 件号 runs without gaps, that retention terms come from your schedule, and that 形成日期 parses and matches the register's year. It does not decide whether a particular document belonged in the archive, nor which retention period it deserves. Those are the archivist's judgements.

### ⚠️ Three things this plugin refuses to do, and why

1. It never decides which retention period a document deserves. There is **no single national

retention table** you can apply. 《档案法实施条例》第十九条第二款 and 国家档案局令第8号第十二条 require each

institution to compile its own 归档范围 and 保管期限表 and have it approved by the档案 authority; and

国家档案局令第10号第十一条 says the enterprise figures are a minimum — an enterprise may lawfully

choose a *longer* period. So AR-003 checks only that the wording is one you have configured, and a

test asserts that the pack says a longer period "is not an error".

2. It puts the transfer years where they belong. The 20-year / 10-year figures are in

《档案法实施条例》第二十条第二款, keyed to the *receiving archive's level*, not to whether the unit

is an enterprise. 《档案法》第十五条 contains no year figure at all — it says only "按照国家有关规定，

定期". Attributing "满20年" to the law's article 15 would be fabrication, and a test asserts the pack

does not.

3. It does not use the outdated first article. 国家档案局令第8号's 第一条 cites the 1999

《档案法实施办法》, which the 2024 条例 (国务院令第772号) repealed in its 第五十二条. The pack never cites it,

and a test asserts that.

Two lists are yours, not the law's: the required description fields (AR-001) and your retention

vocabulary (AR-003). Both ship empty, and a rule whose list is unset reports itself in skipped

rather than passing silently.

Compatibility

Surface · Status Harness · Peer range >=0.1.2-rc.1 =0.2.0-0 =0.2.1-0 =24.0.0 Platforms · All (plain ESM; no native code, no network, no model call) Tool mode · Works in native and ptc; for a year's registers use ptc

What it does

Registers the archive_check tool. It reads one register — items with the columns the register carries, plus the fonds and year it covers — applies a versioned rule pack, and returns a report.

Rule · Check · Severity · Basis kind AR-001 · each item carries your required description fields (off by default) · info · local AR-002 · 档号 is unique within the register · warn · principle AR-003 · 保管期限 uses a term from your schedule (off by default) · info · local AR-004 · 件号 is unique and gap-free within the register · warn · principle AR-005 · 形成日期 parses, and its year matches the register's year · warn · principle AR-006 · the register declares its fonds and year · warn · principle AR-007 · items past your configured transfer deadline (off by default) · info · local

Configuration

Key · Type · Default · Description rulesFile · string · rules/archive-check.yaml · Rule-pack path, relative to the package root disabledRules · string[] · [] · Rule ids to stop running; each appears in skipped onlyRules · string[] · [] · Run only these rule ids; empty runs every rule skipNotes · string · "" · Note appended to every skipped reason timeoutMs · number · 120000 · Cooperative tool timeout budget

Rule-level parameters worth knowing:

• AR-001 requiredFields — the columns a row must fill, e.g. [档号, 题名, 保管期限, 责任者].

Empty means the rule does not run. A blank cell counts as unfilled.

• AR-003 retentionTerms — the terms your 保管期限表 uses, e.g.

[永久, 定期30年, 定期10年]. It can also be passed per call for a one-off comparison.

• AR-004 checkSequence — set to false to stop checking 件号 continuity.
• AR-006 requireHeader — set to false if your register legitimately carries no fonds or year.
• AR-007 transferAfterYears — your archive's transfer deadline: 20 for a central / provincial /

sub-provincial receiving archive, 10 for a county-level one (《档案法实施条例》第二十条第二款). 0 means the rule does not run. AR-007 requireFormedAt makes a missing 形成日期 column a finding rather than a skip, because the deadline cannot be computed without it.

Material format

The tool accepts JSON or YAML:

fonds: 某单位
year: 2026
items:
  - { 档号: A-2026-001, 题名: 关于第一项工作的通知, 保管期限: 永久,   形成日期: 2026-03-15, 件号: "1" }
  - { 档号: A-2026-002, 题名: 关于第二项工作的通知, 保管期限: 定期30年, 形成日期: 2026-04-01, 件号: "2" }

Column names are recognised from 档号/档案号, 题名/文件题名/标题, 保管期限/期限, 形成日期/成文日期/日期, and 件号/序号. A plain list of titles also works — each string becomes an item's 题名. Numbers are accepted as strings, so a spreadsheet export needs no cleaning.

保管期限 is read in two shapes: 永久/长期 for permanent, and any N年/定期N年/bare N for a fixed term. A term it cannot read is reported as unreadable, which is different from a term outside your configured list — the two produce different findings, because they need different fixes.

Rule sources

Rule data lives in rules/archive-check.yaml. Every rule carries a document, a document number, a clause in the source's own numbering, a verbatim excerpt and the URL the excerpt was read from. The loader enforces that an excerpt is a real quotation of at least eight characters, and that a check resting on a general principle or a local policy can never be declared error.

The clauses quoted come from:

• 《中华人民共和国档案法》 (2020-06-20 revision, 主席令第四十七号, in force 2021-01-01) — articles 13–15, 21, 37, 39
• 《中华人民共和国档案法实施条例》 (国务院令第772号, published 2024-01-12, in force 2024-03-01;

its 第五十二条 repeals the 1999 《档案法实施办法》) — articles 19, 20, 24, 39, 40

• 《机关文件材料归档范围和文书档案保管期限规定》 (国家档案局令第8号) — articles 3, 4, 6, 12, 14
• 《企业文件材料归档范围和档案保管期限规定》 (国家档案局令第10号) — articles 7, 11, 15, 16
• 《归档文件整理规则》 (DA/T 22—2015) — 5.2.2, 5.3.1, 5.4.1, 5.4.3 e), 5.5.2

Three corrections shaped this pack and are recorded in its header:

1. The regulation was replaced. 国务院令第772号 is in force from 2024-03-01 and repeals the 1999

implementation measures, so 令第8号's 第一条 (which cites the repealed text) is never quoted.

1. The transfer years live in the regulation, not the law. 第二十条第二款 carries the 20/10 year

figures and keys them to the receiving archive's level; 《档案法》第十五条 has no year at all.

1. No universal retention table exists. Each institution compiles and has its own approved, and an

enterprise's figures are a statutory minimum rather than a ceiling.

The full clause-verification report, including the sources that were checked and rejected, is in rules/evidence/clause-verification.md.

Troubleshooting

• `AR-001` and `AR-003` report themselves as skipped. Their lists are empty. AR-003 can also be fed

per call, so a one-off comparison needs no rule-pack edit.

• `AR-004` reports nothing. Fewer than two 件号 values parsed as plain integers — alphanumeric

references are deliberately left out of the continuity check rather than guessed at.

• `AR-005` fires on a date I can read. The reader accepts 2026-03-15 and 2026-03-15 09:30; a

Chinese-numeral date like 二〇二六年三月十五日 is reported as unparseable on purpose, so you can decide whether to normalise the export.

• The reader refuses a register it used to accept. It found none of the known archive columns; the