Commit Graph

3 Commits

Author SHA1 Message Date
govin 76708ce767 backend: print the 参考文献 list as a bibliography, one entry per work
The list was printing each citation's quote under a `引用 #53` tag: no authors,
no year, no pages, no DOI — the quoted passage where the entry should be — and
it numbered *citations*, so a paper with 86 citations to 65 works listed 21 of
them two or three times under different numbers. The same article was `[5]` in
one paragraph and `[17]` in another.

Two rules were wrong, so two are stated here:

**A work is numbered where the reader first meets it.** A citation is a place
in the text; an entry is a work. `citations` still has one row per place, and
each row now carries the number of its *work*, so the marker in the text, the
tooltip on it and the entry in the list are the same number. The document grew
a `references` list — the entries, in order — and `reference_style`, which
names the style that wrote them.

**How a reference prints is a property of a style, not of a citation.** The new
`app/citation_styles` package holds one module per style; `springer.py`
implements Springer's basic style, whose shape is
`Names: Title. <where it sits> (year). <identifier>` with a branch per document
type — a journal with its volume(issue) and pages, a book with publisher and
place, a chapter inside somebody else's book, a patent with its number, a page
whose URL is its source.

Three of its rules are decisions rather than transcription, and each is
documented where it applies: up to six contributors are named and more become
three plus `et al.`; a journal prints under its 刊名缩写 when the writer stored
one, because no algorithm abbreviates an arbitrary title correctly; and a CJK
name keeps its printed form even with halves filled in, because dotting 「三」
into an initial is wrong in Chinese and insufficient in English.

Nothing is invented to fill a gap. An entry says what it knows and reports the
rest as `missing` (「缺 责任者、出版年」), 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 rather than a library that needs attention.

`document_text` had the same bug in the MCP surface and now prints the entries,
with in-text markers taken from the document's numbering rather than from each
sentence's local position — which is what made the text an agent reads disagree
with the list under it.

`scripts/check_citation_styles.py` checks the formatter with no server and no
database: one reference of every type, and the exact entry the style calls for.
2026-09-22 21:50:27 +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 2aff867641 backend: serve the writing domain to agents as an MCP server
The paper is written by a model now. A browser is the wrong client for that:
the work is "generate the paper, then put it in", and doing it through a form
means a person retyping what a model already produced. So the same domain is
served over the Model Context Protocol, which Claude Code, Codex and the
DeepSeek Harness all speak.

It is a third front door, not a second implementation. Every tool is three
lines around an `app.crud` call and validates through `app.schemas`, exactly
as the REST routes do, so a rule fixed in the CRUD layer is fixed on both
surfaces 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:

- 29 tools, prefixed `paper_` `paragraph_` `sentence_` `template_` `field_`,
  because a model picks a tool out of a list by name rather than by reading 29
  descriptions;
- results as compact `None`-free JSON, since a tool result is paid for in
  context tokens and `PaperRead.model_dump()` carries four counts and two
  timestamps into every list row;
- paragraphs addressed by **heading** as well as by position. Storage is
  correct as it stands — a sentence remembers the position it sits at, which is
  what makes a template switch non-destructive — but nobody writing
  "1. Introduction" knows the template places it at `sort = 20`. The server
  translates, and refuses with the real heading list when it cannot, so a model
  that guessed wrong corrects itself in one retry;
- `paper_write` and `paper_write_text`: one intention, one call. The latter
  finds its own sections from Markdown headings or from lines that name a
  template heading, and reports every heading it could not place instead of
  writing half a paper;
- `sentence_search` across papers, for consistency rather than retrieval — a
  paper that says 洪水损失 should not be joined by one that says GUL;
- `paper_delete` refuses once, naming what would go with it. A cascading delete
  has no undo in a tool call.

Two transports, one build. `stdio` is what a client spawns — so nothing in the
process may print to stdout, and diagnostics go to stderr. `streamable-http` is
what a client on another machine connects to, optionally behind a bearer token;
binding a non-loopback address disables the SDK's DNS-rebinding allow-list,
because a LAN client sends whatever Host it knows the server by.

Tools register with `structured_output=False` on purpose: 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 came back.

`scripts/smoke_mcp.py` drives the whole loop through a real MCP client — the
child process and JSON-RPC over stdin/stdout a client actually uses — and runs
unchanged against a running HTTP server via `--url`. 47 checks pass on both
transports; the REST suite still passes its 45.
2026-09-19 00:01:43 +08:00