Migrate window-bounds persistence off the electron-window-state library into
a WindowManager built-in `rememberBounds` capability, backed by the main-process
persist cache (`window.bounds` key — its first real consumer).
- New `windowBoundsTracker` free-function module: validates the stored record
(including displayBounds), restores onto the display the window was last on
(clamping into its work area, never resetting to primary), and snapshots at
teardown via getNormalBounds + isMaximized.
- Singleton-only gate (dev warning for non-singleton types). Runtime toggle
`wm.setRememberBounds` (orthogonal to the registry flag; OFF drops only that
type's slot) plus `wm.peekWindowBounds`.
- Persist at three teardown exits: native close (singletons), before
window.destroy() in destroyWindow (programmatic destroys), and a new onStop
so shutdown writes land before CacheService flushes its persist map.
- Wire Main + QuickAssistant. Main re-applies maximize consumer-side on its own
show schedule (tray-on-launch defers to first show); remove electron-window-state
and its orphaned keepers/constants/comments.
Fullscreen is not persisted and old *-state.json is not migrated (one-time
reset, loseable). Adds tracker/integration/persist tests, extends the main
CacheService mock with persist methods, and documents the capability plus a
breaking-change note.
### What this PR does
**Before this PR**, Cherry Studio managed external CLI binaries through
five uncoordinated mechanisms — each requiring its own download script,
IPC channel, and on-disk layout:
| Mechanism | Where it lived | How it worked |
|---|---|---|
| rtk extraction | `src/main/utils/rtk.ts` + `AgentBootstrapService` |
Copies bundled binary to `~/.cherrystudio/bin/` |
| OpenClaw installer | `resources/scripts/install-openclaw.js` |
Downloads from GitHub/mirror with custom extraction |
| CodeCliService | `src/main/services/CodeCliService.ts` | `bun install
-g` to `~/.cherrystudio/install/global/` |
| ripgrep | `node_modules/@anthropic-ai/claude-agent-sdk/vendor/` |
Vendored, hardcoded path in `FileStorage` |
| (old) MiseService | `src/main/services/MiseService.ts` | Bundled mise
+ `mise use -g` |
**After this PR**, a single `BinaryManager` lifecycle service owns all
third-party CLI binary acquisition. It wraps
[mise](https://mise.jdx.dev) as the only acquisition backend (no custom
`BinaryBackend` interface — mise's polyglot grammar already covers
`npm:`, `pipx:`, `github:`, registry entries). Tools install into an
isolated environment under `~/.cherrystudio/mise/` so user-level mise
installs are never touched. `uv`, `bun`, `rg`, and mise itself ship
bundled at build time for instant first-run availability; everything
else flows through mise on demand.
<img width=\"1304\" height=\"714\" alt=\"BinaryManager settings UI\"
src=\"https://github.com/user-attachments/assets/7a4b78ab-5aa2-4e97-9ab7-134b20a4d78d\"
/>
<img width=\"1165\" height=\"748\" alt=\"Three-state managed vs bundled
vs not-installed\"
src=\"https://github.com/user-attachments/assets/a0dcfb7d-8bc3-4acd-b563-0fc04d99e252\"
/>
<img width=\"523\" height=\"328\" alt=\"Custom tool dialog\"
src=\"https://github.com/user-attachments/assets/90c3ee95-7f2a-4daf-a334-f20de6ff5ca2\"
/>
Fixes#15183. Addresses #15370.
### Why we need it and why it was done in this way
Adding a new managed CLI tool should be a one-line preset entry — not 4+
files of bespoke download/extract/IPC code. mise is a mature polyglot
tool manager that already speaks the backends Cherry needs.
**Tradeoffs made:**
- **mise bundled at build time** (~15 MB per platform) rather than
downloaded at first run — faster first-run UX, no chicken-and-egg on a
fresh install.
- **Fully isolated mise environment** (\`HOME\`/\`XDG_*\`/\`MISE_*\` all
relocated under \`feature.binaries.data\`) — Cherry never reads or
writes the user's own \`~/.config/mise/\` or \`~/.local/share/mise/\`.
- **No custom \`BinaryBackend\` interface.** mise's grammar (\`npm:\`,
\`pipx:\`, \`github:\`, registry) is already polyglot; wrapping it would
be a shallow seam that re-implements what mise owns. Removing this
abstraction makes consumers simpler (deletion test passes).
- **Auth-token policy: opt-in only.** Ambient \`GITHUB_TOKEN\` /
\`GH_TOKEN\` are not forwarded into mise's process env. Users who hit
GitHub's unauthenticated 60 req/hr API limit can set
\`CHERRY_GITHUB_TOKEN\` to raise it to 5000 req/hr without consenting to
share their general shell token.
- **China mirror auto-detection.** \`isUserInChina()\` toggles
\`NPM_CONFIG_REGISTRY=registry.npmmirror.com\` +
\`PIP_INDEX_URL=pypi.tuna.tsinghua.edu.cn\` for every npm/pipx backend
transparently.
**Alternatives considered:**
- *Keep per-tool install scripts.* Doesn't scale — each new tool is 4+
files of duplicated logic.
- *Use mise from user's \`PATH\`.* Would depend on user having mise
installed and could conflict with their config.
- *Custom \`BinaryBackend\` abstraction.* Shallow wrapper over mise's
grammar; no second backend in sight; deletion test passes.
**Scope (what's in / what's out):**
- **In:** uv, bun, ripgrep, claude-code, openclaw, gh, opencode,
gemini-cli, lark, kimi-cli, qwen-code, iflow-cli, github-copilot-cli —
anything mise can install as a single relocatable binary.
- **Out:** \`OvmsManager\` (multi-file server provisioning, hardware
detection, generated config); Tesseract OCR data (not a binary; lives
with \`OvOcrService\`).
### Breaking changes
None at the user-facing layer. v2 data is throwaway per CLAUDE.md, so
the preference-key rename (\`feature.mise.*\` → \`feature.binaries.*\`)
intentionally ships without a migrator.
### Special notes for your reviewer
**Architecture & docs**
- \`docs/references/binary-manager/README.md\` — scope criterion,
persisted/contract surface, bundled-vs-mise state contract, China mirror
behavior, \`CHERRY_GITHUB_TOKEN\` opt-in, adding a new managed binary.
- \`CLAUDE.md\` adds a \`**MUST READ**\` link next to Lifecycle / Window
Manager / Data / Paths.
- The mise-shim-wins-over-\`cherry.bin\` precedence rule is documented
in the README's "State contract" section.
**Code orientation**
- \`src/main/services/BinaryManager.ts\` — the lifecycle service. Wraps
mise via \`runMise()\`; isolated env in \`buildIsolatedEnv()\`; bundled
extraction with atomic tmp+rename; per-tool try/catch so a single
failure can't abort init; \`isManagedBinaryReady()\` verifies the
resolved file is executable (not just that mise thinks it's installed).
- \`packages/shared/data/presets/binary-tools.ts\` —
\`PREDEFINED_BINARY_TOOLS\` registry; \`tool\` field is a mise spec.
-
\`src/renderer/src/pages/settings/McpSettings/EnvironmentDependencies.tsx\`
— three-state UI (\`managed\` / \`bundled\` / \`not-installed\`) backed
by \`Binary_GetState\` + \`Binary_ProbeBundled\`.
- \`scripts/download-binaries.js\` — build-time downloader for mise / uv
/ bun / rg (HTTPS + sha256-verified, archive-aware extraction).
**Migration**
- \`OpenClawService.install()\` is now two lines delegating to
\`BinaryManager\` — \`install-openclaw.js\` is gone.
- \`CodeCliService\` no longer uses \`bun install -g\`; the
\`BUN_INSTALL\` / \`~/.cherrystudio/install/global/\` path is removed.
- \`FileStorage.getRipgrepBinaryPath()\` now resolves via
\`getBinaryPath('rg')\`; the vendored SDK rg is no longer used.
- \`extractRtkBinaries\` + the \`AgentBootstrapService\` call are
deleted. \`rtkRewrite()\` degrades gracefully when rtk is absent;
\`rtkAvailable\` caches with a 60s TTL so install-via-mise takes effect
without restart.
**Multi-round review**
Two adversarial review rounds against this branch (Bug Hunter / Security
/ Architecture / Correctness) ran during development; both rounds'
High-severity findings are addressed in commits \`70afde6af\` and
\`1d864439d\`. R3 known follow-ups (architecture duplications in
\`CodeCliService\`'s switch statements, etc.) are tracked as Medium and
intentionally deferred.
### Checklist
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: Write code that humans can understand and Keep it simple
- [x] Refactor: Leaves binary acquisition meaningfully cleaner than
before (five mechanisms → one)
- [x] Upgrade: v2 data is throwaway; no migrator needed and the absence
is intentional
- [x] Documentation: \`docs/references/binary-manager/README.md\` +
\`CLAUDE.md\` Architecture section
- [x] Self-review: Two multi-perspective review rounds against the
branch; all Highs addressed
### Release note
\`\`\`release-note
NONE
\`\`\`
---------
Signed-off-by: Vaayne <liu.vaayne@gmail.com>
Signed-off-by: Vaayne Liu <vaayne@macos.shared>
Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com>
### What this PR does
Before this PR:
- Knowledge embeddings and reranking ran through the legacy
embedjs-based
knowledgeV1 stack with their own provider clients, independent of the
app's
AI service.
- File-processing intake accepted several heterogeneous input shapes,
and
knowledge file items were tracked by FileEntry ids, coupling file
content to
the file-manager entry/cache.
After this PR:
- Embeddings and reranking are routed through the unified `AiService`
(with
cherryin rerank support) and guarded by strict embedding-dimension
validation
that rejects stale/mismatched vectors.
- File-processing intake is collapsed to a single path-based model;
knowledge
file items are stored by base-relative path under the knowledge-base
directory, and v1 uploads are copied into the v2 base dir during
migration so
migrated items stay reindexable/restorable.
- Legacy `knowledgeV1` is removed; the orchestration services were
renamed to
`KnowledgeService` / `FileProcessingService`.
- Chat -> knowledge attach is temporarily disconnected (tracked TODO)
while the
v2 file-manager bridge is rebuilt.
Fixes #N/A (no linked issue)
### Why we need it and why it was done in this way
Routing embeddings/rerank through `AiService` unifies provider handling
and
credentials and removes the parallel embedjs client stack and its v1
coupling.
Storing knowledge files by base-relative path (instead of FileEntry ids)
makes
each knowledge base self-contained and portable.
The following tradeoffs were made:
- A large, coordinated refactor plus a migration step that physically
copies v1
uploads into the v2 base dir, in exchange for removing the parallel
client
stack and making bases self-contained.
- Base-relative path storage required a fail-fast/dedup strategy for
same-named
files and a guard for blank legacy filenames.
The following alternatives were considered:
- Keeping the embedjs stack behind an adapter — rejected; perpetuates
the
parallel client and v1 coupling.
- Keeping FileEntry-id storage — rejected; couples knowledge files to
the
file-manager cache and blocks portability.
### Breaking changes
- `knowledgeV1` is removed. Legacy v1 knowledge data reaches v2 only
through the
v2 migrators; there is no v1 fallback.
- The v2 knowledge HTTP API (API gateway) now returns v2-native
per-entry fields
(`embeddingModelId`, `createdAt` on base entries; `chunkId`,
`scoreKind`,
`rank` on search results). The response envelope (`knowledge_bases`,
`searched_bases`, `total`) is unchanged. See
`v2-refactor-temp/docs/breaking-changes/2026-06-05-knowledge-api-v2.md`.
### Special notes for your reviewer
- This branch went through several rounds of multi-agent code review.
The most
recent 6 commits address review findings: directory-import path
collisions,
migrated-file source copying + blank `relativePath` guard, addItems
rollback
error preservation, eager `document_to_markdown` output-target
validation, a
`CompletedKnowledgeBase` type guard, and breaking-changes doc
corrections.
- Chat -> knowledge attach is intentionally disconnected for now
(tracked in
`v2-refactor-temp/docs/knowledge/knowledge-todo.md`).
- Local full `pnpm lint`/`pnpm test` was not run per the project's
review
conventions; please rely on CI / `pnpm build:check`.
### Checklist
- [x] Branch: This PR targets the correct branch — `main` for active
development, `v1` for v1 maintenance fixes
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: Write code that humans can understand and Keep it simple
- [x] Refactor: You have left the code cleaner than you found it (Boy
Scout Rule)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] Documentation: A user-guide update was considered and is present
(link) or not required.
- [x] Self-review: I have reviewed my own code before requesting review
from others
### Release note
```release-note
NONE
```
---------
Signed-off-by: eeee0717 <chentao020717Work@outlook.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Replace the v1 renderer-driven disk polling with a main-process service:
- Remove checkAppStorageQuota (browser storage-quota >=95% warning); v2
business data lives in main-process SQLite, so the browser-side quota no
longer reflects where data is stored.
- Add StorageMonitorService (WhenReady, @DependsOn WindowManager): fs.statfs
with capacity-adaptive polling (5-60 min by free space), pushing health
transitions (ok<->low) to the main window only.
- Rename utils/dataLimit.ts to hooks/useStorageMonitorNotification.ts, a thin
subscriber that drives the existing antd notification (UI migration deferred
to the broader v2 refactor).
- Drop the App_GetDiskInfo IPC handler, the getDiskInfo preload API, and the
check-disk-space dependency.
- Add a breaking-change entry for the removed storage-quota warning.
Normalise the bundle id casing from com.cherryai.CherryStudio to
com.cherryai.cherrystudio so it follows the dominant lowercase
convention used by modern AI tools (Anthropic Claude, OpenAI Codex,
Raycast, Docker) and the reverse-DNS norm. macOS LaunchServices is
case-insensitive, so this is a no-op on existing installs - bundle-id
bound state stays as it was after 4439d3b28, and no new breaking-changes
entry is needed.
Touches the same five definition points as the original rebrand
(electron-builder appId, notarize appBundleId, AppUserModelID, selection
self-detection, preview workflow replaceAll/appId) plus the
breaking-changes doc body. The doc's historical commit-subject reference
for 4439d3b28 deliberately retains its original PascalCase to remain a
faithful quote of that commit's subject.
Document the macOS-specific consequences of changing the app bundle id
in 4439d3b28 (com.kangfenmao.CherryStudio -> com.cherryai.CherryStudio):
- User data is preserved automatically because userData is keyed by
productName, not bundle id.
- All bundle-id-scoped macOS state resets (URL scheme registration,
Accessibility / TCC authorizations, safeStorage Keychain entries,
notification permission, Login Items, Documents/Downloads access),
with no code path to migrate it across; users must re-grant each one.
- Auto-update on macOS may be rejected by Squirrel.Mac because the
designated requirement embeds the old bundle id; release manager must
smoke-test the v1 -> v2 update path before promoting v2 to GA.
### What this PR does
Before this PR:
Web Search settings still depended on legacy renderer-side settings
wiring and provider-specific UI structure. Provider selection, API key
editing, blacklist handling, and compression settings were split across
legacy hooks/routes and were not aligned with the v2 preference/provider
configuration model.
After this PR:
Web Search settings are migrated to the v2 data and architecture path:
- Adds `useWebSearch` as the renderer settings hook backed by v2
preference APIs.
- Rebuilds the Web Search settings page around smaller components,
hooks, and utilities for provider metadata, API keys, defaults,
blacklist, and provider checks.
- Uses v2 provider presets and resolved provider capability data for
keyword search and URL fetch defaults.
- Updates preference mappings/classification for removed or normalized
Web Search settings.
- Adds focused tests for the new settings hooks, provider metadata, API
key handling, blacklist parsing, and provider check behavior.
- Documents user-visible v2 Web Search setting changes in the breaking
changes log.
<!-- (optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)`
format, will close the issue(s) when PR gets merged)*: -->
Fixes # N/A
### Why we need it and why it was done in this way
The v2 refactor is moving settings and provider configuration away from
legacy renderer-local state. Web Search settings need to read and write
through the same v2 preference source of truth as the main-side Web
Search service so the UI, migration layer, and runtime configuration use
one provider model.
The following tradeoffs were made:
- The PR keeps the work scoped to Web Search settings and the
preference/provider metadata needed by that settings surface.
- Deprecated settings are removed instead of preserved through
compatibility UI, because v1 Web Search settings are throwaway during
the v2 refactor.
- The settings page is split into local hooks/components instead of
introducing a broader settings framework abstraction.
- Runtime service adjustments are limited to what is required by the
settings schema and preference changes.
The following alternatives were considered:
- Keeping the old `useWebSearchProviders` path as a compatibility layer,
but that would continue dual settings ownership during the v2 migration.
- Preserving the removed subscription-source and cutoff-unit UI, but
those settings do not map cleanly to the v2 Web Search configuration
model.
- Combining this with runtime Web Search tool behavior changes, but that
would make the PR too broad and harder to review.
Links to places where the discussion took place: N/A
### Breaking changes
This PR removes deprecated Web Search settings from the v2 settings
surface:
- Web Search subscription-source management is removed.
- Compression cutoff is normalized to a token-based cutoff limit; the
cutoff unit selector is removed.
Impact: users will configure Web Search through v2 provider defaults,
API keys, capability hosts, blacklist, and compression settings. No
manual migration action is expected.
### Special notes for your reviewer
Scope of this PR:
- Web Search settings UI migration to v2 data/preferences.
- Renderer settings hooks/components/utilities for Web Search provider
configuration.
- Preference classification/mapping changes required by the settings
migration.
- Tests for the settings-side behavior introduced here.
Explicitly out of scope:
- Web Search runtime orchestration in chat responses.
- Built-in/external Web Search tool execution behavior.
- Message rendering for Web Search tool results or citations.
- Model switching behavior and assistant-level `enableWebSearch`
semantics outside the settings migration.
- Large-scale UI design-system replacement beyond the files touched for
this settings migration.
- New provider integrations or provider search algorithm changes.
Review scope note: this PR is based on `v2`, but the intended review
scope is limited to the Web Search settings migration described above.
Web Search runtime/service/tool changes that are already part of the
prerequisite v2 Web Search work are not part of this PR's review scope.
Validation:
- Not run in this PR creation pass.
### Checklist
This checklist is not enforcing, but it's a reminder of items that could
be relevant to every PR.
Approvers are expected to review this list.
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [x] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
Present in `v2-refactor-temp/docs/breaking-changes/`.
- [x] Self-review: I have reviewed my own code (e.g., via
[`/gh-pr-review`](/.claude/skills/gh-pr-review/SKILL.md), `gh pr diff`,
or GitHub UI) before requesting review from others
### Release note
<!-- Write your release note:
1. Enter your extended release note in the below block. If the PR
requires additional action from users switching to the new release,
include the string "action required".
2. If no release note is required, just write "NONE".
3. Only include user-facing changes (new features, bug fixes visible to
users, UI changes, behavior changes). For CI, maintenance, internal
refactoring, build tooling, or other non-user-facing work, write "NONE".
-->
```release-note
Web Search settings now use the v2 preference/provider configuration path. Deprecated subscription-source settings were removed, and compression cutoff is now token-based.
```
---------
Signed-off-by: eeee0717 <chentao020717Work@outlook.com>
### What this PR does
**Before this PR:**
- Right-click menus across the renderer were built with antd's
`Dropdown` (`trigger={['contextMenu']}`) plus an ad-hoc bespoke menu
(`src/renderer/src/components/layout/TabContextMenu.tsx`) for the
AppShell tab bar. There was no shared design-system primitive; styling,
sub-menu support, and `asChild` ergonomics were inconsistent.
- The selection-aware copy/quote wrapper lived at
`src/renderer/src/components/ContextMenu/index.tsx` under a generic name
that suggested it was the canonical context menu (it wasn't — it was
specifically for text selection).
**After this PR:**
- New Radix-based `ContextMenu` primitive lives at
`packages/ui/src/components/primitives/context-menu.tsx`, with the
supporting `ContextMenuItemContent` helper, a new `--cs-menu-item-hover`
design token, and a primitive-level unit test
(`packages/ui/src/components/primitives/__tests__/context-menu.test.tsx`).
- 16 renderer call sites migrated to the new primitive (chat tabs,
topics, agent sessions, attachments, notes, mini-apps, image viewer, SVG
renderer, inputbar tools, citations, messages, skills settings,
assistant items, agent items, assistant preset cards, YAML front
matter).
- `TabContextMenu.tsx` deleted; the old selection wrapper renamed to
`SelectionContextMenu.tsx` and its behavior tightened (see Breaking
changes).
- Async `onSelect` handlers now wrap their work in `try/catch + logger +
toast` so user-visible operations like LLM auto-rename,
save-to-knowledge, and export to Notion/Yuque/etc no longer fail
silently.
Fixes #
### Why we need it and why it was done in this way
`@cherrystudio/ui` is now the v2 design-system home; every other
primitive (Tooltip, Combobox, Toast, TreeSelect, …) has moved here.
Right-click menus were the largest remaining surface still bound to
antd's `Dropdown`. Picking Radix as the backend is consistent with the
rest of the primitive library; building our own `ContextMenuItemContent`
helper keeps the call-site noise low for the common `icon + label +
shortcut/submenu chevron` shape.
The following tradeoffs were made:
- The click-triggered "more actions" Dropdowns in `AssistantItem` /
`AgentItem` / `AssistantPresetCard` / `YamlFrontMatterNodeView` still
use `antd Dropdown` for now — `@cherrystudio/ui` ships `ContextMenu` and
`SelectDropdown` but no click-driven `DropdownMenu` yet. Tracked as
#14994. Acceptable as a follow-up because the migration boundary is at
the right-click surface for this PR.
- `KnowledgePage` / `KnowledgeUrls` / `SkillsSettings` were
intentionally left untouched per @kangfenmao to avoid conflicting with
the knowledge-base PR (#14734). They'll be migrated once that lands.
- For the menu focus-state contrast I originally bumped
`--cs-background-subtle`, but the token leaks into ~44 unrelated
consumers. Reverted and replaced with a dedicated `--cs-menu-item-hover`
token.
The following alternatives were considered:
- Pinning down a click-driven antd shim around the new `ContextMenu` to
handle both triggers in a single tree — rejected; it would have meant
inverting the migration goal (less antd, not more).
- Putting all menu hover styling under one bumped subtle background —
rejected after review; the dedicated `--cs-menu-item-hover` token keeps
the change surgical.
Links to places where the discussion took place:
https://github.com/CherryHQ/cherry-studio/pull/12060#pullrequestreview-4260670092
### Breaking changes
Renamed `ContextMenu` (the selection-aware copy/quote wrapper) to
`SelectionContextMenu`. User-visible behavior change: right-clicking
inside chat messages, citations, and agent session messages now always
shows the menu with disabled items when no text is selected (was: menu
suppressed entirely). Once a selection exists the actions behave
identically to v1. Logged in
`v2-refactor-temp/docs/breaking-changes/2026-05-11-message-right-click-menu-discoverable-when-no-selection.md`.
### Special notes for your reviewer
- The reviewer correctly flagged a regression class where the f2d8db5f7
fix landed mid-PR (drag handler/style getting clobbered when `{...rest}`
was spread after them). The new primitive-level test guards that pattern
at the boundary (asChild forwarding of `onClick` / `onPointerDown` +
`onSelect` semantics).
- macOS transparent-window `z-50` behavior on the tab right-click menu —
I tested locally via the dev build; Radix portals to body and the menu
rides above the title-bar drag region. Worth a focused manual
verification on review.
- Knowledge-base files (`KnowledgePage.tsx`, `KnowledgeUrls.tsx`,
`SkillsSettings.tsx`) were reset to `origin/v2` baseline per @kangfenmao
— see commit `68cbb648d`.
### Checklist
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [x] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
- [x] Self-review: I have reviewed my own code before requesting review
from others
### Release note
```release-note
NONE
```
---------
Signed-off-by: suyao <sy20010504@gmail.com>
Co-authored-by: MyPrototypeWhat <daoquqiexing@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
<!-- Template from
https://github.com/kubevirt/kubevirt/blob/main/.github/PULL_REQUEST_TEMPLATE.md?-->
### What this PR does
This PR adds the new v2 **Resource Library** page at `/app/library` as a
unified management entry point for **Assistants, Agents, and Skills**.
The page provides a shared navigation and interaction shell, but
resource data is loaded per active resource tab. Assistants, Agents, and
Skills each keep their own adapter/query path and backend ownership
boundary; there is no aggregated cross-resource list endpoint in this
PR.
**Scope by resource**
- **Assistant** — when the Assistant tab is active, the library uses the
Assistant DataApi list/create/duplicate/update/delete paths. Assistant
reads include embedded `tags` and `modelName`, and Assistant list
supports `search` and `tagIds` filtering.
- **Agent** — when the Agent tab is active, the library uses the Agent
DataApi list/create/update/delete paths and the Agent editor for
configuration. Agent list supports the resource-library search/tag
filter shape through the Agent DataApi.
- **Skill** — when the Skill tab is active, the library uses Skill
list/detail/import/uninstall flows. Filesystem-affecting operations stay
on the existing skill IPC service, while tag binding and list filtering
use the v2 tag/skill API paths.
Before this PR:
- Assistant, Agent, and Skill management lived in separate product
surfaces.
- There was no shared v2 Resource Library entry point for browsing these
resource types through one navigation model.
- Resource search and tag filtering were not exposed through a
tab-scoped Resource Library UI.
- Assistant list reads did not embed tag metadata or model display names
for the library cards.
After this PR:
- `/app/library` provides a shared Resource Library shell with
resource-specific tabs.
- Switching tabs changes which resource adapter/query path is active; no
cross-resource aggregate query is introduced.
- Assistant, Agent, and Skill lists can be searched and filtered by tags
within their active tab.
- Assistant reads embed `tags[]` and `modelName`, and Assistant
create/update accepts optional `tagIds` for tag binding.
- Agent configuration can be created and edited from the library editor
flow.
- Skill detail, import/install, uninstall, file preview, and tag binding
are available from the library page.
- The library keeps the current v2 `useDataApi.refetch` contract as a
revalidation/cache helper; this PR does not turn `refetch` into an
imperative data-read API.
<!-- (optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)`
format, will close the issue(s) when PR gets merged)*: -->
Fixes #
### Why we need it and why it was done in this way
The v2 Resource Library is intended to replace fragmented
resource-management entry points with one consistent place to browse and
manage Assistants, Agents, and Skills while keeping each resource type's
data ownership intact.
The implementation keeps the Resource Library as a shared UI surface
while keeping reads and writes resource-scoped. Switching tabs changes
which resource adapter/query path is active, so each resource type keeps
its own backend contract instead of introducing a new aggregated query
layer.
The following tradeoffs were made:
- **Shared shell, resource-scoped data**: the UI frame is shared, but
Assistant, Agent, and Skill keep separate adapters and backend paths.
- **No aggregate Resource Library endpoint**: the page does not
introduce a cross-resource list API. This avoids a new orchestration
layer and keeps pagination/filtering behavior owned by each resource
service.
- **Tag filtering uses OR semantics**: matching any selected tag is
enough for inclusion. AND semantics can be added later as a separate
query shape if needed.
- **Filesystem work stays outside DataApi**: Skill install/uninstall
still use the skill IPC service because those operations touch local
directories, archives, repositories, and symlinks.
- **`refetch` remains a revalidation trigger**: direct cache control or
imperative reads should continue to use SWR/DataApi `mutate` or explicit
requests rather than relying on `refetch` return values.
The following alternatives were considered:
- A single aggregated `/library/resources` style endpoint — rejected
because it would duplicate resource-specific filtering logic and blur
service ownership.
- Client-only filtering across all resource types — rejected because
search/tag filtering should use the resource service's current query
contract where available.
- Moving Skill install/uninstall into DataApi — rejected because
filesystem mutation is outside the SQLite-backed DataApi boundary.
Links to places where the discussion took place: N/A
### Breaking changes
None.
The API/schema changes are additive:
- Assistant responses include embedded `tags` and `modelName`.
- Assistant create/update accepts optional `tagIds`.
- Resource list paths support tab-scoped search/tag filtering where
applicable.
Existing callers that do not use the new fields or query params should
continue to work.
### Special notes for your reviewer
Base branch is `v2`. This PR is still a draft while review feedback is
being addressed.
Suggested review entry points:
- Renderer library shell:
`src/renderer/src/pages/library/LibraryPage.tsx`
- Resource list/grid: `src/renderer/src/pages/library/list/`
- Assistant adapter/editor:
`src/renderer/src/pages/library/adapters/assistantAdapter.ts`,
`src/renderer/src/pages/library/editor/assistant/`
- Agent adapter/editor:
`src/renderer/src/pages/library/adapters/agentAdapter.ts`,
`src/renderer/src/pages/library/editor/agent/`
- Skill adapter/detail/import:
`src/renderer/src/pages/library/adapters/skillAdapter.ts`,
`src/renderer/src/pages/library/detail/skill/`,
`src/renderer/src/pages/library/list/ImportSkillDialog.tsx`
- Backend services: `AssistantService`, `AgentService`, `TagService`,
and skill service integration paths.
Known follow-ups:
1. Continue UI polish on Resource Library spacing and detail/editor
interactions.
2. Continue component-level i18n cleanup for any remaining literals
found during review.
3. Keep model-picker related v2 LLM migration work separate from this PR
unless required by this library flow.
### Checklist
This checklist is not enforcing, but it's a reminder of items that could
be relevant to every PR.
Approvers are expected to review this list.
- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [x] Documentation: A [user-guide update](https://docs.cherry-ai.com)
was considered and is present (link) or not required. Check this only
when the PR introduces or changes a user-facing feature or behavior.
- [x] Self-review: I have reviewed my own code (e.g., via
[`/gh-pr-review`](/.claude/skills/gh-pr-review/SKILL.md), `gh pr diff`,
or GitHub UI) before requesting review from others
### Release note
<!-- Write your release note:
1. Enter your extended release note in the below block. If the PR
requires additional action from users switching to the new release,
include the string "action required".
2. If no release note is required, just write "NONE".
3. Only include user-facing changes (new features, bug fixes visible to
users, UI changes, behavior changes). For CI, maintenance, internal
refactoring, build tooling, or other non-user-facing work, write "NONE".
-->
```release-note
Add a new v2 Resource Library page under /app/library for managing Assistants, Agents, and Skills through resource-specific tabs, with search, tag filtering, editors/details, assistant import/export, and skill import/uninstall flows.
```
---------
Signed-off-by: jdzhang <625013594@qq.com>
Signed-off-by: suyao <sy20010504@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: suyao <sy20010504@gmail.com>
Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com>
### What this PR does
Migrates the MiniApp feature from v1 (Redux + sidecar
`custom-minapps.json`) to the v2 data architecture (DataApi + Preference
+ Cache), and integrates it into the v2 AppShell tab system.
**Before this PR**
- App lists lived in three Redux arrays (`enabled` / `disabled` /
`pinned`); custom-app logos were stripped before persistence and
recovered at runtime from `{userData}/Data/Files/custom-minapps.json`.
- Settings (`region`, `max_keep_alive`, `open_link_external`,
`show_opened_in_sidebar`) lived in legacy redux/electron-store.
- Runtime keep-alive used a module-level `lru-cache` singleton, mirrored
into v2 cache via `onInsert` / `disposeAfter` (two sources of truth —
already a known race).
- Routes were `/app/minapp/*`; sidebar icon literal was `'minapp'`.
- Sidebar mode used the legacy popup container; top-navbar mode was
non-functional.
**After this PR**
- A single `mini_app` SQLite table owns every row (preset + custom).
Preset rows are seeded by `MiniAppSeeder` from `PRESETS_MINI_APPS` on
every boot; custom rows come in via `POST /mini-apps`. The seeder uses
`setWhere isNotNull(presetMiniappId)` so refreshing preset display
fields can never overwrite a custom row whose `appId` happens to collide
with a preset.
- `MiniAppMigrator` imports v1 Redux state and reads
`custom-minapps.json` (path resolved through
`MigrationPaths.customMiniAppsFile`) to recover stripped logos.
- Settings live under typed Preference keys
(`feature.mini_app.{region,max_keep_alive,open_link_external}`); sidebar
icon literal renamed `'minapp'` → `'mini_app'` with a complex preference
transform that rewrites existing user arrays in-place.
- API: `GET/POST/PATCH/DELETE /mini-apps` + `POST
/mini-apps/order:batch`, Zod-validated, fractional-indexing ordering
scoped by `status` (cross-status batches are rejected with
`VALIDATION_ERROR` per the data-ordering-guide contract). Status
transitions reassign `orderKey` to the tail of the target partition
inside a transaction.
- Renderer hook `useMiniApps` exposes **command-style** writes only:
`updateAppStatus(id, status)` and `setAppStatusBulk([{id, status}])`.
The legacy declarative `updateMiniApps(list)` /
`updateDisabledMiniApps(list)` / `updatePinnedMiniApps(list)` are gone —
they took region-filtered subsets and silently disabled rows the caller
never saw.
- Keep-alive list is stored solely in
`useCache('mini_app.opened_keep_alive')`. Cap eviction respects AppShell
pin status: `useMiniAppPopup` reads pinned mini-app routes from
`useTabs` and skips them in eviction. `MiniAppTabsPool` renders webviews
in a stable `appId`-sorted order so LRU reorders never move `<webview>`
DOM nodes (Electron `<webview>` loses its guest WebContents on
detach/reattach).
- **Unified launch path**: clicking any miniapp (from the launcher grid
or a top tab bar entry) calls `openTab('/app/mini-app/<id>', { title,
icon: app.logo })`. A globally-mounted `<MiniAppTabsPool>` in `AppShell`
keeps a `<webview>` alive per opened app, regardless of sidebar vs
top-navbar layout.
- Settings UI rewritten as a `PageSidePanel` drawer composed of
`MiniAppListPair` (visible / hidden columns with drag-drop) and
`MiniAppDisplaySettings` (region / cache slider). New custom-app form is
a separate `NewMiniAppPanel` drawer.
- Sidebar's running-mini-apps strip removed — opened apps live
exclusively in the top tab bar (per #3198804265). Companion preference
`feature.mini_app.show_opened_in_sidebar` deleted from the schema.
### Why we need it and why it was done in this way
Part of the broader v2 data-layer migration (Redux/Dexie/ElectronStore →
DataApi + Preference + Cache).
**Architecture**
- DataApi for entity rows (preserves user content); Preference for
atomic settings; Cache (Memory tier) for runtime ephemera.
- Layered preset pattern (`best-practice-layered-preset-pattern.md`):
preset and custom rows share the same table, discriminated by
`presetMiniappId`. Seeder refreshes preset display fields on re-run;
custom rows are immutable to the seeder.
- Region filtering is a **view-only** concern (read path); the write
path is command-style and never references region. This eliminated a
class of bugs where editing the visible (filtered) list caused
region-hidden rows to drift.
- AppShell tab pinning is the canonical "keep this loaded" signal. The
keep-alive cap respects it; pinned mini-app tabs never get evicted
regardless of cap. Render-order independence in `MiniAppTabsPool`
ensures LRU touches don't move `<webview>` nodes around.
- Per-app icon resolution: `app.logo` is a `CompoundIcon` id (e.g.
`"Moonshot"`) for presets and a URL for custom apps. UI consumers (tab
bar, sidebar entry, settings list) call `getMiniAppsLogo` to resolve the
id to a `CompoundIcon` before rendering, with `<img>` fallback for URL
strings.
- Per-entity tab icons are cleared on internal navigation, sidebar
reuse, and the top-bar settings button — three call sites that all flip
the active tab's URL now consistently reset `icon: undefined` so a
mini-app logo never sticks onto an unrelated route.
**Tradeoffs**
- `useMiniApps` still exposes `miniapps` (region-filtered
enabled+pinned) and `disabled` (region-filtered). These are display-only
views. Renamed/typed wrappers were considered but deferred — the
refactor to command-style writes already eliminated the bug class that
motivated the rename.
- The `applyReorderedList` integration test for
`reorderMiniAppsByStatus` was dropped — `MockUseDataApiUtils` doesn't
fill the SWR cache that `useReorder.readCurrent` reads. Splice logic is
straightforward and the server-side `applyScopedMoves` test covers the
contract.
- Sidebar primitives in `@cherrystudio/ui`-adjacent layout still accept
`miniAppTabs` / `onMiniAppTabClick` props (defensive defaults — render
nothing without a producer). Removing these from the primitive's API is
a separate refactor not in scope.
### Breaking changes
User-visible changes are auto-migrated by the v2 migration framework —
no manual user action required:
- Sidebar icon literal `'minapp'` → `'mini_app'` (rewritten by the
`sidebar_icons_rename` complex preference transform)
- Preference key rename `feature.minapp.*` → `feature.mini_app.*`
(auto-migrated via `classification.json`)
- Custom-app logos stripped from v1 Redux are recovered from
`custom-minapps.json` during migration
One product-shape change is documented under
`v2-refactor-temp/docs/breaking-changes/`:
- `2026-05-07-miniapp-sidebar-running-list-removed.md` — the sidebar no
longer surfaces opened mini-apps under the mini-app entry. Open apps are
accessed exclusively via the top tab bar; pin a tab to keep its state
across switches.
The legacy v1 preference `showOpenedMinappsInSidebar` is reclassified as
`status: deleted` in the migration pipeline; v1 values are dropped
during v1→v2 migration with no v2 destination.
### Special notes for your reviewer
**Verified end-to-end on a real dev profile**: v1 Redux state +
`custom-minapps.json` → v2 SQLite, including pinned-app cross-group
dedup (a v1 pinned app appears in both `pinned` and `enabled` Redux
arrays; the migrator counts duplicates as skipped so the engine's
`targetCount >= sourceCount - skippedCount` invariant holds — without
this, any user with pinned miniapps was blocked from migrating).
**Drizzle migrations** are throwaway in dev per `CLAUDE.md`.
`migrations/sqlite-drizzle/0020_even_hulk.sql` is the single regenerated
migration; it will be wiped to a clean initial migration before release.
**Review history**: 28 line-comments across multiple formal review
rounds. All resolved. The most consequential fixes:
- `applyScopedMoves` in `MiniAppService.reorder` — rejects cross-status
batches with `VALIDATION_ERROR` instead of silently splitting them.
- `update()` reassigns `orderKey` to a fresh tail in the target
partition on status change.
- Empty-string substitution in migrator mappings is now caught by the
post-transform validity check; bad rows are skipped + warned, never
inserted.
- Migrator validation switched from `limit(5)` sample to full `count(*)
WHERE empty-fields` — bad rows can no longer pass validation by virtue
of being beyond the sample window.
- Keep-alive cap exempts pinned tabs (#3198809321 + the kangfenmao
keepalive review); render order in `MiniAppTabsPool` is `appId`-stable
so LRU touches don't move `<webview>` nodes (this was the root cause of
"switching tabs reloads the webview").
**Out of scope**:
- The remaining `@renderer/store/tabs` import in
`PaintingsRoutePage.tsx` is pre-existing v1 residual (not introduced or
touched by this PR).
### Checklist
- [x] PR: description rewritten to reflect the final architecture +
integration with the AppShell tab system
- [x] Code: command-style writes (`updateAppStatus` /
`setAppStatusBulk`); see `useMiniApps`, `MiniAppService`,
`MiniAppMigrator`, `MiniAppTabsPool`, `useMiniAppPopup` for the main
entry points
- [x] Refactor: ~1500 lines of dead/legacy code removed
(`Tab/TabContainer`, `TabsService`, `MiniAppPopupContainer`,
`TopViewMiniAppContainer`, legacy LRU singleton, `PinnedMiniApps`, dead
`userOverrides` / `MiniAppRegistryService`, unused `Signal.ts`)
- [x] Upgrade: v1 → v2 migration verified end-to-end on a real dev
instance
- [x] Documentation: architecture covered by `docs/references/data/`;
one user-visible behavior change documented in
`v2-refactor-temp/docs/breaking-changes/`
- [x] Self-review: multi-agent review via `/gh-pr-review` (twice); all
28 review comments resolved
### Release note
```release-note
NONE - Internal v2 data refactor. User-facing renames (route, sidebar icon, preference keys) are auto-migrated. The sidebar no longer shows a running-mini-apps strip; opened apps live in the top tab bar.
```
---------
Signed-off-by: suyao <sy20010504@gmail.com>
Signed-off-by: chengcheng84 <hello_world0000@outlook.com>
Co-authored-by: suyao <sy20010504@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
Add a v2 breaking-change fragment documenting the Cherry Studio.exe →
CherryStudio.exe rename on Windows: who is affected, what auto-handles,
and which manual references (Task Scheduler, firewall allow-lists,
AutoHotkey scripts, custom .bat files, in-app filter list) users must
update by hand.
Add an internal record for v2 changes that affect how users use the
app. PR authors drop a fragment .md per change; the release manager
aggregates and translates them into the Chinese user-facing release
note at v2.0.0, then discards the fragments with v2-refactor-temp/.
Also translate v2-refactor-temp/README.md to English and link the new
directory from it.
