README

Prompt Weaver는 Wi-Fi signage 제작을 위한 프롬프트와 이미지 결과를 생성·보정·내보내는 PHP/Laravel 패키지입니다.

주요 기능은 다음과 같습니다.

디자인 브리프 프롬프트 생성
JSON 설정 프롬프트 생성
이미지 생성 프롬프트 생성
생성 이미지의 텍스트·QR 위치 보정
PNG, HTML, 최종 설정 내보내기

요구사항

PHP 8.3 이상
Composer 2.x
Workbench 개발 환경은 Laravel 12 또는 13
GD PHP extension
QR calibration을 사용할 경우 uv와 OpenCV 실행 환경

설치

composer require cable8mm/prompt-weaver

Laravel package discovery가 service provider를 자동으로 등록합니다. 설정을 서비스의 config/prompt-weaver.php로 복사하려면 다음을 실행합니다.

php artisan vendor:publish --tag=prompt-weaver-config

어떤 방식으로 사용하는가

standalone CLI

standalone으로 사용할 때는 저장소를 clone한 뒤 Composer 의존성을 설치합니다.

git clone https://github.com/cable8mm/prompt-weaver.git
cd prompt-weaver
composer update
uv sync --locked

기본 CLI 흐름은 init → pipe → calibrate → preview입니다. 미리보기를 확인한 뒤 code → export를 실행합니다.

./weaver init cafe-restaurant
./weaver pipe cafe-restaurant
./weaver calibrate cafe-restaurant
./weaver preview cafe-restaurant
./weaver code cafe-restaurant
./weaver export cafe-restaurant

pipe 대신 brief, config, image를 단계별로 실행하면 각 AI 단계의 입력과 결과를 확인하면서 디버깅할 수 있습니다. 자세한 명령 순서는 CLI 사용법을 참고하세요.

Laravel 서비스

Laravel 서비스에서는 Python 환경을 먼저 준비한 뒤 서비스의 Artisan command나 job에서 패키지를 사용합니다.

php artisan prompt-weaver:install
php artisan prompt-weaver:doctor

서비스에서 실행할 calibration command와 도메인 workflow는 패키지가 대신 만들지 않습니다. Laravel 통합 방법은 Laravel 서비스 통합을 참고하세요.

패키지 저장소에서 Laravel workflow를 직접 확인하려면 composer serve로 Workbench를 실행할 수 있습니다. fixture 기반 init + pipe, 이미지 업로드, 실제 calibration, preview 흐름은 Laravel 서비스 통합에 설명되어 있습니다.

Docker와 Coolify

Docker 또는 Coolify 배포에서는 서비스 이미지에 uv를 설치하고, 이미지 빌드 중 위 Artisan 명령을 실행해야 합니다. 첫 웹 요청에서 Python 환경을 설치하면 안 됩니다.

자세한 내용은 Docker와 Coolify 배포를 참고하세요.

문서

패키지 개발

패키지 자체를 수정하는 경우 다음과 같이 개발 의존성을 설치합니다.

git clone https://github.com/cable8mm/prompt-weaver.git
cd prompt-weaver
composer install
uv sync --locked

PHP 테스트와 정적 검사는 다음 명령으로 실행합니다.

composer test
composer lint

WifiNote Publish 기능만 확인하려면 다음 테스트를 실행합니다. ZIP 생성과 manifest, WifiNote 파일·개수 제한, 비밀 설정 저장 권한, 승인 전 업로드 방지, HTTP multipart 요청 및 401/403/422/500·timeout·network 오류 처리를 로컬에서 검사하며 실제 WifiNote 서버에는 접속하지 않습니다.

./vendor/bin/pest \
  tests/Unit/Services/WifiNotePublishServiceTest.php \
  tests/Unit/Services/WifiNoteUploadClientTest.php \
  tests/Integration/WifiNotePublishCommandTest.php

실제 WifiNote 개발 서버에 수동으로 게시 흐름을 시험하려면 먼저 dist/에 시험용 템플릿을 준비한 뒤 다음을 실행합니다.

./weaver login
./weaver publish

예를 들어 개발 서버 주소가 https://wifinote.test라면 ./weaver login에서 다음과 같이 입력합니다.

WifiNote Server URL: https://wifinote.test
Personal Access Token: [개발 서버에서 발급한 테스트용 토큰]

publish 전에 선택한 템플릿 루트의 모든 preview.png를 직접 확인하세요. Prompt Weaver는 검토 결과를 기록하거나 승인 여부를 강제하지 않으며, 게시 과정에서도 export 디렉터리는 그대로 유지됩니다. WifiNote importer 규격에 맞춰 각 템플릿은 config.json, image.png, preview.png를 포함하고 config.json의 metadata.code가 디렉터리명과 일치해야 합니다. 한 팩은 최대 50개 템플릿, 압축 후 100 MiB까지 허용되며, 초과하면 확인 요청 전에 거부됩니다. 큰 dist/에서 일부만 시험하려면 이 규격을 만족하는 템플릿만 별도 폴더에 준비하고 ./weaver publish --dist-root=path/to/test-templates를 실행하세요.

login에 입력한 URL과 토큰은 이후 publish에서 사용됩니다. publish는 업로드 전에 확인을 요청하며, y를 입력하면 선택한 폴더의 ZIP을 WifiNote 서버로 전송합니다. 실제 개발 서버에서만 시험하고, 202 Accepted와 업로드 ID는 ZIP이 private inbox에 저장됐음을 뜻합니다. WifiNote import는 업로드와 별개로 php artisan template-packs:import 또는 Scheduler가 수행합니다. 업로드 요청을 보내지 않고 확인 동작만 점검하려면 질문에서 n을 선택합니다.

Python detector 테스트는 다음과 같습니다.

uv run --locked python scripts/test_calibrate_qr.py

실제 AI provider를 사용하는 E2E 테스트는 명시적으로 활성화해야 합니다.

composer test:e2e

패키지의 CLI 명령을 변경하면 CLI 사용법과 테스트를 함께 수정합니다. Laravel 통합 명령을 변경하면 Laravel 서비스 통합과 Docker/Coolify 배포를 함께 확인합니다. pyproject.toml 또는 uv.lock을 변경하면 Python 환경 설치와 Docker 배포 예시도 함께 확인합니다.

서비스 고유의 command 이름은 패키지에 추가하지 않고 소비 서비스에서 정의합니다.

라이선스

MIT

cable8mm / prompt-weaver

Package info

Security

Statistics