aeo-advisor

# AEO Advisor [](LICENSE) [](https://github.com/sponsors/kailichama) [](https://nodejs.org) **一个用于获取品牌在AI答案中被引用的自托管平台。** 扫描您在ChatGPT、Perplexity、Gemini和Google AI概览中的可见性；生成优化引用的内容；发布它；并衡量它是否有所改进。 > **为什么存在。** 搜索正在从十个蓝色链接转向AI生成的答案，而获得引用的策略与经典SEO不同。AEO Advisor是一个开放的、端到端的参考实现，实现了这些策略 — — 构建用于**教授模式**，而不仅仅是运行它们。 > **本地优先 — 无需托管。** 在自己的机器上使用`npm run dev`和自己的AI提供商密钥（在设置中输入，存储在本地SQLite文件中加密）运行它。数据库在第一次运行时创建和迁移 — 无需安装数据库服务器，也无需云依赖。托管仅适用于始终在线或团队共享的部署；在这种情况下，请先阅读[SECURITY.md](SECURITY.md) — **应用程序没有内置登录**，必须位于身份验证代理后面（生产版本在没有身份验证代理的情况下关闭）。 ## 您将学习 即使您从未部署应用程序，这些都是它演示的AEO模式： - **闭环管道** — 扫描 → 创建 → 发布 → 衡量 → 重新扫描，以便内容由测量的可见性驱动。 - **引用驱动因素** — 研究支持的信号（基于GEO论文，KDD 2024），使内容可提取和可引用：具体性、片段可提取性、权威信号、独立可理解性。 - **LLM-as-Judge评分** — 一个结构化的评分标准，用于评估内容的引用价值，并提供自动修订循环。 - **BAVT（预算感知价值树搜索）** — 树结构、回溯研究，匹配基线答案质量，工具调用成本降低约4倍。 - **机器可读性工具包** — 生成`llms.txt`、`robots.txt`、`sitemap.xml`和使站点对AI爬虫可读的馈送。 - **BYOK + 静止加密** — 自带密钥架构，AES-256-GCM，确保没有共享服务器秘密。 ## 截图 | 首页 — 可见性仪表盘 | 扫描 — 多引擎审计 | |---|---| |  |  | | 衡量 — KPI、成本和ROI | 站点健康 — 机器可读性工具包 | |---|---| |  |  | ## 功能 AEO Advisor运行一个**闭环管道**，用于AI生成答案中的品牌可见性： <p align="center"> <img src="docs/assets/aeo-loop.png" alt="闭环：扫描、创建、发布、衡量 — 然后重新扫描" width="440"> </p> 1. **扫描** — 查询4个答案引擎（Claude、GPT-4o、Gemini、Perplexity），以审计目标查询的品牌可见性 2. **创建** — 通过研究 --> 简报组装 --> 内容生成 --> 引用评分 --> 自动修订循环，生成优化内容 3. **发布** — 一键将内容推送到您的CMS（GitHub Pages、WordPress、Webflow） 4. **衡量** — 跟踪KPI，验证索引，并监控AI引流流量到达您的发布页面 5. **循环** — 重新扫描以检测变化，将新的空白反馈到管道中（计划重新扫描在路线图中，位于实验性`ENABLE_SCHEDULED_SCANS`标志后面） ### 关键功能 今天有效的内容，按管道阶段划分： - **扫描** — 4个答案引擎并行查询（Claude、GPT-4o、Gemini、Perplexity Sonar）；AI查询播种来自品牌配置、竞争对手和研究；竞争对手可见性跟踪；响应丰富（URL分类、品牌情绪、引用上下文）；每个项目扫描偏好（引擎选择、竞争/提升策略） - **创建** — 通过BAVT树搜索进行深入主题研究，深度可选（快速/标准/深入），基于嵌入的重复数据删除；结构化简报组装；内容生成；LLM-as-Judge可引用性评分；草稿编辑历史和快照 - **发布** — 3个CMS适配器（GitHub Pages、WordPress、Webflow）；机器可读性工具包（robots.txt、sitemap.xml、llms.txt、RSS）为每个品牌站点生成，可部署到GitHub；发布时IndexNow + sitemap ping；通过Google索引和Bing Webmaster API发布后验证 - **衡量** — 跨扫描的可见性趋势和每个查询的性能；通过发布的页面上的隐私安全代码跟踪AI引流（不支持referrer的平台不会被检测，因此计数可能低于实际AI流量）；站点健康审计；ROI预测 - **平台** — 使用AES-256-GCM加密的BYOK密钥管理；用于无头审计的stdio MCP服务器；具有自动迁移的SQLite 一个功能是默认关闭但可用的：**自动修订循环**（`ENABLE_REVISION_LOOP=true`）重新生成和重新评估未达到评分标准的內容，最多3次迭代。计划重新扫描尚未功能完整 — 那是[路线图](#roadmap)上的首要事项。 ## 技术栈 | 层 | 技术 | |-------|-----------| | 框架 | Next.js 16（应用路由器） | | UI | React 19，Tailwind CSS 4 | | 语言 | TypeScript 5 | | 数据库 | SQLite（通过better-sqlite3，WAL模式，模式v46 — 参见`ui/src/lib/db.ts`） | | AI | Anthropic SDK（Claude），Google Generative AI SDK（Gemini）；OpenAI和Perplexity通过REST | | 嵌入 | Gemini `gemini-embedding-001` | | CMS | GitHub REST API，WordPress REST，Webflow API | | 测试 | Vitest | ## 项目结构 ``` aeo-advisor/ ├── skills/ # Claude技能定义（Anthropic约定） │ ├── README.md │ ├── ai-visibility-scanner/SKILL.md │ ├── brief-assembler/SKILL.md │ ├── citability-scorer/SKILL.md │ ├── content-generator/SKILL.md │ ├── content-topics-planner/SKILL.md │ ├── entity-authority-auditor/SKILL.md │ ├── combined-analyst/SKILL.md │ ├── domain-investigator/SKILL.md │ ├── serp-ranking-advisor/SKILL.md │ └── dev-search-first/SKILL.md └── ui/ # Next.js仪表盘应用程序 └── src/ ├── app/ │ ├── page.tsx # 首页 — 带有活动日志的启动器 │ ├── scan/page.tsx # 扫描和审计（可深链接选项卡） │ ├── create/page.tsx # 内容创作管道 │ ├── publish/page.tsx # 战略规划和CMS发布 │ ├── measure/page.tsx # KPI、查询性能和归因 │ ├── site-health/page.tsx # 机器可读性审计 │ └── api/ # API路由（运行`ls ui/src/app/api`；参见CLAUDE.md） ├── components/ # 可重用UI组件 └── lib/ ├── skills/ # 协同技能模块 │ ├── index.ts # 桶重新导出 │ ├── types.ts # SkillPromptResult，ProjectContext │ ├── shared.ts # 引用驱动程序常量，共享维度 │ ├── scanner/ # prompt.ts，parser.ts，__tests__/ │ ├── assembler/ # prompt.ts，parser.ts，__tests__/ │ ├── generator/ # prompt.ts，parser.ts，__tests__/ │ ├── scorer/ # prompt.ts，parser.ts，__tests__/ │ ├── topics/ # prompt.ts，parser.ts，__tests__/ │ ├── mapper/ # prompt.ts，parser.ts，__tests__/ │ ├── revision/ # prompt.ts │ ├── query-seeding/ # prompt.ts │ ├── entity-auditor/ # prompt.ts，parser.ts │ ├── serp-advisor/ # prompt.ts，parser.ts │ ├── mr-prose/ # prompt.ts，parser.ts │ ├── mr-scorer/ # prompt.ts，parser.ts │ └── answer-engine/ # parser.ts ├── db.ts # SQLite模式+版本控制迁移 ├── db-queries.ts # 所有表的类型化查询帮助器 ├── types.ts # 共享TypeScript接口 ├── pipeline.ts # 管道阶段编排 ├── similarity.ts # 嵌入相似性服务 ├── claude-client.ts # Anthropic SDK包装器 ├── openai-client.ts # OpenAI REST客户端（原始获取） ├── perplexity-client.ts # Perplexity API客户端 ├── brand-config.ts # 品牌上下文管理 ├── enrichment/ # 多源丰富管道（7个模块） ├── bavt/ # 预算感知价值树搜索（6个模块） └── cms/ # CMS适配器层（策略模式） ``` ### 机器可读性工具包 MR工具包为品牌站点生成AI优化的技术资产（robots.txt、sitemap.xml、llms.txt、RSS）。迭代LLM生成循环为llms.txt生成内容，缓存刷新。资产在`mr_artifacts` / `mr_artifact_versions`表中版本化，可以部署到GitHub存储库。 ``` mr_briefs（每个项目的结构化简报） | mr_artifacts（每种资产类型：robots、sitemap、llms-txt、rss） | mr_artifact_versions（每个资产的版本历史） ``` ## 管道架构 ``` ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ 扫描 │───>│ 创建 │───>│ 发布 │───>│ 衡量 │───>│ 重新扫描 │ │ │ │ │ │ │ │ │ │ │ │ 4个AI │ │ 研究 │ │ GitHub │ │ 索引 │ │ 检测 │ │ 引擎 │ │ 组装 │ │ WP │ │ 验证 │ │ 变化， │ │ │ │ 生成 │ │ Webflow │ │ 流量 │ │ 新空白 │ │ │ │ 评分 │ │ │ │ ROI │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ ``` ### 扫描阶段 并行查询4个答案引擎，每个目标查询。策略感知：**竞争**模式跟踪竞争对手的位移，**提升**模式跟踪权威景观。丰富管道分类URL，分析品牌描述，并上下文化引用。专家空白检测在没有命名权威的情况下显示机会。 ### 创建阶段 1. **主题研究员** — 基于BAVT的主题深入研究，相似性重复数据删除 2. **简报组装器** — 从扫描+研究数据中构建内容需求（具有专家名称、凭证和可引用声明的规定引用源） 3. **内容生成器** — 生成具有专家引用、比较表和跨平台可提取声明的优化内容 4. **可引用性评分器** — 在6-7个维度上评估内容（基于研究的PASS/FAIL标准） 5. **自动修订** — 如果分数 < 阈值，则修订和重新评估（最多3次迭代），使用基于证据的修复模式。 通过`ENABLE_REVISION_LOOP=true`选择加入 — 默认关闭，直到预算预飞行落地 ### 发布阶段 将批准的内容通过适配器模式推送到配置的CMS。机器可读性工具包生成robots.txt、sitemap.xml、llms.txt和RSS源。IndexNow在发布时自动ping搜索引擎。 ### 衡量阶段 跟踪随时间变化的可见性，带有折线图、扫描历史和叙述性洞察。向Google/Bing索引API提交URL，并报告到达已发布页面的AI引流访问。查询性能跟踪，带有每个查询的详细抽屉和原型过滤器（获得/失去/可见/不可见）。 ## BAVT — 预算感知价值树搜索 BAVT是创建阶段主题深入研究背后的研究引擎。基于论文*“花费更少，推理更好”*（Li等人，UBC，2026年3月），它通过将推理建模为**分支树**而不是线性链来优化LLM代理解决多步骤问题的能力。 ### 为什么不只是链式调用？ 线性推理链完全致力于每条路径 — 如果步骤3/8走错方向，则剩余5次调用被浪费。BAVT将每一步视为树节点，可以**回溯**以探索任何先状态的替代方案，将计算集中在最重要的地方。 **论文中的主要结果：** BAVT在5次工具调用中始终匹配或击败基线在20次工具调用上的表现 — 4倍的效率提升。 ### 三个核心机制 1. **树结构搜索** — 节点可以从任何先前状态分支。死胡同路径被废弃，而不是完成。 2. **步骤级批评家（残余增量评分）** — 在每个操作后，LLM批评家根据[-4，+4]的尺度评估该步骤的**边际收益**。通过评估变化而不是绝对状态，它规避了LLM的过度自信。 3. **预算感知节点选择（幂律加权）** — 使用以下公式选择要扩展的节点：`weight = node_value ^ (1 / remaining_budget_ratio)`。早期，这会广泛探索。随着预算减少，它会集中在最佳节点上。 ### 它在AEO Advisor中如何运行 ``` 问题输入 --> 规划器（抽象2-5跳计划） | 树搜索循环： 1. 选择节点（基于预算的加权） 2. 决定指令（加宽/加深/回答/备份） 3. 运行生成器（网页搜索或推理步骤） 4. 运行批评家（评估边际收益） 5. 更新节点值，分支或继续 6. 重复直到预算耗尽或找到答案 | 最高置信度终端节点的最佳答案 ``` **研究深度**可按运行选择：快速（3次网络搜索/25K令牌），标准（6/50K），或深入（10/100K）。 **替代引擎：** 设置`RESEARCH_ENGINE=single`将BAVT替换为单次传递引擎（`ui/src/lib/research/`），该引擎使用提供者的网络搜索工具进行一次预算感知请求。它实现相同的合同，正在与树搜索进行A/B评估。 **集成：** 主题研究API（`/api/projects/[id]/topics/[topicId]/research`）使用SSE进度流触发BAVT。结果按主题缓存（7天新鲜度窗口），并通过Gemini嵌入式重复数据删除。 ### 实现 `ui/src/lib/bavt/`中的六个模块： | 模块 | 角色 | |--------|------| | `types.ts` | 树节点结构，预算配置，进度事件 | | `bavt-planner.ts` | 抽象计划生成（Sonnet，无工具） | | `bavt-generator.ts` | 操作执行 — 网页搜索或根据指令进行推理 | | `bavt-critic.ts` | 步骤评分器 — 具有边际收益的LLM-as-judge | | `bavt-orchestrator.ts` | 主循环 — 节点选择，预算跟踪，指令调度 | | `index.ts` | 公共API（`runBAVT`） | ## 环境变量 > **AI提供商密钥不是环境变量。** Anthropic、OpenAI、Gemini和Perplexity密钥在应用内**设置**页面（BYOK — 自带密钥）由每位用户输入，并存储在数据库中加密。 将它们放在`.env.local`中不会产生影响。 在`ui/`目录中创建一个`.env.local`文件（复制`ui/.env.example`）： ```env # 本地开发所需 — 替代Cloudflare Access身份验证头 DEV_USER_EMAIL=you@example.com # 保存任何BYOK密钥和CMS加密所需。64字符十六进制；加密 # 如果缺少/格式错误则抛出异常（无回退，无派生）：openssl rand -hex 32 CMS_ENCRYPTION_KEY= # 可选 — 发布后验证 GOOGLE_INDEXING_SERVICE_ACCOUNT= # Google索引API服务帐户JSON BING_WEBMASTER_API_KEY= # Bing Webmaster API key # 可选 — 功能标志 ENABLE_REVISION_LOOP= # “true”启用自动修订循环（默认关闭；路由503） ENABLE_SCHEDULED_SCANS= # “true”显示扫描调度UI +警报铃（实验性；需要外部cron） RESEARCH_ENGINE= # 主题研究引擎：bavt（默认）或single（一项预算感知请求） # 可选 — 基础设施 CRON_SECRET= # /api/cron/scan的承载令牌 DATABASE_PATH= # 自定义数据库目录（默认为./data/） INDEXNOW_SALT= # IndexNow密钥派生的盐（建议覆盖） LOG_LEVEL= # 调试 | 信息 | 警告 | 错误（默认：信息） NEXTAUTH_URL=http://localhost:3000 # 应用程序的基本URL # 生产自托管，仅需阅读SECURITY.md后再设置 DISABLE_AUTH_GATE= # “true”禁用已关闭生产的身份验证门控 ``` 然后启动应用程序，打开**设置**，并粘贴您的AI提供商密钥（BYOK）以开始。 ## 数据库 `ui/data/aeo-advisor.db`处的SQLite数据库（首次运行时自动创建）。 - **模式版本**：v46（启动时自动迁移；权威版本是`ui/src/lib/db.ts`中的最后一个`PRAGMA user_version`） - **模式**：WAL（Write-Ahead Logging），用于并发读取 - **表和视图**：参见`ui/src/lib/db.ts`以获取当前、权威的模式（项目、audit_results、引用、主题、topic_research、content_drafts、cms_configs、user_api_keys、brand_knowledge、mr_artifacts、竞争对手提及等，以及`v_source_authority`和`v_citation_patterns`等SQL视图） ## 快速入门 ```bash cd ui npm install cp .env.example .env.local # 设置DEV_USER_EMAIL和CMS_ENCRYPTION_KEY（openssl rand -hex 32） npm run dev ``` 在[http://localhost:3000](http://localhost:3000)打开。 然后打开**设置**，粘贴您的AI提供商密钥（BYOK），开始扫描。 在`ui/data/`处创建的SQLite数据库将在第一次运行时自动迁移；无需安装或配置数据库服务器。 ### 部署（可选） `ui/Dockerfile` + `ui/docker-compose.yml` 构建一个独立的生产镜像，并为数据库提供持久化卷 — 适用于始终在线或团队共享实例。**生产环境部署需要身份验证反向代理**（例如 Cloudflare Access）：应用程序没有内置登录功能，身份信息来自代理的头部，生产环境构建如果没有身份验证反向代理将返回 403（`DEV_USER_EMAIL`仅限开发环境使用）。请在部署前阅读 [SECURITY.md](SECURITY.md)。 ### 命令 ```bash npm run dev # 开发服务器 npm run build # 生产环境构建 npm test # 运行单元测试 npm run test:watch # 监视模式 ``` ### 页面 | 路由 | 页面 | 用途 | |-------|------|---------| | `/` | 首页 | 项目启动台、关键指标、活动动态 | | `/scan` | 扫描 | 多引擎可见性审计、叙事洞察、差距检测、深入钻取（可深度链接的选项卡） | | `/create` | 创建 | 内容管道：研究 --> 简报 --> 生成 --> 评分 --> 修订 | | `/publish` | 发布 | 策略规划、CMS 配置、发布和验证索引 | | `/measure` | 衡量 | 可见性时间线、扫描历史、查询性能、ROI 跟踪 | | `/site-health` | 网站健康 | 机器可读性审计（robots.txt、sitemap、llms.txt、RSS） | ## 在没有 UI 的情况下使用（MCP 服务器） AEO Advisor 附带一个 [MCP](https://modelcontextprotocol.io) 服务器，因此您可以从任何支持 MCP 的代理（Claude Code、Claude Desktop、Cowork）运行审计 — 无需浏览器。它重用了相同的库和本地数据库，并从其环境中读取**您自己的**提供者密钥（BYOK）。 > 注意与 Web 应用程序的不对称性：**Web 应用程序**仅从设置（数据库）读取密钥，绝不从环境变量读取；**MCP 服务器**没有设置 UI，因此它仅从您在此处传递的环境变量读取密钥。相同的 BYOK 原则，不同的家园。 **添加它**（来自 Claude Code）： ```bash claude mcp add aeo-advisor \ --env DATABASE_PATH=/absolute/path/to/aeo-advisor/ui/data \ --env ANTHROPIC_API_KEY=sk-ant-... \ -- npx tsx /absolute/path/to/aeo-advisor/ui/src/mcp/server.ts ``` 添加 `OPENAI_API_KEY` / `GEMINI_API_KEY` / `PERPLEXITY_API_KEY` 以审计更多引擎（单个密钥提供单引擎审计）。 | 工具 | 功能 | 成本 | |------|------|------| | `audit_brand` | 多引擎可见性审计：您的品牌是否出现在客户问题的某一组中，哪些内容被引用？ | 使用 API 积分 | | `list_projects` · `get_visibility` · `get_scan_history` · `list_gaps` | 查看项目、KPI、过去的扫描和差距 | 免费 | | `generate_machine_readability` | 为域名生成 robots.txt / sitemap.xml / llms.txt | 免费 | 示例： *"审计 **Acme** 在人们询问 '最佳项目管理工具' 和 'AI 笔记应用' 时是否显示，以及哪些内容被引用。"* ## 设计系统 “彭博终端遇上豪华杂志” — 黑色星系美学。 | 元素 | 值 | |---------|-------| | 背景 | `#06060e`（深太空海军蓝） | | 卡片 | `#0c0c18`，边框为 `#1e1e35` | | 强调色三元组 | 紫色 `#8b5cf6` / 青色 `#06b6d4` / 玫瑰色 `#e879a0` | | 显示字体 | Instrument Serif | | 正文字体 | Geist Sans | | 数据字体 | Geist Mono | ## 克劳德技能 `skills/` 目录包含克劳德技能定义，按照Anthropic子文件夹约定组织（每个技能都是一个命名的文件夹，里面有一个 `SKILL.md` 文件）。请参阅 [`skills/README.md`](skills/README.md) 获取完整列表。 ## 路线图 方向，按大致优先级顺序排列。较大的主题被跟踪为 GitHub 问题，标记为 `roadmap`，其中包含详细信息和讨论；其他问题则是普通问题（`good first issue` 标记为自包含的起点）。 1. **自托管者的定时扫描** — 无头 BYOK 密钥解析和遵循保存的调度配置，以便在无需打开浏览器的情况下按计划重新扫描 2. **闭合测量环** — 将发布的内容与可见性变化关联起来（一个单元测试匹配梯度已经在 `ui/src/lib/attribution.ts` 中搭建），并跟踪哪些内容特征与收益相关 3. **一键工作流** — 确定性的扫描/创建/发布编排器（纯 TypeScript，无代理）带有进度、成本跟踪和取消 4. **更深入的机器访问** — MCP 服务器 v2（生成/评分/发布工具、SSE 传输）、现有 Zod 模式的 OpenAPI 规范和 API 令牌身份验证 5. **频道集成** — 跨发布（LinkedIn、Medium、Dev.to）、社交分享和 Google 搜索控制台/Bing 网站管理员反馈环 6. **智能代理和自动驾驶** *(实验性)* — 工作流之上的自适应编排器，以及带有干运行和成本上限的最终端到端模式。 ## 贡献 我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取设置说明、编码标准和 PR 指南。 ## 许可证 AEO Advisor 在 [Apache License 2.0](LICENSE) 下许可 — 免费使用、修改和自我托管，包括商业用途。请参阅 [`LICENSE`](LICENSE) 和 [`NOTICE`](NOTICE)。 ## 支持 如果 AEO Advisor 对您有帮助，请考虑 [赞助该项目](https://github.com/sponsors/kailichama) 以帮助资助开发和 API 成本。