midscene 项目说明书

Doramagic 项目包 · 项目说明书

midscene 项目

AI 驱动、视觉驱动的 UI 自动化，覆盖全平台。

项目概览与整体架构

Midscene.js 是一套基于视觉的 AI 驱动 UI 自动化 SDK，核心目标是用自然语言描述操作步骤，替代传统依赖 DOM 选择器或可访问性树的脆弱自动化方案。其设计哲学明确写在根目录 README.md 中：只要人类能看见的元素，Midscene 就能定位与操作，从而覆盖 <canvas、原生应用、跨域 iframe 等传统工具无法触及的界面。

章节 相关页面

继续阅读本节完整说明和来源证据。

一、项目定位与核心价值

Midscene.js 是一套基于视觉的 AI 驱动 UI 自动化 SDK，核心目标是用自然语言描述操作步骤，替代传统依赖 DOM 选择器或可访问性树的脆弱自动化方案。其设计哲学明确写在根目录 README.md 中：只要人类能看见的元素，Midscene 就能定位与操作，从而覆盖 <canvas>、原生应用、跨域 iframe 等传统工具无法触及的界面。

主要应用场景包括：

Web 端 UI 自动化与测试 —— 与 Playwright 或 Vitest 集成（packages/web-integration/README.md）。
多端覆盖 —— Android、iOS、桌面（Computer）以及 HarmonyOS（packages/harmony-mcp/package.json）。
AI Agent 模式 —— 通过 Skills 与 MCP 让模型自主驱动测试与操作（README.md）。

当前最新发布版本为 v1.9.7，采用 MIT 许可证（packages/cli/package.json、README.md）。

二、仓库结构与包划分

项目采用 monorepo 模式（@midscene/* workspace），按"核心能力 + 平台适配 + 工具"进行分层。下表汇总了主要包及其职责：

包名	目录	职责与入口
`@midscene/core`	packages/core	核心 SDK：AI 模型抽象、任务规划、设备抽象、工具函数（`./utils`、`./ai-model`、`./device`）
`@midscene/web`	packages/web-integration	浏览器集成：Playwright、Puppeteer、桥接模式（`./bridge-mode`）
`@midscene/ios`	packages/ios	iOS 模拟器自动化，含 CLI (`midscene-ios`) 与 MCP server
`@midscene/android`	（由 cli package 引用）	Android 设备自动化
`@midscene/harmony`	（由 cli package 引用）	HarmonyOS 鸿蒙端 UI 自动化
`@midscene/computer`	（由 cli package 引用）	桌面操作抽象层，依赖 libnut 原生控制（README.md）
`@midscene/computer-mac`	packages/computer-mac	macOS 桌面自动化实现
`@midscene/shared`	packages/shared	公共类型、录制器（recorder）、键盘布局、坐标系统
`@midscene/visualizer`	packages/visualizer	可视化与回放组件
`@midscene/cli`	packages/cli	统一命令行工具（`midscene`），聚合各平台

应用层（apps/）目前以 apps/chrome-extension 为主，提供浏览器扩展形式的录制与回放能力，封装了 openai 客户端并使用 rsbuild 构建。

三、核心架构与数据流

Midscene 的运行时遵循"截图 → AI 规划 → 平台执行 → 回放/断言"的闭环：

flowchart LR
  A[用户自然语言指令] --> B[AI 规划层<br/>core/ai-model]
  B --> C[设备抽象层<br/>core/device]
  C --> D{平台适配}
  D -->|Web| E[web-integration<br/>Playwright/Puppeteer]
  D -->|Mobile| F[iOS / Android / Harmony]
  D -->|Desktop| G[computer / computer-mac<br/>libnut]
  E & F & G --> H[截图与事件回放]
  H --> I[Visualizer / Chrome Extension<br/>录制报告]
  I --> J{断言/导出}
  J -->|通过| K[CI 测试或 Agent 循环]
  J -->|生成脚本| L[Playwright/YAML/Markdown]

关键模块说明：

录制与回放抽象 由 packages/shared/src/recorder.ts 定义事件模型（MidsceneRecorderTarget、MidsceneRecorderGeneratedCode），统一支持导出 Markdown、YAML 与 Playwright 脚本——回应了社区 #2240 关于"导出 AI 步骤为可复用 Playwright 脚本"的需求。
键盘输入层 在 packages/shared/src/us-keyboard-layout.ts 通过 transformHotkeyInput 将自然语言按键转换为 KeyInput，覆盖 Numpad0-9、ArrowUp 等完整 US 键盘布局。

四、平台支持与集成方式

浏览器自动化：通过 packages/web-integration 暴露 bridge-mode 与 bridge-mode-browser 子入口，可注入到任意已有浏览器控制栈。
命令行：@midscene/cli 聚合了 android、computer、harmony、ios、web 等子命令（packages/cli/package.json），适合在 CI 中以 YAML 脚本驱动。
MCP 集成：@midscene/harmony 与 @midscene/ios 都提供 mcp-server 子包，遵循 Model Context Protocol 标准，可被外部 Agent 调度。
桌面操作：底层使用 libnut 进行跨平台原生键鼠控制（README.md）。

五、社区生态与已知限制

Awesome Midscene 收录的社区扩展（README.md）已经覆盖：

iOS 镜像（midscene-ios）
PC 端跨平台（midscene-pc）
Python / Java 多语言 SDK

当前仍在演进的方向与社区关注点（community_context）：

RAG 与领域知识（#426）—— 当前通用 LLM 对高层或领域化指令理解不足，社区希望引入检索增强机制。
视口外元素（#179）—— 滚动后定位、长表单、商品页等场景需要自动滚动并重定位。
鸿蒙原生支持（#1594）—— 仓库已新增 @midscene/harmony 与 @midscene/harmony-mcp 作为初步落地。
Playwright 脚本导出（#2240）—— MidsceneRecorderGeneratedCode 接口已预留 playwright 字段，CLI 端持续完善中。
桌面 Agent 化（#1389）—— 鼓励社区基于"任意接口集成"能力扩展 Windows / Linux 桌面 Agent。

核心引擎:Agent、多模态模型与 AI 工作流

Midscene 的核心引擎位于 @midscene/core 包中，定位为"基于 AI 的 UI 自动化 SDK"——通过自然语言即可驱动页面操作、断言与数据抽取 README.md。其包描述明确指出，核心包对外提供多组入口：./ai-model、./device、./tree、./utils 以及根入口 packages/core/package.json，分别对应 A...

章节 相关页面

继续阅读本节完整说明和来源证据。

一、核心引擎的定位与设计哲学

Midscene 的核心引擎位于 @midscene/core 包中，定位为"基于 AI 的 UI 自动化 SDK"——通过自然语言即可驱动页面操作、断言与数据抽取 README.md。其包描述明确指出，核心包对外提供多组入口：./ai-model、./device、./tree、./utils 以及根入口 packages/core/package.json，分别对应 AI 模型适配、设备抽象、页面树结构与通用工具。

与依赖 DOM 或可访问性树的传统方案不同，Midscene 强调"以截图作为唯一视觉输入"的设计理念：只要人类能看到的目标，引擎就能定位与操作，对 <canvas>、原生应用和跨域 iframe 同样有效 README.md。这一设计在 Issue #179（视口外元素支持）以及 Issue #1389（PC 设备接入 midscene-pc）等社区讨论中被反复印证是引擎扩展性的根基。

二、Agent 工作流与任务模型

Midscene 的 Agent 围绕一组语义化动作构建，这些动作在 YAML 任务脚本与录制器输出中保持一致 packages/shared/src/constants/example-code.ts：

任务类型	用途	关键参数
`ai` / `aiAct`	自然语言驱动的自动规划交互	`cacheable`
`aiTap` / `aiDoubleClick` / `aiHover`	瞬时点击/双击/悬停	元素描述 + 可选 `xpath`
`aiInput`	文本输入	`text value` + 定位
`aiScroll`	滚动	`direction`、`scrollType`、`distance`
`aiAssert`	视觉断言	期望状态描述
`sleep`	延时控制	毫秒数

任务层还支持 continueOnError 容错控制与 cacheable 缓存选项，后者与文档中提到的"caching feature"配合，可在多模态模型推理时复用结果以降低成本 packages/shared/src/constants/example-code.ts。如下图为典型 Agent 工作流：

flowchart LR
    A[自然语言指令 / YAML 任务] --> B[截图采集<br/>device 抽象]
    B --> C[多模态模型<br/>@midscene/core/ai-model]
    C --> D{规划结果}
    D -- 交互 --> E[执行动作<br/>aiTap / aiInput / aiScroll]
    D -- 断言 --> F[视觉比对<br/>aiAssert]
    E --> G[页面状态更新]
    F --> G
    G --> B

需要注意的是，Issue #179 反馈的"视口外元素"问题正是在该循环中通过 aiScroll 暴露的：当目标不在当前视口时，引擎需要多次截图-规划-滚动才能收敛。

三、多模态模型与平台适配

引擎通过 @midscene/core 暴露 ./ai-model 子入口，封装了与多模态大模型的协议对接 packages/core/package.json。围绕该入口，平台适配层以 npm workspace 形式分发独立包：

Web @midscene/web：与 Playwright、Puppeteer 集成，并提供 Bridge Mode 用于远程脚本控制 packages/web-integration/README.md packages/web-integration/package.json。
CLI @midscene/cli：聚合 Web/Android/iOS/Harmony/Computer 等子包，提供 midscene 命令行入口 packages/cli/package.json。
iOS @midscene/ios：提供 midscene-ios 命令及 mcp-server 子入口，支持模拟器自动化 packages/ios/package.json。
Harmony MCP @midscene/harmony-mcp：基于 @modelcontextprotocol/sdk 的鸿蒙适配，对应社区 Issue #1594 关于"鸿蒙 UI 自动化最后一块拼图"的诉求 packages/harmony-mcp/package.json。
Visualizer @midscene/visualizer：用于执行过程可视化与回放 packages/visualizer/README.md。

统一的设备抽象（./device）和树结构（./tree）使多模态模型在不同平台下复用相同的提示词与规划策略 packages/core/package.json。这也是社区 Issue #1389 中 midscene-pc 能直接接入 AI agent 的根本原因。

四、录制器与工作流代码生成

Chrome 扩展内的录制器是 Agent 工作流的"逆向入口"——用户操作被记录为结构化事件，再由 AI 转换为可复用的脚本 apps/chrome-extension/src/extension/recorder/utils.ts。MidsceneRecorderTarget 抽象了 platformId、deviceId、label 与 values，覆盖不同平台的录制目标 packages/shared/src/recorder.ts。

录制器支持三类代码输出：

Markdown：保留完整事件描述，支持 maxScreenshots（默认 20）张截图嵌入 packages/shared/src/recorder.ts。
YAML：与 example-code.ts 中定义的任务格式保持一致，便于直接进入 CI 流水线 apps/chrome-extension/src/extension/recorder/utils.ts。
Playwright：直接生成可执行的 .spec 脚本，对应 Issue #2240 中"将 AI 执行步骤导出为可复用 Playwright 脚本"的需求 apps/chrome-extension/src/extension/recorder/utils.ts。

录制器还提供 exportAllEventsToZip 工具，可将会话、截图与代码打包下载，便于团队共享与回归测试 apps/chrome-extension/src/extension/recorder/utils.ts。

五、典型失败模式与建议

视口外元素定位失败：若未在任务序列中加入 aiScroll，模型可能直接放弃，参考 Issue #179 建议改用滚动-重定位-操作的循环。
领域术语误识别：社区 Issue #426 指出通用 LLM 难以理解产品域指令，可结合提示词微调或在任务脚本中显式给出 locate 描述以约束模型。
录制器输出无截图：检查 MidsceneRecorderMarkdownScreenshotOptions.maxScreenshots 是否被业务层覆盖 packages/shared/src/recorder.ts。

平台集成:Web、Mobile、桌面与自定义接口

Midscene 是一个面向 UI 自动化的多模态 SDK，定位为"视觉驱动的 AI Operator"，通过截图与多模态模型完成元素定位、断言与数据抽取。其核心设计原则是"多平台统一接入":同一套自然语言 API 可以在 Web、Mobile、桌面乃至自定义接口上复用。

章节 相关页面

继续阅读本节完整说明和来源证据。

概览

项目以 monorepo 形式组织,核心抽象位于 @midscene/core,各平台包通过 device 接口与核心解耦资料来源：packages/core/package.json:1-50。上层入口由 @midscene/cli 统一调度 Web、Android、iOS、HarmonyOS 与 computer 五个平台资料来源：packages/cli/package.json:1-30。

Web 平台集成

@midscene/web(原 web-integration)是 Web 端的主入口,提供三条主要接入路径:

集成方式	适用场景	包导出
Playwright	现代 E2E 测试	`./`
Puppeteer	遗留/轻量场景	`./`
Bridge Mode	跨进程/跨语言	`./bridge-mode`

导出项中除主入口外,还显式暴露了 ./bridge-mode、./bridge-mode-browser 与 ./utils 等子路径,方便按需打包资料来源：packages/web-integration/package.json:1-60。README 中也分别给出 Playwright、Puppeteer 与 Bridge Mode 的官方文档链接资料来源：packages/web-integration/README.md:1-10。

Bridge Mode 是社区与#2240中"将 AI 执行步骤导出为可复用 Playwright 脚本"诉求的重要基础——它让 AI 推理过程可在独立进程运行,从而支持回放与脚本化。

Mobile 平台集成

Mobile 端按操作系统拆分为独立包:

iOS:@midscene/ios 提供 SDK、CLI(midscene-ios)与 MCP Server 入口资料来源：packages/ios/package.json:1-40。
Android:@midscene/android 通过 CLI 统一调度入口资料来源：packages/cli/package.json:1-20。
HarmonyOS:@midscene/harmony 与 @midscene/harmony-mcp 提供鸿蒙设备驱动与 MCP 适配层资料来源：packages/harmony-mcp/package.json:1-15。

各 Mobile 包共享 @midscene/core 的设备抽象,使得 aiAct、aiQuery、aiAssert 等高层 API 在三端语义一致。社区对 HarmonyOS 自动化的强烈呼声(#1594)促使项目将鸿蒙纳入主仓,而非作为外部扩展。

桌面与 Computer 集成

桌面端由 @midscene/computer 包提供,项目括跨平台键盘鼠标控制与滚动事件归一化(例如近期修复的"libnut 滚动 tick 触发完整 WHEEL_DELTA")。CLI 顶层依赖中已包含该包资料来源：packages/cli/package.json:1-20。

桌面交互需要把抽象键名映射到平台键码,@midscene/shared 中的 us-keyboard-layout.ts 与 transformHotkeyInput 工具负责将自然语言热键拆分为可识别的键输入序列资料来源：packages/shared/src/us-keyboard-layout.ts:1-80。

社区项目 midscene-pc 进一步将桌面能力扩展为 Windows/macOS/Linux 上的统一代理(#1389),印证了"通过统一 device 接口对接任意 UI"这一架构路线的可扩展性。

自定义接口与生态扩展

当内置平台不满足需求时,Midscene 通过以下机制支持自定义接入:

Bridge Mode:将浏览器或任意客户端桥接到独立 AI 推理进程,适合 WebView、Electron、跨语言客户端资料来源：packages/web-integration/package.json:1-60。
Recorder 数据模型:@midscene/shared 暴露统一的 MidsceneRecorderEvent、MidsceneRecorderTarget、MidsceneRecorderGeneratedCode 等类型,涵盖 click、drag、scroll、input、navigation、setViewport、keydown 等事件,并支持 web / android / ios / computer / harmony 等平台 ID 资料来源：packages/shared/src/recorder.ts:1-80。这使得任何实现了 recorder 协议的工具都能被纳入 Midscene 生态。
Chrome 扩展:apps/chrome-extension 内的 recorder 工具(例如 utils.ts 中的 Mermaid mindmap 生成逻辑)展示了如何把浏览器操作转为可回放、可文档化的脚本资料来源：apps/chrome-extension/src/extension/recorder/utils.ts:1-40。
社区 SDK:Awesome Midscene 列出 iOS Mirror、PC 设备、Python、Java 等第三方绑定,共同构成多语言生态。

针对#179中"视口外元素"的诉求,RAG 增强(#426)通常与自定义接口结合:将产品领域知识注入上层 Agent,使 AI 在跨平台执行时能更好地理解长表单、滚动加载等场景。

flowchart LR
  Core["@midscene/core<br/>(device 抽象)"] --> Web["@midscene/web<br/>(Playwright/Puppeteer/Bridge)"]
  Core --> Android["@midscene/android"]
  Core --> iOS["@midscene/ios"]
  Core --> Harmony["@midscene/harmony + MCP"]
  Core --> Computer["@midscene/computer"]
  Core --> Shared["@midscene/shared<br/>(recorder/keyboard)"]
  Web --> Bridge["bridge-mode<br/>(跨进程)"]
  Shared --> Chrome["Chrome Extension Recorder"]
  Shared --> Community["PC / iOS Mirror / Python / Java"]

开发者工具、扩展能力与运维

Midscene 是一套面向 UI 自动化的多模态 AI 引擎,以"截图即操作"为核心抽象,通过 monorepo 组织多个 npm 子包,并以 CLI、Chrome 扩展、MCP 服务器、录制器与 Visualizer 等组件支撑开发、调试与运维全流程。本页围绕社区关注的扩展诉求(RAG、视口外元素定位、PC 与鸿蒙平台支持、AI 步骤导出为 Playwright 脚本等...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

包结构与命令行入口

仓库采用 pnpm 工作区管理多个独立发布的子包,核心能力按平台与职责拆分:

包名	角色	关键依赖/入口
`@midscene/cli`	命令行聚合入口,统一调度各平台驱动	依赖 `@midscene/web`、`@midscene/android`、`@midscene/ios`、`@midscene/harmony`、`@midscene/computer`、`@midscene/core`、`@midscene/shared`;通过 `bin.midscene` 暴露可执行命令
`@midscene/core`	核心抽象:AI 设备、树结构、模型路由、YAML 播放器	`exports` 暴露 `./utils`、`./ai-model`、`./tree`、`./device` 等子路径
`@midscene/web`	Playwright/Puppeteer 集成、Bridge 模式	暴露 `./bridge-mode`、`./bridge-mode-browser`、`./ui-utils` 入口
`@midscene/ios`	iOS 模拟器自动化 + MCP Server 子入口	`bin.midscene-ios` 与 `./mcp-server` 导出
`@midscene/computer-mac`	macOS 桌面自动化运行时	仅依赖 `@midscene/computer`
`@midscene/harmony-mcp`	鸿蒙 MCP 集成	依赖 `@modelcontextprotocol/[email protected]`

@midscene/cli 在 package.json 中以 workspace:* 引用所有平台驱动,并通过 "bin": { "midscene": "./bin/midscene" } 提供统一 CLI,使得一次安装即可对任意平台发起操作。资料来源:packages/cli/package.json:1-31。

@midscene/core 是所有上层包的依赖底座,其 exports 字段按子路径分发,便于 CLI、Chrome 扩展与第三方 SDK 按需引用,避免打包冗余。资料来源:packages/core/package.json:1-46。

@midscene/web 在 exports 中额外声明 Bridge 模式相关子路径,这是社区 Issue #2240 建议的"导出 Playwright 脚本"功能落地的关键依赖:录制产物可直接复用 Web 集成侧的桥接与代码生成能力。资料来源:packages/web-integration/package.json:1-46。

Chrome 扩展与录制器

Chrome 扩展(apps/chrome-extension)是开发者最常用的录制入口,负责捕获用户在浏览器中的操作,并在结束时生成结构化的会话描述、可视化思维导图与可回放的测试脚本。扩展内部将采集到的会话数据序列化为 JSON,再驱动大模型生成 Mermaid 思维导图,要求保留完整的事件顺序、页面流转与输入值,不允许缩写或截断,以确保回放与交接的完整性。资料来源:apps/chrome-extension/src/extension/recorder/utils.ts:1-19。

底层数据结构由 @midscene/shared 统一定义,核心类型包括:

MidsceneRecorderTarget:描述一次录制目标(平台 ID、设备 ID、标签、键值参数);
MidsceneRecorderGeneratedCode:录制产物,可同时输出 Markdown、YAML 与 Playwright 三种脚本,以及更新时间戳;
MidsceneRecorderMarkdownScreenshotAsset:截图资产元数据,关联事件索引、哈希、相对路径、MIME 类型与 base64 数据;
DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS = 20:控制单次录制嵌入 Markdown 的截图上限,避免文档膨胀。

这些类型被 CLI、Visualizer 与第三方 SDK 共享,确保"录—存—放—生成"流水线各阶段对同一事件有统一理解。社区 Issue #2240 关注的 Playwright 脚本导出正是基于 MidsceneRecorderGeneratedCode.playwright 字段在 UI 层提供一键导出。资料来源:packages/shared/src/recorder.ts:1-31。

此外,@midscene/shared 还导出 US 键盘布局与 transformHotkeyInput 等工具函数,负责将自然语言中的快捷键(如 page down、ctrl a)映射到具体的键码定义,支撑跨平台快捷键操作的语义一致性,这也是后续 RAG(Issue #426)中"理解产品领域快捷键"诉求的基础设施。资料来源:packages/shared/src/us-keyboard-layout.ts:1-15。

MCP 集成与跨平台扩展

社区 Issue #1594 关注的 HarmonyOS 自动化已通过 @midscene/harmony-mcp 进入路线图。该包在 devDependencies 中显式引入 @modelcontextprotocol/[email protected],并提供 @modelcontextprotocol/inspector 用于调试 MCP Server,意味着鸿蒙设备将以 MCP 协议对外暴露自动化能力,可被任意 MCP 客户端(如 Claude Desktop、Cursor)直接调用。资料来源:packages/harmony-mcp/package.json:1-8。

iOS 端同样提供 MCP 入口。@midscene/ios 在 exports 中声明 ./mcp-server 子路径,并通过 bin.midscene-ios 提供独立 CLI,使 iOS 模拟器自动化既可作为库调用,也可作为 MCP Server 独立部署。资料来源:packages/ios/package.json:1-35。

桌面端由 @midscene/computer 与平台绑定包(如 @midscene/computer-mac)协作。computer-mac 仅依赖 @midscene/computer,作为 macOS 平台的轻量运行时绑定;README 致谢的 libnut 提供跨平台原生键鼠控制,与社区项目 midscene-pc 共同覆盖 Windows、macOS 与 Linux(见 Issue #1389)。最新 v1.9.7 还修复了 libnut 滚动事件中 WHEEL_DELTA 的发送问题,以保证桌面端录制与回放的滚动手势一致性。资料来源:packages/computer-mac/package.json:1-15。

可视化与日常运维

根 README 将 Midscene 定位为面向 UI 测试的多模态 SDK,推荐接入 Playwright、Vitest 等既有测试体系,或通过 Skills / MCP 让 AI Agent 自治执行。Visualizer @midscene/visualizer 与 @midscene/shared 提供回放 UI、报告与断言可视化,是日常运维与回归分析的主要入口。资料来源:README.md:1-10。

@midscene/web 同时提供 Bridge 模式(./bridge-mode 与 ./bridge-mode-browser),允许将页面控制权移交至独立 Node 进程,便于在 CI、长任务或分布式执行环境中保持浏览器连接稳定,这也是社区在生产环境部署 Midscene 时常用的运维手段。资料来源:packages/web-integration/README.md:1-10。

针对社区反馈的两个痛点——"视口外元素的滚动定位"(Issue #179)与"AI 步骤导出为 Playwright 脚本"(Issue #2240)——前者依赖多模态模型对截图中长内容的理解,需要在 AI 设备层配合滚动策略;后者可直接复用 MidsceneRecorderGeneratedCode 中已有的 playwright 字段,在 CLI 或 Visualizer 中暴露一键导出即可落地。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models

可能增加新用户试用和生产接入成本。

medium 仓库名和安装名不一致

用户照着仓库名搜索包或照着包名找仓库时容易走错入口。

medium 来源证据：[Bug]: Raw \x1b[1A\x1b[2K ANSI escape sequences polluting logs in non-TTY / Kubernetes Pod environment

可能增加新用户试用和生产接入成本。

medium 来源证据：Bridge 模式下 fileChooserAccept 报错 -32000 Not allowed

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：web-infra-dev/midscene

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models。

1. 配置坑 · 来源证据：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/web-infra-dev/midscene/issues/2063 | 来源类型 github_issue 暴露的待验证使用条件。

2. 身份坑 · 仓库名和安装名不一致

严重度：medium
证据强度：runtime_trace
发现：仓库名 midscene 与安装入口 @midscene/web 不完全一致。
对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
复现命令：npm install @midscene/web
证据：identity.distribution | https://github.com/web-infra-dev/midscene | repo=midscene; install=@midscene/web

3. 安装坑 · 来源证据：[Bug]: Raw \x1b[1A\x1b[2K ANSI escape sequences polluting logs in non-TTY / Kubernetes Pod environment

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Raw \x1b[1A\x1b[2K ANSI escape sequences polluting logs in non-TTY / Kubernetes Pod environment
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/web-infra-dev/midscene/issues/2689 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：Bridge 模式下 fileChooserAccept 报错 -32000 Not allowed

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bridge 模式下 fileChooserAccept 报错 -32000 Not allowed
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/web-infra-dev/midscene/issues/2691 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

5. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/web-infra-dev/midscene | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/web-infra-dev/midscene | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/web-infra-dev/midscene | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/web-infra-dev/midscene | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/web-infra-dev/midscene | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/web-infra-dev/midscene | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

midscene 项目

项目概览与整体架构

一、项目定位与核心价值

二、仓库结构与包划分

三、核心架构与数据流

四、平台支持与集成方式

五、社区生态与已知限制

See Also

核心引擎:Agent、多模态模型与 AI 工作流

一、核心引擎的定位与设计哲学

二、Agent 工作流与任务模型

三、多模态模型与平台适配

四、录制器与工作流代码生成

五、典型失败模式与建议

See Also

平台集成:Web、Mobile、桌面与自定义接口

概览

Web 平台集成

Mobile 平台集成

桌面与 Computer 集成

自定义接口与生态扩展

See Also

开发者工具、扩展能力与运维

概述

包结构与命令行入口

Chrome 扩展与录制器

MCP 集成与跨平台扩展

可视化与日常运维

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 配置坑 · 来源证据：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models

2. 身份坑 · 仓库名和安装名不一致

3. 安装坑 · 来源证据：[Bug]: Raw \x1b[1A\x1b[2K ANSI escape sequences polluting logs in non-TTY / Kubernetes Pod environment

4. 配置坑 · 来源证据：Bridge 模式下 fileChooserAccept 报错 -32000 Not allowed

5. 能力坑 · 能力判断依赖假设

6. 维护坑 · 维护活跃度未知

8. 安全/权限坑 · 存在评分风险

9. 维护坑 · issue/PR 响应质量未知

10. 维护坑 · 发布节奏不明确