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
+38 -11
View File
@@ -34,7 +34,7 @@ from __future__ import annotations
import json
import re
from collections.abc import Iterator, Sequence
from collections.abc import Iterator, Mapping, Sequence
from contextlib import contextmanager
from datetime import date, datetime
from decimal import Decimal
@@ -277,19 +277,37 @@ def paragraph_row(paragraph: ParagraphRead, *, preview: int = 80) -> dict:
}
def paragraph_text(paragraph: ParagraphRead, *, citations: bool = False) -> str:
def paragraph_text(
paragraph: ParagraphRead,
*,
citations: bool = False,
index_by_citation: Mapping[int, int] | None = None,
) -> str:
"""Print one paragraph exactly as the document renders it.
``separator_before`` is added, not invented: the server decided what
belongs at each seam, so a tool result and the paper view agree on where
the spaces go. Nothing here adds spacing of its own.
A marker's number comes from ``index_by_citation`` — the citation's *work*
number as the whole document assigned it, not its position in this sentence —
so what is printed in the text matches the 参考文献 list it points at. Read
without that map there is no document to number against, and the marker
falls back to the citation's place in the sentence.
"""
parts: list[str] = []
for sentence in paragraph.sentences:
parts.append(sentence.separator_before + sentence.content)
if citations and sentence.citations:
markers = ",".join(str(index) for index in range(1, len(sentence.citations) + 1))
parts.append(f"[{markers}]")
numbers = [
str(
index_by_citation.get(citation.id, position)
if index_by_citation is not None
else position
)
for position, citation in enumerate(sentence.citations, start=1)
]
parts.append(f"[{','.join(numbers)}]")
return "".join(parts)
@@ -306,22 +324,31 @@ def document_text(
three rules the paper view renders by, applied here so a single tool call
can hand a model the finished manuscript.
"""
# Citation id → the number of the work it cites, so the markers printed in
# the text are the numbers the list below uses.
index_by_citation = {row.id: row.index for row in document.citations}
lines: list[str] = []
for paragraph in document.paragraphs:
body = paragraph_text(paragraph, citations=citations)
body = paragraph_text(
paragraph, citations=citations, index_by_citation=index_by_citation
)
if not body and not include_empty:
continue
lines.append(paragraph.name if paragraph.matched and paragraph.name else "未设定")
lines.append(body)
lines.append("")
if citations and document.citations:
if citations and document.references:
# The entries, not the quotes: a 参考文献 list is a bibliography, and the
# one assembled above already carries each work once, numbered as the
# text numbers it. A work whose library row is missing prints the gap
# rather than a fabricated entry.
lines.append("参考文献")
for citation in document.citations:
reference = (
f"[{citation.reference_id}]" if citation.reference_id else ""
)
lines.append(f"[{citation.index}]{reference} {citation.quote}")
for entry in document.references:
text = entry.text or "(未关联文献库条目)"
note = f"(缺 {'、'.join(entry.missing)})" if entry.missing else ""
lines.append(f"[{entry.index}] {text}{note}")
lines.append("")
text = "\n".join(lines).rstrip("\n")