weapp-ide-cli 6.1.9 → 6.3.0

package/dist/index.d.ts

@@ -1,22 +1,127 @@
+import { AutomatorElement, AutomatorMiniProgram, AutomatorPage, DevtoolsConnectionInput, DevtoolsContext, DevtoolsElementSnapshot, DevtoolsPageSnapshot, DevtoolsRuntimeSessionOptions, DevtoolsToolResult, MachineE2ELeaseRecoveryScope, MiniProgramEventMap, closeSharedMiniProgram, getSharedMiniProgramSessionCount, readDevtoolsElementSnapshot as readElementSnapshot, releaseSharedMiniProgram, resolveDevtoolsProjectPath as resolveProjectPath, toDevtoolsSerializableValue as toSerializableValue } from "@weapp-vite/devtools-runtime";
 import { Buffer } from "node:buffer";
-import { AutomatorElement, AutomatorMiniProgram, AutomatorPage, DevtoolsConnectionInput, DevtoolsContext, DevtoolsElementSnapshot, DevtoolsPageSnapshot, DevtoolsRuntimeSessionOptions, DevtoolsToolResult, MiniProgramEventMap, closeSharedMiniProgram, getSharedMiniProgramSessionCount, readDevtoolsElementSnapshot as readElementSnapshot, releaseSharedMiniProgram, resolveDevtoolsProjectPath as resolveProjectPath, toDevtoolsSerializableValue as toSerializableValue } from "@weapp-vite/devtools-runtime";
+import { OperationLifecycle } from "@weapp-vite/miniprogram-automator/operation";
+import { MiniProgram } from "@weapp-vite/miniprogram-automator";
 import { McpServer } from "@modelcontextprotocol/server";
-//#region src/cli/automator.d.ts
-export interface AutomatorOptions {
-  projectPath: string;
+//#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/types.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;
+}
+//#endregion
+//#region src/devtoolsTarget/discovery.d.ts
+/** 产品版本按数字段比较，避免日期版本的字符串排序漂移。 */
+export declare function compareWechatDevtoolsVersions(a: string, b: string): number;
+/** 只扫描已知安装根，不递归遍历磁盘，也不执行候选应用。 */
+export declare function listWechatDevtoolsInstallations(options?: ResolveWechatDevtoolsTargetOptions): Promise<WechatDevtoolsInstallation[]>;
+//#endregion
+//#region src/devtoolsTarget/host.d.ts
+interface WechatDevtoolsHostInspectionOptions {
+  platform?: NodeJS.Platform;
+  signal?: AbortSignal;
   timeout?: number;
+}
+/** 启动前验证共享宿主身份；无活跃宿主可以继续，其他安装不得被隐式接管。 */
+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/official.d.ts
+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;
+}>;
+//#endregion
+//#region src/devtoolsTarget/registry.d.ts
+/** 校验安装后登记真实 CLI 路径，不更改默认选择或登录数据。 */
+export declare function registerWechatDevtoolsInstallation(cliPath: string, registryPath?: string): Promise<ResolvedWechatDevtoolsTarget>;
+/** 允许移除已经失效的登记；不会删除应用或用户配置。 */
+export declare function unregisterWechatDevtoolsInstallation(cliPath: string, registryPath?: string): Promise<void>;
+//#endregion
+//#region src/devtoolsTarget/index.d.ts
+export declare function validateWechatDevtoolsSelection(options: WechatDevtoolsSelectionOptions): void;
+export declare function readWechatDevtoolsSelectionEnvironment(env?: NodeJS.ProcessEnv): WechatDevtoolsSelectionOptions;
+/** 每次操作只解析一次安装，显式选择覆盖继承的配置但不写回全局设置。 */
+export declare function resolveWechatDevtoolsTarget(options?: ResolveWechatDevtoolsTargetOptions): Promise<ResolvedWechatDevtoolsTarget>;
+/** 命令的所有异步阶段复用同一安装，彼此并发的调用不会污染环境变量。 */
+export declare function withWechatDevtoolsSelection<T>(options: ResolveWechatDevtoolsTargetOptions, runner: (target: ResolvedWechatDevtoolsTarget) => Promise<T>): Promise<T>;
+/** 读取当前操作固定的安装；没有活动选择时不触发发现或启动。 */
+export declare function getActiveWechatDevtoolsTarget(): ResolvedWechatDevtoolsTarget | undefined;
+//#endregion
+//#region src/cli/agentStart.d.ts
+export interface StartWechatIdeAgentOptions {
+  projectPath: string;
+  port: number;
   cliPath?: string;
-  port?: number;
-  sessionId?: string;
+  target?: ResolvedWechatDevtoolsTarget;
   trustProject?: boolean;
-  preferOpenedSession?: boolean;
-  preserveProjectRoot?: boolean;
-  persistAsDefaultSession?: boolean;
+  timeout?: number;
+  signal?: AbortSignal;
+  /** 预检完成后、命令派发前登记启动意图；钩子开始后取消仍按派发结果未知处理。 */
+  onBeforeDispatch?: () => void | Promise<void>;
+  /** 官方回执验证后先登记窗口所有权，再检查取消状态。 */
+  onStarted?: (result: StartWechatIdeAgentResult) => void | Promise<void>;
+}
+export interface StartWechatIdeAgentResult {
+  autoPort: number;
+  openedProjectWindow: boolean;
+  version: string;
 }
-/**
- * @description 为项目路径派生稳定的 DevTools automator 端口，避免多个 dev:open 项目抢占默认端口。
- */
-export declare function resolveProjectAutomatorPort(projectPath: string): number;
+/** 使用所选安装的官方 agent start，并保留其窗口复用和端口冲突语义。 */
+export declare function startWechatIdeAgent(options: StartWechatIdeAgentOptions): Promise<StartWechatIdeAgentResult>;
+//#endregion
+//#region src/cli/automator/context.d.ts
+interface AutomatorInstallationOptions extends DevtoolsRuntimeSessionOptions, WechatDevtoolsSelectionOptions {
+  target?: ResolvedWechatDevtoolsTarget;
+  signal?: AbortSignal;
+}
+/** 在连接与共享缓存入口固定安装选择；headless 不读取或修改 IDE 状态。 */
+export declare function resolveAutomatorSessionOptions<T extends AutomatorInstallationOptions>(options: T): Promise<T & AutomatorInstallationOptions & {
+  installationId: string;
+}>;
+//#endregion
+//#region src/cli/automator/errors.d.ts
 /**
  * @description 判断错误是否属于开发者工具服务端口不可用。
  */
@@ -53,17 +158,42 @@ 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;
+  signal?: AbortSignal;
+  cliPath?: string;
+  port?: number;
+  sessionId?: string;
+  trustProject?: boolean;
+  preferOpenedSession?: boolean;
+  preserveProjectRoot?: boolean;
+  persistAsDefaultSession?: boolean;
+}
+/**
+ * @description 为项目路径派生稳定的 DevTools automator 端口，避免多个 dev:open 项目抢占默认端口。
+ */
+export declare function resolveProjectAutomatorPort(projectPath: string): number;
 /**
  * @description 基于当前配置解析 CLI 路径，并通过现代化 automator 入口启动会话。
  */
 export declare function launchAutomator(options: AutomatorOptions): Promise<any>;
 /**
- * @description 连接当前项目已打开的开发者工具自动化会话，不触发新的 IDE 拉起。
+ * @description 登记由外部 automator bridge 创建的会话，供 CLI 子进程安全复用。
  */
-export declare function connectOpenedAutomator(options: AutomatorOptions): Promise<unknown>;
+export declare function persistOpenedAutomatorSession(options: AutomatorOptions & {
+  wsEndpoint: string;
+}): Promise<void>;
+/**
+ * @description 只读连接当前项目已打开的自动化会话；失败不证明缓存过期，也不删除其他操作持有的会话记录。
+ */
+export declare function connectOpenedAutomator(options: AutomatorOptions): Promise<MiniProgram>;
 //#endregion
 //#region src/cli/automator-argv.d.ts
 export interface ParsedAutomatorArgs {
+  cliPath?: string;
   projectPath: string;
   timeout?: number;
   port?: number;
@@ -93,7 +223,10 @@ export declare function removeOption(argv: readonly string[], optionName: string
 type MiniProgramLike = AutomatorMiniProgram;
 type MiniProgramPage = AutomatorPage;
 type MiniProgramElement = AutomatorElement;
-interface AutomatorSessionOptions extends DevtoolsRuntimeSessionOptions {}
+interface AutomatorSessionOptions extends DevtoolsRuntimeSessionOptions, WechatDevtoolsSelectionOptions {
+  signal?: AbortSignal;
+  target?: ResolvedWechatDevtoolsTarget;
+}
 /** 建立交互式会话，并报告最终连接错误。 */
 export declare function connectMiniProgram(options: AutomatorSessionOptions): Promise<MiniProgramLike>;
 /**
@@ -246,8 +379,19 @@ export declare function parseCompareArgs(argv: string[]): CompareOptions;
  */
 export declare function handleConfigCommand(argv: string[]): Promise<void>;
 //#endregion
+//#region src/cli/devtoolsSelection.d.ts
+/** 包装参数不会透传官方 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>;
+//#endregion
 //#region src/cli/http.d.ts
-export interface WechatDevtoolsHttpCommandOptions {
+export interface WechatDevtoolsHttpCommandOptions extends WechatDevtoolsSelectionOptions {
+  cliPath?: string;
+  target?: ResolvedWechatDevtoolsTarget;
   port?: number;
   signal?: AbortSignal;
   timeoutMs?: number;
@@ -264,9 +408,10 @@ export interface PollWechatIdeEngineBuildResult extends WechatDevtoolsEngineBuil
   done: boolean;
   failed: boolean;
 }
+/** 请求期间持有机器租约，避免 E2E 与另一入口同时更改共享宿主。 */
 export declare function requestWechatDevtoolsHttp(pathname: string, query: Record<string, string>, options?: WechatDevtoolsHttpCommandOptions): Promise<string>;
 /**
- * @description 通过微信开发者工具 HTTP 服务端口重新打开项目；若项目已打开，开发者工具会刷新当前项目。
+ * @description 请求微信开发者工具打开项目并返回原始响应；目标 runtime 状态仍需通过会话或界面确认。
  */
 export declare function openWechatIdeProjectByHttp(projectPath: string, options?: WechatDevtoolsHttpCommandOptions): Promise<string>;
 /**
@@ -297,17 +442,19 @@ export interface RunWechatIdeEngineBuildByHttpOptions extends WechatDevtoolsHttp
 }
 export interface RunWechatIdeEngineBuildOptions extends RunWechatIdeEngineBuildByHttpOptions {
   fallbackToCli?: boolean;
+  /** 避免 CLI 诊断污染协议标准输出。 */
+  quiet?: boolean;
   logPath?: string;
 }
 export declare function isWechatIdeEngineBuildEndpointMissingError(error: unknown): boolean;
-/**
- * @description 通过开发者工具 HTTP 服务端口执行 engine build，并轮询直到构建结束。
- */
+/** 固定安装上下文后完整持有 HTTP 构建与轮询期间的租约。 */
 export declare function runWechatIdeEngineBuildByHttp(projectPath: string, options?: RunWechatIdeEngineBuildByHttpOptions): Promise<PollWechatIdeEngineBuildResult>;
-/**
- * @description 以更接近官方 CLI 的方式执行 engine build，并支持将构建日志写入文件。
- */
+/** HTTP、轮询与 CLI 回退沿用同一次解析的安装。 */
 export declare function runWechatIdeEngineBuild(projectPath: string, options?: RunWechatIdeEngineBuildOptions): Promise<void | PollWechatIdeEngineBuildResult>;
+/** 在验收交互前等待 IDE 消费产物，并沿用该会话选择的安装。 */
+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';
@@ -344,6 +491,7 @@ export interface SharedInputSession {
   suspend: () => void;
 }
 export interface ExclusiveKeypressOptions<T> {
+  signal?: AbortSignal;
   ignoreInitialMs?: number;
   timeoutMs?: number;
   onKeypress: (str: string, key: {
@@ -355,6 +503,20 @@ export declare function createSharedInputSession(options: SharedInputSessionOpti
 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;
+} | {
+  status: 'unknown';
+  reason: 'timeout' | 'command-failed' | 'invalid-response' | 'installation-mismatch' | 'runtime-busy';
+};
+/** 显式调用指定 CLI 查询登录语义，不重试、不提示登录；原生 CLI 可能启动 IDE。 */
+export declare function queryWechatIdeLogin(cliPath: string, options?: {
+  timeout?: number;
+  signal?: AbortSignal;
+}): Promise<WechatIdeLoginQueryResult>;
+//#endregion
 //#region src/cli/minidev.d.ts
 /**
  * @description 运行支付宝小程序 CLI（minidev）
@@ -378,6 +540,7 @@ export declare function resolveCliPath(): Promise<{
 //#endregion
 //#region src/cli/retry.d.ts
 export interface RetryKeypressOptions {
+  signal?: AbortSignal;
   timeoutMs?: number;
 }
 export interface RetryPromptOptions extends RetryKeypressOptions {
@@ -391,6 +554,7 @@ export interface RetryLogger {
   warn: (message: string) => void;
 }
 export interface WechatIdeLoginRetryOptions {
+  signal?: AbortSignal;
   allowRetry?: boolean;
   cancelLevel?: 'info' | 'warn';
   error: unknown;
@@ -447,9 +611,7 @@ export declare function promptWechatIdeLoginRetry(options: WechatIdeLoginRetryOp
  * @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
@@ -468,32 +630,35 @@ export declare function getAutomatorCommandHelp(command: string): string | undef
 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;
+  signal?: AbortSignal;
 }
-/**
- * @description 运行微信开发者工具 CLI，并在登录失效时允许按键重试。
- */
+/** 原生 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;
+  maxAttempts?: number;
+  disposeLate?: (result: TResult) => void | Promise<void>;
   createCancelError: (result: TResult) => Error;
-  execute: () => Promise<TResult>;
+  execute: (operation: OperationLifecycle) => Promise<TResult>;
   isRetryableResult: (result: TResult) => boolean;
   onCancel?: (result: TResult) => void;
   onRetry?: () => void;
-  promptRetry: (result: TResult, retryCount: number) => Promise<TPromptResult>;
+  promptRetry: (result: TResult, retryCount: number, operation: OperationLifecycle) => Promise<TPromptResult>;
   shouldRetry: (result: TPromptResult) => boolean;
 }
-/**
- * @description 执行可重试命令循环，并将“是否可重试”与“如何提示重试”交给调用方定义。
- */
+/** 命令、登录提示和有限重试共用一个 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>;
@@ -515,24 +680,24 @@ export declare function parseScreenshotArgs(argv: string[]): ScreenshotOptions;
 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;
@@ -542,14 +707,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;
@@ -557,7 +722,7 @@ export interface UploadWechatIdeOptions {
   projectPath?: string;
   version: string;
 }
-export interface AutoWechatIdeOptions {
+export interface AutoWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   account?: string;
   appid?: string;
   extAppid?: string;
@@ -567,7 +732,7 @@ export interface AutoWechatIdeOptions {
   ticket?: string;
   trustProject?: boolean;
 }
-export interface AutoReplayWechatIdeOptions {
+export interface AutoReplayWechatIdeOptions extends WechatDevtoolsSelectionOptions {
   account?: string;
   appid?: string;
   extAppid?: string;
@@ -579,16 +744,21 @@ export interface AutoReplayWechatIdeOptions {
   ticket?: string;
   trustProject?: boolean;
 }
-export interface OpenWechatIdeOtherProjectOptions {
+export interface OpenWechatIdeOtherProjectOptions extends WechatDevtoolsSelectionOptions {
+  projectPath?: string;
+}
+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;
@@ -606,7 +776,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;
@@ -618,7 +788,7 @@ export interface BuildWechatIdeApkOptions {
   storePass: string;
   useAab?: boolean;
 }
-export interface BuildWechatIdeIpaOptions {
+export interface BuildWechatIdeIpaOptions extends WechatDevtoolsSelectionOptions {
   certificateName?: string;
   isDistribute: boolean;
   isRemoteBuild?: boolean;
@@ -635,9 +805,7 @@ export interface BuildWechatIdeIpaOptions {
   versionDesc?: string;
   versionName?: string;
 }
-/**
- * @description 调用微信开发者工具 open 命令。
- */
+/** 打开与兼容回退在同一机器租约内沿用固定安装，禁止重新选择宿主。 */
 export declare function openWechatIde(options?: OpenWechatIdeOptions): Promise<void>;
 /**
  * @description 调用微信开发者工具 login 命令。
@@ -649,7 +817,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 命令。
  */
@@ -677,11 +845,11 @@ export declare function uploadWechatIde(options: UploadWechatIdeOptions): Promis
 /**
  * @description 调用微信开发者工具 close 命令。
  */
-export declare function closeWechatIdeProject(): Promise<void>;
+export declare function closeWechatIdeProject(options?: CloseWechatIdeProjectOptions): Promise<void>;
 /**
  * @description 调用微信开发者工具 quit 命令。
  */
-export declare function quitWechatIde(): Promise<void>;
+export declare function quitWechatIde(options?: WechatDevtoolsSelectionOptions): Promise<void>;
 /**
  * @description 调用微信开发者工具 cache 命令。
  */
@@ -689,7 +857,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 状态。
  */
@@ -738,14 +906,15 @@ export declare function buildWechatIdeIpa(options: BuildWechatIdeIpaOptions): Pr
 export declare function dispatchWechatCliCommand(argv: string[]): Promise<boolean>;
 //#endregion
 //#region src/cli/wechatDevtoolsRuntimePort.d.ts
+type PortTarget = Pick<ResolvedWechatDevtoolsTarget, 'installationId'>;
 /**
- * @description 标记当前进程最近一次检测到的微信开发者工具服务端口。
+ * @description 标记所选安装检测到的服务端口；无身份的旧调用仅保留在独立兼容槽中。
  */
-export declare function setRuntimeWechatDevtoolsServicePort(port: number | undefined): void;
+export declare function setRuntimeWechatDevtoolsServicePort(port: number | undefined, target?: PortTarget): void;
 /**
- * @description 读取当前进程最近一次检测到的微信开发者工具服务端口。
+ * @description 只读取所选安装的服务端口，不借用其他安装或无身份的旧记录。
  */
-export declare function getRuntimeWechatDevtoolsServicePort(): number | undefined;
+export declare function getRuntimeWechatDevtoolsServicePort(target?: PortTarget): number | undefined;
 //#endregion
 //#region src/cli/wechatDevtoolsSettings.d.ts
 export interface WechatDevtoolsSecuritySettings {
@@ -758,10 +927,8 @@ export interface DetectedWechatDevtoolsServicePortSettings {
   enabled?: boolean;
   port?: number;
 }
-export interface DetectWechatDevtoolsServicePortOptions {
-  homeDir?: string;
-  localAppDataDir?: string;
-  platform?: NodeJS.Platform;
+export interface DetectWechatDevtoolsServicePortOptions extends ResolveWechatDevtoolsTargetOptions {
+  target?: ResolvedWechatDevtoolsTarget;
 }
 export interface DetectWechatDevtoolsServicePortResult {
   touchedInstanceCount: number;
@@ -799,7 +966,7 @@ interface BaseConfig {
 /**
  * @description 配置来源
  */
-type ConfigSource = 'custom' | 'default' | 'missing';
+type ConfigSource = 'custom' | 'default' | 'environment' | 'missing';
 /**
  * @description 解析后的配置
  */
@@ -869,7 +1036,7 @@ export declare function resolveDevtoolsAutomationDefaults(config: {
   autoTrustProject: boolean;
 };
 /**
- * @description 读取并解析 CLI 配置（自定义优先）
+ * @description 读取并解析 CLI 配置（进程选择优先，其次用户配置与平台默认）
  */
 export declare function getConfig(): Promise<ResolvedConfig>;
 /**
@@ -877,8 +1044,189 @@ export declare function getConfig(): Promise<ResolvedConfig>;
  */
 export declare function getConfiguredLocale(): Promise<"zh" | "en" | undefined>;
 //#endregion
+//#region src/devtoolsProjectOwnership/types.d.ts
+interface ManagedWechatHostIdentity {
+  pid: number;
+  executable: string;
+  started: string;
+}
+type ManagedWechatProjectState = 'starting' | 'unconfirmed' | 'owned' | 'borrowed' | 'closing' | 'failed' | 'released';
+interface ManagedWechatInstallationExitEvidence {
+  protocol: 'wechat-devtools-installation-exit-v1';
+  recoveredAt: string;
+  recoveryScopeId: string;
+  journalScopeId: string;
+  journalRootPath: string;
+  installationId: string;
+  profileDir: string;
+  previous: {
+    state: 'starting' | 'unconfirmed' | 'failed' | 'borrowed';
+    error?: string;
+    updatedAt: string;
+    recordSha256: string;
+  };
+  stoppedOwnerPids: number[];
+  closedPorts: number[];
+  processInspection: {
+    platform: 'darwin';
+    installationRoot: string;
+    checkedAt: string;
+    inspectedProcessCount: number;
+    kernelPathProcessCount: number;
+    textImageProcessCount: number;
+    exitedProcessCount: number;
+    zombieProcessCount: number;
+    selectedProcessCount: 0;
+  };
+}
+interface ManagedWechatWindowLogCursor {
+  name: string;
+  identity: string;
+  offset: number;
+  anchor: string;
+  skipPartialLine: boolean;
+}
+interface ManagedWechatWindowCloseCall {
+  fileIdentity: string;
+  winId: string;
+  browserWindowId: number;
+  calledAt: string;
+  cancelled?: boolean;
+}
+interface ManagedWechatWindowCloseEvidence {
+  protocol: 'wechat-devtools-window-close-trace-v1';
+  profileDir: string;
+  productVersion: string;
+  capturedAt: string;
+  /** 活动日志按文件句柄捕获时，绑定实际持有日志的主进程身份。 */
+  mainHost?: ManagedWechatHostIdentity;
+  /** 关闭意图先于 CLI 落盘；未知执行结果不能再次按路径关闭窗口。 */
+  dispatchedAt?: string;
+  cursors: ManagedWechatWindowLogCursor[];
+  calls: ManagedWechatWindowCloseCall[];
+  window?: ManagedWechatWindowCloseCall & {
+    runtimeId: string;
+    requestedAt: string;
+    nativeClosedAt?: string;
+    webContentsDestroyedAt?: string;
+  };
+  failure?: string;
+  /** 旧整目录门禁恢复时保留原失败和游标，不重新捕获偏移或重复关窗。 */
+  logInventoryRecovery?: {
+    failure: string;
+    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;
+  generation: string;
+  journalPath: string;
+  ownerToken: string;
+  ownerPid: number;
+  target: ResolvedWechatDevtoolsTarget;
+  projectPath: string;
+  state: ManagedWechatProjectState;
+  openedProjectWindow?: boolean;
+  port?: number;
+  /** 自动化端口的监听进程身份，可能是 backend；不能当作主宿主或窗口身份。 */
+  host?: ManagedWechatHostIdentity;
+  createdAt: string;
+  updatedAt: string;
+  closeAcknowledgedAt?: string;
+  /** 端口退出不是窗口退出；保存所选 profile 的增量销毁证据供父任务恢复。 */
+  windowClose?: ManagedWechatWindowCloseEvidence;
+  releasedReason?: 'borrowed' | 'project-closed' | 'installation-exited' | 'not-started';
+  /** 显式恢复只终结已退出安装的活资源；原启动失败与归属缺口仍保留。 */
+  installationExitRecovery?: ManagedWechatInstallationExitEvidence;
+  error?: string;
+  snapshot?: ManagedWechatProjectSnapshot;
+}
+interface BeginManagedWechatProjectOptions {
+  target: ResolvedWechatDevtoolsTarget;
+  projectPath: string;
+  generation?: string;
+  port?: number;
+  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;
+  }) => Promise<void>;
+  fail: (error: unknown) => Promise<void>;
+  close: () => Promise<void>;
+}
+interface CleanupManagedWechatProjectsOptions {
+  journalPath?: string;
+  scope?: 'process' | 'journal';
+}
+//#endregion
+//#region src/devtoolsProjectOwnership/installationExit/index.d.ts
+export interface RecoverManagedWechatProjectsAfterInstallationExitOptions {
+  target: ResolvedWechatDevtoolsTarget;
+  recoveryScope: MachineE2ELeaseRecoveryScope;
+}
+export interface ManagedWechatInstallationExitRecoveryResult {
+  recoveredRecordIds: string[];
+}
+/** 在精确恢复租约中终结已退出安装的未知启动或失败关窗；保留原证据，不补造销毁事件。 */
+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/snapshot/index.d.ts
+/** 窗口已经释放不代表本任务快照也已回收。 */
+export declare function isManagedWechatProjectFullyReleased(record: {
+  state: ManagedWechatProjectRecord['state'];
+  snapshot?: Pick<NonNullable<ManagedWechatProjectRecord['snapshot']>, 'state'>;
+}): boolean;
+//#endregion
+//#region src/devtoolsProjectOwnership/index.d.ts
+/** 窗口销毁与连接断开分别验证；失败保留登记供后续继续观察。 */
+export declare function closeManagedWechatProject(options: {
+  journalPath?: string;
+  id: string;
+}): Promise<void>;
+/** 未启用受管日志时不改变公共共享会话；意图登记本身没有项目关闭权。 */
+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;
 }
 export declare function startWeappIdeMcpServer(options?: StartWeappIdeMcpServerOptions): Promise<{
@@ -890,14 +1238,7 @@ interface ToolRegistrar {
   registerTool: McpServer['registerTool'];
 }
 export interface WeappIdeMcpRuntimeHooks {
-  withMiniProgram: <T>(options: {
-    preferOpenedSession?: boolean;
-    port?: number;
-    projectPath: string;
-    sharedSession?: boolean;
-    sessionId?: string;
-    timeout?: number;
-  }, runner: (miniProgram: MiniProgramLike) => Promise<T>) => Promise<T>;
+  withMiniProgram: <T>(options: AutomatorSessionOptions, runner: (miniProgram: MiniProgramLike) => Promise<T>) => Promise<T>;
 }
 export interface WeappIdeMcpServerOptions {
   runtimeHooks: WeappIdeMcpRuntimeHooks;
@@ -962,12 +1303,15 @@ interface ExecuteOptions {
   pipeStdout?: boolean;
   pipeStderr?: boolean;
   timeout?: number;
+  signal?: AbortSignal;
 }
 /**
  * @description 执行 CLI 命令并透传输出
  */
 export declare function execute(cliPath: string, argv: string[], options?: ExecuteOptions): Promise<import("execa").Result<{
   timeout: number | undefined;
+  cancelSignal: AbortSignal | undefined;
+  forceKillAfterDelay: number;
 }>>;
 //#endregion
 //#region src/utils/path.d.ts
@@ -976,4 +1320,4 @@ export declare function execute(cliPath: string, argv: string[], options?: Execu
  */
 export declare function resolvePath(filePath: string): string;
 //#endregion
-export { type AutomatorSessionOptions, type BaseConfig, type ConfigSource, type DevtoolsConnectionInput, type DevtoolsContext, type DevtoolsElementSnapshot, type DevtoolsPageSnapshot, type DevtoolsToolResult, type MiniProgramElement, type MiniProgramEventMap, type MiniProgramLike, type MiniProgramPage, type ResolvedConfig, 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 };