ui-gen-record

ui-gen-record은(는) 무엇을 하나요?

"UI 페이지 생성 요청"의 메타 정보(비용, 모델, 수정 횟수, 산출물)를 하나의 Feishu 다차원 테이블에 보관합니다.

트리거 시나리오

핵심: .config.json은 항상 "현재 활성화된 테이블"을 가리킵니다. "새로 만들기 / 링크 바인딩"은 이 포인터만 변경할 뿐, 기존 테이블의 데이터에는 영향을 주지 않습니다.

시나리오	사용자 표현	동작
최초 + "정리"만 말함	"테이블에 정리해줘 / 다차원 테이블에 보관해줘 / 이 요청을 기록해줘"	bootstrap.sh 실행하여 새 테이블 생성 후 append
최초 + Feishu 테이블 링크 제공	"이 테이블에 정리해줘 https://xxx.feishu.cn/base/..."	link.sh <url> 실행하여 기존 테이블 바인딩 후 append
이미 설정됨 + "정리"만 말함	"테이블에 정리해줘"	.config.json이 가리키는 현재 테이블에 바로 append
이미 설정됨 + "새로 만들기"	"새 테이블 만들어줘 / 다시 새로 만들고 싶어"	bootstrap.sh --force 실행하여 새로 만들고 포인터 전환
이미 설정됨 + 새 링크 제공	"이 테이블로 바꿔줘 https://..."	link.sh --force <url> 실행하여 새 테이블로 전환

Feishu Base URL이 명시적으로 포함된 경우에만 바인딩 분기로 동작합니다. 그 외에는 기본적으로 새로 만들기 또는 바로 append를 수행합니다.

의존성

• lark-cli (lark-cli auth login 완료)
• 실행 중인 사용자가 Feishu에 계정이 있고, lark-cli auth list로 open_id를 확인할 수 있어야 함

테이블 생성 / 바인딩: .config.json 초기화

다음 두 가지 방법으로 스킬을 Feishu 다차원 테이블에 연결할 수 있습니다. 둘 중 하나를 선택하세요:

방법 A: 새 테이블 만들기 (처음 사용하는 사용자에게 권장)

bash ~/.cursor/skills/ui-gen-record/scripts/bootstrap.sh
# 이미 .config.json이 있을 때 강제로 새로 만들고 포인터 덮어쓰기:
bash ~/.cursor/skills/ui-gen-record/scripts/bootstrap.sh --force

방법 B: 기존 테이블에 바인딩

사용자가 Feishu Base 링크(예: https://xxx.feishu.cn/base/<base_token>?table=<table_id>)를 제공한 경우:

bash ~/.cursor/skills/ui-gen-record/scripts/link.sh <base_url>
# 이미 .config.json이 있을 때 새 링크로 전환:
bash ~/.cursor/skills/ui-gen-record/scripts/link.sh --force <base_url>

link.sh는 다음을 수행합니다:

1. URL에서 base_token (그리고 선택적으로 table_id / view_id)을 추출
2. lark-cli를 통해 필드 목록을 스캔하고, 필드 이름으로 모든 field_ids를 역조회
3. 10개 필수 필드("요구사항명 / 요구사항일자 / 미리보기링크 / 디자인시안링크 / 사용모델 / 파일 / 수정횟수 / 토큰소비 / 달러비용 / 월")가 모두 있는지 검증; 하나라도 없으면 오류와 함께 종료
4. .config.json에 기록: 이후 append.sh는 별도 링크 제공 없이 자동으로 이 테이블에 레코드를 추가

주의: link.sh가 성공적으로 바인딩되려면 대상 테이블의 필드 이름이 이 스킬이 정의한 것과 완전히 일치해야 합니다 (타입도 일치해야 함, 특히 토큰소비=number 천단위 구분, 달러비용=number USD 통화, 월=formula). 가장 안전한 방법은 이 테이블 역시 이 스킬의 bootstrap.sh로 생성하는 것입니다.

bootstrap.sh가 구체적으로 하는 일:

1. lark-cli auth list로 현재 사용자의 open_id를 가져옴
2. 봇(bot)的身份으로 Base를 생성, 그 안의 테이블은 UI 페이지 생성 기록
3. 표준 필드 + 3개의 보조 수식 필드 생성 (아래 표 참조)
4. 뷰는 월 기준 내림차순 그룹화
5. 대시보드 UI 생성 실시간 통계 생성 및 6개 블록 채우기 (아래 참조)
6. 현재 사용자를 full_access로 추가한 후, 소유자를 해당 사용자로 이전
7. base_token / table_id / view_id / dashboard_id / field_ids / owner_open_id를 .config.json에 기록
8. stdout 마지막에 일회성 수동 미세 조정 2단계를 echo ("월" 열 숨기기, 차트 색상 설정) – 이는 Open API가 지원하지 않으므로 사용자가 브라우저에서 직접 클릭해야 함

생성된 Base URL은 stdout에 echo되므로 사용자에게 알려줘야 합니다.

테이블 구조

필드	유형	설명
요구사항명	text	페이지 이름 또는 요구사항 간단 설명
요구사항일자	datetime	YYYY-MM-DD HH:mm:ss, 기본값은 "현재 시간"
미리보기링크	text (url)	로컬 미리보기 주소, 예: http://localhost:5173/xxx
디자인시안링크	text (url)	Figma / Motiff / Pencil 링크
사용모델	select (색상 태그 포함)	옵션: Claude Opus 4.7(보라) / Claude Sonnet 4.6(파랑) / GPT-5.4(초록) / Gemini 3 Pro(주황) / Gemini 3.1 Pro(빨강), 확장 가능
파일	attachment	.tsx 소스코드 + 내보낸 .zip (여러 개 가능)
수정횟수	text	사용자가 요청한 모든 작은 수정 사항 (중복 포함), 왼쪽 정렬
토큰소비	number(plain)	precision=0, thousands_separator=true, 프론트 표시 1,000,000; 대시보드는 SUM
달러비용	number(currency)	currency_code=USD, precision=2, 프론트 표시 $25.00; 대시보드는 SUM
월	formula(text)	TEXT([요구사항일자], "YYYY-MM"): 뷰 그룹화에 사용. Bitable API는 datetime 그룹화 기본값이 일 단위이므로, 월별로 분류하려면 이 텍스트 필드가 필요

append.sh의 외부 파라미터는 호환성 유지: 여전히 --token-usage "1,000,000" 및 --usd-cost "$25.00"를 전달 가능하며, 스크립트 내부에서 쉼표/달러 기호를 제거한 후 number로 토큰소비 / 달러비용에 기록합니다.

기본 뷰는 월 기준 내림차순 그룹화 (2026-05 / 2026-04 각각 그룹). 어떤 열도 숨길 필요 없습니다.

대시보드

bootstrap은 UI 생성 실시간 통계라는 대시보드를 생성하며, 6개의 블록을 포함합니다:

전체 통계

• 가장 많이 사용된 모델 (원형 차트): 사용모델 필드 기준 카운트, 수량 내림차순
• 토큰 총 소비 / 달러 총 비용 (지표 카드): SUM(토큰소비) / SUM(달러비용)

월별 통계

• 월별 가장 많이 사용된 모델 (누적 막대 차트): x=월 색상=사용모델 y=count_all
• 월별 토큰 총 소비 (막대 차트): x=월 y=SUM(토큰소비)
• 월별 달러 총 비용 (막대 차트): x=월 y=SUM(달러비용)

append.sh로 레코드를 추가할 때마다 대시보드를 새로고침하면 새 데이터를 확인할 수 있습니다.

차트 색상 미세 조정 (일회성 수동 작업)

Bitable Open API는 차트 시리즈 색상 설정을 노출하지 않습니다. 차트의 모델 색상을 테이블 select 색상 태그와 일치시키려면 사용자가 브라우저에서 수동으로 한 번 조정해야 합니다 (조정 후 영구 저장). bootstrap 종료 시 이 대응표가 echo됩니다:

모델	색상 계열	근사 hex
Claude Opus 4.7	보라	#B66CFF
Claude Sonnet 4.6	파랑	#5B9FFF
GPT-5.4	초록	#67D474
Gemini 3 Pro	주황	#FF9944
Gemini 3.1 Pro	빨강	#FF6B6B

작업 경로: 차트 우측 상단 편집 → 우측 스타일 → 차트 색상 → 분류별 설정 → 하나씩 색상 지정 → 저장. "가장 많이 사용된 모델"과 "월별 가장 많이 사용된 모델" 이렇게 모델 차원이 포함된 두 차트만 조정하면 됩니다.

후속 사용: 레코드 한 건 추가

사용자가 "테이블에 정리해줘" 등의 명령을 내리면:

1단계: 데이터 수집

현재 대화 컨텍스트에서 추론하거나 사용자에게 물어서 다음 정보를 확보; 명확하지 않은 항목은 빈 문자열 "" 허용:

• REQ_NAME: 요구사항명 (필수, 보통 페이지 경로 또는 한글 페이지명)
• REQ_DATE: 요구사항일자 (기본값: 현재 시간 $(date +'%Y-%m-%d %H:%M:%S'); 과거 파일 보관 시 stat -f '%Sm' 사용)
• PREVIEW_URL: 미리보기 링크 (보통 http://localhost:5173/<slug>)
• DESIGN_URL: 디자인 시안 링크 (Figma / Motiff / Pencil)
• MODEL: 사용 모델 (반드시 select 옵션에 포함되어야 함. 없으면 먼저 lark-cli base +field-update로 옵션 확장)
• MOD_COUNT: 수정 횟수 (정수 문자열)
• TOKEN_USAGE: 토큰 소비 (천단위 구분 문자열, 예: 1,000,000)
• USD_COST: 달러 비용 ($로 시작하는 문자열, 예: $25.00)
• ATTACHMENT_PATHS: 로컬 첨부파일 절대 경로 배열

1.5단계: 첨부파일 자동 수집

첨부파일은 두 부분으로 구성되며, agent가 사용자에게 묻지 않고 다음 고정 절차에 따라 처리합니다:

1) 소스코드 (필수 전송)

사용자가 이미 가지고 있는 페이지 소스코드. 가장 흔한 경우는 .tsx이며, .html 또는 이번 산출물을 대표할 수 있는 모든 파일 가능. 경로는 REQ_NAME에서 추론하거나 사용자에게 직접 물어봅니다.

2) 내보내기 zip (선택 사항, 있으면 포함, 없으면 건너뜀)

이 프로젝트의 dev 서버에는 POST /__api/export-html 인터페이스가 내장되어 있습니다 (내비게이션 패널의 "내보내기" 버튼도 같은 인터페이스를 호출). 스킬은 자동 helper를 제공합니다:

ZIP_PATH="$(bash ~/.cursor/skills/ui-gen-record/scripts/try-export.sh "<pageName>")"
# 설명:
# - pageName = src/pages/ 아래 확장자를 뺀 상대 경로, 예: "转介绍周任务-最终版" 또는 "landing/index"
# - 성공 시: ZIP_PATH는 /tmp/<basename>.zip
# - 실패 시 (dev 서버 미실행 / 인터페이스 404 / 페이지명 없음 / 비 zip 응답): ZIP_PATH는 빈 문자열
# - 어떤 경우든 exit 0으로 종료되어 agent 흐름을 방해하지 않음

그런 다음 결과에 따라 --attachment 파라미터를 조합합니다:

ATTACH_ARGS=(--attachment "/abs/path/to/source.tsx")
if [[ -n "$ZIP_PATH" ]]; then
  ATTACH_ARGS+=(--attachment "$ZIP_PATH")
fi
bash ~/.cursor/skills/ui-gen-record/scripts/append.sh ... "${ATTACH_ARGS[@]}"

원칙: 내부 동료 (dev 서버 실행 중)는 자동으로 zip이 포함됩니다; 외부 사용자 (dev 서버가 없거나 이 프로젝트가 아닌 경우)는 zip 없이 소스코드와 사용자가 이미 가지고 있는 파일만 첨부됩니다. 어떤 상황에서도 사용자에게 zip 처리 방법을 확인하지 마십시오.

2단계: append 스크립트 호출

bash ~/.cursor/skills/ui-gen-record/scripts/append.sh \
  --req-name "<요구사항/페이지명>" \
  --req-date "2026-01-01 12:00:00" \
  --preview-url "http://localhost:5173/<페이지 경로>" \
  --design-url "https://<디자인 시안 링크>" \
  --model "Claude Opus 4.7" \
  --mod-count "10" \
  --token-usage "500,000" \
  --usd-cost "\$12.50" \
  --attachment "/absolute/path/to/export.zip" \
  --attachment "/absolute/path/to/source.tsx"

스크립트는 새 레코드 id와 Base URL을 반환합니다. Base URL을 사용자에게 알려주세요.

추정 규칙 (필수, 비워둘 수 없음)

Agent는 MOD_COUNT / TOKEN_USAGE / USD_COST 수집 시 다음 기준을 따릅니다. transcript가 없어도 반드시 추정값을 제공해야 하며, 이 세 필드는 절대 비워둘 수 없습니다:

• 수정 횟수: 이번 대화에서 사용자가 제시한 각각 독립적으로 실행 가능한 작은 요구사항의 개수, 중복 포함. 초기 "페이지 생성"도 1로 계산.
  • 과거 파일을 보관하는 경우 (transcript를 볼 수 없음), 최소 1 입력
• 토큰 소비 (천단위 구분 문자열, 예: 160,000):
  • 현재 세션이 보이는 경우: "세션 문자 수 + 도구 왕복 + 대용량 파일 읽기/쓰기 횟수"로 추정
  • 과거 파일만 보관하는 경우: 생성된 파일 크기로 역추정. 경험치: 1KB 소스코드 ≈ 15K 총 토큰 (Cursor의 기본 프로젝트 컨텍스트 포함)
  • 중국어 ≈ 1.3 tokens/char; Opus 세션은 일반적으로 50만–300만 토큰 범위
• 달러 비용 ($ 접두사 포함, 예: $0.42): 모델의 현재 공식 가격으로 추정
  • 공식: cost = input_tokens × input_rate + output_tokens × output_rate
  • 일반적인 비율: input : output ≈ 15 : 1 (Cursor agent 세션 기준)

모델 가격표 (2026년 참고값)

모델	Input ($/M)	Output ($/M)
Claude Opus 4.7	15	75
Claude Sonnet 4.6	3	15
GPT-5.4	10	30
Gemini 3 Pro / 3.1 Pro	2	12

추정값은 오차를 허용합니다. 사용자가 정확한 청구서를 받은 후 테이블에서 직접 수동으로 덮어쓸 수 있습니다.

오류 처리

• config.json이 존재하지 않음
  • 사용자가 링크를 제공하지 않음 → bootstrap.sh 실행하여 새로 만들기
  • 사용자가 링크를 제공함 → link.sh <url> 실행하여 바인딩
• link.sh가 "해당 테이블에 필수 필드가 없습니다" 오류 → 대상 테이블이 이 스킬로 생성된 것이 아니어서 스키마가 맞지 않음. 사용자에게 필드를 직접 추가하거나 bootstrap.sh로 새 규격 테이블을 만들도록 안내.
• base_token invalid → 사용자가 테이블을 삭제했거나 권한이 없을 수 있음. 다시 bootstrap 또는 다른 테이블에 link하도록 안내.
• OpenAPIUpdateField limited (속도 제한) → sleep 2 후 재시도.
• 첨부파일을 찾을 수 없음 → 경로가 존재하는지 확인; ~/Downloads에 URL 인코딩된 파일인 경우 먼저 cp로 /tmp에 복사한 후 전송 (lark-cli는 상대 경로 요구).
• 모델이 select 옵션에 없음 → 먼저 사용자에게 새 옵션 추가 여부 확인; lark-cli base +field-update로 options 업데이트.

관련 파일

• scripts/bootstrap.sh — 새 규격 테이블을 만들고 소유권을 현재 CLI 로그인 사용자에게 이전. --force는 .config.json이 이미 있어도 강제로 새로 만들고 포인터 덮어쓰기
• scripts/link.sh — 스킬을 기존 Feishu 다차원 테이블(URL 파라미터)에 연결, --force는 기존 포인터 덮어쓰기 가능
• scripts/append.sh — 레코드 한 건 추가, 여러 첨부파일 지원
• scripts/try-export.sh — 이 프로젝트의 dev 서버를 통해 zip 내보내기를 자동으로 시도; 성공 시 stdout에 경로 출력, 실패 시 빈 문자열 출력. append 로직이 "내부 동료는 zip 있음 / 외부 사용자는 zip 없음" 두 경우를 분기 없이 처리할 수 있게 함
• .config.json (실행 시 생성) — base_token / table_id / field_ids / owner_open_id / base_url / linked 저장 (linked=true는 link.sh를 통해 기존 테이블에 바인딩되었음을 의미; 생략 시 bootstrap.sh로 생성됨을 의미)