A least-privilege key — PutObject / GetObject and no ListBucket — gets a 403
from HeadBucket, and reading that as "the bucket is missing" turned a working
key into a 503. The bucket may well be there and simply not be the key's
business, so a refusal to look at it is no longer a failure; the PUT that
follows is the honest test.
`scripts/check_storage.py` covers what a smoke test cannot, because these are
the rules whose failure is silent: the format read from the magic bytes rather
than the client's word, the key pattern the read route serves and nothing
outside it, a caption that cannot break out of the Markdown it is written into,
what is actually asked of MinIO on a write, and the refusals — unconfigured
storage, a key we never wrote, an object that is gone. boto3's client is a stub,
so it needs no credentials, no bucket and no network.
`frontend/scripts/check-image.mjs` is the third layer: bytes can be stored and
returned perfectly while the `<img>` draws nothing. It builds its own PNG
fixture, drives the page and measures what the browser did — the picture
decoded, the figure is centred on the column, `{width=50%}` is half the column,
the 图注 prints under the picture, an image inside a sentence stays inline, and
「插入图片」 ends with the picture in the paper. Run with `pnpm check:image`; it
needs Playwright, which stays out of the app's dependencies.
59 KiB
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 clientvue-router— client-side routingpinia+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 NodePort192.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:
- A table is its module's name plus what it holds —
template*belongs to the 模板 module,paper*to the 论文 module. - A class is named after its table (
TemplateTitle→template_title), so reading a class name tells you which table to look at. - 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
sortvalues 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 selection1..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 byid) and may be numbered10, 20, 30to leave room, exactly astemplate_title_placement.sortallows.
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:
试验装置如  所示。
{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.pngis 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-longimmutablecache 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.
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 TABLEdoes carry a referencing constraint along with the renamed table here (the rename in revisionf27a1c6d9e04was 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.
- deleting a library field still placed in a template →
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
textverbatim. 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_coloris stored and returned as canonical#RRGGBB. The API also acceptsrgb(r, g, b),#rgband bareaabbcc, and normalises them on write.font_sizeis 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
fieldsalready ordered bysort; clients never sort. - Route paths mirror table names one for one:
/templatesfortemplate,/template-titlesfortemplate_title,/papersforpaper. - A paper document returns its
paragraphsin ascending position order, already carrying their sentences and citation numbering, and itsreferencesas formatted entries. The client sorts nothing, merges nothing and formats nothing: two implementations of the same rule would eventually disagree. - A citation's
indexis the number of its work, so 86 citations to 65 works produce 65 entries and repeated numbers incitations— see 「The 参考文献 list is one entry per work」 above. - A document's
reference_stylenames the style the entries were written in (springer), so a client can label the block without hard-coding the choice. - Sentence
contentis 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 blankquoteis refused with422. keywordsis stored as a canonical,-joined string;,、;and;are accepted on write and de-duplicated.- Paper
statusis one ofdraft,writing,done. - A citation's
reference_idis checked against the library: citing literature that does not exist is a400naming the ids, not a foreign-key error from the driver. A citation with noreference_idstays 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
400naming 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.
tagmay be given more than once, and the filters narrow rather than widen:?tag=1&tag=2returns 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
415when its bytes are not PNG/JPEG/GIF/ WebP (SVG included),413when it is overMAX_IMAGE_BYTES(20 MiB) and400when it is empty. A key that has no object, or one this application did not write, is404. - 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 |
|---|---|
41 tools with paper_ / paragraph_ / sentence_ / template_ / field_ / reference_ / reference_tag_ prefixes |
a model picks a tool out of a list by its name, not by reading 41 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 rule in document_text |
a paragraph is its sentences run together, so a formula, a list or an author line 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 |
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()fromsrc/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 fromASIDE_INSETso 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_alignmoves 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-alignon.katexis a trap. KaTeX centres a display formula in that very element, so a well-meanttext-align: leftin 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: falserenders 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 throughv-html, and KaTeX runs withtrustoff, 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 readsroute.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. 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.