# cherry-electron-dev

Adopt this skill: https://proskills.md/skills/other/cherryhq-cherry-studio-agents-skills-cherry-electron-dev

Page: https://proskills.md/skills/other/cherryhq-cherry-studio-agents-skills-cherry-electron-dev
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/cherry-electron-dev/SKILL.md
size: 3340
sha: 9eb7412a0f81a0b0bc54e5f0cd00e4eea7b91242
upstream: https://github.com/cherryhq/cherry-studio/blob/main/.agents/skills/cherry-electron-dev/SKILL.md

```text
---
name: cherry-electron-dev
description: Develop, fix, profile, and test PRs in a tracked Cherry Studio Electron instance. Use for implementation, UI and interaction work, runtime debugging, DevTools inspection, performance analysis, and interactive PR verification with a test report. Reuse a verified workspace instance and manage its lifetime according to the selected workflow.
---

# Cherry Studio Development

## Choose the workflow

- For ongoing implementation, debugging, or profiling in the current checkout,
  follow the development loop below with the `persistent` runtime policy.
- For a bounded PR test, read [PR Testing](references/pr-testing.md) and follow
  that workflow with the `ephemeral` runtime policy. It covers PR checkout,
  interactive tests, reporting, cleanup, and restoration of the original branch.
- For code review without interactive app testing, use `gh-pr-review`.

## Required runtime workflow

Before reading or controlling Electron UI, read
[Electron Instance Management](references/electron-instance.md) and select the
policy for the chosen workflow. Preserve a borrowed instance's existing policy
and ownership.

That reference is the only authority for instance discovery, `instance.json`,
CDP target selection, launching, replacement, shutdown, and troubleshooting.
Do not reproduce those procedures here or substitute generic Electron app
control.

## Development loop

1. State the requested behavior and the evidence that will prove it.
2. Read the relevant code and nearby README files.
3. Verify and reuse the tracked instance through the runtime reference.
4. Reproduce or inspect the current behavior before editing when practical.
5. Capture the smallest useful evidence: UI state, DOM, console/network output,
   main-process logs, persisted state, or performance metrics.
6. Trace the responsible code path and make only the requested change.
7. Keep Electron running. Use HMR for renderer changes and verify in the same
   window.
8. Repeat the same scenario and compare before/after evidence.

Inspect the real window at the relevant size and theme for UI work. Check both
renderer and main-process evidence for renderer failures.

Restart only for a non-reloadable layer, crash, unreliable runtime state, or
startup profiling. Use the reference's exact-instance replacement procedure,
refresh `instance.json`, and keep the replacement running.

Run the narrowest relevant validation and follow current user and repository
instructions for lint, formatting, and tests.

## Performance and DevTools

For lag, jank, high CPU, memory growth, leaks, slow startup, or explicit
DevTools use, read
[Performance Debugging](references/performance-debugging.md).

Store temporary logs, screenshots, and profiles under
`.context/cherry-electron-dev/`. Compare a quiet baseline with the same bounded
scenario before and after a fix. Detach profiling sessions afterward; do not
close the CDP browser, page, or Electron process.

## Development handoff

Leave reused user-owned and healthy agent-launched instances running after the
instruction. Stop one only when the user asks, a required restart is part of
the task, or the instance is unhealthy and blocks progress.

Report the verified PID, whether it remains running, CDP port, tracking file,
evidence paths, reproduction, and verification.
```

## File: .agents/skills/cherry-electron-dev/references/electron-instance.md
size: 8128
sha: fdf124cd030a18c8ade1e0fa5a2172ec135284d9
upstream: https://github.com/cherryhq/cherry-studio/blob/main/.agents/skills/cherry-electron-dev/references/electron-instance.md

````text
# Electron Instance Management

Use this as the single runtime procedure for development and PR testing in
`cherry-electron-dev`.

## Contents

- Session policy and scratch data
- Verify or discover an instance
- Bind CDP to the exact target
- Gracefully replace an instance
- Start and track a debug instance
- Finish or recover
- Troubleshooting

## Session policy and scratch data

Choose the caller's policy before touching Electron:

| Policy | Use | Finish |
| --- | --- | --- |
| `persistent` | Ongoing development | Leave a healthy instance running |
| `ephemeral` | A bounded PR test | Stop only the instance started by this test |

Treat pre-existing processes as user-owned. Preserve `userData`, databases,
caches, and preferences unless the user explicitly requests a reset.

Use `.context/cherry-electron-dev/` for runtime state and artifacts. The
repository ignores this path, and `mkdir -p` creates it in Conductor and
ordinary clones:

```bash
mkdir -p .context/cherry-electron-dev
```

Track the active instance in `.context/cherry-electron-dev/instance.json` with:

- workspace path and Git HEAD at launch
- `persistent` or `ephemeral` policy and `user` or `agent` ownership
- `launch_purpose` (`development`, `pr-test:<number>`, or `external`)
- `workflow_relation` (`started` or `borrowed`)
- Electron PID, runner PID/session, and process group
- CDP and main-process inspector ports
- exact main-window target URL
- development profile suffix
- launch command, log path, and start time

The file is a hint, not proof. Revalidate it before every UI operation.
At the start of a new workflow, an already-running instance is `borrowed` even
when the same agent launched it during an earlier instruction.

## Verify or discover an instance

Reuse the record only when all checks pass:

1. The Electron PID is alive.
2. Its cwd is the exact current workspace.
3. The recorded CDP listener belongs to that PID.
4. `/json/list` contains the recorded Cherry Studio target.
5. When exact checked-out code matters, the launch Git HEAD matches current
   HEAD; otherwise restart instead of relying on HMR for main-process changes.

```bash
lsof -a -p <ELECTRON_PID> -d cwd -Fn
lsof -nP -a -p <ELECTRON_PID> -iTCP:<CDP_PORT> -sTCP:LISTEN
curl -fsS http://127.0.0.1:<CDP_PORT>/json/version | jq .
curl -fsS http://127.0.0.1:<CDP_PORT>/json/list | \
  jq '.[] | {id, type, title, url}'
```

If the record is missing or stale, discover before launching:

```bash
ps -axo pid=,ppid=,pgid=,command= | \
  rg -i 'Cherry Studio|CherryStudio|electron-vite|remote-debugging-port'
lsof -nP -iTCP -sTCP:LISTEN | rg 'Electron|Cherry|:9222|:5173'
lsof -a -p <ELECTRON_PID> -d cwd -Fn
ps -o pid=,ppid=,pgid=,command= -p <PID>,<PARENT_PID>
```

Ignore candidates that cannot be tied to this workspace. A packaged app and
another checkout are not interchangeable. Never infer ownership from an open
port alone.

If a candidate passes every applicable check, adopt it immediately instead of
launching:

1. Attach to its verified CDP endpoint.
2. Write or refresh `instance.json` with its live identity and
   `workflow_relation: borrowed`.
3. Preserve a trustworthy existing policy and ownership. Without a trustworthy
   record, treat a pre-existing process as `user` owned and `persistent`.
4. End the launch path. Start another instance only when no suitable candidate
   exists or replacement is required.

## Bind CDP to the exact target

Use the verified CDP endpoint exclusively. List targets and match URL and
title; never assume target index `0`. The normal main target is titled
`Cherry Studio` and uses:

```text
http://localhost:5173/windows/main/index.html
```

If the dev server selects another port, require the same
`/windows/main/index.html` path and record the exact URL. Re-list after windows
open or close. Do not navigate a target unless navigation is part of the test.

Use Playwright/CDP or optional `agent-browser`. Do not install a global CLI just
for a task, and do not launch another instance because one controller is
unavailable.

Never pass `Electron`, `com.github.Electron`, or a `node_modules` Electron.app
path to Computer Use or another app-control API. Shared Electron identifiers
can launch or select the wrong checkout.

## Gracefully replace an instance

Replace only when current-workspace code or required CDP access is unavailable.
Before replacing a user-owned process, explain why and record its PID, command,
cwd, parent/runner, PGID, and ports.

Send `SIGTERM` to the exact Electron main PID and wait up to eight seconds:

```bash
kill -TERM <ELECTRON_PID>
for _ in $(seq 1 16); do
  kill -0 <ELECTRON_PID> 2>/dev/null || break
  sleep 0.5
done
kill -0 <ELECTRON_PID> 2>/dev/null && echo "still running"
```

If Electron exits but its verified same-workspace runner remains, terminate
that PID separately. Never use broad `pkill`, kill arbitrary port owners, or
signal a process group before inspecting every member.

Do not escalate automatically to `SIGKILL`. Report the remaining PID and logs
and ask before forcing a process that may be migrating, backing up, or
preventing quit. Verify the old PID and ports are gone before replacement.

## Start and track a debug instance

Read `package.json` for the current debug command. If its default CDP or
inspector port belongs to an unrelated process, choose free ports and change
only those arguments; do not kill the owner.

Prefer a managed terminal session. With a terminal tool such as
`exec_command`, request a PTY and short initial yield, retain its returned
session ID, and let this command continue:

```bash
pnpm debug 2>&1 | tee .context/cherry-electron-dev/electron.log
```

Do not run that command as an ordinary blocking call. If no managed-session
tool exists, use a recorded background runner:

```bash
nohup pnpm debug >.context/cherry-electron-dev/electron.log 2>&1 &
echo $!
```

Immediately record the returned runner PID. Resolve and record the real
Electron PID and PGID after launch.

Keep the existing development profile for `persistent` work. For an isolated
PR test, set a distinct `CS_DEV_USER_DATA_SUFFIX` and record it.

Wait for the selected CDP endpoint, then identify and record the exact target:

```bash
for _ in $(seq 1 60); do
  curl -fsS http://127.0.0.1:<CDP_PORT>/json/version >/dev/null && break
  sleep 0.5
done
curl -fsS http://127.0.0.1:<CDP_PORT>/json/list | \
  jq '.[] | {id, type, title, url}'
```

Write `instance.json` only after PID, cwd, listener ownership, and target checks
pass. Give a new instance `workflow_relation: started`; never reclassify a
borrowed instance as newly started.

## Finish or recover

For `persistent`, leave healthy user-owned and agent-owned instances running.
For `ephemeral`, stop an instance only when all of these are true:

1. Its verified record has `workflow_relation: started`.
2. Its verified record still says `ephemeral` and `agent` owned.
3. Its PID, cwd, and launch purpose still match the current test.

Leave every borrowed instance running, regardless of whether its existing
ownership is `user` or `agent`.

If an unexpected window or PID appears:

1. Stop UI actions.
2. Identify only the new PID by command and cwd.
3. Gracefully stop that verified unexpected PID.
4. Revalidate the tracked PID, cwd, CDP listener, and target.
5. Resume only through the tracked CDP endpoint.

Never close all Electron processes to recover from a targeting mistake.

## Troubleshooting

| Symptom | Action |
| --- | --- |
| CDP works but the page is missing | Re-list targets and match URL/title; splash, migration, settings, detached tabs, and mini-apps are separate targets. |
| Debug launch exits | Inspect the recorded log for a profile lock, native rebuild, database/startup failure, or port collision; confirm the old PID exited. |
| Splash or migration is stuck | Read startup logs and wait; do not bypass, reset, or force-close without understanding its phase. |
| CDP automation is unavailable | Use logs/source when sufficient. If UI evidence is essential, explain why and use the replacement procedure; never fall back to generic Electron control. |
````

## File: .agents/skills/cherry-electron-dev/references/performance-debugging.md
size: 14873
sha: 85581080e57fde0c77a3dc7e2f78eba794a2f09c
upstream: https://github.com/cherryhq/cherry-studio/blob/main/.agents/skills/cherry-electron-dev/references/performance-debugging.md

````text
# Performance Debugging

Use this reference for Cherry Studio lag, jank, CPU, memory, leak, startup, and
DevTools investigations.

## Contents

- Bind safely and choose a profile
- Quick renderer metrics
- Interaction trace
- Memory and allocation
- Development-runtime overhead
- Node and main-process checks
- Startup analysis
- Interpretation and reporting

## Bind safely and choose a profile

First read [Electron Instance Management](electron-instance.md) and complete
its PID, workspace, CDP, and target checks. Never find or open a development
instance through the macOS application name `Electron`.

Connect Playwright to the recorded CDP port and exact main target:

```js
var { chromium } = await import("playwright")
var browser = await chromium.connectOverCDP("http://127.0.0.1:<CDP_PORT>")
var page = browser
  .contexts()
  .flatMap((context) => context.pages())
  .find((candidate) => candidate.url() === "<MAIN_TARGET_URL>")
if (!page || (await page.title()) !== "Cherry Studio") {
  throw new Error("Bound Cherry Studio main target not found")
}
var cdp = await page.context().newCDPSession(page)
```

Never call `browser.close()`, `page.close()`, or an Electron quit action.
Detach only the profiling `CDPSession`. For visible DevTools, open the selected
target's frontend without replacing the bound session:

```text
http://127.0.0.1:<CDP_PORT><devtoolsFrontendUrl>
```

Choose the smallest profile:

| Question | Profile |
| --- | --- |
| Renderer load or memory level? | Quick metrics |
| Cause of a visible stall? | 5-30 second trace |
| Memory growth after repetition? | Repeated checkpoints |
| Allocation source? | Allocation sampling |
| Main/helper resource use? | Process sampling, then Node inspector |
| Slow startup? | Restart-aware startup analysis |

Collect a quiet idle baseline. Keep action, duration, window size, route, data,
and visible-DevTools state identical between comparisons.

## Quick renderer metrics

```js
await cdp.send("Performance.enable")
var beforeRaw = await cdp.send("Performance.getMetrics")
var before = Object.fromEntries(
  beforeRaw.metrics.map(({ name, value }) => [name, value])
)
// Run one bounded scenario.
var afterRaw = await cdp.send("Performance.getMetrics")
var after = Object.fromEntries(
  afterRaw.metrics.map(({ name, value }) => [name, value])
)
```

Compare deltas for cumulative counters: `TaskDuration`, `ScriptDuration`,
`LayoutDuration`, `LayoutCount`, `RecalcStyleDuration`, `RecalcStyleCount`, and
`V8CompileDuration`. Treat `JSHeapUsedSize`, `JSHeapTotalSize`, `Nodes`,
`Documents`, `Frames`, and `JSEventListeners` as point-in-time gauges.

Approximate renderer main-thread utilization for a window of
`elapsedSeconds`:

```text
100 * delta(TaskDuration) / elapsedSeconds
```

This is orientation, not complete CPU usage. Repeat identical scenarios and
compare medians when differences are small.

## Interaction trace

Trace one reproducible action for 5-30 seconds:

```js
var traceDone = new Promise((resolve) =>
  cdp.once("Tracing.tracingComplete", resolve)
)
await cdp.send("Tracing.start", {
  categories: [
    "devtools.timeline",
    "v8",
    "blink.user_timing",
    "disabled-by-default-devtools.timeline"
  ].join(","),
  transferMode: "ReturnAsStream"
})
// Perform the action.
await cdp.send("Tracing.end")
var { stream } = await traceDone
var chunks = []
while (true) {
  var part = await cdp.send("IO.read", { handle: stream })
  chunks.push(Buffer.from(part.data, part.base64Encoded ? "base64" : "utf8"))
  if (part.eof) break
}
await cdp.send("IO.close", { handle: stream })
var fs = await import("node:fs/promises")
await fs.writeFile("<TRACE_PATH>.json", Buffer.concat(chunks))
```

Correlate long tasks with script stacks, layout, paint, GC, and user timing.
Keep raw traces under `.context`; they may contain private UI content or URLs.

## Memory and allocation

For leak suspicion, record heap/nodes/documents/listeners at idle, repeat the
same action a fixed number of times, return to the same idle state, and record
again across multiple cycles. One larger heap value is not proof; V8 may defer
GC. Do not force GC unless a post-GC comparison is explicitly needed.

Triangulate renderer memory instead of relying on one number:

- OS RSS or process footprint includes V8, native allocations, graphics, and
  diagnostic buffers.
- `JSHeapUsedSize` covers only the live V8 heap.
- `Nodes`, `Documents`, `Frames`, and `JSEventListeners` expose retained UI
  structures but not native or performance-entry storage.

Large OS growth with a stable JS heap and stable DOM gauges is not, by itself,
an application heap leak. Check development-runtime instrumentation before
changing product code.

For bounded allocation attribution:

```js
await cdp.send("HeapProfiler.enable")
await cdp.send("HeapProfiler.startSampling", { samplingInterval: 32768 })
// Perform one bounded scenario.
var { profile } = await cdp.send("HeapProfiler.stopSampling")
var fs = await import("node:fs/promises")
await fs.writeFile("<PROFILE_PATH>.json", JSON.stringify(profile))
```

Use a full heap snapshot only when sampling and gauges are insufficient. Warn
first: it can pause the renderer, be large, and contain private data.

## Development-runtime overhead

Development measurements are useful for relative comparisons, but their
absolute memory and CPU are not a production baseline. HMR, source maps,
DevTools, Strict Mode, and framework instrumentation can add or retain work.
Keep visible-DevTools state identical across samples and identify the retaining
system before attributing growth to Cherry Studio.

React 19 development builds emit component Performance Tracks through User
Timing. When a changing prop contains a growing HTML or text string, React can
serialize both previous and current prop values into
`PerformanceMeasure.detail.devtools.properties` on every render. Those entries
remain in the renderer's performance timeline until cleared and can make the
process footprint grow by gigabytes while the JS heap and DOM stay bounded.

Suspect this path when a CPU profile contains `logComponentRender`,
`addValueToProperties`, or `performance.measure`. Inspect entry counts and
string lengths without returning or serializing the retained values:

```js
var timingSummary = await page.evaluate(() => {
  var measures = performance.getEntriesByType("measure")
  var reactMeasures = 0
  var largestProperty = null

  for (var entry of measures) {
    var devtools = entry.detail?.devtools
    if (devtools?.track !== "Components ⚛") continue
    reactMeasures++

    for (var property of devtools.properties ?? []) {
      if (!Array.isArray(property)) continue
      for (var value of property) {
        if (
          typeof value === "string" &&
          value.length > (largestProperty?.length ?? 0)
        ) {
          largestProperty = { component: entry.name, length: value.length }
        }
      }
    }
  }

  return { totalMeasures: measures.length, reactMeasures, largestProperty }
})
```

Do not call `JSON.stringify()` on all performance entries or return their
`detail` objects over CDP; that creates another large copy and contaminates the
measurement.

To distinguish retained diagnostic entries from an application leak:

1. Stop or finish the bounded scenario and capture OS, heap, DOM, and timing
   counts.
2. Save any required trace before cleanup; clearing removes evidence from the
   current User Timing buffer.
3. Run `performance.clearMeasures()` and `performance.clearMarks()` in the
   page.
4. Only for this explicit post-cleanup comparison, run
   `HeapProfiler.collectGarbage` and resample the same gauges.
5. If measures immediately accumulate again, rendering is still active; wait
   for the same idle state and repeat once.

A sharp process-footprint drop after cleanup, with bounded heap and DOM, is
evidence of development instrumentation retention rather than an equivalent
production leak. It is not a product fix: never add content truncation,
memoization, or stream throttling solely to hide this signal. If production
impact matters, verify it independently against the current production bundle
or packaged build and report separately whether that validation was run.

## Node and main-process checks

Identify the busy process before profiling. Sample the tracked process group
several times before, during, and after:

```bash
ps -axo pid=,ppid=,pgid=,%cpu=,rss=,command= | \
  awk '$3 == <TRACKED_PGID>'
```

Separate Electron main, renderer/helper, GPU, Vite, runner, and spawned child
process costs. A Claude Code or MCP child is not part of the Electron main V8
isolate even when it shares the process group; profile the PID that actually
owns the CPU or memory.

### Prefer the built-in main-process diagnostics

For startup, lifecycle, database, DataApi, or IPC latency, first read
[Performance Diagnostics](../../../../docs/dev/references/diagnostics/README.md). Restart the
tracked instance with `CS_DIAGNOSTICS=1` prepended to its existing launch
command only when the restart is justified by the question. The opt-in path
provides:

- a `boot-whenReady.cpuprofile` with 1000 microsecond V8 samples;
- lifecycle service spans and event-loop lag;
- slow better-sqlite3 queries, DataApi requests, and IPC handlers;
- window construction and ready-to-show timings.

Keep the sampling interval at 1000 microseconds. Sort CPU profiles by self time;
wall time assigned to async service initialization can include sibling work and
is not reliable attribution.

Interpret the combined signals:

| Observation | Likely class | Next evidence |
| --- | --- | --- |
| High CPU and profiler self time | Synchronous JavaScript or native call site | Inspect the hottest stack and bound the same input |
| High event-loop lag | Main thread blocked | Correlate the lag window with CPU, DB, IPC, and logs |
| Long wall time, low CPU, low lag | Async I/O, network, timer, or subprocess wait | Trace start/end timestamps and the external dependency |
| `fires=0` during a long startup phase | Microtask chain never yielded | Trust CPU self time, not timer-based lag |
| Slow better-sqlite3 query plus lag | Synchronous database work | Inspect SQL, row count, query plan, and transaction scope |

### Profile steady-state Node work

For runtime work outside startup, verify that the recorded Node inspector port,
normally `9229`, belongs to the exact Electron main PID. Inspect
`http://127.0.0.1:<INSPECTOR_PORT>/json/list`, attach to that target, and collect
only a bounded reproduction with `Profiler.enable`,
`Profiler.setSamplingInterval({ interval: 1000 })`, `Profiler.start`, and
`Profiler.stop`. Save the returned profile under
`.context/cherry-electron-dev/` and detach the inspector connection afterward.
Do not confuse the main-process inspector with renderer CDP, normally `9222`.

Do not leave the CPU profiler running while waiting for user input or an
unbounded stream. Sampling has overhead, and an oversized profile is harder to
attribute. Compare the same duration and input, and use source-mapped stacks
from the tracked debug instance.

If the exact main PID has high CPU but the V8 profile does not account for it,
capture a short native sample of that PID on macOS:

```bash
sample <ELECTRON_MAIN_PID> 10 -file \
  .context/cherry-electron-dev/main-native-sample.txt
```

This gap points toward Electron, a native addon, another main-process thread,
or the wrong PID—not automatically toward JavaScript. Keep native samples under
`.context`; stacks and paths may be private.

### Diagnose Node memory growth

At matched idle checkpoints, record both OS RSS/footprint and main-isolate
memory from `process.memoryUsage()` through inspector `Runtime.evaluate`. Return
only numeric fields and aggregate resource types; do not return application
objects or message contents over the inspector channel.

```js
(() => {
  var memory = process.memoryUsage()
  var resources = process.getActiveResourcesInfo?.() ?? []
  var resourcesByType = {}
  for (var type of resources) {
    resourcesByType[type] = (resourcesByType[type] ?? 0) + 1
  }
  return { ...memory, resourcesByType }
})()
```

Use repeated, fixed-size cycles and return to the same idle state before each
sample:

- rising `heapUsed` after comparable post-GC checkpoints suggests retained JS
  objects;
- rising `external` or `arrayBuffers` suggests Buffer, typed-array, or native
  backing-store retention;
- rising handle/resource counts suggest timers, sockets, pipes, or requests
  that were not released;
- rising OS footprint with bounded isolate fields points toward Electron/native
  allocations, SQLite/native addons, allocator fragmentation, or another
  process—not proof of a JavaScript leak.

Capture the raw checkpoint first. When a post-GC discriminator is necessary,
call `HeapProfiler.collectGarbage` through the same main-process inspector and
resample after a fixed quiet delay. Compare post-GC checkpoints with each
other; do not compare a forced-GC result with an arbitrary pre-GC peak. A heap
drop without an RSS drop can be allocator retention rather than live objects.

Use `HeapProfiler.startSampling` for bounded allocation attribution. Reserve a
full heap snapshot for cases sampling cannot resolve: it pauses the main
process, can be very large, and may contain tokens, prompts, paths, or other
private data. Never expose the main inspector beyond loopback, and do not add
permanent diagnostic logging or instrumentation until existing evidence shows
which boundary lacks observability.

## Startup analysis

Startup profiling requires a restart:

1. Explain and record the current instance/scenario.
2. Gracefully stop only the tracked instance.
3. Start the same debug command and profile.
4. Preserve startup logs and timestamps.
5. Measure navigation milestones such as `NavigationStart`,
   `DomContentLoaded`, and `FirstMeaningfulPaint`.
6. Update `instance.json` and keep the replacement running.

Separate native rebuild, main bootstrap, database migration, service startup,
renderer load, and first interactive UI. Do not treat the whole `pnpm debug`
duration as app startup.

## Interpretation and reporting

- Script-heavy `TaskDuration` suggests JavaScript/React work.
- Layout/style deltas suggest DOM measurement or CSS invalidation.
- Repeated long trace tasks identify likely jank sources.
- Heap plus node/listener growth after identical idle cycles suggests a leak.
- Quiet renderer plus high main CPU points to services or IPC.
- High helper/GPU CPU without renderer task growth points to media, canvas,
  GPU, or embedded web content.

Report exact PID/target/route/scenario/duration, baseline and scenario deltas,
artifact paths, strongest evidence, uncertainty, and before/after comparison
for a fix. Keep Electron running after collection unless restart was explicitly
part of the profile.
````

## File: .agents/skills/cherry-electron-dev/references/pr-testing.md
size: 5406
sha: 8607400529e429ff6189bd2d4d9719b36273c680
upstream: https://github.com/cherryhq/cherry-studio/blob/main/.agents/skills/cherry-electron-dev/references/pr-testing.md

````text
# PR Testing

Use this workflow for a bounded PR test within `cherry-electron-dev`. For
ongoing implementation or debugging, follow the skill's development loop.

## Prerequisites and safety

- Require authenticated `gh`, `pnpm`, and installed project dependencies.
- Use Playwright/CDP or optional `agent-browser` for UI control.
- Before touching Electron, read
  [Electron Instance Management](electron-instance.md)
  and select its `ephemeral` policy.
- Treat that reference as the only authority for discovery, target selection,
  launch, replacement, shutdown, tracking, and troubleshooting.
- Never discard local changes. Stop and ask if checkout would overwrite them.
- Show the report before posting it anywhere.

`$ARGUMENTS` may contain a PR number, PR URL, `latest`/`recent`, or nothing.

## Workflow

### 1. Resolve and inspect the PR

If no PR is specified, list recent PRs and ask the user to choose unless they
requested the latest:

```bash
gh pr list --repo CherryHQ/cherry-studio --state open --limit 10 \
  --json number,title,author,createdAt,headRefName,changedFiles
```

Record the current branch for restoration, inspect the PR, then check it out:

```bash
git status --short
git branch --show-current
gh pr view <NUMBER> --json title,body,author,headRefName,headRefOid,files
gh pr checkout <NUMBER>
```

Read the changed files and nearby instructions. Record the exact checked-out
HEAD and verify it matches the resolved PR head.

### 2. Analyze and start the app

Run static analysis while the app starts when both can proceed independently.

Inspect existing CI results with `gh pr checks <NUMBER>`. Follow current
repository instructions for local validation: use explicit affected test file
paths when needed, and do not default to full lint, test, or typecheck suites.
Record which checks ran locally, which ran in CI, and any coverage gaps.

Read the changed code and check:

- blocked or deprecated v1/v2-refactor files
- hardcoded user-visible strings instead of i18n
- `console.log` instead of `loggerService`
- missing types on new public interfaces

For Electron:

1. Use the shared reference to verify existing instances.
2. Reuse only an instance from this workspace whose recorded launch HEAD equals
   the checked-out PR HEAD.
3. When reusing one, mark it borrowed and preserve its existing policy and
   ownership. Never reclassify a persistent instance as ephemeral.
4. Otherwise gracefully replace only the verified same-workspace instance.
5. Launch an `ephemeral`, agent-owned instance with an isolated
   `CS_DEV_USER_DATA_SUFFIX`, such as `PR-<NUMBER>`.
6. Keep its managed terminal/session, PIDs, ports, log, exact target, and
   `pr-test:<NUMBER>` launch purpose in
   `instance.json`.

Do not use broad process or port cleanup.

### 3. Run interactive tests

Bind the controller to the exact target returned by the shared reference.
Never navigate to a guessed root URL or select a target by index.

Build test cases from the PR description and changed files:

1. Capture the initial state.
2. Inspect interactive elements with the available CDP controller.
3. Exercise the changed behavior.
4. Capture the result and verify relevant persisted state.
5. Repeat edge cases justified by the change.

Consider UI rendering, interactions, persistence, light/dark themes, relevant
window sizes, i18n, empty states, and rapid interaction only when in scope.

Store screenshots and the report under `.context/cherry-electron-dev/pr-<NUMBER>/`:

```bash
mkdir -p .context/cherry-electron-dev/pr-<NUMBER>
```

If an isolated profile shows the migration wizard or splash, follow the shared
troubleshooting guidance and startup logs. Do not reset or force-close data.

### 4. Clean up and restore

Perform cleanup and restoration even if testing fails or is blocked, and
report any incomplete cleanup or restoration.

Use the shared `ephemeral` finish procedure. Stop only an instance launched by
this PR-test workflow whose verified record remains `ephemeral`, agent-owned,
and scoped to `pr-test:<NUMBER>`. Leave every borrowed instance running. Do not
stop unrelated workspaces or packaged apps.

Restore the branch recorded before checkout. If it no longer exists, resolve
the repository default branch and report the fallback before switching:

```bash
git checkout <ORIGINAL_BRANCH>
```

### 5. Report

Save `.context/cherry-electron-dev/pr-<NUMBER>/report.md` and show it to the user.
Match the report language to the user's language; the template uses English labels:

```markdown
# PR #<NUMBER> Test Report

**Title**: <title>
**Author**: @<author>
**Branch**: <branch>
**Tested HEAD**: <commit SHA>
**Changed files**: <count>

## Static Analysis

| Check | Result | Notes |
| --- | --- | --- |
| CI checks | ✅/❌/pending | ... |
| Local checks | ✅/❌/not run | <exact commands and scope> |
| Blocked-file check | ✅/⚠️ | ... |
| Logging, i18n, and types | ✅/❌ | ... |

## UI Tests

### <Test Case>

<scenario, evidence, and result>

![screenshot](<filename>.png)

## Findings

<findings or none>

## Runtime and Cleanup

<verified PID, CDP port, tracking file, evidence paths, whether the instance
was started or borrowed, final process state, and restored branch>

## Conclusion

- Total findings: N
- Recommendation: APPROVE / REQUEST_CHANGES / COMMENT
```

Do not post the report or submit a GitHub review unless the user explicitly
asks.
````

## File: README.md
upstream: https://github.com/cherryhq/cherry-studio/blob/main/README.md

```text

<h1 align="center">
  <a href="https://github.com/CherryHQ/cherry-studio/releases">
    <img src="https://github.com/CherryHQ/cherry-studio/blob/main/build/icon.png?raw=true" width="150" height="150" alt="banner" /><br>
  </a>
</h1>

<p align="center">English | <a href="https://cherryai.com">Official Site</a> | <a href="https://cherryai.com/docs/en/">Documentation</a> | <a href="./docs/dev/contrib/development.md">Development</a> | <a href="https://github.com/CherryHQ/cherry-studio/issues">Feedback</a><br></p>

<div align="center">

[![][deepwiki-shield]][deepwiki-link]
[![][twitter-shield]][twitter-link]
[![][discord-shield]][discord-link]
[![][telegram-shield]][telegram-link]

</div>
<div align="center">

[![][github-release-shield]][github-release-link]
[![][github-nightly-shield]][github-nightly-link]
[![][github-contributors-shield]][github-contributors-link]
[![][license-shield]][license-link]
[![][commercial-shield]][commercial-link]
[![][sponsor-shield]][sponsor-link]

</div>

<div align="center">
 <a href="https://hellogithub.com/repository/1605492e1e2a4df3be07abfa4578dd37" target="_blank" style="text-decoration: none"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=1605492e1e2a4df3be07abfa4578dd37" alt="Featured｜HelloGitHub"  width="220" height="55" /></a>
 <a href="https://trendshift.io/repositories/14318" target="_blank" style="text-decoration: none"><img src="https://trendshift.io/api/badge/repositories/14318" alt="CherryHQ%2Fcherry-studio | Trendshift" width="220" height="55" /></a>
 <a href="https://www.producthunt.com/posts/cherry-studio?embed=true&utm_source=badge-featured&utm_medium=badge&utm_souce=badge-cherry&#0045;studio" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=496640&theme=light" alt="Cherry&#0032;Studio - AI&#0032;Chatbots&#0044;&#0032;AI&#0032;Desktop&#0032;Client | Product Hunt" width="220" height="55" /></a>
</div>

# 🍒 Cherry Studio

Cherry Studio is an AI workstation for Windows, macOS, and Linux. Chat with multiple models, work with agents, build knowledge bases, create images, and automate everyday tasks in one place.

**[Download Desktop](https://cherryai.com/download)** · **[Getting Started](https://cherryai.com/docs/en/getting-started/quick-start/)**

📱 **Cherry Studio Mobile is now available for iOS and Android!** [Download](https://cherryai.com/mobile) · [GitHub repository](https://github.com/CherryHQ/cherry-studio-app).

👏 Join [Telegram Group](https://t.me/CherryStudioAI)｜[Discord](https://discord.gg/wez8HtpxqQ) | [QQ Group(575014769)](https://qm.qq.com/q/lo0D4qVZKi)

❤️ Like Cherry Studio? Give it a star 🌟 or [Sponsor](docs/dev/sponsor.md) to support the development!

# 🌠 Screenshots

**Agents — work with files, tools, and multi-step tasks.**

![Cherry Studio agent workspace creating a presentation](.github/images/readme/agent-light-en.webp)

**Conversations — explore ideas with your models and assistants.**

![Cherry Studio conversation displaying a Mermaid chart](.github/images/readme/chat-light-en.webp)

**Model providers — configure services, API keys, and models in one place.**

![Cherry Studio model provider settings in light mode](.github/images/readme/provider-light-en.webp)

**Knowledge bases — organize sources for retrieval and agent workflows.**

![Cherry Studio knowledge base with folders and documents](.github/images/readme/knowledge-light-en.webp)

**Image creation — turn prompts into images and refine your work.**

![Cherry Studio image creation workspace](.github/images/readme/drawing-light-en.webp)

# 🌟 Key Features

## Agents & Automation

- 🤖 Create agents with their own instructions, workspaces, models, and tool permissions.
- 🛠️ Work with files, run commands, and use browser and computer automation tools.
- 🔌 Extend capabilities with Skills and MCP (Model Context Protocol) servers.
- ⏰ Run scheduled tasks and connect agents to messaging platforms through Channels.

## Models & Conversations

- ☁️ Connect OpenAI, Anthropic, Gemini, and other cloud providers, or add custom compatible services.
- 💻 Use local models through Ollama and LM Studio.
- 💬 Customize assistants and compare responses from multiple models in one conversation.
- 📝 Read and share rich responses with Markdown, code highlighting, formulas, Mermaid charts, and conversation exports.

## Knowledge & Documents

- 📚 Build local knowledge bases from files, folders, and web pages, then use them in conversations and agents.
- 📄 Process PDF, Office documents, images, and text, with OCR and document processing options.
- ✍️ Organize ideas in Markdown notes and manage attachments and generated files in the file library.

## Creative & Everyday Tools

- 🎨 Generate and edit images with supported image models.
- 🔤 Translate text and documents, and use quick translation from other apps.
- 🔍 Search the web, read pages, and find content across your conversations and knowledge bases.
- 🧩 Open web-based tools through Mini Apps, or use the API Gateway to connect other applications to your configured models.

## Voice & Workspace

- 🎙️ Dictate messages and listen to responses with speech recognition and text-to-speech options, including local models.
- 🪟 Work across tabs and detached windows, with window pinning, Quick Assistant, and text selection tools.
- 🌈 Customize your workspace with light and dark themes, layouts, and custom CSS.
- 💾 Keep conversation history and knowledge bases on your device, with local and WebDAV backup options.

Model and tool availability depends on your provider, operating system, and configuration. Some features require API credentials, downloaded models, additional dependencies, or system permissions. See the [user documentation](https://cherryai.com/docs/en/) for setup.

# 📝 Roadmap

Follow upcoming work on our [project board](https://github.com/orgs/CherryHQ/projects/7) and [GitHub Issues](https://github.com/CherryHQ/cherry-studio/issues). See [Releases](https://github.com/CherryHQ/cherry-studio/releases) for features and fixes already shipped.

Share ideas and discuss priorities in [GitHub Discussions](https://github.com/CherryHQ/cherry-studio/discussions).

# 🌈 Theme

- Theme Gallery: <https://cherrycss.com>
- Aero Theme: <https://github.com/hakadao/CherryStudio-Aero>
- PaperMaterial Theme: <https://github.com/rainoffallingstar/CherryStudio-PaperMaterial>
- Claude dynamic-style: <https://github.com/bjl101501/CherryStudio-Claudestyle-dynamic>
- Maple Neon Theme: <https://github.com/Cle2ment/maple_neon>

Check each community theme's supported Cherry Studio version before installing. Themes written for v1 need adaptation for the v2 interface.

Contributions of compatible themes are welcome.

# 🤝 Contributing

Contributions of code, bug reports, documentation, translations, product ideas, and community support are welcome. Browse [good first issues](https://github.com/CherryHQ/cherry-studio/labels/good%20first%20issue) to find a place to start.

## Getting Started

1. Read the [Contributing Guide](CONTRIBUTING.md) and [Development Guide](docs/dev/contrib/development.md).
2. Fork the repository and create a focused branch from `main`.
3. Validate your changes, sign and sign off your commits, and open a pull request targeting `main` using the repository template.

See the [Branching Strategy](docs/dev/contrib/branching-strategy.md) for branch and release conventions.

# 🏢 Enterprise Edition

Cherry Studio Enterprise Edition brings centralized model management, shared knowledge bases, employee access controls, and private deployment options to teams and organizations.

Visit the [Enterprise website](https://enterprise.cherryai.com) for current capabilities and deployment information. For purchasing, pricing, or a demo, contact [bd@cherry-ai.com](mailto:bd@cherry-ai.com).

# 🔗 Related Projects

- [Cherry Studio Mobile](https://github.com/CherryHQ/cherry-studio-app): The mobile version of Cherry Studio for iOS and Android.

- [Cherry Studio Web
```
