From 9ffa30cc03f62ef5c1c687a05e58cb1084cbc3d9 Mon Sep 17 00:00:00 2001
From: chenhang <averych@126.com>
Date: Tue, 16 Jun 2026 14:06:31 +0800
Subject: [PATCH 1/3] style: remove markdown bold syntax from code comments

Remove `**...**` emphasis markers from inline comments and JSDoc blocks across
auth and chat components, machine mappers, and quota helpers. These are
plain code comments, not rendered markdown, so the bold syntax was noise.

Files touched:
- src/app/auth/components/auth-screen.tsx
- src/app/chat/components/chat-header.tsx
- src/app/chat/components/chat-screen.tsx
- chat machine mapper / quota helpers

No functional or behavioral changes.
---
 src/app/auth/components/auth-screen.tsx       |  4 +-
 src/app/chat/components/chat-header.tsx       |  2 +-
 src/app/chat/components/chat-screen.tsx       | 28 +++---
 src/app/chat/components/message-content.tsx   |  2 +-
 .../deviceid/[deviceId]/DeepLinkPersist.tsx   |  2 +-
 src/app/chat/deviceid/[deviceId]/page.tsx     |  2 +-
 src/app/page.tsx                              |  2 +-
 src/app/splash/components/splash-button.tsx   | 10 +--
 src/core/fonts.ts                             |  4 +-
 src/core/net/interceptor/token_interceptor.ts |  2 +-
 src/data/repositories/auth_repository.ts      |  8 +-
 .../interfaces/iauth_repository.ts            |  2 +-
 src/data/schemas/chat/chat_send_response.ts   |  2 +-
 src/data/storage/chat/chat_storage.ts         |  6 +-
 src/lib/auth/auth.ts                          |  2 +-
 src/lib/auth/auth_platform.ts                 |  4 +-
 src/lib/auth/logout.ts                        |  2 +-
 src/providers/session-provider.tsx            |  2 +-
 src/router/index.ts                           |  2 +-
 src/router/proxy.ts                           | 16 ++--
 src/router/routes.ts                          |  4 +-
 src/stores/auth/auth-actors.ts                | 12 +--
 src/stores/auth/auth-events.ts                | 10 +--
 src/stores/auth/auth-machine.ts               | 16 ++--
 src/stores/auth/auth-state.ts                 |  6 +-
 src/stores/auth/oauth-session-sync.tsx        |  2 +-
 src/stores/chat/chat-context.tsx              | 10 +--
 src/stores/chat/chat-events.ts                | 18 ++--
 src/stores/chat/chat-machine.actors.ts        | 46 +++++-----
 src/stores/chat/chat-machine.helpers.ts       | 62 ++++++-------
 src/stores/chat/chat-machine.ts               | 86 +++++++++----------
 src/stores/chat/chat-state.ts                 | 32 +++----
 src/utils/result.ts                           |  4 +-
 33 files changed, 206 insertions(+), 206 deletions(-)

diff --git a/src/app/auth/components/auth-screen.tsx b/src/app/auth/components/auth-screen.tsx
index 9828a01b..7ae6cdaf 100644
--- a/src/app/auth/components/auth-screen.tsx
+++ b/src/app/auth/components/auth-screen.tsx
@@ -24,8 +24,8 @@ export function AuthScreen() {
   const router = useRouter();
 
   // 邮箱登录成功 → 通知 User + 跳转
-  // 用 **pendingRedirect flag**（不是 useRef transition detection）——
-  // re-mount 时 flag 在 auth context 里**持久**，区分"刚按了"和"re-visit"准确无误。
+  // 用 pendingRedirect flag（不是 useRef transition detection）——
+  // re-mount 时 flag 在 auth context 里持久，区分"刚按了"和"re-visit"准确无误。
   useEffect(() => {
     console.log("[auth-screen] useEffect (loginStatus + pendingRedirect)", {
       pending: state.pendingRedirect,
diff --git a/src/app/chat/components/chat-header.tsx b/src/app/chat/components/chat-header.tsx
index 6bf693bf..7e0bdcdb 100644
--- a/src/app/chat/components/chat-header.tsx
+++ b/src/app/chat/components/chat-header.tsx
@@ -8,7 +8,7 @@
  *   - 游客模式（isGuest=true）：渲染 `GuestBanner` 提示注册（点击 → /auth）
  *   - 登录模式（isGuest=false）：渲染 `MenuButton`（点击 → push 到 /sidebar）
  *
- * 注意：菜单按钮直接 push 到侧边栏路由，**不**打开下拉菜单
+ * 注意：菜单按钮直接 push 到侧边栏路由，不打开下拉菜单
  * （Dart 端 `MenuButton(onTap: _goSidebar)` 行为）。
  */
 import { useRouter } from "next/navigation";
diff --git a/src/app/chat/components/chat-screen.tsx b/src/app/chat/components/chat-screen.tsx
index 346e8ee7..66a3899f 100644
--- a/src/app/chat/components/chat-screen.tsx
+++ b/src/app/chat/components/chat-screen.tsx
@@ -5,9 +5,9 @@
  * 原始 Dart: lib/ui/chat/chat_screen.dart（172 行）
  *
  * 职责（本文件）：
- *   - **订阅 auth 状态机**（loginStatus）—— 派生 isGuest / **派鉴权生命周期事件**给 chat 机器
+ *   - 订阅 auth 状态机（loginStatus）—— 派生 isGuest / 派鉴权生命周期事件给 chat 机器
  *   - 屏幕生命周期事件（init / visible / invisible）
- *   - **不**直接管理 WebSocket / **不**直接读 AuthStorage（除 token 取值）
+ *   - 不直接管理 WebSocket / 不直接读 AuthStorage（除 token 取值）
  *
  * 子组件职责：
  *   - ChatHeader：顶部栏（游客 banner / 菜单按钮）
@@ -16,13 +16,13 @@
  *   - PwaInstallOverlay：PWA 安装提示触发器
  *   - BrowserHintOverlay：浏览器提示
  *
- * **鉴权解耦**（**事件驱动**）：
- *   - chat 机器**不**感知鉴权 / **不**管 WebSocket —— 由 chat-screen 派生 loginStatus
- *   - chat-screen **只**派 3 个事件：
- *     - `ChatGuestLogin` → 游客会话（**断** WS = 不连）
- *     - `ChatNonGuestLogin { token }` → 非游客会话（**连** WS）
+ * 鉴权解耦（事件驱动）：
+ *   - chat 机器不感知鉴权 / 不管 WebSocket —— 由 chat-screen 派生 loginStatus
+ *   - chat-screen 只派 3 个事件：
+ *     - `ChatGuestLogin` → 游客会话（断 WS = 不连）
+ *     - `ChatNonGuestLogin { token }` → 非游客会话（连 WS）
  *     - `ChatLogout` → 登出（机器自动 cleanup WS actor）
- *   - chat 机器**内部**用 fromCallback actor 完整管理 WS 生命周期
+ *   - chat 机器内部用 fromCallback actor 完整管理 WS 生命周期
  */
 import { useEffect, useRef } from "react";
 import Image from "next/image";
@@ -49,16 +49,16 @@ function deriveIsGuest(loginStatus: LoginStatus): boolean {
 }
 
 /**
- * 按 loginStatus 派鉴权生命周期事件（chat 机器**不**感知 loginStatus —— 这层转换在此）
+ * 按 loginStatus 派鉴权生命周期事件（chat 机器不感知 loginStatus —— 这层转换在此）
  *
- * 设计：**不**直接管理 WS / **不**读 AuthStorage（除取 token）
+ * 设计：不直接管理 WS / 不读 AuthStorage（除取 token）
  */
 function dispatchAuthLifecycle(
   loginStatus: LoginStatus,
   chatDispatch: ReturnType<typeof useChatDispatch>,
 ): void {
   if (loginStatus === "guest") {
-    // 游客：派 ChatGuestLogin（chat 机器**不**连 WS —— 业务事实"断 WS"）
+    // 游客：派 ChatGuestLogin（chat 机器不连 WS —— 业务事实"断 WS"）
     chatDispatch({ type: "ChatGuestLogin" });
     return;
   }
@@ -81,7 +81,7 @@ export function ChatScreen() {
   const authState = useAuthState();
   const chatDispatch = useChatDispatch();
 
-  // isGuest 派生（chat-screen 是**唯一**知道这个值的地方 —— chat 机器无 isGuest 字段）
+  // isGuest 派生（chat-screen 是唯一知道这个值的地方 —— chat 机器无 isGuest 字段）
   const isGuest = deriveIsGuest(authState.loginStatus);
 
   // ─────────────────────────────────────────────────────────────
@@ -91,7 +91,7 @@ export function ChatScreen() {
     dispatchAuthLifecycle(authState.loginStatus, chatDispatch);
     return () => {
     };
-    // 注：mount useEffect 故意**不**依赖 loginStatus —— 首次 mount 时机是固定的
+    // 注：mount useEffect 故意不依赖 loginStatus —— 首次 mount 时机是固定的
     //     （"用户进 /chat 那一刻"），loginStatus 由 splash/auth-screen 提前 settle。
     //     loginStatus 后续变化由下方"副作用 ②" 统一处理。
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -110,7 +110,7 @@ export function ChatScreen() {
     const prev = prevLoginStatusRef.current;
     prevLoginStatusRef.current = authState.loginStatus;
     if (prev === null) return; // 首次 mount 由 mount useEffect 处理
-    if (prev === authState.loginStatus) return; // 登录态**没**变
+    if (prev === authState.loginStatus) return; // 登录态没变
     dispatchAuthLifecycle(authState.loginStatus, chatDispatch);
   }, [authState.loginStatus, chatDispatch]);
 
diff --git a/src/app/chat/components/message-content.tsx b/src/app/chat/components/message-content.tsx
index dea5e557..e55671b6 100644
--- a/src/app/chat/components/message-content.tsx
+++ b/src/app/chat/components/message-content.tsx
@@ -29,7 +29,7 @@ export function MessageContent({ content, imageUrl, isFromAI }: MessageContentPr
       style={{
         display: "flex",
         flexDirection: "column",
-        // **关键**：在 row flex 父中撑开（不依赖 content 循环）—— 让 TextBubble 能拿到真实宽度
+        // 关键：在 row flex 父中撑开（不依赖 content 循环）—— 让 TextBubble 能拿到真实宽度
         flex: "1 1 0",
         // 防超长 content（图片 / 超长 url）撑爆父
         minWidth: 0,
diff --git a/src/app/chat/deviceid/[deviceId]/DeepLinkPersist.tsx b/src/app/chat/deviceid/[deviceId]/DeepLinkPersist.tsx
index c753a45d..a8157fd1 100644
--- a/src/app/chat/deviceid/[deviceId]/DeepLinkPersist.tsx
+++ b/src/app/chat/deviceid/[deviceId]/DeepLinkPersist.tsx
@@ -7,7 +7,7 @@
  * `redirect` 回调（`app_router.dart:60-78`）。
  *
  * 设计：
- *   - **不**走 Server `redirect()`：避免把 fbid 暴露在 URL 里。
+ *   - 不走 Server `redirect()`：避免把 fbid 暴露在 URL 里。
  *   - deviceId 走 `AuthStorage.getInstance().setDeviceId`（与 `token_interceptor.ts` 同源；
  *     写入键 `cozsweet.deviceId`）。
  *   - fbid 走 `window.localStorage.setItem(StorageKeys.facebookId, ...)`，
diff --git a/src/app/chat/deviceid/[deviceId]/page.tsx b/src/app/chat/deviceid/[deviceId]/page.tsx
index 31de2bb0..687530a1 100644
--- a/src/app/chat/deviceid/[deviceId]/page.tsx
+++ b/src/app/chat/deviceid/[deviceId]/page.tsx
@@ -9,7 +9,7 @@
  * Next.js 16 全局 helper `PageProps<'/literal'>` 由 `next dev` / `next build` /
  * `next typegen` 生成。
  *
- * 这里**不**调用 `redirect()`：把 fbid 暴露在 URL 上对用户不友好；
+ * 这里不调用 `redirect()`：把 fbid 暴露在 URL 上对用户不友好；
  * 跳转推迟到 Client 完成持久化之后。
  */
 
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 8b5815ec..3b935c5e 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -4,7 +4,7 @@
  * Server Component：把访客直接送入 `/splash`，由 splash 页（Client）根据
  * `authStorage.hasLoginToken()` 决定是否再跳 `/chat`。
  *
- * 这里**不**做鉴权重定向：Server 端读不到 localStorage，且当前没有 HttpOnly
+ * 这里不做鉴权重定向：Server 端读不到 localStorage，且当前没有 HttpOnly
  * cookie（见 `src/data/storage/auth/auth_storage.ts` 的 TODO）。
  * `src/proxy.ts` 已为未来 cookie 化预留了基于 `login_token` cookie 的 short-circuit。
  */
diff --git a/src/app/splash/components/splash-button.tsx b/src/app/splash/components/splash-button.tsx
index ab82cac4..6e4c81c9 100644
--- a/src/app/splash/components/splash-button.tsx
+++ b/src/app/splash/components/splash-button.tsx
@@ -2,14 +2,14 @@
 /**
  * Splash 底部按钮组
  *
- * 本组件是 splash 鉴权流程的**纯 UI 入口**：
+ * 本组件是 splash 鉴权流程的纯 UI 入口：
  *   - 消费 `useAuthState` / `useAuthDispatch`（仅用于 isLoading 显示 + 派事件）
- *   - **Skip 按钮 = 显式游客登录入口**（派发 `AuthGuestLoginSubmitted`）
+ *   - Skip 按钮 = 显式游客登录入口（派发 `AuthGuestLoginSubmitted`）
  *   - 社交登录按钮仅派发 `AuthFacebookLoginSubmitted` 事件，由状态机负责调 NextAuth
  *
- * **派事件策略**（**单**事件）：
+ * 派事件策略（单事件）：
  *   - 派业务事件（`AuthGuestLoginSubmitted` / `AuthFacebookLoginSubmitted`）→ 状态机开始跑
- *   - `pendingRedirect: true` 在**登录成功 onDone** 里**自动**置（auth-machine.ts `onLoginSuccess` helper）
+ *   - `pendingRedirect: true` 在登录成功 onDone 里自动置（auth-machine.ts `onLoginSuccess` helper）
  *   - splash-screen 看到 flag=true + loginStatus 非 notLoggedIn → 跳 /chat
  */
 import { useAuthDispatch, useAuthState } from "@/stores/auth/auth-context";
@@ -35,7 +35,7 @@ export function SplashButton() {
 
   return (
     <div className={styles.wrapper}>
-      {/* Skip 按钮 = 显式游客登录入口（派发 AuthGuestLoginSubmitted，**不**做路由跳转） */}
+      {/* Skip 按钮 = 显式游客登录入口（派发 AuthGuestLoginSubmitted，不做路由跳转） */}
       <button
         type="button"
         onClick={handleSkip}
diff --git a/src/core/fonts.ts b/src/core/fonts.ts
index 47de011b..0807400b 100644
--- a/src/core/fonts.ts
+++ b/src/core/fonts.ts
@@ -8,7 +8,7 @@ import localFont from "next/font/local";
  *   subset、inline，浏览器不会向 Google 发送请求，也不会产生 layout shift。
  * - 产出的 CSS 变量由 `globals.css` 桥接到 Tailwind（如 `font-sans`、`font-athelas`）。
  *
- * 注意：本文件**不**通过 `src/lib/index.ts` 桶导出，避免被误打进客户端 bundle。
+ * 注意：本文件不通过 `src/lib/index.ts` 桶导出，避免被误打进客户端 bundle。
  *       引用方式：`import { geistSans, geistMono, athelas } from "@/lib/fonts";`
  */
 
@@ -28,7 +28,7 @@ const geistMono = Geist_Mono({
  * 原始资源：/Users/chase/Documents/cozsweet/fonts/Athelas-*.ttf
  * 放置位置：/public/fonts/Athelas-*.ttf
  *
- * 路径计算（`next/font/local` 要求相对路径从**调用文件**出发）：
+ * 路径计算（`next/font/local` 要求相对路径从调用文件出发）：
  *   src/lib/fonts.ts → ../../public/fonts/...
  */
 const athelas = localFont({
diff --git a/src/core/net/interceptor/token_interceptor.ts b/src/core/net/interceptor/token_interceptor.ts
index e035050f..95f089a4 100644
--- a/src/core/net/interceptor/token_interceptor.ts
+++ b/src/core/net/interceptor/token_interceptor.ts
@@ -87,7 +87,7 @@ export const onRequestToken: FetchHook = async (ctx) => {
 
   const token = await getAuthToken();
   if (token) {
-    // ofetch 推荐：改 ctx.options.headers（**不**依赖 ctx.request 是 Request 实例 —— 实例类型不稳定）
+    // ofetch 推荐：改 ctx.options.headers（不依赖 ctx.request 是 Request 实例 —— 实例类型不稳定）
     const headers = new Headers(ctx.options.headers);
     headers.set("Authorization", `Bearer ${token}`);
     ctx.options.headers = headers;
diff --git a/src/data/repositories/auth_repository.ts b/src/data/repositories/auth_repository.ts
index f6ccb5ef..e5cbcdf7 100644
--- a/src/data/repositories/auth_repository.ts
+++ b/src/data/repositories/auth_repository.ts
@@ -6,8 +6,8 @@
  * 认证仓库：编排远程 API + 本地 AuthStorage + UserStorage。
  * 行为对齐原 Dart `lib/data/repositories/auth_repository_impl.dart`：
  *   - 登录成功后调 `_saveLoginData` 持久化 token + User
- *   - 登出先调 API，再**强制**清本地态（无论 API 成败）
- *   - `getCurrentUser` 成功后**尽力**写本地 User 缓存（不因缓存失败影响主流程）
+ *   - 登出先调 API，再强制清本地态（无论 API 成败）
+ *   - `getCurrentUser` 成功后尽力写本地 User 缓存（不因缓存失败影响主流程）
  *   - 写 storage 失败用 `console.warn` 记录，不让本地缓存失败影响主流程
  *
  * 原始 Dart: lib/data/repositories/auth_repository_impl.dart
@@ -98,7 +98,7 @@ export class AuthRepository implements IAuthRepository {
   }
 
   /**
-   * 退出登录：先调 API 注销服务端会话，**无论成败**都清本地登录态。
+   * 退出登录：先调 API 注销服务端会话，无论成败都清本地登录态。
    * 强制清本地的逻辑：用户即使在 API 失败时也想从设备上登出。
    */
   async logout(): Promise<Result<void>> {
@@ -237,7 +237,7 @@ export class AuthRepository implements IAuthRepository {
   }
 
   /**
-   * 获取当前登录用户。成功后**尽力**写本地 User 缓存（offline hydrate），
+   * 获取当前登录用户。成功后尽力写本地 User 缓存（offline hydrate），
    * 缓存失败用 `console.warn` 记录，不影响主流程。
    */
   async getCurrentUser(): Promise<Result<User>> {
diff --git a/src/data/repositories/interfaces/iauth_repository.ts b/src/data/repositories/interfaces/iauth_repository.ts
index ecf2cf9a..e406d990 100644
--- a/src/data/repositories/interfaces/iauth_repository.ts
+++ b/src/data/repositories/interfaces/iauth_repository.ts
@@ -40,7 +40,7 @@ export interface IAuthRepository {
   sendCode(email: string): Promise<Result<void>>;
 
   /**
-   * 退出登录：先调 API 注销服务端会话，**无论成败**都清本地登录态。
+   * 退出登录：先调 API 注销服务端会话，无论成败都清本地登录态。
    */
   logout(): Promise<Result<void>>;
 
diff --git a/src/data/schemas/chat/chat_send_response.ts b/src/data/schemas/chat/chat_send_response.ts
index d022c9d5..35ca13d9 100644
--- a/src/data/schemas/chat/chat_send_response.ts
+++ b/src/data/schemas/chat/chat_send_response.ts
@@ -15,7 +15,7 @@ export const ChatSendResponseSchema = z.object({
   currentMood: z.string().default(""),
   messageId: z.string(),
   isGuest: z.boolean().default(false),
-  // 函数式 default —— 每次 parse 时**重新**调 Date.now()（后端不返回 timestamp 时用**当下**时间）
+  // 函数式 default —— 每次 parse 时重新调 Date.now()（后端不返回 timestamp 时用当下时间）
   timestamp: z.number().default(() => Date.now()),
 });
 
diff --git a/src/data/storage/chat/chat_storage.ts b/src/data/storage/chat/chat_storage.ts
index eb7a242a..ced0799a 100644
--- a/src/data/storage/chat/chat_storage.ts
+++ b/src/data/storage/chat/chat_storage.ts
@@ -43,7 +43,7 @@ export class ChatStorage implements IChatStorage {
   // ---- guest daily chat quota ----
 
   getGuestDailyChatQuota(): Promise<ResultT<GuestChatQuotaData | null>> {
-    // get-or-init：**有**返**有**，**无**则**用** DTO 默认**值**（`threshold` = max per day）**初**始**化**并**返**回**
+    // get-or-init：有返有，无则用 DTO 默认值（`threshold` = max per day）初始化并返回
     return SpAsyncUtil.getJson(
       StorageKeys.guestChatQuota,
       GuestChatQuotaSchema,
@@ -57,7 +57,7 @@ export class ChatStorage implements IChatStorage {
         today,
       );
       if (Result.isErr(initResult)) {
-        return existing; // **初**始**化**失**败** → **返**原**始** null
+        return existing; // 初始化失败 → 返原始 null
       }
       return {
         success: true,
@@ -78,7 +78,7 @@ export class ChatStorage implements IChatStorage {
   // ---- guest total quota ----
 
   getGuestTotalQuota(): Promise<ResultT<number | null>> {
-    // get-or-init：**有**返**有**，**无**则**用** DTO 默认**值**（`totalQuotaDefault`）**初**始**化**并**返**回**
+    // get-or-init：有返有，无则用 DTO 默认值（`totalQuotaDefault`）初始化并返回
     return SpAsyncUtil.getJson(
       StorageKeys.guestTotalQuotaRemaining,
       z.number(),
diff --git a/src/lib/auth/auth.ts b/src/lib/auth/auth.ts
index 5b74243a..5f3ab344 100644
--- a/src/lib/auth/auth.ts
+++ b/src/lib/auth/auth.ts
@@ -24,7 +24,7 @@ export const handler = NextAuth({
   // 把 OAuth provider 的 token 塞进 NextAuth session，供前端取用：
   //   - Google: account.id_token     → 调后端 /api/auth/google-login 换业务 token
   //   - Facebook: account.access_token → 调后端 /api/auth/facebook-login
-  // 仅在**首次 sign-in** 时把 `account` 注入到 JWT；后续请求 account=undefined
+  // 仅在首次 sign-in 时把 `account` 注入到 JWT；后续请求 account=undefined
   // （由 NextAuth 控制），所以下面的 `if (account)` 守卫是必要的。
   callbacks: {
     async jwt({ token, account }) {
diff --git a/src/lib/auth/auth_platform.ts b/src/lib/auth/auth_platform.ts
index 34bfe1c4..a621e47c 100644
--- a/src/lib/auth/auth_platform.ts
+++ b/src/lib/auth/auth_platform.ts
@@ -2,7 +2,7 @@
 /**
  * AuthPlatform 统一 OAuth 登录入口
  *
- * **两个**独立方法（**不**再依赖构造器）：
+ * 两个独立方法（不再依赖构造器）：
  *   - `googleSignIn()`   → 触发 Google OAuth
  *   - `facebookSignIn()` → 触发 Facebook OAuth
  *
@@ -12,7 +12,7 @@
  *   3. NextAuth 写 next-auth.session-token (httpOnly) cookie
  *   4. 重定向到 callbackUrl (默认 /chat)
  *
- * **不**做任何持久化（不写 unstorage / 不调后端 / 不设自定义 cookie）。
+ * 不做任何持久化（不写 unstorage / 不调后端 / 不设自定义 cookie）。
  * 原始 Dart: nextauth-helpers.{googleLogin, facebookLogin}()
  */
 import { signIn } from "next-auth/react";
diff --git a/src/lib/auth/logout.ts b/src/lib/auth/logout.ts
index cef2bb89..8251ef61 100644
--- a/src/lib/auth/logout.ts
+++ b/src/lib/auth/logout.ts
@@ -3,7 +3,7 @@
  * 登出（NextAuth 流程触发器）
  *
  * 调用 `signOut()` 清除 NextAuth session cookie 并重定向。
- * **不**做任何持久化（不写 unstorage / 不调后端 / 不设自定义 cookie）。
+ * 不做任何持久化（不写 unstorage / 不调后端 / 不设自定义 cookie）。
  * 原始 Dart: nextauth-helpers.logout()
  */
 import { signOut } from "next-auth/react";
diff --git a/src/providers/session-provider.tsx b/src/providers/session-provider.tsx
index d22e742c..c12777a0 100644
--- a/src/providers/session-provider.tsx
+++ b/src/providers/session-provider.tsx
@@ -3,7 +3,7 @@
  * SessionProvider 客户端包装
  *
  * 背景：next-auth v4 的 `SessionProvider`（从 `next-auth/react` 导出）
- * **没有** `"use client"` 指令。这是 v4 的历史遗留（v5 / Auth.js 已修正）。
+ * 没有 `"use client"` 指令。这是 v4 的历史遗留（v5 / Auth.js 已修正）。
  *
  * 当 Server Component（如 `src/app/layout.tsx`）直接 import 时，Next.js
  * 不会自动把它当 client component 渲染，会继续在服务端 tree 里执行，导致
diff --git a/src/router/index.ts b/src/router/index.ts
index a700b2fb..81e9c9b9 100644
--- a/src/router/index.ts
+++ b/src/router/index.ts
@@ -1,4 +1,4 @@
-// /**
+// /
 //  * Router 公共导出
 //  *
 //  * 集中管理：
diff --git a/src/router/proxy.ts b/src/router/proxy.ts
index a319b450..45de18d0 100644
--- a/src/router/proxy.ts
+++ b/src/router/proxy.ts
@@ -1,4 +1,4 @@
-// /**
+// /
 //  * Next.js 16 Proxy（原 `middleware.ts`）
 //  *
 //  * 行为（鉴权路由统一在此处理，业务层组件不再做 auth-driven 跳转）：
@@ -9,17 +9,17 @@
 //  *   - 其他情况透传（`NextResponse.next()`）
 //  *
 //  * 重要约束：
-//  *   - **不**做自定义 cookie 持久化：统一用 NextAuth 内置 `next-auth.session-token` /
+//  *   - 不做自定义 cookie 持久化：统一用 NextAuth 内置 `next-auth.session-token` /
 //  *     `__Secure-next-auth.session-token`（v5 默认 httpOnly + secure）作信号。
 //  *   - 真正的鉴权门在 Client 侧 `useSession()`（next-auth/react），用于 UI 状态。
-//  *   - 路由跳转（**唯一**鉴权跳转点）由本 proxy 集中处理。
+//  *   - 路由跳转（唯一鉴权跳转点）由本 proxy 集中处理。
 //  *   - 副作用：邮箱登录用户（不走 NextAuth）不会被本 proxy 识别为已登录。
 //  *     邮箱登录在后续轮次若要恢复 proxy 行为，需引入 NextAuth EmailProvider 或独立
 //  *     email-session 体系。
 //  *
 //  * Next 16 重要变更（参见 `node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/proxy.md`）：
 //  *   - 文件从 `middleware.ts` 重命名为 `proxy.ts`；`middleware` 仍可用但已 deprecated。
-//  *   - 默认 Node.js runtime；**不**支持 `runtime` 配置（设置会抛错）。
+//  *   - 默认 Node.js runtime；不支持 `runtime` 配置（设置会抛错）。
 //  *   - 函数导出名建议为 `proxy`（可默认导出）。
 //  *
 //  * 用 `src/` 时 proxy 必须放在 `src/` 内（参见 `src-folder.md`）。
@@ -36,13 +36,13 @@
 //   ROUTES,
 // } from "@/router/routes";
 
-// /** NextAuth 内置 session cookie 名（v5 默认 httpOnly） */
+// / NextAuth 内置 session cookie 名（v5 默认 httpOnly） */
 // const SESSION_COOKIE_NAMES = [
 //   "next-auth.session-token",
 //   "__Secure-next-auth.session-token",
 // ];
 
-// /** proxy 入口日志（Node.js runtime 跑，pino 兼容）—— 排查 / 监控路由用 */
+// / proxy 入口日志（Node.js runtime 跑，pino 兼容）—— 排查 / 监控路由用 */
 // const log = new Logger("Proxy");
 
 // function isAuthOnlyRoute(pathname: string): boolean {
@@ -53,7 +53,7 @@
 //   return (PROTECTED_ROUTES as readonly string[]).includes(pathname);
 // }
 
-// /**
+// /
 //  * Proxy 入口
 //  */
 // export function proxy(request: NextRequest) {
@@ -89,7 +89,7 @@
 //   return NextResponse.next();
 // }
 
-// /**
+// /
 //  * 匹配器：排除 API、Next 静态资源、图标与常见静态文件扩展名。
 //  * 不排除 `_next/data`，因为 proxy 文档明确说明"即使在排除列表中 proxy 仍会跑"
 //  * （安全兜底）。
diff --git a/src/router/routes.ts b/src/router/routes.ts
index 111d1614..cf14ac3e 100644
--- a/src/router/routes.ts
+++ b/src/router/routes.ts
@@ -9,9 +9,9 @@
  *  - 不导出 Client-only 模块（`use-auth-gate` 走独立路径导入），保证 Server bundle 不被污染。
  *  - 动态深链通过 `ROUTE_BUILDERS` 函数生成，避免手拼字符串。
  *
- * 注意：proxy 路由跳转逻辑（2026-06-15 迁出），但本文件的**类型化常量**仍在
+ * 注意：proxy 路由跳转逻辑（2026-06-15 迁出），但本文件的类型化常量仍在
  * 被 8 个组件（auth-screen / chat-header / DeepLinkPersist /
- * error / not-found / page / sidebar-screen / splash-screen）使用 —— **不能**整体注释。
+ * error / not-found / page / sidebar-screen / splash-screen）使用 —— 不能整体注释。
  */
 
 /** 静态路由字面量 */
diff --git a/src/stores/auth/auth-actors.ts b/src/stores/auth/auth-actors.ts
index 33602007..74e5a0c8 100644
--- a/src/stores/auth/auth-actors.ts
+++ b/src/stores/auth/auth-actors.ts
@@ -93,7 +93,7 @@ export const syncFacebookBackendActor = fromPromise<
 });
 
 // ========== 显式游客登录 actor（opt-in） ==========
-// 由 splash UI 派发 `AuthGuestLoginSubmitted` 触发，**不**自动跑。
+// 由 splash UI 派发 `AuthGuestLoginSubmitted` 触发，不自动跑。
 // 取代了之前 checkAuthStatusActor 的 auto-guest-login 行为 —— 避免每次
 // 访 splash 都自动创建游客账号污染后端。
 //
@@ -115,7 +115,7 @@ export const guestLoginActor = fromPromise<LoginStatus, void>(async () => {
     console.log("[auth-machine] guestLoginActor SHORT-CIRCUIT (has local guestToken) → return guest");
     return "guest" as LoginStatus;
   }
-  // Result.err(_) 时**不**抛 —— 落到 API 路径让真正的错误信号出现
+  // Result.err(_) 时不抛 —— 落到 API 路径让真正的错误信号出现
 
   // 2. 没有（或读不出）才走完整流程：拿 deviceId → 调后端
   const deviceId = await deviceIdentifier.getDeviceId();
@@ -138,15 +138,15 @@ export const guestLoginActor = fromPromise<LoginStatus, void>(async () => {
 
 // ========== 启动 / 恢复时检查登录态 actor（只查不创） ==========
 // 由 <AuthStatusChecker /> 在 mount 时派发（一次性）。
-// 流程（**纯只读**）：
+// 流程（纯只读）：
 //   1. deviceIdentifier.getDeviceId()     —— 无则通过 fingerprintjs 生成 + 落盘
-//      （给后续 OAuth/email 登录准备 deviceId，**不**在 splash 首次访问就 auto-create 游客）
+//      （给后续 OAuth/email 登录准备 deviceId，不在 splash 首次访问就 auto-create 游客）
 //   2. AuthStorage.getLoginToken()         —— 有 → "email"
 //   3. AuthStorage.getGuestToken()         —— 有 → "guest"
-//   4. 都没有 → "notLoggedIn"（让用户**显式**选 OAuth / Email / Guest 入口）
+//   4. 都没有 → "notLoggedIn"（让用户显式选 OAuth / Email / Guest 入口）
 
 export const checkAuthStatusActor = fromPromise<LoginStatus, void>(async () => {
-  // 1. 拿 deviceId（**不**用于 auto-guest-login，仅供后续登录用）
+  // 1. 拿 deviceId（不用于 auto-guest-login，仅供后续登录用）
   await deviceIdentifier.getDeviceId();
   const storage = AuthStorage.getInstance();
 
diff --git a/src/stores/auth/auth-events.ts b/src/stores/auth/auth-events.ts
index 7e49d84b..7ac1fae9 100644
--- a/src/stores/auth/auth-events.ts
+++ b/src/stores/auth/auth-events.ts
@@ -13,9 +13,9 @@ export type AuthEvent =
   | { type: "AuthModeChanged"; mode: AuthMode }
   | { type: "AuthFormCleared" }
   | { type: "AuthReset" }
-  /** 启动 / 恢复时检查登录态 —— 拿 deviceId → 查 token（**不**自动创建游客账号） */
+  /** 启动 / 恢复时检查登录态 —— 拿 deviceId → 查 token（不自动创建游客账号） */
   | { type: "AuthStatusCheckSubmitted" }
-  /** 显式游客登录 —— splash 上点"游客模式"按钮触发（**不**自动） */
+  /** 显式游客登录 —— splash 上点"游客模式"按钮触发（不自动） */
   | { type: "AuthGuestLoginSubmitted" }
   // 业务事件（提交）
   | { type: "AuthEmailLoginSubmitted"; email: string; password: string }
@@ -35,7 +35,7 @@ export type AuthEvent =
   | { type: "AuthGoogleSyncSubmitted"; idToken: string }
   | { type: "AuthFacebookSyncSubmitted"; accessToken: string }
   // ──────────────────────────────────────────────────────────────────────
-  // splash / auth screen 跳完 /chat 后**清**"刚按了"信号（一次性）：
-  // `pendingRedirect` 在 login onDone action 里**自动**置 true（不是按钮派的）
-  // —— 因此**只**需要 `AuthClearPendingRedirect` 一个事件
+  // splash / auth screen 跳完 /chat 后清"刚按了"信号（一次性）：
+  // `pendingRedirect` 在 login onDone action 里自动置 true（不是按钮派的）
+  // —— 因此只需要 `AuthClearPendingRedirect` 一个事件
   | { type: "AuthClearPendingRedirect" };
diff --git a/src/stores/auth/auth-machine.ts b/src/stores/auth/auth-machine.ts
index 87bf0385..baa9b644 100644
--- a/src/stores/auth/auth-machine.ts
+++ b/src/stores/auth/auth-machine.ts
@@ -27,13 +27,13 @@ export type { AuthEvent } from "./auth-events";
 //
 // 设计：所有登录/同步流跑完都回 `idle`（带正确 `loginStatus`）。
 //
-// `pendingRedirect: boolean`（"用户**显式**触发了登录"信号）——
-// **在登录成功的 onDone 里自动置 true**：
+// `pendingRedirect: boolean`（"用户显式触发了登录"信号）——
+// 在登录成功的 onDone 里自动置 true：
 //   splash / auth screen 看到 `pendingRedirect && loginStatus !== "notLoggedIn"` 跳 /chat
 //   跳完派 `AuthClearPendingRedirect` 置 false
-// checkingAuthStatus **不**设 flag —— 被动查 token 不算"用户意图"。
+// checkingAuthStatus 不设 flag —— 被动查 token 不算"用户意图"。
 //
-// 注：onDone 用了**内联**assign（不是 helper function）—— XState v5 的 TypeScript
+// 注：onDone 用了内联assign（不是 helper function）—— XState v5 的 TypeScript
 // 推断对 helper return type 不友好；内联能保留 `state.matches("loadingXxx")` 的类型。
 // ============================================================
 export const authMachine = setup({
@@ -83,7 +83,7 @@ export const authMachine = setup({
         },
         // 启动 / 恢复时检查登录态 —— 由 <AuthStatusChecker /> 派发
         AuthStatusCheckSubmitted: "checkingAuthStatus",
-        // 显式游客登录 —— 由 splash UI 派发（**不**自动）
+        // 显式游客登录 —— 由 splash UI 派发（不自动）
         AuthGuestLoginSubmitted: "loadingGuestLogin",
         AuthEmailLoginSubmitted: "loadingEmailLogin",
         AuthEmailRegisterSubmitted: "loadingEmailRegister",
@@ -98,7 +98,7 @@ export const authMachine = setup({
             errorMessage: "Apple login not implemented",
           }),
         },
-        // splash / auth screen 跳完 /chat 后**清**flag
+        // splash / auth screen 跳完 /chat 后清flag
         AuthClearPendingRedirect: {
           actions: assign({ pendingRedirect: false }),
         },
@@ -110,10 +110,10 @@ export const authMachine = setup({
       invoke: {
         src: "checkAuthStatus",
         onDone: {
-          target: "idle", // ← status check 完回 idle（**不**再假冒 success）
+          target: "idle", // ← status check 完回 idle（不再假冒 success）
           actions: assign({
             loginStatus: ({ event }) => event.output,
-            // **不**置 pendingRedirect —— 状态查询是**被动**读 token，不算"用户意图"
+            // 不置 pendingRedirect —— 状态查询是被动读 token，不算"用户意图"
             errorMessage: null,
           }),
         },
diff --git a/src/stores/auth/auth-state.ts b/src/stores/auth/auth-state.ts
index 6ff27957..0d4cee55 100644
--- a/src/stores/auth/auth-state.ts
+++ b/src/stores/auth/auth-state.ts
@@ -18,12 +18,12 @@ export interface AuthState {
   /** 当前登录状态（未登录 / 游客 / OAuth / 邮箱） */
   loginStatus: LoginStatus;
   /**
-   * **一次性的"刚按了"信号** —— Skip / Facebook / 邮箱登录按钮**刚**派事件 → 置 true
+   * 一次性的"刚按了"信号 —— Skip / Facebook / 邮箱登录按钮刚派事件 → 置 true
    *   → splash-screen / auth-screen 看到 `pendingRedirect && loginStatus !== "notLoggedIn"` 触发跳转
    *   → 跳完置 false
    *
-   * 历史：之前用 useRef 做 transition detection，**但** re-mount 时 ref 重置，bug 复发。
-   *       现**在 auth state 里持久**（machine 不重置）—— re-mount 时也能区分"刚按"和"历史"。
+   * 历史：之前用 useRef 做 transition detection，但 re-mount 时 ref 重置，bug 复发。
+   *       现在 auth state 里持久（machine 不重置）—— re-mount 时也能区分"刚按"和"历史"。
    */
   pendingRedirect: boolean;
 }
diff --git a/src/stores/auth/oauth-session-sync.tsx b/src/stores/auth/oauth-session-sync.tsx
index 8594f07d..8d228ce5 100644
--- a/src/stores/auth/oauth-session-sync.tsx
+++ b/src/stores/auth/oauth-session-sync.tsx
@@ -9,7 +9,7 @@
  *   → auth machine 调 `authRepository.googleLogin/facebookLogin` 换业务 token
  *   → 业务 token 写入本地 storage
  *
- * 此组件**无可见 UI**（返回 null），仅作为 NextAuth session 与 auth state
+ * 此组件无可见 UI（返回 null），仅作为 NextAuth session 与 auth state
  * machine 之间的桥接器。挂在 RootProviders 内、AuthProvider 之后：
  *   <AuthProvider>     ← 提供 useAuthState / useAuthDispatch
  *     <OAuthSessionSync />  ← 用上面两个 hook
diff --git a/src/stores/chat/chat-context.tsx b/src/stores/chat/chat-context.tsx
index 60e483f0..896a6349 100644
--- a/src/stores/chat/chat-context.tsx
+++ b/src/stores/chat/chat-context.tsx
@@ -8,8 +8,8 @@
  * 兼容性：保持原 `useChatState()` / `useChatDispatch()` API。
  * 内部将 XState 状态机快照映射回原 `ChatState` 形状。
  *
- * 注：WebSocket 长生命周期 actor **由 chat-screen.tsx 监听 auth 状态机驱动**——
- * 鉴权解耦（loginStatus 在 auth，chat 机器**不**感知鉴权）。
+ * 注：WebSocket 长生命周期 actor 由 chat-screen.tsx 监听 auth 状态机驱动——
+ * 鉴权解耦（loginStatus 在 auth，chat 机器不感知鉴权）。
  */
 import {
   type Dispatch,
@@ -26,7 +26,7 @@ import type { ChatEvent, ChatState as MachineContext } from "./chat-machine";
 /**
  * 对外暴露的 State 形状
  *
- * **isGuest 字段已删** —— 由 chat-screen 派生自 `auth.loginStatus === "guest"`。
+ * isGuest 字段已删 —— 由 chat-screen 派生自 `auth.loginStatus === "guest"`。
  *   消费方（chat-screen）通过 `useAuthState()` 取 loginStatus，本地派生 isGuest。
  */
 interface ChatState {
@@ -40,9 +40,9 @@ interface ChatState {
   isLoadingMore: boolean;
   hasMore: boolean;
   historyOffset: number;
-  /** 游客配额加载完成标**志**（**仅** guestSession 期间） —— UI 可**用**此**显**示 loading */
+  /** 游客配额加载完成标志（仅 guestSession 期间） —— UI 可用此显示 loading */
   quotaLoaded: boolean;
-  /** history 初始加**载**完成标**志**（local → network → save 跑**完**） —— UI 可**用**此**显**示 loading */
+  /** history 初始加载完成标志（local → network → save 跑完） —— UI 可用此显示 loading */
   historyLoaded: boolean;
 }
 
diff --git a/src/stores/chat/chat-events.ts b/src/stores/chat/chat-events.ts
index 747f26ae..1d2eee74 100644
--- a/src/stores/chat/chat-events.ts
+++ b/src/stores/chat/chat-events.ts
@@ -3,20 +3,20 @@
  *
  * 事件名与原 Dart ChatEvent 对齐。
  *
- * 历史：原本有 `ChatAuthStatusChanged`（chat 机器刷新 isGuest）—— 已**删**。
+ * 历史：原本有 `ChatAuthStatusChanged`（chat 机器刷新 isGuest）—— 已删。
  * 鉴权状态变化（loginStatus）由 chat-screen 通过 `useAuthState()` 订阅，
- * chat 机器**不**感知鉴权。
+ * chat 机器不感知鉴权。
  *
- * 鉴权生命周期事件（**本轮新增**）：
- *   - `ChatGuestLogin`：游客进入 /chat —— 拉本地消息 + 初始化配额（**不**连 WS）
- *   - `ChatNonGuestLogin`：非游客进入 /chat —— 拉服务器端首屏 + **连** WS（token 在 payload）
+ * 鉴权生命周期事件（本轮新增）：
+ *   - `ChatGuestLogin`：游客进入 /chat —— 拉本地消息 + 初始化配额（不连 WS）
+ *   - `ChatNonGuestLogin`：非游客进入 /chat —— 拉服务器端首屏 + 连 WS（token 在 payload）
  *   - `ChatLogout`：登出 / 切换用户 —— 断 WS + 清消息
  *
- * 设计：**所有**WS / 历史 / 配额相关副作用**全部**通过派发事件给 chat 机器处理，
- * chat-screen **不**直接创建 ChatWebSocket / 不读 AuthStorage（除 token 取值）。
+ * 设计：所有WS / 历史 / 配额相关副作用全部通过派发事件给 chat 机器处理，
+ * chat-screen 不直接创建 ChatWebSocket / 不读 AuthStorage（除 token 取值）。
  */
 export type ChatEvent =
-  // 鉴权生命周期（**用户**显式触发登录后由 chat-screen 派）
+  // 鉴权生命周期（用户显式触发登录后由 chat-screen 派）
   | { type: "ChatGuestLogin" }
   | { type: "ChatNonGuestLogin"; token: string }
   | { type: "ChatLogout" }
@@ -24,7 +24,7 @@ export type ChatEvent =
   | { type: "ChatSendMessage"; content: string }
   | { type: "ChatSendImage"; imageBase64: string }
   | { type: "ChatLoadMoreHistory" }
-  // WebSocket / AI 推句（**由** chat 机器内部 actor 派回 —— "机器**自**驱动"）
+  // WebSocket / AI 推句（由 chat 机器内部 actor 派回 —— "机器自驱动"）
   | {
       type: "ChatAISentenceReceived";
       index: number;
diff --git a/src/stores/chat/chat-machine.actors.ts b/src/stores/chat/chat-machine.actors.ts
index 65588391..df910fb9 100644
--- a/src/stores/chat/chat-machine.actors.ts
+++ b/src/stores/chat/chat-machine.actors.ts
@@ -2,16 +2,16 @@
  * Chat 状态机：4 个 XState actor
  *
  * 从 `chat-machine.ts` 抽出的"Actors"段：
- *   - `loadQuotaActor`（fromPromise，**仅**游客有意义 —— 拉**日**配 + 总**配**）
- *   - `loadHistoryActor`（fromPromise —— local → network → save network to local 3 **步**）
- *   - `sendMessageHttpActor`（fromPromise，**已** wire —— "一次发送 = 一次返回"）
- *   - `loadMoreHistoryActor`（fromPromise —— 翻**页**，**不**走 local-first）
- *   - `chatWebSocketActor`（fromCallback，长生命周期 —— **仅** userSession 期间 invoke）
+ *   - `loadQuotaActor`（fromPromise，仅游客有意义 —— 拉日配 + 总配）
+ *   - `loadHistoryActor`（fromPromise —— local → network → save network to local 3 步）
+ *   - `sendMessageHttpActor`（fromPromise，已 wire —— "一次发送 = 一次返回"）
+ *   - `loadMoreHistoryActor`（fromPromise —— 翻页，不走 local-first）
+ *   - `chatWebSocketActor`（fromCallback，长生命周期 —— 仅 userSession 期间 invoke）
  *
  * 设计：
  *   - 依赖 `chat-machine.helpers.ts`（纯函数 + 数据加载）
  *   - 依赖 `createChatWebSocket`（`@/core/net/chat-websocket`）
- *   - 保留**全链日志**（用户要求"不要将其删除"）
+ *   - 保留全链日志（用户要求"不要将其删除"）
  *   - 命名约定：`[chat-machine]` 前缀 —— 与 `chat-machine.ts` 的日志对齐
  */
 
@@ -31,12 +31,12 @@ import {
 import type { ChatEvent } from "./chat-events";
 
 // ============================================================
-// Init 任务 1：拉游客配额（fromPromise，**纯** local）
+// Init 任务 1：拉游客配额（fromPromise，纯 local）
 // ============================================================
 /**
- * 拉游客**日**配 + 总**配**（**仅** guestSession 期间 invoke）
- * - 失**败**返 `{ remaining: 0, total: 0 }`（**不**抛，**让** UI **还**是**能**进** ready）
- * - onDone 在 state machine **里**赋 guestRemainingQuota + guestTotalQuota + 设 quotaLoaded: true
+ * 拉游客日配 + 总配（仅 guestSession 期间 invoke）
+ * - 失败返 `{ remaining: 0, total: 0 }`（不抛，让 UI 还是能进 ready）
+ * - onDone 在 state machine 里赋 guestRemainingQuota + guestTotalQuota + 设 quotaLoaded: true
  */
 export const loadQuotaActor = fromPromise<{
   remaining: number;
@@ -49,13 +49,13 @@ export const loadQuotaActor = fromPromise<{
 });
 
 // ============================================================
-// Init 任务 2：拉 history 3 步流（fromPromise，**返**回**最**终**结**果**）
+// Init 任务 2：拉 history 3 步流（fromPromise，返回最终结果）
 // ============================================================
 /**
- * local → network → save network to local 3 步流（**返**回** network **最**终** messages**）
- * - 选**方**案 A（fromPromise）：UI **不**会**看**到** local 中**间**态**，**直**接**显**示** network **结**果**
- * - 内部 3 步**走** helper `readAndSyncHistory`（**日**志**全**在** helper **里**）
- * - 失**败**返 local（**退**而**求**其**次**）
+ * local → network → save network to local 3 步流（返回 network 最终 messages）
+ * - 选方案 A（fromPromise）：UI 不会看到 local 中间态，直接显示 network 结果
+ * - 内部 3 步走 helper `readAndSyncHistory`（日志全在 helper 里）
+ * - 失败返 local（退而求其次）
  */
 export const loadHistoryActor = fromPromise<{
   messages: UiMessage[];
@@ -81,10 +81,10 @@ export const loadHistoryActor = fromPromise<{
 // HTTP: one-shot Promise
 // ============================================================
 /**
- * HTTP 发送消息（**一次发送 = 一次返回**）
- * - 后端响应**就**是 AI 回复（`ChatSendResponse.reply: string`）
- * - **不**再调 `getLocalMessages()`（**多此一举**）
- * - 返回 `{ reply: UiMessage }` —— `sending.onDone` 把它**追加**到 `context.messages`
+ * HTTP 发送消息（一次发送 = 一次返回）
+ * - 后端响应就是 AI 回复（`ChatSendResponse.reply: string`）
+ * - 不再调 `getLocalMessages()`（多此一举）
+ * - 返回 `{ reply: UiMessage }` —— `sending.onDone` 把它追加到 `context.messages`
  */
 export const sendMessageHttpActor = fromPromise<
   { reply: UiMessage },
@@ -122,7 +122,7 @@ export const sendMessageHttpActor = fromPromise<
   return { reply };
 });
 
-/** 翻历史（pagination）—— **不**走 local-first，**纯** server fetch */
+/** 翻历史（pagination）—— 不走 local-first，纯 server fetch */
 export const loadMoreHistoryActor = fromPromise<
   { messages: UiMessage[]; hasMore: boolean; newOffset: number },
   { offset: number }
@@ -173,13 +173,13 @@ export const loadMoreHistoryActor = fromPromise<
 // WebSocket: long-lived callback
 // ============================================================
 /**
- * 长生命周期 WebSocket（**仅** `userSession` 期间 invoke）
+ * 长生命周期 WebSocket（仅 `userSession` 期间 invoke）
  * - 启动：连 WS，事件 → sendBack 派回机器
  * - 停止（cleanup）：disconnect
- * - **游客**不** invoke 此 actor（业务事实"游客不连 WS"）
+ * - 游客不 invoke 此 actor（业务事实"游客不连 WS"）
  *
  * 之所以用 fromCallback 而非 fromPromise：
- * - WS 是长连接，**不**是一次性 Promise
+ * - WS 是长连接，不是一次性 Promise
  * - fromCallback 提供 `sendBack` 回调，actor 内部事件 → 机器
  * - cleanup 函数 → XState 在 parent state exit 时自动调用
  */
diff --git a/src/stores/chat/chat-machine.helpers.ts b/src/stores/chat/chat-machine.helpers.ts
index 4f976e0d..0241888a 100644
--- a/src/stores/chat/chat-machine.helpers.ts
+++ b/src/stores/chat/chat-machine.helpers.ts
@@ -4,20 +4,20 @@
  * 从 `chat-machine.ts` 抽出的"helpers"段：
  *   - 翻页大小常量
  *   - 仓库注入（接口类型 → 单例）
- *   - DTO ↔ UiMessage 映射（**纯函数** —— 可单测）
- *   - Result → number 映射（**纯函数** —— 可单测）
- *   - 2 **个**独立 init 任务**的**数据加载**：
- *     - `readGuestQuota()` —— 游客**日**配 + 总**配**（**仅**游客有意义，**纯** ChatStorage）
- *     - `readAndSyncHistory()` —— local → network → save network to local 3 **步**
+ *   - DTO ↔ UiMessage 映射（纯函数 —— 可单测）
+ *   - Result → number 映射（纯函数 —— 可单测）
+ *   - 2 个独立 init 任务的数据加载：
+ *     - `readGuestQuota()` —— 游客日配 + 总配（仅游客有意义，纯 ChatStorage）
+ *     - `readAndSyncHistory()` —— local → network → save network to local 3 步
  *
  * 设计目标：
- *   - helpers **无 XState 依赖**（可独立 import / 测试）
+ *   - helpers 无 XState 依赖（可独立 import / 测试）
  *   - actors 依赖 helpers（import）
- *   - machine 依赖 actors（import）—— **不**直接依赖 helpers
+ *   - machine 依赖 actors（import）—— 不直接依赖 helpers
  *
  * 历史：
- *   - `readInitData` + `InitResult` 已**删**（**被** 2 **个**独立 helper **替**换**）
- *   - `AuthStorage` import **已**删**（**只** `readInitData` 用过，**移**到** `chatInit` actor **上**层**调**用**）
+ *   - `readInitData` + `InitResult` 已删（被 2 个独立 helper 替换）
+ *   - `AuthStorage` import 已删（只 `readInitData` 用过，移到 `chatInit` actor 上层调用）
  */
 
 import type { UiMessage } from "@/models/chat/ui-message";
@@ -31,7 +31,7 @@ import { Result } from "@/utils/result";
 // ============================================================
 // Constants
 // ============================================================
-/** 翻历史每页大小（**仅** `loadMoreHistoryActor` 用） */
+/** 翻历史每页大小（仅 `loadMoreHistoryActor` 用） */
 export const PAGE_SIZE = 20;
 
 // ============================================================
@@ -44,7 +44,7 @@ export const chatRepo: IChatRepository = chatRepository;
 // DTO ↔ UiMessage 映射
 // ============================================================
 /**
- * ChatMessage[] → UiMessage[]（**纯函数**）
+ * ChatMessage[] → UiMessage[]（纯函数）
  * - 与 Dart `LocalMessage → ChatMessage` 等价
  * - 业务事实：`role === "assistant"` → `isFromAI: true`
  */
@@ -63,9 +63,9 @@ export function localMessagesToUi(
 }
 
 /**
- * ChatSendResponse → UiMessage（**纯函数**）
- * - 业务事实：后端响应**就是** AI 的回复
- * - 用后端 `timestamp`（**不**用本地 time）—— 多设备/时区**一致**
+ * ChatSendResponse → UiMessage（纯函数）
+ * - 业务事实：后端响应就是 AI 的回复
+ * - 用后端 `timestamp`（不用本地 time）—— 多设备/时区一致
  */
 export function sendResponseToUiMessage(response: ChatSendResponse): UiMessage {
   return {
@@ -78,7 +78,7 @@ export function sendResponseToUiMessage(response: ChatSendResponse): UiMessage {
 // ============================================================
 // Result → number 映射
 // ============================================================
-/** 日配额 Result → number（**纯函数**） */
+/** 日配额 Result → number（纯函数） */
 export function mapQuotaResult(
   r: Result<{ remaining: number } | null>,
   fallback: number,
@@ -87,7 +87,7 @@ export function mapQuotaResult(
   return fallback;
 }
 
-/** 总配额 Result → number（**纯函数**） */
+/** 总配额 Result → number（纯函数） */
 export function mapTotalQuotaResult(
   r: Result<number | null>,
   fallback: number,
@@ -118,26 +118,26 @@ export async function readGuestQuota(): Promise<{
 // Init 任务 2：history 3 步流（local → network → save）—— `loadHistoryActor` 调
 // ============================================================
 /**
- * 拉 history **流**程（**每**步**都**记**日**志** —— 用户要求"**不**要**删**除**"）
- *   1. **读** local（chatRepo.getLocalMessages）→ **返** localMessages
- *   2. **读** network（chatRepo.getHistory）→ **返** networkMessages
- *   3. **用** network **覆**盖** local（chatRepo.saveMessagesToLocal）→ local **被**同步
+ * 拉 history 流程（每步都记日志 —— 用户要求"不要删除"）
+ *   1. 读 local（chatRepo.getLocalMessages）→ 返 localMessages
+ *   2. 读 network（chatRepo.getHistory）→ 返 networkMessages
+ *   3. 用 network 覆盖 local（chatRepo.saveMessagesToLocal）→ local 被同步
  *
- * **返**回** network **最**终** messages**（authorititative），**不**返** local（UI **不**需**要**过渡**态**）
+ * 返回 network 最终 messages（authorititative），不返 local（UI 不需要过渡态）
  *
- * **保**留**日**志**（**前**缀 `[chat-machine]` 与 chat-machine.actors.ts **对**齐**）
+ * 保留日志（前缀 `[chat-machine]` 与 chat-machine.actors.ts 对齐）
  */
 export async function readAndSyncHistory(): Promise<{
-  messages: UiMessage[];        // network **最**终** messages（authorititative）
+  messages: UiMessage[];        // network 最终 messages（authorititative）
   hasMore: boolean;
   newOffset: number;
-  localOverwritten: boolean;     // true = local **已**被 network **覆**盖**（**写**入** ChatStorage）
-  /** 真实从 local 读到的消息数（**调**试**用**） */
+  localOverwritten: boolean;     // true = local 已被 network 覆盖（写入 ChatStorage）
+  /** 真实从 local 读到的消息数（调试用） */
   localCount: number;
-  /** 真实从 network 读到的消息数（**调**试**用**） */
+  /** 真实从 network 读到的消息数（调试用） */
   networkCount: number;
 }> {
-  // 1. **读** local
+  // 1. 读 local
   const localResult = await chatRepo.getLocalMessages();
   const localMessages =
     Result.isOk(localResult) && localResult.data
@@ -147,16 +147,16 @@ export async function readAndSyncHistory(): Promise<{
     count: localMessages.length,
   });
 
-  // 2. **读** network
+  // 2. 读 network
   const networkResult = await chatRepo.getHistory(PAGE_SIZE, 0);
   if (!Result.isOk(networkResult)) {
-    // network 失**败** —— **返**空 messages（**不**让 UI 卡**住**）
+    // network 失败 —— 返空 messages（不让 UI 卡住）
     console.error(
       "[chat-machine] loadHistory NETWORK FAILED",
       networkResult.success ? null : (networkResult as { error: unknown }).error,
     );
     return {
-      messages: localMessages, // **退**而**求**其**次**：返 local（**不**然**屏**幕**空**）
+      messages: localMessages, // 退而求其次：返 local（不然屏幕空）
       hasMore: false,
       newOffset: 0,
       localOverwritten: false,
@@ -169,7 +169,7 @@ export async function readAndSyncHistory(): Promise<{
     count: networkUi.length,
   });
 
-  // 3. **用** network **覆**盖** local（"**再**用**网**络**数**据**覆**盖**本**地**数**据"**这**句**的**字**面**实**现**）
+  // 3. 用 network 覆盖 local（"再用网络数据覆盖本地数据"这句的字面实现）
   const saveResult = await chatRepo.saveMessagesToLocal(networkResult.data.messages);
   const localOverwritten = Result.isOk(saveResult);
   console.log("[chat-machine] loadHistory SAVE TO LOCAL DONE", {
diff --git a/src/stores/chat/chat-machine.ts b/src/stores/chat/chat-machine.ts
index 5a568844..92b368ba 100644
--- a/src/stores/chat/chat-machine.ts
+++ b/src/stores/chat/chat-machine.ts
@@ -1,32 +1,32 @@
 /**
  * Chat 状态机（XState v5）
  *
- * **鉴权解耦**（**事件驱动**）：
- *   chat 机器**不**感知鉴权 / **不**管 WebSocket —— 由 chat-screen 派生 loginStatus
- *   chat-screen **只**派 3 个事件：
- *     - `ChatGuestLogin` → 游客会话（**断** WS = 不连）
- *     - `ChatNonGuestLogin { token }` → 非游客会话（**连** WS）
+ * 鉴权解耦（事件驱动）：
+ *   chat 机器不感知鉴权 / 不管 WebSocket —— 由 chat-screen 派生 loginStatus
+ *   chat-screen 只派 3 个事件：
+ *     - `ChatGuestLogin` → 游客会话（断 WS = 不连）
+ *     - `ChatNonGuestLogin { token }` → 非游客会话（连 WS）
  *     - `ChatLogout` → 登出（机器自动 cleanup WS actor）
  *
- * **状态结构**（parent state 模式）：
+ * 状态结构（parent state 模式）：
  *   - `idle`：屏没挂 / 登出
- *   - `guestSession`（**parent**）：游客会话 —— **不** invoke WS
- *   - `userSession`（**parent**）：非游客会话 —— **invoke WS**（持久）
+ *   - `guestSession`（parent）：游客会话 —— 不 invoke WS
+ *   - `userSession`（parent）：非游客会话 —— invoke WS（持久）
  *
- * **init 双任务**（**核**心**重**构**）：
- *   - guestSession.initializing：loadQuota + loadHistory **并**行**（`invoke: [...]` **数**组**）
- *   - userSession.initializing：loadHistory + parent-level chatWebSocket **并**行
- *   - **每**个**任务**都**是**独**立** actor，**不**互**相**等**待**（**除**非** `always` barrier）
+ * init 双任务（核心重构）：
+ *   - guestSession.initializing：loadQuota + loadHistory 并行（`invoke: [...]` 数组）
+ *   - userSession.initializing：loadHistory + parent-level chatWebSocket 并行
+ *   - 每个任务都是独立 actor，不互相等待（除非 `always` barrier）
  *
- * **消息发送路径**（**业务事实**）：
- *   - `wsConnected: true`（**仅** userSession 期间）→ **走 WS**，**不**消耗次数（**仅**配额规则）
- *   - `wsConnected: false` → **走 HTTP**，消耗次数（**仅**游客有意义 —— 非游客 0-1=max(0,-1)=0 天然 no-op）
+ * 消息发送路径（业务事实）：
+ *   - `wsConnected: true`（仅 userSession 期间）→ 走 WS，不消耗次数（仅配额规则）
+ *   - `wsConnected: false` → 走 HTTP，消耗次数（仅游客有意义 —— 非游客 0-1=max(0,-1)=0 天然 no-op）
  *   - `ChatWebSocketConnected` 事件 → `wsConnected = true`
- *   - `userSession.exit` action → `wsConnected = false`（WS actor cleanup 时**也**会跑 exit）
+ *   - `userSession.exit` action → `wsConnected = false`（WS actor cleanup 时也会跑 exit）
  *
- * **配额（**仅**游客）**：
+ * 配额（仅游客）：
  *   - 非游客"无消息限制"（业务事实）—— 永不被赋值
- *   - `appendUserMessage` 减 `context.wsConnected ? q : Math.max(0, q-1)` —— WS 已连时**不**递减
+ *   - `appendUserMessage` 减 `context.wsConnected ? q : Math.max(0, q-1)` —— WS 已连时不递减
  *
  */
 
@@ -75,7 +75,7 @@ export const chatMachine = setup({
     appendUserMessage: assign(({ context, event }) => {
       if (event.type !== "ChatSendMessage") return {};
 
-      // 两**个**额度**同**步**更**新**：WS 已**连****不**递减（**实**时**会**话**不**消耗**），HTTP **必**须**减
+      // 两个额度同步更新：WS 已连不递减（实时会话不消耗），HTTP 必须减
       const newRemaining = context.wsConnected
         ? context.guestRemainingQuota
         : Math.max(0, context.guestRemainingQuota - 1);
@@ -83,8 +83,8 @@ export const chatMachine = setup({
         ? context.guestTotalQuota
         : Math.max(0, context.guestTotalQuota - 1);
 
-      // 持**久**化**两**个**额度**（** fire-and-forget，**不** await —— assign **是** sync）
-      // daily quota 需**要** today **字**符**串**（**让** ChatStorage 跨**天**判**断** reset）
+      // 持久化两个额度（ fire-and-forget，不 await —— assign 是 sync）
+      // daily quota 需要 today 字符串（让 ChatStorage 跨天判断 reset）
       const today = formatDate();
       ChatStorage.getInstance().setGuestDailyChatQuota(newRemaining, today);
       ChatStorage.getInstance().setGuestTotalQuota(newTotal);
@@ -117,7 +117,7 @@ export const chatMachine = setup({
 
     appendUserImage: assign(({ context, event }) => {
       if (event.type !== "ChatSendImage") return {};
-      // **同** appendUserMessage：两**个**额度**同**步**减
+      // 同 appendUserMessage：两个额度同步减
       const newRemaining = context.wsConnected
         ? context.guestRemainingQuota
         : Math.max(0, context.guestRemainingQuota - 1);
@@ -211,13 +211,13 @@ export const chatMachine = setup({
     },
 
     // ========================================================================
-    // guestSession（游客会话 —— **不**连 WS，2 **个** init 任务**并**行**）
+    // guestSession（游客会话 —— 不连 WS，2 个 init 任务并行）
     // ========================================================================
     guestSession: {
       initial: "initializing",
       states: {
         initializing: {
-          // "always" barrier：两**个**任务**都**完**成**才**进** ready
+          // "always" barrier：两个任务都完成才进 ready
           always: [
             {
               target: "ready",
@@ -225,7 +225,7 @@ export const chatMachine = setup({
             },
           ],
           invoke: [
-            // 任务 1：加载配额（fromPromise，**返**结果 + onDone 设 flag）
+            // 任务 1：加载配额（fromPromise，返结果 + onDone 设 flag）
             {
               id: "loadQuota",
               src: "loadQuota",
@@ -237,13 +237,13 @@ export const chatMachine = setup({
                 })),
               },
               onError: {
-                // 失败**也**标 loaded，**不**卡 init（**游**客**可**能 quota 服务**不**可**用**，**让** UI **进** ready）
+                // 失败也标 loaded，不卡 init（游客可能 quota 服务不可用，让 UI 进 ready）
                 actions: assign({
                   quotaLoaded: true,
                 }),
               },
             },
-            // 任务 2：拉 history（fromPromise，**返**回**最**终** network messages**）
+            // 任务 2：拉 history（fromPromise，返回最终 network messages）
             {
               id: "loadHistory",
               src: "loadHistory",
@@ -256,7 +256,7 @@ export const chatMachine = setup({
                 })),
               },
               onError: {
-                // 失败**也**标 loaded，**不**卡 init（**让** UI **还**是**能**进** ready，**屏**幕**可**能**空**）
+                // 失败也标 loaded，不卡 init（让 UI 还是能进 ready，屏幕可能空）
                 actions: assign({
                   historyLoaded: true,
                 }),
@@ -266,29 +266,29 @@ export const chatMachine = setup({
         },
         ready: {
           on: {
-            // **配**额**检**查** + 发**送**消息**（3 **条** guard，**按**顺**序**匹**配**）
-            // 1. **总**配**额**（guestTotalQuota）**不**足 → **触**发** quota exceeded dialog，**不**发**送**
-            // 2. **每**日**配**额**（guestRemainingQuota）**不**足 → **同**上**
-            // 3. **两**个**配**额**都** OK + **内**容**非**空** → **发**送** + **减**配**额**
+            // 配额检查 + 发送消息（3 条 guard，按顺序匹配）
+            // 1. 总配额（guestTotalQuota）不足 → 触发 quota exceeded dialog，不发送
+            // 2. 每日配额（guestRemainingQuota）不足 → 同上
+            // 3. 两个配额都 OK + 内容非空 → 发送 + 减配额
             ChatSendMessage: [
-              // 1. 总配**额** **不**足**（guestTotalQuota <= 0） → **触**发** quota exceeded dialog
+              // 1. 总配额 不足（guestTotalQuota <= 0） → 触发 quota exceeded dialog
               {
                 guard: ({ context }) => context.guestTotalQuota <= 0,
                 actions: "incrementQuotaExceeded",
               },
-              // 2. 每**日**配**额** **不**足**（guestRemainingQuota <= 0） → **触**发** quota exceeded dialog
+              // 2. 每日配额 不足（guestRemainingQuota <= 0） → 触发 quota exceeded dialog
               {
                 guard: ({ context }) => context.guestRemainingQuota <= 0,
                 actions: "incrementQuotaExceeded",
               },
-              // 3. 两**个**配**额**都** OK + **内**容**非**空** → **发**送**（**只**用** appendUserMessage **自**己**的**日**志**）
+              // 3. 两个配额都 OK + 内容非空 → 发送（只用 appendUserMessage 自己的日志）
               {
                 actions: "appendUserMessage",
                 guard: ({ event }) => event.content.trim().length > 0,
                 target: "sending",
               },
             ],
-            // **配**额**检**查** + 发**送**图**片**（**同**样** 3 **条** guard，**不**检**查** "内**容**空"**）
+            // 配额检查 + 发送图片（同样 3 条 guard，不检查 "内容空"）
             ChatSendImage: [
               {
                 guard: ({ context }) => context.guestTotalQuota <= 0,
@@ -303,7 +303,7 @@ export const chatMachine = setup({
                 target: "sending",
               },
             ],
-            // **删**除 ChatLoadMoreHistory handler —— 游客**无**服**务**端** history，**不**支**持**翻**页**
+            // 删除 ChatLoadMoreHistory handler —— 游客无服务端 history，不支持翻页
             ChatLogout: "#chat.idle",
             ChatNonGuestLogin: "#chat.userSession",
             ChatAISentenceReceived: { actions: "appendOrUpdateAISentence" },
@@ -331,18 +331,18 @@ export const chatMachine = setup({
             },
           },
         },
-        // **删**除 loadingMore（游客**无**翻**页**）
+        // 删除 loadingMore（游客无翻页）
       },
     },
 
     // ========================================================================
-    // userSession（非游客会话 —— WS **父**级 + history **子**级**）
+    // userSession（非游客会话 —— WS 父级 + history 子级）
     // ========================================================================
     userSession: {
       initial: "initializing",
       exit: "clearWsConnected",
       invoke: {
-        // 父级：WS 长**连**接（**一**进**来****就**连，跨 initializing/ready/sending/loadingMore）
+        // 父级：WS 长连接（一进来就连，跨 initializing/ready/sending/loadingMore）
         src: "chatWebSocket",
         input: ({ event }) => ({
           token: event.type === "ChatNonGuestLogin" ? event.token : "",
@@ -350,7 +350,7 @@ export const chatMachine = setup({
       },
       states: {
         initializing: {
-          // barrier：WS **连**上** + history **加**载**完**成**才**进** ready
+          // barrier：WS 连上 + history 加载完成才进 ready
           always: [
             {
               target: "ready",
@@ -358,7 +358,7 @@ export const chatMachine = setup({
             },
           ],
           invoke: {
-            // 任务 2：拉 history（**只**调**用** loadHistoryActor，**不**再**用** loadMoreHistoryActor）
+            // 任务 2：拉 history（只调用 loadHistoryActor，不再用 loadMoreHistoryActor）
             src: "loadHistory",
             onDone: {
               actions: assign(({ event }) => ({
@@ -370,7 +370,7 @@ export const chatMachine = setup({
               })),
             },
             onError: {
-              // 失败**也**标 loaded，**不**卡 init
+              // 失败也标 loaded，不卡 init
               actions: assign({
                 isLoadingMore: false,
                 historyLoaded: true,
diff --git a/src/stores/chat/chat-state.ts b/src/stores/chat/chat-state.ts
index bc81015b..02ec6607 100644
--- a/src/stores/chat/chat-state.ts
+++ b/src/stores/chat/chat-state.ts
@@ -4,17 +4,17 @@
  * 注：GuestChatQuota 仍位于 chat-machine.ts（属于业务常量，与上下文配对紧密）。
  *
  * 历史：
- *   - `isGuest: boolean` 字段已**删**（由 chat-screen 派生自 `auth.loginStatus === "guest"`）
- *   - `guestRemainingQuota` / `guestTotalQuota` default **改 0**：
+ *   - `isGuest: boolean` 字段已删（由 chat-screen 派生自 `auth.loginStatus === "guest"`）
+ *   - `guestRemainingQuota` / `guestTotalQuota` default 改 0：
  *     - 游客：chat-screen 派 `ChatInit` → readInitData 调 ChatStorage → onDone 条件赋
- *     - 非游客：**永不被赋值**（业务事实"非游客无消息限制"）—— 0 - 1 = max(0, -1) = 0 天然 no-op
+ *     - 非游客：永不被赋值（业务事实"非游客无消息限制"）—— 0 - 1 = max(0, -1) = 0 天然 no-op
  *     - 0 同时表示"未初始化"和"已耗尽" —— UI 用 `if (isGuest && ...)` 天然过滤
  *
- * 新增 `wsConnected: boolean`（**仅** userSession 期间 true）：
- *   - **WS 已连** → 消息发送走 WS，**不**消耗次数
- *   - **WS 未连** → 消息发送走 HTTP，消耗次数
+ * 新增 `wsConnected: boolean`（仅 userSession 期间 true）：
+ *   - WS 已连 → 消息发送走 WS，不消耗次数
+ *   - WS 未连 → 消息发送走 HTTP，消耗次数
  *   - `ChatWebSocketConnected` 事件 → true
- *   - `userSession.exit` → false（WS actor cleanup 时**也**会跑 exit）
+ *   - `userSession.exit` → false（WS actor cleanup 时也会跑 exit）
  */
 import type { UiMessage } from "@/models/chat/ui-message";
 
@@ -22,13 +22,13 @@ export interface ChatState {
   messages: UiMessage[];
   isReplyingAI: boolean;
   /**
-   * WebSocket 连接状态（**仅** userSession 期间 true）
-   * - 决定消息发送**路径**（WS / HTTP）和**是否消耗**次数
-   * - true：走 WS，**不**消耗次数
+   * WebSocket 连接状态（仅 userSession 期间 true）
+   * - 决定消息发送路径（WS / HTTP）和是否消耗次数
+   * - true：走 WS，不消耗次数
    * - false：走 HTTP，消耗次数
    */
   wsConnected: boolean;
-  /** 游客剩余配额（次/天）—— **仅**游客业务展示用
+  /** 游客剩余配额（次/天）—— 仅游客业务展示用
    */
   guestRemainingQuota: number;
   /** 游客总配额（仅游客展示用） */
@@ -37,14 +37,14 @@ export interface ChatState {
   isLoadingMore: boolean;
   hasMore: boolean;
   historyOffset: number;
-  /** 游客配额加载完成标**志**（**仅** guestSession 期间） —— default false
-   * - guestSession.initializing **走** always barrier：`quotaLoaded && historyLoaded` **才**进** ready
-   * - userSession **永不为** true（**不**调 loadQuota）—— OK，**不**影响 barrier
+  /** 游客配额加载完成标志（仅 guestSession 期间） —— default false
+   * - guestSession.initializing 走 always barrier：`quotaLoaded && historyLoaded` 才进 ready
+   * - userSession 永不为 true（不调 loadQuota）—— OK，不影响 barrier
    */
   quotaLoaded: boolean;
-  /** history 加**载**完成标**志**（initial load —— local → network → save 跑**完**）
+  /** history 加载完成标志（initial load —— local → network → save 跑完）
    * - guestSession.initializing / userSession.initializing 走 always barrier
-   * - **不**被 `loadMoreHistoryActor` 设**置**（**翻**页**是**另**一**码**事**）
+   * - 不被 `loadMoreHistoryActor` 设置（翻页是另一码事）
    */
   historyLoaded: boolean;
 }
diff --git a/src/utils/result.ts b/src/utils/result.ts
index bb6eab20..0420ae9f 100644
--- a/src/utils/result.ts
+++ b/src/utils/result.ts
@@ -57,9 +57,9 @@ export const Result = {
    *
    * 错误处理策略（重点）：
    *   1. 捕获后用 `toError` 规范化（保留 .stack / .code / .status 等字段）
-   *   2. **用 Logger 记录**（带 stack + component=Result 标签）—— 调试 dev 控制台可见，
+   *   2. 用 Logger 记录（带 stack + component=Result 标签）—— 调试 dev 控制台可见，
    *      生产环境走 JSON pipeline 接入日志平台
-   *   3. **不**重新抛出 —— 调用方拿到的永远是 `Result<T>`（throw 风格调用方可在
+   *   3. 不重新抛出 —— 调用方拿到的永远是 `Result<T>`（throw 风格调用方可在
    *      最外层显式 `throw Result.unwrap(r)`）
    */
   async wrap<T>(thunk: () => Promise<T>): Promise<Result<T>> {

From dcb6312fa37a15d104a47448f99c59a0757880df Mon Sep 17 00:00:00 2001
From: chenhang <averych@126.com>
Date: Tue, 16 Jun 2026 15:17:44 +0800
Subject: [PATCH 2/3] feat(chat): add quota-exhausted banner for guest users

Introduce ChatQuotaExhaustedBanner component that displays a pink gradient
banner with an "Unlock your membership to continue" CTA when a guest user's
free chat quota has been exhausted. The banner is shown in ChatScreen when
isGuest is true, quota has loaded, and the chat state machine's
quotaExceededTrigger has been incremented by a quota guard. Default click
navigates to /subscription, with an optional onUnlock callback for
overrides/tests. Styles align with the existing splash and sidebar VIP
card visual language.
---
 .../chat-quota-exhausted-banner.module.css    | 50 +++++++++++++
 .../chat-quota-exhausted-banner.tsx           | 73 +++++++++++++++++++
 src/app/chat/components/chat-screen.tsx       | 22 +++++-
 src/app/chat/components/index.ts              |  2 +
 src/data/storage/chat/chat_storage.ts         | 14 ----
 src/stores/chat/chat-context.tsx              | 13 +---
 src/stores/chat/chat-machine.ts               | 11 ++-
 src/stores/chat/chat-state.ts                 |  7 --
 8 files changed, 153 insertions(+), 39 deletions(-)
 create mode 100644 src/app/chat/components/chat-quota-exhausted-banner.module.css
 create mode 100644 src/app/chat/components/chat-quota-exhausted-banner.tsx

diff --git a/src/app/chat/components/chat-quota-exhausted-banner.module.css b/src/app/chat/components/chat-quota-exhausted-banner.module.css
new file mode 100644
index 00000000..7c82fe05
--- /dev/null
+++ b/src/app/chat/components/chat-quota-exhausted-banner.module.css
@@ -0,0 +1,50 @@
+/* ChatQuotaExhaustedBanner — 游客配额耗尽横幅
+ * 视觉规格（与设计稿对齐）：
+ *   - 粉→品红渐变背景（与 splash gradient 一致）
+ *   - 居中文案 + 渐变 pill 按钮
+ *   - 圆角 + 阴影（与 /sidebar 已有卡片的视觉重量对齐）
+ */
+
+.banner {
+  flex: 0 0 auto;
+  margin: 0 var(--spacing-lg, 16px) var(--spacing-lg, 16px);
+  padding: var(--spacing-xl, 24px) var(--spacing-lg, 16px);
+  border-radius: 24px;
+  background: linear-gradient(135deg, #f96ade 0%, #f657a0 100%);
+  text-align: center;
+  box-shadow: 0 4px 16px rgba(248, 77, 150, 0.25);
+}
+
+.text {
+  color: #fff;
+  font-size: 1rem;
+  font-weight: 600;
+  line-height: 1.4;
+  margin: 0 0 var(--spacing-lg, 16px);
+  /* 与 splash 标题的粉色字保持视觉一致（白底渐变叠加层需要白字保证可读性） */
+  opacity: 0.95;
+}
+
+.cta {
+  width: 100%;
+  padding: 0.875rem 1.5rem;
+  border: none;
+  border-radius: 999px;
+  background: linear-gradient(135deg, #ffb8e0 0%, #f57ec0 100%);
+  color: #fff;
+  font-size: 1rem;
+  font-weight: 700;
+  cursor: pointer;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+  transition:
+    transform 0.15s ease,
+    box-shadow 0.15s ease;
+}
+
+.cta:hover {
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+}
+
+.cta:active {
+  transform: scale(0.98);
+}
diff --git a/src/app/chat/components/chat-quota-exhausted-banner.tsx b/src/app/chat/components/chat-quota-exhausted-banner.tsx
new file mode 100644
index 00000000..96dbb2b4
--- /dev/null
+++ b/src/app/chat/components/chat-quota-exhausted-banner.tsx
@@ -0,0 +1,73 @@
+"use client";
+/**
+ * ChatQuotaExhaustedBanner 游客配额耗尽横幅
+ *
+ * 何时显示：
+ *   - isGuest === true（仅游客业务事实"非游客无配额上限"）
+ *   - quotaLoaded === true（避免一进 /chat 就跳 banner）
+ *   - guestTotalQuota <= 0（用 total 而非 remaining —— 配额刚减为 0 不立即跳）
+ *
+ * 视觉规格（与设计稿对齐）：
+ *   - 粉→品红渐变背景（与 splash 渐变一致）
+ *   - 大字号粉色/白色提示文案（"The limit for free chat times has been reached today"）
+ *   - 粉→品红渐变 pill 按钮"Unlock your membership to continue" → 跳 /subscription
+ *
+ * 业务关系：
+ *   - 与 `src/app/sidebar/components/vip-benefits-card.tsx` 的 "Activate VIP Membership" 行为一致
+ *   - 与 `src/app/sidebar/components/voice-package-card.tsx` 的 "Buy Package" 行为一致
+ *
+ * 不做的事：
+ *   - 不直接管理 state machine（chat 机器不感知 UI 层）
+ *   - 不显示具体剩余分钟数（已用 total<=0 表达"耗尽"足够）
+ */
+import { useRouter } from "next/navigation";
+
+import { ROUTES } from "@/router/routes";
+
+import styles from "./chat-quota-exhausted-banner.module.css";
+
+export interface ChatQuotaExhaustedBannerProps {
+  /**
+   * 自定义点击回调（不传则默认 router.push(ROUTES.subscription)）
+   * - 测试时可传 mock
+   * - 嵌入其他场景时（如 nested overlay）可传自定义
+   */
+  onUnlock?: () => void;
+}
+
+export function ChatQuotaExhaustedBanner({
+  onUnlock,
+}: ChatQuotaExhaustedBannerProps) {
+  const router = useRouter();
+
+  const handleClick = () => {
+    if (onUnlock) {
+      onUnlock();
+      return;
+    }
+    router.push(ROUTES.subscription);
+  };
+
+  return (
+    <div
+      className={styles.banner}
+      role="status"
+      aria-live="polite"
+      data-testid="chat-quota-exhausted-banner"
+    >
+      <p className={styles.text}>
+        The limit for free chat times
+        <br />
+        has been reached today
+      </p>
+      <button
+        type="button"
+        className={styles.cta}
+        onClick={handleClick}
+        aria-label="Unlock your membership to continue"
+      >
+        Unlock your membership to continue
+      </button>
+    </div>
+  );
+}
diff --git a/src/app/chat/components/chat-screen.tsx b/src/app/chat/components/chat-screen.tsx
index 66a3899f..c2103c1a 100644
--- a/src/app/chat/components/chat-screen.tsx
+++ b/src/app/chat/components/chat-screen.tsx
@@ -2,8 +2,6 @@
 /**
  * ChatScreen 编排层
  *
- * 原始 Dart: lib/ui/chat/chat_screen.dart（172 行）
- *
  * 职责（本文件）：
  *   - 订阅 auth 状态机（loginStatus）—— 派生 isGuest / 派鉴权生命周期事件给 chat 机器
  *   - 屏幕生命周期事件（init / visible / invisible）
@@ -38,9 +36,11 @@ import { BrowserHintOverlay } from "./browser-hint-overlay";
 import { ChatArea } from "./chat-area";
 import { ChatHeader } from "./chat-header";
 import { ChatInputBar } from "./chat-input-bar";
+import { ChatQuotaExhaustedBanner } from "./chat-quota-exhausted-banner";
 import { PwaInstallOverlay } from "./pwa-install-overlay";
 import styles from "./chat-screen.module.css";
 
+
 /**
  * 派生 isGuest —— 单一来源：`auth.loginStatus`
  */
@@ -84,6 +84,17 @@ export function ChatScreen() {
   // isGuest 派生（chat-screen 是唯一知道这个值的地方 —— chat 机器无 isGuest 字段）
   const isGuest = deriveIsGuest(authState.loginStatus);
 
+  // 游客配额耗尽 → 显示 Unlock CTA banner（替代 ChatInputBar）
+  // 三重条件：游客 + 配额加载完 + 用户被配额 guard 拦截过至少一次
+  // - quotaLoaded 避免一进 /chat 就跳 banner（loadQuota 还在 in-flight）
+  // - quotaExceededTrigger 而非 guestTotalQuota / guestRemainingQuota ——
+  //   trigger 由 chat 机器的 guard 在 ChatSendMessage / ChatSendImage 被拦截时 +1，
+  //   是 "用户被配额拒绝过" 的权威信号（避免依赖 quota 数值本身的边界判断）
+  const showExhaustedBanner =
+    isGuest && state.quotaLoaded && state.quotaExceededTrigger > 0;
+
+
+
   // ─────────────────────────────────────────────────────────────
   // 屏幕生命周期 + 派初次鉴权生命周期事件
   // ─────────────────────────────────────────────────────────────
@@ -138,7 +149,12 @@ export function ChatScreen() {
             isGuest={isGuest}
           />
 
-          <ChatInputBar disabled={state.isReplyingAI} />
+          {showExhaustedBanner ? (
+            <ChatQuotaExhaustedBanner />
+          ) : (
+            <ChatInputBar disabled={state.isReplyingAI} />
+          )}
+
         </div>
 
         {/* 浏览器提示（应用内浏览器检测） */}
diff --git a/src/app/chat/components/index.ts b/src/app/chat/components/index.ts
index 8b298016..5a830fd3 100644
--- a/src/app/chat/components/index.ts
+++ b/src/app/chat/components/index.ts
@@ -8,7 +8,9 @@ export * from "./chat-area";
 export * from "./chat-header";
 export * from "./chat-input-bar";
 export * from "./chat-input-text-field";
+export * from "./chat-quota-exhausted-banner";
 export * from "./chat-screen";
+
 export * from "./chat-send-button";
 export * from "./date-header";
 export * from "./fullscreen-image-viewer";
diff --git a/src/data/storage/chat/chat_storage.ts b/src/data/storage/chat/chat_storage.ts
index ced0799a..cdffd6cf 100644
--- a/src/data/storage/chat/chat_storage.ts
+++ b/src/data/storage/chat/chat_storage.ts
@@ -1,19 +1,5 @@
 "use client";
 
-/**
- * ChatStorage 完整实现（基于 unstorage 抽象）
- *
- * 对齐 Dart 端 `ChatStorage`（lib/data/services/storage/chat/chat_storage.dart）：
- *   - 游客每日聊天配额（GuestChatQuota：{ remaining, date }）
- *   - 游客总配额（int）
- *
- * 注意：本类与 `LocalChatStorage`（IndexedDB / Dexie）是不同类：
- *   - ChatStorage = 游客配额等元数据（KV）
- *   - LocalChatStorage = 聊天记录本身（IndexedDB）
- *
- * 设计：内部使用 SpAsyncUtil 静态类 + Zod 校验；保持对外 API 完全兼容。
- */
-
 import {
   GuestChatQuotaSchema,
   type GuestChatQuotaData,
diff --git a/src/stores/chat/chat-context.tsx b/src/stores/chat/chat-context.tsx
index 896a6349..d286952c 100644
--- a/src/stores/chat/chat-context.tsx
+++ b/src/stores/chat/chat-context.tsx
@@ -1,16 +1,5 @@
 "use client";
-/**
- * ChatContext：基于 XState v5 的 React Context Provider
- *
- * 业务事件通过 `useMachine(chatMachine).send()` 派发。
- * XState 自动处理 HTTP 副作用（invoke + fromPromise actors）。
- *
- * 兼容性：保持原 `useChatState()` / `useChatDispatch()` API。
- * 内部将 XState 状态机快照映射回原 `ChatState` 形状。
- *
- * 注：WebSocket 长生命周期 actor 由 chat-screen.tsx 监听 auth 状态机驱动——
- * 鉴权解耦（loginStatus 在 auth，chat 机器不感知鉴权）。
- */
+
 import {
   type Dispatch,
   type ReactNode,
diff --git a/src/stores/chat/chat-machine.ts b/src/stores/chat/chat-machine.ts
index 92b368ba..e56d66a5 100644
--- a/src/stores/chat/chat-machine.ts
+++ b/src/stores/chat/chat-machine.ts
@@ -33,7 +33,8 @@
 import { setup, assign } from "xstate";
 
 import { ChatStorage } from "@/data/storage/chat/chat_storage";
-import { formatDate } from "@/utils/date";
+import { formatDate, todayString } from "@/utils/date";
+
 
 import { ChatState, initialState } from "./chat-state";
 import type { ChatEvent } from "./chat-events";
@@ -85,8 +86,9 @@ export const chatMachine = setup({
 
       // 持久化两个额度（ fire-and-forget，不 await —— assign 是 sync）
       // daily quota 需要 today 字符串（让 ChatStorage 跨天判断 reset）
-      const today = formatDate();
+      const today = todayString();
       ChatStorage.getInstance().setGuestDailyChatQuota(newRemaining, today);
+
       ChatStorage.getInstance().setGuestTotalQuota(newTotal);
 
       console.log("[chat-machine] appendUserMessage", {
@@ -124,9 +126,12 @@ export const chatMachine = setup({
       const newTotal = context.wsConnected
         ? context.guestTotalQuota
         : Math.max(0, context.guestTotalQuota - 1);
-      const today = formatDate();
+        
+      const today = todayString();
       void ChatStorage.getInstance().setGuestDailyChatQuota(newRemaining, today);
+
       void ChatStorage.getInstance().setGuestTotalQuota(newTotal);
+      
       console.log("[chat-machine] appendUserImage", {
         oldMessagesCount: context.messages.length,
         wsConnected: context.wsConnected,
diff --git a/src/stores/chat/chat-state.ts b/src/stores/chat/chat-state.ts
index 02ec6607..85dabdae 100644
--- a/src/stores/chat/chat-state.ts
+++ b/src/stores/chat/chat-state.ts
@@ -3,13 +3,6 @@
  *
  * 注：GuestChatQuota 仍位于 chat-machine.ts（属于业务常量，与上下文配对紧密）。
  *
- * 历史：
- *   - `isGuest: boolean` 字段已删（由 chat-screen 派生自 `auth.loginStatus === "guest"`）
- *   - `guestRemainingQuota` / `guestTotalQuota` default 改 0：
- *     - 游客：chat-screen 派 `ChatInit` → readInitData 调 ChatStorage → onDone 条件赋
- *     - 非游客：永不被赋值（业务事实"非游客无消息限制"）—— 0 - 1 = max(0, -1) = 0 天然 no-op
- *     - 0 同时表示"未初始化"和"已耗尽" —— UI 用 `if (isGuest && ...)` 天然过滤
- *
  * 新增 `wsConnected: boolean`（仅 userSession 期间 true）：
  *   - WS 已连 → 消息发送走 WS，不消耗次数
  *   - WS 未连 → 消息发送走 HTTP，消耗次数

From 02b1b713a5baf6da9290a13defec676b47a8b6d4 Mon Sep 17 00:00:00 2001
From: chenhang <averych@126.com>
Date: Tue, 16 Jun 2026 15:30:23 +0800
Subject: [PATCH 3/3] style(splash): set Athelas as primary font and italicize
 button text

- Prioritize Athelas in --font-system font stack with system fonts as fallback
- Apply italic style to splash button heading and label for typography emphasis
---
 src/app/splash/components/splash-button.module.css | 2 ++
 src/tokens/typography.css                          | 8 ++++++--
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/app/splash/components/splash-button.module.css b/src/app/splash/components/splash-button.module.css
index 34bce9af..a1b4ca30 100644
--- a/src/app/splash/components/splash-button.module.css
+++ b/src/app/splash/components/splash-button.module.css
@@ -12,6 +12,7 @@
   font-family: var(--font-athelas);
   font-size: var(--font-size-xxl);
   font-weight: 700;
+  font-style: italic;
   color: #ffffff;
   background: transparent;
   border: 0;
@@ -43,6 +44,7 @@
   color: #ffffff;
   font-weight: 700;
   cursor: pointer;
+  font-style: italic;
   display: inline-flex;
   align-items: center;
   justify-content: center;
diff --git a/src/tokens/typography.css b/src/tokens/typography.css
index 320c436f..40352ca3 100644
--- a/src/tokens/typography.css
+++ b/src/tokens/typography.css
@@ -7,8 +7,12 @@
  */
 @theme {
   /* 字体族 */
-  --font-system: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
-    Roboto, "Helvetica Neue", Arial, sans-serif;
+  /*
+   * --font-system 优先用 Athelas（Apple 平台专用字体 — next/font/local，所有平台都能加载）。
+   * 不支持的字符自动回退到 system-ui 等系统字体（浏览器 font fallback 机制）。
+   */
+  --font-system: var(--font-athelas), system-ui, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
   --font-athelas: "Athelas", serif;
 
   /* Tailwind 默认字体别名：font-sans → font-system */