gaoding-cli 1.0.0-alpha.19 → 1.0.0-alpha.21

package/README.md

@@ -31,7 +31,7 @@ gd-cli model list --tool <tool>
 gd-cli model get <model>
 ```
 
-选定 Model 后，以 `model get` 返回的 `parameters` 与 `usageDescription` 构造实际输入；`tool call --schema` 只给出整个 Tool 的参数并集。运行 `gd-cli --help` 查看当前命令；运行任一命令的 `--help` 查看参数。`gd-cli update` 固定检查 npm `latest`，支持更新 npm、pnpm 全局安装并同步 Agent Skill。
+选定 Model 后，以 `model get` 返回的 `parameters` 与 `usageDescription` 构造实际输入；其中 `cost` 是当前上架 SKU 的稿豆价格区间，不表示某次调用的实际扣费。`tool call --schema` 只给出整个 Tool 的参数并集。运行 `gd-cli --help` 查看当前命令；运行任一命令的 `--help` 查看参数。`gd-cli update` 固定检查 npm `latest`，支持更新 npm、pnpm 全局安装并同步 Agent Skill。
 
 发布切换必须先完成精确版本的安装验收，再执行仓库中的 `scripts/promote-latest.mjs`；不要直接用未校验的 `npm dist-tag add` 移动 `latest`。
 

package/dist/src/bootstrap/create-runtime.js

@@ -40,7 +40,7 @@ const productionEndpoints = {
     toolApi: new URL("https://gdcli.gaoding.com/api"),
     damApi: new URL("https://gdcli.gaoding.com/api"),
     ssoApi: new URL("https://www.gaoding.com/api/sso"),
-    authPageOrigin: new URL("https://www.gaoding.com")
+    authPageOrigin: new URL("https://www.gaoding.art")
 };
 export function createProductionRuntime(options = {}) {
     const bundledSkills = loadBundledSkills(fileURLToPath(import.meta.url));

package/dist/src/cli/errors.js

@@ -25,6 +25,12 @@ export class CliUsageError extends Error {
         this.name = "CliUsageError";
     }
 }
+const INSUFFICIENT_CREDITS_REMOTE_CODE = "12020770";
+const INSUFFICIENT_CREDITS_NEXT_STEPS = [
+    "前往 https://www.gaoding.art/pricing 购买稿豆",
+    "也可以执行 gd-cli org switch 切换到有可用稿豆的组织",
+    "处理后重新发起本次创作"
+];
 export function isHelpOutcome(error) {
     return error instanceof CommanderError
         && error.exitCode === 0
@@ -62,6 +68,9 @@ export function mapCliError(error, options) {
         || error instanceof CommanderError) {
         return failure("USAGE_ERROR", "命令或参数无效，请查看 --help。", 2);
     }
+    if (isInsufficientCreditsError(error)) {
+        return failure("INSUFFICIENT_CREDITS", "当前组织稿豆不足，无法完成本次创作。", 1, INSUFFICIENT_CREDITS_NEXT_STEPS);
+    }
     if (error instanceof RemoteProtocolError) {
         return failure("REMOTE_PROTOCOL_INCOMPATIBLE", "稿定服务返回了当前 CLI 无法安全处理的结果；为避免重复创作，已停止处理。", 1);
     }
@@ -89,6 +98,11 @@ export function mapCliError(error, options) {
     }
     return failure("INTERNAL_ERROR", "CLI 发生内部错误。", 1);
 }
+function isInsufficientCreditsError(error) {
+    return (error instanceof RemoteRequestError
+        || error instanceof RemoteProtocolError
+        || error instanceof ToolTaskFailedError) && error.remoteCode === INSUFFICIENT_CREDITS_REMOTE_CODE;
+}
 export function classifyTelemetryError(error) {
     const outcome = mapCliError(error, { aborted: false });
     const remoteError = error instanceof RemoteRequestError

package/dist/src/features/editor/bridge-client.js

@@ -6,6 +6,12 @@ export class EditorBridgeError extends Error {
         this.code = code;
     }
 }
+export class EditorBridgeUnavailableError extends Error {
+    constructor() {
+        super("Editor Bridge is unavailable.");
+        this.name = "EditorBridgeUnavailableError";
+    }
+}
 export function createEditorBridgeClient(options) {
     const fetch = options.fetch ?? globalThis.fetch;
     const baseUrl = `http://127.0.0.1:${options.state.port}`;
@@ -28,8 +34,7 @@ export function createEditorBridgeClient(options) {
         async rpc(method, payload, signal) {
             const value = await request("/rpc", "POST", { method, ...(payload === undefined ? {} : { payload }) }, signal);
             if (!isRecord(value) ||
-                !hasExactKeys(value, ["result"]) ||
-                !("result" in value)) {
+                (!hasExactKeys(value, []) && !hasExactKeys(value, ["result"]))) {
                 throw invalidResponse();
             }
             return value.result;
@@ -44,16 +49,24 @@ export function createEditorBridgeClient(options) {
         }
     };
     async function request(pathname, method, body, signal) {
-        const response = await fetch(`${baseUrl}${pathname}`, {
-            method,
-            headers: {
-                Authorization: `Bearer ${options.state.token}`,
-                ...(body === undefined ? {} : { "Content-Type": "application/json" })
-            },
-            redirect: "error",
-            signal,
-            ...(body === undefined ? {} : { body: JSON.stringify(body) })
-        });
+        signal.throwIfAborted();
+        let response;
+        try {
+            response = await fetch(`${baseUrl}${pathname}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${options.state.token}`,
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" })
+                },
+                redirect: "error",
+                signal,
+                ...(body === undefined ? {} : { body: JSON.stringify(body) })
+            });
+        }
+        catch {
+            signal.throwIfAborted();
+            throw new EditorBridgeUnavailableError();
+        }
         let value;
         try {
             value = await response.json();

package/dist/src/features/editor/bridge-server.js

@@ -2,10 +2,12 @@ import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
 import { EDITOR_PROTOCOL_VERSION } from "./protocol.js";
+const DEFAULT_RPC_TIMEOUT_MS = 60_000;
 export async function startEditorBridge(options) {
     const token = options.token ?? randomBytes(32).toString("hex");
     const now = options.now ?? (() => new Date());
     const nextRequestId = options.requestId ?? randomUUID;
+    const rpcTimeoutMs = Math.max(0, options.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS);
     const webSockets = new WebSocketServer({ noServer: true });
     let pageSocket = null;
     let pending;
@@ -69,13 +71,14 @@ export async function startEditorBridge(options) {
             const pageResponse = parseResponseMessage(message);
             if (!pageResponse || pageResponse.requestId !== pending?.requestId)
                 return;
-            const response = pending.response;
-            pending = undefined;
+            const current = takePending(pageResponse.requestId);
+            if (!current)
+                return;
             if (pageResponse.error) {
-                sendJson(response, 422, { error: pageResponse.error });
+                sendJson(current.response, 422, { error: pageResponse.error });
             }
             else {
-                sendJson(response, 200, { result: pageResponse.result });
+                sendJson(current.response, 200, { result: pageResponse.result });
             }
         });
         socket.on("error", () => {
@@ -143,7 +146,14 @@ export async function startEditorBridge(options) {
             }
             const requestId = nextRequestId();
             const socket = pageSocket;
-            pending = { requestId, response };
+            const timer = setTimeout(() => {
+                const current = takePending(requestId);
+                if (!current)
+                    return;
+                sendError(current.response, 504, "EDITOR_RPC_TIMEOUT", "The Editor page did not respond in time.");
+                setImmediate(() => void close());
+            }, rpcTimeoutMs);
+            pending = { requestId, response, timer };
             const message = {
                 type: "request",
                 requestId,
@@ -152,16 +162,19 @@ export async function startEditorBridge(options) {
             };
             try {
                 socket.send(JSON.stringify(message), (error) => {
-                    if (!error || pending?.requestId !== requestId)
+                    if (!error)
                         return;
-                    pending = undefined;
-                    sendError(response, 503, "EDITOR_DISCONNECTED", "The Editor page disconnected.");
+                    const current = takePending(requestId);
+                    if (!current)
+                        return;
+                    sendError(current.response, 503, "EDITOR_DISCONNECTED", "The Editor page disconnected.");
                 });
             }
             catch {
-                if (pending?.requestId === requestId)
-                    pending = undefined;
-                sendError(response, 503, "EDITOR_DISCONNECTED", "The Editor page disconnected.");
+                const current = takePending(requestId);
+                if (current) {
+                    sendError(current.response, 503, "EDITOR_DISCONNECTED", "The Editor page disconnected.");
+                }
             }
             return;
         }
@@ -172,12 +185,20 @@ export async function startEditorBridge(options) {
         }
         sendError(response, 404, "NOT_FOUND", "Editor Bridge route not found.");
     }
+    function takePending(requestId) {
+        if (!pending || (requestId !== undefined && pending.requestId !== requestId)) {
+            return undefined;
+        }
+        const current = pending;
+        pending = undefined;
+        clearTimeout(current.timer);
+        return current;
+    }
     function failPending(status, code, message) {
-        if (!pending)
+        const current = takePending();
+        if (!current)
             return;
-        const response = pending.response;
-        pending = undefined;
-        sendError(response, status, code, message);
+        sendError(current.response, status, code, message);
     }
     function close() {
         if (closing)

package/dist/src/features/editor/public-url.js

@@ -0,0 +1,36 @@
+import { isSensitiveKey } from "../../platform/redact.js";
+const PRIVATE_SEGMENTS = new Set([
+    "token",
+    "signature",
+    "secret",
+    "password",
+    "credential",
+    "credentials"
+]);
+const PRIVATE_FOCUSED_KEYS = new Set([
+    "focused-editor-token",
+    "focused-editor-port"
+]);
+export function toPublicEditorUrl(input) {
+    const output = new URL(input.href);
+    removePrivateParameters(output.searchParams);
+    const fragment = output.hash.slice(1);
+    if (fragment.includes("=") || fragment.includes("&")) {
+        const parameters = new URLSearchParams(fragment);
+        removePrivateParameters(parameters);
+        output.hash = parameters.toString();
+    }
+    return output;
+}
+function removePrivateParameters(parameters) {
+    for (const key of new Set(parameters.keys())) {
+        if (isPrivateKey(key))
+            parameters.delete(key);
+    }
+}
+function isPrivateKey(key) {
+    const lower = key.toLowerCase();
+    if (isSensitiveKey(key) || PRIVATE_FOCUSED_KEYS.has(lower))
+        return true;
+    return lower.split(/[-_.]+/u).some((part) => PRIVATE_SEGMENTS.has(part));
+}

package/dist/src/features/editor/session.js

@@ -1,5 +1,6 @@
-import { createEditorBridgeClient } from "./bridge-client.js";
+import { createEditorBridgeClient, EditorBridgeUnavailableError } from "./bridge-client.js";
 import { startEditorBridgeProcess } from "./bridge-process.js";
+import { toPublicEditorUrl } from "./public-url.js";
 const DEFAULT_CREATE_URL = new URL("https://www.gaoding.art/editor/canvas?mode=create&type=board");
 const DEFAULT_WORK_URL = new URL("https://www.gaoding.art/editor/canvas");
 const DEFAULT_CONNECTION_TIMEOUT_MS = 60_000;
@@ -14,7 +15,7 @@ export class EditorTargetError extends Error {
 export class EditorSessionNotFoundError extends Error {
     code = "EDITOR_SESSION_NOT_FOUND";
     constructor() {
-        super("当前没有 Editor 会话。");
+        super("当前没有可用的 Editor 会话，请重新执行 gd-cli editor connect [target]。");
         this.name = "EditorSessionNotFoundError";
     }
 }
@@ -58,7 +59,7 @@ export function createEditorSession(dependencies) {
                 await cleanupFailedSession(state);
                 throw cause;
             }
-            return { target: targetUrl.href };
+            return { target: toPublicEditorUrl(targetUrl).href };
         },
         async disconnect(signal) {
             signal.throwIfAborted();
@@ -71,8 +72,7 @@ export function createEditorSession(dependencies) {
             }
             catch (cause) {
                 signal.throwIfAborted();
-                await dependencies.store.removeIfOwned(state.token);
-                throw cause;
+                await throwUnavailableSession(cause, state);
             }
             await client.disconnect(signal);
             await dependencies.store.removeIfOwned(state.token);
@@ -83,9 +83,21 @@ export function createEditorSession(dependencies) {
             const state = await dependencies.store.read();
             if (state === null)
                 throw new EditorSessionNotFoundError();
-            return createClient(state).rpc(method, payload, signal);
+            try {
+                return await createClient(state).rpc(method, payload, signal);
+            }
+            catch (cause) {
+                signal.throwIfAborted();
+                await throwUnavailableSession(cause, state);
+            }
         }
     };
+    async function throwUnavailableSession(cause, state) {
+        if (!(cause instanceof EditorBridgeUnavailableError))
+            throw cause;
+        await dependencies.store.removeIfOwned(state.token);
+        throw new EditorSessionNotFoundError();
+    }
     async function replaceCurrentSession(signal) {
         const current = await dependencies.store.read();
         if (current === null)
@@ -96,6 +108,8 @@ export function createEditorSession(dependencies) {
         }
         catch (cause) {
             signal.throwIfAborted();
+            if (!(cause instanceof EditorBridgeUnavailableError))
+                throw cause;
             await dependencies.store.removeIfOwned(current.token);
             return;
         }

package/dist/src/features/editor/use-cases.js

@@ -2,7 +2,9 @@ import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { OutputContractError } from "../../bootstrap/validators.js";
+import { toPublicEditorUrl } from "./public-url.js";
 const PNG_DATA_URL_PREFIX = "data:image/png;base64,";
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const STRICT_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 export function createEditorUseCases(dependencies) {
     const validate = dependencies.validate;
@@ -40,7 +42,13 @@ export function createEditorUseCases(dependencies) {
             return result;
         },
         async save({ signal }) {
-            const result = await dependencies.session.rpc("save", undefined, signal);
+            const raw = await dependencies.session.rpc("save", undefined, signal);
+            validate.save(raw);
+            const url = safeEditorResultUrl(raw.url);
+            const result = {
+                ...raw,
+                url: toPublicEditorUrl(url).href
+            };
             validate.save(result);
             return result;
         }
@@ -57,5 +65,24 @@ function decodePngDataUrl(value) {
     const bytes = Buffer.from(encoded, "base64");
     if (bytes.toString("base64") !== encoded)
         throw new OutputContractError();
+    if (bytes.length < PNG_SIGNATURE.length ||
+        !bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+        throw new OutputContractError();
+    }
     return bytes;
 }
+function safeEditorResultUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new OutputContractError();
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username !== "" ||
+        url.password !== "") {
+        throw new OutputContractError();
+    }
+    return url;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaoding-cli",
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.21",
   "description": "Gaoding command-line interface for agents and people.",
   "type": "module",
   "license": "MIT",

package/skills/gd-cli/references/editor.md

@@ -1,12 +1,252 @@
 # AI+ Editor
 
-只操作当前连接的作品，并在修改前后读取真实画布状态。
+## 使用边界
 
-1. 用 `gd-cli editor connect [target]` 打开并连接作品；`target` 可以是作品 ID 或完整 URL，省略时打开新作品。
-2. 用 `gd-cli editor snapshot` 读取元素与选择状态。
-3. 把有序元素操作写入 JSON，再用 `gd-cli editor apply --input actions.json` 应用；也可用 `--input -`。
-4. 再次执行 `gd-cli editor snapshot`，必要时执行 `gd-cli editor screenshot` 做视觉复核。
-5. 用 `gd-cli editor save` 保存；需要机器可读结果时仅对支持的命令使用 `--json`。
-6. 完成后用 `gd-cli editor disconnect` 断开连接。
+使用 `gd-cli editor` 读取和操作浏览器中当前一个 AI+ Editor 作品。当前版本只支持一个 Editor Session、当前 Page 的直属 Shape 和 Connector，以及单操作者串行操作。
 
-不要在未读取快照时猜测元素 ID。修改结果与目标不符时，先重新读取快照或截图，再生成下一组操作。
+支持的 Shape：
+
+- `rectangle`
+- `rounded-rectangle`
+- `triangle-up`
+- `ellipse`
+- `diamond`
+
+Connector 必须从一个 Shape 绑定到另一个 Shape，`lineType` 只支持 `straight` 和 `elbowed`。当前不支持 Group、图片、视频、独立文本、嵌套元素、自由 Connector、半绑定 Connector、Connector label、端点坐标、选择修改或页面管理。
+
+当前 Page 只要包含不支持的直属元素，`snapshot`、`apply` 和 `screenshot` 都会返回 `UNSUPPORTED_PAGE_CONTENT`。此时停止操作，让用户换用空白或专用 Page；保留原作品内容。
+
+## 标准流程
+
+按以下闭环执行，完成标准是保存后得到 `workId` 和公开作品 URL：
+
+1. 建立 Session。target 省略时在线上新建 Board；纯数字按线上作品 ID 打开；完整 HTTP/HTTPS URL 按该 URL 的环境打开：
+
+   ```bash
+   gd-cli editor connect
+   gd-cli editor connect 37428738696269847
+   gd-cli editor connect "http://my.gaoding.art:3000/?mode=create&type=board"
+   ```
+
+   三种形式只选与目标匹配的一种。`connect` 只有在页面已连接，且浏览器 AI+ 登录、作品加载、Board 类型、编辑/保存权限和内容检查全部通过后才成功。连接失败时停止作图。
+
+2. 读取当前 Page：
+
+   ```bash
+   gd-cli editor snapshot
+   ```
+
+3. 根据 Snapshot 生成完整、有序的 Action JSON 数组，通过文件或 stdin 应用：
+
+   ```bash
+   gd-cli editor apply --input actions.json
+   # 或
+   gd-cli editor apply --input -
+   ```
+
+4. 每次 Apply 后都重新读取结构。只要涉及布局、文字或 Connector，再获取截图并打开实际 PNG 复查：
+
+   ```bash
+   gd-cli editor snapshot
+   gd-cli editor screenshot --json
+   ```
+
+   `screenshot --json` 返回 `{ "path": "<绝对 PNG 路径>" }`。使用本地图片查看能力检查图片；文件存在或 Action 已提交都不代表渲染正确。
+
+5. 结构和视觉复查均通过后显式保存：
+
+   ```bash
+   gd-cli editor save --json
+   ```
+
+   成功 stdout 形如：
+
+   ```json
+   {
+     "workId": "37428738696269847",
+     "url": "https://www.gaoding.art/editor/canvas?mode=user&type=board&id=37428738696269847"
+   }
+   ```
+
+   只有该命令成功才可以声明作品已保存。新 Board 在第一次显式保存时创建作品 ID；把返回的公开 `url` 交给用户，并保留其中的环境参数。
+
+6. 保存成功后断开 Session：
+
+   ```bash
+   gd-cli editor disconnect
+   ```
+
+`connect` 会替换旧 Session 并打开作品页面。连接前置检查失败会清理本次 Session，但保留浏览器页面；用户在页面中完成登录或处理访问权限后，再重新执行 `connect`。GD CLI 的 AK/SK 登录不能替代浏览器 AI+ 登录，账号密码应由用户在浏览器登录界面输入。
+
+如果 AI+ 在同一个 SPA 页面再次加载或切换作品，当前 Session 会主动断开以避免误写；此时重新执行 `gd-cli editor connect [target]`。
+
+## 复查作品
+
+复查依据必须是 Apply 后的最新 Snapshot 和实际截图。Snapshot 用于确认元素、字段和连接关系；截图用于判断路径、文字和布局。
+
+逐项检查，全部通过才算完成：
+
+- 每个 Connector 的 `fromId`、`toId` 都指向预期 Shape，方向符合语义；
+- 每条可见路径从 `fromId` Shape 边界开始、在 `toId` Shape 边界结束，不穿过任一端点 Shape 的填充或文字；
+- 同轴相邻 Connector 也逐条检查，不能把端点穿线解释成连续线效果；
+- Connector 不穿过无关 Shape，没有明显绕行、不自然折返或错误连接；
+- Shape 中的文字完整可读，没有截断、溢出或意外换行；
+- Shape、文字和 Connector 没有非预期重叠，必要间距真实存在；
+- 整体阅读方向清楚，构图平衡，关系容易沿 Connector 追踪。
+
+发现可执行问题时，先读取最新 Snapshot，再提交修正。Update 必须包含完整元素，不能提交 patch。若 `fromId`、`toId` 正确，但截图中的 Connector 仍穿过端点 Shape，原样提交该 Connector 的完整 Update 以触发原生路径重算；业务关系正确时不为绕开渲染问题改动关系。
+
+修正后再次执行 `snapshot`；涉及视觉变化时再次执行 `screenshot --json` 并打开图片。存在问题就继续修正；没有可执行问题时结束复查并保存。
+
+## Snapshot 契约
+
+```ts
+type FocusedPageSnapshot = {
+  elements: Array<FocusedShape | FocusedConnector>;
+  selectedIds: string[];
+};
+
+type FocusedShape = {
+  _type: "shape";
+  id: string;
+  shapeType:
+    | "rectangle"
+    | "rounded-rectangle"
+    | "triangle-up"
+    | "ellipse"
+    | "diamond";
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  text?: string;
+  fill: string;
+  stroke: string | null;
+};
+
+type FocusedConnector = {
+  _type: "connector";
+  id: string;
+  fromId: string;
+  toId: string;
+  lineType: "straight" | "elbowed";
+  color: string;
+};
+```
+
+`x`、`y` 是 Shape 左上角的 Page 坐标，`w`、`h` 是尺寸。`selectedIds` 只读。
+
+只使用简短、有语义的 `id`，例如 `start`、`review`、`start-to-review`。Bridge 会把这些 ID 映射到 Editor 内部标识。Connector 用 `fromId`、`toId` 表达有方向的 Shape 关系。
+
+## Action 契约
+
+```ts
+type FocusedEditorAction =
+  | { _type: "create"; element: FocusedShape | FocusedConnector }
+  | { _type: "update"; element: FocusedShape | FocusedConnector }
+  | { _type: "delete"; id: string };
+```
+
+- 输入必须是 JSON 数组，Action 按数组顺序执行。
+- Create 的 `id` 必须唯一；Connector 可以引用本数组中更早创建的 Shape。
+- Update 必须提交完整元素，不能提交 patch，也不能改变 `id` 或 `_type`。
+- Delete 的 `id` 必须存在；删除 Shape 会同时删除绑定到它的 Connector。
+- 对象不接受额外字段。所有数值必须有限，`w`、`h` 必须大于 0。
+- `fill`、`stroke` 和 `color` 使用 `#RRGGBB` 或 `#RRGGBBAA`；只有 Shape 的 `stroke` 可以为 `null`。
+- 整批 Action 会先预检，再在一个可回滚事务中应用。任何一项无效时整批不写入；修正输入后再提交。
+
+## 完整示例
+
+以下数组创建从左到右的 `Start -> Review? -> Done` 流程图：
+
+```json
+[
+  {
+    "_type": "create",
+    "element": {
+      "_type": "shape",
+      "id": "start",
+      "shapeType": "rounded-rectangle",
+      "x": 80,
+      "y": 160,
+      "w": 180,
+      "h": 80,
+      "text": "Start",
+      "fill": "#ffffff",
+      "stroke": "#222222"
+    }
+  },
+  {
+    "_type": "create",
+    "element": {
+      "_type": "shape",
+      "id": "review",
+      "shapeType": "diamond",
+      "x": 360,
+      "y": 140,
+      "w": 140,
+      "h": 120,
+      "text": "Review?",
+      "fill": "#f2f6ff",
+      "stroke": "#222222"
+    }
+  },
+  {
+    "_type": "create",
+    "element": {
+      "_type": "shape",
+      "id": "done",
+      "shapeType": "rounded-rectangle",
+      "x": 600,
+      "y": 160,
+      "w": 180,
+      "h": 80,
+      "text": "Done",
+      "fill": "#e8f7ed",
+      "stroke": "#222222"
+    }
+  },
+  {
+    "_type": "create",
+    "element": {
+      "_type": "connector",
+      "id": "start-to-review",
+      "fromId": "start",
+      "toId": "review",
+      "lineType": "straight",
+      "color": "#222222"
+    }
+  },
+  {
+    "_type": "create",
+    "element": {
+      "_type": "connector",
+      "id": "review-to-done",
+      "fromId": "review",
+      "toId": "done",
+      "lineType": "straight",
+      "color": "#222222"
+    }
+  }
+]
+```
+
+修改现有元素时，以最新 Snapshot 中的完整对象为基础，只改变目标字段后提交完整 Update。
+
+## 失败处理
+
+- `LOGIN_REQUIRED`：停止作图，让用户在已打开的 AI+ 页面登录，然后重新执行 `connect`；浏览器登录不能用 `gd-cli auth` 代替。
+- `EDITOR_NOT_READY`：停止并检查页面是否完成加载；重新执行 `connect`，成功前不调用写操作。
+- `WORK_NOT_EDITABLE`：停止；当前用户没有该作品的编辑或保存能力。
+- `EDITOR_SESSION_NOT_FOUND`：重新执行 `gd-cli editor connect [target]`，然后读取 Snapshot。
+- `EDITOR_NOT_CONNECTED`：页面连接已丢失；重新连接目标作品，不轮询旧 Session。
+- `UNSUPPORTED_PAGE_CONTENT`：停止，让用户改用空白或专用 Page。
+- `INVALID_ACTIONS`：根据本契约和最新 Snapshot 修正 Action，不原样重试。
+- `APPLY_FAILED`：运行时异常已触发批次回滚；重新读取 Snapshot，确认作品处于 Apply 前状态后再决定下一步。
+- `EDITOR_ROLLBACK_FAILED`：无法确认恢复到 Apply 前状态。停止所有 `apply` 和 `save`，只读取 Snapshot 或截图并报告。
+- `SAVE_FAILED`：保留当前 Session，处理明确失败原因后可再次执行 `save --json`；成功前不报告已保存。
+- `EDITOR_BUSY`：等待当前命令结束后再发下一条，保持串行。
+- `EDITOR_RPC_TIMEOUT`：页面是否执行完成未知，Bridge 会关闭。读取类操作可重新连接同一作品后重试；`apply` 或 `save` 属于不确定写入，先重新连接同一作品并检查真实状态，再决定后续动作。无法检查原作品时停止并报告，不自动重试该写入。
+- `PROTOCOL_VERSION_MISMATCH`：停止并升级 GD CLI，或使用协议匹配的 AI+ Editor。
+
+任何写操作在超时、取消或连接中断后都可能已经提交。恢复时先观察真实状态，避免重复创建、重复 Apply 或重复 Save。

package/skills/gd-cli/references/errors.md

@@ -6,6 +6,7 @@
 - 退出码 `1` 表示运行、服务或状态失败；只执行错误中 `error.details.next_steps` 明确给出的恢复步骤，缺失时停止并报告。
 - 退出码 `2` 表示命令或参数错误；执行对应命令的 `--help` 后修正调用。
 - 退出码 `130` 表示用户中断；立即停止，不自动重试。
+- `INSUFFICIENT_CREDITS` 表示当前组织稿豆不足；按 `error.details.next_steps` 引导用户前往 https://www.gaoding.art/pricing 购买稿豆，或执行 `gd-cli org switch` 切换到有可用稿豆的组织，处理后再重新发起创作。
 
 Agent 或 Tool 等可能消耗稿豆的请求如果可能已经提交、但完成状态未知，停止并报告，不自动重试原调用。