Add DeepResearch docs.

Author: baixiaokuang

docs/00DeepResearchOutline.md

@@ -0,0 +1,89 @@
+## 2. The Electron Runtime and Process Architecture
+
+To describe VS Code simply as an "Electron App" is to understate the complexity of its runtime environment. While it relies on Electron to bridge the gap between web technologies (Chromium) and the underlying operating system (Node.js), VS Code implements a highly specialized process model that mitigates the common pitfalls of Electron—namely, memory bloat and UI freezing.
+
+### 2.1 The Multi-Process Model
+
+The architecture of VS Code is fundamentally multi-process. This design mimics the architecture of a modern web browser, where tabs are isolated from one another to prevent a single page crash from bringing down the entire browser. In VS Code, this isolation is applied to the functional components of the IDE.1
+
+The application is composed of the following primary processes:
+
+| **Process Type**      | **Cardinality**  | **Primary Responsibility**                                                                    | **Execution Context**                      |
+| --------------------- | ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| **Main Process**      | Singleton        | Application Lifecycle, Window Management, Native Menus, Update Orchestration, IPC Routing.    | Full Node.js + Electron Main API           |
+| **Renderer Process**  | One per Window   | UI Rendering (DOM), Layout, Theme Application, User Input Capture.                            | Sandboxed (No direct Node.js access)       |
+| **Extension Host**    | One per Window\* | Execution of Extension Logic, API Implementation, File System Operations.                     | Full Node.js (Isolated)                    |
+| **Shared Process**    | Singleton        | Cross-Window Coordination, Extension Management (Install/Uninstall), Telemetry, Auto-Updates. | Full Node.js                               |
+| **Pty Host**          | Singleton        | Terminal Shell Management, Process Forking (bash, zsh, powershell).                           | Full Node.js + Native Modules (`node-pty`) |
+| **Utility Processes** | Dynamic          | File Watching, Search Indexing, Language Servers.                                             | Task Specific                              |
+
+_\*Note: In remote development scenarios (SSH, WSL, Containers), the Extension Host runs on the remote environment, physically separating the logic from the UI._
+
+### 2.2 The Main Process: The Orchestrator
+
+The `main.js` entry point initializes the **Main Process**. Its role is strictly managerial. It does not perform heavy computation. Instead, it acts as the traffic controller for the application. When a user launches VS Code, the Main Process is responsible for parsing command-line arguments, reading the global configuration, and spawning the first Renderer Process to display the workbench.1
+
+A critical function of the Main Process is window management via the `BrowserWindow` API. Each editor window is a separate instance of `BrowserWindow`. The Main Process tracks the state of these windows, manages the native application menu (which is distinct from the HTML-based menus inside the window), and handles global events like "Open File" when the application is triggered from the OS file explorer.
+
+### 2.3 The Renderer Process and The Sandbox
+
+Historically, Electron applications allowed Renderer processes (the web pages) to access Node.js APIs directly. This was known as "Node Integration." While convenient, it posed significant security and performance risks. A malicious extension or a compromised dependency could execute arbitrary code directly from the UI thread, and synchronous file I/O could block the painting of the screen.
+
+VS Code has aggressively migrated to a **Sandboxed Renderer** architecture.4 In this model:
+
+1. **No Node Integration:** The Renderer process cannot require Node.js modules like `fs` (file system) or `child_process`. It is a pure web environment.
+
+2. **Context Isolation:** The JavaScript context of the application (VS Code core) is isolated from the context of the preload scripts. This prevents "prototype pollution" attacks where malicious code modifies global objects to hijack application behavior.5
+
+3. **IPC Bridging:** To perform system operations (like reading a file to display it), the Renderer must communicate with the Main Process or the Extension Host via Inter-Process Communication (IPC).
+
+This architectural shift forces a strict separation of concerns. The Renderer is responsible _only_ for the View. It receives a model (text, decorations, list items) and renders it. It captures user intent (keystrokes, clicks) and forwards them to the logic layer. This ensures that the UI remains responsive at 60 frames per second (FPS), even if the disk is slow or the extension host is busy.6
+
+### 2.4 The Extension Host: Performance Isolation
+
+The **Extension Host** is the crown jewel of VS Code's stability. In many legacy editors (e.g., Eclipse, older versions of Atom), extensions or plugins ran in the same thread as the UI. If a plugin entered an infinite loop or performed a heavy synchronous operation (like parsing a large XML file), the entire editor would freeze.
+
+In VS Code, extensions are loaded into a separate Node.js process—the Extension Host.
+
+- **Isolation:** If an extension crashes, the Extension Host process terminates, but the VS Code window (Renderer) remains open and responsive. The user can save their work (cached in the Renderer) and restart the extension host without losing data.7
+
+- **Asynchronous Communication:** All communication between the Extension Host and the Renderer is asynchronous. When an extension wants to show a notification, it sends a JSON-RPC message. The Renderer acknowledges receipt and renders the notification when it processes its next frame. The extension continues execution without waiting for the pixels to be drawn.3
+
+**The "Remote" Benefit:** This separation enabled the "Remote Development" architecture with almost no changes to the extension API. Because the Extension Host is already a separate process communicating via IPC, moving that process to a different machine (connected via SSH) and tunneling the IPC messages over a socket was a natural architectural evolution. The extension API remains identical; the extension "thinks" it is running locally, accessing the "local" (remote) file system, while the UI runs on the client.9
+
+### 2.5 The Shared Process
+
+The **Shared Process** solves the problem of state duplication. If a user has ten VS Code windows open, it is inefficient to have ten separate processes checking for updates or ten separate telemetry reporters. The Shared Process is a hidden window (or a utility process in newer Electron versions) that handles these singleton responsibilities. It ensures that operations affecting the global application state are serialized and managed centrally.
+
+### 2.6 Code-Level Map (Where the Processes Start)
+
+- **Main bootstrap:** `src/vs/code/electron-main/main.ts` is the first TypeScript entry. It sets a global error handler, parses CLI args, builds the main service collection, enforces the single-instance lock via `claimInstance`, and then hands control to `CodeApplication.startup()`.
+- **App orchestration:** `src/vs/code/electron-main/app.ts` hosts `CodeApplication`, which configures Electron session security (permission handler, context isolation defaults), registers `validatedIpcMain` listeners, and wires all top-level services (logging, telemetry, protocol handlers, URL handling, lifecycle). It resolves `IWindowsMainService` and is the only place that creates `BrowserWindow` instances for workbench windows.
+- **Renderer boot:** `WindowsMainService` (`src/vs/platform/windows/electron-main/windowsMainService.ts`) constructs windows pointing at `src/vs/code/electron-browser/workbench/workbench.html`, passing an `INativeWindowConfiguration` blob. The renderer script `src/vs/code/electron-browser/workbench/workbench.ts` runs in a sandboxed page, pulls the preload-provided `window.vscode` globals, and delegates to `DesktopMain` in `src/vs/workbench/electron-browser/desktop.main.ts` to compose workbench services and start the UI.
+- **Preload + sandbox boundary:** The renderer code assumes no Node integration; all privileged access flows through IPC channels exposed by the preload (defined in `src/vs/base/parts/sandbox/electron-browser/globals.ts`) and the typed `MainProcessService` bridge.
+
+### 2.7 Shared Process (Implementation Details)
+
+- **Process creation:** `SharedProcess` in `src/vs/platform/sharedProcess/electron-main/sharedProcess.ts` waits for the first window connection, then spawns an Electron `UtilityProcess` with entry `vs/code/electron-utility/sharedProcess/sharedProcessMain`. It uses `SharedProcessLifecycle` messages to gate IPC (`ipcReady`, `initDone`) and forwards crash notifications back to windows.
+- **Singleton services:** The utility entry `src/vs/code/electron-utility/sharedProcess/sharedProcessMain.ts` constructs a full service container (extension gallery/management, telemetry, user data sync, tunnel service, loggers, policy) and exposes them via `UtilityProcessMessagePortServer`.
+- **Window connection:** Renderers connect lazily through `SharedProcessService` (`src/vs/workbench/services/sharedProcess/electron-browser/sharedProcessService.ts`), which waits for the workbench `Restored` phase before calling `acquirePort(SharedProcessChannelConnection)` to get a `MessagePort` into the shared process.
+
+### 2.8 Extension Host Utility Processes
+
+- **Spawner:** `ExtensionHostStarter` in `src/vs/platform/extensions/electron-main/extensionHostStarter.ts` creates per-window extension host processes via `WindowUtilityProcess`. Each host loads `vs/workbench/api/node/extensionHostProcess` with correlation ids, forwards stdout/stderr to the main log service, and is tied into `ILifecycleMainService` so shutdown waits for a graceful exit (with a force-kill fallback).
+- **IPC shape:** The `WindowUtilityProcess` abstraction (see `src/vs/platform/utilityProcess/electron-main/utilityProcess.ts`) wraps Electron utility processes, returning `MessagePort` connections that the renderer’s extension service speaks JSON-RPC over. Inspect/debug flags are passed through `execArgv` when `--inspect-extensions` is set.
+
+### 2.9 Pty Host and Other Worker Processes
+
+- **Terminal backend:** `ElectronPtyHostStarter` (`src/vs/platform/terminal/electron-main/electronPtyHostStarter.ts`) starts a `UtilityProcess` with entry `vs/platform/terminal/node/ptyHostMain` and publishes a `MessagePort` when the renderer sends `vscode:createPtyHostMessageChannel`. Environment flags (`VSCODE_RECONNECT_*`) and optional debug ports are injected before spawn.
+- **UtilityProcess contract:** The shared `UtilityProcess` class (`src/vs/platform/utilityProcess/electron-main/utilityProcess.ts`) centralizes spawn, stdout/stderr streaming, crash reporting, lifecycle binding to windows/parent PID, and optional auth proxying. This is reused for shared process, extension hosts, pty host, and other background workers (search/file watching/language services).
+
+### 2.10 IPC Surfaces from the Renderer
+
+- **Main-process bridge:** `ElectronIPCMainProcessService` in `src/vs/platform/ipc/electron-browser/mainProcessService.ts` exposes typed channels backed by `validatedIpcMain` handlers registered in `app.ts`. Renderer services call into the main process through these channels instead of touching Node APIs directly.
+- **Shared-process bridge:** `SharedProcessService` (above) handles message-port IPC to the singleton worker. Both bridges enforce context isolation by keeping all privileged work off the DOM thread and serializing data across process boundaries.
+
+### 2.11 Lifecycle and Single-Instance Guards
+
+- **Locking and exit:** `main.ts` writes a lockfile (`environmentMainService.mainLockfile`) after successfully owning the Node IPC handle; if another instance holds it, the process exits early. `CodeApplication` registers lifecycle listeners that dispose services and remove the lockfile on shutdown.
+- **Crash signaling:** Shared-process crashes trigger `onDidCrash` in `SharedProcess` (`src/vs/platform/sharedProcess/electron-main/sharedProcess.ts`), which then notifies focused windows via `windowsMainService.sendToFocused('vscode:reportSharedProcessCrash')`, keeping failures isolated while leaving the UI responsive.