scitex-python

<!-- --- !-- Timestamp: 2026-03-23 01:22:48 !-- Author: ywatanabe !-- File: /home/ywatanabe/proj/scitex-python/README.md !-- --- --> # SciTeX (<code>scitex</code>) <p align="center"> <a href="https://scitex.ai"> <img src="docs/assets/images/scitex-logo-blue-cropped.png" alt="SciTeX" width="400"> </a> </p> <p align="center"><b>Python 科学计算库，适用于 AI 和人类研究人员</b></p> <p align="center"> <a href="https://badge.fury.io/py/scitex"><img src="https://badge.fury.io/py/scitex.svg" alt="PyPI 版本"></a> <a href="https://pypi.org/project/scitex/"><img src="https://img.shields.io/pypi/pyversions/scitex.svg" alt="Python 版本"></a> <a href="https://scitex-python.readthedocs.io"><img src="https://readthedocs.org/projects/scitex-python/badge/?version=latest" alt="文档"></a> <a href="https://codecov.io/gh/ywatanabe1989/scitex-python"><img src="https://img.shields.io/codecov/c/github/ywatanabe1989/scitex-python/develop?label=cov" alt="代码覆盖率"></a> <a href="https://github.com/ywatanabe1989/scitex-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ywatanabe1989/scitex-python" alt="许可证"></a> </p> <p align="center"> <a href="https://scitex-python.readthedocs.io">文档</a> &middot; <a href="https://scitex-python.readthedocs.io/en/latest/quickstart.html">快速开始</a> &middot; <a href="https://scitex-python.readthedocs.io/en/latest/api/index.html">API</a> &middot; <code>pip install scitex[all]</code> </p> --- 该仓库提供 `scitex`，SciTeX 生态系统的核心层 —— 解决科学研究中的关键问题： ## 问题与解决方案 | # | 问题 | 解决方案 | |---|---------|----------| | 1 | **工具碎片化** -- 文献搜索、统计、绘图和写作需要独立的工具，且格式不兼容 | **统一工具包** -- `import scitex as stx` 提供 73 个模块，统一在一个命名空间下，可通过 Python API、CLI 和 MCP 访问。这些模块是独立的包，但通过插件注册表松散耦合 —— 每个模块都可以独立工作，但可以组合成协同工作（保存图表 → 自动导出 CSV + YAML 配置文件 → 由 Clew 进行哈希跟踪 → 在 scitex-writer 中可引用） | | 2 | **缺乏验证** -- 现有工具关注工作是否可以被复现，而不是是否已经被验证 | **加密验证** -- Clew 构建 SHA-256 哈希链 DAG，将每个论文声明链接回源数据 | | 3 | **AI 代理缺乏上下文** -- 通用 LLM 无法在整个研究生命周期中运行，而需要特定领域的工具 | **323 个 MCP 工具** -- AI 代理可以通过结构化的工具调用运行统计、创建图表、搜索文献和编译论文 | | 4 | **缺乏自定义工具** -- 每个实验室都需要特定领域的工具，但构建和共享这些工具需要深入的基础设施知识 | **应用商店和创建工具** -- 研究人员使用 [scitex-app](https://github.com/ywatanabe1989/scitex-app) SDK 创建自定义应用，并通过 [SciTeX Cloud](https://scitex.ai) 共享 | | 5 | **供应商锁定** -- 云研究工具（Overleaf、Zotero、Mendeley、Colab、GitHub Copilot）将数据保存在第三方服务器上，并依赖可能突然消失或商业化的 API | **开放和自托管** -- 每个 SciTeX 包都是 AGPL-3.0 许可证；整个 39 包生态系统可以在您自己的硬件上运行（或 SciTeX Cloud 自身也是可自托管的）；云集成是可插拔的额外功能，而不是必需品 | ## SciTeX 与研究工作流 <p align="center"> <img src="scripts/assets/workflow_out/workflow.png" alt="SciTeX 研究工作流" width="600"> </p> <p align="center">_{<b>图 1.</b> SciTeX 研究流程 —— 从文献搜索到论文编译，每个步骤都经过加密链接。}</p> ## 演示 —— 从数据到论文的自动化研究 **40 分钟，最小化人工干预** —— 使用 SciTeX 的 AI 代理完成了一个完整的研究周期：文献搜索、统计分析、出版-ready 图表、21 页论文和同行评议模拟。更多演示请访问 [https://scitex.ai/demos/](https://scitex.ai/demos/)。 <p align="center"> <a href="https://scitex.ai/demos/watch/scitex-automated-research/"> <img src="docs/assets/images/scitex-demo.gif" alt="SciTeX 演示" width="800"> </a> </p> ## 安装 ```bash # 推荐使用 uv 解析器，约 3 分钟（比 pip 快 10-30 倍） uv pip install "scitex[all]" # 普通 pip 也可用，但预计需要 30-90 分钟 —— 因为 pip 的解析器会回溯 # 大量依赖项。见下面的安装提示。 pip install "scitex[all]" ``` > **为什么使用 uv？** `scitex[all]` 提取大量的传递性依赖项 > （numpy/pandas/torch/jax/playwright/openalex-local/sphinx-rtd-theme/…）。 > pip 的串行解析器会遍历版本历史，尝试满足 > 每个约束，并可能花费 30 多分钟下载元数据 > 然后安装单个轮子。uv 并行解析相同的集合 > 在 1-3 分钟内。一次性安装 uv > `pip install uv` （或 `curl -LsSf https://astral.sh/uv/install.sh | sh`）。 <details> <summary><strong>每个模块的额外依赖</strong></summary> ```bash pip install scitex # 仅核心（最小） pip install scitex[plt,stats,scholar] # 典型研究设置 pip install scitex[plt] # 出版-ready 图表（figrecipe） pip install scitex[stats] # 统计测试（23+ 测试） pip install scitex[scholar] # 文献搜索、PDF 下载、BibTeX 增强 pip install scitex[writer] # LaTeX 论文编译 pip install scitex[audio] # 文本转语音 pip install scitex[ai] # LLM API（OpenAI、Anthropic、Google）+ 机器学习工具 pip install scitex[dataset] # 科学数据集（DANDI、OpenNeuro、PhysioNet） pip install scitex[browser] # 网页自动化（Playwright） pip install scitex[capture] # 截图捕获和监控 pip install scitex[cloud] # 云平台集成 ``` 需要 Python 3.10+。在上面的命令中添加 `uv ` （例如 `uv pip install scitex[plt,stats,scholar]`) 以获得 10-30 倍更快的解析速度。 </details> <details> <summary><strong>安装提示 — 超时、镜像、<code>[all]</code> 大小</strong></summary> `scitex[all]` 提取完整的 33 包生态系统和大量额外依赖项（Playwright 浏览器、torch、jax、pymupdf、Apptainer/Docker 集成等）。使用 **普通 pip** 时，这需要 **30-90 分钟**，因为 pip 的解析器在传递性集合上会卡住；而使用 **uv** 时，只需要约 3 分钟。推荐的优先级顺序是： ```bash # 1. uv（推荐）—— 并行 Rust 解析器，速度快 10-30 倍 pip install uv && uv pip install "scitex[all]" # 2. pip 带有扩展超时（默认 15s 在慢速链接上中止） pip install --timeout 600 --retries 5 "scitex[all]" # 3. 分组安装，如果单个运行持续失败 uv pip install scitex[io,stats,plt] # 核心分析层 uv pip install scitex[scholar,writer] # 研究层 uv pip install scitex[audio,browser,dataset,cloud] # 重大额外依赖 # 4. 镜像 —— 用于 pypi.org 不可靠的网络 uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "scitex[all]" ``` 如果单个依赖项挂起，请使用 `pip install -v` 识别它，并单独安装该包，使用 `--no-deps`，然后继续完整安装。 </details> <details> <summary><strong>模块概述</strong></summary> | 类别 | 模块 | 描述 | |----------|---------|-------------| | **核心** | `session`, `io`, `config`, `clew` | 实验跟踪、文件 I/O、配置、加密验证 | | **分析** | `stats`, `plt`, `dsp`, `linalg` | 统计、绘图、信号处理、线性代数 | | **研究** | `scholar`, `writer`, `diagram`, `canvas` | 文献、论文、图表、图形 | | **机器学习/AI** | `ai`, `nn`, `torch`, `cv`, `benchmark` | LLM API、神经网络、PyTorch、计算机视觉 | | **数据** | `pd`, `db`, `dataset`, `schema` | Pandas 实用程序、数据库、科学数据集 | | **基础设施** | `app`, `cloud`, `tunnel`, `container` | 应用 SDK、云、SSH 隧道、容器 | | **自动化** | `browser`, `capture`, `audio`, `notification` | 网页自动化、截图、文本转语音、通知 | | **开发** | `dev`, `template`, `linter`, `introspect` | 生态系统工具、脚手架、代码分析 | </details> ## 架构 — 包（3 层级联） 33 包生态系统遵循严格的 **依赖级联**：上游导入中间层，中间层导入下游，从不反向。下游应用必须独立工作；伞形工具只负责协调。 ``` 上游（协调层 — SOC，仅集成测试） scitex（scitex-python），scitex-cloud │ 导入/重新暴露 ▼ 中间层（共享基础设施 — 包装，不替换） scitex-io, scitex-stats, scitex-app, scitex-ui, scitex-audio, scitex-dev │ 通过插件注册表集成/包装 ▼ 下游（独立应用 — 自己的 I/O/GUI，单元测试） figrecipe, scitex-writer, scitex-scholar, scitex-clew, scitex-notebook, scitex-dataset, scitex-ssh, scitex-container, scitex-browser, scitex-linter, openalex-local, crossref-local, socialia, + 实用程序 （scitex-{path,str,dict,logging,types,db,repro,audit,parallel,compat,gists,etc,core}） ``` **单行契约**：下游不知道上游存在；上游不重复下游逻辑。见 [01_ecosystem_01_upstream-and-downstream.md](https://github.com/ywatanabe1989/scitex-dev/blob/main/src/scitex_dev/_skills/general/01_ecosystem_01_upstream-and-downstream.md) 获取完整规则（测试、级联、接口）和 [01_ecosystem_02_dependency-and-version-pinning.md](https://github.com/ywatanabe1989/scitex-dev/blob/main/src/scitex_dev/_skills/general/01_ecosystem_02_dependency-and-version-pinning.md) 获取依赖固定。 ## 三个接口 SciTeX 伞形工具的每个功能都可以通过三个接口访问，因此人类和 AI 代理共享一个工具包： | 接口 | 入口点 | 示例 | |-----------|-------------|---------| | **Python API** | `import scitex as stx` | `stx.io.save(fig, "result.png")` | | **CLI** | `scitex <group> <command>` | `scitex io convert data.csv data.parquet` | | **MCP** | `scitex mcp start` | 323 个工具，AI 代理可以直接调用 | Python API 是主要接口；CLI 和 MCP 服务器为 shell 和 AI 代理公开相同的逻辑。见下面的 [快速开始](#快速开始) 获取可运行的 Python 示例和 [完整的 MCP 参考](./docs/02_MCP_TOOLS.md)。 ## 快速开始 <details> <summary><strong><code>@scitex.session</code> -- 可复制的实验跟踪</strong></summary> 一个装饰器提供：自动 CLI、YAML 配置注入、随机种子固定、结构化输出和日志记录。 ```python import scitex as stx import numpy as np @stx.session def main( data_path: str = "./data.csv", # --data-path data.csv n_samples: int = 100, # --n-samples 200 CONFIG=stx.session.INJECTED, # 聚合 ./config/*.yaml plt=stx.session.INJECTED, # 预配置的 matplotlib logger=stx.session.INJECTED, # 会话日志记录器 ): """分析数据。文档字符串成为 --help 文本。""" # 加载 data = stx.io.load(data_path) # 演示数据 x = np.linspace(0, 2 * np.pi, n_samples) y = np.sin(x) + np.random.randn(n_samples) * 0.1 # FigRecipe 绘图 fig, ax = stx.plt.subplots() ax.plot(x, y) ax.set_xyt("时间", "幅度", "噪声正弦波") # 保存 sine.png + sine.csv，并带有日志消息 stx.io.save(fig, "sine.png") return 0 if __name__ == "__main__": main() ``` ```bash $ python script.py --data-path experiment.csv --n-samples 200 $ python script.py --help # 用法：script.py [-h] [--data-path DATA_PATH] [--n-samples N_SAMPLES] # 分析数据。文档字符串成为 --help 文本。 ``` ``` script_out/FINISHED_SUCCESS/2026-03-18_14-30-00_Z5MR/ ├── sine.png, sine.csv # 图表 + 自动导出的绘图数据 ├── CONFIGS/CONFIG.yaml # 冻结的参数 └── logs/{stdout,stderr}.log # 执行日志 ``` 注入的 `CONFIG` 是一个 `DotDict`，合并 YAML 用户配置和会话解析的键： | 键 | 含义 | |-----|---------| | `CONFIG.ID` | 会话标识符，例如 `2026-04-23T21-30-00_Z5MR` | | `CONFIG.PID` | Python 进程 ID | | `CONFIG.START_DATETIME` | 会话开始时间 | | `CONFIG.FILE` | 调用脚本的路径 | | `CONFIG.SDIR_OUT` | 基本输出目录，例如 `analysis_out/` | | `CONFIG.SDIR_RUN` | 此运行的目录，例如 `analysis_out/FINISHED_SUCCESS/<ID>/` | | `CONFIG.ARGS` | 解析的 CLI 参数 | | `CONFIG.MODEL.*` | 来自 `./config/MODEL.yaml` 的值（每个 YAML 文件一个命名空间） | 使用 `CONFIG.SDIR_RUN / "results.csv"` 重新加载在同一会话中较早保存的文件。`CONFIG` 的冻结副本保存在 `CONFIG.SDIR_RUN/CONFIGS/{CONFIG.yaml,CONFIG.pkl}`，因此任何运行都是完全可审计的。见 [会话配置文档](https://scitex-python.readthedocs.io/en/latest/api/session.html) 获取完整参考。 </details> <details> <summary><strong><code>scitex.io</code> -- 统一文件 I/O（50+ 格式）</strong></summary> ```python import scitex as stx # 保存和加载 — 格式从扩展名中检测。 # symlink_from_cwd=True 在 cwd 处放置一个符号链接，以便文件名可以正常工作； # 没有它，save() 会路由到 <script>_out/，而 load() 必须使用绝对路径。 stx.io.save(df, "results.csv", symlink_from_cwd=True) df = stx.io.load("results.csv") stx.io.save(arr, "data.npy", symlink_from_cwd=True) arr = stx.io.load("data.npy") stx.io.save(fig, "figure.png") # 还导出图表数据为 CSV stx.io.save(config, "config.yaml") stx.io.save(model, "model.pkl") # 聚合 ./config/*.yaml 到单个 DotDict CONFIG = stx.io.load_configs(config_dir="./config") print(CONFIG.MODEL.hidden_size) # 点符号访问 # 注册自定义格式 @stx.io.register_saver(".custom") def save_custom(obj, path, **kw): with open(path, "w") as f: f.write(str(obj)) @stx.io.register_loader(".custom") def load_custom(path, **kw): with open(path) as f: return f.read() ``` 支持：CSV、JSON、YAML、TOML、HDF5、NPY、NPZ、PKL、PNG、JPG、SVG、PDF、Excel、Parquet、Zarr、INI、TXT、MAT、WAV、MP3、BibTeX 等。 **内置功能**：自动目录创建、路径解析到 `<script_name>_out/>`、符号链接（`symlink_from_cwd=True`）、保存日志记录文件大小和 Clew 哈希跟踪。 </details> <details> <summary><strong><code>scitex.plt</code> -- 可复制、样式可定制图表</strong></summary> 由 [figrecipe](https://github.com/ywatanabe1989/figrecipe) 驱动。图表是 **可复制的节点** 在 Clew 验证 DAG 中 —— 科学数据和视觉样式被分解，因此图表可以在不改变底层数据哈希的情况下重新样式化（字体、颜色、布局）。每个图表都自动导出其数据为 CSV + YAML 配置文件，以便精确复制。 ```python import scitex as stx fig, axes = stx.plt.subplots(1, 3) axes[0].stx_line(x, y) axes[0].set_xyt("时间", "值", "线") axes[1].stx_violin([g1, g2, g3]) axes[1].set_xyt("组", "分数", "小提琴") axes[2].stx_heatmap(corr_matrix) axes[2].set_xyt("X", "Y", "热图") stx.io.save(fig, "analysis.png") # 保存 analysis.png + analysis.csv + analysis.yaml # 在不更改数据的情况下重新样式化（哈希仍然有效） stx.plt.reproduce("analysis.yaml", style="nature") ``` </details> <details> <summary><strong><code>scitex.stats</code> -- 出版-ready 统计数据（23+ 测试）</strong></summary> ```python import scitex as stx result = stx.stats.run_test("ttest_ind", group1, group2, return_as="dataframe") ``` # 返回值：p值、效应大小（Cohen's d）、置信区间、正态性检验、功效 recommendations = stx.stats.recommend_tests(data) stx.stats.annotate(ax, test=result, style="apa") # 星号 + "t(58) = 2.34, p = .021, d = 0.60" 在 matplotlib 坐标轴上 </details> <details> <summary><strong><code>scitex.scholar</code> -- 文献管理</strong></summary> 搜索、下载、丰富论文。支持本地 CrossRef（1.67亿+）和 OpenAlex（2.5亿+）数据库。 ```python import scitex as stx scholar = stx.scholar.Scholar() # 延迟加载库 papers = scholar.process_papers(["神经振荡 工作记忆"]) scholar.download_pdfs_from_dois(["10.1038/s41586-024-07804-3"]) scholar.enrich_papers(bibtex_path="references.bib") ``` ```bash scitex scholar crossref-scitex search "神经振荡" --abstracts scitex scholar fetch --from-bibtex references.bib --project myproject ``` </details> <details> <summary><strong><code>scitex.writer</code> -- LaTeX 手稿编译</strong></summary> ```python import scitex as stx stx.writer.compile.manuscript("paper/") # latexmk 包装器 stx.writer.figures.add("paper/", "results.png", caption="主要结果") stx.writer.tables.add("paper/", "stats.csv", caption="统计摘要") ``` </details> <details> <summary><strong><code>scitex.notification</code> -- 多后端通知</strong></summary> 在实验完成时通过桌面、电话、短信或电子邮件通知，并自动降级。 ```python import scitex as stx stx.notification.alert("实验完成：准确率 = 94.2%") stx.notification.call("训练发散 -- 损失为 NaN") stx.notification.sms("GPU 作业在 node-42 上完成") @stx.session(notify=True) # 在完成或失败时通知 def main(CONFIG=stx.session.INJECTED): ... ``` </details> <details> <summary><strong><code>scitex.clew</code> -- AI 驱动科学的加密验证</strong></summary> 当 AI 代理大规模生产研究时，问题从 *"这可以重现吗？"* 转变为 *"这已经被验证了吗？"*。Clew 构建了一个 **SHA-256 哈希链 DAG**，将每个手稿声明链接回源数据。 ```python import scitex as stx # 每个 stx.io.load/save 自动记录文件哈希 -- 零配置 stx.clew.status() # {'verified': 12, 'mismatched': 0, 'missing': 0} stx.clew.chain("results/figure1.png") # 追溯一个文件到源数据 stx.clew.dag(claims=True) # 验证所有手稿声明 # 注册可追溯的断言 stx.clew.add_claim( file_path="paper/main.tex", claim_type="statistic", line_number=142, claim_value="t(58) = 2.34, p = .021", source_session="2026-03-18_14-30-00_Z5MR", source_file="results/stats.csv", ) stx.clew.mermaid(claims=True) # 可视化 provenance DAG ``` | 模式 | 函数 | 答案 | |------|----------|---------| | **项目** | `clew.dag()` | 整个项目是否完整？ | | **文件** | `clew.chain("output.csv")` | 我可以信任这个特定文件吗？ | | **声明** | `clew.verify_claim("Fig 1")` | 这个手稿断言有效吗？ | **L1** 哈希比较（毫秒）/ **L2** 沙盒重新执行（分钟）/ **L3** 已注册时间戳证明（可选）。 <p align="center"> <img src="docs/clew-dag.png" alt="Clew DAG" width="300"> </p> <p align="center">_{<b>图 2.</b> Clew 验证 DAG -- 绿色节点已验证（哈希匹配），红色节点有不匹配。每个节点显示其 SHA-256 哈希前缀。}</p> </details> <details> <summary><strong><code>scitex.audio</code> -- 文本转语音（ElevenLabs / LuxTTS / gTTS / pyttsx3）</strong></summary> ```python import scitex as stx stx.audio.speak("训练完成。准确率 94%。") stx.audio.speak("离线模式", backend="pyttsx3") # 强制离线 stx.audio.speak("报告", output_path="report.mp3", play=False) # TTS → 文件 ``` 后端自动降级：ElevenLabs（付费，最高）→ LuxTTS（离线，48 kHz，语音克隆）→ gTTS（免费在线）→ pyttsx3（离线 espeak）。 </details> <details> <summary><strong><code>scitex.dataset</code> -- OpenNeuro / DANDI / PhysioNet / Zenodo 获取器</strong></summary> ```python import scitex as stx ds = stx.dataset.neuroscience.openneuro.fetch_all_datasets(max_datasets=10) stx.dataset.neuroscience.dandi.fetch_all_datasets(max_datasets=10) hits = stx.dataset.search_datasets(ds, text_query="相位幅度耦合") ``` 跨神经科学 / 生物医学 / 临床试验存储库的统一 API。 </details> <details> <summary><strong><code>scitex.container</code> -- Apptainer / Docker 管理</strong></summary> ```python import scitex as stx stx.container.apptainer.build(def_name="recipe") # 版本化 SIF stx.container.apptainer.switch_version("2.19.5") # 原子活动 SIF 切换 stx.container.apptainer.rollback() # 回滚到以前的版本 snap = stx.container.env_snapshot() # 用于论文的环境快照 ``` 可复制的 HPC 容器 — 构建、版本控制、回滚、环境快照用于手稿。 </details> <details> <summary><strong><code>scitex.tunnel</code> -- 持久 SSH 反向隧道</strong></summary> ```python import scitex as stx stx.tunnel.setup(port=8888, bastion_server="gw.example.com") stx.tunnel.status() # {"8888": "active"} ``` 用于实验室机器的 NAT 穿透 -- autossh 支持的 systemd 服务。 </details> <details> <summary><strong><code>scitex.linter</code> -- 47 规则约定检查器</strong></summary> ```python import scitex as stx issues = stx.linter.lint_file("src/") for i in issues: print(f"{i.filepath}:{i.line} [{i.rule.id}] {i.message}") ``` 检查 SciTeX 项目的生态系统约定（`stx.io.save` 使用、CONFIGS 命名、matplotlib 首选项、导入卫生）。补充 ruff/flake8。 </details> <details> <summary><strong><code>scitex.repro</code> -- 种子一切 + 数组哈希</strong></summary> ```python import scitex as stx rng = stx.repro.RandomStateManager(seed=42) # 种子随机 + numpy + torch + tf run_id = stx.repro.gen_ID() # "20260423_2155_abc12345" digest = stx.repro.hash_array(np_array) # 确定性 SHA ``` 一次调用种子所有 RNG；生成实验运行 ID；为指纹哈希数组。 </details> <details> <summary><strong><code>scitex.parallel</code> -- 带 tqdm 的线程映射</strong></summary> ```python import scitex as stx results = stx.parallel.run(download, [(u,) for u in urls], n_jobs=-1) ``` 用于 I/O 绑定工作的即插即用并行映射 -- HTTP 获取、文件读取、API 调用。内置 tqdm 进度条。 </details> <details> <summary><strong><code>scitex.path</code> -- 项目感知路径和会话目录</strong></summary> ```python import scitex as stx root = stx.path.find_git_root() # 向上遍历到 .git/ out = stx.path.get_spath("results.csv") # → {script}_out/results.csv stx.path.create_relative_symlink(src, dst) # 相对（可移植）符号链接 latest = stx.path.find_latest(".", "model_", ".pt") # model_v003.pt（最高版本） stx.path.fix_broken_symlinks("dir/", remove=True) # 清理悬挂链接 ``` 自动将保存路由到 `{script}_out/` 并解析会话范围路径，以便 `@stx.session` 脚本生成日期、哈希可跟踪的输出目录，无需样板代码。 </details> <details> <summary><strong><code>scitex.logging</code> -- 扩展日志 + 异常层次结构 + Tee</strong></summary> ```python import scitex as stx logger = stx.logging.getLogger(__name__) logger.success("训练在第 87 个纪元收敛") # SUCCESS 级别（自定义） logger.fail("验证损失发散") # FAIL 级别（自定义） # 具有 SciTeX 类别的结构化警告 stx.logging.warn_deprecated("old_api", replacement="new_api", version="3.0") stx.logging.warn_data_loss("NaN 值在列 'bp' 中被丢弃") # 类型异常（30+ 个 SciTeXError 子类） raise stx.logging.ShapeError("期望 (N, 2)，得到 (N, 3)") # Tee stdout/stderr 到日志文件 with stx.logging.Tee("run.log"): main() # 打印到屏幕 + 文件 ``` 扩展标准库 `logging`，具有 SUCCESS/FAIL 级别、30+ 个类异常树（`IOError`/`ShapeError`/`ConfigKeyError`/ ...）、结构化警告类别和 tee-to-file。`SCITEX_LOGGING_LEVEL` 环境变量设置默认导入级别。 </details> <details> <summary><strong><code>scitex.db</code> -- 带有 ndarray BLOB 存储的 SQLite3 / PostgreSQL</strong></summary> ```python import scitex as stx, numpy as np db = stx.db.SQLite3("experiments.db") with db: # 上下文管理器事务 db.execute("CREATE TABLE IF NOT EXISTS runs (id TEXT, acc REAL)") db.save_array("weights_epoch_87", np.random.rand(1024, 1024)) # 压缩 BLOB df = db.to_df("runs") # pandas 往返 w = db.load_array("weights_epoch_87") # 类型化 ndarray 返回 db.check_health() # 完整性 + 架构漂移 stx.db.delete_duplicates(conn, "runs", columns=["id"]) ``` 带有第一类压缩 ndarray BLOB、数据帧往返、健康检查和重复删除的 SQLite / PostgreSQL 客户端。当您不需要 ORM 时，替换手动滚动的 `pickle → BLOB` 存储或 SQLAlchemy Core。 </details> <details> <summary><strong><code>scitex.browser</code> -- 用于科学抓取的 Playwright 帮助程序</strong></summary> ```python import scitex as stx, asyncio async def grab_pdf(): async with stx.browser.SyncBrowserSession() as session: page = await session.new_page() await page.goto("https://journal.example/article/123") await stx.browser.click_with_fallbacks_async( page, ["button.download-pdf", "a[href$='.pdf']"] # 遍历选择器 ) await stx.browser.save_as_pdf_async(page, "article.pdf") asyncio.run(grab_pdf()) ``` Playwright 包装器，具有：Chrome-PDF-查看器下载帮助程序、弹出窗口/cookie 消除器（`close_popups_async`、`PopupHandler`）、光标/点击/步骤叠加层用于调试视频录制、控制台日志收集器、测试失败工件捕获。原始 Playwright 脚本 + 隐身插件的即插即用替换。 </details> <details> <summary><strong>实用模块 -- 低级帮助程序</strong></summary> | 模块 | 目的 | 关键 API | |--------|---------|---------| | `stx.str` | 文本 / LaTeX 备用 / 着色打印 | `printc`, `safe_latex_render`, `grep` | | `stx.dict` | `DotDict` + 安全合并 / 展平 | `DotDict`, `safe_merge`, `flatten` | | `stx.types` | 联盟类型别名 + 谓词 | `ArrayLike`, `ColorLike`, `is_array_like` | | `stx.audit` | 统一安全扫描（bandit / shellcheck / pip-audit） | `audit()` | | `stx.compat` | 弃用 shim | `@deprecated`, `notify` 旧别名 | | `stx.etc` | 终端按键帮助程序 | `wait_key`, `count` | 参见 [docs/05_ADDITIONAL_MODULES.md](./docs/05_ADDITIONAL_MODULES.md) 获取完整示例。 </details> > **[代理用法](./docs/06_AGENTIC_USAGE.md)** -- MCP 设置、示例提示、一次性输出和技能触发测试。 > **[完整 API 参考](https://scitex-python.readthedocs.io/en/latest/api/index.html)** · **[示例](./examples/)** · **[模块状态](./docs/04_MODULE_STATUS.md)** <details> <summary><strong>CLI 命令</strong></summary> ```bash scitex --help-recursive # 显示所有命令 scitex scholar crossref-scitex search "主题" # 搜索文献（CrossRef 1.67亿+） scitex scholar fetch "10.1038/..." # 按 DOI 下载论文 scitex stats recommend # 建议统计测试 scitex clew status # 项目验证概述 scitex clew dag --claims # 验证所有手稿声明 scitex audio speak "分析完成" # 文本转语音 scitex notification send "作业完成" # 多后端通知 scitex template clone research my_proj # 搭建项目 scitex dev ecosystem list # 检查生态系统版本 scitex mcp list-tools # 列出所有 MCP 工具（323） ``` > **[完整 CLI 参考](./docs/01_CLI_COMMANDS.md)** </details> <details> <summary><strong>MCP 服务器（23 个模块中的 323 个工具）</strong></summary> 通过 [MCP](https://modelcontextprotocol.io/) 将 AI 代理变成自主研究人员。 | 类别 | 工具 | | 类别 | 工具 | | 类别 | 工具 | |----------|-------|-|----------|-------|-|----------|-------| | plt | 73 | | crossref | 15 | | io | 5 | | cloud | 50 | | dev | 13 | | template | 4 | | writer | 38 | | introspect | 12 | | openalex | 4 | | scholar | 22 | | stats | 10 | | linter | 3 | | clew | 9 | | dataset | 8 | | social | 3 | | project | 6 | | notify | 5 | | tunnel | 3 | | docs | 4 | | ui | 2 | | usage | 2 | ```json {"mcpServers": {"scitex": {"command": "scitex", "args": ["mcp", "start"], "env": {"SCITEX_ENV_SRC": "${SCITEX_ENV_SRC}"}}}} ``` > **[完整 MCP 参考](./docs/02_MCP_TOOLS.md)** </details> ## 配置 ```bash cp -r .env.d.examples .env.d # 1. 复制示例 $EDITOR .env.d/ # 2. 编辑凭证 source .env.d/entry.src # 3. 在 shell 中加载 ``` > **[完整配置参考](./.env.d.examples/README.md)** ## SciTeX 生态系统 [`scitex-cloud`](https://github.com/ywatanabe1989/scitex-cloud) 是一个自托管的 Web 应用程序，作为协作研究工作空间 -- 带有内置的 Writer、Scholar 和应用商店，研究人员使用 [`scitex-app`](https://github.com/ywatanabe1989/scitex-app) SDK 和 [`scitex-ui`](https://github.com/ywatanabe1989/scitex-ui) 组件构建自定义工具，然后与社区分享。生产实例托管在 [scitex.ai](https://scitex.ai)。 <!-- hook-bypass: line-limit --> <details> <summary><strong>完整生态系统（37 个软件包，按主要接口分组）</strong></summary> 每个软件包都通过以下六个接口之一公开生态系统：Python 库、CLI、MCP 工具、Claude Code 技能、钩子以及 HTTP。评分：⭐⭐⭐ = 主要 / 规范表面，⭐⭐ = 强大的次要表面，⭐ = 薄，— = 不提供。软件包按其 **主要** 接口分组 -- 用户应首先访问的接口。 ### Python-first（库 API 是主要接口） | 软件包 | 模块 | 接口 | 描述 | |---------|--------|-----------|-------------| | [crossref-local](https://github.com/ywatanabe1989/crossref-local) | `stx.scholar` | Py ⭐⭐⭐ · CLI ⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 离线、零 API 密钥 DOI 查找 + 全文搜索 CrossRef 语料库 | | [openalex-local](https://github.com/ywatanabe1989/openalex-local) | `stx.scholar` | Py ⭐⭐⭐ · CLI ⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 离线、零 API 密钥搜索整个 OpenAlex 学术语料库 | | [scitex-browser](https://github.com/ywatanabe1989/scitex-browser) | `stx.browser` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 用于科学网页抓取和 AI 代理浏览的 Playwright 包装器 | | [scitex-compat](https://github.com/ywatanabe1989/scitex-compat) | `stx.compat` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐ · 钩子 — · HTTP — | 废弃 SciTeX API 的向后兼容性伪影 | | [scitex-core](https://github.com/ywatanabe1989/scitex-core) | `stx.core` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | SciTeX 生态系统的基础层 | | [scitex-dataset](https://github.com/ywatanabe1989/scitex-dataset) | `stx.dataset` | Py ⭐⭐⭐ · CLI ⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 跨 7 个科学存储库的统一数据集发现 API | | [scitex-db](https://github.com/ywatanabe1989/scitex-db) | `stx.db` | Py ⭐⭐⭐ · CLI ⭐ · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 用于科学 Python 的关系数据库包装器 | | [scitex-dict](https://github.com/ywatanabe1989/scitex-dict) | `stx.dict` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐ · 钩子 — · HTTP — | 科学 Python 的字典实用程序 | | [scitex-etc](https://github.com/ywatanabe1989/scitex-etc) | `stx.etc` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐ · 钩子 — · HTTP — | 杂项 SciTeX 实用程序 | | [scitex-gists](https://github.com/ywatanabe1989/scitex-gists) | `stx.gists` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐ · 钩子 — · HTTP — | SigmaPlot v12 宏代码片段作为可打印的 Python 函数 | | [scitex-logging](https://github.com/ywatanabe1989/scitex-logging) | `stx.logging` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 增强的 Python 日志记录 + 警告 + 异常，用于 SciTeX | | [scitex-parallel](https://github.com/ywatanabe1989/scitex-parallel) | `stx.parallel` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐ · 钩子 — · HTTP — | 科学 Python 的最小线程池并行执行 | | [scitex-path](https://github.com/ywatanabe1989/scitex-path) | `stx.path` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 科学 Python 的项目感知路径实用程序 | | [scitex-plt](https://github.com/ywatanabe1989/scitex-plt) | `stx.plt` | Py ⭐⭐⭐ · CLI — · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 发布就绪的绘图（对 figrecipe 的薄包装） | | [scitex-repro](https://github.com/ywatanabe1989/scitex-repro) | `stx.repro` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 科学 Python 实验的可复制性帮助程序 | | [scitex-stats](https://github.com/ywatanabe1989/scitex-stats) | `stx.stats` | Py ⭐⭐⭐ · CLI ⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 23 个测试的发布就绪统计测试 | | [scitex-str](https://github.com/ywatanabe1989/scitex-str) | `stx.str` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 科学 Python 的文本处理实用程序 | | [scitex-types](https://github.com/ywatanabe1989/scitex-types) | `stx.types` | Py ⭐⭐⭐ · CLI — · MCP — · 技能 ⭐ · 钩子 — · HTTP — | 科学 Python 的类型别名和运行时类型保护 | </details> ### CLI优先 | 软件包 | 模块 | 接口 | 描述 | |---------|--------|-----------|-------------| | [scitex-agent-container](https://github.com/ywatanabe1989/scitex-agent-container) | `stx.agent_container` | Python ⭐⭐ · 命令行 ⭐⭐⭐ · MCP — · 技能 ⭐⭐ · 钩子 — · HTTP — | 基于YAML的声明式AI代理生命周期管理（tmux/screen/SSH） | | [scitex-app](https://github.com/ywatanabe1989/scitex-app) | `stx.app` | Python ⭐⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | SciTeX工作区应用的开发人员SDK | | [scitex-audit](https://github.com/ywatanabe1989/scitex-audit) | `stx.audit` | Python ⭐ · 命令行 ⭐⭐⭐ · MCP ⭐ · 技能 ⭐ · 钩子 — · HTTP — | 统一的科学Python项目存储库安全扫描器 | | [scitex-clew](https://github.com/ywatanabe1989/scitex-clew) | `stx.clew` | Python ⭐⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 面向科学流程的基于哈希的可复制性验证 | | [scitex-container](https://github.com/ywatanabe1989/scitex-container) | `stx.container` | Python ⭐⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 面向Apptainer/Singularity + Docker的统一容器管理 | | [scitex-dev](https://github.com/ywatanabe1989/scitex-dev) | `stx.dev` | Python ⭐⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 用于维护整个SciTeX生态系统的开发人员实用工具 | | [scitex-notebook](https://github.com/ywatanabe1989/scitex-notebook) | `stx.notebook` | Python ⭐⭐ · 命令行 ⭐⭐⭐ · MCP ⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | Jupyter Notebook可复制性 — 验证，编译为DAG，转换为脚本 | | [scitex-ssh](https://github.com/ywatanabe1989/scitex-ssh) | `stx.tunnel` | Python ⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | SSH基本操作（执行/复制/附加）以及用于NAT穿越的门控、自动重新连接的反向隧道 | ### MCP优先 | 软件包 | 模块 | 接口 | 描述 | |---------|--------|-----------|-------------| | [scitex-audio](https://github.com/ywatanabe1989/scitex-audio) | `stx.audio` | Python ⭐⭐ · 命令行 ⭐ · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 统一的文本转语音并自动后端故障转移 | | [socialia](https://github.com/ywatanabe1989/socialia) | `stx.social` | Python ⭐ · 命令行 ⭐ · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 面向6个社交平台的统一发布 + 分析客户端 | ### 钩子优先 | 软件包 | 模块 | 接口 | 描述 | |---------|--------|-----------|-------------| | [scitex-linter](https://github.com/ywatanabe1989/scitex-linter) | `stx.linter` | Python ⭐ · 命令行 ⭐⭐ · MCP ⭐ · 技能 ⭐⭐ · 钩子 ⭐⭐⭐ · HTTP — | 面向可复制研究Python的基于AST的Linter（pre-commit钩子） | ### 混合（多个同等主要的接口） | 软件包 | 模块 | 接口 | 描述 | |---------|--------|-----------|-------------| | [figrecipe](https://github.com/ywatanabe1989/figrecipe) | `stx.plt` | Python ⭐⭐⭐ · 命令行 ⭐ · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 具有毫米精度布局的出版就绪matplotlib图形 | | [scitex-cloud](https://github.com/ywatanabe1989/scitex-cloud) | `stx.cloud` | Python ⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP ⭐⭐ | SciTeX云操作面（55个MCP工具） | | [scitex-io](https://github.com/ywatanabe1989/scitex-io) | `stx.io` | Python ⭐⭐⭐ · 命令行 ⭐ · MCP ⭐⭐ · 技能 ⭐⭐⭐ · 钩子 — · HTTP — | 面向30+科学格式的通用一次性文件I/O | | [scitex-notification](https://github.com/ywatanabe1989/scitex-notification) | `stx.notification` | Python ⭐⭐ · 命令行 ⭐ · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 跨9个后端的一次性提醒（音频/桌面/电子邮件/Telegram/...） | | [scitex-orochi](https://github.com/ywatanabe1989/scitex-orochi) | `stx.orochi` | Python ⭐⭐ · 命令行 ⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP ⭐⭐ | 代理通信中心 — 代理之间的实时WebSocket消息传递 | | [scitex-scholar](https://github.com/ywatanabe1989/scitex-scholar) | `stx.scholar` | Python ⭐⭐⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 端到端的科学文献工具包 | | [scitex-ui](https://github.com/ywatanabe1989/scitex-ui) | `stx.ui` | Python ⭐⭐ · 命令行 ⭐ · MCP ⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP ⭐⭐ | SciTeX Web应用程序的共享前端框架 | | [scitex-writer](https://github.com/ywatanabe1989/scitex-writer) | `stx.writer` | Python ⭐ · 命令行 ⭐⭐⭐ · MCP ⭐⭐⭐ · 技能 ⭐⭐ · 钩子 — · HTTP — | 端到端的LaTeX手稿工具链（45个MCP工具） | ## SciTeX的一部分 `scitex` 是 [SciTeX](https://scitex.ai) 的一部分 — 它是汇总整个生态系统的伞形发行版，位于一个 `import scitex` 命名空间下。每个对等模块（`scitex.io`、`scitex.plt`、`scitex.stats`，...）是一个独立的软件包，可以单独安装（`pip install scitex[io]`），但组合成设计的协同作用：保存一个图形 → 自动导出CSV + YAML配方 → 通过Clew进行哈希跟踪 → 在`scitex-writer`中引用。 > 研究的四项自由 > > 0. 在任何地方运行研究的自由 — 您的机器，您的条件。 > 1. 研究每一步的工作原理的自由 — 从原始数据到最终的手稿。 > 2. 重新分发工作流的自由，而不仅仅是论文。 > 3. 修改任何模块并与社区共享改进的自由。 > > AGPL-3.0 — 因为研究基础设施应享有与运行它的软件相同的自由。 <p align="center"> <a href="https://star-history.com/#ywatanabe1989/scitex-python&Date"> <img alt="Star History" src="https://api.star-history.com/svg?repos=ywatanabe1989/scitex-python&type=Date" /> </a> </p> <p align="center"> <a href="https://scitex.ai"><img src="docs/assets/images/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a> </p> <!-- EOF -->