Move project docs to docs/project-docs and update references

- Move AGENTS.md, CLEANUP_SUMMARY.md, DOCUMENTATION_GUIDE.md, IMPLEMENTATION_SUMMARY.md, QUICK_COMMANDS.md to docs/project-docs/ - Update AGENTS.md to include splicing module documentation - Update mkdocs.yml navigation to include project-docs section - Update .gitignore to track docs/ directory - Add docs/plans/ splicing design documents Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-18 17:56:03 +08:00
parent 68f171ad1d
commit a768d26e47
10 changed files with 555 additions and 7 deletions
--- a/docs/project-docs/AGENTS.md
+++ b/docs/project-docs/AGENTS.md
@@ -0,0 +1,275 @@
+# AGENTS.md
+
+本文件为 AI 编程助手（如 Claude、Copilot、Cursor 等）提供项目上下文和开发指南。
+
+## 项目概述
+
+**Macrolactone Fragmenter** 是一个专业的大环内酯（12-20元环）侧链断裂和分析工具，用于化学信息学研究。
+
+### 核心功能
+- 智能环原子编号（基于内酯结构）
+- 自动侧链断裂分析
+- 分子可视化（SVG/PNG）
+- 批量处理和数据导出
+
+## 技术栈
+
+| 组件 | 技术 |
+|------|------|
+| 语言 | Python 3.8+ |
+| 化学库 | RDKit |
+| 数据处理 | Pandas, NumPy |
+| 可视化 | Matplotlib, Seaborn |
+| 环境管理 | Pixi (推荐) / Conda |
+| 文档 | MkDocs + Material |
+| 测试 | Pytest |
+| 代码格式 | Black, Flake8 |
+
+## 项目结构
+
+```
+macro_split/
+├── src/                           # 核心源代码
+│   ├── __init__.py               # 包初始化
+│   ├── macrolactone_fragmenter.py # ⭐ 主入口类
+│   ├── macro_lactone_analyzer.py  # 环数分析器
+│   ├── ring_numbering.py          # 环编号系统
+│   ├── ring_visualization.py      # 可视化工具
+│   ├── fragment_cleaver.py        # 侧链断裂逻辑
+│   ├── fragment_dataclass.py      # 碎片数据类
+│   ├── visualizer.py              # 统计可视化
+│   └── splicing/                  # 分子拼接模块
+│       ├── engine.py              # 拼接引擎
+│       ├── scaffold_prep.py       # 骨架准备
+│       └── fragment_prep.py       # 片段激活
+├── notebooks/                     # Jupyter Notebook 示例
+├── scripts/                       # 批量处理脚本
+├── tests/                         # 单元测试
+├── docs/                          # 文档目录
+├── pyproject.toml                 # 项目配置
+├── pixi.toml                      # Pixi 环境配置
+└── mkdocs.yml                     # 文档配置
+```
+
+## 核心模块说明
+
+### MacrolactoneFragmenter (主入口)
+```python
+from src.macrolactone_fragmenter import MacrolactoneFragmenter
+
+fragmenter = MacrolactoneFragmenter(ring_size=16)
+result = fragmenter.process_molecule(smiles, parent_id="mol_001")
+```
+
+### MacroLactoneAnalyzer (环数分析)
+```python
+from src.macro_lactone_analyzer import MacroLactoneAnalyzer
+
+analyzer = MacroLactoneAnalyzer()
+info = analyzer.get_single_ring_info(smiles)
+```
+
+### Splicing 模块 (分子拼接)
+```python
+from src.splicing.scaffold_prep import prepare_tylosin_scaffold
+from src.splicing.fragment_prep import activate_fragment
+from src.splicing.engine import splice_molecule
+
+# 准备骨架（移除侧链，标记dummy原子）
+scaffold, dummy_map = prepare_tylosin_scaffold(smiles, positions=[3, 5, 9])
+
+# 激活片段（添加连接点）
+fragment = activate_fragment(fragment_smiles, strategy="smart")
+
+# 拼接分子
+new_mol = splice_molecule(scaffold, fragment, position=3)
+```
+
+### 数据类结构
+```python
+@dataclass
+class Fragment:
+    fragment_smiles: str      # 碎片 SMILES
+    parent_smiles: str        # 母分子 SMILES
+    cleavage_position: int    # 断裂位置 (1-N)
+    fragment_id: str          # 碎片 ID
+    parent_id: str            # 母分子 ID
+    atom_count: int           # 原子数
+    molecular_weight: float   # 分子量
+```
+
+## 开发命令
+
+### 环境设置
+```bash
+# 安装依赖
+pixi install
+
+# 激活环境
+pixi shell
+```
+
+### 代码质量
+```bash
+# 格式化代码
+pixi run black src/
+
+# 代码检查
+pixi run flake8 src/
+
+# 运行测试
+pixi run pytest
+
+# 测试覆盖率
+pixi run pytest --cov=src
+```
+
+### 文档
+```bash
+# 本地预览文档
+pixi run mkdocs serve
+
+# 构建文档
+pixi run mkdocs build
+```
+
+## 编码规范
+
+### Python 风格
+- 使用 Black 格式化，行宽 100 字符
+- 使用 Google 风格的 docstring
+- 类型注解：所有公共函数必须有类型提示
+- 命名：类用 PascalCase，函数/变量用 snake_case
+
+### Docstring 示例
+```python
+def process_molecule(self, smiles: str, parent_id: str = None) -> FragmentResult:
+    """
+    处理单个分子，进行侧链断裂分析。
+
+    Args:
+        smiles: 分子的 SMILES 字符串
+        parent_id: 可选的分子标识符
+
+    Returns:
+        FragmentResult 对象，包含所有碎片信息
+
+    Raises:
+        ValueError: 如果 SMILES 无效或不是目标环大小
+
+    Example:
+        >>> fragmenter = MacrolactoneFragmenter(ring_size=16)
+        >>> result = fragmenter.process_molecule("C1CC...")
+    """
+```
+
+### 导入顺序
+```python
+# 1. 标准库
+import json
+from pathlib import Path
+from typing import List, Dict, Optional
+
+# 2. 第三方库
+import pandas as pd
+import numpy as np
+from rdkit import Chem
+
+# 3. 本地模块
+from src.fragment_dataclass import Fragment
+from src.ring_numbering import RingNumbering
+```
+
+## 关键概念
+
+### 环编号系统
+- **位置 1**: 羰基碳（C=O 中的 C）
+- **位置 2**: 酯键氧（环上的 O）
+- **位置 3-N**: 按顺序编号环上剩余原子
+
+### 支持的环大小
+- 12元环 到 20元环
+- 默认处理 16元环
+
+### SMARTS 模式
+```python
+# 内酯键 SMARTS（16元环示例）
+LACTONE_SMARTS_16 = "[C;R16](=O)[O;R16]"
+```
+
+## 测试指南
+
+### 运行测试
+```bash
+# 全部测试
+pixi run pytest
+
+# 特定模块
+pixi run pytest tests/test_fragmenter.py
+
+# 详细输出
+pixi run pytest -v
+
+# 单个测试
+pixi run pytest tests/test_fragmenter.py::test_process_molecule
+```
+
+### 测试数据
+测试用的 SMILES 示例（16元环大环内酯）：
+```python
+TEST_SMILES = [
+    "O=C1CCCCCCCC(=O)OCC/C=C/C=C/1",  # 简单 16 元环
+    "CCC1OC(=O)C[C@H](O)C(C)[C@@H](O)...",  # 复杂结构
+]
+```
+
+## 常见任务
+
+### 添加新功能
+1. 在 `src/` 目录创建或修改模块
+2. 更新 `src/__init__.py` 导出新类/函数
+3. 编写单元测试
+4. 更新文档
+
+### 处理新的环大小
+```python
+# 在 MacrolactoneFragmenter 中指定环大小
+fragmenter = MacrolactoneFragmenter(ring_size=14)  # 14元环
+```
+
+### 批量处理
+```python
+results = fragmenter.process_csv(
+    "data/molecules.csv",
+    smiles_column="smiles",
+    id_column="unique_id",
+    max_rows=1000
+)
+df = fragmenter.batch_to_dataframe(results)
+```
+
+## 注意事项
+
+### RDKit 依赖
+- RDKit 必须通过 conda/pixi 安装，不支持 pip
+- 确保环境中有 RDKit：`python -c "from rdkit import Chem; print('OK')"`
+
+### 性能考虑
+- 批量处理大数据集时，使用 `process_csv` 方法
+- 处理速度约 ~100 分子/分钟
+- 大规模处理考虑使用 `scripts/batch_process_*.py`
+
+### 错误处理
+- 无效 SMILES 会抛出 `ValueError`
+- 非目标环大小会被跳过
+- 批量处理会记录失败的分子到日志
+
+## 相关资源
+
+- **文档**: `docs/` 目录或运行 `pixi run mkdocs serve`
+- **示例**: `notebooks/filter_molecules.ipynb`
+- **脚本**: `scripts/README.md`
+
+---
+
+*最后更新: 2025-01-23*
--- a/docs/project-docs/CLEANUP_SUMMARY.md
+++ b/docs/project-docs/CLEANUP_SUMMARY.md
@@ -0,0 +1,162 @@
+# 项目清理总结
+
+## ✅ 清理完成
+
+根目录已成功清理，现在更加整洁和专业！
+
+## 📁 当前根目录结构
+
+### 保留的 MD 文件（3 个）
+
+1. **README.md** (7.7 KB)
+   - 项目主文档
+   - 包含快速开始、安装、核心功能说明
+   - 已完全更新为现代化风格
+
+2. **DOCUMENTATION_GUIDE.md** (7.1 KB)
+   - 文档系统使用指南
+   - 如何编辑、构建、部署文档
+   - 非常实用的参考文档
+
+3. **QUICK_COMMANDS.md** (2.6 KB)
+   - 快速命令参考
+   - 常用命令速查表
+   - 便于日常使用
+
+### 归档的文件（14 个）
+
+已移动到 `archive/` 目录：
+
+- BATCH_PROCESSING_GUIDE.md
+- BRIDGE_RING_ANALYSIS.md
+- FINAL_REPORT.md
+- FIXES_SUMMARY.md
+- FRAGMENT_ANALYSIS_GUIDE.md
+- INDEX.md
+- LACTONE_DETECTION_FIX.md
+- PROJECT_COMPLETION_SUMMARY.md
+- PROJECT_SUMMARY.md
+- QUICK_GUIDE.md
+- QUICK_START.md
+- RERUN_GUIDE.md
+- SUMMARY.md
+- USAGE_EXAMPLES.md
+
+这些是开发过程中的临时文档，已归档备份但不再维护。
+
+## 📚 完整文档位置
+
+所有重要内容已整合到专业的文档系统中：
+
+### docs/ 目录结构
+
+```
+docs/
+├── index.md                     # 文档首页
+├── getting-started.md           # 快速开始（5分钟上手）
+├── installation.md              # 详细安装指南
+├── user-guide/                  # 用户指南
+│   ├── index.md
+│   ├── fragmenter-usage.md      # MacrolactoneFragmenter 使用
+│   ├── ring-numbering.md        # 环编号系统
+│   ├── visualization.md         # 可视化功能
+│   ├── batch-processing.md      # 批量处理
+│   └── data-export.md           # 数据导出
+├── tutorials/                   # 教程与示例
+│   ├── index.md
+│   ├── basic-tutorial.md
+│   ├── advanced-usage.md
+│   └── use-cases.md
+├── api/                         # API 参考（自动生成）
+│   ├── index.md
+│   ├── macrolactone-fragmenter.md
+│   ├── fragment-dataclass.md
+│   ├── ring-numbering.md
+│   ├── ring-visualization.md
+│   └── utilities.md
+├── development/                 # 开发者指南
+│   ├── index.md
+│   ├── contributing.md
+│   ├── project-structure.md
+│   └── testing.md
+└── about/                       # 关于
+    ├── index.md
+    ├── changelog.md
+    └── license.md
+```
+
+## 🎯 清理带来的好处
+
+1. **更专业**：根目录整洁，符合开源项目规范
+2. **易导航**：只保留最重要的 3 个文档
+3. **不丢失**：旧文档已归档到 `archive/` 目录
+4. **文档化**：完整的文档系统在 `docs/` 目录
+
+## 🚀 如何查看文档
+
+### 本地预览
+
+```bash
+# 启动文档服务器
+pixi run mkdocs serve
+
+# 访问 http://localhost:8000
+```
+
+### 构建静态网站
+
+```bash
+# 构建到 site/ 目录
+pixi run mkdocs build
+```
+
+### 部署到 GitHub Pages
+
+```bash
+# 自动构建并部署
+pixi run mkdocs gh-deploy
+```
+
+## 📋 快速参考
+
+| 文档 | 用途 | 位置 |
+|------|------|------|
+| 项目介绍 | 快速了解项目 | `README.md` |
+| 快速开始 | 5分钟上手 | `docs/getting-started.md` |
+| 安装指南 | 详细安装步骤 | `docs/installation.md` |
+| 用户指南 | 完整使用说明 | `docs/user-guide/` |
+| API 文档 | 代码参考 | `docs/api/` |
+| 教程示例 | 实际案例 | `docs/tutorials/` |
+| 开发指南 | 贡献代码 | `docs/development/` |
+| 文档系统 | 如何编辑文档 | `DOCUMENTATION_GUIDE.md` |
+| 快速命令 | 常用命令 | `QUICK_COMMANDS.md` |
+
+## 📊 统计
+
+### 清理前
+- 根目录 MD 文件：17 个
+- 总大小：~120 KB
+- 状态：混乱，难以导航
+
+### 清理后
+- 根目录 MD 文件：3 个（保留最重要的）
+- 归档文件：14 个（移动到 archive/）
+- 完整文档：30+ 个（在 docs/ 目录）
+- 状态：整洁，专业，易于使用
+
+## ✨ 总结
+
+根目录清理完成！现在项目结构更加清晰：
+
+- ✅ **根目录**：只有 3 个核心 MD 文件
+- ✅ **docs/**：完整的文档系统（30+ 文件）
+- ✅ **archive/**：历史文档归档
+- ✅ **src/**：核心代码
+- ✅ **notebooks/**：示例 Notebook
+
+项目现在完全准备好分享、发布和协作！🎉
+
+---
+
+*清理日期：2025-11-08*
+
--- a/docs/project-docs/DOCUMENTATION_GUIDE.md
+++ b/docs/project-docs/DOCUMENTATION_GUIDE.md
@@ -0,0 +1,377 @@
+# 文档系统使用指南
+
+本项目已完成完整的文档系统搭建，使用 **MkDocs + Material 主题 + mkdocstrings** 构建。
+
+## 📚 文档系统特性
+
+### ✅ 已完成功能
+
+1. **完整的文档结构**
+   - 首页和快速开始
+   - 详细的用户指南
+   - 教程与示例
+   - 自动生成的 API 文档
+   - 开发者指南
+
+2. **现代化主题**
+   - Material Design 风格
+   - 支持中文
+   - 深色/浅色模式切换
+   - 响应式设计
+
+3. **强大的功能**
+   - 自动从代码生成 API 文档
+   - 搜索功能
+   - 代码高亮
+   - 数学公式支持（MathJax）
+   - 导航标签
+
+4. **打包支持**
+   - `setup.py` 和 `pyproject.toml` 配置
+   - 支持 `pip install -e .` 开发模式
+   - 支持 `pip install .` 常规安装
+   - MIT License
+
+## 🚀 使用文档系统
+
+### 本地预览文档
+
+```bash
+# 启动开发服务器
+pixi run mkdocs serve
+
+# 访问 http://localhost:8000
+```
+
+### 构建静态网站
+
+```bash
+# 构建文档到 site/ 目录
+pixi run mkdocs build
+```
+
+### 部署到 GitHub Pages
+
+```bash
+# 自动构建并部署
+pixi run mkdocs gh-deploy
+```
+
+## 📁 文档结构
+
+```
+docs/
+├── index.md                     # 首页
+├── getting-started.md           # 快速开始
+├── installation.md              # 安装指南
+├── user-guide/                  # 用户指南
+│   ├── index.md
+│   ├── fragmenter-usage.md      # MacrolactoneFragmenter 使用
+│   ├── ring-numbering.md        # 环编号系统
+│   ├── visualization.md         # 可视化功能
+│   ├── batch-processing.md      # 批量处理
+│   └── data-export.md           # 数据导出
+├── tutorials/                   # 教程
+│   ├── index.md
+│   ├── basic-tutorial.md
+│   ├── advanced-usage.md
+│   └── use-cases.md
+├── api/                         # API 文档（自动生成）
+│   ├── index.md
+│   ├── macrolactone-fragmenter.md
+│   ├── fragment-dataclass.md
+│   ├── ring-numbering.md
+│   ├── ring-visualization.md
+│   └── utilities.md
+├── development/                 # 开发者指南
+│   ├── index.md
+│   ├── contributing.md
+│   ├── project-structure.md
+│   └── testing.md
+├── about/                       # 关于
+│   ├── index.md
+│   ├── changelog.md
+│   └── license.md
+├── stylesheets/                 # 自定义样式
+│   └── extra.css
+└── javascripts/                 # 自定义脚本
+    └── mathjax.js
+```
+
+## 📝 如何添加新文档
+
+### 1. 创建 Markdown 文件
+
+在 `docs/` 目录下创建新的 `.md` 文件：
+
+```bash
+# 例如：创建新的教程
+touch docs/tutorials/my-new-tutorial.md
+```
+
+### 2. 编辑文件内容
+
+使用 Markdown 格式编写内容：
+
+```markdown
+# 我的新教程
+
+## 简介
+
+这是一个新教程...
+
+## 示例代码
+
+\`\`\`python
+from src.macrolactone_fragmenter import MacrolactoneFragmenter
+
+fragmenter = MacrolactoneFragmenter(ring_size=16)
+\`\`\`
+```
+
+### 3. 添加到导航
+
+编辑 `mkdocs.yml`，在 `nav` 部分添加链接：
+
+```yaml
+nav:
+  - 教程与示例:
+    - tutorials/index.md
+    - 基础教程: tutorials/basic-tutorial.md
+    - 我的新教程: tutorials/my-new-tutorial.md  # 新添加
+```
+
+### 4. 预览更改
+
+```bash
+pixi run mkdocs serve
+```
+
+## 🎨 自定义文档
+
+### 修改主题颜色
+
+编辑 `mkdocs.yml` 中的 `theme.palette` 部分：
+
+```yaml
+theme:
+  palette:
+    primary: indigo  # 修改为其他颜色：red, blue, green 等
+    accent: indigo
+```
+
+### 添加自定义 CSS
+
+编辑 `docs/stylesheets/extra.css`：
+
+```css
+/* 自定义样式 */
+.my-custom-class {
+    color: red;
+}
+```
+
+### 修改导航结构
+
+编辑 `mkdocs.yml` 中的 `nav` 部分。
+
+## 📖 自动 API 文档
+
+本项目使用 `mkdocstrings` 自动从 Python 代码生成 API 文档。
+
+### 如何添加 API 文档
+
+在 `docs/api/` 目录创建新的 `.md` 文件，使用特殊语法：
+
+```markdown
+# 我的模块 API
+
+::: src.my_module.MyClass
+    options:
+      show_root_heading: true
+      show_source: true
+      heading_level: 2
+```
+
+这会自动提取 `src/my_module.py` 中 `MyClass` 的 docstring 并生成文档。
+
+### Docstring 格式
+
+使用 Google 风格的 docstring：
+
+```python
+def my_function(param1: str, param2: int) -> bool:
+    """
+    函数简短描述。
+    
+    详细描述...
+    
+    Args:
+        param1: 第一个参数说明
+        param2: 第二个参数说明
+    
+    Returns:
+        返回值说明
+    
+    Raises:
+        ValueError: 何时抛出此异常
+    
+    Example:
+        >>> my_function("test", 42)
+        True
+    """
+    pass
+```
+
+## 🔍 文档特性
+
+### 代码块
+
+支持语法高亮：
+
+\`\`\`python
+from src.macrolactone_fragmenter import MacrolactoneFragmenter
+fragmenter = MacrolactoneFragmenter(ring_size=16)
+\`\`\`
+
+### 提示框
+
+使用 admonition：
+
+```markdown
+!!! note "注意"
+    这是一个注意提示。
+
+!!! tip "提示"
+    这是一个小贴士。
+
+!!! warning "警告"
+    这是一个警告。
+```
+
+### 标签页
+
+使用 tabbed：
+
+```markdown
+=== "Python"
+    \`\`\`python
+    print("Hello")
+    \`\`\`
+
+=== "Bash"
+    \`\`\`bash
+    echo "Hello"
+    \`\`\`
+```
+
+### 数学公式
+
+使用 MathJax：
+
+```markdown
+行内公式：\\( E = mc^2 \\)
+
+块公式：
+\\[
+\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}
+\\]
+```
+
+## 📦 打包和发布
+
+### 本地安装
+
+```bash
+# 开发模式
+pip install -e .
+
+# 常规安装
+pip install .
+```
+
+### 构建分发包
+
+```bash
+# 安装构建工具
+pip install build
+
+# 构建
+python -m build
+
+# 会生成：
+# dist/macrolactone_fragmenter-1.2.0.tar.gz
+# dist/macrolactone_fragmenter-1.2.0-py3-none-any.whl
+```
+
+### 发布到 PyPI
+
+```bash
+# 安装 twine
+pip install twine
+
+# 上传到 PyPI
+twine upload dist/*
+
+# 或先上传到 TestPyPI 测试
+twine upload --repository testpypi dist/*
+```
+
+## 🚀 持续集成（CI）
+
+可以配置 GitHub Actions 自动构建和部署文档。
+
+创建 `.github/workflows/docs.yml`：
+
+```yaml
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material mkdocstrings[python]
+      - run: mkdocs gh-deploy --force
+```
+
+## ℹ️ 注意事项
+
+1. **RDKit 依赖**：PyPI 安装后仍需通过 conda 安装 RDKit
+2. **文档更新**：修改代码后记得更新 docstring
+3. **锚点链接**：使用英文标题更容易创建稳定的锚点
+4. **图片路径**：放在 `docs/assets/images/` 目录
+
+## 📊 项目状态
+
+✅ 所有任务已完成：
+
+1. ✅ 安装 MkDocs、Material 主题、mkdocstrings
+2. ✅ 创建完整的文档结构
+3. ✅ 自动生成 API 文档
+4. ✅ 创建 setup.py 和 pyproject.toml
+5. ✅ 支持 pip install 安装
+6. ✅ 更新 README.md
+7. ✅ 测试文档构建
+
+## 🎉 完成！
+
+文档系统已完全搭建完成，您可以：
+
+1. 运行 `pixi run mkdocs serve` 查看文档
+2. 使用 `pip install -e .` 安装项目
+3. 继续完善教程和示例内容
+4. 准备发布到 PyPI
+
+---
+
+**祝您使用愉快！** 🚀
+
--- a/docs/project-docs/IMPLEMENTATION_SUMMARY.md
+++ b/docs/project-docs/IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,215 @@
+# MacroLactoneAnalyzer 封装实现总结
+
+## 📋 完成的工作
+
+### 1. 核心功能封装
+
+✅ **创建了 `src/macro_lactone_analyzer.py`**
+- 封装了环数识别、验证和分类功能
+- 参考用户提供的 `macro_lactone_analyzer.py` 设计
+- 支持12-20元环大环内酯分析
+- 包含静态方法和实例方法
+- 支持单分子和批量分析
+- 集成动态SMARTS匹配功能
+
+### 2. API文档
+
+✅ **创建了完整的API文档** (`docs/api/macro-lactone-analyzer.md`)
+- 详细的方法说明
+- 丰富的使用示例
+- 错误处理指南
+- 性能优化建议
+- 与其他模块的集成方法
+- 常见问题解答
+
+### 3. 教程文档
+
+✅ **创建了详细教程** (`docs/tutorials/using-macro-lactone-analyzer.md`)
+- 快速开始指南
+- 实际应用案例
+- 高级用法说明
+- 性能优化技巧
+- 在Notebook中的完整工作流
+
+### 4. 更新了 mkdocs.yml
+
+✅ **配置了文档导航**
+- 在API参考部分添加了MacroLactoneAnalyzer
+- 在教程部分添加了环数识别教程
+- 更新了文档树结构
+
+### 5. 更新了 Notebook
+
+✅ **更新了 `analyze_ring12_20_molecules_CLEAN.ipynb`**
+- 使用新封装的MacroLactoneAnalyzer类
+- 替换了原有的内联函数
+- 简化了代码结构
+- 提高了可维护性
+
+### 6. 更新了 __init__.py
+
+✅ **更新了 `src/__init__.py`**
+- 导出了MacroLactoneAnalyzer类
+- 更新了版本号到2.0.0
+- 完善了__all__列表
+
+## 🎯 新封装的 MacroLactoneAnalyzer 功能
+
+### 核心方法
+
+#### 静态方法
+- `detect_ring_sizes(mol)`: 识别环大小
+- `is_valid_macrolactone(mol, size)`: 验证大环内酯
+- `analyze_smiles(smiles)`: 单分子分析
+- `dynamic_smarts_match(smiles, ring_size)`: 动态SMARTS匹配
+
+#### 实例方法
+- `get_single_ring_info(smiles)`: 单分子详细信息
+- `analyze_list(smiles_list)`: 批量分析
+- `classify_molecules(df)`: DataFrame分类
+- `add_smiles(smiles)`: 添加SMILES
+- `calculate_molecular_properties(smiles)`: 计算分子性质
+
+### 特性
+
+1. **高复用性**: 独立的模块，可被其他代码调用
+2. **类型安全**: 完整的类型提示
+3. **错误处理**: 详细的异常处理
+4. **灵活配置**: 支持自定义酯键SMARTS模式
+5. **性能优化**: 支持批量处理和并行分析
+6. **详细日志**: 进度显示和统计信息
+
+## 📚 文档访问方式
+
+### 本地文档服务器
+
+```bash
+# 启动文档服务器
+cd /home/zly/project/macro_split
+pixi run mkdocs serve
+
+# 访问地址
+http://localhost:8000
+```
+
+### 文档结构
+
+```
+docs/
+├── api/
+│   ├── macro-lactone-analyzer.md  # API参考
+│   ├── index.md
+│   └── ...
+├── tutorials/
+│   ├── using-macro-lactone-analyzer.md  # 环数识别教程
+│   ├── index.md
+│   └── ...
+├── user-guide/
+├── getting-started.md
+└── ...
+```
+
+## 🔧 在代码中的使用
+
+### 基本用法
+
+```python
+from src.macro_lactone_analyzer import MacroLactoneAnalyzer
+
+# 创建分析器实例
+analyzer = MacroLactoneAnalyzer()
+
+# 单分子分析
+result = analyzer.get_single_ring_info("O=C1CCCCCCCC(=O)OCC/C=C/C=C/1")
+print(result)
+# 输出: {
+#   'ring_sizes': [16],
+#   'valid_sizes': [16],
+#   'is_macrolactone': True,
+#   'has_ester': True,
+#   'is_bridge': False
+# }
+```
+
+### 批量分析
+
+```python
+# 批量分析
+smiles_list = ["SMILES1", "SMILES2", "SMILES3"]
+stats = analyzer.analyze_list(smiles_list)
+print(f"大环内酯数: {stats['macrolactones']}")
+```
+
+### DataFrame分类
+
+```python
+import pandas as pd
+
+df = pd.read_csv('molecules.csv')
+ring_dfs, bridge_df = analyzer.classify_molecules(df, 'smiles', 'ID')
+
+for size, df_size in ring_dfs.items():
+    if not df_size.empty:
+        print(f"{size}元环: {len(df_size)} 个分子")
+```
+
+## 🎓 用户可参考的资料
+
+1. **API参考**: 完整的方法文档和示例
+2. **教程**: 详细的使用指南和最佳实践
+3. **代码示例**: 在notebook中的实际应用
+4. **测试用例**: 在 `src/macro_lactone_analyzer.py` 的 `__main__` 部分
+
+## 🔄 与原有代码的对比
+
+### 原有方式
+```python
+# 在notebook中定义函数
+def detect_ring_sizes(mol):
+    ...
+
+def is_valid_macrolactone(mol, size):
+    ...
+
+def classify_molecules_by_ring_size(df):
+    ...
+```
+
+### 新方式
+```python
+# 导入封装好的类
+from src.macro_lactone_analyzer import MacroLactoneAnalyzer
+
+# 创建实例并使用
+analyzer = MacroLactoneAnalyzer()
+ring_dfs, bridge_df = analyzer.classify_molecules(df, 'smiles', 'ID')
+```
+
+## ✨ 优势
+
+1. **代码复用**: 可以在多个notebook和脚本中使用
+2. **易于维护**: 集中管理，修改只需改一个地方
+3. **文档完善**: 有完整的API文档和教程
+4. **类型安全**: 完整的类型提示
+5. **测试覆盖**: 包含单元测试（待补充）
+6. **版本控制**: 清晰的版本记录
+
+## 📈 后续建议
+
+1. **添加单元测试**: 在 `tests/` 目录下添加测试用例
+2. **性能优化**: 对大数据集进行性能测试和优化
+3. **并行处理**: 完善多进程/多线程支持
+4. **缓存机制**: 添加结果缓存，避免重复计算
+5. **可视化**: 集成图表生成功能
+
+## 🎉 总结
+
+通过封装 `MacroLactoneAnalyzer` 类，我们实现了：
+
+- ✅ 环数识别功能的模块化
+- ✅ 完整的文档和教程
+- ✅ 易于使用的API
+- ✅ 高度可复用的代码
+- ✅ 详细的示例和最佳实践
+
+用户现在可以通过运行 `pixi run mkdocs serve` 查看详细的文档，并通过简单的导入语句使用强大的环数识别功能。
--- a/docs/project-docs/QUICK_COMMANDS.md
+++ b/docs/project-docs/QUICK_COMMANDS.md
@@ -0,0 +1,149 @@
+# 快速命令参考
+
+## 📚 查看文档
+
+```bash
+# 启动文档服务器（推荐）
+pixi run mkdocs serve
+
+# 访问：http://localhost:8000
+
+# 构建静态文档
+pixi run mkdocs build
+
+# 部署到 GitHub Pages
+pixi run mkdocs gh-deploy
+```
+
+## 📦 安装项目
+
+```bash
+# 方式 1: 使用 Pixi（推荐）
+pixi install
+pixi shell
+
+# 方式 2: 使用 Pip（需要先安装 RDKit）
+conda install -c conda-forge rdkit
+pip install -e .  # 开发模式
+
+# 方式 3: 常规安装
+pip install .
+```
+
+## 🧪 测试安装
+
+```python
+# 测试导入
+from src.macrolactone_fragmenter import MacrolactoneFragmenter
+print("✓ 安装成功！")
+
+# 快速测试
+fragmenter = MacrolactoneFragmenter(ring_size=16)
+print(f"✓ 初始化成功！ring_size={fragmenter.ring_size}")
+```
+
+## 📓 运行示例
+
+```bash
+# Jupyter Notebook
+pixi run jupyter notebook notebooks/filter_molecules.ipynb
+
+# 或启动 Jupyter Lab
+pixi run jupyter lab
+```
+
+## 🔍 项目结构
+
+```bash
+# 查看文档文件
+find docs -type f -name "*.md" | sort
+
+# 查看源代码
+ls -la src/
+
+# 查看配置文件
+cat pyproject.toml
+cat mkdocs.yml
+```
+
+## 📝 文档编辑
+
+```bash
+# 编辑文档
+vim docs/user-guide/fragmenter-usage.md
+
+# 实时预览
+pixi run mkdocs serve
+
+# 构建验证
+pixi run mkdocs build
+```
+
+## 🚀 发布准备
+
+```bash
+# 构建分发包
+python -m build
+
+# 检查包
+twine check dist/*
+
+# 上传到 TestPyPI（测试）
+twine upload --repository testpypi dist/*
+
+# 上传到 PyPI（正式发布）
+twine upload dist/*
+```
+
+## 🛠️ 开发工具
+
+```bash
+# 格式化代码
+pixi run black src/
+
+# 检查代码质量
+pixi run flake8 src/
+
+# 运行测试
+pixi run pytest
+
+# 测试覆盖率
+pixi run pytest --cov=src
+```
+
+## 📊 项目信息
+
+```bash
+# 查看 Pixi 环境
+pixi list
+
+# 查看项目信息
+cat pyproject.toml | grep -A 10 '\[project\]'
+
+# 查看版本
+cat pyproject.toml | grep version
+```
+
+## 🔗 重要文件
+
+| 文件 | 说明 |
+|------|------|
+| `README.md` | 项目主文档 |
+| `DOCUMENTATION_GUIDE.md` | 文档系统使用指南 |
+| `PROJECT_COMPLETION_SUMMARY.md` | 项目完成总结 |
+| `QUICK_COMMANDS.md` | 本文件 |
+| `pyproject.toml` | Python 项目配置 |
+| `setup.py` | 打包脚本 |
+| `mkdocs.yml` | 文档配置 |
+| `pixi.toml` | Pixi 环境配置 |
+
+## 💡 常用链接
+
+- **本地文档**: http://localhost:8000 (运行 `pixi run mkdocs serve`)
+- **GitHub**: https://github.com/yourusername/macro_split
+- **PyPI**: https://pypi.org/project/macrolactone-fragmenter/
+
+---
+
+**需要帮助？** 查看 `DOCUMENTATION_GUIDE.md` 或运行 `pixi run mkdocs serve`
+