@yarch/contract 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,39 @@
 # @yarch/contract
 
-yarch 前端契约 SDK——契约唯一权威为 [yarch 仓 contract/](https://github.com/yuandonghao/yarch/tree/main/contract)，本包是其 TypeScript 方言实现（React/Vue 通吃，零框架依赖）。
+yarch 前端契约 SDK——契约唯一权威为 [yarch 仓 contract/](https://github.com/ydonghao/yarch/tree/main/contract)，本包是其 TypeScript 方言实现。**三端同源（MP4，0.3.0 起）**：同一内核服务 web / 微信小程序 / 小游戏，transport 可插拔。
 
-- `rest-response`：`RestResponse<T>` 信封类型 + 解包（失败抛 `ApiError`）
-- `error-codes`：13 码常量表（0 成功 · 1xxx 通用 · 2xxx 认证 · 3xxx+ 业务注册段）
-- `api-error`：traceId 报障凭证 · `shouldRedirectToLogin`
-- `trace-id`：`X-Trace-Id` 生成/透传（W3C traceparent 对齐）
-- `http`：fetch 封装 + 401 映射
-- `navigator`：导航端口（依赖倒置——框架适配包 `@yarch/react` / `@yarch/vue` 注入实现）
+## 出口（按端选用）
 
-用法：`createClient({ baseUrl, getHeaders })` → `api.get<PageData<T>>("/items?page=1")`。
+| 出口 | 内容 | 适用端 |
+|---|---|---|
+| `@yarch/contract`（主入口） | core + 微前端运行时件（event-bus / sub-app / manifest / navigator / shared-contract）+ fetch 封装 | web（微前端体系） |
+| `@yarch/contract/core` | **零环境依赖内核**：信封类型与解包 / 错误码表 / ApiError（四要素）/ traceId / transport 骨架接口 | 三端通用（含 Node 测试） |
+| `@yarch/contract/fetch` | fetch transport + `createClient`（web/H5/Node） | web 单页 / H5 |
+| `@yarch/contract/wx` | **wx.request transport + wx storage 适配**：小程序域禁从主入口引（会带进微前端件） | 微信小程序 / 小游戏 |
+| `@yarch/contract/cocos` | **运行时自动检测**：微信小游戏环境用 wx、H5 环境用 fetch——游戏代码不感知构建目标 | Cocos Creator 游戏（小游戏 + H5） |
 
-配套：工程脚手架 `npm create @yarch/admin@latest <name>`（[@yarch/create-admin](https://www.npmjs.com/package/@yarch/create-admin)）。
+## 内核语义（client-shared 协作参考级，对齐 [miniprogram.md](https://github.com/ydonghao/yarch/tree/main/contract/clients) 三）
+
+- 信封解包单点：`code != 0` 抛 `ApiError`（`code / message / traceId / httpStatus` 四要素）
+- 错误三分类：业务 `ApiError` · 传输错误本地保留码 `-1` · **取消不是错误**（`CancelledError` 原样传导）
+- traceId 会话复用：同 client 全部请求携带同一 `X-Trace-Id`（32 位小写 hex）
+- 超时单配置点：默认 30s，业务侧无 per-request 入口
+- 认证失效（2001/2002）：`onUnauthorized` 刷新 → 重放一次（防环、并发合并一次刷新）；终态 `onSessionExpired` 单点回调
+- GET 传输错误自动重试一次；写操作永不自动重试（防双写）
+
+## 用法
+
+```ts
+// web（React/Vue 通吃，零框架依赖）
+import { createClient } from "@yarch/contract";
+const api = createClient({ baseUrl, getHeaders });
+const page = await api.get<PageData<Item>>(`/v1/items?page=1`);
+
+// 微信小程序 / 小游戏
+import { createWxClient, createWxStorageBackend } from "@yarch/contract/wx";
+import { createAppStorage } from "@yarch/contract/core";
+const api = createWxClient({ baseUrl, onUnauthorized, onSessionExpired });
+const storage = createAppStorage("ysaas-companion", createWxStorageBackend()); // key 强制前缀隔离
+```
+
+配套：web 工程脚手架 `npm create @yarch/admin@latest <name>`（[@yarch/create-admin](https://www.npmjs.com/package/@yarch/create-admin)）。

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@yarch/contract",
-  "version": "0.1.0",
-  "description": "yarch 前端契约 SDK（跨框架，React/Vue 通吃）：RestResponse/PageData 类型与解包、错误码常量表、ApiError、traceId、fetch 封装",
+  "version": "0.3.0",
+  "description": "yarch 前端契约 SDK（三端同源 MP4）：信封解包/错误码表/ApiError 四要素/traceId 会话复用/401 刷新重放——@yarch/contract/core 零环境依赖，/wx 微信小程序适配，主入口含微前端运行时件",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core.ts",
+    "./wx": "./src/wx.ts",
+    "./fetch": "./src/http.ts",
+    "./cocos": "./src/cocos.ts"
+  },
   "files": [
     "src",
     "README.md"
   ],
   "scripts": { "test": "vitest run" },
   "publishConfig": { "access": "public" },
-  "repository": { "type": "git", "url": "git+https://github.com/yuandonghao/yarch.git", "directory": "stacks/web/packages/contract" },
+  "repository": { "type": "git", "url": "git+https://github.com/ydonghao/yarch.git", "directory": "stacks/web/packages/contract" },
   "license": "Apache-2.0",
   "devDependencies": { "vitest": "^3.0.0", "typescript": "^5.6.0" }
 }

package/src/api-error.ts

@@ -1,13 +1,16 @@
-/** ApiError：业务错误的统一形态 —— code 对应错误码表，traceId 是报障凭证 */
+/** ApiError：业务错误的统一形态 —— code 对应错误码表，traceId 是报障凭证，httpStatus 是传输层佐证 */
 export class ApiError extends Error {
   readonly code: number;
   readonly traceId: string;
+  /** HTTP 状态码（client-shared 一-3 四要素；0 = 未到达 HTTP 层，如传输错误本地保留码 -1） */
+  readonly httpStatus: number;
 
-  constructor(code: number, message: string, traceId = "") {
+  constructor(code: number, message: string, traceId = "", httpStatus = 0) {
     super(message);
     this.name = "ApiError";
     this.code = code;
     this.traceId = traceId;
+    this.httpStatus = httpStatus;
   }
 
   /** 契约：token 过期引导重登录，禁无脑重试（rest-conventions.md 认证段） */

package/src/cocos.ts

@@ -0,0 +1,51 @@
+/**
+ * Cocos Creator 适配器（game.md 三-2 的 Cocos 档载体）：
+ * 运行时环境检测——微信小游戏环境用 wx.request（./wx），H5/浏览器环境用 fetch（./http）。
+ * 游戏代码只引本出口，构建目标切换（小游戏↔H5）无需改业务代码。
+ */
+import { createCoreClient } from "./transport";
+import { createWxClient, createWxStorageBackend } from "./wx";
+import { createClient, fetchTransport } from "./http";
+import type { CoreClient, CoreClientOptions } from "./transport";
+import { createAppStorage } from "./storage";
+
+/** 当前运行时环境（game.md 二-1 Cocos 默认档面向双构建目标） */
+export type CocosRuntime = "wechat-minigame" | "h5";
+
+export function detectCocosRuntime(): CocosRuntime {
+  if (typeof (globalThis as { wx?: { request?: unknown } }).wx?.request === "function") {
+    return "wechat-minigame";
+  }
+  if (typeof (globalThis as { fetch?: unknown }).fetch === "function") {
+    return "h5";
+  }
+  throw new Error(
+    "Cocos 运行时不可识别：既无 globalThis.wx.request（微信小游戏）也无 fetch（H5）——" +
+      "请确认构建目标平台；Cocos 原生（非 H5/非小游戏）档暂不支持，须自行注入 HttpTransport",
+  );
+}
+
+/**
+ * 创建 Cocos 契约客户端（自动检测运行时）。
+ * - 微信小游戏：createWxClient（wx.request transport + wx storage）
+ * - H5：createClient（fetch transport + localStorage）
+ * options 与 web/wx 完全一致（client-shared 口径，照搬不另设——game.md 三-2）。
+ */
+export function createCocosClient(options: CoreClientOptions = {}): CoreClient {
+  const runtime = detectCocosRuntime();
+  if (runtime === "wechat-minigame") return createWxClient(options);
+  return createClient(options);
+}
+
+/**
+ * 创建 Cocos 端 storage（自动检测运行时，key 强制服务名前缀隔离——game.md 三-3 / miniprogram.md 三-6）。
+ */
+export function createCocosStorage(appName: string) {
+  const runtime = detectCocosRuntime();
+  if (runtime === "wechat-minigame") {
+    return createAppStorage(appName, createWxStorageBackend());
+  }
+  return createAppStorage(appName);
+}
+
+export { createCoreClient, fetchTransport, createWxClient, createWxStorageBackend };

package/src/core.ts

@@ -0,0 +1,10 @@
+/**
+ * 三端同源 core 出口（MP4）：零微前端依赖、零 DOM 运行时依赖——web（fetch 版另有 ./fetch 出口）、
+ * 微信小程序/小游戏（./wx 出口）、Node 测试环境通吃。主入口 `@yarch/contract` = 本出口 + 微前端运行时件。
+ */
+export * from "./error-codes";
+export * from "./rest-response";
+export * from "./api-error";
+export * from "./trace-id";
+export * from "./storage";
+export * from "./transport";

package/src/event-bus.ts

@@ -0,0 +1,79 @@
+/**
+ * 微前端事件通道（micro-frontend.md 九）：三条通信通道之一——事件上行/广播。
+ * 事件名格式 `{应用名}:{动词-名词}`（九-3，正例 ysaas-billing:export-done），裸事件名禁；
+ * payload 为可序列化 JSON；处理方异常不得中断发布方（九-4）——emit 内逐 handler try/catch 兜底。
+ * 基座与子应用经共享 contract 实例（八-1 单例）取到同一条总线，无需额外传输层。
+ */
+export type AppEventPayload = unknown;
+export type AppEventHandler = (payload: AppEventPayload) => void;
+
+const APP_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+const EVENT_NAME_RE = /^[a-z][a-z0-9-]{1,31}:[a-z]+(-[a-z]+)+$/;
+const EVENT_ACTION_RE = /^[a-z]+(-[a-z]+)+$/;
+
+export function assertAppEventName(name: string): void {
+  if (!EVENT_NAME_RE.test(name)) {
+    throw new Error(`事件名 ${name} 违反九-3 格式 {应用名}:{动词-名词}（正例 ysaas-billing:export-done）`);
+  }
+}
+
+export interface AppEventBus {
+  emit(name: string, payload: AppEventPayload): void;
+  /** 返回取消订阅函数（七-4：与注册成对使用） */
+  on(name: string, handler: AppEventHandler): () => void;
+}
+
+export function createAppEventBus(
+  onHandlerError: (name: string, cause: unknown) => void = console.error,
+): AppEventBus {
+  const handlers = new Map<string, Set<AppEventHandler>>();
+  return {
+    emit(name, payload) {
+      assertAppEventName(name);
+      for (const handler of handlers.get(name) ?? []) {
+        try {
+          handler(payload);
+        } catch (cause) {
+          onHandlerError(name, cause); // 九-4：处理方异常不得中断发布方
+        }
+      }
+    },
+    on(name, handler) {
+      assertAppEventName(name);
+      const set = handlers.get(name) ?? new Set();
+      set.add(handler);
+      handlers.set(name, set);
+      return () => set.delete(handler);
+    },
+  };
+}
+
+let bus: AppEventBus | null = null;
+
+/** 体系级单例总线：微前端下各方共享同一 contract 实例 → 同一条总线 */
+export function getAppEventBus(): AppEventBus {
+  bus ??= createAppEventBus();
+  return bus;
+}
+
+/** 子应用侧前缀封装（九-3 类型+运行时双强制）：action 形如 "export-done"，自动拼 `{应用名}:` 前缀 */
+export function defineAppEvents(appName: string) {
+  if (!APP_NAME_RE.test(appName)) {
+    throw new Error(`应用名 ${appName} 违反二-1 格式 ^[a-z][a-z0-9-]{1,31}$`);
+  }
+  const assertAction = (action: string) => {
+    if (!EVENT_ACTION_RE.test(action)) {
+      throw new Error(`事件动作 ${action} 须为 动词-名词（正例 export-done）`);
+    }
+  };
+  return {
+    emit(action: string, payload: AppEventPayload) {
+      assertAction(action);
+      getAppEventBus().emit(`${appName}:${action}`, payload);
+    },
+    on(action: string, handler: AppEventHandler) {
+      assertAction(action);
+      return getAppEventBus().on(`${appName}:${action}`, handler);
+    },
+  };
+}

package/src/http.ts

@@ -1,54 +1,55 @@
-/** 框架无关 fetch 封装：traceId 透传 + 信封解包 + 错误映射（401/402→重登录端口） */
-import { ApiError } from "./api-error";
-import { RestResponse } from "./rest-response";
-import { newTraceId, TRACE_ID_HEADER } from "./trace-id";
+/**
+ * fetch transport（web/H5/Node）+ 兼容旧签名的 createClient（micro-frontend.md / client-shared 协作参考的 web 方言）。
+ * 小程序/小游戏域禁用本入口（用 @yarch/contract/wx）。
+ * 行为口径（0.3.0 起对齐 client-shared）：traceId 会话内复用（二-1）、GET 传输错误自动重试一次（三-2）、
+ * 2001/2002 走 onUnauthorized 刷新重放一次（一-6，无钩子时维持 navigateToLogin 终态）。
+ */
+import { CancelledError, TransportError, createCoreClient } from "./transport";
+import type { CoreClientOptions, HttpTransport, TransportRequest, TransportResponse } from "./transport";
 import { navigateToLogin } from "./navigator";
 
-export interface HttpOptions {
-  baseUrl?: string;
-  getHeaders?: () => Record<string, string>;
-}
-
-export function createClient(options: HttpOptions = {}) {
-  const baseUrl = options.baseUrl ?? "";
+export type HttpOptions = CoreClientOptions;
 
-  async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-      [TRACE_ID_HEADER]: newTraceId(),
-      ...(options.getHeaders?.() ?? {}),
-    };
-    let response: Response;
+export const fetchTransport: HttpTransport = {
+  async send(req: TransportRequest): Promise<TransportResponse> {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, req.timeoutMs);
+    const onOuterAbort = () => controller.abort();
+    if (req.signal) {
+      if (req.signal.aborted) controller.abort();
+      else req.signal.addEventListener("abort", onOuterAbort);
+    }
     try {
-      response = await fetch(baseUrl + path, {
-        method,
-        headers,
-        body: body === undefined ? undefined : JSON.stringify(body),
+      const response = await fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+        signal: controller.signal,
+      });
+      const headers: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
       });
+      return { status: response.status, headers, text: () => response.text() };
     } catch (cause) {
-      throw new ApiError(-1, `网络错误：${String(cause)}`);
+      // 判定顺序：外部取消优先（原样传导），其次超时（传输错误），最后其他网络错误
+      if (req.signal?.aborted) throw new CancelledError("request cancelled");
+      if (timedOut) throw new TransportError(`请求超时（${req.timeoutMs}ms）`);
+      throw new TransportError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      clearTimeout(timer);
+      req.signal?.removeEventListener?.("abort", onOuterAbort);
     }
+  },
+};
 
-    if (response.status === 401) {
-      navigateToLogin("unauthorized");
-      throw new ApiError(2001, "未认证", response.headers.get(TRACE_ID_HEADER) ?? "");
-    }
-
-    const envelope = (await response.json()) as RestResponse<T>;
-    if (envelope.code !== 0) {
-      const apiError = new ApiError(envelope.code, envelope.message, envelope.traceId);
-      if (apiError.shouldRedirectToLogin) {
-        navigateToLogin(`code ${envelope.code}`);
-      }
-      throw apiError;
-    }
-    return envelope.data as T;
-  }
-
-  return {
-    get: <T>(path: string) => request<T>("GET", path),
-    post: <T>(path: string, body: unknown) => request<T>("POST", path, body),
-    put: <T>(path: string, body: unknown) => request<T>("PUT", path, body),
-    delete: <T>(path: string) => request<T>("DELETE", path),
-  };
+export function createClient(options: HttpOptions = {}) {
+  return createCoreClient(fetchTransport, {
+    onSessionExpired: (reason) => navigateToLogin(reason),
+    ...options,
+  });
 }

package/src/index.ts

@@ -2,5 +2,11 @@ export * from "./error-codes";
 export * from "./rest-response";
 export * from "./api-error";
 export * from "./trace-id";
+export * from "./transport";
 export * from "./navigator";
 export * from "./http";
+export * from "./event-bus";
+export * from "./storage";
+export * from "./sub-app";
+export * from "./manifest";
+export * from "./shared-contract";

package/src/manifest.ts

@@ -0,0 +1,31 @@
+/**
+ * 基座子应用入口登记表（micro-frontend.md 三-4/十二-2）：声明式 manifest，进 git 纳管，
+ * 入口变更只改此表。跨环境（test/staging/prod）入口 URL 由环境配置注入（十二-7），禁硬编码。
+ */
+export interface SubAppMenuMeta {
+  /** 菜单键：`{应用名}:{路径}`，与前缀哲学同源 */
+  key: string;
+  /** 子应用内部路由路径（kebab-case，四-4）；基座按 `路由前缀 + path` 装配 */
+  path: string;
+  title: string;
+  icon?: string;
+}
+
+export interface SubAppRegistration {
+  /** 应用名（二-1：首段 = registry 已登记服务名，两段及以上） */
+  name: string;
+  /** 入口 URL（dev=子应用 dev server，prod=静态目录/CDN，内容寻址产物） */
+  entry: string;
+  version?: string;
+  /** 路由前缀（四-1：恒等于 `/{name}`，字段化以对表十二-2；基座装配时校验一致） */
+  routePrefix: string;
+  /** 菜单元数据（三-4：基座读取装配，禁硬编码子应用内部路由） */
+  menu: SubAppMenuMeta[];
+}
+
+export type MicroAppsConfig = SubAppRegistration[];
+
+/** 路由前缀唯一写法（四-1）：子应用路由前缀 = 应用名 */
+export function subAppRoutePrefix(appName: string): string {
+  return `/${appName}`;
+}

package/src/navigator.ts

@@ -1,8 +1,12 @@
 /**
- * 导航端口（依赖倒置）：共享包零框架依赖，401→重登录 的路由跳转由各框架适配层注入实现
+ * 导航端口（依赖倒置）：共享包零框架依赖，路由跳转由各框架适配层注入实现
  * （对应 java 侧 ProductCache 端口的同一手法）。
+ * 微前端条文：跨应用跳转必须走本端口（micro-frontend.md 四-3）；
+ * 401 跳登录权唯一归基座（十-2）——子应用只抛 ApiError，禁自行跳转。
  */
 export interface YarchNavigator {
+  /** 应用内/跨应用路径跳转（如 /ysaas-billing/invoices）；微前端下由基座实现，按路由前缀分发 */
+  navigate(path: string): void;
   /** 401/2002 时引导到登录页（记录回跳地址） */
   redirectToLogin(reason: string): void;
 }
@@ -13,6 +17,10 @@ export function setNavigator(impl: YarchNavigator): void {
   navigator = impl;
 }
 
+export function navigateTo(path: string): void {
+  navigator?.navigate(path);
+}
+
 export function navigateToLogin(reason: string): void {
   navigator?.redirectToLogin(reason);
 }

package/src/shared-contract.ts

@@ -0,0 +1,16 @@
+/**
+ * @yarch/contract 运行时单例标记（micro-frontend.md 八-1）：整个微前端体系只允许一份实例，
+ * 由基座注册共享（集成构建的子应用经 window 全局取用）；子应用私带第二份 =
+ * 两个 ApiError 类，instanceof 全失效。
+ */
+export const SHARED_CONTRACT_KEY = "__YARCH_CONTRACT__";
+
+/** 基座侧注册：传入 `import * as contract from "@yarch/contract"` 的命名空间 */
+export function setSharedContract(namespace: object): void {
+  (globalThis as Record<string, unknown>)[SHARED_CONTRACT_KEY] = namespace;
+}
+
+/** 子应用集成构建 shim / e2e 单例断言用；未注册返回 undefined */
+export function getSharedContract<T = unknown>(): T | undefined {
+  return (globalThis as Record<string, unknown>)[SHARED_CONTRACT_KEY] as T | undefined;
+}

package/src/storage.ts

@@ -0,0 +1,49 @@
+/**
+ * 前缀化 storage（micro-frontend.md 二-2/七-3；miniprogram.md 三-6 小程序同款纪律）：
+ * key 一律 `{应用名}:` 前缀，裸 key（token、userInfo 直写）= 跨应用覆写事故。
+ * 冒号分层与 redis.md key 哲学同源；值统一 JSON 序列化。
+ * backend 环境无关（StorageLike 最小形状）：web 传默认 localStorage，小程序/小游戏传 createWxStorageBackend()。
+ */
+export interface StorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+const APP_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+const KEY_RE = /^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)*$/;
+
+export function createAppStorage(appName: string, backend?: StorageLike): AppStorage {
+  if (!APP_NAME_RE.test(appName)) {
+    throw new Error(`应用名 ${appName} 违反二-1 格式 ^[a-z][a-z0-9-]{1,31}$`);
+  }
+  const store =
+    backend ?? (globalThis as unknown as { localStorage?: StorageLike }).localStorage;
+  if (!store) {
+    throw new Error("无 storage backend：小程序/小游戏环境须传 createWxStorageBackend()");
+  }
+  const fullKey = (key: string) => {
+    if (!KEY_RE.test(key)) {
+      throw new Error(`storage key ${key} 须为 kebab-case 冒号分层（正例 filter-state）`);
+    }
+    return `${appName}:${key}`;
+  };
+  return {
+    get<T>(key: string): T | null {
+      const raw = store.getItem(fullKey(key));
+      return raw === null ? null : (JSON.parse(raw) as T);
+    },
+    set<T>(key: string, value: T): void {
+      store.setItem(fullKey(key), JSON.stringify(value));
+    },
+    remove(key: string): void {
+      store.removeItem(fullKey(key));
+    },
+  };
+}
+
+export interface AppStorage {
+  get<T>(key: string): T | null;
+  set<T>(key: string, value: T): void;
+  remove(key: string): void;
+}

package/src/sub-app.ts

@@ -0,0 +1,22 @@
+/** 子应用挂载 props 最小集（micro-frontend.md 五-5）：禁把基座整个 store 实例扔给子应用。 */
+import type { YarchNavigator } from "./navigator";
+
+export interface SubAppUser {
+  id: string;
+  name: string;
+}
+
+export interface SubAppMountProps {
+  /** 容器节点：子应用根挂载目标 */
+  container: HTMLElement;
+  /** 路由 base（四-2：由基座挂载时注入；独立运行时从环境变量取同值） */
+  base: string;
+  /** 导航端口实例（四-3；contract 单例已由基座注册时可缺省） */
+  navigator?: YarchNavigator;
+  /** 用户上下文（十-1：登录态归基座，子应用只读） */
+  user: SubAppUser | null;
+  /** 取 token 函数引用（十-1：子应用禁自行持久化 token） */
+  getToken(): string | null;
+  /** 主题 token（六-5：从基座下发，子应用禁自带第二套主题） */
+  themeToken?: Record<string, string>;
+}

package/src/trace-id.ts

@@ -2,9 +2,17 @@
 const TRACE_HEADER = "X-Trace-Id";
 
 export function newTraceId(): string {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  // 优先密码学随机（浏览器/Node）；小程序/小游戏无 crypto 全局时回退 Math.random——
+  // traceId 是排障关联标识而非安全凭证，熵需求以碰撞 rare 为准
+  const cryptoApi = (globalThis as { crypto?: Crypto }).crypto;
+  if (cryptoApi?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    cryptoApi.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  let hex = "";
+  for (let i = 0; i < 16; i++) hex += Math.floor(Math.random() * 256).toString(16).padStart(2, "0");
+  return hex;
 }
 
 export function traceHeader(): Record<string, string> {

package/src/transport.ts

@@ -0,0 +1,208 @@
+/**
+ * 环境无关契约内核骨架（miniprogram.md 三 / client-shared 一·二·三的落点）：
+ * 信封解包单点 / 错误三分类 / traceId 会话复用 / 认证失效刷新重放一次 / GET 幂等读重试一次 / 取消原样传导。
+ * Transport 由各端注入：fetch（web/H5/Node）见 ./http.ts，wx.request（小程序/小游戏）见 ./wx.ts。
+ * 本文件零 DOM、零 Node、零 wx 依赖——AbortSignal 用自制最小形状（小程序工程 tsconfig 无 DOM lib 也可编译）。
+ */
+import { ApiError } from "./api-error";
+import { CODE_SUCCESS, errorCodes } from "./error-codes";
+import type { RestResponse } from "./rest-response";
+import { newTraceId, TRACE_ID_HEADER } from "./trace-id";
+
+/** 取消不是错误（client-shared 一-4）：不是 ApiError、不落 -1，调用方 catch 后按取消收尾（禁转译禁吞） */
+export class CancelledError extends Error {
+  constructor(reason = "request cancelled") {
+    super(reason);
+    this.name = "CancelledError";
+  }
+}
+
+/** 传输层失败信号（断网/超时/TLS——各端 Transport 抛出，骨架统一映射为 ApiError(-1)） */
+export class TransportError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = "TransportError";
+  }
+}
+
+/** AbortSignal 最小形状（结构兼容 DOM AbortSignal；wx 基础库版本不支持时由适配器静默降级） */
+export interface AbortSignalLike {
+  readonly aborted: boolean;
+  addEventListener(type: "abort", listener: () => void): void;
+  removeEventListener?(type: "abort", listener: () => void): void;
+}
+
+export interface TransportRequest {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  /** 已序列化的 JSON body（undefined = 无 body） */
+  body?: string;
+  /** 超时单配置点（client-shared 三-1）：由客户端持有，业务侧无 per-request 入口 */
+  timeoutMs: number;
+  signal?: AbortSignalLike;
+}
+
+export interface TransportResponse {
+  status: number;
+  /** 响应头，键一律小写（各端适配器负责归一） */
+  headers: Record<string, string>;
+  text(): Promise<string>;
+}
+
+export interface HttpTransport {
+  send(req: TransportRequest): Promise<TransportResponse>;
+}
+
+export interface CoreClientOptions {
+  baseUrl?: string;
+  /** 超时默认 30s（client-shared 三-1 读写档；连接档由各端网络栈处理） */
+  timeoutMs?: number;
+  /** 凭证注入（Authorization 等），每请求调用 */
+  getHeaders?: () => Record<string, string>;
+  /** 会话 traceId（client-shared 二-1 本地生成一次、会话内复用）；不传则内核生成 */
+  traceId?: string;
+  /**
+   * 认证失效（2001/2002）刷新钩子（client-shared 一-6）：返回 true 触发原请求重放一次（防环），
+   * 抛错或返回 false 走 onSessionExpired 终态。并发失效合并为一次刷新。
+   */
+  onUnauthorized?: () => Promise<boolean> | boolean;
+  /** 会话终态回调：清态 + 路由登录（跳转权唯一，禁业务层各自捕获 401 跳登录） */
+  onSessionExpired?: (reason: string) => void;
+  /** 幂等读（GET）传输失败自动重试一次（client-shared 三-2：最多 1 次），默认开；写操作永不自动重试（防双写） */
+  retryGetOnTransportError?: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const RETRY_DELAY_MS = 600;
+const TRACE_ID_HEADER_LOWER = "x-trace-id";
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+export function createCoreClient(transport: HttpTransport, options: CoreClientOptions = {}) {
+  const baseUrl = options.baseUrl ?? "";
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retryGet = options.retryGetOnTransportError ?? true;
+  const sessionTraceId = options.traceId ?? newTraceId();
+  let refreshing: Promise<boolean> | null = null;
+
+  function tryRefresh(): Promise<boolean> {
+    if (!options.onUnauthorized) return Promise.resolve(false);
+    // 并发 401 合并一次刷新；settle 后清空，允许会话内后续再次过期时重新刷新
+    refreshing ??= Promise.resolve(options.onUnauthorized()).finally(() => {
+      refreshing = null;
+    });
+    return refreshing;
+  }
+
+  async function sendOnce<T>(
+    method: string,
+    path: string,
+    body: unknown,
+    signal: AbortSignalLike | undefined,
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      [TRACE_ID_HEADER]: sessionTraceId,
+      ...(options.getHeaders?.() ?? {}),
+    };
+    let response: TransportResponse;
+    try {
+      response = await transport.send({
+        method,
+        url: baseUrl + path,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        timeoutMs,
+        signal,
+      });
+    } catch (cause) {
+      if (cause instanceof CancelledError) throw cause; // 取消原样传导，禁转译禁吞
+      throw new ApiError(
+        -1,
+        `网络错误：${cause instanceof Error ? cause.message : String(cause)}`,
+        "",
+        0,
+      );
+    }
+
+    // HTTP 状态只是传输信号（client-shared 一-2）：2xx/4xx/5xx 一律解析 body，网关故障面也保证信封
+    let raw: string;
+    try {
+      raw = await response.text();
+    } catch (cause) {
+      throw new ApiError(-1, `响应读取失败：${String(cause)}`, "", response.status);
+    }
+    let envelope: RestResponse<T>;
+    try {
+      envelope = JSON.parse(raw) as RestResponse<T>;
+      if (typeof envelope?.code !== "number") throw new Error("非信封形状");
+    } catch {
+      if (response.status === 401) {
+        throw new ApiError(
+          errorCodes.UNAUTHORIZED,
+          "未认证（网关 401 无信封）",
+          response.headers[TRACE_ID_HEADER_LOWER] ?? "",
+          401,
+        );
+      }
+      throw new ApiError(-1, `信封不可解析（HTTP ${response.status}）`, "", response.status);
+    }
+
+    if (envelope.code !== CODE_SUCCESS) {
+      throw new ApiError(envelope.code, envelope.message, envelope.traceId, response.status);
+    }
+    return envelope.data as T;
+  }
+
+  async function request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    signal?: AbortSignalLike,
+    isReplay = false,
+  ): Promise<T> {
+    try {
+      return await sendOnce<T>(method, path, body, signal);
+    } catch (cause) {
+      if (cause instanceof CancelledError) throw cause;
+
+      // 传输错误且幂等读：自动重试一次（client-shared 三-2；写操作永不自动重试）
+      if (retryGet && method === "GET" && cause instanceof ApiError && cause.code === -1 && !signal?.aborted) {
+        await delay(RETRY_DELAY_MS);
+        if (signal?.aborted) throw new CancelledError();
+        try {
+          return await sendOnce<T>(method, path, body, signal);
+        } catch (retryCause) {
+          if (retryCause instanceof CancelledError) throw retryCause;
+          if (retryCause instanceof ApiError && retryCause.code === -1) {
+            throw new ApiError(-1, `网络错误（已重试）：${retryCause.message}`, "", 0);
+          }
+          throw retryCause;
+        }
+      }
+
+      // 认证失效单点：刷新 → 重放一次；终态走 onSessionExpired（client-shared 一-6，防环）
+      if (cause instanceof ApiError && cause.shouldRedirectToLogin) {
+        if (!isReplay) {
+          if (await tryRefresh()) return request<T>(method, path, body, signal, true);
+        }
+        options.onSessionExpired?.(`code ${cause.code}${isReplay ? "（重放后仍失效）" : ""}`);
+        throw cause;
+      }
+
+      throw cause;
+    }
+  }
+
+  return {
+    get: <T>(path: string, signal?: AbortSignalLike) => request<T>("GET", path, undefined, signal),
+    post: <T>(path: string, body: unknown, signal?: AbortSignalLike) =>
+      request<T>("POST", path, body, signal),
+    put: <T>(path: string, body: unknown, signal?: AbortSignalLike) =>
+      request<T>("PUT", path, body, signal),
+    delete: <T>(path: string, signal?: AbortSignalLike) => request<T>("DELETE", path, undefined, signal),
+  };
+}
+
+export type CoreClient = ReturnType<typeof createCoreClient>;

package/src/wx.ts

@@ -0,0 +1,127 @@
+/**
+ * wx.request 适配器（miniprogram.md 三的载体 / MP4 三端同源的小程序方言）：
+ * 超时单点 / X-Trace-Id 会话注入 / 错误三分类 / 认证失效刷新重放 / 取消原样传导。
+ * 消费：`import { createWxClient, createWxStorageBackend } from "@yarch/contract/wx"`——
+ * **禁从主入口引**（主出口含微前端运行时件，会把 window 语义带进小程序 bundle）。
+ * 本文件零 DOM 依赖；wx 全局以最小接口形状解析（不依赖 miniprogram-api-typings）。
+ */
+import { createCoreClient, CancelledError, TransportError } from "./transport";
+import type {
+  AbortSignalLike,
+  CoreClient,
+  CoreClientOptions,
+  HttpTransport,
+  TransportRequest,
+  TransportResponse,
+} from "./transport";
+import type { StorageLike } from "./storage";
+
+type WxRequestMethod = "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "PATCH";
+
+interface WxRequestFail {
+  errMsg?: string;
+}
+
+interface WxLike {
+  request(options: {
+    url: string;
+    method?: WxRequestMethod;
+    header?: Record<string, string>;
+    data?: string;
+    timeout?: number;
+    success?(res: { statusCode: number; data: unknown; header?: Record<string, unknown> }): void;
+    fail?(err: WxRequestFail): void;
+  }): { abort(): void };
+  setStorageSync(key: string, value: string): void;
+  getStorageSync(key: string): unknown;
+  removeStorageSync(key: string): void;
+}
+
+function resolveWx(): WxLike {
+  const impl = (globalThis as { wx?: WxLike }).wx;
+  if (!impl) {
+    throw new Error("createWxClient / createWxStorageBackend 须在微信小程序/小游戏环境调用（globalThis.wx 不存在）");
+  }
+  return impl;
+}
+
+/** AbortSignal 可选支持（基础库版本差异，不支持时取消降级为不取消——不违反取消语义：宁可多收一次响应） */
+function hookSignal(task: { abort(): void }, signal: AbortSignalLike | undefined): void {
+  if (!signal || typeof signal.addEventListener !== "function") return;
+  if (signal.aborted) {
+    task.abort();
+    return;
+  }
+  signal.addEventListener("abort", () => task.abort());
+}
+
+/** wx 响应头键大小写不定、值可能 string|string[]：归一为小写键逗号_join 单值 */
+function normalizeHeaders(header: Record<string, unknown> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!header) return out;
+  for (const [key, value] of Object.entries(header)) {
+    out[key.toLowerCase()] = Array.isArray(value) ? value.join(",") : String(value);
+  }
+  return out;
+}
+
+export function createWxTransport(): HttpTransport {
+  const wx = resolveWx();
+  return {
+    send(req: TransportRequest): Promise<TransportResponse> {
+      return new Promise((resolve, reject) => {
+        const task = wx.request({
+          url: req.url,
+          method: req.method as WxRequestMethod,
+          header: req.headers,
+          // body 已由内核序列化为 JSON 字符串；wx 对 string data 原样发送（禁再对象化触发双重序列化）
+          data: req.body,
+          timeout: req.timeoutMs,
+          success: (res) => {
+            resolve({
+              status: res.statusCode,
+              headers: normalizeHeaders(res.header),
+              // wx 按 content-type 预解析 res.data：已是对象时还原为字符串供内核统一 JSON.parse；
+              // 空体（data 为 ""/undefined）归一为空串 → 内核按信封不可解析处理
+              text: async () =>
+                typeof res.data === "string" ? res.data : JSON.stringify(res.data ?? ""),
+            });
+          },
+          fail: (err) => {
+            const msg = typeof err?.errMsg === "string" ? err.errMsg : String(err);
+            if (msg.includes("abort")) {
+              // 取消不是错误：专用异常原样上抛，禁转译为 ApiError（client-shared 一-4）
+              reject(new CancelledError(msg));
+            } else {
+              reject(new TransportError(msg));
+            }
+          },
+        });
+        hookSignal(task, req.signal);
+      });
+    },
+  };
+}
+
+export function createWxClient(options: CoreClientOptions = {}): CoreClient {
+  return createCoreClient(createWxTransport(), options);
+}
+
+/** wx storage 适配（miniprogram.md 三-6：凭证存储 key 以已登记服务名前缀隔离，防宿主生态串号） */
+export function createWxStorageBackend(): StorageLike {
+  const wx = resolveWx();
+  return {
+    getItem(key: string): string | null {
+      const value = wx.getStorageSync(key);
+      return value === "" || value === null || value === undefined ? null : (value as string);
+    },
+    setItem(key: string, value: string): void {
+      wx.setStorageSync(key, value);
+    },
+    removeItem(key: string): void {
+      wx.removeStorageSync(key);
+    },
+  };
+}
+
+export { CancelledError, TransportError };