<div align="center">
AI 프로그래밍 어시스턴트가 작업을 수행하기 전에 도구를 먼저 확인합니다. 로컬에 설치된 복사본을 발견하면, 프로젝트 요구사항에 맞는 버전을 선택하고 검증 가능한 절대 경로만을 반환합니다.
CI
Release
MIT
Windows
간체 중국어 · English · 빠른 시작 · 참고 매뉴얼 · agent 연동 · 업데이트 기록
</div>
toolkit-map 的工作方式：项目要求 + 本机副本 → toolkit-map find → 可验证的绝对路径
해결하는 문제점
AI 프로그래밍 어시스턴트가 node, python, git 등을 실행할 때 일반적으로 PATH를 직접 따릅니다. PATH에는 Node 16이 있는데, 프로젝트는 Node 22를 요구합니다. 기계에는 여러 복사본이 설치되어 있어 agent가 어떤 것을 선택해야 할지 모릅니다. 또한, node --version은 단순히 PATH 상에서 어느 버전으로 해석되었는지만 알려줄 뿐, 이 프로젝트에 실제로 필요한 버전을 알려주지는 않습니다.
toolkit-map은 호출 전에 세 가지를 답변합니다:
- 프로젝트가 요구하는 버전은 무엇인가?
mise.toml, .tool-versions, .nvmrc, Node engines 등 일반적인 선언 파일을 읽어옵니다.
- 로컬에 검증된 복사본이 어떤 것이 있는가? PATH, 통합 저장소(unified repository), mise 설치 디렉터리 및 수동 등록 위치를 스캔합니다.
- 이번에는 어느 절대 경로를 사용해야 하는가?
path, version, verification, 그리고 requirement를 반환합니다.
조회는 엄격히 읽기 전용(read-only)이며, 설치하거나 PATH를 변경하지 않습니다. 버전 추측도 하지 않습니다. 지도 유지보수(scan / update / add)는 별도의 명시적 동작이므로, 실행 전에 사용자 승인이 필요합니다. 요구사항을 충족하는 복사본이 없을 경우 version_mismatch를 반환하며, 다운그레이드하지 않습니다. 선언된 요구사항을 해석할 수 없는 경우 requirement_unsupported를 반환하고, 이는 버전 관리자나 사람이 처리해야 합니다. 다른 도구와의 차이점 및 반환 예시는 참고 매뉴얼에서 확인할 수 있습니다.
빠른 시작
요구 사항: Windows + Windows PowerShell 5.1 또는 PowerShell 7 + Git. MCP에 연동하려면 Node.js 18+가 추가로 필요합니다. 지도 자체는 Node.js에 의존하지 않습니다.
다운로드, 프로젝트 연동 및 프로젝트 레벨 MCP 설정 쓰기를 한 번에 완료하는 방법:
$project = (Get-Location).Path
$d = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
git clone --branch v2.0.0 --depth 1 https://github.com/haxsd/toolkit-map $d
...
종료 코드를 확인하세요: 0은 모든 것이 완료되었음을 의미합니다. 2는 부분적으로 완료되었음을 의미합니다 (규칙이 연동되었으나, MCP가 작성되지 않았을 수 있습니다. 예: Node 18+가 없거나 시작 검사에 실패한 경우). 1은 프로젝트 연동에 실패했음을 의미합니다. -ExecutionPolicy Bypass는 해당 자식 프로세스에만 작용하며, 사용자 또는 기계의 정책을 변경하지 않습니다. 조직 정책 거부 시에는 조직 절차를 따라 신청해야 하며, 레지스트리나 그룹 정책을 임의로 수정해서는 안 됩니다.
수동으로 동일한 단계를 완료하는 방법:
$project = (Get-Location).Path
$installDir = Join-Path $env:USERPROFILE 'Projects\toolkit-map'
git clone --branch v2.0.0 --depth 1 https://github.com/haxsd/toolkit-map $installDir
...
이미 설치된 경우 업그레이드 단계를 참조하세요. Git이 없거나 ZIP 파일을 다운로드하고 싶은 경우 ZIP 연동을 따르세요. MCP 클라이언트는 지도 도구를 직접 호출할 수 있으며, 설정, 프로토콜 및 승인 기준은 MCP 연동에서 확인할 수 있습니다. 규칙 위치, 템플릿 및 적용 승인 기준은 agent 연동에서 확인하세요.
보안 경계
- 읽기 전용 조회(查询只读):
status / find / doctor는 도구를 설치하거나 PATH를 변경하지 않으며, 설정을 작성하지 않습니다. find는 새로운 후보를 실행하거나 지도를 작성하지 않습니다.
- 유지보수 및 설치는 명시적 동작:
scan / update / add는 지도를 작성하고 로컬의 후보 프로그램을 탐지할 수 있습니다. install은 별도로 호출해야 하며, 먼저 -WhatIf를 사용하는 것이 좋습니다. MCP 유지보수는 기본적으로 미리보기만 수행하며, confirm:true는 요청을 실행하는 것일 뿐이며 여전히 사용자 승인이 필요합니다.
- 기존 환경 변경 없음: 기존 도구를 마이그레이션하거나 PATH를 변경하지 않으며, 전역 실행 정책이나 자격 증명(credentials)도 건드리지 않습니다.
- 팀 저장소: 규칙 접근 및 MCP 설정에는 로컬 절대 경로가 포함되므로 공유 저장소에 커밋하지 마십시오. 각 구성원이 로컬에서 생성해야 합니다.
- 로컬 지도, 도구, 캐시 및 자격 증명은 배포 패키지에 포함되지 않습니다. 전체 경계는 보안 정책을 참조하십시오.
문서
참고 매뉴얼 · 규약 동결 · MCP 통합 · 2분 데모 · 에이전트 통합 · 플랫폼 설명 · 저장소 및 대형 도구 설치 · 문제 해결 · 취소 및 제거 · 개발 및 기여 · 보안 정책 · 업데이트 기록
자주 묻는 질문
- 프로젝트 선언이 없을 때 최신 버전을 선택하나요? 그렇지 않습니다. 순서는
-Version > 프로젝트 선언 > 상위 디렉터리/전역 선언 > 시스템 기본값입니다. PATH에 Node 16이 있으면 16을 반환하며, 특정 버전이 필요하면 선언하거나 -Version을 전달해야 합니다.
- 도구를 옮기거나 PATH를 변경하나요? 그렇지 않습니다. 기존 사본은 제자리에 남아 있으며,
install은 별도의 명시적 작업입니다.
- 반드시 mise를 사용해야 하나요? 그럴 필요 없습니다. mise가 없어도 발견하고 등록하며 조회할 수 있으며, 완전한 관리자 환경이 필요할 때만 사용합니다.
- 취소가 가능한가요? 접근 규칙, MCP 설정 및 스킬 연결은 제거할 수 있지만, 기존 도구는 유지됩니다. 취소 및 제거를 참조하십시오.
기여 및 라이선스
Issue와 PR을 환영합니다: 먼저 개발 및 기여를 확인하고, 버그 또는 기능 제안은 Issue 템플릿을 사용해 주십시오. 재현 단계와 doctor -Bundle -Json 출력을 첨부하는 것이 좋습니다(붙여넣기 전에 경로에서 사용자 이름은 가립니다).
소스 코드, 프로토콜, 일반 예제 및 레시피는 MIT 라이선스를 사용합니다.
