aigclink/geolook

## 1. 解决的问题 越来越多的用户直接询问 AI —— “X 的最佳工具”、“X 和 Y 哪个好”。如果你的品牌： | 问题 | GeoLook 能为你带来什么 | |---|---| | **AI 从不提及你** —— 你不在品类问题的候选名单中 | 逐个引擎采样真实回答；量化提及率 / 排名 / 引用份额；诊断是“缺席”还是“被竞品主导” | | **你不知道原因** —— AI 是一个黑盒 | 6 维度站点审计 + 差距诊断：页面无法爬取？缺失提取块？未出现在 AI 实际引用的渠道中？信息不一致？ | | **建议难以落地** —— 建议堆积如山，无人执行或验证 | 生成带有验收标准的实施 ticket；在样本项目 (18/21) 中，86% 可自动验证 —— “完成”是用测量数据说话，而非口头声称 | | **做的工作到底有没有用？** | 跨采样轮次的单问题前后对比 + 任务级别的前后对比 | | **你提供 GEO 服务，但打包工作很痛苦** | 一键生成供客户使用的诊断报告、策略、执行计划、ticket CSV 和验收清单 | ## 2. 功能图谱 四个阶段加上运维，全部集中在一个自托管的 dashboard 中： **Status** — 跨 15 个引擎（10 个通过 API 自动化 + 5 个手动表格）的引擎表现：提及率、排名、引用份额、每个引擎实际引用的内容、原始回答的**样本回放**、疑似负面标记；**品牌提及分布**（你与竞品的对比，按引擎和总体汇总）；竞品表格，一键即可查看每个对手最强的引擎；7 类问题库，其中每个问题都有一个**诊断类型**（疑似负面 > 竞品主导 > 缺席 > 低排名）。 **Keyword mining** — 从真实搜索需求中扩展问题库：来自品牌/竞品/品类词根的 Baidu suggest (CN) + Google autocomplete (Global) 词汇（使用免费的公共端点，无需 key）。每一轮都会进行快照对比，以标记**上升趋势的需求**（仅影响话题排序，从不影响指标）；从竞品词根中挖掘出的替代/对比表述会输入到 Competitors 页面。这些仅作为候选 —— 添加到问题库始终需要人工审核。  **Diagnosis** — 站点审计（robots / sitemap / llms.txt / 可访问性 / 语言覆盖范围 / 提取块，支持点击过滤直接跳转到修复 ticket）；差距诊断（内容 → 渠道 → 事实）；基于真实引用语料库数据加权的 **19 个渠道的渠道地图**，每个渠道都详细规定了要构建什么、构建多少、更新频率以及由谁负责；作为唯一事实来源的 **brand facts library**，llms.txt、JSON-LD 和内容草稿均由此生成。  **Action** — 结构化的 ticket（理由 / 负责人 / 工作量 / 时间窗口 / 验收标准），带有“首次测量 → 当前 → 目标”的进度条，并在出现回退时自动重新开启；一个 **content workbench**（按“未提及 + 无内容”排序的话题池，手边备有所需的提取块和 brand facts，实时的可引用性预检，针对 AI 草稿的捏造风险检查，以及将每项内容匹配到其目标渠道的**分发清单**）；**deploy assets**（llms.txt、JSON-LD、HTML snippets，每个都标有其目标位置，以及一份 DEPLOY.md 操作手册）；**发布**到 GitHub / WordPress 草稿 / WeChat OA 草稿 / webhook —— 始终需手动确认。   **Results** — 单问题前后对比（全部 / CN / global 标签页），任务级别的前后对比，验证历史；面向老板的一页纸报告、执行计划以及完整的客户交付包（HTML + CSV）。 **Operations** — 定期的全周期重新运行（每 7/14/30 天），支持多品牌一键切换，以及一个手动采样循环（导出表格 → 填写 → 重新导入），该循环的数据会反馈到相同的指标中。 ## 3. 与其他 GEO 工具的区别 大多数 GEO 产品是**监控 SaaS**：它们展示提及率和排名，按月收费，并将你的数据保留在它们的云端。GeoLook 是一个**实施平台**： | | 典型的 GEO 监控 SaaS | GeoLook | |---|---|---| | **闭环深度** | 监控 + 建议 | 监控 → 诊断 → **ticket → 资产 → 自动验证 → 交付** | | **验证** | 无（或手动打勾确认） | 程式化验证：重新爬取 + 下一轮采样决定；出现回退自动重新开启 | | **指标** | 黑盒分数 | 完全可复现；UI 中设有“这些数字从何而来”的面板；未测量的指标直接显示“未测量”，绝不造假 | | **中国市场** | 主要针对西方引擎 | 一流的 CN 引擎矩阵（GLM / Doubao / DeepSeek / Kimi / MiniMax / Nano / Baidu AI）+ 基于引用语料库数据校准的 CN 渠道（Baike、排名站点、WeChat、Toutiao…）；CN 和 Global 分开测量 | | **评分依据** | 启发式方法 | 锚定于公开的实证数据：602 个 prompt / 21,143 次引用 / 187,818 次去重后的 CN 引用（[references/](references/)) | | **数据所有权** | 供应商云端 | **所有内容都在你的机器上**，位于 `work/` 目录下（JSON/Markdown）；`git init` 就是你的备份方案 | | **成本** | 订阅制 | 免费开源；你只需为自己的引擎 API 采样成本付费（也可以是零 —— 手动采样同样有效） | | **交付物** | Dashboard 截图 | 面向客户的诊断报告 / 策略 / 执行计划 / ticket CSV —— 专为代理商和顾问打造 | 诚实的局限性：这是一个单机工具，没有账户或团队协作功能；采样频率和数量取决于你自己的 API 预算；“疑似负面”标记仅供人工审查作为线索，而非最终定论。这些都是有意为之的设计选择。 ## 4. 部署 ### 前置条件 - macOS 或 Linux（Windows 需通过 WSL —— 代码使用了 `fcntl` 文件锁） - Python **3.9+** - 仅需三个第三方包：`requests`、`beautifulsoup4`、`lxml` ### 三个步骤 ``` # 1. Clone 和安装 git clone https://github.com/aigclink/geolook.git cd geolook pip3 install requests beautifulsoup4 lxml # 2. 启动 dashboard（打开你的浏览器） python3 scripts/geo.py ui # → http://127.0.0.1:8765 # 3.（可选）配置 engine API keys # A：在 dashboard 中 — Settings → Engines & Keys → "Configure"（写入本地 .env） # B：cp .env.example .env 并进行编辑 ``` **无需 key 也可运行**：将跳过自动采样；改为使用手动采样表循环。爬取、审计、ticket 和资产生成均不需要 key。一个支持 CN 的 key（例如 DeepSeek/GLM）即可解锁问题库 / brand facts 的自动推导以及 AI 初稿生成。 ### 远程 / 服务器部署 服务器仅绑定到 `127.0.0.1`（这是刻意设置的安全边界 —— 没有身份验证层）。如需远程访问： ``` ssh -N -L 8765:127.0.0.1:8765 user@your-server # then open http://127.0.0.1:8765 locally ``` 对于多用户设置，请在前面放置带有身份验证的反向代理。`.env` 和 `work/` 包含密钥和项目数据 —— 请注意文件权限。 ### 升级 ``` git pull # your data lives in work/ and .env, both gitignored ``` ## 5. 使用说明 ### 路线 A：完全自动化（10–30 分钟） ``` python3 scripts/geo.py new --url https://example.com --market both ``` `--market` 可设为 `cn` / `global` / `both`。九个步骤将自动运行：爬取 → 审计 → 推导 facts/competitors/questions → 采样每个引擎 → ticket → 资产 → 报告 → 自动验证 → 交付包，最终生成在 `work//delivery//` 中。 ### 路线 B：dashboard 操作流程（推荐首次使用） 1. **Onboard** — 运行 `python3 scripts/geo.py ui`，按照 3 步向导操作（URL + 市场），点击“create & auto-bootstrap”。第一个周期将在后台运行。 2. **检查基础信息**（重要，约 10 分钟）— facts 仅从你的网站内容中提取；未知项标记为“unconfirmed”。检查 **Brand Facts**（修改措辞，添加别名 —— 缺少别_names 会低估提及率）和 **Question Bank**（问题读起来像真实的用户查询吗？）。 3. **Status** — 在 Overview 中查看单行结论和健康评分；进入 **Engines** 深入了解每个引擎并回放原始回答（随时记录事实错误）；进入 **Competitors** 查看每个对手最强的引擎 —— 那就是你接下来要去建设的渠道。 4. **Diagnosis** — 站点审计（点击缺失的块 → 跳转至其修复 ticket）→ Gap diagnosis → Channel map（打开任何渠道以查看其建设计划）。 5. **Execute** — 在 **Action Plan** 中按 P0 优先级处理 ticket（点击标题查看原因/方法/验收标准）；在 **Workbench** 中撰写内容（预检 ≥ B，发布为最终版，然后完成分发清单）；部署 **Assets**（将 llms.txt 放到站点根目录，JSON-LD 放入 ``，snippets 放入模板 —— 参见 DEPLOY.md）。 6. **Verify** — 设置 → “Auto-verify” 会重新爬取并判定 ticket；在下一轮采样之后，在 **Verification** 中检查每个问题的前后对比。 7. **Operate** — 启用定期重新运行（7/14/30 天）；在 **Reports & Delivery** 中生成月度报告和客户交付包。 ### 无 API 引擎的手动采样 ``` python3 scripts/geo.py sample-sheet --slug # export sheet with per-question guidance python3 scripts/geo.py sample-import --slug --file ``` ### CLI 备忘单 | 命令 | 用途 | |---|---| | `new` / `serve` / `cycle` | 自动新建项目 / 完整周期 / 轻量循环 | | `ui` | 全流程 dashboard | | `bootstrap` / `crawl` / `audit` | 推导基础信息 / 爬取 / 6 维度评分 | | `sample` / `sample-sheet` / `sample-import` | API 采样 / 手动表格 | | `plan` / `generate` / `lint` | ticket / 资产（`--draft` 添加草稿） / 捏造风险检查 | | `verify` / `report` / `deliverables` / `deliver` | 自动验证 / 报告 / 正式交付物 / 客户交付包 | | `publish` / `task` / `status` / `list` | 发布内容 / ticket 状态 / 项目面板 / 项目 | 每个命令都支持 `--help`。 ## FAQ **问：AI 的回答每次都不一样 —— 采样结果怎么能稳定？** 单次 AI 回答本质上是随机的，因此 GeoLook **绝不会将单次回答**作为指标。稳定性来自四个层面： 1. **聚合** — 提及率及相关指标是数十个问题 × 多个引擎的比率；单个问题的波动会被平均掉。 2. **固定变量** — 每个引擎的采样模型都是锁定的（在设置中可见且可更改），问题库是固定的，并且各轮次重复使用同一套问题；唯一改变的只有时间。 3. **重复轮次** — `sample --repeat N` 会在你的预算允许时对每个问题进行多次采样。 4. **归因严谨** — UI 明确将单轮的变动标记为观测性的（“下降不一定是回退 —— 采样存在噪音”）；只有连续两轮出现相同趋势的变动才算是，并且 ticket 验证依赖于确定性信号（重新爬取网站），而不仅仅是依靠采样。 老实说：它测量的是一个**分布**，而不是一个固定值 —— 这正是真实用户的体验，因为对 AI 引擎的每一次真实查询实际上也是在抽取一个随机样本。 ## 基于实证数据的评分 所有六个审计维度都锚定于公开的实证数据；`scripts/audit.py` 实现了 [references/method.md](references/method.md)： - 高影响力页面的平均单词数为 **1,943**；低分页面仅有 170 个单词 (11.4 倍) - 数字 **+61.6%**，定义 **+57.3%**，对比 **+55.3%**，操作指南 **+41.2%** 的引用概率提升 - 纯问答格式为 **−5.7%** —— 看起来像个 FAQ 并没有帮助 - 话题相关性是最强的预测指标 (r = 0.432)，高于权威性 - 品牌自有的网站仅获得了 CN 引用中的 **1.37%** —— 你的网站是事实来源；外部渠道才是引用来源 ## 设计原则与安全边界 - **单机、自托管**：在 127.0.0.1 上使用标准库 `http.server`；无数据库，无账户；数据均为纯文件 - **绝不捏造**：facts 仅来自网站内容；严禁编造竞品名称；AI 草稿必须通过 lint 检查 + 人工审核 - **验证即产品**：任何可自动验证的事物都不依赖于某人随口说的“完成了” - **发布始终需手动操作**：渠道凭证位于本地 `.env`（权限模式 600）；每次发布都是明确的点击操作；WeChat/WordPress 仅进入草稿状态 ## Claude Code 集成（可选） 本仓库也可以用作 Claude Code 技能（[SKILL.md](SKILL.md)）：将其放入你的技能目录，并告诉 Claude “针对 example.com 进行 GEO 优化”。Claude 是可选的 —— 每个脚本都是普通的 CLI。 ## 布局 ``` scripts/ All logic (geo.py CLI · dashboard.py server · ui.html single-page UI) references/ Methodology: sampling discipline, content patterns, citation structures tests/ Unit tests work// Per-project data (gitignored, never leaves your machine) docs/ Screenshots and the 40-second demo video ``` ## 联系方式 如有问题、想法或合作意向 —— 请发送电子邮件至 [bingqiang2008@gmail.com](mailto:bingqiang2008@gmail.com)，或提交一个 [issue](https://github.com/aigclink/geolook/issues)。 ## License [MIT](LICENSE)

标签：AI搜索引擎优化, GEO, Homebrew安装, Python, 代码示例, 开源, 数据分析, 无后门, 逆向工具, 防御加固