backend: print the 参考文献 list as a bibliography, one entry per work

The list was printing each citation's quote under a `引用 #53` tag: no authors,
no year, no pages, no DOI — the quoted passage where the entry should be — and
it numbered *citations*, so a paper with 86 citations to 65 works listed 21 of
them two or three times under different numbers. The same article was `[5]` in
one paragraph and `[17]` in another.

Two rules were wrong, so two are stated here:

**A work is numbered where the reader first meets it.** A citation is a place
in the text; an entry is a work. `citations` still has one row per place, and
each row now carries the number of its *work*, so the marker in the text, the
tooltip on it and the entry in the list are the same number. The document grew
a `references` list — the entries, in order — and `reference_style`, which
names the style that wrote them.

**How a reference prints is a property of a style, not of a citation.** The new
`app/citation_styles` package holds one module per style; `springer.py`
implements Springer's basic style, whose shape is
`Names: Title. <where it sits> (year). <identifier>` with a branch per document
type — a journal with its volume(issue) and pages, a book with publisher and
place, a chapter inside somebody else's book, a patent with its number, a page
whose URL is its source.

Three of its rules are decisions rather than transcription, and each is
documented where it applies: up to six contributors are named and more become
three plus `et al.`; a journal prints under its 刊名缩写 when the writer stored
one, because no algorithm abbreviates an arbitrary title correctly; and a CJK
name keeps its printed form even with halves filled in, because dotting 「三」
into an initial is wrong in Chinese and insufficient in English.

Nothing is invented to fill a gap. An entry says what it knows and reports the
rest as `missing` (「缺 责任者、出版年」), and the document warns about the
incomplete ones by number: an entry that is short because fields are empty
looks like a fact about the document rather than a library that needs attention.

`document_text` had the same bug in the MCP surface and now prints the entries,
with in-text markers taken from the document's numbering rather than from each
sentence's local position — which is what made the text an agent reads disagree
with the list under it.

`scripts/check_citation_styles.py` checks the formatter with no server and no
database: one reference of every type, and the exact entry the style calls for.
This commit is contained in:
2026-09-22 21:50:27 +08:00
parent 15955f552d
commit 76708ce767
8 changed files with 1305 additions and 46 deletions
+45 -7
View File
@@ -8,8 +8,8 @@ Three shapes of payload live here:
reading every sentence of it and writing the whole set back, so the update
schema is a full replacement;
* the **document** — what the reader sees: the template's paragraphs in order,
each carrying the sentences stored at its position, plus the flat citation
list for the 参考文献 block.
each carrying the sentences stored at its position, plus the 参考文献 list,
already formatted in one citation style.
Text normalisation is deliberately strict, because the two sides of the wire
have to agree on what counts as empty:
@@ -27,6 +27,8 @@ from typing import Literal
from pydantic import BaseModel, ConfigDict, Field, field_validator
from app.citation_styles import DEFAULT_STYLE as DEFAULT_REFERENCE_STYLE
#: Writing states, mirroring :data:`app.models.paper.PAPER_STATUSES`. Kept as a
#: literal so the generated OpenAPI document describes the enum for clients.
PaperStatus = Literal["draft", "writing", "done"]
@@ -200,11 +202,13 @@ class ParagraphRead(BaseModel):
class PaperCitationRead(BaseModel):
"""One citation as it appears in the paper's 参考文献 list.
"""One citation — one place in the text where one work is cited.
``index`` is the number shown in the text as ``[index]``; it counts
citations in reading order across the whole document, so the list and the
markers cannot disagree.
A citation is not a row of the 参考文献 list, and this is the difference that
matters: a paper that cites the same article in three sentences has three
citations and **one** entry, so ``index`` is the number of the *work* and is
shared by all three. The in-text markers and the list therefore cannot
disagree about what ``[7]`` means.
"""
index: int
@@ -217,6 +221,30 @@ class PaperCitationRead(BaseModel):
paragraph_name: str | None = None
class PaperReferenceRead(BaseModel):
"""One entry of the 参考文献 list: one work, however often it is cited.
``text`` is the entry as it prints — the whole point of the list — and it is
assembled by :mod:`app.citation_styles` rather than by a client, so the paper
view, an export and an agent all print the same bibliography.
"""
#: The number the text shows as ``[index]``, assigned in order of first
#: appearance so the list reads in the order the reader meets the works.
index: int
#: The library row it came from, or ``None`` for a citation written before
#: the literature was entered.
reference_id: int | None
#: The formatted entry, or ``""`` when there is no library row to print.
text: str
#: Which parts a complete entry still lacks, in Chinese — 责任者、出版年、DOI…
#: Empty for a complete entry, and empty for an unlinked one, where the
#: question is not what is missing but what this is.
missing: list[str] = Field(default_factory=list)
#: Every place it is cited, in reading order.
citations: list[PaperCitationRead] = Field(default_factory=list)
class PaperBase(BaseModel):
"""Shared body of the paper create payload."""
@@ -342,8 +370,18 @@ class PaperDocumentRead(BaseModel):
#: template or a sentence mentions appears exactly once, so an empty
#: paragraph is still a paragraph — the structure survives with no content.
paragraphs: list[ParagraphRead]
#: Citations in reading order, numbered to match the in-text markers.
#: Citations in reading order, each carrying the number of the work it cites.
#: One row per place in the text, not per work: this is what renders the
#: in-text markers.
citations: list[PaperCitationRead]
#: The 参考文献 list: one entry per work, numbered in order of first
#: appearance, already formatted. A client prints these and does not group,
#: sort or assemble them — two implementations of the same rules would
#: eventually print two different bibliographies.
references: list[PaperReferenceRead] = Field(default_factory=list)
#: The citation style the entries were written in, so a client can name it
#: without hard-coding the choice (see ``app.citation_styles``).
reference_style: str = DEFAULT_REFERENCE_STYLE
#: Anything the reader should be told about the document as a whole, e.g.
#: a template that places two fields at the same position.
warnings: list[str] = Field(default_factory=list)