HHostingByteSoftware
Ctrl K
ComunidadGuías…

AGENTS.md

Rama master · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
<!-- Generated: 2026-05-21 | Updated: 2026-09-09 -->

# Nyro AI Gateway

## Purpose
Nyro is a Rust workspace for a local AI protocol gateway with a Tauri desktop app, standalone server, and React WebUI. It translates OpenAI / Anthropic / Gemini-compatible client traffic to configured model providers while keeping administration and configuration local.

## Key Files

| File | Description |
|------|-------------|
| `Cargo.toml` | Root `nyro` package plus workspace definition for the new data-plane crates and legacy applications. |
| `Cargo.lock` | Locked Rust dependency graph. |
| `README.md` / `README_CN.md` | User-facing project documentation in English and Chinese. |
| `Makefile` | Common development and release commands. |
| `docs/design/architecture.md` | Architecture overview and module layout. |
| `webui/package.json` | React/Vite WebUI dependencies and scripts. |

## Subdirectories

| Directory | Purpose |
|-----------|---------|
| `src/` | Experimental source-built root `nyro proxy` entrypoint, bootstrap, and Unix SIGHUP configuration reload; separate from released legacy entries. |
| `crates/nyro-kernel/` | Workload-neutral lifecycle/generation library used by the experimental root proxy. |
| `crates/nyro-protocol/` | Protocol wire types and bounded stream framing for the new data plane. |
| `crates/nyro-llm/` | New typed LLM runtime, OpenAI/Anthropic/Gemini Chat codecs/providers, request execution, and correlated usage observations. |
| `crates/nyro-config/` | Strict standalone file configuration for the experimental root proxy. |
| `crates/nyro-security/` | Transport-neutral credential authentication and authorization primitives. |
| `crates/nyro-limit/` | Shared concurrency, token-bucket rate admission, and cumulative quota primitives. |
| `crates/nyro-core/` | Core Rust library: gateway, proxy, protocol conversion, provider adapters, storage, admin service. |
| `crates/nyro-tools/` | Rust CLI/tooling crate. |
| `src-server/` | Standalone server binary exposing proxy/admin HTTP surfaces. |
| `src-tauri/` | Tauri desktop application shell and IPC integration. |
| `webui/` | React + TypeScript management console. |
| `docs/` | Design, server, standalone, and testing documentation. |
| `tests/` | Python/E2E test assets and shared fixtures. |
| `scripts/` | Install and release automation. |

## For AI Agents

### Working In This Repository
- Keep changes focused and reversible; do not mix unrelated cleanup into feature or refactor work.
- Prefer existing patterns and utilities before adding abstractions or dependencies.
- Do not edit generated build output such as `webui/dist/` unless the task explicitly requires it.
- Preserve separate English and Chinese user-facing docs when updating public documentation.

### Multilingual Defaults
- For any multilingual/i18n-capable value, the default must be English, in both frontend and backend code.
- This applies to UI labels, fallback strings, seed/default configuration, generated examples, API defaults, and documentation-derived constants.
- Add localized alternatives explicitly, but keep the canonical fallback/default value in English unless a caller/user setting selects another language.

### Testing Requirements
- Rust core changes: run the narrowest relevant `cargo test -p <crate> ...`, then `cargo check -p <crate>` or `cargo clippy -p <crate> --all-targets` when behavior or public APIs change.
- WebUI changes: run the relevant package script from `webui/` such as `npm run lint` or `npm run build` when TypeScript/UI behavior changes.
- Documentation-only changes should still be checked for path/name accuracy.

### Common Patterns
- `nyro-kernel` owns resource/generation invariants only; keep business rules, configuration, HTTP, databases, and global module discovery outside it. See its README for lifecycle ownership and cancellation contracts.
- `nyro-core` should remain transport-agnostic; desktop IPC and server HTTP layers call into core APIs rather than embedding core business logic.
- Admin service code should be split by functional responsibility and tested through public APIs where possible; keep private state-machine tests internal instead of exposing private APIs just for tests.
- Protocol/provider logic should keep protocol conversion boundaries explicit and avoid coupling provider adapters to UI/server transport concerns.

## Dependencies

### Internal
- The root `nyro` package composes `nyro-kernel`, `nyro-config`, `nyro-llm`, `nyro-security`, and `nyro-limit` for the experimental file-config proxy.
- `src-tauri/` and `src-server/` depend on `crates/nyro-core/`.
- `webui/` talks to the desktop IPC/server admin surfaces and should not duplicate core business rules.
- Documentation in `docs/` should reflect current crate and module boundaries.

### External
- Rust workspace uses Tokio, Axum, Reqwest, SQLx, Serde, Tauri, and tracing-related crates.
- WebUI uses React, Vite, TypeScript, Radix UI primitives, TanStack Query, and Zustand.

<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

### Database Changes

When modifying the database schema — including changes to `INIT_SQL`, `POSTGRES_INIT_SQL`, `MYSQL_INIT_SQL` constants or the `migrate()` function in any storage backend — you **must** also:

1. Update `docs/database/schema.md` to reflect the new table/column definitions.
2. Regenerate `deploy/schema/postgres.sql` and `deploy/schema/mysql.sql` to match the final post-migration state:
   ```bash
   nyro-tools dump-schema --backend postgres > deploy/schema/postgres.sql
   nyro-tools dump-schema --backend mysql    > deploy/schema/mysql.sql
   ```
   These files are the authoritative reference schema for DBAs. They represent the **final state** after all migrations have run (with final table names: `models`, `model_backends`, `api_key_models`).

> The SQL files in `deploy/schema/` are derived reference artifacts — do not manually edit them except to update the header comment. Always regenerate from the migration source of truth.

### Release Process

Local release work (cutting a `release/vX.Y.Z` branch off `master` through pushing it):

1. Branch: `git checkout master && git pull && git checkout -b release/vX.Y.Z`.
2. Bump the version in **3 places** (keep identical): `Cargo.toml` `[workspace.package].version`, `src-tauri/tauri.conf.json` `version`, `webui/package.json` `version`. Refresh `Cargo.lock` via `cargo update -w` (never edit it by hand).
3. Changelog: summarize all commits since the last tag (`git log $(git describe --tags --abbrev=0)..HEAD --no-merges --oneline`) into a new version entry, and write it to **both** `CHANGELOG.md` (English, canonical) and `CHANGELOG_CN.md` (Chinese).
4. Verify with `make check` and `make test`, then commit (`chore: release vX.Y.Z`) and push the branch.

PR merge (`release/vX.Y.Z` → `master`) and tagging `vX.Y.Z` are done remotely on GitHub; pushing the tag triggers the release workflows.

> See `docs/release.md` for the full local release runbook (source of truth).