환경 설정 Skill (일회성)
목표: "이 머신에 이 도구들이 정확히 어디에 있는지"를 명확히 파악하여 경로 계약으로 작성하고, 임무를 마칩니다.
본 스킬의 생명 주기는 '사용 후 폐기'입니다. 상주시키지 마십시오 — 마무리 시 반드시 §7의 확인 절차를 따라야 합니다.
0. 세 가지 엄격한 규칙 (먼저 읽으세요)
- 탐지 단계는 읽기 전용입니다.
scripts/detect.py는 절대로 시스템 파일을 생성/수정/삭제하지 않습니다. 오직which/stat/ 버전 조회 / 디렉터리 나열만 수행합니다. 모든 쓰기 작업은 §4의install.sh에서만 발생해야 하며, 각 항목을 manifest에 기록해야 합니다. - 절대 사용자 디스크에 쓰지 않습니다.
/mnt/c,/mnt/d, Windows 드라이브를 건드리지 않습니다. 모든 결과물과 임시 파일은 현재 작업 공간 또는~/.config/ideaform/에 저장됩니다. - sudo를 시도하지 마십시오. 샌드박스 내 프로세스는 절대 root 권한을 얻을 수 없습니다(커널
NoNewPrivs=1). 시도하는 것은 순전히 시간 낭비입니다. root가 필요한 작업은 사용자가 자신의 터미널에서 실행하도록 안내하고, 정확한 명령을 제시하십시오. 이 프로젝트의 모든 도구는 사용자 수준 설치(AppImage 압축 풀기, venv 패키지 설치, 로컬 폰트)가 가능하도록 설계되었으며, root가 필요하지 않습니다.
1. 계약 파일 (본 스킬의 유일한 외부 산출물)
위치 (고정, 두 스킬 외부의 제3자 위치):
$VW_CONFIG_ROOT/toolchain.json # 기본 ~/.config/ideaform/
$VW_CONFIG_ROOT/env.sh # shell에서 직접 source 할 수 있는 내보내기 스크립트
$VW_CONFIG_ROOT/install-manifest.jsonl # 설치된 항목 기록, 롤백 용도
$VW_CONFIG_ROOT/logs/
$VW_CONFIG_ROOT/backup/ # 덮어쓰기 전 원본 파일 백업
$VW_CONFIG_ROOT 기본값은 ~/.config/ideaform이며, 환경 변수로 재정의할 수 있습니다.
계약 파일을 Skill 디렉터리 외부에 두는 것은 의도적인 설계입니다 — 이 스킬을 삭제해도 작업 흐름 스킬이 계속 읽을 수 있습니다.
schema_version 1의 필드 (작업 흐름 스킬은 이 키들을 사용하여 값을 가져옵니다):
{
"schema_version": 1,
"generated_at": "ISO8601",
"generated_by": "[email protected]",
"verified_at": "ISO8601 | null", // 스모크 테스트 통과 후에만 도장
"host": { "os": "linux", "distro": "...", "arch": "x86_64", "in_wsl": true },
"config_root": "/abs/path",
"tmpdir": "/abs/path/to/big/disk/tmp", // ★ 큰 디스크를 가리켜야 함. 10MB /tmp는 안 됨
"tools": {
"node": { "path": "/abs", "version": "22.x", "status": "ok|missing|degraded" },
"python": { "path": "/abs", "version": "3.13.x", "status": "..." },
"venv": { "path": "/abs", "python": "/abs/bin/python", "pip": "/abs/bin/pip" },
"ffmpeg": { "path": "/abs", "version": "...", "flavor": "full|remotion-minimal", "status": "..." },
"ffprobe": { "path": "/abs", "status": "..." },
"remotion": { "project": "/abs", "version": "4.x", "status": "..." },
"lmms": { "apprun": "/abs", "root": "/abs", "version": "1.2.2",
"stkdir": "/abs", "status": "..." },
"fonts": { "cjk_families": ["Noto Sans CJK SC"], "status": "..." }
},
"env_file": "/abs/env.sh",
"manifest": "/abs/install-manifest.jsonl"
}
작업 흐름 스킬은 시작 시 schema_version과 verified_at을 확인합니다:
버전 불일치 → 본 스킬 재실행 요구; verified_at이 null → "스모크 테스트 통과 안 됨" 경고.
2. 실행 순서 (순서대로, 건너뛰지 마십시오)
1단계 · 읽기 전용 탐지
python3 skills/ideaform-setup/scripts/detect.py # 사람이 읽을 수 있는 보고서
python3 skills/ideaform-setup/scripts/detect.py --json # 기계가 읽을 수 있는 보고서
references/toolchain-matrix.md를 참조하여 항목별로 확인합니다.
각 항목의 상태는 ok / missing / degraded입니다(존재하지만 기능이 완전하지 않은 경우, 예: ffmpeg가 Remotion 축소판).
2단계 · 계획 수립 및 사용자 확인
탐지 결과를 표로 정리하여 사용자에게 보여줍니다: 어떤 항목이 ok, missing, degraded인지, 그리고 각 missing 항목에 대해 어떻게 설치할지, 어디에 설치할지, 필요한 디스크 공간은 얼마인지 명시합니다. 사용자가 확인한 후에만 진행하십시오. 임의로 설치하지 마십시오.
3단계 · 보충 설치 (사용자 확인 후에만)
bash skills/ideaform-setup/scripts/install.sh --only <tool1,tool2>
--only를 전달하지 않으면 모든 missing 항목을 설치합니다. 스크립트:
- 설치 전에 덮어쓰게 될 기존 파일을
$VW_CONFIG_ROOT/backup/<타임스탬프>/에 백업합니다. - 각 단계가 완료될 때마다
install-manifest.jsonl에 레코드를 추가합니다. - 전적으로 사용자 수준 경로에 설치하며, root가 필요하지 않습니다.
특정 항목에 root가 필요한 경우(매우 드뭄), 스크립트는 중단하고 명령을 출력하여 사용자가 자신의 터미널에서 실행하도록 전달합니다.
4단계 · 계약 작성
python3 skills/ideaform-setup/scripts/detect.py --write
분석 결과를 toolchain.json + env.sh에 기록합니다. 이 시점에서 verified_at은 여전히 null입니다.
5단계 · 커뮤니티 Skill 수확 (拿来主义)
계약이 작성되면 체인에 어떤 도구가 있는지 결정됩니다. 기존 지식에만 의존하지 말고, 커뮤니티에서 이미 검증된 성숙한 skill을 가져오십시오:
python3 skills/ideaform-setup/scripts/harvest-skills.py --from-contract # 체인에 있는 각 도구에 대해 수확
python3 skills/ideaform-setup/scripts/harvest-skills.py --from-contract --dry-run # 후보 목록을 먼저 확인
스크립트는 각 도구에 대해: GitHub에서 filename:SKILL.md 검색 → 별/라이선스/최신성 기준 점수 매기기 →
보안 검사(위험 패턴 발견 시 _quarantine/ 격리 영역으로 이동, 다음 후보로 대체) →
~/.workbuddy/skills/<name>/에 저장(출처 증명 _PROVENANCE.md 포함) → manifest에 기록합니다.
- 적격한 후보를 찾지 못함 = 이 도구는 정말 직접 skill을 작성해야 함 — 이것이 바로 이 저장소의
skills/ideaform*이 존재하는 이유입니다. - 저장된 skill은 사용자가 발전시킬 수 있습니다. 스크립트에는 포크 보호(
_harvest.json파일별 해시)가 있습니다: 로컬에서 수정된 것은 기본적으로 덮어쓰지 않으며,--force는 수정되지 않은 것만 업그레이드하고, 포크된 상위 버전은_upstream/에 저장되어 수동 병합을 기다립니다.references/skill-harvest.md§4.1을 참조하십시오. - 전체 프로토콜(점수 세부 기준 / 보안 검사 모드 / 할당량)은
references/skill-harvest.md를 참조하십시오.
이 단계는 초기 설정에만 해당하지 않습니다. 나중에 프로덕션에서 새로운 오픈 소스 도구를 도입할 때(예: 화학 구조식 그리기를 위해 RDKit을 생각할 때), 가장 먼저 할 일은
harvest-skills.py rdkit입니다 — 수확하고, 그다음에 작업하십시오.
6단계 · 엔드투엔드 스모크 검증 (필수, 건너뛰지 마십시오)
python3 skills/ideaform-setup/scripts/verify.py
실제로 최소한의 폐쇄 루프를 실행하여 네 가지 항목이 모두 통과해야 도장을 찍습니다:
★ 합격 기준: 이 단계를 실행한 후, 환경 변수가 없는 상태에서 다시 실행해도 —
env -u TMPDIR -u VW_TMPDIR -u VW_CHROME python3 scripts/verify.py— 여전히 모두 통과해야 계약이 진정으로 자기 일관성이 있다는 것을 증명합니다(도구 체인, TMPDIR, chrome 경로가 모두 계약에서 읽혀짐). 수동export로만 통과 = 계약에 누락이 있으며, 작업 흐름 스킬이 다른 머신에서 실패합니다.
| 검증 | 작업 | 통과 기준 |
|---|---|---|
| ① TTS | 중국어 문장 합성 | 오디오 > 2 KB 및 RMS > 임계값 |
| ② 화면 | Remotion 1프레임 still 렌더링 | PNG 크기 정확, 파일 > 20 KB |
| ③ 오디오 렌더링 | LMMS 1초 프로젝트 렌더링 | WAV 피크 > 1000 및 무음 아님 |
| ④ 오디오/비디오 합성 | ffmpeg가 무음 비디오 + 오디오 트랙 합성 | 출력 오디오 비트레이트 > 64000 bps |
모두 통과 → verified_at을 toolchain.json에 기록합니다.
통과하지 못한 항목이 있으면 중단하고 어떤 항목과 이유를 보고하십시오. 수정 후 다시 실행하십시오. 도장을 찍지 마십시오.
7단계 · 인계 확인 + 마무리
§7 참조.
3. 각 도구 찾는 방법 (요약)
전체 테이블은 references/toolchain-matrix.md에 있습니다. 핵심:
- Node / Python: 우선 머신에 호스팅된 버전 경로(
~/.workbuddy/binaries/...), 그 다음PATH로 폴백. - ffmpeg / ffprobe: 시스템에는 일반적으로 없습니다. Remotion 패키지에 축소판이 포함되어 있음
(
node_modules/@remotion/compositor-linux-x64-gnu/ffmpeg) — 충분하지만 필터가 적음 (volumedetect/acompressor없음,loudnorm지연 있음). 발견되면missing이 아닌degraded로 표시하고 계약에flavor를 명시하십시오. - Remotion 프로젝트: 우선
$VW_REMOTION_PROJECT, 그 다음~/tools/remotion-app, 그 다음 작업 공간의remotion.config.ts스캔, 없으면 본 스킬에 포함된assets/templates/remotion-starter/로 새로 생성. - LMMS:
squashfs-root/AppRun찾기(AppImage 압축 풀기 후 실행 진입점).~/.lmmsrc.xml의stkdir이 반드시 해당 압축 풀기 디렉터리의rawwaves/를 가리켜야 함을 주의하십시오. 그렇지 않으면 전체가 무음이고 오류 보고도 없음 — 이것이 이 작업 흐름에서 가장 비싼 함정이며,verify.py③이 이를 위해 설계되었습니다. - 중국어 폰트:
fc-list로Noto Sans CJK SC등 확인. 없으면 사용자 수준 폰트를~/.local/share/fonts/에 설치.
4. 설치 단계의 위치
| 도구 | 설치 위치 | 방법 |
|---|---|---|
| Node / Python | 없을 때만 설치 | 우선 머신의 기존 호스팅 버전 사용; 그렇지 않으면 사용자에게 안내 |
edge-tts / soundfile / numpy | venv | <venv>/bin/pip install, 반드시 export TMPDIR=<큰 디스크> |
| ffmpeg 전체 버전 | ~/.local/bin/ | 미러에서 정적 패키지 다운로드 후 압축 풀기, root 불필요(선택 사항, 축소판으로 충분하면 설치하지 마십시오) |
| LMMS | $VW_CONFIG_ROOT/lmms/ | AppImage 프록시 다운로드 → --appimage-extract 압축 풀기 |
| Remotion 종속성 | 프로젝트 디렉터리 | npm install, TMPDIR을 큰 디스크로 지정 |
| 중국어 폰트 | ~/.local/share/fonts/ | .ttc 압축 풀기 → fc-cache -f |
⚠️ 모든 다운로드는 검증해야 합니다: 바이트 수 / SHA256 / 압축 풀기 후 실행 가능 여부. 다운로드 실패 시 재시도하고, 절반만 남은 파일을 남기지 마십시오.
5. 롤백
install-manifest.jsonl은 유일한 사실 공급원이며, 형식은 다음과 같습니다:
{ "entries": [
{ "ts": "...", "kind": "pip-install", "target": "<venv>", "detail": "edge-tts==7.3.1",
"undo": "<venv>/bin/pip uninstall -y edge-tts" },
{ "ts": "...", "kind": "mkdir", "target": "$VW_CONFIG_ROOT/lmms", "undo": "rm -rf ..." },
{ "ts": "...", "kind": "backup-file", "target": "~/.lmmsrc.xml",
"backup": "$VW_CONFIG_ROOT/backup/<ts>/lmmsrc.xml", "undo": "cp 백업을 원래 위치로" }
] }
bash skills/ideaform-setup/scripts/rollback.sh --list # 취소할 내용 확인
bash skills/ideaform-setup/scripts/rollback.sh --dry-run # 연습, 실제 실행 안 함
bash skills/ideaform-setup/scripts/rollback.sh --yes # 실제 롤백 (역순)
사용자의 기존 파일을 덮어쓰기 전에 반드시 백업하십시오 — 특히 ~/.lmmsrc.xml.
롤백은 기본적으로 계약 파일을 삭제하지 않습니다(작업 흐름 스킬이 사용하므로). 사용자가 명시적으로 --purge-contract를 요청하는 경우에만 삭제합니다.
7. ★ 마무리: 비활성화 / 보관 / 삭제 (반드시 사용자가 선택하도록 하십시오)
스모크 테스트 통과 후, 자동으로 자신을 삭제하지 마십시오. 다음 절차를 따르십시오:
① 먼저 보고
사용자에게 설명:
- 환경 설정이 완료되었으며,
toolchain.json이 준비되었습니다(경로 제공) - 스모크 테스트 네 가지 항목 결과
- 작업 흐름 스킬은 본 스킬이 없어도 작동합니다(계약 파일이 Skill 외부에 있으므로)
② 세 가지 옵션 제공, 사용자가 선택하도록 함
| 옵션 | 작업 | 복원 가능성 | 적용 |
|---|---|---|---|
| A. 비활성화(권장) | 본 SKILL.md frontmatter의 disable: false를 true로 변경 | false로 되돌리면 복원 | 나중에 머신/환경 변경 시 재실행하고 싶을 때 |
| B. 보관 | 전체 skill 디렉터리를 $VW_CONFIG_ROOT/archive/ideaform-setup-<ts>/로 이동 | 다시 이동하면 복원 | 스킬 목록에 표시되지 않게 하면서 예비로 보관하고 싶을 때 |
| C. 삭제 | 실제로 디렉터리 삭제 | 자동 백업으로 복원 | 더 이상 필요하지 않다고 확신할 때 |
A 권장: 비활성화가 가장 안전하고 비용이 가장 낮으며, "환경이 변경되면 다시 실행" 기능을 유지합니다.
③ 실행 전 철칙
어떤 옵션이든, 먼저 백업, 그다음 실행, 마지막으로 확인:
- 백업:
cp -r <skill 디렉터리> $VW_CONFIG_ROOT/backup/skill-ideaform-setup-<ts>/ - 목록 작성: 삭제/변경될 모든 경로를 목록으로 사용자에게 보여줍니다.
- 재확인: 사용자가 명확히 "삭제하세요" 등으로 응답할 때까지 기다리십시오. 기본값이나 추론으로 확인을 대체하지 마십시오.
- 실행: 삭제는
mv를 사용하여 백업 후 삭제하고, 직접rm -rf를 사용하지 마십시오. - 검증: 작업 흐름 스킬이 여전히
toolchain.json을 읽고 정상적으로 시작되는지 확인하십시오.
④ 삭제 후 자체 점검
test -f "$VW_CONFIG_ROOT/toolchain.json" && echo "계약 여전히 존재 ✓"
계약 존재 → 작업 흐름 영향 없음. 계약 없음 → 실수로 삭제된 것이므로 백업으로 복원.
사용자가 "그냥 삭제해도 되나요?"라고 물으면, 세 가지 옵션을 설명하고 장단점을 설명하십시오. "네"라고만 답하지 마십시오.
8. 일반적인 오류
| 현상 | 실제 원인 | 처리 |
|---|---|---|
| LMMS 렌더링 결과 전체가 무음, 로그에 오류 없음 | ~/.lmmsrc.xml의 stkdir이 압축 풀기 디렉터리의 rawwaves/를 가리키지 않음 | stkdir을 수정하고 verify.py ③을 다시 실행하여 재검증 |
npm install / pip install에서 ENOSPC 오류 | TMPDIR이 10MB /tmp tmpfs에 설정됨 | export TMPDIR=<큰 디스크>, 계약의 tmpdir이 이 용도 |
| Remotion 렌더링 중간에 시간 초과 / 페이지 멈춤 | 동시성이 너무 높아 메모리 폭발(4×1080p 페이지) | --concurrency 낮추기, 긴 클립은 분할 렌더링 |
| AppImage 실행 안 됨 | 샌드박스에 /dev/fuse 없음 | --appimage-extract로 압축 풀고 AppRun 사용 |
| LMMS 시작 거부 | 샌드박스 내 id가 root로 표시됨 | --allowroot 추가 |
edge-tts에서 WSServerHandshakeError 403 오류 | 버전이 너무 오래됨(네트워크 문제 아님) | pip install --upgrade edge-tts, 시스템 시계 동기화 확인 |
자세한 내용은 docs/05-故障排查.md 참조.
9. 누구에게 인계할지
설정이 완료되면, 다음 단계는 작업 흐름 스킬입니다:
skills/ideaform/SKILL.md
작업 흐름 스킬은 먼저 본 스킬이 작성한 toolchain.json을 읽습니다. 인계 대화:
환경 설정이 완료되고 검증되었으며, 계약은
<경로>에 있습니다. 이제 작업 흐름 스킬로 전환하여 생산을 시작하십시오.