platinum-seo-engine

# 白金SEO引擎 [](https://github.com/popiliadam/platinum-seo-engine/actions/workflows/ci.yml) [](https://github.com/popiliadam/platinum-seo-engine/releases/latest) [](LICENSE) [](https://claude.ai/code) > 状态：**v2.1.0** — 可投入生产的核心（生产/发布套件 + 4个新技术SEO技能正在进行中：合约 + 测试锁定，运行时延迟）· 49种技能 · 29种命令 · 6个钩子 · 4个MCP服务器（3个stdio + 1个HTTP） > **基于Claude Code的Schema锁定、漂移检查的SEO自动化**。 > 将手动SEO工作转换为可审计、可重复的工作流 — 以JSON Schema、追加状态和自我审计工具为后盾。 --- ## 目录 [这是什么？](#what-is-this) · [适用人群](#who-is-this-for) · [功能](#what-it-does) · [快速入门](#quick-start) · [架构](#architecture) · [Screaming Frog MCP](#screaming-frog-24-mcp-optional) · [技能和命令](#skills--commands) · [技术栈](#tech-stack) · [路线图](#status--roadmap) · [文档](#documentation) · [贡献](#contributing) · [许可证](#license) --- ## 这是什么？ `platinum-seo-engine`是一个**Claude Code插件**，在编辑器中运行您的整个SEO操作 — 关键词研究、页面审计、内容规划、报告、索引 — 所有这些都受严格的合约约束，因此系统不会悄悄地偏移。 大多数SEO工具链都是松散的：一个Google Sheet在这里，一个Ahrefs导出在那里，一个LLM每次都即兴发挥不同的格式。数据分散在各个标签页中，字段名称自行更改，三个月后没有人能够重现某个数字。这个插件采取了相反的立场。 **核心思想：** *更少的代码，更严格的规则，单一权威，机器可读的合约。* 每个工作流都是一个可发现的[技能](#skills--commands)，每个输入/输出都根据[JSON Schema](schemas/)进行验证，每个状态更改都追加到事件日志中，并且一个[漂移检查](skills/governance/drift-check/SKILL.md)技能监控整个过程。 结果：您可以数周后重新运行任何工作流，将项目交给其他人，或审计一年的活动 — 而系统会准确告诉您发生了什么。 --- ## 适用人群 - **SEO操作员**，他们管理多个站点，需要可重复的工作流代替临时电子表格。 - **机构**，管理一个投资组合 — 插件是项目无关的，同一个安装驱动任意数量的站点。 - **技术SEO**，他们已经使用Claude Code，并希望在真正的管道中连接技能/命令（GSC摄取 → 发现 → 规划 → 报告）。 - **团队**，他们需要SEO决策的审计轨迹（每个操作都记录在`events.jsonl`中）。 如果您熟悉CLI、JSON和“schema优先”的理念，那么您将从本插件中获得最大的收益。 --- ## 功能 开箱即用，**49种技能**涵盖8个类别，覆盖了SEO的整个循环： | 类别 | 涵盖内容 | 技能 | |---|---|---| | **摄取** | 从Google Search Console、DataForSEO、Screaming Frog（文件下拉 + 原生MCP主协调器）、Scrapling中拉取数据 | 5 | | **发现** | 快速赢取、内容差距、 cannibalization、内容衰退、页面审计、schema审计、技术审计、地理分析、竞争分析、AIO竞争地图、GBP审计、faceted-nav审计、robots-policy审计、hreflang审计 | 14 | | **规划** | 话题地图、集群地图、新内容计划、内部链接、主任务同步、迁移地图 | 6 | | **生产** | 新博客起草、内容修订、FAQ优化、内容修复、图像生成 | 5 | | **发布** | 索引ping（URL索引API）、索引状态验证 | 2 | | **报告** | 每周/每月网站报告 + 6个投资组合级报告（概览、热图、KPI趋势等） | 9 | | **元** | 初始化项目、品牌入职、whats-next路由器、mark-done | 4 | | **治理** | Schema验证、词汇表审计、漂移检查、上下文加载器 | 4 | 另外还有**29种斜杠命令**（`/pseo-init`、`/pseo-quickwin`、`/pseo-driftcheck`、`/pseo-sf-crawl`、`/pseo-sf-status`等）、**6个钩子**在会话开始、提示提交和工具使用时触发，以及**4个MCP服务器**自动连接（GSC、DataForSEO、Scrapling、SF — 最后一个通过HTTP `http://127.0.0.1:11435/mcp`）。 典型的工作流如下： ```text /pseo-init → 启动项目（slug、domain、brand) /pseo-gsc-pull → 摄取90天的Search Console数据 /pseo-quickwin → 查找卡在11-20位且有高印象的页面 /pseo-whats-next → 路由器技能建议下一个高影响力的操作 /pseo-monthly → 生成当月的报告 /pseo-driftcheck → 审计整个状态的一致性 ``` --- ## 快速入门 ### 要求 - [Claude Code CLI](https://claude.ai/code)（最新版） - Python 3.10+ - Node.js 18+（用于MCP服务器，通过`npx`） - Git ### 安装 ```bash # 1. 克隆插件 git clone https://github.com/popiliadam/platinum-seo-engine ~/Documents/platinum-seo-engine # 2. 在Claude Code中注册 claude /plugin add ~/Documents/platinum-seo-engine # 3. 配置凭证 cp ~/Documents/platinum-seo-engine/.env.example ~/Documents/platinum-seo-engine/.env # 编辑.env — 参见下表 ``` 重启Claude Code插件添加步骤后。 ### 必需的环境变量 | 变量 | 获取方式 | |---|---| | `GOOGLE_APPLICATION_CREDENTIALS` | Google Cloud Console → IAM → 服务账户（JSON密钥路径） | | `DATAFORSEO_USERNAME` | [app.dataforseo.com](https://app.dataforseo.com) → API选项卡 | | `DATAFORSEO_PASSWORD` | 相同 | | `PSEO_WORKSPACE_ROOT` | 本地路径到您的workspace仓库（参见[架构](#architecture)） | 可选： | 变量 | 使用方 | |---|---| | `HIGGSFIELD_API_KEY` | `generate-images`技能（第11阶段+） | | `SCRAPLING_BIN` | 当Screaming Frog不可用时的站点爬取备用方案 | ### 首次运行 ```bash # 在Claude Code中 /pseo-init # 启动您的第一个项目 /pseo-status # 验证插件加载 /pseo-quickwin # 烟雾测试 — 应该在2分钟内完成 ``` 完整说明： **[docs/INSTALL.md](docs/INSTALL.md)** · 故障排除：同一文件，底部章节。 --- ## 架构 插件强制实施**两个仓库分离**，逻辑和数据分离： ``` ┌──────────────────────────────────┐ ┌──────────────────────────────────┐ │ platinum-seo-engine (此项目) │ 读取 │ platinum-seo-workspace │ │ ───────────────────────────── │ ─────► │ ───────────────────────────── │ │ • skills/ (49个SKILL.md) │ │ • projects/{slug}/ │ │ • commands/ (29种斜杠命令)│ │ ├ project.config.json │ │ • hooks/ (6个钩子) │ 写入 │ ├ master.xlsx │ │ • schemas/ (32个JSON │ ─────► │ ├ events.jsonl （追加日志）│ │ • scripts/ Schemas) │ │ └ workflows/{run_id}.json │ │ • rules/ （10个学科 │ │ • shared/ │ │ • templates/ 强制执行CI)│ │ • _archive/ │ │ • docs/ │ │ │ │ │ │ 没有逻辑。只有数据+状态。 │ │ 项目无关。 │ │ 没有项目名称在插件仓库中。 │ └──────────────────────────────────┘ └──────────────────────────────────┘ ``` 插件**永远不会**存储项目数据；工作空间**永远不会**包含逻辑。它们在运行时通过`.env`中的`PSEO_WORKSPACE_ROOT`链接。 ### 10个学科（不可妥协的规则） 每个规则都通过CI、`drift-check`技能或两者强制执行： | # | 学科 | 含义 | |---|---|---| | 1 | 单一事实来源 | 每个术语、schema和规则都定义在一个地方 | | 2 | Schema优先 | 没有数据在创建其`*.schema.json`之前被写入 | | 3 | 项目无关插件 | 插件仓库中永远不会出现项目名称（CI grep检查） | | 4 | 追加日志 | `events.jsonl`和`workflows/{run_id}.json`永远不会被覆盖 | | 5 | 原子Excel写入 | `master.xlsx`仅通过具有备份和不变性检查的交易包装器写入 | | 6 | 命名 | 斜杠和技能`kebab-case`；表格和Python`snake_case`；运行ID `{slug}-{date}-{uuid}` | | 7 | 机密管理 | API密钥从不提交；`.env`仅限；预提交守护进程 | | 8 | 词汇表学科 | 每个技术术语都存在于`docs/GLOSSARY.md` | | 9 | 技能描述学科 | 每个技能前置验证对抗`skill-frontmatter.schema.json` | | 10 | 时间学科 | 所有时间戳存储在UTC ISO-8601中，以本地时间显示 | 奖励：**Schema版本控制** — 提升schema需要`scripts/migrations/`中的迁移脚本。 完整架构： **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** --- ## Screaming Frog 24 MCP（可选） v1.8添加了Screaming Frog 24的原生MCP服务器作为PSEO中的**第四个MCP**（第一个HTTP传输MCP；现有3个使用stdio）。MCP主摄取路径取代了手动CSV下拉作为权威工作流 — 操作员触发`/pseo-sf-crawl`，协调器运行完整的24报告导出原子性。文件下拉保留为灾难恢复（D-SF-07；不会被废弃）。 ### 设置 1. 安装Screaming Frog 24+ ([screamingfrog.co.uk](https://www.screamingfrog.co.uk/seo-spider/)) 2. 打开SF → 配置 → API访问 → MCP服务器选项卡 → 点击**启动** 3. 插件安装后，通过`claude mcp list`验证 — `sf`条目应显示已连接。 SF 24的MCP是**流式HTTP**，具有每个会话的`Mcp-Session-Id`；它公开**没有**普通工具列表或健康HTTP端点，可以被裸`curl`命中。 仓库的规范化程序探针是`SfMcpClient.health()`，位于[`scripts/util/sf_mcp_client.py`](scripts/util/sf_mcp_client.py)，它运行`initialize` → `notifications/initialized` → `tools/call`握手。 ### SF设置（推荐） | 设置 | 值 | 原因 | |---|---|---| | 端口 | `11435` | 默认；匹配`.mcp.json` | | 最大响应大小（字节） | `100000` | D-SF-05；协调器通过文件路径处理大数据 | | 目录 | `/Users/apple/seo_spider_mcp_server`（推荐） | D-SF-03；**可选** F-15隔离。项目配置`sf.mcp.allowed_directory`默认值是**null**（SF GUI默认值适用；不强制隔离）直到您将其设置为此路径。 | | Node.js运行时环境 | ☐ 未选中 | D-SF-04；安全（v1.1+范围） | ### .mcp.json片段（v1.8+） ```json { "mcpServers": { "gsc": { "command": "bash", "args": ["-c", "set -a; [ -f .env ] && source .env; set +a; exec npx -y mcp-server-gsc@0.3.0"] }, "dataforseo": { "command": "bash", "args": ["-c", "set -a; [ -f .env ] && source .env; set +a; exec npx -y dataforseo-mcp-server@2.8.10"] }, "ScraplingServer":{ "command": "${SCRAPLING_BIN:-scrapling}", "args": ["mcp"] }, "sf": { "type": "http", "url": "http://127.0.0.1:11435/mcp" } } } ``` ### 首次爬取演练 ``` /pseo-sf-crawl <slug> https://example.com/ ``` 协调器：预飞行（DURUR-orch-1/2/4/7）→ `sf_crawl` → 轮询进度 → 24报告迭代（第1层：14个必填 + 第2层：10个琥珀色容忍）→ 原子移动到`projects/{slug}/sf-exports/{date}/raw/` → sf-import交接。 中间循环恢复： `/pseo-sf-crawl <slug> --resume <run_id>` 从停止的地方继续（workflow_runner.pause/resume）。 实时状态表： `/pseo-sf-status`（4列：project_slug、last_crawl_date、sf_mcp_connection_status、allowed_directory_path）。 完整设置： **[docs/INSTALL.md § Screaming Frog 24 MCP Setup](docs/INSTALL.md)** · 规格： **[docs/superpowers/specs/2026-05-26-sf-mcp-hybrid-integration-design.md](docs/superpowers/specs/2026-05-26-sf-mcp-hybrid-integration-design.md)` · ADR： **[ADR-039](docs/DECISIONS.md) + **[ADR-040](docs/DECISIONS.md)`（`type:http`) --- ## 技能和命令 技能位于`skills/{category}/{name}/SKILL.md`。每个技能都是一个自包含的markdown文件，具有声明其输入、输出、依赖和触发提示的YAML前置matter。Claude Code自动加载它们。 一些亮点： - **`quick-wins`** — 扫描GSC中卡在11-20位且印象≥100的页面，根据现实的提升潜力进行评分，并返回一个排名列表。 - **`cannibalization`** — 检测URL竞争相同的查询，排名严重性并提出整合行动。 - **`content-decay`** — 标记点击/印象每月下降的页面，并按修复难度进行评分。 - **`topical-map`** — 从种子关键词集 + DataForSEO聚类构建hub-and-spoke集群。 - **`drift-check`** — 只读治理审计，检查30多个模式、状态文件和Excel工作区的一致性；插件自我治理的基础。 - **`whats-next`** — 读取项目状态并建议影响最大的下一步行动。 浏览完整目录： [`skills/`](skills/)。 斜杠命令与常用触发的技能一一映射：参见 [`commands/`](commands/)。 --- ## 技术栈 - **Python 3.10+** — 脚本、模式验证、Excel交易 (`openpyxl`、`jsonschema`、`pyyaml`). - **Claude Code Plugin SDK** — 技能、斜杠命令、钩子。 - **模型上下文协议（MCP）** — `.mcp.json`中连接的四个服务器（v1.8+）： - `mcp-server-gsc`（Google Search Console，stdio） - `dataforseo-mcp-server`（DataForSEO，stdio） - `Scrapling`（隐秘站点抓取，防bot备用，stdio） - `sf`（Screaming Frog 24原生MCP，**HTTP** `http://127.0.0.1:11435/mcp` — v1.8 ADR-039；`type:http` ADR-040） - **JSON Schema**（Draft 7）— `schemas/`中的32个模式（31个 `*.schema.json` + `cross-sheet-invariants.json`）。 - **Excel** 作为操作数据平面（`master.xlsx`），**JSONL** 用于追加日志。 - **GitHub Actions** — CI 在每次推送时运行模式验证、漂移检查、lint 和完整的pytest套件。 --- ## 状态和路线图 **当前：** v2.1.0 — **统一修复 + 能力差距版本** 在 v2.0.0 AMO里程碑（自主性和多项目编排）基础上。SEO方法论修正（衰退R-85，cannibalization重写，规则包修复R-123+），测量规则（核心更新日历，MAD异常，干预与控制群体，AIO存在 + CTR-uplift评分），4个新技术SEO技能（分面导航，robots-policy，hreflang，迁移映射），商家和本地SEO模块，模式强化（63个节点），以及完整的测试。 AMO层之下：每个会话的项目绑定，一个编排器以有序管道运行意图并 **验证每个步骤的输出**，一个停止钩子强制跳过的步骤，每个会话的同意门控（推送/删除/POST/站点地图/索引），AI披露隔离，独立正确性预言（现实≤5%结构化错误），投资组合成本/配额账本和关闭调度器。完整的pytest套件绿色，零回归。 插件以 **15个阶段** 交付。基础阶段（0-4）已完成；技能阶段（5-13）以批次交付~49种技能；第14阶段涵盖工作空间+CI+完整飞行员运行端到端。第5阶段是 **GO/NO-GO门槛** — 失败将发送项目返回到基础工作，而不是用补丁覆盖空白。 | 阶段 | 标题 | 状态 | 技能 | |---|---|---|---| | 0 | 经理启动 | 完成 | — | | 1 | 模式迁移 | 完成 | — | | 2 | 规则 + 模板 | 完成 | — | | 3 | 核心脚本 | 完成 | — | | 4 | 钩子 + 命令 | 完成 | — | | 5 | 关键路径技能（GO/NO-GO） | 完成 | 5 | | 6 | 摄取套件 | 完成 | 4 | | 7 | 发现套件 | 完成 | 10 | | 8 | 规划套件 | 完成 | 5 | | 9 | 报告套件 | 完成 | 9 | | 10 | 内容规则处理 | 完成 | — | | 11 | 生产套件 | 进行中 | 5 | | 12 | 发布 + 专业 | 进行中 | 2 | | 13 | 治理最终 | 完成 | 4 | | 14 | 工作空间 + CI + 飞行员E2E | 进行中 | — | > 阶段11（生产）和12（发布）正在进行中：它们的技能已经锁定规格和合约（SKILL.md +配对测试），但运行时脚本延迟，因此每个技能的前置说明都是`status: wip`。 文档跟踪该前置说明，而不是过度宣传。 详细状态： **[docs/PHASE_STATUS.md](docs/PHASE_STATUS.md)** · 开放问题： **[docs/OPEN_QUESTIONS.md](docs/OPEN_QUESTIONS.md)** · 最新发布： **[docs/RELEASE_NOTES_v2.1.0.md](docs/RELEASE_NOTES_v2.1.0.md)**. --- ## 文档 | 文档 | 内容 | |---|---| | [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 愿景，两仓库策略，10门学科，阶段路线图，v1验收标准 | | [`INSTALL.md`](docs/INSTALL.md) | 需求，安装，配置，首次运行烟雾测试，故障排除 | | [`CONTRIBUTING.md`](docs/CONTRIBUTING.md) | 管理员/工作者协议，技能创作，阶段学科 | | [`WORKFLOWS.md`](docs/WORKFLOWS.md) | 完整的49技能目录，包含输入/输出 | | [`GLOSSARY.md`](docs/GLOSSARY.md) | 规范术语 — 每个技术术语都定义一次 | | [`DECISIONS.md`](docs/DECISIONS.md) | 架构决策记录（只追加） | | [`PHASE_STATUS.md`](docs/PHASE_STATUS.md) | 当前阶段 + 历史 | | [`OPEN_QUESTIONS.md`](docs/OPEN_QUESTIONS.md) | 待定决策和未解决范围 | | [`SESSION_PROTOCOL.md`](docs/SESSION_PROTOCOL.md) | 管理员会话如何开启、运行和关闭 | | [发行说明](docs/) | 每个小版本一个文件 (`RELEASE_NOTES_v*.md`) | --- ## 贡献 本项目遵循 **管理员/工作者** 协议：管理员会话设置上下文并分配工作；工作者会话一次执行一个阶段或技能，然后以关闭提交结束。超出此节奏的贡献往往会偏离轨道，因此如果您想提交更改，请先阅读 `docs/CONTRIBUTING.md`。 对于一次性的错误报告或问题，请打开一个问题。 --- ## 配套仓库 `platinum-seo-engine` 是配对的一半。另一半 — **[platinum-seo-workspace](https://github.com/popiliadam/platinum-seo-workspace)** — 持有项目数据、状态和输出。默认情况下它是私有的，因为它包含真实的客户数据；如果您分叉引擎，您将创建自己的工作空间。 --- ## 许可证 **AGPL-3.0** — 见 [`LICENSE`](LICENSE)。免费使用、研究、修改和自行托管。如果您运行修改后的版本作为网络服务或重新分发它，您的更改必须在相同的许可证下发布 — 以便引擎对所有人保持开放。 **商业支持和机构许可**（私人修改，白色标签，优先帮助）：[suleymanncapar@gmail.com](mailto:suleymanncapar@gmail.com) — 或打开一个问题。 直到v2.1.0（含）为止的发布版本都使用MIT许可证发布，并保持不变；AGPL-3.0从此开始应用。 --- ## 作者 由 **Süleyman Çapar** ([@popiliadam](https://github.com/popiliadam)) — `suleymanncapar@gmail.com` 构建。 如果您在生产环境中尝试使用并遇到文档中遗漏的边缘情况，提供可重现步骤的问题是最快的解决方法。