# LiiiSTEM-GEO-分析

**Repository Path**: jack5261/LiiiSTEM-GEO-analysis

## Basic Information

- **Project Name**: LiiiSTEM-GEO-分析
- **Description**: LiiiSTEM-GEO-分析
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LiiiSTEM / MoganSTEM GEO 自动化检测

> 当前状态说明：仓库已经支持 `Kimi / DeepSeek / Qwen / Doubao` 四个 Provider，可本地执行 `run / report / dashboard`。真实调用前仍需先安装依赖并配置对应的 API Key。

## 项目目标

本项目用于自动化检测 `LiiiSTEM / MoganSTEM` 在 GEO 场景中的曝光效果。当前版本围绕 `多 Provider API + 本地手动运行 + Markdown 报告 + HTML 看板` 建设一套可重复执行的检测流程。

核心目标包括：

- 读取结构化问题集并逐题提问。
- 获取多模型回答并保存原始响应。
- 自动判断回答正文是否提及 `LiiiSTEM / MoganSTEM`。
- 自动统计竞品词频。
- 生成 Markdown 报告和静态 HTML 看板。

## 当前状态

- 当前仓库只有人工 GEO 基线 [test.md](./test.md)。
- `test.md` 记录了 25 个问题、5 类题型、人工链接与人工判断结果。
- `test.md` 是后续迁移到 `prompts/geo_prompts.yaml` 的来源文件。
- 当前仓库已经包含：
  - `prompts/geo_prompts.yaml`
  - `config/brands.yaml`
  - `config/providers.yaml`
  - `geo_detector/` 下的 Provider、Evaluator、Reporter、CLI
  - `tests/` 下的基础测试

## 当前支持范围

当前固定范围如下：

- 支持 `KimiProvider / DeepSeekProvider / QwenProvider / DoubaoProvider`。
- 默认通过各家的 OpenAI 兼容聊天接口调用。
- `Kimi`、`Qwen`、`Doubao` 默认开启联网能力。
- `DeepSeek` 官方 API 当前未提供内置联网搜索，本项目暂不为它开启联网模式。
- 只支持本地手动运行。
- 只做品牌提及率和竞品词频分析。
- 保持统一 Provider 抽象，便于继续扩展。

当前版本不包含：

- 浏览器自动化
- 定时任务
- GitHub Actions
- 数据库
- 推荐排序分析
- 语义立场分析

## 当前目录结构

以下结构对应当前已落地的核心目录：

```text
.
├── test.md
├── 设计文档.md
├── todo.md
├── readme.md
├── requirements.txt
├── .env.example
├── prompts/
│   └── geo_prompts.yaml
├── config/
│   ├── brands.yaml
│   └── providers.yaml
├── geo_detector/
│   ├── cli.py
│   ├── evaluator.py
│   ├── loaders.py
│   ├── models.py
│   ├── providers/
│   │   ├── deepseek.py
│   │   ├── doubao.py
│   │   ├── kimi.py
│   │   └── qwen.py
│   └── reporting/
│       ├── markdown.py
│       └── html.py
├── runs/
├── reports/
├── dashboard/
└── tests/
```

## 运行命令

```bash
python3 -m geo_detector run                      # 同时运行全部已启用 AI 并生成结果
python3 -m geo_detector run --concurrency 5     # 指定并发数加快运行，默认是 3
python3 -m geo_detector run --provider kimi      # 只运行指定 AI
python3 -m geo_detector run --limit 1           # 只跑前 1 题做联调
python3 -m geo_detector run --run-id <run_id>   # 手动指定本次运行批次号
python3 -m geo_detector report                   # 为最近一次 run 或 batch 生成 Markdown 报告
python3 -m geo_detector report --run-id <run_id>      # 为指定 run 生成 Markdown 报告
python3 -m geo_detector dashboard                # 为最近一次 run 或 batch 生成 HTML 看板
python3 -m geo_detector dashboard --run-id <run_id>   # 为指定 run 生成 HTML 看板
cp .env.example .env                             # 复制环境变量模板文件
export MOONSHOT_API_KEY='你的 Kimi API Key'      # 在当前终端设置 Kimi API key
export DEEPSEEK_API_KEY='你的 DeepSeek API Key'  # 在当前终端设置 DeepSeek API key
export DASHSCOPE_API_KEY='你的千问 API Key'      # 在当前终端设置 Qwen API key
export ARK_API_KEY='你的豆包 API Key'            # 在当前终端设置 Doubao API key
source ./apikey.md                               # 也可以把本地私密配置写进 apikey.md 后统一加载
```

## 配置说明

V1 的配置全部采用文件化管理：

- 各 Provider API key 通过环境变量或本地 `.env` 加载。
- 也可以在本地维护一个不会上传的 `apikey.md`，用 `source ./apikey.md` 一次性导入。
- Prompt 配置计划放在 `prompts/geo_prompts.yaml`。
- 品牌词表计划放在 `config/brands.yaml`。
- Provider 默认配置计划放在 `config/providers.yaml`。

V1 固定的目标品牌词表为：

- `Liii STEM`
- `LiiiSTEM`
- `liiistem.com`
- `liiistem.cn`
- `Mogan STEM`
- `MoganSTEM`
- `mogan.app`

V1 固定的初始竞品 watchlist 为：

- `Obsidian`
- `Quarto`
- `Notion`
- `语雀`
- `Word`
- `WPS`
- `Overleaf`
- `Typora`
- `Typst`
- `LaTeX`

## 结果产物说明

V1 目标产物路径如下：

- 原始响应：`runs/<run_id>/responses/*.json`
- 运行汇总：`runs/<run_id>/summary.json`
- Markdown 报告：`reports/<run_id>.md`
- HTML 看板：`dashboard/<run_id>.html`

约定如下：

- `runs/` 负责保存可复盘的原始响应与汇总。
- `reports/` 负责保存面向人工阅读的 Markdown 报告。
- `dashboard/` 负责保存可直接打开的静态 HTML 页面。

## 日常维护建议

当前首版代码已经落地，建议按以下顺序维护：

1. 先核对 `test.md` 与 `prompts/geo_prompts.yaml` 的映射完整性。
2. 修改问题集、品牌词表或 Provider 配置时，只改配置文件，不直接改报告生成逻辑。
3. 每次执行 run 后保留 `runs/<run_id>/`，不要覆盖历史结果。
4. 优先通过报告和看板发现异常，再回查原始响应 JSON。
5. 新增 Provider 时，保持 `RunResult` 和 `RunSummary` 结构不变。

## 已知限制

- V1 只支持本地手动运行。
- V1 只分析品牌提及率和竞品词频。
- V1 不做推荐排序分析。
- V1 不做语义立场分析。
- V1 不包含浏览器自动化、定时任务或 CI。