# 00-SPEC 共享写作规范（所有章节必须遵守）

> 本文件是全书统一规范。任何章节写作前必须先读本文件与 `outline.md`。
> 项目根：`C:\Users\Kael\Desktop\DSH\project_1\spatial-niche-tutorial`

## 1. 定位与风格
- 读者：**刚入门的生信新手**。默认读者会基础 R/Python，但不懂空间转录组。
- 风格：**手把手、步骤化**。每个分析步骤 = 目的 → 代码 → 输出解读 → 常见坑。
- 语气：耐心、鼓励；不说"显然""众所周知"。
- 概念先行：每个专业名词第一次出现时给出**中文解释 + 英文原名**，如"空间生态位（spatial niche）"。
- 每章结构固定：
  1. 本章目标（3-5 条，`## 本章目标`）
  2. 正文若干节（`## 1.x` 小节）
  3. 代码块（R/Python/bash 带注释）
  4. 图引用（至少 1 张，`图 X-X`）
  5. 小结（`## 本章小结`）
  6. 练习与思考（`## 练习与思考`，3-5 题，含"动手题"）

## 2. 技术栈与版本（全书统一，不得冲突）
- R ≥ 4.3、RStudio；Seurat v5（注意与 v4 语法差异）、CellChat v2、BayesSpace、tidyverse、patchwork
- Python ≥ 3.10、scanpy、squidpy、anndata、matplotlib、pandas、numpy、cell2location（可选）
- 示例数据：10x Visium 人乳腺癌 demo（官方下载）；教学图为模拟数据风格
- 若某章节用到不同版本，须注明"本书以 XX 版本为例"

## 3. 代码规范
- 语言标注：R 代码块用 ` ```r `，Python 用 ` ```python `，shell 用 ` ```bash `
- 代码必须**可运行**（注释中的伪代码除外，需标明"伪代码"）
- 注释用中文，解释"为什么"而非"是什么"
- 输出解读：代码后必须有一小段"运行结果解读"
- 代码文件命名：`code/0X_xxx.R`，与章节目录无关，按流程顺序

## 4. 图表规范
- 图统一存放 `figures/`，命名 `figNN_name.png`
- 正文引用格式：`图 8-1`（第 8 章第 1 张图）；交叉引用写"见图 10-2"
- 每张图必须有图注（figure caption）：一句话说明 + 关键信息
- 图引用写法示例：
  `![图 8-1 质控指标分布。左：UMI 数 violin；右：基因数 violin；中：线粒体比例。](figures/fig07_qc.png){width=80%}`
- 注意：markdown 里图片路径用相对路径 `figures/xxx.png`

## 5. 术语一致性（首次出现加英文）
| 中文 | 英文 | 备注 |
| --- | --- | --- |
| 空间生态位 | spatial niche | 核心概念 |
| 空间域 | spatial domain | 与 niche 可互换，注意行文统一 |
| 邻域 | neighborhood | |
| 细胞通讯 | cell-cell communication (CCC) | |
| 配体-受体 | ligand-receptor (L-R) | |
| 侵袭前沿 | invasive front | |
| 免疫浸润区 | immune-infiltrated region | |
| 肿瘤核心 | tumor core | |
| 去卷积 | deconvolution | |
| spot | spot | 10x Visium 的捕获点，保留英文 |
| 通讯重编程 | communication reprogramming | 核心卖点 |

## 6. 字数与篇幅
- 每章 2500–4000 中文字（不含代码）；代码块不占字数
- 代码总量：每章 40–120 行
- 全书约 4 万字

## 7. 引用与参考文献
- 引用文献用 `[作者 年份]` 格式（如 [Jin 2024]），文末附录 B 汇总
- 关键工具首次出现给官网/仓库地址
- 论文类论断须可回溯（见 literature/references.bib）

## 8. 科学严谨性
- 区分"分析结果"与"生物学解释"：解释处写明"这提示……""需要实验验证"
- 通讯推断是**计算预测**，不是直接测量——每章涉及通讯结论必须提醒读者
- 统计方法注明（如 BH-FDR 校正、排列检验）

## 9. Markdown 格式要求
- 标题：`#` 章号与标题（如 `# 第 08 章 预处理与质控`）；`##` 小节；`###` 子小节
- 列表、表格用标准 markdown；表格用于参数、对比、脚本清单
- 中英文之间加空格（如"使用 R 语言"），中文引号用「」或“”，代码内 ASCII 引号
- 强调用 `**加粗**`；不要用下划线

## 10. 交付检查（每章完成前自查）
- [ ] 章节结构符合第 1 节模板
- [ ] 图引用路径正确（相对路径 figures/）
- [ ] 代码块语言标注正确、可运行
- [ ] 术语中英对照、全书一致
- [ ] 无未解释缩写；有"运行结果解读"
- [ ] 字数达标
