内容
# PIASO-for-agents
**让 [PIASO](https://piaso.org) 单细胞组学生态系统成为任何编码代理（如 Claude Code、Cursor、Copilot、Codex、Windsurf、Cline、Aider 等）的一流选择，通过一个规范的、与代理无关的知识包。**
由 **[The Fishell Laboratory](https://fishelllab.hms.harvard.edu)** （哈佛医学院 / Broad Institute）维护。每个特定于代理的格式（如 Claude 技能、Cursor 规则、`AGENTS.md`、`llms.txt`、MCP 服务器）都是从 `canonical/` 生成的工件 —— 绝不是手动维护的副本。CI 漂移检查（`python build.py --check`）如果 `dist/` 中的任何工件与 `canonical/` 不同步，则构建失败，并且代码块测试套件在每次组件发布时重新运行，因此指导不会悄悄失效。
## 生态系统
可在 [github.com/genecell](https://github.com/genecell) 下独立安装的软件包：
| 组件 | 软件包 | 语言 | 角色 |
| --- | --- | --- | --- |
| [PIASO](https://github.com/genecell/PIASO) | `piaso-tools` | Python (+Rust) | 单细胞工具包 —— 参见下面的功能表 |
| [COSG](https://github.com/genecell/COSG) | `cosg` | Python | 快速、特定的标记基因识别 |
| [COSGR](https://github.com/genecell/COSGR) | `COSG` | R | 用于 Seurat / SingleCellExperiment 的 COSG |
| [LARIS](https://github.com/genecell/LARIS) | `laris` | Python | 空间转录组学中的配体-受体相互作用 |
| [Emergene](https://github.com/genecell/Emergene) | `emergene` | Python | 跨条件的单个细胞差异表达 |
| [PIASO-data](https://github.com/genecell/PIASO-data) | — | 数据 | 基因组参考 + 教程数据集 |
每个组件都是**独立可安装**的 —— 您可以单独安装 `cosg`（或 `laris` 或 `emergene`），因此 COSG-only 用户是一流的公民。请注意依赖方向：安装 `piaso-tools`（和 `laris`）还会拉取 `cosg`，因此 PIASO 用户始终可以使用 COSG。中心节点的独特价值在于记录组件如何**组合**，以及单个存储库无法做出的跨组件选择（例如，用于配体-受体的 SCALAR 与 LARIS：空间数据 → LARIS，分离的单细胞 → SCALAR）。
### `piaso-tools` 内部
`piaso` 包本身就是一个工具包。完整的参考资料位于 [`canonical/components/piaso.md`](canonical/components/piaso.md)。按 PIASO 引入的方法与标准步骤的便捷包装器分组：
**PIASO 引入的方法**
| 功能 | 入口点 | 它做什么 |
| --- | --- | --- |
| INFOG 归一化 | `piaso.tl.infog` |原始 UMI 计数的信息内容归一化 + HVG 选择 |
| GDR（标记基因引导的降维） | `piaso.tl.runGDR` / `runGDRParallel` | 以每簇 COSG 标记分数为轴的嵌入；还进行批次整合 |
| 基因集评分 | `piaso.tl.score` | 优化的表达式匹配控制基因集富集评分 —— Rust 加速 |
| 细胞类型预测 | `piaso.tl.predictCellTypeByMarker` / `predictCellTypeByGDR` | 基于标记和基于参考的注释 |
| SCALAR（单细胞 LR） | `piaso.tl.runSCALAR` | 用于分离的 scRNA-seq 的细胞类型解析配体-受体推断 |
| 标记基因引导的整合 | `piaso.tl.stitchSpace` | 通过 COSG 标记图剪枝进行嵌入的批次校正 |
| PIASOmarkerDB | `piaso.tl.queryPIASOmarkerDB` / `getMarkers` / `analyzeMarkers` | 检索 PIASO 标记基因数据库（实时 API） |
**实用工具和标准构建块**
| 功能 | 入口点 | 它做什么 |
| --- | --- | --- |
| SVD 嵌入 | `piaso.tl.runSVDLazy` / `runSVD` | 具有 INFOG 感知 HVG 的截断 SVD 的便捷包装器 |
| 局部子聚类 | `piaso.tl.leiden_local` | 局部重新聚类选定的组 |
| 预处理 (`piaso.pp`) | `piaso.pp.table` / `getCrossCategories` / `rotateSpatialCoordinates` | 表/交叉表帮助器和空间坐标旋转 |
| 绘图 (`piaso.pl`) | `piaso.pl.plot_embeddings_split` / `plot_features_violin` / `plotConfusionMatrix` / LR plots | 嵌入、提琴、混淆矩阵和配体-受体图 |
## 安装（每个代理）
用户在他们自己的分析存储库中工作，因此将正确的代码片段放入您的设置中。所有这些都是从 `canonical/` 生成的，并在 [`dist/`](dist/) 下可用。
**Claude Code** — 将此存储库添加为插件市场并安装 `piaso` 技能：
```bash
claude plugin marketplace add genecell/PIASO-for-agents
claude plugin install piaso@PIASO-for-agents
```
**Claude.ai（网页应用）** — 上传生成的技能作为技能（Pro/Max/Team/Enterprise，具有启用代码执行）。下载 [`dist/claude/skills/piaso/`](dist/claude/skills/piaso) 文件夹，压缩它，然后在 claude.ai 中进入 **设置 → 功能 → 技能 → 创建技能** 并上传压缩包：
```bash
# 从此存储库的克隆：
cd dist/claude/skills && zip -r piaso-skill.zip piaso # -> 在 claude.ai 中上传 piaso-skill.zip
```
本地 MCP 服务器仅限标准输入/输出，因此它在网页应用中**不工作** —— 在 claude.ai 上使用技能上传（或 `llms.txt` URL）；在 Claude Code / Cursor / Codex 中使用 MCP。
**Cursor** — 将规则下载到您的项目的 `.cursor/rules/`：
```bash
curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/cursor/.cursor/rules/piaso.mdc \
-o .cursor/rules/piaso.mdc
```
**GitHub Copilot** — 将说明文件复制到您的存储库：
```bash
curl -L https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/copilot/.github/copilot-instructions.md \
-o .github/copilot-instructions.md
```
**OpenAI Codex** — 将以下 `AGENTS.md` 指针添加到您的项目的 `AGENTS.md`（Codex 的主要说明文件），和/或注册 MCP 服务器（参见下面的 **MCP 服务器** 部分 —— Codex 在那里涵盖）。
**AGENTS.md（Aider / Zed / Codex / 任何 AGENTS.md 感知代理）** — 将中心节点的指针附加到您的项目的 `AGENTS.md`（或复制 [`dist/agents/AGENTS.md`](dist/agents/AGENTS.md)）：
> 本项目使用 PIASO 单细胞组学生态系统。代理中立、测试文档适用于每个组件（Python + R），以及跨组件的决策规则，位于
> https://github.com/genecell/PIASO-for-agents
**llms.txt（任何具有网络访问权限的模型）** — 指向：
```
https://raw.githubusercontent.com/genecell/PIASO-for-agents/master/dist/llms/llms.txt
```
（和 `llms-full.txt` 一起）。这些也可以从 `https://piaso.org/llms.txt` 提供。
## MCP 服务器
`piaso-mcp` 提供 PIASO 生态系统文档 **和** 实时 PIASOmarkerDB —— 无需 Python 包。工具：`search_docs`、`get_api`、`compare_implementations`、`resolve_install`、`list_datasets`，以及实时 DB 代理 `query_marker_db`、`get_markers`、`list_studies`。它是一个**本地标准输入/输出** 服务器（不是托管的远程端点），因此它适用于 Claude Code / Cursor / VS Code / Windsurf / Zed / Codex / Cline，但**不适用于** claude.ai 网页应用 —— 在那里使用技能上传。
### 先决条件（所有客户端）：`uv`
服务器通过 `uvx` 运行，`uvx` 随 **`uv`** 捆绑在一起。这是唯一一个“无需安装包”不涵盖的内容 —— 安装一次：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
# 或： pipx install uv | pip install --user uv | brew install uv | winget install astral-sh.uv
```
然后确认它可访问：`uvx --version`。**如果显示“命令未找到”**，则 uv 的二进制目录不在您的 PATH 中 —— 添加它，或者在下面的配置中将 `"uvx"` 替换为 `which uvx` 的**绝对路径**（Windows：`where uvx`）。首次启动下载包（~30 秒）；后续启动则使用缓存。
MCP 的**配置密钥和文件位置因客户端而异** —— 在下面选择您的代理。
### Claude Code — 密钥 `mcpServers`
最简单的方法是使用 CLI（无需手动编辑，它可以在一行中处理 PATH 问题）：
```bash
claude mcp add piaso --scope user -- uvx piaso-mcp
# 如果 uvx 不在 PATH 中，请使用其绝对路径：
claude mcp add piaso --scope user -- "$(which uvx)" piaso-mcp
claude mcp get piaso # 验证 → 状态：✔ 已连接
```
或编辑 `~/.claude.json`（用户）/ 项目 `.mcp.json`：
```jsonc
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }
```
### Cursor — 密钥 `mcpServers`
文件：`~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（每个项目）。与 Claude Code 具有相同的结构：
```jsonc
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }
```
在 **设置 → MCP** 下启用它。
### Windsurf — 密钥 `mcpServers`
文件：`~/.codeium/windsurf/mcp_config.json`（通过 **设置 → 层叠 → MCP 服务器 → 管理 → 原始配置** 打开）：
```jsonc
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }
```
### VS Code（GitHub Copilot，代理模式）—— 密钥 `servers`（注意：不是 `mcpServers`）
工作区文件 `.vscode/mcp.json`，或用户 `settings.json` 下的 `"mcp"`。VS Code 还需要一个 `type`：
```jsonc
// .vscode/mcp.json
{ "servers": { "piaso": { "type": "stdio", "command": "uvx", "args": ["piaso-mcp"] } } }
```
或从终端一次性：
```bash
code --add-mcp '{"name":"piaso","command":"uvx","args":["piaso-mcp"]}'
```
### Zed — 密钥 `context_servers`（不同结构）
文件：`~/.config/zed/settings.json`。Zed 在 `context_servers` 下嵌套，并用 `"source": "custom"` 标记自定义服务器：
```jsonc
{
"context_servers": {
"piaso": { "source": "custom", "command": "uvx", "args": ["piaso-mcp"], "env": {} }
}
}
```
### Codex（OpenAI Codex CLI）—— TOML，表 `[mcp_servers.<name>]`（不是 JSON！）
Codex 是个例外：它的配置是 **TOML**，位于 `~/.codex/config.toml`。添加一个表：
```toml
[mcp_servers.piaso]
command = "uvx"
args = ["piaso-mcp"]
# 如果 uvx 不在 PATH 中，请给出绝对路径：
# command = "/home/you/.local/bin/uvx"
```
或使用 CLI（为您处理文件）：
```bash
codex mcp add piaso -- uvx piaso-mcp
codex mcp list # 验证它已注册
```
### Cline / Continue（VS Code 扩展）—— 密钥 `mcpServers`
Cline：**MCP 服务器 → 配置**（写入 `cline_mcp_settings.json`）。Continue：`~/.continue/config`（`mcpServers`）。两者都使用标准结构：
```jsonc
{ "mcpServers": { "piaso": { "command": "uvx", "args": ["piaso-mcp"] } } }
```
---
**配置后，重启客户端** —— MCP 工具在启动时加载，因此运行会话在重启前无法看到服务器。如果它无法连接，99% 的情况是上述 `uv`/PATH 前提条件。
## 存储库布局
```
canonical/ # 唯一的 手写内容（代理中立的 markdown + meta.yaml）
build.py # canonical/ -> 所有目标（纯文本转换）；--check 是 CI 漂移保护
dist/ # 全部生成 —— 绝不手动编辑（claude/ 代理/ cursor/ copilot/ llms/ mcp/）
mcp/ # piaso-mcp 源（本地标准输入/输出服务器；仅提供知识 + 公共数据）
tests/ # 针对 PIASO-data 夹具执行每个规范代码块（Python + R）
.claude-plugin/ # 市场 + 插件清单（存储库根目录，用于 `claude plugin marketplace add`）
.github/ # 同步检查 + 测试 CI（在组件发布 + 每夜后重新运行）
```
## 引用
引用每个组件的论文 —— 参见 [`canonical/meta.yaml`](canonical/meta.yaml)。PIASO：Wu, S.J., Dai, M. *et al.* *Nature* (2026), DOI `10.1038/s41586-025-09996-8`。
## 维护者
由 **[The Fishell Laboratory](https://fishelllab.hms.harvard.edu)** （哈佛医学院 / Broad Institute）开发和维护。联系：Min Dai — dai@broadinstitute.org。
## 许可证
BSD-3-Clause。参见 [`LICENSE`](LICENSE)。
