diff --git a/.github/ISSUE_TEMPLATE/bug_report_en.yaml b/.github/ISSUE_TEMPLATE/bug_report_en.yaml
index 043ef521c..7b62702d6 100644
--- a/.github/ISSUE_TEMPLATE/bug_report_en.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report_en.yaml
@@ -14,7 +14,9 @@ body:
     attributes:
       label: "Problem Description"
       description: "What problem occurred? What is the expected normal behavior?"
-      placeholder: "e.g., When clicking the download button on YouTube page, the script throws a 404 error, expected to show a download window"
+      placeholder:
+        "e.g., When clicking the download button on YouTube page, the script throws a 404 error, expected to show a
+        download window"
     validations:
       required: true
 
@@ -37,7 +39,9 @@ body:
     id: scriptcat-version
     attributes:
       label: ScriptCat Version
-      description: You can view it by clicking on the ScriptCat popup window. If possible, please use the latest version as your issue may have already been resolved
+      description:
+        You can view it by clicking on the ScriptCat popup window. If possible, please use the latest version as your
+        issue may have already been resolved
       placeholder: e.g., v0.17.0
     validations:
       required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request_en.md b/.github/ISSUE_TEMPLATE/feature_request_en.md
index 995a35b67..d5194e850 100644
--- a/.github/ISSUE_TEMPLATE/feature_request_en.md
+++ b/.github/ISSUE_TEMPLATE/feature_request_en.md
@@ -12,7 +12,8 @@ Please clearly describe the feature you want:
 
 ### Use Case
 
-In what situations is this feature needed? (e.g., when processing specific websites, improving operational efficiency, etc.)
+In what situations is this feature needed? (e.g., when processing specific websites, improving operational efficiency,
+etc.)
 
 ### Additional Information
 
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 1bebf61b1..69901b700 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -9,22 +9,28 @@ When performing a code review, respond in Chinese.
 ScriptCat is a sophisticated browser extension that executes user scripts with a unique multi-process architecture:
 
 ### Core Components
-- **Service Worker** (`src/service_worker.ts`) - Main background process handling script management, installations, and chrome APIs
+
+- **Service Worker** (`src/service_worker.ts`) - Main background process handling script management, installations, and
+  chrome APIs
 - **Offscreen** (`src/offscreen.ts`) - Isolated background environment for running background/scheduled scripts
 - **Sandbox** (`src/sandbox.ts`) - Secure execution environment inside offscreen for script isolation
 - **Content Scripts** (`src/content.ts`) - Injected into web pages to execute user scripts
 - **Inject Scripts** (`src/inject.ts`) - Runs in page context with access to page globals
 
 ### Message Passing System
+
 ScriptCat uses a sophisticated message passing architecture (`packages/message/`):
+
 - **ExtensionMessage** - Chrome extension runtime messages between service worker/content/pages
 - **WindowMessage** - PostMessage-based communication between offscreen/sandbox
 - **CustomEventMessage** - CustomEvent-based communication between content/inject scripts
 - **MessageQueue** - Cross-environment event broadcasting system
 
-Key pattern: All communication flows through Service Worker → Offscreen → Sandbox for background scripts, or Service Worker → Content → Inject for page scripts.
+Key pattern: All communication flows through Service Worker → Offscreen → Sandbox for background scripts, or Service
+Worker → Content → Inject for page scripts.
 
 ### Script Execution Flow
+
 1. **Page Scripts**: Service Worker registers with `chrome.userScripts` → injected into pages
 2. **Background Scripts**: Service Worker → Offscreen → Sandbox execution
 3. **Scheduled Scripts**: Cron-based execution in Sandbox environment
@@ -32,6 +38,7 @@ Key pattern: All communication flows through Service Worker → Offscreen → Sa
 ## Key Development Patterns
 
 ### Path Aliases
+
 ```typescript
 "@App": "./src/"
 "@Packages": "./packages/"
@@ -39,24 +46,30 @@ Key pattern: All communication flows through Service Worker → Offscreen → Sa
 ```
 
 ### Repository Pattern
+
 All data access uses DAO classes extending `Repo<T>` base class:
+
 ```typescript
 // Example: ScriptDAO, ResourceDAO, SubscribeDAO
 export class ScriptDAO extends Repo<Script> {
-  public save(val: Script) { return super._save(val.uuid, val); }
+  public save(val: Script) {
+    return super._save(val.uuid, val);
+  }
 }
 ```
 
 ### Service Layer Structure
+
 Services follow a consistent pattern with dependency injection:
+
 ```typescript
 export class ExampleService {
   constructor(
-    private group: Group,           // Message handling group
-    private messageQueue: IMessageQueue,  // Event broadcasting (MessageQueue's interface)
-    private dataDAO: DataDAO        // Data access
+    private group: Group, // Message handling group
+    private messageQueue: IMessageQueue, // Event broadcasting (MessageQueue's interface)
+    private dataDAO: DataDAO // Data access
   ) {}
-  
+
   init() {
     this.group.on("action", this.handleAction.bind(this));
   }
@@ -64,7 +77,9 @@ export class ExampleService {
 ```
 
 ### Script Compilation & Sandboxing
+
 User scripts are compiled with sandbox context isolation:
+
 - `compileScriptCode()` - Wraps scripts with error handling and context binding
 - `compileInjectScript()` - Creates window-mounted functions for inject scripts
 - Sandbox uses `with(arguments[0])` for controlled variable access
@@ -77,10 +92,10 @@ User scripts are compiled with sandbox context isolation:
 - **Rspack** - Fast bundler (Webpack alternative) with SWC
 - **TypeScript** - Type-safe development
 
-
 ## Development Workflows
 
 ### Build & Development
+
 ```bash
 pnpm run dev           # Development with source maps
 pnpm run dev:noMap     # Development without source maps (needed for incognito)
@@ -89,44 +104,51 @@ pnpm run pack          # Create browser extension packages
 ```
 
 ### Testing
+
 ```bash
 pnpm test              # Run all tests with Vitest
 pnpm run coverage      # Generate coverage reports
 ```
 
 **Testing Patterns:**
+
 - Uses Vitest with jsdom environment
 - Chrome extension APIs mocked via `@Packages/chrome-extension-mock`
 - Message system testing with `MockMessage` classes
 - Sandbox testing validates script isolation
 
 ### Code Organization
+
 - **Monorepo structure** with packages in `packages/` (message, filesystem, etc.)
 - **Feature-based organization** in `src/app/service/` by environment
 - **Shared utilities** in `src/pkg/` for cross-cutting concerns
 - **Type definitions** in `src/types/` with global declarations
 
 ### Browser Extension Specifics
+
 - **Manifest V3** with service worker background
 - **User Scripts API** for script injection (Chrome/Edge)
-- **Offscreen API** for DOM access in background contexts  
+- **Offscreen API** for DOM access in background contexts
 - **Declarative Net Request** for script installation interception
 
 ## Critical Integration Points
 
 ### Script Installation Flow
+
 1. URL patterns trigger declarative net request rules
 2. Service Worker opens install page with cached script data
 3. Install page validates and processes script metadata
 4. Scripts registered with appropriate execution environment
 
 ### GM API Implementation
+
 - Split between Service Worker (`GMApi`) and Offscreen (`OffscreenGMApi`)
 - Permission verification via `PermissionVerify` service
 - Value storage abstracted through `ValueService`
 - Cross-origin requests handled in service worker context
 
 ### Resource Management
+
 - `ResourceService` handles script dependencies (@require, @resource)
 - Content Security Policy handling for external resources
 - Caching layer via `Cache` class with automatic expiration
@@ -139,33 +161,42 @@ pnpm run coverage      # Generate coverage reports
 - Sandbox script execution isolated from page context - use `unsafeWindow` for page access
 
 ## File Structure Patterns
+
 - Tests co-located with source files (`.test.ts` suffix)
 - Template files use `.tpl` extension for build-time processing
 - Configuration files use factory pattern for environment-specific setup
 
 ## Language
+
 - The code is developed and maintained by developers based in Mainland China.
 - Comments should preferably be written in Simplified Chinese.
 - The user interface supports multiple languages, with English set as the default for global users.
 
 ## PR Review Policy
 
-When performing Pull Request (PR) reviews, Copilot must always conduct a **comprehensive and independent review** of the entire PR content.
+When performing Pull Request (PR) reviews, Copilot must always conduct a **comprehensive and independent review** of the
+entire PR content.
 
 - **Full Review Every Time**  
-  Always review **all modified files** in every PR, regardless of previous reviews or user comments. Even during re-reviews, treat the PR as new and **do not rely on prior review states**.
+  Always review **all modified files** in every PR, regardless of previous reviews or user comments. Even during
+  re-reviews, treat the PR as new and **do not rely on prior review states**.
 
 - **No Skipping of Files**  
-  Do not skip or ignore any text-based file types (including `.md`, `.json`, `.yml`, `.toml`, `.ts`, `.js`, `.py`, `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.). Every file that is changed must be fully examined.
+  Do not skip or ignore any text-based file types (including `.md`, `.json`, `.yml`, `.toml`, `.ts`, `.js`, `.py`,
+  `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.). Every file that is changed must be fully examined.
 
 - **Reference as Context Only**  
-  PR descriptions, commit messages, or user discussions serve only as **reference context**. The review must focus primarily on the **actual code and file changes**.
+  PR descriptions, commit messages, or user discussions serve only as **reference context**. The review must focus
+  primarily on the **actual code and file changes**.
 
 - **Infer Intent from Code Changes**  
-  Always attempt to **infer the purpose and intent** of the changes directly from the modified content, rather than relying solely on user statements or PR titles.
+  Always attempt to **infer the purpose and intent** of the changes directly from the modified content, rather than
+  relying solely on user statements or PR titles.
 
 - **Critical Thinking Requirement**  
-  For each change, Copilot should assess correctness, consistency, and maintainability — ensuring that logic, style, and architectural impact align with project standards.
+  For each change, Copilot should assess correctness, consistency, and maintainability — ensuring that logic, style, and
+  architectural impact align with project standards.
 
 - **Independent Verification**  
-  Do not assume unchanged files or previously reviewed sections are safe; verify all code paths potentially affected by the modifications.
+  Do not assume unchanged files or previously reviewed sections are safe; verify all code paths potentially affected by
+  the modifications.
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index 3b0577d66..93d73a104 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -5,6 +5,7 @@ on:
     branches:
       - main
       - release/*
+      - feature/*
       - dev
     paths-ignore:
       - ".github/**"
@@ -25,7 +26,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+          cache: "pnpm"
 
       - name: Package with Node
         env:
@@ -51,4 +52,3 @@ jobs:
           name: scriptcat-chrome-extension
           path: |
             dist/ext/*
-
diff --git a/.github/workflows/packageRelease.yml b/.github/workflows/packageRelease.yml
index ad4631724..878d62325 100644
--- a/.github/workflows/packageRelease.yml
+++ b/.github/workflows/packageRelease.yml
@@ -18,7 +18,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+          cache: "pnpm"
 
       - name: Package with Node
         env:
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
index e224d9d78..a5b8ae4a7 100644
--- a/.github/workflows/test.yaml
+++ b/.github/workflows/test.yaml
@@ -5,6 +5,7 @@ on:
     branches:
       - main
       - release/*
+      - feature/*
       - dev
       - develop/*
   pull_request:
@@ -21,7 +22,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+          cache: "pnpm"
 
       - name: Setup pnpm
         run: corepack enable
@@ -61,7 +62,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: 'pnpm'
+          cache: "pnpm"
 
       - name: Setup pnpm
         run: corepack enable
diff --git a/.husky/pre-commit b/.husky/pre-commit
new file mode 100644
index 000000000..fd92f4e77
--- /dev/null
+++ b/.husky/pre-commit
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+pnpm run lint-fix
\ No newline at end of file
diff --git a/.husky/pre-push b/.husky/pre-push
new file mode 100644
index 000000000..12257e946
--- /dev/null
+++ b/.husky/pre-push
@@ -0,0 +1,35 @@
+#!/bin/sh
+
+# Skip checks: SKIP_PRE_PUSH=1 git push or git push --no-verify
+if [ "$SKIP_PRE_PUSH" = "1" ]; then
+  echo "⏭ SKIP_PRE_PUSH=1, skipping pre-push checks"
+  exit 0
+fi
+
+# Only run checks when pushing to main or release/* branches
+remote="$1"
+need_check=0
+
+while read local_ref local_sha remote_ref remote_sha; do
+  branch=$(echo "$remote_ref" | sed 's|refs/heads/||')
+
+  if [ "$branch" = "main" ] || echo "$branch" | grep -q "^release/"; then
+    need_check=1
+    echo "🔍 Detected push target: $branch"
+  fi
+done
+
+if [ "$need_check" = "0" ]; then
+  exit 0
+fi
+
+echo ""
+echo "▶ Running lint..."
+pnpm run lint || exit 1
+
+echo ""
+echo "▶ Running tests..."
+pnpm run test:ci || exit 1
+
+echo ""
+echo "✅ All checks passed! (build and e2e tests will run in CI)"
diff --git a/.prettierrc b/.prettierrc
index bcded0e80..74213a963 100644
--- a/.prettierrc
+++ b/.prettierrc
@@ -16,4 +16,4 @@
   "trailingComma": "es5",
   "useTabs": false,
   "endOfLine": "auto"
-}
\ No newline at end of file
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 869c389b5..405413bb4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,13 +46,11 @@ git commit -m "✨ add login feature"
 ### 工作流概述
 
 `main` 分支是 ScriptCat 的主分支。为了保持代码的完整性，请不要直接修改 `main`
-分支。你应该创建一个新的分支，并在这个分支上进行修改，然后发起一个目标分支为
-`main` 的 Pull Request。Pull Request
-的标题请尽量使用中文，以便于自动生成更新日志。
+分支。你应该创建一个新的分支，并在这个分支上进行修改，然后发起一个目标分支为 `main` 的 Pull Request。Pull
+Request 的标题请尽量使用中文，以便于自动生成更新日志。
 
-如果你不是 ScriptCat 团队的成员，你可以先 fork 本仓库，然后向本仓库的 `main`
-分支发起 Pull Request。在创建 commit 时，请按照上述 commit message
-规范进行。我们将在 code review 完成后将你的贡献合并到主分支。
+如果你不是 ScriptCat 团队的成员，你可以先 fork 本仓库，然后向本仓库的 `main` 分支发起 Pull
+Request。在创建 commit 时，请按照上述 commit message 规范进行。我们将在 code review 完成后将你的贡献合并到主分支。
 
 ## 撰写文档
 
diff --git a/README.md b/README.md
index 773b76a29..8870b3d5c 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ smooth.
 
 | Browser | Store Link                                                                                                                                                                                                                       | Status       |
 | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
-| Chrome  | [Stable Version](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta Version](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom)                  | ✅ Available |
+| Chrome  | [Stable Version](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta Version](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom)                   | ✅ Available |
 | Edge    | [Stable Version](https://microsoftedge.microsoft.com/addons/detail/scriptcat/liilgpjgabokdklappibcjfablkpcekh) [Beta Version](https://microsoftedge.microsoft.com/addons/detail/scriptcat-beta/nimmbghgpcjmeniofmpdfkofcedcjpfi) | ✅ Available |
 | Firefox | [Stable Version](https://addons.mozilla.org/en/firefox/addon/scriptcat/) [Beta Version](https://addons.mozilla.org/en/firefox/addon/scriptcat-pre/)                                                                              | ✅ MV2       |
 
diff --git a/README_RU.md b/README_RU.md
index cb21e0f00..37118ec53 100644
--- a/README_RU.md
+++ b/README_RU.md
@@ -69,11 +69,11 @@ ScriptCat — это мощный менеджер пользовательск
 
 #### Магазины расширений (рекомендуется)
 
-| Браузер | Ссылка на магазин | Статус |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
-| Chrome  | [Стабильная версия](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) / [Beta](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom) | ✅ Доступно |
+| Браузер | Ссылка на магазин                                                                                                                                                                                                             | Статус      |
+| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| Chrome  | [Стабильная версия](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) / [Beta](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom)                   | ✅ Доступно |
 | Edge    | [Стабильная версия](https://microsoftedge.microsoft.com/addons/detail/scriptcat/liilgpjgabokdklappibcjfablkpcekh) / [Beta](https://microsoftedge.microsoft.com/addons/detail/scriptcat-beta/nimmbghgpcjmeniofmpdfkofcedcjpfi) | ✅ Доступно |
-| Firefox | [Стабильная версия](https://addons.mozilla.org/firefox/addon/scriptcat/) / [Beta](https://addons.mozilla.org/firefox/addon/scriptcat-pre/) | ✅ MV2 |
+| Firefox | [Стабильная версия](https://addons.mozilla.org/firefox/addon/scriptcat/) / [Beta](https://addons.mozilla.org/firefox/addon/scriptcat-pre/)                                                                                    | ✅ MV2      |
 
 #### Ручная установка
 
diff --git a/README_ja.md b/README_ja.md
index 467b42fe2..11d37a863 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -65,11 +65,11 @@ ScriptCat は、Tampermonkey の設計思想に基づく強力なユーザース
 
 #### 拡張ストア（推奨）
 
-| ブラウザ | ストアリンク | ステータス |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Chrome   | [安定版](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta 版](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom) | ✅ 利用可能 |
+| ブラウザ | ストアリンク                                                                                                                                                                                                        | ステータス  |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| Chrome   | [安定版](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta 版](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom)                   | ✅ 利用可能 |
 | Edge     | [安定版](https://microsoftedge.microsoft.com/addons/detail/scriptcat/liilgpjgabokdklappibcjfablkpcekh) [Beta 版](https://microsoftedge.microsoft.com/addons/detail/scriptcat-beta/nimmbghgpcjmeniofmpdfkofcedcjpfi) | ✅ 利用可能 |
-| Firefox  | [安定版](https://addons.mozilla.org/ja/firefox/addon/scriptcat/) [Beta 版](https://addons.mozilla.org/ja/firefox/addon/scriptcat-pre/) | ✅ MV2 |
+| Firefox  | [安定版](https://addons.mozilla.org/ja/firefox/addon/scriptcat/) [Beta 版](https://addons.mozilla.org/ja/firefox/addon/scriptcat-pre/)                                                                              | ✅ MV2      |
 
 #### 手動インストール
 
@@ -80,8 +80,10 @@ ScriptCat は、Tampermonkey の設計思想に基づく強力なユーザース
 
 #### スクリプトのインストール
 
-1. **スクリプトセンターから取得**： [ScriptCat スクリプトセンター](https://scriptcat.org/ja/search) またはその他のユーザースクリプトセンターへアクセス
-2. **バックグラウンドスクリプトセンター**：ユニークな [バックグラウンドスクリプト](https://scriptcat.org/ja/search?script_type=3) を体験
+1. **スクリプトセンターから取得**： [ScriptCat スクリプトセンター](https://scriptcat.org/ja/search)
+   またはその他のユーザースクリプトセンターへアクセス
+2. **バックグラウンドスクリプトセンター**：ユニークな
+   [バックグラウンドスクリプト](https://scriptcat.org/ja/search?script_type=3) を体験
 3. **互換性**：多くの Tampermonkey スクリプトをサポートしており、そのままインストール可能。不具合があれば  
    [issues](https://github.com/scriptscat/scriptcat/issues) にてご報告ください。
 
diff --git a/README_zh-CN.md b/README_zh-CN.md
index f37c45328..15501c3c2 100644
--- a/README_zh-CN.md
+++ b/README_zh-CN.md
@@ -63,11 +63,11 @@ ScriptCat（脚本猫）是一个功能强大的用户脚本管理器，基于
 
 #### 扩展商店（推荐）
 
-| 浏览器 | 商店链接 | 状态 |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| Chrome  | [正式版本](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta版本](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom) | ✅ 可用 |
+| 浏览器  | 商店链接                                                                                                                                                                                                               | 状态    |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Chrome  | [正式版本](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta版本](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom)                   | ✅ 可用 |
 | Edge    | [正式版本](https://microsoftedge.microsoft.com/addons/detail/scriptcat/liilgpjgabokdklappibcjfablkpcekh) [Beta版本](https://microsoftedge.microsoft.com/addons/detail/scriptcat-beta/nimmbghgpcjmeniofmpdfkofcedcjpfi) | ✅ 可用 |
-| Firefox | [正式版本](https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat/) [Beta版本](https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat-pre/) | ✅ MV2 |
+| Firefox | [正式版本](https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat/) [Beta版本](https://addons.mozilla.org/zh-CN/firefox/addon/scriptcat-pre/)                                                                        | ✅ MV2  |
 
 #### 手动安装
 
diff --git a/README_zh-TW.md b/README_zh-TW.md
index 5f8bb3138..eb722bd7d 100644
--- a/README_zh-TW.md
+++ b/README_zh-TW.md
@@ -65,11 +65,11 @@ ScriptCat 是一款基於 Tampermonkey 設計理念的強大使用者腳本管
 
 #### 擴充商店（推薦）
 
-| 瀏覽器 | 商店連結 | 狀態 |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
-| Chrome  | [正式版](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta 版](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom) | ✅ 可用 |
+| 瀏覽器  | 商店連結                                                                                                                                                                                                            | 狀態    |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Chrome  | [正式版](https://chromewebstore.google.com/detail/scriptcat/ndcooeababalnlpkfedmmbbbgkljhpjf) [Beta 版](https://chromewebstore.google.com/detail/scriptcat-beta/jaehimmlecjmebpekkipmpmbpfhdacom)                   | ✅ 可用 |
 | Edge    | [正式版](https://microsoftedge.microsoft.com/addons/detail/scriptcat/liilgpjgabokdklappibcjfablkpcekh) [Beta 版](https://microsoftedge.microsoft.com/addons/detail/scriptcat-beta/nimmbghgpcjmeniofmpdfkofcedcjpfi) | ✅ 可用 |
-| Firefox | [正式版](https://addons.mozilla.org/zh-TW/firefox/addon/scriptcat/) [Beta 版](https://addons.mozilla.org/zh-TW/firefox/addon/scriptcat-pre/) | ✅ MV2 |
+| Firefox | [正式版](https://addons.mozilla.org/zh-TW/firefox/addon/scriptcat/) [Beta 版](https://addons.mozilla.org/zh-TW/firefox/addon/scriptcat-pre/)                                                                        | ✅ MV2  |
 
 #### 手動安裝
 
diff --git a/SECURITY.md b/SECURITY.md
index 034e84803..88f067a77 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,8 +2,8 @@
 
 ## Supported Versions
 
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
+Use this section to tell people about which versions of your project are currently being supported with security
+updates.
 
 | Version | Supported          |
 | ------- | ------------------ |
@@ -16,6 +16,5 @@ currently being supported with security updates.
 
 Use this section to tell people how to report a vulnerability.
 
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.
+Tell them where to go, how often they can expect to get an update on a reported vulnerability, what to expect if the
+vulnerability is accepted or declined, etc.
diff --git a/docs/AI prompt.md b/docs/AI prompt.md
index 6e4cb8a2b..9e7c6a239 100644
--- a/docs/AI prompt.md	
+++ b/docs/AI prompt.md	
@@ -6,10 +6,13 @@
 
 ```md
 ### 角色
+
 你是一名专业的 TypeScript 测试工程师，精通 Vitest 测试框架和单元测试最佳实践。
 
 ### 任务
+
 请为我提供的 TypeScript 文件编写完整的单元测试套件，遵循以下规范：
+
 1. **测试框架**：使用 Vitest
 2. **文件命名**：`<原文件名>.test.ts` 格式，与原文件同级目录
 3. **测试覆盖**：
@@ -23,14 +26,12 @@
    - 添加清晰的测试描述
 
 ### 输入格式
-请严格按此格式提供被测试代码，下面请为此文件编写单元测试
 
+请严格按此格式提供被测试代码，下面请为此文件编写单元测试
 ```
 
 ## 提取翻译
 
 ```md
-
 你是一个翻译专家，使用react-i18next做为翻译框架，我需要你帮助我翻译这个React文件中的中文，首先你需要提取文件中的中文部分，生成一个合适的key，使用蛇形命名，添加到 src/locales/zh-CN/translations.json 文件中，然后使用`useTranslation`替换原有中文，如果有参数你可以使用i18next的格式，不需要处理其他语言，不要做多余的事情
-
-```
\ No newline at end of file
+```
diff --git a/docs/CONTRIBUTING_EN.md b/docs/CONTRIBUTING_EN.md
index 385f3b439..f1a40fb76 100644
--- a/docs/CONTRIBUTING_EN.md
+++ b/docs/CONTRIBUTING_EN.md
@@ -2,23 +2,29 @@
 
 # ScriptCat Contributing Guide
 
-We greatly appreciate your contributions to ScriptCat! This guide aims to help you contribute to ScriptCat in a more standardized way, so please read it carefully.
+We greatly appreciate your contributions to ScriptCat! This guide aims to help you contribute to ScriptCat in a more
+standardized way, so please read it carefully.
 
 ## Submitting Issues
 
-Before submitting an issue, we recommend that you first check the [existing Issues](https://github.com/scriptscat/scriptcat/issues) to avoid duplicate submissions.
+Before submitting an issue, we recommend that you first check the
+[existing Issues](https://github.com/scriptscat/scriptcat/issues) to avoid duplicate submissions.
 
 ### Reporting Problems, Bugs & Vulnerabilities
 
-ScriptCat is an evolving project. If you encounter problems during use and are confident that these issues are caused by ScriptCat, we welcome you to submit an Issue. When submitting, please include detailed reproduction steps and runtime environment information.
+ScriptCat is an evolving project. If you encounter problems during use and are confident that these issues are caused by
+ScriptCat, we welcome you to submit an Issue. When submitting, please include detailed reproduction steps and runtime
+environment information.
 
 ### Proposing New Features
 
-We welcome you to propose new feature suggestions in Issues. To help us better understand your needs, we recommend that you describe the feature in as much detail as possible and provide what you think might be a possible solution.
+We welcome you to propose new feature suggestions in Issues. To help us better understand your needs, we recommend that
+you describe the feature in as much detail as possible and provide what you think might be a possible solution.
 
 ## Pull Request
 
-ScriptCat uses [pnpm](https://pnpm.io/) to manage project dependencies. If you already have npm installed, the following commands can help you quickly set up the development environment:
+ScriptCat uses [pnpm](https://pnpm.io/) to manage project dependencies. If you already have npm installed, the following
+commands can help you quickly set up the development environment:
 
 ```bash
 # Install node.js dependencies
@@ -34,7 +40,8 @@ pnpm config set https-proxy https://127.0.0.1:7890
 
 ### Commit Guidelines
 
-We hope that each commit can clearly describe its purpose, and each commit should ideally contain only one modification. Our commit message format follows the [gitmoji](https://gitmoji.dev/) specification. For example:
+We hope that each commit can clearly describe its purpose, and each commit should ideally contain only one modification.
+Our commit message format follows the [gitmoji](https://gitmoji.dev/) specification. For example:
 
 ```bash
 git commit -m "✨ add login feature"
@@ -44,13 +51,20 @@ This example indicates that a new feature has been added: login functionality.
 
 ### Workflow Overview
 
-The `main` branch is ScriptCat's primary branch. To maintain code integrity, please do not directly modify the `main` branch. You should create a new branch and make modifications on this branch, then initiate a Pull Request targeting the `main` branch. Please try to use Chinese for Pull Request titles to facilitate automatic changelog generation.
+The `main` branch is ScriptCat's primary branch. To maintain code integrity, please do not directly modify the `main`
+branch. You should create a new branch and make modifications on this branch, then initiate a Pull Request targeting the
+`main` branch. Please try to use Chinese for Pull Request titles to facilitate automatic changelog generation.
 
-If you are not a member of the ScriptCat team, you can first fork this repository and then initiate a Pull Request to the `main` branch of this repository. When creating commits, please follow the commit message guidelines mentioned above. We will merge your contributions to the main branch after code review is completed.
+If you are not a member of the ScriptCat team, you can first fork this repository and then initiate a Pull Request to
+the `main` branch of this repository. When creating commits, please follow the commit message guidelines mentioned
+above. We will merge your contributions to the main branch after code review is completed.
 
 ## Writing Documentation
 
-ScriptCat's documentation is in a separate repository: [scriptcat.org](https://docs.scriptcat.org), written using [docusaurus](https://docusaurus.io/). There are some [Markdown](https://docusaurus.io/zh-CN/docs/markdown-features) features that can help you. If you need to preview the modified documentation locally, you can use the following commands to install documentation dependencies and start the dev server:
+ScriptCat's documentation is in a separate repository: [scriptcat.org](https://docs.scriptcat.org), written using
+[docusaurus](https://docusaurus.io/). There are some [Markdown](https://docusaurus.io/zh-CN/docs/markdown-features)
+features that can help you. If you need to preview the modified documentation locally, you can use the following
+commands to install documentation dependencies and start the dev server:
 
 ```bash
 pnpm install
@@ -59,7 +73,9 @@ pnpm start
 
 ### Help Us Translate
 
-[Crowdin](https://crowdin.com/project/scriptcat) is an online multilingual translation platform. If you are interested in helping us translate ScriptCat-related content, you can find the ScriptCat project on Crowdin and start translation work.
+[Crowdin](https://crowdin.com/project/scriptcat) is an online multilingual translation platform. If you are interested
+in helping us translate ScriptCat-related content, you can find the ScriptCat project on Crowdin and start translation
+work.
 
 - `src/locales` is the translation file directory for the [extension](https://github.com/scriptscat/scriptcat)
 
@@ -73,7 +89,8 @@ Visit the script site at: [https://scriptcat.org/ach-UG](https://scriptcat.org/a
 
 ## Participating in Development
 
-ScriptCat uses ESLint to standardize code style and Vitest for unit testing. You can use the following commands to run them:
+ScriptCat uses ESLint to standardize code style and Vitest for unit testing. You can use the following commands to run
+them:
 
 ```bash
 pnpm test
@@ -105,4 +122,6 @@ Before packaging, please ensure that the `scriptcat.pem` file is generated in th
 
 ## Important Notes
 
-- After running `pnpm run dev`, you need to import and load the contents of the `dist/ext` directory into the browser extension, then start editing code and save. The browser updates in real-time, but changes involving `manifest.json`, `service_worker`, `offscreen`, and `sandbox` require reloading.
+- After running `pnpm run dev`, you need to import and load the contents of the `dist/ext` directory into the browser
+  extension, then start editing code and save. The browser updates in real-time, but changes involving `manifest.json`,
+  `service_worker`, `offscreen`, and `sandbox` require reloading.
diff --git a/docs/CONTRIBUTING_RU.md b/docs/CONTRIBUTING_RU.md
index bc8a54a20..99b4c7e62 100644
--- a/docs/CONTRIBUTING_RU.md
+++ b/docs/CONTRIBUTING_RU.md
@@ -2,23 +2,29 @@
 
 # Руководство по внесению вклада в ScriptCat
 
-Мы очень благодарны за ваш вклад в развитие ScriptCat! Это руководство призвано помочь вам вносить вклад в ScriptCat более стандартизированным образом, поэтому, пожалуйста, обязательно внимательно его прочитайте.
+Мы очень благодарны за ваш вклад в развитие ScriptCat! Это руководство призвано помочь вам вносить вклад в ScriptCat
+более стандартизированным образом, поэтому, пожалуйста, обязательно внимательно его прочитайте.
 
 ## Создание Issue
 
-Перед созданием Issue мы рекомендуем сначала проверить [существующие Issues](https://github.com/scriptscat/scriptcat/issues), чтобы избежать дублирования.
+Перед созданием Issue мы рекомендуем сначала проверить
+[существующие Issues](https://github.com/scriptscat/scriptcat/issues), чтобы избежать дублирования.
 
 ### Сообщение о проблемах, сбоях и уязвимостях
 
-ScriptCat — это постоянно развивающийся проект. Если вы столкнетесь с проблемами в процессе использования и уверены, что они вызваны ScriptCat, вы можете создать Issue. При создании, приложите подробные шаги для воспроизведения и информацию о среде выполнения.
+ScriptCat — это постоянно развивающийся проект. Если вы столкнетесь с проблемами в процессе использования и уверены, что
+они вызваны ScriptCat, вы можете создать Issue. При создании, приложите подробные шаги для воспроизведения и информацию
+о среде выполнения.
 
 ### Предложение новых функций
 
-Мы приветствуем ваши предложения по новым функциям в Issues. Чтобы мы лучше поняли ваши потребности, максимально подробно опишите функцию и предложите возможные решения.
+Мы приветствуем ваши предложения по новым функциям в Issues. Чтобы мы лучше поняли ваши потребности, максимально
+подробно опишите функцию и предложите возможные решения.
 
 ## Pull Request
 
-ScriptCat использует [pnpm](https://pnpm.io/) для управления зависимостями проекта. Если у вас уже установлен npm, следующие команды помогут вам быстро настроить среду разработки:
+ScriptCat использует [pnpm](https://pnpm.io/) для управления зависимостями проекта. Если у вас уже установлен npm,
+следующие команды помогут вам быстро настроить среду разработки:
 
 ```bash
 # Установка зависимостей node.js
@@ -34,7 +40,8 @@ pnpm config set https-proxy https://127.0.0.1:7890
 
 ### Соглашение по коммитам (Commit)
 
-Мы хотим, чтобы каждый коммит четко описывал свою цель, и каждый коммит по возможности содержал только одно изменение. Наше соглашение по сообщениям коммитов следует [gitmoji](https://gitmoji.dev/). Например:
+Мы хотим, чтобы каждый коммит четко описывал свою цель, и каждый коммит по возможности содержал только одно изменение.
+Наше соглашение по сообщениям коммитов следует [gitmoji](https://gitmoji.dev/). Например:
 
 ```bash
 git commit -m "✨ add login feature"
@@ -46,17 +53,20 @@ git commit -m "✨ add login feature"
 
 Ветка `main` является основной веткой ScriptCat. Для сохранения целостности кода, не изменяйте напрямую ветку `main`.
 Вам следует создать новую ветку, внести изменения в этой ветке, а затем создать Pull Request с целевой веткой `main`.
-Заголовок Pull Request, по возможности пишите на китайском языке для удобства автоматического создания журнала изменений.
+Заголовок Pull Request, по возможности пишите на китайском языке для удобства автоматического создания журнала
+изменений.
 
-Если вы не являетесь участником команды ScriptCat, вы можете сначала сделать fork этого репозитория, а затем создать Pull Request
-в ветку `main` этого репозитория. При создании коммитов, следуйте указанному выше соглашению по сообщениям коммитов.
-Мы объединим ваш вклад в `main` ветку после проведения code review.
+Если вы не являетесь участником команды ScriptCat, вы можете сначала сделать fork этого репозитория, а затем создать
+Pull Request в ветку `main` этого репозитория. При создании коммитов, следуйте указанному выше соглашению по сообщениям
+коммитов. Мы объединим ваш вклад в `main` ветку после проведения code review.
 
 ## Написание документации
 
-Документация ScriptCat находится в другом репозитории: [scriptcat.org](https://docs.scriptcat.org), она написана с использованием [docusaurus](https://docusaurus.io/), вот некоторые
-особенности [Markdown](https://docusaurus.io/docs/markdown-features), которые могут вам помочь. Если вам нужно предпросмотреть измененную документацию локально,
-вы можете использовать следующие команды для установки зависимостей документации и запуска dev сервера:
+Документация ScriptCat находится в другом репозитории: [scriptcat.org](https://docs.scriptcat.org), она написана с
+использованием [docusaurus](https://docusaurus.io/), вот некоторые особенности
+[Markdown](https://docusaurus.io/docs/markdown-features), которые могут вам помочь. Если вам нужно предпросмотреть
+измененную документацию локально, вы можете использовать следующие команды для установки зависимостей документации и
+запуска dev сервера:
 
 ```bash
 pnpm install
@@ -65,8 +75,9 @@ pnpm start
 
 ### Помощь с переводом
 
-[Crowdin](https://crowdin.com/project/scriptcat) — это онлайн-платформа для многозначного перевода. Если вы заинтересованы помочь нам
-с переводом контента, связанного с ScriptCat, вы можете найти проект ScriptCat на Crowdin и начать работу по переводу.
+[Crowdin](https://crowdin.com/project/scriptcat) — это онлайн-платформа для многозначного перевода. Если вы
+заинтересованы помочь нам с переводом контента, связанного с ScriptCat, вы можете найти проект ScriptCat на Crowdin и
+начать работу по переводу.
 
 - `src/locales` — каталог файлов перевода для [расширения](https://github.com/scriptscat/scriptcat)
 
@@ -76,11 +87,13 @@ pnpm start
 
 #### Включение режима WYSIWYG для хранилища скриптов
 
-Перейдите на страницу хранилища скриптов: [https://scriptcat.org/ach-UG](https://scriptcat.org/ach-UG) чтобы включить режим WYSIWYG (What You See Is What You Get).
+Перейдите на страницу хранилища скриптов: [https://scriptcat.org/ach-UG](https://scriptcat.org/ach-UG) чтобы включить
+режим WYSIWYG (What You See Is What You Get).
 
 ## Участие в разработке
 
-ScriptCat использует ESLint для стандартизации стиля кода и Vitest для модульного тестирования. Вы можете использовать следующие команды для запуска:
+ScriptCat использует ESLint для стандартизации стиля кода и Vitest для модульного тестирования. Вы можете использовать
+следующие команды для запуска:
 
 ```bash
 pnpm test
@@ -112,5 +125,6 @@ pnpm run pack
 
 ## Важные моменты
 
-- После выполнения `pnpm run dev` необходимо импортировать содержимое каталога `dist/ext` в расширение браузера, а затем начать изменять код
-и сохранять — браузер будет обновляться в реальном времени. Однако изменения, затрагивающие `manifest.json`, `service_worker`, `offscreen`, `sandbox`, требуют перезагрузки расширения.
+- После выполнения `pnpm run dev` необходимо импортировать содержимое каталога `dist/ext` в расширение браузера, а затем
+  начать изменять код и сохранять — браузер будет обновляться в реальном времени. Однако изменения, затрагивающие
+  `manifest.json`, `service_worker`, `offscreen`, `sandbox`, требуют перезагрузки расширения.
diff --git a/e2e/agent-cattool.spec.ts b/e2e/agent-cattool.spec.ts
new file mode 100644
index 000000000..da2abaace
--- /dev/null
+++ b/e2e/agent-cattool.spec.ts
@@ -0,0 +1,154 @@
+import { expect } from "@playwright/test";
+import { test, makeTextSSE, makeToolCallSSE, runAgentTestScript } from "./agent-fixtures";
+
+const TARGET_URL = "https://content-security-policy.com/";
+
+const HELLO_TOOL_CODE = `
+// ==CATTool==
+// @name         hello_world
+// @description  向指定的人打招呼
+// @param        name string [required] 要打招呼的人名
+// ==/CATTool==
+
+return "你好，" + args.name + "！";
+`.trim();
+
+test.describe("Agent CATTool API", () => {
+  test.setTimeout(300_000);
+
+  test("install, list, call, and remove CATTool", async ({ context, extensionId }) => {
+    const escapedToolCode = JSON.stringify(HELLO_TOOL_CODE);
+
+    const code = `// ==UserScript==
+// @name         CATTool Management Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test CAT.agent.tools install/list/call/remove
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.tools
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const toolCode = ${escapedToolCode};
+
+    // Install
+    await CAT.agent.tools.install(toolCode);
+    console.log("Tool installed");
+
+    // List
+    const tools = await CAT.agent.tools.list();
+    assert("tool appears in list", tools.some(t => t.name === "hello_world"));
+    assert("tool has description", tools.some(t => t.description === "向指定的人打招呼"));
+
+    // Call directly
+    const result = await CAT.agent.tools.call("hello_world", { name: "测试" });
+    console.log("Call result: " + JSON.stringify(result));
+    assert("call returns greeting", typeof result === "string" && result.includes("你好") && result.includes("测试"));
+
+    // Remove
+    await CAT.agent.tools.remove("hello_world");
+    const toolsAfter = await CAT.agent.tools.list();
+    assert("tool removed from list", !toolsAfter.some(t => t.name === "hello_world"));
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message + " " + e.stack);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[cattool-management] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[cattool-management] logs:", logs.join("\n"));
+    expect(failed, "Some CATTool management tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+
+  test("CATTool + conversation integration", async ({ context, extensionId, mockLLMResponse }) => {
+    let callCount = 0;
+    mockLLMResponse(() => {
+      callCount++;
+      if (callCount === 1) {
+        // LLM decides to call the installed CATTool
+        return makeToolCallSSE([
+          {
+            id: "call_cat_1",
+            name: "hello_world",
+            arguments: JSON.stringify({ name: "小明" }),
+          },
+        ]);
+      }
+      // After tool result, LLM gives final answer
+      return makeTextSSE("工具返回了问候：你好，小明！");
+    });
+
+    const escapedToolCode = JSON.stringify(HELLO_TOOL_CODE);
+
+    const code = `// ==UserScript==
+// @name         CATTool Conversation Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test CATTool invocation through conversation
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.tools
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const toolCode = ${escapedToolCode};
+
+    // Install CATTool first
+    await CAT.agent.tools.install(toolCode);
+    console.log("CATTool installed");
+
+    // Create conversation — installed CATTools should be auto-registered
+    const conv = await CAT.agent.conversation.create({
+      system: "你是助手，使用工具来完成任务。",
+    });
+    assert("conversation created", !!conv && !!conv.id);
+
+    // Chat — mock will trigger hello_world tool call
+    const reply = await conv.chat("请向小明打招呼");
+    console.log("Reply: " + reply.content);
+    assert("reply has content", !!reply.content);
+    assert("reply mentions greeting", reply.content.includes("你好") || reply.content.includes("小明"));
+
+    // Clean up
+    await CAT.agent.tools.remove("hello_world");
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message + " " + e.stack);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[cattool-conversation] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[cattool-conversation] logs:", logs.join("\n"));
+    expect(failed, "Some CATTool conversation tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+});
diff --git a/e2e/agent-conversation.spec.ts b/e2e/agent-conversation.spec.ts
new file mode 100644
index 000000000..8d0b282c5
--- /dev/null
+++ b/e2e/agent-conversation.spec.ts
@@ -0,0 +1,203 @@
+import { expect } from "@playwright/test";
+import { test, makeTextSSE, makeToolCallSSE, runAgentTestScript } from "./agent-fixtures";
+
+const TARGET_URL = "https://content-security-policy.com/";
+
+test.describe("Agent Conversation API", () => {
+  test.setTimeout(300_000);
+
+  test("basic chat — send message and receive text reply", async ({ context, extensionId, mockLLMResponse }) => {
+    mockLLMResponse(() => makeTextSSE("1+1等于2。"));
+
+    const code = `// ==UserScript==
+// @name         Agent Basic Chat Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test basic CAT.agent.conversation.chat()
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const conv = await CAT.agent.conversation.create({
+      system: "你是一个助手。",
+    });
+    assert("conversation created", !!conv && !!conv.id);
+
+    const reply = await conv.chat("1+1等于几？");
+    assert("reply has content", !!reply.content);
+    assert("reply content correct", reply.content.includes("2"));
+    assert("reply has usage", !!reply.usage);
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[agent-basic-chat] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[agent-basic-chat] logs:", logs.join("\n"));
+    expect(failed, "Some basic chat tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+
+  test("tool calling — script-defined tools are invoked", async ({ context, extensionId, mockLLMResponse }) => {
+    let callCount = 0;
+    mockLLMResponse(() => {
+      callCount++;
+      // First call: LLM decides to call the tool
+      if (callCount === 1) {
+        return makeToolCallSSE([
+          {
+            id: "call_1",
+            name: "get_weather",
+            arguments: JSON.stringify({ city: "北京" }),
+          },
+        ]);
+      }
+      // Second call: after tool result, LLM gives final answer
+      return makeTextSSE("北京今天22度，多云。");
+    });
+
+    const code = `// ==UserScript==
+// @name         Agent Tool Calling Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test tool calling via CAT.agent.conversation
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  let toolCalled = false;
+  let toolArgs = null;
+
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const conv = await CAT.agent.conversation.create({
+      system: "你是天气助手。",
+      tools: [
+        {
+          name: "get_weather",
+          description: "获取天气",
+          parameters: {
+            type: "object",
+            properties: {
+              city: { type: "string", description: "城市" },
+            },
+            required: ["city"],
+          },
+          handler: async (args) => {
+            toolCalled = true;
+            toolArgs = args;
+            return { city: args.city, temperature: 22, condition: "多云" };
+          },
+        },
+      ],
+    });
+
+    const reply = await conv.chat("北京天气怎么样？");
+    assert("tool was called", toolCalled);
+    assert("tool received city arg", toolArgs && toolArgs.city === "北京");
+    assert("final reply has content", !!reply.content);
+    assert("final reply mentions weather", reply.content.includes("22") || reply.content.includes("多云"));
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[agent-tool-calling] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[agent-tool-calling] logs:", logs.join("\n"));
+    expect(failed, "Some tool calling tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+
+  test("multi-turn conversation — context is preserved", async ({ context, extensionId, mockLLMResponse }) => {
+    let requestCount = 0;
+    let lastMessages: any[] = [];
+
+    mockLLMResponse(({ messages }) => {
+      requestCount++;
+      lastMessages = messages;
+      if (requestCount === 1) {
+        return makeTextSSE("斐波那契数列是一个数列，每个数是前两个数之和。");
+      }
+      return makeTextSSE("前5个数是：1, 1, 2, 3, 5。");
+    });
+
+    const code = `// ==UserScript==
+// @name         Agent Multi-turn Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test multi-turn conversation context preservation
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const conv = await CAT.agent.conversation.create({
+      system: "你是数学老师。",
+    });
+
+    const reply1 = await conv.chat("什么是斐波那契数列？");
+    assert("first reply has content", !!reply1.content);
+
+    const reply2 = await conv.chat("前5个数是什么？");
+    assert("second reply has content", !!reply2.content);
+    assert("second reply has fibonacci numbers", reply2.content.includes("1") && reply2.content.includes("5"));
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[agent-multi-turn] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[agent-multi-turn] logs:", logs.join("\n"));
+    expect(failed, "Some multi-turn tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+    // Verify the mock received multiple requests (context was sent)
+    expect(requestCount, "Should have made 2 LLM requests").toBe(2);
+    // The second request should contain history messages
+    expect(lastMessages.length, "Second request should include conversation history").toBeGreaterThan(2);
+  });
+});
diff --git a/e2e/agent-error-handling.spec.ts b/e2e/agent-error-handling.spec.ts
new file mode 100644
index 000000000..22f5d4a4e
--- /dev/null
+++ b/e2e/agent-error-handling.spec.ts
@@ -0,0 +1,201 @@
+import { expect } from "@playwright/test";
+import { test, makeTextSSE, runAgentTestScript } from "./agent-fixtures";
+
+const TARGET_URL = "https://content-security-policy.com/";
+
+test.describe("Agent Error Handling", () => {
+  test.setTimeout(300_000);
+
+  test("LLM returns 500 then retries and succeeds", async ({ context, extensionId, mockLLMResponse }) => {
+    let callCount = 0;
+    mockLLMResponse(() => {
+      callCount++;
+      if (callCount === 1) {
+        // First call will be intercepted below as 500; but mockLLMResponse
+        // wraps to always return 200. So we use a different approach:
+        // Return valid response on second call
+        return makeTextSSE("重试后的回复");
+      }
+      return makeTextSSE("重试后的回复");
+    });
+
+    // Override the route to return 500 on first call, then succeed
+    let reqCount = 0;
+    await context.route("**/mock-llm.test/**", async (route) => {
+      reqCount++;
+      if (reqCount === 1) {
+        await route.fulfill({
+          status: 500,
+          body: "Internal Server Error",
+        });
+        return;
+      }
+      // Second call: return valid SSE
+      await route.fulfill({
+        status: 200,
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+        body: makeTextSSE("重试成功了！"),
+      });
+    });
+
+    const code = `// ==UserScript==
+// @name         Agent Error Retry Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test LLM 500 error retry
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const conv = await CAT.agent.conversation.create({
+      system: "你是助手。",
+    });
+    assert("conversation created", !!conv && !!conv.id);
+
+    const reply = await conv.chat("你好");
+    assert("reply has content after retry", !!reply.content);
+    assert("reply content correct", reply.content.includes("重试成功"));
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 90_000);
+
+    console.log(`[error-retry] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[error-retry] logs:", logs.join("\n"));
+    expect(failed, "Some error retry tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+
+  test("LLM returns 401 — script receives auth error", async ({ context, extensionId }) => {
+    // Override route to always return 401
+    await context.route("**/mock-llm.test/**", async (route) => {
+      await route.fulfill({
+        status: 401,
+        body: "401 Unauthorized: Invalid API key",
+      });
+    });
+
+    const code = `// ==UserScript==
+// @name         Agent Auth Error Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test LLM 401 auth error
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const conv = await CAT.agent.conversation.create({
+      system: "你是助手。",
+    });
+    assert("conversation created", !!conv && !!conv.id);
+
+    // chatStream to capture error events
+    let errorReceived = false;
+    let errorCode = "";
+    const reply = await conv.chat("你好").catch(e => e);
+    assert("received error", reply instanceof Error);
+    // Error message may contain "401" or "Unauthorized" or "API error"
+    const msg = reply.message || "";
+    assert("error is auth related", msg.includes("401") || msg.includes("nauthorized") || msg.includes("API error") || msg.includes("error"));
+  } catch (e) {
+    // Expected error path
+    passed++;
+    console.log("PASS: caught expected auth error - " + e.message);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[auth-error] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[auth-error] logs:", logs.join("\n"));
+    expect(failed, "Some auth error tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+
+  test("conversation abort — conv.abort() cancels ongoing chat", async ({ context, extensionId, mockLLMResponse }) => {
+    // Use a slow response to give time for abort
+    mockLLMResponse(() => {
+      return makeTextSSE("这是一个很长的回复");
+    });
+
+    const code = `// ==UserScript==
+// @name         Agent Abort Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test conversation abort
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const conv = await CAT.agent.conversation.create({
+      system: "你是助手。",
+    });
+    assert("conversation created", !!conv && !!conv.id);
+
+    // Start a chat and verify it completes normally first
+    const reply1 = await conv.chat("第一条消息");
+    assert("first chat works", !!reply1.content);
+
+    // Verify the conversation object exists and has expected methods
+    assert("conv has chat method", typeof conv.chat === "function");
+    assert("conv has id", typeof conv.id === "string");
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message);
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 60_000);
+
+    console.log(`[abort] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[abort] logs:", logs.join("\n"));
+    expect(failed, "Some abort tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+});
diff --git a/e2e/agent-fixtures.ts b/e2e/agent-fixtures.ts
new file mode 100644
index 000000000..c70666744
--- /dev/null
+++ b/e2e/agent-fixtures.ts
@@ -0,0 +1,301 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { test as base, chromium, type BrowserContext, type Route } from "@playwright/test";
+import { installScriptByCode } from "./utils";
+
+/** OpenAI-compatible SSE response for plain text replies */
+function makeTextSSE(content: string): string {
+  const lines = [
+    `data: ${JSON.stringify({ choices: [{ delta: { role: "assistant", content }, index: 0 }] })}`,
+    `data: ${JSON.stringify({ choices: [{ delta: {}, index: 0, finish_reason: "stop" }], usage: { prompt_tokens: 10, completion_tokens: 5 } })}`,
+    "data: [DONE]",
+    "",
+  ];
+  return lines.join("\n\n");
+}
+
+/** OpenAI-compatible SSE response for tool_calls */
+function makeToolCallSSE(toolCalls: Array<{ id: string; name: string; arguments: string }>): string {
+  const lines: string[] = [];
+  for (const tc of toolCalls) {
+    // First chunk: tool call start with name
+    lines.push(
+      `data: ${JSON.stringify({
+        choices: [
+          {
+            delta: {
+              role: "assistant",
+              tool_calls: [
+                {
+                  index: 0,
+                  id: tc.id,
+                  type: "function",
+                  function: { name: tc.name, arguments: "" },
+                },
+              ],
+            },
+            index: 0,
+          },
+        ],
+      })}`
+    );
+    // Second chunk: arguments
+    lines.push(
+      `data: ${JSON.stringify({
+        choices: [
+          {
+            delta: {
+              tool_calls: [{ index: 0, function: { arguments: tc.arguments } }],
+            },
+            index: 0,
+          },
+        ],
+      })}`
+    );
+  }
+  // Finish with tool_calls reason
+  lines.push(
+    `data: ${JSON.stringify({
+      choices: [{ delta: {}, index: 0, finish_reason: "tool_calls" }],
+      usage: { prompt_tokens: 10, completion_tokens: 5 },
+    })}`
+  );
+  lines.push("data: [DONE]");
+  lines.push("");
+  return lines.join("\n\n");
+}
+
+export type MockLLMHandler = (body: { messages: any[]; tools?: any[] }) => string;
+
+export type AgentFixtures = {
+  context: BrowserContext;
+  extensionId: string;
+  mockLLMResponse: (handler: MockLLMHandler) => void;
+};
+
+export { makeTextSSE, makeToolCallSSE };
+
+export const test = base.extend<AgentFixtures>({
+  // eslint-disable-next-line no-empty-pattern
+  context: async ({}, use) => {
+    const pathToExtension = path.resolve(__dirname, "../dist/ext");
+    const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pw-agent-"));
+    const chromeArgs = [`--disable-extensions-except=${pathToExtension}`, `--load-extension=${pathToExtension}`];
+
+    // Phase 1: Enable user scripts permission
+    const ctx1 = await chromium.launchPersistentContext(userDataDir, {
+      headless: false,
+      args: ["--headless=new", ...chromeArgs],
+    });
+    let [bg] = ctx1.serviceWorkers();
+    if (!bg) bg = await ctx1.waitForEvent("serviceworker");
+    const extensionId = bg.url().split("/")[2];
+    const extPage = await ctx1.newPage();
+    await extPage.goto("chrome://extensions/");
+    await extPage.waitForLoadState("domcontentloaded");
+    await extPage.waitForTimeout(1_000);
+    await extPage.evaluate(async (id) => {
+      await (chrome as any).developerPrivate.updateExtensionConfiguration({
+        extensionId: id,
+        userScriptsAccess: true,
+      });
+    }, extensionId);
+    await extPage.close();
+    await ctx1.close();
+
+    // Phase 2: Relaunch with user scripts enabled
+    const context = await chromium.launchPersistentContext(userDataDir, {
+      headless: false,
+      args: ["--headless=new", ...chromeArgs],
+    });
+
+    // 立即等待 service worker 就绪（与 Phase 1 一致，避免事件丢失竞态）
+    let [bg2] = context.serviceWorkers();
+    if (!bg2) bg2 = await context.waitForEvent("serviceworker", { timeout: 30_000 });
+
+    (context as any).__extensionId = extensionId;
+
+    await use(context);
+    await context.close();
+    fs.rmSync(userDataDir, { recursive: true, force: true });
+  },
+
+  extensionId: async ({ context }, use) => {
+    const extensionId: string = (context as any).__extensionId;
+
+    // 唤醒可能已空闲终止的 service worker
+    const ensureServiceWorker = async () => {
+      let sw = context.serviceWorkers().find((w) => w.url().includes(extensionId));
+      if (sw) return sw;
+
+      // SW 可能已空闲终止，通过导航重新激活
+      const swPromise = context.waitForEvent("serviceworker", { timeout: 30_000 });
+      const wakePage = await context.newPage();
+      try {
+        await wakePage.goto(`chrome-extension://${extensionId}/src/options.html`, {
+          waitUntil: "commit",
+          timeout: 10_000,
+        });
+      } catch {
+        // 即使导航失败，请求本身也可能触发 service worker 注册
+      }
+
+      sw = context.serviceWorkers().find((w) => w.url().includes(extensionId));
+      if (!sw) sw = await swPromise;
+      await wakePage.close();
+      return sw;
+    };
+
+    // Dismiss first-use dialog（导航也会唤醒 SW）
+    const initPage = await context.newPage();
+    await initPage.goto(`chrome-extension://${extensionId}/src/options.html`, {
+      waitUntil: "domcontentloaded",
+    });
+    await initPage.evaluate(() => localStorage.setItem("firstUse", "false"));
+    await initPage.close();
+
+    // 确保 SW 处于活跃状态
+    const sw = await ensureServiceWorker();
+    await sw.evaluate(() => {
+      const modelConfig = {
+        id: "mock-model",
+        name: "Mock LLM",
+        provider: "openai",
+        apiBaseUrl: "https://mock-llm.test/v1",
+        apiKey: "test-key",
+        model: "mock-gpt",
+      };
+      return new Promise<void>((resolve) => {
+        chrome.storage.local.set(
+          {
+            "agent_model:mock-model": modelConfig,
+            "agent_model:__default__": "mock-model",
+          },
+          () => resolve()
+        );
+      });
+    });
+
+    await use(extensionId);
+  },
+
+  mockLLMResponse: async ({ context }, use) => {
+    let currentHandler: MockLLMHandler = () => makeTextSSE("default mock response");
+
+    // Set up route interception for mock LLM
+    await context.route("**/mock-llm.test/**", async (route: Route) => {
+      const request = route.request();
+      if (request.method() !== "POST") {
+        await route.fulfill({ status: 405, body: "Method not allowed" });
+        return;
+      }
+
+      let body: any;
+      try {
+        body = JSON.parse(request.postData() || "{}");
+      } catch {
+        body = {};
+      }
+
+      const sseResponse = currentHandler({
+        messages: body.messages || [],
+        tools: body.tools,
+      });
+
+      await route.fulfill({
+        status: 200,
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+        body: sseResponse,
+      });
+    });
+
+    const setHandler = (handler: MockLLMHandler) => {
+      currentHandler = handler;
+    };
+
+    await use(setHandler);
+  },
+});
+
+/**
+ * Auto-approve permission confirm dialogs and CATTool install pages.
+ */
+export function autoApprovePermissions(context: BrowserContext): void {
+  context.on("page", async (page) => {
+    const url = page.url();
+
+    // Auto-approve permission confirm dialogs
+    if (url.includes("confirm.html")) {
+      try {
+        await page.waitForLoadState("domcontentloaded");
+        const successButtons = page.locator("button.arco-btn-status-success");
+        await successButtons.first().waitFor({ timeout: 5_000 });
+        const count = await successButtons.count();
+        if (count >= 3) {
+          await successButtons.nth(2).click();
+        } else {
+          await successButtons.last().click();
+        }
+        console.log("[autoApprove] Permission approved on confirm page");
+      } catch (e) {
+        console.log("[autoApprove] Failed to approve:", e);
+      }
+      return;
+    }
+
+    // Auto-approve CATTool install pages
+    if (url.includes("install.html") && url.includes("cattool=")) {
+      try {
+        await page.waitForLoadState("domcontentloaded");
+        // Wait for the install button to appear (primary button)
+        const installButton = page.locator("button.arco-btn-primary").first();
+        await installButton.waitFor({ timeout: 10_000 });
+        await installButton.click();
+        console.log("[autoApprove] CATTool install approved");
+      } catch (e) {
+        console.log("[autoApprove] Failed to approve CATTool install:", e);
+      }
+      return;
+    }
+  });
+}
+
+/** Run an agent test script and collect console results */
+export async function runAgentTestScript(
+  context: BrowserContext,
+  extensionId: string,
+  code: string,
+  targetUrl: string,
+  timeoutMs: number
+): Promise<{ passed: number; failed: number; logs: string[] }> {
+  await installScriptByCode(context, extensionId, code);
+  autoApprovePermissions(context);
+
+  const page = await context.newPage();
+  const logs: string[] = [];
+  page.on("console", (msg) => logs.push(msg.text()));
+
+  await page.goto(targetUrl, { waitUntil: "domcontentloaded" });
+
+  const deadline = Date.now() + timeoutMs;
+  let passed = -1;
+  let failed = -1;
+  while (Date.now() < deadline) {
+    for (const log of logs) {
+      const passMatch = log.match(/通过[:：]\s*(\d+)/);
+      const failMatch = log.match(/失败[:：]\s*(\d+)/);
+      if (passMatch) passed = parseInt(passMatch[1], 10);
+      if (failMatch) failed = parseInt(failMatch[1], 10);
+    }
+    if (passed >= 0 && failed >= 0) break;
+    await page.waitForTimeout(500);
+  }
+
+  await page.close();
+  return { passed, failed, logs };
+}
diff --git a/e2e/agent-skill.spec.ts b/e2e/agent-skill.spec.ts
new file mode 100644
index 000000000..569b3d7a2
--- /dev/null
+++ b/e2e/agent-skill.spec.ts
@@ -0,0 +1,132 @@
+import { expect } from "@playwright/test";
+import { test, makeTextSSE, makeToolCallSSE, runAgentTestScript } from "./agent-fixtures";
+
+const TARGET_URL = "https://content-security-policy.com/";
+
+const SKILL_MD = `---
+name: greeting-skill
+description: A skill for greeting people
+---
+You are a greeting assistant. Use the greeting tool to greet people.
+
+## Available Tools
+- **greeting-skill__say_hello**: Greet a person by name
+`;
+
+const SAY_HELLO_CODE = `
+// ==CATTool==
+// @name         say_hello
+// @description  Say hello to someone
+// @param        name string [required] Person's name
+// ==/CATTool==
+
+return "Hello, " + args.name + "! Welcome!";
+`.trim();
+
+test.describe("Agent Skill System", () => {
+  test.setTimeout(300_000);
+
+  test("Skill install + load_skill + dynamic CATTool invocation", async ({ context, extensionId, mockLLMResponse }) => {
+    let callCount = 0;
+    mockLLMResponse(({ tools: _tools }) => {
+      callCount++;
+      if (callCount === 1) {
+        // First call: LLM decides to load the skill
+        return makeToolCallSSE([
+          {
+            id: "call_load",
+            name: "load_skill",
+            arguments: JSON.stringify({ skill_name: "greeting-skill" }),
+          },
+        ]);
+      }
+      if (callCount === 2) {
+        // Second call: after skill loaded, LLM calls the dynamic CATTool
+        // The tool should now be registered as greeting-skill__say_hello
+        return makeToolCallSSE([
+          {
+            id: "call_greet",
+            name: "greeting-skill__say_hello",
+            arguments: JSON.stringify({ name: "World" }),
+          },
+        ]);
+      }
+      // Third call: final text response
+      return makeTextSSE("工具返回了：Hello, World! Welcome!");
+    });
+
+    const escapedSkillMd = JSON.stringify(SKILL_MD);
+    const escapedToolCode = JSON.stringify(SAY_HELLO_CODE);
+
+    const code = `// ==UserScript==
+// @name         Agent Skill Test
+// @namespace    https://e2e.test
+// @version      1.0.0
+// @description  Test Skill install + load_skill + dynamic CATTool
+// @author       E2E
+// @match        ${TARGET_URL}*
+// @grant        CAT.agent.skills
+// @grant        CAT.agent.conversation
+// ==/UserScript==
+
+(async () => {
+  let passed = 0;
+  let failed = 0;
+  function assert(name, condition) {
+    if (condition) { passed++; console.log("PASS: " + name); }
+    else { failed++; console.log("FAIL: " + name); }
+  }
+
+  try {
+    const skillMd = ${escapedSkillMd};
+    const toolCode = ${escapedToolCode};
+
+    // Install the skill with its CATTool script
+    // CAT.agent.skills.install(skillMd, scripts?, references?)
+    const skillRecord = await CAT.agent.skills.install(
+      skillMd,
+      [{ name: "say_hello.js", code: toolCode }]
+    );
+    console.log("Skill installed: " + JSON.stringify(skillRecord));
+    assert("skill installed", !!skillRecord);
+    assert("skill name correct", skillRecord.name === "greeting-skill");
+    assert("skill has tool", skillRecord.toolNames && skillRecord.toolNames.includes("say_hello"));
+
+    // Verify skill appears in list
+    const skills = await CAT.agent.skills.list();
+    assert("skill in list", skills.some(s => s.name === "greeting-skill"));
+
+    // Create conversation with skills enabled
+    const conv = await CAT.agent.conversation.create({
+      system: "You are a greeting assistant.",
+      skills: ["greeting-skill"],
+    });
+    assert("conversation created", !!conv && !!conv.id);
+
+    // Chat — mock will trigger load_skill → then say_hello CATTool → final text
+    const reply = await conv.chat("Please greet World");
+    console.log("Reply: " + reply.content);
+    assert("reply has content", !!reply.content);
+    assert("reply mentions greeting", reply.content.includes("Hello") || reply.content.includes("World"));
+
+    // Clean up
+    await CAT.agent.skills.remove("greeting-skill");
+    const skillsAfter = await CAT.agent.skills.list();
+    assert("skill removed", !skillsAfter.some(s => s.name === "greeting-skill"));
+  } catch (e) {
+    failed++;
+    console.log("ERROR: " + e.message + " " + (e.stack || ""));
+  }
+
+  console.log("通过: " + passed + ", 失败: " + failed);
+})();
+`;
+
+    const { passed, failed, logs } = await runAgentTestScript(context, extensionId, code, TARGET_URL, 90_000);
+
+    console.log(`[skill-integration] passed=${passed}, failed=${failed}`);
+    if (failed !== 0) console.log("[skill-integration] logs:", logs.join("\n"));
+    expect(failed, "Some skill integration tests failed").toBe(0);
+    expect(passed, "No test results found").toBeGreaterThan(0);
+  });
+});
diff --git a/e2e/gm-api.spec.ts b/e2e/gm-api.spec.ts
index e70c9a190..b6a023f44 100644
--- a/e2e/gm-api.spec.ts
+++ b/e2e/gm-api.spec.ts
@@ -43,7 +43,7 @@ const test = base.extend<{
     });
     // Ensure service worker is registered before handing context to fixtures,
     // preventing extensionId fixture from timing out with the global 10s timeout.
-    let [sw] = context.serviceWorkers();
+    const [sw] = context.serviceWorkers();
     if (!sw) await context.waitForEvent("serviceworker", { timeout: 30_000 });
     await use(context);
     await context.close();
diff --git a/e2e/options.spec.ts b/e2e/options.spec.ts
index 2901e4113..327de276d 100644
--- a/e2e/options.spec.ts
+++ b/e2e/options.spec.ts
@@ -35,12 +35,8 @@ test.describe("Options Page", () => {
       .click();
     await expect(page).toHaveURL(/.*#\/logger/);
 
-    // Click "Tools" / "工具" menu item
-    await page
-      .locator(".arco-menu-item")
-      .filter({ hasText: /tool|工具/i })
-      .first()
-      .click();
+    // Click "Tools" / "工具" menu item (use .menu-tools class to avoid hitting "CATool" submenu)
+    await page.locator(".menu-tools .arco-menu-item").click();
     await expect(page).toHaveURL(/.*#\/tools/);
 
     // Click "Settings" / "设置" menu item
diff --git a/e2e/utils.ts b/e2e/utils.ts
index ff33c5134..d1494c557 100644
--- a/e2e/utils.ts
+++ b/e2e/utils.ts
@@ -49,11 +49,9 @@ export async function installScriptByCode(context: BrowserContext, extensionId:
   await page.evaluate((text) => navigator.clipboard.writeText(text), code);
   await page.keyboard.press("ControlOrMeta+v");
   // Wait for Monaco to finish rendering the pasted content (content will differ from template)
-  await page.waitForFunction(
-    (init) => document.querySelector(".view-lines")?.textContent !== init,
-    initialText,
-    { timeout: 10_000 }
-  );
+  await page.waitForFunction((init) => document.querySelector(".view-lines")?.textContent !== init, initialText, {
+    timeout: 10_000,
+  });
   // Save
   await page.keyboard.press("ControlOrMeta+s");
   // Wait for save: try arco-message first, then verify via script list
diff --git a/example/agent/README.md b/example/agent/README.md
new file mode 100644
index 000000000..f7437a428
--- /dev/null
+++ b/example/agent/README.md
@@ -0,0 +1,5 @@
+# Agent 示例
+
+Agent 相关的 Skills、CATTools 和使用示例已迁移到独立仓库：
+
+- **GitHub**: https://github.com/scriptscat/skills
diff --git a/example/cat_file_storage.js b/example/cat_file_storage.js
index c142c97bf..815947fba 100644
--- a/example/cat_file_storage.js
+++ b/example/cat_file_storage.js
@@ -10,41 +10,42 @@
 // ==/UserScript==
 
 CAT_fileStorage("upload", {
-	path: "test.txt",
-	baseDir: "test-dir",
-	data: new Blob(["Hello World"]),
-	onload() {
-		CAT_fileStorage("list", {
-			baseDir: "test-dir",
-			onload(list) {
-				console.log(list);
-				list.forEach(value => {
-					if (value.name === "test.txt") {
-						CAT_fileStorage("download", {
-							file: value,
-							baseDir: "test-dir",
-							async onload(data) {
-								console.log(await data.text());
-								CAT_fileStorage("delete", {
-									path: value.name,
-									baseDir: "test-dir",
-									onload() {
-										console.log('ok');
-									}
-								});
-							}
-						});
-					}
-				});
-			}
-		})
-	}, onerror(err) {
-		console.log(err);
-		switch (err.code) {
-			case 1:
-			case 2:
-				CAT_fileStorage("config");
-				break;
-		}
-	}
+  path: "test.txt",
+  baseDir: "test-dir",
+  data: new Blob(["Hello World"]),
+  onload() {
+    CAT_fileStorage("list", {
+      baseDir: "test-dir",
+      onload(list) {
+        console.log(list);
+        list.forEach((value) => {
+          if (value.name === "test.txt") {
+            CAT_fileStorage("download", {
+              file: value,
+              baseDir: "test-dir",
+              async onload(data) {
+                console.log(await data.text());
+                CAT_fileStorage("delete", {
+                  path: value.name,
+                  baseDir: "test-dir",
+                  onload() {
+                    console.log("ok");
+                  },
+                });
+              },
+            });
+          }
+        });
+      },
+    });
+  },
+  onerror(err) {
+    console.log(err);
+    switch (err.code) {
+      case 1:
+      case 2:
+        CAT_fileStorage("config");
+        break;
+    }
+  },
 });
diff --git a/example/cloudcat.js b/example/cloudcat.js
index 6bbbbb3ac..8f303f847 100644
--- a/example/cloudcat.js
+++ b/example/cloudcat.js
@@ -10,6 +10,6 @@
 // ==/UserScript==
 
 return new Promise((resolve, reject) => {
-    // Your code here...
-    resolve();
+  // Your code here...
+  resolve();
 });
diff --git a/example/crontab.js b/example/crontab.js
index 684df4ea0..79bcf4436 100644
--- a/example/crontab.js
+++ b/example/crontab.js
@@ -11,27 +11,25 @@
 // ==/UserScript==
 
 return new Promise((resolve, reject) => {
-    // Your code here...
-    GM_log("下午两点至四点每十五分钟运行一次");
-    
+  // Your code here...
+  GM_log("下午两点至四点每十五分钟运行一次");
 
-    GM_xmlhttpRequest({
-        url: "https://dog.ceo/api/breeds/image/random",
-        method: "GET",
-        responseType: "json",
-        anonymous: true,
+  GM_xmlhttpRequest({
+    url: "https://dog.ceo/api/breeds/image/random",
+    method: "GET",
+    responseType: "json",
+    anonymous: true,
 
-        onload(resp) {
-            if (typeof resp.response.message !== "string") {
-                reject("服务器回应错误。");
-            }
-            else {
-                GM_log(`你可能会遇到的狗狗是\n${resp.response.message}`);
-                resolve();
-            }
-        },
-        onerror(){
-            reject("服务器回应错误。");
-        }
-    });
+    onload(resp) {
+      if (typeof resp.response.message !== "string") {
+        reject("服务器回应错误。");
+      } else {
+        GM_log(`你可能会遇到的狗狗是\n${resp.response.message}`);
+        resolve();
+      }
+    },
+    onerror() {
+      reject("服务器回应错误。");
+    },
+  });
 });
diff --git a/example/error_retry.js b/example/error_retry.js
index 8b14c6c1d..b30314839 100644
--- a/example/error_retry.js
+++ b/example/error_retry.js
@@ -9,10 +9,10 @@
 // ==/UserScript==
 
 return new Promise((resolve, reject) => {
-	// Your code here...
-	GM_notification({
-		title: "retry",
-		text: "10秒后重试"
-	});
-	reject(new CATRetryError("xxx错误", 10));
+  // Your code here...
+  GM_notification({
+    title: "retry",
+    text: "10秒后重试",
+  });
+  reject(new CATRetryError("xxx错误", 10));
 });
diff --git a/example/gm_async.js b/example/gm_async.js
index 943fe4623..9cd973464 100644
--- a/example/gm_async.js
+++ b/example/gm_async.js
@@ -18,37 +18,34 @@
  * - 避免污染全局作用域
  */
 (async function () {
-    'use strict';
-
-    /**
-     * GM.setValue / GM.getValue（Promise 风格）
-     * ----------------
-     * - 新版 GM API 返回 Promise
-     * - 用于持久化存储数据（不随标签页关闭而消失）
-     * - 作用域为当前脚本
-     */
-
-    // 设置一个键值对：test-key = 1
-    GM.setValue("test-key", 1).then(() => {
-
-        // 设置完成后再读取该值
-        GM.getValue("test-key").then(value => {
-            console.log("get test-key value:", value);
-        });
-
+  "use strict";
+
+  /**
+   * GM.setValue / GM.getValue（Promise 风格）
+   * ----------------
+   * - 新版 GM API 返回 Promise
+   * - 用于持久化存储数据（不随标签页关闭而消失）
+   * - 作用域为当前脚本
+   */
+
+  // 设置一个键值对：test-key = 1
+  GM.setValue("test-key", 1).then(() => {
+    // 设置完成后再读取该值
+    GM.getValue("test-key").then((value) => {
+      console.log("get test-key value:", value);
     });
+  });
 
-    /**
-     * GM.getResourceUrl（异步版本）
-     * ----------------
-     * - 读取通过 @resource 声明的静态资源
-     * - 返回的是一个 Promise
-     * - resolve 后得到资源的本地 URL（blob / data URL）
-     */
-
-    const resourceUrl = await GM.getResourceUrl("test.html");
+  /**
+   * GM.getResourceUrl（异步版本）
+   * ----------------
+   * - 读取通过 @resource 声明的静态资源
+   * - 返回的是一个 Promise
+   * - resolve 后得到资源的本地 URL（blob / data URL）
+   */
 
-    // 打印资源对应的 URL
-    console.log(resourceUrl);
+  const resourceUrl = await GM.getResourceUrl("test.html");
 
+  // 打印资源对应的 URL
+  console.log(resourceUrl);
 })();
diff --git a/example/gm_cookie.js b/example/gm_cookie.js
index c8d6b1c00..98bba59c8 100644
--- a/example/gm_cookie.js
+++ b/example/gm_cookie.js
@@ -16,56 +16,73 @@
  * set / list / delete Cookie
  * 每个新域名首次使用都需要用户授权
  */
-GM_cookie("set", {
+GM_cookie(
+  "set",
+  {
     url: "http://example.com/cookie",
     name: "cookie1",
-    value: "value"
-}, () => {
-
-    GM_cookie("set", {
+    value: "value",
+  },
+  () => {
+    GM_cookie(
+      "set",
+      {
         url: "http://www.example.com/",
         domain: ".example.com",
         path: "/path",
         name: "cookie2",
-        value: "path"
-    }, () => {
-
+        value: "path",
+      },
+      () => {
         // 按 domain 查询 cookie
-        GM_cookie("list", {
-            domain: "example.com"
-        }, (cookies) => {
+        GM_cookie(
+          "list",
+          {
+            domain: "example.com",
+          },
+          (cookies) => {
             console.log("domain", cookies);
-        });
+          }
+        );
 
         // 按 url 查询 cookie
-        GM_cookie("list", {
+        GM_cookie(
+          "list",
+          {
             url: "http://example.com/cookie",
-        }, (cookies) => {
+          },
+          (cookies) => {
             console.log("url", cookies);
-        });
+          }
+        );
 
         // 删除 cookie
-        GM_cookie("delete", {
+        GM_cookie(
+          "delete",
+          {
             url: "http://www.example.com/path",
-            name: "cookie2"
-        }, () => {
-
-            GM_cookie("list", {
-                domain: "example.com"
-            }, (cookies) => {
+            name: "cookie2",
+          },
+          () => {
+            GM_cookie(
+              "list",
+              {
+                domain: "example.com",
+              },
+              (cookies) => {
                 console.log("delete", cookies);
-            });
-
-        });
-    });
-});
+              }
+            );
+          }
+        );
+      }
+    );
+  }
+);
 
 /**
  * GM.cookie（Promise / async 风格）
  * ----------------
  * ScriptCat / 新版 TM 推荐写法
  */
-console.log(
-  "async GM.cookie.list",
-  await GM.cookie.list({ domain: "example.com" })
-);
+console.log("async GM.cookie.list", await GM.cookie.list({ domain: "example.com" }));
diff --git a/example/gm_download.js b/example/gm_download.js
index b34674ed6..c5105b69d 100644
--- a/example/gm_download.js
+++ b/example/gm_download.js
@@ -22,39 +22,37 @@
 // 1. 下载网络资源
 
 GM_download({
-    url: "https://scriptcat.org/api/v2/open/crx-download/ndcooeababalnlpkfedmmbbbgkljhpjf",
-    name: "scriptcat.crx",
+  url: "https://scriptcat.org/api/v2/open/crx-download/ndcooeababalnlpkfedmmbbbgkljhpjf",
+  name: "scriptcat.crx",
 
-    headers: {
-        referer: "http://www.example.com/",
-        origin: "www.example.com"
-    },
+  headers: {
+    referer: "http://www.example.com/",
+    origin: "www.example.com",
+  },
 
-    onprogress(data) {
-        console.log("progress", data);
-    },
+  onprogress(data) {
+    console.log("progress", data);
+  },
 
-    onload(data) {
-        console.log("load", data);
-    },
+  onload(data) {
+    console.log("load", data);
+  },
 });
 
 // 2. 下载 Blob 资源
 // 参考： https://github.com/Tampermonkey/tampermonkey/issues/2591
 
 const pngData = new Uint8Array([
-    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
-    0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
-    0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, 0x89, 0x00, 0x00, 0x00,
-    0x0a, 0x49, 0x44, 0x41, 0x54, 0x08, 0xd7, 0x63, 0xf8, 0xcf, 0xc0, 0x00,
-    0x00, 0x03, 0x01, 0x01, 0x00, 0xae, 0xb4, 0xfa, 0x77, 0x00, 0x00, 0x00,
-    0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00,
+  0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, 0x89, 0x00, 0x00, 0x00, 0x0a, 0x49,
+  0x44, 0x41, 0x54, 0x08, 0xd7, 0x63, 0xf8, 0xcf, 0xc0, 0x00, 0x00, 0x03, 0x01, 0x01, 0x00, 0xae, 0xb4, 0xfa, 0x77,
+  0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
 ]);
 
-const testImageUrl = URL.createObjectURL(new Blob([pngData], { type: 'image/png' }));
+const testImageUrl = URL.createObjectURL(new Blob([pngData], { type: "image/png" }));
 
 GM_download({
-    url: testImageUrl,
-    name: 'test/test.png', // 储存在 test 资料夹内
-    conflictAction: 'overwrite', // 每次都使用固定的档案名
+  url: testImageUrl,
+  name: "test/test.png", // 储存在 test 资料夹内
+  conflictAction: "overwrite", // 每次都使用固定的档案名
 });
diff --git a/example/gm_log.js b/example/gm_log.js
index 780d1ba58..10745efb8 100644
--- a/example/gm_log.js
+++ b/example/gm_log.js
@@ -19,5 +19,5 @@
  * 3. 附加标签信息
  */
 GM_log("log message", "info", {
-  component: "example"
+  component: "example",
 });
diff --git a/example/gm_menu/gm_bg_menu.js b/example/gm_menu/gm_bg_menu.js
index 0688dc450..d9161ea18 100644
--- a/example/gm_menu/gm_bg_menu.js
+++ b/example/gm_menu/gm_bg_menu.js
@@ -10,9 +10,13 @@
 // ==/UserScript==
 
 return new Promise((resolve) => {
-  const id = GM_registerMenuCommand("测试菜单", () => {
-    console.log(id);
-    GM_unregisterMenuCommand(id);
-    resolve();
-  }, "z");
-});
\ No newline at end of file
+  const id = GM_registerMenuCommand(
+    "测试菜单",
+    () => {
+      console.log(id);
+      GM_unregisterMenuCommand(id);
+      resolve();
+    },
+    "z"
+  );
+});
diff --git a/example/gm_save_tab.js b/example/gm_save_tab.js
index b57ecf189..f7570dccf 100644
--- a/example/gm_save_tab.js
+++ b/example/gm_save_tab.js
@@ -30,8 +30,8 @@ GM_saveTab({ test: "save" });
  *
  * 回调函数会接收到保存的数据对象
  */
-GM_getTab(data => {
-    console.log(data);
+GM_getTab((data) => {
+  console.log(data);
 });
 
 /**
@@ -46,6 +46,6 @@ GM_getTab(data => {
  *   ...
  * }
  */
-GM_getTabs(data => {
-    console.log(data);
+GM_getTabs((data) => {
+  console.log(data);
 });
diff --git a/example/gm_tab.js b/example/gm_tab.js
index 92775c19e..7582f9428 100644
--- a/example/gm_tab.js
+++ b/example/gm_tab.js
@@ -17,10 +17,10 @@ const tab = GM_openInTab("https://scriptcat.org/search");
 
 // 监听标签页关闭事件
 tab.onclose = () => {
-    console.log("close");
-}
+  console.log("close");
+};
 
 // 3 秒后主动关闭该标签页
 setTimeout(() => {
-    tab.close();
+  tab.close();
 }, 3000);
diff --git a/example/gm_value/listener_change.js b/example/gm_value/listener_change.js
index 7ec068726..88ed2ac3c 100644
--- a/example/gm_value/listener_change.js
+++ b/example/gm_value/listener_change.js
@@ -13,11 +13,11 @@
 // ==/UserScript==
 
 GM_addValueChangeListener("test_set", function (name, oldval, newval, remote) {
-    console.log("test_set change", name, oldval, newval, remote);
+  console.log("test_set change", name, oldval, newval, remote);
 });
 
 setInterval(() => {
-    console.log("test_set: ", GM_getValue("test_set"));
-    console.log("value list:", GM_listValues());
-    GM_setValue("test_set", Date.now());
+  console.log("test_set: ", GM_getValue("test_set"));
+  console.log("value list:", GM_listValues());
+  GM_setValue("test_set", Date.now());
 }, 2000);
diff --git a/example/gm_xhr.js b/example/gm_xhr.js
index 0792181c5..65815eaaa 100644
--- a/example/gm_xhr.js
+++ b/example/gm_xhr.js
@@ -14,10 +14,7 @@
  */
 const data = new FormData();
 data.append("username", "admin");
-data.append(
-  "file",
-  new File(["foo"], "foo.txt", { type: "text/plain" })
-);
+data.append("file", new File(["foo"], "foo.txt", { type: "text/plain" }));
 
 /**
  * GM_xmlhttpRequest
diff --git a/example/require_css.js b/example/require_css.js
index 55696d6c9..82176d8cb 100644
--- a/example/require_css.js
+++ b/example/require_css.js
@@ -8,8 +8,8 @@
 // @require-css  https://samplesdl.me/training_html-css/style.css
 // ==/UserScript==
 
-(function() {
-    'use strict';
+(function () {
+  "use strict";
 
-    // Your code here...
+  // Your code here...
 })();
diff --git a/example/require_local_file.js b/example/require_local_file.js
index df5d4abd6..61b86a5c4 100644
--- a/example/require_local_file.js
+++ b/example/require_local_file.js
@@ -8,8 +8,8 @@
 // @require      file:///Users/codfrm/Desktop/test.js
 // ==/UserScript==
 
-(function() {
-    'use strict';
+(function () {
+  "use strict";
 
-    // Your code here...
+  // Your code here...
 })();
diff --git a/example/tests/gm_xhr_test.js b/example/tests/gm_xhr_test.js
index 2a03deead..dff6d2377 100644
--- a/example/tests/gm_xhr_test.js
+++ b/example/tests/gm_xhr_test.js
@@ -1,7 +1,7 @@
 // ==UserScript==
 // @name         GM_xmlhttpRequest Exhaustive Test Harness v3
 // @namespace    tm-gmxhr-test
-// @version      1.2.3
+// @version      1.2.4
 // @description  Comprehensive in-page tests for GM_xmlhttpRequest: normal, abnormal, and edge cases with clear pass/fail output.
 // @author       you
 // @match        *://*/*?GM_XHR_TEST_SC
@@ -878,6 +878,36 @@ const enableTool = true;
         assertEq(objectProps(res), "ok", "Object Props OK");
       },
     },
+    {
+      name: "responseType=document(parse ok)",
+      async run(fetch) {
+        const { res } = await gmRequest({
+          method: "GET",
+          url: `${HB}/base64/PHRlc3QtMTIzPmhlbGxvPC90ZXN0LTEyMz4=`,
+          responseType: "document",
+          fetch,
+        });
+        assertEq(res.status, 200);
+        assert(res.response instanceof Document, "xml present");
+        assert(res.responseXML !== null, "xml OK");
+        assert(!!res.responseXML.querySelector("test-123"), "xml content ok");
+      },
+    },
+    {
+      name: "responseType=document(parser error)",
+      async run(fetch) {
+        const { res } = await gmRequest({
+          method: "GET",
+          url: `${HB}/base64/AAAAAAEAAQA=`,
+          responseType: "document",
+          fetch,
+        });
+        assertEq(res.status, 200);
+        assert(res.response instanceof Document, "xml present");
+        assert(res.responseXML !== null, "xml OK");
+        assert(!!res.responseXML.querySelector("parsererror"), "xml content ok");
+      },
+    },
     {
       name: "overrideMimeType (force text)",
       async run(fetch) {
diff --git a/example/userconfig.js b/example/userconfig.js
index 5e36d13ec..a65c5c759 100644
--- a/example/userconfig.js
+++ b/example/userconfig.js
@@ -91,7 +91,7 @@ setInterval(() => {
   // GM_info新方法读取UserConfig，可直接关联读取缺省值，无需额外修改
   console.log(userConfig["group1.configA"]);
   console.log(userConfig["group1.configG"]);
-}, 5000)
+}, 5000);
 
 // 打开用户配置
 CAT_userConfig();
diff --git a/example/vscode.user.js b/example/vscode.user.js
index 9d91649dc..cefd35162 100644
--- a/example/vscode.user.js
+++ b/example/vscode.user.js
@@ -7,7 +7,7 @@
 // @match        https://bbs.tampermonkey.net.cn/
 // ==/UserScript==
 
-(function() {
-    'use strict';
-    // Your code here...
+(function () {
+  "use strict";
+  // Your code here...
 })();
diff --git a/package.json b/package.json
index 7f2b38c93..2e8ba08f9 100644
--- a/package.json
+++ b/package.json
@@ -1,12 +1,13 @@
 {
   "name": "scriptcat",
-  "version": "1.3.1",
+  "version": "1.5.0-alpha",
   "description": "脚本猫,一个可以执行用户脚本的浏览器扩展,万物皆可脚本化,让你的浏览器可以做更多的事情!",
   "author": "CodFrm",
   "license": "GPLv3",
   "private": true,
   "scripts": {
     "preinstall": "pnpm dlx only-allow pnpm",
+    "prepare": "husky",
     "test": "vitest --test-timeout=500 --no-coverage --isolate=false --reporter=verbose",
     "test:ci": "vitest run --test-timeout=500 --no-coverage --isolate=false --reporter=default --reporter.summary=false",
     "coverage": "vitest run --coverage",
@@ -42,6 +43,7 @@
     "eslint-linter-browserify": "9.26.0",
     "eventemitter3": "^5.0.1",
     "fast-xml-parser": "^5.3.6",
+    "highlight.js": "^11.11.1",
     "i18next": "^23.16.4",
     "monaco-editor": "^0.52.2",
     "react": "^18.3.1",
@@ -50,7 +52,10 @@
     "react-i18next": "^15.6.0",
     "react-icons": "^5.5.0",
     "react-joyride": "^2.9.3",
+    "react-markdown": "^9.1.0",
     "react-router-dom": "^7.13.0",
+    "rehype-highlight": "^7.0.2",
+    "remark-gfm": "^4.0.1",
     "string-similarity-js": "^2.1.4",
     "uuid": "^11.1.0",
     "webdav": "^5.9.0",
@@ -84,6 +89,7 @@
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-userscripts": "^0.5.6",
     "globals": "^16.5.0",
+    "husky": "^9.1.7",
     "iconv-lite": "^0.7.2",
     "jsdom": "^26.1.0",
     "jszip": "^3.10.1",
@@ -104,4 +110,4 @@
     "**/*.scss",
     "**/*.less"
   ]
-}
\ No newline at end of file
+}
diff --git a/packages/chrome-extension-mock/README.md b/packages/chrome-extension-mock/README.md
index 8e691efdc..1d7c1f361 100644
--- a/packages/chrome-extension-mock/README.md
+++ b/packages/chrome-extension-mock/README.md
@@ -1,3 +1,3 @@
 # mock一个chrome扩展环境
-> 只针对自己的项目做了一些简单的封装，如果有需要可以自己修改
 
+> 只针对自己的项目做了一些简单的封装，如果有需要可以自己修改
diff --git a/packages/cloudscript/README.md b/packages/cloudscript/README.md
index 9e7707a74..e13f2d901 100644
--- a/packages/cloudscript/README.md
+++ b/packages/cloudscript/README.md
@@ -1,3 +1 @@
 # 脚本上云
-
-
diff --git a/packages/eslint/compat-grant.js b/packages/eslint/compat-grant.js
index 6b90fa7a2..bf9039de7 100644
--- a/packages/eslint/compat-grant.js
+++ b/packages/eslint/compat-grant.js
@@ -7,6 +7,11 @@ const compatMap = {
   CAT_registerMenuInput: [{ type: "scriptcat", versionConstraint: ">=0.17.0-beta.2" }],
   CAT_unregisterMenuInput: [{ type: "scriptcat", versionConstraint: ">=0.17.0-beta.2" }],
   CAT_scriptLoaded: [{ type: "scriptcat", versionConstraint: ">=1.1.0-beta" }],
+  "CAT.agent.conversation": [{ type: "scriptcat", versionConstraint: ">=1.4.0-beta" }],
+  "CAT.agent.tools": [{ type: "scriptcat", versionConstraint: ">=1.4.0-beta" }],
+  "CAT.agent.skills": [{ type: "scriptcat", versionConstraint: ">=1.4.0-beta" }],
+  "CAT.agent.dom": [{ type: "scriptcat", versionConstraint: ">=1.4.0-beta" }],
+  "CAT.agent.task": [{ type: "scriptcat", versionConstraint: ">=1.4.0-beta" }],
   ...compat_grant.compatMap,
 };
 
diff --git a/packages/eslint/linter-config.ts b/packages/eslint/linter-config.ts
index d6b57a1c4..361eadcc8 100644
--- a/packages/eslint/linter-config.ts
+++ b/packages/eslint/linter-config.ts
@@ -17,6 +17,7 @@ const config = {
     CAT_registerMenuInput: "readonly",
     CAT_unregisterMenuInput: "readonly",
     CAT_scriptLoaded: "readonly",
+    CAT: "readonly",
   },
   rules: {
     "constructor-super": ["error"],
diff --git a/packages/message/README.md b/packages/message/README.md
index 6ebb01776..fd73c1f34 100644
--- a/packages/message/README.md
+++ b/packages/message/README.md
@@ -4,11 +4,9 @@
 
 主要会有以下几种类型的消息：
 
-- 从脚本发起的GM请求，需要层层传递到service_worker/offscreen进行处理，有的GM只需要进行一次调用获取一次结果，有的需要进行
-  多次调用获取多次结果，使用connect的方式实现
+- 从脚本发起的GM请求，需要层层传递到service_worker/offscreen进行处理，有的GM只需要进行一次调用获取一次结果，有的需要进行多次调用获取多次结果，使用connect的方式实现
 - 从service_worker/offscreen发起的请求，类似消息队列，其它页面进行监听，触发后广播给所有页面，使用sendMessage方式实现
-- 从扩展页面发起的请求，需要传递到service_worker/offscreen进行处理，如果只是单次调用，获取一次结果，使用sendMessage方式实现，如果需要
-  多次调用获取多次结果，使用connect方式实现
+- 从扩展页面发起的请求，需要传递到service_worker/offscreen进行处理，如果只是单次调用，获取一次结果，使用sendMessage方式实现，如果需要多次调用获取多次结果，使用connect方式实现
 
 ## 注意点
 
diff --git a/packages/message/extension_message.ts b/packages/message/extension_message.ts
index 7b6dfc745..e1fd75720 100644
--- a/packages/message/extension_message.ts
+++ b/packages/message/extension_message.ts
@@ -1,4 +1,8 @@
+import EventEmitter from "eventemitter3";
 import type { Message, MessageConnect, MessageSend, RuntimeMessageSender, TMessage, TMessageCommAction } from "./types";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+const listenerMgr = new EventEmitter<string, any>(); // 单一管理器
 
 export class ExtensionMessage implements Message {
   constructor(private backgroundPrimary = false) {}
@@ -19,8 +23,6 @@ export class ExtensionMessage implements Message {
         if (lastError) {
           console.error("chrome.runtime.lastError in chrome.runtime.sendMessage:", lastError);
           // 通信API出错不回继续对话
-          resolve = null;
-          return;
         }
         resolve!(resp);
         resolve = null;
@@ -146,25 +148,75 @@ export class ExtensionMessage implements Message {
 }
 
 export class ExtensionMessageConnect implements MessageConnect {
-  constructor(private con: chrome.runtime.Port) {}
+  private readonly listenerId = `${uuidv4()}`; // 使用 uuidv4 确保唯一
+  private con: chrome.runtime.Port | null;
+  private isSelfDisconnected = false;
+
+  constructor(con: chrome.runtime.Port) {
+    this.con = con; // 强引用
+    const handler = (msg: TMessage, _con: chrome.runtime.Port) => {
+      listenerMgr.emit(`onMessage:${this.listenerId}`, msg);
+    };
+    const cleanup = (con: chrome.runtime.Port) => {
+      if (this.con) {
+        this.con = null;
+        listenerMgr.removeAllListeners(`cleanup:${this.listenerId}`);
+        con.onMessage.removeListener(handler);
+        con.onDisconnect.removeListener(cleanup);
+        listenerMgr.emit(`onDisconnect:${this.listenerId}`, this.isSelfDisconnected);
+        listenerMgr.removeAllListeners(`onDisconnect:${this.listenerId}`);
+        listenerMgr.removeAllListeners(`onMessage:${this.listenerId}`);
+      }
+    };
+    con.onMessage.addListener(handler);
+    con.onDisconnect.addListener(cleanup);
+    listenerMgr.once(`cleanup:${this.listenerId}`, cleanup);
+  }
 
   sendMessage(data: TMessage) {
-    this.con.postMessage(data);
+    if (!this.con) {
+      console.warn("Attempted to sendMessage on a disconnected port.");
+      // 無法 sendMessage 不应该屏蔽错误
+      throw new Error("Attempted to sendMessage on a disconnected port.");
+    }
+    this.con?.postMessage(data);
   }
 
   onMessage(callback: (data: TMessage) => void) {
-    this.con.onMessage.addListener(callback);
+    if (!this.con) {
+      console.error("onMessage Invalid Port");
+      // 無法監聽的話不应该屏蔽错误
+      throw new Error("onMessage Invalid Port");
+    }
+    listenerMgr.addListener(`onMessage:${this.listenerId}`, callback);
   }
 
   disconnect() {
-    this.con.disconnect();
+    if (!this.con) {
+      console.warn("Attempted to disconnect on a disconnected port.");
+      // 重复 disconnect() 不应该屏蔽错误
+      throw new Error("Attempted to disconnect on a disconnected port.");
+    }
+    this.isSelfDisconnected = true;
+    this.con?.disconnect();
+    // Note: .disconnect() will NOT automatically trigger the 'cleanup' listener
+    listenerMgr.emit(`cleanup:${this.listenerId}`);
   }
 
-  onDisconnect(callback: () => void) {
-    this.con.onDisconnect.addListener(callback);
+  onDisconnect(callback: (isSelfDisconnected: boolean) => void) {
+    if (!this.con) {
+      console.error("onDisconnect Invalid Port");
+      // 無法監聽的話不应该屏蔽错误
+      throw new Error("onDisconnect Invalid Port");
+    }
+    listenerMgr.once(`onDisconnect:${this.listenerId}`, callback);
   }
 
   getPort(): chrome.runtime.Port {
+    if (!this.con) {
+      console.error("Port is already disconnected.");
+      throw new Error("Port is already disconnected.");
+    }
     return this.con;
   }
 }
diff --git a/packages/message/mock_message.ts b/packages/message/mock_message.ts
index f4bc3ea47..e49d04481 100644
--- a/packages/message/mock_message.ts
+++ b/packages/message/mock_message.ts
@@ -16,11 +16,11 @@ export class MockMessageConnect implements MessageConnect {
   }
 
   disconnect(): void {
-    this.EE.emit("disconnect");
+    this.EE.emit("disconnect", true); // MockMessageConnect 未有模拟由另一端触发 disconnect() 的情况
   }
 
-  onDisconnect(callback: () => void): void {
-    this.EE.on("disconnect", callback);
+  onDisconnect(callback: (isSelfDisconnected: boolean) => void) {
+    this.EE.once("disconnect", callback);
   }
 }
 
diff --git a/packages/message/server.ts b/packages/message/server.ts
index e69e7f0e7..05c8169e3 100644
--- a/packages/message/server.ts
+++ b/packages/message/server.ts
@@ -273,15 +273,15 @@ export function forwardMessage(
   senderTo: MessageSend,
   middleware?: ApiFunctionSync
 ) {
-  const handler = (params: any, fromCon: IGetSender) => {
-    const fromConnect = fromCon.getConnect();
+  const handler = async (params: any, fromCon: IGetSender): Promise<any> => {
+    const fromConnect: MessageConnect | undefined = fromCon.getConnect();
     if (fromConnect) {
-      connect(senderTo, `${prefix}/${path}`, params).then((toCon: MessageConnect) => {
-        fromConnect.onMessage(toCon.sendMessage.bind(toCon));
-        toCon.onMessage(fromConnect.sendMessage.bind(fromConnect));
-        fromConnect.onDisconnect(toCon.disconnect.bind(toCon));
-        toCon.onDisconnect(fromConnect.disconnect.bind(fromConnect));
-      });
+      const toCon: MessageConnect = await connect(senderTo, `${prefix}/${path}`, params);
+      fromConnect.onMessage(toCon.sendMessage.bind(toCon));
+      toCon.onMessage(fromConnect.sendMessage.bind(fromConnect));
+      fromConnect.onDisconnect(toCon.disconnect.bind(toCon));
+      toCon.onDisconnect(fromConnect.disconnect.bind(fromConnect));
+      return undefined;
     } else {
       return sendMessage(senderTo, prefix + "/" + path, params);
     }
diff --git a/packages/message/types.ts b/packages/message/types.ts
index 23cd59aaf..3c3e94a91 100644
--- a/packages/message/types.ts
+++ b/packages/message/types.ts
@@ -50,7 +50,7 @@ export interface MessageConnect {
   onMessage(callback: (data: TMessage) => void): void;
   sendMessage(data: TMessage): void;
   disconnect(): void;
-  onDisconnect(callback: () => void): void;
+  onDisconnect(callback: (isSelfDisconnected: boolean) => void): void;
 }
 
 export type ExtMessageSender = {
diff --git a/packages/message/window_message.ts b/packages/message/window_message.ts
index baedbbe30..e4fdb7c48 100644
--- a/packages/message/window_message.ts
+++ b/packages/message/window_message.ts
@@ -2,6 +2,8 @@ import type { Message, MessageConnect, MessageSend, RuntimeMessageSender, TMessa
 import { uuidv4 } from "@App/pkg/utils/uuid";
 import EventEmitter from "eventemitter3";
 
+const listenerMgr = new EventEmitter<string, any>(); // 单一管理器
+
 // 通过 window.postMessage/onmessage 实现通信
 
 export interface PostMessage {
@@ -90,7 +92,9 @@ export class WindowMessage implements Message {
         data,
       };
       this.target.postMessage(body, "*");
-      resolve(new WindowMessageConnect(body.messageId, this.EE, this.target));
+      // 使用 WindowPostMessage 包装，确保后续 sendMessage 也带 "*" targetOrigin
+      // 否则沙箱（origin: null）→ offscreen（origin: chrome-extension://）的消息会被丢弃
+      resolve(new WindowMessageConnect(body.messageId, this.EE, new WindowPostMessage(this.target)));
     });
   }
 
@@ -121,19 +125,41 @@ export class WindowMessage implements Message {
 }
 
 export class WindowMessageConnect implements MessageConnect {
+  private readonly listenerId = `${uuidv4()}`; // 使用 uuidv4 确保唯一
+  private target: PostMessage | null;
+  private isSelfDisconnected = false;
+
   constructor(
     private messageId: string,
-    private EE: EventEmitter<string, any>,
-    private target: PostMessage
+    EE: EventEmitter<string, any>,
+    target: PostMessage
   ) {
-    this.onDisconnect(() => {
-      // 移除所有监听
-      this.EE.removeAllListeners("connectMessage:" + this.messageId);
-      this.EE.removeAllListeners("disconnect:" + this.messageId);
-    });
+    this.target = target; // 强引用
+    const handler = (msg: TMessage) => {
+      listenerMgr.emit(`onMessage:${this.listenerId}`, msg);
+    };
+    const cleanup = () => {
+      if (this.target) {
+        this.target = null;
+        listenerMgr.removeAllListeners(`cleanup:${this.listenerId}`);
+        EE.removeAllListeners("connectMessage:" + this.messageId); // 模拟 con.onMessage.removeListener
+        EE.removeAllListeners("disconnect:" + this.messageId); // 模拟 con.onDisconnect.removeListener
+        listenerMgr.emit(`onDisconnect:${this.listenerId}`, this.isSelfDisconnected);
+        listenerMgr.removeAllListeners(`onDisconnect:${this.listenerId}`);
+        listenerMgr.removeAllListeners(`onMessage:${this.listenerId}`);
+      }
+    };
+    EE.addListener(`connectMessage:${this.messageId}`, handler); // 模拟 con.onMessage.addListener
+    EE.addListener(`disconnect:${this.messageId}`, cleanup); // 模拟 con.onDisconnect.addListener
+    listenerMgr.once(`cleanup:${this.listenerId}`, cleanup);
   }
 
   sendMessage(data: TMessage) {
+    if (!this.target) {
+      console.error("Attempted to sendMessage on a disconnected Target.");
+      // 無法 sendMessage 不应该屏蔽错误
+      throw new Error("Attempted to sendMessage on a disconnected Target.");
+    }
     const body: WindowMessageBody<TMessage> = {
       messageId: this.messageId,
       type: "connectMessage",
@@ -143,20 +169,38 @@ export class WindowMessageConnect implements MessageConnect {
   }
 
   onMessage(callback: (data: TMessage) => void) {
-    this.EE.addListener(`connectMessage:${this.messageId}`, callback);
+    if (!this.target) {
+      console.error("onMessage Invalid Target");
+      // 無法監聽的話不应该屏蔽错误
+      throw new Error("onMessage Invalid Target");
+    }
+    listenerMgr.addListener(`onMessage:${this.listenerId}`, callback);
   }
 
   disconnect() {
+    if (!this.target) {
+      console.warn("Attempted to disconnect on a disconnected Target.");
+      // 重复 disconnect() 不应该屏蔽错误
+      throw new Error("Attempted to disconnect on a disconnected Target.");
+    }
+    this.isSelfDisconnected = true;
     const body: WindowMessageBody<TMessage> = {
       messageId: this.messageId,
       type: "disconnect",
       data: null,
     };
     this.target.postMessage(body);
+    // Note: .disconnect() will NOT automatically trigger the 'cleanup' listener
+    listenerMgr.emit(`cleanup:${this.listenerId}`);
   }
 
-  onDisconnect(callback: () => void) {
-    this.EE.addListener(`disconnect:${this.messageId}`, callback);
+  onDisconnect(callback: (isSelfDisconnected: boolean) => void) {
+    if (!this.target) {
+      console.error("onDisconnect Invalid Target");
+      // 無法監聽的話不应该屏蔽错误
+      throw new Error("onDisconnect Invalid Target");
+    }
+    listenerMgr.once(`onDisconnect:${this.listenerId}`, callback);
   }
 }
 
diff --git a/playwright.config.ts b/playwright.config.ts
index 9a15dabba..a5bea295d 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -8,7 +8,7 @@ export default defineConfig({
   },
   fullyParallel: false,
   forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 1 : 0,
+  retries: process.env.CI ? 1 : 1,
   workers: 1,
   reporter: process.env.CI ? [["html", { open: "never" }], ["list"]] : "list",
   outputDir: "test-results",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d2dab0f5e..82c69ba90 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -50,6 +50,9 @@ importers:
       fast-xml-parser:
         specifier: ^5.3.6
         version: 5.3.6
+      highlight.js:
+        specifier: ^11.11.1
+        version: 11.11.1
       i18next:
         specifier: ^23.16.4
         version: 23.16.4
@@ -74,9 +77,18 @@ importers:
       react-joyride:
         specifier: ^2.9.3
         version: 2.9.3(@types/react@18.3.23)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react-markdown:
+        specifier: ^9.1.0
+        version: 9.1.0(@types/react@18.3.23)(react@18.3.1)
       react-router-dom:
         specifier: ^7.13.0
         version: 7.13.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      rehype-highlight:
+        specifier: ^7.0.2
+        version: 7.0.2
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
       string-similarity-js:
         specifier: ^2.1.4
         version: 2.1.4
@@ -171,6 +183,9 @@ importers:
       globals:
         specifier: ^16.5.0
         version: 16.5.0
+      husky:
+        specifier: ^9.1.7
+        version: 9.1.7
       iconv-lite:
         specifier: ^0.7.2
         version: 0.7.2
@@ -996,67 +1011,56 @@ packages:
     resolution: {integrity: sha512-+xmiDGGaSfIIOXMzkhJ++Oa0Gwvl9oXUeIiwarsdRXSe27HUIvjbSIpPxvnNsRebsNdUo7uAiQVgBD1hVriwSQ==}
     cpu: [arm]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.44.2':
     resolution: {integrity: sha512-bDHvhzOfORk3wt8yxIra8N4k/N0MnKInCW5OGZaeDYa/hMrdPaJzo7CSkjKZqX4JFUWjUGm88lI6QJLCM7lDrA==}
     cpu: [arm]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.44.2':
     resolution: {integrity: sha512-NMsDEsDiYghTbeZWEGnNi4F0hSbGnsuOG+VnNvxkKg0IGDvFh7UVpM/14mnMwxRxUf9AdAVJgHPvKXf6FpMB7A==}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.44.2':
     resolution: {integrity: sha512-lb5bxXnxXglVq+7imxykIp5xMq+idehfl+wOgiiix0191av84OqbjUED+PRC5OA8eFJYj5xAGcpAZ0pF2MnW+A==}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-loongarch64-gnu@4.44.2':
     resolution: {integrity: sha512-Yl5Rdpf9pIc4GW1PmkUGHdMtbx0fBLE1//SxDmuf3X0dUC57+zMepow2LK0V21661cjXdTn8hO2tXDdAWAqE5g==}
     cpu: [loong64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-powerpc64le-gnu@4.44.2':
     resolution: {integrity: sha512-03vUDH+w55s680YYryyr78jsO1RWU9ocRMaeV2vMniJJW/6HhoTBwyyiiTPVHNWLnhsnwcQ0oH3S9JSBEKuyqw==}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-gnu@4.44.2':
     resolution: {integrity: sha512-iYtAqBg5eEMG4dEfVlkqo05xMOk6y/JXIToRca2bAWuqjrJYJlx/I7+Z+4hSrsWU8GdJDFPL4ktV3dy4yBSrzg==}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.44.2':
     resolution: {integrity: sha512-e6vEbgaaqz2yEHqtkPXa28fFuBGmUJ0N2dOJK8YUfijejInt9gfCSA7YDdJ4nYlv67JfP3+PSWFX4IVw/xRIPg==}
     cpu: [riscv64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.44.2':
     resolution: {integrity: sha512-evFOtkmVdY3udE+0QKrV5wBx7bKI0iHz5yEVx5WqDJkxp9YQefy4Mpx3RajIVcM6o7jxTvVd/qpC1IXUhGc1Mw==}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.44.2':
     resolution: {integrity: sha512-/bXb0bEsWMyEkIsUL2Yt5nFB5naLAwyOWMEviQfQY1x3l5WsLKgvZf66TM7UTfED6erckUVUJQ/jJ1FSpm3pRQ==}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.44.2':
     resolution: {integrity: sha512-3D3OB1vSSBXmkGEZR27uiMRNiwN08/RVAcBKwhUYPaiZ8bcvdeEwWPvbnXvvXHY+A/7xluzcN+kaiOFNiOZwWg==}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-win32-arm64-msvc@4.44.2':
     resolution: {integrity: sha512-VfU0fsMK+rwdK8mwODqYeM2hDrF2WiHaSmCBrS7gColkQft95/8tphyzv2EupVxn3iE0FI78wzffoULH1G+dkw==}
@@ -1087,25 +1091,21 @@ packages:
     resolution: {integrity: sha512-eQfcsaxhFrv5FmtaA7+O1F9/2yFDNIoPZzV/ZvqvFz5bBXVc4FAm/1fVpBg8Po/kX1h0chBc7Xkpry3cabFW8w==}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@rspack/binding-linux-arm64-musl@1.7.6':
     resolution: {integrity: sha512-DfQXKiyPIl7i1yECHy4eAkSmlUzzsSAbOjgMuKn7pudsWf483jg0UUYutNgXSlBjc/QSUp7906Cg8oty9OfwPA==}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@rspack/binding-linux-x64-gnu@1.7.6':
     resolution: {integrity: sha512-NdA+2X3lk2GGrMMnTGyYTzM3pn+zNjaqXqlgKmFBXvjfZqzSsKq3pdD1KHZCd5QHN+Fwvoszj0JFsquEVhE1og==}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@rspack/binding-linux-x64-musl@1.7.6':
     resolution: {integrity: sha512-rEy6MHKob02t/77YNgr6dREyJ0e0tv1X6Xsg8Z5E7rPXead06zefUbfazj4RELYySWnM38ovZyJAkPx/gOn3VA==}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@rspack/binding-wasm32-wasi@1.7.6':
     resolution: {integrity: sha512-YupOrz0daSG+YBbCIgpDgzfMM38YpChv+afZpaxx5Ml7xPeAZIIdgWmLHnQ2rts73N2M1NspAiBwV00Xx0N4Vg==}
@@ -1221,6 +1221,9 @@ packages:
   '@types/crypto-js@4.2.2':
     resolution: {integrity: sha512-sDOLlVbHhXpAUAL0YHDUUwDZf3iN4Bwi4W6a0W0b+QcAezUbRtH4FVb+9J4h+XFPW7l/gQ9F8qC7P+Ec4k8QVQ==}
 
+  '@types/debug@4.1.12':
+    resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
+
   '@types/deep-eql@4.0.2':
     resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
 
@@ -1230,6 +1233,9 @@ packages:
   '@types/eslint@9.6.1':
     resolution: {integrity: sha512-FXx2pKgId/WyYo2jXw63kk7/+TY7u7AziEJxJAnSFzHlqTAS3Ync6SvgYAN/k4/PQpnnVuzoMuVnByKK2qp0ag==}
 
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
@@ -1248,6 +1254,9 @@ packages:
   '@types/har-format@1.2.16':
     resolution: {integrity: sha512-fluxdy7ryD3MV6h8pTfTYpy/xQzCFC7m89nOH9y94cNqJ1mDIDPut7MnRHI3F6qRmh/cT2fUjG1MLdCNb4hE9A==}
 
+  '@types/hast@3.0.4':
+    resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+
   '@types/http-errors@2.0.5':
     resolution: {integrity: sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==}
 
@@ -1260,9 +1269,15 @@ packages:
   '@types/luxon@3.7.1':
     resolution: {integrity: sha512-H3iskjFIAn5SlJU7OuxUmTEpebK6TKB8rxZShDslBMZJ5u9S//KM1sbdAisiSrqwLQncVjnpi2OK2J51h+4lsg==}
 
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
   '@types/mime@1.3.5':
     resolution: {integrity: sha512-/pyBZWSLD2n0dcHE3hq8s8ZvcETHtEuF+3E7XVt0Ig2nvsVQXdghHVcEkIWjy9A0wKfTn97a/PSDYohKIlnP/w==}
 
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
   '@types/node-forge@1.3.14':
     resolution: {integrity: sha512-mhVF2BnD4BO+jtOp7z1CdzaK4mbuK0LLQYAvdOLqHTavxFNq4zA1EmYkpnFjP8HOUzedfQkRnp0E2ulSAYSzAw==}
 
@@ -1316,6 +1331,12 @@ packages:
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
@@ -1378,6 +1399,9 @@ packages:
     resolution: {integrity: sha512-uk574k8IU0rOF/AjniX8qbLSGURJVUCeM5e4MIMKBFFi8weeiLrG1fyQejyLXQpRZbU/1BuQasleV/RfHC3hHg==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
+  '@ungap/structured-clone@1.3.0':
+    resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
+
   '@unocss/astro@66.5.4':
     resolution: {integrity: sha512-6KsilC1SiTBmEJRMuPl+Mg8KDWB1+DaVoirGZR7BAEtMf2NzrfQcR4+O/3DHtzb38pfb0K1aHCfWwCozHxLlfA==}
     peerDependencies:
@@ -1716,6 +1740,9 @@ packages:
   b-validate@1.5.3:
     resolution: {integrity: sha512-iCvCkGFskbaYtfQ0a3GmcQCHl/Sv1GufXFGuUQ+FE+WJa7A/espLOuFIn09B944V8/ImPj71T4+rTASxO2PAuA==}
 
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
   balanced-match@1.0.2:
     resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
 
@@ -1804,6 +1831,9 @@ packages:
   caniuse-lite@1.0.30001727:
     resolution: {integrity: sha512-pB68nIHmbN6L/4C6MH1DokyR3bYqFwjaSs/sWDHGj4CTcFtQUQMuJftVwWkXq7mNWOybD3KhUv3oWHoGxgP14Q==}
 
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
   chai@6.2.2:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
@@ -1812,6 +1842,18 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
   chardet@2.1.1:
     resolution: {integrity: sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==}
 
@@ -1848,6 +1890,9 @@ packages:
   colorette@2.0.20:
     resolution: {integrity: sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==}
 
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
   commander@2.20.3:
     resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
 
@@ -2012,6 +2057,9 @@ packages:
   decimal.js@10.5.0:
     resolution: {integrity: sha512-8vDa8Qxvr/+d94hSh5P3IJwI5t8/c0KsMp+g8bNw9cY2icONa5aPfvKeieW1WlG0WQYwwhJ7mjui2xtiePQSXw==}
 
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
   deep-diff@1.0.2:
     resolution: {integrity: sha512-aWS3UIVH+NPGCD1kki+DCU9Dua032iSsO43LqQpcs4R3+dVv7tX0qBGjiVHJHjplsoUM2XRO/KB92glqc68awg==}
 
@@ -2070,6 +2118,9 @@ packages:
   detect-node@2.1.0:
     resolution: {integrity: sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==}
 
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
   dexie@4.0.10:
     resolution: {integrity: sha512-eM2RzuR3i+M046r2Q0Optl3pS31qTWf8aFuA7H9wnsHTwl8EPvroVLwvQene/6paAs39Tbk6fWZcn2aZaHkc/w==}
 
@@ -2195,6 +2246,10 @@ packages:
     resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
     engines: {node: '>=10'}
 
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
   eslint-config-prettier@10.1.8:
     resolution: {integrity: sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==}
     hasBin: true
@@ -2282,6 +2337,9 @@ packages:
     resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
     engines: {node: '>=4.0'}
 
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
   estree-walker@3.0.3:
     resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
 
@@ -2318,6 +2376,9 @@ packages:
   exsolve@1.0.7:
     resolution: {integrity: sha512-VO5fQUzZtI6C+vx4w/4BWJpg3s/5l+6pRQEHzFRM8WFi4XffSP1Z+4qi7GbjWbvRQEbdIco5mIMq+zX4rPuLrw==}
 
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
@@ -2548,6 +2609,22 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
+  hast-util-is-element@3.0.0:
+    resolution: {integrity: sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==}
+
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
+  hast-util-to-text@4.0.2:
+    resolution: {integrity: sha512-KK6y/BN8lbaq654j7JgBydev7wuNMcID54lkRav1P0CaE1e47P72AWWPiGKXTJU271ooYzcvTAn/Zt0REnvc7A==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  highlight.js@11.11.1:
+    resolution: {integrity: sha512-Xwwo44whKBVCYoliBQwaPvtd/2tYFkRQtXDWj1nackaV2JPXx3L0+Jvd8/qCJ2p+ML0/XVkJ2q+Mr+UVdpJK5w==}
+    engines: {node: '>=12.0.0'}
+
   hot-patcher@2.0.1:
     resolution: {integrity: sha512-ECg1JFG0YzehicQaogenlcs2qg6WsXQsxtnbr1i696u5tLUjtJdQAh0u2g0Q5YV45f263Ta1GnUJsc8WIfJf4Q==}
 
@@ -2564,6 +2641,9 @@ packages:
   html-parse-stringify@3.0.1:
     resolution: {integrity: sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==}
 
+  html-url-attributes@3.0.1:
+    resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
+
   http-deceiver@1.2.7:
     resolution: {integrity: sha512-LmpOGxTfbpgtGVxJrj5k7asXHCgNZp5nLfp+hWc8QQRqtb7fUy6kRY3BO1h9ddF6yIPYUARgxGOwB42DnxIaNw==}
 
@@ -2599,6 +2679,11 @@ packages:
     resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
     engines: {node: '>= 14'}
 
+  husky@9.1.7:
+    resolution: {integrity: sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   hyperdyperid@1.2.0:
     resolution: {integrity: sha512-Y93lCzHYgGWdrJ66yIktxiaGULYc6oGiABxhcO5AufBeOyoIdZF7bIfLaOrbM0iGIOXQQgxxRrFEnb+Y6w1n4A==}
     engines: {node: '>=10.18'}
@@ -2651,6 +2736,9 @@ packages:
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
   internal-slot@1.1.0:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
@@ -2663,6 +2751,12 @@ packages:
     resolution: {integrity: sha512-Zv/pA+ciVFbCSBBjGfaKUya/CcGmUHzTydLMaTwrUUEM2DIEO3iZvueGxmacvmN50fGpGVKeTXpb2LcYQxeVdg==}
     engines: {node: '>= 10'}
 
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
   is-array-buffer@3.0.5:
     resolution: {integrity: sha512-DDfANUiiG2wC1qawP66qlTugJeL5HyzMpfr8lLK+jMQirGzNod0B12cFB/9q838Ru27sBwfw78/rdoU7RERz6A==}
     engines: {node: '>= 0.4'}
@@ -2708,6 +2802,9 @@ packages:
     resolution: {integrity: sha512-PwwhEakHVKTdRNVOw+/Gyh0+MzlCl4R6qKvkhuvLtPMggI1WAHt9sOwZxQLSGpUaDnrdyDsomoRgNnCfKNSXXg==}
     engines: {node: '>= 0.4'}
 
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
   is-docker@3.0.0:
     resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -2729,6 +2826,9 @@ packages:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
 
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
   is-inside-container@1.0.0:
     resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
     engines: {node: '>=14.16'}
@@ -2760,6 +2860,10 @@ packages:
     resolution: {integrity: sha512-gwsOE28k+23GP1B6vFl1oVh/WOzmawBrKwo5Ev6wMKzPkaXaCDIQKzLnvsA42DRlbVTWorkgTKIviAKCWkfUwA==}
     engines: {node: '>=10'}
 
+  is-plain-obj@4.1.0:
+    resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
+    engines: {node: '>=12'}
+
   is-potential-custom-element-name@1.0.1:
     resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==}
 
@@ -2941,10 +3045,16 @@ packages:
   lodash@4.17.21:
     resolution: {integrity: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==}
 
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
   loose-envify@1.4.0:
     resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
     hasBin: true
 
+  lowlight@3.3.0:
+    resolution: {integrity: sha512-0JNhgFoPvP6U6lE/UdVsSq99tn6DhjjpAj5MxG49ewd2mOBVtwWYIT8ClyABhq198aXXODMU6Ox8DrGy/CpTZQ==}
+
   lru-cache@10.4.3:
     resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
 
@@ -2969,6 +3079,9 @@ packages:
   make-error@1.3.6:
     resolution: {integrity: sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==}
 
+  markdown-table@3.0.4:
+    resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
@@ -2976,6 +3089,51 @@ packages:
   md5@2.3.0:
     resolution: {integrity: sha512-T1GITYmFaKuO91vxyoQMFETst+O71VUPEU3ze5GNzDm0OWdP8v1ziTaAEPUr/3kLsY3Sftgz242A1SetQiDL7g==}
 
+  mdast-util-find-and-replace@3.0.2:
+    resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
+
+  mdast-util-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
+
+  mdast-util-gfm-table@2.0.0:
+    resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
+
+  mdast-util-gfm@3.1.0:
+    resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
+
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
   mdn-data@2.12.2:
     resolution: {integrity: sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==}
 
@@ -3002,6 +3160,90 @@ packages:
     resolution: {integrity: sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==}
     engines: {node: '>= 0.6'}
 
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
+
+  micromark-extension-gfm-table@2.1.1:
+    resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
+
+  micromark-extension-gfm@3.0.0:
+    resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
   micromatch@4.0.8:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
@@ -3209,6 +3451,9 @@ packages:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
 
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
   parse-json@5.2.0:
     resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
     engines: {node: '>=8'}
@@ -3329,6 +3574,9 @@ packages:
   prop-types@15.8.1:
     resolution: {integrity: sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg==}
 
+  property-information@7.1.0:
+    resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==}
+
   protocol-buffers-schema@3.6.0:
     resolution: {integrity: sha512-TdDRD+/QNdrCGCE7v8340QyuXd4kIWIgapsE2+n/SaGiSSbomYl4TjHlvIoCWRpE7wFt02EpB35VVA2ImcBVqw==}
 
@@ -3440,6 +3688,12 @@ packages:
       react: 15 - 18
       react-dom: 15 - 18
 
+  react-markdown@9.1.0:
+    resolution: {integrity: sha512-xaijuJB0kzGiUdG7nc2MOMDUDBWPyGAjZtUrow9XxUeua8IqeP+VlIfAZ3bphpcLTnSZXz6z9jcVC/TCwbfgdw==}
+    peerDependencies:
+      '@types/react': '>=18'
+      react: '>=18'
+
   react-router-dom@7.13.0:
     resolution: {integrity: sha512-5CO/l5Yahi2SKC6rGZ+HDEjpjkGaG/ncEP7eWFTvFxbHP8yeeI0PxTDjimtpXYlR3b3i9/WIL4VJttPrESIf2g==}
     engines: {node: '>=20.0.0'}
@@ -3490,6 +3744,21 @@ packages:
     resolution: {integrity: sha512-vqlC04+RQoFalODCbCumG2xIOvapzVMHwsyIGM/SIE8fRhFFsXeH8/QQ+s0T0kDAhKc4k30s73/0ydkHQz6HlQ==}
     engines: {node: '>= 0.4'}
 
+  rehype-highlight@7.0.2:
+    resolution: {integrity: sha512-k158pK7wdC2qL3M5NcZROZ2tR/l7zOzjxXd5VGdcfIyoijjQqpHd3JKtYSBDpDZ38UI2WJWuFAtkMDxmx5kstA==}
+
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
   require-from-string@2.0.2:
     resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
     engines: {node: '>=0.10.0'}
@@ -3693,6 +3962,9 @@ packages:
     resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
     engines: {node: '>=0.10.0'}
 
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
   spdy-transport@3.0.0:
     resolution: {integrity: sha512-hsLVFE5SjA6TCisWeJXFKniGGOpBgMLmerfO2aCyCU5s7nJ/rpAepqmFifv/GCbSbueEeAJJnmSQ2rKC/g8Fcw==}
 
@@ -3742,6 +4014,9 @@ packages:
   string_decoder@1.3.0:
     resolution: {integrity: sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==}
 
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
   strip-indent@3.0.0:
     resolution: {integrity: sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==}
     engines: {node: '>=8'}
@@ -3753,6 +4028,12 @@ packages:
   strnum@2.1.2:
     resolution: {integrity: sha512-l63NF9y/cLROq/yqKXSLtcMeeyOfnSQlfMSlzFt/K73oIaD8DGaQWd7Z34X9GPiKqP5rbSh84Hl4bOlLcjiSrQ==}
 
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
   supports-color@7.2.0:
     resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
     engines: {node: '>=8'}
@@ -3867,6 +4148,12 @@ packages:
     peerDependencies:
       tslib: '2'
 
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
   ts-api-utils@2.1.0:
     resolution: {integrity: sha512-CUgTZL1irw8u29bzrOD/nH85jqyc74D6SshFgujOIA7osm2Rz7dYH77agkx7H4FBNxDq7Cjf+IjaX/8zwFW+ZQ==}
     engines: {node: '>=18.12'}
@@ -3951,6 +4238,27 @@ packages:
   undici-types@6.21.0:
     resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
 
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-find-after@5.0.0:
+    resolution: {integrity: sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
   unocss@66.5.4:
     resolution: {integrity: sha512-yNajR8ADgvOzLhDkMKAXVE/SHM4sDrtVhhCnhBjiUMOR0LHIYO7cqunJJudbccrsfJbRTn/odSTBGu9f2IaXOg==}
     engines: {node: '>=14'}
@@ -4029,6 +4337,12 @@ packages:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
 
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
   vite@7.0.2:
     resolution: {integrity: sha512-hxdyZDY1CM6SNpKI4w4lcUc3Mtkd9ej4ECWVHSMrOdSinVc2zYOAppHeGc/hzmRo3pxM5blMzkuWHOJA/3NiFw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -4279,6 +4593,9 @@ packages:
     resolution: {integrity: sha512-EkXc2JGcKhO5N5aZ7TmuNo45budRaFGHOmz24wtJR7znbNqDPmdZtUauKX6et8KAVseAMBOyWJqEpXcHTBsh7Q==}
     engines: {node: '>= 6'}
 
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
 snapshots:
 
   '@adobe/css-tools@4.4.3': {}
@@ -5166,6 +5483,10 @@ snapshots:
 
   '@types/crypto-js@4.2.2': {}
 
+  '@types/debug@4.1.12':
+    dependencies:
+      '@types/ms': 2.1.0
+
   '@types/deep-eql@4.0.2': {}
 
   '@types/eslint-scope@3.7.7':
@@ -5180,6 +5501,10 @@ snapshots:
       '@types/json-schema': 7.0.15
     optional: true
 
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.8
+
   '@types/estree@1.0.8': {}
 
   '@types/express-serve-static-core@4.19.8':
@@ -5204,6 +5529,10 @@ snapshots:
 
   '@types/har-format@1.2.16': {}
 
+  '@types/hast@3.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
   '@types/http-errors@2.0.5': {}
 
   '@types/http-proxy@1.17.17':
@@ -5214,8 +5543,14 @@ snapshots:
 
   '@types/luxon@3.7.1': {}
 
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
   '@types/mime@1.3.5': {}
 
+  '@types/ms@2.1.0': {}
+
   '@types/node-forge@1.3.14':
     dependencies:
       '@types/node': 22.16.2
@@ -5275,6 +5610,10 @@ snapshots:
   '@types/trusted-types@2.0.7':
     optional: true
 
+  '@types/unist@2.0.11': {}
+
+  '@types/unist@3.0.3': {}
+
   '@types/ws@8.18.1':
     dependencies:
       '@types/node': 22.16.2
@@ -5372,6 +5711,8 @@ snapshots:
       '@typescript-eslint/types': 8.46.3
       eslint-visitor-keys: 4.2.1
 
+  '@ungap/structured-clone@1.3.0': {}
+
   '@unocss/astro@66.5.4(vite@7.0.2(@types/node@22.16.0)(jiti@2.6.1)(terser@5.43.1)(tsx@4.19.2)(yaml@2.8.1))':
     dependencies:
       '@unocss/core': 66.5.4
@@ -5865,6 +6206,8 @@ snapshots:
 
   b-validate@1.5.3: {}
 
+  bail@2.0.2: {}
+
   balanced-match@1.0.2: {}
 
   base-64@1.0.0: {}
@@ -5969,6 +6312,8 @@ snapshots:
 
   caniuse-lite@1.0.30001727: {}
 
+  ccount@2.0.1: {}
+
   chai@6.2.2: {}
 
   chalk@4.1.2:
@@ -5976,6 +6321,14 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
   chardet@2.1.1: {}
 
   charenc@0.0.2: {}
@@ -6019,6 +6372,8 @@ snapshots:
 
   colorette@2.0.20: {}
 
+  comma-separated-tokens@2.0.3: {}
+
   commander@2.20.3: {}
 
   commander@7.2.0: {}
@@ -6172,6 +6527,10 @@ snapshots:
 
   decimal.js@10.5.0: {}
 
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
   deep-diff@1.0.2: {}
 
   deep-is@0.1.4: {}
@@ -6215,6 +6574,10 @@ snapshots:
 
   detect-node@2.1.0: {}
 
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
   dexie@4.0.10: {}
 
   diff@4.0.2: {}
@@ -6440,6 +6803,8 @@ snapshots:
 
   escape-string-regexp@4.0.0: {}
 
+  escape-string-regexp@5.0.0: {}
+
   eslint-config-prettier@10.1.8(eslint@9.39.2(jiti@2.6.1)):
     dependencies:
       eslint: 9.39.2(jiti@2.6.1)
@@ -6562,6 +6927,8 @@ snapshots:
 
   estraverse@5.3.0: {}
 
+  estree-util-is-identifier-name@3.0.0: {}
+
   estree-walker@3.0.3:
     dependencies:
       '@types/estree': 1.0.8
@@ -6619,6 +6986,8 @@ snapshots:
 
   exsolve@1.0.7: {}
 
+  extend@3.0.2: {}
+
   fast-deep-equal@3.1.3: {}
 
   fast-diff@1.3.0: {}
@@ -6850,6 +7219,43 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
+  hast-util-is-element@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  hast-util-to-text@4.0.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      hast-util-is-element: 3.0.0
+      unist-util-find-after: 5.0.0
+
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  highlight.js@11.11.1: {}
+
   hot-patcher@2.0.1: {}
 
   hpack.js@2.1.6:
@@ -6869,6 +7275,8 @@ snapshots:
     dependencies:
       void-elements: 3.1.0
 
+  html-url-attributes@3.0.1: {}
+
   http-deceiver@1.2.7: {}
 
   http-errors@1.8.1:
@@ -6923,6 +7331,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  husky@9.1.7: {}
+
   hyperdyperid@1.2.0: {}
 
   i18next@23.16.4:
@@ -6965,6 +7375,8 @@ snapshots:
 
   inherits@2.0.4: {}
 
+  inline-style-parser@0.2.7: {}
+
   internal-slot@1.1.0:
     dependencies:
       es-errors: 1.3.0
@@ -6975,6 +7387,13 @@ snapshots:
 
   ipaddr.js@2.3.0: {}
 
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
   is-array-buffer@3.0.5:
     dependencies:
       call-bind: 1.0.8
@@ -7021,6 +7440,8 @@ snapshots:
       call-bound: 1.0.3
       has-tostringtag: 1.0.2
 
+  is-decimal@2.0.1: {}
+
   is-docker@3.0.0: {}
 
   is-extglob@2.1.1: {}
@@ -7037,6 +7458,8 @@ snapshots:
     dependencies:
       is-extglob: 2.1.1
 
+  is-hexadecimal@2.0.1: {}
+
   is-inside-container@1.0.0:
     dependencies:
       is-docker: 3.0.0
@@ -7058,6 +7481,8 @@ snapshots:
 
   is-plain-obj@3.0.0: {}
 
+  is-plain-obj@4.1.0: {}
+
   is-potential-custom-element-name@1.0.1: {}
 
   is-regex@1.2.1:
@@ -7256,10 +7681,18 @@ snapshots:
 
   lodash@4.17.21: {}
 
+  longest-streak@3.1.0: {}
+
   loose-envify@1.4.0:
     dependencies:
       js-tokens: 4.0.0
 
+  lowlight@3.3.0:
+    dependencies:
+      '@types/hast': 3.0.4
+      devlop: 1.1.0
+      highlight.js: 11.11.1
+
   lru-cache@10.4.3: {}
 
   luxon@3.7.2: {}
@@ -7282,6 +7715,8 @@ snapshots:
 
   make-error@1.3.6: {}
 
+  markdown-table@3.0.4: {}
+
   math-intrinsics@1.1.0: {}
 
   md5@2.3.0:
@@ -7290,6 +7725,159 @@ snapshots:
       crypt: 0.0.2
       is-buffer: 1.1.6
 
+  mdast-util-find-and-replace@3.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      escape-string-regexp: 5.0.0
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-find-and-replace: 3.0.2
+      micromark-util-character: 2.1.1
+
+  mdast-util-gfm-footnote@2.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-util-normalize-identifier: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-table@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      markdown-table: 3.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm@3.1.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-footnote: 2.1.0
+      mdast-util-gfm-strikethrough: 2.0.0
+      mdast-util-gfm-table: 2.0.0
+      mdast-util-gfm-task-list-item: 2.0.0
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.0
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
   mdn-data@2.12.2: {}
 
   media-typer@0.3.0: {}
@@ -7320,6 +7908,197 @@ snapshots:
 
   methods@1.1.2: {}
 
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-table@2.1.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm@3.0.0:
+    dependencies:
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-strikethrough: 2.1.0
+      micromark-extension-gfm-table: 2.1.1
+      micromark-extension-gfm-tagfilter: 2.0.0
+      micromark-extension-gfm-task-list-item: 2.1.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.12
+      debug: 4.4.1
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
   micromatch@4.0.8:
     dependencies:
       braces: 3.0.3
@@ -7514,6 +8293,16 @@ snapshots:
     dependencies:
       callsites: 3.1.0
 
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
   parse-json@5.2.0:
     dependencies:
       '@babel/code-frame': 7.27.1
@@ -7620,6 +8409,8 @@ snapshots:
       object-assign: 4.1.1
       react-is: 16.13.1
 
+  property-information@7.1.0: {}
+
   protocol-buffers-schema@3.6.0: {}
 
   proxy-addr@2.0.7:
@@ -7738,6 +8529,24 @@ snapshots:
     transitivePeerDependencies:
       - '@types/react'
 
+  react-markdown@9.1.0(@types/react@18.3.23)(react@18.3.1):
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/react': 18.3.23
+      devlop: 1.1.0
+      hast-util-to-jsx-runtime: 2.3.6
+      html-url-attributes: 3.0.1
+      mdast-util-to-hast: 13.2.1
+      react: 18.3.1
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
   react-router-dom@7.13.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
     dependencies:
       react: 18.3.1
@@ -7808,6 +8617,48 @@ snapshots:
       es-errors: 1.3.0
       set-function-name: 2.0.2
 
+  rehype-highlight@7.0.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      hast-util-to-text: 4.0.2
+      lowlight: 3.3.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
   require-from-string@2.0.2: {}
 
   requires-port@1.0.0: {}
@@ -8078,6 +8929,8 @@ snapshots:
   source-map@0.6.1:
     optional: true
 
+  space-separated-tokens@2.0.2: {}
+
   spdy-transport@3.0.0:
     dependencies:
       debug: 4.4.1
@@ -8161,6 +9014,11 @@ snapshots:
     dependencies:
       safe-buffer: 5.2.1
 
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
   strip-indent@3.0.0:
     dependencies:
       min-indent: 1.0.1
@@ -8169,6 +9027,14 @@ snapshots:
 
   strnum@2.1.2: {}
 
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
   supports-color@7.2.0:
     dependencies:
       has-flag: 4.0.0
@@ -8270,6 +9136,10 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
   ts-api-utils@2.1.0(typescript@5.9.3):
     dependencies:
       typescript: 5.9.3
@@ -8379,6 +9249,44 @@ snapshots:
 
   undici-types@6.21.0: {}
 
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-find-after@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
   unocss@66.5.4(postcss@8.5.6)(vite@7.0.2(@types/node@22.16.0)(jiti@2.6.1)(terser@5.43.1)(tsx@4.19.2)(yaml@2.8.1)):
     dependencies:
       '@unocss/astro': 66.5.4(vite@7.0.2(@types/node@22.16.0)(jiti@2.6.1)(terser@5.43.1)(tsx@4.19.2)(yaml@2.8.1))
@@ -8457,6 +9365,16 @@ snapshots:
 
   vary@1.1.2: {}
 
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
   vite@7.0.2(@types/node@22.16.0)(jiti@2.6.1)(terser@5.43.1)(tsx@4.19.2)(yaml@2.8.1):
     dependencies:
       esbuild: 0.25.5
@@ -8749,3 +9667,5 @@ snapshots:
       archiver-utils: 2.1.0
       compress-commons: 2.1.1
       readable-stream: 3.6.2
+
+  zwitch@2.0.4: {}
diff --git a/rspack.config.ts b/rspack.config.ts
index fff70db2a..8c3abbeec 100644
--- a/rspack.config.ts
+++ b/rspack.config.ts
@@ -2,6 +2,7 @@ import * as path from "path";
 import { rspack, NormalModule, type Configuration } from "@rspack/core";
 import { readFileSync } from "fs";
 import { v4 as uuidv4 } from "uuid";
+import { toChromeVersion } from "./scripts/version.js";
 
 const pkg = JSON.parse(readFileSync("./package.json", "utf-8"));
 
@@ -137,6 +138,7 @@ export default {
           // 将manifest.json内版本号替换为package.json中版本号
           transform(content: Buffer) {
             const manifest = JSON.parse(content.toString()) as chrome.runtime.ManifestV3;
+            manifest.version = toChromeVersion(version);
             if (isDev || isBeta) {
               manifest.name = "__MSG_scriptcat_beta__";
             }
diff --git a/scripts/pack.js b/scripts/pack.js
index 26d0f79a2..23ecfb393 100644
--- a/scripts/pack.js
+++ b/scripts/pack.js
@@ -7,6 +7,7 @@ import { execSync } from "child_process";
 import manifest from "../src/manifest.json" with { type: "json" };
 import packageInfo from "../package.json" with { type: "json" };
 import semver from "semver";
+import { toChromeVersion } from "./version.js";
 
 // ============================================================================
 
@@ -26,26 +27,11 @@ const createJSZip = () => {
 
 // 判断是否为beta版本
 const version = semver.parse(packageInfo.version);
+manifest.version = toChromeVersion(packageInfo.version);
 if (version.prerelease.length) {
-  // 替换manifest中的版本
-  let betaVersion = 1000;
-  switch (version.prerelease[0]) {
-    case "alpha":
-      // 第一位进1
-      betaVersion += parseInt(version.prerelease[1] || "0", 10) + 1 || 1;
-      break;
-    case "beta":
-      // 第三位进1
-      betaVersion += 100 * (parseInt(version.prerelease[1] || "0", 10) + 1 || 1);
-      break;
-    default:
-      throw new Error("未知的版本类型");
-  }
-  manifest.version = `${version.major}.${version.minor}.${version.patch}.${betaVersion}`;
   manifest.name = `__MSG_scriptcat_beta__`;
 } else {
   manifest.name = `__MSG_scriptcat__`;
-  manifest.version = packageInfo.version;
 }
 
 // 处理manifest version
diff --git a/scripts/version.js b/scripts/version.js
new file mode 100644
index 000000000..e3bbfdeef
--- /dev/null
+++ b/scripts/version.js
@@ -0,0 +1,25 @@
+import semver from "semver";
+
+/**
+ * 将 prerelease 版本号转换为 Chrome 兼容的纯数字格式
+ * 例如: "1.4.0-beta" -> "1.4.0.1100", "1.4.0-alpha.1" -> "1.4.0.1002"
+ * 非 prerelease 版本原样返回
+ */
+export function toChromeVersion(ver) {
+  const parsed = semver.parse(ver);
+  if (!parsed || !parsed.prerelease.length) {
+    return ver;
+  }
+  let betaVersion = 1000;
+  switch (parsed.prerelease[0]) {
+    case "alpha":
+      betaVersion += parseInt(parsed.prerelease[1] || "0", 10) + 1 || 1;
+      break;
+    case "beta":
+      betaVersion += 100 * (parseInt(parsed.prerelease[1] || "0", 10) + 1 || 1);
+      break;
+    default:
+      throw new Error("未知的版本类型");
+  }
+  return `${parsed.major}.${parsed.minor}.${parsed.patch}.${betaVersion}`;
+}
diff --git a/src/app/cache_key.ts b/src/app/cache_key.ts
index 74d3874af..7ae718b87 100644
--- a/src/app/cache_key.ts
+++ b/src/app/cache_key.ts
@@ -4,3 +4,5 @@ export const CACHE_KEY_SCRIPT_INFO = "scriptInfo:"; // 加载脚本信息时的
 export const CACHE_KEY_FAVICON = "favicon:";
 export const CACHE_KEY_SET_VALUE = "setValue:";
 export const CACHE_KEY_PERMISSION = "permission:";
+export const CACHE_KEY_CATTOOL_INSTALL = "cattoolInstall:"; // CATTool 待安装代码缓存
+export const CACHE_KEY_SKILL_INSTALL = "skillInstall:"; // Skill ZIP 待安装数据缓存
diff --git a/src/app/repo/agent_chat.test.ts b/src/app/repo/agent_chat.test.ts
new file mode 100644
index 000000000..040bdaf38
--- /dev/null
+++ b/src/app/repo/agent_chat.test.ts
@@ -0,0 +1,203 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { AgentChatRepo } from "./agent_chat";
+
+// Mock OPFS 文件系统
+function createMockOPFS() {
+  function createMockWritable() {
+    let data: any = null;
+    return {
+      write: vi.fn(async (content: any) => {
+        data = content;
+      }),
+      close: vi.fn(async () => {}),
+      getData: () => data,
+    };
+  }
+
+  function createMockFileHandle(name: string, dir: Map<string, any>) {
+    return {
+      kind: "file" as const,
+      getFile: vi.fn(async () => {
+        const content = dir.get(name);
+        if (content instanceof Blob) {
+          return content;
+        }
+        return new Blob([typeof content === "string" ? content : ""], { type: "application/octet-stream" });
+      }),
+      createWritable: vi.fn(async () => {
+        const writable = createMockWritable();
+        const origClose = writable.close;
+        writable.close = vi.fn(async () => {
+          const written = writable.getData();
+          if (written instanceof Blob) {
+            dir.set(name, written);
+          } else if (typeof written === "string") {
+            dir.set(name, written);
+          } else {
+            dir.set(name, written);
+          }
+          await origClose();
+        });
+        return writable;
+      }),
+    };
+  }
+
+  function createMockDirHandle(store: Map<string, any>): any {
+    return {
+      kind: "directory" as const,
+      getDirectoryHandle: vi.fn(async (name: string, opts?: { create?: boolean }) => {
+        if (!store.has("__dir__" + name)) {
+          if (opts?.create) {
+            store.set("__dir__" + name, new Map());
+          } else {
+            throw new Error("Not found");
+          }
+        }
+        return createMockDirHandle(store.get("__dir__" + name));
+      }),
+      getFileHandle: vi.fn(async (name: string, opts?: { create?: boolean }) => {
+        if (!store.has(name) && !opts?.create) {
+          throw new Error("Not found");
+        }
+        if (!store.has(name)) {
+          store.set(name, "");
+        }
+        return createMockFileHandle(name, store);
+      }),
+      removeEntry: vi.fn(async (name: string) => {
+        store.delete(name);
+        store.delete("__dir__" + name);
+      }),
+      [Symbol.asyncIterator]: async function* () {
+        for (const [key] of store) {
+          if (!key.startsWith("__dir__")) {
+            yield [key, { kind: "file" }];
+          }
+        }
+      },
+    };
+  }
+
+  const rootStore = new Map<string, any>();
+  const mockRoot = createMockDirHandle(rootStore);
+
+  vi.stubGlobal("navigator", {
+    ...navigator,
+    storage: {
+      getDirectory: vi.fn(async () => mockRoot),
+    },
+  });
+
+  return { rootStore, mockRoot };
+}
+
+describe("AgentChatRepo 附件存储", () => {
+  let repo: AgentChatRepo;
+
+  beforeEach(() => {
+    createMockOPFS();
+    repo = new AgentChatRepo();
+  });
+
+  it("saveAttachment 应保存 data URL 字符串并返回大小", async () => {
+    const dataUrl = "data:image/jpeg;base64,/9j/4AAQSkZJRg==";
+    const size = await repo.saveAttachment("att-1", dataUrl);
+
+    // base64 "/9j/4AAQSkZJRg==" 解码为 10 字节
+    expect(size).toBeGreaterThan(0);
+  });
+
+  it("saveAttachment 应保存 Blob 数据并返回大小", async () => {
+    const blob = new Blob(["hello world"], { type: "text/plain" });
+    const size = await repo.saveAttachment("att-2", blob);
+
+    expect(size).toBe(blob.size);
+  });
+
+  it("getAttachment 应返回已保存的附件", async () => {
+    const blob = new Blob(["test data"], { type: "text/plain" });
+    await repo.saveAttachment("att-3", blob);
+
+    const result = await repo.getAttachment("att-3");
+
+    expect(result).not.toBeNull();
+    expect(result).toBeInstanceOf(Blob);
+  });
+
+  it("getAttachment 不存在的附件应返回 null", async () => {
+    const result = await repo.getAttachment("nonexistent");
+
+    expect(result).toBeNull();
+  });
+
+  it("deleteAttachment 应删除已保存的附件", async () => {
+    const blob = new Blob(["data"], { type: "text/plain" });
+    await repo.saveAttachment("att-4", blob);
+
+    await repo.deleteAttachment("att-4");
+
+    const result = await repo.getAttachment("att-4");
+    expect(result).toBeNull();
+  });
+
+  it("deleteAttachments 应批量删除附件", async () => {
+    await repo.saveAttachment("att-a", new Blob(["a"]));
+    await repo.saveAttachment("att-b", new Blob(["b"]));
+    await repo.saveAttachment("att-c", new Blob(["c"]));
+
+    await repo.deleteAttachments(["att-a", "att-c"]);
+
+    expect(await repo.getAttachment("att-a")).toBeNull();
+    expect(await repo.getAttachment("att-b")).not.toBeNull();
+    expect(await repo.getAttachment("att-c")).toBeNull();
+  });
+
+  it("saveAttachment 纯文本（非 data URL）应作为 octet-stream 存储", async () => {
+    const size = await repo.saveAttachment("att-5", "plain text content");
+    expect(size).toBeGreaterThan(0);
+  });
+
+  it("deleteConversation 应清理关联的附件", async () => {
+    // 先保存会话和消息（含附件）
+    const convId = "conv-1";
+    await repo.saveConversation({
+      id: convId,
+      title: "Test",
+      modelId: "m1",
+      createtime: Date.now(),
+      updatetime: Date.now(),
+    });
+    await repo.saveMessages(convId, [
+      {
+        id: "msg-1",
+        conversationId: convId,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            id: "tc-1",
+            name: "screenshot",
+            arguments: "{}",
+            attachments: [
+              { id: "att-del-1", type: "image", name: "img.jpg", mimeType: "image/jpeg" },
+              { id: "att-del-2", type: "file", name: "file.zip", mimeType: "application/zip" },
+            ],
+          },
+        ],
+        createtime: Date.now(),
+      },
+    ]);
+
+    // 保存附件数据
+    await repo.saveAttachment("att-del-1", new Blob(["img"]));
+    await repo.saveAttachment("att-del-2", new Blob(["zip"]));
+
+    // 删除会话
+    await repo.deleteConversation(convId);
+
+    // 附件应被清理
+    expect(await repo.getAttachment("att-del-1")).toBeNull();
+    expect(await repo.getAttachment("att-del-2")).toBeNull();
+  });
+});
diff --git a/src/app/repo/agent_chat.ts b/src/app/repo/agent_chat.ts
new file mode 100644
index 000000000..46b3de0c1
--- /dev/null
+++ b/src/app/repo/agent_chat.ts
@@ -0,0 +1,166 @@
+import type { Conversation, ChatMessage } from "@App/app/service/agent/types";
+import { OPFSRepo } from "./opfs_repo";
+
+const CONVERSATIONS_FILE = "conversations.json";
+const MESSAGES_DIR = "data";
+const ATTACHMENTS_DIR = "attachments";
+
+// 目录结构：agents/conversations/
+//            agents/conversations/conversations.json       - 会话列表
+//            agents/conversations/data/{id}.json           - 每个会话的消息
+//            agents/conversations/attachments/{id}         - 附件二进制数据
+export class AgentChatRepo extends OPFSRepo {
+  constructor() {
+    super("conversations");
+  }
+
+  // 获取所有会话列表
+  async listConversations(): Promise<Conversation[]> {
+    return this.readJsonFile<Conversation[]>(CONVERSATIONS_FILE, []);
+  }
+
+  // 保存/更新会话
+  async saveConversation(conversation: Conversation): Promise<void> {
+    const conversations = await this.readJsonFile<Conversation[]>(CONVERSATIONS_FILE, []);
+    const index = conversations.findIndex((c) => c.id === conversation.id);
+    if (index >= 0) {
+      conversations[index] = conversation;
+    } else {
+      conversations.unshift(conversation);
+    }
+    await this.writeJsonFile(CONVERSATIONS_FILE, conversations);
+  }
+
+  // 删除会话及其消息和附件
+  async deleteConversation(id: string): Promise<void> {
+    // 清理会话关联的附件
+    const messages = await this.getMessages(id);
+    const attachmentIds: string[] = [];
+    for (const msg of messages) {
+      // 扫描 toolCalls 中的附件
+      if (msg.toolCalls) {
+        for (const tc of msg.toolCalls) {
+          if (tc.attachments) {
+            for (const att of tc.attachments) {
+              attachmentIds.push(att.id);
+            }
+          }
+        }
+      }
+      // 扫描 ContentBlock[] 中的附件
+      if (Array.isArray(msg.content)) {
+        for (const block of msg.content) {
+          if (block.type !== "text" && "attachmentId" in block) {
+            attachmentIds.push(block.attachmentId);
+          }
+        }
+      }
+    }
+    if (attachmentIds.length > 0) {
+      await this.deleteAttachments(attachmentIds);
+    }
+
+    const conversations = await this.readJsonFile<Conversation[]>(CONVERSATIONS_FILE, []);
+    const filtered = conversations.filter((c) => c.id !== id);
+    await this.writeJsonFile(CONVERSATIONS_FILE, filtered);
+    // 删除对应消息文件
+    const messagesDir = await this.getChildDir(MESSAGES_DIR);
+    await this.deleteFile(`${id}.json`, messagesDir);
+  }
+
+  // 获取指定会话的所有消息
+  async getMessages(conversationId: string): Promise<ChatMessage[]> {
+    const messagesDir = await this.getChildDir(MESSAGES_DIR);
+    return this.readJsonFile<ChatMessage[]>(`${conversationId}.json`, [], messagesDir);
+  }
+
+  // 追加消息
+  async appendMessage(message: ChatMessage): Promise<void> {
+    const messagesDir = await this.getChildDir(MESSAGES_DIR);
+    const messages = await this.readJsonFile<ChatMessage[]>(`${message.conversationId}.json`, [], messagesDir);
+    messages.push(message);
+    await this.writeJsonFile(`${message.conversationId}.json`, messages, messagesDir);
+  }
+
+  // 更新消息（按 id 匹配）
+  async updateMessage(message: ChatMessage): Promise<void> {
+    const messagesDir = await this.getChildDir(MESSAGES_DIR);
+    const messages = await this.readJsonFile<ChatMessage[]>(`${message.conversationId}.json`, [], messagesDir);
+    const index = messages.findIndex((m) => m.id === message.id);
+    if (index >= 0) {
+      messages[index] = message;
+      await this.writeJsonFile(`${message.conversationId}.json`, messages, messagesDir);
+    }
+  }
+
+  // 保存整个消息列表（用于批量更新）
+  async saveMessages(conversationId: string, messages: ChatMessage[]): Promise<void> {
+    const messagesDir = await this.getChildDir(MESSAGES_DIR);
+    await this.writeJsonFile(`${conversationId}.json`, messages, messagesDir);
+  }
+
+  // ---- 附件存储 ----
+
+  // 保存附件数据（支持 base64/data URL 字符串或 Blob）
+  async saveAttachment(id: string, data: string | Blob): Promise<number> {
+    const dir = await this.getChildDir(ATTACHMENTS_DIR);
+    const fileHandle = await dir.getFileHandle(id, { create: true });
+    const writable = await fileHandle.createWritable();
+
+    let size: number;
+    if (data instanceof Blob) {
+      await writable.write(data);
+      size = data.size;
+    } else {
+      // 字符串数据（base64/data URL），按原始二进制存储
+      const binary = this.dataUrlToBlob(data);
+      await writable.write(binary);
+      size = binary.size;
+    }
+
+    await writable.close();
+    return size;
+  }
+
+  // 读取附件数据为 Blob
+  async getAttachment(id: string): Promise<Blob | null> {
+    try {
+      const dir = await this.getChildDir(ATTACHMENTS_DIR);
+      const fileHandle = await dir.getFileHandle(id);
+      return await fileHandle.getFile();
+    } catch {
+      return null;
+    }
+  }
+
+  // 删除单个附件
+  async deleteAttachment(id: string): Promise<void> {
+    const dir = await this.getChildDir(ATTACHMENTS_DIR);
+    await this.deleteFile(id, dir);
+  }
+
+  // 删除会话关联的所有附件（需传入附件 ID 列表）
+  async deleteAttachments(ids: string[]): Promise<void> {
+    const dir = await this.getChildDir(ATTACHMENTS_DIR);
+    for (const id of ids) {
+      await this.deleteFile(id, dir);
+    }
+  }
+
+  // 将 data URL 或纯 base64 转换为 Blob
+  private dataUrlToBlob(data: string): Blob {
+    // 匹配 data URL 格式
+    const match = data.match(/^data:([^;]+);base64,(.+)$/s);
+    if (match) {
+      const byteString = atob(match[2]);
+      const ab = new ArrayBuffer(byteString.length);
+      const ia = new Uint8Array(ab);
+      for (let i = 0; i < byteString.length; i++) {
+        ia[i] = byteString.charCodeAt(i);
+      }
+      return new Blob([ab], { type: match[1] });
+    }
+    // 纯文本存储
+    return new Blob([data], { type: "application/octet-stream" });
+  }
+}
diff --git a/src/app/repo/agent_model.ts b/src/app/repo/agent_model.ts
new file mode 100644
index 000000000..3950c8e9a
--- /dev/null
+++ b/src/app/repo/agent_model.ts
@@ -0,0 +1,49 @@
+import type { AgentModelConfig } from "@App/app/service/agent/types";
+import { Repo } from "./repo";
+
+const DEFAULT_MODEL_KEY = "agent_model:__default__";
+
+// 使用 chrome.storage.local 存储 Agent 模型配置
+export class AgentModelRepo extends Repo<AgentModelConfig> {
+  constructor() {
+    super("agent_model:");
+  }
+
+  // 获取所有模型（排除 __default__ 这个存储默认模型 ID 的 key）
+  async listModels(): Promise<AgentModelConfig[]> {
+    return this.find((key) => key !== `${this.prefix}__default__`);
+  }
+
+  // 获取指定模型
+  async getModel(id: string): Promise<AgentModelConfig | undefined> {
+    return this.get(id);
+  }
+
+  // 保存模型
+  async saveModel(model: AgentModelConfig): Promise<void> {
+    await this._save(model.id, model);
+  }
+
+  // 删除模型
+  async removeModel(id: string): Promise<void> {
+    await this.delete(id);
+  }
+
+  // 获取默认模型 ID（独立 key，不复用 Repo<AgentModelConfig> 的 get）
+  async getDefaultModelId(): Promise<string> {
+    return new Promise<string>((resolve) => {
+      chrome.storage.local.get(DEFAULT_MODEL_KEY, (result) => {
+        resolve(result[DEFAULT_MODEL_KEY] || "");
+      });
+    });
+  }
+
+  // 设置默认模型 ID
+  async setDefaultModelId(id: string): Promise<void> {
+    return new Promise<void>((resolve) => {
+      chrome.storage.local.set({ [DEFAULT_MODEL_KEY]: id }, () => {
+        resolve();
+      });
+    });
+  }
+}
diff --git a/src/app/repo/agent_task.test.ts b/src/app/repo/agent_task.test.ts
new file mode 100644
index 000000000..9537c15a2
--- /dev/null
+++ b/src/app/repo/agent_task.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { AgentTaskRepo, AgentTaskRunRepo } from "./agent_task";
+import type { AgentTask, AgentTaskRun } from "@App/app/service/agent/types";
+
+function makeTask(overrides: Partial<AgentTask> = {}): AgentTask {
+  return {
+    id: "task-1",
+    name: "测试任务",
+    crontab: "0 9 * * *",
+    mode: "internal",
+    enabled: true,
+    notify: false,
+    createtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+function makeRun(overrides: Partial<AgentTaskRun> = {}): AgentTaskRun {
+  return {
+    id: "run-1",
+    taskId: "task-1",
+    starttime: Date.now(),
+    status: "running",
+    ...overrides,
+  };
+}
+
+describe.concurrent("AgentTaskRepo", () => {
+  let repo: AgentTaskRepo;
+
+  beforeEach(() => {
+    repo = new AgentTaskRepo();
+  });
+
+  it.concurrent("saveTask / getTask CRUD", async () => {
+    const task = makeTask();
+    await repo.saveTask(task);
+    const result = await repo.getTask("task-1");
+    expect(result).toBeDefined();
+    expect(result!.name).toBe("测试任务");
+  });
+
+  it.concurrent("listTasks 返回所有任务", async () => {
+    await repo.saveTask(makeTask({ id: "t-a", name: "A" }));
+    await repo.saveTask(makeTask({ id: "t-b", name: "B" }));
+    const list = await repo.listTasks();
+    expect(list.length).toBeGreaterThanOrEqual(2);
+    const names = list.map((t) => t.name);
+    expect(names).toContain("A");
+    expect(names).toContain("B");
+  });
+
+  it.concurrent("removeTask 删除任务", async () => {
+    const task = makeTask({ id: "t-del" });
+    await repo.saveTask(task);
+    await repo.removeTask("t-del");
+    const result = await repo.getTask("t-del");
+    expect(result).toBeUndefined();
+  });
+
+  it.concurrent("removeTask 同时清理关联的 runs", async () => {
+    const taskId = "t-clean";
+    await repo.saveTask(makeTask({ id: taskId }));
+    const runRepo = new AgentTaskRunRepo();
+    await runRepo.appendRun(makeRun({ id: "r1", taskId }));
+    await runRepo.appendRun(makeRun({ id: "r2", taskId }));
+
+    await repo.removeTask(taskId);
+
+    const runs = await runRepo.listRuns(taskId);
+    expect(runs).toHaveLength(0);
+  });
+});
+
+describe.concurrent("AgentTaskRunRepo", () => {
+  let repo: AgentTaskRunRepo;
+
+  beforeEach(() => {
+    repo = new AgentTaskRunRepo();
+  });
+
+  it.concurrent("appendRun / listRuns", async () => {
+    const taskId = "task-run-test";
+    await repo.appendRun(makeRun({ id: "r-a", taskId, starttime: 1000 }));
+    await repo.appendRun(makeRun({ id: "r-b", taskId, starttime: 2000 }));
+    await repo.appendRun(makeRun({ id: "r-c", taskId, starttime: 3000 }));
+
+    const runs = await repo.listRuns(taskId);
+    expect(runs.length).toBe(3);
+    // 按 starttime 降序
+    expect(runs[0].id).toBe("r-c");
+    expect(runs[1].id).toBe("r-b");
+    expect(runs[2].id).toBe("r-a");
+  });
+
+  it.concurrent("listRuns 限制返回条数", async () => {
+    const taskId = "task-limit";
+    for (let i = 0; i < 5; i++) {
+      await repo.appendRun(makeRun({ id: `rl-${i}`, taskId, starttime: i * 1000 }));
+    }
+    const runs = await repo.listRuns(taskId, 3);
+    expect(runs.length).toBe(3);
+  });
+
+  it.concurrent("clearRuns 清理指定任务的运行历史", async () => {
+    const taskId = "task-clear";
+    await repo.appendRun(makeRun({ id: "rc-1", taskId }));
+    await repo.appendRun(makeRun({ id: "rc-2", taskId }));
+    // 其他任务的 run 不受影响
+    await repo.appendRun(makeRun({ id: "rc-other", taskId: "other-task" }));
+
+    await repo.clearRuns(taskId);
+
+    const runs = await repo.listRuns(taskId);
+    expect(runs).toHaveLength(0);
+
+    const otherRuns = await repo.listRuns("other-task");
+    expect(otherRuns).toHaveLength(1);
+  });
+
+  it.concurrent("updateRun 更新运行状态", async () => {
+    await repo.appendRun(makeRun({ id: "r-upd", taskId: "t-upd" }));
+    await repo.updateRun("r-upd", { status: "success", endtime: Date.now() });
+    const runs = await repo.listRuns("t-upd");
+    expect(runs[0].status).toBe("success");
+    expect(runs[0].endtime).toBeDefined();
+  });
+});
diff --git a/src/app/repo/agent_task.ts b/src/app/repo/agent_task.ts
new file mode 100644
index 000000000..082c1bf24
--- /dev/null
+++ b/src/app/repo/agent_task.ts
@@ -0,0 +1,56 @@
+import type { AgentTask, AgentTaskRun } from "@App/app/service/agent/types";
+import { Repo } from "./repo";
+
+export class AgentTaskRepo extends Repo<AgentTask> {
+  constructor() {
+    super("agent_task:");
+  }
+
+  async listTasks(): Promise<AgentTask[]> {
+    return this.find();
+  }
+
+  async getTask(id: string): Promise<AgentTask | undefined> {
+    return this.get(id);
+  }
+
+  async saveTask(task: AgentTask): Promise<void> {
+    await this._save(task.id, task);
+  }
+
+  async removeTask(id: string): Promise<void> {
+    await this.delete(id);
+    // 同时清理关联的 runs
+    const runRepo = new AgentTaskRunRepo();
+    await runRepo.clearRuns(id);
+  }
+}
+
+export class AgentTaskRunRepo extends Repo<AgentTaskRun> {
+  constructor() {
+    super("agent_task_run:");
+  }
+
+  async appendRun(run: AgentTaskRun): Promise<void> {
+    await this._save(run.id, run);
+  }
+
+  async updateRun(id: string, data: Partial<AgentTaskRun>): Promise<void> {
+    await this.update(id, data);
+  }
+
+  async listRuns(taskId: string, limit = 50): Promise<AgentTaskRun[]> {
+    const all = await this.find((_key, value) => value.taskId === taskId);
+    // 按 starttime 降序排列
+    all.sort((a, b) => b.starttime - a.starttime);
+    return all.slice(0, limit);
+  }
+
+  async clearRuns(taskId: string): Promise<void> {
+    const all = await this.find((_key, value) => value.taskId === taskId);
+    if (all.length > 0) {
+      const keys = all.map((r) => r.id);
+      await this.deletes(keys);
+    }
+  }
+}
diff --git a/src/app/repo/cattool_repo.test.ts b/src/app/repo/cattool_repo.test.ts
new file mode 100644
index 000000000..d626539fe
--- /dev/null
+++ b/src/app/repo/cattool_repo.test.ts
@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest";
+import { CATToolRepo } from "./cattool_repo";
+
+describe("CATToolRepo.sanitizeName", () => {
+  it("普通名称应保持不变", () => {
+    expect(CATToolRepo.sanitizeName("weather")).toBe("weather");
+    expect(CATToolRepo.sanitizeName("hello_world")).toBe("hello_world");
+    expect(CATToolRepo.sanitizeName("my-tool")).toBe("my-tool");
+  });
+
+  it("应过滤正斜杠", () => {
+    expect(CATToolRepo.sanitizeName("a/b")).toBe("a_b");
+  });
+
+  it("应过滤反斜杠", () => {
+    expect(CATToolRepo.sanitizeName("a\\b")).toBe("a_b");
+  });
+
+  it("应过滤点号防止路径穿越", () => {
+    expect(CATToolRepo.sanitizeName("..")).toBe("__");
+    expect(CATToolRepo.sanitizeName("../..")).toBe("_____");
+    expect(CATToolRepo.sanitizeName("a.b")).toBe("a_b");
+  });
+
+  it("应过滤 Windows 特殊字符", () => {
+    expect(CATToolRepo.sanitizeName('a:b*c?"d<e>f|g')).toBe("a_b_c__d_e_f_g");
+  });
+
+  it("空字符串应返回空字符串", () => {
+    expect(CATToolRepo.sanitizeName("")).toBe("");
+  });
+
+  it("中文名称应保持不变", () => {
+    expect(CATToolRepo.sanitizeName("天气查询")).toBe("天气查询");
+  });
+
+  it("不同名称可能映射到相同的文件名（碰撞）", () => {
+    // "a.b" 和 "a/b" 都映射为 "a_b"，文档化此行为
+    expect(CATToolRepo.sanitizeName("a.b")).toBe("a_b");
+    expect(CATToolRepo.sanitizeName("a/b")).toBe("a_b");
+    expect(CATToolRepo.sanitizeName("a\\b")).toBe("a_b");
+    expect(CATToolRepo.sanitizeName("a:b")).toBe("a_b");
+    // 所有这些都碰撞到同一个文件名
+    expect(CATToolRepo.sanitizeName("a.b")).toBe(CATToolRepo.sanitizeName("a/b"));
+  });
+});
diff --git a/src/app/repo/cattool_repo.ts b/src/app/repo/cattool_repo.ts
new file mode 100644
index 000000000..7699a1fd3
--- /dev/null
+++ b/src/app/repo/cattool_repo.ts
@@ -0,0 +1,96 @@
+import type { CATToolRecord } from "@App/app/service/agent/types";
+import { OPFSRepo } from "./opfs_repo";
+
+// 索引文件中存储的摘要信息（不含 code）
+export type CATToolSummary = Omit<CATToolRecord, "code">;
+
+const REGISTRY_FILE = "tools.json";
+// 完整记录存放的子目录
+const DATA_DIR = "data";
+
+// 目录结构：agents/tools/tools.json（索引）+ agents/tools/data/<id>.json（完整记录）
+export class CATToolRepo extends OPFSRepo {
+  constructor() {
+    super("tools");
+  }
+
+  // 将工具名转为安全的文件名，过滤路径分隔符和特殊字符
+  // 注意：不同名称可能映射到同一文件名（如 "a.b" 和 "a/b" 都变成 "a_b"），
+  // 当前仅用于兼容旧数据的迁移清理，新数据使用 UUID 作为文件名
+  static sanitizeName(name: string): string {
+    // 移除路径分隔符和 OPFS 不允许的字符
+    return name.replace(/[/\\:*?"<>|.]/g, "_");
+  }
+
+  // 使用 UUID 作为 data 文件名，完全避免碰撞
+  private idToFileName(id: string): string {
+    return `${id}.json`;
+  }
+
+  // 获取完整记录所在的子目录
+  private async getDataDir(): Promise<FileSystemDirectoryHandle> {
+    return this.getChildDir(DATA_DIR);
+  }
+
+  // 读取索引文件
+  private async readRegistry(): Promise<CATToolSummary[]> {
+    return this.readJsonFile<CATToolSummary[]>(REGISTRY_FILE, []);
+  }
+
+  // 写入索引文件
+  private async writeRegistry(summaries: CATToolSummary[]): Promise<void> {
+    await this.writeJsonFile(REGISTRY_FILE, summaries);
+  }
+
+  // 从完整记录生成摘要（去掉 code）
+  private toSummary(record: CATToolRecord): CATToolSummary {
+    const { code: _, ...summary } = record;
+    return summary;
+  }
+
+  // 列出所有工具的摘要信息（只读索引，不读单个文件）
+  async listTools(): Promise<CATToolSummary[]> {
+    return this.readRegistry();
+  }
+
+  // 获取完整的工具记录（含 code），通过索引查找 id 再读取 data 文件
+  async getTool(name: string): Promise<CATToolRecord | null> {
+    const registry = await this.readRegistry();
+    const summary = registry.find((t) => t.name === name);
+    if (!summary) return null;
+    const dataDir = await this.getDataDir();
+    return this.readJsonFile<CATToolRecord | null>(this.idToFileName(summary.id), null, dataDir);
+  }
+
+  // 保存工具并更新索引，使用 record.id 作为 data 文件名
+  async saveTool(record: CATToolRecord): Promise<void> {
+    const dataDir = await this.getDataDir();
+    await this.writeJsonFile(this.idToFileName(record.id), record, dataDir);
+    // 更新索引
+    const registry = await this.readRegistry();
+    const idx = registry.findIndex((t) => t.name === record.name);
+    const summary = this.toSummary(record);
+    if (idx >= 0) {
+      registry[idx] = summary;
+    } else {
+      registry.push(summary);
+    }
+    await this.writeRegistry(registry);
+  }
+
+  // 删除工具并更新索引
+  // 先更新索引再删 data 文件：如果中间崩溃，最差情况是留下孤儿 data 文件（无害），
+  // 反过来会产生索引中有记录但 data 已删的悬空引用
+  async removeTool(name: string): Promise<boolean> {
+    const registry = await this.readRegistry();
+    const summary = registry.find((t) => t.name === name);
+    if (!summary) return false;
+    // 先从索引中移除
+    const filtered = registry.filter((t) => t.name !== name);
+    await this.writeRegistry(filtered);
+    // 再删除 data 文件
+    const dataDir = await this.getDataDir();
+    await this.deleteFile(this.idToFileName(summary.id), dataDir);
+    return true;
+  }
+}
diff --git a/src/app/repo/mcp_server_repo.ts b/src/app/repo/mcp_server_repo.ts
new file mode 100644
index 000000000..710084912
--- /dev/null
+++ b/src/app/repo/mcp_server_repo.ts
@@ -0,0 +1,25 @@
+import type { MCPServerConfig } from "@App/app/service/agent/types";
+import { Repo } from "./repo";
+
+// 使用 chrome.storage.local 存储 MCP 服务器配置
+export class MCPServerRepo extends Repo<MCPServerConfig> {
+  constructor() {
+    super("mcp_server:");
+  }
+
+  async listServers(): Promise<MCPServerConfig[]> {
+    return this.find();
+  }
+
+  async getServer(id: string): Promise<MCPServerConfig | undefined> {
+    return this.get(id);
+  }
+
+  async saveServer(config: MCPServerConfig): Promise<void> {
+    await this._save(config.id, config);
+  }
+
+  async removeServer(id: string): Promise<void> {
+    await this.delete(id);
+  }
+}
diff --git a/src/app/repo/opfs_repo.ts b/src/app/repo/opfs_repo.ts
new file mode 100644
index 000000000..626059777
--- /dev/null
+++ b/src/app/repo/opfs_repo.ts
@@ -0,0 +1,99 @@
+// OPFS（Origin Private File System）通用 Repo 基类
+// 所有 Agent 相关的持久化数据统一存储在 agents/ 目录下
+
+const AGENTS_ROOT = "agents";
+
+// 获取 agents 根目录
+async function getAgentsRoot(): Promise<FileSystemDirectoryHandle> {
+  const root = await navigator.storage.getDirectory();
+  return root.getDirectoryHandle(AGENTS_ROOT, { create: true });
+}
+
+// 按路径逐级获取子目录，自动创建不存在的目录
+async function getSubDir(base: FileSystemDirectoryHandle, path: string): Promise<FileSystemDirectoryHandle> {
+  const parts = path.split("/").filter(Boolean);
+  let dir = base;
+  for (const part of parts) {
+    dir = await dir.getDirectoryHandle(part, { create: true });
+  }
+  return dir;
+}
+
+/**
+ * OPFS Repo 基类，提供基于 OPFS 的 JSON 文件读写能力
+ *
+ * 目录结构示例：
+ *   agents/conversations/          - 对话元数据
+ *   agents/conversations/messages/ - 对话消息
+ *   agents/skills/                 - Skill 配置
+ *   agents/memory/                 - Agent 记忆
+ */
+export class OPFSRepo {
+  constructor(private subPath: string) {}
+
+  // 获取当前 Repo 对应的目录
+  protected async getDir(): Promise<FileSystemDirectoryHandle> {
+    const root = await getAgentsRoot();
+    return getSubDir(root, this.subPath);
+  }
+
+  // 获取子目录
+  protected async getChildDir(childPath: string): Promise<FileSystemDirectoryHandle> {
+    const dir = await this.getDir();
+    return getSubDir(dir, childPath);
+  }
+
+  // 读取 JSON 文件，文件不存在时返回默认值
+  protected async readJsonFile<T>(filename: string, defaultValue: T, dir?: FileSystemDirectoryHandle): Promise<T> {
+    try {
+      const targetDir = dir || (await this.getDir());
+      const fileHandle = await targetDir.getFileHandle(filename);
+      const file = await fileHandle.getFile();
+      const text = await file.text();
+      return JSON.parse(text) as T;
+    } catch {
+      return defaultValue;
+    }
+  }
+
+  // 写入 JSON 文件
+  protected async writeJsonFile(filename: string, data: unknown, dir?: FileSystemDirectoryHandle): Promise<void> {
+    const targetDir = dir || (await this.getDir());
+    const fileHandle = await targetDir.getFileHandle(filename, { create: true });
+    const writable = await fileHandle.createWritable();
+    await writable.write(JSON.stringify(data));
+    await writable.close();
+  }
+
+  // 删除文件，不存在时忽略
+  protected async deleteFile(filename: string, dir?: FileSystemDirectoryHandle): Promise<void> {
+    try {
+      const targetDir = dir || (await this.getDir());
+      await targetDir.removeEntry(filename);
+    } catch {
+      // 文件不存在则忽略
+    }
+  }
+
+  // 递归删除子目录
+  protected async removeDirectory(name: string, dir?: FileSystemDirectoryHandle): Promise<void> {
+    try {
+      const targetDir = dir || (await this.getDir());
+      await targetDir.removeEntry(name, { recursive: true });
+    } catch {
+      // 目录不存在则忽略
+    }
+  }
+
+  // 列出目录下所有文件名
+  protected async listFiles(dir?: FileSystemDirectoryHandle): Promise<string[]> {
+    const targetDir = dir || (await this.getDir());
+    const files: string[] = [];
+    for await (const [name, handle] of targetDir as any) {
+      if (handle.kind === "file") {
+        files.push(name);
+      }
+    }
+    return files;
+  }
+}
diff --git a/src/app/repo/skill_repo.ts b/src/app/repo/skill_repo.ts
new file mode 100644
index 000000000..0b563740e
--- /dev/null
+++ b/src/app/repo/skill_repo.ts
@@ -0,0 +1,172 @@
+import type { CATToolRecord, SkillRecord, SkillReference, SkillSummary } from "@App/app/service/agent/types";
+import { OPFSRepo } from "./opfs_repo";
+
+const REGISTRY_FILE = "registry.json";
+const DATA_DIR = "data";
+const SCRIPTS_DIR = "scripts";
+const REFERENCES_DIR = "references";
+const CONFIG_VALUES_FILE = "config_values.json";
+
+// 目录结构：
+// agents/skills/registry.json — SkillSummary[]
+// agents/skills/data/{sanitized_name}/
+//   skill.json — SkillRecord
+//   scripts/{toolname}.json — CATToolRecord
+//   references/{name}.json — { name, content }
+export class SkillRepo extends OPFSRepo {
+  constructor() {
+    super("skills");
+  }
+
+  // 将名称转为安全的目录名，过滤路径分隔符和特殊字符
+  static sanitizeName(name: string): string {
+    return name.replace(/[/\\:*?"<>|.]/g, "_");
+  }
+
+  private async getDataDir(): Promise<FileSystemDirectoryHandle> {
+    return this.getChildDir(DATA_DIR);
+  }
+
+  private async getSkillDir(name: string): Promise<FileSystemDirectoryHandle> {
+    return this.getChildDir(`${DATA_DIR}/${SkillRepo.sanitizeName(name)}`);
+  }
+
+  private async readRegistry(): Promise<SkillSummary[]> {
+    return this.readJsonFile<SkillSummary[]>(REGISTRY_FILE, []);
+  }
+
+  private async writeRegistry(summaries: SkillSummary[]): Promise<void> {
+    await this.writeJsonFile(REGISTRY_FILE, summaries);
+  }
+
+  async listSkills(): Promise<SkillSummary[]> {
+    return this.readRegistry();
+  }
+
+  async getSkill(name: string): Promise<SkillRecord | null> {
+    const registry = await this.readRegistry();
+    if (!registry.find((s) => s.name === name)) return null;
+    const skillDir = await this.getSkillDir(name);
+    return this.readJsonFile<SkillRecord | null>("skill.json", null, skillDir);
+  }
+
+  async saveSkill(record: SkillRecord, scripts?: CATToolRecord[], references?: SkillReference[]): Promise<void> {
+    const skillDir = await this.getSkillDir(record.name);
+
+    // 写 skill.json
+    await this.writeJsonFile("skill.json", record, skillDir);
+
+    // 写 scripts（先清空旧文件再写入，防止更新后残留旧工具）
+    if (scripts) {
+      const sanitized = SkillRepo.sanitizeName(record.name);
+      await this.removeDirectory(SCRIPTS_DIR, await this.getSkillDir(record.name));
+      if (scripts.length > 0) {
+        const scriptsDir = await this.getChildDir(`${DATA_DIR}/${sanitized}/${SCRIPTS_DIR}`);
+        for (const script of scripts) {
+          await this.writeJsonFile(`${script.name}.json`, script, scriptsDir);
+        }
+      }
+    }
+
+    // 写 references（先清空旧文件再写入）
+    if (references) {
+      const sanitized = SkillRepo.sanitizeName(record.name);
+      await this.removeDirectory(REFERENCES_DIR, await this.getSkillDir(record.name));
+      if (references.length > 0) {
+        const refsDir = await this.getChildDir(`${DATA_DIR}/${sanitized}/${REFERENCES_DIR}`);
+        for (const ref of references) {
+          await this.writeJsonFile(`${ref.name}.json`, ref, refsDir);
+        }
+      }
+    }
+
+    // 更新 registry
+    const registry = await this.readRegistry();
+    const summary: SkillSummary = {
+      name: record.name,
+      description: record.description,
+      toolNames: record.toolNames,
+      referenceNames: record.referenceNames,
+      ...(record.config && Object.keys(record.config).length > 0 ? { hasConfig: true } : {}),
+      installtime: record.installtime,
+      updatetime: record.updatetime,
+    };
+    const idx = registry.findIndex((s) => s.name === record.name);
+    if (idx >= 0) {
+      registry[idx] = summary;
+    } else {
+      registry.push(summary);
+    }
+    await this.writeRegistry(registry);
+  }
+
+  async removeSkill(name: string): Promise<boolean> {
+    const registry = await this.readRegistry();
+    if (!registry.find((s) => s.name === name)) return false;
+
+    // 先更新 registry
+    const filtered = registry.filter((s) => s.name !== name);
+    await this.writeRegistry(filtered);
+
+    // 再删除整个 data/{sanitized_name}/ 目录
+    const dataDir = await this.getDataDir();
+    await this.removeDirectory(SkillRepo.sanitizeName(name), dataDir);
+
+    return true;
+  }
+
+  async getSkillScripts(name: string): Promise<CATToolRecord[]> {
+    try {
+      const scriptsDir = await this.getChildDir(`${DATA_DIR}/${SkillRepo.sanitizeName(name)}/${SCRIPTS_DIR}`);
+      const files = await this.listFiles(scriptsDir);
+      const records: CATToolRecord[] = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const record = await this.readJsonFile<CATToolRecord | null>(file, null, scriptsDir);
+        if (record) records.push(record);
+      }
+      return records;
+    } catch {
+      return [];
+    }
+  }
+
+  async getSkillReferences(name: string): Promise<SkillReference[]> {
+    try {
+      const refsDir = await this.getChildDir(`${DATA_DIR}/${SkillRepo.sanitizeName(name)}/${REFERENCES_DIR}`);
+      const files = await this.listFiles(refsDir);
+      const refs: SkillReference[] = [];
+      for (const file of files) {
+        if (!file.endsWith(".json")) continue;
+        const ref = await this.readJsonFile<SkillReference | null>(file, null, refsDir);
+        if (ref) refs.push(ref);
+      }
+      return refs;
+    } catch {
+      return [];
+    }
+  }
+
+  async getReference(skillName: string, refName: string): Promise<SkillReference | null> {
+    try {
+      const refsDir = await this.getChildDir(`${DATA_DIR}/${SkillRepo.sanitizeName(skillName)}/${REFERENCES_DIR}`);
+      return this.readJsonFile<SkillReference | null>(`${refName}.json`, null, refsDir);
+    } catch {
+      return null;
+    }
+  }
+
+  async getConfigValues(name: string): Promise<Record<string, unknown>> {
+    try {
+      const skillDir = await this.getSkillDir(name);
+      return this.readJsonFile<Record<string, unknown>>(CONFIG_VALUES_FILE, {}, skillDir);
+    } catch {
+      return {};
+    }
+  }
+
+  async saveConfigValues(name: string, values: Record<string, unknown>): Promise<void> {
+    const skillDir = await this.getSkillDir(name);
+    await this.writeJsonFile(CONFIG_VALUES_FILE, values, skillDir);
+  }
+}
diff --git a/src/app/service/agent/agent.test.ts b/src/app/service/agent/agent.test.ts
new file mode 100644
index 000000000..d34b7a1dc
--- /dev/null
+++ b/src/app/service/agent/agent.test.ts
@@ -0,0 +1,1505 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { SSEParser } from "./sse_parser";
+import { buildOpenAIRequest, parseOpenAIStream } from "./providers/openai";
+import { buildAnthropicRequest, parseAnthropicStream } from "./providers/anthropic";
+import type { AgentModelConfig } from "./types";
+import type { ChatRequest, ChatStreamEvent, ToolDefinition } from "./types";
+import { AgentService } from "@App/app/service/service_worker/agent";
+import type { ToolRegistry } from "./tool_registry";
+import type { ToolExecutor } from "./tool_registry";
+
+// 模型配置
+const openaiConfig: AgentModelConfig = {
+  id: "test-openai",
+  name: "Test OpenAI",
+  provider: "openai",
+  apiBaseUrl: "https://api.openai.com/v1",
+  apiKey: "sk-test",
+  model: "gpt-4o",
+};
+
+const anthropicConfig: AgentModelConfig = {
+  id: "test-anthropic",
+  name: "Test Anthropic",
+  provider: "anthropic",
+  apiBaseUrl: "https://api.anthropic.com",
+  apiKey: "sk-ant-test",
+  model: "claude-sonnet-4-20250514",
+};
+
+const testTools: ToolDefinition[] = [
+  {
+    name: "get_weather",
+    description: "获取指定城市的天气",
+    parameters: {
+      type: "object",
+      properties: {
+        city: { type: "string", description: "城市名称" },
+      },
+      required: ["city"],
+    },
+  },
+];
+
+// 辅助函数：将 SSE 文本构造为 ReadableStreamDefaultReader
+function createMockReader(chunks: string[]): ReadableStreamDefaultReader<Uint8Array> {
+  const encoder = new TextEncoder();
+  let index = 0;
+  return {
+    read: async () => {
+      if (index >= chunks.length) {
+        return { done: true, value: undefined } as ReadableStreamReadDoneResult<Uint8Array>;
+      }
+      const value = encoder.encode(chunks[index++]);
+      return { done: false, value } as ReadableStreamReadResult<Uint8Array>;
+    },
+    releaseLock: () => {},
+    cancel: async () => {},
+    closed: Promise.resolve(undefined),
+  } as ReadableStreamDefaultReader<Uint8Array>;
+}
+
+// 辅助函数：收集 parseStream 产生的所有事件
+async function collectEvents(
+  parseFn: typeof parseOpenAIStream,
+  chunks: string[],
+  signal?: AbortSignal
+): Promise<ChatStreamEvent[]> {
+  const events: ChatStreamEvent[] = [];
+  const reader = createMockReader(chunks);
+  await parseFn(reader, (e) => events.push(e), signal ?? new AbortController().signal);
+  return events;
+}
+
+describe("SSEParser", () => {
+  it("应正确解析单个 SSE 事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse('data: {"text":"hello"}\n\n');
+    expect(events).toHaveLength(1);
+    expect(events[0].event).toBe("message");
+    expect(events[0].data).toBe('{"text":"hello"}');
+  });
+
+  it("应正确解析带 event 字段的事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse('event: content_block_delta\ndata: {"delta":"hi"}\n\n');
+    expect(events).toHaveLength(1);
+    expect(events[0].event).toBe("content_block_delta");
+  });
+
+  it("应正确处理跨 chunk 的事件", () => {
+    const parser = new SSEParser();
+    const events1 = parser.parse('data: {"text":');
+    expect(events1).toHaveLength(0);
+    const events2 = parser.parse('"hello"}\n\n');
+    expect(events2).toHaveLength(1);
+    expect(events2[0].data).toBe('{"text":"hello"}');
+  });
+
+  it("应正确解析多个连续事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse('data: {"a":1}\n\ndata: {"b":2}\n\n');
+    expect(events).toHaveLength(2);
+  });
+
+  it("应忽略注释行", () => {
+    const parser = new SSEParser();
+    const events = parser.parse(": comment\ndata: test\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("test");
+  });
+});
+
+describe("OpenAI Provider", () => {
+  describe("buildOpenAIRequest", () => {
+    it("应正确构造基础请求", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-openai",
+        messages: [
+          { role: "system", content: "你是助手" },
+          { role: "user", content: "你好" },
+        ],
+      };
+
+      const { url, init } = buildOpenAIRequest(openaiConfig, request);
+      expect(url).toBe("https://api.openai.com/v1/chat/completions");
+      expect(init.method).toBe("POST");
+
+      const headers = init.headers as Record<string, string>;
+      expect(headers["Authorization"]).toBe("Bearer sk-test");
+
+      const body = JSON.parse(init.body as string);
+      expect(body.model).toBe("gpt-4o");
+      expect(body.messages).toHaveLength(2);
+      expect(body.stream).toBe(true);
+      expect(body.tools).toBeUndefined();
+    });
+
+    it("应正确包含工具定义", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-openai",
+        messages: [{ role: "user", content: "北京天气" }],
+        tools: testTools,
+      };
+
+      const { init } = buildOpenAIRequest(openaiConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      expect(body.tools).toHaveLength(1);
+      expect(body.tools[0].type).toBe("function");
+      expect(body.tools[0].function.name).toBe("get_weather");
+      expect(body.tools[0].function.description).toBe("获取指定城市的天气");
+      expect(body.tools[0].function.parameters.properties.city.type).toBe("string");
+    });
+
+    it("应正确处理 tool 角色消息", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-openai",
+        messages: [
+          { role: "user", content: "北京天气" },
+          { role: "assistant", content: "" },
+          { role: "tool", content: '{"temp": 25}', toolCallId: "call_123" },
+        ],
+        tools: testTools,
+      };
+
+      const { init } = buildOpenAIRequest(openaiConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      expect(body.messages[2].role).toBe("tool");
+      expect(body.messages[2].tool_call_id).toBe("call_123");
+    });
+
+    it("应正确转换 assistant 消息中的 toolCalls 为 OpenAI tool_calls 格式", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-openai",
+        messages: [
+          { role: "user", content: "北京天气" },
+          {
+            role: "assistant",
+            content: "",
+            toolCalls: [{ id: "call_abc", name: "get_weather", arguments: '{"city":"北京"}' }],
+          },
+          { role: "tool", content: '{"temp": 25}', toolCallId: "call_abc" },
+        ],
+        tools: testTools,
+      };
+
+      const { init } = buildOpenAIRequest(openaiConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      // assistant 消息应包含 tool_calls
+      const assistantMsg = body.messages[1];
+      expect(assistantMsg.role).toBe("assistant");
+      expect(assistantMsg.tool_calls).toHaveLength(1);
+      expect(assistantMsg.tool_calls[0].id).toBe("call_abc");
+      expect(assistantMsg.tool_calls[0].type).toBe("function");
+      expect(assistantMsg.tool_calls[0].function.name).toBe("get_weather");
+      expect(assistantMsg.tool_calls[0].function.arguments).toBe('{"city":"北京"}');
+
+      // tool 消息应有 tool_call_id
+      const toolMsg = body.messages[2];
+      expect(toolMsg.role).toBe("tool");
+      expect(toolMsg.tool_call_id).toBe("call_abc");
+    });
+
+    it("assistant 消息没有 toolCalls 时不应生成 tool_calls 字段", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-openai",
+        messages: [
+          { role: "user", content: "你好" },
+          { role: "assistant", content: "你好！" },
+        ],
+      };
+
+      const { init } = buildOpenAIRequest(openaiConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      expect(body.messages[1].tool_calls).toBeUndefined();
+    });
+  });
+
+  describe("parseOpenAIStream", () => {
+    it("应正确解析内容增量事件", async () => {
+      const events = await collectEvents(parseOpenAIStream, [
+        'data: {"choices":[{"delta":{"content":"你好"}}]}\n\n',
+        'data: {"choices":[{"delta":{"content":"世界"}}]}\n\n',
+        "data: [DONE]\n\n",
+      ]);
+
+      expect(events).toHaveLength(3);
+      expect(events[0]).toEqual({ type: "content_delta", delta: "你好" });
+      expect(events[1]).toEqual({ type: "content_delta", delta: "世界" });
+      expect(events[2]).toEqual({ type: "done" });
+    });
+
+    it("应正确解析 tool_call 事件", async () => {
+      const events = await collectEvents(parseOpenAIStream, [
+        'data: {"choices":[{"delta":{"tool_calls":[{"id":"call_1","function":{"name":"get_weather","arguments":""}}]}}]}\n\n',
+        'data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\\"city\\":"}}]}}]}\n\n',
+        'data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"\\"北京\\"}"}}]}}]}\n\n',
+        "data: [DONE]\n\n",
+      ]);
+
+      expect(events[0].type).toBe("tool_call_start");
+      if (events[0].type === "tool_call_start") {
+        expect(events[0].toolCall.id).toBe("call_1");
+        expect(events[0].toolCall.name).toBe("get_weather");
+      }
+      expect(events[1].type).toBe("tool_call_delta");
+      expect(events[2].type).toBe("tool_call_delta");
+      expect(events[3]).toEqual({ type: "done" });
+    });
+
+    it("应正确解析带 usage 的 done 事件", async () => {
+      const events = await collectEvents(parseOpenAIStream, [
+        'data: {"choices":[{"delta":{"content":"hi"}}]}\n\n',
+        'data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n',
+      ]);
+
+      expect(events).toHaveLength(2);
+      expect(events[1]).toEqual({
+        type: "done",
+        usage: { inputTokens: 10, outputTokens: 5 },
+      });
+    });
+
+    it("应正确处理 SSE 流中的 API 错误响应", async () => {
+      // 模拟真实场景：API 返回 200 但 SSE 数据中包含错误
+      const events = await collectEvents(parseOpenAIStream, [
+        'data: {"error":{"message":"Request failed with status code 400","type":"invalid_request_error","code":null}}\n\n',
+        'data: {"id":"","object":"chat.completion.chunk","created":0,"model":"","choices":[],"usage":{"prompt_tokens":100,"completion_tokens":0,"total_tokens":100}}\n\n',
+        "data: [DONE]\n\n",
+      ]);
+
+      // 应只有一个 error 事件，后续数据不再处理
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe("error");
+      if (events[0].type === "error") {
+        expect(events[0].message).toBe("Request failed with status code 400");
+      }
+    });
+
+    it("应处理没有 message 字段的错误响应", async () => {
+      const events = await collectEvents(parseOpenAIStream, [
+        'data: {"error":{"type":"server_error","code":"internal"}}\n\n',
+      ]);
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe("error");
+      if (events[0].type === "error") {
+        // 没有 message 时应回退到 JSON.stringify
+        expect(events[0].message).toContain("server_error");
+      }
+    });
+
+    it("应正确处理读取流异常", async () => {
+      const reader = {
+        read: async () => {
+          throw new Error("Network error");
+        },
+        releaseLock: () => {},
+        cancel: async () => {},
+        closed: Promise.resolve(undefined),
+      } as unknown as ReadableStreamDefaultReader<Uint8Array>;
+
+      const events: ChatStreamEvent[] = [];
+      await parseOpenAIStream(reader, (e) => events.push(e), new AbortController().signal);
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe("error");
+      if (events[0].type === "error") {
+        expect(events[0].message).toBe("Network error");
+      }
+    });
+
+    it("signal 中断时不应产生错误事件", async () => {
+      const abortController = new AbortController();
+      abortController.abort();
+
+      const events = await collectEvents(
+        parseOpenAIStream,
+        ['data: {"choices":[{"delta":{"content":"hello"}}]}\n\n'],
+        abortController.signal
+      );
+
+      // signal 已中断，不应处理任何数据
+      expect(events).toHaveLength(0);
+    });
+  });
+});
+
+describe("Anthropic Provider", () => {
+  describe("buildAnthropicRequest", () => {
+    it("应正确构造基础请求", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-anthropic",
+        messages: [
+          { role: "system", content: "你是助手" },
+          { role: "user", content: "你好" },
+        ],
+      };
+
+      const { url, init } = buildAnthropicRequest(anthropicConfig, request);
+      expect(url).toBe("https://api.anthropic.com/v1/messages");
+
+      const headers = init.headers as Record<string, string>;
+      expect(headers["x-api-key"]).toBe("sk-ant-test");
+
+      const body = JSON.parse(init.body as string);
+      expect(body.model).toBe("claude-sonnet-4-20250514");
+      expect(body.system).toEqual([{ type: "text", text: "你是助手", cache_control: { type: "ephemeral" } }]);
+      // system 消息不应出现在 messages 中
+      expect(body.messages).toHaveLength(1);
+      expect(body.messages[0].role).toBe("user");
+      expect(body.tools).toBeUndefined();
+    });
+
+    it("应正确包含工具定义（Anthropic 格式）", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-anthropic",
+        messages: [{ role: "user", content: "北京天气" }],
+        tools: testTools,
+      };
+
+      const { init } = buildAnthropicRequest(anthropicConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      expect(body.tools).toHaveLength(1);
+      expect(body.tools[0].name).toBe("get_weather");
+      expect(body.tools[0].input_schema).toBeDefined();
+      // Anthropic 不用 function 包裹
+      expect(body.tools[0].type).toBeUndefined();
+    });
+
+    it("应正确转换 tool 角色消息为 Anthropic tool_result 格式", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-anthropic",
+        messages: [
+          { role: "user", content: "北京天气" },
+          { role: "assistant", content: "" },
+          { role: "tool", content: '{"temp": 25}', toolCallId: "toolu_123" },
+        ],
+        tools: testTools,
+      };
+
+      const { init } = buildAnthropicRequest(anthropicConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      // tool 消息应转换为 user 角色 + tool_result content block
+      const toolMsg = body.messages[2];
+      expect(toolMsg.role).toBe("user");
+      expect(toolMsg.content).toBeInstanceOf(Array);
+      expect(toolMsg.content[0].type).toBe("tool_result");
+      expect(toolMsg.content[0].tool_use_id).toBe("toolu_123");
+      expect(toolMsg.content[0].content).toBe('{"temp": 25}');
+    });
+
+    it("应正确转换 assistant 消息中的 toolCalls 为 Anthropic content blocks", () => {
+      const request: ChatRequest = {
+        conversationId: "test",
+        modelId: "test-anthropic",
+        messages: [
+          { role: "user", content: "北京天气" },
+          {
+            role: "assistant",
+            content: "让我查一下",
+            toolCalls: [{ id: "toolu_abc", name: "get_weather", arguments: '{"city":"北京"}' }],
+          },
+          { role: "tool", content: '{"temp": 25}', toolCallId: "toolu_abc" },
+        ],
+        tools: testTools,
+      };
+
+      const { init } = buildAnthropicRequest(anthropicConfig, request);
+      const body = JSON.parse(init.body as string);
+
+      // assistant 消息应转换为 content blocks（text + tool_use）
+      const assistantMsg = body.messages[1];
+      expect(assistantMsg.role).toBe("assistant");
+      expect(assistantMsg.content).toBeInstanceOf(Array);
+      expect(assistantMsg.content).toHaveLength(2);
+      expect(assistantMsg.content[0]).toEqual({ type: "text", text: "让我查一下" });
+      expect(assistantMsg.content[1]).toEqual({
+        type: "tool_use",
+        id: "toolu_abc",
+        name: "get_weather",
+        input: { city: "北京" },
+      });
+    });
+  });
+
+  describe("parseAnthropicStream", () => {
+    it("应正确解析内容增量事件", async () => {
+      const events = await collectEvents(parseAnthropicStream, [
+        'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"你好"}}\n\n',
+        'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"世界"}}\n\n',
+        "event: message_stop\ndata: {}\n\n",
+      ]);
+
+      expect(events).toHaveLength(3);
+      expect(events[0]).toEqual({ type: "content_delta", delta: "你好" });
+      expect(events[1]).toEqual({ type: "content_delta", delta: "世界" });
+      expect(events[2]).toEqual({ type: "done" });
+    });
+
+    it("应正确解析 tool_use 事件", async () => {
+      const events = await collectEvents(parseAnthropicStream, [
+        'event: content_block_start\ndata: {"content_block":{"type":"tool_use","id":"toolu_1","name":"get_weather"}}\n\n',
+        'event: content_block_delta\ndata: {"delta":{"type":"input_json_delta","partial_json":"{\\"city\\":"}}\n\n',
+        'event: content_block_delta\ndata: {"delta":{"type":"input_json_delta","partial_json":"\\"北京\\"}"}}\n\n',
+        "event: message_stop\ndata: {}\n\n",
+      ]);
+
+      expect(events[0].type).toBe("tool_call_start");
+      if (events[0].type === "tool_call_start") {
+        expect(events[0].toolCall.id).toBe("toolu_1");
+        expect(events[0].toolCall.name).toBe("get_weather");
+      }
+      expect(events[1].type).toBe("tool_call_delta");
+      expect(events[2].type).toBe("tool_call_delta");
+      expect(events[3]).toEqual({ type: "done" });
+    });
+
+    it("应正确解析带 usage 的 message_delta 事件", async () => {
+      const events = await collectEvents(parseAnthropicStream, [
+        'event: message_delta\ndata: {"usage":{"input_tokens":20,"output_tokens":8}}\n\n',
+      ]);
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({
+        type: "done",
+        usage: { inputTokens: 20, outputTokens: 8 },
+      });
+    });
+
+    it("应正确处理 error 事件", async () => {
+      const events = await collectEvents(parseAnthropicStream, [
+        'event: error\ndata: {"error":{"message":"Rate limit exceeded"}}\n\n',
+      ]);
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe("error");
+      if (events[0].type === "error") {
+        expect(events[0].message).toBe("Rate limit exceeded");
+      }
+    });
+
+    it("应正确解析 thinking 事件", async () => {
+      const events = await collectEvents(parseAnthropicStream, [
+        'event: content_block_start\ndata: {"content_block":{"type":"thinking"}}\n\n',
+        'event: content_block_delta\ndata: {"delta":{"type":"thinking_delta","thinking":"让我想想..."}}\n\n',
+        "event: message_stop\ndata: {}\n\n",
+      ]);
+
+      expect(events).toHaveLength(2); // thinking_delta + done（thinking start 不产生事件）
+      expect(events[0]).toEqual({ type: "thinking_delta", delta: "让我想想..." });
+      expect(events[1]).toEqual({ type: "done" });
+    });
+  });
+});
+
+describe("Agent Types", () => {
+  it("ChatRequest 应支持 tools 字段", () => {
+    const request: ChatRequest = {
+      conversationId: "test",
+      modelId: "test",
+      messages: [{ role: "user", content: "hello" }],
+      tools: testTools,
+    };
+    expect(request.tools).toHaveLength(1);
+  });
+
+  it("ChatRequest 消息应支持 tool 角色和 toolCallId", () => {
+    const request: ChatRequest = {
+      conversationId: "test",
+      modelId: "test",
+      messages: [
+        { role: "user", content: "hello" },
+        { role: "tool", content: "result", toolCallId: "call_1" },
+      ],
+    };
+    expect(request.messages[1].role).toBe("tool");
+    expect(request.messages[1].toolCallId).toBe("call_1");
+  });
+
+  it("ChatRequest 消息应支持 toolCalls 字段", () => {
+    const request: ChatRequest = {
+      conversationId: "test",
+      modelId: "test",
+      messages: [
+        { role: "user", content: "hello" },
+        {
+          role: "assistant",
+          content: "",
+          toolCalls: [{ id: "call_1", name: "test_tool", arguments: "{}" }],
+        },
+        { role: "tool", content: "result", toolCallId: "call_1" },
+      ],
+    };
+    expect(request.messages[1].toolCalls).toHaveLength(1);
+    expect(request.messages[1].toolCalls![0].name).toBe("test_tool");
+  });
+});
+
+// ---- callLLMWithToolLoop 测试 ----
+
+// 辅助：构造 mock Response，兼容 jsdom 不支持 ReadableStream body 的情况
+function buildSSEResponse(sseChunks: string[]): Response {
+  const encoder = new TextEncoder();
+  let index = 0;
+  const mockReader = {
+    read: async () => {
+      if (index >= sseChunks.length) {
+        return { done: true, value: undefined } as ReadableStreamReadDoneResult<Uint8Array>;
+      }
+      const value = encoder.encode(sseChunks[index++]);
+      return { done: false, value } as ReadableStreamReadResult<Uint8Array>;
+    },
+    releaseLock: () => {},
+    cancel: async () => {},
+    closed: Promise.resolve(undefined),
+  };
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      getReader: () => mockReader,
+    },
+    text: async () => "",
+  } as unknown as Response;
+}
+
+// 辅助：构造纯文本 SSE 数据（OpenAI 格式）
+function makeTextSSE(text: string, usage?: { prompt_tokens: number; completion_tokens: number }): string[] {
+  const chunks: string[] = [];
+  chunks.push(`data: {"choices":[{"delta":{"content":"${text}"}}]}\n\n`);
+  if (usage) {
+    chunks.push(`data: {"usage":${JSON.stringify(usage)}}\n\n`);
+  } else {
+    chunks.push("data: [DONE]\n\n");
+  }
+  return chunks;
+}
+
+// 辅助：构造带 tool_call 的 SSE 数据（OpenAI 格式）
+function makeToolCallSSE(
+  toolId: string,
+  toolName: string,
+  args: string,
+  usage?: { prompt_tokens: number; completion_tokens: number }
+): string[] {
+  const chunks: string[] = [];
+  chunks.push(
+    `data: {"choices":[{"delta":{"tool_calls":[{"id":"${toolId}","function":{"name":"${toolName}","arguments":""}}]}}]}\n\n`
+  );
+  chunks.push(
+    `data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"${args.replace(/"/g, '\\"')}"}}]}}]}\n\n`
+  );
+  if (usage) {
+    chunks.push(`data: {"usage":${JSON.stringify(usage)}}\n\n`);
+  } else {
+    chunks.push("data: [DONE]\n\n");
+  }
+  return chunks;
+}
+
+// 辅助：构造 HTTP 错误响应
+function buildErrorResponse(status: number, body: string): Response {
+  return {
+    ok: false,
+    status,
+    body: null,
+    text: async () => body,
+  } as unknown as Response;
+}
+
+// 创建 mock AgentService 实例
+function createTestService() {
+  const mockRepo = {
+    appendMessage: vi.fn().mockResolvedValue(undefined),
+    getMessages: vi.fn().mockResolvedValue([]),
+    listConversations: vi.fn().mockResolvedValue([]),
+    saveConversation: vi.fn().mockResolvedValue(undefined),
+    saveMessages: vi.fn().mockResolvedValue(undefined),
+  };
+
+  const mockGroup = {
+    on: vi.fn(),
+  } as any;
+
+  const mockSender = {} as any;
+
+  const service = new AgentService(mockGroup, mockSender);
+
+  // 替换 modelRepo（避免 chrome.storage 调用）
+  (service as any).modelRepo = {
+    listModels: vi.fn().mockResolvedValue([openaiConfig]),
+    getModel: vi.fn().mockImplementation((id: string) => {
+      if (id === "test-openai") return Promise.resolve(openaiConfig);
+      return Promise.resolve(undefined);
+    }),
+    getDefaultModelId: vi.fn().mockResolvedValue("test-openai"),
+  };
+
+  // 替换 repo 和 catToolRepo（避免 OPFS 调用）
+  (service as any).repo = mockRepo;
+  (service as any).catToolRepo = { listTools: vi.fn().mockResolvedValue([]) };
+
+  const toolRegistry = (service as any).toolRegistry as ToolRegistry;
+
+  return { service, mockRepo, toolRegistry };
+}
+
+describe("callLLMWithToolLoop", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it("无 tool calling 的简单对话", async () => {
+    const { service } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    fetchSpy.mockResolvedValueOnce(
+      buildSSEResponse(makeTextSSE("你好世界", { prompt_tokens: 10, completion_tokens: 5 }))
+    );
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "你好" }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    // 应该收到 content_delta 和 done
+    const contentEvents = events.filter((e) => e.type === "content_delta");
+    expect(contentEvents.length).toBeGreaterThanOrEqual(1);
+
+    const doneEvent = events.find((e) => e.type === "done");
+    expect(doneEvent).toBeDefined();
+    expect(doneEvent!.type === "done" && doneEvent!.usage).toEqual({ inputTokens: 10, outputTokens: 5 });
+  });
+
+  it("单轮 tool calling", async () => {
+    const { service, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // 注册一个 mock 工具
+    const mockExecutor: ToolExecutor = {
+      execute: vi.fn().mockResolvedValue({ temp: 25 }),
+    };
+    toolRegistry.registerBuiltin(
+      { name: "get_weather", description: "获取天气", parameters: { type: "object", properties: {} } },
+      mockExecutor
+    );
+
+    // 第一次调用：LLM 返回 tool_call
+    fetchSpy.mockResolvedValueOnce(
+      buildSSEResponse(
+        makeToolCallSSE("call_1", "get_weather", '{"city":"北京"}', { prompt_tokens: 20, completion_tokens: 10 })
+      )
+    );
+    // 第二次调用：LLM 返回纯文本
+    fetchSpy.mockResolvedValueOnce(
+      buildSSEResponse(makeTextSSE("北京今天25度", { prompt_tokens: 30, completion_tokens: 8 }))
+    );
+
+    const messages: ChatRequest["messages"] = [{ role: "user", content: "北京天气怎么样" }];
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages,
+      tools: [{ name: "get_weather", description: "获取天气", parameters: {} }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    // fetch 应被调用两次
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+    // 工具应被执行
+    expect(mockExecutor.execute).toHaveBeenCalledWith({ city: "北京" });
+
+    // messages 应包含 assistant(tool_call) + tool(result) + user 原始消息
+    expect(messages.length).toBe(3); // user + assistant(toolCalls) + tool(result)
+    expect(messages[1].role).toBe("assistant");
+    expect(messages[1].toolCalls).toBeDefined();
+    expect(messages[2].role).toBe("tool");
+
+    // 应有 done 事件，usage 是累加的
+    const doneEvent = events.find((e) => e.type === "done");
+    expect(doneEvent).toBeDefined();
+    if (doneEvent?.type === "done") {
+      expect(doneEvent.usage).toEqual({ inputTokens: 50, outputTokens: 18 });
+    }
+  });
+
+  it("多轮 tool calling", async () => {
+    const { service, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    const mockExecutor: ToolExecutor = {
+      execute: vi.fn().mockResolvedValue("result"),
+    };
+    toolRegistry.registerBuiltin(
+      { name: "search", description: "搜索", parameters: { type: "object", properties: {} } },
+      mockExecutor
+    );
+
+    // 第一次：tool_call
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_1", "search", '{"q":"a"}')));
+    // 第二次：又一个 tool_call
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_2", "search", '{"q":"b"}')));
+    // 第三次：纯文本
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("完成")));
+
+    const messages: ChatRequest["messages"] = [{ role: "user", content: "搜索" }];
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages,
+      tools: [{ name: "search", description: "搜索", parameters: {} }],
+      maxIterations: 10,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+    expect(mockExecutor.execute).toHaveBeenCalledTimes(2);
+    // user + assistant+tool + assistant+tool = 5 条消息
+    expect(messages.length).toBe(5);
+    expect(events.find((e) => e.type === "done")).toBeDefined();
+  });
+
+  it("超过 maxIterations 限制", async () => {
+    const { service, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    toolRegistry.registerBuiltin(
+      { name: "loop_tool", description: "循环工具", parameters: { type: "object", properties: {} } },
+      { execute: vi.fn().mockResolvedValue("ok") }
+    );
+
+    // 每次都返回 tool_call
+    fetchSpy.mockImplementation(() => Promise.resolve(buildSSEResponse(makeToolCallSSE("call_x", "loop_tool", "{}"))));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      tools: [{ name: "loop_tool", description: "循环工具", parameters: {} }],
+      maxIterations: 3,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    // fetch 应被调用 3 次（maxIterations）
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+
+    // 应收到 error 事件
+    const errorEvent = events.find((e) => e.type === "error");
+    expect(errorEvent).toBeDefined();
+    if (errorEvent?.type === "error") {
+      expect(errorEvent.message).toContain("maximum iterations");
+      expect(errorEvent.message).toContain("3");
+    }
+  });
+
+  it("signal 中止后应提前退出", async () => {
+    const { service } = createTestService();
+    const events: ChatStreamEvent[] = [];
+    const abortController = new AbortController();
+
+    // 模拟：callLLM 正常返回结果，但在返回后 signal 已被 abort
+    // 通过 mock callLLM 直接实现，避免 parseStream 阻塞
+    const callLLMSpy = vi.spyOn(service as any, "callLLM").mockImplementation(async () => {
+      abortController.abort();
+      return { content: "hello", toolCalls: undefined, usage: { inputTokens: 5, outputTokens: 3 } };
+    });
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: abortController.signal,
+      scriptToolCallback: null,
+    });
+
+    // abort 后不应有 done 事件（callLLMWithToolLoop 在 signal.aborted 时直接 return）
+    expect(events.find((e) => e.type === "done")).toBeUndefined();
+    callLLMSpy.mockRestore();
+  });
+
+  it("scriptToolCallback 转发未注册的工具", async () => {
+    const { service } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    const scriptCallback = vi.fn().mockResolvedValue([{ id: "call_1", result: '{"data":"from_script"}' }]);
+
+    // 第一次：tool_call（工具未在 registry 注册）
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_1", "script_tool", '{"input":"test"}')));
+    // 第二次：纯文本
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("done")));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      tools: [{ name: "script_tool", description: "脚本工具", parameters: {} }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: scriptCallback,
+    });
+
+    // scriptCallback 应被调用
+    expect(scriptCallback).toHaveBeenCalledTimes(1);
+    expect(scriptCallback).toHaveBeenCalledWith([expect.objectContaining({ id: "call_1", name: "script_tool" })]);
+
+    expect(events.find((e) => e.type === "done")).toBeDefined();
+  });
+
+  it("有 conversationId 时应持久化消息", async () => {
+    const { service, mockRepo } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("回答")));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "问题" }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+      conversationId: "conv-123",
+    });
+
+    // 应调用 appendMessage 持久化 assistant 消息
+    expect(mockRepo.appendMessage).toHaveBeenCalledTimes(1);
+    expect(mockRepo.appendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        conversationId: "conv-123",
+        role: "assistant",
+        content: "回答",
+      })
+    );
+  });
+
+  it("无 conversationId 时不应调用持久化", async () => {
+    const { service, mockRepo } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("回答")));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "问题" }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+      // 无 conversationId
+    });
+
+    expect(mockRepo.appendMessage).not.toHaveBeenCalled();
+  });
+
+  it("有 conversationId 的 tool calling 应持久化所有消息", async () => {
+    const { service, mockRepo, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    toolRegistry.registerBuiltin(
+      { name: "my_tool", description: "工具", parameters: { type: "object", properties: {} } },
+      { execute: vi.fn().mockResolvedValue("tool_result") }
+    );
+
+    // 第一次：tool_call
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_1", "my_tool", "{}")));
+    // 第二次：纯文本
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("最终回答")));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "问题" }],
+      tools: [{ name: "my_tool", description: "工具", parameters: {} }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+      conversationId: "conv-456",
+    });
+
+    // 应持久化 3 条消息：assistant(tool_call) + tool(result) + assistant(final)
+    expect(mockRepo.appendMessage).toHaveBeenCalledTimes(3);
+
+    // 第一次：assistant with toolCalls
+    expect(mockRepo.appendMessage.mock.calls[0][0]).toMatchObject({
+      conversationId: "conv-456",
+      role: "assistant",
+      toolCalls: expect.arrayContaining([expect.objectContaining({ id: "call_1", name: "my_tool" })]),
+    });
+
+    // 第二次：tool result
+    expect(mockRepo.appendMessage.mock.calls[1][0]).toMatchObject({
+      conversationId: "conv-456",
+      role: "tool",
+      toolCallId: "call_1",
+    });
+
+    // 第三次：最终 assistant 回答
+    expect(mockRepo.appendMessage.mock.calls[2][0]).toMatchObject({
+      conversationId: "conv-456",
+      role: "assistant",
+      content: "最终回答",
+    });
+  });
+
+  it("callLLM 抛出异常时应向上传播", async () => {
+    const { service } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // fetch 返回 HTTP 500 JSON 错误
+    fetchSpy.mockResolvedValueOnce(buildErrorResponse(500, '{"error":{"message":"Internal server error"}}'));
+
+    await expect(
+      (service as any).callLLMWithToolLoop({
+        model: openaiConfig,
+        messages: [{ role: "user", content: "test" }],
+        maxIterations: 5,
+        sendEvent: (e: ChatStreamEvent) => events.push(e),
+        signal: new AbortController().signal,
+        scriptToolCallback: null,
+      })
+    ).rejects.toThrow("Internal server error");
+
+    // 不应有 done 或 error 事件（异常直接抛出，由上层 catch）
+    expect(events.find((e) => e.type === "done")).toBeUndefined();
+  });
+
+  it("callLLM HTTP 错误 - 纯文本错误体", async () => {
+    const { service } = createTestService();
+
+    // 429 是可重试错误，需要 mock 足够多的失败响应让 withRetry 用尽重试次数
+    const errorResp = () => buildErrorResponse(429, "Rate limit exceeded");
+    fetchSpy.mockResolvedValueOnce(errorResp());
+    fetchSpy.mockResolvedValueOnce(errorResp());
+    fetchSpy.mockResolvedValueOnce(errorResp());
+    fetchSpy.mockResolvedValueOnce(errorResp());
+
+    await expect(
+      (service as any).callLLMWithToolLoop({
+        model: openaiConfig,
+        messages: [{ role: "user", content: "test" }],
+        maxIterations: 5,
+        sendEvent: () => {},
+        signal: new AbortController().signal,
+        scriptToolCallback: null,
+        delayFn: async () => {},
+      })
+    ).rejects.toThrow("API error: 429 - Rate limit exceeded");
+  });
+
+  it("callLLM HTTP 错误 - 空错误体", async () => {
+    const { service } = createTestService();
+
+    // 502 是可重试错误，需要 mock 足够多的失败响应让 withRetry 用尽重试次数
+    const errorResp = () => buildErrorResponse(502, "");
+    fetchSpy.mockResolvedValueOnce(errorResp());
+    fetchSpy.mockResolvedValueOnce(errorResp());
+    fetchSpy.mockResolvedValueOnce(errorResp());
+    fetchSpy.mockResolvedValueOnce(errorResp());
+
+    await expect(
+      (service as any).callLLMWithToolLoop({
+        model: openaiConfig,
+        messages: [{ role: "user", content: "test" }],
+        maxIterations: 5,
+        sendEvent: () => {},
+        signal: new AbortController().signal,
+        scriptToolCallback: null,
+        delayFn: async () => {},
+      })
+    ).rejects.toThrow("API error: 502");
+  });
+
+  it("LLM 返回 toolCalls 但没有工具定义时应正常结束", async () => {
+    const { service } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // LLM 幻觉返回了 tool_call，但调用时没传 tools 且 registry 也没有注册工具
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_1", "phantom_tool", '{"x":1}')));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      // 不传 tools，allToolDefs 为空
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    // 应只调用 1 次 fetch（不进入 tool calling 循环）
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    // 应正常结束，发送 done
+    const doneEvent = events.find((e) => e.type === "done");
+    expect(doneEvent).toBeDefined();
+  });
+
+  it("callLLM 内部不应将 done/error 事件转发给 sendEvent", async () => {
+    const { service } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // 使用带 usage 的响应（parseOpenAIStream 会产生 done 事件）
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("hello", { prompt_tokens: 5, completion_tokens: 3 })));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    // callLLM 内部过滤了 parseStream 产生的 done 事件，只有 callLLMWithToolLoop 发送的 done
+    // 所以只应有 1 个 done 事件（来自 callLLMWithToolLoop 第 306 行）
+    const doneEvents = events.filter((e) => e.type === "done");
+    expect(doneEvents).toHaveLength(1);
+
+    // content_delta 应正常转发
+    const contentEvents = events.filter((e) => e.type === "content_delta");
+    expect(contentEvents.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("单次响应包含多个 tool_calls", async () => {
+    const { service, toolRegistry, mockRepo } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    const executorA: ToolExecutor = { execute: vi.fn().mockResolvedValue("result_a") };
+    const executorB: ToolExecutor = { execute: vi.fn().mockResolvedValue("result_b") };
+
+    toolRegistry.registerBuiltin(
+      { name: "tool_a", description: "工具A", parameters: { type: "object", properties: {} } },
+      executorA
+    );
+    toolRegistry.registerBuiltin(
+      { name: "tool_b", description: "工具B", parameters: { type: "object", properties: {} } },
+      executorB
+    );
+
+    // 直接 mock callLLM 返回多个 toolCalls（绕过 callLLM 内部 currentToolCall 单变量的限制）
+    let callCount = 0;
+    const callLLMSpy = vi.spyOn(service as any, "callLLM").mockImplementation(async () => {
+      callCount++;
+      if (callCount === 1) {
+        return {
+          content: "",
+          toolCalls: [
+            { id: "call_a", name: "tool_a", arguments: '{"x":1}' },
+            { id: "call_b", name: "tool_b", arguments: '{"y":2}' },
+          ],
+          usage: { inputTokens: 20, outputTokens: 10 },
+        };
+      }
+      return { content: "两个工具都执行完了", usage: { inputTokens: 30, outputTokens: 8 } };
+    });
+
+    const messages: ChatRequest["messages"] = [{ role: "user", content: "同时用两个工具" }];
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages,
+      tools: [
+        { name: "tool_a", description: "工具A", parameters: {} },
+        { name: "tool_b", description: "工具B", parameters: {} },
+      ],
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+      conversationId: "conv-multi",
+    });
+
+    // 两个工具都应被执行
+    expect(executorA.execute).toHaveBeenCalledTimes(1);
+    expect(executorB.execute).toHaveBeenCalledTimes(1);
+
+    // messages: user + assistant(2 toolCalls) + tool_a_result + tool_b_result = 4
+    expect(messages.length).toBe(4);
+    expect(messages[1].role).toBe("assistant");
+    expect(messages[1].toolCalls).toHaveLength(2);
+    expect(messages[2].role).toBe("tool");
+    expect(messages[3].role).toBe("tool");
+
+    // 持久化：assistant(toolCalls) + 2个tool结果 + assistant(final) = 4
+    expect(mockRepo.appendMessage).toHaveBeenCalledTimes(4);
+    expect(mockRepo.appendMessage.mock.calls[1][0]).toMatchObject({ role: "tool", toolCallId: "call_a" });
+    expect(mockRepo.appendMessage.mock.calls[2][0]).toMatchObject({ role: "tool", toolCallId: "call_b" });
+
+    expect(events.find((e) => e.type === "done")).toBeDefined();
+    callLLMSpy.mockRestore();
+  });
+
+  it("skipBuiltinTools 时仅使用传入的 tools", async () => {
+    const { service, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // 注册一个内置工具
+    const builtinExecutor: ToolExecutor = {
+      execute: vi.fn().mockResolvedValue("builtin_result"),
+    };
+    toolRegistry.registerBuiltin(
+      { name: "builtin_tool", description: "内置工具", parameters: { type: "object", properties: {} } },
+      builtinExecutor
+    );
+
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("hello")));
+
+    // 用 skipBuiltinTools 调用，传入一个脚本工具
+    const scriptTools: ToolDefinition[] = [
+      { name: "script_tool", description: "脚本工具", parameters: { type: "object", properties: {} } },
+    ];
+
+    // mock callLLM 来检查传入的 tools
+    let capturedTools: ToolDefinition[] | undefined;
+    const callLLMSpy = vi
+      .spyOn(service as any, "callLLM")
+      .mockImplementation(async (_model: any, params: any, sendEvent: any) => {
+        capturedTools = params.tools;
+        sendEvent({ type: "done" });
+        return { content: "ok", usage: { inputTokens: 5, outputTokens: 3 } };
+      });
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      tools: scriptTools,
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+      skipBuiltinTools: true,
+    });
+
+    // 传给 callLLM 的 tools 应只有脚本工具，不含内置工具
+    expect(capturedTools).toHaveLength(1);
+    expect(capturedTools![0].name).toBe("script_tool");
+
+    callLLMSpy.mockRestore();
+  });
+
+  it("skipBuiltinTools 无 tools 传入时 allToolDefs 为空", async () => {
+    const { service, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // 注册内置工具
+    toolRegistry.registerBuiltin(
+      { name: "builtin_tool", description: "内置工具", parameters: { type: "object", properties: {} } },
+      { execute: vi.fn().mockResolvedValue("result") }
+    );
+
+    let capturedTools: ToolDefinition[] | undefined;
+    const callLLMSpy = vi
+      .spyOn(service as any, "callLLM")
+      .mockImplementation(async (_model: any, params: any, sendEvent: any) => {
+        capturedTools = params.tools;
+        sendEvent({ type: "done" });
+        return { content: "ok", usage: { inputTokens: 5, outputTokens: 3 } };
+      });
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      // 不传 tools
+      maxIterations: 5,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+      skipBuiltinTools: true,
+    });
+
+    // 不应有任何工具
+    expect(capturedTools).toBeUndefined();
+
+    callLLMSpy.mockRestore();
+  });
+
+  it("每轮循环应重新获取工具定义（支持动态注册）", async () => {
+    const { service, toolRegistry } = createTestService();
+    const events: ChatStreamEvent[] = [];
+
+    // 注册 load_skill 工具：第一次调用时动态注册 new_tool
+    const loadSkillExecutor: ToolExecutor = {
+      execute: vi.fn().mockImplementation(async () => {
+        // 模拟 load_skill 动态注册新工具
+        toolRegistry.registerBuiltin(
+          { name: "dynamic_tool", description: "动态注册的工具", parameters: { type: "object", properties: {} } },
+          { execute: vi.fn().mockResolvedValue("dynamic result") }
+        );
+        return "skill loaded";
+      }),
+    };
+    toolRegistry.registerBuiltin(
+      { name: "load_skill", description: "加载 Skill", parameters: { type: "object", properties: {} } },
+      loadSkillExecutor
+    );
+
+    // 第一轮：LLM 调用 load_skill
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_1", "load_skill", '{"skill_name":"test"}')));
+    // 第二轮：LLM 调用 dynamic_tool（动态注册的）
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeToolCallSSE("call_2", "dynamic_tool", "{}")));
+    // 第三轮：纯文本结束
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("完成")));
+
+    await (service as any).callLLMWithToolLoop({
+      model: openaiConfig,
+      messages: [{ role: "user", content: "test" }],
+      maxIterations: 10,
+      sendEvent: (e: ChatStreamEvent) => events.push(e),
+      signal: new AbortController().signal,
+      scriptToolCallback: null,
+    });
+
+    // fetch 应被调用 3 次（load_skill → dynamic_tool → 完成）
+    expect(fetchSpy).toHaveBeenCalledTimes(3);
+
+    // 第二次 fetch 的请求体应包含 dynamic_tool 定义
+    const secondCallBody = JSON.parse(fetchSpy.mock.calls[1][1]!.body as string);
+    const toolNames = secondCallBody.tools.map((t: any) => t.function.name);
+    expect(toolNames).toContain("dynamic_tool");
+
+    // 应有 done 事件
+    expect(events.find((e) => e.type === "done")).toBeDefined();
+
+    // 清理
+    toolRegistry.unregisterBuiltin("load_skill");
+    toolRegistry.unregisterBuiltin("dynamic_tool");
+  });
+});
+
+// ---- handleConversationChat ephemeral 测试 ----
+
+describe("handleConversationChat ephemeral 模式", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  // 辅助：创建 mock sender（connect 模式）
+  function createMockSender() {
+    const sentMessages: any[] = [];
+    let onMessageCb: ((msg: any) => void) | null = null;
+    let onDisconnectCb: (() => void) | null = null;
+
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: (cb: (msg: any) => void) => {
+        onMessageCb = cb;
+      },
+      onDisconnect: (cb: () => void) => {
+        onDisconnectCb = cb;
+      },
+      disconnect: () => {},
+    };
+
+    const sender = {
+      isType: (type: any) => type === 1, // GetSenderType.CONNECT = 1
+      getConnect: () => mockConn,
+    };
+
+    return { sender, sentMessages, mockConn, getOnMessage: () => onMessageCb, getOnDisconnect: () => onDisconnectCb };
+  }
+
+  it("ephemeral 模式不加载会话、不持久化", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    fetchSpy.mockResolvedValueOnce(
+      buildSSEResponse(makeTextSSE("ephemeral reply", { prompt_tokens: 10, completion_tokens: 5 }))
+    );
+
+    await (service as any).handleConversationChat(
+      {
+        conversationId: "eph-conv-1",
+        message: "hello",
+        ephemeral: true,
+        modelId: "test-openai",
+        messages: [{ role: "user", content: "hello" }],
+        system: "你是助手",
+        scriptUuid: "test-uuid",
+      },
+      sender
+    );
+
+    // 不应调用 repo 的 getMessages 或 listConversations（不加载会话）
+    expect(mockRepo.getMessages).not.toHaveBeenCalled();
+    expect(mockRepo.listConversations).not.toHaveBeenCalled();
+    // 不应调用 appendMessage（不持久化）
+    expect(mockRepo.appendMessage).not.toHaveBeenCalled();
+    // 不应调用 saveConversation
+    expect(mockRepo.saveConversation).not.toHaveBeenCalled();
+  });
+
+  it("ephemeral 模式使用传入的 messages 和 system", async () => {
+    const { service } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("回复", { prompt_tokens: 10, completion_tokens: 5 })));
+
+    await (service as any).handleConversationChat(
+      {
+        conversationId: "eph-conv-2",
+        message: "你好",
+        ephemeral: true,
+        modelId: "test-openai",
+        messages: [
+          { role: "user", content: "上一条" },
+          { role: "assistant", content: "上次回复" },
+          { role: "user", content: "你好" },
+        ],
+        system: "系统提示",
+        scriptUuid: "test-uuid",
+      },
+      sender
+    );
+
+    // 应该发送了 fetch 请求
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    // 检查 fetch 请求体中的消息
+    const fetchBody = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+    // 应包含 system + 3 条消息
+    expect(fetchBody.messages.length).toBeGreaterThanOrEqual(4);
+    // 第一条应是 system，包含内置提示词 + 用户自定义
+    expect(fetchBody.messages[0].role).toBe("system");
+    expect(fetchBody.messages[0].content).toContain("You are ScriptCat Agent");
+    expect(fetchBody.messages[0].content).toContain("系统提示");
+
+    // 应该发送了 done 事件
+    const doneMsg = sentMessages.find((m) => m.action === "event" && m.data.type === "done");
+    expect(doneMsg).toBeDefined();
+  });
+
+  it("ephemeral 模式使用 skipBuiltinTools", async () => {
+    const { service, toolRegistry } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    // 注册内置工具
+    toolRegistry.registerBuiltin(
+      { name: "dom_read_page", description: "读取页面", parameters: { type: "object", properties: {} } },
+      { execute: vi.fn().mockResolvedValue("page content") }
+    );
+
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("ok", { prompt_tokens: 5, completion_tokens: 3 })));
+
+    await (service as any).handleConversationChat(
+      {
+        conversationId: "eph-conv-3",
+        message: "test",
+        ephemeral: true,
+        modelId: "test-openai",
+        messages: [{ role: "user", content: "test" }],
+        scriptUuid: "test-uuid",
+      },
+      sender
+    );
+
+    // fetch 请求体中不应包含内置工具
+    const fetchBody = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+    expect(fetchBody.tools).toBeUndefined();
+
+    // 应正常完成
+    const doneMsg = sentMessages.find((m) => m.action === "event" && m.data.type === "done");
+    expect(doneMsg).toBeDefined();
+  });
+
+  it("ephemeral 模式带脚本工具时 tools 传入 callLLMWithToolLoop", async () => {
+    const { service } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    // mock callLLMWithToolLoop 来验证参数
+    let capturedParams: any;
+    const loopSpy = vi.spyOn(service as any, "callLLMWithToolLoop").mockImplementation(async (params: any) => {
+      capturedParams = params;
+      params.sendEvent({ type: "done", usage: { inputTokens: 5, outputTokens: 3 } });
+    });
+
+    await (service as any).handleConversationChat(
+      {
+        conversationId: "eph-conv-4",
+        message: "test",
+        ephemeral: true,
+        modelId: "test-openai",
+        messages: [{ role: "user", content: "test" }],
+        tools: [{ name: "my_script_tool", description: "脚本工具", parameters: {} }],
+        scriptUuid: "test-uuid",
+      },
+      sender
+    );
+
+    // 验证 callLLMWithToolLoop 收到正确参数
+    expect(capturedParams.skipBuiltinTools).toBe(true);
+    expect(capturedParams.tools).toHaveLength(1);
+    expect(capturedParams.tools[0].name).toBe("my_script_tool");
+    expect(capturedParams.scriptToolCallback).not.toBeNull();
+    // 不应有 conversationId（ephemeral 不持久化）
+    expect(capturedParams.conversationId).toBeUndefined();
+
+    // 应发送 done 事件
+    expect(sentMessages.some((m) => m.action === "event" && m.data.type === "done")).toBe(true);
+
+    loopSpy.mockRestore();
+  });
+
+  it("ephemeral 模式无 system 时不添加 system 消息", async () => {
+    const { service } = createTestService();
+    const { sender } = createMockSender();
+
+    fetchSpy.mockResolvedValueOnce(buildSSEResponse(makeTextSSE("ok", { prompt_tokens: 5, completion_tokens: 3 })));
+
+    await (service as any).handleConversationChat(
+      {
+        conversationId: "eph-conv-5",
+        message: "test",
+        ephemeral: true,
+        modelId: "test-openai",
+        messages: [{ role: "user", content: "test" }],
+        // 无 system
+        scriptUuid: "test-uuid",
+      },
+      sender
+    );
+
+    const fetchBody = JSON.parse(fetchSpy.mock.calls[0][1]!.body as string);
+    // 应有 system 消息（内置提示词），即使用户没传 system
+    const systemMsg = fetchBody.messages.find((m: any) => m.role === "system");
+    expect(systemMsg).toBeDefined();
+    expect(systemMsg.content).toContain("You are ScriptCat Agent");
+  });
+});
diff --git a/src/app/service/agent/cattool_executor.test.ts b/src/app/service/agent/cattool_executor.test.ts
new file mode 100644
index 000000000..f5a467790
--- /dev/null
+++ b/src/app/service/agent/cattool_executor.test.ts
@@ -0,0 +1,572 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import {
+  CATToolExecutor,
+  getCATToolNameByUuid,
+  getCATToolGrantsByUuid,
+  CATTOOL_UUID_PREFIX,
+  type RequireLoader,
+} from "./cattool_executor";
+import type { CATToolRecord } from "./types";
+
+function createRecord(params: CATToolRecord["params"] = [], overrides?: Partial<CATToolRecord>): CATToolRecord {
+  return {
+    id: "test-uuid-001",
+    name: "test_tool",
+    description: "测试工具",
+    params,
+    grants: [],
+    code: `// ==CATTool==
+// @name test_tool
+// ==/CATTool==
+return args.value;`,
+    installtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+// 创建 mock sender，sendMessage 返回 { data: response }
+function createMockSender(response: any = "mock_result") {
+  return {
+    sendMessage: vi.fn().mockResolvedValue({ data: response }),
+  } as any;
+}
+
+// 从 mock sender 的调用中提取传给 offscreen 的 params
+function getCallParams(sender: any) {
+  const call = sender.sendMessage.mock.calls[0][0];
+  // sendMessage 被调用为 sendMessage({ action, data })
+  return call.data;
+}
+
+describe("CATToolExecutor", () => {
+  it("应将 string 类型参数转换为字符串", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "city", type: "string", required: true, description: "城市" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ city: 123 });
+
+    const params = getCallParams(sender);
+    expect(params.args).toEqual({ city: "123" });
+  });
+
+  it("应将 number 类型参数转换为数字", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "count", type: "number", required: true, description: "数量" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ count: "42" });
+
+    const params = getCallParams(sender);
+    expect(params.args).toEqual({ count: 42 });
+  });
+
+  it("应将 boolean 类型参数转换为布尔值", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "verbose", type: "boolean", required: false, description: "详细模式" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ verbose: "true" });
+
+    const params = getCallParams(sender);
+    expect(params.args).toEqual({ verbose: true });
+  });
+
+  it('boolean 类型：非 true/"true" 应转换为 false', async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "verbose", type: "boolean", required: false, description: "详细模式" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ verbose: "false" });
+    expect(getCallParams(sender).args).toEqual({ verbose: false });
+
+    // 重置并测试 0
+    sender.sendMessage.mockClear();
+    sender.sendMessage.mockResolvedValue({ data: "mock_result" });
+    await executor.execute({ verbose: 0 });
+    expect(getCallParams(sender).args).toEqual({ verbose: false });
+  });
+
+  it("boolean 类型：true 值应保持为 true", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "flag", type: "boolean", required: false, description: "标记" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ flag: true });
+
+    expect(getCallParams(sender).args).toEqual({ flag: true });
+  });
+
+  it("应跳过 undefined 参数", async () => {
+    const sender = createMockSender();
+    const record = createRecord([
+      { name: "required_param", type: "string", required: true, description: "必须" },
+      { name: "optional_param", type: "string", required: false, description: "可选" },
+    ]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ required_param: "hello" });
+
+    expect(getCallParams(sender).args).toEqual({ required_param: "hello" });
+  });
+
+  it("应忽略不在定义中的额外参数", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "city", type: "string", required: true, description: "城市" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ city: "北京", extra: "should_be_ignored" });
+
+    expect(getCallParams(sender).args).toEqual({ city: "北京" });
+  });
+
+  it("应传递正确的 code（去除元数据头）和 grants", async () => {
+    const sender = createMockSender();
+    const record: CATToolRecord = {
+      id: "test-uuid-weather",
+      name: "weather",
+      description: "查天气",
+      params: [],
+      grants: ["GM.xmlHttpRequest"],
+      code: `// ==CATTool==
+// @name weather
+// ==/CATTool==
+const result = await GM.xmlHttpRequest({url: "http://example.com"});
+return result;`,
+      installtime: 1,
+      updatetime: 1,
+    };
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({});
+
+    const params = getCallParams(sender);
+    expect(params.grants).toEqual(["GM.xmlHttpRequest"]);
+    expect(params.name).toBe("weather");
+    expect(params.code).not.toContain("==CATTool==");
+  });
+
+  it("应处理多个混合类型参数", async () => {
+    const sender = createMockSender();
+    const record = createRecord([
+      { name: "city", type: "string", required: true, description: "城市" },
+      { name: "days", type: "number", required: false, description: "天数" },
+      { name: "detailed", type: "boolean", required: false, description: "详细" },
+    ]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ city: "上海", days: "7", detailed: "true" });
+
+    expect(getCallParams(sender).args).toEqual({ city: "上海", days: 7, detailed: true });
+  });
+
+  it("应生成 cattool- 前缀的 UUID", async () => {
+    const sender = createMockSender();
+    const record = createRecord();
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({});
+
+    const params = getCallParams(sender);
+    expect(params.uuid).toMatch(/^cattool-/);
+    expect(params.uuid.length).toBeGreaterThan(CATTOOL_UUID_PREFIX.length);
+  });
+
+  it("每次执行应生成不同的 UUID", async () => {
+    const sender = createMockSender();
+    const record = createRecord();
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({});
+    const uuid1 = getCallParams(sender).uuid;
+
+    sender.sendMessage.mockClear();
+    sender.sendMessage.mockResolvedValue({ data: "mock_result" });
+    await executor.execute({});
+    const uuid2 = getCallParams(sender).uuid;
+
+    expect(uuid1).not.toBe(uuid2);
+  });
+
+  it("执行期间应能通过 UUID 查找工具名，执行后应清理映射", async () => {
+    let capturedUuid = "";
+    const sender = {
+      sendMessage: vi.fn().mockImplementation((msg: any) => {
+        capturedUuid = msg.data.uuid;
+        // 执行期间映射应存在
+        expect(getCATToolNameByUuid(msg.data.uuid)).toBe("test_tool");
+        return Promise.resolve({ data: "result" });
+      }),
+    } as any;
+
+    const record = createRecord();
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({});
+
+    // 执行完成后映射应被清理
+    expect(capturedUuid).toBeTruthy();
+    expect(getCATToolNameByUuid(capturedUuid)).toBe("");
+  });
+
+  it("执行失败时也应清理 UUID 映射", async () => {
+    let capturedUuid = "";
+    const sender = {
+      sendMessage: vi.fn().mockImplementation((msg: any) => {
+        capturedUuid = msg.data.uuid;
+        return Promise.reject(new Error("执行失败"));
+      }),
+    } as any;
+
+    const record = createRecord();
+    const executor = new CATToolExecutor(record, sender);
+
+    await expect(executor.execute({})).rejects.toThrow("执行失败");
+
+    // 即使失败，映射也应被清理
+    expect(capturedUuid).toBeTruthy();
+    expect(getCATToolNameByUuid(capturedUuid)).toBe("");
+  });
+});
+
+describe("getCATToolNameByUuid", () => {
+  it("未注册的 UUID 应返回空字符串", () => {
+    expect(getCATToolNameByUuid("cattool-unknown-uuid")).toBe("");
+  });
+
+  it("空字符串应返回空字符串", () => {
+    expect(getCATToolNameByUuid("")).toBe("");
+  });
+});
+
+describe("getCATToolGrantsByUuid", () => {
+  it("未注册的 UUID 应返回空数组", () => {
+    expect(getCATToolGrantsByUuid("cattool-unknown-uuid")).toEqual([]);
+  });
+
+  it("执行期间应能通过 UUID 获取 grants", async () => {
+    let capturedUuid = "";
+    const sender = {
+      sendMessage: vi.fn().mockImplementation((msg: any) => {
+        capturedUuid = msg.data.uuid;
+        // 执行期间应能获取 grants
+        expect(getCATToolGrantsByUuid(msg.data.uuid)).toEqual(["CAT.agent.dom", "GM.xmlHttpRequest"]);
+        return Promise.resolve({ data: "result" });
+      }),
+    } as any;
+
+    const record = createRecord([], {
+      grants: ["CAT.agent.dom", "GM.xmlHttpRequest"],
+    });
+    const executor = new CATToolExecutor(record, sender);
+    await executor.execute({});
+
+    // 执行完成后应清理
+    expect(getCATToolGrantsByUuid(capturedUuid)).toEqual([]);
+  });
+
+  it("执行失败时也应清理 grants 映射", async () => {
+    let capturedUuid = "";
+    const sender = {
+      sendMessage: vi.fn().mockImplementation((msg: any) => {
+        capturedUuid = msg.data.uuid;
+        return Promise.reject(new Error("执行失败"));
+      }),
+    } as any;
+
+    const record = createRecord([], { grants: ["CAT.agent.dom"] });
+    const executor = new CATToolExecutor(record, sender);
+
+    await expect(executor.execute({})).rejects.toThrow("执行失败");
+    expect(getCATToolGrantsByUuid(capturedUuid)).toEqual([]);
+  });
+});
+
+describe("CATTOOL_UUID_PREFIX", () => {
+  it("应为 'cattool-'", () => {
+    expect(CATTOOL_UUID_PREFIX).toBe("cattool-");
+  });
+});
+
+describe("CATToolExecutor 类型转换边界值", () => {
+  it('boolean 转换："false" → false', async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "flag", type: "boolean", required: false, description: "标记" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ flag: "false" });
+    expect(getCallParams(sender).args).toEqual({ flag: false });
+  });
+
+  it('boolean 转换："0" → false', async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "flag", type: "boolean", required: false, description: "标记" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ flag: "0" });
+    expect(getCallParams(sender).args).toEqual({ flag: false });
+  });
+
+  it("boolean 转换：null → false", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "flag", type: "boolean", required: false, description: "标记" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ flag: null });
+    expect(getCallParams(sender).args).toEqual({ flag: false });
+  });
+
+  it('boolean 转换："true" → true（确认只有这个值和 true 为 true）', async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "flag", type: "boolean", required: false, description: "标记" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ flag: "true" });
+    expect(getCallParams(sender).args).toEqual({ flag: true });
+  });
+
+  it('number 转换："abc" → NaN', async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "count", type: "number", required: false, description: "数量" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ count: "abc" });
+    expect(getCallParams(sender).args.count).toBeNaN();
+  });
+
+  it('number 转换："" → 0', async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "count", type: "number", required: false, description: "数量" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ count: "" });
+    expect(getCallParams(sender).args).toEqual({ count: 0 });
+  });
+
+  it("number 转换：null → 0", async () => {
+    const sender = createMockSender();
+    const record = createRecord([{ name: "count", type: "number", required: false, description: "数量" }]);
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ count: null });
+    expect(getCallParams(sender).args).toEqual({ count: 0 });
+  });
+
+  it("空 params 定义但有多余 args：只传 metadata 中定义的参数", async () => {
+    const sender = createMockSender();
+    const record = createRecord([]); // 空 params
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({ extra1: "a", extra2: 123, extra3: true });
+    expect(getCallParams(sender).args).toEqual({});
+  });
+});
+
+describe("CATToolExecutor @require 加载", () => {
+  it("有 requires 和 requireLoader 时应加载资源并传给 executeCATTool", async () => {
+    const sender = createMockSender();
+    const record = createRecord([], {
+      requires: ["https://cdn.example.com/lib1.js", "https://cdn.example.com/lib2.js"],
+    });
+    const loader: RequireLoader = vi.fn().mockImplementation((url: string) => {
+      if (url.includes("lib1")) return Promise.resolve("var LIB1 = {};");
+      if (url.includes("lib2")) return Promise.resolve("var LIB2 = {};");
+      return Promise.resolve(undefined);
+    });
+    const executor = new CATToolExecutor(record, sender, loader);
+
+    await executor.execute({});
+
+    // requireLoader 应被调用两次
+    expect(loader).toHaveBeenCalledTimes(2);
+    expect(loader).toHaveBeenCalledWith("https://cdn.example.com/lib1.js");
+    expect(loader).toHaveBeenCalledWith("https://cdn.example.com/lib2.js");
+
+    // 传给 offscreen 的 params 应包含 requires
+    const params = getCallParams(sender);
+    expect(params.requires).toEqual([
+      { url: "https://cdn.example.com/lib1.js", content: "var LIB1 = {};" },
+      { url: "https://cdn.example.com/lib2.js", content: "var LIB2 = {};" },
+    ]);
+  });
+
+  it("无 requireLoader 时 requires 不应传给 executeCATTool", async () => {
+    const sender = createMockSender();
+    const record = createRecord([], {
+      requires: ["https://cdn.example.com/lib.js"],
+    });
+    // 不传 requireLoader
+    const executor = new CATToolExecutor(record, sender);
+
+    await executor.execute({});
+
+    const params = getCallParams(sender);
+    expect(params.requires).toBeUndefined();
+  });
+
+  it("无 requires 字段时不应调用 requireLoader", async () => {
+    const sender = createMockSender();
+    const record = createRecord(); // 默认无 requires
+    const loader: RequireLoader = vi.fn();
+    const executor = new CATToolExecutor(record, sender, loader);
+
+    await executor.execute({});
+
+    expect(loader).not.toHaveBeenCalled();
+    const params = getCallParams(sender);
+    expect(params.requires).toBeUndefined();
+  });
+
+  it("空 requires 数组时不应调用 requireLoader", async () => {
+    const sender = createMockSender();
+    const record = createRecord([], { requires: [] });
+    const loader: RequireLoader = vi.fn();
+    const executor = new CATToolExecutor(record, sender, loader);
+
+    await executor.execute({});
+
+    expect(loader).not.toHaveBeenCalled();
+    const params = getCallParams(sender);
+    expect(params.requires).toBeUndefined();
+  });
+
+  it("requireLoader 返回 undefined 的 URL 应被跳过", async () => {
+    const sender = createMockSender();
+    const record = createRecord([], {
+      requires: [
+        "https://cdn.example.com/good.js",
+        "https://cdn.example.com/missing.js",
+        "https://cdn.example.com/also-good.js",
+      ],
+    });
+    const loader: RequireLoader = vi.fn().mockImplementation((url: string) => {
+      if (url.includes("missing")) return Promise.resolve(undefined);
+      if (url.includes("also-good")) return Promise.resolve("var ALSO = 2;");
+      if (url.includes("good")) return Promise.resolve("var GOOD = 1;");
+      return Promise.resolve(undefined);
+    });
+    const executor = new CATToolExecutor(record, sender, loader);
+
+    await executor.execute({});
+
+    // loader 被调用 3 次
+    expect(loader).toHaveBeenCalledTimes(3);
+    // 只有成功加载的 2 个资源被传递
+    const params = getCallParams(sender);
+    expect(params.requires).toEqual([
+      { url: "https://cdn.example.com/good.js", content: "var GOOD = 1;" },
+      { url: "https://cdn.example.com/also-good.js", content: "var ALSO = 2;" },
+    ]);
+  });
+
+  it("所有 requireLoader 返回 undefined 时 requires 应为 undefined", async () => {
+    const sender = createMockSender();
+    const record = createRecord([], {
+      requires: ["https://cdn.example.com/missing1.js", "https://cdn.example.com/missing2.js"],
+    });
+    const loader: RequireLoader = vi.fn().mockResolvedValue(undefined);
+    const executor = new CATToolExecutor(record, sender, loader);
+
+    await executor.execute({});
+
+    const params = getCallParams(sender);
+    expect(params.requires).toBeUndefined();
+  });
+});
+
+describe("CATToolExecutor 超时处理", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("执行超过 30s 时应抛出带 errorCode=tool_timeout 的错误", async () => {
+    vi.useFakeTimers();
+
+    // sender.sendMessage 永不 resolve，模拟挂死的 CATTool
+    const sender = {
+      sendMessage: vi.fn().mockReturnValue(new Promise(() => {})),
+    } as any;
+
+    const record = createRecord([], { name: "hang_tool" });
+    const executor = new CATToolExecutor(record, sender);
+
+    // 先附加 catch 再推进时间，防止 rejection 在处理前被标记为 unhandled
+    const errPromise = executor.execute({}).catch((e) => e);
+
+    // 推进 30s 触发超时
+    await vi.advanceTimersByTimeAsync(30_000);
+
+    const err = await errPromise;
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("hang_tool");
+    expect((err as Error).message).toContain("timed out");
+    expect((err as any).errorCode).toBe("tool_timeout");
+  });
+
+  it("超时后 UUID 映射应被清理", async () => {
+    vi.useFakeTimers();
+
+    let capturedUuid = "";
+    const sender = {
+      sendMessage: vi.fn().mockImplementation((msg: any) => {
+        capturedUuid = msg.data.uuid;
+        return new Promise(() => {});
+      }),
+    } as any;
+
+    const record = createRecord([], { name: "hang_tool2" });
+    const executor = new CATToolExecutor(record, sender);
+
+    const execPromise = executor.execute({}).catch(() => {});
+    await vi.advanceTimersByTimeAsync(30_000);
+    await execPromise;
+
+    expect(capturedUuid).toMatch(/^cattool-/);
+    expect(getCATToolNameByUuid(capturedUuid)).toBe("");
+  });
+
+  it("自定义 timeout 应覆盖默认 30s", async () => {
+    vi.useFakeTimers();
+
+    const sender = {
+      sendMessage: vi.fn().mockReturnValue(new Promise(() => {})),
+    } as any;
+
+    const record = createRecord([], { name: "slow_tool", timeout: 120 });
+    const executor = new CATToolExecutor(record, sender);
+
+    const errPromise = executor.execute({}).catch((e) => e);
+
+    // 30s 后不应超时
+    await vi.advanceTimersByTimeAsync(30_000);
+    // 60s 后仍不应超时
+    await vi.advanceTimersByTimeAsync(30_000);
+
+    // 推进到 120s 触发超时
+    await vi.advanceTimersByTimeAsync(60_000);
+
+    const err = await errPromise;
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("slow_tool");
+    expect((err as Error).message).toContain("120s");
+    expect((err as any).errorCode).toBe("tool_timeout");
+  });
+
+  it("30s 内完成的执行不应超时", async () => {
+    vi.useFakeTimers();
+
+    const sender = {
+      sendMessage: vi.fn().mockResolvedValue({ data: "ok" }),
+    } as any;
+
+    const record = createRecord();
+    const executor = new CATToolExecutor(record, sender);
+
+    const execPromise = executor.execute({});
+    // 推进 5s，执行早已完成（mock 是 resolved）
+    await vi.advanceTimersByTimeAsync(5_000);
+
+    await expect(execPromise).resolves.toBeDefined();
+  });
+});
diff --git a/src/app/service/agent/cattool_executor.ts b/src/app/service/agent/cattool_executor.ts
new file mode 100644
index 000000000..9333fa80a
--- /dev/null
+++ b/src/app/service/agent/cattool_executor.ts
@@ -0,0 +1,109 @@
+import type { MessageSend } from "@Packages/message/types";
+import type { CATToolRecord, JsonValue } from "./types";
+import type { ToolExecutor } from "./tool_registry";
+import { getCATToolBody } from "@App/pkg/utils/cattool";
+import { executeCATTool } from "@App/app/service/offscreen/client";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+// CATTool UUID 前缀，用于在 GM API 请求中识别 CATTool
+export const CATTOOL_UUID_PREFIX = "cattool-";
+
+// CATTool 默认超时（ms）
+const CATTOOL_DEFAULT_TIMEOUT_MS = 30_000;
+
+// 全局的 CATTool UUID → 工具信息映射，供 GM API 权限验证时使用
+// 直接携带 grants，避免运行时再查 repo（skill 的 CATTool 不在 catToolRepo 中）
+// 注意：此 Map 在 SW 重启后会丢失，但 CATTool 执行是单次 request-response，
+// SW 重启会同时中断消息通道，所以映射丢失不会导致额外问题
+const cattoolUuidMap = new Map<string, { name: string; grants: string[] }>();
+
+// 根据 CATTool UUID 获取工具名
+export function getCATToolNameByUuid(uuid: string): string {
+  return cattoolUuidMap.get(uuid)?.name || "";
+}
+
+// 根据 CATTool UUID 直接获取 grants（用于 GM API 权限验证）
+export function getCATToolGrantsByUuid(uuid: string): string[] {
+  return cattoolUuidMap.get(uuid)?.grants || [];
+}
+
+// require 资源加载器类型：根据 URL 返回资源内容
+export type RequireLoader = (url: string) => Promise<string | undefined>;
+
+// CATTool 执行器，通过 Offscreen -> Sandbox 执行 CATTool 脚本
+export class CATToolExecutor implements ToolExecutor {
+  constructor(
+    private record: CATToolRecord,
+    private sender: MessageSend,
+    private requireLoader?: RequireLoader,
+    private configValues?: Record<string, unknown>
+  ) {}
+
+  async execute(args: Record<string, unknown>): Promise<JsonValue> {
+    // 根据 @param 定义做基本的类型转换
+    const typedArgs: Record<string, unknown> = {};
+    for (const param of this.record.params) {
+      const val = args[param.name];
+      if (val === undefined) continue;
+      switch (param.type) {
+        case "number":
+          typedArgs[param.name] = Number(val);
+          break;
+        case "boolean":
+          typedArgs[param.name] = val === true || val === "true";
+          break;
+        default:
+          typedArgs[param.name] = String(val);
+      }
+    }
+
+    // 在 service worker 端生成 UUID 并注册映射
+    const uuid = CATTOOL_UUID_PREFIX + uuidv4();
+    cattoolUuidMap.set(uuid, { name: this.record.name, grants: this.record.grants });
+
+    // 加载 @require 资源内容
+    let requires: Array<{ url: string; content: string }> | undefined;
+    if (this.record.requires?.length && this.requireLoader) {
+      const loaded: Array<{ url: string; content: string }> = [];
+      for (const url of this.record.requires) {
+        const content = await this.requireLoader(url);
+        if (content) {
+          loaded.push({ url, content });
+        }
+      }
+      if (loaded.length > 0) {
+        requires = loaded;
+      }
+    }
+
+    const code = getCATToolBody(this.record.code);
+    const timeoutMs = this.record.timeout ? this.record.timeout * 1000 : CATTOOL_DEFAULT_TIMEOUT_MS;
+    const timeoutSec = timeoutMs / 1000;
+    try {
+      const execPromise = executeCATTool(this.sender, {
+        uuid,
+        code,
+        args: typedArgs,
+        grants: this.record.grants,
+        name: this.record.name,
+        requires,
+        configValues: this.configValues,
+      });
+      const timeoutPromise = new Promise<never>((_, reject) =>
+        setTimeout(
+          () =>
+            reject(
+              Object.assign(new Error(`CATTool "${this.record.name}" timed out after ${timeoutSec}s`), {
+                errorCode: "tool_timeout",
+              })
+            ),
+          timeoutMs
+        )
+      );
+      return await Promise.race([execPromise, timeoutPromise]);
+    } finally {
+      // 执行完毕后清理映射
+      cattoolUuidMap.delete(uuid);
+    }
+  }
+}
diff --git a/src/app/service/agent/content_utils.test.ts b/src/app/service/agent/content_utils.test.ts
new file mode 100644
index 000000000..2dd6cce39
--- /dev/null
+++ b/src/app/service/agent/content_utils.test.ts
@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { getTextContent, normalizeContent, isContentBlocks } from "./content_utils";
+import type { ContentBlock } from "./types";
+
+describe("content_utils", () => {
+  describe("getTextContent", () => {
+    it("returns string content as-is", () => {
+      expect(getTextContent("hello world")).toBe("hello world");
+    });
+
+    it("returns empty string for empty string", () => {
+      expect(getTextContent("")).toBe("");
+    });
+
+    it("extracts text from ContentBlock[]", () => {
+      const blocks: ContentBlock[] = [
+        { type: "text", text: "Hello " },
+        { type: "image", attachmentId: "img1", mimeType: "image/png", name: "test.png" },
+        { type: "text", text: "world" },
+      ];
+      expect(getTextContent(blocks)).toBe("Hello world");
+    });
+
+    it("returns empty string for ContentBlock[] with no text blocks", () => {
+      const blocks: ContentBlock[] = [
+        { type: "image", attachmentId: "img1", mimeType: "image/png" },
+        { type: "file", attachmentId: "f1", mimeType: "application/pdf", name: "doc.pdf" },
+      ];
+      expect(getTextContent(blocks)).toBe("");
+    });
+
+    it("returns empty string for empty ContentBlock[]", () => {
+      expect(getTextContent([])).toBe("");
+    });
+
+    it("handles audio blocks (skipped in text extraction)", () => {
+      const blocks: ContentBlock[] = [
+        { type: "text", text: "Listen: " },
+        { type: "audio", attachmentId: "a1", mimeType: "audio/wav", name: "clip.wav", durationMs: 5000 },
+      ];
+      expect(getTextContent(blocks)).toBe("Listen: ");
+    });
+  });
+
+  describe("normalizeContent", () => {
+    it("converts string to TextBlock[]", () => {
+      expect(normalizeContent("hello")).toEqual([{ type: "text", text: "hello" }]);
+    });
+
+    it("returns empty array for empty string", () => {
+      expect(normalizeContent("")).toEqual([]);
+    });
+
+    it("returns ContentBlock[] as-is", () => {
+      const blocks: ContentBlock[] = [
+        { type: "text", text: "hello" },
+        { type: "image", attachmentId: "img1", mimeType: "image/png" },
+      ];
+      expect(normalizeContent(blocks)).toBe(blocks);
+    });
+
+    it("returns empty array as-is", () => {
+      const blocks: ContentBlock[] = [];
+      expect(normalizeContent(blocks)).toBe(blocks);
+    });
+  });
+
+  describe("isContentBlocks", () => {
+    it("returns false for string", () => {
+      expect(isContentBlocks("hello")).toBe(false);
+    });
+
+    it("returns true for ContentBlock[]", () => {
+      expect(isContentBlocks([{ type: "text", text: "hello" }])).toBe(true);
+    });
+
+    it("returns true for empty array", () => {
+      expect(isContentBlocks([])).toBe(true);
+    });
+  });
+});
diff --git a/src/app/service/agent/content_utils.ts b/src/app/service/agent/content_utils.ts
new file mode 100644
index 000000000..8dbc591eb
--- /dev/null
+++ b/src/app/service/agent/content_utils.ts
@@ -0,0 +1,33 @@
+import type { MessageContent, ContentBlock } from "./types";
+
+/**
+ * 从 MessageContent 提取纯文本（用于 copy、搜索、标题生成等）
+ * - string: 直接返回
+ * - ContentBlock[]: 连接所有 TextBlock 的 text
+ */
+export function getTextContent(content: MessageContent): string {
+  if (typeof content === "string") return content;
+  return content
+    .filter((b): b is Extract<ContentBlock, { type: "text" }> => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+}
+
+/**
+ * 将 MessageContent 统一为 ContentBlock[]
+ * - string: 转为 [{ type: "text", text }]
+ * - ContentBlock[]: 原样返回
+ */
+export function normalizeContent(content: MessageContent): ContentBlock[] {
+  if (typeof content === "string") {
+    return content ? [{ type: "text", text: content }] : [];
+  }
+  return content;
+}
+
+/**
+ * 类型守卫：判断 content 是否为 ContentBlock[]
+ */
+export function isContentBlocks(content: MessageContent): content is ContentBlock[] {
+  return Array.isArray(content);
+}
diff --git a/src/app/service/agent/mcp_client.test.ts b/src/app/service/agent/mcp_client.test.ts
new file mode 100644
index 000000000..3b3eeedcf
--- /dev/null
+++ b/src/app/service/agent/mcp_client.test.ts
@@ -0,0 +1,430 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MCPClient } from "./mcp_client";
+import type { MCPServerConfig } from "./types";
+
+// Mock fetch
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+
+function createConfig(overrides?: Partial<MCPServerConfig>): MCPServerConfig {
+  return {
+    id: "test-server",
+    name: "Test Server",
+    url: "https://mcp.example.com/rpc",
+    enabled: true,
+    createtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+function jsonResponse(result: unknown, headers?: Record<string, string>): Response {
+  const h = new Headers({ "Content-Type": "application/json", ...headers });
+  return new Response(JSON.stringify({ jsonrpc: "2.0", id: 1, result }), {
+    status: 200,
+    headers: h,
+  });
+}
+
+function jsonErrorResponse(code: number, message: string): Response {
+  return new Response(JSON.stringify({ jsonrpc: "2.0", id: 1, error: { code, message } }), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function httpErrorResponse(status: number, body = ""): Response {
+  return new Response(body, { status, headers: { "Content-Type": "text/plain" } });
+}
+
+describe("MCPClient", () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  describe("initialize", () => {
+    it("应正确发送 initialize 和 initialized 请求", async () => {
+      const client = new MCPClient(createConfig());
+
+      // initialize response
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          serverInfo: { name: "TestServer", version: "1.0" },
+        })
+      );
+      // initialized notification response
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+
+      await client.initialize();
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+
+      // 第一个请求是 initialize
+      const firstCall = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(firstCall.method).toBe("initialize");
+      expect(firstCall.id).toBeDefined();
+      expect(firstCall.params.protocolVersion).toBe("2025-03-26");
+
+      // 第二个请求是 initialized 通知（无 id）
+      const secondCall = JSON.parse(mockFetch.mock.calls[1][1].body);
+      expect(secondCall.method).toBe("notifications/initialized");
+      expect(secondCall.id).toBeUndefined();
+
+      expect(client.isInitialized()).toBe(true);
+    });
+
+    it("initialize 响应缺少 protocolVersion 时应抛出错误", async () => {
+      const client = new MCPClient(createConfig());
+      mockFetch.mockResolvedValueOnce(jsonResponse({}));
+
+      await expect(client.initialize()).rejects.toThrow("missing protocolVersion");
+    });
+
+    it("HTTP 错误时应抛出", async () => {
+      const client = new MCPClient(createConfig());
+      mockFetch.mockResolvedValueOnce(httpErrorResponse(500, "Internal Server Error"));
+
+      await expect(client.initialize()).rejects.toThrow("500");
+    });
+  });
+
+  describe("listTools", () => {
+    it("应正确解析 tools/list 响应", async () => {
+      const client = new MCPClient(createConfig());
+
+      // initialize
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      // listTools
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          tools: [
+            {
+              name: "search",
+              description: "Search the web",
+              inputSchema: { type: "object", properties: { query: { type: "string" } } },
+            },
+          ],
+        })
+      );
+
+      const tools = await client.listTools();
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe("search");
+      expect(tools[0].serverId).toBe("test-server");
+      expect(tools[0].description).toBe("Search the web");
+    });
+
+    it("未初始化时应抛出错误", async () => {
+      const client = new MCPClient(createConfig());
+      await expect(client.listTools()).rejects.toThrow("not initialized");
+    });
+  });
+
+  describe("callTool", () => {
+    async function initClient(): Promise<MCPClient> {
+      const client = new MCPClient(createConfig());
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+      return client;
+    }
+
+    it("应正确发送 tools/call 并返回文本结果", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          content: [{ type: "text", text: "Result from tool" }],
+        })
+      );
+
+      const result = await client.callTool("search", { query: "hello" });
+      expect(result).toBe("Result from tool");
+
+      const lastCall = JSON.parse(mockFetch.mock.lastCall![1].body);
+      expect(lastCall.method).toBe("tools/call");
+      expect(lastCall.params.name).toBe("search");
+      expect(lastCall.params.arguments).toEqual({ query: "hello" });
+    });
+
+    it("isError 时应抛出错误", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          content: [{ type: "text", text: "Something went wrong" }],
+          isError: true,
+        })
+      );
+
+      await expect(client.callTool("search", { query: "fail" })).rejects.toThrow("Something went wrong");
+    });
+
+    it("多内容时应返回完整 content 数组", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          content: [
+            { type: "text", text: "Part 1" },
+            { type: "image", data: "base64data", mimeType: "image/png" },
+          ],
+        })
+      );
+
+      const result = await client.callTool("multi", {});
+      expect(Array.isArray(result)).toBe(true);
+      expect((result as any[]).length).toBe(2);
+    });
+  });
+
+  describe("listResources / readResource", () => {
+    async function initClient(): Promise<MCPClient> {
+      const client = new MCPClient(createConfig());
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+      return client;
+    }
+
+    it("应正确解析 resources/list", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          resources: [{ uri: "file:///docs/readme.md", name: "README", mimeType: "text/markdown" }],
+        })
+      );
+
+      const resources = await client.listResources();
+      expect(resources).toHaveLength(1);
+      expect(resources[0].uri).toBe("file:///docs/readme.md");
+      expect(resources[0].serverId).toBe("test-server");
+    });
+
+    it("应正确读取资源", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          contents: [{ uri: "file:///docs/readme.md", text: "# Hello", mimeType: "text/markdown" }],
+        })
+      );
+
+      const result = await client.readResource("file:///docs/readme.md");
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0].text).toBe("# Hello");
+    });
+  });
+
+  describe("listPrompts / getPrompt", () => {
+    async function initClient(): Promise<MCPClient> {
+      const client = new MCPClient(createConfig());
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+      return client;
+    }
+
+    it("应正确解析 prompts/list", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          prompts: [
+            {
+              name: "summarize",
+              description: "Summarize text",
+              arguments: [{ name: "text", required: true }],
+            },
+          ],
+        })
+      );
+
+      const prompts = await client.listPrompts();
+      expect(prompts).toHaveLength(1);
+      expect(prompts[0].name).toBe("summarize");
+      expect(prompts[0].arguments).toHaveLength(1);
+    });
+
+    it("应正确获取 prompt 消息", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          messages: [{ role: "user", content: { type: "text", text: "Summarize: hello world" } }],
+        })
+      );
+
+      const messages = await client.getPrompt("summarize", { text: "hello world" });
+      expect(messages).toHaveLength(1);
+      expect(messages[0].role).toBe("user");
+    });
+  });
+
+  describe("Session ID 管理", () => {
+    it("应存储并回传 Mcp-Session-Id", async () => {
+      const client = new MCPClient(createConfig());
+
+      // initialize 返回 session id
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }, { "Mcp-Session-Id": "session-123" })
+      );
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      // 后续请求应包含 session id
+      mockFetch.mockResolvedValueOnce(jsonResponse({ tools: [] }));
+      await client.listTools();
+
+      const lastCallHeaders = mockFetch.mock.lastCall![1].headers;
+      expect(lastCallHeaders["Mcp-Session-Id"]).toBe("session-123");
+    });
+  });
+
+  describe("JSON-RPC 错误处理", () => {
+    it("应正确处理 JSON-RPC 错误", async () => {
+      const client = new MCPClient(createConfig());
+
+      // initialize 返回 JSON-RPC 错误
+      mockFetch.mockResolvedValueOnce(jsonErrorResponse(-32600, "Invalid Request"));
+
+      await expect(client.initialize()).rejects.toThrow("MCP error -32600: Invalid Request");
+    });
+  });
+
+  describe("认证头", () => {
+    it("应设置 Bearer token", async () => {
+      const client = new MCPClient(createConfig({ apiKey: "sk-test-key" }));
+
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      const headers = mockFetch.mock.calls[0][1].headers;
+      expect(headers["Authorization"]).toBe("Bearer sk-test-key");
+    });
+
+    it("应设置自定义 headers", async () => {
+      const client = new MCPClient(createConfig({ headers: { "X-Custom": "custom-value" } }));
+
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      const headers = mockFetch.mock.calls[0][1].headers;
+      expect(headers["X-Custom"]).toBe("custom-value");
+    });
+  });
+
+  describe("close", () => {
+    it("close 后应标记为未初始化", async () => {
+      const client = new MCPClient(createConfig());
+
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      expect(client.isInitialized()).toBe(true);
+      client.close();
+      expect(client.isInitialized()).toBe(false);
+    });
+
+    it("close 后调用 listTools 应抛出 not initialized", async () => {
+      const client = new MCPClient(createConfig());
+
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      client.close();
+      await expect(client.listTools()).rejects.toThrow("not initialized");
+    });
+
+    it("close 后调用 callTool 应抛出 not initialized", async () => {
+      const client = new MCPClient(createConfig());
+
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+
+      client.close();
+      await expect(client.callTool("search", { q: "test" })).rejects.toThrow("not initialized");
+    });
+  });
+
+  describe("callTool 边界场景", () => {
+    async function initClient(): Promise<MCPClient> {
+      const client = new MCPClient(createConfig());
+      mockFetch.mockResolvedValueOnce(jsonResponse({ protocolVersion: "2025-03-26", capabilities: {} }));
+      mockFetch.mockResolvedValueOnce(new Response(null, { status: 200 }));
+      await client.initialize();
+      return client;
+    }
+
+    it("callTool 无参数调用：不传 args → 发送 arguments: {}", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          content: [{ type: "text", text: "no args result" }],
+        })
+      );
+
+      const result = await client.callTool("ping");
+      expect(result).toBe("no args result");
+
+      const lastCall = JSON.parse(mockFetch.mock.lastCall![1].body);
+      expect(lastCall.method).toBe("tools/call");
+      expect(lastCall.params.name).toBe("ping");
+      expect(lastCall.params.arguments).toEqual({});
+    });
+
+    it("callTool JSON-RPC 错误：返回 JSON-RPC error → 抛出 MCP error", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(jsonErrorResponse(-32601, "Method not found"));
+
+      await expect(client.callTool("unknown_tool", {})).rejects.toThrow("MCP error -32601: Method not found");
+    });
+
+    it("callTool 空 content：返回空 content 数组", async () => {
+      const client = await initClient();
+
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          content: [],
+        })
+      );
+
+      const result = await client.callTool("empty", {});
+      // 空 content，不是单个 text，返回整个 content 数组
+      expect(Array.isArray(result)).toBe(true);
+      expect((result as any[]).length).toBe(0);
+    });
+  });
+
+  describe("sendNotification 失败", () => {
+    it("initialize 过程中通知失败应抛出", async () => {
+      const client = new MCPClient(createConfig());
+
+      // initialize 请求成功
+      mockFetch.mockResolvedValueOnce(
+        jsonResponse({
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          serverInfo: { name: "TestServer", version: "1.0" },
+        })
+      );
+      // initialized 通知失败（HTTP error）
+      mockFetch.mockResolvedValueOnce(httpErrorResponse(503, "Service Unavailable"));
+
+      await expect(client.initialize()).rejects.toThrow("503");
+    });
+  });
+});
diff --git a/src/app/service/agent/mcp_client.ts b/src/app/service/agent/mcp_client.ts
new file mode 100644
index 000000000..ded33d610
--- /dev/null
+++ b/src/app/service/agent/mcp_client.ts
@@ -0,0 +1,246 @@
+import type { MCPServerConfig, MCPTool, MCPResource, MCPPrompt, MCPPromptMessage } from "./types";
+
+// JSON-RPC 2.0 请求
+type JsonRpcRequest = {
+  jsonrpc: "2.0";
+  id?: number;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+// JSON-RPC 2.0 响应
+type JsonRpcResponse = {
+  jsonrpc: "2.0";
+  id?: number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+// MCP 协议版本
+const MCP_PROTOCOL_VERSION = "2025-03-26";
+
+// MCP Client — JSON-RPC 2.0 over Streamable HTTP (POST only)
+export class MCPClient {
+  private nextId = 1;
+  private sessionId?: string;
+  private initialized = false;
+
+  constructor(private config: MCPServerConfig) {}
+
+  // 初始化：交换协议版本和能力
+  async initialize(): Promise<void> {
+    const result = (await this.sendRequest("initialize", {
+      protocolVersion: MCP_PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "ScriptCat", version: "1.0.0" },
+    })) as {
+      protocolVersion: string;
+      capabilities: Record<string, unknown>;
+      serverInfo?: { name: string; version?: string };
+    };
+
+    if (!result || !result.protocolVersion) {
+      throw new Error("Invalid initialize response: missing protocolVersion");
+    }
+
+    // 发送 initialized 通知（无 id = 通知）
+    await this.sendNotification("notifications/initialized", {});
+    this.initialized = true;
+  }
+
+  // ---- Tools ----
+
+  async listTools(): Promise<MCPTool[]> {
+    this.ensureInitialized();
+    const result = (await this.sendRequest("tools/list", {})) as {
+      tools: Array<{ name: string; description?: string; inputSchema: Record<string, unknown> }>;
+    };
+    return (result.tools || []).map((t) => ({
+      serverId: this.config.id,
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+    }));
+  }
+
+  async callTool(name: string, args?: Record<string, unknown>): Promise<unknown> {
+    this.ensureInitialized();
+    const result = (await this.sendRequest("tools/call", {
+      name,
+      arguments: args || {},
+    })) as {
+      content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+      isError?: boolean;
+    };
+
+    if (result.isError) {
+      const errorText = result.content?.map((c) => c.text || "").join("\n") || "Tool call failed";
+      throw new Error(errorText);
+    }
+
+    // 返回文本内容或完整 content
+    if (result.content?.length === 1 && result.content[0].type === "text") {
+      return result.content[0].text;
+    }
+    return result.content;
+  }
+
+  // ---- Resources ----
+
+  async listResources(): Promise<MCPResource[]> {
+    this.ensureInitialized();
+    const result = (await this.sendRequest("resources/list", {})) as {
+      resources: Array<{ uri: string; name: string; description?: string; mimeType?: string }>;
+    };
+    return (result.resources || []).map((r) => ({
+      serverId: this.config.id,
+      uri: r.uri,
+      name: r.name,
+      description: r.description,
+      mimeType: r.mimeType,
+    }));
+  }
+
+  async readResource(
+    uri: string
+  ): Promise<{ contents: Array<{ uri: string; text?: string; blob?: string; mimeType?: string }> }> {
+    this.ensureInitialized();
+    return (await this.sendRequest("resources/read", { uri })) as {
+      contents: Array<{ uri: string; text?: string; blob?: string; mimeType?: string }>;
+    };
+  }
+
+  // ---- Prompts ----
+
+  async listPrompts(): Promise<MCPPrompt[]> {
+    this.ensureInitialized();
+    const result = (await this.sendRequest("prompts/list", {})) as {
+      prompts: Array<{
+        name: string;
+        description?: string;
+        arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+      }>;
+    };
+    return (result.prompts || []).map((p) => ({
+      serverId: this.config.id,
+      name: p.name,
+      description: p.description,
+      arguments: p.arguments,
+    }));
+  }
+
+  async getPrompt(name: string, args?: Record<string, string>): Promise<MCPPromptMessage[]> {
+    this.ensureInitialized();
+    const result = (await this.sendRequest("prompts/get", {
+      name,
+      arguments: args || {},
+    })) as {
+      messages: MCPPromptMessage[];
+    };
+    return result.messages || [];
+  }
+
+  // ---- Lifecycle ----
+
+  close(): void {
+    this.initialized = false;
+    this.sessionId = undefined;
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  // ---- Internal ----
+
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error("MCPClient not initialized. Call initialize() first.");
+    }
+  }
+
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    };
+
+    // 认证
+    if (this.config.apiKey) {
+      headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+    }
+
+    // 自定义 headers
+    if (this.config.headers) {
+      Object.assign(headers, this.config.headers);
+    }
+
+    // Session ID
+    if (this.sessionId) {
+      headers["Mcp-Session-Id"] = this.sessionId;
+    }
+
+    return headers;
+  }
+
+  async sendRequest(method: string, params?: Record<string, unknown>): Promise<unknown> {
+    const id = this.nextId++;
+    const body: JsonRpcRequest = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    };
+
+    const response = await fetch(this.config.url, {
+      method: "POST",
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    });
+
+    // 存储 session ID
+    const sessionId = response.headers.get("Mcp-Session-Id");
+    if (sessionId) {
+      this.sessionId = sessionId;
+    }
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(`MCP request failed: ${response.status} ${errorText}`);
+    }
+
+    const json = (await response.json()) as JsonRpcResponse;
+
+    if (json.error) {
+      throw new Error(`MCP error ${json.error.code}: ${json.error.message}`);
+    }
+
+    return json.result;
+  }
+
+  private async sendNotification(method: string, params?: Record<string, unknown>): Promise<void> {
+    const body: JsonRpcRequest = {
+      jsonrpc: "2.0",
+      method,
+      params,
+    };
+
+    const response = await fetch(this.config.url, {
+      method: "POST",
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    });
+
+    // 存储 session ID
+    const sessionId = response.headers.get("Mcp-Session-Id");
+    if (sessionId) {
+      this.sessionId = sessionId;
+    }
+
+    // 通知不需要响应体，但检查状态码
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(`MCP notification failed: ${response.status} ${errorText}`);
+    }
+  }
+}
diff --git a/src/app/service/agent/mcp_tool_executor.test.ts b/src/app/service/agent/mcp_tool_executor.test.ts
new file mode 100644
index 000000000..d01415e63
--- /dev/null
+++ b/src/app/service/agent/mcp_tool_executor.test.ts
@@ -0,0 +1,114 @@
+import { describe, it, expect, vi } from "vitest";
+import { MCPToolExecutor } from "./mcp_tool_executor";
+import type { MCPClient } from "./mcp_client";
+
+function createMockClient(callToolResult: unknown): MCPClient {
+  return {
+    callTool: vi.fn().mockResolvedValue(callToolResult),
+  } as unknown as MCPClient;
+}
+
+describe("MCPToolExecutor", () => {
+  it("应将参数透传给 MCPClient.callTool 并返回结果", async () => {
+    const client = createMockClient("tool result");
+    const executor = new MCPToolExecutor(client, "search");
+
+    const result = await executor.execute({ query: "hello" });
+
+    expect(result).toBe("tool result");
+    expect(client.callTool).toHaveBeenCalledWith("search", { query: "hello" });
+  });
+
+  it("应正确传递工具名", async () => {
+    const client = createMockClient({ data: [1, 2, 3] });
+    const executor = new MCPToolExecutor(client, "fetch_data");
+
+    const result = await executor.execute({ limit: 10 });
+
+    expect(result).toEqual({ data: [1, 2, 3] });
+    expect(client.callTool).toHaveBeenCalledWith("fetch_data", { limit: 10 });
+  });
+
+  it("callTool 抛出异常时应向上传播", async () => {
+    const client = {
+      callTool: vi.fn().mockRejectedValue(new Error("MCP error")),
+    } as unknown as MCPClient;
+    const executor = new MCPToolExecutor(client, "failing_tool");
+
+    await expect(executor.execute({})).rejects.toThrow("MCP error");
+  });
+
+  it("包含 image 类型的 content 应转换为 ToolResultWithAttachments", async () => {
+    const mcpContent = [
+      { type: "text", text: "Here is the screenshot" },
+      { type: "image", data: "iVBORw0KGgo=", mimeType: "image/png" },
+    ];
+    const client = createMockClient(mcpContent);
+    const executor = new MCPToolExecutor(client, "screenshot_tool");
+
+    const result = await executor.execute({});
+
+    expect(result).toEqual({
+      content: "Here is the screenshot",
+      attachments: [
+        {
+          type: "image",
+          name: "image.png",
+          mimeType: "image/png",
+          data: "data:image/png;base64,iVBORw0KGgo=",
+        },
+      ],
+    });
+  });
+
+  it("多个 image 内容应全部转换为附件", async () => {
+    const mcpContent = [
+      { type: "image", data: "abc123", mimeType: "image/jpeg" },
+      { type: "image", data: "def456", mimeType: "image/png" },
+    ];
+    const client = createMockClient(mcpContent);
+    const executor = new MCPToolExecutor(client, "multi_image");
+
+    const result = (await executor.execute({})) as any;
+
+    expect(result.content).toBe("Tool completed.");
+    expect(result.attachments).toHaveLength(2);
+    expect(result.attachments[0].mimeType).toBe("image/jpeg");
+    expect(result.attachments[0].name).toBe("image.jpeg");
+    expect(result.attachments[1].mimeType).toBe("image/png");
+  });
+
+  it("只包含 text 的 content 数组应原样返回", async () => {
+    const mcpContent = [
+      { type: "text", text: "Line 1" },
+      { type: "text", text: "Line 2" },
+    ];
+    const client = createMockClient(mcpContent);
+    const executor = new MCPToolExecutor(client, "text_tool");
+
+    const result = await executor.execute({});
+
+    // 没有 image，原样返回 content 数组
+    expect(result).toEqual(mcpContent);
+  });
+
+  it("非数组结果应原样返回", async () => {
+    const client = createMockClient("plain string result");
+    const executor = new MCPToolExecutor(client, "simple_tool");
+
+    const result = await executor.execute({});
+
+    expect(result).toBe("plain string result");
+  });
+
+  it("image 缺少 mimeType 时应默认为 image/png", async () => {
+    const mcpContent = [{ type: "image", data: "abc123" }];
+    const client = createMockClient(mcpContent);
+    const executor = new MCPToolExecutor(client, "no_mime");
+
+    const result = (await executor.execute({})) as any;
+
+    expect(result.attachments[0].mimeType).toBe("image/png");
+    expect(result.attachments[0].data).toBe("data:image/png;base64,abc123");
+  });
+});
diff --git a/src/app/service/agent/mcp_tool_executor.ts b/src/app/service/agent/mcp_tool_executor.ts
new file mode 100644
index 000000000..88dbafc6d
--- /dev/null
+++ b/src/app/service/agent/mcp_tool_executor.ts
@@ -0,0 +1,43 @@
+import type { MCPClient } from "./mcp_client";
+import type { ToolExecutor } from "./tool_registry";
+import type { ToolResultWithAttachments } from "./types";
+
+// MCP 工具执行器，将 ToolExecutor 接口桥接到 MCPClient.callTool
+export class MCPToolExecutor implements ToolExecutor {
+  constructor(
+    private client: MCPClient,
+    private toolName: string
+  ) {}
+
+  async execute(args: Record<string, unknown>): Promise<unknown> {
+    const result = await this.client.callTool(this.toolName, args);
+
+    // 检测 MCP 返回的 content 数组是否包含 image 类型
+    if (Array.isArray(result)) {
+      const textParts: string[] = [];
+      const attachments: ToolResultWithAttachments["attachments"] = [];
+
+      for (const item of result) {
+        if (item.type === "text" && item.text) {
+          textParts.push(item.text);
+        } else if (item.type === "image" && item.data) {
+          attachments.push({
+            type: "image",
+            name: "image." + (item.mimeType?.split("/")[1] || "png"),
+            mimeType: item.mimeType || "image/png",
+            data: `data:${item.mimeType || "image/png"};base64,${item.data}`,
+          });
+        }
+      }
+
+      if (attachments.length > 0) {
+        return {
+          content: textParts.join("\n") || "Tool completed.",
+          attachments,
+        } as ToolResultWithAttachments;
+      }
+    }
+
+    return result;
+  }
+}
diff --git a/src/app/service/agent/providers/anthropic.test.ts b/src/app/service/agent/providers/anthropic.test.ts
new file mode 100644
index 000000000..0140ae9cc
--- /dev/null
+++ b/src/app/service/agent/providers/anthropic.test.ts
@@ -0,0 +1,438 @@
+import { describe, it, expect } from "vitest";
+import { buildAnthropicRequest, parseAnthropicStream } from "./anthropic";
+import type { AgentModelConfig } from "../types";
+import type { ChatRequest, ChatStreamEvent } from "../types";
+
+const config: AgentModelConfig = {
+  id: "test",
+  name: "Test",
+  provider: "anthropic",
+  apiBaseUrl: "https://api.anthropic.com",
+  apiKey: "sk-ant-test",
+  model: "claude-sonnet-4-20250514",
+};
+
+describe("buildAnthropicRequest", () => {
+  it("多个 system 消息应合并为单个", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [
+        { role: "system", content: "你是助手" },
+        { role: "system", content: "请用中文回答" },
+        { role: "user", content: "你好" },
+      ],
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    expect(body.system).toEqual([
+      { type: "text", text: "你是助手" },
+      { type: "text", text: "请用中文回答", cache_control: { type: "ephemeral" } },
+    ]);
+    expect(body.messages).toHaveLength(1);
+    expect(body.messages[0].role).toBe("user");
+  });
+
+  it("无 system 消息时不包含 system 字段", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+    expect(body.system).toBeUndefined();
+  });
+
+  it("apiBaseUrl 为空时使用默认 URL", () => {
+    const noBaseConfig = { ...config, apiBaseUrl: "" };
+    const { url } = buildAnthropicRequest(noBaseConfig, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(url).toBe("https://api.anthropic.com/v1/messages");
+  });
+
+  it("assistant 消息带 toolCalls 时应转换为 content blocks 格式", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [
+        { role: "user", content: "天气" },
+        {
+          role: "assistant",
+          content: "让我查一下",
+          toolCalls: [{ id: "toolu_1", name: "get_weather", arguments: '{"city":"北京"}' }],
+        },
+        { role: "tool", content: '{"temp":25}', toolCallId: "toolu_1" },
+      ],
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    // messages[0] 是 user, messages[1] 是 assistant
+    const assistantMsg = body.messages[1];
+    expect(assistantMsg.role).toBe("assistant");
+    expect(assistantMsg.content).toHaveLength(2);
+    expect(assistantMsg.content[0]).toEqual({ type: "text", text: "让我查一下" });
+    expect(assistantMsg.content[1].type).toBe("tool_use");
+    expect(assistantMsg.content[1].name).toBe("get_weather");
+    expect(assistantMsg.content[1].input).toEqual({ city: "北京" });
+  });
+
+  it("assistant 消息仅有 toolCalls 无 content 时不应包含 text block", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [
+        { role: "user", content: "天气" },
+        {
+          role: "assistant",
+          content: "",
+          toolCalls: [{ id: "toolu_1", name: "get_weather", arguments: '{"city":"北京"}' }],
+        },
+      ],
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    // messages[0] 是 user "天气", messages[1] 是 assistant
+    const assistantMsg = body.messages[1];
+    expect(assistantMsg.content).toHaveLength(1);
+    expect(assistantMsg.content[0].type).toBe("tool_use");
+  });
+
+  it("应设置正确的 Anthropic 头", () => {
+    const { init } = buildAnthropicRequest(config, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const headers = init.headers as Record<string, string>;
+    expect(headers["x-api-key"]).toBe("sk-ant-test");
+    expect(headers["anthropic-version"]).toBe("2023-06-01");
+    expect(headers["anthropic-dangerous-direct-browser-access"]).toBe("true");
+    expect(headers["Content-Type"]).toBe("application/json");
+  });
+
+  it("工具定义应使用 input_schema 而非 parameters", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+      tools: [
+        {
+          name: "test_tool",
+          description: "测试",
+          parameters: { type: "object", properties: { x: { type: "number" } } },
+        },
+      ],
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    expect(body.tools[0].input_schema).toBeDefined();
+    expect(body.tools[0].parameters).toBeUndefined();
+    expect(body.tools[0].type).toBeUndefined();
+    // 最后一个工具应带 cache_control
+    expect(body.tools[0].cache_control).toEqual({ type: "ephemeral" });
+  });
+
+  it("cache: false 时不应添加 cache_control", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [
+        { role: "system", content: "你是助手" },
+        { role: "user", content: "hi" },
+      ],
+      tools: [
+        {
+          name: "test_tool",
+          description: "测试",
+          parameters: { type: "object", properties: { x: { type: "number" } } },
+        },
+      ],
+      cache: false,
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    // system block 不应有 cache_control
+    expect(body.system[0].cache_control).toBeUndefined();
+    // tool 不应有 cache_control
+    expect(body.tools[0].cache_control).toBeUndefined();
+  });
+
+  it("默认不设置 max_tokens，应设置 stream", () => {
+    const { init } = buildAnthropicRequest(config, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const body = JSON.parse(init.body as string);
+    expect(body.max_tokens).toBeUndefined();
+    expect(body.stream).toBe(true);
+  });
+
+  it("配置 maxTokens 时应设置 max_tokens", () => {
+    const configWithMax = { ...config, maxTokens: 4096 };
+    const { init } = buildAnthropicRequest(configWithMax, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const body = JSON.parse(init.body as string);
+    expect(body.max_tokens).toBe(4096);
+  });
+
+  it("tool 消息无 toolCallId 时应按普通消息处理", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [
+        { role: "user", content: "hi" },
+        { role: "tool", content: "result" }, // 无 toolCallId
+      ],
+    };
+
+    const { init } = buildAnthropicRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    // 无 toolCallId 时不转换为 tool_result
+    const toolMsg = body.messages[1];
+    expect(toolMsg.role).toBe("tool");
+    expect(toolMsg.content).toBe("result");
+  });
+});
+
+// 辅助函数：创建 mock ReadableStreamDefaultReader
+function createMockReader(chunks: string[]): ReadableStreamDefaultReader<Uint8Array> {
+  const encoder = new TextEncoder();
+  let index = 0;
+  return {
+    read: async () => {
+      if (index < chunks.length) {
+        return { done: false, value: encoder.encode(chunks[index++]) };
+      }
+      return { done: true, value: undefined } as any;
+    },
+    cancel: async () => {},
+    closed: Promise.resolve(undefined),
+    releaseLock: () => {},
+  };
+}
+
+describe("parseAnthropicStream", () => {
+  it("应正确解析 content_block_delta (text_delta)", async () => {
+    const reader = createMockReader([
+      'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"Hello"}}\n\n',
+      'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":" World"}}\n\n',
+      "event: message_stop\ndata: {}\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(3);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "Hello" });
+    expect(events[1]).toEqual({ type: "content_delta", delta: " World" });
+    expect(events[2]).toEqual({ type: "done" });
+  });
+
+  it("应正确解析 tool_use 事件", async () => {
+    const reader = createMockReader([
+      'event: content_block_start\ndata: {"content_block":{"type":"tool_use","id":"toolu_1","name":"get_weather"}}\n\n',
+      'event: content_block_delta\ndata: {"delta":{"type":"input_json_delta","partial_json":"{\\"city\\""}}\n\n',
+      'event: content_block_delta\ndata: {"delta":{"type":"input_json_delta","partial_json":":\\"北京\\"}"}}\n\n',
+      "event: message_stop\ndata: {}\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events[0].type).toBe("tool_call_start");
+    if (events[0].type === "tool_call_start") {
+      expect(events[0].toolCall.id).toBe("toolu_1");
+      expect(events[0].toolCall.name).toBe("get_weather");
+      expect(events[0].toolCall.arguments).toBe("");
+    }
+    expect(events[1].type).toBe("tool_call_delta");
+    expect(events[2].type).toBe("tool_call_delta");
+  });
+
+  it("应正确解析 thinking_delta 事件", async () => {
+    const reader = createMockReader([
+      'event: content_block_start\ndata: {"content_block":{"type":"thinking"}}\n\n',
+      'event: content_block_delta\ndata: {"delta":{"type":"thinking_delta","thinking":"让我想想..."}}\n\n',
+      "event: message_stop\ndata: {}\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events[0]).toEqual({ type: "thinking_delta", delta: "让我想想..." });
+    expect(events[1]).toEqual({ type: "done" });
+  });
+
+  it("应正确处理 message_delta 中的 usage", async () => {
+    const reader = createMockReader([
+      'event: message_delta\ndata: {"usage":{"input_tokens":100,"output_tokens":50}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("done");
+    if (events[0].type === "done") {
+      expect(events[0].usage).toEqual({
+        inputTokens: 100,
+        outputTokens: 50,
+        cacheCreationInputTokens: undefined,
+        cacheReadInputTokens: undefined,
+      });
+    }
+  });
+
+  it("应合并 message_start 和 message_delta 的 usage（含 cache 信息）", async () => {
+    const reader = createMockReader([
+      'event: message_start\ndata: {"message":{"usage":{"input_tokens":200,"cache_creation_input_tokens":50,"cache_read_input_tokens":100}}}\n\n',
+      'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"hi"}}\n\n',
+      'event: message_delta\ndata: {"usage":{"output_tokens":30}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(2);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "hi" });
+    expect(events[1].type).toBe("done");
+    if (events[1].type === "done") {
+      expect(events[1].usage).toEqual({
+        inputTokens: 200,
+        outputTokens: 30,
+        cacheCreationInputTokens: 50,
+        cacheReadInputTokens: 100,
+      });
+    }
+  });
+
+  it("应正确处理 error 事件", async () => {
+    const reader = createMockReader(['event: error\ndata: {"error":{"message":"Overloaded"}}\n\n']);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("error");
+    if (events[0].type === "error") {
+      expect(events[0].message).toBe("Overloaded");
+    }
+  });
+
+  it("error 事件无 message 时使用默认错误信息", async () => {
+    const reader = createMockReader(['event: error\ndata: {"error":{}}\n\n']);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events[0].type).toBe("error");
+    if (events[0].type === "error") {
+      expect(events[0].message).toBe("Anthropic API error");
+    }
+  });
+
+  it("signal 已中止时应停止读取", async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const reader = createMockReader([
+      'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"hi"}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("读取错误时应发送 error 事件", async () => {
+    const reader = {
+      read: async () => {
+        throw new Error("Connection reset");
+      },
+      cancel: async () => {},
+      closed: Promise.resolve(undefined),
+      releaseLock: () => {},
+    } as any;
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("error");
+    if (events[0].type === "error") {
+      expect(events[0].message).toBe("Connection reset");
+    }
+  });
+
+  it("读取错误但 signal 已中止时不应发送 error", async () => {
+    const controller = new AbortController();
+    const reader = {
+      read: async () => {
+        controller.abort();
+        throw new Error("Aborted");
+      },
+      cancel: async () => {},
+      closed: Promise.resolve(undefined),
+      releaseLock: () => {},
+    } as any;
+
+    const events: ChatStreamEvent[] = [];
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("应忽略无法解析的 JSON 数据", async () => {
+    const reader = createMockReader([
+      "event: content_block_delta\ndata: {bad json\n\n",
+      'event: content_block_delta\ndata: {"delta":{"type":"text_delta","text":"ok"}}\n\n',
+      "event: message_stop\ndata: {}\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseAnthropicStream(reader, (e) => events.push(e), controller.signal);
+
+    // 第一个 JSON 解析失败应忽略
+    expect(events).toHaveLength(2);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "ok" });
+  });
+});
diff --git a/src/app/service/agent/providers/anthropic.ts b/src/app/service/agent/providers/anthropic.ts
new file mode 100644
index 000000000..eabbe42fe
--- /dev/null
+++ b/src/app/service/agent/providers/anthropic.ts
@@ -0,0 +1,287 @@
+import type { ChatStreamEvent, ChatRequest, ContentBlock } from "../types";
+import type { AgentModelConfig } from "../types";
+import { SSEParser } from "../sse_parser";
+import { isContentBlocks } from "../content_utils";
+
+// 将 ContentBlock[] 转换为 Anthropic content 格式
+function convertContentBlocks(
+  blocks: ContentBlock[],
+  attachmentResolver?: (id: string) => string | null
+): Array<Record<string, unknown>> {
+  const result: Array<Record<string, unknown>> = [];
+  for (const block of blocks) {
+    switch (block.type) {
+      case "text":
+        result.push({ type: "text", text: block.text });
+        break;
+      case "image": {
+        const data = attachmentResolver?.(block.attachmentId);
+        if (data) {
+          // data URL → base64 内容
+          const match = data.match(/^data:([^;]+);base64,(.+)$/s);
+          if (match) {
+            result.push({
+              type: "image",
+              source: { type: "base64", media_type: match[1], data: match[2] },
+            });
+          } else {
+            result.push({ type: "text", text: `[Image: ${block.name || "image"}]` });
+          }
+        } else {
+          result.push({ type: "text", text: `[Image: ${block.name || "image"}]` });
+        }
+        break;
+      }
+      case "file": {
+        const data = attachmentResolver?.(block.attachmentId);
+        if (data) {
+          const match = data.match(/^data:([^;]+);base64,(.+)$/s);
+          if (match) {
+            result.push({
+              type: "document",
+              source: { type: "base64", media_type: match[1], data: match[2] },
+            });
+          } else {
+            result.push({ type: "text", text: `[File: ${block.name}]` });
+          }
+        } else {
+          result.push({ type: "text", text: `[File: ${block.name}]` });
+        }
+        break;
+      }
+      case "audio":
+        // Anthropic 暂不支持音频，降级为文本描述
+        result.push({
+          type: "text",
+          text: `[Audio: ${block.name || "audio"}${block.durationMs ? ` (${(block.durationMs / 1000).toFixed(1)}s)` : ""}]`,
+        });
+        break;
+    }
+  }
+  return result;
+}
+
+// 构造 Anthropic 格式的请求
+export function buildAnthropicRequest(
+  config: AgentModelConfig,
+  request: ChatRequest,
+  attachmentResolver?: (id: string) => string | null
+): { url: string; init: RequestInit } {
+  const baseUrl = config.apiBaseUrl || "https://api.anthropic.com";
+  const url = `${baseUrl}/v1/messages`;
+  const useCache = request.cache !== false;
+
+  // 分离 system 消息和其他消息
+  const systemMessages = request.messages.filter((m) => m.role === "system");
+  const otherMessages = request.messages.filter((m) => m.role !== "system");
+
+  // Anthropic 格式：tool 角色消息需要转换为 tool_result content block
+  // assistant 消息带 toolCalls 时需要转换为 tool_use content blocks
+  const messages = otherMessages.map((m) => {
+    if (m.role === "tool" && m.toolCallId) {
+      return {
+        role: "user" as const,
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: m.toolCallId,
+            content: m.content,
+          },
+        ],
+      };
+    }
+    // assistant 消息带 tool_calls 时，转换为 content blocks 格式
+    if (m.role === "assistant" && m.toolCalls && m.toolCalls.length > 0) {
+      const content: Array<Record<string, unknown>> = [];
+      if (m.content) {
+        if (isContentBlocks(m.content)) {
+          content.push(...convertContentBlocks(m.content, attachmentResolver));
+        } else {
+          content.push({ type: "text", text: m.content });
+        }
+      }
+      for (const tc of m.toolCalls) {
+        content.push({
+          type: "tool_use",
+          id: tc.id,
+          name: tc.name,
+          input: tc.arguments ? JSON.parse(tc.arguments) : {},
+        });
+      }
+      return { role: "assistant" as const, content };
+    }
+    // 处理 ContentBlock[] 格式的消息内容
+    if (isContentBlocks(m.content)) {
+      return { role: m.role, content: convertContentBlocks(m.content, attachmentResolver) };
+    }
+    return { role: m.role, content: m.content };
+  });
+
+  const body: Record<string, unknown> = {
+    model: config.model,
+    messages,
+    stream: true,
+  };
+
+  if (config.maxTokens) {
+    body.max_tokens = config.maxTokens;
+  }
+
+  if (systemMessages.length > 0) {
+    const systemBlocks = systemMessages.map((m) => ({
+      type: "text" as const,
+      text:
+        typeof m.content === "string"
+          ? m.content
+          : m.content
+              .filter((b) => b.type === "text")
+              .map((b) => (b as { type: "text"; text: string }).text)
+              .join(""),
+    }));
+    // 最后一个 system block 加 cache_control（仅在启用缓存时）
+    if (useCache && systemBlocks.length > 0) {
+      (systemBlocks[systemBlocks.length - 1] as Record<string, unknown>).cache_control = { type: "ephemeral" };
+    }
+    body.system = systemBlocks;
+  }
+
+  // 添加工具定义
+  if (request.tools && request.tools.length > 0) {
+    const tools = request.tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters,
+    }));
+    // 最后一个 tool 加 cache_control（仅在启用缓存时）
+    if (useCache && tools.length > 0) {
+      (tools[tools.length - 1] as Record<string, unknown>).cache_control = { type: "ephemeral" };
+    }
+    body.tools = tools;
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "x-api-key": config.apiKey,
+    "anthropic-version": "2023-06-01",
+    "anthropic-dangerous-direct-browser-access": "true",
+  };
+
+  return {
+    url,
+    init: {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+// 解析 Anthropic SSE 流，生成 ChatStreamEvent
+export function parseAnthropicStream(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  onEvent: (event: ChatStreamEvent) => void,
+  signal: AbortSignal
+): Promise<void> {
+  const parser = new SSEParser();
+  const decoder = new TextDecoder();
+
+  // 跟踪 message_start 中的 usage（含 cache 信息），在 message_delta 中合并输出
+  let cachedUsage: { inputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number } | null =
+    null;
+
+  return (async () => {
+    try {
+      while (!signal.aborted) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        const events = parser.parse(chunk);
+
+        for (const sseEvent of events) {
+          try {
+            const json = JSON.parse(sseEvent.data);
+
+            switch (sseEvent.event) {
+              case "message_start": {
+                // message_start 包含初始 usage（input_tokens, cache 信息）
+                const usage = json.message?.usage;
+                if (usage) {
+                  cachedUsage = {
+                    inputTokens: usage.input_tokens || 0,
+                    cacheCreationInputTokens: usage.cache_creation_input_tokens,
+                    cacheReadInputTokens: usage.cache_read_input_tokens,
+                  };
+                }
+                break;
+              }
+              case "content_block_start": {
+                const block = json.content_block;
+                if (block?.type === "thinking") {
+                  // thinking block 开始，后续通过 content_block_delta 传输内容
+                } else if (block?.type === "tool_use") {
+                  onEvent({
+                    type: "tool_call_start",
+                    toolCall: {
+                      id: block.id,
+                      name: block.name,
+                      arguments: "",
+                    },
+                  });
+                }
+                break;
+              }
+              case "content_block_delta": {
+                const delta = json.delta;
+                if (delta?.type === "text_delta") {
+                  onEvent({ type: "content_delta", delta: delta.text });
+                } else if (delta?.type === "thinking_delta") {
+                  onEvent({ type: "thinking_delta", delta: delta.thinking });
+                } else if (delta?.type === "input_json_delta") {
+                  onEvent({
+                    type: "tool_call_delta",
+                    id: "",
+                    delta: delta.partial_json,
+                  });
+                }
+                break;
+              }
+              case "message_delta": {
+                // 消息结束，合并 message_start 的 input usage 和 message_delta 的 output usage
+                if (json.usage) {
+                  onEvent({
+                    type: "done",
+                    usage: {
+                      inputTokens: cachedUsage?.inputTokens || json.usage.input_tokens || 0,
+                      outputTokens: json.usage.output_tokens || 0,
+                      cacheCreationInputTokens: cachedUsage?.cacheCreationInputTokens,
+                      cacheReadInputTokens: cachedUsage?.cacheReadInputTokens,
+                    },
+                  });
+                  return;
+                }
+                break;
+              }
+              case "message_stop": {
+                onEvent({ type: "done" });
+                return;
+              }
+              case "error": {
+                onEvent({
+                  type: "error",
+                  message: json.error?.message || "Anthropic API error",
+                });
+                return;
+              }
+            }
+          } catch {
+            // 解析失败忽略
+          }
+        }
+      }
+    } catch (e: any) {
+      if (signal.aborted) return;
+      onEvent({ type: "error", message: e.message || "Stream read error" });
+    }
+  })();
+}
diff --git a/src/app/service/agent/providers/openai.test.ts b/src/app/service/agent/providers/openai.test.ts
new file mode 100644
index 000000000..9c853c772
--- /dev/null
+++ b/src/app/service/agent/providers/openai.test.ts
@@ -0,0 +1,451 @@
+import { describe, it, expect } from "vitest";
+import { buildOpenAIRequest, parseOpenAIStream } from "./openai";
+import type { AgentModelConfig } from "../types";
+import type { ChatRequest, ChatStreamEvent } from "../types";
+
+const config: AgentModelConfig = {
+  id: "test",
+  name: "Test",
+  provider: "openai",
+  apiBaseUrl: "https://api.openai.com/v1",
+  apiKey: "sk-test",
+  model: "gpt-4o",
+};
+
+describe("buildOpenAIRequest", () => {
+  it("无 apiKey 时不包含 Authorization 头", () => {
+    const noKeyConfig = { ...config, apiKey: "" };
+    const { init } = buildOpenAIRequest(noKeyConfig, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const headers = init.headers as Record<string, string>;
+    expect(headers["Authorization"]).toBeUndefined();
+  });
+
+  it("自定义 apiBaseUrl 时使用自定义 URL", () => {
+    const customConfig = { ...config, apiBaseUrl: "https://my-proxy.com/api" };
+    const { url } = buildOpenAIRequest(customConfig, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(url).toBe("https://my-proxy.com/api/chat/completions");
+  });
+
+  it("apiBaseUrl 为空时使用默认 URL", () => {
+    const noBaseConfig = { ...config, apiBaseUrl: "" };
+    const { url } = buildOpenAIRequest(noBaseConfig, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(url).toBe("https://api.openai.com/v1/chat/completions");
+  });
+
+  it("assistant 消息带 toolCalls 时应转换为 OpenAI 格式", () => {
+    const request: ChatRequest = {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [
+        { role: "user", content: "天气" },
+        {
+          role: "assistant",
+          content: "",
+          toolCalls: [{ id: "call_1", name: "get_weather", arguments: '{"city":"北京"}' }],
+        },
+        { role: "tool", content: '{"temp":25}', toolCallId: "call_1" },
+      ],
+    };
+
+    const { init } = buildOpenAIRequest(config, request);
+    const body = JSON.parse(init.body as string);
+
+    // assistant 消息应包含 tool_calls
+    const assistantMsg = body.messages[1];
+    expect(assistantMsg.tool_calls).toHaveLength(1);
+    expect(assistantMsg.tool_calls[0].type).toBe("function");
+    expect(assistantMsg.tool_calls[0].function.name).toBe("get_weather");
+    expect(assistantMsg.tool_calls[0].function.arguments).toBe('{"city":"北京"}');
+
+    // tool 消息应包含 tool_call_id
+    const toolMsg = body.messages[2];
+    expect(toolMsg.role).toBe("tool");
+    expect(toolMsg.tool_call_id).toBe("call_1");
+  });
+
+  it("无 tools 时不包含 tools 字段", () => {
+    const { init } = buildOpenAIRequest(config, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const body = JSON.parse(init.body as string);
+    expect(body.tools).toBeUndefined();
+  });
+
+  it("应设置 stream 和 stream_options", () => {
+    const { init } = buildOpenAIRequest(config, {
+      conversationId: "c1",
+      modelId: "test",
+      messages: [{ role: "user", content: "hi" }],
+    });
+    const body = JSON.parse(init.body as string);
+    expect(body.stream).toBe(true);
+    expect(body.stream_options).toEqual({ include_usage: true });
+  });
+});
+
+// 辅助函数：创建 mock ReadableStreamDefaultReader
+function createMockReader(chunks: string[]): ReadableStreamDefaultReader<Uint8Array> {
+  const encoder = new TextEncoder();
+  let index = 0;
+  return {
+    read: async () => {
+      if (index < chunks.length) {
+        return { done: false, value: encoder.encode(chunks[index++]) };
+      }
+      return { done: true, value: undefined } as any;
+    },
+    cancel: async () => {},
+    closed: Promise.resolve(undefined),
+    releaseLock: () => {},
+  };
+}
+
+describe("parseOpenAIStream", () => {
+  it("应正确解析 content_delta 事件", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"content":"Hello"}}]}\n\n',
+      'data: {"choices":[{"delta":{"content":" World"}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(3);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "Hello" });
+    expect(events[1]).toEqual({ type: "content_delta", delta: " World" });
+    expect(events[2]).toEqual({ type: "done" });
+  });
+
+  it("应正确解析 tool_call_start 和 tool_call_delta", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"tool_calls":[{"id":"call_1","function":{"name":"get_weather","arguments":""}}]}}]}\n\n',
+      'data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\\"city\\""}}]}}]}\n\n',
+      'data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":":\\"北京\\"}"}}]}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events[0].type).toBe("tool_call_start");
+    if (events[0].type === "tool_call_start") {
+      expect(events[0].toolCall.name).toBe("get_weather");
+      expect(events[0].toolCall.id).toBe("call_1");
+    }
+    expect(events[1].type).toBe("tool_call_delta");
+    expect(events[2].type).toBe("tool_call_delta");
+  });
+
+  it("应正确处理 usage 信息", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"content":"hi"}}]}\n\n',
+      'data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].type).toBe("done");
+    if (events[1].type === "done") {
+      expect(events[1].usage).toEqual({ inputTokens: 10, outputTokens: 5 });
+    }
+  });
+
+  it("应正确处理含 cached_tokens 的 usage 信息", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"content":"hi"}}]}\n\n',
+      'data: {"usage":{"prompt_tokens":100,"completion_tokens":20,"prompt_tokens_details":{"cached_tokens":80}}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(2);
+    expect(events[1].type).toBe("done");
+    if (events[1].type === "done") {
+      expect(events[1].usage).toEqual({ inputTokens: 100, outputTokens: 20, cacheReadInputTokens: 80 });
+    }
+  });
+
+  it("应正确处理 API 错误响应", async () => {
+    const reader = createMockReader(['data: {"error":{"message":"Rate limit exceeded"}}\n\n']);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("error");
+    if (events[0].type === "error") {
+      expect(events[0].message).toBe("Rate limit exceeded");
+    }
+  });
+
+  it("应忽略无 choices 的事件", async () => {
+    const reader = createMockReader([
+      'data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk"}\n\n',
+      'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(2);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "ok" });
+  });
+
+  it("应忽略无法解析的 JSON", async () => {
+    const reader = createMockReader([
+      "data: {invalid json\n\n",
+      'data: {"choices":[{"delta":{"content":"ok"}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(2);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "ok" });
+  });
+
+  it("signal 已中止时应停止读取", async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const reader = createMockReader(['data: {"choices":[{"delta":{"content":"hello"}}]}\n\n']);
+
+    const events: ChatStreamEvent[] = [];
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("读取错误时应发送 error 事件", async () => {
+    const reader = {
+      read: async () => {
+        throw new Error("Network error");
+      },
+      cancel: async () => {},
+      closed: Promise.resolve(undefined),
+      releaseLock: () => {},
+    } as any;
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("error");
+    if (events[0].type === "error") {
+      expect(events[0].message).toBe("Network error");
+    }
+  });
+
+  it("读取错误但 signal 已中止时不应发送 error 事件", async () => {
+    const controller = new AbortController();
+    const reader = {
+      read: async () => {
+        controller.abort();
+        throw new Error("Aborted");
+      },
+      cancel: async () => {},
+      closed: Promise.resolve(undefined),
+      releaseLock: () => {},
+    } as any;
+
+    const events: ChatStreamEvent[] = [];
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(0);
+  });
+
+  it("应正确解析 reasoning_content 为 thinking_delta 事件", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":"让我思考"}}]}\n\n',
+      'data: {"choices":[{"delta":{"reasoning_content":"一下这个问题"}}]}\n\n',
+      'data: {"choices":[{"delta":{"content":"这是答案"}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(4);
+    expect(events[0]).toEqual({ type: "thinking_delta", delta: "让我思考" });
+    expect(events[1]).toEqual({ type: "thinking_delta", delta: "一下这个问题" });
+    expect(events[2]).toEqual({ type: "content_delta", delta: "这是答案" });
+    expect(events[3]).toEqual({ type: "done" });
+  });
+
+  it("reasoning_content 和 content 同时存在时应同时发出两个事件", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"reasoning_content":"思考中","content":"回答"}}]}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(3);
+    expect(events[0]).toEqual({ type: "thinking_delta", delta: "思考中" });
+    expect(events[1]).toEqual({ type: "content_delta", delta: "回答" });
+  });
+
+  it("最后一个 chunk 同时包含 usage 和 choices 时应先处理 choices 再处理 usage", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"tool_calls":[{"id":"call_1","function":{"name":"search","arguments":""}}]}}]}\n\n',
+      'data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\\"q\\":\\"test\\"}"}}]}}]}\n\n',
+      // 最后一个 chunk 同时包含 choices（finish_reason）和 usage
+      'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":100,"completion_tokens":20}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    // tool_call_start, tool_call_delta, done(with usage)
+    expect(events).toHaveLength(3);
+    expect(events[0].type).toBe("tool_call_start");
+    expect(events[1].type).toBe("tool_call_delta");
+    expect(events[2].type).toBe("done");
+    if (events[2].type === "done") {
+      expect(events[2].usage).toEqual({ inputTokens: 100, outputTokens: 20 });
+    }
+  });
+
+  it("最后一个 chunk 同时包含 usage 和 tool_call 增量时不应丢失 tool_call 数据", async () => {
+    // 模拟实际场景：最后一个 chunk 携带 tool_call arguments 增量 + usage
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"tool_calls":[{"id":"call_1","function":{"name":"dom_read_page","arguments":"{\\"tabId\\":123"}}]}}]}\n\n',
+      'data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":",\\"mode\\":\\"summary\\"}"}}]},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":40010,"completion_tokens":154}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(3);
+    expect(events[0].type).toBe("tool_call_start");
+    if (events[0].type === "tool_call_start") {
+      expect(events[0].toolCall.name).toBe("dom_read_page");
+      expect(events[0].toolCall.arguments).toBe('{"tabId":123');
+    }
+    // 关键：最后的 tool_call_delta 不应被 usage 检查吞掉
+    expect(events[1].type).toBe("tool_call_delta");
+    if (events[1].type === "tool_call_delta") {
+      expect(events[1].delta).toBe(',"mode":"summary"}');
+    }
+    expect(events[2].type).toBe("done");
+    if (events[2].type === "done") {
+      expect(events[2].usage).toEqual({ inputTokens: 40010, outputTokens: 154 });
+    }
+  });
+
+  it("每个 chunk 都带 usage 时不应提前终止流（Grok 兼容）", async () => {
+    // Grok API 在每个 chunk 都附带 usage，不应被当作结束信号
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"content":"很"},"finish_reason":null,"index":0}],"usage":{"prompt_tokens":100,"completion_tokens":1}}\n\n',
+      'data: {"choices":[{"delta":{"content":"抱"},"finish_reason":null,"index":0}],"usage":{"prompt_tokens":100,"completion_tokens":2}}\n\n',
+      'data: {"choices":[{"delta":{"content":"歉"},"finish_reason":null,"index":0}],"usage":{"prompt_tokens":100,"completion_tokens":3}}\n\n',
+      'data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}],"usage":{"prompt_tokens":100,"completion_tokens":3}}\n\n',
+      "data: [DONE]\n\n",
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    // 应收到 3 个 content_delta + 1 个 done（带最终 usage）
+    expect(events).toHaveLength(4);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "很" });
+    expect(events[1]).toEqual({ type: "content_delta", delta: "抱" });
+    expect(events[2]).toEqual({ type: "content_delta", delta: "歉" });
+    expect(events[3].type).toBe("done");
+    if (events[3].type === "done") {
+      expect(events[3].usage).toEqual({ inputTokens: 100, outputTokens: 3 });
+    }
+  });
+
+  it("每个 chunk 都带 usage 且无 [DONE] 时应在流结束时发出 done", async () => {
+    // 某些 API 在所有 chunk 带 usage 但不发 [DONE]
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"content":"你好"},"finish_reason":null}],"usage":{"prompt_tokens":50,"completion_tokens":1}}\n\n',
+      'data: {"choices":[{"delta":{"content":"世界"},"finish_reason":null}],"usage":{"prompt_tokens":50,"completion_tokens":2}}\n\n',
+      'data: {"choices":[{"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":50,"completion_tokens":2}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(3);
+    expect(events[0]).toEqual({ type: "content_delta", delta: "你好" });
+    expect(events[1]).toEqual({ type: "content_delta", delta: "世界" });
+    expect(events[2].type).toBe("done");
+    if (events[2].type === "done") {
+      expect(events[2].usage).toEqual({ inputTokens: 50, outputTokens: 2 });
+    }
+  });
+
+  it("reasoning_content 后跟 tool_calls 应都正确解析", async () => {
+    const reader = createMockReader([
+      'data: {"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":"分析页面"}}]}\n\n',
+      'data: {"choices":[{"delta":{"reasoning_content":"结构"}}]}\n\n',
+      'data: {"choices":[{"delta":{"tool_calls":[{"id":"call_1","function":{"name":"dom_read_page","arguments":"{\\"selector\\":\\".item\\"}"}}]}}]}\n\n',
+      'data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":500,"completion_tokens":50}}\n\n',
+    ]);
+
+    const events: ChatStreamEvent[] = [];
+    const controller = new AbortController();
+
+    await parseOpenAIStream(reader, (e) => events.push(e), controller.signal);
+
+    expect(events).toHaveLength(4);
+    expect(events[0]).toEqual({ type: "thinking_delta", delta: "分析页面" });
+    expect(events[1]).toEqual({ type: "thinking_delta", delta: "结构" });
+    expect(events[2].type).toBe("tool_call_start");
+    expect(events[3].type).toBe("done");
+    if (events[3].type === "done") {
+      expect(events[3].usage).toEqual({ inputTokens: 500, outputTokens: 50 });
+    }
+  });
+});
diff --git a/src/app/service/agent/providers/openai.ts b/src/app/service/agent/providers/openai.ts
new file mode 100644
index 000000000..61bb951a0
--- /dev/null
+++ b/src/app/service/agent/providers/openai.ts
@@ -0,0 +1,220 @@
+import type { ChatStreamEvent, ChatRequest, ContentBlock } from "../types";
+import type { AgentModelConfig } from "../types";
+import { SSEParser } from "../sse_parser";
+import { isContentBlocks } from "../content_utils";
+
+// 将 ContentBlock[] 转换为 OpenAI content 数组格式
+function convertContentBlocks(
+  blocks: ContentBlock[],
+  attachmentResolver?: (id: string) => string | null
+): Array<Record<string, unknown>> {
+  const result: Array<Record<string, unknown>> = [];
+  for (const block of blocks) {
+    switch (block.type) {
+      case "text":
+        result.push({ type: "text", text: block.text });
+        break;
+      case "image": {
+        const data = attachmentResolver?.(block.attachmentId);
+        if (data) {
+          result.push({ type: "image_url", image_url: { url: data } });
+        } else {
+          result.push({ type: "text", text: `[Image: ${block.name || "image"}]` });
+        }
+        break;
+      }
+      case "file":
+        // OpenAI 不支持文件上传到 chat，降级为文本引用
+        result.push({ type: "text", text: `[File: ${block.name}]` });
+        break;
+      case "audio": {
+        const data = attachmentResolver?.(block.attachmentId);
+        if (data) {
+          const match = data.match(/^data:([^;]+);base64,(.+)$/s);
+          if (match) {
+            // 从 mimeType 提取格式 (e.g. "audio/wav" → "wav")
+            const format = block.mimeType.split("/")[1] || "wav";
+            result.push({ type: "input_audio", input_audio: { data: match[2], format } });
+          } else {
+            result.push({ type: "text", text: `[Audio: ${block.name || "audio"}]` });
+          }
+        } else {
+          result.push({ type: "text", text: `[Audio: ${block.name || "audio"}]` });
+        }
+        break;
+      }
+    }
+  }
+  return result;
+}
+
+// 构造 OpenAI 兼容格式的请求
+export function buildOpenAIRequest(
+  config: AgentModelConfig,
+  request: ChatRequest,
+  attachmentResolver?: (id: string) => string | null
+): { url: string; init: RequestInit } {
+  const baseUrl = config.apiBaseUrl || "https://api.openai.com/v1";
+  const url = `${baseUrl}/chat/completions`;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+  }
+
+  const messages = request.messages.map((m) => {
+    const msg: Record<string, unknown> = { role: m.role };
+    // 处理 ContentBlock[] 格式的消息内容
+    if (isContentBlocks(m.content)) {
+      msg.content = convertContentBlocks(m.content, attachmentResolver);
+    } else {
+      msg.content = m.content;
+    }
+    if (m.toolCallId) {
+      msg.tool_call_id = m.toolCallId;
+    }
+    // assistant 消息带 tool_calls 时，转换为 OpenAI 格式
+    if (m.toolCalls && m.toolCalls.length > 0) {
+      msg.tool_calls = m.toolCalls.map((tc) => ({
+        id: tc.id,
+        type: "function",
+        function: { name: tc.name, arguments: tc.arguments },
+      }));
+    }
+    return msg;
+  });
+
+  const body: Record<string, unknown> = {
+    model: config.model,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+  };
+
+  // 添加工具定义
+  if (request.tools && request.tools.length > 0) {
+    body.tools = request.tools.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+  }
+
+  return {
+    url,
+    init: {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    },
+  };
+}
+
+// 解析 OpenAI SSE 流，生成 ChatStreamEvent
+export function parseOpenAIStream(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  onEvent: (event: ChatStreamEvent) => void,
+  signal: AbortSignal
+): Promise<void> {
+  const parser = new SSEParser();
+  const decoder = new TextDecoder();
+
+  return (async () => {
+    // 记录最新的 usage 数据（某些 API 如 Grok 在每个 chunk 都带 usage，而非仅最后一个）
+    let lastUsage:
+      | { inputTokens: number; outputTokens: number; cacheCreationInputTokens?: number; cacheReadInputTokens?: number }
+      | undefined;
+
+    try {
+      while (!signal.aborted) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        const events = parser.parse(chunk);
+
+        for (const sseEvent of events) {
+          if (sseEvent.data === "[DONE]") {
+            onEvent({ type: "done", usage: lastUsage });
+            return;
+          }
+
+          try {
+            const json = JSON.parse(sseEvent.data);
+
+            // 处理 API 错误响应
+            if (json.error) {
+              onEvent({
+                type: "error",
+                message: json.error.message || JSON.stringify(json.error),
+              });
+              return;
+            }
+
+            const choice = json.choices?.[0];
+            if (choice) {
+              const delta = choice.delta;
+              if (delta) {
+                // 思考过程增量（reasoning_content 兼容 deepseek / openai o-series）
+                if (delta.reasoning_content) {
+                  onEvent({ type: "thinking_delta", delta: delta.reasoning_content });
+                }
+
+                // 内容增量
+                if (delta.content) {
+                  onEvent({ type: "content_delta", delta: delta.content });
+                }
+
+                // 工具调用
+                if (delta.tool_calls) {
+                  for (const tc of delta.tool_calls) {
+                    if (tc.function?.name) {
+                      onEvent({
+                        type: "tool_call_start",
+                        toolCall: {
+                          id: tc.id || `tc_${Date.now()}`,
+                          name: tc.function.name,
+                          arguments: tc.function.arguments || "",
+                        },
+                      });
+                    } else if (tc.function?.arguments) {
+                      onEvent({
+                        type: "tool_call_delta",
+                        id: tc.id || "",
+                        delta: tc.function.arguments,
+                      });
+                    }
+                  }
+                }
+              }
+            }
+
+            // 记录 usage（不作为结束信号，兼容每个 chunk 都带 usage 的 API）
+            if (json.usage) {
+              const cachedTokens = json.usage.prompt_tokens_details?.cached_tokens;
+              lastUsage = {
+                inputTokens: json.usage.prompt_tokens || 0,
+                outputTokens: json.usage.completion_tokens || 0,
+                ...(cachedTokens ? { cacheReadInputTokens: cachedTokens } : {}),
+              };
+            }
+          } catch {
+            // 解析失败忽略
+          }
+        }
+      }
+      // 流正常结束但没收到 [DONE]（某些 API 可能如此）
+      if (!signal.aborted) {
+        onEvent({ type: "done", usage: lastUsage });
+      }
+    } catch (e: any) {
+      if (signal.aborted) return;
+      onEvent({ type: "error", message: e.message || "Stream read error" });
+    }
+  })();
+}
diff --git a/src/app/service/agent/sse_parser.test.ts b/src/app/service/agent/sse_parser.test.ts
new file mode 100644
index 000000000..6e8ddc845
--- /dev/null
+++ b/src/app/service/agent/sse_parser.test.ts
@@ -0,0 +1,130 @@
+import { describe, it, expect } from "vitest";
+import { SSEParser } from "./sse_parser";
+
+describe("SSEParser", () => {
+  it("应正确解析单个 SSE 事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse('data: {"text":"hello"}\n\n');
+    expect(events).toHaveLength(1);
+    expect(events[0].event).toBe("message");
+    expect(events[0].data).toBe('{"text":"hello"}');
+  });
+
+  it("应正确解析带 event 字段的事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse('event: content_block_delta\ndata: {"delta":"hi"}\n\n');
+    expect(events).toHaveLength(1);
+    expect(events[0].event).toBe("content_block_delta");
+    expect(events[0].data).toBe('{"delta":"hi"}');
+  });
+
+  it("应正确处理跨 chunk 的事件", () => {
+    const parser = new SSEParser();
+    const events1 = parser.parse('data: {"text":');
+    expect(events1).toHaveLength(0);
+    const events2 = parser.parse('"hello"}\n\n');
+    expect(events2).toHaveLength(1);
+    expect(events2[0].data).toBe('{"text":"hello"}');
+  });
+
+  it("应正确解析多个连续事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse('data: {"a":1}\n\ndata: {"b":2}\n\n');
+    expect(events).toHaveLength(2);
+    expect(events[0].data).toBe('{"a":1}');
+    expect(events[1].data).toBe('{"b":2}');
+  });
+
+  it("应忽略注释行", () => {
+    const parser = new SSEParser();
+    const events = parser.parse(": comment\ndata: test\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("test");
+  });
+
+  it("应正确处理 \\r\\n 换行符", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("data: hello\r\n\r\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("hello");
+  });
+
+  it("应正确处理多行 data 字段（拼接为换行符分隔）", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("data: line1\ndata: line2\ndata: line3\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("line1\nline2\nline3");
+  });
+
+  it("应忽略没有冒号的行", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("invalid-line\ndata: valid\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("valid");
+  });
+
+  it("空行但无 data 时不应产生事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("\n\n");
+    expect(events).toHaveLength(0);
+  });
+
+  it("data 冒号后无空格时应正确解析", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("data:no-space\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("no-space");
+  });
+
+  it("data 为空字符串时应正确解析", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("data: \n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("");
+  });
+
+  it("reset 后应清除所有状态", () => {
+    const parser = new SSEParser();
+    // 先输入一个不完整的事件
+    parser.parse("data: partial");
+    parser.reset();
+    // reset 后新的输入应从头开始
+    const events = parser.parse("data: fresh\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("fresh");
+  });
+
+  it("reset 后之前的 event 字段不应残留", () => {
+    const parser = new SSEParser();
+    parser.parse("event: old_type\n");
+    parser.reset();
+    const events = parser.parse("data: new\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].event).toBe("message"); // 不应是 old_type
+  });
+
+  it("应处理跨多个 chunk 的复杂场景", () => {
+    const parser = new SSEParser();
+    // chunk1: event 和部分 data
+    const e1 = parser.parse("event: test\ndata: part");
+    expect(e1).toHaveLength(0);
+    // chunk2: data 剩余部分和空行
+    const e2 = parser.parse("ial\n\n");
+    expect(e2).toHaveLength(1);
+    expect(e2[0].event).toBe("test");
+    expect(e2[0].data).toBe("partial");
+  });
+
+  it("连续空行不应产生重复事件", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("data: once\n\n\n\n");
+    expect(events).toHaveLength(1);
+  });
+
+  it("应忽略未知字段", () => {
+    const parser = new SSEParser();
+    const events = parser.parse("id: 123\nretry: 5000\ndata: hello\n\n");
+    expect(events).toHaveLength(1);
+    expect(events[0].data).toBe("hello");
+  });
+});
diff --git a/src/app/service/agent/sse_parser.ts b/src/app/service/agent/sse_parser.ts
new file mode 100644
index 000000000..62dfd30ad
--- /dev/null
+++ b/src/app/service/agent/sse_parser.ts
@@ -0,0 +1,71 @@
+// SSE (Server-Sent Events) 文本流解析器
+export type SSEEvent = {
+  event: string;
+  data: string;
+};
+
+export class SSEParser {
+  private buffer = "";
+  private currentEvent = "";
+  private currentData: string[] = [];
+
+  // 解析输入的文本块，返回完整的事件列表
+  parse(chunk: string): SSEEvent[] {
+    this.buffer += chunk;
+    const events: SSEEvent[] = [];
+    const lines = this.buffer.split("\n");
+    // 保留最后一个不完整的行
+    this.buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      if (line === "" || line === "\r") {
+        // 空行表示事件结束
+        if (this.currentData.length > 0) {
+          events.push({
+            event: this.currentEvent || "message",
+            data: this.currentData.join("\n"),
+          });
+          this.currentEvent = "";
+          this.currentData = [];
+        }
+        continue;
+      }
+
+      const cleanLine = line.endsWith("\r") ? line.slice(0, -1) : line;
+
+      if (cleanLine.startsWith(":")) {
+        // 注释行，忽略
+        continue;
+      }
+
+      const colonIndex = cleanLine.indexOf(":");
+      if (colonIndex === -1) {
+        // 没有冒号，整行作为字段名
+        continue;
+      }
+
+      const field = cleanLine.slice(0, colonIndex);
+      // 冒号后如果有空格则跳过
+      const value =
+        cleanLine[colonIndex + 1] === " " ? cleanLine.slice(colonIndex + 2) : cleanLine.slice(colonIndex + 1);
+
+      switch (field) {
+        case "event":
+          this.currentEvent = value;
+          break;
+        case "data":
+          this.currentData.push(value);
+          break;
+      }
+    }
+
+    return events;
+  }
+
+  // 重置解析器状态
+  reset(): void {
+    this.buffer = "";
+    this.currentEvent = "";
+    this.currentData = [];
+  }
+}
diff --git a/src/app/service/agent/system_prompt.test.ts b/src/app/service/agent/system_prompt.test.ts
new file mode 100644
index 000000000..73846d510
--- /dev/null
+++ b/src/app/service/agent/system_prompt.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+
+import { buildSystemPrompt } from "./system_prompt";
+
+describe("buildSystemPrompt", () => {
+  it("无 userSystem、无 skillSuffix 时只返回内置提示词", () => {
+    const result = buildSystemPrompt({});
+    expect(result).toContain("You are ScriptCat Agent");
+    expect(result).toContain("## Core Principles");
+    // 末尾不应有多余的空行
+    expect(result.endsWith("\n\n")).toBe(false);
+  });
+
+  it("有 userSystem 时拼接在内置提示词之后", () => {
+    const result = buildSystemPrompt({ userSystem: "You are a helpful bot." });
+    expect(result).toContain("You are ScriptCat Agent");
+    expect(result).toContain("You are a helpful bot.");
+    // userSystem 应在内置提示词之后
+    const builtinEnd = result.indexOf("debugger permission.");
+    const userStart = result.indexOf("You are a helpful bot.");
+    expect(userStart).toBeGreaterThan(builtinEnd);
+  });
+
+  it("有 skillSuffix 时拼接在末尾", () => {
+    const result = buildSystemPrompt({
+      skillSuffix: "\n# Available Skills\n- browser_automation",
+    });
+    expect(result).toContain("You are ScriptCat Agent");
+    expect(result).toContain("# Available Skills");
+  });
+
+  it("都有时按顺序拼接：内置 + userSystem + skillSuffix", () => {
+    const result = buildSystemPrompt({
+      userSystem: "Custom instructions here.",
+      skillSuffix: "\n# Skills\n- test_skill",
+    });
+
+    const builtinPos = result.indexOf("You are ScriptCat Agent");
+    const userPos = result.indexOf("Custom instructions here.");
+    const skillPos = result.indexOf("# Skills");
+
+    expect(builtinPos).toBeLessThan(userPos);
+    expect(userPos).toBeLessThan(skillPos);
+  });
+
+  it("userSystem 为空字符串时不额外追加", () => {
+    const result = buildSystemPrompt({ userSystem: "" });
+    // 不应出现连续三个换行（即空段落）
+    expect(result).not.toContain("\n\n\n");
+  });
+});
diff --git a/src/app/service/agent/system_prompt.ts b/src/app/service/agent/system_prompt.ts
new file mode 100644
index 000000000..948928682
--- /dev/null
+++ b/src/app/service/agent/system_prompt.ts
@@ -0,0 +1,85 @@
+// Agent 内置系统提示词
+
+const BUILTIN_SYSTEM_PROMPT = `You are ScriptCat Agent, an AI assistant built into the ScriptCat browser extension. You help users automate browser tasks, extract web data, and manage userscripts.
+
+## Core Principles
+
+- Before interacting with a page, verify its current state — never assume a page is as expected.
+- When a step fails, analyze the cause and change your approach. Never retry the exact same action.
+
+## Planning
+
+- **Simple tasks** (single step, clear intent): act directly.
+- **Complex tasks** (multi-step, involves navigation across pages, form submissions, or data processing): first propose a numbered step-by-step plan, then wait for user confirmation before executing. The user may adjust, approve, or reject the plan.
+- During execution, if the situation deviates from the plan (unexpected page state, missing element, new information), pause and inform the user with an updated plan rather than silently improvising.
+
+## Tool Usage
+
+Your tools come from Skills, CATTools, and MCP servers. Read each tool's description before calling — it defines behavior, parameters, and constraints. When a tool returns an error, read the error message and adapt — do not blindly retry.
+
+### Loop Detection
+Detect when you are stuck and stop early:
+- **Hard loop**: Same tool + same arguments failing 2+ times → change approach immediately.
+- **Ping-pong**: Alternating between two actions (A → B → A → B) without progress → stop and rethink.
+- **Persistent failure**: Same error 3+ times despite different approaches → escalate.
+
+### Escalation (in order of preference)
+1. **Switch strategy** — try a fundamentally different approach.
+2. **Ask the user** — summarize what you tried and why it failed, then ask for guidance.
+3. **Declare blocked** — if the task is impossible given current permissions or page state, say so clearly.
+
+## Safety
+
+- **Confirm before irreversible actions**: submitting forms, making purchases, deleting data, posting content.
+- **Proceed freely on read-only actions**: navigating, reading content, taking screenshots, extracting data.
+- **Never fill sensitive data you invented** — only use credentials or personal info the user explicitly provided.
+- **Never bypass site security** — do not attempt to circumvent CAPTCHAs, rate limits, or access controls. If blocked, inform the user.
+- If the user's intent is unclear, ask before acting.
+
+## Communication
+
+- Respond in the user's language.
+- State what you will do before each action. Keep it to one short sentence.
+- When a task is blocked, explain the specific reason and what the user can do about it.
+- Keep responses concise — do not over-explain routine operations.
+- When reporting extracted data or results, format them clearly (use lists or structured text).`;
+
+// Skill 摘要提示词模板
+export const SKILL_SUFFIX_HEADER = `---
+
+# Available Skills
+
+Skills extend your capabilities with specialized tools and workflows. **You must call \`load_skill\` before using any skill** — this loads the skill's detailed instructions and registers its tools.
+
+Rules:
+- Only load skills that are relevant to the current task.
+- After loading, follow the skill's instructions carefully — they override general guidelines for that domain.
+- Skill tools are registered with a prefix: \`skillname__toolname\`. Call them directly after loading.
+- If a skill has reference documents, use \`read_reference\` to access them when needed.
+
+Installed skills:
+`;
+
+export interface BuildSystemPromptOptions {
+  /** 用户自定义 system prompt */
+  userSystem?: string;
+  /** skill 解析后追加的提示词后缀 */
+  skillSuffix?: string;
+}
+
+/**
+ * 组装完整的 system prompt：内置提示词 + 用户自定义 + skill 后缀
+ */
+export function buildSystemPrompt(options: BuildSystemPromptOptions): string {
+  const parts: string[] = [BUILTIN_SYSTEM_PROMPT];
+
+  if (options.userSystem) {
+    parts.push(options.userSystem);
+  }
+
+  if (options.skillSuffix) {
+    parts.push(options.skillSuffix);
+  }
+
+  return parts.join("\n\n");
+}
diff --git a/src/app/service/agent/task_scheduler.test.ts b/src/app/service/agent/task_scheduler.test.ts
new file mode 100644
index 000000000..04093feb6
--- /dev/null
+++ b/src/app/service/agent/task_scheduler.test.ts
@@ -0,0 +1,161 @@
+import { describe, expect, it, beforeEach, vi } from "vitest";
+import { AgentTaskScheduler } from "./task_scheduler";
+import { AgentTaskRepo, AgentTaskRunRepo } from "@App/app/repo/agent_task";
+import type { AgentTask } from "@App/app/service/agent/types";
+
+function makeTask(overrides: Partial<AgentTask> = {}): AgentTask {
+  return {
+    id: "task-1",
+    name: "测试任务",
+    crontab: "0 9 * * *",
+    mode: "internal",
+    enabled: true,
+    notify: false,
+    createtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("AgentTaskScheduler", () => {
+  let repo: AgentTaskRepo;
+  let runRepo: AgentTaskRunRepo;
+  let internalExecutor: ReturnType<
+    typeof vi.fn<
+      (task: AgentTask) => Promise<{ conversationId: string; usage?: { inputTokens: number; outputTokens: number } }>
+    >
+  >;
+  let eventEmitter: ReturnType<typeof vi.fn<(task: AgentTask) => Promise<void>>>;
+  let scheduler: AgentTaskScheduler;
+
+  beforeEach(() => {
+    repo = new AgentTaskRepo();
+    runRepo = new AgentTaskRunRepo();
+    internalExecutor = vi
+      .fn()
+      .mockResolvedValue({ conversationId: "conv-1", usage: { inputTokens: 100, outputTokens: 50 } });
+    eventEmitter = vi.fn().mockResolvedValue(undefined);
+    scheduler = new AgentTaskScheduler(repo, runRepo, internalExecutor, eventEmitter);
+  });
+
+  it("init 加载并计算 nextruntime", async () => {
+    const task = makeTask({ id: "init-1", nextruntime: undefined });
+    await repo.saveTask(task);
+
+    await scheduler.init();
+
+    const updated = await repo.getTask("init-1");
+    expect(updated).toBeDefined();
+    expect(updated!.nextruntime).toBeGreaterThan(Date.now() - 1000);
+  });
+
+  it("tick 执行到期任务", async () => {
+    const task = makeTask({ id: "tick-1", nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.tick();
+
+    // 等待异步执行完成
+    await vi.waitFor(async () => {
+      expect(internalExecutor).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("tick 跳过未到期任务", async () => {
+    const task = makeTask({ id: "skip-1", nextruntime: Date.now() + 60_000 });
+    await repo.saveTask(task);
+
+    await scheduler.tick();
+
+    expect(internalExecutor).not.toHaveBeenCalled();
+  });
+
+  it("tick 跳过 disabled 任务", async () => {
+    const task = makeTask({ id: "disabled-1", enabled: false, nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.tick();
+
+    expect(internalExecutor).not.toHaveBeenCalled();
+  });
+
+  it("tick 跳过正在运行的任务", async () => {
+    // 让 executor 永远 pending
+    internalExecutor.mockReturnValue(new Promise(() => {}));
+
+    const task = makeTask({ id: "running-1", nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.tick();
+
+    // 等待第一次执行开始
+    await vi.waitFor(() => {
+      expect(scheduler.isRunning("running-1")).toBe(true);
+    });
+
+    // 再次 tick 不应重复执行
+    await scheduler.tick();
+    expect(internalExecutor).toHaveBeenCalledTimes(1);
+  });
+
+  it("internal 模式调 internalExecutor", async () => {
+    const task = makeTask({ id: "internal-1", mode: "internal", nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.executeTask(task);
+
+    expect(internalExecutor).toHaveBeenCalledTimes(1);
+    expect(internalExecutor).toHaveBeenCalledWith(expect.objectContaining({ id: "internal-1" }));
+    expect(eventEmitter).not.toHaveBeenCalled();
+
+    // 检查 run 记录
+    const runs = await runRepo.listRuns("internal-1");
+    expect(runs).toHaveLength(1);
+    expect(runs[0].status).toBe("success");
+    expect(runs[0].conversationId).toBe("conv-1");
+    expect(runs[0].usage).toEqual({ inputTokens: 100, outputTokens: 50 });
+  });
+
+  it("event 模式调 eventEmitter", async () => {
+    const task = makeTask({ id: "event-1", mode: "event", nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.executeTask(task);
+
+    expect(eventEmitter).toHaveBeenCalledTimes(1);
+    expect(internalExecutor).not.toHaveBeenCalled();
+
+    const runs = await runRepo.listRuns("event-1");
+    expect(runs).toHaveLength(1);
+    expect(runs[0].status).toBe("success");
+  });
+
+  it("执行失败更新 error 状态", async () => {
+    internalExecutor.mockRejectedValue(new Error("LLM 调用失败"));
+
+    const task = makeTask({ id: "error-1", nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.executeTask(task);
+
+    const runs = await runRepo.listRuns("error-1");
+    expect(runs).toHaveLength(1);
+    expect(runs[0].status).toBe("error");
+    expect(runs[0].error).toBe("LLM 调用失败");
+
+    const updatedTask = await repo.getTask("error-1");
+    expect(updatedTask!.lastRunStatus).toBe("error");
+    expect(updatedTask!.lastRunError).toBe("LLM 调用失败");
+  });
+
+  it("执行完成后更新 nextruntime", async () => {
+    const task = makeTask({ id: "next-1", nextruntime: Date.now() - 1000 });
+    await repo.saveTask(task);
+
+    await scheduler.executeTask(task);
+
+    const updated = await repo.getTask("next-1");
+    expect(updated!.nextruntime).toBeGreaterThan(Date.now() - 1000);
+    expect(updated!.lastruntime).toBeDefined();
+  });
+});
diff --git a/src/app/service/agent/task_scheduler.ts b/src/app/service/agent/task_scheduler.ts
new file mode 100644
index 000000000..478adf642
--- /dev/null
+++ b/src/app/service/agent/task_scheduler.ts
@@ -0,0 +1,117 @@
+import type { AgentTask, AgentTaskRun } from "@App/app/service/agent/types";
+import type { AgentTaskRepo, AgentTaskRunRepo } from "@App/app/repo/agent_task";
+import { nextTimeInfo } from "@App/pkg/utils/cron";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+export type InternalExecutor = (task: AgentTask) => Promise<{
+  conversationId: string;
+  usage?: { inputTokens: number; outputTokens: number };
+}>;
+
+export type EventEmitter = (task: AgentTask) => Promise<void>;
+
+export class AgentTaskScheduler {
+  private runningTasks = new Set<string>();
+
+  constructor(
+    private repo: AgentTaskRepo,
+    private runRepo: AgentTaskRunRepo,
+    private internalExecutor: InternalExecutor,
+    private eventEmitter: EventEmitter
+  ) {}
+
+  async init(): Promise<void> {
+    // 加载所有 enabled 任务，计算 nextruntime
+    const tasks = await this.repo.listTasks();
+    for (const task of tasks) {
+      if (task.enabled && !task.nextruntime) {
+        try {
+          const info = nextTimeInfo(task.crontab);
+          task.nextruntime = info.next.toMillis();
+          task.updatetime = Date.now();
+          await this.repo.saveTask(task);
+        } catch {
+          // cron 表达式无效，跳过
+        }
+      }
+    }
+  }
+
+  async tick(now?: number): Promise<void> {
+    const currentTime = now ?? Date.now();
+    const tasks = await this.repo.listTasks();
+
+    for (const task of tasks) {
+      if (!task.enabled) continue;
+      if (this.runningTasks.has(task.id)) continue;
+      if (!task.nextruntime || task.nextruntime > currentTime) continue;
+
+      // 不 await，并行执行多个任务
+      this.executeTask(task).catch(() => {
+        // 错误已在 executeTask 内部处理
+      });
+    }
+  }
+
+  async executeTask(task: AgentTask): Promise<void> {
+    if (this.runningTasks.has(task.id)) return;
+    this.runningTasks.add(task.id);
+
+    const run: AgentTaskRun = {
+      id: uuidv4(),
+      taskId: task.id,
+      starttime: Date.now(),
+      status: "running",
+    };
+    await this.runRepo.appendRun(run);
+
+    try {
+      if (task.mode === "internal") {
+        const result = await this.internalExecutor(task);
+        run.conversationId = result.conversationId;
+        run.usage = result.usage;
+      } else {
+        await this.eventEmitter(task);
+      }
+
+      run.status = "success";
+      run.endtime = Date.now();
+
+      task.lastRunStatus = "success";
+      task.lastRunError = undefined;
+    } catch (e: any) {
+      run.status = "error";
+      run.error = e.message || "Unknown error";
+      run.endtime = Date.now();
+
+      task.lastRunStatus = "error";
+      task.lastRunError = run.error;
+    } finally {
+      this.runningTasks.delete(task.id);
+
+      // 更新 run 记录
+      await this.runRepo.updateRun(run.id, {
+        status: run.status,
+        endtime: run.endtime,
+        error: run.error,
+        conversationId: run.conversationId,
+        usage: run.usage,
+      });
+
+      // 更新 task 状态
+      task.lastruntime = run.starttime;
+      try {
+        const info = nextTimeInfo(task.crontab);
+        task.nextruntime = info.next.toMillis();
+      } catch {
+        task.nextruntime = undefined;
+      }
+      task.updatetime = Date.now();
+      await this.repo.saveTask(task);
+    }
+  }
+
+  isRunning(taskId: string): boolean {
+    return this.runningTasks.has(taskId);
+  }
+}
diff --git a/src/app/service/agent/tool_registry.test.ts b/src/app/service/agent/tool_registry.test.ts
new file mode 100644
index 000000000..69e1210ce
--- /dev/null
+++ b/src/app/service/agent/tool_registry.test.ts
@@ -0,0 +1,430 @@
+import { describe, it, expect, vi } from "vitest";
+import { ToolRegistry } from "./tool_registry";
+import type { ToolExecutor } from "./tool_registry";
+import type { ToolCall, ToolDefinition, ToolResultWithAttachments } from "./types";
+import type { AgentChatRepo } from "@App/app/repo/agent_chat";
+
+vi.mock("@App/pkg/utils/uuid", () => ({
+  uuidv4: vi.fn(() => "mock-uuid-" + Math.random().toString(36).slice(2, 8)),
+}));
+
+// 创建一个简单的 mock executor
+function createExecutor(fn: (args: Record<string, unknown>) => Promise<unknown>): ToolExecutor {
+  return { execute: fn };
+}
+
+const weatherDef: ToolDefinition = {
+  name: "get_weather",
+  description: "获取天气",
+  parameters: { type: "object", properties: { city: { type: "string" } } },
+};
+
+const calcDef: ToolDefinition = {
+  name: "calc",
+  description: "计算器",
+  parameters: { type: "object", properties: { expr: { type: "string" } } },
+};
+
+describe("ToolRegistry", () => {
+  describe("registerBuiltin / unregisterBuiltin", () => {
+    it("应正确注册和注销内置工具", () => {
+      const registry = new ToolRegistry();
+      const executor = createExecutor(async () => "ok");
+      registry.registerBuiltin(weatherDef, executor);
+
+      expect(registry.getDefinitions()).toHaveLength(1);
+      expect(registry.getDefinitions()[0].name).toBe("get_weather");
+
+      const removed = registry.unregisterBuiltin("get_weather");
+      expect(removed).toBe(true);
+      expect(registry.getDefinitions()).toHaveLength(0);
+    });
+
+    it("注销不存在的工具应返回 false", () => {
+      const registry = new ToolRegistry();
+      expect(registry.unregisterBuiltin("nonexistent")).toBe(false);
+    });
+
+    it("重复注册同名工具应覆盖", () => {
+      const registry = new ToolRegistry();
+      const executor1 = createExecutor(async () => "v1");
+      const executor2 = createExecutor(async () => "v2");
+
+      registry.registerBuiltin(weatherDef, executor1);
+      registry.registerBuiltin(weatherDef, executor2);
+
+      expect(registry.getDefinitions()).toHaveLength(1);
+    });
+  });
+
+  describe("getDefinitions", () => {
+    it("应合并内置和额外的工具定义", () => {
+      const registry = new ToolRegistry();
+      registry.registerBuiltin(
+        weatherDef,
+        createExecutor(async () => "")
+      );
+
+      const defs = registry.getDefinitions([calcDef]);
+      expect(defs).toHaveLength(2);
+      expect(defs.map((d) => d.name)).toEqual(["get_weather", "calc"]);
+    });
+
+    it("没有注册工具时返回空数组", () => {
+      const registry = new ToolRegistry();
+      expect(registry.getDefinitions()).toHaveLength(0);
+    });
+
+    it("extraTools 为 undefined 时只返回内置工具", () => {
+      const registry = new ToolRegistry();
+      registry.registerBuiltin(
+        weatherDef,
+        createExecutor(async () => "")
+      );
+      const defs = registry.getDefinitions(undefined);
+      expect(defs).toHaveLength(1);
+    });
+  });
+
+  describe("execute", () => {
+    it("应正确执行内置工具", async () => {
+      const registry = new ToolRegistry();
+      const executor = createExecutor(async (args) => `${args.city}的天气：晴`);
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: '{"city":"北京"}' }]);
+
+      expect(results).toHaveLength(1);
+      expect(results[0].id).toBe("tc_1");
+      expect(results[0].result).toBe("北京的天气：晴");
+    });
+
+    it("内置工具返回非字符串时应 JSON.stringify", async () => {
+      const registry = new ToolRegistry();
+      const executor = createExecutor(async () => ({ temp: 25, unit: "C" }));
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: '{"city":"上海"}' }]);
+
+      expect(results[0].result).toBe('{"temp":25,"unit":"C"}');
+    });
+
+    it("空 arguments 时应传入空对象", async () => {
+      const registry = new ToolRegistry();
+      const executeSpy = vi.fn().mockResolvedValue("ok");
+      registry.registerBuiltin(weatherDef, { execute: executeSpy });
+
+      await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "" }]);
+
+      expect(executeSpy).toHaveBeenCalledWith({});
+    });
+
+    it("内置工具抛出异常时应返回错误信息", async () => {
+      const registry = new ToolRegistry();
+      const executor = createExecutor(async () => {
+        throw new Error("API 请求失败");
+      });
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: '{"city":"error"}' }]);
+
+      expect(results).toHaveLength(1);
+      const parsed = JSON.parse(results[0].result);
+      expect(parsed.error).toBe("API 请求失败");
+    });
+
+    it("内置工具抛出无 message 的异常时应返回默认错误", async () => {
+      const registry = new ToolRegistry();
+      const executor = createExecutor(async () => {
+        throw {};
+      });
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      const parsed = JSON.parse(results[0].result);
+      expect(parsed.error).toBe("Tool execution failed");
+    });
+
+    it("未找到的工具应转发给 scriptCallback", async () => {
+      const registry = new ToolRegistry();
+      const scriptCallback = vi.fn().mockResolvedValue([{ id: "tc_1", result: "script result" }]);
+
+      const results = await registry.execute([{ id: "tc_1", name: "unknown_tool", arguments: "{}" }], scriptCallback);
+
+      expect(scriptCallback).toHaveBeenCalledWith([{ id: "tc_1", name: "unknown_tool", arguments: "{}" }]);
+      expect(results[0].result).toBe("script result");
+    });
+
+    it("无 scriptCallback 时未找到的工具返回错误", async () => {
+      const registry = new ToolRegistry();
+
+      const results = await registry.execute([{ id: "tc_1", name: "unknown_tool", arguments: "{}" }]);
+
+      const parsed = JSON.parse(results[0].result);
+      expect(parsed.error).toContain("unknown_tool");
+      expect(parsed.error).toContain("not found");
+    });
+
+    it("scriptCallback 为 null 时未找到的工具返回错误", async () => {
+      const registry = new ToolRegistry();
+
+      const results = await registry.execute([{ id: "tc_1", name: "unknown_tool", arguments: "{}" }], null);
+
+      const parsed = JSON.parse(results[0].result);
+      expect(parsed.error).toContain("not found");
+    });
+
+    it("应正确分离内置和脚本工具并分别执行", async () => {
+      const registry = new ToolRegistry();
+      const builtinExecutor = createExecutor(async () => "builtin_result");
+      registry.registerBuiltin(weatherDef, builtinExecutor);
+
+      const scriptCallback = vi.fn().mockResolvedValue([{ id: "tc_2", result: "script_result" }]);
+
+      const toolCalls: ToolCall[] = [
+        { id: "tc_1", name: "get_weather", arguments: '{"city":"杭州"}' },
+        { id: "tc_2", name: "custom_tool", arguments: '{"key":"val"}' },
+      ];
+
+      const results = await registry.execute(toolCalls, scriptCallback);
+
+      expect(results).toHaveLength(2);
+      // 内置工具结果
+      expect(results.find((r) => r.id === "tc_1")?.result).toBe("builtin_result");
+      // 脚本工具结果
+      expect(results.find((r) => r.id === "tc_2")?.result).toBe("script_result");
+      // scriptCallback 只收到脚本工具
+      expect(scriptCallback).toHaveBeenCalledWith([toolCalls[1]]);
+    });
+
+    it("空 toolCalls 数组时应返回空结果", async () => {
+      const registry = new ToolRegistry();
+      const results = await registry.execute([]);
+      expect(results).toHaveLength(0);
+    });
+
+    it("JSON 解析失败时应返回错误", async () => {
+      const registry = new ToolRegistry();
+      const executor = createExecutor(async () => "ok");
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "invalid json{" }]);
+
+      const parsed = JSON.parse(results[0].result);
+      expect(parsed.error).toBeDefined();
+    });
+  });
+
+  describe("附件处理", () => {
+    function createMockChatRepo() {
+      return {
+        saveAttachment: vi.fn().mockResolvedValue(1024),
+        getAttachment: vi.fn().mockResolvedValue(null),
+        deleteAttachment: vi.fn().mockResolvedValue(undefined),
+        deleteAttachments: vi.fn().mockResolvedValue(undefined),
+      } as unknown as AgentChatRepo;
+    }
+
+    it("内置工具返回 ToolResultWithAttachments 时应提取附件并保存", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const structuredResult: ToolResultWithAttachments = {
+        content: "Screenshot captured.",
+        attachments: [
+          { type: "image", name: "screenshot.jpg", mimeType: "image/jpeg", data: "data:image/jpeg;base64,/9j/abc" },
+        ],
+      };
+      const executor = createExecutor(async () => structuredResult);
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      // 文本结果只包含 content
+      expect(results[0].result).toBe("Screenshot captured.");
+      // 附件元数据
+      expect(results[0].attachments).toHaveLength(1);
+      expect(results[0].attachments![0].type).toBe("image");
+      expect(results[0].attachments![0].name).toBe("screenshot.jpg");
+      expect(results[0].attachments![0].mimeType).toBe("image/jpeg");
+      expect(results[0].attachments![0].size).toBe(1024);
+      expect(results[0].attachments![0].id).toMatch(/^mock-uuid-/);
+      // 验证 chatRepo.saveAttachment 被调用
+      expect(mockRepo.saveAttachment).toHaveBeenCalledTimes(1);
+      expect(mockRepo.saveAttachment).toHaveBeenCalledWith(
+        expect.stringMatching(/^mock-uuid-/),
+        "data:image/jpeg;base64,/9j/abc"
+      );
+    });
+
+    it("内置工具返回 ToolResultWithAttachments 含多个附件时应全部保存", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const structuredResult: ToolResultWithAttachments = {
+        content: "Files generated.",
+        attachments: [
+          { type: "image", name: "img1.png", mimeType: "image/png", data: "data:image/png;base64,abc" },
+          {
+            type: "file",
+            name: "report.xlsx",
+            mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            data: "base64data",
+          },
+        ],
+      };
+      const executor = createExecutor(async () => structuredResult);
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      expect(results[0].attachments).toHaveLength(2);
+      expect(results[0].attachments![0].name).toBe("img1.png");
+      expect(results[0].attachments![1].name).toBe("report.xlsx");
+      expect(mockRepo.saveAttachment).toHaveBeenCalledTimes(2);
+    });
+
+    it("内置工具返回 Blob 附件时应正确保存", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const blob = new Blob(["hello"], { type: "text/plain" });
+      const structuredResult: ToolResultWithAttachments = {
+        content: "File created.",
+        attachments: [{ type: "file", name: "data.txt", mimeType: "text/plain", data: blob as unknown as string }],
+      };
+      const executor = createExecutor(async () => structuredResult);
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      expect(results[0].attachments).toHaveLength(1);
+      expect(mockRepo.saveAttachment).toHaveBeenCalledWith(expect.any(String), blob);
+    });
+
+    it("内置工具返回普通值时不应产生附件", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const executor = createExecutor(async () => "plain result");
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      expect(results[0].result).toBe("plain result");
+      expect(results[0].attachments).toBeUndefined();
+      expect(mockRepo.saveAttachment).not.toHaveBeenCalled();
+    });
+
+    it("内置工具返回对象（非附件格式）时不应产生附件", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      // 有 content 但没有 attachments 数组
+      const executor = createExecutor(async () => ({ content: "hello", other: 42 }));
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      expect(results[0].result).toBe('{"content":"hello","other":42}');
+      expect(results[0].attachments).toBeUndefined();
+    });
+
+    it("无 chatRepo 时应返回空附件列表", async () => {
+      const registry = new ToolRegistry();
+      // 不调用 setChatRepo
+
+      const structuredResult: ToolResultWithAttachments = {
+        content: "Screenshot captured.",
+        attachments: [
+          { type: "image", name: "screenshot.jpg", mimeType: "image/jpeg", data: "data:image/jpeg;base64,abc" },
+        ],
+      };
+      const executor = createExecutor(async () => structuredResult);
+      registry.registerBuiltin(weatherDef, executor);
+
+      const results = await registry.execute([{ id: "tc_1", name: "get_weather", arguments: "{}" }]);
+
+      expect(results[0].result).toBe("Screenshot captured.");
+      // 无 chatRepo 时附件为空数组
+      expect(results[0].attachments).toEqual([]);
+    });
+
+    it("脚本工具返回结构化附件结果时应提取附件", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const structuredResult: ToolResultWithAttachments = {
+        content: "CATTool generated file.",
+        attachments: [{ type: "file", name: "output.zip", mimeType: "application/zip", data: "base64zipdata" }],
+      };
+
+      const scriptCallback = vi.fn().mockResolvedValue([{ id: "tc_1", result: JSON.stringify(structuredResult) }]);
+
+      const results = await registry.execute([{ id: "tc_1", name: "script_tool", arguments: "{}" }], scriptCallback);
+
+      expect(results[0].result).toBe("CATTool generated file.");
+      expect(results[0].attachments).toHaveLength(1);
+      expect(results[0].attachments![0].name).toBe("output.zip");
+      expect(mockRepo.saveAttachment).toHaveBeenCalledTimes(1);
+    });
+
+    it("脚本工具返回普通 JSON 时不应产生附件", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const scriptCallback = vi.fn().mockResolvedValue([{ id: "tc_1", result: JSON.stringify({ data: "hello" }) }]);
+
+      const results = await registry.execute([{ id: "tc_1", name: "script_tool", arguments: "{}" }], scriptCallback);
+
+      expect(results[0].result).toBe('{"data":"hello"}');
+      expect(results[0].attachments).toBeUndefined();
+    });
+
+    it("脚本工具返回非 JSON 字符串时不应产生附件", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      const scriptCallback = vi.fn().mockResolvedValue([{ id: "tc_1", result: "plain text result" }]);
+
+      const results = await registry.execute([{ id: "tc_1", name: "script_tool", arguments: "{}" }], scriptCallback);
+
+      expect(results[0].result).toBe("plain text result");
+      expect(results[0].attachments).toBeUndefined();
+    });
+
+    it("isToolResultWithAttachments 边界值判断", async () => {
+      const registry = new ToolRegistry();
+      const mockRepo = createMockChatRepo();
+      registry.setChatRepo(mockRepo);
+
+      // null
+      const exec1 = createExecutor(async () => null);
+      registry.registerBuiltin(weatherDef, exec1);
+      const r1 = await registry.execute([{ id: "t1", name: "get_weather", arguments: "{}" }]);
+      expect(r1[0].result).toBe("null");
+      expect(r1[0].attachments).toBeUndefined();
+
+      // content 是数字而不是字符串
+      const exec2 = createExecutor(async () => ({ content: 123, attachments: [] }));
+      registry.registerBuiltin(weatherDef, exec2);
+      const r2 = await registry.execute([{ id: "t2", name: "get_weather", arguments: "{}" }]);
+      expect(r2[0].attachments).toBeUndefined();
+
+      // attachments 不是数组
+      const exec3 = createExecutor(async () => ({ content: "ok", attachments: "not-array" }));
+      registry.registerBuiltin(weatherDef, exec3);
+      const r3 = await registry.execute([{ id: "t3", name: "get_weather", arguments: "{}" }]);
+      expect(r3[0].attachments).toBeUndefined();
+    });
+  });
+});
diff --git a/src/app/service/agent/tool_registry.ts b/src/app/service/agent/tool_registry.ts
new file mode 100644
index 000000000..d6ece1183
--- /dev/null
+++ b/src/app/service/agent/tool_registry.ts
@@ -0,0 +1,143 @@
+import type { Attachment, ToolCall, ToolDefinition, ToolResultWithAttachments } from "./types";
+import type { AgentChatRepo } from "@App/app/repo/agent_chat";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+// 工具执行器接口
+export interface ToolExecutor {
+  execute(args: Record<string, unknown>): Promise<unknown>;
+}
+
+// 脚本工具回调类型：将 tool calls 发送到 Sandbox 执行
+export type ScriptToolCallback = (toolCalls: ToolCall[]) => Promise<Array<{ id: string; result: string }>>;
+
+// 工具执行结果（可能含附件）
+export type ToolExecuteResult = {
+  id: string;
+  result: string;
+  attachments?: Attachment[];
+};
+
+// 判断返回值是否是带附件的结构化结果
+function isToolResultWithAttachments(value: unknown): value is ToolResultWithAttachments {
+  if (typeof value !== "object" || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.content === "string" && Array.isArray(obj.attachments);
+}
+
+// 工具注册表，管理内置工具和脚本工具的统一执行
+export class ToolRegistry {
+  private builtinTools = new Map<string, { definition: ToolDefinition; executor: ToolExecutor }>();
+  private chatRepo?: AgentChatRepo;
+
+  // 注入 AgentChatRepo 用于保存附件
+  setChatRepo(repo: AgentChatRepo): void {
+    this.chatRepo = repo;
+  }
+
+  // 注册内置工具（由 SW 直接执行）
+  registerBuiltin(definition: ToolDefinition, executor: ToolExecutor): void {
+    this.builtinTools.set(definition.name, { definition, executor });
+  }
+
+  // 注销内置工具
+  unregisterBuiltin(name: string): boolean {
+    return this.builtinTools.delete(name);
+  }
+
+  // 获取所有工具定义（内置 + 额外的脚本工具），发送给 LLM
+  getDefinitions(extraTools?: ToolDefinition[]): ToolDefinition[] {
+    const definitions: ToolDefinition[] = [];
+    for (const { definition } of this.builtinTools.values()) {
+      definitions.push(definition);
+    }
+    if (extraTools) {
+      definitions.push(...extraTools);
+    }
+    return definitions;
+  }
+
+  // 执行工具调用：先查内置工具，未找到则交给脚本回调
+  async execute(toolCalls: ToolCall[], scriptCallback?: ScriptToolCallback | null): Promise<ToolExecuteResult[]> {
+    const builtinCalls: ToolCall[] = [];
+    const scriptCalls: ToolCall[] = [];
+
+    for (const tc of toolCalls) {
+      if (this.builtinTools.has(tc.name)) {
+        builtinCalls.push(tc);
+      } else {
+        scriptCalls.push(tc);
+      }
+    }
+
+    const results: ToolExecuteResult[] = [];
+
+    // 执行内置工具
+    for (const tc of builtinCalls) {
+      const tool = this.builtinTools.get(tc.name)!;
+      try {
+        let args: Record<string, unknown> = {};
+        if (tc.arguments) {
+          args = JSON.parse(tc.arguments);
+        }
+        const rawResult = await tool.executor.execute(args);
+
+        // 检查是否带附件
+        if (isToolResultWithAttachments(rawResult)) {
+          const attachments = await this.saveAttachments(rawResult.attachments);
+          results.push({ id: tc.id, result: rawResult.content, attachments });
+        } else {
+          results.push({ id: tc.id, result: typeof rawResult === "string" ? rawResult : JSON.stringify(rawResult) });
+        }
+      } catch (e: any) {
+        results.push({ id: tc.id, result: JSON.stringify({ error: e.message || "Tool execution failed" }) });
+      }
+    }
+
+    // 执行脚本工具
+    if (scriptCalls.length > 0) {
+      if (scriptCallback) {
+        const scriptResults = await scriptCallback(scriptCalls);
+        // 脚本工具也可能返回带附件的结构化结果
+        for (const sr of scriptResults) {
+          try {
+            const parsed = JSON.parse(sr.result);
+            if (isToolResultWithAttachments(parsed)) {
+              const attachments = await this.saveAttachments(parsed.attachments);
+              results.push({ id: sr.id, result: parsed.content, attachments });
+              continue;
+            }
+          } catch {
+            // 不是 JSON 或不是结构化结果，按原始字符串处理
+          }
+          results.push({ id: sr.id, result: sr.result });
+        }
+      } else {
+        // 没有脚本回调，返回错误
+        for (const tc of scriptCalls) {
+          results.push({ id: tc.id, result: JSON.stringify({ error: `Tool "${tc.name}" not found` }) });
+        }
+      }
+    }
+
+    return results;
+  }
+
+  // 保存附件数据到 OPFS，返回 Attachment 元数据
+  private async saveAttachments(attachmentDataList: ToolResultWithAttachments["attachments"]): Promise<Attachment[]> {
+    if (!this.chatRepo || attachmentDataList.length === 0) return [];
+
+    const attachments: Attachment[] = [];
+    for (const ad of attachmentDataList) {
+      const id = uuidv4();
+      const size = await this.chatRepo.saveAttachment(id, ad.data);
+      attachments.push({
+        id,
+        type: ad.type,
+        name: ad.name,
+        mimeType: ad.mimeType,
+        size,
+      });
+    }
+    return attachments;
+  }
+}
diff --git a/src/app/service/agent/types.ts b/src/app/service/agent/types.ts
new file mode 100644
index 000000000..1e73da15b
--- /dev/null
+++ b/src/app/service/agent/types.ts
@@ -0,0 +1,544 @@
+// ---- 通用类型 ----
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+// ---- ContentBlock 多模态内容类型 ----
+
+export type TextBlock = { type: "text"; text: string };
+export type ImageBlock = { type: "image"; attachmentId: string; mimeType: string; name?: string };
+export type FileBlock = { type: "file"; attachmentId: string; mimeType: string; name: string; size?: number };
+export type AudioBlock = { type: "audio"; attachmentId: string; mimeType: string; name?: string; durationMs?: number };
+
+export type ContentBlock = TextBlock | ImageBlock | FileBlock | AudioBlock;
+export type MessageContent = string | ContentBlock[];
+
+export type Conversation = {
+  id: string;
+  title: string;
+  modelId: string;
+  system?: string;
+  skills?: "auto" | string[];
+  createtime: number;
+  updatetime: number;
+};
+
+export type MessageRole = "user" | "assistant" | "system" | "tool";
+
+export type Attachment = {
+  id: string;
+  type: "image" | "file" | "audio";
+  name: string; // 文件名
+  mimeType: string; // "image/jpeg", "application/zip" 等
+  size?: number; // 字节数
+  // 数据不内联存储，通过 id 从 OPFS 加载
+};
+
+export type AttachmentData = {
+  type: "image" | "file" | "audio";
+  name: string;
+  mimeType: string;
+  data: string | Blob; // base64/data URL 或 Blob
+};
+
+export type ToolResultWithAttachments = {
+  content: string; // 文本结果（发给 LLM）
+  attachments: AttachmentData[]; // 附件数据（仅存储+展示）
+};
+
+export type ToolCall = {
+  id: string;
+  name: string;
+  arguments: string;
+  result?: string;
+  attachments?: Attachment[];
+  status?: "pending" | "running" | "completed" | "error";
+};
+
+export type ThinkingBlock = {
+  content: string;
+};
+
+export type ChatMessage = {
+  id: string;
+  conversationId: string;
+  role: MessageRole;
+  content: MessageContent;
+  thinking?: ThinkingBlock;
+  toolCalls?: ToolCall[];
+  // tool 角色的消息需要关联到对应的 tool_call
+  toolCallId?: string;
+  error?: string;
+  modelId?: string;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+  };
+  durationMs?: number;
+  firstTokenMs?: number;
+  parentId?: string;
+  createtime: number;
+};
+
+// Service Worker -> UI/Sandbox 的流式事件（通过 MessageConnect 的 sendMessage 传输）
+export type ChatStreamEvent =
+  | { type: "content_delta"; delta: string }
+  | { type: "thinking_delta"; delta: string }
+  | { type: "tool_call_start"; toolCall: Omit<ToolCall, "result"> }
+  | { type: "tool_call_delta"; id: string; delta: string }
+  | { type: "tool_call_complete"; id: string; result: string; attachments?: Attachment[] }
+  | { type: "content_block_start"; block: Omit<ImageBlock | FileBlock | AudioBlock, "attachmentId"> }
+  | { type: "content_block_complete"; block: ImageBlock | FileBlock | AudioBlock }
+  | { type: "new_message" }
+  | {
+      type: "done";
+      usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheCreationInputTokens?: number;
+        cacheReadInputTokens?: number;
+      };
+      durationMs?: number;
+    }
+  | { type: "error"; message: string; errorCode?: string };
+
+// UI -> Service Worker 的聊天请求
+export type ChatRequest = {
+  conversationId: string;
+  modelId: string;
+  messages: Array<{ role: MessageRole; content: MessageContent; toolCallId?: string; toolCalls?: ToolCall[] }>;
+  tools?: ToolDefinition[];
+  cache?: boolean; // 是否启用 prompt caching（Anthropic），默认 true。短对话（如子 agent）可关闭以节省开销
+};
+
+// ---- Agent 模型配置 ----
+
+export type AgentModelConfig = {
+  id: string; // 唯一标识
+  name: string; // 用户自定义名称（如 "GPT-4o", "Claude Sonnet"）
+  provider: "openai" | "anthropic";
+  apiBaseUrl: string;
+  apiKey: string;
+  model: string;
+  maxTokens?: number; // 最大输出 token 数，不设置则由 API 端决定
+};
+
+// ---- CAT.agent.conversation 用户脚本 API 类型 ----
+
+// 工具定义（用户脚本传入的格式）
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>; // JSON Schema
+};
+
+// 命令处理器类型
+export type CommandHandler = (args: string, conv: any) => Promise<string | void>;
+
+// conversation.create() 的参数
+export type ConversationCreateOptions = {
+  id?: string;
+  system?: string;
+  model?: string; // modelId，不传则使用默认模型
+  maxIterations?: number; // tool calling 最大循环次数，默认 20
+  skills?: "auto" | string[]; // 加载的 Skill，"auto" 加载全部，数组指定名称
+  tools?: Array<ToolDefinition & { handler: (args: Record<string, unknown>) => Promise<unknown> }>;
+  commands?: Record<string, CommandHandler>; // 自定义命令处理器，以 / 开头
+  ephemeral?: boolean; // 临时会话：不持久化、不加载内置资源、工具由脚本提供
+  cache?: boolean; // 是否启用 prompt caching，默认 true
+};
+
+// conv.chat() 的参数
+export type ChatOptions = {
+  tools?: Array<ToolDefinition & { handler: (args: Record<string, unknown>) => Promise<unknown> }>;
+};
+
+// conv.chat() 的返回值
+export type ChatReply = {
+  content: MessageContent;
+  thinking?: string;
+  toolCalls?: ToolCall[];
+  usage?: { inputTokens: number; outputTokens: number };
+  command?: boolean; // 标识该回复来自命令处理
+};
+
+// conv.chatStream() 的流式 chunk
+export type StreamChunk = {
+  type: "content_delta" | "thinking_delta" | "tool_call" | "content_block" | "done" | "error";
+  content?: string;
+  block?: ContentBlock;
+  toolCall?: ToolCall;
+  usage?: { inputTokens: number; outputTokens: number };
+  error?: string;
+  /** 错误分类码："rate_limit" | "auth" | "tool_timeout" | "max_iterations" | "api_error" */
+  errorCode?: string;
+  command?: boolean; // 标识该 chunk 来自命令处理
+};
+
+// ---- Skill 类型 ----
+
+// Skill config 字段定义（SKILL.md frontmatter 中声明）
+export type SkillConfigField = {
+  title: string;
+  type: "text" | "number" | "select" | "switch";
+  secret?: boolean;
+  required?: boolean;
+  default?: unknown;
+  values?: string[]; // select 类型的选项列表
+};
+
+// Skill 摘要（registry.json 中）
+export type SkillSummary = {
+  name: string;
+  description: string;
+  toolNames: string[]; // 随 Skill 打包的 CATTool 名称（scripts/ 目录下）
+  referenceNames: string[]; // 参考资料名称（references/ 目录下）
+  hasConfig?: boolean; // 是否有 config 字段声明
+  installtime: number;
+  updatetime: number;
+};
+
+// SKILL.md frontmatter 解析结果
+export type SkillMetadata = {
+  name: string;
+  description: string;
+  config?: Record<string, SkillConfigField>;
+};
+
+// 完整 Skill 记录
+export type SkillRecord = SkillSummary & {
+  prompt: string; // SKILL.md body（去 frontmatter 后的 markdown）
+  config?: Record<string, SkillConfigField>; // config schema（来自 SKILL.md frontmatter）
+};
+
+// Skill 参考资料
+export type SkillReference = {
+  name: string;
+  content: string;
+};
+
+// CAT.agent.skills API 请求
+export type SkillApiRequest =
+  | { action: "list"; scriptUuid: string }
+  | { action: "get"; name: string; scriptUuid: string }
+  | {
+      action: "install";
+      skillMd: string;
+      scripts?: Array<{ name: string; code: string }>;
+      references?: Array<{ name: string; content: string }>;
+      scriptUuid: string;
+    }
+  | { action: "remove"; name: string; scriptUuid: string };
+
+// ---- CATTool 类型 ----
+
+export type CATToolParam = {
+  name: string;
+  type: "string" | "number" | "boolean";
+  required: boolean;
+  description: string;
+  enum?: string[];
+};
+
+export type CATToolMetadata = {
+  name: string;
+  description: string;
+  params: CATToolParam[];
+  grants: string[];
+  requires: string[];
+  timeout?: number; // 自定义超时时间（秒）
+};
+
+// OPFS 中存储的 CATTool 记录
+export type CATToolRecord = {
+  id: string; // UUID，用于 OPFS data 文件名，避免 name 转文件名时的碰撞
+  name: string;
+  description: string;
+  params: CATToolParam[];
+  grants: string[];
+  requires?: string[]; // @require URL 列表
+  timeout?: number; // 自定义超时时间（秒）
+  code: string; // 完整代码（含元数据头）
+  sourceScriptUuid?: string; // 安装来源脚本的 UUID
+  sourceScriptName?: string; // 安装来源脚本的名称
+  installtime: number;
+  updatetime: number;
+};
+
+// CAT.agent.tools API 请求
+export type CATToolApiRequest =
+  | { action: "install"; code: string; scriptUuid: string }
+  | { action: "remove"; name: string; scriptUuid: string }
+  | { action: "list"; scriptUuid: string }
+  | { action: "call"; name: string; params: Record<string, unknown>; scriptUuid: string };
+
+// ---- CAT.agent.dom 类型 ----
+
+export type TabInfo = {
+  tabId: number;
+  url: string;
+  title: string;
+  active: boolean;
+  windowId: number;
+  discarded: boolean;
+};
+
+export type ActionResult = {
+  success: boolean;
+  navigated?: boolean;
+  url?: string;
+  newTab?: { tabId: number; url: string };
+};
+
+export type PageContent = {
+  title: string;
+  url: string;
+  html: string;
+  truncated?: boolean;
+  totalLength?: number;
+};
+
+export type ReadPageOptions = {
+  tabId?: number;
+  selector?: string;
+  maxLength?: number;
+  removeTags?: string[]; // 要移除的标签/选择器，如 ["script", "style", "svg"]
+};
+
+export type DomActionOptions = {
+  tabId?: number;
+  trusted?: boolean;
+};
+
+export type WaitForOptions = {
+  tabId?: number;
+  timeout?: number;
+};
+
+export type ScreenshotOptions = {
+  tabId?: number;
+  quality?: number;
+  fullPage?: boolean;
+};
+
+export type NavigateOptions = {
+  tabId?: number;
+  waitUntil?: boolean;
+  timeout?: number;
+};
+
+export type ScrollDirection = "up" | "down" | "top" | "bottom";
+
+export type ScrollOptions = {
+  tabId?: number;
+  selector?: string;
+};
+
+export type ScrollResult = {
+  scrollTop: number;
+  scrollHeight: number;
+  clientHeight: number;
+  atBottom: boolean;
+};
+
+export type NavigateResult = {
+  tabId: number;
+  url: string;
+  title: string;
+};
+
+export type WaitForResult = {
+  found: boolean;
+  element?: {
+    selector: string;
+    tag: string;
+    text: string;
+    role?: string;
+    type?: string;
+    visible: boolean;
+  };
+};
+
+// GM API 请求类型
+export type ExecuteScriptOptions = {
+  tabId?: number;
+};
+
+export type MonitorResult = {
+  dialogs: Array<{ type: string; message: string }>;
+  addedNodes: Array<{ tag: string; id?: string; class?: string; role?: string; text: string }>;
+};
+
+export type MonitorStatus = {
+  hasChanges: boolean;
+  dialogCount: number;
+  nodeCount: number;
+};
+
+export type DomApiRequest =
+  | { action: "listTabs"; scriptUuid: string }
+  | { action: "navigate"; url: string; options?: NavigateOptions; scriptUuid: string }
+  | { action: "readPage"; options?: ReadPageOptions; scriptUuid: string }
+  | { action: "screenshot"; options?: ScreenshotOptions; scriptUuid: string }
+  | { action: "click"; selector: string; options?: DomActionOptions; scriptUuid: string }
+  | { action: "fill"; selector: string; value: string; options?: DomActionOptions; scriptUuid: string }
+  | { action: "scroll"; direction: ScrollDirection; options?: ScrollOptions; scriptUuid: string }
+  | { action: "waitFor"; selector: string; options?: WaitForOptions; scriptUuid: string }
+  | { action: "executeScript"; code: string; options?: ExecuteScriptOptions; scriptUuid: string }
+  | { action: "startMonitor"; tabId: number; scriptUuid: string }
+  | { action: "stopMonitor"; tabId: number; scriptUuid: string }
+  | { action: "peekMonitor"; tabId: number; scriptUuid: string };
+
+// ---- MCP 类型 ----
+
+// MCP 服务器配置
+export type MCPServerConfig = {
+  id: string;
+  name: string;
+  url: string; // Streamable HTTP endpoint
+  apiKey?: string; // 可选认证
+  headers?: Record<string, string>; // 自定义请求头
+  enabled: boolean;
+  createtime: number;
+  updatetime: number;
+};
+
+// MCP 工具（从服务器 tools/list 获取）
+export type MCPTool = {
+  serverId: string;
+  name: string;
+  description?: string;
+  inputSchema: Record<string, unknown>; // JSON Schema
+};
+
+// MCP 资源（从服务器 resources/list 获取）
+export type MCPResource = {
+  serverId: string;
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+};
+
+// MCP 提示词模板（从服务器 prompts/list 获取）
+export type MCPPrompt = {
+  serverId: string;
+  name: string;
+  description?: string;
+  arguments?: Array<{
+    name: string;
+    description?: string;
+    required?: boolean;
+  }>;
+};
+
+// MCP 提示词消息（prompts/get 返回）
+export type MCPPromptMessage = {
+  role: "user" | "assistant";
+  content:
+    | { type: "text"; text: string }
+    | { type: "resource"; resource: { uri: string; text: string; mimeType?: string } };
+};
+
+// CAT.agent.mcp API 请求
+export type MCPApiRequest =
+  | { action: "listServers"; scriptUuid: string }
+  | { action: "getServer"; id: string; scriptUuid: string }
+  | {
+      action: "addServer";
+      config: Omit<MCPServerConfig, "id" | "createtime" | "updatetime">;
+      scriptUuid: string;
+    }
+  | { action: "updateServer"; id: string; config: Partial<MCPServerConfig>; scriptUuid: string }
+  | { action: "removeServer"; id: string; scriptUuid: string }
+  | { action: "listTools"; serverId: string; scriptUuid: string }
+  | { action: "listResources"; serverId: string; scriptUuid: string }
+  | { action: "readResource"; serverId: string; uri: string; scriptUuid: string }
+  | { action: "listPrompts"; serverId: string; scriptUuid: string }
+  | {
+      action: "getPrompt";
+      serverId: string;
+      name: string;
+      args?: Record<string, string>;
+      scriptUuid: string;
+    }
+  | { action: "testConnection"; id: string; scriptUuid: string };
+
+// ---- Agent 定时任务类型 ----
+
+export type AgentTask = {
+  id: string;
+  name: string;
+  crontab: string; // cron 表达式（复用 cron.ts 格式）
+  mode: "internal" | "event"; // internal: SW 自主执行; event: 通知脚本
+  enabled: boolean;
+  notify: boolean; // 是否通过 chrome.notifications 通知
+
+  // --- internal 模式字段 ---
+  prompt?: string; // 每次触发发送的消息
+  modelId?: string; // 使用的模型 ID
+  conversationId?: string; // 可选：续接已有对话
+  skills?: "auto" | string[];
+  maxIterations?: number; // 工具循环上限，默认 10
+
+  // --- event 模式字段 ---
+  sourceScriptUuid?: string; // 创建任务的脚本 UUID
+
+  // --- 运行状态 ---
+  lastruntime?: number;
+  nextruntime?: number;
+  lastRunStatus?: "success" | "error";
+  lastRunError?: string;
+  createtime: number;
+  updatetime: number;
+};
+
+export type AgentTaskTrigger = {
+  taskId: string;
+  name: string;
+  crontab: string;
+  triggeredAt: number;
+};
+
+export type AgentTaskRun = {
+  id: string;
+  taskId: string;
+  conversationId?: string; // internal 模式才有
+  starttime: number;
+  endtime?: number;
+  status: "running" | "success" | "error";
+  error?: string;
+  usage?: { inputTokens: number; outputTokens: number };
+};
+
+export type AgentTaskApiRequest =
+  | { action: "list" }
+  | { action: "get"; id: string }
+  | { action: "create"; task: Omit<AgentTask, "id" | "createtime" | "updatetime" | "nextruntime"> }
+  | { action: "update"; id: string; task: Partial<AgentTask> }
+  | { action: "delete"; id: string }
+  | { action: "enable"; id: string; enabled: boolean }
+  | { action: "runNow"; id: string }
+  | { action: "listRuns"; taskId: string; limit?: number }
+  | { action: "clearRuns"; taskId: string };
+
+// Sandbox -> Service Worker 的 conversation API 请求
+export type ConversationApiRequest =
+  | { action: "create"; options: ConversationCreateOptions; scriptUuid: string }
+  | { action: "get"; id: string; scriptUuid: string }
+  | {
+      action: "chat";
+      conversationId: string;
+      message: MessageContent;
+      tools?: ToolDefinition[];
+      scriptUuid: string;
+      // ephemeral 会话专用字段
+      ephemeral?: boolean;
+      messages?: Array<{ role: MessageRole; content: MessageContent; toolCallId?: string; toolCalls?: ToolCall[] }>;
+      system?: string;
+      modelId?: string;
+    }
+  | { action: "getMessages"; conversationId: string; scriptUuid: string }
+  | { action: "save"; conversationId: string; scriptUuid: string }
+  | { action: "clearMessages"; conversationId: string; scriptUuid: string };
diff --git a/src/app/service/content/gm_api/cat_agent.test.ts b/src/app/service/content/gm_api/cat_agent.test.ts
new file mode 100644
index 000000000..eda2e57f8
--- /dev/null
+++ b/src/app/service/content/gm_api/cat_agent.test.ts
@@ -0,0 +1,517 @@
+import { describe, expect, it, vi } from "vitest";
+import { ConversationInstance } from "./cat_agent";
+import type { Conversation, StreamChunk } from "@App/app/service/agent/types";
+import type { MessageConnect } from "@Packages/message/types";
+
+function mockConversation(overrides?: Partial<Conversation>): Conversation {
+  return {
+    id: "test-conv-id",
+    title: "Test",
+    modelId: "gpt-4",
+    createtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+// 创建模拟的 MessageConnect，模拟 LLM 正常回复
+function mockConnect(): MessageConnect {
+  const conn: MessageConnect = {
+    onMessage(cb: (msg: any) => void) {
+      setTimeout(() => {
+        cb({ action: "event", data: { type: "content_delta", delta: "LLM reply" } });
+        cb({ action: "event", data: { type: "done", usage: { inputTokens: 10, outputTokens: 5 } } });
+      }, 10);
+    },
+    onDisconnect() {},
+    sendMessage() {},
+    disconnect() {},
+  };
+  return conn;
+}
+
+function createInstance(commands?: Record<string, (args: string, conv: any) => Promise<string | void>>) {
+  const gmSendMessage = vi.fn().mockResolvedValue(undefined);
+  const gmConnect = vi.fn().mockResolvedValue(mockConnect());
+
+  const instance = new ConversationInstance(
+    mockConversation(),
+    gmSendMessage,
+    gmConnect,
+    "test-script-uuid",
+    20,
+    undefined, // initialTools
+    commands
+  );
+
+  return { instance, gmSendMessage, gmConnect };
+}
+
+describe("ConversationInstance 命令机制", () => {
+  it("内置 /new 命令清空消息历史", async () => {
+    const { instance, gmSendMessage } = createInstance();
+
+    const result = await instance.chat("/new");
+
+    expect(result.command).toBe(true);
+    expect(result.content).toBe("对话已清空");
+    // 应该调用了 clearMessages
+    expect(gmSendMessage).toHaveBeenCalledWith("CAT_agentConversation", [
+      expect.objectContaining({ action: "clearMessages", conversationId: "test-conv-id" }),
+    ]);
+  });
+
+  it("自定义命令正确拦截并返回结果", async () => {
+    const { instance, gmConnect } = createInstance({
+      "/search": async (args) => {
+        return `搜索结果: ${args}`;
+      },
+    });
+
+    const result = await instance.chat("/search hello world");
+
+    expect(result.command).toBe(true);
+    expect(result.content).toBe("搜索结果: hello world");
+    // 不应建立 LLM 连接
+    expect(gmConnect).not.toHaveBeenCalled();
+  });
+
+  it("未注册的 /xxx 命令正常发送给 LLM", async () => {
+    const { instance, gmConnect } = createInstance();
+
+    const result = await instance.chat("/unknown command");
+
+    expect(result.command).toBeUndefined();
+    expect(result.content).toBe("LLM reply");
+    // 应该建立了 LLM 连接
+    expect(gmConnect).toHaveBeenCalled();
+  });
+
+  it("普通消息正常发送给 LLM", async () => {
+    const { instance, gmConnect } = createInstance();
+
+    const result = await instance.chat("你好");
+
+    expect(result.command).toBeUndefined();
+    expect(result.content).toBe("LLM reply");
+    expect(gmConnect).toHaveBeenCalled();
+  });
+
+  it("chatStream 命令拦截返回正确的 chunk 序列", async () => {
+    const { instance, gmConnect } = createInstance({
+      "/test": async () => "测试结果",
+    });
+
+    const stream = await instance.chatStream("/test");
+    const chunks: StreamChunk[] = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0].type).toBe("done");
+    expect(chunks[0].content).toBe("测试结果");
+    expect(chunks[0].command).toBe(true);
+    // 不应建立 LLM 连接
+    expect(gmConnect).not.toHaveBeenCalled();
+  });
+
+  it("脚本覆盖内置 /new 命令", async () => {
+    const customNewHandler = vi.fn().mockResolvedValue("自定义清空逻辑");
+    const { instance, gmSendMessage } = createInstance({
+      "/new": customNewHandler,
+    });
+
+    const result = await instance.chat("/new");
+
+    expect(result.command).toBe(true);
+    expect(result.content).toBe("自定义清空逻辑");
+    expect(customNewHandler).toHaveBeenCalledWith("", instance);
+    // 自定义处理器不会自动调用 clearMessages
+    expect(gmSendMessage).not.toHaveBeenCalled();
+  });
+
+  it("命令处理器返回 void 时 content 为空字符串", async () => {
+    const { instance } = createInstance({
+      "/silent": async () => {
+        // 不返回值
+      },
+    });
+
+    const result = await instance.chat("/silent");
+
+    expect(result.command).toBe(true);
+    expect(result.content).toBe("");
+  });
+
+  it("命令参数正确传递", async () => {
+    const handler = vi.fn().mockResolvedValue("ok");
+    const { instance } = createInstance({
+      "/cmd": handler,
+    });
+
+    await instance.chat("/cmd  arg1 arg2  ");
+
+    expect(handler).toHaveBeenCalledWith("arg1 arg2", instance);
+  });
+
+  it("无参数命令正确解析", async () => {
+    const handler = vi.fn().mockResolvedValue("ok");
+    const { instance } = createInstance({
+      "/reset": handler,
+    });
+
+    await instance.chat("/reset");
+
+    expect(handler).toHaveBeenCalledWith("", instance);
+  });
+});
+
+// ---- Ephemeral 会话测试 ----
+
+function createEphemeralInstance(options?: {
+  system?: string;
+  tools?: Array<{
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+  }>;
+}) {
+  const gmSendMessage = vi.fn().mockResolvedValue(undefined);
+  const gmConnect = vi.fn().mockResolvedValue(mockConnect());
+
+  const instance = new ConversationInstance(
+    mockConversation({ modelId: "test-model" }),
+    gmSendMessage,
+    gmConnect,
+    "test-script-uuid",
+    20,
+    options?.tools,
+    undefined, // commands
+    true, // ephemeral
+    options?.system
+  );
+
+  return { instance, gmSendMessage, gmConnect };
+}
+
+describe("ConversationInstance ephemeral 模式", () => {
+  it("chat 时传递 ephemeral 参数给 SW", async () => {
+    const { instance, gmConnect } = createEphemeralInstance({ system: "你是助手" });
+
+    await instance.chat("你好");
+
+    expect(gmConnect).toHaveBeenCalledTimes(1);
+    const connectParams = gmConnect.mock.calls[0][1][0];
+    expect(connectParams.ephemeral).toBe(true);
+    expect(connectParams.system).toBe("你是助手");
+    expect(connectParams.modelId).toBe("test-model");
+    // messages 应包含 user message
+    expect(connectParams.messages).toEqual(expect.arrayContaining([{ role: "user", content: "你好" }]));
+  });
+
+  it("chat 后 assistant 消息追加到内存历史", async () => {
+    const { instance } = createEphemeralInstance();
+
+    await instance.chat("你好");
+
+    const messages = await instance.getMessages();
+    // 应有 user + assistant
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+    expect(messages[0].role).toBe("user");
+    expect(messages[0].content).toBe("你好");
+    // 最后一条应是 assistant
+    const lastMsg = messages[messages.length - 1];
+    expect(lastMsg.role).toBe("assistant");
+    expect(lastMsg.content).toBe("LLM reply");
+  });
+
+  it("多轮对话正确累积消息历史", async () => {
+    const { instance, gmConnect } = createEphemeralInstance();
+
+    await instance.chat("第一条");
+    await instance.chat("第二条");
+
+    // 第二次 connect 时 messages 应包含前一轮的历史
+    const secondCallParams = gmConnect.mock.calls[1][1][0];
+    const msgs = secondCallParams.messages;
+    // 包含：user("第一条") + assistant("LLM reply") + assistant("LLM reply")(final) + user("第二条")
+    expect(msgs.length).toBeGreaterThanOrEqual(3);
+    expect(msgs[0]).toEqual({ role: "user", content: "第一条" });
+    // 最后一条在 messages 数组中是 user("第二条")，因为 user message 在 connect 前追加
+    // assistant 回复在 processChat 之后才追加，所以第二次 connect 时的 messages 最后一条是 user
+    const userMsgs = msgs.filter((m: any) => m.role === "user");
+    expect(userMsgs).toHaveLength(2);
+    expect(userMsgs[0].content).toBe("第一条");
+    expect(userMsgs[1].content).toBe("第二条");
+    // 应有第一轮的 assistant 回复
+    const assistantMsgs = msgs.filter((m: any) => m.role === "assistant");
+    expect(assistantMsgs.length).toBeGreaterThanOrEqual(1);
+    expect(assistantMsgs[0].content).toBe("LLM reply");
+  });
+
+  it("getMessages 返回内存历史（不调用 SW）", async () => {
+    const { instance, gmSendMessage } = createEphemeralInstance();
+
+    await instance.chat("测试");
+
+    const messages = await instance.getMessages();
+    // 不应调用 SW 的 getMessages
+    expect(gmSendMessage).not.toHaveBeenCalledWith(
+      "CAT_agentConversation",
+      expect.arrayContaining([expect.objectContaining({ action: "getMessages" })])
+    );
+    // 消息应包含 conversationId 和 id
+    expect(messages[0].conversationId).toBe("test-conv-id");
+    expect(messages[0].id).toMatch(/^ephemeral-/);
+  });
+
+  it("clear 清空内存历史（不调用 SW）", async () => {
+    const { instance, gmSendMessage } = createEphemeralInstance();
+
+    await instance.chat("测试");
+    expect((await instance.getMessages()).length).toBeGreaterThan(0);
+
+    await instance.clear();
+
+    const messages = await instance.getMessages();
+    expect(messages).toHaveLength(0);
+    // 不应调用 SW 的 clearMessages
+    expect(gmSendMessage).not.toHaveBeenCalledWith(
+      "CAT_agentConversation",
+      expect.arrayContaining([expect.objectContaining({ action: "clearMessages" })])
+    );
+  });
+
+  it("chatStream ephemeral 传递正确参数", async () => {
+    const { instance, gmConnect } = createEphemeralInstance({ system: "系统提示" });
+
+    const stream = await instance.chatStream("流式测试");
+    const chunks: StreamChunk[] = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    expect(gmConnect).toHaveBeenCalledTimes(1);
+    const connectParams = gmConnect.mock.calls[0][1][0];
+    expect(connectParams.ephemeral).toBe(true);
+    expect(connectParams.system).toBe("系统提示");
+    expect(connectParams.messages).toEqual(expect.arrayContaining([{ role: "user", content: "流式测试" }]));
+
+    // 流应正常完成
+    expect(chunks.some((c) => c.type === "done")).toBe(true);
+  });
+
+  it("chatStream ephemeral 收集 assistant 消息到内存历史", async () => {
+    const { instance } = createEphemeralInstance();
+
+    const stream = await instance.chatStream("你好");
+    // 消费完 stream
+    for await (const _chunk of stream) {
+      // drain
+    }
+
+    const messages = await instance.getMessages();
+    expect(messages.length).toBeGreaterThanOrEqual(2);
+    expect(messages[0].role).toBe("user");
+    const lastMsg = messages[messages.length - 1];
+    expect(lastMsg.role).toBe("assistant");
+    expect(lastMsg.content).toBe("LLM reply");
+  });
+
+  it("ephemeral 模式下 /new 命令清空内存历史", async () => {
+    const { instance, gmSendMessage } = createEphemeralInstance();
+
+    await instance.chat("消息1");
+    expect((await instance.getMessages()).length).toBeGreaterThan(0);
+
+    const result = await instance.chat("/new");
+    expect(result.command).toBe(true);
+
+    const messages = await instance.getMessages();
+    expect(messages).toHaveLength(0);
+    // ephemeral 的 clear 不调用 SW
+    expect(gmSendMessage).not.toHaveBeenCalled();
+  });
+
+  it("ephemeral 模式带自定义工具时传递 tools", async () => {
+    const handler = vi.fn().mockResolvedValue({ result: "ok" });
+    const { instance, gmConnect } = createEphemeralInstance({
+      tools: [
+        {
+          name: "my_tool",
+          description: "自定义工具",
+          parameters: { type: "object", properties: {} },
+          handler,
+        },
+      ],
+    });
+
+    await instance.chat("使用工具");
+
+    const connectParams = gmConnect.mock.calls[0][1][0];
+    expect(connectParams.tools).toBeDefined();
+    expect(connectParams.tools).toHaveLength(1);
+    expect(connectParams.tools[0].name).toBe("my_tool");
+  });
+});
+
+// ---- errorCode 透传测试 ----
+
+// 创建发送指定事件序列的 mock 连接
+function mockConnectWithEvents(events: any[]): MessageConnect {
+  return {
+    onMessage(cb: (msg: any) => void) {
+      let i = 0;
+      const send = () => {
+        if (i < events.length) {
+          cb({ action: "event", data: events[i++] });
+          setTimeout(send, 0);
+        }
+      };
+      setTimeout(send, 0);
+    },
+    onDisconnect() {},
+    sendMessage() {},
+    disconnect() {},
+  };
+}
+
+describe("errorCode 透传：chat()", () => {
+  it("error event 带 errorCode 时，reject 的 Error 应有对应 errorCode", async () => {
+    const errorEvent = { type: "error", message: "Rate limit exceeded", errorCode: "rate_limit" };
+    const gmConnect = vi.fn().mockResolvedValue(mockConnectWithEvents([errorEvent]));
+
+    const instance = new ConversationInstance(
+      mockConversation(),
+      vi.fn().mockResolvedValue(undefined),
+      gmConnect,
+      "uuid",
+      20
+    );
+
+    const err = await instance.chat("你好").catch((e) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toBe("Rate limit exceeded");
+    expect((err as any).errorCode).toBe("rate_limit");
+  });
+
+  it("error event 无 errorCode 时，errorCode 应为 undefined", async () => {
+    const errorEvent = { type: "error", message: "Unknown error" };
+    const gmConnect = vi.fn().mockResolvedValue(mockConnectWithEvents([errorEvent]));
+
+    const instance = new ConversationInstance(
+      mockConversation(),
+      vi.fn().mockResolvedValue(undefined),
+      gmConnect,
+      "uuid",
+      20
+    );
+
+    const err = await instance.chat("你好").catch((e) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as any).errorCode).toBeUndefined();
+  });
+
+  it("各种 errorCode 值均能正确透传", async () => {
+    const codes = ["rate_limit", "auth", "tool_timeout", "max_iterations", "api_error"];
+
+    for (const code of codes) {
+      const gmConnect = vi
+        .fn()
+        .mockResolvedValue(mockConnectWithEvents([{ type: "error", message: "error", errorCode: code }]));
+
+      const instance = new ConversationInstance(
+        mockConversation(),
+        vi.fn().mockResolvedValue(undefined),
+        gmConnect,
+        "uuid",
+        20
+      );
+
+      const err = await instance.chat("test").catch((e) => e);
+      expect((err as any).errorCode).toBe(code);
+    }
+  });
+});
+
+describe("errorCode 透传：chatStream()", () => {
+  // processStream 在收到 error 事件后：将 error chunk 推入队列并设置 done=true。
+  // 迭代器先 yield error chunk（done: false），然后返回 { done: true }（正常结束）。
+  // 因此不会 throw，只需检查 chunk 中的 errorCode 即可。
+
+  it("error event 带 errorCode 时，error chunk 应有对应 errorCode", async () => {
+    const errorEvent = { type: "error", message: "Tool timed out", errorCode: "tool_timeout" };
+    const gmConnect = vi.fn().mockResolvedValue(mockConnectWithEvents([errorEvent]));
+
+    const instance = new ConversationInstance(
+      mockConversation(),
+      vi.fn().mockResolvedValue(undefined),
+      gmConnect,
+      "uuid",
+      20
+    );
+
+    const stream = await instance.chatStream("你好");
+    const chunks: StreamChunk[] = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const errorChunk = chunks.find((c) => c.type === "error");
+    expect(errorChunk).toBeDefined();
+    expect(errorChunk!.error).toBe("Tool timed out");
+    expect((errorChunk as any).errorCode).toBe("tool_timeout");
+  });
+
+  it("error event 无 errorCode 时，chunk.errorCode 应为 undefined", async () => {
+    const errorEvent = { type: "error", message: "Some error" };
+    const gmConnect = vi.fn().mockResolvedValue(mockConnectWithEvents([errorEvent]));
+
+    const instance = new ConversationInstance(
+      mockConversation(),
+      vi.fn().mockResolvedValue(undefined),
+      gmConnect,
+      "uuid",
+      20
+    );
+
+    const stream = await instance.chatStream("你好");
+    const chunks: StreamChunk[] = [];
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const errorChunk = chunks.find((c) => c.type === "error");
+    expect(errorChunk).toBeDefined();
+    expect((errorChunk as any).errorCode).toBeUndefined();
+  });
+
+  it("各种 errorCode 均能正确在 chunk 中透传", async () => {
+    const codes = ["rate_limit", "auth", "tool_timeout", "max_iterations", "api_error"];
+
+    for (const code of codes) {
+      const gmConnect = vi
+        .fn()
+        .mockResolvedValue(mockConnectWithEvents([{ type: "error", message: "err", errorCode: code }]));
+
+      const instance = new ConversationInstance(
+        mockConversation(),
+        vi.fn().mockResolvedValue(undefined),
+        gmConnect,
+        "uuid",
+        20
+      );
+
+      const stream = await instance.chatStream("test");
+      const chunks: StreamChunk[] = [];
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+
+      const errorChunk = chunks.find((c) => c.type === "error");
+      expect((errorChunk as any).errorCode).toBe(code);
+    }
+  });
+});
diff --git a/src/app/service/content/gm_api/cat_agent.ts b/src/app/service/content/gm_api/cat_agent.ts
new file mode 100644
index 000000000..0035c0fdd
--- /dev/null
+++ b/src/app/service/content/gm_api/cat_agent.ts
@@ -0,0 +1,581 @@
+import GMContext from "./gm_context";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+import type { MessageConnect } from "@Packages/message/types";
+import type {
+  ChatReply,
+  ChatStreamEvent,
+  CommandHandler,
+  Conversation,
+  ConversationApiRequest,
+  ConversationCreateOptions,
+  ChatOptions,
+  StreamChunk,
+  ToolCall,
+  ToolDefinition,
+  ChatMessage,
+  MessageRole,
+  MessageContent,
+} from "@App/app/service/agent/types";
+import { getTextContent } from "@App/app/service/agent/content_utils";
+
+// 对话实例，暴露给用户脚本
+// 导出供测试使用
+export class ConversationInstance {
+  private toolHandlers: Map<string, (args: Record<string, unknown>) => Promise<unknown>> = new Map();
+  private toolDefs: ToolDefinition[] = [];
+  private commandHandlers: Map<string, CommandHandler> = new Map();
+  private ephemeral: boolean;
+  private cache?: boolean;
+  private systemPrompt?: string;
+  private messageHistory: Array<{
+    role: MessageRole;
+    content: MessageContent;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+  }> = [];
+
+  constructor(
+    private conv: Conversation,
+    private gmSendMessage: (api: string, params: any[]) => Promise<any>,
+    private gmConnect: (api: string, params: any[]) => Promise<MessageConnect>,
+    private scriptUuid: string,
+    private maxIterations: number,
+    initialTools?: ConversationCreateOptions["tools"],
+    commands?: Record<string, CommandHandler>,
+    ephemeral?: boolean,
+    system?: string,
+    cache?: boolean
+  ) {
+    this.ephemeral = ephemeral || false;
+    this.cache = cache;
+    this.systemPrompt = system;
+    if (initialTools) {
+      for (const tool of initialTools) {
+        this.toolHandlers.set(tool.name, tool.handler);
+        this.toolDefs.push({ name: tool.name, description: tool.description, parameters: tool.parameters });
+      }
+    }
+
+    // 注册内置 /new 命令
+    this.commandHandlers.set("/new", async () => {
+      await this.clear();
+      return "对话已清空";
+    });
+
+    // 用户传入的 commands 覆盖内置命令
+    if (commands) {
+      for (const [name, handler] of Object.entries(commands)) {
+        this.commandHandlers.set(name, handler);
+      }
+    }
+  }
+
+  get id() {
+    return this.conv.id;
+  }
+
+  get title() {
+    return this.conv.title;
+  }
+
+  get modelId() {
+    return this.conv.modelId;
+  }
+
+  // 发送消息并获取回复（内置 tool calling 循环）
+  async chat(content: MessageContent, options?: ChatOptions): Promise<ChatReply> {
+    // 命令拦截（仅纯文本消息支持命令）
+    const textContent = getTextContent(content);
+    const cmdResult = await this.tryExecuteCommand(textContent);
+    if (cmdResult !== undefined) return cmdResult;
+
+    const { toolDefs, handlers } = this.mergeTools(options?.tools);
+
+    // ephemeral 模式：追加 user message 到内存历史
+    if (this.ephemeral) {
+      this.messageHistory.push({ role: "user", content });
+    }
+
+    // 通过 GM API connect 建立流式连接
+    const connectParams: Record<string, unknown> = {
+      conversationId: this.conv.id,
+      message: content,
+      tools: toolDefs.length > 0 ? toolDefs : undefined,
+      maxIterations: this.maxIterations,
+      scriptUuid: this.scriptUuid,
+    };
+
+    if (this.cache !== undefined) {
+      connectParams.cache = this.cache;
+    }
+    if (this.ephemeral) {
+      connectParams.ephemeral = true;
+      connectParams.messages = this.messageHistory;
+      connectParams.system = this.systemPrompt;
+      connectParams.modelId = this.conv.modelId;
+    }
+
+    const conn = await this.gmConnect("CAT_agentConversationChat", [connectParams]);
+
+    const reply = await this.processChat(conn, handlers);
+
+    // ephemeral 模式：收集 assistant 响应到内存历史
+    if (this.ephemeral) {
+      if (reply.toolCalls && reply.toolCalls.length > 0) {
+        this.messageHistory.push({ role: "assistant", content: reply.content, toolCalls: reply.toolCalls });
+        for (const tc of reply.toolCalls) {
+          if (tc.result !== undefined) {
+            this.messageHistory.push({ role: "tool", content: tc.result, toolCallId: tc.id });
+          }
+        }
+      }
+      this.messageHistory.push({ role: "assistant", content: reply.content });
+    }
+
+    return reply;
+  }
+
+  // 流式发送消息
+  async chatStream(content: MessageContent, options?: ChatOptions): Promise<AsyncIterable<StreamChunk>> {
+    // 命令拦截：返回单个 done chunk（仅纯文本消息支持命令）
+    const textContent = getTextContent(content);
+    const cmdResult = await this.tryExecuteCommand(textContent);
+    if (cmdResult !== undefined) {
+      return {
+        [Symbol.asyncIterator]() {
+          let yielded = false;
+          return {
+            async next(): Promise<IteratorResult<StreamChunk>> {
+              if (!yielded) {
+                yielded = true;
+                return {
+                  value: { type: "done" as const, content: getTextContent(cmdResult.content), command: true },
+                  done: false,
+                };
+              }
+              return { value: undefined as any, done: true };
+            },
+          };
+        },
+      };
+    }
+
+    const { toolDefs, handlers } = this.mergeTools(options?.tools);
+
+    // ephemeral 模式：追加 user message 到内存历史
+    if (this.ephemeral) {
+      this.messageHistory.push({ role: "user", content });
+    }
+
+    const connectParams: Record<string, unknown> = {
+      conversationId: this.conv.id,
+      message: content,
+      tools: toolDefs.length > 0 ? toolDefs : undefined,
+      maxIterations: this.maxIterations,
+      scriptUuid: this.scriptUuid,
+    };
+
+    if (this.cache !== undefined) {
+      connectParams.cache = this.cache;
+    }
+    if (this.ephemeral) {
+      connectParams.ephemeral = true;
+      connectParams.messages = this.messageHistory;
+      connectParams.system = this.systemPrompt;
+      connectParams.modelId = this.conv.modelId;
+    }
+
+    const conn = await this.gmConnect("CAT_agentConversationChat", [connectParams]);
+
+    // ephemeral 模式：包装 stream 以收集 assistant 消息到内存历史
+    if (this.ephemeral) {
+      return this.processStreamEphemeral(conn, handlers);
+    }
+
+    return this.processStream(conn, handlers);
+  }
+
+  // 解析命令："/command args" -> { name, args }
+  private parseCommand(content: string): { name: string; args: string } | null {
+    const trimmed = content.trim();
+    if (!trimmed.startsWith("/")) return null;
+    const spaceIdx = trimmed.indexOf(" ");
+    if (spaceIdx === -1) return { name: trimmed, args: "" };
+    return { name: trimmed.slice(0, spaceIdx), args: trimmed.slice(spaceIdx + 1).trim() };
+  }
+
+  // 尝试执行命令，未注册的命令返回 undefined（正常发送给 LLM）
+  private async tryExecuteCommand(content: string): Promise<ChatReply | undefined> {
+    const parsed = this.parseCommand(content);
+    if (!parsed) return undefined;
+
+    const handler = this.commandHandlers.get(parsed.name);
+    if (!handler) return undefined;
+
+    const result = await handler(parsed.args, this);
+    // 命令结果始终为纯文本 string
+    return { content: (result || "") as string, command: true };
+  }
+
+  // 合并实例级别和调用级别的工具定义
+  private mergeTools(callTools?: ChatOptions["tools"]) {
+    const toolDefs: ToolDefinition[] = [...this.toolDefs];
+    const handlers = new Map(this.toolHandlers);
+
+    if (callTools) {
+      for (const tool of callTools) {
+        // 调用级别的工具覆盖实例级别的同名工具
+        if (!handlers.has(tool.name)) {
+          toolDefs.push({ name: tool.name, description: tool.description, parameters: tool.parameters });
+        }
+        handlers.set(tool.name, tool.handler);
+      }
+    }
+
+    return { toolDefs, handlers };
+  }
+
+  // 获取对话历史
+  async getMessages(): Promise<ChatMessage[]> {
+    if (this.ephemeral) {
+      // ephemeral 模式：从内存历史转换为 ChatMessage 格式
+      return this.messageHistory.map((msg, idx) => ({
+        id: `ephemeral-${idx}`,
+        conversationId: this.conv.id,
+        role: msg.role,
+        content: msg.content,
+        toolCallId: msg.toolCallId,
+        toolCalls: msg.toolCalls,
+        createtime: Date.now(),
+      }));
+    }
+    const messages = await this.gmSendMessage("CAT_agentConversation", [
+      {
+        action: "getMessages",
+        conversationId: this.conv.id,
+        scriptUuid: this.scriptUuid,
+      } as ConversationApiRequest,
+    ]);
+    return messages || [];
+  }
+
+  // 清空对话消息历史
+  async clear(): Promise<void> {
+    if (this.ephemeral) {
+      this.messageHistory = [];
+      return;
+    }
+    await this.gmSendMessage("CAT_agentConversation", [
+      {
+        action: "clearMessages",
+        conversationId: this.conv.id,
+        scriptUuid: this.scriptUuid,
+      } as ConversationApiRequest,
+    ]);
+  }
+
+  // 持久化对话
+  async save(): Promise<void> {
+    await this.gmSendMessage("CAT_agentConversation", [
+      {
+        action: "save",
+        conversationId: this.conv.id,
+        scriptUuid: this.scriptUuid,
+      } as ConversationApiRequest,
+    ]);
+  }
+
+  // 处理非流式 chat 的响应
+  private processChat(
+    conn: MessageConnect,
+    handlers: Map<string, (args: Record<string, unknown>) => Promise<unknown>>
+  ): Promise<ChatReply> {
+    return new Promise((resolve, reject) => {
+      let content = "";
+      let thinking = "";
+      const toolCalls: ToolCall[] = [];
+      let currentToolCall: ToolCall | null = null;
+      let usage: { inputTokens: number; outputTokens: number } | undefined;
+
+      conn.onMessage(async (msg: any) => {
+        if (msg.action === "executeTools") {
+          // Service Worker 请求执行 tools
+          const requestedToolCalls: ToolCall[] = msg.data;
+          const results = await this.executeTools(requestedToolCalls, handlers);
+          conn.sendMessage({ action: "toolResults", data: results });
+          return;
+        }
+
+        if (msg.action !== "event") return;
+        const event: ChatStreamEvent = msg.data;
+
+        switch (event.type) {
+          case "content_delta":
+            content += event.delta;
+            break;
+          case "thinking_delta":
+            thinking += event.delta;
+            break;
+          case "tool_call_start":
+            if (currentToolCall) toolCalls.push(currentToolCall);
+            currentToolCall = { ...event.toolCall, arguments: event.toolCall.arguments || "" };
+            break;
+          case "tool_call_delta":
+            if (currentToolCall) currentToolCall.arguments += event.delta;
+            break;
+          case "done":
+            if (currentToolCall) {
+              toolCalls.push(currentToolCall);
+              currentToolCall = null;
+            }
+            if (event.usage) usage = event.usage;
+            resolve({
+              content,
+              thinking: thinking || undefined,
+              toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+              usage,
+            });
+            break;
+          case "error":
+            reject(Object.assign(new Error(event.message), { errorCode: event.errorCode }));
+            break;
+        }
+      });
+
+      conn.onDisconnect(() => {
+        reject(new Error("Connection disconnected"));
+      });
+    });
+  }
+
+  // 处理流式 chat 的响应
+  private processStream(
+    conn: MessageConnect,
+    handlers: Map<string, (args: Record<string, unknown>) => Promise<unknown>>
+  ): AsyncIterable<StreamChunk> {
+    const chunks: StreamChunk[] = [];
+    let resolve: (() => void) | null = null;
+    let done = false;
+    let error: Error | null = null;
+
+    conn.onMessage(async (msg: any) => {
+      if (msg.action === "executeTools") {
+        const requestedToolCalls: ToolCall[] = msg.data;
+        const results = await this.executeTools(requestedToolCalls, handlers);
+        conn.sendMessage({ action: "toolResults", data: results });
+        return;
+      }
+
+      if (msg.action !== "event") return;
+      const event: ChatStreamEvent = msg.data;
+
+      let chunk: StreamChunk | null = null;
+      switch (event.type) {
+        case "content_delta":
+          chunk = { type: "content_delta", content: event.delta };
+          break;
+        case "thinking_delta":
+          chunk = { type: "thinking_delta", content: event.delta };
+          break;
+        case "tool_call_start":
+          chunk = { type: "tool_call", toolCall: { ...event.toolCall, arguments: "" } };
+          break;
+        case "done":
+          chunk = { type: "done", usage: event.usage };
+          done = true;
+          break;
+        case "error":
+          chunk = { type: "error", error: event.message, errorCode: event.errorCode };
+          error = Object.assign(new Error(event.message), { errorCode: event.errorCode });
+          done = true;
+          break;
+      }
+
+      if (chunk) {
+        chunks.push(chunk);
+        resolve?.();
+      }
+    });
+
+    conn.onDisconnect(() => {
+      done = true;
+      error = error || new Error("Connection disconnected");
+      resolve?.();
+    });
+
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          async next(): Promise<IteratorResult<StreamChunk>> {
+            while (chunks.length === 0 && !done) {
+              await new Promise<void>((r) => {
+                resolve = r;
+              });
+            }
+
+            if (chunks.length > 0) {
+              return { value: chunks.shift()!, done: false };
+            }
+
+            if (error && !done) throw error;
+            return { value: undefined as any, done: true };
+          },
+        };
+      },
+    };
+  }
+
+  // 处理 ephemeral 流式 chat 的响应（收集 assistant 消息到内存历史）
+  private processStreamEphemeral(
+    conn: MessageConnect,
+    handlers: Map<string, (args: Record<string, unknown>) => Promise<unknown>>
+  ): AsyncIterable<StreamChunk> {
+    const inner = this.processStream(conn, handlers);
+    const messageHistory = this.messageHistory;
+    let content = "";
+    const toolCalls: ToolCall[] = [];
+
+    return {
+      [Symbol.asyncIterator]() {
+        const iter = inner[Symbol.asyncIterator]();
+        return {
+          async next(): Promise<IteratorResult<StreamChunk>> {
+            const result = await iter.next();
+            if (result.done) {
+              // 流结束时，追加 assistant 消息到历史
+              if (content || toolCalls.length > 0) {
+                messageHistory.push({
+                  role: "assistant",
+                  content,
+                  toolCalls: toolCalls.length > 0 ? [...toolCalls] : undefined,
+                });
+              }
+              return result;
+            }
+
+            const chunk = result.value;
+            switch (chunk.type) {
+              case "content_delta":
+                content += chunk.content || "";
+                break;
+              case "tool_call":
+                if (chunk.toolCall) {
+                  toolCalls.push(chunk.toolCall);
+                }
+                break;
+            }
+            return result;
+          },
+        };
+      },
+    };
+  }
+
+  // 执行用户定义的 tool handlers
+  private async executeTools(
+    toolCalls: ToolCall[],
+    handlers: Map<string, (args: Record<string, unknown>) => Promise<unknown>>
+  ): Promise<Array<{ id: string; result: string }>> {
+    const results: Array<{ id: string; result: string }> = [];
+
+    for (const tc of toolCalls) {
+      const handler = handlers.get(tc.name);
+      if (!handler) {
+        results.push({ id: tc.id, result: JSON.stringify({ error: `Tool "${tc.name}" not found` }) });
+        continue;
+      }
+
+      try {
+        let args: Record<string, unknown> = {};
+        if (tc.arguments) {
+          args = JSON.parse(tc.arguments);
+        }
+        const result = await handler(args);
+        results.push({ id: tc.id, result: typeof result === "string" ? result : JSON.stringify(result) });
+      } catch (e: any) {
+        results.push({ id: tc.id, result: JSON.stringify({ error: e.message || "Tool execution failed" }) });
+      }
+    }
+
+    return results;
+  }
+}
+
+// 运行时 this 是 GM_Base 实例，定义其实际拥有的字段类型
+interface GMBaseContext {
+  sendMessage: (api: string, params: unknown[]) => Promise<unknown>;
+  connect: (api: string, params: unknown[]) => Promise<MessageConnect>;
+  scriptRes?: { uuid: string };
+}
+
+// 构建 ConversationInstance，独立函数避免 this 绑定问题
+// （装饰器方法运行时 this 是 GM_Base 实例，不是 CATAgentApi）
+function buildInstance(
+  ctx: GMBaseContext,
+  conv: Conversation,
+  options?: ConversationCreateOptions
+): ConversationInstance {
+  return new ConversationInstance(
+    conv,
+    ctx.sendMessage.bind(ctx),
+    ctx.connect.bind(ctx),
+    ctx.scriptRes?.uuid || "",
+    options?.maxIterations || 20,
+    options?.tools,
+    options?.commands,
+    options?.ephemeral,
+    options?.system,
+    options?.cache
+  );
+}
+
+// CAT.agent.conversation API 对象，注入到脚本上下文
+// 使用 @GMContext.API 装饰器注册到 "CAT.agent.conversation" grant
+export default class CATAgentApi {
+  // 标记为 protected 的内部状态（由 GM_Base 绑定）
+  @GMContext.protected()
+  protected sendMessage!: (api: string, params: any[]) => Promise<any>;
+
+  @GMContext.protected()
+  protected connect!: (api: string, params: any[]) => Promise<MessageConnect>;
+
+  @GMContext.protected()
+  protected scriptRes?: any;
+
+  // CAT.agent.conversation.create()
+  @GMContext.API({ follow: "CAT.agent.conversation" })
+  public "CAT.agent.conversation.create"(options: ConversationCreateOptions = {}): Promise<ConversationInstance> {
+    return (async () => {
+      if (options.ephemeral) {
+        // ephemeral 模式：不发请求到 SW，直接在脚本端构造
+        const conv: Conversation = {
+          id: options.id || uuidv4(),
+          title: "New Chat",
+          modelId: options.model || "",
+          system: options.system,
+          createtime: Date.now(),
+          updatetime: Date.now(),
+        };
+        return buildInstance(this as unknown as GMBaseContext, conv, options);
+      }
+
+      const { tools: _tools, ephemeral: _ephemeral, ...serverOptions } = options;
+      const conv = (await this.sendMessage("CAT_agentConversation", [
+        { action: "create", options: serverOptions, scriptUuid: this.scriptRes?.uuid || "" } as ConversationApiRequest,
+      ])) as Conversation;
+      return buildInstance(this as unknown as GMBaseContext, conv, options);
+    })();
+  }
+
+  // CAT.agent.conversation.get()
+  @GMContext.API({ follow: "CAT.agent.conversation" })
+  public "CAT.agent.conversation.get"(id: string): Promise<ConversationInstance | null> {
+    return (async () => {
+      const conv = (await this.sendMessage("CAT_agentConversation", [
+        { action: "get", id, scriptUuid: this.scriptRes?.uuid || "" } as ConversationApiRequest,
+      ])) as Conversation | null;
+      if (!conv) return null;
+      return buildInstance(this as unknown as GMBaseContext, conv);
+    })();
+  }
+}
diff --git a/src/app/service/content/gm_api/cat_agent_dom.ts b/src/app/service/content/gm_api/cat_agent_dom.ts
new file mode 100644
index 000000000..d3dd6f961
--- /dev/null
+++ b/src/app/service/content/gm_api/cat_agent_dom.ts
@@ -0,0 +1,133 @@
+// CAT.agent.dom API，注入到脚本上下文
+// 使用 @GMContext.API 装饰器注册到 "CAT.agent.dom" grant
+
+import GMContext from "./gm_context";
+import type {
+  DomApiRequest,
+  ReadPageOptions,
+  ScreenshotOptions,
+  DomActionOptions,
+  NavigateOptions,
+  ScrollDirection,
+  ScrollOptions,
+  WaitForOptions,
+  ExecuteScriptOptions,
+  TabInfo,
+  NavigateResult,
+  PageContent,
+  ActionResult,
+  ScrollResult,
+  WaitForResult,
+  MonitorResult,
+  MonitorStatus,
+} from "@App/app/service/agent/types";
+
+// 运行时 this 是 GM_Base 实例
+interface GMBaseContext {
+  sendMessage: <T = unknown>(api: string, params: unknown[]) => Promise<T>;
+  scriptRes?: { uuid: string };
+}
+
+export default class CATAgentDomApi {
+  @GMContext.protected()
+  protected sendMessage!: (api: string, params: any[]) => Promise<any>;
+
+  @GMContext.protected()
+  protected scriptRes?: any;
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.listTabs"(): Promise<TabInfo[]> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "listTabs", scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.navigate"(url: string, options?: NavigateOptions): Promise<NavigateResult> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "navigate", url, options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.readPage"(options?: ReadPageOptions): Promise<PageContent> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "readPage", options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.screenshot"(options?: ScreenshotOptions): Promise<string> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "screenshot", options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.click"(selector: string, options?: DomActionOptions): Promise<ActionResult> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "click", selector, options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.fill"(selector: string, value: string, options?: DomActionOptions): Promise<ActionResult> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "fill", selector, value, options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.scroll"(direction: ScrollDirection, options?: ScrollOptions): Promise<ScrollResult> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "scroll", direction, options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.waitFor"(selector: string, options?: WaitForOptions): Promise<WaitForResult> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "waitFor", selector, options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.executeScript"(code: string, options?: ExecuteScriptOptions): Promise<unknown> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "executeScript", code, options, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.startMonitor"(tabId: number): Promise<void> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "startMonitor", tabId, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.stopMonitor"(tabId: number): Promise<MonitorResult> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "stopMonitor", tabId, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+
+  @GMContext.API({ follow: "CAT.agent.dom" })
+  public "CAT.agent.dom.peekMonitor"(tabId: number): Promise<MonitorStatus> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentDom", [
+      { action: "peekMonitor", tabId, scriptUuid: ctx.scriptRes?.uuid || "" } as DomApiRequest,
+    ]);
+  }
+}
diff --git a/src/app/service/content/gm_api/cat_agent_skills.ts b/src/app/service/content/gm_api/cat_agent_skills.ts
new file mode 100644
index 000000000..a07e78eec
--- /dev/null
+++ b/src/app/service/content/gm_api/cat_agent_skills.ts
@@ -0,0 +1,63 @@
+import type { SkillApiRequest, SkillRecord, SkillSummary } from "@App/app/service/agent/types";
+import GMContext from "./gm_context";
+
+// 运行时 this 是 GM_Base 实例
+interface GMBaseContext {
+  sendMessage: (api: string, params: SkillApiRequest[]) => Promise<SkillSummary[] | SkillRecord | null | boolean>;
+  scriptRes?: { uuid: string };
+}
+
+// CAT.agent.skills API，注入到脚本上下文
+// 使用 @GMContext.API 装饰器注册到 "CAT.agent.skills" grant
+export default class CATAgentSkillsApi {
+  @GMContext.protected()
+  protected sendMessage!: (
+    api: string,
+    params: SkillApiRequest[]
+  ) => Promise<SkillSummary[] | SkillRecord | null | boolean>;
+
+  @GMContext.protected()
+  protected scriptRes?: { uuid: string };
+
+  @GMContext.API({ follow: "CAT.agent.skills" })
+  public "CAT.agent.skills.list"(): Promise<SkillSummary[]> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentSkills", [
+      { action: "list", scriptUuid: ctx.scriptRes?.uuid || "" } as SkillApiRequest,
+    ]) as Promise<SkillSummary[]>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.skills" })
+  public "CAT.agent.skills.get"(name: string): Promise<SkillRecord | null> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentSkills", [
+      { action: "get", name, scriptUuid: ctx.scriptRes?.uuid || "" } as SkillApiRequest,
+    ]) as Promise<SkillRecord | null>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.skills" })
+  public "CAT.agent.skills.install"(
+    skillMd: string,
+    scripts?: Array<{ name: string; code: string }>,
+    references?: Array<{ name: string; content: string }>
+  ): Promise<SkillRecord> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentSkills", [
+      {
+        action: "install",
+        skillMd,
+        scripts,
+        references,
+        scriptUuid: ctx.scriptRes?.uuid || "",
+      } as SkillApiRequest,
+    ]) as Promise<SkillRecord>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.skills" })
+  public "CAT.agent.skills.remove"(name: string): Promise<boolean> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentSkills", [
+      { action: "remove", name, scriptUuid: ctx.scriptRes?.uuid || "" } as SkillApiRequest,
+    ]) as Promise<boolean>;
+  }
+}
diff --git a/src/app/service/content/gm_api/cat_agent_task.ts b/src/app/service/content/gm_api/cat_agent_task.ts
new file mode 100644
index 000000000..9d039f9e0
--- /dev/null
+++ b/src/app/service/content/gm_api/cat_agent_task.ts
@@ -0,0 +1,106 @@
+import GMContext from "./gm_context";
+import type { AgentTask, AgentTaskApiRequest, AgentTaskTrigger } from "@App/app/service/agent/types";
+import type EventEmitter from "eventemitter3";
+
+// 运行时 this 是 GM_Base 实例
+interface GMBaseContext {
+  sendMessage: (api: string, params: unknown[]) => Promise<unknown>;
+  scriptRes?: { uuid: string };
+  EE?: EventEmitter | null;
+}
+
+// 内部 listener 计数器
+let listenerCounter = 0;
+// listener id → { eventName, callback } 映射，供 removeListener 使用
+const listenerMap = new Map<number, { eventName: string; callback: (...args: any[]) => void }>();
+
+// CAT.agent.task API，注入到脚本上下文
+export default class CATAgentTaskApi {
+  @GMContext.protected()
+  protected sendMessage!: (api: string, params: any[]) => Promise<any>;
+
+  @GMContext.protected()
+  protected scriptRes?: any;
+
+  @GMContext.protected()
+  protected EE?: EventEmitter | null;
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.create"(
+    options: Omit<AgentTask, "id" | "createtime" | "updatetime" | "nextruntime" | "sourceScriptUuid">
+  ): Promise<AgentTask> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTask", [
+      {
+        action: "create",
+        task: { ...options, sourceScriptUuid: ctx.scriptRes?.uuid || "" },
+      } as AgentTaskApiRequest,
+    ]) as Promise<AgentTask>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.list"(): Promise<AgentTask[]> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTask", [{ action: "list" } as AgentTaskApiRequest]) as Promise<AgentTask[]>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.get"(id: string): Promise<AgentTask | undefined> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTask", [{ action: "get", id } as AgentTaskApiRequest]) as Promise<
+      AgentTask | undefined
+    >;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.update"(id: string, task: Partial<AgentTask>): Promise<AgentTask> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTask", [
+      { action: "update", id, task } as AgentTaskApiRequest,
+    ]) as Promise<AgentTask>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.remove"(id: string): Promise<boolean> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTask", [{ action: "delete", id } as AgentTaskApiRequest]) as Promise<boolean>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.runNow"(id: string): Promise<void> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTask", [{ action: "runNow", id } as AgentTaskApiRequest]) as Promise<void>;
+  }
+
+  // 监听任务触发事件
+  // 利用 EE.on("agentTask:{taskId}", callback) 注册监听
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.addListener"(taskId: string, callback: (trigger: AgentTaskTrigger) => void): number {
+    const ctx = this as unknown as GMBaseContext;
+    if (!ctx.EE) return 0;
+
+    const listenerId = ++listenerCounter;
+    const eventName = `agentTask:${taskId}`;
+
+    const wrappedCallback = (data: AgentTaskTrigger) => {
+      callback(data);
+    };
+
+    ctx.EE.on(eventName, wrappedCallback);
+    listenerMap.set(listenerId, { eventName, callback: wrappedCallback });
+
+    return listenerId;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.task" })
+  public "CAT.agent.task.removeListener"(listenerId: number): void {
+    const ctx = this as unknown as GMBaseContext;
+    if (!ctx.EE) return;
+
+    const entry = listenerMap.get(listenerId);
+    if (entry) {
+      ctx.EE.off(entry.eventName, entry.callback);
+      listenerMap.delete(listenerId);
+    }
+  }
+}
diff --git a/src/app/service/content/gm_api/cat_agent_tools.ts b/src/app/service/content/gm_api/cat_agent_tools.ts
new file mode 100644
index 000000000..febbebb76
--- /dev/null
+++ b/src/app/service/content/gm_api/cat_agent_tools.ts
@@ -0,0 +1,51 @@
+import GMContext from "./gm_context";
+import type { CATToolApiRequest, CATToolRecord, JsonValue } from "@App/app/service/agent/types";
+import type { CATToolSummary } from "@App/app/repo/cattool_repo";
+
+// 运行时 this 是 GM_Base 实例
+interface GMBaseContext {
+  sendMessage: (api: string, params: unknown[]) => Promise<unknown>;
+  scriptRes?: { uuid: string };
+}
+
+// CAT.agent.tools API，注入到脚本上下文
+// 使用 @GMContext.API 装饰器注册到 "CAT.agent.tools" grant
+export default class CATAgentToolsApi {
+  @GMContext.protected()
+  protected sendMessage!: (api: string, params: unknown[]) => Promise<unknown>;
+
+  @GMContext.protected()
+  protected scriptRes?: { uuid: string };
+
+  @GMContext.API({ follow: "CAT.agent.tools" })
+  public "CAT.agent.tools.install"(code: string): Promise<CATToolRecord> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTools", [
+      { action: "install", code, scriptUuid: ctx.scriptRes?.uuid || "" } as CATToolApiRequest,
+    ]) as Promise<CATToolRecord>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.tools" })
+  public "CAT.agent.tools.remove"(name: string): Promise<boolean> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTools", [
+      { action: "remove", name, scriptUuid: ctx.scriptRes?.uuid || "" } as CATToolApiRequest,
+    ]) as Promise<boolean>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.tools" })
+  public "CAT.agent.tools.list"(): Promise<CATToolSummary[]> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTools", [
+      { action: "list", scriptUuid: ctx.scriptRes?.uuid || "" } as CATToolApiRequest,
+    ]) as Promise<CATToolSummary[]>;
+  }
+
+  @GMContext.API({ follow: "CAT.agent.tools" })
+  public "CAT.agent.tools.call"(name: string, params: Record<string, unknown> = {}): Promise<JsonValue> {
+    const ctx = this as unknown as GMBaseContext;
+    return ctx.sendMessage("CAT_agentTools", [
+      { action: "call", name, params, scriptUuid: ctx.scriptRes?.uuid || "" } as CATToolApiRequest,
+    ]) as Promise<JsonValue>;
+  }
+}
diff --git a/src/app/service/content/gm_api/gm_api.test.ts b/src/app/service/content/gm_api/gm_api.test.ts
index 2a76ed845..8a94e1b66 100644
--- a/src/app/service/content/gm_api/gm_api.test.ts
+++ b/src/app/service/content/gm_api/gm_api.test.ts
@@ -1208,3 +1208,119 @@ return { value1, value2, value3, values1,values2, allValues1, allValues2, value4
     expect(ret).toEqual(123);
   });
 });
+
+describe("@grant CAT.agent.conversation", () => {
+  it("CAT.agent.conversation 应该在沙盒中可访问", async () => {
+    const script = Object.assign({}, scriptRes) as ScriptLoadInfo;
+    script.metadata.grant = ["CAT.agent.conversation", "GM_log"];
+    const exec = new ExecScript(script, {
+      envPrefix: "scripting",
+      message: undefined as any,
+      contentMsg: undefined as any,
+      code: nilFn,
+      envInfo,
+    });
+    script.code = `return {
+      CAT: typeof CAT,
+      create: typeof CAT.agent.conversation.create,
+      get: typeof CAT.agent.conversation.get,
+    }`;
+    exec.scriptFunc = compileScript(compileScriptCode(script));
+    const ret = await exec.exec();
+    expect(ret.CAT).toEqual("object");
+    expect(ret.create).toEqual("function");
+    expect(ret.get).toEqual("function");
+  });
+});
+
+describe("@grant CAT.agent.dom", () => {
+  it("CAT.agent.dom 所有方法应该在沙盒中可访问", async () => {
+    const script = Object.assign({}, scriptRes) as ScriptLoadInfo;
+    script.metadata.grant = ["CAT.agent.dom"];
+    const exec = new ExecScript(script, {
+      envPrefix: "scripting",
+      message: undefined as any,
+      contentMsg: undefined as any,
+      code: nilFn,
+      envInfo,
+    });
+    script.code = `return {
+      CAT: typeof CAT,
+      agent: typeof CAT.agent,
+      dom: typeof CAT.agent.dom,
+      listTabs: typeof CAT.agent.dom.listTabs,
+      navigate: typeof CAT.agent.dom.navigate,
+      readPage: typeof CAT.agent.dom.readPage,
+      screenshot: typeof CAT.agent.dom.screenshot,
+      click: typeof CAT.agent.dom.click,
+      fill: typeof CAT.agent.dom.fill,
+      scroll: typeof CAT.agent.dom.scroll,
+      waitFor: typeof CAT.agent.dom.waitFor,
+    }`;
+    exec.scriptFunc = compileScript(compileScriptCode(script));
+    const ret = await exec.exec();
+    expect(ret.CAT).toEqual("object");
+    expect(ret.agent).toEqual("object");
+    expect(ret.dom).toEqual("object");
+    expect(ret.listTabs).toEqual("function");
+    expect(ret.navigate).toEqual("function");
+    expect(ret.readPage).toEqual("function");
+    expect(ret.screenshot).toEqual("function");
+    expect(ret.click).toEqual("function");
+    expect(ret.fill).toEqual("function");
+    expect(ret.scroll).toEqual("function");
+    expect(ret.waitFor).toEqual("function");
+  });
+
+  it("CAT.agent.dom.readPage 应通过 sendMessage 发送正确参数", async () => {
+    const script = Object.assign({}, scriptRes) as ScriptLoadInfo;
+    script.uuid = "test-uuid";
+    script.metadata.grant = ["CAT.agent.dom"];
+    const mockSendMessage = vi.fn().mockResolvedValue({ data: { title: "Test", url: "https://example.com" } });
+    const mockMessage = {
+      sendMessage: mockSendMessage,
+    } as unknown as Message;
+    const exec = new ExecScript(script, {
+      envPrefix: "offscreen",
+      message: mockMessage,
+      contentMsg: undefined as any,
+      code: nilFn,
+      envInfo,
+    });
+    script.code = `return CAT.agent.dom.readPage({ tabId: 1, mode: "summary", maxLength: 2000 });`;
+    exec.scriptFunc = compileScript(compileScriptCode(script));
+    const ret = await exec.exec();
+    expect(ret).toEqual({ title: "Test", url: "https://example.com" });
+    expect(mockSendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "offscreen/runtime/gmApi",
+        data: expect.objectContaining({
+          api: "CAT_agentDom",
+          params: [
+            expect.objectContaining({
+              action: "readPage",
+              options: { tabId: 1, mode: "summary", maxLength: 2000 },
+              scriptUuid: "test-uuid",
+            }),
+          ],
+        }),
+      })
+    );
+  });
+
+  it("未 grant CAT.agent.dom 时方法不可用", async () => {
+    const script = Object.assign({}, scriptRes) as ScriptLoadInfo;
+    script.metadata.grant = ["GM_log"];
+    const exec = new ExecScript(script, {
+      envPrefix: "scripting",
+      message: undefined as any,
+      contentMsg: undefined as any,
+      code: nilFn,
+      envInfo,
+    });
+    script.code = `return { hasCat: typeof CAT !== "undefined" && CAT?.agent?.dom?.readPage !== undefined }`;
+    exec.scriptFunc = compileScript(compileScriptCode(script));
+    const ret = await exec.exec();
+    expect(ret.hasCat).toEqual(false);
+  });
+});
diff --git a/src/app/service/content/gm_api/gm_api.ts b/src/app/service/content/gm_api/gm_api.ts
index ba023b3a5..468b547b9 100644
--- a/src/app/service/content/gm_api/gm_api.ts
+++ b/src/app/service/content/gm_api/gm_api.ts
@@ -18,13 +18,25 @@ import GMContext from "./gm_context";
 import { type ScriptRunResource } from "@App/app/repo/scripts";
 import type { ValueUpdateDataEncoded } from "../types";
 import { connect, sendMessage } from "@Packages/message/client";
+import { ScriptEnvTag } from "@Packages/message/consts";
 import { getStorageName } from "@App/pkg/utils/utils";
 import { ListenerManager } from "../listener_manager";
 import { decodeRValue, encodeRValue, type REncoded } from "@App/pkg/utils/message_value";
 import { type TGMKeyValue } from "@App/app/repo/value";
 import type { ContextType } from "./gm_xhr";
 import { convObjectToURL, GM_xmlhttpRequest, toBlobURL, urlToDocumentInContentPage } from "./gm_xhr";
-import { ScriptEnvTag } from "@Packages/message/consts";
+// 导入 CAT Agent API 以触发装饰器注册
+// 注意：不能使用 import "./cat_agent"，sideEffects 配置会导致 tree-shaking 移除纯副作用导入
+import CATAgentApi from "./cat_agent";
+void CATAgentApi;
+import CATAgentToolsApi from "./cat_agent_tools";
+void CATAgentToolsApi;
+import CATAgentSkillsApi from "./cat_agent_skills";
+void CATAgentSkillsApi;
+import CATAgentDomApi from "./cat_agent_dom";
+void CATAgentDomApi;
+import CATAgentTaskApi from "./cat_agent_task";
+void CATAgentTaskApi;
 
 // 内部函数呼叫定义
 export interface IGM_Base {
diff --git a/src/app/service/offscreen/client.ts b/src/app/service/offscreen/client.ts
index a79421c08..2fe9ceb1f 100644
--- a/src/app/service/offscreen/client.ts
+++ b/src/app/service/offscreen/client.ts
@@ -37,6 +37,22 @@ export function createObjectURL(msgSender: MessageSend, params: { blob: Blob; pe
   return sendMessage(msgSender, "offscreen/createObjectURL", params);
 }
 
+// 执行 CATTool
+export function executeCATTool(
+  msgSender: MessageSend,
+  params: {
+    uuid: string;
+    code: string;
+    args: Record<string, unknown>;
+    grants: string[];
+    name: string;
+    requires?: Array<{ url: string; content: string }>;
+    configValues?: Record<string, unknown>;
+  }
+) {
+  return sendMessage(msgSender, "offscreen/executeCATTool", params);
+}
+
 export class VscodeConnectClient extends Client {
   constructor(msgSender: MessageSend) {
     super(msgSender, "offscreen/vscodeConnect");
diff --git a/src/app/service/offscreen/index.ts b/src/app/service/offscreen/index.ts
index a3a22328d..0d200f1f7 100644
--- a/src/app/service/offscreen/index.ts
+++ b/src/app/service/offscreen/index.ts
@@ -57,10 +57,11 @@ export class OffscreenManager {
     script.init();
     // 转发从sandbox来的gm api请求
     forwardMessage("serviceWorker", "runtime/gmApi", this.windowServer, this.extMsgSender);
+    // 转发 CATTool 执行请求到 sandbox
+    forwardMessage("sandbox", "executeCATTool", this.windowServer, this.windowMessage);
     // 转发valueUpdate与emitEvent
     forwardMessage("sandbox", "runtime/valueUpdate", this.windowServer, this.windowMessage);
     forwardMessage("sandbox", "runtime/emitEvent", this.windowServer, this.windowMessage);
-
     const gmApi = new GMApi(this.windowServer.group("gmApi"));
     gmApi.init();
     const vscodeConnect = new VSCodeConnect(this.windowServer.group("vscodeConnect"), this.extMsgSender);
diff --git a/src/app/service/sandbox/runtime.ts b/src/app/service/sandbox/runtime.ts
index 3ceff0654..91ddf4671 100644
--- a/src/app/service/sandbox/runtime.ts
+++ b/src/app/service/sandbox/runtime.ts
@@ -13,6 +13,7 @@ import { CronJob } from "cron";
 import { proxyUpdateRunStatus } from "../offscreen/client";
 import { BgExecScriptWarp } from "../content/exec_warp";
 import type ExecScript from "../content/exec_script";
+import { compileScriptCodeByResource } from "../content/utils";
 import type { ValueUpdateDataEncoded } from "../content/types";
 import { getStorageName, getMetadataStr, getUserConfigStr, getISOWeek } from "@App/pkg/utils/utils";
 import type { EmitEventRequest, ScriptLoadInfo } from "../service_worker/types";
@@ -346,6 +347,67 @@ export class Runtime {
     this.api.on("runtime/valueUpdate", this.valueUpdate.bind(this));
     this.api.on("runtime/emitEvent", this.emitEvent.bind(this));
     this.api.on("setSandboxLanguage", this.setSandboxLanguage.bind(this));
+    this.api.on("executeCATTool", this.executeCATTool.bind(this));
     initLanguage();
   }
+
+  // 执行 CATTool：构建最小化脚本上下文，注入 args，执行并返回结果
+  async executeCATTool(params: {
+    uuid: string;
+    code: string;
+    args: Record<string, unknown>;
+    grants: string[];
+    name: string;
+    requires?: Array<{ url: string; content: string }>;
+    configValues?: Record<string, unknown>;
+  }): Promise<unknown> {
+    const uuid = params.uuid;
+    const metadata: any = {
+      grant: params.grants,
+    };
+    // 通过 compileScriptCodeByResource 包裹代码，加上 with(arguments[0]||this.$) 等上下文绑定，
+    // 使脚本能访问 sandboxContext 上注入的变量（args、GM API 等）
+    const compiledCode = compileScriptCodeByResource({
+      name: params.name,
+      code: params.code,
+      require: params.requires || [],
+    });
+
+    // 构造最小化的 ScriptLoadInfo
+    const scriptLoadInfo = {
+      uuid,
+      name: params.name,
+      namespace: "",
+      type: SCRIPT_TYPE_BACKGROUND,
+      status: 1,
+      sort: 0,
+      runStatus: "complete" as const,
+      createtime: Date.now(),
+      checktime: 0,
+      code: compiledCode,
+      value: {},
+      flag: "",
+      resource: {},
+      metadata,
+      originalMetadata: metadata,
+      metadataStr: "",
+      userConfigStr: "",
+    } as ScriptLoadInfo;
+
+    // 使用 BgExecScriptWarp 执行，它会自动构建 setTimeout/setInterval 等
+    const exec = new BgExecScriptWarp(scriptLoadInfo, this.windowMessage);
+    // 通过 sandboxContext 注入 args（BgExecScriptWarp 通过 globalInjection 注入了 setTimeout 等，
+    // sandboxContext 已经包含了这些，再追加 args 即可）
+    if ((exec as any).sandboxContext) {
+      (exec as any).sandboxContext.args = params.args;
+      (exec as any).sandboxContext.CAT_CONFIG = Object.freeze(params.configValues || {});
+    }
+
+    try {
+      const result = await exec.exec();
+      return result;
+    } finally {
+      exec.stop();
+    }
+  }
 }
diff --git a/src/app/service/service_worker/agent.test.ts b/src/app/service/service_worker/agent.test.ts
new file mode 100644
index 000000000..acdc6c42d
--- /dev/null
+++ b/src/app/service/service_worker/agent.test.ts
@@ -0,0 +1,2268 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { AgentService, isRetryableError, withRetry, classifyErrorCode } from "./agent";
+import { cacheInstance } from "@App/app/cache";
+import { CACHE_KEY_CATTOOL_INSTALL } from "@App/app/cache_key";
+
+// 确保 chrome.tabs.onRemoved 方法可用
+if (!chrome.tabs.onRemoved.removeListener) {
+  (chrome.tabs.onRemoved as any).removeListener = vi.fn();
+}
+if (!chrome.tabs.onRemoved.addListener) {
+  (chrome.tabs.onRemoved as any).addListener = vi.fn();
+}
+
+// 创建 mock AgentService 实例
+function createTestService() {
+  const mockGroup = { on: vi.fn() } as any;
+  const mockSender = {} as any;
+
+  const service = new AgentService(mockGroup, mockSender);
+
+  // 替换 modelRepo（避免 chrome.storage 调用）
+  const mockModelRepo = {
+    listModels: vi
+      .fn()
+      .mockResolvedValue([
+        { id: "test-openai", name: "Test", provider: "openai", apiBaseUrl: "", apiKey: "", model: "gpt-4o" },
+      ]),
+    getModel: vi.fn().mockImplementation((id: string) => {
+      if (id === "test-openai") {
+        return Promise.resolve({
+          id: "test-openai",
+          name: "Test",
+          provider: "openai",
+          apiBaseUrl: "",
+          apiKey: "",
+          model: "gpt-4o",
+        });
+      }
+      return Promise.resolve(undefined);
+    }),
+    getDefaultModelId: vi.fn().mockResolvedValue("test-openai"),
+    saveModel: vi.fn().mockResolvedValue(undefined),
+    removeModel: vi.fn().mockResolvedValue(undefined),
+    setDefaultModelId: vi.fn().mockResolvedValue(undefined),
+  };
+  (service as any).modelRepo = mockModelRepo;
+
+  // 替换 repo 和 catToolRepo（避免 OPFS 调用）
+  const mockRepo = {
+    appendMessage: vi.fn().mockResolvedValue(undefined),
+    getMessages: vi.fn().mockResolvedValue([]),
+    listConversations: vi.fn().mockResolvedValue([]),
+    saveConversation: vi.fn().mockResolvedValue(undefined),
+    saveMessages: vi.fn().mockResolvedValue(undefined),
+  };
+  const mockCatToolRepo = {
+    listTools: vi.fn().mockResolvedValue([]),
+    getTool: vi.fn().mockResolvedValue(null),
+    saveTool: vi.fn().mockResolvedValue(undefined),
+    removeTool: vi.fn().mockResolvedValue(true),
+  };
+  const mockSkillRepo = {
+    listSkills: vi.fn().mockResolvedValue([]),
+    getSkill: vi.fn().mockResolvedValue(null),
+    saveSkill: vi.fn().mockResolvedValue(undefined),
+    removeSkill: vi.fn().mockResolvedValue(true),
+    getSkillScripts: vi.fn().mockResolvedValue([]),
+    getSkillReferences: vi.fn().mockResolvedValue([]),
+    getReference: vi.fn().mockResolvedValue(null),
+  };
+  (service as any).repo = mockRepo;
+  (service as any).catToolRepo = mockCatToolRepo;
+  (service as any).skillRepo = mockSkillRepo;
+
+  return { service, mockRepo, mockCatToolRepo, mockSkillRepo };
+}
+
+const VALID_CATTOOL_CODE = `// ==CATTool==
+// @name test-tool
+// @description A test tool
+// @param {string} input - The input
+// ==/CATTool==
+module.exports = async function(params) { return params.input; }`;
+
+describe("AgentService CATTool 安装流程", () => {
+  beforeEach(async () => {
+    await cacheInstance.clear();
+  });
+
+  describe("cancelCATToolInstall", () => {
+    it("应 await cleanupPendingInstall 并 reject", async () => {
+      const { service } = createTestService();
+      let rejected = false;
+      let rejectedError: Error | null = null;
+
+      // 模拟 pendingInstall
+      const uuid = "test-uuid";
+      // 创建 pending promise（catch 防止 unhandled rejection）
+      new Promise<any>((resolve, reject) => {
+        (service as any).pendingInstalls.set(uuid, {
+          resolve,
+          reject: (err: Error) => {
+            rejected = true;
+            rejectedError = err;
+            reject(err);
+          },
+          tabId: 1,
+          timer: setTimeout(() => {}, 60000),
+          onTabRemoved: () => {},
+        });
+      }).catch(() => {});
+
+      await service.cancelCATToolInstall(uuid);
+
+      expect(rejected).toBe(true);
+      expect(rejectedError!.message).toBe("CATTool install cancelled by user");
+      // pendingInstalls 应已清理
+      expect((service as any).pendingInstalls.has(uuid)).toBe(false);
+    });
+
+    it("uuid 不存在时应静默返回", async () => {
+      const { service } = createTestService();
+      // 不应抛出异常
+      await service.cancelCATToolInstall("non-existent");
+    });
+  });
+
+  describe("completeCATToolInstall", () => {
+    it("缓存存在时应完成安装并 resolve", async () => {
+      const { service } = createTestService();
+      const uuid = "complete-uuid";
+
+      // 设置缓存
+      await cacheInstance.set(CACHE_KEY_CATTOOL_INSTALL + uuid, {
+        code: VALID_CATTOOL_CODE,
+        scriptUuid: "src-script",
+        scriptName: "Source Script",
+      });
+
+      let resolvedRecord: any = null;
+
+      const completionPromise = new Promise<any>((resolve, reject) => {
+        (service as any).pendingInstalls.set(uuid, {
+          resolve: (record: any) => {
+            resolvedRecord = record;
+            resolve(record);
+          },
+          reject,
+          tabId: 1,
+          timer: setTimeout(() => {}, 60000),
+          onTabRemoved: () => {},
+        });
+      });
+
+      await (service as any).completeCATToolInstall(uuid);
+      await completionPromise;
+
+      expect(resolvedRecord).not.toBeNull();
+      expect(resolvedRecord.name).toBe("test-tool");
+      // pendingInstalls 应已清理
+      expect((service as any).pendingInstalls.has(uuid)).toBe(false);
+    });
+
+    it("缓存不存在时应 reject", async () => {
+      const { service } = createTestService();
+      const uuid = "no-cache-uuid";
+
+      let rejectedError: Error | null = null;
+
+      new Promise<any>((resolve, reject) => {
+        (service as any).pendingInstalls.set(uuid, {
+          resolve,
+          reject: (err: Error) => {
+            rejectedError = err;
+            reject(err);
+          },
+          tabId: 1,
+          timer: setTimeout(() => {}, 60000),
+          onTabRemoved: () => {},
+        });
+      }).catch(() => {});
+
+      await (service as any).completeCATToolInstall(uuid);
+
+      expect(rejectedError).not.toBeNull();
+      expect(rejectedError!.message).toContain("not found or expired");
+    });
+
+    it("pending 不存在时应静默返回", async () => {
+      const { service } = createTestService();
+      // 不应抛出异常
+      await (service as any).completeCATToolInstall("non-existent");
+    });
+  });
+
+  describe("getCATToolInstallCode", () => {
+    it("缓存存在时应返回代码和元信息", async () => {
+      const { service } = createTestService();
+      const uuid = "get-code-uuid";
+
+      await cacheInstance.set(CACHE_KEY_CATTOOL_INSTALL + uuid, {
+        code: VALID_CATTOOL_CODE,
+        scriptName: "My Script",
+      });
+
+      const result = await (service as any).getCATToolInstallCode(uuid);
+
+      expect(result.code).toBe(VALID_CATTOOL_CODE);
+      expect(result.scriptName).toBe("My Script");
+      expect(result.isUpdate).toBe(false);
+    });
+
+    it("同名工具已存在时 isUpdate 应为 true", async () => {
+      const { service, mockCatToolRepo } = createTestService();
+      const uuid = "update-uuid";
+
+      await cacheInstance.set(CACHE_KEY_CATTOOL_INSTALL + uuid, {
+        code: VALID_CATTOOL_CODE,
+      });
+
+      // 模拟已存在同名工具
+      mockCatToolRepo.getTool.mockResolvedValueOnce({ name: "test-tool" });
+
+      const result = await (service as any).getCATToolInstallCode(uuid);
+
+      expect(result.isUpdate).toBe(true);
+    });
+
+    it("缓存不存在时应抛出异常", async () => {
+      const { service } = createTestService();
+
+      await expect((service as any).getCATToolInstallCode("missing")).rejects.toThrow("not found or expired");
+    });
+  });
+
+  describe("installCATTool", () => {
+    it("应正确安装新工具", async () => {
+      const { service, mockCatToolRepo } = createTestService();
+
+      const record = await service.installCATTool(VALID_CATTOOL_CODE);
+
+      expect(record.id).toBeDefined();
+      expect(record.name).toBe("test-tool");
+      expect(record.description).toBe("A test tool");
+      expect(record.code).toBe(VALID_CATTOOL_CODE);
+      expect(record.installtime).toBeDefined();
+      expect(record.updatetime).toBeDefined();
+      expect(mockCatToolRepo.saveTool).toHaveBeenCalledTimes(1);
+    });
+
+    it("更新已有工具时应保留 id 和 installtime", async () => {
+      const { service, mockCatToolRepo } = createTestService();
+
+      const oldId = "existing-uuid-123";
+      const oldInstallTime = 1000000;
+      mockCatToolRepo.getTool.mockResolvedValueOnce({
+        id: oldId,
+        name: "test-tool",
+        installtime: oldInstallTime,
+        updatetime: oldInstallTime,
+      });
+
+      const record = await service.installCATTool(VALID_CATTOOL_CODE);
+
+      expect(record.id).toBe(oldId);
+      expect(record.installtime).toBe(oldInstallTime);
+      expect(record.updatetime).toBeGreaterThan(oldInstallTime);
+    });
+
+    it("无效代码应抛出异常", async () => {
+      const { service } = createTestService();
+
+      await expect(service.installCATTool("invalid code")).rejects.toThrow("Invalid CATTool");
+    });
+  });
+
+  describe("removeCATTool", () => {
+    it("工具存在时应删除并返回 true", async () => {
+      const { service, mockCatToolRepo } = createTestService();
+      mockCatToolRepo.removeTool.mockResolvedValueOnce(true);
+
+      const result = await service.removeCATTool("test-tool");
+
+      expect(result).toBe(true);
+      expect(mockCatToolRepo.removeTool).toHaveBeenCalledWith("test-tool");
+    });
+
+    it("工具不存在时应返回 false", async () => {
+      const { service, mockCatToolRepo } = createTestService();
+      mockCatToolRepo.removeTool.mockResolvedValueOnce(false);
+
+      const result = await service.removeCATTool("non-existent");
+
+      expect(result).toBe(false);
+    });
+  });
+});
+
+// ---- Skill 系统测试 ----
+
+import type { SkillRecord, CATToolRecord } from "@App/app/service/agent/types";
+
+// 辅助：创建 SkillRecord
+function makeSkillRecord(overrides: Partial<SkillRecord> = {}): SkillRecord {
+  return {
+    name: "test-skill",
+    description: "A test skill",
+    toolNames: [],
+    referenceNames: [],
+    prompt: "You are a test skill assistant.",
+    installtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+// 辅助：创建 CATToolRecord
+function makeCATToolRecord(overrides: Partial<CATToolRecord> = {}): CATToolRecord {
+  return {
+    id: "tool-id-1",
+    name: "test-cattool",
+    description: "A test CATTool",
+    params: [{ name: "input", type: "string", description: "The input", required: true }],
+    grants: [],
+    code: "module.exports = async (p) => p.input;",
+    installtime: Date.now(),
+    updatetime: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("AgentService Skill 系统", () => {
+  describe("resolveSkills", () => {
+    it("无 skills 时返回空", () => {
+      const { service } = createTestService();
+      const result = (service as any).resolveSkills(undefined);
+      expect(result.promptSuffix).toBe("");
+      expect(result.metaTools).toEqual([]);
+    });
+
+    it('"auto" 加载全部 skill 摘要', () => {
+      const { service } = createTestService();
+
+      const skill1 = makeSkillRecord({
+        name: "price-monitor",
+        description: "监控商品价格",
+        toolNames: ["price-check"],
+        prompt: "Monitor prices.",
+      });
+      const skill2 = makeSkillRecord({
+        name: "translator",
+        description: "翻译助手",
+        referenceNames: ["glossary"],
+        prompt: "Translate text.",
+      });
+      (service as any).skillCache.set("price-monitor", skill1);
+      (service as any).skillCache.set("translator", skill2);
+
+      const result = (service as any).resolveSkills("auto");
+
+      // promptSuffix 应包含两个 skill 的 name + description
+      expect(result.promptSuffix).toContain("price-monitor");
+      expect(result.promptSuffix).toContain("监控商品价格");
+      expect(result.promptSuffix).toContain("translator");
+      expect(result.promptSuffix).toContain("翻译助手");
+
+      // promptSuffix 不应包含 skill.prompt 内容
+      expect(result.promptSuffix).not.toContain("Monitor prices.");
+      expect(result.promptSuffix).not.toContain("Translate text.");
+
+      // 应返回 2 个 metaTools（load_skill, read_reference），不再有 execute_skill_tool
+      expect(result.metaTools).toHaveLength(2);
+      const names = result.metaTools.map((t: any) => t.definition.name);
+      expect(names).toContain("load_skill");
+      expect(names).toContain("read_reference");
+      expect(names).not.toContain("execute_skill_tool");
+
+      // dynamicToolNames 初始为空
+      expect(result.dynamicToolNames).toEqual([]);
+    });
+
+    it("指定名称过滤", () => {
+      const { service } = createTestService();
+
+      const skill1 = makeSkillRecord({ name: "skill-a", description: "Skill A" });
+      const skill2 = makeSkillRecord({ name: "skill-b", description: "Skill B" });
+      (service as any).skillCache.set("skill-a", skill1);
+      (service as any).skillCache.set("skill-b", skill2);
+
+      const result = (service as any).resolveSkills(["skill-a"]);
+
+      expect(result.promptSuffix).toContain("skill-a");
+      expect(result.promptSuffix).toContain("Skill A");
+      expect(result.promptSuffix).not.toContain("skill-b");
+      expect(result.promptSuffix).not.toContain("Skill B");
+    });
+
+    it("无工具/参考资料的 skill 只注册 load_skill", () => {
+      const { service } = createTestService();
+
+      const skill = makeSkillRecord({ name: "simple-skill", toolNames: [], referenceNames: [] });
+      (service as any).skillCache.set("simple-skill", skill);
+
+      const result = (service as any).resolveSkills("auto");
+
+      expect(result.metaTools).toHaveLength(1);
+      expect(result.metaTools[0].definition.name).toBe("load_skill");
+    });
+
+    it("有工具无参考资料时只注册 load_skill", () => {
+      const { service } = createTestService();
+
+      const skill = makeSkillRecord({ name: "tools-only", toolNames: ["my-tool"], referenceNames: [] });
+      (service as any).skillCache.set("tools-only", skill);
+
+      const result = (service as any).resolveSkills("auto");
+
+      // 工具在 load_skill 调用时才动态注册，不再有 execute_skill_tool
+      expect(result.metaTools).toHaveLength(1);
+      expect(result.metaTools[0].definition.name).toBe("load_skill");
+    });
+
+    it("有参考资料无工具时注册 load_skill + read_reference", () => {
+      const { service } = createTestService();
+
+      const skill = makeSkillRecord({ name: "refs-only", toolNames: [], referenceNames: ["doc.md"] });
+      (service as any).skillCache.set("refs-only", skill);
+
+      const result = (service as any).resolveSkills("auto");
+
+      expect(result.metaTools).toHaveLength(2);
+      const names = result.metaTools.map((t: any) => t.definition.name);
+      expect(names).toContain("load_skill");
+      expect(names).toContain("read_reference");
+    });
+  });
+
+  describe("load_skill meta-tool", () => {
+    it("返回完整 prompt", async () => {
+      const { service } = createTestService();
+
+      const skill = makeSkillRecord({ name: "my-skill", prompt: "Detailed instructions here." });
+      (service as any).skillCache.set("my-skill", skill);
+
+      const result = (service as any).resolveSkills("auto");
+      const loadSkill = result.metaTools.find((t: any) => t.definition.name === "load_skill");
+
+      const output = await loadSkill.executor.execute({ skill_name: "my-skill" });
+      expect(output).toBe("Detailed instructions here.");
+    });
+
+    it("skill 不存在时抛错", async () => {
+      const { service } = createTestService();
+
+      const skill = makeSkillRecord({ name: "existing" });
+      (service as any).skillCache.set("existing", skill);
+
+      const result = (service as any).resolveSkills("auto");
+      const loadSkill = result.metaTools.find((t: any) => t.definition.name === "load_skill");
+
+      await expect(loadSkill.executor.execute({ skill_name: "non-existent" })).rejects.toThrow(
+        'Skill "non-existent" not found'
+      );
+    });
+
+    it("动态注册 skill 的 CATTool 为独立工具", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const toolRecord = makeCATToolRecord({
+        name: "price-check",
+        description: "Check price",
+        params: [{ name: "url", type: "string", description: "Target URL", required: true }],
+        grants: [],
+      });
+      const skill = makeSkillRecord({ name: "price-skill", toolNames: ["price-check"] });
+      (service as any).skillCache.set("price-skill", skill);
+
+      mockSkillRepo.getSkillScripts.mockResolvedValueOnce([toolRecord]);
+
+      const result = (service as any).resolveSkills("auto");
+      const loadSkill = result.metaTools.find((t: any) => t.definition.name === "load_skill");
+
+      // 调用 load_skill 前，toolRegistry 中不应有 price-skill__price-check
+      const registry = (service as any).toolRegistry;
+      const defsBefore = registry.getDefinitions();
+      expect(defsBefore.find((d: any) => d.name === "price-skill__price-check")).toBeUndefined();
+
+      // 调用 load_skill（CATToolExecutor 执行会失败，但注册应完成）
+      const output = await loadSkill.executor.execute({ skill_name: "price-skill" });
+      expect(output).toBe(skill.prompt);
+
+      // 调用后，toolRegistry 中应有 price-skill__price-check
+      const defsAfter = registry.getDefinitions();
+      const registered = defsAfter.find((d: any) => d.name === "price-skill__price-check");
+      expect(registered).toBeDefined();
+      expect(registered.description).toBe("Check price");
+      expect(registered.parameters.properties.url).toBeDefined();
+      expect(registered.parameters.required).toContain("url");
+
+      // dynamicToolNames 应记录注册的工具名
+      expect(result.dynamicToolNames).toContain("price-skill__price-check");
+
+      // 验证 getSkillScripts 被正确调用
+      expect(mockSkillRepo.getSkillScripts).toHaveBeenCalledWith("price-skill");
+
+      // 清理
+      registry.unregisterBuiltin("price-skill__price-check");
+    });
+
+    it("无工具的 skill 不调用 getSkillScripts", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const skill = makeSkillRecord({ name: "no-tools", toolNames: [], prompt: "Simple prompt." });
+      (service as any).skillCache.set("no-tools", skill);
+
+      const result = (service as any).resolveSkills("auto");
+      const loadSkill = result.metaTools.find((t: any) => t.definition.name === "load_skill");
+
+      await loadSkill.executor.execute({ skill_name: "no-tools" });
+      expect(mockSkillRepo.getSkillScripts).not.toHaveBeenCalled();
+      expect(result.dynamicToolNames).toEqual([]);
+    });
+
+    it("多个 CATTool 应全部注册并使用正确前缀", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const tool1 = makeCATToolRecord({
+        name: "extract",
+        description: "提取数据",
+        params: [{ name: "url", type: "string", description: "URL", required: true }],
+      });
+      const tool2 = makeCATToolRecord({
+        name: "compare",
+        description: "比较价格",
+        params: [
+          { name: "a", type: "number", description: "价格A", required: true },
+          { name: "b", type: "number", description: "价格B", required: true },
+        ],
+      });
+
+      const skill = makeSkillRecord({ name: "taobao", toolNames: ["extract", "compare"] });
+      (service as any).skillCache.set("taobao", skill);
+
+      mockSkillRepo.getSkillScripts.mockResolvedValueOnce([tool1, tool2]);
+
+      const result = (service as any).resolveSkills("auto");
+      const loadSkill = result.metaTools.find((t: any) => t.definition.name === "load_skill");
+
+      await loadSkill.executor.execute({ skill_name: "taobao" });
+
+      const registry = (service as any).toolRegistry;
+      const defs = registry.getDefinitions();
+
+      // 两个工具都应注册
+      const extractDef = defs.find((d: any) => d.name === "taobao__extract");
+      const compareDef = defs.find((d: any) => d.name === "taobao__compare");
+      expect(extractDef).toBeDefined();
+      expect(compareDef).toBeDefined();
+      expect(extractDef.description).toBe("提取数据");
+      expect(compareDef.parameters.required).toEqual(["a", "b"]);
+
+      // dynamicToolNames 应记录两个工具名
+      expect(result.dynamicToolNames).toHaveLength(2);
+      expect(result.dynamicToolNames).toContain("taobao__extract");
+      expect(result.dynamicToolNames).toContain("taobao__compare");
+
+      // 清理
+      registry.unregisterBuiltin("taobao__extract");
+      registry.unregisterBuiltin("taobao__compare");
+    });
+
+    it("重复 load_skill 同一 skill 应幂等注册（覆盖已有）", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const toolRecord = makeCATToolRecord({
+        name: "my-tool",
+        description: "V1",
+        params: [],
+      });
+      const skill = makeSkillRecord({ name: "my-skill", toolNames: ["my-tool"] });
+      (service as any).skillCache.set("my-skill", skill);
+
+      // 第一次 load
+      mockSkillRepo.getSkillScripts.mockResolvedValueOnce([toolRecord]);
+      const result = (service as any).resolveSkills("auto");
+      const loadSkill = result.metaTools.find((t: any) => t.definition.name === "load_skill");
+      await loadSkill.executor.execute({ skill_name: "my-skill" });
+
+      // 第二次 load（模拟更新后的 toolRecord）
+      const updatedTool = makeCATToolRecord({ name: "my-tool", description: "V2", params: [] });
+      mockSkillRepo.getSkillScripts.mockResolvedValueOnce([updatedTool]);
+      await loadSkill.executor.execute({ skill_name: "my-skill" });
+
+      const registry = (service as any).toolRegistry;
+      const defs = registry.getDefinitions();
+      const def = defs.find((d: any) => d.name === "my-skill__my-tool");
+      expect(def).toBeDefined();
+
+      // dynamicToolNames 应记录两次（由外层清理负责去重）
+      expect(result.dynamicToolNames).toContain("my-skill__my-tool");
+
+      // 清理
+      registry.unregisterBuiltin("my-skill__my-tool");
+    });
+  });
+
+  describe("read_reference meta-tool", () => {
+    it("正常返回参考资料内容", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const skill = makeSkillRecord({ name: "ref-skill", referenceNames: ["api-doc"] });
+      (service as any).skillCache.set("ref-skill", skill);
+
+      mockSkillRepo.getReference.mockResolvedValueOnce({ name: "api-doc", content: "API documentation content" });
+
+      const result = (service as any).resolveSkills("auto");
+      const readRef = result.metaTools.find((t: any) => t.definition.name === "read_reference");
+
+      const output = await readRef.executor.execute({ skill_name: "ref-skill", reference_name: "api-doc" });
+      expect(output).toBe("API documentation content");
+      expect(mockSkillRepo.getReference).toHaveBeenCalledWith("ref-skill", "api-doc");
+    });
+
+    it("不存在时抛错", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const skill = makeSkillRecord({ name: "ref-skill", referenceNames: ["doc"] });
+      (service as any).skillCache.set("ref-skill", skill);
+
+      mockSkillRepo.getReference.mockResolvedValueOnce(null);
+
+      const result = (service as any).resolveSkills("auto");
+      const readRef = result.metaTools.find((t: any) => t.definition.name === "read_reference");
+
+      await expect(
+        readRef.executor.execute({ skill_name: "ref-skill", reference_name: "missing-doc" })
+      ).rejects.toThrow('Reference "missing-doc" not found in skill "ref-skill"');
+    });
+  });
+
+  describe("installSkill + resolveSkills 集成", () => {
+    it("安装后缓存生效", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const skillMd = `---
+name: integrated-skill
+description: An integrated test skill
+---
+Do something useful.`;
+
+      mockSkillRepo.getSkill = vi.fn().mockResolvedValue(null);
+      // mock saveSkill to succeed
+      mockSkillRepo.saveSkill = vi.fn().mockResolvedValue(undefined);
+
+      await service.installSkill(skillMd);
+
+      // skillCache 应包含新安装的 skill
+      expect((service as any).skillCache.has("integrated-skill")).toBe(true);
+
+      const result = (service as any).resolveSkills("auto");
+      expect(result.promptSuffix).toContain("integrated-skill");
+      expect(result.promptSuffix).toContain("An integrated test skill");
+      // 不应包含 prompt 内容
+      expect(result.promptSuffix).not.toContain("Do something useful.");
+    });
+  });
+
+  describe("removeSkill + resolveSkills 集成", () => {
+    it("卸载后缓存清除", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      // 先放入缓存
+      const skill = makeSkillRecord({ name: "to-remove" });
+      (service as any).skillCache.set("to-remove", skill);
+
+      mockSkillRepo.removeSkill.mockResolvedValueOnce(true);
+
+      await service.removeSkill("to-remove");
+
+      // skillCache 应不再包含
+      expect((service as any).skillCache.has("to-remove")).toBe(false);
+
+      const result = (service as any).resolveSkills("auto");
+      expect(result.promptSuffix).toBe("");
+      expect(result.metaTools).toEqual([]);
+    });
+  });
+
+  describe("installSkill 完整流程", () => {
+    it("安装含脚本和参考资料的 Skill", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const skillMd = `---
+name: full-skill
+description: A skill with tools and refs
+---
+You are a full-featured skill.`;
+
+      const scripts = [
+        {
+          name: "my-tool",
+          code: VALID_CATTOOL_CODE,
+        },
+      ];
+
+      const references = [{ name: "api-doc", content: "Some API documentation" }];
+
+      const record = await service.installSkill(skillMd, scripts, references);
+
+      expect(record.name).toBe("full-skill");
+      expect(record.description).toBe("A skill with tools and refs");
+      expect(record.prompt).toBe("You are a full-featured skill.");
+      expect(record.toolNames).toEqual(["test-tool"]);
+      expect(record.referenceNames).toEqual(["api-doc"]);
+
+      // saveSkill 应被调用，带上脚本和参考资料
+      expect(mockSkillRepo.saveSkill).toHaveBeenCalledTimes(1);
+      const [savedRecord, savedScripts, savedRefs] = mockSkillRepo.saveSkill.mock.calls[0];
+      expect(savedRecord.name).toBe("full-skill");
+      expect(savedScripts).toHaveLength(1);
+      expect(savedScripts[0].name).toBe("test-tool");
+      expect(savedRefs).toHaveLength(1);
+      expect(savedRefs[0].name).toBe("api-doc");
+
+      // skillCache 应包含新安装的 skill
+      expect((service as any).skillCache.has("full-skill")).toBe(true);
+    });
+
+    it("更新已有 Skill 时保留 installtime", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const oldInstallTime = 1000000;
+      mockSkillRepo.getSkill.mockResolvedValueOnce(
+        makeSkillRecord({ name: "existing-skill", installtime: oldInstallTime })
+      );
+
+      const skillMd = `---
+name: existing-skill
+description: Updated description
+---
+Updated prompt.`;
+
+      const record = await service.installSkill(skillMd);
+
+      expect(record.installtime).toBe(oldInstallTime);
+      expect(record.updatetime).toBeGreaterThan(oldInstallTime);
+      expect(record.description).toBe("Updated description");
+      expect(record.prompt).toBe("Updated prompt.");
+    });
+
+    it("无效 SKILL.md 应抛出异常", async () => {
+      const { service } = createTestService();
+
+      await expect(service.installSkill("not valid skill md")).rejects.toThrow("Invalid SKILL.md");
+    });
+
+    it("含无效 CATTool 脚本时应抛出异常", async () => {
+      const { service } = createTestService();
+
+      const skillMd = `---
+name: bad-scripts
+description: Has invalid script
+---
+Some prompt.`;
+
+      await expect(service.installSkill(skillMd, [{ name: "bad-tool", code: "not a cattool" }])).rejects.toThrow(
+        "Invalid CATTool script"
+      );
+    });
+  });
+
+  describe("removeSkill", () => {
+    it("删除存在的 Skill 返回 true", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      (service as any).skillCache.set("to-delete", makeSkillRecord({ name: "to-delete" }));
+      mockSkillRepo.removeSkill.mockResolvedValueOnce(true);
+
+      const result = await service.removeSkill("to-delete");
+
+      expect(result).toBe(true);
+      expect(mockSkillRepo.removeSkill).toHaveBeenCalledWith("to-delete");
+      expect((service as any).skillCache.has("to-delete")).toBe(false);
+    });
+
+    it("删除不存在的 Skill 返回 false 且不影响缓存", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      mockSkillRepo.removeSkill.mockResolvedValueOnce(false);
+
+      const result = await service.removeSkill("non-existent");
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe("installSkill 从 ZIP 解析结果安装", () => {
+    it("应正确安装 parseSkillZip 返回的完整结构", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      // 模拟 parseSkillZip 的输出结构
+      const zipResult = {
+        skillMd: `---
+name: taobao-helper
+description: 淘宝购物助手
+---
+你是一个淘宝购物助手。`,
+        scripts: [{ name: "taobao_extract.js", code: VALID_CATTOOL_CODE }],
+        references: [
+          { name: "api_docs.md", content: "# API Docs\n淘宝接口文档" },
+          { name: "guide.txt", content: "使用指南" },
+        ],
+      };
+
+      const record = await service.installSkill(zipResult.skillMd, zipResult.scripts, zipResult.references);
+
+      expect(record.name).toBe("taobao-helper");
+      expect(record.description).toBe("淘宝购物助手");
+      expect(record.prompt).toBe("你是一个淘宝购物助手。");
+      expect(record.toolNames).toEqual(["test-tool"]); // CATTool 名称从 metadata 中解析
+      expect(record.referenceNames).toEqual(["api_docs.md", "guide.txt"]);
+
+      // 验证 saveSkill 调用参数
+      expect(mockSkillRepo.saveSkill).toHaveBeenCalledTimes(1);
+      const [savedRecord, savedScripts, savedRefs] = mockSkillRepo.saveSkill.mock.calls[0];
+      expect(savedRecord.name).toBe("taobao-helper");
+      expect(savedScripts).toHaveLength(1);
+      expect(savedScripts[0].name).toBe("test-tool");
+      expect(savedRefs).toHaveLength(2);
+      expect(savedRefs[0].name).toBe("api_docs.md");
+      expect(savedRefs[1].content).toBe("使用指南");
+
+      // 验证 skillCache 更新
+      expect((service as any).skillCache.has("taobao-helper")).toBe(true);
+    });
+
+    it("ZIP 结果中多个脚本应全部安装", async () => {
+      const { service, mockSkillRepo } = createTestService();
+
+      const anotherToolCode = `// ==CATTool==
+// @name another-tool
+// @description Another tool
+// @param {string} query - Search query
+// ==/CATTool==
+return query;`;
+
+      const record = await service.installSkill(
+        `---\nname: multi-tool\ndescription: Multi tools skill\n---\nMulti tool prompt.`,
+        [
+          { name: "tool1.js", code: VALID_CATTOOL_CODE },
+          { name: "tool2.js", code: anotherToolCode },
+        ],
+        []
+      );
+
+      expect(record.toolNames).toHaveLength(2);
+      expect(record.toolNames).toContain("test-tool");
+      expect(record.toolNames).toContain("another-tool");
+
+      const savedScripts = mockSkillRepo.saveSkill.mock.calls[0][1];
+      expect(savedScripts).toHaveLength(2);
+    });
+
+    it("ZIP 结果无脚本无参考资料时应正常安装", async () => {
+      const { service } = createTestService();
+
+      const record = await service.installSkill(
+        `---\nname: simple-zip\ndescription: Simple\n---\nSimple prompt.`,
+        [],
+        []
+      );
+
+      expect(record.name).toBe("simple-zip");
+      expect(record.toolNames).toEqual([]);
+      expect(record.referenceNames).toEqual([]);
+    });
+  });
+});
+
+// ---- handleConversationChat skill 动态工具清理测试 ----
+
+describe("handleConversationChat skill 动态工具清理", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  // 辅助：创建 mock sender
+  function createMockSender() {
+    const sentMessages: any[] = [];
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: vi.fn(),
+      onDisconnect: vi.fn(),
+    };
+    const sender = {
+      isType: (type: any) => type === 1, // GetSenderType.CONNECT
+      getConnect: () => mockConn,
+    };
+    return { sender, sentMessages };
+  }
+
+  it("对话结束后应清理 meta-tools 和动态注册的 CATTool", async () => {
+    const { service, mockRepo, mockSkillRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    // 设置 skill 带工具
+    const toolRecord = makeCATToolRecord({
+      name: "my-tool",
+      description: "A tool",
+      params: [],
+    });
+    const skill = makeSkillRecord({
+      name: "test-skill",
+      toolNames: ["my-tool"],
+      referenceNames: [],
+      prompt: "Test prompt.",
+    });
+    (service as any).skillCache.set("test-skill", skill);
+
+    // mock conversation 存在且带 skills
+    mockRepo.listConversations.mockResolvedValue([
+      {
+        id: "conv-1",
+        title: "Test",
+        modelId: "test-openai",
+        skills: "auto",
+        createtime: Date.now(),
+        updatetime: Date.now(),
+      },
+    ]);
+
+    // 第一轮 LLM 调用 load_skill → 注册动态工具
+    mockSkillRepo.getSkillScripts.mockResolvedValueOnce([toolRecord]);
+
+    // 构造 SSE：LLM 调用 load_skill，然后纯文本结束
+    const encoder = new TextEncoder();
+    // 第一次 fetch：返回 load_skill tool call
+    fetchSpy.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => {
+          const chunks = [
+            `data: {"choices":[{"delta":{"tool_calls":[{"id":"call_1","function":{"name":"load_skill","arguments":""}}]}}]}\n\n`,
+            `data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":"{\\"skill_name\\":\\"test-skill\\"}"}}]}}]}\n\n`,
+            `data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n`,
+          ];
+          let i = 0;
+          return {
+            read: async () => {
+              if (i >= chunks.length) return { done: true, value: undefined };
+              return { done: false, value: encoder.encode(chunks[i++]) };
+            },
+            releaseLock: () => {},
+            cancel: async () => {},
+            closed: Promise.resolve(undefined),
+          };
+        },
+      },
+      text: async () => "",
+    } as unknown as Response);
+
+    // 第二次 fetch：纯文本结束
+    fetchSpy.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => {
+          const chunks = [
+            `data: {"choices":[{"delta":{"content":"完成"}}]}\n\n`,
+            `data: {"usage":{"prompt_tokens":20,"completion_tokens":8}}\n\n`,
+          ];
+          let i = 0;
+          return {
+            read: async () => {
+              if (i >= chunks.length) return { done: true, value: undefined };
+              return { done: false, value: encoder.encode(chunks[i++]) };
+            },
+            releaseLock: () => {},
+            cancel: async () => {},
+            closed: Promise.resolve(undefined),
+          };
+        },
+      },
+      text: async () => "",
+    } as unknown as Response);
+
+    const registry = (service as any).toolRegistry;
+
+    // 对话前 registry 不应有 load_skill 和 test-skill__my-tool
+    expect(registry.getDefinitions().find((d: any) => d.name === "load_skill")).toBeUndefined();
+    expect(registry.getDefinitions().find((d: any) => d.name === "test-skill__my-tool")).toBeUndefined();
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "test" }, sender);
+
+    // 对话后 meta-tools 应已清理
+    expect(registry.getDefinitions().find((d: any) => d.name === "load_skill")).toBeUndefined();
+    // 动态注册的 CATTool 也应已清理
+    expect(registry.getDefinitions().find((d: any) => d.name === "test-skill__my-tool")).toBeUndefined();
+  });
+});
+
+// ---- init() 消息注册测试 ----
+
+describe("AgentService init() 消息注册", () => {
+  it("应注册 installSkill 和 removeSkill 消息处理", () => {
+    const mockGroup = { on: vi.fn() } as any;
+    const mockSender = {} as any;
+
+    const service = new AgentService(mockGroup, mockSender);
+
+    // 替换 repos 避免 OPFS 调用
+    (service as any).catToolRepo = { listTools: vi.fn().mockResolvedValue([]) };
+    (service as any).skillRepo = { listSkills: vi.fn().mockResolvedValue([]) };
+
+    service.init();
+
+    // 收集所有 group.on 注册的消息名
+    const registeredNames = mockGroup.on.mock.calls.map((call: any[]) => call[0]);
+
+    expect(registeredNames).toContain("installSkill");
+    expect(registeredNames).toContain("removeSkill");
+  });
+
+  it("installSkill 消息处理应正确转发参数", async () => {
+    const mockGroup = { on: vi.fn() } as any;
+    const mockSender = {} as any;
+
+    const service = new AgentService(mockGroup, mockSender);
+
+    const mockSkillRepo = {
+      listSkills: vi.fn().mockResolvedValue([]),
+      getSkill: vi.fn().mockResolvedValue(null),
+      saveSkill: vi.fn().mockResolvedValue(undefined),
+    };
+    (service as any).catToolRepo = { listTools: vi.fn().mockResolvedValue([]) };
+    (service as any).skillRepo = mockSkillRepo;
+
+    service.init();
+
+    // 找到 installSkill 处理函数
+    const installSkillCall = mockGroup.on.mock.calls.find((call: any[]) => call[0] === "installSkill");
+    expect(installSkillCall).toBeDefined();
+
+    const handler = installSkillCall[1];
+    const skillMd = `---
+name: msg-test
+description: Test via message
+---
+Prompt content.`;
+
+    const result = await handler({ skillMd });
+
+    expect(result.name).toBe("msg-test");
+    expect(mockSkillRepo.saveSkill).toHaveBeenCalledTimes(1);
+  });
+
+  it("removeSkill 消息处理应正确转发参数", async () => {
+    const mockGroup = { on: vi.fn() } as any;
+    const mockSender = {} as any;
+
+    const service = new AgentService(mockGroup, mockSender);
+
+    const mockSkillRepo = {
+      listSkills: vi.fn().mockResolvedValue([]),
+      removeSkill: vi.fn().mockResolvedValue(true),
+    };
+    (service as any).catToolRepo = { listTools: vi.fn().mockResolvedValue([]) };
+    (service as any).skillRepo = mockSkillRepo;
+
+    service.init();
+
+    // 找到 removeSkill 处理函数
+    const removeSkillCall = mockGroup.on.mock.calls.find((call: any[]) => call[0] === "removeSkill");
+    expect(removeSkillCall).toBeDefined();
+
+    const handler = removeSkillCall[1];
+    const result = await handler("msg-test-skill");
+
+    expect(result).toBe(true);
+    expect(mockSkillRepo.removeSkill).toHaveBeenCalledWith("msg-test-skill");
+  });
+});
+
+// ---- isRetryableError ----
+
+describe("isRetryableError", () => {
+  it("429 应可重试", () => {
+    expect(isRetryableError(new Error("HTTP 429 Too Many Requests"))).toBe(true);
+  });
+
+  it("500 应可重试", () => {
+    expect(isRetryableError(new Error("HTTP 500 Internal Server Error"))).toBe(true);
+  });
+
+  it("503 应可重试", () => {
+    expect(isRetryableError(new Error("503 Service Unavailable"))).toBe(true);
+  });
+
+  it("network 错误应可重试", () => {
+    expect(isRetryableError(new Error("network error"))).toBe(true);
+    expect(isRetryableError(new Error("Network Error"))).toBe(true);
+  });
+
+  it("fetch 失败应可重试", () => {
+    expect(isRetryableError(new Error("fetch failed"))).toBe(true);
+  });
+
+  it("ECONNRESET 应可重试", () => {
+    expect(isRetryableError(new Error("ECONNRESET"))).toBe(true);
+  });
+
+  it("401 不应重试", () => {
+    expect(isRetryableError(new Error("401 Unauthorized"))).toBe(false);
+  });
+
+  it("403 不应重试", () => {
+    expect(isRetryableError(new Error("403 Forbidden"))).toBe(false);
+  });
+
+  it("400 不应重试", () => {
+    expect(isRetryableError(new Error("400 Bad Request"))).toBe(false);
+  });
+
+  it("404 不应重试", () => {
+    expect(isRetryableError(new Error("404 Not Found"))).toBe(false);
+  });
+
+  it("普通错误不应重试", () => {
+    expect(isRetryableError(new Error("Invalid API key"))).toBe(false);
+    expect(isRetryableError(new Error("JSON parse error"))).toBe(false);
+  });
+});
+
+// ---- withRetry ----
+
+// 测试用的立即返回 delay（避免真实等待和 fake timer 复杂性）
+const immediateDelay = () => Promise.resolve();
+
+describe("withRetry", () => {
+  it("首次成功时直接返回结果", async () => {
+    const fn = vi.fn().mockResolvedValue("ok");
+    const signal = new AbortController().signal;
+    const result = await withRetry(fn, signal, 3, immediateDelay);
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("429 错误应重试直到成功", async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("HTTP 429 Too Many Requests"))
+      .mockRejectedValueOnce(new Error("HTTP 429 Too Many Requests"))
+      .mockResolvedValue("ok");
+    const signal = new AbortController().signal;
+
+    const result = await withRetry(fn, signal, 3, immediateDelay);
+
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(3);
+  });
+
+  it("超过最大重试次数后抛出最后的错误", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("HTTP 429 Too Many Requests"));
+    const signal = new AbortController().signal;
+
+    await expect(withRetry(fn, signal, 3, immediateDelay)).rejects.toThrow("429");
+    // 1 次首次尝试 + 3 次重试 = 4 次
+    expect(fn).toHaveBeenCalledTimes(4);
+  });
+
+  it("401 错误不重试，直接抛出", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("401 Unauthorized"));
+    const signal = new AbortController().signal;
+
+    await expect(withRetry(fn, signal, 3, immediateDelay)).rejects.toThrow("401");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("pre-abort 时不调用 fn，直接抛出", async () => {
+    const ac = new AbortController();
+    ac.abort();
+
+    const fn = vi.fn().mockResolvedValue("ok");
+
+    await expect(withRetry(fn, ac.signal, 3, immediateDelay)).rejects.toThrow();
+    // 信号已 abort，循环开头立即退出，fn 从未被调用
+    expect(fn).toHaveBeenCalledTimes(0);
+  });
+
+  it("fn 内 abort 后不再重试", async () => {
+    const ac = new AbortController();
+    // fn 执行时同步 abort，模拟外部取消
+    const fn = vi.fn().mockImplementation(() => {
+      ac.abort();
+      return Promise.reject(new Error("HTTP 500"));
+    });
+
+    await expect(withRetry(fn, ac.signal, 3, immediateDelay)).rejects.toThrow();
+    // fn 被调用一次后 abort，catch 分支检测到 signal.aborted，立即抛出不再重试
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("500 错误重试后成功", async () => {
+    const fn = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("HTTP 500 Internal Server Error"))
+      .mockResolvedValue("recovered");
+    const signal = new AbortController().signal;
+
+    const result = await withRetry(fn, signal, 3, immediateDelay);
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ---- classifyErrorCode ----
+
+describe("classifyErrorCode", () => {
+  it("429 应分类为 rate_limit", () => {
+    expect(classifyErrorCode(new Error("HTTP 429 Too Many Requests"))).toBe("rate_limit");
+  });
+
+  it("401 应分类为 auth", () => {
+    expect(classifyErrorCode(new Error("401 Unauthorized"))).toBe("auth");
+  });
+
+  it("403 应分类为 auth", () => {
+    expect(classifyErrorCode(new Error("403 Forbidden"))).toBe("auth");
+  });
+
+  it("消息含 timed out 应分类为 tool_timeout", () => {
+    expect(classifyErrorCode(new Error('CATTool "foo" timed out after 30s'))).toBe("tool_timeout");
+  });
+
+  it("errorCode 属性为 tool_timeout 应分类为 tool_timeout", () => {
+    const e = Object.assign(new Error("execution failed"), { errorCode: "tool_timeout" });
+    expect(classifyErrorCode(e)).toBe("tool_timeout");
+  });
+
+  it("其他错误应分类为 api_error", () => {
+    expect(classifyErrorCode(new Error("500 Internal Server Error"))).toBe("api_error");
+    expect(classifyErrorCode(new Error("Unknown error"))).toBe("api_error");
+  });
+});
+
+// ---- handleConversationChat skipSaveUserMessage（重新生成 bug 修复验证）----
+
+describe("handleConversationChat skipSaveUserMessage", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  function createMockSender() {
+    const sentMessages: any[] = [];
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: vi.fn(),
+      onDisconnect: vi.fn(),
+    };
+    const sender = {
+      isType: (type: any) => type === 1, // GetSenderType.CONNECT
+      getConnect: () => mockConn,
+    };
+    return { sender, sentMessages };
+  }
+
+  // 创建最简单的 OpenAI SSE 响应（纯文本，无 tool call）
+  function makeTextResponse(text: string): Response {
+    const encoder = new TextEncoder();
+    const chunks = [
+      `data: {"choices":[{"delta":{"content":"${text}"}}]}\n\n`,
+      `data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n`,
+    ];
+    let i = 0;
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => ({
+          read: async () => {
+            if (i >= chunks.length) return { done: true, value: undefined };
+            return { done: false, value: encoder.encode(chunks[i++]) };
+          },
+          releaseLock: () => {},
+          cancel: async () => {},
+          closed: Promise.resolve(undefined),
+        }),
+      },
+      text: async () => "",
+    } as unknown as Response;
+  }
+
+  // 已存在于 storage 中的用户消息（模拟重新生成场景）
+  const EXISTING_USER_MSG = {
+    id: "existing-u1",
+    conversationId: "conv-1",
+    role: "user" as const,
+    content: "你好",
+    createtime: 1000,
+  };
+
+  const BASE_CONV = {
+    id: "conv-1",
+    title: "Test",
+    modelId: "test-openai",
+    createtime: Date.now(),
+    updatetime: Date.now(),
+  };
+
+  it("【默认行为】不传 skipSaveUserMessage：用户消息应被保存到 storage", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]); // 空历史
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("你好！"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "你好", modelId: "test-openai" },
+      sender
+    );
+
+    const appendCalls: any[][] = mockRepo.appendMessage.mock.calls;
+    const userCall = appendCalls.find((c) => c[0].role === "user");
+    expect(userCall).toBeDefined();
+    expect(userCall![0].content).toBe("你好");
+  });
+
+  it("【bug 回归】skipSaveUserMessage=true：用户消息不应再次保存到 storage", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    // storage 中已有用户消息（重新生成场景）
+    mockRepo.getMessages.mockResolvedValue([EXISTING_USER_MSG]);
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("你好！"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "你好", modelId: "test-openai", skipSaveUserMessage: true },
+      sender
+    );
+
+    const appendCalls: any[][] = mockRepo.appendMessage.mock.calls;
+    // user 角色消息不应被再次保存
+    const userCall = appendCalls.find((c) => c[0].role === "user");
+    expect(userCall).toBeUndefined();
+
+    // assistant 回复仍应被保存
+    const assistantCall = appendCalls.find((c) => c[0].role === "assistant");
+    expect(assistantCall).toBeDefined();
+    expect(assistantCall![0].content).toBe("你好！");
+  });
+
+  it("【bug 回归】skipSaveUserMessage=true：LLM 请求中用户消息不应出现两次", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    // storage 中已有用户消息
+    mockRepo.getMessages.mockResolvedValue([EXISTING_USER_MSG]);
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("你好！"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "你好", modelId: "test-openai", skipSaveUserMessage: true },
+      sender
+    );
+
+    // 检查发往 LLM 的请求 body
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const requestBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    const userMessages = requestBody.messages.filter((m: any) => m.role === "user");
+
+    // 用户消息只应出现一次（来自 existingMessages，不应被重复追加）
+    expect(userMessages).toHaveLength(1);
+    expect(userMessages[0].content).toBe("你好");
+  });
+
+  it("skipSaveUserMessage=false（默认）：LLM 收到 user message（来自 params.message 追加）", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]); // 空历史
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("你好！"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "你好", modelId: "test-openai" },
+      sender
+    );
+
+    const requestBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    const userMessages = requestBody.messages.filter((m: any) => m.role === "user");
+
+    // 历史为空时，用户消息应来自 params.message 追加，只出现一次
+    expect(userMessages).toHaveLength(1);
+    expect(userMessages[0].content).toBe("你好");
+  });
+
+  it("skipSaveUserMessage=true：对话标题不应被更新（用户消息已在历史中）", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    const conv = { ...BASE_CONV, title: "New Chat" };
+    mockRepo.listConversations.mockResolvedValue([conv]);
+    // existingMessages 非空 → 标题更新条件（length === 0）不满足
+    mockRepo.getMessages.mockResolvedValue([EXISTING_USER_MSG]);
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("你好！"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "你好", modelId: "test-openai", skipSaveUserMessage: true },
+      sender
+    );
+
+    // saveConversation 不应以更新标题为目的被调用（title 仍应为 "New Chat"）
+    const saveConvCalls: any[][] = mockRepo.saveConversation.mock.calls;
+    const titleUpdated = saveConvCalls.some((c) => c[0].title !== "New Chat");
+    expect(titleUpdated).toBe(false);
+  });
+
+  it("多轮对话中 skipSaveUserMessage=true：历史消息完整传入 LLM", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    // 两轮历史 + 第三条用户消息待重新生成
+    mockRepo.getMessages.mockResolvedValue([
+      { id: "u1", conversationId: "conv-1", role: "user", content: "第一条", createtime: 1000 },
+      { id: "a1", conversationId: "conv-1", role: "assistant", content: "回复一", createtime: 1001 },
+      { id: "u2", conversationId: "conv-1", role: "user", content: "第二条", createtime: 1002 },
+    ]);
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("回复二"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "第二条", modelId: "test-openai", skipSaveUserMessage: true },
+      sender
+    );
+
+    const requestBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    // 过滤 system 消息
+    const nonSystem = requestBody.messages.filter((m: any) => m.role !== "system");
+
+    // 应有 user("第一条"), assistant("回复一"), user("第二条") — 共 3 条，无重复
+    expect(nonSystem).toHaveLength(3);
+    expect(nonSystem[0]).toMatchObject({ role: "user", content: "第一条" });
+    expect(nonSystem[1]).toMatchObject({ role: "assistant", content: "回复一" });
+    expect(nonSystem[2]).toMatchObject({ role: "user", content: "第二条" });
+  });
+});
+
+// ---- callLLM 相关测试（通过 callLLMWithToolLoop 间接测试） ----
+
+describe("callLLM 流式响应解析", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  // 辅助：创建 OpenAI SSE Response
+  function makeSSEResponse(chunks: string[]): Response {
+    const encoder = new TextEncoder();
+    let i = 0;
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => ({
+          read: async () => {
+            if (i >= chunks.length) return { done: true, value: undefined };
+            return { done: false, value: encoder.encode(chunks[i++]) };
+          },
+          releaseLock: () => {},
+          cancel: async () => {},
+          closed: Promise.resolve(undefined),
+        }),
+      },
+      text: async () => "",
+    } as unknown as Response;
+  }
+
+  // 辅助：创建 Anthropic SSE Response
+  function makeAnthropicSSEResponse(events: Array<{ event: string; data: any }>): Response {
+    const encoder = new TextEncoder();
+    const chunks = events.map((e) => `event: ${e.event}\ndata: ${JSON.stringify(e.data)}\n\n`);
+    let i = 0;
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => ({
+          read: async () => {
+            if (i >= chunks.length) return { done: true, value: undefined };
+            return { done: false, value: encoder.encode(chunks[i++]) };
+          },
+          releaseLock: () => {},
+          cancel: async () => {},
+          closed: Promise.resolve(undefined),
+        }),
+      },
+      text: async () => "",
+    } as unknown as Response;
+  }
+
+  function createMockSender() {
+    const sentMessages: any[] = [];
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: vi.fn(),
+      onDisconnect: vi.fn(),
+    };
+    const sender = {
+      isType: (type: any) => type === 1,
+      getConnect: () => mockConn,
+    };
+    return { sender, sentMessages };
+  }
+
+  const BASE_CONV = {
+    id: "conv-1",
+    title: "Test",
+    modelId: "test-openai",
+    createtime: Date.now(),
+    updatetime: Date.now(),
+  };
+
+  it("正常文本响应：OpenAI SSE → sendEvent 收到 content_delta + done", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    fetchSpy.mockResolvedValueOnce(
+      makeSSEResponse([
+        `data: {"choices":[{"delta":{"content":"你好"}}]}\n\n`,
+        `data: {"choices":[{"delta":{"content":"世界"}}]}\n\n`,
+        `data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n`,
+      ])
+    );
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "hi" }, sender);
+
+    const events = sentMessages.map((m) => m.data);
+    const contentDeltas = events.filter((e: any) => e.type === "content_delta");
+    const doneEvents = events.filter((e: any) => e.type === "done");
+
+    expect(contentDeltas.length).toBeGreaterThanOrEqual(1);
+    expect(doneEvents).toHaveLength(1);
+    expect(doneEvents[0].usage).toBeDefined();
+    expect(doneEvents[0].usage.inputTokens).toBe(10);
+    expect(doneEvents[0].usage.outputTokens).toBe(5);
+  });
+
+  it("正常文本响应（Anthropic provider）：验证 buildAnthropicRequest + parseAnthropicStream", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    // 设置 Anthropic model
+    const anthropicModelRepo = {
+      listModels: vi.fn().mockResolvedValue([
+        {
+          id: "test-anthropic",
+          name: "Claude",
+          provider: "anthropic",
+          apiBaseUrl: "https://api.anthropic.com",
+          apiKey: "sk-test",
+          model: "claude-3",
+        },
+      ]),
+      getModel: vi.fn().mockImplementation((id: string) => {
+        if (id === "test-anthropic") {
+          return Promise.resolve({
+            id: "test-anthropic",
+            name: "Claude",
+            provider: "anthropic",
+            apiBaseUrl: "https://api.anthropic.com",
+            apiKey: "sk-test",
+            model: "claude-3",
+          });
+        }
+        return Promise.resolve(undefined);
+      }),
+      getDefaultModelId: vi.fn().mockResolvedValue("test-anthropic"),
+      saveModel: vi.fn(),
+      removeModel: vi.fn(),
+      setDefaultModelId: vi.fn(),
+    };
+    (service as any).modelRepo = anthropicModelRepo;
+
+    const conv = { ...BASE_CONV, modelId: "test-anthropic" };
+    mockRepo.listConversations.mockResolvedValue([conv]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    fetchSpy.mockResolvedValueOnce(
+      makeAnthropicSSEResponse([
+        { event: "message_start", data: { message: { usage: { input_tokens: 15 } } } },
+        { event: "content_block_start", data: { content_block: { type: "text", text: "" } } },
+        { event: "content_block_delta", data: { delta: { type: "text_delta", text: "你好世界" } } },
+        { event: "message_delta", data: { usage: { output_tokens: 8 } } },
+      ])
+    );
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "hi" }, sender);
+
+    // 验证请求使用了 Anthropic 格式
+    const reqInit = fetchSpy.mock.calls[0][1];
+    expect(reqInit.headers["x-api-key"]).toBe("sk-test");
+    expect(fetchSpy.mock.calls[0][0]).toContain("/v1/messages");
+
+    const events = sentMessages.map((m) => m.data);
+    const contentDeltas = events.filter((e: any) => e.type === "content_delta");
+    const doneEvents = events.filter((e: any) => e.type === "done");
+    expect(contentDeltas).toHaveLength(1);
+    expect(contentDeltas[0].delta).toBe("你好世界");
+    expect(doneEvents).toHaveLength(1);
+    expect(doneEvents[0].usage.inputTokens).toBe(15);
+    expect(doneEvents[0].usage.outputTokens).toBe(8);
+  });
+
+  it("API 错误响应（HTTP 401）：sendEvent 收到 error + errorCode=auth", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    // 返回 401 错误，errorText 非 JSON 使消息包含 "401"（classifyErrorCode 靠正则匹配）
+    fetchSpy.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      text: async () => "401 Unauthorized",
+    } as unknown as Response);
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "hi" }, sender);
+
+    const events = sentMessages.map((m) => m.data);
+    const errorEvents = events.filter((e: any) => e.type === "error");
+    expect(errorEvents).toHaveLength(1);
+    expect(errorEvents[0].errorCode).toBe("auth");
+  });
+
+  it("API 错误响应（HTTP 500 后重试成功）：withRetry 生效", async () => {
+    vi.useFakeTimers();
+
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    // 第一次 500 错误
+    fetchSpy.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      text: async () => "Internal Server Error",
+    } as unknown as Response);
+
+    // 第二次成功
+    fetchSpy.mockResolvedValueOnce(
+      makeSSEResponse([
+        `data: {"choices":[{"delta":{"content":"恢复了"}}]}\n\n`,
+        `data: {"usage":{"prompt_tokens":10,"completion_tokens":3}}\n\n`,
+      ])
+    );
+
+    const chatPromise = (service as any).handleConversationChat({ conversationId: "conv-1", message: "hi" }, sender);
+
+    // 推进定时器跳过 withRetry 的退避延迟
+    await vi.advanceTimersByTimeAsync(10_000);
+
+    await chatPromise;
+
+    // fetch 应被调用 2 次（500 + 成功）
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+    const events = sentMessages.map((m) => m.data);
+    const doneEvents = events.filter((e: any) => e.type === "done");
+    expect(doneEvents).toHaveLength(1);
+
+    vi.useRealTimers();
+  });
+
+  it("无 response body：抛出 No response body", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    fetchSpy.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: null,
+      text: async () => "",
+    } as unknown as Response);
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "hi" }, sender);
+
+    const events = sentMessages.map((m) => m.data);
+    const errorEvents = events.filter((e: any) => e.type === "error");
+    expect(errorEvents).toHaveLength(1);
+    expect(errorEvents[0].message).toContain("No response body");
+  });
+
+  it("AbortSignal 中止：disconnect 后不再发送消息", async () => {
+    const { service, mockRepo } = createTestService();
+    const sentMessages: any[] = [];
+    let disconnectCb: (() => void) | null = null;
+
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: vi.fn(),
+      onDisconnect: vi.fn().mockImplementation((cb: () => void) => {
+        disconnectCb = cb;
+      }),
+    };
+    const sender = {
+      isType: (type: any) => type === 1,
+      getConnect: () => mockConn,
+    };
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    // fetch 抛 AbortError（模拟 signal 取消 fetch）
+    fetchSpy.mockImplementation((_url: string, _init: RequestInit) => {
+      // 在 fetch 调用时立即触发 disconnect
+      if (disconnectCb) {
+        disconnectCb();
+        disconnectCb = null;
+      }
+      // 模拟 abort 导致 fetch reject
+      return Promise.reject(new DOMException("The operation was aborted", "AbortError"));
+    });
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "hi" }, sender);
+
+    // abort 后 handleConversationChat 检测到 signal.aborted，静默返回
+    const events = sentMessages.map((m) => m.data);
+    // 不应有 error 事件（abort 不算 error）
+    const errorEvents = events.filter((e: any) => e.type === "error");
+    expect(errorEvents).toHaveLength(0);
+    // 不应有 done 事件
+    const doneEvents = events.filter((e: any) => e.type === "done");
+    expect(doneEvents).toHaveLength(0);
+  });
+});
+
+// ---- callLLMWithToolLoop 场景补充 ----
+
+describe("callLLMWithToolLoop 工具调用循环", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  function makeSSEResponse(chunks: string[]): Response {
+    const encoder = new TextEncoder();
+    let i = 0;
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => ({
+          read: async () => {
+            if (i >= chunks.length) return { done: true, value: undefined };
+            return { done: false, value: encoder.encode(chunks[i++]) };
+          },
+          releaseLock: () => {},
+          cancel: async () => {},
+          closed: Promise.resolve(undefined),
+        }),
+      },
+      text: async () => "",
+    } as unknown as Response;
+  }
+
+  function makeToolCallResponse(toolCalls: Array<{ id: string; name: string; arguments: string }>): Response {
+    const chunks: string[] = [];
+    for (const tc of toolCalls) {
+      chunks.push(
+        `data: {"choices":[{"delta":{"tool_calls":[{"id":"${tc.id}","function":{"name":"${tc.name}","arguments":""}}]}}]}\n\n`
+      );
+      chunks.push(
+        `data: {"choices":[{"delta":{"tool_calls":[{"function":{"arguments":${JSON.stringify(tc.arguments)}}}]}}]}\n\n`
+      );
+    }
+    chunks.push(`data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n`);
+    return makeSSEResponse(chunks);
+  }
+
+  function makeTextResponse(text: string): Response {
+    return makeSSEResponse([
+      `data: {"choices":[{"delta":{"content":"${text}"}}]}\n\n`,
+      `data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n`,
+    ]);
+  }
+
+  function createMockSender() {
+    const sentMessages: any[] = [];
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: vi.fn(),
+      onDisconnect: vi.fn(),
+    };
+    const sender = {
+      isType: (type: any) => type === 1,
+      getConnect: () => mockConn,
+    };
+    return { sender, sentMessages };
+  }
+
+  const BASE_CONV = {
+    id: "conv-1",
+    title: "Test",
+    modelId: "test-openai",
+    createtime: Date.now(),
+    updatetime: Date.now(),
+  };
+
+  it("工具调用单轮：tool_call → 执行 → 文本完成", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    // 注册一个内置工具
+    const registry = (service as any).toolRegistry;
+    registry.registerBuiltin(
+      { name: "echo", description: "Echo", parameters: { type: "object", properties: { msg: { type: "string" } } } },
+      { execute: async (args: Record<string, unknown>) => `echo: ${args.msg}` }
+    );
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    // 第一次：返回 tool_call
+    fetchSpy.mockResolvedValueOnce(
+      makeToolCallResponse([{ id: "call_1", name: "echo", arguments: '{"msg":"hello"}' }])
+    );
+    // 第二次：纯文本
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("done"));
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "test" }, sender);
+
+    const events = sentMessages.map((m) => m.data);
+    // 应有 tool_call_start, tool_call_complete, new_message, done
+    expect(events.some((e: any) => e.type === "tool_call_start")).toBe(true);
+    expect(events.some((e: any) => e.type === "tool_call_complete")).toBe(true);
+    const completeEvent = events.find((e: any) => e.type === "tool_call_complete");
+    expect(completeEvent.result).toBe("echo: hello");
+    expect(events.some((e: any) => e.type === "new_message")).toBe(true);
+    expect(events.some((e: any) => e.type === "done")).toBe(true);
+
+    // assistant 消息应持久化（tool_calls 和最终文本各一条）
+    const appendCalls = mockRepo.appendMessage.mock.calls;
+    const assistantCalls = appendCalls.filter((c: any) => c[0].role === "assistant");
+    expect(assistantCalls).toHaveLength(2); // tool_call + final text
+
+    // fetch 应调用 2 次
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+
+    registry.unregisterBuiltin("echo");
+  });
+
+  it("工具调用多轮（3 轮）：连续 tool_call 后文本", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    const registry = (service as any).toolRegistry;
+    let callCount = 0;
+    registry.registerBuiltin(
+      { name: "counter", description: "Count", parameters: { type: "object", properties: {} } },
+      {
+        execute: async () => {
+          callCount++;
+          return `count=${callCount}`;
+        },
+      }
+    );
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    // 3 轮 tool_call
+    fetchSpy.mockResolvedValueOnce(makeToolCallResponse([{ id: "c1", name: "counter", arguments: "{}" }]));
+    fetchSpy.mockResolvedValueOnce(makeToolCallResponse([{ id: "c2", name: "counter", arguments: "{}" }]));
+    fetchSpy.mockResolvedValueOnce(makeToolCallResponse([{ id: "c3", name: "counter", arguments: "{}" }]));
+    // 最终文本
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("done"));
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "test" }, sender);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+    expect(callCount).toBe(3);
+
+    const events = sentMessages.map((m) => m.data);
+    const doneEvents = events.filter((e: any) => e.type === "done");
+    expect(doneEvents).toHaveLength(1);
+    // done 事件 usage 应累计 4 轮
+    expect(doneEvents[0].usage.inputTokens).toBe(40); // 10 * 4
+    expect(doneEvents[0].usage.outputTokens).toBe(20); // 5 * 4
+
+    registry.unregisterBuiltin("counter");
+  });
+
+  it("超过 maxIterations：sendEvent 收到 max_iterations 错误", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    const registry = (service as any).toolRegistry;
+    registry.registerBuiltin(
+      { name: "loop", description: "Loop", parameters: { type: "object", properties: {} } },
+      { execute: async () => "ok" }
+    );
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+
+    // maxIterations=1 但 LLM 一直返回 tool_call
+    fetchSpy.mockResolvedValueOnce(makeToolCallResponse([{ id: "c1", name: "loop", arguments: "{}" }]));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "test", maxIterations: 1 },
+      sender
+    );
+
+    const events = sentMessages.map((m) => m.data);
+    const errorEvents = events.filter((e: any) => e.type === "error");
+    expect(errorEvents).toHaveLength(1);
+    expect(errorEvents[0].message).toContain("maximum iterations");
+    expect(errorEvents[0].errorCode).toBe("max_iterations");
+
+    // fetch 只调用 1 次（maxIterations=1）
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+    registry.unregisterBuiltin("loop");
+  });
+
+  it("工具执行后附件回写：toolCalls 被更新", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    const registry = (service as any).toolRegistry;
+    // 注册返回带附件结果的工具
+    registry.registerBuiltin(
+      { name: "screenshot", description: "Screenshot", parameters: { type: "object", properties: {} } },
+      {
+        execute: async () => ({
+          content: "Screenshot taken",
+          attachments: [{ type: "image", name: "shot.png", mimeType: "image/png", data: "base64data" }],
+        }),
+      }
+    );
+    // 注入 mock chatRepo 到 registry 用于保存附件
+    registry.setChatRepo({
+      saveAttachment: vi.fn().mockResolvedValue(1024),
+    });
+
+    mockRepo.listConversations.mockResolvedValue([BASE_CONV]);
+    mockRepo.getMessages.mockResolvedValue([]);
+    // appendMessage 后 getMessages 返回含 toolCalls 的 assistant 消息
+    const storedMessages: any[] = [];
+    mockRepo.appendMessage.mockImplementation(async (msg: any) => {
+      storedMessages.push(msg);
+    });
+    mockRepo.getMessages.mockImplementation(async () => [...storedMessages]);
+
+    // 第一次：tool_call
+    fetchSpy.mockResolvedValueOnce(makeToolCallResponse([{ id: "sc1", name: "screenshot", arguments: "{}" }]));
+    // 第二次：文本
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("done"));
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "截图" }, sender);
+
+    const events = sentMessages.map((m) => m.data);
+    const completeEvent = events.find((e: any) => e.type === "tool_call_complete");
+    expect(completeEvent).toBeDefined();
+    expect(completeEvent.result).toBe("Screenshot taken");
+    expect(completeEvent.attachments).toHaveLength(1);
+    expect(completeEvent.attachments[0].type).toBe("image");
+
+    registry.unregisterBuiltin("screenshot");
+  });
+});
+
+// ---- handleConversationChat 场景补充 ----
+
+describe("handleConversationChat 场景补充", () => {
+  let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  function makeSSEResponse(chunks: string[]): Response {
+    const encoder = new TextEncoder();
+    let i = 0;
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        getReader: () => ({
+          read: async () => {
+            if (i >= chunks.length) return { done: true, value: undefined };
+            return { done: false, value: encoder.encode(chunks[i++]) };
+          },
+          releaseLock: () => {},
+          cancel: async () => {},
+          closed: Promise.resolve(undefined),
+        }),
+      },
+      text: async () => "",
+    } as unknown as Response;
+  }
+
+  function makeTextResponse(text: string): Response {
+    return makeSSEResponse([
+      `data: {"choices":[{"delta":{"content":"${text}"}}]}\n\n`,
+      `data: {"usage":{"prompt_tokens":10,"completion_tokens":5}}\n\n`,
+    ]);
+  }
+
+  function createMockSender() {
+    const sentMessages: any[] = [];
+    const mockConn = {
+      sendMessage: (msg: any) => sentMessages.push(msg),
+      onMessage: vi.fn(),
+      onDisconnect: vi.fn(),
+    };
+    const sender = {
+      isType: (type: any) => type === 1,
+      getConnect: () => mockConn,
+    };
+    return { sender, sentMessages };
+  }
+
+  it("对话标题自动更新：第一条消息时 title 从 New Chat 变成消息截断", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    const conv = {
+      id: "conv-1",
+      title: "New Chat",
+      modelId: "test-openai",
+      createtime: Date.now(),
+      updatetime: Date.now(),
+    };
+    mockRepo.listConversations.mockResolvedValue([conv]);
+    mockRepo.getMessages.mockResolvedValue([]); // 空历史 → 第一条消息
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("ok"));
+
+    // 使用超过 30 个字符的消息（中文和英文混合确保超过 30 字符）
+    const longMessage = "This is a very long message that is used for testing title truncation behavior";
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: longMessage }, sender);
+
+    // saveConversation 应被调用，标题为截断后的消息
+    const saveCalls = mockRepo.saveConversation.mock.calls;
+    const titleUpdate = saveCalls.find((c: any) => c[0].title !== "New Chat");
+    expect(titleUpdate).toBeDefined();
+    expect(titleUpdate![0].title).toBe(longMessage.slice(0, 30) + "...");
+  });
+
+  it("ephemeral 模式：不走 repo 持久化", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("ephemeral reply"));
+
+    await (service as any).handleConversationChat(
+      {
+        conversationId: "eph-1",
+        message: "hi",
+        ephemeral: true,
+        messages: [{ role: "user", content: "hi" }],
+        system: "You are a helper.",
+      },
+      sender
+    );
+
+    // ephemeral 模式不应查询 conversation
+    expect(mockRepo.listConversations).not.toHaveBeenCalled();
+    // 不应持久化消息
+    expect(mockRepo.appendMessage).not.toHaveBeenCalled();
+
+    // 但应收到 done 事件
+    const events = sentMessages.map((m) => m.data);
+    expect(events.some((e: any) => e.type === "done")).toBe(true);
+  });
+
+  it("modelId 覆盖：传入新 modelId 时更新 conversation", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    // 添加第二个 model
+    const modelRepo = (service as any).modelRepo;
+    modelRepo.getModel.mockImplementation((id: string) => {
+      if (id === "test-openai")
+        return Promise.resolve({
+          id: "test-openai",
+          name: "Test",
+          provider: "openai",
+          apiBaseUrl: "",
+          apiKey: "",
+          model: "gpt-4o",
+        });
+      if (id === "test-openai-2")
+        return Promise.resolve({
+          id: "test-openai-2",
+          name: "Test2",
+          provider: "openai",
+          apiBaseUrl: "",
+          apiKey: "",
+          model: "gpt-4o-mini",
+        });
+      return Promise.resolve(undefined);
+    });
+
+    const conv = {
+      id: "conv-1",
+      title: "Test",
+      modelId: "test-openai",
+      createtime: Date.now(),
+      updatetime: Date.now(),
+    };
+    mockRepo.listConversations.mockResolvedValue([conv]);
+    mockRepo.getMessages.mockResolvedValue([]);
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("ok"));
+
+    await (service as any).handleConversationChat(
+      { conversationId: "conv-1", message: "hi", modelId: "test-openai-2" },
+      sender
+    );
+
+    // conversation 应被保存，modelId 更新为 test-openai-2
+    const saveConvCalls = mockRepo.saveConversation.mock.calls;
+    const modelUpdate = saveConvCalls.find((c: any) => c[0].modelId === "test-openai-2");
+    expect(modelUpdate).toBeDefined();
+  });
+
+  it("conversation 不存在时 sendEvent error", async () => {
+    const { service, mockRepo } = createTestService();
+    const { sender, sentMessages } = createMockSender();
+
+    mockRepo.listConversations.mockResolvedValue([]); // 空
+
+    await (service as any).handleConversationChat({ conversationId: "not-exist", message: "hi" }, sender);
+
+    const events = sentMessages.map((m) => m.data);
+    const errorEvents = events.filter((e: any) => e.type === "error");
+    expect(errorEvents).toHaveLength(1);
+    expect(errorEvents[0].message).toContain("Conversation not found");
+  });
+
+  it("skill 动态加载：历史消息含 load_skill 调用时预加载 skill 工具", async () => {
+    const { service, mockRepo, mockSkillRepo } = createTestService();
+    const { sender } = createMockSender();
+
+    // 设置 skill
+    const skill = makeSkillRecord({
+      name: "web-skill",
+      toolNames: ["web-tool"],
+      prompt: "Web instructions.",
+    });
+    (service as any).skillCache.set("web-skill", skill);
+
+    const toolRecord = makeCATToolRecord({
+      name: "web-tool",
+      description: "Web tool",
+      params: [],
+    });
+    mockSkillRepo.getSkillScripts.mockResolvedValueOnce([toolRecord]);
+
+    const conv = {
+      id: "conv-1",
+      title: "Test",
+      modelId: "test-openai",
+      skills: "auto" as const,
+      createtime: Date.now(),
+      updatetime: Date.now(),
+    };
+    mockRepo.listConversations.mockResolvedValue([conv]);
+    // 历史中含 load_skill 调用
+    mockRepo.getMessages.mockResolvedValue([
+      {
+        id: "u1",
+        conversationId: "conv-1",
+        role: "user",
+        content: "帮我查网页",
+        createtime: 1000,
+      },
+      {
+        id: "a1",
+        conversationId: "conv-1",
+        role: "assistant",
+        content: "",
+        toolCalls: [{ id: "tc1", name: "load_skill", arguments: '{"skill_name":"web-skill"}' }],
+        createtime: 1001,
+      },
+      {
+        id: "t1",
+        conversationId: "conv-1",
+        role: "tool",
+        content: "Web instructions.",
+        toolCallId: "tc1",
+        createtime: 1002,
+      },
+    ]);
+    fetchSpy.mockResolvedValueOnce(makeTextResponse("ok"));
+
+    await (service as any).handleConversationChat({ conversationId: "conv-1", message: "继续" }, sender);
+
+    // getSkillScripts 应被调用以预加载 web-skill 的工具
+    expect(mockSkillRepo.getSkillScripts).toHaveBeenCalledWith("web-skill");
+
+    // 发送给 LLM 的工具列表应包含 web-skill__web-tool
+    const requestBody = JSON.parse(fetchSpy.mock.calls[0][1].body);
+    const toolNames = requestBody.tools?.map((t: any) => t.function?.name || t.name) || [];
+    expect(toolNames).toContain("web-skill__web-tool");
+  });
+});
+
+describe.concurrent("AgentService.handleDomApi", () => {
+  it.concurrent("应将请求转发到 domService.handleDomApi", async () => {
+    const { service } = createTestService();
+    const mockResult = [{ id: 1, title: "Test Tab", url: "https://example.com" }];
+    const mockHandleDomApi = vi.fn().mockResolvedValue(mockResult);
+    (service as any).domService = { handleDomApi: mockHandleDomApi };
+
+    const request = { action: "listTabs" as const, scriptUuid: "test" };
+    const result = await service.handleDomApi(request);
+
+    expect(mockHandleDomApi).toHaveBeenCalledWith(request);
+    expect(result).toEqual(mockResult);
+  });
+
+  it.concurrent("应正确传递 domService 的错误", async () => {
+    const { service } = createTestService();
+    const mockHandleDomApi = vi.fn().mockRejectedValue(new Error("DOM action failed"));
+    (service as any).domService = { handleDomApi: mockHandleDomApi };
+
+    await expect(service.handleDomApi({ action: "listTabs", scriptUuid: "test" })).rejects.toThrow("DOM action failed");
+  });
+});
diff --git a/src/app/service/service_worker/agent.ts b/src/app/service/service_worker/agent.ts
new file mode 100644
index 000000000..b0ea43d5f
--- /dev/null
+++ b/src/app/service/service_worker/agent.ts
@@ -0,0 +1,1635 @@
+import type { Group, IGetSender } from "@Packages/message/server";
+import { GetSenderType } from "@Packages/message/server";
+import type { MessageSend } from "@Packages/message/types";
+import type { AgentModelConfig } from "@App/app/service/agent/types";
+import type { Script } from "@App/app/repo/scripts";
+import { i18nName } from "@App/locales/locales";
+import type {
+  ChatRequest,
+  ChatStreamEvent,
+  ConversationApiRequest,
+  Conversation,
+  ToolCall,
+  ToolDefinition,
+  CATToolApiRequest,
+  CATToolRecord,
+  JsonValue,
+  DomApiRequest,
+  SkillApiRequest,
+  SkillMetadata,
+  SkillRecord,
+  SkillSummary,
+  MessageContent,
+  AgentTask,
+  AgentTaskApiRequest,
+  AgentTaskTrigger,
+  Attachment,
+} from "@App/app/service/agent/types";
+import { getTextContent, isContentBlocks } from "@App/app/service/agent/content_utils";
+import { buildOpenAIRequest, parseOpenAIStream } from "@App/app/service/agent/providers/openai";
+import { buildAnthropicRequest, parseAnthropicStream } from "@App/app/service/agent/providers/anthropic";
+import { AgentChatRepo } from "@App/app/repo/agent_chat";
+import { AgentModelRepo } from "@App/app/repo/agent_model";
+import { CATToolRepo, type CATToolSummary } from "@App/app/repo/cattool_repo";
+import { SkillRepo } from "@App/app/repo/skill_repo";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+import { ToolRegistry } from "@App/app/service/agent/tool_registry";
+import type { ScriptToolCallback, ToolExecutor } from "@App/app/service/agent/tool_registry";
+import { parseCATToolMetadata, catToolToToolDefinition, prefixToolDefinition } from "@App/pkg/utils/cattool";
+import { parseSkillMd, parseSkillZip } from "@App/pkg/utils/skill";
+import { CATToolExecutor } from "@App/app/service/agent/cattool_executor";
+import { CACHE_KEY_CATTOOL_INSTALL, CACHE_KEY_SKILL_INSTALL } from "@App/app/cache_key";
+import { buildSystemPrompt, SKILL_SUFFIX_HEADER } from "@App/app/service/agent/system_prompt";
+import { cacheInstance } from "@App/app/cache";
+import { AgentDomService } from "./agent_dom";
+import { MCPService } from "./agent_mcp";
+import { type ResourceService } from "./resource";
+import { AgentTaskRepo, AgentTaskRunRepo } from "@App/app/repo/agent_task";
+import { AgentTaskScheduler } from "@App/app/service/agent/task_scheduler";
+import { InfoNotification } from "./utils";
+import { nextTimeInfo } from "@App/pkg/utils/cron";
+import { sendMessage } from "@Packages/message/client";
+
+// 安装超时时间：5 分钟
+const CATTOOL_INSTALL_TIMEOUT = 5 * 60 * 1000;
+
+// 判断是否可重试（429 / 5xx / 网络错误，不含 4xx 客户端错误）
+export function isRetryableError(e: Error): boolean {
+  const msg = e.message;
+  return /429|5\d\d|network|fetch|ECONNRESET/i.test(msg) && !/40[0134]/.test(msg);
+}
+
+// 指数退避重试，aborted 时立即退出
+// delayFn 仅供测试注入，生产代码不传
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  signal: AbortSignal,
+  maxRetries = 3,
+  delayFn?: (ms: number, signal: AbortSignal) => Promise<void>
+): Promise<T> {
+  const wait =
+    delayFn ??
+    ((ms, sig) =>
+      new Promise<void>((r) => {
+        const t = setTimeout(r, ms);
+        sig.addEventListener(
+          "abort",
+          () => {
+            clearTimeout(t);
+            r();
+          },
+          { once: true }
+        );
+      }));
+
+  let lastError!: Error;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (signal.aborted) throw lastError ?? new Error("Aborted");
+    try {
+      return await fn();
+    } catch (e: any) {
+      if (signal.aborted) throw e;
+      lastError = e;
+      if (!isRetryableError(e) || attempt === maxRetries) throw e;
+      const delay = 1000 * Math.pow(2, attempt) + Math.random() * 1000;
+      await wait(delay, signal);
+    }
+  }
+  throw lastError;
+}
+
+// 将 Error 分类为 errorCode 字符串
+export function classifyErrorCode(e: Error): string {
+  const msg = e.message;
+  if (/429/.test(msg)) return "rate_limit";
+  if (/401|403/.test(msg)) return "auth";
+  if (/timed out/.test(msg) || (e as any).errorCode === "tool_timeout") return "tool_timeout";
+  return "api_error";
+}
+
+export class AgentService {
+  private repo = new AgentChatRepo();
+  private catToolRepo = new CATToolRepo();
+  private skillRepo = new SkillRepo();
+  private toolRegistry = new ToolRegistry();
+  // 已加载的 Skill 缓存
+  private skillCache = new Map<string, SkillRecord>();
+  // 待确认的 CATTool 安装请求
+  private pendingInstalls = new Map<
+    string,
+    {
+      resolve: (record: CATToolRecord) => void;
+      reject: (error: Error) => void;
+      tabId: number;
+      timer: ReturnType<typeof setTimeout>;
+      onTabRemoved: (tabId: number) => void;
+    }
+  >();
+
+  private modelRepo = new AgentModelRepo();
+  private domService = new AgentDomService();
+  private mcpService!: MCPService;
+  private taskRepo = new AgentTaskRepo();
+  private taskRunRepo = new AgentTaskRunRepo();
+  private taskScheduler!: AgentTaskScheduler;
+
+  constructor(
+    private group: Group,
+    private sender: MessageSend,
+    private resourceService?: ResourceService
+  ) {}
+
+  handleDomApi(request: DomApiRequest): Promise<unknown> {
+    return this.domService.handleDomApi(request);
+  }
+
+  init() {
+    // 注入 chatRepo 到 ToolRegistry 用于保存附件
+    this.toolRegistry.setChatRepo(this.repo);
+    // 初始化 MCP Service
+    this.mcpService = new MCPService(this.toolRegistry);
+    this.mcpService.init();
+    // Sandbox conversation API
+    this.group.on("conversation", this.handleConversation.bind(this));
+    // 流式聊天（UI 和 Sandbox 共用）
+    this.group.on("conversationChat", this.handleConversationChat.bind(this));
+    // 通过 install page 安装 CATTool（文件/URL 安装，无来源脚本）
+    this.group.on("installCATTool", (code: string) => this.installCATTool(code));
+    // CATTool 安装页面相关消息
+    this.group.on("getCATToolInstallCode", (uuid: string) => this.getCATToolInstallCode(uuid));
+    this.group.on("completeCATToolInstall", (uuid: string) => this.completeCATToolInstall(uuid));
+    this.group.on("cancelCATToolInstall", (uuid: string) => this.cancelCATToolInstall(uuid));
+    this.group.on("removeCATTool", (name: string) => this.removeCATTool(name));
+    // Skill 管理（供 Options UI 调用）
+    this.group.on(
+      "installSkill",
+      (params: {
+        skillMd: string;
+        scripts?: Array<{ name: string; code: string }>;
+        references?: Array<{ name: string; content: string }>;
+      }) => this.installSkill(params.skillMd, params.scripts, params.references)
+    );
+    this.group.on("removeSkill", (name: string) => this.removeSkill(name));
+    this.group.on("refreshSkill", (name: string) => this.refreshSkill(name));
+    this.group.on("getSkillConfigValues", (name: string) => this.skillRepo.getConfigValues(name));
+    this.group.on("saveSkillConfig", (params: { name: string; values: Record<string, unknown> }) =>
+      this.skillRepo.saveConfigValues(params.name, params.values)
+    );
+    // Skill ZIP 安装页面相关消息
+    this.group.on("prepareSkillInstall", (zipBase64: string) => this.prepareSkillInstall(zipBase64));
+    this.group.on("getSkillInstallData", (uuid: string) => this.getSkillInstallData(uuid));
+    this.group.on("completeSkillInstall", (uuid: string) => this.completeSkillInstall(uuid));
+    this.group.on("cancelSkillInstall", (uuid: string) => this.cancelSkillInstall(uuid));
+    // Agent 定时任务 API
+    this.group.on("agentTask", this.handleAgentTask.bind(this));
+    // 初始化定时任务调度器
+    this.taskScheduler = new AgentTaskScheduler(
+      this.taskRepo,
+      this.taskRunRepo,
+      (task) => this.executeInternalTask(task),
+      (task) => this.emitTaskEvent(task)
+    );
+    this.taskScheduler.init();
+    // 加载已安装的 CATTools
+    this.loadCATTools();
+    // 加载已安装的 Skills
+    this.loadSkills();
+  }
+
+  // 获取工具注册表（供外部注册内置工具）
+  getToolRegistry(): ToolRegistry {
+    return this.toolRegistry;
+  }
+
+  // 创建 require 资源加载器，从 ResourceDAO 缓存中读取已下载的资源内容
+  private createRequireLoader(): ((url: string) => Promise<string | undefined>) | undefined {
+    if (!this.resourceService) return undefined;
+    const rs = this.resourceService;
+    return async (url: string) => {
+      const res = await rs.getResource("cattool-require", url, "require", false);
+      return res?.content as string | undefined;
+    };
+  }
+
+  // 从 OPFS 加载所有 CATTool 并注册到 ToolRegistry
+  private async loadCATTools() {
+    try {
+      const summaries = await this.catToolRepo.listTools();
+      for (const summary of summaries) {
+        // 读取完整记录（含 code），CATToolExecutor 需要 code 执行
+        const tool = await this.catToolRepo.getTool(summary.name);
+        if (!tool) continue;
+        const def = catToolToToolDefinition({
+          name: tool.name,
+          description: tool.description,
+          params: tool.params,
+          grants: tool.grants,
+          requires: tool.requires || [],
+        });
+        this.toolRegistry.registerBuiltin(def, new CATToolExecutor(tool, this.sender, this.createRequireLoader()));
+      }
+    } catch {
+      // OPFS 可能在 SW 环境不可用，静默忽略
+    }
+  }
+
+  // 安装 CATTool
+  async installCATTool(code: string, sourceScriptUuid?: string, sourceScriptName?: string): Promise<CATToolRecord> {
+    const metadata = parseCATToolMetadata(code);
+    if (!metadata) {
+      throw new Error("Invalid CATTool: missing or malformed ==CATTool== header");
+    }
+
+    // 下载并缓存 @require 资源
+    if (metadata.requires.length > 0 && this.resourceService) {
+      const dummyUuid = "cattool-require";
+      await Promise.all(
+        metadata.requires.map((url) => this.resourceService!.getResource(dummyUuid, url, "require", true))
+      );
+    }
+
+    const now = Date.now();
+    const existing = await this.catToolRepo.getTool(metadata.name);
+    const record: CATToolRecord = {
+      id: existing?.id || uuidv4(),
+      name: metadata.name,
+      description: metadata.description,
+      params: metadata.params,
+      grants: metadata.grants,
+      requires: metadata.requires.length > 0 ? metadata.requires : undefined,
+      timeout: metadata.timeout,
+      code,
+      sourceScriptUuid: sourceScriptUuid || existing?.sourceScriptUuid,
+      sourceScriptName: sourceScriptName || existing?.sourceScriptName,
+      installtime: existing?.installtime || now,
+      updatetime: now,
+    };
+
+    await this.catToolRepo.saveTool(record);
+
+    // 注册/更新到 ToolRegistry
+    const def = catToolToToolDefinition(metadata);
+    this.toolRegistry.unregisterBuiltin(metadata.name);
+    this.toolRegistry.registerBuiltin(def, new CATToolExecutor(record, this.sender, this.createRequireLoader()));
+
+    return record;
+  }
+
+  // 卸载 CATTool
+  async removeCATTool(name: string): Promise<boolean> {
+    const removed = await this.catToolRepo.removeTool(name);
+    if (removed) {
+      this.toolRegistry.unregisterBuiltin(name);
+    }
+    return removed;
+  }
+
+  // 根据名称获取 CATTool 的 grants（供 GM API 权限验证使用）
+  async getCATToolGrants(name: string): Promise<string[]> {
+    const tool = await this.catToolRepo.getTool(name);
+    return tool?.grants || [];
+  }
+
+  // 直接调用 CATTool
+  async callCATTool(name: string, params: Record<string, unknown>): Promise<JsonValue> {
+    const tool = await this.catToolRepo.getTool(name);
+    if (!tool) {
+      throw new Error(`CATTool "${name}" not found`);
+    }
+    const executor = new CATToolExecutor(tool, this.sender, this.createRequireLoader());
+    return executor.execute(params);
+  }
+
+  // 打开安装页面让用户确认安装 CATTool
+  async openCATToolInstallPage(code: string, scriptUuid?: string, scriptName?: string): Promise<CATToolRecord> {
+    const uuid = uuidv4();
+    // 缓存代码和来源信息到 session storage
+    await cacheInstance.set(CACHE_KEY_CATTOOL_INSTALL + uuid, { code, scriptUuid, scriptName });
+    // 打开安装页面
+    const tab = await chrome.tabs.create({
+      url: `/src/install.html?cattool=${uuid}`,
+    });
+    if (!tab.id) {
+      await cacheInstance.del(CACHE_KEY_CATTOOL_INSTALL + uuid);
+      throw new Error("Failed to create install tab");
+    }
+    const tabId = tab.id;
+
+    return new Promise<CATToolRecord>((resolve, reject) => {
+      // 超时处理
+      const timer = setTimeout(() => {
+        this.cleanupPendingInstall(uuid);
+        reject(new Error("CATTool install timed out"));
+      }, CATTOOL_INSTALL_TIMEOUT);
+
+      // 监听 tab 关闭作为取消的 fallback
+      const onTabRemoved = (removedTabId: number) => {
+        if (removedTabId === tabId && this.pendingInstalls.has(uuid)) {
+          this.cleanupPendingInstall(uuid);
+          reject(new Error("CATTool install cancelled by user"));
+        }
+      };
+      chrome.tabs.onRemoved.addListener(onTabRemoved);
+
+      this.pendingInstalls.set(uuid, { resolve, reject, tabId, timer, onTabRemoved });
+    });
+  }
+
+  // 供安装页面获取缓存的 CATTool 安装信息
+  async getCATToolInstallCode(uuid: string): Promise<{
+    code: string;
+    scriptName?: string;
+    isUpdate?: boolean;
+  }> {
+    const cached = await cacheInstance.get<{ code: string; scriptUuid?: string; scriptName?: string }>(
+      CACHE_KEY_CATTOOL_INSTALL + uuid
+    );
+    if (!cached) {
+      throw new Error("CATTool install code not found or expired");
+    }
+    // 检查同名工具是否已存在
+    const metadata = parseCATToolMetadata(cached.code);
+    let isUpdate = false;
+    if (metadata) {
+      const existing = await this.catToolRepo.getTool(metadata.name);
+      if (existing) {
+        isUpdate = true;
+      }
+    }
+    return {
+      code: cached.code,
+      scriptName: cached.scriptName,
+      isUpdate,
+    };
+  }
+
+  // 安装页面通知安装完成
+  async completeCATToolInstall(uuid: string): Promise<void> {
+    const pending = this.pendingInstalls.get(uuid);
+    if (!pending) {
+      return;
+    }
+    try {
+      const cached = await cacheInstance.get<{ code: string; scriptUuid?: string; scriptName?: string }>(
+        CACHE_KEY_CATTOOL_INSTALL + uuid
+      );
+      if (!cached) {
+        throw new Error("CATTool install code not found or expired");
+      }
+      const record = await this.installCATTool(cached.code, cached.scriptUuid, cached.scriptName);
+      pending.resolve(record);
+    } catch (e: any) {
+      pending.reject(e);
+    } finally {
+      this.cleanupPendingInstall(uuid);
+    }
+  }
+
+  // 安装页面通知取消
+  async cancelCATToolInstall(uuid: string): Promise<void> {
+    const pending = this.pendingInstalls.get(uuid);
+    if (!pending) {
+      return;
+    }
+    try {
+      pending.reject(new Error("CATTool install cancelled by user"));
+    } finally {
+      await this.cleanupPendingInstall(uuid);
+    }
+  }
+
+  // 清理待确认安装的状态
+  private async cleanupPendingInstall(uuid: string) {
+    const pending = this.pendingInstalls.get(uuid);
+    if (pending) {
+      clearTimeout(pending.timer);
+      chrome.tabs.onRemoved.removeListener(pending.onTabRemoved);
+      this.pendingInstalls.delete(uuid);
+    }
+    await cacheInstance.del(CACHE_KEY_CATTOOL_INSTALL + uuid);
+  }
+
+  // 处理 CAT.agent.tools API 请求
+  async handleToolsApi(
+    request: CATToolApiRequest,
+    script?: Script
+  ): Promise<CATToolRecord | boolean | CATToolSummary[] | JsonValue> {
+    switch (request.action) {
+      case "install":
+        return this.openCATToolInstallPage(request.code, script?.uuid, script ? i18nName(script) : undefined);
+      case "remove":
+        return this.removeCATTool(request.name);
+      case "list":
+        return this.catToolRepo.listTools();
+      case "call":
+        return this.callCATTool(request.name, request.params);
+      default:
+        throw new Error(`Unknown tools action: ${(request as any).action}`);
+    }
+  }
+
+  // ---- Skill 管理 ----
+
+  // 从 OPFS 加载所有 Skill 到缓存
+  private async loadSkills() {
+    try {
+      const summaries = await this.skillRepo.listSkills();
+      for (const summary of summaries) {
+        const record = await this.skillRepo.getSkill(summary.name);
+        if (record) {
+          this.skillCache.set(record.name, record);
+        }
+      }
+    } catch {
+      // OPFS 可能不可用，静默忽略
+    }
+  }
+
+  // 安装 Skill
+  async installSkill(
+    skillMd: string,
+    scripts?: Array<{ name: string; code: string }>,
+    references?: Array<{ name: string; content: string }>
+  ): Promise<SkillRecord> {
+    const parsed = parseSkillMd(skillMd);
+    if (!parsed) {
+      throw new Error("Invalid SKILL.md: missing or malformed frontmatter");
+    }
+
+    // 解析 CATTool 脚本
+    const toolRecords: CATToolRecord[] = [];
+    const toolNames: string[] = [];
+    if (scripts) {
+      for (const script of scripts) {
+        const metadata = parseCATToolMetadata(script.code);
+        if (!metadata) {
+          throw new Error(`Invalid CATTool script "${script.name}": missing ==CATTool== header`);
+        }
+        // 下载并缓存 @require 资源
+        if (metadata.requires.length > 0 && this.resourceService) {
+          const dummyUuid = "cattool-require";
+          await Promise.all(
+            metadata.requires.map((url) => this.resourceService!.getResource(dummyUuid, url, "require", true))
+          );
+        }
+        toolNames.push(metadata.name);
+        const now = Date.now();
+        toolRecords.push({
+          id: uuidv4(),
+          name: metadata.name,
+          description: metadata.description,
+          params: metadata.params,
+          grants: metadata.grants,
+          requires: metadata.requires.length > 0 ? metadata.requires : undefined,
+          timeout: metadata.timeout,
+          code: script.code,
+          installtime: now,
+          updatetime: now,
+        });
+      }
+    }
+
+    const referenceNames = references?.map((r) => r.name) || [];
+
+    const now = Date.now();
+    const existing = await this.skillRepo.getSkill(parsed.metadata.name);
+    const record: SkillRecord = {
+      name: parsed.metadata.name,
+      description: parsed.metadata.description,
+      toolNames,
+      referenceNames,
+      prompt: parsed.prompt,
+      ...(parsed.metadata.config ? { config: parsed.metadata.config } : {}),
+      installtime: existing?.installtime || now,
+      updatetime: now,
+    };
+
+    const skillRefs = references?.map((r) => ({ name: r.name, content: r.content }));
+    await this.skillRepo.saveSkill(record, toolRecords, skillRefs);
+    this.skillCache.set(record.name, record);
+
+    return record;
+  }
+
+  // 卸载 Skill
+  async removeSkill(name: string): Promise<boolean> {
+    const removed = await this.skillRepo.removeSkill(name);
+    if (removed) {
+      this.skillCache.delete(name);
+    }
+    return removed;
+  }
+
+  // 刷新单个 Skill 缓存（从 OPFS 重新加载）
+  async refreshSkill(name: string): Promise<boolean> {
+    const record = await this.skillRepo.getSkill(name);
+    if (record) {
+      this.skillCache.set(record.name, record);
+      return true;
+    }
+    this.skillCache.delete(name);
+    return false;
+  }
+
+  // 缓存 Skill ZIP 数据，返回 uuid，供安装页面获取
+  async prepareSkillInstall(zipBase64: string): Promise<string> {
+    const uuid = uuidv4();
+    await cacheInstance.set(CACHE_KEY_SKILL_INSTALL + uuid, zipBase64);
+    return uuid;
+  }
+
+  // 获取缓存的 Skill ZIP 数据并解析
+  async getSkillInstallData(uuid: string): Promise<{
+    skillMd: string;
+    metadata: SkillMetadata;
+    prompt: string;
+    scripts: Array<{ name: string; code: string }>;
+    references: Array<{ name: string; content: string }>;
+    isUpdate: boolean;
+  }> {
+    const zipBase64 = await cacheInstance.get<string>(CACHE_KEY_SKILL_INSTALL + uuid);
+    if (!zipBase64) {
+      throw new Error("Skill install data not found or expired");
+    }
+    // base64 → ArrayBuffer
+    const binaryStr = atob(zipBase64);
+    const bytes = new Uint8Array(binaryStr.length);
+    for (let i = 0; i < binaryStr.length; i++) {
+      bytes[i] = binaryStr.charCodeAt(i);
+    }
+    const buffer = bytes.buffer;
+
+    const result = await parseSkillZip(buffer);
+    const parsed = parseSkillMd(result.skillMd);
+    if (!parsed) {
+      throw new Error("Invalid SKILL.md format in ZIP");
+    }
+    // 检查是否为更新
+    const existing = await this.skillRepo.getSkill(parsed.metadata.name);
+    return {
+      skillMd: result.skillMd,
+      metadata: parsed.metadata,
+      prompt: parsed.prompt,
+      scripts: result.scripts,
+      references: result.references,
+      isUpdate: !!existing,
+    };
+  }
+
+  // Skill 安装页面确认安装
+  async completeSkillInstall(uuid: string): Promise<SkillRecord> {
+    const data = await this.getSkillInstallData(uuid);
+    const record = await this.installSkill(data.skillMd, data.scripts, data.references);
+    await cacheInstance.del(CACHE_KEY_SKILL_INSTALL + uuid);
+    return record;
+  }
+
+  // Skill 安装页面取消
+  async cancelSkillInstall(uuid: string): Promise<void> {
+    await cacheInstance.del(CACHE_KEY_SKILL_INSTALL + uuid);
+  }
+
+  // 处理 CAT.agent.skills API 请求
+  async handleSkillsApi(request: SkillApiRequest): Promise<SkillSummary[] | SkillRecord | null | boolean> {
+    switch (request.action) {
+      case "list":
+        return this.skillRepo.listSkills();
+      case "get":
+        return this.skillRepo.getSkill(request.name);
+      case "install":
+        return this.installSkill(request.skillMd, request.scripts, request.references);
+      case "remove":
+        return this.removeSkill(request.name);
+      default:
+        throw new Error(`Unknown skills action: ${(request as any).action}`);
+    }
+  }
+
+  // 解析对话关联的 skills，返回 system prompt 附加内容和 meta-tool 定义
+  // 两层渐进加载：1) system prompt 只注入摘要 2) load_skill 按需加载完整提示词并动态注册 CATTool
+  private resolveSkills(skills?: "auto" | string[]): {
+    promptSuffix: string;
+    metaTools: Array<{ definition: ToolDefinition; executor: ToolExecutor }>;
+    // load_skill 动态注册的工具名引用，对话结束后需清理
+    dynamicToolNames: string[];
+  } {
+    if (!skills) {
+      return { promptSuffix: "", metaTools: [], dynamicToolNames: [] };
+    }
+
+    // 确定要加载的 skill 列表
+    let skillRecords: SkillRecord[];
+    if (skills === "auto") {
+      skillRecords = Array.from(this.skillCache.values());
+    } else {
+      skillRecords = skills.map((name) => this.skillCache.get(name)).filter((r): r is SkillRecord => r != null);
+    }
+
+    if (skillRecords.length === 0) {
+      return { promptSuffix: "", metaTools: [], dynamicToolNames: [] };
+    }
+
+    // 构建 prompt 后缀：只包含 name + description 摘要
+    const promptParts: string[] = [SKILL_SUFFIX_HEADER];
+
+    // 检查是否有任何参考资料
+    let hasReferences = false;
+
+    for (const skill of skillRecords) {
+      const toolHint = skill.toolNames.length > 0 ? ` (tools: ${skill.toolNames.join(", ")})` : "";
+      const refHint = skill.referenceNames.length > 0 ? ` [has references]` : "";
+      promptParts.push(`- **${skill.name}**: ${skill.description || "(no description)"}${toolHint}${refHint}`);
+      if (skill.referenceNames.length > 0) hasReferences = true;
+    }
+
+    // 构建 meta-tools
+    const metaTools: Array<{ definition: ToolDefinition; executor: ToolExecutor }> = [];
+
+    // load_skill 动态注册的工具名，对话结束后需清理
+    const dynamicToolNames: string[] = [];
+    // 已加载的 skill 名，避免重复加载和重复注册工具
+    const loadedSkills = new Set<string>();
+
+    // load_skill — 始终注册
+    metaTools.push({
+      definition: {
+        name: "load_skill",
+        description:
+          "Load a skill's full instructions and register its tools. MUST be called before using any skill. Returns the skill's detailed prompt; the skill's CATTools become callable as `skillname__toolname`.",
+        parameters: {
+          type: "object",
+          properties: {
+            skill_name: { type: "string", description: "Name of the skill to load" },
+          },
+          required: ["skill_name"],
+        },
+      },
+      executor: {
+        execute: async (args: Record<string, unknown>) => {
+          const skillName = args.skill_name as string;
+          const record = this.skillCache.get(skillName);
+          if (!record) {
+            throw new Error(`Skill "${skillName}" not found`);
+          }
+          // 已加载过则直接返回 prompt，跳过工具注册
+          if (loadedSkills.has(skillName)) {
+            return record.prompt;
+          }
+          loadedSkills.add(skillName);
+          // 动态注册该 skill 的 CATTool 为独立 LLM tool
+          if (record.toolNames.length > 0) {
+            const toolRecords = await this.skillRepo.getSkillScripts(skillName);
+            // 读取 skill 的用户配置值（如 API Key 等），注入到每个 CATTool 执行器
+            const configValues = record.config ? await this.skillRepo.getConfigValues(skillName) : undefined;
+            for (const tool of toolRecords) {
+              const def = catToolToToolDefinition({
+                name: tool.name,
+                description: tool.description,
+                params: tool.params,
+                grants: tool.grants,
+                requires: tool.requires || [],
+              });
+              const prefixed = prefixToolDefinition(skillName, def);
+              this.toolRegistry.registerBuiltin(
+                prefixed,
+                new CATToolExecutor(tool, this.sender, this.createRequireLoader(), configValues)
+              );
+              dynamicToolNames.push(prefixed.name);
+            }
+          }
+          return record.prompt;
+        },
+      },
+    });
+
+    // read_reference — 有参考资料时才注册
+    if (hasReferences) {
+      metaTools.push({
+        definition: {
+          name: "read_reference",
+          description:
+            "Read a reference document belonging to a skill (e.g. API docs, examples). The skill must be loaded first via `load_skill`.",
+          parameters: {
+            type: "object",
+            properties: {
+              skill_name: { type: "string", description: "Name of the skill that owns the reference" },
+              reference_name: { type: "string", description: "Name of the reference document to read" },
+            },
+            required: ["skill_name", "reference_name"],
+          },
+        },
+        executor: {
+          execute: async (args: Record<string, unknown>) => {
+            const skillName = args.skill_name as string;
+            const refName = args.reference_name as string;
+            const ref = await this.skillRepo.getReference(skillName, refName);
+            if (!ref) {
+              throw new Error(`Reference "${refName}" not found in skill "${skillName}"`);
+            }
+            return ref.content;
+          },
+        },
+      });
+    }
+
+    return { promptSuffix: promptParts.join("\n"), metaTools, dynamicToolNames };
+  }
+
+  // 获取模型配置
+  private async getModel(modelId?: string): Promise<AgentModelConfig> {
+    let model: AgentModelConfig | undefined;
+    if (modelId) {
+      model = await this.modelRepo.getModel(modelId);
+    }
+    if (!model) {
+      const defaultId = await this.modelRepo.getDefaultModelId();
+      if (defaultId) {
+        model = await this.modelRepo.getModel(defaultId);
+      }
+    }
+    if (!model) {
+      const models = await this.modelRepo.listModels();
+      if (models.length > 0) {
+        model = models[0];
+      }
+    }
+    if (!model) {
+      throw new Error("No model configured. Please configure a model in Agent settings.");
+    }
+    return model;
+  }
+
+  // 定时任务调度器 tick，由 alarm handler 调用
+  async onSchedulerTick() {
+    await this.taskScheduler.tick();
+  }
+
+  // 处理定时任务 API 请求
+  private async handleAgentTask(params: AgentTaskApiRequest) {
+    switch (params.action) {
+      case "list":
+        return this.taskRepo.listTasks();
+      case "get":
+        return this.taskRepo.getTask(params.id);
+      case "create": {
+        const now = Date.now();
+        const task: AgentTask = {
+          ...params.task,
+          id: uuidv4(),
+          createtime: now,
+          updatetime: now,
+        };
+        // 计算 nextruntime
+        if (task.enabled) {
+          try {
+            const info = nextTimeInfo(task.crontab);
+            task.nextruntime = info.next.toMillis();
+          } catch {
+            // cron 无效，不设置 nextruntime
+          }
+        }
+        await this.taskRepo.saveTask(task);
+        return task;
+      }
+      case "update": {
+        const existing = await this.taskRepo.getTask(params.id);
+        if (!existing) throw new Error("Task not found");
+        const updated = { ...existing, ...params.task, updatetime: Date.now() };
+        // 如果 crontab 或 enabled 变化，重新计算 nextruntime
+        if (params.task.crontab !== undefined || params.task.enabled !== undefined) {
+          if (updated.enabled) {
+            try {
+              const info = nextTimeInfo(updated.crontab);
+              updated.nextruntime = info.next.toMillis();
+            } catch {
+              updated.nextruntime = undefined;
+            }
+          }
+        }
+        await this.taskRepo.saveTask(updated);
+        return updated;
+      }
+      case "delete":
+        await this.taskRepo.removeTask(params.id);
+        return true;
+      case "enable": {
+        const task = await this.taskRepo.getTask(params.id);
+        if (!task) throw new Error("Task not found");
+        task.enabled = params.enabled;
+        task.updatetime = Date.now();
+        if (task.enabled) {
+          try {
+            const info = nextTimeInfo(task.crontab);
+            task.nextruntime = info.next.toMillis();
+          } catch {
+            task.nextruntime = undefined;
+          }
+        }
+        await this.taskRepo.saveTask(task);
+        return task;
+      }
+      case "runNow": {
+        const task = await this.taskRepo.getTask(params.id);
+        if (!task) throw new Error("Task not found");
+        // 不 await，立即返回
+        this.taskScheduler.executeTask(task).catch(() => {});
+        return true;
+      }
+      case "listRuns":
+        return this.taskRunRepo.listRuns(params.taskId, params.limit);
+      case "clearRuns":
+        await this.taskRunRepo.clearRuns(params.taskId);
+        return true;
+      default:
+        throw new Error(`Unknown agentTask action: ${(params as any).action}`);
+    }
+  }
+
+  // internal 模式定时任务执行：构建对话并调用 LLM
+  private async executeInternalTask(
+    task: AgentTask
+  ): Promise<{ conversationId: string; usage?: { inputTokens: number; outputTokens: number } }> {
+    const model = await this.getModel(task.modelId);
+
+    // 解析 Skills
+    const { promptSuffix, metaTools, dynamicToolNames } = this.resolveSkills(task.skills);
+
+    // 临时注册 skill meta-tools
+    const registeredMetaToolNames: string[] = [];
+    for (const mt of metaTools) {
+      this.toolRegistry.registerBuiltin(mt.definition, mt.executor);
+      registeredMetaToolNames.push(mt.definition.name);
+    }
+
+    try {
+      let conversationId: string;
+      const messages: ChatRequest["messages"] = [];
+
+      if (task.conversationId) {
+        // 续接已有对话
+        conversationId = task.conversationId;
+        const conv = await this.getConversation(conversationId);
+
+        const systemContent = buildSystemPrompt({
+          userSystem: conv?.system,
+          skillSuffix: promptSuffix,
+        });
+        messages.push({ role: "system", content: systemContent });
+
+        // 加载历史消息
+        if (conv) {
+          const existingMessages = await this.repo.getMessages(conversationId);
+
+          // 预加载之前已加载的 skill 的工具
+          if (metaTools.length > 0) {
+            const loadSkillMeta = metaTools.find((mt) => mt.definition.name === "load_skill");
+            if (loadSkillMeta) {
+              for (const msg of existingMessages) {
+                if (msg.role === "assistant" && msg.toolCalls) {
+                  for (const tc of msg.toolCalls) {
+                    if (tc.name === "load_skill") {
+                      try {
+                        const args = JSON.parse(tc.arguments || "{}");
+                        if (args.skill_name) {
+                          await loadSkillMeta.executor.execute({ skill_name: args.skill_name });
+                        }
+                      } catch {
+                        // 跳过
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+
+          for (const msg of existingMessages) {
+            if (msg.role === "system") continue;
+            messages.push({
+              role: msg.role,
+              content: msg.content,
+              toolCallId: msg.toolCallId,
+              toolCalls: msg.toolCalls,
+            });
+          }
+        }
+      } else {
+        // 创建新对话
+        conversationId = uuidv4();
+        const conv: Conversation = {
+          id: conversationId,
+          title: task.name,
+          modelId: model.id,
+          skills: task.skills,
+          createtime: Date.now(),
+          updatetime: Date.now(),
+        };
+        await this.repo.saveConversation(conv);
+
+        const systemContent = buildSystemPrompt({ skillSuffix: promptSuffix });
+        messages.push({ role: "system", content: systemContent });
+      }
+
+      // 添加用户消息（task.prompt）
+      const userContent = task.prompt || task.name;
+      messages.push({ role: "user", content: userContent });
+      await this.repo.appendMessage({
+        id: uuidv4(),
+        conversationId,
+        role: "user",
+        content: userContent,
+        createtime: Date.now(),
+      });
+
+      // 收集 usage
+      const totalUsage = { inputTokens: 0, outputTokens: 0 };
+      const abortController = new AbortController();
+
+      const sendEvent = (event: ChatStreamEvent) => {
+        // 定时任务无 UI 连接，但需要收集 usage
+        if (event.type === "done" && event.usage) {
+          totalUsage.inputTokens += event.usage.inputTokens;
+          totalUsage.outputTokens += event.usage.outputTokens;
+        }
+      };
+
+      await this.callLLMWithToolLoop({
+        model,
+        messages,
+        maxIterations: task.maxIterations || 10,
+        sendEvent,
+        signal: abortController.signal,
+        scriptToolCallback: null,
+        conversationId,
+      });
+
+      // 通知
+      if (task.notify) {
+        InfoNotification(task.name, "定时任务执行完成");
+      }
+
+      return { conversationId, usage: totalUsage };
+    } finally {
+      // 清理临时注册的工具
+      for (const name of registeredMetaToolNames) {
+        this.toolRegistry.unregisterBuiltin(name);
+      }
+      for (const name of dynamicToolNames) {
+        this.toolRegistry.unregisterBuiltin(name);
+      }
+    }
+  }
+
+  // event 模式定时任务：通知脚本
+  private async emitTaskEvent(task: AgentTask): Promise<void> {
+    if (!task.sourceScriptUuid) {
+      throw new Error("Event mode task missing sourceScriptUuid");
+    }
+
+    const trigger: AgentTaskTrigger = {
+      taskId: task.id,
+      name: task.name,
+      crontab: task.crontab,
+      triggeredAt: Date.now(),
+    };
+
+    // 通过 offscreen → sandbox → 脚本 EventEmitter 链路通知脚本
+    await sendMessage(this.sender, "offscreen/runtime/emitEvent", {
+      uuid: task.sourceScriptUuid,
+      event: "agentTask",
+      eventId: task.id,
+      data: trigger,
+    });
+
+    if (task.notify) {
+      InfoNotification(task.name, "定时任务已触发");
+    }
+  }
+
+  // 处理 conversation API 请求（非流式），供 GMApi 调用
+  async handleConversationApi(params: ConversationApiRequest) {
+    return this.handleConversation(params);
+  }
+
+  // 处理定时任务 API 请求，供 GMApi 调用
+  async handleAgentTaskApi(params: AgentTaskApiRequest) {
+    return this.handleAgentTask(params);
+  }
+
+  // 处理流式 conversation chat，供 GMApi 调用
+  async handleConversationChatFromGmApi(
+    params: {
+      conversationId: string;
+      message: MessageContent;
+      tools?: ToolDefinition[];
+      maxIterations?: number;
+      scriptUuid: string;
+      // ephemeral 会话专用字段
+      ephemeral?: boolean;
+      messages?: ChatRequest["messages"];
+      system?: string;
+      modelId?: string;
+      cache?: boolean;
+    },
+    sender: IGetSender
+  ) {
+    return this.handleConversationChat(params, sender);
+  }
+
+  // 处理 Sandbox conversation API 请求（非流式）
+  private async handleConversation(params: ConversationApiRequest) {
+    switch (params.action) {
+      case "create":
+        return this.createConversation(params);
+      case "get":
+        return this.getConversation(params.id);
+      case "getMessages":
+        return this.repo.getMessages(params.conversationId);
+      case "save":
+        // 对话已经在 chat 过程中持久化，这里确保元数据也保存
+        return true;
+      case "clearMessages":
+        await this.repo.saveMessages(params.conversationId, []);
+        return true;
+      default:
+        throw new Error(`Unknown conversation action: ${(params as any).action}`);
+    }
+  }
+
+  private async createConversation(params: Extract<ConversationApiRequest, { action: "create" }>) {
+    const model = await this.getModel(params.options.model);
+    const conv: Conversation = {
+      id: params.options.id || uuidv4(),
+      title: "New Chat",
+      modelId: model.id,
+      system: params.options.system,
+      skills: params.options.skills,
+      createtime: Date.now(),
+      updatetime: Date.now(),
+    };
+    await this.repo.saveConversation(conv);
+    return conv;
+  }
+
+  private async getConversation(id: string): Promise<Conversation | null> {
+    const conversations = await this.repo.listConversations();
+    return conversations.find((c) => c.id === id) || null;
+  }
+
+  // 统一的 tool calling 循环，UI 和脚本共用
+  private async callLLMWithToolLoop(params: {
+    model: AgentModelConfig;
+    messages: ChatRequest["messages"];
+    tools?: ToolDefinition[];
+    maxIterations: number;
+    sendEvent: (event: ChatStreamEvent) => void;
+    signal: AbortSignal;
+    // 脚本自定义工具的回调，null 表示只用内置工具
+    scriptToolCallback: ScriptToolCallback | null;
+    // 对话 ID，用于持久化消息（可选，UI 场景由 hooks 自行持久化）
+    conversationId?: string;
+    // 跳过内置工具，仅使用传入的 tools（ephemeral 模式）
+    skipBuiltinTools?: boolean;
+    // 是否启用 prompt caching，默认 true
+    cache?: boolean;
+    // 仅供测试注入，跳过重试延迟
+    delayFn?: (ms: number, signal: AbortSignal) => Promise<void>;
+  }): Promise<void> {
+    const { model, messages, tools, maxIterations, sendEvent, signal, scriptToolCallback, conversationId } = params;
+
+    const startTime = Date.now();
+    let iterations = 0;
+    const totalUsage = { inputTokens: 0, outputTokens: 0 };
+
+    while (iterations < maxIterations) {
+      iterations++;
+
+      // 每轮重新获取工具定义（load_skill 可能动态注册了新工具）
+      const allToolDefs = params.skipBuiltinTools ? tools || [] : this.toolRegistry.getDefinitions(tools);
+
+      // 调用 LLM（带指数退避重试）
+      const result = await withRetry(
+        () =>
+          this.callLLM(
+            model,
+            { messages, tools: allToolDefs.length > 0 ? allToolDefs : undefined, cache: params.cache },
+            sendEvent,
+            signal
+          ),
+        signal,
+        undefined,
+        params.delayFn
+      );
+
+      if (signal.aborted) return;
+
+      // 累计 usage
+      if (result.usage) {
+        totalUsage.inputTokens += result.usage.inputTokens;
+        totalUsage.outputTokens += result.usage.outputTokens;
+      }
+
+      // 如果有 tool calls，需要执行并继续循环
+      if (result.toolCalls && result.toolCalls.length > 0 && allToolDefs.length > 0) {
+        // 持久化 assistant 消息（含 tool calls）
+        if (conversationId) {
+          await this.repo.appendMessage({
+            id: uuidv4(),
+            conversationId,
+            role: "assistant",
+            content: result.content,
+            thinking: result.thinking ? { content: result.thinking } : undefined,
+            toolCalls: result.toolCalls,
+            createtime: Date.now(),
+          });
+        }
+
+        // 将 assistant 消息加入上下文（带 toolCalls，供 provider 构建 tool_calls 字段）
+        messages.push({ role: "assistant", content: result.content || "", toolCalls: result.toolCalls });
+
+        // 通过 ToolRegistry 执行工具（内置工具直接执行，脚本工具回调 Sandbox）
+        const toolResults = await this.toolRegistry.execute(result.toolCalls, scriptToolCallback);
+
+        // 将 tool 结果加入消息，并通知 UI 工具执行完成
+        // 收集需要回写附件的 toolCall ID → Attachment[]
+        const attachmentUpdates = new Map<string, Attachment[]>();
+
+        for (const tr of toolResults) {
+          // LLM 上下文只包含文本结果，不含附件
+          messages.push({ role: "tool", content: tr.result, toolCallId: tr.id });
+          // 通知 UI 工具执行完成（含附件元数据）
+          sendEvent({ type: "tool_call_complete", id: tr.id, result: tr.result, attachments: tr.attachments });
+
+          if (tr.attachments?.length) {
+            attachmentUpdates.set(tr.id, tr.attachments);
+          }
+
+          // 持久化 tool 结果消息
+          if (conversationId) {
+            await this.repo.appendMessage({
+              id: uuidv4(),
+              conversationId,
+              role: "tool",
+              content: tr.result,
+              toolCallId: tr.id,
+              createtime: Date.now(),
+            });
+          }
+        }
+
+        // 回写附件元数据到 assistant 消息的 toolCalls（内存 + 持久化）
+        if (attachmentUpdates.size > 0) {
+          // 找到最近的 assistant 消息（刚推入的倒数第 toolResults.length + 1 位）
+          const assistantMsg = messages.find(
+            (m) => m.role === "assistant" && m.toolCalls?.some((tc) => attachmentUpdates.has(tc.id))
+          );
+          if (assistantMsg?.toolCalls) {
+            for (const tc of assistantMsg.toolCalls) {
+              const atts = attachmentUpdates.get(tc.id);
+              if (atts) tc.attachments = atts;
+            }
+            // 更新持久化的 assistant 消息
+            if (conversationId) {
+              const allMessages = await this.repo.getMessages(conversationId);
+              // 找到最后一条有匹配 toolCall 的 assistant 消息
+              for (let i = allMessages.length - 1; i >= 0; i--) {
+                const msg = allMessages[i];
+                if (msg.role === "assistant" && msg.toolCalls?.some((tc) => attachmentUpdates.has(tc.id))) {
+                  for (const tc of msg.toolCalls!) {
+                    const atts = attachmentUpdates.get(tc.id);
+                    if (atts) tc.attachments = atts;
+                  }
+                  await this.repo.saveMessages(conversationId, allMessages);
+                  break;
+                }
+              }
+            }
+          }
+        }
+
+        // 通知 UI 即将开始新一轮 LLM 调用，创建新的 assistant 消息
+        sendEvent({ type: "new_message" });
+
+        // 继续循环
+        continue;
+      }
+
+      // 没有 tool calls，对话结束
+      if (conversationId) {
+        await this.repo.appendMessage({
+          id: uuidv4(),
+          conversationId,
+          role: "assistant",
+          content: result.content,
+          thinking: result.thinking ? { content: result.thinking } : undefined,
+          createtime: Date.now(),
+        });
+      }
+
+      // 发送 done 事件
+      sendEvent({ type: "done", usage: totalUsage, durationMs: Date.now() - startTime });
+      return;
+    }
+
+    // 超过最大迭代次数
+    const maxIterMsg = `Tool calling loop exceeded maximum iterations (${maxIterations})`;
+    if (conversationId) {
+      await this.repo.appendMessage({
+        id: uuidv4(),
+        conversationId,
+        role: "assistant",
+        content: "",
+        error: maxIterMsg,
+        createtime: Date.now(),
+      });
+    }
+    sendEvent({
+      type: "error",
+      message: maxIterMsg,
+      errorCode: "max_iterations",
+    });
+  }
+
+  // 解析消息中所有 ContentBlock 引用的 attachmentId → base64 data URL
+  private async resolveAttachments(messages: ChatRequest["messages"]): Promise<(id: string) => string | null> {
+    const resolved = new Map<string, string>();
+    const ids = new Set<string>();
+
+    for (const m of messages) {
+      if (isContentBlocks(m.content)) {
+        for (const block of m.content) {
+          if (block.type !== "text" && "attachmentId" in block) {
+            ids.add(block.attachmentId);
+          }
+        }
+      }
+    }
+
+    if (ids.size === 0) return () => null;
+
+    for (const id of ids) {
+      try {
+        const blob = await this.repo.getAttachment(id);
+        if (blob) {
+          // Blob → base64 data URL
+          const buffer = await blob.arrayBuffer();
+          const bytes = new Uint8Array(buffer);
+          let binary = "";
+          for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]);
+          }
+          const b64 = btoa(binary);
+          resolved.set(id, `data:${blob.type || "application/octet-stream"};base64,${b64}`);
+        }
+      } catch {
+        // 加载失败，跳过
+      }
+    }
+
+    return (id: string) => resolved.get(id) ?? null;
+  }
+
+  // 统一的流式 conversation chat（UI 和脚本 API 共用）
+  private async handleConversationChat(
+    params: {
+      conversationId: string;
+      message: MessageContent;
+      tools?: ToolDefinition[];
+      maxIterations?: number;
+      scriptUuid?: string;
+      modelId?: string;
+      // 用户消息已在存储中（重新生成场景），跳过保存和 LLM 上下文追加
+      skipSaveUserMessage?: boolean;
+      // ephemeral 会话专用字段
+      ephemeral?: boolean;
+      messages?: ChatRequest["messages"];
+      system?: string;
+      cache?: boolean;
+    },
+    sender: IGetSender
+  ) {
+    if (!sender.isType(GetSenderType.CONNECT)) {
+      throw new Error("Conversation chat requires connect mode");
+    }
+    const msgConn = sender.getConnect()!;
+
+    const abortController = new AbortController();
+    let isDisconnected = false;
+
+    msgConn.onDisconnect(() => {
+      isDisconnected = true;
+      abortController.abort();
+    });
+
+    const sendEvent = (event: ChatStreamEvent) => {
+      if (!isDisconnected) {
+        msgConn.sendMessage({ action: "event", data: event });
+      }
+    };
+
+    // 构建脚本工具回调：通过 MessageConnect 让 Sandbox 执行 handler
+    let toolResultResolve: ((results: Array<{ id: string; result: string }>) => void) | null = null;
+
+    msgConn.onMessage((msg: any) => {
+      if (msg.action === "toolResults" && toolResultResolve) {
+        const resolve = toolResultResolve;
+        toolResultResolve = null;
+        resolve(msg.data);
+      }
+    });
+
+    const scriptToolCallback: ScriptToolCallback = (toolCalls: ToolCall[]) => {
+      return new Promise((resolve) => {
+        toolResultResolve = resolve;
+        msgConn.sendMessage({ action: "executeTools", data: toolCalls });
+      });
+    };
+
+    try {
+      // ephemeral 模式：无状态处理，不从 repo 加载/持久化
+      if (params.ephemeral) {
+        const model = await this.getModel(params.modelId);
+
+        // 使用脚本传入的完整消息历史
+        const messages: ChatRequest["messages"] = [];
+
+        // 添加 system prompt（内置提示词 + 用户自定义）
+        const ephemeralSystem = buildSystemPrompt({ userSystem: params.system });
+        messages.push({ role: "system", content: ephemeralSystem });
+
+        // 添加脚本端维护的消息历史（已含最新 user message）
+        if (params.messages) {
+          for (const msg of params.messages) {
+            messages.push({
+              role: msg.role,
+              content: msg.content,
+              toolCallId: msg.toolCallId,
+              toolCalls: msg.toolCalls,
+            });
+          }
+        }
+
+        await this.callLLMWithToolLoop({
+          model,
+          messages,
+          tools: params.tools,
+          maxIterations: params.maxIterations || 20,
+          sendEvent,
+          signal: abortController.signal,
+          scriptToolCallback: params.tools && params.tools.length > 0 ? scriptToolCallback : null,
+          skipBuiltinTools: true,
+          cache: params.cache,
+        });
+        return;
+      }
+
+      // 获取对话和模型
+      const conv = await this.getConversation(params.conversationId);
+      if (!conv) {
+        sendEvent({ type: "error", message: "Conversation not found" });
+        return;
+      }
+
+      // UI 传入 modelId 时覆盖 conversation 的 modelId
+      if (params.modelId && params.modelId !== conv.modelId) {
+        conv.modelId = params.modelId;
+        conv.updatetime = Date.now();
+        await this.repo.saveConversation(conv);
+      }
+
+      const model = await this.getModel(conv.modelId);
+
+      // 解析 Skills（注入 prompt + 注册 meta-tools）
+      const { promptSuffix, metaTools, dynamicToolNames } = this.resolveSkills(conv.skills);
+
+      // 临时注册 skill meta-tools（对话结束后清理）
+      const registeredMetaToolNames: string[] = [];
+      for (const mt of metaTools) {
+        this.toolRegistry.registerBuiltin(mt.definition, mt.executor);
+        registeredMetaToolNames.push(mt.definition.name);
+      }
+
+      // 加载历史消息
+      const existingMessages = await this.repo.getMessages(params.conversationId);
+
+      // 扫描历史消息中的 load_skill 调用，预加载之前已加载的 skill 的工具
+      if (metaTools.length > 0) {
+        const loadSkillMeta = metaTools.find((mt) => mt.definition.name === "load_skill");
+        if (loadSkillMeta) {
+          const loadedSkillNames = new Set<string>();
+          for (const msg of existingMessages) {
+            if (msg.role === "assistant" && msg.toolCalls) {
+              for (const tc of msg.toolCalls) {
+                if (tc.name === "load_skill") {
+                  try {
+                    const args = JSON.parse(tc.arguments || "{}");
+                    if (args.skill_name) {
+                      loadedSkillNames.add(args.skill_name);
+                    }
+                  } catch {
+                    // 解析失败，跳过
+                  }
+                }
+              }
+            }
+          }
+          // 预执行 load_skill 以注册动态工具（结果不需要，只需要副作用）
+          for (const skillName of loadedSkillNames) {
+            try {
+              await loadSkillMeta.executor.execute({ skill_name: skillName });
+            } catch {
+              // 加载失败，跳过
+            }
+          }
+        }
+      }
+
+      // 构建消息列表
+      const messages: ChatRequest["messages"] = [];
+
+      // 添加 system 消息（内置提示词 + 用户自定义 + skill prompt）
+      const systemContent = buildSystemPrompt({
+        userSystem: conv.system,
+        skillSuffix: promptSuffix,
+      });
+      messages.push({ role: "system", content: systemContent });
+
+      // 添加历史消息（跳过 system）
+      for (const msg of existingMessages) {
+        if (msg.role === "system") continue;
+        messages.push({
+          role: msg.role,
+          content: msg.content,
+          toolCallId: msg.toolCallId,
+          toolCalls: msg.toolCalls,
+        });
+      }
+
+      if (!params.skipSaveUserMessage) {
+        // 添加新用户消息到 LLM 上下文并持久化
+        messages.push({ role: "user", content: params.message });
+        await this.repo.appendMessage({
+          id: uuidv4(),
+          conversationId: params.conversationId,
+          role: "user",
+          content: params.message,
+          createtime: Date.now(),
+        });
+      }
+
+      // 更新对话标题（如果是第一条消息）
+      if (existingMessages.length === 0 && conv.title === "New Chat") {
+        const titleText = getTextContent(params.message);
+        conv.title = titleText.slice(0, 30) + (titleText.length > 30 ? "..." : "");
+        conv.updatetime = Date.now();
+        await this.repo.saveConversation(conv);
+      }
+
+      try {
+        // 使用统一的 tool calling 循环
+        await this.callLLMWithToolLoop({
+          model,
+          messages,
+          tools: params.tools,
+          maxIterations: params.maxIterations || 20,
+          sendEvent,
+          signal: abortController.signal,
+          scriptToolCallback: params.tools && params.tools.length > 0 ? scriptToolCallback : null,
+          conversationId: params.conversationId,
+        });
+      } finally {
+        // 清理临时注册的 meta-tools 和 load_skill 动态注册的 CATTool
+        for (const name of registeredMetaToolNames) {
+          this.toolRegistry.unregisterBuiltin(name);
+        }
+        for (const name of dynamicToolNames) {
+          this.toolRegistry.unregisterBuiltin(name);
+        }
+      }
+    } catch (e: any) {
+      if (abortController.signal.aborted) return;
+      const errorMsg = e.message || "Unknown error";
+      // 持久化错误消息到 OPFS，确保刷新后仍可见
+      if (params.conversationId && !params.ephemeral) {
+        try {
+          await this.repo.appendMessage({
+            id: uuidv4(),
+            conversationId: params.conversationId,
+            role: "assistant",
+            content: "",
+            error: errorMsg,
+            createtime: Date.now(),
+          });
+        } catch {
+          // 持久化失败不阻塞错误事件发送
+        }
+      }
+      sendEvent({ type: "error", message: errorMsg, errorCode: classifyErrorCode(e) });
+    }
+  }
+
+  // 调用 LLM 并收集完整响应（内部处理流式）
+  private async callLLM(
+    model: AgentModelConfig,
+    params: { messages: ChatRequest["messages"]; tools?: ToolDefinition[]; cache?: boolean },
+    sendEvent: (event: ChatStreamEvent) => void,
+    signal: AbortSignal
+  ): Promise<{
+    content: string;
+    thinking?: string;
+    toolCalls?: ToolCall[];
+    usage?: { inputTokens: number; outputTokens: number };
+  }> {
+    const chatRequest: ChatRequest = {
+      conversationId: "",
+      modelId: model.id,
+      messages: params.messages,
+      tools: params.tools,
+      cache: params.cache,
+    };
+
+    // 预解析消息中 ContentBlock 引用的 attachmentId → base64
+    const attachmentResolver = await this.resolveAttachments(params.messages);
+
+    const { url, init } =
+      model.provider === "anthropic"
+        ? buildAnthropicRequest(model, chatRequest, attachmentResolver)
+        : buildOpenAIRequest(model, chatRequest, attachmentResolver);
+
+    const response = await fetch(url, { ...init, signal });
+
+    if (!response.ok) {
+      const errorText = await response.text().catch(() => "");
+      let errorMessage = `API error: ${response.status}`;
+      try {
+        const errorJson = JSON.parse(errorText);
+        errorMessage = errorJson.error?.message || errorJson.message || errorMessage;
+      } catch {
+        if (errorText) errorMessage += ` - ${errorText.slice(0, 200)}`;
+      }
+      throw new Error(errorMessage);
+    }
+
+    if (!response.body) {
+      throw new Error("No response body");
+    }
+
+    const reader = response.body.getReader();
+    const parseStream = model.provider === "anthropic" ? parseAnthropicStream : parseOpenAIStream;
+
+    // 收集响应
+    let content = "";
+    let thinking = "";
+    const toolCalls: ToolCall[] = [];
+    let currentToolCall: ToolCall | null = null;
+    let usage: { inputTokens: number; outputTokens: number } | undefined;
+
+    return new Promise((resolve, reject) => {
+      const onEvent = (event: ChatStreamEvent) => {
+        // 只转发流式内容事件，done 和 error 由 callLLMWithToolLoop 统一管理
+        // 避免在 tool calling 循环中提前发送 done 导致客户端过早 resolve
+        if (event.type !== "done" && event.type !== "error") {
+          sendEvent(event);
+        }
+
+        switch (event.type) {
+          case "content_delta":
+            content += event.delta;
+            break;
+          case "thinking_delta":
+            thinking += event.delta;
+            break;
+          case "tool_call_start":
+            currentToolCall = { ...event.toolCall, arguments: event.toolCall.arguments || "" };
+            break;
+          case "tool_call_delta":
+            if (currentToolCall) {
+              currentToolCall.arguments += event.delta;
+            }
+            break;
+          case "done":
+            // 保存当前的 tool call
+            if (currentToolCall) {
+              toolCalls.push(currentToolCall);
+              currentToolCall = null;
+            }
+            if (event.usage) {
+              usage = event.usage;
+            }
+            resolve({
+              content,
+              thinking: thinking || undefined,
+              toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+              usage,
+            });
+            break;
+          case "error":
+            reject(new Error(event.message));
+            break;
+        }
+      };
+
+      parseStream(reader, onEvent, signal).catch(reject);
+    });
+  }
+}
diff --git a/src/app/service/service_worker/agent_dom.test.ts b/src/app/service/service_worker/agent_dom.test.ts
new file mode 100644
index 000000000..a1e4ce69d
--- /dev/null
+++ b/src/app/service/service_worker/agent_dom.test.ts
@@ -0,0 +1,368 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentDomService } from "./agent_dom";
+
+// mock chrome.scripting
+const mockExecuteScript = vi.fn();
+// mock chrome.tabs
+const mockTabsQuery = vi.fn();
+const mockTabsGet = vi.fn();
+const mockTabsCreate = vi.fn();
+const mockTabsUpdate = vi.fn();
+const mockTabsReload = vi.fn();
+const mockCaptureVisibleTab = vi.fn();
+const mockOnUpdated = {
+  addListener: vi.fn(),
+  removeListener: vi.fn(),
+};
+const mockOnCreated = {
+  addListener: vi.fn(),
+  removeListener: vi.fn(),
+};
+const mockOnRemoved = {
+  addListener: vi.fn(),
+  removeListener: vi.fn(),
+};
+
+// mock chrome.permissions
+const mockPermissionsContains = vi.fn();
+const mockPermissionsRequest = vi.fn();
+
+beforeEach(() => {
+  vi.clearAllMocks();
+
+  // 设置 chrome.scripting mock
+  (chrome as any).scripting = {
+    executeScript: mockExecuteScript,
+  };
+  // 覆盖 chrome.tabs mock
+  (chrome.tabs as any).query = mockTabsQuery;
+  (chrome.tabs as any).get = mockTabsGet;
+  (chrome.tabs as any).create = mockTabsCreate;
+  (chrome.tabs as any).update = mockTabsUpdate;
+  (chrome.tabs as any).reload = mockTabsReload;
+  (chrome.tabs as any).captureVisibleTab = mockCaptureVisibleTab;
+  (chrome.tabs as any).onUpdated = mockOnUpdated;
+  (chrome.tabs as any).onCreated = mockOnCreated;
+  (chrome.tabs as any).onRemoved = mockOnRemoved;
+  (chrome as any).permissions = {
+    contains: mockPermissionsContains,
+    request: mockPermissionsRequest,
+  };
+});
+
+describe("AgentDomService", () => {
+  let service: AgentDomService;
+
+  beforeEach(() => {
+    service = new AgentDomService();
+  });
+
+  describe("listTabs", () => {
+    it("应返回所有标签页信息", async () => {
+      mockTabsQuery.mockResolvedValue([
+        { id: 1, url: "https://example.com", title: "Example", active: true, windowId: 1, discarded: false },
+        { id: 2, url: "https://test.com", title: "Test", active: false, windowId: 1, discarded: false },
+      ]);
+
+      const result = await service.listTabs();
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toEqual({
+        tabId: 1,
+        url: "https://example.com",
+        title: "Example",
+        active: true,
+        windowId: 1,
+        discarded: false,
+      });
+      expect(result[1].tabId).toBe(2);
+    });
+
+    it("应过滤没有 id 的标签页", async () => {
+      mockTabsQuery.mockResolvedValue([
+        { id: 1, url: "https://example.com", title: "Example", active: true, windowId: 1 },
+        { url: "https://no-id.com", title: "No ID", active: false, windowId: 1 },
+      ]);
+
+      const result = await service.listTabs();
+      expect(result).toHaveLength(1);
+      expect(result[0].tabId).toBe(1);
+    });
+  });
+
+  describe("navigate", () => {
+    it("应在指定 tabId 时更新标签页", async () => {
+      mockTabsUpdate.mockResolvedValue({});
+      mockTabsGet.mockResolvedValue({
+        id: 1,
+        url: "https://new-url.com",
+        title: "New Page",
+        status: "complete",
+      });
+
+      const result = await service.navigate("https://new-url.com", { tabId: 1, waitUntil: false });
+
+      expect(mockTabsUpdate).toHaveBeenCalledWith(1, { url: "https://new-url.com" });
+      expect(result.tabId).toBe(1);
+      expect(result.url).toBe("https://new-url.com");
+    });
+
+    it("应在未指定 tabId 时创建新标签页", async () => {
+      mockTabsCreate.mockResolvedValue({ id: 5 });
+      mockTabsGet.mockResolvedValue({
+        id: 5,
+        url: "https://new-url.com",
+        title: "New Page",
+        status: "complete",
+      });
+
+      const result = await service.navigate("https://new-url.com", { waitUntil: false });
+
+      expect(mockTabsCreate).toHaveBeenCalledWith({ url: "https://new-url.com" });
+      expect(result.tabId).toBe(5);
+    });
+  });
+
+  describe("readPage", () => {
+    it("应返回页面 HTML", async () => {
+      const mockPageContent = {
+        title: "Test Page",
+        url: "https://example.com",
+        html: "<html><body><h1>Hello</h1></body></html>",
+      };
+      mockExecuteScript.mockResolvedValue([{ result: mockPageContent }]);
+      mockTabsQuery.mockResolvedValue([{ id: 1 }]);
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+
+      const result = await service.readPage({ tabId: 1 });
+
+      expect(result.title).toBe("Test Page");
+      expect(result.html).toContain("<h1>Hello</h1>");
+      expect(mockExecuteScript).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: { tabId: 1 },
+          world: "MAIN",
+        })
+      );
+    });
+
+    it("应在 HTML 超长时截断", async () => {
+      const mockPageContent = {
+        title: "Test Page",
+        url: "https://example.com",
+        html: "<html>truncated...</html>",
+        truncated: true,
+        totalLength: 500000,
+      };
+      mockExecuteScript.mockResolvedValue([{ result: mockPageContent }]);
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+
+      const result = await service.readPage({ tabId: 1 });
+
+      expect(result.truncated).toBe(true);
+      expect(result.totalLength).toBe(500000);
+    });
+  });
+
+  describe("click", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("应执行默认模式点击", async () => {
+      mockTabsGet.mockResolvedValue({ id: 1, url: "https://example.com", status: "complete", discarded: false });
+      // 点击执行
+      mockExecuteScript.mockResolvedValueOnce([{ result: undefined }]);
+
+      const promise = service.click("#btn", { tabId: 1 });
+      await vi.advanceTimersByTimeAsync(600);
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+      expect(mockExecuteScript).toHaveBeenCalledTimes(1);
+    });
+
+    it("应检测页面跳转", async () => {
+      // 第一次 get 返回原始 URL（resolveTabId）
+      mockTabsGet.mockResolvedValueOnce({ id: 1, url: "https://example.com", status: "complete", discarded: false });
+      // 第二次 get 返回原始 URL（executeClick 内部）
+      mockTabsGet.mockResolvedValueOnce({ id: 1, url: "https://example.com", status: "complete" });
+      mockExecuteScript.mockResolvedValueOnce([{ result: undefined }]); // 点击
+      // 第三次 get 返回新 URL（collectActionResult）
+      mockTabsGet.mockResolvedValueOnce({ id: 1, url: "https://new-page.com", status: "complete" });
+
+      const promise = service.click("#link", { tabId: 1 });
+      await vi.advanceTimersByTimeAsync(600);
+      const result = await promise;
+
+      expect(result.success).toBe(true);
+      expect(result.navigated).toBe(true);
+      expect(result.url).toBe("https://new-page.com");
+    });
+  });
+
+  describe("fill", () => {
+    it("应执行默认模式填写", async () => {
+      mockTabsGet.mockResolvedValue({ id: 1, url: "https://example.com", status: "complete", discarded: false });
+      mockExecuteScript.mockResolvedValue([{ result: undefined }]);
+
+      const result = await service.fill("#input", "test value", { tabId: 1 });
+
+      expect(result.success).toBe(true);
+      expect(result.url).toBe("https://example.com");
+    });
+  });
+
+  describe("scroll", () => {
+    it("应返回滚动位置信息", async () => {
+      const scrollResult = {
+        scrollTop: 800,
+        scrollHeight: 5000,
+        clientHeight: 900,
+        atBottom: false,
+      };
+      mockExecuteScript.mockResolvedValue([{ result: scrollResult }]);
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+
+      const result = await service.scroll("down", { tabId: 1 });
+
+      expect(result.scrollTop).toBe(800);
+      expect(result.atBottom).toBe(false);
+    });
+  });
+
+  describe("waitFor", () => {
+    it("应在元素存在时立即返回", async () => {
+      const waitResult = {
+        found: true,
+        element: {
+          selector: "#target",
+          tag: "div",
+          text: "Found",
+          visible: true,
+        },
+      };
+      mockExecuteScript.mockResolvedValue([{ result: waitResult }]);
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+
+      const result = await service.waitFor("#target", { tabId: 1 });
+
+      expect(result.found).toBe(true);
+      expect(result.element?.tag).toBe("div");
+    });
+
+    it("应在超时后返回 found: false", async () => {
+      vi.useFakeTimers({ shouldAdvanceTime: true });
+      mockExecuteScript.mockResolvedValue([{ result: null }]);
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+
+      const promise = service.waitFor("#nonexistent", { tabId: 1, timeout: 100 });
+      // 需要多次 advance 来驱动 while 循环中的 setTimeout
+      for (let i = 0; i < 5; i++) {
+        await vi.advanceTimersByTimeAsync(600);
+      }
+      const result = await promise;
+
+      expect(result.found).toBe(false);
+      vi.useRealTimers();
+    });
+  });
+
+  describe("screenshot", () => {
+    it("应在前台 tab 使用 captureVisibleTab", async () => {
+      mockTabsGet.mockResolvedValue({
+        id: 1,
+        active: true,
+        windowId: 1,
+        status: "complete",
+        discarded: false,
+      });
+      mockCaptureVisibleTab.mockResolvedValue("data:image/jpeg;base64,abc123");
+
+      const result = await service.screenshot({ tabId: 1 });
+
+      expect(result).toBe("data:image/jpeg;base64,abc123");
+      expect(mockCaptureVisibleTab).toHaveBeenCalledWith(1, { format: "jpeg", quality: 80 });
+    });
+  });
+
+  describe("executeScript", () => {
+    it("应在页面中执行代码并返回结果", async () => {
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+      mockExecuteScript.mockResolvedValue([{ result: { count: 42, items: ["a", "b"] } }]);
+
+      const result = await service.executeScript('return document.querySelectorAll("a").length', { tabId: 1 });
+
+      expect(result).toEqual({ count: 42, items: ["a", "b"] });
+      expect(mockExecuteScript).toHaveBeenCalledWith(
+        expect.objectContaining({
+          target: { tabId: 1 },
+          world: "MAIN",
+        })
+      );
+    });
+
+    it("应在执行失败时抛出错误", async () => {
+      mockTabsGet.mockResolvedValue({ id: 1, status: "complete", discarded: false });
+      mockExecuteScript.mockResolvedValue([]);
+
+      await expect(service.executeScript("return 1", { tabId: 1 })).rejects.toThrow("Failed to execute script");
+    });
+  });
+
+  describe("handleDomApi", () => {
+    it("应正确路由 listTabs 请求", async () => {
+      mockTabsQuery.mockResolvedValue([]);
+
+      const result = await service.handleDomApi({ action: "listTabs", scriptUuid: "test" });
+
+      expect(result).toEqual([]);
+    });
+
+    it("应对未知 action 抛出错误", async () => {
+      await expect(service.handleDomApi({ action: "unknown" as any, scriptUuid: "test" })).rejects.toThrow(
+        "Unknown DOM action"
+      );
+    });
+  });
+
+  describe("resolveTabId", () => {
+    it("应在 tab 被 discard 时自动 reload", async () => {
+      mockTabsGet.mockResolvedValueOnce({
+        id: 1,
+        discarded: true,
+        status: "complete",
+      });
+      mockTabsReload.mockResolvedValue(undefined);
+      // reload 后再次 get
+      mockTabsGet.mockResolvedValueOnce({
+        id: 1,
+        discarded: false,
+        status: "complete",
+      });
+
+      // 通过 readPage 间接测试 resolveTabId
+      const mockContent = {
+        title: "Test",
+        url: "https://example.com",
+        html: "<html><body>Test</body></html>",
+      };
+      mockExecuteScript.mockResolvedValue([{ result: mockContent }]);
+
+      await service.readPage({ tabId: 1 });
+
+      expect(mockTabsReload).toHaveBeenCalledWith(1);
+    });
+
+    it("应在无活动 tab 时抛出错误", async () => {
+      mockTabsQuery.mockResolvedValue([]);
+      mockExecuteScript.mockResolvedValue([{ result: {} }]);
+
+      await expect(service.readPage()).rejects.toThrow("No active tab found");
+    });
+  });
+});
diff --git a/src/app/service/service_worker/agent_dom.ts b/src/app/service/service_worker/agent_dom.ts
new file mode 100644
index 000000000..352f7dd8a
--- /dev/null
+++ b/src/app/service/service_worker/agent_dom.ts
@@ -0,0 +1,567 @@
+// AgentDomService — DOM 操作核心逻辑，在 Service Worker 中运行
+// 默认模式通过 chrome.scripting.executeScript 操作
+// trusted 模式通过 chrome.debugger CDP 操作
+
+import type {
+  TabInfo,
+  ActionResult,
+  PageContent,
+  ReadPageOptions,
+  DomActionOptions,
+  ScreenshotOptions,
+  NavigateOptions,
+  ScrollDirection,
+  ScrollOptions,
+  ScrollResult,
+  NavigateResult,
+  WaitForOptions,
+  WaitForResult,
+  DomApiRequest,
+  ExecuteScriptOptions,
+} from "@App/app/service/agent/types";
+
+type ReadPageInjectedOptions = {
+  selector: string | undefined | null;
+  maxLength: number;
+  removeTags: string[];
+};
+import type { MonitorResult, MonitorStatus } from "@App/app/service/agent/types";
+import {
+  withDebugger,
+  cdpClick,
+  cdpFill,
+  cdpScreenshot,
+  cdpStartMonitor,
+  cdpStopMonitor,
+  cdpPeekMonitor,
+} from "./agent_dom_cdp";
+
+export class AgentDomService {
+  // 列出所有标签页
+  async listTabs(): Promise<TabInfo[]> {
+    const tabs = await chrome.tabs.query({});
+    return tabs
+      .filter((t) => t.id !== undefined)
+      .map((t) => ({
+        tabId: t.id!,
+        url: t.url || "",
+        title: t.title || "",
+        active: t.active || false,
+        windowId: t.windowId,
+        discarded: t.discarded || false,
+      }));
+  }
+
+  // 导航到 URL
+  async navigate(url: string, options?: NavigateOptions): Promise<NavigateResult> {
+    const timeout = options?.timeout ?? 30000;
+    const waitUntil = options?.waitUntil ?? true;
+
+    let tabId: number;
+    if (options?.tabId) {
+      await chrome.tabs.update(options.tabId, { url });
+      tabId = options.tabId;
+    } else {
+      const tab = await chrome.tabs.create({ url });
+      tabId = tab.id!;
+    }
+
+    if (waitUntil) {
+      await this.waitForPageLoad(tabId, timeout);
+    }
+
+    const tab = await chrome.tabs.get(tabId);
+    return {
+      tabId,
+      url: tab.url || url,
+      title: tab.title || "",
+    };
+  }
+
+  // 读取页面内容，返回原始 HTML
+  async readPage(options?: ReadPageOptions): Promise<PageContent> {
+    const tabId = await this.resolveTabId(options?.tabId);
+    const maxLength = options?.maxLength ?? 200000;
+    const selector = options?.selector;
+    const removeTags = options?.removeTags ?? ["script", "style", "noscript", "svg", "link[rel=stylesheet]"];
+
+    const results = await chrome.scripting.executeScript({
+      target: { tabId },
+      func: readPageContent,
+      args: [{ selector, maxLength, removeTags } as ReadPageInjectedOptions],
+      world: "MAIN",
+    });
+
+    if (!results || results.length === 0) {
+      throw new Error("Failed to read page content");
+    }
+
+    return results[0].result as PageContent;
+  }
+
+  // 截图
+  async screenshot(options?: ScreenshotOptions): Promise<string> {
+    const tabId = await this.resolveTabId(options?.tabId);
+
+    // 检查 tab 是否前台 active
+    const tab = await chrome.tabs.get(tabId);
+    if (!tab.active) {
+      // 后台 tab 优先用 CDP 截图
+      try {
+        return await withDebugger(tabId, (id) => cdpScreenshot(id, options));
+      } catch (e) {
+        console.error("[AgentDom] CDP screenshot failed, falling back to captureVisibleTab", {
+          tabId,
+          error: e instanceof Error ? e.message : e,
+        });
+      }
+      // 降级：先激活 tab 再用 captureVisibleTab
+      await chrome.tabs.update(tabId, { active: true });
+      await new Promise((resolve) => setTimeout(resolve, 300));
+    }
+
+    const quality = options?.quality ?? 80;
+    const updatedTab = await chrome.tabs.get(tabId);
+    const dataUrl = await chrome.tabs.captureVisibleTab(updatedTab.windowId, {
+      format: "jpeg",
+      quality,
+    });
+    return dataUrl;
+  }
+
+  // 点击元素
+  async click(selector: string, options?: DomActionOptions): Promise<ActionResult> {
+    const tabId = await this.resolveTabId(options?.tabId);
+
+    if (options?.trusted) {
+      try {
+        return await withDebugger(tabId, (id) => cdpClick(id, selector));
+      } catch (e) {
+        console.error("[AgentDom] CDP click failed, falling back to non-trusted mode", {
+          tabId,
+          selector,
+          error: e instanceof Error ? e.message : e,
+        });
+      }
+    }
+
+    return this.executeClick(tabId, selector);
+  }
+
+  // 填写表单
+  async fill(selector: string, value: string, options?: DomActionOptions): Promise<ActionResult> {
+    const tabId = await this.resolveTabId(options?.tabId);
+
+    if (options?.trusted) {
+      try {
+        return await withDebugger(tabId, (id) => cdpFill(id, selector, value));
+      } catch (e) {
+        console.error("[AgentDom] CDP fill failed, falling back to non-trusted mode", {
+          tabId,
+          selector,
+          error: e instanceof Error ? e.message : e,
+        });
+      }
+    }
+
+    return this.executeFill(tabId, selector, value);
+  }
+
+  // 滚动页面
+  async scroll(direction: ScrollDirection, options?: ScrollOptions): Promise<ScrollResult> {
+    const tabId = await this.resolveTabId(options?.tabId);
+    const selector = options?.selector;
+
+    const results = await chrome.scripting.executeScript({
+      target: { tabId },
+      func: executeScroll,
+      args: [direction, selector || null],
+      world: "MAIN",
+    });
+
+    if (!results || results.length === 0) {
+      throw new Error("Failed to scroll");
+    }
+
+    return results[0].result as ScrollResult;
+  }
+
+  // 等待元素出现
+  async waitFor(selector: string, options?: WaitForOptions): Promise<WaitForResult> {
+    const tabId = await this.resolveTabId(options?.tabId);
+    const timeout = options?.timeout ?? 10000;
+    const interval = 500;
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeout) {
+      const results = await chrome.scripting.executeScript({
+        target: { tabId },
+        func: checkElement,
+        args: [selector],
+        world: "MAIN",
+      });
+
+      if (results?.[0]?.result) {
+        return results[0].result as WaitForResult;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+
+    return { found: false };
+  }
+
+  // 在页面中执行 JavaScript 代码
+  async executeScript(code: string, options?: ExecuteScriptOptions): Promise<unknown> {
+    const tabId = await this.resolveTabId(options?.tabId);
+
+    const results = await chrome.scripting.executeScript({
+      target: { tabId },
+      func: (codeStr: string) => {
+        // 用 Function 构造器执行代码，支持 return 返回值
+        const fn = new Function(codeStr);
+        return fn();
+      },
+      args: [code],
+      world: "MAIN",
+    });
+
+    if (!results || results.length === 0) {
+      throw new Error("Failed to execute script");
+    }
+
+    return results[0].result;
+  }
+
+  // 启动页面监控（CDP：dialog 自动处理 + MutationObserver）
+  async startMonitor(tabId: number): Promise<void> {
+    return cdpStartMonitor(tabId);
+  }
+
+  // 停止监控并返回收集的结果
+  async stopMonitor(tabId: number): Promise<MonitorResult> {
+    return cdpStopMonitor(tabId);
+  }
+
+  // 查询当前 monitor 状态（不停止监控）
+  peekMonitor(tabId: number): MonitorStatus {
+    return cdpPeekMonitor(tabId);
+  }
+
+  // 处理 GM API 请求路由
+  async handleDomApi(request: DomApiRequest): Promise<unknown> {
+    switch (request.action) {
+      case "listTabs":
+        return this.listTabs();
+      case "navigate":
+        return this.navigate(request.url, request.options);
+      case "readPage":
+        return this.readPage(request.options);
+      case "screenshot":
+        return this.screenshot(request.options);
+      case "click":
+        return this.click(request.selector, request.options);
+      case "fill":
+        return this.fill(request.selector, request.value, request.options);
+      case "scroll":
+        return this.scroll(request.direction, request.options);
+      case "waitFor":
+        return this.waitFor(request.selector, request.options);
+      case "executeScript":
+        return this.executeScript(request.code, request.options);
+      case "startMonitor":
+        return this.startMonitor(request.tabId);
+      case "stopMonitor":
+        return this.stopMonitor(request.tabId);
+      case "peekMonitor":
+        return this.peekMonitor(request.tabId);
+      default:
+        throw new Error(`Unknown DOM action: ${(request as any).action}`);
+    }
+  }
+
+  // ---- 辅助方法 ----
+
+  // 不可注入脚本的 URL 协议
+  private static RESTRICTED_PROTOCOLS = ["chrome:", "chrome-extension:", "edge:", "about:", "devtools:"];
+
+  // 检查 URL 是否可以注入脚本
+  private isRestrictedUrl(url: string | undefined): boolean {
+    if (!url) return false;
+    return AgentDomService.RESTRICTED_PROTOCOLS.some((p) => url.startsWith(p));
+  }
+
+  // 解析 tabId，未传则获取当前活动 tab
+  private async resolveTabId(tabId?: number): Promise<number> {
+    if (tabId) {
+      const tab = await chrome.tabs.get(tabId);
+      // 检测是否为受限页面
+      if (this.isRestrictedUrl(tab.url)) {
+        throw new Error(
+          `Cannot operate on restricted page: ${tab.url}. Browser internal pages and extension pages do not allow script injection. Please specify a regular web page tab.`
+        );
+      }
+      // 检测 tab 是否被 discard
+      if (tab.discarded) {
+        await chrome.tabs.reload(tabId);
+        await this.waitForPageLoad(tabId, 30000);
+      }
+      return tabId;
+    }
+    const tabs = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
+    if (tabs.length === 0 || !tabs[0].id) {
+      throw new Error("No active tab found");
+    }
+    // 当前活动标签是受限页面时，提示用户指定目标 tab
+    if (this.isRestrictedUrl(tabs[0].url)) {
+      throw new Error(
+        `Active tab is a restricted page (${tabs[0].url}) which does not allow script injection. Please use dom_list_tabs to find a regular web page and specify its tabId.`
+      );
+    }
+    return tabs[0].id;
+  }
+
+  // 等待页面加载完成
+  private waitForPageLoad(tabId: number, timeout: number): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        chrome.tabs.onUpdated.removeListener(listener);
+        reject(new Error("Page load timed out"));
+      }, timeout);
+
+      const listener = (updatedTabId: number, changeInfo: { status?: string }) => {
+        if (updatedTabId === tabId && changeInfo.status === "complete") {
+          clearTimeout(timer);
+          chrome.tabs.onUpdated.removeListener(listener);
+          resolve();
+        }
+      };
+
+      // 先检查当前状态
+      chrome.tabs.get(tabId).then((tab) => {
+        if (tab.status === "complete") {
+          clearTimeout(timer);
+          resolve();
+        } else {
+          chrome.tabs.onUpdated.addListener(listener);
+        }
+      });
+    });
+  }
+
+  // 默认模式点击
+  private async executeClick(tabId: number, selector: string): Promise<ActionResult> {
+    const tab = await chrome.tabs.get(tabId);
+    const originalUrl = tab.url || "";
+
+    // 监听新 tab 打开
+    let newTabInfo: { tabId: number; url: string } | undefined;
+    const onCreated = (newTab: chrome.tabs.Tab) => {
+      if (newTab.openerTabId === tabId && newTab.id) {
+        newTabInfo = { tabId: newTab.id, url: newTab.pendingUrl || newTab.url || "" };
+      }
+    };
+    chrome.tabs.onCreated.addListener(onCreated);
+
+    try {
+      // 执行点击
+      await chrome.scripting.executeScript({
+        target: { tabId },
+        func: (sel: string) => {
+          const el = document.querySelector(sel);
+          if (!el) throw new Error(`Element not found: ${sel}`);
+          (el as HTMLElement).click();
+        },
+        args: [selector],
+        world: "MAIN",
+      });
+
+      // 等待页面稳定
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      // 收集结果
+      return await this.collectActionResult(tabId, originalUrl, newTabInfo);
+    } finally {
+      chrome.tabs.onCreated.removeListener(onCreated);
+    }
+  }
+
+  // 默认模式填写
+  private async executeFill(tabId: number, selector: string, value: string): Promise<ActionResult> {
+    const tab = await chrome.tabs.get(tabId);
+    const originalUrl = tab.url || "";
+
+    await chrome.scripting.executeScript({
+      target: { tabId },
+      func: (sel: string, val: string) => {
+        const el = document.querySelector(sel) as HTMLInputElement | HTMLTextAreaElement | null;
+        if (!el) throw new Error(`Element not found: ${sel}`);
+        el.focus();
+        // 清空现有值
+        el.value = "";
+        // 设置新值
+        el.value = val;
+        // 触发事件
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        el.dispatchEvent(new Event("change", { bubbles: true }));
+      },
+      args: [selector, value],
+      world: "MAIN",
+    });
+
+    return {
+      success: true,
+      url: originalUrl,
+    };
+  }
+
+  // 收集操作后的状态
+  private async collectActionResult(
+    tabId: number,
+    originalUrl: string,
+    newTabInfo?: { tabId: number; url: string }
+  ): Promise<ActionResult> {
+    let currentUrl = originalUrl;
+    try {
+      const tab = await chrome.tabs.get(tabId);
+      currentUrl = tab.url || originalUrl;
+    } catch {
+      // tab 可能已关闭
+    }
+
+    const navigated = currentUrl !== originalUrl;
+
+    const result: ActionResult = {
+      success: true,
+      navigated,
+      url: currentUrl,
+    };
+
+    if (newTabInfo) {
+      result.newTab = newTabInfo;
+    }
+
+    return result;
+  }
+}
+
+// ---- 注入到页面中执行的函数 ----
+
+// 读取页面 HTML（注入到页面执行）
+function readPageContent(options: ReadPageInjectedOptions): PageContent {
+  const { selector, maxLength, removeTags } = options;
+
+  const root = selector ? document.querySelector(selector) : document.documentElement;
+  if (!root) {
+    return {
+      title: document.title,
+      url: location.href,
+      html: `<error>Element not found: ${selector}</error>`,
+    };
+  }
+
+  // 克隆节点并移除指定标签
+  const clone = root.cloneNode(true) as Element;
+  if (removeTags && removeTags.length > 0) {
+    for (const tag of removeTags) {
+      clone.querySelectorAll(tag).forEach((el) => el.remove());
+    }
+  }
+
+  const html = clone.outerHTML;
+  const result: PageContent = {
+    title: document.title,
+    url: location.href,
+    html,
+  };
+
+  if (html.length > maxLength) {
+    result.truncated = true;
+    result.totalLength = html.length;
+    result.html = html.slice(0, maxLength);
+  }
+
+  return result;
+}
+
+// 滚动操作（注入到页面执行）
+function executeScroll(direction: string, selector: string | null): ScrollResult {
+  const target = selector ? document.querySelector(selector) : document.documentElement;
+  if (!target) throw new Error(`Element not found: ${selector}`);
+
+  const el = selector ? (target as HTMLElement) : document.documentElement;
+  const scrollAmount = window.innerHeight * 0.8;
+
+  switch (direction) {
+    case "up":
+      if (selector) {
+        el.scrollBy(0, -scrollAmount);
+      } else {
+        window.scrollBy(0, -scrollAmount);
+      }
+      break;
+    case "down":
+      if (selector) {
+        el.scrollBy(0, scrollAmount);
+      } else {
+        window.scrollBy(0, scrollAmount);
+      }
+      break;
+    case "top":
+      if (selector) {
+        el.scrollTop = 0;
+      } else {
+        window.scrollTo(0, 0);
+      }
+      break;
+    case "bottom":
+      if (selector) {
+        el.scrollTop = el.scrollHeight;
+      } else {
+        window.scrollTo(0, document.documentElement.scrollHeight);
+      }
+      break;
+  }
+
+  const scrollEl = selector ? el : document.documentElement;
+  return {
+    scrollTop: scrollEl.scrollTop || window.scrollY,
+    scrollHeight: scrollEl.scrollHeight,
+    clientHeight: scrollEl.clientHeight || window.innerHeight,
+    atBottom: scrollEl.scrollTop + scrollEl.clientHeight >= scrollEl.scrollHeight - 10,
+  };
+}
+
+// 检查元素是否存在（注入到页面执行）
+function checkElement(selector: string): WaitForResult | null {
+  const el = document.querySelector(selector);
+  if (!el) return null;
+
+  const htmlEl = el as HTMLElement;
+  const style = window.getComputedStyle(el);
+  const visible = style.display !== "none" && style.visibility !== "hidden";
+
+  // 生成选择器
+  const getSelector = (e: Element): string => {
+    if (e.id) return `#${e.id}`;
+    const tag = e.tagName.toLowerCase();
+    const parent = e.parentElement;
+    if (!parent) return tag;
+    const siblings = Array.from(parent.children).filter((c) => c.tagName === e.tagName);
+    if (siblings.length === 1) return `${getSelector(parent)} > ${tag}`;
+    const index = siblings.indexOf(e) + 1;
+    return `${getSelector(parent)} > ${tag}:nth-of-type(${index})`;
+  };
+
+  return {
+    found: true,
+    element: {
+      selector: getSelector(el),
+      tag: el.tagName.toLowerCase(),
+      text: (htmlEl.textContent || "").trim().slice(0, 100),
+      role: el.getAttribute("role") || undefined,
+      type: el.getAttribute("type") || undefined,
+      visible,
+    },
+  };
+}
diff --git a/src/app/service/service_worker/agent_dom_cdp.test.ts b/src/app/service/service_worker/agent_dom_cdp.test.ts
new file mode 100644
index 000000000..12fed57b9
--- /dev/null
+++ b/src/app/service/service_worker/agent_dom_cdp.test.ts
@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// mock chrome.debugger 和 chrome.tabs
+const mockSendCommand = vi.fn();
+const mockAttach = vi.fn().mockResolvedValue(undefined);
+const mockDetach = vi.fn().mockResolvedValue(undefined);
+const mockTabsGet = vi.fn();
+
+vi.stubGlobal("chrome", {
+  debugger: {
+    attach: mockAttach,
+    detach: mockDetach,
+    sendCommand: mockSendCommand,
+    onEvent: { addListener: vi.fn(), removeListener: vi.fn() },
+  },
+  tabs: { get: mockTabsGet },
+});
+
+import { cdpClick, withDebugger, cdpFill, cdpScreenshot } from "./agent_dom_cdp";
+
+// 构造 sendCommand 的响应映射
+function setupClickMocks(hitTestValue: string) {
+  mockTabsGet.mockResolvedValue({ url: "https://example.com" });
+  mockSendCommand.mockImplementation((_debuggee: unknown, method: string) => {
+    switch (method) {
+      case "DOM.getDocument":
+        return Promise.resolve({ root: { nodeId: 1 } });
+      case "DOM.querySelector":
+        return Promise.resolve({ nodeId: 2 });
+      case "DOM.scrollIntoViewIfNeeded":
+        return Promise.resolve({});
+      case "DOM.getBoxModel":
+        return Promise.resolve({
+          model: { content: [100, 100, 200, 100, 200, 200, 100, 200] },
+        });
+      case "Page.getLayoutMetrics":
+        return Promise.resolve({ visualViewport: { pageX: 0, pageY: 0 } });
+      case "Runtime.evaluate":
+        return Promise.resolve({ result: { value: hitTestValue } });
+      case "Input.dispatchMouseEvent":
+        return Promise.resolve({});
+      default:
+        return Promise.resolve({});
+    }
+  });
+}
+
+describe("agent_dom_cdp", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("模块可正常导入", () => {
+    expect(withDebugger).toBeDefined();
+    expect(cdpClick).toBeDefined();
+    expect(cdpFill).toBeDefined();
+    expect(cdpScreenshot).toBeDefined();
+  });
+
+  it("cdpClick 在元素未被遮挡时正常点击", async () => {
+    setupClickMocks("hit");
+    const result = await cdpClick(999, "#btn");
+    expect(result.success).toBe(true);
+    // 验证 dispatchMouseEvent 被调用（mousePressed + mouseReleased）
+    const mouseEvents = mockSendCommand.mock.calls.filter((c: unknown[]) => c[1] === "Input.dispatchMouseEvent");
+    expect(mouseEvents).toHaveLength(2);
+  }, 1000);
+
+  it("cdpClick 在元素被遮挡时抛出错误", async () => {
+    setupClickMocks("blocked_by:div.modal-overlay");
+    await expect(cdpClick(999, "#btn")).rejects.toThrow(/Click blocked/);
+    // 验证未发送鼠标事件
+    const mouseEvents = mockSendCommand.mock.calls.filter((c: unknown[]) => c[1] === "Input.dispatchMouseEvent");
+    expect(mouseEvents).toHaveLength(0);
+  });
+
+  it("cdpClick 遮挡错误信息包含遮挡元素描述", async () => {
+    setupClickMocks("blocked_by:div#overlay.modal");
+    await expect(cdpClick(999, "#btn")).rejects.toThrow(/blocked_by:div#overlay\.modal/);
+  });
+
+  it("cdpClick 在元素不存在时抛出错误", async () => {
+    mockTabsGet.mockResolvedValue({ url: "https://example.com" });
+    mockSendCommand.mockImplementation((_debuggee: unknown, method: string) => {
+      if (method === "DOM.getDocument") return Promise.resolve({ root: { nodeId: 1 } });
+      if (method === "DOM.querySelector") return Promise.resolve({ nodeId: 0 });
+      return Promise.resolve({});
+    });
+    await expect(cdpClick(999, "#nonexistent")).rejects.toThrow(/Element not found/);
+  });
+});
diff --git a/src/app/service/service_worker/agent_dom_cdp.ts b/src/app/service/service_worker/agent_dom_cdp.ts
new file mode 100644
index 000000000..7def148d8
--- /dev/null
+++ b/src/app/service/service_worker/agent_dom_cdp.ts
@@ -0,0 +1,352 @@
+// CDP（Chrome DevTools Protocol）操作封装
+// 通过 chrome.debugger API 实现真实用户输入模拟（isTrusted=true）
+// 以及页面监控（dialog 自动处理 + DOM 变化捕获）
+
+import type { ActionResult, MonitorResult, ScreenshotOptions } from "@App/app/service/agent/types";
+
+// 活跃的 monitor 会话，key 为 tabId（提前声明，withDebugger 需要检查）
+type MonitorEventListener = (source: chrome.debugger.Debuggee, method: string, params?: any) => void;
+
+type CapturedNode = {
+  nodeId: number;
+  tag: string;
+  id?: string;
+  class?: string;
+  role?: string;
+};
+
+type MonitorSession = {
+  dialogs: Array<{ type: string; message: string }>;
+  capturedNodes: CapturedNode[]; // 从事件中直接提取的节点信息
+  listener: MonitorEventListener;
+};
+
+const activeMonitors = new Map<number, MonitorSession>();
+
+// 生命周期管理：attach → 执行 → detach
+// 如果该 tabId 已有活跃的 monitor（已 attach），则复用连接，不做 attach/detach
+export async function withDebugger<T>(tabId: number, fn: (tabId: number) => Promise<T>): Promise<T> {
+  const hasMonitor = activeMonitors.has(tabId);
+  if (!hasMonitor) {
+    await chrome.debugger.attach({ tabId }, "1.3");
+  }
+  try {
+    return await fn(tabId);
+  } finally {
+    if (!hasMonitor) {
+      try {
+        await chrome.debugger.detach({ tabId });
+      } catch {
+        // tab 可能已经关闭
+      }
+    }
+  }
+}
+
+// 发送 CDP 命令的封装
+function sendCommand(tabId: number, method: string, params?: Record<string, unknown>): Promise<any> {
+  return chrome.debugger.sendCommand({ tabId }, method, params);
+}
+
+// 通过 CDP 点击元素
+export async function cdpClick(tabId: number, selector: string): Promise<ActionResult> {
+  const originalUrl = (await chrome.tabs.get(tabId)).url || "";
+
+  // 定位元素
+  const doc = await sendCommand(tabId, "DOM.getDocument");
+  const nodeId = await sendCommand(tabId, "DOM.querySelector", {
+    nodeId: doc.root.nodeId,
+    selector,
+  });
+  if (!nodeId?.nodeId) {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  // 滚动到可见位置
+  await sendCommand(tabId, "DOM.scrollIntoViewIfNeeded", { nodeId: nodeId.nodeId });
+
+  // 获取元素中心的页面坐标
+  const boxModel = await sendCommand(tabId, "DOM.getBoxModel", { nodeId: nodeId.nodeId });
+  if (!boxModel?.model) {
+    throw new Error(`Cannot get box model for: ${selector}`);
+  }
+  const content = boxModel.model.content;
+  // content 是 [x1,y1, x2,y2, x3,y3, x4,y4] 四个角的页面坐标
+  const pageX = (content[0] + content[2] + content[4] + content[6]) / 4;
+  const pageY = (content[1] + content[3] + content[5] + content[7]) / 4;
+
+  // 将页面坐标转为视口坐标（Input.dispatchMouseEvent 需要视口相对坐标）
+  const metrics = await sendCommand(tabId, "Page.getLayoutMetrics");
+  const viewportX = pageX - (metrics.visualViewport?.pageX ?? 0);
+  const viewportY = pageY - (metrics.visualViewport?.pageY ?? 0);
+
+  // 遮挡检测：检查该坐标处实际命中的元素是否是目标元素（或其子元素）
+  const selectorStr = JSON.stringify(selector);
+  const hitTest = await sendCommand(tabId, "Runtime.evaluate", {
+    expression: `(() => {
+      const el = document.elementFromPoint(${viewportX}, ${viewportY});
+      const target = document.querySelector(${selectorStr});
+      if (!el || !target) return 'not_found';
+      if (target.contains(el) || el === target) return 'hit';
+      return 'blocked_by:' + el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + (el.className ? '.' + String(el.className).split(' ').join('.') : '');
+    })()`,
+    returnByValue: true,
+  });
+  const hitValue = hitTest?.result?.value;
+  if (typeof hitValue === "string" && hitValue !== "hit") {
+    throw new Error(
+      `Click blocked: element at (${Math.round(viewportX)},${Math.round(viewportY)}) is ${hitValue}, not "${selector}"`
+    );
+  }
+
+  // 模拟鼠标点击
+  await sendCommand(tabId, "Input.dispatchMouseEvent", {
+    type: "mousePressed",
+    x: viewportX,
+    y: viewportY,
+    button: "left",
+    clickCount: 1,
+  });
+  await sendCommand(tabId, "Input.dispatchMouseEvent", {
+    type: "mouseReleased",
+    x: viewportX,
+    y: viewportY,
+    button: "left",
+    clickCount: 1,
+  });
+
+  // 等待页面稳定
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  // 收集结果
+  const tab = await chrome.tabs.get(tabId);
+  const currentUrl = tab.url || "";
+  return {
+    success: true,
+    navigated: currentUrl !== originalUrl,
+    url: currentUrl,
+  };
+}
+
+// 通过 CDP 填写表单
+export async function cdpFill(tabId: number, selector: string, value: string): Promise<ActionResult> {
+  const originalUrl = (await chrome.tabs.get(tabId)).url || "";
+
+  // 定位元素
+  const doc = await sendCommand(tabId, "DOM.getDocument");
+  const nodeId = await sendCommand(tabId, "DOM.querySelector", {
+    nodeId: doc.root.nodeId,
+    selector,
+  });
+  if (!nodeId?.nodeId) {
+    throw new Error(`Element not found: ${selector}`);
+  }
+
+  // 聚焦元素
+  await sendCommand(tabId, "DOM.focus", { nodeId: nodeId.nodeId });
+
+  // 全选并删除现有内容
+  await sendCommand(tabId, "Input.dispatchKeyEvent", {
+    type: "keyDown",
+    key: "a",
+    code: "KeyA",
+    modifiers: 2, // Ctrl
+  });
+  await sendCommand(tabId, "Input.dispatchKeyEvent", {
+    type: "keyUp",
+    key: "a",
+    code: "KeyA",
+    modifiers: 2,
+  });
+  await sendCommand(tabId, "Input.dispatchKeyEvent", {
+    type: "keyDown",
+    key: "Delete",
+    code: "Delete",
+  });
+  await sendCommand(tabId, "Input.dispatchKeyEvent", {
+    type: "keyUp",
+    key: "Delete",
+    code: "Delete",
+  });
+
+  // 逐字符输入
+  for (const char of value) {
+    await sendCommand(tabId, "Input.dispatchKeyEvent", {
+      type: "keyDown",
+      key: char,
+    });
+    await sendCommand(tabId, "Input.dispatchKeyEvent", {
+      type: "char",
+      text: char,
+    });
+    await sendCommand(tabId, "Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key: char,
+    });
+  }
+
+  // 等待页面稳定
+  await new Promise((resolve) => setTimeout(resolve, 200));
+
+  return {
+    success: true,
+    url: originalUrl,
+  };
+}
+
+// 通过 CDP 截图
+export async function cdpScreenshot(tabId: number, options?: ScreenshotOptions): Promise<string> {
+  const quality = options?.quality ?? 80;
+  const result = await sendCommand(tabId, "Page.captureScreenshot", {
+    format: "jpeg",
+    quality,
+    captureBeyondViewport: options?.fullPage ?? false,
+  });
+  return `data:image/jpeg;base64,${result.data}`;
+}
+
+// ---- 页面监控（startMonitor / stopMonitor） ----
+
+// 启动页面监控：attach debugger，纯 CDP 事件监听（dialog + DOM 变化），零注入
+export async function cdpStartMonitor(tabId: number): Promise<void> {
+  // 如果已有 monitor，先停止
+  if (activeMonitors.has(tabId)) {
+    await cdpStopMonitor(tabId);
+  }
+
+  const dialogs: Array<{ type: string; message: string }> = [];
+  const capturedNodes: CapturedNode[] = [];
+
+  // attach debugger
+  await chrome.debugger.attach({ tabId }, "1.3");
+  await sendCommand(tabId, "Page.enable");
+  await sendCommand(tabId, "DOM.enable");
+
+  // 获取 document root，触发 DOM 树追踪
+  await sendCommand(tabId, "DOM.getDocument", { depth: 0 });
+
+  // 监听 CDP 事件
+  const listener: MonitorEventListener = (source, method, params) => {
+    if (source.tabId !== tabId) return;
+
+    // JS 弹框（alert/confirm/prompt）
+    if (method === "Page.javascriptDialogOpening") {
+      dialogs.push({
+        type: String(params?.type || "alert"),
+        message: String(params?.message || ""),
+      });
+      sendCommand(tabId, "Page.handleJavaScriptDialog", { accept: true }).catch(() => {});
+    }
+
+    // DOM 新增子节点：直接从事件的 node 对象提取属性
+    if (method === "DOM.childNodeInserted") {
+      const node = params?.node;
+      if (node && node.nodeType === 1) {
+        // node.attributes 是 [name, value, name, value, ...] 扁平数组
+        const attrs: Record<string, string> = {};
+        if (node.attributes) {
+          for (let i = 0; i < node.attributes.length; i += 2) {
+            attrs[node.attributes[i]] = node.attributes[i + 1];
+          }
+        }
+        capturedNodes.push({
+          nodeId: node.nodeId,
+          tag: (node.localName || node.nodeName || "").toLowerCase(),
+          id: attrs.id || undefined,
+          class: attrs.class || undefined,
+          role: attrs.role || undefined,
+        });
+      }
+    }
+  };
+  chrome.debugger.onEvent.addListener(listener);
+
+  activeMonitors.set(tabId, { dialogs, capturedNodes, listener });
+}
+
+// 轻量查询当前 monitor 状态（不停止监控）
+export function cdpPeekMonitor(tabId: number): { hasChanges: boolean; dialogCount: number; nodeCount: number } {
+  const monitor = activeMonitors.get(tabId);
+  if (!monitor) {
+    return { hasChanges: false, dialogCount: 0, nodeCount: 0 };
+  }
+  const dialogCount = monitor.dialogs.length;
+  const nodeCount = monitor.capturedNodes.length;
+  return { hasChanges: dialogCount > 0 || nodeCount > 0, dialogCount, nodeCount };
+}
+
+// 从 outerHTML 中提取纯文本（去除所有标签）
+function stripHtmlTags(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+// 停止监控：纯 CDP 解析新增节点 → 收集结果 → detach
+export async function cdpStopMonitor(tabId: number): Promise<MonitorResult> {
+  const monitor = activeMonitors.get(tabId);
+  const result: MonitorResult = {
+    dialogs: monitor?.dialogs || [],
+    addedNodes: [],
+  };
+
+  if (monitor && monitor.capturedNodes.length > 0) {
+    // 去重（按 nodeId）并限制数量
+    const seen = new Set<number>();
+    const uniqueNodes = monitor.capturedNodes
+      .filter((n) => {
+        if (seen.has(n.nodeId)) return false;
+        seen.add(n.nodeId);
+        return true;
+      })
+      .slice(0, 50);
+
+    for (const captured of uniqueNodes) {
+      try {
+        // 用 DOM.getBoxModel 检测可见性：不可见/未渲染的元素会抛异常
+        await sendCommand(tabId, "DOM.getBoxModel", { nodeId: captured.nodeId });
+
+        // 用 DOM.getOuterHTML 获取内容，纯 CDP 无需注入 JS
+        const htmlResult = await sendCommand(tabId, "DOM.getOuterHTML", { nodeId: captured.nodeId });
+        const outerHTML: string = htmlResult?.outerHTML || "";
+        const text = stripHtmlTags(outerHTML).slice(0, 300);
+        if (!text) continue;
+
+        result.addedNodes.push({
+          tag: captured.tag,
+          id: captured.id,
+          class: captured.class,
+          role: captured.role,
+          text,
+        });
+      } catch {
+        // 节点可能已被移除或不可见，跳过
+      }
+    }
+  }
+
+  // 清理
+  if (monitor) {
+    chrome.debugger.onEvent.removeListener(monitor.listener);
+    activeMonitors.delete(tabId);
+  }
+
+  try {
+    await sendCommand(tabId, "DOM.disable");
+  } catch {
+    /* 忽略 */
+  }
+  try {
+    await sendCommand(tabId, "Page.disable");
+  } catch {
+    /* 忽略 */
+  }
+  try {
+    await chrome.debugger.detach({ tabId });
+  } catch {
+    /* 忽略 */
+  }
+
+  return result;
+}
diff --git a/src/app/service/service_worker/agent_mcp.test.ts b/src/app/service/service_worker/agent_mcp.test.ts
new file mode 100644
index 000000000..640e8f83d
--- /dev/null
+++ b/src/app/service/service_worker/agent_mcp.test.ts
@@ -0,0 +1,207 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { MCPService } from "./agent_mcp";
+import { ToolRegistry } from "@App/app/service/agent/tool_registry";
+
+// 共享的服务器存储
+const servers = new Map<string, any>();
+
+// Mock MCPServerRepo
+vi.mock("@App/app/repo/mcp_server_repo", () => {
+  return {
+    MCPServerRepo: class {
+      async listServers() {
+        return Array.from(servers.values());
+      }
+      async getServer(id: string) {
+        return servers.get(id);
+      }
+      async saveServer(config: any) {
+        servers.set(config.id, config);
+      }
+      async removeServer(id: string) {
+        servers.delete(id);
+      }
+    },
+  };
+});
+
+// Mock MCPClient
+vi.mock("@App/app/service/agent/mcp_client", () => {
+  return {
+    MCPClient: class {
+      async initialize() {}
+      async listTools() {
+        return [
+          {
+            serverId: "test-server",
+            name: "search",
+            description: "Search the web",
+            inputSchema: { type: "object", properties: { query: { type: "string" } } },
+          },
+        ];
+      }
+      async listResources() {
+        return [{ serverId: "test-server", uri: "file:///test.md", name: "test", mimeType: "text/markdown" }];
+      }
+      async listPrompts() {
+        return [{ serverId: "test-server", name: "summarize", description: "Summarize text" }];
+      }
+      async callTool() {
+        return "tool result";
+      }
+      async readResource() {
+        return { contents: [{ uri: "file:///test.md", text: "# Test" }] };
+      }
+      async getPrompt() {
+        return [{ role: "user", content: { type: "text", text: "Hello" } }];
+      }
+      close() {}
+      isInitialized() {
+        return true;
+      }
+    },
+  };
+});
+
+// Mock uuid
+vi.mock("@App/pkg/utils/uuid", () => ({
+  uuidv4: vi.fn(() => "mock-uuid-123"),
+}));
+
+describe("MCPService", () => {
+  let toolRegistry: ToolRegistry;
+  let service: MCPService;
+
+  beforeEach(() => {
+    servers.clear();
+    toolRegistry = new ToolRegistry();
+    service = new MCPService(toolRegistry);
+  });
+
+  describe("handleMCPApi - addServer", () => {
+    it("应添加服务器", async () => {
+      const result = (await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "Test", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      })) as any;
+
+      expect(typeof result.id).toBe("string");
+      expect(result.id.length).toBeGreaterThan(0);
+      expect(result.name).toBe("Test");
+      expect(result.url).toBe("https://mcp.test.com");
+    });
+  });
+
+  describe("handleMCPApi - listServers", () => {
+    it("应列出所有服务器", async () => {
+      await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "Test", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      });
+
+      const result = (await service.handleMCPApi({
+        action: "listServers",
+        scriptUuid: "test",
+      })) as any[];
+
+      expect(result.length).toBe(1);
+    });
+  });
+
+  describe("handleMCPApi - removeServer", () => {
+    it("应删除服务器", async () => {
+      const server = (await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "Test", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      })) as any;
+
+      const result = await service.handleMCPApi({
+        action: "removeServer",
+        id: server.id,
+        scriptUuid: "test",
+      });
+
+      expect(result).toBe(true);
+    });
+  });
+
+  describe("connectServer / disconnectServer", () => {
+    it("连接后应将工具注册到 ToolRegistry", async () => {
+      const server = (await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "TestSrv", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      })) as any;
+
+      await service.connectServer(server.id);
+
+      const defs = toolRegistry.getDefinitions();
+      expect(defs.length).toBe(1);
+      expect(defs[0].name).toContain("search");
+    });
+
+    it("断开后应注销工具", async () => {
+      const server = (await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "TestSrv", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      })) as any;
+
+      await service.connectServer(server.id);
+      expect(toolRegistry.getDefinitions().length).toBe(1);
+
+      await service.disconnectServer(server.id);
+      expect(toolRegistry.getDefinitions().length).toBe(0);
+    });
+  });
+
+  describe("handleMCPApi - listTools", () => {
+    it("应通过懒连接获取工具列表", async () => {
+      const server = (await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "Test", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      })) as any;
+
+      const tools = (await service.handleMCPApi({
+        action: "listTools",
+        serverId: server.id,
+        scriptUuid: "test",
+      })) as any[];
+
+      expect(tools).toHaveLength(1);
+      expect(tools[0].name).toBe("search");
+    });
+  });
+
+  describe("handleMCPApi - testConnection", () => {
+    it("应返回工具、资源、提示词数量", async () => {
+      const server = (await service.handleMCPApi({
+        action: "addServer",
+        config: { name: "Test", url: "https://mcp.test.com", enabled: false },
+        scriptUuid: "test",
+      })) as any;
+
+      const result = (await service.handleMCPApi({
+        action: "testConnection",
+        id: server.id,
+        scriptUuid: "test",
+      })) as any;
+
+      expect(result.tools).toBe(1);
+      expect(result.resources).toBe(1);
+      expect(result.prompts).toBe(1);
+    });
+  });
+
+  describe("handleMCPApi - unknown action", () => {
+    it("应抛出错误", async () => {
+      await expect(service.handleMCPApi({ action: "unknown" as any, scriptUuid: "test" })).rejects.toThrow(
+        "Unknown MCP action"
+      );
+    });
+  });
+});
diff --git a/src/app/service/service_worker/agent_mcp.ts b/src/app/service/service_worker/agent_mcp.ts
new file mode 100644
index 000000000..78a47adb1
--- /dev/null
+++ b/src/app/service/service_worker/agent_mcp.ts
@@ -0,0 +1,230 @@
+import type { MCPApiRequest, MCPServerConfig, MCPTool, ToolDefinition } from "@App/app/service/agent/types";
+import { MCPClient } from "@App/app/service/agent/mcp_client";
+import { MCPToolExecutor } from "@App/app/service/agent/mcp_tool_executor";
+import { MCPServerRepo } from "@App/app/repo/mcp_server_repo";
+import type { ToolRegistry } from "@App/app/service/agent/tool_registry";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+// 将服务器名和工具名合成为全局唯一的工具名
+function mcpToolName(serverName: string, toolName: string): string {
+  // 使用小写字母和下划线，避免特殊字符
+  const safeName = serverName.replace(/[^a-zA-Z0-9]/g, "_").toLowerCase();
+  return `mcp_${safeName}_${toolName}`;
+}
+
+// MCPService 管理 MCP 服务器连接池和工具注册
+export class MCPService {
+  private repo = new MCPServerRepo();
+  private clients = new Map<string, MCPClient>();
+  // 记录每个服务器注册的工具名，便于注销
+  private registeredTools = new Map<string, string[]>();
+
+  constructor(private toolRegistry: ToolRegistry) {}
+
+  // 加载所有已保存的服务器配置，自动连接已启用的服务器
+  async init(): Promise<void> {
+    try {
+      const servers = await this.repo.listServers();
+      for (const server of servers) {
+        if (server.enabled) {
+          try {
+            await this.connectServer(server.id);
+          } catch {
+            // 连接失败不影响其他服务器
+          }
+        }
+      }
+    } catch {
+      // 加载失败静默忽略
+    }
+  }
+
+  // 连接服务器：创建 MCPClient，初始化，列出工具，注册到 ToolRegistry
+  async connectServer(id: string): Promise<MCPTool[]> {
+    const config = await this.repo.getServer(id);
+    if (!config) {
+      throw new Error(`MCP server "${id}" not found`);
+    }
+
+    // 如果已连接，先断开
+    if (this.clients.has(id)) {
+      await this.disconnectServer(id);
+    }
+
+    const client = new MCPClient(config);
+    await client.initialize();
+
+    // 列出工具
+    const tools = await client.listTools();
+    this.clients.set(id, client);
+
+    // 注册工具到 ToolRegistry
+    const toolNames: string[] = [];
+    for (const tool of tools) {
+      const name = mcpToolName(config.name, tool.name);
+      const definition: ToolDefinition = {
+        name,
+        description: `[MCP: ${config.name}] ${tool.description || tool.name}`,
+        parameters: tool.inputSchema,
+      };
+      this.toolRegistry.registerBuiltin(definition, new MCPToolExecutor(client, tool.name));
+      toolNames.push(name);
+    }
+    this.registeredTools.set(id, toolNames);
+
+    return tools;
+  }
+
+  // 确保服务器已连接（懒连接）
+  private async ensureConnected(serverId: string): Promise<MCPClient> {
+    let client = this.clients.get(serverId);
+    if (client && client.isInitialized()) {
+      return client;
+    }
+    await this.connectServer(serverId);
+    client = this.clients.get(serverId);
+    if (!client) {
+      throw new Error(`Failed to connect to MCP server "${serverId}"`);
+    }
+    return client;
+  }
+
+  // 断开服务器连接，注销所有工具
+  async disconnectServer(id: string): Promise<void> {
+    const toolNames = this.registeredTools.get(id);
+    if (toolNames) {
+      for (const name of toolNames) {
+        this.toolRegistry.unregisterBuiltin(name);
+      }
+      this.registeredTools.delete(id);
+    }
+
+    const client = this.clients.get(id);
+    if (client) {
+      client.close();
+      this.clients.delete(id);
+    }
+  }
+
+  // 测试连接：初始化 + listTools
+  async testConnection(id: string): Promise<{ tools: number; resources: number; prompts: number }> {
+    const config = await this.repo.getServer(id);
+    if (!config) {
+      throw new Error(`MCP server "${id}" not found`);
+    }
+
+    const client = new MCPClient(config);
+    try {
+      await client.initialize();
+      const [tools, resources, prompts] = await Promise.all([
+        client.listTools().catch(() => []),
+        client.listResources().catch(() => []),
+        client.listPrompts().catch(() => []),
+      ]);
+      return {
+        tools: tools.length,
+        resources: resources.length,
+        prompts: prompts.length,
+      };
+    } finally {
+      client.close();
+    }
+  }
+
+  // 处理 MCP API 请求
+  async handleMCPApi(request: MCPApiRequest): Promise<unknown> {
+    switch (request.action) {
+      case "listServers":
+        return this.repo.listServers();
+
+      case "getServer": {
+        const server = await this.repo.getServer(request.id);
+        if (!server) throw new Error(`MCP server "${request.id}" not found`);
+        return server;
+      }
+
+      case "addServer": {
+        const now = Date.now();
+        const config: MCPServerConfig = {
+          ...request.config,
+          id: uuidv4(),
+          createtime: now,
+          updatetime: now,
+        };
+        await this.repo.saveServer(config);
+        // 如果启用了，连接服务器
+        if (config.enabled) {
+          try {
+            await this.connectServer(config.id);
+          } catch {
+            // 连接失败不影响保存
+          }
+        }
+        return config;
+      }
+
+      case "updateServer": {
+        const existing = await this.repo.getServer(request.id);
+        if (!existing) throw new Error(`MCP server "${request.id}" not found`);
+        const updated: MCPServerConfig = {
+          ...existing,
+          ...request.config,
+          id: existing.id, // 不允许修改 ID
+          createtime: existing.createtime, // 不允许修改创建时间
+          updatetime: Date.now(),
+        };
+        await this.repo.saveServer(updated);
+
+        // 处理 enabled 状态变更
+        if (updated.enabled && !this.clients.has(request.id)) {
+          try {
+            await this.connectServer(request.id);
+          } catch {
+            // 连接失败不影响保存
+          }
+        } else if (!updated.enabled && this.clients.has(request.id)) {
+          await this.disconnectServer(request.id);
+        }
+
+        return updated;
+      }
+
+      case "removeServer": {
+        await this.disconnectServer(request.id);
+        await this.repo.removeServer(request.id);
+        return true;
+      }
+
+      case "listTools": {
+        const client = await this.ensureConnected(request.serverId);
+        return client.listTools();
+      }
+
+      case "listResources": {
+        const client = await this.ensureConnected(request.serverId);
+        return client.listResources();
+      }
+
+      case "readResource": {
+        const client = await this.ensureConnected(request.serverId);
+        return client.readResource(request.uri);
+      }
+
+      case "listPrompts": {
+        const client = await this.ensureConnected(request.serverId);
+        return client.listPrompts();
+      }
+
+      case "getPrompt": {
+        const client = await this.ensureConnected(request.serverId);
+        return client.getPrompt(request.name, request.args);
+      }
+
+      case "testConnection":
+        return this.testConnection(request.id);
+
+      default:
+        throw new Error(`Unknown MCP action: ${(request as any).action}`);
+    }
+  }
+}
diff --git a/src/app/service/service_worker/client.ts b/src/app/service/service_worker/client.ts
index 0961b1f16..4d7c47d0f 100644
--- a/src/app/service/service_worker/client.ts
+++ b/src/app/service/service_worker/client.ts
@@ -11,7 +11,14 @@ import { type FileSystemType } from "@Packages/filesystem/factory";
 import { type ResourceBackup } from "@App/pkg/backup/struct";
 import { type VSCodeConnect } from "../offscreen/vscode-connect";
 import { type ScriptInfo } from "@App/pkg/utils/scriptInstall";
-import type { ScriptService, TCheckScriptUpdateOption, TOpenBatchUpdatePageOption } from "./script";
+import type { SkillConfigField } from "@App/app/service/agent/types";
+import type {
+  ScriptService,
+  TCheckScriptUpdateOption,
+  TOpenBatchUpdatePageOption,
+  TScriptInstallParam,
+  TScriptInstallReturn,
+} from "./script";
 import { encodeRValue, type TKeyValuePair } from "@App/pkg/utils/message_value";
 import { type TSetValuesParams } from "./value";
 
@@ -40,15 +47,9 @@ export class ScriptClient extends Client {
     return this.do<[boolean, ScriptInfo, { byWebRequest?: boolean }]>("getInstallInfo", uuid);
   }
 
-  install(params: {
-    script: Script;
-    code: string;
-    upsertBy?: InstallSource;
-    createtime?: number;
-    updatetime?: number;
-  }): Promise<{ update: boolean }> {
+  install(params: TScriptInstallParam): Promise<TScriptInstallReturn> {
     if (!params.upsertBy) params.upsertBy = "user";
-    return this.doThrow("install", { ...params });
+    return this.doThrow("install", { ...params } satisfies TScriptInstallParam);
   }
 
   // delete(uuid: string) {
@@ -328,3 +329,80 @@ export class SystemClient extends Client {
     return this.do("connectVSCode", params);
   }
 }
+
+export class AgentClient extends Client {
+  constructor(msgSender: MessageSend) {
+    super(msgSender, "serviceWorker/agent");
+  }
+
+  installCATTool(code: string): Promise<unknown> {
+    return this.do("installCATTool", code);
+  }
+
+  getCATToolInstallCode(uuid: string): Promise<{ code: string; scriptName?: string; isUpdate?: boolean }> {
+    return this.doThrow("getCATToolInstallCode", uuid);
+  }
+
+  completeCATToolInstall(uuid: string): Promise<void> {
+    return this.do("completeCATToolInstall", uuid);
+  }
+
+  cancelCATToolInstall(uuid: string): Promise<void> {
+    return this.do("cancelCATToolInstall", uuid);
+  }
+
+  removeCATTool(name: string): Promise<boolean> {
+    return this.doThrow("removeCATTool", name);
+  }
+
+  installSkill(params: {
+    skillMd: string;
+    scripts?: Array<{ name: string; code: string }>;
+    references?: Array<{ name: string; content: string }>;
+  }): Promise<unknown> {
+    return this.do("installSkill", params);
+  }
+
+  removeSkill(name: string): Promise<unknown> {
+    return this.do("removeSkill", name);
+  }
+
+  refreshSkill(name: string): Promise<boolean> {
+    return this.doThrow("refreshSkill", name);
+  }
+
+  prepareSkillInstall(zipBase64: string): Promise<string> {
+    return this.doThrow("prepareSkillInstall", zipBase64);
+  }
+
+  getSkillInstallData(uuid: string): Promise<{
+    skillMd: string;
+    metadata: {
+      name: string;
+      description: string;
+      config?: Record<string, SkillConfigField>;
+    };
+    prompt: string;
+    scripts: Array<{ name: string; code: string }>;
+    references: Array<{ name: string; content: string }>;
+    isUpdate: boolean;
+  }> {
+    return this.doThrow("getSkillInstallData", uuid);
+  }
+
+  completeSkillInstall(uuid: string): Promise<unknown> {
+    return this.doThrow("completeSkillInstall", uuid);
+  }
+
+  cancelSkillInstall(uuid: string): Promise<void> {
+    return this.do("cancelSkillInstall", uuid);
+  }
+
+  getSkillConfigValues(name: string): Promise<Record<string, unknown>> {
+    return this.doThrow("getSkillConfigValues", name);
+  }
+
+  saveSkillConfig(params: { name: string; values: Record<string, unknown> }): Promise<void> {
+    return this.doThrow("saveSkillConfig", params);
+  }
+}
diff --git a/src/app/service/service_worker/gm_api/gm_agent.ts b/src/app/service/service_worker/gm_api/gm_agent.ts
new file mode 100644
index 000000000..7518b5bed
--- /dev/null
+++ b/src/app/service/service_worker/gm_api/gm_agent.ts
@@ -0,0 +1,57 @@
+// Agent API 方法，通过 PermissionVerify.API 装饰器注册到全局 API Map
+// 运行时 this 绑定为 GMApi 实例（由 handlerRequest 中的 api.api.call(this, ...) 实现）
+
+import type { IGetSender } from "@Packages/message/server";
+import type { ConfirmParam } from "../permission_verify";
+import PermissionVerify, { type ApiParamConfirmFn } from "../permission_verify";
+import type { GMApiRequest } from "../types";
+import type { ConversationApiRequest } from "@App/app/service/agent/types";
+import i18next, { i18nName } from "@App/locales/locales";
+import type GMApi from "./gm_api";
+
+// Agent API 共用的权限确认逻辑
+const agentConfirm: ApiParamConfirmFn = async (request: GMApiRequest, _sender: IGetSender, gmApi: GMApi) => {
+  const ret = await gmApi.permissionVerify.queryPermission(request, {
+    permission: "agent.conversation",
+  });
+  if (ret && ret.allow) return true;
+  const metadata: { [key: string]: string } = {};
+  metadata[i18next.t("script_name")] = i18nName(request.script);
+  return {
+    permission: "agent.conversation",
+    title: i18next.t("agent_permission_title"),
+    metadata,
+    describe: i18next.t("agent_permission_describe"),
+    permissionContent: i18next.t("agent_permission_content"),
+  } as ConfirmParam;
+};
+
+// 独立类，仅用于承载装饰器注册
+// 方法在运行时通过 call(gmApiInstance, ...) 执行，this 指向 GMApi
+class GMAgentApi {
+  @PermissionVerify.API({
+    link: ["CAT.agent.conversation"],
+    confirm: agentConfirm,
+    dotAlias: false,
+  })
+  CAT_agentConversation(this: GMApi, request: GMApiRequest<[ConversationApiRequest]>, _sender: IGetSender) {
+    if (!this.agentService) {
+      throw new Error("AgentService is not available");
+    }
+    return this.agentService.handleConversationApi(request.params[0]);
+  }
+
+  @PermissionVerify.API({
+    link: ["CAT.agent.conversation"],
+    confirm: agentConfirm,
+    dotAlias: false,
+  })
+  async CAT_agentConversationChat(this: GMApi, request: GMApiRequest<[any]>, sender: IGetSender) {
+    if (!this.agentService) {
+      throw new Error("AgentService is not available");
+    }
+    return this.agentService.handleConversationChatFromGmApi(request.params[0], sender);
+  }
+}
+
+export default GMAgentApi;
diff --git a/src/app/service/service_worker/gm_api/gm_agent_dom.ts b/src/app/service/service_worker/gm_api/gm_agent_dom.ts
new file mode 100644
index 000000000..7bbea8107
--- /dev/null
+++ b/src/app/service/service_worker/gm_api/gm_agent_dom.ts
@@ -0,0 +1,43 @@
+// Agent DOM API 方法，通过 PermissionVerify.API 装饰器注册到全局 API Map
+// 运行时 this 绑定为 GMApi 实例
+
+import type { IGetSender } from "@Packages/message/server";
+import type { ConfirmParam } from "../permission_verify";
+import PermissionVerify, { type ApiParamConfirmFn } from "../permission_verify";
+import type { GMApiRequest } from "../types";
+import type { DomApiRequest } from "@App/app/service/agent/types";
+import i18next, { i18nName } from "@App/locales/locales";
+import type GMApi from "./gm_api";
+
+// DOM API 权限确认逻辑
+const agentDomConfirm: ApiParamConfirmFn = async (request: GMApiRequest, _sender: IGetSender, gmApi: GMApi) => {
+  const ret = await gmApi.permissionVerify.queryPermission(request, {
+    permission: "agent.dom",
+  });
+  if (ret && ret.allow) return true;
+  const metadata: { [key: string]: string } = {};
+  metadata[i18next.t("script_name")] = i18nName(request.script);
+  return {
+    permission: "agent.dom",
+    title: i18next.t("agent_dom_permission_title"),
+    metadata,
+    describe: i18next.t("agent_dom_permission_describe"),
+    permissionContent: i18next.t("agent_dom_permission_content"),
+  } as ConfirmParam;
+};
+
+class GMAgentDomApi {
+  @PermissionVerify.API({
+    link: ["CAT.agent.dom"],
+    confirm: agentDomConfirm,
+    dotAlias: false,
+  })
+  CAT_agentDom(this: GMApi, request: GMApiRequest<[DomApiRequest]>, _sender: IGetSender) {
+    if (!this.agentService) {
+      throw new Error("AgentService is not available");
+    }
+    return this.agentService.handleDomApi(request.params[0]);
+  }
+}
+
+export default GMAgentDomApi;
diff --git a/src/app/service/service_worker/gm_api/gm_agent_skills.ts b/src/app/service/service_worker/gm_api/gm_agent_skills.ts
new file mode 100644
index 000000000..63835ecba
--- /dev/null
+++ b/src/app/service/service_worker/gm_api/gm_agent_skills.ts
@@ -0,0 +1,57 @@
+// Skill API 方法，通过 PermissionVerify.API 装饰器注册到全局 API Map
+// 运行时 this 绑定为 GMApi 实例
+
+import type { IGetSender } from "@Packages/message/server";
+import type { ConfirmParam } from "../permission_verify";
+import PermissionVerify, { type ApiParamConfirmFn } from "../permission_verify";
+import type { GMApiRequest } from "../types";
+import type { SkillApiRequest } from "@App/app/service/agent/types";
+import i18next, { i18nName } from "@App/locales/locales";
+import type GMApi from "./gm_api";
+
+// 写操作（install/remove）每次都需弹窗确认
+const agentConfirm: ApiParamConfirmFn = async (request: GMApiRequest, _sender: IGetSender, gmApi: GMApi) => {
+  const skillsReq = request.params[0] as SkillApiRequest;
+  const isWrite = skillsReq.action === "install" || skillsReq.action === "remove";
+
+  if (isWrite) {
+    // 写操作：仅查询 DB 中的持久化授权，跳过缓存
+    const ret = await gmApi.permissionVerify.queryPersistentPermission(request, {
+      permission: "agent.skills",
+    });
+    if (ret && ret.allow) return true;
+  } else {
+    // 读操作：缓存 + DB
+    const ret = await gmApi.permissionVerify.queryPermission(request, {
+      permission: "agent.skills",
+    });
+    if (ret && ret.allow) return true;
+  }
+
+  const metadata: { [key: string]: string } = {};
+  metadata[i18next.t("script_name")] = i18nName(request.script);
+  return {
+    permission: "agent.skills",
+    title: i18next.t("agent_permission_title"),
+    metadata,
+    describe: i18next.t("agent_permission_describe"),
+    permissionContent: i18next.t("agent_permission_content"),
+    persistentOnly: isWrite,
+  } as ConfirmParam;
+};
+
+class GMAgentSkillsApi {
+  @PermissionVerify.API({
+    link: ["CAT.agent.skills"],
+    confirm: agentConfirm,
+    dotAlias: false,
+  })
+  CAT_agentSkills(this: GMApi, request: GMApiRequest<[SkillApiRequest]>, _sender: IGetSender) {
+    if (!this.agentService) {
+      throw new Error("AgentService is not available");
+    }
+    return this.agentService.handleSkillsApi(request.params[0]);
+  }
+}
+
+export default GMAgentSkillsApi;
diff --git a/src/app/service/service_worker/gm_api/gm_agent_task.ts b/src/app/service/service_worker/gm_api/gm_agent_task.ts
new file mode 100644
index 000000000..d689d0520
--- /dev/null
+++ b/src/app/service/service_worker/gm_api/gm_agent_task.ts
@@ -0,0 +1,43 @@
+// Agent Task API 方法，通过 PermissionVerify.API 装饰器注册到全局 API Map
+// 运行时 this 绑定为 GMApi 实例
+
+import type { IGetSender } from "@Packages/message/server";
+import type { ConfirmParam } from "../permission_verify";
+import PermissionVerify, { type ApiParamConfirmFn } from "../permission_verify";
+import type { GMApiRequest } from "../types";
+import type { AgentTaskApiRequest } from "@App/app/service/agent/types";
+import i18next, { i18nName } from "@App/locales/locales";
+import type GMApi from "./gm_api";
+
+// 复用 Agent API 的权限确认逻辑
+const agentTaskConfirm: ApiParamConfirmFn = async (request: GMApiRequest, _sender: IGetSender, gmApi: GMApi) => {
+  const ret = await gmApi.permissionVerify.queryPermission(request, {
+    permission: "agent.task",
+  });
+  if (ret && ret.allow) return true;
+  const metadata: { [key: string]: string } = {};
+  metadata[i18next.t("script_name")] = i18nName(request.script);
+  return {
+    permission: "agent.task",
+    title: i18next.t("agent_permission_title"),
+    metadata,
+    describe: i18next.t("agent_permission_describe"),
+    permissionContent: i18next.t("agent_permission_content"),
+  } as ConfirmParam;
+};
+
+class GMAgentTaskApi {
+  @PermissionVerify.API({
+    link: ["CAT.agent.task"],
+    confirm: agentTaskConfirm,
+    dotAlias: false,
+  })
+  CAT_agentTask(this: GMApi, request: GMApiRequest<[AgentTaskApiRequest]>, _sender: IGetSender) {
+    if (!this.agentService) {
+      throw new Error("AgentService is not available");
+    }
+    return this.agentService.handleAgentTaskApi(request.params[0]);
+  }
+}
+
+export default GMAgentTaskApi;
diff --git a/src/app/service/service_worker/gm_api/gm_agent_tools.ts b/src/app/service/service_worker/gm_api/gm_agent_tools.ts
new file mode 100644
index 000000000..c8d8d0203
--- /dev/null
+++ b/src/app/service/service_worker/gm_api/gm_agent_tools.ts
@@ -0,0 +1,57 @@
+// CATTool API 方法，通过 PermissionVerify.API 装饰器注册到全局 API Map
+// 运行时 this 绑定为 GMApi 实例
+
+import type { IGetSender } from "@Packages/message/server";
+import type { ConfirmParam } from "../permission_verify";
+import PermissionVerify, { type ApiParamConfirmFn } from "../permission_verify";
+import type { GMApiRequest } from "../types";
+import type { CATToolApiRequest } from "@App/app/service/agent/types";
+import i18next, { i18nName } from "@App/locales/locales";
+import type GMApi from "./gm_api";
+
+// 复用 Agent API 的权限确认逻辑，写操作（install/remove）每次都需弹窗确认
+const agentConfirm: ApiParamConfirmFn = async (request: GMApiRequest, _sender: IGetSender, gmApi: GMApi) => {
+  const toolsReq = request.params[0] as CATToolApiRequest;
+  const isWrite = toolsReq.action === "install" || toolsReq.action === "remove";
+
+  if (isWrite) {
+    // 写操作：仅查询 DB 中的持久化授权，跳过缓存
+    const ret = await gmApi.permissionVerify.queryPersistentPermission(request, {
+      permission: "agent.tools",
+    });
+    if (ret && ret.allow) return true;
+  } else {
+    // 读操作：缓存 + DB
+    const ret = await gmApi.permissionVerify.queryPermission(request, {
+      permission: "agent.tools",
+    });
+    if (ret && ret.allow) return true;
+  }
+
+  const metadata: { [key: string]: string } = {};
+  metadata[i18next.t("script_name")] = i18nName(request.script);
+  return {
+    permission: "agent.tools",
+    title: i18next.t("agent_permission_title"),
+    metadata,
+    describe: i18next.t("agent_permission_describe"),
+    permissionContent: i18next.t("agent_permission_content"),
+    persistentOnly: isWrite,
+  } as ConfirmParam;
+};
+
+class GMAgentToolsApi {
+  @PermissionVerify.API({
+    link: ["CAT.agent.tools"],
+    confirm: agentConfirm,
+    dotAlias: false,
+  })
+  CAT_agentTools(this: GMApi, request: GMApiRequest<[CATToolApiRequest]>, _sender: IGetSender) {
+    if (!this.agentService) {
+      throw new Error("AgentService is not available");
+    }
+    return this.agentService.handleToolsApi(request.params[0], request.script);
+  }
+}
+
+export default GMAgentToolsApi;
diff --git a/src/app/service/service_worker/gm_api/gm_api.test.ts b/src/app/service/service_worker/gm_api/gm_api.test.ts
index 5be6e38da..b4749041a 100644
--- a/src/app/service/service_worker/gm_api/gm_api.test.ts
+++ b/src/app/service/service_worker/gm_api/gm_api.test.ts
@@ -2,6 +2,9 @@ import { describe, it, expect } from "vitest";
 import { type IGetSender } from "@Packages/message/server";
 import { type ExtMessageSender } from "@Packages/message/types";
 import { ConnectMatch, getConnectMatched } from "./gm_api";
+import { PermissionVerifyApiGet } from "../permission_verify";
+// 触发所有 GM API 装饰器注册（与 gm_api.ts 中的 import 保持同步）
+import "./gm_api";
 
 // 小工具：建立假的 IGetSender
 const makeSender = (url?: string): IGetSender => ({
@@ -98,3 +101,25 @@ describe.concurrent("isConnectMatched", () => {
     expect(getConnectMatched(["Api.Example.com"], req, makeSender())).toBe(ConnectMatch.DOMAIN);
   });
 });
+
+describe.concurrent("GM API 注册完整性", () => {
+  it.concurrent("CAT_agentDom 应已注册", () => {
+    const api = PermissionVerifyApiGet("CAT_agentDom");
+    expect(api).toBeDefined();
+    expect(api!.param.link).toContain("CAT.agent.dom");
+  });
+
+  it.concurrent("Agent 相关 API 应全部注册", () => {
+    // 确保 Agent 相关的 GM API 不会因 import 遗漏而丢失
+    const agentApis = [
+      "CAT_agentConversation",
+      "CAT_agentConversationChat",
+      "CAT_agentTools",
+      "CAT_agentSkills",
+      "CAT_agentDom",
+    ];
+    for (const name of agentApis) {
+      expect(PermissionVerifyApiGet(name), `${name} 应已注册`).toBeDefined();
+    }
+  });
+});
diff --git a/src/app/service/service_worker/gm_api/gm_api.ts b/src/app/service/service_worker/gm_api/gm_api.ts
index 1f853e284..237448741 100644
--- a/src/app/service/service_worker/gm_api/gm_api.ts
+++ b/src/app/service/service_worker/gm_api/gm_api.ts
@@ -1,6 +1,6 @@
 import LoggerCore from "@App/app/logger/core";
 import Logger from "@App/app/logger/logger";
-import { ScriptDAO } from "@App/app/repo/scripts";
+import { ScriptDAO, type Script } from "@App/app/repo/scripts";
 import { type IGetSender, type Group, GetSenderType } from "@Packages/message/server";
 import type { ExtMessageSender, MessageSend, TMessageCommAction } from "@Packages/message/types";
 import { connect, sendMessage } from "@Packages/message/client";
@@ -28,6 +28,11 @@ import type {
 import type { TScriptMenuRegister, TScriptMenuUnregister } from "../../queue";
 import type { NotificationOptionCache } from "../utils";
 import { BrowserNoSupport, notificationsUpdate } from "../utils";
+import {
+  getCATToolGrantsByUuid,
+  getCATToolNameByUuid,
+  CATTOOL_UUID_PREFIX,
+} from "@App/app/service/agent/cattool_executor";
 import i18n from "@App/locales/locales";
 import { encodeRValue, type TKeyValuePair } from "@App/pkg/utils/message_value";
 import { createObjectURL } from "../../offscreen/client";
@@ -45,6 +50,19 @@ import { headerModifierMap, headersReceivedMap } from "./gm_xhr";
 import { BgGMXhr } from "@App/pkg/utils/xhr/bg_gm_xhr";
 import { mightPrepareSetClipboard, setClipboard } from "../clipboard";
 import { nativePageWindowOpen } from "../../offscreen/gm_api";
+import type { AgentService } from "../agent";
+// 导入 Agent API 以触发装饰器注册
+// 注意：不能使用 import "./gm_agent"，sideEffects 配置会导致 tree-shaking 移除纯副作用导入
+import GMAgentApi from "./gm_agent";
+void GMAgentApi;
+import GMAgentToolsApi from "./gm_agent_tools";
+void GMAgentToolsApi;
+import GMAgentSkillsApi from "./gm_agent_skills";
+void GMAgentSkillsApi;
+import GMAgentDomApi from "./gm_agent_dom";
+void GMAgentDomApi;
+import GMAgentTaskApi from "./gm_agent_task";
+void GMAgentTaskApi;
 
 let generatedUniqueMarkerIDs = "";
 let generatedUniqueMarkerIDWhen = "";
@@ -237,9 +255,11 @@ export default class GMApi {
 
   scriptDAO: ScriptDAO = new ScriptDAO();
 
+  agentService?: AgentService;
+
   constructor(
     private systemConfig: SystemConfig,
-    private permissionVerify: PermissionVerify,
+    public permissionVerify: PermissionVerify,
     private group: Group,
     private msgSender: MessageSend,
     private mq: IMessageQueue,
@@ -249,6 +269,10 @@ export default class GMApi {
     this.logger = LoggerCore.logger().with({ service: "runtime/gm_api" });
   }
 
+  setAgentService(agentService: AgentService) {
+    this.agentService = agentService;
+  }
+
   // PermissionVerify.API
   // sendMessage from Content Script, etc
   async handlerRequest(data: MessageRequest, sender: IGetSender) {
@@ -269,11 +293,36 @@ export default class GMApi {
 
   // 解析请求
   async parseRequest<T>(data: MessageRequest<T>): Promise<GMApiRequest<T>> {
-    const script = await this.scriptDAO.get(data.uuid);
-    if (!script) {
-      throw new Error("script is not found");
+    let script;
+    if (data.uuid.startsWith(CATTOOL_UUID_PREFIX)) {
+      // CATTool GM API 调用：构造虚拟 Script 对象（CATTool 不在 ScriptDAO 中）
+      // 直接从 UUID map 获取 grants，避免查 repo（skill 的 CATTool 不在 catToolRepo 中）
+      const grants = getCATToolGrantsByUuid(data.uuid);
+      const toolName = getCATToolNameByUuid(data.uuid);
+      // 使用基于工具名的稳定标识符，使权限缓存在多次执行间有效
+      // 每次执行生成新的临时 UUID，但权限应绑定到工具本身而非单次执行
+      const stableUuid = CATTOOL_UUID_PREFIX + toolName;
+      script = {
+        uuid: stableUuid,
+        name: toolName || data.uuid,
+        namespace: "",
+        metadata: { grant: grants },
+        type: 3,
+        status: 1,
+        sort: 0,
+        runStatus: "running" as const,
+        createtime: Date.now(),
+        checktime: 0,
+      } as Script;
+    } else {
+      script = await this.scriptDAO.get(data.uuid);
+      if (!script) {
+        throw new Error("script is not found");
+      }
     }
-    return { ...data, script } as GMApiRequest<T>;
+    // CATTool 使用稳定标识符覆盖 uuid，确保权限 DB 查询/保存也用同一个标识符
+    const uuid = data.uuid.startsWith(CATTOOL_UUID_PREFIX) ? script.uuid : data.uuid;
+    return { ...data, uuid, script } as GMApiRequest<T>;
   }
 
   @PermissionVerify.API({
diff --git a/src/app/service/service_worker/index.ts b/src/app/service/service_worker/index.ts
index 51f381283..3e1d6327c 100644
--- a/src/app/service/service_worker/index.ts
+++ b/src/app/service/service_worker/index.ts
@@ -21,6 +21,7 @@ import { FaviconDAO } from "@App/app/repo/favicon";
 import { onRegularUpdateCheckAlarm } from "./regular_updatecheck";
 import { cacheInstance } from "@App/app/cache";
 import { InfoNotification } from "./utils";
+import { AgentService } from "./agent";
 
 // service worker的管理器
 export default class ServiceWorkerManager {
@@ -101,6 +102,14 @@ export default class ServiceWorkerManager {
       faviconDAO
     );
     system.init();
+    const agent = new AgentService(this.api.group("agent"), this.sender, resource);
+    agent.init();
+
+    // 注入 AgentService 到 GMApi，使 Agent API 走权限验证通道
+    const gmApi = runtime.getGMApi();
+    if (gmApi) {
+      gmApi.setAgentService(agent);
+    }
 
     const regularScriptUpdateCheck = async () => {
       const res = await onRegularUpdateCheckAlarm(systemConfig, script, subscribe);
@@ -152,6 +161,9 @@ export default class ServiceWorkerManager {
           // 检查扩展更新
           regularExtensionUpdateCheck();
           break;
+        case "agentTaskScheduler":
+          agent.onSchedulerTick();
+          break;
       }
     });
     // 12小时检查一次扩展更新
@@ -180,6 +192,29 @@ export default class ServiceWorkerManager {
       }
     });
 
+    // Agent 定时任务调度器 alarm（每分钟触发一次）
+    chrome.alarms.get("agentTaskScheduler", (alarm) => {
+      const lastError = chrome.runtime.lastError;
+      if (lastError) {
+        console.error("chrome.runtime.lastError in chrome.alarms.get:", lastError);
+      }
+      if (!alarm) {
+        chrome.alarms.create(
+          "agentTaskScheduler",
+          {
+            delayInMinutes: 1,
+            periodInMinutes: 1,
+          },
+          () => {
+            const lastError = chrome.runtime.lastError;
+            if (lastError) {
+              console.error("chrome.runtime.lastError in chrome.alarms.create:", lastError);
+            }
+          }
+        );
+      }
+    });
+
     // 云同步
     systemConfig.watch("cloud_sync", (value) => {
       synchronize.cloudSyncConfigChange(value);
diff --git a/src/app/service/service_worker/permission_verify.ts b/src/app/service/service_worker/permission_verify.ts
index 4f8510261..97b4eb7f2 100644
--- a/src/app/service/service_worker/permission_verify.ts
+++ b/src/app/service/service_worker/permission_verify.ts
@@ -28,6 +28,8 @@ export interface ConfirmParam {
   wildcard?: boolean;
   // 权限内容
   permissionContent?: string;
+  // 仅接受持久化（DB 存储）的授权，忽略临时缓存
+  persistentOnly?: boolean;
 }
 
 export interface UserConfirm {
@@ -196,6 +198,21 @@ export default class PermissionVerify {
     return `${CACHE_KEY_PERMISSION}${request.script.uuid}:${confirm.permission}:${confirm.permissionValue || ""}`;
   }
 
+  // 仅查询 DB 中的持久化权限，跳过缓存
+  async queryPersistentPermission<T>(
+    request: GMApiRequest<T>,
+    confirm: {
+      permission: string;
+      permissionValue?: string;
+    }
+  ): Promise<Permission | undefined> {
+    let model = await this.permissionDAO.findByKey(request.uuid, confirm.permission, confirm.permissionValue || "");
+    if (!model) {
+      model = await this.permissionDAO.findByKey(request.uuid, confirm.permission, "*");
+    }
+    return model;
+  }
+
   async queryPermission<T>(
     request: GMApiRequest<T>,
     confirm: {
@@ -222,15 +239,26 @@ export default class PermissionVerify {
     if (typeof confirm === "boolean") {
       return confirm;
     }
-    const ret = await this.queryPermission(request, confirm);
-    // 有查询到结果,进入判断,不再需要用户确认
-    if (ret) {
-      if (ret.allow) {
-        return true;
+
+    if (confirm.persistentOnly) {
+      // 仅查询 DB，跳过缓存
+      const ret = await this.queryPersistentPermission(request, confirm);
+      if (ret) {
+        if (ret.allow) return true;
+        throw new Error("permission denied");
+      }
+    } else {
+      const ret = await this.queryPermission(request, confirm);
+      // 有查询到结果,进入判断,不再需要用户确认
+      if (ret) {
+        if (ret.allow) {
+          return true;
+        }
+        // 权限拒绝
+        throw new Error("permission denied");
       }
-      // 权限拒绝
-      throw new Error("permission denied");
     }
+
     // 没有权限,则弹出页面让用户进行确认
     const userConfirm = await this.confirmWindow(request.script, confirm, sender);
     // 成功存入数据库
@@ -257,12 +285,12 @@ export default class PermissionVerify {
       default:
         break;
     }
-    // 临时 放入缓存
-    if (userConfirm.type >= 2) {
+    // persistentOnly 模式：type 2-3 不缓存（等同于 type 1 的一次性允许）
+    if (!confirm.persistentOnly && userConfirm.type >= 2) {
       const cacheKey = this.buildCacheKey(request, confirm);
       cacheInstance.set(cacheKey, model);
     }
-    // 总是 放入数据库
+    // 总是 放入数据库（type 4-5 为永久授权）
     if (userConfirm.type >= 4) {
       const oldConfirm = await this.permissionDAO.findByKey(model.uuid, model.permission, model.permissionValue);
       if (!oldConfirm) {
diff --git a/src/app/service/service_worker/runtime.ts b/src/app/service/service_worker/runtime.ts
index 8ea36659e..3e0992057 100644
--- a/src/app/service/service_worker/runtime.ts
+++ b/src/app/service/service_worker/runtime.ts
@@ -23,6 +23,7 @@ import {
   obtainBlackList,
   sourceMapTo,
 } from "@App/pkg/utils/utils";
+import { BrowserType, getBrowserInstalledVersion, getBrowserType, isPermissionOk } from "@App/pkg/utils/utils";
 import { cacheInstance } from "@App/app/cache";
 import { UrlMatch } from "@App/pkg/utils/match";
 import { ExtensionContentMessageSend } from "@Packages/message/extension_message";
@@ -86,6 +87,11 @@ export class RuntimeService {
   scriptMatchEnable: UrlMatch<string> = new UrlMatch<string>();
   scriptMatchDisable: UrlMatch<string> = new UrlMatch<string>();
   blackMatch: UrlMatch<string> = new UrlMatch<string>();
+  private gmApi?: GMApi;
+
+  getGMApi(): GMApi | undefined {
+    return this.gmApi;
+  }
 
   logger: Logger;
 
@@ -173,22 +179,8 @@ export class RuntimeService {
     }
   }
 
-  showNoDeveloperModeWarning() {
-    // 判断是否首次
-    this.localStorageDAO.get("firstShowDeveloperMode").then((res) => {
-      if (!res) {
-        this.localStorageDAO.save({
-          key: "firstShowDeveloperMode",
-          value: true,
-        });
-        // 打开页面
-        initLocalesPromise.then(() => {
-          chrome.tabs.create({
-            url: `${DocumentationSite}${localePath}/docs/use/open-dev/`,
-          });
-        });
-      }
-    });
+  async showUserscriptActivationGuide() {
+    const storageKey = "firstShowDeveloperMode";
     chrome.action.setBadgeBackgroundColor({
       color: "#ff8c00",
     });
@@ -217,6 +209,35 @@ export class RuntimeService {
         });
       }
     });
+
+    const currentInstalledBrowser = getBrowserInstalledVersion();
+    const lastInstalledBrowser = (await this.localStorageDAO.get(storageKey))?.value as string | boolean | undefined;
+    // 判断是否安装后的首次，或是浏览器升级后的首次
+    if (currentInstalledBrowser === lastInstalledBrowser) return; // 非首次则不弹出页面
+
+    const savePromise = this.localStorageDAO.save({
+      key: storageKey,
+      value: currentInstalledBrowser,
+    });
+    await Promise.allSettled([initLocalesPromise, this.initReady, savePromise]); // 等一下语言加载和 isUserScriptsAvailable 检查之类的
+
+    const userscript_enabled: boolean = this.isUserScriptsAvailable;
+    const permission = await isPermissionOk("userScripts");
+    const browserType = getBrowserType();
+    const guard =
+      browserType.chrome & BrowserType.guardedByDeveloperMode
+        ? "developerMode"
+        : browserType.chrome & BrowserType.guardedByAllowScript
+          ? "allowScript"
+          : "none";
+
+    // 打开页面
+    const path = `${DocumentationSite}${localePath}/docs/use/open-dev/`;
+    let search = `?userscript_enabled=${userscript_enabled}&userscript_permission=${permission}&userscript_guard=${guard}`;
+    if (browserType.chrome & BrowserType.Edge) search += "&browser=edge";
+    else if (browserType.chrome & BrowserType.Chrome) search += "&browser=chrome";
+    const hash = `${guard === "developerMode" ? "#enable-developer-mode" : guard === "allowScript" ? "#allow-user-scripts" : ""}`;
+    chrome.tabs.create({ url: `${path}${search}${hash}` });
   }
 
   async getInjectJsCode() {
@@ -351,7 +372,7 @@ export class RuntimeService {
   init() {
     // 启动gm api
     const permission = new PermissionVerify(this.group.group("permission"), this.mq);
-    const gmApi = new GMApi(
+    this.gmApi = new GMApi(
       this.systemConfig,
       permission,
       this.group,
@@ -361,7 +382,7 @@ export class RuntimeService {
       new GMExternalDependencies(this)
     );
     permission.init();
-    gmApi.start();
+    this.gmApi.start();
 
     this.group.on("stopScript", this.stopScript.bind(this));
     this.group.on("runScript", this.runScript.bind(this));
@@ -581,7 +602,7 @@ export class RuntimeService {
       // 检查是否开启了开发者模式
       if (!this.isUserScriptsAvailable) {
         // 未开启加上警告引导
-        this.showNoDeveloperModeWarning();
+        this.showUserscriptActivationGuide();
         let cid: ReturnType<typeof setInterval> | number;
         cid = setInterval(async () => {
           if (!this.isUserScriptsAvailable) {
diff --git a/src/app/service/service_worker/script.ts b/src/app/service/service_worker/script.ts
index 227be28d1..a91e7b4dd 100644
--- a/src/app/service/service_worker/script.ts
+++ b/src/app/service/service_worker/script.ts
@@ -47,6 +47,7 @@ import { getSimilarityScore, ScriptUpdateCheck } from "./script_update_check";
 import { LocalStorageDAO } from "@App/app/repo/localStorage";
 import { CompiledResourceDAO } from "@App/app/repo/resource";
 import { initRegularUpdateCheck } from "./regular_updatecheck";
+import { parseCATToolMetadata } from "@App/pkg/utils/cattool";
 
 export type TCheckScriptUpdateOption = Partial<
   { checkType: "user"; noUpdateCheck?: number } | ({ checkType: "system" } & Record<string, any>)
@@ -54,6 +55,19 @@ export type TCheckScriptUpdateOption = Partial<
 
 export type TOpenBatchUpdatePageOption = { q: string; dontCheckNow: boolean };
 
+export type TScriptInstallParam = {
+  script: Script; // 脚本信息（包含脚本的基础元数据）
+  code: string; // 脚本源码内容
+  upsertBy?: InstallSource; // 安装/更新来源（用于标识脚本来源渠道）
+  createtime?: number; // 导入时指定的创建时间（时间戳，毫秒）
+  updatetime?: number; // 导入时指定的最后更新时间（时间戳，毫秒）
+};
+
+export type TScriptInstallReturn = {
+  update: boolean; // 是否为更新操作（true 表示更新，false 表示新增）
+  updatetime: number | undefined; // 实际生效的更新时间（时间戳，毫秒）
+};
+
 export class ScriptService {
   logger: Logger;
   scriptCodeDAO: ScriptCodeDAO = new ScriptCodeDAO();
@@ -85,8 +99,8 @@ export class ScriptService {
         }
         // 处理url, 实现安装脚本
         let targetUrl: string;
-        // 判断是否为 file:///*/*.user.js
-        if (req.url.startsWith("file://") && req.url.endsWith(".user.js")) {
+        // 判断是否为 file:///*/*.user.js 或 file:///*/*.cattool.js
+        if (req.url.startsWith("file://") && (req.url.endsWith(".user.js") || req.url.endsWith(".cattool.js"))) {
           targetUrl = req.url;
         } else {
           const reqUrl = new URL(req.url);
@@ -153,6 +167,7 @@ export class ScriptService {
           { schemes: ["http", "https"], hostEquals: "docs.scriptcat.org", pathPrefix: "/en/docs/script_installation/" },
           { schemes: ["http", "https"], hostEquals: "www.tampermonkey.net", pathPrefix: "/script_installation.php" },
           { schemes: ["file"], pathSuffix: ".user.js" },
+          { schemes: ["file"], pathSuffix: ".cattool.js" },
         ],
       }
     );
@@ -237,6 +252,14 @@ export class ScriptService {
         isUrlFilterCaseSensitive: false,
         requestDomains: ["bitbucket.org"], // Chrome 101+
       },
+      // CATTool (.cattool.js) 安装检测
+      {
+        regexFilter: "^([^?#]+?\\.cattool\\.js)",
+        resourceTypes: [chrome.declarativeNetRequest.ResourceType.MAIN_FRAME],
+        requestMethods: ["get" as chrome.declarativeNetRequest.RequestMethod],
+        isUrlFilterCaseSensitive: false,
+        excludedRequestDomains: ["github.com", "gitlab.com", "gitea.com", "bitbucket.org"],
+      },
     ];
     const installPageURL = chrome.runtime.getURL("src/install.html");
     const rules = conditions.map((condition, idx) => {
@@ -369,14 +392,8 @@ export class ScriptService {
     return this.mq.publish<TInstallScript>("installScript", { script, ...options });
   }
 
-  // 安装脚本 / 更新腳本
-  async installScript(param: {
-    script: Script;
-    code: string;
-    upsertBy?: InstallSource;
-    createtime?: number;
-    updatetime?: number;
-  }) {
+  // 安装脚本 / 更新脚本
+  async installScript(param: TScriptInstallParam): Promise<TScriptInstallReturn> {
     param.upsertBy = param.upsertBy || "user";
     const { script, upsertBy, createtime, updatetime } = param;
     // 删 storage cache
@@ -427,10 +444,11 @@ export class ScriptService {
         ]);
 
         // 广播一下
-        // Runtime 會負責更新 CompiledResource
+        // Runtime 会负责更新 CompiledResource
         this.publishInstallScript(script, { update, upsertBy });
 
-        return { update };
+        // 传回(由后台控制的)实际更新时间，让 editor 中的script能保持正确的更新时间
+        return { update, updatetime: script.updatetime };
       })
       .catch((e: any) => {
         logger.error("install error", Logger.E(e));
@@ -764,17 +782,51 @@ export class ScriptService {
         setTimeout(resolve, Math.round(MIN_DELAY + ((++i / n + Math.random()) / 2) * (MAX_DELAY - MIN_DELAY)))
       );
 
-    return Promise.all(
-      (uuids as string[]).map(async (uuid, _idx) => {
-        const script = scripts[_idx];
-        const res =
-          !script || script.uuid !== uuid || !checkScripts.includes(script)
-            ? false
-            : await this._checkUpdateAvailable(script, delayFn);
-        if (!res) return false;
-        return res;
-      })
-    );
+    const CHECK_UPDATE_TIMEOUT_MS = 300_000; // 5 分钟超时
+
+    const results = new Map<
+      string,
+      | false
+      | {
+          updateAvailable: true;
+          code: string;
+          metadata: Partial<Record<string, string[]>>;
+        }
+    >();
+
+    // 预初始化 Map 确保顺序
+    for (const uuid of uuids as string[]) {
+      results.set(uuid, false);
+    }
+
+    const abortController = new AbortController();
+    let timeoutId: ReturnType<typeof setTimeout>;
+
+    const timeoutPromise = new Promise<void>((resolve) => {
+      timeoutId = setTimeout(() => {
+        abortController.abort();
+        resolve();
+      }, CHECK_UPDATE_TIMEOUT_MS);
+    });
+
+    await Promise.race([
+      timeoutPromise,
+      Promise.allSettled(
+        (uuids as string[]).map(async (uuid, _idx) => {
+          const script = scripts[_idx];
+          const res =
+            !script || script.uuid !== uuid || !checkScripts.includes(script)
+              ? false
+              : await this._checkUpdateAvailable(script, delayFn, abortController.signal);
+          if (!res) return false;
+          results.set(uuid, res);
+          return res;
+        })
+      ).finally(() => {
+        clearTimeout(timeoutId);
+      }),
+    ]);
+    return [...results.values()];
   }
 
   async _checkUpdateAvailable(
@@ -784,7 +836,8 @@ export class ScriptService {
       checkUpdateUrl?: string;
       metadata: Partial<Record<string, any>>;
     },
-    delayFn?: () => Promise<any>
+    delayFn?: () => Promise<any>,
+    signal?: AbortSignal
   ): Promise<false | { updateAvailable: true; code: string; metadata: SCMetadata }> {
     const { uuid, name, checkUpdateUrl } = script;
 
@@ -796,8 +849,12 @@ export class ScriptService {
       name,
     });
     try {
-      if (delayFn) await delayFn();
-      const code = await fetchScriptBody(checkUpdateUrl);
+      if (delayFn) {
+        if (signal?.aborted) return false;
+        await delayFn();
+      }
+      if (signal?.aborted) return false;
+      const code = await fetchScriptBody(checkUpdateUrl, signal);
       const metadata = parseMetadata(code);
       if (!metadata) {
         logger.error("parse metadata failed");
@@ -855,6 +912,18 @@ export class ScriptService {
         logger?.error("prepare script failed", Logger.E(e));
       }
     }
+    // 检测是否为 CATTool
+    const cattoolMeta = parseCATToolMetadata(code);
+    if (cattoolMeta) {
+      const si = [
+        false,
+        { uuid, code, url, source: upsertBy, metadata: {}, userSubscribe: false, cattool: true } as ScriptInfo,
+        options,
+      ];
+      await cacheInstance.set(`${CACHE_KEY_SCRIPT_INFO}${uuid}`, si);
+      return 1;
+    }
+
     const metadata = parseMetadata(code);
     if (!metadata) {
       throw new Error("parse script info failed");
@@ -1144,7 +1213,7 @@ export class ScriptService {
   }
 
   isInstalled({ name, namespace }: { name: string; namespace: string }): Promise<App.IsInstalledResponse> {
-    // 用於 window.external
+    // 用于 window.external
     return this.scriptDAO.findByNameAndNamespace(name, namespace).then((script) => {
       if (script) {
         return {
diff --git a/src/assets/_locales/en/messages.json b/src/assets/_locales/en/messages.json
index 4165381cb..07481b4e3 100644
--- a/src/assets/_locales/en/messages.json
+++ b/src/assets/_locales/en/messages.json
@@ -11,4 +11,4 @@
   "scriptcat_description": {
     "message": "Everything can be scripted, allowing your browser to do more!"
   }
-}
\ No newline at end of file
+}
diff --git a/src/assets/_locales/ru/messages.json b/src/assets/_locales/ru/messages.json
index cdc009c96..cb36c4f46 100644
--- a/src/assets/_locales/ru/messages.json
+++ b/src/assets/_locales/ru/messages.json
@@ -11,4 +11,4 @@
   "scriptcat_description": {
     "message": "Всё можно автоматизировать скриптами, позволяя вашему браузеру делать больше!"
   }
-}
\ No newline at end of file
+}
diff --git a/src/assets/_locales/vi/messages.json b/src/assets/_locales/vi/messages.json
index 24a61e888..b501e3572 100644
--- a/src/assets/_locales/vi/messages.json
+++ b/src/assets/_locales/vi/messages.json
@@ -11,4 +11,4 @@
   "scriptcat_description": {
     "message": "Mọi thứ đều có thể viết được, cho phép trình duyệt của bạn làm được nhiều việc hơn!"
   }
-}
\ No newline at end of file
+}
diff --git a/src/assets/_locales/zh_CN/messages.json b/src/assets/_locales/zh_CN/messages.json
index 0b7d5775f..a4488bbdf 100644
--- a/src/assets/_locales/zh_CN/messages.json
+++ b/src/assets/_locales/zh_CN/messages.json
@@ -11,4 +11,4 @@
   "scriptcat_description": {
     "message": "万物皆可脚本化，让你的浏览器可以做更多的事情！"
   }
-}
\ No newline at end of file
+}
diff --git a/src/index.css b/src/index.css
index 6eb4944b4..6c46ac7e4 100644
--- a/src/index.css
+++ b/src/index.css
@@ -3,34 +3,34 @@
 @unocss;
 
 body {
-    scrollbar-color: var(--color-scrollbar-thumb) var(--color-scrollbar-track);
-    /* 对于webkit浏览器的滚动条样式 */
-    scrollbar-width: thin;
+  scrollbar-color: var(--color-scrollbar-thumb) var(--color-scrollbar-track);
+  /* 对于webkit浏览器的滚动条样式 */
+  scrollbar-width: thin;
 }
 
-body[arco-theme='dark'] {
-    --color-scrollbar-thumb: #6b6b6b;
-    --color-scrollbar-track: #2d2d2d;
-    --color-scrollbar-thumb-hover: #8c8c8c;
+body[arco-theme="dark"] {
+  --color-scrollbar-thumb: #6b6b6b;
+  --color-scrollbar-track: #2d2d2d;
+  --color-scrollbar-thumb-hover: #8c8c8c;
 }
 
-body[arco-theme='light'] {
-    --color-scrollbar-thumb: #6b6b6b;
-    --color-scrollbar-track: #f0f0f0;
-    --color-scrollbar-thumb-hover: #8c8c8c;
+body[arco-theme="light"] {
+  --color-scrollbar-thumb: #6b6b6b;
+  --color-scrollbar-track: #f0f0f0;
+  --color-scrollbar-thumb-hover: #8c8c8c;
 }
 
 :root {
-	--sc-zero-1: 0;
-	--sc-zero-2: 0;
-	--sc-zero-3: 0;
-	--sc-zero-4: 0;
+  --sc-zero-1: 0;
+  --sc-zero-2: 0;
+  --sc-zero-3: 0;
+  --sc-zero-4: 0;
 }
 
 /* 自定义 .sc-inset-0 避免打包成 inset: 0 使旧浏览器布局错位 */
 .sc-inset-0 {
-	top: var(--sc-zero-1);
-	left: var(--sc-zero-2);
-	right: var(--sc-zero-3);
-	bottom: var(--sc-zero-4);
+  top: var(--sc-zero-1);
+  left: var(--sc-zero-2);
+  right: var(--sc-zero-3);
+  bottom: var(--sc-zero-4);
 }
diff --git a/src/locales/README.md b/src/locales/README.md
index de687d95b..279bf3817 100644
--- a/src/locales/README.md
+++ b/src/locales/README.md
@@ -25,8 +25,8 @@ for example:
 
 ### Help Us Translate
 
-[Crowdin](https://crowdin.com/project/scriptcat)
-is an online localization platform that helps us manage translations. If you're interested in helping us translate ScriptCat, you can find the project on Crowdin and start contributing.
+[Crowdin](https://crowdin.com/project/scriptcat) is an online localization platform that helps us manage translations.
+If you're interested in helping us translate ScriptCat, you can find the project on Crowdin and start contributing.
 
 - `src/locales` is the translation file directory for the [extension](https://github.com/scriptscat/scriptcat)
 
diff --git a/src/locales/ach-UG/translation.json b/src/locales/ach-UG/translation.json
index e6f3850b5..4dcb700e9 100644
--- a/src/locales/ach-UG/translation.json
+++ b/src/locales/ach-UG/translation.json
@@ -428,7 +428,6 @@
   "develop_mode_guide": "crwdns8624:0crwdne8624:0",
   "allow_user_script_guide": "crwdns8626:0crwdne8626:0",
   "lower_version_browser_guide": "crwdns8628:0crwdne8628:0",
-  "confirm_leave_page": "crwdns8634:0crwdne8634:0",
   "page_in_blacklist": "crwdns8636:0crwdne8636:0",
   "baidu_netdisk": "crwdns8638:0crwdne8638:0",
   "save_only_current_group": "crwdns8640:0crwdne8640:0",
@@ -557,5 +556,135 @@
   "editor": {
     "show_script_list": "Show Script List",
     "hide_script_list": "Hide Script List"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "Chat",
+  "agent_provider": "Model Service",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "Model Service",
+  "agent_provider_select": "AI Provider",
+  "agent_provider_api_base_url": "API Base URL",
+  "agent_provider_api_key": "API Key",
+  "agent_provider_model": "Default Model",
+  "agent_provider_test_connection": "Test Connection",
+  "agent_provider_test_success": "Connection Successful",
+  "agent_provider_test_failed": "Connection Failed",
+  "agent_model_fetch": "Fetch Models",
+  "agent_model_fetch_failed": "Failed to fetch models",
+  "agent_model_name": "Name",
+  "agent_model_add": "Add Model",
+  "agent_model_edit": "Edit",
+  "agent_model_delete": "Delete",
+  "agent_model_set_default": "Set as Default",
+  "agent_model_default_label": "Default",
+  "agent_model_delete_confirm": "Are you sure to delete this model?",
+  "agent_model_no_models": "No models configured",
+  "agent_coming_soon": "Coming soon...",
+  "agent_skills_title": "Skills Management",
+  "agent_skills_add": "Add Skill",
+  "agent_skills_empty": "No skills installed",
+  "agent_skills_tools": "Tools",
+  "agent_skills_references": "References",
+  "agent_skills_detail": "Skill Details",
+  "agent_skills_edit_prompt": "Prompt",
+  "agent_skills_install": "Install Skill",
+  "agent_skills_install_url": "Import from URL",
+  "agent_skills_install_paste": "Paste SKILL.md",
+  "agent_skills_uninstall": "Uninstall",
+  "agent_skills_uninstall_confirm": "Are you sure to uninstall Skill \"{{name}}\"?",
+  "agent_skills_save_success": "Saved successfully",
+  "agent_skills_install_success": "Installed successfully",
+  "agent_skills_fetch_failed": "Fetch failed",
+  "agent_skills_add_script": "Add Script",
+  "agent_skills_add_reference": "Add Reference",
+  "agent_skills_install_zip": "Upload ZIP",
+  "agent_skills_install_zip_hint": "Click to select a .zip file",
+  "agent_skills_prompt": "Prompt",
+  "agent_skills_installed_at": "Installed at",
+  "agent_skills_refresh": "Refresh",
+  "agent_skills_refresh_success": "Refreshed successfully",
+  "agent_skills_tool_code": "Tool Code",
+  "agent_skills_click_to_view_code": "Click tool name to view code",
+  "agent_chat_new": "New Chat",
+  "agent_chat_delete": "Delete Chat",
+  "agent_chat_delete_confirm": "Delete this conversation?",
+  "agent_chat_no_conversations": "No conversations",
+  "agent_chat_input_placeholder": "Type a message...",
+  "agent_chat_send": "Send",
+  "agent_chat_stop": "Stop",
+  "agent_chat_thinking": "Thinking",
+  "agent_chat_tool_call": "Tool Call",
+  "agent_chat_error": "Error occurred",
+  "agent_chat_no_model": "No model configured. Please add one in Model Service first.",
+  "agent_chat_model_select": "Select Model",
+  "agent_chat_rename": "Rename",
+  "agent_chat_copy": "Copy",
+  "agent_chat_copy_success": "Copied",
+  "agent_chat_regenerate": "Regenerate",
+  "agent_chat_streaming": "Generating...",
+  "agent_chat_newline": "for new line",
+  "agent_chat_welcome_hint": "Ask me anything about your scripts",
+  "agent_chat_welcome_start": "Create a conversation to get started",
+  "agent_chat_tokens": "tokens",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} tools",
+  "agent_chat_delete_round": "Delete",
+  "agent_chat_copy_message": "Copy",
+  "agent_chat_edit_message": "Edit",
+  "agent_chat_save_and_send": "Save & Send",
+  "agent_chat_cancel_edit": "Cancel",
+  "agent_permission_title": "The script is requesting to use Agent conversation",
+  "agent_permission_describe": "This script requests Agent conversation access, which will consume API tokens. Only grant access to trusted scripts.",
+  "agent_permission_content": "Agent Conversation",
+  "cattool_parameters": "Parameters",
+  "cattool_permissions": "Permissions",
+  "cattool_required": "required",
+  "cattool_source_script": "Installed by script",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "CATTool Management",
+  "agent_catool_empty": "No CATTools installed",
+  "agent_catool_detail": "Details",
+  "agent_catool_delete": "Delete",
+  "agent_catool_delete_confirm": "Are you sure to delete CATTool \"{{name}}\"?",
+  "agent_catool_delete_success": "Deleted successfully",
+  "agent_catool_installed_at": "Installed at",
+  "agent_catool_source": "Source script",
+  "agent_catool_description": "Description",
+  "agent_catool_params": "Parameters",
+  "agent_catool_grants": "Permissions",
+  "agent_catool_code": "Code",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "OPFS File Browser",
+  "agent_opfs_empty": "Empty directory",
+  "agent_opfs_name": "Name",
+  "agent_opfs_size": "Size",
+  "agent_opfs_type": "Type",
+  "agent_opfs_modified": "Last Modified",
+  "agent_opfs_delete_confirm": "Are you sure to delete?",
+  "agent_opfs_delete_success": "Deleted",
+  "agent_opfs_file": "File",
+  "agent_opfs_directory": "Directory",
+  "agent_opfs_preview": "Preview",
+  "agent_opfs_root": "Root",
+  "agent_dom_permission_title": "The script is requesting DOM operation access",
+  "agent_dom_permission_describe": "This script requests the ability to read and manipulate web page DOM (click, fill forms, navigate, screenshot, etc.). Only grant access to trusted scripts.",
+  "agent_dom_permission_content": "Agent DOM Operations",
+  "agent_mcp_title": "MCP Servers",
+  "agent_mcp_add_server": "Add Server",
+  "agent_mcp_no_servers": "No MCP servers configured",
+  "agent_mcp_test_connection": "Test",
+  "agent_mcp_name_url_required": "Name and URL are required",
+  "agent_mcp_optional": "optional",
+  "agent_mcp_custom_headers": "Custom Headers",
+  "agent_mcp_enabled": "Enabled",
+  "agent_mcp_detail": "Details",
+  "agent_mcp_tools": "Tools",
+  "agent_mcp_resources": "Resources",
+  "agent_mcp_prompts": "Prompts",
+  "agent_mcp_no_tools": "No tools available",
+  "agent_mcp_no_resources": "No resources available",
+  "agent_mcp_no_prompts": "No prompts available",
+  "agent_mcp_loading": "Loading...",
+  "agent_mcp_parameters": "Parameters"
+}
diff --git a/src/locales/de-DE/translation.json b/src/locales/de-DE/translation.json
index 9df67cfd8..98ae7c657 100644
--- a/src/locales/de-DE/translation.json
+++ b/src/locales/de-DE/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "'Nutzerskripts zulassen' ist derzeit nicht aktiviert, daher können die Skripte nicht richtig ausgeführt werden. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉Hier klicken, um zu erfahren, wie man es aktiviert</a>",
   "lower_version_browser_guide": "Ihr Browser ist zu veraltet, daher können die Skripte nicht richtig ausgeführt werden. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉Hier klicken, um mehr zu erfahren</a>",
   "click_to_reload": "👉Zum Neuladen klicken",
-  "confirm_leave_page": "Derzeit im Bearbeitungsstatus. Das Navigieren zu anderen Seiten führt zum Verlust des aktuellen Inhalts. Navigieren?",
   "page_in_blacklist": "Die aktuelle Seite ist auf der Blacklist und kann keine Skripte verwenden",
   "baidu_netdisk": "Baidu Netdisk",
   "netdisk_unbind": "{{provider}} trennen",
@@ -454,7 +453,7 @@
   "expression_format_error": "Ausdrucksformat-Fehler",
   "migration_confirm_message": "Das erneute Versuchen der Speicher-Engine-Migration wird vorhandene Daten ändern. Bitte bestätigen Sie. Details siehe: https://docs.scriptcat.org/docs/change/v0.17/",
   "retry_migration": "Speicher-Engine-Migration erneut versuchen",
-  "script_modified_leave_confirm": "Skript wurde geändert. Das Verlassen führt zum Verlust der Änderungen. Fortfahren?",
+  "script_modified_leave_confirm": "Ihre Änderungen wurden noch nicht gespeichert. Wenn Sie die Seite verlassen, gehen die Änderungen verloren. Möchten Sie die Seite wirklich verlassen?",
   "create_success_note": "Erstellung erfolgreich. Beachten Sie, dass Hintergrundskripte standardmäßig nicht aktiviert werden",
   "save_as_failed": "Speichern unter fehlgeschlagen",
   "save_as_success": "Speichern unter erfolgreich",
@@ -581,8 +580,143 @@
     "maybe_later": "Vielleicht später",
     "settings_hint": "Sie können diese Option jederzeit in den Einstellungen ändern."
   },
+  "favicon_service": "Favicon-Dienst",
+  "favicon_service_desc": "Dienst zum Abrufen von Website-Symbolen auswählen",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "Lokal abrufen",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "Skriptliste anzeigen",
     "hide_script_list": "Skriptliste ausblenden"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "Chat",
+  "agent_provider": "Model Service",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "Model Service",
+  "agent_provider_select": "AI Provider",
+  "agent_provider_api_base_url": "API Base URL",
+  "agent_provider_api_key": "API Key",
+  "agent_provider_model": "Default Model",
+  "agent_provider_test_connection": "Test Connection",
+  "agent_provider_test_success": "Connection Successful",
+  "agent_provider_test_failed": "Connection Failed",
+  "agent_model_fetch": "Modelle abrufen",
+  "agent_model_fetch_failed": "Modellliste konnte nicht abgerufen werden",
+  "agent_model_name": "Name",
+  "agent_model_add": "Add Model",
+  "agent_model_edit": "Edit",
+  "agent_model_delete": "Delete",
+  "agent_model_set_default": "Set as Default",
+  "agent_model_default_label": "Default",
+  "agent_model_delete_confirm": "Are you sure to delete this model?",
+  "agent_model_no_models": "No models configured",
+  "agent_coming_soon": "Coming soon...",
+  "agent_skills_title": "Skills Management",
+  "agent_skills_add": "Add Skill",
+  "agent_skills_empty": "No skills installed",
+  "agent_skills_tools": "Tools",
+  "agent_skills_references": "References",
+  "agent_skills_detail": "Skill Details",
+  "agent_skills_edit_prompt": "Prompt",
+  "agent_skills_install": "Install Skill",
+  "agent_skills_install_url": "Import from URL",
+  "agent_skills_install_paste": "Paste SKILL.md",
+  "agent_skills_uninstall": "Uninstall",
+  "agent_skills_uninstall_confirm": "Are you sure to uninstall Skill \"{{name}}\"?",
+  "agent_skills_save_success": "Saved successfully",
+  "agent_skills_install_success": "Installed successfully",
+  "agent_skills_fetch_failed": "Fetch failed",
+  "agent_skills_add_script": "Add Script",
+  "agent_skills_add_reference": "Add Reference",
+  "agent_skills_install_zip": "Upload ZIP",
+  "agent_skills_install_zip_hint": "Click to select a .zip file",
+  "agent_skills_prompt": "Prompt",
+  "agent_skills_installed_at": "Installed at",
+  "agent_skills_refresh": "Refresh",
+  "agent_skills_refresh_success": "Refreshed successfully",
+  "agent_skills_tool_code": "Tool Code",
+  "agent_skills_click_to_view_code": "Click tool name to view code",
+  "agent_chat_new": "New Chat",
+  "agent_chat_delete": "Delete Chat",
+  "agent_chat_delete_confirm": "Delete this conversation?",
+  "agent_chat_no_conversations": "No conversations",
+  "agent_chat_input_placeholder": "Type a message...",
+  "agent_chat_send": "Send",
+  "agent_chat_stop": "Stop",
+  "agent_chat_thinking": "Thinking",
+  "agent_chat_tool_call": "Tool Call",
+  "agent_chat_error": "Error occurred",
+  "agent_chat_no_model": "No model configured. Please add one in Model Service first.",
+  "agent_chat_model_select": "Select Model",
+  "agent_chat_rename": "Rename",
+  "agent_chat_copy": "Copy",
+  "agent_chat_copy_success": "Copied",
+  "agent_chat_regenerate": "Regenerate",
+  "agent_chat_streaming": "Generating...",
+  "agent_chat_newline": "for new line",
+  "agent_chat_welcome_hint": "Ask me anything about your scripts",
+  "agent_chat_welcome_start": "Create a conversation to get started",
+  "agent_chat_tokens": "tokens",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} tools",
+  "agent_chat_delete_round": "Delete",
+  "agent_chat_copy_message": "Copy",
+  "agent_chat_edit_message": "Bearbeiten",
+  "agent_chat_save_and_send": "Speichern & Senden",
+  "agent_chat_cancel_edit": "Abbrechen",
+  "agent_permission_title": "Das Skript fordert die Verwendung des Agent-Gesprächs an",
+  "agent_permission_describe": "Dieses Skript fordert Zugang zur Agent-Gesprächsfunktion an, was API-Token verbraucht. Erlauben Sie nur vertrauenswürdigen Skripten.",
+  "agent_permission_content": "Agent-Gespräch",
+  "cattool_parameters": "Parameter",
+  "cattool_permissions": "Berechtigungen",
+  "cattool_required": "erforderlich",
+  "cattool_source_script": "Installiert durch Skript",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "CATTool-Verwaltung",
+  "agent_catool_empty": "Keine CATTools installiert",
+  "agent_catool_detail": "Details",
+  "agent_catool_delete": "Löschen",
+  "agent_catool_delete_confirm": "CATTool \"{{name}}\" wirklich löschen?",
+  "agent_catool_delete_success": "Erfolgreich gelöscht",
+  "agent_catool_installed_at": "Installiert am",
+  "agent_catool_source": "Quellskript",
+  "agent_catool_description": "Beschreibung",
+  "agent_catool_params": "Parameter",
+  "agent_catool_grants": "Berechtigungen",
+  "agent_catool_code": "Code",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "OPFS Dateibrowser",
+  "agent_opfs_empty": "Leeres Verzeichnis",
+  "agent_opfs_name": "Name",
+  "agent_opfs_size": "Größe",
+  "agent_opfs_type": "Typ",
+  "agent_opfs_modified": "Zuletzt geändert",
+  "agent_opfs_delete_confirm": "Sind Sie sicher, dass Sie löschen möchten?",
+  "agent_opfs_delete_success": "Gelöscht",
+  "agent_opfs_file": "Datei",
+  "agent_opfs_directory": "Verzeichnis",
+  "agent_opfs_preview": "Vorschau",
+  "agent_opfs_root": "Stammverzeichnis",
+  "agent_dom_permission_title": "Das Skript fordert DOM-Zugriff an",
+  "agent_dom_permission_describe": "Dieses Skript fordert die Fähigkeit an, das DOM der Webseite zu lesen und zu manipulieren (Klicken, Formulare ausfüllen, Navigation, Screenshot usw.). Erlauben Sie nur vertrauenswürdigen Skripten.",
+  "agent_dom_permission_content": "Agent DOM-Operationen",
+  "agent_mcp_title": "MCP-Server",
+  "agent_mcp_add_server": "Server hinzufügen",
+  "agent_mcp_no_servers": "Keine MCP-Server konfiguriert",
+  "agent_mcp_test_connection": "Testen",
+  "agent_mcp_name_url_required": "Name und URL sind erforderlich",
+  "agent_mcp_optional": "optional",
+  "agent_mcp_custom_headers": "Benutzerdefinierte Header",
+  "agent_mcp_enabled": "Aktiviert",
+  "agent_mcp_detail": "Details",
+  "agent_mcp_tools": "Werkzeuge",
+  "agent_mcp_resources": "Ressourcen",
+  "agent_mcp_prompts": "Prompts",
+  "agent_mcp_no_tools": "Keine Werkzeuge verfügbar",
+  "agent_mcp_no_resources": "Keine Ressourcen verfügbar",
+  "agent_mcp_no_prompts": "Keine Prompts verfügbar",
+  "agent_mcp_loading": "Laden...",
+  "agent_mcp_parameters": "Parameter"
+}
diff --git a/src/locales/en-US/translation.json b/src/locales/en-US/translation.json
index 9769ef7f7..a2739c481 100644
--- a/src/locales/en-US/translation.json
+++ b/src/locales/en-US/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "'Allow User Scripts' is currently not enabled, so the scripts cannot run properly. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉tap to learn how to enable</a>",
   "lower_version_browser_guide": "Your browser is too outdated, so the scripts cannot run properly. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉Click me to learn more</a>",
   "click_to_reload": "👉Click to Reload",
-  "confirm_leave_page": "Currently editing status. Leaving this page will lose the current content. Do you want to leave?",
   "page_in_blacklist": "The current page is blacklisted, cannot use script",
   "baidu_netdisk": "BaiduNetdisk",
   "netdisk_unbind": "Unbind {{provider}}",
@@ -454,7 +453,7 @@
   "expression_format_error": "Condition expression format error",
   "migration_confirm_message": "Retry the migration storage engine to modify existing data. Please confirm, see：https://docs.scriptcat.org/docs/change/v0.17/.",
   "retry_migration": "Retry Migration Storage Engine",
-  "script_modified_leave_confirm": "The script has been modified. Changes will be lost after leaving, continue?",
+  "script_modified_leave_confirm": "Your changes have not been saved. If you leave, your changes will be lost. Are you sure you want to leave?",
   "create_success_note": "New script successfully created. Note that the background script will not be enabled by default.",
   "save_as_failed": "Save As Failed",
   "save_as_success": "Saved Successfully",
@@ -581,8 +580,178 @@
     "maybe_later": "Maybe Later",
     "settings_hint": "You can change this option in settings at any time."
   },
+  "favicon_service": "Favicon Service",
+  "favicon_service_desc": "Choose the service for fetching website icons",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "Local Fetch",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "Show Script List",
     "hide_script_list": "Hide Script List"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "Chat",
+  "agent_provider": "Model Service",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "Model Service",
+  "agent_provider_select": "AI Provider",
+  "agent_provider_api_base_url": "API Base URL",
+  "agent_provider_api_key": "API Key",
+  "agent_provider_model": "Default Model",
+  "agent_provider_test_connection": "Test Connection",
+  "agent_provider_test_success": "Connection Successful",
+  "agent_provider_test_failed": "Connection Failed",
+  "agent_model_fetch": "Fetch Models",
+  "agent_model_fetch_failed": "Failed to fetch models",
+  "agent_model_name": "Name",
+  "agent_model_add": "Add Model",
+  "agent_model_edit": "Edit",
+  "agent_model_delete": "Delete",
+  "agent_model_set_default": "Set as Default",
+  "agent_model_default_label": "Default",
+  "agent_model_delete_confirm": "Are you sure to delete this model?",
+  "agent_model_no_models": "No models configured",
+  "agent_coming_soon": "Coming soon...",
+  "agent_skills_title": "Skills Management",
+  "agent_skills_add": "Add Skill",
+  "agent_skills_empty": "No skills installed",
+  "agent_skills_tools": "Tools",
+  "agent_skills_references": "References",
+  "agent_skills_detail": "Skill Details",
+  "agent_skills_edit_prompt": "Prompt",
+  "agent_skills_install": "Install Skill",
+  "agent_skills_install_url": "Import from URL",
+  "agent_skills_install_paste": "Paste SKILL.md",
+  "agent_skills_uninstall": "Uninstall",
+  "agent_skills_uninstall_confirm": "Are you sure to uninstall Skill \"{{name}}\"?",
+  "agent_skills_save_success": "Saved successfully",
+  "agent_skills_install_success": "Installed successfully",
+  "agent_skills_fetch_failed": "Fetch failed",
+  "agent_skills_add_script": "Add Script",
+  "agent_skills_add_reference": "Add Reference",
+  "agent_skills_install_zip": "Upload ZIP",
+  "agent_skills_install_zip_hint": "Click to select a .zip file",
+  "agent_skills_prompt": "Prompt",
+  "agent_skills_installed_at": "Installed at",
+  "agent_skills_refresh": "Refresh",
+  "agent_skills_refresh_success": "Refreshed successfully",
+  "agent_skills_tool_code": "Tool Code",
+  "agent_skills_click_to_view_code": "Click tool name to view code",
+  "agent_skills_config": "Config",
+  "agent_skills_config_saved": "Config saved",
+  "agent_chat_new": "New Chat",
+  "agent_chat_delete": "Delete Chat",
+  "agent_chat_delete_confirm": "Delete this conversation?",
+  "agent_chat_no_conversations": "No conversations",
+  "agent_chat_input_placeholder": "Type a message...",
+  "agent_chat_send": "Send",
+  "agent_chat_stop": "Stop",
+  "agent_chat_thinking": "Thinking",
+  "agent_chat_tool_call": "Tool Call",
+  "agent_chat_error": "Error occurred",
+  "agent_chat_no_model": "No model configured. Please add one in Model Service first.",
+  "agent_chat_model_select": "Select Model",
+  "agent_chat_rename": "Rename",
+  "agent_chat_copy": "Copy",
+  "agent_chat_copy_success": "Copied",
+  "agent_chat_regenerate": "Regenerate",
+  "agent_chat_streaming": "Generating...",
+  "agent_chat_newline": "for new line",
+  "agent_chat_welcome_hint": "Ask me anything about your scripts",
+  "agent_chat_welcome_start": "Create a conversation to get started",
+  "agent_chat_tokens": "tokens",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} tools",
+  "agent_chat_delete_round": "Delete",
+  "agent_chat_copy_message": "Copy",
+  "agent_chat_edit_message": "Edit",
+  "agent_chat_save_and_send": "Save & Send",
+  "agent_chat_cancel_edit": "Cancel",
+  "agent_permission_title": "The script is requesting to use Agent conversation",
+  "agent_permission_describe": "This script requests Agent conversation access, which will consume API tokens. Only grant access to trusted scripts.",
+  "agent_permission_content": "Agent Conversation",
+  "cattool_parameters": "Parameters",
+  "cattool_permissions": "Permissions",
+  "cattool_required": "required",
+  "cattool_source_script": "Installed by script",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "CATTool Management",
+  "agent_catool_empty": "No CATTools installed",
+  "agent_catool_detail": "Details",
+  "agent_catool_delete": "Delete",
+  "agent_catool_delete_confirm": "Are you sure to delete CATTool \"{{name}}\"?",
+  "agent_catool_delete_success": "Deleted successfully",
+  "agent_catool_installed_at": "Installed at",
+  "agent_catool_source": "Source script",
+  "agent_catool_description": "Description",
+  "agent_catool_params": "Parameters",
+  "agent_catool_grants": "Permissions",
+  "agent_catool_code": "Code",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "OPFS File Browser",
+  "agent_opfs_empty": "Empty directory",
+  "agent_opfs_name": "Name",
+  "agent_opfs_size": "Size",
+  "agent_opfs_type": "Type",
+  "agent_opfs_modified": "Last Modified",
+  "agent_opfs_delete_confirm": "Are you sure to delete?",
+  "agent_opfs_delete_success": "Deleted",
+  "agent_opfs_file": "File",
+  "agent_opfs_directory": "Directory",
+  "agent_opfs_preview": "Preview",
+  "agent_opfs_root": "Root",
+  "agent_dom_permission_title": "The script is requesting DOM operation access",
+  "agent_dom_permission_describe": "This script requests the ability to read and manipulate web page DOM (click, fill forms, navigate, screenshot, etc.). Only grant access to trusted scripts.",
+  "agent_dom_permission_content": "Agent DOM Operations",
+  "agent_mcp_title": "MCP Servers",
+  "agent_mcp_add_server": "Add Server",
+  "agent_mcp_no_servers": "No MCP servers configured",
+  "agent_mcp_test_connection": "Test",
+  "agent_mcp_name_url_required": "Name and URL are required",
+  "agent_mcp_optional": "optional",
+  "agent_mcp_custom_headers": "Custom Headers",
+  "agent_mcp_enabled": "Enabled",
+  "agent_mcp_detail": "Details",
+  "agent_mcp_tools": "Tools",
+  "agent_mcp_resources": "Resources",
+  "agent_mcp_prompts": "Prompts",
+  "agent_mcp_no_tools": "No tools available",
+  "agent_mcp_no_resources": "No resources available",
+  "agent_mcp_no_prompts": "No prompts available",
+  "agent_mcp_loading": "Loading...",
+  "agent_mcp_parameters": "Parameters",
+  "agent_tasks": "Tasks",
+  "agent_tasks_title": "Scheduled Tasks",
+  "agent_tasks_create": "Create Task",
+  "agent_tasks_edit": "Edit Task",
+  "agent_tasks_mode_internal": "Internal",
+  "agent_tasks_mode_event": "Event",
+  "agent_tasks_cron": "Cron Expression",
+  "agent_tasks_next_run": "Next Run",
+  "agent_tasks_last_status": "Last Status",
+  "agent_tasks_run_now": "Run Now",
+  "agent_tasks_history": "History",
+  "agent_tasks_prompt": "Prompt",
+  "agent_tasks_max_iterations": "Max Iterations",
+  "agent_tasks_notify": "Notify on Complete",
+  "agent_tasks_no_tasks": "No scheduled tasks",
+  "agent_tasks_delete_confirm": "Are you sure to delete this task?",
+  "agent_tasks_clear_runs": "Clear History",
+  "agent_tasks_clear_runs_confirm": "Are you sure to clear the run history?",
+  "agent_tasks_event_hint": "When triggered, the script that created this task will be notified",
+  "agent_tasks_name_cron_required": "Name and Cron expression are required",
+  "agent_tasks_model_select": "Select Model",
+  "agent_tasks_skills": "Skills",
+  "agent_tasks_skills_auto": "Auto load all",
+  "agent_tasks_conversation_id": "Continue conversation ID (optional)",
+  "agent_tasks_run_status_success": "Success",
+  "agent_tasks_run_status_error": "Error",
+  "agent_tasks_run_status_running": "Running",
+  "agent_tasks_run_duration": "Duration",
+  "agent_tasks_run_usage": "Usage",
+  "agent_tasks_run_conversation": "View Conversation",
+  "agent_tasks_run_time": "Time",
+  "agent_tasks_run_status": "Status",
+  "agent_tasks_never_run": "Never run"
+}
diff --git a/src/locales/ja-JP/translation.json b/src/locales/ja-JP/translation.json
index 823949c52..a4690b132 100644
--- a/src/locales/ja-JP/translation.json
+++ b/src/locales/ja-JP/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "現在「ユーザー スクリプトを許可する」が有効ではないため、スクリプトは正常に動作しません。<a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉有効化の方法はこちら</a>",
   "lower_version_browser_guide": "ご使用のブラウザは古すぎるため、スクリプトは正常に動作しません。<a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉詳しくはこちら</a>",
   "click_to_reload": "👉再読み込みする",
-  "confirm_leave_page": "現在編集中です。他のページに移動すると現在の内容が失われます。移動しますか？",
   "page_in_blacklist": "現在のページはブラックリストにあり、スクリプトを使用できません",
   "baidu_netdisk": "百度ネットディスク",
   "netdisk_unbind": "{{provider}} の連携を解除",
@@ -454,7 +453,7 @@
   "expression_format_error": "式フォーマットエラー",
   "migration_confirm_message": "ストレージエンジンの移行を再試行すると既存のデータが変更されます。確認してください。詳細はこちら：https://docs.scriptcat.org/docs/change/v0.17/",
   "retry_migration": "ストレージエンジンの移行を再試行",
-  "script_modified_leave_confirm": "スクリプトが変更されています。離れると変更が失われます。続行しますか？",
+  "script_modified_leave_confirm": "現在の内容はまだ保存されていません。このままページを離れると変更は失われます。よろしいですか？",
   "create_success_note": "作成に成功しました。バックグラウンドスクリプトはデフォルトで有効になりませんのでご注意ください",
   "save_as_failed": "名前を付けて保存に失敗しました",
   "save_as_success": "名前を付けて保存に成功しました",
@@ -581,8 +580,143 @@
     "maybe_later": "後で",
     "settings_hint": "設定ページでいつでも変更できます。"
   },
+  "favicon_service": "Favicon サービス",
+  "favicon_service_desc": "ウェブサイトアイコンの取得サービスを選択",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "ローカル取得",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "スクリプトリストを表示",
     "hide_script_list": "スクリプトリストを非表示"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "チャット",
+  "agent_provider": "モデルサービス",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "モデルサービス",
+  "agent_provider_select": "AIサービスプロバイダー",
+  "agent_provider_api_base_url": "APIアドレス",
+  "agent_provider_api_key": "APIキー",
+  "agent_provider_model": "デフォルトモデル",
+  "agent_provider_test_connection": "接続テスト",
+  "agent_provider_test_success": "接続成功",
+  "agent_provider_test_failed": "接続失敗",
+  "agent_model_fetch": "モデルを取得",
+  "agent_model_fetch_failed": "モデルリストの取得に失敗しました",
+  "agent_model_name": "名前",
+  "agent_model_add": "モデルを追加",
+  "agent_model_edit": "編集",
+  "agent_model_delete": "削除",
+  "agent_model_set_default": "デフォルトに設定",
+  "agent_model_default_label": "デフォルト",
+  "agent_model_delete_confirm": "このモデル設定を削除してもよろしいですか？",
+  "agent_model_no_models": "モデル設定がありません",
+  "agent_coming_soon": "開発中...",
+  "agent_skills_title": "Skills 管理",
+  "agent_skills_add": "Skill を追加",
+  "agent_skills_empty": "インストール済みの Skill はありません",
+  "agent_skills_tools": "ツール",
+  "agent_skills_references": "参考資料",
+  "agent_skills_detail": "Skill 詳細",
+  "agent_skills_edit_prompt": "プロンプト",
+  "agent_skills_install": "Skill をインストール",
+  "agent_skills_install_url": "URL からインポート",
+  "agent_skills_install_paste": "SKILL.md を貼り付け",
+  "agent_skills_uninstall": "アンインストール",
+  "agent_skills_uninstall_confirm": "Skill「{{name}}」をアンインストールしますか？",
+  "agent_skills_save_success": "保存しました",
+  "agent_skills_install_success": "インストールしました",
+  "agent_skills_fetch_failed": "取得に失敗しました",
+  "agent_skills_add_script": "スクリプトを追加",
+  "agent_skills_add_reference": "参考資料を追加",
+  "agent_skills_install_zip": "ZIP アップロード",
+  "agent_skills_install_zip_hint": "クリックして .zip ファイルを選択",
+  "agent_skills_prompt": "プロンプト",
+  "agent_skills_installed_at": "インストール日時",
+  "agent_skills_refresh": "更新",
+  "agent_skills_refresh_success": "更新しました",
+  "agent_skills_tool_code": "ツールコード",
+  "agent_skills_click_to_view_code": "ツール名をクリックしてコードを表示",
+  "agent_chat_new": "新しいチャット",
+  "agent_chat_delete": "チャットを削除",
+  "agent_chat_delete_confirm": "この会話を削除しますか？",
+  "agent_chat_no_conversations": "会話がありません",
+  "agent_chat_input_placeholder": "メッセージを入力...",
+  "agent_chat_send": "送信",
+  "agent_chat_stop": "停止",
+  "agent_chat_thinking": "思考中",
+  "agent_chat_tool_call": "ツール呼び出し",
+  "agent_chat_error": "エラーが発生しました",
+  "agent_chat_no_model": "モデルが設定されていません。先にモデルサービスで追加してください。",
+  "agent_chat_model_select": "モデルを選択",
+  "agent_chat_rename": "名前を変更",
+  "agent_chat_copy": "コピー",
+  "agent_chat_copy_success": "コピーしました",
+  "agent_chat_regenerate": "再生成",
+  "agent_chat_streaming": "生成中...",
+  "agent_chat_newline": "改行",
+  "agent_chat_welcome_hint": "スクリプトに関する質問は何でもどうぞ",
+  "agent_chat_welcome_start": "会話を作成して始めましょう",
+  "agent_chat_tokens": "トークン",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} ツール呼び出し",
+  "agent_chat_delete_round": "削除",
+  "agent_chat_copy_message": "コピー",
+  "agent_chat_edit_message": "編集",
+  "agent_chat_save_and_send": "保存して送信",
+  "agent_chat_cancel_edit": "キャンセル",
+  "agent_permission_title": "スクリプトが Agent 会話の使用をリクエストしています",
+  "agent_permission_describe": "このスクリプトは Agent 会話機能の使用をリクエストしており、API トークンを消費します。信頼できるスクリプトにのみ許可してください。",
+  "agent_permission_content": "Agent 会話",
+  "cattool_parameters": "パラメータ",
+  "cattool_permissions": "権限",
+  "cattool_required": "必須",
+  "cattool_source_script": "スクリプトからインストール",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "CATTool 管理",
+  "agent_catool_empty": "CATTool がインストールされていません",
+  "agent_catool_detail": "詳細",
+  "agent_catool_delete": "削除",
+  "agent_catool_delete_confirm": "CATTool「{{name}}」を削除しますか？",
+  "agent_catool_delete_success": "削除しました",
+  "agent_catool_installed_at": "インストール日時",
+  "agent_catool_source": "ソーススクリプト",
+  "agent_catool_description": "説明",
+  "agent_catool_params": "パラメータ",
+  "agent_catool_grants": "権限",
+  "agent_catool_code": "コード",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "OPFS ファイルブラウザ",
+  "agent_opfs_empty": "空のディレクトリ",
+  "agent_opfs_name": "名前",
+  "agent_opfs_size": "サイズ",
+  "agent_opfs_type": "種類",
+  "agent_opfs_modified": "最終更新",
+  "agent_opfs_delete_confirm": "削除してよろしいですか？",
+  "agent_opfs_delete_success": "削除しました",
+  "agent_opfs_file": "ファイル",
+  "agent_opfs_directory": "ディレクトリ",
+  "agent_opfs_preview": "プレビュー",
+  "agent_opfs_root": "ルート",
+  "agent_dom_permission_title": "スクリプトが DOM 操作アクセスをリクエストしています",
+  "agent_dom_permission_describe": "このスクリプトはウェブページの DOM を読み取り操作する能力（クリック、フォーム入力、ナビゲーション、スクリーンショットなど）をリクエストしています。信頼できるスクリプトにのみ許可してください。",
+  "agent_dom_permission_content": "Agent DOM 操作",
+  "agent_mcp_title": "MCPサーバー",
+  "agent_mcp_add_server": "サーバーを追加",
+  "agent_mcp_no_servers": "MCPサーバーが設定されていません",
+  "agent_mcp_test_connection": "テスト",
+  "agent_mcp_name_url_required": "名前とURLは必須です",
+  "agent_mcp_optional": "任意",
+  "agent_mcp_custom_headers": "カスタムヘッダー",
+  "agent_mcp_enabled": "有効",
+  "agent_mcp_detail": "詳細",
+  "agent_mcp_tools": "ツール",
+  "agent_mcp_resources": "リソース",
+  "agent_mcp_prompts": "プロンプト",
+  "agent_mcp_no_tools": "利用可能なツールはありません",
+  "agent_mcp_no_resources": "利用可能なリソースはありません",
+  "agent_mcp_no_prompts": "利用可能なプロンプトはありません",
+  "agent_mcp_loading": "読み込み中...",
+  "agent_mcp_parameters": "パラメータ"
+}
diff --git a/src/locales/ru-RU/translation.json b/src/locales/ru-RU/translation.json
index 1b6b72973..5fb3db30c 100644
--- a/src/locales/ru-RU/translation.json
+++ b/src/locales/ru-RU/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "«Разрешить пользовательские скрипты» сейчас отключён, поэтому скрипты не могут работать корректно. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉Нажмите, чтобы узнать, как включить</a>",
   "lower_version_browser_guide": "Ваш браузер слишком устарел, поэтому скрипты не могут работать корректно. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉Нажмите, чтобы узнать подробнее</a>",
   "click_to_reload": "👉Нажмите для перезагрузки",
-  "confirm_leave_page": "В настоящее время идет редактирование. Переход на другую страницу приведет к потере текущего содержимого. Продолжить переход?",
   "page_in_blacklist": "Текущая страница находится в черном списке, невозможно использовать скрипты",
   "baidu_netdisk": "Baidu Netdisk",
   "netdisk_unbind": "Отвязать {{provider}}",
@@ -454,7 +453,7 @@
   "expression_format_error": "Ошибка формата выражения",
   "migration_confirm_message": "Повторная попытка миграции движка хранения изменит существующие данные. Пожалуйста, подтвердите. Подробности см.: https://docs.scriptcat.org/docs/change/v0.17/",
   "retry_migration": "Повторить миграцию движка хранения",
-  "script_modified_leave_confirm": "Скрипт был изменен. Изменения будут потеряны после выхода. Продолжить?",
+  "script_modified_leave_confirm": "Изменения не сохранены. Если вы покинете страницу, они будут потеряны. Вы уверены, что хотите уйти?",
   "create_success_note": "Создание успешно. Обратите внимание, что фоновые скрипты не включаются по умолчанию",
   "save_as_failed": "Ошибка «Сохранить как»",
   "save_as_success": "«Сохранить как» успешно",
@@ -581,8 +580,143 @@
     "maybe_later": "Может быть позже",
     "settings_hint": "Вы можете изменить эту опцию в настройках в любое время."
   },
+  "favicon_service": "Сервис Favicon",
+  "favicon_service_desc": "Выберите сервис для получения значков сайтов",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "Локальное получение",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "Показать список скриптов",
     "hide_script_list": "Скрыть список скриптов"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "Chat",
+  "agent_provider": "Model Service",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "Model Service",
+  "agent_provider_select": "AI Provider",
+  "agent_provider_api_base_url": "API Base URL",
+  "agent_provider_api_key": "API Key",
+  "agent_provider_model": "Default Model",
+  "agent_provider_test_connection": "Test Connection",
+  "agent_provider_test_success": "Connection Successful",
+  "agent_provider_test_failed": "Connection Failed",
+  "agent_model_fetch": "Получить модели",
+  "agent_model_fetch_failed": "Не удалось получить список моделей",
+  "agent_model_name": "Name",
+  "agent_model_add": "Add Model",
+  "agent_model_edit": "Edit",
+  "agent_model_delete": "Delete",
+  "agent_model_set_default": "Set as Default",
+  "agent_model_default_label": "Default",
+  "agent_model_delete_confirm": "Are you sure to delete this model?",
+  "agent_model_no_models": "No models configured",
+  "agent_coming_soon": "Coming soon...",
+  "agent_skills_title": "Skills Management",
+  "agent_skills_add": "Add Skill",
+  "agent_skills_empty": "No skills installed",
+  "agent_skills_tools": "Tools",
+  "agent_skills_references": "References",
+  "agent_skills_detail": "Skill Details",
+  "agent_skills_edit_prompt": "Prompt",
+  "agent_skills_install": "Install Skill",
+  "agent_skills_install_url": "Import from URL",
+  "agent_skills_install_paste": "Paste SKILL.md",
+  "agent_skills_uninstall": "Uninstall",
+  "agent_skills_uninstall_confirm": "Are you sure to uninstall Skill \"{{name}}\"?",
+  "agent_skills_save_success": "Saved successfully",
+  "agent_skills_install_success": "Installed successfully",
+  "agent_skills_fetch_failed": "Fetch failed",
+  "agent_skills_add_script": "Add Script",
+  "agent_skills_add_reference": "Add Reference",
+  "agent_skills_install_zip": "Upload ZIP",
+  "agent_skills_install_zip_hint": "Click to select a .zip file",
+  "agent_skills_prompt": "Prompt",
+  "agent_skills_installed_at": "Installed at",
+  "agent_skills_refresh": "Refresh",
+  "agent_skills_refresh_success": "Refreshed successfully",
+  "agent_skills_tool_code": "Tool Code",
+  "agent_skills_click_to_view_code": "Click tool name to view code",
+  "agent_chat_new": "New Chat",
+  "agent_chat_delete": "Delete Chat",
+  "agent_chat_delete_confirm": "Delete this conversation?",
+  "agent_chat_no_conversations": "No conversations",
+  "agent_chat_input_placeholder": "Type a message...",
+  "agent_chat_send": "Send",
+  "agent_chat_stop": "Stop",
+  "agent_chat_thinking": "Thinking",
+  "agent_chat_tool_call": "Tool Call",
+  "agent_chat_error": "Error occurred",
+  "agent_chat_no_model": "No model configured. Please add one in Model Service first.",
+  "agent_chat_model_select": "Select Model",
+  "agent_chat_rename": "Rename",
+  "agent_chat_copy": "Copy",
+  "agent_chat_copy_success": "Copied",
+  "agent_chat_regenerate": "Regenerate",
+  "agent_chat_streaming": "Generating...",
+  "agent_chat_newline": "for new line",
+  "agent_chat_welcome_hint": "Ask me anything about your scripts",
+  "agent_chat_welcome_start": "Create a conversation to get started",
+  "agent_chat_tokens": "tokens",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} tools",
+  "agent_chat_delete_round": "Delete",
+  "agent_chat_copy_message": "Copy",
+  "agent_chat_edit_message": "Редактировать",
+  "agent_chat_save_and_send": "Сохранить и отправить",
+  "agent_chat_cancel_edit": "Отмена",
+  "agent_permission_title": "Скрипт запрашивает использование Agent разговора",
+  "agent_permission_describe": "Этот скрипт запрашивает доступ к функции Agent разговора, что будет потреблять API токены. Разрешайте только доверенным скриптам.",
+  "agent_permission_content": "Agent разговор",
+  "cattool_parameters": "Параметры",
+  "cattool_permissions": "Разрешения",
+  "cattool_required": "обязательно",
+  "cattool_source_script": "Установлено скриптом",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "Управление CATTool",
+  "agent_catool_empty": "CATTool не установлены",
+  "agent_catool_detail": "Подробности",
+  "agent_catool_delete": "Удалить",
+  "agent_catool_delete_confirm": "Удалить CATTool «{{name}}»?",
+  "agent_catool_delete_success": "Успешно удалено",
+  "agent_catool_installed_at": "Установлено",
+  "agent_catool_source": "Исходный скрипт",
+  "agent_catool_description": "Описание",
+  "agent_catool_params": "Параметры",
+  "agent_catool_grants": "Разрешения",
+  "agent_catool_code": "Код",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "Файловый браузер OPFS",
+  "agent_opfs_empty": "Пустая директория",
+  "agent_opfs_name": "Имя",
+  "agent_opfs_size": "Размер",
+  "agent_opfs_type": "Тип",
+  "agent_opfs_modified": "Последнее изменение",
+  "agent_opfs_delete_confirm": "Вы уверены, что хотите удалить?",
+  "agent_opfs_delete_success": "Удалено",
+  "agent_opfs_file": "Файл",
+  "agent_opfs_directory": "Директория",
+  "agent_opfs_preview": "Предпросмотр",
+  "agent_opfs_root": "Корень",
+  "agent_dom_permission_title": "Скрипт запрашивает доступ к операциям DOM",
+  "agent_dom_permission_describe": "Этот скрипт запрашивает возможность читать и управлять DOM веб-страницы (клик, заполнение форм, навигация, скриншот и т.д.). Разрешайте только доверенным скриптам.",
+  "agent_dom_permission_content": "Agent DOM операции",
+  "agent_mcp_title": "MCP серверы",
+  "agent_mcp_add_server": "Добавить сервер",
+  "agent_mcp_no_servers": "MCP серверы не настроены",
+  "agent_mcp_test_connection": "Тест",
+  "agent_mcp_name_url_required": "Имя и URL обязательны",
+  "agent_mcp_optional": "необязательно",
+  "agent_mcp_custom_headers": "Пользовательские заголовки",
+  "agent_mcp_enabled": "Включено",
+  "agent_mcp_detail": "Подробности",
+  "agent_mcp_tools": "Инструменты",
+  "agent_mcp_resources": "Ресурсы",
+  "agent_mcp_prompts": "Промпты",
+  "agent_mcp_no_tools": "Нет доступных инструментов",
+  "agent_mcp_no_resources": "Нет доступных ресурсов",
+  "agent_mcp_no_prompts": "Нет доступных промптов",
+  "agent_mcp_loading": "Загрузка...",
+  "agent_mcp_parameters": "Параметры"
+}
diff --git a/src/locales/vi-VN/translation.json b/src/locales/vi-VN/translation.json
index c69cb10be..a3ac870e8 100644
--- a/src/locales/vi-VN/translation.json
+++ b/src/locales/vi-VN/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "'Cho phép tập lệnh người dùng' hiện chưa được bật, nên các script không thể hoạt động đúng cách. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉Nhấn để xem cách bật</a>",
   "lower_version_browser_guide": "Trình duyệt của bạn quá cũ, nên các script không thể hoạt động đúng cách. <a href=\"https://docs.scriptcat.org/en/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉Nhấn để xem thêm</a>",
   "click_to_reload": "👉Nhấp chuột để tải lại",
-  "confirm_leave_page": "Hiện đang ở trạng thái chỉnh sửa. Rời khỏi trang này sẽ làm mất nội dung hiện tại. Bạn có muốn rời đi không?",
   "page_in_blacklist": "Trang hiện tại nằm trong danh sách đen, không thể sử dụng script",
   "baidu_netdisk": "Baidunetdisk",
   "netdisk_unbind": "Hủy liên kết {{provider}}",
@@ -454,7 +453,7 @@
   "expression_format_error": "Lỗi định dạng biểu thức điều kiện",
   "migration_confirm_message": "Thử lại công cụ lưu trữ di chuyển để sửa đổi dữ liệu hiện có. Vui lòng xác nhận, xem: https://docs.scriptcat.org/docs/change/v0.17/.",
   "retry_migration": "Thử lại công cụ lưu trữ di chuyển",
-  "script_modified_leave_confirm": "Script đã được sửa đổi. Các thay đổi sẽ bị mất sau khi rời đi, tiếp tục?",
+  "script_modified_leave_confirm": "Nội dung hiện chưa được lưu. Nếu rời khỏi trang, các thay đổi sẽ bị mất. Bạn có chắc chắn muốn rời đi không?",
   "create_success_note": "Script mới được tạo thành công. Lưu ý rằng script nền sẽ không được bật theo mặc định.",
   "save_as_failed": "Lưu thành thất bại",
   "save_as_success": "Lưu thành công",
@@ -581,8 +580,143 @@
     "maybe_later": "Để sau",
     "settings_hint": "Bạn có thể thay đổi tùy chọn này trong cài đặt bất kỳ lúc nào."
   },
+  "favicon_service": "Dịch vụ Favicon",
+  "favicon_service_desc": "Chọn dịch vụ để lấy biểu tượng trang web",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "Lấy cục bộ",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "Hiển thị danh sách script",
     "hide_script_list": "Ẩn danh sách script"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "Chat",
+  "agent_provider": "Model Service",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "Model Service",
+  "agent_provider_select": "AI Provider",
+  "agent_provider_api_base_url": "API Base URL",
+  "agent_provider_api_key": "API Key",
+  "agent_provider_model": "Default Model",
+  "agent_provider_test_connection": "Test Connection",
+  "agent_provider_test_success": "Connection Successful",
+  "agent_provider_test_failed": "Connection Failed",
+  "agent_model_fetch": "Fetch Models",
+  "agent_model_fetch_failed": "Failed to fetch models",
+  "agent_model_name": "Name",
+  "agent_model_add": "Add Model",
+  "agent_model_edit": "Edit",
+  "agent_model_delete": "Delete",
+  "agent_model_set_default": "Set as Default",
+  "agent_model_default_label": "Default",
+  "agent_model_delete_confirm": "Are you sure to delete this model?",
+  "agent_model_no_models": "No models configured",
+  "agent_coming_soon": "Coming soon...",
+  "agent_skills_title": "Skills Management",
+  "agent_skills_add": "Add Skill",
+  "agent_skills_empty": "No skills installed",
+  "agent_skills_tools": "Tools",
+  "agent_skills_references": "References",
+  "agent_skills_detail": "Skill Details",
+  "agent_skills_edit_prompt": "Prompt",
+  "agent_skills_install": "Install Skill",
+  "agent_skills_install_url": "Import from URL",
+  "agent_skills_install_paste": "Paste SKILL.md",
+  "agent_skills_uninstall": "Uninstall",
+  "agent_skills_uninstall_confirm": "Are you sure to uninstall Skill \"{{name}}\"?",
+  "agent_skills_save_success": "Saved successfully",
+  "agent_skills_install_success": "Installed successfully",
+  "agent_skills_fetch_failed": "Fetch failed",
+  "agent_skills_add_script": "Add Script",
+  "agent_skills_add_reference": "Add Reference",
+  "agent_skills_install_zip": "Upload ZIP",
+  "agent_skills_install_zip_hint": "Click to select a .zip file",
+  "agent_skills_prompt": "Prompt",
+  "agent_skills_installed_at": "Installed at",
+  "agent_skills_refresh": "Refresh",
+  "agent_skills_refresh_success": "Refreshed successfully",
+  "agent_skills_tool_code": "Tool Code",
+  "agent_skills_click_to_view_code": "Click tool name to view code",
+  "agent_chat_new": "New Chat",
+  "agent_chat_delete": "Delete Chat",
+  "agent_chat_delete_confirm": "Delete this conversation?",
+  "agent_chat_no_conversations": "No conversations",
+  "agent_chat_input_placeholder": "Type a message...",
+  "agent_chat_send": "Send",
+  "agent_chat_stop": "Stop",
+  "agent_chat_thinking": "Thinking",
+  "agent_chat_tool_call": "Tool Call",
+  "agent_chat_error": "Error occurred",
+  "agent_chat_no_model": "No model configured. Please add one in Model Service first.",
+  "agent_chat_model_select": "Select Model",
+  "agent_chat_rename": "Rename",
+  "agent_chat_copy": "Copy",
+  "agent_chat_copy_success": "Copied",
+  "agent_chat_regenerate": "Regenerate",
+  "agent_chat_streaming": "Generating...",
+  "agent_chat_newline": "for new line",
+  "agent_chat_welcome_hint": "Ask me anything about your scripts",
+  "agent_chat_welcome_start": "Create a conversation to get started",
+  "agent_chat_tokens": "tokens",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} tools",
+  "agent_chat_delete_round": "Delete",
+  "agent_chat_copy_message": "Copy",
+  "agent_chat_edit_message": "Chỉnh sửa",
+  "agent_chat_save_and_send": "Lưu & Gửi",
+  "agent_chat_cancel_edit": "Hủy",
+  "agent_permission_title": "Script yêu cầu sử dụng cuộc trò chuyện Agent",
+  "agent_permission_describe": "Script này yêu cầu quyền truy cập chức năng cuộc trò chuyện Agent, sẽ tiêu thụ API token. Chỉ cấp quyền cho các script đáng tin cậy.",
+  "agent_permission_content": "Cuộc trò chuyện Agent",
+  "cattool_parameters": "Tham số",
+  "cattool_permissions": "Quyền",
+  "cattool_required": "bắt buộc",
+  "cattool_source_script": "Được cài đặt bởi script",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "Quản lý CATTool",
+  "agent_catool_empty": "Chưa có CATTool nào được cài đặt",
+  "agent_catool_detail": "Chi tiết",
+  "agent_catool_delete": "Xóa",
+  "agent_catool_delete_confirm": "Bạn có chắc muốn xóa CATTool \"{{name}}\"?",
+  "agent_catool_delete_success": "Đã xóa thành công",
+  "agent_catool_installed_at": "Thời gian cài đặt",
+  "agent_catool_source": "Script nguồn",
+  "agent_catool_description": "Mô tả",
+  "agent_catool_params": "Tham số",
+  "agent_catool_grants": "Quyền",
+  "agent_catool_code": "Mã nguồn",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "Trình duyệt tệp OPFS",
+  "agent_opfs_empty": "Thư mục trống",
+  "agent_opfs_name": "Tên",
+  "agent_opfs_size": "Kích thước",
+  "agent_opfs_type": "Loại",
+  "agent_opfs_modified": "Sửa đổi lần cuối",
+  "agent_opfs_delete_confirm": "Bạn có chắc chắn muốn xóa không?",
+  "agent_opfs_delete_success": "Đã xóa",
+  "agent_opfs_file": "Tệp",
+  "agent_opfs_directory": "Thư mục",
+  "agent_opfs_preview": "Xem trước",
+  "agent_opfs_root": "Gốc",
+  "agent_dom_permission_title": "Script yêu cầu quyền thao tác DOM",
+  "agent_dom_permission_describe": "Script này yêu cầu khả năng đọc và thao tác DOM trang web (nhấp chuột, điền biểu mẫu, điều hướng, chụp ảnh màn hình, v.v.). Chỉ cấp quyền cho các script đáng tin cậy.",
+  "agent_dom_permission_content": "Agent DOM thao tác",
+  "agent_mcp_title": "Máy chủ MCP",
+  "agent_mcp_add_server": "Thêm máy chủ",
+  "agent_mcp_no_servers": "Chưa cấu hình máy chủ MCP",
+  "agent_mcp_test_connection": "Kiểm tra",
+  "agent_mcp_name_url_required": "Tên và URL là bắt buộc",
+  "agent_mcp_optional": "tùy chọn",
+  "agent_mcp_custom_headers": "Header tùy chỉnh",
+  "agent_mcp_enabled": "Đã bật",
+  "agent_mcp_detail": "Chi tiết",
+  "agent_mcp_tools": "Công cụ",
+  "agent_mcp_resources": "Tài nguyên",
+  "agent_mcp_prompts": "Lời nhắc",
+  "agent_mcp_no_tools": "Không có công cụ nào",
+  "agent_mcp_no_resources": "Không có tài nguyên nào",
+  "agent_mcp_no_prompts": "Không có lời nhắc nào",
+  "agent_mcp_loading": "Đang tải...",
+  "agent_mcp_parameters": "Tham số"
+}
diff --git a/src/locales/zh-CN/translation.json b/src/locales/zh-CN/translation.json
index 1267d3472..9b8bf3f29 100644
--- a/src/locales/zh-CN/translation.json
+++ b/src/locales/zh-CN/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "当前未启用“允许运行用户脚本”，脚本无法正常运行。<a href=\"https://docs.scriptcat.org/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉点击查看启用方法</a>",
   "lower_version_browser_guide": "您的浏览器版本过低，脚本无法正常运行。<a href=\"https://docs.scriptcat.org/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉点击了解更多</a>",
   "click_to_reload": "👉点击重新加载",
-  "confirm_leave_page": "当前正在编辑状态，跳转其它页面将会丢失当前内容，是否跳转？",
   "page_in_blacklist": "当前页面在黑名单中，无法使用脚本",
   "baidu_netdisk": "百度网盘",
   "netdisk_unbind": "解除绑定 {{provider}}",
@@ -454,7 +453,7 @@
   "expression_format_error": "表达式格式错误",
   "migration_confirm_message": "重试迁移储存引擎会对现有数据造成修改，请确认，详情请看：https://docs.scriptcat.org/docs/change/v0.17/",
   "retry_migration": "重试迁移储存引擎",
-  "script_modified_leave_confirm": "脚本已修改, 离开后会丢失修改, 是否继续?",
+  "script_modified_leave_confirm": "当前内容尚未保存，离开后更改将丢失，确定要离开吗？",
   "create_success_note": "新建成功,请注意后台脚本不会默认开启",
   "save_as_failed": "另存为失败",
   "save_as_success": "另存为成功",
@@ -581,8 +580,178 @@
     "maybe_later": "暂不启用",
     "settings_hint": "你可以随时在设置中修改此选项。"
   },
+  "favicon_service": "图标服务",
+  "favicon_service_desc": "选择获取网站图标的服务",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "本地获取",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "显示脚本列表",
     "hide_script_list": "隐藏脚本列表"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "会话",
+  "agent_provider": "模型服务",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "模型服务",
+  "agent_provider_select": "AI 服务提供商",
+  "agent_provider_api_base_url": "API 地址",
+  "agent_provider_api_key": "API 密钥",
+  "agent_provider_model": "默认模型",
+  "agent_provider_test_connection": "测试连接",
+  "agent_provider_test_success": "连接成功",
+  "agent_provider_test_failed": "连接失败",
+  "agent_model_fetch": "获取模型",
+  "agent_model_fetch_failed": "获取模型列表失败",
+  "agent_model_name": "名称",
+  "agent_model_add": "添加模型",
+  "agent_model_edit": "编辑",
+  "agent_model_delete": "删除",
+  "agent_model_set_default": "设为默认",
+  "agent_model_default_label": "默认",
+  "agent_model_delete_confirm": "确定要删除此模型配置吗？",
+  "agent_model_no_models": "暂无模型配置",
+  "agent_coming_soon": "开发中...",
+  "agent_skills_title": "Skills 管理",
+  "agent_skills_add": "添加 Skill",
+  "agent_skills_empty": "暂无已安装的 Skill",
+  "agent_skills_tools": "工具",
+  "agent_skills_references": "参考资料",
+  "agent_skills_detail": "Skill 详情",
+  "agent_skills_edit_prompt": "提示词",
+  "agent_skills_install": "安装 Skill",
+  "agent_skills_install_url": "从 URL 导入",
+  "agent_skills_install_paste": "粘贴 SKILL.md",
+  "agent_skills_uninstall": "卸载",
+  "agent_skills_uninstall_confirm": "确定要卸载 Skill「{{name}}」？",
+  "agent_skills_save_success": "保存成功",
+  "agent_skills_install_success": "安装成功",
+  "agent_skills_fetch_failed": "获取失败",
+  "agent_skills_add_script": "添加脚本",
+  "agent_skills_add_reference": "添加参考资料",
+  "agent_skills_install_zip": "上传 ZIP",
+  "agent_skills_install_zip_hint": "点击选择 .zip 文件",
+  "agent_skills_prompt": "提示词",
+  "agent_skills_installed_at": "安装时间",
+  "agent_skills_refresh": "刷新",
+  "agent_skills_refresh_success": "刷新成功",
+  "agent_skills_tool_code": "工具代码",
+  "agent_skills_click_to_view_code": "点击工具名称查看代码",
+  "agent_skills_config": "配置",
+  "agent_skills_config_saved": "配置已保存",
+  "agent_chat_new": "新建会话",
+  "agent_chat_delete": "删除会话",
+  "agent_chat_delete_confirm": "确定要删除此会话吗？",
+  "agent_chat_no_conversations": "暂无会话",
+  "agent_chat_input_placeholder": "输入消息...",
+  "agent_chat_send": "发送",
+  "agent_chat_stop": "停止",
+  "agent_chat_thinking": "思考过程",
+  "agent_chat_tool_call": "工具调用",
+  "agent_chat_error": "发生错误",
+  "agent_chat_no_model": "未配置模型，请先在模型服务中添加",
+  "agent_chat_model_select": "选择模型",
+  "agent_chat_rename": "重命名",
+  "agent_chat_copy": "复制",
+  "agent_chat_copy_success": "已复制",
+  "agent_chat_regenerate": "重新生成",
+  "agent_chat_streaming": "生成中...",
+  "agent_chat_newline": "换行",
+  "agent_chat_welcome_hint": "有关脚本的任何问题，尽管问我",
+  "agent_chat_welcome_start": "创建一个对话开始吧",
+  "agent_chat_tokens": "令牌",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} 次工具调用",
+  "agent_chat_delete_round": "删除",
+  "agent_chat_copy_message": "复制",
+  "agent_chat_edit_message": "编辑",
+  "agent_chat_save_and_send": "保存并发送",
+  "agent_chat_cancel_edit": "取消",
+  "agent_permission_title": "脚本请求使用 Agent 对话",
+  "agent_permission_describe": "此脚本请求使用 Agent 对话功能，将消耗 API Token。请仅对可信脚本授权。",
+  "agent_permission_content": "Agent 对话",
+  "cattool_parameters": "参数",
+  "cattool_permissions": "权限",
+  "cattool_required": "必填",
+  "cattool_source_script": "由脚本安装",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "CATTool 管理",
+  "agent_catool_empty": "暂无已安装的 CATTool",
+  "agent_catool_detail": "详情",
+  "agent_catool_delete": "删除",
+  "agent_catool_delete_confirm": "确定要删除 CATTool「{{name}}」？",
+  "agent_catool_delete_success": "删除成功",
+  "agent_catool_installed_at": "安装时间",
+  "agent_catool_source": "来源脚本",
+  "agent_catool_description": "描述",
+  "agent_catool_params": "参数",
+  "agent_catool_grants": "权限",
+  "agent_catool_code": "代码",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "OPFS 文件浏览器",
+  "agent_opfs_empty": "空目录",
+  "agent_opfs_name": "名称",
+  "agent_opfs_size": "大小",
+  "agent_opfs_type": "类型",
+  "agent_opfs_modified": "最后修改",
+  "agent_opfs_delete_confirm": "确定要删除吗？",
+  "agent_opfs_delete_success": "已删除",
+  "agent_opfs_file": "文件",
+  "agent_opfs_directory": "目录",
+  "agent_opfs_preview": "预览",
+  "agent_opfs_root": "根目录",
+  "agent_dom_permission_title": "脚本请求 DOM 操作权限",
+  "agent_dom_permission_describe": "此脚本请求读取和操作网页 DOM 的能力（点击、填写表单、导航、截图等）。请仅对可信脚本授权。",
+  "agent_dom_permission_content": "Agent DOM 操作",
+  "agent_mcp_title": "MCP 服务器",
+  "agent_mcp_add_server": "添加服务器",
+  "agent_mcp_no_servers": "未配置 MCP 服务器",
+  "agent_mcp_test_connection": "测试",
+  "agent_mcp_name_url_required": "名称和 URL 不能为空",
+  "agent_mcp_optional": "可选",
+  "agent_mcp_custom_headers": "自定义请求头",
+  "agent_mcp_enabled": "启用",
+  "agent_mcp_detail": "详情",
+  "agent_mcp_tools": "工具",
+  "agent_mcp_resources": "资源",
+  "agent_mcp_prompts": "提示词",
+  "agent_mcp_no_tools": "暂无可用工具",
+  "agent_mcp_no_resources": "暂无可用资源",
+  "agent_mcp_no_prompts": "暂无可用提示词",
+  "agent_mcp_loading": "加载中...",
+  "agent_mcp_parameters": "参数",
+  "agent_tasks": "定时任务",
+  "agent_tasks_title": "定时任务管理",
+  "agent_tasks_create": "创建任务",
+  "agent_tasks_edit": "编辑任务",
+  "agent_tasks_mode_internal": "内部执行",
+  "agent_tasks_mode_event": "事件驱动",
+  "agent_tasks_cron": "Cron 表达式",
+  "agent_tasks_next_run": "下次运行",
+  "agent_tasks_last_status": "上次状态",
+  "agent_tasks_run_now": "立即运行",
+  "agent_tasks_history": "运行历史",
+  "agent_tasks_prompt": "提示词",
+  "agent_tasks_max_iterations": "最大迭代次数",
+  "agent_tasks_notify": "完成通知",
+  "agent_tasks_no_tasks": "暂无定时任务",
+  "agent_tasks_delete_confirm": "确定要删除此定时任务吗？",
+  "agent_tasks_clear_runs": "清除历史",
+  "agent_tasks_clear_runs_confirm": "确定要清除此任务的运行历史吗？",
+  "agent_tasks_event_hint": "任务触发时将通知创建此任务的脚本",
+  "agent_tasks_name_cron_required": "名称和 Cron 表达式不能为空",
+  "agent_tasks_model_select": "选择模型",
+  "agent_tasks_skills": "Skills",
+  "agent_tasks_skills_auto": "自动加载全部",
+  "agent_tasks_conversation_id": "续接对话 ID（可选）",
+  "agent_tasks_run_status_success": "成功",
+  "agent_tasks_run_status_error": "失败",
+  "agent_tasks_run_status_running": "运行中",
+  "agent_tasks_run_duration": "耗时",
+  "agent_tasks_run_usage": "用量",
+  "agent_tasks_run_conversation": "查看对话",
+  "agent_tasks_run_time": "时间",
+  "agent_tasks_run_status": "状态",
+  "agent_tasks_never_run": "未运行"
+}
diff --git a/src/locales/zh-TW/translation.json b/src/locales/zh-TW/translation.json
index a56ddd57e..83e1213bd 100644
--- a/src/locales/zh-TW/translation.json
+++ b/src/locales/zh-TW/translation.json
@@ -438,7 +438,6 @@
   "allow_user_script_guide": "目前尚未啟用「允許使用者指令碼」，腳本無法正常執行。<a href=\"https://docs.scriptcat.org/docs/use/open-dev/?browser={{browser}}\" target=\"black\" style=\"color: var(--color-text-1)\">👉點此查看啟用方式</a>",
   "lower_version_browser_guide": "您的瀏覽器版本過舊，腳本無法正常執行。<a href=\"https://docs.scriptcat.org/docs/use/open-dev/\" target=\"black\" style=\"color: var(--color-text-1)\">👉點擊了解更多</a>",
   "click_to_reload": "👉點擊重新載入",
-  "confirm_leave_page": "目前正在編輯狀態，跳轉其他頁面將會遺失目前內容，是否跳轉？",
   "page_in_blacklist": "目前頁面在黑名單中，無法使用腳本",
   "baidu_netdisk": "百度網盤",
   "netdisk_unbind": "解除綁定 {{provider}}",
@@ -454,7 +453,7 @@
   "expression_format_error": "表達式格式錯誤",
   "migration_confirm_message": "重試遷移儲存引擎會對現有資料造成修改，請確認，詳情請參閱：https://docs.scriptcat.org/docs/change/v0.17/",
   "retry_migration": "重試遷移儲存引擎",
-  "script_modified_leave_confirm": "腳本已修改，離開後會遺失修改，是否繼續？",
+  "script_modified_leave_confirm": "目前內容尚未儲存，離開後變更將會遺失，確定要離開嗎？",
   "create_success_note": "新建成功，請注意背景腳本不會預設開啟",
   "save_as_failed": "另存新檔失敗",
   "save_as_success": "另存新檔成功",
@@ -581,8 +580,143 @@
     "maybe_later": "暫不啟用",
     "settings_hint": "你可以隨時在設定中修改此選項。"
   },
+  "favicon_service": "圖示服務",
+  "favicon_service_desc": "選擇取得網站圖示的服務",
+  "favicon_service_scriptcat": "ScriptCat",
+  "favicon_service_local": "本地取得",
+  "favicon_service_google": "Google",
   "editor": {
     "show_script_list": "顯示腳本列表",
     "hide_script_list": "隱藏腳本列表"
-  }
-}
\ No newline at end of file
+  },
+  "agent": "AI Agent",
+  "agent_chat": "會話",
+  "agent_provider": "模型服務",
+  "agent_mcp": "MCP",
+  "agent_skills": "Skills",
+  "agent_provider_title": "模型服務",
+  "agent_provider_select": "AI 服務提供商",
+  "agent_provider_api_base_url": "API 地址",
+  "agent_provider_api_key": "API 密鑰",
+  "agent_provider_model": "預設模型",
+  "agent_provider_test_connection": "測試連接",
+  "agent_provider_test_success": "連接成功",
+  "agent_provider_test_failed": "連接失敗",
+  "agent_model_fetch": "取得模型",
+  "agent_model_fetch_failed": "取得模型列表失敗",
+  "agent_model_name": "名稱",
+  "agent_model_add": "新增模型",
+  "agent_model_edit": "編輯",
+  "agent_model_delete": "刪除",
+  "agent_model_set_default": "設為預設",
+  "agent_model_default_label": "預設",
+  "agent_model_delete_confirm": "確定要刪除此模型配置嗎？",
+  "agent_model_no_models": "暫無模型配置",
+  "agent_coming_soon": "開發中...",
+  "agent_skills_title": "Skills 管理",
+  "agent_skills_add": "新增 Skill",
+  "agent_skills_empty": "尚無已安裝的 Skill",
+  "agent_skills_tools": "工具",
+  "agent_skills_references": "參考資料",
+  "agent_skills_detail": "Skill 詳情",
+  "agent_skills_edit_prompt": "提示詞",
+  "agent_skills_install": "安裝 Skill",
+  "agent_skills_install_url": "從 URL 匯入",
+  "agent_skills_install_paste": "貼上 SKILL.md",
+  "agent_skills_uninstall": "解除安裝",
+  "agent_skills_uninstall_confirm": "確定要解除安裝 Skill「{{name}}」？",
+  "agent_skills_save_success": "儲存成功",
+  "agent_skills_install_success": "安裝成功",
+  "agent_skills_fetch_failed": "取得失敗",
+  "agent_skills_add_script": "新增腳本",
+  "agent_skills_add_reference": "新增參考資料",
+  "agent_skills_install_zip": "上傳 ZIP",
+  "agent_skills_install_zip_hint": "點擊選擇 .zip 檔案",
+  "agent_skills_prompt": "提示詞",
+  "agent_skills_installed_at": "安裝時間",
+  "agent_skills_refresh": "重新整理",
+  "agent_skills_refresh_success": "重新整理成功",
+  "agent_skills_tool_code": "工具程式碼",
+  "agent_skills_click_to_view_code": "點擊工具名稱查看程式碼",
+  "agent_chat_new": "新建會話",
+  "agent_chat_delete": "刪除會話",
+  "agent_chat_delete_confirm": "確定要刪除此會話嗎？",
+  "agent_chat_no_conversations": "暫無會話",
+  "agent_chat_input_placeholder": "輸入訊息...",
+  "agent_chat_send": "發送",
+  "agent_chat_stop": "停止",
+  "agent_chat_thinking": "思考過程",
+  "agent_chat_tool_call": "工具調用",
+  "agent_chat_error": "發生錯誤",
+  "agent_chat_no_model": "未配置模型，請先在模型服務中新增",
+  "agent_chat_model_select": "選擇模型",
+  "agent_chat_rename": "重新命名",
+  "agent_chat_copy": "複製",
+  "agent_chat_copy_success": "已複製",
+  "agent_chat_regenerate": "重新生成",
+  "agent_chat_streaming": "生成中...",
+  "agent_chat_newline": "換行",
+  "agent_chat_welcome_hint": "有關腳本的任何問題，儘管問我",
+  "agent_chat_welcome_start": "建立一個對話開始吧",
+  "agent_chat_tokens": "令牌",
+  "agent_chat_first_token": "TTFT",
+  "agent_chat_tools_count": "{{count}} 次工具調用",
+  "agent_chat_delete_round": "刪除",
+  "agent_chat_copy_message": "複製",
+  "agent_chat_edit_message": "編輯",
+  "agent_chat_save_and_send": "儲存並傳送",
+  "agent_chat_cancel_edit": "取消",
+  "agent_permission_title": "腳本請求使用 Agent 對話",
+  "agent_permission_describe": "此腳本請求使用 Agent 對話功能，將消耗 API Token。請僅對可信腳本授權。",
+  "agent_permission_content": "Agent 對話",
+  "cattool_parameters": "參數",
+  "cattool_permissions": "權限",
+  "cattool_required": "必填",
+  "cattool_source_script": "由腳本安裝",
+  "agent_catool": "CATTool",
+  "agent_catool_title": "CATTool 管理",
+  "agent_catool_empty": "尚無已安裝的 CATTool",
+  "agent_catool_detail": "詳情",
+  "agent_catool_delete": "刪除",
+  "agent_catool_delete_confirm": "確定要刪除 CATTool「{{name}}」？",
+  "agent_catool_delete_success": "刪除成功",
+  "agent_catool_installed_at": "安裝時間",
+  "agent_catool_source": "來源腳本",
+  "agent_catool_description": "描述",
+  "agent_catool_params": "參數",
+  "agent_catool_grants": "權限",
+  "agent_catool_code": "程式碼",
+  "agent_opfs": "OPFS",
+  "agent_opfs_title": "OPFS 檔案瀏覽器",
+  "agent_opfs_empty": "空目錄",
+  "agent_opfs_name": "名稱",
+  "agent_opfs_size": "大小",
+  "agent_opfs_type": "類型",
+  "agent_opfs_modified": "最後修改",
+  "agent_opfs_delete_confirm": "確定要刪除嗎？",
+  "agent_opfs_delete_success": "已刪除",
+  "agent_opfs_file": "檔案",
+  "agent_opfs_directory": "目錄",
+  "agent_opfs_preview": "預覽",
+  "agent_opfs_root": "根目錄",
+  "agent_dom_permission_title": "腳本請求 DOM 操作權限",
+  "agent_dom_permission_describe": "此腳本請求讀取和操作網頁 DOM 的能力（點擊、填寫表單、導航、截圖等）。請僅對可信腳本授權。",
+  "agent_dom_permission_content": "Agent DOM 操作",
+  "agent_mcp_title": "MCP 伺服器",
+  "agent_mcp_add_server": "新增伺服器",
+  "agent_mcp_no_servers": "未配置 MCP 伺服器",
+  "agent_mcp_test_connection": "測試",
+  "agent_mcp_name_url_required": "名稱和 URL 不能為空",
+  "agent_mcp_optional": "可選",
+  "agent_mcp_custom_headers": "自訂請求標頭",
+  "agent_mcp_enabled": "啟用",
+  "agent_mcp_detail": "詳情",
+  "agent_mcp_tools": "工具",
+  "agent_mcp_resources": "資源",
+  "agent_mcp_prompts": "提示詞",
+  "agent_mcp_no_tools": "暫無可用工具",
+  "agent_mcp_no_resources": "暫無可用資源",
+  "agent_mcp_no_prompts": "暫無可用提示詞",
+  "agent_mcp_loading": "載入中...",
+  "agent_mcp_parameters": "參數"
+}
diff --git a/src/manifest.json b/src/manifest.json
index 35a72068d..45800a971 100644
--- a/src/manifest.json
+++ b/src/manifest.json
@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "__MSG_scriptcat__",
-  "version": "1.3.1",
+  "version": "1.5.0.1001",
   "author": "CodFrm",
   "description": "__MSG_scriptcat_description__",
   "options_ui": {
@@ -10,9 +10,7 @@
   },
   "background": {
     "service_worker": "src/service_worker.js",
-    "scripts": [
-      "src/service_worker.js"
-    ]
+    "scripts": ["src/service_worker.js"]
   },
   "incognito": "split",
   "action": {
@@ -41,28 +39,18 @@
     "notifications",
     "clipboardWrite",
     "unlimitedStorage",
-    "declarativeNetRequest"
-  ],
-  "optional_permissions": [
-    "background",
-    "userScripts"
-  ],
-  "host_permissions": [
-    "<all_urls>"
+    "declarativeNetRequest",
+    "debugger"
   ],
+  "optional_permissions": ["background", "userScripts"],
+  "host_permissions": ["<all_urls>"],
   "sandbox": {
-    "pages": [
-      "src/sandbox.html"
-    ]
+    "pages": ["src/sandbox.html"]
   },
   "web_accessible_resources": [
     {
-      "resources": [
-        "/src/install.html"
-      ],
-      "matches": [
-        "<all_urls>"
-      ]
+      "resources": ["/src/install.html"],
+      "matches": ["<all_urls>"]
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/src/pages/batchupdate/index.css b/src/pages/batchupdate/index.css
index 6954b0a75..ba648c31d 100644
--- a/src/pages/batchupdate/index.css
+++ b/src/pages/batchupdate/index.css
@@ -1,19 +1,19 @@
 .batchupdate-mainlayout {
-    min-height: max-content;
-    padding-top: 12px;
-    padding-bottom: 12px;
+  min-height: max-content;
+  padding-top: 12px;
+  padding-bottom: 12px;
 }
 
 body .text-clickable {
-    color: inherit;
-    cursor: pointer;
+  color: inherit;
+  cursor: pointer;
 }
 
 body .text-clickable:hover {
-    color: inherit;
-    text-decoration: underline;
+  color: inherit;
+  text-decoration: underline;
 }
 
 .script-card.card-disabled {
-    filter: contrast(0.9);
+  filter: contrast(0.9);
 }
diff --git a/src/pages/components/CloudScriptPlan/index.tsx b/src/pages/components/CloudScriptPlan/index.tsx
index c74710b88..50fe8c930 100644
--- a/src/pages/components/CloudScriptPlan/index.tsx
+++ b/src/pages/components/CloudScriptPlan/index.tsx
@@ -57,6 +57,7 @@ const CloudScriptPlan: React.FC<{
         }
       });
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [script]);
   return (
     <Modal
diff --git a/src/pages/components/CustomLink/index.tsx b/src/pages/components/CustomLink/index.tsx
index f37e2d715..85b0af973 100644
--- a/src/pages/components/CustomLink/index.tsx
+++ b/src/pages/components/CustomLink/index.tsx
@@ -14,7 +14,8 @@ const CustomLink: React.FC<{
 
   const click = () => {
     if (window.onbeforeunload) {
-      if (confirm(t("confirm_leave_page"))) {
+      // 目前仅用于 ScriptEditor 编辑内容修改提示
+      if (confirm(t("script_modified_leave_confirm"))) {
         nav({
           pathname: to,
           search,
diff --git a/src/pages/components/PopupWarnings/index.tsx b/src/pages/components/PopupWarnings/index.tsx
index 066170d27..8ff441a57 100644
--- a/src/pages/components/PopupWarnings/index.tsx
+++ b/src/pages/components/PopupWarnings/index.tsx
@@ -1,7 +1,7 @@
 import { Alert, Button } from "@arco-design/web-react";
 import { useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { checkUserScriptsAvailable, getBrowserType, BrowserType } from "@App/pkg/utils/utils";
+import { checkUserScriptsAvailable, getBrowserType, BrowserType, isPermissionOk } from "@App/pkg/utils/utils";
 import edgeMobileQrCode from "@App/assets/images/edge_mobile_qrcode.png";
 
 interface PopupWarningsProps {
@@ -39,16 +39,28 @@ function PopupWarnings({ isBlacklist }: PopupWarningsProps) {
 
     const browser = browserType.chrome & BrowserType.Edge ? "edge" : "chrome";
 
-    const warningMessageHTML = browserType.firefox
-      ? t("develop_mode_guide", { browser: "firefox" })
-      : browserType.chrome
-        ? browserType.chrome & BrowserType.chromeA
+    let warningMessageHTML;
+
+    if (browserType.firefox) {
+      // firefox
+      warningMessageHTML = t("develop_mode_guide", { browser: "firefox" });
+    } else if (browserType.chrome) {
+      // chrome
+      warningMessageHTML =
+        browserType.chrome & BrowserType.noUserScriptsAPI
           ? t("lower_version_browser_guide")
-          : (browserType.chrome & BrowserType.chromeC && browserType.chrome & BrowserType.Chrome) ||
-              browserType.chrome & BrowserType.edgeA
-            ? t("allow_user_script_guide", { browser }) // Edge 144+ 后使用`允许用户脚本`控制
-            : t("develop_mode_guide", { browser }) // Edge浏览器目前没有允许用户脚本选项，开启开发者模式即可
-        : "UNKNOWN";
+          : // 120+
+            browserType.chrome & BrowserType.guardedByDeveloperMode
+            ? t("develop_mode_guide", { browser }) // Edge浏览器目前没有允许用户脚本选项，开启开发者模式即可
+            : // Edge 144+ / Chrome 138+
+              browserType.chrome & BrowserType.guardedByAllowScript
+              ? t("allow_user_script_guide", { browser }) // Edge 144+ 后使用`允许用户脚本`控制
+              : // 用于日后扩充更新版本
+                "UNKNOWN";
+    } else {
+      // other browsers
+      warningMessageHTML = "UNKNOWN";
+    }
 
     return warningMessageHTML;
   }, [isUserScriptsAvailableState, t]);
@@ -62,28 +74,14 @@ function PopupWarnings({ isBlacklist }: PopupWarningsProps) {
 
   // 权限要求详见：https://github.com/mdn/webextensions-examples/blob/main/userScripts-mv3/options.mjs
   useEffect(() => {
-    //@ts-ignore
-    if (chrome.permissions?.contains && chrome.permissions?.request) {
-      chrome.permissions.contains(
-        {
-          permissions: ["userScripts"],
-        },
-        function (permissionOK) {
-          const lastError = chrome.runtime.lastError;
-          if (lastError) {
-            console.error("chrome.runtime.lastError in chrome.permissions.contains:", lastError.message);
-            // runtime 错误的话不显示按钮
-            return;
-          }
-          if (permissionOK === false) {
-            // 假设browser能支持 `chrome.permissions.contains` 及在 callback返回一个false值的话，
-            // chrome.permissions.request 应该可以执行
-            // 因此在这裡显示按钮
-            setShowRequestButton(true);
-          }
-        }
-      );
-    }
+    isPermissionOk("userScripts").then((permissionOK) => {
+      if (permissionOK === false) {
+        // 假设browser能支持 `chrome.permissions.contains` 及在 callback返回一个false值的话，
+        // chrome.permissions.request 应该可以执行
+        // 因此在这里显示按钮
+        setShowRequestButton(true);
+      }
+    });
   }, []);
 
   const handleRequestPermission = () => {
@@ -103,8 +101,8 @@ function PopupWarnings({ isBlacklist }: PopupWarningsProps) {
       if (granted) {
         setPermissionReqResult("✅");
         // UserScripts API相关的初始化：
-        // userScripts.LISTEN_CONNECTIONS 進行 Server 通讯初始化
-        // onUserScriptAPIGrantAdded 進行 腳本注冊
+        // userScripts.LISTEN_CONNECTIONS 进行 Server 通讯初始化
+        // onUserScriptAPIGrantAdded 进行 脚本注册
         updateIsUserScriptsAvailableState();
       } else {
         setPermissionReqResult("❎");
diff --git a/src/pages/components/RuntimeSetting/index.tsx b/src/pages/components/RuntimeSetting/index.tsx
index 60e7d2c7a..472d513c8 100644
--- a/src/pages/components/RuntimeSetting/index.tsx
+++ b/src/pages/components/RuntimeSetting/index.tsx
@@ -5,6 +5,7 @@ import FileSystemParams from "../FileSystemParams";
 import { systemConfig } from "@App/pages/store/global";
 import type { FileSystemType } from "@Packages/filesystem/factory";
 import FileSystemFactory from "@Packages/filesystem/factory";
+import { isPermissionOk } from "@App/pkg/utils/utils";
 
 const CollapseItem = Collapse.Item;
 
@@ -24,11 +25,8 @@ const RuntimeSetting: React.FC = () => {
       setFilesystemType(res.filesystem);
       setFilesystemParam(res.params[res.filesystem] || {});
     });
-    chrome.permissions.contains({ permissions: ["background"] }, (result) => {
-      if (chrome.runtime.lastError) {
-        console.error(chrome.runtime.lastError);
-        return;
-      }
+    isPermissionOk("background").then((result) => {
+      if (result === null) return; // 无法要求 background permission
       setEnableBackgroundState(result);
     });
   }, []);
diff --git a/src/pages/components/ScriptSetting/Match.tsx b/src/pages/components/ScriptSetting/Match.tsx
index a8ff7fedc..fe4f5224c 100644
--- a/src/pages/components/ScriptSetting/Match.tsx
+++ b/src/pages/components/ScriptSetting/Match.tsx
@@ -87,6 +87,7 @@ const Match: React.FC<{
 
   useEffect(() => {
     refreshMatch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [script]);
 
   const columns: ColumnProps[] = [
diff --git a/src/pages/components/layout/MainLayout.tsx b/src/pages/components/layout/MainLayout.tsx
index e2c670fbc..4ac77fd45 100644
--- a/src/pages/components/layout/MainLayout.tsx
+++ b/src/pages/components/layout/MainLayout.tsx
@@ -27,13 +27,14 @@ import React, { useEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useAppContext } from "@App/pages/store/AppContext";
 import { RiFileCodeLine, RiImportLine, RiPlayListAddLine, RiTerminalBoxLine, RiTimerLine } from "react-icons/ri";
-import { scriptClient } from "@App/pages/store/features/script";
+import { scriptClient, agentClient } from "@App/pages/store/features/script";
 import { useDropzone, type FileWithPath } from "react-dropzone";
 import { systemConfig } from "@App/pages/store/global";
 import i18n, { matchLanguage } from "@App/locales/locales";
 import "./index.css";
 import { arcoLocale } from "@App/locales/arco";
-import { prepareScriptByCode } from "@App/pkg/utils/script";
+import { prepareScriptByCode, parseMetadata } from "@App/pkg/utils/script";
+import { parseCATToolMetadata } from "@App/pkg/utils/cattool";
 import { saveHandle } from "@App/pkg/utils/filehandle-db";
 import { makeBlobURL } from "@App/pkg/utils/utils";
 
@@ -188,6 +189,20 @@ const MainLayout: React.FC<{
     if (stat) showImportResult(stat);
   };
 
+  // 处理 ZIP 文件的 Skill 安装
+  const handleZipSkillInstall = async (file: File) => {
+    const buffer = await file.arrayBuffer();
+    // ArrayBuffer → base64（chrome.runtime 消息不支持直接传 ArrayBuffer）
+    const bytes = new Uint8Array(buffer);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    const base64 = btoa(binary);
+    const uuid = await agentClient.prepareSkillInstall(base64);
+    window.open(`/src/install.html?skill=${uuid}`, "_blank");
+  };
+
   const onDrop = (acceptedFiles: FileWithPath[]) => {
     // 本地的文件在当前页面处理，打开安装页面，将FileSystemFileHandle传递过去
     // 实现本地文件的监听
@@ -195,6 +210,12 @@ const MainLayout: React.FC<{
     Promise.all(
       acceptedFiles.map(async (aFile) => {
         try {
+          // ZIP 文件走 Skill 安装流程
+          if (aFile.name.endsWith(".zip")) {
+            await handleZipSkillInstall(aFile);
+            stat.success++;
+            return;
+          }
           // 解析看看是不是一个标准的script文件
           // 如果是，则打开安装页面
           let fileHandle = aFile.handle;
@@ -223,9 +244,17 @@ const MainLayout: React.FC<{
           if (!file.name || !file.size) {
             throw new Error("No Read Access Right for File");
           }
-          // 先检查内容，后弹出安装页面
+          // 先检查内容，后弹出安装页面（支持 UserScript 和 CATTool）
           const checkOk = await Promise.allSettled([
-            file.text().then((code) => prepareScriptByCode(code, `file:///*resp-check*/${file.name}`)),
+            file.text().then((code) => {
+              // 先尝试 UserScript 解析
+              const metadata = parseMetadata(code);
+              if (metadata) return prepareScriptByCode(code, `file:///*resp-check*/${file.name}`);
+              // 再尝试 CATTool 解析
+              const cattoolMeta = parseCATToolMetadata(code);
+              if (cattoolMeta) return { script: {} as any };
+              throw new Error("not a valid UserScript or CATTool");
+            }),
             simpleDigestMessage(`f=${file.name}\ns=${file.size},m=${file.lastModified}`),
           ]);
           if (checkOk[0].status === "rejected" || !checkOk[0].value || checkOk[1].status === "rejected") {
@@ -250,7 +279,7 @@ const MainLayout: React.FC<{
   };
 
   const { getRootProps, getInputProps, isDragActive } = useDropzone({
-    accept: { "text/javascript": [".js"] },
+    accept: { "text/javascript": [".js"], "application/zip": [".zip"] },
     onDrop,
     noClick: true,
     noKeyboard: true,
@@ -310,7 +339,7 @@ const MainLayout: React.FC<{
       }}
     >
       {contextHolder}
-      <Layout className={"tw-min-h-screen"}>
+      <Layout className={"tw-h-screen tw-overflow-hidden"}>
         <Layout.Header
           style={{
             height: "50px",
@@ -491,7 +520,7 @@ const MainLayout: React.FC<{
           </Space>
         </Layout.Header>
         <Layout
-          className={`tw-bottom-0 tw-w-full ${className}`}
+          className={`tw-bottom-0 tw-w-full tw-flex-1 tw-overflow-hidden ${className}`}
           style={{ background: "var(--color-fill-2)" }}
           {...getRootProps({})}
         >
diff --git a/src/pages/components/layout/Sider.tsx b/src/pages/components/layout/Sider.tsx
index 37fd399ec..0ce5fb638 100644
--- a/src/pages/components/layout/Sider.tsx
+++ b/src/pages/components/layout/Sider.tsx
@@ -1,3 +1,4 @@
+import Agent from "@App/pages/options/routes/Agent";
 import Logger from "@App/pages/options/routes/Logger";
 import ScriptEditor from "@App/pages/options/routes/script/ScriptEditor";
 import ScriptList from "@App/pages/options/routes/ScriptList";
@@ -13,6 +14,7 @@ import {
   IconLink,
   IconQuestion,
   IconRight,
+  IconRobot,
   IconSettings,
   IconSubscribe,
   IconTool,
@@ -37,6 +39,7 @@ if (!hash.length) {
 const Sider: React.FC = () => {
   const [menuSelect, setMenuSelect] = useState(hash);
   const [collapsed, setCollapsed] = useState(localStorage.collapsed === "true");
+  const [openKeys, setOpenKeys] = useState<string[]>(hash.startsWith("/agent") ? ["/agent"] : []);
   const { t } = useTranslation();
   const guideRef = useRef<{ open: () => void }>(null);
 
@@ -51,7 +54,14 @@ const Sider: React.FC = () => {
       <SiderGuide ref={guideRef} />
       <Layout.Sider collapsed={collapsed} width={170}>
         <div className="tw-flex tw-flex-col tw-justify-between tw-h-full">
-          <Menu style={{ width: "100%" }} selectedKeys={[menuSelect]} selectable onClickMenuItem={handleMenuClick}>
+          <Menu
+            style={{ width: "100%" }}
+            selectedKeys={[menuSelect]}
+            openKeys={openKeys}
+            onClickSubMenu={(_, openKeys) => setOpenKeys(openKeys)}
+            selectable
+            onClickMenuItem={handleMenuClick}
+          >
             <CustomLink to="/">
               <MenuItem key="/" className="menu-script">
                 <IconCode /> {t("installed_scripts")}
@@ -62,6 +72,43 @@ const Sider: React.FC = () => {
                 <IconSubscribe /> {t("subscribe")}
               </MenuItem>
             </CustomLink>
+            <Menu.SubMenu
+              key="/agent"
+              title={
+                <span
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    setMenuSelect("/agent/chat");
+                    setOpenKeys((prev) => (prev.includes("/agent") ? prev : [...prev, "/agent"]));
+                    window.location.hash = "/agent/chat";
+                  }}
+                >
+                  <IconRobot /> {t("agent")}
+                </span>
+              }
+            >
+              <CustomLink to="/agent/chat">
+                <MenuItem key="/agent/chat">{t("agent_chat")}</MenuItem>
+              </CustomLink>
+              <CustomLink to="/agent/provider">
+                <MenuItem key="/agent/provider">{t("agent_provider")}</MenuItem>
+              </CustomLink>
+              <CustomLink to="/agent/catool">
+                <MenuItem key="/agent/catool">{t("agent_catool")}</MenuItem>
+              </CustomLink>
+              <CustomLink to="/agent/skills">
+                <MenuItem key="/agent/skills">{t("agent_skills")}</MenuItem>
+              </CustomLink>
+              <CustomLink to="/agent/mcp">
+                <MenuItem key="/agent/mcp">{t("agent_mcp")}</MenuItem>
+              </CustomLink>
+              <CustomLink to="/agent/tasks">
+                <MenuItem key="/agent/tasks">{t("agent_tasks")}</MenuItem>
+              </CustomLink>
+              <CustomLink to="/agent/opfs">
+                <MenuItem key="/agent/opfs">{t("agent_opfs")}</MenuItem>
+              </CustomLink>
+            </Menu.SubMenu>
             <CustomLink to="/logger">
               <MenuItem key="/logger">
                 <IconFile /> {t("logs")}
@@ -171,7 +218,7 @@ const Sider: React.FC = () => {
           borderLeft: "1px solid var(--color-bg-5)",
           overflow: "hidden",
           padding: 0,
-          height: "auto",
+          height: "100%",
           boxSizing: "border-box",
           position: "relative",
         }}
@@ -186,6 +233,7 @@ const Sider: React.FC = () => {
             <Route path="/subscribe" element={<SubscribeList />} />
             <Route path="/logger" element={<Logger />} />
             <Route path="/tools" element={<Tools />} />
+            <Route path="/agent/*" element={<Agent />} />
             <Route path="/setting" element={<Setting />} />
           </Routes>
         </div>
diff --git a/src/pages/components/layout/index.css b/src/pages/components/layout/index.css
index fd53b2633..75764a6af 100644
--- a/src/pages/components/layout/index.css
+++ b/src/pages/components/layout/index.css
@@ -1,26 +1,26 @@
 .arco-dropdown-menu-selected {
-    background-color: var(--color-fill-2) !important;
+  background-color: var(--color-fill-2) !important;
 }
 
 .action-tools .arco-dropdown-popup-visible .arco-icon-down {
-    transform: rotate(180deg);
+  transform: rotate(180deg);
 }
 
-.action-tools>.arco-btn {
-    padding: 0 8px;
+.action-tools > .arco-btn {
+  padding: 0 8px;
 }
 
 .arco-dropdown-menu-item,
 .arco-dropdown-menu-item a {
-    display: flex;
-    align-items: center;
+  display: flex;
+  align-items: center;
 }
 
 :is(.arco-dropdown-menu-pop-header, .arco-dropdown-menu-item, .arco-dropdown-menu-item a) > svg {
-    margin-right: .5em;
+  margin-right: 0.5em;
 }
 
 /* 避免拖拽时 tooltip 等元件弹出 */
 .dragzone-active .arco-layout-content {
-    pointer-events: none;
+  pointer-events: none;
 }
diff --git a/src/pages/confirm/App.tsx b/src/pages/confirm/App.tsx
index b440a33ad..7e7f32e9d 100644
--- a/src/pages/confirm/App.tsx
+++ b/src/pages/confirm/App.tsx
@@ -4,24 +4,29 @@ import React, { useEffect, useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { permissionClient } from "../store/features/script";
 
-function App() {
-  const uuid = new URLSearchParams(location.search).get("uuid");
+// 权限确认组件
+function PermissionConfirmRequest({ uuid }: { uuid: string }) {
   const [confirm, setConfirm] = React.useState<ConfirmParam>();
   const [likeNum, setLikeNum] = React.useState(0);
   const [second, setSecond] = React.useState(30);
 
   const { t } = useTranslation();
 
-  if (second === 0) {
-    window.close();
-  }
-
-  setTimeout(() => {
-    setSecond(second - 1);
-  }, 1000);
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setSecond((s) => {
+        if (s <= 1) {
+          clearInterval(timer);
+          window.close();
+          return 0;
+        }
+        return s - 1;
+      });
+    }, 1000);
+    return () => clearInterval(timer);
+  }, []);
 
   useEffect(() => {
-    if (!uuid) return;
     window.addEventListener("beforeunload", () => {
       permissionClient.confirm(uuid, {
         allow: false,
@@ -39,11 +44,10 @@ function App() {
       .catch((e: any) => {
         Message.error(e.message || t("get_confirm_error"));
       });
-  }, []);
+  }, [uuid, t]);
 
   const handleConfirm = (allow: boolean, type: number) => {
     return async () => {
-      if (!uuid) return;
       try {
         await permissionClient.confirm(uuid, {
           allow,
@@ -143,4 +147,15 @@ function App() {
   );
 }
 
+function App() {
+  const params = new URLSearchParams(location.search);
+  const uuid = params.get("uuid");
+
+  if (uuid) {
+    return <PermissionConfirmRequest uuid={uuid} />;
+  }
+
+  return null;
+}
+
 export default App;
diff --git a/src/pages/install/App.tsx b/src/pages/install/App.tsx
index 6bbb48d51..a4ae92578 100644
--- a/src/pages/install/App.tsx
+++ b/src/pages/install/App.tsx
@@ -1,751 +1,64 @@
-import {
-  Button,
-  Dropdown,
-  Message,
-  Menu,
-  Modal,
-  Space,
-  Switch,
-  Tag,
-  Tooltip,
-  Typography,
-  Popover,
-} from "@arco-design/web-react";
-import { IconDown } from "@arco-design/web-react/icon";
-import { uuidv4 } from "@App/pkg/utils/uuid";
-import CodeEditor from "../components/CodeEditor";
-import { useEffect, useMemo, useState } from "react";
-import type { SCMetadata, Script } from "@App/app/repo/scripts";
-import { SCRIPT_STATUS_DISABLE, SCRIPT_STATUS_ENABLE } from "@App/app/repo/scripts";
-import type { Subscribe } from "@App/app/repo/subscribe";
-import { i18nDescription, i18nName } from "@App/locales/locales";
+import { Space, Typography } from "@arco-design/web-react";
 import { useTranslation } from "react-i18next";
-import { createScriptInfo, type ScriptInfo } from "@App/pkg/utils/scriptInstall";
-import { parseMetadata, prepareScriptByCode, prepareSubscribeByCode } from "@App/pkg/utils/script";
-import { nextTimeDisplay } from "@App/pkg/utils/cron";
-import { scriptClient, subscribeClient } from "../store/features/script";
-import { type FTInfo, startFileTrack, unmountFileTrack } from "@App/pkg/utils/file-tracker";
-import { cleanupOldHandles, loadHandle, saveHandle } from "@App/pkg/utils/filehandle-db";
-import { dayFormat } from "@App/pkg/utils/day_format";
-import { intervalExecution, timeoutExecution } from "@App/pkg/utils/timer";
-import { useSearchParams } from "react-router-dom";
-import { CACHE_KEY_SCRIPT_INFO } from "@App/app/cache_key";
-import { cacheInstance } from "@App/app/cache";
-import { formatBytes } from "@App/pkg/utils/utils";
-import { ScriptIcons } from "../options/routes/utils";
-import { bytesDecode, detectEncoding } from "@App/pkg/utils/encoding";
-import { prettyUrl } from "@App/pkg/utils/url-utils";
-
-const backgroundPromptShownKey = "background_prompt_shown";
-
-type ScriptOrSubscribe = Script | Subscribe;
-
-// Types
-interface PermissionItem {
-  label: string;
-  color?: string;
-  value: string[];
-}
-
-type Permission = PermissionItem[];
-
-const closeWindow = (doBackwards: boolean) => {
-  if (doBackwards) {
-    history.go(-1);
-  } else {
-    window.close();
-  }
-};
-
-const fetchScriptBody = async (url: string, { onProgress }: { [key: string]: any }) => {
-  let origin;
-  try {
-    origin = new URL(url).origin;
-  } catch {
-    throw new Error(`Invalid url: ${url}`);
-  }
-  const response = await fetch(url, {
-    headers: {
-      "Cache-Control": "no-cache",
-      Accept: "text/javascript,application/javascript,text/plain,application/octet-stream,application/force-download",
-      // 参考：加权 Accept-Encoding 值说明
-      // https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Encoding#weighted_accept-encoding_values
-      "Accept-Encoding": "br;q=1.0, gzip;q=0.8, *;q=0.1",
-      Origin: origin,
-    },
-    referrer: origin + "/",
-  });
-
-  if (!response.ok) {
-    throw new Error(`Fetch failed with status ${response.status}`);
-  }
-
-  if (!response.body || !response.headers) {
-    throw new Error("No response body or headers");
-  }
-  if (response.headers.get("content-type")?.includes("text/html")) {
-    throw new Error("Response is text/html, not a valid UserScript");
-  }
-
-  const reader = response.body.getReader();
-
-  // 读取数据
-  let receivedLength = 0; // 当前已接收的长度
-  const chunks = []; // 已接收的二进制分片数组（用于组装正文）
-  while (true) {
-    const { done, value } = await reader.read();
-
-    if (done) {
-      break;
-    }
-
-    chunks.push(value);
-    receivedLength += value.length;
-    onProgress?.({ receivedLength });
-  }
-
-  // 合并分片（chunks）
-  const chunksAll = new Uint8Array(receivedLength);
-  let position = 0;
-  for (const chunk of chunks) {
-    chunksAll.set(chunk, position);
-    position += chunk.length;
-  }
-
-  // 检测编码：优先使用 Content-Type，回退到 chardet（仅检测前16KB）
-  const contentType = response.headers.get("content-type");
-  const encode = detectEncoding(chunksAll, contentType);
-
-  // 使用检测到的 charset 解码
-  let code;
-  try {
-    code = bytesDecode(encode, chunksAll);
-  } catch (e: any) {
-    console.warn(`Failed to decode response with charset ${encode}: ${e.message}`);
-    // 回退到 UTF-8
-    code = new TextDecoder("utf-8").decode(chunksAll);
-  }
-
-  const metadata = parseMetadata(code);
-  if (!metadata) {
-    throw new Error("parse script info failed");
-  }
-
-  return { code, metadata };
-};
-
-const cleanupStaleInstallInfo = (uuid: string) => {
-  // 页面打开时不清除当前uuid，每30秒更新一次记录
-  const f = () => {
-    cacheInstance.tx(`scriptInfoKeeps`, (val: Record<string, number> | undefined, tx) => {
-      val = val || {};
-      val[uuid] = Date.now();
-      tx.set(val);
-    });
-  };
-  f();
-  setInterval(f, 30_000);
-
-  // 页面打开后清除旧记录
-  const delay = Math.floor(5000 * Math.random()) + 10000; // 使用随机时间避免浏览器重启时大量Tabs同时执行清除
-  timeoutExecution(
-    `${cIdKey}cleanupStaleInstallInfo`,
-    () => {
-      cacheInstance
-        .tx(`scriptInfoKeeps`, (val: Record<string, number> | undefined, tx) => {
-          const now = Date.now();
-          const keeps = new Set<string>();
-          const out: Record<string, number> = {};
-          for (const [k, ts] of Object.entries(val ?? {})) {
-            if (ts > 0 && now - ts < 60_000) {
-              keeps.add(`${CACHE_KEY_SCRIPT_INFO}${k}`);
-              out[k] = ts;
-            }
-          }
-          tx.set(out);
-          return keeps;
-        })
-        .then(async (keeps) => {
-          const list = await cacheInstance.list();
-          const filtered = list.filter((key) => key.startsWith(CACHE_KEY_SCRIPT_INFO) && !keeps.has(key));
-          if (filtered.length) {
-            // 清理缓存
-            cacheInstance.dels(filtered);
-          }
-        });
-    },
-    delay
-  );
-};
-
-const cIdKey = `(cid_${Math.random()})`;
+import { useInstallData } from "./hooks";
+import CATToolInstallView from "./components/CATToolInstallView";
+import SkillInstallView from "./components/SkillInstallView";
+import ScriptInstallView from "./components/ScriptInstallView";
 
 function App() {
-  const [enable, setEnable] = useState<boolean>(false);
-  const [btnText, setBtnText] = useState<string>("");
-  const [scriptCode, setScriptCode] = useState<string>("");
-  const [scriptInfo, setScriptInfo] = useState<ScriptInfo>();
-  const [upsertScript, setUpsertScript] = useState<ScriptOrSubscribe | undefined>(undefined);
-  const [diffCode, setDiffCode] = useState<string>();
-  const [oldScriptVersion, setOldScriptVersion] = useState<string | null>(null);
-  const [isUpdate, setIsUpdate] = useState<boolean>(false);
-  const [localFileHandle, setLocalFileHandle] = useState<FileSystemFileHandle | null>(null);
-  const [showBackgroundPrompt, setShowBackgroundPrompt] = useState<boolean>(false);
+  const data = useInstallData();
   const { t } = useTranslation();
-  const [searchParams, setSearchParams] = useSearchParams();
-  const [loaded, setLoaded] = useState<boolean>(false);
-  const [doBackwards, setDoBackwards] = useState<boolean>(false);
-
-  const installOrUpdateScript = async (newScript: Script, code: string) => {
-    if (newScript.ignoreVersion) newScript.ignoreVersion = "";
-    await scriptClient.install({ script: newScript, code });
-    const metadata = newScript.metadata;
-    setScriptInfo((prev) => (prev ? { ...prev, code, metadata } : prev));
-    const scriptVersion = metadata.version?.[0];
-    const oldScriptVersion = typeof scriptVersion === "string" ? scriptVersion : "N/A";
-    setOldScriptVersion(oldScriptVersion);
-    setUpsertScript(newScript);
-    setDiffCode(code);
-  };
-
-  const getUpdatedNewScript = async (uuid: string, code: string) => {
-    const oldScript = await scriptClient.info(uuid);
-    if (!oldScript || oldScript.uuid !== uuid) {
-      throw new Error("uuid is mismatched");
-    }
-    const { script } = await prepareScriptByCode(code, oldScript.origin || "", uuid);
-    script.origin = oldScript.origin || script.origin || "";
-    if (!script.name) {
-      throw new Error(t("script_name_cannot_be_set_to_empty"));
-    }
-    return script;
-  };
-
-  const initAsync = async () => {
-    try {
-      const uuid = searchParams.get("uuid");
-      const fid = searchParams.get("file");
-
-      // 如果有 url 或 没有 uuid 和 file，跳过初始化逻辑
-      if (searchParams.get("url") || (!uuid && !fid)) {
-        return;
-      }
-      let info: ScriptInfo | undefined;
-      let isKnownUpdate: boolean = false;
-
-      if (window.history.length > 1) {
-        setDoBackwards(true);
-      }
-      setLoaded(true);
-
-      let paramOptions = {};
-      if (uuid) {
-        const cachedInfo = await scriptClient.getInstallInfo(uuid);
-        cleanupStaleInstallInfo(uuid);
-        if (cachedInfo?.[0]) isKnownUpdate = true;
-        info = cachedInfo?.[1] || undefined;
-        paramOptions = cachedInfo?.[2] || {};
-        if (!info) {
-          throw new Error("fetch script info failed");
-        }
-      } else {
-        // 检查是不是本地文件安装
-        if (!fid) {
-          throw new Error("url param - local file id is not found");
-        }
-        const fileHandle = await loadHandle(fid);
-        if (!fileHandle) {
-          throw new Error("invalid file access - fileHandle is null");
-        }
-        const file = await fileHandle.getFile();
-        if (!file) {
-          throw new Error("invalid file access - file is null");
-        }
-        // 处理本地文件的安装流程
-        // 处理成info对象
-        setLocalFileHandle((prev) => {
-          if (prev instanceof FileSystemFileHandle) unmountFileTrack(prev);
-          return fileHandle!;
-        });
-
-        // 刷新 timestamp, 使 10s~15s 后不会被立即清掉
-        // 每五分钟刷新一次db记录的timestamp，使开启中的安装页面的fileHandle不会被刷掉
-        intervalExecution(`${cIdKey}liveFileHandle`, () => saveHandle(fid, fileHandle), 5 * 60 * 1000, true);
-
-        const code = await file.text();
-        const metadata = parseMetadata(code);
-        if (!metadata) {
-          throw new Error("parse script info failed");
-        }
-        info = createScriptInfo(uuidv4(), code, `file:///*from-local*/${file.name}`, "user", metadata);
-      }
-
-      let prepare:
-        | { script: Script; oldScript?: Script; oldScriptCode?: string }
-        | { subscribe: Subscribe; oldSubscribe?: Subscribe };
-      let action: Script | Subscribe;
-
-      const { code, url } = info;
-      let oldVersion: string | undefined = undefined;
-      let diffCode: string | undefined = undefined;
-      if (info.userSubscribe) {
-        prepare = await prepareSubscribeByCode(code, url);
-        action = prepare.subscribe;
-        if (prepare.oldSubscribe) {
-          const oldSubscribeVersion = prepare.oldSubscribe.metadata.version?.[0];
-          oldVersion = typeof oldSubscribeVersion === "string" ? oldSubscribeVersion : "N/A";
-        }
-        diffCode = prepare.oldSubscribe?.code;
-      } else {
-        const knownUUID = isKnownUpdate ? info.uuid : undefined;
-        prepare = await prepareScriptByCode(code, url, knownUUID, false, undefined, paramOptions);
-        action = prepare.script;
-        if (prepare.oldScript) {
-          const oldScriptVersion = prepare.oldScript.metadata.version?.[0];
-          oldVersion = typeof oldScriptVersion === "string" ? oldScriptVersion : "N/A";
-        }
-        diffCode = prepare.oldScriptCode;
-      }
-      setScriptCode(code);
-      setDiffCode(diffCode);
-      setOldScriptVersion(typeof oldVersion === "string" ? oldVersion : null);
-      setIsUpdate(typeof oldVersion === "string");
-      setScriptInfo(info);
-      setUpsertScript(action);
-
-      // 检查是否需要显示后台运行提示
-      if (!info.userSubscribe) {
-        setShowBackgroundPrompt(await checkBackgroundPrompt(action as Script));
-      }
-    } catch (e: any) {
-      Message.error(t("script_info_load_failed") + " " + e.message);
-    } finally {
-      // fileHandle 保留处理方式（暂定）：
-      // fileHandle 会保留一段足够时间，避免用户重新刷画面，重启浏览器等操作后，安装页变得空白一片。
-      // 处理会在所有Tab都载入后（不包含睡眠Tab）进行，因此延迟 10s~15s 让处理有足够时间。
-      // 安装页面关掉后15分钟为不保留状态，会在安装画面再次打开时（其他脚本安装），进行清除。
-      const delay = Math.floor(5000 * Math.random()) + 10000; // 使用乱数时间避免浏览器重启时大量Tabs同时执行DB清除
-      timeoutExecution(`${cIdKey}cleanupFileHandle`, cleanupOldHandles, delay);
-    }
-  };
-
-  useEffect(() => {
-    !loaded && initAsync();
-  }, [searchParams, loaded]);
-
-  const [watchFile, setWatchFile] = useState(false);
-  const metadataLive = useMemo(() => (scriptInfo?.metadata || {}) as SCMetadata, [scriptInfo]);
-
-  const permissions = useMemo(() => {
-    const permissions: Permission = [];
-
-    if (!scriptInfo) return permissions;
-
-    if (scriptInfo.userSubscribe) {
-      permissions.push({
-        label: t("subscribe_install_label"),
-        color: "#ff0000",
-        value: metadataLive.scripturl!,
-      });
-    }
 
-    if (metadataLive.match) {
-      permissions.push({ label: t("script_runs_in"), value: metadataLive.match });
-    }
-
-    if (metadataLive.connect) {
-      permissions.push({
-        label: t("script_has_full_access_to"),
-        color: "#F9925A",
-        value: metadataLive.connect,
-      });
-    }
-
-    if (metadataLive.require) {
-      permissions.push({ label: t("script_requires"), value: metadataLive.require });
-    }
-
-    return permissions;
-  }, [scriptInfo, metadataLive, t]);
-
-  const descriptionParagraph = useMemo(() => {
-    const ret: JSX.Element[] = [];
-
-    if (!scriptInfo) return ret;
-
-    const isCookie = metadataLive.grant?.some((val) => val === "GM_cookie");
-    if (isCookie) {
-      ret.push(
-        <Typography.Text type="error" key="cookie">
-          {t("cookie_warning")}
-        </Typography.Text>
-      );
-    }
-
-    if (metadataLive.crontab) {
-      ret.push(<Typography.Text key="crontab">{t("scheduled_script_description_title")}</Typography.Text>);
-      ret.push(
-        <div key="cronta-nexttime" className="tw-flex tw-flex-row tw-flex-wrap tw-gap-x-2">
-          <Typography.Text>{t("scheduled_script_description_description_expr")}</Typography.Text>
-          <Typography.Text code>{metadataLive.crontab[0]}</Typography.Text>
-          <Typography.Text>{t("scheduled_script_description_description_next")}</Typography.Text>
-          <Typography.Text code>{nextTimeDisplay(metadataLive.crontab[0])}</Typography.Text>
-        </div>
-      );
-    } else if (metadataLive.background) {
-      ret.push(<Typography.Text key="background">{t("background_script_description")}</Typography.Text>);
-    }
-
-    return ret;
-  }, [scriptInfo, metadataLive, t]);
-
-  const antifeatures: { [key: string]: { color: string; title: string; description: string } } = {
-    "referral-link": {
-      color: "purple",
-      title: t("antifeature_referral_link_title"),
-      description: t("antifeature_referral_link_description"),
-    },
-    ads: {
-      color: "orange",
-      title: t("antifeature_ads_title"),
-      description: t("antifeature_ads_description"),
-    },
-    payment: {
-      color: "magenta",
-      title: t("antifeature_payment_title"),
-      description: t("antifeature_payment_description"),
-    },
-    miner: {
-      color: "orangered",
-      title: t("antifeature_miner_title"),
-      description: t("antifeature_miner_description"),
-    },
-    membership: {
-      color: "blue",
-      title: t("antifeature_membership_title"),
-      description: t("antifeature_membership_description"),
-    },
-    tracking: {
-      color: "pinkpurple",
-      title: t("antifeature_tracking_title"),
-      description: t("antifeature_tracking_description"),
-    },
-  };
-
-  // 更新按钮文案和页面标题
-  useEffect(() => {
-    if (scriptInfo?.userSubscribe) {
-      setBtnText(isUpdate ? t("update_subscribe")! : t("install_subscribe"));
-    } else {
-      setBtnText(isUpdate ? t("update_script")! : t("install_script"));
-    }
-    if (upsertScript) {
-      document.title = `${!isUpdate ? t("install_script") : t("update_script")} - ${i18nName(upsertScript!)} - ScriptCat`;
-    }
-  }, [isUpdate, scriptInfo, upsertScript, t]);
-
-  // 设置脚本状态
-  useEffect(() => {
-    if (upsertScript) {
-      setEnable(upsertScript.status === SCRIPT_STATUS_ENABLE);
-    }
-  }, [upsertScript]);
-
-  // 检查是否需要显示后台运行提示
-  const checkBackgroundPrompt = async (script: Script) => {
-    // 只有后台脚本或定时脚本才提示
-    if (!script.metadata.background && !script.metadata.crontab) {
-      return false;
-    }
-
-    // 检查是否首次安装或更新
-    const hasShown = localStorage.getItem(backgroundPromptShownKey);
-
-    if (hasShown !== "true") {
-      // 检查是否已经有后台权限
-      if (!(await chrome.permissions.contains({ permissions: ["background"] }))) {
-        return true;
-      }
-    }
-    return false;
-  };
-
-  const handleInstall = async (options: { closeAfterInstall?: boolean; noMoreUpdates?: boolean } = {}) => {
-    if (!upsertScript) {
-      Message.error(t("script_info_load_failed")!);
-      return;
-    }
-
-    const { closeAfterInstall: shouldClose = true, noMoreUpdates: disableUpdates = false } = options;
-
-    try {
-      if (scriptInfo?.userSubscribe) {
-        await subscribeClient.install(upsertScript as Subscribe);
-        Message.success(t("subscribe_success")!);
-        setBtnText(t("subscribe_success")!);
-      } else {
-        // 如果选择不再检查更新，可以在这里设置脚本的更新配置
-        if (disableUpdates && upsertScript) {
-          // 这里可以设置脚本禁用自动更新的逻辑
-          (upsertScript as Script).checkUpdate = false;
-        }
-        // 故意只安装或执行，不改变显示内容
-        await scriptClient.install({ script: upsertScript as Script, code: scriptCode });
-        if (isUpdate) {
-          Message.success(t("install.update_success")!);
-          setBtnText(t("install.update_success")!);
-        } else {
-          // 如果选择不再检查更新，可以在这里设置脚本的更新配置
-          if (disableUpdates && upsertScript) {
-            // 这里可以设置脚本禁用自动更新的逻辑
-            (upsertScript as Script).checkUpdate = false;
-          }
-          if ((upsertScript as Script).ignoreVersion) (upsertScript as Script).ignoreVersion = "";
-          // 故意只安装或执行，不改变显示内容
-          await scriptClient.install({ script: upsertScript as Script, code: scriptCode });
-          if (isUpdate) {
-            Message.success(t("install.update_success")!);
-            setBtnText(t("install.update_success")!);
-          } else {
-            Message.success(t("install_success")!);
-            setBtnText(t("install_success")!);
-          }
-        }
-      }
-
-      if (shouldClose) {
-        setTimeout(() => {
-          closeWindow(doBackwards);
-        }, 500);
-      }
-    } catch (e) {
-      const errorMessage = scriptInfo?.userSubscribe ? t("subscribe_failed") : t("install_failed");
-      Message.error(`${errorMessage}: ${e}`);
-    }
-  };
-
-  const handleClose = (options?: { noMoreUpdates: boolean }) => {
-    const { noMoreUpdates = false } = options || {};
-    if (noMoreUpdates && scriptInfo && !scriptInfo.userSubscribe) {
-      scriptClient.setCheckUpdateUrl(scriptInfo.uuid, false);
-    }
-    closeWindow(doBackwards);
-  };
-
-  const {
-    handleInstallBasic,
-    handleInstallCloseAfterInstall,
-    handleInstallNoMoreUpdates,
-    handleStatusChange,
-    handleCloseBasic,
-    handleCloseNoMoreUpdates,
-    setWatchFileClick,
-  } = {
-    handleInstallBasic: () => handleInstall(),
-    handleInstallCloseAfterInstall: () => handleInstall({ closeAfterInstall: false }),
-    handleInstallNoMoreUpdates: () => handleInstall({ noMoreUpdates: true }),
-    handleStatusChange: (checked: boolean) => {
-      setUpsertScript((script) => {
-        if (!script) {
-          return script;
-        }
-        script.status = checked ? SCRIPT_STATUS_ENABLE : SCRIPT_STATUS_DISABLE;
-        setEnable(checked);
-        return script;
-      });
-    },
-    handleCloseBasic: () => handleClose(),
-    handleCloseNoMoreUpdates: () => handleClose({ noMoreUpdates: true }),
-    setWatchFileClick: () => {
-      setWatchFile((prev) => !prev);
-    },
-  };
-
-  const fileWatchMessageId = `id_${Math.random()}`;
-
-  async function onWatchFileCodeChanged(this: FTInfo, code: string, hideInfo: boolean = false) {
-    if (this.uuid !== scriptInfo?.uuid) return;
-    if (this.fileName !== localFileHandle?.name) return;
-    setScriptCode(code);
-    const uuid = (upsertScript as Script)?.uuid;
-    if (!uuid) {
-      throw new Error("uuid is undefined");
-    }
-    try {
-      const newScript = await getUpdatedNewScript(uuid, code);
-      await installOrUpdateScript(newScript, code);
-    } catch (e) {
-      Message.error({
-        id: fileWatchMessageId,
-        content: t("install_failed") + ": " + e,
-      });
-      return;
-    }
-    if (!hideInfo) {
-      Message.info({
-        id: fileWatchMessageId,
-        content: `${t("last_updated")}: ${dayFormat()}`,
-        duration: 3000,
-        closable: true,
-        showIcon: true,
-      });
-    }
+  // Skill ZIP 安装
+  if (data.skillPreview) {
+    return (
+      <SkillInstallView
+        metadata={data.skillPreview.metadata}
+        prompt={data.skillPreview.prompt}
+        scripts={data.skillPreview.scripts}
+        references={data.skillPreview.references}
+        isUpdate={data.skillPreview.isUpdate}
+        onInstall={data.handleSkillInstall}
+        onClose={data.handleSkillCancel}
+      />
+    );
   }
 
-  async function onWatchFileError() {
-    // e.g. NotFoundError
-    setWatchFile(false);
+  // CATTool 安装
+  if (data.cattoolMetadata && data.scriptInfo?.cattool) {
+    // 通过 GM API 安装（有 cattoolInstallUuid）使用 API 回调，否则用普通安装
+    const onInstall = data.cattoolInstallUuid ? data.handleCATToolApiInstall : data.handleCATToolInstall;
+    const onClose = data.cattoolInstallUuid ? data.handleCATToolApiCancel : data.handleCloseBasic;
+    return (
+      <CATToolInstallView
+        metadata={data.cattoolMetadata}
+        scriptCode={data.scriptCode}
+        onInstall={onInstall}
+        onClose={onClose}
+        sourceScriptName={data.cattoolSourceScriptName}
+        isUpdate={data.cattoolIsUpdate}
+      />
+    );
   }
 
-  const memoWatchFile = useMemo(() => {
-    return `${watchFile}.${scriptInfo?.uuid}.${localFileHandle?.name}`;
-  }, [watchFile, scriptInfo, localFileHandle]);
-
-  const setupWatchFile = async (uuid: string, fileName: string, handle: FileSystemFileHandle) => {
-    try {
-      // 如没有安装纪录，将进行安装。
-      // 如已经安装，在FileSystemObserver检查更改前，先进行更新。
-      const code = `${scriptCode}`;
-      await installOrUpdateScript(upsertScript as Script, code);
-      // setScriptCode(`${code}`);
-      setDiffCode(`${code}`);
-      const ftInfo: FTInfo = {
-        uuid,
-        fileName,
-        setCode: onWatchFileCodeChanged,
-        onFileError: onWatchFileError,
-      };
-      // 进行监听
-      startFileTrack(handle, ftInfo);
-      // 先取最新代码
-      const file = await handle.getFile();
-      const currentCode = await file.text();
-      // 如不一致，先更新
-      if (currentCode !== code) {
-        ftInfo.setCode(currentCode, true);
-      }
-    } catch (e: any) {
-      Message.error(`${e.message}`);
-      console.warn(e);
-    }
-  };
-
-  useEffect(() => {
-    if (!watchFile || !localFileHandle) {
-      return;
-    }
-    // 去除React特性
-    const [handle] = [localFileHandle];
-    unmountFileTrack(handle); // 避免重复追踪
-    const uuid = scriptInfo?.uuid;
-    const fileName = handle?.name;
-    if (!uuid || !fileName) {
-      return;
-    }
-    setupWatchFile(uuid, fileName, handle);
-    return () => {
-      unmountFileTrack(handle);
-    };
-  }, [memoWatchFile]);
-
-  // 检查是否有 uuid 或 file
-  const searchParamUrl = searchParams.get("url");
-  const hasValidSourceParam = !searchParamUrl && !!(searchParams.get("uuid") || searchParams.get("file"));
-
-  const urlHref = useMemo(() => {
-    if (searchParamUrl) {
-      try {
-        // 取url=之后的所有内容
-        const idx = location.search.indexOf("url=");
-        const rawUrl = idx !== -1 ? location.search.slice(idx + 4) : searchParamUrl;
-        const urlObject = new URL(rawUrl);
-        // 验证解析后的 URL 是否具备核心要素，确保安全性与合法性
-        if (urlObject.protocol && urlObject.hostname && urlObject.pathname) {
-          return rawUrl;
-        }
-      } catch {
-        // ignored
-      }
-    }
-    return "";
-  }, [searchParamUrl]);
-
-  const [fetchingState, setFetchingState] = useState({
-    loadingStatus: "",
-    errorStatus: "",
-  });
-
-  const loadURLAsync = async (url: string) => {
-    // 1. 定义获取单个脚本的内部逻辑，负责处理进度条与单次错误
-    const fetchValidScript = async () => {
-      const result = await fetchScriptBody(url, {
-        onProgress: (info: { receivedLength: number }) => {
-          setFetchingState((prev) => ({
-            ...prev,
-            loadingStatus: t("downloading_status_text", { bytes: formatBytes(info.receivedLength) }),
-          }));
-        },
-      });
-      if (result.code && result.metadata) {
-        return { result, url } as const; // 找到有效的立即返回
-      }
-      throw new Error(t("install_page_load_failed"));
-    };
-
-    try {
-      // 2. 执行获取
-      const { result, url } = await fetchValidScript();
-      const { code, metadata } = result;
-
-      // 3. 处理数据与缓存
-      const uuid = uuidv4();
-      const scriptData = [false, createScriptInfo(uuid, code, url, "user", metadata)];
-
-      await cacheInstance.set(`${CACHE_KEY_SCRIPT_INFO}${uuid}`, scriptData);
-
-      // 4. 更新导向
-      setSearchParams(new URLSearchParams(`?uuid=${uuid}`), { replace: true });
-    } catch (err: any) {
-      // 5. 统一错误处理
-      setFetchingState((prev) => ({
-        ...prev,
-        loadingStatus: "",
-        errorStatus: `${err?.message || err}`,
-      }));
-    }
-  };
-
-  const handleUrlChangeAndFetch = (targetUrlHref: string) => {
-    setFetchingState((prev) => ({
-      ...prev,
-      loadingStatus: t("install_page_please_wait"),
-    }));
-    loadURLAsync(targetUrlHref);
-  };
-
-  // 有 url 的话下载内容
-  useEffect(() => {
-    if (urlHref) handleUrlChangeAndFetch(urlHref);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [urlHref]);
-
-  if (!hasValidSourceParam) {
-    return urlHref ? (
+  // URL 加载中 / 错误 / 无效页面
+  if (!data.hasValidSourceParam) {
+    return data.urlHref ? (
       <div className="tw-flex tw-justify-center tw-items-center tw-h-screen">
         <Space direction="vertical" align="center">
-          {fetchingState.loadingStatus && (
+          {data.fetchingState.loadingStatus && (
             <>
               <Typography.Title heading={3}>{t("install_page_loading")}</Typography.Title>
               <div className="downloading">
-                <Typography.Text>{fetchingState.loadingStatus}</Typography.Text>
+                <Typography.Text>{data.fetchingState.loadingStatus}</Typography.Text>
                 <div className="loader"></div>
               </div>
             </>
           )}
-          {fetchingState.errorStatus && (
+          {data.fetchingState.errorStatus && (
             <>
               <Typography.Title heading={3}>{t("install_page_load_failed")}</Typography.Title>
-              <div className="error-message">{fetchingState.errorStatus}</div>
+              <div className="error-message">{data.fetchingState.errorStatus}</div>
             </>
           )}
         </Space>
@@ -759,249 +72,8 @@ function App() {
     );
   }
 
-  return (
-    <div id="install-app-container" className="tw-flex tw-flex-col">
-      {/* 后台运行提示对话框 */}
-      <Modal
-        title={t("enable_background.prompt_title")}
-        visible={showBackgroundPrompt}
-        onOk={async () => {
-          try {
-            const granted = await chrome.permissions.request({ permissions: ["background"] });
-            if (granted) {
-              Message.success(t("enable_background.title")!);
-            } else {
-              Message.info(t("enable_background.maybe_later")!);
-            }
-            setShowBackgroundPrompt(false);
-            localStorage.setItem(backgroundPromptShownKey, "true");
-          } catch (e) {
-            console.error(e);
-            Message.error(t("enable_background.enable_failed")!);
-          }
-        }}
-        onCancel={() => {
-          setShowBackgroundPrompt(false);
-          localStorage.setItem(backgroundPromptShownKey, "true");
-        }}
-        okText={t("enable_background.enable_now")}
-        cancelText={t("enable_background.maybe_later")}
-        autoFocus={false}
-        focusLock={true}
-      >
-        <Space direction="vertical" size="medium">
-          <Typography.Text>
-            {t("enable_background.prompt_description", {
-              scriptType: upsertScript?.metadata?.background ? t("background_script") : t("scheduled_script"),
-            })}
-          </Typography.Text>
-          <Typography.Text type="secondary">{t("enable_background.settings_hint")}</Typography.Text>
-        </Space>
-      </Modal>
-      <div className="tw-flex tw-flex-row tw-gap-x-3 tw-pt-3 tw-pb-3">
-        <div className="tw-grow-1 tw-shrink-1 tw-flex tw-flex-row tw-justify-start tw-items-center">
-          {upsertScript?.metadata.icon && <ScriptIcons script={upsertScript} size={32} />}
-          {upsertScript && (
-            <Tooltip position="tl" content={i18nName(upsertScript)}>
-              <Typography.Text bold className="tw-text-size-lg tw-truncate tw-w-0 tw-grow-1">
-                {i18nName(upsertScript)}
-              </Typography.Text>
-            </Tooltip>
-          )}
-          <Tooltip content={scriptInfo?.userSubscribe ? t("subscribe_source_tooltip") : t("script_status_tooltip")}>
-            <Switch style={{ marginLeft: "8px" }} checked={enable} onChange={handleStatusChange} />
-          </Tooltip>
-        </div>
-        <div className="tw-grow-0 tw-shrink-1 tw-flex tw-flex-row tw-flex-wrap tw-gap-x-2 tw-gap-y-1 tw-items-center">
-          <div className="tw-flex tw-flex-row tw-flex-nowrap tw-gap-x-2">
-            {oldScriptVersion && (
-              <Tooltip content={`${t("current_version")}: v${oldScriptVersion}`}>
-                <Tag bordered>{oldScriptVersion}</Tag>
-              </Tooltip>
-            )}
-            {typeof metadataLive.version?.[0] === "string" && metadataLive.version[0] !== oldScriptVersion && (
-              <Tooltip color="red" content={`${t("update_version")}: v${metadataLive.version[0]}`}>
-                <Tag bordered color="red">
-                  {metadataLive.version[0]}
-                </Tag>
-              </Tooltip>
-            )}
-          </div>
-        </div>
-      </div>
-      <div className="tw-shrink-1 tw-grow-1 tw-overflow-y-auto tw-pl-4 tw-pr-4 tw-gap-y-2 tw-flex tw-flex-col tw-mb-4 tw-h-0">
-        <div className="tw-flex tw-flex-wrap tw-gap-x-3 tw-gap-y-2 tw-items-start">
-          <div className="tw-flex tw-flex-col tw-shrink-1 tw-grow-1 tw-basis-8/12">
-            <div className="tw-grow-1 tw-shrink-0">
-              <div className="tw-flex tw-flex-wrap tw-gap-x-2 tw-gap-y-1 tag-container tw-float-right">
-                {(metadataLive.background || metadataLive.crontab) && (
-                  <Tooltip color="green" content={t("background_script_tag")}>
-                    <Tag bordered color="green">
-                      {t("background_script")}
-                    </Tag>
-                  </Tooltip>
-                )}
-                {metadataLive.crontab && (
-                  <Tooltip color="green" content={t("scheduled_script_tag")}>
-                    <Tag bordered color="green">
-                      {t("scheduled_script")}
-                    </Tag>
-                  </Tooltip>
-                )}
-                {metadataLive.antifeature?.length &&
-                  metadataLive.antifeature.map((antifeature) => {
-                    const item = antifeature.split(" ")[0];
-                    return (
-                      antifeatures[item] && (
-                        <Tooltip color={antifeatures[item].color} content={antifeatures[item].description}>
-                          <Tag bordered color={antifeatures[item].color}>
-                            {antifeatures[item].title}
-                          </Tag>
-                        </Tooltip>
-                      )
-                    );
-                  })}
-              </div>
-              <div>
-                <div>
-                  <Typography.Text bold>{upsertScript && i18nDescription(upsertScript!)}</Typography.Text>
-                </div>
-                <div>
-                  <Typography.Text bold>{`${t("author")}: ${metadataLive.author}`}</Typography.Text>
-                </div>
-                <div>
-                  <Typography.Text
-                    bold
-                    style={{
-                      overflowWrap: "break-word",
-                      wordBreak: "break-word",
-                      maxHeight: "70px",
-                      display: "block",
-                      overflowY: "auto",
-                    }}
-                  >
-                    {`${t("source")}: ${prettyUrl(scriptInfo?.url)}`}
-                  </Typography.Text>
-                </div>
-              </div>
-            </div>
-          </div>
-          {descriptionParagraph?.length ? (
-            <div className="tw-flex tw-flex-col tw-shrink-0 tw-grow-1">
-              <Typography>
-                <Typography.Paragraph blockquote className="tw-pt-2 tw-pb-2">
-                  {descriptionParagraph}
-                </Typography.Paragraph>
-              </Typography>
-            </div>
-          ) : (
-            <></>
-          )}
-          <div className="tw-flex tw-flex-row tw-flex-wrap tw-gap-x-4">
-            {permissions.map((item) => (
-              <div key={item.label} className="tw-flex tw-flex-col tw-gap-y-2">
-                {item.value?.length > 0 ? (
-                  <>
-                    <Typography.Text bold color={item.color}>
-                      {item.label}
-                    </Typography.Text>
-                    <div
-                      style={{
-                        maxHeight: "calc( 7.5 * 1.2rem )",
-                        overflowY: "auto",
-                        overflowX: "auto",
-                        boxSizing: "border-box",
-                      }}
-                    >
-                      {item.value.map((v) => (
-                        <div key={v} className="permission-entry">
-                          <Typography.Text style={{ wordBreak: "unset", color: item.color }}>{v}</Typography.Text>
-                        </div>
-                      ))}
-                    </div>
-                  </>
-                ) : (
-                  <></>
-                )}
-              </div>
-            ))}
-          </div>
-        </div>
-        <div className="tw-flex tw-flex-row tw-flex-wrap tw-items-center tw-gap-2">
-          <div className="tw-grow-1">
-            <Typography.Text type="error">{t("install_from_legitimate_sources_warning")}</Typography.Text>
-          </div>
-          <div className="tw-grow-1 tw-shrink-0 tw-text-end">
-            <Space>
-              <Button.Group>
-                <Button type="primary" size="small" onClick={handleInstallBasic} disabled={watchFile}>
-                  {btnText}
-                </Button>
-                <Dropdown
-                  droplist={
-                    <Menu>
-                      <Menu.Item key="install-no-close" onClick={handleInstallCloseAfterInstall}>
-                        {isUpdate ? t("update_script_no_close") : t("install_script_no_close")}
-                      </Menu.Item>
-                      {!scriptInfo?.userSubscribe && (
-                        <Menu.Item key="install-no-updates" onClick={handleInstallNoMoreUpdates}>
-                          {isUpdate ? t("update_script_no_more_update") : t("install_script_no_more_update")}
-                        </Menu.Item>
-                      )}
-                    </Menu>
-                  }
-                  position="bottom"
-                  disabled={watchFile}
-                >
-                  <Button type="primary" size="small" icon={<IconDown />} disabled={watchFile} />
-                </Dropdown>
-              </Button.Group>
-              {localFileHandle && (
-                <Popover content={t("watch_file_description")}>
-                  <Button type="secondary" size="small" onClick={setWatchFileClick}>
-                    {watchFile ? t("stop_watch_file") : t("watch_file")}
-                  </Button>
-                </Popover>
-              )}
-              {isUpdate ? (
-                <Button.Group>
-                  <Button type="primary" status="danger" size="small" onClick={handleCloseBasic}>
-                    {t("close")}
-                  </Button>
-                  <Dropdown
-                    droplist={
-                      <Menu>
-                        {!scriptInfo?.userSubscribe && (
-                          <Menu.Item key="install-no-updates" onClick={handleCloseNoMoreUpdates}>
-                            {t("close_update_script_no_more_update")}
-                          </Menu.Item>
-                        )}
-                      </Menu>
-                    }
-                    position="bottom"
-                  >
-                    <Button type="primary" status="danger" size="small" icon={<IconDown />} />
-                  </Dropdown>
-                </Button.Group>
-              ) : (
-                <Button type="primary" status="danger" size="small" onClick={handleCloseBasic}>
-                  {t("close")}
-                </Button>
-              )}
-            </Space>
-          </div>
-        </div>
-        <div id="show-code-container">
-          <CodeEditor
-            id="show-code"
-            className="sc-inset-0"
-            code={scriptCode || undefined}
-            diffCode={diffCode === scriptCode ? "" : diffCode || ""}
-          />
-        </div>
-      </div>
-    </div>
-  );
+  // UserScript / Subscribe 安装
+  return <ScriptInstallView data={data} />;
 }
 
 export default App;
diff --git a/src/pages/install/components/CATToolInstallView.tsx b/src/pages/install/components/CATToolInstallView.tsx
new file mode 100644
index 000000000..89499a642
--- /dev/null
+++ b/src/pages/install/components/CATToolInstallView.tsx
@@ -0,0 +1,117 @@
+import { Button, Space, Tag, Typography } from "@arco-design/web-react";
+import { useTranslation } from "react-i18next";
+import CodeEditor from "../../components/CodeEditor";
+import type { CATToolMetadata } from "@App/app/service/agent/types";
+
+interface CATToolInstallViewProps {
+  metadata: CATToolMetadata;
+  scriptCode: string;
+  onInstall: () => void;
+  onClose: () => void;
+  sourceScriptName?: string;
+  isUpdate?: boolean;
+}
+
+function CATToolInstallView({
+  metadata,
+  scriptCode,
+  onInstall,
+  onClose,
+  sourceScriptName,
+  isUpdate,
+}: CATToolInstallViewProps) {
+  const { t } = useTranslation();
+
+  return (
+    <div id="install-app-container" className="tw-flex tw-flex-col">
+      <div className="tw-flex tw-flex-row tw-gap-x-3 tw-pt-3 tw-pb-3">
+        <div className="tw-grow-1 tw-shrink-1 tw-flex tw-flex-row tw-justify-start tw-items-center">
+          <Tag bordered color="arcoblue" style={{ marginRight: "8px" }}>
+            {"CATTool"}
+          </Tag>
+          <Typography.Text bold className="tw-text-size-lg tw-truncate tw-w-0 tw-grow-1">
+            {metadata.name}
+          </Typography.Text>
+          {isUpdate && (
+            <Tag bordered color="green" style={{ marginLeft: "8px" }}>
+              {t("update")}
+            </Tag>
+          )}
+        </div>
+      </div>
+      <div className="tw-shrink-1 tw-grow-1 tw-overflow-y-auto tw-pl-4 tw-pr-4 tw-gap-y-2 tw-flex tw-flex-col tw-mb-4 tw-h-0">
+        <div className="tw-flex tw-flex-wrap tw-gap-x-3 tw-gap-y-2 tw-items-start">
+          <div className="tw-flex tw-flex-col tw-shrink-1 tw-grow-1 tw-basis-8/12">
+            {sourceScriptName && (
+              <div className="tw-mb-1">
+                <Typography.Text type="secondary">
+                  {`${t("cattool_source_script")}: ${sourceScriptName}`}
+                </Typography.Text>
+              </div>
+            )}
+            {metadata.description && (
+              <div>
+                <Typography.Text bold>{metadata.description}</Typography.Text>
+              </div>
+            )}
+            {metadata.params.length > 0 && (
+              <div className="tw-mt-2">
+                <Typography.Text bold>{`${t("cattool_parameters")}:`}</Typography.Text>
+                <div className="tw-mt-1 tw-flex tw-flex-col tw-gap-y-1">
+                  {metadata.params.map((param) => (
+                    <div key={param.name} className="tw-flex tw-flex-row tw-gap-x-2 tw-items-center">
+                      <Tag bordered size="small">
+                        {param.name}
+                      </Tag>
+                      <Tag bordered size="small" color="gray">
+                        {param.type}
+                      </Tag>
+                      {param.required && (
+                        <Tag bordered size="small" color="red">
+                          {t("cattool_required")}
+                        </Tag>
+                      )}
+                      {param.description && <Typography.Text type="secondary">{param.description}</Typography.Text>}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+            {metadata.grants.length > 0 && (
+              <div className="tw-mt-2">
+                <Typography.Text bold>{`${t("cattool_permissions")}:`}</Typography.Text>
+                <div className="tw-mt-1 tw-flex tw-flex-row tw-flex-wrap tw-gap-1">
+                  {metadata.grants.map((grant) => (
+                    <Tag key={grant} bordered size="small" color="orangered">
+                      {grant}
+                    </Tag>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+        <div className="tw-flex tw-flex-row tw-flex-wrap tw-items-center tw-gap-2">
+          <div className="tw-grow-1">
+            <Typography.Text type="error">{t("install_from_legitimate_sources_warning")}</Typography.Text>
+          </div>
+          <div className="tw-grow-1 tw-shrink-0 tw-text-end">
+            <Space>
+              <Button type="primary" size="small" onClick={onInstall}>
+                {isUpdate ? t("update_script") : t("install_script")}
+              </Button>
+              <Button type="primary" status="danger" size="small" onClick={onClose}>
+                {t("close")}
+              </Button>
+            </Space>
+          </div>
+        </div>
+        <div id="show-code-container">
+          <CodeEditor id="show-code" className="sc-inset-0" code={scriptCode || undefined} diffCode="" />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default CATToolInstallView;
diff --git a/src/pages/install/components/ScriptInstallView.tsx b/src/pages/install/components/ScriptInstallView.tsx
new file mode 100644
index 000000000..01e3c6626
--- /dev/null
+++ b/src/pages/install/components/ScriptInstallView.tsx
@@ -0,0 +1,296 @@
+import {
+  Button,
+  Dropdown,
+  Menu,
+  Modal,
+  Space,
+  Switch,
+  Tag,
+  Tooltip,
+  Typography,
+  Popover,
+  Message,
+} from "@arco-design/web-react";
+import { IconDown } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import CodeEditor from "../../components/CodeEditor";
+import { i18nName, i18nDescription } from "@App/locales/locales";
+import { ScriptIcons } from "../../options/routes/utils";
+import { prettyUrl } from "@App/pkg/utils/url-utils";
+import { backgroundPromptShownKey } from "../utils";
+import type { InstallData } from "../hooks";
+
+function ScriptInstallView({ data }: { data: InstallData }) {
+  const {
+    enable,
+    btnText,
+    scriptCode,
+    scriptInfo,
+    upsertScript,
+    diffCode,
+    oldScriptVersion,
+    isUpdate,
+    localFileHandle,
+    showBackgroundPrompt,
+    setShowBackgroundPrompt,
+    watchFile,
+    metadataLive,
+    permissions,
+    descriptionParagraph,
+    antifeatures,
+    handleInstallBasic,
+    handleInstallCloseAfterInstall,
+    handleInstallNoMoreUpdates,
+    handleStatusChange,
+    handleCloseBasic,
+    handleCloseNoMoreUpdates,
+    setWatchFileClick,
+  } = data;
+  const { t } = useTranslation();
+
+  return (
+    <div id="install-app-container" className="tw-flex tw-flex-col">
+      {/* 后台运行提示对话框 */}
+      <Modal
+        title={t("enable_background.prompt_title")}
+        visible={showBackgroundPrompt}
+        onOk={async () => {
+          try {
+            const granted = await chrome.permissions.request({ permissions: ["background"] });
+            if (granted) {
+              Message.success(t("enable_background.title")!);
+            } else {
+              Message.info(t("enable_background.maybe_later")!);
+            }
+            setShowBackgroundPrompt(false);
+            localStorage.setItem(backgroundPromptShownKey, "true");
+          } catch (e) {
+            console.error(e);
+            Message.error(t("enable_background.enable_failed")!);
+          }
+        }}
+        onCancel={() => {
+          setShowBackgroundPrompt(false);
+          localStorage.setItem(backgroundPromptShownKey, "true");
+        }}
+        okText={t("enable_background.enable_now")}
+        cancelText={t("enable_background.maybe_later")}
+        autoFocus={false}
+        focusLock={true}
+      >
+        <Space direction="vertical" size="medium">
+          <Typography.Text>
+            {t("enable_background.prompt_description", {
+              scriptType: upsertScript?.metadata?.background ? t("background_script") : t("scheduled_script"),
+            })}
+          </Typography.Text>
+          <Typography.Text type="secondary">{t("enable_background.settings_hint")}</Typography.Text>
+        </Space>
+      </Modal>
+      <div className="tw-flex tw-flex-row tw-gap-x-3 tw-pt-3 tw-pb-3">
+        <div className="tw-grow-1 tw-shrink-1 tw-flex tw-flex-row tw-justify-start tw-items-center">
+          {upsertScript?.metadata.icon && <ScriptIcons script={upsertScript} size={32} />}
+          {upsertScript && (
+            <Tooltip position="tl" content={i18nName(upsertScript)}>
+              <Typography.Text bold className="tw-text-size-lg tw-truncate tw-w-0 tw-grow-1">
+                {i18nName(upsertScript)}
+              </Typography.Text>
+            </Tooltip>
+          )}
+          <Tooltip content={scriptInfo?.userSubscribe ? t("subscribe_source_tooltip") : t("script_status_tooltip")}>
+            <Switch style={{ marginLeft: "8px" }} checked={enable} onChange={handleStatusChange} />
+          </Tooltip>
+        </div>
+        <div className="tw-grow-0 tw-shrink-1 tw-flex tw-flex-row tw-flex-wrap tw-gap-x-2 tw-gap-y-1 tw-items-center">
+          <div className="tw-flex tw-flex-row tw-flex-nowrap tw-gap-x-2">
+            {oldScriptVersion && (
+              <Tooltip content={`${t("current_version")}: v${oldScriptVersion}`}>
+                <Tag bordered>{oldScriptVersion}</Tag>
+              </Tooltip>
+            )}
+            {typeof metadataLive.version?.[0] === "string" && metadataLive.version[0] !== oldScriptVersion && (
+              <Tooltip color="red" content={`${t("update_version")}: v${metadataLive.version[0]}`}>
+                <Tag bordered color="red">
+                  {metadataLive.version[0]}
+                </Tag>
+              </Tooltip>
+            )}
+          </div>
+        </div>
+      </div>
+      <div className="tw-shrink-1 tw-grow-1 tw-overflow-y-auto tw-pl-4 tw-pr-4 tw-gap-y-2 tw-flex tw-flex-col tw-mb-4 tw-h-0">
+        <div className="tw-flex tw-flex-wrap tw-gap-x-3 tw-gap-y-2 tw-items-start">
+          <div className="tw-flex tw-flex-col tw-shrink-1 tw-grow-1 tw-basis-8/12">
+            <div className="tw-grow-1 tw-shrink-0">
+              <div className="tw-flex tw-flex-wrap tw-gap-x-2 tw-gap-y-1 tag-container tw-float-right">
+                {(metadataLive.background || metadataLive.crontab) && (
+                  <Tooltip color="green" content={t("background_script_tag")}>
+                    <Tag bordered color="green">
+                      {t("background_script")}
+                    </Tag>
+                  </Tooltip>
+                )}
+                {metadataLive.crontab && (
+                  <Tooltip color="green" content={t("scheduled_script_tag")}>
+                    <Tag bordered color="green">
+                      {t("scheduled_script")}
+                    </Tag>
+                  </Tooltip>
+                )}
+                {metadataLive.antifeature?.length &&
+                  metadataLive.antifeature.map((antifeature) => {
+                    const item = antifeature.split(" ")[0];
+                    return (
+                      antifeatures[item] && (
+                        <Tooltip key={item} color={antifeatures[item].color} content={antifeatures[item].description}>
+                          <Tag bordered color={antifeatures[item].color}>
+                            {antifeatures[item].title}
+                          </Tag>
+                        </Tooltip>
+                      )
+                    );
+                  })}
+              </div>
+              <div>
+                <div>
+                  <Typography.Text bold>{upsertScript && i18nDescription(upsertScript!)}</Typography.Text>
+                </div>
+                <div>
+                  <Typography.Text bold>{`${t("author")}: ${metadataLive.author}`}</Typography.Text>
+                </div>
+                <div>
+                  <Typography.Text
+                    bold
+                    style={{
+                      overflowWrap: "break-word",
+                      wordBreak: "break-word",
+                      maxHeight: "70px",
+                      display: "block",
+                      overflowY: "auto",
+                    }}
+                  >
+                    {`${t("source")}: ${prettyUrl(scriptInfo?.url)}`}
+                  </Typography.Text>
+                </div>
+              </div>
+            </div>
+          </div>
+          {descriptionParagraph?.length ? (
+            <div className="tw-flex tw-flex-col tw-shrink-0 tw-grow-1">
+              <Typography>
+                <Typography.Paragraph blockquote className="tw-pt-2 tw-pb-2">
+                  {descriptionParagraph}
+                </Typography.Paragraph>
+              </Typography>
+            </div>
+          ) : (
+            <></>
+          )}
+          <div className="tw-flex tw-flex-row tw-flex-wrap tw-gap-x-4">
+            {permissions.map((item) => (
+              <div key={item.label} className="tw-flex tw-flex-col tw-gap-y-2">
+                {item.value?.length > 0 ? (
+                  <>
+                    <Typography.Text bold color={item.color}>
+                      {item.label}
+                    </Typography.Text>
+                    <div
+                      style={{
+                        maxHeight: "calc( 7.5 * 1.2rem )",
+                        overflowY: "auto",
+                        overflowX: "auto",
+                        boxSizing: "border-box",
+                      }}
+                    >
+                      {item.value.map((v) => (
+                        <div key={v} className="permission-entry">
+                          <Typography.Text style={{ wordBreak: "unset", color: item.color }}>{v}</Typography.Text>
+                        </div>
+                      ))}
+                    </div>
+                  </>
+                ) : (
+                  <></>
+                )}
+              </div>
+            ))}
+          </div>
+        </div>
+        <div className="tw-flex tw-flex-row tw-flex-wrap tw-items-center tw-gap-2">
+          <div className="tw-grow-1">
+            <Typography.Text type="error">{t("install_from_legitimate_sources_warning")}</Typography.Text>
+          </div>
+          <div className="tw-grow-1 tw-shrink-0 tw-text-end">
+            <Space>
+              <Button.Group>
+                <Button type="primary" size="small" onClick={handleInstallBasic} disabled={watchFile}>
+                  {btnText}
+                </Button>
+                <Dropdown
+                  droplist={
+                    <Menu>
+                      <Menu.Item key="install-no-close" onClick={handleInstallCloseAfterInstall}>
+                        {isUpdate ? t("update_script_no_close") : t("install_script_no_close")}
+                      </Menu.Item>
+                      {!scriptInfo?.userSubscribe && (
+                        <Menu.Item key="install-no-updates" onClick={handleInstallNoMoreUpdates}>
+                          {isUpdate ? t("update_script_no_more_update") : t("install_script_no_more_update")}
+                        </Menu.Item>
+                      )}
+                    </Menu>
+                  }
+                  position="bottom"
+                  disabled={watchFile}
+                >
+                  <Button type="primary" size="small" icon={<IconDown />} disabled={watchFile} />
+                </Dropdown>
+              </Button.Group>
+              {localFileHandle && (
+                <Popover content={t("watch_file_description")}>
+                  <Button type="secondary" size="small" onClick={setWatchFileClick}>
+                    {watchFile ? t("stop_watch_file") : t("watch_file")}
+                  </Button>
+                </Popover>
+              )}
+              {isUpdate ? (
+                <Button.Group>
+                  <Button type="primary" status="danger" size="small" onClick={handleCloseBasic}>
+                    {t("close")}
+                  </Button>
+                  <Dropdown
+                    droplist={
+                      <Menu>
+                        {!scriptInfo?.userSubscribe && (
+                          <Menu.Item key="install-no-updates" onClick={handleCloseNoMoreUpdates}>
+                            {t("close_update_script_no_more_update")}
+                          </Menu.Item>
+                        )}
+                      </Menu>
+                    }
+                    position="bottom"
+                  >
+                    <Button type="primary" status="danger" size="small" icon={<IconDown />} />
+                  </Dropdown>
+                </Button.Group>
+              ) : (
+                <Button type="primary" status="danger" size="small" onClick={handleCloseBasic}>
+                  {t("close")}
+                </Button>
+              )}
+            </Space>
+          </div>
+        </div>
+        <div id="show-code-container">
+          <CodeEditor
+            id="show-code"
+            className="sc-inset-0"
+            code={scriptCode || undefined}
+            diffCode={diffCode === scriptCode ? "" : diffCode || ""}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default ScriptInstallView;
diff --git a/src/pages/install/components/SkillInstallView.tsx b/src/pages/install/components/SkillInstallView.tsx
new file mode 100644
index 000000000..a75cd6ffe
--- /dev/null
+++ b/src/pages/install/components/SkillInstallView.tsx
@@ -0,0 +1,223 @@
+import { useState } from "react";
+import { Button, Space, Tag, Typography } from "@arco-design/web-react";
+import { IconDown, IconUp } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { parseCATToolMetadata } from "@App/pkg/utils/cattool";
+import type { SkillConfigField } from "@App/app/service/agent/types";
+
+interface SkillInstallViewProps {
+  metadata: { name: string; description: string; config?: Record<string, SkillConfigField> };
+  prompt: string;
+  scripts: Array<{ name: string; code: string }>;
+  references: Array<{ name: string; content: string }>;
+  isUpdate: boolean;
+  onInstall: () => void;
+  onClose: () => void;
+}
+
+function SkillInstallView({
+  metadata,
+  prompt,
+  scripts,
+  references,
+  isUpdate,
+  onInstall,
+  onClose,
+}: SkillInstallViewProps) {
+  const { t } = useTranslation();
+  const [promptExpanded, setPromptExpanded] = useState(false);
+
+  return (
+    <div id="install-app-container" className="tw-flex tw-flex-col">
+      {/* Header */}
+      <div className="tw-flex tw-flex-row tw-gap-x-3 tw-pt-3 tw-pb-3">
+        <div className="tw-grow-1 tw-shrink-1 tw-flex tw-flex-row tw-justify-start tw-items-center">
+          <Tag bordered color="purple" style={{ marginRight: "8px" }}>
+            {"Skill"}
+          </Tag>
+          <Typography.Text bold className="tw-text-size-lg tw-truncate tw-w-0 tw-grow-1">
+            {metadata.name}
+          </Typography.Text>
+          {isUpdate && (
+            <Tag bordered color="green" style={{ marginLeft: "8px" }}>
+              {t("update")}
+            </Tag>
+          )}
+        </div>
+      </div>
+
+      {/* Content */}
+      <div className="tw-shrink-1 tw-grow-1 tw-overflow-y-auto tw-pl-4 tw-pr-4 tw-gap-y-2 tw-flex tw-flex-col tw-mb-4 tw-h-0">
+        <div className="tw-flex tw-flex-wrap tw-gap-x-3 tw-gap-y-2 tw-items-start">
+          <div className="tw-flex tw-flex-col tw-shrink-1 tw-grow-1 tw-basis-full">
+            {/* Description */}
+            {metadata.description && (
+              <div className="tw-mb-2">
+                <Typography.Text bold>{metadata.description}</Typography.Text>
+              </div>
+            )}
+
+            {/* Prompt */}
+            {prompt && (
+              <div className="tw-mb-2">
+                <div
+                  className="tw-flex tw-items-center tw-gap-1 tw-cursor-pointer tw-select-none"
+                  onClick={() => setPromptExpanded(!promptExpanded)}
+                >
+                  <Typography.Text bold>
+                    {t("agent_skills_prompt")}
+                    {":"}
+                  </Typography.Text>
+                  {promptExpanded ? <IconUp /> : <IconDown />}
+                </div>
+                {promptExpanded ? (
+                  <div className="tw-mt-1 tw-p-3 tw-rounded-lg tw-bg-[var(--color-fill-1)] tw-overflow-auto tw-max-h-80">
+                    <pre className="tw-whitespace-pre-wrap tw-text-sm tw-m-0" style={{ fontFamily: "monospace" }}>
+                      {prompt}
+                    </pre>
+                  </div>
+                ) : (
+                  <div className="tw-mt-1">
+                    <Typography.Text type="secondary" className="tw-text-xs">
+                      {prompt.length > 150 ? prompt.slice(0, 150) + "..." : prompt}
+                    </Typography.Text>
+                  </div>
+                )}
+              </div>
+            )}
+
+            {/* Tools */}
+            {scripts.length > 0 && (
+              <div className="tw-mt-2">
+                <Typography.Text bold>{`${t("agent_skills_tools")} (${scripts.length}):`}</Typography.Text>
+                <div className="tw-mt-1 tw-flex tw-flex-col tw-gap-y-2">
+                  {scripts.map((script) => {
+                    const toolMeta = parseCATToolMetadata(script.code);
+                    return (
+                      <div key={script.name} className="tw-p-3 tw-rounded-lg tw-bg-[var(--color-fill-1)]">
+                        <div className="tw-flex tw-items-center tw-gap-2 tw-mb-1">
+                          <Tag bordered size="small" color="arcoblue">
+                            {toolMeta?.name || script.name}
+                          </Tag>
+                        </div>
+                        {toolMeta?.description && (
+                          <Typography.Text type="secondary" className="tw-text-xs">
+                            {toolMeta.description}
+                          </Typography.Text>
+                        )}
+                        {toolMeta && toolMeta.params.length > 0 && (
+                          <div className="tw-mt-1 tw-flex tw-flex-col tw-gap-y-1">
+                            {toolMeta.params.map((param) => (
+                              <div key={param.name} className="tw-flex tw-flex-row tw-gap-x-2 tw-items-center">
+                                <Tag bordered size="small">
+                                  {param.name}
+                                </Tag>
+                                <Tag bordered size="small" color="gray">
+                                  {param.type}
+                                </Tag>
+                                {param.required && (
+                                  <Tag bordered size="small" color="red">
+                                    {t("cattool_required")}
+                                  </Tag>
+                                )}
+                                {param.description && (
+                                  <Typography.Text type="secondary" className="tw-text-xs">
+                                    {param.description}
+                                  </Typography.Text>
+                                )}
+                              </div>
+                            ))}
+                          </div>
+                        )}
+                        {toolMeta && toolMeta.grants.length > 0 && (
+                          <div className="tw-mt-1 tw-flex tw-flex-row tw-flex-wrap tw-gap-1">
+                            {toolMeta.grants.map((grant) => (
+                              <Tag key={grant} bordered size="small" color="orangered">
+                                {grant}
+                              </Tag>
+                            ))}
+                          </div>
+                        )}
+                      </div>
+                    );
+                  })}
+                </div>
+              </div>
+            )}
+
+            {/* Config Fields */}
+            {metadata.config && Object.keys(metadata.config).length > 0 && (
+              <div className="tw-mt-2">
+                <Typography.Text
+                  bold
+                >{`${t("agent_skills_config")} (${Object.keys(metadata.config).length}):`}</Typography.Text>
+                <div className="tw-mt-1 tw-flex tw-flex-col tw-gap-y-2">
+                  {Object.entries(metadata.config).map(([key, field]) => (
+                    <div key={key} className="tw-p-3 tw-rounded-lg tw-bg-[var(--color-fill-1)]">
+                      <div className="tw-flex tw-items-center tw-gap-2 tw-mb-1">
+                        <Tag bordered size="small" color="orange">
+                          {key}
+                        </Tag>
+                        <Tag bordered size="small" color="gray">
+                          {field.type}
+                        </Tag>
+                        {field.required && (
+                          <Tag bordered size="small" color="red">
+                            {t("cattool_required")}
+                          </Tag>
+                        )}
+                        {field.secret && (
+                          <Tag bordered size="small" color="purple">
+                            {"secret"}
+                          </Tag>
+                        )}
+                      </div>
+                      {field.title && (
+                        <Typography.Text type="secondary" className="tw-text-xs">
+                          {field.title}
+                        </Typography.Text>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {/* References */}
+            {references.length > 0 && (
+              <div className="tw-mt-2">
+                <Typography.Text bold>{`${t("agent_skills_references")} (${references.length}):`}</Typography.Text>
+                <div className="tw-mt-1 tw-flex tw-flex-wrap tw-gap-1.5">
+                  {references.map((ref) => (
+                    <Tag key={ref.name} bordered size="small" color="green">
+                      {ref.name}
+                    </Tag>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Warning + Actions */}
+        <div className="tw-flex tw-flex-row tw-flex-wrap tw-items-center tw-gap-2 tw-mt-4">
+          <div className="tw-grow-1">
+            <Typography.Text type="error">{t("install_from_legitimate_sources_warning")}</Typography.Text>
+          </div>
+          <div className="tw-grow-1 tw-shrink-0 tw-text-end">
+            <Space>
+              <Button type="primary" size="small" onClick={onInstall}>
+                {isUpdate ? t("update_script") : t("install_script")}
+              </Button>
+              <Button type="primary" status="danger" size="small" onClick={onClose}>
+                {t("close")}
+              </Button>
+            </Space>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default SkillInstallView;
diff --git a/src/pages/install/hooks.tsx b/src/pages/install/hooks.tsx
new file mode 100644
index 000000000..15fb12d38
--- /dev/null
+++ b/src/pages/install/hooks.tsx
@@ -0,0 +1,735 @@
+import { useEffect, useMemo, useState } from "react";
+import { useSearchParams } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { Message, Typography } from "@arco-design/web-react";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+import type { SCMetadata, Script } from "@App/app/repo/scripts";
+import { SCRIPT_STATUS_DISABLE, SCRIPT_STATUS_ENABLE } from "@App/app/repo/scripts";
+import type { Subscribe } from "@App/app/repo/subscribe";
+import { createScriptInfo, type ScriptInfo } from "@App/pkg/utils/scriptInstall";
+import { parseMetadata, prepareScriptByCode, prepareSubscribeByCode } from "@App/pkg/utils/script";
+import { nextTimeDisplay } from "@App/pkg/utils/cron";
+import { scriptClient, subscribeClient, agentClient } from "../store/features/script";
+import { type FTInfo, startFileTrack, unmountFileTrack } from "@App/pkg/utils/file-tracker";
+import { cleanupOldHandles, loadHandle, saveHandle } from "@App/pkg/utils/filehandle-db";
+import { dayFormat } from "@App/pkg/utils/day_format";
+import { intervalExecution, timeoutExecution } from "@App/pkg/utils/timer";
+import { CACHE_KEY_SCRIPT_INFO } from "@App/app/cache_key";
+import { cacheInstance } from "@App/app/cache";
+import { formatBytes } from "@App/pkg/utils/utils";
+import { i18nName } from "@App/locales/locales";
+import { parseCATToolMetadata } from "@App/pkg/utils/cattool";
+import type { CATToolMetadata } from "@App/app/service/agent/types";
+import {
+  cIdKey,
+  backgroundPromptShownKey,
+  closeWindow,
+  fetchScriptBody,
+  cleanupStaleInstallInfo,
+  type Permission,
+} from "./utils";
+
+type ScriptOrSubscribe = Script | Subscribe;
+
+export function useInstallData() {
+  const [enable, setEnable] = useState<boolean>(false);
+  const [btnText, setBtnText] = useState<string>("");
+  const [scriptCode, setScriptCode] = useState<string>("");
+  const [scriptInfo, setScriptInfo] = useState<ScriptInfo>();
+  const [upsertScript, setUpsertScript] = useState<ScriptOrSubscribe | undefined>(undefined);
+  const [diffCode, setDiffCode] = useState<string>();
+  const [oldScriptVersion, setOldScriptVersion] = useState<string | null>(null);
+  const [isUpdate, setIsUpdate] = useState<boolean>(false);
+  const [localFileHandle, setLocalFileHandle] = useState<FileSystemFileHandle | null>(null);
+  const [showBackgroundPrompt, setShowBackgroundPrompt] = useState<boolean>(false);
+  const { t } = useTranslation();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const [loaded, setLoaded] = useState<boolean>(false);
+  const [doBackwards, setDoBackwards] = useState<boolean>(false);
+  const [cattoolMetadata, setCattoolMetadata] = useState<CATToolMetadata | null>(null);
+  const [cattoolSourceScriptName, setCattoolSourceScriptName] = useState<string | undefined>(undefined);
+  const [cattoolIsUpdate, setCattoolIsUpdate] = useState(false);
+  const [watchFile, setWatchFile] = useState(false);
+
+  // Skill 安装相关状态
+  const skillInstallUuid = searchParams.get("skill");
+  const [skillPreview, setSkillPreview] = useState<{
+    metadata: { name: string; description: string };
+    prompt: string;
+    scripts: Array<{ name: string; code: string }>;
+    references: Array<{ name: string; content: string }>;
+    isUpdate: boolean;
+  } | null>(null);
+
+  const installOrUpdateScript = async (newScript: Script, code: string) => {
+    if (newScript.ignoreVersion) newScript.ignoreVersion = "";
+    await scriptClient.install({ script: newScript, code });
+    const metadata = newScript.metadata;
+    setScriptInfo((prev) => (prev ? { ...prev, code, metadata } : prev));
+    const scriptVersion = metadata.version?.[0];
+    const oldScriptVersion = typeof scriptVersion === "string" ? scriptVersion : "N/A";
+    setOldScriptVersion(oldScriptVersion);
+    setUpsertScript(newScript);
+    setDiffCode(code);
+  };
+
+  const getUpdatedNewScript = async (uuid: string, code: string) => {
+    const oldScript = await scriptClient.info(uuid);
+    if (!oldScript || oldScript.uuid !== uuid) {
+      throw new Error("uuid is mismatched");
+    }
+    const { script } = await prepareScriptByCode(code, oldScript.origin || "", uuid);
+    script.origin = oldScript.origin || script.origin || "";
+    if (!script.name) {
+      throw new Error(t("script_name_cannot_be_set_to_empty"));
+    }
+    return script;
+  };
+
+  const checkBackgroundPrompt = async (script: Script) => {
+    if (!script.metadata.background && !script.metadata.crontab) {
+      return false;
+    }
+    const hasShown = localStorage.getItem(backgroundPromptShownKey);
+    if (hasShown !== "true") {
+      if (!(await chrome.permissions.contains({ permissions: ["background"] }))) {
+        return true;
+      }
+    }
+    return false;
+  };
+
+  // CATTool 通过 GM API 安装的 UUID（由 AgentService 缓存）
+  const cattoolInstallUuid = searchParams.get("cattool");
+
+  const initCATToolFromApi = async (cattoolUuid: string) => {
+    try {
+      setLoaded(true);
+      const { code, scriptName, isUpdate: isExistingUpdate } = await agentClient.getCATToolInstallCode(cattoolUuid);
+      const toolMeta = parseCATToolMetadata(code);
+      if (!toolMeta) {
+        throw new Error("Invalid CATTool: missing or malformed ==CATTool== header");
+      }
+      setCattoolMetadata(toolMeta);
+      setScriptCode(code);
+      setCattoolSourceScriptName(scriptName);
+      setCattoolIsUpdate(!!isExistingUpdate);
+      // 创建一个最小 ScriptInfo 用于页面展示
+      const info = createScriptInfo(cattoolUuid, code, "", "user", {} as SCMetadata);
+      info.cattool = true;
+      setScriptInfo(info);
+    } catch (e: any) {
+      Message.error(t("script_info_load_failed") + " " + e.message);
+    }
+  };
+
+  // CATTool API 安装：点击安装后通知 AgentService
+  const handleCATToolApiInstall = async () => {
+    if (!cattoolInstallUuid) return;
+    try {
+      await agentClient.completeCATToolInstall(cattoolInstallUuid);
+      Message.success(t("install_success")!);
+      setTimeout(() => {
+        closeWindow(doBackwards);
+      }, 500);
+    } catch (e) {
+      Message.error(`${t("install_failed")}: ${e}`);
+    }
+  };
+
+  // CATTool API 安装：用户点击关闭时通知取消
+  const handleCATToolApiCancel = () => {
+    if (!cattoolInstallUuid) return;
+    agentClient.cancelCATToolInstall(cattoolInstallUuid);
+    closeWindow(doBackwards);
+  };
+
+  // Skill ZIP 安装：从缓存加载并解析
+  const initSkillFromCache = async (uuid: string) => {
+    try {
+      setLoaded(true);
+      if (window.history.length > 1) {
+        setDoBackwards(true);
+      }
+      const data = await agentClient.getSkillInstallData(uuid);
+      setSkillPreview(data);
+    } catch (e: any) {
+      Message.error(t("script_info_load_failed") + " " + e.message);
+    }
+  };
+
+  // Skill 安装确认
+  const handleSkillInstall = async () => {
+    if (!skillInstallUuid) return;
+    try {
+      await agentClient.completeSkillInstall(skillInstallUuid);
+      Message.success(t("install_success")!);
+      setTimeout(() => {
+        closeWindow(doBackwards);
+      }, 500);
+    } catch (e) {
+      Message.error(`${t("install_failed")}: ${e}`);
+    }
+  };
+
+  // Skill 安装取消
+  const handleSkillCancel = () => {
+    if (!skillInstallUuid) return;
+    agentClient.cancelSkillInstall(skillInstallUuid);
+    closeWindow(doBackwards);
+  };
+
+  const initAsync = async () => {
+    try {
+      const uuid = searchParams.get("uuid");
+      const fid = searchParams.get("file");
+
+      // 如果有 url 或 没有 uuid 和 file，跳过初始化逻辑
+      if (searchParams.get("url") || (!uuid && !fid)) {
+        return;
+      }
+      let info: ScriptInfo | undefined;
+      let isKnownUpdate: boolean = false;
+
+      if (window.history.length > 1) {
+        setDoBackwards(true);
+      }
+      setLoaded(true);
+
+      let paramOptions = {};
+      if (uuid) {
+        const cachedInfo = await scriptClient.getInstallInfo(uuid);
+        cleanupStaleInstallInfo(uuid);
+        if (cachedInfo?.[0]) isKnownUpdate = true;
+        info = cachedInfo?.[1] || undefined;
+        paramOptions = cachedInfo?.[2] || {};
+        if (!info) {
+          throw new Error("fetch script info failed");
+        }
+      } else {
+        // 检查是不是本地文件安装
+        if (!fid) {
+          throw new Error("url param - local file id is not found");
+        }
+        const fileHandle = await loadHandle(fid);
+        if (!fileHandle) {
+          throw new Error("invalid file access - fileHandle is null");
+        }
+        const file = await fileHandle.getFile();
+        if (!file) {
+          throw new Error("invalid file access - file is null");
+        }
+        // 处理本地文件的安装流程
+        setLocalFileHandle((prev) => {
+          if (prev instanceof FileSystemFileHandle) unmountFileTrack(prev);
+          return fileHandle!;
+        });
+
+        // 刷新 timestamp, 使 10s~15s 后不会被立即清掉
+        intervalExecution(`${cIdKey}liveFileHandle`, () => saveHandle(fid, fileHandle), 5 * 60 * 1000, true);
+
+        const code = await file.text();
+        const metadata = parseMetadata(code);
+        if (!metadata) {
+          // 非 UserScript，尝试作为 CATTool 处理
+          const cattoolMeta = parseCATToolMetadata(code);
+          if (!cattoolMeta) {
+            throw new Error("parse script info failed");
+          }
+          info = createScriptInfo(uuidv4(), code, `file:///*from-local*/${file.name}`, "user", {} as SCMetadata);
+          info.cattool = true;
+        } else {
+          info = createScriptInfo(uuidv4(), code, `file:///*from-local*/${file.name}`, "user", metadata);
+        }
+      }
+
+      // CATTool 安装：只需解析元数据并展示
+      if (info.cattool) {
+        const toolMeta = parseCATToolMetadata(info.code);
+        if (!toolMeta) {
+          throw new Error("Invalid CATTool: missing or malformed ==CATTool== header");
+        }
+        setCattoolMetadata(toolMeta);
+        setScriptCode(info.code);
+        setScriptInfo(info);
+        return;
+      }
+
+      let prepare:
+        | { script: Script; oldScript?: Script; oldScriptCode?: string }
+        | { subscribe: Subscribe; oldSubscribe?: Subscribe };
+      let action: Script | Subscribe;
+
+      const { code, url } = info;
+      let oldVersion: string | undefined = undefined;
+      let diffCode: string | undefined = undefined;
+      if (info.userSubscribe) {
+        prepare = await prepareSubscribeByCode(code, url);
+        action = prepare.subscribe;
+        if (prepare.oldSubscribe) {
+          const oldSubscribeVersion = prepare.oldSubscribe.metadata.version?.[0];
+          oldVersion = typeof oldSubscribeVersion === "string" ? oldSubscribeVersion : "N/A";
+        }
+        diffCode = prepare.oldSubscribe?.code;
+      } else {
+        const knownUUID = isKnownUpdate ? info.uuid : undefined;
+        prepare = await prepareScriptByCode(code, url, knownUUID, false, undefined, paramOptions);
+        action = prepare.script;
+        if (prepare.oldScript) {
+          const oldScriptVersion = prepare.oldScript.metadata.version?.[0];
+          oldVersion = typeof oldScriptVersion === "string" ? oldScriptVersion : "N/A";
+        }
+        diffCode = prepare.oldScriptCode;
+      }
+      setScriptCode(code);
+      setDiffCode(diffCode);
+      setOldScriptVersion(typeof oldVersion === "string" ? oldVersion : null);
+      setIsUpdate(typeof oldVersion === "string");
+      setScriptInfo(info);
+      setUpsertScript(action);
+
+      // 检查是否需要显示后台运行提示
+      if (!info.userSubscribe) {
+        setShowBackgroundPrompt(await checkBackgroundPrompt(action as Script));
+      }
+    } catch (e: any) {
+      Message.error(t("script_info_load_failed") + " " + e.message);
+    } finally {
+      const delay = Math.floor(5000 * Math.random()) + 10000;
+      timeoutExecution(`${cIdKey}cleanupFileHandle`, cleanupOldHandles, delay);
+    }
+  };
+
+  useEffect(() => {
+    if (loaded) return;
+    if (skillInstallUuid) {
+      initSkillFromCache(skillInstallUuid);
+    } else if (cattoolInstallUuid) {
+      initCATToolFromApi(cattoolInstallUuid);
+    } else {
+      initAsync();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [searchParams, loaded]);
+
+  const metadataLive = useMemo(() => (scriptInfo?.metadata || {}) as SCMetadata, [scriptInfo]);
+
+  const permissions = useMemo(() => {
+    const permissions: Permission = [];
+
+    if (!scriptInfo) return permissions;
+
+    if (scriptInfo.userSubscribe) {
+      permissions.push({
+        label: t("subscribe_install_label"),
+        color: "#ff0000",
+        value: metadataLive.scripturl!,
+      });
+    }
+
+    if (metadataLive.match) {
+      permissions.push({ label: t("script_runs_in"), value: metadataLive.match });
+    }
+
+    if (metadataLive.connect) {
+      permissions.push({
+        label: t("script_has_full_access_to"),
+        color: "#F9925A",
+        value: metadataLive.connect,
+      });
+    }
+
+    if (metadataLive.require) {
+      permissions.push({ label: t("script_requires"), value: metadataLive.require });
+    }
+
+    return permissions;
+  }, [scriptInfo, metadataLive, t]);
+
+  const descriptionParagraph = useMemo(() => {
+    const ret: JSX.Element[] = [];
+
+    if (!scriptInfo) return ret;
+
+    const isCookie = metadataLive.grant?.some((val: string) => val === "GM_cookie");
+    if (isCookie) {
+      ret.push(
+        <Typography.Text type="error" key="cookie">
+          {t("cookie_warning")}
+        </Typography.Text>
+      );
+    }
+
+    if (metadataLive.crontab) {
+      ret.push(<Typography.Text key="crontab">{t("scheduled_script_description_title")}</Typography.Text>);
+      ret.push(
+        <div key="cronta-nexttime" className="tw-flex tw-flex-row tw-flex-wrap tw-gap-x-2">
+          <Typography.Text>{t("scheduled_script_description_description_expr")}</Typography.Text>
+          <Typography.Text code>{metadataLive.crontab[0]}</Typography.Text>
+          <Typography.Text>{t("scheduled_script_description_description_next")}</Typography.Text>
+          <Typography.Text code>{nextTimeDisplay(metadataLive.crontab[0])}</Typography.Text>
+        </div>
+      );
+    } else if (metadataLive.background) {
+      ret.push(<Typography.Text key="background">{t("background_script_description")}</Typography.Text>);
+    }
+
+    return ret;
+  }, [scriptInfo, metadataLive, t]);
+
+  const antifeatures: { [key: string]: { color: string; title: string; description: string } } = {
+    "referral-link": {
+      color: "purple",
+      title: t("antifeature_referral_link_title"),
+      description: t("antifeature_referral_link_description"),
+    },
+    ads: {
+      color: "orange",
+      title: t("antifeature_ads_title"),
+      description: t("antifeature_ads_description"),
+    },
+    payment: {
+      color: "magenta",
+      title: t("antifeature_payment_title"),
+      description: t("antifeature_payment_description"),
+    },
+    miner: {
+      color: "orangered",
+      title: t("antifeature_miner_title"),
+      description: t("antifeature_miner_description"),
+    },
+    membership: {
+      color: "blue",
+      title: t("antifeature_membership_title"),
+      description: t("antifeature_membership_description"),
+    },
+    tracking: {
+      color: "pinkpurple",
+      title: t("antifeature_tracking_title"),
+      description: t("antifeature_tracking_description"),
+    },
+  };
+
+  // 更新按钮文案和页面标题
+  useEffect(() => {
+    if (skillPreview) {
+      document.title = `${t("install_script")} - ${skillPreview.metadata.name} - ScriptCat`;
+      return;
+    }
+    if (scriptInfo?.cattool && cattoolMetadata) {
+      document.title = `${t("install_script")} - ${cattoolMetadata.name} - ScriptCat`;
+      return;
+    }
+    if (scriptInfo?.userSubscribe) {
+      setBtnText(isUpdate ? t("update_subscribe")! : t("install_subscribe"));
+    } else {
+      setBtnText(isUpdate ? t("update_script")! : t("install_script"));
+    }
+    if (upsertScript) {
+      document.title = `${!isUpdate ? t("install_script") : t("update_script")} - ${i18nName(upsertScript!)} - ScriptCat`;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isUpdate, scriptInfo, upsertScript, cattoolMetadata, t]);
+
+  // 设置脚本状态
+  useEffect(() => {
+    if (upsertScript) {
+      setEnable(upsertScript.status === SCRIPT_STATUS_ENABLE);
+    }
+  }, [upsertScript]);
+
+  const handleInstall = async (options: { closeAfterInstall?: boolean; noMoreUpdates?: boolean } = {}) => {
+    if (!upsertScript) {
+      Message.error(t("script_info_load_failed")!);
+      return;
+    }
+
+    const { closeAfterInstall: shouldClose = true, noMoreUpdates: disableUpdates = false } = options;
+
+    try {
+      if (scriptInfo?.userSubscribe) {
+        await subscribeClient.install(upsertScript as Subscribe);
+        Message.success(t("subscribe_success")!);
+        setBtnText(t("subscribe_success")!);
+      } else {
+        if (disableUpdates && upsertScript) {
+          (upsertScript as Script).checkUpdate = false;
+        }
+        await scriptClient.install({ script: upsertScript as Script, code: scriptCode });
+        if (isUpdate) {
+          Message.success(t("install.update_success")!);
+          setBtnText(t("install.update_success")!);
+        } else {
+          if (disableUpdates && upsertScript) {
+            (upsertScript as Script).checkUpdate = false;
+          }
+          if ((upsertScript as Script).ignoreVersion) (upsertScript as Script).ignoreVersion = "";
+          await scriptClient.install({ script: upsertScript as Script, code: scriptCode });
+          if (isUpdate) {
+            Message.success(t("install.update_success")!);
+            setBtnText(t("install.update_success")!);
+          } else {
+            Message.success(t("install_success")!);
+            setBtnText(t("install_success")!);
+          }
+        }
+      }
+
+      if (shouldClose) {
+        setTimeout(() => {
+          closeWindow(doBackwards);
+        }, 500);
+      }
+    } catch (e) {
+      const errorMessage = scriptInfo?.userSubscribe ? t("subscribe_failed") : t("install_failed");
+      Message.error(`${errorMessage}: ${e}`);
+    }
+  };
+
+  const handleClose = (options?: { noMoreUpdates: boolean }) => {
+    const { noMoreUpdates = false } = options || {};
+    if (noMoreUpdates && scriptInfo && !scriptInfo.userSubscribe) {
+      scriptClient.setCheckUpdateUrl(scriptInfo.uuid, false);
+    }
+    closeWindow(doBackwards);
+  };
+
+  const handleCATToolInstall = async () => {
+    try {
+      await agentClient.installCATTool(scriptCode);
+      Message.success(t("install_success")!);
+      setTimeout(() => {
+        closeWindow(doBackwards);
+      }, 500);
+    } catch (e) {
+      Message.error(`${t("install_failed")}: ${e}`);
+    }
+  };
+
+  const handleInstallBasic = () => handleInstall();
+  const handleInstallCloseAfterInstall = () => handleInstall({ closeAfterInstall: false });
+  const handleInstallNoMoreUpdates = () => handleInstall({ noMoreUpdates: true });
+  const handleStatusChange = (checked: boolean) => {
+    setUpsertScript((script) => {
+      if (!script) {
+        return script;
+      }
+      script.status = checked ? SCRIPT_STATUS_ENABLE : SCRIPT_STATUS_DISABLE;
+      setEnable(checked);
+      return script;
+    });
+  };
+  const handleCloseBasic = () => handleClose();
+  const handleCloseNoMoreUpdates = () => handleClose({ noMoreUpdates: true });
+  const setWatchFileClick = () => {
+    setWatchFile((prev) => !prev);
+  };
+
+  const fileWatchMessageId = `id_${Math.random()}`;
+
+  async function onWatchFileCodeChanged(this: FTInfo, code: string, hideInfo: boolean = false) {
+    if (this.uuid !== scriptInfo?.uuid) return;
+    if (this.fileName !== localFileHandle?.name) return;
+    setScriptCode(code);
+    const uuid = (upsertScript as Script)?.uuid;
+    if (!uuid) {
+      throw new Error("uuid is undefined");
+    }
+    try {
+      const newScript = await getUpdatedNewScript(uuid, code);
+      await installOrUpdateScript(newScript, code);
+    } catch (e) {
+      Message.error({
+        id: fileWatchMessageId,
+        content: t("install_failed") + ": " + e,
+      });
+      return;
+    }
+    if (!hideInfo) {
+      Message.info({
+        id: fileWatchMessageId,
+        content: `${t("last_updated")}: ${dayFormat()}`,
+        duration: 3000,
+        closable: true,
+        showIcon: true,
+      });
+    }
+  }
+
+  async function onWatchFileError() {
+    setWatchFile(false);
+  }
+
+  const memoWatchFile = useMemo(() => {
+    return `${watchFile}.${scriptInfo?.uuid}.${localFileHandle?.name}`;
+  }, [watchFile, scriptInfo, localFileHandle]);
+
+  const setupWatchFile = async (uuid: string, fileName: string, handle: FileSystemFileHandle) => {
+    try {
+      const code = `${scriptCode}`;
+      await installOrUpdateScript(upsertScript as Script, code);
+      setDiffCode(`${code}`);
+      const ftInfo: FTInfo = {
+        uuid,
+        fileName,
+        setCode: onWatchFileCodeChanged,
+        onFileError: onWatchFileError,
+      };
+      startFileTrack(handle, ftInfo);
+      const file = await handle.getFile();
+      const currentCode = await file.text();
+      if (currentCode !== code) {
+        ftInfo.setCode(currentCode, true);
+      }
+    } catch (e: any) {
+      Message.error(`${e.message}`);
+      console.warn(e);
+    }
+  };
+
+  useEffect(() => {
+    if (!watchFile || !localFileHandle) {
+      return;
+    }
+    const [handle] = [localFileHandle];
+    unmountFileTrack(handle);
+    const uuid = scriptInfo?.uuid;
+    const fileName = handle?.name;
+    if (!uuid || !fileName) {
+      return;
+    }
+    setupWatchFile(uuid, fileName, handle);
+    return () => {
+      unmountFileTrack(handle);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [memoWatchFile]);
+
+  // 检查是否有 uuid 或 file
+  const searchParamUrl = searchParams.get("url");
+  const hasValidSourceParam =
+    !searchParamUrl &&
+    !!(searchParams.get("uuid") || searchParams.get("file") || cattoolInstallUuid || skillInstallUuid);
+
+  const urlHref = useMemo(() => {
+    if (searchParamUrl) {
+      try {
+        const idx = location.search.indexOf("url=");
+        const rawUrl = idx !== -1 ? location.search.slice(idx + 4) : searchParamUrl;
+        const urlObject = new URL(rawUrl);
+        if (urlObject.protocol && urlObject.hostname && urlObject.pathname) {
+          return rawUrl;
+        }
+      } catch {
+        // ignored
+      }
+    }
+    return "";
+  }, [searchParamUrl]);
+
+  const [fetchingState, setFetchingState] = useState({
+    loadingStatus: "",
+    errorStatus: "",
+  });
+
+  const loadURLAsync = async (url: string) => {
+    const fetchValidScript = async () => {
+      const result = await fetchScriptBody(url, {
+        onProgress: (info: { receivedLength: number }) => {
+          setFetchingState((prev) => ({
+            ...prev,
+            loadingStatus: t("downloading_status_text", { bytes: formatBytes(info.receivedLength) }),
+          }));
+        },
+      });
+      if (result.code && result.metadata) {
+        return { result, url } as const;
+      }
+      throw new Error(t("install_page_load_failed"));
+    };
+
+    try {
+      const { result, url } = await fetchValidScript();
+      const { code, metadata } = result;
+      const isCATTool = "cattool" in result && result.cattool === true;
+
+      const uuid = uuidv4();
+      const info = createScriptInfo(uuid, code, url, "user", metadata);
+      if (isCATTool) {
+        info.cattool = true;
+      }
+      const scriptData = [false, info];
+
+      await cacheInstance.set(`${CACHE_KEY_SCRIPT_INFO}${uuid}`, scriptData);
+
+      setSearchParams(new URLSearchParams(`?uuid=${uuid}`), { replace: true });
+    } catch (err: any) {
+      setFetchingState((prev) => ({
+        ...prev,
+        loadingStatus: "",
+        errorStatus: `${err?.message || err}`,
+      }));
+    }
+  };
+
+  const handleUrlChangeAndFetch = (targetUrlHref: string) => {
+    setFetchingState((prev) => ({
+      ...prev,
+      loadingStatus: t("install_page_please_wait"),
+    }));
+    loadURLAsync(targetUrlHref);
+  };
+
+  // 有 url 的话下载内容
+  useEffect(() => {
+    if (urlHref) handleUrlChangeAndFetch(urlHref);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [urlHref]);
+
+  return {
+    // 状态
+    enable,
+    btnText,
+    scriptCode,
+    scriptInfo,
+    upsertScript,
+    diffCode,
+    oldScriptVersion,
+    isUpdate,
+    localFileHandle,
+    showBackgroundPrompt,
+    setShowBackgroundPrompt,
+    cattoolMetadata,
+    cattoolSourceScriptName,
+    cattoolIsUpdate,
+    watchFile,
+    metadataLive,
+    permissions,
+    descriptionParagraph,
+    antifeatures,
+    hasValidSourceParam,
+    urlHref,
+    fetchingState,
+    // 事件处理
+    handleInstallBasic,
+    handleInstallCloseAfterInstall,
+    handleInstallNoMoreUpdates,
+    handleStatusChange,
+    handleCloseBasic,
+    handleCloseNoMoreUpdates,
+    handleCATToolInstall,
+    handleCATToolApiInstall,
+    handleCATToolApiCancel,
+    cattoolInstallUuid,
+    setWatchFileClick,
+    // Skill 安装
+    skillPreview,
+    skillInstallUuid,
+    handleSkillInstall,
+    handleSkillCancel,
+    // i18n
+    t,
+  };
+}
+
+export type InstallData = ReturnType<typeof useInstallData>;
diff --git a/src/pages/install/index.css b/src/pages/install/index.css
index b54e8fd9b..820eac7e4 100644
--- a/src/pages/install/index.css
+++ b/src/pages/install/index.css
@@ -1,108 +1,123 @@
 .monaco-diff-editor .diffOverview {
-	background: var(--vscode-editorGutter-background);
+  background: var(--vscode-editorGutter-background);
 }
 
 #install-app-container {
-	display: flex;
-	flex-direction: column;
-	min-height: calc(100vh - 50px);
-	box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  min-height: calc(100vh - 50px);
+  box-sizing: border-box;
 }
 
 #show-code-container {
-	display: block;
-	height: calc( 100% - 44px );
-	padding: 2px 2px;
-	position: relative;
-	box-sizing: border-box;
-	margin: 0;
-	border: 0;
-	flex-grow: 1;
-	flex-shrink: 0;
-	contain: strict;
+  display: block;
+  height: calc(100% - 44px);
+  padding: 2px 2px;
+  position: relative;
+  box-sizing: border-box;
+  margin: 0;
+  border: 0;
+  flex-grow: 1;
+  flex-shrink: 0;
+  contain: strict;
 }
 
-#show-code { /* 配合 .sc-inset-0 */
-	margin: 0px;
-	padding: 0px;
-	border: 0px;
-	overflow: hidden;
-	border: 1px solid var(--color-neutral-5);
-	box-sizing: border-box;
-	position: absolute;
-	background: #071119;
+#show-code {
+  /* 配合 .sc-inset-0 */
+  margin: 0px;
+  padding: 0px;
+  border: 0px;
+  overflow: hidden;
+  border: 1px solid var(--color-neutral-5);
+  box-sizing: border-box;
+  position: absolute;
+  background: #071119;
 }
 
 .downloading {
-	display: flex;
-	flex-direction: row;
-	flex-wrap: wrap;
-	column-gap: 4px;
-	align-items: center;
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  column-gap: 4px;
+  align-items: center;
 }
 
 .error-message {
-	color: red;
+  color: red;
 }
 
 .error-message:empty {
-	display: none;
+  display: none;
 }
 
 .error-message::before {
-	content: "ERROR: ";
+  content: "ERROR: ";
 }
 
 /* https://css-loaders.com/dots/ */
 .loader {
-	width: 60px;
-	aspect-ratio: 2;
-	--_g: no-repeat radial-gradient(circle closest-side, currentColor 90%, rgba(0,0,0,0));
-	background: var(--_g) 0% 50%, var(--_g) 50% 50%, var(--_g) 100% 50%;
-	background-size: calc(100%/3) 50%;
-	animation: l3 1s infinite linear;
-	transform: scale(0.5);
+  width: 60px;
+  aspect-ratio: 2;
+  --_g: no-repeat radial-gradient(circle closest-side, currentColor 90%, rgba(0, 0, 0, 0));
+  background:
+    var(--_g) 0% 50%,
+    var(--_g) 50% 50%,
+    var(--_g) 100% 50%;
+  background-size: calc(100% / 3) 50%;
+  animation: l3 1s infinite linear;
+  transform: scale(0.5);
 }
 
 @keyframes l3 {
-	20% {
-		background-position: 0% 0%, 50% 50%, 100% 50%
-	}
-
-	40% {
-		background-position: 0% 100%, 50% 0%, 100% 50%
-	}
-
-	60% {
-		background-position: 0% 50%, 50% 100%, 100% 0%
-	}
-
-	80% {
-		background-position: 0% 50%, 50% 50%, 100% 100%
-	}
-
+  20% {
+    background-position:
+      0% 0%,
+      50% 50%,
+      100% 50%;
+  }
+
+  40% {
+    background-position:
+      0% 100%,
+      50% 0%,
+      100% 50%;
+  }
+
+  60% {
+    background-position:
+      0% 50%,
+      50% 100%,
+      100% 0%;
+  }
+
+  80% {
+    background-position:
+      0% 50%,
+      50% 50%,
+      100% 100%;
+  }
 }
 
 .tag-container {
-	inline-size: min-content;
-	align-content: flex-start;
-	justify-items: flex-end;
-	justify-content: flex-end;
+  inline-size: min-content;
+  align-content: flex-start;
+  justify-items: flex-end;
+  justify-content: flex-end;
 }
 
 .tag-container .arco-tag {
-	flex-grow: 1;
-	text-align: center;
+  flex-grow: 1;
+  text-align: center;
 }
 
 div.permission-entry span.arco-typography {
-	line-height: 1rem;
-	padding: 0;
-	margin: 0;
+  line-height: 1rem;
+  padding: 0;
+  margin: 0;
 }
 
 div.permission-entry {
-	line-height: 1.2rem;
-	padding: 0;
-	margin: 0;
+  line-height: 1.2rem;
+  padding: 0;
+  margin: 0;
 }
diff --git a/src/pages/install/utils.ts b/src/pages/install/utils.ts
new file mode 100644
index 000000000..d18adfd3d
--- /dev/null
+++ b/src/pages/install/utils.ts
@@ -0,0 +1,154 @@
+import { parseMetadata } from "@App/pkg/utils/script";
+import { detectEncoding, bytesDecode } from "@App/pkg/utils/encoding";
+import { parseCATToolMetadata } from "@App/pkg/utils/cattool";
+import { cacheInstance } from "@App/app/cache";
+import { CACHE_KEY_SCRIPT_INFO } from "@App/app/cache_key";
+import { timeoutExecution } from "@App/pkg/utils/timer";
+import type { SCMetadata } from "@App/app/repo/scripts";
+
+export const cIdKey = `(cid_${Math.random()})`;
+
+export const backgroundPromptShownKey = "background_prompt_shown";
+
+// Types
+export interface PermissionItem {
+  label: string;
+  color?: string;
+  value: string[];
+}
+
+export type Permission = PermissionItem[];
+
+export const closeWindow = (doBackwards: boolean) => {
+  if (doBackwards) {
+    history.go(-1);
+  } else {
+    window.close();
+  }
+};
+
+export const fetchScriptBody = async (url: string, { onProgress }: { [key: string]: any }) => {
+  let origin;
+  try {
+    origin = new URL(url).origin;
+  } catch {
+    throw new Error(`Invalid url: ${url}`);
+  }
+  const response = await fetch(url, {
+    headers: {
+      "Cache-Control": "no-cache",
+      Accept: "text/javascript,application/javascript,text/plain,application/octet-stream,application/force-download",
+      // 参考：加权 Accept-Encoding 值说明
+      // https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Encoding#weighted_accept-encoding_values
+      "Accept-Encoding": "br;q=1.0, gzip;q=0.8, *;q=0.1",
+      Origin: origin,
+    },
+    referrer: origin + "/",
+  });
+
+  if (!response.ok) {
+    throw new Error(`Fetch failed with status ${response.status}`);
+  }
+
+  if (!response.body || !response.headers) {
+    throw new Error("No response body or headers");
+  }
+  if (response.headers.get("content-type")?.includes("text/html")) {
+    throw new Error("Response is text/html, not a valid UserScript");
+  }
+
+  const reader = response.body.getReader();
+
+  // 读取数据
+  let receivedLength = 0; // 当前已接收的长度
+  const chunks = []; // 已接收的二进制分片数组（用于组装正文）
+  while (true) {
+    const { done, value } = await reader.read();
+
+    if (done) {
+      break;
+    }
+
+    chunks.push(value);
+    receivedLength += value.length;
+    onProgress?.({ receivedLength });
+  }
+
+  // 合并分片（chunks）
+  const chunksAll = new Uint8Array(receivedLength);
+  let position = 0;
+  for (const chunk of chunks) {
+    chunksAll.set(chunk, position);
+    position += chunk.length;
+  }
+
+  // 检测编码：优先使用 Content-Type，回退到 chardet（仅检测前16KB）
+  const contentType = response.headers.get("content-type");
+  const encode = detectEncoding(chunksAll, contentType);
+
+  // 使用检测到的 charset 解码
+  let code;
+  try {
+    code = bytesDecode(encode, chunksAll);
+  } catch (e: any) {
+    console.warn(`Failed to decode response with charset ${encode}: ${e.message}`);
+    // 回退到 UTF-8
+    code = new TextDecoder("utf-8").decode(chunksAll);
+  }
+
+  const metadata = parseMetadata(code);
+  // 如果不是 UserScript，检测是否为 CATTool
+  if (!metadata) {
+    const cattoolMeta = parseCATToolMetadata(code);
+    if (cattoolMeta) {
+      return { code, metadata: {} as SCMetadata, cattool: true };
+    }
+    throw new Error("parse script info failed");
+  }
+
+  return { code, metadata };
+};
+
+export const cleanupStaleInstallInfo = (uuid: string) => {
+  // 页面打开时不清除当前uuid，每30秒更新一次记录
+  const f = () => {
+    cacheInstance.tx(`scriptInfoKeeps`, (val: Record<string, number> | undefined, tx) => {
+      val = val || {};
+      val[uuid] = Date.now();
+      tx.set(val);
+    });
+  };
+  f();
+  setInterval(f, 30_000);
+
+  // 页面打开后清除旧记录
+  const delay = Math.floor(5000 * Math.random()) + 10000; // 使用随机时间避免浏览器重启时大量Tabs同时执行清除
+  timeoutExecution(
+    `${cIdKey}cleanupStaleInstallInfo`,
+    () => {
+      cacheInstance
+        .tx(`scriptInfoKeeps`, (val: Record<string, number> | undefined, tx) => {
+          const now = Date.now();
+          const keeps = new Set<string>();
+          const out: Record<string, number> = {};
+          for (const [k, ts] of Object.entries(val ?? {})) {
+            if (ts > 0 && now - ts < 60_000) {
+              keeps.add(`${CACHE_KEY_SCRIPT_INFO}${k}`);
+              out[k] = ts;
+            }
+          }
+          tx.set(out);
+          return keeps;
+        })
+        .then(async (keeps) => {
+          const list = await cacheInstance.list();
+          const filtered = list.filter((key) => key.startsWith(CACHE_KEY_SCRIPT_INFO) && !keeps.has(key));
+          if (filtered.length) {
+            // 清理缓存
+            cacheInstance.dels(filtered);
+          }
+        });
+    },
+    delay
+  );
+};
diff --git a/src/pages/options/index.css b/src/pages/options/index.css
index d7b98634f..492767d8c 100644
--- a/src/pages/options/index.css
+++ b/src/pages/options/index.css
@@ -79,7 +79,6 @@ h6.arco-typography {
   .arco-table-border .arco-table-th:first-child,
   .arco-table-border .arco-table-td:first-child {
     border-left: none !important;
-
   }
 
   /* 卡片视图样式 */
@@ -107,5 +106,4 @@ h6.arco-typography {
       grid-template-columns: 1fr;
     }
   }
-
-}
\ No newline at end of file
+}
diff --git a/src/pages/options/routes/Agent.tsx b/src/pages/options/routes/Agent.tsx
new file mode 100644
index 000000000..8c9d2cf1e
--- /dev/null
+++ b/src/pages/options/routes/Agent.tsx
@@ -0,0 +1,25 @@
+import { Route, Routes } from "react-router-dom";
+import AgentProvider from "./AgentProvider";
+import AgentChat from "./AgentChat";
+import AgentMcp from "./AgentMcp";
+import AgentOPFS from "./AgentOPFS";
+import AgentSkills from "./AgentSkills";
+import AgentCATool from "./AgentCATool";
+import AgentTasks from "./AgentTasks";
+
+function Agent() {
+  return (
+    <Routes>
+      <Route path="/chat" element={<AgentChat />} />
+      <Route path="/provider" element={<AgentProvider />} />
+      <Route path="/mcp" element={<AgentMcp />} />
+      <Route path="/skills" element={<AgentSkills />} />
+      <Route path="/catool" element={<AgentCATool />} />
+      <Route path="/tasks" element={<AgentTasks />} />
+      <Route path="/opfs" element={<AgentOPFS />} />
+      <Route path="*" element={<AgentChat />} />
+    </Routes>
+  );
+}
+
+export default Agent;
diff --git a/src/pages/options/routes/AgentCATool.tsx b/src/pages/options/routes/AgentCATool.tsx
new file mode 100644
index 000000000..8ac7d5da9
--- /dev/null
+++ b/src/pages/options/routes/AgentCATool.tsx
@@ -0,0 +1,263 @@
+import { Button, Card, Drawer, Empty, Message, Popconfirm, Space, Tag, Typography } from "@arco-design/web-react";
+import { IconCode, IconDelete, IconEye } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { useCallback, useEffect, useState } from "react";
+import type { CATToolRecord } from "@App/app/service/agent/types";
+import type { CATToolSummary } from "@App/app/repo/cattool_repo";
+import { CATToolRepo } from "@App/app/repo/cattool_repo";
+import { agentClient } from "@App/pages/store/features/script";
+
+const catToolRepo = new CATToolRepo();
+
+function CATToolCard({
+  tool,
+  onDetail,
+  onDelete,
+  t,
+}: {
+  tool: CATToolSummary;
+  onDetail: () => void;
+  onDelete: () => void;
+  t: (key: string, opts?: Record<string, string | number>) => string;
+}) {
+  return (
+    <div className="tw-group tw-relative tw-rounded-xl tw-p-5 tw-transition-all tw-duration-200 tw-cursor-default tw-bg-[var(--color-bg-2)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.06)] hover:tw-shadow-[0_4px_16px_rgba(0,0,0,0.1)]">
+      {/* Header */}
+      <div className="tw-flex tw-items-start tw-justify-between tw-mb-3">
+        <div className="tw-flex tw-items-center tw-gap-3">
+          <div className="tw-w-10 tw-h-10 tw-rounded-lg tw-flex tw-items-center tw-justify-center tw-text-xs tw-font-bold tw-shrink-0 tw-bg-[rgb(var(--orange-1))] tw-text-[rgb(var(--orange-6))]">
+            <IconCode />
+          </div>
+          <div className="tw-flex tw-flex-col tw-gap-0.5">
+            <Typography.Text className="tw-font-semibold tw-text-base !tw-mb-0">{tool.name}</Typography.Text>
+            {tool.description && (
+              <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+                {tool.description}
+              </Typography.Text>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Params */}
+      {tool.params.length > 0 && (
+        <div className="tw-flex tw-flex-wrap tw-gap-1.5 tw-mb-3">
+          {tool.params.map((p) => (
+            <Tag key={p.name} size="small" color={p.required ? "arcoblue" : "gray"}>
+              {p.required ? p.name : `${p.name}?`}
+            </Tag>
+          ))}
+        </div>
+      )}
+
+      {/* Grants */}
+      {tool.grants.length > 0 && (
+        <div className="tw-flex tw-flex-wrap tw-gap-1.5 tw-mb-3">
+          {tool.grants.map((g) => (
+            <Tag key={g} size="small" color="orange">
+              {g}
+            </Tag>
+          ))}
+        </div>
+      )}
+
+      {/* Source */}
+      {tool.sourceScriptName && (
+        <div className="tw-text-xs tw-text-[var(--color-text-3)] tw-mb-3">
+          {t("agent_catool_source")}
+          {": "}
+          {tool.sourceScriptName}
+        </div>
+      )}
+
+      {/* Install time */}
+      <div className="tw-text-xs tw-text-[var(--color-text-3)] tw-mb-3">
+        {t("agent_catool_installed_at")}
+        {": "}
+        {new Date(tool.installtime).toLocaleString()}
+      </div>
+
+      {/* Actions */}
+      <div className="tw-flex tw-items-center tw-justify-end tw-gap-0.5 tw-pt-3 tw-border-t tw-border-solid tw-border-[var(--color-border-1)] tw-border-x-0 tw-border-b-0 tw-opacity-60 group-hover:tw-opacity-100 tw-transition-opacity">
+        <Button type="text" size="small" icon={<IconEye />} onClick={onDetail}>
+          {t("agent_catool_detail")}
+        </Button>
+        <Popconfirm title={t("agent_catool_delete_confirm", { name: tool.name })} onOk={onDelete}>
+          <Button type="text" size="small" status="danger" icon={<IconDelete />}>
+            {t("agent_catool_delete")}
+          </Button>
+        </Popconfirm>
+      </div>
+    </div>
+  );
+}
+
+function CATToolDetailDrawer({
+  visible,
+  tool,
+  onClose,
+}: {
+  visible: boolean;
+  tool: CATToolRecord | null;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation();
+
+  if (!tool) return null;
+
+  return (
+    <Drawer width={560} title={tool.name} visible={visible} onCancel={onClose} footer={null} unmountOnExit>
+      <Space direction="vertical" size={16} className="tw-w-full">
+        {/* Description */}
+        {tool.description && (
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">
+              {t("agent_catool_description")}
+            </div>
+            <Typography.Text type="secondary">{tool.description}</Typography.Text>
+          </div>
+        )}
+
+        {/* Params */}
+        {tool.params.length > 0 && (
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_catool_params")} {"("}
+              {tool.params.length}
+              {")"}
+            </div>
+            <div className="tw-flex tw-flex-col tw-gap-2">
+              {tool.params.map((p) => (
+                <div key={p.name} className="tw-rounded-lg tw-p-3 tw-bg-[var(--color-fill-1)]">
+                  <div className="tw-flex tw-items-center tw-gap-2 tw-mb-1">
+                    <Typography.Text className="tw-font-semibold tw-text-sm !tw-mb-0">{p.name}</Typography.Text>
+                    <Tag size="small">{p.type}</Tag>
+                    {p.required && (
+                      <Tag size="small" color="arcoblue">
+                        {"required"}
+                      </Tag>
+                    )}
+                  </div>
+                  {p.description && (
+                    <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+                      {p.description}
+                    </Typography.Text>
+                  )}
+                  {p.enum && p.enum.length > 0 && (
+                    <div className="tw-mt-1 tw-flex tw-gap-1 tw-flex-wrap">
+                      {p.enum.map((v) => (
+                        <Tag key={v} size="small" color="green">
+                          {v}
+                        </Tag>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Grants */}
+        {tool.grants.length > 0 && (
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_catool_grants")} {"("}
+              {tool.grants.length}
+              {")"}
+            </div>
+            <div className="tw-flex tw-flex-wrap tw-gap-1.5">
+              {tool.grants.map((g) => (
+                <Tag key={g} color="orange">
+                  {g}
+                </Tag>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {/* Code */}
+        <div>
+          <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+            {t("agent_catool_code")}
+          </div>
+          <pre className="tw-rounded-lg tw-p-3 tw-bg-[var(--color-fill-1)] tw-text-xs tw-font-mono tw-overflow-auto tw-max-h-80 tw-whitespace-pre-wrap tw-break-all">
+            {tool.code}
+          </pre>
+        </div>
+
+        {/* Source */}
+        {tool.sourceScriptName && (
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">
+              {t("agent_catool_source")}
+            </div>
+            <Typography.Text type="secondary">{tool.sourceScriptName}</Typography.Text>
+          </div>
+        )}
+      </Space>
+    </Drawer>
+  );
+}
+
+function AgentCATool() {
+  const { t } = useTranslation();
+  const [tools, setTools] = useState<CATToolSummary[]>([]);
+  const [detailVisible, setDetailVisible] = useState(false);
+  const [detailTool, setDetailTool] = useState<CATToolRecord | null>(null);
+
+  const loadTools = useCallback(async () => {
+    const list = await catToolRepo.listTools();
+    setTools(list);
+  }, []);
+
+  useEffect(() => {
+    loadTools();
+  }, [loadTools]);
+
+  const handleDetail = async (name: string) => {
+    const record = await catToolRepo.getTool(name);
+    if (record) {
+      setDetailTool(record);
+      setDetailVisible(true);
+    }
+  };
+
+  const handleDelete = async (name: string) => {
+    try {
+      await agentClient.removeCATTool(name);
+      Message.success(t("agent_catool_delete_success"));
+      loadTools();
+    } catch (e: any) {
+      Message.error(e.message || String(e));
+    }
+  };
+
+  return (
+    <Space className="tw-w-full tw-h-full tw-overflow-auto tw-relative" direction="vertical">
+      <Card title={t("agent_catool_title")} bordered={false}>
+        {tools.length === 0 ? (
+          <div className="tw-py-12">
+            <Empty description={t("agent_catool_empty")} />
+          </div>
+        ) : (
+          <div className="tw-grid tw-grid-cols-1 md:tw-grid-cols-2 tw-gap-4">
+            {tools.map((tool) => (
+              <CATToolCard
+                key={tool.name}
+                tool={tool}
+                onDetail={() => handleDetail(tool.name)}
+                onDelete={() => handleDelete(tool.name)}
+                t={t}
+              />
+            ))}
+          </div>
+        )}
+      </Card>
+
+      <CATToolDetailDrawer visible={detailVisible} tool={detailTool} onClose={() => setDetailVisible(false)} />
+    </Space>
+  );
+}
+
+export default AgentCATool;
diff --git a/src/pages/options/routes/AgentChat/AttachmentRenderers.tsx b/src/pages/options/routes/AgentChat/AttachmentRenderers.tsx
new file mode 100644
index 000000000..dc95178e3
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/AttachmentRenderers.tsx
@@ -0,0 +1,137 @@
+import { useState, useEffect, useCallback } from "react";
+import { IconDownload, IconEye } from "@arco-design/web-react/icon";
+import type { Attachment, AudioBlock } from "@App/app/service/agent/types";
+import { AgentChatRepo } from "@App/app/repo/agent_chat";
+
+const repo = new AgentChatRepo();
+
+// 图片附件组件：从 OPFS 懒加载并展示
+export function AttachmentImage({ attachment }: { attachment: Attachment }) {
+  const [blobUrl, setBlobUrl] = useState<string | null>(null);
+  const [preview, setPreview] = useState(false);
+
+  useEffect(() => {
+    let revoked = false;
+    repo.getAttachment(attachment.id).then((blob) => {
+      if (blob && !revoked) {
+        setBlobUrl(URL.createObjectURL(blob));
+      }
+    });
+    return () => {
+      revoked = true;
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [attachment.id]);
+
+  if (!blobUrl) {
+    return (
+      <div className="tw-w-40 tw-h-24 tw-bg-[var(--color-fill-2)] tw-rounded tw-flex tw-items-center tw-justify-center tw-text-xs tw-text-[var(--color-text-4)]">
+        {"Loading..."}
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div className="tw-relative tw-inline-block tw-group tw-cursor-pointer" onClick={() => setPreview(true)}>
+        <img
+          src={blobUrl}
+          alt={attachment.name}
+          className="tw-max-w-xs tw-max-h-48 tw-rounded tw-border tw-border-solid tw-border-[var(--color-border-1)] tw-object-contain"
+        />
+        <div className="tw-absolute tw-inset-0 tw-bg-black/0 group-hover:tw-bg-black/20 tw-rounded tw-flex tw-items-center tw-justify-center tw-transition-colors">
+          <IconEye
+            className="tw-text-white tw-opacity-0 group-hover:tw-opacity-100 tw-transition-opacity"
+            style={{ fontSize: 20 }}
+          />
+        </div>
+      </div>
+      {/* 全屏预览 */}
+      {preview && (
+        <div
+          className="tw-fixed tw-inset-0 tw-z-[1000] tw-bg-black/80 tw-flex tw-items-center tw-justify-center tw-cursor-pointer"
+          onClick={() => setPreview(false)}
+        >
+          <img
+            src={blobUrl}
+            alt={attachment.name}
+            className="tw-max-w-[90vw] tw-max-h-[90vh] tw-object-contain"
+            onClick={(e) => e.stopPropagation()}
+          />
+        </div>
+      )}
+    </>
+  );
+}
+
+// 文件附件组件：显示文件信息和下载按钮
+export function AttachmentFile({ attachment }: { attachment: Attachment }) {
+  const handleDownload = useCallback(async () => {
+    const blob = await repo.getAttachment(attachment.id);
+    if (!blob) return;
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = attachment.name;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+  }, [attachment.id, attachment.name]);
+
+  const sizeText = attachment.size
+    ? attachment.size < 1024
+      ? `${attachment.size} B`
+      : attachment.size < 1024 * 1024
+        ? `${(attachment.size / 1024).toFixed(1)} KB`
+        : `${(attachment.size / (1024 * 1024)).toFixed(1)} MB`
+    : "";
+
+  return (
+    <div
+      className="tw-inline-flex tw-items-center tw-gap-2 tw-px-3 tw-py-2 tw-rounded-lg tw-bg-[var(--color-fill-1)] tw-border tw-border-solid tw-border-[var(--color-border-1)] tw-cursor-pointer hover:tw-bg-[var(--color-fill-2)] tw-transition-colors"
+      onClick={handleDownload}
+    >
+      <IconDownload style={{ fontSize: 14 }} className="tw-text-[var(--color-text-3)]" />
+      <div className="tw-flex tw-flex-col">
+        <span className="tw-text-xs tw-font-medium tw-text-[var(--color-text-2)]">{attachment.name}</span>
+        {sizeText && <span className="tw-text-[10px] tw-text-[var(--color-text-4)]">{sizeText}</span>}
+      </div>
+    </div>
+  );
+}
+
+// 音频附件组件：audio 播放器
+export function AttachmentAudio({ block }: { block: AudioBlock }) {
+  const [blobUrl, setBlobUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    let revoked = false;
+    repo.getAttachment(block.attachmentId).then((blob) => {
+      if (blob && !revoked) {
+        setBlobUrl(URL.createObjectURL(blob));
+      }
+    });
+    return () => {
+      revoked = true;
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [block.attachmentId]);
+
+  if (!blobUrl) {
+    return (
+      <div className="tw-h-10 tw-bg-[var(--color-fill-2)] tw-rounded tw-flex tw-items-center tw-justify-center tw-text-xs tw-text-[var(--color-text-4)] tw-px-4">
+        {"Loading audio..."}
+      </div>
+    );
+  }
+
+  return (
+    <div className="tw-my-1">
+      {block.name && <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-mb-1 tw-block">{block.name}</span>}
+      <audio controls src={blobUrl} className="tw-max-w-xs" />
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/ChatArea.tsx b/src/pages/options/routes/AgentChat/ChatArea.tsx
new file mode 100644
index 000000000..b8bd943c8
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/ChatArea.tsx
@@ -0,0 +1,417 @@
+import { useCallback, useEffect, useRef } from "react";
+import { useTranslation } from "react-i18next";
+import { Message as ArcoMessage } from "@arco-design/web-react";
+import { IconRobot } from "@arco-design/web-react/icon";
+import type { AgentModelConfig, SkillSummary, ContentBlock, MessageContent } from "@App/app/service/agent/types";
+import type { ChatMessage, ChatStreamEvent } from "@App/app/service/agent/types";
+import { getTextContent } from "@App/app/service/agent/content_utils";
+import { UserMessageItem, AssistantMessageGroup } from "./MessageItem";
+import ChatInput from "./ChatInput";
+import { useMessages, useStreamingChat, deleteMessages, clearMessages } from "./hooks";
+import {
+  mergeToolResults,
+  groupMessages,
+  computeRegenerateAction,
+  computeEditAction,
+  computeUserRegenerateAction,
+  findNextAssistantGroupIndex,
+  type MessageGroup,
+} from "./chat_utils";
+
+function genId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+// 欢迎界面
+function WelcomeScreen({ hasConversation }: { hasConversation: boolean }) {
+  const { t } = useTranslation();
+
+  return (
+    <div className="tw-flex tw-flex-col tw-items-center tw-justify-center tw-h-full tw-py-20 tw-select-none">
+      <div className="tw-w-16 tw-h-16 tw-rounded-2xl tw-bg-gradient-to-br tw-from-[rgb(var(--arcoblue-1))] tw-to-[rgb(var(--arcoblue-2))] tw-flex tw-items-center tw-justify-center tw-mb-5 tw-shadow-sm">
+        <IconRobot style={{ fontSize: 32, color: "rgb(var(--arcoblue-6))" }} />
+      </div>
+      <h2 className="tw-text-lg tw-font-semibold tw-text-[var(--color-text-1)] tw-mb-2 tw-mt-0">
+        {hasConversation ? t("agent_chat_input_placeholder") : t("agent_chat_no_conversations")}
+      </h2>
+      <p className="tw-text-sm tw-text-[var(--color-text-3)] tw-mb-6 tw-mt-0">
+        {hasConversation
+          ? t("agent_chat_welcome_hint") || "Ask me anything about your scripts"
+          : t("agent_chat_welcome_start") || "Create a conversation to get started"}
+      </p>
+    </div>
+  );
+}
+
+export default function ChatArea({
+  conversationId,
+  models,
+  selectedModelId,
+  onModelChange,
+  onConversationTitleChange,
+  skills,
+  selectedSkills,
+  onSkillsChange,
+}: {
+  conversationId: string;
+  models: AgentModelConfig[];
+  selectedModelId: string;
+  onModelChange: (id: string) => void;
+  onConversationTitleChange?: () => void;
+  skills?: SkillSummary[];
+  selectedSkills?: "auto" | string[];
+  onSkillsChange?: (skills: "auto" | string[]) => void;
+}) {
+  const { t } = useTranslation();
+  const { messages, setMessages, loadMessages } = useMessages(conversationId);
+  const { isStreaming, sendMessage, stopGeneration } = useStreamingChat();
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const streamingMsgRef = useRef<ChatMessage | null>(null);
+  // 计时相关
+  const sendStartTimeRef = useRef<number>(0);
+  const firstTokenRecordedRef = useRef<boolean>(false);
+  const firstTokenMsRef = useRef<number | undefined>(undefined);
+
+  // 自动滚动到底部
+  const scrollToBottom = useCallback(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, []);
+
+  useEffect(() => {
+    scrollToBottom();
+  }, [messages, scrollToBottom]);
+
+  // 流式期间累积的非文本 blocks（content_block_complete 事件）
+  const pendingBlocksRef = useRef<ContentBlock[]>([]);
+
+  // 创建流式事件回调（提取公共逻辑）
+  const createStreamCallback = () => {
+    pendingBlocksRef.current = [];
+    return (event: ChatStreamEvent) => {
+      const msg = streamingMsgRef.current;
+      if (!msg) return;
+
+      switch (event.type) {
+        case "content_delta":
+          if (!firstTokenRecordedRef.current) {
+            firstTokenRecordedRef.current = true;
+            firstTokenMsRef.current = Date.now() - sendStartTimeRef.current;
+          }
+          // streaming 期间 content 始终为 string
+          if (typeof msg.content === "string") {
+            msg.content += event.delta;
+          }
+          break;
+        case "thinking_delta":
+          if (!msg.thinking) msg.thinking = { content: "" };
+          msg.thinking.content += event.delta;
+          break;
+        case "tool_call_start":
+          if (!msg.toolCalls) msg.toolCalls = [];
+          msg.toolCalls.push({ ...event.toolCall, status: "running" });
+          break;
+        case "tool_call_delta":
+          if (msg.toolCalls?.length) {
+            const lastTc = msg.toolCalls[msg.toolCalls.length - 1];
+            lastTc.arguments += event.delta;
+          }
+          break;
+        case "tool_call_complete": {
+          const tc = msg.toolCalls?.find((t) => t.id === event.id);
+          if (tc) {
+            tc.status = "completed";
+            tc.result = event.result;
+            tc.attachments = event.attachments;
+          }
+          break;
+        }
+        case "content_block_start":
+          // 非文本 block 开始，暂不处理（等 complete 时处理）
+          break;
+        case "content_block_complete":
+          // 非文本 block 完成，加入 pending 列表
+          pendingBlocksRef.current.push(event.block);
+          break;
+        case "new_message": {
+          // 在开始新消息前，合并 pending blocks 到当前消息
+          if (pendingBlocksRef.current.length > 0) {
+            const textContent = typeof msg.content === "string" ? msg.content : "";
+            const blocks: ContentBlock[] = [];
+            if (textContent) blocks.push({ type: "text", text: textContent });
+            blocks.push(...pendingBlocksRef.current);
+            msg.content = blocks;
+            pendingBlocksRef.current = [];
+          }
+
+          const newMsg: ChatMessage = {
+            id: genId(),
+            conversationId,
+            role: "assistant",
+            content: "",
+            modelId: selectedModelId,
+            createtime: Date.now(),
+          };
+          streamingMsgRef.current = newMsg;
+          setMessages((prev) => [...prev, newMsg]);
+          return;
+        }
+        case "error":
+          msg.error = event.message;
+          break;
+        case "done":
+          if (event.usage) msg.usage = event.usage;
+          if (event.durationMs != null) msg.durationMs = event.durationMs;
+          if (firstTokenMsRef.current != null) msg.firstTokenMs = firstTokenMsRef.current;
+          // 合并 pending blocks 到最终消息
+          if (pendingBlocksRef.current.length > 0) {
+            const textContent = typeof msg.content === "string" ? msg.content : "";
+            const blocks: ContentBlock[] = [];
+            if (textContent) blocks.push({ type: "text", text: textContent });
+            blocks.push(...pendingBlocksRef.current);
+            msg.content = blocks;
+            pendingBlocksRef.current = [];
+          }
+          break;
+      }
+
+      setMessages((prev) => {
+        const updated = [...prev];
+        const idx = updated.findIndex((m) => m.id === msg.id);
+        if (idx >= 0) {
+          updated[idx] = { ...msg };
+        }
+        return updated;
+      });
+    };
+  };
+
+  const createDoneCallback = () => {
+    return async () => {
+      streamingMsgRef.current = null;
+      await loadMessages();
+      onConversationTitleChange?.();
+    };
+  };
+
+  // 初始化流式请求的公共逻辑
+  const startStreaming = (baseMessages: ChatMessage[], content: MessageContent, skipUserMessage?: boolean) => {
+    sendStartTimeRef.current = Date.now();
+    firstTokenRecordedRef.current = false;
+    firstTokenMsRef.current = undefined;
+
+    const newMessages = [...baseMessages];
+    if (!skipUserMessage) {
+      newMessages.push({
+        id: genId(),
+        conversationId,
+        role: "user",
+        content,
+        createtime: Date.now(),
+      });
+    }
+
+    const assistantMsg: ChatMessage = {
+      id: genId(),
+      conversationId,
+      role: "assistant",
+      content: "",
+      modelId: selectedModelId,
+      createtime: Date.now(),
+    };
+    streamingMsgRef.current = assistantMsg;
+    newMessages.push(assistantMsg);
+
+    setMessages(newMessages);
+    sendMessage(
+      conversationId,
+      content,
+      createStreamCallback(),
+      createDoneCallback(),
+      selectedModelId,
+      skipUserMessage
+    );
+  };
+
+  // 用 ref 保存 startStreaming 的最新引用，避免 useCallback 闭包陈旧
+  const startStreamingRef = useRef(startStreaming);
+  startStreamingRef.current = startStreaming;
+
+  // 发送消息（支持指定 content 和可选的已有消息列表用于重新回答）
+  const handleSend = async (content: MessageContent, existingMessages?: ChatMessage[]) => {
+    if (!conversationId || !selectedModelId) return;
+
+    // 处理 /new 命令：清空对话上下文
+    if (typeof content === "string" && content.trim() === "/new") {
+      await clearMessages(conversationId);
+      setMessages([]);
+      return;
+    }
+
+    startStreaming(existingMessages ?? messages, content);
+  };
+
+  // 复制消息组的文本内容到剪贴板
+  const handleCopy = useCallback(
+    (groupMessages: ChatMessage[]) => {
+      const text = groupMessages
+        .map((m) => getTextContent(m.content))
+        .filter(Boolean)
+        .join("\n\n");
+      navigator.clipboard.writeText(text).then(() => {
+        ArcoMessage.success(t("agent_chat_copy_success"));
+      });
+    },
+    [t]
+  );
+
+  // 重新回答：删除当前 assistant 消息组，用上一条用户消息重新请求
+  const handleRegenerate = useCallback(
+    async (groups: MessageGroup[], groupIndex: number) => {
+      if (isStreaming) return;
+
+      const action = computeRegenerateAction(groups, groupIndex, messages);
+      if (!action) return;
+
+      await deleteMessages(conversationId, action.idsToDelete);
+      setMessages(action.remainingMessages);
+
+      // 通过 ref 调用最新的 startStreaming，避免闭包陈旧
+      startStreamingRef.current(action.remainingMessages, action.userContent);
+    },
+    [conversationId, isStreaming, messages, setMessages]
+  );
+
+  // 重新生成用户消息的回复：保留用户消息，只删除后续回复
+  const handleRegenerateUserMessage = useCallback(
+    async (messageId: string) => {
+      if (isStreaming) return;
+
+      const action = computeUserRegenerateAction(messageId, messages);
+      if (!action) return;
+
+      if (action.idsToDelete.length > 0) {
+        await deleteMessages(conversationId, action.idsToDelete);
+      }
+
+      setMessages(action.remainingMessages);
+
+      // skipUserMessage=true：用户消息已在 remainingMessages 中，不需要重新创建
+      startStreamingRef.current(action.remainingMessages, action.userContent, action.skipUserMessage);
+    },
+    [conversationId, isStreaming, messages, setMessages]
+  );
+
+  // 删除整轮对话（用户消息 + assistant 消息组）
+  const handleDeleteRound = useCallback(
+    async (groups: MessageGroup[], groupIndex: number) => {
+      if (isStreaming) return;
+
+      const group = groups[groupIndex];
+      if (group.type !== "assistant") return;
+
+      const idsToDelete: string[] = group.messages.map((m) => m.id);
+
+      // 找到前面的用户消息
+      for (let i = groupIndex - 1; i >= 0; i--) {
+        if (groups[i].type === "user") {
+          idsToDelete.push((groups[i] as { type: "user"; message: ChatMessage }).message.id);
+          break;
+        }
+      }
+
+      // 从持久化存储中删除（这里要删除原始消息，包括 tool 角色消息）
+      const allToolCallIds = group.messages.flatMap((m) => m.toolCalls?.map((tc) => tc.id) || []);
+      const originalToolMsgIds = messages
+        .filter((m) => m.role === "tool" && m.toolCallId && allToolCallIds.includes(m.toolCallId))
+        .map((m) => m.id);
+      idsToDelete.push(...originalToolMsgIds);
+
+      await deleteMessages(conversationId, idsToDelete);
+      loadMessages();
+    },
+    [conversationId, isStreaming, messages, loadMessages]
+  );
+
+  // 编辑用户消息并重新发送：删除该消息及其后的所有消息
+  const handleEditMessage = useCallback(
+    async (messageId: string, newContent: string) => {
+      if (isStreaming) return;
+
+      const action = computeEditAction(messageId, messages);
+      if (!action) return;
+
+      await deleteMessages(conversationId, action.idsToDelete);
+      setMessages(action.remainingMessages);
+
+      // 通过 ref 调用最新的 startStreaming
+      startStreamingRef.current(action.remainingMessages, newContent);
+    },
+    [conversationId, isStreaming, messages, setMessages]
+  );
+
+  const noModel = models.length === 0;
+  const showWelcome = !conversationId || (messages.length === 0 && !isStreaming);
+  const mergedMessages = mergeToolResults(messages);
+  const messageGroups = groupMessages(mergedMessages);
+
+  return (
+    <div className="tw-flex tw-flex-col tw-flex-1 tw-min-w-0 tw-h-full tw-bg-[var(--color-bg-1)]">
+      {/* 消息列表 */}
+      <div className="tw-flex-1 tw-overflow-y-auto tw-px-4 agent-chat-scroll">
+        <div className="tw-max-w-3xl tw-mx-auto">
+          {showWelcome ? (
+            <WelcomeScreen hasConversation={!!conversationId} />
+          ) : (
+            messageGroups.map((group, groupIndex) =>
+              group.type === "user" ? (
+                <UserMessageItem
+                  key={group.message.id}
+                  message={group.message}
+                  isStreaming={isStreaming}
+                  onEdit={(newContent) => handleEditMessage(group.message.id, newContent)}
+                  onRegenerate={
+                    findNextAssistantGroupIndex(messageGroups, groupIndex) != null ||
+                    groupIndex === messageGroups.length - 1
+                      ? () => handleRegenerateUserMessage(group.message.id)
+                      : undefined
+                  }
+                />
+              ) : (
+                <AssistantMessageGroup
+                  key={group.messages[0].id}
+                  messages={group.messages}
+                  streamingId={isStreaming ? streamingMsgRef.current?.id : undefined}
+                  isStreaming={isStreaming}
+                  streamStartTime={sendStartTimeRef.current || undefined}
+                  onCopy={() => handleCopy(group.messages)}
+                  onRegenerate={() => handleRegenerate(messageGroups, groupIndex)}
+                  onDelete={() => handleDeleteRound(messageGroups, groupIndex)}
+                />
+              )
+            )
+          )}
+          <div ref={messagesEndRef} />
+        </div>
+      </div>
+
+      {/* 输入区域 */}
+      <ChatInput
+        models={models}
+        selectedModelId={selectedModelId}
+        onModelChange={onModelChange}
+        onSend={handleSend}
+        onStop={stopGeneration}
+        isStreaming={isStreaming}
+        disabled={noModel || !conversationId}
+        skills={skills}
+        selectedSkills={selectedSkills}
+        onSkillsChange={onSkillsChange}
+      />
+      {noModel && (
+        <div className="tw-text-center tw-text-xs tw-text-[var(--color-text-3)] tw-pb-2">
+          {t("agent_chat_no_model")}
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/ChatInput.tsx b/src/pages/options/routes/AgentChat/ChatInput.tsx
new file mode 100644
index 000000000..adb8418c9
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/ChatInput.tsx
@@ -0,0 +1,161 @@
+import { useState, useRef, useEffect } from "react";
+import { Select } from "@arco-design/web-react";
+import { IconSend, IconPause } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import type { AgentModelConfig, SkillSummary, MessageContent } from "@App/app/service/agent/types";
+
+export default function ChatInput({
+  models,
+  selectedModelId,
+  onModelChange,
+  onSend,
+  onStop,
+  isStreaming,
+  disabled,
+  skills,
+  selectedSkills,
+  onSkillsChange,
+}: {
+  models: AgentModelConfig[];
+  selectedModelId: string;
+  onModelChange: (id: string) => void;
+  onSend: (content: MessageContent) => void;
+  onStop: () => void;
+  isStreaming: boolean;
+  disabled?: boolean;
+  skills?: SkillSummary[];
+  selectedSkills?: "auto" | string[];
+  onSkillsChange?: (skills: "auto" | string[]) => void;
+}) {
+  const { t } = useTranslation();
+  const [input, setInput] = useState("");
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // 自动调整高度
+  useEffect(() => {
+    const el = textareaRef.current;
+    if (el) {
+      el.style.height = "auto";
+      el.style.height = Math.min(el.scrollHeight, 200) + "px";
+    }
+  }, [input]);
+
+  const handleSend = () => {
+    const trimmed = input.trim();
+    if (!trimmed || isStreaming || disabled) return;
+    onSend(trimmed);
+    setInput("");
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    // 忽略输入法组合状态中的回车（如中文输入法确认候选词）
+    if (e.nativeEvent.isComposing) return;
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      handleSend();
+    }
+  };
+
+  const canSend = input.trim() && !disabled;
+
+  return (
+    <div className="tw-px-4 tw-pb-4 tw-pt-2 tw-bg-[var(--color-bg-1)]">
+      <div className="tw-max-w-3xl tw-mx-auto">
+        <div className="tw-rounded-2xl tw-border tw-border-solid tw-border-[var(--color-border-2)] tw-bg-[var(--color-bg-2)] tw-shadow-[0_2px_12px_rgba(0,0,0,0.06)] tw-overflow-hidden">
+          {/* 输入区域 */}
+          <div className="tw-px-4 tw-pt-3 tw-pb-2">
+            <textarea
+              ref={textareaRef}
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              onKeyDown={handleKeyDown}
+              placeholder={t("agent_chat_input_placeholder")}
+              disabled={disabled}
+              rows={1}
+              className="tw-w-full tw-resize-none tw-border-none tw-outline-none tw-bg-transparent tw-text-sm tw-text-[var(--color-text-1)] tw-min-h-[24px] tw-max-h-[200px] placeholder:tw-text-[var(--color-text-4)]"
+            />
+          </div>
+
+          {/* 底部工具栏 */}
+          <div className="tw-flex tw-items-center tw-justify-between tw-px-3 tw-pb-2">
+            <div className="tw-flex tw-items-center tw-gap-2">
+              <Select
+                size="mini"
+                value={selectedModelId}
+                onChange={onModelChange}
+                triggerProps={{ autoAlignPopupWidth: false }}
+                getPopupContainer={() => document.body}
+                className="!tw-w-auto !tw-min-w-[100px]"
+                bordered={false}
+              >
+                {models.map((m) => (
+                  <Select.Option key={m.id} value={m.id}>
+                    {m.name}
+                  </Select.Option>
+                ))}
+              </Select>
+              {skills && skills.length > 0 && onSkillsChange && (
+                <Select
+                  size="mini"
+                  mode="multiple"
+                  value={selectedSkills === "auto" ? ["__auto__"] : selectedSkills || []}
+                  onChange={(val: string[]) => {
+                    const wasAuto = selectedSkills === "auto";
+                    if (!wasAuto && val.includes("__auto__")) {
+                      // 切换到 auto 模式
+                      onSkillsChange("auto");
+                    } else if (wasAuto && val.length > 1) {
+                      // 从 auto 模式选择了具体 skill，取消 auto
+                      onSkillsChange(val.filter((v) => v !== "__auto__"));
+                    } else {
+                      onSkillsChange(val.filter((v) => v !== "__auto__"));
+                    }
+                  }}
+                  triggerProps={{ autoAlignPopupWidth: false }}
+                  getPopupContainer={() => document.body}
+                  className="!tw-w-auto !tw-min-w-[80px] !tw-max-w-[200px]"
+                  bordered={false}
+                  placeholder="Skills"
+                  allowClear
+                >
+                  <Select.Option key="__auto__" value="__auto__">
+                    {"Auto (all)"}
+                  </Select.Option>
+                  {skills.map((s) => (
+                    <Select.Option key={s.name} value={s.name}>
+                      {s.name}
+                    </Select.Option>
+                  ))}
+                </Select>
+              )}
+              <span className="tw-text-xs tw-text-[var(--color-text-4)] tw-hidden sm:tw-inline">
+                {"Shift+Enter"} {t("agent_chat_newline")}
+              </span>
+            </div>
+
+            {isStreaming ? (
+              <button
+                onClick={onStop}
+                className="tw-w-8 tw-h-8 tw-rounded-full tw-flex tw-items-center tw-justify-center tw-bg-[rgb(var(--orange-6))] tw-text-white tw-border-none tw-cursor-pointer tw-transition-all hover:tw-opacity-80 tw-shadow-sm"
+              >
+                <IconPause style={{ fontSize: 14 }} />
+              </button>
+            ) : (
+              <button
+                onClick={handleSend}
+                disabled={!canSend}
+                className={`tw-w-8 tw-h-8 tw-rounded-full tw-flex tw-items-center tw-justify-center tw-border-none tw-cursor-pointer tw-transition-all tw-shadow-sm ${
+                  canSend
+                    ? "tw-bg-[rgb(var(--arcoblue-6))] tw-text-white hover:tw-opacity-80"
+                    : "tw-bg-[var(--color-fill-3)] tw-text-[var(--color-text-4)] tw-cursor-not-allowed"
+                }`}
+              >
+                <IconSend style={{ fontSize: 14 }} />
+              </button>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/ContentBlockRenderer.tsx b/src/pages/options/routes/AgentChat/ContentBlockRenderer.tsx
new file mode 100644
index 000000000..40f32b401
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/ContentBlockRenderer.tsx
@@ -0,0 +1,47 @@
+import type { MessageContent, AudioBlock } from "@App/app/service/agent/types";
+import MarkdownRenderer from "./MarkdownRenderer";
+import { AttachmentImage, AttachmentFile, AttachmentAudio } from "./AttachmentRenderers";
+
+export default function ContentBlockRenderer({ content, className }: { content: MessageContent; className?: string }) {
+  if (typeof content === "string") {
+    return content ? <MarkdownRenderer content={content} /> : null;
+  }
+
+  return (
+    <div className={className}>
+      {content.map((block, i) => {
+        switch (block.type) {
+          case "text":
+            return block.text ? <MarkdownRenderer key={i} content={block.text} /> : null;
+          case "image":
+            return (
+              <AttachmentImage
+                key={i}
+                attachment={{
+                  id: block.attachmentId,
+                  type: "image",
+                  name: block.name || "image",
+                  mimeType: block.mimeType,
+                }}
+              />
+            );
+          case "file":
+            return (
+              <AttachmentFile
+                key={i}
+                attachment={{
+                  id: block.attachmentId,
+                  type: "file",
+                  name: block.name,
+                  mimeType: block.mimeType,
+                  size: block.size,
+                }}
+              />
+            );
+          case "audio":
+            return <AttachmentAudio key={i} block={block as AudioBlock} />;
+        }
+      })}
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/ConversationList.tsx b/src/pages/options/routes/AgentChat/ConversationList.tsx
new file mode 100644
index 000000000..037123cc1
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/ConversationList.tsx
@@ -0,0 +1,130 @@
+import { useState } from "react";
+import { Button, Input, Popconfirm, Empty } from "@arco-design/web-react";
+import { IconPlus, IconDelete, IconEdit, IconCheck, IconClose, IconMessage } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import type { Conversation } from "@App/app/service/agent/types";
+
+export default function ConversationList({
+  conversations,
+  activeId,
+  onSelect,
+  onCreate,
+  onDelete,
+  onRename,
+}: {
+  conversations: Conversation[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  onCreate: () => void;
+  onDelete: (id: string) => void;
+  onRename: (id: string, title: string) => void;
+}) {
+  const { t } = useTranslation();
+  const [editingId, setEditingId] = useState<string>("");
+  const [editValue, setEditValue] = useState("");
+  // 记录正在显示删除确认弹框的会话 ID，防止鼠标移开时按钮隐藏导致弹框消失
+  const [deletingId, setDeletingId] = useState<string>("");
+
+  const startRename = (conv: Conversation) => {
+    setEditingId(conv.id);
+    setEditValue(conv.title);
+  };
+
+  const confirmRename = () => {
+    if (editValue.trim() && editingId) {
+      onRename(editingId, editValue.trim());
+    }
+    setEditingId("");
+  };
+
+  return (
+    <div className="tw-flex tw-flex-col tw-h-full tw-w-[240px] tw-border-r tw-border-solid tw-border-[var(--color-border-2)] tw-border-y-0 tw-border-l-0 tw-bg-[var(--color-bg-1)]">
+      {/* 头部 */}
+      <div className="tw-p-3 tw-border-b tw-border-solid tw-border-[var(--color-border-2)] tw-border-x-0 tw-border-t-0">
+        <Button
+          long
+          icon={<IconPlus />}
+          size="small"
+          onClick={onCreate}
+          className="!tw-border-dashed !tw-text-[var(--color-text-2)] hover:!tw-text-[rgb(var(--arcoblue-6))] hover:!tw-border-[rgb(var(--arcoblue-6))]"
+        >
+          {t("agent_chat_new")}
+        </Button>
+      </div>
+
+      {/* 列表 */}
+      <div className="tw-flex-1 tw-overflow-y-auto tw-py-1 agent-chat-scroll">
+        {conversations.length === 0 ? (
+          <div className="tw-py-8">
+            <Empty description={t("agent_chat_no_conversations")} />
+          </div>
+        ) : (
+          conversations.map((conv) => (
+            <div
+              key={conv.id}
+              className={`agent-conversation-item tw-group tw-flex tw-items-center tw-gap-2 tw-mx-2 tw-my-0.5 tw-px-3 tw-py-2.5 tw-rounded-lg tw-cursor-pointer ${
+                conv.id === activeId
+                  ? "active tw-bg-[var(--color-fill-2)] tw-text-[var(--color-text-1)]"
+                  : "hover:tw-bg-[var(--color-fill-1)] tw-text-[var(--color-text-2)]"
+              }`}
+              onClick={() => onSelect(conv.id)}
+            >
+              {editingId === conv.id ? (
+                <div className="tw-flex tw-items-center tw-gap-1 tw-flex-1 tw-min-w-0">
+                  <Input
+                    size="mini"
+                    value={editValue}
+                    onChange={setEditValue}
+                    onPressEnter={confirmRename}
+                    autoFocus
+                    className="tw-flex-1"
+                  />
+                  <Button type="text" size="mini" icon={<IconCheck />} onClick={confirmRename} />
+                  <Button type="text" size="mini" icon={<IconClose />} onClick={() => setEditingId("")} />
+                </div>
+              ) : (
+                <>
+                  <IconMessage className="tw-text-sm tw-text-[var(--color-text-3)] tw-shrink-0" />
+                  <span className="tw-flex-1 tw-truncate tw-text-sm">{conv.title}</span>
+                  <div
+                    className={`tw-items-center tw-shrink-0 ${
+                      deletingId === conv.id ? "tw-flex" : "tw-hidden group-hover:tw-flex"
+                    }`}
+                  >
+                    <Button
+                      type="text"
+                      size="mini"
+                      icon={<IconEdit />}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        startRename(conv);
+                      }}
+                    />
+                    <Popconfirm
+                      title={t("agent_chat_delete_confirm")}
+                      position="top"
+                      getPopupContainer={() => document.body}
+                      onVisibleChange={(visible) => {
+                        setDeletingId(visible ? conv.id : "");
+                      }}
+                      onOk={() => onDelete(conv.id)}
+                      onCancel={(e) => e?.stopPropagation()}
+                    >
+                      <Button
+                        type="text"
+                        size="mini"
+                        status="danger"
+                        icon={<IconDelete />}
+                        onClick={(e) => e.stopPropagation()}
+                      />
+                    </Popconfirm>
+                  </div>
+                </>
+              )}
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/MarkdownRenderer.tsx b/src/pages/options/routes/AgentChat/MarkdownRenderer.tsx
new file mode 100644
index 000000000..2d7882061
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/MarkdownRenderer.tsx
@@ -0,0 +1,87 @@
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import rehypeHighlight from "rehype-highlight";
+import type { ReactNode } from "react";
+import { useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Tooltip } from "@arco-design/web-react";
+import { IconCopy, IconCheck } from "@arco-design/web-react/icon";
+import "highlight.js/styles/github.css";
+
+// 从 React 节点树中递归提取纯文本，用于复制功能
+function extractText(node: ReactNode): string {
+  if (node == null || typeof node === "boolean") return "";
+  if (typeof node === "string" || typeof node === "number") return String(node);
+  if (Array.isArray(node)) return node.map(extractText).join("");
+  if (typeof node === "object" && "props" in node) {
+    return extractText(node.props.children);
+  }
+  return "";
+}
+
+function CodeBlock({ children, className }: { children: ReactNode; className?: string }) {
+  const { t } = useTranslation();
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout>>();
+
+  const language = className?.replace("hljs language-", "").replace("language-", "") || "";
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(extractText(children)).then(() => {
+      setCopied(true);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setCopied(false), 2000);
+    });
+  };
+
+  return (
+    <div className="tw-relative tw-group tw-my-3">
+      <div className="tw-flex tw-items-center tw-justify-between tw-px-4 tw-py-1.5 tw-bg-[var(--color-fill-3)] tw-rounded-t-lg tw-text-xs tw-text-[var(--color-text-3)]">
+        <span className="tw-font-medium">{language}</span>
+        <Tooltip content={copied ? t("agent_chat_copy_success") : t("agent_chat_copy")}>
+          <button
+            onClick={handleCopy}
+            className="tw-flex tw-items-center tw-gap-1 tw-px-2 tw-py-0.5 tw-rounded tw-border-none tw-bg-transparent tw-text-[var(--color-text-3)] tw-cursor-pointer hover:tw-text-[var(--color-text-1)] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors tw-text-xs"
+          >
+            {copied ? <IconCheck style={{ fontSize: 12 }} /> : <IconCopy style={{ fontSize: 12 }} />}
+          </button>
+        </Tooltip>
+      </div>
+      <pre className="!tw-mt-0 !tw-rounded-t-none !tw-rounded-b-lg !tw-bg-[var(--color-fill-2)]">
+        <code className={className}>{children}</code>
+      </pre>
+    </div>
+  );
+}
+
+export default function MarkdownRenderer({ content }: { content: string }) {
+  return (
+    <div className="ai-markdown-body">
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={[rehypeHighlight]}
+        components={{
+          pre({ children }) {
+            return <>{children}</>;
+          },
+          code({ className, children, ...props }) {
+            const isInline = !className;
+            if (isInline) {
+              return (
+                <code
+                  className="tw-px-1.5 tw-py-0.5 tw-rounded tw-bg-[var(--color-fill-2)] tw-text-[rgb(var(--arcoblue-6))] tw-text-[0.9em]"
+                  {...props}
+                >
+                  {children}
+                </code>
+              );
+            }
+            return <CodeBlock className={className}>{children}</CodeBlock>;
+          },
+        }}
+      >
+        {content}
+      </ReactMarkdown>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/MessageItem.tsx b/src/pages/options/routes/AgentChat/MessageItem.tsx
new file mode 100644
index 000000000..03b336362
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/MessageItem.tsx
@@ -0,0 +1,254 @@
+import { useState, useRef, useEffect } from "react";
+import type { ChatMessage } from "@App/app/service/agent/types";
+import ContentBlockRenderer from "./ContentBlockRenderer";
+import ThinkingBlock from "./ThinkingBlock";
+import ToolCallBlock from "./ToolCallBlock";
+import MessageToolbar from "./MessageToolbar";
+import { Message as ArcoMessage, Tooltip } from "@arco-design/web-react";
+import { IconRobot, IconUser, IconEdit, IconCopy, IconRefresh, IconExclamationCircleFill } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { getTextContent } from "@App/app/service/agent/content_utils";
+
+// 单条助手消息内容（无头像、无外层包装）
+function AssistantMessageContent({ message, isStreaming }: { message: ChatMessage; isStreaming?: boolean }) {
+  const { t } = useTranslation();
+  return (
+    <div className="tw-text-sm tw-min-w-0 tw-w-full">
+      {/* Thinking 块 */}
+      {message.thinking?.content && <ThinkingBlock content={message.thinking.content} />}
+
+      {/* 主内容 */}
+      {(typeof message.content === "string" ? message.content : message.content.length > 0) && (
+        <div className={isStreaming ? "agent-streaming-cursor" : ""}>
+          <ContentBlockRenderer content={message.content} />
+        </div>
+      )}
+
+      {/* 流式指示 */}
+      {isStreaming && !getTextContent(message.content) && !message.thinking?.content && (
+        <div className="tw-flex tw-items-center tw-gap-2 tw-py-2">
+          <div className="agent-tool-spinner" />
+          <span className="tw-text-[var(--color-text-3)] tw-text-xs">{t("agent_chat_streaming")}</span>
+        </div>
+      )}
+
+      {/* 工具调用 */}
+      {message.toolCalls?.map((tc) => (
+        <ToolCallBlock key={tc.id} toolCall={tc} />
+      ))}
+
+      {/* 错误 */}
+      {message.error && (
+        <div className="agent-error-block">
+          <IconExclamationCircleFill className="agent-error-icon" />
+          <span style={{ minWidth: 0, wordBreak: "break-word" }}>{message.error}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// 用户消息
+export function UserMessageItem({
+  message,
+  onEdit,
+  onRegenerate,
+  isStreaming,
+}: {
+  message: ChatMessage;
+  onEdit?: (newContent: string) => void;
+  onRegenerate?: () => void;
+  isStreaming?: boolean;
+}) {
+  const { t } = useTranslation();
+  const [editing, setEditing] = useState(false);
+  const [editContent, setEditContent] = useState(getTextContent(message.content));
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  // 进入编辑模式时聚焦并调整高度
+  useEffect(() => {
+    if (editing && textareaRef.current) {
+      const el = textareaRef.current;
+      el.focus();
+      el.style.height = "auto";
+      el.style.height = el.scrollHeight + "px";
+      // 光标移到末尾
+      el.setSelectionRange(el.value.length, el.value.length);
+    }
+  }, [editing]);
+
+  const handleStartEdit = () => {
+    setEditContent(getTextContent(message.content));
+    setEditing(true);
+  };
+
+  const handleCancel = () => {
+    setEditing(false);
+    setEditContent(getTextContent(message.content));
+  };
+
+  const handleSave = () => {
+    const trimmed = editContent.trim();
+    if (!trimmed) return;
+    setEditing(false);
+    onEdit?.(trimmed);
+  };
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(getTextContent(message.content)).then(() => {
+      ArcoMessage.success(t("agent_chat_copy_success"));
+    });
+  };
+
+  const canInteract = !isStreaming;
+
+  return (
+    <div className="agent-message-item tw-flex tw-gap-3 tw-py-5 tw-flex-row-reverse">
+      <div className="tw-w-8 tw-h-8 tw-rounded-full tw-flex tw-items-center tw-justify-center tw-shrink-0 tw-shadow-sm tw-bg-gradient-to-br tw-from-[rgb(var(--arcoblue-5))] tw-to-[rgb(var(--arcoblue-6))] tw-text-white">
+        <IconUser style={{ fontSize: 14 }} />
+      </div>
+      <div className="tw-flex tw-flex-col tw-items-end tw-max-w-[80%] tw-min-w-0">
+        {editing ? (
+          // 编辑模式：圆角容器，与消息气泡同宽
+          <div className="agent-edit-container tw-rounded-2xl tw-rounded-tr-sm tw-overflow-hidden tw-min-w-[240px]">
+            <textarea
+              ref={textareaRef}
+              className="tw-w-full tw-min-h-[40px] tw-max-h-[200px] tw-px-4 tw-pt-3 tw-pb-2 tw-bg-transparent tw-text-[var(--color-text-1)] tw-text-sm tw-resize-none tw-outline-none tw-border-none tw-leading-relaxed"
+              value={editContent}
+              onChange={(e) => {
+                setEditContent(e.target.value);
+                e.target.style.height = "auto";
+                e.target.style.height = e.target.scrollHeight + "px";
+              }}
+              onKeyDown={(e) => {
+                if (e.key === "Escape") handleCancel();
+                if (e.key === "Enter" && !e.shiftKey) {
+                  e.preventDefault();
+                  handleSave();
+                }
+              }}
+            />
+            <div className="tw-flex tw-items-center tw-justify-between tw-px-3 tw-pb-2">
+              <span className="tw-text-xs tw-text-[var(--color-text-4)]">
+                {"Escape"} {t("agent_chat_cancel_edit")}
+              </span>
+              <div className="tw-flex tw-gap-1.5">
+                <button
+                  className="tw-px-3 tw-py-1.5 tw-rounded-lg tw-text-xs tw-font-medium tw-border tw-border-solid tw-border-[var(--color-border-2)] tw-bg-[var(--color-bg-1)] tw-text-[var(--color-text-2)] tw-cursor-pointer hover:tw-bg-[var(--color-fill-2)] tw-transition-colors"
+                  onClick={handleCancel}
+                >
+                  {t("agent_chat_cancel_edit")}
+                </button>
+                <button
+                  className="tw-px-3 tw-py-1.5 tw-rounded-lg tw-text-xs tw-font-medium tw-border-none tw-bg-[rgb(var(--arcoblue-6))] tw-text-white tw-cursor-pointer hover:tw-bg-[rgb(var(--arcoblue-5))] tw-transition-colors tw-shadow-sm"
+                  onClick={handleSave}
+                >
+                  {t("agent_chat_save_and_send")}
+                </button>
+              </div>
+            </div>
+          </div>
+        ) : (
+          // 只读模式：消息气泡 + 底部工具条
+          <>
+            <div className="tw-px-4 tw-py-2.5 tw-rounded-2xl tw-rounded-tr-sm tw-bg-gradient-to-br tw-from-[rgb(var(--arcoblue-5))] tw-to-[rgb(var(--arcoblue-6))] tw-text-[var(--color-text-1)] dark:tw-text-white tw-text-sm tw-whitespace-pre-wrap tw-break-words tw-shadow-sm">
+              {getTextContent(message.content)}
+            </div>
+            {canInteract && (
+              <div className="agent-toolbar-actions tw-opacity-0 tw-transition-opacity tw-flex tw-items-center tw-mt-1 tw-gap-0.5">
+                <Tooltip content={t("agent_chat_copy_message")} mini position="bottom">
+                  <button
+                    className="tw-w-6 tw-h-6 tw-flex tw-items-center tw-justify-center tw-rounded tw-bg-transparent tw-border-none tw-cursor-pointer tw-text-[var(--color-text-3)] hover:tw-text-[var(--color-text-1)] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors"
+                    onClick={handleCopy}
+                  >
+                    <IconCopy style={{ fontSize: 13 }} />
+                  </button>
+                </Tooltip>
+                {onEdit && (
+                  <Tooltip content={t("agent_chat_edit_message")} mini position="bottom">
+                    <button
+                      className="tw-w-6 tw-h-6 tw-flex tw-items-center tw-justify-center tw-rounded tw-bg-transparent tw-border-none tw-cursor-pointer tw-text-[var(--color-text-3)] hover:tw-text-[var(--color-text-1)] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors"
+                      onClick={handleStartEdit}
+                    >
+                      <IconEdit style={{ fontSize: 13 }} />
+                    </button>
+                  </Tooltip>
+                )}
+                {onRegenerate && (
+                  <Tooltip content={t("agent_chat_regenerate")} mini position="bottom">
+                    <button
+                      className="tw-w-6 tw-h-6 tw-flex tw-items-center tw-justify-center tw-rounded tw-bg-transparent tw-border-none tw-cursor-pointer tw-text-[var(--color-text-3)] hover:tw-text-[var(--color-text-1)] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors"
+                      onClick={onRegenerate}
+                    >
+                      <IconRefresh style={{ fontSize: 13 }} />
+                    </button>
+                  </Tooltip>
+                )}
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// 助手消息组（连续的 assistant 消息共享一个头像）
+export function AssistantMessageGroup({
+  messages,
+  streamingId,
+  isStreaming,
+  streamStartTime,
+  onCopy,
+  onRegenerate,
+  onDelete,
+}: {
+  messages: ChatMessage[];
+  streamingId?: string;
+  isStreaming?: boolean;
+  streamStartTime?: number;
+  onCopy: () => void;
+  onRegenerate: () => void;
+  onDelete: () => void;
+}) {
+  // 从组内最后一条消息获取元数据（done 事件数据写在最后一条 assistant 消息上）
+  const lastMsg = messages[messages.length - 1];
+  const usage = lastMsg.usage;
+  const durationMs = lastMsg.durationMs;
+  const firstTokenMs = lastMsg.firstTokenMs;
+
+  // 统计组内所有 toolCalls 总数
+  const toolCallCount = messages.reduce((sum, m) => sum + (m.toolCalls?.length || 0), 0);
+
+  // 是否正在流式生成这个组
+  const isGroupStreaming = isStreaming && messages.some((m) => m.id === streamingId);
+
+  return (
+    <div className="agent-message-item tw-flex tw-gap-3 tw-py-5">
+      {/* 头像：只显示一次 */}
+      <div className="tw-w-8 tw-h-8 tw-rounded-full tw-flex tw-items-center tw-justify-center tw-shrink-0 tw-shadow-sm tw-bg-[var(--color-fill-2)] tw-text-[var(--color-text-2)]">
+        <IconRobot style={{ fontSize: 14 }} />
+      </div>
+
+      {/* 消息内容：连续的 assistant 消息纵向排列 */}
+      <div className="tw-flex tw-flex-col tw-max-w-[80%] tw-min-w-0 tw-gap-1">
+        {messages.map((msg) => (
+          <AssistantMessageContent key={msg.id} message={msg} isStreaming={streamingId === msg.id} />
+        ))}
+
+        {/* 工具条 */}
+        <MessageToolbar
+          usage={usage}
+          durationMs={durationMs}
+          firstTokenMs={firstTokenMs}
+          toolCallCount={toolCallCount}
+          isStreaming={isGroupStreaming}
+          streamStartTime={streamStartTime}
+          onCopy={onCopy}
+          onRegenerate={onRegenerate}
+          onDelete={onDelete}
+        />
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/MessageToolbar.tsx b/src/pages/options/routes/AgentChat/MessageToolbar.tsx
new file mode 100644
index 000000000..4039d8288
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/MessageToolbar.tsx
@@ -0,0 +1,164 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { Popconfirm, Tooltip } from "@arco-design/web-react";
+import { IconCopy, IconRefresh, IconDelete } from "@arco-design/web-react/icon";
+
+export type MessageToolbarProps = {
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+  };
+  durationMs?: number;
+  firstTokenMs?: number;
+  toolCallCount: number;
+  isStreaming?: boolean;
+  streamStartTime?: number;
+  onCopy: () => void;
+  onRegenerate: () => void;
+  onDelete: () => void;
+};
+
+// 格式化时长
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const min = Math.floor(ms / 60000);
+  const sec = Math.round((ms % 60000) / 1000);
+  return `${min}m${sec}s`;
+}
+
+// 格式化 token 数
+function formatTokens(n: number): string {
+  if (n < 1000) return `${n}`;
+  if (n < 10000) return `${(n / 1000).toFixed(1)}k`;
+  return `${Math.round(n / 1000)}k`;
+}
+
+// 分隔点
+function Dot() {
+  return <span className="tw-text-[var(--color-text-3)] tw-text-xs tw-mx-1">{"·"}</span>;
+}
+
+// 流式计时器
+function LiveTimer({ startTime }: { startTime: number }) {
+  const [elapsed, setElapsed] = useState(Date.now() - startTime);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setElapsed(Date.now() - startTime);
+    }, 100);
+    return () => clearInterval(timer);
+  }, [startTime]);
+
+  return (
+    <span className="tw-inline-flex tw-items-center tw-gap-1">
+      <span className="agent-tool-spinner" style={{ width: 10, height: 10, borderWidth: 1.5 }} />
+      <span>{formatDuration(elapsed)}</span>
+    </span>
+  );
+}
+
+// 操作按钮
+function ActionButton({ tooltip, onClick, children }: { tooltip: string; onClick: () => void; children: ReactNode }) {
+  return (
+    <Tooltip content={tooltip} mini>
+      <button
+        className="tw-w-6 tw-h-6 tw-flex tw-items-center tw-justify-center tw-rounded tw-bg-transparent tw-border-none tw-cursor-pointer tw-text-[var(--color-text-3)] hover:tw-text-[var(--color-text-1)] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors"
+        onClick={onClick}
+      >
+        {children}
+      </button>
+    </Tooltip>
+  );
+}
+
+export default function MessageToolbar({
+  usage,
+  durationMs,
+  firstTokenMs,
+  toolCallCount,
+  isStreaming,
+  streamStartTime,
+  onCopy,
+  onRegenerate,
+  onDelete,
+}: MessageToolbarProps) {
+  const { t } = useTranslation();
+
+  // 元数据片段
+  const metaParts: ReactNode[] = [];
+
+  if (isStreaming && streamStartTime) {
+    metaParts.push(
+      <span key="live" className="tw-inline-flex tw-items-center">
+        <LiveTimer startTime={streamStartTime} />
+      </span>
+    );
+  } else {
+    if (usage) {
+      const cacheInfo =
+        usage.cacheReadInputTokens || usage.cacheCreationInputTokens
+          ? ` (cache R:${formatTokens(usage.cacheReadInputTokens || 0)} W:${formatTokens(usage.cacheCreationInputTokens || 0)})`
+          : "";
+      metaParts.push(
+        <span key="tokens">
+          <span style={{ color: "rgb(var(--green-5))" }}>{"↑"}</span>
+          {formatTokens(usage.inputTokens)}
+          {cacheInfo} <span style={{ color: "rgb(var(--red-5))" }}>{"↓"}</span>
+          {formatTokens(usage.outputTokens)}
+        </span>
+      );
+    }
+    if (durationMs != null) {
+      metaParts.push(<span key="dur">{formatDuration(durationMs)}</span>);
+    }
+    if (firstTokenMs != null) {
+      metaParts.push(
+        <span key="ttft">
+          {t("agent_chat_first_token")} {formatDuration(firstTokenMs)}
+        </span>
+      );
+    }
+  }
+
+  if (toolCallCount > 0) {
+    metaParts.push(<span key="tools">{t("agent_chat_tools_count", { count: toolCallCount })}</span>);
+  }
+
+  return (
+    <div className="tw-flex tw-items-center tw-justify-between tw-w-full tw-mt-2 tw-select-none tw-text-xs tw-text-[var(--color-text-3)] agent-message-toolbar">
+      {/* 最左侧：操作按钮（hover 时显示） */}
+      <div className="tw-flex tw-items-center">
+        {!isStreaming && (
+          <div className="agent-toolbar-actions tw-flex tw-items-center tw-opacity-0 tw-transition-opacity">
+            <ActionButton tooltip={t("agent_chat_copy_message")} onClick={onCopy}>
+              <IconCopy style={{ fontSize: 14 }} />
+            </ActionButton>
+            <ActionButton tooltip={t("agent_chat_regenerate")} onClick={onRegenerate}>
+              <IconRefresh style={{ fontSize: 14 }} />
+            </ActionButton>
+            <Popconfirm title={t("agent_chat_delete_confirm")} onOk={onDelete} position="top">
+              <Tooltip content={t("agent_chat_delete_round")} mini>
+                <button className="tw-w-6 tw-h-6 tw-flex tw-items-center tw-justify-center tw-rounded tw-bg-transparent tw-border-none tw-cursor-pointer tw-text-[var(--color-text-3)] hover:tw-text-[rgb(var(--red-6))] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors">
+                  <IconDelete style={{ fontSize: 14 }} />
+                </button>
+              </Tooltip>
+            </Popconfirm>
+          </div>
+        )}
+      </div>
+
+      {/* 最右侧：元数据信息 */}
+      <div className="tw-flex tw-items-center tw-flex-wrap tw-justify-end">
+        {metaParts.map((part, i) => (
+          <span key={i} className="tw-inline-flex tw-items-center">
+            {i > 0 && <Dot />}
+            {part}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/ThinkingBlock.tsx b/src/pages/options/routes/AgentChat/ThinkingBlock.tsx
new file mode 100644
index 000000000..7589b9467
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/ThinkingBlock.tsx
@@ -0,0 +1,53 @@
+import { useState, useRef, useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { IconDown, IconRight } from "@arco-design/web-react/icon";
+import MarkdownRenderer from "./MarkdownRenderer";
+
+export default function ThinkingBlock({ content }: { content: string }) {
+  const { t } = useTranslation();
+  const [expanded, setExpanded] = useState(false);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [contentHeight, setContentHeight] = useState(0);
+
+  useEffect(() => {
+    if (contentRef.current) {
+      setContentHeight(contentRef.current.scrollHeight);
+    }
+  }, [content, expanded]);
+
+  if (!content) return null;
+
+  return (
+    <div className="tw-my-3">
+      {/* 触发器 */}
+      <div
+        className="tw-inline-flex tw-items-center tw-gap-1.5 tw-cursor-pointer tw-select-none tw-group"
+        onClick={() => setExpanded(!expanded)}
+      >
+        <div className="tw-w-5 tw-h-5 tw-rounded-full tw-flex tw-items-center tw-justify-center tw-bg-[var(--color-fill-2)] group-hover:tw-bg-[var(--color-fill-3)] tw-transition-colors">
+          {expanded ? (
+            <IconDown style={{ fontSize: 10 }} className="tw-text-[var(--color-text-3)]" />
+          ) : (
+            <IconRight style={{ fontSize: 10 }} className="tw-text-[var(--color-text-3)]" />
+          )}
+        </div>
+        <span className="tw-text-xs tw-text-[var(--color-text-3)] group-hover:tw-text-[var(--color-text-2)] tw-transition-colors tw-italic">
+          {t("agent_chat_thinking")}
+        </span>
+      </div>
+
+      {/* 内容区域 */}
+      <div
+        className="agent-collapsible-content"
+        style={{ maxHeight: expanded ? contentHeight + 32 : 0, opacity: expanded ? 1 : 0 }}
+      >
+        <div
+          ref={contentRef}
+          className="tw-mt-2 tw-pl-4 tw-border-l-2 tw-border-solid tw-border-[var(--color-border-2)] tw-border-t-0 tw-border-r-0 tw-border-b-0 tw-text-sm tw-text-[var(--color-text-3)]"
+        >
+          <MarkdownRenderer content={content} />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/ToolCallBlock.tsx b/src/pages/options/routes/AgentChat/ToolCallBlock.tsx
new file mode 100644
index 000000000..6f75e02dc
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/ToolCallBlock.tsx
@@ -0,0 +1,111 @@
+import { useState, useRef, useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { IconDown, IconRight, IconCheck, IconClose } from "@arco-design/web-react/icon";
+import type { ToolCall } from "@App/app/service/agent/types";
+import { AttachmentImage, AttachmentFile } from "./AttachmentRenderers";
+
+// 状态图标
+function StatusIcon({ status }: { status?: string }) {
+  switch (status) {
+    case "running":
+      return <span className="agent-tool-spinner" />;
+    case "completed":
+      return (
+        <span className="tw-w-4 tw-h-4 tw-rounded-full tw-bg-[rgb(var(--green-1))] tw-flex tw-items-center tw-justify-center">
+          <IconCheck style={{ fontSize: 10, color: "rgb(var(--green-6))" }} />
+        </span>
+      );
+    case "error":
+      return (
+        <span className="tw-w-4 tw-h-4 tw-rounded-full tw-bg-[rgb(var(--red-1))] tw-flex tw-items-center tw-justify-center">
+          <IconClose style={{ fontSize: 10, color: "rgb(var(--red-6))" }} />
+        </span>
+      );
+    default:
+      return <span className="tw-w-3 tw-h-3 tw-rounded-full tw-bg-[var(--color-fill-3)]" />;
+  }
+}
+
+export default function ToolCallBlock({ toolCall }: { toolCall: ToolCall }) {
+  const { t } = useTranslation();
+  const [expanded, setExpanded] = useState(false);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [contentHeight, setContentHeight] = useState(0);
+
+  // 使用 ResizeObserver 监听内容区域尺寸变化，自动更新高度
+  // 解决流式加载期间展开后 result 到达导致 max-height 不足的问题
+  useEffect(() => {
+    const el = contentRef.current;
+    if (!el) return;
+
+    const observer = new ResizeObserver(() => {
+      setContentHeight(el.scrollHeight);
+    });
+    observer.observe(el);
+
+    return () => observer.disconnect();
+  }, []);
+
+  const hasAttachments = toolCall.attachments && toolCall.attachments.length > 0;
+
+  return (
+    <div className="tw-my-2">
+      {/* 触发器 */}
+      <div
+        className="tw-inline-flex tw-items-center tw-gap-2 tw-px-3 tw-py-1.5 tw-rounded-full tw-cursor-pointer tw-select-none tw-bg-[var(--color-fill-1)] hover:tw-bg-[var(--color-fill-2)] tw-transition-colors tw-border tw-border-solid tw-border-[var(--color-border-1)]"
+        onClick={() => setExpanded(!expanded)}
+      >
+        <StatusIcon status={toolCall.status} />
+        <span className="tw-text-xs tw-font-medium tw-text-[var(--color-text-2)]">{toolCall.name}</span>
+        {expanded ? (
+          <IconDown style={{ fontSize: 10 }} className="tw-text-[var(--color-text-4)]" />
+        ) : (
+          <IconRight style={{ fontSize: 10 }} className="tw-text-[var(--color-text-4)]" />
+        )}
+      </div>
+
+      {/* 附件展示（始终可见，不需要展开） */}
+      {hasAttachments && (
+        <div className="tw-mt-2 tw-ml-2 tw-flex tw-flex-wrap tw-gap-2">
+          {toolCall.attachments!.map((att) =>
+            att.type === "image" ? (
+              <AttachmentImage key={att.id} attachment={att} />
+            ) : (
+              <AttachmentFile key={att.id} attachment={att} />
+            )
+          )}
+        </div>
+      )}
+
+      {/* 展开内容（参数和文本结果） */}
+      <div
+        className="agent-collapsible-content"
+        style={{ maxHeight: expanded ? contentHeight + 32 : 0, opacity: expanded ? 1 : 0 }}
+      >
+        <div ref={contentRef} className="tw-mt-2 tw-ml-2">
+          {/* 参数 */}
+          <div className="tw-rounded-lg tw-overflow-hidden tw-border tw-border-solid tw-border-[var(--color-border-1)]">
+            <div className="tw-px-3 tw-py-1.5 tw-bg-[var(--color-fill-2)] tw-text-xs tw-font-medium tw-text-[var(--color-text-3)]">
+              {t("agent_chat_tool_arguments") || "Arguments"}
+            </div>
+            <pre className="tw-m-0 tw-px-3 tw-py-2 tw-whitespace-pre-wrap tw-break-all tw-text-xs tw-font-mono tw-text-[var(--color-text-2)] tw-bg-[var(--color-fill-1)] tw-max-h-[300px] tw-overflow-y-auto">
+              {toolCall.arguments}
+            </pre>
+          </div>
+
+          {/* 文本结果 */}
+          {toolCall.result && (
+            <div className="tw-rounded-lg tw-overflow-hidden tw-border tw-border-solid tw-border-[var(--color-border-1)] tw-mt-2">
+              <div className="tw-px-3 tw-py-1.5 tw-bg-[var(--color-fill-2)] tw-text-xs tw-font-medium tw-text-[var(--color-text-3)]">
+                {t("agent_chat_tool_result") || "Result"}
+              </div>
+              <pre className="tw-m-0 tw-px-3 tw-py-2 tw-whitespace-pre-wrap tw-break-all tw-text-xs tw-font-mono tw-text-[var(--color-text-2)] tw-bg-[var(--color-fill-1)] tw-max-h-[300px] tw-overflow-y-auto">
+                {toolCall.result}
+              </pre>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/chat_utils.test.ts b/src/pages/options/routes/AgentChat/chat_utils.test.ts
new file mode 100644
index 000000000..99e13aac6
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/chat_utils.test.ts
@@ -0,0 +1,373 @@
+import { describe, it, expect } from "vitest";
+import type { ChatMessage } from "@App/app/service/agent/types";
+import {
+  mergeToolResults,
+  groupMessages,
+  computeRegenerateAction,
+  computeEditAction,
+  computeUserRegenerateAction,
+  findNextAssistantGroupIndex,
+} from "./chat_utils";
+
+// 辅助函数：创建测试消息
+function makeMsg(overrides: Partial<ChatMessage> & { id: string; role: ChatMessage["role"] }): ChatMessage {
+  return {
+    conversationId: "conv1",
+    content: "",
+    createtime: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("mergeToolResults", () => {
+  it("过滤掉 tool 和 system 消息，只保留 user 和 assistant", () => {
+    const messages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+      makeMsg({ id: "t1", role: "tool", content: "result", toolCallId: "tc1" }),
+      makeMsg({ id: "s1", role: "system", content: "system prompt" }),
+    ];
+    const result = mergeToolResults(messages);
+    expect(result.map((m) => m.id)).toEqual(["u1", "a1"]);
+  });
+
+  it("将 tool 结果合并到 assistant 的 toolCalls 中", () => {
+    const messages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({
+        id: "a1",
+        role: "assistant",
+        content: "",
+        toolCalls: [{ id: "tc1", name: "test", arguments: "{}", status: "running" }],
+      }),
+      makeMsg({ id: "t1", role: "tool", content: "tool output", toolCallId: "tc1" }),
+    ];
+    const result = mergeToolResults(messages);
+    expect(result).toHaveLength(2);
+    expect(result[1].toolCalls?.[0].result).toBe("tool output");
+    expect(result[1].toolCalls?.[0].status).toBe("running");
+  });
+});
+
+describe("groupMessages", () => {
+  it("用户和 assistant 消息交替分组", () => {
+    const messages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "q1" }),
+      makeMsg({ id: "a1", role: "assistant", content: "r1" }),
+      makeMsg({ id: "u2", role: "user", content: "q2" }),
+      makeMsg({ id: "a2", role: "assistant", content: "r2" }),
+    ];
+    const groups = groupMessages(messages);
+    expect(groups).toHaveLength(4);
+    expect(groups[0]).toEqual({ type: "user", message: messages[0] });
+    expect(groups[1]).toEqual({ type: "assistant", messages: [messages[1]] });
+    expect(groups[2]).toEqual({ type: "user", message: messages[2] });
+    expect(groups[3]).toEqual({ type: "assistant", messages: [messages[3]] });
+  });
+
+  it("连续的 assistant 消息合并为一组", () => {
+    const messages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "q1" }),
+      makeMsg({ id: "a1", role: "assistant", content: "r1" }),
+      makeMsg({ id: "a2", role: "assistant", content: "r2" }),
+    ];
+    const groups = groupMessages(messages);
+    expect(groups).toHaveLength(2);
+    expect(groups[1]).toEqual({ type: "assistant", messages: [messages[1], messages[2]] });
+  });
+
+  it("空消息列表返回空分组", () => {
+    expect(groupMessages([])).toEqual([]);
+  });
+});
+
+describe("computeRegenerateAction", () => {
+  // 典型场景：[user, assistant] — 重新生成第一条
+  it("重新生成第一条用户消息后的 assistant 响应", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+    ];
+    const groups = groupMessages(mergeToolResults(allMessages));
+    // groups: [user(u1), assistant(a1)]
+
+    const result = computeRegenerateAction(groups, 1, allMessages);
+    expect(result).not.toBeNull();
+    // 应删除 assistant 消息 + 用户消息（handleSend 会重新创建）
+    expect(result!.idsToDelete).toContain("a1");
+    expect(result!.idsToDelete).toContain("u1");
+    // 剩余消息应为空
+    expect(result!.remainingMessages).toEqual([]);
+    // 用户内容保留用于重新发送
+    expect(result!.userContent).toBe("hello");
+  });
+
+  // 多轮对话：[u1, a1, u2, a2] — 重新生成第二轮的 assistant
+  it("重新生成中间轮的 assistant 响应", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "first" }),
+      makeMsg({ id: "a1", role: "assistant", content: "reply1" }),
+      makeMsg({ id: "u2", role: "user", content: "second" }),
+      makeMsg({ id: "a2", role: "assistant", content: "reply2" }),
+    ];
+    const groups = groupMessages(mergeToolResults(allMessages));
+    // groups: [user(u1), assistant(a1), user(u2), assistant(a2)]
+
+    const result = computeRegenerateAction(groups, 3, allMessages);
+    expect(result).not.toBeNull();
+    expect(result!.idsToDelete).toContain("a2");
+    expect(result!.idsToDelete).toContain("u2");
+    expect(result!.idsToDelete).not.toContain("u1");
+    expect(result!.idsToDelete).not.toContain("a1");
+    // 保留第一轮
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["u1", "a1"]);
+    expect(result!.userContent).toBe("second");
+  });
+
+  // 包含 tool 消息：[u1, a1(toolCall), tool, a2]
+  it("包含 tool 消息时正确处理", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({
+        id: "a1",
+        role: "assistant",
+        content: "",
+        toolCalls: [{ id: "tc1", name: "test", arguments: "{}", status: "completed" }],
+      }),
+      makeMsg({ id: "t1", role: "tool", content: "result", toolCallId: "tc1" }),
+      makeMsg({ id: "a2", role: "assistant", content: "final" }),
+    ];
+    const merged = mergeToolResults(allMessages);
+    const groups = groupMessages(merged);
+    // merged 过滤了 tool 消息：[u1, a1, a2]
+    // groups: [user(u1), assistant(a1, a2)]
+
+    const result = computeRegenerateAction(groups, 1, allMessages);
+    expect(result).not.toBeNull();
+    // 应删除 merged 中的 assistant 消息 ID + 用户消息 ID
+    expect(result!.idsToDelete).toContain("a1");
+    expect(result!.idsToDelete).toContain("a2");
+    expect(result!.idsToDelete).toContain("u1");
+    // 注意：tool 消息不在 groups 里，所以不在 idsToDelete 中
+    // 但 remainingMessages 基于 allMessages 过滤，tool 消息也会被保留
+    // 这是一个已知行为——deleteMessages 只删指定 ID
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["t1"]);
+  });
+
+  it("没有用户消息时返回 null", () => {
+    const allMessages: ChatMessage[] = [makeMsg({ id: "a1", role: "assistant", content: "hi" })];
+    const groups = groupMessages(allMessages);
+    const result = computeRegenerateAction(groups, 0, allMessages);
+    expect(result).toBeNull();
+  });
+
+  it("传入非 assistant 组索引时返回 null", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+    ];
+    const groups = groupMessages(allMessages);
+    const result = computeRegenerateAction(groups, 0, allMessages);
+    expect(result).toBeNull();
+  });
+});
+
+describe("computeEditAction", () => {
+  it("编辑第一条用户消息：删除所有消息", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+    ];
+    const result = computeEditAction("u1", allMessages);
+    expect(result).not.toBeNull();
+    expect(result!.idsToDelete.map((id) => id)).toEqual(["u1", "a1"]);
+    expect(result!.remainingMessages).toEqual([]);
+  });
+
+  it("编辑中间用户消息：保留之前的消息", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "first" }),
+      makeMsg({ id: "a1", role: "assistant", content: "reply1" }),
+      makeMsg({ id: "u2", role: "user", content: "second" }),
+      makeMsg({ id: "a2", role: "assistant", content: "reply2" }),
+    ];
+    const result = computeEditAction("u2", allMessages);
+    expect(result).not.toBeNull();
+    expect(result!.idsToDelete).toEqual(["u2", "a2"]);
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["u1", "a1"]);
+  });
+
+  it("消息不存在时返回 null", () => {
+    const result = computeEditAction("nonexistent", []);
+    expect(result).toBeNull();
+  });
+});
+
+describe("findNextAssistantGroupIndex", () => {
+  it("用户消息后面有 assistant 组时返回其索引", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+    ];
+    const groups = groupMessages(allMessages);
+    expect(findNextAssistantGroupIndex(groups, 0)).toBe(1);
+  });
+
+  it("用户消息后面没有 assistant 组时返回 null", () => {
+    const allMessages: ChatMessage[] = [makeMsg({ id: "u1", role: "user", content: "hello" })];
+    const groups = groupMessages(allMessages);
+    expect(findNextAssistantGroupIndex(groups, 0)).toBeNull();
+  });
+
+  it("用户消息是最后一个 group 时返回 null", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "first" }),
+      makeMsg({ id: "a1", role: "assistant", content: "reply" }),
+      makeMsg({ id: "u2", role: "user", content: "second" }),
+    ];
+    const groups = groupMessages(allMessages);
+    // groups: [user(u1), assistant(a1), user(u2)]
+    expect(findNextAssistantGroupIndex(groups, 2)).toBeNull();
+  });
+
+  // 关键场景：用户消息重新生成走的逻辑
+  it("用户消息重新生成：通过 findNextAssistantGroupIndex + computeRegenerateAction 联合使用", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+      makeMsg({ id: "u2", role: "user", content: "world" }),
+      makeMsg({ id: "a2", role: "assistant", content: "bye" }),
+    ];
+    const groups = groupMessages(mergeToolResults(allMessages));
+
+    // 第一条用户消息的重新生成
+    const assistantIdx0 = findNextAssistantGroupIndex(groups, 0);
+    expect(assistantIdx0).toBe(1);
+    const action0 = computeRegenerateAction(groups, assistantIdx0!, allMessages);
+    expect(action0).not.toBeNull();
+    expect(action0!.userContent).toBe("hello");
+    // 重新生成第一条：删除 u1 + a1，remainingMessages 不包含它们
+    // handleSend 会用 userContent 重新创建 user + assistant
+    expect(action0!.idsToDelete).toContain("u1");
+    expect(action0!.idsToDelete).toContain("a1");
+    // 注意：第二轮消息仍然保留在 remainingMessages 中
+    expect(action0!.remainingMessages.map((m) => m.id)).toEqual(["u2", "a2"]);
+
+    // 第二条用户消息的重新生成
+    const assistantIdx2 = findNextAssistantGroupIndex(groups, 2);
+    expect(assistantIdx2).toBe(3);
+    const action2 = computeRegenerateAction(groups, assistantIdx2!, allMessages);
+    expect(action2).not.toBeNull();
+    expect(action2!.userContent).toBe("world");
+    expect(action2!.idsToDelete).toContain("u2");
+    expect(action2!.idsToDelete).toContain("a2");
+    expect(action2!.remainingMessages.map((m) => m.id)).toEqual(["u1", "a1"]);
+  });
+});
+
+describe("computeUserRegenerateAction — 用户消息重新生成（bug 修复验证）", () => {
+  // 这是用户报告的 bug 场景：点击第一条用户消息的重新生成，会话被清空
+  it("【bug 回归】第一条用户消息重新生成：必须保留用户消息，只删除 assistant 回复", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({ id: "a1", role: "assistant", content: "hi" }),
+    ];
+
+    const result = computeUserRegenerateAction("u1", allMessages);
+    expect(result).not.toBeNull();
+
+    // 关键断言 1: 只删除 assistant 回复，不删除用户消息
+    expect(result!.idsToDelete).toEqual(["a1"]);
+    expect(result!.idsToDelete).not.toContain("u1");
+
+    // 关键断言 2: remainingMessages 必须包含用户消息
+    expect(result!.remainingMessages).toHaveLength(1);
+    expect(result!.remainingMessages[0].id).toBe("u1");
+    expect(result!.remainingMessages[0].content).toBe("hello");
+
+    // 关键断言 3: skipUserMessage 必须为 true，防止 startStreaming 重复创建用户消息
+    expect(result!.skipUserMessage).toBe(true);
+
+    // 关键断言 4: userContent 正确传递
+    expect(result!.userContent).toBe("hello");
+  });
+
+  it("多轮对话中重新生成第一条用户消息：只删除紧跟的 assistant 回复", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "first" }),
+      makeMsg({ id: "a1", role: "assistant", content: "reply1" }),
+      makeMsg({ id: "u2", role: "user", content: "second" }),
+      makeMsg({ id: "a2", role: "assistant", content: "reply2" }),
+    ];
+
+    const result = computeUserRegenerateAction("u1", allMessages);
+    expect(result).not.toBeNull();
+
+    // 删除用户消息之后的所有消息（a1, u2, a2）
+    expect(result!.idsToDelete).toEqual(["a1", "u2", "a2"]);
+
+    // 只保留第一条用户消息
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["u1"]);
+    expect(result!.skipUserMessage).toBe(true);
+    expect(result!.userContent).toBe("first");
+  });
+
+  it("重新生成中间用户消息：保留之前的消息和当前用户消息", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "first" }),
+      makeMsg({ id: "a1", role: "assistant", content: "reply1" }),
+      makeMsg({ id: "u2", role: "user", content: "second" }),
+      makeMsg({ id: "a2", role: "assistant", content: "reply2" }),
+    ];
+
+    const result = computeUserRegenerateAction("u2", allMessages);
+    expect(result).not.toBeNull();
+
+    // 只删除 u2 之后的回复
+    expect(result!.idsToDelete).toEqual(["a2"]);
+
+    // 保留 u1, a1, u2
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["u1", "a1", "u2"]);
+    expect(result!.skipUserMessage).toBe(true);
+    expect(result!.userContent).toBe("second");
+  });
+
+  it("用户消息后面没有回复时：idsToDelete 为空", () => {
+    const allMessages: ChatMessage[] = [makeMsg({ id: "u1", role: "user", content: "hello" })];
+
+    const result = computeUserRegenerateAction("u1", allMessages);
+    expect(result).not.toBeNull();
+    expect(result!.idsToDelete).toEqual([]);
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["u1"]);
+    expect(result!.userContent).toBe("hello");
+  });
+
+  it("消息不存在时返回 null", () => {
+    const result = computeUserRegenerateAction("nonexistent", [makeMsg({ id: "u1", role: "user", content: "hello" })]);
+    expect(result).toBeNull();
+  });
+
+  it("包含 tool 消息时也只删除用户消息之后的部分", () => {
+    const allMessages: ChatMessage[] = [
+      makeMsg({ id: "u1", role: "user", content: "hello" }),
+      makeMsg({
+        id: "a1",
+        role: "assistant",
+        content: "",
+        toolCalls: [{ id: "tc1", name: "test", arguments: "{}", status: "completed" }],
+      }),
+      makeMsg({ id: "t1", role: "tool", content: "result", toolCallId: "tc1" }),
+      makeMsg({ id: "a2", role: "assistant", content: "final" }),
+    ];
+
+    const result = computeUserRegenerateAction("u1", allMessages);
+    expect(result).not.toBeNull();
+
+    // 删除 u1 之后的所有消息（a1, t1, a2）
+    expect(result!.idsToDelete).toEqual(["a1", "t1", "a2"]);
+
+    // 只保留 u1
+    expect(result!.remainingMessages.map((m) => m.id)).toEqual(["u1"]);
+    expect(result!.skipUserMessage).toBe(true);
+  });
+});
diff --git a/src/pages/options/routes/AgentChat/chat_utils.ts b/src/pages/options/routes/AgentChat/chat_utils.ts
new file mode 100644
index 000000000..7c8bf0ea1
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/chat_utils.ts
@@ -0,0 +1,128 @@
+import type { ChatMessage, MessageContent } from "@App/app/service/agent/types";
+
+// 将消息按角色分组：连续的 assistant 消息合并为一组
+export type MessageGroup = { type: "user"; message: ChatMessage } | { type: "assistant"; messages: ChatMessage[] };
+
+// 将 tool 角色消息的结果合并到 assistant 消息的 toolCalls 中，并过滤掉 tool/system 消息
+export function mergeToolResults(messages: ChatMessage[]): ChatMessage[] {
+  const toolResultMap = new Map<string, string>();
+  for (const msg of messages) {
+    if (msg.role === "tool" && msg.toolCallId) {
+      // tool 消息的 content 始终是 string
+      toolResultMap.set(msg.toolCallId, typeof msg.content === "string" ? msg.content : "");
+    }
+  }
+
+  return messages
+    .filter((msg) => msg.role === "user" || msg.role === "assistant")
+    .map((msg) => {
+      if (msg.role === "assistant" && msg.toolCalls && toolResultMap.size > 0) {
+        const updatedToolCalls = msg.toolCalls.map((tc) => {
+          const result = toolResultMap.get(tc.id);
+          if (result !== undefined) {
+            return { ...tc, result, status: (tc.status || "completed") as typeof tc.status };
+          }
+          return tc;
+        });
+        return { ...msg, toolCalls: updatedToolCalls };
+      }
+      return msg;
+    });
+}
+
+export function groupMessages(messages: ChatMessage[]): MessageGroup[] {
+  const groups: MessageGroup[] = [];
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      groups.push({ type: "user", message: msg });
+    } else {
+      const last = groups[groups.length - 1];
+      if (last && last.type === "assistant") {
+        last.messages.push(msg);
+      } else {
+        groups.push({ type: "assistant", messages: [msg] });
+      }
+    }
+  }
+  return groups;
+}
+
+// 计算重新生成操作需要删除的消息 ID 和保留的消息
+// 输入: assistant 组在 groups 中的 groupIndex
+// 返回: { idsToDelete, remainingMessages, userContent } 或 null（无法执行）
+export function computeRegenerateAction(
+  groups: MessageGroup[],
+  assistantGroupIndex: number,
+  allMessages: ChatMessage[]
+): { idsToDelete: string[]; remainingMessages: ChatMessage[]; userContent: MessageContent } | null {
+  const group = groups[assistantGroupIndex];
+  if (!group || group.type !== "assistant") return null;
+
+  // 找到前面的用户消息
+  let userMessage: ChatMessage | null = null;
+  for (let i = assistantGroupIndex - 1; i >= 0; i--) {
+    if (groups[i].type === "user") {
+      userMessage = (groups[i] as { type: "user"; message: ChatMessage }).message;
+      break;
+    }
+  }
+  if (!userMessage) return null;
+
+  // 收集需要删除的消息 ID（assistant 组 + 用户消息）
+  const idsToDelete = group.messages.map((m) => m.id);
+  idsToDelete.push(userMessage.id);
+
+  // 重建消息列表
+  const idSet = new Set(idsToDelete);
+  const remainingMessages = allMessages.filter((m) => !idSet.has(m.id));
+
+  return { idsToDelete, remainingMessages, userContent: userMessage.content };
+}
+
+// 计算编辑消息操作需要删除的消息 ID 和保留的消息
+export function computeEditAction(
+  messageId: string,
+  allMessages: ChatMessage[]
+): { idsToDelete: string[]; remainingMessages: ChatMessage[] } | null {
+  const idx = allMessages.findIndex((m) => m.id === messageId);
+  if (idx < 0) return null;
+
+  const idsToDelete = allMessages.slice(idx).map((m) => m.id);
+  const remainingMessages = allMessages.slice(0, idx);
+
+  return { idsToDelete, remainingMessages };
+}
+
+// 根据用户消息在 groups 中的位置，找到对应的 assistant 组索引
+// 用于"用户消息重新生成"场景
+export function findNextAssistantGroupIndex(groups: MessageGroup[], userGroupIndex: number): number | null {
+  if (userGroupIndex + 1 < groups.length && groups[userGroupIndex + 1].type === "assistant") {
+    return userGroupIndex + 1;
+  }
+  return null;
+}
+
+// 计算用户消息重新生成的操作：保留用户消息本身，只删除后续回复
+// 返回 { idsToDelete, remainingMessages, userContent, skipUserMessage: true }
+export function computeUserRegenerateAction(
+  messageId: string,
+  allMessages: ChatMessage[]
+): {
+  idsToDelete: string[];
+  remainingMessages: ChatMessage[];
+  userContent: MessageContent;
+  skipUserMessage: true;
+} | null {
+  const idx = allMessages.findIndex((m) => m.id === messageId);
+  if (idx < 0) return null;
+
+  const userContent = allMessages[idx].content;
+
+  // 只删除用户消息之后的回复（保留用户消息本身）
+  const idsToDelete = allMessages.slice(idx + 1).map((m) => m.id);
+
+  // 保留到用户消息为止（含用户消息）
+  const remainingMessages = allMessages.slice(0, idx + 1);
+
+  return { idsToDelete, remainingMessages, userContent, skipUserMessage: true };
+}
diff --git a/src/pages/options/routes/AgentChat/hooks.ts b/src/pages/options/routes/AgentChat/hooks.ts
new file mode 100644
index 000000000..2a7b225f0
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/hooks.ts
@@ -0,0 +1,229 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useSearchParams } from "react-router-dom";
+import type {
+  Conversation,
+  ChatMessage,
+  ChatStreamEvent,
+  SkillSummary,
+  MessageContent,
+} from "@App/app/service/agent/types";
+import { AgentChatRepo } from "@App/app/repo/agent_chat";
+import { SkillRepo } from "@App/app/repo/skill_repo";
+import { message as extensionMessage } from "@App/pages/store/global";
+import { connect } from "@Packages/message/client";
+import type { MessageConnect } from "@Packages/message/types";
+
+const repo = new AgentChatRepo();
+const skillRepo = new SkillRepo();
+
+// 生成唯一 ID
+function genId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+// 会话管理 hook
+export function useConversations() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const [conversations, setConversations] = useState<Conversation[]>([]);
+
+  // 从 URL 参数读取当前会话 ID
+  const activeId = searchParams.get("id") || "";
+
+  // 设置会话 ID 并同步到 URL
+  const setActiveId = useCallback(
+    (id: string) => {
+      setSearchParams(id ? { id } : {}, { replace: true });
+    },
+    [setSearchParams]
+  );
+
+  // 加载会话列表
+  const loadConversations = useCallback(async () => {
+    const list = await repo.listConversations();
+    setConversations(list);
+    return list;
+  }, []);
+
+  useEffect(() => {
+    loadConversations().then((list) => {
+      if (list.length > 0 && !activeId) {
+        // 进入页面时，如果有会话且 URL 中无 id 参数，则自动选中第一个
+        setActiveId(list[0].id);
+      }
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [loadConversations]);
+
+  // 创建新会话
+  const createConversation = useCallback(
+    async (modelId: string, skills?: "auto" | string[]) => {
+      const conv: Conversation = {
+        id: genId(),
+        title: "New Chat",
+        modelId,
+        skills,
+        createtime: Date.now(),
+        updatetime: Date.now(),
+      };
+      await repo.saveConversation(conv);
+      const list = await loadConversations();
+      setActiveId(conv.id);
+      return { conv, list };
+    },
+    [loadConversations, setActiveId]
+  );
+
+  // 删除会话
+  const deleteConversation = useCallback(
+    async (id: string) => {
+      await repo.deleteConversation(id);
+      const list = await loadConversations();
+      if (activeId === id) {
+        setActiveId(list[0]?.id || "");
+      }
+    },
+    [activeId, loadConversations, setActiveId]
+  );
+
+  // 重命名会话
+  const renameConversation = useCallback(
+    async (id: string, title: string) => {
+      const list = await repo.listConversations();
+      const conv = list.find((c) => c.id === id);
+      if (conv) {
+        conv.title = title;
+        conv.updatetime = Date.now();
+        await repo.saveConversation(conv);
+        await loadConversations();
+      }
+    },
+    [loadConversations]
+  );
+
+  return {
+    conversations,
+    activeId,
+    setActiveId,
+    createConversation,
+    deleteConversation,
+    renameConversation,
+    loadConversations,
+  };
+}
+
+// 消息管理 hook
+export function useMessages(conversationId: string) {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+
+  const loadMessages = useCallback(async () => {
+    if (!conversationId) {
+      setMessages([]);
+      return;
+    }
+    const msgs = await repo.getMessages(conversationId);
+    setMessages(msgs);
+  }, [conversationId]);
+
+  useEffect(() => {
+    loadMessages();
+  }, [loadMessages]);
+
+  return { messages, setMessages, loadMessages };
+}
+
+// 流式聊天 hook
+export function useStreamingChat() {
+  const [isStreaming, setIsStreaming] = useState(false);
+  const connRef = useRef<MessageConnect | null>(null);
+  const abortedRef = useRef(false);
+
+  const stopGeneration = useCallback(() => {
+    abortedRef.current = true;
+    if (connRef.current) {
+      connRef.current.disconnect();
+      connRef.current = null;
+    }
+    setIsStreaming(false);
+  }, []);
+
+  const sendMessage = useCallback(
+    async (
+      conversationId: string,
+      message: MessageContent,
+      onEvent: (event: ChatStreamEvent) => void,
+      onDone: () => void,
+      modelId?: string,
+      skipSaveUserMessage?: boolean
+    ) => {
+      setIsStreaming(true);
+      abortedRef.current = false;
+
+      try {
+        const conn = await connect(extensionMessage, "serviceWorker/agent/conversationChat", {
+          conversationId,
+          message,
+          modelId,
+          skipSaveUserMessage,
+        });
+
+        connRef.current = conn;
+
+        conn.onMessage((msg) => {
+          if (abortedRef.current) return;
+          const event = msg.data as ChatStreamEvent;
+          onEvent(event);
+          if (event.type === "done" || event.type === "error") {
+            setIsStreaming(false);
+            connRef.current = null;
+            onDone();
+          }
+        });
+
+        conn.onDisconnect(() => {
+          setIsStreaming(false);
+          connRef.current = null;
+        });
+      } catch (e: any) {
+        setIsStreaming(false);
+        onEvent({ type: "error", message: e.message || "Connection failed" });
+        onDone();
+      }
+    },
+    []
+  );
+
+  return { isStreaming, sendMessage, stopGeneration };
+}
+
+// 批量删除持久化消息
+export async function deleteMessages(conversationId: string, messageIds: string[]): Promise<void> {
+  const messages = await repo.getMessages(conversationId);
+  const idSet = new Set(messageIds);
+  const filtered = messages.filter((m) => !idSet.has(m.id));
+  await repo.saveMessages(conversationId, filtered);
+}
+
+// 清空对话消息
+export async function clearMessages(conversationId: string): Promise<void> {
+  await repo.saveMessages(conversationId, []);
+}
+
+// Skill 列表 hook
+export function useSkills() {
+  const [skills, setSkills] = useState<SkillSummary[]>([]);
+
+  const loadSkills = useCallback(async () => {
+    try {
+      const list = await skillRepo.listSkills();
+      setSkills(list);
+    } catch {
+      setSkills([]);
+    }
+  }, []);
+
+  useEffect(() => {
+    loadSkills();
+  }, [loadSkills]);
+
+  return { skills, loadSkills };
+}
diff --git a/src/pages/options/routes/AgentChat/index.tsx b/src/pages/options/routes/AgentChat/index.tsx
new file mode 100644
index 000000000..e01cf8733
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/index.tsx
@@ -0,0 +1,73 @@
+import { useCallback, useEffect, useState } from "react";
+import ConversationList from "./ConversationList";
+import ChatArea from "./ChatArea";
+import { useConversations, useSkills } from "./hooks";
+import type { AgentModelConfig } from "@App/app/service/agent/types";
+import { AgentModelRepo } from "@App/app/repo/agent_model";
+import "./styles.css";
+
+const agentModelRepo = new AgentModelRepo();
+
+export default function AgentChat() {
+  const [models, setModels] = useState<AgentModelConfig[]>([]);
+  const [defaultModelId, setDefaultModelId] = useState("");
+
+  useEffect(() => {
+    Promise.all([agentModelRepo.listModels(), agentModelRepo.getDefaultModelId()]).then(([modelList, defId]) => {
+      setModels(modelList);
+      setDefaultModelId(defId || modelList[0]?.id || "");
+    });
+  }, []);
+
+  const {
+    conversations,
+    activeId,
+    setActiveId,
+    createConversation,
+    deleteConversation,
+    renameConversation,
+    loadConversations,
+  } = useConversations();
+
+  const { skills } = useSkills();
+
+  const [selectedModelId, setSelectedModelId] = useState<string>("");
+  // 当前选择的 skills 配置（用于创建新对话）
+  const [selectedSkills, setSelectedSkills] = useState<"auto" | string[]>("auto");
+
+  // 使用默认模型 ID（如果未选择）
+  const effectiveModelId = selectedModelId || defaultModelId;
+
+  const handleCreate = useCallback(async () => {
+    const { conv } = await createConversation(effectiveModelId, selectedSkills);
+    setActiveId(conv.id);
+  }, [createConversation, effectiveModelId, selectedSkills, setActiveId]);
+
+  // 当会话标题变更时重新加载会话列表
+  const handleTitleChange = useCallback(() => {
+    loadConversations();
+  }, [loadConversations]);
+
+  return (
+    <div className="tw-flex tw-h-full tw-bg-[var(--color-bg-1)]">
+      <ConversationList
+        conversations={conversations}
+        activeId={activeId}
+        onSelect={setActiveId}
+        onCreate={handleCreate}
+        onDelete={deleteConversation}
+        onRename={renameConversation}
+      />
+      <ChatArea
+        conversationId={activeId}
+        models={models}
+        selectedModelId={effectiveModelId}
+        onModelChange={setSelectedModelId}
+        onConversationTitleChange={handleTitleChange}
+        skills={skills}
+        selectedSkills={selectedSkills}
+        onSkillsChange={setSelectedSkills}
+      />
+    </div>
+  );
+}
diff --git a/src/pages/options/routes/AgentChat/styles.css b/src/pages/options/routes/AgentChat/styles.css
new file mode 100644
index 000000000..628b98b91
--- /dev/null
+++ b/src/pages/options/routes/AgentChat/styles.css
@@ -0,0 +1,384 @@
+/* Agent Chat 全局样式 */
+
+/* 消息淡入动画 */
+@keyframes message-fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.agent-message-item {
+  animation: message-fade-in 0.3s ease-out;
+}
+
+/* 流式光标闪烁 */
+@keyframes cursor-blink {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0;
+  }
+}
+
+.agent-streaming-cursor::after {
+  content: "▍";
+  animation: cursor-blink 1s step-end infinite;
+  color: var(--color-text-3);
+  margin-left: 1px;
+}
+
+/* 展开收起过渡 */
+.agent-collapsible-content {
+  overflow: hidden;
+  transition:
+    max-height 0.25s ease-out,
+    opacity 0.2s ease-out;
+}
+
+/* Loading spinner for running tool calls */
+@keyframes spin-dot {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+.agent-tool-spinner {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 1.5px solid var(--color-border-2);
+  border-top-color: rgb(var(--arcoblue-6));
+  border-radius: 50%;
+  animation: spin-dot 0.8s linear infinite;
+}
+
+/* 自定义滚动条 */
+.agent-chat-scroll::-webkit-scrollbar {
+  width: 6px;
+}
+
+.agent-chat-scroll::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.agent-chat-scroll::-webkit-scrollbar-thumb {
+  background: var(--color-fill-3);
+  border-radius: 3px;
+}
+
+.agent-chat-scroll::-webkit-scrollbar-thumb:hover {
+  background: var(--color-fill-4);
+}
+
+/* Markdown 样式 */
+.ai-markdown-body {
+  font-size: 14px;
+  line-height: 1.7;
+  color: var(--color-text-1);
+  word-wrap: break-word;
+}
+
+.ai-markdown-body p {
+  margin: 0.6em 0;
+}
+
+.ai-markdown-body p:first-child {
+  margin-top: 0;
+}
+
+.ai-markdown-body p:last-child {
+  margin-bottom: 0;
+}
+
+.ai-markdown-body h1,
+.ai-markdown-body h2,
+.ai-markdown-body h3,
+.ai-markdown-body h4,
+.ai-markdown-body h5,
+.ai-markdown-body h6 {
+  margin: 1em 0 0.5em;
+  font-weight: 600;
+  line-height: 1.4;
+  color: var(--color-text-1);
+}
+
+.ai-markdown-body h1 {
+  font-size: 1.5em;
+}
+
+.ai-markdown-body h2 {
+  font-size: 1.3em;
+}
+
+.ai-markdown-body h3 {
+  font-size: 1.15em;
+}
+
+.ai-markdown-body ul,
+.ai-markdown-body ol {
+  margin: 0.5em 0;
+  padding-left: 1.5em;
+}
+
+.ai-markdown-body li {
+  margin: 0.25em 0;
+}
+
+.ai-markdown-body li > p {
+  margin: 0.25em 0;
+}
+
+.ai-markdown-body blockquote {
+  margin: 0.8em 0;
+  padding: 0.4em 1em;
+  border-left: 3px solid rgb(var(--arcoblue-5));
+  background: var(--color-fill-1);
+  border-radius: 0 6px 6px 0;
+  color: var(--color-text-2);
+}
+
+.ai-markdown-body blockquote p {
+  margin: 0.25em 0;
+}
+
+.ai-markdown-body hr {
+  margin: 1.2em 0;
+  border: none;
+  border-top: 1px solid var(--color-border-2);
+}
+
+.ai-markdown-body a {
+  color: rgb(var(--arcoblue-6));
+  text-decoration: none;
+}
+
+.ai-markdown-body a:hover {
+  text-decoration: underline;
+}
+
+.ai-markdown-body img {
+  max-width: 100%;
+  border-radius: 8px;
+}
+
+/* 代码块 */
+.ai-markdown-body pre {
+  margin: 0.8em 0;
+  padding: 14px 16px;
+  background: var(--color-fill-2);
+  border-radius: 0 0 8px 8px;
+  overflow-x: auto;
+  font-size: 13px;
+  line-height: 1.6;
+}
+
+.ai-markdown-body pre code {
+  font-family: "SF Mono", "Fira Code", "Fira Mono", Menlo, Consolas, monospace;
+  font-size: inherit;
+  background: none;
+  padding: 0;
+  border-radius: 0;
+}
+
+/* 行内代码 */
+.ai-markdown-body code {
+  font-family: "SF Mono", "Fira Code", "Fira Mono", Menlo, Consolas, monospace;
+  font-size: 0.9em;
+  padding: 0.15em 0.4em;
+  background: var(--color-fill-2);
+  border-radius: 4px;
+  color: rgb(var(--arcoblue-6));
+}
+
+/* 表格 */
+.ai-markdown-body table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.8em 0;
+  font-size: 13px;
+}
+
+.ai-markdown-body th,
+.ai-markdown-body td {
+  border: 1px solid var(--color-border-2);
+  padding: 8px 12px;
+  text-align: left;
+}
+
+.ai-markdown-body th {
+  background: var(--color-fill-1);
+  font-weight: 600;
+}
+
+/* 暗色模式代码高亮 (github-dark) */
+body[arco-theme="dark"] .ai-markdown-body .hljs {
+  color: #c9d1d9;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-doctag,
+body[arco-theme="dark"] .ai-markdown-body .hljs-keyword,
+body[arco-theme="dark"] .ai-markdown-body .hljs-meta .hljs-keyword,
+body[arco-theme="dark"] .ai-markdown-body .hljs-template-tag,
+body[arco-theme="dark"] .ai-markdown-body .hljs-template-variable,
+body[arco-theme="dark"] .ai-markdown-body .hljs-type,
+body[arco-theme="dark"] .ai-markdown-body .hljs-variable.language_ {
+  color: #ff7b72;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-title,
+body[arco-theme="dark"] .ai-markdown-body .hljs-title.class_,
+body[arco-theme="dark"] .ai-markdown-body .hljs-title.class_.inherited__,
+body[arco-theme="dark"] .ai-markdown-body .hljs-title.function_ {
+  color: #d2a8ff;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-attr,
+body[arco-theme="dark"] .ai-markdown-body .hljs-attribute,
+body[arco-theme="dark"] .ai-markdown-body .hljs-literal,
+body[arco-theme="dark"] .ai-markdown-body .hljs-meta,
+body[arco-theme="dark"] .ai-markdown-body .hljs-number,
+body[arco-theme="dark"] .ai-markdown-body .hljs-operator,
+body[arco-theme="dark"] .ai-markdown-body .hljs-variable,
+body[arco-theme="dark"] .ai-markdown-body .hljs-selector-attr,
+body[arco-theme="dark"] .ai-markdown-body .hljs-selector-class,
+body[arco-theme="dark"] .ai-markdown-body .hljs-selector-id {
+  color: #79c0ff;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-regexp,
+body[arco-theme="dark"] .ai-markdown-body .hljs-string,
+body[arco-theme="dark"] .ai-markdown-body .hljs-meta .hljs-string {
+  color: #a5d6ff;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-built_in,
+body[arco-theme="dark"] .ai-markdown-body .hljs-symbol {
+  color: #ffa657;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-comment,
+body[arco-theme="dark"] .ai-markdown-body .hljs-code,
+body[arco-theme="dark"] .ai-markdown-body .hljs-formula {
+  color: #8b949e;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-name,
+body[arco-theme="dark"] .ai-markdown-body .hljs-quote,
+body[arco-theme="dark"] .ai-markdown-body .hljs-selector-tag,
+body[arco-theme="dark"] .ai-markdown-body .hljs-selector-pseudo {
+  color: #7ee787;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-subst {
+  color: #c9d1d9;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-section {
+  color: #1f6feb;
+  font-weight: bold;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-bullet {
+  color: #f2cc60;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-emphasis {
+  color: #c9d1d9;
+  font-style: italic;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-strong {
+  color: #c9d1d9;
+  font-weight: bold;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-addition {
+  color: #aff5b4;
+  background-color: #033a16;
+}
+body[arco-theme="dark"] .ai-markdown-body .hljs-deletion {
+  color: #ffdcd7;
+  background-color: #67060c;
+}
+
+/* 错误消息 */
+.agent-error-block {
+  margin-top: 8px;
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 10px 14px;
+  border-radius: 8px;
+  border-left: 3px solid #e5484d;
+  background: #fff0f0;
+  color: #ce2c31;
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.agent-error-block .agent-error-icon {
+  flex-shrink: 0;
+  font-size: 16px;
+  margin-top: 1px;
+  color: #e5484d;
+}
+
+body[arco-theme="dark"] .agent-error-block {
+  background: rgba(229, 72, 77, 0.1);
+  color: #ff6369;
+  border-left-color: #e5484d;
+}
+
+body[arco-theme="dark"] .agent-error-block .agent-error-icon {
+  color: #ff6369;
+}
+
+/* 侧边栏会话列表 */
+.agent-conversation-item {
+  position: relative;
+  transition: background-color 0.15s ease;
+}
+
+.agent-conversation-item::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 3px;
+  height: 0;
+  background: rgb(var(--arcoblue-6));
+  border-radius: 0 2px 2px 0;
+  transition: height 0.2s ease;
+}
+
+.agent-conversation-item.active::before {
+  height: 60%;
+}
+
+/* 消息工具条：hover 消息组时显示操作按钮 */
+.agent-message-item:hover .agent-toolbar-actions {
+  opacity: 1 !important;
+}
+
+/* 用户消息编辑容器 */
+.agent-edit-container {
+  border: 1px solid rgb(var(--arcoblue-4));
+  background: var(--color-bg-2);
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.08);
+  animation: edit-expand 0.2s ease-out;
+}
+
+body[arco-theme="dark"] .agent-edit-container {
+  border-color: rgb(var(--arcoblue-7));
+  background: var(--color-bg-3);
+  box-shadow: 0 2px 16px rgba(0, 0, 0, 0.32);
+}
+
+@keyframes edit-expand {
+  from {
+    opacity: 0;
+    transform: scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
diff --git a/src/pages/options/routes/AgentMcp.tsx b/src/pages/options/routes/AgentMcp.tsx
new file mode 100644
index 000000000..1e94e6319
--- /dev/null
+++ b/src/pages/options/routes/AgentMcp.tsx
@@ -0,0 +1,603 @@
+import {
+  Button,
+  Card,
+  Drawer,
+  Empty,
+  Input,
+  Message,
+  Modal,
+  Popconfirm,
+  Space,
+  Spin,
+  Switch,
+  Tabs,
+  Tag,
+  Typography,
+} from "@arco-design/web-react";
+import { IconDelete, IconEdit, IconEye, IconLink, IconPlus } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { MCPServerConfig, MCPTool, MCPResource, MCPPrompt } from "@App/app/service/agent/types";
+import { MCPServerRepo } from "@App/app/repo/mcp_server_repo";
+import { MCPClient } from "@App/app/service/agent/mcp_client";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+const mcpServerRepo = new MCPServerRepo();
+
+const emptyServer: Omit<MCPServerConfig, "id" | "createtime" | "updatetime"> = {
+  name: "",
+  url: "",
+  apiKey: "",
+  headers: {},
+  enabled: true,
+};
+
+function ServerCard({
+  server,
+  onEdit,
+  onDelete,
+  onToggle,
+  onTest,
+  onDetail,
+  testing,
+}: {
+  server: MCPServerConfig;
+  onEdit: () => void;
+  onDelete: () => void;
+  onToggle: (enabled: boolean) => void;
+  onTest: () => void;
+  onDetail: () => void;
+  testing: boolean;
+}) {
+  const { t } = useTranslation();
+
+  return (
+    <div
+      className={`tw-group tw-relative tw-rounded-xl tw-p-5 tw-transition-all tw-duration-200 tw-cursor-default ${
+        server.enabled
+          ? "tw-bg-[var(--color-bg-2)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.06)] hover:tw-shadow-[0_4px_16px_rgba(0,0,0,0.1)]"
+          : "tw-bg-[var(--color-bg-3)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.03)] tw-opacity-60"
+      }`}
+    >
+      {/* 顶部区域 */}
+      <div className="tw-flex tw-items-start tw-justify-between tw-mb-4">
+        <div className="tw-flex tw-items-center tw-gap-3">
+          <div className="tw-w-10 tw-h-10 tw-rounded-lg tw-flex tw-items-center tw-justify-center tw-text-xs tw-font-bold tw-shrink-0 tw-bg-[#e8f5e9] tw-text-[#2e7d32]">
+            {"MCP"}
+          </div>
+          <div className="tw-flex tw-flex-col tw-gap-0.5">
+            <Typography.Text className="tw-font-semibold tw-text-base !tw-mb-0">{server.name}</Typography.Text>
+            <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0 tw-break-all">
+              {server.url}
+            </Typography.Text>
+          </div>
+        </div>
+        <Switch size="small" checked={server.enabled} onChange={onToggle} />
+      </div>
+
+      {/* 信息区域 */}
+      <div className="tw-flex tw-flex-col tw-gap-2 tw-mb-4">
+        {server.apiKey && (
+          <div className="tw-flex tw-items-center tw-gap-2">
+            <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-min-w-16">{"API Key"}</span>
+            <Typography.Text type="secondary" className="tw-text-xs tw-font-mono !tw-mb-0">
+              {server.apiKey.length > 8
+                ? `${server.apiKey.slice(0, 4)}${"*".repeat(8)}${server.apiKey.slice(-4)}`
+                : "****"}
+            </Typography.Text>
+          </div>
+        )}
+        {server.headers && Object.keys(server.headers).length > 0 && (
+          <div className="tw-flex tw-items-center tw-gap-2">
+            <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-min-w-16">{"Headers"}</span>
+            <Tag size="small">
+              {Object.keys(server.headers).length} {"custom"}
+            </Tag>
+          </div>
+        )}
+      </div>
+
+      {/* 操作栏 */}
+      <div className="tw-flex tw-items-center tw-justify-end tw-gap-0.5 tw-pt-3 tw-border-t tw-border-solid tw-border-[var(--color-border-1)] tw-border-x-0 tw-border-b-0 tw-opacity-60 group-hover:tw-opacity-100 tw-transition-opacity">
+        <Button type="text" size="small" icon={<IconEye />} onClick={onDetail}>
+          {t("agent_mcp_detail")}
+        </Button>
+        <Button type="text" size="small" icon={<IconLink />} onClick={onTest} loading={testing}>
+          {t("agent_mcp_test_connection")}
+        </Button>
+        <Button type="text" size="small" icon={<IconEdit />} onClick={onEdit}>
+          {t("agent_model_edit")}
+        </Button>
+        <Popconfirm title={t("agent_model_delete_confirm")} onOk={onDelete}>
+          <Button type="text" size="small" status="danger" icon={<IconDelete />}>
+            {t("agent_model_delete")}
+          </Button>
+        </Popconfirm>
+      </div>
+    </div>
+  );
+}
+
+// 格式化 JSON Schema 参数概要
+function formatSchemaParams(inputSchema: Record<string, unknown>): string[] {
+  const properties = inputSchema.properties as Record<string, { description?: string }> | undefined;
+  const required = (inputSchema.required as string[]) || [];
+  if (!properties) return [];
+  return Object.keys(properties).map((name) => (required.includes(name) ? name : `${name}?`));
+}
+
+function ServerDetailDrawer({
+  server,
+  visible,
+  onClose,
+}: {
+  server: MCPServerConfig | null;
+  visible: boolean;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [tools, setTools] = useState<MCPTool[]>([]);
+  const [resources, setResources] = useState<MCPResource[]>([]);
+  const [prompts, setPrompts] = useState<MCPPrompt[]>([]);
+  const clientRef = useRef<MCPClient | null>(null);
+
+  useEffect(() => {
+    if (!visible || !server) return;
+
+    let cancelled = false;
+    const client = new MCPClient(server);
+    clientRef.current = client;
+
+    const load = async () => {
+      setLoading(true);
+      setError(null);
+      setTools([]);
+      setResources([]);
+      setPrompts([]);
+
+      try {
+        await client.initialize();
+        if (cancelled) return;
+
+        const [toolsResult, resourcesResult, promptsResult] = await Promise.all([
+          client.listTools().catch(() => [] as MCPTool[]),
+          client.listResources().catch(() => [] as MCPResource[]),
+          client.listPrompts().catch(() => [] as MCPPrompt[]),
+        ]);
+
+        if (!cancelled) {
+          setTools(toolsResult);
+          setResources(resourcesResult);
+          setPrompts(promptsResult);
+        }
+      } catch (e) {
+        if (!cancelled) {
+          setError(String(e));
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    load();
+
+    return () => {
+      cancelled = true;
+      client.close();
+      clientRef.current = null;
+    };
+  }, [visible, server]);
+
+  const handleClose = () => {
+    onClose();
+  };
+
+  return (
+    <Drawer width={520} title={server?.name || ""} visible={visible} onCancel={handleClose} footer={null} unmountOnExit>
+      {loading ? (
+        <div className="tw-flex tw-items-center tw-justify-center tw-py-16">
+          <Spin tip={t("agent_mcp_loading")} />
+        </div>
+      ) : error ? (
+        <div className="tw-py-8">
+          <Empty description={error} />
+        </div>
+      ) : (
+        <Tabs defaultActiveTab="tools">
+          <Tabs.TabPane key="tools" title={`${t("agent_mcp_tools")} (${tools.length})`}>
+            {tools.length === 0 ? (
+              <Empty className="tw-py-8" description={t("agent_mcp_no_tools")} />
+            ) : (
+              <div className="tw-flex tw-flex-col tw-gap-3 tw-py-2">
+                {tools.map((tool) => (
+                  <div key={tool.name} className="tw-rounded-lg tw-p-3 tw-bg-[var(--color-fill-1)]">
+                    <div className="tw-flex tw-items-center tw-gap-2 tw-mb-1">
+                      <Typography.Text className="tw-font-semibold tw-text-sm !tw-mb-0">{tool.name}</Typography.Text>
+                    </div>
+                    {tool.description && (
+                      <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0 tw-block tw-mb-1">
+                        {tool.description}
+                      </Typography.Text>
+                    )}
+                    {tool.inputSchema && formatSchemaParams(tool.inputSchema).length > 0 && (
+                      <div className="tw-mt-2 tw-flex tw-items-center tw-gap-1 tw-flex-wrap">
+                        <span className="tw-text-xs tw-text-[var(--color-text-3)]">
+                          {t("agent_mcp_parameters")}
+                          {":"}
+                        </span>
+                        {formatSchemaParams(tool.inputSchema).map((param) => (
+                          <Tag key={param} size="small" className="!tw-text-xs">
+                            {param}
+                          </Tag>
+                        ))}
+                      </div>
+                    )}
+                  </div>
+                ))}
+              </div>
+            )}
+          </Tabs.TabPane>
+
+          <Tabs.TabPane key="resources" title={`${t("agent_mcp_resources")} (${resources.length})`}>
+            {resources.length === 0 ? (
+              <Empty className="tw-py-8" description={t("agent_mcp_no_resources")} />
+            ) : (
+              <div className="tw-flex tw-flex-col tw-gap-3 tw-py-2">
+                {resources.map((resource) => (
+                  <div key={resource.uri} className="tw-rounded-lg tw-p-3 tw-bg-[var(--color-fill-1)]">
+                    <Typography.Text className="tw-font-semibold tw-text-sm !tw-mb-0">{resource.name}</Typography.Text>
+                    <Typography.Text type="secondary" className="tw-text-xs tw-font-mono !tw-mb-0 tw-block">
+                      {resource.uri}
+                    </Typography.Text>
+                    {resource.description && (
+                      <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0 tw-block tw-mt-1">
+                        {resource.description}
+                      </Typography.Text>
+                    )}
+                    {resource.mimeType && (
+                      <Tag size="small" className="tw-mt-1">
+                        {resource.mimeType}
+                      </Tag>
+                    )}
+                  </div>
+                ))}
+              </div>
+            )}
+          </Tabs.TabPane>
+
+          <Tabs.TabPane key="prompts" title={`${t("agent_mcp_prompts")} (${prompts.length})`}>
+            {prompts.length === 0 ? (
+              <Empty className="tw-py-8" description={t("agent_mcp_no_prompts")} />
+            ) : (
+              <div className="tw-flex tw-flex-col tw-gap-3 tw-py-2">
+                {prompts.map((prompt) => (
+                  <div key={prompt.name} className="tw-rounded-lg tw-p-3 tw-bg-[var(--color-fill-1)]">
+                    <Typography.Text className="tw-font-semibold tw-text-sm !tw-mb-0">{prompt.name}</Typography.Text>
+                    {prompt.description && (
+                      <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0 tw-block tw-mt-1">
+                        {prompt.description}
+                      </Typography.Text>
+                    )}
+                    {prompt.arguments && prompt.arguments.length > 0 && (
+                      <div className="tw-mt-2 tw-flex tw-items-center tw-gap-1 tw-flex-wrap">
+                        <span className="tw-text-xs tw-text-[var(--color-text-3)]">
+                          {t("agent_mcp_parameters")}
+                          {":"}
+                        </span>
+                        {prompt.arguments.map((arg) => (
+                          <Tag key={arg.name} size="small" className="!tw-text-xs">
+                            {arg.required ? arg.name : `${arg.name}?`}
+                          </Tag>
+                        ))}
+                      </div>
+                    )}
+                  </div>
+                ))}
+              </div>
+            )}
+          </Tabs.TabPane>
+        </Tabs>
+      )}
+    </Drawer>
+  );
+}
+
+function AgentMcp() {
+  const { t } = useTranslation();
+  const [servers, setServers] = useState<MCPServerConfig[]>([]);
+  const [modalVisible, setModalVisible] = useState(false);
+  const [editingServer, setEditingServer] = useState<Omit<MCPServerConfig, "id" | "createtime" | "updatetime">>({
+    ...emptyServer,
+  });
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [headersText, setHeadersText] = useState("");
+  const [testingId, setTestingId] = useState<string | null>(null);
+  const [modalTesting, setModalTesting] = useState(false);
+  const [detailServer, setDetailServer] = useState<MCPServerConfig | null>(null);
+  const [drawerVisible, setDrawerVisible] = useState(false);
+
+  const loadData = useCallback(async () => {
+    const list = await mcpServerRepo.listServers();
+    setServers(list);
+  }, []);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  const handleAdd = () => {
+    setEditingServer({ ...emptyServer });
+    setEditingId(null);
+    setHeadersText("");
+    setModalVisible(true);
+  };
+
+  const handleEdit = (server: MCPServerConfig) => {
+    setEditingServer({
+      name: server.name,
+      url: server.url,
+      apiKey: server.apiKey,
+      headers: server.headers,
+      enabled: server.enabled,
+    });
+    setEditingId(server.id);
+    setHeadersText(
+      server.headers
+        ? Object.entries(server.headers)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join("\n")
+        : ""
+    );
+    setModalVisible(true);
+  };
+
+  const handleDelete = async (id: string) => {
+    await mcpServerRepo.removeServer(id);
+    loadData();
+  };
+
+  const handleToggle = async (server: MCPServerConfig, enabled: boolean) => {
+    await mcpServerRepo.saveServer({ ...server, enabled, updatetime: Date.now() });
+    loadData();
+  };
+
+  const handleTest = async (server: MCPServerConfig) => {
+    setTestingId(server.id);
+    try {
+      await doTestConnection(server);
+    } finally {
+      setTestingId(null);
+    }
+  };
+
+  const doTestConnection = async (server: Pick<MCPServerConfig, "url" | "apiKey" | "headers">) => {
+    try {
+      const response = await fetch(server.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          ...(server.apiKey ? { Authorization: `Bearer ${server.apiKey}` } : {}),
+          ...(server.headers || {}),
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "initialize",
+          params: {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: "ScriptCat", version: "1.0.0" },
+          },
+        }),
+      });
+      if (response.ok) {
+        const json = await response.json();
+        if (json.result) {
+          const serverInfo = json.result.serverInfo;
+          Message.success(
+            `${t("agent_provider_test_success")}${serverInfo ? ` - ${serverInfo.name} ${serverInfo.version || ""}` : ""}`
+          );
+        } else if (json.error) {
+          Message.error(`${t("agent_provider_test_failed")}: ${json.error.message}`);
+        }
+      } else {
+        Message.error(`${t("agent_provider_test_failed")}: ${response.status}`);
+      }
+    } catch (e) {
+      Message.error(`${t("agent_provider_test_failed")}: ${e}`);
+    }
+  };
+
+  const handleModalTest = async () => {
+    if (!editingServer.url) {
+      Message.error(t("agent_mcp_name_url_required"));
+      return;
+    }
+    setModalTesting(true);
+    try {
+      const headers = parseHeaders(headersText);
+      await doTestConnection({ url: editingServer.url, apiKey: editingServer.apiKey, headers });
+    } finally {
+      setModalTesting(false);
+    }
+  };
+
+  const handleDetail = (server: MCPServerConfig) => {
+    setDetailServer(server);
+    setDrawerVisible(true);
+  };
+
+  const parseHeaders = (text: string): Record<string, string> => {
+    const headers: Record<string, string> = {};
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const idx = trimmed.indexOf(":");
+      if (idx > 0) {
+        headers[trimmed.slice(0, idx).trim()] = trimmed.slice(idx + 1).trim();
+      }
+    }
+    return headers;
+  };
+
+  const handleModalOk = async () => {
+    if (!editingServer.name || !editingServer.url) {
+      Message.error(t("agent_mcp_name_url_required"));
+      return;
+    }
+
+    const headers = parseHeaders(headersText);
+    const now = Date.now();
+
+    if (editingId) {
+      // 编辑
+      const existing = servers.find((s) => s.id === editingId);
+      if (existing) {
+        await mcpServerRepo.saveServer({
+          ...existing,
+          name: editingServer.name,
+          url: editingServer.url,
+          apiKey: editingServer.apiKey,
+          headers,
+          enabled: editingServer.enabled,
+          updatetime: now,
+        });
+      }
+    } else {
+      // 新增
+      await mcpServerRepo.saveServer({
+        id: uuidv4(),
+        name: editingServer.name,
+        url: editingServer.url,
+        apiKey: editingServer.apiKey,
+        headers,
+        enabled: editingServer.enabled,
+        createtime: now,
+        updatetime: now,
+      });
+    }
+
+    setModalVisible(false);
+    loadData();
+  };
+
+  return (
+    <Space className="tw-w-full tw-h-full tw-overflow-auto tw-relative" direction="vertical">
+      <Card
+        title={t("agent_mcp_title")}
+        bordered={false}
+        extra={
+          <Button type="primary" icon={<IconPlus />} onClick={handleAdd}>
+            {t("agent_mcp_add_server")}
+          </Button>
+        }
+      >
+        {servers.length === 0 ? (
+          <div className="tw-py-12">
+            <Empty description={t("agent_mcp_no_servers")} />
+          </div>
+        ) : (
+          <div className="tw-grid tw-grid-cols-1 md:tw-grid-cols-2 tw-gap-4">
+            {servers.map((server) => (
+              <ServerCard
+                key={server.id}
+                server={server}
+                onEdit={() => handleEdit(server)}
+                onDelete={() => handleDelete(server.id)}
+                onToggle={(enabled) => handleToggle(server, enabled)}
+                onTest={() => handleTest(server)}
+                onDetail={() => handleDetail(server)}
+                testing={testingId === server.id}
+              />
+            ))}
+          </div>
+        )}
+      </Card>
+
+      <Modal
+        title={editingId ? t("agent_model_edit") : t("agent_mcp_add_server")}
+        visible={modalVisible}
+        onOk={handleModalOk}
+        onCancel={() => setModalVisible(false)}
+        autoFocus={false}
+        focusLock
+        unmountOnExit
+      >
+        <Space direction="vertical" size={20} className="tw-w-full">
+          {/* 名称 */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_model_name")}
+            </div>
+            <Input
+              value={editingServer.name}
+              placeholder="My MCP Server"
+              onChange={(value) => setEditingServer((prev) => ({ ...prev, name: value }))}
+            />
+          </div>
+
+          {/* URL */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">{"URL"}</div>
+            <Input
+              value={editingServer.url}
+              placeholder="https://example.com/mcp"
+              onChange={(value) => setEditingServer((prev) => ({ ...prev, url: value }))}
+            />
+          </div>
+
+          {/* API Key */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {"API Key ("}
+              {t("agent_mcp_optional")}
+              {")"}
+            </div>
+            <Input.Password
+              value={editingServer.apiKey}
+              onChange={(value) => setEditingServer((prev) => ({ ...prev, apiKey: value }))}
+            />
+          </div>
+
+          {/* 自定义 Headers */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_mcp_custom_headers")} {"("}
+              {t("agent_mcp_optional")}
+              {")"}
+            </div>
+            <Input.TextArea
+              value={headersText}
+              placeholder={"X-Custom-Header: value\nAnother-Header: value"}
+              autoSize={{ minRows: 2, maxRows: 5 }}
+              onChange={(value) => setHeadersText(value)}
+            />
+          </div>
+
+          {/* 启用 */}
+          <div className="tw-flex tw-items-center tw-gap-3">
+            <span className="tw-text-sm tw-font-medium tw-text-[var(--color-text-2)]">{t("agent_mcp_enabled")}</span>
+            <Switch
+              checked={editingServer.enabled}
+              onChange={(checked) => setEditingServer((prev) => ({ ...prev, enabled: checked }))}
+            />
+          </div>
+
+          {/* 测试连接 */}
+          <Button type="outline" icon={<IconLink />} loading={modalTesting} onClick={handleModalTest} long>
+            {t("agent_provider_test_connection")}
+          </Button>
+        </Space>
+      </Modal>
+
+      <ServerDetailDrawer server={detailServer} visible={drawerVisible} onClose={() => setDrawerVisible(false)} />
+    </Space>
+  );
+}
+
+export default AgentMcp;
diff --git a/src/pages/options/routes/AgentOPFS.tsx b/src/pages/options/routes/AgentOPFS.tsx
new file mode 100644
index 000000000..68e15e76b
--- /dev/null
+++ b/src/pages/options/routes/AgentOPFS.tsx
@@ -0,0 +1,226 @@
+import { useCallback, useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Breadcrumb, Button, Card, Empty, Message, Modal, Space, Table } from "@arco-design/web-react";
+import { IconDelete, IconFolder, IconFile } from "@arco-design/web-react/icon";
+
+interface FileEntry {
+  name: string;
+  kind: "file" | "directory";
+  size?: number;
+  lastModified?: number;
+}
+
+// 格式化文件大小
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function AgentOPFS() {
+  const { t } = useTranslation();
+  const [path, setPath] = useState<string[]>(["agents"]);
+  const [entries, setEntries] = useState<FileEntry[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [previewContent, setPreviewContent] = useState<string | null>(null);
+  const [previewName, setPreviewName] = useState("");
+
+  // 获取指定路径的目录句柄
+  const getDirHandle = useCallback(async (pathParts: string[]) => {
+    let dir = await navigator.storage.getDirectory();
+    for (const part of pathParts) {
+      dir = await dir.getDirectoryHandle(part);
+    }
+    return dir;
+  }, []);
+
+  // 加载目录内容
+  const loadDirectory = useCallback(
+    async (pathParts: string[]) => {
+      setLoading(true);
+      try {
+        const dir = await getDirHandle(pathParts);
+        const items: FileEntry[] = [];
+        for await (const [name, handle] of dir as any) {
+          const entry: FileEntry = { name, kind: handle.kind };
+          if (handle.kind === "file") {
+            try {
+              const file = await (handle as FileSystemFileHandle).getFile();
+              entry.size = file.size;
+              entry.lastModified = file.lastModified;
+            } catch {
+              // 忽略无法读取的文件
+            }
+          }
+          items.push(entry);
+        }
+        // 目录排前面，同类型按名称排序
+        items.sort((a, b) => {
+          if (a.kind !== b.kind) return a.kind === "directory" ? -1 : 1;
+          return a.name.localeCompare(b.name);
+        });
+        setEntries(items);
+      } catch (e) {
+        console.error("Failed to load OPFS directory:", e);
+        setEntries([]);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [getDirHandle]
+  );
+
+  useEffect(() => {
+    loadDirectory(path);
+  }, [path, loadDirectory]);
+
+  // 进入子目录
+  const enterDirectory = (name: string) => {
+    setPath((prev) => [...prev, name]);
+  };
+
+  // 面包屑导航跳转，-1 表示跳转到 OPFS 根目录
+  const navigateTo = (index: number) => {
+    if (index < 0) {
+      setPath([]);
+    } else {
+      setPath((prev) => prev.slice(0, index));
+    }
+  };
+
+  // 预览文件
+  const previewFile = async (name: string) => {
+    try {
+      const dir = await getDirHandle(path);
+      const fileHandle = await dir.getFileHandle(name);
+      const file = await fileHandle.getFile();
+      const text = await file.text();
+      // 尝试 JSON 格式化
+      try {
+        const json = JSON.parse(text);
+        setPreviewContent(JSON.stringify(json, null, 2));
+      } catch {
+        setPreviewContent(text);
+      }
+      setPreviewName(name);
+    } catch (e) {
+      Message.error(String(e));
+    }
+  };
+
+  // 删除文件或目录
+  const deleteEntry = (name: string, kind: "file" | "directory") => {
+    Modal.confirm({
+      title: t("agent_opfs_delete_confirm"),
+      onOk: async () => {
+        try {
+          const dir = await getDirHandle(path);
+          await dir.removeEntry(name, { recursive: kind === "directory" });
+          Message.success(t("agent_opfs_delete_success"));
+          loadDirectory(path);
+        } catch (e) {
+          Message.error(String(e));
+        }
+      },
+    });
+  };
+
+  const columns = [
+    {
+      title: t("agent_opfs_name"),
+      dataIndex: "name",
+      render: (name: string, record: FileEntry) => (
+        <span
+          style={{ cursor: "pointer" }}
+          onClick={() => (record.kind === "directory" ? enterDirectory(name) : previewFile(name))}
+        >
+          {record.kind === "directory" ? <IconFolder className="tw-mr-1" /> : <IconFile className="tw-mr-1" />}
+          {name}
+        </span>
+      ),
+    },
+    {
+      title: t("agent_opfs_type"),
+      dataIndex: "kind",
+      width: 100,
+      render: (kind: string) => (kind === "directory" ? t("agent_opfs_directory") : t("agent_opfs_file")),
+    },
+    {
+      title: t("agent_opfs_size"),
+      dataIndex: "size",
+      width: 120,
+      sorter: (a: FileEntry, b: FileEntry) => {
+        // 目录始终排在最前面
+        if (a.kind !== b.kind) return a.kind === "directory" ? -1 : 1;
+        return (a.size ?? 0) - (b.size ?? 0);
+      },
+      render: (size?: number) => (size !== undefined ? formatSize(size) : "-"),
+    },
+    {
+      title: t("agent_opfs_modified"),
+      dataIndex: "lastModified",
+      width: 180,
+      defaultSortOrder: "descend" as const,
+      sorter: (a: FileEntry, b: FileEntry) => {
+        // 目录始终排在最前面
+        if (a.kind !== b.kind) return a.kind === "directory" ? -1 : 1;
+        return (a.lastModified ?? 0) - (b.lastModified ?? 0);
+      },
+      render: (ts?: number) => (ts ? new Date(ts).toLocaleString() : "-"),
+    },
+    {
+      title: "",
+      dataIndex: "actions",
+      width: 80,
+      render: (_: unknown, record: FileEntry) => (
+        <Space>
+          <Button
+            type="text"
+            status="danger"
+            icon={<IconDelete />}
+            size="small"
+            onClick={() => deleteEntry(record.name, record.kind)}
+          />
+        </Space>
+      ),
+    },
+  ];
+
+  return (
+    <Space className="tw-w-full tw-h-full tw-overflow-auto tw-relative" direction="vertical">
+      <Card bordered={false} title={t("agent_opfs_title")}>
+        <Breadcrumb style={{ marginBottom: 16 }}>
+          <Breadcrumb.Item onClick={() => navigateTo(-1)} style={{ cursor: "pointer" }}>
+            {t("agent_opfs_root")}
+          </Breadcrumb.Item>
+          {path.map((part, index) => (
+            <Breadcrumb.Item key={index} onClick={() => navigateTo(index + 1)} style={{ cursor: "pointer" }}>
+              {part}
+            </Breadcrumb.Item>
+          ))}
+        </Breadcrumb>
+        <Table
+          columns={columns}
+          data={entries}
+          rowKey="name"
+          loading={loading}
+          pagination={false}
+          noDataElement={<Empty description={t("agent_opfs_empty")} />}
+        />
+      </Card>
+      <Modal
+        title={`${t("agent_opfs_preview")} - ${previewName}`}
+        visible={previewContent !== null}
+        onCancel={() => setPreviewContent(null)}
+        footer={null}
+        style={{ width: 700 }}
+      >
+        <pre style={{ maxHeight: 500, overflow: "auto", whiteSpace: "pre-wrap", wordBreak: "break-all" }}>
+          {previewContent}
+        </pre>
+      </Modal>
+    </Space>
+  );
+}
+
+export default AgentOPFS;
diff --git a/src/pages/options/routes/AgentProvider.tsx b/src/pages/options/routes/AgentProvider.tsx
new file mode 100644
index 000000000..3b23b1259
--- /dev/null
+++ b/src/pages/options/routes/AgentProvider.tsx
@@ -0,0 +1,392 @@
+import {
+  Button,
+  Card,
+  Empty,
+  Input,
+  Message,
+  Modal,
+  Popconfirm,
+  Select,
+  Space,
+  Tag,
+  Tooltip,
+  Typography,
+} from "@arco-design/web-react";
+import { IconCheck, IconDelete, IconEdit, IconPlus } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { useCallback, useEffect, useState } from "react";
+import type { AgentModelConfig } from "@App/app/service/agent/types";
+import { AgentModelRepo } from "@App/app/repo/agent_model";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+
+const agentModelRepo = new AgentModelRepo();
+
+const emptyModel: AgentModelConfig = {
+  id: "",
+  name: "",
+  provider: "openai",
+  apiBaseUrl: "",
+  apiKey: "",
+  model: "",
+};
+
+// Provider 配色方案
+const providerTheme: Record<string, { bg: string; text: string; accent: string; label: string }> = {
+  openai: {
+    bg: "tw-bg-[#f0fdf4]",
+    text: "tw-text-[#16a34a]",
+    accent: "#16a34a",
+    label: "OpenAI",
+  },
+  anthropic: {
+    bg: "tw-bg-[#fef3e2]",
+    text: "tw-text-[#d97706]",
+    accent: "#d97706",
+    label: "Anthropic",
+  },
+};
+
+function ModelCard({
+  model,
+  isDefault,
+  onEdit,
+  onDelete,
+  onSetDefault,
+  t,
+}: {
+  model: AgentModelConfig;
+  isDefault: boolean;
+  onEdit: () => void;
+  onDelete: () => void;
+  onSetDefault: () => void;
+  t: (key: string) => string;
+}) {
+  const theme = providerTheme[model.provider] || providerTheme.openai;
+  // 遮蔽 API Key，只显示前4位和后4位
+  const maskedKey =
+    model.apiKey && model.apiKey.length > 8
+      ? `${model.apiKey.slice(0, 4)}${"*".repeat(8)}${model.apiKey.slice(-4)}`
+      : "****";
+
+  return (
+    <div
+      className={`tw-group tw-relative tw-rounded-xl tw-p-5 tw-transition-all tw-duration-200 tw-cursor-default ${
+        isDefault
+          ? "tw-bg-[rgb(var(--arcoblue-1))] tw-shadow-[0_0_0_1.5px_rgb(var(--arcoblue-6)),0_2px_8px_rgba(0,0,0,0.06)]"
+          : "tw-bg-[var(--color-bg-2)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.06)] hover:tw-shadow-[0_4px_16px_rgba(0,0,0,0.1)]"
+      }`}
+    >
+      {/* 顶部区域 */}
+      <div className="tw-flex tw-items-start tw-justify-between tw-mb-4">
+        <div className="tw-flex tw-items-center tw-gap-3">
+          {/* Provider 色块标识 */}
+          <div
+            className={`tw-w-10 tw-h-10 tw-rounded-lg tw-flex tw-items-center tw-justify-center tw-text-xs tw-font-bold tw-shrink-0 ${theme.bg} ${theme.text}`}
+          >
+            {model.provider === "openai" ? "AI" : "An"}
+          </div>
+          <div className="tw-flex tw-flex-col tw-gap-0.5">
+            <div className="tw-flex tw-items-center tw-gap-2">
+              <Typography.Text className="tw-font-semibold tw-text-base !tw-mb-0">{model.name}</Typography.Text>
+              {isDefault && (
+                <Tag size="small" color="arcoblue">
+                  {t("agent_model_default_label")}
+                </Tag>
+              )}
+            </div>
+            <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+              {theme.label}
+            </Typography.Text>
+          </div>
+        </div>
+      </div>
+
+      {/* 信息区域 */}
+      <div className="tw-flex tw-flex-col tw-gap-2 tw-mb-4">
+        <div className="tw-flex tw-items-center tw-gap-2">
+          <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-min-w-12">{t("agent_provider_model")}</span>
+          <Tag className="!tw-rounded-md" size="small">
+            {model.model}
+          </Tag>
+        </div>
+        <div className="tw-flex tw-items-center tw-gap-2">
+          <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-min-w-12">{"API Key"}</span>
+          <Typography.Text type="secondary" className="tw-text-xs tw-font-mono !tw-mb-0">
+            {maskedKey}
+          </Typography.Text>
+        </div>
+      </div>
+
+      {/* 操作栏 - 悬停时更明显 */}
+      <div className="tw-flex tw-items-center tw-justify-end tw-gap-0.5 tw-pt-3 tw-border-t tw-border-solid tw-border-[var(--color-border-1)] tw-border-x-0 tw-border-b-0 tw-opacity-60 group-hover:tw-opacity-100 tw-transition-opacity">
+        {!isDefault && (
+          <Tooltip content={t("agent_model_set_default")}>
+            <Button type="text" size="small" icon={<IconCheck />} onClick={onSetDefault}>
+              {t("agent_model_set_default")}
+            </Button>
+          </Tooltip>
+        )}
+        <Button type="text" size="small" icon={<IconEdit />} onClick={onEdit}>
+          {t("agent_model_edit")}
+        </Button>
+        <Popconfirm title={t("agent_model_delete_confirm")} onOk={onDelete}>
+          <Button type="text" size="small" status="danger" icon={<IconDelete />}>
+            {t("agent_model_delete")}
+          </Button>
+        </Popconfirm>
+      </div>
+    </div>
+  );
+}
+
+function AgentProvider() {
+  const { t } = useTranslation();
+  const [models, setModels] = useState<AgentModelConfig[]>([]);
+  const [defaultModelId, setDefaultModelId] = useState("");
+  const [modalVisible, setModalVisible] = useState(false);
+  const [editingModel, setEditingModel] = useState<AgentModelConfig>({ ...emptyModel });
+  const [isEditing, setIsEditing] = useState(false);
+  const [availableModels, setAvailableModels] = useState<string[]>([]);
+  const [fetchingModels, setFetchingModels] = useState(false);
+
+  // 从 Repo 加载数据
+  const loadData = useCallback(async () => {
+    const [modelList, defId] = await Promise.all([agentModelRepo.listModels(), agentModelRepo.getDefaultModelId()]);
+    setModels(modelList);
+    setDefaultModelId(defId);
+  }, []);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  const handleAdd = () => {
+    setEditingModel({ ...emptyModel });
+    setIsEditing(false);
+    setAvailableModels([]);
+    setModalVisible(true);
+  };
+
+  const handleEdit = (record: AgentModelConfig) => {
+    setEditingModel({ ...record });
+    setIsEditing(true);
+    setAvailableModels([]);
+    setModalVisible(true);
+  };
+
+  const handleDelete = async (id: string) => {
+    await agentModelRepo.removeModel(id);
+    if (defaultModelId === id) {
+      const remaining = models.filter((m) => m.id !== id);
+      await agentModelRepo.setDefaultModelId(remaining[0]?.id || "");
+    }
+    loadData();
+  };
+
+  const handleSetDefault = async (id: string) => {
+    await agentModelRepo.setDefaultModelId(id);
+    loadData();
+  };
+
+  const handleModalOk = async () => {
+    if (!editingModel.name || !editingModel.model) {
+      Message.error(t("agent_model_name") + " / " + t("agent_provider_model") + " required");
+      return;
+    }
+    if (isEditing) {
+      await agentModelRepo.saveModel(editingModel);
+    } else {
+      const newModel = { ...editingModel, id: uuidv4() };
+      await agentModelRepo.saveModel(newModel);
+      // 如果是第一个模型，自动设为默认
+      if (models.length === 0) {
+        await agentModelRepo.setDefaultModelId(newModel.id);
+      }
+    }
+    setModalVisible(false);
+    loadData();
+  };
+
+  const buildProviderRequest = (m: AgentModelConfig) => {
+    const baseUrl =
+      m.apiBaseUrl || (m.provider === "openai" ? "https://api.openai.com/v1" : "https://api.anthropic.com");
+    const headers: Record<string, string> = {};
+    let modelsUrl: string;
+    if (m.provider === "anthropic") {
+      modelsUrl = `${baseUrl}/v1/models`;
+      headers["x-api-key"] = m.apiKey;
+      headers["anthropic-version"] = "2023-06-01";
+      headers["anthropic-dangerous-direct-browser-access"] = "true";
+    } else {
+      modelsUrl = `${baseUrl}/models`;
+      if (m.apiKey) {
+        headers["Authorization"] = `Bearer ${m.apiKey}`;
+      }
+    }
+    return { modelsUrl, headers };
+  };
+
+  const handleTestConnection = async () => {
+    try {
+      const { modelsUrl, headers } = buildProviderRequest(editingModel);
+      const resp = await fetch(modelsUrl, { method: "GET", headers });
+      if (resp.ok) {
+        Message.success(t("agent_provider_test_success")!);
+      } else {
+        Message.error(`${t("agent_provider_test_failed")}: ${resp.status}`);
+      }
+    } catch (e) {
+      Message.error(`${t("agent_provider_test_failed")}: ${e}`);
+    }
+  };
+
+  const handleFetchModels = async () => {
+    setFetchingModels(true);
+    try {
+      const { modelsUrl, headers } = buildProviderRequest(editingModel);
+      const resp = await fetch(modelsUrl, { method: "GET", headers });
+      if (!resp.ok) {
+        Message.error(`${t("agent_model_fetch_failed")}: ${resp.status}`);
+        return;
+      }
+      const json = await resp.json();
+      const ids: string[] = (json.data || []).map((item: { id: string }) => item.id);
+      setAvailableModels(ids);
+    } catch (e) {
+      Message.error(`${t("agent_model_fetch_failed")}: ${e}`);
+    } finally {
+      setFetchingModels(false);
+    }
+  };
+
+  return (
+    <Space className="tw-w-full tw-h-full tw-overflow-auto tw-relative" direction="vertical">
+      <Card
+        title={t("agent_provider_title")}
+        bordered={false}
+        extra={
+          <Button type="primary" icon={<IconPlus />} onClick={handleAdd}>
+            {t("agent_model_add")}
+          </Button>
+        }
+      >
+        {models.length === 0 ? (
+          <div className="tw-py-12">
+            <Empty description={t("agent_model_no_models")} />
+          </div>
+        ) : (
+          <div className="tw-grid tw-grid-cols-1 md:tw-grid-cols-2 tw-gap-4">
+            {models.map((model) => (
+              <ModelCard
+                key={model.id}
+                model={model}
+                isDefault={model.id === defaultModelId}
+                onEdit={() => handleEdit(model)}
+                onDelete={() => handleDelete(model.id)}
+                onSetDefault={() => handleSetDefault(model.id)}
+                t={t}
+              />
+            ))}
+          </div>
+        )}
+      </Card>
+
+      <Modal
+        title={isEditing ? t("agent_model_edit") : t("agent_model_add")}
+        visible={modalVisible}
+        onOk={handleModalOk}
+        onCancel={() => setModalVisible(false)}
+        autoFocus={false}
+        focusLock
+        unmountOnExit
+      >
+        <Space direction="vertical" size={20} className="tw-w-full">
+          {/* 名称 */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_model_name")}
+            </div>
+            <Input
+              value={editingModel.name}
+              placeholder="GPT-4o / Claude Sonnet"
+              onChange={(value) => setEditingModel((prev) => ({ ...prev, name: value }))}
+            />
+          </div>
+
+          {/* Provider */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_provider_select")}
+            </div>
+            <Select
+              value={editingModel.provider}
+              onChange={(value) => setEditingModel((prev) => ({ ...prev, provider: value }))}
+            >
+              <Select.Option value="openai">{"OpenAI"}</Select.Option>
+              <Select.Option value="anthropic">{"Anthropic"}</Select.Option>
+            </Select>
+          </div>
+
+          {/* API Base URL */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_provider_api_base_url")}
+            </div>
+            <Input
+              value={editingModel.apiBaseUrl}
+              placeholder={
+                editingModel.provider === "openai" ? "https://api.openai.com/v1" : "https://api.anthropic.com"
+              }
+              onChange={(value) => setEditingModel((prev) => ({ ...prev, apiBaseUrl: value }))}
+            />
+          </div>
+
+          {/* API Key */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">{"API Key"}</div>
+            <Input.Password
+              value={editingModel.apiKey}
+              onChange={(value) => setEditingModel((prev) => ({ ...prev, apiKey: value }))}
+            />
+          </div>
+
+          {/* 模型 */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_provider_model")}
+            </div>
+            <div className="tw-flex tw-gap-2">
+              <Select
+                className="tw-flex-1"
+                showSearch
+                allowClear
+                allowCreate
+                value={editingModel.model || undefined}
+                placeholder="gpt-4o / claude-sonnet-4-20250514"
+                onChange={(value) => setEditingModel((prev) => ({ ...prev, model: value || "" }))}
+              >
+                {availableModels.map((id) => (
+                  <Select.Option key={id} value={id}>
+                    {id}
+                  </Select.Option>
+                ))}
+              </Select>
+              <Button type="outline" loading={fetchingModels} onClick={handleFetchModels}>
+                {t("agent_model_fetch")}
+              </Button>
+            </div>
+          </div>
+
+          {/* 测试连接 */}
+          <div className="tw-flex tw-justify-end tw-pt-2">
+            <Button type="outline" onClick={handleTestConnection}>
+              {t("agent_provider_test_connection")}
+            </Button>
+          </div>
+        </Space>
+      </Modal>
+    </Space>
+  );
+}
+
+export default AgentProvider;
diff --git a/src/pages/options/routes/AgentSkills.tsx b/src/pages/options/routes/AgentSkills.tsx
new file mode 100644
index 000000000..dabc15627
--- /dev/null
+++ b/src/pages/options/routes/AgentSkills.tsx
@@ -0,0 +1,577 @@
+import {
+  Button,
+  Card,
+  Empty,
+  Input,
+  InputNumber,
+  Message,
+  Modal,
+  Popconfirm,
+  Select,
+  Space,
+  Switch,
+  Tag,
+  Typography,
+} from "@arco-design/web-react";
+import { IconDelete, IconEye, IconPlus, IconRefresh, IconSettings } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type {
+  SkillSummary,
+  SkillRecord,
+  SkillReference,
+  CATToolRecord,
+  SkillConfigField,
+} from "@App/app/service/agent/types";
+import { SkillRepo } from "@App/app/repo/skill_repo";
+import { agentClient } from "@App/pages/store/features/script";
+
+const skillRepo = new SkillRepo();
+
+// ---- Skill Card ----
+
+function SkillCard({
+  skill,
+  onDetail,
+  onUninstall,
+  onRefresh,
+  onConfig,
+  t,
+}: {
+  skill: SkillSummary;
+  onDetail: () => void;
+  onUninstall: () => void;
+  onRefresh: () => void;
+  onConfig?: () => void;
+  t: (key: string, opts?: Record<string, string>) => string;
+}) {
+  return (
+    <div className="tw-group tw-relative tw-rounded-xl tw-p-5 tw-transition-all tw-duration-200 tw-cursor-default tw-bg-[var(--color-bg-2)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.06)] hover:tw-shadow-[0_4px_16px_rgba(0,0,0,0.1)]">
+      {/* Header */}
+      <div className="tw-flex tw-items-start tw-justify-between tw-mb-3">
+        <div className="tw-flex tw-items-center tw-gap-3">
+          <div className="tw-w-10 tw-h-10 tw-rounded-lg tw-flex tw-items-center tw-justify-center tw-text-xs tw-font-bold tw-shrink-0 tw-bg-[rgb(var(--arcoblue-1))] tw-text-[rgb(var(--arcoblue-6))]">
+            {"Sk"}
+          </div>
+          <div className="tw-flex tw-flex-col tw-gap-0.5">
+            <Typography.Text className="tw-font-semibold tw-text-base !tw-mb-0">{skill.name}</Typography.Text>
+            {skill.description && (
+              <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+                {skill.description}
+              </Typography.Text>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Tags */}
+      <div className="tw-flex tw-flex-wrap tw-gap-1.5 tw-mb-3">
+        {skill.toolNames.length > 0 && (
+          <Tag size="small" color="arcoblue">
+            {t("agent_skills_tools")}
+            {": "}
+            {skill.toolNames.length}
+          </Tag>
+        )}
+        {skill.referenceNames.length > 0 && (
+          <Tag size="small" color="green">
+            {t("agent_skills_references")}
+            {": "}
+            {skill.referenceNames.length}
+          </Tag>
+        )}
+        {skill.hasConfig && (
+          <Tag size="small" color="orange">
+            {t("agent_skills_config")}
+          </Tag>
+        )}
+      </div>
+
+      {/* Install time */}
+      <div className="tw-text-xs tw-text-[var(--color-text-3)] tw-mb-3">
+        {t("agent_skills_installed_at")}
+        {": "}
+        {new Date(skill.installtime).toLocaleString()}
+      </div>
+
+      {/* Actions */}
+      <div className="tw-flex tw-items-center tw-justify-end tw-gap-0.5 tw-pt-3 tw-border-t tw-border-solid tw-border-[var(--color-border-1)] tw-border-x-0 tw-border-b-0 tw-opacity-60 group-hover:tw-opacity-100 tw-transition-opacity">
+        <Button type="text" size="small" icon={<IconEye />} onClick={onDetail}>
+          {t("agent_skills_detail")}
+        </Button>
+        {skill.hasConfig && onConfig && (
+          <Button type="text" size="small" icon={<IconSettings />} onClick={onConfig}>
+            {t("agent_skills_config")}
+          </Button>
+        )}
+        <Button type="text" size="small" icon={<IconRefresh />} onClick={onRefresh}>
+          {t("agent_skills_refresh")}
+        </Button>
+        <Popconfirm title={t("agent_skills_uninstall_confirm", { name: skill.name })} onOk={onUninstall}>
+          <Button type="text" size="small" status="danger" icon={<IconDelete />}>
+            {t("agent_skills_uninstall")}
+          </Button>
+        </Popconfirm>
+      </div>
+    </div>
+  );
+}
+
+// ---- Tool Code Viewer Modal ----
+
+function ToolCodeModal({
+  visible,
+  tool,
+  onClose,
+  t,
+}: {
+  visible: boolean;
+  tool: CATToolRecord | null;
+  onClose: () => void;
+  t: (key: string) => string;
+}) {
+  if (!tool) return null;
+
+  return (
+    <Modal
+      title={`${t("agent_skills_tool_code")} - ${tool.name}`}
+      visible={visible}
+      onCancel={onClose}
+      footer={
+        <Button type="primary" onClick={onClose}>
+          {t("confirm")}
+        </Button>
+      }
+      autoFocus={false}
+      focusLock
+      unmountOnExit
+      style={{ width: 720 }}
+    >
+      <pre
+        style={{
+          background: "var(--color-fill-2)",
+          borderRadius: 8,
+          padding: 16,
+          fontSize: 13,
+          fontFamily: "monospace",
+          overflow: "auto",
+          maxHeight: 480,
+          margin: 0,
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-all",
+        }}
+      >
+        {tool.code}
+      </pre>
+    </Modal>
+  );
+}
+
+// ---- Config Modal ----
+
+function SkillConfigModal({
+  visible,
+  skill,
+  onClose,
+  t,
+}: {
+  visible: boolean;
+  skill: SkillRecord | null;
+  onClose: () => void;
+  t: (key: string) => string;
+}) {
+  const [values, setValues] = useState<Record<string, unknown>>({});
+  const [saving, setSaving] = useState(false);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (visible && skill?.config) {
+      setLoading(true);
+      agentClient
+        .getSkillConfigValues(skill.name)
+        .then((saved) => {
+          // 用 default 值填充未保存的字段
+          const merged: Record<string, unknown> = {};
+          for (const [key, field] of Object.entries(skill.config!)) {
+            merged[key] = saved[key] !== undefined ? saved[key] : (field.default ?? "");
+          }
+          setValues(merged);
+        })
+        .catch(() => {
+          // 初始化为默认值
+          const defaults: Record<string, unknown> = {};
+          for (const [key, field] of Object.entries(skill.config!)) {
+            defaults[key] = field.default ?? "";
+          }
+          setValues(defaults);
+        })
+        .finally(() => setLoading(false));
+    }
+  }, [visible, skill]);
+
+  const handleSave = async () => {
+    if (!skill) return;
+    setSaving(true);
+    try {
+      await agentClient.saveSkillConfig({ name: skill.name, values });
+      Message.success(t("agent_skills_config_saved"));
+      onClose();
+    } catch (e: any) {
+      Message.error(e.message || String(e));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (!skill?.config) return null;
+
+  const renderField = (key: string, field: SkillConfigField) => {
+    const value = values[key];
+    const onChange = (v: unknown) => setValues((prev) => ({ ...prev, [key]: v }));
+    const label = (
+      <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">
+        {field.title || key}
+        {field.required && <span className="tw-text-red-500 tw-ml-0.5">{"*"}</span>}
+      </div>
+    );
+
+    switch (field.type) {
+      case "number":
+        return (
+          <div key={key}>
+            {label}
+            <InputNumber value={value as number} onChange={(v) => onChange(v)} className="tw-w-full" />
+          </div>
+        );
+      case "select":
+        return (
+          <div key={key}>
+            {label}
+            <Select value={value as string} onChange={(v) => onChange(v)} className="tw-w-full">
+              {(field.values || []).map((v) => (
+                <Select.Option key={v} value={v}>
+                  {v}
+                </Select.Option>
+              ))}
+            </Select>
+          </div>
+        );
+      case "switch":
+        return (
+          <div key={key} className="tw-flex tw-items-center tw-justify-between">
+            <span className="tw-text-sm tw-font-medium tw-text-[var(--color-text-2)]">
+              {field.title || key}
+              {field.required && <span className="tw-text-red-500 tw-ml-0.5">{"*"}</span>}
+            </span>
+            <Switch checked={!!value} onChange={(v) => onChange(v)} />
+          </div>
+        );
+      default: // text
+        return (
+          <div key={key}>
+            {label}
+            {field.secret ? (
+              <Input.Password value={String(value || "")} onChange={(v) => onChange(v)} />
+            ) : (
+              <Input value={String(value || "")} onChange={(v) => onChange(v)} />
+            )}
+          </div>
+        );
+    }
+  };
+
+  return (
+    <Modal
+      title={`${t("agent_skills_config")} - ${skill.name}`}
+      visible={visible}
+      onOk={handleSave}
+      onCancel={onClose}
+      confirmLoading={saving}
+      autoFocus={false}
+      focusLock
+      unmountOnExit
+      style={{ width: 520 }}
+    >
+      {loading ? (
+        <div className="tw-py-8 tw-text-center tw-text-[var(--color-text-3)]">{"Loading..."}</div>
+      ) : (
+        <Space direction="vertical" size={12} className="tw-w-full">
+          {Object.entries(skill.config).map(([key, field]) => renderField(key, field))}
+        </Space>
+      )}
+    </Modal>
+  );
+}
+
+// ---- Detail/Edit Modal ----
+
+function SkillDetailModal({
+  visible,
+  skill,
+  onClose,
+  onSaved,
+  t,
+}: {
+  visible: boolean;
+  skill: SkillRecord | null;
+  onClose: () => void;
+  onSaved: () => void;
+  t: (key: string) => string;
+}) {
+  const [prompt, setPrompt] = useState("");
+  const [scripts, setScripts] = useState<CATToolRecord[]>([]);
+  const [references, setReferences] = useState<SkillReference[]>([]);
+  const [saving, setSaving] = useState(false);
+  const [viewingTool, setViewingTool] = useState<CATToolRecord | null>(null);
+
+  useEffect(() => {
+    if (skill) {
+      setPrompt(skill.prompt);
+      // Load scripts and references
+      skillRepo.getSkillScripts(skill.name).then(setScripts);
+      skillRepo.getSkillReferences(skill.name).then(setReferences);
+    }
+  }, [skill]);
+
+  const handleSave = async () => {
+    if (!skill) return;
+    setSaving(true);
+    try {
+      const skillMd = `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n${prompt}`;
+      await agentClient.installSkill({
+        skillMd,
+        scripts: scripts.map((s) => ({ name: s.name, code: s.code })),
+        references: references.map((r) => ({ name: r.name, content: r.content })),
+      });
+      Message.success(t("agent_skills_save_success"));
+      onSaved();
+      onClose();
+    } catch (e: any) {
+      Message.error(e.message || String(e));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (!skill) return null;
+
+  return (
+    <>
+      <Modal
+        title={t("agent_skills_detail")}
+        visible={visible}
+        onOk={handleSave}
+        onCancel={onClose}
+        confirmLoading={saving}
+        autoFocus={false}
+        focusLock
+        unmountOnExit
+        style={{ width: 640 }}
+      >
+        <Space direction="vertical" size={16} className="tw-w-full">
+          {/* Name & Description (read-only) */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">{"Name"}</div>
+            <Typography.Text>{skill.name}</Typography.Text>
+          </div>
+          {skill.description && (
+            <div>
+              <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">{"Description"}</div>
+              <Typography.Text type="secondary">{skill.description}</Typography.Text>
+            </div>
+          )}
+
+          {/* Prompt (editable) */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">
+              {t("agent_skills_prompt")}
+            </div>
+            <Input.TextArea
+              value={prompt}
+              onChange={setPrompt}
+              autoSize={{ minRows: 6, maxRows: 16 }}
+              style={{ fontFamily: "monospace", fontSize: 13 }}
+            />
+          </div>
+
+          {/* Scripts - clickable to view code */}
+          {scripts.length > 0 && (
+            <div>
+              <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">
+                {t("agent_skills_tools")} {"("}
+                {scripts.length}
+                {")"}
+              </div>
+              <div className="tw-flex tw-flex-wrap tw-gap-1.5">
+                {scripts.map((s) => (
+                  <Tag
+                    key={s.name}
+                    color="arcoblue"
+                    className="tw-cursor-pointer hover:tw-opacity-80"
+                    onClick={() => setViewingTool(s)}
+                  >
+                    {s.name}
+                  </Tag>
+                ))}
+              </div>
+              <div className="tw-text-xs tw-text-[var(--color-text-3)] tw-mt-1">
+                {t("agent_skills_click_to_view_code")}
+              </div>
+            </div>
+          )}
+
+          {/* References */}
+          {references.length > 0 && (
+            <div>
+              <div className="tw-text-sm tw-font-medium tw-mb-1 tw-text-[var(--color-text-2)]">
+                {t("agent_skills_references")} {"("}
+                {references.length}
+                {")"}
+              </div>
+              <div className="tw-flex tw-flex-wrap tw-gap-1.5">
+                {references.map((r) => (
+                  <Tag key={r.name} color="green">
+                    {r.name}
+                  </Tag>
+                ))}
+              </div>
+            </div>
+          )}
+        </Space>
+      </Modal>
+
+      <ToolCodeModal visible={!!viewingTool} tool={viewingTool} onClose={() => setViewingTool(null)} t={t} />
+    </>
+  );
+}
+
+// ---- Main Page ----
+
+function AgentSkills() {
+  const { t } = useTranslation();
+  const [skills, setSkills] = useState<SkillSummary[]>([]);
+  const [detailVisible, setDetailVisible] = useState(false);
+  const [detailSkill, setDetailSkill] = useState<SkillRecord | null>(null);
+  const [configVisible, setConfigVisible] = useState(false);
+  const [configSkill, setConfigSkill] = useState<SkillRecord | null>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const loadSkills = useCallback(async () => {
+    const list = await skillRepo.listSkills();
+    setSkills(list);
+  }, []);
+
+  useEffect(() => {
+    loadSkills();
+  }, [loadSkills]);
+
+  const handleDetail = async (name: string) => {
+    const record = await skillRepo.getSkill(name);
+    if (record) {
+      setDetailSkill(record);
+      setDetailVisible(true);
+    }
+  };
+
+  const handleUninstall = async (name: string) => {
+    await agentClient.removeSkill(name);
+    loadSkills();
+  };
+
+  const handleConfig = async (name: string) => {
+    const record = await skillRepo.getSkill(name);
+    if (record?.config) {
+      setConfigSkill(record);
+      setConfigVisible(true);
+    }
+  };
+
+  const handleRefresh = async (name: string) => {
+    try {
+      await agentClient.refreshSkill(name);
+      await loadSkills();
+      Message.success(t("agent_skills_refresh_success"));
+    } catch (e: any) {
+      Message.error(e.message || String(e));
+    }
+  };
+
+  // 选择 ZIP 文件后走安装页面流程
+  const handleZipFileSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    try {
+      const buffer = await file.arrayBuffer();
+      const bytes = new Uint8Array(buffer);
+      let binary = "";
+      for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+      }
+      const base64 = btoa(binary);
+      const uuid = await agentClient.prepareSkillInstall(base64);
+      window.open(`/src/install.html?skill=${uuid}`, "_blank");
+    } catch (err: any) {
+      Message.error(err.message || String(err));
+    } finally {
+      // 清空 input 以便再次选择相同文件
+      if (fileInputRef.current) {
+        fileInputRef.current.value = "";
+      }
+    }
+  };
+
+  return (
+    <Space className="tw-w-full tw-h-full tw-overflow-auto tw-relative" direction="vertical">
+      <Card
+        title={t("agent_skills_title")}
+        bordered={false}
+        extra={
+          <>
+            <input
+              ref={fileInputRef}
+              type="file"
+              accept=".zip"
+              onChange={handleZipFileSelect}
+              style={{ display: "none" }}
+            />
+            <Button type="primary" icon={<IconPlus />} onClick={() => fileInputRef.current?.click()}>
+              {t("agent_skills_add")}
+            </Button>
+          </>
+        }
+      >
+        {skills.length === 0 ? (
+          <div className="tw-py-12">
+            <Empty description={t("agent_skills_empty")} />
+          </div>
+        ) : (
+          <div className="tw-grid tw-grid-cols-1 md:tw-grid-cols-2 tw-gap-4">
+            {skills.map((skill) => (
+              <SkillCard
+                key={skill.name}
+                skill={skill}
+                onDetail={() => handleDetail(skill.name)}
+                onUninstall={() => handleUninstall(skill.name)}
+                onRefresh={() => handleRefresh(skill.name)}
+                onConfig={skill.hasConfig ? () => handleConfig(skill.name) : undefined}
+                t={t}
+              />
+            ))}
+          </div>
+        )}
+      </Card>
+
+      <SkillDetailModal
+        visible={detailVisible}
+        skill={detailSkill}
+        onClose={() => setDetailVisible(false)}
+        onSaved={loadSkills}
+        t={t}
+      />
+
+      <SkillConfigModal visible={configVisible} skill={configSkill} onClose={() => setConfigVisible(false)} t={t} />
+    </Space>
+  );
+}
+
+export default AgentSkills;
diff --git a/src/pages/options/routes/AgentTasks.tsx b/src/pages/options/routes/AgentTasks.tsx
new file mode 100644
index 000000000..575b90139
--- /dev/null
+++ b/src/pages/options/routes/AgentTasks.tsx
@@ -0,0 +1,547 @@
+import {
+  Badge,
+  Button,
+  Card,
+  Drawer,
+  Empty,
+  Input,
+  InputNumber,
+  Message,
+  Modal,
+  Popconfirm,
+  Radio,
+  Select,
+  Space,
+  Switch,
+  Table,
+  Tag,
+  Typography,
+} from "@arco-design/web-react";
+import { IconDelete, IconEdit, IconHistory, IconPlayArrow, IconPlus } from "@arco-design/web-react/icon";
+import { useTranslation } from "react-i18next";
+import { useCallback, useEffect, useState } from "react";
+import type { AgentTask, AgentTaskRun, AgentModelConfig } from "@App/app/service/agent/types";
+import { AgentTaskRepo, AgentTaskRunRepo } from "@App/app/repo/agent_task";
+import { AgentModelRepo } from "@App/app/repo/agent_model";
+import { uuidv4 } from "@App/pkg/utils/uuid";
+import { nextTimeDisplay } from "@App/pkg/utils/cron";
+
+const taskRepo = new AgentTaskRepo();
+const taskRunRepo = new AgentTaskRunRepo();
+const modelRepo = new AgentModelRepo();
+
+const emptyTask: Omit<AgentTask, "id" | "createtime" | "updatetime" | "nextruntime"> = {
+  name: "",
+  crontab: "",
+  mode: "internal",
+  enabled: true,
+  notify: true,
+  prompt: "",
+  maxIterations: 10,
+};
+
+function TaskCard({
+  task,
+  onEdit,
+  onDelete,
+  onToggle,
+  onRunNow,
+  onHistory,
+}: {
+  task: AgentTask;
+  onEdit: () => void;
+  onDelete: () => void;
+  onToggle: (enabled: boolean) => void;
+  onRunNow: () => void;
+  onHistory: () => void;
+}) {
+  const { t } = useTranslation();
+
+  let nextRunText = "";
+  try {
+    nextRunText = task.enabled && task.crontab ? nextTimeDisplay(task.crontab) : "-";
+  } catch {
+    nextRunText = "-";
+  }
+
+  return (
+    <div
+      className={`tw-group tw-relative tw-rounded-xl tw-p-5 tw-transition-all tw-duration-200 tw-cursor-default ${
+        task.enabled
+          ? "tw-bg-[var(--color-bg-2)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.06)] hover:tw-shadow-[0_4px_16px_rgba(0,0,0,0.1)]"
+          : "tw-bg-[var(--color-bg-3)] tw-shadow-[0_1px_4px_rgba(0,0,0,0.03)] tw-opacity-60"
+      }`}
+    >
+      {/* 顶部区域 */}
+      <div className="tw-flex tw-items-start tw-justify-between tw-mb-4">
+        <div className="tw-flex tw-items-center tw-gap-3">
+          <div
+            className={`tw-w-10 tw-h-10 tw-rounded-lg tw-flex tw-items-center tw-justify-center tw-text-lg tw-font-bold tw-shrink-0 ${
+              task.mode === "internal" ? "tw-bg-[#e3f2fd] tw-text-[#1565c0]" : "tw-bg-[#e8f5e9] tw-text-[#2e7d32]"
+            }`}
+          >
+            {task.mode === "internal" ? "I" : "E"}
+          </div>
+          <div className="tw-flex tw-flex-col tw-gap-0.5">
+            <Typography.Text className="tw-font-semibold tw-text-base !tw-mb-0">{task.name}</Typography.Text>
+            <div className="tw-flex tw-items-center tw-gap-2">
+              <Tag size="small" color={task.mode === "internal" ? "blue" : "green"}>
+                {t(task.mode === "internal" ? "agent_tasks_mode_internal" : "agent_tasks_mode_event")}
+              </Tag>
+              <Typography.Text type="secondary" className="tw-text-xs tw-font-mono !tw-mb-0">
+                {task.crontab}
+              </Typography.Text>
+            </div>
+          </div>
+        </div>
+        <Switch size="small" checked={task.enabled} onChange={onToggle} />
+      </div>
+
+      {/* 信息区域 */}
+      <div className="tw-flex tw-flex-col tw-gap-2 tw-mb-4">
+        <div className="tw-flex tw-items-center tw-gap-2">
+          <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-min-w-16">{t("agent_tasks_next_run")}</span>
+          <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+            {nextRunText}
+          </Typography.Text>
+        </div>
+        <div className="tw-flex tw-items-center tw-gap-2">
+          <span className="tw-text-xs tw-text-[var(--color-text-3)] tw-min-w-16">{t("agent_tasks_last_status")}</span>
+          {task.lastRunStatus ? (
+            <Badge
+              status={task.lastRunStatus === "success" ? "success" : "error"}
+              text={t(
+                task.lastRunStatus === "success" ? "agent_tasks_run_status_success" : "agent_tasks_run_status_error"
+              )}
+            />
+          ) : (
+            <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+              {t("agent_tasks_never_run")}
+            </Typography.Text>
+          )}
+        </div>
+      </div>
+
+      {/* 操作栏 */}
+      <div className="tw-flex tw-items-center tw-justify-end tw-gap-0.5 tw-pt-3 tw-border-t tw-border-solid tw-border-[var(--color-border-1)] tw-border-x-0 tw-border-b-0 tw-opacity-60 group-hover:tw-opacity-100 tw-transition-opacity">
+        <Button type="text" size="small" icon={<IconPlayArrow />} onClick={onRunNow}>
+          {t("agent_tasks_run_now")}
+        </Button>
+        <Button type="text" size="small" icon={<IconHistory />} onClick={onHistory}>
+          {t("agent_tasks_history")}
+        </Button>
+        <Button type="text" size="small" icon={<IconEdit />} onClick={onEdit}>
+          {t("agent_model_edit")}
+        </Button>
+        <Popconfirm title={t("agent_tasks_delete_confirm")} onOk={onDelete}>
+          <Button type="text" size="small" status="danger" icon={<IconDelete />}>
+            {t("agent_model_delete")}
+          </Button>
+        </Popconfirm>
+      </div>
+    </div>
+  );
+}
+
+function RunHistoryDrawer({
+  task,
+  visible,
+  onClose,
+}: {
+  task: AgentTask | null;
+  visible: boolean;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation();
+  const [runs, setRuns] = useState<AgentTaskRun[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (!visible || !task) return;
+    setLoading(true);
+    taskRunRepo
+      .listRuns(task.id)
+      .then(setRuns)
+      .finally(() => setLoading(false));
+  }, [visible, task]);
+
+  const handleClear = async () => {
+    if (!task) return;
+    await taskRunRepo.clearRuns(task.id);
+    setRuns([]);
+    Message.success(t("clear_success"));
+  };
+
+  const columns = [
+    {
+      title: t("agent_tasks_run_time"),
+      dataIndex: "starttime",
+      width: 170,
+      render: (val: number) => new Date(val).toLocaleString(),
+    },
+    {
+      title: t("agent_tasks_run_status"),
+      dataIndex: "status",
+      width: 100,
+      render: (status: string) => (
+        <Badge
+          status={status === "success" ? "success" : status === "error" ? "error" : "processing"}
+          text={t(`agent_tasks_run_status_${status}`)}
+        />
+      ),
+    },
+    {
+      title: t("agent_tasks_run_duration"),
+      dataIndex: "endtime",
+      width: 100,
+      render: (endtime: number | undefined, record: AgentTaskRun) =>
+        endtime ? `${((endtime - record.starttime) / 1000).toFixed(1)}s` : "-",
+    },
+    {
+      title: t("agent_tasks_run_usage"),
+      dataIndex: "usage",
+      width: 120,
+      render: (usage: AgentTaskRun["usage"]) => (usage ? `${usage.inputTokens} / ${usage.outputTokens}` : "-"),
+    },
+  ];
+
+  return (
+    <Drawer
+      width={600}
+      title={task?.name || ""}
+      visible={visible}
+      onCancel={onClose}
+      footer={
+        <Popconfirm title={t("agent_tasks_clear_runs_confirm")} onOk={handleClear}>
+          <Button status="danger" size="small">
+            {t("agent_tasks_clear_runs")}
+          </Button>
+        </Popconfirm>
+      }
+      unmountOnExit
+    >
+      <Table
+        columns={columns}
+        data={runs}
+        rowKey="id"
+        loading={loading}
+        pagination={false}
+        size="small"
+        noDataElement={<Empty description={t("no_data")} />}
+      />
+    </Drawer>
+  );
+}
+
+function AgentTasks() {
+  const { t } = useTranslation();
+  const [tasks, setTasks] = useState<AgentTask[]>([]);
+  const [models, setModels] = useState<AgentModelConfig[]>([]);
+  const [modalVisible, setModalVisible] = useState(false);
+  const [editingTask, setEditingTask] = useState<Omit<AgentTask, "id" | "createtime" | "updatetime" | "nextruntime">>({
+    ...emptyTask,
+  });
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [cronPreview, setCronPreview] = useState("");
+  const [drawerTask, setDrawerTask] = useState<AgentTask | null>(null);
+  const [drawerVisible, setDrawerVisible] = useState(false);
+
+  const loadData = useCallback(async () => {
+    const [taskList, modelList] = await Promise.all([taskRepo.listTasks(), modelRepo.listModels()]);
+    setTasks(taskList);
+    setModels(modelList);
+  }, []);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  // 实时预览 cron 下次运行时间
+  useEffect(() => {
+    if (!editingTask.crontab) {
+      setCronPreview("");
+      return;
+    }
+    try {
+      setCronPreview(nextTimeDisplay(editingTask.crontab));
+    } catch {
+      setCronPreview(t("cron_invalid_expr"));
+    }
+  }, [editingTask.crontab, t]);
+
+  const handleAdd = () => {
+    setEditingTask({ ...emptyTask });
+    setEditingId(null);
+    setModalVisible(true);
+  };
+
+  const handleEdit = (task: AgentTask) => {
+    const { id: _id, createtime: _ct, updatetime: _ut, nextruntime: _nt, ...rest } = task;
+    setEditingTask(rest);
+    setEditingId(task.id);
+    setModalVisible(true);
+  };
+
+  const handleDelete = async (id: string) => {
+    await taskRepo.removeTask(id);
+    loadData();
+  };
+
+  const handleToggle = async (task: AgentTask, enabled: boolean) => {
+    const updated = { ...task, enabled, updatetime: Date.now() };
+    if (enabled) {
+      try {
+        const info = nextTimeDisplay(task.crontab);
+        void info; // just validate
+      } catch {
+        // ignore
+      }
+    }
+    await taskRepo.saveTask(updated);
+    loadData();
+  };
+
+  const handleRunNow = async (task: AgentTask) => {
+    try {
+      // 通过 sendMessage 调用 SW
+      await chrome.runtime.sendMessage({
+        channel: "agent",
+        action: "agentTask",
+        data: { action: "runNow", id: task.id },
+      });
+      Message.success(t("agent_tasks_run_now"));
+    } catch {
+      // 直接通过 repo 标记（fallback：调度器会在下次 tick 执行）
+      Message.info(t("agent_tasks_run_now"));
+    }
+  };
+
+  const handleHistory = (task: AgentTask) => {
+    setDrawerTask(task);
+    setDrawerVisible(true);
+  };
+
+  const handleModalOk = async () => {
+    if (!editingTask.name || !editingTask.crontab) {
+      Message.error(t("agent_tasks_name_cron_required"));
+      return;
+    }
+
+    // 验证 cron 表达式
+    try {
+      nextTimeDisplay(editingTask.crontab);
+    } catch {
+      Message.error(t("cron_invalid_expr"));
+      return;
+    }
+
+    const now = Date.now();
+
+    if (editingId) {
+      const existing = tasks.find((t) => t.id === editingId);
+      if (existing) {
+        const updated: AgentTask = { ...existing, ...editingTask, updatetime: now };
+        if (updated.enabled) {
+          try {
+            const info = nextTimeDisplay(updated.crontab);
+            void info;
+          } catch {
+            // ignore
+          }
+        }
+        await taskRepo.saveTask(updated);
+      }
+    } else {
+      const task: AgentTask = {
+        ...editingTask,
+        id: uuidv4(),
+        createtime: now,
+        updatetime: now,
+      };
+      if (task.enabled) {
+        try {
+          // nextruntime will be computed by scheduler init
+        } catch {
+          // ignore
+        }
+      }
+      await taskRepo.saveTask(task);
+    }
+
+    setModalVisible(false);
+    loadData();
+  };
+
+  return (
+    <Space className="tw-w-full tw-h-full tw-overflow-auto tw-relative" direction="vertical">
+      <Card
+        title={t("agent_tasks_title")}
+        bordered={false}
+        extra={
+          <Button type="primary" icon={<IconPlus />} onClick={handleAdd}>
+            {t("agent_tasks_create")}
+          </Button>
+        }
+      >
+        {tasks.length === 0 ? (
+          <div className="tw-py-12">
+            <Empty description={t("agent_tasks_no_tasks")} />
+          </div>
+        ) : (
+          <div className="tw-grid tw-grid-cols-1 md:tw-grid-cols-2 tw-gap-4">
+            {tasks.map((task) => (
+              <TaskCard
+                key={task.id}
+                task={task}
+                onEdit={() => handleEdit(task)}
+                onDelete={() => handleDelete(task.id)}
+                onToggle={(enabled) => handleToggle(task, enabled)}
+                onRunNow={() => handleRunNow(task)}
+                onHistory={() => handleHistory(task)}
+              />
+            ))}
+          </div>
+        )}
+      </Card>
+
+      <Modal
+        title={editingId ? t("agent_tasks_edit") : t("agent_tasks_create")}
+        visible={modalVisible}
+        onOk={handleModalOk}
+        onCancel={() => setModalVisible(false)}
+        autoFocus={false}
+        focusLock
+        unmountOnExit
+        style={{ maxWidth: 520 }}
+      >
+        <Space direction="vertical" size={16} className="tw-w-full">
+          {/* 名称 */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_model_name")}
+            </div>
+            <Input
+              value={editingTask.name}
+              placeholder="Daily Summary"
+              onChange={(value) => setEditingTask((prev) => ({ ...prev, name: value }))}
+            />
+          </div>
+
+          {/* 模式 */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">{t("type")}</div>
+            <Radio.Group
+              value={editingTask.mode}
+              onChange={(value) => setEditingTask((prev) => ({ ...prev, mode: value }))}
+            >
+              <Radio value="internal">{t("agent_tasks_mode_internal")}</Radio>
+              <Radio value="event">{t("agent_tasks_mode_event")}</Radio>
+            </Radio.Group>
+          </div>
+
+          {/* Cron 表达式 */}
+          <div>
+            <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+              {t("agent_tasks_cron")}
+            </div>
+            <Input
+              value={editingTask.crontab}
+              placeholder="0 9 * * *"
+              onChange={(value) => setEditingTask((prev) => ({ ...prev, crontab: value }))}
+            />
+            {cronPreview && (
+              <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0 tw-mt-1 tw-block">
+                {t("agent_tasks_next_run")}
+                {": "}
+                {cronPreview}
+              </Typography.Text>
+            )}
+          </div>
+
+          {/* internal 模式字段 */}
+          {editingTask.mode === "internal" && (
+            <>
+              {/* 提示词 */}
+              <div>
+                <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+                  {t("agent_tasks_prompt")}
+                </div>
+                <Input.TextArea
+                  value={editingTask.prompt}
+                  placeholder="请生成今日摘要报告"
+                  autoSize={{ minRows: 3, maxRows: 8 }}
+                  onChange={(value) => setEditingTask((prev) => ({ ...prev, prompt: value }))}
+                />
+              </div>
+
+              {/* 模型选择 */}
+              <div>
+                <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+                  {t("agent_tasks_model_select")}
+                </div>
+                <Select
+                  value={editingTask.modelId || undefined}
+                  placeholder={t("agent_tasks_model_select")}
+                  allowClear
+                  onChange={(value) => setEditingTask((prev) => ({ ...prev, modelId: value }))}
+                >
+                  {models.map((m) => (
+                    <Select.Option key={m.id} value={m.id}>
+                      {m.name}
+                    </Select.Option>
+                  ))}
+                </Select>
+              </div>
+
+              {/* 最大迭代次数 */}
+              <div>
+                <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+                  {t("agent_tasks_max_iterations")}
+                </div>
+                <InputNumber
+                  value={editingTask.maxIterations}
+                  min={1}
+                  max={100}
+                  onChange={(value) => setEditingTask((prev) => ({ ...prev, maxIterations: value }))}
+                />
+              </div>
+
+              {/* 续接对话 ID */}
+              <div>
+                <div className="tw-text-sm tw-font-medium tw-mb-2 tw-text-[var(--color-text-2)]">
+                  {t("agent_tasks_conversation_id")}
+                </div>
+                <Input
+                  value={editingTask.conversationId || ""}
+                  placeholder=""
+                  allowClear
+                  onChange={(value) => setEditingTask((prev) => ({ ...prev, conversationId: value || undefined }))}
+                />
+              </div>
+            </>
+          )}
+
+          {/* event 模式提示 */}
+          {editingTask.mode === "event" && (
+            <Typography.Text type="secondary" className="tw-text-xs !tw-mb-0">
+              {t("agent_tasks_event_hint")}
+            </Typography.Text>
+          )}
+
+          {/* 通知开关 */}
+          <div className="tw-flex tw-items-center tw-gap-3">
+            <span className="tw-text-sm tw-font-medium tw-text-[var(--color-text-2)]">{t("agent_tasks_notify")}</span>
+            <Switch
+              checked={editingTask.notify}
+              onChange={(checked) => setEditingTask((prev) => ({ ...prev, notify: checked }))}
+            />
+          </div>
+        </Space>
+      </Modal>
+
+      <RunHistoryDrawer task={drawerTask} visible={drawerVisible} onClose={() => setDrawerVisible(false)} />
+    </Space>
+  );
+}
+
+export default AgentTasks;
diff --git a/src/pages/options/routes/Logger.tsx b/src/pages/options/routes/Logger.tsx
index 8cf1db927..966c1805f 100644
--- a/src/pages/options/routes/Logger.tsx
+++ b/src/pages/options/routes/Logger.tsx
@@ -75,6 +75,7 @@ function LoggerPage() {
       onQueryLog();
       setInit(2);
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [init]);
 
   useEffect(() => {
@@ -104,6 +105,7 @@ function LoggerPage() {
         setInit(1);
       }
     });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [startTime, endTime]);
 
   return (
diff --git a/src/pages/options/routes/ScriptList/hooks.tsx b/src/pages/options/routes/ScriptList/hooks.tsx
index 425082748..6cb0909ee 100644
--- a/src/pages/options/routes/ScriptList/hooks.tsx
+++ b/src/pages/options/routes/ScriptList/hooks.tsx
@@ -10,6 +10,7 @@ import {
 } from "@App/app/repo/scripts";
 import { fetchScript, fetchScriptList } from "@App/pages/store/features/script";
 import { loadScriptFavicons } from "@App/pages/store/favicons";
+import { systemConfig } from "@App/pages/store/global";
 import { parseTags } from "@App/app/repo/metadata";
 import { getCombinedMeta } from "@App/app/service/service_worker/utils";
 import { cacheInstance } from "@App/app/cache";
@@ -76,7 +77,8 @@ export function useScriptDataManagement() {
       setLoadingList(false);
       cacheInstance.tx("faviconOPFSControl", async () => {
         if (!mounted) return;
-        for await (const { chunkResults } of loadScriptFavicons(list)) {
+        const faviconService = await systemConfig.getFaviconService();
+        for await (const { chunkResults } of loadScriptFavicons(list, faviconService)) {
           if (!mounted) return;
           setScriptList((prev) => {
             const favMap = new Map(chunkResults.map((r) => [r.uuid, r]));
diff --git a/src/pages/options/routes/ScriptList/index.tsx b/src/pages/options/routes/ScriptList/index.tsx
index da178ee8a..96a969ff6 100644
--- a/src/pages/options/routes/ScriptList/index.tsx
+++ b/src/pages/options/routes/ScriptList/index.tsx
@@ -256,6 +256,7 @@ function ScriptList() {
         }
       });
     }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   return (
diff --git a/src/pages/options/routes/Setting.tsx b/src/pages/options/routes/Setting.tsx
index afb779499..0ac87c935 100644
--- a/src/pages/options/routes/Setting.tsx
+++ b/src/pages/options/routes/Setting.tsx
@@ -15,6 +15,8 @@ import CustomTrans from "@App/pages/components/CustomTrans";
 import { useSystemConfig } from "./utils";
 import { subscribeMessage } from "@App/pages/store/global";
 import { SystemConfigChange, type SystemConfigKey } from "@App/pkg/config/config";
+import { FaviconDAO } from "@App/app/repo/favicon";
+import { clearFaviconMemoryCache } from "@App/pages/store/favicons";
 import { type TKeyValue } from "@Packages/message/message_queue";
 import { useEffect, useMemo } from "react";
 import { systemConfig } from "@App/pages/store/global";
@@ -41,6 +43,7 @@ function Setting() {
   const [badgeTextColor, setBadgeTextColor, submitBadgeTextColor] = useSystemConfig("badge_text_color");
   const [scriptMenuDisplayType, setScriptMenuDisplayType, submitScriptMenuDisplayType] =
     useSystemConfig("script_menu_display_type");
+  const [faviconService, setFaviconService, submitFaviconService] = useSystemConfig("favicon_service");
 
   const [editorTypeDefinition, setEditorTypeDefinition, submitEditorTypeDefinition] =
     useSystemConfig("editor_type_definition");
@@ -81,6 +84,7 @@ function Setting() {
       badge_background_color: setBadgeBackgroundColor,
       badge_text_color: setBadgeTextColor,
       script_menu_display_type: setScriptMenuDisplayType,
+      favicon_service: setFaviconService,
       editor_type_definition: setEditorTypeDefinition,
     } as const;
     const hookMgr = new HookManager();
@@ -306,6 +310,39 @@ function Setting() {
               </div>
             </Space>
           </div>
+
+          {/* Favicon 服务 */}
+          <div className="tw-flex tw-items-center tw-justify-between tw-min-h-9">
+            <div className="tw-flex tw-items-center tw-gap-4 tw-flex-1">
+              <span className="tw-min-w-20">{t("favicon_service")}</span>
+              <Select
+                value={faviconService}
+                className="tw-w-40 tw-max-w-50"
+                onChange={async (value) => {
+                  submitFaviconService(value);
+                  // 清除 favicon 缓存
+                  try {
+                    const faviconDAO = new FaviconDAO();
+                    const allFavicons = await faviconDAO.find();
+                    await faviconDAO.deletes(allFavicons.map((f) => f.uuid));
+                    // 清除 OPFS 缓存：删除并重建目录
+                    const opfsRoot = await navigator.storage.getDirectory();
+                    await opfsRoot.removeEntry("cached_favicons", { recursive: true }).catch(() => {});
+                    // 清除内存中的 blob URL 缓存
+                    clearFaviconMemoryCache();
+                  } catch {
+                    // 忽略清除缓存的错误
+                  }
+                  Message.success(t("save_success")!);
+                }}
+              >
+                <Select.Option value="scriptcat">{t("favicon_service_scriptcat")}</Select.Option>
+                <Select.Option value="google">{t("favicon_service_google")}</Select.Option>
+                <Select.Option value="local">{t("favicon_service_local")}</Select.Option>
+              </Select>
+            </div>
+            <span className="tw-text-xs tw-ml-6 tw-flex-shrink-0">{t("favicon_service_desc")}</span>
+          </div>
         </Space>
       </Card>
 
diff --git a/src/pages/options/routes/script/ScriptEditor.tsx b/src/pages/options/routes/script/ScriptEditor.tsx
index 8fc3322d8..69ccfa22c 100644
--- a/src/pages/options/routes/script/ScriptEditor.tsx
+++ b/src/pages/options/routes/script/ScriptEditor.tsx
@@ -1,8 +1,8 @@
 import type { Script } from "@App/app/repo/scripts";
 import { SCRIPT_TYPE_NORMAL, ScriptCodeDAO, ScriptDAO } from "@App/app/repo/scripts";
 import CodeEditor from "@App/pages/components/CodeEditor";
-import React, { useCallback, useEffect, useMemo, useState } from "react";
-import { useParams, useSearchParams } from "react-router-dom";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useNavigate, useParams, useSearchParams } from "react-router-dom";
 import type { editor } from "monaco-editor";
 import { KeyCode, KeyMod } from "monaco-editor";
 import { Button, Dropdown, Grid, Input, Menu, Message, Modal, Space, Tabs, Tooltip } from "@arco-design/web-react";
@@ -32,18 +32,18 @@ type HotKey = {
   id: string;
   title: string;
   hotKey: number;
-  action: (script: Script, codeEditor: editor.IStandaloneCodeEditor) => void;
+  action: (script: Script, codeEditor: editor.ICodeEditor) => void;
 };
 
 const Editor: React.FC<{
   id: string;
-  script: Script;
+  getScript: (uuid: string) => Script | undefined;
   code: string;
   hotKeys: HotKey[];
-  callbackEditor: (e: editor.IStandaloneCodeEditor) => void;
+  callbackEditor: (e: editor.ICodeEditor) => void;
   onChange: (code: string) => void;
   className: string;
-}> = ({ id, script, code, hotKeys, callbackEditor, onChange, className }) => {
+}> = ({ id, getScript, code, hotKeys, callbackEditor, onChange, className }) => {
   const [node, setNode] = useState<{ editor: editor.IStandaloneCodeEditor }>();
   const ref = useCallback<(node: { editor: editor.IStandaloneCodeEditor }) => void>(
     (inlineNode) => {
@@ -60,7 +60,7 @@ const Editor: React.FC<{
     // @ts-ignore
     if (!node.editor.uuid) {
       // @ts-ignore
-      node.editor.uuid = script.uuid;
+      node.editor.uuid = id;
     }
     hotKeys.forEach((item) => {
       node.editor.addAction({
@@ -68,8 +68,10 @@ const Editor: React.FC<{
         label: item.title,
         keybindings: [item.hotKey],
         run(editor) {
-          // @ts-ignore
-          item.action(script, editor);
+          const script = getScript(id);
+          if (script) {
+            item.action(script, editor);
+          }
         },
       });
     });
@@ -78,26 +80,27 @@ const Editor: React.FC<{
     });
     callbackEditor(node.editor);
     return node.editor.dispose.bind(node.editor);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [node?.editor]);
 
   return <CodeEditor key={id} id={id} ref={ref} className={className} code={code} diffCode="" editable />;
 };
 
 const WarpEditor = React.memo(Editor, (prev, next) => {
-  return prev.script.uuid === next.script.uuid;
+  return prev.id === next.id;
 });
 
 type EditorMenu = {
   title: string;
   tooltip?: string;
-  action?: (script: Script, e: editor.IStandaloneCodeEditor) => void;
+  action?: (script: Script, e: editor.ICodeEditor) => void;
   items?: {
     id: string;
     title: string;
     tooltip?: string;
     hotKey?: number;
     hotKeyString?: string;
-    action: (script: Script, e: editor.IStandaloneCodeEditor) => void;
+    action: (script: Script, e: editor.ICodeEditor) => void;
   }[];
 };
 
@@ -171,7 +174,11 @@ const emptyScript = async (template: string, hotKeys: any, target?: string) => {
 
 type visibleItem = "scriptStorage" | "scriptSetting" | "scriptResource";
 
-const popstate = () => {
+const popstate: EventListener = (e: Event) => {
+  if (!e.isTrusted) return;
+  if (location.href.startsWith(chrome.runtime.getURL("/src/options.html#/script/editor"))) {
+    return;
+  }
   if (confirm(i18n.t("script_modified_leave_confirm"))) {
     window.history.back();
     window.removeEventListener("popstate", popstate);
@@ -181,42 +188,110 @@ const popstate = () => {
   return false;
 };
 
+type EditorState = {
+  script: Script;
+  code: string;
+  active: boolean;
+  hotKeys: HotKey[];
+  editor?: editor.ICodeEditor;
+  isChanged: boolean;
+};
+
+const scriptDAO = new ScriptDAO();
+const scriptCodeDAO = new ScriptCodeDAO();
+
 function ScriptEditor() {
   const [visible, setVisible] = useState<{ [key: string]: boolean }>({});
   const [searchKeyword, setSearchKeyword] = useState<string>("");
   const [showSearchInput, setShowSearchInput] = useState<boolean>(false);
   const [modal, contextHolder] = Modal.useModal();
-  const [editors, setEditors] = useState<
-    {
-      script: Script;
-      code: string;
-      active: boolean;
-      hotKeys: HotKey[];
-      editor?: editor.IStandaloneCodeEditor;
-      isChanged: boolean;
-    }[]
-  >([]);
+  const [editors, setEditors] = useState<EditorState[]>([]);
+  const editorsRef = useRef<EditorState[]>(editors); // 取出资料用
+  // Sync during render (no useEffect needed)
+  editorsRef.current = editors;
+  // The function identity is now permanent (empty dependency array)
+  const getScript = useCallback((uuid: string) => {
+    return editorsRef.current.find((e) => e.script.uuid === uuid)?.script;
+  }, []);
+  const editorFindIndex = (uuid: string) => {
+    return editorsRef.current.findIndex((e) => e.script.uuid === uuid);
+  };
+  const editorFindItem = (uuid: string) => {
+    return editorsRef.current.find((e) => e.script.uuid === uuid);
+  };
+  const delayedEditorFocus = (editor: editor.ICodeEditor | null | undefined, delayMs: number = 100) => {
+    editor = !editor ? editorsRef.current.find((e) => e.active && e.script.uuid === selectedScript)?.editor : editor;
+    if (editor) {
+      setTimeout(editor.focus.bind(editor), delayMs);
+    }
+  };
   const [scriptList, setScriptList] = useState<Script[]>([]);
   const [currentScript, setCurrentScript] = useState<Script>();
-  const [selectSciptButtonAndTab, setSelectSciptButtonAndTab] = useState<string>("");
+  const [selectedScript, setSelectSciptButtonAndTab] = useState<string>("");
   const [rightOperationTab, setRightOperationTab] = useState<{
     key: string;
     uuid: string;
     selectSciptButtonAndTab: string;
   }>();
-  const [pageInit, setPageInit] = useState<boolean>(false);
+  const cidRef = useRef<ReturnType<typeof setTimeout>>();
   const [canLoadScript, setCanLoadScript] = useState<boolean>(false);
   const [hiddenScriptList, setHiddenScriptList] = useState<boolean>(() => {
     return localStorage.getItem("hiddenEditorScriptList") === "true";
   });
 
   const pageUrlParams = useParams();
-  const [pageUrlSearchParams, setPageUrlSearchParams] = useSearchParams();
+  const [pageUrlSearchParams, _] = useSearchParams();
 
+  const navigate = useNavigate();
   const { t } = useTranslation();
 
-  const scriptDAO = new ScriptDAO();
-  const scriptCodeDAO = new ScriptCodeDAO();
+  // 封装：统一的打开/创建脚本逻辑 (Command Pattern)
+  const openScript = useCallback(
+    async (uuid?: string, template?: string, target?: string) => {
+      const insertEditor = (e: EditorState) => {
+        let insertIdx = editorFindIndex(selectedScript);
+        insertIdx = insertIdx >= 0 ? insertIdx + 1 : editorsRef.current.length;
+        setEditors((prev) => {
+          const ret = prev.map((e) => ({ ...e, active: false }));
+          ret.splice(insertIdx, 0, e);
+          return ret;
+        });
+      };
+
+      if (uuid) {
+        // 如果已在编辑器中，直接激活
+        const existIndex = editorFindIndex(uuid);
+        if (existIndex !== -1) {
+          setEditors((prev) => prev.map((e, i) => ({ ...e, active: i === existIndex })));
+          setSelectSciptButtonAndTab(uuid);
+          return;
+        }
+
+        // 如果不在，从数据库读取
+        const script = scriptList.find((s) => s.uuid === uuid);
+        if (script) {
+          const code = await scriptCodeDAO.findByUUID(uuid);
+          const newEditor: EditorState = {
+            script,
+            code: code?.code || "",
+            active: true,
+            hotKeys: hotKeys.current,
+            isChanged: false,
+          };
+          insertEditor(newEditor);
+          setSelectSciptButtonAndTab(uuid);
+        } else {
+          Message.error("Script Not Found");
+        }
+      } else {
+        // 新建脚本
+        const e = await emptyScript(template || "", hotKeys.current, target || "blank");
+        insertEditor(e);
+        setSelectSciptButtonAndTab(e.script.uuid);
+      }
+    },
+    [scriptList, selectedScript]
+  );
 
   const setShow = (key: visibleItem, show: boolean) => {
     for (const k of Object.keys(visible)) {
@@ -226,7 +301,7 @@ function ScriptEditor() {
     setVisible({ ...visible });
   };
 
-  const save = (existingScript: Script, e: editor.IStandaloneCodeEditor): Promise<Script> => {
+  const save = (existingScript: Script, e: editor.ICodeEditor): Promise<Script> => {
     // 解析code生成新的script并更新
     const code = e.getValue();
     const targetUUID = existingScript.uuid;
@@ -247,11 +322,12 @@ function ScriptEditor() {
           Message.warning(t("script_name_cannot_be_set_to_empty"));
           return Promise.reject(new Error("script name cannot be empty"));
         }
+
         if (script.ignoreVersion) script.ignoreVersion = "";
         return scriptClient
           .install({ script, code })
-          .then((update): Script => {
-            if (!update) {
+          .then((result): Script => {
+            if (!result.update) {
               Message.success(t("create_success_note"));
               // 保存的时候如何左侧没有脚本即新建
               setScriptList((prev) => {
@@ -267,6 +343,7 @@ function ScriptEditor() {
                     ? {
                         ...script,
                         name,
+                        updatetime: result.updatetime || script.updatetime,
                       }
                     : script
                 )
@@ -285,6 +362,7 @@ function ScriptEditor() {
                       script: {
                         ...item.script,
                         name,
+                        updatetime: result.updatetime || item.script.updatetime,
                       },
                     }
                   : item
@@ -303,7 +381,7 @@ function ScriptEditor() {
       });
   };
 
-  const saveAs = (script: Script, e: editor.IStandaloneCodeEditor) => {
+  const saveAs = (script: Script, e: editor.ICodeEditor) => {
     return new Promise<void>((resolve) => {
       chrome.downloads.download(
         {
@@ -428,18 +506,12 @@ function ScriptEditor() {
   ];
 
   // 根据菜单生产快捷键
-  const hotKeys: HotKey[] = [];
-  let activeTab = "";
-  for (let i = 0; i < editors.length; i += 1) {
-    if (editors[i].active) {
-      activeTab = i.toString();
-      break;
-    }
-  }
+  const hotKeys = useRef<HotKey[]>([]);
+  hotKeys.current = [];
   menu.forEach((item) => {
     item.items?.forEach((menuItem) => {
       if (menuItem.hotKey) {
-        hotKeys.push({
+        hotKeys.current.push({
           id: menuItem.id,
           title: menuItem.title,
           hotKey: menuItem.hotKey,
@@ -448,97 +520,53 @@ function ScriptEditor() {
       }
     });
   });
+
+  const templateVal = useRef(pageUrlSearchParams.get("template"));
+  const targetVal = useRef(pageUrlSearchParams.get("target"));
+
+  // 初始化 & 网址改变
   useEffect(() => {
-    const [alreadyInit] = [pageInit];
-    if (!alreadyInit) {
-      setPageInit(true); // 防止开发模式下重复初始化
+    const template = pageUrlSearchParams.get("template");
+    const target = pageUrlSearchParams.get("target");
+    if (template) templateVal.current = template;
+    if (target) targetVal.current = target;
 
-      const newParams = new URLSearchParams(pageUrlSearchParams);
-      if (newParams.get("d")) {
-        newParams.delete("d");
-        setPageUrlSearchParams(newParams, { replace: true });
+    if (canLoadScript) {
+      const uuid = pageUrlParams.uuid;
+      if (uuid === selectedScript) return;
+      if (!uuid || editorFindItem(uuid) || scriptList.find((v) => v.uuid === uuid)) {
+        const template = templateVal.current;
+        const target = targetVal.current;
+        openScript(uuid || undefined, template || undefined, target || undefined);
+      } else {
+        if (!selectedScript) {
+          // e.g. F5 reload the script editor page with an unsaved template script.
+          openScript(undefined, template || undefined, target || undefined);
+        } else {
+          Message.error("Invalid UUID");
+        }
       }
-
-      scriptDAO.all().then((scripts) => {
-        setScriptList(scripts.sort((a, b) => a.sort - b.sort));
-        setCanLoadScript(true);
-      });
     }
-    // 恢复标题
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [canLoadScript, pageUrlSearchParams, pageUrlParams.uuid, navigate]);
+
+  const updateScriptList = () => {
+    return scriptDAO.all().then((scripts) => {
+      setScriptList(scripts.sort((a, b) => a.sort - b.sort));
+      setCanLoadScript(true);
+    });
+  };
+
+  // 页面初次挂载：获取脚本列表
+  useEffect(() => {
+    updateScriptList();
+    // 离开ScriptEditor时恢复标题
     return () => {
       document.title = "Home - ScriptCat";
     };
   }, []);
 
-  const memoUrlQueryString = useMemo(() => {
-    return `${pageUrlParams.uuid || ""}|${pageUrlSearchParams.get("template") || ""}|${pageUrlSearchParams.get("target") || ""}|${pageUrlSearchParams.get("d") || ""}`;
-  }, [pageUrlParams, pageUrlSearchParams]);
-
-  useEffect(() => {
-    if (!canLoadScript) return;
-
-    const [uuid, template, target, d] = memoUrlQueryString.split("|");
-    if (d) return;
-    const newParams = new URLSearchParams(pageUrlSearchParams);
-    newParams.set("d", `${Date.now()}`);
-    setPageUrlSearchParams(newParams, { replace: true });
-
-    // 如果有id则打开对应的脚本
-    if (uuid) {
-      const [scripts] = [scriptList];
-      for (let i = 0; i < scripts.length; i += 1) {
-        if (scripts[i].uuid === uuid) {
-          // 如果已经打开则激活
-          scriptCodeDAO.findByUUID(uuid).then((code) => {
-            const uuid = scripts[i].uuid;
-            setEditors((prev) => {
-              const flag = prev.some((item) => item.script.uuid === uuid);
-              if (flag) {
-                return prev.map((item) =>
-                  item.script.uuid === uuid
-                    ? {
-                        ...item,
-                        active: true,
-                      }
-                    : {
-                        ...item,
-                        active: false,
-                      }
-                );
-              } else {
-                const newEditor = {
-                  script: scripts[i],
-                  code: code?.code || "",
-                  active: true,
-                  hotKeys,
-                  isChanged: false,
-                };
-                return [...prev, newEditor];
-              }
-            });
-            setSelectSciptButtonAndTab(uuid);
-          });
-          break;
-        }
-      }
-    } else {
-      emptyScript(template || "", hotKeys, target || "blank").then((e) => {
-        setEditors((prev) => {
-          prev.forEach((item) => {
-            if (item) {
-              item.active = false;
-            }
-          });
-          const uuid = e?.script?.uuid;
-          if (uuid) {
-            setSelectSciptButtonAndTab(uuid);
-          }
-          return [...prev, e];
-        });
-      });
-    }
-  }, [canLoadScript, memoUrlQueryString]);
-
   // 控制onbeforeunload
   useEffect(() => {
     let flag = false;
@@ -567,130 +595,104 @@ function ScriptEditor() {
   }, [editors]);
 
   // 对tab点击右键进行的操作
+  // 1 关闭当前, 2关闭其它, 3关闭左侧, 4关闭右侧
   useEffect(() => {
-    let selectEditorIndex: number = 0;
-    // 1 关闭当前, 2关闭其它, 3关闭左侧, 4关闭右侧
-    if (rightOperationTab) {
+    if (!rightOperationTab) return;
+
+    setEditors((prev) => {
+      const idx = editorFindIndex(rightOperationTab.uuid);
+      if (idx === -1) return prev;
+
+      let newList = [...prev];
       switch (rightOperationTab.key) {
         case "1":
-          setEditors((prev) => {
-            prev = prev.filter((item) => item.script.uuid !== rightOperationTab.uuid);
-            if (prev.length > 0) {
-              // 还有的话，如果之前有选中的，那么我们还是选中之前的，如果没有选中的我们就选中第一个
-              if (rightOperationTab.selectSciptButtonAndTab === rightOperationTab.uuid) {
-                prev[0] = {
-                  ...prev[0],
-                  active: true,
-                };
-                const chooseTabUUID = prev[0].script.uuid;
-                setSelectSciptButtonAndTab(chooseTabUUID);
-                return prev;
-              } else {
-                const prevTabUUID = rightOperationTab.selectSciptButtonAndTab;
-                setSelectSciptButtonAndTab(prevTabUUID);
-                // 之前选中的tab
-                return prev.map((item) =>
-                  item.script.uuid === prevTabUUID
-                    ? {
-                        ...item,
-                        active: true,
-                      }
-                    : {
-                        ...item,
-                        active: false,
-                      }
-                );
-              }
-            } else {
-              return [];
-            }
-          });
+          newList = newList.filter((e) => e.script.uuid !== rightOperationTab.uuid);
           break;
         case "2":
-          setSelectSciptButtonAndTab(rightOperationTab.uuid);
-          setEditors((prev) => prev.filter((item) => item.script.uuid === rightOperationTab.uuid));
+          newList = newList.filter((e) => e.script.uuid === rightOperationTab.uuid);
           break;
         case "3":
-          setEditors((prev) => {
-            prev.some((item, index) => {
-              if (item.script.uuid === rightOperationTab.uuid) {
-                selectEditorIndex = index;
-                return true;
-              }
-            });
-            return prev.slice(selectEditorIndex);
-          });
+          newList = newList.slice(idx);
           break;
         case "4":
-          setEditors((prev) => {
-            prev.some((item, index) => {
-              if (item.script.uuid === rightOperationTab.uuid) {
-                selectEditorIndex = index;
-                return true;
-              }
-            });
-            return prev.slice(0, selectEditorIndex + 1);
-          });
+          newList = newList.slice(0, idx + 1);
+          break;
       }
-    }
+
+      // 关键修复：确保关闭后仍有一个 Tab 是激活的
+      if (newList.length > 0 && !newList.some((e) => e.active)) {
+        newList[0] = { ...newList[0], active: true };
+        setSelectSciptButtonAndTab(newList[0].script.uuid);
+      }
+      return newList;
+    });
+    setRightOperationTab(undefined); // 处理完清空，防止重复触发
   }, [rightOperationTab]);
 
   // 通用的编辑器删除处理函数
-  const handleDeleteEditor = (targetUuid: string, needConfirm: boolean = false) => {
-    setEditors((prev) => {
-      const targetIndex = prev.findIndex((e) => e.script.uuid === targetUuid);
-      if (targetIndex === -1) return prev;
-
-      const targetEditor = prev[targetIndex];
+  const handleDeleteEditor = async (targetUuid: string, needConfirm: boolean = false) => {
+    const editors = editorsRef.current;
+    const targetIndex = editorFindIndex(targetUuid);
+    if (targetIndex === -1) return;
+    const targetEditor = editors[targetIndex];
 
-      // 如果需要确认且脚本已修改
-      if (needConfirm && targetEditor.isChanged) {
-        if (!confirm(t("script_modified_close_confirm"))) {
-          return prev;
-        }
-      }
+    // 如果需要确认且脚本已修改
+    if (needConfirm && targetEditor.isChanged) {
+      if (!confirm(t("script_modified_close_confirm"))) return;
+    }
 
-      // 如果只剩一个编辑器，打开空白脚本
-      if (prev.length === 1) {
-        const template = pageUrlSearchParams.get("template") || "";
-        emptyScript(template || "", hotKeys, "blank").then((e) => {
-          setEditors([e]);
-          setSelectSciptButtonAndTab(e.script.uuid);
-        });
-        return prev;
-      }
+    // 如果只剩一个编辑器，打开空白脚本
+    if (editors.length === 1) {
+      const template = templateVal.current || "";
+      const e = await emptyScript(template || "", hotKeys.current, "blank");
+      setEditors([e]);
+      setSelectSciptButtonAndTab(e.script.uuid);
+      return;
+    }
 
+    setEditors((prev) => {
+      // 在回调中重新计算 index，避免 confirm/await 期间状态变化导致的竞态问题
+      const currentIndex = prev.findIndex((e) => e.script.uuid === targetUuid);
+      if (currentIndex === -1) return prev;
+      const currentEditor = prev[currentIndex];
       // 删除目标编辑器
-      prev = prev.filter((_, index) => index !== targetIndex);
-
+      const filtered = prev.filter((e) => e.script.uuid !== targetUuid);
       // 如果删除的是当前激活的编辑器，需要激活其他编辑器
-      if (targetEditor.active && prev.length > 0) {
-        let nextActiveIndex;
-        if (targetIndex >= prev.length) {
-          // 如果删除的是最后一个，激活前一个
-          nextActiveIndex = prev.length - 1;
-        } else {
-          // 否则激活下一个（原来的下一个现在在同样的位置）
-          nextActiveIndex = targetIndex;
-        }
-        prev[nextActiveIndex].active = true;
-        setSelectSciptButtonAndTab(prev[nextActiveIndex].script.uuid);
+      if (currentEditor.active && filtered.length > 0) {
+        // 如果删除的是最后一个，激活前一个
+        // 否则激活下一个（原来的下一个现在在同样的位置）
+        const nextActiveIndex = currentIndex >= filtered.length ? filtered.length - 1 : currentIndex;
+        filtered[nextActiveIndex] = { ...filtered[nextActiveIndex], active: true };
+        setSelectSciptButtonAndTab(filtered[nextActiveIndex].script.uuid);
       }
-
-      return prev;
+      return filtered;
     });
   };
 
   // 处理编辑器激活状态变化时的focus
   useEffect(() => {
-    editors.forEach((item) => {
-      if (item.active && item.editor) {
-        setTimeout(() => {
-          item.editor?.focus();
-        }, 100);
-      }
+    if (!selectedScript) return;
+    if (pageUrlParams.uuid !== selectedScript) {
+      navigate(`/script/editor/${selectedScript}`, { replace: true });
+    }
+    delayedEditorFocus(null);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedScript]); // 只在activeTab变化时执行
+
+  const handleEditorChange = (uuid: string, newCode: string) => {
+    const targetEditor = editorFindItem(uuid);
+    if (!targetEditor) return;
+    const isChanged = targetEditor.code !== newCode;
+    if (targetEditor.isChanged === isChanged) return;
+    setEditors((prev) => prev.map((e) => (e.script.uuid !== uuid ? e : { ...e, isChanged: isChanged })));
+  };
+
+  const filteredScriptList = useMemo(() => {
+    return scriptList.filter((script) => {
+      if (!searchKeyword) return true;
+      return i18nName(script).toLowerCase().includes(searchKeyword.toLowerCase());
     });
-  }, [activeTab]); // 只在activeTab变化时执行
+  }, [scriptList, searchKeyword]);
 
   return (
     <div
@@ -911,19 +913,14 @@ function ScriptEditor() {
                   />
                 </div>
               )}
-              {scriptList
-                .filter((script) => {
-                  if (!searchKeyword) return true;
-                  return i18nName(script).toLowerCase().includes(searchKeyword.toLowerCase());
-                })
-                .map((script) => (
-                  <div
-                    key={`s_${script.uuid}`}
-                    className="tw-relative group"
-                    style={{
-                      overflow: "hidden",
-                    }}
-                  >
+              {filteredScriptList.map((script) => {
+                const editor = editorFindItem(script.uuid);
+                const colorRGB = !editor ? "173,173,173" : editor.isChanged ? "230,155,31" : "199,199,199";
+                const alpha = script.status === 2 ? 0.8 : 1.0;
+                const colorRGBA = `rgba(${colorRGB},${alpha})`;
+                const delBtnRGBA = `rgba(173,173,173,${alpha})`;
+                return (
+                  <div key={`s_${script.uuid}`} className="tw-relative tw-group">
                     <Button
                       size="mini"
                       className="tw-text-left tw-w-full"
@@ -931,38 +928,12 @@ function ScriptEditor() {
                         overflow: "hidden",
                         textOverflow: "ellipsis",
                         whiteSpace: "nowrap",
-                        backgroundColor: selectSciptButtonAndTab === script.uuid ? "gray" : "",
+                        color: `${colorRGBA}`,
+                        backgroundColor: selectedScript === script.uuid ? "#414958" : editor ? "#474747" : "#333333",
                         paddingRight: "32px", // 为删除按钮留出空间
                       }}
                       onClick={() => {
-                        setSelectSciptButtonAndTab(script.uuid);
-                        // 如果已经打开则激活
-                        let flag = false;
-                        for (let i = 0; i < editors.length; i += 1) {
-                          if (editors[i].script.uuid === script.uuid) {
-                            editors[i].active = true;
-                            flag = true;
-                          } else {
-                            editors[i].active = false;
-                          }
-                        }
-                        if (!flag) {
-                          // 如果没有打开则打开
-                          // 获取code
-                          scriptCodeDAO.findByUUID(script.uuid).then((code) => {
-                            if (!code) {
-                              return;
-                            }
-                            const newEditor = {
-                              script,
-                              code: code.code,
-                              active: true,
-                              hotKeys,
-                              isChanged: false,
-                            };
-                            setEditors((prev) => [...prev, newEditor]);
-                          });
-                        }
+                        openScript(script.uuid);
                       }}
                     >
                       <span className="tw-overflow-hidden tw-text-ellipsis">{i18nName(script)}</span>
@@ -980,7 +951,7 @@ function ScriptEditor() {
                         minWidth: "20px",
                         border: "none",
                         background: "transparent",
-                        color: "var(--color-text-2)",
+                        color: `${delBtnRGBA}`,
                         boxShadow: "none",
                       }}
                       onClick={(e) => {
@@ -989,13 +960,16 @@ function ScriptEditor() {
                         modal.confirm!({
                           title: t("confirm_delete_script"),
                           content: t("confirm_delete_script_content", { name: i18nName(script) }),
+                          focusLock: false,
+                          simple: false,
+                          closable: true,
                           onOk: () => {
                             scriptClient
                               .deletes([script.uuid])
                               .then(() => {
                                 setScriptList((prev) => prev.filter((s) => s.uuid !== script.uuid));
                                 handleDeleteEditor(script.uuid);
-                                if (selectSciptButtonAndTab === script.uuid) {
+                                if (selectedScript === script.uuid) {
                                   setSelectSciptButtonAndTab("");
                                 }
                                 Message.success(t("delete_success"));
@@ -1005,11 +979,15 @@ function ScriptEditor() {
                                 Message.error(`${t("delete_failed")}: ${err}`);
                               });
                           },
+                          onCancel: () => {
+                            delayedEditorFocus(null);
+                          },
                         });
                       }}
                     />
                   </div>
-                ))}
+                );
+              })}
             </div>
           </Col>
         )}
@@ -1017,53 +995,31 @@ function ScriptEditor() {
           <div className="tw-flex tw-flex-row tw-w-full tw-justify-between">
             <Tabs
               editable
-              activeTab={activeTab}
+              activeTab={selectedScript}
               className="edit-tabs"
               type="card-gutter"
               style={{
                 overflow: "hidden",
               }}
-              onChange={(index: string) => {
-                setEditors((prev) =>
-                  prev.map((editor, i) =>
-                    `${i}` === index
-                      ? {
-                          ...editor,
-                          active:
-                            (setSelectSciptButtonAndTab(editor.script.uuid), // 需要用 microTask 推遲嗎？
-                            true),
-                        }
-                      : {
-                          ...editor,
-                          active: false,
-                        }
-                  )
-                );
-              }}
-              onAddTab={() => {
-                const template = pageUrlSearchParams.get("template") || "";
-                emptyScript(template || "", hotKeys, "blank").then((e) => {
-                  setEditors((prev) => {
-                    prev.forEach((item) => {
-                      item.active = false;
-                    });
-                    setSelectSciptButtonAndTab(e.script.uuid);
-                    return [...prev, e];
-                  });
-                });
+              onChange={(uuid) => {
+                // rightTabOperation 时会发生多次 onChange
+                // 只取最后一个
+                clearTimeout(cidRef.current);
+                cidRef.current = setTimeout(() => {
+                  if (editorFindIndex(uuid) >= 0) {
+                    openScript(uuid);
+                  }
+                }, 1);
               }}
-              onDeleteTab={(index: string) => {
-                const i = parseInt(index, 10);
-                const targetUuid = editors[i]?.script.uuid;
-                if (targetUuid) {
-                  handleDeleteEditor(targetUuid, true);
-                }
+              onAddTab={() => openScript(undefined, templateVal.current || undefined, undefined)} // 不传参数即为新建
+              onDeleteTab={(uuid) => {
+                handleDeleteEditor(uuid, true);
               }}
             >
-              {editors.map((e, index) => (
+              {editors.map((e, _index) => (
                 <TabPane
                   destroyOnHide
-                  key={index!.toString()}
+                  key={e.script.uuid}
                   title={
                     <Dropdown
                       trigger="contextMenu"
@@ -1075,7 +1031,7 @@ function ScriptEditor() {
                               ...rightOperationTab,
                               key,
                               uuid: e.script.uuid,
-                              selectSciptButtonAndTab,
+                              selectSciptButtonAndTab: selectedScript,
                             });
                           }}
                         >
@@ -1090,7 +1046,7 @@ function ScriptEditor() {
                         style={{
                           color: e.isChanged
                             ? "rgb(var(--orange-5))"
-                            : e.script.uuid === selectSciptButtonAndTab
+                            : e.script.uuid === selectedScript
                               ? "rgb(var(--green-7))"
                               : e.active
                                 ? "rgb(var(--green-7))"
@@ -1142,8 +1098,8 @@ function ScriptEditor() {
                   <WarpEditor
                     className="script-code-editor"
                     key={`e_${item.script.uuid}`}
-                    id={`e_${item.script.uuid}`}
-                    script={item.script}
+                    id={`${item.script.uuid}`}
+                    getScript={getScript}
                     code={item.code}
                     hotKeys={item.hotKeys}
                     callbackEditor={(e) => {
@@ -1152,26 +1108,14 @@ function ScriptEditor() {
                           v.script.uuid === item.script.uuid
                             ? {
                                 ...v,
-                                editor:
-                                  (v.active && setTimeout(() => e.focus(), 100), // 编辑器实例创建后立即聚焦一次
-                                  e),
+                                editor: e,
                               }
                             : v
                         )
                       );
+                      delayedEditorFocus(e); // 编辑器实例创建后立即聚焦一次
                     }}
-                    onChange={(code) => {
-                      setEditors((prev) => {
-                        const script = prev.find((v) => v.script.uuid === item.script.uuid);
-                        if (!script) return prev;
-                        const isChanged = !(script.code === code);
-                        if (isChanged !== script.isChanged) {
-                          script.isChanged = isChanged;
-                          return [...prev];
-                        }
-                        return prev;
-                      });
-                    }}
+                    onChange={(code) => handleEditorChange(item.script.uuid, code)}
                   />
                 </div>
               );
diff --git a/src/pages/options/routes/script/index.css b/src/pages/options/routes/script/index.css
index dd878a496..8ce5d1773 100644
--- a/src/pages/options/routes/script/index.css
+++ b/src/pages/options/routes/script/index.css
@@ -6,11 +6,11 @@
 }
 
 .script-code-editor {
-	margin: 0;
-	padding: 0;
-	border: 0;
-	width: 100%;
-	height: 100%;
-	overflow: hidden;
-	box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  box-sizing: border-box;
 }
diff --git a/src/pages/sandbox.html b/src/pages/sandbox.html
index 3761c576f..3f7c8b4c5 100644
--- a/src/pages/sandbox.html
+++ b/src/pages/sandbox.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
diff --git a/src/pages/store/favicons.test.ts b/src/pages/store/favicons.test.ts
index 6f78f81b0..d3a9f023f 100644
--- a/src/pages/store/favicons.test.ts
+++ b/src/pages/store/favicons.test.ts
@@ -1,5 +1,12 @@
-import { extractFaviconsDomain } from "@App/pages/store/favicons";
-import { describe, it, expect } from "vitest";
+import {
+  extractFaviconsDomain,
+  extractDomainFromPattern,
+  parseFaviconsNew,
+  fetchIconByService,
+  fetchIconByDomain,
+  timeoutAbortSignal,
+} from "@App/pages/store/favicons";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 describe("extractFaviconsDomain", () => {
   it("应该正确提取各种URL模式的域名", () => {
@@ -41,4 +48,285 @@ describe("extractFaviconsDomain", () => {
     expect(extractFaviconsDomain([], [])).toEqual([]);
     expect(extractFaviconsDomain()).toEqual([]);
   });
+
+  it("相同域名应该去重", () => {
+    const result = extractFaviconsDomain(["https://example.com/page1", "https://example.com/page2"], []);
+    // 两个pattern提取出相同域名 example.com，应去重
+    expect(result).toHaveLength(1);
+    expect(result[0].domain).toBe("example.com");
+  });
+});
+
+describe("extractDomainFromPattern", () => {
+  // 基础场景已在 extractFaviconsDomain 中覆盖，这里只测试额外边界情况
+  it("应该从带query参数的URL中提取域名", () => {
+    expect(extractDomainFromPattern("https://www.google.com/search?q=test")).toBe("www.google.com");
+  });
+
+  it("空字符串应返回null", () => {
+    expect(extractDomainFromPattern("")).toBe(null);
+  });
+});
+
+describe("parseFaviconsNew", () => {
+  it("应该解析标准favicon link标签", () => {
+    const hrefs: string[] = [];
+    const html = '<html><head><link rel="icon" href="/favicon.ico"></head></html>';
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toEqual(["/favicon.ico"]);
+  });
+
+  it("应该解析apple-touch-icon", () => {
+    const hrefs: string[] = [];
+    const html = '<link rel="apple-touch-icon" href="/apple-icon.png">';
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toEqual(["/apple-icon.png"]);
+  });
+
+  it("应该解析apple-touch-icon-precomposed", () => {
+    const hrefs: string[] = [];
+    const html = '<link rel="apple-touch-icon-precomposed" href="/precomposed.png">';
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toEqual(["/precomposed.png"]);
+  });
+
+  it("应该解析多个favicon link标签", () => {
+    const hrefs: string[] = [];
+    const html = `
+      <link rel="icon" href="/icon1.png">
+      <link rel="icon" href="/icon2.png">
+      <link rel="apple-touch-icon" href="/icon3.png">
+    `;
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toHaveLength(3);
+    expect(hrefs).toEqual(["/icon1.png", "/icon2.png", "/icon3.png"]);
+  });
+
+  it("没有link标签时不应调用回调", () => {
+    const callback = vi.fn();
+    parseFaviconsNew("<html><body>hello</body></html>", callback);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("应该忽略非favicon的link标签", () => {
+    const hrefs: string[] = [];
+    const html = '<link rel="stylesheet" href="/style.css"><link rel="icon" href="/icon.png">';
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toEqual(["/icon.png"]);
+  });
+
+  it("应该处理单引号和双引号", () => {
+    const hrefs: string[] = [];
+    const html = `<link rel='icon' href='/icon1.png'><link rel="icon" href="/icon2.png">`;
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toEqual(["/icon1.png", "/icon2.png"]);
+  });
+
+  it("应该处理大小写混合的标签", () => {
+    const hrefs: string[] = [];
+    const html = '<LINK REL="icon" HREF="/icon.png">';
+    parseFaviconsNew(html, (href) => hrefs.push(href));
+    expect(hrefs).toEqual(["/icon.png"]);
+  });
+});
+
+// 创建模拟HTML Response的辅助函数
+const mockHtmlResponse = (url: string, html: string) => ({
+  ok: true,
+  url,
+  headers: new Headers({ "content-type": "text/html; charset=utf-8" }),
+  arrayBuffer: () => Promise.resolve(new TextEncoder().encode(html).buffer),
+});
+
+describe("fetchIconByService", () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        url: "https://example.com/favicon.ico",
+        text: () => Promise.resolve(""),
+        blob: () => Promise.resolve(new Blob()),
+        headers: new Headers({ "content-type": "text/html" }),
+      })
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("scriptcat服务应返回scriptcat API URL", async () => {
+    const result = await fetchIconByService("example.com", "scriptcat");
+    expect(result).toEqual(["https://ext.scriptcat.org/api/v1/open/favicons?domain=example.com&sz=64"]);
+  });
+
+  it("google服务应返回Google favicon URL", async () => {
+    const result = await fetchIconByService("example.com", "google");
+    expect(result).toEqual(["https://www.google.com/s2/favicons?domain=example.com&sz=64"]);
+  });
+
+  it("应该对域名进行URL编码", async () => {
+    const result = await fetchIconByService("例え.jp", "scriptcat");
+    expect(result).toEqual([
+      `https://ext.scriptcat.org/api/v1/open/favicons?domain=${encodeURIComponent("例え.jp")}&sz=64`,
+    ]);
+  });
+
+  // local 服务的具体行为已在 fetchIconByDomain 测试中充分覆盖
+});
+
+describe("fetchIconByDomain", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("应该从HTML中解析favicon并验证", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://example.com") {
+          return Promise.resolve(
+            mockHtmlResponse(
+              "https://example.com/",
+              '<html><head><link rel="icon" href="/static/favicon.ico"></head></html>'
+            )
+          );
+        }
+        return Promise.resolve({ ok: true, url: "https://example.com/static/favicon.ico" });
+      })
+    );
+
+    const icons = await fetchIconByDomain("example.com");
+    expect(icons).toEqual(["https://example.com/static/favicon.ico"]);
+  });
+
+  it("没有link标签时应回退到/favicon.ico", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://noicon.com") {
+          return Promise.resolve(mockHtmlResponse("https://noicon.com/", "<html><head></head></html>"));
+        }
+        return Promise.resolve({ ok: true, url: "https://noicon.com/favicon.ico" });
+      })
+    );
+
+    const icons = await fetchIconByDomain("noicon.com");
+    expect(icons).toEqual(["https://noicon.com/favicon.ico"]);
+  });
+
+  it("HEAD请求失败时应过滤掉该icon", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://fail.com") {
+          return Promise.resolve(
+            mockHtmlResponse("https://fail.com/", '<html><head><link rel="icon" href="/missing.ico"></head></html>')
+          );
+        }
+        return Promise.reject(new Error("Not found"));
+      })
+    );
+
+    const icons = await fetchIconByDomain("fail.com");
+    expect(icons).toEqual([]);
+  });
+
+  it("HEAD请求返回非OK状态时应过滤掉该icon", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://badstatus.com") {
+          return Promise.resolve(
+            mockHtmlResponse("https://badstatus.com/", '<html><head><link rel="icon" href="/icon.png"></head></html>')
+          );
+        }
+        return Promise.resolve({ ok: false, url: "https://badstatus.com/icon.png" });
+      })
+    );
+
+    const icons = await fetchIconByDomain("badstatus.com");
+    expect(icons).toEqual([]);
+  });
+
+  it("HEAD请求重定向到不同文件名时应过滤", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://redirect.com") {
+          return Promise.resolve(
+            mockHtmlResponse("https://redirect.com/", '<html><head><link rel="icon" href="/icon.png"></head></html>')
+          );
+        }
+        return Promise.resolve({ ok: true, url: "https://redirect.com/404.html" });
+      })
+    );
+
+    const icons = await fetchIconByDomain("redirect.com");
+    expect(icons).toEqual([]);
+  });
+
+  it("应该正确解析相对URL为绝对URL", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://cdn.example.com") {
+          // 页面重定向到了不同的URL
+          return Promise.resolve(
+            mockHtmlResponse(
+              "https://www.example.com/home",
+              '<html><head><link rel="icon" href="../assets/icon.png"></head></html>'
+            )
+          );
+        }
+        return Promise.resolve({ ok: true, url: "https://www.example.com/assets/icon.png" });
+      })
+    );
+
+    const icons = await fetchIconByDomain("cdn.example.com");
+    expect(icons).toEqual(["https://www.example.com/assets/icon.png"]);
+  });
+
+  it("应该处理多个favicon并全部验证", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((url: string | URL) => {
+        const urlStr = url.toString();
+        if (urlStr === "https://multi.com") {
+          return Promise.resolve(
+            mockHtmlResponse(
+              "https://multi.com/",
+              `<html><head>
+                <link rel="icon" href="/icon16.png">
+                <link rel="icon" href="/icon32.png">
+                <link rel="apple-touch-icon" href="/apple.png">
+              </head></html>`
+            )
+          );
+        }
+        // 所有HEAD请求都成功
+        return Promise.resolve({ ok: true, url: urlStr });
+      })
+    );
+
+    const icons = await fetchIconByDomain("multi.com");
+    expect(icons).toHaveLength(3);
+    expect(icons).toContain("https://multi.com/icon16.png");
+    expect(icons).toContain("https://multi.com/icon32.png");
+    expect(icons).toContain("https://multi.com/apple.png");
+  });
+});
+
+describe("timeoutAbortSignal", () => {
+  it("应该返回AbortSignal", () => {
+    const signal = timeoutAbortSignal(5000);
+    expect(signal).toBeInstanceOf(AbortSignal);
+  });
 });
diff --git a/src/pages/store/favicons.ts b/src/pages/store/favicons.ts
index 0ed61ef6f..feb2da4df 100644
--- a/src/pages/store/favicons.ts
+++ b/src/pages/store/favicons.ts
@@ -3,11 +3,26 @@ import { FaviconDAO, type FaviconFile, type FaviconRecord } from "@App/app/repo/
 import { v5 as uuidv5 } from "uuid";
 import { getFaviconRootFolder } from "@App/app/service/service_worker/utils";
 import { readBlobContent } from "@App/pkg/utils/encoding";
+import type { FaviconService } from "@App/pkg/config/config";
 
 let scriptDAO: ScriptDAO | null = null;
 let faviconDAO: FaviconDAO | null = null;
 const loadFaviconPromises = new Map<string, any>(); // 关联 iconUrl 和 blobUrl
 
+// 清除内存中的 favicon 缓存，切换服务时调用
+export const clearFaviconMemoryCache = () => {
+  loadFaviconPromises.forEach((promise) => {
+    Promise.resolve(promise)
+      .then((blobUrl) => {
+        if (typeof blobUrl === "string" && blobUrl.startsWith("blob:")) {
+          URL.revokeObjectURL(blobUrl);
+        }
+      })
+      .catch(() => {});
+  });
+  loadFaviconPromises.clear();
+};
+
 /**
  * 从URL模式中提取域名
  */
@@ -179,8 +194,26 @@ export async function fetchIconByDomain(domain: string): Promise<string[]> {
   return urls.filter((url) => !!url) as string[];
 }
 
+/**
+ * 根据服务类型获取favicon URL列表
+ */
+export async function fetchIconByService(domain: string, service: FaviconService): Promise<string[]> {
+  switch (service) {
+    case "scriptcat":
+      return [`https://ext.scriptcat.org/api/v1/open/favicons?domain=${encodeURIComponent(domain)}&sz=64`];
+    case "google":
+      return [`https://www.google.com/s2/favicons?domain=${encodeURIComponent(domain)}&sz=64`];
+    case "local":
+    default:
+      return await fetchIconByDomain(domain);
+  }
+}
+
 // 获取脚本的favicon
-export const getScriptFavicon = async (uuid: string): Promise<FaviconRecord[]> => {
+export const getScriptFavicon = async (
+  uuid: string,
+  service: FaviconService = "scriptcat"
+): Promise<FaviconRecord[]> => {
   scriptDAO ||= new ScriptDAO();
   faviconDAO ||= new FaviconDAO();
   const script = await scriptDAO.get(uuid);
@@ -199,7 +232,7 @@ export const getScriptFavicon = async (uuid: string): Promise<FaviconRecord[]> =
     domains.map(async (domain) => {
       try {
         if (domain.domain) {
-          const icons = await fetchIconByDomain(domain.domain);
+          const icons = await fetchIconByService(domain.domain, service);
           const icon = icons.length > 0 ? icons[0] : "";
           return { match: domain.match, website: "http://" + domain.domain, icon };
         }
@@ -233,6 +266,11 @@ export const loadFavicon = async (iconUrl: string): Promise<string> => {
     // 文件不存在，下载并保存
     const newFileHandle = await directoryHandle.getFileHandle(filename, { create: true });
     const response = await fetch(iconUrl);
+    if (response.status >= 300) {
+      // 状态码异常，删除创建的空文件并抛出错误
+      await directoryHandle.removeEntry(filename).catch(() => {});
+      throw new Error(`Favicon fetch failed with status ${response.status}`);
+    }
     const blob = await response.blob();
     const writable = await newFileHandle.createWritable();
     await writable.write(blob);
@@ -256,9 +294,9 @@ const getFileFromOPFS = async (opfsRet: FaviconFile): Promise<File> => {
 };
 
 // 处理单个脚本的favicon
-const processScriptFavicon = async (script: Script) => {
+const processScriptFavicon = async (script: Script, service: FaviconService = "scriptcat") => {
   const favFnAsync = async () => {
-    const icons = await getScriptFavicon(script.uuid); // 恒久。不会因SW重启而失效
+    const icons = await getScriptFavicon(script.uuid, service); // 恒久。不会因SW重启而失效
     if (icons.length === 0) return [];
     const newIcons = await Promise.all(
       icons.map(async (icon) => {
@@ -305,7 +343,7 @@ type FavIconResult = {
 type TFaviconStack = { chunkResults: FavIconResult[]; pendingCount: number };
 
 // 处理favicon加载，以批次方式处理
-export const loadScriptFavicons = async function* (scripts: Script[]) {
+export const loadScriptFavicons = async function* (scripts: Script[], service: FaviconService = "scriptcat") {
   const stack: TFaviconStack[] = [];
   const asyncWaiter: { promise?: any; resolve?: any } = {};
   const createPromise = () => {
@@ -319,7 +357,7 @@ export const loadScriptFavicons = async function* (scripts: Script[]) {
   const results: FavIconResult[] = [];
   let waiting = false;
   for (const script of scripts) {
-    processScriptFavicon(script).then((result: FavIconResult) => {
+    processScriptFavicon(script, service).then((result: FavIconResult) => {
       results.push(result);
       // 下一个 MacroTask 执行。
       // 使用 requestAnimationFrame 而非setTimeout 是因为前台才要显示。而且网页绘画中时会延后这个
diff --git a/src/pages/store/features/script.ts b/src/pages/store/features/script.ts
index 1e36d6c74..ed2cefbab 100644
--- a/src/pages/store/features/script.ts
+++ b/src/pages/store/features/script.ts
@@ -1,5 +1,6 @@
 import type { Script } from "@App/app/repo/scripts";
 import {
+  AgentClient,
   PermissionClient,
   PopupClient,
   ResourceClient,
@@ -21,6 +22,7 @@ export const permissionClient = new PermissionClient(message);
 export const valueClient = new ValueClient(message);
 export const resourceClient = new ResourceClient(message);
 export const synchronizeClient = new SynchronizeClient(message);
+export const agentClient = new AgentClient(message);
 
 export const fetchScriptList = async () => {
   return await scriptClient.getAllScripts();
diff --git a/src/pages/template.html b/src/pages/template.html
index 89a30c56d..6879472e2 100644
--- a/src/pages/template.html
+++ b/src/pages/template.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html>
   <head>
     <meta charset="UTF-8" />
diff --git a/src/pkg/config/config.ts b/src/pkg/config/config.ts
index 4215fb516..109d334fa 100644
--- a/src/pkg/config/config.ts
+++ b/src/pkg/config/config.ts
@@ -19,6 +19,8 @@ export type CloudSyncConfig = {
   params: { [key: string]: any };
 };
 
+export type FaviconService = "scriptcat" | "local" | "google";
+
 export type CATFileStorage = {
   filesystem: FileSystemType;
   params: { [key: string]: any };
@@ -474,6 +476,14 @@ export class SystemConfig {
   getScriptMenuDisplayType(): Promise<"no_browser" | "all"> {
     return this._get("script_menu_display_type", "all");
   }
+
+  getFaviconService() {
+    return this._get<FaviconService>("favicon_service", "scriptcat");
+  }
+
+  setFaviconService(val: FaviconService) {
+    return this._set("favicon_service", val);
+  }
 }
 
 let lazyScriptNamePrefix: string = "";
diff --git a/src/pkg/utils/cattool.test.ts b/src/pkg/utils/cattool.test.ts
new file mode 100644
index 000000000..7a276a217
--- /dev/null
+++ b/src/pkg/utils/cattool.test.ts
@@ -0,0 +1,476 @@
+import { describe, expect, it } from "vitest";
+import { parseCATToolMetadata, catToolToToolDefinition, getCATToolBody, prefixToolDefinition } from "./cattool";
+
+describe("parseCATToolMetadata", () => {
+  it("应正确解析完整的 CATTool 元数据", () => {
+    const code = `
+// ==CATTool==
+// @name        weather
+// @description 查询天气信息
+// @param       city string [required] 城市名称
+// @param       unit string[celsius,fahrenheit] 温度单位
+// @grant       GM.xmlHttpRequest
+// ==/CATTool==
+
+const result = await GM.xmlHttpRequest({ url: "https://api.weather.com/" + args.city });
+return result;
+`;
+    const meta = parseCATToolMetadata(code);
+    expect(meta).not.toBeNull();
+    expect(meta!.name).toBe("weather");
+    expect(meta!.description).toBe("查询天气信息");
+    expect(meta!.params).toHaveLength(2);
+
+    expect(meta!.params[0]).toEqual({
+      name: "city",
+      type: "string",
+      required: true,
+      description: "城市名称",
+    });
+
+    expect(meta!.params[1]).toEqual({
+      name: "unit",
+      type: "string",
+      required: false,
+      description: "温度单位",
+      enum: ["celsius", "fahrenheit"],
+    });
+
+    expect(meta!.grants).toEqual(["GM.xmlHttpRequest"]);
+  });
+
+  it("没有 ==CATTool== 头时返回 null", () => {
+    const code = `console.log("hello");`;
+    expect(parseCATToolMetadata(code)).toBeNull();
+  });
+
+  it("缺少 @name 时返回 null", () => {
+    const code = `
+// ==CATTool==
+// @description 没有名字的工具
+// ==/CATTool==
+return "test";
+`;
+    expect(parseCATToolMetadata(code)).toBeNull();
+  });
+
+  it("应正确解析 number 和 boolean 类型参数", () => {
+    const code = `
+// ==CATTool==
+// @name        calc
+// @description 计算器
+// @param       value number [required] 输入值
+// @param       verbose boolean 是否输出详细信息
+// ==/CATTool==
+return args.value * 2;
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.params[0].type).toBe("number");
+    expect(meta.params[0].required).toBe(true);
+    expect(meta.params[1].type).toBe("boolean");
+    expect(meta.params[1].required).toBe(false);
+  });
+
+  it("应正确解析无参数的工具", () => {
+    const code = `
+// ==CATTool==
+// @name        ping
+// @description 测试连通性
+// ==/CATTool==
+return "pong";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.name).toBe("ping");
+    expect(meta.params).toHaveLength(0);
+    expect(meta.grants).toHaveLength(0);
+  });
+
+  it("应正确解析多个 @grant", () => {
+    const code = `
+// ==CATTool==
+// @name        multi_grant
+// @description 多个 grant
+// @grant       GM.xmlHttpRequest
+// @grant       GM.getValue
+// @grant       GM.setValue
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.grants).toEqual(["GM.xmlHttpRequest", "GM.getValue", "GM.setValue"]);
+  });
+
+  it("应正确解析单个 @require URL", () => {
+    const code = `
+// ==CATTool==
+// @name        xlsx_tool
+// @description 生成 Excel
+// @require     https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js
+// ==/CATTool==
+return XLSX.utils.book_new();
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.requires).toEqual(["https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js"]);
+  });
+
+  it("应正确解析多个 @require URL", () => {
+    const code = `
+// ==CATTool==
+// @name        multi_require
+// @description 多个外部库
+// @require     https://cdn.example.com/lib1.js
+// @require     https://cdn.example.com/lib2.js
+// @require     https://cdn.example.com/lib3.js
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.requires).toEqual([
+      "https://cdn.example.com/lib1.js",
+      "https://cdn.example.com/lib2.js",
+      "https://cdn.example.com/lib3.js",
+    ]);
+  });
+
+  it("无 @require 时 requires 应为空数组", () => {
+    const code = `
+// ==CATTool==
+// @name        no_require
+// @description 无外部依赖
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.requires).toEqual([]);
+  });
+
+  it("空 @require 值不应加入列表", () => {
+    const code = `
+// ==CATTool==
+// @name        empty_require
+// @description 测试
+// @require
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.requires).toHaveLength(0);
+  });
+
+  it("空 @grant 值不应加入列表", () => {
+    const code = `
+// ==CATTool==
+// @name        empty_grant
+// @description 测试
+// @grant
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.grants).toHaveLength(0);
+  });
+
+  it("@param 带空 enum 括号时不应生成 enum 字段", () => {
+    const code = `
+// ==CATTool==
+// @name        test
+// @param       mode string[] 模式
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.params[0].enum).toBeUndefined();
+  });
+
+  it("@param enum 中的空格应被 trim", () => {
+    const code = `
+// ==CATTool==
+// @name        test
+// @param       color string[red , green , blue] 颜色选择
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.params[0].enum).toEqual(["red", "green", "blue"]);
+  });
+
+  it("无效的参数类型应被忽略", () => {
+    const code = `
+// ==CATTool==
+// @name        test
+// @param       data object 数据
+// @param       valid string 有效参数
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    // "object" 不是有效类型，应被忽略
+    expect(meta.params).toHaveLength(1);
+    expect(meta.params[0].name).toBe("valid");
+  });
+
+  it("仅有 @name 时应返回有效元数据", () => {
+    const code = `
+// ==CATTool==
+// @name        minimal
+// ==/CATTool==
+return 42;
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.name).toBe("minimal");
+    expect(meta.description).toBe("");
+    expect(meta.params).toHaveLength(0);
+    expect(meta.grants).toHaveLength(0);
+  });
+
+  it("非 @ 开头的行应被忽略", () => {
+    const code = `
+// ==CATTool==
+// @name        test
+// 这是一个注释，不是 @ 指令
+// @description 测试工具
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.name).toBe("test");
+    expect(meta.description).toBe("测试工具");
+  });
+
+  it("应正确解析 @timeout", () => {
+    const code = `
+// ==CATTool==
+// @name        slow_tool
+// @description 耗时工具
+// @timeout     120
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.name).toBe("slow_tool");
+    expect(meta.timeout).toBe(120);
+  });
+
+  it("无 @timeout 时 timeout 应为 undefined", () => {
+    const code = `
+// ==CATTool==
+// @name        fast_tool
+// @description 快速工具
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.timeout).toBeUndefined();
+  });
+
+  it("@timeout 值无效时应忽略", () => {
+    const code = `
+// ==CATTool==
+// @name        bad_timeout
+// @timeout     abc
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.timeout).toBeUndefined();
+  });
+
+  it("@timeout 值为 0 或负数时应忽略", () => {
+    const code = `
+// ==CATTool==
+// @name        zero_timeout
+// @timeout     0
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.timeout).toBeUndefined();
+
+    const code2 = `
+// ==CATTool==
+// @name        neg_timeout
+// @timeout     -5
+// ==/CATTool==
+return "ok";
+`;
+    const meta2 = parseCATToolMetadata(code2)!;
+    expect(meta2.timeout).toBeUndefined();
+  });
+
+  it("@param [required] 带 enum 时应同时解析", () => {
+    const code = `
+// ==CATTool==
+// @name        test
+// @param       level string[low,medium,high] [required] 级别
+// ==/CATTool==
+return "ok";
+`;
+    const meta = parseCATToolMetadata(code)!;
+    expect(meta.params[0].name).toBe("level");
+    expect(meta.params[0].required).toBe(true);
+    expect(meta.params[0].enum).toEqual(["low", "medium", "high"]);
+    expect(meta.params[0].description).toBe("级别");
+  });
+});
+
+describe("catToolToToolDefinition", () => {
+  it("应正确生成 JSON Schema 格式的 ToolDefinition", () => {
+    const def = catToolToToolDefinition({
+      name: "weather",
+      description: "查询天气",
+      params: [
+        { name: "city", type: "string", required: true, description: "城市" },
+        { name: "unit", type: "string", required: false, description: "单位", enum: ["c", "f"] },
+      ],
+      grants: [],
+      requires: [],
+    });
+
+    expect(def.name).toBe("weather");
+    expect(def.description).toBe("查询天气");
+    expect(def.parameters).toEqual({
+      type: "object",
+      properties: {
+        city: { type: "string", description: "城市" },
+        unit: { type: "string", description: "单位", enum: ["c", "f"] },
+      },
+      required: ["city"],
+    });
+  });
+
+  it("无 required 参数时不包含 required 字段", () => {
+    const def = catToolToToolDefinition({
+      name: "test",
+      description: "test",
+      params: [{ name: "x", type: "number", required: false, description: "x" }],
+      grants: [],
+      requires: [],
+    });
+
+    expect(def.parameters).not.toHaveProperty("required");
+  });
+
+  it("无参数时 properties 应为空对象", () => {
+    const def = catToolToToolDefinition({
+      name: "ping",
+      description: "连通性测试",
+      params: [],
+      grants: [],
+      requires: [],
+    });
+
+    expect(def.parameters).toEqual({
+      type: "object",
+      properties: {},
+    });
+  });
+
+  it("多个 required 参数应全部出现在 required 数组中", () => {
+    const def = catToolToToolDefinition({
+      name: "test",
+      description: "测试",
+      params: [
+        { name: "a", type: "string", required: true, description: "参数a" },
+        { name: "b", type: "number", required: true, description: "参数b" },
+        { name: "c", type: "boolean", required: false, description: "参数c" },
+      ],
+      grants: [],
+      requires: [],
+    });
+
+    expect((def.parameters as any).required).toEqual(["a", "b"]);
+  });
+
+  it("enum 参数应在 JSON Schema 中包含 enum 字段", () => {
+    const def = catToolToToolDefinition({
+      name: "test",
+      description: "测试",
+      params: [{ name: "color", type: "string", required: false, description: "颜色", enum: ["red", "green", "blue"] }],
+      grants: [],
+      requires: [],
+    });
+
+    const props = (def.parameters as any).properties;
+    expect(props.color.enum).toEqual(["red", "green", "blue"]);
+  });
+});
+
+describe("prefixToolDefinition", () => {
+  it("应给工具名添加前缀", () => {
+    const def = catToolToToolDefinition({
+      name: "price-check",
+      description: "查询价格",
+      params: [{ name: "url", type: "string", required: true, description: "目标URL" }],
+      grants: [],
+      requires: [],
+    });
+
+    const prefixed = prefixToolDefinition("taobao", def);
+
+    expect(prefixed.name).toBe("taobao__price-check");
+    expect(prefixed.description).toBe("查询价格");
+    expect(prefixed.parameters).toEqual(def.parameters);
+  });
+
+  it("不应修改原始 ToolDefinition", () => {
+    const def = catToolToToolDefinition({
+      name: "my-tool",
+      description: "测试",
+      params: [],
+      grants: [],
+      requires: [],
+    });
+
+    prefixToolDefinition("skill-a", def);
+
+    // 原始对象不变
+    expect(def.name).toBe("my-tool");
+  });
+
+  it("双下划线分隔应避免命名冲突", () => {
+    const def1 = catToolToToolDefinition({ name: "extract", description: "A", params: [], grants: [], requires: [] });
+    const def2 = catToolToToolDefinition({ name: "extract", description: "B", params: [], grants: [], requires: [] });
+
+    const p1 = prefixToolDefinition("skill-a", def1);
+    const p2 = prefixToolDefinition("skill-b", def2);
+
+    expect(p1.name).toBe("skill-a__extract");
+    expect(p2.name).toBe("skill-b__extract");
+    expect(p1.name).not.toBe(p2.name);
+  });
+});
+
+describe("getCATToolBody", () => {
+  it("应正确去掉元数据头返回脚本体", () => {
+    const code = `// ==CATTool==
+// @name test
+// ==/CATTool==
+const x = 1;
+return x;`;
+    const body = getCATToolBody(code);
+    expect(body).toBe("const x = 1;\nreturn x;");
+  });
+
+  it("无元数据头时应返回原始代码", () => {
+    const code = `const x = 1;\nreturn x;`;
+    const body = getCATToolBody(code);
+    expect(body).toBe("const x = 1;\nreturn x;");
+  });
+
+  it("应保留元数据头后面的所有代码", () => {
+    const code = `// ==CATTool==
+// @name test
+// @description 测试
+// @param city string [required] 城市
+// @grant GM.xmlHttpRequest
+// ==/CATTool==
+
+const result = await GM.xmlHttpRequest({url: "http://example.com/" + args.city});
+const data = JSON.parse(result.responseText);
+return data;`;
+    const body = getCATToolBody(code);
+    expect(body).toContain("const result = await GM.xmlHttpRequest");
+    expect(body).toContain("return data;");
+    expect(body).not.toContain("==CATTool==");
+  });
+});
diff --git a/src/pkg/utils/cattool.ts b/src/pkg/utils/cattool.ts
new file mode 100644
index 000000000..a5df12072
--- /dev/null
+++ b/src/pkg/utils/cattool.ts
@@ -0,0 +1,134 @@
+import type { CATToolMetadata, CATToolParam, ToolDefinition } from "@App/app/service/agent/types";
+
+// 解析 ==CATTool== 元数据头
+export function parseCATToolMetadata(code: string): CATToolMetadata | null {
+  const match = code.match(/\/\/\s*==CATTool==([\s\S]*?)\/\/\s*==\/CATTool==/);
+  if (!match) return null;
+
+  const block = match[1];
+  const lines = block.split("\n");
+
+  let name = "";
+  let description = "";
+  const params: CATToolParam[] = [];
+  const grants: string[] = [];
+  const requires: string[] = [];
+  let timeout: number | undefined;
+
+  for (const line of lines) {
+    const trimmed = line.replace(/^\/\/\s*/, "").trim();
+    if (!trimmed.startsWith("@")) continue;
+
+    const atMatch = trimmed.match(/^@(\w+)\s*(.*)/);
+    if (!atMatch) continue;
+
+    const [, key, value] = atMatch;
+    const val = value.trim();
+
+    switch (key) {
+      case "name":
+        name = val;
+        break;
+      case "description":
+        description = val;
+        break;
+      case "param":
+        {
+          const param = parseParam(val);
+          if (param) params.push(param);
+        }
+        break;
+      case "grant":
+        if (val) grants.push(val);
+        break;
+      case "require":
+        if (val) requires.push(val);
+        break;
+      case "timeout": {
+        const n = Number(val);
+        if (Number.isFinite(n) && n > 0) timeout = n;
+        break;
+      }
+    }
+  }
+
+  if (!name) return null;
+
+  return { name, description, params, grants, requires, ...(timeout !== undefined ? { timeout } : {}) };
+}
+
+// 解析 @param 行: name type [required] description
+// type 支持 string|number|boolean，支持 enum [val1,val2]
+function parseParam(raw: string): CATToolParam | null {
+  // 匹配: paramName type [required] description
+  // 或: paramName type[val1,val2] [required] description
+  const match = raw.match(/^(\w+)\s+(string|number|boolean)(\[[^\]]*\])?\s*(.*)/);
+  if (!match) return null;
+
+  const [, name, type, enumPart, rest] = match;
+
+  let enumValues: string[] | undefined;
+  if (enumPart) {
+    // 解析 [val1,val2]
+    const inner = enumPart.slice(1, -1).trim();
+    if (inner) {
+      enumValues = inner.split(",").map((v) => v.trim());
+    }
+  }
+
+  // rest 可能以 [required] 开头
+  let required = false;
+  let description = rest.trim();
+  if (description.startsWith("[required]")) {
+    required = true;
+    description = description.slice("[required]".length).trim();
+  }
+
+  return {
+    name,
+    type: type as CATToolParam["type"],
+    required,
+    description,
+    ...(enumValues ? { enum: enumValues } : {}),
+  };
+}
+
+// 将 CATTool 元数据转为 ToolDefinition（JSON Schema 格式）
+export function catToolToToolDefinition(metadata: CATToolMetadata): ToolDefinition {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required: string[] = [];
+
+  for (const param of metadata.params) {
+    const prop: Record<string, unknown> = {
+      type: param.type,
+      description: param.description,
+    };
+    if (param.enum) {
+      prop.enum = param.enum;
+    }
+    properties[param.name] = prop;
+    if (param.required) {
+      required.push(param.name);
+    }
+  }
+
+  return {
+    name: metadata.name,
+    description: metadata.description,
+    parameters: {
+      type: "object",
+      properties,
+      ...(required.length > 0 ? { required } : {}),
+    },
+  };
+}
+
+// 给 ToolDefinition 加前缀（用于 Skill 动态注册时避免冲突）
+export function prefixToolDefinition(prefix: string, def: ToolDefinition): ToolDefinition {
+  return { ...def, name: `${prefix}__${def.name}` };
+}
+
+// 获取 CATTool 脚本体（去掉元数据头）
+export function getCATToolBody(code: string): string {
+  return code.replace(/\/\/\s*==CATTool==[\s\S]*?\/\/\s*==\/CATTool==\s*/, "").trim();
+}
diff --git a/src/pkg/utils/script.ts b/src/pkg/utils/script.ts
index 76a5a5600..4f1ba4c57 100644
--- a/src/pkg/utils/script.ts
+++ b/src/pkg/utils/script.ts
@@ -46,8 +46,9 @@ export function parseMetadata(code: string): SCMetadata | null {
 }
 
 // 从网址取得脚本代码
-export async function fetchScriptBody(url: string): Promise<string> {
+export async function fetchScriptBody(url: string, signal?: AbortSignal): Promise<string> {
   const resp = await fetch(url, {
+    signal,
     headers: {
       "Cache-Control": "no-cache",
     },
diff --git a/src/pkg/utils/scriptInstall.ts b/src/pkg/utils/scriptInstall.ts
index 3669b00ca..0f47d9f03 100644
--- a/src/pkg/utils/scriptInstall.ts
+++ b/src/pkg/utils/scriptInstall.ts
@@ -10,6 +10,7 @@ export type ScriptInfo = {
   userSubscribe: boolean;
   metadata: SCMetadata;
   source: InstallSource;
+  cattool?: boolean;
 };
 
 // 供 getInstallInfo 使用
diff --git a/src/pkg/utils/skill.test.ts b/src/pkg/utils/skill.test.ts
new file mode 100644
index 000000000..9c20cd875
--- /dev/null
+++ b/src/pkg/utils/skill.test.ts
@@ -0,0 +1,443 @@
+import { describe, expect, it } from "vitest";
+import JSZip from "jszip";
+import { parseSkillMd, parseSkillZip } from "./skill";
+import { parseCATToolMetadata } from "./cattool";
+
+// 辅助函数：创建测试用 ZIP ArrayBuffer
+async function createTestZip(files: Record<string, string>): Promise<ArrayBuffer> {
+  const zip = new JSZip();
+  for (const [path, content] of Object.entries(files)) {
+    zip.file(path, content);
+  }
+  return zip.generateAsync({ type: "arraybuffer" });
+}
+
+describe("parseSkillMd", () => {
+  it("应正确解析完整的 SKILL.md", () => {
+    const content = `---
+name: web-search
+description: 网络搜索能力
+---
+
+# Web Search Skill
+
+你可以使用搜索工具来查找信息。`;
+
+    const result = parseSkillMd(content);
+    expect(result).not.toBeNull();
+    expect(result!.metadata.name).toBe("web-search");
+    expect(result!.metadata.description).toBe("网络搜索能力");
+    expect(result!.prompt).toBe("# Web Search Skill\n\n你可以使用搜索工具来查找信息。");
+  });
+
+  it("没有 frontmatter 时返回 null", () => {
+    const content = "# Just a markdown file\n\nNo frontmatter here.";
+    expect(parseSkillMd(content)).toBeNull();
+  });
+
+  it("缺少 name 时返回 null", () => {
+    const content = `---
+description: 没有名字
+---
+
+Some prompt content.`;
+    expect(parseSkillMd(content)).toBeNull();
+  });
+
+  it("应正确处理带引号的值", () => {
+    const content = `---
+name: "quoted-name"
+description: 'single quoted'
+---
+
+Prompt text.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.name).toBe("quoted-name");
+    expect(result.metadata.description).toBe("single quoted");
+  });
+
+  it("body 为空时 prompt 应为空字符串", () => {
+    const content = `---
+name: empty-body
+description: test
+---
+`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.prompt).toBe("");
+  });
+
+  it("应忽略未知的 frontmatter 字段", () => {
+    const content = `---
+name: test-skill
+description: test
+version: 1.0.0
+author: someone
+---
+
+Prompt content here.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.name).toBe("test-skill");
+    expect(result.metadata.description).toBe("test");
+  });
+
+  it("仅有 name 时应返回有效结果", () => {
+    const content = `---
+name: minimal
+---
+
+Minimal prompt.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.name).toBe("minimal");
+    expect(result.metadata.description).toBe("");
+    expect(result.prompt).toBe("Minimal prompt.");
+  });
+
+  // ---- config 字段解析测试 ----
+
+  it("应正确解析含 config 的 SKILL.md", () => {
+    const content = `---
+name: weather-query
+description: 查询天气信息
+config:
+  WEATHER_API_KEY:
+    title: "OpenWeatherMap API Key"
+    type: text
+    secret: true
+    required: true
+  DEFAULT_CITY:
+    title: "默认城市"
+    type: text
+    default: "Beijing"
+---
+
+Use weather API to query.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.name).toBe("weather-query");
+    expect(result.metadata.config).toBeDefined();
+    const config = result.metadata.config!;
+    expect(Object.keys(config)).toHaveLength(2);
+
+    expect(config.WEATHER_API_KEY.title).toBe("OpenWeatherMap API Key");
+    expect(config.WEATHER_API_KEY.type).toBe("text");
+    expect(config.WEATHER_API_KEY.secret).toBe(true);
+    expect(config.WEATHER_API_KEY.required).toBe(true);
+
+    expect(config.DEFAULT_CITY.title).toBe("默认城市");
+    expect(config.DEFAULT_CITY.type).toBe("text");
+    expect(config.DEFAULT_CITY.default).toBe("Beijing");
+  });
+
+  it("config 中 type 缺失时默认为 text", () => {
+    const content = `---
+name: test
+config:
+  API_KEY:
+    title: "API Key"
+---
+
+Prompt.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.config!.API_KEY.type).toBe("text");
+  });
+
+  it("应解析 select 类型的 values 字段", () => {
+    const content = `---
+name: test
+config:
+  REGION:
+    title: "Region"
+    type: select
+    values:
+      - us-east-1
+      - eu-west-1
+      - ap-northeast-1
+    default: us-east-1
+---
+
+Prompt.`;
+
+    const result = parseSkillMd(content)!;
+    const field = result.metadata.config!.REGION;
+    expect(field.type).toBe("select");
+    expect(field.values).toEqual(["us-east-1", "eu-west-1", "ap-northeast-1"]);
+    expect(field.default).toBe("us-east-1");
+  });
+
+  it("应解析 switch 和 number 类型", () => {
+    const content = `---
+name: test
+config:
+  ENABLED:
+    title: "Enable feature"
+    type: switch
+    default: true
+  MAX_RESULTS:
+    title: "Max results"
+    type: number
+    default: 10
+---
+
+Prompt.`;
+
+    const result = parseSkillMd(content)!;
+    const config = result.metadata.config!;
+    expect(config.ENABLED.type).toBe("switch");
+    expect(config.ENABLED.default).toBe(true);
+    expect(config.MAX_RESULTS.type).toBe("number");
+    expect(config.MAX_RESULTS.default).toBe(10);
+  });
+
+  it("无 config 时 metadata.config 应为 undefined", () => {
+    const content = `---
+name: no-config
+description: test
+---
+
+Prompt.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.config).toBeUndefined();
+  });
+
+  it("空 config 对象时为 undefined", () => {
+    const content = `---
+name: empty-config
+config: {}
+---
+
+Prompt.`;
+
+    const result = parseSkillMd(content)!;
+    expect(result.metadata.config).toBeUndefined();
+  });
+
+  it("应正确处理多行 prompt 内容", () => {
+    const content = `---
+name: multi-line
+description: test
+---
+
+# Title
+
+Paragraph 1.
+
+## Subtitle
+
+- item 1
+- item 2
+
+\`\`\`js
+console.log("hello");
+\`\`\``;
+
+    const result = parseSkillMd(content)!;
+    expect(result.prompt).toContain("# Title");
+    expect(result.prompt).toContain("- item 1");
+    expect(result.prompt).toContain('console.log("hello");');
+  });
+});
+
+describe("parseSkillZip", () => {
+  const skillMdContent = `---
+name: test-skill
+description: A test skill
+---
+
+Test prompt content.`;
+
+  it("应正确解析包含 SKILL.md + tools + references 的 ZIP", async () => {
+    const zipData = await createTestZip({
+      "SKILL.md": skillMdContent,
+      "scripts/extract.js": "// tool code\nconsole.log('extract');",
+      "scripts/parse.js": "// parse tool",
+      "references/api_docs.md": "# API Docs\nSome docs.",
+      "references/data.txt": "sample data",
+    });
+
+    const result = await parseSkillZip(zipData);
+    expect(result.skillMd).toBe(skillMdContent);
+    expect(result.scripts).toHaveLength(2);
+    expect(result.scripts.map((s) => s.name).sort()).toEqual(["extract.js", "parse.js"]);
+    expect(result.scripts.find((s) => s.name === "extract.js")!.code).toContain("console.log('extract')");
+    expect(result.references).toHaveLength(2);
+    expect(result.references.map((r) => r.name).sort()).toEqual(["api_docs.md", "data.txt"]);
+    expect(result.references.find((r) => r.name === "api_docs.md")!.content).toContain("# API Docs");
+  });
+
+  it("应支持嵌套一层目录结构", async () => {
+    const zipData = await createTestZip({
+      "my-skill/SKILL.md": skillMdContent,
+      "my-skill/scripts/helper.js": "// helper",
+      "my-skill/references/readme.md": "readme content",
+    });
+
+    const result = await parseSkillZip(zipData);
+    expect(result.skillMd).toBe(skillMdContent);
+    expect(result.scripts).toHaveLength(1);
+    expect(result.scripts[0].name).toBe("helper.js");
+    expect(result.references).toHaveLength(1);
+    expect(result.references[0].name).toBe("readme.md");
+  });
+
+  it("缺少 SKILL.md 时应抛错", async () => {
+    const zipData = await createTestZip({
+      "scripts/some.js": "// code",
+      "references/doc.md": "doc",
+    });
+
+    await expect(parseSkillZip(zipData)).rejects.toThrow("SKILL.md");
+  });
+
+  it("tools 和 references 目录为空时应返回空数组", async () => {
+    const zipData = await createTestZip({
+      "SKILL.md": skillMdContent,
+    });
+
+    const result = await parseSkillZip(zipData);
+    expect(result.skillMd).toBe(skillMdContent);
+    expect(result.scripts).toEqual([]);
+    expect(result.references).toEqual([]);
+  });
+
+  it("应忽略非 .js 的 tools 文件", async () => {
+    const zipData = await createTestZip({
+      "SKILL.md": skillMdContent,
+      "scripts/valid.js": "// valid",
+      "scripts/readme.md": "not a tool",
+      "scripts/config.json": "{}",
+    });
+
+    const result = await parseSkillZip(zipData);
+    expect(result.scripts).toHaveLength(1);
+    expect(result.scripts[0].name).toBe("valid.js");
+  });
+
+  it("应忽略子目录中的文件", async () => {
+    const zipData = await createTestZip({
+      "SKILL.md": skillMdContent,
+      "scripts/nested/deep.js": "// nested",
+      "references/sub/file.md": "nested ref",
+    });
+
+    const result = await parseSkillZip(zipData);
+    expect(result.scripts).toEqual([]);
+    expect(result.references).toEqual([]);
+  });
+});
+
+// ---- ZIP → parseSkillMd → installSkill 集成测试 ----
+
+describe("parseSkillZip 端到端集成", () => {
+  const VALID_CATTOOL_CODE = `// ==CATTool==
+// @name taobao_extract
+// @description 提取淘宝页面数据
+// @param pageType string[search_results,product_detail] 页面类型
+// @param tabId number 标签页 ID
+// ==/CATTool==
+const pageType = args.pageType || "auto";
+return { pageType };`;
+
+  it("ZIP 解析结果可直接传给 parseSkillMd 验证", async () => {
+    const skillMd = `---
+name: taobao-helper
+description: 淘宝购物助手
+---
+
+你是一个淘宝购物助手，可以帮用户提取商品信息。`;
+
+    const zipData = await createTestZip({
+      "SKILL.md": skillMd,
+      "scripts/taobao_extract.js": VALID_CATTOOL_CODE,
+      "references/api_docs.md": "# 淘宝 API 文档\n提取接口说明",
+    });
+
+    const zipResult = await parseSkillZip(zipData);
+
+    // 验证 skillMd 可被 parseSkillMd 正确解析
+    const parsed = parseSkillMd(zipResult.skillMd);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.metadata.name).toBe("taobao-helper");
+    expect(parsed!.metadata.description).toBe("淘宝购物助手");
+    expect(parsed!.prompt).toContain("淘宝购物助手");
+  });
+
+  it("ZIP 中的 CATTool 脚本可被 parseCATToolMetadata 正确解析", async () => {
+    const zipData = await createTestZip({
+      "SKILL.md": `---\nname: tool-skill\ndescription: test\n---\nPrompt.`,
+      "scripts/taobao_extract.js": VALID_CATTOOL_CODE,
+    });
+
+    const zipResult = await parseSkillZip(zipData);
+
+    // 验证脚本可被 CATTool 解析器识别
+    expect(zipResult.scripts).toHaveLength(1);
+    const toolMeta = parseCATToolMetadata(zipResult.scripts[0].code);
+    expect(toolMeta).not.toBeNull();
+    expect(toolMeta!.name).toBe("taobao_extract");
+    expect(toolMeta!.description).toBe("提取淘宝页面数据");
+    expect(toolMeta!.params).toHaveLength(2);
+    expect(toolMeta!.params[0].name).toBe("pageType");
+    expect(toolMeta!.params[1].name).toBe("tabId");
+  });
+
+  it("ZIP 解析输出结构与 installSkill 参数签名一致", async () => {
+    const zipData = await createTestZip({
+      "SKILL.md": `---\nname: sig-test\ndescription: Signature test\n---\nPrompt.`,
+      "scripts/helper.js": VALID_CATTOOL_CODE,
+      "references/doc.md": "Doc content",
+    });
+
+    const result = await parseSkillZip(zipData);
+
+    // 验证结构：skillMd 是 string，scripts 是 {name, code}[]，references 是 {name, content}[]
+    expect(typeof result.skillMd).toBe("string");
+    expect(Array.isArray(result.scripts)).toBe(true);
+    expect(Array.isArray(result.references)).toBe(true);
+
+    for (const s of result.scripts) {
+      expect(typeof s.name).toBe("string");
+      expect(typeof s.code).toBe("string");
+      expect(s.name).toBeTruthy();
+      expect(s.code).toBeTruthy();
+    }
+
+    for (const r of result.references) {
+      expect(typeof r.name).toBe("string");
+      expect(typeof r.content).toBe("string");
+      expect(r.name).toBeTruthy();
+      expect(r.content).toBeTruthy();
+    }
+  });
+
+  it("嵌套目录 ZIP 的完整流程：解析 → 验证 SKILL.md → 验证 CATTool", async () => {
+    const zipData = await createTestZip({
+      "taobao-skill/SKILL.md": `---\nname: nested-skill\ndescription: 嵌套目录测试\n---\n嵌套 Skill 提示词。`,
+      "taobao-skill/scripts/extract.js": VALID_CATTOOL_CODE,
+      "taobao-skill/references/guide.txt": "使用指南内容",
+    });
+
+    const zipResult = await parseSkillZip(zipData);
+
+    // Step 1: SKILL.md 正确
+    const parsed = parseSkillMd(zipResult.skillMd);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.metadata.name).toBe("nested-skill");
+
+    // Step 2: CATTool 正确
+    expect(zipResult.scripts).toHaveLength(1);
+    const toolMeta = parseCATToolMetadata(zipResult.scripts[0].code);
+    expect(toolMeta).not.toBeNull();
+    expect(toolMeta!.name).toBe("taobao_extract");
+
+    // Step 3: references 正确
+    expect(zipResult.references).toHaveLength(1);
+    expect(zipResult.references[0].name).toBe("guide.txt");
+    expect(zipResult.references[0].content).toBe("使用指南内容");
+  });
+});
diff --git a/src/pkg/utils/skill.ts b/src/pkg/utils/skill.ts
new file mode 100644
index 000000000..58fb3237d
--- /dev/null
+++ b/src/pkg/utils/skill.ts
@@ -0,0 +1,134 @@
+import type { SkillConfigField, SkillMetadata } from "@App/app/service/agent/types";
+import { parse as parseYaml } from "yaml";
+import { loadAsyncJSZip } from "./jszip-x";
+
+// 校验并规范化单个 config 字段
+function normalizeConfigField(raw: Record<string, unknown>): SkillConfigField {
+  const type = (raw.type as string) || "text";
+  const field: SkillConfigField = {
+    title: String(raw.title || ""),
+    type: type as SkillConfigField["type"],
+  };
+  if (raw.secret === true) field.secret = true;
+  if (raw.required === true) field.required = true;
+  if (raw.default !== undefined) field.default = raw.default;
+  if (Array.isArray(raw.values)) field.values = raw.values.map(String);
+  return field;
+}
+
+// 解析 SKILL.md 内容：YAML frontmatter + markdown body
+export function parseSkillMd(content: string): { metadata: SkillMetadata; prompt: string } | null {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+  if (!match) return null;
+
+  const [, frontmatter, body] = match;
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = parseYaml(frontmatter);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") return null;
+
+  const name = typeof parsed.name === "string" ? parsed.name : "";
+  if (!name) return null;
+
+  const description = typeof parsed.description === "string" ? parsed.description : "";
+
+  // 解析 config 块
+  let config: Record<string, SkillConfigField> | undefined;
+  if (parsed.config && typeof parsed.config === "object" && !Array.isArray(parsed.config)) {
+    const rawConfig = parsed.config as Record<string, unknown>;
+    const entries = Object.entries(rawConfig);
+    if (entries.length > 0) {
+      config = {};
+      for (const [key, value] of entries) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          config[key] = normalizeConfigField(value as Record<string, unknown>);
+        }
+      }
+      // 如果解析后没有有效字段，置为 undefined
+      if (Object.keys(config).length === 0) config = undefined;
+    }
+  }
+
+  return {
+    metadata: { name, description, ...(config ? { config } : {}) },
+    prompt: body.trim(),
+  };
+}
+
+// 解析 Skill ZIP 包：提取 SKILL.md、scripts/*.js、references/*
+export async function parseSkillZip(data: ArrayBuffer): Promise<{
+  skillMd: string;
+  scripts: Array<{ name: string; code: string }>;
+  references: Array<{ name: string; content: string }>;
+}> {
+  const zip = await loadAsyncJSZip(data);
+  const files: Record<string, any> = {};
+  // @ts-ignore JSZip forEach
+  zip.forEach((relativePath: string, file: any) => {
+    files[relativePath] = file;
+  });
+
+  // 查找 SKILL.md：根目录或第一层子目录
+  let skillMdPath = "";
+  let prefix = "";
+  for (const path of Object.keys(files)) {
+    const normalized = path.replace(/\\/g, "/");
+    if (normalized === "SKILL.md" || normalized.endsWith("/SKILL.md")) {
+      const parts = normalized.split("/");
+      if (parts.length === 1) {
+        // 根目录
+        skillMdPath = path;
+        prefix = "";
+        break;
+      } else if (parts.length === 2) {
+        // 一层子目录
+        skillMdPath = path;
+        prefix = parts[0] + "/";
+        break;
+      }
+    }
+  }
+
+  if (!skillMdPath) {
+    throw new Error("ZIP 包中未找到 SKILL.md");
+  }
+
+  const skillMd: string = await files[skillMdPath].async("string");
+
+  // 提取 scripts/*.js
+  const scripts: Array<{ name: string; code: string }> = [];
+  const scriptsDir = prefix + "scripts/";
+  for (const [path, file] of Object.entries(files)) {
+    if ((file as any).dir) continue;
+    const normalized = path.replace(/\\/g, "/");
+    if (normalized.startsWith(scriptsDir) && normalized.endsWith(".js")) {
+      const name = normalized.slice(scriptsDir.length);
+      if (name && !name.includes("/")) {
+        const code: string = await (file as any).async("string");
+        scripts.push({ name, code });
+      }
+    }
+  }
+
+  // 提取 references/*
+  const references: Array<{ name: string; content: string }> = [];
+  const refsDir = prefix + "references/";
+  for (const [path, file] of Object.entries(files)) {
+    if ((file as any).dir) continue;
+    const normalized = path.replace(/\\/g, "/");
+    if (normalized.startsWith(refsDir)) {
+      const name = normalized.slice(refsDir.length);
+      if (name && !name.includes("/")) {
+        const content: string = await (file as any).async("string");
+        references.push({ name, content });
+      }
+    }
+  }
+
+  return { skillMd, scripts, references };
+}
diff --git a/src/pkg/utils/utils.ts b/src/pkg/utils/utils.ts
index 015485240..a165ee1ed 100644
--- a/src/pkg/utils/utils.ts
+++ b/src/pkg/utils/utils.ts
@@ -40,8 +40,8 @@ export const deferred = <T = void>(): Deferred<T> => {
 };
 
 export function isFirefox() {
-  //@ts-ignore
-  return typeof mozInnerScreenX !== "undefined";
+  // @ts-ignore. For both Page & Worker
+  return typeof mozInnerScreenX !== "undefined" || typeof navigator.mozGetUserMedia === "function";
 }
 
 export function valueType(val: unknown) {
@@ -251,17 +251,25 @@ export function getBrowserVersion(): number {
 
 // 判断是否为Edge浏览器
 export function isEdge(): boolean {
-  return navigator.userAgent.includes("Edg/");
+  return (
+    // @ts-ignore; For Extension (Page/Worker), we can check UserSubscriptionState (hidden feature in Edge)
+    typeof chrome.runtime.UserSubscriptionState === "object" ||
+    // Fallback to userAgent check
+    navigator.userAgent.includes("Edg/")
+  );
 }
 
-export enum BrowserType {
-  Edge = 2,
-  Chrome = 1,
-  chromeA = 4, // ~ 120
-  chromeB = 8, // 121 ~ 137
-  chromeC = 16, // 138 ~
-  edgeA = 32, // Edge 144~
-}
+export const BrowserType = {
+  Edge: 2,
+  Chrome: 1,
+  noUserScriptsAPI: 64,
+  guardedByDeveloperMode: 128,
+  guardedByAllowScript: 256,
+  Mouse: 1, // Desktop, Laptop. Tablet ??
+  Touch: 2, // Touchscreen Laptop, Mobile, Tablet
+} as const;
+
+export type BrowserType = ValueOf<typeof BrowserType>;
 
 export function getBrowserType() {
   const o = {
@@ -270,25 +278,40 @@ export function getBrowserType() {
     chrome: 0, // Chrome, Chromium, Brave, Edge
     unknown: 0,
     chromeVersion: 0,
+    device: 0,
   };
   if (isFirefox()) {
+    // Firefox, Zen
     o.firefox = 1;
   } else {
     //@ts-ignore
     const isWebkitBased = typeof webkitIndexedDB === "object";
     if (isWebkitBased) {
+      // Safari, Orion
       o.webkit = 1;
     } else {
-      //@ts-ignore
-      const isChromeBased = typeof webkitRequestAnimationFrame === "function";
+      const isChromeBased =
+        typeof requestAnimationFrame === "function"
+          ? // @ts-ignore. For Page only
+            typeof webkitRequestAnimationFrame === "function"
+          : // @ts-ignore. Available in Worker (Chrome 74+ Edge 79+)
+            typeof BackgroundFetchRecord === "function";
       if (isChromeBased) {
         const isEdgeBrowser = isEdge();
         const chromeVersion = getBrowserVersion();
         o.chrome |= isEdgeBrowser ? BrowserType.Edge : BrowserType.Chrome;
-        o.chrome |= chromeVersion < 120 ? BrowserType.chromeA : 0; // Chrome 120 以下
-        o.chrome |= chromeVersion < 138 ? BrowserType.chromeB : BrowserType.chromeC; // Chrome 121 ~ 137 / 138 以上
-        if (isEdgeBrowser) {
-          o.chrome |= chromeVersion >= 144 ? BrowserType.edgeA : 0; // Edge 144 以上
+        // 由小至大
+        if (chromeVersion < 120) {
+          o.chrome |= BrowserType.noUserScriptsAPI;
+        } else {
+          // 120+
+          if (isEdgeBrowser ? chromeVersion < 144 : chromeVersion < 138) {
+            o.chrome |= BrowserType.guardedByDeveloperMode;
+          } else {
+            // Edge 144+ / Chrome 138+
+            o.chrome |= BrowserType.guardedByAllowScript;
+            // 如日后再变化，在这里再加条件式
+          }
         }
         o.chromeVersion = chromeVersion;
       } else {
@@ -296,9 +319,36 @@ export function getBrowserType() {
       }
     }
   }
+  // BrowserType.Mouse 未能在 Worker 使用
+  o.device |= typeof matchMedia === "function" && !matchMedia("(hover: none)").matches ? BrowserType.Mouse : 0;
+  o.device |= navigator.maxTouchPoints > 0 ? BrowserType.Touch : 0;
   return o;
 }
 
+export const isPermissionOk = async (
+  manifestPermission: chrome.runtime.ManifestOptionalPermissions & chrome.runtime.ManifestPermissions
+): Promise<boolean | null> => {
+  // 兼容 Firefox - 避免因为检查 permission 时，该permission不存在于 optional permission 而报错
+  const manifest = chrome.runtime.getManifest();
+  if (manifest.optional_permissions?.includes(manifestPermission)) {
+    try {
+      return await chrome.permissions.contains({ permissions: [manifestPermission] });
+    } catch {
+      // ignored
+    }
+  } else if (manifest.permissions?.includes(manifestPermission)) {
+    // mainfest 而列明有该permission, 不用检查
+    return true;
+  }
+  return null;
+};
+
+export const getBrowserInstalledVersion = () => {
+  // unique for each browser update.
+  // Usage: Detect whether the browser is upgraded.
+  return btoa([...navigator.userAgent.matchAll(/[\d._]+/g)].map((e) => e[0]).join(";"));
+};
+
 export const makeBlobURL = <T extends { blob: Blob; persistence: boolean }>(
   params: T,
   fallbackFn?: (params: T) => string | Promise<string>
@@ -406,7 +456,8 @@ export function cleanFileName(name: string): string {
 }
 
 export const sourceMapTo = (scriptName: string) => {
-  const url = chrome.runtime.getURL(`/${encodeURI(scriptName)}`);
+  // sandbox 环境中 chrome.runtime 不可用，使用脚本名作为 sourceURL
+  const url = chrome.runtime?.getURL ? chrome.runtime.getURL(`/${encodeURI(scriptName)}`) : encodeURI(scriptName);
   return `\n//# sourceURL=${url}`;
 };
 
@@ -474,7 +525,7 @@ export const normalizeResponseHeaders = (headersString: string) => {
 // 遵循 ISO 8601, 一月四日为Week 1，星期一为新一周
 // 能应对每年开始和结束（不会因为踏入新一年而重新计算）
 // 见 https://wikipedia.org/wiki/ISO_week_date
-// 中文說明 https://juejin.cn/post/6921245139855736846
+// 中文说明 https://juejin.cn/post/6921245139855736846
 export const getISOWeek = (date: Date): number => {
   // 使用传入日期的年月日创建 UTC 日期对象，忽略本地时间部分，避免时区影响
   const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
diff --git a/src/types/scriptcat.d.ts b/src/types/scriptcat.d.ts
index d03005163..4da4c6638 100644
--- a/src/types/scriptcat.d.ts
+++ b/src/types/scriptcat.d.ts
@@ -6,134 +6,147 @@ declare type ConfigType = "text" | "checkbox" | "select" | "mult-select" | "numb
 
 declare interface Config {
   [key: string]: unknown;
+  /** Config item title. */
   title: string;
+  /** Config item description. */
   description: string;
+  /** Default value. */
   default?: unknown;
+  /** UI widget type. */
   type?: ConfigType;
+  /** Binding key for two-way data flow. */
   bind?: string;
+  /** Allowed values (for select/multi-select). */
   values?: unknown[];
+  /** Whether to mask input (password field). */
   password?: boolean;
-  // 文本类型时是字符串长度,数字类型时是最大值
+  /** Max string length (for text) or max numeric value (for number). */
   max?: number;
+  /** Min numeric value. */
   min?: number;
-  rows?: number; // textarea行数
-  index: number; // 配置项排序位置
+  /** Number of rows (for textarea). */
+  rows?: number;
+  /** Sort index among config items. */
+  index: number;
 }
 
 declare type UserConfig = { [key: string]: { [key: string]: Config } };
 
+/** Script and environment metadata, compatible with Tampermonkey's `GM_info`. */
 declare const GM_info: {
+  /** ScriptCat version string. */
   version: string;
+  /** Whether auto-update is enabled for this script. */
   scriptWillUpdate: boolean;
+  /** Always `"ScriptCat"`. */
   scriptHandler: "ScriptCat";
   scriptUpdateURL?: string;
-  // scriptSource: string;
   scriptMetaStr?: string;
   userConfig?: UserConfig;
   userConfigStr?: string;
+  /** Whether running in an incognito/private window. */
   isIncognito: boolean;
-  sandboxMode: "raw"; // "js" | "raw" | "none";
+  /** Sandbox mode (ScriptCat always uses `"raw"`). */
+  sandboxMode: "raw";
   userAgentData: {
-    brands?: {
-      brand: string;
-      version: string;
-    }[];
+    brands?: { brand: string; version: string }[];
     mobile?: boolean;
     platform?: string;
     architecture?: string;
     bitness?: string;
   };
-  downloadMode: "native"; // "native" | "disabled" | "browser";
+  /** Download mode (ScriptCat uses `"native"`). */
+  downloadMode: "native";
+  /** Metadata parsed from the script header. */
   script: {
     author?: string;
     description?: string;
-    // excludes: string[];
     grant: string[];
     header: string;
-    // homepage?: string;
     icon?: string;
     icon64?: string;
     includes?: string[];
-    // lastModified: number;
     matches: string[];
     name: string;
     namespace?: string;
-    // position: number;
     "run-at": string;
     "run-in": string[];
-    // resources: string[];
-    // unwrap: boolean;
     version: string;
-    /* options: {
-      awareOfChrome: boolean;
-      run_at: string;
-      noframes?: boolean;
-      compat_arrayLeft: boolean;
-      compat_foreach: boolean;
-      compat_forvarin: boolean;
-      compat_metadata: boolean;
-      compat_uW_gmonkey: boolean;
-      override: {
-        orig_excludes: string[];
-        orig_includes: string[];
-        use_includes: string[];
-        use_excludes: string[];
-        [key: string]: any;
-      };
-      [key: string]: any;
-    }; */
     [key: string]: unknown;
   };
   [key: string]: unknown;
 };
 
+// ===========================================================================
+// GM_* functions (Greasemonkey/Tampermonkey compatible, synchronous style)
+// ===========================================================================
+
+/** List all stored value keys. */
 declare function GM_listValues(): string[];
 
+/** Listen for changes to a stored value. Returns a listener ID. */
 declare function GM_addValueChangeListener(name: string, listener: GMTypes.ValueChangeListener): number;
 
+/** Remove a value change listener by ID. */
 declare function GM_removeValueChangeListener(listenerId: number): void;
 
+/** Store a value. */
 declare function GM_setValue(name: string, value: any): void;
-// 设置多个值, values是一个对象, 键为值的名称, 值为值的内容
+
+/** Store multiple values at once. Keys are value names. */
 declare function GM_setValues(values: { [key: string]: any }): void;
 
+/** Retrieve a stored value (returns `defaultValue` if not found). */
 declare function GM_getValue(name: string, defaultValue?: any): any;
 
-// 获取多个值, 如果keysOrDefaults是一个对象, 则使用对象的值作为默认值
+/**
+ * Retrieve multiple values. If `keysOrDefaults` is an object, its values are used as defaults.
+ * If it is an array, each element is a key name (no defaults).
+ */
 declare function GM_getValues(keysOrDefaults: { [key: string]: any } | string[] | null | undefined): {
   [key: string]: any;
 };
 
+/** Delete a stored value. */
 declare function GM_deleteValue(name: string): void;
 
-// 删除多个值, names是一个字符串数组
+/** Delete multiple stored values. */
 declare function GM_deleteValues(names: string[]): void;
 
-// 支持level和label
-declare function GM_log(message: string, level?: GMTypes.LoggerLevel, labels?: GMTypes.LoggerLabel): void;
+/** Log a message with optional level and structured labels. */
+declare function GM_log(message: string, level?: GMTypes.LoggerLevel, ...labels: GMTypes.LoggerLabel[]): void;
 
+/** Get the text content of a `@resource` by name. */
 declare function GM_getResourceText(name: string): string | undefined;
 
+/** Get a URL (data: or blob:) for a `@resource` by name. */
 declare function GM_getResourceURL(name: string, isBlobUrl?: boolean): string | undefined;
 
-function GM_registerMenuCommand(
+/** Register a menu command in the ScriptCat popup. */
+declare function GM_registerMenuCommand(
   name: string,
   listener?: (inputValue?: any) => void,
   options_or_accessKey?:
     | {
         id?: number | string;
-        accessKey?: string; // 菜单快捷键
-        autoClose?: boolean; // 默认为 true，false 时点击后不关闭弹出菜单页面
-        nested?: boolean; // SC特有配置，默认为 true，false 的话浏览器右键菜单项目由三级菜单升至二级菜单
-        individual?: boolean; // SC特有配置，默认为 false，true 表示相同的菜单项不合并显示
+        /** Keyboard shortcut key. */
+        accessKey?: string;
+        /** Whether clicking the menu closes the popup (default: true). */
+        autoClose?: boolean;
+        /** SC extension: nest under a parent menu (default: true). `false` promotes to browser context menu. */
+        nested?: boolean;
+        /** SC extension: do not merge identical menu items (default: false). */
+        individual?: boolean;
       }
     | string
 ): number;
 
+/** Unregister a menu command by ID. */
 declare function GM_unregisterMenuCommand(id: number): void;
 
 /**
- * 注册一个菜单输入框, 允许用户输入值, 并在输入完成后用回调函数
+ * Register a menu item with an input field, allowing the user to enter a value.
+ * The callback receives the user's input.
  */
 declare function CAT_registerMenuInput(
   name: string,
@@ -141,42 +154,64 @@ declare function CAT_registerMenuInput(
   options_or_accessKey?:
     | {
         id?: number | string;
-        accessKey?: string; // 菜单快捷键
-        autoClose?: boolean; // 默认为 true，false 时点击后不关闭弹出菜单页面
-        nested?: boolean; // SC特有配置，默认为 true，false 的话浏览器右键菜单项目由三级菜单升至二级菜单
-        individual?: boolean; // SC特有配置，默认为 false，true 表示相同的菜单项不合并显示
-        // 可选输入框
+        accessKey?: string;
+        autoClose?: boolean;
+        nested?: boolean;
+        individual?: boolean;
+        /** Input widget type. */
         inputType?: "text" | "number" | "boolean";
-        title?: string; // title 只适用于输入框类型
+        /** Dialog title (for the input popup). */
+        title?: string;
+        /** Label shown next to the input. */
         inputLabel?: string;
+        /** Default value for the input. */
         inputDefaultValue?: string | number | boolean;
+        /** Placeholder text. */
         inputPlaceholder?: string;
       }
     | string
 ): number;
 
+/** Unregister a menu input (alias of `GM_unregisterMenuCommand`). */
 declare const CAT_unregisterMenuInput: typeof GM_unregisterMenuCommand;
 
-/**
- * 当使用 @early-start 时，可以使用此函数来等待脚本完全加载完成
- */
+/** Wait for the script to be fully loaded. Used with `@early-start`. */
 declare function CAT_scriptLoaded(): Promise<void>;
 
+/** Create a blob URL from a Blob object. ScriptCat manages the URL lifecycle. */
+declare function CAT_createBlobUrl(blob: Blob): Promise<string>;
+
+/** Fetch a blob URL and return the Blob data. Helper for `GM_xmlhttpRequest` stream responses. */
+declare function CAT_fetchBlob(url: string): Promise<Blob>;
+
+/** Fetch a URL and parse it as a Document (in the content page context if available). */
+declare function CAT_fetchDocument(url: string): Promise<Document | undefined>;
+
+/** Open a URL in a new tab. Returns a Tab handle (or `undefined` if context is invalid). */
 declare function GM_openInTab(url: string, options: GMTypes.OpenTabOptions): GMTypes.Tab | undefined;
 declare function GM_openInTab(url: string, loadInBackground: boolean): GMTypes.Tab | undefined;
 declare function GM_openInTab(url: string): GMTypes.Tab | undefined;
 
+/** Close a tab opened by `GM_openInTab`. */
+declare function GM_closeInTab(tabId: string): void;
+
+/** Perform a cross-origin XMLHttpRequest. Requires `@connect` for the target domain. */
 declare function GM_xmlhttpRequest(details: GMTypes.XHRDetails): GMTypes.AbortHandle<void>;
 
+/** Download a file. */
 declare function GM_download(details: GMTypes.DownloadDetails<string | Blob | File>): GMTypes.AbortHandle<boolean>;
 declare function GM_download(url: string, filename: string): GMTypes.AbortHandle<boolean>;
 
+/** Get the tab's persistent storage object. */
 declare function GM_getTab(callback: (tab: object) => void): void;
 
-declare function GM_saveTab(tab: object): Promise<void>;
+/** Save the tab's persistent storage object. */
+declare function GM_saveTab(tab: object): void;
 
+/** Get all tabs' persistent storage objects. */
 declare function GM_getTabs(callback: (tabs: { [key: number]: object }) => void): void;
 
+/** Show a desktop notification. */
 declare function GM_notification(details: GMTypes.NotificationDetails, ondone?: GMTypes.NotificationOnDone): void;
 declare function GM_notification(
   text: string,
@@ -185,12 +220,16 @@ declare function GM_notification(
   onclick?: GMTypes.NotificationOnClick
 ): void;
 
+/** Close a notification by ID. */
 declare function GM_closeNotification(id: string): void;
 
+/** Update a notification by ID. */
 declare function GM_updateNotification(id: string, details: GMTypes.NotificationDetails): void;
 
+/** Copy text to the clipboard. */
 declare function GM_setClipboard(data: string, info?: string | { type?: string; mimetype?: string }): void;
 
+/** Add a DOM element to the page. */
 declare function GM_addElement(tag: string, attributes: Record<string, string | number | boolean>): HTMLElement;
 declare function GM_addElement(
   parentNode: Node,
@@ -198,149 +237,173 @@ declare function GM_addElement(
   attrs: Record<string, string | number | boolean>
 ): HTMLElement;
 
-declare function GM_addStyle(css: string): HTMLStyleElement;
+/** Inject a CSS stylesheet into the page. */
+declare function GM_addStyle(css: string): Element | undefined;
 
-// name和domain不能都为空
+/**
+ * Perform cookie operations. Both `name` and `domain` cannot be empty simultaneously.
+ * @param action - `"list"` | `"set"` | `"delete"`
+ */
 declare function GM_cookie(
   action: GMTypes.CookieAction,
   details: GMTypes.CookieDetails,
   ondone: (cookie: GMTypes.Cookie[], error: unknown | undefined) => void
 ): void;
 
-/**
- * GM.* API (兼容 Greasemonkey4/Tampermonkey 4+ 的 Promise 风格)
- */
+// ===========================================================================
+// GM.* object (Greasemonkey 4 / Tampermonkey 4+ Promise-style API)
+// ===========================================================================
+
+/** Promise-based API object. Each method corresponds to a `GM_*` function. */
 declare const GM: {
-  /** 脚本信息 */
+  /** Script and environment metadata (same as `GM_info`). */
   readonly info: typeof GM_info;
 
-  /** 获取一个值 */
+  /** Retrieve a stored value. */
   getValue<T = any>(name: string, defaultValue?: T): Promise<T>;
 
-  /** 获取多个值, 如果keysOrDefaults是一个对象, 则使用对象的值作为默认值 */
+  /** Retrieve multiple stored values. If `keysOrDefaults` is an object, values are used as defaults. */
   getValues(keysOrDefaults: { [key: string]: any } | string[] | null | undefined): Promise<{ [key: string]: any }>;
 
-  /** 设置一个值 */
+  /** Store a value. */
   setValue(name: string, value: any): Promise<void>;
 
-  /** 设置多个值, values是一个对象, 键为值的名称, 值为值的内容 */
+  /** Store multiple values at once. */
   setValues(values: { [key: string]: any }): Promise<void>;
 
-  /** 删除一个值 */
+  /** Delete a stored value. */
   deleteValue(name: string): Promise<void>;
 
-  /** 删除多个值, names是一个字符串数组 */
+  /** Delete multiple stored values. */
   deleteValues(names: string[]): Promise<void>;
 
-  /** 获取所有已保存值的 key 列表 */
+  /** List all stored value keys. */
   listValues(): Promise<string[]>;
 
-  /** 值变更监听 */
+  /** Listen for changes to a stored value. */
   addValueChangeListener(name: string, listener: GMTypes.ValueChangeListener): Promise<number>;
+  /** Remove a value change listener. */
   removeValueChangeListener(listenerId: number): Promise<void>;
 
-  /** 支持level和label */
-  log(message: string, level?: GMTypes.LoggerLevel, labels?: GMTypes.LoggerLabel): Promise<void>;
+  /** Log a message with optional level and structured labels. */
+  log(message: string, level?: GMTypes.LoggerLevel, ...labels: GMTypes.LoggerLabel[]): Promise<void>;
 
-  /** 获取资源文本 */
+  /** Get the text content of a `@resource`. */
   getResourceText(name: string): Promise<string | undefined>;
 
-  /** 获取资源URL */
+  /** Get a URL for a `@resource`. */
   getResourceURL(name: string, isBlobUrl?: boolean): Promise<string | undefined>;
 
-  /** 注册菜单 */
+  /** Register a menu command. */
   registerMenuCommand(
     name: string,
     listener?: (inputValue?: any) => void,
     options_or_accessKey?:
       | {
           id?: number | string;
-          accessKey?: string; // 菜单快捷键
-          autoClose?: boolean; // 默认为 true
-          title?: string; // 菜单提示
-          // ScriptCat 扩展
-          icon?: string; // 菜单图标
-          // ScriptCat 扩展
-          closeOnClick?: boolean; // 点击菜单后是否关闭, 与autoClose含义相同
+          accessKey?: string;
+          autoClose?: boolean;
+          title?: string;
+          /** SC extension: menu icon URL. */
+          icon?: string;
+          /** SC extension: alias for `autoClose`. */
+          closeOnClick?: boolean;
         }
       | string
   ): Promise<number | string | undefined>;
 
-  /** 注销菜单 */
+  /** Unregister a menu command. */
   unregisterMenuCommand(id: number | string): Promise<void>;
 
-  /** 样式注入 */
-  addStyle(css: string): Promise<HTMLStyleElement>;
+  /** Inject a CSS stylesheet. */
+  addStyle(css: string): Promise<Element | undefined>;
 
-  /** 通知 */
+  /** Show a desktop notification. */
   notification(details: GMTypes.NotificationDetails, ondone?: GMTypes.NotificationOnDone): Promise<void>;
   notification(text: string, title: string, image: string, onclick?: GMTypes.NotificationOnClick): Promise<void>;
+  /** Close a notification. */
   closeNotification(id: string): Promise<void>;
+  /** Update a notification. */
   updateNotification(id: string, details: GMTypes.NotificationDetails): Promise<void>;
 
-  /** 设置剪贴板 */
+  /** Copy text to the clipboard. */
   setClipboard(data: string, info?: string | { type?: string; mimetype?: string }): Promise<void>;
 
-  /** 添加元素 */
+  /** Add a DOM element. */
   addElement(tag: string, attributes: Record<string, string | number | boolean>): Promise<HTMLElement>;
   addElement(parentNode: Node, tag: string, attrs: Record<string, string | number | boolean>): Promise<HTMLElement>;
 
-  /** XMLHttpRequest */
-  xmlHttpRequest(details: GMTypes.XHRDetails): Promise<GMTypes.XHRResponse>;
+  /** Perform a cross-origin XMLHttpRequest. The returned Promise also has an `.abort()` method. */
+  xmlHttpRequest(details: GMTypes.XHRDetails): Promise<GMTypes.XHRResponse> & GMTypes.AbortHandle<void>;
 
-  /** 下载 */
+  /** Download a file. */
   download(details: GMTypes.DownloadDetails<string | Blob | File>): Promise<boolean>;
   download(url: string, filename: string): Promise<boolean>;
 
-  /** Tab 存储 */
+  /** Get the tab's persistent storage object. */
   getTab(): Promise<object>;
+  /** Save the tab's persistent storage object. */
   saveTab(tab: object): Promise<void>;
+  /** Get all tabs' persistent storage objects. */
   getTabs(): Promise<{ [key: number]: object }>;
 
-  /** 打开新标签页 */
+  /** Open a URL in a new tab. */
   openInTab(url: string, options: GMTypes.OpenTabOptions): Promise<GMTypes.Tab | undefined>;
   openInTab(url: string, loadInBackground: boolean): Promise<GMTypes.Tab | undefined>;
   openInTab(url: string): Promise<GMTypes.Tab | undefined>;
 
-  /** Cookie 操作 */
-  cookie(action: GMTypes.CookieAction, details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+  /** Close a tab opened by `openInTab`. */
+  closeInTab(tabId: string): Promise<void>;
+
+  /** Cookie operations with sub-methods. */
+  cookie: {
+    (action: GMTypes.CookieAction, details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+    /** Set a cookie. */
+    set(details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+    /** List cookies matching the filter. */
+    list(details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+    /** Delete a cookie. */
+    delete(details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+  };
 };
 
+// ===========================================================================
+// CAT_* functions (ScriptCat-specific extensions)
+// ===========================================================================
+
 /**
- * 设置浏览器代理
- * @deprecated 正式版中已废弃,后续可能会在beta版本中添加
+ * Set browser proxy rules.
+ * @deprecated Removed in stable release; may return in beta.
  */
 declare function CAT_setProxy(rule: CATType.ProxyRule[] | string): void;
 
 /**
- * 清理所有代理规则
- * @deprecated 正式版中已废弃,后续可能会在beta版本中添加
+ * Clear all proxy rules.
+ * @deprecated Removed in stable release; may return in beta.
  */
 declare function CAT_clearProxy(): void;
 
 /**
- * 输入x、y,模拟真实点击
- * @deprecated 正式版中已废弃,后续可能会在beta版本中添加
+ * Simulate a real click at coordinates (x, y).
+ * @deprecated Removed in stable release; may return in beta.
  */
 declare function CAT_click(x: number, y: number): void;
 
-/**
- * 打开脚本的用户配置页面
- */
+/** Open the script's user configuration page. */
 declare function CAT_userConfig(): void;
 
 /**
- * 操控管理器设置的储存系统,将会在目录下创建一个app/uuid目录供此 API 使用,如果指定了baseDir参数,则会使用baseDir作为基础目录
- * 上传时默认覆盖同名文件
- * @param action 操作类型 list 列出指定目录所有文件, upload 上传文件, download 下载文件, delete 删除文件, config 打开配置页, 暂时不提供move/mkdir等操作
- * @param details
+ * Interact with the managed file storage system.
+ * Creates an `app/<uuid>` directory for this script (or uses `baseDir`).
+ * Upload overwrites files with the same name.
+ * @param action - `"list"` | `"upload"` | `"download"` | `"delete"` | `"config"`
  */
 declare function CAT_fileStorage(
   action: "list",
   details: {
-    // 文件路径
+    /** Directory path to list. */
     path?: string;
-    // 基础目录,如果未设置,则将脚本uuid作为目录
+    /** Base directory; defaults to the script's UUID. */
     baseDir?: string;
     onload?: (files: CATType.FileStorageFileInfo[]) => void;
     onerror?: (error: CATType.FileStorageError) => void;
@@ -349,58 +412,52 @@ declare function CAT_fileStorage(
 declare function CAT_fileStorage(
   action: "download",
   details: {
-    file: CATType.FileStorageFileInfo; // 某些平台需要提供文件的hash值,所以需要传入文件信息
+    /** File info object (some platforms need the file hash). */
+    file: CATType.FileStorageFileInfo;
     onload: (data: Blob) => void;
-    // onprogress?: (progress: number) => void;
     onerror?: (error: CATType.FileStorageError) => void;
-    // public?: boolean;
   }
 ): void;
 declare function CAT_fileStorage(
   action: "delete",
   details: {
+    /** File path to delete. */
     path: string;
     onload?: () => void;
     onerror?: (error: CATType.FileStorageError) => void;
-    // public?: boolean;
   }
 ): void;
 declare function CAT_fileStorage(
   action: "upload",
   details: {
+    /** Destination file path. */
     path: string;
-    // 基础目录,如果未设置,则将脚本uuid作为目录
+    /** Base directory; defaults to the script's UUID. */
     baseDir?: string;
+    /** File data to upload. */
     data: Blob;
     onload?: () => void;
-    // onprogress?: (progress: number) => void;
     onerror?: (error: CATType.FileStorageError) => void;
-    // public?: boolean;
   }
 ): void;
+/** Open the file storage configuration page. */
 declare function CAT_fileStorage(action: "config"): void;
 
 /**
- * 脚本猫后台脚本重试, 当你的脚本出现错误时, 可以reject返回此错误, 以便脚本猫重试
- * 重试时间请注意不要与脚本执行时间冲突, 否则可能会导致重复执行, 最小重试时间为5s
- * @class CATRetryError
+ * Retry error for background scripts. Throw this to make ScriptCat retry later.
+ * Minimum retry interval is 5 seconds. Avoid overlapping with the script's own schedule.
  */
 declare class CATRetryError {
-  /**
-   * constructor 构造函数
-   * @param {string} message 错误信息
-   * @param {number} seconds x秒后重试, 单位秒
-   */
+  /** @param message - Error message. @param seconds - Retry after N seconds. */
   constructor(message: string, seconds: number);
-
-  /**
-   * constructor 构造函数
-   * @param {string} message 错误信息
-   * @param {Date} date 重试时间, 指定时间后重试
-   */
+  /** @param message - Error message. @param date - Retry at a specific time. */
   constructor(message: string, date: Date);
 }
 
+// ===========================================================================
+// CATType namespace (ScriptCat-specific types)
+// ===========================================================================
+
 declare namespace CATType {
   interface ProxyRule {
     proxyServer: ProxyServer;
@@ -416,26 +473,30 @@ declare namespace CATType {
   }
 
   interface FileStorageError {
-    // 错误码 -1 未知错误 1 用户未配置文件储存源 2 文件储存源配置错误 3 路径不存在
-    // 4 上传失败 5 下载失败 6 删除失败 7 不允许的文件路径 8 网络类型的错误
+    /**
+     * Error code:
+     * -1 = unknown, 1 = storage not configured, 2 = config error, 3 = path not found,
+     * 4 = upload failed, 5 = download failed, 6 = delete failed,
+     * 7 = disallowed file path, 8 = network error
+     */
     code: -1 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
     error: string;
   }
 
   interface FileStorageFileInfo {
-    // 文件名
+    /** File name. */
     name: string;
-    // 文件路径
+    /** Relative file path. */
     path: string;
-    // 储存空间绝对路径
+    /** Absolute path in the storage space. */
     absPath: string;
-    // 文件大小
+    /** File size in bytes. */
     size: number;
-    // 文件摘要
+    /** File content digest/hash. */
     digest: string;
-    // 文件创建时间
+    /** Creation timestamp. */
     createtime: number;
-    // 文件修改时间
+    /** Last modification timestamp. */
     updatetime: number;
   }
 
@@ -448,6 +509,10 @@ declare namespace CATType {
   };
 }
 
+// ===========================================================================
+// GMTypes namespace (Greasemonkey/Tampermonkey compatible types)
+// ===========================================================================
+
 declare namespace GMTypes {
   type CookieAction = "list" | "delete" | "set";
 
@@ -487,7 +552,7 @@ declare namespace GMTypes {
     sameSite: "unspecified" | "no_restriction" | "lax" | "strict";
   }
 
-  // tabid是只有后台脚本监听才有的参数
+  /** Value change listener. `tabid` is only available for background script listeners. */
   type ValueChangeListener = (
     name: string,
     oldValue: unknown,
@@ -498,81 +563,55 @@ declare namespace GMTypes {
 
   interface OpenTabOptions {
     /**
-     * 决定新标签页是否在打开时获得焦点。
-     *
-     * - `true` → 新标签页会立即切换到前台。
-     * - `false` → 新标签页在后台打开，不会打断当前页面的焦点。
-     *
-     * 默认值：true
+     * Whether the new tab gains focus immediately.
+     * - `true` — tab opens in foreground.
+     * - `false` — tab opens in background.
+     * @default true
      */
     active?: boolean;
 
     /**
-     * 决定新标签页插入位置。
-     *
-     * - 如果是 `boolean`：
-     *   - `true` → 插入在当前标签页之后。
-     *   - `false` → 插入到窗口末尾。
-     * - 如果是 `number`：
-     *   - `0` → 插入到当前标签前一格。
-     *   - `1` → 插入到当前标签后一格。
-     *
-     * 默认值：true
+     * Tab insertion position.
+     * - `true` / `1` — insert after the current tab.
+     * - `false` — append to the end of the window.
+     * - `0` — insert before the current tab.
+     * @default true
      */
     insert?: boolean | number;
 
     /**
-     * 决定是否设置父标签页（即 `openerTabId`）。
-     *
-     * - `true` → 浏览器能追踪由哪个标签打开的子标签，
-     *   有助于某些扩展（如标签树管理器）识别父子关系。
-     *
-     * 默认值：true
+     * Set the opener tab ID so browsers can track parent-child relationships.
+     * @default true
      */
     setParent?: boolean;
 
     /**
-     * 是否在隐私窗口（无痕模式）中打开标签页。
-     *
-     * 注意：ScriptCat 的 manifest.json 配置了 `"incognito": "split"`，
-     * 在 normal window 中执行时，tabId/windowId 将不可用，
-     * 只能执行「打开新标签页」动作。
-     *
-     * 默认值：false
+     * Open in an incognito/private window.
+     * Note: ScriptCat uses `"incognito": "split"` — in a normal window,
+     * tabId/windowId will not be available.
+     * @default false
      */
     incognito?: boolean;
 
     /**
-     * 历史兼容字段，仅 TM 支持。
-     * 语义与 `active` **相反**：
-     *
-     * - `true` → 等价于 `active = false`（后台加载）。
-     * - `false` → 等价于 `active = true`（前台加载）。
-     *
-     * ⚠️ 不推荐使用：与 `active` 功能重复且容易混淆。
-     *
-     * 默认值：false
-     * @deprecated 请使用 `active` 替代
+     * Legacy field (TM only). Semantics are the **opposite** of `active`:
+     * `true` = background, `false` = foreground.
+     * @default false
+     * @deprecated Use `active` instead.
      */
     loadInBackground?: boolean;
 
     /**
-     * 是否将新标签页固定（pin）在浏览器标签栏左侧。
-     *
-     * - `true` → 新标签页为固定状态。
-     * - `false` → 普通标签页。
-     *
-     * 默认值：false
+     * Pin the new tab in the browser tab bar.
+     * @default false
      */
     pinned?: boolean;
 
     /**
-     * 使用 `window.open` 打开新标签，而不是 `chrome.tabs.create`
-     * 在打开一些特殊协议的链接时很有用，例如 `vscode://`, `m3u8dl://`
-     * 其他参数在这个打开方式下无效
-     *
-     * 相关：Issue #178 #1043
-     * 默认值：false
+     * Use `window.open` instead of `chrome.tabs.create`.
+     * Useful for special protocols like `vscode://`, `m3u8dl://`.
+     * Other options are ignored in this mode.
+     * @default false
      */
     useOpen?: boolean;
   }
@@ -580,7 +619,7 @@ declare namespace GMTypes {
   type SWOpenTabOptions = OpenTabOptions & Required<Pick<OpenTabOptions, "active">>;
 
   /**
-   * XMLHttpRequest readyState 状态值
+   * XMLHttpRequest readyState values.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/readyState
    */
   type ReadyState =
@@ -625,20 +664,25 @@ declare namespace GMTypes {
     binary?: boolean;
     timeout?: number;
     context?: ContextType;
-    responseType?: "text" | "arraybuffer" | "blob" | "json" | "document" | "stream"; // stream 在当前版本是一个较为简陋的实现
+    /** Response type. `"stream"` support is rudimentary in the current version. */
+    responseType?: "text" | "arraybuffer" | "blob" | "json" | "document" | "stream";
     overrideMimeType?: string;
+    /** Send request without cookies (Tampermonkey compatible). */
     anonymous?: boolean;
-    mozAnon?: boolean; // 发送请求时不携带cookie (兼容Greasemonkey)
+    /** Send request without cookies (Greasemonkey compatible). */
+    mozAnon?: boolean;
+    /** Force using the Fetch API internally. */
     fetch?: boolean;
     user?: string;
     password?: string;
+    /** Disable caching. */
     nocache?: boolean;
-    revalidate?: boolean; // 强制重新验证缓存内容：允许缓存，但必须在使用缓存内容之前重新验证
-    redirect?: "follow" | "error" | "manual"; // 为了与tm保持一致, 在v0.17.0后废弃maxRedirects, 使用redirect替代, 会强制使用fetch模式
-    cookiePartition?: Record<string, any> & {
-      topLevelSite?: string; // 表示分区 cookie 的顶部帧站点
-    }; // 包含用于发送和接收的分区 cookie 的分区键 https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#storage_partitioning
-    context?: any; // 自定义值，传递给响应的 response.context 属性
+    /** Force revalidation: allow cache but revalidate before using. */
+    revalidate?: boolean;
+    /** Redirect handling. Forces fetch mode internally. */
+    redirect?: "follow" | "error" | "manual";
+    /** Partitioned cookie key for storage partitioning. */
+    cookiePartition?: Record<string, any> & { topLevelSite?: string };
 
     onload?: Listener<XHRResponse>;
     onloadstart?: Listener<XHRResponse>;
@@ -660,25 +704,26 @@ declare namespace GMTypes {
   }
 
   interface DownloadDetails<URL> {
-    // TM/SC 标准参数
+    // Standard parameters (TM/SC)
     url: URL;
     name: string;
     headers?: { [key: string]: string };
     saveAs?: boolean;
     conflictAction?: "uniquify" | "overwrite" | "prompt";
 
-    // 其他参数
-    timeout?: number; // SC/VM
-    anonymous?: boolean; // SC/VM
-    context?: ContextType; // SC/VM
-    user?: string; // SC/VM
-    password?: string; // SC/VM
+    // Extended parameters (SC/VM)
+    timeout?: number;
+    anonymous?: boolean;
+    context?: ContextType;
+    user?: string;
+    password?: string;
 
-    method?: "GET" | "POST"; // SC
-    downloadMode?: "native" | "browser"; // SC
-    cookie?: string; // SC
+    // SC-only parameters
+    method?: "GET" | "POST";
+    downloadMode?: "native" | "browser";
+    cookie?: string;
 
-    // TM/SC 标准回调
+    // Callbacks
     onload?: Listener<object>;
     onerror?: Listener<DownloadError>;
     onprogress?: Listener<{
@@ -733,7 +778,7 @@ declare namespace GMTypes {
     ondone?: NotificationOnDone;
     progress?: number;
     oncreate?: NotificationOnClick;
-    // 只能存在2个
+    /** Max 2 buttons. */
     buttons?: NotificationButton[];
   }
 
@@ -746,3 +791,729 @@ declare namespace GMTypes {
 
   type GMClipboardInfo = string | { type?: string; mimetype?: string };
 }
+
+// ===========================================================================
+// CAT.agent — ScriptCat Agent API
+// @grant CAT.agent.conversation / CAT.agent.tools / CAT.agent.dom /
+//        CAT.agent.task / CAT.agent.skills
+// ===========================================================================
+
+/** CAT Agent conversation, content blocks, and streaming types. */
+declare namespace CATAgent {
+  // ---- Content Block types ----
+
+  /** Plain text content block. */
+  type TextBlock = { type: "text"; text: string };
+
+  /** Image content block. Data is stored in OPFS and referenced by `attachmentId`. */
+  type ImageBlock = { type: "image"; attachmentId: string; mimeType: string; name?: string };
+
+  /** File content block. */
+  type FileBlock = { type: "file"; attachmentId: string; mimeType: string; name: string; size?: number };
+
+  /** Audio content block. */
+  type AudioBlock = {
+    type: "audio";
+    attachmentId: string;
+    mimeType: string;
+    name?: string;
+    /** Duration in milliseconds. */
+    durationMs?: number;
+  };
+
+  /** Union of all content block types. */
+  type ContentBlock = TextBlock | ImageBlock | FileBlock | AudioBlock;
+
+  /** Message content: plain string or an array of content blocks (multimodal). */
+  type MessageContent = string | ContentBlock[];
+
+  // ---- Tool types ----
+
+  /**
+   * Tool definition with an inline handler function.
+   * Use in `ConversationCreateOptions.tools` or `ChatOptions.tools`
+   * to register tools that the LLM can call.
+   */
+  interface ToolDefinition {
+    /** Unique tool name. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** JSON Schema describing the tool parameters. */
+    parameters: Record<string, unknown>;
+    /** Handler invoked when the LLM calls this tool. */
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+  }
+
+  /**
+   * Custom command handler. Commands are prefixed with `/` (e.g. `/new`).
+   * Return a string to display as the reply, or void.
+   */
+  type CommandHandler = (args: string, conv: ConversationInstance) => Promise<string | void>;
+
+  // ---- Conversation options ----
+
+  /** Options for creating a new conversation via `CAT.agent.conversation.create()`. */
+  interface ConversationCreateOptions {
+    /** Custom conversation ID; auto-generated if omitted. */
+    id?: string;
+    /** System prompt. */
+    system?: string;
+    /** Model ID; uses the default model if omitted. */
+    model?: string;
+    /** Max tool-calling loop iterations (default: 20). */
+    maxIterations?: number;
+    /** Skills to load: `"auto"` loads all installed skills, or specify names. */
+    skills?: "auto" | string[];
+    /** Tools with inline handlers, available for the lifetime of this conversation. */
+    tools?: ToolDefinition[];
+    /**
+     * Custom slash-command handlers (e.g. `{ "/reset": handler }`).
+     * The built-in `/new` command (clear conversation) can be overridden.
+     */
+    commands?: Record<string, CommandHandler>;
+    /**
+     * Ephemeral mode: messages are kept in memory only, not persisted.
+     * Built-in tools/skills are NOT loaded; the script must supply all tools.
+     */
+    ephemeral?: boolean;
+    /** Enable prompt caching. Defaults to true. */
+    cache?: boolean;
+  }
+
+  /** Options for a single `chat()` / `chatStream()` call. */
+  interface ChatOptions {
+    /** Additional tools for this call only (merged with conversation-level tools). */
+    tools?: ToolDefinition[];
+  }
+
+  // ---- Tool call ----
+
+  /** Record of a tool call made by the LLM. */
+  interface ToolCallInfo {
+    /** Unique call ID. */
+    id: string;
+    /** Tool name. */
+    name: string;
+    /** JSON-serialized arguments. */
+    arguments: string;
+    /** Tool execution result (populated after execution). */
+    result?: string;
+    /** Call status. */
+    status?: "pending" | "running" | "completed" | "error";
+  }
+
+  // ---- Chat reply ----
+
+  /** Result of a non-streaming `chat()` call. */
+  interface ChatReply {
+    /** Response content. */
+    content: MessageContent;
+    /** Model thinking/reasoning text (if available). */
+    thinking?: string;
+    /** Tool calls made during this turn. */
+    toolCalls?: ToolCallInfo[];
+    /** Token usage. */
+    usage?: { inputTokens: number; outputTokens: number };
+    /** `true` when the reply was produced by a command handler, not the LLM. */
+    command?: boolean;
+  }
+
+  /** A single chunk emitted during streaming via `chatStream()`. */
+  interface StreamChunk {
+    /**
+     * Chunk type:
+     * - `"content_delta"` — incremental text
+     * - `"thinking_delta"` — incremental thinking/reasoning
+     * - `"tool_call"` — a tool call event
+     * - `"content_block"` — a complete non-text content block
+     * - `"done"` — stream finished
+     * - `"error"` — an error occurred
+     */
+    type: "content_delta" | "thinking_delta" | "tool_call" | "content_block" | "done" | "error";
+    /** Text delta (for content_delta / thinking_delta). */
+    content?: string;
+    /** Complete content block (for content_block). */
+    block?: ContentBlock;
+    /** Tool call info (for tool_call). */
+    toolCall?: ToolCallInfo;
+    /** Token usage (for done). */
+    usage?: { inputTokens: number; outputTokens: number };
+    /** Error message (for error). */
+    error?: string;
+    /** Error classification: `"rate_limit"` | `"auth"` | `"tool_timeout"` | `"max_iterations"` | `"api_error"` */
+    errorCode?: string;
+    /** `true` when the chunk was produced by a command handler. */
+    command?: boolean;
+  }
+
+  // ---- Chat message ----
+
+  /** A persisted chat message in a conversation. */
+  interface ChatMessage {
+    /** Message ID. */
+    id: string;
+    /** Parent conversation ID. */
+    conversationId: string;
+    /** Message role. */
+    role: "user" | "assistant" | "system" | "tool";
+    /** Message content (text or multimodal). */
+    content: MessageContent;
+    /** Model thinking/reasoning block. */
+    thinking?: { content: string };
+    /** Tool calls in this message. */
+    toolCalls?: ToolCallInfo[];
+    /** Associated tool_call ID (for role="tool" messages). */
+    toolCallId?: string;
+    /** Error message (if the turn errored). */
+    error?: string;
+    /** Model ID used for this message. */
+    modelId?: string;
+    /** Token usage for this message. */
+    usage?: {
+      inputTokens: number;
+      outputTokens: number;
+      /** Anthropic cache creation input tokens. */
+      cacheCreationInputTokens?: number;
+      /** Anthropic cache read input tokens. */
+      cacheReadInputTokens?: number;
+    };
+    /** Total response duration in ms. */
+    durationMs?: number;
+    /** Time-to-first-token in ms. */
+    firstTokenMs?: number;
+    /** Parent message ID (for branching). */
+    parentId?: string;
+    /** Creation timestamp. */
+    createtime: number;
+  }
+
+  // ---- Conversation instance ----
+
+  /**
+   * A conversation instance returned by `CAT.agent.conversation.create()` or `.get()`.
+   * Provides methods for chatting, streaming, and managing message history.
+   */
+  interface ConversationInstance {
+    /** Conversation ID. */
+    readonly id: string;
+    /** Conversation title. */
+    readonly title: string;
+    /** Model ID used. */
+    readonly modelId: string;
+
+    /** Send a message and wait for the full reply (with automatic tool-calling loop). */
+    chat(content: MessageContent, options?: ChatOptions): Promise<ChatReply>;
+
+    /** Send a message and receive a streaming response. */
+    chatStream(content: MessageContent, options?: ChatOptions): Promise<AsyncIterable<StreamChunk>>;
+
+    /** Get all messages in this conversation. */
+    getMessages(): Promise<ChatMessage[]>;
+
+    /** Clear all messages in this conversation. */
+    clear(): Promise<void>;
+
+    /** Persist the conversation to storage. */
+    save(): Promise<void>;
+  }
+
+  // ---- Conversation API ----
+
+  /**
+   * `CAT.agent.conversation` — create and retrieve conversation instances.
+   * @grant CAT.agent.conversation
+   */
+  interface ConversationAPI {
+    /** Create a new conversation. */
+    create(options?: ConversationCreateOptions): Promise<ConversationInstance>;
+
+    /** Get an existing conversation by ID. Returns `null` if not found. */
+    get(id: string): Promise<ConversationInstance | null>;
+  }
+}
+
+// ---- CAT.agent.tools — CATTool management API ----
+
+/** CATTool management types — install, remove, list, and invoke CATTools. */
+declare namespace CATAgentTools {
+  /** A parameter definition for a CATTool. */
+  interface CATToolParam {
+    /** Parameter name. */
+    name: string;
+    /** Parameter type. */
+    type: "string" | "number" | "boolean";
+    /** Whether required. */
+    required: boolean;
+    /** Parameter description. */
+    description: string;
+    /** Allowed values (for enum parameters). */
+    enum?: string[];
+  }
+
+  /** A persisted CATTool record. */
+  interface CATToolRecord {
+    /** Internal UUID. */
+    id: string;
+    /** Tool name (from `@name` metadata). */
+    name: string;
+    /** Tool description. */
+    description: string;
+    /** Parameter definitions. */
+    params: CATToolParam[];
+    /** Required GM grants. */
+    grants: string[];
+    /** `@require` URL list. */
+    requires?: string[];
+    /** Full source code (including metadata header). */
+    code: string;
+    /** UUID of the script that installed this tool. */
+    sourceScriptUuid?: string;
+    /** Name of the script that installed this tool. */
+    sourceScriptName?: string;
+    /** Installation timestamp. */
+    installtime: number;
+    /** Last update timestamp. */
+    updatetime: number;
+  }
+
+  /** Summary of a CATTool (without source code). Returned by `list()`. */
+  type CATToolSummary = Omit<CATToolRecord, "code">;
+
+  /**
+   * `CAT.agent.tools` — manage and invoke CATTools.
+   * @grant CAT.agent.tools
+   */
+  interface ToolsAPI {
+    /** Install a CATTool from source code. */
+    install(code: string): Promise<CATToolRecord>;
+
+    /** Remove a CATTool by name. */
+    remove(name: string): Promise<boolean>;
+
+    /** List all installed CATTools (without source code). */
+    list(): Promise<CATToolSummary[]>;
+
+    /** Invoke a CATTool by name with optional parameters. */
+    call(name: string, params?: Record<string, unknown>): Promise<unknown>;
+  }
+}
+
+// ---- CAT.agent.dom — Browser DOM automation API ----
+
+/** DOM automation types — interact with browser tabs, pages, and elements. */
+declare namespace CATAgentDom {
+  /** Information about a browser tab. */
+  interface TabInfo {
+    /** Tab ID. */
+    tabId: number;
+    /** Current URL. */
+    url: string;
+    /** Page title. */
+    title: string;
+    /** Whether the tab is active. */
+    active: boolean;
+    /** Window ID. */
+    windowId: number;
+    /** Whether the tab is discarded (unloaded from memory). */
+    discarded: boolean;
+  }
+
+  /** Result of a DOM action (click, fill, etc.). */
+  interface ActionResult {
+    /** Whether the action succeeded. */
+    success: boolean;
+    /** Whether a navigation occurred as a result. */
+    navigated?: boolean;
+    /** Current URL after the action. */
+    url?: string;
+    /** New tab opened as a result. */
+    newTab?: { tabId: number; url: string };
+  }
+
+  /** Page content returned by `readPage()`. */
+  interface PageContent {
+    /** Page title. */
+    title: string;
+    /** Page URL. */
+    url: string;
+    /** HTML content (or selected fragment). */
+    html: string;
+    /** Whether the content was truncated due to `maxLength`. */
+    truncated?: boolean;
+    /** Original total length before truncation. */
+    totalLength?: number;
+  }
+
+  /** Options for `readPage()`. */
+  interface ReadPageOptions {
+    /** Target tab ID; defaults to the active tab. */
+    tabId?: number;
+    /** CSS selector to read a specific element. */
+    selector?: string;
+    /** Maximum content length in characters. */
+    maxLength?: number;
+    /** Tags/selectors to remove before reading (e.g. `["script", "style", "svg"]`). */
+    removeTags?: string[];
+  }
+
+  /** Options for DOM actions (click, fill). */
+  interface DomActionOptions {
+    /** Target tab ID. */
+    tabId?: number;
+    /** Use trusted (CDP-dispatched) events instead of synthetic JS events. */
+    trusted?: boolean;
+  }
+
+  /** Options for `screenshot()`. */
+  interface ScreenshotOptions {
+    /** Target tab ID. */
+    tabId?: number;
+    /** JPEG quality (0–100). */
+    quality?: number;
+    /** Capture the full scrollable page. */
+    fullPage?: boolean;
+  }
+
+  /** Options for `navigate()`. */
+  interface NavigateOptions {
+    /** Target tab ID. */
+    tabId?: number;
+    /** Wait until the page is fully loaded. */
+    waitUntil?: boolean;
+    /** Navigation timeout in ms. */
+    timeout?: number;
+  }
+
+  /** Scroll direction. */
+  type ScrollDirection = "up" | "down" | "top" | "bottom";
+
+  /** Options for `scroll()`. */
+  interface ScrollOptions {
+    /** Target tab ID. */
+    tabId?: number;
+    /** Scroll within a specific element. */
+    selector?: string;
+  }
+
+  /** Result of a scroll operation. */
+  interface ScrollResult {
+    /** Current scroll position. */
+    scrollTop: number;
+    /** Total scrollable height. */
+    scrollHeight: number;
+    /** Visible viewport height. */
+    clientHeight: number;
+    /** Whether scrolled to the bottom. */
+    atBottom: boolean;
+  }
+
+  /** Result of a `navigate()` call. */
+  interface NavigateResult {
+    /** Tab ID. */
+    tabId: number;
+    /** Final URL after navigation. */
+    url: string;
+    /** Page title. */
+    title: string;
+  }
+
+  /** Options for `waitFor()`. */
+  interface WaitForOptions {
+    /** Target tab ID. */
+    tabId?: number;
+    /** Timeout in ms. */
+    timeout?: number;
+  }
+
+  /** Result of `waitFor()`. */
+  interface WaitForResult {
+    /** Whether the element was found. */
+    found: boolean;
+    /** Element details (when found). */
+    element?: {
+      selector: string;
+      tag: string;
+      text: string;
+      role?: string;
+      type?: string;
+      visible: boolean;
+    };
+  }
+
+  /** Options for `executeScript()`. */
+  interface ExecuteScriptOptions {
+    /** Target tab ID. */
+    tabId?: number;
+  }
+
+  /** Result of `stopMonitor()` — collected DOM changes during monitoring. */
+  interface MonitorResult {
+    /** Dialogs captured during monitoring. */
+    dialogs: Array<{ type: string; message: string }>;
+    /** DOM nodes added during monitoring. */
+    addedNodes: Array<{ tag: string; id?: string; class?: string; role?: string; text: string }>;
+  }
+
+  /** Result of `peekMonitor()` — summary of DOM changes being monitored. */
+  interface MonitorStatus {
+    /** Whether any changes were detected. */
+    hasChanges: boolean;
+    /** Number of dialogs captured. */
+    dialogCount: number;
+    /** Number of added DOM nodes captured. */
+    nodeCount: number;
+  }
+
+  /**
+   * `CAT.agent.dom` — browser tab and DOM automation.
+   * @grant CAT.agent.dom
+   */
+  interface DomAPI {
+    /** List all open browser tabs. */
+    listTabs(): Promise<TabInfo[]>;
+
+    /** Navigate a tab to a URL. */
+    navigate(url: string, options?: NavigateOptions): Promise<NavigateResult>;
+
+    /** Read the HTML content of a page (or a selected element). */
+    readPage(options?: ReadPageOptions): Promise<PageContent>;
+
+    /** Capture a screenshot of a tab. Returns a base64-encoded data URL. */
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+
+    /** Click an element matching the CSS selector. */
+    click(selector: string, options?: DomActionOptions): Promise<ActionResult>;
+
+    /** Fill an input/textarea matching the CSS selector with the given value. */
+    fill(selector: string, value: string, options?: DomActionOptions): Promise<ActionResult>;
+
+    /** Scroll a page or element. */
+    scroll(direction: ScrollDirection, options?: ScrollOptions): Promise<ScrollResult>;
+
+    /** Wait for an element matching the CSS selector to appear. */
+    waitFor(selector: string, options?: WaitForOptions): Promise<WaitForResult>;
+
+    /** Execute JavaScript code in the page context. */
+    executeScript(code: string, options?: ExecuteScriptOptions): Promise<unknown>;
+
+    /** Start monitoring DOM changes on a tab (dialogs, added nodes). */
+    startMonitor(tabId: number): Promise<void>;
+
+    /** Stop monitoring and return collected changes (dialogs, added nodes). */
+    stopMonitor(tabId: number): Promise<MonitorResult>;
+
+    /** Peek at the current monitor status for a tab. */
+    peekMonitor(tabId: number): Promise<MonitorStatus>;
+  }
+}
+
+// ---- CAT.agent.task — Scheduled task API ----
+
+/** Scheduled task types — create cron-based tasks that run agent conversations or emit events. */
+declare namespace CATAgentTask {
+  /** A scheduled agent task record. */
+  interface AgentTask {
+    /** Task ID. */
+    id: string;
+    /** Task name. */
+    name: string;
+    /** Cron expression. */
+    crontab: string;
+    /**
+     * Execution mode:
+     * - `"internal"` — Service Worker runs an LLM conversation automatically.
+     * - `"event"` — Notifies the script via `addListener`.
+     */
+    mode: "internal" | "event";
+    /** Whether the task is enabled. */
+    enabled: boolean;
+    /** Whether to show a browser notification on trigger. */
+    notify: boolean;
+
+    // --- internal mode fields ---
+    /** Prompt to send on each trigger. */
+    prompt?: string;
+    /** Model ID to use. */
+    modelId?: string;
+    /** Existing conversation ID to continue. */
+    conversationId?: string;
+    /** Skills to load. */
+    skills?: "auto" | string[];
+    /** Max tool-calling iterations (default: 10). */
+    maxIterations?: number;
+
+    // --- event mode fields ---
+    /** UUID of the script that created this task. */
+    sourceScriptUuid?: string;
+
+    // --- runtime status ---
+    /** Last run timestamp. */
+    lastruntime?: number;
+    /** Next scheduled run timestamp. */
+    nextruntime?: number;
+    /** Last run result status. */
+    lastRunStatus?: "success" | "error";
+    /** Last run error message. */
+    lastRunError?: string;
+    /** Creation timestamp. */
+    createtime: number;
+    /** Last update timestamp. */
+    updatetime: number;
+  }
+
+  /** Event payload delivered to `addListener` callbacks when a task triggers. */
+  interface AgentTaskTrigger {
+    /** Task ID. */
+    taskId: string;
+    /** Task name. */
+    name: string;
+    /** Cron expression. */
+    crontab: string;
+    /** Trigger timestamp. */
+    triggeredAt: number;
+  }
+
+  /** Options for creating a new task (fields auto-populated by the system are omitted). */
+  type AgentTaskCreateOptions = Omit<
+    AgentTask,
+    "id" | "createtime" | "updatetime" | "nextruntime" | "sourceScriptUuid"
+  >;
+
+  /**
+   * `CAT.agent.task` — create and manage scheduled agent tasks.
+   * @grant CAT.agent.task
+   */
+  interface TaskAPI {
+    /** Create a new scheduled task. */
+    create(options: AgentTaskCreateOptions): Promise<AgentTask>;
+
+    /** List all tasks. */
+    list(): Promise<AgentTask[]>;
+
+    /** Get a task by ID. */
+    get(id: string): Promise<AgentTask | undefined>;
+
+    /** Update a task. */
+    update(id: string, task: Partial<AgentTask>): Promise<AgentTask>;
+
+    /** Remove a task by ID. */
+    remove(id: string): Promise<boolean>;
+
+    /** Immediately trigger a task (regardless of cron schedule). */
+    runNow(id: string): Promise<void>;
+
+    /**
+     * Listen for task trigger events (for `mode: "event"` tasks).
+     * Returns a listener ID for later removal.
+     */
+    addListener(taskId: string, callback: (trigger: AgentTaskTrigger) => void): number;
+
+    /** Remove a previously registered listener. */
+    removeListener(listenerId: number): void;
+  }
+}
+
+// ---- CAT.agent.skills — Skill management API ----
+
+/** Skill management types — install, remove, and query Agent Skills. */
+declare namespace CATAgentSkills {
+  /** Summary info for an installed Skill. */
+  interface SkillSummary {
+    /** Skill name. */
+    name: string;
+    /** Skill description. */
+    description: string;
+    /** CATTool names bundled in this Skill (from `scripts/` directory). */
+    toolNames: string[];
+    /** Reference document names (from `references/` directory). */
+    referenceNames: string[];
+    /** Whether this Skill has config fields declared. */
+    hasConfig?: boolean;
+    /** Installation timestamp. */
+    installtime: number;
+    /** Last update timestamp. */
+    updatetime: number;
+  }
+
+  /** Config field definition declared in SKILL.md frontmatter. */
+  interface SkillConfigField {
+    /** Display title. */
+    title: string;
+    /** Widget type. */
+    type: "text" | "number" | "select" | "switch";
+    /** Whether the value should be masked (e.g. API keys). */
+    secret?: boolean;
+    /** Whether the field is required. */
+    required?: boolean;
+    /** Default value. */
+    default?: unknown;
+    /** Allowed values (for `select` type). */
+    values?: string[];
+  }
+
+  /** Full Skill record including the prompt and config schema. */
+  interface SkillRecord extends SkillSummary {
+    /** SKILL.md body (markdown after frontmatter removal). */
+    prompt: string;
+    /** Config schema from SKILL.md frontmatter. */
+    config?: Record<string, SkillConfigField>;
+  }
+
+  /**
+   * `CAT.agent.skills` — manage Agent Skills (packaged prompts + tools + references).
+   * @grant CAT.agent.skills
+   */
+  interface SkillsAPI {
+    /** List all installed Skills. */
+    list(): Promise<SkillSummary[]>;
+
+    /** Get full details of a Skill by name. Returns `null` if not found. */
+    get(name: string): Promise<SkillRecord | null>;
+
+    /**
+     * Install a Skill from a SKILL.md string, with optional bundled scripts and references.
+     * @param skillMd - The SKILL.md content (with YAML frontmatter).
+     * @param scripts - CATTool scripts to bundle.
+     * @param references - Reference documents to bundle.
+     */
+    install(
+      skillMd: string,
+      scripts?: Array<{ name: string; code: string }>,
+      references?: Array<{ name: string; content: string }>
+    ): Promise<SkillRecord>;
+
+    /** Remove a Skill by name. */
+    remove(name: string): Promise<boolean>;
+  }
+}
+
+// ---- CAT global object ----
+
+/**
+ * ScriptCat Agent global object — provides access to conversation, tools, DOM, task, and skills APIs.
+ * Each sub-API requires its own `@grant` declaration.
+ */
+declare const CAT: {
+  agent: {
+    /** @grant CAT.agent.conversation */
+    conversation: CATAgent.ConversationAPI;
+    /** @grant CAT.agent.tools */
+    tools: CATAgentTools.ToolsAPI;
+    /** @grant CAT.agent.dom */
+    dom: CATAgentDom.DomAPI;
+    /** @grant CAT.agent.task */
+    task: CATAgentTask.TaskAPI;
+    /** @grant CAT.agent.skills */
+    skills: CATAgentSkills.SkillsAPI;
+  };
+};
+
+/**
+ * Skill configuration values injected into the CATTool sandbox at runtime.
+ *
+ * Declared in the `config` block of a SKILL.md frontmatter and filled in by
+ * the user through the Skill settings UI. The object is frozen at injection
+ * time, so properties are read-only.
+ */
+declare const CAT_CONFIG: Readonly<Record<string, unknown>>;
diff --git a/src/types/scriptcat.zh-CN.d.ts b/src/types/scriptcat.zh-CN.d.ts
new file mode 100644
index 000000000..9fecfe677
--- /dev/null
+++ b/src/types/scriptcat.zh-CN.d.ts
@@ -0,0 +1,1525 @@
+// ============================================================================
+// scriptcat.zh-CN.d.ts — ScriptCat 全量中文类型声明
+// 此文件为 scriptcat.d.ts 的中文翻译版本，包含所有 GM_*/CAT_*/CAT.agent API。
+// 如需接入，请在 tsconfig.json 中替换或追加此文件。
+// ============================================================================
+
+// @copyright https://github.com/silverwzw/Tampermonkey-Typescript-Declaration
+
+declare const unsafeWindow: Window;
+
+declare type ConfigType = "text" | "checkbox" | "select" | "mult-select" | "number" | "textarea" | "time";
+
+declare interface Config {
+  [key: string]: unknown;
+  /** 配置项标题。 */
+  title: string;
+  /** 配置项描述。 */
+  description: string;
+  /** 默认值。 */
+  default?: unknown;
+  /** UI 控件类型。 */
+  type?: ConfigType;
+  /** 双向绑定的键名。 */
+  bind?: string;
+  /** 允许的值（用于 select / multi-select）。 */
+  values?: unknown[];
+  /** 是否隐藏输入内容（密码字段）。 */
+  password?: boolean;
+  /** 文本最大长度 / 数值最大值。 */
+  max?: number;
+  /** 数值最小值。 */
+  min?: number;
+  /** 行数（用于 textarea）。 */
+  rows?: number;
+  /** 配置项排序索引。 */
+  index: number;
+}
+
+declare type UserConfig = { [key: string]: { [key: string]: Config } };
+
+/** 脚本及环境元数据，兼容 Tampermonkey 的 `GM_info`。 */
+declare const GM_info: {
+  /** ScriptCat 版本号。 */
+  version: string;
+  /** 脚本是否已启用自动更新。 */
+  scriptWillUpdate: boolean;
+  /** 始终为 `"ScriptCat"`。 */
+  scriptHandler: "ScriptCat";
+  scriptUpdateURL?: string;
+  scriptMetaStr?: string;
+  userConfig?: UserConfig;
+  userConfigStr?: string;
+  /** 是否在隐私/无痕窗口中运行。 */
+  isIncognito: boolean;
+  /** 沙箱模式（ScriptCat 始终使用 `"raw"`）。 */
+  sandboxMode: "raw";
+  userAgentData: {
+    brands?: { brand: string; version: string }[];
+    mobile?: boolean;
+    platform?: string;
+    architecture?: string;
+    bitness?: string;
+  };
+  /** 下载模式（ScriptCat 使用 `"native"`）。 */
+  downloadMode: "native";
+  /** 从脚本头部解析的元数据。 */
+  script: {
+    author?: string;
+    description?: string;
+    grant: string[];
+    header: string;
+    icon?: string;
+    icon64?: string;
+    includes?: string[];
+    matches: string[];
+    name: string;
+    namespace?: string;
+    "run-at": string;
+    "run-in": string[];
+    version: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+// ===========================================================================
+// GM_* 函数（Greasemonkey/Tampermonkey 兼容，同步风格）
+// ===========================================================================
+
+/** 列出所有已存储的值的键名。 */
+declare function GM_listValues(): string[];
+
+/** 监听某个存储值的变化。返回监听器 ID。 */
+declare function GM_addValueChangeListener(name: string, listener: GMTypes.ValueChangeListener): number;
+
+/** 根据 ID 移除值变化监听器。 */
+declare function GM_removeValueChangeListener(listenerId: number): void;
+
+/** 存储一个值。 */
+declare function GM_setValue(name: string, value: any): void;
+
+/** 批量存储多个值。键为值的名称。 */
+declare function GM_setValues(values: { [key: string]: any }): void;
+
+/** 获取存储的值（未找到时返回 `defaultValue`）。 */
+declare function GM_getValue(name: string, defaultValue?: any): any;
+
+/**
+ * 批量获取多个值。
+ * 若 `keysOrDefaults` 为对象，其值作为默认值；若为数组，每个元素为键名（无默认值）。
+ */
+declare function GM_getValues(keysOrDefaults: { [key: string]: any } | string[] | null | undefined): {
+  [key: string]: any;
+};
+
+/** 删除一个存储的值。 */
+declare function GM_deleteValue(name: string): void;
+
+/** 批量删除多个存储的值。 */
+declare function GM_deleteValues(names: string[]): void;
+
+/** 记录日志，可选等级和结构化标签。 */
+declare function GM_log(message: string, level?: GMTypes.LoggerLevel, ...labels: GMTypes.LoggerLabel[]): void;
+
+/** 根据名称获取 `@resource` 的文本内容。 */
+declare function GM_getResourceText(name: string): string | undefined;
+
+/** 根据名称获取 `@resource` 的 URL（data: 或 blob:）。 */
+declare function GM_getResourceURL(name: string, isBlobUrl?: boolean): string | undefined;
+
+/** 在 ScriptCat 弹出面板中注册菜单命令。 */
+declare function GM_registerMenuCommand(
+  name: string,
+  listener?: (inputValue?: any) => void,
+  options_or_accessKey?:
+    | {
+        id?: number | string;
+        /** 键盘快捷键。 */
+        accessKey?: string;
+        /** 点击菜单后是否关闭弹出面板（默认 true）。 */
+        autoClose?: boolean;
+        /** SC 扩展：嵌套在父菜单下（默认 true）。`false` 提升到浏览器右键菜单。 */
+        nested?: boolean;
+        /** SC 扩展：不合并相同菜单项（默认 false）。 */
+        individual?: boolean;
+      }
+    | string
+): number;
+
+/** 根据 ID 注销菜单命令。 */
+declare function GM_unregisterMenuCommand(id: number): void;
+
+/**
+ * 注册带输入框的菜单项，允许用户输入值。
+ * 回调接收用户的输入。
+ */
+declare function CAT_registerMenuInput(
+  name: string,
+  listener?: (inputValue?: any) => void,
+  options_or_accessKey?:
+    | {
+        id?: number | string;
+        accessKey?: string;
+        autoClose?: boolean;
+        nested?: boolean;
+        individual?: boolean;
+        /** 输入控件类型。 */
+        inputType?: "text" | "number" | "boolean";
+        /** 对话框标题。 */
+        title?: string;
+        /** 输入框旁显示的标签。 */
+        inputLabel?: string;
+        /** 输入框默认值。 */
+        inputDefaultValue?: string | number | boolean;
+        /** 占位文本。 */
+        inputPlaceholder?: string;
+      }
+    | string
+): number;
+
+/** 注销菜单输入（`GM_unregisterMenuCommand` 的别名）。 */
+declare const CAT_unregisterMenuInput: typeof GM_unregisterMenuCommand;
+
+/** 等待脚本完全加载。配合 `@early-start` 使用。 */
+declare function CAT_scriptLoaded(): Promise<void>;
+
+/** 从 Blob 对象创建 blob URL。ScriptCat 管理 URL 生命周期。 */
+declare function CAT_createBlobUrl(blob: Blob): Promise<string>;
+
+/** 获取 blob URL 并返回 Blob 数据。用于 `GM_xmlhttpRequest` stream 响应的辅助函数。 */
+declare function CAT_fetchBlob(url: string): Promise<Blob>;
+
+/** 获取 URL 并解析为 Document（优先在内容页上下文中执行）。 */
+declare function CAT_fetchDocument(url: string): Promise<Document | undefined>;
+
+/** 在新标签页中打开 URL。返回 Tab 句柄（上下文无效时返回 `undefined`）。 */
+declare function GM_openInTab(url: string, options: GMTypes.OpenTabOptions): GMTypes.Tab | undefined;
+declare function GM_openInTab(url: string, loadInBackground: boolean): GMTypes.Tab | undefined;
+declare function GM_openInTab(url: string): GMTypes.Tab | undefined;
+
+/** 关闭由 `GM_openInTab` 打开的标签页。 */
+declare function GM_closeInTab(tabId: string): void;
+
+/** 执行跨域 XMLHttpRequest。目标域名需在 `@connect` 中声明。 */
+declare function GM_xmlhttpRequest(details: GMTypes.XHRDetails): GMTypes.AbortHandle<void>;
+
+/** 下载文件。 */
+declare function GM_download(details: GMTypes.DownloadDetails<string | Blob | File>): GMTypes.AbortHandle<boolean>;
+declare function GM_download(url: string, filename: string): GMTypes.AbortHandle<boolean>;
+
+/** 获取标签页的持久化存储对象。 */
+declare function GM_getTab(callback: (tab: object) => void): void;
+
+/** 保存标签页的持久化存储对象。 */
+declare function GM_saveTab(tab: object): void;
+
+/** 获取所有标签页的持久化存储对象。 */
+declare function GM_getTabs(callback: (tabs: { [key: number]: object }) => void): void;
+
+/** 显示桌面通知。 */
+declare function GM_notification(details: GMTypes.NotificationDetails, ondone?: GMTypes.NotificationOnDone): void;
+declare function GM_notification(
+  text: string,
+  title: string,
+  image: string,
+  onclick?: GMTypes.NotificationOnClick
+): void;
+
+/** 根据 ID 关闭通知。 */
+declare function GM_closeNotification(id: string): void;
+
+/** 根据 ID 更新通知。 */
+declare function GM_updateNotification(id: string, details: GMTypes.NotificationDetails): void;
+
+/** 复制文本到剪贴板。 */
+declare function GM_setClipboard(data: string, info?: string | { type?: string; mimetype?: string }): void;
+
+/** 向页面添加 DOM 元素。 */
+declare function GM_addElement(tag: string, attributes: Record<string, string | number | boolean>): HTMLElement;
+declare function GM_addElement(
+  parentNode: Node,
+  tag: string,
+  attrs: Record<string, string | number | boolean>
+): HTMLElement;
+
+/** 向页面注入 CSS 样式表。 */
+declare function GM_addStyle(css: string): Element | undefined;
+
+/**
+ * 执行 Cookie 操作。`name` 和 `domain` 不能同时为空。
+ * @param action - `"list"` | `"set"` | `"delete"`
+ */
+declare function GM_cookie(
+  action: GMTypes.CookieAction,
+  details: GMTypes.CookieDetails,
+  ondone: (cookie: GMTypes.Cookie[], error: unknown | undefined) => void
+): void;
+
+// ===========================================================================
+// GM.* 对象（Greasemonkey 4 / Tampermonkey 4+ Promise 风格 API）
+// ===========================================================================
+
+/** Promise 风格的 API 对象。每个方法对应一个 `GM_*` 函数。 */
+declare const GM: {
+  /** 脚本及环境元数据（同 `GM_info`）。 */
+  readonly info: typeof GM_info;
+
+  /** 获取存储的值。 */
+  getValue<T = any>(name: string, defaultValue?: T): Promise<T>;
+
+  /** 批量获取多个存储的值。若 `keysOrDefaults` 为对象，其值作为默认值。 */
+  getValues(keysOrDefaults: { [key: string]: any } | string[] | null | undefined): Promise<{ [key: string]: any }>;
+
+  /** 存储一个值。 */
+  setValue(name: string, value: any): Promise<void>;
+
+  /** 批量存储多个值。 */
+  setValues(values: { [key: string]: any }): Promise<void>;
+
+  /** 删除一个存储的值。 */
+  deleteValue(name: string): Promise<void>;
+
+  /** 批量删除多个存储的值。 */
+  deleteValues(names: string[]): Promise<void>;
+
+  /** 列出所有已存储的值的键名。 */
+  listValues(): Promise<string[]>;
+
+  /** 监听存储值的变化。 */
+  addValueChangeListener(name: string, listener: GMTypes.ValueChangeListener): Promise<number>;
+  /** 移除值变化监听器。 */
+  removeValueChangeListener(listenerId: number): Promise<void>;
+
+  /** 记录日志，可选等级和结构化标签。 */
+  log(message: string, level?: GMTypes.LoggerLevel, ...labels: GMTypes.LoggerLabel[]): Promise<void>;
+
+  /** 获取 `@resource` 的文本内容。 */
+  getResourceText(name: string): Promise<string | undefined>;
+
+  /** 获取 `@resource` 的 URL。 */
+  getResourceURL(name: string, isBlobUrl?: boolean): Promise<string | undefined>;
+
+  /** 注册菜单命令。 */
+  registerMenuCommand(
+    name: string,
+    listener?: (inputValue?: any) => void,
+    options_or_accessKey?:
+      | {
+          id?: number | string;
+          accessKey?: string;
+          autoClose?: boolean;
+          title?: string;
+          /** SC 扩展：菜单图标 URL。 */
+          icon?: string;
+          /** SC 扩展：`autoClose` 的别名。 */
+          closeOnClick?: boolean;
+        }
+      | string
+  ): Promise<number | string | undefined>;
+
+  /** 注销菜单命令。 */
+  unregisterMenuCommand(id: number | string): Promise<void>;
+
+  /** 注入 CSS 样式表。 */
+  addStyle(css: string): Promise<Element | undefined>;
+
+  /** 显示桌面通知。 */
+  notification(details: GMTypes.NotificationDetails, ondone?: GMTypes.NotificationOnDone): Promise<void>;
+  notification(text: string, title: string, image: string, onclick?: GMTypes.NotificationOnClick): Promise<void>;
+  /** 关闭通知。 */
+  closeNotification(id: string): Promise<void>;
+  /** 更新通知。 */
+  updateNotification(id: string, details: GMTypes.NotificationDetails): Promise<void>;
+
+  /** 复制文本到剪贴板。 */
+  setClipboard(data: string, info?: string | { type?: string; mimetype?: string }): Promise<void>;
+
+  /** 添加 DOM 元素。 */
+  addElement(tag: string, attributes: Record<string, string | number | boolean>): Promise<HTMLElement>;
+  addElement(parentNode: Node, tag: string, attrs: Record<string, string | number | boolean>): Promise<HTMLElement>;
+
+  /** 执行跨域 XMLHttpRequest。返回的 Promise 同时具有 `.abort()` 方法。 */
+  xmlHttpRequest(details: GMTypes.XHRDetails): Promise<GMTypes.XHRResponse> & GMTypes.AbortHandle<void>;
+
+  /** 下载文件。 */
+  download(details: GMTypes.DownloadDetails<string | Blob | File>): Promise<boolean>;
+  download(url: string, filename: string): Promise<boolean>;
+
+  /** 获取标签页的持久化存储对象。 */
+  getTab(): Promise<object>;
+  /** 保存标签页的持久化存储对象。 */
+  saveTab(tab: object): Promise<void>;
+  /** 获取所有标签页的持久化存储对象。 */
+  getTabs(): Promise<{ [key: number]: object }>;
+
+  /** 在新标签页中打开 URL。 */
+  openInTab(url: string, options: GMTypes.OpenTabOptions): Promise<GMTypes.Tab | undefined>;
+  openInTab(url: string, loadInBackground: boolean): Promise<GMTypes.Tab | undefined>;
+  openInTab(url: string): Promise<GMTypes.Tab | undefined>;
+
+  /** 关闭由 `openInTab` 打开的标签页。 */
+  closeInTab(tabId: string): Promise<void>;
+
+  /** Cookie 操作（含子方法）。 */
+  cookie: {
+    (action: GMTypes.CookieAction, details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+    /** 设置 Cookie。 */
+    set(details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+    /** 列出匹配的 Cookie。 */
+    list(details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+    /** 删除 Cookie。 */
+    delete(details: GMTypes.CookieDetails): Promise<GMTypes.Cookie[]>;
+  };
+};
+
+// ===========================================================================
+// CAT_* 函数（ScriptCat 专有扩展）
+// ===========================================================================
+
+/**
+ * 设置浏览器代理规则。
+ * @deprecated 已从稳定版移除；可能在 beta 版中恢复。
+ */
+declare function CAT_setProxy(rule: CATType.ProxyRule[] | string): void;
+
+/**
+ * 清除所有代理规则。
+ * @deprecated 已从稳定版移除；可能在 beta 版中恢复。
+ */
+declare function CAT_clearProxy(): void;
+
+/**
+ * 在坐标 (x, y) 模拟真实点击。
+ * @deprecated 已从稳定版移除；可能在 beta 版中恢复。
+ */
+declare function CAT_click(x: number, y: number): void;
+
+/** 打开脚本的用户配置页面。 */
+declare function CAT_userConfig(): void;
+
+/**
+ * 与托管文件存储系统交互。
+ * 为当前脚本创建 `app/<uuid>` 目录（或使用 `baseDir`）。
+ * 上传会覆盖同名文件。
+ * @param action - `"list"` | `"upload"` | `"download"` | `"delete"` | `"config"`
+ */
+declare function CAT_fileStorage(
+  action: "list",
+  details: {
+    /** 要列出的目录路径。 */
+    path?: string;
+    /** 基础目录；默认为脚本的 UUID。 */
+    baseDir?: string;
+    onload?: (files: CATType.FileStorageFileInfo[]) => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+  }
+): void;
+declare function CAT_fileStorage(
+  action: "download",
+  details: {
+    /** 文件信息对象（某些平台需要文件哈希）。 */
+    file: CATType.FileStorageFileInfo;
+    onload: (data: Blob) => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+  }
+): void;
+declare function CAT_fileStorage(
+  action: "delete",
+  details: {
+    /** 要删除的文件路径。 */
+    path: string;
+    onload?: () => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+  }
+): void;
+declare function CAT_fileStorage(
+  action: "upload",
+  details: {
+    /** 目标文件路径。 */
+    path: string;
+    /** 基础目录；默认为脚本的 UUID。 */
+    baseDir?: string;
+    /** 要上传的文件数据。 */
+    data: Blob;
+    onload?: () => void;
+    onerror?: (error: CATType.FileStorageError) => void;
+  }
+): void;
+/** 打开文件存储配置页面。 */
+declare function CAT_fileStorage(action: "config"): void;
+
+/**
+ * 后台脚本重试错误。抛出此错误可让 ScriptCat 稍后重试。
+ * 最小重试间隔为 5 秒。避免与脚本自身的调度重叠。
+ */
+declare class CATRetryError {
+  /** @param message - 错误信息。 @param seconds - N 秒后重试。 */
+  constructor(message: string, seconds: number);
+  /** @param message - 错误信息。 @param date - 在指定时间重试。 */
+  constructor(message: string, date: Date);
+}
+
+// ===========================================================================
+// CATType 命名空间（ScriptCat 专有类型）
+// ===========================================================================
+
+declare namespace CATType {
+  interface ProxyRule {
+    proxyServer: ProxyServer;
+    matchUrl: string[];
+  }
+
+  type ProxyScheme = "http" | "https" | "quic" | "socks4" | "socks5";
+
+  interface ProxyServer {
+    scheme?: ProxyScheme;
+    host: string;
+    port?: number;
+  }
+
+  interface FileStorageError {
+    /**
+     * 错误码：
+     * -1 = 未知，1 = 存储未配置，2 = 配置错误，3 = 路径不存在，
+     * 4 = 上传失败，5 = 下载失败，6 = 删除失败，
+     * 7 = 不允许的文件路径，8 = 网络错误
+     */
+    code: -1 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+    error: string;
+  }
+
+  interface FileStorageFileInfo {
+    /** 文件名。 */
+    name: string;
+    /** 相对文件路径。 */
+    path: string;
+    /** 存储空间中的绝对路径。 */
+    absPath: string;
+    /** 文件大小（字节）。 */
+    size: number;
+    /** 文件内容摘要/哈希。 */
+    digest: string;
+    /** 创建时间戳。 */
+    createtime: number;
+    /** 最后修改时间戳。 */
+    updatetime: number;
+  }
+
+  type CATFileStorageDetails = {
+    baseDir: string;
+    path: string;
+    filename: any;
+    file: FileStorageFileInfo;
+    data?: string;
+  };
+}
+
+// ===========================================================================
+// GMTypes 命名空间（Greasemonkey/Tampermonkey 兼容类型）
+// ===========================================================================
+
+declare namespace GMTypes {
+  type CookieAction = "list" | "delete" | "set";
+
+  type LoggerLevel = "debug" | "info" | "warn" | "error";
+
+  type LoggerLabel = {
+    [key: string]: string | boolean | number | undefined;
+  };
+
+  interface CookieDetailsPartitionKeyType {
+    topLevelSite?: string;
+  }
+
+  interface CookieDetails {
+    url?: string;
+    name?: string;
+    value?: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    session?: boolean;
+    httpOnly?: boolean;
+    expirationDate?: number;
+    partitionKey?: CookieDetailsPartitionKeyType;
+  }
+
+  interface Cookie {
+    domain: string;
+    name: string;
+    value: string;
+    session: boolean;
+    hostOnly: boolean;
+    expirationDate?: number;
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "unspecified" | "no_restriction" | "lax" | "strict";
+  }
+
+  /** 值变化监听器。`tabid` 仅在后台脚本监听器中可用。 */
+  type ValueChangeListener = (
+    name: string,
+    oldValue: unknown,
+    newValue: unknown,
+    remote: boolean,
+    tabid?: number
+  ) => unknown;
+
+  interface OpenTabOptions {
+    /**
+     * 新标签页是否立即获得焦点。
+     * - `true` — 前台打开。
+     * - `false` — 后台打开。
+     * @default true
+     */
+    active?: boolean;
+
+    /**
+     * 标签页插入位置。
+     * - `true` / `1` — 插入到当前标签页之后。
+     * - `false` — 追加到窗口末尾。
+     * - `0` — 插入到当前标签页之前。
+     * @default true
+     */
+    insert?: boolean | number;
+
+    /**
+     * 设置 opener 标签页 ID，以便浏览器追踪父子关系。
+     * @default true
+     */
+    setParent?: boolean;
+
+    /**
+     * 在隐私/无痕窗口中打开。
+     * 注意：ScriptCat 使用 `"incognito": "split"` — 在普通窗口中，
+     * tabId/windowId 将不可用。
+     * @default false
+     */
+    incognito?: boolean;
+
+    /**
+     * 旧版字段（仅 TM）。语义与 `active` **相反**：
+     * `true` = 后台，`false` = 前台。
+     * @default false
+     * @deprecated 请使用 `active` 代替。
+     */
+    loadInBackground?: boolean;
+
+    /**
+     * 将新标签页固定在浏览器标签栏。
+     * @default false
+     */
+    pinned?: boolean;
+
+    /**
+     * 使用 `window.open` 代替 `chrome.tabs.create`。
+     * 适用于特殊协议如 `vscode://`、`m3u8dl://`。
+     * 此模式下其他选项会被忽略。
+     * @default false
+     */
+    useOpen?: boolean;
+  }
+
+  type SWOpenTabOptions = OpenTabOptions & Required<Pick<OpenTabOptions, "active">>;
+
+  /**
+   * XMLHttpRequest readyState 值。
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/readyState
+   */
+  type ReadyState =
+    | 0 // UNSENT
+    | 1 // OPENED
+    | 2 // HEADERS_RECEIVED
+    | 3 // LOADING
+    | 4; // DONE
+
+  interface XHRResponse {
+    finalUrl?: string;
+    readyState?: ReadyState;
+    responseHeaders?: string;
+    status?: number;
+    statusText?: string;
+    response?: string | Blob | ArrayBuffer | Document | ReadableStream<Uint8Array<ArrayBufferLike>> | null | undefined;
+    responseText?: string | undefined;
+    responseXML?: Document | null | undefined;
+    responseType?: "text" | "arraybuffer" | "blob" | "json" | "document" | "stream" | "";
+  }
+
+  interface XHRProgress extends XHRResponse {
+    done: number;
+    lengthComputable: boolean;
+    loaded: number;
+    position?: number;
+    total: number;
+    totalSize: number;
+  }
+
+  type Listener<OBJ> = (event: OBJ) => unknown;
+  type ContextType = unknown;
+
+  type GMXHRDataType = string | Blob | File | BufferSource | FormData | URLSearchParams;
+
+  interface XHRDetails {
+    method?: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+    url: string | URL | File | Blob;
+    headers?: { [key: string]: string };
+    data?: GMXHRDataType;
+    cookie?: string;
+    binary?: boolean;
+    timeout?: number;
+    context?: ContextType;
+    /** 响应类型。当前版本中 `"stream"` 支持有限。 */
+    responseType?: "text" | "arraybuffer" | "blob" | "json" | "document" | "stream";
+    overrideMimeType?: string;
+    /** 发送不带 Cookie 的请求（Tampermonkey 兼容）。 */
+    anonymous?: boolean;
+    /** 发送不带 Cookie 的请求（Greasemonkey 兼容）。 */
+    mozAnon?: boolean;
+    /** 强制内部使用 Fetch API。 */
+    fetch?: boolean;
+    user?: string;
+    password?: string;
+    /** 禁用缓存。 */
+    nocache?: boolean;
+    /** 强制重新验证：允许缓存但使用前重新验证。 */
+    revalidate?: boolean;
+    /** 重定向处理。内部强制使用 fetch 模式。 */
+    redirect?: "follow" | "error" | "manual";
+    /** 分区 Cookie 键，用于存储分区。 */
+    cookiePartition?: Record<string, any> & { topLevelSite?: string };
+
+    onload?: Listener<XHRResponse>;
+    onloadstart?: Listener<XHRResponse>;
+    onloadend?: Listener<XHRResponse>;
+    onprogress?: Listener<XHRProgress>;
+    onreadystatechange?: Listener<XHRResponse>;
+    ontimeout?: Listener<XHRResponse>;
+    onabort?: Listener<XHRResponse>;
+    onerror?: (err: string | (XHRResponse & { error: string })) => void;
+  }
+
+  interface AbortHandle<RETURN_TYPE> {
+    abort(): RETURN_TYPE;
+  }
+
+  interface DownloadError {
+    error: "not_enabled" | "not_whitelisted" | "not_permitted" | "not_supported" | "not_succeeded" | "unknown";
+    details?: string;
+  }
+
+  interface DownloadDetails<URL> {
+    // 标准参数（TM/SC）
+    url: URL;
+    name: string;
+    headers?: { [key: string]: string };
+    saveAs?: boolean;
+    conflictAction?: "uniquify" | "overwrite" | "prompt";
+
+    // 扩展参数（SC/VM）
+    timeout?: number;
+    anonymous?: boolean;
+    context?: ContextType;
+    user?: string;
+    password?: string;
+
+    // SC 专有参数
+    method?: "GET" | "POST";
+    downloadMode?: "native" | "browser";
+    cookie?: string;
+
+    // 回调
+    onload?: Listener<object>;
+    onerror?: Listener<DownloadError>;
+    onprogress?: Listener<{
+      done: number;
+      lengthComputable: boolean;
+      loaded: number;
+      position?: number;
+      total: number;
+      totalSize: number;
+    }>;
+    ontimeout?: (arg1?: any) => void;
+  }
+
+  interface NotificationThis extends NotificationDetails {
+    id: string;
+  }
+
+  type NotificationOnClickEvent = {
+    event: "click" | "buttonClick";
+    id: string;
+    isButtonClick: boolean;
+    buttonClickIndex: number | undefined;
+    byUser: boolean | undefined;
+    preventDefault: () => void;
+    highlight: NotificationDetails["highlight"];
+    image: NotificationDetails["image"];
+    silent: NotificationDetails["silent"];
+    tag: NotificationDetails["tag"];
+    text: NotificationDetails["tag"];
+    timeout: NotificationDetails["timeout"];
+    title: NotificationDetails["title"];
+    url: NotificationDetails["url"];
+  };
+  type NotificationOnClick = (this: NotificationThis, event: NotificationOnClickEvent) => unknown;
+  type NotificationOnDone = (this: NotificationThis, user?: boolean) => unknown;
+
+  interface NotificationButton {
+    title: string;
+    iconUrl?: string;
+  }
+
+  interface NotificationDetails {
+    text?: string;
+    title?: string;
+    tag?: string;
+    image?: string;
+    highlight?: boolean;
+    silent?: boolean;
+    timeout?: number;
+    url?: string;
+    onclick?: NotificationOnClick;
+    ondone?: NotificationOnDone;
+    progress?: number;
+    oncreate?: NotificationOnClick;
+    /** 最多 2 个按钮。 */
+    buttons?: NotificationButton[];
+  }
+
+  interface Tab {
+    close(): void;
+    onclose?: () => void;
+    closed?: boolean;
+    name?: string;
+  }
+
+  type GMClipboardInfo = string | { type?: string; mimetype?: string };
+}
+
+// ===========================================================================
+// CAT.agent — ScriptCat Agent API
+// @grant CAT.agent.conversation / CAT.agent.tools / CAT.agent.dom /
+//        CAT.agent.task / CAT.agent.skills
+// ===========================================================================
+
+// ---- CAT.agent.conversation API ----
+
+/** CAT Agent 对话、内容块和流式类型。 */
+declare namespace CATAgent {
+  // ---- 内容块类型 ----
+
+  /** 纯文本内容块。 */
+  type TextBlock = { type: "text"; text: string };
+
+  /** 图片内容块。数据存储在 OPFS 中，通过 `attachmentId` 引用。 */
+  type ImageBlock = { type: "image"; attachmentId: string; mimeType: string; name?: string };
+
+  /** 文件内容块。 */
+  type FileBlock = { type: "file"; attachmentId: string; mimeType: string; name: string; size?: number };
+
+  /** 音频内容块。 */
+  type AudioBlock = {
+    type: "audio";
+    attachmentId: string;
+    mimeType: string;
+    name?: string;
+    /** 时长（毫秒）。 */
+    durationMs?: number;
+  };
+
+  /** 所有内容块类型的联合类型。 */
+  type ContentBlock = TextBlock | ImageBlock | FileBlock | AudioBlock;
+
+  /** 消息内容：纯字符串或内容块数组（多模态）。 */
+  type MessageContent = string | ContentBlock[];
+
+  // ---- 工具类型 ----
+
+  /**
+   * 工具定义（含内联处理函数）。
+   * 用于 `ConversationCreateOptions.tools` 或 `ChatOptions.tools`，注册可供 LLM 调用的工具。
+   */
+  interface ToolDefinition {
+    /** 工具唯一名称。 */
+    name: string;
+    /** 工具描述。 */
+    description: string;
+    /** 描述工具参数的 JSON Schema。 */
+    parameters: Record<string, unknown>;
+    /** LLM 调用此工具时执行的处理函数。 */
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+  }
+
+  /**
+   * 自定义命令处理器。命令以 `/` 开头（如 `/new`）。
+   * 返回字符串作为回复内容，或返回 void。
+   */
+  type CommandHandler = (args: string, conv: ConversationInstance) => Promise<string | void>;
+
+  // ---- 对话选项 ----
+
+  /** 通过 `CAT.agent.conversation.create()` 创建对话时的选项。 */
+  interface ConversationCreateOptions {
+    /** 自定义对话 ID，省略则自动生成。 */
+    id?: string;
+    /** 系统提示词。 */
+    system?: string;
+    /** 模型 ID，省略则使用默认模型。 */
+    model?: string;
+    /** 工具调用循环最大迭代次数（默认 20）。 */
+    maxIterations?: number;
+    /** 加载的 Skill：`"auto"` 加载全部已安装 Skill，或指定名称数组。 */
+    skills?: "auto" | string[];
+    /** 带内联处理函数的工具，在此对话生命周期内可用。 */
+    tools?: ToolDefinition[];
+    /**
+     * 自定义斜杠命令处理器（如 `{ "/reset": handler }`）。
+     * 内置的 `/new` 命令（清空对话）可被覆盖。
+     */
+    commands?: Record<string, CommandHandler>;
+    /**
+     * 临时模式：消息仅保留在内存中，不持久化。
+     * 不加载内置工具/Skill，脚本需自行提供所有工具。
+     */
+    ephemeral?: boolean;
+    /** 是否启用 prompt caching，默认 true。 */
+    cache?: boolean;
+  }
+
+  /** 单次 `chat()` / `chatStream()` 调用的选项。 */
+  interface ChatOptions {
+    /** 仅用于此次调用的附加工具（与对话级工具合并）。 */
+    tools?: ToolDefinition[];
+  }
+
+  // ---- 工具调用 ----
+
+  /** LLM 发起的工具调用记录。 */
+  interface ToolCallInfo {
+    /** 唯一调用 ID。 */
+    id: string;
+    /** 工具名称。 */
+    name: string;
+    /** JSON 序列化的参数。 */
+    arguments: string;
+    /** 工具执行结果（执行后填充）。 */
+    result?: string;
+    /** 调用状态。 */
+    status?: "pending" | "running" | "completed" | "error";
+  }
+
+  // ---- 聊天回复 ----
+
+  /** 非流式 `chat()` 调用的返回结果。 */
+  interface ChatReply {
+    /** 回复内容。 */
+    content: MessageContent;
+    /** 模型思考/推理文本（如有）。 */
+    thinking?: string;
+    /** 本轮中的工具调用。 */
+    toolCalls?: ToolCallInfo[];
+    /** Token 用量。 */
+    usage?: { inputTokens: number; outputTokens: number };
+    /** 当回复由命令处理器产生（而非 LLM）时为 `true`。 */
+    command?: boolean;
+  }
+
+  /** 通过 `chatStream()` 流式返回的单个数据块。 */
+  interface StreamChunk {
+    /**
+     * 数据块类型：
+     * - `"content_delta"` — 增量文本
+     * - `"thinking_delta"` — 增量思考/推理
+     * - `"tool_call"` — 工具调用事件
+     * - `"content_block"` — 完整的非文本内容块
+     * - `"done"` — 流结束
+     * - `"error"` — 发生错误
+     */
+    type: "content_delta" | "thinking_delta" | "tool_call" | "content_block" | "done" | "error";
+    /** 文本增量（用于 content_delta / thinking_delta）。 */
+    content?: string;
+    /** 完整内容块（用于 content_block）。 */
+    block?: ContentBlock;
+    /** 工具调用信息（用于 tool_call）。 */
+    toolCall?: ToolCallInfo;
+    /** Token 用量（用于 done）。 */
+    usage?: { inputTokens: number; outputTokens: number };
+    /** 错误信息（用于 error）。 */
+    error?: string;
+    /** 错误分类码：`"rate_limit"` | `"auth"` | `"tool_timeout"` | `"max_iterations"` | `"api_error"` */
+    errorCode?: string;
+    /** 当数据块由命令处理器产生时为 `true`。 */
+    command?: boolean;
+  }
+
+  // ---- 聊天消息 ----
+
+  /** 对话中持久化的聊天消息。 */
+  interface ChatMessage {
+    /** 消息 ID。 */
+    id: string;
+    /** 所属对话 ID。 */
+    conversationId: string;
+    /** 消息角色。 */
+    role: "user" | "assistant" | "system" | "tool";
+    /** 消息内容（文本或多模态）。 */
+    content: MessageContent;
+    /** 模型思考/推理块。 */
+    thinking?: { content: string };
+    /** 此消息中的工具调用。 */
+    toolCalls?: ToolCallInfo[];
+    /** 关联的 tool_call ID（用于 role="tool" 的消息）。 */
+    toolCallId?: string;
+    /** 错误信息（当轮次出错时）。 */
+    error?: string;
+    /** 生成此消息使用的模型 ID。 */
+    modelId?: string;
+    /** 此消息的 Token 用量。 */
+    usage?: {
+      inputTokens: number;
+      outputTokens: number;
+      /** Anthropic 缓存创建输入 tokens。 */
+      cacheCreationInputTokens?: number;
+      /** Anthropic 缓存读取输入 tokens。 */
+      cacheReadInputTokens?: number;
+    };
+    /** 总响应时长（毫秒）。 */
+    durationMs?: number;
+    /** 首 token 时间（毫秒）。 */
+    firstTokenMs?: number;
+    /** 父消息 ID（用于分支）。 */
+    parentId?: string;
+    /** 创建时间戳。 */
+    createtime: number;
+  }
+
+  // ---- 对话实例 ----
+
+  /**
+   * 由 `CAT.agent.conversation.create()` 或 `.get()` 返回的对话实例。
+   * 提供聊天、流式传输和管理消息历史的方法。
+   */
+  interface ConversationInstance {
+    /** 对话 ID。 */
+    readonly id: string;
+    /** 对话标题。 */
+    readonly title: string;
+    /** 使用的模型 ID。 */
+    readonly modelId: string;
+
+    /** 发送消息并等待完整回复（自动执行工具调用循环）。 */
+    chat(content: MessageContent, options?: ChatOptions): Promise<ChatReply>;
+
+    /** 发送消息并接收流式响应。 */
+    chatStream(content: MessageContent, options?: ChatOptions): Promise<AsyncIterable<StreamChunk>>;
+
+    /** 获取此对话中的所有消息。 */
+    getMessages(): Promise<ChatMessage[]>;
+
+    /** 清空此对话中的所有消息。 */
+    clear(): Promise<void>;
+
+    /** 将对话持久化到存储。 */
+    save(): Promise<void>;
+  }
+
+  // ---- 对话 API ----
+
+  /**
+   * `CAT.agent.conversation` — 创建和获取对话实例。
+   * @grant CAT.agent.conversation
+   */
+  interface ConversationAPI {
+    /** 创建新对话。 */
+    create(options?: ConversationCreateOptions): Promise<ConversationInstance>;
+
+    /** 根据 ID 获取已有对话。未找到时返回 `null`。 */
+    get(id: string): Promise<ConversationInstance | null>;
+  }
+}
+
+// ---- CAT.agent.tools — CATTool 管理 API ----
+
+/** CATTool 管理类型 — 安装、卸载、列出和调用 CATTool。 */
+declare namespace CATAgentTools {
+  /** CATTool 的参数定义。 */
+  interface CATToolParam {
+    /** 参数名称。 */
+    name: string;
+    /** 参数类型。 */
+    type: "string" | "number" | "boolean";
+    /** 是否必填。 */
+    required: boolean;
+    /** 参数描述。 */
+    description: string;
+    /** 允许的值（用于枚举参数）。 */
+    enum?: string[];
+  }
+
+  /** 持久化的 CATTool 记录。 */
+  interface CATToolRecord {
+    /** 内部 UUID。 */
+    id: string;
+    /** 工具名称（来自 `@name` 元数据）。 */
+    name: string;
+    /** 工具描述。 */
+    description: string;
+    /** 参数定义列表。 */
+    params: CATToolParam[];
+    /** 所需的 GM 权限。 */
+    grants: string[];
+    /** `@require` URL 列表。 */
+    requires?: string[];
+    /** 完整源代码（含元数据头）。 */
+    code: string;
+    /** 安装此工具的脚本 UUID。 */
+    sourceScriptUuid?: string;
+    /** 安装此工具的脚本名称。 */
+    sourceScriptName?: string;
+    /** 安装时间戳。 */
+    installtime: number;
+    /** 最后更新时间戳。 */
+    updatetime: number;
+  }
+
+  /** CATTool 摘要（不含源代码）。由 `list()` 返回。 */
+  type CATToolSummary = Omit<CATToolRecord, "code">;
+
+  /**
+   * `CAT.agent.tools` — 管理和调用 CATTool。
+   * @grant CAT.agent.tools
+   */
+  interface ToolsAPI {
+    /** 从源代码安装 CATTool。 */
+    install(code: string): Promise<CATToolRecord>;
+
+    /** 按名称卸载 CATTool。 */
+    remove(name: string): Promise<boolean>;
+
+    /** 列出所有已安装的 CATTool（不含源代码）。 */
+    list(): Promise<CATToolSummary[]>;
+
+    /** 按名称调用 CATTool，可传入参数。 */
+    call(name: string, params?: Record<string, unknown>): Promise<unknown>;
+  }
+}
+
+// ---- CAT.agent.dom — 浏览器 DOM 自动化 API ----
+
+/** DOM 自动化类型 — 与浏览器标签页、页面和元素交互。 */
+declare namespace CATAgentDom {
+  /** 浏览器标签页信息。 */
+  interface TabInfo {
+    /** 标签页 ID。 */
+    tabId: number;
+    /** 当前 URL。 */
+    url: string;
+    /** 页面标题。 */
+    title: string;
+    /** 标签页是否处于激活状态。 */
+    active: boolean;
+    /** 窗口 ID。 */
+    windowId: number;
+    /** 标签页是否已被丢弃（从内存中卸载）。 */
+    discarded: boolean;
+  }
+
+  /** DOM 操作（点击、填充等）的结果。 */
+  interface ActionResult {
+    /** 操作是否成功。 */
+    success: boolean;
+    /** 操作是否导致了导航。 */
+    navigated?: boolean;
+    /** 操作后的当前 URL。 */
+    url?: string;
+    /** 操作导致打开的新标签页。 */
+    newTab?: { tabId: number; url: string };
+  }
+
+  /** `readPage()` 返回的页面内容。 */
+  interface PageContent {
+    /** 页面标题。 */
+    title: string;
+    /** 页面 URL。 */
+    url: string;
+    /** HTML 内容（或选定的片段）。 */
+    html: string;
+    /** 内容是否因 `maxLength` 而被截断。 */
+    truncated?: boolean;
+    /** 截断前的原始总长度。 */
+    totalLength?: number;
+  }
+
+  /** `readPage()` 的选项。 */
+  interface ReadPageOptions {
+    /** 目标标签页 ID，默认为活动标签页。 */
+    tabId?: number;
+    /** 读取特定元素的 CSS 选择器。 */
+    selector?: string;
+    /** 最大内容长度（字符数）。 */
+    maxLength?: number;
+    /** 读取前要移除的标签/选择器（如 `["script", "style", "svg"]`）。 */
+    removeTags?: string[];
+  }
+
+  /** DOM 操作（点击、填充）的选项。 */
+  interface DomActionOptions {
+    /** 目标标签页 ID。 */
+    tabId?: number;
+    /** 使用可信的（CDP 派发的）事件，而非合成 JS 事件。 */
+    trusted?: boolean;
+  }
+
+  /** `screenshot()` 的选项。 */
+  interface ScreenshotOptions {
+    /** 目标标签页 ID。 */
+    tabId?: number;
+    /** JPEG 质量（0–100）。 */
+    quality?: number;
+    /** 捕获完整可滚动页面。 */
+    fullPage?: boolean;
+  }
+
+  /** `navigate()` 的选项。 */
+  interface NavigateOptions {
+    /** 目标标签页 ID。 */
+    tabId?: number;
+    /** 等待页面完全加载。 */
+    waitUntil?: boolean;
+    /** 导航超时时间（毫秒）。 */
+    timeout?: number;
+  }
+
+  /** 滚动方向。 */
+  type ScrollDirection = "up" | "down" | "top" | "bottom";
+
+  /** `scroll()` 的选项。 */
+  interface ScrollOptions {
+    /** 目标标签页 ID。 */
+    tabId?: number;
+    /** 在特定元素内滚动。 */
+    selector?: string;
+  }
+
+  /** 滚动操作的结果。 */
+  interface ScrollResult {
+    /** 当前滚动位置。 */
+    scrollTop: number;
+    /** 总可滚动高度。 */
+    scrollHeight: number;
+    /** 可见视口高度。 */
+    clientHeight: number;
+    /** 是否已滚动到底部。 */
+    atBottom: boolean;
+  }
+
+  /** `navigate()` 调用的结果。 */
+  interface NavigateResult {
+    /** 标签页 ID。 */
+    tabId: number;
+    /** 导航后的最终 URL。 */
+    url: string;
+    /** 页面标题。 */
+    title: string;
+  }
+
+  /** `waitFor()` 的选项。 */
+  interface WaitForOptions {
+    /** 目标标签页 ID。 */
+    tabId?: number;
+    /** 超时时间（毫秒）。 */
+    timeout?: number;
+  }
+
+  /** `waitFor()` 的结果。 */
+  interface WaitForResult {
+    /** 是否找到了元素。 */
+    found: boolean;
+    /** 元素详情（找到时）。 */
+    element?: {
+      selector: string;
+      tag: string;
+      text: string;
+      role?: string;
+      type?: string;
+      visible: boolean;
+    };
+  }
+
+  /** `executeScript()` 的选项。 */
+  interface ExecuteScriptOptions {
+    /** 目标标签页 ID。 */
+    tabId?: number;
+  }
+
+  /** `stopMonitor()` 的结果 — 监控期间收集的 DOM 变更。 */
+  interface MonitorResult {
+    /** 监控期间捕获的对话框。 */
+    dialogs: Array<{ type: string; message: string }>;
+    /** 监控期间新增的 DOM 节点。 */
+    addedNodes: Array<{ tag: string; id?: string; class?: string; role?: string; text: string }>;
+  }
+
+  /** `peekMonitor()` 的结果 — 正在监控的 DOM 变更摘要。 */
+  interface MonitorStatus {
+    /** 是否检测到变更。 */
+    hasChanges: boolean;
+    /** 捕获的对话框数量。 */
+    dialogCount: number;
+    /** 捕获的新增 DOM 节点数量。 */
+    nodeCount: number;
+  }
+
+  /**
+   * `CAT.agent.dom` — 浏览器标签页和 DOM 自动化。
+   * @grant CAT.agent.dom
+   */
+  interface DomAPI {
+    /** 列出所有打开的浏览器标签页。 */
+    listTabs(): Promise<TabInfo[]>;
+
+    /** 导航标签页到指定 URL。 */
+    navigate(url: string, options?: NavigateOptions): Promise<NavigateResult>;
+
+    /** 读取页面的 HTML 内容（或选定元素）。 */
+    readPage(options?: ReadPageOptions): Promise<PageContent>;
+
+    /** 截取标签页的屏幕截图。返回 base64 编码的 data URL。 */
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+
+    /** 点击匹配 CSS 选择器的元素。 */
+    click(selector: string, options?: DomActionOptions): Promise<ActionResult>;
+
+    /** 向匹配 CSS 选择器的输入框/文本域填入指定值。 */
+    fill(selector: string, value: string, options?: DomActionOptions): Promise<ActionResult>;
+
+    /** 滚动页面或元素。 */
+    scroll(direction: ScrollDirection, options?: ScrollOptions): Promise<ScrollResult>;
+
+    /** 等待匹配 CSS 选择器的元素出现。 */
+    waitFor(selector: string, options?: WaitForOptions): Promise<WaitForResult>;
+
+    /** 在页面上下文中执行 JavaScript 代码。 */
+    executeScript(code: string, options?: ExecuteScriptOptions): Promise<unknown>;
+
+    /** 开始监控标签页上的 DOM 变更（对话框、新增节点）。 */
+    startMonitor(tabId: number): Promise<void>;
+
+    /** 停止监控并返回收集到的变更（对话框、新增节点）。 */
+    stopMonitor(tabId: number): Promise<MonitorResult>;
+
+    /** 查看标签页的当前监控状态。 */
+    peekMonitor(tabId: number): Promise<MonitorStatus>;
+  }
+}
+
+// ---- CAT.agent.task — 定时任务 API ----
+
+/** 定时任务类型 — 创建基于 cron 的任务，运行 Agent 对话或发出事件。 */
+declare namespace CATAgentTask {
+  /** 定时 Agent 任务记录。 */
+  interface AgentTask {
+    /** 任务 ID。 */
+    id: string;
+    /** 任务名称。 */
+    name: string;
+    /** Cron 表达式。 */
+    crontab: string;
+    /**
+     * 执行模式：
+     * - `"internal"` — Service Worker 自动运行 LLM 对话。
+     * - `"event"` — 通过 `addListener` 通知脚本。
+     */
+    mode: "internal" | "event";
+    /** 任务是否启用。 */
+    enabled: boolean;
+    /** 触发时是否显示浏览器通知。 */
+    notify: boolean;
+
+    // --- internal 模式字段 ---
+    /** 每次触发时发送的提示词。 */
+    prompt?: string;
+    /** 使用的模型 ID。 */
+    modelId?: string;
+    /** 要续接的已有对话 ID。 */
+    conversationId?: string;
+    /** 加载的 Skill。 */
+    skills?: "auto" | string[];
+    /** 工具调用最大迭代次数（默认 10）。 */
+    maxIterations?: number;
+
+    // --- event 模式字段 ---
+    /** 创建此任务的脚本 UUID。 */
+    sourceScriptUuid?: string;
+
+    // --- 运行状态 ---
+    /** 上次运行时间戳。 */
+    lastruntime?: number;
+    /** 下次计划运行时间戳。 */
+    nextruntime?: number;
+    /** 上次运行结果状态。 */
+    lastRunStatus?: "success" | "error";
+    /** 上次运行错误信息。 */
+    lastRunError?: string;
+    /** 创建时间戳。 */
+    createtime: number;
+    /** 最后更新时间戳。 */
+    updatetime: number;
+  }
+
+  /** 任务触发时通过 `addListener` 回调传递的事件载荷。 */
+  interface AgentTaskTrigger {
+    /** 任务 ID。 */
+    taskId: string;
+    /** 任务名称。 */
+    name: string;
+    /** Cron 表达式。 */
+    crontab: string;
+    /** 触发时间戳。 */
+    triggeredAt: number;
+  }
+
+  /** 创建新任务的选项（系统自动填充的字段已省略）。 */
+  type AgentTaskCreateOptions = Omit<
+    AgentTask,
+    "id" | "createtime" | "updatetime" | "nextruntime" | "sourceScriptUuid"
+  >;
+
+  /**
+   * `CAT.agent.task` — 创建和管理定时 Agent 任务。
+   * @grant CAT.agent.task
+   */
+  interface TaskAPI {
+    /** 创建新的定时任务。 */
+    create(options: AgentTaskCreateOptions): Promise<AgentTask>;
+
+    /** 列出所有任务。 */
+    list(): Promise<AgentTask[]>;
+
+    /** 根据 ID 获取任务。 */
+    get(id: string): Promise<AgentTask | undefined>;
+
+    /** 更新任务。 */
+    update(id: string, task: Partial<AgentTask>): Promise<AgentTask>;
+
+    /** 根据 ID 删除任务。 */
+    remove(id: string): Promise<boolean>;
+
+    /** 立即触发任务（不受 cron 计划限制）。 */
+    runNow(id: string): Promise<void>;
+
+    /**
+     * 监听任务触发事件（用于 `mode: "event"` 的任务）。
+     * 返回监听器 ID，可用于后续移除。
+     */
+    addListener(taskId: string, callback: (trigger: AgentTaskTrigger) => void): number;
+
+    /** 移除之前注册的监听器。 */
+    removeListener(listenerId: number): void;
+  }
+}
+
+// ---- CAT.agent.skills — Skill 管理 API ----
+
+/** Skill 管理类型 — 安装、卸载和查询 Agent Skill。 */
+declare namespace CATAgentSkills {
+  /** 已安装 Skill 的摘要信息。 */
+  interface SkillSummary {
+    /** Skill 名称。 */
+    name: string;
+    /** Skill 描述。 */
+    description: string;
+    /** 此 Skill 中打包的 CATTool 名称（来自 `scripts/` 目录）。 */
+    toolNames: string[];
+    /** 参考资料名称（来自 `references/` 目录）。 */
+    referenceNames: string[];
+    /** 此 Skill 是否声明了配置字段。 */
+    hasConfig?: boolean;
+    /** 安装时间戳。 */
+    installtime: number;
+    /** 最后更新时间戳。 */
+    updatetime: number;
+  }
+
+  /** SKILL.md frontmatter 中声明的配置字段定义。 */
+  interface SkillConfigField {
+    /** 显示标题。 */
+    title: string;
+    /** 控件类型。 */
+    type: "text" | "number" | "select" | "switch";
+    /** 值是否应被掩码显示（如 API 密钥）。 */
+    secret?: boolean;
+    /** 是否必填。 */
+    required?: boolean;
+    /** 默认值。 */
+    default?: unknown;
+    /** 允许的值（用于 `select` 类型）。 */
+    values?: string[];
+  }
+
+  /** 包含 prompt 和配置模式的完整 Skill 记录。 */
+  interface SkillRecord extends SkillSummary {
+    /** SKILL.md 正文（去除 frontmatter 后的 markdown）。 */
+    prompt: string;
+    /** 来自 SKILL.md frontmatter 的配置模式。 */
+    config?: Record<string, SkillConfigField>;
+  }
+
+  /**
+   * `CAT.agent.skills` — 管理 Agent Skill（打包的提示词 + 工具 + 参考资料）。
+   * @grant CAT.agent.skills
+   */
+  interface SkillsAPI {
+    /** 列出所有已安装的 Skill。 */
+    list(): Promise<SkillSummary[]>;
+
+    /** 根据名称获取 Skill 的完整详情。未找到时返回 `null`。 */
+    get(name: string): Promise<SkillRecord | null>;
+
+    /**
+     * 从 SKILL.md 字符串安装 Skill，可附带打包的脚本和参考资料。
+     * @param skillMd - SKILL.md 内容（含 YAML frontmatter）。
+     * @param scripts - 要打包的 CATTool 脚本。
+     * @param references - 要打包的参考资料。
+     */
+    install(
+      skillMd: string,
+      scripts?: Array<{ name: string; code: string }>,
+      references?: Array<{ name: string; content: string }>
+    ): Promise<SkillRecord>;
+
+    /** 根据名称卸载 Skill。 */
+    remove(name: string): Promise<boolean>;
+  }
+}
+
+// ---- CAT 全局对象 ----
+
+/**
+ * ScriptCat Agent 全局对象 — 提供对话、工具、DOM、任务和 Skill API 的访问。
+ * 每个子 API 需要各自的 `@grant` 声明。
+ */
+declare const CAT: {
+  agent: {
+    /** @grant CAT.agent.conversation */
+    conversation: CATAgent.ConversationAPI;
+    /** @grant CAT.agent.tools */
+    tools: CATAgentTools.ToolsAPI;
+    /** @grant CAT.agent.dom */
+    dom: CATAgentDom.DomAPI;
+    /** @grant CAT.agent.task */
+    task: CATAgentTask.TaskAPI;
+    /** @grant CAT.agent.skills */
+    skills: CATAgentSkills.SkillsAPI;
+  };
+};
+
+/**
+ * Skill 配置值，运行时注入到 CATTool 沙箱中。
+ *
+ * 在 SKILL.md frontmatter 的 `config` 块中声明，由用户在 Skill 设置 UI 中填写。
+ * 注入时对象已被冻结，属性为只读。
+ */
+declare const CAT_CONFIG: Readonly<Record<string, unknown>>;
diff --git a/tests/pages/popup/App.test.tsx b/tests/pages/popup/App.test.tsx
index fa1bde6e7..0d7f59d60 100644
--- a/tests/pages/popup/App.test.tsx
+++ b/tests/pages/popup/App.test.tsx
@@ -72,10 +72,15 @@ vi.mock("@App/pkg/utils/utils", () => ({
     title: "Example",
   }),
   BrowserType: {
-    Chrome: "chrome",
-    Firefox: "firefox",
-    Edge: "edge",
+    Edge: 2,
+    Chrome: 1,
+    noUserScriptsAPI: 64,
+    guardedByDeveloperMode: 128,
+    guardedByAllowScript: 256,
+    Mouse: 1,
+    Touch: 2,
   },
+  isPermissionOk: vi.fn(async (_s: string) => true),
 }));
 
 vi.mock("@App/locales/locales", () => ({
diff --git a/tsconfig.json b/tsconfig.json
index 4cb3f3dc7..fdcfc724a 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,11 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2022",
-    "lib": [
-      "DOM",
-      "ES2022",
-      "WebWorker"
-    ],
+    "lib": ["DOM", "ES2022", "WebWorker"],
     "module": "nodenext",
     "jsx": "react-jsx",
     "strict": true,
@@ -20,25 +16,15 @@
     "allowImportingTsExtensions": true,
     "baseUrl": ".",
     "paths": {
-      "@App/*": [
-        "src/*"
-      ],
-      "@Packages/*": [
-        "packages/*"
-      ],
-      "@Tests/*": [
-        "tests/*"
-      ]
+      "@App/*": ["src/*"],
+      "@Packages/*": ["packages/*"],
+      "@Tests/*": ["tests/*"]
     }
   },
-  "include": [
-    "src",
-    "packages",
-    "tests"
-  ],
+  "include": ["src", "packages", "tests"],
   "ts-node": {
     "compilerOptions": {
       "module": "CommonJS"
     }
   }
-}
\ No newline at end of file
+}
diff --git a/vitest.config.ts b/vitest.config.ts
index 303e19862..91493ccc8 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -25,9 +25,9 @@ export default defineConfig({
   ],
   test: {
     environment: "jsdom",
-    exclude: ["e2e/**", "node_modules/**", ".claude/**"],
     // List setup file
     setupFiles: ["./tests/vitest.setup.ts"],
+    exclude: ["**/node_modules/**", "**/.claude/**", "e2e/**"],
     env: {
       VI_TESTING: "true",
       SC_RANDOM_KEY: "005a7deb-3a6e-4337-83ea-b9626c02ea38",