Add AGENTS.md for AI coding agents and link it from the READMEs

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
VallierDevandClaude Opus 5.5 committed 2026-10-14 23:59:04 +08:00
1 parent c99a587afc
commit 0543f14f0e
4 files changed
+223

No files matched your search

+211
View File
@@ -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/<tag>.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/<uid>/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 <id> -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, <which> 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":<request 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}, <case>}`, answered with Message 22
`RpcResponse {1 header (same id), <case>}`. 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/<tag>.md` before tagging a release.
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
+6
View File
@@ -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
+5
View File
@@ -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