diff --git a/docs/MCP.md b/docs/MCP.md index 847561f..d1f0029 100644 --- a/docs/MCP.md +++ b/docs/MCP.md @@ -249,7 +249,7 @@ Header: Authorization: Bearer | `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 `paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。 +`paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。 +`json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`), +以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`), +不要自己去猜或补一个看起来合理的年份。 + ### 3.2 段落 paragraphs(5 个) 段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。 diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md index fba428a..ed7bfda 100644 --- a/docs/OVERVIEW.md +++ b/docs/OVERVIEW.md @@ -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 —