Figma 드래프트 정리 도구 (자율, 내부 API)

이 스킬은 Figma 팀의 드래프트 폴더를 비우기 위해 모든 파일을 분류하고 올바른 번호가 매겨진 카테고리 프로젝트로 정리하는 검증된 안정적인 방법을 구현합니다. Chrome의 javascript_tool을 통해 Figma 내부 API를 사용하여 전체 작업을 수행합니다. 파일 카드를 클릭하거나, 이동 대화 상자를 열거나, 이름 필드를 수정할 필요가 없습니다. 마우스 기반 접근 방식은 느리고 불안정했습니다. 내부 API는 이동과 이름 변경을 하나의 요청으로 처리하며 멈추지 않습니다.

좋은 결과를 내는 핵심 아이디어: 파일의 내용이 진실의 근원이며 이전 이름은 절대 신뢰하지 않습니다. 오래된 드래프트 이름은 종종 잘못되었거나, 일반적이거나, 복사된 경우가 많습니다. 따라서 각 파일에 대해 프레임 내부의 실제 텍스트를 읽고, 그로부터 이름과 카테고리를 결정한 다음 이름을 변경하고 이동합니다.

작동 모드

기본값은 완전 자율 모드입니다: 드래프트 폴더를 순서대로 한 파일씩 처리하여, 각 파일의 이름을 즉시 변경하고 이동하며 파일 간 승인을 위해 멈추지 않습니다. 파일당 간단한 결과를 보고합니다. 내용에서 결정할 수 없는 진정한 모호함(드문 경우)이 있거나 API 호출이 반복적으로 실패하는 경우에만 사용자에게 질문하기 위해 멈춥니다.

사용자가 미리보기/승인 단계를 명시적으로 요청하는 경우, 비교 표(현재 이름 → 제안된 이름 + 카테고리)를 표시하고 기다립니다. 그러나 이것은 예외이며 기본값이 아닙니다.

5단계 (파일당 — 이 단계를 재사용하고 새로 만들지 마세요)

각 드래프트 파일에 대해 정확히 다음 5단계를 순서대로 수행합니다:

파일 키 캡처 — 드래프트 목록에서 (다시 가져온 목록의 인덱스 0).
실제 내용 검사 — REST API를 통해 프레임의 실제 텍스트를 읽습니다. 이전 이름을 신뢰하지 마세요.
새 이름 + 카테고리 결정 — 둘 다 내용에서 파생됩니다. 이름 패턴: <Subject> - <Key Features> Dashboard (디자인의 언어와 관계없이 영어).
대상 프로젝트 확인 — 일치하는 번호가 매겨진 카테고리 프로젝트를 찾습니다. 없으면 새로 만듭니다(시퀀스의 다음 번호).
이름 변경 + 이동 — 두 가지를 모두 수행하는 하나의 내부 API PUT. HTTP 200을 기대합니다.

그런 다음 드래프트 목록을 다시 가져오고 드래프트 폴더가 빌 때까지 1단계부터 반복합니다. 파일이 떠나면서 목록이 재정렬되므로 매 반복마다 다시 가져와야 합니다. 항상 인덱스 0을 가져옵니다.

설정 (세션당 한 번)

Chrome 탭이 팀의 드래프트 페이지(예: https://www.figma.com/files/team/{TEAM_ID}/drafts)에 열려 있고 tabId를 알고 있는지 확인합니다. 사용자는 해당 Chrome 프로필에서 Figma에 로그인되어 있어야 합니다.
사용자의 값을 수집합니다. 이미 알려지지 않은 경우 한 번만 물어보세요:
- FIGMA_TOKEN — 읽기 전용 파일 액세스 권한이 있는 Figma 개인 액세스 토큰 (Figma → 설정 → 보안 → 개인 액세스 토큰 → 범위 "파일 내용: 읽기 전용"). 파일 내용을 읽는 데만 사용됩니다.
- TEAM_ID — 드래프트 페이지 URL에서 /team/ 뒤에 오는 숫자입니다.
scripts/helpers.js의 CONFIG 블록에 넣거나 (붙여넣기 전에 window.__FIGMA_TOKEN 및 window.__TEAM_ID를 설정하세요). 토큰을 공유하거나 커밋될 파일에 절대 쓰지 마세요.
도우미 블록을 한 번 붙여넣습니다 (scripts/helpers.js 참조). 이 블록은 window에 findDraftsFolder, inspect, moveFile, loadFolders, loadDrafts를 정의합니다. 모든 JS는 Figma 탭에서 Chrome의 javascript_tool을 통해 실행합니다.
드래프트 폴더 ID를 찾습니다(드래프트 페이지가 로드 완료되어야 함):
```
window.findDraftsFolder()   // → "drafts=<id>"
```
NOT_FOUND를 반환하면 드래프트 페이지를 다시 로드하고, 기다린 후 도우미를 다시 붙여넣고 다시 시도합니다.
이름 변경/이동이 카테고리 프로젝트를 찾을 수 있도록 로드합니다:
```
window.loadFolders()   // window.__folders = { "<name>": id, ... }을 채웁니다.
```

도우미는 일반적인 인앱(SPA) 탐색에서 유지되지만, 프로젝트 생성 페이지는 하드 리로드를 수행하여 도우미를 지웁니다. 새 프로젝트를 만든 후에는 도우미 블록을 다시 붙여넣고 계속하기 전에 loadFolders()를 다시 실행하세요. 리로드 후 복원할 수 있도록 토큰, 팀 ID, 드래프트 폴더 ID를 메모에 보관하세요.

카테고리 프로젝트가 없는 팀에서 첫 실행

팀에 번호가 매겨진 프로젝트가 아직 없으면 첫 번째 파일들이 각각 카테고리(01 - ..., 02 - ...)를 만듭니다. 이는 예상된 동작입니다. references/categories.md에는 UI/대시보드 작업에 잘 맞는 카테고리 시작 목록이 포함되어 있습니다. 이름 지정 가이드로 사용하고 이미 존재해야 하는 목록으로 사용하지 마세요.

라이브 카테고리 목록은 loadFolders() 이후의 window.__folders입니다. references/categories.md는 시작 목록이자 이름 지정 가이드입니다. 새 카테고리를 일관되게 유지하고 다음 사용 가능한 번호를 찾으려면 읽어보세요.

1-2단계 — 다음 파일을 가져와 내용 검사

드래프트 목록을 가져오고 인덱스 0을 취한 후 내용 검사를 실행합니다:

window.loadDrafts().then(n=>{
  window.__last="CLEARED"; window.__ir="";
  const d=window.__drafts[0]; window.__cur=d; window.__cn=d?d.name:null;
  if(d){ window.inspect(d.key).then(r=>window.__ir=r).catch(e=>window.__ir="ERR:"+e); }
  return "n="+n+(d?(" first="+String(d.name).replace(/[^A-Za-z0-9 ]/g,"")+" key="+d.key):" EMPTY");
})

n=0 EMPTY는 드래프트 폴더가 비었음을 의미합니다 — 작업 완료입니다.

window.inspect는 각 페이지의 처음 몇 프레임을 살펴보고 짧은 텍스트 문자열을 수집합니다. 실행 후 약 8초를 기다린 다음 정리된 단어 목록을 읽습니다(이 필터는 템플릿 상용구를 제거합니다 — 아래 무시 목록 참조):

new Promise(res=>setTimeout(()=>res(
  [...new Set((window.__last.match(/[A-Za-z]{4,}/g)||[]))]
    .filter(w=>!/http|www|figma|preview|envato|MirNFT|Explore|creators|rankings|Auctions|Solid|Melt|Flare|Mare|Fusion|Soul/i.test(w))
    .slice(0,40).join(" ")
), 8000))

지연을 위해 별도의 대기 도구 대신 위의 JS setTimeout 프로미스를 사용하세요. 모든 것을 브라우저 탭 내에서 유지합니다.

결과가 드물거나 상용구가 지배적인 경우, 더 깊은 전체 문서 탐색(깊이 12)으로 확장하세요 — scripts/deep_walk.js 참조. 내용이 분류하기에 너무 얇으면 최후의 수단으로 파일의 이전 이름을 사용하세요.

분류 시 무시할 상용구

많은 드래프트는 장식용 썸네일을 공유하는 구매 템플릿입니다. 다음이 아닌 메인 이름이 지정된 대시보드 프레임으로 분류하세요:

NFT 미리보기 썸네일 (MirNFT / preview envato / Explore / Auctions / CryptoPunks / WonderPals / Azuki / Doodles / Decentraland / Sandbox 등)
음악 미리보기 썸네일, FastEat 음식 미리보기
비의료 파일 내에 나타나는 일반 의료 템플릿 사이드바 (Message / Test / Payment / Appointment / Settings / Help / Medicine / Order / "Welcome Alexa June")

3단계 — 내용에서 이름 + 카테고리 결정

이름을 영어로 <Subject> - <Key Features> Dashboard 형식으로 만듭니다. 실제 실행 예시:

암호화폐 지갑 + 거래소 + 분석 → Crypto Trading Platform - Wallet & Exchange Dashboard → 카테고리 07 - Crypto
온라인 강좌, 학생, 강사, 분석 → Online Courses - Students & Performance Dashboard → 05 - LMS
메시지/그룹이 있는 채팅 앱 → Chat App - Messages & Groups Dashboard → 36 - Chat & Messaging
칼로리/운동 추적기 → Health Tracker - Calories & Training Dashboard → 14 - Medical & Health

내용 신호를 references/categories.md의 번호가 매겨진 프로젝트 목록과 일치시켜 카테고리를 선택합니다.

4단계 — 대상 프로젝트 확인 (또는 생성)

window.__folders에서 카테고리 이름을 찾습니다. 대부분의 폴더 키는 뒤에 Dashboard가 붙습니다(예: 02 - Finance & Insurance Dashboard). 일부는 그렇지 않습니다(04 - UI Components, 37 - Agency & Portfolio Website, 47 - Pitch Deck & Presentation, 48 - UX Case Study). 정확한 키를 사용하세요.

일치하는 카테고리 프로젝트가 없으면 새로 만듭니다 (예상되고 허용된 동작입니다 — 멈추지 마세요). 내부 API는 프로젝트를 만들 수 없으므로 Figma UI를 사용하세요:

https://www.figma.com/files/team/{TEAM_ID}/all-projects로 이동합니다.
+ 프로젝트 (오른쪽 상단)를 클릭합니다. 좌표는 화면에 따라 다릅니다 — 스크린샷을 찍거나 find를 사용하여 각 컨트롤을 찾으세요.
기다렸다가 이름 필드를 클릭하고 새 번호 이름을 입력합니다 (references/categories.md의 다음 사용 가능한 번호, 나머지와 같은 스타일, 예: 49 - Crowdfunding & Fundraising Dashboard).
계속을 클릭합니다.
2단계 "사람 추가"에서 사람을 추가하지 않고 프로젝트 만들기를 클릭합니다 — 공유/권한을 절대 변경하지 마세요.
페이지가 새 프로젝트로 하드 리로드됩니다 → 도우미를 다시 붙여넣고 loadFolders()를 다시 실행합니다.

그런 다음 이동을 진행합니다.

5단계 — 한 번의 호출로 이름 변경 + 이동

window.moveFile(window.__cur.key, "<CATEGORY FOLDER KEY>", "<NEW NAME>").then(r=>"mv="+r)

mv=S200은 성공을 의미합니다(이름 변경 및 이동이 함께 완료됨). 다른 결과: 쿠키/CSRF를 다시 읽고, 폴더 키가 window.__folders에 존재하는지 확인한 후 재시도합니다.

1단계로 돌아갑니다.

엄격한 규칙 (사용자를 보호합니다 — 반드시 따르세요)

내용이 기준이며, 이전 이름은 절대 아닙니다. 이름을 지정하기 전에 항상 검사하세요.
기본적으로 자율 모드 — 파일 간 권한 프롬프트 없음. 결과만 보고합니다.
영어 이름, 패턴 <Subject> - <Key Features> Dashboard.
카테고리가 없으면 만들고, 시퀀스의 다음 번호를 사용합니다. 번호를 재사용하지 마세요.
절대 아무것도 삭제하지 마세요 — 파일을 휴지통에 버리거나 삭제로 드래프트를 비우지 않습니다. 파일만 이동합니다.
공유 또는 권한을 절대 변경하지 마세요 — 프로젝트를 만들 때 사람을 추가하지 않고 "프로젝트 만들기"를 클릭하세요.
한 번에 하나의 파일, 항상 다시 가져와서 인덱스 0을 취합니다(목록이 재정렬됨).
프로젝트 생성 하드 리로드 후 도우미를 다시 붙여넣으세요.
모든 Figma API 호출에 Chrome JS를 사용하세요 — bash/WebFetch를 사용하지 마세요(프록시에 의해 차단됨).

작동하지 않는 것 (시간 낭비하지 마세요)

PUT /v1/files/{key} (공용 REST) → 404. 내부 PUT /api/files/{key} (moveFile 내)를 사용하세요.
공용 REST에는 드래프트 목록 엔드포인트가 없음 → 내부 /api/folders/{id}/paginated_files (loadDrafts 내)를 사용하세요.
API를 통한 프로젝트 생성 → 지원되지 않음. 위의 UI 흐름을 사용하세요.
별도의 대기 도구 → 여기서는 신뢰할 수 없음. JS setTimeout 프로미스를 사용하세요.
22자 파일 키를 단일 원시 문자열로 읽으면 base64로 차단될 수 있음 — 도우미는 이미 키를 안전하게 반환합니다.

참조 파일

references/categories.md — 시작 번호가 매겨진 카테고리 목록 + Dashboard 접미사가 없는 키, 그리고 다음 사용 가능한 번호를 찾는 방법.
scripts/helpers.js — 세션당 한 번 붙여넣을 도우미 블록 (findDraftsFolder / inspect / moveFile / loadFolders / loadDrafts), CONFIG 블록 및 CSRF 처리 포함.
scripts/deep_walk.js — 희박하거나 상용구가 많은 파일을 위한 깊이 12 전체 문서 텍스트 탐색.

내부 API에 대한 참고 사항

이름 변경 + 이동 및 드래프트 목록은 문서화된 공용 REST API가 아닌 Figma의 내부 웹 API(Figma 웹 앱이 호출하는 동일한 엔드포인트)를 사용합니다. 이는 문서화되지 않았으며 예고 없이 변경될 수 있습니다. 이전에 작동하던 호출이 실패하기 시작하면 엔드포인트가 변경되었을 가능성이 높습니다. 이 스킬은 사용자의 재량에 따라 Figma의 이용 약관에 따라 사용하십시오.

Figma 드래프트 정리 도구