fix: update zod import to use namespace import

* 🐛 fix: guard webview search against destroyed webviews

* delete code

* delete code

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+/src/renderer/src/store/ @0xfullex
+/src/main/services/ConfigManager.ts @0xfullex
+/packages/shared/IpcChannel.ts @0xfullex
+/src/main/ipc.ts @0xfullex

.github/ISSUE_TEMPLATE/#0_bug_report.yml

@@ -1,94 +0,0 @@
-name: 🐛 错误报告 (中文)
-description: 创建一个报告以帮助我们改进
-title: '[错误]: '
-labels: ['BUG']
-body:
-  - type: markdown
-    attributes:
-      value: |
-        感谢您花时间填写此错误报告！
-        在提交此问题之前，请确保您已经了解了[常见问题](https://docs.cherry-ai.com/question-contact/questions)和[知识科普](https://docs.cherry-ai.com/question-contact/knowledge)
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: 提交前检查
-      description: |
-        在提交 Issue 前请确保您已经完成了以下所有步骤
-      options:
-        - label: 我理解 Issue 是用于反馈和解决问题的，而非吐槽评论区，将尽可能提供更多信息帮助问题解决。
-          required: true
-        - label: 我的问题不是 [常见问题](https://github.com/CherryHQ/cherry-studio/issues/3881) 中的内容。
-          required: true
-        - label: 我已经查看了 **置顶 Issue** 并搜索了现有的 [开放Issue](https://github.com/CherryHQ/cherry-studio/issues)和[已关闭Issue](https://github.com/CherryHQ/cherry-studio/issues?q=is%3Aissue%20state%3Aclosed%20)，没有找到类似的问题。
-          required: true
-        - label: 我填写了简短且清晰明确的标题，以便开发者在翻阅 Issue 列表时能快速确定大致问题。而不是“一个建议”、“卡住了”等。
-          required: true
-        - label: 我确认我正在使用最新版本的 Cherry Studio。
-          required: true
-
-  - type: dropdown
-    id: platform
-    attributes:
-      label: 平台
-      description: 您正在使用哪个平台？
-      options:
-        - Windows
-        - macOS
-        - Linux
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: 版本
-      description: 您正在运行的 Cherry Studio 版本是什么？
-      placeholder: 例如 v1.0.0
-    validations:
-      required: true
-
-  - type: textarea
-    id: description
-    attributes:
-      label: 错误描述
-      description: 描述问题时请尽可能详细。请尽可能提供截图或屏幕录制，以帮助我们更好地理解问题。
-      placeholder: 告诉我们发生了什么...(记得附上截图/录屏，如果适用)
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: 重现步骤
-      description: 提供详细的重现步骤，以便于我们的开发人员可以准确地重现问题。请尽可能为每个步骤提供截图或屏幕录制。
-      placeholder: |
-        1. 转到 '...'
-        2. 点击 '....'
-        3. 向下滚动到 '....'
-        4. 看到错误
-
-        记得尽可能为每个步骤附上截图/录屏！
-    validations:
-      required: true
-
-  - type: textarea
-    id: expected
-    attributes:
-      label: 预期行为
-      description: 清晰简洁地描述您期望发生的事情
-    validations:
-      required: true
-
-  - type: textarea
-    id: logs
-    attributes:
-      label: 相关日志输出
-      description: 请复制并粘贴任何相关的日志输出
-      render: shell
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: 附加信息
-      description: 任何能让我们对你所遇到的问题有更多了解的东西

.github/ISSUE_TEMPLATE/#1_feature_request.yml

@@ -1,76 +0,0 @@
-name: 💡 功能建议 (中文)
-description: 为项目提出新的想法
-title: '[功能]: '
-labels: ['feature']
-body:
-  - type: markdown
-    attributes:
-      value: |
-        感谢您花时间提出新的功能建议!
-        在提交此问题之前，请确保您已经了解了[项目规划](https://docs.cherry-ai.com/cherrystudio/planning)和[功能介绍](https://docs.cherry-ai.com/cherrystudio/preview)
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: 提交前检查
-      description: |
-        在提交 Issue 前请确保您已经完成了以下所有步骤
-      options:
-        - label: 我理解 Issue 是用于反馈和解决问题的，而非吐槽评论区，将尽可能提供更多信息帮助问题解决。
-          required: true
-        - label: 我已经查看了置顶 Issue 并搜索了现有的 [开放Issue](https://github.com/CherryHQ/cherry-studio/issues)和[已关闭Issue](https://github.com/CherryHQ/cherry-studio/issues?q=is%3Aissue%20state%3Aclosed%20)，没有找到类似的建议。
-          required: true
-        - label: 我填写了简短且清晰明确的标题，以便开发者在翻阅 Issue 列表时能快速确定大致问题。而不是“一个建议”、“卡住了”等。
-          required: true
-        - label: 最新的 Cherry Studio 版本没有实现我所提出的功能。
-          required: true
-
-  - type: dropdown
-    id: platform
-    attributes:
-      label: 平台
-      description: 您正在使用哪个平台？
-      options:
-        - Windows
-        - macOS
-        - Linux
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: 版本
-      description: 您正在运行的 Cherry Studio 版本是什么？
-      placeholder: 例如 v1.0.0
-    validations:
-      required: true
-
-  - type: textarea
-    id: problem
-    attributes:
-      label: 您的功能建议是否与某个问题/issue相关?
-      description: 请简明扼要地描述您遇到的问题
-      placeholder: 我总是感到沮丧,因为...
-    validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: 请描述您希望实现的解决方案
-      description: 请简明扼要地描述您希望发生的情况
-    validations:
-      required: true
-
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: 请描述您考虑过的其他方案
-      description: 请简明扼要地描述您考虑过的任何其他解决方案或功能
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: 其他补充信息
-      description: 在此添加任何其他与功能建议相关的上下文或截图

.github/ISSUE_TEMPLATE/#2_question.yml

@@ -1,77 +0,0 @@
-name: ❓ 提问 & 讨论 (中文)
-description: 寻求帮助、讨论问题、提出疑问等...
-title: '[讨论]: '
-labels: ['discussion', 'help wanted']
-body:
-  - type: markdown
-    attributes:
-      value: |
-        感谢您的提问！请尽可能详细地描述您的问题，这样我们才能更好地帮助您。
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: Issue 检查清单
-      description: |
-        在提交 Issue 前请确保您已经完成了以下所有步骤
-      options:
-        - label: 我理解 Issue 是用于反馈和解决问题的，而非吐槽评论区，将尽可能提供更多信息帮助问题解决。
-          required: true
-        - label: 我确认自己需要的是提出问题并且讨论问题，而不是 Bug 反馈或需求建议。
-          required: true
-
-  - type: dropdown
-    id: platform
-    attributes:
-      label: 平台
-      description: 您正在使用哪个平台？
-      options:
-        - Windows
-        - macOS
-        - Linux
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: 版本
-      description: 您正在运行的 Cherry Studio 版本是什么？
-      placeholder: 例如 v1.0.0
-    validations:
-      required: true
-
-  - type: textarea
-    id: question
-    attributes:
-      label: 您的问题
-      description: 请详细描述您的问题
-      placeholder: 请尽可能清楚地说明您的问题...
-    validations:
-      required: true
-
-  - type: textarea
-    id: context
-    attributes:
-      label: 相关背景
-      description: 请提供一些背景信息，帮助我们更好地理解您的问题
-      placeholder: 例如：使用场景、已尝试的解决方案等
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: 补充信息
-      description: 任何其他相关的信息、截图或代码示例
-      render: shell
-
-  - type: dropdown
-    id: priority
-    attributes:
-      label: 优先级
-      description: 这个问题对您来说有多紧急？
-      options:
-        - 低 (有空再看)
-        - 中 (希望尽快得到答复)
-        - 高 (阻碍工作进行)
-    validations:
-      required: true

.github/ISSUE_TEMPLATE/#3_others.yml

@@ -1,76 +0,0 @@
-name: 🤔 其他问题 (中文)
-description: 提交不属于错误报告或功能需求的问题
-title: '[其他]: '
-body:
-  - type: markdown
-    attributes:
-      value: |
-        感谢您花时间提出问题！
-        在提交此问题之前，请确保您已经了解了[常见问题](https://docs.cherry-ai.com/question-contact/questions)和[知识科普](https://docs.cherry-ai.com/question-contact/knowledge)
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: 提交前检查
-      description: |
-        在提交 Issue 前请确保您已经完成了以下所有步骤
-      options:
-        - label: 我理解 Issue 是用于反馈和解决问题的，而非吐槽评论区，将尽可能提供更多信息帮助问题解决。
-          required: true
-        - label: 我已经查看了置顶 Issue 并搜索了现有的 [开放Issue](https://github.com/CherryHQ/cherry-studio/issues)和[已关闭Issue](https://github.com/CherryHQ/cherry-studio/issues?q=is%3Aissue%20state%3Aclosed%20)，没有找到类似的问题。
-          required: true
-        - label: 我填写了简短且清晰明确的标题，以便开发者在翻阅 Issue 列表时能快速确定大致问题。而不是"一个问题"、"求助"等。
-          required: true
-        - label: 我的问题不属于错误报告或功能需求类别。
-          required: true
-
-  - type: dropdown
-    id: platform
-    attributes:
-      label: 平台
-      description: 您正在使用哪个平台？
-      options:
-        - Windows
-        - macOS
-        - Linux
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: 版本
-      description: 您正在运行的 Cherry Studio 版本是什么？
-      placeholder: 例如 v1.0.0
-    validations:
-      required: true
-
-  - type: textarea
-    id: question
-    attributes:
-      label: 问题描述
-      description: 请详细描述您的问题或疑问
-      placeholder: 我想了解有关...的更多信息
-    validations:
-      required: true
-
-  - type: textarea
-    id: context
-    attributes:
-      label: 相关背景
-      description: 请提供与您的问题相关的任何背景信息或上下文
-      placeholder: 我尝试实现...时遇到了疑问
-    validations:
-      required: true
-
-  - type: textarea
-    id: attempts
-    attributes:
-      label: 您已尝试的方法
-      description: 请描述您为解决问题已经尝试过的方法（如果有）
-
-  - type: textarea
-    id: additional
-    attributes:
-      label: 附加信息
-      description: 任何能让我们对您的问题有更多了解的信息，包括截图或相关链接

.github/workflows/auto-i18n.yml

@@ -0,0 +1,66 @@
+name: Auto I18N
+
+env:
+  API_KEY: ${{ secrets.TRANSLATE_API_KEY }}
+  MODEL: ${{ vars.AUTO_I18N_MODEL || 'deepseek/deepseek-v3.1'}}
+  BASE_URL: ${{ vars.AUTO_I18N_BASE_URL || 'https://api.ppinfra.com/openai'}}
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
+jobs:
+  auto-i18n:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == 'CherryHQ/cherry-studio'
+    name: Auto I18N
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: 🐈‍⬛ Checkout
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - name: 📦 Setting Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies in isolated directory
+        run: |
+          # 在临时目录安装依赖
+          mkdir -p /tmp/translation-deps
+          cd /tmp/translation-deps
+          echo '{"dependencies": {"openai": "^5.12.2", "cli-progress": "^3.12.0", "tsx": "^4.20.3", "@biomejs/biome": "2.2.4"}}' > package.json
+          npm install --no-package-lock
+
+          # 设置 NODE_PATH 让项目能找到这些依赖
+          echo "NODE_PATH=/tmp/translation-deps/node_modules" >> $GITHUB_ENV
+
+      - name: 🏃‍♀️ Translate
+        run: npx tsx scripts/auto-translate-i18n.ts
+
+      - name: 🔍 Format
+        run: cd /tmp/translation-deps && npx biome format --config-path /home/runner/work/cherry-studio/cherry-studio/biome.jsonc --write /home/runner/work/cherry-studio/cherry-studio/src/renderer/src/i18n/
+
+      - name: 🔄 Commit changes
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git reset -- package.json yarn.lock  # 不提交 package.json 和 yarn.lock 的更改
+          if git diff --cached --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "fix(i18n): Auto update translations for PR #${{ github.event.pull_request.number }}"
+          fi
+
+      - name: 🚀 Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.event.pull_request.head.ref }}

.github/workflows/claude-code-review.yml

@@ -0,0 +1,56 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Only trigger code review for PRs from the main repository due to upstream OIDC issues
+    # https://github.com/anthropics/claude-code-action/issues/542
+    if: |
+      (github.event.pull_request.head.repo.full_name == github.repository) &&
+      (github.event.pull_request.draft == false)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+      actions: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            PR number: ${{ github.event.number }}
+            Repo: ${{ github.repository }}
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

.github/workflows/claude-translator.yml

@@ -0,0 +1,112 @@
+name: Claude Translator
+concurrency:
+  group: translator-${{ github.event.comment.id || github.event.issue.number || github.event.review.id }}
+  cancel-in-progress: false
+
+on:
+  issues:
+    types: [opened]
+  issue_comment:
+    types: [created, edited]
+  pull_request_review:
+    types: [submitted, edited]
+  pull_request_review_comment:
+    types: [created, edited]
+
+jobs:
+  translate:
+    if: |
+      (github.event_name == 'issues')
+      || (github.event_name == 'issue_comment' && github.event.sender.type != 'Bot')
+      || (
+        (github.event_name == 'pull_request_review' || github.event_name == 'pull_request_review_comment')
+        && github.event.sender.type != 'Bot'
+        && github.event.pull_request.head.repo.fork == false
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write # 编辑issues/comments
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude for translation
+        uses: anthropics/claude-code-action@main
+        id: claude
+        with:
+          # Warning: Permissions should have been controlled by workflow permission.
+          # Now `contents: read` is safe for files, but we could make a fine-grained token to control it.
+          # See: https://github.com/anthropics/claude-code-action/blob/main/docs/security.md
+          github_token: ${{ secrets.TOKEN_GITHUB_WRITE }}
+          allowed_non_write_users: "*"
+          anthropic_api_key: ${{ secrets.CLAUDE_TRANSLATOR_APIKEY }}
+          claude_args: "--allowed-tools Bash(gh issue:*),Bash(gh api:repos/*/issues:*),Bash(gh api:repos/*/pulls/*/reviews/*),Bash(gh api:repos/*/pulls/comments/*)"
+          prompt: |
+            你是一个多语言翻译助手。你需要响应 GitHub Webhooks 中的以下四种事件：
+
+            - issues
+            - issue_comment
+            - pull_request_review
+            - pull_request_review_comment
+
+            请完成以下任务：
+
+            1. 获取当前事件的完整信息。
+
+               - 如果当前事件是 issues，就获取该 issues 的信息。
+               - 如果当前事件是 issue_comment，就获取该 comment 的信息。
+               - 如果当前事件是 pull_request_review，就获取该 review 的信息。
+               - 如果当前事件是 pull_request_review_comment，就获取该 comment 的信息。
+
+            2. 智能检测内容。
+
+                - 如果获取到的信息是已经遵循格式要求翻译过的内容，则检查翻译内容和原始内容是否匹配。若不匹配，则重新翻译一次令其匹配，并遵循格式要求；
+                - 如果获取到的信息是未翻译过的内容，检查其内容语言。若不是英文，则翻译成英文；
+                - 如果获取到的信息是部分翻译为英文的内容，则将其翻译为英文；
+                - 如果获取到的信息包含了对已翻译内容的引用，则将引用内容清理为仅含英文的内容。引用的内容不能够包含"This xxx was translated by Claude"和"Original Content`等内容。
+                - 如果获取到的信息包含了其他类型的引用，即对非 Claude 翻译的内容的引用，则直接照原样引用，不进行翻译。
+                - 如果获取到的信息是通过邮件回复的内容，则在翻译时应当将邮件内容的引用放到最后。在原始内容和翻译内容中只需要回复的内容本身，不要包含对邮件内容的引用。
+                - 如果获取到的信息本身不需要任何处理，则跳过任务。
+
+            3. 格式要求：
+
+               - 标题：英文翻译（如果非英文）
+               - 内容格式：
+                 > [!NOTE]
+                 > This issue/comment/review was translated by Claude.
+
+                 [翻译内容]
+
+                 ---
+                 <details>
+                 <summary>Original Content</summary>
+                 [原始内容]
+                 </details>
+
+            4. 使用gh工具更新：
+
+               - 根据环境信息中的Event类型选择正确的命令：
+                 - 如果 Event 是 'issues': gh issue edit [ISSUE_NUMBER] --title "[英文标题]" --body "[翻译内容 + 原始内容]"
+                 - 如果 Event 是 'issue_comment': gh api -X PATCH /repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }} -f body="[翻译内容 + 原始内容]"
+                 - 如果 Event 是 'pull_request_review': gh api -X PUT /repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews/${{ github.event.review.id }} -f body="[翻译内容]"
+                 - 如果 Event 是 'pull_request_review_comment': gh api -X PATCH /repos/${{ github.repository }}/pulls/comments/${{ github.event.comment.id }} -f body="[翻译内容 + 原始内容]"
+
+            环境信息：
+            - Event: ${{ github.event_name }}
+            - Issue Number: ${{ github.event.issue.number }}
+            - Repository: ${{ github.repository }}
+            - (Review) Comment ID: ${{ github.event.comment.id || 'N/A' }}
+            - Pull Request Number: ${{ github.event.pull_request.number || 'N/A' }}
+            - Review ID: ${{ github.event.review.id || 'N/A' }}
+
+
+            使用以下命令获取完整信息：
+            gh issue view ${{ github.event.issue.number }} --json title,body,comments
+        env:
+          ANTHROPIC_BASE_URL: ${{ secrets.CLAUDE_TRANSLATOR_BASEURL }}

.github/workflows/claude.yml

@@ -0,0 +1,60 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment'
+        && contains(github.event.comment.body, '@claude')
+        && contains(fromJSON('["COLLABORATOR","MEMBER","OWNER"]'), github.event.comment.author_association))
+      ||
+      (github.event_name == 'pull_request_review_comment'
+        && contains(github.event.comment.body, '@claude')
+        && contains(fromJSON('["COLLABORATOR","MEMBER","OWNER"]'), github.event.comment.author_association))
+      ||
+      (github.event_name == 'pull_request_review'
+        && contains(github.event.review.body, '@claude')
+        && contains(fromJSON('["COLLABORATOR","MEMBER","OWNER"]'), github.event.review.author_association))
+      ||
+      (github.event_name == 'issues'
+        && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))
+        && contains(fromJSON('["COLLABORATOR","MEMBER","OWNER"]'), github.event.issue.author_association))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
+          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'

.github/workflows/delete-branch.yml

@@ -0,0 +1,22 @@
+name: Delete merged branch
+on:
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  delete-branch:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    if: github.event.pull_request.merged == true && github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Delete merged branch
+        uses: actions/github-script@v8
+        with:
+          script: |
+            github.rest.git.deleteRef({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              ref: `heads/${context.payload.pull_request.head.ref}`,
+            })

.github/workflows/nightly-build.yml

@@ -56,7 +56,7 @@ jobs:
           ref: main
 
       - name: Install Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 20
 
@@ -98,10 +98,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_OPTIONS: --max-old-space-size=8192
-          MAIN_VITE_CHERRYIN_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYIN_CLIENT_SECRET }}
-          MAIN_VITE_MINERU_API_KEY: ${{ vars.MAIN_VITE_MINERU_API_KEY }}
-          RENDERER_VITE_AIHUBMIX_SECRET: ${{ vars.RENDERER_VITE_AIHUBMIX_SECRET }}
-          RENDERER_VITE_PPIO_APP_SECRET: ${{ vars.RENDERER_VITE_PPIO_APP_SECRET }}
+          MAIN_VITE_CHERRYAI_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYAI_CLIENT_SECRET }}
+          MAIN_VITE_MINERU_API_KEY: ${{ secrets.MAIN_VITE_MINERU_API_KEY }}
+          RENDERER_VITE_AIHUBMIX_SECRET: ${{ secrets.RENDERER_VITE_AIHUBMIX_SECRET }}
+          RENDERER_VITE_PPIO_APP_SECRET: ${{ secrets.RENDERER_VITE_PPIO_APP_SECRET }}
 
       - name: Build Mac
         if: matrix.os == 'macos-latest'
@@ -110,15 +110,15 @@ jobs:
         env:
           CSC_LINK: ${{ secrets.CSC_LINK }}
           CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ vars.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ vars.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ vars.APPLE_TEAM_ID }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_OPTIONS: --max-old-space-size=8192
-          MAIN_VITE_CHERRYIN_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYIN_CLIENT_SECRET }}
-          MAIN_VITE_MINERU_API_KEY: ${{ vars.MAIN_VITE_MINERU_API_KEY }}
-          RENDERER_VITE_AIHUBMIX_SECRET: ${{ vars.RENDERER_VITE_AIHUBMIX_SECRET }}
-          RENDERER_VITE_PPIO_APP_SECRET: ${{ vars.RENDERER_VITE_PPIO_APP_SECRET }}
+          MAIN_VITE_CHERRYAI_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYAI_CLIENT_SECRET }}
+          MAIN_VITE_MINERU_API_KEY: ${{ secrets.MAIN_VITE_MINERU_API_KEY }}
+          RENDERER_VITE_AIHUBMIX_SECRET: ${{ secrets.RENDERER_VITE_AIHUBMIX_SECRET }}
+          RENDERER_VITE_PPIO_APP_SECRET: ${{ secrets.RENDERER_VITE_PPIO_APP_SECRET }}
 
       - name: Build Windows
         if: matrix.os == 'windows-latest'
@@ -127,10 +127,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_OPTIONS: --max-old-space-size=8192
-          MAIN_VITE_CHERRYIN_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYIN_CLIENT_SECRET }}
-          MAIN_VITE_MINERU_API_KEY: ${{ vars.MAIN_VITE_MINERU_API_KEY }}
-          RENDERER_VITE_AIHUBMIX_SECRET: ${{ vars.RENDERER_VITE_AIHUBMIX_SECRET }}
-          RENDERER_VITE_PPIO_APP_SECRET: ${{ vars.RENDERER_VITE_PPIO_APP_SECRET }}
+          MAIN_VITE_CHERRYAI_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYAI_CLIENT_SECRET }}
+          MAIN_VITE_MINERU_API_KEY: ${{ secrets.MAIN_VITE_MINERU_API_KEY }}
+          RENDERER_VITE_AIHUBMIX_SECRET: ${{ secrets.RENDERER_VITE_AIHUBMIX_SECRET }}
+          RENDERER_VITE_PPIO_APP_SECRET: ${{ secrets.RENDERER_VITE_PPIO_APP_SECRET }}
 
       - name: Rename artifacts with nightly format
         shell: bash

.github/workflows/pr-ci.yml

@@ -9,19 +9,22 @@ on:
     branches:
       - main
       - develop
+      - v2
+    types: [ready_for_review, synchronize, opened]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     env:
       PRCI: true
+    if: github.event.pull_request.draft == false
 
     steps:
       - name: Check out Git repository
         uses: actions/checkout@v5
 
       - name: Install Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 20
 
@@ -48,6 +51,9 @@ jobs:
       - name: Lint Check
         run: yarn test:lint
 
+      - name: Format Check
+        run: yarn format:check
+
       - name: Type Check
         run: yarn typecheck
 

.github/workflows/release.yml

@@ -47,7 +47,7 @@ jobs:
           npm version "$VERSION" --no-git-tag-version --allow-same-version
 
       - name: Install Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 20
 
@@ -85,10 +85,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_OPTIONS: --max-old-space-size=8192
-          MAIN_VITE_CHERRYIN_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYIN_CLIENT_SECRET }}
-          MAIN_VITE_MINERU_API_KEY: ${{ vars.MAIN_VITE_MINERU_API_KEY }}
-          RENDERER_VITE_AIHUBMIX_SECRET: ${{ vars.RENDERER_VITE_AIHUBMIX_SECRET }}
-          RENDERER_VITE_PPIO_APP_SECRET: ${{ vars.RENDERER_VITE_PPIO_APP_SECRET }}
+          MAIN_VITE_CHERRYAI_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYAI_CLIENT_SECRET }}
+          MAIN_VITE_MINERU_API_KEY: ${{ secrets.MAIN_VITE_MINERU_API_KEY }}
+          RENDERER_VITE_AIHUBMIX_SECRET: ${{ secrets.RENDERER_VITE_AIHUBMIX_SECRET }}
+          RENDERER_VITE_PPIO_APP_SECRET: ${{ secrets.RENDERER_VITE_PPIO_APP_SECRET }}
 
       - name: Build Mac
         if: matrix.os == 'macos-latest'
@@ -98,15 +98,15 @@ jobs:
         env:
           CSC_LINK: ${{ secrets.CSC_LINK }}
           CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ vars.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ vars.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ vars.APPLE_TEAM_ID }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_OPTIONS: --max-old-space-size=8192
-          MAIN_VITE_CHERRYIN_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYIN_CLIENT_SECRET }}
-          MAIN_VITE_MINERU_API_KEY: ${{ vars.MAIN_VITE_MINERU_API_KEY }}
-          RENDERER_VITE_AIHUBMIX_SECRET: ${{ vars.RENDERER_VITE_AIHUBMIX_SECRET }}
-          RENDERER_VITE_PPIO_APP_SECRET: ${{ vars.RENDERER_VITE_PPIO_APP_SECRET }}
+          MAIN_VITE_CHERRYAI_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYAI_CLIENT_SECRET }}
+          MAIN_VITE_MINERU_API_KEY: ${{ secrets.MAIN_VITE_MINERU_API_KEY }}
+          RENDERER_VITE_AIHUBMIX_SECRET: ${{ secrets.RENDERER_VITE_AIHUBMIX_SECRET }}
+          RENDERER_VITE_PPIO_APP_SECRET: ${{ secrets.RENDERER_VITE_PPIO_APP_SECRET }}
 
       - name: Build Windows
         if: matrix.os == 'windows-latest'
@@ -115,10 +115,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_OPTIONS: --max-old-space-size=8192
-          MAIN_VITE_CHERRYIN_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYIN_CLIENT_SECRET }}
-          MAIN_VITE_MINERU_API_KEY: ${{ vars.MAIN_VITE_MINERU_API_KEY }}
-          RENDERER_VITE_AIHUBMIX_SECRET: ${{ vars.RENDERER_VITE_AIHUBMIX_SECRET }}
-          RENDERER_VITE_PPIO_APP_SECRET: ${{ vars.RENDERER_VITE_PPIO_APP_SECRET }}
+          MAIN_VITE_CHERRYAI_CLIENT_SECRET: ${{ secrets.MAIN_VITE_CHERRYAI_CLIENT_SECRET }}
+          MAIN_VITE_MINERU_API_KEY: ${{ secrets.MAIN_VITE_MINERU_API_KEY }}
+          RENDERER_VITE_AIHUBMIX_SECRET: ${{ secrets.RENDERER_VITE_AIHUBMIX_SECRET }}
+          RENDERER_VITE_PPIO_APP_SECRET: ${{ secrets.RENDERER_VITE_PPIO_APP_SECRET }}
 
       - name: Release
         uses: ncipollo/release-action@v1

.gitignore

@@ -37,6 +37,7 @@ dist
 out
 mcp_server
 stats.html
+.eslintcache
 
 # ENV
 .env
@@ -53,6 +54,8 @@ local
 .qwen/*
 .trae/*
 .claude-code-router/*
+.codebuddy/*
+.zed/*
 CLAUDE.local.md
 
 # vitest
@@ -68,3 +71,5 @@ playwright-report
 test-results
 
 YOUR_MEMORY_FILE_PATH
+
+.sessions/

.oxlintrc.json

@@ -0,0 +1,215 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {},
+  "env": {
+    "es2022": true
+  },
+  "globals": {},
+  "ignorePatterns": [
+    "node_modules/**",
+    "build/**",
+    "dist/**",
+    "out/**",
+    "local/**",
+    ".yarn/**",
+    ".gitignore",
+    "scripts/cloudflare-worker.js",
+    "src/main/integration/nutstore/sso/lib/**",
+    "src/main/integration/cherryai/index.js",
+    "src/main/integration/nutstore/sso/lib/**",
+    "src/renderer/src/ui/**",
+    "packages/**/dist",
+    "eslint.config.mjs"
+  ],
+  "overrides": [
+    // set different env
+    {
+      "env": {
+        "node": true
+      },
+      "files": ["src/main/**", "resources/scripts/**", "scripts/**", "playwright.config.ts", "electron.vite.config.ts"]
+    },
+    {
+      "env": {
+        "browser": true
+      },
+      "files": [
+        "src/renderer/**/*.{ts,tsx}",
+        "packages/aiCore/**",
+        "packages/extension-table-plus/**",
+        "resources/js/**"
+      ]
+    },
+    {
+      "env": {
+        "node": true,
+        "vitest": true
+      },
+      "files": ["**/__tests__/*.test.{ts,tsx}", "tests/**"]
+    },
+    {
+      "env": {
+        "browser": true,
+        "node": true
+      },
+      "files": ["src/preload/**"]
+    }
+  ],
+  // We don't use the React plugin here because its behavior differs slightly from that of ESLint's React plugin.
+  "plugins": ["unicorn", "typescript", "oxc", "import"],
+  "rules": {
+    "constructor-super": "error",
+    "for-direction": "error",
+    "getter-return": "error",
+    "no-array-constructor": "off",
+    // "import/no-cycle": "error", // tons of error, bro
+    "no-async-promise-executor": "error",
+    "no-caller": "warn",
+    "no-case-declarations": "error",
+    "no-class-assign": "error",
+    "no-compare-neg-zero": "error",
+    "no-cond-assign": "error",
+    "no-const-assign": "error",
+    "no-constant-binary-expression": "error",
+    "no-constant-condition": "error",
+    "no-control-regex": "error",
+    "no-debugger": "error",
+    "no-delete-var": "error",
+    "no-dupe-args": "error",
+    "no-dupe-class-members": "error",
+    "no-dupe-else-if": "error",
+    "no-dupe-keys": "error",
+    "no-duplicate-case": "error",
+    "no-empty": "error",
+    "no-empty-character-class": "error",
+    "no-empty-pattern": "error",
+    "no-empty-static-block": "error",
+    "no-eval": "warn",
+    "no-ex-assign": "error",
+    "no-extra-boolean-cast": "error",
+    "no-fallthrough": "warn",
+    "no-func-assign": "error",
+    "no-global-assign": "error",
+    "no-import-assign": "error",
+    "no-invalid-regexp": "error",
+    "no-irregular-whitespace": "error",
+    "no-loss-of-precision": "error",
+    "no-misleading-character-class": "error",
+    "no-new-native-nonconstructor": "error",
+    "no-nonoctal-decimal-escape": "error",
+    "no-obj-calls": "error",
+    "no-octal": "error",
+    "no-prototype-builtins": "error",
+    "no-redeclare": "error",
+    "no-regex-spaces": "error",
+    "no-self-assign": "error",
+    "no-setter-return": "error",
+    "no-shadow-restricted-names": "error",
+    "no-sparse-arrays": "error",
+    "no-this-before-super": "error",
+    "no-unassigned-vars": "warn",
+    "no-undef": "error",
+    "no-unexpected-multiline": "error",
+    "no-unreachable": "error",
+    "no-unsafe-finally": "error",
+    "no-unsafe-negation": "error",
+    "no-unsafe-optional-chaining": "error",
+    "no-unused-expressions": "off", // this rule disallow us to use expression to call function, like `condition && fn()`
+    "no-unused-labels": "error",
+    "no-unused-private-class-members": "error",
+    "no-unused-vars": ["warn", { "caughtErrors": "none" }],
+    "no-useless-backreference": "error",
+    "no-useless-catch": "error",
+    "no-useless-escape": "error",
+    "no-useless-rename": "warn",
+    "no-with": "error",
+    "oxc/bad-array-method-on-arguments": "warn",
+    "oxc/bad-char-at-comparison": "warn",
+    "oxc/bad-comparison-sequence": "warn",
+    "oxc/bad-min-max-func": "warn",
+    "oxc/bad-object-literal-comparison": "warn",
+    "oxc/bad-replace-all-arg": "warn",
+    "oxc/const-comparisons": "warn",
+    "oxc/double-comparisons": "warn",
+    "oxc/erasing-op": "warn",
+    "oxc/missing-throw": "warn",
+    "oxc/number-arg-out-of-range": "warn",
+    "oxc/only-used-in-recursion": "off", // manually off bacause of existing warning. may turn it on in the future
+    "oxc/uninvoked-array-callback": "warn",
+    "require-yield": "error",
+    "typescript/await-thenable": "warn",
+    // "typescript/ban-ts-comment": "error",
+    "typescript/no-array-constructor": "error",
+    // "typescript/consistent-type-imports": "error",
+    "typescript/no-array-delete": "warn",
+    "typescript/no-base-to-string": "warn",
+    "typescript/no-duplicate-enum-values": "error",
+    "typescript/no-duplicate-type-constituents": "warn",
+    "typescript/no-empty-object-type": "off",
+    "typescript/no-explicit-any": "off", // not safe but too many errors
+    "typescript/no-extra-non-null-assertion": "error",
+    "typescript/no-floating-promises": "warn",
+    "typescript/no-for-in-array": "warn",
+    "typescript/no-implied-eval": "warn",
+    "typescript/no-meaningless-void-operator": "warn",
+    "typescript/no-misused-new": "error",
+    "typescript/no-misused-spread": "warn",
+    "typescript/no-namespace": "error",
+    "typescript/no-non-null-asserted-optional-chain": "off", // it's off now. but may turn it on.
+    "typescript/no-redundant-type-constituents": "warn",
+    "typescript/no-require-imports": "off",
+    "typescript/no-this-alias": "error",
+    "typescript/no-unnecessary-parameter-property-assignment": "warn",
+    "typescript/no-unnecessary-type-constraint": "error",
+    "typescript/no-unsafe-declaration-merging": "error",
+    "typescript/no-unsafe-function-type": "error",
+    "typescript/no-unsafe-unary-minus": "warn",
+    "typescript/no-useless-empty-export": "warn",
+    "typescript/no-wrapper-object-types": "error",
+    "typescript/prefer-as-const": "error",
+    "typescript/prefer-namespace-keyword": "error",
+    "typescript/require-array-sort-compare": "warn",
+    "typescript/restrict-template-expressions": "warn",
+    "typescript/triple-slash-reference": "error",
+    "typescript/unbound-method": "warn",
+    "unicorn/no-await-in-promise-methods": "warn",
+    "unicorn/no-empty-file": "off", // manually off bacause of existing warning. may turn it on in the future
+    "unicorn/no-invalid-fetch-options": "warn",
+    "unicorn/no-invalid-remove-event-listener": "warn",
+    "unicorn/no-new-array": "off", // manually off bacause of existing warning. may turn it on in the future
+    "unicorn/no-single-promise-in-promise-methods": "warn",
+    "unicorn/no-thenable": "off", // manually off bacause of existing warning. may turn it on in the future
+    "unicorn/no-unnecessary-await": "warn",
+    "unicorn/no-useless-fallback-in-spread": "warn",
+    "unicorn/no-useless-length-check": "warn",
+    "unicorn/no-useless-spread": "off", // manually off bacause of existing warning. may turn it on in the future
+    "unicorn/prefer-set-size": "warn",
+    "unicorn/prefer-string-starts-ends-with": "warn",
+    "use-isnan": "error",
+    "valid-typeof": "error"
+  },
+  "settings": {
+    "jsdoc": {
+      "augmentsExtendsReplacesDocs": false,
+      "exemptDestructuredRootsFromChecks": false,
+      "ignoreInternal": false,
+      "ignorePrivate": false,
+      "ignoreReplacesDocs": true,
+      "implementsReplacesDocs": false,
+      "overrideReplacesDocs": true,
+      "tagNamePreference": {}
+    },
+    "jsx-a11y": {
+      "attributes": {},
+      "components": {},
+      "polymorphicPropName": null
+    },
+    "next": {
+      "rootDir": []
+    },
+    "react": {
+      "formComponents": [],
+      "linkComponents": []
+    }
+  }
+}

.prettierignore

@@ -1,11 +0,0 @@
-out
-dist
-pnpm-lock.yaml
-LICENSE.md
-tsconfig.json
-tsconfig.*.json
-CHANGELOG*.md
-agents.json
-src/renderer/src/integration/nutstore/sso/lib
-AGENT.md
-src/main/integration/cherryin/index.js

.prettierrc

@@ -1,11 +0,0 @@
-{
-  "bracketSameLine": true,
-  "endOfLine": "lf",
-  "jsonRecursiveSort": true,
-  "jsonSortOrder": "{\"*\": \"lexical\"}",
-  "plugins": ["prettier-plugin-sort-json"],
-  "printWidth": 120,
-  "semi": false,
-  "singleQuote": true,
-  "trailingComma": "none"
-}

.vscode/extensions.json

@@ -1,8 +1,11 @@
 {
   "recommendations": [
     "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode",
     "editorconfig.editorconfig",
-    "lokalise.i18n-ally"
+    "lokalise.i18n-ally",
+    "bradlc.vscode-tailwindcss",
+    "vitest.explorer",
+    "oxc.oxc-vscode",
+    "biomejs.biome"
   ]
 }

.vscode/settings.json

@@ -1,38 +1,43 @@
 {
   "[css]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "[javascript]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "[json]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "[jsonc]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "[markdown]": {
     "files.trimTrailingWhitespace": false
   },
   "[scss]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "[typescript]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "[typescriptreact]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode"
+    "editor.defaultFormatter": "biomejs.biome"
   },
   "editor.codeActionsOnSave": {
+    "source.fixAll.biome": "explicit",
     "source.fixAll.eslint": "explicit",
+    "source.fixAll.oxc": "explicit",
     "source.organizeImports": "never"
   },
   "editor.formatOnSave": true,
+  "files.associations": {
+    "*.css": "tailwindcss"
+  },
   "files.eol": "\n",
-  "i18n-ally.displayLanguage": "zh-cn",
+  // "i18n-ally.displayLanguage": "zh-cn", // 界面显示语言
   "i18n-ally.enabledFrameworks": ["react-i18next", "i18next"],
   "i18n-ally.enabledParsers": ["ts", "js", "json"], // 解析语言
-  "i18n-ally.fullReloadOnChanged": true, // 界面显示语言
+  "i18n-ally.fullReloadOnChanged": true,
   "i18n-ally.keystyle": "nested", // 翻译路径格式
   "i18n-ally.localesPaths": ["src/renderer/src/i18n/locales"],
   // "i18n-ally.namespace": true, // 开启命名空间
@@ -42,5 +47,9 @@
   "search.exclude": {
     "**/dist/**": true,
     ".yarn/releases/**": true
-  }
+  },
+  "tailwindCSS.classAttributes": [
+    "className",
+    "classNames",
+  ]
 }

.yarn/patches/@ai-sdk-google-npm-2.0.20-b9102f9d54.patch

@@ -0,0 +1,13 @@
+diff --git a/dist/index.mjs b/dist/index.mjs
+index 69ab1599c76801dc1167551b6fa283dded123466..f0af43bba7ad1196fe05338817e65b4ebda40955 100644
+--- a/dist/index.mjs
++++ b/dist/index.mjs
+@@ -477,7 +477,7 @@ function convertToGoogleGenerativeAIMessages(prompt, options) {
+ 
+ // src/get-model-path.ts
+ function getModelPath(modelId) {
+-  return modelId.includes("/") ? modelId : `models/${modelId}`;
++  return modelId?.includes("models/") ? modelId : `models/${modelId}`;
+ }
+ 
+ // src/google-generative-ai-options.ts

.yarn/patches/@anthropic-ai-claude-agent-sdk-npm-0.1.1-d937b73fed.patch

@@ -0,0 +1,31 @@
+diff --git a/sdk.mjs b/sdk.mjs
+index 461e9a2ba246778261108a682762ffcf26f7224e..44bd667d9f591969d36a105ba5eb8b478c738dd8 100644
+--- a/sdk.mjs
++++ b/sdk.mjs
+@@ -6215,7 +6215,7 @@ function createAbortController(maxListeners = DEFAULT_MAX_LISTENERS) {
+ }
+
+ // ../src/transport/ProcessTransport.ts
+-import { spawn } from "child_process";
++import { fork } from "child_process";
+ import { createInterface } from "readline";
+
+ // ../src/utils/fsOperations.ts
+@@ -6473,14 +6473,11 @@ class ProcessTransport {
+         const errorMessage = isNativeBinary(pathToClaudeCodeExecutable) ? `Claude Code native binary not found at ${pathToClaudeCodeExecutable}. Please ensure Claude Code is installed via native installer or specify a valid path with options.pathToClaudeCodeExecutable.` : `Claude Code executable not found at ${pathToClaudeCodeExecutable}. Is options.pathToClaudeCodeExecutable set?`;
+         throw new ReferenceError(errorMessage);
+       }
+-      const isNative = isNativeBinary(pathToClaudeCodeExecutable);
+-      const spawnCommand = isNative ? pathToClaudeCodeExecutable : executable;
+-      const spawnArgs = isNative ? args : [...executableArgs, pathToClaudeCodeExecutable, ...args];
+-      this.logForDebugging(isNative ? `Spawning Claude Code native binary: ${pathToClaudeCodeExecutable} ${args.join(" ")}` : `Spawning Claude Code process: ${executable} ${[...executableArgs, pathToClaudeCodeExecutable, ...args].join(" ")}`);
++      this.logForDebugging(`Forking Claude Code Node.js process: ${pathToClaudeCodeExecutable} ${args.join(" ")}`);
+       const stderrMode = env.DEBUG || stderr ? "pipe" : "ignore";
+-      this.child = spawn(spawnCommand, spawnArgs, {
++      this.child = fork(pathToClaudeCodeExecutable, args, {
+         cwd,
+-        stdio: ["pipe", "pipe", stderrMode],
++        stdio: stderrMode === "pipe" ? ["pipe", "pipe", "pipe", "ipc"] : ["pipe", "pipe", "ignore", "ipc"],
+         signal: this.abortController.signal,
+         env
+       });

.yarnrc.yml

@@ -5,3 +5,5 @@ httpTimeout: 300000
 nodeLinker: node-modules
 
 yarnPath: .yarn/releases/yarn-4.9.1.cjs
+npmRegistryServer: https://registry.npmjs.org
+npmPublishRegistry: https://registry.npmjs.org

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -1,120 +1,51 @@
-# CLAUDE.md
+# AI Assistant Guide
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding assistants when working with code in this repository. Adherence to these guidelines is crucial for maintaining code quality and consistency.
+
+## Guiding Principles (MUST FOLLOW)
+
+- **Keep it clear**: Write code that is easy to read, maintain, and explain.
+- **Match the house style**: Reuse existing patterns, naming, and conventions.
+- **Search smart**: Prefer `ast-grep` for semantic queries; fall back to `rg`/`grep` when needed.
+- **Build with HeroUI**: Use HeroUI for every new UI component; never add `antd` or `styled-components`.
+- **Log centrally**: Route all logging through `loggerService` with the right context—no `console.log`.
+- **Research via subagent**: Lean on `subagent` for external docs, APIs, news, and references.
+- **Seek review**: Ask a human developer to review substantial changes before merging.
+- **Commit in rhythm**: Keep commits small, conventional, and emoji-tagged.
 
 ## Development Commands
 
-### Environment Setup
+- **Install**: `yarn install` - Install all project dependencies
+- **Development**: `yarn dev` - Runs Electron app in development mode with hot reload
+- **Debug**: `yarn debug` - Starts with debugging enabled, use `chrome://inspect` to attach debugger
+- **Build Check**: `yarn build:check` - **REQUIRED** before commits (lint + test + typecheck)
+  - If having i18n sort issues, run `yarn sync:i18n` first to sync template
+  - If having formatting issues, run `yarn format` first
+- **Test**: `yarn test` - Run all tests (Vitest) across main and renderer processes
+- **Single Test**:
+  - `yarn test:main` - Run tests for main process only
+  - `yarn test:renderer` - Run tests for renderer process only
+- **Lint**: `yarn lint` - Fix linting issues and run TypeScript type checking
+- **Format**: `yarn format` - Auto-format code using Biome
 
-- **Prerequisites**: Node.js v22.x.x or higher, Yarn 4.9.1
-- **Setup Yarn**: `corepack enable && corepack prepare yarn@4.9.1 --activate`
-- **Install Dependencies**: `yarn install`
+## Project Architecture
 
-### Development
+### Electron Structure
+- **Main Process** (`src/main/`): Node.js backend with services (MCP, Knowledge, Storage, etc.)
+- **Renderer Process** (`src/renderer/`): React UI with Redux state management
+- **Preload Scripts** (`src/preload/`): Secure IPC bridge
 
-- **Start Development**: `yarn dev` - Runs Electron app in development mode
-- **Debug Mode**: `yarn debug` - Starts with debugging enabled, use chrome://inspect
-
-### Testing & Quality
-
-- **Run Tests**: `yarn test` - Runs all tests (Vitest)
-- **Run E2E Tests**: `yarn test:e2e` - Playwright end-to-end tests
-- **Type Check**: `yarn typecheck` - Checks TypeScript for both node and web
-- **Lint**: `yarn lint` - ESLint with auto-fix
-- **Format**: `yarn format` - Prettier formatting
-
-### Build & Release
-
-- **Build**: `yarn build` - Builds for production (includes typecheck)
-- **Platform-specific builds**:
-  - Windows: `yarn build:win`
-  - macOS: `yarn build:mac`
-  - Linux: `yarn build:linux`
-
-## Architecture Overview
-
-### Electron Multi-Process Architecture
-
-- **Main Process** (`src/main/`): Node.js backend handling system integration, file operations, and services
-- **Renderer Process** (`src/renderer/`): React-based UI running in Chromium
-- **Preload Scripts** (`src/preload/`): Secure bridge between main and renderer processes
-
-### Key Architectural Components
-
-#### Main Process Services (`src/main/services/`)
-
-- **MCPService**: Model Context Protocol server management
-- **KnowledgeService**: Document processing and knowledge base management
-- **FileStorage/S3Storage/WebDav**: Multiple storage backends
-- **WindowService**: Multi-window management (main, mini, selection windows)
-- **ProxyManager**: Network proxy handling
-- **SearchService**: Full-text search capabilities
-
-#### AI Core (`src/renderer/src/aiCore/`)
-
-- **Middleware System**: Composable pipeline for AI request processing
-- **Client Factory**: Supports multiple AI providers (OpenAI, Anthropic, Gemini, etc.)
-- **Stream Processing**: Real-time response handling
-
-#### State Management (`src/renderer/src/store/`)
-
-- **Redux Toolkit**: Centralized state management
-- **Persistent Storage**: Redux-persist for data persistence
-- **Thunks**: Async actions for complex operations
-
-#### Knowledge Management
-
-- **Embeddings**: Vector search with multiple providers (OpenAI, Voyage, etc.)
-- **OCR**: Document text extraction (system OCR, Doc2x, Mineru)
-- **Preprocessing**: Document preparation pipeline
-- **Loaders**: Support for various file formats (PDF, DOCX, EPUB, etc.)
-
-### Build System
-
-- **Electron-Vite**: Development and build tooling (v4.0.0)
-- **Rolldown-Vite**: Using experimental rolldown-vite instead of standard vite
-- **Workspaces**: Monorepo structure with `packages/` directory
-- **Multiple Entry Points**: Main app, mini window, selection toolbar
-- **Styled Components**: CSS-in-JS styling with SWC optimization
-
-### Testing Strategy
-
-- **Vitest**: Unit and integration testing
-- **Playwright**: End-to-end testing
-- **Component Testing**: React Testing Library
-- **Coverage**: Available via `yarn test:coverage`
-
-### Key Patterns
-
-- **IPC Communication**: Secure main-renderer communication via preload scripts
-- **Service Layer**: Clear separation between UI and business logic
-- **Plugin Architecture**: Extensible via MCP servers and middleware
-- **Multi-language Support**: i18n with dynamic loading
-- **Theme System**: Light/dark themes with custom CSS variables
-
-## Logging Standards
-
-### Usage
+### Key Components
+- **AI Core** (`src/renderer/src/aiCore/`): Middleware pipeline for multiple AI providers.
+- **Services** (`src/main/services/`): MCPService, KnowledgeService, WindowService, etc.
+- **Build System**: Electron-Vite with experimental rolldown-vite, yarn workspaces.
+- **State Management**: Redux Toolkit (`src/renderer/src/store/`) for predictable state.
+- **UI Components**: HeroUI (`@heroui/*`) for all new UI elements.
 
+### Logging
 ```typescript
-// Main process
 import { loggerService } from '@logger'
 const logger = loggerService.withContext('moduleName')
-
-// Renderer process (set window source first)
-loggerService.initWindowSource('windowName')
-const logger = loggerService.withContext('moduleName')
-
-// Logging
+// Renderer: loggerService.initWindowSource('windowName') first
 logger.info('message', CONTEXT)
-logger.error('message', new Error('error'), CONTEXT)
 ```
-
-### Log Levels (highest to lowest)
-
-- `error` - Critical errors causing crash/unusable functionality
-- `warn` - Potential issues that don't affect core functionality
-- `info` - Application lifecycle and key user actions
-- `verbose` - Detailed flow information for feature tracing
-- `debug` - Development diagnostic info (not for production)
-- `silly` - Extreme debugging, low-level information

LICENSE

@@ -1,48 +1,3 @@
-**许可协议 (Licensing)**
-
-本项目采用**区分用户的双重许可 (User-Segmented Dual Licensing)** 模式。
-
-**核心原则：**
-
-* **个人用户 和 10人及以下企业/组织:** 默认适用 **GNU Affero 通用公共许可证 v3.0 (AGPLv3)**。  
-* **超过10人的企业/组织:** **必须** 获取 **商业许可证 (Commercial License)**。
-
-定义：“10人及以下”  
-指在您的组织（包括公司、非营利组织、政府机构、教育机构等任何实体）中，能够访问、使用或以任何方式直接或间接受益于本软件（Cherry Studio）功能的个人总数不超过10人。这包括但不限于开发者、测试人员、运营人员、最终用户、通过集成系统间接使用者等。
-
----
-
-**1. 开源许可证 (Open Source License): AGPLv3 - 适用于个人及10人及以下组织**
-
-* 如果您是个人用户，或者您的组织满足上述“10人及以下”的定义，您可以在 **AGPLv3** 的条款下自由使用、修改和分发 Cherry Studio。AGPLv3 的完整文本可以访问 [https://www.gnu.org/licenses/agpl-3.0.html](https://www.gnu.org/licenses/agpl-3.0.html) 获取。  
-* **核心义务：** AGPLv3 的一个关键要求是，如果您修改了 Cherry Studio 并通过网络提供服务，或者分发了修改后的版本，您必须以 AGPLv3 许可证向接收者提供相应的**完整源代码**。即使您符合“10人及以下”的标准，如果您希望避免此源代码公开义务，您也需要考虑获取商业许可证（见下文）。  
-* 使用前请务必仔细阅读并理解 AGPLv3 的所有条款。
-
-**2. 商业许可证 (Commercial License) - 适用于超过10人的组织，或希望规避 AGPLv3 义务的用户**
-
-* **强制要求：** 如果您的组织**不**满足上述“10人及以下”的定义（即有11人或更多人可以访问、使用或受益于本软件），您**必须**联系我们获取并签署一份商业许可证才能使用 Cherry Studio。  
-* **自愿选择：** 即使您的组织满足“10人及以下”的条件，但如果您的使用场景**无法满足 AGPLv3 的条款要求**（特别是关于**源代码公开**的义务），或者您需要 AGPLv3 **未提供**的特定商业条款（如保证、赔偿、无 Copyleft 限制等），您也**必须**联系我们获取并签署一份商业许可证。  
-* **需要商业许可证的常见情况包括（但不限于）：**  
-  * 您的组织规模超过10人。  
-  * （无论组织规模）您希望分发修改过的 Cherry Studio 版本，但**不希望**根据 AGPLv3 公开您修改部分的源代码。  
-  * （无论组织规模）您希望基于修改过的 Cherry Studio 提供网络服务（SaaS），但**不希望**根据 AGPLv3 向服务使用者提供修改后的源代码。  
-  * （无论组织规模）您的公司政策、客户合同或项目要求不允许使用 AGPLv3 许可的软件，或要求闭源分发及保密。  
-* 商业许可证将为您提供豁免 AGPLv3 义务（如源代码公开）的权利，并可能包含额外的商业保障条款。  
-* **获取商业许可：** 请通过邮箱 **bd@cherry-ai.com** 联系 Cherry Studio 开发团队洽谈商业授权事宜。
-
-**3. 贡献 (Contributions)**
-
-* 我们欢迎社区对 Cherry Studio 的贡献。所有向本项目提交的贡献都将被视为在 **AGPLv3** 许可证下提供。  
-* 通过向本项目提交贡献（例如通过 Pull Request），即表示您同意您的代码以 AGPLv3 许可证授权给本项目及所有后续使用者（无论这些使用者最终遵循 AGPLv3 还是商业许可）。  
-* 您也理解并同意，您的贡献可能会被包含在根据商业许可证分发的 Cherry Studio 版本中。
-
-**4. 其他条款 (Other Terms)**
-
-* 关于商业许可证的具体条款和条件，以双方签署的正式商业许可协议为准。  
-* 项目维护者保留根据需要更新本许可政策（包括用户规模定义和阈值）的权利。相关更新将通过项目官方渠道（如代码仓库、官方网站）进行通知。
-
----
-
 **Licensing**
 
 This project employs a **User-Segmented Dual Licensing** model.

README.md

@@ -82,7 +82,7 @@ Cherry Studio is a desktop client that supports multiple LLM providers, availabl
 1. **Diverse LLM Provider Support**:
 
 - ☁️ Major LLM Cloud Services: OpenAI, Gemini, Anthropic, and more
-- 🔗 AI Web Service Integration: Claude, Peplexity, Poe, and others
+- 🔗 AI Web Service Integration: Claude, Perplexity, Poe, and others
 - 💻 Local Model Support with Ollama, LM Studio
 
 2. **AI Assistants & Conversations**:

biome.jsonc

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
+  "assist": {
+    // to sort json
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedKeys": {
+          "level": "on",
+          "options": {
+            "sortOrder": "lexicographic"
+          }
+        }
+      }
+    },
+    "enabled": true,
+    "includes": ["**/*.json", "!*.json", "!**/package.json"]
+  },
+  "css": {
+    "formatter": {
+      "quoteStyle": "single"
+    }
+  },
+  "files": { "ignoreUnknown": false },
+  "formatter": {
+    "attributePosition": "auto",
+    "bracketSameLine": false,
+    "bracketSpacing": true,
+    "enabled": true,
+    "expand": "auto",
+    "formatWithErrors": true,
+    "includes": [
+      "**",
+      "!out/**",
+      "!**/dist/**",
+      "!build/**",
+      "!.yarn/**",
+      "!.github/**",
+      "!.husky/**",
+      "!.vscode/**",
+      "!*.yaml",
+      "!*.yml",
+      "!*.mjs",
+      "!*.cjs",
+      "!*.md",
+      "!*.json",
+      "!src/main/integration/**",
+      "!**/tailwind.css",
+      "!**/package.json"
+    ],
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineEnding": "lf",
+    "lineWidth": 120,
+    "useEditorconfig": true
+  },
+  "html": { "formatter": { "selfCloseVoidElements": "always" } },
+  "javascript": {
+    "formatter": {
+      "arrowParentheses": "always",
+      "attributePosition": "auto",
+      // To minimize changes in this PR as much as possible, it's set to true. However, setting it to false would make it more convenient to add attributes at the end.
+      "bracketSameLine": true,
+      "bracketSpacing": true,
+      "jsxQuoteStyle": "double",
+      "quoteProperties": "asNeeded",
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "trailingCommas": "none"
+    }
+  },
+  "json": {
+    "parser": {
+      "allowComments": true
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "includes": ["!**/tailwind.css", "src/renderer/**/*.{tsx,ts}"],
+    // only enable sorted tailwind css rule. used as formatter instead of linter
+    "rules": {
+      "nursery": {
+        // to sort tailwind css classes
+        "useSortedClasses": {
+          "fix": "safe",
+          "level": "warn",
+          "options": {
+            "functions": ["cn"]
+          }
+        }
+      },
+      "recommended": false,
+      "suspicious": "off"
+    }
+  },
+  "vcs": { "clientKind": "git", "enabled": false, "useIgnoreFile": false }
+}

components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "aliases": {
+    "components": "@renderer/ui/third-party",
+    "hooks": "@renderer/hooks",
+    "lib": "@renderer/lib",
+    "ui": "@renderer/ui",
+    "utils": "@renderer/utils"
+  },
+  "iconLibrary": "lucide",
+  "rsc": false,
+  "style": "new-york",
+  "tailwind": {
+    "baseColor": "zinc",
+    "config": "",
+    "css": "src/renderer/src/assets/styles/tailwind.css",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "tsx": true
+}

docs/README.zh.md

@@ -13,7 +13,7 @@
         <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=fr">Français</a></p>
         <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=de">Deutsch</a></p>
         <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=es">Español</a></p>
-        <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=it">Itapano</a></p>
+        <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=it">Italiano</a></p>
         <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=ru">Русский</a></p>
         <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=pt">Português</a></p>
         <p><a href="https://openaitx.github.io/view.html?user=CherryHQ&project=cherry-studio&lang=nl">Nederlands</a></p>
@@ -89,7 +89,7 @@ https://docs.cherry-ai.com
 1. **多样化 LLM 服务支持**：
 
 - ☁️ 支持主流 LLM 云服务：OpenAI、Gemini、Anthropic、硅基流动等
-- 🔗 集成流行 AI Web 服务：Claude、Peplexity、Poe、腾讯元宝、知乎直答等
+- 🔗 集成流行 AI Web 服务：Claude、Perplexity、Poe、腾讯元宝、知乎直答等
 - 💻 支持 Ollama、LM Studio 本地模型部署
 
 2. **智能助手与对话**：

docs/dev.md

@@ -2,7 +2,9 @@
 
 ## IDE Setup
 
-[Cursor](https://www.cursor.com/) + [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- Editor: [Cursor](https://www.cursor.com/), etc. Any VS Code compatible editor.
+- Linter: [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
+- Formatter: [Biome](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
 
 ## Project Setup
 

electron-builder.yml

@@ -17,52 +17,52 @@ protocols:
     schemes:
       - cherrystudio
 files:
-  - '**/*'
-  - '!**/{.vscode,.yarn,.yarn-lock,.github,.cursorrules,.prettierrc}'
-  - '!electron.vite.config.{js,ts,mjs,cjs}}'
-  - '!**/{.eslintignore,.eslintrc.js,.eslintrc.json,.eslintcache,root.eslint.config.js,eslint.config.js,.eslintrc.cjs,.prettierignore,.prettierrc.yaml,eslint.config.mjs,dev-app-update.yml,CHANGELOG.md,README.md}'
-  - '!**/{.env,.env.*,.npmrc,pnpm-lock.yaml}'
-  - '!**/{tsconfig.json,tsconfig.tsbuildinfo,tsconfig.node.json,tsconfig.web.json}'
-  - '!**/{.editorconfig,.jekyll-metadata}'
-  - '!src'
-  - '!scripts'
-  - '!local'
-  - '!docs'
-  - '!packages'
-  - '!.swc'
-  - '!.bin'
-  - '!._*'
-  - '!*.log'
-  - '!stats.html'
-  - '!*.md'
-  - '!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}'
-  - '!**/*.{map,ts,tsx,jsx,less,scss,sass,css.d.ts,d.cts,d.mts,md,markdown,yaml,yml}'
-  - '!**/{test,tests,__tests__,powered-test,coverage}/**'
-  - '!**/{example,examples}/**'
-  - '!**/*.{spec,test}.{js,jsx,ts,tsx}'
-  - '!**/*.min.*.map'
-  - '!**/*.d.ts'
-  - '!**/dist/es6/**'
-  - '!**/dist/demo/**'
-  - '!**/amd/**'
-  - '!**/{.DS_Store,Thumbs.db,thumbs.db,__pycache__}'
-  - '!**/{LICENSE,license,LICENSE.*,*.LICENSE.txt,NOTICE.txt,README.md,readme.md,CHANGELOG.md}'
-  - '!node_modules/rollup-plugin-visualizer'
-  - '!node_modules/js-tiktoken'
-  - '!node_modules/@tavily/core/node_modules/js-tiktoken'
-  - '!node_modules/pdf-parse/lib/pdf.js/{v1.9.426,v1.10.88,v2.0.550}'
-  - '!node_modules/mammoth/{mammoth.browser.js,mammoth.browser.min.js}'
-  - '!node_modules/selection-hook/prebuilds/**/*' # we rebuild .node, don't use prebuilds
-  - '!node_modules/selection-hook/node_modules' # we don't need what in the node_modules dir
-  - '!node_modules/selection-hook/src' # we don't need source files
-  - '!node_modules/tesseract.js-core/{tesseract-core.js,tesseract-core.wasm,tesseract-core.wasm.js}' # we don't need source files
-  - '!node_modules/tesseract.js-core/{tesseract-core-lstm.js,tesseract-core-lstm.wasm,tesseract-core-lstm.wasm.js}' # we don't need source files
-  - '!node_modules/tesseract.js-core/{tesseract-core-simd-lstm.js,tesseract-core-simd-lstm.wasm,tesseract-core-simd-lstm.wasm.js}' # we don't need source files
-  - '!**/*.{h,iobj,ipdb,tlog,recipe,vcxproj,vcxproj.filters,Makefile,*.Makefile}' # filter .node build files
+  - "**/*"
+  - "!**/{.vscode,.yarn,.yarn-lock,.github,.cursorrules,.prettierrc}"
+  - "!electron.vite.config.{js,ts,mjs,cjs}}"
+  - "!**/{.eslintignore,.eslintrc.js,.eslintrc.json,.eslintcache,root.eslint.config.js,eslint.config.js,.eslintrc.cjs,.prettierignore,.prettierrc.yaml,eslint.config.mjs,dev-app-update.yml,CHANGELOG.md,README.md,biome.jsonc}"
+  - "!**/{.env,.env.*,.npmrc,pnpm-lock.yaml}"
+  - "!**/{tsconfig.json,tsconfig.tsbuildinfo,tsconfig.node.json,tsconfig.web.json}"
+  - "!**/{.editorconfig,.jekyll-metadata}"
+  - "!src"
+  - "!scripts"
+  - "!local"
+  - "!docs"
+  - "!packages"
+  - "!.swc"
+  - "!.bin"
+  - "!._*"
+  - "!*.log"
+  - "!stats.html"
+  - "!*.md"
+  - "!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,xproj}"
+  - "!**/*.{map,ts,tsx,jsx,less,scss,sass,css.d.ts,d.cts,d.mts,md,markdown,yaml,yml}"
+  - "!**/{test,tests,__tests__,powered-test,coverage}/**"
+  - "!**/{example,examples}/**"
+  - "!**/*.{spec,test}.{js,jsx,ts,tsx}"
+  - "!**/*.min.*.map"
+  - "!**/*.d.ts"
+  - "!**/dist/es6/**"
+  - "!**/dist/demo/**"
+  - "!**/amd/**"
+  - "!**/{.DS_Store,Thumbs.db,thumbs.db,__pycache__}"
+  - "!**/{LICENSE,license,LICENSE.*,*.LICENSE.txt,NOTICE.txt,README.md,readme.md,CHANGELOG.md}"
+  - "!node_modules/rollup-plugin-visualizer"
+  - "!node_modules/js-tiktoken"
+  - "!node_modules/@tavily/core/node_modules/js-tiktoken"
+  - "!node_modules/pdf-parse/lib/pdf.js/{v1.9.426,v1.10.88,v2.0.550}"
+  - "!node_modules/mammoth/{mammoth.browser.js,mammoth.browser.min.js}"
+  - "!node_modules/selection-hook/prebuilds/**/*" # we rebuild .node, don't use prebuilds
+  - "!node_modules/selection-hook/node_modules" # we don't need what in the node_modules dir
+  - "!node_modules/selection-hook/src" # we don't need source files
+  - "!node_modules/tesseract.js-core/{tesseract-core.js,tesseract-core.wasm,tesseract-core.wasm.js}" # we don't need source files
+  - "!node_modules/tesseract.js-core/{tesseract-core-lstm.js,tesseract-core-lstm.wasm,tesseract-core-lstm.wasm.js}" # we don't need source files
+  - "!node_modules/tesseract.js-core/{tesseract-core-simd-lstm.js,tesseract-core-simd-lstm.wasm,tesseract-core-simd-lstm.wasm.js}" # we don't need source files
+  - "!**/*.{h,iobj,ipdb,tlog,recipe,vcxproj,vcxproj.filters,Makefile,*.Makefile}" # filter .node build files
 asarUnpack:
   - resources/**
-  - '**/*.{metal,exp,lib}'
-  - 'node_modules/@img/sharp-libvips-*/**'
+  - "**/*.{metal,exp,lib}"
+  - "node_modules/@img/sharp-libvips-*/**"
 win:
   executableName: Cherry Studio
   artifactName: ${productName}-${version}-${arch}-setup.${ext}
@@ -88,7 +88,7 @@ mac:
   entitlementsInherit: build/entitlements.mac.plist
   notarize: false
   artifactName: ${productName}-${version}-${arch}.${ext}
-  minimumSystemVersion: '20.1.0' # 最低支持 macOS 11.0
+  minimumSystemVersion: "20.1.0" # 最低支持 macOS 11.0
   extendInfo:
     - NSCameraUsageDescription: Application requests access to the device's camera.
     - NSMicrophoneUsageDescription: Application requests access to the device's microphone.
@@ -110,6 +110,10 @@ linux:
       StartupWMClass: CherryStudio
   mimeTypes:
     - x-scheme-handler/cherrystudio
+rpm:
+  # Workaround for electron build issue on rpm package:
+  # https://github.com/electron/forge/issues/3594
+  fpm: ["--rpm-rpmbuild-define=_build_id_links none"]
 publish:
   provider: generic
   url: https://releases.cherry-ai.com
@@ -121,12 +125,21 @@ afterSign: scripts/notarize.js
 artifactBuildCompleted: scripts/artifact-build-completed.js
 releaseInfo:
   releaseNotes: |
-    🔧 性能优化：
-    - 优化AI服务连接方式，提升响应速度和稳定性
-    - 改进模型列表获取功能，减少不必要的网络请求
-    - 增强各AI服务商的兼容性和连接可靠性
+    What's New in v1.6.3
 
-    🐛 问题修复：
-    - 修复部分AI服务商连接失败的问题
-    - 修复模型配置加载时的潜在错误
-    - 提升应用整体稳定性和容错能力
+    Features:
+    - Notes: Add spell-check control, automatic table line wrapping, export functionality, and LLM-based renaming
+    - UI: Expand topic rename clickable area, add middle-click tab closing, remove redundant scrollbars, fix message menubar overflow
+    - Editor: Add read-only extension support, make TextFilePreview read-only but copyable
+    - Models: Update support for DeepSeek v3.2, Claude 4.5, GLM 4.6, Gemini regex, and vision models
+    - Code Tools: Add GitHub Copilot CLI integration
+
+    Bug Fixes:
+    - Fix migration for missing providers
+    - Fix forked topic retaining old name after rename
+    - Restore first token latency reporting in metrics
+    - Fix UI scrollbar and overflow issues
+
+    Technical Updates:
+    - Upgrade to Electron 37.6.0
+    - Update dependencies across packages

electron.vite.config.ts

@@ -4,7 +4,9 @@ import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
 import { resolve } from 'path'
 import { visualizer } from 'rollup-plugin-visualizer'
 
-import pkg from './package.json' assert { type: 'json' }
+// assert not supported by biome
+// import pkg from './package.json' assert { type: 'json' }
+import pkg from './package.json'
 
 const visualizerPlugin = (type: 'renderer' | 'main') => {
   return process.env[`VISUALIZER_${type.toUpperCase()}`] ? [visualizer({ open: true })] : []
@@ -23,10 +25,7 @@ export default defineConfig({
         '@shared': resolve('packages/shared'),
         '@logger': resolve('src/main/services/LoggerService'),
         '@mcp-trace/trace-core': resolve('packages/mcp-trace/trace-core'),
-        '@mcp-trace/trace-node': resolve('packages/mcp-trace/trace-node'),
-        '@cherrystudio/ai-core/provider': resolve('packages/aiCore/src/core/providers'),
-        '@cherrystudio/ai-core/built-in/plugins': resolve('packages/aiCore/src/core/plugins/built-in'),
-        '@cherrystudio/ai-core': resolve('packages/aiCore/src')
+        '@mcp-trace/trace-node': resolve('packages/mcp-trace/trace-node')
       }
     },
     build: {
@@ -35,6 +34,10 @@ export default defineConfig({
         output: {
           manualChunks: undefined, // 彻底禁用代码分割 - 返回 null 强制单文件打包
           inlineDynamicImports: true // 内联所有动态导入，这是关键配置
+        },
+        onwarn(warning, warn) {
+          if (warning.code === 'COMMONJS_VARIABLE_IN_ESM') return
+          warn(warning)
         }
       },
       sourcemap: isDev
@@ -63,6 +66,7 @@ export default defineConfig({
   },
   renderer: {
     plugins: [
+      (async () => (await import('@tailwindcss/vite')).default())(),
       react({
         tsDecorators: true,
         plugins: [
@@ -84,6 +88,7 @@ export default defineConfig({
       alias: {
         '@renderer': resolve('src/renderer/src'),
         '@shared': resolve('packages/shared'),
+        '@types': resolve('src/renderer/src/types'),
         '@logger': resolve('src/renderer/src/services/LoggerService'),
         '@mcp-trace/trace-core': resolve('packages/mcp-trace/trace-core'),
         '@mcp-trace/trace-web': resolve('packages/mcp-trace/trace-web'),
@@ -111,6 +116,10 @@ export default defineConfig({
           selectionToolbar: resolve(__dirname, 'src/renderer/selectionToolbar.html'),
           selectionAction: resolve(__dirname, 'src/renderer/selectionAction.html'),
           traceWindow: resolve(__dirname, 'src/renderer/traceWindow.html')
+        },
+        onwarn(warning, warn) {
+          if (warning.code === 'COMMONJS_VARIABLE_IN_ESM') return
+          warn(warning)
         }
       }
     },

eslint.config.mjs

@@ -1,8 +1,9 @@
-import electronConfigPrettier from '@electron-toolkit/eslint-config-prettier'
 import tseslint from '@electron-toolkit/eslint-config-ts'
 import eslint from '@eslint/js'
 import eslintReact from '@eslint-react/eslint-plugin'
 import { defineConfig } from 'eslint/config'
+import importZod from 'eslint-plugin-import-zod'
+import oxlint from 'eslint-plugin-oxlint'
 import reactHooks from 'eslint-plugin-react-hooks'
 import simpleImportSort from 'eslint-plugin-simple-import-sort'
 import unusedImports from 'eslint-plugin-unused-imports'
@@ -10,13 +11,13 @@ import unusedImports from 'eslint-plugin-unused-imports'
 export default defineConfig([
   eslint.configs.recommended,
   tseslint.configs.recommended,
-  electronConfigPrettier,
   eslintReact.configs['recommended-typescript'],
   reactHooks.configs['recommended-latest'],
   {
     plugins: {
       'simple-import-sort': simpleImportSort,
-      'unused-imports': unusedImports
+      'unused-imports': unusedImports,
+      'import-zod': importZod
     },
     rules: {
       '@typescript-eslint/explicit-function-return-type': 'off',
@@ -26,7 +27,7 @@ export default defineConfig([
       'simple-import-sort/exports': 'error',
       'unused-imports/no-unused-imports': 'error',
       '@eslint-react/no-prop-types': 'error',
-      'prettier/prettier': ['error']
+      'import-zod/prefer-zod-namespace': 'error'
     }
   },
   // Configuration for ensuring compatibility with the original ESLint(8.x) rules
@@ -50,10 +51,31 @@ export default defineConfig([
       '@eslint-react/no-children-to-array': 'off'
     }
   },
+  {
+    ignores: [
+      'node_modules/**',
+      'build/**',
+      'dist/**',
+      'out/**',
+      'local/**',
+      '.yarn/**',
+      '.gitignore',
+      'scripts/cloudflare-worker.js',
+      'src/main/integration/nutstore/sso/lib/**',
+      'src/main/integration/cherryai/index.js',
+      'src/main/integration/nutstore/sso/lib/**',
+      'src/renderer/src/ui/**',
+      'packages/**/dist'
+    ]
+  },
+  // turn off oxlint supported rules.
+  ...oxlint.configs['flat/eslint'],
+  ...oxlint.configs['flat/typescript'],
+  ...oxlint.configs['flat/unicorn'],
   {
     // LoggerService Custom Rules - only apply to src directory
     files: ['src/**/*.{ts,tsx,js,jsx}'],
-    ignores: ['src/**/__tests__/**', 'src/**/__mocks__/**', 'src/**/*.test.*'],
+    ignores: ['src/**/__tests__/**', 'src/**/__mocks__/**', 'src/**/*.test.*', 'src/preload/**'],
     rules: {
       'no-restricted-syntax': [
         process.env.PRCI ? 'error' : 'warn',
@@ -112,18 +134,4 @@ export default defineConfig([
       'i18n/no-template-in-t': 'warn'
     }
   },
-  {
-    ignores: [
-      'node_modules/**',
-      'build/**',
-      'dist/**',
-      'out/**',
-      'local/**',
-      '.yarn/**',
-      '.gitignore',
-      'scripts/cloudflare-worker.js',
-      'src/main/integration/nutstore/sso/lib/**',
-      'src/main/integration/cherryin/index.js'
-    ]
-  }
 ])

package.json

@@ -1,6 +1,6 @@
 {
   "name": "CherryStudio",
-  "version": "1.6.0-beta.6",
+  "version": "1.7.0-alpha.5",
   "private": true,
   "description": "A powerful AI assistant for producer.",
   "main": "./out/main/index.js",
@@ -43,15 +43,18 @@
     "release": "node scripts/version.js",
     "publish": "yarn build:check && yarn release patch push",
     "pulish:artifacts": "cd packages/artifacts && npm publish && cd -",
-    "generate:agents": "yarn workspace @cherry-studio/database agents",
+    "agents:generate": "NODE_ENV='development' drizzle-kit generate --config src/main/services/agents/drizzle.config.ts",
+    "agents:push": "NODE_ENV='development' drizzle-kit push --config src/main/services/agents/drizzle.config.ts",
+    "agents:studio": "NODE_ENV='development' drizzle-kit studio --config src/main/services/agents/drizzle.config.ts",
+    "agents:drop": "NODE_ENV='development' drizzle-kit drop --config src/main/services/agents/drizzle.config.ts",
     "generate:icons": "electron-icon-builder --input=./build/logo.png --output=build",
     "analyze:renderer": "VISUALIZER_RENDERER=true yarn build",
     "analyze:main": "VISUALIZER_MAIN=true yarn build",
     "typecheck": "concurrently -n \"node,web\" -c \"cyan,magenta\" \"npm run typecheck:node\" \"npm run typecheck:web\"",
-    "typecheck:node": "tsc --noEmit -p tsconfig.node.json --composite false",
-    "typecheck:web": "tsc --noEmit -p tsconfig.web.json --composite false",
-    "check:i18n": "tsx scripts/check-i18n.ts",
-    "sync:i18n": "tsx scripts/sync-i18n.ts",
+    "typecheck:node": "tsgo --noEmit -p tsconfig.node.json --composite false",
+    "typecheck:web": "tsgo --noEmit -p tsconfig.web.json --composite false",
+    "check:i18n": "dotenv -e .env -- tsx scripts/check-i18n.ts",
+    "sync:i18n": "dotenv -e .env -- tsx scripts/sync-i18n.ts",
     "update:i18n": "dotenv -e .env -- tsx scripts/update-i18n.ts",
     "auto:i18n": "dotenv -e .env -- tsx scripts/auto-translate-i18n.ts",
     "update:languages": "tsx scripts/update-languages.ts",
@@ -63,26 +66,32 @@
     "test:ui": "vitest --ui",
     "test:watch": "vitest",
     "test:e2e": "yarn playwright test",
-    "test:lint": "eslint . --ext .js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts",
+    "test:lint": "oxlint --deny-warnings && eslint . --ext .js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --cache",
     "test:scripts": "vitest scripts",
-    "format": "prettier --write .",
-    "lint": "eslint . --ext .js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix && yarn typecheck && yarn check:i18n",
-    "prepare": "git config blame.ignoreRevsFile .git-blame-ignore-revs && husky"
+    "lint": "oxlint --fix && eslint . --ext .js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --cache && yarn typecheck && yarn check:i18n && yarn format:check",
+    "format": "biome format --write && biome lint --write",
+    "format:check": "biome format && biome lint",
+    "prepare": "git config blame.ignoreRevsFile .git-blame-ignore-revs && husky",
+    "claude": "dotenv -e .env -- claude",
+    "release:aicore:alpha": "yarn workspace @cherrystudio/ai-core version prerelease --immediate && yarn workspace @cherrystudio/ai-core npm publish --tag alpha --access public",
+    "release:aicore:beta": "yarn workspace @cherrystudio/ai-core version prerelease --immediate && yarn workspace @cherrystudio/ai-core npm publish --tag beta --access public",
+    "release:aicore": "yarn workspace @cherrystudio/ai-core version patch --immediate && yarn workspace @cherrystudio/ai-core npm publish --access public"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "patch:@anthropic-ai/claude-agent-sdk@npm%3A0.1.1#~/.yarn/patches/@anthropic-ai-claude-agent-sdk-npm-0.1.1-d937b73fed.patch",
     "@libsql/client": "0.14.0",
     "@libsql/win32-x64-msvc": "^0.4.7",
     "@napi-rs/system-ocr": "patch:@napi-rs/system-ocr@npm%3A1.0.2#~/.yarn/patches/@napi-rs-system-ocr-npm-1.0.2-59e7a78e8b.patch",
     "@strongtz/win32-arm64-msvc": "^0.4.7",
-    "ai-sdk-provider-claude-code": "^1.1.3",
-    "express": "^5.1.0",
+    "font-list": "^2.0.0",
     "graceful-fs": "^4.2.11",
     "jsdom": "26.1.0",
     "node-stream-zip": "^1.15.0",
     "officeparser": "^4.2.0",
     "os-proxy-config": "^1.1.2",
-    "selection-hook": "^1.0.11",
+    "selection-hook": "^1.0.12",
     "sharp": "^0.34.3",
+    "swagger-jsdoc": "^6.2.8",
     "tesseract.js": "patch:tesseract.js@npm%3A6.0.1#~/.yarn/patches/tesseract.js-npm-6.0.1-2562a7e46d.patch",
     "turndown": "7.2.0"
   },
@@ -90,16 +99,18 @@
     "@agentic/exa": "^7.3.3",
     "@agentic/searxng": "^7.3.3",
     "@agentic/tavily": "^7.3.3",
-    "@ai-sdk/amazon-bedrock": "^3.0.0",
-    "@ai-sdk/google-vertex": "^3.0.0",
-    "@ai-sdk/mistral": "^2.0.0",
+    "@ai-sdk/amazon-bedrock": "^3.0.35",
+    "@ai-sdk/google-vertex": "^3.0.40",
+    "@ai-sdk/mistral": "^2.0.19",
+    "@ai-sdk/perplexity": "^2.0.13",
     "@ant-design/v5-patch-for-react-19": "^1.0.3",
     "@anthropic-ai/sdk": "^0.41.0",
     "@anthropic-ai/vertex-sdk": "patch:@anthropic-ai/vertex-sdk@npm%3A0.11.4#~/.yarn/patches/@anthropic-ai-vertex-sdk-npm-0.11.4-c19cb41edb.patch",
     "@aws-sdk/client-bedrock": "^3.840.0",
     "@aws-sdk/client-bedrock-runtime": "^3.840.0",
     "@aws-sdk/client-s3": "^3.840.0",
-    "@cherrystudio/ai-core": "workspace:*",
+    "@biomejs/biome": "2.2.4",
+    "@cherrystudio/ai-core": "workspace:^1.0.0-alpha.18",
     "@cherrystudio/embedjs": "^0.1.31",
     "@cherrystudio/embedjs-libsql": "^0.1.31",
     "@cherrystudio/embedjs-loader-csv": "^0.1.31",
@@ -117,7 +128,6 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@electron-toolkit/eslint-config-prettier": "^3.0.0",
     "@electron-toolkit/eslint-config-ts": "^3.0.0",
     "@electron-toolkit/preload": "^3.0.0",
     "@electron-toolkit/tsconfig": "^1.0.1",
@@ -128,11 +138,11 @@
     "@eslint/js": "^9.22.0",
     "@google/genai": "patch:@google/genai@npm%3A1.0.1#~/.yarn/patches/@google-genai-npm-1.0.1-e26f0f9af7.patch",
     "@hello-pangea/dnd": "^18.0.1",
+    "@heroui/react": "^2.8.3",
     "@kangfenmao/keyv-storage": "^0.1.0",
-    "@langchain/community": "^0.3.36",
-    "@langchain/ollama": "^0.2.1",
+    "@langchain/community": "^0.3.50",
     "@mistralai/mistralai": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.17.0",
+    "@modelcontextprotocol/sdk": "^1.17.5",
     "@mozilla/readability": "^0.6.0",
     "@notionhq/client": "^2.2.15",
     "@openrouter/ai-sdk-provider": "^1.1.2",
@@ -142,10 +152,13 @@
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
     "@opentelemetry/sdk-trace-web": "^2.0.0",
+    "@opeoginni/github-copilot-openai-compatible": "0.1.18",
     "@playwright/test": "^1.52.0",
+    "@radix-ui/react-context-menu": "^2.2.16",
     "@reduxjs/toolkit": "^2.2.5",
     "@shikijs/markdown-it": "^3.12.0",
     "@swc/plugin-styled-components": "^8.0.4",
+    "@tailwindcss/vite": "^4.1.13",
     "@tanstack/react-query": "^5.85.5",
     "@tanstack/react-virtual": "^3.13.12",
     "@testing-library/dom": "^10.4.0",
@@ -171,21 +184,31 @@
     "@truto/turndown-plugin-gfm": "^1.0.2",
     "@tryfabric/martian": "^1.2.4",
     "@types/cli-progress": "^3",
-    "@types/express": "^5.0.3",
+    "@types/content-type": "^1.1.9",
+    "@types/cors": "^2.8.19",
+    "@types/diff": "^7",
+    "@types/express": "^5",
     "@types/fs-extra": "^11",
     "@types/he": "^1",
+    "@types/html-to-text": "^9",
     "@types/lodash": "^4.17.5",
     "@types/markdown-it": "^14",
     "@types/md5": "^2.3.5",
+    "@types/mime-types": "^3",
     "@types/node": "^22.17.1",
     "@types/pako": "^1.0.2",
     "@types/react": "^19.0.12",
     "@types/react-dom": "^19.0.4",
     "@types/react-infinite-scroll-component": "^5.0.0",
     "@types/react-transition-group": "^4.4.12",
+    "@types/react-window": "^1",
+    "@types/swagger-jsdoc": "^6",
+    "@types/swagger-ui-express": "^4.1.8",
     "@types/tinycolor2": "^1",
     "@types/turndown": "^5.0.5",
+    "@types/uuid": "^10.0.0",
     "@types/word-extractor": "^1",
+    "@typescript/native-preview": "latest",
     "@uiw/codemirror-extensions-langs": "^4.25.1",
     "@uiw/codemirror-themes-all": "^4.25.1",
     "@uiw/react-codemirror": "^4.25.1",
@@ -197,15 +220,18 @@
     "@viz-js/lang-dot": "^1.0.5",
     "@viz-js/viz": "^3.14.0",
     "@xyflow/react": "^12.4.4",
-    "ai": "^5.0.29",
+    "ai": "^5.0.68",
     "antd": "patch:antd@npm%3A5.27.0#~/.yarn/patches/antd-npm-5.27.0-aa91c36546.patch",
     "archiver": "^7.0.1",
     "async-mutex": "^0.5.0",
     "axios": "^1.7.3",
     "browser-image-compression": "^2.0.2",
     "chardet": "^2.1.0",
+    "check-disk-space": "3.4.0",
+    "cheerio": "^1.1.2",
     "chokidar": "^4.0.3",
     "cli-progress": "^3.12.0",
+    "clsx": "^2.1.1",
     "code-inspector-plugin": "^0.20.14",
     "color": "^5.0.0",
     "concurrently": "^9.2.1",
@@ -217,9 +243,12 @@
     "docx": "^9.0.2",
     "dompurify": "^3.2.6",
     "dotenv-cli": "^7.4.2",
-    "electron": "37.4.0",
+    "drizzle-kit": "^0.31.4",
+    "drizzle-orm": "^0.44.5",
+    "electron": "37.6.0",
     "electron-builder": "26.0.15",
     "electron-devtools-installer": "^3.2.0",
+    "electron-reload": "^2.0.0-alpha.1",
     "electron-store": "^8.2.0",
     "electron-updater": "6.6.4",
     "electron-vite": "4.0.0",
@@ -228,18 +257,24 @@
     "emoji-picker-element": "^1.22.1",
     "epub": "patch:epub@npm%3A1.3.0#~/.yarn/patches/epub-npm-1.3.0-8325494ffe.patch",
     "eslint": "^9.22.0",
+    "eslint-plugin-import-zod": "^1.2.0",
+    "eslint-plugin-oxlint": "^1.15.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-unused-imports": "^4.1.4",
+    "express": "^5.1.0",
+    "express-validator": "^7.2.1",
     "fast-diff": "^1.3.0",
     "fast-xml-parser": "^5.2.0",
     "fetch-socks": "1.3.2",
+    "framer-motion": "^12.23.12",
     "franc-min": "^6.2.0",
     "fs-extra": "^11.2.0",
     "google-auth-library": "^9.15.1",
     "he": "^1.2.0",
     "html-tags": "^5.1.0",
     "html-to-image": "^1.11.13",
+    "html-to-text": "^9.0.5",
     "htmlparser2": "^10.0.0",
     "husky": "^9.1.7",
     "i18next": "^23.11.5",
@@ -256,15 +291,17 @@
     "markdown-it": "^14.1.0",
     "mermaid": "^11.10.1",
     "mime": "^4.0.4",
+    "mime-types": "^3.0.1",
     "motion": "^12.10.5",
     "notion-helper": "^1.3.22",
     "npx-scope-finder": "^1.2.0",
     "openai": "patch:openai@npm%3A5.12.2#~/.yarn/patches/openai-npm-5.12.2-30b075401c.patch",
+    "oxlint": "^1.22.0",
+    "oxlint-tsgolint": "^0.2.0",
     "p-queue": "^8.1.0",
     "pdf-lib": "^1.17.1",
+    "pdf-parse": "^1.1.1",
     "playwright": "^1.52.0",
-    "prettier": "^3.5.3",
-    "prettier-plugin-sort-json": "^4.1.1",
     "proxy-agent": "^6.5.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -274,6 +311,7 @@
     "react-infinite-scroll-component": "^6.1.0",
     "react-json-view": "^1.21.3",
     "react-markdown": "^10.1.0",
+    "react-player": "^3.3.1",
     "react-redux": "^9.1.2",
     "react-router": "6",
     "react-router-dom": "6",
@@ -293,21 +331,24 @@
     "remark-math": "^6.0.0",
     "remove-markdown": "^0.6.2",
     "rollup-plugin-visualizer": "^5.12.0",
-    "sass": "^1.88.0",
     "shiki": "^3.12.0",
     "strict-url-sanitise": "^0.0.1",
     "string-width": "^7.2.0",
     "striptags": "^3.2.0",
     "styled-components": "^6.1.11",
+    "swagger-ui-express": "^5.0.1",
+    "swr": "^2.3.6",
+    "tailwindcss": "^4.1.13",
     "tar": "^7.4.3",
     "tiny-pinyin": "^1.3.2",
     "tokenx": "^1.1.0",
     "tsx": "^4.20.3",
     "turndown-plugin-gfm": "^1.0.2",
-    "typescript": "^5.6.2",
+    "tw-animate-css": "^1.3.8",
+    "typescript": "~5.8.2",
     "undici": "6.21.2",
     "unified": "^11.0.5",
-    "uuid": "^10.0.0",
+    "uuid": "^13.0.0",
     "vite": "npm:rolldown-vite@latest",
     "vitest": "^3.2.4",
     "webdav": "^5.8.0",
@@ -315,9 +356,11 @@
     "winston-daily-rotate-file": "^5.0.0",
     "word-extractor": "^1.0.4",
     "y-protocols": "^1.0.6",
+    "yaml": "^2.8.1",
     "yjs": "^13.6.27",
+    "youtubei.js": "^15.0.1",
     "zipread": "^1.3.3",
-    "zod": "^3.25.74"
+    "zod": "^4.1.5"
   },
   "resolutions": {
     "@codemirror/language": "6.11.3",
@@ -329,6 +372,7 @@
     "app-builder-lib@npm:26.0.13": "patch:app-builder-lib@npm%3A26.0.13#~/.yarn/patches/app-builder-lib-npm-26.0.13-a064c9e1d0.patch",
     "app-builder-lib@npm:26.0.15": "patch:app-builder-lib@npm%3A26.0.15#~/.yarn/patches/app-builder-lib-npm-26.0.15-360e5b0476.patch",
     "atomically@npm:^1.7.0": "patch:atomically@npm%3A1.7.0#~/.yarn/patches/atomically-npm-1.7.0-e742e5293b.patch",
+    "esbuild": "^0.25.0",
     "file-stream-rotator@npm:^0.6.1": "patch:file-stream-rotator@npm%3A0.6.1#~/.yarn/patches/file-stream-rotator-npm-0.6.1-eab45fb13d.patch",
     "libsql@npm:^0.4.4": "patch:libsql@npm%3A0.4.7#~/.yarn/patches/libsql-npm-0.4.7-444e260fb1.patch",
     "node-abi": "4.12.0",
@@ -336,24 +380,20 @@
     "openai@npm:^4.87.3": "patch:openai@npm%3A5.12.2#~/.yarn/patches/openai-npm-5.12.2-30b075401c.patch",
     "pdf-parse@npm:1.1.1": "patch:pdf-parse@npm%3A1.1.1#~/.yarn/patches/pdf-parse-npm-1.1.1-04a6109b2a.patch",
     "pkce-challenge@npm:^4.1.0": "patch:pkce-challenge@npm%3A4.1.0#~/.yarn/patches/pkce-challenge-npm-4.1.0-fbc51695a3.patch",
+    "tar-fs": "^2.1.4",
     "undici": "6.21.2",
     "vite": "npm:rolldown-vite@latest",
     "tesseract.js@npm:*": "patch:tesseract.js@npm%3A6.0.1#~/.yarn/patches/tesseract.js-npm-6.0.1-2562a7e46d.patch",
-    "@img/sharp-darwin-arm64": "0.34.3",
-    "@img/sharp-darwin-x64": "0.34.3",
-    "@img/sharp-linux-arm": "0.34.3",
-    "@img/sharp-linux-arm64": "0.34.3",
-    "@img/sharp-linux-x64": "0.34.3",
-    "@img/sharp-win32-x64": "0.34.3"
+    "@ai-sdk/google@npm:2.0.20": "patch:@ai-sdk/google@npm%3A2.0.20#~/.yarn/patches/@ai-sdk-google-npm-2.0.20-b9102f9d54.patch"
   },
   "packageManager": "yarn@4.9.1",
   "lint-staged": {
     "*.{js,jsx,ts,tsx,cjs,mjs,cts,mts}": [
-      "prettier --write",
+      "biome format --write --no-errors-on-unmatched",
       "eslint --fix"
     ],
-    "*.{json,yml,yaml,css,scss,html}": [
-      "prettier --write"
+    "*.{json,yml,yaml,css,html}": [
+      "biome format --write --no-errors-on-unmatched"
     ]
   }
 }

packages/aiCore/examples/hub-provider-usage.ts

@@ -1,103 +0,0 @@
-/**
- * Hub Provider 使用示例
- *
- * 演示如何使用简化后的Hub Provider功能来路由到多个底层provider
- */
-
-import { createHubProvider, initializeProvider, providerRegistry } from '../src/index'
-
-async function demonstrateHubProvider() {
-  try {
-    // 1. 初始化底层providers
-    console.log('📦 初始化底层providers...')
-
-    initializeProvider('openai', {
-      apiKey: process.env.OPENAI_API_KEY || 'sk-test-key'
-    })
-
-    initializeProvider('anthropic', {
-      apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-test-key'
-    })
-
-    // 2. 创建Hub Provider（自动包含所有已初始化的providers）
-    console.log('🌐 创建Hub Provider...')
-
-    const aihubmixProvider = createHubProvider({
-      hubId: 'aihubmix',
-      debug: true
-    })
-
-    // 3. 注册Hub Provider
-    providerRegistry.registerProvider('aihubmix', aihubmixProvider)
-
-    console.log('✅ Hub Provider "aihubmix" 注册成功')
-
-    // 4. 使用Hub Provider访问不同的模型
-    console.log('\n🚀 使用Hub模型...')
-
-    // 通过Hub路由到OpenAI
-    const openaiModel = providerRegistry.languageModel('aihubmix:openai:gpt-4')
-    console.log('✓ OpenAI模型已获取:', openaiModel.modelId)
-
-    // 通过Hub路由到Anthropic
-    const anthropicModel = providerRegistry.languageModel('aihubmix:anthropic:claude-3.5-sonnet')
-    console.log('✓ Anthropic模型已获取:', anthropicModel.modelId)
-
-    // 5. 演示错误处理
-    console.log('\n❌ 演示错误处理...')
-
-    try {
-      // 尝试访问未初始化的provider
-      providerRegistry.languageModel('aihubmix:google:gemini-pro')
-    } catch (error) {
-      console.log('预期错误:', error.message)
-    }
-
-    try {
-      // 尝试使用错误的模型ID格式
-      providerRegistry.languageModel('aihubmix:invalid-format')
-    } catch (error) {
-      console.log('预期错误:', error.message)
-    }
-
-    // 6. 多个Hub Provider示例
-    console.log('\n🔄 创建多个Hub Provider...')
-
-    const localHubProvider = createHubProvider({
-      hubId: 'local-ai'
-    })
-
-    providerRegistry.registerProvider('local-ai', localHubProvider)
-    console.log('✅ Hub Provider "local-ai" 注册成功')
-
-    console.log('\n🎉 Hub Provider演示完成！')
-  } catch (error) {
-    console.error('💥 演示过程中发生错误:', error)
-  }
-}
-
-// 演示简化的使用方式
-function simplifiedUsageExample() {
-  console.log('\n📝 简化使用示例:')
-  console.log(`
-// 1. 初始化providers
-initializeProvider('openai', { apiKey: 'sk-xxx' })
-initializeProvider('anthropic', { apiKey: 'sk-ant-xxx' })
-
-// 2. 创建并注册Hub Provider
-const hubProvider = createHubProvider({ hubId: 'aihubmix' })
-providerRegistry.registerProvider('aihubmix', hubProvider)
-
-// 3. 直接使用
-const model1 = providerRegistry.languageModel('aihubmix:openai:gpt-4')
-const model2 = providerRegistry.languageModel('aihubmix:anthropic:claude-3.5-sonnet')
-`)
-}
-
-// 运行演示
-if (require.main === module) {
-  demonstrateHubProvider()
-  simplifiedUsageExample()
-}
-
-export { demonstrateHubProvider, simplifiedUsageExample }

packages/aiCore/examples/image-generation.ts

@@ -1,167 +0,0 @@
-/**
- * Image Generation Example
- * 演示如何使用 aiCore 的文生图功能
- */
-
-import { createExecutor, generateImage } from '../src/index'
-
-async function main() {
-  // 方式1: 使用执行器实例
-  console.log('📸 创建 OpenAI 图像生成执行器...')
-  const executor = createExecutor('openai', {
-    apiKey: process.env.OPENAI_API_KEY!
-  })
-
-  try {
-    console.log('🎨 使用执行器生成图像...')
-    const result1 = await executor.generateImage('dall-e-3', {
-      prompt: 'A futuristic cityscape at sunset with flying cars',
-      size: '1024x1024',
-      n: 1
-    })
-
-    console.log('✅ 图像生成成功!')
-    console.log('📊 结果:', {
-      imagesCount: result1.images.length,
-      mediaType: result1.image.mediaType,
-      hasBase64: !!result1.image.base64,
-      providerMetadata: result1.providerMetadata
-    })
-  } catch (error) {
-    console.error('❌ 执行器生成失败:', error)
-  }
-
-  // 方式2: 使用直接调用 API
-  try {
-    console.log('🎨 使用直接 API 生成图像...')
-    const result2 = await generateImage('openai', { apiKey: process.env.OPENAI_API_KEY! }, 'dall-e-3', {
-      prompt: 'A magical forest with glowing mushrooms and fairy lights',
-      aspectRatio: '16:9',
-      providerOptions: {
-        openai: {
-          quality: 'hd',
-          style: 'vivid'
-        }
-      }
-    })
-
-    console.log('✅ 直接 API 生成成功!')
-    console.log('📊 结果:', {
-      imagesCount: result2.images.length,
-      mediaType: result2.image.mediaType,
-      hasBase64: !!result2.image.base64
-    })
-  } catch (error) {
-    console.error('❌ 直接 API 生成失败:', error)
-  }
-
-  // 方式3: 支持其他提供商 (Google Imagen)
-  if (process.env.GOOGLE_API_KEY) {
-    try {
-      console.log('🎨 使用 Google Imagen 生成图像...')
-      const googleExecutor = createExecutor('google', {
-        apiKey: process.env.GOOGLE_API_KEY!
-      })
-
-      const result3 = await googleExecutor.generateImage('imagen-3.0-generate-002', {
-        prompt: 'A serene mountain lake at dawn with mist rising from the water',
-        aspectRatio: '1:1'
-      })
-
-      console.log('✅ Google Imagen 生成成功!')
-      console.log('📊 结果:', {
-        imagesCount: result3.images.length,
-        mediaType: result3.image.mediaType,
-        hasBase64: !!result3.image.base64
-      })
-    } catch (error) {
-      console.error('❌ Google Imagen 生成失败:', error)
-    }
-  }
-
-  // 方式4: 支持插件系统
-  const pluginExample = async () => {
-    console.log('🔌 演示插件系统...')
-
-    // 创建一个示例插件，用于修改提示词
-    const promptEnhancerPlugin = {
-      name: 'prompt-enhancer',
-      transformParams: async (params: any) => {
-        console.log('🔧 插件: 增强提示词...')
-        return {
-          ...params,
-          prompt: `${params.prompt}, highly detailed, cinematic lighting, 4K resolution`
-        }
-      },
-      transformResult: async (result: any) => {
-        console.log('🔧 插件: 处理结果...')
-        return {
-          ...result,
-          enhanced: true
-        }
-      }
-    }
-
-    const executorWithPlugin = createExecutor(
-      'openai',
-      {
-        apiKey: process.env.OPENAI_API_KEY!
-      },
-      [promptEnhancerPlugin]
-    )
-
-    try {
-      const result4 = await executorWithPlugin.generateImage('dall-e-3', {
-        prompt: 'A cute robot playing in a garden'
-      })
-
-      console.log('✅ 插件系统生成成功!')
-      console.log('📊 结果:', {
-        imagesCount: result4.images.length,
-        enhanced: (result4 as any).enhanced,
-        mediaType: result4.image.mediaType
-      })
-    } catch (error) {
-      console.error('❌ 插件系统生成失败:', error)
-    }
-  }
-
-  await pluginExample()
-}
-
-// 错误处理演示
-async function errorHandlingExample() {
-  console.log('⚠️  演示错误处理...')
-
-  try {
-    const executor = createExecutor('openai', {
-      apiKey: 'invalid-key'
-    })
-
-    await executor.generateImage('dall-e-3', {
-      prompt: 'Test image'
-    })
-  } catch (error: any) {
-    console.log('✅ 成功捕获错误:', error.constructor.name)
-    console.log('📋 错误信息:', error.message)
-    console.log('🏷️  提供商ID:', error.providerId)
-    console.log('🏷️  模型ID:', error.modelId)
-  }
-}
-
-// 运行示例
-if (require.main === module) {
-  main()
-    .then(() => {
-      console.log('🎉 所有示例完成!')
-      return errorHandlingExample()
-    })
-    .then(() => {
-      console.log('🎯 示例程序结束')
-      process.exit(0)
-    })
-    .catch((error) => {
-      console.error('💥 程序执行出错:', error)
-      process.exit(1)
-    })
-}

packages/aiCore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cherrystudio/ai-core",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.1",
   "description": "Cherry Studio AI Core - Unified AI Provider Interface Based on Vercel AI SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,16 +36,15 @@
     "ai": "^5.0.26"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^2.0.5",
-    "@ai-sdk/azure": "^2.0.16",
-    "@ai-sdk/deepseek": "^1.0.9",
-    "@ai-sdk/google": "^2.0.7",
-    "@ai-sdk/openai": "^2.0.19",
-    "@ai-sdk/openai-compatible": "^1.0.9",
+    "@ai-sdk/anthropic": "^2.0.27",
+    "@ai-sdk/azure": "^2.0.49",
+    "@ai-sdk/deepseek": "^1.0.23",
+    "@ai-sdk/openai": "^2.0.48",
+    "@ai-sdk/openai-compatible": "^1.0.22",
     "@ai-sdk/provider": "^2.0.0",
-    "@ai-sdk/provider-utils": "^3.0.4",
-    "@ai-sdk/xai": "^2.0.9",
-    "zod": "^3.25.0"
+    "@ai-sdk/provider-utils": "^3.0.12",
+    "@ai-sdk/xai": "^2.0.26",
+    "zod": "^4.1.5"
   },
   "devDependencies": {
     "tsdown": "^0.12.9",

packages/aiCore/src/core/models/ModelResolver.ts

@@ -84,7 +84,6 @@ export class ModelResolver {
    */
   private resolveTraditionalModel(providerId: string, modelId: string): LanguageModelV2 {
     const fullModelId = `${providerId}${DEFAULT_SEPARATOR}${modelId}`
-    console.log('fullModelId', fullModelId)
     return globalRegistryManagement.languageModel(fullModelId as any)
   }
 

packages/aiCore/src/core/options/factory.ts

@@ -59,7 +59,7 @@ export function createGoogleOptions(options: ExtractProviderOptions<'google'>) {
 /**
  * 创建OpenRouter供应商选项的便捷函数
  */
-export function createOpenRouterOptions(options: ExtractProviderOptions<'openrouter'>) {
+export function createOpenRouterOptions(options: ExtractProviderOptions<'openrouter'> | Record<string, any>) {
   return createProviderOptions('openrouter', options)
 }
 

packages/aiCore/src/core/options/openrouter.ts

@@ -1,38 +0,0 @@
-export type OpenRouterProviderOptions = {
-  models?: string[]
-
-  /**
-   * https://openrouter.ai/docs/use-cases/reasoning-tokens
-   * One of `max_tokens` or `effort` is required.
-   * If `exclude` is true, reasoning will be removed from the response. Default is false.
-   */
-  reasoning?: {
-    exclude?: boolean
-  } & (
-    | {
-        max_tokens: number
-      }
-    | {
-        effort: 'high' | 'medium' | 'low'
-      }
-  )
-
-  /**
-   * A unique identifier representing your end-user, which can
-   * help OpenRouter to monitor and detect abuse.
-   */
-  user?: string
-
-  extraBody?: Record<string, unknown>
-
-  /**
-   * Enable usage accounting to get detailed token usage information.
-   * https://openrouter.ai/docs/use-cases/usage-accounting
-   */
-  usage?: {
-    /**
-     * When true, includes token usage information in the response.
-     */
-    include: boolean
-  }
-}

packages/aiCore/src/core/options/types.ts

@@ -2,9 +2,8 @@ import { type AnthropicProviderOptions } from '@ai-sdk/anthropic'
 import { type GoogleGenerativeAIProviderOptions } from '@ai-sdk/google'
 import { type OpenAIResponsesProviderOptions } from '@ai-sdk/openai'
 import { type SharedV2ProviderMetadata } from '@ai-sdk/provider'
-
-import { type OpenRouterProviderOptions } from './openrouter'
-import { type XaiProviderOptions } from './xai'
+import { type XaiProviderOptions } from '@ai-sdk/xai'
+import { type OpenRouterProviderOptions } from '@openrouter/ai-sdk-provider'
 
 export type ProviderOptions<T extends keyof SharedV2ProviderMetadata> = SharedV2ProviderMetadata[T]
 

packages/aiCore/src/core/options/xai.ts

@@ -1,86 +0,0 @@
-// copy from @ai-sdk/xai/xai-chat-options.ts
-// 如果@ai-sdk/xai暴露出了xaiProviderOptions就删除这个文件
-
-import * as z from 'zod/v4'
-
-const webSourceSchema = z.object({
-  type: z.literal('web'),
-  country: z.string().length(2).optional(),
-  excludedWebsites: z.array(z.string()).max(5).optional(),
-  allowedWebsites: z.array(z.string()).max(5).optional(),
-  safeSearch: z.boolean().optional()
-})
-
-const xSourceSchema = z.object({
-  type: z.literal('x'),
-  xHandles: z.array(z.string()).optional()
-})
-
-const newsSourceSchema = z.object({
-  type: z.literal('news'),
-  country: z.string().length(2).optional(),
-  excludedWebsites: z.array(z.string()).max(5).optional(),
-  safeSearch: z.boolean().optional()
-})
-
-const rssSourceSchema = z.object({
-  type: z.literal('rss'),
-  links: z.array(z.url()).max(1) // currently only supports one RSS link
-})
-
-const searchSourceSchema = z.discriminatedUnion('type', [
-  webSourceSchema,
-  xSourceSchema,
-  newsSourceSchema,
-  rssSourceSchema
-])
-
-export const xaiProviderOptions = z.object({
-  /**
-   * reasoning effort for reasoning models
-   * only supported by grok-3-mini and grok-3-mini-fast models
-   */
-  reasoningEffort: z.enum(['low', 'high']).optional(),
-
-  searchParameters: z
-    .object({
-      /**
-       * search mode preference
-       * - "off": disables search completely
-       * - "auto": model decides whether to search (default)
-       * - "on": always enables search
-       */
-      mode: z.enum(['off', 'auto', 'on']),
-
-      /**
-       * whether to return citations in the response
-       * defaults to true
-       */
-      returnCitations: z.boolean().optional(),
-
-      /**
-       * start date for search data (ISO8601 format: YYYY-MM-DD)
-       */
-      fromDate: z.string().optional(),
-
-      /**
-       * end date for search data (ISO8601 format: YYYY-MM-DD)
-       */
-      toDate: z.string().optional(),
-
-      /**
-       * maximum number of search results to consider
-       * defaults to 20
-       */
-      maxSearchResults: z.number().min(1).max(50).optional(),
-
-      /**
-       * data sources to search from
-       * defaults to ["web", "x"] if not specified
-       */
-      sources: z.array(searchSourceSchema).optional()
-    })
-    .optional()
-})
-
-export type XaiProviderOptions = z.infer<typeof xaiProviderOptions>

packages/aiCore/src/core/plugins/built-in/googleToolsPlugin/index.ts

@@ -0,0 +1,38 @@
+import { google } from '@ai-sdk/google'
+
+import { definePlugin } from '../../'
+import type { AiRequestContext } from '../../types'
+
+const toolNameMap = {
+  googleSearch: 'google_search',
+  urlContext: 'url_context',
+  codeExecution: 'code_execution'
+} as const
+
+type ToolConfigKey = keyof typeof toolNameMap
+type ToolConfig = { googleSearch?: boolean; urlContext?: boolean; codeExecution?: boolean }
+
+export const googleToolsPlugin = (config?: ToolConfig) =>
+  definePlugin({
+    name: 'googleToolsPlugin',
+    transformParams: <T>(params: T, context: AiRequestContext): T => {
+      const { providerId } = context
+      if (providerId === 'google' && config) {
+        if (typeof params === 'object' && params !== null) {
+          const typedParams = params as T & { tools?: Record<string, unknown> }
+
+          if (!typedParams.tools) {
+            typedParams.tools = {}
+          }
+          // 使用类型安全的方式遍历配置
+          ;(Object.keys(config) as ToolConfigKey[]).forEach((key) => {
+            if (config[key] && key in toolNameMap && key in google.tools) {
+              const toolName = toolNameMap[key]
+              typedParams.tools![toolName] = google.tools[key]({})
+            }
+          })
+        }
+      }
+      return params
+    }
+  })

packages/aiCore/src/core/plugins/built-in/index.ts

@@ -4,7 +4,12 @@
  */
 export const BUILT_IN_PLUGIN_PREFIX = 'built-in:'
 
+export { googleToolsPlugin } from './googleToolsPlugin'
 export { createLoggingPlugin } from './logging'
 export { createPromptToolUsePlugin } from './toolUsePlugin/promptToolUsePlugin'
-export type { PromptToolUseConfig, ToolUseRequestContext, ToolUseResult } from './toolUsePlugin/type'
-export { webSearchPlugin } from './webSearchPlugin'
+export type {
+  PromptToolUseConfig,
+  ToolUseRequestContext,
+  ToolUseResult
+} from './toolUsePlugin/type'
+export { webSearchPlugin, type WebSearchPluginConfig } from './webSearchPlugin'

packages/aiCore/src/core/plugins/built-in/toolUsePlugin/StreamEventManager.ts

@@ -27,10 +27,20 @@ export class StreamEventManager {
   /**
    * 发送步骤完成事件
    */
-  sendStepFinishEvent(controller: StreamController, chunk: any): void {
+  sendStepFinishEvent(
+    controller: StreamController,
+    chunk: any,
+    context: AiRequestContext,
+    finishReason: string = 'stop'
+  ): void {
+    // 累加当前步骤的 usage
+    if (chunk.usage && context.accumulatedUsage) {
+      this.accumulateUsage(context.accumulatedUsage, chunk.usage)
+    }
+
     controller.enqueue({
       type: 'finish-step',
-      finishReason: 'stop',
+      finishReason,
       response: chunk.response,
       usage: chunk.usage,
       providerMetadata: chunk.providerMetadata
@@ -43,28 +53,32 @@ export class StreamEventManager {
   async handleRecursiveCall(
     controller: StreamController,
     recursiveParams: any,
-    context: AiRequestContext,
-    stepId: string
+    context: AiRequestContext
   ): Promise<void> {
-    try {
-      console.log('[MCP Prompt] Starting recursive call after tool execution...')
+    // try {
+    // 重置工具执行状态，准备处理新的步骤
+    context.hasExecutedToolsInCurrentStep = false
 
     const recursiveResult = await context.recursiveCall(recursiveParams)
 
     if (recursiveResult && recursiveResult.fullStream) {
-        await this.pipeRecursiveStream(controller, recursiveResult.fullStream)
+      await this.pipeRecursiveStream(controller, recursiveResult.fullStream, context)
     } else {
       console.warn('[MCP Prompt] No fullstream found in recursive result:', recursiveResult)
     }
-    } catch (error) {
-      this.handleRecursiveCallError(controller, error, stepId)
-    }
+    // } catch (error) {
+    //   this.handleRecursiveCallError(controller, error, stepId)
+    // }
   }
 
   /**
    * 将递归流的数据传递到当前流
    */
-  private async pipeRecursiveStream(controller: StreamController, recursiveStream: ReadableStream): Promise<void> {
+  private async pipeRecursiveStream(
+    controller: StreamController,
+    recursiveStream: ReadableStream,
+    context?: AiRequestContext
+  ): Promise<void> {
     const reader = recursiveStream.getReader()
     try {
       while (true) {
@@ -73,9 +87,16 @@ export class StreamEventManager {
           break
         }
         if (value.type === 'finish') {
-          // 迭代的流不发finish
+          // 迭代的流不发finish，但需要累加其 usage
+          if (value.usage && context?.accumulatedUsage) {
+            this.accumulateUsage(context.accumulatedUsage, value.usage)
+          }
           break
         }
+        // 对于 finish-step 类型，累加其 usage
+        if (value.type === 'finish-step' && value.usage && context?.accumulatedUsage) {
+          this.accumulateUsage(context.accumulatedUsage, value.usage)
+        }
         // 将递归流的数据传递到当前流
         controller.enqueue(value)
       }
@@ -87,25 +108,25 @@ export class StreamEventManager {
   /**
    * 处理递归调用错误
    */
-  private handleRecursiveCallError(controller: StreamController, error: unknown, stepId: string): void {
-    console.error('[MCP Prompt] Recursive call failed:', error)
+  // private handleRecursiveCallError(controller: StreamController, error: unknown): void {
+  //   console.error('[MCP Prompt] Recursive call failed:', error)
 
-    // 使用 AI SDK 标准错误格式，但不中断流
-    controller.enqueue({
-      type: 'error',
-      error: {
-        message: error instanceof Error ? error.message : String(error),
-        name: error instanceof Error ? error.name : 'RecursiveCallError'
-      }
-    })
+  //   // 使用 AI SDK 标准错误格式，但不中断流
+  //   controller.enqueue({
+  //     type: 'error',
+  //     error: {
+  //       message: error instanceof Error ? error.message : String(error),
+  //       name: error instanceof Error ? error.name : 'RecursiveCallError'
+  //     }
+  //   })
 
-    // 继续发送文本增量，保持流的连续性
-    controller.enqueue({
-      type: 'text-delta',
-      id: stepId,
-      text: '\n\n[工具执行后递归调用失败，继续对话...]'
-    })
-  }
+  //   // // 继续发送文本增量，保持流的连续性
+  //   // controller.enqueue({
+  //   //   type: 'text-delta',
+  //   //   id: stepId,
+  //   //   text: '\n\n[工具执行后递归调用失败，继续对话...]'
+  //   // })
+  // }
 
   /**
    * 构建递归调用的参数
@@ -136,4 +157,18 @@ export class StreamEventManager {
 
     return recursiveParams
   }
+
+  /**
+   * 累加 usage 数据
+   */
+  private accumulateUsage(target: any, source: any): void {
+    if (!target || !source) return
+
+    // 累加各种 token 类型
+    target.inputTokens = (target.inputTokens || 0) + (source.inputTokens || 0)
+    target.outputTokens = (target.outputTokens || 0) + (source.outputTokens || 0)
+    target.totalTokens = (target.totalTokens || 0) + (source.totalTokens || 0)
+    target.reasoningTokens = (target.reasoningTokens || 0) + (source.reasoningTokens || 0)
+    target.cachedInputTokens = (target.cachedInputTokens || 0) + (source.cachedInputTokens || 0)
+  }
 }

packages/aiCore/src/core/plugins/built-in/toolUsePlugin/ToolExecutor.ts

@@ -4,7 +4,7 @@
  * 负责工具的执行、结果格式化和相关事件发送
  * 从 promptToolUsePlugin.ts 中提取出来以降低复杂度
  */
-import type { ToolSet } from 'ai'
+import type { ToolSet, TypedToolError } from 'ai'
 
 import type { ToolUseResult } from './type'
 
@@ -38,7 +38,6 @@ export class ToolExecutor {
     controller: StreamController
   ): Promise<ExecutedResult[]> {
     const executedResults: ExecutedResult[] = []
-
     for (const toolUse of toolUses) {
       try {
         const tool = tools[toolUse.toolName]
@@ -46,17 +45,12 @@ export class ToolExecutor {
           throw new Error(`Tool "${toolUse.toolName}" has no execute method`)
         }
 
-        // 发送工具调用开始事件
-        this.sendToolStartEvents(controller, toolUse)
-
-        console.log(`[MCP Prompt Stream] Executing tool: ${toolUse.toolName}`, toolUse.arguments)
-
         // 发送 tool-call 事件
         controller.enqueue({
           type: 'tool-call',
           toolCallId: toolUse.id,
           toolName: toolUse.toolName,
-          input: tool.inputSchema
+          input: toolUse.arguments
         })
 
         const result = await tool.execute(toolUse.arguments, {
@@ -111,45 +105,46 @@ export class ToolExecutor {
   /**
    * 发送工具调用开始相关事件
    */
-  private sendToolStartEvents(controller: StreamController, toolUse: ToolUseResult): void {
-    // 发送 tool-input-start 事件
-    controller.enqueue({
-      type: 'tool-input-start',
-      id: toolUse.id,
-      toolName: toolUse.toolName
-    })
-  }
+  // private sendToolStartEvents(controller: StreamController, toolUse: ToolUseResult): void {
+  //   // 发送 tool-input-start 事件
+  //   controller.enqueue({
+  //     type: 'tool-input-start',
+  //     id: toolUse.id,
+  //     toolName: toolUse.toolName
+  //   })
+  // }
 
   /**
    * 处理工具执行错误
    */
-  private handleToolError(
+  private handleToolError<T extends ToolSet>(
     toolUse: ToolUseResult,
     error: unknown,
     controller: StreamController
-    // _tools: ToolSet
   ): ExecutedResult {
     // 使用 AI SDK 标准错误格式
-    // const toolError: TypedToolError<typeof _tools> = {
-    //   type: 'tool-error',
-    //   toolCallId: toolUse.id,
-    //   toolName: toolUse.toolName,
-    //   input: toolUse.arguments,
-    //   error: error instanceof Error ? error.message : String(error)
-    // }
+    const toolError: TypedToolError<T> = {
+      type: 'tool-error',
+      toolCallId: toolUse.id,
+      toolName: toolUse.toolName,
+      input: toolUse.arguments,
+      error
+    }
 
-    // controller.enqueue(toolError)
+    controller.enqueue(toolError)
 
     // 发送标准错误事件
-    controller.enqueue({
-      type: 'error',
-      error: error instanceof Error ? error.message : String(error)
-    })
+    // controller.enqueue({
+    //   type: 'tool-error',
+    //   toolCallId: toolUse.id,
+    //   error: error instanceof Error ? error.message : String(error),
+    //   input: toolUse.arguments
+    // })
 
     return {
       toolCallId: toolUse.id,
       toolName: toolUse.toolName,
-      result: error instanceof Error ? error.message : String(error),
+      result: error,
       isError: true
     }
   }

packages/aiCore/src/core/plugins/built-in/toolUsePlugin/promptToolUsePlugin.ts

@@ -8,9 +8,19 @@ import type { TextStreamPart, ToolSet } from 'ai'
 import { definePlugin } from '../../index'
 import type { AiRequestContext } from '../../types'
 import { StreamEventManager } from './StreamEventManager'
+import { type TagConfig, TagExtractor } from './tagExtraction'
 import { ToolExecutor } from './ToolExecutor'
 import { PromptToolUseConfig, ToolUseResult } from './type'
 
+/**
+ * 工具使用标签配置
+ */
+const TOOL_USE_TAG_CONFIG: TagConfig = {
+  openingTag: '<tool_use>',
+  closingTag: '</tool_use>',
+  separator: '\n'
+}
+
 /**
  * 默认系统提示符模板（提取自 Cherry Studio）
  */
@@ -146,8 +156,10 @@ Assistant: The population of Shanghai is 26 million, while Guangzhou has a popul
 /**
  * 构建可用工具部分（提取自 Cherry Studio）
  */
-function buildAvailableTools(tools: ToolSet): string {
+function buildAvailableTools(tools: ToolSet): string | null {
   const availableTools = Object.keys(tools)
+  if (availableTools.length === 0) return null
+  const result = availableTools
     .map((toolName: string) => {
       const tool = tools[toolName]
       return `
@@ -162,7 +174,7 @@ function buildAvailableTools(tools: ToolSet): string {
     })
     .join('\n')
   return `<tools>
-${availableTools}
+${result}
 </tools>`
 }
 
@@ -171,6 +183,7 @@ ${availableTools}
  */
 function defaultBuildSystemPrompt(userSystemPrompt: string, tools: ToolSet): string {
   const availableTools = buildAvailableTools(tools)
+  if (availableTools === null) return userSystemPrompt
 
   const fullPrompt = DEFAULT_SYSTEM_PROMPT.replace('{{ TOOL_USE_EXAMPLES }}', DEFAULT_TOOL_USE_EXAMPLES)
     .replace('{{ AVAILABLE_TOOLS }}', availableTools)
@@ -248,40 +261,76 @@ export const createPromptToolUsePlugin = (config: PromptToolUseConfig = {}) => {
         return params
       }
 
-      context.mcpTools = params.tools
-      console.log('tools stored in context', params.tools)
+      // 分离 provider-defined 和其他类型的工具
+      const providerDefinedTools: ToolSet = {}
+      const promptTools: ToolSet = {}
 
-      // 构建系统提示符
+      for (const [toolName, tool] of Object.entries(params.tools as ToolSet)) {
+        if (tool.type === 'provider-defined') {
+          // provider-defined 类型的工具保留在 tools 参数中
+          providerDefinedTools[toolName] = tool
+        } else {
+          // 其他工具转换为 prompt 模式
+          promptTools[toolName] = tool
+        }
+      }
+
+      // 只有当有非 provider-defined 工具时才保存到 context
+      if (Object.keys(promptTools).length > 0) {
+        context.mcpTools = promptTools
+      }
+
+      // 构建系统提示符（只包含非 provider-defined 工具）
       const userSystemPrompt = typeof params.system === 'string' ? params.system : ''
-      const systemPrompt = buildSystemPrompt(userSystemPrompt, params.tools)
+      const systemPrompt = buildSystemPrompt(userSystemPrompt, promptTools)
       let systemMessage: string | null = systemPrompt
-      console.log('config.context', context)
       if (config.createSystemMessage) {
         // 🎯 如果用户提供了自定义处理函数，使用它
         systemMessage = config.createSystemMessage(systemPrompt, params, context)
       }
 
-      // 移除 tools，改为 prompt 模式
+      // 保留 provider-defined tools，移除其他 tools
       const transformedParams = {
         ...params,
         ...(systemMessage ? { system: systemMessage } : {}),
-        tools: undefined
+        tools: Object.keys(providerDefinedTools).length > 0 ? providerDefinedTools : undefined
       }
       context.originalParams = transformedParams
-      console.log('transformedParams', transformedParams)
       return transformedParams
     },
     transformStream: (_: any, context: AiRequestContext) => () => {
       let textBuffer = ''
-      let stepId = ''
+      // let stepId = ''
 
+      // 如果没有需要 prompt 模式处理的工具，直接返回原始流
       if (!context.mcpTools) {
-        throw new Error('No tools available')
+        return new TransformStream()
       }
 
-      // 创建工具执行器和流事件管理器
+      // 从 context 中获取或初始化 usage 累加器
+      if (!context.accumulatedUsage) {
+        context.accumulatedUsage = {
+          inputTokens: 0,
+          outputTokens: 0,
+          totalTokens: 0,
+          reasoningTokens: 0,
+          cachedInputTokens: 0
+        }
+      }
+
+      // 创建工具执行器、流事件管理器和标签提取器
       const toolExecutor = new ToolExecutor()
       const streamEventManager = new StreamEventManager()
+      const tagExtractor = new TagExtractor(TOOL_USE_TAG_CONFIG)
+
+      // 在context中初始化工具执行状态，避免递归调用时状态丢失
+      if (!context.hasExecutedToolsInCurrentStep) {
+        context.hasExecutedToolsInCurrentStep = false
+      }
+
+      // 用于hold text-start事件，直到确认有非工具标签内容
+      let pendingTextStart: TextStreamPart<TOOLS> | null = null
+      let hasStartedText = false
 
       type TOOLS = NonNullable<typeof context.mcpTools>
       return new TransformStream<TextStreamPart<TOOLS>, TextStreamPart<TOOLS>>({
@@ -289,60 +338,66 @@ export const createPromptToolUsePlugin = (config: PromptToolUseConfig = {}) => {
           chunk: TextStreamPart<TOOLS>,
           controller: TransformStreamDefaultController<TextStreamPart<TOOLS>>
         ) {
-          // 收集文本内容
+          // Hold住text-start事件，直到确认有非工具标签内容
+          if ((chunk as any).type === 'text-start') {
+            pendingTextStart = chunk
+            return
+          }
+
+          // text-delta阶段：收集文本内容并过滤工具标签
           if (chunk.type === 'text-delta') {
             textBuffer += chunk.text || ''
-            stepId = chunk.id || ''
-            controller.enqueue(chunk)
-            return
+            // stepId = chunk.id || ''
+
+            // 使用TagExtractor过滤工具标签，只传递非标签内容到UI层
+            const extractionResults = tagExtractor.processText(chunk.text || '')
+
+            for (const result of extractionResults) {
+              // 只传递非标签内容到UI层
+              if (!result.isTagContent && result.content) {
+                // 如果还没有发送text-start且有pending的text-start，先发送它
+                if (!hasStartedText && pendingTextStart) {
+                  controller.enqueue(pendingTextStart)
+                  hasStartedText = true
+                  pendingTextStart = null
                 }
 
-          if (chunk.type === 'text-end' || chunk.type === 'finish-step') {
-            const tools = context.mcpTools
-            if (!tools || Object.keys(tools).length === 0) {
-              controller.enqueue(chunk)
-              return
+                const filteredChunk = {
+                  ...chunk,
+                  text: result.content
+                }
+                controller.enqueue(filteredChunk)
+              }
             }
-
-            // 解析工具调用
-            const { results: parsedTools, content: parsedContent } = parseToolUse(textBuffer, tools)
-            const validToolUses = parsedTools.filter((t) => t.status === 'pending')
-
-            // 如果没有有效的工具调用，直接传递原始事件
-            if (validToolUses.length === 0) {
-              controller.enqueue(chunk)
             return
           }
 
           if (chunk.type === 'text-end') {
-              controller.enqueue({
-                type: 'text-end',
-                id: stepId,
-                providerMetadata: {
-                  text: {
-                    value: parsedContent
+            // 只有当已经发送了text-start时才发送text-end
+            if (hasStartedText) {
+              controller.enqueue(chunk)
             }
-                }
-              })
             return
           }
 
-            controller.enqueue({
-              ...chunk,
-              finishReason: 'tool-calls'
-            })
+          if (chunk.type === 'finish-step') {
+            // 统一在finish-step阶段检查并执行工具调用
+            const tools = context.mcpTools
+            if (tools && Object.keys(tools).length > 0 && !context.hasExecutedToolsInCurrentStep) {
+              // 解析完整的textBuffer来检测工具调用
+              const { results: parsedTools } = parseToolUse(textBuffer, tools)
+              const validToolUses = parsedTools.filter((t) => t.status === 'pending')
 
-            // 发送步骤开始事件
-            streamEventManager.sendStepStartEvent(controller)
+              if (validToolUses.length > 0) {
+                context.hasExecutedToolsInCurrentStep = true
 
-            // 执行工具调用
+                // 执行工具调用（不需要手动发送 start-step，外部流已经处理）
                 const executedResults = await toolExecutor.executeTools(validToolUses, tools, controller)
 
-            // 发送步骤完成事件
-            streamEventManager.sendStepFinishEvent(controller, chunk)
+                // 发送步骤完成事件，使用 tool-calls 作为 finishReason
+                streamEventManager.sendStepFinishEvent(controller, chunk, context, 'tool-calls')
 
                 // 处理递归调用
-            if (validToolUses.length > 0) {
                 const toolResultsText = toolExecutor.formatToolResults(executedResults)
                 const recursiveParams = streamEventManager.buildRecursiveParams(
                   context,
@@ -351,21 +406,38 @@ export const createPromptToolUsePlugin = (config: PromptToolUseConfig = {}) => {
                   tools
                 )
 
-              await streamEventManager.handleRecursiveCall(controller, recursiveParams, context, stepId)
+                await streamEventManager.handleRecursiveCall(controller, recursiveParams, context)
+                return
               }
+            }
+
+            // 如果没有执行工具调用，直接传递原始finish-step事件
+            controller.enqueue(chunk)
 
             // 清理状态
             textBuffer = ''
             return
           }
 
-          // 对于其他类型的事件，直接传递
+          // 处理 finish 类型，使用累加后的 totalUsage
+          if (chunk.type === 'finish') {
+            controller.enqueue({
+              ...chunk,
+              totalUsage: context.accumulatedUsage
+            })
+            return
+          }
+
+          // 对于其他类型的事件，直接传递（不包括text-start，已在上面处理）
+          if ((chunk as any).type !== 'text-start') {
             controller.enqueue(chunk)
+          }
         },
 
         flush() {
-          // 流结束时的清理工作
-          console.log('[MCP Prompt] Stream ended, cleaning up...')
+          // 清理pending状态
+          pendingTextStart = null
+          hasStartedText = false
         }
       })
     }

packages/aiCore/src/core/plugins/built-in/webSearchPlugin/helper.ts

@@ -1,15 +1,26 @@
 import { anthropic } from '@ai-sdk/anthropic'
 import { google } from '@ai-sdk/google'
 import { openai } from '@ai-sdk/openai'
+import { InferToolInput, InferToolOutput, type Tool } from 'ai'
 
 import { ProviderOptionsMap } from '../../../options/types'
+import { OpenRouterSearchConfig } from './openrouter'
 
 /**
  * 从 AI SDK 的工具函数中提取参数类型，以确保类型安全。
  */
-type OpenAISearchConfig = Parameters<typeof openai.tools.webSearchPreview>[0]
-type AnthropicSearchConfig = Parameters<typeof anthropic.tools.webSearch_20250305>[0]
-type GoogleSearchConfig = Parameters<typeof google.tools.googleSearch>[0]
+export type OpenAISearchConfig = NonNullable<Parameters<typeof openai.tools.webSearch>[0]>
+export type OpenAISearchPreviewConfig = NonNullable<Parameters<typeof openai.tools.webSearchPreview>[0]>
+export type AnthropicSearchConfig = NonNullable<Parameters<typeof anthropic.tools.webSearch_20250305>[0]>
+export type GoogleSearchConfig = NonNullable<Parameters<typeof google.tools.googleSearch>[0]>
+export type XAISearchConfig = NonNullable<ProviderOptionsMap['xai']['searchParameters']>
+
+type NormalizeTool<T> = T extends Tool<infer INPUT, infer OUTPUT> ? Tool<INPUT, OUTPUT> : Tool<any, any>
+
+type AnthropicWebSearchTool = NormalizeTool<ReturnType<typeof anthropic.tools.webSearch_20250305>>
+type OpenAIWebSearchTool = NormalizeTool<ReturnType<typeof openai.tools.webSearch>>
+type OpenAIChatWebSearchTool = NormalizeTool<ReturnType<typeof openai.tools.webSearchPreview>>
+type GoogleWebSearchTool = NormalizeTool<ReturnType<typeof google.tools.googleSearch>>
 
 /**
  * 插件初始化时接收的完整配置对象
@@ -18,10 +29,12 @@ type GoogleSearchConfig = Parameters<typeof google.tools.googleSearch>[0]
  */
 export interface WebSearchPluginConfig {
   openai?: OpenAISearchConfig
+  'openai-chat'?: OpenAISearchPreviewConfig
   anthropic?: AnthropicSearchConfig
   xai?: ProviderOptionsMap['xai']['searchParameters']
   google?: GoogleSearchConfig
   'google-vertex'?: GoogleSearchConfig
+  openrouter?: OpenRouterSearchConfig
 }
 
 /**
@@ -31,6 +44,7 @@ export const DEFAULT_WEB_SEARCH_CONFIG: WebSearchPluginConfig = {
   google: {},
   'google-vertex': {},
   openai: {},
+  'openai-chat': {},
   xai: {
     mode: 'on',
     returnCitations: true,
@@ -39,29 +53,44 @@ export const DEFAULT_WEB_SEARCH_CONFIG: WebSearchPluginConfig = {
   },
   anthropic: {
     maxUses: 5
+  },
+  openrouter: {
+    plugins: [
+      {
+        id: 'web',
+        max_results: 5
+      }
+    ]
   }
 }
 
 export type WebSearchToolOutputSchema = {
   // Anthropic 工具 - 手动定义
-  anthropicWebSearch: Array<{
-    url: string
-    title: string
-    pageAge: string | null
-    encryptedContent: string
-    type: string
-  }>
+  anthropic: InferToolOutput<AnthropicWebSearchTool>
 
   // OpenAI 工具 - 基于实际输出
-  openaiWebSearch: {
+  // TODO: 上游定义不规范,是unknown
+  // openai: InferToolOutput<ReturnType<typeof openai.tools.webSearch>>
+  openai: {
+    status: 'completed' | 'failed'
+  }
+  'openai-chat': {
     status: 'completed' | 'failed'
   }
-
   // Google 工具
-  googleSearch: {
+  // TODO: 上游定义不规范,是unknown
+  // google: InferToolOutput<ReturnType<typeof google.tools.googleSearch>>
+  google: {
     webSearchQueries?: string[]
     groundingChunks?: Array<{
       web?: { uri: string; title: string }
     }>
   }
 }
+
+export type WebSearchToolInputSchema = {
+  anthropic: InferToolInput<AnthropicWebSearchTool>
+  openai: InferToolInput<OpenAIWebSearchTool>
+  google: InferToolInput<GoogleWebSearchTool>
+  'openai-chat': InferToolInput<OpenAIChatWebSearchTool>
+}

packages/aiCore/src/core/plugins/built-in/webSearchPlugin/index.ts

@@ -6,7 +6,7 @@ import { anthropic } from '@ai-sdk/anthropic'
 import { google } from '@ai-sdk/google'
 import { openai } from '@ai-sdk/openai'
 
-import { createXaiOptions, mergeProviderOptions } from '../../../options'
+import { createOpenRouterOptions, createXaiOptions, mergeProviderOptions } from '../../../options'
 import { definePlugin } from '../../'
 import type { AiRequestContext } from '../../types'
 import { DEFAULT_WEB_SEARCH_CONFIG, WebSearchPluginConfig } from './helper'
@@ -27,7 +27,14 @@ export const webSearchPlugin = (config: WebSearchPluginConfig = DEFAULT_WEB_SEAR
         case 'openai': {
           if (config.openai) {
             if (!params.tools) params.tools = {}
-            params.tools.web_search_preview = openai.tools.webSearchPreview(config.openai)
+            params.tools.web_search = openai.tools.webSearch(config.openai)
+          }
+          break
+        }
+        case 'openai-chat': {
+          if (config['openai-chat']) {
+            if (!params.tools) params.tools = {}
+            params.tools.web_search_preview = openai.tools.webSearchPreview(config['openai-chat'])
           }
           break
         }
@@ -56,6 +63,14 @@ export const webSearchPlugin = (config: WebSearchPluginConfig = DEFAULT_WEB_SEAR
           }
           break
         }
+
+        case 'openrouter': {
+          if (config.openrouter) {
+            const searchOptions = createOpenRouterOptions(config.openrouter)
+            params.providerOptions = mergeProviderOptions(params.providerOptions, searchOptions)
+          }
+          break
+        }
       }
 
       return params

packages/aiCore/src/core/plugins/built-in/webSearchPlugin/openrouter.ts

@@ -0,0 +1,26 @@
+export type OpenRouterSearchConfig = {
+  plugins?: Array<{
+    id: 'web'
+    /**
+     * Maximum number of search results to include (default: 5)
+     */
+    max_results?: number
+    /**
+     * Custom search prompt to guide the search query
+     */
+    search_prompt?: string
+  }>
+  /**
+   * Built-in web search options for models that support native web search
+   */
+  web_search_options?: {
+    /**
+     * Maximum number of search results to include
+     */
+    max_results?: number
+    /**
+     * Custom search prompt to guide the search query
+     */
+    search_prompt?: string
+  }
+}

packages/aiCore/src/core/plugins/index.ts

@@ -1,5 +1,8 @@
 // 核心类型和接口
 export type { AiPlugin, AiRequestContext, HookResult, PluginManagerConfig } from './types'
+import type { ImageModelV2 } from '@ai-sdk/provider'
+import type { LanguageModel } from 'ai'
+
 import type { ProviderId } from '../providers'
 import type { AiPlugin, AiRequestContext } from './types'
 
@@ -9,16 +12,16 @@ export { PluginManager } from './manager'
 // 工具函数
 export function createContext<T extends ProviderId>(
   providerId: T,
-  modelId: string,
+  model: LanguageModel | ImageModelV2,
   originalParams: any
 ): AiRequestContext {
   return {
     providerId,
-    modelId,
+    model,
     originalParams,
     metadata: {},
     startTime: Date.now(),
-    requestId: `${providerId}-${modelId}-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    requestId: `${providerId}-${typeof model === 'string' ? model : model?.modelId}-${Date.now()}-${Math.random().toString(36).slice(2)}`,
     // 占位
     recursiveCall: () => Promise.resolve(null)
   }

packages/aiCore/src/core/plugins/types.ts

@@ -14,7 +14,7 @@ export type RecursiveCallFn = (newParams: any) => Promise<any>
  */
 export interface AiRequestContext {
   providerId: ProviderId
-  modelId: string
+  model: LanguageModel | ImageModelV2
   originalParams: any
   metadata: Record<string, any>
   startTime: number

packages/aiCore/src/core/providers/schemas.ts

@@ -9,8 +9,10 @@ import { createDeepSeek } from '@ai-sdk/deepseek'
 import { createGoogleGenerativeAI } from '@ai-sdk/google'
 import { createOpenAI, type OpenAIProviderSettings } from '@ai-sdk/openai'
 import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
+import { LanguageModelV2 } from '@ai-sdk/provider'
 import { createXai } from '@ai-sdk/xai'
-import { customProvider, type Provider } from 'ai'
+import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+import { customProvider, Provider } from 'ai'
 import * as z from 'zod'
 
 /**
@@ -25,7 +27,8 @@ export const baseProviderIds = [
   'xai',
   'azure',
   'azure-responses',
-  'deepseek'
+  'deepseek',
+  'openrouter'
 ] as const
 
 /**
@@ -38,14 +41,16 @@ export const baseProviderIdSchema = z.enum(baseProviderIds)
  */
 export type BaseProviderId = z.infer<typeof baseProviderIdSchema>
 
-export const baseProviderSchema = z.object({
-  id: baseProviderIdSchema,
-  name: z.string(),
-  creator: z.function().args(z.any()).returns(z.any()) as z.ZodType<(options: any) => Provider>,
-  supportsImageGeneration: z.boolean()
-})
+export const isBaseProvider = (id: ProviderId): id is BaseProviderId => {
+  return baseProviderIdSchema.safeParse(id).success
+}
 
-export type BaseProvider = z.infer<typeof baseProviderSchema>
+type BaseProvider = {
+  id: BaseProviderId
+  name: string
+  creator: (options: any) => Provider | LanguageModelV2
+  supportsImageGeneration: boolean
+}
 
 /**
  * 基础 Providers 定义
@@ -121,6 +126,12 @@ export const baseProviders = [
     name: 'DeepSeek',
     creator: createDeepSeek,
     supportsImageGeneration: false
+  },
+  {
+    id: 'openrouter',
+    name: 'OpenRouter',
+    creator: createOpenRouter,
+    supportsImageGeneration: true
   }
 ] as const satisfies BaseProvider[]
 
@@ -148,7 +159,12 @@ export const providerConfigSchema = z
   .object({
     id: customProviderIdSchema, // 只允许自定义ID
     name: z.string().min(1),
-    creator: z.function().optional(),
+    creator: z
+      .function({
+        input: z.any(),
+        output: z.any()
+      })
+      .optional(),
     import: z.function().optional(),
     creatorFunctionName: z.string().optional(),
     supportsImageGeneration: z.boolean().default(false),

packages/aiCore/src/core/runtime/executor.ts

@@ -4,12 +4,12 @@
  */
 import { ImageModelV2, LanguageModelV2, LanguageModelV2Middleware } from '@ai-sdk/provider'
 import {
-  experimental_generateImage as generateImage,
-  generateObject,
-  generateText,
+  experimental_generateImage as _generateImage,
+  generateObject as _generateObject,
+  generateText as _generateText,
   LanguageModel,
-  streamObject,
-  streamText
+  streamObject as _streamObject,
+  streamText as _streamText
 } from 'ai'
 
 import { globalModelResolver } from '../models'
@@ -18,7 +18,14 @@ import { type AiPlugin, type AiRequestContext, definePlugin } from '../plugins'
 import { type ProviderId } from '../providers'
 import { ImageGenerationError, ImageModelResolutionError } from './errors'
 import { PluginEngine } from './pluginEngine'
-import { type RuntimeConfig } from './types'
+import type {
+  generateImageParams,
+  generateObjectParams,
+  generateTextParams,
+  RuntimeConfig,
+  streamObjectParams,
+  streamTextParams
+} from './types'
 
 export class RuntimeExecutor<T extends ProviderId = ProviderId> {
   public pluginEngine: PluginEngine<T>
@@ -75,12 +82,12 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
    * 流式文本生成
    */
   async streamText(
-    params: Parameters<typeof streamText>[0],
+    params: streamTextParams,
     options?: {
       middlewares?: LanguageModelV2Middleware[]
     }
-  ): Promise<ReturnType<typeof streamText>> {
-    const { model, ...restParams } = params
+  ): Promise<ReturnType<typeof _streamText>> {
+    const { model } = params
 
     // 根据 model 类型决定插件配置
     if (typeof model === 'string') {
@@ -94,19 +101,16 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
 
     return this.pluginEngine.executeStreamWithPlugins(
       'streamText',
-      model,
-      restParams,
-      async (resolvedModel, transformedParams, streamTransforms) => {
+      params,
+      (resolvedModel, transformedParams, streamTransforms) => {
         const experimental_transform =
           params?.experimental_transform ?? (streamTransforms.length > 0 ? streamTransforms : undefined)
 
-        const finalParams = {
-          model: resolvedModel,
+        return _streamText({
           ...transformedParams,
+          model: resolvedModel,
           experimental_transform
-        } as Parameters<typeof streamText>[0]
-
-        return await streamText(finalParams)
+        })
       }
     )
   }
@@ -117,12 +121,12 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
    * 生成文本
    */
   async generateText(
-    params: Parameters<typeof generateText>[0],
+    params: generateTextParams,
     options?: {
       middlewares?: LanguageModelV2Middleware[]
     }
-  ): Promise<ReturnType<typeof generateText>> {
-    const { model, ...restParams } = params
+  ): Promise<ReturnType<typeof _generateText>> {
+    const { model } = params
 
     // 根据 model 类型决定插件配置
     if (typeof model === 'string') {
@@ -134,12 +138,10 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
       this.pluginEngine.usePlugins([this.createConfigureContextPlugin()])
     }
 
-    return this.pluginEngine.executeWithPlugins(
+    return this.pluginEngine.executeWithPlugins<Parameters<typeof _generateText>[0], ReturnType<typeof _generateText>>(
       'generateText',
-      model,
-      restParams,
-      async (resolvedModel, transformedParams) =>
-        generateText({ model: resolvedModel, ...transformedParams } as Parameters<typeof generateText>[0])
+      params,
+      (resolvedModel, transformedParams) => _generateText({ ...transformedParams, model: resolvedModel })
     )
   }
 
@@ -147,12 +149,12 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
    * 生成结构化对象
    */
   async generateObject(
-    params: Parameters<typeof generateObject>[0],
+    params: generateObjectParams,
     options?: {
       middlewares?: LanguageModelV2Middleware[]
     }
-  ): Promise<ReturnType<typeof generateObject>> {
-    const { model, ...restParams } = params
+  ): Promise<ReturnType<typeof _generateObject>> {
+    const { model } = params
 
     // 根据 model 类型决定插件配置
     if (typeof model === 'string') {
@@ -164,25 +166,23 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
       this.pluginEngine.usePlugins([this.createConfigureContextPlugin()])
     }
 
-    return this.pluginEngine.executeWithPlugins(
+    return this.pluginEngine.executeWithPlugins<generateObjectParams, ReturnType<typeof _generateObject>>(
       'generateObject',
-      model,
-      restParams,
-      async (resolvedModel, transformedParams) =>
-        generateObject({ model: resolvedModel, ...transformedParams } as Parameters<typeof generateObject>[0])
+      params,
+      async (resolvedModel, transformedParams) => _generateObject({ ...transformedParams, model: resolvedModel })
     )
   }
 
   /**
    * 流式生成结构化对象
    */
-  async streamObject(
-    params: Parameters<typeof streamObject>[0],
+  streamObject(
+    params: streamObjectParams,
     options?: {
       middlewares?: LanguageModelV2Middleware[]
     }
-  ): Promise<ReturnType<typeof streamObject>> {
-    const { model, ...restParams } = params
+  ): Promise<ReturnType<typeof _streamObject>> {
+    const { model } = params
 
     // 根据 model 类型决定插件配置
     if (typeof model === 'string') {
@@ -194,23 +194,17 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
       this.pluginEngine.usePlugins([this.createConfigureContextPlugin()])
     }
 
-    return this.pluginEngine.executeWithPlugins(
-      'streamObject',
-      model,
-      restParams,
-      async (resolvedModel, transformedParams) =>
-        streamObject({ model: resolvedModel, ...transformedParams } as Parameters<typeof streamObject>[0])
+    return this.pluginEngine.executeStreamWithPlugins('streamObject', params, (resolvedModel, transformedParams) =>
+      _streamObject({ ...transformedParams, model: resolvedModel })
     )
   }
 
   /**
    * 生成图像
    */
-  async generateImage(
-    params: Omit<Parameters<typeof generateImage>[0], 'model'> & { model: string | ImageModelV2 }
-  ): Promise<ReturnType<typeof generateImage>> {
+  generateImage(params: generateImageParams): Promise<ReturnType<typeof _generateImage>> {
     try {
-      const { model, ...restParams } = params
+      const { model } = params
 
       // 根据 model 类型决定插件配置
       if (typeof model === 'string') {
@@ -219,13 +213,8 @@ export class RuntimeExecutor<T extends ProviderId = ProviderId> {
         this.pluginEngine.usePlugins([this.createConfigureContextPlugin()])
       }
 
-      return await this.pluginEngine.executeImageWithPlugins(
-        'generateImage',
-        model,
-        restParams,
-        async (resolvedModel, transformedParams) => {
-          return await generateImage({ model: resolvedModel, ...transformedParams })
-        }
+      return this.pluginEngine.executeImageWithPlugins('generateImage', params, (resolvedModel, transformedParams) =>
+        _generateImage({ ...transformedParams, model: resolvedModel })
       )
     } catch (error) {
       if (error instanceof Error) {

packages/aiCore/src/core/runtime/pluginEngine.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @eslint-react/naming-convention/context-name */
 import { ImageModelV2 } from '@ai-sdk/provider'
-import { LanguageModel } from 'ai'
+import { experimental_generateImage, generateObject, generateText, LanguageModel, streamObject, streamText } from 'ai'
 
 import { type AiPlugin, createContext, PluginManager } from '../plugins'
 import { type ProviderId } from '../providers/types'
@@ -62,17 +62,19 @@ export class PluginEngine<T extends ProviderId = ProviderId> {
    * 执行带插件的操作（非流式）
    * 提供给AiExecutor使用
    */
-  async executeWithPlugins<TParams, TResult>(
+  async executeWithPlugins<
+    TParams extends Parameters<typeof generateText | typeof generateObject>[0],
+    TResult extends ReturnType<typeof generateText | typeof generateObject>
+  >(
     methodName: string,
-    model: LanguageModel,
     params: TParams,
-    executor: (model: LanguageModel, transformedParams: TParams) => Promise<TResult>,
+    executor: (model: LanguageModel, transformedParams: TParams) => TResult,
     _context?: ReturnType<typeof createContext>
   ): Promise<TResult> {
     // 统一处理模型解析
     let resolvedModel: LanguageModel | undefined
     let modelId: string
-
+    const { model } = params
     if (typeof model === 'string') {
       // 字符串：需要通过插件解析
       modelId = model
@@ -83,13 +85,13 @@ export class PluginEngine<T extends ProviderId = ProviderId> {
     }
 
     // 使用正确的createContext创建请求上下文
-    const context = _context ? _context : createContext(this.providerId, modelId, params)
+    const context = _context ? _context : createContext(this.providerId, model, params)
 
     // 🔥 为上下文添加递归调用能力
     context.recursiveCall = async (newParams: any): Promise<TResult> => {
       // 递归调用自身，重新走完整的插件流程
       context.isRecursiveCall = true
-      const result = await this.executeWithPlugins(methodName, model, newParams, executor, context)
+      const result = await this.executeWithPlugins(methodName, newParams, executor, context)
       context.isRecursiveCall = false
       return result
     }
@@ -138,17 +140,19 @@ export class PluginEngine<T extends ProviderId = ProviderId> {
    * 执行带插件的图像生成操作
    * 提供给AiExecutor使用
    */
-  async executeImageWithPlugins<TParams, TResult>(
+  async executeImageWithPlugins<
+    TParams extends Omit<Parameters<typeof experimental_generateImage>[0], 'model'> & { model: string | ImageModelV2 },
+    TResult extends ReturnType<typeof experimental_generateImage>
+  >(
     methodName: string,
-    model: ImageModelV2 | string,
     params: TParams,
-    executor: (model: ImageModelV2, transformedParams: TParams) => Promise<TResult>,
+    executor: (model: ImageModelV2, transformedParams: TParams) => TResult,
     _context?: ReturnType<typeof createContext>
   ): Promise<TResult> {
     // 统一处理模型解析
     let resolvedModel: ImageModelV2 | undefined
     let modelId: string
-
+    const { model } = params
     if (typeof model === 'string') {
       // 字符串：需要通过插件解析
       modelId = model
@@ -159,13 +163,13 @@ export class PluginEngine<T extends ProviderId = ProviderId> {
     }
 
     // 使用正确的createContext创建请求上下文
-    const context = _context ? _context : createContext(this.providerId, modelId, params)
+    const context = _context ? _context : createContext(this.providerId, model, params)
 
     // 🔥 为上下文添加递归调用能力
     context.recursiveCall = async (newParams: any): Promise<TResult> => {
       // 递归调用自身，重新走完整的插件流程
       context.isRecursiveCall = true
-      const result = await this.executeImageWithPlugins(methodName, model, newParams, executor, context)
+      const result = await this.executeImageWithPlugins(methodName, newParams, executor, context)
       context.isRecursiveCall = false
       return result
     }
@@ -214,17 +218,19 @@ export class PluginEngine<T extends ProviderId = ProviderId> {
    * 执行流式调用的通用逻辑（支持流转换器）
    * 提供给AiExecutor使用
    */
-  async executeStreamWithPlugins<TParams, TResult>(
+  async executeStreamWithPlugins<
+    TParams extends Parameters<typeof streamText | typeof streamObject>[0],
+    TResult extends ReturnType<typeof streamText | typeof streamObject>
+  >(
     methodName: string,
-    model: LanguageModel,
     params: TParams,
-    executor: (model: LanguageModel, transformedParams: TParams, streamTransforms: any[]) => Promise<TResult>,
+    executor: (model: LanguageModel, transformedParams: TParams, streamTransforms: any[]) => TResult,
     _context?: ReturnType<typeof createContext>
   ): Promise<TResult> {
     // 统一处理模型解析
     let resolvedModel: LanguageModel | undefined
     let modelId: string
-
+    const { model } = params
     if (typeof model === 'string') {
       // 字符串：需要通过插件解析
       modelId = model
@@ -235,13 +241,13 @@ export class PluginEngine<T extends ProviderId = ProviderId> {
     }
 
     // 创建请求上下文
-    const context = _context ? _context : createContext(this.providerId, modelId, params)
+    const context = _context ? _context : createContext(this.providerId, model, params)
 
     // 🔥 为上下文添加递归调用能力
     context.recursiveCall = async (newParams: any): Promise<TResult> => {
       // 递归调用自身，重新走完整的插件流程
       context.isRecursiveCall = true
-      const result = await this.executeStreamWithPlugins(methodName, model, newParams, executor, context)
+      const result = await this.executeStreamWithPlugins(methodName, newParams, executor, context)
       context.isRecursiveCall = false
       return result
     }

packages/aiCore/src/core/runtime/types.ts

@@ -1,6 +1,9 @@
 /**
  * Runtime 层类型定义
  */
+import { ImageModelV2 } from '@ai-sdk/provider'
+import { experimental_generateImage, generateObject, generateText, streamObject, streamText } from 'ai'
+
 import { type ModelConfig } from '../models/types'
 import { type AiPlugin } from '../plugins'
 import { type ProviderId } from '../providers/types'
@@ -13,3 +16,11 @@ export interface RuntimeConfig<T extends ProviderId = ProviderId> {
   providerSettings: ModelConfig<T>['providerSettings'] & { mode?: 'chat' | 'responses' }
   plugins?: AiPlugin[]
 }
+
+export type generateImageParams = Omit<Parameters<typeof experimental_generateImage>[0], 'model'> & {
+  model: string | ImageModelV2
+}
+export type generateObjectParams = Parameters<typeof generateObject>[0]
+export type generateTextParams = Parameters<typeof generateText>[0]
+export type streamObjectParams = Parameters<typeof streamObject>[0]
+export type streamTextParams = Parameters<typeof streamText>[0]

packages/aiCore/tsconfig.json

@@ -1,26 +1,21 @@
 {
   "compilerOptions": {
-    "target": "ES2020",
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "forceConsistentCasingInFileNames": true,
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "declaration": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "allowSyntheticDefaultImports": true,
     "noEmitOnError": false,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
+    "outDir": "./dist",
+    "resolveJsonModule": true,
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2020"
   },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
+  "exclude": ["node_modules", "dist"],
+  "include": ["src/**/*"]
 }

packages/extension-table-plus/package.json

@@ -67,13 +67,13 @@
     "dist"
   ],
   "devDependencies": {
+    "@biomejs/biome": "2.2.4",
     "@tiptap/core": "^3.2.0",
     "@tiptap/pm": "^3.2.0",
     "eslint": "^9.22.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-simple-import-sort": "^12.1.1",
     "eslint-plugin-unused-imports": "^4.1.4",
-    "prettier": "^3.5.3",
     "tsdown": "^0.13.3"
   },
   "peerDependencies": {
@@ -87,7 +87,7 @@
   },
   "scripts": {
     "build": "tsdown",
-    "lint": "prettier ./src/ --write && eslint --fix ./src/"
+    "lint": "biome format ./src/ --write && eslint --fix ./src/"
   },
   "packageManager": "yarn@4.9.1"
 }

packages/shared/IpcChannel.ts

@@ -5,9 +5,10 @@ export enum IpcChannel {
   App_SetLanguage = 'app:set-language',
   App_SetEnableSpellCheck = 'app:set-enable-spell-check',
   App_SetSpellCheckLanguages = 'app:set-spell-check-languages',
-  App_ShowUpdateDialog = 'app:show-update-dialog',
   App_CheckForUpdate = 'app:check-for-update',
+  App_QuitAndInstall = 'app:quit-and-install',
   App_Reload = 'app:reload',
+  App_Quit = 'app:quit',
   App_Info = 'app:info',
   App_Proxy = 'app:proxy',
   App_SetLaunchToTray = 'app:set-launch-to-tray',
@@ -33,10 +34,13 @@ export enum IpcChannel {
   App_GetBinaryPath = 'app:get-binary-path',
   App_InstallUvBinary = 'app:install-uv-binary',
   App_InstallBunBinary = 'app:install-bun-binary',
+  App_InstallOvmsBinary = 'app:install-ovms-binary',
   App_LogToMain = 'app:log-to-main',
   App_SaveData = 'app:save-data',
+  App_GetDiskInfo = 'app:get-disk-info',
   App_SetFullScreen = 'app:set-full-screen',
   App_IsFullScreen = 'app:is-full-screen',
+  App_GetSystemFonts = 'app:get-system-fonts',
 
   App_MacIsProcessTrusted = 'app:mac-is-process-trusted',
   App_MacRequestProcessTrust = 'app:mac-request-process-trust',
@@ -49,6 +53,7 @@ export enum IpcChannel {
 
   Webview_SetOpenLinkExternal = 'webview:set-open-link-external',
   Webview_SetSpellCheckEnabled = 'webview:set-spell-check-enabled',
+  Webview_SearchHotkey = 'webview:search-hotkey',
 
   // Open
   Open_Path = 'open:path',
@@ -83,10 +88,17 @@ export enum IpcChannel {
   Mcp_UploadDxt = 'mcp:upload-dxt',
   Mcp_AbortTool = 'mcp:abort-tool',
   Mcp_GetServerVersion = 'mcp:get-server-version',
-
+  Mcp_Progress = 'mcp:progress',
   // Python
   Python_Execute = 'python:execute',
 
+  // agent messages
+  AgentMessage_PersistExchange = 'agent-message:persist-exchange',
+  AgentMessage_GetHistory = 'agent-message:get-history',
+
+  // JavaScript
+  Js_Execute = 'js:execute',
+
   //copilot
   Copilot_GetAuthMessage = 'copilot:get-auth-message',
   Copilot_GetCopilotToken = 'copilot:get-copilot-token',
@@ -123,6 +135,12 @@ export enum IpcChannel {
   Windows_SetMinimumSize = 'window:set-minimum-size',
   Windows_Resize = 'window:resize',
   Windows_GetSize = 'window:get-size',
+  Windows_Minimize = 'window:minimize',
+  Windows_Maximize = 'window:maximize',
+  Windows_Unmaximize = 'window:unmaximize',
+  Windows_Close = 'window:close',
+  Windows_IsMaximized = 'window:is-maximized',
+  Windows_MaximizedChanged = 'window:maximized-changed',
 
   KnowledgeBase_Create = 'knowledge-base:create',
   KnowledgeBase_Reset = 'knowledge-base:reset',
@@ -174,6 +192,7 @@ export enum IpcChannel {
   File_ValidateNotesDirectory = 'file:validateNotesDirectory',
   File_StartWatcher = 'file:startWatcher',
   File_StopWatcher = 'file:stopWatcher',
+  File_ShowInFolder = 'file:showInFolder',
 
   // file service
   FileService_Upload = 'file-service:upload',
@@ -211,6 +230,7 @@ export enum IpcChannel {
   // system
   System_GetDeviceType = 'system:getDeviceType',
   System_GetHostname = 'system:getHostname',
+  System_GetCpuName = 'system:getCpuName',
 
   // DevTools
   System_ToggleDevTools = 'system:toggleDevTools',
@@ -218,7 +238,6 @@ export enum IpcChannel {
   // events
   BackupProgress = 'backup-progress',
   ThemeUpdated = 'theme:updated',
-  UpdateDownloadedCancelled = 'update-downloaded-cancelled',
   RestoreProgress = 'restore-progress',
   UpdateError = 'update-error',
   UpdateAvailable = 'update-available',
@@ -250,7 +269,6 @@ export enum IpcChannel {
 
   // Provider
   Provider_AddKey = 'provider:add-key',
-  Provider_GetClaudeCodePort = 'provider:get-claude-code-port',
 
   //Selection Assistant
   Selection_TextSelected = 'selection:text-selected',
@@ -297,12 +315,40 @@ export enum IpcChannel {
   TRACE_CLEAN_LOCAL_DATA = 'trace:cleanLocalData',
   TRACE_ADD_STREAM_MESSAGE = 'trace:addStreamMessage',
 
+  // API Server
+  ApiServer_Start = 'api-server:start',
+  ApiServer_Stop = 'api-server:stop',
+  ApiServer_Restart = 'api-server:restart',
+  ApiServer_GetStatus = 'api-server:get-status',
+  ApiServer_GetConfig = 'api-server:get-config',
+
+  // Anthropic OAuth
+  Anthropic_StartOAuthFlow = 'anthropic:start-oauth-flow',
+  Anthropic_CompleteOAuthWithCode = 'anthropic:complete-oauth-with-code',
+  Anthropic_CancelOAuthFlow = 'anthropic:cancel-oauth-flow',
+  Anthropic_GetAccessToken = 'anthropic:get-access-token',
+  Anthropic_HasCredentials = 'anthropic:has-credentials',
+  Anthropic_ClearCredentials = 'anthropic:clear-credentials',
+
   // CodeTools
   CodeTools_Run = 'code-tools:run',
+  CodeTools_GetAvailableTerminals = 'code-tools:get-available-terminals',
+  CodeTools_SetCustomTerminalPath = 'code-tools:set-custom-terminal-path',
+  CodeTools_GetCustomTerminalPath = 'code-tools:get-custom-terminal-path',
+  CodeTools_RemoveCustomTerminalPath = 'code-tools:remove-custom-terminal-path',
 
   // OCR
   OCR_ocr = 'ocr:ocr',
 
-  // Cherryin
-  Cherryin_GetSignature = 'cherryin:get-signature'
+  // OVMS
+  Ovms_AddModel = 'ovms:add-model',
+  Ovms_StopAddModel = 'ovms:stop-addmodel',
+  Ovms_GetModels = 'ovms:get-models',
+  Ovms_IsRunning = 'ovms:is-running',
+  Ovms_GetStatus = 'ovms:get-status',
+  Ovms_RunOVMS = 'ovms:run-ovms',
+  Ovms_StopOVMS = 'ovms:stop-ovms',
+
+  // CherryAI
+  Cherryai_GetSignature = 'cherryai:get-signature'
 }

packages/shared/agents/claudecode/types.ts

@@ -0,0 +1,12 @@
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk'
+import type { ContentBlockParam } from '@anthropic-ai/sdk/resources/messages'
+
+export type ClaudeCodeRawValue =
+  | {
+      type: string
+      session_id: string
+      slash_commands: string[]
+      tools: string[]
+      raw: Extract<SDKMessage, { type: 'system' }>
+    }
+  | ContentBlockParam

packages/shared/anthropic/index.ts

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Shared Anthropic AI client utilities for Cherry Studio
+ *
+ * This module provides functions for creating Anthropic SDK clients with different
+ * authentication methods (OAuth, API key) and building Claude Code system messages.
+ * It supports both standard Anthropic API and Anthropic Vertex AI endpoints.
+ *
+ * This shared module can be used by both main and renderer processes.
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import { TextBlockParam } from '@anthropic-ai/sdk/resources'
+import { loggerService } from '@logger'
+import { Provider } from '@types'
+import type { ModelMessage } from 'ai'
+
+const logger = loggerService.withContext('anthropic-sdk')
+
+const defaultClaudeCodeSystemPrompt = `You are Claude Code, Anthropic's official CLI for Claude.`
+
+const defaultClaudeCodeSystem: Array<TextBlockParam> = [
+  {
+    type: 'text',
+    text: defaultClaudeCodeSystemPrompt
+  }
+]
+
+/**
+ * Creates and configures an Anthropic SDK client based on the provider configuration.
+ *
+ * This function supports two authentication methods:
+ * 1. OAuth: Uses OAuth tokens passed as parameter
+ * 2. API Key: Uses traditional API key authentication
+ *
+ * For OAuth authentication, it includes Claude Code specific headers and beta features.
+ * For API key authentication, it uses the provider's configuration with custom headers.
+ *
+ * @param provider - The provider configuration containing authentication details
+ * @param oauthToken - Optional OAuth token for OAuth authentication
+ * @returns An initialized Anthropic or AnthropicVertex client
+ * @throws Error when OAuth token is not available for OAuth authentication
+ *
+ * @example
+ * ```typescript
+ * // OAuth authentication
+ * const oauthProvider = { authType: 'oauth' };
+ * const oauthClient = getSdkClient(oauthProvider, 'oauth-token-here');
+ *
+ * // API key authentication
+ * const apiKeyProvider = {
+ *   authType: 'apikey',
+ *   apiKey: 'your-api-key',
+ *   apiHost: 'https://api.anthropic.com'
+ * };
+ * const apiKeyClient = getSdkClient(apiKeyProvider);
+ * ```
+ */
+export function getSdkClient(
+  provider: Provider,
+  oauthToken?: string | null,
+  extraHeaders?: Record<string, string | string[]>
+): Anthropic {
+  if (provider.authType === 'oauth') {
+    if (!oauthToken) {
+      throw new Error('OAuth token is not available')
+    }
+    return new Anthropic({
+      authToken: oauthToken,
+      baseURL: 'https://api.anthropic.com',
+      dangerouslyAllowBrowser: true,
+      defaultHeaders: {
+        'Content-Type': 'application/json',
+        'anthropic-version': '2023-06-01',
+        'anthropic-beta':
+          'oauth-2025-04-20,claude-code-20250219,interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14',
+        'anthropic-dangerous-direct-browser-access': 'true',
+        'user-agent': 'claude-cli/1.0.118 (external, sdk-ts)',
+        'x-app': 'cli',
+        'x-stainless-retry-count': '0',
+        'x-stainless-timeout': '600',
+        'x-stainless-lang': 'js',
+        'x-stainless-package-version': '0.60.0',
+        'x-stainless-os': 'MacOS',
+        'x-stainless-arch': 'arm64',
+        'x-stainless-runtime': 'node',
+        'x-stainless-runtime-version': 'v22.18.0',
+        ...extraHeaders
+      }
+    })
+  }
+  const baseURL =
+    provider.type === 'anthropic'
+      ? provider.apiHost
+      : (provider.anthropicApiHost && provider.anthropicApiHost.trim()) || provider.apiHost
+
+  logger.debug('Anthropic API baseURL', { baseURL, providerId: provider.id })
+
+  if (provider.id === 'aihubmix') {
+    return new Anthropic({
+      apiKey: provider.apiKey,
+      baseURL,
+      dangerouslyAllowBrowser: true,
+      defaultHeaders: {
+        'anthropic-beta': 'output-128k-2025-02-19',
+        'APP-Code': 'MLTG2087',
+        ...provider.extra_headers,
+        ...extraHeaders
+      }
+    })
+  }
+
+  return new Anthropic({
+    apiKey: provider.apiKey,
+    authToken: provider.apiKey,
+    baseURL,
+    dangerouslyAllowBrowser: true,
+    defaultHeaders: {
+      'anthropic-beta': 'output-128k-2025-02-19',
+      ...provider.extra_headers
+    }
+  })
+}
+
+/**
+ * Builds and prepends the Claude Code system message to user-provided system messages.
+ *
+ * This function ensures that all interactions with Claude include the official Claude Code
+ * system prompt, which identifies the assistant as "Claude Code, Anthropic's official CLI for Claude."
+ *
+ * The function handles three cases:
+ * 1. No system message provided: Returns only the default Claude Code system message
+ * 2. String system message: Converts to array format and prepends Claude Code message
+ * 3. Array system message: Checks if Claude Code message exists and prepends if missing
+ *
+ * @param system - Optional user-provided system message (string or TextBlockParam array)
+ * @returns Combined system message with Claude Code prompt prepended
+ *
+ * ```
+ */
+export function buildClaudeCodeSystemMessage(system?: string | Array<TextBlockParam>): Array<TextBlockParam> {
+  if (!system) {
+    return defaultClaudeCodeSystem
+  }
+
+  if (typeof system === 'string') {
+    if (system.trim() === defaultClaudeCodeSystemPrompt || system.trim() === '') {
+      return defaultClaudeCodeSystem
+    } else {
+      return [...defaultClaudeCodeSystem, { type: 'text', text: system }]
+    }
+  }
+  if (Array.isArray(system)) {
+    const firstSystem = system[0]
+    if (firstSystem.type === 'text' && firstSystem.text.trim() === defaultClaudeCodeSystemPrompt) {
+      return system
+    } else {
+      return [...defaultClaudeCodeSystem, ...system]
+    }
+  }
+
+  return defaultClaudeCodeSystem
+}
+
+export function buildClaudeCodeSystemModelMessage(system?: string | Array<TextBlockParam>): Array<ModelMessage> {
+  const textBlocks = buildClaudeCodeSystemMessage(system)
+  return textBlocks.map((block) => ({
+    role: 'system',
+    content: block.text
+  }))
+}

packages/shared/config/constant.ts

@@ -216,5 +216,257 @@ export enum codeTools {
   qwenCode = 'qwen-code',
   claudeCode = 'claude-code',
   geminiCli = 'gemini-cli',
-  openaiCodex = 'openai-codex'
+  openaiCodex = 'openai-codex',
+  iFlowCli = 'iflow-cli',
+  githubCopilotCli = 'github-copilot-cli'
 }
+
+export enum terminalApps {
+  systemDefault = 'Terminal',
+  iterm2 = 'iTerm2',
+  kitty = 'kitty',
+  alacritty = 'Alacritty',
+  wezterm = 'WezTerm',
+  ghostty = 'Ghostty',
+  tabby = 'Tabby',
+  // Windows terminals
+  windowsTerminal = 'WindowsTerminal',
+  powershell = 'PowerShell',
+  cmd = 'CMD',
+  wsl = 'WSL'
+}
+
+export interface TerminalConfig {
+  id: string
+  name: string
+  bundleId?: string
+  customPath?: string // For user-configured terminal paths on Windows
+}
+
+export interface TerminalConfigWithCommand extends TerminalConfig {
+  command: (directory: string, fullCommand: string) => { command: string; args: string[] }
+}
+
+export const MACOS_TERMINALS: TerminalConfig[] = [
+  {
+    id: terminalApps.systemDefault,
+    name: 'Terminal',
+    bundleId: 'com.apple.Terminal'
+  },
+  {
+    id: terminalApps.iterm2,
+    name: 'iTerm2',
+    bundleId: 'com.googlecode.iterm2'
+  },
+  {
+    id: terminalApps.kitty,
+    name: 'kitty',
+    bundleId: 'net.kovidgoyal.kitty'
+  },
+  {
+    id: terminalApps.alacritty,
+    name: 'Alacritty',
+    bundleId: 'org.alacritty'
+  },
+  {
+    id: terminalApps.wezterm,
+    name: 'WezTerm',
+    bundleId: 'com.github.wez.wezterm'
+  },
+  {
+    id: terminalApps.ghostty,
+    name: 'Ghostty',
+    bundleId: 'com.mitchellh.ghostty'
+  },
+  {
+    id: terminalApps.tabby,
+    name: 'Tabby',
+    bundleId: 'org.tabby'
+  }
+]
+
+export const WINDOWS_TERMINALS: TerminalConfig[] = [
+  {
+    id: terminalApps.cmd,
+    name: 'Command Prompt'
+  },
+  {
+    id: terminalApps.powershell,
+    name: 'PowerShell'
+  },
+  {
+    id: terminalApps.windowsTerminal,
+    name: 'Windows Terminal'
+  },
+  {
+    id: terminalApps.wsl,
+    name: 'WSL (Ubuntu/Debian)'
+  },
+  {
+    id: terminalApps.alacritty,
+    name: 'Alacritty'
+  },
+  {
+    id: terminalApps.wezterm,
+    name: 'WezTerm'
+  }
+]
+
+export const WINDOWS_TERMINALS_WITH_COMMANDS: TerminalConfigWithCommand[] = [
+  {
+    id: terminalApps.cmd,
+    name: 'Command Prompt',
+    command: (_: string, fullCommand: string) => ({
+      command: 'cmd',
+      args: ['/c', 'start', 'cmd', '/k', fullCommand]
+    })
+  },
+  {
+    id: terminalApps.powershell,
+    name: 'PowerShell',
+    command: (_: string, fullCommand: string) => ({
+      command: 'cmd',
+      args: ['/c', 'start', 'powershell', '-NoExit', '-Command', `& '${fullCommand}'`]
+    })
+  },
+  {
+    id: terminalApps.windowsTerminal,
+    name: 'Windows Terminal',
+    command: (_: string, fullCommand: string) => ({
+      command: 'wt',
+      args: ['cmd', '/k', fullCommand]
+    })
+  },
+  {
+    id: terminalApps.wsl,
+    name: 'WSL (Ubuntu/Debian)',
+    command: (_: string, fullCommand: string) => {
+      // Start WSL in a new window and execute the batch file from within WSL using cmd.exe
+      // The batch file will run in Windows context but output will be in WSL terminal
+      return {
+        command: 'cmd',
+        args: ['/c', 'start', 'wsl', '-e', 'bash', '-c', `cmd.exe /c '${fullCommand}' ; exec bash`]
+      }
+    }
+  },
+  {
+    id: terminalApps.alacritty,
+    name: 'Alacritty',
+    customPath: '', // Will be set by user in settings
+    command: (_: string, fullCommand: string) => ({
+      command: 'alacritty', // Will be replaced with customPath if set
+      args: ['-e', 'cmd', '/k', fullCommand]
+    })
+  },
+  {
+    id: terminalApps.wezterm,
+    name: 'WezTerm',
+    customPath: '', // Will be set by user in settings
+    command: (_: string, fullCommand: string) => ({
+      command: 'wezterm', // Will be replaced with customPath if set
+      args: ['start', 'cmd', '/k', fullCommand]
+    })
+  }
+]
+
+// Helper function to escape strings for AppleScript
+const escapeForAppleScript = (str: string): string => {
+  // In AppleScript strings, backslashes and double quotes need to be escaped
+  // When passed through osascript -e with single quotes, we need:
+  // 1. Backslash: \ -> \\
+  // 2. Double quote: " -> \"
+  return str
+    .replace(/\\/g, '\\\\') // Escape backslashes first
+    .replace(/"/g, '\\"') // Then escape double quotes
+}
+
+export const MACOS_TERMINALS_WITH_COMMANDS: TerminalConfigWithCommand[] = [
+  {
+    id: terminalApps.systemDefault,
+    name: 'Terminal',
+    bundleId: 'com.apple.Terminal',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `open -na Terminal && sleep 0.5 && osascript -e 'tell application "Terminal" to activate' -e 'tell application "Terminal" to do script "${escapeForAppleScript(fullCommand)}" in front window'`
+      ]
+    })
+  },
+  {
+    id: terminalApps.iterm2,
+    name: 'iTerm2',
+    bundleId: 'com.googlecode.iterm2',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `open -na iTerm && sleep 0.8 && osascript -e 'on waitUntilRunning()\n  repeat 50 times\n    tell application "System Events"\n      if (exists process "iTerm2") then exit repeat\n    end tell\n    delay 0.1\n  end repeat\nend waitUntilRunning\n\nwaitUntilRunning()\n\ntell application "iTerm2"\n  if (count of windows) = 0 then\n    create window with default profile\n    delay 0.3\n  else\n    tell current window\n      create tab with default profile\n    end tell\n    delay 0.3\n  end if\n  tell current session of current window to write text "${escapeForAppleScript(fullCommand)}"\n  activate\nend tell'`
+      ]
+    })
+  },
+  {
+    id: terminalApps.kitty,
+    name: 'kitty',
+    bundleId: 'net.kovidgoyal.kitty',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `cd "${_directory}" && open -na kitty --args --directory="${_directory}" sh -c "${fullCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}; exec \\$SHELL" && sleep 0.5 && osascript -e 'tell application "kitty" to activate'`
+      ]
+    })
+  },
+  {
+    id: terminalApps.alacritty,
+    name: 'Alacritty',
+    bundleId: 'org.alacritty',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `open -na Alacritty --args --working-directory "${_directory}" -e sh -c "${fullCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}; exec \\$SHELL" && sleep 0.5 && osascript -e 'tell application "Alacritty" to activate'`
+      ]
+    })
+  },
+  {
+    id: terminalApps.wezterm,
+    name: 'WezTerm',
+    bundleId: 'com.github.wez.wezterm',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `open -na WezTerm --args start --new-tab --cwd "${_directory}" -- sh -c "${fullCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}; exec \\$SHELL" && sleep 0.5 && osascript -e 'tell application "WezTerm" to activate'`
+      ]
+    })
+  },
+  {
+    id: terminalApps.ghostty,
+    name: 'Ghostty',
+    bundleId: 'com.mitchellh.ghostty',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `cd "${_directory}" && open -na Ghostty --args --working-directory="${_directory}" -e sh -c "${fullCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}; exec \\$SHELL" && sleep 0.5 && osascript -e 'tell application "Ghostty" to activate'`
+      ]
+    })
+  },
+  {
+    id: terminalApps.tabby,
+    name: 'Tabby',
+    bundleId: 'org.tabby',
+    command: (_directory: string, fullCommand: string) => ({
+      command: 'sh',
+      args: [
+        '-c',
+        `if pgrep -x "Tabby" > /dev/null; then
+          open -na Tabby --args open && sleep 0.3
+        else
+          open -na Tabby --args open && sleep 2
+        fi && osascript -e 'tell application "Tabby" to activate' -e 'set the clipboard to "${escapeForAppleScript(fullCommand)}"' -e 'tell application "System Events" to tell process "Tabby" to keystroke "v" using {command down}' -e 'tell application "System Events" to key code 36'`
+      ]
+    })
+  }
+]

packages/shared/config/types.ts

@@ -7,7 +7,7 @@ export type LoaderReturn = {
   loaderType: string
   status?: ProcessingStatus
   message?: string
-  messageSource?: 'preprocess' | 'embedding'
+  messageSource?: 'preprocess' | 'embedding' | 'validation'
 }
 
 export type FileChangeEventType = 'add' | 'change' | 'unlink' | 'addDir' | 'unlinkDir'
@@ -17,3 +17,17 @@ export type FileChangeEvent = {
   filePath: string
   watchPath: string
 }
+
+export type MCPProgressEvent = {
+  callId: string
+  progress: number // 0-1 range
+}
+
+export type WebviewKeyEvent = {
+  webviewId: number
+  key: string
+  control: boolean
+  meta: boolean
+  shift: boolean
+  alt: boolean
+}

packages/shared/utils.ts

@@ -0,0 +1,6 @@
+export const defaultAppHeaders = () => {
+  return {
+    'HTTP-Referer': 'https://cherry-ai.com',
+    'X-Title': 'Cherry Studio'
+  }
+}

resources/cherry-studio/license.html

@@ -1,31 +1,38 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="zh-CN">
-
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>许可协议 | License Agreement</title>
     <script src="https://cdn.tailwindcss.com"></script>
-</head>
+  </head>
 
-<body class="bg-gray-50">
-  <div class="max-w-4xl mx-auto px-4 py-8">
+  <body class="bg-gray-50">
+    <div class="mx-auto max-w-4xl px-4 py-8">
       <!-- 中文版本 -->
       <div class="mb-12">
-      <h1 class="text-3xl font-bold mb-8 text-gray-900">许可协议</h1>
+        <h1 class="mb-8 text-3xl font-bold text-gray-900">许可协议</h1>
 
-      <p class="mb-6 text-gray-700">本项目采用<strong>区分用户的双重许可 (User-Segmented Dual Licensing)</strong> 模式。</p>
+        <p class="mb-6 text-gray-700">
+          本项目采用<strong>区分用户的双重许可 (User-Segmented Dual Licensing)</strong> 模式。
+        </p>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">核心原则</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li><strong>个人用户 和 10人及以下企业/组织:</strong> 默认适用 <strong>GNU Affero 通用公共许可证 v3.0 (AGPLv3)</strong>。</li>
-          <li><strong>超过10人的企业/组织:</strong> <strong>必须</strong> 获取 <strong>商业许可证 (Commercial License)</strong>。</li>
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">核心原则</h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              <strong>个人用户 和 10人及以下企业/组织:</strong> 默认适用
+              <strong>GNU Affero 通用公共许可证 v3.0 (AGPLv3)</strong>。
+            </li>
+            <li>
+              <strong>超过10人的企业/组织:</strong> <strong>必须</strong> 获取
+              <strong>商业许可证 (Commercial License)</strong>。
+            </li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">定义："10人及以下"</h2>
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">定义："10人及以下"</h2>
           <p class="text-gray-700">
             指在您的组织（包括公司、非营利组织、政府机构、教育机构等任何实体）中，能够访问、使用或以任何方式直接或间接受益于本软件（Cherry
             Studio）功能的个人总数不超过10人。这包括但不限于开发者、测试人员、运营人员、最终用户、通过集成系统间接使用者等。
@@ -33,167 +40,235 @@
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">1. 开源许可证 (Open Source License): AGPLv3 - 适用于个人及10人及以下组织
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">
+            1. 开源许可证 (Open Source License): AGPLv3 - 适用于个人及10人及以下组织
           </h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li>如果您是个人用户，或者您的组织满足上述"10人及以下"的定义，您可以在 <strong>AGPLv3</strong> 的条款下自由使用、修改和分发 Cherry Studio。AGPLv3 的完整文本可以访问
-            <a href="https://www.gnu.org/licenses/agpl-3.0.html"
-              class="text-blue-600 hover:underline">https://www.gnu.org/licenses/agpl-3.0.html</a> 获取。
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              如果您是个人用户，或者您的组织满足上述"10人及以下"的定义，您可以在
+              <strong>AGPLv3</strong> 的条款下自由使用、修改和分发 Cherry Studio。AGPLv3 的完整文本可以访问
+              <a href="https://www.gnu.org/licenses/agpl-3.0.html" class="text-blue-600 hover:underline"
+                >https://www.gnu.org/licenses/agpl-3.0.html</a
+              >
+              获取。
+            </li>
+            <li>
+              <strong>核心义务：</strong> AGPLv3 的一个关键要求是，如果您修改了 Cherry Studio
+              并通过网络提供服务，或者分发了修改后的版本，您必须以 AGPLv3
+              许可证向接收者提供相应的<strong>完整源代码</strong>。即使您符合"10人及以下"的标准，如果您希望避免此源代码公开义务，您也需要考虑获取商业许可证（见下文）。
             </li>
-          <li><strong>核心义务：</strong> AGPLv3 的一个关键要求是，如果您修改了 Cherry Studio 并通过网络提供服务，或者分发了修改后的版本，您必须以 AGPLv3
-            许可证向接收者提供相应的<strong>完整源代码</strong>。即使您符合"10人及以下"的标准，如果您希望避免此源代码公开义务，您也需要考虑获取商业许可证（见下文）。</li>
             <li>使用前请务必仔细阅读并理解 AGPLv3 的所有条款。</li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">2. 商业许可证 (Commercial License) - 适用于超过10人的组织，或希望规避 AGPLv3
-          义务的用户</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li><strong>强制要求：</strong>
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">
+            2. 商业许可证 (Commercial License) - 适用于超过10人的组织，或希望规避 AGPLv3 义务的用户
+          </h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              <strong>强制要求：</strong>
               如果您的组织<strong>不</strong>满足上述"10人及以下"的定义（即有11人或更多人可以访问、使用或受益于本软件），您<strong>必须</strong>联系我们获取并签署一份商业许可证才能使用
-            Cherry Studio。</li>
-          <li><strong>自愿选择：</strong> 即使您的组织满足"10人及以下"的条件，但如果您的使用场景<strong>无法满足 AGPLv3
-              的条款要求</strong>（特别是关于<strong>源代码公开</strong>的义务），或者您需要 AGPLv3 <strong>未提供</strong>的特定商业条款（如保证、赔偿、无 Copyleft
-            限制等），您也<strong>必须</strong>联系我们获取并签署一份商业许可证。</li>
-          <li><strong>需要商业许可证的常见情况包括（但不限于）：</strong>
-            <ul class="list-disc pl-6 mt-2 space-y-1">
+              Cherry Studio。
+            </li>
+            <li>
+              <strong>自愿选择：</strong> 即使您的组织满足"10人及以下"的条件，但如果您的使用场景<strong
+                >无法满足 AGPLv3 的条款要求</strong
+              >（特别是关于<strong>源代码公开</strong>的义务），或者您需要 AGPLv3
+              <strong>未提供</strong>的特定商业条款（如保证、赔偿、无 Copyleft
+              限制等），您也<strong>必须</strong>联系我们获取并签署一份商业许可证。
+            </li>
+            <li>
+              <strong>需要商业许可证的常见情况包括（但不限于）：</strong>
+              <ul class="mt-2 list-disc space-y-1 pl-6">
                 <li>您的组织规模超过10人。</li>
-              <li>（无论组织规模）您希望分发修改过的 Cherry Studio 版本，但<strong>不希望</strong>根据 AGPLv3 公开您修改部分的源代码。</li>
-              <li>（无论组织规模）您希望基于修改过的 Cherry Studio 提供网络服务（SaaS），但<strong>不希望</strong>根据 AGPLv3 向服务使用者提供修改后的源代码。</li>
-              <li>（无论组织规模）您的公司政策、客户合同或项目要求不允许使用 AGPLv3 许可的软件，或要求闭源分发及保密。</li>
+                <li>
+                  （无论组织规模）您希望分发修改过的 Cherry Studio 版本，但<strong>不希望</strong>根据 AGPLv3
+                  公开您修改部分的源代码。
+                </li>
+                <li>
+                  （无论组织规模）您希望基于修改过的 Cherry Studio 提供网络服务（SaaS），但<strong>不希望</strong>根据
+                  AGPLv3 向服务使用者提供修改后的源代码。
+                </li>
+                <li>
+                  （无论组织规模）您的公司政策、客户合同或项目要求不允许使用 AGPLv3 许可的软件，或要求闭源分发及保密。
+                </li>
               </ul>
             </li>
-          <li><strong>获取商业许可：</strong> 请通过邮箱 <a href="mailto:bd@cherry-ai.com"
-              class="text-blue-600 hover:underline">bd@cherry-ai.com</a> 联系 Cherry Studio 开发团队洽谈商业授权事宜。</li>
+            <li>
+              <strong>获取商业许可：</strong> 请通过邮箱
+              <a href="mailto:bd@cherry-ai.com" class="text-blue-600 hover:underline">bd@cherry-ai.com</a> 联系 Cherry
+              Studio 开发团队洽谈商业授权事宜。
+            </li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">3. 贡献 (Contributions)</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li>我们欢迎社区对 Cherry Studio 的贡献。所有向本项目提交的贡献都将被视为在 <strong>AGPLv3</strong> 许可证下提供。</li>
-          <li>通过向本项目提交贡献（例如通过 Pull Request），即表示您同意您的代码以 AGPLv3 许可证授权给本项目及所有后续使用者（无论这些使用者最终遵循 AGPLv3 还是商业许可）。</li>
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">3. 贡献 (Contributions)</h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              我们欢迎社区对 Cherry Studio 的贡献。所有向本项目提交的贡献都将被视为在
+              <strong>AGPLv3</strong> 许可证下提供。
+            </li>
+            <li>
+              通过向本项目提交贡献（例如通过 Pull Request），即表示您同意您的代码以 AGPLv3
+              许可证授权给本项目及所有后续使用者（无论这些使用者最终遵循 AGPLv3 还是商业许可）。
+            </li>
             <li>您也理解并同意，您的贡献可能会被包含在根据商业许可证分发的 Cherry Studio 版本中。</li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">4. 其他条款 (Other Terms)</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">4. 其他条款 (Other Terms)</h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
             <li>关于商业许可证的具体条款和条件，以双方签署的正式商业许可协议为准。</li>
-          <li>项目维护者保留根据需要更新本许可政策（包括用户规模定义和阈值）的权利。相关更新将通过项目官方渠道（如代码仓库、官方网站）进行通知。</li>
+            <li>
+              项目维护者保留根据需要更新本许可政策（包括用户规模定义和阈值）的权利。相关更新将通过项目官方渠道（如代码仓库、官方网站）进行通知。
+            </li>
           </ul>
         </section>
       </div>
 
-    <hr class="my-12 border-gray-300">
+      <hr class="my-12 border-gray-300" />
 
       <!-- English Version -->
       <div>
-      <h1 class="text-3xl font-bold mb-8 text-gray-900">Licensing</h1>
+        <h1 class="mb-8 text-3xl font-bold text-gray-900">Licensing</h1>
 
         <p class="mb-6 text-gray-700">This project employs a <strong>User-Segmented Dual Licensing</strong> model.</p>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">Core Principle</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li><strong>Individual Users and Organizations with 10 or Fewer Individuals:</strong> Governed by default
-            under the <strong>GNU Affero General Public License v3.0 (AGPLv3)</strong>.</li>
-          <li><strong>Organizations with More Than 10 Individuals:</strong> <strong>Must</strong> obtain a
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">Core Principle</h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              <strong>Individual Users and Organizations with 10 or Fewer Individuals:</strong> Governed by default
+              under the <strong>GNU Affero General Public License v3.0 (AGPLv3)</strong>.
+            </li>
+            <li>
+              <strong>Organizations with More Than 10 Individuals:</strong> <strong>Must</strong> obtain a
               <strong>Commercial License</strong>.
             </li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">Definition: "10 or Fewer Individuals"</h2>
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">Definition: "10 or Fewer Individuals"</h2>
           <p class="text-gray-700">
             Refers to any organization (including companies, non-profits, government agencies, educational institutions,
-          etc.) where the total number of individuals who can access, use, or in any way directly or indirectly benefit
-          from the functionality of this software (Cherry Studio) does not exceed 10. This includes, but is not limited
-          to, developers, testers, operations staff, end-users, and indirect users via integrated systems.
+            etc.) where the total number of individuals who can access, use, or in any way directly or indirectly
+            benefit from the functionality of this software (Cherry Studio) does not exceed 10. This includes, but is
+            not limited to, developers, testers, operations staff, end-users, and indirect users via integrated systems.
           </p>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">1. Open Source License: AGPLv3 - For Individuals and
-          Organizations of 10 or Fewer</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li>If you are an individual user, or if your organization meets the "10 or Fewer Individuals" definition
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">
+            1. Open Source License: AGPLv3 - For Individuals and Organizations of 10 or Fewer
+          </h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              If you are an individual user, or if your organization meets the "10 or Fewer Individuals" definition
               above, you are free to use, modify, and distribute Cherry Studio under the terms of the
-            <strong>AGPLv3</strong>. The full text of the AGPLv3 can be found at <a
-              href="https://www.gnu.org/licenses/agpl-3.0.html"
-              class="text-blue-600 hover:underline">https://www.gnu.org/licenses/agpl-3.0.html</a>.
+              <strong>AGPLv3</strong>. The full text of the AGPLv3 can be found at
+              <a href="https://www.gnu.org/licenses/agpl-3.0.html" class="text-blue-600 hover:underline"
+                >https://www.gnu.org/licenses/agpl-3.0.html</a
+              >.
+            </li>
+            <li>
+              <strong>Core Obligation:</strong> A key requirement of the AGPLv3 is that if you modify Cherry Studio and
+              make it available over a network, or distribute the modified version, you must provide the
+              <strong>complete corresponding source code</strong> under the AGPLv3 license to the recipients. Even if
+              you qualify under the "10 or Fewer Individuals" rule, if you wish to avoid this source code disclosure
+              obligation, you will need to obtain a Commercial License (see below).
             </li>
-          <li><strong>Core Obligation:</strong> A key requirement of the AGPLv3 is that if you modify Cherry Studio and
-            make it available over a network, or distribute the modified version, you must provide the <strong>complete
-              corresponding source code</strong> under the AGPLv3 license to the recipients. Even if you qualify under
-            the "10 or Fewer Individuals" rule, if you wish to avoid this source code disclosure obligation, you will
-            need to obtain a Commercial License (see below).</li>
             <li>Please read and understand the full terms of the AGPLv3 carefully before use.</li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">2. Commercial License - For Organizations with More Than 10
-          Individuals, or Users Needing to Avoid AGPLv3 Obligations</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li><strong>Mandatory Requirement:</strong> If your organization does <strong>not</strong> meet the "10 or
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">
+            2. Commercial License - For Organizations with More Than 10 Individuals, or Users Needing to Avoid AGPLv3
+            Obligations
+          </h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              <strong>Mandatory Requirement:</strong> If your organization does <strong>not</strong> meet the "10 or
               Fewer Individuals" definition above (i.e., 11 or more individuals can access, use, or benefit from the
               software), you <strong>must</strong> contact us to obtain and execute a Commercial License to use Cherry
-            Studio.</li>
-          <li><strong>Voluntary Option:</strong> Even if your organization meets the "10 or Fewer Individuals"
-            condition, if your intended use case <strong>cannot comply with the terms of the AGPLv3</strong>
-            (particularly the obligations regarding <strong>source code disclosure</strong>), or if you require specific
-            commercial terms <strong>not offered</strong> by the AGPLv3 (such as warranties, indemnities, or freedom
-            from copyleft restrictions), you also <strong>must</strong> contact us to obtain and execute a Commercial
-            License.</li>
-          <li><strong>Common scenarios requiring a Commercial License include (but are not limited to):</strong>
-            <ul class="list-disc pl-6 mt-2 space-y-1">
-              <li>Your organization has more than 10 individuals who can access, use, or benefit from the software.</li>
-              <li>(Regardless of organization size) You wish to distribute a modified version of Cherry Studio but
+              Studio.
+            </li>
+            <li>
+              <strong>Voluntary Option:</strong> Even if your organization meets the "10 or Fewer Individuals"
+              condition, if your intended use case
+              <strong>cannot comply with the terms of the AGPLv3</strong> (particularly the obligations regarding
+              <strong>source code disclosure</strong>), or if you require specific commercial terms
+              <strong>not offered</strong> by the AGPLv3 (such as warranties, indemnities, or freedom from copyleft
+              restrictions), you also <strong>must</strong> contact us to obtain and execute a Commercial License.
+            </li>
+            <li>
+              <strong>Common scenarios requiring a Commercial License include (but are not limited to):</strong>
+              <ul class="mt-2 list-disc space-y-1 pl-6">
+                <li>
+                  Your organization has more than 10 individuals who can access, use, or benefit from the software.
+                </li>
+                <li>
+                  (Regardless of organization size) You wish to distribute a modified version of Cherry Studio but
                   <strong>do not want</strong> to disclose the source code of your modifications under AGPLv3.
                 </li>
-              <li>(Regardless of organization size) You wish to provide a network service (SaaS) based on a modified
+                <li>
+                  (Regardless of organization size) You wish to provide a network service (SaaS) based on a modified
                   version of Cherry Studio but <strong>do not want</strong> to provide the modified source code to users
-                of the service under AGPLv3.</li>
-              <li>(Regardless of organization size) Your corporate policies, client contracts, or project requirements
-                prohibit the use of AGPLv3-licensed software or mandate closed-source distribution and confidentiality.
+                  of the service under AGPLv3.
+                </li>
+                <li>
+                  (Regardless of organization size) Your corporate policies, client contracts, or project requirements
+                  prohibit the use of AGPLv3-licensed software or mandate closed-source distribution and
+                  confidentiality.
                 </li>
               </ul>
             </li>
-          <li><strong>Obtaining a Commercial License:</strong> Please contact the Cherry Studio development team via
+            <li>
+              <strong>Obtaining a Commercial License:</strong> Please contact the Cherry Studio development team via
               email at <a href="mailto:bd@cherry-ai.com" class="text-blue-600 hover:underline">bd@cherry-ai.com</a> to
-            discuss commercial licensing options.</li>
+              discuss commercial licensing options.
+            </li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">3. Contributions</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li>We welcome community contributions to Cherry Studio. All contributions submitted to this project are
-            considered to be offered under the <strong>AGPLv3</strong> license.</li>
-          <li>By submitting a contribution to this project (e.g., via a Pull Request), you agree to license your code
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">3. Contributions</h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              We welcome community contributions to Cherry Studio. All contributions submitted to this project are
+              considered to be offered under the <strong>AGPLv3</strong> license.
+            </li>
+            <li>
+              By submitting a contribution to this project (e.g., via a Pull Request), you agree to license your code
               under the AGPLv3 to the project and all its downstream users (regardless of whether those users ultimately
-            operate under AGPLv3 or a Commercial License).</li>
-          <li>You also understand and agree that your contribution may be included in distributions of Cherry Studio
-            offered under our commercial license.</li>
+              operate under AGPLv3 or a Commercial License).
+            </li>
+            <li>
+              You also understand and agree that your contribution may be included in distributions of Cherry Studio
+              offered under our commercial license.
+            </li>
           </ul>
         </section>
 
         <section class="mb-8">
-        <h2 class="text-xl font-semibold mb-4 text-gray-900">4. Other Terms</h2>
-        <ul class="list-disc pl-6 space-y-2 text-gray-700">
-          <li>The specific terms and conditions of the Commercial License are governed by the formal commercial license
-            agreement signed by both parties.</li>
-          <li>The project maintainers reserve the right to update this licensing policy (including the definition and
+          <h2 class="mb-4 text-xl font-semibold text-gray-900">4. Other Terms</h2>
+          <ul class="list-disc space-y-2 pl-6 text-gray-700">
+            <li>
+              The specific terms and conditions of the Commercial License are governed by the formal commercial license
+              agreement signed by both parties.
+            </li>
+            <li>
+              The project maintainers reserve the right to update this licensing policy (including the definition and
               threshold for user count) as needed. Updates will be communicated through official project channels (e.g.,
-            code repository, official website).</li>
+              code repository, official website).
+            </li>
           </ul>
         </section>
       </div>
     </div>
-</body>
-
+  </body>
 </html>

resources/cherry-studio/privacy-en.html

@@ -0,0 +1,252 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Privacy Policy</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+            line-height: 1.6;
+            color: #333;
+            background: transparent;
+            margin: 0 auto;
+        }
+
+        body.dark {
+            background: transparent;
+            color: rgba(255, 255, 255, 0.85);
+        }
+
+        h1 {
+            font-size: 24px;
+            font-weight: 600;
+            margin-bottom: 20px;
+            color: #1a1a1a;
+        }
+
+        body.dark h1 {
+            color: rgba(255, 255, 255, 0.95);
+        }
+
+        h2 {
+            font-size: 18px;
+            font-weight: 600;
+            margin-top: 24px;
+            margin-bottom: 12px;
+            color: #2c2c2c;
+        }
+
+        body.dark h2 {
+            color: rgba(255, 255, 255, 0.9);
+        }
+
+        p {
+            margin: 12px 0;
+            line-height: 1.8;
+        }
+
+        body.dark p {
+            color: rgba(255, 255, 255, 0.8);
+        }
+
+        ul {
+            margin: 12px 0;
+            padding-left: 24px;
+        }
+
+        li {
+            margin: 6px 0;
+            line-height: 1.6;
+        }
+
+        body.dark li {
+            color: rgba(255, 255, 255, 0.75);
+        }
+
+        a {
+            color: #0066cc;
+            text-decoration: none;
+        }
+
+        a:hover {
+            text-decoration: underline;
+        }
+
+        body.dark a {
+            color: #4da6ff;
+        }
+
+        .footer {
+            margin-top: 40px;
+            padding-top: 20px;
+            border-top: 1px solid #e0e0e0;
+            font-size: 13px;
+            color: #666;
+        }
+
+        body.dark .footer {
+            border-top-color: rgba(255, 255, 255, 0.1);
+            color: rgba(255, 255, 255, 0.5);
+        }
+
+        .content-wrapper {
+            max-height: calc(100vh - 40px);
+            overflow-y: auto;
+            padding-right: 10px;
+            background: transparent;
+        }
+
+        /* Scrollbar styles - Light mode */
+        ::-webkit-scrollbar {
+            width: 8px;
+            height: 8px;
+        }
+
+        ::-webkit-scrollbar-track {
+            background: rgba(0, 0, 0, 0.05);
+            border-radius: 4px;
+        }
+
+        ::-webkit-scrollbar-thumb {
+            background: rgba(0, 0, 0, 0.2);
+            border-radius: 4px;
+        }
+
+        ::-webkit-scrollbar-thumb:hover {
+            background: rgba(0, 0, 0, 0.3);
+        }
+
+        /* Scrollbar styles - Dark mode */
+        body.dark ::-webkit-scrollbar-track {
+            background: rgba(255, 255, 255, 0.05);
+        }
+
+        body.dark ::-webkit-scrollbar-thumb {
+            background: rgba(255, 255, 255, 0.2);
+        }
+
+        body.dark ::-webkit-scrollbar-thumb:hover {
+            background: rgba(255, 255, 255, 0.3);
+        }
+    </style>
+    <script>
+        // Detect theme
+        document.addEventListener('DOMContentLoaded', function () {
+            const urlParams = new URLSearchParams(window.location.search);
+            const theme = urlParams.get('theme');
+            if (theme === 'dark') {
+                document.documentElement.classList.add('dark');
+                document.body.classList.add('dark');
+            }
+        });
+    </script>
+</head>
+
+<body>
+    <div class="content-wrapper">
+        <h1>Privacy Policy</h1>
+
+        <p>
+            Welcome to Cherry Studio (hereinafter referred to as "the Software" or "we"). We highly value your privacy
+            protection. This Privacy Policy explains how we process and protect your personal information and data.
+            Please read and understand this policy carefully before using the Software:
+        </p>
+
+        <h2>1. Information We Collect</h2>
+        <p>To optimize user experience and improve software quality, we may only collect the following anonymous,
+            non-personal information:</p>
+        <ul>
+            <li>Software version information</li>
+            <li>Activity and usage frequency of software features</li>
+            <li>Anonymous crash and error log information</li>
+        </ul>
+        <p>The above information is completely anonymous, does not involve any personal identity data, and cannot be
+            linked to your personal information.</p>
+
+        <h2>2. Information We Do Not Collect</h2>
+        <p>To maximize the protection of your privacy and security, we explicitly commit that we:</p>
+        <ul>
+            <li>Will not collect, save, transmit, or process model service API Key information you enter into the
+                Software</li>
+            <li>Will not collect, save, transmit, or process any conversation data generated during your use of the
+                Software, including but not limited to chat content, instruction information, knowledge base
+                information, vector data, and other custom content</li>
+            <li>Will not collect, save, transmit, or process any sensitive information that can identify personal
+                identity</li>
+        </ul>
+
+        <h2>3. Data Interaction Description</h2>
+        <p>
+            The Software uses API Keys from third-party model service providers that you apply for and configure
+            yourself to complete model calls and conversation functions. The model services you use (such as large
+            models, API interfaces, etc.) are directly provided by third-party providers of your choice. We do not
+            intervene, monitor, or interfere with the data transmission process.
+        </p>
+        <p>
+            Data interactions between you and third-party model services are governed by the privacy policies and user
+            agreements of third-party service providers. We recommend that you fully understand the privacy terms of
+            relevant service providers before use.
+        </p>
+
+        <h2>4. Local Data Security Protection</h2>
+        <p>The Software is a localized application, and all data is stored on your local device by default. We have
+            taken the following measures to ensure data security:</p>
+        <ul>
+            <li>Conversation records, configuration information, and other data are only saved on your local device</li>
+            <li>Data import/export functions are provided to facilitate your independent management and backup of data
+            </li>
+            <li>Your local data will not be uploaded to any server or cloud storage</li>
+        </ul>
+
+        <h2>5. Third-Party Services</h2>
+        <p>
+            When using the Software, you may access third-party services (such as AI model APIs, translation services,
+            etc.). The use of these third-party services is governed by their respective terms of service and privacy
+            policies. We strongly recommend that you carefully read and understand the relevant terms before use.
+        </p>
+
+        <h2>6. User Rights</h2>
+        <p>You have complete control over your data:</p>
+        <ul>
+            <li>You can view, modify, and delete all locally stored data at any time</li>
+            <li>You can choose whether to enable specific features or services</li>
+            <li>You can stop using the Software and delete all related data at any time</li>
+        </ul>
+
+        <h2>7. Children's Privacy Protection</h2>
+        <p>The Software is not intended for minors under 18 years of age. If you are a minor, please use the Software
+            under the guidance of a guardian.</p>
+
+        <h2>8. Privacy Policy Updates</h2>
+        <p>
+            We may update this Privacy Policy based on legal requirements or changes in product features. The updated
+            policy will be published in the Software and you will be notified before it takes effect. If you do not
+            agree with the updated terms, you can choose to stop using the Software.
+        </p>
+
+        <h2>9. Contact Us</h2>
+        <p>If you have any questions, suggestions, or complaints about this Privacy Policy, please contact us through
+            the following methods:</p>
+        <ul>
+            <li>
+                GitHub: <a href="https://github.com/CherryHQ/cherry-studio" target="_blank"
+                    rel="noopener noreferrer">https://github.com/CherryHQ/cherry-studio</a>
+            </li>
+            <li>Email: support@cherry-ai.com</li>
+        </ul>
+
+        <div class="footer">
+            Last Updated: December 2024
+        </div>
+    </div>
+</body>
+
+</html>

resources/cherry-studio/privacy-zh.html

@@ -0,0 +1,230 @@
+<!DOCTYPE html>
+<html lang="zh">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>隐私协议</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+            line-height: 1.6;
+            color: #333;
+            background: transparent;
+            margin: 0 auto;
+        }
+
+        body.dark {
+            background: transparent;
+            color: rgba(255, 255, 255, 0.85);
+        }
+
+        h1 {
+            font-size: 24px;
+            font-weight: 600;
+            margin-bottom: 20px;
+            color: #1a1a1a;
+        }
+
+        body.dark h1 {
+            color: rgba(255, 255, 255, 0.95);
+        }
+
+        h2 {
+            font-size: 18px;
+            font-weight: 600;
+            margin-top: 24px;
+            margin-bottom: 12px;
+            color: #2c2c2c;
+        }
+
+        body.dark h2 {
+            color: rgba(255, 255, 255, 0.9);
+        }
+
+        p {
+            margin: 12px 0;
+            line-height: 1.8;
+        }
+
+        body.dark p {
+            color: rgba(255, 255, 255, 0.8);
+        }
+
+        ul {
+            margin: 12px 0;
+            padding-left: 24px;
+        }
+
+        li {
+            margin: 6px 0;
+            line-height: 1.6;
+        }
+
+        body.dark li {
+            color: rgba(255, 255, 255, 0.75);
+        }
+
+        a {
+            color: #0066cc;
+            text-decoration: none;
+        }
+
+        a:hover {
+            text-decoration: underline;
+        }
+
+        body.dark a {
+            color: #4da6ff;
+        }
+
+        .footer {
+            margin-top: 40px;
+            padding-top: 20px;
+            border-top: 1px solid #e0e0e0;
+            font-size: 13px;
+            color: #666;
+        }
+
+        body.dark .footer {
+            border-top-color: rgba(255, 255, 255, 0.1);
+            color: rgba(255, 255, 255, 0.5);
+        }
+
+        .content-wrapper {
+            overflow-y: auto;
+            padding-right: 10px;
+            background: transparent;
+        }
+
+        /* 滚动条样式 - 亮色模式 */
+        ::-webkit-scrollbar {
+            width: 8px;
+            height: 8px;
+        }
+
+        ::-webkit-scrollbar-track {
+            background: rgba(0, 0, 0, 0.05);
+            border-radius: 4px;
+        }
+
+        ::-webkit-scrollbar-thumb {
+            background: rgba(0, 0, 0, 0.2);
+            border-radius: 4px;
+        }
+
+        ::-webkit-scrollbar-thumb:hover {
+            background: rgba(0, 0, 0, 0.3);
+        }
+
+        /* 滚动条样式 - 暗色模式 */
+        body.dark ::-webkit-scrollbar-track {
+            background: rgba(255, 255, 255, 0.05);
+        }
+
+        body.dark ::-webkit-scrollbar-thumb {
+            background: rgba(255, 255, 255, 0.2);
+        }
+
+        body.dark ::-webkit-scrollbar-thumb:hover {
+            background: rgba(255, 255, 255, 0.3);
+        }
+    </style>
+    <script>
+        // 检测主题
+        document.addEventListener('DOMContentLoaded', function () {
+            const urlParams = new URLSearchParams(window.location.search);
+            const theme = urlParams.get('theme');
+            if (theme === 'dark') {
+                document.documentElement.classList.add('dark');
+                document.body.classList.add('dark');
+            }
+        });
+    </script>
+</head>
+
+<body>
+    <div class="content-wrapper">
+        <h1>隐私协议</h1>
+
+        <p>
+            欢迎使用 Cherry Studio（以下简称"本软件"或"我们"）。我们高度重视您的隐私保护，本隐私协议将说明我们如何处理与保护您的个人信息和数据。请在使用本软件前仔细阅读并理解本协议：
+        </p>
+
+        <h2>一、我们收集的信息范围</h2>
+        <p>为了优化用户体验和提升软件质量，我们仅可能会匿名收集以下非个人化信息：</p>
+        <ul>
+            <li>软件版本信息；</li>
+            <li>软件功能的活跃度、使用频次；</li>
+            <li>匿名的崩溃、错误日志信息；</li>
+        </ul>
+        <p>上述信息完全匿名，不会涉及任何个人身份数据，也无法关联到您的个人信息。</p>
+
+        <h2>二、我们不会收集的任何信息</h2>
+        <p>为了最大限度保护您的隐私安全，我们明确承诺：</p>
+        <ul>
+            <li>不会收集、保存、传输或处理您输入到本软件中的模型服务 API Key 信息；</li>
+            <li>不会收集、保存、传输或处理您在使用本软件过程中产生的任何对话数据，包括但不限于聊天内容、指令信息、知识库信息、向量数据及其他自定义内容；</li>
+            <li>不会收集、保存、传输或处理任何可识别个人身份的敏感信息。</li>
+        </ul>
+
+        <h2>三、数据交互说明</h2>
+        <p>
+            本软件采用您自行申请并配置的第三方模型服务提供商的 API Key，以完成相关模型的调用与对话功能。您使用的模型服务（例如大模型、API 接口等）由您选择的第三方提供商直接提供，我们不会介入、监控或干扰数据传输过程。
+        </p>
+        <p>
+            您与第三方模型服务之间的数据交互受第三方服务提供商的隐私政策和用户协议约束，我们建议您在使用前充分了解相关服务商的隐私条款。
+        </p>
+
+        <h2>四、本地数据的安全保护</h2>
+        <p>本软件为本地化应用程序，所有数据默认存储在您的本地设备上。我们采取了以下措施保障数据安全：</p>
+        <ul>
+            <li>对话记录、配置信息等数据仅保存在您的本地设备中；</li>
+            <li>提供数据导入/导出功能，方便您自主管理和备份数据；</li>
+            <li>不会将您的本地数据上传至任何服务器或云端存储。</li>
+        </ul>
+
+        <h2>五、第三方服务</h2>
+        <p>
+            在使用本软件过程中，您可能会接入第三方服务（如 AI 模型 API、翻译服务等）。这些第三方服务的使用受其各自的服务条款和隐私政策约束。我们强烈建议您在使用前仔细阅读并理解相关条款。
+        </p>
+
+        <h2>六、用户权利</h2>
+        <p>您对自己的数据拥有完全的控制权：</p>
+        <ul>
+            <li>您可以随时查看、修改、删除本地存储的所有数据；</li>
+            <li>您可以选择是否启用特定功能或服务；</li>
+            <li>您可以随时停止使用本软件并删除所有相关数据。</li>
+        </ul>
+
+        <h2>七、儿童隐私保护</h2>
+        <p>本软件不面向 18 岁以下的未成年人提供服务。如果您是未成年人，请在监护人的指导下使用本软件。</p>
+
+        <h2>八、隐私政策的更新</h2>
+        <p>
+            我们可能会根据法律法规要求或产品功能的变化更新本隐私协议。更新后的协议将在软件中发布，并在生效前通知您。如果您不同意更新后的条款，您可以选择停止使用本软件。
+        </p>
+
+        <h2>九、联系我们</h2>
+        <p>如果您对本隐私协议有任何疑问、建议或投诉，请通过以下方式联系我们：</p>
+        <ul>
+            <li>
+                GitHub: <a href="https://github.com/CherryHQ/cherry-studio" target="_blank"
+                    rel="noopener noreferrer">https://github.com/CherryHQ/cherry-studio</a>
+            </li>
+            <li>Email: support@cherry-ai.com</li>
+        </ul>
+
+        <div class="footer">
+            最后更新日期：2024年12月
+        </div>
+    </div>
+</body>
+
+</html>

resources/cherry-studio/releases.html

@@ -12,18 +12,18 @@
 
   <body id="app">
     <div :class="isDark ? 'dark-bg' : 'bg'" class="min-h-screen">
-      <div class="max-w-3xl mx-auto py-12 px-4">
-        <h1 class="text-3xl font-bold mb-8" :class="isDark ? 'text-white' : 'text-gray-900'">Release Timeline</h1>
+      <div class="mx-auto max-w-3xl px-4 py-12">
+        <h1 class="mb-8 text-3xl font-bold" :class="isDark ? 'text-white' : 'text-gray-900'">Release Timeline</h1>
 
         <!-- Loading状态 -->
-        <div v-if="loading" class="text-center py-8">
+        <div v-if="loading" class="py-8 text-center">
           <div
-            class="inline-block animate-spin rounded-full h-8 w-8 border-4"
+            class="inline-block h-8 w-8 animate-spin rounded-full border-4"
             :class="isDark ? 'border-gray-700 border-t-blue-500' : 'border-gray-300 border-t-blue-500'"></div>
         </div>
 
         <!-- Error 状态 -->
-        <div v-else-if="error" class="text-red-500 text-center py-8">{{ error }}</div>
+        <div v-else-if="error" class="py-8 text-center text-red-500">{{ error }}</div>
 
         <!-- Release 列表 -->
         <div v-else class="space-y-8">
@@ -32,21 +32,21 @@
             :key="release.id"
             class="relative pl-8"
             :class="isDark ? 'border-l-2 border-gray-700' : 'border-l-2 border-gray-200'">
-            <div class="absolute -left-2 top-0 w-4 h-4 rounded-full bg-green-500"></div>
+            <div class="absolute top-0 -left-2 h-4 w-4 rounded-full bg-green-500"></div>
             <div
-              class="rounded-lg shadow-sm p-6 transition-shadow"
+              class="rounded-lg p-6 shadow-sm transition-shadow"
               :class="isDark ? 'bg-black hover:shadow-md hover:shadow-black' : 'bg-white hover:shadow-md'">
-              <div class="flex items-start justify-between mb-4">
+              <div class="mb-4 flex items-start justify-between">
                 <div>
                   <h2 class="text-xl font-semibold" :class="isDark ? 'text-white' : 'text-gray-900'">
                     {{ release.name || release.tag_name }}
                   </h2>
-                  <p class="text-sm mt-1" :class="isDark ? 'text-gray-400' : 'text-gray-500'">
+                  <p class="mt-1 text-sm" :class="isDark ? 'text-gray-400' : 'text-gray-500'">
                     {{ formatDate(release.published_at) }}
                   </p>
                 </div>
                 <span
-                  class="inline-flex items-center px-3 py-1 rounded-full text-sm font-medium"
+                  class="inline-flex items-center rounded-full px-3 py-1 text-sm font-medium"
                   :class="isDark ? 'bg-green-900 text-green-200' : 'bg-green-100 text-green-800'">
                   {{ release.tag_name }}
                 </span>

resources/database/drizzle/0000_confused_wendigo.sql

@@ -0,0 +1,53 @@
+--> statement-breakpoint
+CREATE TABLE `migrations` (
+	`version` integer PRIMARY KEY NOT NULL,
+	`tag` text NOT NULL,
+	`executed_at` integer NOT NULL
+);
+
+CREATE TABLE `agents` (
+	`id` text PRIMARY KEY NOT NULL,
+	`type` text NOT NULL,
+	`name` text NOT NULL,
+	`description` text,
+	`accessible_paths` text,
+	`instructions` text,
+	`model` text NOT NULL,
+	`plan_model` text,
+	`small_model` text,
+	`mcps` text,
+	`allowed_tools` text,
+	`configuration` text,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
+
+--> statement-breakpoint
+CREATE TABLE `sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`agent_type` text NOT NULL,
+	`agent_id` text NOT NULL,
+	`name` text NOT NULL,
+	`description` text,
+	`accessible_paths` text,
+	`instructions` text,
+	`model` text NOT NULL,
+	`plan_model` text,
+	`small_model` text,
+	`mcps` text,
+	`allowed_tools` text,
+	`configuration` text,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);
+
+--> statement-breakpoint
+CREATE TABLE `session_messages` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`session_id` text NOT NULL,
+	`role` text NOT NULL,
+	`content` text NOT NULL,
+	`metadata` text,
+	`created_at` text NOT NULL,
+	`updated_at` text NOT NULL
+);

resources/database/drizzle/0001_woozy_captain_flint.sql

@@ -0,0 +1 @@
+ALTER TABLE `session_messages` ADD `agent_session_id` text DEFAULT '';

resources/database/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,331 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "35efb412-0230-4767-9c76-7b7c4d40369f",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "agents": {
+      "name": "agents",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "accessible_paths": {
+          "name": "accessible_paths",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instructions": {
+          "name": "instructions",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "model": {
+          "name": "model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "plan_model": {
+          "name": "plan_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "small_model": {
+          "name": "small_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mcps": {
+          "name": "mcps",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "allowed_tools": {
+          "name": "allowed_tools",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "configuration": {
+          "name": "configuration",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "session_messages": {
+      "name": "session_messages",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "migrations": {
+      "name": "migrations",
+      "columns": {
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "tag": {
+          "name": "tag",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "executed_at": {
+          "name": "executed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_id": {
+          "name": "agent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "accessible_paths": {
+          "name": "accessible_paths",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instructions": {
+          "name": "instructions",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "model": {
+          "name": "model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "plan_model": {
+          "name": "plan_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "small_model": {
+          "name": "small_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mcps": {
+          "name": "mcps",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "allowed_tools": {
+          "name": "allowed_tools",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "configuration": {
+          "name": "configuration",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

resources/database/drizzle/meta/0001_snapshot.json

@@ -0,0 +1,339 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "dabab6db-a2cd-4e96-b06e-6cb87d445a87",
+  "prevId": "35efb412-0230-4767-9c76-7b7c4d40369f",
+  "tables": {
+    "agents": {
+      "name": "agents",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "accessible_paths": {
+          "name": "accessible_paths",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instructions": {
+          "name": "instructions",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "model": {
+          "name": "model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "plan_model": {
+          "name": "plan_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "small_model": {
+          "name": "small_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mcps": {
+          "name": "mcps",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "allowed_tools": {
+          "name": "allowed_tools",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "configuration": {
+          "name": "configuration",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "session_messages": {
+      "name": "session_messages",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_session_id": {
+          "name": "agent_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "migrations": {
+      "name": "migrations",
+      "columns": {
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "tag": {
+          "name": "tag",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "executed_at": {
+          "name": "executed_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_id": {
+          "name": "agent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "accessible_paths": {
+          "name": "accessible_paths",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instructions": {
+          "name": "instructions",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "model": {
+          "name": "model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "plan_model": {
+          "name": "plan_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "small_model": {
+          "name": "small_model",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "mcps": {
+          "name": "mcps",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "allowed_tools": {
+          "name": "allowed_tools",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "configuration": {
+          "name": "configuration",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

resources/database/drizzle/meta/_journal.json

@@ -0,0 +1,20 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1758091173882,
+      "tag": "0000_confused_wendigo",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1758187378775,
+      "tag": "0001_woozy_captain_flint",
+      "breakpoints": true
+    }
+  ]
+}

resources/scripts/download.js

@@ -1,5 +1,7 @@
 const https = require('https')
 const fs = require('fs')
+const path = require('path')
+const { execSync } = require('child_process')
 
 /**
  * Downloads a file from a URL with redirect handling
@@ -32,4 +34,39 @@ async function downloadWithRedirects(url, destinationPath) {
   })
 }
 
-module.exports = { downloadWithRedirects }
+/**
+ * Downloads a file using PowerShell Invoke-WebRequest command
+ * @param {string} url The URL to download from
+ * @param {string} destinationPath The path to save the file to
+ * @returns {Promise<boolean>} Promise that resolves to true if download succeeds
+ */
+async function downloadWithPowerShell(url, destinationPath) {
+  return new Promise((resolve, reject) => {
+    try {
+      // Only support windows platform for PowerShell download
+      if (process.platform !== 'win32') {
+        return reject(new Error('PowerShell download is only supported on Windows'))
+      }
+
+      const outputDir = path.dirname(destinationPath)
+      fs.mkdirSync(outputDir, { recursive: true })
+
+      // PowerShell command to download the file with progress disabled for faster download
+      const psCommand = `powershell -Command "$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest '${url}' -OutFile '${destinationPath}'"`
+
+      console.log(`Downloading with PowerShell: ${url}`)
+      execSync(psCommand, { stdio: 'inherit' })
+
+      if (fs.existsSync(destinationPath)) {
+        console.log(`Download completed: ${destinationPath}`)
+        resolve(true)
+      } else {
+        reject(new Error('Download failed: File not found after download'))
+      }
+    } catch (error) {
+      reject(new Error(`PowerShell download failed: ${error.message}`))
+    }
+  })
+}
+
+module.exports = { downloadWithRedirects, downloadWithPowerShell }

resources/scripts/install-ovms.js

@@ -0,0 +1,177 @@
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { execSync } = require('child_process')
+const { downloadWithPowerShell } = require('./download')
+
+// Base URL for downloading OVMS binaries
+const OVMS_PKG_NAME = 'ovms250911.zip'
+const OVMS_RELEASE_BASE_URL = [`https://gitcode.com/gcw_ggDjjkY3/kjfile/releases/download/download/${OVMS_PKG_NAME}`]
+
+/**
+ * Downloads and extracts the OVMS binary for the specified platform
+ */
+async function downloadOvmsBinary() {
+  // Create output directory structure - OVMS goes into its own subdirectory
+  const csDir = path.join(os.homedir(), '.cherrystudio')
+
+  // Ensure directories exist
+  fs.mkdirSync(csDir, { recursive: true })
+
+  const csOvmsDir = path.join(csDir, 'ovms')
+  // Delete existing OVMS directory if it exists
+  if (fs.existsSync(csOvmsDir)) {
+    fs.rmSync(csOvmsDir, { recursive: true })
+  }
+
+  const tempdir = os.tmpdir()
+  const tempFilename = path.join(tempdir, 'ovms.zip')
+
+  // Try each URL until one succeeds
+  let downloadSuccess = false
+  let lastError = null
+
+  for (let i = 0; i < OVMS_RELEASE_BASE_URL.length; i++) {
+    const downloadUrl = OVMS_RELEASE_BASE_URL[i]
+    console.log(`Attempting download from URL ${i + 1}/${OVMS_RELEASE_BASE_URL.length}: ${downloadUrl}`)
+
+    try {
+      console.log(`Downloading OVMS from ${downloadUrl} to ${tempFilename}...`)
+
+      // Try PowerShell download first, fallback to Node.js download if it fails
+      await downloadWithPowerShell(downloadUrl, tempFilename)
+
+      // If we get here, download was successful
+      downloadSuccess = true
+      console.log(`Successfully downloaded from: ${downloadUrl}`)
+      break
+    } catch (error) {
+      console.warn(`Download failed from ${downloadUrl}: ${error.message}`)
+      lastError = error
+
+      // Clean up failed download file if it exists
+      if (fs.existsSync(tempFilename)) {
+        try {
+          fs.unlinkSync(tempFilename)
+        } catch (cleanupError) {
+          console.warn(`Failed to clean up temporary file: ${cleanupError.message}`)
+        }
+      }
+
+      // Continue to next URL if this one failed
+      if (i < OVMS_RELEASE_BASE_URL.length - 1) {
+        console.log(`Trying next URL...`)
+      }
+    }
+  }
+
+  // Check if any download succeeded
+  if (!downloadSuccess) {
+    console.error(`All download URLs failed. Last error: ${lastError?.message || 'Unknown error'}`)
+    return 103
+  }
+
+  try {
+    console.log(`Extracting to ${csDir}...`)
+
+    // Use tar.exe to extract the ZIP file
+    console.log(`Extracting OVMS to ${csDir}...`)
+    execSync(`tar -xf ${tempFilename} -C ${csDir}`, { stdio: 'inherit' })
+    console.log(`OVMS extracted to ${csDir}`)
+
+    // Clean up temporary file
+    fs.unlinkSync(tempFilename)
+    console.log(`Installation directory: ${csDir}`)
+  } catch (error) {
+    console.error(`Error installing OVMS: ${error.message}`)
+    if (fs.existsSync(tempFilename)) {
+      fs.unlinkSync(tempFilename)
+    }
+
+    // Check if ovmsDir is empty and remove it if so
+    try {
+      const ovmsDir = path.join(csDir, 'ovms')
+      const files = fs.readdirSync(ovmsDir)
+      if (files.length === 0) {
+        fs.rmSync(ovmsDir, { recursive: true })
+        console.log(`Removed empty directory: ${ovmsDir}`)
+      }
+    } catch (cleanupError) {
+      console.warn(`Warning: Failed to clean up directory: ${cleanupError.message}`)
+      return 105
+    }
+
+    return 104
+  }
+
+  return 0
+}
+
+/**
+ * Get the CPU Name and ID
+ */
+function getCpuInfo() {
+  const cpuInfo = {
+    name: '',
+    id: ''
+  }
+
+  // Use PowerShell to get CPU information
+  try {
+    const psCommand = `powershell -Command "Get-CimInstance -ClassName Win32_Processor | Select-Object Name, DeviceID | ConvertTo-Json"`
+    const psOutput = execSync(psCommand).toString()
+    const cpuData = JSON.parse(psOutput)
+
+    if (Array.isArray(cpuData)) {
+      cpuInfo.name = cpuData[0].Name || ''
+      cpuInfo.id = cpuData[0].DeviceID || ''
+    } else {
+      cpuInfo.name = cpuData.Name || ''
+      cpuInfo.id = cpuData.DeviceID || ''
+    }
+  } catch (error) {
+    console.error(`Failed to get CPU info: ${error.message}`)
+  }
+
+  return cpuInfo
+}
+
+/**
+ * Main function to install OVMS
+ */
+async function installOvms() {
+  const platform = os.platform()
+  console.log(`Detected platform: ${platform}`)
+
+  const cpuName = getCpuInfo().name
+  console.log(`CPU Name: ${cpuName}`)
+
+  // Check if CPU name contains "Ultra"
+  if (!cpuName.toLowerCase().includes('intel') || !cpuName.toLowerCase().includes('ultra')) {
+    console.error('OVMS installation requires an Intel(R) Core(TM) Ultra CPU.')
+    return 101
+  }
+
+  // only support windows
+  if (platform !== 'win32') {
+    console.error('OVMS installation is only supported on Windows.')
+    return 102
+  }
+
+  return await downloadOvmsBinary()
+}
+
+// Run the installation
+installOvms()
+  .then((retcode) => {
+    if (retcode === 0) {
+      console.log('OVMS installation successful')
+    } else {
+      console.error('OVMS installation failed')
+    }
+    process.exit(retcode)
+  })
+  .catch((error) => {
+    console.error('OVMS installation failed:', error)
+    process.exit(100)
+  })

scripts/auto-translate-i18n.ts

@@ -9,8 +9,9 @@ import * as path from 'path'
 
 const localesDir = path.join(__dirname, '../src/renderer/src/i18n/locales')
 const translateDir = path.join(__dirname, '../src/renderer/src/i18n/translate')
-const baseLocale = 'zh-cn'
+const baseLocale = process.env.BASE_LOCALE ?? 'zh-cn'
 const baseFileName = `${baseLocale}.json`
+const baseLocalePath = path.join(__dirname, '../src/renderer/src/i18n/locales', baseFileName)
 
 type I18NValue = string | { [key: string]: I18NValue }
 type I18N = { [key: string]: I18NValue }
@@ -105,6 +106,9 @@ const translateRecursively = async (originObj: I18N, systemPrompt: string): Prom
 }
 
 const main = async () => {
+  if (!fs.existsSync(baseLocalePath)) {
+    throw new Error(`${baseLocalePath} not found.`)
+  }
   const localeFiles = fs
     .readdirSync(localesDir)
     .filter((file) => file.endsWith('.json') && file !== baseFileName)

scripts/before-pack.js

@@ -35,6 +35,9 @@ const allX64 = {
   '@napi-rs/system-ocr-win32-x64-msvc': '1.0.2'
 }
 
+const claudeCodeVenderPath = '@anthropic-ai/claude-agent-sdk/vendor'
+const claudeCodeVenders = ['arm64-darwin', 'arm64-linux', 'x64-darwin', 'x64-linux', 'x64-win32']
+
 const platformToArch = {
   mac: 'darwin',
   windows: 'win32',
@@ -46,9 +49,6 @@ exports.default = async function (context) {
   const archType = arch === Arch.arm64 ? 'arm64' : 'x64'
   const platform = context.packager.platform.name
 
-  const arm64Filters = Object.keys(allArm64).map((f) => '!node_modules/' + f + '/**')
-  const x64Filters = Object.keys(allX64).map((f) => '!node_modules/' + f + '/*')
-
   const downloadPackages = async (packages) => {
     console.log('downloading packages ......')
     const downloadPromises = []
@@ -67,25 +67,39 @@ exports.default = async function (context) {
     await Promise.all(downloadPromises)
   }
 
-  const changeFilters = async (packages, filtersToExclude, filtersToInclude) => {
-    await downloadPackages(packages)
+  const changeFilters = async (filtersToExclude, filtersToInclude) => {
     // remove filters for the target architecture (allow inclusion)
-
     let filters = context.packager.config.files[0].filter
     filters = filters.filter((filter) => !filtersToInclude.includes(filter))
+
     // add filters for other architectures (exclude them)
     filters.push(...filtersToExclude)
 
     context.packager.config.files[0].filter = filters
   }
 
-  if (arch === Arch.arm64) {
-    await changeFilters(allArm64, x64Filters, arm64Filters)
-    return
-  }
+  await downloadPackages(arch === Arch.arm64 ? allArm64 : allX64)
 
-  if (arch === Arch.x64) {
-    await changeFilters(allX64, arm64Filters, x64Filters)
-    return
+  const arm64Filters = Object.keys(allArm64).map((f) => '!node_modules/' + f + '/**')
+  const x64Filters = Object.keys(allX64).map((f) => '!node_modules/' + f + '/*')
+  const excludeClaudeCodeRipgrepFilters = claudeCodeVenders
+    .filter((f) => f !== `${archType}-${platformToArch[platform]}`)
+    .map((f) => '!node_modules/' + claudeCodeVenderPath + '/ripgrep/' + f + '/**')
+  const excludeClaudeCodeJBPlutins = ['!node_modules/' + claudeCodeVenderPath + '/' + 'claude-code-jetbrains-plugin']
+
+  const includeClaudeCodeFilters = [
+    '!node_modules/' + claudeCodeVenderPath + '/ripgrep/' + `${archType}-${platformToArch[platform]}/**`
+  ]
+
+  if (arch === Arch.arm64) {
+    await changeFilters(
+      [...x64Filters, ...excludeClaudeCodeRipgrepFilters, ...excludeClaudeCodeJBPlutins],
+      [...arm64Filters, ...includeClaudeCodeFilters]
+    )
+  } else {
+    await changeFilters(
+      [...arm64Filters, ...excludeClaudeCodeRipgrepFilters, ...excludeClaudeCodeJBPlutins],
+      [...x64Filters, ...includeClaudeCodeFilters]
+    )
   }
 }

scripts/check-i18n.ts

@@ -4,7 +4,7 @@ import * as path from 'path'
 import { sortedObjectByKeys } from './sort'
 
 const translationsDir = path.join(__dirname, '../src/renderer/src/i18n/locales')
-const baseLocale = 'zh-cn'
+const baseLocale = process.env.BASE_LOCALE ?? 'zh-cn'
 const baseFileName = `${baseLocale}.json`
 const baseFilePath = path.join(translationsDir, baseFileName)
 

scripts/sync-i18n.ts

@@ -5,7 +5,7 @@ import { sortedObjectByKeys } from './sort'
 
 const localesDir = path.join(__dirname, '../src/renderer/src/i18n/locales')
 const translateDir = path.join(__dirname, '../src/renderer/src/i18n/translate')
-const baseLocale = 'zh-cn'
+const baseLocale = process.env.BASE_LOCALE ?? 'zh-cn'
 const baseFileName = `${baseLocale}.json`
 const baseFilePath = path.join(localesDir, baseFileName)
 

scripts/update-languages.ts

@@ -1,6 +1,6 @@
 import { exec } from 'child_process'
 import * as fs from 'fs/promises'
-import linguistLanguages from 'linguist-languages'
+import * as linguistLanguages from 'linguist-languages'
 import * as path from 'path'
 import { promisify } from 'util'
 
@@ -75,17 +75,17 @@ export const languages: Record<string, LanguageData> = ${languagesObjectString};
 }
 
 /**
- * Formats a file using Prettier.
+ * Formats a file using Biome.
  * @param filePath The path to the file to format.
  */
-async function formatWithPrettier(filePath: string): Promise<void> {
-  console.log('🎨 Formatting file with Prettier...')
+async function format(filePath: string): Promise<void> {
+  console.log('🎨 Formatting file with Biome...')
   try {
-    await execAsync(`yarn prettier --write ${filePath}`)
-    console.log('✅ Prettier formatting complete.')
+    await execAsync(`yarn biome format --write ${filePath}`)
+    console.log('✅ Biome formatting complete.')
   } catch (e: any) {
-    console.error('❌ Prettier formatting failed:', e.stdout || e.stderr)
-    throw new Error('Prettier formatting failed.')
+    console.error('❌ Biome formatting failed:', e.stdout || e.stderr)
+    throw new Error('Biome formatting failed.')
   }
 }
 
@@ -116,7 +116,7 @@ async function updateLanguagesFile(): Promise<void> {
     await fs.writeFile(LANGUAGES_FILE_PATH, fileContent, 'utf-8')
     console.log(`✅ Successfully wrote to ${LANGUAGES_FILE_PATH}`)
 
-    await formatWithPrettier(LANGUAGES_FILE_PATH)
+    await format(LANGUAGES_FILE_PATH)
     await checkTypeScript(LANGUAGES_FILE_PATH)
 
     console.log('🎉 Successfully updated languages.ts file!')

src/main/apiServer/app.ts

@@ -0,0 +1,148 @@
+import { loggerService } from '@main/services/LoggerService'
+import cors from 'cors'
+import express from 'express'
+import { v4 as uuidv4 } from 'uuid'
+
+import { LONG_POLL_TIMEOUT_MS } from './config/timeouts'
+import { authMiddleware } from './middleware/auth'
+import { errorHandler } from './middleware/error'
+import { setupOpenAPIDocumentation } from './middleware/openapi'
+import { agentsRoutes } from './routes/agents'
+import { chatRoutes } from './routes/chat'
+import { mcpRoutes } from './routes/mcp'
+import { messagesProviderRoutes, messagesRoutes } from './routes/messages'
+import { modelsRoutes } from './routes/models'
+
+const logger = loggerService.withContext('ApiServer')
+
+const extendMessagesTimeout: express.RequestHandler = (req, res, next) => {
+  req.setTimeout(LONG_POLL_TIMEOUT_MS)
+  res.setTimeout(LONG_POLL_TIMEOUT_MS)
+  next()
+}
+
+const app = express()
+app.use(
+  express.json({
+    limit: '50mb'
+  })
+)
+
+// Global middleware
+app.use((req, res, next) => {
+  const start = Date.now()
+  res.on('finish', () => {
+    const duration = Date.now() - start
+    logger.info('API request completed', {
+      method: req.method,
+      path: req.path,
+      statusCode: res.statusCode,
+      durationMs: duration
+    })
+  })
+  next()
+})
+
+app.use((_req, res, next) => {
+  res.setHeader('X-Request-ID', uuidv4())
+  next()
+})
+
+app.use(
+  cors({
+    origin: '*',
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']
+  })
+)
+
+/**
+ * @swagger
+ * /health:
+ *   get:
+ *     summary: Health check endpoint
+ *     description: Check server status (no authentication required)
+ *     tags: [Health]
+ *     security: []
+ *     responses:
+ *       200:
+ *         description: Server is healthy
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: ok
+ *                 timestamp:
+ *                   type: string
+ *                   format: date-time
+ *                 version:
+ *                   type: string
+ *                   example: 1.0.0
+ */
+app.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    version: process.env.npm_package_version || '1.0.0'
+  })
+})
+
+/**
+ * @swagger
+ * /:
+ *   get:
+ *     summary: API information
+ *     description: Get basic API information and available endpoints
+ *     tags: [General]
+ *     security: []
+ *     responses:
+ *       200:
+ *         description: API information
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 name:
+ *                   type: string
+ *                   example: Cherry Studio API
+ *                 version:
+ *                   type: string
+ *                   example: 1.0.0
+ *                 endpoints:
+ *                   type: object
+ */
+app.get('/', (_req, res) => {
+  res.json({
+    name: 'Cherry Studio API',
+    version: '1.0.0',
+    endpoints: {
+      health: 'GET /health'
+    }
+  })
+})
+
+// Setup OpenAPI documentation before protected routes so docs remain public
+setupOpenAPIDocumentation(app)
+
+// Provider-specific messages route requires authentication
+app.use('/:provider/v1/messages', authMiddleware, extendMessagesTimeout, messagesProviderRoutes)
+
+// API v1 routes with auth
+const apiRouter = express.Router()
+apiRouter.use(authMiddleware)
+// Mount routes
+apiRouter.use('/chat', chatRoutes)
+apiRouter.use('/mcps', mcpRoutes)
+apiRouter.use('/messages', extendMessagesTimeout, messagesRoutes)
+apiRouter.use('/models', modelsRoutes)
+apiRouter.use('/agents', agentsRoutes)
+app.use('/v1', apiRouter)
+
+// Error handling (must be last)
+app.use(errorHandler)
+
+export { app }

src/main/apiServer/config.ts

@@ -0,0 +1,65 @@
+import { ApiServerConfig } from '@types'
+import { v4 as uuidv4 } from 'uuid'
+
+import { loggerService } from '../services/LoggerService'
+import { reduxService } from '../services/ReduxService'
+
+const logger = loggerService.withContext('ApiServerConfig')
+
+const defaultHost = 'localhost'
+const defaultPort = 23333
+
+class ConfigManager {
+  private _config: ApiServerConfig | null = null
+
+  private generateApiKey(): string {
+    return `cs-sk-${uuidv4()}`
+  }
+
+  async load(): Promise<ApiServerConfig> {
+    try {
+      const settings = await reduxService.select('state.settings')
+      const serverSettings = settings?.apiServer
+      let apiKey = serverSettings?.apiKey
+      if (!apiKey || apiKey.trim() === '') {
+        apiKey = this.generateApiKey()
+        await reduxService.dispatch({
+          type: 'settings/setApiServerApiKey',
+          payload: apiKey
+        })
+      }
+      this._config = {
+        enabled: serverSettings?.enabled ?? false,
+        port: serverSettings?.port ?? defaultPort,
+        host: defaultHost,
+        apiKey: apiKey
+      }
+      return this._config
+    } catch (error: any) {
+      logger.warn('Failed to load config from Redux, using defaults', { error })
+      this._config = {
+        enabled: false,
+        port: defaultPort,
+        host: defaultHost,
+        apiKey: this.generateApiKey()
+      }
+      return this._config
+    }
+  }
+
+  async get(): Promise<ApiServerConfig> {
+    if (!this._config) {
+      await this.load()
+    }
+    if (!this._config) {
+      throw new Error('Failed to load API server configuration')
+    }
+    return this._config
+  }
+
+  async reload(): Promise<ApiServerConfig> {
+    return await this.load()
+  }
+}
+
+export const config = new ConfigManager()

src/main/apiServer/config/timeouts.ts

@@ -0,0 +1,3 @@
+export const LONG_POLL_TIMEOUT_MS = 120 * 60_000 // 120 minutes
+
+export const MESSAGE_STREAM_TIMEOUT_MS = LONG_POLL_TIMEOUT_MS

src/main/apiServer/index.ts

@@ -0,0 +1,2 @@
+export { config } from './config'
+export { apiServer } from './server'

src/main/apiServer/middleware/__tests__/auth.test.ts

@@ -0,0 +1,368 @@
+import type { NextFunction, Request, Response } from 'express'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { config } from '../../config'
+import { authMiddleware } from '../auth'
+
+// Mock the config module
+vi.mock('../../config', () => ({
+  config: {
+    get: vi.fn()
+  }
+}))
+
+// Mock the logger
+vi.mock('@logger', () => ({
+  loggerService: {
+    withContext: vi.fn(() => ({
+      debug: vi.fn()
+    }))
+  }
+}))
+
+const mockConfig = config as any
+
+describe('authMiddleware', () => {
+  let req: Partial<Request>
+  let res: Partial<Response>
+  let next: NextFunction
+  let jsonMock: ReturnType<typeof vi.fn>
+  let statusMock: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    jsonMock = vi.fn()
+    statusMock = vi.fn(() => ({ json: jsonMock }))
+
+    req = {
+      header: vi.fn()
+    }
+    res = {
+      status: statusMock
+    }
+    next = vi.fn()
+
+    vi.clearAllMocks()
+  })
+
+  describe('Missing credentials', () => {
+    it('should return 401 when both auth headers are missing', async () => {
+      ;(req.header as any).mockReturnValue('')
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: missing credentials' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should return 401 when both auth headers are empty strings', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return ''
+        if (header === 'x-api-key') return ''
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: missing credentials' })
+      expect(next).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Server configuration', () => {
+    it('should return 403 when API key is not configured', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return 'some-key'
+        return ''
+      })
+
+      mockConfig.get.mockResolvedValue({ apiKey: '' })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should return 403 when API key is null', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return 'some-key'
+        return ''
+      })
+
+      mockConfig.get.mockResolvedValue({ apiKey: null })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('API Key authentication (priority)', () => {
+    const validApiKey = 'valid-api-key-123'
+
+    beforeEach(() => {
+      mockConfig.get.mockResolvedValue({ apiKey: validApiKey })
+    })
+
+    it('should authenticate successfully with valid API key', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return validApiKey
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(next).toHaveBeenCalled()
+      expect(statusMock).not.toHaveBeenCalled()
+    })
+
+    it('should return 403 with invalid API key', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return 'invalid-key'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should return 401 with empty API key', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return '   '
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: empty x-api-key' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should handle API key with whitespace', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return `  ${validApiKey}  `
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(next).toHaveBeenCalled()
+      expect(statusMock).not.toHaveBeenCalled()
+    })
+
+    it('should prioritize API key over Bearer token when both are present', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return validApiKey
+        if (header === 'authorization') return 'Bearer invalid-token'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(next).toHaveBeenCalled()
+      expect(statusMock).not.toHaveBeenCalled()
+    })
+
+    it('should return 403 when API key is invalid even if Bearer token is valid', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return 'invalid-key'
+        if (header === 'authorization') return `Bearer ${validApiKey}`
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Bearer token authentication (fallback)', () => {
+    const validApiKey = 'valid-api-key-123'
+
+    beforeEach(() => {
+      mockConfig.get.mockResolvedValue({ apiKey: validApiKey })
+    })
+
+    it('should authenticate successfully with valid Bearer token when no API key', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return `Bearer ${validApiKey}`
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(next).toHaveBeenCalled()
+      expect(statusMock).not.toHaveBeenCalled()
+    })
+
+    it('should return 403 with invalid Bearer token', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return 'Bearer invalid-token'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should return 401 with malformed authorization header', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return 'Basic sometoken'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: invalid authorization format' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should return 401 with Bearer without space', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return 'Bearer'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: invalid authorization format' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should handle Bearer token with only trailing spaces (edge case)', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return 'Bearer    ' // This will be trimmed to "Bearer" and fail format check
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: invalid authorization format' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should handle Bearer token with case insensitive prefix', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return `bearer ${validApiKey}`
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(next).toHaveBeenCalled()
+      expect(statusMock).not.toHaveBeenCalled()
+    })
+
+    it('should handle Bearer token with whitespace', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return `  Bearer   ${validApiKey}  `
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(next).toHaveBeenCalled()
+      expect(statusMock).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Edge cases', () => {
+    const validApiKey = 'valid-api-key-123'
+
+    beforeEach(() => {
+      mockConfig.get.mockResolvedValue({ apiKey: validApiKey })
+    })
+
+    it('should handle config.get() rejection', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return validApiKey
+        return ''
+      })
+
+      mockConfig.get.mockRejectedValue(new Error('Config error'))
+
+      await expect(authMiddleware(req as Request, res as Response, next)).rejects.toThrow('Config error')
+    })
+
+    it('should use timing-safe comparison for different length tokens', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return 'short'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should return 401 when neither credential format is valid', async () => {
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return 'Invalid format'
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(401)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Unauthorized: invalid authorization format' })
+      expect(next).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('Timing attack protection', () => {
+    const validApiKey = 'valid-api-key-123'
+
+    beforeEach(() => {
+      mockConfig.get.mockResolvedValue({ apiKey: validApiKey })
+    })
+
+    it('should handle similar length but different API keys securely', async () => {
+      const similarKey = 'valid-api-key-124' // Same length, different last char
+
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'x-api-key') return similarKey
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+
+    it('should handle similar length but different Bearer tokens securely', async () => {
+      const similarKey = 'valid-api-key-124' // Same length, different last char
+
+      ;(req.header as any).mockImplementation((header: string) => {
+        if (header === 'authorization') return `Bearer ${similarKey}`
+        return ''
+      })
+
+      await authMiddleware(req as Request, res as Response, next)
+
+      expect(statusMock).toHaveBeenCalledWith(403)
+      expect(jsonMock).toHaveBeenCalledWith({ error: 'Forbidden' })
+      expect(next).not.toHaveBeenCalled()
+    })
+  })
+})

src/main/apiServer/middleware/auth.ts

@@ -0,0 +1,66 @@
+import crypto from 'crypto'
+import { NextFunction, Request, Response } from 'express'
+
+import { config } from '../config'
+
+const isValidToken = (token: string, apiKey: string): boolean => {
+  if (token.length !== apiKey.length) {
+    return false
+  }
+  const tokenBuf = Buffer.from(token)
+  const keyBuf = Buffer.from(apiKey)
+  return crypto.timingSafeEqual(tokenBuf, keyBuf)
+}
+
+export const authMiddleware = async (req: Request, res: Response, next: NextFunction) => {
+  const auth = req.header('authorization') || ''
+  const xApiKey = req.header('x-api-key') || ''
+
+  // Fast rejection if neither credential header provided
+  if (!auth && !xApiKey) {
+    return res.status(401).json({ error: 'Unauthorized: missing credentials' })
+  }
+
+  const { apiKey } = await config.get()
+
+  if (!apiKey) {
+    return res.status(403).json({ error: 'Forbidden' })
+  }
+
+  // Check API key first (priority)
+  if (xApiKey) {
+    const trimmedApiKey = xApiKey.trim()
+    if (!trimmedApiKey) {
+      return res.status(401).json({ error: 'Unauthorized: empty x-api-key' })
+    }
+
+    if (isValidToken(trimmedApiKey, apiKey)) {
+      return next()
+    } else {
+      return res.status(403).json({ error: 'Forbidden' })
+    }
+  }
+
+  // Fallback to Bearer token
+  if (auth) {
+    const trimmed = auth.trim()
+    const bearerPrefix = /^Bearer\s+/i
+
+    if (!bearerPrefix.test(trimmed)) {
+      return res.status(401).json({ error: 'Unauthorized: invalid authorization format' })
+    }
+
+    const token = trimmed.replace(bearerPrefix, '').trim()
+    if (!token) {
+      return res.status(401).json({ error: 'Unauthorized: empty bearer token' })
+    }
+
+    if (isValidToken(token, apiKey)) {
+      return next()
+    } else {
+      return res.status(403).json({ error: 'Forbidden' })
+    }
+  }
+
+  return res.status(401).json({ error: 'Unauthorized: invalid credentials format' })
+}

src/main/apiServer/middleware/error.ts

@@ -0,0 +1,21 @@
+import { NextFunction, Request, Response } from 'express'
+
+import { loggerService } from '../../services/LoggerService'
+
+const logger = loggerService.withContext('ApiServerErrorHandler')
+
+// oxlint-disable-next-line @typescript-eslint/no-unused-vars
+export const errorHandler = (err: Error, _req: Request, res: Response, _next: NextFunction) => {
+  logger.error('API server error', { error: err })
+
+  // Don't expose internal errors in production
+  const isDev = process.env.NODE_ENV === 'development'
+
+  res.status(500).json({
+    error: {
+      message: isDev ? err.message : 'Internal server error',
+      type: 'server_error',
+      ...(isDev && { stack: err.stack })
+    }
+  })
+}

src/main/apiServer/middleware/openapi.ts

@@ -0,0 +1,207 @@
+import { Express } from 'express'
+import swaggerJSDoc from 'swagger-jsdoc'
+import swaggerUi from 'swagger-ui-express'
+
+import { loggerService } from '../../services/LoggerService'
+
+const logger = loggerService.withContext('OpenAPIMiddleware')
+
+const swaggerOptions: swaggerJSDoc.Options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'Cherry Studio API',
+      version: '1.0.0',
+      description: 'OpenAI-compatible API for Cherry Studio with additional Cherry-specific endpoints',
+      contact: {
+        name: 'Cherry Studio',
+        url: 'https://github.com/CherryHQ/cherry-studio'
+      }
+    },
+    servers: [
+      {
+        url: 'http://localhost:23333',
+        description: 'Local development server'
+      }
+    ],
+    components: {
+      securitySchemes: {
+        BearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description: 'Use the API key from Cherry Studio settings'
+        }
+      },
+      schemas: {
+        Error: {
+          type: 'object',
+          properties: {
+            error: {
+              type: 'object',
+              properties: {
+                message: { type: 'string' },
+                type: { type: 'string' },
+                code: { type: 'string' }
+              }
+            }
+          }
+        },
+        ChatMessage: {
+          type: 'object',
+          properties: {
+            role: {
+              type: 'string',
+              enum: ['system', 'user', 'assistant', 'tool']
+            },
+            content: {
+              oneOf: [
+                { type: 'string' },
+                {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      type: { type: 'string' },
+                      text: { type: 'string' },
+                      image_url: {
+                        type: 'object',
+                        properties: {
+                          url: { type: 'string' }
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            },
+            name: { type: 'string' },
+            tool_calls: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string' },
+                  type: { type: 'string' },
+                  function: {
+                    type: 'object',
+                    properties: {
+                      name: { type: 'string' },
+                      arguments: { type: 'string' }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        ChatCompletionRequest: {
+          type: 'object',
+          required: ['model', 'messages'],
+          properties: {
+            model: {
+              type: 'string',
+              description: 'The model to use for completion, in format provider:model-id'
+            },
+            messages: {
+              type: 'array',
+              items: { $ref: '#/components/schemas/ChatMessage' }
+            },
+            temperature: {
+              type: 'number',
+              minimum: 0,
+              maximum: 2,
+              default: 1
+            },
+            max_tokens: {
+              type: 'integer',
+              minimum: 1
+            },
+            stream: {
+              type: 'boolean',
+              default: false
+            },
+            tools: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  type: { type: 'string' },
+                  function: {
+                    type: 'object',
+                    properties: {
+                      name: { type: 'string' },
+                      description: { type: 'string' },
+                      parameters: { type: 'object' }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        Model: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            object: { type: 'string', enum: ['model'] },
+            created: { type: 'integer' },
+            owned_by: { type: 'string' }
+          }
+        },
+        MCPServer: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' },
+            command: { type: 'string' },
+            args: {
+              type: 'array',
+              items: { type: 'string' }
+            },
+            env: { type: 'object' },
+            disabled: { type: 'boolean' }
+          }
+        }
+      }
+    },
+    security: [
+      {
+        BearerAuth: []
+      }
+    ]
+  },
+  apis: ['./src/main/apiServer/routes/*.ts', './src/main/apiServer/app.ts']
+}
+
+export function setupOpenAPIDocumentation(app: Express) {
+  try {
+    const specs = swaggerJSDoc(swaggerOptions)
+
+    // Serve OpenAPI JSON
+    app.get('/api-docs.json', (_req, res) => {
+      res.setHeader('Content-Type', 'application/json')
+      res.send(specs)
+    })
+
+    // Serve Swagger UI
+    app.use(
+      '/api-docs',
+      swaggerUi.serve,
+      swaggerUi.setup(specs, {
+        customCss: `
+        .swagger-ui .topbar { display: none; }
+        .swagger-ui .info .title { color: #1890ff; }
+      `,
+        customSiteTitle: 'Cherry Studio API Documentation'
+      })
+    )
+
+    logger.info('OpenAPI documentation ready', {
+      docsPath: '/api-docs',
+      specPath: '/api-docs.json'
+    })
+  } catch (error) {
+    logger.error('Failed to setup OpenAPI documentation', { error })
+  }
+}

src/main/apiServer/routes/agents/handlers/agents.ts

@@ -0,0 +1,567 @@
+import { loggerService } from '@logger'
+import { AgentModelValidationError, agentService, sessionService } from '@main/services/agents'
+import { ListAgentsResponse, type ReplaceAgentRequest, type UpdateAgentRequest } from '@types'
+import { Request, Response } from 'express'
+
+import type { ValidationRequest } from '../validators/zodValidator'
+
+const logger = loggerService.withContext('ApiServerAgentsHandlers')
+
+const modelValidationErrorBody = (error: AgentModelValidationError) => ({
+  error: {
+    message: `Invalid ${error.context.field}: ${error.detail.message}`,
+    type: 'invalid_request_error',
+    code: error.detail.code
+  }
+})
+
+/**
+ * @swagger
+ * /v1/agents:
+ *   post:
+ *     summary: Create a new agent
+ *     description: Creates a new autonomous agent with the specified configuration and automatically
+ *       provisions an initial session that mirrors the agent's settings.
+ *     tags: [Agents]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/CreateAgentRequest'
+ *     responses:
+ *       201:
+ *         description: Agent created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       400:
+ *         description: Validation error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Internal server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+export const createAgent = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    logger.debug('Creating agent')
+    logger.debug('Agent payload', { body: req.body })
+
+    const agent = await agentService.createAgent(req.body)
+
+    try {
+      logger.info('Agent created', { agentId: agent.id })
+      logger.debug('Creating default session for agent', { agentId: agent.id })
+
+      await sessionService.createSession(agent.id, {})
+
+      logger.info('Default session created for agent', { agentId: agent.id })
+      return res.status(201).json(agent)
+    } catch (sessionError: any) {
+      logger.error('Failed to create default session for new agent, rolling back agent creation', {
+        agentId: agent.id,
+        error: sessionError
+      })
+
+      try {
+        await agentService.deleteAgent(agent.id)
+      } catch (rollbackError: any) {
+        logger.error('Failed to roll back agent after session creation failure', {
+          agentId: agent.id,
+          error: rollbackError
+        })
+      }
+
+      return res.status(500).json({
+        error: {
+          message: `Failed to create default session for agent: ${sessionError.message}`,
+          type: 'internal_error',
+          code: 'agent_session_creation_failed'
+        }
+      })
+    }
+  } catch (error: any) {
+    if (error instanceof AgentModelValidationError) {
+      logger.warn('Agent model validation error during create', {
+        agentType: error.context.agentType,
+        field: error.context.field,
+        model: error.context.model,
+        detail: error.detail
+      })
+      return res.status(400).json(modelValidationErrorBody(error))
+    }
+
+    logger.error('Error creating agent', { error })
+    return res.status(500).json({
+      error: {
+        message: `Failed to create agent: ${error.message}`,
+        type: 'internal_error',
+        code: 'agent_creation_failed'
+      }
+    })
+  }
+}
+
+/**
+ * @swagger
+ * /v1/agents:
+ *   get:
+ *     summary: List all agents
+ *     description: Retrieves a paginated list of all agents
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *           minimum: 1
+ *           maximum: 100
+ *           default: 20
+ *         description: Number of agents to return
+ *       - in: query
+ *         name: offset
+ *         schema:
+ *           type: integer
+ *           minimum: 0
+ *           default: 0
+ *         description: Number of agents to skip
+ *     responses:
+ *       200:
+ *         description: List of agents
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 data:
+ *                   type: array
+ *                   items:
+ *                     $ref: '#/components/schemas/AgentEntity'
+ *                 total:
+ *                   type: integer
+ *                   description: Total number of agents
+ *                 limit:
+ *                   type: integer
+ *                   description: Number of agents returned
+ *                 offset:
+ *                   type: integer
+ *                   description: Number of agents skipped
+ *       400:
+ *         description: Validation error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Internal server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+export const listAgents = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const limit = req.query.limit ? parseInt(req.query.limit as string) : 20
+    const offset = req.query.offset ? parseInt(req.query.offset as string) : 0
+
+    logger.debug('Listing agents', { limit, offset })
+
+    const result = await agentService.listAgents({ limit, offset })
+
+    logger.info('Agents listed', {
+      returned: result.agents.length,
+      total: result.total,
+      limit,
+      offset
+    })
+    return res.json({
+      data: result.agents,
+      total: result.total,
+      limit,
+      offset
+    } satisfies ListAgentsResponse)
+  } catch (error: any) {
+    logger.error('Error listing agents', { error })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to list agents',
+        type: 'internal_error',
+        code: 'agent_list_failed'
+      }
+    })
+  }
+}
+
+/**
+ * @swagger
+ * /v1/agents/{agentId}:
+ *   get:
+ *     summary: Get agent by ID
+ *     description: Retrieves a specific agent by its ID
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent details
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Internal server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+export const getAgent = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const { agentId } = req.params
+    logger.debug('Getting agent', { agentId })
+
+    const agent = await agentService.getAgent(agentId)
+
+    if (!agent) {
+      logger.warn('Agent not found', { agentId })
+      return res.status(404).json({
+        error: {
+          message: 'Agent not found',
+          type: 'not_found',
+          code: 'agent_not_found'
+        }
+      })
+    }
+
+    logger.info('Agent retrieved', { agentId })
+    return res.json(agent)
+  } catch (error: any) {
+    logger.error('Error getting agent', { error, agentId: req.params.agentId })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to get agent',
+        type: 'internal_error',
+        code: 'agent_get_failed'
+      }
+    })
+  }
+}
+
+/**
+ * @swagger
+ * /v1/agents/{agentId}:
+ *   put:
+ *     summary: Update agent
+ *     description: Updates an existing agent with the provided data
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/CreateAgentRequest'
+ *     responses:
+ *       200:
+ *         description: Agent updated successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       400:
+ *         description: Validation error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Internal server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+export const updateAgent = async (req: Request, res: Response): Promise<Response> => {
+  const { agentId } = req.params
+  try {
+    logger.debug('Updating agent', { agentId })
+    logger.debug('Replace payload', { body: req.body })
+
+    const { validatedBody } = req as ValidationRequest
+    const replacePayload = (validatedBody ?? {}) as ReplaceAgentRequest
+
+    const agent = await agentService.updateAgent(agentId, replacePayload, { replace: true })
+
+    if (!agent) {
+      logger.warn('Agent not found for update', { agentId })
+      return res.status(404).json({
+        error: {
+          message: 'Agent not found',
+          type: 'not_found',
+          code: 'agent_not_found'
+        }
+      })
+    }
+
+    logger.info('Agent updated', { agentId })
+    return res.json(agent)
+  } catch (error: any) {
+    if (error instanceof AgentModelValidationError) {
+      logger.warn('Agent model validation error during update', {
+        agentId,
+        agentType: error.context.agentType,
+        field: error.context.field,
+        model: error.context.model,
+        detail: error.detail
+      })
+      return res.status(400).json(modelValidationErrorBody(error))
+    }
+
+    logger.error('Error updating agent', { error, agentId })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to update agent: ' + error.message,
+        type: 'internal_error',
+        code: 'agent_update_failed'
+      }
+    })
+  }
+}
+
+/**
+ * @swagger
+ * /v1/agents/{agentId}:
+ *   patch:
+ *     summary: Partially update agent
+ *     description: Partially updates an existing agent with only the provided fields
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               name:
+ *                 type: string
+ *                 description: Agent name
+ *               description:
+ *                 type: string
+ *                 description: Agent description
+ *               avatar:
+ *                 type: string
+ *                 description: Agent avatar URL
+ *               instructions:
+ *                 type: string
+ *                 description: System prompt/instructions
+ *               model:
+ *                 type: string
+ *                 description: Main model ID
+ *               plan_model:
+ *                 type: string
+ *                 description: Optional planning model ID
+ *               small_model:
+ *                 type: string
+ *                 description: Optional small/fast model ID
+ *               tools:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 description: Tools
+ *               mcps:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 description: MCP tool IDs
+ *               knowledges:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 description: Knowledge base IDs
+ *               configuration:
+ *                 type: object
+ *                 description: Extensible settings
+ *               accessible_paths:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 description: Accessible directory paths
+ *               permission_mode:
+ *                 type: string
+ *                 enum: [readOnly, acceptEdits, bypassPermissions]
+ *                 description: Permission mode
+ *               max_steps:
+ *                 type: integer
+ *                 description: Maximum steps the agent can take
+ *             description: Only include the fields you want to update
+ *     responses:
+ *       200:
+ *         description: Agent updated successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       400:
+ *         description: Validation error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Internal server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+export const patchAgent = async (req: Request, res: Response): Promise<Response> => {
+  const { agentId } = req.params
+  try {
+    logger.debug('Partially updating agent', { agentId })
+    logger.debug('Patch payload', { body: req.body })
+
+    const { validatedBody } = req as ValidationRequest
+    const updatePayload = (validatedBody ?? {}) as UpdateAgentRequest
+
+    const agent = await agentService.updateAgent(agentId, updatePayload)
+
+    if (!agent) {
+      logger.warn('Agent not found for partial update', { agentId })
+      return res.status(404).json({
+        error: {
+          message: 'Agent not found',
+          type: 'not_found',
+          code: 'agent_not_found'
+        }
+      })
+    }
+
+    logger.info('Agent patched', { agentId })
+    return res.json(agent)
+  } catch (error: any) {
+    if (error instanceof AgentModelValidationError) {
+      logger.warn('Agent model validation error during partial update', {
+        agentId,
+        agentType: error.context.agentType,
+        field: error.context.field,
+        model: error.context.model,
+        detail: error.detail
+      })
+      return res.status(400).json(modelValidationErrorBody(error))
+    }
+
+    logger.error('Error partially updating agent', { error, agentId })
+    return res.status(500).json({
+      error: {
+        message: `Failed to partially update agent: ${error.message}`,
+        type: 'internal_error',
+        code: 'agent_patch_failed'
+      }
+    })
+  }
+}
+
+/**
+ * @swagger
+ * /v1/agents/{agentId}:
+ *   delete:
+ *     summary: Delete agent
+ *     description: Deletes an agent and all associated sessions and logs
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     responses:
+ *       204:
+ *         description: Agent deleted successfully
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Internal server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+export const deleteAgent = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const { agentId } = req.params
+    logger.debug('Deleting agent', { agentId })
+
+    const deleted = await agentService.deleteAgent(agentId)
+
+    if (!deleted) {
+      logger.warn('Agent not found for deletion', { agentId })
+      return res.status(404).json({
+        error: {
+          message: 'Agent not found',
+          type: 'not_found',
+          code: 'agent_not_found'
+        }
+      })
+    }
+
+    logger.info('Agent deleted', { agentId })
+    return res.status(204).send()
+  } catch (error: any) {
+    logger.error('Error deleting agent', { error, agentId: req.params.agentId })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to delete agent',
+        type: 'internal_error',
+        code: 'agent_delete_failed'
+      }
+    })
+  }
+}

src/main/apiServer/routes/agents/handlers/index.ts

@@ -0,0 +1,3 @@
+export * as agentHandlers from './agents'
+export * as messageHandlers from './messages'
+export * as sessionHandlers from './sessions'

src/main/apiServer/routes/agents/handlers/messages.ts

@@ -0,0 +1,317 @@
+import { loggerService } from '@logger'
+import { MESSAGE_STREAM_TIMEOUT_MS } from '@main/apiServer/config/timeouts'
+import { createStreamAbortController, STREAM_TIMEOUT_REASON } from '@main/apiServer/utils/createStreamAbortController'
+import { agentService, sessionMessageService, sessionService } from '@main/services/agents'
+import { Request, Response } from 'express'
+
+const logger = loggerService.withContext('ApiServerMessagesHandlers')
+
+// Helper function to verify agent and session exist and belong together
+const verifyAgentAndSession = async (agentId: string, sessionId: string) => {
+  const agentExists = await agentService.agentExists(agentId)
+  if (!agentExists) {
+    throw { status: 404, code: 'agent_not_found', message: 'Agent not found' }
+  }
+
+  const session = await sessionService.getSession(agentId, sessionId)
+  if (!session) {
+    throw { status: 404, code: 'session_not_found', message: 'Session not found' }
+  }
+
+  if (session.agent_id !== agentId) {
+    throw { status: 404, code: 'session_not_found', message: 'Session not found for this agent' }
+  }
+
+  return session
+}
+
+export const createMessage = async (req: Request, res: Response): Promise<void> => {
+  let clearAbortTimeout: (() => void) | undefined
+
+  try {
+    const { agentId, sessionId } = req.params
+
+    const session = await verifyAgentAndSession(agentId, sessionId)
+
+    const messageData = req.body
+
+    logger.info('Creating streaming message', { agentId, sessionId })
+    logger.debug('Streaming message payload', { messageData })
+
+    // Set SSE headers
+    res.setHeader('Content-Type', 'text/event-stream')
+    res.setHeader('Cache-Control', 'no-cache')
+    res.setHeader('Connection', 'keep-alive')
+    res.setHeader('Access-Control-Allow-Origin', '*')
+    res.setHeader('Access-Control-Allow-Headers', 'Cache-Control')
+
+    const {
+      abortController,
+      registerAbortHandler,
+      clearAbortTimeout: helperClearAbortTimeout
+    } = createStreamAbortController({
+      timeoutMs: MESSAGE_STREAM_TIMEOUT_MS
+    })
+    clearAbortTimeout = helperClearAbortTimeout
+    const { stream, completion } = await sessionMessageService.createSessionMessage(
+      session,
+      messageData,
+      abortController
+    )
+    const reader = stream.getReader()
+
+    // Track stream lifecycle so we keep the SSE connection open until persistence finishes
+    let responseEnded = false
+    let streamFinished = false
+
+    const cleanupAbortTimeout = () => {
+      clearAbortTimeout?.()
+    }
+
+    const finalizeResponse = () => {
+      if (responseEnded) {
+        return
+      }
+
+      if (!streamFinished) {
+        return
+      }
+
+      responseEnded = true
+      cleanupAbortTimeout()
+      try {
+        // res.write('data: {"type":"finish"}\n\n')
+        res.write('data: [DONE]\n\n')
+      } catch (writeError) {
+        logger.error('Error writing final sentinel to SSE stream', { error: writeError as Error })
+      }
+      res.end()
+    }
+
+    /**
+     * Client Disconnect Detection for Server-Sent Events (SSE)
+     *
+     * We monitor multiple HTTP events to reliably detect when a client disconnects
+     * from the streaming response. This is crucial for:
+     * - Aborting long-running Claude Code processes
+     * - Cleaning up resources and preventing memory leaks
+     * - Avoiding orphaned processes
+     *
+     * Event Priority & Behavior:
+     * 1. res.on('close') - Most common for SSE client disconnects (browser tab close, curl Ctrl+C)
+     * 2. req.on('aborted') - Explicit request abortion
+     * 3. req.on('close') - Request object closure (less common with SSE)
+     *
+     * When any disconnect event fires, we:
+     * - Abort the Claude Code SDK process via abortController
+     * - Clean up event listeners to prevent memory leaks
+     * - Mark the response as ended to prevent further writes
+     */
+    registerAbortHandler((abortReason) => {
+      cleanupAbortTimeout()
+
+      if (responseEnded) return
+
+      responseEnded = true
+
+      if (abortReason === STREAM_TIMEOUT_REASON) {
+        logger.error('Streaming message timeout', { agentId, sessionId })
+        try {
+          res.write(
+            `data: ${JSON.stringify({
+              type: 'error',
+              error: {
+                message: 'Stream timeout',
+                type: 'timeout_error',
+                code: 'stream_timeout'
+              }
+            })}\n\n`
+          )
+        } catch (writeError) {
+          logger.error('Error writing timeout to SSE stream', { error: writeError })
+        }
+      } else if (abortReason === 'Client disconnected') {
+        logger.info('Streaming client disconnected', { agentId, sessionId })
+      } else {
+        logger.warn('Streaming aborted', { agentId, sessionId, reason: abortReason })
+      }
+
+      reader.cancel(abortReason ?? 'stream aborted').catch(() => {})
+
+      if (!res.headersSent) {
+        res.setHeader('Content-Type', 'text/event-stream')
+        res.setHeader('Cache-Control', 'no-cache')
+        res.setHeader('Connection', 'keep-alive')
+      }
+
+      if (!res.writableEnded) {
+        res.end()
+      }
+    })
+
+    const handleDisconnect = () => {
+      if (abortController.signal.aborted) return
+      abortController.abort('Client disconnected')
+    }
+
+    req.on('close', handleDisconnect)
+    req.on('aborted', handleDisconnect)
+    res.on('close', handleDisconnect)
+
+    const pumpStream = async () => {
+      try {
+        while (!responseEnded) {
+          const { done, value } = await reader.read()
+          if (done) {
+            break
+          }
+
+          res.write(`data: ${JSON.stringify(value)}\n\n`)
+        }
+
+        streamFinished = true
+        finalizeResponse()
+      } catch (error) {
+        if (responseEnded) return
+        logger.error('Error reading agent stream', { error })
+        try {
+          res.write(
+            `data: ${JSON.stringify({
+              type: 'error',
+              error: {
+                message: (error as Error).message || 'Stream processing error',
+                type: 'stream_error',
+                code: 'stream_processing_failed'
+              }
+            })}\n\n`
+          )
+        } catch (writeError) {
+          logger.error('Error writing stream error to SSE', { error: writeError })
+        }
+        responseEnded = true
+        cleanupAbortTimeout()
+        res.end()
+      }
+    }
+
+    pumpStream().catch((error) => {
+      logger.error('Pump stream failure', { error })
+    })
+
+    completion
+      .then(() => {
+        streamFinished = true
+        finalizeResponse()
+      })
+      .catch((error) => {
+        if (responseEnded) return
+        logger.error('Streaming message error', { agentId, sessionId, error })
+        try {
+          res.write(
+            `data: ${JSON.stringify({
+              type: 'error',
+              error: {
+                message: (error as { message?: string })?.message || 'Stream processing error',
+                type: 'stream_error',
+                code: 'stream_processing_failed'
+              }
+            })}\n\n`
+          )
+        } catch (writeError) {
+          logger.error('Error writing completion error to SSE stream', { error: writeError })
+        }
+        responseEnded = true
+        cleanupAbortTimeout()
+        res.end()
+      })
+    // Clear timeout when response ends
+    res.on('close', cleanupAbortTimeout)
+    res.on('finish', cleanupAbortTimeout)
+  } catch (error: any) {
+    clearAbortTimeout?.()
+    logger.error('Error in streaming message handler', {
+      error,
+      agentId: req.params.agentId,
+      sessionId: req.params.sessionId
+    })
+
+    // Send error as SSE if possible
+    if (!res.headersSent) {
+      res.setHeader('Content-Type', 'text/event-stream')
+      res.setHeader('Cache-Control', 'no-cache')
+      res.setHeader('Connection', 'keep-alive')
+    }
+
+    try {
+      const errorResponse = {
+        type: 'error',
+        error: {
+          message: error.status ? error.message : 'Failed to create streaming message',
+          type: error.status ? 'not_found' : 'internal_error',
+          code: error.status ? error.code : 'stream_creation_failed'
+        }
+      }
+
+      res.write(`data: ${JSON.stringify(errorResponse)}\n\n`)
+    } catch (writeError) {
+      logger.error('Error writing initial error to SSE stream', { error: writeError })
+    }
+
+    res.end()
+  }
+}
+
+export const deleteMessage = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const { agentId, sessionId, messageId: messageIdParam } = req.params
+    const messageId = Number(messageIdParam)
+
+    await verifyAgentAndSession(agentId, sessionId)
+
+    const deleted = await sessionMessageService.deleteSessionMessage(sessionId, messageId)
+
+    if (!deleted) {
+      logger.warn('Session message not found', { agentId, sessionId, messageId })
+      return res.status(404).json({
+        error: {
+          message: 'Message not found for this session',
+          type: 'not_found',
+          code: 'session_message_not_found'
+        }
+      })
+    }
+
+    logger.info('Session message deleted', { agentId, sessionId, messageId })
+    return res.status(204).send()
+  } catch (error: any) {
+    if (error?.status === 404) {
+      logger.warn('Delete message failed - missing resource', {
+        agentId: req.params.agentId,
+        sessionId: req.params.sessionId,
+        messageId: req.params.messageId,
+        error
+      })
+      return res.status(404).json({
+        error: {
+          message: error.message,
+          type: 'not_found',
+          code: error.code ?? 'session_message_not_found'
+        }
+      })
+    }
+
+    logger.error('Error deleting session message', {
+      error,
+      agentId: req.params.agentId,
+      sessionId: req.params.sessionId,
+      messageId: Number(req.params.messageId)
+    })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to delete session message',
+        type: 'internal_error',
+        code: 'session_message_delete_failed'
+      }
+    })
+  }
+}

src/main/apiServer/routes/agents/handlers/sessions.ts

@@ -0,0 +1,366 @@
+import { loggerService } from '@logger'
+import { AgentModelValidationError, sessionMessageService, sessionService } from '@main/services/agents'
+import { ListAgentSessionsResponse, type ReplaceSessionRequest, UpdateSessionResponse } from '@types'
+import { Request, Response } from 'express'
+
+import type { ValidationRequest } from '../validators/zodValidator'
+
+const logger = loggerService.withContext('ApiServerSessionsHandlers')
+
+const modelValidationErrorBody = (error: AgentModelValidationError) => ({
+  error: {
+    message: `Invalid ${error.context.field}: ${error.detail.message}`,
+    type: 'invalid_request_error',
+    code: error.detail.code
+  }
+})
+
+export const createSession = async (req: Request, res: Response): Promise<Response> => {
+  const { agentId } = req.params
+  try {
+    const sessionData = req.body
+
+    logger.debug('Creating new session', { agentId })
+    logger.debug('Session payload', { sessionData })
+
+    const session = await sessionService.createSession(agentId, sessionData)
+
+    logger.info('Session created', { agentId, sessionId: session?.id })
+    return res.status(201).json(session)
+  } catch (error: any) {
+    if (error instanceof AgentModelValidationError) {
+      logger.warn('Session model validation error during create', {
+        agentId,
+        agentType: error.context.agentType,
+        field: error.context.field,
+        model: error.context.model,
+        detail: error.detail
+      })
+      return res.status(400).json(modelValidationErrorBody(error))
+    }
+
+    logger.error('Error creating session', { error, agentId })
+    return res.status(500).json({
+      error: {
+        message: `Failed to create session: ${error.message}`,
+        type: 'internal_error',
+        code: 'session_creation_failed'
+      }
+    })
+  }
+}
+
+export const listSessions = async (req: Request, res: Response): Promise<Response> => {
+  const { agentId } = req.params
+  try {
+    const limit = req.query.limit ? parseInt(req.query.limit as string) : 20
+    const offset = req.query.offset ? parseInt(req.query.offset as string) : 0
+    const status = req.query.status as any
+
+    logger.debug('Listing agent sessions', { agentId, limit, offset, status })
+
+    const result = await sessionService.listSessions(agentId, { limit, offset })
+
+    logger.info('Agent sessions listed', {
+      agentId,
+      returned: result.sessions.length,
+      total: result.total,
+      limit,
+      offset
+    })
+    return res.json({
+      data: result.sessions,
+      total: result.total,
+      limit,
+      offset
+    })
+  } catch (error: any) {
+    logger.error('Error listing sessions', { error, agentId })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to list sessions',
+        type: 'internal_error',
+        code: 'session_list_failed'
+      }
+    })
+  }
+}
+
+export const getSession = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const { agentId, sessionId } = req.params
+    logger.debug('Getting session', { agentId, sessionId })
+
+    const session = await sessionService.getSession(agentId, sessionId)
+
+    if (!session) {
+      logger.warn('Session not found', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    // // Verify session belongs to the agent
+    //   logger.warn(`Session ${sessionId} does not belong to agent ${agentId}`)
+    //   return res.status(404).json({
+    //     error: {
+    //       message: 'Session not found for this agent',
+    //       type: 'not_found',
+    //       code: 'session_not_found'
+    //     }
+    //   })
+    // }
+
+    // Fetch session messages
+    logger.debug('Fetching session messages', { sessionId })
+    const { messages } = await sessionMessageService.listSessionMessages(sessionId)
+
+    // Add messages to session
+    const sessionWithMessages = {
+      ...session,
+      messages: messages
+    }
+
+    logger.info('Session retrieved', { agentId, sessionId, messageCount: messages.length })
+    return res.json(sessionWithMessages)
+  } catch (error: any) {
+    logger.error('Error getting session', { error, agentId: req.params.agentId, sessionId: req.params.sessionId })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to get session',
+        type: 'internal_error',
+        code: 'session_get_failed'
+      }
+    })
+  }
+}
+
+export const updateSession = async (req: Request, res: Response): Promise<Response> => {
+  const { agentId, sessionId } = req.params
+  try {
+    logger.debug('Updating session', { agentId, sessionId })
+    logger.debug('Replace payload', { body: req.body })
+
+    // First check if session exists and belongs to agent
+    const existingSession = await sessionService.getSession(agentId, sessionId)
+    if (!existingSession || existingSession.agent_id !== agentId) {
+      logger.warn('Session not found for update', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found for this agent',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    const { validatedBody } = req as ValidationRequest
+    const replacePayload = (validatedBody ?? {}) as ReplaceSessionRequest
+
+    const session = await sessionService.updateSession(agentId, sessionId, replacePayload)
+
+    if (!session) {
+      logger.warn('Session missing during update', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    logger.info('Session updated', { agentId, sessionId })
+    return res.json(session satisfies UpdateSessionResponse)
+  } catch (error: any) {
+    if (error instanceof AgentModelValidationError) {
+      logger.warn('Session model validation error during update', {
+        agentId,
+        sessionId,
+        agentType: error.context.agentType,
+        field: error.context.field,
+        model: error.context.model,
+        detail: error.detail
+      })
+      return res.status(400).json(modelValidationErrorBody(error))
+    }
+
+    logger.error('Error updating session', { error, agentId, sessionId })
+    return res.status(500).json({
+      error: {
+        message: `Failed to update session: ${error.message}`,
+        type: 'internal_error',
+        code: 'session_update_failed'
+      }
+    })
+  }
+}
+
+export const patchSession = async (req: Request, res: Response): Promise<Response> => {
+  const { agentId, sessionId } = req.params
+  try {
+    logger.debug('Patching session', { agentId, sessionId })
+    logger.debug('Patch payload', { body: req.body })
+
+    // First check if session exists and belongs to agent
+    const existingSession = await sessionService.getSession(agentId, sessionId)
+    if (!existingSession || existingSession.agent_id !== agentId) {
+      logger.warn('Session not found for patch', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found for this agent',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    const updateSession = { ...existingSession, ...req.body }
+    const session = await sessionService.updateSession(agentId, sessionId, updateSession)
+
+    if (!session) {
+      logger.warn('Session missing while patching', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    logger.info('Session patched', { agentId, sessionId })
+    return res.json(session)
+  } catch (error: any) {
+    if (error instanceof AgentModelValidationError) {
+      logger.warn('Session model validation error during patch', {
+        agentId,
+        sessionId,
+        agentType: error.context.agentType,
+        field: error.context.field,
+        model: error.context.model,
+        detail: error.detail
+      })
+      return res.status(400).json(modelValidationErrorBody(error))
+    }
+
+    logger.error('Error patching session', { error, agentId, sessionId })
+    return res.status(500).json({
+      error: {
+        message: `Failed to patch session, ${error.message}`,
+        type: 'internal_error',
+        code: 'session_patch_failed'
+      }
+    })
+  }
+}
+
+export const deleteSession = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const { agentId, sessionId } = req.params
+    logger.debug('Deleting session', { agentId, sessionId })
+
+    // First check if session exists and belongs to agent
+    const existingSession = await sessionService.getSession(agentId, sessionId)
+    if (!existingSession || existingSession.agent_id !== agentId) {
+      logger.warn('Session not found for deletion', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found for this agent',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    const deleted = await sessionService.deleteSession(agentId, sessionId)
+
+    if (!deleted) {
+      logger.warn('Session missing during delete', { agentId, sessionId })
+      return res.status(404).json({
+        error: {
+          message: 'Session not found',
+          type: 'not_found',
+          code: 'session_not_found'
+        }
+      })
+    }
+
+    logger.info('Session deleted', { agentId, sessionId })
+
+    const { total } = await sessionService.listSessions(agentId, { limit: 1 })
+
+    if (total === 0) {
+      logger.info('No remaining sessions, creating default', { agentId })
+      try {
+        const fallbackSession = await sessionService.createSession(agentId, {})
+        logger.info('Default session created after delete', {
+          agentId,
+          sessionId: fallbackSession?.id
+        })
+      } catch (recoveryError: any) {
+        logger.error('Failed to recreate session after deleting last session', {
+          agentId,
+          error: recoveryError
+        })
+        return res.status(500).json({
+          error: {
+            message: `Failed to recreate session after deletion: ${recoveryError.message}`,
+            type: 'internal_error',
+            code: 'session_recovery_failed'
+          }
+        })
+      }
+    }
+
+    return res.status(204).send()
+  } catch (error: any) {
+    logger.error('Error deleting session', { error, agentId: req.params.agentId, sessionId: req.params.sessionId })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to delete session',
+        type: 'internal_error',
+        code: 'session_delete_failed'
+      }
+    })
+  }
+}
+
+// Convenience endpoints for sessions without agent context
+export const listAllSessions = async (req: Request, res: Response): Promise<Response> => {
+  try {
+    const limit = req.query.limit ? parseInt(req.query.limit as string) : 20
+    const offset = req.query.offset ? parseInt(req.query.offset as string) : 0
+    const status = req.query.status as any
+
+    logger.debug('Listing all sessions', { limit, offset, status })
+
+    const result = await sessionService.listSessions(undefined, { limit, offset })
+
+    logger.info('Sessions listed', {
+      returned: result.sessions.length,
+      total: result.total,
+      limit,
+      offset
+    })
+    return res.json({
+      data: result.sessions,
+      total: result.total,
+      limit,
+      offset
+    } satisfies ListAgentSessionsResponse)
+  } catch (error: any) {
+    logger.error('Error listing all sessions', { error })
+    return res.status(500).json({
+      error: {
+        message: 'Failed to list sessions',
+        type: 'internal_error',
+        code: 'session_list_failed'
+      }
+    })
+  }
+}

src/main/apiServer/routes/agents/index.ts

@@ -0,0 +1,965 @@
+import express from 'express'
+
+import { agentHandlers, messageHandlers, sessionHandlers } from './handlers'
+import { checkAgentExists, handleValidationErrors } from './middleware'
+import {
+  validateAgent,
+  validateAgentId,
+  validateAgentReplace,
+  validateAgentUpdate,
+  validatePagination,
+  validateSession,
+  validateSessionId,
+  validateSessionMessage,
+  validateSessionMessageId,
+  validateSessionReplace,
+  validateSessionUpdate
+} from './validators'
+
+// Create main agents router
+const agentsRouter = express.Router()
+
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     PermissionMode:
+ *       type: string
+ *       enum: [default, acceptEdits, bypassPermissions, plan]
+ *       description: Permission mode for agent operations
+ *
+ *     AgentType:
+ *       type: string
+ *       enum: [claude-code]
+ *       description: Type of agent
+ *
+ *     AgentConfiguration:
+ *       type: object
+ *       properties:
+ *         permission_mode:
+ *           $ref: '#/components/schemas/PermissionMode'
+ *           default: default
+ *         max_turns:
+ *           type: integer
+ *           default: 10
+ *           description: Maximum number of interaction turns
+ *       additionalProperties: true
+ *
+ *     AgentBase:
+ *       type: object
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: Agent name
+ *         description:
+ *           type: string
+ *           description: Agent description
+ *         accessible_paths:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of directory paths the agent can access
+ *         instructions:
+ *           type: string
+ *           description: System prompt/instructions
+ *         model:
+ *           type: string
+ *           description: Main model ID
+ *         plan_model:
+ *           type: string
+ *           description: Optional planning model ID
+ *         small_model:
+ *           type: string
+ *           description: Optional small/fast model ID
+ *         mcps:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of MCP tool IDs
+ *         allowed_tools:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of allowed tool IDs (whitelist)
+ *         configuration:
+ *           $ref: '#/components/schemas/AgentConfiguration'
+ *       required:
+ *         - model
+ *         - accessible_paths
+ *
+ *     AgentEntity:
+ *       allOf:
+ *         - $ref: '#/components/schemas/AgentBase'
+ *         - type: object
+ *           properties:
+ *             id:
+ *               type: string
+ *               description: Unique agent identifier
+ *             type:
+ *               $ref: '#/components/schemas/AgentType'
+ *             created_at:
+ *               type: string
+ *               format: date-time
+ *               description: ISO timestamp of creation
+ *             updated_at:
+ *               type: string
+ *               format: date-time
+ *               description: ISO timestamp of last update
+ *           required:
+ *             - id
+ *             - type
+ *             - created_at
+ *             - updated_at
+ *     CreateAgentRequest:
+ *       allOf:
+ *         - $ref: '#/components/schemas/AgentBase'
+ *         - type: object
+ *           properties:
+ *             type:
+ *               $ref: '#/components/schemas/AgentType'
+ *             name:
+ *               type: string
+ *               minLength: 1
+ *               description: Agent name (required)
+ *             model:
+ *               type: string
+ *               minLength: 1
+ *               description: Main model ID (required)
+ *           required:
+ *             - type
+ *             - name
+ *             - model
+ *
+ *     UpdateAgentRequest:
+ *       type: object
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: Agent name
+ *         description:
+ *           type: string
+ *           description: Agent description
+ *         accessible_paths:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of directory paths the agent can access
+ *         instructions:
+ *           type: string
+ *           description: System prompt/instructions
+ *         model:
+ *           type: string
+ *           description: Main model ID
+ *         plan_model:
+ *           type: string
+ *           description: Optional planning model ID
+ *         small_model:
+ *           type: string
+ *           description: Optional small/fast model ID
+ *         mcps:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of MCP tool IDs
+ *         allowed_tools:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of allowed tool IDs (whitelist)
+ *         configuration:
+ *           $ref: '#/components/schemas/AgentConfiguration'
+ *       description: Partial update - all fields are optional
+ *
+ *     ReplaceAgentRequest:
+ *       $ref: '#/components/schemas/AgentBase'
+ *
+ *     SessionEntity:
+ *       allOf:
+ *         - $ref: '#/components/schemas/AgentBase'
+ *         - type: object
+ *           properties:
+ *             id:
+ *               type: string
+ *               description: Unique session identifier
+ *             agent_id:
+ *               type: string
+ *               description: Primary agent ID for the session
+ *             agent_type:
+ *               $ref: '#/components/schemas/AgentType'
+ *             created_at:
+ *               type: string
+ *               format: date-time
+ *               description: ISO timestamp of creation
+ *             updated_at:
+ *               type: string
+ *               format: date-time
+ *               description: ISO timestamp of last update
+ *           required:
+ *             - id
+ *             - agent_id
+ *             - agent_type
+ *             - created_at
+ *             - updated_at
+ *
+ *     CreateSessionRequest:
+ *       allOf:
+ *         - $ref: '#/components/schemas/AgentBase'
+ *         - type: object
+ *           properties:
+ *             model:
+ *               type: string
+ *               minLength: 1
+ *               description: Main model ID (required)
+ *           required:
+ *             - model
+ *
+ *     UpdateSessionRequest:
+ *       type: object
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: Session name
+ *         description:
+ *           type: string
+ *           description: Session description
+ *         accessible_paths:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of directory paths the agent can access
+ *         instructions:
+ *           type: string
+ *           description: System prompt/instructions
+ *         model:
+ *           type: string
+ *           description: Main model ID
+ *         plan_model:
+ *           type: string
+ *           description: Optional planning model ID
+ *         small_model:
+ *           type: string
+ *           description: Optional small/fast model ID
+ *         mcps:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of MCP tool IDs
+ *         allowed_tools:
+ *           type: array
+ *           items:
+ *             type: string
+ *           description: Array of allowed tool IDs (whitelist)
+ *         configuration:
+ *           $ref: '#/components/schemas/AgentConfiguration'
+ *       description: Partial update - all fields are optional
+ *
+ *     ReplaceSessionRequest:
+ *       allOf:
+ *         - $ref: '#/components/schemas/AgentBase'
+ *         - type: object
+ *           properties:
+ *             model:
+ *               type: string
+ *               minLength: 1
+ *               description: Main model ID (required)
+ *           required:
+ *             - model
+ *
+ *     CreateSessionMessageRequest:
+ *       type: object
+ *       properties:
+ *         content:
+ *           type: string
+ *           minLength: 1
+ *           description: Message content
+ *       required:
+ *         - content
+ *
+ *     PaginationQuery:
+ *       type: object
+ *       properties:
+ *         limit:
+ *           type: integer
+ *           minimum: 1
+ *           maximum: 100
+ *           default: 20
+ *           description: Number of items to return
+ *         offset:
+ *           type: integer
+ *           minimum: 0
+ *           default: 0
+ *           description: Number of items to skip
+ *         status:
+ *           type: string
+ *           enum: [idle, running, completed, failed, stopped]
+ *           description: Filter by session status
+ *
+ *     ListAgentsResponse:
+ *       type: object
+ *       properties:
+ *         agents:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/AgentEntity'
+ *         total:
+ *           type: integer
+ *           description: Total number of agents
+ *         limit:
+ *           type: integer
+ *           description: Number of items returned
+ *         offset:
+ *           type: integer
+ *           description: Number of items skipped
+ *       required:
+ *         - agents
+ *         - total
+ *         - limit
+ *         - offset
+ *
+ *     ListSessionsResponse:
+ *       type: object
+ *       properties:
+ *         sessions:
+ *           type: array
+ *           items:
+ *             $ref: '#/components/schemas/SessionEntity'
+ *         total:
+ *           type: integer
+ *           description: Total number of sessions
+ *         limit:
+ *           type: integer
+ *           description: Number of items returned
+ *         offset:
+ *           type: integer
+ *           description: Number of items skipped
+ *       required:
+ *         - sessions
+ *         - total
+ *         - limit
+ *         - offset
+ *
+ *     ErrorResponse:
+ *       type: object
+ *       properties:
+ *         error:
+ *           type: object
+ *           properties:
+ *             message:
+ *               type: string
+ *               description: Error message
+ *             type:
+ *               type: string
+ *               description: Error type
+ *             code:
+ *               type: string
+ *               description: Error code
+ *           required:
+ *             - message
+ *             - type
+ *             - code
+ *       required:
+ *         - error
+ */
+
+/**
+ * @swagger
+ * /agents:
+ *   post:
+ *     summary: Create a new agent
+ *     tags: [Agents]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/CreateAgentRequest'
+ *     responses:
+ *       201:
+ *         description: Agent created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       400:
+ *         description: Invalid request body
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+// Agent CRUD routes
+agentsRouter.post('/', validateAgent, handleValidationErrors, agentHandlers.createAgent)
+
+/**
+ * @swagger
+ * /agents:
+ *   get:
+ *     summary: List all agents with pagination
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *           minimum: 1
+ *           maximum: 100
+ *           default: 20
+ *         description: Number of agents to return
+ *       - in: query
+ *         name: offset
+ *         schema:
+ *           type: integer
+ *           minimum: 0
+ *           default: 0
+ *         description: Number of agents to skip
+ *       - in: query
+ *         name: status
+ *         schema:
+ *           type: string
+ *           enum: [idle, running, completed, failed, stopped]
+ *         description: Filter by agent status
+ *     responses:
+ *       200:
+ *         description: List of agents
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ListAgentsResponse'
+ */
+agentsRouter.get('/', validatePagination, handleValidationErrors, agentHandlers.listAgents)
+
+/**
+ * @swagger
+ * /agents/{agentId}:
+ *   get:
+ *     summary: Get agent by ID
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent details
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+agentsRouter.get('/:agentId', validateAgentId, handleValidationErrors, agentHandlers.getAgent)
+/**
+ * @swagger
+ * /agents/{agentId}:
+ *   put:
+ *     summary: Replace agent (full update)
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/ReplaceAgentRequest'
+ *     responses:
+ *       200:
+ *         description: Agent updated successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       400:
+ *         description: Invalid request body
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+agentsRouter.put('/:agentId', validateAgentId, validateAgentReplace, handleValidationErrors, agentHandlers.updateAgent)
+/**
+ * @swagger
+ * /agents/{agentId}:
+ *   patch:
+ *     summary: Update agent (partial update)
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/UpdateAgentRequest'
+ *     responses:
+ *       200:
+ *         description: Agent updated successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/AgentEntity'
+ *       400:
+ *         description: Invalid request body
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+agentsRouter.patch('/:agentId', validateAgentId, validateAgentUpdate, handleValidationErrors, agentHandlers.patchAgent)
+/**
+ * @swagger
+ * /agents/{agentId}:
+ *   delete:
+ *     summary: Delete agent
+ *     tags: [Agents]
+ *     parameters:
+ *       - in: path
+ *         name: agentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Agent ID
+ *     responses:
+ *       204:
+ *         description: Agent deleted successfully
+ *       404:
+ *         description: Agent not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+agentsRouter.delete('/:agentId', validateAgentId, handleValidationErrors, agentHandlers.deleteAgent)
+
+// Create sessions router with agent context
+const createSessionsRouter = (): express.Router => {
+  const sessionsRouter = express.Router({ mergeParams: true })
+
+  // Session CRUD routes (nested under agent)
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions:
+   *   post:
+   *     summary: Create a new session for an agent
+   *     tags: [Sessions]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             $ref: '#/components/schemas/CreateSessionRequest'
+   *     responses:
+   *       201:
+   *         description: Session created successfully
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/SessionEntity'
+   *       400:
+   *         description: Invalid request body
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   *       404:
+   *         description: Agent not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  sessionsRouter.post('/', validateSession, handleValidationErrors, sessionHandlers.createSession)
+
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions:
+   *   get:
+   *     summary: List sessions for an agent
+   *     tags: [Sessions]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: query
+   *         name: limit
+   *         schema:
+   *           type: integer
+   *           minimum: 1
+   *           maximum: 100
+   *           default: 20
+   *         description: Number of sessions to return
+   *       - in: query
+   *         name: offset
+   *         schema:
+   *           type: integer
+   *           minimum: 0
+   *           default: 0
+   *         description: Number of sessions to skip
+   *       - in: query
+   *         name: status
+   *         schema:
+   *           type: string
+   *           enum: [idle, running, completed, failed, stopped]
+   *         description: Filter by session status
+   *     responses:
+   *       200:
+   *         description: List of sessions
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ListSessionsResponse'
+   *       404:
+   *         description: Agent not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  sessionsRouter.get('/', validatePagination, handleValidationErrors, sessionHandlers.listSessions)
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions/{sessionId}:
+   *   get:
+   *     summary: Get session by ID
+   *     tags: [Sessions]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: path
+   *         name: sessionId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Session ID
+   *     responses:
+   *       200:
+   *         description: Session details
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/SessionEntity'
+   *       404:
+   *         description: Agent or session not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  sessionsRouter.get('/:sessionId', validateSessionId, handleValidationErrors, sessionHandlers.getSession)
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions/{sessionId}:
+   *   put:
+   *     summary: Replace session (full update)
+   *     tags: [Sessions]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: path
+   *         name: sessionId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Session ID
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             $ref: '#/components/schemas/ReplaceSessionRequest'
+   *     responses:
+   *       200:
+   *         description: Session updated successfully
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/SessionEntity'
+   *       400:
+   *         description: Invalid request body
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   *       404:
+   *         description: Agent or session not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  sessionsRouter.put(
+    '/:sessionId',
+    validateSessionId,
+    validateSessionReplace,
+    handleValidationErrors,
+    sessionHandlers.updateSession
+  )
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions/{sessionId}:
+   *   patch:
+   *     summary: Update session (partial update)
+   *     tags: [Sessions]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: path
+   *         name: sessionId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Session ID
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             $ref: '#/components/schemas/UpdateSessionRequest'
+   *     responses:
+   *       200:
+   *         description: Session updated successfully
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/SessionEntity'
+   *       400:
+   *         description: Invalid request body
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   *       404:
+   *         description: Agent or session not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  sessionsRouter.patch(
+    '/:sessionId',
+    validateSessionId,
+    validateSessionUpdate,
+    handleValidationErrors,
+    sessionHandlers.patchSession
+  )
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions/{sessionId}:
+   *   delete:
+   *     summary: Delete session
+   *     tags: [Sessions]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: path
+   *         name: sessionId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Session ID
+   *     responses:
+   *       204:
+   *         description: Session deleted successfully
+   *       404:
+   *         description: Agent or session not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  sessionsRouter.delete('/:sessionId', validateSessionId, handleValidationErrors, sessionHandlers.deleteSession)
+
+  return sessionsRouter
+}
+
+// Create messages router with agent and session context
+const createMessagesRouter = (): express.Router => {
+  const messagesRouter = express.Router({ mergeParams: true })
+
+  // Message CRUD routes (nested under agent/session)
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions/{sessionId}/messages:
+   *   post:
+   *     summary: Create a new message in a session
+   *     tags: [Messages]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: path
+   *         name: sessionId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Session ID
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             $ref: '#/components/schemas/CreateSessionMessageRequest'
+   *     responses:
+   *       201:
+   *         description: Message created successfully
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 id:
+   *                   type: number
+   *                   description: Message ID
+   *                 session_id:
+   *                   type: string
+   *                   description: Session ID
+   *                 role:
+   *                   type: string
+   *                   enum: [assistant, user, system, tool]
+   *                   description: Message role
+   *                 content:
+   *                   type: object
+   *                   description: Message content (AI SDK format)
+   *                 agent_session_id:
+   *                   type: string
+   *                   description: Agent session ID for resuming
+   *                 metadata:
+   *                   type: object
+   *                   description: Additional metadata
+   *                 created_at:
+   *                   type: string
+   *                   format: date-time
+   *                 updated_at:
+   *                   type: string
+   *                   format: date-time
+   *       400:
+   *         description: Invalid request body
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   *       404:
+   *         description: Agent or session not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  messagesRouter.post('/', validateSessionMessage, handleValidationErrors, messageHandlers.createMessage)
+
+  /**
+   * @swagger
+   * /agents/{agentId}/sessions/{sessionId}/messages/{messageId}:
+   *   delete:
+   *     summary: Delete a message from a session
+   *     tags: [Messages]
+   *     parameters:
+   *       - in: path
+   *         name: agentId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Agent ID
+   *       - in: path
+   *         name: sessionId
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Session ID
+   *       - in: path
+   *         name: messageId
+   *         required: true
+   *         schema:
+   *           type: integer
+   *         description: Message ID
+   *     responses:
+   *       204:
+   *         description: Message deleted successfully
+   *       404:
+   *         description: Agent, session, or message not found
+   *         content:
+   *           application/json:
+   *             schema:
+   *               $ref: '#/components/schemas/ErrorResponse'
+   */
+  messagesRouter.delete('/:messageId', validateSessionMessageId, handleValidationErrors, messageHandlers.deleteMessage)
+  return messagesRouter
+}
+
+// Mount nested resources with clear hierarchy
+const sessionsRouter = createSessionsRouter()
+const messagesRouter = createMessagesRouter()
+
+// Mount sessions under specific agent
+agentsRouter.use('/:agentId/sessions', validateAgentId, checkAgentExists, handleValidationErrors, sessionsRouter)
+
+// Mount messages under specific agent/session
+agentsRouter.use(
+  '/:agentId/sessions/:sessionId/messages',
+  validateAgentId,
+  validateSessionId,
+  handleValidationErrors,
+  messagesRouter
+)
+
+// Export main router and convenience router
+export const agentsRoutes = agentsRouter

src/main/apiServer/routes/agents/middleware/common.ts

@@ -0,0 +1,44 @@
+import { Request, Response } from 'express'
+
+import { agentService } from '../../../../services/agents'
+import { loggerService } from '../../../../services/LoggerService'
+
+const logger = loggerService.withContext('ApiServerMiddleware')
+
+// Since Zod validators handle their own errors, this is now a pass-through
+export const handleValidationErrors = (_req: Request, _res: Response, next: any): void => {
+  next()
+}
+
+// Middleware to check if agent exists
+export const checkAgentExists = async (req: Request, res: Response, next: any): Promise<void> => {
+  try {
+    const { agentId } = req.params
+    const exists = await agentService.agentExists(agentId)
+
+    if (!exists) {
+      res.status(404).json({
+        error: {
+          message: 'Agent not found',
+          type: 'not_found',
+          code: 'agent_not_found'
+        }
+      })
+      return
+    }
+
+    next()
+  } catch (error) {
+    logger.error('Error checking agent existence', {
+      error: error as Error,
+      agentId: req.params.agentId
+    })
+    res.status(500).json({
+      error: {
+        message: 'Failed to validate agent',
+        type: 'internal_error',
+        code: 'agent_validation_failed'
+      }
+    })
+  }
+}

src/main/apiServer/routes/agents/middleware/index.ts

@@ -0,0 +1 @@
+export * from './common'

src/main/apiServer/routes/agents/validators/agents.ts

@@ -0,0 +1,24 @@
+import {
+  AgentIdParamSchema,
+  CreateAgentRequestSchema,
+  ReplaceAgentRequestSchema,
+  UpdateAgentRequestSchema
+} from '@types'
+
+import { createZodValidator } from './zodValidator'
+
+export const validateAgent = createZodValidator({
+  body: CreateAgentRequestSchema
+})
+
+export const validateAgentReplace = createZodValidator({
+  body: ReplaceAgentRequestSchema
+})
+
+export const validateAgentUpdate = createZodValidator({
+  body: UpdateAgentRequestSchema
+})
+
+export const validateAgentId = createZodValidator({
+  params: AgentIdParamSchema
+})

src/main/apiServer/routes/agents/validators/common.ts

@@ -0,0 +1,7 @@
+import { PaginationQuerySchema } from '@types'
+
+import { createZodValidator } from './zodValidator'
+
+export const validatePagination = createZodValidator({
+  query: PaginationQuerySchema
+})

src/main/apiServer/routes/agents/validators/index.ts

@@ -0,0 +1,4 @@
+export * from './agents'
+export * from './common'
+export * from './messages'
+export * from './sessions'