mcpField
O
oma-scholar

oma-scholar

github.com/gracefullight生产力4947 次安装今天更新
代码仓库

关于 oma-scholar

oma-scholar 是面向学术论文与 Knows sidecar 的研究工作流技能，可生成、验证、分析和比较 sidecar，也能搜索或获取论文信息。它使用结构化声明、证据和关系来支持精简阅读，并在来源缺少信息时避免臆造。

主要功能

  1. 01生成和验证 .knows.yaml sidecar
  2. 02搜索论文并解析论文身份
  3. 03获取完整或指定部分的 sidecar
  4. 04分析声明、证据和论文关系
  5. 05结构化比较论文或生成评审 sidecar

适用场景

  1. 01从论文草稿生成 sidecar
  2. 02检查 sidecar 结构并查看警告
  3. 03按声明部分获取论文信息
  4. 04比较两篇论文的方法与证据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gracefullight/stock-checker --skill oma-scholar

安装后在 Claude Code 中输入/oma-scholar确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

config/
scholar-config.yaml
resources/
api-endpoints.md
checklist.md
execution-protocol.md
fallback-providers.md
setup-openalex.md
sidecar-spec.md
upstream-spec-cache.md

详细介绍

Scholar - 研究论文侧车助手

调度

目标

使用 Knows .knows.yaml 规范搜索、获取、生成、验证、分析、评审和比较学术论文侧车，以支持节省 token 的研究工作流。

意图特征
  • 用户请求学术文献搜索、侧车生成、侧车验证、论文主张／证据摘要、论文结构比较，或以侧车形式进行同行评审。
  • 用户提及 Knows、.knows.yaml、knows.academy、OpenAlex、主张、证据、关系或论文侧车。
适用场景
  • 通过 Knows 侧车以节省 token 的方式阅读研究论文（仅主张约需 700 个 token，完整 PDF 约需 10K 个 token）
  • 根据自己的论文草稿、LaTeX 或研究笔记生成 .knows.yaml 侧车
  • 分享前验证侧车结构（基于规则）
  • 以侧车形式生成同行评审
  • 查询或总结现有侧车
  • 对两篇论文进行结构化比较（主张、方法、证据）
  • 从 knows.academy 搜索／获取侧车（仅限 2026 年论文；当前数量可通过 /api/proxy/jobs/stats 查询）
不适用场景
  • 通用网页搜索或非学术内容 -> 使用 oma-search
  • 翻译论文 -> 使用 oma-translation
  • 仅解析 PDF（无侧车） -> 使用 oma-pdf
  • 将侧车提交回 knows.academy -> 超出范围（托管 LLM 仅在本地使用或生成内容）
  • 包含编辑系统的完整同行评审工作流 -> 超出范围
预期输入
  • 论文、摘要、草稿、LaTeX、研究笔记、侧车文件、DOI、OpenAlex ID、Knows 记录 ID 或搜索查询
  • 所需模式：生成、验证、评审、分析、比较或远程获取
  • 可选的严格程度、章节筛选条件或 CI 行为
预期输出
  • .knows.yaml 侧车、评审侧车、lint 报告、搜索／获取结果、自然语言分析或结构化比较
  • 符合 v0.9.0 / paper@1 配置文件的侧车
  • 分享生成的侧车前提供验证状态和警告
依赖项
  • oma scholar CLI 子命令
  • knows.academy 公共 API；OpenAlex 和 Semantic Scholar 回退方案
  • resources/sidecar-spec.md、API 端点、OpenAlex 设置、上游缓存、检查清单和执行协议
控制流特性
  • 根据模式、来源可用性、Knows/OpenAlex 覆盖情况、严格或宽松验证以及获取的章节进行分支
  • 读取／写入 YAML 侧车，并可能调用公共 API
  • 缺少来源证据时避免编造内容

结构化流程

入口
  1. 确定模式和来源材料／查询。
  2. 根据需要通过 Knows 或 OpenAlex 确定论文身份。
  3. 加载侧车规范和特定模式的协议。
场景
  1. 准备：选择模式并收集来源或远程标识符。
  2. 获取：获取论文元数据、侧车章节或本地来源文本。
  3. 推理：提取主张、证据、关系、来源信息或比较结构。
  4. 执行：生成、lint、评审、分析、比较或获取侧车数据。
  5. 验证：检查受支持的本地契约、ID、关系和来源信息；报告 lint 的局限性。完整符合规范需要使用精确的 schema 验证器。
  6. 完成：返回侧车、报告、摘要或比较结果，并说明注意事项。
转换
  • 如果 knows.academy 中没有该论文，则回退到 OpenAlex 的元数据／摘要。
  • 如果要生成侧车，则在分享前运行 lint。
  • 如果使用的第三方侧车存在悬空引用，则在适当情况下使用宽松模式。
  • 如果缺少来源证据，则省略字段而不是猜测。
失败与恢复
  • 如果远程 API 超时，则重试或使用 OpenAlex 回退方案。
  • 如果 YAML 解析失败，则修正缩进和标量类型。
  • 如果关系密度或孤立陈述发出警告，则检查覆盖范围和适合类型的链接。保留锚定于来源的问题／定义；切勿为了满足配额而添加缺乏依据的关系。
退出
  • 成功：请求的 sidecar 操作完成，并附有验证状态。
  • 部分成功：明确说明缺少的元数据、回退来源或验证警告。

逻辑操作

操作
操作SSL 原语证据
选择模式SELECTGenerate/Validate/Review/Analyze/Compare/Remote
读取论文或 sidecarREAD源文件或 YAML
请求远程数据REQUESTKnows/OpenAlex API
推断声明/证据/关系INFERSidecar 生成/分析
写入 sidecarWRITE.knows.yaml 输出
验证 sidecarVALIDATEoma scholar lint
报告结果NOTIFY摘要或 lint 报告
工具和手段
  • oma scholar search|resolve|get|lint
  • Knows 公共 API、OpenAlex 回退方案、sidecar 规范、检查清单
规范命令路径
oma scholar search "<query>"
oma scholar resolve "<title-or-doi>"
oma scholar get "<record-id-or-doi>"
oma scholar lint "<paper.knows.yaml>"
资源范围
范围资源目标
LOCAL_FS论文草稿、sidecar YAML、评审 sidecar
NETWORKknows.academy 和 OpenAlex API
PROCESSoma scholar CLI 和 lint
USER_DATA用户提供的论文内容和研究笔记
前置条件
  • 可识别模式和来源。
  • 可获取用于生成或验证的规范规则。
影响和副作用
  • 可能创建本地 sidecar 或评审 sidecar 文件。
  • 可能查询公开的学术 API。
  • 不会将 sidecar 提交回 knows.academy。
护栏
  1. 本地生成目标为兼容 v0.9.0 生产环境 / paper@1（评审 sidecar 使用 review@1）。这比完全符合规范的标准范围更窄；请参阅 resources/sidecar-spec.md。
  2. 由宿主 LLM 生成 sidecar：绝不调用 anthropic SDK 或外部 LLM CLI；此技能在 Agent 内运行。
  3. 防止伪造：如果来源中未显示 DOI/venue/year，请完全省略该字段；绝不写 doi: TODO 或猜测。
  4. 顶层元数据：title、authors、venue、year 位于顶层（不使用 metadata 包装层）。
  5. 字段名称必须准确：statement_type、evidence_type、predicate、artifact_type（不是 type/claim）。
  6. 来源信息仅有 SINGLE 个参与者：provenance.actor 是一个对象，而不是 provenance.actors 数组。
  7. 置信度是一个对象：{claim_strength: ..., extraction_fidelity: ...}，两者的值均来自 high|medium|low。
  8. 覆盖度是一个对象：coverage.statements（4 值枚举）+ coverage.evidence（3 值枚举）。
  9. 封闭枚举：actor 为 tool|person|org（绝不使用 ai/llm/model）；artifact role 为 subject|supporting|cited；predicate 使用现在时。
  10. 数字不加引号：value: 22，绝不写 value: '22'。
  11. 关系覆盖度：检查本地比例/孤立项警告；仅添加有来源依据且类型适当的关系。带有证据的声明使用 supported_by；定义和开放问题可以仅锚定来源。1.5 的比例是诊断指标，不是填充图谱的配额。
  12. ID 格式：使用描述性 kebab-case，并带前缀：stmt:privacy-budget-tradeoff、ev:cifar10-accuracy-table、art:paper。
  13. 分享前验证：生成和评审后运行 oma scholar lint；评审 sidecar 中的跨记录引用（record_id#local_id）可被识别，不会被标记为悬空引用。
  14. 远程 API 无需身份验证：https://knows.academy/api/proxy/* 是公开的；不要编造身份验证标头。
  15. 部分获取参数为 section（单数）：固定枚举 statements|evidence|relations|artifacts|citation。
  16. 备用 API 密钥为可选项：OPENALEX_API_KEY（元数据补充）和 S2_API_KEY（Semantic Scholar 专用速率限制）都能提高吞吐量，但没有它们时，级联流程也能正常降级。
  17. Sidecar 内容保持英文：schema 字段、ID、声明文本遵循上游惯例；面向用户的回复遵循 oma-config.yaml 中的 language 设置。
  18. 契约范围：本地生成规则和 lint 用于跟踪生产兼容性，而非完整的规范 v0.9 schema。保留导入内容的规范形状，并报告与本地 lint 的不兼容之处。未经针对确切 schema 的验证，不要声称完全符合 schema，也不要添加 $schema；请参阅 resources/upstream-spec-cache.md。
模式
模式触发方式输出
生成“从这篇论文 / 摘要 / 草稿创建 sidecar”、“生成 .knows.yaml”{paper}.knows.yaml（由宿主 LLM 输出，然后通过 oma scholar lint 验证）
验证“对这个 sidecar 执行 lint”、“验证 .knows.yaml”包含文件:行号问题的通过/失败报告
评审“以 sidecar 形式对这篇论文进行同行评审”{paper}.review.knows.yaml
分析“总结这个 sidecar”、“它提出了哪些声明？”自然语言回答
比较“从结构上比较论文 A 和论文 B”差异表（声明/方法/证据）
远程“查找关于 X 的论文”、“获取 sidecar :id”、“仅获取 :id 的声明”搜索结果 / sidecar 内容
提供方回退（knows.academy → OpenAlex → Semantic Scholar）

knows.academy 目前仅收录 2026 年的论文（大多来自 arXiv）。对于更早的论文或非 2026 年论文（Transformer 2017、BERT 2018、经典论文、期刊论文），此技能会自动回退到 OpenAlex 获取元数据和摘要；若 OpenAlex 也没有，则会回退到 Semantic Scholar（AI TL;DR、引用数和高影响力引用数）。参见 resources/fallback-providers.md。

使用 oma scholar CLI 子命令：

# Hybrid search: knows first, OpenAlex fallback
oma scholar search "vision language action"

# Cross-source resolve: figures out which source has the right paper
oma scholar resolve "Attention Is All You Need"

# Get by id (knows record_id, OpenAlex W-id, DOI, arXiv:<id>, CorpusId:<n>)
oma scholar get "10.48550/arXiv.1706.03762"

当 OpenAlex 返回答案时（knows.academy 中没有该论文），请使用返回的摘要作为 Mode 1 Generate 的输入，生成本地 sidecar。

快速参考
搜索（knows + 自动回退到 OpenAlex）
oma scholar search "diffusion super resolution"
oma scholar search --year-min 2024 "vision language action"
查找一篇特定论文
oma scholar resolve "Attention Is All You Need"
# returns top hit from each source + recommendation
获取 sidecar 或作品
# knows.academy full sidecar
oma scholar get "knows:generated/reconvla/1.0.0"

# Partial fetch (claims only, ~700 tokens, 93% reduction vs PDF)
oma scholar get --section statements "knows:generated/reconvla/1.0.0"

# By DOI or OpenAlex W-id (works regardless of knows.academy availability)
oma scholar get "10.48550/arXiv.1706.03762"

# Semantic Scholar: AI TL;DR + citation/influential-citation counts
oma scholar get "arXiv:1706.03762"

当无法访问 knows.academy 时，get knows:... 会自动从 record_id 中提取 slug 并回退到 OpenAlex。结果会标记为 fallback: "openalex"，并包含元数据和摘要，可用于在本地运行 Mode 1 Generate。

验证
# Strict mode for own Generate output (default)
oma scholar lint paper.knows.yaml

# Lenient mode for third-party / fetched sidecars
oma scholar lint --lenient remote.knows.yaml

# Treat warnings as failures (CI mode)
oma scholar lint --fail-on-warning paper.knows.yaml

knows.academy 提供的 sidecar 中，约有 47% 至少包含一个悬空交叉引用（subject_ref/object_ref 中的拼写错误，基于 15 个生产样本测得）。使用 --lenient 消费第三方记录，这样这些问题会显示为警告，而不是阻断性错误。

原始 API（CLI 不可用时）
curl -s "https://knows.academy/api/proxy/search?q=..."
curl -s "https://knows.academy/api/proxy/sidecars/<encoded-id>"
curl -s "https://knows.academy/api/proxy/partial?record_id=<id>&section=statements"
curl -s "https://knows.academy/api/proxy/jobs/stats"   # platform health
配置

项目特定设置：config/scholar-config.yaml。其中有一个由用户调整的键，存放在其他位置——先从 .agents/oma-config.yaml 读取 scholar.base_url，再回退到技能配置中的 api.base_url。其中的其他所有内容（端点路径、超时、id 前缀、lint 规则）均属于协议结构，而非偏好设置。

故障排除
问题解决方案
[ERROR] *.value: numeric value '22' is quoted移除引号：value: '22' -> value: 22
[ERROR] provenance.actor.type: 'ai' is not allowed改为 tool、person 或 org
[ERROR] *.type: use \statement_type` instead of `type``将 type 重命名为 statement_type（或 evidence_type/predicate/artifact_type）
[ERROR] provenance.actors: v0.9 spec uses singular \actor``将 actors: [{...}] 数组替换为 actor: {...} 对象
[ERROR] *.object_ref: reference 'X' does not match any defined id修正 subject_ref/object_ref，使其指向实际存在的 id；或者在消费第三方数据时使用 --lenient（跨记录的 record_id#local_id 引用可被识别，且绝不会被标记）
[WARN] relations: avg relations/statement is N.NN (target ≥ 1.5)检查覆盖范围；仅添加有依据且类型合适的链接，切勿填充图谱
[WARN] statements: only N statements; most papers warrant ≥ 8仅根据摘要生成时属于预期情况；使用全文进行 Generate 应达到 15 条以上
[WARN] *.predicate: past-tense '...' is suspicious改为现在时（evaluated_on -> evaluates_on）
远程 API 返回空结果尝试更宽泛的查询；检查 /api/proxy/jobs/stats；CLI 会自动回退到 OpenAlex
knows.academy search failed: fetch failed（stderr）平台超时；会自动回退到 OpenAlex；稍后重试获取 sidecar
OpenAlex 403/429设置 OPENALEX_API_KEY（参见 resources/setup-openalex.md）
semanticscholar error: HTTP 429（stderr）匿名池受到限流；CLI 重试一次后会跳过该来源。设置 S2_API_KEY（在 semanticscholar.org/product/api 免费申请）可获得专属限额
YAML 无法解析检查缩进；数字和布尔值不得加引号；包含 : 的字符串需要加引号

参考资料

  • 执行步骤（按照所选任务执行）：resources/execution-protocol.md
  • Sidecar 规范规则：resources/sidecar-spec.md
  • API 端点：resources/api-endpoints.md
  • OpenAlex 设置：resources/setup-openalex.md
  • 上游规范快照：resources/upstream-spec-cache.md
  • 生成后检查清单：resources/checklist.md
  • CLI 子命令：oma scholar search|resolve|get|lint（实现在 cli/commands/scholar/ 下）
  • 上下文加载：../_shared/core/context-loading.md
  • 质量原则：../_shared/core/quality-principles.md
  • 国际化规则：../../rules/i18n-guide.md

评论

支持 Markdown