Imported from h4rvey-g/bioinfo-for-dummies (AGENTS.md). Install upstream with npx skills add h4rvey-g/bioinfo-for-dummies. Copyright stays with the author.

Repository Guidelines

本仓库贡献须知（简体中文，精炼版）。

项目结构与模块

• 章节：根目录下按编号命名的 .qmd（例 1.2.AI-code.qmd），保证顺序与标题一致。
• 配置：_quarto.yml 决定章节顺序、主题与输出格式，新增/删除章节时同步更新。
• 产物：_book/ 为渲染结果，.quarto/ 为缓存，均已列入 .gitignore。
• CI：.github/workflows/quarto-gh-pages.yml 负责构建并发布 HTML 站点。

构建、测试与开发命令

• quarto preview：本地热重载预览（HTML）。
• quarto render：完整构建到 _book/；需要 PDF 时追加 --to pdf（需 LaTeX）。
• quarto check：检测 Quarto 依赖与引擎，换机或首次提交前执行。
• 需先安装 Quarto CLI（https://quarto.org/docs/get-started/），确保在 PATH 中。

编码风格与命名

• 文稿：短句、主动语态，避免冗长；每段聚焦单一观点。
• 标题：保留数字前缀匹配章节序（如 # 2.3 Environment Management）。
• 代码块：使用围栏并标注语言（bash`, r, ```python）。
• YAML/JSON：两空格缩进；长行约 100 字符换行。
• 资源：图片用相对路径引用，放在对应章节附近；替换封面时更新 cover.png。

内容编排原则

• 面向零基础读者，章节从概念启蒙到实操进阶，由浅入深排列；每章开头先交代预备知识。
• 每个新术语首次出现时给一句定义 + 一个具体例子，必要时补上简单类比或小图示。
• 先讲“为什么/场景”，再讲“是什么/原理”，最后讲“怎么做/命令与配置”，确保落地可操作。
• 练习与示例按难度递增：起步用最小可复现样例，进阶再引入多样数据或参数。
• 结论与摘要用通俗表述，避免堆砌公式或行话；保留进一步阅读链接供有基础的读者拓展。

章节写作规范

• 每章结尾添加两小节：任务清单（列出本章建议读者完成的步骤或练习）与 重点内容（对任务清单中需要解释的内容做出解说）。
• 列表保持简洁、可执行；必要时给出示例命令或路径。

测试指引

• 提交前运行 quarto render --quiet，确保所有章节可编译。
• 检查链接与引用是否有效；文献集中在 references.bib，引用格式 [@key]。
• 不提交 _book/ 与 .quarto/，必要时可本地重建。

提交与 PR 规范

• 沿用 Conventional Commits（如 feat: ...、fix: ...、docs: ...、chore: ...）。
• PR 需写明目的、影响的章节、已执行的命令（如 quarto render），样式变动可附截图。
• PR 尽量聚焦单一改动；若调整章节顺序务必同步修改 _quarto.yml；有关联 issue 时请链接。

安全与配置

• 禁止在 .qmd 中存放密钥、令牌或本地绝对路径。
• 外部数据/引用需注明来源，优先使用可下载且有版本的资源。
• 新增文件保持 ASCII 命名和编号风格（如 3.1.topic.qmd）。