Skip to main content
Glama
co-scientist-plugin

co-scientist-plugin

co-scientist 插件

在你的编码代理中运行一个多智能体科学研究引擎。

一个 Agent Plugins 1.0 包,让 Claude Code、Codex CLI、Cursor、VS Code、Copilot 和 Kiro 驱动 AI co-scientist 引擎:生成 假设、评审假设、在 Elo 锦标赛中排序、进化胜出者, 并读回综合结果。

tests Python 3.11 to 3.13 License: Apache 2.0 Agent Plugins 1.0

安装 · 代理能获得什么 · 设计规则 · 与 ScientistOS 协同 · 贡献


理念

AI co-scientist 引擎是 Gottweis 等人,Nature,2026 的一个开源重新实现。它接收一个研究目标,并运行六个专家代理:生成、 反思、排序、进化、邻近性和元评审,由 一个 Supervisor 在持久化的 SQLite 任务队列上调度。

该引擎有一个 CLI。这个包为它提供了一个面向代理的界面,因此 驱动它的可以是 Claude Code 或 Codex,而不是你手动输入命令:

you    → "review hypothesis 3 in that Crohn's session and tell me what breaks"
agent  → reads the hypothesis, searches the literature, applies the rubric,
         records the review into the engine's database, reports the verdict

它写下的评审现在成为引擎自身 Reflection 代理写入的同一张表中的一行。它计入锦标赛。元评审会看到它。

Related MCP server: consensus-mcp

代理能获得什么

一个 MCP 服务器,提供十五个工具:

分组

工具

生命周期

session_start · session_resume · session_pause · session_abort · session_list · session_status

读取

hypotheses_list · hypothesis_get · overview_get

写入

hypothesis_record · review_record · match_record · feedback_add

诊断

estimate_cost · doctor

七项技能,承载工具无法承载的判断:

技能

作用

running-research-sessions

将模糊的目标打磨为清晰的目标,对运行规模设门槛,启动并监控运行

reading-research-overviews

诚实地阅读排序后的输出,检查五种已知的失败模式

reviewing-hypotheses

依据带锚点的评分标准进行评审,做出裁决决定,然后记录结果

ranking-hypotheses

进行三轮到五轮的辩论,依据有序标准做出决定,记录 Elo 对局

evolving-hypotheses

组合、简化、可行性、跳出框架,每种都有各自的参考文件和失败模式

benchmarking-models

跨模型 Elo 基准测试,以及如何不夸大其词地解读结果

grounding-claims

逐条核查引用是否真的支持所声称的内容,并给出裁决

设计规则

引擎保留所有状态:Elo、任务队列、去重、嵌入、 token 预算、终止条件。这个包不重新实现其中任何一部分。

代理产生的所有内容都通过引擎自身代理写入的同一套仓库回流。 match_record 复用引擎的 Elo 模块及其 elo_journal 幂等性。review_record 写入与 Reflection 完全相同的 Review 模型, 并将 draft 提升为 reviewed,与 Reflection 的做法完全一致。 hypothesis_record 根据是否存在父节点来推导 created_by。

这些技能用直白的话说明后果:未被记录的输出等于不存在。 一个代理在对话中描述了一次评审却没有调用 review_record,那么它就没有产生任何系统可用的东西。

这正是阻止常见失败模式的关键:"把提示词移植成技能然后就算完成"。 提示词不是质量来源。锦标赛才是, 而锦标赛需要一个地方来计分。

与 ScientistOS 协同

这个插件生成并排序候选假设。它不决定 你可以从这些假设中主张什么,而这一区别至关重要:一个假设 可能在锦标赛中排名第一,却仍然建立在一个与文献 相矛盾的机制之上。reading-research-overviews 技能列出了这种失败模式以及 其他几种需要人工核查的模式。

ScientistOS 将这种核查 变成结构性的而非建议性的。它维护一个类型化的证据图,并 拒绝以超出其谱系支持的强度记录任何主张。

this plugin   →  ranked hypotheses, reviews with claim / url / excerpt per source
                              ↓
ScientistOS   →  hypothesis and source nodes, evidence at its honest level,
                 an integrity gate before anything gets written up

两者并排安装,因为两者都是技能和 MCP 包,一个 同时加载两者的代理可以获得完整的路径。这里没有任何东西依赖 ScientistOS, ScientistOS 也不依赖这个包。

安装

无需 API 密钥,也无需为计费做任何决定。 如果你 已经登录了 Claude Code 或 Codex CLI,那就满足了全部 要求:研究引擎通过你编码代理所使用的同一个订阅 来运行其代理。

python3.12 -m venv .venv
source .venv/bin/activate

pip install "co-scientist @ git+https://github.com/Kaimen-Inc/Co-Scientist.git"
pip install "co-scientist-plugin @ git+https://github.com/Ahmad-Jaradat-Space/co-scientist-plugin.git"

co-scientist init

首次连接时,服务器会寻找一个可用的后端。如果找不到, 它会采用任何已安装并已登录的代理 CLI,将该选择写入 ~/.co-scientist/config.toml,然后继续运行。已有的 provider = 行永远不会被改动,因此你自己配置好的设置不会被干扰。设置 COSCI_AUTO_BACKEND=0 可以完全关闭自动选择。

如果 doctor 仍然报告没有后端,请登录 CLI(claude 或 codex login),而不要去找什么密钥。它还会报告一个本地哈希 嵌入器,这是预期的无密钥状态:去重能捕捉重复的措辞, 但无法捕捉两句话用不同方式表达同一个假设的情况。

一切数据都留在你的机器上:SQLite 位于 ./data 下,无需账户,无需服务 注册,除了你的 CLI 本来就会产生的模型调用之外没有任何网络流量。

config/subscription.toml 是同样的选择, 只不过由你手动写出,将模型 ID 固定下来,而不是让 你的 CLI 去解析别名。通过 export COSCI_CONFIG=/path/to/config/subscription.toml 让引擎指向它。

计量式 API 同样可用:在首次运行前于 ~/.co-scientist/config.toml 中设置 provider 和密钥,自动选择就不会 插手。estimate_cost 随后会根据预算估算运行成本,而这些技能 会就支出征询许可,而不是直接消耗时间。参见 引擎的后端指南。

Codex CLI

codex plugins install ./co-scientist-plugin

Claude Code

ln -s "$PWD/skills/"* ~/.claude/skills/
claude mcp add co-scientist -- co-scientist-mcp

其他任何客户端

任何能读取 Agent Plugins 1.0 的客户端都会按原样加载该目录。任何 能分别读取 SKILL.md 和 MCP 配置的客户端,也可以单独使用 skills/ 和 mcp.json。

配置

服务器读取引擎的配置。如果需要,可以在你的 mcp.json 的 env 块中设置以下变量:

变量

作用

COSCI_CONFIG

要叠加加载的额外 TOML 配置的路径

COSCI_ALLOW_START

0 时拒绝 session_start 和 session_resume

COSCI_START_TIMEOUT

等待已启动的运行完成注册的秒数,默认 120

COSCI_AUTO_BACKEND

0 时关闭在未配置任何内容的情况下自动选择已登录 CLI 的行为

只读安装

一次会话会发起数百次模型调用,并且在对话结束后 继续运行。在共享机器上,或任何不应让代理 自行启动会话的环境中:

co-scientist-mcp --read-only

读取功能保持可用;session_start 和 session_resume 会拒绝并给出 解释。

Virtualenv 路径

mcp.json 调用 co-scientist-mcp,这假设控制台脚本位于 PATH 上。如果你的代理没有激活 virtualenv,请使用绝对路径:

{
  "command": "/path/to/.venv/bin/co-scientist-mcp",
  "args": []
}

开发

pip install -e ".[dev]"
ruff check coscientist_plugin tests
pytest -q
co-scientist-plugin-validate

每个测试都在离线环境下针对一次性数据库运行。无需密钥,无需网络,无需 模型调用。

三项检查守护这个包:

  • co-scientist-plugin-validate 检查规范符合性:十个允许的 清单字段、传输类型、技能 frontmatter、名称与目录 一致性、正文长度,以及每个相对链接都能解析且只保持 一层深度。

  • tests/test_plugin.py 检查验证器无法检查的内容:没有技能 指示代理调用不存在的 MCP 工具或引擎命令, 并且记录纪律确实写在了负责写入的技能中。

  • tests/test_server.py 覆盖设计所依赖的不变量:零和 Elo、每轮幂等、跨会话拒绝、没有摘录的证据 被拒绝,以及状态转换永远不会把已排序的假设 拖回更早的状态。

与引擎的关系

本仓库仅包含插件层。它所驱动的引擎位于 Kaimen-Inc/Co-Scientist, 是在同一许可证下的独立项目。参见 NOTICE。

两个项目均与 Google 或论文作者无关联。 两者产生的假设都是科学家的起点,而非结论。

许可证

Apache-2.0。参见 LICENSE 和 NOTICE。

Available Tools

15 tools
doctorA

Check the install: which LLM backend is configured, whether its credentials resolve, whether embeddings are real or the hash fallback, and where the database lives. Run this first when anything fails.

Inputs: no named parameters.

estimate_costA

Pre-flight size of a session under the current config: calls and tokens per agent, and how long it may run. On a metered API backend it also prices it. Run this before session_start and show the user.

Inputs: no named parameters.

feedback_addA

Inject researcher feedback into a session. A running session picks it up on its next planning step; a paused one picks it up on resume. kind='pin' or 'rejection' with a target also moves that hypothesis's state.

Inputs: text (required), session_id (required), kind, target.

hypotheses_listA

List a session's hypotheses ranked by Elo, with title, summary, state, matches played and dedup cluster. Bodies are omitted; use hypothesis_get.

Inputs: session_id (required), limit, state, offset.

hypothesis_getA

One hypothesis in full: statement, detailed text, citations, Elo history, every review recorded against it, and its tournament matches. Read this before reviewing or ranking it.

Inputs: hypothesis_id (required), include_matches.

hypothesis_recordA

Add a hypothesis to a session, in the same table Generation and Evolution write to. It enters as a draft, gets reviewed, and then competes in the tournament like any other. Set parent_ids when it derives from existing hypotheses, which is what makes it an Evolution result rather than a fresh idea. Recording is what makes a hypothesis real: an idea only described in chat is never reviewed, ranked, or seen by the meta-review.

Inputs: title (required), summary (required), strategy (required), full_text (required), +3 more.

match_recordA

Record the outcome of a head-to-head comparison between two hypotheses and apply the Elo update. Compare them on the paper's criteria (correctness, novelty, testability, and how well each survives its reviews) and give the rationale. Idempotent per (pair, round_id): recording the same pair twice under the same round moves no Elo.

Inputs: hyp_a (required), hyp_b (required), winner (required), rationale (required), +2 more.

overview_getA

The final research overview for a session: the meta-review synthesis of the ranked hypotheses. Only exists once the session has finalized.

Inputs: session_id (required).

review_recordA

Record a review against a hypothesis, in the same table and format the Reflection agent writes. Every factual claim in evidence needs a url and an excerpt you actually read. A 'full' review on a draft hypothesis also promotes it to reviewed. Do not report a review to the user without recording it first, or the tournament and meta-review will never see it.

Inputs: body (required), kind (required), hypothesis_id (required), scores, +4 more.

session_abortA

Abort a session for good. The main loop exits at its next check.

Inputs: session_id (required).

session_listA

List sessions newest first, with status, hypothesis count, top Elo and budget spent. Use this to find a session id the user refers to by topic.

Inputs: limit.

session_pauseA

Pause a running session. Workers drain and the loop sleeps until resumed.

Inputs: session_id (required).

session_resumeA

Resume a paused or interrupted session. The engine reclaims expired task leases and continues where it stopped. Returns immediately; poll session_status.

Inputs: session_id (required).

session_startA

Start a new research session from a natural-language goal. The engine runs the full Generation, Reflection, Elo tournament, Evolution and Meta-review loop in a detached process; this returns as soon as the session id exists. Poll session_status for progress. It runs for minutes to hours, so agree the scale with the user first: call estimate_cost.

Inputs: goal (required), n_initial, budget_usd, concurrency, +2 more.

session_statusA

Progress for one session: status, task counts by state, hypothesis counts by state, matches played, Elo spread, budget spent, and whether the final overview exists yet. This is the polling tool.

Inputs: session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 15 tools

    Disambiguation4/5

    Tools are mostly distinct by resource and action (sessions vs hypotheses vs reviews vs matches). Minor overlap between session_pause/session_abort and hypothesis_record/review_record, but descriptions are detailed enough to avoid misselection.

    Naming Consistency4/5

    Most tools follow a noun_verb pattern (session_list, hypotheses_list, hypothesis_get, review_record), but session_resume, session_start, session_pause, session_abort are verb-first. doctor breaks the pattern entirely. Consistent within each resource group, mixed across groups.

    Tool Count5/5

    15 tools for a complex scientific research orchestration server. Each tool maps to a distinct lifecycle step: session management (7), hypothesis operations (4), review/match/feedback (3), overview (1), cost estimation (1), diagnostics (1). Well-scoped for the complexity.

    Completeness4/5

    Covers the full session lifecycle (start, poll, pause, resume, abort), hypothesis CRUD (list, get, record), review and tournament operations. Missing explicit update/delete for hypotheses or sessions, but the domain (adding to a persistent tournament) doesn't require them. Overview_get exists only after finalization; no explicit wait/finalize tool but polling covers it.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers