# QDD Installation Guide

这份文档回答一个很实际的问题：**别的用户怎么安装 QDD，并且在自己的目录里使用，而不是依赖你当前这个仓库路径。**

在安装之前，先记住 QDD 对外只保留的最小工作流：

1. `qdd-start`：完成项目 onboarding，把生物背景、数据资源、运行环境注入共享上下文
2. `qdd-propose`：人给模糊研究计划，Agent 创建 `study.md` 和 `task.md`
3. `qdd-explore`：人和 Agent 讨论并完善 `study.md` / `task.md`
4. `qdd-apply`：Agent 读取假设和任务要求，写代码、跑结果、产出证据
5. `qdd-close`：Agent 评判假设，把可复用内容写回 `context` / `artifacts`，并给出 follow-up 方向
6. `qdd-conclude`：通用 Agent 跨 study 综合证据，经两轮人工确认写出完整 `story.md`，再忠实渲染为 TeX

当前代码中的实际入口分别是：

- `qdd-start` -> 安装后的 `qdd-start`
- `qdd-propose` -> 安装后的 `qdd-propose`
- `qdd-explore` -> 安装后的 `qdd-explore`
- `qdd-apply` -> 安装后的 `qdd-apply`
- `qdd-close` -> 安装后的 `qdd-close`
- `qdd-conclude` -> Codex 中的 `$qdd-conclude`，或 Claude Code 中的 `/qdd-conclude`

另外，底层脚手架命令仍然是：

- `qdd init`

## 前提

目标用户需要：

- Node.js `>= 20.19.0`
- npm
- 一个可写的 home 目录

可选：

- Claude Code
- Codex / `~/.codex`

QDD 当前没有发布到 npm registry，所以安装方式是 **源码安装** 或 **tarball 安装**。

## Python 分析环境

如果要直接运行 `domain-skills/` 里的分析脚本，除了 Node CLI 之外，还需要单独准备分析环境。

仓库提供了一个可选的稳定核心环境文件，方便新用户快速获得当前已落地 skill 的常用依赖：

```bash
conda env create -f envs/qdd-skill-core.yml
conda activate qdd-skill-core
```

这份环境覆盖了当前已落地的 skill 依赖，包括：

- `scanpy`
- `squidpy`
- `scvelo`
- `pydeseq2`
- `gseapy`
- `python-igraph`
- `leidenalg`
- `cellxgene-census`
- `harmonypy`
- `scanorama`
- `bbknn`
- `scib`

这不是 QDD 协议要求的唯一环境。实际运行时，应先激活你的项目分析环境；如果你使用上面的示例环境，就先 `conda activate qdd-skill-core`，然后直接运行脚本：

```bash
python <skill-script>.py ...
```

不要用未激活的系统 Python 去判断这些 skill 是否“缺依赖”，否则很容易把本地 shell 环境和项目分析环境混淆。

当前这套已发布 skill **不依赖 R 包**。如果后面真的引入 R-backed skill，再单独补 `R` 环境文件，不要提前把默认环境做重。

### 可选深度学习 / GPU 后端

当前默认 skill 环境不强制安装 PyTorch、scVI 或其他大型深度学习栈。后续 PyTorch-backed executor skill 应遵循这套轻量规则：

- 默认设备参数使用 `--device auto`
- `auto` 优先使用 CUDA；后端支持时可使用 MPS；没有可用加速器时回退 CPU
- GPU 到 CPU 的回退只允许发生在同一个已选择的方法内，不能把 `method=scvi` 静默改成 Harmony 之类的其他算法
- 缺少可选依赖时，只有任务或用户显式允许 `--install-missing` 才能自动安装
- 如果未授权安装或安装失败，skill 应明确报错，并在报告里说明缺少的包和建议命令
- 成功安装或设备回退都应写入 `result.json` / `report.md`

---

## 方案 A：从源码全局安装（推荐）

适合：开发者、本机长期使用者。

### 1. 获取仓库

```bash
git clone <your-qdd-repo-url>
cd qdd
```

### 2. 安装依赖并构建

```bash
npm install
npm run build
```

### 3. 全局安装 CLI

```bash
npm install -g .
```

### 4. 验证

```bash
qdd --version
which qdd
```

安装完成后，这个用户就可以在**任意目录**运行：

```bash
mkdir ~/research/my-qdd-project
cd ~/research/my-qdd-project
qdd init .
```

这一步已经和你的原始仓库目录解耦了。

---

## 方案 B：分发 tarball 给别的用户

适合：另一台机器、另一个用户、或者不想直接给源码仓库的人。

### 维护者打包

在 QDD 仓库根目录执行：

```bash
npm install
npm run build
npm pack
```

会生成一个类似下面的文件：

```text
qdd-0.1.0.tgz
```

把这个文件发给对方。

### 对方安装

```bash
npm install -g ./qdd-0.1.0.tgz
```

然后验证：

```bash
qdd --version
```

之后就可以在自己的任意目录里初始化项目：

```bash
mkdir my-qdd-project
cd my-qdd-project
qdd init .
```

---

## 方案 C：开发态安装（`npm link`）

适合：本地继续开发 QDD，同时想直接测试 `qdd` 命令。

在仓库根目录执行：

```bash
npm install
npm run build
npm link
```

之后当前用户就能直接用：

```bash
qdd --version
```

如果你改了源码，需要重新构建：

```bash
npm run build
```

---

## 初始化一个新项目

安装好 CLI 后，QDD 的使用与源码位置无关。你只需要在目标研究目录中执行：

```bash
mkdir my-qdd-project
cd my-qdd-project
qdd init .
```

默认会安装两套 bootstrap：

- Claude Code
- Codex

如果只想装一套：

```bash
qdd init . --tool claude
qdd init . --tool codex
```

如果后续升级了 QDD，想刷新当前项目的 bootstrap：

```bash
qdd init . --refresh-bootstrap
```

初始化后，先由人补两个项目级真相源：

- `contract.yaml`
- `context/resources.md`

更推荐直接让 Agent 先走：

- `qdd-start`

---

## 安装后会写到哪里

### 项目内

`qdd init .` 会在当前项目写入：

```text
.qdd/
.claude/
.codex/skills/qdd/
artifacts/data/
contract.yaml
evolution.yaml
context/
studies/
artifacts/
```

### 用户级

如果启用了 Codex，QDD 还会写用户级 prompt：

```text
$CODEX_HOME/prompts/
```

默认情况下：

```text
~/.codex/prompts/
```

也就是说：

- `.codex/skills/qdd/` 是**项目级**的 QDD workflow skill surface
- `.claude/skills/` 和 `.claude/commands/` 是 Claude Code 的**项目级** QDD workflow surface
- `~/.codex/prompts/` 是**用户级**的

`qdd-conclude` 的关键安装路径是：

```text
.codex/skills/qdd/qdd-conclude/SKILL.md
.claude/skills/qdd-conclude/SKILL.md
.claude/commands/qdd-conclude.md
$CODEX_HOME/prompts/qdd-conclude.md
```

这和 OpenSpec 的做法一致，便于多个项目共用同一组 Codex prompt 名称。

当前推荐的 skill 目录结构是：

```text
domain-skills/
├── plot/
│   └── marker-heatmap/
│       ├── SKILL.md
│       └── scripts/
├── genomics/
└── env/
```

其中：

- `domain-skills/` 是仓库里的中央领域 skill 源目录
- `qdd` 会直接从这里解析 task `skills:` 和 `qdd skills suggest`
- `qdd/*` 是 workflow skill，不应写进 task `skills:`
- task `skills:` 只应引用领域 skill，例如 `plot/...`、`genomics/...`、`env/...`

项目内保留的只是 workflow bootstrap，大致是：

```text
.codex/skills/
└── qdd/
```

如果你更新了仓库里的 `domain-skills/`，对某个项目执行：

```bash
qdd init . --refresh-bootstrap
```

就会刷新 workflow bootstrap，并更新 `.qdd/bootstrap.yaml` 里的中央 skill 源路径配置。

---

## 最短使用流程

```bash
qdd init .
```

然后让 Agent 按这条最小循环工作：

1. `qdd-start`
2. `qdd-propose`
3. `qdd-explore`
4. `qdd-apply`
5. `qdd-close`

项目达到可综合状态后，使用第六个 human workflow 生成论文：

- Codex：`$qdd-conclude`
- Claude Code：`/qdd-conclude`

它先生成跨 study 的 `research_synthesis.md`，在 Gate 1 与用户对齐叙事后才写完整 `story.md`，并在 Gate 2 接受该 story 后才渲染 TeX。它不是 `qdd conclude` CLI，也不会启动 auto 或 SDK production session。

如果 Agent 需要结构化读取边界，最常用的是：

```bash
qdd status --json
qdd instructions PROJECT --command qdd-start --json
qdd instructions STUDY-001 --command qdd-apply --json
qdd instructions TASK-001 --command qdd-apply --json
qdd validate --json
```

这一套就够了。对外介绍时，不需要把 QDD 讲成更多层命令系统。

---

## 升级方式

如果用户是通过源码目录安装的：

```bash
cd /path/to/qdd
git pull
npm install
npm run build
npm install -g .
```

如果用户是通过 tarball 安装的：

```bash
npm install -g ./qdd-<new-version>.tgz
```

升级 CLI 后，建议在已有项目里执行一次：

```bash
qdd init . --refresh-bootstrap
```

---

## 卸载

```bash
npm uninstall -g qdd
```

这只会移除 CLI，不会删除已经初始化的 QDD 项目。

---

## 常见问题

### 1. `qdd: command not found`

通常是 npm global bin 不在 `PATH` 里。

先看：

```bash
npm bin -g
```

把输出目录加入 shell 的 `PATH`。

### 2. Codex prompt 没装到预期位置

检查：

```bash
echo $CODEX_HOME
```

如果没设置，默认就是：

```text
~/.codex
```

### 3. 新版本 prompt 没生效

在项目根目录执行：

```bash
qdd init . --refresh-bootstrap
```

### 4. 别的用户不在你的仓库目录下，还能用吗？

可以。只要他已经通过全局安装拿到 `qdd` 命令，后续就只和**他自己的项目目录**有关，不依赖你的仓库绝对路径。

---

## 维护建议

如果你准备给更多人分发，建议采用这条流程：

1. 在主仓库里完成修改
2. `npm run build`
3. `npm test`
4. `npm pack`
5. 分发 `qdd-<version>.tgz`

这样最稳，不要求对方理解仓库结构，也不要求对方在你的源码目录里工作。