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
+87
View File
@@ -0,0 +1,87 @@
"""Citation styles: a stored reference written out as a bibliography entry.
A reference is stored as fields — 题名, 刊名, 卷, 期, 页码, DOI, 责任者 — and a
*paper* prints those fields in the order and with the punctuation one particular
style asks for. The two are deliberately separate: the library holds the facts
once, and a style decides how to write them down, so adding a style adds a module
rather than a column.
The module is one style per file, registered in :data:`STYLES`, and this package
is the only thing the rest of the application imports:
.. code-block:: python
from app.citation_styles import DEFAULT_STYLE, format_reference
text = format_reference(reference) # the default style
gaps = missing_fields(reference) # 「缺 责任者、出版年」
``DEFAULT_STYLE`` is what a document is assembled with, and the document reports
it back as ``reference_style`` so a client can name the format it is showing
without hard-coding the choice.
"""
from typing import Protocol
from app.citation_styles import springer
from app.models import Reference
class Style(Protocol):
"""What a style module provides.
Structural rather than a base class: a style is a module of two functions,
and inheriting from something would only add an import to every one of them.
"""
def format_reference(self, reference: Reference) -> str:
"""Write one reference out as a bibliography entry."""
def missing_fields(self, reference: Reference) -> list[str]:
"""Which parts a complete entry is missing, in Chinese."""
#: The styles this build can print, by the token a document reports.
STYLES: dict[str, Style] = {"springer": springer}
#: The style a document is assembled with when nothing says otherwise.
#:
#: Springer's basic style: bracketed numerals in the text, a numbered list at the
#: end, and entries of the shape ``Names: Title. <where> (year). <identifier>``.
DEFAULT_STYLE = "springer"
def _style(name: str):
"""Look a style up, or say which ones exist."""
try:
return STYLES[name]
except KeyError:
known = "、".join(sorted(STYLES))
raise ValueError(f"未知的参考文献格式:{name}(可用:{known})") from None
def format_reference(reference: Reference | None, style: str = DEFAULT_STYLE) -> str:
"""Write one reference out as a bibliography entry.
``None`` — a citation whose row the library no longer has — yields the empty
string rather than a fabricated entry: the caller decides how to say
"unlinked", and this module never guesses.
"""
if reference is None:
return ""
return _style(style).format_reference(reference)
def missing_fields(reference: Reference | None, style: str = DEFAULT_STYLE) -> list[str]:
"""Which parts a complete entry is missing, in the style's own terms."""
if reference is None:
return []
return _style(style).missing_fields(reference)
__all__ = [
"DEFAULT_STYLE",
"STYLES",
"format_reference",
"missing_fields",
]