Files
paper-doc/docs/OVERVIEW.md
T
govin 48f0c12fd2 frontend: let the writer set a figure's size in the editor
Figures come out of a plotting tool at whatever size they were made. On the
paper this was written for, the sixteen of them are 1441, 1857, 2409 and 4169
pixels wide — every one wider than the 1276px column — so with no size they all
printed at the full width, and the near-square ones (1857×1986, 1974×2068) took
1365px of height, a page each. Measured in the browser, all sixteen came out at
exactly 1276px: not one of them was the size its author wanted.

`{width=…}` has been in the syntax all along, so this is the control that was
missing, not the feature. A row that is a figure now carries 宽度 in its header:
25/50/70/100%, or any value typed in — the size a panel wants is what it
measures, not a round number — with 原尺寸 as the empty value. Beside it, what
the picture will measure on the page (`原图 1857×1986 · 显示 893×955`), worked
out against the column actually rendered behind the dialog, which is the number
the writer is deciding with.

Two rules keep it honest. The value goes through `parseImageWidth` — the same
function that parses the attribute when the paper is printed — so what the
control shows is what will be printed, and a value it cannot read is refused
with the forms that work instead of stored as a size that quietly does nothing.
And the attribute is written into the sentence content by `withImageWidth`,
which edits only the first picture: the control is offered for a figure, and a
sentence with words around its picture is not one. Reading the size back out of
the content rather than keeping a copy of it in the draft means there is one
place it can be wrong instead of two.

`check-image.mjs` grows from 15 checks to 24, driving the real control: that
only figure rows offer one, that it shows what each is set to, that typing 30%
converts to 383×239 immediately, that what was typed is what gets stored, that
the paper then prints it at 30% of the column, that clearing it goes back to the
natural 480×300, and that "宽一点" is refused while the sentence keeps its size.

The MCP side of the same rule was wrong and is fixed with it: `image_upload(width=
"60")` wrote `{width=60px}`, and the reader takes a bare number as a share of the
column — `parseImageWidth` only reads pixels when the value says `px`. A model
asking for 60% got a 60-pixel figure. v7 is deployed with the corrected reading,
and smoke_mcp.py checks it.
2026-09-24 11:25:18 +08:00

61 KiB
Raw Blame History

paper-doc

A tool that supports the paper-writing process: it manages the materials, sections, figures, and references that go into a paper. The name reflects the document-centric core of the workflow — a paper is composed from structured documents rather than written in one pass.

The first feature to land is the template configuration: a reusable library of section fields plus named templates built from them, so that a paper is written by filling in a known structure instead of deciding one.

The second is paper authoring: a paper is a document written against a template, sentence by sentence, paragraph by paragraph. The structure is never copied into the paper — it is read from the template on every render — so switching a paper's template re-shapes the whole document in one write without touching a single sentence.

Tech Stack

Backend

  • FastAPI (Python) — REST API
  • SQLAlchemy + Alembic — ORM layer and schema migrations
  • TiDB v8.5.0 — MySQL-compatible distributed SQL database, deployed in k3s
  • MCP Python SDK — the same domain layer, exposed as MCP tools (see below)
  • Dependencies managed with venv + requirements.txt

Frontend

  • Vue 3 + Vite — single-page application
  • axios — HTTP client
  • vue-router — client-side routing
  • pinia + pinia-plugin-persistedstate — state management with persistence
  • Element Plus — UI component library
  • Dependencies managed with pnpm

Architecture

A decoupled SPA + REST API layout:

  • The Vue SPA runs in the browser and talks to the backend exclusively over HTTP/JSON via axios. It holds no direct database access.
  • The FastAPI backend owns all persistence. It connects to TiDB through SQLAlchemy sessions and owns the schema through Alembic migrations.
  • TiDB runs inside the existing k3s cluster. The backend reaches it either through the in-cluster Service (tidb-tidb.tidb:4000) or, during local development, through the NodePort 192.168.1.88:32738.

Development runs both parts locally: Vite serves the SPA with a dev proxy that forwards /api to the FastAPI process, so the browser sees a single origin and no CORS configuration is required.

Browser ──HTTP/JSON──▶ FastAPI ──SQLAlchemy──▶ TiDB (k3s)
   │                      ▲
   └── Vite dev server ───┘  (proxy /api)

Domain Model

Ten tables. Every one is prefixed with the module it belongs to, and a model class is named after its table, so the schema can be read as four groups:

template_title                    one reusable heading (字段库)
  id, name, level, font_size, font_color

template                          a named outline (模板)
  id, name, abstract

template_title_placement          that heading placed in a template — and the
  id, template_id → template,     only home of display order
  title_id → template_title, sort

paper                             the document
  id, title, template_id, author, status, keywords, target_journal

paper_sentence                    one sentence, at one position, in one paper
  id, paper_id → paper, template_id, paper_template_filed_sort, sort, content

paper_sentence_reference          the citations of one sentence
  id, sentence_id → paper_sentence, reference_id → reference, quote, sort

reference                         the 参考文献 module: the literature itself
  id, type, title, subtitle, container_title, volume, issue, pages,
  publisher, publisher_place, publication_year, doi, url, …

reference_author                  its contributors, in print order
  id, reference_id → reference, sort, name, family_name, given_name, role

reference_tag                     the writer's own labels (文献标签)
  id, name (unique), color, note

reference_tag_link                which literature carries which label
  reference_id → reference,       — the pair is the primary key and the
  tag_id → reference_tag          row holds nothing else

How the tables are named

Three rules, applied everywhere:

  1. A table is its module's name plus what it holds — template* belongs to the 模板 module, paper* to the 论文 module.
  2. A class is named after its table (TemplateTitle → template_title), so reading a class name tells you which table to look at.
  3. One concept, one word. The library entry, the placement and the paper's paragraph are three different things and never share a name.

The join table is a placement rather than a _link because it is not a bare link: it carries sort, the only place display order is stored, and it deliberately allows the same title twice in one template. Calling it a link would describe two foreign keys and hide the column the whole ordering rule rests on.

template_title and template_title_placement are one word apart on purpose — the first is the catalogue, the second is one use of it — and the earlier pair (template_field_library / template_field) hid that distinction behind a prefix that meant the opposite kind of thing. Revision b19e4d7a3c58 renamed them.

paper has no abstract column, and that is a decision rather than an omission. A paper's abstract is a paragraph of its body — the template's 0 Abstract field — so it has a position in the document, the heading and typography the template gives it, and the same sentence-by-sentence editing as every other paragraph. A column for it would be a second home for the same text, one the document never reads: a paper could show two different abstracts, and the one in the column could drift from the one in the body. Revision a83f5c21d7b6 removed it, moving each stored abstract into the abstract paragraph first.

The two template tables are one word apart and mean different things, which is what the names are for: template_title_placement is a placement — this template puts this title here, sort included — while template_title is the catalogue the title was picked from, shared by every template and owned by none. The library is managed from the 模板 menu, because it is the raw material a template is built out of.

The title library is flat, not a tree

template_title has no parent_id. Hierarchy is expressed only by level (1 for 1., 2 for 1.1), which is a rendering hint: it drives indentation and numbering semantics in the UI and nothing else.

The reason is reuse. With a parent pointer a level-2 heading would belong to exactly one level-1 heading, so "Background" could not sit under both 1. Introduction and 2. Related Work. Titles are attached to templates, not to each other, so one title can appear in any number of templates, in a different position in each.

The numbering a reader sees is part of name and is written by the user ("1. Introduction", "0 Abstract"). Nothing derives or rewrites it.

Display order lives in the placement table

template_title_placement.sort is a plain ascending integer and is the only thing that decides what order a template's titles appear in. The order the user clicked titles in is never stored, so selecting 标题1, 标题2.1, 标题2, 标题1.1 and setting sorts 1, 4, 3, 2 renders as 标题1, 标题1.1, 标题2, 标题2.1.

Two consequences are deliberate:

  • There is no unique constraint on (template_id, title_id). Placing the same title twice in one template is a legitimate layout — the same level-2 heading under two different level-1 headings. The UI warns about a repeat; it does not forbid one.
  • Ties are legal. Equal sort values are broken by insertion order, so the ordering is always total and stable. The UI warns about ties too, and offers a button that renumbers the selection 1..N.

Templates hold references, not copies

template_title_placement points at a library title; it does not snapshot its name or typography. Renaming or restyling a title therefore updates every template that places it, which is what makes "fix the template and the section names follow" work.

A sentence is addressed by position, not by field id

paper_sentence.paper_template_filed_sort holds the sort of the template placement the sentence belongs to — not template_title_placement.id, and not template_title.id. Together with sort, the sentence's own position inside that paragraph, it is everything needed to place a line of text.

The indirection is the feature. Two templates have no rows in common, but they can share a position, so a sentence that remembers "I sit at position 7" lands on whatever the new template puts at position 7 when the paper is switched. The alternative — pointing at a placement row — would make every sentence belong to one template and turn a switch into a re-mapping of every line.

Three behaviours fall out of that one choice:

  • The structure exists before the content. A paragraph is any position the template defines or any position a sentence occupies, so an unwritten paragraph still renders, empty, and a paper created a second ago already has its full shape.
  • A switch destroys nothing. Positions the new template does not define are still rendered, in their place in the order, under the heading 未设定. Switch back and the old headings return, because the sentences never moved.
  • Ties and gaps are fine. Sentences may share a sort (broken by id) and may be numbered 10, 20, 30 to leave room, exactly as template_title_placement.sort allows.

The name paper_template_filed_sort keeps the spelling the feature was specified with; it is the template field's sort (the sort column of template_title_placement). paper_sentence.template_id is the template the sentence was written against. It is kept in step with the paper's current template and is provenance rather than a lookup key: rendering never filters on it, which is precisely why content survives a switch.

The reference library holds literature, not citations

reference is the literature: one row per document the writer has read, and it is global — the same article is cited from several papers, so the entry cannot belong to one of them. The citation is a different fact — "this sentence quotes this passage" — and it lives on the paper side, in paper_sentence_reference, which carries the quote and the citation's order inside the sentence.

So the relation is many-to-many in both directions, through that table:

paper_sentence ──< paper_sentence_reference >── reference
                        (quote, sort)              (title, year, …)

Two questions follow from it, and each is answered from its own side: "what does this sentence quote?" is a lookup by sentence_id, and "where have I used this article?" is a lookup by reference_id (GET /references/{id}/citations). One column on paper_sentence could not express the first of those — it would cap a sentence at one citation — which is why the relation is a table rather than a foreign key.

Why these columns and no others

The field set is the intersection of the formats a paper has to survive:

Format What it decided
CSL JSON (csl-data.json: 103 fields, 45 types) the field names, and partial dates as year / month / day rather than one DATE
GB/T 7714-2015 every entry carries a type with its marker; patents need patent_country + patent_number, standards standard_number, online resources accessed_date
BibTeX / RIS citation_key, and the one-field-per-fact layout that makes an export a mapping rather than a parse

Contributors are a child table, not a column, and each row stores the printed name and its two halves. That is not duplication: a citation prints 「张三」, Zhang, S. or S. Zhang depending on the style, so the printed form is the authority for display and the halves are the authority for rewriting a name — and an institutional author (「世界卫生组织」) has no halves at all.

The 103 CSL fields include roles this project will never print (narrator, performer, curator) and archival fields (call-number, archive-place). They are left out on purpose; see :mod:app.models.reference.

Tags are the writer's filing, not the document's keywords

reference.keywords is a field of the document — the 关键词 printed on the article, transcribed because a citation record should be able to reproduce it. A tag is a fact about the writer: 「综述」, 「必读」, 「待精读」, the labels that narrow a library of a few hundred entries to the handful that matter for the paragraph being written. They never print, one document carries several, and the same label is on many documents. Two different facts with two different lifetimes cannot share a column, so labels live in their own two tables:

reference_tag       one label: name (unique), colour, note
reference_tag_link  reference_id + tag_id — the pair is the primary key

The link table is named _link and not _placement for the reason template_title_placement is not: it carries nothing of its own. There is no sort here, so the pair is the row — which also means the same label cannot be applied to the same document twice, and that is a property of the key rather than a rule anyone has to remember to enforce.

A tag is made first and applied second. A reference is created with tag_ids, never with tag names, so a typo cannot invent a label and two clients cannot create two spellings of one. An id the library does not have is refused with 400 naming it, and nothing is written.

Deleting a tag is not guarded, deliberately. Both foreign keys cascade, so removing a label removes labels and leaves the literature where it was. That is the opposite of deleting a cited reference, which is refused with 409: a citation is a claim the paper makes, while a label is only a way of finding the row again. The confirmation in the UI says how many entries will lose the label, which is the honest form of that warning.

A sentence is a line, not parsed text

Nothing in the writing path splits text. There is no sentence detector, no punctuation rules and no comma handling: one line in the editor is one sentence, and what the writer types is what is stored, minus runs of whitespace (leading, trailing, and any newline pasted inside a line, which fold to a single space so a sentence really is one line). Commas never break anything — the only place a comma separates anything in this project is the keyword field.

That is deliberate. A splitter that guesses wrong corrupts content, and the guess would have to be right for every abbreviation (et al., i.e.), every decimal (3.14), every numbered list and every language the tool is used in. The writer decides where a sentence ends; the software only decides what goes at the seam between two of them.

Exactly one split has ever been performed, in revision a83f5c21d7b6, to move the old paper.abstract column into the body. It cut after a Chinese full stop (。) and nothing else — deliberately conservative: an English abstract survives that migration as a single row rather than being cut at the first et al., and one long line is a line the writer can split by hand.

A line break is asked for, never guessed

A paragraph is its sentences run together — that is the model. Everything a paper also puts inside a paragraph that is not prose (a display formula, a list of items, an author line) therefore needs a way to say "start a new line here", and that is paper_sentence.line_break_before.

It is a flag rather than a newline inside content for two reasons. Content folds its whitespace, deliberately, so that a sentence really is one line and a pasted newline cannot split one in half; and a break buried in a string is a break nobody can see, count or remove. A flag prints a <br> and is visible in the editor as a checkbox on the sentence's row.

A break also replaces the separator rather than adding to it: the new line already separates the two sentences, and a space as well would indent the line by one blank.

The renderer groups a paragraph into printed lines to make that work. CSS can only indent the first line of a block, so a paragraph printed as one block indents its opening line and leaves every line the writer broke flush against the margin — which is exactly where a new paragraph should be indented. So each printed line is its own block, and the two-character first-line indent sits on the line rather than on the paragraph. A line after a display formula is the exception: that text continues the same paragraph, and a Chinese manuscript does not indent a continuation.

What goes at the seam

A paragraph is printed by concatenating its sentences in sort order, so the seam between two of them has to be spelled out: app.crud.paper.sentence_separator returns "" or a single space, and the document response carries it as SentenceRead.separator_before.

Seam Separator Why
……缺口。 + 本研究…… "" Chinese needs nothing; the full stop separates
First sentence. + Second. " " without it the two print as First sentence.Second.
缺口。 + This study " " mixed text takes the space
test. + 本研究…… " " same, in the other direction
anything + an empty sentence "" an empty line carries citations, not text

So the rule is about the seam rather than the language: a space goes in unless both sides are CJK, where adjacency is already the convention. It is derived on every read and never stored — a stored separator is one that can go stale against the text it separates — and a client prints separator_before + content and adds no spacing of its own.

separator_before was added because the alternative was already a bug: CJK sentences printed correctly by accident (the full stop hides the missing space), so nothing looked wrong until the first English paper, whose sentences would have run together.

An image is an object, and the sentence keeps only its address

Not everything in a paper is text, and the parts that are not do not get a table. The bytes of a 插图 live in MinIO (k3s, S3 protocol) and the sentence keeps the address, as Markdown:

试验装置如 ![行内示意图](/api/images/2026/09/9f8c1a4b7e2d0c33.png) 所示。
![试验装置示意图](/api/images/2026/09/9f8c1a4b7e2d0c33.png){width=70%}

A table was the obvious alternative — paper_image with a sort, a caption and a paragraph position — and it is wrong here, for the reason the sentence model already gives: a paragraph is reassembled from sentences ordered by one number, and a second table holding its own sort beside that one gives a paragraph two orderings that eventually disagree. Keeping the picture inside content means a figure moves between paragraphs by being cut and pasted, survives a template switch with the sentence it belongs to, and needs no new endpoint to write. The same argument that made citations a table (a citation carries data of its own, and is queried in both directions) is what keeps images out of one.

Three properties of the storage are deliberate:

  • The key is the digest of the picture. 2026/09/9f8c1a4b7e2d0c33.png is derived from the bytes, so uploading the same screenshot twice — from two paragraphs, or by accident — stores one object, and the address can never come to mean a different picture than the one it was written for. That is what makes the year-long immutable cache header safe to hand out.
  • The format is sniffed, never trusted. The declared content type and the filename are the uploader's claims; the magic bytes are the fact. PNG, JPEG, GIF and WebP are accepted — and SVG is not, because an uploaded SVG served from this origin is stored XSS, while the page already renders text the writer controls. The served content type comes from a whitelist on our side, with X-Content-Type-Options: nosniff.
  • The key space is also the access rule. GET /api/images/{key} serves keys of the shape this application writes and nothing else, so the read route cannot become a browser for the rest of the bucket, whatever else is in it.

Images are served through the API rather than from a public bucket URL so that a sentence never embeds a host name: the same paper is read from the LAN in development and from the public address later, and a hard-coded origin would break on the other. It also means the bucket stays private. The response streams the object out of MinIO rather than reading it into memory, and releases the connection when the reader stops.

Two rules decide how a picture prints, and both follow from "a sentence is a line":

What the sentence holds How it prints
nothing but ![图注](地址) a figure: its own line, centred, the brackets' text as 图注 underneath
an image inside a run of text inline, on the line with the words, height capped at 12em

The size is optional and comes from pandoc's attribute form — {width=70%}, {width=400px} — and is validated to digits plus one unit before it becomes a CSS length, so no second declaration can be smuggled through it. A bare number is a share of the column, because parseImageWidth only reads a value as pixels when it says px; the MCP tool that writes the same attribute follows that rule rather than inventing its own.

Leaving the size off means the picture prints at its own width, capped to the column — and that turned out to be the wrong default to live with. Figures come out of a plotting tool at whatever size they were made: one paper's are 1441, 1857, 2409 and 4169 pixels wide, so every one of them is wider than the 1276px column and they all printed at the full width, with the near-square ones (1857×1986, 1974×2068) filling a whole page at 1365px tall. A written size is therefore part of the editor: a row that is a figure carries a 宽度 control — presets, or any value typed in — and beside it what the picture will measure on the page (原图 1857×1986 · 显示 893×955), measured against the real column behind the dialog. The control writes the attribute through the reader's own parseImageWidth, so what it shows is what gets printed, and a value that function cannot read is refused instead of stored as a size that does nothing.

Configuration is three variables (MINIO_ENDPOINT, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, plus MINIO_BUCKET). Left empty, the paper still writes and reads: only the image routes answer 503, saying which variables are missing. The bucket is created on the first upload if it is not there.

Citations are a table, not a column

One sentence may quote several references, so paper_sentence_reference holds one row per citation. quote — 引用内容 — is required and must not be blank: a citation that does not say what it quotes is rejected with 422 rather than stored as a half-record. reference_id is a plain nullable integer with no foreign key, because the reference library does not exist yet; a citation may therefore be written now and linked later.

Foreign keys are declared, and this cluster enforces them

TiDB parses FOREIGN KEY for compatibility, and from v6.6 honours it when tidb_enable_foreign_key is on. On the cluster this project runs against it is on, so the constraints are real integrity rather than documentation: a dangling insert is rejected (1452) and ON DELETE CASCADE / SET NULL actually fire. Two consequences are worth knowing before touching a migration:

  • Tables must be created in dependency order, and a rename must be checked rather than assumed. RENAME TABLE does carry a referencing constraint along with the renamed table here (the rename in revision f27a1c6d9e04 was rehearsed against the cluster before it was written), but that is a property of the deployment, not of SQL.
  • The API still checks first. A database violation surfaces as a generic driver error, while the application refuses with a message that names the row and the count:
    • deleting a library field still placed in a template → 409, naming the field and how many templates use it;
    • deleting a template a paper is written against → 409, naming the template and how many papers use it — the template is that paper's structure, so removing it would empty the paper rather than tidy up;
    • creating a template that references a missing field → 400, and creating or patching a paper that references a missing template likewise.

The ORM cascades stay as well. Template.items, Paper.sentences and PaperSentence.citations use cascade="all, delete-orphan", so deleting a row 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.

Method Path Notes
GET /health liveness plus a TiDB probe
GET /template-titles keyword, level, page, page_size
POST /template-titles create a library entry
GET PATCH DELETE /template-titles/{id} read / partial update / delete
POST /template-titles/batch-delete body { "ids": [...] }
GET /templates keyword matches name or abstract
POST /templates name + abstract + ordered fields
GET PATCH DELETE /templates/{id} PATCH with fields replaces the selection
POST /templates/batch-delete body { "ids": [...] }
GET /papers keyword matches title/author/keywords, plus status, template_id
POST /papers title + template + author/status/keywords/journal; no sentence rows are created
GET PATCH DELETE /papers/{id} PATCH with template_id is the template switch
POST /papers/batch-delete body { "ids": [...] }
GET /references keyword (题名/刊名/作者/DOI/关键词/备注), type, year, cited, tag
POST /references the whole entry, authors in print order, tag_ids to label it
GET PATCH DELETE /references/{id} PATCH with authors or tag_ids replaces that list
POST /references/batch-delete body { "ids": [...] }
GET /references/{id}/citations which sentences cite it, and in which paragraph
GET /reference-tags keyword matches 标签名称 or 备注; each row carries its 文献数
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, 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
PATCH DELETE /papers/{id}/sentences/{id} edit or remove one sentence
POST /images multipart/form-data, one file field; answers key, url, ready-to-paste markdown, content_type, size, sha256
GET /images/{key} streams the picture; only keys this app wrote, cached immutable for a year

Conventions worth knowing:

  • font_color is stored and returned as canonical #RRGGBB. The API also accepts rgb(r, g, b), #rgb and bare aabbcc, and normalises them on write.
  • font_size is a JSON number, not a string — a client should not have to parse it before using it in a CSS rule.
  • List endpoints return { items, total, page, page_size, pages }.
  • A template read returns fields already ordered by sort; clients never sort.
  • Route paths mirror table names one for one: /templates for template, /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, 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 blank quote is refused with 422.
  • keywords is stored as a canonical , -joined string; ,、; and ; are accepted on write and de-duplicated.
  • Paper status is one of draft, writing, done.
  • A citation's reference_id is checked against the library: citing literature that does not exist is a 400 naming the ids, not a foreign-key error from the driver. A citation with no reference_id stays legal — a quote may be written before it is linked.
  • Deleting a reference a sentence cites is refused with 409, naming the entry and how many citations use it.
  • Applying a tag that does not exist is a 400 naming the ids, not a foreign-key error: the library is checked before the write, and a reference naming a label that is not there is refused whole rather than stored half-labelled.
  • Deleting a tag is not refused. The label rows go and the literature stays, because a label is the writer's filing rather than a claim the paper makes.
  • tag may be given more than once, and the filters narrow rather than widen: ?tag=1&tag=2 returns the rows carrying both labels, which is how the rail's labels compose with the toolbar's.
  • A DOI is stored without its https://doi.org/ prefix, so the column holds one spelling whichever way it was pasted.
  • An uploaded image is refused with 415 when its bytes are not PNG/JPEG/GIF/ WebP (SVG included), 413 when it is over MAX_IMAGE_BYTES (20 MiB) and 400 when it is empty. A key that has no object, or one this application did not write, is 404.
  • An image URL is relative (/api/images/…) and same-origin on purpose: the client prints it as it stands, and the paper does not name a host.

MCP server

The same domain layer is also served over the Model Context Protocol, so an agent — Claude Code, Codex, the DeepSeek Harness — can write a paper without a browser. Full manual: docs/MCP.md.

It is a third front door rather than a second implementation. The REST routes, the MCP tools and the seed script all call app.crud and all validate through app.schemas, so a rule fixed in the CRUD layer is fixed everywhere and a paper written by an agent is indistinguishable from one written by hand. What app/mcp/ adds is only what a model needs and a browser does not:

Addition Why the REST shape is wrong for a model
42 tools with paper_ / paragraph_ / sentence_ / template_ / field_ / reference_ / reference_tag_ / image_ prefixes a model picks a tool out of a list by its name, not by reading 42 descriptions
JSON strings, None-free, no pagination envelope on reads a tool result is paid for in context tokens
paragraph_write addressed by heading as well as position nobody writing "1. Introduction" knows the template places it at sort = 20
paper_write / paper_write_text "generate the paper, then put it in" is one intention, not thirty round trips
paper_delete refuses once before it deletes a cascading delete has no undo in a tool call
sentence_search across papers the job is consistency — one paper says 洪水损失, the next must not say GUL
reference_* and reference_tag_* the reference library is what makes a citation mean something; an agent that can cite id 42 but cannot look up what 42 is is writing blind
reference_import "here are the twenty references I cited" is one intention, and twenty round trips would spend twenty schemas on it
line_break_before on a sentence, and the display-formula and figure rules in document_text a paragraph is its sentences run together, so a formula, a list, an author line or a 插图 needs a way to say where the line starts — and the text an agent reads back has to break lines where the paper view breaks them, or the two disagree about what the manuscript looks like
image_upload taking base64 the upload route is multipart/form-data, which a model cannot send; it has bytes and a tool argument, and it gets back the same Markdown and the same sentence the editor would have written
the sentence's own columns read from SentenceInput rather than listed line_break_before and formula_align were each added to the domain, used by the editor and the API, and silently dropped by every MCP write path; the field set is now derived, and smoke_mcp.py fails if specs.py lags behind

Two transports are served from one build: stdio, which is what a client spawns, and streamable-http, which is what a client on another machine connects to (behind a bearer token). The package is split so that only app/mcp/server.py knows a transport exists:

app/mcp/
├── server.py      transports, CLI, health probes, the instructions sent at initialize
├── support.py     sessions, JSON shaping, heading resolution, the one text splitter
├── specs.py       the shapes a model may send (a paragraph, a sentence, a citation)
├── selfcheck.py   --check: connect once and print the tool surface
└── tools/         papers, paragraphs, sentences, templates, fields — registered
                   by register_all(), each tool three lines around an app.crud call

/healthz and /readyz exist for Kubernetes and are the only unauthenticated routes. They answer different questions on purpose: liveness touches nothing, so a database that is briefly unreachable cannot become a restart loop, while readiness runs SELECT 1 so the pod leaves the Service's endpoints while TiDB is down and rejoins when it is not.

Two shape decisions are worth knowing before adding a tool. A nested argument model keeps model_fields_set, which a flattened signature cannot: 38 bibliographic fields spread across keyword parameters would arrive with the omitted ones indistinguishable from explicit nulls, so reference_update takes its changes as one object and forwards only the keys the caller actually wrote. And a domain refusal belongs in DOMAIN_REFUSALS in tools/registry.py on the day it is written — UnknownReference was translated there when the reference tools were still to come, and the tag rules (UnknownTag, DuplicateTagName) had to be added when those tools landed, because an unlisted refusal reaches the model as Error executing tool … and says nothing about what to fix.

Two more decisions are worth knowing. Results are registered with structured_output=False: inferred from a -> str annotation, the SDK publishes a {"result": …} envelope and sends the JSON twice, once as structuredContent and once as text, and clients that read only one of the two then disagree about what the tool returned. And the docstring is the tool description verbatim, sent with every request — so a tool docstring is one or two lines and the reasoning goes in the module docstring, where it costs nothing.

Frontend

Shell

┌───────────────────────────┬──────────────────────────────────────┐
│ [mark] paper-doc          │  论文  模板  参考文献           [mk] │  header
├───────────────────────────┼──────────────────────────────────────┤
│  论文                     │                                      │  second-level
│   论文列表                │  <RouterView>                        │  menu, left
│   新建论文                │                                      │
│   ── 我的论文 ──          │                                      │
│   ● 论文标题 A            │                                      │
│   ● 论文标题 B            │                                      │
└───────────────────────────┴──────────────────────────────────────┘
             <- 208px ->

The mark appears at both ends of the header. The three top-level entries are the two surfaces a paper is worked in — 论文 and 模板 — and, marked out to their right, 参考文献: the library is drawn from rather than worked in, so it is a button one step away instead of a third thing to choose between (§ the rail lists what is in it).

The second-level menu sits on the left and is driven by route.meta.section, so a route declares which menu it belongs to and deep links render correctly on first paint. Routes without a section (the welcome page) show no menu.

Two menus are not static lists, and both carry real data rather than links. 论文 lists the papers themselves, read from the papers store, so a paper can be opened straight from the rail. 参考文献 lists the tags, read from the referenceTags store, so a label can be picked straight from the rail — and because both are driven by their stores, every page that creates, renames or deletes one reloads it, which is what keeps the rail and the table showing the same thing. Each rail grows a filter box once its list passes six entries.

A tag in the rail links to /references?tag=<id>, which makes the query parameter part of the view rather than a hidden filter state: SectionAside highlights that entry by matching the parameter, and the table's own tag selector writes the same parameter back.

Two things about this layout are deliberate and easy to break by accident:

  • Which side the menu lands on follows from its DOM order inside the flex row in App.vue — first child, left. Moving it is a one-block change there, not a stylesheet override.
  • The logo block is exactly as wide as the rail. Both read asideWidth() from src/layout.ts, so they cannot drift apart, and collapsing the rail narrows the logo block with it (dropping the wordmark and centring the mark). The header's own padding is zeroed for this; the two insets come from ASIDE_INSET so the mark lines up with the section title below it.

The column also carries through to the content: the rail is 208px and both the top nav's first item and .el-main are inset a further 20px by their own Element Plus defaults, so the menu text, the page body, and the page header all start on the same vertical line.

Shell metrics

src/layout.ts is the single source for the rail's width and inset. It is a module rather than CSS custom properties because el-aside takes its width through a prop, which would otherwise fight an inline style coming from the stylesheet.

List pages fill the window

A table is the page. Left alone it is as tall as its rows, so on a large screen most of the window sits empty below the last row while the page is still the thing that scrolls — the wrong half of the screen moving for a list that should simply show more. The five list pages (/papers, /templates/list, /templates/fields, /references, /references/tags) therefore stretch the table to the height the window offers, with the toolbar above it and the pagination below it staying put while the rows scroll inside the table.

It is CSS only — no resize listener, no measured pixel height, nothing to go stale when the rail collapses or the window changes. Four links carry it, and each one is load-bearing:

Piece Why
.page--fill min-height: 100% of the content area — a floor that still grows
.card--fill makes the card a column so its body can pass the height down
.card--fill > .el-card__body a column with min-height: 0, without which a flex child refuses to shrink below its content
.table-fill + height="100%" flex: 1 1 0 so the table takes the leftover height instead of claiming its content height as its basis; Element Plus then pins the header and scrolls the rows

Measured in a real browser at three window sizes, with rows to scroll and with none:

Window Table Page scroll Rows scroll Empty state
1920x1080 781px none 519px inside centred, 741px
1440x900 601px none 699px inside centred, 561px
1280x620 321px none 979px inside centred, 281px

.table-fill keeps a 240px floor. Below it — a 1280x420 window — the table stops shrinking, the page grows past the viewport and the content area scrolls, which is the pre-existing behaviour rather than a squashed table. Pages that are not lists (the paper document) keep scrolling normally.

Routes

Path View Section
/ welcome —
/papers paper table + CRUD (?new=1 opens the create dialog) papers
/papers/:id one paper, read as a document papers
/templates redirects to /templates/list —
/templates/list template table + CRUD templates
/templates/fields title library + CRUD (the UI label is 字段管理) templates
/references reference table + CRUD (?tag=<id> filters, ?new=1 opens the create dialog) references
/references/tags tag library + CRUD (the UI label is 标签管理) references

Sentences are stored as LaTeX and typeset on read

A formula is stored exactly as the writer typed it — $\ell$, $$ … \tag{1} $$ — because that is the form that can be edited; an equation image cannot be changed by one character. The same is true of a picture: the sentence keeps the Markdown that points at it. Typesetting happens when the paper is read, in src/utils/rich.ts, which splits a sentence into text, formulas and images, hands the formulas to KaTeX and escapes everything else.

Four delimiters are recognised, because a writer's habit decides which they use: $$…$$ and \[…\] for display, $…$ and \(…\) for inline. An unmatched $ is left alone rather than swallowing the rest of the paragraph.

Four rules are worth knowing when reading the renderer:

  • A display formula is a block. It takes its own line whether or not the sentence asked for a break, because that is what "display" means.
  • It is centred, and its number is at the right margin. \tag{1} prints the number against the right edge of the block while the formula stays centred — the layout every numbered style uses. paper_sentence.formula_align moves the formula (left / center / right), never the number, and it is a per-sentence field rather than a template-field setting: one paragraph legitimately mixes a centred equation with a right-aligned continuation, and a field describes a heading, not a formula.
  • A text-align on .katex is a trap. KaTeX centres a display formula in that very element, so a well-meant text-align: left in the paragraph's stylesheet overrides it and every formula in the paper sits against the left margin with only its number at the right. That is exactly what happened here; the rule now carries only a font size.
  • KaTeX never throws. throwOnError: false renders a formula it cannot read as its own source in red, so one typo shows itself instead of blanking the paragraph the writer is looking at. Text segments are escaped before they go through v-html, and KaTeX runs with trust off, so a sentence cannot inject markup.

An image is the one thing the renderer does not build inside that HTML string. A figure is printed by PaperParagraph as a real <img> — so it can carry the writer's size and be opened at full resolution by a click — and figureOf() decides whether a sentence is a figure: it is one when the sentence holds nothing but a picture and whitespace. The reader's click is handled once, on the paragraph body, because inline pictures arrive through v-html, where no listener can be bound to them from a template.

The paper view

PapersView is the library; papers/PaperDetailView is the writing surface. The detail view renders the server's document verbatim and adds three things it 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, 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 document in one write.

Changing a paper's template from the metadata form is deliberately disabled: a silent re-shape of the document is exactly what the preview exists to prevent.

The reference library view

references/ReferenceListView is the library and references/TagManageView is the label library beside it. Three things about the pair are decisions rather than layout:

  • The tag filter lives in the URL. The rail links to /references?tag=<id> and the toolbar's selector writes the same parameter back, so the two cannot disagree about which label is being looked at, the rail can highlight it, and a filtered view is a link someone can be sent. The page reads route.query.tag, which is why the filter survives a refresh and a back-navigation.
  • The citation count is a door. "Which of my sentences use this?" is the question that decides whether an entry is safe to delete, and the count in the row opens the answer (ReferenceCitationsDialog: the paper, the paragraph heading, the sentence, and the quoted passage) rather than being a number to interpret.
  • A tag is created before it is applied. The form's picker offers the labels that exist and allows a new name to be typed; that name is created through the tag API before the reference is written, so no stored reference can point at a label that is not there. The dialog says so, and links to 标签管理 for anyone who would rather file first and tag second — which is the intended order.

The form itself is grouped by tab (基本信息 / 责任者 / 出版信息 / 标识与链接 / 摘要与备注) rather than listed flat: the field set is the union of what CSL, GB/T 7714 and BibTeX need, and forty inputs in a column is a form nobody fills in correctly.

Directory Structure

paper-doc/
├── backend/                 # FastAPI application
│   ├── app/
│   │   ├── api/routes/      # route handlers (health, images, 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 the object store (MinIO) the
│   │   │                    #   images a paper embeds are kept in
│   │   ├── crud/            # data-access helpers
│   │   ├── db/              # engine, session, declarative base
│   │   ├── mcp/             # MCP server: tools, specs, transports, self-check
│   │   ├── models/          # SQLAlchemy models
│   │   └── schemas/         # Pydantic request/response models
│   ├── alembic/             # migration environment and revisions
│   ├── scripts/seed.py      # idempotent seed for the title library + templates
│   ├── 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/smoke_images.py  # end-to-end check of upload, serve and refusal
│   ├── scripts/check_citation_styles.py  # the formatter, one entry per type
│   │                                #   (no server, no database)
│   ├── scripts/check_storage.py  # the image rules: formats, keys, refusals
│   │                                #   (no server, no bucket)
│   ├── 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
│   ├── requirements.txt
│   └── .env.example
├── frontend/                # Vue 3 SPA
│   ├── scripts/check-image.mjs  # the browser check: does a figure draw?
│   ├── src/
│   │   ├── api/             # axios instance and endpoint modules
│   │   ├── components/      # shell, field, template, paper and reference
│   │   │                    #   components
│   │   ├── router/          # vue-router configuration
│   │   ├── stores/          # pinia stores (UI prefs persisted, the paper and
│   │   │                    #   tag lists not)
│   │   ├── styles/          # global reset and the shell viewport contract
│   │   ├── utils/           # formatting helpers, and rich.ts — the reader for
│   │   │                    #   a sentence's LaTeX and its images
│   │   └── views/           # route-level components (papers/, references/,
│   │                        #   templates/)
│   ├── package.json
│   └── vite.config.ts
├── deploy/                  # packaging and the k3s manifests
│   ├── build-mcp-image.sh   # build + push the image from a DinD pod
│   ├── k8s/                 # namespace, ConfigMap, Deployment, Service
│   └── README.md
└── docs/                    # project documentation
    ├── OVERVIEW.md
    └── MCP.md               # the MCP manual: tools, workflows, client configs

Getting Started

Prerequisites

  • Python 3.10+ with venv
  • Node.js 18+ with pnpm
  • Network access to the TiDB instance (local development uses the NodePort)
  • Optional: a MinIO (or any S3-compatible) endpoint, for the images a paper embeds. Without one, everything still works except uploading pictures.

Backend

cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env          # then fill in the database credentials, and the
                              # MINIO_* ones if the paper is to hold images
uvicorn app.main:app --reload --port 8000

API docs are then served at http://127.0.0.1:8000/docs.

Frontend

cd frontend
pnpm install
pnpm dev

The SPA is served at http://127.0.0.1:5173 and proxies /api to the backend on port 8000.

Database

The paper_doc database is created once, out of band, against TiDB. Schema changes are applied through Alembic:

cd backend
alembic upgrade head

Object storage

The images a paper embeds live in MinIO, deployed in the same k3s cluster (namespace minio, manifests in /opt/kubectl/minio/): the S3 API on NodePort 30090, the console on 30091. From inside the cluster the Service is http://minio.minio.svc.cluster.local:9000.

# backend/.env — never committed
MINIO_ENDPOINT=http://192.168.1.88:30090
MINIO_ACCESS_KEY=…            # a dedicated key, not the MinIO root account
MINIO_SECRET_KEY=…
MINIO_BUCKET=paper-images     # created on the first upload if it is absent

The bucket stays private. Nothing is made public to display a figure: the API streams the object out of the bucket on /api/images/{key}, which is both what keeps the paper's addresses portable and what keeps the bucket from being a second, unauthenticated way into the deployment.

A key scoped to objects alone (PutObject / GetObject, no ListBucket) is enough, and is the better choice: the upload tolerates the 403 that such a key gets when it checks whether the bucket exists, rather than mistaking it for a missing bucket.

Seed data

scripts/seed.py fills the title library with a standard academic outline (20 fields, from 0 Abstract to 7 References) and creates three starter templates. It matches fields and templates by name, so running it twice adds nothing:

cd backend
.venv/bin/python scripts/seed.py            # add anything missing
.venv/bin/python scripts/seed.py --reset    # empty the tables first

Checking the reference library end to end

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, 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:

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:

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 — create a paper on a template, verify the empty structure, fill a paragraph with sentences and citations, switch the template, check that unmatched positions survive under an unset heading, move a paragraph, and delete it all again. It exits non-zero on the first failed expectation and cleans up after itself:

cd backend
.venv/bin/python scripts/smoke_papers.py

Checking images

Three scripts, because the feature has three layers that fail differently. scripts/check_storage.py needs nothing running: it replaces boto3's client with a stub and checks the rules that decide what may be stored and served at all — the format sniffed from the magic bytes (and SVG refused), the key pattern that the read route will serve and nothing outside it, the Markdown a caption may not break out of, what is asked of MinIO on a write, and that a key which is not allowed to look at the bucket still works.

cd backend
.venv/bin/python scripts/check_storage.py      # no server, no bucket
.venv/bin/python scripts/smoke_images.py       # against a running API + MinIO

scripts/smoke_images.py is the end-to-end one: it uploads each accepted format, fetches every one back byte for byte, checks the refusals (415 for text, an SVG and a mislabelled file, 400 for an empty one, 404 for a key this application never wrote), proves the same bytes are stored once, and writes a sentence holding a figure through the paper endpoints to show the Markdown survives them unchanged. Nothing needs cleaning up afterwards, and that is itself the property under test — a key is the digest of its picture, so a second run stores the same objects rather than more copies of them.

The third layer is the page, and it is the one neither of the other two can reach: bytes can be stored and returned perfectly while the <img> shows nothing. frontend/scripts/check-image.mjs therefore measures what the browser did — that the picture decoded (naturalWidth), that a figure took a line of its own and is centred on the column, that {width=50%} came out at exactly half the column, that the 图注 prints under the picture, that an image inside a sentence stayed in that line, and that the editor's 「插入图片」 button ends with the picture in the paper after saving. It needs Playwright, which is not a dependency of the app:

cd frontend
pnpm add -D playwright && npx playwright install chromium
pnpm check:image
# or point at an install that lives elsewhere
PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs pnpm check:image

It creates a throwaway paper for the run and deletes it, so it can be pointed at a database that holds real work.

Checking the MCP server

scripts/mcp_server.py --check connects to the database once and prints the tool surface, which is the failure this catches: a client that spawned the server successfully and then sees every call fail. scripts/smoke_mcp.py drives the whole writing loop through a real MCP client — the same child process and JSON-RPC over stdin/stdout that Claude Code, Codex and the Harness use — and runs unchanged against --url for the HTTP transport:

cd backend
.venv/bin/python scripts/mcp_server.py --check
.venv/bin/python scripts/smoke_mcp.py

Deployment

The MCP server runs in k3s in the paper-doc namespace and is reached at http://192.168.1.88:30931/mcp, behind a bearer token. There is no container runtime on this host — k3s runs containerd, and neither ctr nor crictl builds from a Dockerfile — so deploy/build-mcp-image.sh builds inside a throwaway privileged docker-in-docker pod, with the working tree mounted in through a hostPath so the build context is what you are actually looking at. The database is the in-cluster TiDB Service (tidb-tidb.tidb:4000), not the NodePort the host uses, and the object store is the in-cluster MinIO Service (minio.minio.svc.cluster.local:9000) rather than the host's :30090 — the same bucket either way, and neither address changes when the node's does. deploy/README.md has the commands, the two traps worth knowing (a reused image tag silently keeps the cached image; COPY carries the working tree's 0600 file mode into the image and a non-root container then cannot read its own code), and how to add the REST API to the same namespace.