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:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user