@deployxai/dxc 0.1.7 → 0.1.8

package/dist/index.js

@@ -6,7 +6,7 @@ import {
 import {
   SourceCli,
   SourceCliError
-} from "./chunks/chunk-NAL5UOUZ.js";
+} from "./chunks/chunk-QPHUHGHV.js";
 import {
   CONTENT_ARTIFACT_KINDS,
   CONTENT_STAGE_INPUTS,
@@ -81,7 +81,7 @@ import {
   wechatRenderResultSchema,
   writePrivateBuffer,
   writePrivateJson
-} from "./chunks/chunk-N4CMLINP.js";
+} from "./chunks/chunk-UQRFCGHR.js";
 
 // node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/dist/nodes/identity.js
 var require_identity = __commonJS({
@@ -23295,7 +23295,7 @@ import os3 from "node:os";
 // apps/cli/package.json
 var package_default = {
   name: "@dxc/cli",
-  version: "0.1.7",
+  version: "0.1.8",
   private: true,
   type: "module",
   bin: {
@@ -27207,13 +27207,13 @@ var ContentMemoryCli = class {
 // apps/cli/src/project.ts
 import { createHash as createHash4, randomUUID as randomUUID3 } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { lstat as lstat2, mkdir, readFile as readFile3, rename as rename3, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
+import { lstat as lstat3, mkdir, readFile as readFile3, rename as rename3, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
 import path4 from "node:path";
 
 // apps/cli/src/stage-artifact.ts
 import { createHash as createHash3, randomUUID as randomUUID2 } from "node:crypto";
 import { constants as fileConstants } from "node:fs";
-import { open, readFile as readFile2, rename as rename2, unlink, writeFile } from "node:fs/promises";
+import { lstat as lstat2, open, readFile as readFile2, rename as rename2, unlink, writeFile } from "node:fs/promises";
 import path3 from "node:path";
 
 // packages/renderer-wechat/src/article.ts
@@ -29338,10 +29338,26 @@ var StageArtifactValidationError = class extends Error {
   issues;
 };
 function issuePaths2(issues) {
-  return issues.map((issue) => {
-    const location = issue.path.map(String).join(".");
-    return location.length === 0 ? issue.message : location;
-  });
+  const flattened = issues.flatMap(
+    (issue) => issue.code === "invalid_union" && issue.errors !== void 0 ? [...issue.errors].sort((left, right) => left.length - right.length)[0] ?? [] : [issue]
+  );
+  return [
+    ...new Set(
+      flattened.map((issue) => {
+        const location = issue.path.map(String).join(".");
+        if (location === "coverSource" || /^inlineAssets\.\d+\.source$/u.test(location)) {
+          return `${location}: \u4EC5\u5141\u8BB8 agent-generated\uFF08\u672C\u6B21\u7531 Agent \u751F\u6210\uFF09\u6216 local-material\uFF08\u7528\u6237\u63D0\u4F9B\u7684\u672C\u5730\u7D20\u6750\uFF09\uFF1BSVG \u6216\u56FE\u8868\u7ECF\u5BFC\u51FA\u4E3A PNG/JPEG \u540E\uFF0C\u6309\u771F\u5B9E\u6765\u6E90\u9009\u62E9\u5176\u4E2D\u4E00\u4E2A\u503C`;
+        }
+        if (issue.code === "unrecognized_keys" && issue.keys?.includes("planned")) {
+          return "planned: \u8BE5\u5B57\u6BB5\u4E0D\u5C5E\u4E8E\u5DF2\u5B8C\u6210\u89C6\u89C9\u4EA7\u7269\uFF1Bplanned=true \u53EA\u80FD\u4F7F\u7528\u751F\u6210\u524D\u6388\u6743\u5951\u7EA6\uFF0C\u751F\u6210\u7ED3\u675F\u540E\u5FC5\u987B\u79FB\u9664";
+        }
+        if (location === "generation") {
+          return "generation: planned=true \u65F6\u5FC5\u987B\u58F0\u660E executionLocation\u3001dataTransit\u3001chargesQuota\u3001maxAttempts \u548C plannedAssets\uFF0C\u5E76\u8D70\u751F\u6210\u524D\u6388\u6743\u5951\u7EA6";
+        }
+        return location.length === 0 ? issue.message : `${location}: ${issue.message}`;
+      })
+    )
+  ];
 }
 function insideProject(directory, relativePath) {
   const target = path3.resolve(directory, relativePath);
@@ -29351,11 +29367,16 @@ function insideProject(directory, relativePath) {
   }
   return target;
 }
-async function readRegularFile(target, maximumBytes) {
+async function readRegularFile(target, maximumBytes, imageRole) {
   let handle;
   try {
     handle = await open(target, fileConstants.O_RDONLY | fileConstants.O_NOFOLLOW);
     const metadata = await handle.stat();
+    if (metadata.isFile() && metadata.size > maximumBytes && imageRole !== void 0) {
+      throw new StageArtifactValidationError([
+        imageRole === "inline-image" ? `${path3.basename(target)} \u662F\u6B63\u6587\u56FE\u7247\uFF0C\u5B9E\u9645 ${metadata.size} bytes\uFF0C\u5FC5\u987B\u5C0F\u4E8E 1048576 bytes\uFF1B\u8BF7\u5BFC\u51FA JPEG \u6216\u964D\u4F4E\u5C3A\u5BF8/\u8D28\u91CF\u540E\u66F4\u65B0\u89C6\u89C9\u8BA1\u5212` : `${path3.basename(target)} \u662F\u5C01\u9762\uFF0C\u5B9E\u9645 ${metadata.size} bytes\uFF0C\u4E0A\u9650 ${maximumBytes} bytes\uFF1B\u8BF7\u964D\u4F4E\u5C3A\u5BF8\u6216\u8D28\u91CF\u540E\u66F4\u65B0\u89C6\u89C9\u8BA1\u5212`
+      ]);
+    }
     if (!metadata.isFile() || metadata.size <= 0 || metadata.size > maximumBytes) {
       throw new StageArtifactValidationError([path3.basename(target)]);
     }
@@ -29385,8 +29406,12 @@ function isSupportedImage(bytes, filePath) {
 function isInsideDirectory(filePath, directory) {
   return filePath.startsWith(`${directory}/`);
 }
-async function validateImageAsset(directory, logicalPath, expectedSha256, maximumBytes) {
-  const bytes = await readRegularFile(insideProject(directory, logicalPath), maximumBytes);
+async function validateImageAsset(directory, logicalPath, expectedSha256, maximumBytes, imageRole) {
+  const bytes = await readRegularFile(
+    insideProject(directory, logicalPath),
+    maximumBytes,
+    imageRole
+  );
   if (!isSupportedImage(bytes, logicalPath)) {
     throw new StageArtifactValidationError([`${logicalPath} \u4E0D\u662F\u771F\u5B9E PNG/JPEG \u6587\u4EF6`]);
   }
@@ -29468,6 +29493,30 @@ async function writeAtomically(target, bytes) {
     throw error;
   }
 }
+async function captureFile(target, logicalPath) {
+  try {
+    const metadata = await lstat2(target);
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+      throw new StageArtifactValidationError([path3.basename(target)]);
+    }
+    return { bytes: await readFile2(target), logicalPath, target };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { logicalPath, target };
+    }
+    throw error;
+  }
+}
+async function assertFileUnchanged(candidate) {
+  const current = await captureFile(candidate.target, candidate.logicalPath);
+  const beforeHash = candidate.bytes === void 0 ? null : sha256(candidate.bytes);
+  const currentHash = current.bytes === void 0 ? null : sha256(current.bytes);
+  if (beforeHash !== currentHash) {
+    throw new StageArtifactValidationError([
+      `NORMALIZATION_CONFLICT: ${candidate.logicalPath} \u5728\u6821\u9A8C\u671F\u95F4\u88AB\u5176\u4ED6\u8FDB\u7A0B\u4FEE\u6539\uFF1BCLI \u672A\u8986\u76D6\u8BE5\u6587\u4EF6\uFF0C\u8BF7\u91CD\u65B0\u8BFB\u53D6\u540E\u91CD\u8BD5`
+    ]);
+  }
+}
 async function bindDeliveryApprovalArtifact(options) {
   const source = (await readRegularFile(options.target, MAXIMUM_ARTIFACT_BYTES)).toString("utf8");
   const frontmatter = parseFrontmatter2(source);
@@ -29500,19 +29549,35 @@ ${frontmatter.body}
 `
   );
 }
+async function readDeliveryDraftIdentity(target) {
+  const source = (await readRegularFile(target, MAXIMUM_ARTIFACT_BYTES)).toString("utf8");
+  const parsed = deliveryStageArtifactFrontmatterSchema.safeParse(parseFrontmatter2(source).value);
+  if (!parsed.success) {
+    throw new StageArtifactValidationError(issuePaths2(parsed.error.issues));
+  }
+  return {
+    accountId: parsed.data.accountId,
+    idempotencyKey: parsed.data.idempotencyKey,
+    rootSnapshotHash: parsed.data.rootSnapshotHash,
+    rootSnapshotId: parsed.data.rootSnapshotId
+  };
+}
 async function normalizeGoldenLines(directory, body, logicalPath) {
   const target = insideProject(directory, logicalPath);
+  const snapshot = await captureFile(target, logicalPath);
   let parsed;
   try {
-    const bytes2 = await readFile2(target);
-    if (bytes2.length === 0 || bytes2.length > 64 * 1024) {
-      throw new StageArtifactValidationError([`${logicalPath} \u4E0D\u662F\u5408\u6CD5\u91D1\u53E5\u4EA4\u63A5\u6587\u4EF6`]);
+    const bytes2 = snapshot.bytes;
+    if (bytes2 === void 0) {
+      parsed = { lines: [], schemaVersion: "dxc-golden-lines@1" };
+    } else {
+      if (bytes2.length === 0 || bytes2.length > 64 * 1024) {
+        throw new StageArtifactValidationError([`${logicalPath} \u4E0D\u662F\u5408\u6CD5\u91D1\u53E5\u4EA4\u63A5\u6587\u4EF6`]);
+      }
+      parsed = JSON.parse(bytes2.toString("utf8"));
     }
-    parsed = JSON.parse(bytes2.toString("utf8"));
   } catch (error) {
-    if (error.code === "ENOENT") {
-      parsed = { lines: [], schemaVersion: "dxc-golden-lines@1" };
-    } else if (error instanceof StageArtifactValidationError) {
+    if (error instanceof StageArtifactValidationError) {
       throw error;
     } else {
       throw new StageArtifactValidationError([`${logicalPath} \u4E0D\u662F\u5408\u6CD5\u91D1\u53E5\u4EA4\u63A5\u6587\u4EF6`]);
@@ -29531,16 +29596,17 @@ async function normalizeGoldenLines(directory, body, logicalPath) {
   };
   const bytes = Buffer.from(`${JSON.stringify(normalized, void 0, 2)}
 `, "utf8");
-  await writeAtomically(target, bytes);
-  return sha256(bytes);
+  return { bytes, snapshot };
 }
 async function normalizeStageArtifact(options) {
   const artifactPath = options.manifest.artifacts[options.stage];
   const target = insideProject(options.directory, artifactPath);
-  const source = (await readRegularFile(
-    target,
-    options.stage === "article" ? MAXIMUM_ARTICLE_BYTES : MAXIMUM_ARTIFACT_BYTES
-  )).toString("utf8");
+  const sourceSnapshot = await captureFile(target, artifactPath);
+  const maximumBytes = options.stage === "article" ? MAXIMUM_ARTICLE_BYTES : MAXIMUM_ARTIFACT_BYTES;
+  if (sourceSnapshot.bytes === void 0 || sourceSnapshot.bytes.length === 0 || sourceSnapshot.bytes.length > maximumBytes) {
+    throw new StageArtifactValidationError([path3.basename(target)]);
+  }
+  const source = sourceSnapshot.bytes.toString("utf8");
   const frontmatter = parseFrontmatter2(source);
   const value = recordValue(frontmatter.value);
   if (value === void 0) {
@@ -29549,6 +29615,8 @@ async function normalizeStageArtifact(options) {
   const previousDxc = recordValue(value["dxc"]) ?? {};
   const nextValue = { ...value };
   const rootQuoteSnapshots = nextValue["quoteSnapshots"];
+  const candidateFiles = [];
+  const sidecars = /* @__PURE__ */ new Map();
   delete nextValue["quoteSnapshots"];
   nextValue["dxc"] = {
     artifactStatus: options.artifactStatus,
@@ -29603,11 +29671,14 @@ async function normalizeStageArtifact(options) {
     const defaultGoldenLinesPath = artifactPath.replace(/\.md$/iu, ".golden-lines.json");
     const goldenLinesPath = typeof nextValue["goldenLinesPath"] === "string" && nextValue["goldenLinesPath"].trim().length > 0 ? nextValue["goldenLinesPath"].trim() : defaultGoldenLinesPath;
     nextValue["goldenLinesPath"] = goldenLinesPath;
-    nextValue["goldenLinesSha256"] = await normalizeGoldenLines(
+    const goldenLines = await normalizeGoldenLines(
       options.directory,
       frontmatter.body,
       goldenLinesPath
     );
+    nextValue["goldenLinesSha256"] = sha256(goldenLines.bytes);
+    sidecars.set(goldenLinesPath, goldenLines.bytes);
+    candidateFiles.push({ ...goldenLines.snapshot, afterBytes: goldenLines.bytes });
   }
   if (options.stage === "titles") {
     const articleInput = options.inputs.find((input) => input.kind === "article");
@@ -29618,16 +29689,20 @@ async function normalizeStageArtifact(options) {
   if (options.stage === "visual-plan") {
     nextValue["assetsDirectory"] ??= options.manifest.assetsDirectory;
     nextValue["inlineImagesSupported"] ??= true;
-    nextValue["inlineAssets"] ??= [];
-    if (typeof nextValue["coverAsset"] === "string") {
+    const isGenerationProposal = nextValue["planned"] === true;
+    if (!isGenerationProposal) {
+      nextValue["inlineAssets"] ??= [];
+    }
+    if (!isGenerationProposal && typeof nextValue["coverAsset"] === "string") {
       nextValue["coverSha256"] = sha256(
         await readRegularFile(
           insideProject(options.directory, nextValue["coverAsset"]),
-          MAXIMUM_COVER_BYTES
+          MAXIMUM_COVER_BYTES,
+          "cover"
         )
       );
     }
-    if (Array.isArray(nextValue["inlineAssets"])) {
+    if (!isGenerationProposal && Array.isArray(nextValue["inlineAssets"])) {
       nextValue["inlineAssets"] = await Promise.all(
         nextValue["inlineAssets"].map(async (asset) => {
           const value2 = recordValue(asset);
@@ -29639,7 +29714,8 @@ async function normalizeStageArtifact(options) {
             sha256: sha256(
               await readRegularFile(
                 insideProject(options.directory, value2["path"]),
-                MAXIMUM_INLINE_IMAGE_BYTES
+                MAXIMUM_INLINE_IMAGE_BYTES,
+                "inline-image"
               )
             )
           };
@@ -29691,12 +29767,58 @@ ${(0, import_yaml2.stringify)(nextValue, { lineWidth: 0 }).trimEnd()}
 
 ${frontmatter.body}
 `;
-  if (normalizedSource !== source) {
-    await writeAtomically(target, normalizedSource);
-  }
+  const normalizedBytes = Buffer.from(normalizedSource, "utf8");
+  candidateFiles.push({ ...sourceSnapshot, afterBytes: normalizedBytes });
+  const changedFiles = candidateFiles.filter(
+    (candidate) => candidate.bytes === void 0 || !candidate.bytes.equals(candidate.afterBytes)
+  );
+  let committedFiles = [];
+  const rollbackCommitted = async () => {
+    for (const candidate of [...committedFiles].reverse()) {
+      const current = await captureFile(candidate.target, candidate.logicalPath);
+      if (current.bytes === void 0 || sha256(current.bytes) !== sha256(candidate.afterBytes)) {
+        continue;
+      }
+      if (candidate.bytes === void 0) {
+        await unlink(candidate.target);
+      } else {
+        await writeAtomically(candidate.target, candidate.bytes);
+      }
+    }
+    committedFiles = [];
+  };
+  return {
+    artifact: {
+      bytes: normalizedBytes.length,
+      path: artifactPath,
+      sha256: sha256(normalizedBytes)
+    },
+    candidate: { sidecars, source: normalizedSource },
+    commit: async () => {
+      for (const candidate of candidateFiles) {
+        await assertFileUnchanged(candidate);
+      }
+      try {
+        for (const candidate of changedFiles) {
+          await assertFileUnchanged(candidate);
+          await writeAtomically(candidate.target, candidate.afterBytes);
+          committedFiles.push(candidate);
+        }
+      } catch (error) {
+        await rollbackCommitted();
+        throw error;
+      }
+    },
+    mutations: changedFiles.map((candidate) => ({
+      afterSha256: sha256(candidate.afterBytes),
+      beforeSha256: candidate.bytes === void 0 ? null : sha256(candidate.bytes),
+      path: candidate.logicalPath
+    })),
+    rollbackCommitted
+  };
 }
-async function validateGoldenLinesSidecar(directory, articleBody, logicalPath, expectedSha256) {
-  const bytes = await readRegularFile(insideProject(directory, logicalPath), 64 * 1024);
+async function validateGoldenLinesSidecar(directory, articleBody, logicalPath, expectedSha256, candidateBytes) {
+  const bytes = candidateBytes ?? await readRegularFile(insideProject(directory, logicalPath), 64 * 1024);
   if (sha256(bytes) !== expectedSha256) {
     throw new StageArtifactValidationError([`${logicalPath} \u54C8\u5E0C\u4E0D\u4E00\u81F4`]);
   }
@@ -29729,13 +29851,27 @@ function compareInputs(declared, actual) {
   }
   return issues;
 }
+function bindConfirmationInputs(contentHash, inputs) {
+  return sha256(
+    Buffer.from(
+      JSON.stringify({
+        contentHash,
+        inputs: inputs.map((input) => ({
+          kind: input.kind,
+          path: input.path,
+          sha256: input.sha256 ?? null
+        }))
+      }),
+      "utf8"
+    )
+  );
+}
 async function validateStageArtifact(options) {
   const artifactPath = options.manifest.artifacts[options.stage];
-  const bytes = await readRegularFile(
+  const source = options.candidate?.source ?? (await readRegularFile(
     insideProject(options.directory, artifactPath),
     options.stage === "article" ? MAXIMUM_ARTICLE_BYTES : MAXIMUM_ARTIFACT_BYTES
-  );
-  const source = bytes.toString("utf8");
+  )).toString("utf8");
   const frontmatter = parseFrontmatter2(source);
   const parsed = contentStageArtifactFrontmatterSchema(options.stage).safeParse(frontmatter.value);
   if (!parsed.success) {
@@ -29775,7 +29911,8 @@ async function validateStageArtifact(options) {
         options.directory,
         frontmatter.body,
         article.goldenLinesPath,
-        article.goldenLinesSha256
+        article.goldenLinesSha256,
+        options.candidate?.sidecars.get(article.goldenLinesPath)
       );
     }
   }
@@ -29812,6 +29949,39 @@ async function validateStageArtifact(options) {
   }
   if (options.stage === "visual-plan") {
     const visual = visualPlanStageArtifactFrontmatterSchema.parse(frontmatter.value);
+    if (!("coverAsset" in visual)) {
+      if (options.checkpointStatus !== "awaiting-user") {
+        throw new StageArtifactValidationError([
+          "planned: \u751F\u6210\u8BA1\u5212\u53EA\u80FD\u7528\u4E8E\u7B49\u5F85\u56FE\u7247\u751F\u6210\u6388\u6743\uFF0C\u4E0D\u80FD\u4F5C\u4E3A\u5DF2\u5B8C\u6210\u89C6\u89C9\u4EA7\u7269"
+        ]);
+      }
+      const semanticFrontmatter2 = { ...visual };
+      delete semanticFrontmatter2["dxc"];
+      const legacyConfirmationSnapshotHash2 = sha256(
+        Buffer.from(
+          JSON.stringify({ body: frontmatter.body, frontmatter: semanticFrontmatter2 }),
+          "utf8"
+        )
+      );
+      return {
+        artifactPhase: "generation-proposal",
+        authorizationPlan: {
+          ...visual.generation,
+          plannedAssets: visual.generation.plannedAssets.map((asset) => ({
+            purpose: asset.purpose,
+            role: asset.role,
+            source: asset.source,
+            ...asset.placementAnchor === void 0 ? {} : { placementAnchor: asset.placementAnchor }
+          }))
+        },
+        confirmationSnapshotHash: bindConfirmationInputs(
+          legacyConfirmationSnapshotHash2,
+          options.inputs
+        ),
+        legacyConfirmationSnapshotHash: legacyConfirmationSnapshotHash2,
+        snapshotType: "stage-artifact"
+      };
+    }
     if (visual.assetsDirectory !== options.manifest.assetsDirectory && !isInsideDirectory(visual.assetsDirectory, options.manifest.assetsDirectory)) {
       throw new StageArtifactValidationError(["assetsDirectory \u4E0D\u5728\u9879\u76EE\u7D20\u6750\u76EE\u5F55\u4E2D"]);
     }
@@ -29826,11 +29996,18 @@ async function validateStageArtifact(options) {
       options.directory,
       visual.coverAsset,
       visual.coverSha256,
-      MAXIMUM_COVER_BYTES
+      MAXIMUM_COVER_BYTES,
+      "cover"
     );
     await Promise.all(
       visual.inlineAssets.map(
-        (asset) => validateImageAsset(options.directory, asset.path, asset.sha256, MAXIMUM_INLINE_IMAGE_BYTES)
+        (asset) => validateImageAsset(
+          options.directory,
+          asset.path,
+          asset.sha256,
+          MAXIMUM_INLINE_IMAGE_BYTES,
+          "inline-image"
+        )
       )
     );
   }
@@ -29842,29 +30019,40 @@ async function validateStageArtifact(options) {
   }
   if (options.stage === "titles") {
     const titles = titlesStageArtifactFrontmatterSchema.parse(frontmatter.value);
+    const legacyConfirmationSnapshotHash2 = sha256(
+      Buffer.from(
+        JSON.stringify({
+          articleSha256: titles.articleSha256,
+          body: frontmatter.body,
+          selectedTitle: titles.selectedTitle
+        }),
+        "utf8"
+      )
+    );
     return {
-      confirmationSnapshotHash: sha256(
-        Buffer.from(
-          JSON.stringify({
-            articleSha256: titles.articleSha256,
-            body: frontmatter.body,
-            selectedTitle: titles.selectedTitle
-          }),
-          "utf8"
-        )
+      confirmationSnapshotHash: bindConfirmationInputs(
+        legacyConfirmationSnapshotHash2,
+        options.inputs
       ),
+      legacyConfirmationSnapshotHash: legacyConfirmationSnapshotHash2,
       snapshotType: "stage-artifact"
     };
   }
   const semanticFrontmatter = { ...parsed.data };
   delete semanticFrontmatter["dxc"];
+  const legacyConfirmationSnapshotHash = articleConfirmationSnapshotHash ?? sha256(
+    Buffer.from(
+      JSON.stringify({ body: frontmatter.body, frontmatter: semanticFrontmatter }),
+      "utf8"
+    )
+  );
   return {
-    confirmationSnapshotHash: articleConfirmationSnapshotHash ?? sha256(
-      Buffer.from(
-        JSON.stringify({ body: frontmatter.body, frontmatter: semanticFrontmatter }),
-        "utf8"
-      )
+    ...options.stage === "visual-plan" ? { artifactPhase: "materialized" } : {},
+    confirmationSnapshotHash: bindConfirmationInputs(
+      legacyConfirmationSnapshotHash,
+      options.inputs
     ),
+    legacyConfirmationSnapshotHash,
     snapshotType: "stage-artifact"
   };
 }
@@ -29879,6 +30067,17 @@ async function stageArtifactRequiresUserConfirmation(options) {
   const value = recordValue(parseFrontmatter2(source).value);
   return normalizedOrigin(value?.["origin"]) === "hotspot" && value?.["researchMode"] === "fact-only" && value?.["externalOpinionStatus"] === "user-skipped";
 }
+async function visualPlanArtifactPhase(options) {
+  const source = (await readRegularFile(
+    insideProject(options.directory, options.manifest.artifacts["visual-plan"]),
+    MAXIMUM_ARTIFACT_BYTES
+  )).toString("utf8");
+  const parsed = visualPlanStageArtifactFrontmatterSchema.safeParse(parseFrontmatter2(source).value);
+  if (!parsed.success) {
+    throw new StageArtifactValidationError(issuePaths2(parsed.error.issues));
+  }
+  return "planned" in parsed.data && parsed.data.planned === true ? "generation-proposal" : "materialized";
+}
 
 // apps/cli/src/project.ts
 var MANIFEST_NAME = "dxc.project.json";
@@ -29908,12 +30107,14 @@ var DEFAULT_ARTIFACT_PATHS = {
   "visual-plan": "artifacts/06-visual-plan.md"
 };
 var ProjectCliError = class extends Error {
-  constructor(code, message) {
+  constructor(code, message, details = {}) {
     super(message);
     this.code = code;
+    this.details = details;
     this.name = "ProjectCliError";
   }
   code;
+  details;
 };
 function migrateCheckpointInputKinds(required, optional, existing) {
   const allowedOptionalInputs = new Set(optional);
@@ -29938,7 +30139,7 @@ function errorCode(error) {
 }
 async function readJsonFile(target, maximumBytes, missingCode) {
   try {
-    const metadata = await lstat2(target);
+    const metadata = await lstat3(target);
     if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size > maximumBytes) {
       throw new ProjectCliError("DXC_PROJECT_INVALID", "Project state file is invalid");
     }
@@ -30035,7 +30236,7 @@ async function inspectArtifact(directory, manifest, kind) {
   const relativePath = manifest.artifacts[kind];
   const target = insideProject2(directory, relativePath);
   try {
-    const metadata = await lstat2(target);
+    const metadata = await lstat3(target);
     if (!metadata.isFile() || metadata.isSymbolicLink()) {
       throw new ProjectCliError("DXC_PROJECT_INVALID", "Project artifact is invalid");
     }
@@ -30119,16 +30320,26 @@ async function inspectCheckpoint(directory, manifest, stage, artifact, artifacts
       };
     }
     if (artifact.sha256 !== checkpoint.artifact.sha256 || artifact.bytes !== checkpoint.artifact.bytes) {
-      return {
-        checkpoint,
-        path: relativePath,
-        reason: "artifact-changed",
-        stage,
-        state: "stale"
-      };
+      let authorizedMaterialization = false;
+      if (checkpoint.checkpointVersion === "4" && checkpoint.stage === "visual-plan" && checkpoint.status === "running" && checkpoint.authorizations.length > 0) {
+        try {
+          authorizedMaterialization = await visualPlanArtifactPhase({ directory, manifest }) === "materialized";
+        } catch {
+          authorizedMaterialization = false;
+        }
+      }
+      if (!authorizedMaterialization) {
+        return {
+          checkpoint,
+          path: relativePath,
+          reason: "artifact-changed",
+          stage,
+          state: "stale"
+        };
+      }
     }
   }
-  if (checkpoint.checkpointVersion === "2" || checkpoint.checkpointVersion === "3") {
+  if (checkpoint.checkpointVersion === "2" || checkpoint.checkpointVersion === "3" || checkpoint.checkpointVersion === "4") {
     if (checkpoint.inputs.some((input) => input.path !== manifest.artifacts[input.kind]) || checkpoint.outputs.some((output) => output.path !== manifest.artifacts[output.kind])) {
       throw new ProjectCliError("DXC_PROJECT_INVALID", "Project checkpoint paths are invalid");
     }
@@ -30295,12 +30506,18 @@ var ProjectCli = class {
       });
       pendingCheckpoints.push({ checkpoint, stage });
     }
-    for (const { checkpoint, stage } of pendingCheckpoints) {
-      await writeJsonAtomically(
-        insideProject2(directory, checkpointRelativePath(manifest, stage)),
-        checkpoint
-      );
+    const writtenTargets = [];
+    try {
+      for (const { checkpoint, stage } of pendingCheckpoints) {
+        const target = insideProject2(directory, checkpointRelativePath(manifest, stage));
+        await writeJsonAtomically(target, checkpoint);
+        writtenTargets.push(target);
+      }
+    } catch (error) {
+      await Promise.all(writtenTargets.map((target) => unlink2(target).catch(() => void 0)));
+      throw error;
     }
+    return writtenTargets;
   }
   async #rememberProject(directory, manifest, updatedAt) {
     const index = await loadProjectIndex(this.#projectIndexPath);
@@ -30329,7 +30546,7 @@ var ProjectCli = class {
     const directory = projectDirectory(this.#currentDirectory, this.#homeDirectory, directoryInput);
     const manifestTarget = path4.join(directory, MANIFEST_NAME);
     try {
-      await lstat2(manifestTarget);
+      await lstat3(manifestTarget);
       throw new ProjectCliError("DXC_PROJECT_EXISTS", "A DxC project already exists");
     } catch (error) {
       if (error instanceof ProjectCliError) {
@@ -30409,9 +30626,18 @@ var ProjectCli = class {
       )
     );
     const summary = workflowSummary(checkpoints);
+    const recoveryPlan = checkpoints.flatMap(
+      (inspection) => inspection.state === "stale" ? [
+        {
+          action: "rerun-stage",
+          reason: inspection.reason,
+          stage: inspection.stage
+        }
+      ] : []
+    );
     let assetsDirectoryReady = false;
     try {
-      const metadata = await lstat2(insideProject2(directory, manifest.assetsDirectory));
+      const metadata = await lstat3(insideProject2(directory, manifest.assetsDirectory));
       assetsDirectoryReady = metadata.isDirectory() && !metadata.isSymbolicLink();
     } catch (error) {
       if (errorCode(error) !== "ENOENT") {
@@ -30428,6 +30654,7 @@ var ProjectCli = class {
         checkpointsDirectory: manifest.checkpointsDirectory,
         manifest,
         manifestPath: MANIFEST_NAME,
+        recoveryPlan,
         ...summary
       },
       ok: true
@@ -30517,10 +30744,46 @@ var ProjectCli = class {
     const status = stepCheckpointStatusSchema.safeParse(options.status);
     const executionLocation = executionLocationSchema.safeParse(options.executionLocation);
     const dataTransit = dataTransitSchema.safeParse(options.dataTransit);
-    const summary = options.summary.trim();
+    const summary = options.summary?.trim() ?? "";
     const requestedWaitingFor = options.waitingFor?.trim();
     if (!stage.success || !status.success || !executionLocation.success || !dataTransit.success || summary.length === 0) {
-      throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", "Checkpoint options are invalid");
+      throw new ProjectCliError(
+        "DXC_PROJECT_STAGE_INVALID",
+        summary.length === 0 ? "\u9636\u6BB5\u68C0\u67E5\u70B9\u7F3A\u5C11\u6458\u8981\u3002" : "Checkpoint options are invalid",
+        summary.length === 0 ? {
+          fields: ["summary"],
+          reason: "SUMMARY_REQUIRED",
+          recovery: "\u8865\u5145 --summary <\u672C\u6B21\u9636\u6BB5\u72B6\u6001\u7684\u7B80\u77ED\u8BF4\u660E> \u540E\u91CD\u8BD5\uFF1BCLI \u4E0D\u4F1A\u5728\u7F3A\u5C11\u6458\u8981\u65F6\u4FEE\u6539\u4EFB\u4F55\u4EA7\u7269\u3002",
+          ...stage.success ? { stage: stage.data } : {}
+        } : { reason: "CHECKPOINT_OPTIONS_INVALID" }
+      );
+    }
+    if (options.confirmationSnapshotHash !== void 0 && stage.data !== "delivery") {
+      throw new ProjectCliError(
+        "DXC_PROJECT_STAGE_INVALID",
+        "--confirmation-snapshot \u4EC5\u7528\u4E8E delivery \u7684\u4E91\u7AEF\u6E32\u67D3\u5FEB\u7167\uFF1B\u5185\u5BB9\u9636\u6BB5\u7531 CLI \u81EA\u52A8\u8BA1\u7B97\u8BED\u4E49\u5FEB\u7167\u3002",
+        {
+          fields: ["confirmationSnapshot"],
+          reason: "CONFIRMATION_SNAPSHOT_FLAG_NOT_ALLOWED",
+          recovery: "\u79FB\u9664\u8BE5\u53C2\u6570\uFF1B\u82E5\u6B63\u6587\u6216\u6807\u9898\u5728\u5C55\u793A\u540E\u53D1\u751F\u53D8\u5316\uFF0C\u5148\u91CD\u65B0\u5199 awaiting-user \u68C0\u67E5\u70B9\u5E76\u518D\u6B21\u5C55\u793A\uFF0C\u518D\u4F7F\u7528 --confirm\u3002",
+          stage: stage.data
+        }
+      );
+    }
+    const authorizationPurpose = options.authorizationPurpose?.trim();
+    const requestingExternalAuthorization = authorizationPurpose === "image-generation" && stage.data === "visual-plan" && status.data === "awaiting-user" && options.confirmed !== true;
+    const confirmingExternalAuthorization = authorizationPurpose === "image-generation" && stage.data === "visual-plan" && status.data === "running" && options.confirmed === true;
+    if (authorizationPurpose !== void 0 && !requestingExternalAuthorization && !confirmingExternalAuthorization) {
+      throw new ProjectCliError(
+        "DXC_PROJECT_STAGE_INVALID",
+        "\u56FE\u7247\u751F\u6210\u6388\u6743\u4EC5\u652F\u6301 visual-plan\uFF1A\u5148\u4EE5 awaiting-user \u8BF7\u6C42\uFF0C\u518D\u4EE5 running --confirm \u786E\u8BA4\u540E\u56DE\u5230\u540C\u4E00\u9636\u6BB5\u3002",
+        {
+          fields: ["authorizationPurpose"],
+          reason: "EXTERNAL_AUTHORIZATION_OPTIONS_INVALID",
+          recovery: "\u8BF7\u6C42\u6388\u6743\u65F6\u4F7F\u7528 --status awaiting-user --authorization-purpose image-generation\uFF1B\u7528\u6237\u786E\u8BA4\u540E\u4F7F\u7528 --status running --confirm \u548C\u76F8\u540C purpose\u3002",
+          stage: stage.data
+        }
+      );
     }
     const expectedSkill = CONTENT_STAGE_SKILLS[stage.data];
     const effectiveSkill = options.skill ?? expectedSkill.name;
@@ -30556,12 +30819,12 @@ var ProjectCli = class {
         status: await inspectArtifact(directory, manifest, inputStage)
       }))
     )).filter((input) => input.status.status === "ready").map((input) => input.inputStage) : [];
-    const migratedExistingInputs = existing?.checkpointVersion === "2" || existing?.checkpointVersion === "3" ? migrateCheckpointInputKinds(
+    const migratedExistingInputs = existing?.checkpointVersion === "2" || existing?.checkpointVersion === "3" || existing?.checkpointVersion === "4" ? migrateCheckpointInputKinds(
       stageInputs.required,
       stageInputs.optional,
       existing.inputs.map((input) => input.kind)
     ) : [];
-    const inputStageValues = options.inputStages !== void 0 ? [...stageInputs.required, ...options.inputStages] : existing?.checkpointVersion === "2" || existing?.checkpointVersion === "3" ? migratedExistingInputs : [...stageInputs.required, ...inferredOptionalInputs];
+    const inputStageValues = options.inputStages !== void 0 ? [...stageInputs.required, ...options.inputStages] : existing?.checkpointVersion === "2" || existing?.checkpointVersion === "3" || existing?.checkpointVersion === "4" ? migratedExistingInputs : [...stageInputs.required, ...inferredOptionalInputs];
     const inputStages = inputStageValues.map(
       (inputStage) => contentArtifactKindSchema.safeParse(inputStage)
     );
@@ -30619,7 +30882,7 @@ var ProjectCli = class {
       );
     }
     const inputs = inputArtifactStatuses.map(artifactReference);
-    const requestedNeedsArtifact = status.data === "awaiting-user" || status.data === "completed";
+    const requestedNeedsArtifact = status.data === "awaiting-user" || status.data === "completed" || confirmingExternalAuthorization;
     const artifactStatusBeforeNormalization = await inspectArtifact(
       directory,
       manifest,
@@ -30635,7 +30898,12 @@ var ProjectCli = class {
         });
       } catch (error) {
         if (error instanceof StageArtifactValidationError) {
-          throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message);
+          throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message, {
+            fields: error.issues.slice(0, 20).map((issue) => issue.slice(0, 200)),
+            reason: "STAGE_ARTIFACT_INVALID",
+            recovery: "\u6309 fields \u4E2D\u7684\u9996\u4E2A\u95EE\u9898\u4FEE\u6B63\u9636\u6BB5\u4EA7\u7269\u540E\u91CD\u8BD5\uFF1B\u5176\u4ED6\u95EE\u9898\u4F5C\u4E3A\u8865\u5145\u8BE6\u60C5\uFF0C\u4E0D\u4F1A\u906E\u4F4F\u4E3B\u539F\u56E0\u3002",
+            stage: stage.data
+          });
         }
         throw error;
       }
@@ -30656,11 +30924,12 @@ var ProjectCli = class {
         "Awaiting checkpoint needs one waiting-for prompt"
       );
     }
-    const needsArtifact = effectiveStatus === "awaiting-user" || effectiveStatus === "completed";
+    const needsArtifact = effectiveStatus === "awaiting-user" || effectiveStatus === "completed" || confirmingExternalAuthorization;
+    let artifactNormalization;
     if (needsArtifact) {
       try {
-        await normalizeStageArtifact({
-          artifactStatus: effectiveStatus === "completed" ? "complete" : "awaiting-user",
+        artifactNormalization = await normalizeStageArtifact({
+          artifactStatus: effectiveStatus === "completed" && !confirmingExternalAuthorization ? "complete" : "awaiting-user",
           createdAt: timestamp,
           directory,
           inputs,
@@ -30671,138 +30940,251 @@ var ProjectCli = class {
         });
       } catch (error) {
         if (error instanceof StageArtifactValidationError) {
-          throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message);
+          throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message, {
+            fields: error.issues.slice(0, 20).map((issue) => issue.slice(0, 200)),
+            reason: "STAGE_ARTIFACT_INVALID",
+            recovery: "\u6309 fields \u4E2D\u7684\u9996\u4E2A\u95EE\u9898\u4FEE\u6B63\u9636\u6BB5\u4EA7\u7269\u540E\u91CD\u8BD5\uFF1B\u6821\u9A8C\u5931\u8D25\u4E0D\u4F1A\u4FDD\u7559 CLI \u89C4\u8303\u5316\u6539\u5199\u3002",
+            stage: stage.data
+          });
         }
         throw error;
       }
     }
-    const artifactStatus = await inspectArtifact(directory, manifest, stage.data);
-    if (needsArtifact && artifactStatus.status !== "ready") {
-      throw new ProjectCliError(
-        "DXC_PROJECT_STAGE_INVALID",
-        "Checkpoint artifact must exist and be non-empty"
-      );
-    }
-    let artifactValidation;
-    if (needsArtifact) {
+    {
+      const artifactStatus = artifactNormalization === void 0 ? await inspectArtifact(directory, manifest, stage.data) : {
+        ...artifactNormalization.artifact,
+        kind: stage.data,
+        status: "ready"
+      };
+      if (needsArtifact && artifactStatus.status !== "ready") {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          "Checkpoint artifact must exist and be non-empty"
+        );
+      }
+      let artifactValidation;
+      if (needsArtifact) {
+        try {
+          artifactValidation = await validateStageArtifact({
+            ...artifactNormalization === void 0 ? {} : { candidate: artifactNormalization.candidate },
+            checkpointStatus: confirmingExternalAuthorization ? "awaiting-user" : effectiveStatus,
+            directory,
+            inputs,
+            manifest,
+            skill: effectiveSkill,
+            skillVersion: effectiveSkillVersion,
+            stage: stage.data
+          });
+        } catch (error) {
+          if (error instanceof StageArtifactValidationError) {
+            throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message, {
+              fields: error.issues.slice(0, 20).map((issue) => issue.slice(0, 200)),
+              reason: "STAGE_ARTIFACT_INVALID",
+              recovery: "\u6309 fields \u4E2D\u7684\u9996\u4E2A\u95EE\u9898\u4FEE\u6B63\u9636\u6BB5\u4EA7\u7269\u540E\u91CD\u8BD5\uFF1B\u9700\u8981\u786E\u8BA4\u65F6\u5148\u91CD\u65B0\u5C55\u793A\u5F53\u524D\u8BED\u4E49\u5FEB\u7167\u3002",
+              stage: stage.data
+            });
+          }
+          throw error;
+        }
+      }
+      if (artifactValidation?.artifactPhase === "generation-proposal" && !requestingExternalAuthorization && !confirmingExternalAuthorization) {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          "\u89C6\u89C9\u4EA7\u7269\u4ECD\u662F\u56FE\u7247\u751F\u6210\u8BA1\u5212\uFF0C\u5FC5\u987B\u5148\u5B8C\u6210\u751F\u6210\u524D\u6388\u6743\uFF0C\u4E0D\u80FD\u76F4\u63A5\u5B8C\u6210\u9636\u6BB5\u3002",
+          {
+            reason: "VISUAL_GENERATION_AUTHORIZATION_REQUIRED",
+            recovery: "\u5148\u4EE5 awaiting-user --authorization-purpose image-generation \u4FDD\u5B58\u8BA1\u5212\uFF1B\u7528\u6237\u786E\u8BA4\u540E\u4EE5 running --confirm \u8FD4\u56DE\u540C\u4E00 visual-plan \u9636\u6BB5\u3002",
+            stage: "visual-plan"
+          }
+        );
+      }
+      const output = artifactReference(artifactStatus);
+      const confirmationSnapshotHash = options.confirmationSnapshotHash?.trim() ?? artifactValidation?.confirmationSnapshotHash;
+      if (needsArtifact && (confirmationSnapshotHash === void 0 || !/^[a-f0-9]{64}$/u.test(confirmationSnapshotHash))) {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          "Confirmation snapshot hash is invalid"
+        );
+      }
+      if (options.confirmationSnapshotHash !== void 0 && artifactValidation !== void 0 && options.confirmationSnapshotHash.trim() !== artifactValidation.confirmationSnapshotHash) {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          "\u786E\u8BA4\u5FEB\u7167\u4E0E\u5F53\u524D\u9636\u6BB5\u7ECF\u8FC7\u6821\u9A8C\u7684\u5185\u5BB9\u6216\u6E32\u67D3\u5FEB\u7167\u4E0D\u4E00\u81F4\u3002"
+        );
+      }
+      const confirmationRelevant = effectiveStatus === "awaiting-user" || effectiveStatus === "completed" && requiresUserConfirmation && options.confirmed;
+      const previousBinding = existing?.checkpointVersion === "3" || existing?.checkpointVersion === "4" ? existing.confirmationBinding : null;
+      const confirmationSnapshotType = artifactValidation?.snapshotType ?? "stage-artifact";
+      const previousInputsMatch = (existing?.checkpointVersion === "2" || existing?.checkpointVersion === "3" || existing?.checkpointVersion === "4") && existing.inputs.length === inputs.length && existing.inputs.every((input, index) => {
+        const current = inputs[index];
+        return current !== void 0 && input.kind === current.kind && input.path === current.path && input.sha256 === current.sha256 && input.bytes === current.bytes;
+      });
+      const legacyPendingSnapshotMatches = options.confirmed && previousInputsMatch && previousBinding?.snapshotType === "stage-artifact" && artifactStatusBeforeNormalization.status === "ready" && previousBinding.snapshotHash === artifactStatusBeforeNormalization.sha256;
+      const legacySemanticSnapshotMatches = options.confirmed && previousInputsMatch && previousBinding?.snapshotType === "stage-artifact" && artifactValidation?.legacyConfirmationSnapshotHash !== void 0 && previousBinding.snapshotHash === artifactValidation.legacyConfirmationSnapshotHash;
+      const previousSnapshotMatches = previousBinding?.snapshotHash === confirmationSnapshotHash || legacySemanticSnapshotMatches || legacyPendingSnapshotMatches;
+      const completingConfirmedStage = effectiveStatus === "completed" && requiresUserConfirmation && options.confirmed;
+      if ((completingConfirmedStage || confirmingExternalAuthorization) && (existing?.status !== "awaiting-user" || existing.confirmation !== "pending" || previousBinding?.status !== "pending" || !previousSnapshotMatches || previousBinding.snapshotType !== confirmationSnapshotType || confirmingExternalAuthorization && (existing.checkpointVersion !== "4" || existing.confirmationPurpose !== "external-action"))) {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          confirmingExternalAuthorization ? "\u5F53\u524D\u56FE\u7247\u751F\u6210\u8BA1\u5212\u4E0D\u662F\u521A\u624D\u7B49\u5F85\u6388\u6743\u7684\u7248\u672C\uFF1B\u8BF7\u91CD\u65B0\u5C55\u793A\u5F53\u524D\u8BA1\u5212\u5E76\u8BF7\u6C42\u6388\u6743\u3002" : "\u5F53\u524D\u5185\u5BB9\u6216\u6E32\u67D3\u5FEB\u7167\u4E0D\u662F\u521A\u624D\u7B49\u5F85\u786E\u8BA4\u7684\u7248\u672C\uFF1B\u8BF7\u5148\u91CD\u65B0\u5C55\u793A\u5E76\u5199\u5165 awaiting-user \u68C0\u67E5\u70B9\uFF0C\u518D\u6839\u636E\u7528\u6237\u660E\u786E\u56DE\u7B54\u786E\u8BA4\u3002",
+          {
+            reason: confirmingExternalAuthorization ? "EXTERNAL_AUTHORIZATION_STALE" : "CONFIRMATION_STALE",
+            recovery: confirmingExternalAuthorization ? "\u7528\u5F53\u524D\u5F20\u6570\u3001\u7528\u9014\u3001\u6570\u636E\u53BB\u5411\u548C\u5C1D\u8BD5\u4E0A\u9650\u91CD\u5199\u751F\u6210\u8BA1\u5212\uFF0C\u5199 awaiting-user \u540E\u91CD\u65B0\u53D6\u5F97\u7528\u6237\u6388\u6743\u3002" : "\u91CD\u65B0\u751F\u6210\u6216\u89C4\u8303\u5316\u5F53\u524D\u4EA7\u7269\uFF0C\u5199 awaiting-user \u68C0\u67E5\u70B9\uFF0C\u5411\u7528\u6237\u5C55\u793A\u8BE5\u8BED\u4E49\u5FEB\u7167\u540E\u518D\u786E\u8BA4\u3002",
+            stage: stage.data
+          }
+        );
+      }
+      const requestedAt = previousBinding !== null && previousSnapshotMatches && previousBinding.snapshotType === confirmationSnapshotType ? previousBinding.requestedAt : timestamp;
+      const confirmedBy = options.confirmedBy?.trim() || "local-interactive-user";
+      const authorizationPlan = artifactValidation?.authorizationPlan;
+      if ((requestingExternalAuthorization || confirmingExternalAuthorization) && authorizationPlan === void 0) {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          "\u56FE\u7247\u751F\u6210\u6388\u6743\u5FC5\u987B\u7ED1\u5B9A planned=true \u7684\u5B8C\u6574\u751F\u6210\u8BA1\u5212\u3002",
+          {
+            reason: "VISUAL_GENERATION_PLAN_REQUIRED",
+            recovery: "\u8865\u9F50 generation.executionLocation\u3001dataTransit\u3001chargesQuota\u3001maxAttempts \u548C plannedAssets \u540E\u91CD\u65B0\u8BF7\u6C42\u6388\u6743\u3002",
+            stage: "visual-plan"
+          }
+        );
+      }
+      if (authorizationPlan !== void 0 && (authorizationPlan.dataTransit !== dataTransit.data || authorizationPlan.executionLocation !== executionLocation.data || confirmingExternalAuthorization && (existing?.execution.dataTransit !== dataTransit.data || existing.execution.location !== executionLocation.data))) {
+        throw new ProjectCliError(
+          "DXC_PROJECT_STAGE_INVALID",
+          "\u56FE\u7247\u751F\u6210\u8BA1\u5212\u3001\u7B49\u5F85\u6388\u6743\u68C0\u67E5\u70B9\u548C\u672C\u6B21\u6267\u884C\u58F0\u660E\u7684\u6570\u636E\u53BB\u5411\u6216\u6267\u884C\u4F4D\u7F6E\u4E0D\u4E00\u81F4\u3002",
+          {
+            fields: ["generation.dataTransit", "generation.executionLocation", "execution"],
+            reason: "EXTERNAL_AUTHORIZATION_EXECUTION_MISMATCH",
+            recovery: "\u4FDD\u6301\u8BF7\u6C42\u6388\u6743\u4E0E\u786E\u8BA4\u547D\u4EE4\u7684 --data-transit\u3001--execution-location \u5B8C\u5168\u4E00\u81F4\uFF1B\u82E5\u6267\u884C\u73AF\u5883\u53D8\u5316\uFF0C\u91CD\u5199\u8BA1\u5212\u5E76\u91CD\u65B0\u53D6\u5F97\u6388\u6743\u3002",
+            stage: "visual-plan"
+          }
+        );
+      }
+      const useCheckpointV4 = authorizationPurpose !== void 0 || existing?.checkpointVersion === "4";
+      const existingAuthorizations = existing?.checkpointVersion === "4" ? existing.authorizations : [];
+      const authorizations = confirmingExternalAuthorization ? [
+        ...existingAuthorizations,
+        {
+          action: "image-generation",
+          confirmedAt: timestamp,
+          confirmedBy,
+          plan: authorizationPlan,
+          planSnapshotHash: confirmationSnapshotHash,
+          requestedAt
+        }
+      ] : existingAuthorizations;
+      const checkpointResult = stepCheckpointSchema.safeParse({
+        ...(effectiveStatus === "awaiting-user" || effectiveStatus === "completed") && artifactStatus.status === "ready" ? {
+          artifact: {
+            bytes: artifactStatus.bytes,
+            kind: stage.data,
+            path: artifactStatus.path,
+            sha256: artifactStatus.sha256
+          }
+        } : confirmingExternalAuthorization && artifactStatus.status === "ready" ? {
+          artifact: {
+            bytes: artifactStatus.bytes,
+            kind: stage.data,
+            path: artifactStatus.path,
+            sha256: artifactStatus.sha256
+          }
+        } : {},
+        ...useCheckpointV4 ? {
+          authorizations,
+          checkpointVersion: "4",
+          confirmationPurpose: confirmationRelevant ? requestingExternalAuthorization ? "external-action" : "stage-completion" : null
+        } : { checkpointVersion: "3" },
+        ...TERMINAL_CHECKPOINT_STATUSES.has(effectiveStatus) ? { completedAt: timestamp } : {},
+        confirmation: effectiveStatus === "awaiting-user" ? "pending" : effectiveStatus === "completed" && requiresUserConfirmation && options.confirmed ? "confirmed" : "not-required",
+        confirmationBinding: confirmationRelevant && confirmationSnapshotHash !== void 0 ? {
+          confirmedAt: effectiveStatus === "completed" ? timestamp : null,
+          confirmedBy: effectiveStatus === "completed" ? confirmedBy : null,
+          requestedAt,
+          snapshotHash: confirmationSnapshotHash,
+          snapshotType: confirmationSnapshotType,
+          status: effectiveStatus === "completed" ? "confirmed" : "pending"
+        } : null,
+        ...effectiveStatus === "failed" ? { errorCode: options.errorCode } : {},
+        execution: {
+          dataTransit: dataTransit.data,
+          location: executionLocation.data
+        },
+        inputs,
+        metadata: {
+          summary
+        },
+        outputs: [output],
+        projectId: manifest.projectId,
+        revision: (existing?.revision ?? 0) + 1,
+        skill: {
+          name: effectiveSkill,
+          version: effectiveSkillVersion
+        },
+        stage: stage.data,
+        startedAt: status.data === "running" && existing !== void 0 && TERMINAL_CHECKPOINT_STATUSES.has(existing.status) ? timestamp : existing?.startedAt ?? timestamp,
+        status: effectiveStatus,
+        updatedAt: timestamp,
+        waitingFor: waitingFor ?? null,
+        workflowId: manifest.workflowId
+      });
+      if (!checkpointResult.success) {
+        throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", "Checkpoint options are invalid");
+      }
+      const checkpoint = checkpointResult.data;
+      const relativePath = checkpointRelativePath(manifest, stage.data);
       try {
-        artifactValidation = await validateStageArtifact({
-          checkpointStatus: effectiveStatus,
-          directory,
-          inputs,
-          manifest,
-          skill: effectiveSkill,
-          skillVersion: effectiveSkillVersion,
-          stage: stage.data
-        });
+        await artifactNormalization?.commit();
       } catch (error) {
         if (error instanceof StageArtifactValidationError) {
-          throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message);
+          throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", error.message, {
+            fields: error.issues.slice(0, 20).map((issue) => issue.slice(0, 200)),
+            reason: error.issues.some((issue) => issue.startsWith("NORMALIZATION_CONFLICT:")) ? "NORMALIZATION_CONFLICT" : "STAGE_ARTIFACT_INVALID",
+            recovery: "\u91CD\u65B0\u8BFB\u53D6\u5F53\u524D\u9636\u6BB5\u4EA7\u7269\u53CA sidecar \u540E\u91CD\u8BD5\uFF1BCLI \u68C0\u6D4B\u5230\u5E76\u53D1\u6539\u52A8\u65F6\u4E0D\u4F1A\u8986\u76D6\u8F83\u65B0\u7684\u6587\u4EF6\u3002",
+            stage: stage.data
+          });
         }
         throw error;
       }
-    }
-    const output = artifactReference(artifactStatus);
-    const confirmationSnapshotHash = options.confirmationSnapshotHash?.trim() ?? artifactValidation?.confirmationSnapshotHash;
-    if (needsArtifact && (confirmationSnapshotHash === void 0 || !/^[a-f0-9]{64}$/u.test(confirmationSnapshotHash))) {
-      throw new ProjectCliError(
-        "DXC_PROJECT_STAGE_INVALID",
-        "Confirmation snapshot hash is invalid"
-      );
-    }
-    if (options.confirmationSnapshotHash !== void 0 && artifactValidation !== void 0 && options.confirmationSnapshotHash.trim() !== artifactValidation.confirmationSnapshotHash) {
-      throw new ProjectCliError(
-        "DXC_PROJECT_STAGE_INVALID",
-        "\u786E\u8BA4\u5FEB\u7167\u4E0E\u5F53\u524D\u9636\u6BB5\u7ECF\u8FC7\u6821\u9A8C\u7684\u5185\u5BB9\u6216\u6E32\u67D3\u5FEB\u7167\u4E0D\u4E00\u81F4\u3002"
-      );
-    }
-    const confirmationRelevant = effectiveStatus === "awaiting-user" || effectiveStatus === "completed" && requiresUserConfirmation && options.confirmed;
-    const previousBinding = existing?.checkpointVersion === "3" ? existing.confirmationBinding : null;
-    const confirmationSnapshotType = artifactValidation?.snapshotType ?? "stage-artifact";
-    const legacyPendingSnapshotMatches = options.confirmed && previousBinding?.snapshotType === "stage-artifact" && artifactStatusBeforeNormalization.status === "ready" && previousBinding.snapshotHash === artifactStatusBeforeNormalization.sha256;
-    const previousSnapshotMatches = previousBinding?.snapshotHash === confirmationSnapshotHash || legacyPendingSnapshotMatches;
-    if (effectiveStatus === "completed" && requiresUserConfirmation && options.confirmed && (existing?.status !== "awaiting-user" || existing.confirmation !== "pending" || previousBinding?.status !== "pending" || !previousSnapshotMatches || previousBinding.snapshotType !== confirmationSnapshotType)) {
-      throw new ProjectCliError(
-        "DXC_PROJECT_STAGE_INVALID",
-        "\u5F53\u524D\u5185\u5BB9\u6216\u6E32\u67D3\u5FEB\u7167\u4E0D\u662F\u521A\u624D\u7B49\u5F85\u786E\u8BA4\u7684\u7248\u672C\uFF1B\u8BF7\u5148\u91CD\u65B0\u5C55\u793A\u5E76\u5199\u5165 awaiting-user \u68C0\u67E5\u70B9\uFF0C\u518D\u6839\u636E\u7528\u6237\u660E\u786E\u56DE\u7B54\u786E\u8BA4\u3002"
-      );
-    }
-    const requestedAt = previousBinding !== null && previousSnapshotMatches && previousBinding.snapshotType === confirmationSnapshotType ? previousBinding.requestedAt : timestamp;
-    const confirmedBy = options.confirmedBy?.trim() || "local-interactive-user";
-    const checkpointResult = stepCheckpointSchema.safeParse({
-      ...needsArtifact && artifactStatus.status === "ready" ? {
-        artifact: {
-          bytes: artifactStatus.bytes,
-          kind: stage.data,
-          path: artifactStatus.path,
-          sha256: artifactStatus.sha256
-        }
-      } : {},
-      checkpointVersion: "3",
-      ...TERMINAL_CHECKPOINT_STATUSES.has(effectiveStatus) ? { completedAt: timestamp } : {},
-      confirmation: effectiveStatus === "awaiting-user" ? "pending" : effectiveStatus === "completed" && requiresUserConfirmation && options.confirmed ? "confirmed" : "not-required",
-      confirmationBinding: confirmationRelevant && confirmationSnapshotHash !== void 0 ? {
-        confirmedAt: effectiveStatus === "completed" ? timestamp : null,
-        confirmedBy: effectiveStatus === "completed" ? confirmedBy : null,
-        requestedAt,
-        snapshotHash: confirmationSnapshotHash,
-        snapshotType: confirmationSnapshotType,
-        status: effectiveStatus === "completed" ? "confirmed" : "pending"
-      } : null,
-      ...effectiveStatus === "failed" ? { errorCode: options.errorCode } : {},
-      execution: {
-        dataTransit: dataTransit.data,
-        location: executionLocation.data
-      },
-      inputs,
-      metadata: {
-        summary
-      },
-      outputs: [output],
-      projectId: manifest.projectId,
-      revision: (existing?.revision ?? 0) + 1,
-      skill: {
-        name: effectiveSkill,
-        version: effectiveSkillVersion
-      },
-      stage: stage.data,
-      startedAt: status.data === "running" && existing !== void 0 && TERMINAL_CHECKPOINT_STATUSES.has(existing.status) ? timestamp : existing?.startedAt ?? timestamp,
-      status: effectiveStatus,
-      updatedAt: timestamp,
-      waitingFor: waitingFor ?? null,
-      workflowId: manifest.workflowId
-    });
-    if (!checkpointResult.success) {
-      throw new ProjectCliError("DXC_PROJECT_STAGE_INVALID", "Checkpoint options are invalid");
-    }
-    const checkpoint = checkpointResult.data;
-    const relativePath = checkpointRelativePath(manifest, stage.data);
-    if (adoptsExistingArticle) {
-      await this.#skipArticleAdoptionPrerequisites(directory, manifest, timestamp, {
-        dataTransit: dataTransit.data,
-        location: executionLocation.data
+      let adoptionTargets = [];
+      try {
+        if (adoptsExistingArticle) {
+          adoptionTargets = await this.#skipArticleAdoptionPrerequisites(
+            directory,
+            manifest,
+            timestamp,
+            {
+              dataTransit: dataTransit.data,
+              location: executionLocation.data
+            }
+          );
+        }
+        await writeJsonAtomically(insideProject2(directory, relativePath), checkpoint);
+      } catch (error) {
+        await Promise.all(adoptionTargets.map((target) => unlink2(target).catch(() => void 0)));
+        await artifactNormalization?.rollbackCommitted();
+        throw error;
+      }
+      await this.#rememberProject(directory, manifest, timestamp).catch(() => void 0);
+      return contentProjectCheckpointResultSchema.parse({
+        command: "project.checkpoint",
+        data: {
+          artifactMutations: artifactNormalization?.mutations ?? [],
+          checkpoint,
+          checkpointPath: relativePath,
+          guidance: effectiveStatus === "awaiting-user" ? {
+            action: requestingExternalAuthorization ? "authorize-external-action" : "confirm-stage",
+            message: waitingFor ?? "\u8BF7\u786E\u8BA4\u5F53\u524D\u9636\u6BB5\u5FEB\u7167\u3002",
+            suggestedFlag: "--confirm"
+          } : null
+        },
+        ok: true
       });
     }
-    await this.#rememberProject(directory, manifest, timestamp);
-    await writeJsonAtomically(insideProject2(directory, relativePath), checkpoint);
-    return contentProjectCheckpointResultSchema.parse({
-      command: "project.checkpoint",
-      data: {
-        checkpoint,
-        checkpointPath: relativePath,
-        guidance: confirmationRequired ? {
-          action: "confirm-stage",
-          message: waitingFor ?? "\u8BF7\u786E\u8BA4\u5F53\u524D\u9636\u6BB5\u5FEB\u7167\u3002",
-          suggestedFlag: "--confirm"
-        } : null
-      },
-      ok: true
-    });
   }
 };
 
 // apps/cli/src/skills.ts
-import { cp, lstat as lstat3, mkdir as mkdir2, mkdtemp, readdir, rename as rename4, rm } from "node:fs/promises";
+import { cp, lstat as lstat4, mkdir as mkdir2, mkdtemp, readdir, rename as rename4, rm } from "node:fs/promises";
 import os from "node:os";
 import path5 from "node:path";
 import { fileURLToPath } from "node:url";
@@ -30831,7 +31213,7 @@ var SkillInstallerError = class extends Error {
 };
 async function isDirectory(directory) {
   try {
-    return (await lstat3(directory)).isDirectory();
+    return (await lstat4(directory)).isDirectory();
   } catch {
     return false;
   }
@@ -30855,7 +31237,7 @@ async function findBundledSkills() {
 async function assertRegularSkillTree(directory) {
   for (const entry of await readdir(directory, { withFileTypes: true })) {
     const entryPath = path5.join(directory, entry.name);
-    const entryStat = await lstat3(entryPath);
+    const entryStat = await lstat4(entryPath);
     if (entryStat.isSymbolicLink()) {
       throw new SkillInstallerError(
         "DXC_SKILL_SOURCE_UNSAFE",
@@ -31111,20 +31493,22 @@ var LOG_REDACTION_PATHS = Object.freeze([
 // apps/cli/src/publishing-assets.ts
 import { createHash as createHash6 } from "node:crypto";
 import { constants as fileConstants2 } from "node:fs";
-import { lstat as lstat4, open as open2, readdir as readdir2, realpath } from "node:fs/promises";
+import { lstat as lstat5, open as open2, readdir as readdir2, realpath } from "node:fs/promises";
 import path6 from "node:path";
 var import_yaml3 = __toESM(require_dist(), 1);
 
 // apps/cli/src/wechat-error.ts
 var WechatCliError = class extends Error {
-  constructor(code, guidance) {
+  constructor(code, guidance, retryable = false) {
     super(guidance ?? code);
     this.code = code;
     this.guidance = guidance;
+    this.retryable = retryable;
     this.name = "WechatCliError";
   }
   code;
   guidance;
+  retryable;
 };
 
 // apps/cli/src/publishing-assets.ts
@@ -31137,16 +31521,35 @@ var VISUAL_PLAN_MAXIMUM_BYTES = 128 * 1024;
 var ARTICLE_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/u;
 var VISUAL_PLAN_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u;
 var LOCAL_WORKFLOW_FRONTMATTER_KEYS = ["dxc", "goldenLinesPath", "goldenLinesSha256"];
-async function readPublishingInput(inputPath, maximumBytes) {
+async function readPublishingInput(inputPath, maximumBytes, role = "article") {
   const target = path6.resolve(inputPath);
   let handle;
   try {
     handle = await open2(target, fileConstants2.O_RDONLY | fileConstants2.O_NOFOLLOW);
     const metadata = await handle.stat();
-    if (!metadata.isFile() || metadata.size <= 0 || metadata.size > maximumBytes) {
+    if (metadata.isFile() && metadata.size > maximumBytes) {
+      const fileName = path6.basename(target);
+      if (role === "inline-image") {
+        throw new WechatCliError(
+          "DXC_PUBLISHING_INLINE_IMAGE_TOO_LARGE",
+          `\u6B63\u6587\u56FE\u7247 ${fileName} \u4E3A ${metadata.size} bytes\uFF1B\u5FC5\u987B\u5C0F\u4E8E 1048576 bytes\u3002\u8BF7\u5BFC\u51FA\u4E3A JPEG\u3001\u964D\u4F4E\u5C3A\u5BF8\u6216\u8D28\u91CF\uFF0C\u66F4\u65B0 visual-plan \u540E\u91CD\u65B0 checkpoint \u548C\u9884\u89C8\u3002`
+        );
+      }
+      if (role === "cover") {
+        throw new WechatCliError(
+          "DXC_PUBLISHING_COVER_TOO_LARGE",
+          `\u5C01\u9762 ${fileName} \u4E3A ${metadata.size} bytes\uFF1B\u4E0A\u9650\u4E3A ${maximumBytes} bytes\u3002\u8BF7\u964D\u4F4E\u5C3A\u5BF8\u6216\u8D28\u91CF\u540E\u91CD\u65B0 checkpoint \u548C\u9884\u89C8\u3002`
+        );
+      }
       throw new WechatCliError(
         "DXC_PUBLISHING_INPUT_INVALID",
-        `\u6587\u4EF6 ${path6.basename(target)} \u4E0D\u662F\u53EF\u8BFB\u53D6\u7684\u666E\u901A\u6587\u4EF6\uFF0C\u6216\u5927\u5C0F\u8D85\u51FA\u9650\u5236\u3002`
+        `\u6587\u4EF6 ${fileName} \u4E3A ${metadata.size} bytes\uFF0C\u8D85\u8FC7 ${maximumBytes} bytes \u7684\u9650\u5236\u3002`
+      );
+    }
+    if (!metadata.isFile() || metadata.size <= 0) {
+      throw new WechatCliError(
+        "DXC_PUBLISHING_INPUT_INVALID",
+        `\u6587\u4EF6 ${path6.basename(target)} \u4E0D\u662F\u53EF\u8BFB\u53D6\u7684\u975E\u7A7A\u666E\u901A\u6587\u4EF6\u3002`
       );
     }
     return {
@@ -31165,7 +31568,7 @@ async function readPublishingInput(inputPath, maximumBytes) {
     await handle?.close();
   }
 }
-async function readContainedPublishingInput(inputPath, maximumBytes, allowedDirectories) {
+async function readContainedPublishingInput(inputPath, maximumBytes, allowedDirectories, role) {
   try {
     const [target, ...directories] = await Promise.all([
       realpath(path6.resolve(inputPath)),
@@ -31189,7 +31592,7 @@ async function readContainedPublishingInput(inputPath, maximumBytes, allowedDire
       `\u65E0\u6CD5\u5B89\u5168\u89E3\u6790\u7D20\u6750 ${path6.basename(inputPath)}\u3002`
     );
   }
-  return readPublishingInput(inputPath, maximumBytes);
+  return readPublishingInput(inputPath, maximumBytes, role);
 }
 function publishingImageMediaType(inputPath) {
   const extension = path6.extname(inputPath).toLowerCase();
@@ -31226,7 +31629,7 @@ async function collectedImages(directoryInput, articleDirectory) {
   const directory = path6.resolve(directoryInput);
   let entries;
   try {
-    const metadata = await lstat4(directory);
+    const metadata = await lstat5(directory);
     if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
       throw new WechatCliError(
         "DXC_PUBLISHING_ASSETS_DIRECTORY_INVALID",
@@ -31260,6 +31663,13 @@ async function collectedImages(directoryInput, articleDirectory) {
   ).map((entry) => path6.join(directory, entry.name)).sort((left, right) => left.localeCompare(right, "zh-CN"));
 }
 function injectCollectedImages(source, images) {
+  const diagnosticText = (value, maximum = 120) => {
+    const sanitized = [...value].map((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint < 32 || codePoint >= 127 && codePoint <= 159 ? " " : character;
+    }).join("").trim();
+    return sanitized.length <= maximum ? sanitized : `${sanitized.slice(0, maximum)}\u2026`;
+  };
   if (images.length === 0) {
     return source;
   }
@@ -31285,9 +31695,11 @@ function injectCollectedImages(source, images) {
       const match = /^after-heading:(.+)$/u.exec(image.placementAnchor);
       const matches = match === null ? void 0 : headingLineByText.get(match[1]?.trim() ?? "");
       if (matches === void 0 || matches.length !== 1) {
+        const matchCount = matches?.length ?? 0;
+        const availableHeadings = [...headingLineByText.keys()].slice(0, 10).map((heading) => diagnosticText(heading)).join("\u3001").slice(0, 600);
         throw new WechatCliError(
           "DXC_PUBLISHING_VISUAL_ANCHOR_INVALID",
-          "\u89C6\u89C9\u8BA1\u5212\u7684\u63D2\u56FE\u951A\u70B9\u5FC5\u987B\u552F\u4E00\u5339\u914D\u6B63\u6587\u4E2D\u7684\u4E00\u4E2A\u4E8C\u7EA7\u6807\u9898\u3002"
+          `\u89C6\u89C9\u8BA1\u5212\u951A\u70B9 ${diagnosticText(image.placementAnchor, 180)} \u7684\u7CBE\u786E\u5339\u914D\u6570\u4E3A ${matchCount}\uFF1B\u5FC5\u987B\u552F\u4E00\u5339\u914D\u6B63\u6587\u4E2D\u7684\u4E00\u4E2A\u4E8C\u7EA7\u6807\u9898\u3002\u53EF\u7528\u6807\u9898\uFF1A${availableHeadings.length === 0 ? "\uFF08\u65E0\uFF09" : availableHeadings}\u3002\u8BF7\u590D\u5236\u6807\u9898\u539F\u6587\uFF08\u542B\u6807\u70B9\uFF09\u66F4\u65B0 placementAnchor\u3002`
         );
       }
       headingLine = matches[0];
@@ -31310,9 +31722,7 @@ function injectCollectedImages(source, images) {
 async function plannedInlineImages(visualPlanFile, availableByFileName) {
   let source;
   try {
-    source = (await readPublishingInput(visualPlanFile, VISUAL_PLAN_MAXIMUM_BYTES)).bytes.toString(
-      "utf8"
-    );
+    source = (await readPublishingInput(visualPlanFile, VISUAL_PLAN_MAXIMUM_BYTES, "visual-plan")).bytes.toString("utf8");
   } catch {
     throw new WechatCliError("DXC_PUBLISHING_VISUAL_PLAN_INVALID");
   }
@@ -31330,6 +31740,12 @@ async function plannedInlineImages(visualPlanFile, availableByFileName) {
   if (!parsed.success) {
     throw new WechatCliError("DXC_PUBLISHING_VISUAL_PLAN_INVALID");
   }
+  if (!("inlineAssets" in parsed.data)) {
+    throw new WechatCliError(
+      "DXC_PUBLISHING_VISUAL_PLAN_INVALID",
+      "\u89C6\u89C9\u8BA1\u5212\u4ECD\u5904\u4E8E\u751F\u6210\u524D\u6388\u6743\u9636\u6BB5\uFF1B\u8BF7\u5148\u5B8C\u6210\u56FE\u7247\u751F\u6210\u5E76\u5199\u5165 coverAsset/inlineAssets \u540E\u518D\u9884\u89C8\u3002"
+    );
+  }
   return Promise.all(
     parsed.data.inlineAssets.map(async (asset) => {
       const absolutePath = availableByFileName.get(path6.posix.basename(asset.path));
@@ -31339,7 +31755,11 @@ async function plannedInlineImages(visualPlanFile, availableByFileName) {
           `\u89C6\u89C9\u8BA1\u5212\u58F0\u660E\u7684\u7D20\u6750 ${path6.posix.basename(asset.path)} \u4E0D\u5728\u6307\u5B9A\u7D20\u6750\u76EE\u5F55\u4E2D\u3002`
         );
       }
-      const input = await readPublishingInput(absolutePath, MAXIMUM_INLINE_IMAGE_BYTES2);
+      const input = await readPublishingInput(
+        absolutePath,
+        MAXIMUM_INLINE_IMAGE_BYTES2,
+        "inline-image"
+      );
       if (createHash6("sha256").update(input.bytes).digest("hex") !== asset.sha256) {
         throw new WechatCliError(
           "DXC_PUBLISHING_VISUAL_PLAN_INVALID",
@@ -31456,7 +31876,8 @@ async function preparePublishingDraft(input) {
       const asset = await readContainedPublishingInput(
         target,
         MAXIMUM_INLINE_IMAGE_BYTES2,
-        automaticAssetDirectories
+        automaticAssetDirectories,
+        "inline-image"
       );
       return {
         ...asset,
@@ -31474,8 +31895,9 @@ async function preparePublishingDraft(input) {
   const cover = explicitCover === void 0 ? await readContainedPublishingInput(
     coverCandidate,
     MAXIMUM_IMAGE_BYTES,
-    automaticAssetDirectories
-  ) : await readPublishingInput(coverCandidate, MAXIMUM_IMAGE_BYTES);
+    automaticAssetDirectories,
+    "cover"
+  ) : await readPublishingInput(coverCandidate, MAXIMUM_IMAGE_BYTES, "cover");
   publishingImageMediaType(cover.path);
   return {
     article: {
@@ -31788,9 +32210,11 @@ async function checkedJson(response) {
   const value = await responseJson(response);
   if (!response.ok) {
     const apiError = apiErrorResponseSchema.safeParse(value);
-    throw new WechatCliError(
-      apiError.success ? apiError.data.error.code : "DXC_API_REQUEST_FAILED"
-    );
+    if (apiError.success) {
+      const guidance = apiError.data.error.code === "PUBLISHING_PREVIEW_REQUIRED" ? "\u670D\u52A1\u7AEF\u5C1A\u672A\u8BB0\u5F55\u4F60\u5B9E\u9645\u67E5\u770B\u8FC7\u6700\u7EC8\u9884\u89C8\u3002\u8BF7\u5BF9\u540C\u4E00 root \u5FEB\u7167\u8FD0\u884C preview-refresh --browser system\uFF0C\u786E\u8BA4\u7CFB\u7EDF\u6D4F\u89C8\u5668\u5DF2\u6253\u5F00\u9875\u9762\u540E\u518D\u521B\u5EFA\u8349\u7A3F\u3002" : apiError.data.error.message;
+      throw new WechatCliError(apiError.data.error.code, guidance, apiError.data.error.retryable);
+    }
+    throw new WechatCliError("DXC_API_REQUEST_FAILED");
   }
   return value;
 }
@@ -32120,8 +32544,6 @@ var WechatCli = class {
     );
     assertCompleteInlineAssets(prepared.inlineAssets, snapshot.inlineAssets);
     if (!snapshot.preflight.ok) {
-      output.writeStdout(`${JSON.stringify({ account, snapshot })}
-`);
       throw new WechatCliError("DXC_PUBLISHING_CLOUD_PREFLIGHT_FAILED");
     }
     const previewResponse = await this.#authenticatedFetch(
@@ -32134,7 +32556,7 @@ var WechatCli = class {
       }
     );
     const preview = publishingPreviewLinkSchema.parse(await checkedJson(previewResponse.response));
-    const browserMode = options.browserMode ?? "agent";
+    const browserMode = options.browserMode ?? "system";
     const result = {
       account,
       presentation: {
@@ -32181,7 +32603,7 @@ var WechatCli = class {
     const secondsRemaining = preview.expiresInSeconds ?? Math.max(0, Math.floor((Date.parse(preview.expiresAt) - Date.now()) / 1e3));
     output.writeStderr(`\u5DF2\u4E3A\u540C\u4E00\u4E2A\u4E0D\u53EF\u53D8\u5FEB\u7167\u91CD\u5EFA\u9884\u89C8\u94FE\u63A5\uFF0C\u5C06\u5728 ${secondsRemaining} \u79D2\u540E\u5931\u6548\u3002
 `);
-    await presentDraftPreview(output, this.#openExternal, preview, options.browserMode ?? "agent");
+    await presentDraftPreview(output, this.#openExternal, preview, options.browserMode ?? "system");
     return preview;
   }
   async createDraft(options, output) {
@@ -32735,12 +33157,22 @@ function previewBrowserMode(value) {
 function collectValues(value, previous) {
   return [...previous, value];
 }
-async function runWechatAction(context, action) {
+async function runWechatAction(context, action, json = false) {
   try {
     await action(new WechatCli(context.wechatDependencies));
   } catch (error) {
     const code = error instanceof WechatCliError ? error.code : "DXC_WECHAT_FAILED";
     const guidance = error instanceof WechatCliError ? error.guidance : void 0;
+    const retryable = error instanceof WechatCliError ? error.retryable : false;
+    if (json) {
+      writeJson(context, {
+        error: {
+          code,
+          message: guidance ?? code,
+          retryable
+        }
+      });
+    }
     context.writeStderr(`${code}${guidance === void 0 ? "" : `: ${guidance}`}
 `);
     context.setExitCode(1);
@@ -32768,7 +33200,7 @@ async function loadKnowledgeModule() {
     Reflect.apply(emitWarning, process, [warning2, ...arguments_]);
   });
   try {
-    return await import("./chunks/knowledge-PWFALFEC.js");
+    return await import("./chunks/knowledge-5Y22MFAV.js");
   } finally {
     process.emitWarning = emitWarning;
   }
@@ -32782,7 +33214,7 @@ async function loadMonitorModule() {
     Reflect.apply(emitWarning, process, [warning2, ...arguments_]);
   });
   try {
-    return await import("./chunks/monitor-CL5UXEO2.js");
+    return await import("./chunks/monitor-MZPF73LC.js");
   } finally {
     process.emitWarning = emitWarning;
   }
@@ -32850,7 +33282,8 @@ async function runMemoryAction(context, command, json, action) {
         error: { code, message },
         ok: false
       }),
-      code
+      code,
+      message
     );
   }
 }
@@ -32885,10 +33318,16 @@ async function runProjectAction(context, command, json, action) {
       json,
       contentProjectErrorResultSchema.parse({
         command,
-        error: { code, message },
+        error: {
+          code,
+          message,
+          ...error instanceof ProjectCliError ? error.details : {}
+        },
         ok: false
       }),
-      code
+      code,
+      message,
+      error instanceof ProjectCliError ? error.details.recovery : void 0
     );
   }
 }
@@ -33264,16 +33703,20 @@ ${hint}
   project.command("checkpoint").description("\u5199\u5165\u7EDF\u4E00\u7684\u9636\u6BB5 contract").argument("<stage>", "\u6B65\u9AA4\u540D\u79F0").requiredOption("--status <status>", "running / awaiting-user / completed / failed / skipped").option("--skill <name>", "\u7279\u6B8A\u63A5\u7BA1\u6D41\u7A0B\u4F7F\u7528\u7684 dxc-* Skill\uFF1B\u5E38\u89C4\u9636\u6BB5\u7531 catalog \u81EA\u52A8\u786E\u5B9A").option(
     "--skill-version <version>",
     "\u7279\u6B8A\u63A5\u7BA1\u6D41\u7A0B\u4F7F\u7528\u7684 Skill \u7248\u672C\uFF1B\u5E38\u89C4\u9636\u6BB5\u7531 catalog \u81EA\u52A8\u786E\u5B9A"
-  ).requiredOption("--summary <text>", "\u672C\u6B21\u9636\u6BB5\u72B6\u6001\u7684\u7B80\u77ED\u8BF4\u660E").option("--directory <path>", "\u9879\u76EE\u76EE\u5F55", ".").option("--inputs <stages>", "\u672C\u6B21\u989D\u5916\u8BFB\u53D6\u7684\u53EF\u9009\u8F93\u5165\uFF1B\u5FC5\u9700\u8F93\u5165\u7531 catalog \u81EA\u52A8\u8865\u9F50").option("--execution-location <location>", "local-device / agent-hosted / unknown", "unknown").option(
+  ).option("--summary <text>", "\u672C\u6B21\u9636\u6BB5\u72B6\u6001\u7684\u7B80\u77ED\u8BF4\u660E").option("--directory <path>", "\u9879\u76EE\u76EE\u5F55", ".").option("--inputs <stages>", "\u672C\u6B21\u989D\u5916\u8BFB\u53D6\u7684\u53EF\u9009\u8F93\u5165\uFF1B\u5FC5\u9700\u8F93\u5165\u7531 catalog \u81EA\u52A8\u8865\u9F50").option("--execution-location <location>", "local-device / agent-hosted / unknown", "unknown").option(
     "--data-transit <transit>",
     "local-only / agent-provider / dxc-cloud / unknown",
     "unknown"
-  ).option("--error-code <code>", "\u5931\u8D25\u65F6\u7684\u7A33\u5B9A\u9519\u8BEF\u7801").option("--waiting-for <prompt>", "awaiting-user \u72B6\u6001\u7B49\u5F85\u7528\u6237\u56DE\u7B54\u7684\u95EE\u9898").option("--confirm", "\u8BB0\u5F55\u7528\u6237\u5DF2\u786E\u8BA4\u8BE5\u6B65\u9AA4\u4EA7\u7269").option("--confirmed-by <actor>", "\u786E\u8BA4\u4EBA\u6216\u7A33\u5B9A\u8EAB\u4EFD\u6807\u8BC6", "local-interactive-user").option("--confirmation-snapshot <sha256>", "\u786E\u8BA4\u6240\u7ED1\u5B9A\u7684\u5FEB\u7167 SHA-256").option("--json", "\u8F93\u51FA JSON").action(
+  ).option("--error-code <code>", "\u5931\u8D25\u65F6\u7684\u7A33\u5B9A\u9519\u8BEF\u7801").option("--waiting-for <prompt>", "awaiting-user \u72B6\u6001\u7B49\u5F85\u7528\u6237\u56DE\u7B54\u7684\u95EE\u9898").option("--confirm", "\u8BB0\u5F55\u7528\u6237\u5DF2\u786E\u8BA4\u8BE5\u6B65\u9AA4\u4EA7\u7269").option(
+    "--authorization-purpose <purpose>",
+    "\u9636\u6BB5\u5185\u5916\u90E8\u52A8\u4F5C\u6388\u6743\uFF1B\u5F53\u524D\u4EC5 visual-plan \u652F\u6301 image-generation"
+  ).option("--confirmed-by <actor>", "\u786E\u8BA4\u4EBA\u6216\u7A33\u5B9A\u8EAB\u4EFD\u6807\u8BC6", "local-interactive-user").option("--confirmation-snapshot <sha256>", "\u786E\u8BA4\u6240\u7ED1\u5B9A\u7684\u5FEB\u7167 SHA-256").option("--json", "\u8F93\u51FA JSON").action(
     async (stage, options) => runProjectAction(
       context,
       "project.checkpoint",
       options.json === true,
       async (projectCli) => projectCli.checkpoint({
+        ...options.authorizationPurpose === void 0 ? {} : { authorizationPurpose: options.authorizationPurpose },
         confirmed: options.confirm === true,
         ...options.confirmedBy === void 0 ? {} : { confirmedBy: options.confirmedBy },
         ...options.confirmationSnapshot === void 0 ? {} : {
@@ -33294,7 +33737,7 @@ ${hint}
         ...options.skillVersion === void 0 ? {} : { skillVersion: options.skillVersion },
         stage,
         status: options.status,
-        summary: options.summary,
+        ...options.summary === void 0 ? {} : { summary: options.summary },
         ...options.waitingFor === void 0 ? {} : { waitingFor: options.waitingFor }
       })
     )
@@ -33456,9 +33899,13 @@ ${hint}
     })
   );
   auth.command("status").description("\u663E\u793A\u5F53\u524D\u8BBE\u5907\u3001\u7528\u6237\u548C\u5185\u5BB9\u7A7A\u95F4").option("--json", "\u8F93\u51FA JSON").action(
-    async () => runWechatAction(context, async (wechatCli) => {
-      await wechatCli.status(context);
-    })
+    async (options) => runWechatAction(
+      context,
+      async (wechatCli) => {
+        await wechatCli.status(context);
+      },
+      options.json === true
+    )
   );
   auth.command("logout").description("\u64A4\u9500\u5F53\u524D\u8BBE\u5907\u4F1A\u8BDD").action(
     async () => runWechatAction(context, async (wechatCli) => {
@@ -33479,149 +33926,195 @@ ${hint}
     })
   );
   wechat.command("accounts").description("\u5217\u51FA\u5DF2\u7ED1\u5B9A\u516C\u4F17\u53F7\u548C\u8349\u7A3F\u6743\u9650").option("--json", "\u8F93\u51FA JSON").action(
-    async (options) => runWechatAction(context, async (wechatCli) => {
-      await wechatCli.accounts(context, options.json === true);
-    })
+    async (options) => runWechatAction(
+      context,
+      async (wechatCli) => {
+        await wechatCli.accounts(context, options.json === true);
+      },
+      options.json === true
+    )
   );
   const draft = wechat.command("draft").description("\u9884\u89C8\u5E76\u521B\u5EFA\u5FAE\u4FE1\u516C\u4F17\u53F7\u8349\u7A3F");
-  draft.command("preview").description("\u91C7\u96C6\u5DF2\u751F\u6210\u6216\u9009\u62E9\u7684\u56FE\u7247\uFF0C\u5E76\u751F\u6210\u4E0D\u53EF\u53D8\u4E91\u7AEF\u9884\u89C8").requiredOption("--article <path>", "Markdown \u6587\u7AE0\u6587\u4EF6").option("--cover <path-or-auto>", "PNG/JPEG \u5185\u5BB9\u5C01\u9762\uFF1Bauto \u4ECE\u6587\u7AE0\u6216\u7D20\u6750\u76EE\u5F55\u89E3\u6790", "auto").option("--assets-directory <path>", "\u91C7\u96C6\u5E76\u5185\u8054\u8BE5\u76EE\u5F55\u4E2D\u5DF2\u51C6\u5907\u597D\u7684 PNG/JPEG").option("--visual-plan <path>", "\u6309\u89C6\u89C9\u8BA1\u5212\u7684\u7CBE\u786E\u7AE0\u8282\u951A\u70B9\u63D2\u5165\u5DF2\u58F0\u660E\u7684\u6B63\u6587\u56FE\u7247").requiredOption("--account <uuid>", "\u76EE\u6807\u516C\u4F17\u53F7\u8D26\u53F7 ID").option("--title <title>", "\u4F7F\u7528\u5DF2\u786E\u8BA4\u6807\u9898\u8986\u76D6\u6587\u7AE0 frontmatter \u6807\u9898").option("--browser <agent|system>", "\u4F18\u5148\u5728 Agent \u53F3\u4FA7\u9884\u89C8\uFF1B\u4E0D\u652F\u6301\u65F6\u53EF\u6539\u7528\u7CFB\u7EDF\u6D4F\u89C8\u5668", "agent").action(
-    async (options) => runWechatAction(context, async (wechatCli) => {
-      await wechatCli.previewDraft(
-        {
-          accountId: validatedOption(
-            options.account,
-            /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
-            "account"
-          ),
-          browserMode: previewBrowserMode(options.browser),
-          articleFile: resolveUserPath({
-            currentDirectory: context.currentDirectory,
-            homeDirectory: context.homeDirectory,
-            input: options.article
-          }),
-          ...options.assetsDirectory === void 0 ? {} : {
-            assetsDirectory: resolveUserPath({
-              currentDirectory: context.currentDirectory,
-              homeDirectory: context.homeDirectory,
-              input: options.assetsDirectory
-            })
-          },
-          ...options.cover === void 0 ? {} : {
-            coverFile: options.cover === "auto" ? "auto" : resolveUserPath({
+  draft.command("preview").description("\u91C7\u96C6\u5DF2\u751F\u6210\u6216\u9009\u62E9\u7684\u56FE\u7247\uFF0C\u5E76\u751F\u6210\u4E0D\u53EF\u53D8\u4E91\u7AEF\u9884\u89C8").requiredOption("--article <path>", "Markdown \u6587\u7AE0\u6587\u4EF6").option("--cover <path-or-auto>", "PNG/JPEG \u5185\u5BB9\u5C01\u9762\uFF1Bauto \u4ECE\u6587\u7AE0\u6216\u7D20\u6750\u76EE\u5F55\u89E3\u6790", "auto").option("--assets-directory <path>", "\u91C7\u96C6\u5E76\u5185\u8054\u8BE5\u76EE\u5F55\u4E2D\u5DF2\u51C6\u5907\u597D\u7684 PNG/JPEG").option("--visual-plan <path>", "\u6309\u89C6\u89C9\u8BA1\u5212\u7684\u7CBE\u786E\u7AE0\u8282\u951A\u70B9\u63D2\u5165\u5DF2\u58F0\u660E\u7684\u6B63\u6587\u56FE\u7247").requiredOption("--account <uuid>", "\u76EE\u6807\u516C\u4F17\u53F7\u8D26\u53F7 ID").option("--title <title>", "\u4F7F\u7528\u5DF2\u786E\u8BA4\u6807\u9898\u8986\u76D6\u6587\u7AE0 frontmatter \u6807\u9898").option(
+    "--browser <agent|system>",
+    "\u4F7F\u7528\u7CFB\u7EDF\u6D4F\u89C8\u5668\uFF1B\u5BBF\u4E3B\u5DF2\u8BC1\u660E\u652F\u6301\u53F3\u4FA7\u6D4F\u89C8\u5668\u65F6\u53EF\u663E\u5F0F\u4F7F\u7528 agent",
+    "system"
+  ).option("--json", "\u8F93\u51FA JSON\uFF1B\u5931\u8D25\u65F6\u4E5F\u5728 stdout \u8FD4\u56DE\u7ED3\u6784\u5316\u9519\u8BEF").action(
+    async (options) => runWechatAction(
+      context,
+      async (wechatCli) => {
+        await wechatCli.previewDraft(
+          {
+            accountId: validatedOption(
+              options.account,
+              /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
+              "account"
+            ),
+            browserMode: previewBrowserMode(options.browser),
+            articleFile: resolveUserPath({
               currentDirectory: context.currentDirectory,
               homeDirectory: context.homeDirectory,
-              input: options.cover
-            })
+              input: options.article
+            }),
+            ...options.assetsDirectory === void 0 ? {} : {
+              assetsDirectory: resolveUserPath({
+                currentDirectory: context.currentDirectory,
+                homeDirectory: context.homeDirectory,
+                input: options.assetsDirectory
+              })
+            },
+            ...options.cover === void 0 ? {} : {
+              coverFile: options.cover === "auto" ? "auto" : resolveUserPath({
+                currentDirectory: context.currentDirectory,
+                homeDirectory: context.homeDirectory,
+                input: options.cover
+              })
+            },
+            ...options.title === void 0 ? {} : { title: options.title },
+            ...options.visualPlan === void 0 ? {} : {
+              visualPlanFile: resolveUserPath({
+                currentDirectory: context.currentDirectory,
+                homeDirectory: context.homeDirectory,
+                input: options.visualPlan
+              })
+            }
           },
-          ...options.title === void 0 ? {} : { title: options.title },
-          ...options.visualPlan === void 0 ? {} : {
-            visualPlanFile: resolveUserPath({
-              currentDirectory: context.currentDirectory,
-              homeDirectory: context.homeDirectory,
-              input: options.visualPlan
-            })
-          }
-        },
-        context
-      );
-    })
+          context
+        );
+      },
+      options.json === true
+    )
   );
-  draft.command("preview-refresh").description("\u4E3A\u540C\u4E00\u4E2A\u4E0D\u53EF\u53D8\u5FEB\u7167\u91CD\u5EFA\u77ED\u65F6\u9884\u89C8\u94FE\u63A5").option("--snapshot <uuid>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 ID").option("--snapshot-hash <sha256>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 SHA-256").option("--browser <agent|system>", "\u4F18\u5148\u5728 Agent \u53F3\u4FA7\u9884\u89C8\uFF1B\u4E0D\u652F\u6301\u65F6\u53EF\u6539\u7528\u7CFB\u7EDF\u6D4F\u89C8\u5668", "agent").action(
-    async (options) => runWechatAction(context, async (wechatCli) => {
-      const missing = [
-        ...options.snapshot === void 0 ? ["--snapshot"] : [],
-        ...options.snapshotHash === void 0 ? ["--snapshot-hash"] : []
-      ];
-      if (missing.length > 0) {
-        throw new WechatCliError(
-          "DXC_PREVIEW_REFRESH_OPTIONS_REQUIRED",
-          `\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570\uFF1A${missing.join("\u3001")}\u3002`
+  draft.command("preview-refresh").description("\u4E3A\u540C\u4E00\u4E2A\u4E0D\u53EF\u53D8\u5FEB\u7167\u91CD\u5EFA\u77ED\u65F6\u9884\u89C8\u94FE\u63A5").option("--snapshot <uuid>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 ID").option("--snapshot-hash <sha256>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 SHA-256").option(
+    "--browser <agent|system>",
+    "\u4F7F\u7528\u7CFB\u7EDF\u6D4F\u89C8\u5668\uFF1B\u5BBF\u4E3B\u5DF2\u8BC1\u660E\u652F\u6301\u53F3\u4FA7\u6D4F\u89C8\u5668\u65F6\u53EF\u663E\u5F0F\u4F7F\u7528 agent",
+    "system"
+  ).option("--json", "\u8F93\u51FA JSON\uFF1B\u5931\u8D25\u65F6\u4E5F\u5728 stdout \u8FD4\u56DE\u7ED3\u6784\u5316\u9519\u8BEF").action(
+    async (options) => runWechatAction(
+      context,
+      async (wechatCli) => {
+        const missing = [
+          ...options.snapshot === void 0 ? ["--snapshot"] : [],
+          ...options.snapshotHash === void 0 ? ["--snapshot-hash"] : []
+        ];
+        if (missing.length > 0) {
+          throw new WechatCliError(
+            "DXC_PREVIEW_REFRESH_OPTIONS_REQUIRED",
+            `\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570\uFF1A${missing.join("\u3001")}\u3002`
+          );
+        }
+        if (options.snapshot === void 0 || options.snapshotHash === void 0) {
+          throw new WechatCliError("DXC_PREVIEW_REFRESH_OPTIONS_REQUIRED");
+        }
+        await wechatCli.refreshDraftPreview(
+          {
+            browserMode: previewBrowserMode(options.browser),
+            snapshotHash: validatedOption(
+              options.snapshotHash,
+              /^[a-f0-9]{64}$/u,
+              "snapshot-hash"
+            ),
+            snapshotId: validatedOption(
+              options.snapshot,
+              /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
+              "snapshot"
+            )
+          },
+          context
         );
-      }
-      if (options.snapshot === void 0 || options.snapshotHash === void 0) {
-        throw new WechatCliError("DXC_PREVIEW_REFRESH_OPTIONS_REQUIRED");
-      }
-      await wechatCli.refreshDraftPreview(
-        {
-          browserMode: previewBrowserMode(options.browser),
-          snapshotHash: validatedOption(
-            options.snapshotHash,
-            /^[a-f0-9]{64}$/u,
-            "snapshot-hash"
-          ),
-          snapshotId: validatedOption(
-            options.snapshot,
-            /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
-            "snapshot"
-          )
-        },
-        context
-      );
-    })
+      },
+      options.json === true
+    )
   );
-  draft.command("create").description("\u786E\u8BA4\u4E0D\u53EF\u53D8\u5FEB\u7167\u548C\u76EE\u6807\u516C\u4F17\u53F7\u540E\u521B\u5EFA\u8349\u7A3F\u610F\u56FE").option("--account <uuid>", "\u76EE\u6807\u516C\u4F17\u53F7\u8D26\u53F7 ID").option("--snapshot <uuid>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 ID").option("--snapshot-hash <sha256>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 SHA-256").option("--idempotency-key <key>", "\u672C\u6B21\u8349\u7A3F\u610F\u56FE\u7684\u5E42\u7B49\u952E").option("--delivery <path>", "\u5199\u56DE\u6700\u7EC8\u9009\u4E2D\u5FEB\u7167\u7684 delivery \u9636\u6BB5\u4EA7\u7269").option("--confirm", "\u786E\u8BA4\u9884\u89C8\u5FEB\u7167\u548C\u76EE\u6807\u516C\u4F17\u53F7").action(
-    async (options) => runWechatAction(context, async (wechatCli) => {
-      const missing = [
-        ...options.account === void 0 ? ["--account"] : [],
-        ...options.snapshot === void 0 ? ["--snapshot"] : [],
-        ...options.snapshotHash === void 0 ? ["--snapshot-hash"] : [],
-        ...options.idempotencyKey === void 0 ? ["--idempotency-key"] : []
-      ];
-      if (missing.length > 0) {
-        throw new WechatCliError(
-          "DXC_DRAFT_OPTIONS_REQUIRED",
-          `\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570\uFF1A${missing.join("\u3001")}\u3002`
+  draft.command("create").description("\u786E\u8BA4\u4E0D\u53EF\u53D8\u5FEB\u7167\u548C\u76EE\u6807\u516C\u4F17\u53F7\u540E\u521B\u5EFA\u8349\u7A3F\u610F\u56FE").option("--account <uuid>", "\u76EE\u6807\u516C\u4F17\u53F7\u8D26\u53F7 ID").option("--snapshot <uuid>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 ID").option("--snapshot-hash <sha256>", "\u4E0D\u53EF\u53D8\u5FEB\u7167 SHA-256").option("--idempotency-key <key>", "\u672C\u6B21\u8349\u7A3F\u610F\u56FE\u7684\u5E42\u7B49\u952E").option("--delivery <path>", "\u5199\u56DE\u6700\u7EC8\u9009\u4E2D\u5FEB\u7167\u7684 delivery \u9636\u6BB5\u4EA7\u7269").option("--confirm", "\u786E\u8BA4\u9884\u89C8\u5FEB\u7167\u548C\u76EE\u6807\u516C\u4F17\u53F7").option("--json", "\u8F93\u51FA JSON\uFF1B\u5931\u8D25\u65F6\u4E5F\u5728 stdout \u8FD4\u56DE\u7ED3\u6784\u5316\u9519\u8BEF").action(
+    async (options) => runWechatAction(
+      context,
+      async (wechatCli) => {
+        const deliveryFile = options.delivery === void 0 ? void 0 : resolveUserPath({
+          currentDirectory: context.currentDirectory,
+          homeDirectory: context.homeDirectory,
+          input: options.delivery
+        });
+        let deliveryIdentity;
+        if (deliveryFile !== void 0) {
+          try {
+            deliveryIdentity = await readDeliveryDraftIdentity(deliveryFile);
+          } catch (error) {
+            throw new WechatCliError(
+              "DXC_DRAFT_DELIVERY_INVALID",
+              error instanceof StageArtifactValidationError ? error.message : "\u65E0\u6CD5\u8BFB\u53D6 delivery \u9636\u6BB5\u4EA7\u7269\u3002"
+            );
+          }
+        }
+        const missing = [
+          ...options.account === void 0 ? ["--account"] : [],
+          ...options.snapshot === void 0 ? ["--snapshot"] : [],
+          ...options.snapshotHash === void 0 ? ["--snapshot-hash"] : [],
+          ...options.idempotencyKey === void 0 && deliveryIdentity === void 0 ? ["--idempotency-key \u6216 --delivery"] : []
+        ];
+        if (missing.length > 0) {
+          throw new WechatCliError(
+            "DXC_DRAFT_OPTIONS_REQUIRED",
+            `\u7F3A\u5C11\u5FC5\u586B\u53C2\u6570\uFF1A${missing.join("\u3001")}\u3002`
+          );
+        }
+        const account = options.account;
+        const snapshot = options.snapshot;
+        const snapshotHash = options.snapshotHash;
+        const idempotencyKey = options.idempotencyKey ?? deliveryIdentity?.idempotencyKey;
+        if (account === void 0 || snapshot === void 0 || snapshotHash === void 0 || idempotencyKey === void 0) {
+          throw new WechatCliError("DXC_DRAFT_OPTIONS_REQUIRED");
+        }
+        if (deliveryIdentity !== void 0 && (deliveryIdentity.accountId !== account || deliveryIdentity.rootSnapshotId !== snapshot || deliveryIdentity.rootSnapshotHash !== snapshotHash || options.idempotencyKey !== void 0 && options.idempotencyKey !== deliveryIdentity.idempotencyKey)) {
+          throw new WechatCliError(
+            "DXC_DRAFT_DELIVERY_MISMATCH",
+            "\u547D\u4EE4\u4E2D\u7684\u516C\u4F17\u53F7\u3001root \u5FEB\u7167\u6216\u5E42\u7B49\u952E\u4E0E delivery \u9636\u6BB5\u4EA7\u7269\u4E0D\u4E00\u81F4\uFF1B\u5DF2\u5728\u4EFB\u4F55\u670D\u52A1\u7AEF\u8BF7\u6C42\u524D\u505C\u6B62\u3002"
+          );
+        }
+        await wechatCli.createDraft(
+          {
+            accountId: validatedOption(
+              account,
+              /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
+              "account"
+            ),
+            confirmed: options.confirm === true,
+            ...deliveryFile === void 0 ? {} : {
+              deliveryFile
+            },
+            idempotencyKey: validatedOption(
+              idempotencyKey,
+              /^[A-Za-z0-9._:-]{16,128}$/u,
+              "idempotency-key"
+            ),
+            snapshotHash: validatedOption(snapshotHash, /^[a-f0-9]{64}$/u, "snapshot-hash"),
+            snapshotId: validatedOption(
+              snapshot,
+              /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
+              "snapshot"
+            )
+          },
+          context
         );
-      }
-      const account = options.account;
-      const snapshot = options.snapshot;
-      const snapshotHash = options.snapshotHash;
-      const idempotencyKey = options.idempotencyKey;
-      if (account === void 0 || snapshot === void 0 || snapshotHash === void 0 || idempotencyKey === void 0) {
-        throw new WechatCliError("DXC_DRAFT_OPTIONS_REQUIRED");
-      }
-      await wechatCli.createDraft(
-        {
-          accountId: validatedOption(
-            account,
+      },
+      options.json === true
+    )
+  );
+  draft.command("status").description("\u67E5\u8BE2\u8349\u7A3F\u610F\u56FE\u72B6\u6001\u548C\u5FAE\u4FE1\u56DE\u8BFB\u7ED3\u679C").argument("<intent-id>", "\u8349\u7A3F\u610F\u56FE ID").option("--json", "\u8F93\u51FA JSON\uFF1B\u5931\u8D25\u65F6\u4E5F\u5728 stdout \u8FD4\u56DE\u7ED3\u6784\u5316\u9519\u8BEF").action(
+    async (intentId, options) => runWechatAction(
+      context,
+      async (wechatCli) => {
+        await wechatCli.publishingDraftStatus(
+          validatedOption(
+            intentId,
             /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
-            "account"
+            "intent-id"
           ),
-          confirmed: options.confirm === true,
-          ...options.delivery === void 0 ? {} : {
-            deliveryFile: resolveUserPath({
-              currentDirectory: context.currentDirectory,
-              homeDirectory: context.homeDirectory,
-              input: options.delivery
-            })
-          },
-          idempotencyKey: validatedOption(
-            idempotencyKey,
-            /^[A-Za-z0-9._:-]{16,128}$/u,
-            "idempotency-key"
-          ),
-          snapshotHash: validatedOption(snapshotHash, /^[a-f0-9]{64}$/u, "snapshot-hash"),
-          snapshotId: validatedOption(
-            snapshot,
-            /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
-            "snapshot"
-          )
-        },
-        context
-      );
-    })
-  );
-  draft.command("status").description("\u67E5\u8BE2\u8349\u7A3F\u610F\u56FE\u72B6\u6001\u548C\u5FAE\u4FE1\u56DE\u8BFB\u7ED3\u679C").argument("<intent-id>", "\u8349\u7A3F\u610F\u56FE ID").action(
-    async (intentId) => runWechatAction(context, async (wechatCli) => {
-      await wechatCli.publishingDraftStatus(
-        validatedOption(
-          intentId,
-          /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu,
-          "intent-id"
-        ),
-        context
-      );
-    })
+          context
+        );
+      },
+      options.json === true
+    )
   );
   draft.command("smoke-preview").description("\u83B7\u53D6\u56FA\u5B9A\u6D4B\u8BD5\u8349\u7A3F\u7684\u4E0D\u53EF\u53D8\u9884\u89C8").requiredOption("--account <uuid>", "\u76EE\u6807\u516C\u4F17\u53F7\u8D26\u53F7 ID").action(
     async (options) => runWechatAction(context, async (wechatCli) => {
@@ -33676,6 +34169,15 @@ async function runCli(arguments_, context = processContext()) {
     await program2.parseAsync([...arguments_]);
   } catch (error) {
     if (error instanceof CommanderError) {
+      if (arguments_.includes("--json")) {
+        writeJson(context, {
+          error: {
+            code: error.code || "DXC_CLI_OPTIONS_INVALID",
+            message: error.message,
+            retryable: false
+          }
+        });
+      }
       context.setExitCode(error.exitCode);
       return;
     }