Update project structure and dependencies; add architecture documentation and improve build scripts. Introduce new versioning and permissions for enhanced functionality.

2026-09-22 03:10:43 +08:00 · 2026-08-06 15:11:35 +08:00
parent c8380de521
commit 0371a8b802
113 changed files with 15944 additions and 6556 deletions
@@ -0,0 +1,25 @@
+# Yakit Browser Agent Native Host
+
+The Native Host is a small stdio-to-loopback-WebSocket transport. It does not store pairing credentials and does not execute browser commands itself. It forwards the normal Bridge v3 server challenge and extension authentication messages; Yak validates the origin-bound paired device signature and returns the engine identity, engine instance, connection, session, task, grant, protocol, and capability identity.
+
+Build from the Yak repository:
+
+```bash
+go build -o yakit-browser-agent-host ./common/browser/nativehostcmd
+```
+
+Install for Linux or macOS, using the ID shown by `chrome://extensions` for an unpacked build:
+
+```bash
+./native-host/install.sh \
+  --host-binary /absolute/path/to/yakit-browser-agent-host \
+  --extension-id YOUR_CHROME_EXTENSION_ID
+```
+
+On Windows, run PowerShell without administrator privileges:
+
+```powershell
+.\native-host\install.ps1 -HostBinary C:\path\yakit-browser-agent-host.exe -ExtensionId YOUR_CHROME_EXTENSION_ID
+```
+
+The installer registers Chrome, Chromium, Edge, Brave, and Firefox per-user locations. Chrome supplies its extension origin to the host. Firefox supplies the Native Host manifest path and add-on ID; the host verifies that ID against `allowed_extensions` before deriving its Bridge origin. It writes only the loopback endpoint to the user configuration directory. Run with `--uninstall` on POSIX or `-Uninstall` on Windows to remove the registrations; uninstall does not require an extension ID. When Chrome runs on Windows and development runs in WSL, build/install the Windows host with `install.ps1`; a Linux Native Host cannot be launched by Windows Chrome.
@@ -0,0 +1,71 @@
+param(
+  [string]$ExtensionId = "",
+  [string]$HostBinary = "yakit-browser-agent-host.exe",
+  [string]$FirefoxId = "[email protected]",
+  [string]$Endpoint = "ws://127.0.0.1:64333/extension",
+  [switch]$Uninstall
+)
+
+$ErrorActionPreference = "Stop"
+$Utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+$HostName = "com.yaklang.browser_agent"
+$InstallRoot = Join-Path $env:LOCALAPPDATA "Yakit\BrowserAgent"
+$ConfigRoot = Join-Path $env:APPDATA "yakit"
+$ManifestPath = Join-Path $InstallRoot "$HostName.json"
+$RegistryTargets = @(
+  "HKCU:\Software\Google\Chrome\NativeMessagingHosts\$HostName",
+  "HKCU:\Software\Chromium\NativeMessagingHosts\$HostName",
+  "HKCU:\Software\Microsoft\Edge\NativeMessagingHosts\$HostName",
+  "HKCU:\Software\BraveSoftware\Brave-Browser\NativeMessagingHosts\$HostName",
+  "HKCU:\Software\Mozilla\NativeMessagingHosts\$HostName"
+)
+
+function Write-JsonFile {
+  param([Parameter(Mandatory = $true)][string]$Path, [Parameter(Mandatory = $true)][object]$Value)
+  [System.IO.File]::WriteAllText($Path, ($Value | ConvertTo-Json -Depth 4), $script:Utf8NoBom)
+}
+
+if ($Uninstall) {
+  foreach ($Target in $RegistryTargets) { Remove-Item $Target -Recurse -Force -ErrorAction SilentlyContinue }
+  Remove-Item $InstallRoot -Recurse -Force -ErrorAction SilentlyContinue
+  Remove-Item (Join-Path $ConfigRoot "browser-agent-native-host.json") -Force -ErrorAction SilentlyContinue
+  Write-Host "Removed $HostName."
+  exit 0
+}
+
+if ($Endpoint -notmatch '^wss?://(127\.0\.0\.1|localhost|\[::1\])(:[0-9]+)?/') {
+  throw "Endpoint must use ws:// or wss:// with an explicit loopback host."
+}
+if ([string]::IsNullOrWhiteSpace($ExtensionId)) {
+  throw "ExtensionId is required when installing the Native Host."
+}
+$ResolvedBinary = (Resolve-Path $HostBinary).Path
+New-Item $InstallRoot -ItemType Directory -Force | Out-Null
+New-Item $ConfigRoot -ItemType Directory -Force | Out-Null
+$InstalledBinary = Join-Path $InstallRoot "yakit-browser-agent-host.exe"
+Copy-Item $ResolvedBinary $InstalledBinary -Force
+Write-JsonFile -Path (Join-Path $ConfigRoot "browser-agent-native-host.json") -Value @{ endpoint = $Endpoint }
+
+Write-JsonFile -Path $ManifestPath -Value @{
+  name = $HostName
+  description = "Yakit Browser Agent Native Host"
+  path = $InstalledBinary
+  type = "stdio"
+  allowed_origins = @("chrome-extension://$ExtensionId/")
+}
+
+$FirefoxManifestPath = Join-Path $InstallRoot "$HostName.firefox.json"
+Write-JsonFile -Path $FirefoxManifestPath -Value @{
+  name = $HostName
+  description = "Yakit Browser Agent Native Host"
+  path = $InstalledBinary
+  type = "stdio"
+  allowed_extensions = @($FirefoxId)
+}
+
+foreach ($Target in $RegistryTargets) {
+  New-Item $Target -Force | Out-Null
+  $Value = if ($Target -like "*Mozilla*") { $FirefoxManifestPath } else { $ManifestPath }
+  Set-Item $Target -Value $Value
+}
+Write-Host "Installed $HostName at $InstalledBinary"
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+host_name="com.yaklang.browser_agent"
+host_binary=""
+extension_id=""
+firefox_id="[email protected]"
+endpoint="ws://127.0.0.1:64333/extension"
+uninstall=false
+
+usage() {
+  printf '%s\n' "Usage: $0 --extension-id ID [--host-binary PATH] [--endpoint WS_URL] [--firefox-id ID] [--uninstall]"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --host-binary) host_binary="${2:-}"; shift 2 ;;
+    --extension-id) extension_id="${2:-}"; shift 2 ;;
+    --firefox-id) firefox_id="${2:-}"; shift 2 ;;
+    --endpoint) endpoint="${2:-}"; shift 2 ;;
+    --uninstall) uninstall=true; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf 'Unknown option: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+case "$(uname -s)" in
+  Darwin)
+    install_root="$HOME/Library/Application Support/Yakit/BrowserAgent"
+    config_root="$HOME/Library/Application Support/yakit"
+    chrome_roots=(
+      "$HOME/Library/Application Support/Google/Chrome/NativeMessagingHosts"
+      "$HOME/Library/Application Support/Chromium/NativeMessagingHosts"
+      "$HOME/Library/Application Support/Microsoft Edge/NativeMessagingHosts"
+      "$HOME/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts"
+    )
+    firefox_root="$HOME/Library/Application Support/Mozilla/NativeMessagingHosts"
+    ;;
+  Linux)
+    install_root="${XDG_DATA_HOME:-$HOME/.local/share}/yakit/browser-agent"
+    config_root="${XDG_CONFIG_HOME:-$HOME/.config}/yakit"
+    chrome_roots=(
+      "$HOME/.config/google-chrome/NativeMessagingHosts"
+      "$HOME/.config/chromium/NativeMessagingHosts"
+      "$HOME/.config/microsoft-edge/NativeMessagingHosts"
+      "$HOME/.config/BraveSoftware/Brave-Browser/NativeMessagingHosts"
+    )
+    firefox_root="$HOME/.mozilla/native-messaging-hosts"
+    ;;
+  *) printf 'Unsupported operating system. Use install.ps1 on Windows.\n' >&2; exit 1 ;;
+esac
+
+manifest_name="$host_name.json"
+if [[ "$uninstall" == true ]]; then
+  for directory in "${chrome_roots[@]}" "$firefox_root"; do rm -f "$directory/$manifest_name"; done
+  rm -f "$install_root/yakit-browser-agent-host" "$config_root/browser-agent-native-host.json"
+  printf 'Removed %s manifests and host binary.\n' "$host_name"
+  exit 0
+fi
+
+if [[ -z "$extension_id" ]]; then printf '%s\n' '--extension-id is required for Chrome/Chromium.' >&2; exit 2; fi
+if [[ -z "$host_binary" ]]; then host_binary="$(command -v yakit-browser-agent-host || true)"; fi
+if [[ -z "$host_binary" || ! -x "$host_binary" ]]; then
+  printf '%s\n' 'Host binary not found. Build it with: go build -o yakit-browser-agent-host ./common/browser/nativehostcmd' >&2
+  exit 1
+fi
+if [[ ! "$endpoint" =~ ^wss?://(127\.0\.0\.1|localhost|\[::1\])(:[0-9]+)?/ ]]; then
+  printf '%s\n' 'Endpoint must use ws:// or wss:// with an explicit loopback host.' >&2
+  exit 2
+fi
+
+mkdir -p "$install_root" "$config_root"
+install -m 0755 "$host_binary" "$install_root/yakit-browser-agent-host"
+printf '{"endpoint":"%s"}\n' "$endpoint" > "$config_root/browser-agent-native-host.json"
+
+for directory in "${chrome_roots[@]}"; do
+  mkdir -p "$directory"
+  printf '{\n  "name": "%s",\n  "description": "Yakit Browser Agent Native Host",\n  "path": "%s",\n  "type": "stdio",\n  "allowed_origins": ["chrome-extension://%s/"]\n}\n' \
+    "$host_name" "$install_root/yakit-browser-agent-host" "$extension_id" > "$directory/$manifest_name"
+done
+
+mkdir -p "$firefox_root"
+printf '{\n  "name": "%s",\n  "description": "Yakit Browser Agent Native Host",\n  "path": "%s",\n  "type": "stdio",\n  "allowed_extensions": ["%s"]\n}\n' \
+  "$host_name" "$install_root/yakit-browser-agent-host" "$firefox_id" > "$firefox_root/$manifest_name"
+
+printf 'Installed %s at %s\n' "$host_name" "$install_root/yakit-browser-agent-host"