@lobehub/chat 1.96.17 → 1.96.18

package/.cursor/rules/backend-architecture.mdc

@@ -28,70 +28,73 @@ LobeChat 的后端设计注重模块化、可测试性和灵活性，以适应
 
 其主要分层如下：
 
-1.  **客户端服务层 (`src/services`)**:
-    *   位于 src/services/。
-    *   这是客户端业务逻辑的核心层，负责封装各种业务操作和数据处理逻辑。
-    *   **环境适配**: 根据不同的运行环境，服务层会选择合适的数据访问方式：
-        *   **本地数据库模式**: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。
-        *   **远程数据库模式**: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。
-    *   **类型转换**: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise<LobeTool[]>`
-    *   每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件，在实现时应该确保本地模式和远程模式业务逻辑实现一致，只是数据库不同。
-
-2.  **API 接口层 (`TRPC`)**:
-    *   位于 src/server/routers/
-    *   使用 `tRPC` 构建类型安全的 API。Router 根据运行时环境（如 Edge Functions, Node.js Lambda）进行组织。
-    *   负责接收客户端请求，并将其路由到相应的 `Service` 层进行处理。
-    *   新建 lambda 端点时可以参考 src/server/routers/lambda/_template.ts
-
-3.  **服务端服务层 (`server/services`)**:
-    *   位于 src/server/services/。
-    *   核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。
-    *   **平台差异抽象**: 一个关键特性是通过其内部的 `impls` 子目录（例如 src/server/services/file/impls 包含 s3.ts 和 local.ts）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
-    *   目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。
-    *   服务会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。
-
-4.  **仓库层 (`Repositories`)**:
-    *   位于 src/database/repositories/。
-    *   主要处理**复杂的跨表查询和数据聚合**逻辑，特别是当需要从**多个 `Model`** 获取数据并进行组合时。
-    *   与 `Model` 层不同，`Repository` 层专注于复杂的业务查询场景，而不涉及简单的领域模型转换。
-    *   当业务逻辑涉及多表关联、复杂的数据统计或需要事务处理时，会使用 `Repository` 层。
-    *   如果数据操作简单（仅涉及单个 `Model`），则通常直接在 `src/services` 层调用 `Model` 并进行简单的类型断言。
-
-5.  **模型层 (`Models`)**:
-    *   位于 src/database/models/ (例如 src/database/models/plugin.ts 和 src/database/models/document.ts)。
-    *   提供对数据库中各个表（由 src/database/schemas/ 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。
-    *   `Model` 类专注于单个数据表的直接操作，**不涉及复杂的领域模型转换**，这些转换通常在上层的 `src/services` 中通过类型断言完成。
-    * model（例如 Topic） 层接口经常需要从对应的 schema 层导入 NewTopic 和 TopicItem
-    * 创建新的 model 时可以参考 src/database/models/_template.ts
-
-6.  **数据库 (`Database`)**:
-    *   **客户端模式 (浏览器/PWA)**: 使用 PGLite (基于 WASM 的 PostgreSQL)，数据存储在用户浏览器本地。
-    *   **服务端模式 (云部署)**: 使用远程 PostgreSQL 数据库。
-    *   **Electron 桌面应用**:
-        *   Electron 客户端会启动一个本地 Node.js 服务。
-        *   本地服务通过 `tRPC` 与 Electron 的渲染进程通信。
-        *   数据库选择依赖于是否开启**云同步**功能：
-            *   **云同步开启**: 连接到远程 PostgreSQL 数据库。
-            *   **云同步关闭**: 使用 PGLite (通过 Node.js 的 WASM 实现) 在本地存储数据。
+1.  客户端服务层 (`src/services`):
+
+    - 位于 src/services/。
+    - 这是客户端业务逻辑的核心层，负责封装各种业务操作和数据处理逻辑。
+    - 环境适配: 根据不同的运行环境，服务层会选择合适的数据访问方式：
+        - 本地数据库模式: 直接调用 `Model` 层进行数据操作，适用于浏览器 PGLite 和本地 Electron 应用。
+        - 远程数据库模式: 通过 `tRPC` 客户端调用服务端 API，适用于需要云同步的场景。
+    - 类型转换: 对于简单的数据类型转换，直接在此层进行类型断言，如 `this.pluginModel.query() as Promise<LobeTool[]>`
+    - 每个服务模块通常包含 `client.ts`（本地模式）、`server.ts`（远程模式）和 `type.ts`（接口定义）文件，在实现时应该确保本地模式和远程模式业务逻辑实现一致，只是数据库不同。
+
+2.  API 接口层 (`TRPC`):
+
+    - 位于 src/server/routers/
+    - 使用 `tRPC` 构建类型安全的 API。Router 根据运行时环境（如 Edge Functions, Node.js Lambda）进行组织。
+    - 负责接收客户端请求，并将其路由到相应的 `Service` 层进行处理。
+    - 新建 lambda 端点时可以参考 src/server/routers/lambda/\_template.ts
+
+3.  仓库层 (`Repositories`):
+
+    - 位于 src/database/repositories/。
+    - 主要处理复杂的跨表查询和数据聚合逻辑，特别是当需要从多个 `Model` 获取数据并进行组合时。
+    - 与 `Model` 层不同，`Repository` 层专注于复杂的业务查询场景，而不涉及简单的领域模型转换。
+    - 当业务逻辑涉及多表关联、复杂的数据统计或需要事务处理时，会使用 `Repository` 层。
+    - 如果数据操作简单（仅涉及单个 `Model`），则通常直接在 `src/services` 层调用 `Model` 并进行简单的类型断言。
+
+4.  模型层 (`Models`):
+
+    - 位于 src/database/models/ (例如 src/database/models/plugin.ts 和 src/database/models/document.ts)。
+    - 提供对数据库中各个表（由 src/database/schemas/ 中的 Drizzle ORM schema 定义）的基本 CRUD (创建、读取、更新、删除) 操作和简单的查询能力。
+    - `Model` 类专注于单个数据表的直接操作，不涉及复杂的领域模型转换，这些转换通常在上层的 `src/services` 中通过类型断言完成。
+    - model（例如 Topic） 层接口经常需要从对应的 schema 层导入 NewTopic 和 TopicItem
+    - 创建新的 model 时可以参考 src/database/models/\_template.ts
+
+5.  数据库 (`Database`):
+    - 客户端模式 (浏览器/PWA): 使用 PGLite (基于 WASM 的 PostgreSQL)，数据存储在用户浏览器本地。
+    - 服务端模式 (云部署): 使用远程 PostgreSQL 数据库。
+    - Electron 桌面应用:
+        - Electron 客户端会启动一个本地 Node.js 服务。
+        - 本地服务通过 `tRPC` 与 Electron 的渲染进程通信。
+        - 数据库选择依赖于是否开启云同步功能：
+            - 云同步开启: 连接到远程 PostgreSQL 数据库。
+            - 云同步关闭: 使用 PGLite (通过 Node.js 的 WASM 实现) 在本地存储数据。
 
 ## 数据流向说明
 
 ### 浏览器/PWA 模式
+
 ```
-UI (React) → Zustand State → Model Layer → PGLite (本地数据库)
+UI (React) → Zustand action -> Client Service → Model Layer → PGLite (本地数据库)
 ```
 
 ### 服务端模式
+
 ```
-UI (React) → Zustand State → tRPC Client → tRPC Routers → Services → Repositories/Models → Remote PostgreSQL
+UI (React) → Zustand action → Client Service -> TRPC Client → TRPC Routers  → Repositories/Models → Remote PostgreSQL
 ```
 
 ### Electron 桌面应用模式
+
 ```
-UI (Electron Renderer) → Zustand State → tRPC Client → 本地 Node.js 服务 → tRPC Routers → Services → Repositories/Models → PGLite/Remote PostgreSQL (取决于云同步设置)
+UI (Electron Renderer) → Zustand action → Client Service -> TRPC Client → 本地 Node.js 服务 → TRPC Routers → Repositories/Models → PGLite/Remote PostgreSQL (取决于云同步设置)
 ```
 
+## 服务层 (Server Services)
 
-
-
-
+-  位于 src/server/services/。
+-  核心职责是封装独立的、可复用的业务逻辑单元。这些服务应易于测试。
+-  平台差异抽象: 一个关键特性是通过其内部的 `impls` 子目录（例如 src/server/services/file/impls 包含 s3.ts 和 local.ts）来抹平不同运行环境带来的差异（例如云端使用 S3 存储，桌面版使用本地文件系统）。这使得上层（如 `tRPC` routers）无需关心底层具体实现。
+-  目标是使 `tRPC` router 层的逻辑尽可能纯粹，专注于请求处理和业务流程编排。
+-  服务可能会调用 `Repository` 层或直接调用 `Model` 层进行数据持久化和检索，也可能调用其他服务。

package/.cursor/rules/code-review.mdc

@@ -0,0 +1,69 @@
+---
+description: How to code review
+globs: 
+alwaysApply: false
+---
+# Role Description
+
+- You are a senior full-stack engineer skilled in performance optimization, security, and design systems.  
+- You excel at reviewing code and providing constructive feedback.  
+- Your task is to review submitted Git diffs **in Chinese** and return a structured review report.  
+- Review style: concise, direct, focused on what matters most, with actionable suggestions.
+
+## Before the Review
+
+Gather the modified code and context. Please strictly follow the process below:
+
+1. Use `read_file` to read [package.json](mdc:package.json)
+2. Use terminal to run command `git diff HEAD | cat` to obtain the diff and list the changed files. If you recieived empty result, run the same command once more.
+3. Use `read_file` to open each changed file.  
+4. Use `read_file` to read  [rules-attach.mdc](mdc:.cursor/rules/rules-attach.mdc). Even if you think it's unnecessary, you must read it.
+5. combine changed files, step3 and `agent_requestable_workspace_rules`, list the rules which need to read 
+6. Use `read_file` to read the rules list in step 5
+
+## Review
+
+### Code Style
+
+- Ensure JSDoc comments accurately reflect the implementation; update them when needed.  
+- Look for opportunities to simplify or modernize code with the latest JavaScript/TypeScript features.  
+- Prefer `async`/`await` over callbacks or chained `.then` promises.  
+- Use consistent, descriptive naming—avoid obscure abbreviations.  
+- Replace magic numbers or strings with well-named constants.  
+- Use semantically meaningful variable, function, and class names.
+- Ignore purely formatting issues and other autofixable lint problems.
+
+### Code Optimization
+
+- Prefer `for…of` loops to index-based `for` loops when feasible.  
+- Decide whether callbacks should be **debounced** or **throttled**.  
+- Use components from `@lobehub/ui`, Ant Design, or the existing design system instead of raw HTML tags (e.g., `Button` vs. `button`).  
+- reuse npm packages already installed (e.g., `lodash/omit`) rather than reinventing the wheel.  
+- Design for dark mode and mobile responsiveness:  
+  - Use the `antd-style` token system instead of hard-coded colors.  
+  - Select the proper component variants.  
+- Performance considerations:  
+  - Where safe, convert sequential async flows to concurrent ones with `Promise.all`, `Promise.race`, etc.  
+  - Query only the required columns from a database rather than selecting entire rows.
+
+### Obvious Bugs
+
+- Do not silently swallow errors in `catch` blocks; at minimum, log them.  
+- Revert temporary code used only for testing (e.g., debug logs, temporary configs).  
+- Remove empty handlers (e.g., an empty `onClick`).  
+- Confirm the UI degrades gracefully for unauthenticated users.
+
+## After the Review: output
+
+1. Summary
+    - Start with a brief explanation of what the change set does.  
+    - Summarize the changes for each modified file (or logical group).
+2. Comments Issues
+    - List the most critical issues first.  
+    - Use an ordered list, which will be convenient for me to reference later.
+    - For each issue:
+      - Mark severity tag (`❌ Must fix`, `⚠️ Should fix`, `💅 Nitpick`)  
+      - Provode file path to the relevant file.
+      - Provide recommended fix  
+    - End with a **git commit** command, instruct the author to run it.  
+      - We use gitmoji to label commit messages, format: [emoji] <type>(<scope>): <subject>

package/.cursor/rules/cursor-rules.mdc

@@ -0,0 +1,28 @@
+---
+description: cursor rules writing and optimization guide
+globs: 
+alwaysApply: false
+---
+当你编写或修改 Cursor Rule 时，请遵循以下准则：
+
+- 当你知道 rule 的文件名时，使用 `read_file` 而不是 `fetch_rules` 去读取它们，它们都在项目根目录的 `.cursor/rules/` 文件夹下
+
+- 代码示例
+  - 示例应尽量精简，仅保留演示核心
+  - 删除与示例无关的导入/导出语句，但保留必要的导入
+  - 同一文件存在多个示例时，若前文已演示模块导入，后续示例可省略重复导入
+  - 无需书写 `export`
+  - 可省略与演示无关或重复的 props、配置对象属性、try/catch、CSS 等代码
+  - 删除无关注释，保留有助理解的注释
+
+- 格式
+  - 修改前请先确认原始文档语言，并保持一致
+  - 无序列表统一使用 `-`
+  - 列表末尾的句号是多余的
+  - 非必要不使用加粗、行内代码等样式，Rule 主要供 LLM 阅读
+  - 避免中英文逐句对照。若括号内容为示例而非翻译，可保留
+
+- Review
+  - 修正 Markdown 语法问题
+  - 纠正错别字
+  - 指出示例与说明不一致之处

package/.cursor/rules/cursor-ux.mdc

@@ -0,0 +1,94 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Guide to Optimize Output(Response) Rendering
+
+## File Path and Code Symbol Rendering
+
+- When rendering file paths, use backtick wrapping instead of markdown links so they can be parsed as clickable links in Cursor IDE.
+
+    - Good: `src/components/Button.tsx`
+    - Bad: [src/components/Button.tsx](mdc:src/components/Button.tsx)
+
+- When rendering functions, variables, or other code symbols, use backtick wrapping so they can be parsed as navigable links in Cursor IDE
+    - Good: The `useState` hook in `MyComponent`
+    - Bad: The useState hook in MyComponent
+     
+## Markdown Render
+
+- don't use br tag to wrap in table cell
+
+## Terminal Command Output
+
+- If terminal commands don't produce output, it's likely due to paging issues. Try piping the command to `cat` to ensure full output is displayed.
+    - Good: `git show commit_hash -- file.txt | cat`
+    - Good: `git log --oneline | cat`
+    - Reason: Some git commands use pagers by default, which may prevent output from being captured properly
+
+## Mermaid Diagram Generation: Strict Syntax Validation Checklist
+
+Before producing any Mermaid diagram, you **must** compare your final code line-by-line against every rule in the following checklist to ensure 100% compliance. **This is a hard requirement and takes precedence over other stylistic suggestions.** Please follow these action steps:
+
+1.  Plan the Mermaid diagram logic in your mind.
+2.  Write the Mermaid code.
+3.  **Carefully review your code line-by-line against the entire checklist below.**
+4.  Fix any aspect of your code that doesn't comply.
+5.  Use the `validateMermaid` tool to check your code for syntax errors. Only proceed if validation passes.
+6.  Output the final, compliant, and copy-ready Mermaid code block.
+7.  Immediately after the Mermaid code block, output:  
+    I have checked that the Mermaid syntax fully complies with the validation checklist.
+
+---
+
+### Checklist Details
+
+#### Rule 1: Edge Labels – Must Be Plain Text Only  
+> **Essence:** Anything inside `|...|` must contain pure, unformatted text. Absolutely NO Markdown, list markers, or parentheses/brackets allowed—these often cause rendering failures.
+
+-   **✅ Do:** `A -->|Process plain text data| B`
+-   **❌ Don't:** `A -->|1. Ordered list item| B`    (No numbered lists)
+-   **❌ Don't:** `CC --"1. fetch('/api/...')"--> API`   (No square brackets)
+-   **❌ Don't:** `A -->|- Unordered list item| B`   (No hyphen lists)
+-   **❌ Don't:** `A -->|Transform (important)| B`   (No parentheses)
+-   **❌ Don't:** `A -->|Transform [important]| B`   (No square brackets)
+
+#### Rule 2: Node Definition – Handle Special Characters with Care  
+> **Essence:** When node text or subgraph titles contain special characters like `()` or `[]`, wrap the text in quotes to avoid conflicts with Mermaid shape syntax.
+
+-   **When your node text includes parentheses (e.g., 'React (JSX)'):**
+    -   **✅ Do:** `I_REACT["<b>React component (JSX)</b>"]` (Quotes wrap all text)
+    -   **❌ Don't:** `I_REACT(<b>React component (JSX)</b>)` (Wrong, Mermaid parses this as a shape)
+    -   **❌ Don't:** `subgraph Plugin Features (Plugins)` (Wrong, subgraph titles with parentheses must also be wrapped in quotes)
+
+#### Rule 3: Double Quotes in Text – Must Be Escaped  
+> **Essence:** Use `&quot;` for double quotes **inside node text**.
+
+-   **✅ Do:** `A[This node contains &quot;quotes&quot;]`
+-   **❌ Don't:** `A[This node contains "quotes"]`
+
+#### Rule 4: All Formatting Must Use HTML Tags (NOT Markdown!)  
+> **Essence:** For newlines, bold, and other text formatting in nodes, use HTML tags only. Markdown is not supported.
+
+-   **✅ Do (robust):** `A["<b>Bold</b> and <code>code</code><br>This is a new line"]`
+-   **❌ Don't (not rendered):** `C["# This is a heading"]`
+-   **❌ Don't (not rendered):** ``C["`const` means constant"]``
+-   **⚠️ Warning (unreliable):** `B["Markdown **bold** might sometimes work but DON'T rely on it"]`
+
+#### Rule 5: No HTML Tags for Participants and Message Labels (Sequence Diagrams)  
+> **Important Addition:**  
+> In Mermaid sequence diagrams, you MUST NOT use any HTML tags (such as `<b>`, `<code>`, etc.) in:
+> - `participant` display names (`as` part)
+> - Message labels (the text after `:` in diagram flows)
+>
+> These tags are generally not rendered—they may appear as-is or cause compatibility issues.
+
+-   **✅ Do:** `participant A as Client`
+-   **❌ Don't:** `participant A as <b>Client</b>`
+-   **✅ Do:** `A->>B: 1. Establish connection`
+-   **❌ Don't:** `A->>B: 1. <code>Establish connection</code>`
+
+---
+
+**Validate each Mermaid code block by running it through the `validateMermaid` tool before delivering your output!**

package/.cursor/rules/debug.mdc

@@ -0,0 +1,193 @@
+---
+description: Debug 调试指南
+globs: 
+alwaysApply: false
+---
+# Debug 调试指南
+
+## 💡 调试流程概览
+
+当遇到问题时，请按照以下优先级进行处理：
+
+1. **快速判断** - 对于熟悉的错误，直接提供解决方案
+2. **信息收集** - 使用工具搜索相关代码和配置
+3. **网络搜索** - 查找现有解决方案
+4. **定位调试** - 添加日志进行问题定位
+5. **临时方案** - 如果找不到根本解决方案，提供临时解决方案
+6. **解决实施** - 提供可维护的最终解决方案
+
+## 🔍 错误信息分析
+
+### 错误来源识别
+
+错误信息可能来自：
+
+- **Terminal 输出** - 构建、运行时错误
+- **浏览器控制台** - 前端 JavaScript 错误
+- **开发工具** - ESLint、TypeScript、测试框架等
+- **服务器日志** - API、数据库连接等后端错误
+- **截图或文本** - 用户直接提供的错误信息
+
+## 🛠️ 信息收集工具
+
+### 代码搜索工具
+
+使用以下工具收集相关信息，并根据场景选择最合适的工具：
+
+- **`codebase_search` (语义搜索)**
+    - **何时使用**: 当你不确定具体的代码实现，想要寻找相关概念、功能或逻辑时。
+    - **示例**: `查询"文件上传"功能的实现`
+- **`grep_search` (精确/正则搜索)**
+    - **何时使用**: 当你知道要查找的确切字符串、函数名、变量名或一个特定的模式时。
+    - **示例**: `查找所有使用了 'useState' 的地方`
+- **`file_search` (文件搜索)**
+    - **何时使用**: 当你知道文件名的一部分，需要快速定位文件时。
+    - **示例**: `查找 'Button.tsx' 组件`
+- **`read_file` (内容读取)**
+    - **何时使用**: 在定位到具体文件后，用于查看其完整内容和上下文。
+- **`web_search` (网络搜索)**
+    - **何时使用**: 当错误信息可能与第三方库、API 或常见问题相关时，用于获取外部信息。
+
+### 环境与依赖检查
+
+- **检查 `package.json`**: 查看 `scripts` 了解项目如何运行、构建和测试。查看 `dependencies` 和 `devDependencies` 确认库版本，版本冲突有时是问题的根源。
+- **运行测试**: 使用 `ni vitest` 运行单元测试和集成测试，这可以快速定位功能回归或组件错误。
+
+### 项目特定搜索目标
+
+针对 lobe-chat 项目，重点关注：
+
+- **配置文件**: [package.json](mdc:package.json), [next.config.mjs](mdc:next.config.mjs)
+- **核心功能**: `src/features/` 下的相关模块
+- **状态管理**: `src/store/` 下的 Zustand stores
+- **数据库**: `src/database/` 和 `src/migrations/`
+- **类型定义**: `src/types/` 下的类型文件
+- **服务层**: `src/services/` 下的 API 服务
+- **启动流程**: [apps/desktop/src/main/core/App.ts](mdc:apps/desktop/src/main/core/App.ts) - 了解应用启动流程
+
+## 🌐 网络搜索策略
+
+### 搜索顺序优先级
+
+1. **和问题相关的项目的 github issue**
+
+2. **技术社区**
+    - Stack Overflow
+    - GitHub Discussions
+    - Reddit
+
+3. **官方文档**
+    - 使用 `mcp_context7_resolve-library-id` 和 `mcp_context7_get-library-docs` 工具
+    - 查阅官方文档网站
+
+### 搜索关键词策略
+
+- **错误信息**: 完整的错误消息
+- **技术栈**: "Next.js 15" + "error message"
+- **上下文**: 添加功能相关的关键词
+
+## 🔧 问题定位与结构化思考
+
+如果问题比较复杂，我们要按照先定位问题，再解决问题的大方向进行。
+
+### 结构化思考工具
+
+对于复杂或多步骤的调试任务，使用 `mcp_sequential-thinking_sequentialthinking` 工具来结构化思考过程。这有助于：
+
+- **分解问题**: 将大问题拆解成可管理的小步骤。
+- **清晰追踪**: 记录每一步的发现和决策，避免遗漏。
+- **自我修正**: 在过程中评估和调整调试路径。
+
+### 日志调试
+
+在问题产生的路径上添加日志，可以简单使用 `console.log` 或者参考 [debug-usage.mdc](mdc:.cursor/rules/debug-usage.mdc) 使用 `debug` 模块。添加完日志后，请求我运行相关的代码并提供关键输出和错误信息。
+
+### 引导式交互调试
+
+虽然我无法直接操作浏览器开发者工具，但我可以引导你进行交互式调试：
+
+1.  **设置断点**: 我会告诉你可以在哪些关键代码行设置断点。
+2.  **检查变量**: 我会请你在断点处检查特定变量的值或 `props`/`state`。
+3.  **分析调用栈**: 我会请你提供调用栈信息，以帮助理解代码执行流程。
+
+## 💡 临时解决方案策略
+
+当无法找到根本解决方案时，提供临时解决方案：
+
+### 临时方案准则
+
+- **快速修复** - 优先让功能可用
+- **最小修改** - 减少对现有代码的影响
+- **清晰标记** - 明确标注这是临时方案
+- **后续计划** - 说明后续如何找到更好的解决方案
+
+### 临时方案模板
+
+```markdown
+## 临时解决方案 ⚠️
+
+**问题**: [简要描述问题]
+
+**临时修复**:
+[具体的临时修复步骤]
+
+**风险说明**:
+
+- [可能的副作用或限制]
+- [需要注意的事项]
+
+**后续计划**:
+
+- [ ] 深入调研根本原因
+- [ ] 寻找更优雅的解决方案
+- [ ] 监控是否有其他影响
+```
+
+## ✅ 解决方案准则
+
+### 方案质量标准
+
+提供的解决方案应该：
+
+- **✅ 低侵入性** - 最小化对现有代码的修改
+- **✅ 可维护性** - 易于理解和后续维护
+- **✅ 类型安全** - 符合 TypeScript 规范
+- **✅ 最佳实践** - 遵循项目的编码规范
+- **✅ 测试友好** - 便于编写和运行测试
+- **❌ 避免长期 Hack** - 临时方案可以 hack，但要明确标注
+
+### 解决方案模板
+
+```markdown
+## 问题原因
+
+[简要说明问题产生的根本原因]
+
+## 解决方案
+
+[详细的解决步骤]
+
+## 代码修改
+
+[具体的代码变更]
+
+## 验证方法
+
+[如何验证问题已解决]
+
+## 预防措施
+
+[如何避免类似问题再次发生]
+```
+
+## 🔄 迭代调试流程
+
+如果初次解决方案无效：
+
+1.  **重新收集信息** - 基于新的错误信息搜索
+2.  **深入代码分析** - 查看更多相关代码文件
+3.  **运行相关测试** - 编写或运行一个失败的测试来稳定复现问题。
+4.  **扩大搜索范围** - 搜索更广泛的相关问题
+5.  **请求更多日志** - 添加更详细的调试信息
+6.  **提供临时方案** - 如果根本解决方案复杂，先提供临时修复
+7.  **分解问题** - 将复杂问题拆解为更小的子问题