papergod 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHENGYU LIU
+
+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

@@ -0,0 +1,244 @@
+# Papergod
+
+AI-powered LaTeX writing platform — a local-first Overleaf-style editor with safe compilation, structured writing context, and Mock/Codex/Claude Code/OpenCode/Pi Agent assistants.
+
+## Quick Start
+
+```bash
+npm install
+npm run papergod
+```
+
+Open http://127.0.0.1:3000 in your browser.
+
+`npm run papergod` reopens the paper workspace most recently selected in the app. On the very first run, when no workspace has been recorded yet, it falls back to the built-in demo and safely fills its missing demo content. To seed another disposable workspace explicitly, use `papergod ./demo-paper --demo`. Ordinary `papergod ./my-paper` runs add only the non-destructive starter writing library; existing resources are never overwritten.
+
+When installed as a package, run Papergod in any paper directory:
+
+```bash
+npx papergod .
+npx papergod ./my-paper --port 4312 --agent codex
+```
+
+The CLI initializes `main.tex` when the workspace contains no TeX files and stores Papergod metadata in `.papergod/project.json`. Agent choices are `mock`, `codex`, `claude-code`, `opencode`, and `pi`. External providers require an installed and authenticated CLI; Papergod invokes them non-interactively with structured output, timeouts, output limits, and analysis-only permissions.
+
+### Multiple paper workspaces
+
+Open **Tools → Workspaces** to register an existing local folder and switch papers without restarting the server. A folder may be a normal directory or a repository created with `git clone`; Papergod does not take over Git credentials or change the repository workflow, so commit and push with Git as usual. The browser reloads after a successful switch to discard stale PDF and editor state.
+
+**Browse…** first attempts a local operating-system picker (`zenity`, `kdialog`, then Python/Tk on Linux and WSL). If none is available, Papergod automatically opens an in-browser directory navigator rooted at the user's home directory; paths outside that browsing boundary can still be entered explicitly and are validated before use.
+
+**Tools → Terminal** opens a real PTY shell whose working directory is the current paper workspace. It supports ANSI output, interactive input, resizing, scrollback, reconnecting after the dialog is closed, and an explicit stop action. Terminal code is loaded only when the tool is opened, so it does not increase the main workbench JavaScript payload.
+
+The recent-workspace registry is stored in `~/.papergod/workspaces.json`. Paper content, prompts, revision history, writing libraries, and Agent profiles remain isolated in each folder's `.papergod/project.json`. Switching is refused while an Agent task is running, and the current source is saved before a browser-initiated switch. New or existing workspaces receive missing starter checklists, eight academic sentence patterns, and ten precision-focused vocabulary entries by stable ID; user-created entries are preserved.
+
+### References and Zotero
+
+Open **Tools → References** to build one searchable citation library from local literature folders and Zotero Desktop. Local folders are scanned recursively for `.bib`, `.bibtex`, and `.pdf` files. Existing BibTeX is treated as authoritative; PDF first pages are inspected for DOI/arXiv identifiers, and uncertain records remain visibly marked for review instead of being guessed. DOI records can be verified against Crossref on demand.
+
+Papergod connects to Zotero's read-only local API at `127.0.0.1:23119`, so ordinary local use requires no Zotero cloud key. In Zotero, enable **Settings → Advanced → Allow other applications on this computer to communicate with Zotero**, then use **Connect Zotero** to search the library or a collection. Better BibTeX is detected when installed but is optional. Imported entries, local entries, and citation status are indexed in `.papergod/references.json`; the compilable `references.bib` stays in the paper workspace and can be tracked with Git.
+
+Reference cards can be selected for two separate actions: **Insert selected** writes a `\cite{...}` command at the editor cursor, while selection also makes those verified records available to the Agent prompt. Citation checking reports missing citekeys and missing bibliography setup. Agent revisions that introduce a citekey absent from the managed bibliography are rejected before source is changed.
+
+**Generate a review paragraph**: select several references (local or imported from Zotero), optionally describe what the paragraph should cover, and run **Generate review paragraph**. Papergod composes a draft that cites each selected record with `\citep{...}` (Mock synthesizes deterministically from bibliographic metadata; a configured external Agent writes a substantive synthesis). The draft stays reviewable until **Insert at cursor** applies it through the same atomic revision flow.
+
+### Paragraph Analysis
+
+- Click the **📊** button next to any paragraph in the outline, or use **Tools → Paragraph analysis** to analyze the whole paper
+- Every analysis reports sentence lengths (in words), and document/section analyses also report paragraph lengths
+- Statistics include the mean μ, sample standard deviation s, coefficient of variation CV = s/μ, median, range, IQR, adjacent-sentence change Δ, and the normalized change Δ/μ — all with the exact formulas shown in the panel
+- A 0–100 **variation index** VI = 100·(0.6·min(1, CV/0.5) + 0.4·min(1, (Δ/μ)/0.8)) combines CV and adjacent change into a single rhythm score
+- The verdict reads the score for you: highly uniform rhythms (low VI) are typical of template-generated text, while high variation resembles organic human drafting — uniformity alone is not proof of AI writing
+
+### Writing Libraries
+
+- **Extract from PDF** reads the text layer of any PDF in the workspace, extracts reusable academic sentence patterns (deterministic rules for Mock, structured Agent extraction for external providers), and lets you add each confirmed candidate to the sentence-pattern library
+
+![Papergod demo](./papergod-demo.png)
+
+## Architecture
+
+```
+Browser (React workbench + progressive legacy workflow migration)
+  │
+  │  shadcn-style primitives + CodeMirror editor + structured outline + PDF.js + AI panel
+  │
+  ▼
+Express server (127.0.0.1 only)
+  ├── /api/files/*       — read/write .tex files (path-traversal protected)
+  ├── /api/compile       — LaTeX compilation (pdflatex/xelatex/lualatex/tectonic)
+  ├── /api/engines       — list available LaTeX engines
+  ├── /api/agent/*       — scoped AI suggestions + audited CLI runs
+  ├── /api/documents/*   — LaTeX structure synchronization + layered prompts
+  ├── /api/libraries/*   — corpora, sentence patterns, and scoped vocabulary
+  ├── /api/annotations   — range-anchored writing and review comments
+  ├── /api/review/*      — atomic review-opinion extraction
+  ├── /api/reviews/*     — configurable peer-review panels and synthesis
+  ├── /api/revisions/*   — reviewable plans, decisions, apply, and rollback
+  ├── /api/generate/*    — prompt/library-controlled full-paper drafts
+  ├── /api/workflow/*    — complete history and portable export bundles
+  ├── /api/workspaces/*  — local workspace registration and runtime switching
+  ├── /api/references/*  — folders, Zotero, BibTeX generation, citekey checks, and review paragraphs
+  ├── /api/analysis/*    — sentence/paragraph rhythm statistics (mean, stddev, CV, variation index)
+  ├── /api/orchestrations/* — multi-agent graphs, gates, runs, and audit records
+  └── /workspace/*       — static serving of compiled PDFs
+```
+
+### Security
+
+- Server binds only to `127.0.0.1` — no network exposure
+- All file paths validated against workspace root (path traversal blocked)
+- LaTeX compilation uses `execFile` with `shell: false`, shell escape disabled, a 30s timeout, and `SIGKILL` on overrun
+- Only `.tex` files can be written or compiled
+- Dotfiles denied in static serving
+- External Agents read only the current workspace and never receive the manuscript or library body in their prompt (workspace-index mode); their output quotes are validated against the in-memory source, and any write still flows through the visible diff review
+- CodeMirror is installed locally from npm; the editor does not depend on a public CDN
+
+### Agent System
+
+- The assistant is organized into Agent Configuration, assembled Prompt Context, a one-run Temporary Prompt, and the single **请神** invocation button
+- **请神** first shows a confirmation dialog, then submits one merged `Prompt Context + Temporary Prompt` instruction to the active Agent
+- A compact **Agent Activity** bar below the invocation button shows context preparation, live CLI output, atomic application, PDF compilation, elapsed time, cancellation, and the final result without blocking the paper
+- Ordinary Agent suggestions are applied together as one atomic revision instead of requiring repeated Accept clicks; the Agent Activity result can roll that revision back as long as no later source edit would be lost
+- **Change history** in Tools keeps the reading view clean while exposing the five most recent applied versions, per-change before/after diffs, source navigation for the current version, and checksum-protected whole-revision rollback
+- Agent configuration uses one shared provider shape for Mock, Codex CLI, Claude Code, OpenCode, and Pi Agent; every external adapter supports revision, paragraph drafting, peer review, review orchestration, and full-paper generation
+- Papergod detects CLI versions and non-secret authentication readiness with a fast **Check setup** action; actual model validation happens in the ordinary reviewable writing workflow
+- Custom CLI paths, prefix arguments, and model overrides are persisted in `.papergod/project.json`, reloaded on later runs, and passed to the real CLI invocation
+- Preview the complete invocation context assembled from project/document/element prompts, summaries, sentence intent, selected libraries, temporary instructions, and target source
+- **Mock agent**: deterministic suggestions based on pattern matching (passive voice, "very + adjective", short conclusions)
+- **CLI agents**: Codex, Claude Code, OpenCode, and Pi Agent run non-interactively with validated structured output, analysis-only execution, timeouts, cancellation, and audit records
+- **Provider isolation**: Codex uses a read-only ephemeral execution; OpenCode runs in a temporary directory with permissions denied; Pi runs in JSON mode with sessions, project context, extensions, and skills disabled
+- **Workspace-index context**: for suggest, peer-review, and review-orchestration runs, the prompt inlines only the workspace absolute path, a flat directory/file listing, the target file's byte range `[start, end)`, and the `.papergod/library/*` paths — the manuscript body and library text are never sent. The Agent reads the files it needs on demand, and its `originalText`/`quote` outputs are still validated against the in-memory target as exact contiguous substrings
+- **On-demand read access**: Pi runs with `--tools read`, Claude Code with `--tools Read,Grep,Glob`, OpenCode with `--dir <workspace>` plus read-only permissions, and Codex with its read-only sandbox pointed at the workspace, so each CLI can read the paper and library files without being able to write them
+- **Structured workflows**: editing, review orchestration, peer review, and full-paper generation each use a dedicated validated JSON protocol
+- **Accept/Reject**: both decisions are persisted; accepted edits use atomic revisions and checksum recovery points
+- **Element scope**: select a section, paragraph, or sentence from the outline to constrain prompts and diffs to that exact source range
+
+### Structured Writing
+
+- LaTeX sections, paragraphs, and sentences are mapped to stable IDs and exact source ranges
+- The outline exposes editable document/element prompts, summaries, and sentence intents
+- Clicking any outline node highlights and scrolls to the matching text in the compiled PDF (text-layer matching with graceful fallback to the source editor); recompile to refresh the PDF text layer
+- **Focus Annotation** opens an immersive three-column reader: paper outline on the left, one paragraph and its revision prompt in the center, and sentence-by-sentence reading with intent and prompt fields on the right
+- Paragraph and sentence navigation automatically preserves draft annotations; **Open in editor** returns the selected paragraph to CodeMirror
+- Sentence-level Agent requests inherit both the parent paragraph prompt and the sentence prompt, so focused annotations become actionable revision context
+- Metadata is persisted atomically in `.papergod/project.json`
+- Project schema v2 automatically migrates existing schema-v1 review records
+- Stale source ranges are rejected before an Agent suggestion can be applied
+
+### Writing Libraries
+
+- Manage algorithm corpora, tagged sentence patterns, citations, and required template slots
+- Keep global vocabulary separate from vocabulary agreed for the current writing session
+- Select resources explicitly or let Papergod retrieve them by text, tags, and section type
+- Generate a reviewable paragraph draft, then insert it only after user confirmation
+- Extract candidate expressions from the current paper; candidates require confirmation before entering a library
+- Agent runs distinguish resources provided as context from resources the Agent reports actually using
+
+### Review & Revise
+
+- Work through one unified two-stage workspace: **Opinions & plans** followed by **Responses & delivery**
+- Anchor a comment to an exact editor selection, or import numbered/bulleted reviewer feedback
+- Use Mock or any configured external Agent to split feedback into atomic categorized opinions, exact quotes, suggested fixes, dependencies, and document-node assignments
+- Build revision plans with visible before/after text plus dependency and conflict information
+- Accept, reject, or defer changes individually; executable changes can also be accepted in a batch
+- Apply accepted edits atomically only after explicit review
+- Create checksum-protected recovery points and refuse rollback when it would discard later author edits
+
+### Peer Review Panels
+
+- Start from methodology, statistics, writing, domain, and reproducibility reviewer profiles
+- Build a custom panel, add reviewer-specific instructions, and edit weighted rubric criteria
+- Run reviewers independently through Mock or any configured external Agent with one audited Agent run per report
+- Validate exact manuscript quotes and rubric references in every external Agent response
+- Synthesize consensus clusters, conflicting assessments, an overall verdict, and prioritized concerns
+- Select concerns and send them directly into the reviewable M6 revision workflow
+
+### Responses, Verification & Full-Paper Generation
+
+- Continue from revision planning in the same Review & Revise drawer instead of switching tools
+- Turn a revision plan into an editable point-by-point response letter and precise change list
+- Apply revisions atomically, recompile the manuscript, and report every unresolved or deferred opinion
+- Generate a complete LaTeX draft from project/document prompts, outline and paragraph prompts, plus selected corpora, patterns, and vocabulary
+- Preview generated source and accept it only through the same visible revision diff used by ordinary edits
+- Record accepted and rejected Agent decisions; accepted suggestions and paragraph insertions receive checksum recovery points
+- Browse a unified history of Agent runs, peer reviews, and revisions
+- Download source, annotations, reports, revisions, responses, change lists, history, and recovery metadata as a portable JSON bundle
+
+### Multi-Agent Orchestration
+
+- Open **Tools → Agent orchestration** to arrange configured local Agents on a native canvas
+- Agent nodes declare a provider (Mock or any configured local CLI) and a task: suggest edits, peer review, draft a paragraph, or generate a full paper
+- Approval-gate nodes pause the run until a human approves or rejects; rejection stops the run and skips downstream nodes
+- Nodes run in parallel whenever their dependencies are satisfied; serial review loops are just chains with gates
+- Every node output is stored as a structured record, every edge carries the input summary passed downstream, and each node execution writes an audited Agent run
+- A cyclic graph is rejected before running; edits and deletions are refused while a run is active
+- Only locally configured CLIs are orchestrated — Papergod never creates or logs into accounts
+
+### LaTeX Compilation
+
+- Auto-detects available engines in order: tectonic → pdflatex → xelatex → lualatex
+- Opens an available paper directly in the compiled PDF view; LaTeX source remains available as an advanced tool
+- Renders compiled PDFs as clean, continuous, width-fitted paper pages without the browser PDF viewer chrome
+- Adds a PDF.js text layer: click manuscript text, choose word/sentence/paragraph scope, and save a persistent modification intent without changing the source immediately
+- Queued modification intents remain editable/removable, are assembled into one document-level prompt when **请神** is invoked, and are resolved together after one atomic revision; undoing that revision reopens the original intent queue
+- Source and rendered pages share one switchable workspace, leaving the assistant column fully available
+- Graceful degradation: if no engine found, compile button is disabled but editor works normally
+- Compilation errors displayed to the user
+
+## Requirements
+
+- Node.js ≥ 18
+- A LaTeX distribution (optional, for compilation): TeX Live, MiKTeX, or Tectonic
+- The corresponding provider CLI and login for external Agents. Pi Agent is not bundled; install and authenticate the current `pi` CLI using its official coding-agent documentation before selecting it.
+
+## Testing
+
+```bash
+npm test
+```
+
+## Project Structure
+
+```
+src/server/
+  index.js      — Express app + API routes
+  security.js   — Path sanitization + security headers
+  latex.js      — Engine detection + compilation
+  agent.js      — Suggestion store and deterministic Mock agent
+  agent-adapters.js — Codex/Claude Code/OpenCode/Pi non-interactive adapters
+  project-store.js — Versioned project metadata and validation
+  project-resources.js — Corpus, vocabulary, annotation, and revision resources
+  latex-structure.js — LaTeX structure/range parser
+  document-structure.js — Structure synchronization and metadata APIs
+  library-engine.js — Retrieval, scoped vocabulary, template rendering, extraction, and prompt context
+  revision-engine.js — Opinion extraction, revision planning, atomic apply, and safe rollback
+  review-panel.js — Reviewer profiles, independent reports, synthesis, and revision handoff
+  revise-workflow.js — Response letters, verification, full-paper generation, history, and export
+  orchestration-engine.js — Multi-agent graphs, gate execution, and audit records
+  paragraph-analysis.js — Sentence/paragraph rhythm statistics and the variation index
+  literature-review.js — Reference synthesis paragraphs with citable \citep output
+  text-extraction.js — PDF text to reusable sentence-pattern candidates
+public/
+  index.html    — Static entry and workflow overlay compatibility layer
+  style.css     — Legacy workflow layout styles
+  app.js        — Existing workflow and API integration logic
+  react/        — Production React bundle generated by Vite
+frontend/
+  src/components/ — React workbench and shadcn-style UI primitives
+  src/theme.css   — White lightweight design tokens and compatibility theme
+  vite.config.js  — Production build into public/react
+example/
+  main.tex      — Sample LaTeX document
+tests/
+  api.test.js   — Integration tests
+```
+
+## Current Scope
+
+- Single-user, local only
+- External Agent quality and availability depend on the user's installed/authenticated CLI
+- No concurrent editing / CRDT
+- No file upload (only pre-existing .tex files in workspace)
+- PDF-only reference identification is best-effort; records without a reliable DOI, arXiv ID, or existing BibTeX require user confirmation
+- PDF-to-source targeting currently matches PDF.js text against parsed manuscript sentences and paragraphs. Complex macros, equations, repeated fragments, and transformed text may not map; SyncTeX-backed coordinate mapping is the planned precision upgrade.

package/ROADMAP.md

@@ -0,0 +1,171 @@
+# Papergod 长期实现路线图
+
+## 目标
+
+Papergod 是一个可通过 npm 安装和启动的、本地优先的 AI LaTeX 写作平台。界面提供类似 Overleaf 的文件编辑、编译和 PDF 预览；写作、分析、评审与修订由 Codex、OpenCode 等 Agent CLI 驱动，并通过结构化数据和可审阅 diff 保证用户始终掌握最终修改权。
+
+## 当前功能覆盖
+
+| 能力 | 状态 | 当前实现 |
+| --- | --- | --- |
+| npm 安装并启动本地网页 | 已实现 | 提供 `papergod` bin、`npx papergod [workspace]` 与首次初始化 |
+| 多论文工作区切换 | 已实现 | Tools 中集中添加/切换本地目录，论文、历史、写作库与 Agent 配置按目录隔离 |
+| 工作区目录浏览与终端 | 已实现 | 原生选择器失败时提供受限网页目录浏览；Tools 提供按 workspace 隔离的交互式 PTY/xterm |
+| 文献引用与 Zotero | 已实现（MVP） | 本地 BibTeX/PDF 文件夹扫描、Zotero Desktop/collection 搜索、可选 Better BibTeX 检测、统一 references.bib、citekey 检查与插入 |
+| 文献综述生成与插入 | 已实现 | References 中多选文献 → 生成可审阅综述段落（Mock 确定性 / 外部 Agent 实质性综述），确认后经原子修订插入，\citep 引用可溯源 |
+| Overleaf 风格编辑界面 | 已实现（Demo） | 文件栏、CodeMirror、PDF 预览、AI 面板 |
+| LaTeX 编辑、保存与编译 | 已实现（基础） | 支持 `.tex` 文件和多种本地引擎，含安全边界与错误反馈 |
+| Agent 建议、diff、接受/拒绝 | 已实现 | Mock/Codex/Claude Code/OpenCode 统一生成结构化建议，逐条接受或拒绝 |
+| Agent CLI 接入 | 已实现 | 自动探测 Codex/Claude Code/OpenCode 的版本与认证状态，支持路径、前置参数、模型覆盖、连接检查及安全结构化调用 |
+| 多 Agent 协作图 | 已实现 | 原生编排画布：Agent 节点/审批关卡、任务连线、输入输出摘要、调度/运行/失败/完成状态、审计记录 |
+| 文章/段落/句子/词汇模型 | 已实现 | 稳定节点 ID、精确范围、摘要、意图和两级词汇作用域 |
+| 全文 Prompt 与每段 Prompt | 已实现 | 全文核心 Prompt 与元素级 Prompt 均可编辑并持久化 |
+| 算法语料与句型库 | 已实现 | 支持存储、检索、变量槽、来源和候选提取，并内置开箱即用的学术句式与检查表 |
+| 通用/本轮协作词汇库 | 已实现 | 全局/本轮作用域合并、检索和采用记录，并提供精确表达 starter vocabulary |
+| 句子意图与段落大意提取 | 已实现（基础） | 大纲展示段落摘要、逐句意图并可单独编辑 |
+| 段落节奏统计分析 | 已实现 | 段落/文档级句长与段长统计（均值、样本标准差、变异系数、中位数、极差、IQR、相邻变化 Δ、变化程度指标 VI 0–100），公式逐条展示，柱状图可视化，并对“AI 机械感”给出启发式判定 |
+| PDF 句式提取入库 | 已实现 | 工作区 PDF 文本层提取（Mock 规则/外部 Agent），候选句式泛化槽位，用户确认后加入句型库 |
+| 专注批注阅读 | 已实现 | 三栏沉浸大窗按小标题、自然段和句子逐级聚焦，分别记录段落/逐句 Prompt，并接入后续 Agent 上下文 |
+| 阅读批注与意见管理 | 已实现 | 精确范围锚点、类别、严重度、状态和来源 |
+| 全文意见编排与任务分配 | 已实现 | Mock/Codex/Claude Code/OpenCode 结构化编排、原子意见、节点分配、依赖/冲突图与显式决策 |
+| 同行评审/论文评审团 | 已实现 | 五类预设/自定义 reviewer、rubric、独立 Agent 报告、共识/冲突汇总及 M6 交接 |
+| 自助 revise | 已实现 | 意见导入、计划执行、可编辑回复信、修改清单、编译复核、未处理检查和导出 |
+| 一键生成论文 | 已实现 | 核心/分层 Prompt、结构大纲和写作库受控生成，全文 diff 审阅后方可应用 |
+| 修改位置与历史 | 已实现 | 最近 5 次版本抽屉、逐块 diff、源码定位、持久 revision、恢复点、校验和与安全回滚 |
+| 自动化测试 | 已实现 | 125 项 API、结构、CLI、工作区/PTY、BibTeX/Zotero、Agent 配置、写作库、评审、修订、生成、编排、统计分析、综述、PDF 提取、安全和编译测试通过 |
+| Agent 上下文工程（文件索引 + 按需读取） | 已实现 | 写作库物化为 `.papergod/library/` 可读文件，prompt 仅注入项目绝对路径、目录清单、目标文件字节范围与库路径；各外部 CLI 放开 workspace 只读访问，正文与库全文不再进入 prompt |
+
+## 目标架构
+
+```text
+Browser
+  ├─ LaTeX editor / PDF preview / file tree
+  ├─ Document outline / paragraph & sentence inspector
+  ├─ Prompt / corpus / vocabulary workspace
+  └─ Review / revise / diff history
+       │
+Local Node.js service
+  ├─ Project & structured document store
+  ├─ LaTeX compiler
+  ├─ Corpus and vocabulary service
+  ├─ Annotation and revision service
+  ├─ Agent orchestrator + JSON validation
+  └─ Codex / OpenCode / Mock adapters
+       │
+Local workspace
+  ├─ *.tex / bibliography / assets
+  └─ .papergod/project.json + runs + revisions
+```
+
+## 实施里程碑
+
+### M1：项目模型与持久化基础
+
+- [x] 定义 project/document/section/paragraph/sentence 的稳定 ID 与排序字段
+- [x] 定义全文 Prompt、段落 Prompt、句子意图和摘要字段
+- [x] 定义 corpus、sentence pattern、global/session vocabulary
+- [x] 定义 annotation、review、revision、agent run 数据结构
+- [x] 在工作区 `.papergod/` 中原子化持久化并提供 API
+- [x] 增加 schema 校验、迁移版本和测试
+
+验收：项目元数据可创建、读取、更新；重新启动服务后数据不丢失；路径与输入校验测试通过。
+
+### M2：可发布 npm CLI
+
+- [x] 提供 `papergod` bin 与 `npx papergod [workspace]`
+- [x] 支持端口、工作区、Agent provider 等 CLI 参数
+- [x] 完善 npm `files`、版本、启动错误和首次初始化
+- [x] 验证干净目录安装、启动、关闭流程
+
+验收：在任意论文目录执行 `npx papergod` 可初始化并打开本地服务。
+
+### M3：真实 Agent CLI 适配层
+
+- [x] 探测 Codex/Claude Code/OpenCode 可用性、版本与认证状态
+- [x] 以参数数组、超时、工作目录和最小环境安全调用 CLI
+- [x] 统一结构化 JSON 请求/响应协议
+- [x] 对输出做 schema 校验、大小限制、错误归一化和取消处理
+- [x] 持久化 CLI 路径、前置参数和模型覆盖，并提供连接检查
+- [x] 保留确定性 Mock，测试永不调用外部 Agent
+
+验收：用户可选择 provider；真实 CLI 能只读分析并生成结构化建议；失败时不会损坏论文。
+
+### M4：结构化论文工作台
+
+- [x] 解析 LaTeX 的 section/paragraph/sentence 映射
+- [x] 展示全文大纲、段落摘要、逐句意图
+- [x] 支持元素级选择、编辑和 AI 重写
+- [x] 支持全文及每段 Prompt 编辑
+- [x] 提供专注批注大窗，按章节、段落、句子逐级阅读并维护两级修改 Prompt
+- [x] 保持结构节点与 `.tex` 文本范围同步
+
+验收：用户能定位任一段/句，查看它的作用并进行局部重写，diff 精确回到原文位置。
+
+### M5：语料、句型与词汇协作
+
+- [x] 管理算法语料与可复用句型模板
+- [x] 管理通用词汇库和本轮协作词汇库
+- [x] 提供标签、适用章节、变量槽位和引用来源
+- [x] Agent 生成时检索并记录实际采用的句型/词汇
+- [x] 支持从现有论文提取候选表达，经用户确认后入库
+
+验收：可选择语料和词汇约束生成段落，并追溯每个表达来自哪个库。
+
+### M6：批注、意见编排与可审阅修订
+
+- [x] 建立文本范围锚定的批注与处理状态
+- [x] 从用户输入/审稿意见中提取原子意见
+- [x] 把意见分配到文章、段落或句子并形成依赖图
+- [x] 分步执行修改，展示 before/after、原因和影响范围
+- [x] 支持逐条/批量接受、拒绝、延期和回滚
+
+验收：一轮批注可转成可执行修订计划，任何文本写入都必须经过可见 diff。
+
+### M7：抽象同行评审团
+
+- [x] 定义方法、统计、写作、领域、复现性等 reviewer profile
+- [x] 支持构造自定义评审团和评审 rubric
+- [x] 并行产生独立意见并进行冲突/共识汇总
+- [x] 评审结论可一键进入 M6 修订工作流
+
+验收：同一稿件能得到角色独立、可追溯、可合并的结构化评审报告。
+
+### M8：自助 Revise 与一键生成
+
+- [x] 导入审稿意见并关联原文
+- [x] 生成 response letter 与修订计划
+- [x] 按计划修订、重新编译并检查未处理意见
+- [x] 从论文核心 Prompt、段落 Prompt、语料和词汇生成初稿
+- [x] 提供完整运行历史、修改清单、导出和恢复点
+
+验收：从“粘贴审稿意见”到“修订稿 + 回复信 + 修改清单”形成完整闭环。
+
+### M9：多 Agent 可视化编排
+
+- [x] 定义 Agent 节点、角色、能力、输入输出端口和任务连线
+- [x] 提供 Papergod 原生的 Agent 编排画布，显示调度、运行、失败和完成状态
+- [x] 支持串行、并行、评审回路和人工确认关卡
+- [x] 为每条边保存输入摘要，为每个节点保存结构化输出和审计记录
+- [x] 第一版仅编排用户已经配置好的本地 CLI，不自动创建或登录账号
+
+验收：用户能在画布上连接多个本地 Agent，运行一次可追踪协作流程，并定位每一步的输入、输出和失败原因。
+
+### M10：Agent 上下文工程（文件索引 + 按需读取）
+
+- [x] 把写作库（语料/句型/词汇）物化为 workspace 内可读文件（`.papergod/library/corpus.md`、`patterns.md`、`vocabulary-global.md`、`vocabulary-session.md` 与 `.papergod/index.json`），外部 Agent 调用前落盘
+- [x] 精简 Agent prompt：只注入项目绝对路径、各层目录清单、目标文件字节范围 `[start, end)` 与库文件路径，不再注入文档正文与库全文
+- [x] 摘要、评审、意见编排等结构化工作流统一走 workspace-index 分支；编排器内对非文件输入仍保留内联（节点输入原文即 prompt，非文件）
+- [x] 放开各外部 CLI 在 workspace 内的只读访问：Pi `--tools read`、Claude Code `--tools Read,Grep,Glob`、OpenCode `--dir workspaceRoot` + 只读权限、Codex 只读沙箱读取当前工作目录
+- [x] Mock 与既有建议/评审/段落/全文生成/编排/综述/PDF 提取工作流兼容新协议，自动化测试通过
+- [x] 保留安全边界：建议/评审的 `originalText`/`quote` 仍以内存中的 `request.content` 校验为精确连续子串，写入仍走可见 diff 审阅
+
+验收：外部 Agent 通过路径自行读取论文与库文件后返回结构化建议，prompt 中不再出现正文全文；所有工作流测试通过且安全边界不变。
+
+## 实现原则
+
+- 本地优先：服务仅绑定 `127.0.0.1`，论文内容默认不离开本机。
+- 用户控制：Agent 先提出结构化 patch，用户审阅后才写入源文件。
+- 可追溯：每次生成记录 provider、prompt、输入范围、语料引用、输出和决定。
+- 可恢复：修改前建立恢复点，批量操作具有原子性。
+- 可替换：业务层只依赖统一 Agent 接口，不绑定某一个 CLI。
+- 可测试：自动测试使用 Mock adapter，不依赖网络或外部模型。