GEO-SEO Claude Code 快速上手指南：安装配置、首次 GEO 审计与故障排查
GEO-SEO Claude Code 快速上手指南：安装配置、首次 GEO 审计与故障排查
本文是 geo-seo-claude 项目 docs/getting-started.md 的深度展开版。它面向想要把 GEO（Generative Engine Optimization，生成式引擎优化）能力接入 Claude Code 的开发者、SEO 工程师与 GEO 代理商：你将从零完成前置环境准备、跨平台安装与验证，随后在几分钟内跑通 60 秒快速快照与完整 GEO 审计，并掌握常见故障的排查方法与卸载清理流程。读完本文，你将获得一套可直接复制执行的安装命令、一条可交付的首次审计路径，以及由 install.sh 与 geo/SKILL.md 源码证实的底层安装原理。
一、前置条件：装这套技能需要什么
在开始安装之前，先确认机器满足下表要求。geo-seo-claude 是一个运行在 Claude Code 之内的技能包（skill bundle），它用 Python 脚本承担页面抓取、可引用性评分、报告生成等重计算任务，因此对 Python 版本有硬性要求。
| 要求 | 用途说明 |
|---|---|
| Python 3.8+ | 运行工具脚本：页面抓取（scripts/fetch_page.py）、AI 可引用性评分（scripts/citability_scorer.py）、PDF 报告生成等 |
| Claude Code CLI | 技能与子代理（subagent）经由 Claude Code 加载与调用，是整套工具的运行时宿主 |
| Git | 安装器依赖 git clone 拉取仓库内容 |
| Playwright（可选） | 用于页面截图；主安装完成后可按需单独安装 |
补充说明两点由源码证实的细节：
- 在 Debian/Ubuntu 等发行版上，系统 Python 可能缺少
venv模块，安装器会给出python3-venv的安装提示（见 install.sh）；安装 uv 可跳过系统包依赖。 - 若本机存在
uv命令，install.sh 会优先用uv创建虚拟环境并安装依赖，速度更快；否则回退到标准库venv+pip。
如果还没有 Claude Code CLI，先通过 npm 全局安装：
npm install -g @anthropic-ai/claude-code
安装完成后可用 claude --version 确认命令可用且已加入 PATH。
二、安装：macOS / Linux 与 Windows 的三种方式
2.1 macOS / Linux — 一行命令安装
从仓库获取安装脚本后直接通过 bash 执行：
curl -fsSL <install.sh 的 raw 地址> | bash
说明：为规避第三方链接失效，也可采用下面的手动方式。两种方式最终调用的是同一个 install.sh。
2.2 macOS / Linux — 手动安装
git clone https://gitcode.com/gh_mirrors/ge/geo-seo-claude.git
cd geo-seo-claude
./install.sh
从源码看，install.sh 会先探测当前脚本所在目录是否存在 geo/SKILL.md：若存在（即你在克隆目录里执行），则直接从本地目录安装，不再重复克隆；否则临时 git clone --depth 1 拉取最新代码再安装。这意味着你甚至可以只下载 geo/、skills/、agents/、scripts/ 等目录后在本地执行安装。
2.3 Windows — 必须使用 Git Bash
PowerShell 与 CMD 均不被支持。Windows 请使用 Git Bash（Git for Windows 自带）。安装脚本 install-win.sh 会在开头检测 OSTYPE/uname 是否为 msys/cygwin/MINGW 环境（install-win.sh），非 Windows 环境会提示改用 install.sh。
# 一行命令（在 Git Bash 中运行）
curl -fsSL <install-win.sh 的 raw 地址> | bash
# 手动安装
git clone https://gitcode.com/gh_mirrors/ge/geo-seo-claude.git
cd geo-seo-claude
./install-win.sh
操作提示：右键点击克隆下来的文件夹，选择"Open Git Bash here"，或在已有 Git Bash 会话中 cd 进入该目录。Windows 版安装器在查找 Python 时会依次尝试 python3、python、py 三个命令（install-win.sh），并对依赖安装使用 pip install --user 以避免管理员权限需求。
三、安装器到底做了什么：源码级拆解
许多用户对"安装"的理解停留在"复制文件"，实际上 install.sh 完成了七个步骤，其中隔离环境与脚本改写是整个工具能稳定运行的关键。
3.1 复制技能、子技能与子代理
- 主技能：
geo/目录整体复制到~/.claude/skills/geo/（install.sh）； - 13 个子技能：
skills/下每个geo-*/目录逐一复制到~/.claude/skills/geo-*/（install.sh）； - 5 个子代理：
agents/下的geo-*.md全部复制到~/.claude/agents/（install.sh）； - 额外资源：
scripts/工具脚本、schema/JSON-LD 模板、templates/报告模板（geo-report-template.html 与 geo-report-style.css，供/geo report-pdf使用）、hooks/钩子脚本一并安装。
3.2 创建隔离的 Python 虚拟环境
依赖被安装到 ~/.claude/skills/geo/.venv/ 专属虚拟环境，不会触碰系统 Python。卸载时虚拟环境随技能目录一并删除。技能与代理文件直接引用该虚拟环境的解释器路径，因此工具运行结果不依赖 PATH 中 python3 指向哪个版本（README.md）。
3.3 改写脚本 shebang 与 Markdown 引用
安装器会把 scripts/*.py 的首行 shebang 改写为虚拟环境解释器（install.sh），随后批量改写 SKILL.md 与代理文件中的命令引用：
python3 ~/.claude/skills/geo/scripts/xxx.py→~/.claude/skills/geo/scripts/xxx.py（脚本靠 shebang 自执行）；- 裸写的
python3 -c .../python3 -m ...→<venv>/python3 -c .../-m ...，保证内联 Python 片段也使用隔离环境的依赖（install.sh）。
3.4 安装 Python 依赖
requirements.txt 中声明的依赖被装进虚拟环境，主要包含：
| 依赖 | 版本约束 | 用途 |
|---|---|---|
| beautifulsoup4 | >=4.12.0,<5.0.0 | HTML 解析（页面抓取与结构化数据提取） |
| requests | >=2.34.2,<3.0.0 | HTTP 抓取 |
| lxml | >=6.1.1,<7.0.0 | 高性能 XML/HTML 解析 |
| playwright | >=1.56.0,<2.0.0 | 无头浏览器截图 |
| Pillow | >=12.3.0,<13.0.0 | 图像处理 |
| validators | >=0.22.0,<1.0.0 | URL 校验 |
| flask | >=3.1.3,<4.0.0 | Web 面板（如 CRM dashboard） |
| rich | >=13.0.0,<14.0.0 | 终端富文本输出 |
3.5 可选安装 Playwright 浏览器
交互模式下安装器会询问是否安装 Playwright Chromium（install.sh）；非交互（管道方式）模式默认跳过并给出后续安装命令。截图相关功能缺失时可用如下命令补装：
python3 -m playwright install chromium
3.6 安装自检
安装末尾执行验证清单（install.sh）：主技能文件 SKILL.md、子技能目录 geo-audit、代理文件数量、scripts/、schema/、报告模板 geo-report-template.html、虚拟环境解释器是否全部就位，缺一即提示安装可能不完整。
四、验证安装：确认技能已被 Claude Code 识别
安装完成后，在任意项目目录打开 Claude Code，执行：
/geo quick https://example.com
若技能正确接线，Claude Code 会立即启动一次 60 秒 GEO 可见性快照。如果返回 "unknown command" 或毫无反应，请完全退出并重新打开 Claude Code —— 它在启动时读取技能与代理，运行期间新增的文件不会被识别。
也可以用文件系统确认安装落位：
ls ~/.claude/skills/geo/
ls ~/.claude/skills/ | grep geo
ls ~/.claude/agents/ | grep geo
五、首次审计：两条路径
5.1 快速路径 — 60 秒快照
/geo quick https://yoursite.com
返回概览级 GEO 可见性评分与最紧要的问题清单，适合第一印象或快速客户筛查。从 docs/commands-reference.md 看，它会抓取首页与少量关键页面，对 AI 爬虫访问、llms.txt 存在性、首页 schema、首屏内容可引用性做轻量检查，输出近似评分与最高影响缺口；该命令不落盘，评分在经由 /geo prospect audit 调用时会写入客户档案。
5.2 完整路径 — 完整审计
/geo audit https://yoursite.com
完整审计并行拉起 5 个子代理，覆盖 AI 可见性、平台优化、技术 SEO、内容质量与结构化数据五个维度，最终产出按优先级排序的行动计划与 0–100 的综合 GEO 评分，耗时视站点规模而定（数分钟级）。
根据 geo/SKILL.md 与 docs/architecture.md，/geo audit 内部执行三个阶段：
Phase 1 发现（串行）：抓取首页 HTML → 识别业务类型（SaaS / 本地服务 / 电商 / 内容出版 / 代理商 / 其他）→ 从 sitemap 或内链抽取最多 50 个关键页面。
Phase 2 并行分析（并行）：同时启动 5 个子代理——
| 子代理 | 文件 | 职责 |
|---|---|---|
| geo-ai-visibility | agents/geo-ai-visibility.md | GEO 审计、可引用性、AI 爬虫、llms.txt、品牌提及 |
| geo-platform-analysis | agents/geo-platform-analysis.md | ChatGPT / Perplexity / Google AI Overviews 平台就绪度 |
| geo-technical | agents/geo-technical.md | 技术 SEO、Core Web Vitals、可抓取性、可索引性 |
| geo-content | agents/geo-content.md | 内容质量、E-E-A-T、可读性、AI 内容检测 |
| geo-schema | agents/geo-schema.md | Schema 标记检测、校验与生成 |
Phase 3 综合（串行）：汇总各子代理报告 → 按权重计算综合 GEO Score（0–100）→ 生成按优先级排序的行动计划 → 输出客户可读报告 GEO-AUDIT-REPORT.md（含执行摘要、评分明细、严重度分级问题、快速见效项与 30 天周度行动计划，见 docs/commands-reference.md）。
5.3 综合评分的权重模型
综合 GEO Score 是六个维度的加权平均，各子代理先独立给出 0–100 子评分，再由协调器加权求和（公式详见 docs/scoring-methodology.md）：
| 类别 | 权重 |
|---|---|
| AI 可引用性与可见性 | 25% |
| 品牌权威信号 | 20% |
| 内容质量与 E-E-A-T | 20% |
| 技术基础 | 15% |
| 结构化数据 | 10% |
| 平台优化 | 10% |
评分区间解读：90–100 极佳（AI 引用概率高）、75–89 良好、60–74 一般、40–59 偏弱、0–39 严重（对 AI 系统基本不可见）。需注意评分仅为诊断工具：高分改善被 AI 引用的结构性条件，但不保证任何特定 AI 系统必然引用该站点；其中可引用性评分与 llms.txt 校验是确定性计算，而品牌、E-E-A-T、技术、Schema、平台五类由 LLM 子代理按评分标准引导评估，两次运行可能存在细微差异。
5.4 审计质量门禁
geo/SKILL.md 中定义了审计过程的硬性约束，理解它们有助于预估审计耗时与行为：
- 单次审计最多抓取 50 页（重质不重量）；
- 单页抓取超时 30 秒；
- 请求间延迟 1 秒，最大 5 个并发；
- 始终尊重并检查 robots.txt；
- 内容相似度 >80% 的重复页面跳过。
六、全部可用命令速览
主技能 geo/SKILL.md 充当路由器，读取 /geo 后的第一个参数并分发到对应子技能。安装器在完成时会打印同样的命令清单供速查：
| 命令 | 功能 |
|---|---|
/geo audit <url> |
完整 GEO + SEO 审计（并行子代理） |
/geo quick <url> |
60 秒 GEO 可见性快照 |
/geo citability <url> |
对页面做 AI 引用就绪度评分 |
/geo crawlers <url> |
检查 AI 爬虫访问（robots.txt 分析） |
/geo llmstxt <url> |
分析或生成 llms.txt |
/geo brands <url> |
扫描 AI 引用平台的品牌提及 |
/geo platforms <url> |
平台专项优化（ChatGPT、Perplexity、Google AIO 等） |
/geo schema <url> |
检测、校验与生成结构化数据 |
/geo technical <url> |
技术 SEO 审计 |
/geo content <url> |
内容质量与 E-E-A-T 评估 |
/geo report <url> |
生成客户交付级 Markdown 报告 |
/geo report-pdf <url> |
生成带图表与评分的专业 PDF 报告 |
/geo prospect <cmd> |
CRM-lite：销售管道中的客户管理 |
/geo proposal <domain> |
依据审计数据自动生成客户提案 |
/geo compare <domain> |
月度环比报告：向客户展示评分提升 |
/geo update |
从上游拉取技能最新更新 |
每个命令的输入输出、文件产物与适用场景均有详细说明，参见 docs/commands-reference.md；各命令评分如何汇入综合分见 docs/scoring-methodology.md。
七、故障排查手册
| 症状 | 原因 | 修复 |
|---|---|---|
安装时提示 Python 3.8+ is required but not found |
Python 未安装或不在 PATH |
从 python.org 安装；Windows 安装时勾选 "Add Python to PATH"；重新打开终端 |
安装器警告 Claude Code CLI not found in PATH |
claude 未安装或不在 PATH |
执行 npm install -g @anthropic-ai/claude-code，用 claude --version 确认 |
/geo quick 返回 "unknown command" 或无响应 |
Claude Code 在启动时读取技能，运行期新文件不可见 | 完全退出并重新打开 Claude Code |
bash: ./install.sh: Permission denied |
脚本可执行位未设置 | chmod +x install.sh && ./install.sh |
Windows 下 curl 无法识别或脚本语法错误 |
在 PowerShell / CMD 中运行了安装脚本 | 只用 Git Bash：右键文件夹 → "Open Git Bash here" |
| 截图相关步骤静默跳过或报错 | 安装时跳过了 Playwright（非交互或选了否） | 手动补装：python3 -m playwright install chromium |
安装器打印 Some Python dependencies failed to install |
pip 出错（网络、权限或虚拟环境冲突） | 在克隆仓库或 ~/.claude/skills/geo/ 下手动执行 python3 -m pip install --user -r requirements.txt |
值得注意的是，macOS/Linux 版安装器在检测到 Claude Code CLI 缺失时，交互模式会询问"是否仍然继续安装"，非交互模式则自动继续（install.sh）——因为该技能最终必须由 Claude Code 驱动，建议始终先装好 CLI 再装技能。
八、卸载与残留数据清理
8.1 脚本化卸载
在克隆的仓库目录内执行：
./uninstall.sh
uninstall.sh 会先列出将删除的内容并请求确认（交互模式），随后移除 ~/.claude/skills/geo/、全部 ~/.claude/skills/geo-*/ 子技能与 ~/.claude/agents/geo-*.md 代理文件。由于 Python 依赖位于技能目录内的隔离虚拟环境，会随目录一并删除，系统 Python 无需额外清理。
8.2 手动卸载
rm -rf ~/.claude/skills/geo ~/.claude/skills/geo-* ~/.claude/agents/geo-*.md
8.3 运行时数据
~/.geo-prospects/（由 /geo prospect、/geo proposal、/geo compare 使用，存放 prospects.json 客户档案、proposals/ 提案与 reports/ 月度报告）不会被卸载器删除。若不再需要这些数据，手动清理：
rm -rf ~/.geo-prospects
九、继续深入
安装、验证与首次审计走通后，可按需查阅仓库内配套文档与源码：
- docs/architecture.md —— 仓库结构与
/geo audit的完整流程设计； - docs/commands-reference.md —— 全部 16 个命令的输入、输出与适用场景；
- docs/scoring-methodology.md —— 综合评分的权重公式、各维度评分标准与局限说明；
- docs/skills-and-agents.md —— 子技能与子代理的职责划分；
- geo/SKILL.md —— 主技能文件，含业务类型识别信号、输出文件约定与 PDF 报告生成工作流；
- scripts/fetch_page.py 与 scripts/citability_scorer.py —— 页面抓取与可引用性评分的确定性实现。
至此，你已经完成从环境准备、跨平台安装、安装自检到 60 秒快照与完整审计的全流程。把这套命令固化到日常工作流中——先 /geo quick 快速筛查，再 /geo audit 深度审计，配合 /geo report 输出交付物——即可把 GEO 优化能力稳定地跑在 Claude Code 之内。