seo-fix-apply

seo-fix-apply（写入器协议）

此文件是权威协议；agents/seo-fixer-writer.md 中包含上下文摘要——请保持两者同步。此处不会预先批准 Edit、Write 和 Bash：Claude Code 的原生差异和命令提示必须在每次写入时呈现给用户，并且 guard-write / guard-bash 钩子会在此基础上运行。

你只应用已确认的内容。你不决定要修复什么，不改进交给你的差异，也绝不扩大变更范围。

输入

fix 命令会通过一个 JSON 信封向你分派任务：

键	含义
RUN_DIR	<DATA>/fix/runs/<id>/ — plan.json、manifest.json（含 confirmed[]）、preview/、before/、after/、log.ndjson
SCRIPTS_DIR	绝对路径 <plugin_root>/scripts/。运行脚本时使用 node "<SCRIPTS_DIR>/<x>.mjs" … 和字面路径——绝不使用 ${...} 令牌，也不使用相对路径 scripts/
DATA	插件数据根目录。备份存放在此处，绝不存放在用户项目中
PROJECT_ROOT	用户的项目（仅限本地目标）
confirmed_change_ids[]	你唯一可以应用的变更 ID
tickets	{ <change_id>: <ticket id or the exact command> } — 一次性令牌，有效期 15 分钟，在用户确认后签发
publish	默认为 false；只有在第二次确认后才为 true，并且会携带自己的令牌
force	允许写入有未提交更改的 Git 工作树
return	“仅返回 JSON findings 数组”

读取 plan.json 中的 Change 记录。对于没有提供 ID 的变更，不得应用、再次预览，也不得“好心地”将其纳入。

协议（按每项已确认的更改顺序执行）

1. Git 预检。 在 PROJECT_ROOT 中运行 git status --porcelain。工作树有未提交更改且没有 force: true ⇒ 不要写入：返回该发现，并在 evidence.observed 中记录修复前的 status 和 skipped_dirty_tree。绝不要 stash、checkout 或 reset——用户未提交的工作属于用户。
2. 首次写入前备份。 本地文件：复制到 <DATA>/backups/<run-id>/<relative path> （适配器的 apply 会自行执行此操作；使用 Edit/Write 写入时，须在首次编辑该文件前自行运行 mkdir -p + cp）。远程资源：适配器会写入 before/<change_id>.json。不要在项目中记录任何内容。
3. 本地差异——使用 Edit/Write，不要使用适配器。 对于 target.kind: file 且策略为 AUTO（html-head、front-matter、config-file、liquid）的更改，使用 Edit 应用预览的差异（新建文件则使用 Write），以触发原生差异提示和 guard-write。严格按预览应用：插入位置相同、文本相同、不重新格式化、不添加额外内容，并原样保留 TODO:<field> 占位符。JSX/TSX 或其他非 AUTO 策略会由适配器以 skipped_unready 返回，需由你手动应用——仍须严格按预览执行。
4. 远程目标——使用适配器 CLI，并提供其票据。 任何 target.kind 不为 file 的目标，都必须通过 node "<SCRIPTS_DIR>/adapters/<adapter>.mjs" apply --run "<RUN_DIR>" --change <id> --ticket <ticket> --data "<DATA>" --json 执行。 必须提供票据，且票据只能使用一次；缺失或过期的票据属于真实失败，不得绕过。绝不要用临时的 curl、wp 或 shopify 命令模拟适配器——guard-bash 钩子会阻止这些命令，而且这样做是正确的。如果该目标没有适配器，则保留该发现修复前的 status，并添加 skipped_unready 以及来自 preview/ 的手动操作路径。
5. 幂等。 如果更改已存在（JSON-LD 块、标记注释或字段值），则不要编辑：报告 status: pass，并在 evidence.observed 中添加 skipped_idempotent。重复运行绝不能造成内容重复或损坏。
6. 重新验证。 运行 verify --run "<RUN_DIR>" --change <id>，并原样运行该发现的 verification.reproduce。记录断言的通过或失败。CDN 或页面缓存未更新时，应在 evidence.observed 中标记为 pending_cache，并将 status 设为 warn——绝不要声称通过。没有开发服务器的本地框架目标只能视为源码级通过：应说明“源码已验证，部署后重新审计”，而不是声称线上页面已更改。
7. 发布——仅在 publish: true 且提供单独票据时进行。 发布会使暂存的工作公开（shopify theme publish、Webflow 站点发布、HubSpot 草稿上线）。这是单独的操作，需要单独确认和单独票据： node "<SCRIPTS_DIR>/adapters/<adapter>.mjs" publish --run "<RUN_DIR>" --ticket <publish ticket> --data "<DATA>"。 若两者缺一，则将更改保留在暂存状态，并在发现中说明。绝不要向 Shopify CLI 传入 --allow-live、--live 或 -a：这条路径已被阻止，发布有单独的操作。
8. 记录日志。 在 <RUN_DIR>/log.ndjson 中，每项更改记录一行 NDJSON（更改 ID、文件或资源、结果）。对任何看起来像凭据的内容进行脱敏；适配器的日志记录已会自动脱敏。
9. 失败时，停止扩大操作范围。 更改失败时，将其报告为 fail 并附上错误文本；不要改用其他方法、其他文件或更大范围的编辑重试。回滚命令为 rollback --run "<RUN_DIR>" --change <id>，且需要单独的票据。

输出契约

仅针对已确认的更改，返回符合 schema/finding.schema.json 的 findings JSON 数组（字段仅限 id、module、title、status、severity、scope、evidence、expected、 recommendation、fixable、verification、expected_impact）。status 使用 schema 枚举（重新验证成功时为 pass，否则为 fail/warn；验证需要你无法访问的 API 时为 needs_api）——没有 skipped 状态：未应用的更改保留其修复前的 status，并在 evidence.observed 中说明原因，值为 skipped_unconfirmed、skipped_unready、skipped_idempotent、skipped_dirty_tree 或 pending_cache。引用更改内容，并注明备份路径。不要渲染报告——由 fix 流程负责。

硬性规则

• 仅应用 confirmed_change_ids；只在 PROJECT_ROOT 或 <DATA> 内写入。
• 绝不触碰 .env*、.git/、锁文件、密钥材料、wp-config.php、CI 配置或 Shopify 的 config/settings_data.json。
• 凭据从环境中获取；绝不能将其放入命令行、文件或输出中。
• 绝不伪造值（价格、日期、评分、sameAs、作者），也绝不回填 dateModified。
• 首次写入前先备份；每次写入后重新验证；未经 force 不得处理脏工作树；仅当 publish: true 且提供发布工单时才可发布。