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.
This commit is contained in:
+6
-1
@@ -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_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
|
||||||
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
|
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
|
||||||
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
|
| `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` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
|
||||||
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
|
| `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_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
|
||||||
|
|
||||||
|
`paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。
|
||||||
|
`json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`),
|
||||||
|
以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`),
|
||||||
|
不要自己去猜或补一个看起来合理的年份。
|
||||||
|
|
||||||
### 3.2 段落 paragraphs(5 个)
|
### 3.2 段落 paragraphs(5 个)
|
||||||
|
|
||||||
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
|
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
|
||||||
|
|||||||
+77
-9
@@ -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 —
|
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.
|
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
|
## API
|
||||||
|
|
||||||
All routes are mounted under `/api`. Interactive docs at `/docs`.
|
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 |
|
| `POST` | `/reference-tags` | name is unique — a duplicate is `409` naming it |
|
||||||
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
|
| `GET` `PATCH` `DELETE` | `/reference-tags/{id}` | renaming follows every reference carrying it |
|
||||||
| `POST` | `/reference-tags/batch-delete` | body `{ "ids": [...] }`; unlabels, never deletes literature |
|
| `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 |
|
| `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 |
|
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
|
||||||
| `POST` | `/papers/{id}/sentences` | append one sentence |
|
| `POST` | `/papers/{id}/sentences` | append one sentence |
|
||||||
@@ -416,9 +452,14 @@ Conventions worth knowing:
|
|||||||
`/template-titles` for `template_title`, `/papers` for
|
`/template-titles` for `template_title`, `/papers` for
|
||||||
`paper`.
|
`paper`.
|
||||||
- A paper document returns its `paragraphs` in ascending position order,
|
- A paper document returns its `paragraphs` in ascending position order,
|
||||||
already carrying their sentences and citation numbering. The client sorts
|
already carrying their sentences and citation numbering, and its `references`
|
||||||
nothing and merges nothing: two implementations of the same ordering rule
|
as formatted entries. The client sorts nothing, merges nothing and formats
|
||||||
would eventually disagree.
|
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
|
- Sentence `content` is folded to a single line (leading, trailing and inner
|
||||||
whitespace runs collapse to one space), so an all-whitespace sentence becomes
|
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
|
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
|
- **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
|
enters a paper through the paragraph editor, so it may never be the thing that
|
||||||
is missing;
|
is missing;
|
||||||
- **numbered citation markers** in the text, matching the 参考文献 list, which
|
- **numbered citation markers** in the text, whose number is the number of the
|
||||||
is numbered in reading order rather than per paragraph;
|
*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 切换模板 dialog that previews the impact** — how much content lands under
|
||||||
a new heading, how much keeps its place under 未设定, and how many empty
|
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
|
paragraphs the new template adds — because a switch re-shapes the whole
|
||||||
@@ -676,6 +721,8 @@ paper-doc/
|
|||||||
│ ├── app/
|
│ ├── app/
|
||||||
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
||||||
│ │ │ # reference_tags, templates, template_title)
|
│ │ │ # reference_tags, templates, template_title)
|
||||||
|
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
|
||||||
|
│ │ │ # registry that names the styles
|
||||||
│ │ ├── core/ # settings and configuration
|
│ │ ├── core/ # settings and configuration
|
||||||
│ │ ├── crud/ # data-access helpers
|
│ │ ├── crud/ # data-access helpers
|
||||||
│ │ ├── db/ # engine, session, declarative base
|
│ │ ├── 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_papers.py # end-to-end check of the writing loop
|
||||||
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
||||||
│ │ # and its tags
|
│ │ # 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/mcp_server.py # MCP entry point (stdio / http)
|
||||||
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||||
│ ├── alembic.ini
|
│ ├── alembic.ini
|
||||||
@@ -774,15 +823,34 @@ cd backend
|
|||||||
`scripts/smoke_references.py` makes the labels first, adds literature and tags
|
`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
|
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
|
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
|
entry cannot be deleted while a tag can, that a tag id the library does not have
|
||||||
does not have is refused by name rather than invented. It cleans up after
|
is refused by name rather than invented, and that the paper's 参考文献 list
|
||||||
itself:
|
prints one formatted entry per work. It cleans up after itself:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
.venv/bin/python scripts/smoke_references.py
|
.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**
|
**Checking the paper feature end to end**
|
||||||
|
|
||||||
`scripts/smoke_papers.py` walks the whole writing loop against a running API —
|
`scripts/smoke_papers.py` walks the whole writing loop against a running API —
|
||||||
|
|||||||
Reference in New Issue
Block a user