Commit Graph

17 Commits

Author SHA1 Message Date
govin 960450f744 frontend: typeset the LaTeX, and let a sentence start a new line
Two things a paper needs that the paragraph model could not express.

**Formulas.** A sentence stores the LaTeX the writer typed — `$\ell$`,
`$$ … \tag{1} $$` — because that is the editable form, and it was being printed
as source. `src/utils/math.ts` now splits a sentence into text and formulas,
gives the formulas to KaTeX and escapes everything else; `math-error` in red
when KaTeX cannot read one, rather than an exception that blanks the paragraph
(the paper in the database has 106 sentences with formulas, 29 of them
display). Four delimiters are recognised — `$$…$$`, `\[…\]`, `$…$`, `\(…\)` —
and an unmatched `$` is left alone instead of swallowing the rest of the
paragraph. A display formula is a block, so it takes its own line and centres
itself without any flagging; text goes through `v-html` escaped, and KaTeX runs
with trust off.

**Line breaks.** A paragraph is its sentences run together, which is right for
prose and wrong for a display formula, a list of items or an author line.
`paper_sentence.line_break_before` is that request: a flag rather than a
newline inside `content`, because content folds its whitespace on purpose (a
sentence really is one line) and because a break hidden in a string is one
nobody can see or remove. It prints a `<br>`, it is a checkbox on the
sentence's row in the editor, and it *replaces* the separator rather than
adding to it — the new line already separates, and a space as well would indent
the line by a blank.

Verified against the real paper in the browser: 214 inline formulas and 29
display formulas typeset with zero failures and no `$$` left on the page; a
sentence flagged for a break lands on its own line while its neighbour stays
inline; the display formula centres on a line of its own and the sentence after
it starts below. 54 paper checks (2 new), 61 reference checks and 76 MCP checks
pass, with `vue-tsc` and the build clean.

Also: `.pnpm-store/` is ignored — pnpm put its content-addressed store in the
project root rather than the home directory.
2026-09-23 11:30:29 +08:00
govin b97aab6f30 docs: describe the citation styles and the per-work numbering
Records the decisions the 参考文献 list now rests on: a citation is a place in
the text and an entry is a work, so a paper with 86 citations to 65 works lists
65 entries; the entries are written by `app/citation_styles` and a client prints
them verbatim; a gap is reported through `missing` rather than quietly rendered
as a shorter entry.

Also documents `scripts/check_citation_styles.py` — the formatter is checked
with no server and no database, because a wrong branch prints something that
looks like a bibliography entry instead of failing loudly — and why the
reference smoke test now stamps a token into everything it creates.
2026-09-22 21:50:39 +08:00
govin 15955f552d backend: give the reference library the MCP tools it was missing, and fix the one that broke
The reference library landed with a full REST API and no MCP surface at all:
an agent could cite `reference_id: 42` — the citation is validated now — but
could not look up what 42 was, create it, or find out whether the library
already had it. That is the citation half of "generate the paper, then write it
in" missing, and it is the half an agent is worst at doing by hand.

Twelve tools, mirroring the REST surface plus one addition each way:

- `reference_*` — search, read, create, update, delete, plus
  `reference_import`, which takes a whole pasted bibliography in one call and
  reports what it skipped (an existing DOI or an identical title) and what it
  could not read, one bad entry at a time rather than losing the other nineteen;
  and `reference_citations`, which answers "what is this cited for" before a
  rename or a delete. `reference_list`'s keyword search across title, container,
  DOI and author names is the de-duplication path that `reference_import` uses.
- `reference_tag_*` — the five CRUD tools. Deleting a tag drops the labelling
  and leaves the literature, which is the opposite of what the field library
  needs and the same choice the REST route makes.

Two things had to be fixed to get here, both found by testing rather than
reading:

`template_list` was crashing. The rename that turned a heading into a title and
its use into a placement changed `TemplateListItem.field_count` to
`placement_count` and left the tool reading the old attribute, so the call died
with `Error executing tool template_list` — unreadable, and live in the
cluster. The suite passed 47 checks while this was broken because it never
called `template_list`: the uncovered tools were exactly the read-only ones, so
the write paths were all green and the browse path was not. The suite now
covers all 41 tools — 76 checks — and step 5 asserts the shape each read tool
returns, not merely that it returned.

`DOMAIN_REFUSALS` in the tool registry held one class, `UnknownReference`. The
tag rules arrived with the tag tools and raise two more, so 「标签不存在:9」 and
「标签「必读」已存在」 would have reached a model as `Error executing tool …`.
The tuple is now the list of every refusal a tool is expected to translate, and
a new one belongs in it on the day it is written.

`reference_update` takes its changes as one nested object rather than 38 keyword
parameters: a nested model keeps `model_fields_set`, so an omitted field stays
absent while an explicit null clears the column. Flattened, the two are
indistinguishable — every omitted field arrives as None — which is the same
problem `paper_update` solves by rebuilding its payload from what it was given.

Verified against the deployed service, not a local process: 76 checks pass over
the NodePort, then the same 76 over stdio and against a local HTTP server, and
the REST suite still passes its 55. The image is rebuilt as v4 and the
Deployment follows it, because `imagePullPolicy: IfNotPresent` means re-pushing
a tag the node already holds changes nothing.
2026-09-22 18:30:24 +08:00
govin a29badd362 docs: describe the tags, the library pages, and the way in
Ten tables now, and the two new ones are argued for where the other
schema decisions are: why a tag is not a keyword, why the link is bare,
why a tag is made before it is applied, and why deleting one is not
refused while deleting a cited reference is.

Also corrects the table count — the section claimed nine while listing
eight — and the shell diagram, which had a header with two entries and
named the wrong side for the second-level menu.
2026-09-22 17:55:23 +08:00
govin d7bb777264 backend: add the reference library (参考文献)
One table per document the writer has read, and one for its contributors:

    reference          id, type, title, subtitle, title_translated,
                       container_title, volume, issue, pages, publisher,
                       publisher_place, event_*, publication_year/month/day,
                       accessed_date, doi, isbn, issn, url, patent_*,
                       standard_number, report_number, arxiv_id, abstract,
                       keywords, note, citation_key, language
    reference_author   reference_id, sort, name, family_name, given_name, role

The field set is the intersection of the formats a paper has to survive, taken
from the CSL JSON schema (103 fields, 45 types — what Zotero, Mendeley and
Pandoc exchange) against GB/T 7714-2015, BibTeX and RIS. The mapping is on
`app.models.reference` rather than in a commit message, because the next person
to add a column needs it more than this one does. Three decisions worth naming:

* **Partial dates.** Year, month and day are separate nullable integers, which
  is CSL's `issued`: a book has a year, a newspaper article a day, a patent its
  公告日期, and nothing invents the rest.
* **Contributors are rows, not a column.** A citation prints an ordered list
  with 编 / 译 marks, and styles rewrite names (「张三」 / "Zhang, S." /
  "S. Zhang"), so the printed form and its two halves are stored separately —
  display reads `name`, a reformatting style reads the halves, and an
  institutional author has neither.
* **`volume` / `issue` / `pages` are strings.** Journals print `12(Suppl.)`,
  `S1` and `e12345`, and a citation reproduces what is printed.

The library is global: the same article is cited from several papers, so the
entry cannot belong to one of them. The citation stays on the paper side in
`paper_sentence_reference`, which now carries a real foreign key to `reference`
(`ON DELETE RESTRICT`) — the column had been a loose integer waiting for this
table. A sentence may quote several documents and a document may be quoted by
many sentences, which is why the relation is a table and not a column on
`paper_sentence`.

Refusals are raised once, in the data layer, as `UnknownReference`, and
translated where each caller speaks: `400` with the offending ids for REST (one
exception handler, no route carries the check), a readable tool error for MCP
(one wrapper in the tool registry). Neither entry point can skip it, so the
foreign key never has to be the thing that complains.

API: `/references` CRUD plus batch delete, and `/references/{id}/citations` for
the reverse lookup — "where have I used this article?" — which is what tells a
writer whether an entry is safe to delete.

Verified: 29 new checks in `scripts/smoke_references.py` (partial dates, DOI
normalisation, author order and roles, search by author/type/year/cited, the
citation round trip, 400 on a phantom id, 409 on a cited entry), the paper
suite's 45 and the MCP suite's 47 still pass. The MCP suite now cites a real
entry instead of a phantom id, which is what an agent has to do now.
2026-09-22 17:13:32 +08:00
govin 199e328b48 refactor: call a heading a title, and its use a placement
`template_field_library` and `template_field` were one word apart and meant
opposite kinds of thing — a catalogue of rows versus one row — and neither name
said what a row actually is. Every row of the library is a **heading**: a piece
of text like 「1. Introduction」 with a level and typography, which is what the
reader sees at the top of a paragraph; and every row of the join table is that
heading *placed* in a template, `sort` included.

    template_field_library  -> template_title
    template_field          -> template_title_placement
    field_id (the column)   -> title_id
    TemplateFieldLibrary    -> TemplateTitle
    TemplateField           -> TemplateTitlePlacement

The join table keeps its own name rather than becoming `_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. `_link` would
describe two foreign keys and hide the column the ordering rule rests on.

Carried through every level, because a half-renamed layer is how the confusing
pair got there in the first place: HTTP paths (`/template-field-library` ->
`/template-titles`), the template payload (`fields`/`field_id` ->
`placements`/`title_id`, and `field_count` -> `placement_count`), the Pydantic
schemas, the CRUD modules, the seed script, the frontend API module and types,
and `docs/OVERVIEW.md`, which now states the naming rules outright.

Two deliberate exceptions:

* `paper_template_filed_sort` is untouched — it is a column of the paper module
  and is spelled as the feature was specified.
* The MCP tools keep their agent-facing names (`field_list`, `field_ids`, and
  the `fields`/`field_id` keys in their responses). Agents already call them by
  those names; the storage names they read underneath have changed.

The migration renames in place (data preserved: 4 templates, 45 titles, 63
placements) and is written to tolerate a database where part of it already ran,
which is not hypothetical — the first attempt renamed the tables and then failed
on the column, because Alembic's MySQL dialect wants an explicit type for
`alter_column` and will not rename a column without one. TiDB carries the
foreign key along with both the renamed table and the renamed column, rehearsed
against the cluster first, and it stays enforced.

Verified: seed re-runs clean, the paper smoke test's 45 checks and the MCP
smoke test's 47 pass, `vue-tsc` and the build are clean, and the UI was driven
in a headless browser through the template list, its preview drawer, the title
library page, the template form (which now posts `placements` with `title_id`)
and the paper document with no console errors.
2026-09-22 16:55:02 +08:00
govin 7e7820f823 deploy: run the MCP server in k3s under the paper-doc namespace
The server has to be reachable by the Harness, Claude Code and Codex, and all
three of those are clients of an address rather than of a source tree — a
stdio child process only serves whichever machine spawned it. So it is packaged
and deployed: namespace `paper-doc`, one Deployment, one NodePort Service at
`http://192.168.1.88:30931/mcp` behind a bearer token, talking to the
in-cluster TiDB Service rather than the node's NodePort.

The namespace is `paper-doc` and not `paper_doc`, which is not a preference:
a namespace name is an RFC 1123 label, underscores are outside that alphabet,
and the API server rejects it outright. The database keeps its underscore.

Two routes were added to the server for the deployment, and they are the only
unauthenticated ones. `/healthz` answers "is this process alive" without
touching anything, `/readyz` answers "can it serve" by running `SELECT 1`. The
split is the point: a failing readiness probe takes the pod out of the
Service's endpoints and puts it back when TiDB returns, while a failing
liveness probe kills a process that was working correctly.

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, mounting the working
tree through a hostPath so the build context is the tree you are looking at,
uncommitted edits included. It reads the registry credentials out of the
cluster's own pull secret, so no password is in the script or in a shell
history. One Dockerfile serves both entry points, because the API and the MCP
server share the domain layer and differ by one argv.

Verified against the deployed Service, not against a local process: 47 MCP
checks pass over the NodePort, and the Node MCP SDK — the one the Harness's
mcp-client plugin uses — lists all 29 tools and calls them. The same 47 pass in
stdio and against a local HTTP server, and the REST suite still passes its 45.
2026-09-21 00:08:17 +08:00
govin 5a6461eeec docs: describe the MCP surface and how to connect a client
`docs/MCP.md` is the manual a person needs to put this in front of an agent:
the 29 tools with their arguments, the workflow ("generate, then write it in"
in one call, versus paragraph by paragraph), the error contract, and the exact
configuration for the three clients in play — the Harness's
`cordis.patch.yml`, Claude Code's `claude mcp add` and `.mcp.json`, and Codex's
`config.toml` — including the note that a new Harness entry has to sit inside
the `insert:` list or it is silently treated as an override of an entry that
does not exist.

`overview.md` gains the section that belongs in a design document rather than a
manual: why the MCP surface is shaped differently from the REST one, and the
two rules a new tool has to follow — keep the docstring to a line or two,
because it is sent with every request, and register with
`structured_output=False`, because the inferred envelope sends the same JSON
twice and clients disagree about which copy counts.
2026-09-19 00:01:47 +08:00
govin e582198cc8 backend: decide the seam between sentences instead of gluing them
A paragraph is its sentences concatenated. Nothing was put between them, which
is right for Chinese — 「。」 already separates — and wrong for English, where
`Adaptive capacity rises.` followed by `Relocation follows.` printed as
`...rises.Relocation...`: a sentence boundary the reader cannot see. CJK output
hid it, so it would have surfaced as an English bug later rather than now.

`sentence_separator` now returns "" or a single space per seam, and the document
carries it as `SentenceRead.separator_before`. The rule is about the seam, not
the language: a space goes in unless both sides are CJK. Mixed seams take the
space. Empty sentences take none. It is derived on every read and never stored,
so it cannot drift from the text, and the client prints `separator_before +
content` and adds no spacing of its own.

No splitting was added anywhere, and none exists: a sentence is one line in the
editor and nothing parses it. The single split this project has ever performed
was the one-time move of the old abstract column, which cut after 「。」 only —
conservative on purpose, since an English abstract is better left in one row
than cut at the first `et al.`.

Five smoke checks cover the seam (Chinese, English, the assembled paragraph,
and that no separator is stored inside the content). 45 checks pass.
2026-09-18 19:01:31 +08:00
govin 45926af966 refactor: make the abstract a paragraph instead of a paper field
A template's abstract paragraph (`0 Abstract`) *is* the paper's abstract: it has
a position in the document, the heading and typography the template gives it,
and the same sentence-by-sentence editing as everything else. `paper.abstract`
was a second home for that text — one the document never reads, so a paper
could show two different abstracts and the column could drift from the body.

The column is gone, from the table, the model, the schemas, the API payloads,
the paper form, the list subtitle and the paper page. Nothing else changed.

The text already written into it is not gone. Revision a83f5c21d7b6 writes each
stored abstract into the paper's body first — one sentence per 。 at the
paragraph carrying the abstract heading, appended after anything already there
rather than replacing it. A template without such a heading keeps the text too,
one position above its first paragraph, where the document renders it under
未设定. Verified against the one paper that had an abstract: 450 characters in,
450 out, identical including `|J| ≤ α · I⁻ᵝ`, split into six sentences in the
`0 Abstract` paragraph, still with its own edit button.

The smoke test no longer assumes an empty database: it records the paper total
before it starts and compares against that, so it can run on a real one.
2026-09-18 18:55:10 +08:00
govin 61857c3ce1 frontend: let the list tables fill the window instead of their rows
A list page is a table with controls around it, and the table was as tall as
its rows: on a large screen most of the window sat empty below the last row
while the page stayed the thing that scrolled. The three list pages now stretch
the table to the height the window offers — the toolbar and the pagination stay
put and the rows scroll inside the table — and give the height back on a small
screen.

Pure CSS, no resize listener and no measured pixel height, so nothing goes
stale when the rail collapses or the window is resized. Four links carry it,
each load-bearing: `.page--fill` is `min-height: 100%` (a floor, not a cap),
`.card--fill` makes the card a column, its body gets `min-height: 0` so a flex
child may shrink below its content, and `.table-fill` is `flex: 1 1 0` so the
table takes the leftover height rather than claiming its content height as its
basis. Element Plus then pins the header and scrolls the rows.

Verified by rendering the pages in a headless browser at 1920x1080, 1440x900
and 1280x620: the table measures 781/601/321px, the page never scrolls, the
rows scroll inside it, header and body columns stay aligned to 0px through a
400px horizontal scroll, the pinned action column stays pinned, and the empty
state is centred in the full-height body rather than stranded at the top. A
1280x420 window hits the 240px floor and falls back to the page scrolling, and
the paper document page is untouched.
2026-09-18 18:26:52 +08:00
govin a5f884f440 refactor: prefix every table with its module
Two tables were named after the concept they came from rather than the module
they belong to, so the schema read as if the template tables were part of the
paper module. Renamed (data preserved, `RENAME TABLE` moves rows in place):

    paper_template  -> template                 the 模板 module
    section_field   -> template_field_library   the 字段库 the 模板 module owns

The paper tables and `template_field` already followed the rule. The rename
carries through everything that named a module:

  models   Template, TemplateField, TemplateFieldLibrary
  schemas  Template*, TemplateFieldLibrary*
  crud     app/crud/template.py, app/crud/template_field_library.py
  API      /template-field-library (was /section-fields); handlers are now
           named after library entries, which removes the ambiguity with
           TemplateField — a placement, a different thing entirely
  client   src/api/templateFieldLibrary.ts

`paper_template_filed_sort` is deliberately untouched: it is a column of the
paper module, spelled as the feature was specified.

TiDB v8.5 with tidb_enable_foreign_key on — as this cluster runs — enforces
foreign keys rather than ignoring them, so the docs' "TiDB does not enforce
foreign keys" was wrong. Corrected, with what actually follows from it: the
rename was rehearsed (RENAME TABLE carries a referencing constraint along), the
API keeps checking first so a violation names the row instead of surfacing a
driver error, and the ORM cascades stay so behaviour does not depend on a
cluster setting.

Revision f27a1c6d9e04 verified both ways; 40 smoke checks, type-check and build
all pass.
2026-09-18 17:48:11 +08:00
govin 2d113f9f6b docs: describe the paper authoring model, API, and views
Records the two decisions the paper feature rests on: a sentence is addressed
by the template placement's `sort` rather than by a row id, and citations are
a table rather than a column. Both explain behaviour that otherwise looks
arbitrary — why an empty paper already has its structure, why a template switch
destroys nothing, and why content with no matching heading is still rendered.

Also documents the new endpoints, the /papers/:id route, the paper view's three
jobs, and the smoke test.
2026-09-18 17:29:19 +08:00
govin 0d0aa20be2 frontend: make the logo block exactly as wide as the second-level menu
The logo block stopped wherever its text happened to end (~140px) while the
rail below it is 208px, so the left edge was a step rather than a column.

Both now read `asideWidth()` from src/layout.ts, so they cannot drift apart,
and collapsing the rail narrows the logo block with it — the wordmark is
dropped and the mark centres in the 56px strip. The block also carries the
rail's separator up through the header, so the column reads as one piece.

The header's own 20px padding had to go for this to work: the logo block has
to start at x=0 to be flush with the rail, so the nav and the right-hand mark
now own their insets. The mark's inset comes from the same `ASIDE_INSET` as
the rail's section title, so the two line up.

A side effect worth keeping: the rail is 208px and the top nav's first item
and .el-main are each inset a further 20px by their own Element Plus defaults,
so the nav text, the page body and the page header all start on one vertical
line.

The widths live in a module rather than CSS custom properties because el-aside
takes its width through a prop and would otherwise fight an inline style.
2026-09-18 16:43:30 +08:00
govin 4b826567b8 frontend: move the second-level menu to the left of the content
The rail was on the right. It now leads the row instead, so the section menu
reads as a conventional left-hand navigation column.

Which side it lands on was never a stylesheet decision: `.app-body` is a flex
row and the aside is simply its first child now, with `.app-main` after it.
The only style change that had to follow is the rail's separator, which moves
from its left edge to its right, plus the collapse tooltip's placement.

The global shell contract in base.css now says this explicitly, so the next
person to move the rail knows the side comes from DOM order rather than from a
rule in that file.
2026-09-18 16:35:24 +08:00
govin 9ded3bd574 docs: document the template domain model, API, and shell layout
Records the decisions that are not visible from the code alone:

  - why section_field has no parent_id, and what reuse that buys;
  - that template_field.sort is the single source of display order, and
    that repeats and ties are deliberately legal;
  - that templates reference library fields rather than copying them, which
    is what makes a rename propagate;
  - that TiDB parses FOREIGN KEY and ignores it, so the integrity lives in
    the application layer.

Also adds the API table, the frontend route table, and the seed script.
2026-09-18 16:10:48 +08:00
govin 4438b04ff1 docs: add docs/OVERVIEW.md and CLAUDE.md (init_project steps 2-4) 2026-09-17 12:44:54 +08:00