fallensigh/xserial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite README in Chinese and English, add drone examples

Browse Source 
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
FallenSigh
2026-06-12 21:56:20 +08:00
parent a2c7c0fa71
commit 4a80fbbe81
67 changed files with 1129 additions and 569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
AGENTS.md
View File

@@ -8,25 +8,25 @@
## Project Structure
`xserial` is a Rust workspace. The root `Cargo.toml` defines four crates in `crates/`, with dependencies flowing:
`pipeview` is a Rust workspace. The root `Cargo.toml` defines four crates in `crates/`, with dependencies flowing:
```
xserial-core (no internal deps — transport, framing, protocol, pipeline)
pipeview-core (no internal deps — transport, framing, protocol, pipeline)
↑
xserial-client (depends on xserial-core — sessions, history, commands, Lua)
pipeview-client (depends on pipeview-core — sessions, history, commands, Lua)
↑ ↑
xserial-gui xserial-tui
(both depend on xserial-core AND xserial-client)
pipeview-gui pipeview-tui
(both depend on pipeview-core AND pipeview-client)
```
| Crate | Type | What goes here |
|-------|------|---------------|
| `xserial-core` | library (`src/lib.rs`) | `transport/`, `frame/`, `protocol/`, `pipeline.rs` — protocol and I/O. Integration tests: `tests/pipeline.rs`. |
| `xserial-client` | library (`src/lib.rs`) | `session.rs`, `manager.rs`, `config.rs`, `history.rs`, `lua/` — state management and Lua bindings. Integration tests: `tests/session_lifecycle.rs`, `tests/lua_tests.rs`. |
| `xserial-gui` | binary (`src/main.rs`) | egui/eframe app. Panels in `src/panels/`. Font helpers in `src/ui_fonts.rs`. Profiling in `src/perf.rs`. |
| `xserial-tui` | binary (`src/main.rs`) | ratatui/crossterm app. **Still a placeholder** — zero tests, not at feature parity with GUI. |
| `pipeview-core` | library (`src/lib.rs`) | `transport/`, `frame/`, `protocol/`, `pipeline.rs` — protocol and I/O. Integration tests: `tests/pipeline.rs`. |
| `pipeview-client` | library (`src/lib.rs`) | `session.rs`, `manager.rs`, `config.rs`, `history.rs`, `lua/` — state management and Lua bindings. Integration tests: `tests/session_lifecycle.rs`, `tests/lua_tests.rs`. |
| `pipeview-gui` | binary (`src/main.rs`) | egui/eframe app. Panels in `src/panels/`. Font helpers in `src/ui_fonts.rs`. Profiling in `src/perf.rs`. |
| `pipeview-tui` | binary (`src/main.rs`) | ratatui/crossterm app. **Still a placeholder** — zero tests, not at feature parity with GUI. |
**Module boundaries**: transport/protocol → `xserial-core`. Session/Lua → `xserial-client`. UI state → `xserial-gui` or `xserial-tui`. Never put I/O logic in the UI crates, never put UI state in the client crate.
**Module boundaries**: transport/protocol → `pipeview-core`. Session/Lua → `pipeview-client`. UI state → `pipeview-gui` or `pipeview-tui`. Never put I/O logic in the UI crates, never put UI state in the client crate.
## Build, Test, and Development Commands
@@ -40,21 +40,21 @@ cargo clippy --workspace --all-targets -- -D warnings # lint gate
**Run specific tests:**
```bash
cargo test -p xserial-core -- tcp_line_text_utf8
cargo test -p xserial-client -- session_echo_send_and_read
cargo test -p xserial-core -- --nocapture # show test output
cargo test -p pipeview-core -- tcp_line_text_utf8
cargo test -p pipeview-client -- session_echo_send_and_read
cargo test -p pipeview-core -- --nocapture # show test output
# Integration tests only
cargo test -p xserial-core --test pipeline
cargo test -p xserial-client --test session_lifecycle
cargo test -p xserial-client --test lua_tests
cargo test -p pipeview-core --test pipeline
cargo test -p pipeview-client --test session_lifecycle
cargo test -p pipeview-client --test lua_tests
```
**Launch:**
```bash
cargo run -p xserial-gui
cargo run -p xserial-tui
cargo run -p pipeview-gui
cargo run -p pipeview-tui
```
## Environment & Configuration
@@ -62,8 +62,8 @@ cargo run -p xserial-tui
### Tracing (all entrypoints)
```bash
RUST_LOG=info cargo run -p xserial-gui
RUST_LOG=xserial_gui::perf=debug cargo run -p xserial-gui
RUST_LOG=info cargo run -p pipeview-gui
RUST_LOG=pipeview_gui::perf=debug cargo run -p pipeview-gui
```
`tracing_subscriber::EnvFilter::from_default_env()` reads `RUST_LOG`. The workspace dep `tracing-subscriber` has `features = ["env-filter"]`.
@@ -71,11 +71,11 @@ RUST_LOG=xserial_gui::perf=debug cargo run -p xserial-gui
### GUI Profiling
```bash
RUST_LOG=xserial_gui::perf=info XSERIAL_GUI_PROFILE=1 cargo run -p xserial-gui
XSERIAL_GUI_PROFILE_INTERVAL_MS=500 cargo run -p xserial-gui # custom interval (default 1s)
RUST_LOG=pipeview_gui::perf=info XSERIAL_GUI_PROFILE=1 cargo run -p pipeview-gui
XSERIAL_GUI_PROFILE_INTERVAL_MS=500 cargo run -p pipeview-gui # custom interval (default 1s)
```
Profiling logs go to target `xserial_gui::perf`.
Profiling logs go to target `pipeview_gui::perf`.
### State & Config File Paths (runtime, not compile-time)
@@ -83,9 +83,9 @@ Uses `env::consts::OS` + env vars — no `cfg(target_os)` gating for path resolu
| Platform | Root config path |
|----------|-----------------|
| Linux | `$XDG_CONFIG_HOME/xserial/` or `~/.config/xserial/` |
| macOS | `~/Library/Application Support/xserial/` |
| Windows | `%APPDATA%\xserial\` |
| Linux | `$XDG_CONFIG_HOME/pipeview/` or `~/.config/pipeview/` |
| macOS | `~/Library/Application Support/pipeview/` |
| Windows | `%APPDATA%\pipeview\` |
State files: `gui-state.json`, `tui-state.json`, `font-settings.json`.
@@ -120,9 +120,9 @@ Standard Rust conventions (`cargo fmt`). No crate-level lint attrs, no `[lints]`
- **No feature flags** — zero `[features]` in any `Cargo.toml`. No `#[cfg(feature)]` in any source.
- **No build scripts** — zero `build.rs` files. No codegen. No `include!`/`include_str!`/`include_bytes!`.
- **All `unsafe` is test-only** — constructing noop wakers for poll-based unit tests in `transport/`. No non-test `unsafe` anywhere.
- **`xserial-tui` is a stub** — no tests, minimal implementation. GUI is the primary target.
- **`pipeview-tui` is a stub** — no tests, minimal implementation. GUI is the primary target.
- **Platform font directories** use `#[cfg(target_os)]` in `ui_fonts.rs` (three blocks: Windows, macOS, Linux/BSD).
- **`tokio` features differ by build**: `xserial-client` uses `["sync", "time"]` for production, `["full"]` for dev-dependencies (tests need net/IO).
- **`tokio` features differ by build**: `pipeview-client` uses `["sync", "time"]` for production, `["full"]` for dev-dependencies (tests need net/IO).
## Commit & PR Guidelines