{"owner":"yanue","repo":"V2rayU","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# V2rayU — Agent Guide\n\nmacOS menu-bar proxy client (Xray-core / sing-box). SwiftUI + GRDB. Targets: macOS 14+.\n\n## Targets & entrypoints\n\n| Target | Type | Entry | Deployment |\n|--------|------|-------|------------|\n| `V2rayU` | macOS app (LSUIElement) | `V2rayU/App/App.swift` — `@main struct V2rayUApp` | 14+ |\n| `V2rayUTool` | CLI (setuid helper) | `V2rayUTool/main.swift` — sets system proxy via SCPreferences | 11.5+ |\n| `V2rayUTests` | Test bundle | Swift Testing, host app = V2rayU.app | 14+ |\n\n## Key paths (defined in `V2rayU/App/App.swift:9-21`)\n\n- `AppHomePath` = `~/.V2rayU` — config, logs, DB, PAC files\n- `AppBinRoot` = `/usr/local/v2rayu` — core binaries + V2rayUTool + update scripts\n- `databasePath` = `~/.V2rayU/.V2rayU.db`\n- `v2rayUTool` = `/usr/local/v2rayu/V2rayUTool`\n- `coreApiPort` = 11111, `coreApiBaseUrl` = `http://127.0.0.1:11111`\n\n## Dependencies (SPM)\n\nGRDB 7.11+ (SQLite), KeyboardShortcuts 2.4+, Yams 6.2+ (YAML), FlyingFox 0.26+ (HTTP), Firebase 12.14+, AppCenter 5.12+.\n\n## Architecture\n\n- **App layer**: `V2rayU/App/` — `App.swift` (entry + AppDelegate), `AppMenu.swift` (menu bar), `AppSettings.swift`, `AppState.swift` (global singleton)\n- **Core layer**: `V2rayU/Core/`\n  - `Database/` — GRDB-based SQLite (`AppDatabase.shared`), entities, migrations, stores\n  - `Handlers/` — `V2rayLaunch.swift` (start/stop cores), `LaunchAgent.swift` (plist gen), `AppInstaller.swift`, `NetworkMonitor.swift`, `SleepManager.swift`, `CoreConfigHandler.swift` (JSON config gen for both cores), `Singbox/`, `V2ray/`\n  - `Protocols/` — Share URI parsing/generation, V2ray/SingBox JSON model structs\n  - `Services/` — `GithubService.swift` (releases API), `HttpServer.swift` (local PAC server via FlyingFox), `DownloadDelegate.swift`\n  - `Utilities/` — `CoreCapabilityRules.swift` (capability rule engine ~1171 lines), `CertFingerprintFetcher.swift`, `DnsResolver.swift`, `Port.swift`, `Shell.swift`, `Scanner.swift`, `Network.swift` (ping)\n- **Features layer**: `V2rayU/Features/` — Profile, Subscription, Routing, Share, PAC, Migration, Diagnostic, Update\n- **UI layer**: `V2rayU/UI/` — Components, Views, Windows\n\n## Run modes\n\n`RunMode` enum: `global`, `pac`, `manual`, `tun` (defined in `V2rayU/Core/Handlers/V2rayLaunch.swift:13`).\n\n## Core engine (V2rayLaunch)\n\nActor-based singleton in `V2rayU/Core/Handlers/V2rayLaunch.swift`. Flow: read DB profile → resolve core compatibility (capability rules) → generate config JSON → create LaunchAgent plist → launch daemon → wait for SOCKS port → set system proxy → (if TUN mode) create tun.json + start tun-helper LaunchDaemon.\n\n## Capability rules system\n\nTwo JSON rule files at `Build/capability-rules/`:\n- `xray-capability-rules.json` (456 lines) — per-protocol/transport/security support with version bounds\n- `singbox-capability-rules.json` (367 lines) — sing-box capabilities\n\nEngine: `V2rayU/Core/Utilities/CoreCapabilityRules.swift` (~1171 lines). Rules loaded from bundled JSON, evaluated at startup to decide which core to use + warn about incompatibilities.\n\n## Build & release\n\n```bash\n# Build universal binary + DMG\n./Build/build.sh\n\n# Install (run as root via app or manually)\n# Copies V2rayUTool, update scripts, core binaries to /usr/local/v2rayu/\n# Sets up LaunchDaemon + sudoers entries\n./Build/install.sh\n```\n\n`build.sh` flow: `xcodebuild archive` (arm64+x86_64) → copy .app → `appdmg` for DMG. Version extracted from `project.pbxproj` MARKETING_VERSION (currently 5.0.2).\n\n## Testing\n\nUses **Swift Testing** framework (not XCTest). Tests are host-app-dependent (TEST_HOST = V2rayU.app).\n\n```bash\n# Run all tests\nxcodebuild test -project V2rayU.xcodeproj -scheme V2rayU -destination 'platform=macOS'\n\n# Run compatibility test suite (needs pre-downloaded core binaries)\n./Build/tests/run-compatibility-test.sh          # requires binaries\n./Build/tests/run-compatibility-test.sh --download  # download first\n\n# Download core versions for testing (xray v1.8.0~v26.5.6, sing-box v1.12.0~v1.13.13)\npython3 Build/tests/download-cores.py\n# Or per-core:\npython3 Build/tests/download-cores.py --core xray\npython3 Build/tests/download-cores.py --core sing-box\n```\n\nTest config: `Build/tests/test-config.json` (`maxProfiles`, `sampleVersions`). Env: `V2RAYU_TEST_BIN_DIR`, `V2RAYU_TEST_REPORT_DIR`, `V2RAYU_MAX_PROFILES`, `V2RAYU_SAMPLE_VERSIONS`.\n\nCompatibility test report: `Build/tests/reports/compatibility-report-*.json`. Generate HTML: `python3 Build/tests/generate-report.py <report.json>`.\n\nTests read the **real DB** at `~/.V2rayU/.V2rayU.db` — profiles must exist.\n\n## Core update scripts (root, via sudoers)\n\n- `Build/update-xray.sh` — installed to `/usr/local/v2rayu/update-xray.sh`, called with sudo for xray-core updates\n- `Build/update-singbox.sh` — same path pattern\n- Both support backup + rollback on failure\n\n## Run-time paths\n\n- `~/.V2rayU/config.json` — active core config\n- `~/.V2rayU/tun.json` — TUN mode config (sing-box)\n- `~/.V2rayU/V2rayU.log` — app log\n- `~/.V2rayU/core.log` — core stderr/stdout\n- `~/.V2rayU/tun.log` — TUN helper log\n- `~/Library/LaunchAgents/yanue.v2rayu.sing-box.plist` / `yanue.v2rayu.xray-core.plist` — per-user LaunchAgents\n- `/Library/LaunchDaemons/yanue.v2rayu.tun-helper.plist` — system LaunchDaemon\n- `/private/etc/sudoers.d/v2rayu-sudoer` — sudoers entry for tun-helper + core updates\n\n## CRITICAL: Never delete DerivedData\n\n**NEVER** delete `~/Library/Developer/Xcode/DerivedData/`. This directory contains SPM package checkouts. Due to network restrictions (GFW), re-resolving SPM dependencies will fail. Use `xcodebuild clean build` (NOT `rm -rf DerivedData`) for clean builds. If DerivedData is corrupted, the user must manually re-resolve via Xcode or VPN.\n\n## Repository conventions\n\n- **No CI**, no linter/formatter config, no typecheck script\n- **Localization**: en, zh-Hans, zh-HK in `V2rayU/Localization/` (String Catalogs + Localizable.strings)\n- **TODO**: `TODO` file (Chinese, issues list) at repo root\n- **Branch/PR**: no established convention visible\n- **Docs are executable sources of truth** — `Docs/CoreCapabilityRules.md` documents the capability rules policy, `Docs/CompatibilityTestSystem.md` documents the test framework, `Docs/XrayReleaseFeatureAnalysis.md` is auto-generated by `Tools/analyze_xray_releases.py`\n"},"files":{"AGENTS.md":"# V2rayU — Agent Guide\n\nmacOS menu-bar proxy client (Xray-core / sing-box). SwiftUI + GRDB. Targets: macOS 14+.\n\n## Targets & entrypoints\n\n| Target | Type | Entry | Deployment |\n|--------|------|-------|------------|\n| `V2rayU` | macOS app (LSUIElement) | `V2rayU/App/App.swift` — `@main struct V2rayUApp` | 14+ |\n| `V2rayUTool` | CLI (setuid helper) | `V2rayUTool/main.swift` — sets system proxy via SCPreferences | 11.5+ |\n| `V2rayUTests` | Test bundle | Swift Testing, host app = V2rayU.app | 14+ |\n\n## Key paths (defined in `V2rayU/App/App.swift:9-21`)\n\n- `AppHomePath` = `~/.V2rayU` — config, logs, DB, PAC files\n- `AppBinRoot` = `/usr/local/v2rayu` — core binaries + V2rayUTool + update scripts\n- `databasePath` = `~/.V2rayU/.V2rayU.db`\n- `v2rayUTool` = `/usr/local/v2rayu/V2rayUTool`\n- `coreApiPort` = 11111, `coreApiBaseUrl` = `http://127.0.0.1:11111`\n\n## Dependencies (SPM)\n\nGRDB 7.11+ (SQLite), KeyboardShortcuts 2.4+, Yams 6.2+ (YAML), FlyingFox 0.26+ (HTTP), Firebase 12.14+, AppCenter 5.12+.\n\n## Architecture\n\n- **App layer**: `V2rayU/App/` — `App.swift` (entry + AppDelegate), `AppMenu.swift` (menu bar), `AppSettings.swift`, `AppState.swift` (global singleton)\n- **Core layer**: `V2rayU/Core/`\n  - `Database/` — GRDB-based SQLite (`AppDatabase.shared`), entities, migrations, stores\n  - `Handlers/` — `V2rayLaunch.swift` (start/stop cores), `LaunchAgent.swift` (plist gen), `AppInstaller.swift`, `NetworkMonitor.swift`, `SleepManager.swift`, `CoreConfigHandler.swift` (JSON config gen for both cores), `Singbox/`, `V2ray/`\n  - `Protocols/` — Share URI parsing/generation, V2ray/SingBox JSON model structs\n  - `Services/` — `GithubService.swift` (releases API), `HttpServer.swift` (local PAC server via FlyingFox), `DownloadDelegate.swift`\n  - `Utilities/` — `CoreCapabilityRules.swift` (capability rule engine ~1171 lines), `CertFingerprintFetcher.swift`, `DnsResolver.swift`, `Port.swift`, `Shell.swift`, `Scanner.swift`, `Network.swift` (ping)\n- **Features layer**: `V2rayU/Features/` — Profile, Subscription, Routing, Share, PAC, Migration, Diagnostic, Update\n- **UI layer**: `V2rayU/UI/` — Components, Views, Windows\n\n## Run modes\n\n`RunMode` enum: `global`, `pac`, `manual`, `tun` (defined in `V2rayU/Core/Handlers/V2rayLaunch.swift:13`).\n\n## Core engine (V2rayLaunch)\n\nActor-based singleton in `V2rayU/Core/Handlers/V2rayLaunch.swift`. Flow: read DB profile → resolve core compatibility (capability rules) → generate config JSON → create LaunchAgent plist → launch daemon → wait for SOCKS port → set system proxy → (if TUN mode) create tun.json + start tun-helper LaunchDaemon.\n\n## Capability rules system\n\nTwo JSON rule files at `Build/capability-rules/`:\n- `xray-capability-rules.json` (456 lines) — per-protocol/transport/security support with version bounds\n- `singbox-capability-rules.json` (367 lines) — sing-box capabilities\n\nEngine: `V2rayU/Core/Utilities/CoreCapabilityRules.swift` (~1171 lines). Rules loaded from bundled JSON, evaluated at startup to decide which core to use + warn about incompatibilities.\n\n## Build & release\n\n```bash\n# Build universal binary + DMG\n./Build/build.sh\n\n# Install (run as root via app or manually)\n# Copies V2rayUTool, update scripts, core binaries to /usr/local/v2rayu/\n# Sets up LaunchDaemon + sudoers entries\n./Build/install.sh\n```\n\n`build.sh` flow: `xcodebuild archive` (arm64+x86_64) → copy .app → `appdmg` for DMG. Version extracted from `project.pbxproj` MARKETING_VERSION (currently 5.0.2).\n\n## Testing\n\nUses **Swift Testing** framework (not XCTest). Tests are host-app-dependent (TEST_HOST = V2rayU.app).\n\n```bash\n# Run all tests\nxcodebuild test -project V2rayU.xcodeproj -scheme V2rayU -destination 'platform=macOS'\n\n# Run compatibility test suite (needs pre-downloaded core binaries)\n./Build/tests/run-compatibility-test.sh          # requires binaries\n./Build/tests/run-compatibility-test.sh --download  # download first\n\n# Download core versions for testing (xray v1.8.0~v26.5.6, sing-box v1.12.0~v1.13.13)\npython3 Build/tests/download-cores.py\n# Or per-core:\npython3 Build/tests/download-cores.py --core xray\npython3 Build/tests/download-cores.py --core sing-box\n```\n\nTest config: `Build/tests/test-config.json` (`maxProfiles`, `sampleVersions`). Env: `V2RAYU_TEST_BIN_DIR`, `V2RAYU_TEST_REPORT_DIR`, `V2RAYU_MAX_PROFILES`, `V2RAYU_SAMPLE_VERSIONS`.\n\nCompatibility test report: `Build/tests/reports/compatibility-report-*.json`. Generate HTML: `python3 Build/tests/generate-report.py <report.json>`.\n\nTests read the **real DB** at `~/.V2rayU/.V2rayU.db` — profiles must exist.\n\n## Core update scripts (root, via sudoers)\n\n- `Build/update-xray.sh` — installed to `/usr/local/v2rayu/update-xray.sh`, called with sudo for xray-core updates\n- `Build/update-singbox.sh` — same path pattern\n- Both support backup + rollback on failure\n\n## Run-time paths\n\n- `~/.V2rayU/config.json` — active core config\n- `~/.V2rayU/tun.json` — TUN mode config (sing-box)\n- `~/.V2rayU/V2rayU.log` — app log\n- `~/.V2rayU/core.log` — core stderr/stdout\n- `~/.V2rayU/tun.log` — TUN helper log\n- `~/Library/LaunchAgents/yanue.v2rayu.sing-box.plist` / `yanue.v2rayu.xray-core.plist` — per-user LaunchAgents\n- `/Library/LaunchDaemons/yanue.v2rayu.tun-helper.plist` — system LaunchDaemon\n- `/private/etc/sudoers.d/v2rayu-sudoer` — sudoers entry for tun-helper + core updates\n\n## CRITICAL: Never delete DerivedData\n\n**NEVER** delete `~/Library/Developer/Xcode/DerivedData/`. This directory contains SPM package checkouts. Due to network restrictions (GFW), re-resolving SPM dependencies will fail. Use `xcodebuild clean build` (NOT `rm -rf DerivedData`) for clean builds. If DerivedData is corrupted, the user must manually re-resolve via Xcode or VPN.\n\n## Repository conventions\n\n- **No CI**, no linter/formatter config, no typecheck script\n- **Localization**: en, zh-Hans, zh-HK in `V2rayU/Localization/` (String Catalogs + Localizable.strings)\n- **TODO**: `TODO` file (Chinese, issues list) at repo root\n- **Branch/PR**: no established convention visible\n- **Docs are executable sources of truth** — `Docs/CoreCapabilityRules.md` documents the capability rules policy, `Docs/CompatibilityTestSystem.md` documents the test framework, `Docs/XrayReleaseFeatureAnalysis.md` is auto-generated by `Tools/analyze_xray_releases.py`\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# V2rayU — Agent Guide\n\nmacOS menu-bar proxy client (Xray-core / sing-box). SwiftUI + GRDB. Targets: macOS 14+.\n\n## Targets & entrypoints\n\n| Target | Type | Entry | Deployment |\n|--------|------|-------|------------|\n| `V2rayU` | macOS app (LSUIElement) | `V2rayU/App/App.swift` — `@main struct V2rayUApp` | 14+ |\n| `V2rayUTool` | CLI (setuid helper) | `V2rayUTool/main.swift` — sets system proxy via SCPreferences | 11.5+ |\n| `V2rayUTests` | Test bundle | Swift Testing, host app = V2rayU.app | 14+ |\n\n## Key paths (defined in `V2rayU/App/App.swift:9-21`)\n\n- `AppHomePath` = `~/.V2rayU` — config, logs, DB, PAC files\n- `AppBinRoot` = `/usr/local/v2rayu` — core binaries + V2rayUTool + update scripts\n- `databasePath` = `~/.V2rayU/.V2rayU.db`\n- `v2rayUTool` = `/usr/local/v2rayu/V2rayUTool`\n- `coreApiPort` = 11111, `coreApiBaseUrl` = `http://127.0.0.1:11111`\n\n## Dependencies (SPM)\n\nGRDB 7.11+ (SQLite), KeyboardShortcuts 2.4+, Yams 6.2+ (YAML), FlyingFox 0.26+ (HTTP), Firebase 12.14+, AppCenter 5.12+.\n\n## Architecture\n\n- **App layer**: `V2rayU/App/` — `App.swift` (entry + AppDelegate), `AppMenu.swift` (menu bar), `AppSettings.swift`, `AppState.swift` (global singleton)\n- **Core layer**: `V2rayU/Core/`\n  - `Database/` — GRDB-based SQLite (`AppDatabase.shared`), entities, migrations, stores\n  - `Handlers/` — `V2rayLaunch.swift` (start/stop cores), `LaunchAgent.swift` (plist gen), `AppInstaller.swift`, `NetworkMonitor.swift`, `SleepManager.swift`, `CoreConfigHandler.swift` (JSON config gen for both cores), `Singbox/`, `V2ray/`\n  - `Protocols/` — Share URI parsing/generation, V2ray/SingBox JSON model structs\n  - `Services/` — `GithubService.swift` (releases API), `HttpServer.swift` (local PAC server via FlyingFox), `DownloadDelegate.swift`\n  - `Utilities/` — `CoreCapabilityRules.swift` (capability rule engine ~1171 lines), `CertFingerprintFetcher.swift`, `DnsResolver.swift`, `Port.swift`, `Shell.swift`, `Scanner.swift`, `Network.swift` (ping)\n- **Features layer**: `V2rayU/Features/` — Profile, Subscription, Routing, Share, PAC, Migration, Diagnostic, Update\n- **UI layer**: `V2rayU/UI/` — Components, Views, Windows\n\n## Run modes\n\n`RunMode` enum: `global`, `pac`, `manual`, `tun` (defined in `V2rayU/Core/Handlers/V2rayLaunch.swift:13`).\n\n## Core engine (V2rayLaunch)\n\nActor-based singleton in `V2rayU/Core/Handlers/V2rayLaunch.swift`. Flow: read DB profile → resolve core compatibility (capability rules) → generate config JSON → create LaunchAgent plist → launch daemon → wait for SOCKS port → set system proxy → (if TUN mode) create tun.json + start tun-helper LaunchDaemon.\n\n## Capability rules system\n\nTwo JSON rule files at `Build/capability-rules/`:\n- `xray-capability-rules.json` (456 lines) — per-protocol/transport/security support with version bounds\n- `singbox-capability-rules.json` (367 lines) — sing-box capabilities\n\nEngine: `V2rayU/Core/Utilities/CoreCapabilityRules.swift` (~1171 lines). Rules loaded from bundled JSON, evaluated at startup to decide which core to use + warn about incompatibilities.\n\n## Build & release\n\n```bash\n# Build universal binary + DMG\n./Build/build.sh\n\n# Install (run as root via app or manually)\n# Copies V2rayUTool, update scripts, core binaries to /usr/local/v2rayu/\n# Sets up LaunchDaemon + sudoers entries\n./Build/install.sh\n```\n\n`build.sh` flow: `xcodebuild archive` (arm64+x86_64) → copy .app → `appdmg` for DMG. Version extracted from `project.pbxproj` MARKETING_VERSION (currently 5.0.2).\n\n## Testing\n\nUses **Swift Testing** framework (not XCTest). Tests are host-app-dependent (TEST_HOST = V2rayU.app).\n\n```bash\n# Run all tests\nxcodebuild test -project V2rayU.xcodeproj -scheme V2rayU -destination 'platform=macOS'\n\n# Run compatibility test suite (needs pre-downloaded core binaries)\n./Build/tests/run-compatibility-test.sh          # requires binaries\n./Build/tests/run-compatibility-test.sh --download  # download first\n\n# Download core versions for testing (xray v1.8.0~v26.5.6, sing-box v1.12.0~v1.13.13)\npython3 Build/tests/download-cores.py\n# Or per-core:\npython3 Build/tests/download-cores.py --core xray\npython3 Build/tests/download-cores.py --core sing-box\n```\n\nTest config: `Build/tests/test-config.json` (`maxProfiles`, `sampleVersions`). Env: `V2RAYU_TEST_BIN_DIR`, `V2RAYU_TEST_REPORT_DIR`, `V2RAYU_MAX_PROFILES`, `V2RAYU_SAMPLE_VERSIONS`.\n\nCompatibility test report: `Build/tests/reports/compatibility-report-*.json`. Generate HTML: `python3 Build/tests/generate-report.py <report.json>`.\n\nTests read the **real DB** at `~/.V2rayU/.V2rayU.db` — profiles must exist.\n\n## Core update scripts (root, via sudoers)\n\n- `Build/update-xray.sh` — installed to `/usr/local/v2rayu/update-xray.sh`, called with sudo for xray-core updates\n- `Build/update-singbox.sh` — same path pattern\n- Both support backup + rollback on failure\n\n## Run-time paths\n\n- `~/.V2rayU/config.json` — active core config\n- `~/.V2rayU/tun.json` — TUN mode config (sing-box)\n- `~/.V2rayU/V2rayU.log` — app log\n- `~/.V2rayU/core.log` — core stderr/stdout\n- `~/.V2rayU/tun.log` — TUN helper log\n- `~/Library/LaunchAgents/yanue.v2rayu.sing-box.plist` / `yanue.v2rayu.xray-core.plist` — per-user LaunchAgents\n- `/Library/LaunchDaemons/yanue.v2rayu.tun-helper.plist` — system LaunchDaemon\n- `/private/etc/sudoers.d/v2rayu-sudoer` — sudoers entry for tun-helper + core updates\n\n## CRITICAL: Never delete DerivedData\n\n**NEVER** delete `~/Library/Developer/Xcode/DerivedData/`. This directory contains SPM package checkouts. Due to network restrictions (GFW), re-resolving SPM dependencies will fail. Use `xcodebuild clean build` (NOT `rm -rf DerivedData`) for clean builds. If DerivedData is corrupted, the user must manually re-resolve via Xcode or VPN.\n\n## Repository conventions\n\n- **No CI**, no linter/formatter config, no typecheck script\n- **Localization**: en, zh-Hans, zh-HK in `V2rayU/Localization/` (String Catalogs + Localizable.strings)\n- **TODO**: `TODO` file (Chinese, issues list) at repo root\n- **Branch/PR**: no established convention visible\n- **Docs are executable sources of truth** — `Docs/CoreCapabilityRules.md` documents the capability rules policy, `Docs/CompatibilityTestSystem.md` documents the test framework, `Docs/XrayReleaseFeatureAnalysis.md` is auto-generated by `Tools/analyze_xray_releases.py`\n","category":"root","tokens":1568}]}