내 문서를 키워드와 의미로 찾는 로컬 검색 CLI 만들기

## 런타임을 하나로 정하고 명령마다 역할 나누기 지원되는 런타임과 패키지 관리자 한 조합을 공식 개발 경로로 선택한다. 호환되는 것처럼 보인다는 이유만으로 대체 런타임이나 설치 명령을 섞지 않는다. 명령의 책임을 명확히 유지한다. - 컬렉션 명령은 인덱싱된 루트와 그 구성을 관리한다. - 컨텍스트 명령은 검색 지침을 경로에 연결한다. - 문서 조회 명령은 알려진 문서를 반환한다. - 검색 명령은 후보 문서의 순위를 정한다. - 유지관리 명령은 인덱스를 점검하거나 갱신한다. - 서비스 명령은 다른 프로세스에 동일한 기능을 제공한다. 설치된 명령 래퍼가 컴파일된 애플리케이션 코드를 호출한다면 그 래퍼를 보존한다. 문서화된 컴파일러 워크플로로 소스를 빌드하며, 네이티브 확장이 기존 배치에 의존할 때는 래퍼를 하나의 컴파일된 실행 파일로 교체하지 않는다. ## 컬렉션마다 설정을 기록하고 제외와 제거 구분하기 각 컬렉션을 고유 이름, 소스 루트, 파일 마스크, 포함 상태, 선택적인 업데이트 전 훅으로 표현한다. 컬렉션 추가, 목록 표시, 점검, 이름 변경, 포함, 제외, 제거 작업을 지원한다. 제거와 제외를 구분한다. 제거는 컬렉션 등록 자체를 없애지만, 제외는 범위가 지정되지 않은 쿼리에서만 해당 컬렉션을 생략한다. 컬렉션 전체 또는 경로 접두사에 대한 파일 목록을 제공한다. 인터페이스가 지원한다면 일반 컬렉션 경로와 도구의 가상 컬렉션 URI를 모두 허용한다. 추가, 제거, 이름 변경, 훅 변경, 포함 상태 변경, 인덱스 갱신을 상태 변경으로 취급한다. 사용자 승인이 필요할 때는 실행 전에 정확한 명령과 예상 효과를 제시한다. ## 검색 안내(컨텍스트)를 문서와 따로 경로별로 붙이기 사람이 작성한 컨텍스트를 문서 내용과 별도로 저장하여, 소스 파일을 다시 쓰지 않고도 순위 지침을 발전시킬 수 있게 한다. 다음 위치에 컨텍스트를 설정할 수 있어야 한다. - 컬렉션 안에서 감지된 현재 디렉터리 - 특정 하위 경로 - 가상 컬렉션 경로 - 모든 컬렉션에 적용되는 지침을 위한 전역 루트 컨텍스트 목록 표시, 컨텍스트가 없는 경로 감지, 오래된 컨텍스트 제거를 위한 명령을 제공한다. 전역 지침을 유지하면서 관련성이 있고 가장 구체적인 범위의 컨텍스트를 적용한다. 컨텍스트 메타데이터와 인덱싱된 문서 텍스트를 혼동하지 않는다. 로컬 메모가 무관한 컬렉션에 조용히 영향을 주지 않도록 범위를 드러낸다. ## 문서마다 짧은 ID를 붙이고 돌려주는 양에 상한 두기 각 문서에 콘텐츠 해시의 앞 6글자에서 파생된 짧은 식별자를 부여한다. 검색 결과에 식별자를 표시하고, 앞쪽 마커가 있거나 없어도 허용한다. 경로나 식별자를 통한 조회, 선택적인 시작 줄과 줄 수, glob 또는 쉼표로 구분된 목록을 통한 일괄 조회를 지원한다. 조회 범위를 명시적으로 제한한다. - 파일별 최대 줄 수를 설정한다. - 최대 바이트 수를 설정하고 10 KB 같은 기본값을 문서화한다. - 알림 없이 일부 내용만 반환하지 말고 너무 큰 파일은 건너뛴다. - 기본적으로 줄 번호를 포함하고 호출자가 이를 끌 수 있게 한다. - 요청받은 경우에만 디스크의 전체 경로를 반환한다. ## 질문에 맞는 검색 방식을 고르고 평소에는 하이브리드 검색 쓰기 서로 다른 세 가지 검색 경로를 제공한다. - 언어 모델 없이 BM25 같은 전체 텍스트 순위화를 사용하는 키워드 검색 - 재순위화 없이 로컬 임베딩을 사용하는 벡터 유사도 검색 - 최고 품질의 기본 경로로서 쿼리 확장과 재순위화를 사용하는 확장형 하이브리드 쿼리 검색 독립적으로 순위가 정해진 결과 집합을 역순위 융합으로 결합한다. 예상치 못한 순서를 진단할 수 있도록 원래 점수와 검색 방식을 충분히 드러낸다. 일반적인 용도에는 하이브리드 쿼리 경로를 우선한다. 정확한 용어가 중요하면 키워드 검색, 의미적 유사성이 목적이면 벡터 검색, 최종 순위 품질보다 속도가 중요하면 재순위화하지 않는 옵션을 선택한다. ## 검색할 컬렉션과 출력 형식을 고르게 하되 표시 때문에 결과가 바뀌지 않게 하기 호출자가 컬렉션 필터를 반복 지정하여 이름이 지정된 여러 컬렉션만 검색하고 나머지는 모두 제외할 수 있게 한다. 결과 수, 전체 결과 모드, 최소 점수, 전체 콘텐츠 모드, 순위화를 구체화하는 의도 설명을 지원한다. 표시와 데이터 전송을 분리한다. 읽기 쉬운 명령줄 형식과 함께 구조화된 JSON, CSV, Markdown, XML, 파일 목록 출력을 제공한다. 이전 형식 플래그는 하나의 공식 형식 옵션에 대한 별칭으로만 유지한다. 일괄 조회에서는 줄 제한, 바이트 제한, 줄 번호 제어를 검색 순위화와 독립적으로 제공한다. 표시 옵션이 선택되는 문서를 바꾸지 않게 한다. ## 검색 인덱스를 만들고 문서를 예측 가능한 청크로 나누기 전체 텍스트 인덱싱에는 영속적인 로컬 데이터베이스를 사용하고, 의미적 유사성에는 호환되는 벡터 확장을 사용한다. 구성된 로컬 모델로 임베딩, 재순위화, 쿼리 확장을 실행한다. 청크당 900개 토큰과 15% 중첩을 목표로 지능형 문서 청킹을 사용한다. 가능하면 Markdown 제목을 경계로 우선한다. 지원되는 코드 파일에는 추상 구문 트리를 인식하는 전략을 제공하여 청크가 함수, 클래스, 임포트 경계에 맞춰지게 한다. 명시적인 자동 전략으로 이를 선택한다. 정규식 청킹을 기본값으로 유지하고 Markdown 및 알 수 없는 파일 형식에 일관되게 사용한다. 전체를 다시 구축하지 않고도 실패를 진단할 수 있도록 인덱싱, 임베딩 생성, 쿼리 시점 순위화를 별도 단계로 유지한다. ## 순위를 조정하기 전에 인덱스와 모델 상태 확인하기 상태를 변경하지 않고 컬렉션과 인덱스의 건전성을 보여 주는 상태 출력을 제공한다. 구성, 인덱스, 모델, 장치 문제를 위한 진단 명령을 추가한다. 버전이 지정된 픽스처 파일로 검색 품질을 벤치마크한다. 비교를 재현할 수 있도록 쿼리, 관련성이 있을 것으로 예상되는 문서, 검색 방식, 순위 지표, 모델 구성, 인덱스 버전을 기록한다. 순위 가중치, 모델 또는 장치 설정을 바꾸기 전에 진단한다. 모델 누락, 오래된 인덱스, 호환되지 않는 벡터 확장, 사용할 수 없는 장치는 그 자체로 순위 알고리즘이 잘못되었다는 증거가 아니다. ## 요청받을 때만 도구를 로컬 또는 HTTP 서비스로 실행하기 로컬 프로세스 통합을 위한 표준 입력 및 출력 서비스와 원격 클라이언트를 위한 선택적 HTTP 서비스를 제공한다. 명시적인 재지정을 허용하면서 8181 같은 문서화된 기본 포트를 사용한다. 디버깅을 위한 포그라운드 실행과 장기 사용을 위한 백그라운드 데몬 모드를 지원한다. 관리 대상 데몬만 중지하는 대응 중지 명령을 제공한다. 서비스 전송 방식과 검색 의미를 분리한다. 명령줄 인터페이스와 서비스 인터페이스는 컬렉션, 컨텍스트, 조회, 순위화, 출력 규칙을 공유해야 한다. 백그라운드 서비스를 암묵적으로 시작하지 않는다. 서비스를 시작하면 엔드포인트, 프로세스 모드, 구성 출처, 종료 방법을 보고한다. ## 인덱스를 바꾸는 작업은 사용자에게 맡기고 설치된 래퍼 망가뜨리지 않기 컬렉션 추가, 임베딩 생성 또는 인덱스 갱신을 절대 자동으로 수행하지 않는다. 기반 검색 데이터베이스를 절대 직접 수정하지 않는다. 요청된 워크플로에 이러한 변경이 필요하면 사용자가 실행할 정확한 명령을 보여 주고 예상 파일, 소요 시간, 자원 사용량을 설명한다. 권한 범위를 넓히지 않으면서 읽기 전용 검색과 조회를 계속 사용할 수 있게 한다. 설치된 셸 래퍼를 덮어쓰거나 네이티브 벡터 확장을 손상시키는 컴파일 모드를 실행하지 않는다. 배포 디렉터리의 컴파일된 JavaScript를 의도적으로 실행하는 래퍼를 교체하지 않는다. 업데이트 전 훅을 실행 가능한 구성으로 취급한다. 점검할 때 이를 표시하고, 명시적으로 요청된 인덱스 갱신의 일부로만 실행한다. ## 회귀 테스트를 추가하고 변경 기록과 함께 릴리스하기 자동화 테스트를 지정된 테스트 트리에 두고, 지원되는 런타임으로 문서화된 전체 테스트 모음을 실행한다. 컬렉션 상태, 조회 제한, 순위 방식, 청크 경계, 서비스 수명 주기에 대해 범위가 좁은 회귀 테스트를 추가한다. 릴리스를 수동으로 조립하지 말고 공식 릴리스 워크플로를 사용한다. 1. 변경할 때마다 미출시 섹션에 변경 기록 항목을 추가한다. 2. 릴리스할 때 해당 섹션을 날짜가 있는 버전으로 변환한다. 3. 프로젝트에서 요구하는 참조 형식으로 외부 기여자를 명시한다. 4. 의도한 버전 계열 전체의 릴리스 노트를 집계한다. 5. 게시 전에 릴리스 훅과 검증을 실행한다. 변경된 동작, 인덱스 또는 스키마 호환성, 실행한 테스트, 벤치마크 영향, 마이그레이션 필요 여부, 사용자에게 남겨 둔 상태 변경 명령을 보고한다.