Prelaunch preview. Explore AROS products and skills. Checkout is in sandbox; no real payment.
← CohortDAG 文档

通过 AI 智能体或命令行使用 CohortDAG

操作指南 · CohortDAG 0.2.9

CohortDAG 附带命令行工具 cohortdag 和 MCP 服务器 cohortdag-mcp,它们与窗口界面使用同一个编译器和 Spark 后端。Claude Code、Codex 或 Google Antigravity 等 AI 智能体可以用它们来编写、检查和运行流程;向已打开的窗口添加步骤,需要你在窗口中接受。CohortDAG 本身不含任何 AI 模型;智能体在应用之外运行,通过这些工具来驱动它。下面的每条命令都是在全新的 Ubuntu 24.04 机器上、按“快速开始”安装 0.2.4 版安装包之后实际运行的,显示的输出即其实际输出。

命令

检查命令

安装包会把 cohortdag 和 cohortdag-mcp 加入 PATH。打印版本号即可检查。

cohortdag --version
0.2.9

检查运行环境

检查 Python、Java、PySpark 和后端。doctor 会启动一个真实的 Spark 驱动程序,因此需要稍等片刻。

cohortdag doctor
✓ Node.js: v24.22.2 (running this CLI)
  ✓ Python: Python 3.12.3 (/home/researcher/.config/cohortdag/python-env/bin/python -> /home/researcher/.config/cohortdag/python-env/bin/python)
  ✓ Java (JVM): openjdk version "17.0.21.0.3" 2026-10-24 (PATH)
  ✓ analysis packages (pyspark + production chain): pyspark 3.5.9; all required imports loaded
  ✓ backend (server.py): /opt/CohortDAG/resources/src/python/server.py
  ✓ Spark driver boot: a real SparkSession started and stopped
  ! data root: $COHORTDAG_DATA_ROOT not set
      fix: Set $COHORTDAG_DATA_ROOT to the directory holding your source parquet tables (only needed to run pipelines that read them).

Environment OK — the CohortDAG backend can run.

查看 CohortDAG 可以连接哪些智能体

CohortDAG 可以把自己注册到 Claude Code、Codex(同时适用于 ChatGPT 桌面应用)和 Google Antigravity。这条命令会列出每个智能体中各个 CohortDAG 条目是已存在还是不存在。下面的输出里所有条目都不存在,因为这台机器上还没有设置任何智能体;连接一个之后可以再运行一次。运行 cohortdag agent install --target all,可一次为这三个智能体安装技能并注册服务器;之后分别重启各个智能体。窗口中的 Help > Connect AI Agents… 效果相同,但一次只处理一个智能体。

cohortdag agent status
Claude Code: not detected (/home/researcher/.claude)
  claude-skill         absent     /home/researcher/.claude/skills/cohortdag-pipeline
  claude-mcp-plugin    absent     /home/researcher/.claude/skills/cohortdag
Google Antigravity: not detected (/home/researcher/.gemini/config)
  antigravity-plugin   absent     /home/researcher/.gemini/config/plugins/cohortdag
OpenAI Codex: not detected (/home/researcher/.codex)
  codex-skill          absent     /home/researcher/.codex/skills/cohortdag-pipeline

连接 Claude Code

去掉 --dry-run 和 --force 后,这条命令会安装 cohortdag-pipeline 技能并注册 CohortDAG 的 MCP 服务器。下面的输出来自 --dry-run:它只列出将要写入的内容(6 个文件),不做任何更改;不带这两个选项运行即可正式安装。重启 Claude Code,在它的聊天窗口输入 /cohortdag-pipeline,然后用自己的话提出要求,例如:“用 CohortDAG 构建示例生存分析流程,并在 Spark 上运行。”智能体会编写流程文件、检查它,并用 CohortDAG 自己的编译器和 Spark 后端运行它;Spark 需要 Java 和 pyspark,cohortdag doctor 会检查 Node、Python、Java 和 pyspark。向已打开的窗口添加步骤,需要你在列出这些步骤的对话框中接受,你也可以拒绝。

cohortdag agent install --target claude-code --dry-run --force
Claude Code — would write 6 file(s):
  /home/researcher/.claude/skills/cohortdag-pipeline/SKILL.md
  /home/researcher/.claude/skills/cohortdag-pipeline/examples/minimal.csp
  /home/researcher/.claude/skills/cohortdag-pipeline/.cohortdag-managed.json
  /home/researcher/.claude/skills/cohortdag/.claude-plugin/plugin.json
  /home/researcher/.claude/skills/cohortdag/.mcp.json
  /home/researcher/.claude/skills/cohortdag/.cohortdag-managed.json

连接 Codex 或 ChatGPT 桌面应用

这会把技能安装到 ~/.codex 下,并在 ~/.codex/config.toml 中注册 cohortdag 服务器;同一次安装同时适用于 Codex 命令行工具和 ChatGPT 桌面应用。重启你使用的那一个,在 ChatGPT 中输入 @cohortdag-pipeline 来调用该技能(在 Codex 命令行工具中则通过 /skills),然后像上面一样提出分析要求。ChatGPT 网站在浏览器中运行,无法访问你电脑上的程序,所以不能使用 CohortDAG。

cohortdag agent install --target codex --dry-run --force
OpenAI Codex — would write 4 file(s):
  /home/researcher/.codex/skills/cohortdag-pipeline/SKILL.md
  /home/researcher/.codex/skills/cohortdag-pipeline/examples/minimal.csp
  /home/researcher/.codex/skills/cohortdag-pipeline/.cohortdag-managed.json
  /home/researcher/.codex/config.toml [key mcp_servers.cohortdag]

连接 Google Antigravity

这会在 ~/.gemini/config/plugins/cohortdag 下安装一个插件(技能就在其中),并在 ~/.gemini/config/mcp_config.json 中注册 cohortdag 服务器。重启 Antigravity;插件会出现在 Settings → Customizations 中。然后像上面一样提出分析要求。

cohortdag agent install --target antigravity --dry-run --force
Google Antigravity — would write 5 file(s):
  /home/researcher/.gemini/config/plugins/cohortdag/plugin.json
  /home/researcher/.gemini/config/plugins/cohortdag/skills/cohortdag-pipeline/SKILL.md
  /home/researcher/.gemini/config/plugins/cohortdag/skills/cohortdag-pipeline/examples/minimal.csp
  /home/researcher/.gemini/config/plugins/cohortdag/.cohortdag-managed.json
  /home/researcher/.gemini/config/mcp_config.json [key mcpServers.cohortdag]

列出入门流程

列出智能体可以作为起点的流程。

cohortdag pipelines list --kind starter

检查流程

在运行之前,先对流程文件做结构检查。这里使用自带的生存分析入门流程。

cohortdag validate /opt/CohortDAG/resources/resources/templates/starter-survival.csp
valid

在 Spark 上运行

在 Apache Spark 上运行所有输出,并把会话连同结果保存为新的 .csp 文件,窗口界面可以直接打开它。

cohortdag run /opt/CohortDAG/resources/resources/templates/starter-survival.csp --all-outputs --save-session survival.csp

生成报告

把已保存会话的报告写成 Markdown。

cohortdag report survival.csp --out report --format md
Wrote study report (4 file(s)) to report

按组成部分查看流程

按阶段及下属分组输出流程。这里使用自带的 Bello-Chavolla 研究。

cohortdag outline /opt/CohortDAG/resources/resources/templates/study-bello-chavolla-2020-mexico-cox.csp
Data sources (0 groups, 1 node)
Cohort definition (1 group, 3 nodes)
  Keep confirmed SARS-CoV-2 cases — 3 nodes: Recodes covariates and follow-up, keeps RESULTADO = 1; writes `bello_chavolla_confirmed_cohort`.
Descriptive results (2 groups, 4 nodes)
  Confirmed cohort mortality (n = 51,633) — 2 nodes: Reads the confirmed cohort back; reproduces Table 1 (5,332 deaths).
  Training cohort, 80% split (n = 41,307) — 2 nodes: Random 80% split stratified by mortality, as in the paper (seed 123).
Analysis (2 groups, 6 nodes)
  Survival by diabetes status — 2 nodes: Kaplan-Meier curves for known diabetes status; reproduces Figure 2.
  Table 2 Cox models — 4 nodes: Individual variables, the lethality score and its risk categories; reproduces Table 2.

为流程生成分组建议

以 JSON 格式输出分组建议,不会修改文件。按各组的用途重新命名后,用 cohortdag groups apply 保存。

cohortdag groups propose /opt/CohortDAG/resources/resources/templates/starter-survival.csp

检查分组是否易读

检查流程中分组的名称、大小和说明。每条问题都附有修改建议;自带的研究没有问题。

cohortdag groups lint /opt/CohortDAG/resources/resources/templates/study-bello-chavolla-2020-mexico-cox.csp --strict
no findings

在窗口中,Help > Connect AI Agents… 的作用与 cohortdag agent install 相同,每次连接一个智能体。