siluzan-tso-cli 1.1.15-beta.1 → 1.1.15-beta.2

package/README.md

@@ -51,7 +51,7 @@ siluzan-tso init -d /path/to/skills  # 写入自定义目录
 siluzan-tso init --force             # 强制覆盖已存在文件
 ```
 
-> **注意**：当前为测试版（1.1.15-beta.1），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
+> **注意**：当前为测试版（1.1.15-beta.2），供内部测试使用。正式发布后安装命令将改为 `npm install -g siluzan-tso-cli`。
 
 | 助手                    | 建议 `--ai`                          |
 | ----------------------- | ------------------------------------ |

package/dist/index.js

@@ -2760,6 +2760,8 @@ async function fetchLatestVersion() {
 import * as path5 from "path";
 import { mkdir as mkdir2, writeFile, chmod as chmod2 } from "fs/promises";
 var MAX_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+var CAMPAIGN_DETAIL_RE = /^\/campaignmanagement\/campaign\/[^/]+\/[^/]+\/?$/i;
+var SEM_MANAGEMENT_RE = /\/SemManagement\//i;
 function shouldAttemptPreSnapshot(method, url) {
   const m = method.toUpperCase();
   if (m !== "PUT" && m !== "PATCH") return false;
@@ -2771,7 +2773,9 @@ function shouldAttemptPreSnapshot(method, url) {
   }
   const host = u.hostname.toLowerCase();
   if (!host.includes("googleapi")) return false;
-  return /\/SemManagement\//i.test(u.pathname);
+  if (SEM_MANAGEMENT_RE.test(u.pathname)) return true;
+  if (CAMPAIGN_DETAIL_RE.test(u.pathname)) return true;
+  return false;
 }
 function getSnapshotGetUrl(method, url) {
   if (!shouldAttemptPreSnapshot(method, url)) return null;
@@ -3671,6 +3675,10 @@ function applyListFilters(records, opts) {
       });
     }
   }
+  const rk = opts.resourceKey?.trim();
+  if (rk) {
+    out = out.filter((r) => r.resourceKey === rk);
+  }
   return out;
 }
 async function runAuditList(opts) {
@@ -3690,6 +3698,7 @@ async function runAuditList(opts) {
       outcome: opts.outcome,
       runId: opts.runId,
       sinceTs: opts.sinceTs,
+      resourceKey: opts.resourceKey,
       failuresOnly: Boolean(opts.failuresOnly)
     },
     items: filtered
@@ -3809,77 +3818,178 @@ auditId: ${record.auditId ?? "\u2014"}`);
 // src/commands/audit-restore.ts
 import { createHash } from "crypto";
 var TSO_WRITE_AUDIT_NS3 = "tso";
+var SUBSEQUENT_WRITES_LOOKBACK_DAYS_MAX = 400;
 async function loadSnapshotForRecord(record) {
   if (!record.preSnapshotRef) return null;
   return readPreSnapshotPayload(TSO_WRITE_AUDIT_NS3, record.preSnapshotRef);
 }
-async function runAuditRestorePlan(opts) {
-  const auditId = opts.id?.trim() ?? "";
-  if (!auditId) {
-    console.error("\u8BF7\u4F7F\u7528 --id <auditId>");
-    process.exit(1);
+function beijingDayFromIsoTs(ts) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return formatBeijingYmd(/* @__PURE__ */ new Date());
+  return formatBeijingYmd(d);
+}
+async function collectSubsequentWrites(target) {
+  const key = target.resourceKey?.trim();
+  if (!key) return [];
+  const sinceDay = beijingDayFromIsoTs(target.ts);
+  const safeSince = sinceDay && /^\d{4}-\d{2}-\d{2}$/.test(sinceDay) ? sinceDay : beijingDayStringDaysAgo(SUBSEQUENT_WRITES_LOOKBACK_DAYS_MAX);
+  const records = await readWriteAuditRecordsSince(TSO_WRITE_AUDIT_NS3, safeSince);
+  const targetMs = new Date(target.ts).getTime();
+  return records.filter((r) => {
+    if (r.resourceKey !== key) return false;
+    if (r.auditId === target.auditId) return false;
+    const t = new Date(r.ts).getTime();
+    if (Number.isNaN(t) || Number.isNaN(targetMs)) return false;
+    return t > targetMs;
+  }).map((r) => ({
+    auditId: r.auditId ?? "",
+    ts: r.ts,
+    method: r.method,
+    outcome: r.outcome,
+    pathname: r.pathname,
+    commit: r.commit,
+    invokedCommand: r.invokedCommand,
+    hasSnapshot: Boolean(r.preSnapshotRef)
+  })).sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+}
+function deriveSupportability(record, snapshot) {
+  if (!record.auditId) {
+    return {
+      code: "v1_record_no_audit_id",
+      reason: "v1 \u5386\u53F2\u5BA1\u8BA1\u884C\u7F3A auditId/preSnapshotRef\uFF0C\u65E0\u6CD5\u7528 restore-apply",
+      hint: "\u8BF7\u4EBA\u5DE5\u6839\u636E commit \u6587\u672C\u4E0E\u539F\u59CB\u53D8\u66F4\u4EBA\u5DE5\u6062\u590D\uFF1B\u6216\u4EC5\u4F5C\u4E3A\u53C2\u8003\u67E5\u770B audit show"
+    };
+  }
+  if (record.outcome !== "success") {
+    return {
+      code: "not_success_write",
+      reason: `audit \u7ED3\u679C\u4E3A ${record.outcome}\uFF0C\u539F\u5199\u672A\u751F\u6548\uFF0C\u65E0\u9700\u8865\u507F`,
+      hint: "\u5931\u8D25\u7684\u5199\u4E0D\u4F1A\u6539\u53D8\u7EBF\u4E0A\u72B6\u6001\uFF1B\u5982\u9700\u6392\u67E5\u8BF7\u770B audit show \u4E2D\u7684 error \u5B57\u6BB5"
+    };
+  }
+  const method = record.method.toUpperCase();
+  if (method === "POST") {
+    return {
+      code: "unsupported_method_post",
+      reason: "POST \u521B\u5EFA\u578B\u5199\u65E0\u5199\u524D\u5FEB\u7167\uFF0C\u65E0\u6CD5\u7528\u540C URL \u8865\u507F",
+      hint: "POST \u64A4\u9500\u9700\u8C03\u7528\u5BF9\u5E94\u8D44\u6E90\u7684 DELETE \u7AEF\u70B9\uFF08CLI \u6682\u672A\u81EA\u52A8\u6D3E\u751F\uFF09\uFF1B\u8BF7\u4EBA\u5DE5\u8FD0\u884C\u5BF9\u5E94 delete/stop \u547D\u4EE4"
+    };
+  }
+  if (method === "DELETE") {
+    return {
+      code: "unsupported_method_delete",
+      reason: "DELETE \u5220\u9664\u578B\u5199\u5728\u5F53\u524D\u5FEB\u7167\u767D\u540D\u5355\u5916\uFF0C\u65E0\u5199\u524D GET",
+      hint: "DELETE \u64A4\u9500\u9700\u6839\u636E\u5386\u53F2\u5FEB\u7167\u91CD\u5EFA\u8D44\u6E90\uFF1B\u5F53\u524D CLI \u672A\u5BF9\u8BE5\u8DEF\u5F84\u914D\u7F6E\u5199\u524D\u5FEB\u7167\uFF0C\u8BF7\u4EBA\u5DE5\u6062\u590D"
+    };
+  }
+  if (method !== "PUT" && method !== "PATCH") {
+    return {
+      code: "unsupported_method_other",
+      reason: `\u8865\u507F\u5199\u4EC5\u652F\u6301 PUT/PATCH\uFF0C\u672C\u6761\u4E3A ${method}`
+    };
+  }
+  if (!record.preSnapshotRef) {
+    return {
+      code: "no_snapshot",
+      reason: "\u8BE5 PUT/PATCH \u672A\u547D\u4E2D\u5199\u524D\u5FEB\u7167\u767D\u540D\u5355\uFF08\u4EC5 Google SemManagement \u9ED8\u8BA4\u5F00\u542F\uFF09",
+      hint: "\u65E0\u6CD5\u81EA\u52A8\u8865\u507F\uFF1B\u8BF7\u4EBA\u5DE5 GET \u5386\u53F2\u503C\u540E\u901A\u8FC7\u5E38\u89C4 ad/optimize \u547D\u4EE4\u53CD\u5411\u5199"
+    };
+  }
+  if (!snapshot) {
+    return {
+      code: "snapshot_missing_or_invalid",
+      reason: "preSnapshotRef \u6307\u5411\u7684 snapshot JSON \u4E0D\u53EF\u8BFB\u6216\u8D8A\u754C",
+      hint: "\u68C0\u67E5 ~/.siluzan/write-audit/tso/snapshots/<auditId>.json \u662F\u5426\u5B58\u5728\uFF1B\u6216\u4FDD\u7559\u671F\u5DF2\u8FC7\u88AB\u6E05\u7406"
+    };
   }
+  return {
+    code: "ready_put_patch",
+    reason: "PUT/PATCH \u5355\u6B65\u8865\u507F\u5199\u5C31\u7EEA"
+  };
+}
+async function buildRestoreContext(auditId) {
   const record = await findWriteAuditRecordByAuditId(TSO_WRITE_AUDIT_NS3, auditId);
-  let plan;
   if (!record) {
-    plan = { status: "unsupported", auditId, reason: "audit_not_found" };
-  } else if (record.outcome !== "success") {
-    plan = { status: "unsupported", auditId, reason: "not_success_write", detail: record.outcome, record };
-  } else if (!record.preSnapshotRef) {
-    plan = {
-      status: "unsupported",
-      auditId,
-      reason: "no_snapshot",
-      detail: "\u7F3A\u5C11 preSnapshotRef",
-      record
+    return {
+      record: null,
+      snapshot: null,
+      subsequentWrites: [],
+      successfulSubsequentWriteCount: 0,
+      supportability: {
+        code: "audit_not_found",
+        reason: `\u672C\u673A\u6700\u8FD1 ${SUBSEQUENT_WRITES_LOOKBACK_DAYS_MAX} \u4E2A\u5317\u4EAC\u65E5\u5185\u672A\u627E\u5230 auditId=${auditId}`,
+        hint: "\u7528 audit list --days 14 --match <commit/path \u7247\u6BB5> \u53CD\u67E5\uFF1B\u8D85\u8FC7\u4FDD\u7559\u671F\u53EF\u80FD\u5DF2\u88AB\u6E05\u7406"
+      }
     };
-  } else {
-    const snap = await loadSnapshotForRecord(record);
-    if (!snap) {
-      plan = {
-        status: "unsupported",
-        auditId,
-        reason: "snapshot_missing_or_invalid",
-        record
+  }
+  const snapshot = await loadSnapshotForRecord(record);
+  const subsequentWrites = await collectSubsequentWrites(record);
+  const successfulSubsequentWriteCount = subsequentWrites.filter(
+    (w) => w.outcome === "success"
+  ).length;
+  return {
+    record,
+    snapshot,
+    resourceKey: record.resourceKey,
+    subsequentWrites,
+    successfulSubsequentWriteCount,
+    supportability: deriveSupportability(record, snapshot)
+  };
+}
+function ctxToPlanPayload(auditId, ctx) {
+  const { record, snapshot, subsequentWrites, successfulSubsequentWriteCount, supportability } = ctx;
+  const target = record ? {
+    ts: record.ts,
+    pathname: record.pathname,
+    method: record.method,
+    outcome: record.outcome,
+    commit: record.commit,
+    invokedCommand: record.invokedCommand,
+    httpStatus: record.httpStatus
+  } : null;
+  const snapshotSummary = snapshot ? (() => {
+    const bodyJson = JSON.stringify(snapshot.body);
+    return {
+      capturedAt: snapshot.capturedAt,
+      originalMethod: snapshot.originalMethod,
+      originalUrl: snapshot.originalUrl,
+      bodyUtf8Length: Buffer.byteLength(bodyJson, "utf8"),
+      bodySha256Prefix: createHash("sha256").update(bodyJson).digest("hex").slice(0, 16)
+    };
+  })() : null;
+  const steps = supportability.code === "ready_put_patch" && snapshot ? [
+    (() => {
+      const bodyJson = JSON.stringify(snapshot.body);
+      return {
+        order: 1,
+        method: snapshot.originalMethod.toUpperCase(),
+        url: snapshot.originalUrl,
+        body: snapshot.body,
+        bodyUtf8Length: Buffer.byteLength(bodyJson, "utf8"),
+        bodySha256Prefix: createHash("sha256").update(bodyJson).digest("hex").slice(0, 16)
       };
-    } else {
-      const m = snap.originalMethod.toUpperCase();
-      if (m !== "PUT" && m !== "PATCH") {
-        plan = {
-          status: "unsupported",
-          auditId,
-          reason: "restore_only_put_patch",
-          detail: m,
-          record
-        };
-      } else {
-        const bodyJson = JSON.stringify(snap.body);
-        const hash = createHash("sha256").update(bodyJson).digest("hex").slice(0, 16);
-        plan = {
-          status: "ready",
-          willMutate: false,
-          auditId,
-          record: {
-            ts: record.ts,
-            pathname: record.pathname,
-            commit: record.commit ?? "",
-            method: record.method,
-            outcome: record.outcome
-          },
-          steps: [
-            {
-              order: 1,
-              method: m,
-              url: snap.originalUrl,
-              body: snap.body,
-              bodyUtf8Length: Buffer.byteLength(bodyJson, "utf8"),
-              bodySha256Prefix: hash
-            }
-          ]
-        };
-      }
-    }
+    })()
+  ] : [];
+  return {
+    auditId,
+    resourceKey: ctx.resourceKey,
+    supportability,
+    willMutate: supportability.code === "ready_put_patch",
+    target,
+    snapshot: snapshotSummary,
+    subsequentWrites,
+    guardChecks: { ackSubsequentWrites: successfulSubsequentWriteCount },
+    steps
+  };
+}
+async function runAuditRestorePlan(opts) {
+  const auditId = opts.id?.trim() ?? "";
+  if (!auditId) {
+    console.error("\u8BF7\u4F7F\u7528 --id <auditId>");
+    process.exit(1);
   }
+  const ctx = await buildRestoreContext(auditId);
+  const plan = ctxToPlanPayload(auditId, ctx);
   const envelope = {
     auditDir: getWriteAuditRootDir(TSO_WRITE_AUDIT_NS3),
     plan
@@ -3890,15 +4000,62 @@ async function runAuditRestorePlan(opts) {
   )) {
     return;
   }
-  if (plan.status === "ready") {
-    console.log("\n\u6062\u590D\u8BA1\u5212\uFF08\u4EC5\u5C55\u793A\uFF0C\u672A\u4FEE\u6539\u7EBF\u4E0A\u8D44\u6E90\uFF09\uFF1A");
-    console.log(JSON.stringify(envelope, null, 2));
+  printPlanForHuman(envelope);
+}
+function printPlanForHuman(envelope) {
+  const { plan } = envelope;
+  console.log(`
+[restore-plan] auditDir: ${envelope.auditDir}`);
+  console.log(`auditId: ${plan.auditId}`);
+  if (plan.resourceKey) console.log(`resourceKey: ${plan.resourceKey}`);
+  console.log(`supportability: ${plan.supportability.code} \u2014\u2014 ${plan.supportability.reason}`);
+  if (plan.supportability.hint) console.log(`  hint: ${plan.supportability.hint}`);
+  if (plan.target) {
+    console.log(
+      `
+\u76EE\u6807 audit\uFF1A${plan.target.ts}  ${plan.target.method} ${plan.target.pathname}  outcome=${plan.target.outcome}` + (plan.target.commit ? `
+  commit: ${plan.target.commit}` : "")
+    );
+  }
+  if (plan.snapshot) {
+    console.log(
+      `
+\u5199\u524D\u5FEB\u7167\uFF1AcapturedAt=${plan.snapshot.capturedAt}  originalMethod=${plan.snapshot.originalMethod}
+  url: ${plan.snapshot.originalUrl}
+  body: ${plan.snapshot.bodyUtf8Length} bytes  sha256[0..16]=${plan.snapshot.bodySha256Prefix}`
+    );
+  }
+  console.log(
+    `
+\u540C\u8D44\u6E90\u540E\u7EED\u5199\uFF08target.ts \u4E4B\u540E\uFF0C\u542B\u5931\u8D25\uFF09\uFF1A${plan.subsequentWrites.length} \u6761\uFF1B\u5176\u4E2D\u6210\u529F ${plan.guardChecks.ackSubsequentWrites} \u6761`
+  );
+  if (plan.subsequentWrites.length > 0) {
+    console.log(
+      `  \u26A0\uFE0F  \u6267\u884C restore-apply \u4F1A\u628A snapshot.body \u6574\u4E2A PUT/PATCH \u56DE\u53BB\uFF0C\u6210\u529F\u7684 ${plan.guardChecks.ackSubsequentWrites} \u6761\u540E\u7EED\u5199\u4F1A\u88AB\u8986\u76D6\u3002`
+    );
+    for (const w of plan.subsequentWrites.slice(0, 10)) {
+      console.log(
+        `   - ${w.ts}  ${w.method}  outcome=${w.outcome}  auditId=${w.auditId}` + (w.commit ? `  commit=${w.commit.slice(0, 60)}` : "")
+      );
+    }
+    if (plan.subsequentWrites.length > 10) {
+      console.log(`   \u2026\u2026 \u8FD8\u6709 ${plan.subsequentWrites.length - 10} \u6761\uFF0C\u8BF7\u8FD0\u884C audit list --resource-key "${plan.resourceKey ?? ""}" --json \u67E5\u770B\u5B8C\u6574\u5386\u53F2`);
+    }
+  }
+  if (plan.steps.length > 0) {
+    console.log(`
+\u8865\u507F\u5199\u6B65\u9AA4\uFF08\u4EC5\u5C55\u793A\uFF0C\u672A\u4FEE\u6539\u7EBF\u4E0A\u8D44\u6E90\uFF09\uFF1A`);
+    console.log(JSON.stringify(plan.steps, null, 2));
     console.log(
-      '\n\u786E\u8BA4\u65E0\u8BEF\u540E\u6267\u884C\uFF1Asiluzan-tso audit restore-apply --id <\u540C\u4E0A> --i-confirm [--commit "\u2026"]\n'
+      `
+\u786E\u8BA4\u65E0\u8BEF\u540E\u6267\u884C\uFF1A
+  siluzan-tso audit restore-apply --id ${plan.auditId} --i-confirm --ack-subsequent-writes ${plan.guardChecks.ackSubsequentWrites} [--commit "\u56DE\u9000\u8BF4\u660E"]
+`
     );
   } else {
-    console.log("\n\u65E0\u6CD5\u751F\u6210\u53EF\u6267\u884C\u7684\u8865\u507F\u5199\u8BA1\u5212\uFF1A");
-    console.log(JSON.stringify(envelope, null, 2));
+    console.log(`
+\u5F53\u524D supportability=${plan.supportability.code}\uFF0C\u65E0\u53EF\u6267\u884C step\u3002
+`);
   }
 }
 async function runAuditRestoreApply(opts) {
@@ -3913,19 +4070,41 @@ async function runAuditRestoreApply(opts) {
     console.error("\u8BF7\u4F7F\u7528 --id <auditId>");
     process.exit(1);
   }
-  const record = await findWriteAuditRecordByAuditId(TSO_WRITE_AUDIT_NS3, auditId);
-  const snap = record?.preSnapshotRef ? await loadSnapshotForRecord(record) : null;
-  if (!record || record.outcome !== "success" || !snap) {
-    console.error("\n\u274C \u65E0\u6CD5\u6267\u884C\uFF1A\u8BB0\u5F55\u4E0D\u5B58\u5728\u3001\u975E\u6210\u529F\u5199\u6216\u5FEB\u7167\u4E0D\u53EF\u7528\u3002\u8BF7 audit restore-plan --id \u2026 \u67E5\u770B\u539F\u56E0\u3002\n");
+  const ctx = await buildRestoreContext(auditId);
+  if (ctx.supportability.code !== "ready_put_patch") {
+    console.error(
+      `
+\u274C \u65E0\u6CD5\u6267\u884C\uFF1Asupportability=${ctx.supportability.code}
+   \u539F\u56E0\uFF1A${ctx.supportability.reason}` + (ctx.supportability.hint ? `
+   \u5EFA\u8BAE\uFF1A${ctx.supportability.hint}` : "") + `
+   \u8BF7\u5148 siluzan-tso audit restore-plan --id ${auditId} \u67E5\u770B\u5B8C\u6574\u8BCA\u65AD\u3002
+`
+    );
     process.exit(1);
   }
-  const m = snap.originalMethod.toUpperCase();
-  if (m !== "PUT" && m !== "PATCH") {
-    console.error(`
-\u274C \u5F53\u524D\u4EC5\u652F\u6301 PUT/PATCH \u7684\u8865\u507F\u5199\uFF0C\u672C\u6761\u4E3A ${m}\u3002
-`);
+  const expected = ctx.successfulSubsequentWriteCount;
+  const ack = Number.isInteger(opts.ackSubsequentWrites) ? Number(opts.ackSubsequentWrites) : -1;
+  if (ack < 0) {
+    console.error(
+      `
+\u274C \u62D2\u7EDD\u6267\u884C\uFF1A\u5FC5\u987B\u663E\u5F0F\u786E\u8BA4\u4F1A\u88AB\u8986\u76D6\u7684"\u540C\u8D44\u6E90\u540E\u7EED\u6210\u529F\u5199"\u6570\u91CF\u3002
+   \u5F53\u524D\u626B\u63CF\u7ED3\u679C\uFF1A${expected} \u6761\uFF1B\u8BF7\u8FFD\u52A0\uFF1A--ack-subsequent-writes ${expected}
+   \u82E5\u8BE5\u6570\u91CF\u4E0D\u4E3A 0\uFF0C\u610F\u5473\u7740\u6709\u66F4\u665A\u7684\u6210\u529F\u5199\u4F1A\u88AB\u672C\u6B21\u56DE\u9000\u8986\u76D6\uFF1B\u8BF7\u5148 restore-plan \u590D\u6838\u3002
+`
+    );
     process.exit(1);
   }
+  if (ack !== expected) {
+    console.error(
+      `
+\u274C \u62D2\u7EDD\u6267\u884C\uFF1A--ack-subsequent-writes=${ack} \u4E0E\u5F53\u524D\u626B\u63CF\u7ED3\u679C ${expected} \u4E0D\u4E00\u81F4\u3002
+   \u8BF4\u660E plan \u4E0E apply \u4E4B\u95F4\u53C8\u53D1\u751F\u4E86\u65B0\u5199\uFF0C\u8BF7\u91CD\u65B0\u8FD0\u884C restore-plan \u590D\u6838\u540E\u518D apply\u3002
+`
+    );
+    process.exit(1);
+  }
+  const snap = ctx.snapshot;
+  const method = snap.originalMethod.toUpperCase();
   if (getResolvedWriteAuditCommit().trim() === "") {
     setWriteAuditCliCommit(`compensate:restore:${auditId}`);
   }
@@ -3933,15 +4112,20 @@ async function runAuditRestoreApply(opts) {
   await apiFetch2(
     snap.originalUrl,
     config,
-    { method: m, body: JSON.stringify(snap.body) },
+    { method, body: JSON.stringify(snap.body) },
     Boolean(opts.verbose)
   );
-  const out = { ok: true, auditId, message: "\u8865\u507F\u5199\u5DF2\u63D0\u4EA4\uFF08\u5E76\u8BB0\u5165\u65B0\u7684\u5BA1\u8BA1\u884C\uFF09\u3002" };
+  const out = {
+    ok: true,
+    auditId,
+    overwrittenSubsequentSuccessfulWrites: expected,
+    message: "\u8865\u507F\u5199\u5DF2\u63D0\u4EA4\uFF08\u5E76\u8BB0\u5165\u65B0\u7684\u5BA1\u8BA1\u884C\uFF09\u3002"
+  };
   if (opts.json) {
     console.log(JSON.stringify(out, null, 2));
   } else {
     console.log(`
-${out.message}
+${out.message}\uFF08\u5DF2\u8986\u76D6 ${expected} \u6761\u540E\u7EED\u6210\u529F\u5199\uFF09
 `);
   }
 }
@@ -14103,7 +14287,11 @@ auditCmd.command("list").description("\u5217\u51FA\u6700\u8FD1 N \u4E2A\u5317\u4
   "--json-out <path>",
   "\u843D\u76D8\uFF08\u76EE\u5F55\u6216 *.json \u6587\u4EF6\u8DEF\u5F84\uFF09\u5E76\u66F4\u65B0 cli-manifest.json\uFF08\u4E0E --json \u4E92\u65A5\uFF09\uFF1Bstdout \u4E00\u884C\u6458\u8981 JSON\uFF0C\u542B outlineFile\uFF08TS \u5F0F\u7C7B\u578B\u5728 `*.outline.txt`\uFF09",
   void 0
-).option("--failures-only", "\u4EC5\u5931\u8D25\u8BB0\u5F55", false).option("--match <sub>", "\u5B50\u4E32\u5339\u914D commit/pathname/cmd/url/auditId/runId\uFF08\u626B JSONL\uFF09", void 0).option("--method <verb>", "HTTP \u65B9\u6CD5\u8FC7\u6EE4\uFF0C\u5982 PUT\u3001POST", void 0).option("--outcome <success|failure>", "\u6309\u7ED3\u679C\u8FC7\u6EE4", void 0).option("--run-id <id>", "\u6309 runId \u5B50\u4E32\u8FC7\u6EE4\uFF08\u73AF\u5883\u53D8\u91CF SILUZAN_AUDIT_RUN_ID \u5199\u5165\u7684\u8BB0\u5F55\uFF09", void 0).option("--since-ts <iso>", "\u4EC5 ts \u4E0D\u65E9\u4E8E\u8BE5 ISO \u65F6\u95F4\uFF08\u5728 --days \u7A97\u53E3\u5185\u518D\u7B5B\uFF09", void 0).action(
+).option("--failures-only", "\u4EC5\u5931\u8D25\u8BB0\u5F55", false).option("--match <sub>", "\u5B50\u4E32\u5339\u914D commit/pathname/cmd/url/auditId/runId\uFF08\u626B JSONL\uFF09", void 0).option("--method <verb>", "HTTP \u65B9\u6CD5\u8FC7\u6EE4\uFF0C\u5982 PUT\u3001POST", void 0).option("--outcome <success|failure>", "\u6309\u7ED3\u679C\u8FC7\u6EE4", void 0).option("--run-id <id>", "\u6309 runId \u5B50\u4E32\u8FC7\u6EE4\uFF08\u73AF\u5883\u53D8\u91CF SILUZAN_AUDIT_RUN_ID \u5199\u5165\u7684\u8BB0\u5F55\uFF09", void 0).option("--since-ts <iso>", "\u4EC5 ts \u4E0D\u65E9\u4E8E\u8BE5 ISO \u65F6\u95F4\uFF08\u5728 --days \u7A97\u53E3\u5185\u518D\u7B5B\uFF09", void 0).option(
+  "--resource-key <key>",
+  "\u7CBE\u786E\u5339\u914D resourceKey\uFF08host+pathname\uFF09\uFF0C\u7528\u4E8E restore-plan \u914D\u5957\u8FFD\u6EAF\u540C\u8D44\u6E90\u5168\u91CF\u5386\u53F2",
+  void 0
+).action(
   async (opts) => {
     await runAuditList({
       days: opts.days,
@@ -14114,7 +14302,8 @@ auditCmd.command("list").description("\u5217\u51FA\u6700\u8FD1 N \u4E2A\u5317\u4
       method: opts.method,
       outcome: opts.outcome,
       runId: opts.runId,
-      sinceTs: opts.sinceTs
+      sinceTs: opts.sinceTs,
+      resourceKey: opts.resourceKey
     });
   }
 );
@@ -14128,11 +14317,18 @@ auditCmd.command("show").description("\u6309 auditId \u5C55\u793A\u5355\u6761\u5
 auditCmd.command("restore-plan").description("\u6839\u636E\u5BA1\u8BA1 + \u5199\u524D\u5FEB\u7167\u751F\u6210\u8865\u507F\u5199\u8BA1\u5212\uFF08\u53EA\u8BFB\uFF0C\u4E0D\u8C03\u7528\u4E1A\u52A1\u63A5\u53E3\uFF09").requiredOption("--id <auditId>", "\u76EE\u6807\u5BA1\u8BA1 auditId").option("--json", "\u8F93\u51FA JSON", false).option("--json-out <path>", "\u843D\u76D8\uFF08\u4E0E --json \u4E92\u65A5\uFF09", void 0).action(async (opts) => {
   await runAuditRestorePlan({ id: opts.id, json: Boolean(opts.json), jsonOut: opts.jsonOut });
 });
-auditCmd.command("restore-apply").description("\u6267\u884C\u8865\u507F\u5199\uFF08\u5C06\u8D44\u6E90\u5199\u56DE\u5FEB\u7167\u4E2D\u7684\u72B6\u6001\uFF09\uFF1B\u987B\u5148 restore-plan \u5E76\u7ECF --i-confirm").requiredOption("--id <auditId>", "\u76EE\u6807\u5BA1\u8BA1 auditId").option("--i-confirm", "\u786E\u8BA4\u5DF2\u9605\u8BFB restore-plan \u5E76\u540C\u610F\u6267\u884C", false).option("-t, --token <token>", "JWT\uFF08\u53EF\u9009\uFF0C\u4E0E\u5168\u5C40\u4E00\u81F4\uFF09", void 0).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF", false).option("--json", "stdout \u4EC5\u8F93\u51FA JSON", false).action(
+auditCmd.command("restore-apply").description(
+  "\u6267\u884C\u8865\u507F\u5199\uFF08\u5C06\u8D44\u6E90\u5199\u56DE\u5FEB\u7167\u4E2D\u7684\u72B6\u6001\uFF09\uFF1B\u987B\u5148 restore-plan\uFF0C\u5E76\u7ECF --i-confirm + --ack-subsequent-writes \u5B88\u536B"
+).requiredOption("--id <auditId>", "\u76EE\u6807\u5BA1\u8BA1 auditId").option("--i-confirm", "\u786E\u8BA4\u5DF2\u9605\u8BFB restore-plan \u5E76\u540C\u610F\u6267\u884C", false).option(
+  "--ack-subsequent-writes <n>",
+  "\u663E\u5F0F\u786E\u8BA4\u4F1A\u88AB\u672C\u6B21\u56DE\u9000\u8986\u76D6\u7684\u540C resourceKey \u540E\u7EED\u6210\u529F\u5199\u6570\u91CF\uFF1B\u5FC5\u987B\u7B49\u4E8E restore-plan.guardChecks.ackSubsequentWrites",
+  (v) => Number.parseInt(v, 10)
+).option("-t, --token <token>", "JWT\uFF08\u53EF\u9009\uFF0C\u4E0E\u5168\u5C40\u4E00\u81F4\uFF09", void 0).option("--verbose", "\u8BE6\u7EC6\u9519\u8BEF", false).option("--json", "stdout \u4EC5\u8F93\u51FA JSON", false).action(
   async (opts) => {
     await runAuditRestoreApply({
       id: opts.id,
       iConfirm: Boolean(opts.iConfirm),
+      ackSubsequentWrites: opts.ackSubsequentWrites,
       token: opts.token,
       verbose: Boolean(opts.verbose),
       json: Boolean(opts.json)

package/dist/skill/SKILL.md

@@ -67,6 +67,8 @@ allowed-tools: Bash(siluzan-tso:*) Read Write
 
 ---
 
+`--commit` 所有的写/修改命令都会有commit字段，请你填写修改前，修改后的值。方便后期出问题时排查或恢复
+
 ## 职责划分
 
 **定位**：`siluzan-tso` + 本 Skill 提供 **可组合的读能力（检查项）** 与 **可验证的写能力（最终操作）**；**不负责**在进程内长期驻留、定时轮询、复合条件规则引擎、或替代宿主的通知渠道。

package/dist/skill/_meta.json

@@ -1,5 +1,5 @@
 {
   "slug": "siluzan-tso",
-  "version": "1.1.15-beta.1",
-  "publishedAt": 1777539704629
+  "version": "1.1.15-beta.2",
+  "publishedAt": 1778032713167
 }

package/dist/skill/references/write-audit-restore.md

@@ -4,6 +4,7 @@
 
 - **补偿写**：再次调用写接口，把资源字段写回「写前快照」中的状态；**不是**数据库或平台的事务回滚 API。
 - **真值在磁盘**：检索与定位一律通过 `siluzan-tso audit list` / `audit show` 读 `~/.siluzan/write-audit/tso/*.jsonl`，**不要**依赖对话中的历史列表。
+- **resourceKey**：写审计在变异请求时由 `host+pathname` 派生，**同一资源的多次写共享同一 key**——`restore-plan` 据此扫描"目标 audit 之后该资源还有哪些写"，让你看见回退会顺带覆盖什么。
 
 ## 写操作必填 commit
 
@@ -11,10 +12,9 @@
 
 - 命令行：`--commit "说明"`（可出现在任意位置，与 `grep` 解析一致）
 
-
 二者同时存在时 **命令行优先**。缺省则 CLI **stderr 报错并退出**，不发起 HTTP。
 
-`audit list`、`audit show`、`audit restore-plan` 不产生业务写，不要求 commit。`audit restore-apply` 须加 `--i-confirm`；若仍未传 commit，会自动使用 `compensate:restore:<auditId>` 作为本条补偿写的说明。
+`audit list`、`audit show`、`audit restore-plan` 不产生业务写，不要求 commit。`audit restore-apply` 须加 `--i-confirm` 与 `--ack-subsequent-writes`；若仍未传 commit，会自动使用 `compensate:restore:<auditId>` 作为本条补偿写的说明。
 
 ## 可选 runId
 
@@ -22,17 +22,80 @@
 
 ## 写前快照（白名单）
 
-仅对部分 **Google 网关 `SemManagement` 的 PUT/PATCH** 在写前自动 `GET` 同 URL（去 query），快照存于 `write-audit/tso/snapshots/<auditId>.json`，审计行含 `preSnapshotRef`。超限或 GET 失败时记 `preSnapshotSkipped`，不阻断主请求。
-
-## 补偿写流程（Agent / 人类）
-
-1. `siluzan-tso audit list --days 14 --match "关键词" --json`（或 `--match` 用 auditId 片段）
-2. `siluzan-tso audit show --id <auditId> --json` 确认 `preSnapshotFileReadable`
-3. `siluzan-tso audit restore-plan --id <auditId> --json`，检查 `plan.status === "ready"`
-4. 人类确认后：`siluzan-tso audit restore-apply --id <auditId> --i-confirm [--commit "人工备注"]`
-
-**禁止**跳过 `restore-plan` 直接 `restore-apply`。**禁止**根据 `commit` 文本编造请求体；**必须以** `restore-plan` 输出的 `steps[].body` 为准。
+仅当 PUT/PATCH 命中以下 **Google 广告网关** 路径时，CLI 会在写前自动 `GET` 同 URL（去 query），快照存于 `write-audit/tso/snapshots/<auditId>.json`，审计行含 `preSnapshotRef`：
+
+1. `/SemManagement/...` —— 历史在用的优化/系列侧接口
+2. `/campaignmanagement/campaign/{accountId}/{campaignId}` —— 广告系列单资源详情（`ad campaign-status / campaign-delete / campaign-edit` 走这里）
+
+未命中时审计行只有 `preSnapshotSkipped`、不会阻断主请求；`restore-plan` 也会返回 `supportability.code = "no_snapshot"` 并给出"人工反向写"的 hint。
+
+明确**未纳入**白名单的资源（业务代码绕开了"单资源 GET"，要么端点不可靠、要么 GET shape 与 PUT body 不对齐——盲目 apply 会写错形状）：
+
+- `/adgroupnmanagement/adgroup/{acc}/{id}`（业务走 list + filter）
+- `/admanagement/campaign/{acc}/{adId}`（业务走 list + filter）
+- `/keywordmanagement/Keyword/{acc}/batch`（批量 PUT，body 是数组）
+- `/negativekeywordmanagement/negativekeyword/{acc}/{id}`（业务走 list + filter）
+- `/campaignmanagement/` 下的 `v2/list/...`、`v2/(targeted|excluded)locations/...`、`criterion/...`、`geolocations/...`
+
+POST 创建型与 DELETE 删除型 **整体**不在快照白名单内，`restore-plan` 会给出 `unsupported_method_post` / `unsupported_method_delete` 的明确诊断与下一步建议。
+
+## restore-plan 输出结构（Agent 决策依据）
+
+```jsonc
+{
+  "auditDir": "...",
+  "plan": {
+    "auditId": "...",
+    "resourceKey": "googleapi.mysiluzan.com/SemManagement/...",
+    "supportability": {
+      "code": "ready_put_patch | audit_not_found | v1_record_no_audit_id | not_success_write | no_snapshot | snapshot_missing_or_invalid | unsupported_method_post | unsupported_method_delete | unsupported_method_other",
+      "reason": "一句话原因",
+      "hint": "仅 unsupported 时给出的人/Agent 下一步建议"
+    },
+    "willMutate": true,
+    "target": { "ts": "...", "method": "PUT", "pathname": "...", "outcome": "success", "commit": "...", "invokedCommand": "...", "httpStatus": 200 },
+    "snapshot": { "capturedAt": "...", "originalMethod": "PUT", "originalUrl": "...", "bodyUtf8Length": 1234, "bodySha256Prefix": "..." },
+    "subsequentWrites": [
+      { "auditId": "...", "ts": "...", "method": "PUT", "outcome": "success", "pathname": "...", "commit": "...", "hasSnapshot": true }
+    ],
+    "guardChecks": { "ackSubsequentWrites": 0 },
+    "steps": [{ "order": 1, "method": "PUT", "url": "...", "body": { /* snapshot.body */ }, "bodyUtf8Length": 1234, "bodySha256Prefix": "..." }]
+  }
+}
+```
+
+要点：
+
+- `supportability.code` 是分流路标，Agent 必须据此判断是否进入 apply 分支。
+- `subsequentWrites` 列出 **同 resourceKey、ts > target.ts** 的全部写（成功+失败）。`guardChecks.ackSubsequentWrites` 则是其中**成功**的数量——`restore-apply` 会要求显式确认。
+- `steps` 仅在 `supportability.code === "ready_put_patch"` 时非空，单步 PUT/PATCH 重放 `snapshot.body`。
+
+## restore-apply 守卫
+
+```
+siluzan-tso audit restore-apply \
+  --id <auditId> \
+  --i-confirm \
+  --ack-subsequent-writes <plan.guardChecks.ackSubsequentWrites>
+```
+
+- `--i-confirm`：人/Agent 已读 plan，承担覆盖风险。
+- `--ack-subsequent-writes <N>`：必须等于 plan 显示的成功后续写数量。**apply 时会再 build 一次上下文**：如果 N 与最新扫描结果不一致（说明 plan→apply 期间又发生了新写），CLI 会拒绝执行——这是防 TOCTOU 的关键守卫。
+
+## 自主回退工作流（Agent / 人类）
+
+1. **定位 audit**：`siluzan-tso audit list --days 14 --match "关键词" --json`。
+2. **看完整审计行**：`siluzan-tso audit show --id <auditId> --json`，确认 `preSnapshotFileReadable === true`。
+3. **生成回退计划**：`siluzan-tso audit restore-plan --id <auditId> --json`。
+   - 检查 `plan.supportability.code === "ready_put_patch"`。
+   - **必读** `plan.subsequentWrites`：若存在成功的后续写，意味着回退会覆盖那些更晚的修改；按需可先用 `siluzan-tso audit list --resource-key "<plan.resourceKey>" --json` 把同资源全量历史拉出来交叉确认。
+   - 决定是接受这个覆盖，还是放弃回退/换另一种修复路径。
+4. **执行**：`siluzan-tso audit restore-apply --id <auditId> --i-confirm --ack-subsequent-writes <N>`，N 来自 plan.guardChecks.ackSubsequentWrites。
+
+**禁止**跳过 `restore-plan` 直接 `restore-apply`。
+**禁止**根据 `commit` 文本编造请求体；**必须以** `restore-plan` 输出的 `steps[].body` 为准。
+**禁止**在 `subsequentWrites` 非空且未与用户确认的情况下，盲目用 plan 中的数字 ack 后强行 apply。
 
 ## v1 历史审计
 
-旧版 JSONL 无 `auditId`/`commit`/`preSnapshotRef`，无法使用 `restore-plan` / `restore-apply`。
+旧版 JSONL 无 `auditId`/`commit`/`preSnapshotRef`，`restore-plan` 会返回 `supportability.code === "v1_record_no_audit_id"` / `audit_not_found`，无法 `restore-apply`，仅可作 `audit show` 参考。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siluzan-tso-cli",
-  "version": "1.1.15-beta.1",
+  "version": "1.1.15-beta.2",
   "description": "Siluzan 广告账户管理 CLI — 查询账户、余额、消耗数据，管理绑定关系与充值。",
   "keywords": [
     "ad-account",