IntentRoute AI
English | 中文
IntentRoute AI is an open-source Windows control plane that turns plain-language network intent into locally validated routing-rule drafts. It can use the OpenAI Responses API or an already-running local Ollama model, then hands accepted rules to the same deterministic sing-box TUN configuration pipeline used by the manual editor.
Project status: v0.24.0 preview. IntentRoute AI is useful for testing and early adoption, but it has not yet demonstrated broad production usage. AI output can be incomplete or wrong. Every generated rule is locally validated, added disabled, and must be explicitly enabled by the user.
v0.19.0 adds batch mode buttons (proxy/direct/block) to the rules toolbar — exposing the previously UI-less SetRulesMode transaction — and severity coloring for runtime logs. v0.18.0 completed the UI renewal with theme-colored page banners and unified list-page grammar; v0.16–v0.17 established the shared dark design system and component-library polish; v0.15.0 added the rule-import preview with full-identity duplicate detection. Every release archive still embeds the unsigned provenance.json build inventory introduced in v0.9.0; code signing itself still requires a certificate.
Why this project exists
Many Windows applications do not expose useful proxy controls, while hand-authoring process/domain/IP routing rules is error-prone. IntentRoute AI provides two complementary paths:
- A conventional, inspectable rule editor for deterministic manual configuration.
- An optional AI authoring assistant that translates natural language into a bounded, reviewable rule draft.
- A local Policy Intelligence workflow that proves ordering, duplicate, conflict, shadowing, broad-scope, and disabled-draft findings before an optional AI explanation.
- A local Route Decision Simulator that explains what the saved policy can prove for one concrete hypothetical process/destination/port/protocol input without pretending to observe traffic.
The application does not capture packets itself. It generates a validated sing-box v1.13+ TUN configuration, starts and supervises the external sing-box process, and keeps the default route direct unless a rule says otherwise.
AI workflow
- Select OpenAI or Ollama (local).
- Enter an intent such as: “Route Chrome and Cursor traffic for GitHub and OpenAI through the proxy; keep everything else direct.”
- The provider returns a strict structured draft containing process, host/IP, port, protocol, action, rationale, confidence, and warnings.
- IntentRoute AI treats the result as untrusted input and validates field limits, executable names, domains, CIDRs, ports, protocols, actions, duplicates, and proxy availability.
- A temporary enabled candidate is passed through
SingBoxConfigBuilder so disabled-rule filtering cannot make validation a no-op. This preview dry-run is deterministic in-process config construction; it intentionally does not execute an external program.
- The user reviews the preview and may edit any draft field (process, action, domains, IP/CIDR, ports, protocol, rationale). Every edit re-runs the same deterministic validation — including the enabled-clone dry-run — before the draft can be accepted as disabled rules.
- Enabling remains a separate user action. That state-changing path writes a candidate file and executes
sing-box check -c before the managed runtime is replaced.
AI never directly enables rules, invokes commands, selects files, installs models, downloads sing-box, or applies an unreviewed configuration.
AI Policy Intelligence workflow
- Open AI Policy Intelligence. A cancellation-aware background worker analyzes a detached configuration snapshot without blocking the WPF dispatcher; this performs no provider request, filesystem write, runtime apply, executable probe, proxy connection, DNS lookup, or traffic observation.
- Findings use the same Canonical Runtime Order as the generated sing-box route: priority ascending, creation timestamp ascending, then persisted source order. The rules page uses that order too.
- The local report distinguishes exact duplicates, same-scope different outcomes, proven earlier-superset shadowing, broad process/global rules, invalid disabled rules, inactive duplicates, same-priority overlaps, the ProxyAll default posture, and non-proven partial-overlap hints. Equivalent suffix, integer-port-union, and mergeable CIDR-union spellings are canonicalized before comparison. Uncertain partial overlaps are not promoted into facts.
- Local rows may show real rule labels and can navigate to an affected rule. They are never serialized to a provider.
- To request an explanation, select 1–20 findings and click Explain selected summary with AI. A confirmation dialog shows the exact logical JSON, provider, and exclusion list for that single request.
- The closed Policy Disclosure contains only aggregate counts plus finding code, category, severity, relationship, and affected-rule count. The AI response must use a strict schema and reference only those finding codes.
- AI explanation is plain, untrusted, read-only text. It cannot change local findings, write a note, create/enable/reorder a rule, save configuration, or apply sing-box. The local fingerprint is rechecked before preview, after confirmation but before sending, and after the response; stale summaries are not sent and stale responses are discarded.
Policy Intelligence describes static configuration semantics, not real connection behavior. A clean report is not proof that TUN creation, a proxy listener, authentication, upstream reachability, DNS behavior, or a particular connection succeeded.
AI Route Decision Simulator
- Open AI Route Simulator and enter one exact process name, one concrete domain or literal IPv4/IPv6 address, one port, and TCP or UDP.
- A bounded background worker validates the detached Configuration Snapshot through the production
SingBoxConfigBuilder, then evaluates enabled rules in Canonical Runtime Order.
- The result is deliberately three-valued: a proven first-rule match, a proven global fallback after all rules miss, or Indeterminate when a missing resolved IP/domain context could allow an earlier rule to win. Invalid input and invalid policy are separate fail-closed states and never return an action.
- The page shows a local evaluation trace and can navigate to a proven matched rule. A fingerprint binds the result to both the snapshot and normalized query; query or configuration changes hide the old result.
- Recovery Protection disables simulation rather than evaluating the empty placeholder state.
This is a static what-if tool, not telemetry. It does not resolve DNS, reverse-resolve an IP, probe a proxy, inspect connections, read runtime logs, enumerate packets, invoke sing-box, or change/apply configuration. The hypothetical query, local rule labels/IDs, proxy identity, and evaluation trace never cross an AI-provider seam.
Provider setup
OpenAI
IntentRoute AI reads the user's key at request time from OPENAI_API_KEY. The key is not accepted in the app UI and is never written to the application configuration, profiles, logs, exports, or diagnostics.
PowerShell example for the current Windows user:
[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'your-api-key', 'User')
Restart IntentRoute AI after changing the environment variable. The OpenAI request uses the Responses API, strict JSON Schema output, no tools, a bounded timeout/output size, and store=false.
Local Ollama
Install Ollama, start its local service, and install a model separately. For example:
ollama pull qwen3:8b
IntentRoute AI queries only literal HTTP 127.0.0.1 (the default) or ::1. It rejects hostnames, other loopback addresses, credentialed endpoints, HTTPS, LAN, and public Ollama endpoints; disables proxy use and redirects for these requests; and never pulls a model or launches Ollama automatically. The UI lists models already installed through GET /api/tags.
Health diagnostics
The Settings page offers a credential-free provider health check for the currently selected provider and model. For OpenAI it reports only whether OPENAI_API_KEY is present — the key is never displayed and no network request is sent. For Ollama it reports loopback service reachability, the installed-model count, and whether the selected model is installed. Diagnostics never contain credentials or endpoints beyond the literal loopback constant.
AI data boundary
| Data |
OpenAI |
Local Ollama |
| User-entered intent |
Sent |
Sent to loopback only |
| Static rule schema/instructions |
Sent |
Sent to loopback only |
| User-selected Policy Disclosure after exact preview/confirmation |
Sent |
Sent to loopback only |
| Route Simulator hypothetical query or local evaluation trace |
Never |
Never |
| Proxy username/password |
Never |
Never |
| Proxy server address |
Never |
Never |
| Existing rule values, IDs, labels, notes, or complete configuration |
Never |
Never |
| Process names, domains, IPs, ports, or paths from existing rules |
Never |
Never |
| Runtime logs |
Never |
Never |
| Full process list or paths |
Never |
Never |
| API key |
Authorization header only |
Not applicable locally |
OpenAI API data handling is governed by the user's OpenAI account and current API policies. store=false is an application-level request setting, not a promise that no provider-side security or abuse-monitoring processing exists. Ollama mode keeps the application request on loopback, but the privacy and behavior of the installed model/runtime remain the user's responsibility.
Current routing capabilities
- Process-aware Proxy / Direct / Block rules.
- Optional exact-domain and
*.suffix filters.
- IPv4/IPv6 address and CIDR filters.
- Single ports and ascending port ranges.
- TCP, UDP, or Both.
Both is emitted explicitly as TCP + UDP; it does not silently include sing-box v1.13 ICMP matching.- Explicit priority ordering.
- Canonical runtime ordering shared by the builder, rule view, process-candidate view, and Policy Intelligence.
- Local Policy Intelligence plus request-scoped, user-selected, structurally de-identified AI explanation.
- Conservative static Route Decision Simulator with proven-match, proven-fallback, and indeterminate states bound to a Configuration Snapshot and query.
- IPv4 and IPv6 TUN addresses with strict routing.
- Atomic candidate configuration,
sing-box check, cancellation-aware startup-settle verification, and rollback.
- Exclusive runtime ownership plus PID/start-time orphan recovery.
- Runtime status whose path, version, and PID describe the same actually managed sing-box process, including after candidate rejection or rollback.
- Passwords protected at rest with Windows DPAPI
CurrentUser.
- Password-free profile exports and bounded/redacted runtime logs.
- Runtime-log triage: minimum-level filter, debounced case-insensitive search, auto-scroll toggle, and a local export of the exact filtered (re-redacted) log view.
- Process-to-rule workflow: name/PID search, real executable paths, and one-click rule creation from a selected running process through the normal configuration transaction.
- Batch rule management: extended multi-selection with one-transaction batch enable/disable/delete and a count-formatted confirmation.
- Rule-constraints editor: context-menu editing of host / IP-CIDR / port constraints, protocol, and note, live-validated with builder-matching semantics before save.
- Literal-loopback-only upstream proxy endpoints with an optional bounded TCP-listener check.
- A recognized sing-box v1.13+ version gate before configuration check or launch.
- Save-blocked recovery when
config.json or a DPAPI-protected password cannot be read safely.
- Transactional configuration edits that validate and atomically persist a complete candidate before publishing it to application state or queueing a runtime apply.
- Detached configuration snapshots, so UI or validation code cannot mutate active routing state outside the supported commit path.
IntentRoute AI does not provide a proxy node, VPN account, packet driver, bundled AI model, OpenAI API key, or sing-box binary.
Install a preview build
- Download
IntentRoute-AI-v0.24.0-win-x64.zip and its .sha256 file from Releases.
- Verify the checksum.
- Download the official Windows x64 sing-box v1.13+ archive separately.
- Install
sing-box.exe separately, then explicitly approve its exact file from Settings → Browse on every elevated app launch. The saved path, imported profiles/configurations, INTENTROUTE_SING_BOX, the legacy PROXYMANAGER_SING_BOX, the application directory, and PATH are candidate-discovery hints only: they may be displayed, but neither version, check, nor run executes until that file is reselected in the current session.
- Ensure an existing proxy service is listening on a literal loopback IP such as
127.0.0.1 or ::1. The Settings page can save SOCKS5/HTTP/HTTPS username and password values and can check whether the local TCP port accepts a connection.
- Run
IntentRouteAI.exe as administrator. TUN creation requires elevation.
The self-contained release targets Windows x64 and does not require a separate .NET runtime.
Configuration and upgrade migration
Current data is stored under %APPDATA%\IntentRouteAI. On first launch, if the new directory has no current configuration, the application copies only config.json and *.profile.json from %APPDATA%\ProxyManager. Copying holds a per-directory exclusive migration lock and uses an in-progress marker plus atomic per-file moves, so an interrupted migration retries only missing known files on the next launch and never overwrites a completed copy. It deliberately does not copy generated sing-box configs, runtime leases, locks, or candidates, and it never deletes the legacy directory automatically.
Proxy passwords are protected at rest with DPAPI CurrentUser. Passwords entered in the UI are always treated as plaintext before storage, including legitimate values that begin with the reserved on-disk dpapi: marker. The generated %APPDATA%\IntentRouteAI\sing-box.generated.json necessarily contains any configured credential in plaintext while sing-box is running. The application removes it on stop, clean exit, and unexpected child exit; the next launch performs bounded orphan recovery and stale-artifact cleanup. Cleanup remains best effort under disk, ACL, administrator, or abrupt-crash interference.
Since v0.3.0, malformed JSON, invalid UTF-8, a null document or collection entry, a rule without a non-empty process name, duplicate rule/server IDs, an explicitly null/empty ID or an omitted Id JSON property, any non-empty proxy-chain definition, or a dpapi: password that cannot be decrypted for the current Windows user makes the configuration unusable, not empty. Persisted object IDs are required JSON members; model initializers may create IDs for new in-memory objects but cannot repair imported data silently. Proxy chains remain parseable only so legacy or imported data can be rejected explicitly; IntentRoute AI does not persist or silently ignore them until an actual sing-box runtime mapping exists. A global rule must use the explicit * process name; a missing name is never interpreted as global routing. IntentRoute AI leaves the original file untouched, attempts to create a timestamped config.json.corrupt-*.bak copy, blocks all save and runtime-apply paths, and shows explicit import/reset recovery controls. Import validates the supported endpoint and routing semantics before replacement. Both import replacement and reset are disabled unless the recovery copy still exists. If the copy could not be created, the user must first make a manual copy and restart the application so preservation can be verified before replacement.
Normal edits, rule imports, AI-draft acceptance, Profile replacement, recovery, and reset use one Configuration Workspace transaction. The application clones the active configuration, applies and validates the complete candidate, atomically saves it, and only then publishes a new detached snapshot. A validation or save failure leaves memory and disk unchanged. Local edits preserve a current-session sing-box approval only while the executable path is unchanged; Profile replacement, recovery, and reset always clear it. Clearing approval cancels any queued replacement apply. If cancellation arrives after a candidate process has started, IntentRoute AI restores the prior generated configuration and restarts its prior process before publishing RunningStale; cancellation and green-state publication are serialized so a late Apply cannot overwrite the warning. The executable must be explicitly approved again before the current configuration can be applied.
Candidate path/version probe results remain local to the attempted Apply. Runtime status changes its executable path and version only when that executable is actually started, and clears them when no managed process remains. A rejected candidate therefore leaves the old PID/path/version aligned; failed-start and cancellation rollback restart the prior configuration with the prior executable rather than the rejected candidate.
Cancellation before candidate promotion (including version probe, candidate write, and external check) also converges to a terminal runtime status: RunningStale when the prior process remains active, or Failed when no managed process exists. Direct runtime callers therefore cannot leave status indefinitely in Starting, Probing, or Checking after cancellation.
The local proxy Test port action only performs a TCP connection to the entered literal loopback IP with a five-second bound. It sends no username or password and does not prove SOCKS/HTTP negotiation, authentication, upstream reachability, DNS behavior, or routed application traffic.
Build and test
Requirements for source builds:
- Windows 10/11 x64
- .NET 8.0.424 SDK (pinned by
global.json)
- PowerShell 7 recommended
./scripts/test.ps1
./scripts/check-vulnerabilities.ps1
./scripts/build.ps1
./scripts/smoke-test-wpf.ps1 -OutputDirectory ./artifacts/win-x64
./scripts/test-pinned-sing-box.ps1
Provider tests use mocked HTTP handlers. They do not require an OpenAI key, a paid API call, a running Ollama service, or a downloaded local model. The Windows CI also launches the published single-file executable, verifies that the expected WPF main window is created, requests a normal close, and requires a clean zero exit.
The explicit test-pinned-sing-box.ps1 developer/CI gate temporarily downloads the official sing-box v1.13.19 Windows archive, verifies its pinned SHA-256, passes representative SingBoxConfigBuilder output through the real sing-box check, and removes the temporary executable and generated configurations. This test-only dependency is never copied into application artifacts; IntentRoute AI itself still never downloads or bundles sing-box. Pass -SingBoxPath C:\path\to\sing-box.exe to test an already-installed exact v1.13.19 executable without downloading it.
Architecture and security
IntentRoute AI 是一款开源 Windows 应用，把自然语言描述的网络分流意图转化为经过本地验证的 sing-box TUN 规则，使用 OpenAI Responses API 或本地 Ollama 模型作为草稿助手。