Adds a unified, file-backed SQLite test harness under tests/helpers/db/
that provisions a real database per test file using the production
migrations + CUSTOM_SQL_STATEMENTS, wires it through
MockMainDbServiceUtils.setDb() so production code reaches it via
application.get('DbService').getDb() transparently, truncates user
tables on beforeEach, and cleans up on afterAll. Replaces the need for
hand-written CREATE TABLE SQL and inline vi.mock('@application')
overrides in consumer tests.
Companion changes:
- Register @test-helpers/* path alias (electron.vite.config.ts,
tsconfig.node.json paths + include, vitest.config.ts main project
include).
- Relax the global vi.mock stubs for node:fs, node:os, node:path in
tests/main.setup.ts so third-party libraries (drizzle-orm migrator
etc.) can read real files. The six existing tests that depended on
the previous fully-stubbed modules now declare a local
vi.mock('node:fs', ...) via the new createNodeFsMock helper at
tests/helpers/mocks/nodeFsMock.ts.
- Self-tests under tests/helpers/db/__tests__/testDatabase.test.ts
cover PRAGMA state, truncate semantics, FTS5 trigger cascades,
NULL-searchableText handling, application-mock routing, and
replay-array accumulation guards.
Align with the existing @logger alias convention by introducing
@application as a short alias for src/main/core/application. This
reduces import verbosity across ~130 main-process files while keeping
4 intentional sub-path imports (@main/core/application/Application)
unchanged to preserve the vi.mock bypass mechanism in tests.
Configured in tsconfig.node.json and electron.vite.config.ts; Vitest
inherits the alias automatically.
Signed-off-by: fullex <0xfullex@gmail.com>
Merge main branch changes including CherryClaw agent system (#13359),
new settings routes (skills, channels, scheduled-tasks), and various
fixes. Adapted merged code to v2 architecture:
- Migrated new routes to TanStack Router (file-based routing)
- Migrated TasksSettings from react-router-dom/Redux to TanStack Router/CacheService
- Migrated baseCallbacks.ts from Redux dispatch to StreamingService
- Added agent bootstrap initialization to v2 entry point
- Replaced antd Switch with @cherrystudio/ui Switch in AgentModal
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: suyao <sy20010504@gmail.com>
### What this PR does
Before this PR:
Cherry Studio only supports `claude-code` as an agent type. Agents have
no autonomous scheduling, no IM channel integration, and no
soul/personality system.
After this PR:
Introduces **CherryClaw** — a new autonomous agent type with:
- **Soul-driven personality**: Markdown-based soul files with
mtime-cached reading
- **Task-based scheduler**: Poll-loop scheduler with drift-resistant
interval computation, tasks as first-class DB entities
(nanoclaw-inspired)
- **Internal claw MCP server**: `cron` tool (add/list/remove)
auto-injected into CherryClaw sessions for autonomous task management
- **Channel abstraction layer**: Pluggable adapter pattern with Telegram
as the first implementation (grammY, long polling, streaming drafts,
typing indicators)
- **Headless message persistence**: Channel and scheduler messages now
persist to the agent SQLite DB
- **Basic sandbox mode**: PreToolUse hook path enforcement + OS-level
sandbox toggle
- **Full UI**: Agent creation modal with type selector, settings tabs
(soul, tasks, channels, advanced), task management CRUD, channel catalog
with inline config
- **53 unit tests** across 8 test files covering all new services
<!-- Fixes # -->
### Why we need it and why it was done in this way
CherryClaw enables Cherry Studio agents to operate autonomously —
executing scheduled tasks and responding to IM messages without user
interaction. This is the foundation for "always-on" AI assistants.
The following tradeoffs were made:
- **Poll-loop scheduler over timer-based**: DB is the source of truth;
no timer state to restore on restart. Simpler, more robust at the cost
of up to 60s latency.
- **AgentServiceRegistry pattern**: Replaced hardcoded
`ClaudeCodeService` in `SessionMessageService` with a registry mapping
`AgentType` → service. Extensible for future agent types.
- **Internal MCP server for cron**: Rather than extending the SDK's tool
system, the `cron` tool is served as a standard MCP server at
`/v1/claw/:agentId/claw-mcp`. This lets the agent discover and use it
naturally.
- **Channel abstraction over direct Telegram integration**:
`ChannelAdapter` + factory registration enables future Discord/Slack
adapters without touching core routing logic.
- **Basic sandbox (not security boundary)**: PreToolUse hook + OS
sandbox provides best-effort restriction for well-behaved agents. Known
bypass vectors documented; hardening deferred.
The following alternatives were considered:
- cron-based OS scheduling (rejected: harder to manage lifecycle, no DB
integration)
- Direct Telegram bot API calls (rejected: grammY provides typed API,
connection management, and middleware)
- Modifying SDK builtin tools (rejected: internal MCP server is cleaner
separation)
### Breaking changes
None. This is a new agent type (`cherry-claw`) alongside the existing
`claude-code` type. No existing behavior is modified.
### Special notes for your reviewer
- **New DB migration**: `0003_wise_meltdown.sql` adds `scheduled_tasks`
and `task_run_logs` tables (agents DB only, not IndexedDB)
- **New dependencies**: `cron-parser` ^5.5.0, `grammy` ^1.41
- **Placeholder avatar**: `cherry-claw.png` is currently a copy of
`claude.png` — needs a proper distinct image
- **74 files changed, ~7400 lines added** — large PR, recommend
reviewing by phase (type system → backend services → MCP → channels → UI
→ tests)
- **Sandbox is basic only**: The PreToolUse path checking has known
bypasses (relative paths, variable expansion). Documented in handoff.md.
Hardening is follow-up work.
- The `handoff.md` file in the repo root contains full architectural
context and decisions
### 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)
- [ ] Upgrade: Impact of this change on upgrade flows was considered and
addressed if required
- [ ] 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.
- [ ] 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
```release-note
New CherryClaw agent type: autonomous agents with soul-driven personality, task-based scheduling (cron/interval/one-time), internal cron MCP tool for self-managed tasks, Telegram channel integration with streaming responses, and basic sandbox mode for filesystem restriction.
```
---------
Signed-off-by: Vaayne <liu.vaayne@gmail.com>
Signed-off-by: suyao <sy20010504@gmail.com>
Signed-off-by: Siin Xu <31815270+SiinXu@users.noreply.github.com>
Signed-off-by: zhangjiadi225 <625013594@qq.com>
Signed-off-by: greycheng255 <greycheng255@gmail.com>
Co-authored-by: kangfenmao <kangfenmao@qq.com>
Co-authored-by: suyao <sy20010504@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Siin Xu <31815270+SiinXu@users.noreply.github.com>
Co-authored-by: fullex <106392080+0xfullex@users.noreply.github.com>
Co-authored-by: zhangjiadi225 <625013594@qq.com>
Add ipcHandle() and ipcOn() helper methods to BaseService that
automatically track registered IPC handlers and clean them up on
service stop/destroy, eliminating manual unregisterIpcHandlers()
boilerplate and preventing handler leaks.
Key changes:
- BaseService.ipcHandle(): wraps ipcMain.handle() with auto-tracking
- BaseService.ipcOn(): wraps ipcMain.on() with auto-tracking
- _doStop(): uses try/finally to guarantee IPC cleanup even on error
- _doDestroy(): safety-net cleanup for services destroyed without stop
- 9 new test cases covering all IPC lifecycle scenarios
- Updated lifecycle docs (decision guide, usage, overview, migration)
Signed-off-by: fullex <0xfullex@gmail.com>
Replace ad-hoc vi.mock('@main/core/application') calls across test files
with a centralized mockApplicationFactory(overrides?) utility that provides
all registered services by default and supports per-service overrides.
- Add tests/__mocks__/main/DbService.ts (standalone DbService mock)
- Add tests/__mocks__/main/application.ts (unified factory)
- Simplify tests/main.setup.ts global mock
- Migrate 4 test files to use mockApplicationFactory
- Document unified mock system in CLAUDE.md and README.md
Signed-off-by: fullex <0xfullex@gmail.com>
- Add global @main/core/application mock in main.setup.ts
- Update service mocks to export class constructors alongside instances
- Migrate test files from singleton imports to application.get() mocks
Signed-off-by: fullex <0xfullex@gmail.com>
### What this PR does
Before this PR:
- Backup system used a complex nested structure that was harder to
maintain
- No support for legacy backup format (LAN transfer)
- Limited path security validation
- electron-store config.json was stored in userData root, not included
in backups
After this PR:
- Implements direct backup and restore methods for IndexedDB and Local
Storage
- Adds legacy backup (LAN transfer) functionality for backward
compatibility
- Implements startup restoration support
- Enhances path security with `resolveAndValidatePath` to prevent
directory traversal attacks
- Simplifies BackupManager constructor and methods
- Adds Joplin and Siyuan icons
- Updates backup metadata structure and progress handling
- Moves electron-store config.json to userData/Data directory so it's
included in backups
- Adds automatic migration from legacy config location
Fixes #
### Why we need it and why it was done in this way
The following tradeoffs were made:
- Added path validation overhead for enhanced security
- Legacy backup format support increases code complexity but ensures
backward compatibility
The following alternatives were considered:
- Keeping the old backup structure, but it was harder to maintain and
extend
Links to places where the discussion took place: N/A
### Breaking changes
The backup format has been updated to a new version. Existing backups
created with older versions will still be supported through the legacy
backup functionality.
### Special notes for your reviewer
- The `resolveAndValidatePath` utility prevents path traversal attacks
by validating that resolved paths stay within expected directories
- The BasicDataSettings component was extracted to improve code
organization
- Tests have been updated to cover the new backup functionality
- electron-store config location changed from `userData/config.json` to
`userData/Data/config.json` with automatic migration
### 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.
- [ ] 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
```release-note
Enhanced backup system with new format (v6), legacy backup support, improved path security, and config.json now included in backups
```
---------
Signed-off-by: kangfenmao <kangfenmao@qq.com>
* feat(mcp): add hub server type definitions
- Add 'hub' to BuiltinMCPServerNames enum as '@cherry/hub'
- Create GeneratedTool, SearchQuery, ExecInput, ExecOutput types
- Add ExecutionContext and ConsoleMethods interfaces
Amp-Thread-ID: https://ampcode.com/threads/T-019b4e7d-86a3-770d-82f8-9e646e7e597e
Co-authored-by: Amp <amp@ampcode.com>
* feat(mcp): implement hub server core components
- generator.ts: Convert MCP tools to JS functions with JSDoc
- tool-registry.ts: In-memory cache with 10-min TTL
- search.ts: Comma-separated keyword search with ranking
- runtime.ts: Code execution with parallel/settle/console helpers
Amp-Thread-ID: https://ampcode.com/threads/T-019b4e7d-86a3-770d-82f8-9e646e7e597e
Co-authored-by: Amp <amp@ampcode.com>
* feat(mcp): integrate hub server with MCP infrastructure
- Create HubServer class with search/exec tools
- Implement mcp-bridge for calling tools via MCPService
- Register hub server in factory with dependency injection
- Initialize hub dependencies in MCPService constructor
- Add hub server description label for i18n
Amp-Thread-ID: https://ampcode.com/threads/T-019b4e7d-86a3-770d-82f8-9e646e7e597e
Co-authored-by: Amp <amp@ampcode.com>
* test(mcp): add unit tests for hub server
- generator.test.ts: Test schema conversion and JSDoc generation
- search.test.ts: Test keyword matching, ranking, and limits
- runtime.test.ts: Test code execution, helpers, and error handling
Amp-Thread-ID: https://ampcode.com/threads/T-019b4e7d-86a3-770d-82f8-9e646e7e597e
Co-authored-by: Amp <amp@ampcode.com>
* docs(mcp): add hub server documentation
- Document search/exec tool usage and parameters
- Explain configuration and caching behavior
- Include architecture diagram and file structure
Amp-Thread-ID: https://ampcode.com/threads/T-019b4e7d-86a3-770d-82f8-9e646e7e597e
Co-authored-by: Amp <amp@ampcode.com>
* ♻️ refactor(hub): simplify dependency injection for HubServer
- Remove HubServerDependencies interface and setHubServerDependencies from factory
- Add initHubBridge() to mcp-bridge for direct initialization
- Make HubServer constructor parameterless (uses pre-initialized bridge)
- MCPService now calls initHubBridge() directly instead of factory setter
- Add integration tests for full search → exec flow
* 📝 docs(hub): add comments explaining why hub is not in builtin list
- Add JSDoc to HubServer class explaining its purpose and design
- Add comment to builtinMCPServers explaining hub exclusion
- Hub is a meta-server for LLM code mode, auto-enabled internally
* ✨ feat: add available tools section to HUB_MODE_SYSTEM_PROMPT
- Add shared utility for generating MCP tool function names (serverName_toolName format)
- Update hub server to use consistent function naming across search, exec and prompt
- Add fetchAllActiveServerTools to ApiService for renderer process
- Update parameterBuilder to include available tools in auto/hub mode prompt
- Use CacheService for 1-minute tools caching in hub server
- Remove ToolRegistry in favor of direct fetching with caching
- Update search ranking to include server name matching
- Fix tests to use new naming format
Amp-Thread-ID: https://ampcode.com/threads/T-019b6971-d5c9-7719-9245-a89390078647
Co-authored-by: Amp <amp@ampcode.com>
* ♻️ refactor: consolidate MCP tool name utilities into shared module
- Merge buildFunctionCallToolName from src/main/utils/mcp.ts into packages/shared/mcp.ts
- Create unified buildMcpToolName base function with options for prefix, delimiter, maxLength, existingNames
- Fix toCamelCase to normalize uppercase snake case (MY_SERVER → myServer)
- Fix maxLength + existingNames interaction to respect length limit when adding collision suffix
- Add comprehensive JSDoc documentation
- Update tests and hub.test.ts for new lowercase normalization behavior
* ✨ feat: isolate hub exec worker and filter disabled tools
* 🐛 fix: inline hub worker source
* 🐛 fix: sync hub tool cache and map
* Update import path for buildFunctionCallToolName in BaseService
* ✨ feat: refine hub mode system prompt
* 🐛 fix: propagate hub tool errors
* 📝 docs: clarify hub exec return
* ✨ feat(hub): improve prompts and tool descriptions for better LLM success rate
- Rewrite HUB_MODE_SYSTEM_PROMPT_BASE with Critical Rules section
- Add Common Mistakes to Avoid section with examples
- Update exec tool description with IMPORTANT return requirement
- Improve search tool description clarity
- Simplify generator output with return reminder in header
- Add per-field @param JSDoc with required/optional markers
Fixes issue where LLMs forgot to return values from exec code
* ♻️ refactor(hub): return empty string when no tools available
* ✨ feat(hub): add dedicated AUTO_MODE_SYSTEM_PROMPT for auto mode
- Create self-contained prompt teaching XML tool_use format
- Only shows search/exec tools (no generic examples)
- Add complete workflow example with common mistakes
- Update parameterBuilder to use getAutoModeSystemPrompt()
- User prompt comes first, then auto mode instructions
- Skip hub prompt when no tools available
* ♻️ refactor: move hub prompts to dedicated prompts-code-mode.ts
- Create src/renderer/src/config/prompts-code-mode.ts
- Move HUB_MODE_SYSTEM_PROMPT_BASE and AUTO_MODE_SYSTEM_PROMPT_BASE
- Move getHubModeSystemPrompt() and getAutoModeSystemPrompt()
- Extract shared buildToolsSection() helper
- Update parameterBuilder.ts import
* ♻️ refactor: add mcpMode support to promptToolUsePlugin
- Add mcpMode parameter to PromptToolUseConfig and defaultBuildSystemPrompt
- Pass mcpMode through middleware config to plugin builder
- Consolidate getAutoModeSystemPrompt into getHubModeSystemPrompt
- Update parameterBuilder to use getHubModeSystemPrompt
* ♻️ refactor: move getHubModeSystemPrompt to shared package
- Create @cherrystudio/shared workspace package with exports
- Move getHubModeSystemPrompt and ToolInfo to packages/shared/prompts
- Add @cherrystudio/shared dependency to @cherrystudio/ai-core
- Update promptToolUsePlugin to import from shared package
- Update renderer prompts-code-mode.ts to re-export from shared
- Add toolSetToToolInfoArray converter for type compatibility
* Revert "♻️ refactor: move getHubModeSystemPrompt to shared package"
This reverts commit 894b2fd487.
* Remove duplicate Tool Use Examples header from system prompt
* fix: add handleModeChange call in MCPToolsButton for manual mode activation
* style: update AssistantMCPSettings to use min-height instead of overflow for better layout control
* feat(i18n): add MCP server modes and truncate messages in multiple languages
- Introduced new "mode" options for MCP servers: auto, disabled, and manual with corresponding descriptions and labels.
- Added translations for "base64DataTruncated" and "truncated" messages across various language files.
- Enhanced user experience by providing clearer feedback on data truncation.
* Normalize tool names for search and exec in parser
* Clarify tool usage rules in code mode prompts and examples
* Clarify code execution instructions and update example usage
* refactor: simplify JSDoc description handling by removing unnecessary truncation
* refactor: optimize listAllActiveServerTools method to use Promise.allSettled for improved error handling and performance
---------
Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: kangfenmao <kangfenmao@qq.com>
- Refactored tests in MainTextBlock and ThinkingBlock to utilize the usePreference hook for managing user settings.
- Updated snapshots in DraggableVirtualList test to reflect changes in class names.
- Enhanced export tests to ensure proper handling of markdown formatting and citation footnotes.
- Mocked additional dependencies globally for improved test reliability.
* Revert "feat: optimize minapp cache with LRU (#8160)"
This reverts commit f0043b4be5.
* feat: integrate logger service and enhance logging throughout the application
- Added a new LoggerService to standardize logging across the application.
- Replaced console.error and console.warn calls with logger methods for improved consistency and error tracking.
- Introduced a new IPC channel for logging messages to the main process.
- Updated various components and services to utilize the new logging system, enhancing error handling and debugging capabilities.
* refactor: enhance logging and error handling across various components
- Integrated the LoggerService for consistent logging throughout the application.
- Updated multiple components and services to utilize the new logging system, improving error tracking and debugging capabilities.
- Refactored file handling and error management in several services to enhance reliability and clarity.
- Improved the structure and readability of the codebase by removing redundant checks and simplifying logic.
* chore: update TypeScript configuration and enhance test setup
- Added test mock paths to tsconfig.web.json for improved test coverage.
- Configured Vitest to include a setup file for main tests, ensuring consistent test environment.
- Updated IPC logger context for better clarity in logging.
- Enhanced LoggerService to handle undefined values gracefully.
- Mocked LoggerService globally in renderer tests to streamline testing process.
* refactor: standardize logging across ProxyManager and ReduxService
- Replaced instances of Logger with logger for consistent logging implementation.
- Improved logging clarity in ProxyManager's configureProxy method and ReduxService's state handling.
- Enhanced error logging in ReduxService to align with the new logging system.
* refactor: reorganize LoggerService for improved clarity and consistency
- Moved the definition of SYSTEM_INFO, APP_VERSION, and DEFAULT_LEVEL to enhance code organization.
- Simplified the getIsDev function in the renderer LoggerService for better readability.
- Updated logging conditions to ensure messages are logged correctly based on context.
* docs: add usage instructions for LoggerService and clean up logging code
- Included important usage instructions for LoggerService in both English and Chinese.
- Commented out the console transport in LoggerService to streamline logging.
- Improved logging message formatting in MCPService for clarity.
- Removed redundant logging statements in SelectionService to enhance code cleanliness.
* refactor: update LoggerService documentation paths and enhance logging implementation
- Changed the documentation paths for LoggerService usage instructions to `docs/technical/how-to-use-logger-en.md` and `docs/technical/how-to-use-logger-zh.md`.
- Replaced console logging with the loggerService in various components, including `MCPSettings`, `BlockManager`, and multiple callback files, to ensure consistent logging practices across the application.
- Improved the clarity and context of log messages for better debugging and monitoring.
* docs: emphasize logger usage guidelines in documentation
- Added a note in both English and Chinese documentation to discourage the use of `console.xxx` for logging unless necessary, promoting consistent logging practices across the application.
