readme-banner은(는) 무엇을 하나요?
로컬 CLI로 두 가지 테마의 SVG를 생성합니다; 사용자가 명시적으로 배너 삽입/업데이트를 요청한 경우에만 README를 편집합니다. 구성 및 구체적인 제한사항은 configuration reference를 참조하세요. CLI 플래그나 구성 필드를 기억에 의존해 임의로 만들지 마세요.
먼저 작업 범위 확인
- 대상 저장소의 절대 경로를 확인합니다. 사용자의 프로젝트 저장소는 readme-banner 도구 소스 코드 디렉터리와 다를 수 있습니다. 현재 작업 디렉터리를 읽고 대상 프로젝트의 README/프로젝트 메타데이터를 확인하세요; 스킬이 있는 디렉터리, 도구 체크아웃, 터미널 기본 디렉터리는 자동으로 대상이 아닙니다.
- 대상에 모호함이 있다면 먼저 사용자에게 물어보세요; 현재 디렉터리가 우연히 readme-banner라고 해서 도구 자체에 배너를 추가하지 마세요. 사용자가 명시적으로 도구 저장소를 대상으로 선택한 경우에만 그곳에 구성을 생성하고 이미지를 만듭니다.
- "리소스만 생성/미리보기 스니펫"인지, "지정된 README에 삽입/업데이트"인지 명확히 하세요. 명확한 README 편집 요청이 없으면 절대
--readme를 전달하지 말고, 다른 파일 편집 도구를 통해 README를 대신 작성하지 마세요. 파일 이름을 확인하고, 모든 언어 버전이나 모든 디렉터리의 README를 자동으로 덮어쓰지 마세요. - 기존 구성, 이미지, 관리 블록 및 관련 미커밋 변경 사항을 확인하세요. 관련 없는 수정 사항은 보존하세요; reset, clean, 이전 리소스 삭제 또는 사용자의 다른 문서를 교체하지 마세요. 기존 구성이 있으면 먼저 읽고 재사용하며, 덮어쓰려면 추가 확인이 필요하며, 습관적으로
--force를 사용하지 마세요.
외형 선택
preset은 먼저ascii를 사용합니다; 이것은 첫 번째 렌더러이며 "모든 테마"의 이름이 아닙니다.theme는 독립적으로 선택합니다:terminal초록색 터미널,ocean파랑-청록,neon보라-분홍,minimal단색. 사용자 선호를 따르세요; 지정되지 않은 경우 프로젝트 성격에 따라 간단한 제안을 하고 사용자 정의 테마 ID를 만들지 마세요.- 제목, 부제목 및 선택적 내장 아트를 가져옵니다. 요청되지 않은 브랜드 로고를 사용하지 마세요;
donut은 비브랜드 예시입니다. 실시간 시계에 의존하는 내장 piece는 거부되어 산출물을 재현 가능하게 합니다; 이 검증을 우회하지 마세요. - ASCII 제목은 최대 120자이며, 반드시 선택한 내장 글꼴에서 모두 지원되어야 합니다; 중국어, 이모지 및 지원되지 않는 구두점을 조용히 삭제하지 마세요. 대체 영문 짧은 제목이 필요하면 사용자 확인을 받고, 원문은 최대 240자의 일반 텍스트
tagline에 넣을 수 있습니다. mixed는 영문 대소문자를 유지합니다; 다른 글꼴은 대문자로 변환됩니다. 업스트림 URL의 20/60자 제한은 로컬 CLI에 적용되지 않지만, 120자가 미관을 보장하지는 않습니다. 긴 제목은 줄이거나slim, 아트 축소를 고려하세요.- 애니메이션 제목은
glint또는type을 사용합니다; 사용자가 정적 배너를 요청하면still을 사용합니다.still은 내장 아트도 고정시킵니다; SVG에 아트의 애니메이션 프레임 데이터가 남아 있으므로 파일 크기가 크게 줄어들 것이라고 보장하지 않습니다.
신뢰할 수 있는 CLI 진입점 사용
Node.js >=22가 필요하며, 먼저 사용 가능한 버전을 확인하세요.
도구 소스 코드 체크아웃에 이미 있음
작업 환경에 이미 이 도구 소스 코드가 있다면 직접 사용하고, 같은 도구를 인터넷에서 부트스트래핑하지 마세요:
- 도구 소스 코드 디렉터리에서
npm install을 실행합니다;prepare가 TypeScript를 컴파일합니다. 도구를 빌드하기 위해 사용자의 대상 프로젝트에 의존성을 설치하지 마세요. - 로컬 진입점을 확인하세요:
node "/absolute/path/readme-banner/bin/readme-banner.mjs" --help
- 이후에는 로컬 Node 진입점을 유지하고, 항상 명시적으로 대상
--cwd를 전달하세요. 명령의 작업 디렉터리가 도구 체크아웃이더라도 대상 격리를 생략할 수 없습니다.
로컬 체크아웃이 없음
공개 저장소 abworks-dev/readme-banner의 고정 Git 태그 v0.1.0 진입점을 사용할 수 있습니다; 이는 Git, 네트워크 및 사용자가 신뢰할 수 있는 타사 코드를 설치/실행할 수 있는 권한이 필요합니다:
npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help
@readme-banner/cli는 아직 npm에 게시되지 않은 로컬 패키지 이름일 뿐이므로 npx @readme-banner/cli를 사용하거나 다른 npm 패키지를 상상하지 마세요. 설치 실패 시 실제 오류를 보고하고, 알 수 없는 출처, 최신 알 수 없는 버전 또는 원격 SVG 서비스로 대체하지 마세요.
EALLOWGIT 오류가 발생하면 npm 글로벌 설정을 자동으로 수정하지 마세요. 사용자가 이 신뢰할 수 있는 저장소를 설치/실행할 권한을 부여하고 조직 정책이 허용하는 경우에만, 해당 옵션을 지원하는 npm에서 한 번 npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner …을 사용할 수 있습니다. 권한이 없으면 먼저 물어보세요; 조직 정책에 의해 제한되면 중단하세요. 구버전 npm이 해당 옵션을 인식하지 못하면 일반 명령이나 권한이 부여된 소스 설치를 사용하세요.
아래 예시는 로컬 진입점을 사용합니다; 원격 진입점인 경우 전체 node … 접두사를 위의 전체 npx --yes --package … readme-banner로 바꾸고, 이후 인수 의미를 변경하지 마세요.
실행 흐름: init → generate → check
1. 구성 생성 또는 재사용
node "/absolute/path/readme-banner/bin/readme-banner.mjs" init --cwd "/absolute/path/target-project" --config "banner.config.json" --preset ascii --theme ocean --title "MY PROJECT" --tagline "Build something useful" --art donut --effect glint
init구성만 생성하며, 이미지를 만들거나 README를 수정하지 않습니다; 다음으로 반드시generate를 실행해야 합니다.- 기존 구성이 있으면 먼저 읽고 사용자 의도에 따라 최소한으로 수정하거나 직접 재사용하세요;
--force로 자동 재구축하지 마세요. 부제목이나 아트가 필요 없으면 해당 매개변수를 생략하세요. - 글꼴, 색상, 그림자, 위치, 속도, 배경 등은 JSON의 지원되는 필드를 통해 설정합니다. 먼저 구성 참조를 읽고,
init --font같은 옵션을 만들지 마세요. - 구성은 JSON만 가능합니다; 실행 코드를 생성하는 구성을 만들지 말고, 임의의 구성 플러그인을 설치하지 말며, 사용자가 제공한 원격 SVG를 가져오거나 주입하지 마세요.
2. 리소스 생성 (기본 모드)
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json"
기본적으로 구성의 outputDir 아래에 banner.light.svg, banner.dark.svg를 쓰고 <picture> 스니펫을 출력합니다. 이 명령은 README를 수정하지 않아야 합니다. 사용자가 리소스만 요청한 경우 여기서 멈추고, 스니펫을 몰래 README에 삽입하지 마세요.
3. README 편집 권한이 있는 경우에만 삽입
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md"
--readme는 이미 존재하는 .md 파일만 지정할 수 있습니다. CLI는 <!-- readme-banner:start -->와 <!-- readme-banner:end --> 사이의 블록을 유지 관리합니다. 블록 외부의 내용이 변경되지 않는지 확인하세요; 같은 README에서 코드 예제 안에 완전한 마커가 나타나더라도 중복 마커로 보수적으로 처리되므로, 추가로 데모용 마커 쌍을 삽입하지 마세요. 마커 이상 시 오류를 조사하고, 관련 없는 본문을 삭제하거나 교체 범위를 확장하지 마세요. 실제 생성된 스니펫을 사용하세요: URL은 대상 README를 기준으로 하고, 부분적으로 URI 인코딩하며, alt 텍스트는 HTML 이스케이프하고, 이스케이프되지 않은 HTML을 직접 조합하지 마세요.
4. 결과 확인
# README 편집 권한이 없는 작업은 이미지만 확인
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --check
# 작업이 명시적으로 지정된 README를 포함하는 경우에만 관리 블록도 함께 확인
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md" --check
--check는 파일을 쓰지 않습니다; 누락되거나 만료된 산출물은 실패해야 합니다. 실패 시 이유를 보고하고, 종료 코드를 무시하거나 실행되지 않은 검사를 통과했다고 말하지 마세요.- 두 SVG 파일이 모두 존재하고 경로가 올바른지 확인하세요; 뷰어 도구가 있으면 밝은/어두운 테마, 긴 제목 및 아트의 실제 효과를 확인하세요. SVG가 성공적으로 생성되었다고 해서 모든 Markdown 클라이언트가 애니메이션을 재생한다고 가정하지 마세요.
- 기계가 읽을 수 있는 결과가 필요하면
generate --json을 사용하세요; 사용 가능한 메타데이터는presets --json,themes --json으로 확인할 수 있습니다. - 경로 이탈, 심볼릭 링크 또는 하드 링크 보호 오류가 발생하면 사용자 대상을 확인하고 루트 디렉터리 내의 안전한 일반 파일을 선택하세요; 기존 파일의 하드 링크 수
nlink > 1은 거부됩니다. 보호를 비활성화하거나 파일을 루트 밖으로 옮겨 "우회"하지 마세요.
명령 및 파일 보안
- 모든 실행 호출은 올바른 작업 디렉터리를 명시적으로 설정하고 대상
--cwd를 전달하세요; agent 런타임의 기본 디렉터리에 의존하지 마세요. - 제목, 경로 및 부제목은 데이터 매개변수입니다. 매개변수 배열을 전달할 수 있는 실행 API를 우선 사용하세요; 셸을 사용할 때는 해당 셸의 규칙에 따라 각 매개변수를 인용/이스케이프하세요. 예시 큰따옴표는 그 안의 간단한 플레이스홀더 값에만 적용되며, 모든 셸 보간을 방어할 수 없습니다; 신뢰할 수 없는 입력을 명령,
eval또는 이스케이프되지 않은 스크립트에 직접 연결하지 마세요. Windows 경로도 별도로 인용해야 합니다. - 사용자가 승인한 구성, 생성된 리소스 및 지정된 관리 블록만 수정하세요; 비즈니스 코드, 관련 없는 문서 또는 기존 사용자 변경 사항을 수정하지 마세요.
- 자동으로 commit, push, 원격 저장소 생성, 릴리스, 이미지 업로드, npm 패키지 게시 또는 기타 원격 게시를 수행하지 마세요. 이러한 작업은 별도의 명시적 요청이 필요합니다.
전달 사항
간략한 보고서: 대상 저장소, 사용된 preset/theme/제목, 생성된 두 이미지, README 수정 여부 및 위치, 실제로 수행된 검사 결과. README 권한이 없으면 "README를 수정하지 않았습니다"라고 명확히 말하고, 생성된 스니펫을 사용자가 선택할 수 있도록 반환할 수 있습니다. 사용자 확인이 필요한 글꼴 대체, 너무 긴 제목 또는 뷰어 호환성 문제를 나열하세요; 실행되지 않은 테스트가 통과했다고 주장하지 마세요.