leduo-patrol 2.0.1 → 2.2.3

package/README.md

@@ -1,6 +1,10 @@
 # 乐多汪汪队 / leduo-patrol
 
-一个部署在服务器上的 Web 控制台，用来通过 ACP 驱动 Claude Code，并在浏览器里接收执行流、工具调用和权限确认。
+一个部署在服务器上的 Web 控制台，可在浏览器里用两种方式连接 Claude Code：
+- `CLI`：直接内嵌 Claude Code 终端
+- `ACP`：结构化时间线 / 权限 / 提问 / 图片输入视图
+
+两种引擎可在同一会话内切换，并共用同一个 Claude `sessionId`。
 
 ## Showcase
 
@@ -83,7 +87,10 @@
 - **目录浏览**：创建会话时可在允许根目录范围内浏览子目录，安全限制越权访问
 
 ### 工具与集成
-- **内置终端**：下方可展开终端抽屉，通过 xterm.js 提供完整 PTY 终端体验（需服务端开启 `LEDUO_ENABLE_SHELL=true`）
+- **双引擎会话**：同一 workspace 会话可在 `CLI` 和 `ACP` 之间切换；切换时复用 Claude `sessionId`
+- **CLI 终端**：主视图可直接运行 Claude Code 原生终端
+- **ACP 结构化视图**：支持时间线、权限确认、AskUserQuestion、多模态图片输入
+- **内置 Shell**：下方可展开终端抽屉，通过 xterm.js 提供完整 PTY shell；服务端默认开启，可通过 `LEDUO_ENABLE_SHELL=false` 显式关闭
 
 ### 界面与可访问性
 - **访问 Key 认证**：所有请求（HTTP / WebSocket）均需携带 key；浏览器检测到无效 key 时展示输入页
@@ -117,6 +124,7 @@ npm run dev:local
   - `local`：监听 `127.0.0.1`，仅本机可访问
 - 可通过命令行参数 `--mode=local|server` 或环境变量 `LEDUO_PATROL_BIND_MODE` 指定，命令行参数优先级更高
 - 若未显式指定，启动时会在终端提示选择模式；并可选择记住到 `~/.leduo-patrol/launch-preferences.json`，后续自动复用
+- 若未设置 `LEDUO_PATROL_ACCESS_KEY`，启动时会提示选择“手动输入自定义 key”或“随机生成 key”，并可选择是否记住到 `~/.leduo-patrol/launch-preferences.json`
 
 - 前端开发服务运行在自动探测到的可访问内网 IP（优先 `bond* / eth* / ens* / enp*` 网卡）上
 - 后端服务运行在 `PORT`（默认 `3001`，端口冲突时会自动递增寻找可用端口）
@@ -150,16 +158,18 @@ LEDUO_PATROL_APP_NAME=乐多汪汪队
 LEDUO_PATROL_WORKSPACE_PATH=/absolute/workspace/path
 LEDUO_PATROL_ALLOWED_ROOTS=/absolute/workspace/path,/another/allowed/root
 LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude
+LEDUO_PATROL_AGENT_BIN=/absolute/path/to/claude-code-acp
 LEDUO_PATROL_SHELL=/absolute/path/to/zsh
 ANTHROPIC_API_KEY=sk-...
 LEDUO_PATROL_ACCESS_KEY=your-fixed-key
-LEDUO_ENABLE_SHELL=true
+LEDUO_ENABLE_SHELL=false
 ```
 
 如果设置了 `LEDUO_PATROL_ALLOWED_ROOTS`，网页中只能连接这些根目录之下的路径；未设置时默认只允许启动命令所在目录。
 如果未设置 `LEDUO_PATROL_WORKSPACE_PATH`，默认工作目录为启动命令所在目录（`process.cwd()`），并在启动日志中提示如何通过环境变量修改。
 如果未设置 `LEDUO_PATROL_ALLOWED_ROOTS`，默认允许根目录同样为启动命令所在目录，并会在启动日志中提示可配置项。
 如果发布安装后的内嵌终端无法启动，可通过 `LEDUO_PATROL_SHELL` 显式指定 shell 路径；例如 macOS 上常见的 `/bin/zsh`。
+如果 ACP agent 不在默认安装位置，可通过 `LEDUO_PATROL_AGENT_BIN` 显式指定 `claude-code-acp` 可执行文件。
 
 ## 状态持久化
 
@@ -177,7 +187,12 @@ LEDUO_ENABLE_SHELL=true
 
 ## 访问校验 Key
 
-服务启动时会自动生成一次性访问 key，并在控制台打印可直接打开的地址。
+服务启动时会优先按以下顺序确定访问 key，并在控制台打印可直接打开的地址：
+
+- `--access-key your-key`
+- `LEDUO_PATROL_ACCESS_KEY`
+- 已记住在 `~/.leduo-patrol/launch-preferences.json` 的 key
+- 若以上都没有：启动时交互选择“手动输入”或“随机生成”
 
 - 开发模式（`npm run dev`）下，`Access URL` 默认指向 Web 端口（默认 `5173`）。
 - 生产模式（`npm start`）下，Web 由同一个 Express 服务静态托管，因此不会出现独立的 Web 监听端口；`Access URL` 会指向 server 端口。若未找到打包后的 `dist/web` 资源，服务会给出错误提示页与启动日志提示。
@@ -193,6 +208,14 @@ LEDUO_PATROL_ACCESS_KEY=your-fixed-key
 LEDUO_PATROL_CLAUDE_BIN=/absolute/path/to/claude
 ```
 
+也可以直接通过命令行传入：
+
+```bash
+npm run dev:server -- --access-key your-fixed-key
+# 或生产模式
+npm start -- --access-key your-fixed-key
+```
+
 ## 已知限制
 
 - 当前只实现了 Claude Code

package/dist/server/__tests__/access-key-prompt.test.js

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { resolveAccessKey, accessKeyPromptTestables } from "../access-key-prompt.js";
+const NON_TTY_STREAM = {
+    isTTY: false,
+};
+const SILENT_STDOUT = {
+    isTTY: true,
+    write: () => true,
+};
+test("access key prompt normalizes values", () => {
+    assert.equal(accessKeyPromptTestables.normalizeAccessKey("  abc  "), "abc");
+    assert.equal(accessKeyPromptTestables.normalizeAccessKey(""), "");
+    assert.equal(accessKeyPromptTestables.normalizeAccessKey(undefined), "");
+});
+test("resolveAccessKey prefers argv over env and remembered key", async () => {
+    const result = await resolveAccessKey({
+        argv: ["--access-key", "cli-key"],
+        envKey: "env-key",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "remembered-key",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "cli-key");
+});
+test("resolveAccessKey falls back to env key", async () => {
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "env-key",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "remembered-key",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "env-key");
+});
+test("resolveAccessKey falls back to remembered key", async () => {
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "remembered-key",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "remembered-key");
+});
+test("resolveAccessKey generates a random key when no tty prompt is available", async () => {
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "",
+        stdin: NON_TTY_STREAM,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "",
+        createRandomKey: () => "random-key",
+    });
+    assert.equal(result, "random-key");
+});
+test("resolveAccessKey can save an interactively chosen key", async () => {
+    let savedKey = "";
+    const ttyStream = {
+        isTTY: true,
+    };
+    const result = await resolveAccessKey({
+        argv: [],
+        envKey: "",
+        stdin: ttyStream,
+        stdout: SILENT_STDOUT,
+        loadRememberedKey: async () => "",
+        saveRememberedKey: async (key) => {
+            savedKey = key;
+        },
+        createRandomKey: () => "random-key",
+        promptForAccessKey: async () => "custom-key",
+        promptShouldRememberKey: async () => true,
+    });
+    assert.equal(result, "custom-key");
+    assert.equal(savedKey, "custom-key");
+});

package/dist/server/__tests__/acp-session.test.js

@@ -0,0 +1,92 @@
+import test, { mock } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { ClaudeAcpSession, acpSessionTestables } from "../acp-session.js";
+function makeSession() {
+    return new ClaudeAcpSession({
+        workspacePath: "/tmp/workspace",
+        agentBinPath: "claude-code-acp",
+        claudeBin: "/tmp/custom-claude",
+        onEvent: () => undefined,
+    });
+}
+test("ClaudeAcpSession.resolveWorkspacePath allows path within workspace", () => {
+    const session = makeSession();
+    const resolved = session.resolveWorkspacePath("a/b.txt");
+    assert.equal(resolved, "/tmp/workspace/a/b.txt");
+});
+test("ClaudeAcpSession.resolveWorkspacePath rejects traversal", () => {
+    const session = makeSession();
+    assert.throws(() => session.resolveWorkspacePath("../etc/passwd"), /outside workspace/);
+});
+test("ClaudeAcpSession.resolvePermission rejects unknown request", async () => {
+    const session = makeSession();
+    await assert.rejects(() => session.resolvePermission("missing", "allow"), /not found|already resolved/);
+});
+test("ClaudeAcpSession.answerQuestion resolves pending question", async () => {
+    const session = makeSession();
+    const calls = [];
+    session.pendingQuestions.set("q-1", {
+        resolve: (value) => calls.push(value),
+        reject: () => undefined,
+    });
+    await session.answerQuestion("q-1", "好的");
+    assert.deepEqual(calls[0], { answer: "好的" });
+    assert.equal(session.pendingQuestions.size, 0);
+});
+test("ClaudeAcpSession.handleExtMethod routes leduo/ask_question", async () => {
+    const events = [];
+    const session = new ClaudeAcpSession({
+        workspacePath: "/tmp/workspace",
+        agentBinPath: "claude-code-acp",
+        onEvent: (event) => events.push(event),
+    });
+    const resultPromise = session.handleExtMethod("leduo/ask_question", {
+        question: "选择颜色",
+        options: [{ id: "red", label: "红色" }],
+        allowCustomAnswer: true,
+    });
+    const event = events[0];
+    assert.equal(event.type, "question_requested");
+    await session.answerQuestion(event.payload.questionId, "红色");
+    const result = await resultPromise;
+    assert.deepEqual(result, { answer: "红色" });
+});
+test("ClaudeAcpSession.findRestorableSession requires exact match when preferred id is provided", async () => {
+    const session = makeSession();
+    session.connection = {
+        unstable_listSessions: async () => ({
+            sessions: [{ sessionId: "other-session-id" }],
+        }),
+    };
+    const result = await session.findRestorableSession("missing-session-id");
+    assert.equal(result, null);
+});
+test("ClaudeAcpSession.findRestorableSession falls back to the first session when no preferred id is provided", async () => {
+    const session = makeSession();
+    session.connection = {
+        unstable_listSessions: async () => ({
+            sessions: [{ sessionId: "restorable-session-id" }],
+        }),
+    };
+    const result = await session.findRestorableSession();
+    assert.equal(result, "restorable-session-id");
+});
+test("ClaudeAcpSession.connect rejects gracefully when the ACP agent spawn emits EAGAIN", async (t) => {
+    const fakeChild = new EventEmitter();
+    fakeChild.stdin = new PassThrough();
+    fakeChild.stdout = new PassThrough();
+    fakeChild.stderr = new PassThrough();
+    fakeChild.kill = (() => true);
+    const spawnMock = mock.method(acpSessionTestables, "spawnAgent", () => {
+        queueMicrotask(() => {
+            const error = Object.assign(new Error("resource temporarily unavailable"), { code: "EAGAIN" });
+            fakeChild.emit("error", error);
+        });
+        return fakeChild;
+    });
+    t.after(() => spawnMock.mock.restore());
+    const session = makeSession();
+    await assert.rejects(() => session.connect(), /Failed to start Claude ACP agent.*EAGAIN/);
+});

package/dist/server/__tests__/activity-monitor.test.js

@@ -8,12 +8,24 @@ test("assistant with stop_reason null → running", () => {
         message: { stop_reason: null, content: [{ type: "thinking" }] },
     }), "running");
 });
-test("assistant with stop_reason undefined → running", () => {
+test("assistant with text content and stop_reason undefined → completed", () => {
     assert.equal(determineActivityState({
         type: "assistant",
         message: { content: [{ type: "text" }] },
+    }), "completed");
+});
+test("assistant with thinking content and stop_reason undefined → running", () => {
+    assert.equal(determineActivityState({
+        type: "assistant",
+        message: { content: [{ type: "thinking" }] },
     }), "running");
 });
+test("assistant with tool_use content and stop_reason undefined → pending", () => {
+    assert.equal(determineActivityState({
+        type: "assistant",
+        message: { content: [{ type: "tool_use" }] },
+    }), "pending");
+});
 test("assistant with no message field → running", () => {
     assert.equal(determineActivityState({ type: "assistant" }), "running");
 });

package/dist/server/__tests__/claude-cli-session.test.js

@@ -22,3 +22,20 @@ test("claudeCliSessionTestables.resolveClaudeBin accepts explicit executable pat
 test("claudeCliSessionTestables.resolveClaudeBin throws actionable error when claude is missing", () => {
     assert.throws(() => claudeCliSessionTestables.resolveClaudeBin(undefined, { PATH: "" }), /LEDUO_PATROL_CLAUDE_BIN/);
 });
+test("claudeCliSessionTestables.buildShellWrappedClaudeLaunch uses a shell exec wrapper", () => {
+    const launch = claudeCliSessionTestables.buildShellWrappedClaudeLaunch("/opt/claude/bin/claude", ["--session-id", "session-123"], (candidate) => candidate === "/bin/sh");
+    assert.deepEqual(launch, {
+        command: "/bin/sh",
+        args: ["-c", 'exec "$0" "$@"', "/opt/claude/bin/claude", "--session-id", "session-123"],
+    });
+});
+test("claudeCliSessionTestables.shouldRetryClaudeSpawnWithShell matches posix_spawnp failures", () => {
+    const shouldRetry = claudeCliSessionTestables.shouldRetryClaudeSpawnWithShell(new Error("posix_spawnp failed."));
+    assert.equal(typeof shouldRetry, "boolean");
+    if (process.platform === "win32") {
+        assert.equal(shouldRetry, false);
+    }
+    else {
+        assert.equal(shouldRetry, true);
+    }
+});

package/dist/server/__tests__/pty-runtime.test.js

@@ -0,0 +1,28 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, statSync, writeFileSync, chmodSync } from "node:fs";
+import { ensureExecutableBit } from "../pty-runtime.js";
+test("ensureExecutableBit adds execute permissions when missing", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-pty-runtime-"));
+    const helperPath = path.join(tempDir, "spawn-helper");
+    writeFileSync(helperPath, "#!/bin/sh\n");
+    chmodSync(helperPath, 0o644);
+    const beforeMode = statSync(helperPath).mode & 0o777;
+    const changed = ensureExecutableBit(helperPath);
+    const afterMode = statSync(helperPath).mode & 0o777;
+    assert.equal(beforeMode, 0o644);
+    assert.equal(changed, true);
+    assert.equal(afterMode, 0o755);
+});
+test("ensureExecutableBit is a no-op when execute permissions already exist", () => {
+    const tempDir = mkdtempSync(path.join(os.tmpdir(), "leduo-patrol-pty-runtime-"));
+    const helperPath = path.join(tempDir, "spawn-helper");
+    writeFileSync(helperPath, "#!/bin/sh\n");
+    chmodSync(helperPath, 0o755);
+    const changed = ensureExecutableBit(helperPath);
+    const mode = statSync(helperPath).mode & 0o777;
+    assert.equal(changed, false);
+    assert.equal(mode, 0o755);
+});

package/dist/server/__tests__/session-manager.test.js

@@ -1,7 +1,221 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { sessionManagerTestables } from "../session-manager.js";
+import { SessionManager, sessionManagerTestables } from "../session-manager.js";
+function makeSnapshot(overrides = {}) {
+    return {
+        clientSessionId: "s1",
+        title: "demo",
+        workspacePath: process.cwd(),
+        connectionState: "connected",
+        activityState: "idle",
+        sessionId: "shared-session-id",
+        engine: "cli",
+        switchable: true,
+        updatedAt: new Date().toISOString(),
+        ...overrides,
+    };
+}
+function makeEntry(overrides = {}) {
+    return {
+        snapshot: makeSnapshot(overrides),
+        cliSession: null,
+        cliExitExpected: false,
+        acpSession: null,
+        acpFullTimeline: [],
+        outputBuffer: "",
+        switchInProgress: false,
+    };
+}
+function makeManager(options) {
+    const manager = new SessionManager(options);
+    manager.activityMonitor.watch = () => undefined;
+    manager.activityMonitor.unwatch = () => undefined;
+    return manager;
+}
 test("sessionManagerTestables.formatError handles Error and objects", () => {
     assert.equal(sessionManagerTestables.formatError(new Error("boom")), "boom");
     assert.match(sessionManagerTestables.formatError({ code: 1 }), /"code":1/);
 });
+test("SessionManager.getAvailableEngines exposes ACP only when agent path exists", () => {
+    const cliOnly = makeManager({ allowedRoots: [process.cwd()] });
+    const dual = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    assert.deepEqual(cliOnly.getAvailableEngines(), ["cli"]);
+    assert.deepEqual(dual.getAvailableEngines(), ["cli", "acp"]);
+});
+test("SessionManager.switchEngine keeps the same Claude sessionId", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    const started = [];
+    const stopped = [];
+    const events = [];
+    manager.startEngine = async (entry, resume) => {
+        started.push({ engine: entry.snapshot.engine, resume, sessionId: entry.snapshot.sessionId });
+        entry.snapshot.connectionState = "connected";
+    };
+    manager.stopEngine = async (entry) => {
+        stopped.push(entry.snapshot.engine);
+    };
+    manager.subscribe((event) => events.push(event.type));
+    manager.sessions.set("s1", makeEntry());
+    await manager.switchEngine("s1", "acp");
+    const entry = manager.sessions.get("s1");
+    assert.equal(entry.snapshot.engine, "acp");
+    assert.equal(entry.snapshot.sessionId, "shared-session-id");
+    assert.deepEqual(stopped, ["cli"]);
+    assert.deepEqual(started, [{ engine: "acp", resume: true, sessionId: "shared-session-id" }]);
+    assert.equal(events.at(-1), "session_updated");
+});
+test("SessionManager.switchEngine clears buffered CLI output before starting the target engine", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    manager.sessions.set("s1", {
+        ...makeEntry({ engine: "acp" }),
+        outputBuffer: "old cli output",
+    });
+    manager.startEngine = async (entry, resume) => {
+        assert.equal(entry.outputBuffer, "");
+        assert.equal(resume, true);
+        entry.snapshot.connectionState = "connected";
+    };
+    manager.stopEngine = SessionManager.prototype["stopEngine"].bind(manager);
+    await manager.switchEngine("s1", "cli");
+    const entry = manager.sessions.get("s1");
+    assert.equal(entry.outputBuffer, "");
+});
+test("SessionManager.createSession starts fresh CLI sessions and emits a connected snapshot", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    const started = [];
+    const events = [];
+    manager.resolveRequestedWorkspace = async (requestedWorkspacePath) => requestedWorkspacePath;
+    manager.startEngine = async (entry, resume) => {
+        started.push({ engine: entry.snapshot.engine, resume, sessionId: entry.snapshot.sessionId });
+        entry.snapshot.connectionState = "connected";
+    };
+    manager.subscribe((event) => {
+        if (event.type === "session_registered" || event.type === "session_updated") {
+            events.push(event);
+        }
+    });
+    const snapshot = await manager.createSession("/tmp/fresh-cli-workspace", "fresh-cli", false, "cli");
+    assert.equal(snapshot.engine, "cli");
+    assert.ok(snapshot.sessionId);
+    assert.deepEqual(started, [{ engine: "cli", resume: false, sessionId: snapshot.sessionId }]);
+    assert.deepEqual(events.map((event) => event.type), ["session_registered", "session_updated"]);
+    assert.equal(events[0]?.payload.connectionState, "connecting");
+    assert.equal(events[1]?.payload.connectionState, "connected");
+});
+test("SessionManager.createSession emits an error snapshot when startup fails", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()] });
+    const events = [];
+    manager.resolveRequestedWorkspace = async (requestedWorkspacePath) => requestedWorkspacePath;
+    manager.startEngine = async (entry) => {
+        entry.snapshot.connectionState = "error";
+        throw new Error("boom");
+    };
+    manager.subscribe((event) => {
+        if (event.type === "session_registered" || event.type === "session_updated") {
+            events.push(event);
+        }
+    });
+    await assert.rejects(() => manager.createSession("/tmp/broken-cli-workspace", "broken-cli", false, "cli"), /boom/);
+    assert.deepEqual(events.map((event) => event.type), ["session_registered", "session_updated"]);
+    assert.equal(events[0]?.payload.connectionState, "connecting");
+    assert.equal(events[1]?.payload.connectionState, "error");
+});
+test("SessionManager.switchEngine rejects busy sessions", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    manager.sessions.set("s1", makeEntry({ activityState: "running" }));
+    manager.startEngine = async () => undefined;
+    manager.stopEngine = async () => undefined;
+    await assert.rejects(() => manager.switchEngine("s1", "acp"), /Session is not switchable: 运行中/);
+});
+test("SessionManager.switchEngine rejects pending ACP approvals", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    manager.sessions.set("s1", makeEntry({
+        engine: "acp",
+        acp: {
+            modes: ["default"],
+            defaultModeId: "default",
+            currentModeId: "default",
+            busy: false,
+            timeline: [],
+            historyTotal: 0,
+            historyStart: 0,
+            permissions: [{
+                    clientSessionId: "s1",
+                    requestId: "req-1",
+                    toolCall: { toolCallId: "tool-1", title: "Write" },
+                    options: [{ optionId: "allow", name: "允许", kind: "allow" }],
+                }],
+            questions: [],
+            availableCommands: [],
+        },
+    }));
+    manager.startEngine = async () => undefined;
+    manager.stopEngine = async () => undefined;
+    await assert.rejects(() => manager.switchEngine("s1", "cli"), /Session is not switchable: 待审批/);
+});
+test("SessionManager.switchEngine allows idle ACP sessions despite stale activityState", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    const started = [];
+    const stopped = [];
+    manager.sessions.set("s1", makeEntry({
+        engine: "acp",
+        activityState: "running",
+        acp: {
+            modes: ["default"],
+            defaultModeId: "default",
+            currentModeId: "default",
+            busy: false,
+            timeline: [],
+            historyTotal: 0,
+            historyStart: 0,
+            permissions: [],
+            questions: [],
+            availableCommands: [],
+        },
+    }));
+    manager.startEngine = async (entry, resume) => {
+        started.push({ engine: entry.snapshot.engine, resume });
+        entry.snapshot.connectionState = "connected";
+    };
+    manager.stopEngine = async (entry) => {
+        stopped.push(entry.snapshot.engine);
+    };
+    await manager.switchEngine("s1", "cli");
+    assert.deepEqual(stopped, ["acp"]);
+    assert.deepEqual(started, [{ engine: "cli", resume: true }]);
+});
+test("SessionManager.switchEngine allows ACP sessions after end_turn even if busy flag is stale", async () => {
+    const manager = makeManager({ allowedRoots: [process.cwd()], agentBinPath: "/tmp/acp" });
+    const started = [];
+    const stopped = [];
+    manager.sessions.set("s1", makeEntry({
+        engine: "acp",
+        acp: {
+            modes: ["default"],
+            defaultModeId: "default",
+            currentModeId: "default",
+            busy: true,
+            timeline: [{
+                    id: "done-1",
+                    kind: "system",
+                    title: "本轮完成",
+                    body: "end_turn",
+                }],
+            historyTotal: 1,
+            historyStart: 0,
+            permissions: [],
+            questions: [],
+            availableCommands: [],
+        },
+    }));
+    manager.startEngine = async (entry, resume) => {
+        started.push({ engine: entry.snapshot.engine, resume });
+        entry.snapshot.connectionState = "connected";
+    };
+    manager.stopEngine = async (entry) => {
+        stopped.push(entry.snapshot.engine);
+    };
+    await manager.switchEngine("s1", "cli");
+    assert.deepEqual(stopped, ["acp"]);
+    assert.deepEqual(started, [{ engine: "cli", resume: true }]);
+});

package/dist/server/access-key-prompt.js

@@ -0,0 +1,84 @@
+import readline from "node:readline/promises";
+import { createAccessKey } from "./access-key.js";
+import { loadStartupPreferences, saveStartupPreferences } from "./startup-preferences.js";
+import { readOptionValue } from "./launch-mode.js";
+export async function resolveAccessKey(options = {}) {
+    const argv = options.argv ?? process.argv.slice(2);
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const createRandomKey = options.createRandomKey ?? createAccessKey;
+    const loadRememberedKey = options.loadRememberedKey ?? loadRememberedAccessKey;
+    const saveRememberedKey = options.saveRememberedKey ?? saveRememberedAccessKey;
+    const promptForKey = options.promptForAccessKey ?? promptForAccessKey;
+    const promptShouldRemember = options.promptShouldRememberKey ?? promptShouldRememberKey;
+    const argvKey = normalizeAccessKey(readOptionValue(argv, "--access-key"));
+    if (argvKey) {
+        return argvKey;
+    }
+    const envKey = normalizeAccessKey(options.envKey ?? process.env.LEDUO_PATROL_ACCESS_KEY);
+    if (envKey) {
+        return envKey;
+    }
+    const rememberedKey = normalizeAccessKey(await loadRememberedKey());
+    if (rememberedKey) {
+        return rememberedKey;
+    }
+    const generatedKey = createRandomKey();
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return generatedKey;
+    }
+    const selectedKey = await promptForKey(stdin, stdout, generatedKey);
+    const shouldRemember = await promptShouldRemember(stdin, stdout);
+    if (shouldRemember) {
+        await saveRememberedKey(selectedKey);
+        stdout.write("已记住访问 key，后续启动会自动复用。\n");
+    }
+    return selectedKey;
+}
+async function promptForAccessKey(stdin, stdout, generatedKey) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        stdout.write("\n请选择访问 key 生成方式：\n");
+        stdout.write("  1) 手动输入自定义 key\n");
+        stdout.write("  2) 使用随机生成 key\n");
+        const answer = (await rl.question("输入 1/2，默认 2: ")).trim().toLowerCase();
+        if (answer === "1" || answer === "custom" || answer === "manual") {
+            const customAnswer = (await rl.question("请输入自定义访问 key: ")).trim();
+            const customKey = normalizeAccessKey(customAnswer);
+            if (customKey) {
+                return customKey;
+            }
+            stdout.write("未输入有效 key，已改用随机生成 key。\n");
+        }
+        stdout.write(`本次启动使用随机 key: ${generatedKey}\n`);
+        return generatedKey;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptShouldRememberKey(stdin, stdout) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await rl.question("是否记住此访问 key 用于后续启动？(y/N): ")).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function normalizeAccessKey(raw) {
+    const normalized = raw?.trim() ?? "";
+    return normalized || "";
+}
+async function loadRememberedAccessKey() {
+    return normalizeAccessKey((await loadStartupPreferences()).accessKey);
+}
+async function saveRememberedAccessKey(key) {
+    await saveStartupPreferences({ accessKey: key });
+}
+export const accessKeyPromptTestables = {
+    normalizeAccessKey,
+    loadRememberedAccessKey,
+    saveRememberedAccessKey,
+};