Fix cloud sync state consistency and provider-safe conflict handling

docs/DOC-MAINTENANCE.md

@@ -29,6 +29,7 @@ Aspirational / feature-branch content belongs in that branch's docs, or is clear
 | [`DEVELOP.md`](./DEVELOP.md) | The concrete "how": commands, structure, style, testing, i18n, commit/PR. |
 | [`VERIFICATION.md`](./VERIFICATION.md) | Lightweight end-to-end functional verification — throwaway scratch scripts driving the real built extension. |
 | [`ARCHITECTURE.md`](./ARCHITECTURE.md) | Deep internals: process model, message passing, service/data layers, GM API, execution, build. |
+| [`CLOUD-SYNC.md`](./CLOUD-SYNC.md) | Cloud sync internals: sync files, digest/status semantics, provider differences, error classification, retry policy. |
 | [`translation/README.md`](./translation/README.md) | Translation / localization single source of truth. |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules + fact-check / anti-drift discipline. |
 | [`README.md`](./README.md) | The index that points to all of the above. |
@@ -97,7 +98,7 @@ git ls-files eslint-rules/; git grep -l "require-last-error-check" -- eslint.con
 Link integrity — confirm every relative markdown link in the core docs resolves:
 
 ```bash
-for doc in AGENTS.md docs/README.md docs/DEVELOP.md docs/VERIFICATION.md docs/ARCHITECTURE.md docs/DOC-MAINTENANCE.md docs/translation/README.md; do
+for doc in AGENTS.md docs/README.md docs/DEVELOP.md docs/VERIFICATION.md docs/ARCHITECTURE.md docs/CLOUD-SYNC.md docs/DOC-MAINTENANCE.md docs/translation/README.md; do
   grep -oE '\]\(([^)]+)\)' "$doc" | sed -E 's/^\]\(|\)$//g' | grep -vE '^https?:|^#' | while read -r link; do
     target="$(dirname "$doc")/${link%%#*}"
     [ -e "$target" ] && echo "ok     $doc → $link" || echo "BROKEN $doc → $link"

docs/README.md

@@ -10,6 +10,7 @@
 | [`DEVELOP.md`](./DEVELOP.md) | 开发规范:命令、目录结构、编码风格、UI/主题、测试机制、i18n、提交/PR 流程。**写代码前先读。** |
 | [`VERIFICATION.md`](./VERIFICATION.md) | 功能验证指南:用一次性 scratch 脚本驱动真实扩展做端到端验证(不跑全量 E2E、不加永久用例)。**验证改动是否真正跑通时读。** |
 | [`ARCHITECTURE.md`](./ARCHITECTURE.md) | 内部原理深入:多进程模型、消息传递、服务/数据层、GM API、脚本执行、构建管线。 |
+| [`CLOUD-SYNC.md`](./CLOUD-SYNC.md) | 云同步实现说明:同步文件语义、主流程、状态合并、provider 差异、错误分类、retry 策略和维护注意事项。 |
 | [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、一键校验脚本。**改/审文档前先读。** |
 
 ## 翻译 / Translation

packages/filesystem/baidu/baidu.test.ts

@@ -1,21 +1,42 @@
 import { describe, expect, it, vi, afterEach } from "vitest";
+import { initTestEnv } from "@Tests/utils";
+import { isNotFoundError, isRateLimitError } from "../error";
+import { getFileSystemCapabilities } from "../filesystem";
 import BaiduFileSystem from "./baidu";
 
+initTestEnv();
+
 describe("BaiduFileSystem", () => {
   afterEach(() => {
     vi.unstubAllGlobals();
     vi.restoreAllMocks();
   });
 
+  it("不应声明原子条件写入能力", () => {
+    const fs = new BaiduFileSystem("/apps", "token");
+
+    expect(getFileSystemCapabilities(fs)).toEqual({
+      supportsAtomicCompareAndSwap: false,
+      supportsCreateOnly: false,
+      supportsConditionalDelete: false,
+    });
+  });
+
   it("request should omit credentials without using global DNR rules", async () => {
     const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
       json: async () => ({ errno: 0 }),
     });
     vi.stubGlobal("fetch", fetchMock);
 
     // 监视 updateDynamicRules，确保不再依赖全局 DNR 规则
     const updateDynamicRulesMock = vi.fn();
-    (chrome as any).declarativeNetRequest.updateDynamicRules = updateDynamicRulesMock;
+    vi.stubGlobal("chrome", {
+      declarativeNetRequest: {
+        updateDynamicRules: updateDynamicRulesMock,
+      },
+    });
 
     const fs = new BaiduFileSystem("/apps", "token");
 
@@ -33,6 +54,38 @@ describe("BaiduFileSystem", () => {
     expect(updateDynamicRulesMock).not.toHaveBeenCalled();
   });
 
+  it("request 遇到 HTTP 429 时应抛出 typed rate-limit 错误", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 429,
+      statusText: "Too Many Requests",
+      json: async () => ({ errno: 0, errmsg: "rate limited" }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const fs = new BaiduFileSystem("/apps", "token");
+
+    await expect(fs.request("https://pan.baidu.com/rest/2.0/xpan/file?method=list")).rejects.toSatisfy(
+      isRateLimitError
+    );
+  });
+
+  it("request 遇到 HTTP 5xx 时应抛出 typed retryable 错误", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 503,
+      statusText: "Service Unavailable",
+      json: async () => ({ errno: 0, errmsg: "service unavailable" }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const fs = new BaiduFileSystem("/apps", "token");
+
+    await expect(fs.request("https://pan.baidu.com/rest/2.0/xpan/file?method=list")).rejects.toMatchObject({
+      provider: "baidu",
+      status: 503,
+      retryable: true,
+    });
+  });
+
   it("create should normalize double slashes in paths", async () => {
     const fs = new BaiduFileSystem("/apps//ScriptCat", "token");
 
@@ -52,4 +105,54 @@ describe("BaiduFileSystem", () => {
       `async=0&filelist=${encodeURIComponent(JSON.stringify(["/apps/ScriptCat/dir/file.user.js"]))}`
     );
   });
+
+  it("创建目录遇到明确已存在 errno 时才标记为冲突", async () => {
+    const fs = new BaiduFileSystem("/apps", "token");
+    vi.spyOn(fs, "request").mockResolvedValue({ errno: 31061, errmsg: "file already exists" });
+
+    await expect(fs.createDir("ScriptCat")).rejects.toMatchObject({
+      provider: "baidu",
+      code: "31061",
+      conflict: true,
+    });
+  });
+
+  it("创建目录遇到普通 errno 时不能误标记为冲突", async () => {
+    const fs = new BaiduFileSystem("/apps", "token");
+    vi.spyOn(fs, "request").mockResolvedValue({ errno: 2, errmsg: "access denied" });
+
+    await expect(fs.createDir("ScriptCat")).rejects.toMatchObject({
+      provider: "baidu",
+      code: "2",
+      conflict: false,
+    });
+  });
+
+  it("写入预创建失败时保留普通 errno 的非冲突语义", async () => {
+    const fs = new BaiduFileSystem("/apps", "token");
+    vi.spyOn(fs, "request").mockResolvedValue({ errno: 2, errmsg: "access denied" });
+    const writer = await fs.create("dir/file.user.js");
+
+    await expect(writer.write("code")).rejects.toMatchObject({
+      provider: "baidu",
+      code: "2",
+      conflict: false,
+    });
+  });
+
+  it("读取文件元数据缺失时应抛出 typed not found 错误", async () => {
+    const fs = new BaiduFileSystem("/apps", "token");
+    vi.spyOn(fs, "request").mockResolvedValue({ errno: -9, errmsg: "file not found" });
+    const reader = await fs.open({
+      fsid: 123,
+      name: "missing.user.js",
+      path: "/apps",
+      size: 0,
+      digest: "",
+      createtime: 0,
+      updatetime: 0,
+    });
+
+    await expect(reader.read("string")).rejects.toSatisfy(isNotFoundError);
+  });
 });

packages/filesystem/baidu/baidu.ts

@@ -2,6 +2,7 @@ import { AuthVerify } from "../auth";
 import type FileSystem from "../filesystem";
 import type { FileInfo, FileCreateOptions, FileReader, FileWriter } from "../filesystem";
 import { joinPath } from "../utils";
+import { createBaiduFileSystemError } from "./error";
 import { BaiduFileReader, BaiduFileWriter } from "./rw";
 
 export default class BaiduFileSystem implements FileSystem {
@@ -52,7 +53,7 @@ export default class BaiduFileSystem implements FileSystem {
       }
     );
     if (data.errno) {
-      throw new Error(JSON.stringify(data));
+      throw createBaiduFileSystemError(data);
     }
   }
 
@@ -62,18 +63,27 @@ export default class BaiduFileSystem implements FileSystem {
     config.headers = headers;
     // 对百度网盘请求显式禁用 cookie，避免依赖全局 DNR 规则造成并发竞态
     config.credentials = "omit";
+    const parseResponse = async (response: Response) => {
+      const data = await response.json().catch(() => ({
+        errmsg: response.statusText || `HTTP ${response.status}`,
+      }));
+      if (!response.ok) {
+        throw createBaiduFileSystemError({ ...data, httpStatus: response.status });
+      }
+      return data;
+    };
     return fetch(url, config)
-      .then((data) => data.json())
+      .then(parseResponse)
       .then(async (data) => {
         if (data.errno === 111 || data.errno === -6) {
           const token = await AuthVerify("baidu", true);
           this.accessToken = token;
           url = url.replace(/access_token=[^&]+/, `access_token=${token}`);
           return fetch(url, config)
-            .then((data2) => data2.json())
+            .then(parseResponse)
             .then((data2) => {
               if (data2.errno === 111 || data2.errno === -6) {
-                throw new Error(JSON.stringify(data2));
+                throw createBaiduFileSystemError(data2);
               }
               return data2;
             });
@@ -95,7 +105,7 @@ export default class BaiduFileSystem implements FileSystem {
       }
     ).then((data) => {
       if (data.errno) {
-        throw new Error(JSON.stringify(data));
+        throw createBaiduFileSystemError(data);
       }
       return data;
     });
@@ -126,7 +136,7 @@ export default class BaiduFileSystem implements FileSystem {
         if (data.errno === -9) {
           break;
         }
-        throw new Error(JSON.stringify(data));
+        throw createBaiduFileSystemError(data);
       }
 
       if (!data.list || data.list.length === 0) {

packages/filesystem/baidu/error.ts

@@ -0,0 +1,35 @@
+import { FileSystemError } from "../error";
+
+export type BaiduErrorResponse = {
+  errno?: number;
+  httpStatus?: number;
+  errmsg?: string;
+  error_msg?: string;
+  [key: string]: unknown;
+};
+
+const BAIDU_FILE_EXISTS_ERRNOS = new Set([31061]);
+
+export function createBaiduFileSystemError(data: BaiduErrorResponse): FileSystemError {
+  const code = typeof data.errno === "number" ? String(data.errno) : undefined;
+  const status = data.httpStatus;
+  const message =
+    data.errmsg || data.error_msg || (code ? `Baidu request failed with errno ${code}` : "Baidu request failed");
+  const conflict = typeof data.errno === "number" && BAIDU_FILE_EXISTS_ERRNOS.has(data.errno);
+  const auth = data.errno === 111 || data.errno === -6 || status === 401;
+  const notFound = data.errno === -9 || status === 404;
+  const rateLimit = status === 429;
+
+  return new FileSystemError({
+    provider: "baidu",
+    message,
+    status,
+    code,
+    conflict,
+    auth,
+    notFound,
+    rateLimit,
+    retryable: rateLimit || (status !== undefined && status >= 500),
+    raw: data,
+  });
+}

packages/filesystem/baidu/rw.ts

@@ -1,6 +1,7 @@
 import type { FileInfo, FileReader, FileWriter } from "../filesystem";
 import { calculateMd5, md5OfText } from "@App/pkg/utils/crypto";
 import type BaiduFileSystem from "./baidu";
+import { createBaiduFileSystemError } from "./error";
 
 export class BaiduFileReader implements FileReader {
   file: FileInfo;
@@ -19,8 +20,11 @@ export class BaiduFileReader implements FileReader {
         this.fs.accessToken
       }&fsids=[${this.file.fsid!}]&dlink=1`
     );
-    if (!data.list.length) {
-      throw new Error("file not found");
+    if (data.errno) {
+      throw createBaiduFileSystemError(data);
+    }
+    if (!data.list?.length) {
+      throw createBaiduFileSystemError({ errno: -9, errmsg: "file not found" });
     }
     const resp = await fetch(`${data.list[0].dlink}&access_token=${this.fs.accessToken}`);
     switch (type) {
@@ -80,7 +84,7 @@ export class BaiduFileWriter implements FileWriter {
       }
     );
     if (data.errno) {
-      throw new Error(JSON.stringify(data));
+      throw createBaiduFileSystemError(data);
     }
     const uploadid = data.uploadid;
     const body = new FormData();
@@ -102,7 +106,7 @@ export class BaiduFileWriter implements FileWriter {
       }
     );
     if (data.errno) {
-      throw new Error(JSON.stringify(data));
+      throw createBaiduFileSystemError(data);
     }
     // 创建文件
     urlencoded = new URLSearchParams();
@@ -121,7 +125,7 @@ export class BaiduFileWriter implements FileWriter {
       }
     );
     if (data.errno) {
-      throw new Error(JSON.stringify(data));
+      throw createBaiduFileSystemError(data);
     }
   }
 }