@fffangchenghao/dsh-latex-look 0.0.0-stage → 0.3.3

package/CASE-STUDY.md

@@ -0,0 +1,91 @@
+# Case study: a 215-page LaTeX book, read the way a reader reads it
+
+This is the document the tool was built against, and the only test that matters:
+**《神经网络与深度学习》中文版** (Michael Nielsen's *Neural Networks and Deep
+Learning*, Chinese translation) — 215 pages, 6 chapters, 3 appendices, 163 figures,
+129 numbered equations, a 63-entry table of contents, a glossary built with
+`glossaries`, and a great deal of mathematics.
+
+The document compiled with **zero errors** long before the work in this file
+started. Every defect below was invisible to the compiler and visible to a reader.
+
+## Why the test was run this way
+
+Two fixed roles, one file:
+
+- A **reader** who can only see the PDF. It gets page numbers, measures pixels,
+  and writes findings as sentences: *"印 52 最上面是图 3-1，章名被压到页面四分之一
+  处"*. It never sees `.tex`, never accepts "it looks fine to me", and does not
+  accept a fix it cannot verify on a re-rendered page.
+- An **editor** who may only change the source, and must prove each change on the
+  rendered page before reporting it.
+
+That split is what makes the numbers below meaningful: they are measurements taken
+by something that does not know what the source *intends*.
+
+## What was actually wrong
+
+| Symptom, as a reader said it | What it was | Pages |
+|---|---|---|
+| "the table of contents has lines sticking out past the margin" | `book.cls` sets `\@pnumwidth` to `1.55em`, too narrow for bold three-digit page numbers | all 63 TOC entries |
+| "the equation numbers are wrong, they say `(5)` instead of `(1-1)`" | 129 equations carried a hard-coded `\tag{N}`, which ignores any `\theequation` redefinition | 129 equations, 6 chapters |
+| "the chapter header says 第0章 on page viii" | the front matter sets `\chapter*`, but `\chaptermark` still ran | 1 page |
+| "there is a gap at the bottom, the text stopped early" | figures did not fit, so they moved to the next page and took the space with them | 9 pages, up to 170 mm |
+| "the figure numbers run backwards: 图 3-4 on p63, then 图 3-3 on p64" | converting an inline figure to a float makes LaTeX place it *after* the inline figures that follow it in the source | 3 runs |
+| "page 52 (a chapter opening) starts with a picture, the chapter title is a quarter down the page" | a float was allowed at the top of a chapter's first page | 1 page |
+
+## What the tool caught that a careful person missed
+
+**The floating–numbering interaction.** Making a figure a float to kill a page hole
+is obviously right, and it silently inverted figure numbers across a chapter,
+because LaTeX orders floats of the same class by source position among *floats*,
+not among inline figures. On a per-page diff, every page was fine. Only a
+reading-order pass over the whole document showed it:
+
+```
+图 3-4 on p63, then 图 3-3 on p64
+```
+
+`sequence` finds this; the fix is to float the entire numbered run, not one member
+of it.
+
+**Page furniture poisoning a whole-book measurement.** The first version of
+`audit` reported that all 215 pages ended 40 pt too early. The cause was that the
+running head, the head rule, and the page number are the *deepest ink* on a page
+in some pages and the *highest* in others; taking a percentile over the whole book
+made page numbers the reference. The fix is to detect furniture first — a row that
+recurs on a large share of pages within the outer 8 % band — and mask the whole
+band, not the individual rows.
+
+**A baseline that outlived its document.** Comparing against "the previous audit"
+is useless the moment the document repaginates: every finding moves, and everything
+reports as new. The audit matches findings by the **text at the break**, so a hole
+is still recognisably the same hole after the page numbers shift.
+
+## Final state
+
+Verified on the rendered PDF, not on the source:
+
+| Measurement | Result |
+|---|---|
+| Compile errors | 0 |
+| Pages | 215 (front matter i–ix, body 1–205) |
+| Overfull `\hbox` | 0 |
+| Numbered figures | 163 — contiguous 1..N in every chapter |
+| Figures out of reading order | 0 |
+| Numbered equations | 129 — `(1-1)` … `(6-1)`, contiguous per chapter |
+| Pages with >60 mm of unexplained white space | 19, all of them chapter ends or front matter |
+| The nine named holes | all ≤ 56 mm |
+| Chapter opening pages | all six start at exactly 17.0 % of page height |
+| Running heads | 197 of 215 pages (the rest are pages where a head is wrong) |
+
+## What this case proves — and what it does not
+
+It proves that an agent can be held to a *visual* acceptance bar on a document it
+cannot see as a whole, and that the failures above are the kind that survive
+compile-and-forget workflows.
+
+It does not prove the tool knows what your document should look like. Every fix
+came from a sentence a person wrote. The tool's job is to make "look at it and
+tell me whether it is right" cheap enough that a person can afford to say it ten
+times in a row.

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## 0.3.3
+
+- **Moved to a scope: `@fffangchenghao/dsh-latex-look`.** The flat name
+  `dsh-latex-look` is deprecated and kept only as a signpost. A scope makes the
+  owner visible at a glance and removes the squatting risk that an unscoped name
+  carries. Install with `target: @fffangchenghao/dsh-latex-look`.
+- The update check follows the new name; the plugin id (`dsh-latex-look`) does
+  not, because profile config and enable state key off it.
+
+## 0.3.2
+
+- **`--point` now says what is drawn there.** Asking "what is at (300,118)" on a
+  rule used to return `\end{document}`, because a rule drawn by `fancyhdr` has no
+  line of its own and inverse search returns the nearest box. The tool measures the
+  ink instead: it reports whether the point holds a rule, text or nothing, and when
+  the ink is a rule it either names the command that draws it
+  (`drawn by line 15: \rule{\linewidth}{0.4pt}`) or says plainly that no line of
+  the document draws it and the reader should look at `\pagestyle`/`\headrulewidth`.
+- Point lookups return the queried coordinates instead of `x=undefined y=undefined`,
+  and synctex's `/tmp/./main.tex` spellings are normalised.
+
+## 0.3.0
+
+Everything below came out of driving the tool against a real 215-page book
+(《神经网络与深度学习》中文版) for a reader who could only see the PDF.
+
+### Added
+
+- **`audit`** — measure every page in one `gs` pass and report only what the
+  current build broke, compared with the baseline the previous audit left
+  behind. Running heads, rules and page numbers are detected and excluded first,
+  or a page number becomes "the lowest ink in the book" and every page looks
+  broken. Findings are matched by the text at the break, not by page number, so
+  the comparison survives a repagination. When a page stops short and the next
+  page opens with a caption, the finding names that caption.
+- **`sequence`** — reading order of numbered labels (`图 1-1`, `Figure 3.2`).
+  Floating one member of a numbered run makes the numbers go backwards, and no
+  per-page diff can show it.
+- **Update check** — the plugin asks the npm registry once a day, in the
+  background, and appends one line to a tool reply when a newer release exists.
+  `latex-look --version` and `latex-look --check-update` for scripts.
+
+### Fixed
+
+- `pageTexts` returns one file per page: `txtwrite` does not reliably separate
+  pages with form feeds, so a single-file read reported every label on page 1.
+- Anonymous `@` names in a preamble rewrite (`\nndl@chapter`) break the compile;
+  the skill now says to use a plain name.
+
+### Skill
+
+- New playbook entries: a top float on a chapter opening page needs
+  `\suppressfloats[t]` in `\chapter`; a figure that becomes a float must be
+  floated together with its numbered run; floating moves a hole, it does not
+  remove it.
+
+## 0.2.0
+
+- `build` cache keyed on the document's source signature.
+- `locate` falls back to the PDF text layer when SyncTeX names the page a float
+  was built on.
+
+## 0.1.0
+
+- First release: compile, render, locate, diff.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fangchenghao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# latex-look — teach an agent to *see* your LaTeX
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@fffangchenghao%2Fdsh-latex-look?color=blue)](https://www.npmjs.com/package/@fffangchenghao/dsh-latex-look)
+[![tests](https://img.shields.io/badge/tests-smoke%20%2B%20scenarios-brightgreen)](test/)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**English** · [简体中文](README.zh-CN.md)
+
+![A page that compiles and still looks wrong, repaired in five edits](docs/before-after.png)
+
+*Left: compiles with zero errors. Right: after five sentences a reader could say out
+loud — "remove the rules around the title", "this table is a grid, make it a
+booktabs table", "that link runs off the page", "the figure is too wide". Try it
+yourself in [`examples/broken-layout`](examples/broken-layout).*
+
+A **DeepSeek Harness plugin** that adds exactly one tool: `latex_look`.
+
+An agent that only reads `.tex` source is blind: a document can compile with zero errors and still look wrong. `latex_look` compiles the document, renders the page as an image, maps any spot on that page back to the exact source line, and diffs what your last edit changed — in a single call.
+
+```
+        ┌─────────────┐   latex_look   ┌──────────────┐
+        │   agent     │ ─────────────► │  pdf → png   │
+        │ (edits .tex)│                │  synctex     │
+        └─────────────┘ ◄───────────── │  pixel diff  │
+              ▲          image + line  └──────────────┘
+              └─────────────── verification ───────────┘
+```
+
+**Read the case study:** [a 215-page LaTeX book, read the way a reader reads it](CASE-STUDY.md) — 163 figures, 129 equations, six classes of defect that compile cleanly.
+
+## Why one tool, not three
+
+Rendering, locating, and diffing are the *implementation*. The agent needs one coherent verb — **"look at this page"** — the same way a person does. `latex_look` compiles, renders, resolves, and diffs in a single call, so the loop is:
+
+```
+look → diagnose → edit .tex → look again → confirm the change → report
+```
+
+## Install
+
+Requires Node ≥ 18, a TeX engine (`xelatex`/`lualatex`/`pdflatex`/`latexmk` or tectonic), `synctex`, and `ghostscript`.
+
+This repository **is** the bundle: `package.json` declares `dsh.bundle.patch`, and `cordis.patch.yml` inserts one row.
+
+```bash
+git clone https://github.com/fangchenghao/latex-look
+```
+
+Then install it into the current profile (in the Harness, via the plugin manager):
+
+```
+plugin_manager  action: install_bundle  target: /absolute/path/to/latex-look
+```
+
+That adds the row `latex-look` and registers the `latex_look` tool. Replacing the sources of an already-installed package needs a Harness restart to load a fresh module generation.
+
+Published on npm as [`@fffangchenghao/dsh-latex-look`](https://www.npmjs.com/package/@fffangchenghao/dsh-latex-look), so the same row also installs straight from the registry:
+
+```
+plugin_manager  action: install_bundle  target: @fffangchenghao/dsh-latex-look
+```
+
+### Updating
+
+The plugin checks the registry **once a day, in the background**, and appends a single line to a tool reply when a newer release exists — no repeated nagging, and an offline machine sees nothing at all. To upgrade, install the same bundle again:
+
+```
+plugin_manager  action: install_bundle  target: @fffangchenghao/dsh-latex-look
+```
+
+On a live profile the upgrade applies immediately; the harness reloads the module generation on the next start, because `core.mjs` (unlike `index.js`) is not hot-reloaded.
+
+From a checkout, the check is available directly:
+
+```bash
+npx latex-look --version
+npx latex-look --check-update
+```
+
+### Releasing
+
+Tagging `v*` runs the test suite on Ubuntu with TeX and Ghostscript installed, verifies the tag matches `package.json`, and publishes to npm. The token comes from the `NPM_TOKEN` repository secret.
+
+### Optional: the knowledge skill
+
+The tool gives the agent eyes. [`SKILL.md`](SKILL.md) gives it the LaTeX knowledge to act on what it sees — a symptom → cause → fix playbook (a rule you want gone is usually `\pagestyle`/`fancyhdr`, not a stray `\hline`). Copy or symlink it into the skills root:
+
+```bash
+mkdir -p ~/.dsh/skills/latex-look
+ln -sf "$PWD/SKILL.md" ~/.dsh/skills/latex-look/SKILL.md
+```
+
+### CLI, for humans and for testing
+
+```bash
+node bin/latex-look.mjs book.tex --page 37
+node bin/latex-look.mjs book.tex --text "表3.1"
+node bin/latex-look.mjs book.tex --page 12 --compare previous --json
+node bin/latex-look.mjs book.tex --page 1 --audit   # what did the last edit break, anywhere?
+```
+
+The CLI runs the same engine as the plugin and needs no Harness, which makes it the fast way to check a change without reloading anything.
+
+## Tests
+
+Three suites run on a clean checkout — they create their own fixtures and compile
+real documents, so expect a few minutes:
+
+```bash
+node test/smoke.mjs           # unit level: problem parsing, PPM, raster diff, aux detection
+node test/scenarios.mjs       # 52 end-to-end cases driven through index.js
+node test/scenarios-deep.mjs  # 29 cases: multi-file papers, beamer, twocolumn, images,
+                              #   engine switching, the build cache, hostile inputs
+node test/book-scenarios.mjs  # 15 cases against a real 208-page book (164 .tex files)
+node test/book-tasks.mjs      # 18 real editing tasks on the same book (see below)
+LATEX_LOOK_BOOK=/pristine/copy node test/book-tasks.mjs   # point it at an unedited copy
+```
+
+The book suite needs a real book and is skipped unless you point it at one:
+
+```bash
+LATEX_LOOK_BOOK=/path/to/book node test/book-scenarios.mjs
+```
+
+These two suites matter most, because a real book is root → `\input{main}` →
+`\input{chap1}`, with a custom `.sty`, 181 figures, a glossary and `fancyhdr` page
+furniture.
+
+`book-scenarios` checks the machinery on that book. `book-tasks` checks the
+*requests*: each case is a sentence a user would say, applied to the copy and then
+verified the way an agent verifies it — look, diff against the previous build, and
+confirm the change is where the edit acts:
+
+| user says | measured |
+|---|---|
+| 把页眉那条横线去掉 | `0.09%`, bbox `y=52 h=1` (a thin band at the top) |
+| 页眉的线太细，加粗到 2pt | `0.27%`, bbox `y=52 h=3` |
+| 链接的蓝色去掉 | `0.29%`, bbox over the contents page |
+| 行距调大一点 | `10.53%`, 208 → 248 pages |
+| 表格行距加大 | `9.07%` |
+| chap2 那个总结框太窄，放宽 | `7.39%` |
+| chap1 那个图太小，放大 | `10.57%` |
+| chap4 那组图对齐时右边空着 | `8.81%` |
+| 段落首行不要缩进 | `14.07%` |
+| 页边距太窄 | `13.32%`, 208 → 226 pages |
+| 正文字号改成 12pt | `11.63%`, 208 → 226 pages |
+| 目录只显示到章 | `2.19%`, 208 → 207 pages |
+
+Nothing in these cases is asserted about how the change *looks* — that is what the
+image is for. The assertions are: the build succeeded, a diff exists, and its
+bounding box is in the region the edit acts on.
+
+Both end-to-end suites stub only `@deepseek-ai/dsh-tools` (it exists solely inside
+the Harness) and call the real `execute` with real arguments, so they exercise the
+argument handling and the exact text the model reads — not just `lib/core.mjs`.
+That matters: several bugs found this way lived only in the formatting layer.
+
+## The page SyncTeX names is not always the page it is on
+
+SyncTeX records the page a box was **built** on. A float that TeX moves to the next
+page gets the previous page's number, so `text: "Version 0.5"` used to answer
+"page 205" for a table that ships on 206 — and page 205 is a different chapter.
+The tool now checks the PDF's own text layer (`gs -sDEVICE=txtwrite`, ~0.12 s a page)
+and looks one and two pages either side; when it overrules SyncTeX it says so.
+
+## One picture, not two
+
+A `compare` call writes three images, but the one to show the user is
+`images.sideBySide`: the page before on the left, the page after on the right, one
+PNG. Finding the difference by eye across two separate files is the hardest part of
+the job for someone who cannot read the source.
+
+Writing a PNG needs no dependency — a signature, `IHDR`, one zlib `IDAT`, `IEND`, and
+`node:zlib` supplies the compression. The composite costs about 0.3 s on an A4 page at
+140 dpi, and only runs when there is something to compare.
+
+## Performance
+
+Verifying an edit always costs a real compile; there is no way around that. But
+browsing pages of the same build should not:
+
+| operation | 208-page book |
+|---|---|
+| first look (3 passes + glossary) | ~17 s |
+| every look after that, sources unchanged | ~0.2 s |
+
+A build is reused when the document, everything it `\input`/`\include`s (three
+levels), its `\includegraphics` files and its aux files are unchanged (mtime and
+size). A failing build is never reused. Pass `fresh: true` to bypass it.
+
+Two consequences worth knowing:
+
+- **The before-snapshot belongs to the build, not to the call.** After an edit, the
+  first look records what the page looked like before it; every later look at that
+  same build reuses the same snapshot, so an agent inspecting three pages of its
+  own edit still sees a diff on the second and third. (It used to be consumed by
+  the first call, which is exactly the wrong way round.)
+- **One build per document at a time.** Two compiles of the same file share its
+  `.aux`/`.toc` and corrupt each other — racing two processes on the 208-page book,
+  one of them died with no error message at all. Builds are now serialised in-process
+  by a promise queue and across processes by a lock file that carries the owner's
+  PID, so a killed run cannot wedge the document.
+
+`-draftmode` on the intermediate passes was measured and rejected: it saves about
+2%, because the time is typesetting, not PDF writing. The ~16 s is TeX itself.
+
+## The tool
+
+```jsonc
+latex_look({
+  "file": "book.tex",       // main .tex (required)
+  "page": 37,               // optional, defaults to 1
+  "text": "表3.1",          // optional: locate this string, show its page
+  "pointX": 240,            // optional, with pointY: PDF points → source line
+  "pointY": 610,
+  "compare": "previous.pdf",// optional: diff against an earlier PDF
+  "dpi": 200,               // optional, 50-300
+  "engine": "xelatex",      // optional
+  "maxPasses": 3,           // optional
+  "timeoutSeconds": 300,    // optional
+  "fresh": false,           // optional: ignore the build cache
+  "audit": false,           // optional: whole-document layout audit vs the last run
+  "auditBlankMm": 30        // optional: how deep a bottom hole must be to count,
+  "sequence": "图"            // optional: check that numbered labels stay in reading order
+})
+```
+
+Returns:
+
+- compile status, pass count, page count, and structured `problems` — each with `file`, `line`, `message`
+- `warnings`: LaTeX/Package/Class warnings plus **Overfull/Underfull** boxes, the usual cause of an ugly page
+- `toc`: whether the document declares `\tableofcontents` and how many entries it actually produced (an empty TOC is reported as a problem, not a success). The declaration is found across `\input`/`\include`, so a one-line root that wraps `\input{main}` still works
+- `aux`: external tools it ran — `makeglossaries`, `makeindex`, `biber`, `bibtex` — chosen from the artifacts the first pass produced, not from the root file's text, so multi-file projects that keep `\makeglossaries` in an included preamble are handled too
+- PNG path(s) for the rendered page — hand these to an image reader
+- `located`: `{ file, line, page }` for the text anchor or point you asked about
+- `diff`: `changedRatio` plus the bounding box of the change **in PDF points**, ready to feed back into `pointX`/`pointY`
+- `sequence`: reading order of labels that start a line ("图 1-1", "Figure 3.2", …). A float is placed later than an inline object that follows it in the source, so floating one member of a numbered run makes the numbers go backwards — the one defect a per-page diff can never show
+- `audit`: page-level layout findings — pages that stop short of the deepest text in the book, pages that start low, nearly empty pages — **compared with the baseline the previous audit left behind**, so `newFindings` is exactly what the latest build broke. Running heads, rules and page numbers are detected and excluded first; otherwise a page number becomes "the lowest ink in the book" and every page looks broken
+
+## How the locating works
+
+`latex_look` compiles with `-synctex=1`, so every glyph carries a link to its source line. Then:
+
+- **point → source**: `synctex edit -o page:x:y:file.pdf`
+- **text → source**: search the `.tex` sources for the string, then `synctex view` each hit to get its page and coordinates
+- **diff bbox → source**: pass the bbox centre as `pointX`/`pointY`
+
+Coordinates are PDF points (72/inch) with the origin at the **top-left** of the page.
+
+## Honest limits
+
+- **`page` is the PDF page index, not the number printed on the page.** In the test
+  book those differ by 10 (printed 130 = index 140), and the offset is different again
+  in the roman-numbered front matter. PDF page labels would let the tool translate, but
+  LaTeX only writes them on request, so an agent that takes a page number from a user
+  must confirm it against the rendered page first.
+- SyncTeX resolves to the *nearest text position*. A decorative rule drawn by a page style (`\pagestyle{headings}`, `fancyhdr`) has no glyph of its own, so it resolves to nearby text. Combine the coordinates with LaTeX knowledge — that is what `SKILL.md` is for.
+- Multi-pass convergence is checked by hashing `.aux`/`.toc`/`.out`/… — a document with `\tableofcontents` needs ≥ 2 passes, and `latex_look` reports a problem if the TOC comes out empty.
+- Multi-file detection follows `\input`/`\include` three levels deep. `\import`/`\subfile`, unusual custom `.latexmkrc` recipes, and `\includeonly` are not understood.
+- Cross-engine pixel parity is impossible: TeX vs Word, or two different TeX engines, have different line-breaking engines. This tool verifies *your* engine's output, not another format's.
+- A `%` in a *file name* defeats the TeX engine itself (`! Emergency stop.`), so no tool can help there. A `%` in a directory name is fine.
+- If the compile fails without writing a new PDF, the stale PDF on disk is **not** rendered and no diff is reported — the tool says so instead. Otherwise an unchanged file would read as "0% changed", i.e. "your edit did nothing".
+- `engine` accepts only the engines in this tool's list (`auto` or a known name); it is never passed to `spawn` unchecked.
+- Rendered PNGs stay under `TMPDIR/latex-look-<pid>/` because the agent opens them after the call returns. Nothing prunes that directory.
+- The build cache tracks the document, its `\input`/`\include` targets, its `\includegraphics` files and its aux files. A `.sty` that changed, or a file pulled in through a macro rather than a literal `\input{...}`, is not tracked — pass `fresh: true` if you suspect a stale build.
+- `maxPasses: 1` on a document with `\tableofcontents` is reported as an error when no `.toc` existed before, and as a warning otherwise: the `.toc` file is written *after* the TOC page is typeset, so one pass reliably produces a blank TOC page.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,99 @@
+# latex-look — 让 Agent 真正「看见」你的 LaTeX
+
+[![npm](https://img.shields.io/npm/v/@fffangchenghao%2Fdsh-latex-look?color=blue)](https://www.npmjs.com/package/@fffangchenghao/dsh-latex-look)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[English](README.md) · **简体中文**
+
+![左：编译零错误，但页面是错的。右：五句话之后的同一页](docs/before-after.png)
+
+*左边编译**零错误**：标题上下各一条横线、表格是带竖线的网格、长链接冲出版心、
+图顶到了页边。右边是五句人话之后的同一页。可直接复现：[`examples/broken-layout`](examples/broken-layout)。*
+
+---
+
+## 它解决什么问题
+
+一个只会读 `.tex` 源码的 Agent 是**瞎的**。
+
+文档可以编译零错误、打开正常，但读者一眼就看出不对：这页最上面多了一条横线、这个表格丑、
+这段文字压到了页边、图太大了、两页之间空了一大块、图号怎么从 3-4 跳回 3-3 了……
+这些**没有一条是编译错误**，`grep` 也搜不到——那条横线根本不在源码里，它是宏包画的。
+
+这类需求你只能这样表达：
+
+> 「把这一页最上面的横线去掉」「这个表格改成三线表」「图小一点」
+> 「这两页之间空太多了，填满」「图号顺序不对」
+
+`latex_look` 就是让 Agent 接得住这些话：**编译 → 渲染成图 → 定位到源码行 → 改完再比一次**，
+一个调用做完。Agent 于是能进入 `看 → 诊断 → 改 → 再看 → 确认` 的循环，而不是改完就说「应该好了」。
+
+## 三个能力，一个动词
+
+| 你说的话 | 它做什么 |
+|---|---|
+| 「这页最上方的横线去掉」 | 渲染该页，把那条线**定位到源码行**（`fancyhdr` 的 `\headrulewidth`，或某个 `\rule`） |
+| 「表格改成三线表」 | 改完渲染，用**像素 diff** 告诉你只动了表格、没碰正文 |
+| 「图号顺序不对」 | 扫全书**阅读顺序**，直接列出 `图 3-4 (p63) → 图 3-3 (p64)` |
+| 「这次改动有没有弄坏别处」 | 全书 `audit`：只报**这一次**新造成的版面问题，并点名是哪个图把页面顶走的 |
+
+```bash
+latex-look main.tex --page 62                    # 渲染第 62 页
+latex-look main.tex --page 62 --at "图 3-1"       # 定位到源码行
+latex-look main.tex --page 62 --compare           # 与上一版并排对比
+latex-look main.tex --page 1  --sequence 图       # 检查图号阅读顺序
+latex-look main.tex --page 1  --audit             # 全书版面回归审计
+```
+
+## 这不是「AI 帮你写 LaTeX」
+
+写 LaTeX 的工具已经很多了（生成、补全、编译服务）。这个工具管的是**验收**：
+改完之后，那份 PDF 到底对不对。
+
+这也是为什么它值得单独存在——**编译器只保证「不是错误」，不保证「好看」**。
+
+## 真实战绩
+
+用一本 215 页的中文技术书（6 章、163 张图、129 个公式、术语表、目录）当靶子，
+读者只能看 PDF、逐像素量、拒绝「我觉得没问题」：
+
+- 编译错误 **0**，Overfull hbox **0**
+- 163 个图题全部按阅读顺序，**0 处倒序**
+- 129 个公式编号分章连续 `(1-1)` … `(6-1)`
+- 9 处「页面下方空一大块」全部压到 ≤56 mm
+- 六章首页首行墨迹**全部 17.0%** 页高——没有任何一章被图占了章名位置
+
+完整记录（含每个缺陷的成因与修法）：[CASE-STUDY.md](CASE-STUDY.md)。
+
+## 安装
+
+需要 Node ≥ 18、TeX 引擎（`xelatex`/`lualatex`/`pdflatex`/`latexmk` 或 tectonic）、
+`synctex`、`ghostscript`。
+
+DeepSeek Harness 插件形态：
+
+```
+plugin_manager  action: install_bundle  target: @fffangchenghao/dsh-latex-look
+```
+
+命令行形态：
+
+```bash
+npm i -g @fffangchenghao/dsh-latex-look
+```
+
+Agent 的「眼睛」由工具提供；[`SKILL.md`](SKILL.md) 提供「看到症状之后怎么改」的知识——
+一份**症状 → 成因 → 修法**的手册，例如「读者说的那条横线通常是 `\pagestyle`/`fancyhdr`，
+不是某个 `\hline`」。
+
+## 更新
+
+插件每天在后台查一次 npm，有新版本时在**一次**工具回复里加一行提示；离线时完全静默。
+
+```bash
+latex-look --version
+latex-look --check-update
+```
+
+## 许可
+
+MIT。