Folio

A LaTeX writing workspace for DeepSeek Harness.
Source beside its PDF, with an assistant that proposes edits — and you decide.

English · 简体中文

Folio is a DeepSeek Harness (DSH) plugin. It adds a Folio page to the Harness sidebar where you write LaTeX, typeset it to PDF, and work with an AI assistant that runs on the models you have already configured in Harness. Everything is local: manuscripts are plain folders on your disk, TeX runs on your machine, and there are no extra accounts or API keys.

Highlights

• Looks and feels like Harness. Every color, font, radius and the light/dark theme come from the host's design tokens.
• Native Harness chat. The assistant is the Harness conversation: model picker, Markdown, reasoning, tool calls and stop/queue all work exactly as in the main chat.
• Edits you review. The assistant reads your files and builds the PDF, but it can only propose changes. Each proposal opens as a diff that you apply or discard.
• Context without copy-paste. Each turn quietly tells the model which manuscript, file, cursor line and selection you are on, plus the latest build errors.
• Real TeX builds. pdfLaTeX, XeLaTeX or Tectonic, with BibTeX/Biber and reruns. Errors become a clickable list that jumps to the file and line.
• Your layout. Toggle and resize every panel; dock the assistant right, left or bottom, or float it as a window.

Features

Editor

• CodeMirror 6 with LaTeX highlighting for commands, environments, math, references and citations.
• \ completion. About 150 common commands and 30+ environments, with Tab stops for arguments.
• Project-aware arguments. \ref{ / \cref{ complete every \label in the project, \cite{ completes keys from your .bib files, and \input{, \includegraphics{, \usepackage{ and \documentclass{ complete files, packages and classes.
• Autosave about a second after you stop typing. Hash checks guard against overwriting changes made on disk.
• Search and replace, bracket matching, and word count (CJK-aware).

\cite{ completes keys from references.bib	\ completes commands and environments with snippets

Builds

• Engines: pdfLaTeX, XeLaTeX and Tectonic; choose the main file and engine from the Compile menu.
• ⌘/Ctrl + S saves and compiles; ⌘/Ctrl + Enter compiles. Optionally compile on every save.
• The last good PDF is kept on disk and shown as soon as you open a manuscript, even after a failed build.
• Build issues (errors, warnings, bad boxes, bibliography messages) appear as a list; click one to jump to its line.

Assistant

• Each manuscript is a Harness Workspace named after its title; every conversation is a Harness Session inside it, so it also shows up in the Harness sidebar.
• The chat switcher lists this manuscript's chats. Switch between them, start a new chat, archive one, or archive all empty chats at once.
• The assistant uses a single tool, folio_project: list and read files, compile, read the last build, and propose_patch (exact find/replace edits, or a full file).
• Writing sessions are restricted at the tool-runtime level to that tool, so the model cannot bypass review with shell or file-system tools. Your other Harness sessions are unaffected.

_{A suggested edit opens as a diff. Apply writes it, but only if the file hasn't changed since the suggestion was made.}

Layout

Floating assistant	Docked at the bottom

Chats of this manuscript	Dark theme

_{The library: create from the Article, Chinese (ctexart) or Blank template.}

Requirements

• DeepSeek Harness 0.2.1-rc.2 series (web profile) and Node.js 24+.
• A TeX distribution on the PATH that Harness starts with:
  • macOS: MacTeX / TeX Live (pdflatex, xelatex, bibtex, biber).
  • Linux: texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-xetex; for Chinese add texlive-lang-chinese and CJK fonts.
  • Tectonic is optional; it runs with --only-cached --untrusted (see Configuration).

Installation

git clone https://github.com/Meinianda-L/folio.git
cd folio
npm install --omit=dev
dsh plugin --profile web add "$(pwd)"

Restart dsh web and open Folio in the Harness sidebar. The repository ships the built browser bundle (client.js), so no build step is needed to use it.

To update later:

git pull
npm install --omit=dev

Then restart Harness. If only client.js changed, reloading the page is enough.

Usage

1. Create a manuscript in the library (Article, 中文 ctexart, or Blank).
2. Write: the file tree, source and PDF sit side by side. The star marks the main file; drag files onto the tree to upload images or .bib files.
3. Compile with the toolbar button, ⌘/Ctrl + S or ⌘/Ctrl + Enter. Click the build status to see issues.
4. Ask the assistant: pick a model in the composer and ask, e.g. "Tighten the abstract" or "Fix the build error". Select text first to point at a passage.
5. Review: when a Suggested edit bar appears, open it, read the diff, then Apply or Discard.

Shortcut	Action
⌘/Ctrl + S	Save and compile
⌘/Ctrl + Enter	Compile
\	Command completion
Tab	Next snippet field
⌘/Ctrl + F	Search and replace

Configuration

By default manuscripts live in ~/Documents/DSH-Folio. To use another folder, add this to your profile's cordis.patch.yml (e.g. ~/.dsh/profiles/web/cordis.patch.yml):

- id: folio
  config:
    projectRoot: /Users/you/Papers

Environment variable	Purpose
DSH_FOLIO_TEX_CACHE	XDG cache root with a pre-warmed Tectonic bundle (defaults to XDG_CACHE_HOME or ~/.cache).

How it works

Harness web client                         Harness host (Node)
┌──────────────────────────────┐           ┌──────────────────────────────────────┐
│ Folio page (React slot)      │  fetch    │ /api/folio      project & file RPC   │
│  ├ CodeMirror editor         │──────────▶│ /api/folio/pdf  last PDF             │
│  ├ PDF viewer                │           │ /api/folio/raw  images (sandboxed)   │
│  └ embedded Harness chat ────┼─ session ▶│ agent/pre-step  hidden context       │
│     (conversation.content)   │           │ folio_project   read/compile/propose │
└──────────────────────────────┘           └──────────────────────────────────────┘

• File and build operations use exact, owner-only routes registered on the Harness connection, so they use Harness's own authentication and no separate server.
• The assistant panel renders Harness's own conversation.content component bound to the manuscript's session.
• A pre-step hook adds a non-user context message at the start of each turn. Harness keeps these messages in the session log but hides them in the chat.

Data on disk

<projectRoot>/<manuscript-id>/
├── project.json          title, main file, engine, current chat
├── main.tex, …           your sources (plain files)
└── .folio/
    ├── output.pdf        last successful build
    ├── build.json        last build summary and issues
    └── proposals.json    pending and recent suggestions

Deleting a manuscript moves its folder to <projectRoot>/.trash/ instead of erasing it. Back up projectRoot like any other folder.

Build sandboxing

Builds run one at a time (at most 4 queued) in a temporary snapshot of the project, with a 60-second limit, no shell escape, and a minimal environment that never includes your model keys. Limits: 500 files and 40 MiB per project (20 MiB of sources per build), 2 MiB per text file, 10 MiB per upload. Native TeX is not an operating-system sandbox: Folio is meant for your own, trusted projects.

Development

npm install           # includes the build toolchain
npm run build         # bundles client-src.jsx + client.css into client.js
npm test              # domain, proposals and host tests (real pdfLaTeX/BibTeX when installed)

File	Role
index.js	Host plugin: routes, context hook, folio_project tool, session restriction
domain.js	Projects, files, uploads, templates, build records
compiler.js	TeX pipeline and log parser
proposals.js	Suggested edits and find/replace application
client-src.jsx, client.css	Browser UI (bundled into client.js)
locale/	English and Chinese strings

Not included

Multi-user collaboration, share links, public/tunnel access, accounts or a separate API-key store. Folio is a single-user, local tool built on your existing Harness setup.

License

MIT