rtk-ai/rtk

enhancement: document all filtering behaviors and data loss per command

Open

#1,163 建立於 2026年4月10日

在 GitHub 查看
 (2 留言) (1 反應) (0 負責人)Rust (48,085 star) (2,914 fork)batch import
documentationeffort-mediumgood first issue

描述

Problem

RTK's README and docs describe the token savings benefits but do not clearly document what data is lost or transformed for each command. Users and AI agents need to understand the trade-offs before enabling the hook.

Missing documentation

For each supported command, users should know:

Command What RTK does What is lost
`rtk curl` JSON->schema, 30-line truncation Actual API response values
`rtk grep` 80 char line limit, 200 result cap Long matches, results beyond 200
`rtk ls` Tree view, grouped by directory Permissions, sizes, dates, symlinks
`rtk git diff` Changed lines only Context lines, hunk headers (partially fixed in #1009)
`rtk git log` One-line commits Full commit messages, diffs
`rtk cat/read` Signature extraction, line limits File body content (in aggressive mode)
`rtk cargo test` Failures only Passing test names, warnings
`rtk env` Masks sensitive values Actual environment variable values

Impact

  1. Users cannot make informed decisions about which commands to exclude
  2. AI agents cannot reason about when to use rtk proxy vs rtk commands
  3. Debugging is harder when users do not realize output is filtered

Proposed solution

Create a new doc: `docs/FILTERING_BEHAVIOR.md` that documents:

  1. Per-command filtering behavior: What each command filter does
  2. Data loss matrix: What information is removed or transformed
  3. Workarounds: How to get raw output for each command
  4. Recommended excludes: Which commands to exclude based on use case

Acceptance criteria

  • New documentation file exists at docs/FILTERING_BEHAVIOR.md
  • Each supported command has a documented filtering behavior
  • Data loss is clearly described
  • Workarounds (exclude_commands, --raw, proxy) are documented

貢獻者指南