fix

fix（选择性写入）

disable-model-invocation: true 表示模型绝不会自行触发此操作——只有用户运行 /claude-seo-ai:fix 才能触发。写入只能通过 seo-fixer-writer 子 Agent（唯一具有 Write/Edit 权限的 Agent）进行，并且只能在明确确认后进行。

--category 用于筛选报告中的发现项，匹配发现项的模块 ID（M5、M7、M17……）、轴（search、ai 或 both——both 会同时匹配前两者）、可修复类别（auto、proposed、advisory）或范围（page、site……），且不区分大小写。它不是主题词汇，也不会按逗号拆分：重复使用该标志以扩大筛选范围（--category M5 --category M17）。将用户的请求转换为这些词——“修复我的 schema”对应 --category M5，“只修复安全项”对应 --category auto——并说明你应用了哪个筛选条件。 --target 接受适配器 ID，以及别名 local、shopify、wordpress、manual 和提供商名称 webflow/wix/ghost/hubspot/bigcommerce（每个都会展开为 page-api）。

在进行任何操作之前，务必牢记两条绝对原则：

• 绝不能凭记忆修复。 每项变更都必须来自磁盘上持久保存的 report.json。如果此目标没有报告，先运行审计——不要根据对话记录重建发现项。
• 你绝不写入。 此线程只运行只读操作（capabilities、plan、preview、verify）。 apply、publish 和 rollback 由写入子 Agent 执行，且每项都需要一个工单。

可修复类别（来自每个发现项的 fixable 字段——参见 schema/finding.schema.json）

• AUTO — 确定性、增量式、可机器验证且语义风险低。可写入（需提供差异并确认）：meta viewport/charset/<html lang>；Tier-1 JSON-LD 区块；sameAs/@id/dateModified（仅使用已确认的输入）；robots.txt AI 爬虫预设 + Sitemap: 行；自引用 canonical；hreflang 链接集；OG/Twitter 卡片；图像 width/height；XML 站点地图条目；llms.txt（需披露，评分为 0）。
• PROPOSED — 会改变文本或含义；起草差异并要求逐项接受：生成的 <title> 和 meta description、答案区块/TL;DR 改写、内部链接插入、标题结构调整、生成的图像替代文本。
• ADVISORY — 绝不写入：内容/E-E-A-T 改写、添加统计数据或引文、Core Web Vitals、渲染策略、重定向/状态码、链接建设、Merchant Center/GBP 后端数据。

每个步骤的设置

DATA="${CLAUDE_SEO_AI_HOME:-${CLAUDE_PLUGIN_DATA:-$HOME/.claude-seo-ai}}"
SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"

以下每条命令的格式均为 node "${CLAUDE_PLUGIN_ROOT}/scripts/<x>.mjs" …，并带有 --data "$DATA"。 凭据绝不通过标志传递：适配器会先读取环境变量 CLAUDE_PLUGIN_OPTION_<KEY>，再读取 <KEY>。如果缺少密钥，请指出密钥名称——绝不要要求用户在此处粘贴值。

流程

0. 解析并提前终止。 解析 DATA 和 SCRIPTS。如果提供了 --rollback <run_id>，则跳过其他所有操作：读取 <DATA>/fix/runs/<run_id>/manifest.json，展示将要恢复的内容（来自 <DATA>/backups/<run_id>/ 的文件、before/*.json 负载、已发布主题的 previous_live_id），请求确认，然后让写入子 Agent运行每个适配器的 rollback --all。报告结果并停止。

1. 加载报告——绝不凭记忆。 使用 --report <path>，否则使用 --run <id>，再否则使用此目标在 <DATA>/runs/<host>/latest 下的最新运行。读取 report.json（发现项、评分、目标）及其旁边的 profile.json。如果报告缺失，或 generated_at 已超过 24 h，请说明情况，并建议先重新运行 /claude-seo-ai:audit。未经用户明确同意，不要继续使用过期报告。 **2. 确认平台配置。**读取 profile.platform、profile.framework、 profile.capabilities、profile.write_targets。当平台置信度低于 high，或 --target auto 留下多个可能的写入路径时，展示检测结果（包括信号）， 并请用户确认或通过 --target 覆盖。配置错误会导致写入错误的界面。

**3. 选择适配器并检查就绪状态。**按以下顺序选择：

• 本地路径目标（或 --project <dir>）⇒ local-files，以及一个平台适配器，用于处理源代码树不负责的资源字段；
• shopify ⇒ shopify-theme + shopify-admin；
• wordpress ⇒ 凭据存在且 SEO 插件开放写入时使用 wordpress-rest，否则在设置了 --ssh/WP_SSH 时使用 wordpress-wpcli，否则使用 instructions；
• webflow / wix / ghost / hubspot / bigcommerce ⇒ 存在密钥时使用 page-api，否则使用 instructions；
• squarespace / framer / unknown ⇒ instructions。

对每个适配器运行 node "${CLAUDE_PLUGIN_ROOT}/scripts/adapters/<adapter>.mjs" capabilities --data "$DATA"。 仅按名称列出缺失的密钥，并提示：运行 /plugin 为 claude-seo-ai 输入密钥，或在启动 Claude Code 的 shell 中导出这些密钥。缺少密钥会将该目标降级为 instructions；不会中止运行。

**4. 制定计划。**一次调用即可构建完整计划：

node "${CLAUDE_PLUGIN_ROOT}/scripts/fix-plan.mjs" --report <report.json> --profile <profile.json> \
  --targets <a,b> --run <run_id> [--category …] [--include-proposed] [--answers <json>] \
  [--project <dir>] [--dev-url <u>] [--lang en|es] --data "$DATA"

它会将 plan.json + manifest.json 写入 <DATA>/fix/runs/<run_id>/，并返回分组摘要。对于尚未确定的现实输入——语言区域映射、sameAs 个人资料 URL、robots 预设、重定向目标、发布日期——在聊天中询问，并通过 --answers 传回。 切勿编造这些信息，也绝不能让 TODO:<field> 占位符进入写入操作。

**5. 预览。**对每项更改运行 preview --run <dir> --change <id>。按目标分组输出，并为每项更改标注其 live_impact：[none]（文件或已暂存的主题）、[staged]（写入草稿/未发布的界面，访客不可见）、[LIVE]（立即可见）。对文件显示统一差异；对 API 负载显示请求 + 变量 + before 值；对 CLI 操作显示确切命令。Shopify 主题更改还会附带其 theme check 结果——若有错误，则阻止应用。

**6. 遇到 --dry-run 时停止。**打印摘要，明确说明未写入任何内容，然后结束。 默认采用 Dry-run：如果用户没有明确要求应用更改，就按 Dry-run 处理。

**7. 确认后再签发工单。**可逐项询问确认，也可让用户一次性接受整批更改——由用户选择。确认时必须说明用户接受的更改的 live_impact。对于每项已确认的更改，在确认的同一轮中：

node "${CLAUDE_PLUGIN_ROOT}/scripts/fix-ticket.mjs" issue --command "<the exact apply command>" \
  --run <run_id> --change <chg_id> --data "$DATA"

工单仅可使用一次，并在 15 分钟后过期。在 manifest.json.confirmed 中记录已确认的 ID。绝不能为用户刚刚未接受的更改签发工单，也绝不能为未向用户展示的命令签发工单。

8. 仅派发一次写入器。调用一次 Agent(seo-fixer-writer)，并提供 JSON 信封，包含： RUN_DIR、SCRIPTS_DIR（绝对路径 ${CLAUDE_PLUGIN_ROOT}/scripts）、DATA、PROJECT_ROOT（本地目标）、confirmed_change_ids[]、tickets（每项更改对应的 ID）、publish（默认 false）、force、lang，以及 return: "JSON array of findings only"。--publish 需要再次确认，并且发布命令需要单独的工单——发布会让已暂存的工作变为可见，因此绝不能与应用确认合并处理。

**9. 验证。**对每项已应用的更改运行：verify --run <dir> --change <id> [--dev-url <u>]，并检查该条发现自身的 verification.reproduce。如实解读结果——CDN 或页面缓存未更新时，状态应为 pending_cache，绝不能算通过。没有开发服务器的本地框架目标只能在源代码层面验证：应说明“源代码已验证；部署后请重新审计”，而不能声称线上页面已修复。 10. 报告。 列出变更 · 目标 · live_impact · 状态 · 验证的表格，随后说明：已暂存但尚未公开的内容、缓存注意事项、回滚命令（/claude-seo-ai:fix --rollback <run_id>）以及后续步骤（发布、重新审核，以及用户需要点击完成的剩余 instructions 项）。

目标类型

• 仅 URL（不使用 --project）：绝不选择 local-files——没有可供编辑的源代码树。框架网站通过平台适配器对各资源进行修复，其他所有操作则通过 instructions 完成；此外，还会提供使用 --project <dir> 重新运行以编辑源代码的选项。
• 本地框架项目：审核可能针对 http://localhost:3000 或构建输出运行，但修复会通过 route-map（路由 → 文件映射）编辑源代码，并通过 --dev-url 重新抓取运行中的开发服务器以进行验证。说明你验证的是三者中的哪一个。
• 没有 API 密钥的托管式建站工具：instructions 会以 --lang en|es 呈现准确的点击路径，并预先填好各项值。这是有效结果，不是失败。

安全（硬性规则）

• 默认采用试运行。 只有用户提出请求并确认变更后，才能写入。
• 遵循 Git 状态：除非使用 --force，否则拒绝写入有未提交变更的工作树；使用 git status --porcelain 检查，并优先创建 seo-fix/<date> 分支。
• 先备份：本地文件备份至 <DATA>/backups/<run_id>/<relpath>，远程资源备份至 <RUN_DIR>/before/<change_id>.json，Shopify 备份完整主题副本。--rollback <run_id> 会从这些位置原样恢复。
• 幂等：每项变更都带有标记或存在性检查；重新运行会产生 skipped_idempotent，绝不会重复添加区块。
• 默认绝不发布到线上：Shopify 推送至未发布的主题，Webflow/HubSpot 保持暂存状态，WordPress 绝不修改 status 或文章内容，Wix 将 publish:false 设为默认值，除非端点另有要求。任何 [LIVE] 操作都会在询问前明确说明。
• 绝不触碰 .git/、.env*、锁文件、密钥材料、wp-config.php 或 Shopify 的 config/settings_data.json。guard-write 和 guard-bash 钩子会分别强制执行这些限制。
• 凭据：仅通过环境变量提供，绝不放入 argv、绝不回显、绝不写入仓库中的文件。日志中的命令会经过脱敏处理。
• 不捏造信息：不编造统计数据、引用、价格、评分或身份链接，也不回填过去的 dateModified。