자산 인벤토리 관리자은(는) 무엇을 하나요?
프로젝트당 하나의 권위 있고 감사 가능한 자산 목록을 유지합니다. 데이터는 프로젝트의 .asset-inventory/ 폴더(자산당 하나의 JSON 파일)와 생성된 Markdown 뷰(기본값 ASSET_LIST.md)에 저장됩니다. Markdown 뷰를 수동으로 편집하지 마십시오: CLI를 통해 레코드를 변경하면 CLI가 Markdown 뷰를 재생성합니다.
CLI
모든 작업은 이 스킬에 포함된 stdlib-only Python 3.9+ 스크립트를 통해 수행됩니다:
python <this-skill-dir>/scripts/asset_inventory.py <command> [options]
아래에서 aim은 해당 명령을 나타냅니다. python이 없거나 Python 3이 아닌 경우 python3, py -3(Windows), uv run --no-project python을 시도하십시오. 프로젝트 내 아무 곳에서나 실행하거나 -C <project>를 전달하십시오. 기계 판독 가능한 출력을 위해 --json을 추가하십시오. 기록에는 작업 에이전트가 기록됩니다: 자동 감지가 잘못된 경우 --agent <name>을 전달하거나 AIM_AGENT를 설정하십시오.
| 작업 | 명령어 |
|---|---|
| 인벤토리 시작 | aim init --profile game|vr|web|software|generic [--git-setup] |
| 자산 등록 | aim add --name "활" --category model --path assets/bow.glb --origin third-party --license CC-BY-4.0 --source-url URL --attribution required --credit "..." |
| 자산 변경 | aim update ID --status final --verification approved --note "이유" |
| 폐기 / 삭제 | aim remove ID --note "X로 대체됨" (레코드는 유지) / --purge |
| 자산 검색 | aim query --category model --status placeholder, --path assets/ui/, --text bow, --format json|csv|ids |
| 단일 레코드 조회 | aim get ID |
| 미등록 파일 검색 | aim scan (--register를 추가하여 needs-triage 레코드 생성) |
| 전체 점검 | aim audit (--strict는 경고를 실패로 처리) |
| Markdown 재생성 | aim render (--check는 CI용) |
| 컨텍스트 (브랜치, 워크트리, 잠금) | aim info |
| 이전 Markdown 테이블 마이그레이션 | aim import-markdown old_list.md |
| Git 충돌 후 | aim resolve, 이후 aim audit |
용어집 (모든 필드는 스키마 참조):
- 상태:
planned,placeholder(작동하지만 프로토타입 품질),integrated,final,retired. - 검증:
unverified,pending,verified(기술적 확인 통과),approved(소유자 승인). 사용자나 검토자가 승인하지 않으면 절대approved로 표시하지 마십시오. - 출처:
original,third-party,procedural,ai-generated,unknown. 타사 및 AI 생성 자산에는 라이선스가 필요합니다.
워크플로우
- 찾기.
aim info를 실행합니다. 인벤토리가 없고 사용자가 원한다면 가장 가까운 프로필(프로필)로aim init을 실행한 후aim scan을 실행하여 기존 항목을 확인합니다. 기존 수동 목록이 있는 경우aim import-markdown을 사용하고imported태그가 붙은 레코드를 검토합니다. - 모든 자산 변경 사항을 동일한 변경 세트에 기록합니다. 자산 파일을 추가, 교체, 수정, 이동 또는 삭제할 때 동일한 커밋에서 해당 레코드를 업데이트합니다: 새 파일은
add, 이동은update --add-path/--remove-path, 타사 파일 편집은update --modifications, 사용하지 않는 파일은remove를 사용합니다. - 출처를 정직하게 기록합니다. 다운로드 시 실제 소스 URL, 작성자, 라이선스 및 필수 크레딧 텍스트를 캡처합니다. 알 수 없는 경우
--origin unknown을 사용하고 그렇게 명시하십시오. 라이선스를 추측하지 마십시오. 라이선스 충돌이 있으면 사용자에게 알립니다. - 상태를 진실되게 유지합니다. 계획됨, 구현됨, 검증됨, 승인됨을 구분합니다. 다음 보류 중인 확인 사항을
--next에 넣습니다. 그러면 목록 상단의 "검토 필요" 섹션에 표시됩니다. - 완료하기 전에 감사합니다.
aim audit를 실행합니다. 오류를 수정하고 남은 경고를 사용자에게 보고합니다. 요약에 목록 경로를 언급하십시오.
공동 작업 규칙 (여러 에이전트, 브랜치, 워크트리)
자세한 내용: 협업.
- 각 Git 워크트리에는 인벤토리의 자체 복사본이 있습니다. 작업 중인 워크트리의 인벤토리를 편집하십시오. 다른 에이전트의 워크트리를 절대 편집하지 마십시오.
- 쓰기 작업은 짧은 잠금(
.asset-inventory/.lock)을 획득하므로 한 폴더를 공유하는 에이전트가 파일을 손상시킬 수 없습니다. 잠금이 보고되면 기다렸다가 다시 시도하십시오.aim info에서 소유자 프로세스가 사라진 경우에만 잠금을 삭제하십시오. - 업데이트 손실을 방지하려면
aim get ID로 읽은 다음aim update ID --expect-revision N을 사용하십시오. 종료 코드 3은 다른 사람이 변경했음을 의미합니다. 다시 읽고 다시 적용하십시오. - 자산당 하나의 파일이므로 병렬 브랜치 간 충돌이 거의 발생하지 않습니다. 복제본당 한 번
aim git-setup을 실행하여 필드 수준 병합 드라이버를 설치하십시오. - 병합, 리베이스 또는 체리픽 후:
aim resolve(레코드에 충돌 마커 또는_conflicts가 있는 경우),aim render,aim audit, 그런 다음 커밋하십시오.ASSET_LIST.md를 수동으로 병합하지 마십시오. 재생성하십시오. - 명시적 ID(예:
M01)는 단일 브랜치에서 괜찮지만 기본 ID(<prefix>-<name-slug>)는 브랜치 간 번호 충돌을 방지합니다.
종료 코드
0 정상 · 1 오류 또는 감사 실패 · 2 잘못된 사용법/알 수 없는 값 · 3 주의가 필요한 개정 또는 병합 충돌.