Skip to content
푸땡로그
Go back

token-router: 큰 로그에서 필요한 원문만 추리는 컨텍스트 도구

Updated:

token-router ↗는 큰 로그나 소스 파일에서 필요한 범위를 찾아 코딩 에이전트에 전달하는 도구입니다. 요약문을 생성하지 않고 원문 조각을 반환합니다.

2026년 10월 14일 확인한 v2.7.1의 기본 경로는 Python만 사용합니다. 로컬 LLM, Ollama, 모델 로그인은 필요하지 않습니다. 과거 로컬 모델을 전제로 했던 설치 안내와 구분해 읽어야 합니다.

원문을 추리는 흐름

flowchart TD
  A["로그·소스·참고 문서"] --> B["검색어 또는 함수명 지정"]
  B --> C["Python 라우터가 범위 추출"]
  C --> D["줄 번호가 붙은 원문 조각"]
  D --> E["코딩 에이전트가 근거 확인"]
  E --> F{"맥락이 충분한가?"}
  F -->|예| G["분석·수정"]
  F -->|아니오| H["누락된 범위 추가 읽기"]

조각이 원문과 같다는 것과 필요한 내용을 빠짐없이 찾았다는 것은 다른 조건입니다. 함수의 호출 관계나 다른 파일의 설정이 필요하다면 에이전트가 그 범위도 읽어야 합니다.

설치와 첫 실행

공식 README ↗는 Python 3.10–3.14와 표준 라이브러리를 사용합니다. 버전을 고정해 설치합니다.

Bash
git clone --branch v2.7.1 --depth 1 https://github.com/sleeplesshan/token-router.git
cd token-router
python3 scripts/install.py install --dest "$HOME/.agents/skills/token-router"
python3 "$HOME/.agents/skills/token-router/scripts/router.py" --version

설치는 스킬 파일을 배치합니다. 이것만으로 모든 파일 읽기를 가로채지는 않습니다.

긴 코드에서는 조사할 함수 이름을 지정합니다. 아래 파일·함수 이름은 설명용 예제이며 실제 프로젝트 값으로 바꿉니다.

Bash
python3 scripts/router.py heavy_code path/to/module.py \
  --symbol Store.lookup --symbol helper --line-numbers --compact-status

분산된 오류 로그에서는 구체적인 검색어를 지정합니다.

Bash
python3 scripts/router.py error_log path/to/ci.log \
  --search-term 'ERROR: worker (' --search-term 'Total test files:' \
  --activation-profile log-context --line-numbers --compact-status

표준 출력은 선택된 원문입니다. 줄 번호와 내용이 조사하려는 오류를 설명하는지 확인합니다. 범위가 부족하면 검색어를 좁히거나 필요한 구간을 직접 읽습니다.

모드입력 대상
error_log로그·스택 추적·CI 출력
heavy_code긴 소스 파일
agent_context작업별 참고 지침

필수 지침을 라우팅으로 누락해서는 안 됩니다. 항상 적용할 규칙은 짧게 유지하고, 선택적으로 읽을 참고 문서를 분리합니다.

토큰을 아껴도 더 빨라지지는 않을 수 있습니다

README의 16회 실험 ↗은 v2.7.0/e3b5217, gpt-6.1-sol medium, 모델 선택 호출 없는 조건입니다. v2.7.1은 해당 실행 로직을 유지합니다. 아래는 실험 중 실제 로그 작업의 입력·출력 토큰과 총 경과 시간입니다.

로그 작업 · 입력 + 출력 토큰

0–120000 토큰 · 낮을수록 적음

일반 검색
112,242
연결된 게이트
82,143

26.82% 감소. 파일 일부만 추린 비율과 전체 실행의 토큰 절감을 구분합니다.

로그 작업 · 총 경과 시간

0–60초 · 낮을수록 빠름

일반 검색
42.76초
연결된 게이트
54.50초

같은 실험에서 시간은 27.46% 늘었습니다.

이 실험으로 모든 프로젝트의 절감률을 보장할 수는 없습니다. 과거의 98–99% 원문 축소율을 작업 전체의 비용 절감으로 읽어서도 안 됩니다. 이미 효율적으로 검색하는 에이전트라면 추출 단계를 추가하는 이점이 작을 수 있습니다.

언제 직접 읽을까

범위가 분명한 오류 조사에는 선택적으로 적용할 수 있습니다. 넓은 아키텍처 검토, 여러 파일에 걸친 리팩터링, 전체 감사에서는 충분한 원문을 직접 읽는 편이 맞습니다.

도입 여부는 같은 문제로 비교합니다. 답변의 근거가 유지되는지 먼저 확인한 뒤 토큰과 시간을 기록합니다. 에이전트 메모리는 이전 작업의 맥락을 유지하고, token-router는 이번 작업에서 읽을 범위를 줄입니다.

참고 자료

2026년 10월 14일 수정: v2.7.1의 모델 없는 기본 경로로 설치·사용 안내를 갱신했습니다. 과거 원문 축소율 대신 토큰과 실행 시간을 함께 측정한 실험을 추가했습니다.


Share this post on:

Previous Post
Gemini 4 Argon·GPT-6 Astra·Claude Fable 5.1: 성능과 도입 조건 비교
Next Post
AI-native SDLC: 코드 생성 이후의 검토와 운영을 연결하는 방법