chrome-extensions

Google Chrome Extension Management Manual

Applies to: Windows desktop Chrome | Updated: 2026-03-14

1. Core Principles

The page must be chrome://extensions/, and the browser must remain maximized
Browser Assist Locator is only responsible for locating, not for performing clicks / input / scrolling
The final coordinate mapping is completed by the daemon; the actual actions are performed by agent-computer executes
If the extension behaves abnormally after its code is updated, first click Update
Troubleshooting order: daemon → status → extension loading → foreground browser → locate

2. Main Usage Workflows

The following workflows cover most actual usage scenarios of this application.

Main Workflow A: Managing installed extensions

Visit chrome://extensions/
Enter keywords in the search box to filter the extension list in real time
Click the extension toggle to enable or disable it (blue = enabled, gray = disabled)
To view details, click Details (version, permissions, incognito mode)
To uninstall, click Remove → confirmation dialog

Main Workflow B: Loading a local extension

Visit chrome://extensions/
Enable Developer mode in the upper-right corner (1890, 180)
Click Load unpacked (100, 250) → a folder picker appears
Select the extension root directory → click "Select Folder"

Main Workflow C: Updating extensions

Confirm that chrome://extensions/ Developer mode is enabled
Click Update (450, 250)
Wait for the lower-left Updating... to disappear; the update is complete

Main Workflow D: Setting shortcuts

Visit chrome://extensions/
Click Keyboard shortcuts in the left navigation
Find the target extension, click Not set
Press the target key combination to complete the binding

Main Workflow E: Complete Browser Assist Locator usage workflow

Step 1: Start the daemon and confirm its status

.\windows-launcher.ps1 daemon start
.\windows-launcher.ps1 browser-assist-status

When the daemon is normal but the extension is not connected, it returns "connected": false, which is normal; just continue loading the extension.

Step 2: Load the extension (choose one of two options)

Method A — Load the source directory directly:

chrome://extensions/ → enable Developer mode (1890, 180)
Load unpacked (100, 250) → select extensions/browser-assist-locator → select folder

Method B — Package first, then load:

.\scripts\package_browser_assist_extension.ps1

The artifact is located at artifacts/browser-assist-locator-package/browser-assist-locator, then load that directory following the Method A workflow.

Step 3: Confirm a successful connection

.\windows-launcher.ps1 browser-assist-status

On success, it returns connected: true + extensionVersion / browserName / lastSeenAt。

Step 4: Open the target page and keep it in the foreground

.\windows-launcher.ps1 browser-open-url --url "<目标 URL>"

Browser Assist v1 verifies whether the foreground window is a browser and whether the URL / title match; the browser must remain in the foreground before executing locate.

Step 5: Initiate a locate request

.\windows-launcher.ps1 browser-assist-locate --input-file .\docs\examples\browser-assist-request.json

Example request body:

{
  "query": {
    "text": "收藏",
    "role": "button",
    "hint": "当前职位详情区域里的收藏按钮",
    "selectorHint": null,
    "index": 0
  },
  "options": {
    "visibleOnly": true,
    "interactiveOnly": true,
    "maxCandidates": 5
  }
}

Step 6: Read the returned result and perform the click

Key fields of the returned structure:

matches[].rect — the DOM geometric box within the web page viewport
matches[].clickablePoint — the click point inside the web page
browser.contentLeftOnScreen / contentTopOnScreen — the content area anchor
mapped.screenCandidates[].screenPoint — the desktop absolute coordinates after daemon mapping (use this）

.\windows-launcher.ps1 click --x <screen_x> --y <screen_y>

Step 7: Screenshot verification

.\windows-launcher.ps1 capture-grid --grid-size 50

Main Workflow F: Ending Browser Assist Locator usage

Keep the extension: just return to the extensions page and turn off the toggle
Completely uninstall: click Remove on the extensions page
Stop the backend：.\windows-launcher.ps1 daemon stop(After the daemon stops, the extension still exists but is in a disconnected state)

3. Stable Rules

3.1 Routes / Pages / Modules

Extension management home page:chrome://extensions/
Keyboard shortcuts configuration page:chrome://extensions/shortcuts(or enter via Keyboard shortcuts in the left navigation on the home page)
Chrome Web Store: Chrome Web Store link at the bottom left of the home page

3.2 Parameters / States / Business Semantics

Only after Developer mode is enabled do the three buttons Load unpacked / Pack extension / Update appear in the upper left corner
Extension toggle: blue = on; gray = off
browser-assist-status Returning "connected": false does not indicate an anomaly; it only means the extension has not yet loaded
browser-assist-status Returning connected: true synchronously returns extensionVersion / browserName / lastSeenAt
After the daemon stops, the extension still exists but is in a disconnected state

3.3 Browser Assist Locator Responsibility Boundaries

Responsible for: finding web page elements, returning page / viewport / browser / matches, returning element rect and clickablePoint
Not responsible for: clicking, typing, scrolling, browser automation execution

Link summary:

扩展页加载 → 扩展连接 daemon → status 显示 connected:true
→ locate 返回 raw+mapped → agent-computer click 执行真实动作

The extension is responsible for locating, the daemon is responsible for mapping, and computer is responsible for execution.

3.4 Judgment Criteria

Directly pass：browser-assist-status Returning connected: true → locate can be initiated directly
Conditionally pass: returning connected: false → first complete the extension loading process, then reconfirm the state
Directly skip: when element locating is not needed, there is no need to start the daemon or load the extension

4. UI / Coordinates / Page Mapping

4.1 Page Areas

Top search box: filters the list of installed extensions in real time
Developer mode toggle in the upper right corner: after enabling, unlocks Load unpacked / Pack extension / Update
Developer button area in the upper left corner: Load unpacked · Pack extension · Update (visible only after Developer mode is enabled)
Extension card area: each card contains an extension toggle, Details, and Remove
Left navigation: Keyboard shortcuts entry
Bottom left corner: Chrome Web Store link

4.2 Key Controls / Coordinates

Coordinates are valid when the browser is maximized + chrome://extensions/ ; they will drift when the window size, system scaling, or browser zoom changes.

Element	Coordinates / Position	Description
Developer mode toggle	`(1890, 180)`	Upper right corner; must be enabled first to use the developer buttons
Load unpacked	`(100, 250)`	Upper left corner; visible after Developer mode is enabled
Update	`(450, 250)`	Upper left corner; visible after Developer mode is enabled
Pack extension	Upper left corner	Visible after Developer mode is enabled; click to open the packaging dialog

4.3 Feedback Mapping

Action	Expected Feedback	Meaning	Next Step
Enter keywords in the search box	Extension list filters in real time	Filtering takes effect	Operate after finding the target extension
Click the extension toggle	Blue ↔ Gray toggle	Enable / disable extension	Continue as needed
Click Details	Enter the details page	View version, permissions, incognito mode	Return to the home page after viewing
Click Remove	A confirmation dialog pops up	Wait for confirmation, then uninstall	Confirm the dialog to complete uninstallation
Enable Developer mode	Three developer buttons appear in the top-left corner	Developer features unlocked	Load unpacked / Update can be used
Click Load unpacked	A folder selector pops up	Wait to select a local directory	Confirm after selecting the extension root directory
Click Update	Appears in the bottom-left corner `Updating...`	Reloading all extensions	Wait for the prompt to disappear
`browser-assist-status` Return `connected: true`	Includes `extensionVersion` / `browserName` / `lastSeenAt`	The extension has successfully connected to the daemon	A locate request can be initiated
`browser-assist-locate` Return result	Contains `matches` / `mapped.screenCandidates`	Element location completed	Take `screenPoint` execute click

5. Shortcuts

None for now (the Chrome extension management page itself has no dedicated shortcuts; extension shortcuts are configured on the Keyboard shortcuts page)

6. Common failures and troubleshooting

Troubleshooting priority order

.\windows-launcher.ps1 daemon start
.\windows-launcher.ps1 browser-assist-status
Confirm the extension is loaded and the toggle is on
Confirm the browser is the foreground window
Confirm the current URL is the target page
Click Update to refresh the extension
Run again browser-assist-locate

Symptom:`browser-assist-status` returns `connected: false`

Possible causes:
- The extension has not been loaded into Chrome
- The extension is loaded but the toggle is off
Check first:
1. chrome://extensions/ Whether Browser Assist Locator exists in and the toggle is blue
2. Whether the daemon has started normally
How to handle:
- Follow step 2 of main flow E to load the extension, or turn on the extension toggle; if the daemon is not started, first run daemon start

Symptom: the extension behaves abnormally after loading / functions do not match expectations

Possible causes:
- The local extension code has been updated, but Chrome is still loading the old version
Check first:
1. Whether the extension source code was just modified
How to handle:
- chrome://extensions/ → Confirm Developer mode is enabled → Click Update (450, 250) → Wait for Updating... to disappear

Symptom: locate request errors / no matching results

Possible causes:
- The browser is not in the foreground, or the current page URL / title does not match the target
- The target element is not visible or not interactive
Check first:
1. Whether the browser window is the current foreground window
2. Whether the current page URL is the target page
3. In the request body visibleOnly / interactiveOnly Whether the target element was filtered out
How to handle:
- Run browser-open-url Bring the browser to the foreground; check whether the filter conditions in the request body are too strict

Symptom: coordinate click offset / target control not hit

Possible causes:
- The browser is not maximized, or the system zoom / browser zoom has changed
Check first:
1. Whether the browser is maximized
2. Whether the system zoom ratio has changed
Handling method:
- Re-maximize the browser; if it is still offset, use the mapped.screenCandidates[].screenPoint returned by locate as the standard, and do not use hard-coded coordinates

7. Self-Improving

When the following situations occur during execution, an additional record needs to be appended to references/self-improving.md：

The original process cannot cover the actual high-frequency usage path
A new failure mode was confirmed during troubleshooting
A more stable and efficient execution method was discovered
New facts worth preserving were discovered

Execution requirements:

It is forbidden to directly modify this SKILL.md body content
Only new content is allowed to be appended to references/self-improving.md
Append only, do not overwrite, do not delete historical records
Only observed facts are recorded here, not inferences, not guesses

For the writing format, strictly use references/self-improving-template.md the template provided in