Dushnilin
2019ddd12a
- Fix #52: Watchdog proxy restart on single URL failure: * Validate failure against secondary independent probe URL before declaring proxy down * Skip restart when direct WAN is also degraded or down (!direct_ok) * Implement 120s cooldown between automated proxy restarts * Fix Telegram notification to accurately state 'Перезапуск sing-box' instead of 'Перезапуск роутера' - Fix #51: Telegram bot spamming WAN up/down notifications: * Filter hotplug events strictly by badwan_monitored_interfaces (defaults to wan) * Add atomic directory lock with debounce delay and real ubus state query * Prevent repeated notifications when interface state has not transitioned - Feat: 2-VPN deadlock elimination & self-download subscription proxy: * Isolate unbootstrapped dependent subscription sections on initial boot (deferred_sections) * Allow self-download proxy target for subscriptions with explicit UI hint '(текущее правило при активности)' * Enable automatic local proxy fallback for subscription refresh when direct WAN download fails while sing-box is active * Add regression test in tests/subscription_bootstrap_deadlock.sh - Fix: Parental control quota enforcement: * Correct route rule filtering when daily quota minutes are exhausted without a fixed time interval - i18n & Version bump: * Bump fe-app-tachyon to 1.3.26 and update Russian PO/POT translations
1 line
106 KiB
JSON
1 line
106 KiB
JSON
{"version": 1, "chunk_size": 2000, "chunk_overlap": 200, "total_chunks": 50, "files": ["01_SYSTEM_ARCHITECTURE.md", "02_UCODE_MODULE_REFERENCE.md", "03_NETWORKING_NFTABLES_AND_ROUTING.md", "04_DPI_BYPASS_ENGINES.md", "05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md", "06_FRONTEND_LUCI_TYPESCRIPT.md", "07_BUILD_TESTS_AND_DEPLOYMENT.md", "08_UCI_CONFIGURATION_SCHEMA.md", "09_TELEGRAM_BOT_ARCHITECTURE.md", "10_HOSTS_ENGINE_AND_BLOCKLISTS.md", "11_TROUBLESHOOTING_AND_FIELD_MANUAL.md", "12_UCODE_PROGRAMMING_PATTERNS.md", "13_REST_API_AND_MCP_SPECIFICATION.md", "14_ZAPRET2_DEEP_DIVE_MANUAL.md", "15_ZAPRET1_NFQWS_FIELD_GUIDE.md", "16_BYEDPI_CIADPI_REFERENCE.md", "17_TSPU_DPI_SIGNATURES_AND_COUNTERS.md", "INDEX.md"], "chunks": [{"id": 0, "file": "01_SYSTEM_ARCHITECTURE.md", "heading": "2.2. Deterministic State & Atomic Writes", "text": "# 01. System Architecture & Core Concepts\n\n## 1. High-Level Overview\n\n**Tachyon** is an enterprise-grade, lightweight traffic orchestration, multi-protocol proxying, and DPI anti-censorship platform built natively for **OpenWrt** (supporting 23.05, 24.10, 25.x, and SNAPSHOT).\n\n```mermaid\ngraph TD\n Client[LAN Clients] -->|TCP/UDP| Router[OpenWrt Router]\n Router --> NFT[nftables: inet TachyonTable]\n \n NFT -->|Direct List / 0ms| WAN[Direct WAN Gateway]\n NFT -->|NFQueue Desync| Zapret[Zapret v1 / v2 nfqws/2]\n NFT -->|SOCKS Desync| ByeDPI[ByeDPI ciadpi]\n NFT -->|TProxy / Redirect| SingBox[sing-box Core v1.11+]\n \n SingBox -->|VLESS Reality / H2 / WG| VPS[External VPS / Global Web]\n Zapret --> WAN\n ByeDPI --> WAN\n \n subgraph Tachyon Control Plane\n UCODE[ucode Core Runtime] --> NFT\n UCODE --> SingBox\n UCODE --> Zapret\n UCODE --> ByeDPI\n Watchdog[Autonomous Watchdog 5-15s] --> UCODE\n AIDoctor[AI Doctor v2.5 / Local Doctor] --> Watchdog\n Telegram[Telegram Bot Daemon] --> UCODE\n RestAPI[HTTP REST Agent API / OpenAPI 3.0] --> UCODE\n LuCI[LuCI TypeScript Web UI] --> UCODE\n end\n```\n\n---\n\n## 2. Core Architectural Pillars\n\n### 2.1. Native ucode Runtime (Zero Heavy Runtimes)\n* All control plane logic, UCI manipulation, config generation, health checks, and JSON APIs are written in **ucode**, OpenWrt's native C-like scripting language.\n* **Benefits**:\n * Consumes $\\approx$ 1–3 MB RAM (contrasted with 30–60 MB for Python/Node).\n * Executes directly in C-speed with native bindings to `libuci`, `libubus`, `libblobmsg`, and posix syscalls (`fs`, `math`, `socket`).\n * Runs on routers with as little as 128 MB RAM.\n\n### 2.2. Deterministic State & Atomic Writes\n* All configuration changes (`/etc/config/tachyon`) and JSON runtime configurations (`/tmp/tachyon/sing-box.json`) use an **atomic write pattern** (`tmp_file + rename`):\n ```ucode\n fs.writefile(tmp_path, json_str);\n fs.rename(tmp_path, target_path);", "embedding": []}, {"id": 1, "file": "01_SYSTEM_ARCHITECTURE.md", "heading": "3. Directory Layout & Repository Anatomy", "text": "* All configuration changes (`/etc/config/tachyon`) and JSON runtime configurations (`/tmp/tachyon/sing-box.json`) use an **atomic write pattern** (`tmp_file + rename`):\n ```ucode\n fs.writefile(tmp_path, json_str);\n fs.rename(tmp_path, target_path);\n ```\n This prevents file corruption during sudden power losses or kernel panics.\n\n### 2.3. Dual Control Interfaces: LuCI & Headless Telegram/REST\n1. **LuCI Web UI**: Modern TypeScript SPA (`fe-app-tachyon`) compiled into LuCI JS assets (`luci-app-tachyon`).\n2. **Interactive Telegram Bot**: Embedded polling daemon with inline keyboards for on-the-fly server switching, rule updates, and instant diagnostics.\n3. **HTTP REST Agent API**: Secure CGI endpoint (`/cgi-bin/tachyon-agent/`) with OpenAPI 3.0.3 spec for integration with LLM agents (ChatGPT Custom GPTs, Cursor, Claude Code, N8N).\n\n---\n\n## 3. Directory Layout & Repository Anatomy\n\n```\ntachyon/\n├── tachyon/files/ # Core backend package root\n│ ├── etc/\n│ │ ├── config/tachyon # Main UCI configuration (chmod 600)\n│ │ ├── init.d/tachyon # Procd service init script\n│ │ └── uci-defaults/ # Post-installation default configs\n│ ├── usr/\n│ │ ├── bin/tachyon # Main CLI entrypoint wrapper\n│ │ └── lib/tachyon/ # Modular ucode libraries (60+ modules)\n│ │ ├── core/ # Low-level helpers, UCI, constants\n│ │ ├── service/ # Lifecycle, Watchdog, APIs, Telegram\n│ │ ├── diagnostics/ # AI Doctor, Local Doctor, Quick Fixes\n│ │ ├── singbox/ # Config generator, DNS, routing\n│ │ ├── providers/ # Zapret v1/v2, ByeDPI, NFQueue\n│ │ ├── nft/ # nftables ruleset compiler & applier\n│ │ ├── dns/ # dnsmasq & DNS routing coordinator\n│ │ ├── components/ # Updater, package manager, hosts\n│ │ ├── config/ # Validator, rule engine, migrations", "embedding": []}, {"id": 2, "file": "01_SYSTEM_ARCHITECTURE.md", "heading": "4. Key Runtime Processes & Daemons", "text": "│ │ ├── dns/ # dnsmasq & DNS routing coordinator\n│ │ ├── components/ # Updater, package manager, hosts\n│ │ ├── config/ # Validator, rule engine, migrations\n│ │ └── subscription/ # Subscriptions fetcher & parser\n├── luci-app-tachyon/ # OpenWrt LuCI package\n│ ├── htdocs/luci-static/resources/view/tachyon/ # Compiled frontend JS bundle\n│ ├── root/etc/uci-defaults/ # LuCI menu registration\n│ └── po/ # Translations (ru, en)\n├── fe-app-tachyon/ # Frontend TypeScript source\n│ ├── src/ # TypeScript SPA source\n│ ├── tsup.config.ts # Builds and patches LuCI baseclass\n│ └── package.json # Dependencies (vitest, typescript, tsup)\n├── tests/ # Comprehensive test suite (100+ shell tests)\n├── build.sh # Release packager (ipk + apk)\n├── install.sh # One-liner end-user installer\n└── docs/ # Technical documentation & Knowledge Base\n```\n\n---\n\n## 4. Key Runtime Processes & Daemons\n\n| Process | Role | Execution Model |\n|---|---|---|\n| `sing-box` | Core proxying & packet tunneling engine | Managed by procd (`/etc/init.d/tachyon`) |\n| `nfqws` / `nfqws2` | Local TCP/UDP packet desynchronizer (Zapret) | Spawned into background per configured rule |\n| `ciadpi` | Local SOCKS desync proxy (ByeDPI) | Spawned on `127.0.0.1:1080` / custom port |\n| `watchdog.uc` | State supervision, loop mitigation, self-healing | Background periodic daemon (every 5–15s) |\n| `telegram.uc` | Telegram Bot Long-Polling Daemon | Procd-supervised background worker |\n| `agent_api.uc` | HTTP REST Agent API Handler | Invoked on-demand via `uhttpd` CGI |", "embedding": []}, {"id": 3, "file": "02_UCODE_MODULE_REFERENCE.md", "heading": "2. Service Management Subsystem (`service/`)", "text": "# 02. ucode Backend Module Reference\n\nTachyon's backend is modularized under `tachyon/files/usr/lib/tachyon/`. Modules are loaded dynamically via ucode's `require()` or executed directly via `ucode -L <lib_dir> <module> <command>`.\n\n---\n\n## 1. Core Subsystem (`core/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `constants.uc` | Central repository of paths, default ports, mark values, version detection (`detect_installed_version()`), commit SHA resolver (`detect_installed_commit_sha()`), UCI config names. |\n| `common.uc` | String manipulation (`trim`, `split_lines`), file helpers (`read_file`, `write_atomic`), logging formatters (`log_info`, `log_error`, `log_debug`). |\n| `helpers.uc` | Process management (`popen_read`, `system_exec`), CIDR formatting, MAC address validators, integer conversions with safety fallbacks. |\n| `ip.uc` | IP v4/v6 parser, subnet containment (`ip_in_subnet`), CIDR validator, loopback & private IP range detection. |\n| `url.uc` | RFC 3986 URL parser, extraction of scheme, host, port, path, query params, hash fragment, safe URL encoding/decoding. |\n| `uci.uc` | High-level wrapper over OpenWrt `libuci`: `get_section`, `set_option`, `add_section`, `delete_section`, atomic commit with lock. |\n| `packages.uc` | Package manager abstraction: detects `opkg` vs `apk` (OpenWrt 25.x+), checks installed packages, versions, and dependencies. |\n| `events.uc` | Internal event bus mechanism: publish/subscribe for service state transitions and notification dispatching. |\n\n---\n\n## 2. Service Management Subsystem (`service/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `lifecycle.uc` | Service start, stop, restart, enable, disable. Coordinates teardown order (nftables -> singbox -> zapret -> dnsmasq) to prevent routing deadlocks. |\n| `state.uc` | Comprehensive runtime state reader (`get_runtime_state()`): active proxy server, watchdog status, interface health, uptime, memory consumption. |\n| `reload.uc` | Hot-reload planner (`plan_reload()`): inspects what changed in UCI and applies the minimal necessary restart (e.g. soft-reload sing-box vs full nftables rebuild). |", "embedding": []}, {"id": 4, "file": "02_UCODE_MODULE_REFERENCE.md", "heading": "3. Diagnostics & AI Subsystem (`diagnostics/`)", "text": "| `state.uc` | Comprehensive runtime state reader (`get_runtime_state()`): active proxy server, watchdog status, interface health, uptime, memory consumption. |\n| `reload.uc` | Hot-reload planner (`plan_reload()`): inspects what changed in UCI and applies the minimal necessary restart (e.g. soft-reload sing-box vs full nftables rebuild). |\n| `reset.uc` | Factory reset routines: wipes `/etc/config/tachyon`, cleans up temporary caches, restores default templates. |\n| `watchdog.uc` | Autonomous supervisor loop: checks sing-box process, memory thresholds (OOM guard), DNS resolution, loop-restart mitigation (`safe_proxy_restart`). |\n| `snapshot.uc` | Assembles a structured system snapshot JSON for AI Doctor and external diagnostics. |\n| `agent_api.uc` | CGI handler for `/cgi-bin/tachyon-agent/`: handles routing, Bearer authentication validation, endpoint dispatch, JSON serialization. |\n| `agent_mcp.uc` | Model Context Protocol (MCP) tool schema and handlers for integration with MCP clients (Cursor, Claude Desktop). |\n| `telegram.uc` | Telegram Bot daemon: polling loop (`getUpdates`), command dispatcher (`/doctor`, `/ai_doctor`, `/fix`, `/restart`, `/status`), inline keyboards. |\n| `warp_generator.uc` | Cloudflare WARP account generator & key exchange for auto-provisioning WireGuard outbounds. |\n| `event_controller.uc` | Coordinates async background job workers, PID tracking, lock files, and log ring-buffer management. |\n\n---\n\n## 3. Diagnostics & AI Subsystem (`diagnostics/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `runtime.uc` | **Local Rule Doctor & AI Doctor engine**: runs 10+ local heuristic checks, detects NTP desync, conntrack overflow, MTU issues, bootstrap DNS deadlock; applies 13+ quick fix codes (`apply_quick_fix()`), executes emergency internet restoration (`restore_native_internet()`). |\n| `service_check.uc` | Health probes: tests sing-box TCP/UDP proxying, DNS response latency, WAN internet connectivity, gateway reachability. |\n| `status.uc` | Detailed diagnostics status assembler for LuCI Diagnostic tab and CLI `tachyon doctor`. |", "embedding": []}, {"id": 5, "file": "02_UCODE_MODULE_REFERENCE.md", "heading": "5. Providers & DPI Bypass Subsystem (`providers/`)", "text": "| `service_check.uc` | Health probes: tests sing-box TCP/UDP proxying, DNS response latency, WAN internet connectivity, gateway reachability. |\n| `status.uc` | Detailed diagnostics status assembler for LuCI Diagnostic tab and CLI `tachyon doctor`. |\n\n---\n\n## 4. sing-box Subsystem (`singbox/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `generator.uc` | Master sing-box JSON configuration compiler (`/tmp/tachyon/sing-box.json`): binds inbounds, outbounds, routing rules, DNS, experimental. |\n| `generator_outbounds.uc` | Compiles VLESS (Reality/gRPC/WS), VMess, Shadowsocks, Trojan, Hysteria2, WireGuard, Direct, and Block outbounds. |\n| `generator_routes.uc` | Compiles routing rules: domain matchers, IP CIDR matchers, GeoIP rules, client MAC/IP matchers, detour assignments. |\n| `dns.uc` | Compiles sing-box DNS configuration: local DNS, remote DoH/DoT/UDP DNS, fakeip/direct resolution rules. |\n| `dns_failover.uc` | High-availability DNS failover logic: switches between primary and secondary bootstrap DNS upon timeouts. |\n| `dns_prefetch.uc` | Domain pre-fetching & cache warming for frequently accessed sites. |\n| `dns_presets.uc` | Built-in DNS presets (Cloudflare, Google, AdGuard, Quad9, OpenDNS, Custom DoH). |\n| `priority.uc` | Outbound group priority manager: auto-failover, fallback groups, URL-test latency sorting. |\n| `route.uc` | Low-level sing-box route rule builder & selector logic. |\n| `rulesets.uc` | Rule-set binary (`.srs`) and JSON ruleset compiler and parser. |\n| `servers.uc` | Server node parser, validator, and URI serializer (VLESS, VMess, SS, Trojan, H2). |\n| `subscription.uc` | Subscriptions processor: download, base64 decoding, node deduplication, format normalizer. |\n| `urltest.uc` | RTT ping & latency testing worker: measures real response times across proxy servers. |\n\n---\n\n## 5. Providers & DPI Bypass Subsystem (`providers/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `zapret/runtime.uc` | Manages **Zapret v1 (`nfqws`)** process arguments, queue numbers, NFQueue bindings, daemon start/stop. |", "embedding": []}, {"id": 6, "file": "02_UCODE_MODULE_REFERENCE.md", "heading": "7. Configuration & Components Subsystem (`config/`, `components/`, `subscription/`)", "text": "## 5. Providers & DPI Bypass Subsystem (`providers/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `zapret/runtime.uc` | Manages **Zapret v1 (`nfqws`)** process arguments, queue numbers, NFQueue bindings, daemon start/stop. |\n| `zapret2/runtime.uc` | Manages **Zapret v2 (`nfqws2`)** advanced multi-vector desync arguments (`--dpi-desync=multisplit`, `--dpi-desync-seqovl`). |\n| `byedpi/runtime.uc` | Manages **ByeDPI (`ciadpi`)** SOCKS5 proxy daemon, port allocation, payload split parameters. |\n| `nfqueue/runtime.uc` | Kernel NFQueue allocation table, prevents queue ID collisions between Zapret v1 and v2. |\n| `rules.uc` | Maps UCI routing rules to specific provider action handlers (`action = zapret | zapret2 | byedpi | proxy`). |\n| `status.uc` | Real-time process inspection and health monitoring of all active DPI bypass daemons. |\n\n---\n\n## 6. Networking & Firewall Subsystem (`nft/`, `dns/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `nft/apply.uc` | Generates and commits nftables ruleset (`inet TachyonTable`): prerouting, output, divert chains, marks, fwmark, bypass sets. |\n| `dns/apply.uc` | Coordinates DNS interception: configures dnsmasq forwarders, port redirection (`127.0.0.1:5353`), ipset / nftset auto-population. |\n\n---\n\n## 7. Configuration & Components Subsystem (`config/`, `components/`, `subscription/`)\n\n| Module | Key Functions & Responsibilities |\n|---|---|\n| `config/validator.uc` | Strict UCI schema validation: validates IP addresses, ports, UUIDs, private keys, domain names, action modes. |\n| `config/migration.uc` | Automatic migration engine: migrates configurations from legacy Forkop, Podkop Plus, and Podkop configs without data loss. |\n| `components/updater.uc` | Background component installer/updater: handles downloading, unpacking, installing, and version checking of binaries. |\n| `components/hosts.uc` | Remote hosts lists ingestor: fetches blocklists, merges into unified `combined.txt`, handles GitHub mirror failovers. |", "embedding": []}, {"id": 7, "file": "02_UCODE_MODULE_REFERENCE.md", "heading": "7. Configuration & Components Subsystem (`config/`, `components/`, `subscription/`)", "text": "| `components/updater.uc` | Background component installer/updater: handles downloading, unpacking, installing, and version checking of binaries. |\n| `components/hosts.uc` | Remote hosts lists ingestor: fetches blocklists, merges into unified `combined.txt`, handles GitHub mirror failovers. |\n| `subscription/cache.uc` | Atomic subscription cache store, prevents redundant network downloads. |\n| `subscription/parser.uc` | Universal proxy URI parser: parses `vless://`, `vmess://`, `ss://`, `trojan://`, `hysteria2://`, `wireguard://`. |", "embedding": []}, {"id": 8, "file": "03_NETWORKING_NFTABLES_AND_ROUTING.md", "heading": "2.1. Key Chains", "text": "# 03. Networking, nftables & Traffic Routing\n\n## 1. Packet Journey & Routing Lifecycle\n\nTachyon intercepts traffic at the OpenWrt kernel level using **nftables** and policy routing (`ip rule` + routing table `100`).\n\n```mermaid\nsequenceDiagram\n autonumber\n participant Client as LAN Client\n participant PREROUTING as nftables PREROUTING\n participant Sets as nftables Sets (Bypass / Target)\n participant Divert as Detour Action\n participant SingBox as sing-box / Zapret / ByeDPI\n participant WAN as WAN / Internet\n\n Client->>PREROUTING: TCP/UDP SYN Packet (e.g. 192.168.1.100 -> 1.1.1.1:443)\n PREROUTING->>Sets: Check destination IP / Port against Tachyon sets\n alt IP in Bypass Set (Local Subnet / RuNet / Direct)\n Sets->>WAN: Direct Forwarding (0 ms overhead)\n else IP in Target Set or Default Detour\n Sets->>Divert: Mark packet with FWMARK (e.g. 0x10000000)\n Divert->>SingBox: Divert via TProxy / Redir / NFQueue\n SingBox->>WAN: Processed / Encrypted / Desynchronized Outbound\n end\n```\n\n---\n\n## 2. nftables Table Structure (`inet TachyonTable`)\n\nTachyon encapsulates all its firewall rules inside a dedicated table `inet TachyonTable`. This ensures clean isolation from the system `inet fw4` firewall.\n\n### 2.1. Key Chains\n\n1. **`dstnat` / `prerouting` (Hook `prerouting`, priority `-100` / `dstnat`)**:\n * Intercepts incoming LAN client packets before routing decisions.\n * Checks client MAC / IP exclusion lists.\n * Matches destination IP against `tachyon_bypass_v4` / `tachyon_target_v4` sets.\n * Performs TProxy redirect (`tproxy to :10080 meta mark set 0x10000000 accept`) or Port redirect.\n2. **`output` (Hook `output`, priority `-100`)**:\n * Intercepts router's own locally generated packets (e.g. DNS lookups, curl, router traffic).\n * Prevents self-interception loops (`meta skuid == \"tachyon\" return`).\n3. **`nfqueue_chain`**:\n * Directs packets destined for Zapret v1 / v2 to kernel NFQueue numbers (`queue num 200`, `queue num 201`).", "embedding": []}, {"id": 9, "file": "03_NETWORKING_NFTABLES_AND_ROUTING.md", "heading": "3.3. Bootstrap DNS Dead-Lock Prevention", "text": "* Prevents self-interception loops (`meta skuid == \"tachyon\" return`).\n3. **`nfqueue_chain`**:\n * Directs packets destined for Zapret v1 / v2 to kernel NFQueue numbers (`queue num 200`, `queue num 201`).\n\n### 2.2. Bitmask & Firewall Marks\n\n| Mark Value | Meaning | Action |\n|---|---|---|\n| `0x10000000` | Redirected to sing-box TProxy | Routed to local loopback via table 100 |\n| `0x20000000` | Processed by Zapret / NFQueue | Dispatched to nfqws daemon |\n| `0x40000000` | Marked for ByeDPI SOCKS | Forwarded to local SOCKS redirect |\n| `0x80000000` | Bypass marker (Direct WAN) | Accepted immediately without inspection |\n\n---\n\n## 3. DNS Architecture & Interception\n\n### 3.1. DNS Resolution Pipeline\n\n```\n[LAN Client DNS Query: 53]\n │\n ▼\n [dnsmasq / Router]\n │\n ├─► If Domain in Direct / RuNet / Local ──► Local Upstream DNS (ISP / DoH)\n │\n ├─► If Domain in Hosts Section ──────────► Static IP from dns_hosts\n │\n └─► If Domain in Target Proxy / Desync ──► sing-box DNS (127.0.0.1:5353)\n │\n ▼\n [Remote Secure DoH/DoT]\n [Populates nftables set]\n```\n\n### 3.2. Dynamic nftables Set Population (`nftset`)\n* When dnsmasq resolves a domain associated with a proxy or Zapret rule, it automatically adds the resolved IP address to the corresponding kernel nftables set (e.g. `tachyon_target_v4`).\n* This enables sub-millisecond, line-rate packet redirection without re-evaluating domain names in user-space for every packet.\n\n### 3.3. Bootstrap DNS Dead-Lock Prevention\n* A critical failure mode in proxy routers is a **DNS loop**: sing-box needs to resolve the VPS hostname (e.g. `vps.example.com`), but its own DNS resolver routes queries through sing-box, which is not yet connected.", "embedding": []}, {"id": 10, "file": "03_NETWORKING_NFTABLES_AND_ROUTING.md", "heading": "4.1. Emergency Internet Restoration Mechanism", "text": "* A critical failure mode in proxy routers is a **DNS loop**: sing-box needs to resolve the VPS hostname (e.g. `vps.example.com`), but its own DNS resolver routes queries through sing-box, which is not yet connected.\n* **Tachyon's Solution**:\n * Dedicated `direct_resolvers` (Cloudflare `1.1.1.1`, Google `8.8.8.8`) bypass all proxy rules.\n * Local Rule Doctor monitors bootstrap DNS reachability and automatically executes `fix_bootstrap_dns` if a circular dependency is detected.\n\n---\n\n## 4. Policy Routing (`ip rule` & Routing Tables)\n\nTachyon provisions routing table `100`:\n```sh\n# Routing rule for marked packets\nip rule add fwmark 0x10000000/0x10000000 lookup 100 priority 10000\n\n# Local loopback route in table 100\nip route add local default dev lo table 100\n```\n\n### 4.1. Emergency Internet Restoration Mechanism\nWhen `tachyon restore_native_internet` is triggered:\n1. `inet TachyonTable` is atomically deleted: `nft delete table inet TachyonTable`.\n2. Policy routing rule `ip rule del lookup 100` is removed.\n3. dnsmasq configuration is reverted to native upstream forwarders.\n4. sing-box process is stopped cleanly.\n5. Result: Full, native WAN connectivity is restored in under 200 ms without rebooting the router.", "embedding": []}, {"id": 11, "file": "04_DPI_BYPASS_ENGINES.md", "heading": "2.1. Основные стратегии обхода", "text": "# 04. Движки обхода DPI и десинхронизации пакетов\n\nTachyon интегрирует три независимых локальных движка десинхронизации сетевых пакетов, которые функционируют непосредственно на оборудовании роутера без необходимости использования внешнего VPS или прокси-сервера (режим «Zero-VPS»).\n\n---\n\n## 1. Сравнительная матрица: Zapret v1 vs Zapret v2 vs ByeDPI\n\n| Параметр | Zapret v1 (`nfqws`) | Zapret v2 (`nfqws2`) | ByeDPI (`ciadpi`) |\n|---|---|---|---|\n| **Исполняемый файл** | `/usr/bin/nfqws` | `/usr/bin/nfqws2` | `/usr/bin/ciadpi` |\n| **Модель работы** | Перехват через Kernel NFQueue | Multi-Queue NFQueue с Lua | Локальный SOCKS5 / TProxy |\n| **Целевые протоколы** | HTTP, TLS (ClientHello) | HTTP, TLS, QUIC, WireGuard, UDP | HTTP, TLS |\n| **Методы фрагментации** | `split2`, `disorder`, `fake` | `multisplit`, `seqovl`, `wsize`, `fake` | `--split-pos`, `--disorder`, `--fake` |\n| **Многоуровневые цепочки** | 1 стратегия на правило | Сложные составные цепочки | Составные аргументы SOCKS |\n| **Нагрузка на CPU** | Минимальная (< 1%) | Низкая (< 2%) | Низкая (< 2%) |\n| **Оптимально для** | Базового DPI, старых роутеров | YouTube 4K, Discord, ТСПУ | Не-root окружений, SOCKS-роутинга |\n\n---\n\n## 2. Принципы и техники десинхронизации пакетов\n\nСистемы глубокого анализа пакетов (DPI / ТСПУ) анализируют заголовки сетевых протоколов (такие как `SNI` в расширении TLS ClientHello или заголовок `Host` в HTTP) для блокировки или замедления трафика. \n\nДесинхронизация обманывает конечный автомат DPI, заставляя его потерять контекст TCP-сессии или пропустить целевой заголовок, в то время как целевой сервер корректно собирает исходный поток данных.\n\n```\nИсходный поток: [TLS ClientHello с SNI] ──────────► (Блокируется ТСПУ / DPI)\n\nДесинхронизация: [Fake-пакет с неверной суммой/TTL] ──► (DPI сбрасывает состояние)\n [Фрагмент 1: Начало ClientHello] ───► (DPI не видит полный SNI)\n [Фрагмент 2: Окончание данных] ─────► (Сервер собирает TCP-поток)\n```\n\n### 2.1. Основные стратегии обхода", "embedding": []}, {"id": 12, "file": "04_DPI_BYPASS_ENGINES.md", "heading": "3.1. Пример настройки Zapret v2 (`/etc/config/tachyon`)", "text": "[Фрагмент 1: Начало ClientHello] ───► (DPI не видит полный SNI)\n [Фрагмент 2: Окончание данных] ─────► (Сервер собирает TCP-поток)\n```\n\n### 2.1. Основные стратегии обхода\n\n1. **`split2` / `multisplit` (Многопозиционное разделение)**:\n * Разрезает TCP-сегмент непосредственно внутри поля TLS SNI или заголовка HTTP Host. Оборудование DPI не выполняет глубокую реассемблинг-сборку мелких фрагментов, а стек TCP целевого сервера склеивает поток без потерь.\n2. **`disorder` / `disorder2` (Изменение порядка доставки)**:\n * Отправляет вторую часть пакета раньше первой с корректными TCP Sequence Numbers. DPI видит фрагменты не по порядку и пропускает инспекцию.\n3. **`fake` / `fake_sni` (Внедрение фейковых пакетов)**:\n * Отправляет поддельный пакет TLS ClientHello с намеренно заниженным TTL (Time To Live). DPI перехватывает поддельный пакет и считает соединение легитимным, после чего пакет угасает в сети, не доходя до целевого сервера.\n4. **`seqovl` (Наложение порядковых номеров / Sequence Overlap)**:\n * Посылает пакет с перекрывающимся диапазоном TCP Sequence. Стек TCP на сервере отбрасывает дублирующиеся байты, тогда как DPI парсит неверные данные и теряет контроль над сессией.\n5. **`wsize` (Манипуляция размером окна TCP Window Size)**:\n * Принудительно устанавливает размер TCP-окна в 1–2 байта, заставляя клиент слать данные микросегментами, что ломает эвристики DPI.\n\n---\n\n## 3. Конфигурация и управление в UCI\n\n### 3.1. Пример настройки Zapret v2 (`/etc/config/tachyon`)\n\n```ini\nconfig provider 'zapret2'\n option enabled '1'\n option daemon_bin '/usr/bin/nfqws2'\n option qnum '201'\n option args_tcp '--dpi-desync=multisplit --dpi-desync-split-pos=1,midsld --dpi-desync-seqovl=1 --dpi-desync-fooling=badseq'\n option args_udp '--dpi-desync=fake --dpi-desync-any-protocol=1 --dpi-desync-cutoff=d4'\n\nconfig rule 'youtube_rule'\n option enabled '1'\n option name 'YouTube 4K Desync'\n option action 'zapret2'\n list domain_pattern 'googlevideo.com'", "embedding": []}, {"id": 13, "file": "04_DPI_BYPASS_ENGINES.md", "heading": "5. Интеграция AmneziaWG в sing-box-extended (2026)", "text": "option args_udp '--dpi-desync=fake --dpi-desync-any-protocol=1 --dpi-desync-cutoff=d4'\n\nconfig rule 'youtube_rule'\n option enabled '1'\n option name 'YouTube 4K Desync'\n option action 'zapret2'\n list domain_pattern 'googlevideo.com'\n list domain_pattern 'youtube.com'\n list domain_pattern 'ytimg.com'\n list domain_pattern 'discord.gg'\n list domain_pattern 'discord.com'\n```\n\n### 3.2. Пример настройки ByeDPI\n\n```ini\nconfig provider 'byedpi'\n option enabled '1'\n option daemon_bin '/usr/bin/ciadpi'\n option listen_ip '127.0.0.1'\n option listen_port '1080'\n option args '--split-pos 1 --disorder 1 --fake -1 --ttl 8'\n```\n\n---\n\n## 4. Мультиплексирование NFQueue и изоляция очередей\n\n* Подсистема ядра Linux `nfnetlink_queue` требует уникальный номер очереди (`qnum`) для каждого запущенного процесса демона.\n* Модуль `providers/nfqueue/runtime.uc` в Tachyon динамически управляет выделением очередей:\n * Базовая очередь Zapret v1: `200`\n * Базовая очередь Zapret v2: `201`\n * Очередь Strategy Fuzzer: `298` / `299`\n* При одновременной активации Zapret v1 и Zapret v2 для разных правил маршрутизации Tachyon гарантирует строгую изоляцию очередей и исключает конфликты PID и fwmark.\n\n---\n\n## 5. Интеграция AmneziaWG в sing-box-extended (2026)\n\nПроверено против релизного бинарника `v1.13.18-extended-2.6.5` (`shtorm-7/sing-box-extended`):\n\n- Секция `endpoint.amnezia` полностью реализована в форке: `AmneziaOptions` (`transport/wireguard/endpoint_options.go`) → параметры IPC `jc / jmin / jmax / s1-s4 / h1-h4 / i1-i5`.\n- Форк `shtorm-7/wireguard-go v0.0.4-extended-1.5.3`: пакеты `I1–I5` отправляются отдельными дейтаграммами **перед** инициализацией рукопожатия (`SendHandshakeInitiation`), значение задается в hex-формате.\n- Генератор Tachyon (`singbox/generator_outbounds.uc` -> `add_awg_endpoint`) формирует конфигурацию, полностью совместимую со схемой форка:\n - Секция `peer` содержит обязательный `allowed_ips`.\n - Параметры `pre_shared_key` и `persistent_keepalive_interval` опциональны.", "embedding": []}, {"id": 14, "file": "04_DPI_BYPASS_ENGINES.md", "heading": "Вывод доступной матрицы стратегий", "text": "- Генератор Tachyon (`singbox/generator_outbounds.uc` -> `add_awg_endpoint`) формирует конфигурацию, полностью совместимую со схемой форка:\n - Секция `peer` содержит обязательный `allowed_ips`.\n - Параметры `pre_shared_key` и `persistent_keepalive_interval` опциональны.\n - Hex-значения `i1–i5` передаются через `uci_bin_to_hex` без повторного кодирования.\n- **Диагностика:** если AWG/WARP-туннель имеет состояние «TX есть, RX нет» на sing-box-extended, конфиг применен корректно — причина во внешней UDP-фильтрации провайдера или блокировке сервера.\n\n---\n\n## 6. Strategy Fuzzer и автоматический подбор стратегий\n\nTachyon включает встроенный модуль автоматического тестирования стратегий обхода — **Strategy Fuzzer & Auto-Tuner** (`diagnostics/fuzzer.uc`), который избавляет от необходимости вручную подбирать флаги `nfqws2` или `ciadpi`.\n\n### 6.1. Механизм работы\n- **Изолированный сэндбокс:** Тестирование выполняется через временные очереди `qnum 298/299` с сокетной меткой `0x08000000` (для Zapret) либо через локальный порт `127.0.0.1:11089` (для ByeDPI), не затрагивая активный домашний трафик.\n- **Метрический скоринг:** Замеряются время TLS-рукопожатия, TTFB (время до первого байта), битрейт загрузки чанка потокового видео (MB/s) и HTTP-код ответа.\n- **1-Click Apply:** Победившая стратегия мгновенно применяется к правилу YouTube/Discord или в глобальные параметры провайдера с автоматической перезагрузкой службы.\n\n### 6.2. Команды управления через CLI\n```sh\n# Запуск бенчмарка стратегий\ntachyon fuzzer_start <engine> <target> [custom_url] [rule_section]\n\n# Просмотр текущего прогресса и результатов\ntachyon fuzzer_status\n\n# Остановка фонового бенчмарка\ntachyon fuzzer_stop\n\n# Применение выбранной стратегии в UCI\ntachyon fuzzer_apply <engine> \"<strategy_args>\" [target_rule_or_global]\n\n# Вывод доступной матрицы стратегий\ntachyon fuzzer_strategies\n```", "embedding": []}, {"id": 15, "file": "05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md", "heading": "3. Local Rule Doctor & 13 Quick Fix Codes", "text": "# 05. AI Stack, AI Doctor & Autonomous Self-Healing\n\n## 1. Overview of Tachyon AI Stack\n\nTachyon provides a dual-layer AI and autonomous resilience stack:\n1. **Autonomous Layer (Local Rule Doctor & Watchdog)**: Runs locally on the router every 5–15 seconds, detects network drops, memory leaks, DNS deadlocks, and time desync without requiring internet access or API tokens.\n2. **Cognitive Layer (AI Doctor v2.5)**: Deep diagnostics powered by LLMs (OpenAI, Anthropic Claude, DeepSeek, or local Ollama/OpenRouter models) with contextual prompt enrichment and automated Multi-Fix generation.\n3. **Agent Integration Layer (HTTP REST Agent API & OpenAPI 3.0)**: Programmatic interface for autonomous AI agents (Cursor, Claude Code, AutoGPT, ChatGPT Custom GPTs, N8N, Dify).\n\n---\n\n## 2. AI Doctor Architecture (v2.5)\n\n```mermaid\ngraph TD\n subgraph Data Collection\n R1[Process Probes: singbox/zapret/dnsmasq]\n R2[Kernel Metrics: conntrack, mem, uptime]\n R3[Watchdog History: failure streaks, OOM events]\n R4[System Logs: 15 most recent critical lines]\n end\n\n R1 --> Aggregator[snapshot.uc Assembler]\n R2 --> Aggregator\n R3 --> Aggregator\n R4 --> Aggregator\n\n Aggregator --> Prompt[Deep Context LLM Prompt]\n Prompt --> LLM[LLM Provider: OpenAI / Claude / DeepSeek / Custom]\n \n LLM --> Verdict[Structured Diagnosis Report]\n LLM --> MultiFix[Multi-Fix Action Plan: FIX: code1, code2]\n \n MultiFix --> Exec[Local Rule Doctor Execution Engine]\n Exec --> Result[Applied Fixes & Service State Refresh]\n```\n\n---\n\n## 3. Local Rule Doctor & 13 Quick Fix Codes\n\nThe execution engine in `diagnostics/runtime.uc` maps standardized fix codes to automated shell/ucode repair procedures:\n\n| Code | Target Subsystem | Action Performed |\n|---|---|---|\n| `start_singbox` | sing-box | Restarts failed sing-box process via procd. |\n| `rebuild_rules` | nftables | Flushes and recompiles `inet TachyonTable` ruleset. |\n| `fix_dnsmasq` | dnsmasq | Restarts dnsmasq and checks `/tmp/etc/dnsmasq.conf.*`. |", "embedding": []}, {"id": 16, "file": "05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md", "heading": "4.1. Authentication Model", "text": "| `start_singbox` | sing-box | Restarts failed sing-box process via procd. |\n| `rebuild_rules` | nftables | Flushes and recompiles `inet TachyonTable` ruleset. |\n| `fix_dnsmasq` | dnsmasq | Restarts dnsmasq and checks `/tmp/etc/dnsmasq.conf.*`. |\n| `fix_resolv_symlink` | DNS | Restores broken `/etc/resolv.conf` -> `/tmp/resolv.conf.d/resolv.conf.auto` link. |\n| `start_watchdog` | Watchdog | Restarts the background watchdog supervisor process. |\n| `restart_singbox_dns` | sing-box DNS | Resets internal sing-box DNS server module and cache. |\n| `fix_uci_config` | UCI | Restores `/etc/config/tachyon` from the latest valid atomic backup. |\n| `fix_wan_interface` | Networking | Runs `ifup wan` to bounce the primary uplink interface. |\n| `fix_gateway` | Networking | Re-establishes default routing gateway via `/etc/init.d/network restart`. |\n| `clear_dns_cache` | Cache | Flushes dnsmasq cache, deletes sing-box `cache.db`, and restarts DNS. |\n| `update_subscriptions`| Subscriptions | Triggers asynchronous background download and refresh of proxy subscriptions. |\n| `reset_firewall` | Firewall | Full restart of OpenWrt firewall (`/etc/init.d/firewall restart`). |\n| `restart_network` | Network Stack | Full restart of OpenWrt network daemon (`/etc/init.d/network restart`). |\n| `fix_system_time` | System NTP | Resynchronizes router clock via NTP pool servers (`ntpd -q -p ...`). |\n| `flush_conntrack` | Kernel | Flushes congested `nf_conntrack` table during connection floods. |\n| `fix_bootstrap_dns` | Resolver | Unblocks sing-box primary bootstrap resolvers and breaks circular loops. |\n| `optimize_mtu` | Tunnels | Auto-calculates optimal MTU (1280–1420) for WireGuard / AmneziaWG interfaces. |\n| `restore_native_internet` | Emergency | One-click full teardown of Tachyon proxying; returns pure native WAN routing. |\n\n---\n\n## 4. HTTP REST Agent API & OpenAPI 3.0.3\n\nTachyon exposes a standardized REST API hosted under `/cgi-bin/tachyon-agent/` via OpenWrt's native `uhttpd`.\n\n### 4.1. Authentication Model", "embedding": []}, {"id": 17, "file": "05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md", "heading": "4.3. Full Endpoint Index", "text": "| `restore_native_internet` | Emergency | One-click full teardown of Tachyon proxying; returns pure native WAN routing. |\n\n---\n\n## 4. HTTP REST Agent API & OpenAPI 3.0.3\n\nTachyon exposes a standardized REST API hosted under `/cgi-bin/tachyon-agent/` via OpenWrt's native `uhttpd`.\n\n### 4.1. Authentication Model\n* **Read-Only Endpoints**: Accessible within LAN without authentication (or secured via firewall).\n* **Write Endpoints**: Require Bearer token authentication:\n ```http\n POST /cgi-bin/tachyon-agent/ai-doctor/fix\n Authorization: Bearer <agent_api_token>\n Content-Type: application/json\n\n {\"fix\": \"clear_dns_cache,start_singbox\"}\n ```\n\n### 4.2. OpenAPI 3.0.3 Specification\n* The live OpenAPI JSON schema is available at:\n ```\n GET /cgi-bin/tachyon-agent/openapi.json\n ```\n* This schema allows instant import into **ChatGPT Custom GPT Actions**, **N8N HTTP Request Nodes**, **Dify**, and **Flowise**.\n\n### 4.3. Full Endpoint Index\n\n| Method | Endpoint | Auth Required | Description |\n|---|---|---|---|\n| `GET` | `/health` | No | Lightweight JSON health status probe. |\n| `GET` | `/snapshot` | No | Full system snapshot (interfaces, memory, proxy status). |\n| `GET` | `/diagnose` | No | Local Rule Doctor diagnosis report. |\n| `GET` | `/logs` | No | Returns last 100 lines of Tachyon system log. |\n| `GET` | `/config` | No | Returns sanitized UCI configuration. |\n| `GET` | `/tools` | No | OpenAI Function Calling / MCP tool definitions. |\n| `GET` | `/openapi.json` | No | OpenAPI 3.0.3 specification JSON. |\n| `POST`| `/heal` | **Bearer** | Triggers manual Watchdog self-healing cycle. |\n| `POST`| `/ai-doctor/fix` | **Bearer** | Applies one or more quick-fix codes. |\n| `POST`| `/restart` | **Bearer** | Restarts specified service (`singbox`, `watchdog`, `dnsmasq`). |\n| `POST`| `/reload` | **Bearer** | Soft-reloads configuration and routing tables. |\n| `POST`| `/config/set` | **Bearer** | Updates specific UCI options. |\n| `POST`| `/section/toggle` | **Bearer** | Enables or disables a routing rule section. |", "embedding": []}, {"id": 18, "file": "05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md", "heading": "4.3. Full Endpoint Index", "text": "| `POST`| `/reload` | **Bearer** | Soft-reloads configuration and routing tables. |\n| `POST`| `/config/set` | **Bearer** | Updates specific UCI options. |\n| `POST`| `/section/toggle` | **Bearer** | Enables or disables a routing rule section. |\n| `POST`| `/domain/add` | **Bearer** | Appends domain pattern to target rule list. |", "embedding": []}, {"id": 19, "file": "06_FRONTEND_LUCI_TYPESCRIPT.md", "heading": "3.1. Key Services (`src/tachyon/services/`)", "text": "# 06. Frontend Architecture (LuCI & TypeScript)\n\n## 1. Frontend Architecture Overview\n\nTachyon's web UI is authored as a single-page application in **TypeScript** under `fe-app-tachyon/` and compiled into a standalone JavaScript view under `luci-app-tachyon/htdocs/luci-static/resources/view/tachyon/main.js`.\n\n```\nfe-app-tachyon/ (TypeScript Source)\n │\n ▼ (npm run build: tsc --noEmit && tsup)\n │\n[tsup build + baseclass.extend transformation]\n │\n ▼\nluci-app-tachyon/htdocs/luci-static/resources/view/tachyon/main.js (LuCI Asset)\n```\n\n---\n\n## 2. The LuCI `baseclass.extend()` Patch Mechanism\n\nLuCI uses a custom asynchronous class system (`baseclass.extend({...})`) rather than standard ES modules or Webpack bundles.\n\n* `fe-app-tachyon/tsup.config.ts` compiles the TypeScript entry point (`src/main.ts`) into an ES module.\n* A custom post-processing step inside `tsup.config.ts` transforms the compiled file:\n 1. Strips ESM `export default` statements.\n 2. Wraps the controller inside LuCI's expected `return baseclass.extend({...})` pattern.\n 3. Injects global LuCI helper references (`ui`, `rpc`, `uci`, `fs`, `_`).\n\n> [!IMPORTANT]\n> **Do not attempt to convert `main.js` back into a standard ES module export.** This LuCI bridge is intentional and strictly required for compatibility with all OpenWrt web themes (Bootstrap, Material, Argon, OpenWrt-Two).\n\n---\n\n## 3. Reactive State Management & Services\n\nThe frontend does not use heavy external frameworks (like React or Vue) to keep package size minimal ($\\approx$ 500 KB uncompressed, $\\approx$ 90 KB gzipped). Instead, it uses lightweight TypeScript observable stores:\n\n### 3.1. Key Services (`src/tachyon/services/`)\n\n| Service | File | Purpose |\n|---|---|---|\n| `StoreService` | `store.service.ts` | Central reactive data store with subscription listeners. |\n| `UiStateService` | `uiState.service.ts` | Tracks UI view state, tab switching, and modal states. |\n| `RuntimeUiStateService`| `runtimeUiState.service.ts`| Polling and caching of backend service metrics and active jobs. |", "embedding": []}, {"id": 20, "file": "06_FRONTEND_LUCI_TYPESCRIPT.md", "heading": "4.1. The Updates & Installation Modal (`renderUpdateProgressModal.ts`)", "text": "| `UiStateService` | `uiState.service.ts` | Tracks UI view state, tab switching, and modal states. |\n| `RuntimeUiStateService`| `runtimeUiState.service.ts`| Polling and caching of backend service metrics and active jobs. |\n| `SocketService` | `socket.service.ts` | WebSocket client for real-time log streaming when available. |\n| `TachyonLogWatcher` | `tachyonLogWatcher.service.ts`| Logread stream deduplication and notification dispatcher. |\n\n---\n\n## 4. Tabs & UI View Structure\n\n```\nsrc/tachyon/tabs/\n├── dashboard/ # Live status, RTT ping matrix, traffic toggles\n├── diagnostic/ # AI Doctor modal, Local Rule Doctor, Emergency Fallback\n├── rules/ # Selective routing rules, domain/IP lists, client matchers\n├── providers/ # Zapret v1, Zapret v2, ByeDPI configurations\n├── updates/ # Component installer, version checks, streaming log modal\n└── settings/ # DNS settings, Telegram bot credentials, AI Doctor API keys\n```\n\n### 4.1. The Updates & Installation Modal (`renderUpdateProgressModal.ts`)\n* Provides a streaming log console that polls `/usr/bin/tachyon` output asynchronously via `componentActionLog(jobId, offset)`.\n* Features:\n * Non-blocking operation: router performs installation in background.\n * Real-time timer and progress badge.\n * Preserves output logs and green success/red error banners.\n * Prevents premature auto-close so users can inspect package manager details.\n * Graceful countdown timer for Tachyon package reloads.", "embedding": []}, {"id": 21, "file": "07_BUILD_TESTS_AND_DEPLOYMENT.md", "heading": "2.1. Installer Lifecycle", "text": "# 07. Build System, Testing & Deployment Pipeline\n\n## 1. Release Package Compilation (`build.sh`)\n\nTachyon produces both legacy **IPK** (opkg) and modern **APK** (apk-tools, OpenWrt 25.x+) packages.\n\n### 1.1. Running the Build\n\n```bash\nbash build.sh <x.y.z> [output-dir]\n```\n\n* **Semver Requirement**: `build.sh` strictly enforces semantic versioning (`x.y.z`).\n* **Cross-Filesystem WSL Protection**: When executed under Windows Subsystem for Linux (WSL), `build.sh` automatically clones the source repository into the native Linux filesystem (`/tmp/tachyon-build-...`) before packaging to avoid Windows filesystem metadata and permission corruption.\n* **Outputs**:\n * `dist/release-final/tachyon_<version>_all.ipk`\n * `dist/release-final/luci-app-tachyon_<version>_all.ipk`\n * `dist/release-final/tachyon-<version>.apk`\n * `dist/release-final/luci-app-tachyon-<version>.apk`\n\n---\n\n## 2. End-User Installer (`install.sh`)\n\nTachyon provides an automated one-liner installer:\n\n```bash\nwget -O /tmp/tachyon-setup.sh https://raw.githubusercontent.com/Dushnilin/tachyon/main/install.sh && sh /tmp/tachyon-setup.sh\n```\n\n### 2.1. Installer Lifecycle\n1. **Architecture & OS Detection**: Detects OpenWrt version (23.05, 24.10, 25.x, SNAPSHOT), CPU architecture (`mips`, `mipsel`, `arm_cortex-a7`, `aarch64_cortex-a53`, `x86_64`), and package manager (`opkg` vs `apk`).\n2. **Dependency Resolution**: Ensures `ucode`, `ucode-mod-fs`, `ucode-mod-uci`, `ucode-mod-ubus`, `kmod-nft-tproxy`, `kmod-nft-queue`, `ca-bundle` are installed.\n3. **Legacy Migration**: Automatically detects `/etc/config/forkop` or `/etc/config/podkop` and seamlessly migrates all rules and servers to `/etc/config/tachyon`.\n4. **Binary Provisioning**: Downloads pre-compiled, optimized sing-box, Zapret, or ByeDPI binaries tailored for the router's target architecture.\n5. **Zero-Reboot Initialization**: Configures UCI defaults, registers LuCI menus, builds initial rulesets, and starts services without requiring a full router reboot.", "embedding": []}, {"id": 22, "file": "07_BUILD_TESTS_AND_DEPLOYMENT.md", "heading": "4. Key Developer Gotchas & Conventions", "text": "4. **Binary Provisioning**: Downloads pre-compiled, optimized sing-box, Zapret, or ByeDPI binaries tailored for the router's target architecture.\n5. **Zero-Reboot Initialization**: Configures UCI defaults, registers LuCI menus, builds initial rulesets, and starts services without requiring a full router reboot.\n\n---\n\n## 3. Testing Workflows\n\n### 3.1. Frontend Unit Tests (vitest)\n\n```bash\ncd fe-app-tachyon\nnpm test # Runs all 522+ vitest unit tests\nnpm run build # Verifies TypeScript compilation and LuCI bundle packaging\n```\n\n### 3.2. Backend Integration Tests & ucode Syntax Linting\n\nBackend tests require the `ucode` binary. On development machines without local ucode, tests run inside the Docker CI image:\n\n```bash\n# 1. ucode syntax check across all 60+ modules\ndocker run --rm -v \"$(pwd):/mnt\" -w /mnt ucode-ci-img:latest bash tests/ucode_syntax_lint.sh\n\n# 2. Run all backend behavioral and unit tests in parallel (-P4)\ndocker run --rm -v \"$(pwd):/mnt\" -w /mnt ucode-ci-img:latest bash tests/run_all.sh\n\n# 3. Run a specific test\ndocker run --rm -v \"$(pwd):/mnt\" -w /mnt ucode-ci-img:latest bash tests/ai_doctor_local.sh\n```\n\n### 3.3. ShellCheck Linting\n\n```bash\nshellcheck --severity=error build.sh install.sh tachyon/files/etc/init.d/* tests/**/*.sh\n```\n\n---\n\n## 4. Key Developer Gotchas & Conventions\n\n1. **LF Line Endings**: Enforced via `.gitattributes`. Committing CRLF will break shell scripts on OpenWrt target systems.\n2. **`fe-app-tachyon` Package Manager**: Always use `npm` (`npm install`, `npm test`, `npm run build`), not `yarn`.\n3. **Version Placeholder**: `__COMPILED_VERSION_VARIABLE__` in `src/constants.ts` is replaced during `build.sh` packaging. Do not remove it.\n4. **UCI Config Permissions**: `/etc/config/tachyon` must remain `chmod 600` because it can store sensitive Telegram bot tokens and API keys.", "embedding": []}, {"id": 23, "file": "08_UCI_CONFIGURATION_SCHEMA.md", "heading": "1. Section: `config settings 'settings'`", "text": "# 08. Complete UCI Configuration Schema Reference\n\nThe primary configuration for Tachyon is stored at `/etc/config/tachyon` (UCI format, mode `0600`).\n\n---\n\n## 1. Section: `config settings 'settings'`\n\nGlobal settings defining service behaviour, DNS resolution, watchdog parameters, Telegram integration, and AI Doctor.\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `enabled` | `boolean` (`0`/`1`) | `1` | Master toggle for Tachyon service. |\n| `log_level` | `string` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error`. |\n| `dns_mode` | `string` | `doh` | DNS routing mode: `direct`, `doh`, `dot`, `udp`, `hosts_only`. |\n| `remote_dns_server` | `string` | `https://1.1.1.1/dns-query` | Upstream secure DNS resolver for proxied domains. |\n| `direct_dns_server` | `string` | `77.88.8.8` | Fallback DNS resolver for direct / local domains. |\n| `tproxy_port` | `integer` | `10080` | Local TCP/UDP transparent proxy port for sing-box. |\n| `dns_port` | `integer` | `5353` | Local DNS listening port for sing-box DNS engine. |\n| `clash_api_port` | `integer` | `9090` | sing-box Clash REST API controller port. |\n| `clash_api_secret` | `string` | `\"\"` | Secret token for sing-box Clash API. |\n| `watchdog_interval` | `integer` | `10` | Watchdog polling interval in seconds (5–60s). |\n| `memory_limit_mb` | `integer` | `0` | Dynamic `GOMEMLIMIT` cap in MB (`0` = auto 50% free RAM). |\n| `enable_telegram` | `boolean` | `0` | Enable interactive Telegram management bot. |\n| `telegram_token` | `string` | `\"\"` | Telegram Bot API token from `@BotFather`. |\n| `telegram_chat_id` | `string` | `\"\"` | Allowed Admin Telegram Chat ID(s) (comma-separated). |\n| `enable_ai_doctor` | `boolean` | `0` | Enable LLM AI Doctor diagnostic engine. |\n| `ai_doctor_provider`| `string` | `openai` | LLM Provider: `openai`, `anthropic`, `deepseek`, `custom`. |\n| `ai_doctor_model` | `string` | `\"\"` | Model override (e.g. `gpt-4o-mini`, `claude-3-5-haiku`). |\n| `ai_doctor_api_key`| `string` | `\"\"` | API key for the chosen LLM provider. |", "embedding": []}, {"id": 24, "file": "08_UCI_CONFIGURATION_SCHEMA.md", "heading": "2. Section: `config server 'name'`", "text": "| `ai_doctor_provider`| `string` | `openai` | LLM Provider: `openai`, `anthropic`, `deepseek`, `custom`. |\n| `ai_doctor_model` | `string` | `\"\"` | Model override (e.g. `gpt-4o-mini`, `claude-3-5-haiku`). |\n| `ai_doctor_api_key`| `string` | `\"\"` | API key for the chosen LLM provider. |\n| `ai_doctor_custom_url`| `string` | `\"\"` | Custom OpenAI-compatible endpoint URL (e.g. OpenRouter/Ollama). |\n| `agent_api_token` | `string` | `\"\"` | Bearer token for HTTP REST Agent API write access. |\n\n---\n\n## 2. Section: `config server 'name'`\n\nDefines an individual manual proxy outbound node.\n\n| Option | Type | Required | Description |\n|---|---|---|---|\n| `type` | `string` | Yes | Protocol: `vless`, `vmess`, `shadowsocks`, `trojan`, `hysteria2`, `wireguard`. |\n| `server` | `string` | Yes | Remote server hostname or IPv4/IPv6 address. |\n| `server_port` | `integer` | Yes | Remote server port (e.g. `443`, `8443`). |\n| `uuid` | `string` | Conditional | User UUID for VLESS / VMess. |\n| `password` | `string` | Conditional | Password for Shadowsocks / Trojan / Hysteria2. |\n| `flow` | `string` | No | Flow control: `xtls-rprx-vision` (VLESS). |\n| `security` | `string` | No | Security type: `reality`, `tls`, `none`. |\n| `sni` | `string` | Conditional | Server Name Indication for TLS / Reality. |\n| `pbk` | `string` | Conditional | Public Key for VLESS Reality. |\n| `sid` | `string` | Conditional | Short ID for VLESS Reality (hex string). |\n| `fingerprint` | `string` | No | TLS fingerprint: `chrome`, `firefox`, `safari`, `randomized`. |\n| `method` | `string` | Conditional | Cipher method for Shadowsocks (e.g. `2022-blake3-aes-128-gcm`). |\n| `routing_mode` | `string` | No | Routing mode: `rules` (default), `direct`, `section`. |\n| `routing_section` | `string` | No | Bound routing section when `routing_mode = 'section'`. |\n| `isolate_lan_for_users` | `boolean` | No | Restrict access to private/LAN IP addresses (`1` / `0`). |\n| `isolated_users` | `list string` | No | Specific usernames (`auth_user`) restricted from LAN. If empty, restricts all users of the inbound. |", "embedding": []}, {"id": 25, "file": "08_UCI_CONFIGURATION_SCHEMA.md", "heading": "5. Section: `config hosts 'name'`", "text": "| `isolate_lan_for_users` | `boolean` | No | Restrict access to private/LAN IP addresses (`1` / `0`). |\n| `isolated_users` | `list string` | No | Specific usernames (`auth_user`) restricted from LAN. If empty, restricts all users of the inbound. |\n| `isolated_subnets` | `list string` | No | Optional custom subnets to block for isolated users (defaults to `ip_is_private: true`). |\n| `custom_route_rules` | `list string` | No | Raw JSON sing-box route rule objects injected before general routing rules. |\n\n---\n\n## 3. Section: `config subscription 'name'`\n\nDefines a remote subscription URL for automated batch node fetching.\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `enabled` | `boolean` | `1` | Enable this subscription source. |\n| `url` | `string` | Required | HTTPS / HTTP link to subscription (Base64, Clash, SIP002). |\n| `update_interval`| `integer` | `86400` | Auto-update interval in seconds (default 24 hours). |\n| `custom_user_agent`| `string` | `\"\"` | Custom User-Agent header for subscription request. |\n| `filter_keywords` | `list string` | `[]` | Include nodes matching regex/keywords. |\n| `exclude_keywords`| `list string` | `[]` | Exclude nodes matching regex/keywords. |\n\n---\n\n## 4. Section: `config rule 'name'`\n\nDefines a selective routing policy.\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `enabled` | `boolean` | `1` | Enable this routing rule. |\n| `name` | `string` | `\"\"` | Human-readable label for UI. |\n| `action` | `string` | `proxy` | Route target: `proxy`, `zapret`, `zapret2`, `byedpi`, `direct`, `hosts`. |\n| `target_server` | `string` | `\"\"` | Bound server ID or outbound tag when `action = 'proxy'`. |\n| `domain_pattern` | `list string` | `[]` | List of target domains or wildcards (e.g. `*.youtube.com`). |\n| `ip_cidr` | `list string` | `[]` | List of IP subnets (e.g. `104.16.0.0/12`). |\n| `client_group` | `string` | `\"\"` | Restrict this rule to a specific client device group. |\n\n---\n\n## 5. Section: `config hosts 'name'`", "embedding": []}, {"id": 26, "file": "08_UCI_CONFIGURATION_SCHEMA.md", "heading": "Recipe B: Hybrid Mode (Local Desync for Media + VLESS Reality for Blocked Sites)", "text": "| `ip_cidr` | `list string` | `[]` | List of IP subnets (e.g. `104.16.0.0/12`). |\n| `client_group` | `string` | `\"\"` | Restrict this rule to a specific client device group. |\n\n---\n\n## 5. Section: `config hosts 'name'`\n\nConfigures static DNS overrides and remote blocklists ingestion.\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `enabled` | `boolean` | `1` | Enable hosts mapping. |\n| `dns_hosts` | `list string` | `[]` | Static mappings in format `domain:ip` (e.g. `example.com:1.2.3.4`). |\n| `hosts_list_urls` | `list string` | `[]` | External URLs for blocklists (AdAway, StevenBlack). |\n| `update_interval` | `integer` | `86400` | Auto-refresh interval in seconds. |\n\n---\n\n## 6. Ready-to-Use Configuration Recipes\n\n### Recipe A: Zero-VPS Local DPI Bypass (YouTube + Discord)\n```ini\nconfig settings 'settings'\n option enabled '1'\n option dns_mode 'doh'\n\nconfig provider 'zapret2'\n option enabled '1'\n option daemon_bin '/usr/bin/nfqws2'\n option qnum '201'\n option args_tcp '--dpi-desync=multisplit --dpi-desync-split-pos=1,midsld --dpi-desync-seqovl=1 --dpi-desync-fooling=badseq'\n\nconfig rule 'youtube_discord'\n option enabled '1'\n option name 'YouTube & Discord Local Desync'\n option action 'zapret2'\n list domain_pattern 'googlevideo.com'\n list domain_pattern 'youtube.com'\n list domain_pattern 'ytimg.com'\n list domain_pattern 'discord.com'\n list domain_pattern 'discord.gg'\n```\n\n### Recipe B: Hybrid Mode (Local Desync for Media + VLESS Reality for Blocked Sites)\n```ini\nconfig server 'my_vps'\n option type 'vless'\n option server 'vps.example.com'\n option server_port '443'\n option uuid '12345678-1234-1234-1234-123456789abc'\n option flow 'xtls-rprx-vision'\n option security 'reality'\n option sni 'yahoo.com'\n option pbk 'XYZ...PUBLIC_KEY...'\n option sid '1a2b3c4d'\n\nconfig rule 'media_rule'\n option enabled '1'\n option action 'zapret2'\n list domain_pattern 'youtube.com'\n list domain_pattern 'googlevideo.com'", "embedding": []}, {"id": 27, "file": "08_UCI_CONFIGURATION_SCHEMA.md", "heading": "Recipe B: Hybrid Mode (Local Desync for Media + VLESS Reality for Blocked Sites)", "text": "option pbk 'XYZ...PUBLIC_KEY...'\n option sid '1a2b3c4d'\n\nconfig rule 'media_rule'\n option enabled '1'\n option action 'zapret2'\n list domain_pattern 'youtube.com'\n list domain_pattern 'googlevideo.com'\n\nconfig rule 'blocked_rule'\n option enabled '1'\n option action 'proxy'\n option target_server 'my_vps'\n list domain_pattern 'instagram.com'\n list domain_pattern 'twitter.com'\n list domain_pattern 'x.com'\n```", "embedding": []}, {"id": 28, "file": "09_TELEGRAM_BOT_ARCHITECTURE.md", "heading": "2. Command Set Reference", "text": "# 09. Telegram Bot Architecture & Management Protocol\n\nTachyon includes an embedded, high-performance Telegram management bot written entirely in **ucode** (`service/telegram.uc`).\n\n---\n\n## 1. Architectural Highlights\n\n```mermaid\ngraph LR\n User[Telegram Client] -->|Encrypted HTTPS| TGAPI[Telegram Bot API Servers]\n TGAPI -->|Long Polling: getUpdates| Daemon[Tachyon telegram.uc Daemon]\n \n Daemon --> Auth{Admin Chat ID Match?}\n Auth -->|No| Reject[Silent Ignore / Warning]\n Auth -->|Yes| Router[Command & Callback Dispatcher]\n \n Router -->|/doctor, /ai_doctor| AIDoc[AI Doctor Engine]\n Router -->|/server, /switch| SrvMgr[Server Manager]\n Router -->|/restart| SvcLife[Service Lifecycle]\n Router -->|/status| StateRep[State Assembler]\n```\n\n* **No Public IP or Port Forwarding Required**: Uses outbound long-polling (`getUpdates` with 30s timeout) to securely communicate through NAT/firewalls.\n* **Zero Overhead Memory Footprint**: Runs as a lightweight ucode process consuming under 2 MB RAM.\n* **Role-Based Access Control**: Rejects any commands from chat IDs not explicitly listed in UCI option `telegram_chat_id`.\n\n---\n\n## 2. Command Set Reference\n\n| Command | Arguments | Action |\n|---|---|---|\n| `/start` | — | Displays main welcome card and interactive control keyboard. |\n| `/status` | — | Returns real-time health card: uptime, active server, RAM usage, ping RTT. |\n| `/doctor` | — | Executes Local Rule Doctor and returns offline diagnostic report. |\n| `/ai_doctor`| — | Invokes AI Doctor with LLM reasoning and returns diagnosis + fix buttons. |\n| `/fix` | `<fix_code>` | Applies specific automated repair code (e.g. `/fix clear_dns_cache`). |\n| `/server` | — | Opens interactive server selector with inline pagination and RTT pings. |\n| `/rules` | — | Shows active routing rules with 1-click toggle switches. |\n| `/restart` | `[service]` | Restarts sing-box, dnsmasq, watchdog, or entire network stack. |\n| `/backup` | — | Sends latest atomic configuration backup directly to Telegram chat. |", "embedding": []}, {"id": 29, "file": "09_TELEGRAM_BOT_ARCHITECTURE.md", "heading": "Commit and restart service", "text": "| `/rules` | — | Shows active routing rules with 1-click toggle switches. |\n| `/restart` | `[service]` | Restarts sing-box, dnsmasq, watchdog, or entire network stack. |\n| `/backup` | — | Sends latest atomic configuration backup directly to Telegram chat. |\n\n---\n\n## 3. Inline Keyboard & Callback Query Protocol\n\nThe bot uses dynamic inline keyboards (`InlineKeyboardMarkup`) for single-tap actions without typing commands.\n\n### 3.1. Callback Data Scheme\nCallbacks follow a structured token format: `action:target:param`\n\n```\nsrv:select:node_1 # Switch active proxy server to node_1\nrule:toggle:youtube # Toggle routing rule 'youtube' on/off\nfix:apply:clear_dns_cache# Execute repair code 'clear_dns_cache'\npage:srv:2 # Navigate to page 2 of server list\n```\n\n### 3.2. Example: Server Switcher Response\n\n```json\n{\n \"chat_id\": 123456789,\n \"text\": \"⚡ <b>Выберите активный сервер:</b>\\nТекущий: <i>🇩🇪 Frankfurt VLESS (18 ms)</i>\",\n \"parse_mode\": \"HTML\",\n \"reply_markup\": {\n \"inline_keyboard\": [\n [\n {\"text\": \"🇩🇪 Frankfurt (18 ms) ✅\", \"callback_data\": \"srv:select:de_1\"},\n {\"text\": \"🇳🇱 Amsterdam (24 ms)\", \"callback_data\": \"srv:select:nl_1\"}\n ],\n [\n {\"text\": \"🇫🇮 Helsinki (31 ms)\", \"callback_data\": \"srv:select:fi_1\"},\n {\"text\": \"🇺🇸 New York (95 ms)\", \"callback_data\": \"srv:select:us_1\"}\n ],\n [\n {\"text\": \"🔄 Замерить пинг\", \"callback_data\": \"srv:ping:all\"},\n {\"text\": \"🩺 Запустить Доктора\", \"callback_data\": \"cmd:doctor\"}\n ]\n ]\n }\n}\n```\n\n---\n\n## 4. Configuration via CLI\n\n```sh\n# Set Bot Token\nuci set tachyon.settings.enable_telegram='1'\nuci set tachyon.settings.telegram_token='123456789:ABCdefGHIjklMNOpqrsTUVwxyz'\n\n# Set Authorized Chat ID(s)\nuci set tachyon.settings.telegram_chat_id='123456789'\n\n# Commit and restart service\nuci commit tachyon\n/etc/init.d/tachyon restart\n```", "embedding": []}, {"id": 30, "file": "10_HOSTS_ENGINE_AND_BLOCKLISTS.md", "heading": "Example UCI Configuration:", "text": "# 10. Hosts Engine, Blocklists & Smart Caching\n\nThe Hosts Engine (`components/hosts.uc`) provides automated background ingestion, normalization, deduplication, and caching of external host lists and static DNS overrides.\n\n---\n\n## 1. Architecture of Hosts Engine\n\n```mermaid\ngraph TD\n Sources[External Remote URLs: AdAway, StevenBlack, Custom] --> Downloader[HTTP Fetcher with Mirror Retry]\n Static[Static dns_hosts in UCI] --> Downloader\n \n Downloader --> Parser[Multi-Format Parser: Hosts, AdBlock, Domains]\n Parser --> Deduper[Deduplication & Sorting Engine]\n Deduper --> Cache[Unified Cache: /tmp/tachyon/hosts/combined.txt]\n \n Cache --> DNSMasq[dnsmasq /etc/dnsmasq.d/tachyon-hosts.conf]\n Cache --> SingboxDNS[sing-box DNS hosts rule]\n```\n\n---\n\n## 2. Multi-Format Ingestion\n\nThe parser automatically detects and normalizes multiple common blocklist formats:\n\n1. **Standard `/etc/hosts` format**:\n ```\n 0.0.0.0 ads.example.com\n 127.0.0.1 tracker.adserver.net\n ```\n2. **Domain-only list format**:\n ```\n malware-domain.org\n telemetry.app.com\n ```\n3. **AdBlock / DNSmasq syntax**:\n ```\n ||badsite.com^\n server=/blocked.com/\n address=/ads.org/0.0.0.0\n ```\n\n---\n\n## 3. GitHub Mirror Retry Resiliency\n\nWhen fetching blocklists hosted on GitHub (e.g. `raw.githubusercontent.com`), access may be blocked or throttled by regional DPI.\n\nTachyon implements an automated fallback retry chain:\n1. **Primary**: Direct HTTPS request to target URL.\n2. **Mirror 1**: `https://gh-proxy.com/<original_url>`\n3. **Mirror 2**: `https://ghfast.top/<original_url>`\n4. **Mirror 3**: `https://ghproxy.net/<original_url>`\n\nIf direct connection fails with timeout or SSL handshake error, Tachyon transparently cycles through available mirrors before reporting an error.\n\n---\n\n## 4. Dedicated Hosts Routing (`action = 'hosts'`)\n\nTachyon supports routing sections that operate purely as DNS-overriding engines without requiring an outbound proxy association.\n\n### Example UCI Configuration:", "embedding": []}, {"id": 31, "file": "10_HOSTS_ENGINE_AND_BLOCKLISTS.md", "heading": "Example UCI Configuration:", "text": "## 4. Dedicated Hosts Routing (`action = 'hosts'`)\n\nTachyon supports routing sections that operate purely as DNS-overriding engines without requiring an outbound proxy association.\n\n### Example UCI Configuration:\n```ini\nconfig rule 'adblock_section'\n option enabled '1'\n option name 'AdBlock & Anti-Tracker'\n option action 'hosts'\n list hosts_list_urls 'https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts'\n list hosts_list_urls 'https://adaway.org/hosts.txt'\n```\n\n* Domains in this section are redirected directly to `0.0.0.0` or custom IPs in dnsmasq / sing-box DNS.\n* Zero traffic is routed to external proxies, preserving VPS bandwidth and minimizing latency.", "embedding": []}, {"id": 32, "file": "11_TROUBLESHOOTING_AND_FIELD_MANUAL.md", "heading": "2. Run AI Doctor with LLM analysis", "text": "# 11. Troubleshooting & Field Diagnostic Manual\n\nA comprehensive guide for diagnosing and resolving common network, proxy, and routing issues on OpenWrt routers running Tachyon.\n\n---\n\n## 1. Quick Emergency Recovery\n\nIf router traffic drops completely or DNS resolution is broken, use the **Emergency Native Internet Restoration** command:\n\n```sh\ntachyon restore_native_internet\n```\n\nThis performs the following actions in under 200 ms:\n1. Atomically drops all nftables interception tables (`nft delete table inet TachyonTable`).\n2. Clears policy routing `table 100` and `ip rule` entries.\n3. Restores dnsmasq to stock upstream forwarders.\n4. Stops sing-box and DPI bypass daemons without rebooting the router.\n\n---\n\n## 2. Symptom Resolution Matrix\n\n| Symptom | Likely Cause | Recommended Fix / Command |\n|---|---|---|\n| **Websites fail to open, ping to 8.8.8.8 works** | DNS loop or dnsmasq forwarder crash. | `tachyon apply_quick_fix clear_dns_cache,fix_dnsmasq` |\n| **YouTube 4K buffers indefinitely** | Zapret strategy out-of-date for current ISP. | Switch Zapret v2 strategy to `multisplit` with `seqovl=1`. |\n| **sing-box fails to start after config change** | Syntax error in custom outbound or invalid UUID. | Check `/var/log/tachyon_service.log` and run `tachyon doctor`. |\n| **System clock desynchronized, TLS fails** | Router rebooted without RTC battery, NTP desync. | `tachyon apply_quick_fix fix_system_time` |\n| **High latency or packet drop under heavy load** | Kernel `nf_conntrack` table overflow. | `tachyon apply_quick_fix flush_conntrack` |\n| **VLESS Reality connection timeout** | Reality SNI domain blocked or expired short ID. | Update server SNI to accessible target (e.g. `yahoo.com`). |\n| **Router runs out of RAM (OOM Crash)** | sing-box buffer explosion on low-RAM device (128 MB). | Lower `memory_limit_mb` in UCI settings (`GOMEMLIMIT=40MiB`). |\n\n---\n\n## 3. Diagnostic Commands Reference\n\n```sh\n# 1. Run local offline rule checks\ntachyon doctor\n\n# 2. Run AI Doctor with LLM analysis", "embedding": []}, {"id": 33, "file": "11_TROUBLESHOOTING_AND_FIELD_MANUAL.md", "heading": "4. Log Inspection Paths", "text": "| **Router runs out of RAM (OOM Crash)** | sing-box buffer explosion on low-RAM device (128 MB). | Lower `memory_limit_mb` in UCI settings (`GOMEMLIMIT=40MiB`). |\n\n---\n\n## 3. Diagnostic Commands Reference\n\n```sh\n# 1. Run local offline rule checks\ntachyon doctor\n\n# 2. Run AI Doctor with LLM analysis\ntachyon ai_doctor\n\n# 3. View real-time Watchdog telemetry\ntachyon ai_status_full\n\n# 4. Inspect active nftables firewall tables\nnft list table inet TachyonTable\n\n# 5. Inspect policy routing table 100\nip route show table 100\nip rule show\n\n# 6. Stream live Tachyon system logs\nlogread -f -e tachyon\n\n# 7. Check listening ports (TProxy 10080, DNS 5353, Clash 9090)\nnetstat -tulpn | grep -E 'sing-box|tachyon|5353|10080'\n```\n\n---\n\n## 4. Log Inspection Paths\n\n| Log Location | Content Description |\n|---|---|\n| `/var/log/tachyon_service.log` | Core service lifecycle events (start, stop, reload). |\n| `/var/log/tachyon_watchdog.log` | Background supervisor health checks and loop warnings. |\n| `/tmp/ai_doctor_last.json` | JSON report of the most recent AI Doctor diagnosis. |\n| `/tmp/tachyon/sing-box.json` | Generated live configuration compiled for sing-box. |\n| `/tmp/tachyon/hosts/combined.txt` | Consolidated deduplicated hosts list. |", "embedding": []}, {"id": 34, "file": "12_UCODE_PROGRAMMING_PATTERNS.md", "heading": "2.3. Safe Error Handling (`try-catch`)", "text": "# 12. ucode Programming Patterns & Conventions\n\nA developer's guide to writing safe, high-performance, and idiomatic **ucode** modules for Tachyon on OpenWrt.\n\n---\n\n## 1. ucode vs JavaScript: Critical Distinctions\n\nWhile ucode syntax resembles JavaScript, its runtime semantics differ significantly:\n\n1. **Variables & Scope**:\n * Always declare variables with `let` or `const`.\n * Unassigned variables are `null` (not `undefined`).\n2. **Arrays vs Dictionaries**:\n * Arrays: `[1, 2, 3]`. Iterated with `for (let item in array)`.\n * Dictionaries (Objects): `{\"key\": \"value\"}`. Iterated with `for (let key, val in dict)`.\n3. **Regular Expressions**:\n * Use `match(str, /regex/)` or `replace(str, /regex/g, \"replacement\")`.\n * Global flag `/g` works with `replace()`, while `match()` returns capture groups array `[full_match, group1, ...]`.\n4. **Boolean Coercion**:\n * Empty strings `\"\"`, `0`, and `null` are falsy. Everything else is truthy.\n\n---\n\n## 2. Mandatory Core Design Patterns\n\n### 2.1. Atomic Configuration Writes\nNever overwrite active configuration files in-place. Always write to a temporary file in `/tmp/` and atomically rename:\n\n```ucode\nlet fs = require(\"fs\");\n\nfunction write_atomic(path, content) {\n let tmp_path = path + \".tmp.\" + int(time());\n let f = fs.open(tmp_path, \"w\");\n if (!f) return false;\n \n f.write(content);\n f.close();\n \n return fs.rename(tmp_path, path);\n}\n```\n\n### 2.2. Shell Argument Quoting\nWhen executing external shell commands, all user inputs must be quoted safely:\n\n```ucode\nfunction shell_quote(value) {\n return \"'\" + replace(\"\" + value, /'/g, \"'\\\\''\") + \"'\";\n}\n\nfunction safe_exec(cmd_args) {\n let parts = [];\n for (let arg in cmd_args)\n push(parts, shell_quote(arg));\n return system(join(\" \", parts));\n}\n```\n\n### 2.3. Safe Error Handling (`try-catch`)\nAll external library loading or file parsing must be wrapped in `try-catch` blocks to avoid unhandled script panics:\n\n```ucode\nlet uci_data = null;", "embedding": []}, {"id": 35, "file": "12_UCODE_PROGRAMMING_PATTERNS.md", "heading": "3. Performance & Memory Optimization Guidelines", "text": "return system(join(\" \", parts));\n}\n```\n\n### 2.3. Safe Error Handling (`try-catch`)\nAll external library loading or file parsing must be wrapped in `try-catch` blocks to avoid unhandled script panics:\n\n```ucode\nlet uci_data = null;\ntry {\n let uci = require(\"uci\").cursor();\n uci_data = uci.get_all(\"tachyon\", \"settings\");\n}\ncatch (e) {\n warn(\"Failed to load UCI settings: \" + e + \"\\n\");\n}\n```\n\n---\n\n## 3. Performance & Memory Optimization Guidelines\n\n1. **Stream Large Files**: Avoid loading multi-megabyte blocklists entirely into RAM with `fs.readfile()`. Use line-by-line streaming via `fs.open()` and `f.read(\"line\")`.\n2. **Avoid Spawning Subprocesses in Loops**: Invoking `system()` or `fs.popen()` spawns a fork-exec sequence in Linux. Use native ucode functions for string manipulation and path operations whenever possible.\n3. **Keep Modules Stateless**: Module files under `usr/lib/tachyon/` should export reusable pure functions or class definitions rather than maintaining mutable global state.", "embedding": []}, {"id": 36, "file": "13_REST_API_AND_MCP_SPECIFICATION.md", "heading": "4. Model Context Protocol (MCP) Tool Definitions", "text": "# 13. HTTP REST Agent API & Model Context Protocol (MCP) Specification\n\nTachyon provides a standardized RESTful Agent API and Model Context Protocol (MCP) integration, enabling seamless orchestration by autonomous LLM agents (ChatGPT Actions, Claude Code, Cursor, Windsurf, N8N, Dify).\n\n---\n\n## 1. REST API Overview\n\n* **Base URL**: `http://<router-ip>/cgi-bin/tachyon-agent/`\n* **OpenAPI Schema**: `http://<router-ip>/cgi-bin/tachyon-agent/openapi.json`\n* **Content-Type**: `application/json`\n\n---\n\n## 2. Authentication Model\n\n1. **Read-Only Endpoints**: Unrestricted when accessed from local LAN.\n2. **Write Endpoints**: Require HTTP Authorization header:\n ```http\n Authorization: Bearer <agent_api_token>\n ```\n\n---\n\n## 3. Endpoint Reference & Payloads\n\n### 3.1. `GET /health`\nReturns lightweight status of all core daemons.\n```json\n{\n \"status\": \"healthy\",\n \"version\": \"1.2.86\",\n \"uptime_seconds\": 18450,\n \"singbox_running\": true,\n \"watchdog_running\": true,\n \"active_server\": \"Frankfurt_VLESS_Reality\"\n}\n```\n\n### 3.2. `GET /diagnose`\nReturns Local Rule Doctor checks and suggested repair codes.\n```json\n{\n \"status\": \"warning\",\n \"checks\": {\n \"dns_loop\": false,\n \"conntrack_full\": false,\n \"time_desync\": true,\n \"singbox_ok\": true\n },\n \"suggested_fixes\": [\"fix_system_time\"]\n}\n```\n\n### 3.3. `POST /ai-doctor/fix`\nApplies one or more quick-fix codes.\n* **Request**:\n ```json\n {\n \"fix\": \"clear_dns_cache,start_singbox\"\n }\n ```\n* **Response**:\n ```json\n {\n \"success\": true,\n \"applied_fixes\": [\"clear_dns_cache\", \"start_singbox\"],\n \"details\": \"DNS cache cleared. sing-box process restarted.\"\n }\n ```\n\n---\n\n## 4. Model Context Protocol (MCP) Tool Definitions\n\nFor MCP-compatible agents (Cursor, Claude Desktop), Tachyon exports tools via `GET /cgi-bin/tachyon-agent/tools`:\n\n```json\n[\n {\n \"name\": \"tachyon_diagnose\",\n \"description\": \"Run diagnostic checks on OpenWrt router network and proxy health\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {}", "embedding": []}, {"id": 37, "file": "13_REST_API_AND_MCP_SPECIFICATION.md", "heading": "4. Model Context Protocol (MCP) Tool Definitions", "text": "```json\n[\n {\n \"name\": \"tachyon_diagnose\",\n \"description\": \"Run diagnostic checks on OpenWrt router network and proxy health\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {}\n }\n },\n {\n \"name\": \"tachyon_apply_fix\",\n \"description\": \"Apply automated repair codes to fix router network or proxy issues\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"fix_codes\": {\n \"type\": \"string\",\n \"description\": \"Comma-separated list of fix codes (e.g. clear_dns_cache,restart_singbox)\"\n }\n },\n \"required\": [\"fix_codes\"]\n }\n },\n {\n \"name\": \"tachyon_switch_server\",\n \"description\": \"Switch active proxy server node\",\n \"input_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"server_id\": {\n \"type\": \"string\",\n \"description\": \"Identifier of target proxy server\"\n }\n },\n \"required\": [\"server_id\"]\n }\n }\n]\n```", "embedding": []}, {"id": 38, "file": "14_ZAPRET2_DEEP_DIVE_MANUAL.md", "heading": "3.1. `multisplit` (Многосегментная фрагментация)", "text": "# 14. Руководство по Zapret v2 (nfqws2): Архитектура, Lua-десинхронизация и Стратегии\n\n## 1. Введение и Архитектурные отличия Zapret v2\n\nZapret v2 (`nfqws2`) — это эволюция классического `nfqws`, переписанная с акцентом на **модульную Lua-логику десинхронизации** и высокопроизводительное мультипрофилирование. В отличие от Zapret v1, где все параметры передавались через монолитные CLI-флаги `--dpi-desync-*`, в `nfqws2` обработка пакетов построена на вызове Lua-скриптов (`--lua-init`) и специализированных действий `--lua-desync`.\n\n### Ключевые преимущества `nfqws2`:\n1. **Мультипрофилирование в одном процессе:** возможность разделять правила для разных протоколов (HTTP, TLS, QUIC, UDP Voice) и диапазонов портов без запуска отдельных демонов.\n2. **Гибкое позиционирование фрагментов (`pos`):** поддержка составных позиций сплита (`pos=1,midsld,sniext+4`), позволяющих резать пакет ровно в уязвимых местах сигнатур DPI.\n3. **Управление перекрытием (`seqovl`):** внедрение контролируемого наложения TCP Sequence чисел (`seqovl=1..2`), сбивающего стейтфул-реассемблеры ТСПУ.\n4. **Контроль размера TCP окна (`wsize`):** принудительное занижение Window Size в исходящих пакетах (`wsize=1`), заставляющее сервер и стек дробить поток на однобайтовые сегменты.\n\n---\n\n## 2. Формат командной строки и Lua-инициализация\n\nTachyon запускает `nfqws2` со стандартным набором Lua-библиотек из `/opt/zapret2/lua/`:\n```bash\n/opt/zapret2/nfq2/nfqws2 \\\n --qnum=<QNUM> \\\n --fwmark=<FWMARK> \\\n --lua-init=@/opt/zapret2/lua/zapret-lib.lua \\\n --lua-init=@/opt/zapret2/lua/zapret-antidpi.lua \\\n --lua-init=@/opt/zapret2/lua/zapret-auto.lua \\\n [СТРАТЕГИИ]\n```\n\n---\n\n## 3. Функции Lua-десинхронизации (`--lua-desync`)\n\nВ `nfqws2` действия десинхронизации задаются через параметр `--lua-desync=<функция>[:ключ=значение[:ключ2=значение2]]`.\n\n### 3.1. `multisplit` (Многосегментная фрагментация)\nОсновная и самая эффективная функция против современных ТСПУ.\n- **Синтаксис:** `--lua-desync=multisplit:pos=<позиции>[:seqovl=<N>][:fooling=<метод>][:wsize=<N>]`", "embedding": []}, {"id": 39, "file": "14_ZAPRET2_DEEP_DIVE_MANUAL.md", "heading": "4. Методы дурения DPI (`fooling`)", "text": "### 3.1. `multisplit` (Многосегментная фрагментация)\nОсновная и самая эффективная функция против современных ТСПУ.\n- **Синтаксис:** `--lua-desync=multisplit:pos=<позиции>[:seqovl=<N>][:fooling=<метод>][:wsize=<N>]`\n- **Параметры `pos`:**\n - `pos=1` — сплит на 1-м байте payload (режет TLS ClientHello на этапе Handshake Type).\n - `pos=midsld` — сплит посередине Second Level Domain внутри SNI (например, `you` | `tube.com`).\n - `pos=sniext` — сплит в начале блока расширений TLS SNI.\n - `pos=sniext+4` — сплит на 4 байта глубже расширения SNI (разрывает парсер расширений DPI).\n - `pos=1,midsld,sniext+2` — тройной сплит, создающий 3 фрагмента с высоким уровнем энтропии.\n- **Параметр `seqovl` (Sequence Overlap):**\n - `seqovl=1` или `seqovl=2` — второй фрагмент отправляется со сдвигом TCP Sequence назад на 1–2 байта. DPI видит конфликт перекрытия данных и пропускает поток, в то время как целевой сервер корректно отбрасывает дублирующийся байт.\n- **Параметр `wsize`:**\n - `wsize=1` — зажимает размер TCP-окна, препятствуя реассемблингу со стороны DPI.\n\n### 3.2. `fake` (Инжекция фейковых пакетов)\nОтправка ложного ClientHello с некорректным SNI или контрольной суммой перед настоящим пакетом.\n- **Синтаксис:** `--lua-desync=fake[:ttl=<N>][:fooling=<метод>]`\n- **Параметры:**\n - `ttl=6` / `ttl=8` — Time-To-Live фейкового пакета. Должен быть достаточным, чтобы долететь до ТСПУ провайдера, но недостаточным, чтобы дойти до сервера назначения.\n - `fooling=badseq` — отправка фейка с невалидным TCP Sequence номером.\n - `fooling=md5sig` — добавление TCP Option 19 (MD5 Signature) в фейковый пакет. ТСПУ часто пассивно анализирует такой пакет и сбрасывает стейт сессии, а сервер назначения дропает его из-за отсутствия MD5-ключа.\n\n### 3.3. `split2` и `disorder2`\n- `split2:pos=<N>` — классическое деление пакета на 2 части в указанной позиции.\n- `disorder2:pos=<N>` — деление на 2 части с обратным порядком отправки (сначала хвост, затем голова).\n\n---\n\n## 4. Методы дурения DPI (`fooling`)", "embedding": []}, {"id": 40, "file": "14_ZAPRET2_DEEP_DIVE_MANUAL.md", "heading": "Instagram & Meta (TLS 1.3 / ECH)", "text": "- `split2:pos=<N>` — классическое деление пакета на 2 части в указанной позиции.\n- `disorder2:pos=<N>` — деление на 2 части с обратным порядком отправки (сначала хвост, затем голова).\n\n---\n\n## 4. Методы дурения DPI (`fooling`)\n\n| Метод | Механизм действия | Когда применять |\n|---|---|---|\n| `badseq` | Фейковый пакет имеет ACK/SEQ вне текущего окна TCP. | Универсально против большинства ТСПУ (Ростелеком, МТС, Мегафон, Билайн). |\n| `md5sig` | Пакет содержит TCP MD5 Signature Option (RFC 2385). | Эффективно, если ТСПУ валидирует опции TCP и дропает сессию. |\n| `badack` | Инвертированный или повреждённый ACK-номер. | Против DPI с жестким контролем двустороннего TCP-хэндшейка. |\n| `datanoack` | Данные в сегменте передаются без флага ACK. | Обход сигнатур, триггерящихся только на валидные ACK-сегменты. |\n\n---\n\n## 5. Готовые шаблоны стратегий под сервисы\n\n### YouTube 4K (GoogleVideo chunk stream)\n```text\n--lua-desync=multisplit:pos=1,midsld:seqovl=1:fooling=badseq\n```\n*Разрывает SNI googlevideo и ClientHello, предотвращая троттлинг видеопотока 2160p60.*\n\n### Discord (Gateway, API и Голосовые каналы UDP)\n```text\n--filter-tcp=443 --lua-desync=multisplit:pos=1,sniext+4:seqovl=1:fooling=badseq --new --filter-udp=50000-65535 --lua-desync=fake:ttl=8\n```\n*Комбинированный профиль: TCP 443 для шлюза сообщений и UDP-фейк для RTC Voice серверов.*\n\n### Instagram & Meta (TLS 1.3 / ECH)\n```text\n--lua-desync=fake:ttl=8 --lua-desync=multisplit:pos=midsld:fooling=badseq\n```\n*Низко-TTL фейк перегружает стейт ТСПУ, после чего фрагментированный TLS 1.3 хэндшейк проходит без сброса.*", "embedding": []}, {"id": 41, "file": "15_ZAPRET1_NFQWS_FIELD_GUIDE.md", "heading": "4. Перекрытие Sequence (`--dpi-desync-split-seqovl`)", "text": "# 15. Руководство по Zapret v1 (nfqws): Полная спецификация и рецепты\n\n## 1. Архитектура и принцип работы `nfqws` (Zapret v1)\n\nКлассический `nfqws` — это высокопроизводительный демон перехвата пакетов через Linux Netfilter Queue (`NFQUEUE`). Он работает на уровне ядра и L4/L7 сетевого стека, перехватывая исходящие TCP и UDP соединения до отправки в физический сетевой интерфейс и модифицируя структуру пакетов.\n\n---\n\n## 2. Основные параметры десинхронизации (`--dpi-desync`)\n\nВ Zapret v1 режим десинхронизации задается флагом `--dpi-desync=<режим1>,<режим2>`.\n\n| Режим | Описание | Механика |\n|---|---|---|\n| `split2` | Деление пакета на 2 части | Пакет режется на 2 TCP-сегмента по указанной позиции. |\n| `disorder2` | Деление с обратной отправкой | Сегменты отправляются в порядке [хвост, голова]. |\n| `fake` | Инжекция фейкового пакета | Перед реальным запросом отправляется ложный payload с низким TTL. |\n| `multisplit` | Множественная фрагментация | Пакет делится на 3+ сегмента по списку позиций. |\n| `ipfrag2` | IP-фрагментация | Фрагментация на сетевом уровне L3 (IP-пакет делится на части). |\n| `syndata` | Данные в SYN пакете | Внедрение полезной нагрузки в первый TCP SYN пакет (TCP Fast Open). |\n\n---\n\n## 3. Позиционирование сплита (`--dpi-desync-split-pos`)\n\nПараметр `--dpi-desync-split-pos` определяет точное смещение (байт), по которому происходит разрезание TCP-сегмента:\n- `--dpi-desync-split-pos=1` — сплит на 1-м байте payload. Разрывает первый байт TLS Content Type (`0x16`).\n- `--dpi-desync-split-pos=2` — сплит на 2-м байте. Разрывает версию TLS (`0x0301`).\n- `--dpi-desync-split-pos=midsld` — сплит посередине доменного имени второго уровня в SNI.\n- `--dpi-desync-split-pos=sniext+4` — сплит в блоке TLS расширений.\n- `--dpi-desync-split-pos=1,midsld` — комбинированное разделение.\n\n---\n\n## 4. Перекрытие Sequence (`--dpi-desync-split-seqovl`)\n\n- `--dpi-desync-split-seqovl=1` или `2` — при сплите второй сегмент имеет начальный Sequence номер, заходящий на N байт назад (перекрывает конец первого сегмента).", "embedding": []}, {"id": 42, "file": "15_ZAPRET1_NFQWS_FIELD_GUIDE.md", "heading": "3. State-DPI Bypass (Перекрытие TCP Sequence)", "text": "## 4. Перекрытие Sequence (`--dpi-desync-split-seqovl`)\n\n- `--dpi-desync-split-seqovl=1` или `2` — при сплите второй сегмент имеет начальный Sequence номер, заходящий на N байт назад (перекрывает конец первого сегмента).\n- ТСПУ видит коллизию данных в потоке и сбрасывает проверку, а сервер назначения корректно дедуплицирует байты по RFC 793.\n\n---\n\n## 5. Методы дурения ТСПУ (`--dpi-desync-fooling`)\n\n- `badseq` — отправка фейка с невалидным Sequence номером.\n- `md5sig` — добавление опции TCP MD5 signature, заставляющей DPI дропнуть фейк или пропустить сессию.\n- `badack` — невалидный номер подтверждения ACK.\n- `hopbyhop` — добавление IPv6 Hop-by-Hop extension header.\n\n---\n\n## 6. Проверенные рецепты для Zapret v1\n\n### 1. YouTube 4K / Web\n```text\n--dpi-desync=fake,split2 --dpi-desync-split-pos=1 --dpi-desync-ttl=8 --dpi-desync-fooling=badseq\n```\n\n### 2. RuTracker & Заблокированные HTTP/HTTPS ресурсы\n```text\n--dpi-desync=disorder2 --dpi-desync-split-pos=1 --dpi-desync-fooling=badseq\n```\n\n### 3. State-DPI Bypass (Перекрытие TCP Sequence)\n```text\n--dpi-desync=split2 --dpi-desync-split-seqovl=1 --dpi-desync-fooling=badseq\n```", "embedding": []}, {"id": 43, "file": "16_BYEDPI_CIADPI_REFERENCE.md", "heading": "2.6. Дополнительные опции", "text": "# 16. Справочник по ByeDPI (ciadpi): SOCKS5/TProxy десинхронизация\n\n## 1. Архитектура и принцип работы ByeDPI (`ciadpi`)\n\n`ciadpi` (ByeDPI) — это легковесный локальный прокси-сервер (SOCKS5 / Transparent TCP), который принимает исходящий трафик и выполняет фрагментацию и манипуляцию пакетами на сокетовом уровне (L7/L4). \n\n### Ключевое отличие от Zapret:\n- Zapret работает через перехват `NFQUEUE` (L3/L4 фильтрация ядра).\n- ByeDPI работает как SOCKS5 прокси (по умолчанию порт `4539` в Tachyon) или прозрачный прокси, модифицируя TCP payload непосредственно перед системным вызовом `send()`/`write()`.\n\n---\n\n## 2. Основные параметры командной строки ByeDPI\n\n### 2.1. Фрагментация (`--split` / `-s`)\n- `--split <позиция>` или `-s <позиция>`\n- **Значения позиции:**\n - `1` — сплит на 1-м байте payload.\n - `2` — сплит на 2-м байте.\n - `1+sniext` — сплит в начале блока TLS SNI расширений.\n - `midsld` — сплит посередине SLD домена.\n\n### 2.2. Изменение порядка сегментов (`--disorder` / `-d`)\n- `--disorder <позиция>` или `-d <позиция>`\n- Отправляет первый сегмент с задержкой или после второго сегмента (out-of-order delivery).\n\n### 2.3. Инжекция фейковых пакетов (`--fake` / `-f` и `--ttl` / `-t`)\n- `--fake <смещение>` или `-f <смещение>` — смещение вставки фейкового пакета (`-1` = перед началом реального запроса).\n- `--ttl <N>` или `-t <N>` — Time-To-Live для фейковых пакетов (обычно `4..8` в зависимости от провайдера).\n\n### 2.4. Out-of-Band данные (`--oob` / `-o`)\n- `--oob <смещение>` или `-o <смещение>` — отправка одного срочного байта TCP OOB (Urgent Pointer) на указанном смещении. Ломает разбор буфера в DPI, заставляя его пропустить пакет.\n\n### 2.5. Автоматический режим (`--auto` / `-a`)\n- `--auto=t,r,a,s`\n- Адаптивный режим подбора: ByeDPI автоматически пробует комбинации флагов при обнаружении сброса соединения или таймаута:\n - `t` — TLS Record splitting\n - `r` — Reverse disorder\n - `a` — Auto-ttl\n - `s` — Simple split\n\n### 2.6. Дополнительные опции\n- `--tlsrec <N>` / `-r <N>` — деление одного ClientHello на несколько независимых TLS Records.", "embedding": []}, {"id": 44, "file": "16_BYEDPI_CIADPI_REFERENCE.md", "heading": "4. Агрессивный низко-TTL фейк", "text": "- `t` — TLS Record splitting\n - `r` — Reverse disorder\n - `a` — Auto-ttl\n - `s` — Simple split\n\n### 2.6. Дополнительные опции\n- `--tlsrec <N>` / `-r <N>` — деление одного ClientHello на несколько независимых TLS Records.\n- `--ip-frag` — включение фрагментации на уровне IP.\n- `--mod-http` / `-M` — модификация HTTP заголовков (манипуляция Host/символами переноса строки).\n\n---\n\n## 3. Рецепты ByeDPI\n\n### 1. Универсальный адаптивный авто-режим\n```text\n-o 2 --auto=t,r,a,s -d 2\n```\n\n### 2. Disorder + Fake с контролем TTL\n```text\n--split 1 --disorder 1 --fake -1 --ttl 8\n```\n\n### 3. SNI Extension Split + Fake\n```text\n-s 1+sniext -f -1 -t 6\n```\n\n### 4. Агрессивный низко-TTL фейк\n```text\n--fake -1 --ttl 4 --disorder 1 --split 1\n```", "embedding": []}, {"id": 45, "file": "17_TSPU_DPI_SIGNATURES_AND_COUNTERS.md", "heading": "2.3. Instagram & Meta (TLS 1.3 / ECH)", "text": "# 17. Сигнатуры ТСПУ (РКН) и методы противодействия десинхронизацией\n\n## 1. Архитектура и принципы работы ТСПУ\n\nТСПУ (Технические средства противодействия угрозам) — это аппаратно-программные комплексы глубокого анализа пакетов (DPI), установленные на сетях операторов связи в РФ. \n\n### Основные режимы фильтрации:\n1. **Пассивный анализ (In-line / TAP):** ТСПУ прослушивает зеркалированный трафик. При обнаружении запрещенного SNI или URL генерирует и инжектирует TCP RST пакет в обе стороны соединения.\n2. **Активный дроп (In-line Drop):** ТСПУ установлен в разрыв канала и физически отбрасывает пакеты сессии, вызывая `Connection Timeout` или `EOF`.\n3. **Троттлинг (Шейпинг по L7-сигнатурам):** Ограничение пропускной способности (например, до 128 Кбит/с) при обнаружении определённых потоков данных (YouTube `googlevideo.com` CDN).\n\n---\n\n## 2. Анализ блокировок по ключевым сервисам\n\n### 2.1. YouTube (GoogleVideo 4K троттлинг)\n- **Механика блокировки:** ТСПУ анализирует TLS ClientHello при обращении к CDN-нодам `rr*.googlevideo.com`. При совпадении сигнатуры ТСПУ не закрывает соединение сразу, а переводит TCP-сессию в режим искусственного ограничения скорости или отбрасывает чанки видео.\n- **Эффективное противодействие:**\n - `multisplit:pos=1,midsld:seqovl=1:fooling=badseq` (Zapret v2)\n - `fake,split2:pos=1:ttl=8:fooling=badseq` (Zapret v1)\n - Сплит на `midsld` разрывает домен `googlevideo` пополам, предотвращая сработку строкового парсера ТСПУ.\n\n### 2.2. Discord (Gateway + Голосовые каналы RTC)\n- **Механика блокировки:** Блокировка состоит из двух компонентов:\n 1. TCP 443 — шлюз сообщений и API (`discord.com`, `gateway.discord.gg`).\n 2. UDP 50000-65535 — голосовые сессии WebRTC / Voice.\n- **Эффективное противодействие:**\n - Мультипрофиль `zapret2`:\n - Для TCP 443: `--filter-tcp=443 --lua-desync=multisplit:pos=1,sniext+4:seqovl=1:fooling=badseq`\n - Для UDP Voice: `--filter-udp=50000-65535 --lua-desync=fake:ttl=8`\n\n### 2.3. Instagram & Meta (TLS 1.3 / ECH)\n- **Механика блокировки:** ТСПУ сбрасывает TCP-соединение инжекцией RST-пакета сразу после получения первого ClientHello с открытым SNI `instagram.com`.", "embedding": []}, {"id": 46, "file": "17_TSPU_DPI_SIGNATURES_AND_COUNTERS.md", "heading": "3. Вычисление оптимального TTL до ТСПУ", "text": "- Для UDP Voice: `--filter-udp=50000-65535 --lua-desync=fake:ttl=8`\n\n### 2.3. Instagram & Meta (TLS 1.3 / ECH)\n- **Механика блокировки:** ТСПУ сбрасывает TCP-соединение инжекцией RST-пакета сразу после получения первого ClientHello с открытым SNI `instagram.com`.\n- **Эффективное противодействие:**\n - Низко-TTL фейк с `fooling=badseq` или `fooling=md5sig`, за которым следует сегментированный TLS-хэндшейк. ТСПУ «съедает» фейковый пакет и блокирует его, игнорируя последующий настоящий запрос.\n\n### 2.4. RuTracker & Сайты из реестра РКН\n- **Механика блокировки:** HTTP перенаправление на заглушку провайдера (302 Redirect) или TCP RST на HTTPS SNI.\n- **Эффективное противодействие:**\n - `disorder2:pos=1` или `split2:pos=1:seqovl=1` нарушает сборку HTTP/TLS заголовка в DPI.\n\n---\n\n## 3. Вычисление оптимального TTL до ТСПУ\n\nДля стратегий с инжекцией фейковых пакетов (`fake`) критически важно подобрать параметр `ttl`:\n- **Слишком маленький TTL (< 3):** фейковый пакет умирает на маршрутизаторах провайдера до того, как долетит до ТСПУ. ТСПУ видит реальный пакет и блокирует сессию.\n- **Слишком большой TTL (> 15):** фейковый пакет долетает до сервера назначения, и сервер разрывает соединение из-за невалидного хэндшейка.\n- **Оптимальный диапазон:** `TTL = 6..8` для большинства магистральных операторов РФ.", "embedding": []}, {"id": 47, "file": "INDEX.md", "heading": "📚 Knowledge Base Table of Contents", "text": "# Tachyon Knowledge Base & Architecture Index\n\nWelcome to the comprehensive technical knowledge base for **Tachyon**. This directory contains deep architectural specifications, module references, packet flow maps, and developer guidelines compiled directly from the codebase.\n\n---\n\n## 📚 Knowledge Base Table of Contents\n\n| Document | Description | Key Topics Covered |\n|---|---|---|\n| [**01. System Architecture**](01_SYSTEM_ARCHITECTURE.md) | High-level system architecture & control plane | ucode runtime, atomic writes, repository layout, daemon lifecycle |\n| [**02. ucode Module Reference**](02_UCODE_MODULE_REFERENCE.md) | Comprehensive reference for all 60+ `.uc` files | `core/`, `service/`, `diagnostics/`, `singbox/`, `providers/`, `nft/`, `dns/` |\n| [**03. Networking & nftables**](03_NETWORKING_NFTABLES_AND_ROUTING.md) | Packet lifecycle, firewall tables & DNS routing | `inet TachyonTable`, fwmark bitmasks, TProxy, bootstrap DNS loops |\n| [**04. DPI Bypass Engines**](04_DPI_BYPASS_ENGINES.md) | Local packet desynchronization deep dive | Zapret v1 (`nfqws`), Zapret v2 (`nfqws2`), ByeDPI (`ciadpi`), multisplit, seqovl |\n| [**05. AI Stack & AI Doctor**](05_AI_STACK_AND_AUTONOMOUS_DOCTOR.md) | AI Doctor v2.5, Watchdog & REST Agent API | 13 Quick Fixes, Local Rule Doctor, NTP/MTU tuning, OpenAPI 3.0.3, REST API |\n| [**06. Frontend LuCI Architecture**](06_FRONTEND_LUCI_TYPESCRIPT.md) | TypeScript SPA & LuCI view integration | `baseclass.extend` patch, reactive stores, live log streaming modal |\n| [**07. Build & Testing Pipeline**](07_BUILD_TESTS_AND_DEPLOYMENT.md) | Compilation, testing & release workflows | `build.sh` (ipk/apk), `install.sh`, Docker CI container, vitest tests |\n| [**08. UCI Configuration Schema**](08_UCI_CONFIGURATION_SCHEMA.md) | Complete `/etc/config/tachyon` reference | All UCI sections, options, validators, default values, ready recipes |\n| [**09. Telegram Bot Architecture**](09_TELEGRAM_BOT_ARCHITECTURE.md) | Remote Telegram control daemon protocol | Long-polling model, inline keyboards, callback query routing, security |", "embedding": []}, {"id": 48, "file": "INDEX.md", "heading": "Diagnostics & AI", "text": "| [**08. UCI Configuration Schema**](08_UCI_CONFIGURATION_SCHEMA.md) | Complete `/etc/config/tachyon` reference | All UCI sections, options, validators, default values, ready recipes |\n| [**09. Telegram Bot Architecture**](09_TELEGRAM_BOT_ARCHITECTURE.md) | Remote Telegram control daemon protocol | Long-polling model, inline keyboards, callback query routing, security |\n| [**10. Hosts Engine & Blocklists**](10_HOSTS_ENGINE_AND_BLOCKLISTS.md) | Hosts ingestion, parsing & smart caching | `combined.txt`, multi-format parsing, GitHub mirror retry resiliency |\n| [**11. Troubleshooting Manual**](11_TROUBLESHOOTING_AND_FIELD_MANUAL.md) | Field diagnostics & emergency recovery | Symptom resolution matrix, diagnostic commands, log inspection paths |\n| [**12. ucode Programming Patterns**](12_UCODE_PROGRAMMING_PATTERNS.md) | Developer guidelines for OpenWrt ucode | Atomic file writes, shell quoting, libuci bindings, RAM efficiency |\n| [**13. REST API & MCP Specification**](13_REST_API_AND_MCP_SPECIFICATION.md) | REST Agent API & MCP tool definitions | OpenAPI 3.0.3, Bearer Auth, OpenAI Function Calling, MCP JSON schema |\n| [**14. Zapret v2 (nfqws2) Deep Dive**](14_ZAPRET2_DEEP_DIVE_MANUAL.md) | Comprehensive Zapret v2 Lua manual | Lua desync functions, multisplit, seqovl, wsize, fooling, multi-profiles |\n| [**15. Zapret v1 (nfqws) Field Guide**](15_ZAPRET1_NFQWS_FIELD_GUIDE.md) | Complete Zapret v1 CLI specification | NFQUEUE desync modes, split-pos, seqovl, syndata, ipfrag, fooling |\n| [**16. ByeDPI (ciadpi) Reference**](16_BYEDPI_CIADPI_REFERENCE.md) | Complete ByeDPI SOCKS5/TProxy manual | Split, disorder, fake, ttl, auto-mode, oob, tlsrec, ip-frag |\n| [**17. TSPU / DPI Signatures & Counters**](17_TSPU_DPI_SIGNATURES_AND_COUNTERS.md) | TSPU filtering mechanics and counters | GoogleVideo 4K, Discord WebRTC, TLS 1.3 RST, TTL distance calculation |\n\n---\n\n## ⚡ Quick Operational Cheat Sheet\n\n### Common CLI Commands\n```sh\n# Diagnostics & AI\ntachyon doctor # Local offline rule diagnostics", "embedding": []}, {"id": 49, "file": "INDEX.md", "heading": "Full backend suite in Docker CI", "text": "| [**17. TSPU / DPI Signatures & Counters**](17_TSPU_DPI_SIGNATURES_AND_COUNTERS.md) | TSPU filtering mechanics and counters | GoogleVideo 4K, Discord WebRTC, TLS 1.3 RST, TTL distance calculation |\n\n---\n\n## ⚡ Quick Operational Cheat Sheet\n\n### Common CLI Commands\n```sh\n# Diagnostics & AI\ntachyon doctor # Local offline rule diagnostics\ntachyon ai_doctor # AI Doctor LLM analysis\ntachyon apply_quick_fix <code1,code2> # Apply automated repair codes\ntachyon restore_native_internet # 1-Click emergency WAN restore\n\n# Service & Watchdog\ntachyon ai_heal # Trigger immediate self-healing cycle\ntachyon ai_status # Concise Watchdog status JSON\ntachyon ai_status_full # Full Watchdog telemetry JSON\n\n# Component Management\ntachyon check_update <component> # Check for component updates\ntachyon component_action install <comp> # Install or update component\n```\n\n### Local Test Execution\n```sh\n# Frontend vitest suite\nnpm --prefix fe-app-tachyon test\n\n# Full backend suite in Docker CI\ndocker run --rm -v \"$(pwd):/mnt\" -w /mnt ucode-ci-img:latest bash tests/run_all.sh\n```", "embedding": []}]} |