weapp-ide-cli 6.2.0 → 6.4.0

package/dist/index.d.ts

@@ -3,20 +3,42 @@ import { Buffer } from "node:buffer";
 import { OperationLifecycle } from "@weapp-vite/miniprogram-automator/operation";
 import { MiniProgram } from "@weapp-vite/miniprogram-automator";
 import { McpServer } from "@modelcontextprotocol/server";
-//#region src/devtoolsTarget/metadata.d.ts
 interface WechatDevtoolsMetadata {
   version?: string;
   channel?: 'stable' | 'rc' | 'nightly' | 'unknown';
 }
-//#endregion
-//#region src/devtoolsTarget/profile.d.ts
 interface WechatDevtoolsProfileOptions {
   homeDir?: string;
   localAppDataDir?: string;
   platform?: NodeJS.Platform;
 }
-//#endregion
-//#region src/devtoolsTarget/host.d.ts
+type WechatDevtoolsChannel = 'stable' | 'rc' | 'nightly';
+interface ResolvedWechatDevtoolsTarget extends WechatDevtoolsMetadata {
+  cliPath: string;
+  installationId: string;
+  appPath: string;
+  profileDir: string;
+}
+interface WechatDevtoolsSelectionOptions {
+  cliPath?: string;
+  target?: ResolvedWechatDevtoolsTarget;
+  devtoolsChannel?: WechatDevtoolsChannel;
+  devtoolsVersion?: string;
+  requireOfficialLatest?: boolean;
+}
+interface ResolveWechatDevtoolsTargetOptions extends WechatDevtoolsProfileOptions, WechatDevtoolsSelectionOptions {
+  searchRoots?: string[];
+  registryPath?: string;
+}
+interface WechatDevtoolsInstallation {
+  cliPath: string;
+  target?: ResolvedWechatDevtoolsTarget;
+  error?: string;
+}
+/** 产品版本按数字段比较，避免日期版本的字符串排序漂移。 */
+export declare function compareWechatDevtoolsVersions(a: string, b: string): number;
+/** 只扫描已知安装根，不递归遍历磁盘，也不执行候选应用。 */
+export declare function listWechatDevtoolsInstallations(options?: ResolveWechatDevtoolsTargetOptions): Promise<WechatDevtoolsInstallation[]>;
 interface WechatDevtoolsHostInspectionOptions {
   platform?: NodeJS.Platform;
   signal?: AbortSignal;
@@ -26,22 +48,31 @@ interface WechatDevtoolsHostInspectionOptions {
 export declare function assertWechatDevtoolsHost(target: ResolvedWechatDevtoolsTarget, options?: WechatDevtoolsHostInspectionOptions): Promise<void>;
 /** HTTP 与 WebSocket 的显式端口均需由所选安装持有，端口号本身不是宿主身份。 */
 export declare function assertWechatDevtoolsPort(target: ResolvedWechatDevtoolsTarget, port: number, options?: WechatDevtoolsHostInspectionOptions): Promise<void>;
-//#endregion
-//#region src/devtoolsTarget/index.d.ts
-export interface ResolvedWechatDevtoolsTarget extends WechatDevtoolsMetadata {
-  cliPath: string;
-  installationId: string;
-  appPath: string;
-  profileDir: string;
-}
-export interface ResolveWechatDevtoolsTargetOptions extends WechatDevtoolsProfileOptions {
-  cliPath?: string;
-  target?: ResolvedWechatDevtoolsTarget;
-}
-/** 一次解析 CLI、应用身份及配置目录，供本次操作的所有阶段共同使用。 */
+export declare const WECHAT_DEVTOOLS_OFFICIAL_CHANNELS_URL = "https://devtools.wxqcloud.qq.com.cn/WechatWebDev/nightly/versions/config.json";
+/** 官方查询只提供版本证据，默认选择不依赖网络可用性。 */
+export declare function readOfficialWechatDevtoolsVersion(channel?: WechatDevtoolsChannel): Promise<{
+  version: string;
+  source: string;
+  queriedAt: string;
+}>;
+/** 仅显式严格模式要求所选安装匹配官方渠道最新版本。 */
+export declare function assertOfficialWechatDevtoolsVersion(target: ResolvedWechatDevtoolsTarget): Promise<{
+  version: string;
+  source: string;
+  queriedAt: string;
+}>;
+/** 校验安装后登记真实 CLI 路径，不更改默认选择或登录数据。 */
+export declare function registerWechatDevtoolsInstallation(cliPath: string, registryPath?: string): Promise<ResolvedWechatDevtoolsTarget>;
+/** 允许移除已经失效的登记；不会删除应用或用户配置。 */
+export declare function unregisterWechatDevtoolsInstallation(cliPath: string, registryPath?: string): Promise<void>;
+export declare function validateWechatDevtoolsSelection(options: WechatDevtoolsSelectionOptions): void;
+export declare function readWechatDevtoolsSelectionEnvironment(env?: NodeJS.ProcessEnv): WechatDevtoolsSelectionOptions;
+/** 每次操作只解析一次安装，显式选择覆盖继承的配置但不写回全局设置。 */
 export declare function resolveWechatDevtoolsTarget(options?: ResolveWechatDevtoolsTargetOptions): Promise<ResolvedWechatDevtoolsTarget>;
-//#endregion
-//#region src/cli/agentStart.d.ts
+/** 命令的所有异步阶段复用同一安装，彼此并发的调用不会污染环境变量。 */
+export declare function withWechatDevtoolsSelection<T>(options: ResolveWechatDevtoolsTargetOptions, runner: (target: ResolvedWechatDevtoolsTarget) => Promise<T>): Promise<T>;
+/** 读取当前操作固定的安装；没有活动选择时不触发发现或启动。 */
+export declare function getActiveWechatDevtoolsTarget(): ResolvedWechatDevtoolsTarget | undefined;
 export interface StartWechatIdeAgentOptions {
   projectPath: string;
   port: number;
@@ -50,6 +81,8 @@ export interface StartWechatIdeAgentOptions {
   trustProject?: boolean;
   timeout?: number;
   signal?: AbortSignal;
+  /** 预检完成后、命令派发前登记启动意图；钩子开始后取消仍按派发结果未知处理。 */
+  onBeforeDispatch?: () => void | Promise<void>;
   /** 官方回执验证后先登记窗口所有权，再检查取消状态。 */
   onStarted?: (result: StartWechatIdeAgentResult) => void | Promise<void>;
 }
@@ -60,9 +93,7 @@ export interface StartWechatIdeAgentResult {
 }
 /** 使用所选安装的官方 agent start，并保留其窗口复用和端口冲突语义。 */
 export declare function startWechatIdeAgent(options: StartWechatIdeAgentOptions): Promise<StartWechatIdeAgentResult>;
-//#endregion
-//#region src/cli/automator/context.d.ts
-interface AutomatorInstallationOptions extends DevtoolsRuntimeSessionOptions {
+interface AutomatorInstallationOptions extends DevtoolsRuntimeSessionOptions, WechatDevtoolsSelectionOptions {
   target?: ResolvedWechatDevtoolsTarget;
   signal?: AbortSignal;
 }
@@ -70,8 +101,6 @@ interface AutomatorInstallationOptions extends DevtoolsRuntimeSessionOptions {
 export declare function resolveAutomatorSessionOptions<T extends AutomatorInstallationOptions>(options: T): Promise<T & AutomatorInstallationOptions & {
   installationId: string;
 }>;
-//#endregion
-//#region src/cli/automator/errors.d.ts
 /**
  * @description 判断错误是否属于开发者工具服务端口不可用。
  */
@@ -108,8 +137,6 @@ export declare function isAutomatorLoginError(error: unknown): boolean;
  * @description 格式化开发者工具登录失效错误，便于终端展示。
  */
 export declare function formatAutomatorLoginError(error: unknown): string;
-//#endregion
-//#region src/cli/automator.d.ts
 export interface AutomatorOptions extends AutomatorInstallationOptions {
   projectPath: string;
   timeout?: number;
@@ -140,8 +167,6 @@ export declare function persistOpenedAutomatorSession(options: AutomatorOptions
  * @description 只读连接当前项目已打开的自动化会话；失败不证明缓存过期，也不删除其他操作持有的会话记录。
  */
 export declare function connectOpenedAutomator(options: AutomatorOptions): Promise<MiniProgram>;
-//#endregion
-//#region src/cli/automator-argv.d.ts
 export interface ParsedAutomatorArgs {
   cliPath?: string;
   projectPath: string;
@@ -168,12 +193,10 @@ export declare function readBooleanOption(argv: readonly string[], ...optionName
  * @description 删除参数中的指定选项（同时支持 --opt value 与 --opt=value）。
  */
 export declare function removeOption(argv: readonly string[], optionName: string): string[];
-//#endregion
-//#region src/cli/automator-session.d.ts
 type MiniProgramLike = AutomatorMiniProgram;
 type MiniProgramPage = AutomatorPage;
 type MiniProgramElement = AutomatorElement;
-interface AutomatorSessionOptions extends DevtoolsRuntimeSessionOptions {
+interface AutomatorSessionOptions extends DevtoolsRuntimeSessionOptions, WechatDevtoolsSelectionOptions {
   signal?: AbortSignal;
   target?: ResolvedWechatDevtoolsTarget;
 }
@@ -187,8 +210,6 @@ export declare function acquireSharedMiniProgram(options: AutomatorSessionOption
  * @description 统一管理 automator 会话生命周期。
  */
 export declare function withMiniProgram<T>(options: AutomatorSessionOptions, runner: (miniProgram: MiniProgramLike) => Promise<T>): Promise<T>;
-//#endregion
-//#region src/cli/command-catalog.d.ts
 export declare const WECHAT_CLI_COMMAND_NAMES: readonly ["open", "login", "islogin", "preview", "auto-preview", "upload", "build-npm", "auto", "auto-replay", "reset-fileutils", "close", "quit", "cache", "engine", "open-other", "build-ipa", "build-apk", "cloud"];
 export declare const MINIDEV_NAMESPACE_COMMAND_NAMES: readonly ["alipay", "ali", "minidev"];
 export declare const CONFIG_COMMAND_NAME: "config";
@@ -198,8 +219,6 @@ export declare const WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES: string[];
  * @description 判断是否为 weapp-ide-cli 支持的顶层命令。
  */
 export declare function isWeappIdeTopLevelCommand(command: string | undefined): boolean;
-//#endregion
-//#region src/cli/commands.d.ts
 export interface AutomatorCommandOptions extends AutomatorSessionOptions {}
 export interface NavigateOptions extends AutomatorCommandOptions {
   url: string;
@@ -304,8 +323,6 @@ export declare function takeScreenshot(options: ScreenshotOptions): Promise<Scre
  * @description 开关远程调试。
  */
 export declare function remote(options: RemoteOptions): Promise<void>;
-//#endregion
-//#region src/cli/compare.d.ts
 interface CompareOptions extends ScreenshotOptions {
   baselinePath: string;
   currentOutputPath?: string;
@@ -322,15 +339,18 @@ export declare function printCompareHelp(): void;
  * @description 解析 compare 命令参数。
  */
 export declare function parseCompareArgs(argv: string[]): CompareOptions;
-//#endregion
-//#region src/cli/config-command.d.ts
 /**
  * @description 处理 config 子命令。
  */
 export declare function handleConfigCommand(argv: string[]): Promise<void>;
-//#endregion
-//#region src/cli/http.d.ts
-export interface WechatDevtoolsHttpCommandOptions {
+/** 包装参数不会透传官方 CLI，选项值和双横线后的内容保持原样。 */
+export declare function splitWechatDevtoolsSelectionArgs(argv: readonly string[]): {
+  args: string[];
+  selection: WechatDevtoolsSelectionOptions;
+};
+/** 显式选择在任何 helper 或 CLI 回退之前固定，避免入口间选版漂移。 */
+export declare function withWechatDevtoolsSelectionArgs<T>(argv: readonly string[], runner: (args: string[]) => Promise<T>): Promise<T>;
+export interface WechatDevtoolsHttpCommandOptions extends WechatDevtoolsSelectionOptions {
   cliPath?: string;
   target?: ResolvedWechatDevtoolsTarget;
   port?: number;
@@ -374,8 +394,6 @@ export declare const WECHAT_DEVTOOLS_ENGINE_BUILD_STATUSES: {
   readonly NOT_START: "NOT_START";
   readonly OPEN_PROJECT: "OPEN_PROJECT";
 };
-//#endregion
-//#region src/cli/engine.d.ts
 export interface RunWechatIdeEngineBuildByHttpOptions extends WechatDevtoolsHttpCommandOptions {
   onProgress?: (result: PollWechatIdeEngineBuildResult) => void;
   overallTimeoutMs?: number;
@@ -396,8 +414,6 @@ export declare function runWechatIdeEngineBuild(projectPath: string, options?: R
 export declare function prepareAcceptanceProject(projectPath: string, signal: AbortSignal, options?: WechatDevtoolsHttpCommandOptions & {
   runtimeProvider?: 'headless' | 'devtools';
 }): Promise<void | PollWechatIdeEngineBuildResult>;
-//#endregion
-//#region src/cli/forwardConsole.d.ts
 export type ForwardConsoleLogLevel = 'debug' | 'log' | 'info' | 'warn' | 'error';
 export interface ForwardConsoleEvent {
   level: ForwardConsoleLogLevel;
@@ -417,8 +433,6 @@ export interface ForwardConsoleSession {
  * @description 启动小程序控制台日志转发，并保持 automator 会话常驻。
  */
 export declare function startForwardConsole(options: ForwardConsoleOptions): Promise<ForwardConsoleSession>;
-//#endregion
-//#region src/cli/inputCoordinator.d.ts
 export interface SharedInputSessionOptions {
   onData?: (chunk: string | Uint8Array) => void;
   onKeypress?: (str: string, key: {
@@ -443,8 +457,6 @@ export interface ExclusiveKeypressOptions<T> {
 export declare function createSharedInputSession(options: SharedInputSessionOptions): SharedInputSession | undefined;
 export declare function waitForExclusiveKeypress<T>(options: ExclusiveKeypressOptions<T>): Promise<T | 'timeout'>;
 export declare function runWithSuspendedSharedInput<T>(runner: () => Promise<T>): Promise<T>;
-//#endregion
-//#region src/cli/loginQuery.d.ts
 export type WechatIdeLoginQueryResult = {
   status: 'success';
   login: boolean;
@@ -457,20 +469,14 @@ export declare function queryWechatIdeLogin(cliPath: string, options?: {
   timeout?: number;
   signal?: AbortSignal;
 }): Promise<WechatIdeLoginQueryResult>;
-//#endregion
-//#region src/cli/minidev.d.ts
 /**
  * @description 运行支付宝小程序 CLI（minidev）
  */
 export declare function runMinidev(argv: readonly string[]): Promise<void>;
-//#endregion
-//#region src/cli/prompt.d.ts
 /**
  * @description 交互式提示并保存 CLI 路径
  */
 export declare function promptForCliPath(): Promise<string | null>;
-//#endregion
-//#region src/cli/resolver.d.ts
 /**
  * @description 解析 CLI 路径并校验可用性
  */
@@ -478,8 +484,6 @@ export declare function resolveCliPath(): Promise<{
   cliPath: string | null;
   source: ConfigSource;
 }>;
-//#endregion
-//#region src/cli/retry.d.ts
 export interface RetryKeypressOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
@@ -546,18 +550,12 @@ export declare function promptRetryKeypress(options: RetryPromptOptions): Promis
  * @description 统一处理微信开发者工具登录失效场景下的提示与重试交互。
  */
 export declare function promptWechatIdeLoginRetry(options: WechatIdeLoginRetryOptions): Promise<"cancel" | "retry">;
-//#endregion
-//#region src/cli/run.d.ts
 /**
  * @description 基于 cac 注册顶层命令，用于统一识别入口。
  */
 export declare function createCli(): import("cac").CAC;
-/**
- * @description CLI 入口解析与分发。
- */
+/** 在分发前剥离公共选择参数并固定本次安装。 */
 export declare function parse(argv: string[]): Promise<void>;
-//#endregion
-//#region src/cli/run-automator.d.ts
 export declare const AUTOMATOR_COMMAND_NAMES: string[];
 /**
  * @description 判断是否属于 automator 子命令。
@@ -571,9 +569,7 @@ export declare function getAutomatorCommandHelp(command: string): string | undef
  * @description 执行 automator 子命令。
  */
 export declare function runAutomatorCommand(command: string, argv: string[]): Promise<void>;
-//#endregion
-//#region src/cli/run-login.d.ts
-export interface RunWechatCliWithRetryOptions {
+export interface RunWechatCliWithRetryOptions extends WechatDevtoolsSelectionOptions {
   target?: ResolvedWechatDevtoolsTarget;
   silent?: boolean;
   timeout?: number;
@@ -581,8 +577,6 @@ export interface RunWechatCliWithRetryOptions {
 }
 /** 原生 CLI 可能启动或改变共享宿主，完整命令与有限重试共用机器租约。 */
 export declare function runWechatCliWithRetry(cliPath: string, argv: string[], options?: RunWechatCliWithRetryOptions): Promise<void>;
-//#endregion
-//#region src/cli/run-login-executor.d.ts
 export interface RetryableCommandExecutorOptions<TResult, TPromptResult> {
   timeout?: number;
   signal?: AbortSignal;
@@ -598,15 +592,11 @@ export interface RetryableCommandExecutorOptions<TResult, TPromptResult> {
 }
 /** 命令、登录提示和有限重试共用一个 deadline，取消信号由执行边界传入 I/O。 */
 export declare function runRetryableCommand<TResult, TPromptResult>(options: RetryableCommandExecutorOptions<TResult, TPromptResult>): Promise<TResult>;
-//#endregion
-//#region src/cli/run-mcp.d.ts
 export interface McpCommandOptions {
   cliPath?: string;
   workspaceRoot?: string;
 }
 export declare function runMcpCommand(argv: string[]): Promise<void>;
-//#endregion
-//#region src/cli/screenshot.d.ts
 /**
  * @description Print help for screenshot command
  */
@@ -615,32 +605,28 @@ export declare function printScreenshotHelp(): void;
  * @description Parse command line arguments for screenshot command
  */
 export declare function parseScreenshotArgs(argv: string[]): ScreenshotOptions;
-//#endregion
-//#region src/cli/wechat-command-schema.d.ts
 /**
  * @description 在调用官方微信 CLI 前做轻量参数校验。
  */
 export declare function validateWechatCliCommandArgs(argv: readonly string[]): void;
-//#endregion
-//#region src/cli/wechat-commands.d.ts
-export interface LoginWechatIdeOptions {
+export interface LoginWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   qrFormat?: 'base64' | 'image' | 'terminal';
   qrOutput?: string;
   qrSize?: string;
   resultOutput?: string;
 }
-export interface OpenWechatIdeOptions {
+export interface OpenWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   appid?: string;
   extAppid?: string;
   platform?: string;
   projectPath?: string;
   trustProject?: boolean;
 }
-export interface BuildWechatIdeNpmOptions {
+export interface BuildWechatIdeNpmOptions extends WechatDevtoolsSelectionOptions {
   compileType?: string;
   projectPath?: string;
 }
-export interface PreviewWechatIdeOptions {
+export interface PreviewWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   appid?: string;
   compileCondition?: string;
   extAppid?: string;
@@ -650,14 +636,14 @@ export interface PreviewWechatIdeOptions {
   qrOutput?: string;
   qrSize?: string;
 }
-export interface AutoPreviewWechatIdeOptions {
+export interface AutoPreviewWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   appid?: string;
   compileCondition?: string;
   extAppid?: string;
   infoOutput?: string;
   projectPath?: string;
 }
-export interface UploadWechatIdeOptions {
+export interface UploadWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   appid?: string;
   desc: string;
   extAppid?: string;
@@ -665,7 +651,7 @@ export interface UploadWechatIdeOptions {
   projectPath?: string;
   version: string;
 }
-export interface AutoWechatIdeOptions {
+export interface AutoWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   account?: string;
   appid?: string;
   extAppid?: string;
@@ -675,7 +661,7 @@ export interface AutoWechatIdeOptions {
   ticket?: string;
   trustProject?: boolean;
 }
-export interface AutoReplayWechatIdeOptions {
+export interface AutoReplayWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   account?: string;
   appid?: string;
   extAppid?: string;
@@ -687,21 +673,21 @@ export interface AutoReplayWechatIdeOptions {
   ticket?: string;
   trustProject?: boolean;
 }
-export interface OpenWechatIdeOtherProjectOptions {
+export interface OpenWechatIdeOtherProjectOptions extends WechatDevtoolsSelectionOptions {
   projectPath?: string;
 }
-export interface CloseWechatIdeProjectOptions {
+export interface CloseWechatIdeProjectOptions extends WechatDevtoolsSelectionOptions {
   projectPath?: string;
   cliPath?: string;
   target?: ResolvedWechatDevtoolsTarget;
 }
-export interface ClearWechatIdeCacheOptions {
+export interface ClearWechatIdeCacheOptions extends WechatDevtoolsSelectionOptions {
   clean: 'all' | 'auth' | 'compile' | 'file' | 'network' | 'session' | 'storage';
 }
-export interface ResetWechatIdeFileUtilsOptions {
+export interface ResetWechatIdeFileUtilsOptions extends WechatDevtoolsSelectionOptions {
   projectPath: string;
 }
-export interface WechatIdeAutomatorSessionOptions {
+export interface WechatIdeAutomatorSessionOptions extends WechatDevtoolsSelectionOptions {
   port?: number;
   preferOpenedSession?: boolean;
   preserveProjectRoot?: boolean;
@@ -719,7 +705,7 @@ export interface ClearWechatIdeCacheByAutomatorOptions extends WechatIdeAutomato
 export interface SetWechatIdeTicketOptions extends WechatIdeAutomatorSessionOptions {
   ticket: string;
 }
-export interface BuildWechatIdeApkOptions {
+export interface BuildWechatIdeApkOptions extends WechatDevtoolsSelectionOptions {
   desc?: string;
   isUploadResourceBundle?: boolean;
   keyAlias: string;
@@ -731,7 +717,7 @@ export interface BuildWechatIdeApkOptions {
   storePass: string;
   useAab?: boolean;
 }
-export interface BuildWechatIdeIpaOptions {
+export interface BuildWechatIdeIpaOptions extends WechatDevtoolsSelectionOptions {
   certificateName?: string;
   isDistribute: boolean;
   isRemoteBuild?: boolean;
@@ -760,7 +746,7 @@ export declare function loginWechatIde(options?: LoginWechatIdeOptions): Promise
 export declare function isWechatIdeLoggedIn(options?: {
   nonInteractive?: boolean;
   silent?: boolean;
-}): Promise<void>;
+} & WechatDevtoolsSelectionOptions): Promise<void>;
 /**
  * @description 调用微信开发者工具 build-npm 命令。
  */
@@ -792,7 +778,7 @@ export declare function closeWechatIdeProject(options?: CloseWechatIdeProjectOpt
 /**
  * @description 调用微信开发者工具 quit 命令。
  */
-export declare function quitWechatIde(): Promise<void>;
+export declare function quitWechatIde(options?: WechatDevtoolsSelectionOptions): Promise<void>;
 /**
  * @description 调用微信开发者工具 cache 命令。
  */
@@ -800,7 +786,7 @@ export declare function clearWechatIdeCache(options: ClearWechatIdeCacheOptions)
 /**
  * @description 调用微信开发者工具 open-other 命令。
  */
-export declare function openWechatIdeOtherProject(_options?: OpenWechatIdeOtherProjectOptions): Promise<void>;
+export declare function openWechatIdeOtherProject(options?: OpenWechatIdeOtherProjectOptions): Promise<void>;
 /**
  * @description 通过微信开发者工具 HTTP 服务端口重置指定项目的 fileutils 状态。
  */
@@ -841,14 +827,10 @@ export declare function buildWechatIdeApk(options: BuildWechatIdeApkOptions): Pr
  * @description 调用微信开发者工具 build-ipa 命令。
  */
 export declare function buildWechatIdeIpa(options: BuildWechatIdeIpaOptions): Promise<void>;
-//#endregion
-//#region src/cli/wechat-dispatch.d.ts
 /**
  * @description 优先将高频官方命令分发到 weapp-ide-cli 的稳定 helper，实现更清晰的程序化命令层。
  */
 export declare function dispatchWechatCliCommand(argv: string[]): Promise<boolean>;
-//#endregion
-//#region src/cli/wechatDevtoolsRuntimePort.d.ts
 type PortTarget = Pick<ResolvedWechatDevtoolsTarget, 'installationId'>;
 /**
  * @description 标记所选安装检测到的服务端口；无身份的旧调用仅保留在独立兼容槽中。
@@ -858,8 +840,6 @@ export declare function setRuntimeWechatDevtoolsServicePort(port: number | undef
  * @description 只读取所选安装的服务端口，不借用其他安装或无身份的旧记录。
  */
 export declare function getRuntimeWechatDevtoolsServicePort(target?: PortTarget): number | undefined;
-//#endregion
-//#region src/cli/wechatDevtoolsSettings.d.ts
 export interface WechatDevtoolsSecuritySettings {
   enableServicePort: boolean;
   port: number;
@@ -895,8 +875,6 @@ export declare function detectWechatDevtoolsServicePort(options?: DetectWechatDe
  * @description 在启动微信开发者工具前，检测服务端口配置，并按需写入项目信任信息。
  */
 export declare function bootstrapWechatDevtoolsSettings(options?: BootstrapWechatDevtoolsSettingsOptions): Promise<BootstrapWechatDevtoolsSettingsResult>;
-//#endregion
-//#region src/types.d.ts
 /**
  * @description 基础配置
  */
@@ -923,8 +901,6 @@ interface AliasEntry {
   find: string;
   replacement: string;
 }
-//#endregion
-//#region src/config/custom.d.ts
 interface CustomConfigFile {
   cliPath?: string;
   locale?: 'zh' | 'en';
@@ -956,8 +932,6 @@ export declare function removeCustomConfigKey(key: keyof CustomConfigFile): Prom
  * @description 覆盖写入配置内容（会替换原内容）。
  */
 export declare function overwriteCustomConfig(config: CustomConfigFile): Promise<void>;
-//#endregion
-//#region src/config/paths.d.ts
 /**
  * @description 默认自定义配置目录
  */
@@ -966,8 +940,6 @@ export declare const defaultCustomConfigDirPath: string;
  * @description 默认自定义配置文件路径
  */
 export declare const defaultCustomConfigFilePath: string;
-//#endregion
-//#region src/config/resolver.d.ts
 /**
  * @description 解析开发者工具自动预热相关配置的最终生效值。
  */
@@ -986,8 +958,6 @@ export declare function getConfig(): Promise<ResolvedConfig>;
  * @description 获取用户配置的语言偏好。
  */
 export declare function getConfiguredLocale(): Promise<"zh" | "en" | undefined>;
-//#endregion
-//#region src/devtoolsProjectOwnership/types.d.ts
 interface ManagedWechatHostIdentity {
   pid: number;
   executable: string;
@@ -1003,7 +973,7 @@ interface ManagedWechatInstallationExitEvidence {
   installationId: string;
   profileDir: string;
   previous: {
-    state: 'starting' | 'unconfirmed' | 'failed';
+    state: 'starting' | 'unconfirmed' | 'failed' | 'borrowed';
     error?: string;
     updatedAt: string;
     recordSha256: string;
@@ -1060,6 +1030,20 @@ interface ManagedWechatWindowCloseEvidence {
     cursors: ManagedWechatWindowLogCursor[];
   };
 }
+interface ManagedWechatProjectSnapshot {
+  protocol: 'wechat-devtools-project-snapshot-v1';
+  sourceProjectPath: string;
+  token: string;
+  state: 'reserved' | 'ready' | 'removed';
+  directoryIdentity?: {
+    dev: string;
+    ino: string;
+  };
+  dispatchedAt?: string;
+  cleanupStartedAt?: string;
+  removedAt?: string;
+  cleanupError?: string;
+}
 interface ManagedWechatProjectRecord {
   schemaVersion: 1;
   id: string;
@@ -1079,10 +1063,11 @@ interface ManagedWechatProjectRecord {
   closeAcknowledgedAt?: string;
   /** 端口退出不是窗口退出；保存所选 profile 的增量销毁证据供父任务恢复。 */
   windowClose?: ManagedWechatWindowCloseEvidence;
-  releasedReason?: 'borrowed' | 'project-closed' | 'installation-exited';
+  releasedReason?: 'borrowed' | 'project-closed' | 'installation-exited' | 'not-started';
   /** 显式恢复只终结已退出安装的活资源；原启动失败与归属缺口仍保留。 */
   installationExitRecovery?: ManagedWechatInstallationExitEvidence;
   error?: string;
+  snapshot?: ManagedWechatProjectSnapshot;
 }
 interface BeginManagedWechatProjectOptions {
   target: ResolvedWechatDevtoolsTarget;
@@ -1092,10 +1077,15 @@ interface BeginManagedWechatProjectOptions {
   journalPath?: string;
   /** 当前任务根作用域最多持有一个窗口；双项目验收须显式指定两个。 */
   maxOwnedWindows?: 1 | 2;
+  /** 将输入项目的布局快照持久绑定当前任务 owner。 */
+  snapshotProject?: boolean;
 }
 interface ManagedWechatProjectIntent {
   id: string;
   journalPath: string;
+  projectPath: string;
+  prepareSnapshot: (populate: (projectPath: string) => Promise<void>) => Promise<void>;
+  markLaunchDispatched: () => Promise<void>;
   confirm: (result: {
     openedProjectWindow: boolean;
     port: number;
@@ -1107,8 +1097,6 @@ interface CleanupManagedWechatProjectsOptions {
   journalPath?: string;
   scope?: 'process' | 'journal';
 }
-//#endregion
-//#region src/devtoolsProjectOwnership/installationExit/index.d.ts
 export interface RecoverManagedWechatProjectsAfterInstallationExitOptions {
   target: ResolvedWechatDevtoolsTarget;
   recoveryScope: MachineE2ELeaseRecoveryScope;
@@ -1118,18 +1106,17 @@ export interface ManagedWechatInstallationExitRecoveryResult {
 }
 /** 在精确恢复租约中终结已退出安装的未知启动或失败关窗；保留原证据，不补造销毁事件。 */
 export declare function recoverManagedWechatProjectsAfterInstallationExit(options: RecoverManagedWechatProjectsAfterInstallationExitOptions): Promise<ManagedWechatInstallationExitRecoveryResult>;
-//#endregion
-//#region src/devtoolsProjectOwnership/journal/constants.d.ts
 /** 受管项目日志的环境变量名称；基础设施预检可在构建包之前读取。 */
 export declare const MANAGED_PROJECT_JOURNAL_ENV = "WEAPP_IDE_MANAGED_PROJECT_JOURNAL";
 /** 仅供显式受管任务声明双项目窗口验收；不允许无限扩大并行窗口。 */
 export declare const MANAGED_PROJECT_MAX_WINDOWS_ENV = "WEAPP_IDE_MANAGED_PROJECT_MAX_WINDOWS";
-//#endregion
-//#region src/devtoolsProjectOwnership/journal.d.ts
 /** 仅递归当前任务明确传递的 children；不扫描用户缓存，不跟随符号链接。 */
 export declare function readManagedWechatProjectRecords(journalPath?: string): Promise<ManagedWechatProjectRecord[]>;
-//#endregion
-//#region src/devtoolsProjectOwnership/index.d.ts
+/** 窗口已经释放不代表本任务快照也已回收。 */
+export declare function isManagedWechatProjectFullyReleased(record: {
+  state: ManagedWechatProjectRecord['state'];
+  snapshot?: Pick<NonNullable<ManagedWechatProjectRecord['snapshot']>, 'state'>;
+}): boolean;
 /** 窗口销毁与连接断开分别验证；失败保留登记供后续继续观察。 */
 export declare function closeManagedWechatProject(options: {
   journalPath?: string;
@@ -1139,8 +1126,6 @@ export declare function closeManagedWechatProject(options: {
 export declare function beginManagedWechatProject(options: BeginManagedWechatProjectOptions): Promise<ManagedWechatProjectIntent | undefined>;
 /** 父进程可回收已退出工作进程的确认所有权；未知启动结果严格阻止后续任务。 */
 export declare function cleanupManagedWechatProjects(options?: CleanupManagedWechatProjectsOptions): Promise<void>;
-//#endregion
-//#region src/mcp/runtime.d.ts
 export interface StartWeappIdeMcpServerOptions {
   cliPath?: string;
   workspaceRoot?: string;
@@ -1148,8 +1133,6 @@ export interface StartWeappIdeMcpServerOptions {
 export declare function startWeappIdeMcpServer(options?: StartWeappIdeMcpServerOptions): Promise<{
   close: () => Promise<void>;
 }>;
-//#endregion
-//#region src/mcp/server.d.ts
 interface ToolRegistrar {
   registerTool: McpServer['registerTool'];
 }
@@ -1168,8 +1151,6 @@ export declare function createWeappIdeMcpServer(options: WeappIdeMcpServerOption
   close: () => Promise<undefined>;
   server: McpServer;
 }>;
-//#endregion
-//#region src/runtime/platform.d.ts
 /**
  * @description 官方微信开发者工具只支持 Windows、macOS，Linux 只有社区版。
  * https://github.com/msojocs/wechat-web-devtools-linux
@@ -1195,8 +1176,6 @@ export declare const operatingSystemName: string;
  * @description 获取默认 CLI 路径（按系统）。
  */
 export declare function getDefaultCliPath(targetOs?: string): Promise<string | undefined>;
-//#endregion
-//#region src/utils/argv.d.ts
 /**
  * @description argv 处理函数
  */
@@ -1213,8 +1192,6 @@ export declare function createAlias(entry: AliasEntry): ArgvTransform;
  * @description 创建路径参数兼容转换器（补全或规范化路径）
  */
 export declare function createPathCompat(option: string): ArgvTransform;
-//#endregion
-//#region src/utils/exec.d.ts
 interface ExecuteOptions {
   pipeStdout?: boolean;
   pipeStderr?: boolean;
@@ -1229,11 +1206,8 @@ export declare function execute(cliPath: string, argv: string[], options?: Execu
   cancelSignal: AbortSignal | undefined;
   forceKillAfterDelay: number;
 }>>;
-//#endregion
-//#region src/utils/path.d.ts
 /**
  * @description 解析为绝对路径（基于当前工作目录）
  */
 export declare function resolvePath(filePath: string): string;
-//#endregion
-export { type AutomatorSessionOptions, type BaseConfig, type BeginManagedWechatProjectOptions, type CleanupManagedWechatProjectsOptions, type ConfigSource, type DevtoolsConnectionInput, type DevtoolsContext, type DevtoolsElementSnapshot, type DevtoolsPageSnapshot, type DevtoolsToolResult, type ManagedWechatHostIdentity, type ManagedWechatInstallationExitEvidence, type ManagedWechatProjectIntent, type ManagedWechatProjectRecord, type ManagedWechatProjectState, type ManagedWechatWindowCloseCall, type ManagedWechatWindowCloseEvidence, type ManagedWechatWindowLogCursor, type MiniProgramElement, type MiniProgramEventMap, type MiniProgramLike, type MiniProgramPage, type ResolvedConfig, type WechatDevtoolsHostInspectionOptions, closeSharedMiniProgram, getSharedMiniProgramSessionCount, readElementSnapshot, releaseSharedMiniProgram, resolveProjectPath, toSerializableValue };
+export { type AutomatorSessionOptions, type BaseConfig, type BeginManagedWechatProjectOptions, type CleanupManagedWechatProjectsOptions, type ConfigSource, type DevtoolsConnectionInput, type DevtoolsContext, type DevtoolsElementSnapshot, type DevtoolsPageSnapshot, type DevtoolsToolResult, type ManagedWechatHostIdentity, type ManagedWechatInstallationExitEvidence, type ManagedWechatProjectIntent, type ManagedWechatProjectRecord, type ManagedWechatProjectSnapshot, type ManagedWechatProjectState, type ManagedWechatWindowCloseCall, type ManagedWechatWindowCloseEvidence, type ManagedWechatWindowLogCursor, type MiniProgramElement, type MiniProgramEventMap, type MiniProgramLike, type MiniProgramPage, type ResolveWechatDevtoolsTargetOptions, type ResolvedConfig, type ResolvedWechatDevtoolsTarget, type WechatDevtoolsChannel, type WechatDevtoolsHostInspectionOptions, type WechatDevtoolsInstallation, type WechatDevtoolsSelectionOptions, closeSharedMiniProgram, getSharedMiniProgramSessionCount, readElementSnapshot, releaseSharedMiniProgram, resolveProjectPath, toSerializableValue };