milesc-bot/market-recon

# market//recon **几分钟内完成有据可查的市场规模评估，而非数周 —— 这是一个开源的 LLM operator，用于研究公开数据并展示每一项凭据。**  ## 问题所在 早期团队和 GTM/战略职能部门经常需要一个站得住脚的答案来回答“这个市场有多大？”——无论是为了融资演示文稿、董事会备忘录还是产品押注。目前的选择都很糟糕：分析师报告花费数千美元且容易过时，DIY 电子表格评估背后没有数据来源，而单次 ChatGPT prompt 虽然能生成看似确定的数字，却无法审计。这些团队真正需要的是**快速且有据可查的市场规模评估**，其中每个数字都能追溯到公开来源，且每个假设都清晰可见。 ## 解决方案 `market-recon` 是一个自托管的 middleware：输入基本的产品信息（名称、描述、目标客户、定价模型、地理范围），一个**作为自主 operator 的开源 LLM** 就会使用 OSINT 工具（网络搜索、公开页面抓取、开放数据集）研究市场，然后返回包含细分、竞争格局地图和完整引用记录的结构化 TAM/SAM/SOM 分析。 三个特性使得输出结果具有可信度而不仅仅是看似确定： 1. **每个数字都展示其推导过程** —— 公式、输入、来源和置信度等级，并在每个数字旁边的“来源”抽屉中呈现。 2. **对数据缺失的诚实** —— 任何 agent 无法从至少一个公开来源验证的信息都会被标记为 `NO DATA FOUND`，绝不凭空捏造。合成器在结构上被禁止引用它实际上并未看到的 URL。 3. **不输入专有数据，不保留任何信息** —— 它在请求时查询公开来源，并将结果仅保留在内存中。 ## 为什么是 agent，而不是 prompt 单次 prompt 调用是让模型去*回忆*市场。而这个 pipeline 是让模型去*研究*市场——并将每个 LLM 判断限制在一个可被检查的步骤中： | 步骤 | 角色 | LLM？ | 故障控制 | |---|---|---|---| | 1 | **查询规划器 (Query Planner)** —— 将产品分解为研究子问题 | 是 | 回退到模板计划 | | 2 | **OSINT 研究员 (OSINT Researcher)** —— 搜索、抓取、构建证据注册表 | 否 | 按查询重试；失效的后端会成为数据缺口，而非崩溃 | | 3 | **数据合成器 (Data Synthesizer)** —— *提取带有引用的*数字/竞争对手/定价 | 是 | 引用未知 URL 的事实将被丢弃并记录 | | 4 | **市场规模分析师 (Market Sizing Analyst)** —— 应用 TAM/SAM/SOM 公式 | 否 | 纯函数；LLM 绝不进行算术运算 | | 5 | **报告生成器 (Report Composer)** —— 细分 + 定位图 | 是 | 确定性回退，在 `warnings` 中声明降级 | 在合成之后，operator 会进行**反思**：空白的证据类别会触发一次使用替代查询的、有边界的重新搜索过程。该循环是一个约 120 行的自定义 plan-execute-reflect 模块（`marketrecon/agent/operator.py`），而不是框架图——每一次转换都是可见的，并且整个 pipeline 在测试中完全离线运行，针对虚假的 LLM 和录制的微型网络。 该模型**仅通过环境变量即可替换** —— 任何兼容 OpenAI 的 endpoint 均可工作（Ollama、vLLM、LM Studio、llama.cpp-server）：只需设置 `LLM_BASE_URL` 和 `LLM_MODEL`。结构化输出使用 schema-in-prompt JSON，并辅以 解析 → 去除标记 → 切片括号 → 修复提示 的阶梯流程，这在开源模型中比原生 tool-calling 稳健得多。 ## 快速开始 **演示模式 —— 零依赖。** 通过真实的 SSE pipeline 重放对虚构公司 *Beacondesk* 的预设分析，让您可以离线探索完整的动态 dashboard： ``` uv sync cd frontend && npm install && npm run build && cd .. uv run uvicorn marketrecon.api.app:app --port 8000 # 打开 http://localhost:8000 并点击“Replay demo analysis” ``` （没有安装 `uv`？直接使用 pip 也可以：`pip install -e .` 然后运行 `uvicorn marketrecon.api.app:app`。） **实时模式。** 将其指向开源的 LLM 和搜索后端： ``` cp .env.example .env # defaults: Ollama at localhost:11434, SearxNG at localhost:8080 ollama pull llama3.1 # the model must actually be pulled, or you'll get a clear 404 hint docker compose up # api + SearxNG (add --profile local-llm for bundled Ollama) ``` `.env` 文件不仅被 docker-compose 识别，也适用于直接运行 `uvicorn`。如果缺少 LLM 或搜索后端，运行将快速失败并在 dashboard 上显示易于理解的消息（而演示模式在两者都不存在的情况下始终有效）。 **一切都在 Docker 中：** ``` docker compose --profile local-llm up -d docker compose exec ollama ollama pull llama3.1 LLM_BASE_URL=http://ollama:11434/v1 docker compose up api ``` ## 方法论 每次分析都会运行所有三种标准评估方法（可在输入表单中选择），并且输出会对每一种进行标注： **自上而下 (Top-down)** —— 以研究员找到的、与产品类别相匹配的分析师/行业报告数字为基准： ``` TAM = median(industry report market values) ``` **自下而上 (Bottom-up)** —— 由 OSINT 发现的客户数量和定价基准构建： ``` TAM = potential_customers × avg_revenue_per_customer (ARPU = user-provided price point, else median public benchmark) ``` **价值理论 (Value-theory)** —— 基于同类竞争产品的收费情况，以及产品定位所暗示的溢价/折扣： ``` TAM = comparable_price × positioning_factor × potential_customers (factor = own_price ÷ comparable_median, clamped to [0.5, 2.0]; 1.0 if unknown) ``` **SAM 和 SOM** 在每种方法的 TAM 基础上应用标准筛选条件： ``` SAM = TAM × serviceable_share (geographic / demographic / product-fit constraints, estimated by the synthesizer from evidence; defaults to 30% with the default explicitly flagged) SOM = SAM × obtainable_share ``` `obtainable_share` 是一种有文档记录的启发式算法（`marketrecon/sizing/methods.py`），而不是模型的直觉：公司阶段的基础值（pre-launch 2% / 早期客户 5% / 扩张阶段 10%）受竞争对手密度（在拥有 10 个竞争对手时减半）衰减影响，并根据市场饱和度（低 ×1.25 / 中 ×1.0 / 高 ×0.6）进行缩放，最终截断在 [0.5%, 25%] 之间。完整的推导字符串包含在每份报告的假设中。 **置信度等级**（`marketrecon/sizing/confidence.py`）同样可审计： - **高 (high)** —— 得到 ≥ 2 个独立域名的证实，且均在 180 天内检索到 - **中 (medium)** —— 单一独立来源，或虽有多个来源证实但已过时 - **低 (low)** —— 无公开来源（该值也将被标记为未验证） 中位数（绝不使用单一挑选的值）汇总了多个发现的数字，这也使得 pipeline 能够抵御某次糟糕的数据提取。  ## 细分与竞争格局 - 跨越**三个轴**的细分 —— 行业人口统计 (firmographic)、地理、用例 —— 每个细分市场的规模计算为 `share × SAM`，并注明份额的出处（LLM 推断的份额最高仅限*中 (medium)* 置信度）。 - 研究员识别**直接和相关的竞争对手**；合成器纯粹从公开来源提取定位、定价层级和市场份额信号（融资、员工人数、评论数量）。 - 生成器选择两个信息量最大的轴，并将竞争对手放置在**定位象限图**上，前端将其渲染为动态散点图 —— 悬停在任何圆点上即可查看其带有来源的详细信息。 ## 架构 ``` frontend/ Vite + vanilla JS + anime.js v4 dashboard (SSE progress, animated report) api/ FastAPI: POST /api/analyses · GET …/events (SSE) · …/report · …/sources agent/ operator loop + 5 roles — HTTP-agnostic, unit-testable tools/ SearxNG / SerpAPI search · cached fetcher (SQLite, TTL) · World Bank data sizing/ pure TAM/SAM/SOM math + confidence scoring schemas/ versioned Pydantic contract (Report v1.0) shared with the frontend ``` 设计说明位于 [`docs/DESIGN.md`](docs/DESIGN.md) 中。UI 遵循 `prefers-reduced-motion` 设置，仅导入其使用的 anime.js 模块（总共约 20 KB gzip 压缩的 JS），并且其图表调色板已经过验证，可确保对色觉障碍友好，并在浅色和深色表面上均具有良好对比度。 ## 测试 ``` uv run pytest # 34 tests, fully offline ``` 测试套件涵盖了精确的规模计算数学、JSON 修复阶梯、针对录制响应的工具适配器、针对虚假 LLM 的完整 agent pipeline（事件排序、引用完整性、对缺失数据的诚实、对幻觉来源的拒绝、生成器回退），以及在演示模式下的端到端 API 契约测试。 ## 配置 | 变量 | 默认值 | 用途 | |---|---|---| | `LLM_BASE_URL` | `http://localhost:11434/v1` | 任何兼容 OpenAI 的 endpoint | | `LLM_MODEL` | `llama3.1` | 例如 `qwen3`, `glm-4.5-air`, `mistral` | | `LLM_API_KEY` | `ollama` | 本地占位符；托管 endpoint 需要真实密钥 | | `SEARCH_BACKEND` | `searxng` | `searxng` (无需密钥) 或 `serpapi` | | `SEARXNG_URL` | `http://localhost:8080` | 自托管实例 | | `SERPAPI_KEY` | — | 仅在使用 SerpAPI 时需要 | | `CACHE_PATH` / `CACHE_TTL_HOURS` | `data/cache.sqlite3` / `24` | 抓取缓存 | ## 数据与隐私 不需要、不请求、也不存储任何专有或客户数据。分析针对**在请求时抓取的公开 OSINT 来源**运行；运行过程存在于进程内存中，并在重启后消失。唯一的持久化存储是已公开页面的本地 TTL 限制缓存 —— 删除该文件即可遗忘所有内容。`examples/` 文件夹包含一家明显是虚构的公司，其来源域名为 `*.example`。 ## 这展示了什么 - **Agent 编排** —— 一个具备角色隔离、有限重试和优雅降级能力的 plan-execute-reflect operator，支持离线端到端测试。 - **OSINT 工具集成** —— 可替换的搜索后端、礼貌的缓存抓取、无需密钥的开放数据丰富，以及从原始抓取到最终数字的引用追踪。 - **严谨的市场规模评估** —— 三种具有明确公式的命名方法论，有文档记录的可获得份额启发式算法，置信度分级，以及对缺失数据的结构性诚实。 - **前端工程** —— 实时的 agent 进度流以及基于版本化 JSON 契约的、注重无障碍访问的动态报告 UI。 围绕业务成果进行构建：创始人可以在笔记本电脑上免费获得一份有根据、可审计且附带来源的市场规模评估。 与 [revops-forecast](../revops-forecast)（与 CRM 无关的收入预测）配套使用 —— 具有相同的视觉语言和相同的“展示推导过程”的理念。 ## 许可证 MIT

标签：AI智能体, AI风险缓解, ESC4, OSINT, 中间件, 商业分析, 市场调研, 网络调试, 自动化, 请求拦截, 逆向工具