rogerdigital/vault-inspector

Vault Inspector

Vault Inspector를 Obsidian 볼트 유지보수를 위한 읽기 전용 품질 관문으로 사용하세요. 이 스킬은 끊어진 링크, 고립된 첨부 파일, 빈 노트, 외부 링크, 중복 파일, 프론트매터 유형 불일치, 태그 사용 문제, 대용량 파일을 찾아야 하는 터미널, CI, 에이전트 관리 볼트 워크플로에 적합합니다.

안전 규칙

• CLI를 읽기 전용으로 취급하십시오. 이 스킬의 일부로 볼트 파일을 수정, 이동, 삭제 또는 다시 작성하지 마십시오.
• --fix를 사용 가능한 옵션으로 제시하지 마십시오. CLI는 현재 수정 실행 시 오류와 함께 종료됩니다.
• 고립된 첨부 파일, 중복 파일 후보 또는 대용량 파일을 자동으로 삭제하지 마십시오. 증거를 요약하고 수동 검토를 권장하십시오.
• title, message, generatedAt, durationMs를 안정적인 자동화 식별자로 취급하지 마십시오.
• 자동화에는 안정적인 필드(schemaVersion, toolVersion, summary, scannerId, severity, primaryPath, relatedPaths, evidence, fingerprint, fixAction, isNew, summary.newIssues)를 사용하십시오.
• --progress로 stderr에 스캔 진행 상황을 유지하고, stdout은 기계가 읽을 수 있는 상태로 유지하십시오.

실행 시점

Vault Inspector를 실행하십시오:

• 볼트를 재구성, 게시, 내보내기 또는 보관하기 전에;
• 생성되거나 에이전트가 관리한 노트 변경 후;
• 링크, 태그, 프론트매터 또는 첨부 파일에 대한 대량 편집 전과 후;
• 볼트 또는 생성된 문서 저장소에 회귀 검사가 필요한 CI에서;
• 사용자가 볼트 위생, 끊어진 링크, 고립된 파일, 중복 파일 또는 대용량 파일 분석을 요청할 때.

기본 명령어

볼트 내부에서:

vinspect . --format json

전역 설치 없이 일회성 사용:

npx vault-inspector /path/to/vault --format json

사람이 읽을 수 있는 보고서 작성:

vinspect . --format markdown --output report.md

선택한 검사기 실행:

vinspect . --scanner broken-links,empty-notes,large-files --format json

네트워크 확인이 허용되는 경우에만 선택적 외부 링크 검사기를 실행:

vinspect . --scanner external-links --format json

stdout을 오염시키지 않고 진행 상황 표시:

vinspect . --format json --progress

기준선 작업 흐름

기준선 생성:

vinspect . --format json --output .vault-inspector-baseline.json --fail-on none

새로운 발견에 대해서만 실패:

vinspect . --baseline .vault-inspector-baseline.json --fail-on new --format json

기준선을 사용할 때는 summary.newIssues와 각 이슈의 isNew 필드를 검사하십시오. 기존 알려진 이슈보다 새로운 이슈를 먼저 보고하십시오.

종료 코드

• 0: 스캔 완료 및 구성된 --fail-on 임계값과 일치하지 않음.
• 1: 스캔 완료 및 구성된 --fail-on 임계값과 일치함.
• 2: 잘못된 CLI 사용 또는 스캔 설정 실패.

종료 코드가 2인 경우 CLI 오류를 보고하고 stdout을 성공적인 스캔 결과로 해석하지 마십시오.

결과 해석

다음 순서로 발견 사항의 우선순위를 지정하십시오:

1. error 심각도의 끊어진 링크 및 누락된 첨부 파일 링크.
2. warning 발견 사항: 누락된 제목, 대용량 파일, 확인된 중복 파일, 오래된 고립된 첨부 파일.
3. info 발견 사항: 사용 빈도가 낮은 태그, 건너뛰거나 시간 초과된 외부 검사, 최근 고립된 첨부 파일, 중복 파일 후보.

각 요약에는 다음을 포함하십시오:

• 총 이슈 수;
• 심각도별 개수;
• 실행된 검사기;
• 신뢰도 높은 이슈 우선;
• 수동 검토에 필요한 파일 경로 및 증거;
• 기준선이 있는 경우 새로운 이슈 개수.

확신을 과장하지 마십시오. 고립된 첨부 파일과 중복 파일 후보는 CSS, Canvas, Dataview, 퍼블리싱 파이프라인 또는 외부 도구에서 파일이 참조될 때 오탐(false positive)이 될 수 있습니다.

제안된 에이전트 응답

스캔 결과를 보고할 때 다음 형식을 사용하십시오:

Vault Inspector가 <N>개의 이슈를 발견했습니다: <E>개 오류, <W>개 경고, <I>개 정보.

최우선 발견 사항:
- [<심각도>] <scannerId>: <primaryPath> - <짧은 증거 기반 설명>

참고:
- <기준선/새 이슈 관련 참고 사항>
- <고립/중복 후보에 대한 수동 검토 주의 사항>

스캔이 통과하면 실행된 명령어와 관련 0 개수를 명시하십시오. 볼트가 완벽하다고 주장하지 말고, Vault Inspector가 선택한 검사기와 필터와 일치하는 이슈를 찾지 못했다고 말하십시오.