skills/rtk-ai__rtk
1
0
Fork 0
mirror of https://github.com/rtk-ai/rtk.git synced 2026-09-19 07:33:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): last review

Browse Source
This commit is contained in:
aesoft
2026-03-25 19:12:46 +01:00
parent 46fa31c4b8
commit 0925cf21e0
12 changed files with 146 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+36 -63
View File
@@ -7,6 +7,7 @@
- [Report an Issue](../../issues/new)
- [Open Pull Requests](../../pulls)
- [Start a Discussion](../../discussions)
- [Technical Documentation](docs/TECHNICAL.md) — Architecture, end-to-end flow, folder map, how to write tests
---
@@ -22,9 +23,9 @@
|------|----------|
| **Report** | File a clear issue with steps to reproduce, expected vs actual behavior |
| **Fix** | Bug fixes, broken filter repairs |
| **Build** | New filters, new command support, performance improvements |
| **Build** | New filters, new command support, new features (for core features, discuss with maintainers before) |
| **Review** | Review open PRs, test changes locally, leave constructive feedback |
| **Document** | Improve docs, add usage examples, clarify existing docs |
| **Document** | Improve docs, clarify |
---
## Design Philosophy
@@ -41,7 +42,7 @@ Filters should be flag-aware: default output (no flags) gets aggressively compre
### Transparency
The LLM doesn't know RTK is involved — hooks rewrite commands silently. RTK's output must be a valid, useful subset of the original tool's output, not a different format the LLM wouldn't expect. If an LLM parses `git diff` output, RTK's filtered version must still look like `git diff` output.
The LLM doesn't know RTK is involved for which commands, hooks rewrite commands silently. RTK's output must be a valid, useful subset of the original tool's output, not a different format the LLM wouldn't expect. If an LLM parses `git diff` output, RTK's filtered version must still look like `git diff` output.
Don't invent new output formats. Don't add RTK-specific headers or markers in the default output. The filtered output should be indistinguishable from "a shorter version of the real command."
@@ -57,12 +58,15 @@ Every filter needs a fallback path. Every hook must handle malformed input grace
`lazy_static!` for all regex. No network calls. No disk reads in the hot path. Benchmark before/after with `hyperfine`.
### Extensibility
Always use components already in place to avoid duplication, also use extensible modules when this is possible.
If you want to submit a new core feature, this is an important point to watch.
---
## What Belongs in RTK?
RTK filters **development CLI commands** consumed by LLM coding assistants — the commands an AI agent runs during a coding session: test runners, linters, build tools, VCS operations, package managers, file operations.
### In Scope
Commands that produce **text output** (typically 100+ tokens) and can be compressed **60%+** without losing essential information for the LLM.
@@ -75,12 +79,15 @@ Commands that produce **text output** (typically 100+ tokens) and can be compres
- File operations (ls, tree, grep, find, cat/head/tail)
- Infrastructure tools with text output (docker, kubectl, terraform)
When implementing a new filter/cmds, be aware of the [Design Philosophy](#design-philosophy) above.
### Out of Scope
- Interactive TUIs (htop, vim, less) — not batch-mode compatible
- Binary output (images, compiled artifacts) — no text to filter
- Trivial commands (<100 tokens typical output) — not worth the overhead
- Commands with no text output — nothing to compress
- Interactive TUIs (htop, vim, less): not batch-mode compatible
- Binary output (images, compiled artifacts): no text to filter
- Trivial commands: not worth the overhead and may loose important informations
- Commands with no text output: nothing to compress
- Others features not related to a LLM-proxy like RTK
### TOML vs Rust: Which One?
@@ -94,20 +101,9 @@ Commands that produce **text output** (typically 100+ tokens) and can be compres
See [`src/filters/README.md`](src/filters/README.md) for TOML filter guidance and [`src/cmds/README.md`](src/cmds/README.md) for Rust module guidance.
### Complete Contribution Checklist
### Adding a Filter
Adding a new filter or command requires changes in multiple places:
1. **Create the filter** — TOML file in `src/filters/` or Rust module in `src/cmds/<ecosystem>/`
2. **Add rewrite pattern** — Entry in `src/discover/rules.rs` (PATTERNS + RULES arrays at matching index) so hooks auto-rewrite the command
3. **Register in main.rs** — (Rust modules only) Three changes:
- Add `pub mod mymod;` to the ecosystem's `mod.rs` (e.g., `src/cmds/system/mod.rs`)
- Add variant to `Commands` enum in `main.rs` with `#[arg(trailing_var_arg = true, allow_hyphen_values = true)]`
- Add routing match arm in `main.rs` to call `mymod::run()`
4. **Write tests** — Real fixture, snapshot test, token savings >= 60%
5. **Update docs** — README.md command list, CHANGELOG.md
See [src/cmds/README.md](src/cmds/README.md#common-pattern) for the standard module template with timer, fallback, tee, and tracking.
For the step-by-step checklist (create filter, register rewrite pattern, register in main.rs, write tests, update docs), see [src/cmds/README.md — Adding a New Command Filter](src/cmds/README.md#adding-a-new-command-filter).
---
@@ -141,12 +137,13 @@ chore(proxy): remove-deprecated-flags
**Each PR must focus on a single feature, fix, or change.** The diff must stay in-scope with the description written by the author in the PR title and body. Out-of-scope changes (unrelated refactors, drive-by fixes, formatting of untouched files) must go in a separate PR.
**For large features or refactors**, prefer multi-part PRs over one enormous PR. Split the work into logical, reviewable chunks that can each be merged independently. Examples:
- Part 1: Add data model and tests
- Part 2: Add CLI command and integration
- Part 3: Update documentation and CHANGELOG
- feat(Part 1): Add data model and tests
- feat(Part 2): Add CLI command and integration
- feat(Part 3): Update documentation and CHANGELOG
**Why**: Small, focused PRs are easier to review, safer to merge, and faster to ship. Large PRs slow down review, hide bugs, and increase merge conflict risk.
### 1. Create Your Branch
```bash
@@ -163,7 +160,7 @@ git checkout -b "feat(scope): your-clear-description"
**No obvious comments.** Don't comment what the code already says. Comments should explain *why*, never *what* to avoid noise.
**Large command files are expected.** Command modules (`*_cmd.rs`) contain the implementation, tests, and fixture in the same file. A big file is fine when it's self-contained for one command.
**Large command files are expected.** Command modules (`*_cmd.rs`) contain the implementation, tests, and fixture in the same file. A big file is fine when it's self-contained for one command. This will be moved in the future.
### 3. Add Tests
@@ -208,6 +205,8 @@ your branch --> develop (review + CI + integration testing) --> version branch -
Every change **must** include tests. We follow **TDD (Red-Green-Refactor)**: write a failing test first, implement the minimum to pass, then refactor.
For how to write tests (fixtures, snapshots, token savings verification), see [docs/TECHNICAL.md — Testing](docs/TECHNICAL.md#testing).
### Test Types
| Type | Where | Run With |
@@ -217,36 +216,6 @@ Every change **must** include tests. We follow **TDD (Red-Green-Refactor)**: wri
| **Smoke tests** | `scripts/test-all.sh` (69 assertions) | `bash scripts/test-all.sh` |
| **Integration tests** | `#[ignore]` tests requiring installed binary | `cargo test --ignored` |
### How to Write Tests
Tests for new commands live **in the module file itself** inside a `#[cfg(test)] mod tests` block (e.g. tests for `src/cmds/cloud/container.rs` go at the bottom of that same file).
**1. Create a fixture from real command output** (not synthetic data):
```bash
kubectl get pods > tests/fixtures/kubectl_pods_raw.txt
```
**2. Write your test in the same module file** (`#[cfg(test)] mod tests`):
```rust
#[test]
fn test_my_filter() {
let input = include_str!("../tests/fixtures/my_cmd_raw.txt");
let output = filter_my_cmd(input);
assert_snapshot!(output);
}
```
**3. Verify token savings**:
```rust
#[test]
fn test_my_filter_savings() {
let input = include_str!("../tests/fixtures/my_cmd_raw.txt");
let output = filter_my_cmd(input);
let savings = 100.0 - (count_tokens(&output) as f64 / count_tokens(input) as f64 * 100.0);
assert!(savings >= 60.0, "Expected >=60% savings, got {:.1}%", savings);
}
```
### Pre-Commit Gate (mandatory)
All three must pass before any PR:
@@ -268,15 +237,19 @@ cargo fmt --all --check && cargo clippy --all-targets && cargo test
## Documentation
Every change **must** include documentation updates. Update the relevant file(s) depending on what you changed:
Every change **must** include documentation updates. Use this table to find which docs to update:
| What you changed | Update |
|------------------|--------|
| New command or filter | [README.md](README.md) (command list + examples) and [CHANGELOG.md](CHANGELOG.md) |
| Architecture or internal design | [ARCHITECTURE.md](ARCHITECTURE.md) |
| Installation or setup | [INSTALL.md](INSTALL.md) |
| What you changed | Update these docs |
|------------------|-------------------|
| New Rust filter (`src/cmds/`) | Ecosystem `README.md` (e.g., `src/cmds/git/README.md`), [README.md](README.md) command list, [CHANGELOG.md](CHANGELOG.md) |
| New TOML filter (`src/filters/`) | [src/filters/README.md](src/filters/README.md) if naming conventions change, [README.md](README.md) command list, [CHANGELOG.md](CHANGELOG.md) |
| New rewrite pattern | `src/discover/rules.rs` — see [Adding a New Command Filter](src/cmds/README.md#adding-a-new-command-filter) |
| Core infrastructure (`src/core/`) | [src/core/README.md](src/core/README.md), [docs/TECHNICAL.md](docs/TECHNICAL.md) if flow changes |
| Hook system (`src/hooks/`) | [src/hooks/README.md](src/hooks/README.md), [hooks/README.md](hooks/README.md) for agent-facing docs |
| Architecture or design change | [ARCHITECTURE.md](ARCHITECTURE.md), [docs/TECHNICAL.md](docs/TECHNICAL.md) |
| Bug fix or breaking change | [CHANGELOG.md](CHANGELOG.md) |
| Tracking / analytics | [docs/tracking.md](docs/tracking.md) |
**Navigation**: [CONTRIBUTING.md](CONTRIBUTING.md) (you are here) → [docs/TECHNICAL.md](docs/TECHNICAL.md) (architecture + flow) → each folder's `README.md` (implementation details).
Keep documentation concise and practical -- examples over explanations.