From bfa5523a9c29029c6212c79c2c8689dd1940adeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=80=81=E8=92=8B?= <23394662@qq.com> Date: Tue, 7 Jul 2026 23:49:14 +0800 Subject: [PATCH] docs(developer-guide): add anolisa architecture, CLI reference, and testing guides Add developer-guide documentation for the anolisa CLI component covering: - Architecture: 5-crate workspace layout, dependency graph, data flow, key design decisions (transaction journal, manifest v2, dual-mode install, adapter subsystem, crash safety) - CLI Reference: complete command/subcommand/flag reference with usage examples for all 18 leaf commands and 7 subcommand groups - Testing: test structure, conventions, platform-specific testing, and CI requirements This follows the documentation-standard.md convention that detailed reference material belongs in docs/developer-guide/ rather than in component README files. --- .../en/anolisa/architecture.md | 241 ++++++++++++ .../en/anolisa/cli-reference.md | 354 ++++++++++++++++++ docs/developer-guide/en/anolisa/testing.md | 129 +++++++ 3 files changed, 724 insertions(+) create mode 100644 docs/developer-guide/en/anolisa/architecture.md create mode 100644 docs/developer-guide/en/anolisa/cli-reference.md create mode 100644 docs/developer-guide/en/anolisa/testing.md diff --git a/docs/developer-guide/en/anolisa/architecture.md b/docs/developer-guide/en/anolisa/architecture.md new file mode 100644 index 000000000..f01485184 --- /dev/null +++ b/docs/developer-guide/en/anolisa/architecture.md @@ -0,0 +1,241 @@ +# Architecture + +anolisa uses a 5-crate Rust workspace architecture, version 0.1.20, requiring Rust 1.88+ (edition 2024). + +## Crate Dependency Graph + +``` +anolisa-env anolisa-platform + (env facts) (platform abstractions) + \ / \ + \ / \ + anolisa-core --------- \ + (planning & execution) \ + | \ \ + | anolisa-build ------ + | (build backends) + | | + anolisa-cli | + (CLI entry) ---+ + +Dependency direction: anolisa-cli -> anolisa-core -> anolisa-env, anolisa-platform + anolisa-cli -> anolisa-build -> anolisa-core, anolisa-env, anolisa-platform + anolisa-cli -> anolisa-env, anolisa-platform +``` + +## Crate Responsibilities + +| Crate | Binary | Responsibility | +|-------|--------|---------------| +| `anolisa-cli` | `anolisa` | CLI entry point. clap parser, command dispatch, response rendering. 18 leaf commands, ~60 flags | +| `anolisa-core` | — | Planning & execution engine. CLI-agnostic, 38 source modules. Handles manifest parsing, dependency resolution, install runner, lifecycle, transactions, adapter management, registry client, telemetry | +| `anolisa-env` | — | Environment facts. OS detection, kernel version probes, distro identification, framework discovery, platform capability probing | +| `anolisa-build` | — | Build backends. Currently cargo; designed for extensibility (make, npm in future) | +| `anolisa-platform` | — | Platform abstractions. Filesystem layout (FHS 3.0 user/system modes), package manager routing, RPM query/transaction, systemd integration, privilege escalation, IPC | + +## Directory Layout + +``` +src/anolisa/ +├── Cargo.toml # Workspace config, shared dependencies +├── AGENTS.md # AI agent constraints for this component +├── CHANGELOG.md # User-perceivable changes per release +├── docs/ # Component-specific design docs +├── crates/ +│ ├── anolisa-cli/ # CLI binary +│ │ └── src/ +│ │ ├── main.rs # Entry point +│ │ ├── commands.rs # Top-level Cli struct, Commands enum, dispatch() +│ │ ├── commands/ +│ │ │ ├── common.rs # Shared helpers (layouts, state, catalog) +│ │ │ ├── adapter.rs # AdapterArgs, AdapterCommands +│ │ │ ├── register.rs # RegisterArgs, RegisterCommands, UnregisterArgs +│ │ │ ├── osbase.rs # OsbaseArgs, kernel/sandbox/security subcommands +│ │ │ ├── system.rs # SystemArgs (serve, setup, teardown, status) +│ │ │ └── tier1/ +│ │ │ ├── list.rs # ListArgs +│ │ │ ├── install.rs # InstallArgs +│ │ │ ├── uninstall.rs # UninstallArgs +│ │ │ ├── status.rs # StatusArgs +│ │ │ ├── update.rs # UpdateArgs, UpdateCommands +│ │ │ ├── doctor.rs # DoctorArgs +│ │ │ ├── logs.rs # LogsArgs +│ │ │ ├── restart.rs # RestartArgs +│ │ │ ├── repair.rs # RepairArgs +│ │ │ ├── forget.rs # ForgetArgs +│ │ │ ├── adopt.rs # AdoptArgs +│ │ │ ├── env.rs # EnvArgs +│ │ │ └── bug.rs # BugArgs +│ │ └── tests/ # Integration tests +│ ├── anolisa-core/ # Planning & execution engine +│ │ └── src/ +│ │ ├── lib.rs # Module declarations, public API +│ │ ├── manifest.rs # TOML manifest parsing (Manifest v2) +│ │ ├── catalog.rs # Component catalog management +│ │ ├── registry.rs # Registry client config +│ │ ├── resolver.rs # Dependency resolution +│ │ ├── install_runner.rs # Install execution pipeline +│ │ ├── lifecycle.rs # Component lifecycle state machine +│ │ ├── transaction.rs # Crash-safe transaction journal +│ │ ├── component.rs # Component model +│ │ ├── instance.rs # Component instance state +│ │ ├── dependency.rs # Dependency graph +│ │ ├── state.rs # ANOLISA state directory +│ │ ├── backup.rs # File backup for rollback +│ │ ├── integrity.rs # SHA256 verification +│ │ ├── lock.rs # File locking +│ │ ├── distribution.rs # Distribution selectors +│ │ ├── download.rs # Artifact download +│ │ ├── provisioner.rs # Artifact provisioning +│ │ ├── metadata.rs # Component metadata +│ │ ├── service.rs # Service lifecycle +│ │ ├── hooks.rs # Install/uninstall hooks +│ │ ├── capability.rs # Capability declarations +│ │ ├── feature_flags.rs # Feature flag system +│ │ ├── health.rs # Health check module +│ │ ├── osbase_install.rs # OS base layer installer +│ │ ├── self_update.rs # CLI self-update logic +│ │ ├── daemon_server.rs # Daemon mode server +│ │ ├── system_helper.rs # System helper daemon integration +│ │ ├── central_log.rs # Centralized logging +│ │ ├── register.rs # Co-Build registration +│ │ ├── telemetry.rs # Telemetry module +│ │ ├── process.rs # Process management +│ │ ├── path_safety.rs # Path traversal safety +│ │ ├── sandbox_manifest.rs# Sandbox scenario manifests +│ │ ├── adapter.rs # Adapter module +│ │ ├── adapter/ +│ │ │ ├── manager.rs # Adapter lifecycle manager +│ │ │ ├── driver.rs # Adapter driver trait +│ │ │ ├── contract.rs # Adapter contract definition +│ │ │ ├── claim.rs # Adapter claim (metadata) +│ │ │ ├── registry.rs # Adapter registry +│ │ │ ├── openclaw.rs # OpenClaw adapter +│ │ │ └── hermes.rs # Hermes adapter +│ │ ├── health/ +│ │ │ ├── engine.rs # Health check engine +│ │ │ └── spec.rs # Health check specification +│ │ ├── registry/ +│ │ │ ├── client.rs # HTTP registry client +│ │ │ ├── cache.rs # Registry cache +│ │ │ ├── config.rs # Registry configuration +│ │ │ └── error.rs # Registry error types +│ │ └── telemetry/ +│ │ ├── ilogtail.rs # iLogtail integration +│ │ └── ops_telemetry.rs # Operations telemetry +│ ├── anolisa-env/ # Environment facts +│ │ └── src/ +│ │ ├── lib.rs +│ │ ├── cache.rs # Probe result caching +│ │ ├── gate.rs # Capability gating +│ │ ├── probes.rs # Probe orchestration +│ │ └── probes/ +│ │ ├── distro.rs # Distribution detection (Alinux, Anolis, etc.) +│ │ ├── kernel.rs # Kernel version, features (eBPF, BTF, etc.) +│ │ ├── platform.rs # Platform details (arch, OS) +│ │ └── frameworks.rs # Agent framework discovery +│ ├── anolisa-build/ # Build backends +│ │ └── src/ +│ │ ├── lib.rs +│ │ ├── backends.rs # Backend registry and dispatch +│ │ └── backends/ +│ │ └── cargo.rs # Cargo build backend +│ └── anolisa-platform/ # Platform abstractions +│ └── src/ +│ ├── lib.rs +│ ├── fs_layout.rs # FHS 3.0 path layout (user/system modes) +│ ├── package_manager.rs # Package manager abstraction +│ ├── pkg_query.rs # Package query interface +│ ├── pkg_transaction.rs # Package transaction interface +│ ├── rpm_query.rs # RPM database query +│ ├── rpm_repo.rs # RPM repository management +│ ├── rpm_transaction.rs # RPM install/remove transactions +│ ├── systemd.rs # systemd unit management +│ ├── command.rs # Command execution helpers +│ ├── privilege.rs # Privilege detection and escalation +│ └── ipc.rs # IPC helpers (sockets) +``` + +## Data Flow + +### Command Dispatch Flow + +``` +User command → clap parsing (commands.rs Cli struct) + → Commands enum (ComponentCommands | ManagementCommands) + → dispatch() routing to command handler + → anolisa-core planning/execution + → anolisa-platform for OS-level operations + → JSON or human-readable output +``` + +### Install Flow + +``` +anolisa install + → anolisa-core: catalog lookup → manifest parsing + → anolisa-core: dependency resolution → install plan + → anolisa-core: transaction journal start + → anolisa-core: download artifact → verify sha256 + → anolisa-platform: fs_layout resolve paths + → anolisa-platform: systemd service setup (if applicable) + → anolisa-core: backup files → provision → hooks + → anolisa-core: adapter scan/register (if applicable) + → anolisa-core: transaction journal commit +``` + +### Sandbox Install Flow (5-Phase) + +``` +anolisa osbase sandbox install + → Phase 1: Pre-flight (anolisa-env probes: distro, kernel, platform) + → Phase 2: Packages (anolisa-platform: rpm install dependencies) + → Phase 3: OS Primitives (anolisa-core: kernel modules, eBPF programs) + → Phase 4: Service Setup (anolisa-platform: systemd enable/start) + → Phase 5: Post-verify (anolisa-core: health checks) +``` + +## Key Design Decisions + +### Transaction Journal + +Every destructive operation (install, uninstall) is wrapped in a crash-safe TOML journal with sha256-verified file backups. On failure, the journal provides automatic rollback. Each step records its state: pending → in_progress → completed → (rolled_back on failure). + +### Manifest Schema v2 + +Typed TOML manifest with: +- Distribution selectors (OS, version, arch filtering) +- Artifact resolution (URL + sha256) +- Build backend declarations +- Adapter specifications +- Health check specifications +- All enforced at the type boundary via serde deserialization + +### Dual-Mode Install + +Two install scopes per `file-hierarchy(7)`: +- **User mode** (`~/.local/`): No root required, suitable for single-user setups +- **System mode** (`/usr/local/`): FHS 3.0 compliant, requires root; redirectable via `--prefix` + +### Adapter Subsystem + +Bridges ANOLISA components into agent frameworks (OpenClaw, Hermes) with: +- **Claim**: Component declares supported adapters in its manifest +- **Driver**: Framework-specific integration code +- **Contract**: Defines the interface between component and framework +- **Manager**: Lifecycle (scan, enable, disable, status) + +### Crash Safety + +- `transaction.rs`: TOML journal with per-step state tracking +- `backup.rs`: sha256-verified file backups before modifications +- `lock.rs`: File-based locking to prevent concurrent operations +- `integrity.rs`: Artifact and file integrity verification + +## Build Profile + +Release builds use: +- `lto = "thin"` for cross-crate optimization +- `codegen-units = 1` for maximum optimization +- `panic = "abort"` for smaller binary size +- `debug = true` for usable backtraces diff --git a/docs/developer-guide/en/anolisa/cli-reference.md b/docs/developer-guide/en/anolisa/cli-reference.md new file mode 100644 index 000000000..7344b8e28 --- /dev/null +++ b/docs/developer-guide/en/anolisa/cli-reference.md @@ -0,0 +1,354 @@ +# CLI Reference + +Complete reference of all `anolisa` CLI commands, subcommands, arguments, and flags. + +--- + +## Global Options + +These flags are available on every command (`global = true`): + +| Flag | Type | Description | +|------|------|-------------| +| `--install-mode ` | `user` \| `system` | Install scope. Defaults to `system` if root, `user` otherwise | +| `--prefix ` | Path | Custom install prefix (system-mode only) | +| `--json` | Flag | Output in JSON format | +| `--dry-run` | Flag | Print plan without executing | +| `-v`, `--verbose` | Flag | Increase verbosity | +| `-q`, `--quiet` | Flag | Suppress non-error output | +| `--no-color` | Flag | Disable colored output | + +--- + +## Component Commands + +### `list` (alias: `ls`) + +List available components. + +``` +anolisa list [--installed] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `--installed`, `--enabled` | Flag | Show only currently installed components | + +### `install` + +Install a component. + +``` +anolisa install [options] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `` | String | Component name to install | +| `--all` | Flag | Install all available components | +| `--package ` | String | Pin to a specific package name | +| `--version ` | String | Pin to a specific version | +| `--force` | Flag | Force reinstall | +| `--no-verify` | Flag | Skip post-install verification | + +### `uninstall` + +Remove a component. + +``` +anolisa uninstall [--purge] [--remove-system-package] [--force] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `` | String | Component to uninstall | +| `--purge` | Flag | Also remove ANOLISA-owned config/cache/state fragments | +| `--remove-system-package` | Flag | For rpm-observed: delegate removal to `dnf remove` | +| `--force` | Flag | Reserved for forcing through warnings | + +### `status` + +Show installation status. + +``` +anolisa status [COMPONENT] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `[COMPONENT]` | String (optional) | Show detail for specific component; omit for aggregate view | + +### `update` + +Update installed components. + +``` +anolisa update [COMPONENT] +anolisa update self +anolisa update all +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `[COMPONENT]` | String (optional) | Component to update | + +Subcommands: + +| Subcommand | Description | +|------------|-------------| +| `self` | Update the anolisa CLI binary only | +| `all` | Update every ANOLISA-managed object | + +### `doctor` + +Run health checks. + +``` +anolisa doctor [COMPONENT] [--fix] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `[COMPONENT]` | String (optional) | Diagnose a specific component; default: all installed | +| `--fix` | Flag | Apply suggested fixes automatically | + +### `logs` + +View operation logs. + +``` +anolisa logs [OBJECT] [options] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `[OBJECT]` | String (optional) | Filter: component / operation id / log source / `all` | +| `--operation-id ` | String | Match exact operation ID | +| `--kind ` | String | Restrict to `operation` or `component` | +| `--source ` | String | Match exact source | +| `--component ` | String | Match exact component name | +| `--severity ` | String | Minimum severity: `debug`, `info`, `warn`, `error` | +| `--since ` | String | Lexicographic ISO8601 lower bound on `started_at` | +| `--limit ` | Integer | Cap returned records (default 50, max 1000) | + +### `restart` + +Restart component services. + +``` +anolisa restart +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `` | String | Component whose services to restart | + +### `repair` + +Refresh ANOLISA state from rpmdb. + +``` +anolisa repair +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `` | String | Component whose ANOLISA state should be refreshed from rpmdb | + +### `forget` + +Drop ANOLISA state record. + +``` +anolisa forget +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `` | String | Component whose ANOLISA state record should be dropped | + +### `adopt` + +Record an existing system RPM as ANOLISA-managed. + +``` +anolisa adopt [--package ] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `` | String | Component to record as an existing system RPM | +| `--package ` | String | Pin the RPM package name when ambiguous | + +### `adapter` + +Manage component adapters. + +``` +anolisa adapter scan +anolisa adapter enable [FRAMEWORK] +anolisa adapter disable [FRAMEWORK] +anolisa adapter status [COMPONENT] +``` + +Subcommands: + +| Subcommand | Args | Description | +|------------|------|-------------| +| `scan` | *(none)* | Discover installed adapter declarations and local state | +| `enable` | `` (required), `[FRAMEWORK]` (optional) | Enable a component's adapter for a framework | +| `disable` | `` (required), `[FRAMEWORK]` (optional) | Disable a previously enabled adapter | +| `status` | `[COMPONENT]` (optional) | Report adapter receipt status | + +--- + +## Management Commands + +### `register` + +Co-Build Program registration. + +``` +anolisa register [--yes] +anolisa register status [--json] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `--yes` | Flag | Skip interactive confirmation | + +Subcommands: + +| Subcommand | Args | Description | +|------------|------|-------------| +| `status` | `--json` (flag) | Output machine-readable JSON | + +### `unregister` + +Co-Build Program unregistration. + +``` +anolisa unregister [--force] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `--force` | Flag | Skip interactive confirmation | + +### `env` + +Display environment information and system capabilities. + +``` +anolisa env [--verbose] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `--verbose` | Flag | Include all probe details | + +### `bug` + +Generate a diagnostic report. + +``` +anolisa bug [--component ] [--limit ] +``` + +| Arg | Type | Description | +|-----|------|-------------| +| `--component ` | String | Limit report to one component | +| `--limit ` | Integer | Max recent warn/error log records (default 20, max 100) | + +### `osbase` + +OS base layer management. + +``` +anolisa osbase kernel install [--dry-run] +anolisa osbase kernel remove +anolisa osbase kernel status + +anolisa osbase sandbox install [--dry-run] [--force] [--no-verify] +anolisa osbase sandbox uninstall [--dry-run] +anolisa osbase sandbox remove [--purge] [--dry-run] +anolisa osbase sandbox list [--json] +anolisa osbase sandbox status [TARGET] [--json] + +anolisa osbase security install [--dry-run] +anolisa osbase security remove +anolisa osbase security status [TARGET] +``` + +#### kernel subcommands + +| Subcommand | Args | Description | +|------------|------|-------------| +| `install` | `--dry-run` (flag) | Install kernel modules and eBPF programs | +| `remove` | *(none)* | Remove kernel modules | +| `status` | *(none)* | Show kernel substrate status | + +#### sandbox subcommands + +| Subcommand | Args | Description | +|------------|------|-------------| +| `install` | `` (required), `--dry-run`, `--force`, `--no-verify` | Install a sandbox scenario | +| `uninstall` | `` (required), `--dry-run` | Uninstall scenario packages | +| `remove` | `` (required), `--purge`, `--dry-run` | Remove a sandbox scenario | +| `list` | `--json` | List available sandbox scenarios | +| `status` | `[TARGET]` (optional), `--json` | Show sandbox scenario status | + +#### security subcommands + +| Subcommand | Args | Description | +|------------|------|-------------| +| `install` | `` (required), `--dry-run` | Install a security overlay | +| `remove` | `` (required) | Remove a security overlay | +| `status` | `[TARGET]` (optional) | Show security overlay status | + +### `system` + +System helper daemon management. + +``` +anolisa system serve [--socket ] +anolisa system setup [--helper-path ] [--upgrade] +anolisa system teardown +anolisa system status [--json] +``` + +| Subcommand | Args | Description | +|------------|------|-------------| +| `serve` | `--socket ` (default: system helper socket path) | Start the system helper daemon (foreground) | +| `setup` | `--helper-path `, `--upgrade` | One-time setup: install system helper daemon | +| `teardown` | *(none)* | Remove system helper: stop service, delete unit + binary | +| `status` | `--json` | Check system helper health | + +--- + +## Configuration + +CLI configuration file: `~/.config/anolisa/config.toml` + +```toml +[registry] +# Component registry URL +url = "https://registry.agentic-os.sh" + +[install] +# Default install mode: "user" or "system" +mode = "user" + +# Installation prefix for user mode +prefix = "~/.local" +``` + +## Environment Variables + +| Variable | Description | +|----------|-------------| +| `ANOLISA_REGISTRY_URL` | Override registry URL | +| `ANOLISA_INSTALL_MODE` | Default install mode (`user` or `system`) | +| `ANOLISA_PREFIX` | Default install prefix | +| `ANOLISA_STATE_DIR` | Override state directory | +| `ANOLISA_NO_COLOR` | Disable colored output | diff --git a/docs/developer-guide/en/anolisa/testing.md b/docs/developer-guide/en/anolisa/testing.md new file mode 100644 index 000000000..06bac3fb0 --- /dev/null +++ b/docs/developer-guide/en/anolisa/testing.md @@ -0,0 +1,129 @@ +# Testing + +Testing strategy and conventions for the anolisa CLI component. + +--- + +## Test Structure + +anolisa tests are organized at the crate level, following Rust conventions: + +``` +crates/anolisa-cli/tests/ # Integration tests for CLI binary +crates/anolisa-core/src/ # Unit tests inline (#[cfg(test)] modules) +crates/anolisa-env/src/ # Unit tests for env probes +crates/anolisa-platform/src/ # Unit tests for platform abstractions +crates/anolisa-build/src/ # Unit tests for build backends +``` + +## Running Tests + +```bash +# From src/anolisa/ + +# Run all tests +cargo test + +# Run tests for a specific crate +cargo test -p anolisa-cli +cargo test -p anolisa-core + +# Run with output +cargo test -- --nocapture + +# Run a specific test +cargo test -p anolisa-core -- manifest::tests::test_parse +``` + +## Code Quality + +```bash +# Format check +cargo fmt --check + +# Lint +cargo clippy -- -D warnings + +# Full CI check +cargo fmt --check && cargo clippy -- -D warnings && cargo test +``` + +## Test Conventions + +### Unit Tests + +- Located in `#[cfg(test)]` modules at the bottom of each source file +- Test pure logic without filesystem or network dependencies +- Use table-driven tests for parsers and validators +- Example from manifest parsing: + +```rust +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_parse_valid_manifest() { + let input = r#" + [component] + name = "test-component" + version = "1.0.0" + "#; + let result = parse_manifest(input); + assert!(result.is_ok()); + } +} +``` + +### Integration Tests + +- Located in `tests/` directories +- Test end-to-end CLI behavior +- Use temporary directories via `tempfile` +- Mock registry responses for download tests +- Verify journal integrity after install/uninstall operations + +### Test Isolation + +- Each test creates its own state directory +- No shared mutable state between tests +- Temporary directories are cleaned up on test completion +- Use `ANOLISA_STATE_DIR` to isolate state + +## Platform-Specific Testing + +Some tests require Linux-specific features and are gated: + +```rust +#[cfg(target_os = "linux")] +#[test] +fn test_ebpf_probe() { + // Requires kernel 5.x+ +} +``` + +### Alinux CI Environment + +Tests are run on Alinux (Anolis OS) in CI with: +- GCC 13 (via `scl enable gcc-toolset-13`) +- Rust 1.88+ +- Kernel 5.10+ with eBPF support + +## Writing New Tests + +1. **Pure logic**: Add `#[test]` in the source file's test module +2. **File I/O**: Use `tempfile::TempDir` for isolation +3. **CLI integration**: Add to `crates/anolisa-cli/tests/` +4. **Cross-crate**: Test in the highest crate that can exercise the full path +5. **Regression tests**: Reference the issue/PR number in the test name + +## Before Submitting a PR + +```bash +cd src/anolisa +cargo fmt --check +cargo clippy -- -D warnings +cargo test +``` + +All three must pass with zero warnings.