scitex-writer

<!-- --- !-- File: README.md !-- --- --> <p align="center"> <a href="https://scitex.ai"> <img src="docs/scitex-logo-banner.png" alt="SciTeX Writer" width="400"> </a> </p> # SciTeX Writer <!-- scitex-badges:start --> <p align="center"> <a href="https://pypi.org/project/scitex-writer/"><img src="https://img.shields.io/pypi/v/scitex-writer?label=pypi" alt="pypi"></a> <a href="https://pypi.org/project/scitex-writer/"><img src="https://img.shields.io/pypi/pyversions/scitex-writer?label=python" alt="python"></a> <a href="https://github.com/ywatanabe1989/scitex-writer/actions/workflows/rtd-sphinx-build-on-ubuntu-latest.yml"><img src="https://img.shields.io/github/actions/workflow/status/ywatanabe1989/scitex-writer/rtd-sphinx-build-on-ubuntu-latest.yml?branch=develop&label=docs" alt="docs"></a> </p> <p align="center"> <a href="https://github.com/ywatanabe1989/scitex-writer/actions/workflows/pytest-matrix-on-ubuntu-py3-11-3-12-3-13.yml"><img src="https://img.shields.io/github/actions/workflow/status/ywatanabe1989/scitex-writer/pytest-matrix-on-ubuntu-py3-11-3-12-3-13.yml?branch=develop&label=tests" alt="tests"></a> <a href="https://codecov.io/gh/ywatanabe1989/scitex-writer"><img src="https://img.shields.io/codecov/c/github/ywatanabe1989/scitex-writer/develop?label=cov" alt="cov"></a> </p> <!-- scitex-badges:end --> <p align="center"> <a href="https://scitex.ai">scitex.ai</a> · <a href="https://scitex-writer.readthedocs.io/">docs</a> · <code>pip install scitex-writer[all]</code> </p> --- **科学手稿的LaTeX编译系统，具备自动版本控制、差异生成和跨平台可复制性。** [SciTeX](https://scitex.ai) 生态系统的一部分 — 赋予人类研究人员和AI代理强大的能力。 ## 问题与解决方案 | # | 问题 | 解决方案 | |---|---------|----------| | 1 | **LaTeX编译脆弱** -- 引用文献、图表、表格、交叉引用、补充材料各自都有自己的失败模式 | **`scitex writer compile`** -- 一条命令运行bibtex → latex → bibtex → latex两次；处理补充材料和修订差异 | | 2 | **图表与手稿分离** -- 作者重新编号图表；一半的引用失效；`\ref{}` 静默打印 `??` | **引用检查 + 浮动顺序审计** -- `writer_check_references` + `writer_check_float_order` 在提交前捕获悬空 `\ref{}` | | 3 | **手稿声明无法验证** -- 论文断言 "t(58) = 2.34, p = .021"；审稿人无法验证 | **基于线索的声明** -- `writer_add_claim` 将每个断言绑定到源会话 + 文件哈希；`writer_render_claims` 暴露验证DAG | ## 演示 <p align="center"> <img src="docs/demo-manuscript-light.png" alt="Light Mode" width="380"/> &nbsp;&nbsp; <img src="docs/demo-manuscript-dark.png" alt="Dark Mode" width="380"/> </p> <p align="center"> <em>浅色模式（默认）和深色模式（<code>--dark-mode</code>）</em> </p> <p align="center"> <a href="https://scitex.ai/demos/watch/scitex-writer/"> <img src="examples/scitex-writer-v2.2.0-demo-thumbnail.png" alt="Demo Video" width="600"/> </a> </p> <p align="center"> <em>带有AI代理的演示视频</em> </p> ## 安装 ```bash # LaTeX依赖（Ubuntu/Debian） sudo apt-get install texlive-latex-extra latexdiff parallel imagemagick ghostscript # LaTeX依赖（macOS） brew install texlive latexdiff parallel imagemagick ghostscript # Python包 + MCP服务器 pip install scitex-writer ``` ## 快速开始 ```bash git clone https://github.com/ywatanabe1989/scitex-writer.git my-paper cd my-paper && make manuscript # 或：./compile.sh manuscript ``` ## SciTeX的一部分 `scitex-writer` 是 [**SciTeX**](https://scitex.ai) 的一部分。 通过 `pip install scitex[writer]` 安装，使用 `scitex.writer`（Python）或 `scitex writer ...`（CLI）。 > 研究的四项自由 > 0. 在任何地方**运行**你的研究 — 你的机器，你的条款。 > 1. **研究**每个步骤的工作原理 — 从原始数据到最终手稿。 > 2. **重新分发**你的工作流，而不仅仅是你的论文。 > 3. **修改**任何模块并与社区分享改进。 > AGPL-3.0 — 因为我们相信研究基础设施应该拥有与软件相同的自由。 ## 问题 科学手稿的LaTeX编译很痛苦： - **环境不一致性** — “它在我机器上编译”在跨Linux、macOS、WSL2和HPC集群协作时不是解决方案。 - **手动图表转换** — 在PNG、SVG、PDF、Mermaid和TIFF格式之间手动转换浪费时间并引入错误。 - **没有版本跟踪** — 生成修订之间的跟踪更改差异需要手动`latexdiff`调用和仔细的文件管理。 - **碎片化工具链** — 编译、参考书目管理、表格格式化和提交打包的独立工作流。 - **AI代理无法帮助** — 没有编程接口，AI助手无法编译或管理手稿。 ## 解决方案 SciTeX Writer解决了这些问题： - **基于容器的可复制编译** — 通过Docker、Singularity或本地安装与自动引擎选择（Tectonic、latexmk或3次传递）实现所有平台的一致构建。 - **自动资产转换** — 图表和表格从源格式（PNG、SVG、逗号分隔值（CSV）、Mermaid）并行转换为LaTeX-ready输出。 - **内置版本跟踪和差异生成** — 每次编译都存档上一个版本并自动生成`latexdiff`文档。 - **统一接口** — 一个工具用于编译、参考书目重复、图表/表格管理和arXiv导出打包。 - **用于AI代理的44个模型上下文协议（MCP）工具** — AI助手可以编程编译、编辑和管理手稿。 ## 架构 ```mermaid flowchart TB subgraph Surfaces["表面（用户界面）"] CLI["CLI<br/><code>_cli/</code>"] MCP["MCP工具<br/><code>_mcp/</code>"] Web["Django编辑器 + 查看器<br/><code>_django/</code>"] Ports["可选桥梁<br/><code>_ports/</code>"] end subgraph Engines["引擎（纯函数）"] Compile["编译<br/><code>_compile/</code>"] Bib["参考书目<br/><code>bib.py</code>"] Claim["声明<br/><code>claim.py</code>"] Export["导出 / arXiv<br/><code>export/</code>"] Migrate["迁移<br/><code>migration/</code>"] end subgraph Model["项目模型（真实来源）"] DC["<code>_dataclasses/</code><br/>(不可变手稿视图)"] Proj["<code>_project/</code>"] Utils["<code>_utils/</code>"] end Surfaces --> Engines Engines --> Model Ports -.optional.-> Scholar["scitex-scholar<br/>(SCHOLAR_AVAILABLE)"] Ports -.optional.-> Figrecipe["figrecipe / clew / stats"] ``` `scitex-writer` 分为三个同心环： | 环 | 模块 | 角色 | |---|---|---| | **项目模型** | `_dataclasses/`、`_project/`、`_utils/` | 手稿树的不可变视图、配置和内容 — 每个其他层读取的真实来源。 | | **引擎** | `_compile/`、`bib.py`、`claim.py`、`export/`、`migration/` | 对项目模型进行操作的纯函数 — LaTeX编译、BibTeX操作、声明渲染、arXiv导出。没有UI，没有I/O假设超出路径。 | | **表面** | `_cli/`、`_mcp/`、`_django/`、`_ports/` | 四个用户界面（CLI、AI代理的MCP工具、Django网页编辑器、可选桥梁）。每个都委托给引擎；它们从不绕过它们。 | `_django` 编辑器 + 查看器使用与本地和 `scitex.ai/apps/writer/` 相同的代码（没有单独的云端实现）。可选的 sibling集成（`_ports/scholar.py`等）遵循 `*_AVAILABLE` 标志模式来自 `scitex-python` — 如果 peer 未安装，桥梁将静默降级。 参见下面的“**四接口**”以获取每个表面的使用详情。 ## 四个接口 | 接口 | 适用于 | 描述 | |-----------|-----|-------------| | **Python API** | 人类研究人员 | `import scitex_writer as sw` | | **命令行界面（CLI）命令** | 终端用户 | `scitex-writer compile`、`scitex-writer bib` | | **MCP工具** | AI代理 | 44种工具用于Claude/GPT集成 | | **技能** | AI代理发现 | 能力和模式的工作流指南 | <details open> <summary><strong>Python API</strong></summary> **编译** — 构建PDF ```python import scitex_writer as sw sw.compile.manuscript("./my-paper") # 完整编译 sw.compile.manuscript("./my-paper", draft=True) # 快速草稿模式 sw.compile.supplementary("./my-paper") sw.compile.revision("./my-paper", track_changes=True) ``` **导出** — arXiv提交 ```python sw.export.manuscript("./my-paper") # arXiv-ready tarball sw.export.manuscript("./my-paper", output_dir="/tmp") # 自定义输出目录 ``` **表格/图表/参考书目** — 创建、读取、更新、删除（CRUD）操作 ```python # 表格 sw.tables.list("./my-paper") sw.tables.add("./my-paper", "results", "a,b\n1,2", "结果摘要") sw.tables.remove("./my-paper", "results") # 图表 sw.figures.list("./my-paper") sw.figures.add("./my-paper", "fig01", "./plot.png", "我的图表") sw.figures.remove("./my-paper", "fig01") # 参考书目 sw.bib.list_files("./my-paper") sw.bib.add("./my-paper", "@article{Smith2024, title={...}}") sw.bib.merge("./my-paper") # 合并 + 去重 ``` **指南** — 引言、方法、结果和讨论（IMRAD）写作技巧 ```python sw.guidelines.get("abstract") sw.guidelines.build("abstract", draft="您的草稿...") sw.guidelines.list_sections() # ['abstract', 'introduction', 'methods', 'discussion', 'proofread'] ``` **提示** — AI2 Asta ```python from scitex_writer import generate_asta result = generate_asta("./my-paper", search_type="related") ``` **GUI** — 基于浏览器的编辑器 ```python sw.gui("./my-paper") # 启动编辑器 sw.gui("./my-paper", port=8080, dark_mode=True) # 自定义选项 ``` </details> <details> <summary><strong>CLI命令</strong></summary> ```bash scitex-writer --help # 显示所有命令 # 编译 - 构建PDF scitex-writer compile manuscript # 编译手稿 scitex-writer compile manuscript --draft # 快速单次编译 scitex-writer compile supplementary # 编译补充材料 scitex-writer compile revision # 编译修订信 # 导出 - arXiv提交 scitex-writer export manuscript # 打包用于arXiv上传 # 检查 - 提交前验证 scitex-writer check-references # 交叉引用、引用、标签、重复标题 scitex-writer check-limits # 章节字数限制 + 参考文献上限（配置驱动） # 更新 - 从模板同步引擎文件 scitex-writer update-project # 预览漂移的引擎文件（安全；传递--yes以应用） # 参考书目 - 参考文献管理 scitex-writer bib list-files # 列出.bib文件 scitex-writer bib list-entries # 列出所有条目 scitex-writer bib get Smith2024 # 获取特定条目 scitex-writer bib add '@article{...}' # 添加条目 scitex-writer bib remove Smith2024 # 删除条目 scitex-writer bib merge # 合并和去重 # 表格 - CSV到LaTeX管理 scitex-writer tables list # 列出表格 scitex-writer tables add results data.csv "Caption" scitex-writer tables remove results # 图表 - 图片管理 scitex-writer figures list # 列出图表 scitex-writer figures add fig01 plot.png "Caption" scitex-writer figures remove fig01 # 指南 - IMRAD写作技巧 scitex-writer guidelines list # 列出可用章节 scitex-writer guidelines abstract # 获取摘要指南 scitex-writer guidelines abstract -d draft.tex # 使用草稿构建提示 # 提示 - AI2 Asta集成 scitex-writer prompts asta # 生成相关论文提示 scitex-writer prompts asta -t coauthors # 查找合作者 # MCP服务器管理 scitex-writer mcp list-tools # 列出所有MCP工具（markdown） scitex-writer mcp doctor # 检查服务器健康状况 scitex-writer mcp install # 显示Claude Desktop配置 scitex-writer mcp start # 启动MCP服务器 ``` # GUI - 基于浏览器的编辑器 scitex-writer gui # 启动编辑器（当前目录） scitex-writer gui ./my-paper # 打开特定项目 scitex-writer gui --port 8080 --no-browser # 自定义端口，不自动打开 </details> <details> <summary><strong>MCP 工具 — 面向 AI 代理的 44 种工具</strong></summary> 将 AI 代理转变为自主手稿编译器。 | 类别 | 工具 | 描述 | |----------|-------|-------------| | 项目 | 4 | 克隆，信息，PDF 路径，文档类型 | | 编译 | 4 | 手稿，补充，修订，内容 | | 表格 | 6 | CSV 到 LaTeX，列表/添加/删除，存档 | | 图形 | 6 | 转换，渲染 PDF，列表/添加/删除，存档 | | 引用 | 6 | 列表文件/条目，CRUD，合并/去重 | | 指南 | 3 | 列表，获取，构建草稿 | | 提示 | 1 | AI2 Asta 提示生成 | | 导出 | 1 | arXiv-ready tarball 打包 | | 声称 | 6 | 可追溯的科学断言 | | 迁移 | 2 | Overleaf 导入/导出 | | 检查 | 2 | 参考完整性，浮动顺序 | | 技能 | 2 | 列表和检索技能页面 | | 更新 | 1 | 带有漂移检测的引擎文件同步 | **Claude 桌面端**（`~/.config/Claude/claude_desktop_config.json`）： ```json { "mcpServers": { "scitex-writer": { "command": "scitex-writer", "args": ["mcp", "start"] } } } ``` > **[完整的 MCP 工具参考](./docs/MCP_TOOLS.md)** </details> <details> <summary><strong>技能 — 面向 AI 代理发现</strong></summary> <br> 技能提供工作流导向的指南，AI 代理查询以发现功能和用法模式。 ```bash scitex-writer skills list # 列出可用的技能页面 scitex-writer skills get SKILL # 显示主要技能页面 scitex-dev skills export --package scitex-writer # 导出到 Claude 代码 ``` | 技能 | 内容 | |-------|---------| | `quick-start` | 基本手稿工作流 | | `compilation` | 编译手稿，补充，修订 | | `bibliography` | BibTeX 管理，丰富 | | `figures-and-tables` | 图形/表格插入和转换 | | `claims` | 声明跟踪和渲染 | | `cli-reference` | CLI 命令 | | `mcp-tools` | 面向 AI 代理的 MCP 工具 | | `writing-attitude` | 证据要求，科学标准 | | `writing-figures-stats` | 图形规则，统计报告 | | `writing-proofreading` | 校对纠正，语言规则 | | `writing-abstract` | 摘要模板，7 节结构 | | `writing-introduction` | 引言模板，8 节结构 | | `writing-methods` | 方法模板，可重复性指南 | | `writing-discussion` | 讨论模板，5 节结构 | | `audit-paper` | 全面的提交前手稿审计 | </details> <details> <summary><strong>其他接口</strong></summary> **Shell 脚本 / Make** — 直接编译，无需 Python。 ```bash make manuscript # 编译手稿 make supplementary # 编译补充材料 make revision # 编译修订 make all # 编译所有文档 make manuscript-export # 打包提交到 arXiv make clean # 删除构建产物 ./compile.sh manuscript --draft # 快速单次编译 ./compile.sh manuscript --no-figs # 跳过图形 ./compile.sh manuscript --dark-mode # 黑色模式（Monaco 主题） ./compile.sh manuscript --watch # 热重载 SCITEX_WRITER_DARK_MODE=true make manuscript ``` **GUI 编辑器** — 带有文件树，PDF 预览和编译控件的独立基于浏览器的编辑器。 <p align="center"> <img src="docs/demo-gui-light.png" alt="GUI 浅色模式" width="380"/> &nbsp;&nbsp; <img src="docs/demo-gui-dark.png" alt="GUI 深色模式" width="380"/> </p> ```bash pip install scitex-writer[editor] scitex-writer gui # 当前目录 scitex-writer gui ./my-paper # 特定项目 scitex-writer gui --port 8080 # 自定义端口 ``` </details> <details> <summary><strong>输出结构</strong></summary> ``` ./scitex-writer/ ├── 00_shared/ # 所有文档共享资源 │ ├── title.tex / authors.tex / keywords.tex / journal_name.tex │ ├── bib_files/ # 多个 .bib 文件（自动合并和去重） │ ├── latex_styles/ # 公共 LaTeX 配置 │ └── templates/ # LaTeX 文档模板 ├── 01_manuscript/ # 主要手稿 │ ├── contents/ # 摘要，引言，方法，结果，讨论 │ │ ├── figures/ # 图形标题 + 媒体 │ │ └── tables/ # 表格标题 + CSV 数据 │ ├── archive/ # 版本历史（gitignored） │ ├── manuscript.tex # 编译 LaTeX │ ├── manuscript_diff.tex # 变更跟踪版本 │ └── manuscript.pdf # 输出 PDF ├── 02_supplementary/ # 补充材料（相同结构） ├── 03_revision/ # 修订响应信 │ └── contents/ # editor/，reviewer1/，reviewer2/ ├── config/ # config_manuscript.yaml └── scripts/ # 容器，安装，shell，python ``` </details> ## 功能 <details> <summary><strong>详情</strong></summary> | 功能 | 描述 | |------------------------|-----------------------------------------------------------------------| | **分离文件** | 模块化章节（摘要，引言，方法，结果，讨论） | | **内置模板** | 预配置的手稿，补充材料和修订 | | **参考文献** | 多文件自动去重，20+ 引用样式 | | **资产** | 并行图形/表格处理（PNG，PDF，SVG，Mermaid，CSV） | | **GUI 编辑器** | 基于浏览器的编辑器，带有 PDF 预览（`scitex-writer gui`） | | **黑暗模式** | Monaco/VS Code 黑色主题，舒适阅读（`--dark-mode`） | | **章节限制** | 每个 IMRAD 章节的字数上限 + 参考文献上限，编译前检查 | | **多引擎** | 自动选择最佳引擎（Tectonic 1-3s，latexmk 3-6s，3-pass 12-18s） | | **跨平台** | Linux，macOS，WSL2，Docker，Singularity，HPC 集群 | </details> ## 用法 <details> <summary><strong>PDF 编译</strong></summary> ```bash # 基本编译 ./scripts/shell/compile_manuscript.sh # 手稿 ./scripts/shell/compile_supplementary.sh # 补充材料 ./scripts/shell/compile_revision.sh # 修订信 # 性能选项 ./scripts/shell/compile_manuscript.sh --draft # 快速单次编译 ./scripts/shell/compile_manuscript.sh --no-figs # 跳过图形 ./scripts/shell/compile_manuscript.sh --no-tables # 跳过表格 ./scripts/shell/compile_manuscript.sh --no-diff # 跳过差异生成 # 引擎选择 ./scripts/shell/compile_manuscript.sh --engine tectonic # 最快 ./scripts/shell/compile_manuscript.sh --engine latexmk # 标准 ./scripts/shell/compile_manuscript.sh --engine 3pass # 最兼容 # 开发 ./scripts/shell/compile_manuscript.sh --watch # 文件更改时热重载 ./scripts/shell/compile_manuscript.sh --clean # 删除缓存 ``` </details> <details> <summary><strong>图形</strong></summary> 1. 将媒体文件放在 `01_manuscript/contents/figures/caption_and_media/` 下： ``` 01_example_figure.png 01_example_figure.tex # 标题文件 ``` 2. 标题文件格式（`01_example_figure.tex`）： ```latex %% 图形标题 \caption{您的图形标题。解释面板（A，B，C）如果适用。} \label{fig:example_figure_01} ``` 3. 支持的格式：PNG，JPEG，PDF，SVG，TIFF，Mermaid（.mmd） 4. 图形自动编译并包含在 `FINAL.tex` 中 </details> <details> <summary><strong>表格</strong></summary> 1. 将 CSV + 标题放在 `01_manuscript/contents/tables/caption_and_media/` 下： ``` 01_example_table.csv 01_example_table.tex # 标题文件 ``` 2. CSV 自动转换为 LaTeX 表格格式 3. 标题文件格式（`01_example_table.tex`）： ```latex %% 表格标题 \caption{您的表格标题。定义使用的缩写。} \label{tab:example_table_01} ``` </details> <details> <summary><strong>参考文献</strong></summary> 组织参考文献到多个 `.bib` 文件中 - 它们自动合并并去重： ```bash 00_shared/bib_files/ ├── methods_refs.bib # 方法相关参考文献 ├── field_background.bib # 背景文献 └── my_papers.bib # 您自己的出版物 ``` 在 `config/config_manuscript.yaml` 中更改引用样式： - `unsrtnat`（编号，引用顺序） - `plainnat`（编号，字母顺序） - `apalike`（作者-年份，APA 样式） - `IEEEtran`（IEEE 格式） - `naturemag`（Nature 样式） </details> ## 文档 <details> <summary><strong>详情</strong></summary> | 指南 | 描述 | |-------|-------------| | [安装](docs/01_GUIDE_INSTALLATION.md) | 所有环境的设置 | | [快速开始](docs/01_GUIDE_QUICK_START.md) | 常见工作流 | | [内容创建](docs/01_GUIDE_CONTENT_CREATION.md) | 编写手稿 | | [参考文献](docs/01_GUIDE_BIBLIOGRAPHY.md) | 参考文献管理 | | [架构](docs/02_ARCHITECTURE_IMPLEMENTATION.md) | 技术细节 | </details> --- <p align="center"> <a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a> <br> AGPL-3.0 </p> <!-- EOF -->