Compare commits

...

4 Commits

Author SHA1 Message Date
govin b97aab6f30 docs: describe the citation styles and the per-work numbering
Records the decisions the 参考文献 list now rests on: a citation is a place in
the text and an entry is a work, so a paper with 86 citations to 65 works lists
65 entries; the entries are written by `app/citation_styles` and a client prints
them verbatim; a gap is reported through `missing` rather than quietly rendered
as a shorter entry.

Also documents `scripts/check_citation_styles.py` — the formatter is checked
with no server and no database, because a wrong branch prints something that
looks like a bibliography entry instead of failing loudly — and why the
reference smoke test now stamps a token into everything it creates.
2026-09-22 21:50:39 +08:00
govin 340e0777ce frontend: print the 参考文献 block as entries, not quotes
The card listed the quoted passage where the bibliography entry belongs, under
a `引用 #53` tag that named a database id rather than the work. It now prints
the server's `references` verbatim — one line per work, already formatted in
Springer's basic style — with the fields a complete entry still lacks shown as
「缺 责任者、出版年」, and the paragraphs that cite it underneath:

    1 引言 / Introduction
    2.1 技术主题识别 / Technology Topic Identification ×2

Each of those links carries the quoted passages for that paragraph in its
tooltip, which is where the quote belongs: it is evidence for a citation, not
the citation itself. The client formats nothing and groups nothing but the
paragraph labels — a second implementation of "which work is number 7" would
eventually disagree with the first.

The marker tooltip in the text stops saying `引用 #53` too and shows the entry
it points at, so hovering a `[7]` answers the question the number raises.
2026-09-22 21:50:39 +08:00
govin 54292eb231 backend: let the reference smoke test survive a populated library
It asserted that a search for "Wang" found one row and that the library was
empty when it finished — both true only of an empty database. The library it
runs against now holds 65 real references and 10 labels, so the run failed on
its own baseline rather than on anything it was testing.

Every row the run creates now carries a per-run token in its title, in one
contributor's name and in its label names, and each count is asserted against a
search for that token. A second, distinct token rides on the author name alone,
because searching for the first one finds every row the run made and "the
search matches an author" needs a string that is in exactly one place.

What the test means does not change: "the search found one row" is a statement
about this run, and the token is what makes it one.
2026-09-22 21:50:33 +08:00
govin 76708ce767 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.
2026-09-22 21:50:27 +08:00
14 changed files with 1721 additions and 122 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",
]
+564
View File
@@ -0,0 +1,564 @@
"""Springer basic style: one stored reference, written out as a bibliography entry.
Springer's **basic** style is the numbered one — bracketed numerals in the text
and a numbered list at the end — which is the shape this project already has.
What it adds is the layout of the entry itself, taken from Springer's own
examples:
.. code-block:: text
Van der Geer, J., Hanraads, J.A.J., Lupton, R.A.: The art of writing a
scientific article. J. Sci. Commun. 163(2), 51–59 (2010).
https://doi.org/10.1016/j.Sc.2010.00372
Strunk Jr., W., White, E.B.: The Elements of Style, 4th edn. Longman,
New York (2000)
Mettam, G.R., Adams, L.B.: How to prepare an electronic version of your
article. In: Jones, B.S., Smith, R.Z. (eds.) Introduction to the Electronic
Age, pp. 281–304. E-Publishing Inc., New York (2009)
So an entry is ``Names: Title. <where the entry sits> (year). <identifier>``,
and *where it sits* is the only part that changes with the document type: a
journal with its volume and pages, a book with its publisher, a chapter inside
somebody else's book, a patent with its number.
Three rules here are decisions rather than transcription, and each is stated
where it is applied:
* **Up to six contributors are named; more become the first three and
``et al.``** — Springer's rule for this style.
* **A journal prints under its 刊名缩写 when the writer stored one**, because
Springer abbreviates journal titles and no algorithm abbreviates an arbitrary
title correctly: the library has a column for the abbreviation precisely so a
human decides it. Without one, the full 刊名 is printed rather than an
invention.
* **A CJK name is printed as stored**, halves or no halves: dotting 「三」 into
an initial is wrong in Chinese and insufficient in English (see
:func:`_name`).
* **Nothing is invented to fill a gap.** A missing year prints no parentheses, a
missing publisher no publisher; the field simply does not appear. What a
complete entry would need is reported separately by :func:`missing_fields`, so
the writer is told what is absent instead of being shown a plausible-looking
fabrication.
"""
from __future__ import annotations
import re
from datetime import date
from typing import Callable
from app.models import Reference, ReferenceAuthor
#: How many contributors are named before the list is cut short, and how many
#: survive the cut. Springer's basic style names up to six, then the first three
#: followed by ``et al.``
_AUTHOR_LIMIT = 6
_AUTHOR_KEEP = 3
#: ``122-141`` → ``122–141``. Springer prints ranges with an en dash, and the
#: stored value is whatever the writer pasted — often a plain hyphen.
_PAGE_RANGE = re.compile(r"(\d+)\s*[-–—]\s*(\d+)")
#: CJK ideographs and kana. A name containing one is printed as stored rather
#: than inverted and initialised; see :func:`_name`.
_CJK = re.compile(r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]")
_MONTHS = (
"January",
"February",
"March",
"April",
"May",
"June",
"July",
"August",
"September",
"October",
"November",
"December",
)
#: For a web page the URL *is* the source, so it is printed where a journal
#: would be rather than at the end as an identifier. Every other type keeps the
#: URL for the trailing ``https://doi.org/…`` slot.
_URL_IS_THE_SOURCE = frozenset({"web-page"})
def format_reference(reference: Reference) -> str:
"""Write one reference out as a Springer bibliography entry.
The clauses are assembled and joined by ``". "``, which is the style's own
punctuation: the colon after the names, the period between the title and
where the entry sits, and the period before the DOI all fall out of it.
"""
clauses = [
clause
for clause in (
_head(reference),
*_where(reference),
_identifier(reference),
_accessed(reference),
)
if clause
]
# A clause that is nothing but a year is not a sentence, so it attaches to
# what precedes it rather than following a full stop. This is the shape a
# reference with a title and a year and nothing else takes: "…: Six (2021)",
# not "…: Six. (2021)". Doing it here rather than in each of the fourteen
# builders is one rule instead of fourteen chances to forget it.
parts: list[str] = []
for clause in clauses:
if parts and clause.startswith("(") and clause.endswith(")"):
parts[-1] = f"{parts[-1]} {clause}"
else:
parts.append(clause)
return ". ".join(parts)
# --- the two halves every entry has ------------------------------------------
def _head(reference: Reference) -> str:
"""``Names: Title`` — what the entry is, and who wrote it."""
names = _head_names(reference)
title = _title(reference)
return f"{names}: {title}" if names else title
def _title(reference: Reference) -> str:
"""The title, with its subtitle after a colon.
The library stores 副题名 as its own column because a citation style is
allowed to drop it; this one prints it, so the two are joined back into the
title the reader saw.
"""
title = _clean(reference.title)
subtitle = _clean(reference.subtitle)
if subtitle and not title.endswith((":", ":")):
title = f"{title}: {subtitle}"
elif subtitle:
title = f"{title} {subtitle}"
# For a whole book the edition belongs to the title ("The Elements of
# Style, 4th edn"); for a chapter it belongs to the book it sits in, which
# is where :func:`_where_chapter` puts it.
if reference.type == "book" and _clean(reference.edition):
title = f"{title}, {_clean(reference.edition)}"
return title
def _head_names(reference: Reference) -> str:
"""The contributors that lead the entry.
Authors first. A book whose contributors are all marked 编者 is written by
its editors — ``Jones, B.S. (ed.)`` — and a 汇编 / 译者 with no author at all
still has to appear somewhere, so the last resort is the stored list in
print order.
"""
authors = [author for author in reference.authors if author.role == "author"]
if authors:
return _name_list(authors)
editors = [author for author in reference.authors if author.role == "editor"]
if editors:
return _name_list(editors) + (" (ed.)" if len(editors) == 1 else " (eds.)")
return _name_list(list(reference.authors))
def _editor_names(reference: Reference) -> str:
"""The 编者 of a chapter's containing book, marked ``(ed.)`` / ``(eds.)``.
The library keeps one contributor list per entry, so these are the
contributors the writer marked 编者. When there are none the container is
printed without a mark rather than guessing whose book it is.
"""
editors = [author for author in reference.authors if author.role == "editor"]
if not editors:
return ""
mark = " (ed.)" if len(editors) == 1 else " (eds.)"
return _name_list(editors) + mark
def _name_list(people: list[ReferenceAuthor]) -> str:
"""The contributor list, cut to Springer's limit."""
names = [_name(person) for person in people if person.name.strip()]
if len(names) > _AUTHOR_LIMIT:
return ", ".join(names[:_AUTHOR_KEEP]) + ", et al."
return ", ".join(names)
def _name(person: ReferenceAuthor) -> str:
"""One contributor as ``Family, I.N.``
The halves are the authority for rewriting a name and the whole ``name`` is
the authority for printing it, as the model says. So a row with Latin halves
is inverted and initialised — some of them arrive already abbreviated
(``Lai KK`` → ``Lai, K.K.``) — while a row without them is printed exactly as
stored, which is the only correct thing to do for an institutional author
(「世界卫生组织」, "World Health Organization") and for a CJK name whose
romanisation the library was never told.
A CJK name keeps its printed form even *with* halves filled in. ``张`` +
``三`` inverted and dotted gives 「张, 三.」, which is neither Chinese nor
English: an initial is a Latin-script idea, and 「三」 is not the initial of
a given name, it is the whole of it. Springer's own ``Zhang, S.`` needs a
romanisation this library does not hold, so the stored 「张三」 is printed
rather than turned into something that is wrong in both languages.
"""
family = _clean(person.family_name)
given = _clean(person.given_name)
if not family or _CJK.search(family) or _CJK.search(given):
return _clean(person.name)
initials = _initials(given)
return f"{family}, {initials}" if initials else family
def _initials(given: str) -> str:
"""``Yong Ming`` → ``Y.M.``, ``AL`` → ``A.L.``, ``Jean-Luc`` → ``J.-L.``"""
if not given:
return ""
initials: list[str] = []
for token in given.split():
parts = [part for part in re.split(r"[-–]", token) if part]
if len(parts) > 1:
initials.append("-".join(_initial(part) for part in parts))
else:
initials.append(_initial(token))
return "".join(part for part in initials if part)
def _initial(token: str) -> str:
"""One given-name token as initials.
A token that is already a block of initials is expanded letter by letter —
``KK`` is two names, not one — and a token that is a name contributes its
first letter.
"""
letters = [character for character in token if character.isalpha()]
if not letters:
return ""
if len(letters) > 1 and token.isupper():
return "".join(f"{character.upper()}." for character in letters)
return f"{letters[0].upper()}."
# --- where the entry sits ----------------------------------------------------
def _where(reference: Reference) -> list[str]:
"""The clauses between the title and the identifier, by document type."""
builder: Callable[[Reference], list[str]] = _WHERE.get(
reference.type, _where_generic
)
return builder(reference)
def _where_journal(reference: Reference) -> list[str]:
"""``J. Sci. Commun. 163(2), 51–59 (2010)``"""
source = _join_space(_container(reference), _volume_issue(reference))
source = _join_comma(source, _pages(reference))
return [_with_year(source, reference)]
def _where_newspaper(reference: Reference) -> list[str]:
"""``The Times, p. 12 (2020)`` — a newspaper has a date, not a volume."""
source = _join_comma(_container(reference), _pages(reference))
return [_with_year(source, reference)]
def _where_book(reference: Reference) -> list[str]:
"""``Longman, New York (2000)``, with the series ahead of it."""
clauses = []
series = _join_comma(_clean(reference.series_title), _clean(reference.series_number))
if series:
clauses.append(series)
place = _join_comma(_clean(reference.publisher), _clean(reference.publisher_place))
clauses.append(_with_year(place, reference))
return [clause for clause in clauses if clause]
def _where_chapter(reference: Reference) -> list[str]:
"""``In: Jones, B.S. (ed.) Book title, pp. 281–304. E-Publishing Inc., New York (2009)``"""
inside = _container(reference)
if inside and _clean(reference.edition):
inside = f"{inside}, {_clean(reference.edition)}"
pages = _pages(reference)
if pages:
inside = _join_comma(inside, f"pp. {pages}")
editors = _editor_names(reference)
inside = _join_space(editors, inside) if editors else inside
opening = f"In: {inside}" if inside else ""
place = _with_year(
_join_comma(_clean(reference.publisher), _clean(reference.publisher_place)),
reference,
)
return [clause for clause in (opening, place) if clause]
def _where_conference(reference: Reference) -> list[str]:
"""``In: Proceedings of …, pp. 10–20. Springer, Cham (2022)``"""
inside = _container(reference) or _clean(reference.event_title)
pages = _pages(reference)
if pages:
inside = _join_comma(inside, f"pp. {pages}")
opening = f"In: {inside}" if inside else ""
place = _with_year(
_join_comma(
_clean(reference.publisher),
_clean(reference.publisher_place) or _clean(reference.event_place),
),
reference,
)
return [clause for clause in (opening, place) if clause]
def _where_thesis(reference: Reference) -> list[str]:
"""``Thesis, 清华大学 (2020)``
The degree (PhD, 硕士) is not a field of this library, so the entry says
what it knows rather than inventing a doctorate.
"""
return [_with_year(_join_comma("Thesis", _clean(reference.publisher)), reference)]
def _where_patent(reference: Reference) -> list[str]:
"""``中国 Patent CN114000000A (2023)`` — the country and number inside the mark."""
mark = _join_space(_clean(reference.patent_country), "Patent")
marked = _join_space(mark, _clean(reference.patent_number))
return [_with_year(marked, reference)]
def _where_standard(reference: Reference) -> list[str]:
"""``GB/T 7714-2015. 中国标准出版社, 北京 (2015)``
The number follows the title rather than leading the entry: the title is
what the writer searched by and what the reader recognises.
"""
number = _clean(reference.standard_number)
place = _with_year(
_join_comma(_clean(reference.publisher), _clean(reference.publisher_place)),
reference,
)
return [clause for clause in (number, place) if clause]
def _where_report(reference: Reference) -> list[str]:
"""``NREL/TP-5000-12345, NREL, Golden (2012)``"""
clause = _join_comma(
_clean(reference.report_number),
_clean(reference.publisher),
_clean(reference.publisher_place),
)
return [_with_year(clause, reference)]
def _where_web(reference: Reference) -> list[str]:
"""``https://… (2021)`` — for a page the URL is where the entry sits."""
return [_with_year(_clean(reference.url), reference)]
def _where_dataset(reference: Reference) -> list[str]:
"""``Dataset (2024)`` — the type stands where a journal name would."""
return [_with_year("Dataset", reference)]
def _where_software(reference: Reference) -> list[str]:
"""``Software (2024)``"""
return [_with_year("Software", reference)]
def _where_preprint(reference: Reference) -> list[str]:
"""``Preprint arXiv:2405.12345 (2024)`` — how a paper is cited before a DOI."""
return [_with_year(_join_space("Preprint", _clean(reference.arxiv_id)), reference)]
def _where_generic(reference: Reference) -> list[str]:
"""Anything typed ``other``: the container, then the publisher.
The year closes whichever of the two is the last thing printed, so it never
dangles on its own in the middle of an entry.
"""
source = _join_comma(_container(reference), _pages(reference))
place = _join_comma(_clean(reference.publisher), _clean(reference.publisher_place))
if place:
return [clause for clause in (source, _with_year(place, reference)) if clause]
return [_with_year(source, reference)]
_WHERE: dict[str, Callable[[Reference], list[str]]] = {
"journal-article": _where_journal,
"newspaper-article": _where_newspaper,
"book": _where_book,
"book-chapter": _where_chapter,
"conference-paper": _where_conference,
"thesis": _where_thesis,
"patent": _where_patent,
"standard": _where_standard,
"report": _where_report,
"web-page": _where_web,
"dataset": _where_dataset,
"software": _where_software,
"preprint": _where_preprint,
}
# --- the identifier, and the day it was read ---------------------------------
def _identifier(reference: Reference) -> str:
"""``https://doi.org/10.1016/j.Sc.2010.00372``, or the URL, or nothing.
A DOI is printed as the resolvable link, which is how Springer prints it —
the column stores it bare so the two spellings cannot drift.
"""
doi = _clean(reference.doi)
if doi:
return f"https://doi.org/{doi}"
if reference.type in _URL_IS_THE_SOURCE:
return ""
return _clean(reference.url)
def _accessed(reference: Reference) -> str:
"""``Accessed 12 May 2021`` — the day an online resource was read."""
if reference.accessed_date is None:
return ""
return f"Accessed {_long_date(reference.accessed_date)}"
def _long_date(value: date) -> str:
return f"{value.day} {_MONTHS[value.month - 1]} {value.year}"
# --- what a complete entry is still missing ----------------------------------
#: The fields a complete entry needs, per type. ``None`` means "this type has no
#: such field", so the list is not padded with requirements that do not apply.
_REQUIRED: dict[str, tuple[str, ...]] = {
"journal-article": ("责任者", "刊名", "卷期页码", "出版年"),
"newspaper-article": ("责任者", "报纸名", "页码", "出版年"),
"book": ("责任者", "出版者", "出版年"),
"book-chapter": ("责任者", "书名", "页码", "出版者", "出版年"),
"conference-paper": ("责任者", "会议名", "出版年"),
"thesis": ("责任者", "培养单位", "出版年"),
"patent": ("责任者", "专利号", "出版年"),
"standard": ("标准编号", "出版年"),
"report": ("责任者", "报告编号", "出版年"),
"web-page": ("URL", "引用日期"),
"dataset": ("URL", "出版年"),
"software": ("URL", "出版年"),
"preprint": ("责任者", "出版年"),
"other": ("责任者", "出版年"),
}
def missing_fields(reference: Reference) -> list[str]:
"""Which parts of a complete entry this reference still lacks, in Chinese.
The point is that a gap should be *reported* rather than quietly rendered as
a shorter entry: an entry with no author and no year looks like a fact about
the document instead of a field nobody filled in.
"""
missing: list[str] = []
for field in _REQUIRED.get(reference.type, _REQUIRED["other"]):
if not _has(reference, field):
missing.append(field)
return missing
def _has(reference: Reference, field: str) -> bool:
"""Whether the field this label names is filled in."""
if field == "责任者":
return bool(reference.authors)
if field == "刊名" or field == "报纸名" or field == "会议名" or field == "书名":
# A chapter's 书名 and a paper's 论文集名 are both the container; a
# conference may carry its meeting name instead.
return bool(
_clean(reference.container_title)
or (field == "会议名" and _clean(reference.event_title))
)
if field == "卷期页码":
return bool(
_clean(reference.volume)
or _clean(reference.issue)
or _clean(reference.pages)
or _clean(reference.article_number)
)
if field == "页码":
return bool(_clean(reference.pages) or _clean(reference.article_number))
if field == "出版者" or field == "培养单位":
return bool(_clean(reference.publisher))
if field == "标准编号":
return bool(_clean(reference.standard_number))
if field == "报告编号":
return bool(_clean(reference.report_number) or _clean(reference.publisher))
if field == "专利号":
return bool(_clean(reference.patent_number))
if field == "URL":
return bool(_clean(reference.url) or _clean(reference.doi))
if field == "引用日期":
return reference.accessed_date is not None
if field == "出版年":
return reference.publication_year is not None
return True
# --- small helpers -----------------------------------------------------------
def _clean(value: str | None) -> str:
"""Whitespace folded, or ``""`` — so a blank field is simply absent."""
if value is None:
return ""
return " ".join(value.split())
def _container(reference: Reference) -> str:
"""The journal or book the entry sits in.
The abbreviation wins when the writer stored one: Springer abbreviates
journal titles, and an algorithm cannot abbreviate an arbitrary title
correctly, so the 刊名缩写 column is where a human decides it.
"""
return _clean(reference.container_title_short) or _clean(reference.container_title)
def _volume_issue(reference: Reference) -> str:
"""``163(2)``, ``163``, ``(2)`` or nothing."""
volume = _clean(reference.volume)
issue = _clean(reference.issue)
if volume and issue:
return f"{volume}({issue})"
return volume or (f"({issue})" if issue else "")
def _pages(reference: Reference) -> str:
"""``51–59`` with an en dash, or the article number when there is no page."""
pages = _clean(reference.pages)
if pages:
return _PAGE_RANGE.sub(lambda match: f"{match.group(1)}–{match.group(2)}", pages)
return _clean(reference.article_number)
def _with_year(clause: str, reference: Reference) -> str:
"""``Journal 163(2), 51–59 (2010)`` — the year closes the clause it follows."""
if reference.publication_year is None:
return clause
return f"{clause} ({reference.publication_year})" if clause else f"({reference.publication_year})"
def _join_comma(*parts: str) -> str:
return ", ".join(part for part in parts if part)
def _join_space(*parts: str) -> str:
return " ".join(part for part in parts if part)
+98 -15
View File
@@ -21,6 +21,12 @@ all three behaviours the feature needs:
Deleting is done in Python rather than with ``ON DELETE CASCADE`` because TiDB
parses foreign keys and then ignores them; the ORM's cascades are the only
thing that actually removes dependent rows.
The 参考文献 list is assembled in the same pass, and by the same rule: a work is
numbered where the reader first meets it, however many times it is cited
afterwards. The entries themselves are written by :mod:`app.citation_styles`,
because how a reference prints is a property of a style rather than of a
citation.
"""
from collections import defaultdict
@@ -31,6 +37,7 @@ from sqlalchemy import func, or_, select
from sqlalchemy import update as sa_update
from sqlalchemy.orm import Session
from app.citation_styles import DEFAULT_STYLE, format_reference, missing_fields
from app.crud import reference as reference_crud
from app.crud.filters import LIKE_ESCAPE, like_pattern
from app.models import (
@@ -47,6 +54,7 @@ from app.schemas.paper import (
PaperDocumentRead,
PaperListItem,
PaperRead,
PaperReferenceRead,
ParagraphRead,
ParagraphUpdate,
SentenceCreate,
@@ -329,9 +337,71 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
# --- 3. the union, in ascending position order --------------------------
positions = sorted(set(placement_by_sort) | set(sentences_by_sort))
# --- 4. the literature the document cites, in one query -----------------
#
# The 参考文献 list is assembled here rather than by the client, for the same
# reason the paragraph order is: "which work is number 7" is a rule, and two
# implementations of a rule eventually disagree. Formatting needs the rows
# themselves — authors, container, pages, DOI — so they are loaded up front,
# once, with their contributors.
cited_ids = {
citation.reference_id
for sentence in paper.sentences
for citation in sentence.citations
if citation.reference_id is not None
}
cited_references = {
row.id: row for row in reference_crud.get_many(db, sorted(cited_ids))
}
if len(cited_references) != len(cited_ids):
# Only reachable if a citation points at a row the library no longer has,
# which the foreign key is there to prevent — so it is a warning rather
# than a crash, and the entries below print as unlinked.
warnings.append(
f"有 {len(cited_ids) - len(cited_references)} 条引用指向的文献已不在库中,"
"参考文献表中只保留了引用位置。"
)
paragraphs: list[ParagraphRead] = []
citations: list[PaperCitationRead] = []
citation_index = 0
references: list[PaperReferenceRead] = []
#: Work → its entry in the list above. Keyed by reference id, because that is
#: what "the same work" means; a citation with no id at all is its own work
#: and is keyed by its citation id so it still gets one entry and one number.
entry_by_work: dict[object, PaperReferenceRead] = {}
def entry_for(citation: PaperSentenceReference) -> PaperReferenceRead:
"""The entry this citation belongs to, numbering it on first sight.
Numbering on first *sight* rather than on first citation is the whole
rule: the entries come out in the order the reader meets the works, and a
work met again keeps the number it already had.
"""
key: object = (
("reference", citation.reference_id)
if citation.reference_id is not None
else ("citation", citation.id)
)
existing = entry_by_work.get(key)
if existing is not None:
return existing
reference = (
cited_references.get(citation.reference_id)
if citation.reference_id is not None
else None
)
entry = PaperReferenceRead(
index=len(references) + 1,
reference_id=citation.reference_id,
text=format_reference(reference),
missing=missing_fields(reference),
citations=[],
)
entry_by_work[key] = entry
references.append(entry)
return entry
for position in positions:
placement = placement_by_sort.get(position)
@@ -363,30 +433,43 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
sentences=sentences,
)
# Citations are numbered in reading order, so a marker in the text and
# its entry in the 参考文献 list cannot disagree.
# Citations are numbered in reading order and by work, so a marker in the
# text and its entry in the 参考文献 list cannot disagree.
for sentence in sentences:
for citation in sentence.citations:
citation_index += 1
citations.append(
PaperCitationRead(
index=citation_index,
id=citation.id,
reference_id=citation.reference_id,
quote=citation.quote,
sentence_id=sentence.id,
sentence_content=sentence.content,
paper_template_filed_sort=position,
paragraph_name=paragraph.name,
)
entry = entry_for(citation)
row = PaperCitationRead(
index=entry.index,
id=citation.id,
reference_id=citation.reference_id,
quote=citation.quote,
sentence_id=sentence.id,
sentence_content=sentence.content,
paper_template_filed_sort=position,
paragraph_name=paragraph.name,
)
citations.append(row)
entry.citations.append(row)
paragraphs.append(paragraph)
unlinked = sum(1 for entry in references if entry.reference_id is None)
if unlinked:
warnings.append(
f"有 {unlinked} 处引用还没有关联文献库条目,参考文献表中缺少它们的条目。"
)
incomplete = [entry for entry in references if entry.missing]
if incomplete:
numbers = "、".join(f"[{entry.index}]" for entry in incomplete)
warnings.append(f"参考文献 {numbers} 的字段不完整,条目里会缺少相应信息。")
return PaperDocumentRead(
paper=read(paper),
paragraphs=paragraphs,
citations=citations,
references=references,
reference_style=DEFAULT_STYLE,
warnings=warnings,
)
+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")
+2
View File
@@ -14,6 +14,7 @@ from app.schemas.paper import (
PaperDocumentRead,
PaperListItem,
PaperRead,
PaperReferenceRead,
PaperStatus,
PaperUpdate,
ParagraphListRead,
@@ -75,6 +76,7 @@ __all__ = [
"PaperDocumentRead",
"PaperListItem",
"PaperRead",
"PaperReferenceRead",
"PaperStatus",
"PaperUpdate",
"ParagraphListRead",
+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)
+435
View File
@@ -0,0 +1,435 @@
"""Check the citation formatter against one reference of every type.
Run it with no server and no database::
.venv/bin/python scripts/check_citation_styles.py
The formatter is pure — a reference in, a printed entry out — so unlike the
``smoke_*`` scripts this one needs nothing running. It builds a reference of each
document type in memory, asserts the exact entry Springer's basic style calls
for, and exits non-zero on the first entry that does not match.
Why it exists: the style has one branch per document type, and a branch that is
wrong prints something that *looks* like a bibliography entry rather than
failing loudly. A paper citing a patent would show a plausible-looking,
incorrect line. Nineteen assertions is a cheap way to keep that from happening.
"""
from __future__ import annotations
import sys
from datetime import date
from pathlib import Path
# Running this as a plain script puts scripts/ on sys.path, not backend/, so
# `import app` would fail. Anchor to the backend directory instead.
BACKEND_DIR = Path(__file__).resolve().parents[1]
if str(BACKEND_DIR) not in sys.path:
sys.path.insert(0, str(BACKEND_DIR))
from app.citation_styles import ( # noqa: E402
DEFAULT_STYLE,
STYLES,
format_reference,
missing_fields,
)
from app.models import Reference, ReferenceAuthor # noqa: E402
_checks = 0
def check(label: str, actual: str, expected: str) -> None:
"""Assert one printed entry, showing both sides when it differs."""
global _checks
_checks += 1
if actual != expected:
raise AssertionError(
f"{label}\n expected: {expected}\n actual: {actual}"
)
print(f" ok {label}")
def author(name: str, family: str | None = None, given: str | None = None,
role: str = "author") -> ReferenceAuthor:
"""One contributor, built in memory — no session, no flush."""
return ReferenceAuthor(
name=name, family_name=family, given_name=given, role=role, sort=0
)
def reference(**fields) -> Reference:
"""A reference with sensible filled-in defaults, overridden per case."""
base: dict = {
"type": "journal-article",
"title": "题名",
"authors": [author("Smith J", "Smith", "J")],
}
base.update(fields)
authors = base.pop("authors")
row = Reference(**base)
row.authors = authors
return row
def main() -> int:
print(f"style: {DEFAULT_STYLE}(可用:{'、'.join(sorted(STYLES))})")
print("\n1. a journal article: names, title, journal, volume(issue), pages, year, DOI")
check(
"journal article",
format_reference(
reference(
title="The art of writing a scientific article",
container_title="Journal of Science Communication",
container_title_short="J. Sci. Commun.",
volume="163",
issue="2",
pages="51-59",
publication_year=2010,
doi="10.1016/j.Sc.2010.00372",
authors=[
author("Van der Geer J", "Van der Geer", "J"),
author("Hanraads JAJ", "Hanraads", "JAJ"),
author("Lupton RA", "Lupton", "RA"),
],
)
),
"Van der Geer, J., Hanraads, J.A.J., Lupton, R.A.: The art of writing a "
"scientific article. J. Sci. Commun. 163(2), 51–59 (2010). "
"https://doi.org/10.1016/j.Sc.2010.00372",
)
print("\n2. the abbreviation wins when the writer stored one, and a range gets an en dash")
entry = format_reference(
reference(
title="A paper",
container_title="Full Journal Name",
container_title_short=None,
volume="9",
pages="1000-1010",
publication_year=2020,
)
)
check(
"full 刊名 when there is no 缩写",
entry,
"Smith, J.: A paper. Full Journal Name 9, 1000–1010 (2020)",
)
print("\n3. more than six contributors become three and et al.")
check(
"seven authors",
format_reference(
reference(
title="A crowded paper",
volume="1",
pages="1-2",
publication_year=2021,
authors=[
author(f"Family{index} A", f"Family{index}", "A")
for index in range(1, 8)
],
)
),
"Family1, A., Family2, A., Family3, A., et al.: A crowded paper. "
"1, 1–2 (2021)",
)
check(
"six authors are all named",
format_reference(
reference(
title="Six",
publication_year=2021,
authors=[
author(f"Family{index} A", f"Family{index}", "A")
for index in range(1, 7)
],
)
),
"Family1, A., Family2, A., Family3, A., Family4, A., Family5, A., "
"Family6, A.: Six (2021)",
)
print("\n4. names: initials, blocks of initials, hyphens, and no halves at all")
check(
"given names become initials",
format_reference(reference(title="T", authors=[author("Yong Ming Li", "Li", "Yong Ming")], publication_year=2020)),
"Li, Y.M.: T (2020)",
)
check(
"a block of initials is expanded letter by letter",
format_reference(reference(title="T", authors=[author("Lai KK", "Lai", "KK")], publication_year=2020)),
"Lai, K.K.: T (2020)",
)
check(
"a hyphenated given name keeps its hyphen",
format_reference(reference(title="T", authors=[author("Dupont JL", "Dupont", "Jean-Luc")], publication_year=2020)),
"Dupont, J.-L.: T (2020)",
)
check(
"an institutional author is printed as stored",
format_reference(reference(title="T", authors=[author("世界卫生组织")], publication_year=2020)),
"世界卫生组织: T (2020)",
)
check(
"a CJK name with no halves is not romanised by guesswork",
format_reference(reference(title="T", authors=[author("张三")], publication_year=2020)),
"张三: T (2020)",
)
check(
"a CJK name keeps its printed form even with halves filled in",
format_reference(
reference(
title="T",
authors=[author("张三", "张", "三")],
publication_year=2020,
)
),
"张三: T (2020)",
)
check(
"editors of a book are marked (ed.)",
format_reference(
reference(
type="book",
title="Edited volume",
publisher="Springer",
publisher_place="Cham",
publication_year=2021,
authors=[author("Jones BS", "Jones", "BS", role="editor")],
)
),
"Jones, B.S. (ed.): Edited volume. Springer, Cham (2021)",
)
print("\n5. every other document type")
check(
"book with an edition and a series",
format_reference(
reference(
type="book",
title="The Elements of Style",
edition="4th edn",
series_title="Style Guides",
series_number="7",
publisher="Longman",
publisher_place="New York",
publication_year=2000,
authors=[author("Strunk W", "Strunk", "W")],
)
),
"Strunk, W.: The Elements of Style, 4th edn. Style Guides, 7. "
"Longman, New York (2000)",
)
check(
"book chapter, with the book's editors marked",
format_reference(
reference(
type="book-chapter",
title="How to prepare an electronic version of your article",
container_title="Introduction to the Electronic Age",
pages="281-304",
publisher="E-Publishing Inc.",
publisher_place="New York",
publication_year=2009,
authors=[
author("Mettam GR", "Mettam", "GR"),
author("Adams LB", "Adams", "LB"),
author("Jones BS", "Jones", "BS", role="editor"),
],
)
),
"Mettam, G.R., Adams, L.B.: How to prepare an electronic version of your "
"article. In: Jones, B.S. (ed.) Introduction to the Electronic Age, "
"pp. 281–304. E-Publishing Inc., New York (2009)",
)
check(
"conference paper",
format_reference(
reference(
type="conference-paper",
title="Crowdsourcing in the tourism industry",
container_title="Proceedings of the 3rd International Conference on Tourism",
pages="1-10",
publisher="Springer",
publisher_place="Cham",
publication_year=2019,
authors=[author("Garrigos-Simon FJ", "Garrigos-Simon", "FJ")],
)
),
"Garrigos-Simon, F.J.: Crowdsourcing in the tourism industry. In: "
"Proceedings of the 3rd International Conference on Tourism, pp. 1–10. "
"Springer, Cham (2019)",
)
check(
"conference paper that only knows its meeting",
format_reference(
reference(
type="conference-paper",
title="A meeting paper",
event_title="第 20 届管理学年会",
event_place="北京",
publication_year=2022,
)
),
"Smith, J.: A meeting paper. In: 第 20 届管理学年会. 北京 (2022)",
)
check(
"thesis",
format_reference(
reference(
type="thesis",
title="A dissertation",
publisher="清华大学",
publisher_place="北京",
publication_year=2020,
)
),
"Smith, J.: A dissertation. Thesis, 清华大学 (2020)",
)
check(
"patent",
format_reference(
reference(
type="patent",
title="一种基于多层聚类的技术识别方法",
patent_country="中国",
patent_number="CN114000000A",
publication_year=2023,
)
),
"Smith, J.: 一种基于多层聚类的技术识别方法. 中国 Patent CN114000000A (2023)",
)
check(
"standard",
format_reference(
reference(
type="standard",
title="信息与文献 参考文献著录规则",
standard_number="GB/T 7714-2015",
publisher="中国标准出版社",
publisher_place="北京",
publication_year=2015,
authors=[],
)
),
"信息与文献 参考文献著录规则. GB/T 7714-2015. 中国标准出版社, 北京 (2015)",
)
check(
"report",
format_reference(
reference(
type="report",
title="Annual technology review",
report_number="NREL/TP-5000-12345",
publisher="NREL",
publisher_place="Golden",
publication_year=2012,
)
),
"Smith, J.: Annual technology review. NREL/TP-5000-12345, NREL, Golden (2012)",
)
check(
"web page, with the day it was read",
format_reference(
reference(
type="web-page",
title="Cancer statistics for the UK",
url="https://www.cancerresearchuk.org/health-professional/cancer-statistics",
publication_year=2021,
accessed_date=date(2021, 5, 12),
authors=[author("Cancer Research UK")],
)
),
"Cancer Research UK: Cancer statistics for the UK. "
"https://www.cancerresearchuk.org/health-professional/cancer-statistics "
"(2021). Accessed 12 May 2021",
)
check(
"dataset",
format_reference(
reference(
type="dataset",
title="Patent citation network",
url="https://doi.org/10.6084/m9.figshare.1234567",
publication_year=2024,
)
),
"Smith, J.: Patent citation network. Dataset (2024). "
"https://doi.org/10.6084/m9.figshare.1234567",
)
check(
"preprint, which has no DOI yet",
format_reference(
reference(
type="preprint",
title="A preprint",
arxiv_id="arXiv:2405.12345",
publication_year=2024,
)
),
"Smith, J.: A preprint. Preprint arXiv:2405.12345 (2024)",
)
check(
"newspaper article",
format_reference(
reference(
type="newspaper-article",
title="A news story",
container_title="The Times",
pages="12",
publication_year=2020,
)
),
"Smith, J.: A news story. The Times, 12 (2020)",
)
check(
"a subtitle rejoins its title",
format_reference(
reference(
title="技术惯性与冲量的耦合机制",
subtitle="基于科学与技术融合网络的实证分析",
volume="198",
pages="122-141",
publication_year=2024,
)
),
"Smith, J.: 技术惯性与冲量的耦合机制: 基于科学与技术融合网络的实证分析. "
"198, 122–141 (2024)",
)
print("\n6. a gap is reported, not papered over")
check(
"an entry with no year prints no invented year",
format_reference(reference(title="No year", volume="1", pages="1-2")),
"Smith, J.: No year. 1, 1–2",
)
missing = missing_fields(
reference(title="No year", volume=None, pages=None, container_title=None)
)
check("the missing fields are named in Chinese", "、".join(missing), "刊名、卷期页码、出版年")
check(
"a complete entry reports nothing missing",
"、".join(missing_fields(reference(
title="Complete",
container_title="A Journal",
volume="1",
pages="1-2",
publication_year=2020,
))),
"",
)
check(
"a web page without a URL is told so, in the style's own terms",
"、".join(missing_fields(reference(
type="web-page", title="No address", url=None, doi=None, accessed_date=None
))),
"URL、引用日期",
)
print(f"\nall {_checks} checks passed")
return 0
if __name__ == "__main__":
sys.exit(main())
+36 -13
View File
@@ -165,13 +165,36 @@ def main() -> int:
check("citations numbered", [c["sort"] for c in paragraph["sentences"][1]["citations"]] == [1, 2])
check("three citations in the paper", len(document["citations"]) == 3)
check(
"citation index is reading order",
[c["index"] for c in document["citations"]] == [1, 2, 3],
"a citation carries the number of its work, not of itself",
[c["index"] for c in document["citations"]] == [1, 1, 2],
str([c["index"] for c in document["citations"]]),
)
print("5. the 参考文献 list: one entry per work, in Springer's basic style")
check(
"two works — the article cited twice, and the unlinked quote",
len(document["references"]) == 2,
str(len(document["references"])),
)
first, second = document["references"]
check("both places that cite the article share its entry", len(first["citations"]) == 2)
check(
"the entry is a bibliography line, not the quote",
first["text"]
== "测试作者: 用于验证引用链路的文献. 测试期刊 (2024)",
first["text"],
)
check(
"what a complete entry still lacks is named",
first["missing"] == ["卷期页码"],
str(first["missing"]),
)
check("the unlinked quote is its own entry", second["reference_id"] is None)
check("and prints no fabricated entry", second["text"] == "", second["text"])
check("the style is reported", document["reference_style"] == "springer", document["reference_style"])
check("sentence template stamped", paragraph["sentences"][0]["template_id"] == wide["id"])
print("5. explicit sorts decide the order, not the order they were sent")
print("6. explicit sorts decide the order, not the order they were sent")
second_sort = document["paragraphs"][1]["paper_template_filed_sort"]
reordered = call(
"PUT",
@@ -202,7 +225,7 @@ def main() -> int:
{"sentences": []},
)
print("6. the seam between sentences depends on the language")
print("7. the seam between sentences depends on the language")
# Chinese needs nothing after 。; English needs a space, or two
# sentences print as `First.Second.`
mixed = call(
@@ -244,7 +267,7 @@ def main() -> int:
# Clear it again so the counts asserted below stay meaningful.
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
print("7. reject a citation with no quote")
print("8. reject a citation with no quote")
bad = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{first_sort}",
@@ -262,7 +285,7 @@ def main() -> int:
)
check("citation without content refused", "detail" in bad)
print("8. a sentence with no paragraph in the template survives a switch")
print("9. a sentence with no paragraph in the template survives a switch")
# A position neither template defines, so the check means the same
# thing before and after the switch below.
orphan_sort = (
@@ -290,7 +313,7 @@ def main() -> int:
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
)["name"] is None)
print("9. switch the template")
print("10. switch the template")
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
check("template changed", switched["template_id"] == narrow["id"])
document = call("GET", f"/papers/{paper['id']}/document")
@@ -320,7 +343,7 @@ def main() -> int:
),
)
print("10. move one paragraph onto another position")
print("11. move one paragraph onto another position")
document = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
@@ -335,18 +358,18 @@ def main() -> int:
all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]),
)
print("11. paper list reports progress")
print("12. paper list reports progress")
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
row = listing["items"][0]
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
check("sentence count", row["sentence_count"] == 3, str(row["sentence_count"]))
print("12. a template in use cannot be deleted")
print("13. a template in use cannot be deleted")
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
print("13. single sentence edit and delete")
print("14. single sentence edit and delete")
sentence_id = target["sentences"][0]["id"]
updated = call(
"PATCH",
@@ -362,7 +385,7 @@ def main() -> int:
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
)
print("14. a paper with no template still works")
print("15. a paper with no template still works")
bare = call(
"POST",
"/papers",
@@ -385,7 +408,7 @@ def main() -> int:
call("DELETE", f"/papers/{bare['id']}", expect=204)
created_papers.remove(bare["id"])
print("15. delete the paper")
print("16. delete the paper")
call("DELETE", f"/papers/{paper['id']}", expect=204)
created_papers.clear()
for reference_id in created_references:
+133 -44
View File
@@ -15,6 +15,12 @@ The order of the first two steps is the point of the tag library rather than an
accident of the script: **tags are made first and applied second**. A reference
is created *with* tag ids, never with tag names, so a typo cannot invent a label
— which is what step 4 checks.
**Every entry this script creates carries a token in its title, its author and
its tag names.** The library it runs against is a real one and may hold hundreds
of entries, so "the search found one row" is only a meaningful assertion about
rows this run made. The token is what makes each count below a statement about
this run rather than about the library's size.
"""
from __future__ import annotations
@@ -24,10 +30,21 @@ import sys
import urllib.error
import urllib.parse
import urllib.request
import uuid
from typing import Any
BASE = "http://127.0.0.1:8000/api"
#: Stamped into every entry this run creates, so each search below can be scoped
#: to this run instead of to an empty database. Short and uppercase: it travels
#: in titles, in an author name and in tag names, and shows up in failure output.
TOKEN = uuid.uuid4().hex[:6].upper()
#: A second token, carried by one contributor's *name* only. Titles and tag names
#: carry ``TOKEN``, so searching for it finds every row this run made; finding a
#: single row by author needs a string that is in exactly one place.
AUTHOR_TOKEN = f"AU{TOKEN}"
_checks = 0
@@ -73,11 +90,19 @@ def main() -> int:
survey = call(
"POST",
"/reference-tags",
{"name": " 综述 ", "color": "rgb(64, 158, 255)", "note": "综述性文献"},
{
"name": f" 综述-{TOKEN} ",
"color": "rgb(64, 158, 255)",
"note": "综述性文献",
},
expect=201,
)
created_tags.append(survey["id"])
check("a name is trimmed to one spelling", survey["name"] == "综述", survey["name"])
check(
"a name is trimmed to one spelling",
survey["name"] == f"综述-{TOKEN}",
survey["name"],
)
check(
"a colour is canonicalised",
survey["color"] == "#409EFF",
@@ -88,18 +113,27 @@ def main() -> int:
must_read = call(
"POST",
"/reference-tags",
{"name": "必读", "color": "#f56c6c"},
{"name": f"必读-{TOKEN}", "color": "#f56c6c"},
expect=201,
)
created_tags.append(must_read["id"])
check("the second tag is stored", must_read["name"] == "必读")
check("the second tag is stored", must_read["name"] == f"必读-{TOKEN}")
print("2. a tag name is unique, and only a real colour is accepted")
duplicate = call(
"POST", "/reference-tags", {"name": "综述"}, expect=409
"POST", "/reference-tags", {"name": f"综述-{TOKEN}"}, expect=409
)
check(
"the refusal names the label",
TOKEN in duplicate["detail"],
duplicate["detail"],
)
call(
"POST",
"/reference-tags",
{"name": f"怪颜色-{TOKEN}", "color": "blue"},
expect=422,
)
check("the refusal names the label", "综述" in duplicate["detail"], duplicate["detail"])
call("POST", "/reference-tags", {"name": "怪颜色", "color": "blue"}, expect=422)
call("POST", "/reference-tags", {"name": " "}, expect=422)
check("a blank name and a non-colour are refused", True)
@@ -109,7 +143,7 @@ def main() -> int:
"/references",
{
"type": "journal-article",
"title": "技术惯性与冲量的耦合机制",
"title": f"技术惯性与冲量的耦合机制({TOKEN})",
"subtitle": "基于科学与技术融合网络的实证分析",
"title_translated": "Coupling inertia and impulse in technology evolution",
"container_title": "Technological Forecasting and Social Change",
@@ -126,7 +160,11 @@ def main() -> int:
"authors": [
{"name": "张三", "family_name": "张", "given_name": "三"},
{"name": "李四"},
{"name": "Wang Wu", "family_name": "Wang", "given_name": "Wu"},
{
"name": f"Wang Wu {AUTHOR_TOKEN}",
"family_name": "Wang",
"given_name": "Wu",
},
{"name": "世界卫生组织", "role": "compiler"},
],
},
@@ -137,7 +175,8 @@ def main() -> int:
check("four contributors stored", len(article["authors"]) == 4)
check(
"they keep the order they were sent in",
[a["name"] for a in article["authors"]] == ["张三", "李四", "Wang Wu", "世界卫生组织"],
[a["name"] for a in article["authors"]]
== ["张三", "李四", f"Wang Wu {AUTHOR_TOKEN}", "世界卫生组织"],
str([a["name"] for a in article["authors"]]),
)
check(
@@ -151,7 +190,8 @@ def main() -> int:
check("not cited yet", article["citation_count"] == 0)
check(
"both tags are on the row",
sorted(tag["name"] for tag in article["tags"]) == ["必读", "综述"],
sorted(tag["name"] for tag in article["tags"])
== [f"必读-{TOKEN}", f"综述-{TOKEN}"],
str(article["tags"]),
)
@@ -159,11 +199,15 @@ def main() -> int:
missing_tag = call(
"POST",
"/references",
{"title": "引用了不存在的标签", "type": "book", "tag_ids": [999999]},
{
"title": f"引用了不存在的标签{TOKEN}",
"type": "book",
"tag_ids": [999999],
},
expect=400,
)
check("the refusal names the id", "999999" in missing_tag["detail"], missing_tag["detail"])
orphan = call("GET", "/references?keyword=引用了不存在的标签")
orphan = call("GET", f"/references?keyword=引用了不存在的标签{TOKEN}")
check("nothing was stored half-labelled", orphan["total"] == 0, str(orphan["total"]))
print("5. add a patent, which needs a country and a number")
@@ -172,7 +216,7 @@ def main() -> int:
"/references",
{
"type": "patent",
"title": "一种基于多层聚类的人工智能技术识别方法",
"title": f"一种基于多层聚类的人工智能技术识别方法({TOKEN})",
"patent_country": "中国",
"patent_number": "CN114000000A",
"publication_year": 2023,
@@ -185,7 +229,7 @@ def main() -> int:
check("patent stored", patent["type"] == "patent" and patent["patent_number"] == "CN114000000A")
check(
"tagging works on create for more than one entry",
[tag["name"] for tag in patent["tags"]] == ["必读"],
[tag["name"] for tag in patent["tags"]] == [f"必读-{TOKEN}"],
str(patent["tags"]),
)
@@ -204,28 +248,40 @@ def main() -> int:
call(
"POST",
"/references",
{"title": "没有标签的书", "authors": [{"name": "甲"}], "type": "book"},
{
"title": f"没有标签的书{TOKEN}",
"authors": [{"name": "甲"}],
"type": "book",
},
expect=201,
)
probe = call("GET", "/references?keyword=没有标签的书")
probe = call("GET", f"/references?keyword=没有标签的书{TOKEN}")
created_references.append(probe["items"][0]["id"])
check("a book needs nothing else", probe["total"] == 1)
check("and may carry no tags at all", probe["items"][0]["tags"] == [])
print("8. find it again: by author, by type, by year, by tag")
by_author = call("GET", "/references?keyword=Wang")
check("search matches an author name", by_author["total"] == 1, str(by_author["total"]))
by_author = call("GET", f"/references?keyword={AUTHOR_TOKEN}")
check(
"search matches an author name",
by_author["total"] == 1,
f'{by_author["total"]} (the token is on one author name)',
)
check(
"the row prints an author line",
by_author["items"][0]["authors_line"].startswith("张三, 李四, Wang Wu"),
by_author["items"][0]["authors_line"],
)
by_type = call("GET", "/references?type=patent")
by_type = call("GET", f"/references?type=patent&keyword={TOKEN}")
check("filter by type", by_type["total"] == 1, str(by_type["total"]))
by_year = call("GET", "/references?year=2024")
by_year = call("GET", f"/references?year=2024&keyword={TOKEN}")
check("filter by year", by_year["total"] == 1, str(by_year["total"]))
uncited = call("GET", "/references?cited=false")
check("filter by not-yet-cited", uncited["total"] == len(created_references))
uncited = call("GET", f"/references?cited=false&keyword={TOKEN}")
check(
"filter by not-yet-cited",
uncited["total"] == len(created_references),
f'{uncited["total"]} of {len(created_references)}',
)
by_tag = call("GET", f"/references?tag={must_read['id']}")
check("filter by tag", by_tag["total"] == 2, str(by_tag["total"]))
@@ -240,31 +296,43 @@ def main() -> int:
)
print("9. the tag table counts what carries each label")
tags = call("GET", "/reference-tags")
tags = call("GET", f"/reference-tags?keyword={TOKEN}")
counts = {tag["name"]: tag["reference_count"] for tag in tags["items"]}
check("two labels in the library", tags["total"] == 2, str(tags["total"]))
check("the shared label counts two rows", counts["必读"] == 2, str(counts))
check("the other counts one", counts["综述"] == 1, str(counts))
found = call("GET", "/reference-tags?keyword=综述")
check("two labels carry this run's token", tags["total"] == 2, str(tags["total"]))
check(
"the shared label counts two rows",
counts[f"必读-{TOKEN}"] == 2,
str(counts),
)
check("the other counts one", counts[f"综述-{TOKEN}"] == 1, str(counts))
found = call("GET", f"/reference-tags?keyword=综述-{TOKEN}")
check("tags are searchable by name", found["total"] == 1, str(found["total"]))
print("10. renaming a label follows it everywhere it is used")
renamed = call(
"PATCH",
f"/reference-tags/{survey['id']}",
{"name": "综述文章", "note": "综述与述评"},
{"name": f"综述文章-{TOKEN}", "note": "综述与述评"},
)
check("the label is renamed", renamed["name"] == "综述文章")
check("the label is renamed", renamed["name"] == f"综述文章-{TOKEN}")
after = call("GET", f"/references/{article['id']}")
check(
"the reference prints the new name",
sorted(tag["name"] for tag in after["tags"]) == ["必读", "综述文章"],
sorted(tag["name"] for tag in after["tags"])
== [f"必读-{TOKEN}", f"综述文章-{TOKEN}"],
str(after["tags"]),
)
taken = call(
"PATCH", f"/reference-tags/{survey['id']}", {"name": "必读"}, expect=409
"PATCH",
f"/reference-tags/{survey['id']}",
{"name": f"必读-{TOKEN}"},
expect=409,
)
check(
"renaming onto a taken name is refused",
TOKEN in taken["detail"],
taken["detail"],
)
check("renaming onto a taken name is refused", "必读" in taken["detail"], taken["detail"])
print("11. edit it: replace the contributor list, a field and its tags")
updated = call(
@@ -283,7 +351,7 @@ def main() -> int:
check("author list replaced wholesale", len(updated["authors"]) == 2)
check(
"tag list replaced wholesale too",
[tag["name"] for tag in updated["tags"]] == ["必读"],
[tag["name"] for tag in updated["tags"]] == [f"必读-{TOKEN}"],
str(updated["tags"]),
)
check("untouched fields kept", updated["container_title"] == "Technological Forecasting and Social Change")
@@ -291,7 +359,7 @@ def main() -> int:
cleared = call("PATCH", f"/references/{patent['id']}", {"tag_ids": None})
check(
"omitting tags leaves them alone",
[tag["name"] for tag in cleared["tags"]] == ["必读"],
[tag["name"] for tag in cleared["tags"]] == [f"必读-{TOKEN}"],
str(cleared["tags"]),
)
@@ -300,7 +368,10 @@ def main() -> int:
paper = call(
"POST",
"/papers",
{"title": "参考文献冒烟测试论文", "template_id": templates[0]["id"]},
{
"title": f"参考文献冒烟测试论文{TOKEN}",
"template_id": templates[0]["id"],
},
expect=201,
)
created_papers.append(paper["id"])
@@ -338,7 +409,7 @@ def main() -> int:
check("and the paper", citations[0]["paper_id"] == paper["id"])
check("and the paragraph heading", citations[0]["paragraph_name"] is not None, str(citations[0]))
cited = call("GET", "/references?cited=true")
cited = call("GET", f"/references?cited=true&keyword={TOKEN}")
check("the cited filter now finds it", cited["total"] == 1, str(cited["total"]))
print("14. a cited reference cannot be deleted; an uncited one can")
@@ -361,7 +432,25 @@ def main() -> int:
str(left["total"]),
)
print("16. clean up")
print("16. the 参考文献 list prints one entry per work, in Springer style")
document = call("GET", f"/papers/{paper['id']}/document")
check("the style is named in the response", document["reference_style"] == "springer")
check(
"one entry for the one work cited",
len(document["references"]) == 1,
str(len(document["references"])),
)
entry = document["references"][0]
check("the entry is a bibliography line", entry["text"].startswith("张三, 李四"), entry["text"])
check("and carries the year and the DOI", "(2024)" in entry["text"] and "https://doi.org/10.1016/j.techfore.2024.123456" in entry["text"], entry["text"])
check("it names the places it is cited", len(entry["citations"]) == 1, str(len(entry["citations"])))
check(
"and the in-text marker is that entry's number",
entry["citations"][0]["index"] == entry["index"],
f'{entry["citations"][0]["index"]} vs {entry["index"]}',
)
print("17. clean up")
call("DELETE", f"/papers/{paper['id']}", expect=204)
created_papers.clear()
for reference_id in created_references:
@@ -370,13 +459,13 @@ def main() -> int:
for tag_id in created_tags:
call("DELETE", f"/reference-tags/{tag_id}", expect=204)
created_tags.clear()
remaining = call("GET", "/references")
# Scoped by the token rather than by "the library is empty": the library
# this runs against holds real literature, and what must be true is that
# none of *this run's* rows survive.
remaining = call("GET", f"/references?keyword={TOKEN}")
check("nothing of ours is left", remaining["total"] == 0, str(remaining["total"]))
check(
"and no labels either",
call("GET", "/reference-tags")["total"] == 0,
str(call("GET", "/reference-tags")["total"]),
)
tags_left = call("GET", f"/reference-tags?keyword={TOKEN}")
check("and no labels either", tags_left["total"] == 0, str(tags_left["total"]))
print(f"\nall {_checks} checks passed")
return 0
+6 -1
View File
@@ -249,7 +249,7 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
| `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
| `paper_document` | 读全文 | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
| `paper_document` | 读全文(`format=text` 时末尾附 Springer 格式的参考文献表) | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
| `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
@@ -258,6 +258,11 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
`paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
`paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。
`json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`),
以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`),
不要自己去猜或补一个看起来合理的年份。
### 3.2 段落 paragraphs(5 个)
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
+77 -9
View File
@@ -370,6 +370,42 @@ The ORM cascades stay as well. `Template.items`, `Paper.sentences` and
removes its dependents whether or not the database would have done it too —
which keeps behaviour identical on a cluster with foreign keys switched off.
### The 参考文献 list is one entry per work, written by a style
A citation and a bibliography entry are two different counts, and confusing them
is the mistake this design is shaped around. `paper_sentence_reference` holds one
row per *place in the text* that quotes something: a paper of 86 citations to 65
works has 86 rows. The 参考文献 list has 65 entries, each numbered where the
reader first meets it, and every citation of that work carries the same number.
So `[7]` means one article everywhere — in the text, in the tooltip on the
marker, and in the list — and a work cannot appear twice under two numbers.
The entries themselves are written by :mod:`app.citation_styles`, which is a
package of one module per style:
```
app/citation_styles/
├── __init__.py the registry, DEFAULT_STYLE, format_reference/missing_fields
└── springer.py Springer's basic style — the numbered one
```
`GET /papers/{id}/document` returns `references` (the entries, in order) and
`reference_style` (which style wrote them). Three consequences are deliberate:
- **The client prints `text` verbatim.** Formatting a bibliography from fields
is a rule, and a second implementation of a rule prints a second bibliography
eventually. The paper view, the MCP text renderer and a future export all read
the same assembled entries.
- **A citation with no library row keeps its number and gets no entry.** It is
listed as its own entry with empty text and a warning, rather than dropped —
dropping it would leave a `[12]` in the text pointing at nothing.
- **A gap is reported, not filled in.** Each entry carries `missing` — the parts
a complete entry needs and does not have, in Chinese (「缺 责任者、出版年」) —
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; saying so
is the difference between a library that needs attention and a bibliography
that lies.
## API
All routes are mounted under `/api`. Interactive docs at `/docs`.
@@ -398,7 +434,7 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
| `POST` | `/reference-tags` | name is unique — a duplicate is `409` naming it |
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
| `POST` | `/reference-tags/batch-delete` | body `{ "ids": [...] }`; unlabels, never deletes literature |
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, warnings |
| `GET` | `/papers/{id}/document` | the whole paper: paragraphs in order, citations, the formatted `references`, warnings |
| `GET` | `/papers/{id}/paragraphs/{sort}` | one paragraph, assembled as the document renders it |
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
| `POST` | `/papers/{id}/sentences` | append one sentence |
@@ -416,9 +452,14 @@ Conventions worth knowing:
`/template-titles` for `template_title`, `/papers` for
`paper`.
- A paper document returns its `paragraphs` in ascending position order,
already carrying their sentences and citation numbering. The client sorts
nothing and merges nothing: two implementations of the same ordering rule
would eventually disagree.
already carrying their sentences and citation numbering, and its `references`
as formatted entries. The client sorts nothing, merges nothing and formats
nothing: two implementations of the same rule would eventually disagree.
- A citation's `index` is the number of its **work**, so 86 citations to 65
works produce 65 entries and repeated numbers in `citations` — see 「The
参考文献 list is one entry per work」 above.
- A document's `reference_style` names the style the entries were written in
(`springer`), so a client can label the block without hard-coding the choice.
- Sentence `content` is folded to a single line (leading, trailing and inner
whitespace runs collapse to one space), so an all-whitespace sentence becomes
the empty string — legal, and rendered as a blank line. A citation with a
@@ -630,8 +671,12 @@ alone knows how to do:
- **an edit button beside every paragraph**, written or not — content only ever
enters a paper through the paragraph editor, so it may never be the thing that
is missing;
- **numbered citation markers** in the text, matching the 参考文献 list, which
is numbered in reading order rather than per paragraph;
- **numbered citation markers** in the text, whose number is the number of the
*work* in the 参考文献 list below — a paper that cites one article in three
sentences prints the same number three times;
- **the 参考文献 block, printed from the server's entries and not reassembled** —
each entry is one work with its bibliography line, and the paragraphs that
cite it hang underneath it, with the quoted passages in the tooltip;
- **a 切换模板 dialog that previews the impact** — how much content lands under
a new heading, how much keeps its place under 未设定, and how many empty
paragraphs the new template adds — because a switch re-shapes the whole
@@ -676,6 +721,8 @@ paper-doc/
│ ├── app/
│ │ ├── api/routes/ # route handlers (health, papers, references,
│ │ │ # reference_tags, templates, template_title)
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
│ │ │ # registry that names the styles
│ │ ├── core/ # settings and configuration
│ │ ├── crud/ # data-access helpers
│ │ ├── db/ # engine, session, declarative base
@@ -687,6 +734,8 @@ paper-doc/
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
│ │ # and its tags
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
│ │ # (no server, no database)
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
│ ├── alembic.ini
@@ -774,15 +823,34 @@ cd backend
`scripts/smoke_references.py` makes the labels first, adds literature and tags
it, finds it again by author, type, year and tag, edits it, cites it from a
sentence, looks the citation up from the reference side, checks that a cited
entry cannot be deleted while a tag can, and checks that a tag id the library
does not have is refused by name rather than invented. It cleans up after
itself:
entry cannot be deleted while a tag can, that a tag id the library does not have
is refused by name rather than invented, and that the paper's 参考文献 list
prints one formatted entry per work. It cleans up after itself:
```bash
cd backend
.venv/bin/python scripts/smoke_references.py
```
Every row it creates carries a per-run token in its title, in one author's name
and in its label names, and it asserts against searches for that token. The
library it runs against is a real one, so "the search found one row" is only a
statement about this run if the run can name its own rows.
**Checking the citation formatter**
`scripts/check_citation_styles.py` needs nothing running: it builds a reference
of every document type in memory and asserts the exact entry Springer's basic
style calls for — authors and initials, the six-author limit, the en-dashed page
range, the DOI, and what is reported missing. A wrong branch here prints
something that *looks* like a bibliography entry, which is exactly the kind of
bug that survives a smoke test:
```bash
cd backend
.venv/bin/python scripts/check_citation_styles.py
```
**Checking the paper feature end to end**
`scripts/smoke_papers.py` walks the whole writing loop against a running API —
+42 -1
View File
@@ -116,7 +116,14 @@ export interface PaperParagraph {
/** One citation as it appears in the 参考文献 list. */
export interface PaperCitation extends Citation {
/** The number shown in the text as `[index]`, in reading order. */
/**
* The number shown in the text as `[index]`, in reading order.
*
* It is the number of the **work**, not of the citation: a paper that cites
* the same article in three sentences prints `[7]` three times and lists the
* article once. Everything that numbers citations reads it from here, so the
* markers and the list cannot disagree.
*/
index: number
sentence_id: number
sentence_content: string
@@ -124,11 +131,35 @@ export interface PaperCitation extends Citation {
paragraph_name: string | null
}
/**
* One entry of the 参考文献 list: one work, however often it is cited.
*
* `text` is the whole entry as it prints, already formatted by the server in
* `reference_style`. A client prints it verbatim — assembling a bibliography
* from fields is a second implementation of a rule, and the two would drift.
*/
export interface PaperReference {
/** The number the text shows as `[index]`. */
index: number
/** The library row it came from, or `null` for a citation written before the
* literature was entered — `text` is empty in that case, and nothing is
* invented to fill it. */
reference_id: number | null
text: string
/** What a complete entry still lacks, in Chinese — 责任者、出版年、DOI… */
missing: string[]
/** Every place in the text that cites it, in reading order. */
citations: PaperCitation[]
}
/** The whole paper as it reads. */
export interface PaperDocument {
paper: PaperDetail
paragraphs: PaperParagraph[]
citations: PaperCitation[]
references: PaperReference[]
/** The citation style the entries were written in, e.g. `springer`. */
reference_style: string
warnings: string[]
}
@@ -218,6 +249,16 @@ export async function getPaperDocument(id: number): Promise<PaperDocument> {
return data
}
/** Display names for the citation styles the server can print. */
export const REFERENCE_STYLE_LABELS: Record<string, string> = {
springer: 'Springer 基本格式',
}
/** The label for a style token, falling back to the token itself. */
export function referenceStyleLabel(style: string): string {
return REFERENCE_STYLE_LABELS[style] ?? style
}
export async function createPaper(payload: PaperPayload): Promise<PaperDetail> {
const { data } = await http.post<PaperDetail>('/papers', payload)
return data
@@ -32,6 +32,8 @@ const props = defineProps<{
paragraph: PaperParagraph
/** Citation id -> the number shown in the text, assigned by reading order. */
citationIndex: Record<number, number>
/** Reference id -> its formatted entry, so a marker can say what it points at. */
referenceText: Record<number, string>
}>()
defineEmits<{ edit: [paragraph: PaperParagraph] }>()
@@ -106,12 +108,19 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
>
<template #content>
<div class="cite-tip">
<div class="cite-tip-head">
[{{ citationIndex[citation.id] ?? '?' }}]
<span v-if="citation.reference_id">引用 #{{ citation.reference_id }}</span>
<span v-else class="cite-tip-unlinked">未关联引用 id</span>
<div class="cite-tip-head">[{{ citationIndex[citation.id] ?? '?' }}]</div>
<!-- What the number means: the entry as the bibliography prints
it, not its database id. -->
<div
v-if="citation.reference_id != null && referenceText[citation.reference_id]"
class="cite-tip-entry"
>
{{ referenceText[citation.reference_id] }}
</div>
<div class="cite-tip-quote">{{ citation.quote }}</div>
<div v-else class="cite-tip-unlinked">
这处引用还没有关联文献库条目
</div>
<div class="cite-tip-quote">「{{ citation.quote }}」</div>
</div>
</template>
<sup class="cite-mark">{{ citationIndex[citation.id] ?? '?' }}</sup>
@@ -222,7 +231,7 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
}
.cite-tip {
max-width: 320px;
max-width: 380px;
}
.cite-tip-head {
@@ -232,7 +241,15 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
font-weight: 600;
}
/* The bibliography entry: the whole point of the tooltip. It is set as a
paragraph of running text because that is how it prints in the list. */
.cite-tip-entry {
margin-top: 4px;
line-height: 1.7;
}
.cite-tip-unlinked {
margin-top: 4px;
font-weight: 400;
opacity: 0.7;
}
+135 -15
View File
@@ -29,7 +29,6 @@ import {
Delete,
Edit,
Refresh,
Right,
Switch,
Warning,
} from '@element-plus/icons-vue'
@@ -41,8 +40,10 @@ import {
getPaperDocument,
PAPER_STATUS_LABELS,
PAPER_STATUS_TAG,
referenceStyleLabel,
type PaperDocument,
type PaperParagraph,
type PaperReference,
} from '@/api/papers'
import PaperFormDialog from '@/components/papers/PaperFormDialog.vue'
import ParagraphEditDialog from '@/components/papers/ParagraphEditDialog.vue'
@@ -77,6 +78,52 @@ const citationIndex = computed<Record<number, number>>(() => {
return map
})
/**
* Reference id -> the formatted entry, for the marker tooltips.
*
* The tooltip on a `[7]` in the text should say what `[7]` *is*, and the entry
* is assembled once by the server — this is a lookup of that same string, not a
* second attempt at formatting it.
*/
const referenceText = computed<Record<number, string>>(() => {
const map: Record<number, string> = {}
for (const entry of paperDoc.value?.references ?? []) {
if (entry.reference_id != null && entry.text) {
map[entry.reference_id] = entry.text
}
}
return map
})
/** How the entries are printed, named rather than hard-coded in the view. */
const styleLabel = computed(() =>
referenceStyleLabel(paperDoc.value?.reference_style ?? 'springer'),
)
/**
* Where an entry is cited, one row per paragraph.
*
* The same work cited twice in one paragraph is one place with a count, not two
* identical links: what the reader needs from the list is where to look, and
* the quotes for that paragraph travel in the tooltip.
*/
function places(entry: PaperReference): { sort: number; name: string; quotes: string[] }[] {
const byParagraph = new Map<number, { sort: number; name: string; quotes: string[] }>()
for (const citation of entry.citations) {
const found = byParagraph.get(citation.paper_template_filed_sort)
if (found) {
found.quotes.push(citation.quote)
continue
}
byParagraph.set(citation.paper_template_filed_sort, {
sort: citation.paper_template_filed_sort,
name: citation.paragraph_name ?? PARAGRAPH_UNSET_LABEL,
quotes: [citation.quote],
})
}
return [...byParagraph.values()]
}
/** How much of the structure has been written, for the header read-out. */
const progress = computed(() => {
if (!paperDoc.value) return { written: 0, total: 0, unmatched: 0 }
@@ -268,33 +315,69 @@ onMounted(load)
:key="paragraph.paper_template_filed_sort"
:paragraph="paragraph"
:citation-index="citationIndex"
:reference-text="referenceText"
@edit="openParagraph"
/>
</div>
</el-card>
<el-card v-if="paperDoc?.citations.length" shadow="never">
<el-card v-if="paperDoc?.references.length" shadow="never">
<template #header>
<div class="paper-head">
<span class="paper-title">参考文献引用</span>
<span class="paper-hint">按正文出现顺序编号,正文中的上标与这里的序号一一对应</span>
<span class="paper-title">参考文献</span>
<span class="paper-hint">
按正文首次出现顺序编号,同一篇文献在多处引用共用同一个序号;条目按 {{ styleLabel }} 排版
</span>
</div>
</template>
<ol class="references">
<li v-for="citation in paperDoc.citations" :key="citation.id" class="reference">
<span class="reference-index">[{{ citation.index }}]</span>
<li v-for="entry in paperDoc.references" :key="entry.index" class="reference">
<span class="reference-index">[{{ entry.index }}]</span>
<div class="reference-body">
<div class="reference-quote">{{ citation.quote }}</div>
<!-- The entry as it prints. Whatever the library is missing shows
up as a shorter entry, so the gap is named underneath rather
than quietly filled in. -->
<p v-if="entry.text" class="reference-text">{{ entry.text }}</p>
<p v-else class="reference-text reference-text--unlinked">
这处引用还没有关联文献库条目,只有引用内容。
</p>
<div class="reference-meta">
<el-tag v-if="citation.reference_id" size="small" effect="plain">
引用 #{{ citation.reference_id }}
<el-tag
v-if="entry.missing.length"
type="warning"
size="small"
effect="plain"
>
缺 {{ entry.missing.join('、') }}
</el-tag>
<el-tag v-else size="small" type="warning" effect="plain">未关联引用 id</el-tag>
<el-button link type="primary" @click="scrollToParagraph(citation.paper_template_filed_sort)">
{{ citation.paragraph_name ?? PARAGRAPH_UNSET_LABEL }}
<el-icon><Right /></el-icon>
</el-button>
<el-tag v-if="!entry.reference_id" type="warning" size="small" effect="plain">
未关联文献
</el-tag>
<span class="reference-places">
<span class="reference-places-label">引用位置</span>
<el-tooltip
v-for="place in places(entry)"
:key="place.sort"
placement="top"
:show-after="200"
>
<template #content>
<div class="place-tip">
<div v-for="(quote, index) in place.quotes" :key="index">
「{{ quote }}」
</div>
</div>
</template>
<el-button link type="primary" @click="scrollToParagraph(place.sort)">
{{ place.name }}
<span v-if="place.quotes.length > 1" class="place-count">
×{{ place.quotes.length }}
</span>
</el-button>
</el-tooltip>
</span>
</div>
</div>
</li>
@@ -446,19 +529,56 @@ onMounted(load)
.reference-body {
min-width: 0;
flex: 1 1 auto;
}
.reference-quote {
/* The entry, printed as the style wrote it: one line of running text, hanging
under its number like a bibliography. */
.reference-text {
margin: 0;
font-size: 13px;
line-height: 1.8;
color: var(--el-text-color-regular);
overflow-wrap: anywhere;
}
.reference-text--unlinked {
color: var(--el-color-warning);
}
.reference-meta {
display: flex;
align-items: center;
gap: 8px;
margin-top: 4px;
flex-wrap: wrap;
}
.reference-places {
display: inline-flex;
align-items: center;
gap: 2px;
flex-wrap: wrap;
font-size: 12px;
color: var(--el-text-color-secondary);
}
.reference-places-label {
margin-right: 2px;
color: var(--el-text-color-placeholder);
}
.place-count {
margin-left: 2px;
color: var(--el-text-color-placeholder);
font-variant-numeric: tabular-nums;
}
.place-tip {
display: flex;
flex-direction: column;
gap: 4px;
max-width: 420px;
line-height: 1.7;
}
</style>