Development · 开发指南

# 使用提供的脚本快速设置（推荐）
./scripts/dev/setup.sh

# 验证环境设置
uv --version
python --version

# 安装 uv（如果未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone <repository-url>
cd negentropy-perceives

# 同步依赖（项目运行时固定 Python 3.13）
uv sync --python 3.13

# 安装开发依赖
uv sync --python 3.13 --group dev

# 启用非 MLX 的 PDF 引擎集合（Docling / MinerU / Marker / PyMuPDF）
uv sync --python 3.13 --extra all-engines

# 或按需单独启用
uv sync --python 3.13 --extra mineru
uv sync --python 3.13 --extra marker

# Apple Silicon 上启用 Docling code/formula 的 Granite Docling + MLX 路径
# 注意：docling-mlx 与 marker/all-engines 互斥（transformers 主版本冲突）
uv sync --python 3.13 --extra docling-mlx

# 初始化用户配置（首次运行时自动生成，也可手动执行）
uv run negentropy-perceives --init-config

# 安装 Playwright 浏览器依赖
uv run playwright install chromium

# 预下载 Docling + Marker + MinerU 所需的全部模型到本地缓存（幂等）
uv run --python 3.13 perceives prefetch-models

# 仅预热部分引擎
uv run --python 3.13 perceives prefetch-models --engines docling,marker

# 指定 HuggingFace 缓存目录（CI / 共享缓存场景）
uv run --python 3.13 perceives prefetch-models --hf-home /shared/hf-cache

negentropy-perceives/
├── src/negentropy/perceives/                    # 核心包
│   ├── __init__.py              # 版本信息（动态读取 pyproject.toml）
│   ├── __main__.py              # python -m 入口
│   ├── _logging.py              # 日志配置
│   ├── config.py                # 配置系统 + 配置验证（NegentropyPerceivesSettings, ConfigValidator）
│   ├── schemas.py               # 响应模型 + 数据传输对象（Pydantic BaseModel）
│   ├── sdk.py                   # Python SDK 封装（NegentropyPerceivesClient）
│   │
│   ├── apps/                    # 应用入口子包
│   │   └── app.py               # MCP 服务器入口（main()）
│   │
│   ├── scraping/                # 网页抓取引擎子包
│   │   ├── engine.py            # 核心抓取引擎（WebScraper, HttpScraper, SeleniumScraper）
│   │   ├── anti_detection.py    # 反检测隐身抓取（AntiDetectionScraper）
│   │   ├── browser.py           # 浏览器工具（selenium_session, playwright_session, stealth_*, chrome_options）
│   │   ├── form_handler.py      # 表单处理（FormHandler）
│   │   └── content_extraction/  # 内容提取（selectors.py, pages.py）
│   │
│   ├── pdf/                     # PDF 处理引擎子包
│   │   ├── processor.py         # 核心 PDF 处理器（多引擎调度）
│   │   ├── enhanced.py          # 增强 PDF 处理器（PyMuPDF）
│   │   ├── docling_engine.py    # Docling 引擎（GPU 加速）
│   │   ├── marker_engine.py     # Marker 引擎（Nougat 模型，学术文档）
│   │   ├── mineru_engine.py     # MineRU 引擎（深度学习文档结构分析）
│   │   ├── llm_orchestrator.py  # LLM 编排器（smart 模式多引擎融合）
│   │   ├── llm_client.py        # LLM 客户端（LiteLLM）
│   │   ├── math_formula.py      # 数学公式处理
│   │   ├── device_config.py     # 设备配置（GPU/CPU 调度）
│   │   ├── hardware.py          # 硬件检测（MPS/CUDA/XPU）
│   │   ├── figure_text_filter.py # 图文过滤
│   │   ├── _imports.py          # 内部导入管理
│   │   └── _sources.py          # 内部数据源管理
│   │
│   ├── markdown/                # Markdown 转换子包
│   │   ├── converter.py         # Markdown 转换器核心
│   │   ├── formatter.py         # 格式化器（数学公式保护）
│   │   ├── html_preprocessor.py # HTML 预处理
│   │   ├── algorithm_detector.py # 算法检测
│   │   ├── formula_placeholder_resolver.py # 公式占位符解析
│   │   ├── image_embedder.py    # 图片嵌入
│   │   └── image_ref_normalizer.py # 图片引用规范化
│   │
│   ├── pipeline/                # Pipeline 编排框架（详见 Pipeline 编排框架 章节）
│   │   ├── base.py              # Stage / StageResult / StageTool 基类
│   │   ├── competitive.py       # CompetitiveStage（多工具并行竞争）
│   │   ├── orchestrator.py      # PipelineOrchestrator（Stage 串联编排）
│   │   ├── scheduler.py         # StageScheduler（降级 / 竞争模式调度）
│   │   ├── registry.py          # 工具注册与发现（register_tool / get_tool）
│   │   ├── models.py            # Pipeline 数据模型（PDF / WebPage 通用）
│   │   ├── convenience.py       # 高级便捷 API（run_pdf_pipeline / run_webpage_pipeline）
│   │   ├── pdf_stages/          # PDF Pipeline Stages（10 个 Stage）
│   │   │   ├── preprocessing.py   # 预处理（PDF 加载 + 文档特征检测）
│   │   │   ├── layout_analysis.py # 版面分析与阅读顺序
│   │   │   ├── text_extraction.py # 文本提取
│   │   │   ├── table_extraction.py # 表格提取
│   │   │   ├── formula_extraction.py # 数学公式提取
│   │   │   ├── image_extraction.py  # 图片提取
│   │   │   ├── code_detection.py    # 代码块检测
│   │   │   ├── asset_bundling.py    # 资源打包
│   │   │   ├── assembly.py          # 内容组装（Markdown 输出）
│   │   │   └── quick_scan.py        # 快速扫描
│   │   └── webpage_stages/      # WebPage Pipeline Stages（9 个 Stage）
│   │       ├── page_fetching.py          # 页面获取
│   │       ├── anti_detection.py         # 反检测
│   │       ├── compliance_check.py       # 合规检查（robots.txt）
│   │       ├── html_sanitization.py      # HTML 清洗
│   │       ├── main_content_extraction.py # 主内容提取
│   │       ├── markdown_conversion.py    # Markdown 转换
│   │       ├── markdown_formatting.py    # Markdown 格式化
│   │       ├── rich_elements.py          # 富元素处理（图片、表格等）
│   │       └── asset_bundling.py         # 资源打包
│   │
│   ├── tools/                   # MCP 工具注册子包（3 模块 · 6 个 tool）
│   │   ├── __init__.py          # 包初始化 + 触发注册
│   │   ├── _registry.py         # FastMCP app 实例 + 共享服务 + 辅助函数导出
│   │   ├── _observability.py    # 可观测性辅助（elapsed_ms）
│   │   ├── _support.py          # 共享类型（ScrapeMethod, PDFMethod, PDFOutputFormat）+ 校验函数
│   │   ├── extraction.py        # 数据提取工具（discover_links, inspect_page）
│   │   ├── markdown.py          # Markdown 转换工具（parse_webpage_to_markdown, parse_webpages_to_markdown）
│   │   └── pdf.py               # PDF 处理工具（parse_pdf_to_markdown, parse_pdfs_to_markdown）
│   │
│   ├── infra/                   # 基础设施层
│   │   ├── parsing.py           # 解析工具（TextCleaner, URLValidator, extract_*）
│   │   └── resilience.py        # 弹性策略（RateLimiter, RetryManager）
│   │
│   └── examples/                # 示例与模板（随包分发）
│       ├── configs/
│       │   └── extraction_configs.py  # 领域提取配置模板
│       ├── mcp/
│       │   └── basic_usage.py         # MCP 工具调用示例
│       └── sdk/
│           └── python_sdk_usage.py    # Python SDK 集成示例
│
├── tests/                        # 测试套件（详见 [测试](#测试) 章节）
│   ├── conftest.py               # 全局共享 Fixture
│   ├── unit/                     # 单元测试（40+ files）
│   ├── integration/              # 集成测试（12 files + tooling.py helper）
│   │   └── tooling.py            # 集成测试共享工具（get_tool_map, build_pdf_tool_kwargs）
│   └── reports/                  # 测试报告（.gitignore，运行时生成）
│
├── scripts/                      # 仓库维护脚本
│   ├── dev/
│   │   └── setup.sh              # 环境初始化
│   └── test/
│       └── run-tests.sh          # 测试执行（支持 unit/integration/full/coverage 等模式）
│
├── docs/                         # 项目文档
├── .github/workflows/            # CI/CD 配置（ci/release/dependencies/review）
├── .github/actions/              # 可复用 Composite Action
│   └── setup-python-uv/action.yml
└── pyproject.toml                # 项目配置

tests/
├── conftest.py                              # 全局共享 Fixture
├── unit/                                    # 单元测试 (40+ files)
│   ├── conftest.py                          # 120s 超时保护（pytest-timeout signal 模式）
│   ├── doc_contracts.py                     # 文档契约验证
│   ├── test_advanced_features.py            # 高级功能向后兼容
│   ├── test_algorithm_detector.py           # 算法检测
│   ├── test_anti_detection.py               # 反检测隐身爬取
│   ├── test_app_entrypoint.py               # 应用入口
│   ├── test_browser_utils.py                # 浏览器工具
│   ├── test_config.py                       # 配置系统
│   ├── test_content_extraction.py           # 内容提取
│   ├── test_dependency_integrity.py         # 跨模块依赖完整性
│   ├── test_device_config.py                # GPU 设备配置
│   ├── test_docling_engine.py               # Docling 引擎
│   ├── test_docs_configuration.py           # 文档一致性（配置相关）
│   ├── test_docs_user_guide.py              # 文档一致性（用户指南相关）
│   ├── test_enhanced_pdf_processor.py       # PDF 增强处理
│   ├── test_examples.py                     # 示例代码验证
│   ├── test_figure_text_filter.py           # 图文过滤
│   ├── test_form_handler.py                 # 表单交互
│   ├── test_formatter_math_protection.py    # 格式化数学公式保护
│   ├── test_formula_placeholder_resolver.py # 公式占位符解析
│   ├── test_github_workflows.py             # CI/CD 工作流验证
│   ├── test_html_math_preservation.py       # HTML 数学公式保留
│   ├── test_image_ref_normalizer.py         # 图片引用规范化
│   ├── test_infra_package.py                # 基础设施包
│   ├── test_llm_client.py                   # LLM 客户端
│   ├── test_llm_orchestrator.py             # LLM 编排器
│   ├── test_logging_config.py               # 日志配置
│   ├── test_markdown_converter.py           # Markdown 转换
│   ├── test_marker_engine.py                # Marker 引擎
│   ├── test_math_formula.py                 # 数学公式处理
│   ├── test_mcp_tools_unit.py               # MCP 工具单元测试
│   ├── test_mineru_engine.py                # MineRU 引擎
│   ├── test_paragraph_separation.py         # 段落分隔
│   ├── test_pdf_processor.py                # PDF 基础处理
│   ├── test_pdf_table_extraction.py         # PDF 表格提取
│   ├── test_pyproject_metadata.py           # pyproject.toml 元数据验证
│   ├── test_schemas.py                      # 响应模型
│   ├── test_scraper.py                      # 网页抓取引擎
│   ├── test_scraping_package.py             # 抓取包完整性
│   ├── test_scripts.py                      # 脚本文件验证
│   ├── test_sdk.py                          # Python SDK
│   ├── test_tool_registry.py                # 工具注册表
│   └── test_utils.py                        # 工具类
├── integration/                             # 集成测试 (12 files)
│   ├── conftest.py                          # 集成测试专用 Fixture（含 GPU 感知）
│   ├── tooling.py                           # 集成测试共享工具（get_tool_map, build_pdf_tool_kwargs）
│   ├── test_comprehensive_integration.py    # 综合集成 + 性能负载
│   ├── test_cross_tool_integration.py       # 跨工具协作
│   ├── test_docling_pdf_integration.py      # Docling PDF GPU 加速集成
│   ├── test_e2e_data_validation.py          # 数据有效性验证
│   ├── test_e2e_document_pipeline.py        # 文档处理管道
│   ├── test_e2e_error_resilience.py         # 错误恢复能力
│   ├── test_e2e_performance.py              # 性能基准
│   ├── test_langchain_blog_conversion.py    # Langchain 博客转换
│   ├── test_llm_pdf_integration.py          # LLM 编排 PDF 集成
│   ├── test_mcp_tools.py                    # MCP 工具端到端
│   ├── test_pdf_formula_regression.py       # PDF 公式回归测试
│   └── test_pdf_integration.py              # PDF 处理集成

./scripts/test/run-tests.sh              # 完整测试套件（默认）
./scripts/test/run-tests.sh unit         # 单元测试
./scripts/test/run-tests.sh integration  # 集成测试
./scripts/test/run-tests.sh quick        # 快速测试（排除慢速测试）
./scripts/test/run-tests.sh performance  # 性能测试
./scripts/test/run-tests.sh coverage     # 仅生成覆盖率报告
./scripts/test/run-tests.sh clean        # 清理测试结果

# 按范围
uv run pytest                                    # 所有测试
uv run pytest tests/unit/                        # 单元测试目录
uv run pytest tests/integration/                 # 集成测试目录
uv run pytest tests/unit/test_config.py          # 特定文件

# 按粒度
uv run pytest tests/unit/test_config.py::TestNegentropyPerceivesSettings           # 测试类
uv run pytest tests/unit/test_config.py::TestNegentropyPerceivesSettings::test_xxx # 测试方法

# 执行控制
uv run pytest -x                     # 首次失败即停
uv run pytest --lf                   # 只跑上次失败的
uv run pytest --ff                   # 优先跑失败的
uv run pytest -n auto                # 自动并行（需 pytest-xdist）
uv run pytest --durations=10         # 最慢 10 个测试
uv run pytest -m "not slow"          # 排除慢速测试

# GPU 加速测试：-m requires_gpu
# LLM 编排测试：-m requires_llm
# 列出不执行：--co -m requires_gpu

tools/_registry.py          定义 FastMCP app 实例 + 共享服务
       ↓                       （web_scraper, markdown_converter, create_pdf_processor 工厂）
tools/_support.py           共享类型别名（ScrapeMethod, PDFMethod, PDFOutputFormat）+ 校验函数
tools/_observability.py     导出 elapsed_ms 计时工具
       ↓
tools/extraction.py         用 @app.tool() 注册 2 个工具（discover_links, inspect_page）
tools/markdown.py           用 @app.tool() 注册 2 个工具（parse_webpage_to_markdown, parse_webpages_to_markdown）
tools/pdf.py                用 @app.tool() 注册 2 个工具（parse_pdf_to_markdown, parse_pdfs_to_markdown）
       ↓                       （6 个 tool 分布于 3 个模块）
tools/__init__.py           导入各子模块 + _registry 公共 API，触发装饰器注册
       ↓
apps/app.py                 应用入口 main()，从 tools 导入 app 实例

class PDFResponse(BaseModel):
    """Response model for PDF conversion."""
    success: bool = Field(..., description="操作是否成功")
    pdf_source: str = Field(..., description="PDF 源路径或 URL")
    method: str = Field(..., description="使用的处理方法")
    output_format: str = Field(default="markdown", description="输出格式")
    content: Optional[str] = Field(default=None, description="转换后的内容")
    # ... 其他字段

from ..schemas import PDFResponse
from ._registry import app, create_pdf_processor, PDFMethod, validate_page_range

@app.tool()
async def parse_pdf_to_markdown(
    pdf_source: Annotated[str, Field(..., description="PDF 源路径或 URL")],
    method: Annotated[PDFMethod, Field(default="auto", description="处理方法")],
    # ... 更多参数
) -> PDFResponse:
    """Convert a PDF document to Markdown format."""
    # 参数校验
    page_range_tuple, page_range_error = validate_page_range(page_range)
    if page_range_error:
        return PDFResponse(success=False, ..., error=page_range_error)

    # Pipeline 路径（auto 模式优先尝试）
    if method == "auto":
        try:
            from ..pipeline import run_pdf_pipeline
            result = await run_pdf_pipeline(source=pdf_source, ...)
            if result.success:
                return PDFResponse(success=True, ..., content=result.markdown)
        except Exception:
            pass  # 降级到传统路径

    # 传统路径
    pdf_processor = create_pdf_processor()
    result = await pdf_processor.process_pdf(pdf_source=pdf_source, method=method, ...)
    return PDFResponse(success=result.get("success", False), ...)

from . import pdf  # noqa: F401  # 触发 @app.tool() 注册

@app.tool()
async def parse_webpage_to_markdown(
    url: Annotated[str, Field(..., description="目标网页URL，必须包含协议前缀")],
    method: Annotated[ScrapeMethod, Field(default="auto", description="抓取方法")],
    extract_main_content: Annotated[bool, Field(default=True, description="是否仅提取主要内容")],
    # ...
) -> MarkdownResponse:

# 文件：test_<模块名>.py，镜像 src/negentropy/perceives/ 下的源码模块
# 类：Test<功能区域>
# 方法：test_<行为>_<条件>

class TestWebScraper:
    def test_scrape_url_success(self): ...
    def test_scrape_url_invalid_url_raises(self): ...

def test_extract_data():
    # Arrange
    config = NegentropyPerceivesSettings(enable_javascript=False)
    # Act
    result = negentropy.perceives.process(config)
    # Assert
    assert result["success"] is True

# 1. 更新版本号（pyproject.toml 中的 version 字段）
# 2. 更新 CHANGELOG.md
# 3. 创建 git tag 并推送
git tag v<VERSION>
git push origin v<VERSION>
# → 自动触发 release.yml Phase 1:
#   CI 验证 → 构建 → Pre-Release GitHub (prerelease=true) → TestPyPI 发布
# → 暂停在人工审批门禁

# 4. 在 TestPyPI 上验证预发布版本
pip install --index-url https://test.pypi.org/simple/ negentropy-perceives==<VERSION>

# 5. 运行冒烟测试确认功能正常
uv run negentropy-perceives --help

# 6. 在 GitHub Releases 页面检查 Pre-Release 内容和 release notes

# 7. 在 GitHub Actions 页面审批 production 环境
#    Settings → Environments → production → Approve

# 审批通过后自动执行 release.yml Phase 2:
#   Promote 正式 Release (prerelease=false) → PyPI 发布 (OIDC) → 更新 CHANGELOG

uv run python -c "from negentropy.perceives import __version__; print(__version__)"

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class NegentropyPerceivesService:
    async def process_content(self, url: str):
        logger.info(f"Starting extraction for URL: {url}")
        # ...
        logger.info("Extraction completed successfully")

uv sync --group dev                                    # 安装开发依赖
export NEGENTROPY_PERCEIVES_ENABLE_JAVASCRIPT=false           # 禁用 JS 渲染
export NEGENTROPY_PERCEIVES_CONCURRENT_REQUESTS=1             # 单请求模式
export NEGENTROPY_PERCEIVES_BROWSER_TIMEOUT=10                # 浏览器超时

uv run pytest -v -s                  # 详细输出 + 显示 print
uv run pytest --tb=long              # 完整错误栈
uv run pytest --pdb                  # 失败时进入 PDB 调试器
uv run pytest --durations=0          # 所有测试执行时间