Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(desktop): let a dev run coexist with an installed release build (#318)

Yaowei Zheng7d8cc5ba2621
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03a27b50..40e61f03 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,6 +20,7 @@ pnpm dev:web # web app (Vite) at 127.0.0.1:7365, /api proxied to 7368
pnpm dev:docs # docs site (Vite) at 127.0.0.1:7367
pnpm dev:landing # landing page (Vite) at 127.0.0.1:7366
pnpm penguin ... # CLI from source; `penguin web` serves at 127.0.0.1:7369
+pnpm desktop # desktop app from source (builds everything first, then Electron)
BASE_PATH=/ pnpm build:site # assemble landing + docs exactly like the Pages deploy
```
@@ -44,10 +45,28 @@ that only re-sync when the package's `build` script runs via pnpm
cache — on the old build; if a running dev web app still serves stale core after a manual
rebuild, delete `packages/web/node_modules/.vite` and restart.
-Dev entry points that touch data (`pnpm dev`, `pnpm dev:server`, `pnpm penguin`) default
-to a separate data root, `~/.penguin/dev-data`, kept apart from the installed CLI/server's
-`~/.penguin/data` — hacking on the repo never mixes state with your real agents. Export
-`PENGUIN_HOME` to point them anywhere else; an explicit value always wins.
+Dev entry points that touch data (`pnpm dev`, `pnpm dev:server`, `pnpm penguin`,
+`pnpm desktop`) default to a separate data root, `~/.penguin/dev-data`, kept apart from
+the installed CLI/server's `~/.penguin/data` — hacking on the repo never mixes state with
+your real agents. Export `PENGUIN_HOME` to point them anywhere else; an explicit value
+always wins. The desktop dev shell isolates one step further: an unpackaged run takes a
+dev-suffixed app identity (`PenguinHarness-Dev`) with its own userData directory,
+single-instance lock, and sticky port, and defaults to `~/.penguin/dev-data` even when
+launched without the env var (`pnpm --dir packages/desktop start`) — so it runs side by
+side with an installed release build, with neither instance seeing the other. Every
+unpackaged launch prints which pair it picked: `[shell] dev instance '<name>' on data
+root <root>`.
+
+Two one-time moves came with that split. A bare `pnpm --dir packages/desktop start` used
+to run on `~/.penguin/data` (the release/CLI root) and now runs on `~/.penguin/dev-data`,
+so sessions made that way are no longer in the window — run it with
+`PENGUIN_HOME=~/.penguin/data` to work against the release root on purpose. And the dev
+shell's userData directory moved with its name, taking the Chromium profile along, so the
+window's origin-scoped preferences (theme, language, layout) and its remembered port
+start fresh once. Note the identity is one fixed name, not one per checkout: two working
+copies both running the desktop shell still share it, and the second launch focuses the
+first one's window instead of opening its own — a distinct `PENGUIN_HOME` does not change
+that, because it moves the data root, not the identity.
Copy `.env.example` to `.env` for model credentials in development.
diff --git a/changelog/unreleased/2026-08-18-desktop-dev-instance.md b/changelog/unreleased/2026-08-18-desktop-dev-instance.md
new file mode 100644
index 00000000..90b6758f
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-desktop-dev-instance.md
@@ -0,0 +1,28 @@
+# Desktop: a dev run coexists with an installed release build
+
+- **Date:** 2026-08-18
+- **Type:** fix
+- **Scope:** `desktop`, `docs`
+- **PR:** [#318](https://github.com/Prism-Shadow/penguin-harness/pull/318)
+- **Issue:** [#292](https://github.com/Prism-Shadow/penguin-harness/issues/292)
+
+[中文版](2026-08-18-desktop-dev-instance.zh.md)
+
+An unpackaged (source) desktop shell — `pnpm desktop`, or `pnpm --dir packages/desktop start` — took a dev-suffixed app identity and its own data root, so hacking on the desktop app stopped colliding with a running installed build.
+
+## The dev instance
+
+- Dev runs set the app name to `PenguinHarness-Dev`, which gives them their own userData directory, and with it their own Chromium profile, `preferred-port` / `server-port` state, Electron single-instance lock and — since Electron derives these from userData — their own `logs`, `sessionData` and `crashDumps` paths. Under the shared lock a dev launch had quit immediately into the running release instance's window, and vice versa; dev runs had also shared, and overwritten the port memory in, the installed app's Chromium profile.
+- The data root defaults to `~/.penguin/dev-data` inside the shell itself when unpackaged, rather than only under the root `pnpm desktop` script: a bare `pnpm --dir packages/desktop start` had found the release install's `server.lock` on `~/.penguin/data` and attached the dev window to the running release server, or spawned its own server over the release's data. An explicit `PENGUIN_HOME` still wins in both forms.
+- Windows dev runs stamp a dev-suffixed AppUserModelID (`com.prismshadow.penguinharness.dev`) instead of claiming the installed app's taskbar and toast identity.
+- Crash and startup-failure dialogs title themselves with `app.name` rather than the hard-coded release name, so a failing dev run is attributable when both instances are up.
+- Every unpackaged launch prints the pair it picked: `[shell] dev instance '<name>' on data root <root>`.
+- Ports needed no new knob: the embedded server kept its `PORT=0` allocator with per-userData stickiness, so the split userData directories give each instance its own stable port. Auto-update and the CLI-install offer already stood down on unpackaged runs.
+
+## Release builds
+
+Release behavior is unchanged — same name, AppUserModelID, userData directory and shared CLI data root. Two unit tests were added to hold that: one pins the release identity to electron-builder.yml's `productName` and `appId`, previously a comment-only contract; the other pins the data-root precedence rule (explicit `PENGUIN_HOME` first, then the CLI root when packaged and the dev root when not), which had lived untestable inside the Electron-importing entry file.
+
+## Compatibility
+
+Contributors take a one-time move, documented in CONTRIBUTING.md and the installation docs. A bare `pnpm --dir packages/desktop start` had run on `~/.penguin/data`, so sessions made that way are not in the dev window — pass `PENGUIN_HOME=~/.penguin/data` to work against the release root deliberately. And because userData moved with the app name, the dev window's origin-scoped preferences and its remembered port start fresh once. The dev identity is one fixed name rather than one per checkout, so two working copies still share an instance lock.
diff --git a/changelog/unreleased/2026-08-18-desktop-dev-instance.zh.md b/changelog/unreleased/2026-08-18-desktop-dev-instance.zh.md
new file mode 100644
index 00000000..012a732f
--- /dev/null
+++ b/changelog/unreleased/2026-08-18-desktop-dev-instance.zh.md
@@ -0,0 +1,28 @@
+# 桌面端:开发运行可与已安装的发行版并存
+
+- **Date:** 2026-08-18
+- **Type:** fix
+- **Scope:** `desktop`, `docs`
+- **PR:** [#318](https://github.com/Prism-Shadow/penguin-harness/pull/318)
+- **Issue:** [#292](https://github.com/Prism-Shadow/penguin-harness/issues/292)
+
+[English](2026-08-18-desktop-dev-instance.md)
+
+未打包(源码)运行的桌面外壳——`pnpm desktop`,或 `pnpm --dir packages/desktop start`——取用带 dev 后缀的应用标识和独立的数据根目录,于是在源码上开发桌面应用不再与正在运行的安装版相撞。
+
+## 开发实例
+
+- 开发运行把应用名设为 `PenguinHarness-Dev`,由此获得独立的 userData 目录,随之而来的还有独立的 Chromium 配置、`preferred-port` / `server-port` 状态、Electron 单实例锁,以及——因为 Electron 的这几个路径都由 userData 推导——独立的 `logs`、`sessionData` 和 `crashDumps`。此前锁是共用的,发行版在跑时启动开发运行会立刻退回到发行版实例的窗口里,反过来也一样;开发运行还共用安装版的 Chromium 配置,并会覆盖其中记住的端口。
+- 未打包时,数据根目录改由外壳自身默认到 `~/.penguin/dev-data`,而不再只由仓库根的 `pnpm desktop` 脚本设置:此前直接执行 `pnpm --dir packages/desktop start`,会在 `~/.penguin/data` 上发现安装版的 `server.lock`,把开发窗口挂到正在运行的发行版服务端上;发行版没在跑时,则会在发行版的数据上另起一个服务端。两种形式下显式的 `PENGUIN_HOME` 仍然优先。
+- Windows 上的开发运行会打上带 dev 后缀的 AppUserModelID(`com.prismshadow.penguinharness.dev`),不再占用安装版在任务栏和通知上的标识。
+- 崩溃与启动失败对话框改用 `app.name` 作标题,不再写死发行版名称,这样两个实例同时开着时,出问题的是哪一次运行仍然认得出来。
+- 每次未打包启动都会打印它选中的这一组:`[shell] dev instance '<name>' on data root <root>`。
+- 端口不需要新开关:内嵌服务端保持 `PORT=0` 分配、按 userData 记忆的做法,userData 目录一分开,各实例自然各有一个稳定端口。自动更新和 CLI 安装提示在未打包运行下本就不会出现。
+
+## 发行版构建
+
+发行版的行为没有变化——应用名、AppUserModelID、userData 目录,以及与 CLI 共享的数据根目录都照旧。为把这一点钉住,新增了两个单元测试:一个把发行版标识与 electron-builder.yml 中的 `productName`、`appId` 对齐,此前这只是一条写在注释里的约定;另一个固定数据根目录的优先级规则(显式 `PENGUIN_HOME` 最优先,其次是打包时取 CLI 根目录、未打包时取 dev 根目录),这条规则原先嵌在会 import Electron 的入口文件里,没法测。
+
+## 兼容性
+
+贡献者需要做一次性的调整,CONTRIBUTING.md 和安装文档中都已写明。此前直接执行 `pnpm --dir packages/desktop start` 跑在 `~/.penguin/data` 上,因此那样创建的会话不会出现在开发窗口里——若要刻意对着发行版的数据根目录工作,加上 `PENGUIN_HOME=~/.penguin/data`。另外 userData 目录随应用名一并搬了家,开发窗口按 origin 存储的偏好设置和记住的端口会重置一次。dev 标识是一个固定名称,而非每个工作副本一个,因此两份工作副本之间仍然共用同一把实例锁。
diff --git a/packages/desktop/src/app-identity.ts b/packages/desktop/src/app-identity.ts
new file mode 100644
index 00000000..56028f48
--- /dev/null
+++ b/packages/desktop/src/app-identity.ts
@@ -0,0 +1,75 @@
+/**
+ * Per-form app identity — pure, no Electron imports, so it unit-tests under plain
+ * vitest.
+ *
+ * A dev (unpackaged) shell must be able to run while an installed release build is
+ * running (#292). Electron keys everything that must stay per-instance on the app
+ * name: the userData directory holds the Chromium profile and this shell's state
+ * files (server-port, preferred-port, cli-install-offered), and the single-instance
+ * lock is derived from it — under a shared name a second launch does not open a
+ * second app, it quits into the running instance's window. A dev-suffixed name
+ * therefore separates the whole set at once (own profile, own sticky port, own
+ * instance lock) and doubles as the visible marker of which instance is which (the
+ * macOS app menu label follows app.name).
+ *
+ * The Windows AppUserModelID splits the same way: Windows groups taskbar buttons and
+ * routes toast notifications by AUMID, so a dev run must not claim the installed
+ * app's identity. (Dev toasts may not render without an installed shortcut carrying
+ * the dev AUMID — acceptable for a source run; the release value keeps matching what
+ * electron-builder stamps on the installed shortcuts, see electron-builder.yml.)
+ *
+ * Tripwire for whoever edits main.ts's imports: Electron resolves the userData path
+ * once, on the first read, and caches it — so `app.setName()` only relocates anything
+ * while nothing has read it yet. ESM evaluates every import before main.ts's first
+ * statement, which means a module-scope `app.getPath(…)` anywhere in the import graph
+ * would silently pin userData to the package name and undo this whole split. Verified
+ * safe today, including updater.ts's eager `electron-updater` construction; keep any
+ * new `app.getPath` call inside a function.
+ */
+import path from "node:path";
+
+export interface AppIdentity {
+ /** app.setName() value; Electron derives the default userData directory from it. */
+ name: string;
+ /** Windows AppUserModelID. The release value must equal electron-builder.yml's appId. */
+ appUserModelId: string;
+}
+
+/** The identity for this form: release, or dev-suffixed so both can run side by side. */
+export function appIdentity(isPackaged: boolean): AppIdentity {
+ return isPackaged
+ ? { name: "PenguinHarness", appUserModelId: "com.prismshadow.penguinharness" }
+ : { name: "PenguinHarness-Dev", appUserModelId: "com.prismshadow.penguinharness.dev" };
+}
+
+/**
+ * The dev default data root, `~/.penguin/dev-data` — the same convention as the repo's
+ * other dev entry points (CONTRIBUTING.md), kept apart from the release/CLI
+ * `~/.penguin/data`. Without this split a dev shell launched bare (no PENGUIN_HOME)
+ * would find the release install's server.lock on the shared root and attach to the
+ * running RELEASE instance — or, with the release idle, spawn its own server over the
+ * release's data.
+ */
+export function devDataRoot(homedir: string): string {
+ return path.join(homedir, ".penguin", "dev-data");
+}
+
+/**
+ * This form's data root, i.e. the precedence rule itself: an explicit `PENGUIN_HOME`
+ * always wins; without one a release build shares the CLI's root by design, so a desktop
+ * install and the CLI see the same Agents, Sessions and usage, while a dev run takes the
+ * repo's dev root instead of attaching to — or writing into — the release install's data.
+ *
+ * `releaseRoot` stays a thunk (core's `resolveRoot`) so core remains the single
+ * definition point of `~/.penguin/data`; it is only called when there is no explicit
+ * value, which is exactly the case where `resolveRoot()` yields that default. Pure, so
+ * the rule is unit-tested — it cannot be, inline in main.ts, which imports Electron.
+ */
+export function desktopDataRoot(opts: {
+ envHome: string | undefined;
+ isPackaged: boolean;
+ homedir: string;
+ releaseRoot: () => string;
+}): string {
+ return opts.envHome ?? (opts.isPackaged ? opts.releaseRoot() : devDataRoot(opts.homedir));
+}
diff --git a/packages/desktop/src/main.ts b/packages/desktop/src/main.ts
index fd44e4cc..4b05749a 100644
--- a/packages/desktop/src/main.ts
+++ b/packages/desktop/src/main.ts
@@ -19,14 +19,20 @@
* Attach mode: when a live server (e.g. `penguin web`) already owns the data root, the
* window loads that instance instead — normal login page, deliberate degradation.
*
+ * Dev isolation: an unpackaged run takes a dev-suffixed identity (own userData, and with
+ * it the single-instance lock and sticky port) and defaults to the ~/.penguin/dev-data
+ * root, so it runs beside an installed release build (see app-identity.ts).
+ *
* Smoke hook (PENGUIN_DESKTOP_SMOKE=1): after the first load settles, print a
* `DESKTOP-SMOKE-RESULT {json}` line (+ screenshot when PENGUIN_DESKTOP_SMOKE_SHOT is
* set) and quit through the regular quit path, exercising the graceful server stop.
*/
+import os from "node:os";
import path from "node:path";
import { app, BrowserWindow, dialog, shell } from "electron";
import { resolveRoot } from "@prismshadow/penguin-core";
import { liveServerLock } from "@prismshadow/penguin-server/lock";
+import { appIdentity, desktopDataRoot } from "./app-identity.js";
import { resolveWindowIcon } from "./app-icon.js";
import { installCliCommand, maybeOfferCliInstall, currentCliInstallKind } from "./cli-install.js";
import { installAppMenu } from "./menu.js";
@@ -41,11 +47,17 @@ import {
restartDelayMs,
} from "./util.js";
-app.setName("PenguinHarness");
+// Identity first: the name decides the userData directory, which also keys the
+// single-instance lock requested below — a dev (unpackaged) run takes a dev-suffixed
+// identity so it runs beside an installed release build instead of quitting into its
+// window (#292; see app-identity.ts).
+const identity = appIdentity(app.isPackaged);
+app.setName(identity.name);
// Windows toasts (the web app's task-completion notifications) need the AppUserModelID
-// of the installed shortcuts; electron-builder stamps them with the appId. Keep in sync
-// with electron-builder.yml.
-if (process.platform === "win32") app.setAppUserModelId("com.prismshadow.penguinharness");
+// of the installed shortcuts; electron-builder stamps them with the appId. Keep the
+// release value in sync with electron-builder.yml. Dev runs stamp the dev-suffixed id
+// so their taskbar/toast identity never claims the installed app's.
+if (process.platform === "win32") app.setAppUserModelId(identity.appUserModelId);
let win: BrowserWindow | null = null;
let server: EmbeddedServer | null = null;
@@ -55,9 +67,11 @@ let quitting = false;
let stopPromise: Promise<void> | null = null;
let restartAttempts = 0;
+// app.name, not a literal: a dev run raises this box while the installed build may be
+// running beside it, and a dialog titled "PenguinHarness" cannot be attributed to either.
function fatal(context: string, err: unknown): void {
const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
- dialog.showErrorBox("PenguinHarness", `${context}\n\n${detail}`);
+ dialog.showErrorBox(app.name, `${context}\n\n${detail}`);
app.exit(1);
}
@@ -177,7 +191,17 @@ async function handleServerExit(dataRoot: string, code: number): Promise<void> {
}
async function boot(): Promise<void> {
- const dataRoot = process.env.PENGUIN_HOME ?? resolveRoot();
+ // Explicit PENGUIN_HOME wins; otherwise a release build shares the CLI's data root and
+ // a dev run takes the repo's dev root (the rule, and why, live in app-identity.ts).
+ const dataRoot = desktopDataRoot({
+ envHome: process.env.PENGUIN_HOME,
+ isPackaged: app.isPackaged,
+ homedir: os.homedir(),
+ releaseRoot: resolveRoot,
+ });
+ if (!app.isPackaged) {
+ process.stdout.write(`[shell] dev instance '${app.name}' on data root ${dataRoot}\n`);
+ }
const existing = await liveServerLock(dataRoot);
if (existing !== null) {
// Attach mode: the one-shot token only works against a server this shell spawned,
@@ -235,7 +259,7 @@ if (!app.requestSingleInstanceLock()) {
// First launch only: offer the 'penguin' command once; the menu entry remains.
// Skipped in smoke mode — a modal dialog would hang the automated run.
if (process.env.PENGUIN_DESKTOP_SMOKE !== "1") await maybeOfferCliInstall(win);
- })().catch((err) => fatal("PenguinHarness failed to start.", err)),
+ })().catch((err) => fatal(`${app.name} failed to start.`, err)),
);
}
diff --git a/packages/desktop/test/app-identity.test.ts b/packages/desktop/test/app-identity.test.ts
new file mode 100644
index 00000000..7583e3a8
--- /dev/null
+++ b/packages/desktop/test/app-identity.test.ts
@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { appIdentity, desktopDataRoot, devDataRoot } from "../src/app-identity.js";
+
+const builderConfig = fs.readFileSync(
+ fileURLToPath(new URL("../electron-builder.yml", import.meta.url)),
+ "utf8",
+);
+
+/** A top-level scalar from electron-builder.yml (line-based; the config keeps them plain). */
+function builderValue(key: string): string {
+ const m = new RegExp(`^${key}:\\s*(\\S+)\\s*$`, "m").exec(builderConfig);
+ if (!m) throw new Error(`electron-builder.yml has no top-level '${key}'`);
+ return m[1]!;
+}
+
+describe("appIdentity", () => {
+ it("release identity matches what electron-builder stamps on installed builds", () => {
+ // The AppUserModelID must equal the appId electron-builder writes into the installed
+ // shortcuts (Windows toast routing), and the name must equal productName. This test
+ // is the sync the main.ts comment used to only ask for.
+ expect(appIdentity(true)).toEqual({
+ name: builderValue("productName"),
+ appUserModelId: builderValue("appId"),
+ });
+ });
+
+ it("dev identity is dev-suffixed so a dev run coexists with a release install", () => {
+ const dev = appIdentity(false);
+ // The name keys the userData directory (Chromium profile, port memory) and the
+ // single-instance lock: sharing it would make a dev launch quit into the release
+ // instance's window.
+ expect(dev.name).not.toBe(appIdentity(true).name);
+ expect(dev.appUserModelId).not.toBe(appIdentity(true).appUserModelId);
+ expect(dev).toEqual({
+ name: "PenguinHarness-Dev",
+ appUserModelId: "com.prismshadow.penguinharness.dev",
+ });
+ });
+});
+
+describe("devDataRoot", () => {
+ it("is ~/.penguin/dev-data, apart from the release/CLI ~/.penguin/data", () => {
+ expect(devDataRoot("/home/dev")).toBe(path.join("/home/dev", ".penguin", "dev-data"));
+ expect(devDataRoot("/home/dev")).not.toBe(path.join("/home/dev", ".penguin", "data"));
+ });
+});
+
+/**
+ * The precedence rule #292 turns on. These pin the RULE, not the constants: flipping the
+ * packaged branch, dropping the PENGUIN_HOME precedence, or letting either form fall into
+ * the other's root has to fail here.
+ */
+describe("desktopDataRoot", () => {
+ const releaseRoot = path.join("/home/dev", ".penguin", "data");
+ const devRoot = path.join("/home/dev", ".penguin", "dev-data");
+ /** Stands in for core's resolveRoot, and records whether the rule consulted it. */
+ function stubRelease(): (() => string) & { calls: number } {
+ const fn = (): string => {
+ fn.calls += 1;
+ return releaseRoot;
+ };
+ fn.calls = 0;
+ return fn;
+ }
+
+ it("an explicit PENGUIN_HOME wins in both forms", () => {
+ for (const isPackaged of [true, false]) {
+ const release = stubRelease();
+ expect(
+ desktopDataRoot({
+ envHome: "/srv/elsewhere",
+ isPackaged,
+ homedir: "/home/dev",
+ releaseRoot: release,
+ }),
+ ).toBe("/srv/elsewhere");
+ // The explicit value short-circuits: core's resolver is never consulted.
+ expect(release.calls).toBe(0);
+ }
+ });
+
+ it("a packaged build with no PENGUIN_HOME shares the CLI's root via core's resolver", () => {
+ const release = stubRelease();
+ expect(
+ desktopDataRoot({
+ envHome: undefined,
+ isPackaged: true,
+ homedir: "/home/dev",
+ releaseRoot: release,
+ }),
+ ).toBe(releaseRoot);
+ // Delegated rather than re-derived, so ~/.penguin/data keeps one definition point.
+ expect(release.calls).toBe(1);
+ });
+
+ it("an unpackaged run with no PENGUIN_HOME takes the dev root, never the release one", () => {
+ const release = stubRelease();
+ const root = desktopDataRoot({
+ envHome: undefined,
+ isPackaged: false,
+ homedir: "/home/dev",
+ releaseRoot: release,
+ });
+ expect(root).toBe(devRoot);
+ // The #292 regression guard: a bare dev launch must not land on the release install's
+ // data root, where it would attach to the running release server via its server.lock.
+ expect(root).not.toBe(releaseRoot);
+ expect(release.calls).toBe(0);
+ });
+});
diff --git a/packages/docs/content/quickstart-cli.en.md b/packages/docs/content/quickstart-cli.en.md
index 583ca822..4a13e427 100644
--- a/packages/docs/content/quickstart-cli.en.md
+++ b/packages/docs/content/quickstart-cli.en.md
@@ -120,7 +120,7 @@ cd penguin-harness
pnpm install && pnpm build
```
-After the build, run `pnpm penguin <args>` inside the repo as the dev runner, or use the globally linked `penguin` command. Dev entry points (`pnpm penguin`, `pnpm dev`) default to a separate data root `~/.penguin/dev-data`, while the linked/installed `penguin` keeps `~/.penguin/data`; export `PENGUIN_HOME` to override.
+After the build, run `pnpm penguin <args>` inside the repo as the dev runner, or use the globally linked `penguin` command. Dev entry points (`pnpm penguin`, `pnpm dev`, `pnpm desktop`) default to a separate data root `~/.penguin/dev-data`, while the linked/installed `penguin` keeps `~/.penguin/data`; export `PENGUIN_HOME` to override. The desktop dev run also uses its own app identity (`PenguinHarness-Dev`), so it can run alongside an installed desktop build without conflicts.
### Install location and options
diff --git a/packages/docs/content/quickstart-cli.zh.md b/packages/docs/content/quickstart-cli.zh.md
index cf33c94d..b0087adf 100644
--- a/packages/docs/content/quickstart-cli.zh.md
+++ b/packages/docs/content/quickstart-cli.zh.md
@@ -120,7 +120,7 @@ cd penguin-harness
pnpm install && pnpm build
```
-构建完成后,在仓库内用 `pnpm penguin <args>` 作为开发入口运行,或使用全局链接的 `penguin` 命令。开发入口(`pnpm penguin`、`pnpm dev`)默认使用独立数据根目录 `~/.penguin/dev-data`,全局链接或安装的 `penguin` 仍使用 `~/.penguin/data`;可通过环境变量 `PENGUIN_HOME` 覆盖。
+构建完成后,在仓库内用 `pnpm penguin <args>` 作为开发入口运行,或使用全局链接的 `penguin` 命令。开发入口(`pnpm penguin`、`pnpm dev`、`pnpm desktop`)默认使用独立数据根目录 `~/.penguin/dev-data`,全局链接或安装的 `penguin` 仍使用 `~/.penguin/data`;可通过环境变量 `PENGUIN_HOME` 覆盖。桌面开发运行还会使用独立的应用标识(`PenguinHarness-Dev`),因此可以与已安装的桌面版同时运行、互不冲突。
### 安装位置与选项