From 0543f14f0effbee3ebd8b18cb5c8942914879ba8 Mon Sep 17 00:00:00 2001 From: VallierDev <24893073+VallierDev@users.noreply.github.com> Date: Wed, 14 Oct 2026 23:59:04 +0800 Subject: [PATCH] Add AGENTS.md for AI coding agents and link it from the READMEs Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + README.en.md | 6 ++ README.md | 5 ++ 4 files changed, 223 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b3e8bba --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,211 @@ +# AGENTS.md — guide for AI coding agents + +This file is written for large language model agents (Claude Code, Codex, Cursor, ...) that are asked to +**build, install, debug or develop** uu-remote-linux. Read it fully before acting. Human documentation is in +[README.md](README.md) (Chinese) and [README.en.md](README.en.md). + +## 1. What this project is + +- An **unofficial Linux host** for NetEase UU Remote (网易 UU 远程). The official Mac / Windows / mobile + clients connect to it and control the Linux desktop. There is no viewer/controller side here. +- One Rust binary, `uuremote-server` (Cargo package `uu-remote-linux`), plus small C engines in `c_engine/` + compiled by `build.rs`. No Wine, no NetEase binaries. +- The host registers with the UU cloud as a **Windows PC** (`x-param-plat=1`) so the official clients accept it. +- License GPL-3.0. Not affiliated with NetEase. + +## 2. Ground rules (must follow) + +1. **Privacy in logs.** Never log keystrokes, terminal text, clipboard contents, file contents, passwords, + tokens, QR login URLs or TURN credentials. Log sizes, counts, field numbers and booleans only. Existing code + follows this; keep it that way in every new log line. +2. **The QR login URL is a credential.** Show the QR only to the human who owns the account. Never paste the + URL or a QR screenshot into chats, issues, logs or commits. +3. **Follow the official host behavior.** Protocol behavior is copied from the official hosts (Mac + `UURemoteServer`, Windows `GameViewerServer.exe`). Do not invent message shapes; when unsure, log the field + numbers of what the viewer sends and derive behavior from evidence. +4. **No NetEase assets.** Do not add NetEase logos, icons, screenshots of their apps or copies of their binaries. +5. **No personal data in source.** Nothing machine- or account-specific is compiled in; credentials come from + the config file / environment. The only built-in default is the public client signing key in `src/auth.rs`. +6. **Don't break other tools.** The desktop, file-transfer, terminal and port-mapping tools each open their own + peer connection; a new offer must never close other peers. +7. Keep changes small and tested; match the surrounding code style (dense, comment only the non-obvious). + +## 3. Build and test + +Dependencies (Ubuntu/Debian): + +```sh +sudo apt install build-essential pkg-config \ + libx11-dev libxext-dev libxtst-dev libxfixes-dev libgtk-3-dev ffmpeg +# --features wayland: libwayland-dev libxkbcommon-dev wl-clipboard +# --features wayland,portal: + libglib2.0-dev libpipewire-0.3-dev +``` + +Rust stable via rustup. Commands: + +```sh +cargo test # unit tests (macOS builds use C stubs, also fine for development) +cargo build --release # X11 host +cargo build --release --features wayland # + Hyprland/wlroots +cargo build --release --features wayland,portal # + GNOME/KDE Wayland via xdg-desktop-portal +``` + +- `build.rs` links X11/Xext/Xtst/Xfixes and `dl` (PAM is loaded at runtime with `dlopen`), and builds the GTK3 + login window only when `pkg-config gtk+-3.0` succeeds (`UU_NO_GTK=1` forces it off). +- The portal feature panics in `build.rs` if GIO/PipeWire development packages are missing. +- `vendor/webrtc-dtls` is a patched copy of the upstream crate (MIT/Apache); keep it as a path dependency. +- CI (`.github/workflows/ci.yml`) runs `cargo test --locked` on ubuntu-22.04. Pushing a `v*` tag runs + `.github/workflows/release.yml`, which builds and publishes the x86_64 tarball; release notes come from + `docs/release-notes/.md`. + +## 4. Install on a user's machine (step by step) + +1. Check the session: `echo $XDG_SESSION_TYPE $XDG_CURRENT_DESKTOP $DISPLAY $WAYLAND_DISPLAY`. + X11 → default build. Hyprland → `--features wayland`. GNOME/KDE on Wayland → `--features wayland,portal` + (or advise the user to pick the "on Xorg" session at the login screen, which is the best-supported path). +2. Install dependencies and build (section 3). Copy the binary: `install -Dm755 target/release/uuremote-server ~/.local/bin/uuremote-server`. +3. **Login (needs the human).** Run `uuremote-server login` inside the graphical session. A GTK window shows a QR + code; the user scans it with the UU Remote mobile app and confirms. Without a display use + `uuremote-server login --no-gui` (terminal QR). Credentials are written to `~/.config/uuremote/config.json` + (mode 0600). Do not read the token out of that file or print it. +4. Create a systemd user unit (`~/.config/systemd/user/uuremote-native.service`): + + ```ini + [Unit] + Description=UU Remote Linux host (unofficial) + After=graphical-session.target + [Service] + Environment=RUST_LOG=info + Environment=DISPLAY=:0 + # GNOME on Xorg usually needs: Environment=XAUTHORITY=/run/user//gdm/Xauthority + ExecStart=%h/.local/bin/uuremote-server + Restart=always + RestartSec=5 + [Install] + WantedBy=default.target + ``` + + Find the real display/Xauthority with `loginctl show-session -p Display` / `ps -o args -C Xorg`. +5. `systemctl --user daemon-reload && systemctl --user enable --now uuremote-native.service` +6. Verify: `journalctl --user -u uuremote-native.service -f` must show + `Device status synchronized: ... availability=Some("ready")`. If credentials are missing or expired the + service opens the QR window on the desktop by itself (disable with `UU_LOGIN_WINDOW=0`). +7. Ask the user to connect from the official client and check desktop, input, sound, file transfer, terminal. + +Updating an installed binary: copy to a temp name and `mv -f` over the old one (a running binary cannot be +overwritten in place: "text file busy"), then restart the service. Restarting kills open viewer windows; the +viewer does not reconnect them automatically. + +## 5. Runtime configuration + +| Item | Meaning | +|---|---| +| `~/.config/uuremote/config.json` | user_id, device_id, client_id, system_id, machine_guid, token, csrf; optional `sign_key`, `ffmpeg_root`. `$UU_CONFIG` overrides the path | +| `~/.config/uuremote/host_settings.json` | persisted 安全 settings: auto_lock, keep_mute, mute_permanent | +| `UU_DESKTOP_BACKEND` | `auto` (default) / `x11` / `wayland` / `portal` | +| `UU_VIDEO_ENCODER=cpu` | force libx264 instead of NVENC | +| `UU_FFMPEG_ROOT` | FFmpeg prefix (`bin/ffmpeg`, libs in `lib/x86_64-linux-gnu`) | +| `UU_AUDIO=0`, `UU_AUDIO_SOURCE` | disable sound / choose the Pulse source (default `@DEFAULT_MONITOR@`) | +| `UU_LOGIN_WINDOW=0` | don't auto-open the login window | + +Token has no expiry field; API code 1120 (HTTP 422) means invalid/expired → re-login. The config is re-read +every 60 s. + +## 6. Code map + +| Path | Role | +|---|---| +| `src/main.rs` | entry, subcommands, room loop (one peer per `ice_id`), room renewal (deferred while connected) | +| `src/signaling.rs` | Engine.IO v4 / Socket.IO client; `be-controlled` binary attachment = ConnectOptions (field 1 capture_type) | +| `src/auth.rs`, `src/config.rs`, `src/login.rs`, `src/login_ui.rs` | signed REST client, config, device init + QR login, GTK window | +| `src/webrtc.rs` | peer connection, data channels, CONTROL dispatch, initialization messages | +| `src/video.rs`, `src/capture_setting.rs` | FFmpeg H.264 pipeline; viewer quality/fps/resolution settings | +| `src/audio.rs` | Pulse/PipeWire monitor → Opus audio track | +| `src/input.rs`, `src/input_mapping.rs` | input injection (X11 XTest / Wayland / portal), Windows VK → keysym | +| `src/cursor.rs` | pointer shape mirroring (X11) | +| `src/clipboard*.rs` | text clipboard bridge and protocol | +| `src/file_trans.rs` | FileTransferFtp RPC | +| `src/terminal.rs` | TERM frames + PTY sessions | +| `src/session_lock.rs`, `c_engine/pam_check.c` | lock state reporting, auto unlock via PAM + logind | +| `src/system_actions.rs`, `src/system_metrics.rs` | SimpleAction system commands, mute, auto-lock, SystemMetrics | +| `src/initialization.rs`, `src/control_protocol.rs`, `src/protocol.rs` | protobuf encoders/decoders for CONTROL | +| `src/session_ice.rs`, `src/network_diagnostics.rs` | cloud ICE servers, address-free path diagnostics | +| `src/desktop_backend.rs`, `src/wayland.rs`, `src/portal*.rs` | backend selection, Hyprland, GNOME/KDE portal | +| `c_engine/x11_engine.c`, `c_engine/clipboard.c` | X11 capture/input/selection | +| `c_engine/wayland_engine.c`, `c_engine/portal_engine.c` | Wayland and portal engines | +| `c_engine/login_window.c` | GTK3 login window | + +Diagnostic subcommands: `login [--no-gui]`, `unlock-check` (password on stdin, prints only accepted/rejected), +`desktop-probe [new.png]`, `desktop-video-probe`, `wayland-input-probe`, `clipboard-acceptance`, +`portal-acceptance`, `help`. Unknown arguments exit with code 2. Builds up to v0.1.0 did **not** reject them and +started a second full host server instead, so check that a subcommand exists in the binary you run. + +## 7. Protocol facts (verified against the official clients) + +- Connection types (ConnectOptions.capture_type): 1 desktop, 5 file transfer, 8 terminal, 9 port mapping. + Video is sent only for desktop connections (capture_type ≤ 2). +- CONTROL messages are protobuf `Message {1 seq, 2 timestamp, payload}`; input arrives as JSON + (`kbd_press`, `mouse_move_absolute` with normalized 0..1 floats, ...). +- Echo: the viewer sends SimpleAction action 0 with its FeatureFlag; the host answers action 1 with args + `{"seq":}` and **its own** FeatureFlag. The viewer only uses features the host declares: + `1 ff_capture_setting=4`, `2 ff_simple_action=2`, `3 ff_system_metrics=2`, `6 ff_file_transfer_ftp=2`, + `8 ff_clipboard=3` (when the clipboard bridge is ready). Do not declare versions you don't implement. +- RPC = Message 21 `RpcRequest {1 header{1 request_id}, }`, answered with Message 22 + `RpcResponse {1 header (same id), }`. Cases used: 2 capture_setting, 3 fps, 4 video_quality, + 6 resolution, 8 file transfer, 9 clipboard, 15 send_video_track, 16–20 plugins, 21 virtual audio policy, + 28/29 terminal. +- CaptureSettingRequest: field 1 is an **fps option index** (1=30, 2=60, 3=90); the real frame rate is + field 18 `fpsCount`. Field 2 quality: 1 Fast, 2 General (高清 2M), 3 HD (超清 8M), 4 Bluray (原画 20M), + 5 Auto, 6 Custom. Resolution: 16/17 pixel size or 5/6, 10 resolution_type (3 = follow remote). + Reply `RpcResponse{2 CaptureSettingResponse{}}` (no errors = applied) and send Message 25 CaptureSettingSync. +- SystemMetrics (Message 13): GeneralMetric `2 system_sound_support` is an enum, **2 = supported** (1 = not + supported); SettingMetric 1 keep_mute, 2 mute_permanent, 3 auto_lock, 5 file_transfer_save_location, + 8/9/10 permission states (2 = allow). +- Security menu: 静音运行 on → SimpleAction 14 + 18, off → 16. 远程结束后自动锁屏 → SimpleAction 19 with + `value` (field 5) **2 = on, 1 = off**. The viewer sends these only when toggled, so the host persists them. +- Auto unlock: host reports `SystemStateChange{1 SecureDesktopState{1 is_locked, 5 is_support_auto_logon}}`; + the viewer (after the user enables 自动解锁被控端) sends SimpleAction 15 with args `{"key": password}`; + failure → Message 12 `ReportError{2: -5}`. +- File transfer: the viewer sends RPCs on CONTROL but receives only on FILE_DATA_CHANNEL, so all replies go + out on FILE. With `ff_file_transfer_ftp=2` directory listings are zlib-compressed protobuf. `remove_dir` is + sent for every delete and must be answered with response case **6 `result{id, file_error}`**, not + `operation_result`. Host root is shown as ":/" (此电脑); home is "~/". +- Terminal: BINARY channel, RPC 28 check_env → 24; frames `"TERM"`, version 1, type (enum+1), 2 flag bytes, + session u32 LE, length u32 LE, payload; JSON `{cols,rows,shell,option}`. +- Cursor shape = Message 15 SystemStateChange field 2. Audio: the viewer always offers an Opus m-line. +- Login API: `/api/v1/device/windows/init` → device_id; `/qrcode/gen/login`; long-poll + `/qrcode/login/status` (1 wait, 2 scanned, 4 confirmed); `/login/by_qrcode` → user token. QR expires after + ~5 min with HTTP 400 code 1190 (not fatal: generate a new one). + +## 8. Known pitfalls + +- webrtc-rs `Sample.duration` sets the gap to the **next** frame. FFmpeg 6.1 rejects `-r` together with + `-fps_mode vfr`. +- All-intra 60 fps saturates Wi-Fi; keep GOP ≈ 0.5 s. A bitrate cap alone does not change quality on a static + desktop, so presets also change the CQ level. +- X11 capture on a GPU saturated by CUDA work starves; prefer the iGPU for the desktop when available. +- Remote keys repeat at high RTT because key-up arrives after the X autorepeat delay. XTEST repeats through the + master keyboard; the engine disables global autorepeat only while a remote key is held. +- Interactive shells ignore SIGTERM: the server HUPs/KILLs PTY sessions on shutdown. +- GTK windows stop repainting while GNOME is locked or the monitor is off; test UI on Xvfb or after unlock. +- logind `unlock-session` by the session owner clears the GNOME shield in ~3 s. +- GNOME closes the portal session on lock; capture/input must share one portal session and be rebuilt after + unlock. Portal input/clipboard permissions are persisted per desktop (0600 file); a revoked permission asks again. + +## 9. Debugging checklist + +- Connection: `Offer for connection: capture_type=`, `PeerConnection State changed`, `ICE path: ... route=`. +- Video: `Desktop encoder: ... fps= cq= maxrate=`, `Desktop latest-frame stats`, `Video feedback totals`. +- Viewer requests: `CONTROL message: fields=[..] simple_action=..` (numbers only), `Capture setting request`, + `SimpleAction N (...) received`. +- Features: `File transfer ...`, `Terminal frame`, `Native desktop clipboard text received: bytes=`, + `Desktop audio started`, `Auto unlock result`, `Auto lock after remote session`. +- When the viewer "does nothing" after a menu click, first check whether any message arrived; usually the + host did not declare the matching FeatureFlag/SystemMetrics capability. + +## 10. Contributing + +- Run `cargo test` (and the feature builds you touched) before committing; keep commits focused. +- New protocol behavior: cite the evidence (observed field numbers, official log strings) in a comment. +- Update README.md / README.en.md when user-visible features or limitations change, and add + `docs/release-notes/.md` before tagging a release. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/README.en.md b/README.en.md index de2670f..fe7e280 100644 --- a/README.en.md +++ b/README.en.md @@ -165,6 +165,12 @@ Common environment variables: Host settings such as "lock after remote session" and "mute host" are stored in `~/.config/uuremote/host_settings.json`. +## Let an AI agent install or develop it + +If you use Claude Code, Codex, Cursor or a similar coding agent, have it read [AGENTS.md](AGENTS.md) first. +It is written for language models: build and install steps, a code map, protocol notes and development rules, +enough to take over installation or development. + ## How it works ```mermaid diff --git a/README.md b/README.md index 78d5b6e..7ec682e 100644 --- a/README.md +++ b/README.md @@ -157,6 +157,11 @@ journalctl --user -u uuremote-native.service -f # 看到 availability=Some("re 「远程结束后自动锁屏」「静音运行」等设置保存在 `~/.config/uuremote/host_settings.json`。 +## 让 AI 帮你安装或开发 + +如果你用 Claude Code、Codex、Cursor 等 AI 编程工具,让它先阅读 [AGENTS.md](AGENTS.md)。 +这份文档写给大模型看,里面有编译安装步骤、代码地图、协议要点和开发规范,读完就能接手编译安装或继续开发。 + ## 工作原理 ```mermaid