SureshBabuoo7/aifme-scout

# AIFME Scout OSS AIFME Scout OSS 是进入 AIFME 营销情报能力的免费、开源、可自托管入口。只需指向一个 URL，它就会返回一个结构化且带有证据链接的快照，涵盖该企业的身份、其网站的构建方式、其对外传达的信息，以及与指定竞争对手的对比情况——所有这些都以 CLI、REST API 和专为人类与 AI agent 设计且带版本控制的 JSON schema 形式呈现。 ## 功能 - **网站扫描** — 安全地获取和分析网站，支持配置超时、抓取延迟和 SSRF 保护。 - **HTML 解析** — 将原始 HTML 转换为确定性、可导航的 DOM 树，并对格式错误的标记进行宽松恢复。 - **SEO 提取** — 提取页面上的 SEO 信号，包括标题、meta 描述、canonical URL、标题层级、Open Graph、Twitter Cards 和结构化数据。 - **Metadata 提取** — 提取结构化的 head metadata，包括 favicons、语言、manifest 链接、RSS/Atom feeds 和验证标签。 - **技术检测** — 基于规则和置信度识别框架、CMS 平台、Web 服务器、分析工具和 CSS 框架。 - **内容提取** — 提取结构化的正文内容，包括标题、段落、列表、表格、图像、链接、按钮、表单、面包屑和页脚。 - **社交媒体发现** — 从解析后的页面链接中发现关联的社交媒体资料，支持平台检测和来源追踪。 - **竞争对手发现** — 从显式声明和用户提供的列表中构建竞争对手比较集。 - **证据收集** — 将所有提取器的输出标准化为具有确定性 ID 的通用、可追踪证据模型。 - **Schema 验证** — 在导出前根据带版本控制的 JSON Schema 验证每个扫描结果。 - **JSON 导出** — 格式优美、符合 schema 规范且具有稳定键顺序的 JSON 输出。 - **Markdown 导出** — 确定性的 Markdown 报告，保留所有章节标题和证据参考。 - **CLI** — 功能齐全的命令行界面，支持配置优先级、退出代码和输出控制。 - **REST API** — 基于 FastAPI 的 HTTP 接口，带有自动生成的 OpenAPI/Swagger 文档。 ## Scout OSS 存在的意义 Scout OSS 仅执行 AIFME 模型中的 **Understand** 步骤，不包含任何超出此范围的功能。它没有持久化存储、推理或决策逻辑，也不能代替目标执行操作。它是一个独立的提取工具包，可为您提供网站公开身份的结构化、带有证据链接的快照——随时可供人类或 AI agent 消费。 商业版 AIFME 平台包含 Remember、Reason、Decide、Execute 和 Measure 功能。Scout OSS 是开源基础：这是收集和理解 Web 情报的免费、可自托管方式。 ## 安装说明 ### 前置条件 - Python 3.11 或更高版本 - pip 或兼容的包管理器 ### 从 PyPI 安装 ``` pip install aifme-scout ``` ### 可编辑安装（开发） ``` git clone https://github.com/aifme/aifme-scout.git cd aifme-scout python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" pre-commit install ``` ## 快速开始 ### CLI 扫描网站并生成 JSON 和 Markdown 输出： ``` aifme-scout scan https://example.com ``` 输出文件将写入当前目录： - `scan-result.json` — 经过 schema 验证的 JSON 报告 - `report.md` — Markdown 摘要 ### REST API 启动 API 服务器： ``` uvicorn aifme_scout.api.app:app --host 0.0.0.0 --port 8000 ``` 扫描网站： ``` curl -X POST "http://localhost:8000/scan" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com"}' ``` 交互式文档可在以下地址找到： - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc ## CLI 示例 ### 基本扫描 ``` aifme-scout scan https://example.com ``` ### 仅输出 JSON ``` aifme-scout scan https://example.com --output json --out ./reports ``` ### 仅输出 Markdown ``` aifme-scout scan https://example.com --output markdown --out ./reports ``` ### 自定义超时和 user agent ``` aifme-scout scan https://example.com --timeout 30 --user-agent "MyBot/1.0" ``` ### 详细模式 ``` aifme-scout scan https://example.com --verbose ``` ### 静默模式 ``` aifme-scout scan https://example.com --quiet ``` ## REST API 示例 ### 健康检查 ``` curl http://localhost:8000/health ``` 响应： ``` { "status": "ok", "version": "1.0.0-rc1" } ``` ### 版本 ``` curl http://localhost:8000/version ``` ### 使用自定义选项扫描 ``` curl -X POST "http://localhost:8000/scan" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "output": "both", "timeout": 15.0, "user_agent": "MyBot/1.0", "mode": "no-llm" }' ``` ## 输出格式 ### JSON JSON 导出器生成一份稳定、格式优美的文档，该文档可通过 `schemas/v1/scan-result.schema.json` 验证。 ``` { "meta": { "schema_version": "1.0.0", "engine_version": "0.12.0", "timestamp": "2024-01-01T00:00:00+00:00" }, "site": { "url": "https://example.com", "target_url": "https://example.com" }, "seo": [], "metadata": [], "technology": [], "content": [], "social": [], "competitors": [], "evidence": [], "diagnostics": { "total_evidence_items": 0, "seo_items": 0, "metadata_items": 0, "technology_items": 0, "content_items": 0, "social_items": 0, "competitor_items": 0, "build_timestamp": "2024-01-01T00:00:00+00:00" } } ``` ### Markdown Markdown 导出器完全按照 Summary Builder 生成的原样渲染 `ScoutSummary`： ``` ## 执行摘要 Target site: https://example.com Evidence items collected: 0 ## 网站概览 URL: https://example.com Schema version: 1.0.0 ## 诊断 total_evidence_items: 0 seo_items: 0 ... ``` ## 架构概述 Scout OSS 遵循确定性、无状态的 pipeline： 1. **Website Scanner** — 获取带有传输 metadata 的原始 HTML 2. **HTML Parser** — 构建可导航的 DOM 树 3. **SEO Extractor** — 推导页面 SEO 信号 4. **Metadata Extractor** — 提取结构化的 head metadata 5. **Technology Detector** — 识别技术指纹 6. **Content Extractor** — 提取结构化的正文内容 7. **Social Discovery** — 查找关联的社交媒体资料 8. **Competitor Discovery** — 构建竞争对手比较集 9. **Evidence Collector** — 将提取器输出标准化为证据项 10. **Schema Builder** — 组装并验证 `ScoutSchema` 11. **Summary Builder** — 生成确定性的、关联证据的摘要 12. **JSON Exporter** — 将 schema 序列化为稳定的 JSON 13. **Markdown Exporter** — 将摘要渲染为 Markdown **Request Handler** 是 CLI 和 REST API 唯一的统一编排入口点。 ## 仓库结构 ``` aifme-scout/ ├── .github/ # GitHub configuration (CI, issue templates, CODEOWNERS) ├── docs/ # Documentation │ ├── architecture.md # Module-level architecture documentation │ ├── api-guide.md # API usage and examples │ ├── cli-guide.md # CLI usage and examples │ ├── schema.md # JSON Schema documentation │ ├── faq.md # Frequently asked questions │ └── migration-guide.md # Migration guidance ├── examples/ # Sample scans and screenshots ├── schemas/ # Versioned JSON schemas │ └── v1/ │ └── scan-result.schema.json ├── tests/ # Test suite │ ├── unit/ # Unit tests │ └── integration/ # Integration tests ├── src/ # Source code │ ├── aifme_scout/ │ │ ├── cli/ # CLI module │ │ ├── api/ # REST API module (FastAPI) │ │ ├── engine/ # Orchestration and assembly │ │ ├── scanner/ # Fetch and transport │ │ ├── parser/ # HTML parsing │ │ ├── extractors/ # Extraction modules │ │ ├── exporters/ # Output rendering │ │ └── utils/ # Cross-cutting helpers ├── scripts/ # Dev/release tooling └── assets/ # Static brand/media ``` ## 开发设置 ``` git clone https://github.com/aifme/aifme-scout.git cd aifme-scout python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" pre-commit install ``` ## 运行测试 ``` # 运行所有测试 pytest # 运行覆盖率 pytest --cov=aifme_scout --cov-report=term-missing # 运行特定测试文件 pytest tests/unit/test_cli.py ``` ## 代码质量 ``` # Lint ruff check src/ tests/ # 类型检查 mypy src/ # 格式检查 black --check src/ tests/ ``` ## License 该项目基于 [Apache License 2.0](./LICENSE) 授权。 ## 贡献指南 有关开发设置、测试和 pull request 指南，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 链接 - [文档](./docs/) - [贡献指南](./CONTRIBUTING.md) - [安全政策](./SECURITY.md) - [行为准则](./CODE_OF_CONDUCT.md) - [支持](./SUPPORT.md) - [常见问题](./FAQ.md) - [更新日志](./CHANGELOG.md)

标签：AI智能体, SEO分析, 商业智能, 技术栈识别, 数据提取, 竞品分析, 逆向工具