seo-platform-detect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

seo-platform-detect

The profile decides three things no module can decide on its own: which platform-conditional check ids fire, which findings are

not_applicable

because the platform owns the thing, and which fix adapter

fix

will reach for. Run it once per audit, right after the snapshot, before dispatch.

Detection is orthogonal to the vertical:

seo-vertical-detect

answers what kind of site is this, this skill answers what is it built on. Both feed one

profile.json

profile

决定三个任何 module 都无法单独决定的事项：哪些 platform-conditional check ids 会触发、哪些 findings 会因相关事项由 platform 负责而成为

not_applicable

，以及

fix

将调用哪个 fix adapter。每次 audit 执行一次，且应在 snapshot 之后、dispatch 之前执行。

Detection 与 vertical 相互正交：

seo-vertical-detect

回答“这是什么类型的站点”，此 skill 回答“它构建在什么之上”。二者共同生成一个

profile.json

。

When to run

何时运行

In the normal

/audit

and

/geo

flow you do not run this yourself:

audit.mjs

already calls the same

detect()

over the run's homepage snapshot and persists the result as

<run_dir>/profile.json

. Read that file first. Run the script directly only when you need a signal the headless pass could not use —

--path <project>

for repo/package signals,

--probe

for the WordPress plugin verdict — or when you are working outside the runner. Either way it is one run per audit, before the dispatch envelopes are built; every subagent reads the same profile.

在正常的

/audit

和

/geo

流程中，你无需自行运行：

audit.mjs

已针对本次 run 的首页 snapshot 调用相同的

detect()

，并将结果持久化为

<run_dir>/profile.json

。先读取该文件。仅在以下情况下直接运行脚本：需要 headless pass 无法使用的 signal——

--path <project>

用于 repo/package signals，

--probe

用于 WordPress plugin 判定——或者正在 runner 之外工作。无论采用哪种方式，每次 audit 在构建 dispatch envelopes 之前运行一次；所有 subagent 都读取同一份 profile。

How to run

如何运行

bash

node "${CLAUDE_PLUGIN_ROOT}/scripts/detect-platform.mjs" --snapshot "<run_dir>/pages/<home-slug>.json"

Add flags when they apply, and only then:

```
--path <project>
```
when the user gave a local project (
```
--project
```
). This is the only way repo and package signals are consulted; without it, Payload is undetectable and Next.js router detection falls back to DOM markers. It is also what turns
```
capabilities.local_files
```
on, which is what makes local file fixes possible at all.
```
--probe
```
when the target is reachable and a WordPress plugin verdict matters. It requests
```
/wp-json/
```
,
```
/.well-known/ucp
```
,
```
/products.json
```
and
```
/wp-sitemap.xml
```
— four GETs, no more. The REST namespace list is the only reliable way to tell Yoast from Rank Math from AIOSEO; HTML comments name a plugin that printed a comment, not one that is active.
```
--out "<run_dir>/profile.platform.json"
```
to persist it instead of piping the stdout JSON.

Offline / fixture mode (used by the tests, and by you when there is no network):

--html <file> [--headers <json>] [--cookies <json>] [--probes <json>] [--url <u>]

Exit codes: 0 ok · 1 bad invocation or unreadable input · 2 fetch failure.

bash

node "${CLAUDE_PLUGIN_ROOT}/scripts/detect-platform.mjs" --snapshot "<run_dir>/pages/<home-slug>.json"

仅在适用时添加相应 flags：

当用户提供 local project（
```
--project
```
）时，使用
```
--path <project>
```
。这是读取 repo 和 package signals 的唯一方式；不使用它，Payload 将无法检测，Next.js router detection 也会回退到 DOM markers。它还会开启
```
capabilities.local_files
```
，而这是实现 local file fixes 的必要条件。
当目标可访问且需要判定 WordPress plugin 时，使用
```
--probe
```
。它会请求
```
/wp-json/
```
、
```
/.well-known/ucp
```
、
```
/products.json
```
和
```
/wp-sitemap.xml
```
——共四次 GET，不会发出更多请求。REST namespace list 是区分 Yoast、Rank Math 和 AIOSEO 的唯一可靠方式；HTML comments 只能表明某个 plugin 打印了一条 comment，并不能证明它处于 active 状态。
使用
```
--out "<run_dir>/profile.platform.json"
```
将结果持久化到文件，而不是通过管道输出 stdout JSON。

离线 / fixture 模式（tests 使用，你在无网络时也使用）：

--html <file> [--headers <json>] [--cookies <json>] [--probes <json>] [--url <u>]

。

退出码：0 成功 · 1 参数调用错误或输入不可读 · 2 fetch failure。

What comes back

返回内容

{ version: "detect-platform/1", target, platform, framework, cms_plugins[], hosting, environment, capabilities, write_targets[], candidates, vertical_hints[], cards[], sources, notes[] }

Each of

platform

framework

cms_plugins[]

hosting

carries its own

confidence

(

high

≥ 8 with ≥ 2 signal kinds,

medium

≥ 5,

low

≥ 2) and the

signals

that produced it. A layer with less evidence than that is

null

— an unresolved platform is a result, not a gap. Report it as unresolved and let the run continue on

instructions

; never round a

low

up in prose.

Four layers are scored independently, so headless setups resolve correctly: a WordPress backend with a Next.js front end yields

platform: wordpress

and

framework: nextjs

, and

capabilities.head_owner

becomes

framework

. Follow

head_owner

whenever the cards disagree.

{ version: "detect-platform/1", target, platform, framework, cms_plugins[], hosting, environment, capabilities, write_targets[], candidates, vertical_hints[], cards[], sources, notes[] }

。

每个

platform

framework

cms_plugins[]

hosting

都各自带有

confidence

（

high

≥ 8 且至少有 2 种 signal kinds，

medium

≥ 5，

low

≥ 2）以及产生该结论的

signals

。证据少于相应门槛的 layer 为

null

——未解析的 platform 本身就是结果，而不是缺口。将其报告为 unresolved，然后让本次 run 在

instructions

的基础上继续；绝不在描述中将

low

向上取整。

四个 layer 独立评分，因此 headless setup 可以被正确解析：采用 Next.js front end 的 WordPress backend 会同时得到

platform: wordpress

和

framework: nextjs

，而

capabilities.head_owner

会变为

framework

。当 cards 出现分歧时，遵循

head_owner

。

Merging into profile.json

合并到 profile.json

<run_dir>/profile.json

is the union of this output and

seo-vertical-detect

's.

audit.mjs

writes it: it refreshes every key

detect()

owns and preserves the ones you added, so a

vertical

block already in the file survives a re-run (a

--vertical

flag overrides it). Shape:

json

{ "version": "detect-platform/1", "platform": {…}, "framework": {…}, "cms_plugins": [],
  "hosting": {…}, "environment": {…}, "capabilities": {…}, "write_targets": [],
  "candidates": {…}, "vertical_hints": [], "cards": [], "sources": {…}, "notes": [],
  "vertical": { "primary": "ecommerce", "also": [], "multilingual": false, "locales": [] } }

Pass

vertical_hints[]

seo-vertical-detect

as signals, never as verdicts — it must still cite its own evidence. Pass

environment.kind

to the scorer (

score.mjs --environment preview|staging|local

), which suppresses noindex-type severity-5 caps on a non-production host and reports them as expected instead.

<run_dir>/profile.json

是本输出与

seo-vertical-detect

输出的合并结果。

audit.mjs

负责写入：它会刷新

detect()

拥有的每个 key，同时保留你添加的 key，因此文件中已有的

vertical

block 在重新运行后仍会保留（

--vertical

flag 会覆盖它）。结构如下：

json

{ "version": "detect-platform/1", "platform": {…}, "framework": {…}, "cms_plugins": [],
  "hosting": {…}, "environment": {…}, "capabilities": {…}, "write_targets": [],
  "candidates": {…}, "vertical_hints": [], "cards": [], "sources": {…}, "notes": [],
  "vertical": { "primary": "ecommerce", "also": [], "multilingual": false, "locales": [] } }

将

vertical_hints[]

作为信号传给

seo-vertical-detect

，绝不要将其当作结论——它仍必须引用自己的 evidence。将

environment.kind

传给 scorer（

score.mjs --environment preview|staging|local

）；这样在 non-production host 上会抑制 noindex 类型的 severity-5 caps，并将其报告为预期结果。

Which card goes to which subagent

哪个 subagent 应获得哪些 card

profile.cards[]

already lists the paths (

references/platforms/<id>.md

). Put them in every dispatch envelope as

platform_cards

, alongside the

platform

field (the absolute

profile.json

path) and a one-line summary (

"shopify (high) · theme head · staging theme available · environment production"

), with these two instructions verbatim:

emit the card's §10 check ids when the rule matches;
card §4 items ⇒
not_applicable
naming the owner in
```
evidence.observed
```
— never a silent pass, never a
```
fail
```
for something the platform will not let anyone change.

Hand out the platform card, the framework card and any plugin card together; a headless site legibly needs all three. When

capabilities.instructions_only

is true, also tell the agents that every fix they propose will be delivered as a click-path, so

fix_preview

must be human-readable prose rather than a diff.

profile.cards[]

已经列出了路径（

references/platforms/<id>.md

）。将它们作为

platform_cards

放入每个 dispatch envelope，同时附上

platform

字段（

profile.json

的绝对路径）和一行摘要（

"shopify (high) · theme head · staging theme available · environment production"

），并逐字加入以下两条指令：

规则匹配时，输出该 card 的 §10 check ids；
card §4 中的项目 ⇒
not_applicable
，并在
```
evidence.observed
```
中指明 owner——绝不能静默通过，也绝不能对平台不允许任何人更改的事项判定为
```
fail
```
。

将 platform card、framework card 和所有适用的 plugin card 一并分发给 subagent；headless site 显然需要三者。当

capabilities.instructions_only

为 true 时，还应告知 agents，他们提出的每项 fix 都将以 click path 的形式交付，因此

fix_preview

必须是人类可读的 prose，而不是 diff。

Honesty

诚实性

```
needs
```
in
```
write_targets
```
lists credential key names. Presence is checked for
```
CLAUDE_PLUGIN_OPTION_<KEY>
```
/
```
<KEY>
```
— values are never read, printed or logged.
```
ready: false
```
means "not configured", never "wrong key".
Cookie names are evidence; cookie values are never recorded.
Repo signals are absent without
```
--path
```
, probe signals absent without
```
--probe
```
, and the profile's
```
notes[]
```
says so. Repeat that in the report rather than presenting a partial profile as complete.
A signal marked
```
UNVERIFIED
```
in a card's §12 may support a detection verdict but must never support a write. When a fix depends on an unverified API detail, the answer is
```
needs_api
```
.

```
write_targets
```
中的
```
needs
```
列出 credential 的 key names。系统只检查
```
CLAUDE_PLUGIN_OPTION_<KEY>
```
/
```
<KEY>
```
是否存在——绝不读取、打印或记录其值。
```
ready: false
```
表示“未配置”，绝不表示“key 错误”。
Cookie 名称属于 evidence；Cookie 值绝不记录。
未提供
```
--path
```
时不存在 repo signals，未提供
```
--probe
```
时不存在 probe signals，profile 的
```
notes[]
```
会注明这些情况。在报告中重复这些缺失情况，而不要将 partial profile 当作 complete profile。
card 的 §12 中标记为
```
UNVERIFIED
```
的 signal 可以支持 detection 结论，但绝不能支持 write。当某项 fix 依赖未经验证的 API detail 时，答案应为
```
needs_api
```
。