집

Skill

데이터베이스 관리

kb-retriever

ConardLi/garden-skills

계층적 인덱스 파일을 탐색하여 로컬 지식 기반 디렉터리에서 질문을 검색하고 답변한 다음, grep, Read, pdfplumber 및 pandas를 사용하여 마크다운, PDF 및 엑셀 파일을 단계적으로 검색합니다.

...모든 것을 확장하십시오

업데이트 된 시간 2026년 9월 30일

# markdown # excel # pandas # pdf # grep # knowledge base # local search # pdfplumber

로컬 지식베이스 검색 Skill (kb-retriever)

지식베이스 디렉토리 설명

지식베이스는 하나의 루트 디렉토리에 저장되며, 다양한 파일 유형(예: .md/.txt、.pdf、.xlsx 등)을 포함하며, 일반적으로 유형이나 업무 용도에 따라 다단계 하위 디렉터리로 구분됩니다.
계층적 디렉토리 구조를 사용하여 파일을 색인화합니다:
- 루트 디렉토리에는 data_structure.md가 있으며, 주요 「분야 디렉터리」와 그 용도를 설명합니다.
- 각 분야 디렉터리 아래에는 해당 디렉터리 하위의 하위 디렉터리/파일 및 각각의 용도를 설명하는 data_structure.md가 있어, 해당 디렉토리 아래에 어떤 하위 디렉토리/파일이 있는지 및 각각의 용도를 설명합니다.
- 더 깊은 수준의 하위 디렉토리에도 계속해서 data_structure.md를 포함할 수 있어, 다단계 인덱스 트리를 형성합니다.
지식베이스 루트 디렉터리 규칙:
- 기본적으로 지식베이스는 현재 프로젝트의 루트 디렉터리 아래에 위치한 knowledge/ 디렉터리에 위치한다고 간주합니다.
- 사용자가 대화에서 다른 경로를 명시적으로 지정한 경우(예: “내 지식베이스는 /data/kb에 있습니다” 또는 “./docs 디렉터리를 지식베이스로 사용하겠습니다”), 사용자가 지정한 경로를 루트 디렉터리로 사용합니다.
- 기본 경로가 knowledge/ 존재하지 않거나 접근에 실패할 경우, 임의로 추측하지 말고 사용자에게 실제 지식베이스 루트 디렉토리 위치를 확인해야 합니다.
개별 비즈니스 파일의 크기가 클 수 있으므로:
- Read를 사용하여 파일 전체를 직접 읽지 마십시오
- PDF, Excel의 경우 해당 스킬을 사용하여 구조화한 후, grep/부분 읽기를 결합하여 정밀한 검색을 수행하십시오

위치 파악 `knowledge` 루트 디렉터리

루트 디렉터리는 사용자의 지시를 우선으로 합니다: 사용자가 경로를 제공한 경우(예: ./docs、./knowledge-personal), 사용자가 제공한 경로를 직접 사용합니다.
기본 루트 디렉터리: 그렇지 않은 경우, 루트 디렉터리를 현재 프로젝트 아래의 knowledge/。
- 쉘을 사용하여 디렉터리가 존재하는지 명시적으로 확인: 우선 test -d knowledge를 사용하거나, 차선책으로 ls -d knowledge。
- 주의: Glob "knowledge" in . 이 같은 패턴을 사용하여 디렉터리의 존재 여부를 판단하는 것은 금지되며,Glob 파일 경로만 반환하고 디렉터리 자체는 반환하지 않으므로, 빈 결과는 “디렉터리가 존재하지 않음”과 “디렉터리가 존재하지만 비어 있음”을 구분할 수 없습니다.
루트 디렉터리가 test -d 등의 방법으로 존재가 확인된 경우에만 Glob을 사용하여 해당 디렉터리에서 내용을 검색하고, 디렉터리를 path로 사용해야 합니다. 예:
- 인덱스 파일:pattern="**/data_structure.md", path="knowledge"
- 모든 Markdown:pattern="**/*.md", path="knowledge"
기본값으로 knowledge/ 존재하지 않는 경우(test -d 실패): 다른 디렉터리를 추측하지 말고, 사용자에게 기본 루트 디렉터리를 찾을 수 없음을 명확히 알리고, 사용자가 실제 지식베이스 경로를 지정하도록 하십시오.

핵심 원칙: 먼저 확인하고, 그 다음 처리

PDF 또는 Excel 파일을 처리할 때의 필수 점검 목록:

✅ 해당 references 문서를 읽고 처리 방법을 숙지함
✅ 권장 도구 및 명령어를 이해함
✅ 파일 처리(추출/변환) 완료
⏭️ 이제 검색을 시작할 수 있습니다

금지 사항:

❌ pdf_reading.md를 읽지 않은 상태에서 바로 PDF 처리를 시도하는 것
❌ excel_reading.md를 읽지 않은 상태에서 바로 Excel 처리를 시도하는 것
❌ 파일 처리 단계를 건너뛰고 원본 PDF/Excel에 직접 검색을 수행하는 경우

전체 흐름

사용자 요구사항 파악
- 사용자 질문을 읽고 다음을 추출:
  - 주제/분야 키워드(예: “판매 보고서”, “시스템 아키텍처”, “인터페이스 문서”)
  - 시간 또는 범위 제한 (예: “2023년 1분기”, “최신 버전”)
  - 필요한 출력 유형 (설명, 요약, 구체적인 필드 수치 등)
- 지식베이스 루트 디렉터리 확인:
  - 먼저 사용자가 질문에서 지식베이스 경로를 지정했는지 확인합니다.
  - 그렇지 않은 경우 기본 루트 디렉터리를 사용합니다. knowledge/。
  - 기본 루트 디렉터리가 존재하지 않거나 디렉터리 구조에 이상이 있는 경우, 임의로 가정하지 말고 사용자에게 확인을 요청해야 합니다.
계층별로 디렉터리 인덱스를 확인합니다. data_structure.md
- '현재 작업 디렉터리' 개념을 사용합니다:
  - 기본적으로 사용자가 지정한 지식베이스 루트 디렉터리에서 시작하며, 사용자가 지정하지 않은 경우 현재 디렉터리를 사용합니다.
- 현재 작업 디렉터리 아래에 data_structure.md：
  - Read를 사용하여 해당 파일의 앞부분 몇 줄(예: limit=300)을 읽고, 필요한 경우 여러 번에 나누어 계속 읽습니다.
  - 목표:
    - 현재 디렉터리 아래에 어떤 하위 디렉터리와 파일이 있는지 파악하기
    - 각 하위 디렉터리/파일의 용도 설명을 이해한다
  - 사용자의 문제를 바탕으로 가장 관련성이 높은 몇 개의 하위 디렉터리나 파일을 선정하여 후보 집합을 구성한다.
- 후보 하위 디렉터리에 대해:
  - 해당 하위 디렉터리로 재귀적으로 진입하여 이를 새로운 「현재 작업 디렉터리」로 삼고, 그 안의 data_structure.md 위 과정을 반복합니다.
  - 재귀 과정에서 모든 분기를 한 번에 깊이 탐색하는 것을 피하고, 문제와 가장 관련성이 높은 경로를 따라 우선적으로 탐색합니다.
- 후보 업무 파일(md/텍스트, PDF, Excel 등)의 경우:
  - 필요한 디렉터리 계층 탐색을 완료한 후, 이러한 파일을 최종 검색 대상 목록으로 수집한다.
- 우선순위를 정할 때는:
  - 용도 설명이 문제 주제와 매우 잘 일치하는 영역 디렉터리와 파일을 우선적으로 선택합니다.
  - 그 다음으로 시간/버전 등의 제약 조건(인덱스에 반영된 경우)을 고려합니다.
  - 일반 설명 문서(예: README.md, 전체 설계 문서 등)는 우선순위가 상대적으로 낮게 설정합니다
파일 처리 방법을 숙지한다(PDF/Excel 파일의 경우 반드시 적용).
- PDF 파일을 처리하기 전에:
  - 반드시 먼저 references/pdf_reading.md를 읽어야 합니다(이 디렉터리는 Knowledge 디렉터리가 아닌 Skills 디렉터리 아래에 위치해 있음에 유의하십시오). 추출 방법을 익히십시오
  - 중점적으로 파악할 사항: pdftotext 명령어, pdfplumber 사용법, 표 추출 방법
- Excel 파일을 처리하기 전에:
  - 반드시 먼저 references/excel_reading.md를 읽고 읽기 방법을 익혀야 합니다
  - 반드시 references/excel_analysis.md를 읽고 분석 방법을 익혀야 합니다
  - 중점적으로 파악할 내용: pandas를 이용한 읽기, 열 필터링, 데이터 필터링
- 목적: 올바른 도구와 방법을 사용하여 무분별한 검색을 방지하기 위함
파일 유형에 따라 처리 및 검색을 수행하십시오
- 방금 배운 방법(추출, 변환, 구조화)을 사용하여 파일을 처리
- 각 후보 파일 유형에 대해 아래의 「Markdown/텍스트」「PDF」「Excel」 전략에 따라 수행
- 총칙:
  - 가장 관련성이 높고 정확한 파일부터 우선적으로 처리
  - 각 파일 내에서 점진적으로 부분 검색을 수행하며, 전체 내용을 한 번에 불러오는 것을 피한다
  - 현재 파일에서 만족스러운 정보를 얻지 못하면 다음 후보 파일로 전환한다
반복 검색
- 모든 문서 유형에 대해 통일된 「다단계 반복 검색 메커니즘」을 사용한다(상기 공통 검색 원칙 참조)
답변 구성 및 출처 추적
- 여러 단계의 검색을 통해 얻은 맥락을 종합하여 사용자의 질문에 답변합니다.
- 가능한 한:
  - 명확하고 직접적인 답변을 제시
  - 사용된 문서명을 명시합니다(필요한 경우 장이나 대략적인 행 번호/페이지 수 등 대략적인 위치를 포함).
- 답변이 추론에 기반하거나 정보가 불완전한 경우:
  - 가정과 불확실성을 명확히 표기
  - 사용자가 더 구체적인 문서 범위나 키워드를 추가할 수 있도록 안내하십시오

공통 검색 원칙

키워드 선정 전략

사용자의 질문에서 3~8개의 키워드 추출 (가능한 영어 약어, 동의어, 상위/하위어 포함)
조합 가능한 구문(예: "판매 보고서", "API 인터페이스 타임아웃")
필요한 경우 업무 용어, 기술 용어, 일반적인 약어(예: "uv", "pv", "GMV") 포함

grep 검색 기본 원칙

항상 가능한 한 정확한 include 및 path를 지정하여 전체 디렉터리를 검색하지 않도록 한다
pattern은 문제 문맥의 핵심 명사나 용어를 우선적으로 시도한 후, 동의어를 시도합니다
각 일치 항목에 대해서는 일치 부근의 국부 영역(위아래 몇 줄)만 읽습니다
「파일명 + 위치 정보 + 텍스트 조각」을 저장

다단계 반복 검색 메커니즘(최대 5회)

모든 파일 유형에 대해 통일된 반복 전략을 적용합니다:

반복 제어
- 「검색 시도 횟수」 카운터를 유지하며, 최대 5회
- 매 검색 후 카운트를 누적
각 반복 단계의 절차
1. 문제를 기반으로 검색 키워드 생성/업데이트 (동의어, 확장어 포함 가능)
2. 아직 충분히 검색되지 않은 파일 또는 파일의 일부를 선택
3. 검색 실행(grep/부분 읽기/전용 스킬 호출)
4. 획득한 문맥 단편 분석
5. 질문에 답하기에 충분한지 판단
종료 조건
- 답변을 뒷받침하기에 충분한 문맥을 찾았을 경우; 또는
- 5회 시도 후에도 적절한 정보를 찾지 못한 경우
정보가 부족한 경우의 처리
- 사용자에게 정보가 누락되었거나 현재 지식베이스에 없을 수 있음을 명확히 알림
- 찾은 정보 중 가장 근접한 내용을 제공하고, 불확실성을 설명
- 사용자가 검색 범위를 좁힐 수 있는 방법(더 구체적인 파일명, 키워드, 기간 등)을 안내

주의 사항

첫 번째 시도에서 다음을 직접 호출하는 것을 금지합니다:Glob "knowledge" in . Glob을 사용하여 디렉터리 존재 여부를 판단하려는 모든 호출은 금지되며, 디렉터리 존재 여부는 셸 명령어(예: test -d)을 통해 확인해야 합니다.
이 스킬을 사용하여 지식 기반을 검색할 때, 웹 검색 등 다른 도구를 통해 정보를 수집해서는 안 됩니다

파일 유형별 구체적인 정책

1. 마크다운/텍스트 파일(.md, .txt, .log 등)

후보 파일 선정
- 다음에 따라 data_structure.md 파일명 및 경로를 바탕으로 관련성을 판단합니다
- 제목 및 목차 유형의 파일(예: 요약 문서, 설계 개요)을 우선적으로 검색
grep을 이용한 위치 파악 및 부분 읽기
- grep 도구를 사용하여 지정된 후보 파일을 검색하며, include 옵션을 통해 특정 확장자(예: "*.md")를 제한
- 일치하는 파일에 대해서는 Read를 사용하여 일치하는 부분 주변의 국부 영역만 읽습니다:
  - 줄 번호 오프셋과 limit을 통해 읽기 범위를 제어합니다(예: 일치하는 줄 주변으로 앞뒤로 각각 수십 줄씩 읽음)
  - 파일 전체 읽기를 피합니다
특별 처리
- 내용이 단지 목차나 제목인 경우, 링크나 소제목명을 바탕으로 해당 내용을 더 깊이 찾아갑니다
- 「다단계 반복 검색 메커니즘」(위 ‘공통 검색 원칙’ 참조)을 적용합니다

2. PDF 파일 검색 전략

워크플로우:

먼저: 처리 방법 가이드 읽기
- 어떤 PDF를 처리하기 전에 반드시 references/pdf_reading.md를 읽어야 합니다(이 디렉터리는 Knowledge 디렉터리가 아닌 Skills 디렉터리 아래에 위치해 있음에 유의하십시오).
- 중점적으로 파악할 사항: pdftotext 명령어, pdfplumber 사용법, 표 추출 방법, 신속 의사결정표
후보 PDF 선택
- 설명에 따라 data_structure.md 의 설명에 따라 가장 관련성이 높은 1~3개의 파일을 선택하십시오
- 사용자가 특정 PDF 파일을 지정한 경우, 해당 파일을 우선적으로 사용합니다
학습한 방법을 적용하여 텍스트 추출
- pdf_reading.md에서 권장하는 도구(pdftotext 또는 pdfplumber 우선)를 사용하십시오
- 중요: pdftotext input.pdf output.txt 텍스트를 파일로 추출하고, stdout에 직접 출력하지 마십시오(대량의 토큰을 차지하는 것을 방지하기 위해).
- 표 추출이 필요한 경우, pdfplumber의 표 추출 기능을 사용하십시오
추출된 결과에 대해 검색을 수행하십시오
- grep을 사용하여 추출된 텍스트에서 키워드를 검색하십시오
- 각 일치 항목에 대해, 일치 부근 범위의 문맥(위아래 수십 줄 또는 인접한 몇 페이지)을 추출하십시오
- 「파일명 + 페이지 번호/대략적인 위치 + 텍스트 조각」을 저장하십시오
- 「다단계 반복 검색 메커니즘」을 적용합니다(위의 공통 검색 원칙 참조)

3. Excel 파일 검색 전략

워크플로우:

먼저: 처리 방법 지침을 읽습니다.
- 어떤 엑셀 파일을 처리하기 전에 반드시 다음을 읽어야 합니다:
  - references/excel_reading.md - 워크시트 읽는 방법 학습 (이 디렉터리는 Knowledge 디렉터리가 아닌 Skills 디렉터리 아래에 위치해 있음에 유의)
  - references/excel_analysis.md - 데이터 분석 방법 학습 (이 디렉터리는 Knowledge 디렉터리가 아닌 Skills 디렉터리 아래에 위치해 있음에 유의하십시오)
- 중점적으로 파악해야 할 내용: pandas 읽기 방법, 열 필터링, 데이터 필터링, 집계 연산
후보 엑셀 파일 선택
- 다음에 따라 data_structure.md 및 파일/워크시트 이름을 기준으로 가장 관련성이 높은 시트를 선택합니다
- '보고서', '통계', '로그', '구성', '매핑' 등의 키워드가 포함된 통합 문서/워크시트를 우선적으로 선택
- 사용자가 구체적인 Excel 파일을 지정한 경우, 해당 파일을 우선적으로 사용
학습된 방법을 적용하여 구조 탐색
- pandas를 사용하여 처음 10~50행을 읽습니다( nrows 매개변수 제한 적용)
- 중점적으로 파악할 사항: 열명/필드명, 데이터 유형(숫자, 날짜, 텍스트), 핵심 필드
- 열 이름을 사용자의 질문과 대조하여 잠재적인 핵심 필드(예: 「수입」「매출액」「error_code」 등)를 식별합니다
데이터 검색 및 분석 수행
- 배운 pandas 메서드를 사용하여 필터링 및 집계 수행 (예: df[df['column'] == value]）
- 한 번에 전체 테이블을 읽지 말고, 매번 일치하는 행 주변의 데이터만 읽도록 한다
- 질문에 시간 범위가 포함된 경우, 검색 시 시간 필터를 적용
- 「다단계 반복 검색 메커니즘」(위의 공통 검색 원칙 참조)을 적용합니다.

다른 도구와의 연계

PDF 처리

PDF를 처리하기 전에 반드시 references/pdf_reading.md를 읽어 처리 방법을 숙지해야 합니다
pdfplumber/pypdf를 사용하여 텍스트 추출, 표 추출, 메타데이터 읽기
신속한 텍스트 추출을 위해 pdftotext 명령줄 도구를 우선적으로 사용

Excel 처리

Excel을 처리하기 전에 반드시 다음 문서를 읽어보아야 합니다:
- references/excel_reading.md - 읽기 방법을 학습합니다
- references/excel_analysis.md - 분석 방법 학습
pandas를 사용하여 데이터 탐색, 미리 보기, 필터링 및 분석 수행

도구 사용 원칙

Grep: 지정된 파일에서 키워드를 기준으로 행 번호와 일치하는 구절을 찾는 데 사용하며, 항상 가능한 한 정확한 include 및 path를 지정해야 합니다
Read: 파일의 일부만 읽을 때만 사용하며, 항상 적절한 limit(예: 200~500행)과 적합한 오프셋을 설정해야 합니다
크기가 매우 클 가능성이 있는 파일의 경우:
- 파일 시작부터 끝까지 직접 읽지 마십시오
- 항상 먼저 인덱스, 디렉터리, 키워드 등을 통해 범위를 좁힌 후 읽어야 함

답변 스타일 및 오류 처리

답변 스타일
- 가능한 한 사용자가 질문한 언어(중국어/영어)로 답변하십시오.
- 먼저 결론을 제시하고, 그 다음 간략한 근거를 제시하십시오.
- 필요한 경우, 뒤쪽에 인용한 파일과 대략적인 위치를 나열할 수 있습니다. 예:
  - 출처: design/api_gateway.md 100행 부근
  - 출처: reports/2023_Q1_sales.xlsx, Summary 시트
정보가 누락되었거나 불확실한 경우
- 현재 지식베이스에서 완전히 일치하는 정보를 찾을 수 없거나 부분적으로만 답변할 수 있음을 명확히 설명하십시오.
- 사실을 임의로 지어내지 마십시오.
- 사용자가 범위를 좁힐 수 있는 방법을 안내하십시오:
  - 더 구체적인 디렉터리/파일 지정
  - 더 정확한 키워드나 필드명을 제공하십시오
  - 시간/버전 범위를 지정

GitHub에서 보기

---
name: kb-retriever
description: Retrieves and answers questions from a local knowledge base directory by navigating hierarchical index files, then progressively searching Markdown, PDF, and Excel files using grep, Read, pdfplumber, and pandas.
---

# 本地知识库检索 Skill（kb-retriever）

## 知识库目录说明

- 知识库存放在一个根目录下，包含多种文件类型（如 `.md`/`.txt`、`.pdf`、`.xlsx` 等），通常按类型或业务用途拆分为多级子目录。
- 采用**分层目录索引文件**：
  - 根目录有一个 `data_structure.md`，说明主要的「领域目录」及其用途。
  - 每个领域目录下可以有自己的 `data_structure.md`，说明该目录下有哪些子目录/文件，以及各自用途。
  - 更深一层的子目录也可以继续有 `data_structure.md`，形成多级索引树。
- 知识库根目录约定：
  - 默认认为知识库位于当前项目根目录下的 `knowledge/` 目录。
  - 如果用户在对话中明确指定了其他路径（例如“我的知识库在 /data/kb”或“用 ./docs 这个目录作为知识库”），则以用户指定的路径作为根目录。
  - 当默认路径 `knowledge/` 不存在或访问失败时，应向用户确认实际的知识库根目录位置，而不是随意猜测。
- 单个业务文件可能很大：
  - 不要直接用 Read 读取整文件
  - 对 PDF、Excel 使用对应 Skill 进行结构化处理后，再结合 grep/局部读取做精细检索

### 定位 `knowledge` 根目录

- 根目录优先听用户：如果用户给了路径（如 `./docs`、`./knowledge-personal`），直接用用户提供的路径。
- 默认根目录：否则约定根目录为当前项目下的 `knowledge/`。
  - 使用 shell 显式检查目录是否存在：优先使用 `test -d knowledge`，或退而求其次使用 `ls -d knowledge`。
  - 注意：禁止使用 `Glob "knowledge" in .` 这类模式来判断目录是否存在，`Glob` 只返回文件路径，不返回目录本身，空结果并不能区分“目录不存在”和“目录存在但为空”。
- 只有在根目录已通过 `test -d` 等方式确认存在时，才使用 Glob 在该目录下检索内容，并把目录作为 `path`，例如：
  - 索引文件：`pattern="**/data_structure.md"`, `path="knowledge"`
  - 所有 Markdown：`pattern="**/*.md"`, `path="knowledge"`
- 如果默认 `knowledge/` 不存在（`test -d` 失败）：不要猜测其他目录，明确告诉用户未找到默认根目录，并让用户指定实际知识库路径。

## 关键原则：先学习，再处理

**遇到 PDF 或 Excel 文件时的强制检查清单**：

- [ ] ✅ 已读取对应的 references 文档学习处理方法
- [ ] ✅ 已理解推荐的工具和命令
- [ ] ✅ 已将文件处理（提取/转换）完成
- [ ] ⏭️ 现在可以开始检索

**禁止行为**：
- ❌ 在未读取 pdf_reading.md 的情况下直接尝试处理 PDF
- ❌ 在未读取 excel_reading.md 的情况下直接尝试处理 Excel
- ❌ 跳过文件处理步骤，直接对原始 PDF/Excel 进行检索

## 总体流程

1. 理解用户需求
   - 读用户问题，提取：
     - 主题/领域关键词（如“销售报表”“系统架构”“接口文档”）
     - 时间或范围限定（如“2023 年 Q1”“最近版本”）
     - 需要的输出类型（解释、摘要、具体字段数值等）
   - 确定知识库根目录：
     - 优先检查用户是否在问题中指定了知识库路径。
     - 否则使用默认根目录 `knowledge/`。
     - 若默认根目录不存在或目录结构异常，应向用户询问确认，而不是自行假设。

2. 分层查看目录索引 `data_structure.md`
   - 使用一个「当前工作目录」的概念：
     - 默认从用户指定的知识库根目录开始；如果用户未指定，则使用当前目录。
   - 在当前工作目录下，如果存在 `data_structure.md`：
     - 使用 Read 读取该文件的前若干行（例如 limit=300），必要时分段继续读取。
     - 目标：
       - 了解当前目录下有哪些子目录和文件
       - 理解每个子目录/文件的用途说明
     - 基于用户问题，挑选**最相关的若干个子目录或文件**，构成候选集合。
   - 对于候选子目录：
     - 递归进入该子目录，将其作为新的「当前工作目录」，继续查找其中的 `data_structure.md` 并重复上述过程。
     - 在递归过程中，避免一次性深入所有分支，优先沿着与问题最相关的路径向下钻取。
   - 对于候选业务文件（md/文本、PDF、Excel 等）：
     - 在完成必要的目录层级探索后，收集这些文件为最终的**检索目标列表**。
   - 在优先级排序时：
     - 优先选择用途说明与问题主题高度匹配的领域目录和文件
     - 其次考虑时间/版本等约束（如果索引中有体现）
     - 通用说明类文档（如 README.md、总体设计类文档）放在较后优先级

3. 学习文件处理方法（遇到 PDF/Excel 时强制执行）
   - **在处理 PDF 文件前**：
     - **必须先读取** [references/pdf_reading.md](references/pdf_reading.md)（注意这个目录位于 Skills 目录下，而不是 Knowledge 目录下）学习提取方法
     - 重点了解：pdftotext 命令、pdfplumber 用法、表格提取方法
   - **在处理 Excel 文件前**：
     - **必须先读取** [references/excel_reading.md](references/excel_reading.md)学习读取方法
     - **必须先读取** [references/excel_analysis.md](references/excel_analysis.md)学习分析方法
     - 重点了解：pandas 读取、列筛选、数据过滤
   - **目的**：确保使用正确的工具和方法，避免盲目检索

4. 按文件类型执行处理和检索
   - 使用刚学到的方法处理文件（提取、转换、结构化）
   - 对每类候选文件，按照下面「Markdown/文本」「PDF」「Excel」策略执行
   - 总原则：
     - 优先从最相关、最精确的文件开始
     - 每个文件内都渐进式地局部检索，避免一次性加载全内容
     - 若当前文件得不到满意信息，切换到下一个候选文件

5. 迭代检索
   - 所有文件类型都使用统一的「多轮迭代检索机制」（见上文公共检索原则）

6. 答案组织与溯源
   - 汇总多轮检索得到的上下文，综合回答用户问题。
   - 尽量：
     - 给出清晰、直接的回答
     - 指出使用过的文件名（必要时包含大致位置，如章节或大概行数/页数）
   - 如果答案基于推断或信息不完全：
     - 明确标注假设与不确定性
     - 提示用户可以补充更具体的文件范围或关键词

## 公共检索原则

### 关键词选择策略
- 从用户问题提取 3-8 个关键词（含可能的英文缩写、同义词、上位/下位词）
- 可组合词组（如 "销售 报表"、"API 接口 超时"）
- 必要时包含业务词、技术术语、常见缩写（如 "uv"、"pv"、"GMV"）

### grep 检索基本原则
- 始终指定尽量精准的 include 和 path，避免搜索整个目录
- pattern 优先尝试问题中的核心名词、术语，再尝试同义词
- 对于每个命中，只读取匹配附近的局部区域（上下若干行）
- 保存「文件名 + 位置信息 + 文本片段」

### 多轮迭代检索机制（最多 5 次）
所有文件类型都采用统一的迭代策略：
1. **迭代控制**
   - 维护「已尝试检索次数」计数，最多 5 次
   - 每次检索后累加计数
2. **每轮迭代流程**
   1. 基于问题生成/更新检索关键词（可包括同义词、扩展词）
   2. 选择尚未充分检索的文件或文件部分
   3. 执行检索（grep/局部读取/专用 Skill 调用）
   4. 分析获取的上下文片段
   5. 判断是否足够回答问题
3. **终止条件**
   - 找到足够支撑回答的上下文；或
   - 已达到 5 次尝试仍未找到合适信息
4. **信息不足时的处理**
   - 明确告知用户信息缺失或可能不在当前知识库中
   - 提供已找到的最接近信息，并说明不确定性
   - 提示用户可以如何缩小范围（更具体的文件名、关键词、时间范围等）

### 注意事项

- 禁止第一次就直接调用：`Glob "knowledge" in .` 或任何试图用 Glob 判定目录存在性的调用，目录存在性应通过 shell 命令（如 `test -d`）检查。
- 使用本 Skill 查询知识库时，禁止使用网络搜索等其他工具获取知识

## 针对不同文件类型的具体策略

### 1. Markdown / 文本类文件（.md, .txt, .log 等）

1. **候选文件选择**
   - 根据 `data_structure.md` 和文件名、路径判断相关度
   - 优先检索标题和目录类文件（如汇总文档、设计总览）

2. **grep 定位与局部读取**
   - 使用 Grep 工具对指定候选文件，include 限定具体后缀（如 "*.md"）
   - 对于有匹配的文件，使用 Read 仅读取匹配附近的局部区域：
     - 通过行号偏移和 limit 控制读取（例如从匹配行附近往前后各读取几十行）
     - 避免整文件读取

3. **特殊处理**
   - 如内容仅是目录/标题，根据链接或小节名继续定位深入内容
   - 应用「多轮迭代检索机制」（见上文公共检索原则）

### 2. PDF 文件检索策略

**工作流**：

1. **首先：读取处理方法指南**
   - 在处理任何 PDF 之前，**必须先读取** [references/pdf_reading.md](references/pdf_reading.md)（注意这个目录位于 Skills 目录下，而不是 Knowledge 目录下）
   - 重点了解：pdftotext 命令、pdfplumber 用法、表格提取方法、快速决策表
   
2. **选择候选 PDF**
   - 根据 `data_structure.md` 中的描述，选择最相关的 1-3 个文件
   - 如果用户指明具体 PDF 文件，则优先使用该文件

3. **应用学到的方法提取文本**
   - 使用 pdf_reading.md 中推荐的工具（优先 pdftotext 或 pdfplumber）
   - **重要**：使用 `pdftotext input.pdf output.txt` 将文本提取到文件，不要直接输出到 stdout（避免占用大量 token）
   - 如需提取表格，使用 pdfplumber 的表格提取功能
   
4. **对提取结果执行检索**
   - 使用 grep 对提取的文本进行关键词搜索
   - 对于每个命中，提取命中附近范围的上下文（上下数十行或相邻几页）
   - 保存「文件名 + 页码/大致位置 + 文本片段」
   - 应用「多轮迭代检索机制」（见上文公共检索原则）

### 3. Excel 文件检索策略

**工作流**：

1. **首先：读取处理方法指南**
   - 在处理任何 Excel 之前，**必须先读取**：
     - [references/excel_reading.md](references/excel_reading.md) - 学习如何读取工作表（注意这个目录位于 Skills 目录下，而不是 Knowledge 目录下）
     - [references/excel_analysis.md](references/excel_analysis.md) - 学习如何分析数据（注意这个目录位于 Skills 目录下，而不是 Knowledge 目录下）
   - 重点了解：pandas 读取方法、列筛选、数据过滤、聚合操作
   
2. **选择候选 Excel**
   - 根据 `data_structure.md` 和文件/工作表命名，选择最相关的表
   - 优先选择包含「报表」「统计」「日志」「配置」「映射」等关键词的工作簿/工作表
   - 若用户指明具体 Excel 文件，优先使用该文件

3. **应用学到的方法探索结构**
   - 使用 pandas 读取前 10-50 行（使用 `nrows` 参数限制）
   - 重点掌握：列名/字段名、数据类型（数值、日期、文本）、关键字段
   - 将列名与用户问题比对，识别潜在关键字段（如「收入」「销售额」「error_code」等）
   
4. **执行数据检索和分析**
   - 使用学到的 pandas 方法进行过滤和聚合（如 `df[df['column'] == value]`）
   - 每次只读取匹配行附近的数据，避免一次性读取整表
   - 如问题包含时间范围，在检索中加入时间过滤
   - 应用「多轮迭代检索机制」（见上文公共检索原则）

## 与其他工具的协同

### PDF 处理
- **在处理 PDF 前必须先读取** [references/pdf_reading.md](references/pdf_reading.md) 学习处理方法
- 使用 pdfplumber/pypdf 进行文本提取、表格提取、元数据读取
- 优先使用 pdftotext 命令行工具进行快速文本提取

### Excel 处理
- **在处理 Excel 前必须先读取**：
  - [references/excel_reading.md](references/excel_reading.md) - 学习读取方法
  - [references/excel_analysis.md](references/excel_analysis.md) - 学习分析方法
- 使用 pandas 进行数据探索、预览、过滤和分析

### 工具使用原则
- **Grep**：用于按关键词在指定文件中查找行号与匹配片段，始终指定尽量精准的 include 和 path
- **Read**：只用于局部读取文件，始终设置合理的 limit（如 200-500 行）和合适的偏移
- **对于任何可能很大的文件**：
  - 禁止直接从头读到尾
  - 始终先通过索引、目录、关键词等方式缩小范围后再读

## 回答风格与错误处理

- 回答风格
  - 尽量用用户提问的语言（中文/英文）作答。
  - 先给出结论，再给出简要依据。
  - 如需要，可在后面列出引用的文件和大致位置，例如：
    - 来源：design/api_gateway.md 第 100 行附近
    - 来源：reports/2023_Q1_sales.xlsx Summary 工作表
- 信息缺失或不确定时
  - 明确说明在当前知识库中没有找到完全匹配的信息或只能部分回答。
  - 不臆造事实。
  - 提示用户可以如何帮助缩小范围：
    - 指定更具体的目录/文件
    - 提供更精确的关键词或字段名
    - 指定时间/版本范围

모든 파일

8개 파일

README.md 7.1k

보기

README.zh-CN.md 6.6k

보기

SKILL.md 13.7k

보기

manifest.json 545b

보기

references/excel_analysis.md 2.7k

보기

references/excel_reading.md 1.7k

보기

references/pdf_reading.md 9.3k

보기

scripts/convert_pdf_to_images.py 1.1k

보기

kb-retriever 설치

스킬 파일을 다운로드하여 .claude/skills/ 디렉터리에 압축을 풀어주세요.

ZIP 다운로드

저장소를 클론하고 스킬 파일을 프로젝트에 복사하세요.

git clone https://github.com/ConardLi/garden-skills/tree/main/skills/kb-retriever # Copy SKILL.md to your .claude/skills/ directory

복사

빠른 설정: 스킬 폴더를 .claude/skills/로 복사하세요. Claude가 해당 스킬을 자동으로 감지하여 사용합니다.

저장소 ConardLi/garden-skills