Claude Code 使用教程：安装、登录、CLAUDE.md、权限模式与常用命令

# macOS / Linux / WSL：原生安装（推荐，后台自动更新）
curl -fsSL https://claude.ai/install.sh | bash
# 想要比 latest 晚约一周、跳过有严重回归版本的 stable 通道
curl -fsSL https://claude.ai/install.sh | bash -s stable

# Windows PowerShell（提示符以 PS 开头）
irm https://claude.ai/install.ps1 | iex
# Windows CMD（提示符不带 PS）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# 包管理器（不自动更新）
brew install --cask claude-code          # stable 通道；claude-code@latest 为 latest 通道
winget install Anthropic.ClaudeCode

# npm（要求 Node.js 22+；不要加 sudo）
npm install -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@latest   # 升级用这条，不用 npm update -g

# 验证
claude --version     # 本页实测输出：2.1.296 (Claude Code)
claude doctor        # 只读诊断：安装方式、自动更新、settings 文件校验

# 先在 shell 里 export 两个变量，再用 1 个 token 的请求验证地址和凭据
export ANTHROPIC_BASE_URL=https://gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-xxxx
curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'
# 返回 {"id":"msg_... 说明通；报“未知模型”也说明地址和凭据是对的；401 就换成 x-api-key 头和 ANTHROPIC_API_KEY
# 进入 claude 后运行 /status，确认出现 Anthropic base URL 和 Auth token 两行

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxx",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "网关提供的模型名",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "网关提供的轻量模型名",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "128000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "600000"
  }
}

# 项目：单细胞数据的差异表达分析

## 目录约定
- data/raw/：原始数据，只读。不修改、不移动、不删除，也不在原地解压或排序。
- data/processed/：由 scripts/ 中的脚本从 raw 生成，可以随时删除重建。
- scripts/：所有分析步骤，按 01_、02_ 编号，每个脚本可独立运行。
- results/：图表与表格，文件名带脚本编号，例如 03_volcano.pdf。
- logs/：每次运行的日志，文件名带时间戳。

## 运行环境
- 用 conda 环境 scrna-2026（environment.yml 已锁版本）。安装新包前先问我。
- 运行脚本：python scripts/<名称>.py 2>&1 | tee logs/$(date +%Y%m%d-%H%M%S)-<名称>.log

## 可复现要求
- 所有随机过程固定 seed=20261010，并写进结果表的元数据。
- 结果里的每个数字必须能由 scripts/ 中的某个脚本重新生成，不在对话里手算。
- 修改分析参数时，同时更新 docs/params.md 中的参数表与修改理由。

## 统计约定
- 差异表达用 Wilcoxon 检验，BH 校正，padj < 0.05 且 |log2FC| > 1。
- 样本信息以 data/raw/metadata.csv 为准，分组名保持原样。

## 长任务
- 预计超过 5 分钟的命令用 nohup 后台运行并写日志，之后读日志汇报进度。

<!-- 维护说明：这行 HTML 注释不会进入 Claude 的上下文 -->
See @docs/params.md for current parameters.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(python scripts/*)",
      "Bash(Rscript scripts/*)",
      "Bash(git diff *)",
      "Bash(git status)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(pip install *)",
      "Bash(conda install *)"
    ],
    "deny": [
      "Edit(data/raw/**)",
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  },
  "env": { "BASH_DEFAULT_TIMEOUT_MS": "600000" },
  "cleanupPeriodDays": 365
}

# 原始数据设为操作系统级只读（本页实测：之后 Python 追加写入报 PermissionError，rm -f 报 Permission denied）
chmod -R a-w data/raw
# 需要更新原始数据时由你自己解除
chmod -R u+w data/raw

---
name: stats-reviewer
description: Reviews analysis scripts and result tables for statistical errors. Use after an analysis script changes or before results go into a figure or manuscript.
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是统计方法审阅者。检查：样本量与分组是否与 data/raw/metadata.csv 一致；多重比较是否校正；
随机种子是否固定；结果表中的数字能否由 scripts/ 中的脚本重新生成。只报告问题与证据，不修改文件。

#!/bin/bash
# .claude/hooks/protect-raw.sh：拦截 Edit/Write 对 data/raw/ 的写入
# 退出码 2 表示阻止，stderr 内容会作为理由反馈给 Claude
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
if [[ "$FILE_PATH" == *"/data/raw/"* ]]; then
  echo "Blocked: $FILE_PATH is raw data (read-only). Write to data/processed/ or results/." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-raw.sh" }
        ]
      }
    ]
  }
}

---
name: run-analysis
description: Run one analysis script reproducibly and log the environment. Use when the user asks to run or rerun an analysis.
disable-model-invocation: true
---

1. 记录 `git rev-parse --short HEAD`、`python --version` 与 `conda env export --no-builds` 到 logs/。
2. 用 `python scripts/$ARGUMENTS 2>&1 | tee logs/$(date +%Y%m%d-%H%M%S)-run.log` 运行。
3. 汇报输出文件路径与关键数字，不修改 data/raw/。

# 添加 MCP 服务器（默认 local 作用域，只对你在当前项目生效，写入 ~/.claude.json）
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add my-db -e DB_URL=postgres://... -- npx -y some-db-mcp
# 与课题组共享：写入项目根目录的 .mcp.json（队友首次运行 claude 时需要批准）
claude mcp add --scope project zotero -- npx -y zotero-mcp
claude mcp list            # 未批准的 .mcp.json 服务器显示为 Pending approval
# 检查 agent 与 skill 文件格式（本页实测：缺 description 只给 warning，但运行时会跳过该 agent）
claude plugin validate .claude/agents

# 单次运行，结果写成 JSON，便于脚本读取 result、session_id、total_cost_usd
claude -p "读取 results/03_de_genes.csv，列出 padj 最小的 20 个基因及其 log2FC" \
  --output-format json --permission-mode dontAsk --allowedTools "Read" \
  --max-turns 5 --max-budget-usd 0.50 < /dev/null > logs/summary.json
jq -r '.result' logs/summary.json

# 批量：每个样本一次独立运行，失败时退出码非 0
for s in S01 S02 S03; do
  claude -p "检查 data/processed/$s.h5ad 的细胞数、基因数和线粒体比例分布，写一段 QC 结论" \
    --permission-mode dontAsk --allowedTools "Read" "Bash(python scripts/qc_summary.py *)" \
    < /dev/null > logs/qc-$s.md || echo "$s failed" >> logs/failed.txt
done

# 会话恢复
claude --continue                 # 当前目录最近一次交互会话
claude --resume                   # 打开会话列表（Ctrl+A 显示本机所有项目）
claude --resume de-analysis       # 按名称恢复（会话中用 /rename de-analysis 命名）
claude -p --resume <session-id> "总结这次改了哪些参数" --output-format json | jq -r '.result'

# 让 Claude 启动长任务时用这种写法：任务独立于 Claude 的进程，日志落盘
nohup python scripts/05_train.py --config configs/run3.yaml \
  > logs/run3-$(date +%Y%m%d-%H%M).log 2>&1 &
echo $! > logs/run3.pid
# HPC 上提交到调度器，不在登录节点上跑
sbatch scripts/05_train.slurm
# 之后让 Claude 读 tail -n 50 logs/run3-*.log 汇报进度，而不是在前台等待