MonadScholar

MonadScholar 是面向 WorkBuddy 的外部 CLI 连接器与单一科研 Skill。它保留原 Scholar 的文献、设计、统计、图表、Meta、临床研究、写作、润色、投稿和科研辅助能力，同时把确定性计算收口到本地 monadscholar CLI。

用户安装连接器后只需用自然语言提出科研任务，不需要理解命令行。WorkBuddy 负责理解意图、读取用户上传的 PDF/Word/PPT/TXT/Markdown，并调用 Skill；CLI 负责真实题录、样本量、统计、Table One、Meta、数据图和期刊公开元数据。

形态

用户自然语言
  -> WorkBuddy
     -> monadscholar-research Skill：任务规划、证据边界、结果解释
     -> WorkBuddy 原生文件读取：PDF / Word / PPT / TXT / Markdown
     -> 官方 ima：大量论文或长期全文资料库
     -> monadscholar CLI：文献元数据 / 引文 / 统计 / Meta / 数据图

这是本地 CLI 连接器，不需要为每位用户提供 MonadScholar 云端服务。PubMed、Crossref 和 OpenAlex 请求由用户设备直接访问相应公开接口；数据表和生成产物默认留在本机。

能力

对外提供一个 monadscholar-research Skill，内部覆盖 40 项能力：

模块	能力
文献、阅读与选题	PubMed、检索式、题录去重与导出、单篇精读、证据矩阵、综述、选题、创新点、立项与开题框架
设计、统计与图表	研究设计、随机与对照、统计方案、样本量、参数/非参数检验、回归、生存分析、Table One、数据图与图表复现
临床、循证与网络	PICO/PECO、逐篇数据提取、偏倚风险、Meta、森林图、漏斗图、PRISMA、临床预测、诊断试验、真实世界研究、网络图
写作、投稿与辅助	IMRaD、摘要、润色、翻译、选刊、投稿清单、cover letter、审稿回复、邮件、术语表、周报、纪要与 PPT 大纲

统计命令支持：

• describe
• independent_t、paired_t、one_sample_t
• mann_whitney、wilcoxon
• chi_square、fisher_exact
• one_way_anova、kruskal
• pearson、spearman
• linear_regression、logistic_regression
• kaplan_meier、cox_regression
• table_one
• sample_size

绘图支持 scatter、line、bar、box、violin、histogram、heatmap、Kaplan–Meier 和 network；数据图导出 300 dpi PNG 与可编辑 SVG。

用户体验

连接器发布到 WorkBuddy 后，用户的典型流程是：

1. 在连接器市场找到“MonadScholar 科研助手”并安装。
2. WorkBuddy 初始化 Python CLI，并加载 monadscholar-research Skill。
3. 用户直接上传材料并描述目标。
4. WorkBuddy 读取证据文档；如果是 CSV/TSV/XLSX/XLSM，则把原始本地路径交给 CLI。
5. MonadScholar 返回结构化 JSON 和产物路径，WorkBuddy 将其解释成研究结论、表格或可下载文件。

例如：

读取这个 Excel，先说明变量、编码和缺失情况，再比较两组主要结局，
生成带 SMD 的 Table One，并画一张叠加原始散点和样本量的箱线图。

精读我上传的三篇 PDF，整理研究设计、样本、主要结果、局限和与我课题的关系。

单次上传的 PDF 等文档由 WorkBuddy 原生解析；大量论文或希望长期复用的全文资料使用官方 ima。

CLI

本地开发安装：

python3 -m pip install -e .
monadscholar doctor

命令：

monadscholar doctor
monadscholar capabilities
monadscholar literature search
monadscholar references run
monadscholar stats run
monadscholar plot run
monadscholar meta run
monadscholar journal match

短参数可以直接传入；复杂参数使用 JSON request：

monadscholar stats run --request "/path/to/request.json"

成功结果：

{
  "ok": true,
  "command": "stats.run",
  "data": {},
  "artifacts": []
}

错误结果：

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Column 'outcome' was not found.",
    "retryable": false
  }
}

退出码：

• 0：成功
• 2：参数、输入文件或数据问题
• 3：本地运行环境问题
• 4：公开元数据网络请求失败
• 5：分析或绘图失败

默认输出目录：

~/.workbuddy/workspace/monadscholar/

连接器包

连接器源码位于 workbuddy-connector/：

workbuddy-connector/
├── connector-meta.json
├── cli.json
├── icon.svg
└── skills/
    └── monadscholar-research/
        ├── SKILL.md
        └── references/

构建市场上传 ZIP：

python3 scripts/build_workbuddy_connector.py

输出：

dist/monadscholar-workbuddy-0.1.0.zip

cli.json 当前从 PyPI 安装固定版本 monadscholar==0.1.0，因此正式提交连接器前必须先发布对应 Python 包。

测试

.venv/bin/python -m unittest discover -s tests -p 'test_*.py'
tests/smoke_cli.sh
MONADSCHOLAR_ACCEPTANCE_OUTPUT_DIR=/tmp/monadscholar-acceptance \
  .venv/bin/python tests/run_acceptance.py
python3 scripts/build_workbuddy_connector.py

tests/run_acceptance.py 会真实访问 PubMed，并从该次检索返回的元数据与摘要生成阅读卡；其余单元测试和 CLI 冒烟可离线运行。

数据与证据边界

• 所有样本量、描述值、P 值、效应量、置信区间、回归结果、Meta 合并值和数据图必须来自 CLI。
• CSV、TSV、XLSX、XLSM 必须让 CLI 读取原文件，不能先由模型转录数值。
• PDF、Word、PPT、TXT、Markdown 的正文证据来自 WorkBuddy 实际解析内容；读不到的内容不猜。
• DOI、PMID、作者、年份和期刊名来自 CLI 返回或用户提供的可核对来源。
• 期刊匹配使用公开元数据初筛；最新 scope、费用、索引和投稿要求仍需核对期刊官网。
• 医学内容用于科研支持，不替代个体化诊疗或专业统计复核。

公开期刊数据

data/journals.json 基于 OpenAlex Sources API 和本地主题标签构建。刷新时会同步更新 Python 包内副本：

.venv/bin/python data/build_journals.py

可选环境变量：

NCBI_EMAIL
NCBI_API_KEY
OPENALEX_EMAIL
OPENALEX_API_KEY
CROSSREF_EMAIL

JCR 影响因子和中科院分区不打包、不推测。

发布前待确认

WorkBuddy 开放文档中仍有几项协议细节未给出完整字段定义，已整理在 docs/OFFICIAL_QUESTIONS.md。这些问题不影响本地 CLI 和 Skill 验收，但在正式提交市场前应由官方确认。