push -f

Edit 툴 4종, 880회 실측 성공률 — replace가 이긴 이유와 patch의 토큰 블랙홀

Sat, 15 Aug 2026 00:00:00 GMT

Edit 툴 4종, 880회 실측 성공률 — `replace`가 이긴 이유와 `patch`의 토큰 블랙홀

코딩 에이전트를 만들 때 "모델이 코드를 어떻게 수정하게 할까?"는 보통 구현 디테일로 취급된다. Git 스타일 unified diff(apply_patch)나 퍼지 매칭(patch)이 사람 개발자에게 익숙하다는 이유로 기본값이 되기 쉽다. 하지만 LLM은 코드를 토큰 스트림으로 본다. 줄 번호 오프셋 계산, 컨텍스트 매칭, hunk 헤더의 산수 실수가 쌓이면 단순한 "실패"가 아니라 비싼 재시도 루프로 이어진다.

이 글은 Oh My Pi 하네스가 제공하는 4가지 코드 편집 툴 — replace, hashline, apply_patch, patch — 의 성공률과 토큰·비용 효율을 11개 LLM × 20개 TypeScript 태스크, 총 880회 실행으로 실측한 결과다.

결론부터: replace가 평균 성공률 85.0%로 압도적이다. patch는 평균 성공률 68.2%로 오히려 2위인데도 입력 토큰이 replace의 3.05배, 성공 1건당 비용은 2.8배로 최악이다. 성공률만 보면 안 되는 이유가 여기 있다.

TL;DR

툴	평균 성공률	11개 모델 중 최고 툴로 선택	비용/성공
`replace`	85.0%	8/11	$0.0094
`hashline`	74.5%	2/11	$0.0118
`apply_patch`	59.1%	1/11	$0.0228
`patch`	68.2%	0/11	$0.0260

replace는 "실패의 하한선"이 가장 높다. 11개 모델 최저 성공률이 60% — 어떤 모델이든 어느 정도는 고쳐낸다.
patch는 어떤 모델에서도 최고 툴이 되지 못했고, 실패할 때마다 파일 전체 재독 → 더 큰 패치 재시도 루프로 토큰을 태운다.
hashline은 구조적 정밀도가 필요한 모델(kimi-k3, qwen3.7-plus)에서 강점을 보였다.
apply_patch는 mimo-v2.5 한 모델만 85%로 최고 툴로 선택 — 모델별 편향이 뚜렷하다.

1. 하네스의 4가지 edit 툴

툴	동작 방식	장점	실패 모드
`replace`	`path, startLine, endLine, newText` — 줄 범위를 통째로 교체	컨텍스트 드리프트 없음, 지역 수정에 출력 토큰 최소	줄 번호가 밀리면 off-by-one
`hashline`	`[파일#태그]` 콘텐츠 해시 헤더 + `SWAP`/`DEL`/`INS` 연산	스냅샷 검증이 결정적, 낡은 줄 번호에 면역	해시 문법을 엄격히 따라야 함
`apply_patch`	표준 unified diff (`@@ -N,M +N,M @@`)	Git 형식, 학습 데이터에 익숙	hunk 헤더 줄 수를 모델이 자주 잘못 계산
`patch`	`oldContext` 문자열을 찾아 `newContext`로 교체	줄 번호 불필요, 프롬프트가 직관적	공백/들여쓰기 민감, 다중 턴 재시도 루프 유발

2. 측정 설계

스케일: 11개 모델 × 4개 툴 × 20개 태스크 = 880회 시도 (arm당 20회, best-of-1)
태스크: 100% TypeScript — Core TS(45%), Express/Node(25%), React+TSX(20%), DOM+jsdom(10%). 난이도는 Easy 25% ~ Nightmare(10+ 파일 아키텍처 리팩터링) 10%
검증: Docker verifier 컨테이너(--network=none)에서 tsc --noEmit + 숨은 동작 테스트. 모델이 자기 환경을 속일 수 없게 격리
설정: 모든 실행은 --thinking off — 추론 토큰 노이즈를 제거하고 순수한 툴 콜·편집 정밀도만 측정
비용: 공식 리스트 가격 기준. 429 쿼터 실패(인프라 원인)는 0토큰으로 제외, 에이전트 유발 재시도는 100% 부과

3. 툴별 성공률

11개 모델 각각에서 해당 툴로 20개 태스크를 돌린 성공률의 평균·중앙값·하한·상한:

툴	평균	중앙값	최저	최고	총 성공 / 220
`replace`	85.0%	85%	60% (mimo-v2.5)	100% (deepseek-v4-flash)	187
`hashline`	74.5%	80%	25% (qwen3.8-max)	95% (deepseek-v4-flash)	164
`apply_patch`	59.1%	65%	0% (qwen3.8-max)¹	90% (deepseek-v4-flash)	130
`patch`	68.2%	70%	35% (minimax-m3)	85% (kimi-k3·qwen3.8-max·deepseek-v4-flash·deepseek-v4-pro)	150

¹ qwen3.8-max × apply_patch arm은 토큰 0·비용 $0 — 쿼터/인프라 실패로 보이며 실측치가 아니다. 제외 시 apply_patch 평균은 65.0%.

여기서 가장 중요한 지표는 하한선(floor) 이다. replace는 가장 못하는 모델(mimo-v2.5)도 60%를 기록했다. 반면 hashline의 바닥은 25%, apply_patch는 사실상 측정 불가(0%)였다. 좋은 툴은 모델의 천장을 높이는 게 아니라 바닥을 끌어올린다 — 그리고 replace가 유일하게 그 역할을 했다.

흥미로운 반전: 모든 툴에서 가장 높은 성공률은 deepseek-v4-flash가 가져갔다 (replace 100%, hashline 95%, apply_patch 90%, patch 85% 공동 1위). 모델 역량이 받쳐주면 어떤 툴이든 잘 쓰지만, 툴은 모델의 바닥을 결정한다.

4. 토큰 & 비용: 성공률 너머

성공률만 보면 patch는 2위다. 그런데 실제 지출을 보면 이야기가 완전히 달라진다 (44개 arm 합산):

툴	총 입력 토큰	총 출력 토큰	캐시 읽기	총 비용	태스크당 입력	평균 $/성공
`replace`	4.26M	197k	6.89M	$1.78	19.4k	$0.0094
`hashline`	6.51M	260k	8.59M	$2.07	29.6k	$0.0118
`apply_patch`	8.82M	243k	12.07M	$2.26	40.1k	$0.0228
`patch`	13.01M	376k	16.79M	$3.28	59.1k	$0.0260

patch는 태스크당 평균 59.1k 입력 토큰 — replace(19.4k)의 3.05배다. 성공률 격차(68% vs 85%)보다 토큰 격차가 훨씬 크다. 성공 1건당 비용으로 환산하면 patch는 replace의 2.8배였고, 880회 전체 총지출($9.38)에서도 replace는 4개 툴 중 가장 적게 썼다.

전체로는 631회 성공(71.7%) 이었다.

5. 모델 × 툴 상호작용 매트릭스

성공률(%) — 굵은 값은 해당 모델의 최고 툴:

모델	`apply_patch`	`hashline`	`patch`	`replace`
deepseek-v4-flash	90	95	85	100
qwen3.8-max	0¹	25	85	95
glm-5.2	45	80	45	95
kimi-k2.7-code	65	80	70	90
hy3	75	80	55	90
kimi-k3	25	90	85	85
mimo-v2.5	85	60	60	60
mimo-v2.5-pro	50	80	65	85
deepseek-v4-pro	80	80	85	85
qwen3.7-plus	75	85	80	70
minimax-m3	60	65	35	80

툴별 우승 횟수: replace 8, hashline 2, apply_patch 1, patch 0.

replace가 11개 중 8개 모델에서 최고 — 현대 LLM은 번호가 매겨진 read 출력만 있으면 절대 줄 번호 이해에 강하다. 오프셋 산수를 아예 제거해 버리는 게 핵심이다.
hashline은 kimi-k3(90%)와 qwen3.7-plus(85%)처럼 구조적 정밀도를 잘 따르는 모델에서 빛났다. 콘텐츠 해시 태그가 낡은 앵커 덮어쓰기를 원천 차단한다.
apply_patch는 mimo-v2.5 한 모델만 85%로 선호. 나머지 모델에선 hunk 헤더 산수 실패가 잦았다.
patch는 단 한 모델의 최고 툴도 되지 못했다.

6. 사례 연구: glm-5.2, 툴 하나로 50%p가 갈렸다

같은 모델, 같은 20개 태스크에서 툴만 바꿨을 뿐인데:

replace     :  95% (19/20) |  298,956 입력 토큰 |  $0.3433
patch       :  45% ( 9/20) | 1,481,206 입력 토큰 |  $1.0886  (토큰 4.95배, 비용 3.2배)
apply_patch :  45% ( 9/20) | 1,482,332 입력 토큰 |  $1.0882

replace로 바꾸자 성공률이 45% → 95%로 두 배가 되면서 토큰은 79.8% 감소했다. 툴 설계가 모델의 실제 코딩 능력보다 더 큰 변수인 경우가 있다는, 가장 극적인 증거다.

7. 왜 `patch`는 실패 루프에 빠지는가

원본 이벤트 스트림(sample-failed-patch-loop-glm52.jsonl)을 보면 패턴이 반복적이다:

graph TD
    A[patch 컨텍스트 매칭 실패] --> B[read로 파일 전체 재독]
    B --> C[컨텍스트를 더 크게 붙인 patch 재시도]
    C -->|여전히 공백/들여쓰기 미스매치| B
    C -->|턴 한도 초과| D[실패 · 토큰 폭증]

미세한 공백 차이(탭 vs 스페이스, 줄바꿈, 들여쓰기)로 첫 매칭이 실패한다.
모델은 거의 예외 없이 파일 전체를 다시 읽어 재정렬한다.
더 큰 컨텍스트로 재시도하지만, 근본 원인(컨텍스트 오해)이 해결되지 않아 또 실패한다.
2~4턴 반복 후 턴 한도에 걸려 실패 — 태스크 하나에 75,000+ 토큰을 태운 사례도 있다.

반면 replace·hashline은 실패 시 "정확한 앵커 오류"라는 결정적 피드백을 주므로 모델이 즉시 재조준한다. 실패가 비싸지 않은 구조가 핵심이다. 퍼지 매칭은 컨텍스트 오해를 숨기고, 그 대가를 토큰으로 지불하게 만든다.

8. 하네스에 주는 교훈

기본값은 replace로. 최신 프론티어·중간 모델에서 가장 높은 신뢰성, 가장 낮은 지연, 가장 적은 토큰 낭비.
대형 파일·동시 편집 환경에서는 hashline. 1,000줄 이상 파일에서 전체 블록 교체가 동시 편집을 덮어쓸 위험이 있다면, 콘텐츠 해시 태그가 낡은 앵커 문제를 제거한다.
순수 컨텍스트 diff patch는 피할 것. 컨텍스트 블록 형식에 특화 파인튜닝된 모델이 아니라면, 실패 루프가 컨텍스트 윈도우와 API 예산을 빠르게 소진한다.
성공률 단일 지표로 툴을 평가하지 말 것. 이 벤치마크처럼 성공률 2위인 툴이 비용은 최악일 수 있다. 성공 1건당 비용($/success)과 토큰 분포를 함께 봐야 한다.

9. 데이터 & 재현

이 글의 모든 수치는 공개된 원본 데이터에서 직접 재계산했다. 벤치마크 데이터, 원본 이벤트 스트림, 재현 스크립트는 omp-bench-review 저장소에 포함돼 있다 (누구나 같은 인프라로 재현 가능):

data/summary-leaderboard.json — 44개 arm 전체 메트릭 (토큰 버킷, 가격, wall time)
data/model-rankings.csv — 스프레드시트용 테이블
data/raw-samples/ — 실제 JSONL 이벤트 스트림 3종 (완벽한 1턴 replace / patch 실패 루프 / 429 쿼터 오류)
scripts/analyze-results.ts · scripts/export-charts.ts — 리더보드·차트 재현 스크립트

bun run analyze   # 리더보드 출력
bun run charts    # ASCII 차트 출력

검증은 Docker 격리 verifier에서 tsc --noEmit + 숨은 동작 테스트로 수행했고, 실행 인프라는 Azure Spot(시간당 약 0.02달러 수준)의 일회성 VM으로 전체 캠페인 비용을 10달러 미만으로 유지했다.

MVCC 그리고 PostgreSQL과 MySQL의 차이점

Mon, 29 Jun 2026 00:00:00 GMT

MVCC

MVCC는 다중 버전 동시성 제어의 약자이다. "기존 데이터를 덮어쓰기" 대신 "새 데이터를 쌓아올린다"로 요약할 수 있다.

그러니까 창팝으로 비유하자면...

A교실에서 시험 치면 강제 -50점 B교실에서 시험 치면 강제 +50점 근데 몇 개월 전에 이 사실에 대해 모른 채로 A교실에서 시험 치기로 한 거임 교실을 바꾸려면 내년을 기약하고 똑같이 B교실이 +50점 줄지 모르는 상황 이 형평성에 가만히 있으면 정당한거냐? -메벤남

그냥넣어보고싶었음

이해가하나도안되잖아쿼리슝좍아

Git으로 설명해보자.

일단 main 브랜치에서 dev 브랜치를 딴다. (BEGIN)
거기서 작업을 잔뜩 한다. (BEGIN 이후 쿼리)
이제 작업사항들을...
- main에 머지하거나(COMMIT)
- 버린다(ROLLBACK)

PostgreSQL의 MVCC 구현

어 코끼리는 짱커 그래서 디스크 더 쓸 거야

순서대로 알아보자면

BEGIN
대충 뭔가 어마무시하게 많은 쿼리들
- UPDATE: 쓰려는 원본 테이블 대신 임시 튜플을 만들고, 그곳에 UPDATE한다
- SELECT: 원본 테이블과 임시 튜플(있으면)에서 찾는다
이제 다 끝나고...
- ROLLBACK: 임시 튜플을 버린다
- COMMIT: 임시 튜플로 원본 테이블의 튜플을 교체한다(레퍼런스 교체 느낌으로 빠르다!)

그렇게 되면, 임시 튜플이나 원본 튜플들은 레퍼런스 없이 떠돌게 된다. 이는 VACUUM 시 GC된다.

이 구현의 장점은...

어마무시하게 원자적이다. 레퍼런스 바꾸기 딸깍ㅋㅋ
SELECT가 여러 번 있어도 용량이 커지지 않는다
- 락도 안 걸린다!

한편 단점은...

UPDATE 쿼리 많으면 산으로 간다. 디스크 용량 3배 사용 이벤트!

MySQL의 MVCC 구현

순서대로 알아보자면

BEGIN
대충 뭔가 많은 쿼리들
- UPDATE: 원래 데이터를 undo log에 백업해두고, 원본 테이블을 바로 수정한다
- SELECT: 현재 트랜잭션 격리 수준에 따라, undo log를 참고해서 적절한 버전의 데이터를 조회한다
이제 다 끝나고...
- ROLLBACK: undo log에 있는 원래 데이터로 복구한다
- COMMIT: 변경사항을 확정한다. undo log는 더 이상 필요 없어지면 purge 스레드가 정리한다

undo log에는 두 종류가 있다:

insert undo log: INSERT 때 기록. 트랜잭션 커밋되면 바로 버려도 됨
update undo log: UPDATE/DELETE 때 기록. MVCC를 위해 커밋 후에도 당장 안 지울 수도 있음

트랜잭션 격리 수준별 동작 방식:

이 구현의 장점은...

디스크 용량을 PostgreSQL보단 적게 쓴다. 원본을 바로 갈아치우니까
UPDATE가 많아도 튜플이 쌓이지 않는다

한편 단점은...

undo log 관리가 복잡하다. purge 스레드가 바쁘게 돈다
롤백 시 undo log를 뒤져서 원복해야 하므로 오래된 트랜잭션일수록 롤백 비용이 크다
SELECT가 오래된 undo log까지 뒤져야 하면 느려질 수 있다, 위 단점과 시너지

그래서 뭐가 더 좋은데?

둘 다 정답은 없다. 트레이드오프가 있을 뿐.

항목	PostgreSQL	MySQL
저장 방식	새 튜플 추가 (append-only)	원본 수정 + undo log
디스크 사용량	`UPDATE` 많으면 죽을게	상대적으로 안정적
SELECT 성능	어 형이야 형은 락 거는 법 몰라	격리 수준에 따라 다름
VACUUM / Purge	`VACUUM` 필요 (안 한다고? 그럼죽어)	purge 스레드가 자동 처리
롤백 속도	임시 튜플 삭제만 하면 끝	undo log 뒤져서 복구해야 함
원자성	레퍼런스 교체로 딸깍	undo log 기반 복구

요약

PostgreSQL: 읽기 성능이 중요하고, 디스크 넉넉할 때. MVCC가 진짜로 "쌓아올린다"에 가깝다
MySQL: 읽기/쓰기 밸런스가 중요하고, 디스크를 아껴야 할 때. Undo log로 타협한 MVCC

OpenAI Responses API SSE Reversing Notes

Sat, 20 Jun 2026 00:00:00 GMT

OpenAI Responses API — SSE Streaming Internals

Source: OpenAI Python SDK openai-python (Stainless-generated)
Scope: SSE (Server-Sent Events) only. WebSocket mode excluded.
Last updated: 2026-06-20

1. High-Level Architecture

flowchart TB
    subgraph User["User Code"]
        A["client.responses.create(stream=True)"]
    end
    subgraph HTTP["HTTP POST /v1/responses"]
        B["POST /v1/responses<br/>headers: text/event-stream<br/>body: { stream: true }"]
    end
    subgraph SSE["SSE Decoding"]
        C["SSEDecoder.decode(line)"]
        D["ServerSentEvent"]
        E["construct_type(discriminator=type)"]
    end
    subgraph SDK["SDK Layer"]
        F["ResponseStreamState<br/>(accumulate + handle)"]
        G["ResponseStreamEvent[]"]
    end
    A --> B
    B -->|chunked transfer| C
    C -->|line by line| D
    D -->|JSON dict| E
    E -->|typed event| F
    F -->|yields| G

or via the convenience API:

with client.responses.stream(input="...", model="gpt-4o") as stream:
    for event in stream:
        ...

which uses ResponseStreamManager → ResponseStream internally.

2. SSE Wire Format

Unlike the Assistants API (which uses named SSE event: fields like thread.message.delta), the Responses API embeds the event type directly in the JSON payload as a type field.

Each SSE chunk looks like:

data: {"type":"response.created","response":{...},"sequence_number":0}

data: {"type":"response.in_progress","response":{...},"sequence_number":1}

data: {"type":"response.output_item.added","output_index":0,"item":{...},"sequence_number":2}

data: {"type":"response.content_part.added","output_index":0,"item_id":"...","content_index":0,"part":{...},"sequence_number":3}

data: {"type":"response.output_text.delta","output_index":0,"item_id":"...","content_index":0,"delta":"Hello","sequence_number":4}
...

event: line is not set for Responses API SSE events.
The type field inside the JSON body is the discriminator.
Every event has a sequence_number: int for ordering.
The stream ends when the connection closes (no [DONE] sentinel for Responses; the [DONE] check in Stream._iter_events is only for legacy Chat Completions).

3. Full Event Catalog (53 types)

3.1 Response Lifecycle Events

#	type literal	Class	Fields
1	response.created	`ResponseCreatedEvent`	response: Response, sequence_number: int
2	response.queued	ResponseQueuedEvent	response: Response, sequence_number: int
3	response.in_progress	ResponseInProgressEvent	response: Response, sequence_number: int
4	response.completed	`ResponseCompletedEvent`	response: Response, sequence_number: int
5	response.failed	ResponseFailedEvent	response: Response, sequence_number: int
6	response.incomplete	ResponseIncompleteEvent	response: Response, sequence_number: int
7	error	ResponseErrorEvent	code: Optional[str], message: str, param: Optional[str], sequence_number: int

3.2 Output Items — Structural

#	type literal	Class	Fields
8	response.output_item.added	ResponseOutputItemAddedEvent	item: `ResponseOutputItem`, output_index: int, sequence_number: int
9	response.output_item.done	ResponseOutputItemDoneEvent	item: `ResponseOutputItem`, output_index: int, sequence_number: int
10	response.content_part.added	ResponseContentPartAddedEvent	part: Part, content_index: int, item_id: str, output_index: int, sequence_number: int
11	response.content_part.done	ResponseContentPartDoneEvent	part: Part, content_index: int, item_id: str, output_index: int, sequence_number: int

Part is a discriminated union of:

ResponseOutputText (type=output_text)
ResponseOutputRefusal (type=refusal)
PartReasoningText (type=reasoning_text)

3.3 Text Content

#	type literal	Class	Fields
12	response.output_text.delta	`ResponseTextDeltaEvent`	delta: str, content_index: int, item_id: str, output_index: int, logprobs: List[Logprob], sequence_number: int
13	response.output_text.done	`ResponseTextDoneEvent`	text: str, content_index: int, item_id: str, output_index: int, logprobs: List[Logprob], sequence_number: int
14	response.output_text.annotation.added	ResponseOutputTextAnnotationAddedEvent	annotation: object, annotation_index: int, content_index: int, item_id: str, output_index: int, sequence_number: int

logprob structure:

Logprob:
  token: str
  logprob: float
  top_logprobs: Optional[List[LogprobTopLogprob]]  # up to 20 alternatives

LogprobTopLogprob:
  token: Optional[str]
  logprob: Optional[float]

3.4 Refusal

#	type literal	Class	Fields
15	response.refusal.delta	ResponseRefusalDeltaEvent	delta: str, content_index: int, item_id: str, output_index: int, sequence_number: int
16	response.refusal.done	ResponseRefusalDoneEvent	refusal: str, content_index: int, item_id: str, output_index: int, sequence_number: int

3.5 Function Calling

#	type literal	Class	Fields
17	response.function_call_arguments.delta	`ResponseFunctionCallArgumentsDeltaEvent`	delta: str, item_id: str, output_index: int, sequence_number: int
18	response.function_call_arguments.done	ResponseFunctionCallArgumentsDoneEvent	arguments: str, name: str, item_id: str, output_index: int, sequence_number: int

3.6 MCP (Model Context Protocol)

#	type literal	Class	Fields
19	response.mcp_call.in_progress	ResponseMcpCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
20	response.mcp_call_arguments.delta	ResponseMcpCallArgumentsDeltaEvent	delta: str (JSON partial), item_id: str, output_index: int, sequence_number: int
21	response.mcp_call_arguments.done	ResponseMcpCallArgumentsDoneEvent	arguments: str (JSON full), item_id: str, output_index: int, sequence_number: int
22	response.mcp_call.completed	ResponseMcpCallCompletedEvent	item_id: str, output_index: int, sequence_number: int
23	response.mcp_call.failed	ResponseMcpCallFailedEvent	item_id: str, output_index: int, sequence_number: int
24	response.mcp_list_tools.in_progress	ResponseMcpListToolsInProgressEvent	item_id: str, output_index: int, sequence_number: int
25	response.mcp_list_tools.completed	ResponseMcpListToolsCompletedEvent	item_id: str, output_index: int, sequence_number: int
26	response.mcp_list_tools.failed	ResponseMcpListToolsFailedEvent	item_id: str, output_index: int, sequence_number: int

3.7 Audio

#	type literal	Class	Fields
27	response.audio.delta	ResponseAudioDeltaEvent	delta: str (Base64 audio bytes), sequence_number: int
28	response.audio.done	ResponseAudioDoneEvent	sequence_number: int
29	response.audio.transcript.delta	ResponseAudioTranscriptDeltaEvent	delta: str, sequence_number: int
30	response.audio.transcript.done	ResponseAudioTranscriptDoneEvent	sequence_number: int

3.8 Web Search Tool

#	type literal	Class	Fields
31	response.web_search_call.in_progress	ResponseWebSearchCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
32	response.web_search_call.searching	ResponseWebSearchCallSearchingEvent	item_id: str, output_index: int, sequence_number: int
33	response.web_search_call.completed	ResponseWebSearchCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.9 File Search Tool

#	type literal	Class	Fields
34	response.file_search_call.in_progress	ResponseFileSearchCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
35	response.file_search_call.searching	ResponseFileSearchCallSearchingEvent	item_id: str, output_index: int, sequence_number: int
36	response.file_search_call.completed	ResponseFileSearchCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.10 Code Interpreter Tool

#	type literal	Class	Fields
37	response.code_interpreter_call.in_progress	ResponseCodeInterpreterCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
38	response.code_interpreter_call.interpreting	ResponseCodeInterpreterCallInterpretingEvent	item_id: str, output_index: int, sequence_number: int
39	response.code_interpreter_call_code.delta	ResponseCodeInterpreterCallCodeDeltaEvent	delta: str, item_id: str, output_index: int, sequence_number: int
40	response.code_interpreter_call_code.done	ResponseCodeInterpreterCallCodeDoneEvent	code: str, item_id: str, output_index: int, sequence_number: int
41	response.code_interpreter_call.completed	ResponseCodeInterpreterCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.11 Reasoning

#	type literal	Class	Fields
42	response.reasoning_text.delta	ResponseReasoningTextDeltaEvent	delta: str, content_index: int, item_id: str, output_index: int, sequence_number: int
43	response.reasoning_text.done	ResponseReasoningTextDoneEvent	text: str, content_index: int, item_id: str, output_index: int, sequence_number: int
44	response.reasoning_summary_part.added	ResponseReasoningSummaryPartAddedEvent	part: Part (summary_text), summary_index: int, item_id: str, output_index: int, sequence_number: int
45	response.reasoning_summary_part.done	ResponseReasoningSummaryPartDoneEvent	part: Part (summary_text), summary_index: int, item_id: str, output_index: int, sequence_number: int
46	response.reasoning_summary_text.delta	ResponseReasoningSummaryTextDeltaEvent	delta: str, summary_index: int, item_id: str, output_index: int, sequence_number: int
47	response.reasoning_summary_text.done	ResponseReasoningSummaryTextDoneEvent	text: str, summary_index: int, item_id: str, output_index: int, sequence_number: int

3.12 Image Generation

#	type literal	Class	Fields
48	response.image_generation_call.in_progress	ResponseImageGenCallInProgressEvent	item_id: str, output_index: int, sequence_number: int
49	response.image_generation_call.generating	ResponseImageGenCallGeneratingEvent	item_id: str, output_index: int, sequence_number: int
50	response.image_generation_call.partial_image	ResponseImageGenCallPartialImageEvent	partial_image_b64: str, partial_image_index: int (0-based), item_id: str, output_index: int, sequence_number: int
51	response.image_generation_call.completed	ResponseImageGenCallCompletedEvent	item_id: str, output_index: int, sequence_number: int

3.13 Custom Tool Call

#	type literal	Class	Fields
52	response.custom_tool_call_input.delta	ResponseCustomToolCallInputDeltaEvent	delta: str, item_id: str, output_index: int, sequence_number: int
53	response.custom_tool_call_input.done	ResponseCustomToolCallInputDoneEvent	input: str, item_id: str, output_index: int, sequence_number: int

4. SSE Parsing Pipeline (Wire to Typed Event)

flowchart TB
    subgraph HTTP["HTTP Response Stream"]
        A["httpx.Response.iter_bytes()"]
    end
    subgraph SSE["SSE Decoder (WHATWG SSE)"]
        B["SSEDecoder.decode(line)"]
        C["ServerSentEvent<br/>.event - None for Responses<br/>.data - raw JSON string"]
    end
    subgraph DISPATCH["Stream Dispatcher"]
        D{"sse.data starts with [DONE]?"}
        E{"sse.event starts with thread.?"}
        F["construct_type(discriminator=type)"]
    end
    subgraph OUT["Typed Event"]
        G["ResponseCreatedEvent |<br/>ResponseTextDeltaEvent |<br/>... (52 more types)"]
    end
    A --> B
    B --> C
    C --> D
    D -->|yes| H["break (legacy)"]
    D -->|no| E
    E -->|yes| I["thread. events (Assistants)"]
    E -->|no| F
    F --> G

Key decoder details

SSEDecoder accumulates lines until a blank line (\n\n, \r\r, or \r\n\r\n).
Each SSE field (event:, data:, id:, retry:) is processed per spec.
For Responses, event: is absent → ServerSentEvent.event is None.
The raw JSON data: is deserialized and passed to construct_type().
ResponseStreamEvent is Annotated[Union[...], PropertyInfo(discriminator="type")], so construct_type examines the "type" key to dispatch to the correct subclass.

5. SDK Convenience API: `ResponseStream` / `ResponseStreamState`

5.1 `ResponseStreamManager` (entry point)

Usage:

with client.responses.stream(
    input="Hello", model="gpt-4o"
) as stream:  # returns ResponseStream[TextFormatT]
    for event in stream:
        ...

The manager:

Calls client.responses.create(stream=True, ...) to get the raw Stream[ResponseStreamEvent].
Wraps it in ResponseStream(raw_stream=..., text_format=..., input_tools=...).
Exposes the stream as an iterator of ResponseStreamEvent[TextFormatT].

5.2 `ResponseStream` → `ResponseStreamState`

ResponseStream.__stream__() delegates to ResponseStreamState.handle_event(sse_event) for each raw event.

handle_event() produces 1 or 2 events per raw SSE event:

Raw SSE type	Emitted events
response.output_text.delta	`ResponseTextDeltaEvent` (with snapshot field added — accumulated text so far)
response.output_text.done	`ResponseTextDoneEvent` (with parsed field if text_format is set)
response.function_call_arguments.delta	`ResponseFunctionCallArgumentsDeltaEvent` (with snapshot — accumulated args so far)
response.completed	`ResponseCompletedEvent` (with response being the full parsed `ParsedResponse`)
All others	Passed through as-is

5.3 accumulate_event() — State Machine

ResponseStreamState maintains a __current_snapshot (partial ParsedResponse):

response.created → Creates initial snapshot from event.response.
response.output_item.added → Appends item to snapshot.output[] (handles function_call, message, and generic types).
response.content_part.added → Appends content part to the indexed output message.
response.output_text.delta → Concatenates delta to the matching output_text content's text.
response.function_call_arguments.delta → Concatenates delta to the matching function call's arguments.
response.completed → Stores the fully parsed response via parse_response() (also handles structured output parsing).

5.4 Convenience methods

stream.get_final_response() → Consumes entire stream, returns the accumulated ParsedResponse.
stream.until_done() → Blocks until stream fully consumed.
stream.close() → Closes underlying httpx response.

5.5 `ResponseStreamEvent`[TextFormatT] (SDK wrapper types)

These subclass or wrap the raw generated types with extra fields:

Raw type	SDK wrapper	Extra fields
`ResponseTextDeltaEvent`	lib.streaming.responses.`ResponseTextDeltaEvent`	snapshot: str (accumulated text)
`ResponseTextDoneEvent`	lib.streaming.responses.`ResponseTextDoneEvent`	parsed: Optional[TextFormatT]
`ResponseFunctionCallArgumentsDeltaEvent`	lib.streaming.responses.`ResponseFunctionCallArgumentsDeltaEvent`	snapshot: str (accumulated args)
`ResponseCompletedEvent`	lib.streaming.responses.`ResponseCompletedEvent`	response: `ParsedResponse`[TextFormatT]

The composite ResponseStreamEvent type alias used by the stream is:

ResponseStreamEvent = Annotated[Union[
    ResponseTextDeltaEvent,       # SDK wrapper
    ResponseTextDoneEvent,        # SDK wrapper
    ResponseFunctionCallArgumentsDeltaEvent,  # SDK wrapper
    ResponseCompletedEvent,       # SDK wrapper
    ResponseAudioDeltaEvent,      # raw
    ... (all other raw events)    # raw
], PropertyInfo(discriminator="type")]

6. Background Mode Streaming

When background=True is passed to responses.stream():

The API request includes "background": true.
The server immediately returns a response.created event with the response id.
The stream stays open but yields events asynchronously as the background processing progresses.
The stream can be interrupted and resumed: note the response_id from response.created, then later call responses.stream(response_id=id, starting_after=N) to resume from sequence number N.

Usage pattern:

with client.responses.stream(input="...", model="gpt-4o", background=True) as stream:
    for event in stream:
        if event.type == "response.created":
            id = event.response.id
        if event.sequence_number == 10:
            break

# Later...
with client.responses.stream(response_id=id, starting_after=10) as stream:
    for event in stream:
        ...
    response = stream.get_final_response()

7. Data Flow Summary

flowchart TB
    subgraph CLIENT["Client"]
        A["HTTP POST /v1/responses<br/>{ stream: true }"]
    end
    subgraph PROXY["HTTP Transport"]
        B["Content-Type: text/event-stream<br/>chunked transfer"]
    end
    subgraph PARSE["SSE Parser"]
        C["SSEDecoder<br/>- buffers \n\n chunks<br/>- parses event:/data:"]
    end
    subgraph DISP["Type Dispatch"]
        D["construct_type()<br/>via type discriminator"]
    end
    subgraph ACC["Accumulator"]
        E["ResponseStreamState<br/>- maintains snapshot<br/>- adds snapshot/parsed"]
    end
    subgraph USER["User"]
        F["for event in stream:"]
    end
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

8. Wire-Level Example (Synthetic)

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"queued","created_at":1718000000,"model":"gpt-4o","output":[],"tools":[],"tool_choice":"auto","parallel_tool_calls":true,"top_p":1,"temperature":1},"sequence_number":0}

data: {"type":"response.queued","response":{"id":"resp_abc123",...},"sequence_number":1}

data: {"type":"response.in_progress","response":{"id":"resp_abc123","status":"in_progress",...},"sequence_number":2}

data: {"type":"response.output_item.added","output_index":0,"item":{"id":"item_1","type":"message","role":"assistant","content":[],"status":"in_progress"},"sequence_number":3}

data: {"type":"response.content_part.added","output_index":0,"item_id":"item_1","content_index":0,"part":{"type":"output_text","text":"","annotations":[]},"sequence_number":4}

data: {"type":"response.output_text.delta","output_index":0,"item_id":"item_1","content_index":0,"delta":"Hello","sequence_number":5,"logprobs":[{"token":"Hello","logprob":-0.01}]}

data: {"type":"response.output_text.delta","output_index":0,"item_id":"item_1","content_index":0,"delta":" world","sequence_number":6,"logprobs":[...]}

data: {"type":"response.output_text.done","output_index":0,"item_id":"item_1","content_index":0,"text":"Hello world","sequence_number":7,"logprobs":[...]}

data: {"type":"response.content_part.done","output_index":0,"item_id":"item_1","content_index":0,"part":{"type":"output_text","text":"Hello world","annotations":[]},"sequence_number":8}

data: {"type":"response.output_item.done","output_index":0,"item":{"id":"item_1","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hello world","annotations":[]}],"status":"completed"},"sequence_number":9}

data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","output":[{"id":"item_1",...}],...},"sequence_number":10}

9. Implementation Reference (Key Files in SDK)

File	Purpose
src/openai/_streaming.py	Stream[T], AsyncStream[T], SSEDecoder, SSEBytesDecoder, `ServerSentEvent`
src/openai/_response.py	APIResponse, _parse() → constructs Stream[T]
src/openai/_base_client.py	request(), _process_response(), _process_response_data(), _make_sse_decoder(), make_request_options()
src/openai/types/responses/response_stream_event.py	`ResponseStreamEvent` discriminated union
src/openai/lib/streaming/responses/_responses.py	`ResponseStream`, `AsyncResponseStream`, `ResponseStreamManager`, `ResponseStreamState`
src/openai/lib/streaming/responses/_events.py	SDK-enhanced wrapper types + `ResponseStreamEvent` (lib version)
src/openai/resources/responses/responses.py	Responses.create(), Responses.stream(), WebSocket connection code

10. Event Taxonomy Diagram

graph LR
    subgraph LIFECYCLE["Response Lifecycle"]
        RC["response.created"] --> RQ["response.queued"]
        RQ --> RI["response.in_progress"]
        RI --> RC2["response.completed"]
        RI --> RF["response.failed"]
        RI --> RINC["response.incomplete"]
    end
    subgraph CONTENT["Content Delta"]
        OT["output_text.delta"] --> OTD["output_text.done"]
        OTD --> OTA["output_text.annotation"]
        RD["refusal.delta"] --> RD2["refusal.done"]
        AD["audio.delta"] --> ADD["audio.done"]
        ATD["audio.transcript.delta"] --> ATDD["audio.transcript.done"]
        RT["reasoning_text.delta"] --> RTD["reasoning_text.done"]
        RS["reasoning_summary_part<br/>reasoning_summary_text"]
    end
    subgraph STRUCT["Output Structure"]
        OIA["output_item.added"] --> OID["output_item.done"]
        CPA["content_part.added"] --> CPD["content_part.done"]
    end
    subgraph IMAGE["Image Generation"]
        IGI["image_gen_call.in_progress"] --> IGG["image_gen_call.generating"]
        IGG --> IGP["image_gen_call.partial_image"]
        IGP --> IGC["image_gen_call.completed"]
    end
    subgraph TOOLS["Tool Calls"]
        FC["function_call_arguments.delta/done"]
        MCP["mcp_call.* (8 events)"]
        WS["web_search_call.* (3 events)"]
        FS["file_search_call.* (3 events)"]
        CI["code_interpreter_call.* (5 events)"]
        CT["custom_tool_call_input.delta/done"]
    end
    LIFECYCLE --> CONTENT
    LIFECYCLE --> STRUCT
    LIFECYCLE --> TOOLS
    LIFECYCLE --> IMAGE

Pro tip: The SDK docstrings only document response.created. Use the type definitions from src/openai/types/responses/response_<name>_event.py as the canonical source. Every event has the type literal (matching the type field in the JSON), sequence_number: int, and event-specific fields.

OpenAI Responses API SSE 리버싱 노트

Sat, 20 Jun 2026 00:00:00 GMT

OpenAI Responses API — SSE 스트리밍 내부 구조

출처: OpenAI Python SDK openai-python (Stainless 생성) 범위: SSE (Server-Sent Events)만 다룸. WebSocket 모드 제외. 마지막 업데이트: 2026-06-20

1. 상위 수준 아키텍처

flowchart TB
    subgraph User["User Code"]
        A["client.responses.create(stream=True)"]
    end
    subgraph HTTP["HTTP Layer"]
        B["POST /v1/responses<br/>Accept: text/event-stream<br/>body: { ..., 'stream': true }"]
    end
    subgraph SSE["SSE Decoding"]
        C["httpx.Response (청크 전송)"]
        D["Stream[ResponseStreamEvent]"]
        E["SSEDecoder.iter_bytes()"]
        F["ServerSentEvent.json()"]
        G["construct_type(discriminator='type')"]
    end
    subgraph Wrapper["SDK Wrapper"]
        H["ResponseStreamState"]
        I["ResponseStream (이터레이터)"]
    end
    A --> B --> C --> D
    C --> E --> F --> G --> D
    D --> H --> I

또는 편의 API 사용:

with client.responses.stream(input="...", model="gpt-4o") as stream:
    for event in stream:
        ...

내부적으로 ResponseStreamManager → ResponseStream을 사용한다.

2. SSE 와이어 포맷

Assistants API(이벤트명 thread.message.delta 등으로 구분)와 달리, Responses API는 JSON 페이로드 내부에 type 필드로 이벤트 타입을 구분한다.

각 SSE 청크는 다음과 같다:

data: {"type":"response.created","response":{...},"sequence_number":0}

data: {"type":"response.in_progress","response":{...},"sequence_number":1}

data: {"type":"response.output_item.added","output_index":0,"item":{...},"sequence_number":2}

data: {"type":"response.content_part.added","output_index":0,"item_id":"...","content_index":0,"part":{...},"sequence_number":3}

data: {"type":"response.output_text.delta","output_index":0,"item_id":"...","content_index":0,"delta":"Hello","sequence_number":4}
...

Responses API SSE 이벤트에는 event: 라인이 설정되지 않는다.
JSON 본문 내부의 type 필드가 구분자(discriminator) 역할을 한다.
모든 이벤트에는 순서 보장용 sequence_number: int가 있다.
스트림은 연결 종료 시 끝난다(Responses에는 [DONE] 센티넬이 없음. Stream._iter_events의 [DONE] 체크는 레거시 Chat Completions 전용).

3. 전체 이벤트 목록 (53종)

3.1 Response 생명주기 이벤트

#	`type` 값	클래스	필드
1	`response.created`	`ResponseCreatedEvent`	`response: Response`, `sequence_number: int`
2	`response.queued`	`ResponseQueuedEvent`	`response: Response`, `sequence_number: int`
3	`response.in_progress`	`ResponseInProgressEvent`	`response: Response`, `sequence_number: int`
4	`response.completed`	`ResponseCompletedEvent`	`response: Response`, `sequence_number: int`
5	`response.failed`	`ResponseFailedEvent`	`response: Response`, `sequence_number: int`
6	`response.incomplete`	`ResponseIncompleteEvent`	`response: Response`, `sequence_number: int`
7	`error`	`ResponseErrorEvent`	`code: Optional[str]`, `message: str`, `param: Optional[str]`, `sequence_number: int`

3.2 출력 항목 — 구조적

#	`type` 값	클래스	필드
8	`response.output_item.added`	`ResponseOutputItemAddedEvent`	`item: ResponseOutputItem`, `output_index: int`, `sequence_number: int`
9	`response.output_item.done`	`ResponseOutputItemDoneEvent`	`item: ResponseOutputItem`, `output_index: int`, `sequence_number: int`
10	`response.content_part.added`	`ResponseContentPartAddedEvent`	`part: Part`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
11	`response.content_part.done`	`ResponseContentPartDoneEvent`	`part: Part`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`

Part는 다음 중 하나의 구분된 유니온:

ResponseOutputText (type=output_text)
ResponseOutputRefusal (type=refusal)
PartReasoningText (type=reasoning_text)

3.3 텍스트 콘텐츠

#	`type` 값	클래스	필드
12	`response.output_text.delta`	`ResponseTextDeltaEvent`	`delta: str`, `content_index: int`, `item_id: str`, `output_index: int`, `logprobs: List[Logprob]`, `sequence_number: int`
13	`response.output_text.done`	`ResponseTextDoneEvent`	`text: str`, `content_index: int`, `item_id: str`, `output_index: int`, `logprobs: List[Logprob]`, `sequence_number: int`
14	`response.output_text.annotation.added`	`ResponseOutputTextAnnotationAddedEvent`	`annotation: object`, `annotation_index: int`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
logprob 구조:

class Logprob:
    token: str
    logprob: float
    top_logprobs: Optional[List[LogprobTopLogprob]]  # 최대 20개 대안

class LogprobTopLogprob:
    token: Optional[str]
    logprob: Optional[float]

3.4 거절(Refusal)

#	`type` 값	클래스	필드
15	`response.refusal.delta`	`ResponseRefusalDeltaEvent`	`delta: str`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
16	`response.refusal.done`	`ResponseRefusalDoneEvent`	`refusal: str`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`

3.5 함수 호출(Function Calling)

#	`type` 값	클래스	필드
17	`response.function_call_arguments.delta`	`ResponseFunctionCallArgumentsDeltaEvent`	`delta: str`, `item_id: str`, `output_index: int`, `sequence_number: int`
18	`response.function_call_arguments.done`	`ResponseFunctionCallArgumentsDoneEvent`	`arguments: str`, `name: str`, `item_id: str`, `output_index: int`, `sequence_number: int`

3.6 MCP (Model Context Protocol)

#	`type` 값	클래스	필드
19	`response.mcp_call.in_progress`	`ResponseMcpCallInProgressEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
20	`response.mcp_call_arguments.delta`	`ResponseMcpCallArgumentsDeltaEvent`	`delta: str` (JSON 부분), `item_id: str`, `output_index: int`, `sequence_number: int`
21	`response.mcp_call_arguments.done`	`ResponseMcpCallArgumentsDoneEvent`	`arguments: str` (JSON 전체), `item_id: str`, `output_index: int`, `sequence_number: int`
22	`response.mcp_call.completed`	`ResponseMcpCallCompletedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
23	`response.mcp_call.failed`	`ResponseMcpCallFailedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
24	`response.mcp_list_tools.in_progress`	`ResponseMcpListToolsInProgressEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
25	`response.mcp_list_tools.completed`	`ResponseMcpListToolsCompletedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
26	`response.mcp_list_tools.failed`	`ResponseMcpListToolsFailedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`

3.7 오디오

#	`type` 값	클래스	필드
27	`response.audio.delta`	`ResponseAudioDeltaEvent`	`delta: str` (Base64 오디오 바이트), `sequence_number: int`
28	`response.audio.done`	`ResponseAudioDoneEvent`	`sequence_number: int`
29	`response.audio.transcript.delta`	`ResponseAudioTranscriptDeltaEvent`	`delta: str`, `sequence_number: int`
30	`response.audio.transcript.done`	`ResponseAudioTranscriptDoneEvent`	`sequence_number: int`

3.8 웹 검색 도구

#	`type` 값	클래스	필드
31	`response.web_search_call.in_progress`	`ResponseWebSearchCallInProgressEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
32	`response.web_search_call.searching`	`ResponseWebSearchCallSearchingEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
33	`response.web_search_call.completed`	`ResponseWebSearchCallCompletedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`

3.9 파일 검색 도구

#	`type` 값	클래스	필드
34	`response.file_search_call.in_progress`	`ResponseFileSearchCallInProgressEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
35	`response.file_search_call.searching`	`ResponseFileSearchCallSearchingEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
36	`response.file_search_call.completed`	`ResponseFileSearchCallCompletedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`

3.10 코드 인터프리터 도구

#	`type` 값	클래스	필드
37	`response.code_interpreter_call.in_progress`	`ResponseCodeInterpreterCallInProgressEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
38	`response.code_interpreter_call.interpreting`	`ResponseCodeInterpreterCallInterpretingEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
39	`response.code_interpreter_call_code.delta`	`ResponseCodeInterpreterCallCodeDeltaEvent`	`delta: str`, `item_id: str`, `output_index: int`, `sequence_number: int`
40	`response.code_interpreter_call_code.done`	`ResponseCodeInterpreterCallCodeDoneEvent`	`code: str`, `item_id: str`, `output_index: int`, `sequence_number: int`
41	`response.code_interpreter_call.completed`	`ResponseCodeInterpreterCallCompletedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`

3.11 추론(Reasoning)

#	`type` 값	클래스	필드
42	`response.reasoning_text.delta`	`ResponseReasoningTextDeltaEvent`	`delta: str`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
43	`response.reasoning_text.done`	`ResponseReasoningTextDoneEvent`	`text: str`, `content_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
44	`response.reasoning_summary_part.added`	`ResponseReasoningSummaryPartAddedEvent`	`part: Part` (summary_text), `summary_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
45	`response.reasoning_summary_part.done`	`ResponseReasoningSummaryPartDoneEvent`	`part: Part` (summary_text), `summary_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
46	`response.reasoning_summary_text.delta`	`ResponseReasoningSummaryTextDeltaEvent`	`delta: str`, `summary_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`
47	`response.reasoning_summary_text.done`	`ResponseReasoningSummaryTextDoneEvent`	`text: str`, `summary_index: int`, `item_id: str`, `output_index: int`, `sequence_number: int`

3.12 이미지 생성

#	`type` 값	클래스	필드
48	`response.image_generation_call.in_progress`	`ResponseImageGenCallInProgressEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
49	`response.image_generation_call.generating`	`ResponseImageGenCallGeneratingEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`
50	`response.image_generation_call.partial_image`	`ResponseImageGenCallPartialImageEvent`	`partial_image_b64: str`, `partial_image_index: int` (0부터 시작), `item_id: str`, `output_index: int`, `sequence_number: int`
51	`response.image_generation_call.completed`	`ResponseImageGenCallCompletedEvent`	`item_id: str`, `output_index: int`, `sequence_number: int`

3.13 사용자 정의 도구 호출

#	`type` 값	클래스	필드
52	`response.custom_tool_call_input.delta`	`ResponseCustomToolCallInputDeltaEvent`	`delta: str`, `item_id: str`, `output_index: int`, `sequence_number: int`
53	`response.custom_tool_call_input.done`	`ResponseCustomToolCallInputDoneEvent`	`input: str`, `item_id: str`, `output_index: int`, `sequence_number: int`

4. SSE 파싱 파이프라인 (와이어 → 타입화된 이벤트)

flowchart LR
    subgraph Wire["HTTP Wire"]
        A["httpx.Response<br/>iter_bytes()"]
    end
    subgraph Decoder["SSE Decoder"]
        B["SSEDecoder.decode(line)<br/>RFC 8895"]
        C["ServerSentEvent<br/>.data = JSON 문자열"]
    end
    subgraph Dispatch["Type Dispatch"]
        D["construct_type()<br/>discriminator='type'"]
    end
    subgraph Output["Output"]
        E["ResponseCreatedEvent |<br/>ResponseTextDeltaEvent |<br/>... (53개 타입화된 모델)"]
    end
    A -- 바이트 --> B -- SSE 라인 --> C -- .json() dict --> D --> E

디코더 주요 상세

SSEDecoder는 빈 줄(\n\n, \r\r, \r\n\r\n)을 만날 때까지 라인을 누적한다.
각 SSE 필드(event:, data:, id:, retry:)는 스펙에 따라 처리된다.
Responses API에서는 event: 필드가 없으므로 ServerSentEvent.event는 None이다.
원본 JSON data:는 역직렬화되어 construct_type()에 전달된다.
ResponseStreamEvent는 Annotated[Union[...], PropertyInfo(discriminator="type")]이므로, construct_type이 "type" 키를 확인하여 올바른 서브클래스로 디스패치한다.

5. SDK 편의 API: ResponseStream / ResponseStreamState

5.1 ResponseStreamManager (진입점)

사용법:

with client.responses.stream(
    input="Hello", model="gpt-4o"
) as stream:  # ResponseStream[TextFormatT] 반환
    for event in stream:
        ...

매니저는:

client.responses.create(stream=True, ...)를 호출하여 원본 Stream[ResponseStreamEvent]를 얻는다.
ResponseStream(raw_stream=..., text_format=..., input_tools=...)으로 래핑한다.
ResponseStreamEvent[TextFormatT]의 이터레이터로 노출한다.

5.2 ResponseStream → ResponseStreamState

ResponseStream.__stream__()은 각 원본 이벤트를 ResponseStreamState.handle_event(sse_event)에 위임한다.

**handle_event()**는 각 원본 SSE 이벤트에 대해 1~2개의 이벤트를 생성:

원본 SSE `type`	방출되는 이벤트
`response.output_text.delta`	`ResponseTextDeltaEvent` (`snapshot` 필드 추가 — 지금까지 누적된 텍스트)
`response.output_text.done`	`ResponseTextDoneEvent` (`parsed` 필드, `text_format` 설정 시)
`response.function_call_arguments.delta`	`ResponseFunctionCallArgumentsDeltaEvent` (`snapshot` — 지금까지 누적된 인자)
`response.completed`	`ResponseCompletedEvent` (`response`가 완전히 파싱된 `ParsedResponse`)
그 외	그대로 통과

5.3 accumulate_event() — 상태 머신

ResponseStreamState는 __current_snapshot (부분 ParsedResponse)을 유지한다:

response.created → event.response에서 초기 스냅샷 생성
response.output_item.added → snapshot.output[]에 항목 추가 (function_call, message, 일반 타입 처리)
response.content_part.added → 인덱싱된 출력 메시지에 콘텐츠 파트 추가
response.output_text.delta → 일치하는 output_text 콘텐츠의 텍스트에 delta 연결
response.function_call_arguments.delta → 일치하는 함수 호출의 인자에 delta 연결
response.completed → parse_response()로 완전히 파싱된 response 저장 (구조화된 출력 파싱 포함)

5.4 편의 메서드

stream.get_final_response() → 스트림 전체를 소비하고 누적된 ParsedResponse 반환
stream.until_done() → 스트림이 완전히 소비될 때까지 블로킹
stream.close() → 내부 httpx response 종료

5.5 ResponseStreamEvent[TextFormatT] (SDK 래퍼 타입)

다음은 원본 생성 타입을 서브클래싱하거나 추가 필드로 래핑한다:

원본 타입	SDK 래퍼	추가 필드
`ResponseTextDeltaEvent`	`lib.streaming.responses.ResponseTextDeltaEvent`	`snapshot: str` (누적 텍스트)
`ResponseTextDoneEvent`	`lib.streaming.responses.ResponseTextDoneEvent`	`parsed: Optional[TextFormatT]`
`ResponseFunctionCallArgumentsDeltaEvent`	`lib.streaming.responses.ResponseFunctionCallArgumentsDeltaEvent`	`snapshot: str` (누적 인자)
`ResponseCompletedEvent`	`lib.streaming.responses.ResponseCompletedEvent`	`response: ParsedResponse[TextFormatT]`

스트림이 사용하는 복합 ResponseStreamEvent 타입 별칭:

ResponseStreamEvent = Annotated[Union[
    ResponseTextDeltaEvent,       # SDK 래퍼
    ResponseTextDoneEvent,        # SDK 래퍼
    ResponseFunctionCallArgumentsDeltaEvent,  # SDK 래퍼
    ResponseCompletedEvent,       # SDK 래퍼
    ResponseAudioDeltaEvent,      # 원본
    ... (그 외 모든 원본 이벤트)    # 원본
], PropertyInfo(discriminator="type")]

6. 백그라운드 모드 스트리밍

responses.stream()에 background=True를 전달하면:

API 요청에 "background": true가 포함된다.
서버는 즉시 response.created 이벤트로 response id를 반환한다.
스트림은 열린 상태로 유지되며, 백그라운드 처리 진행에 따라 비동기적으로 이벤트를 전달한다.
스트림을 중단하고 재개할 수 있다: response.created에서 response_id를 기록한 후, 나중에 responses.stream(response_id=id, starting_after=N)을 호출하여 시퀀스 번호 N부터 재개한다.

사용 패턴:

with client.responses.stream(input="...", model="gpt-4o", background=True) as stream:
    for event in stream:
        if event.type == "response.created":
            id = event.response.id
        if event.sequence_number == 10:
            break

# 나중에...
with client.responses.stream(response_id=id, starting_after=10) as stream:
    for event in stream:
        ...
    response = stream.get_final_response()

7. 데이터 흐름 요약

flowchart TB
    subgraph HTTP["HTTP Layer"]
        A["HTTP POST /v1/responses<br/>{ stream: true }<br/>Content-Type: text/event-stream"]
    end
    subgraph SSE["SSE Decoder"]
        B["SSEDecoder<br/>빈 줄 단위 버퍼링<br/>event:/data: 파싱"]
    end
    subgraph Stream["Stream Layer"]
        C["Stream[ResponseStreamEvent]<br/>construct_type() 디스패치<br/>'type' discriminator 사용"]
    end
    subgraph Accumulator["Accumulator"]
        D["ResponseStreamState<br/>스냅샷 유지<br/>snapshot/parsed 추가"]
    end
    subgraph User["User Code"]
        E["for event in stream:"]
    end
    A --> B --> C --> D --> E

8. 와이어 레벨 예시 (합성)

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"queued","created_at":1718000000,"model":"gpt-4o","output":[],"tools":[],"tool_choice":"auto","parallel_tool_calls":true,"top_p":1,"temperature":1},"sequence_number":0}

data: {"type":"response.queued","response":{"id":"resp_abc123",...},"sequence_number":1}

data: {"type":"response.in_progress","response":{"id":"resp_abc123","status":"in_progress",...},"sequence_number":2}

data: {"type":"response.output_item.added","output_index":0,"item":{"id":"item_1","type":"message","role":"assistant","content":[],"status":"in_progress"},"sequence_number":3}

data: {"type":"response.content_part.added","output_index":0,"item_id":"item_1","content_index":0,"part":{"type":"output_text","text":"","annotations":[]},"sequence_number":4}

data: {"type":"response.output_text.delta","output_index":0,"item_id":"item_1","content_index":0,"delta":"Hello","sequence_number":5,"logprobs":[{"token":"Hello","logprob":-0.01}]}

data: {"type":"response.output_text.delta","output_index":0,"item_id":"item_1","content_index":0,"delta":" world","sequence_number":6,"logprobs":[...]}

data: {"type":"response.output_text.done","output_index":0,"item_id":"item_1","content_index":0,"text":"Hello world","sequence_number":7,"logprobs":[...]}

data: {"type":"response.content_part.done","output_index":0,"item_id":"item_1","content_index":0,"part":{"type":"output_text","text":"Hello world","annotations":[]},"sequence_number":8}

data: {"type":"response.output_item.done","output_index":0,"item":{"id":"item_1","type":"message","role":"assistant","content":[{"type":"output_text","text":"Hello world","annotations":[]}],"status":"completed"},"sequence_number":9}

data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","output":[{"id":"item_1",...}],...},"sequence_number":10}

9. 구현 참조 (SDK 주요 파일)

파일	목적
`src/openai/_streaming.py`	`Stream[T]`, `AsyncStream[T]`, `SSEDecoder`, `SSEBytesDecoder`, `ServerSentEvent`
`src/openai/_response.py`	`APIResponse`, `_parse()` → `Stream[T]` 생성
`src/openai/_base_client.py`	`request()`, `_process_response()`, `_process_response_data()`, `_make_sse_decoder()`, `make_request_options()`
`src/openai/types/responses/response_stream_event.py`	`ResponseStreamEvent` 구분된 유니온
`src/openai/lib/streaming/responses/_responses.py`	`ResponseStream`, `AsyncResponseStream`, `ResponseStreamManager`, `ResponseStreamState`
`src/openai/lib/streaming/responses/_events.py`	SDK 확장 래퍼 타입 + `ResponseStreamEvent` (라이브러리 버전)
`src/openai/resources/responses/responses.py`	`Responses.create()`, `Responses.stream()`, WebSocket 연결 코드

10. 이벤트 분류 다이어그램

mindmap
  root(("Responses API SSE 이벤트<br/>(53종)"))
    생명주기
      response.created
      response.queued
      response.in_progress
      response.completed
      response.failed
      response.incomplete
      error
    출력 구조
      output_item.added
      output_item.done
      content_part.added
      content_part.done
    텍스트 콘텐츠
      output_text.delta
      output_text.done
      output_text.annotation.added
      refusal.delta
      refusal.done
    함수 호출
      function_call_arguments.delta
      function_call_arguments.done
    MCP
      mcp_call.in_progress
      mcp_call_arguments.delta
      mcp_call_arguments.done
      mcp_call.completed
      mcp_call.failed
      mcp_list_tools.in_progress
      mcp_list_tools.completed
      mcp_list_tools.failed
    오디오
      audio.delta
      audio.done
      audio.transcript.delta
      audio.transcript.done
    웹 검색
      web_search_call.in_progress
      web_search_call.searching
      web_search_call.completed
    파일 검색
      file_search_call.in_progress
      file_search_call.searching
      file_search_call.completed
    코드 인터프리터
      code_interpreter_call.in_progress
      code_interpreter_call.interpreting
      code_interpreter_call_code.delta
      code_interpreter_call_code.done
      code_interpreter_call.completed
    추론
      reasoning_text.delta
      reasoning_text.done
      reasoning_summary_part.added
      reasoning_summary_part.done
      reasoning_summary_text.delta
      reasoning_summary_text.done
    이미지 생성
      image_generation_call.in_progress
      image_generation_call.generating
      image_generation_call.partial_image
      image_generation_call.completed
    사용자 정의 도구 호출
      custom_tool_call_input.delta
      custom_tool_call_input.done

팁: SDK docstring에는 response.created만 문서화되어 있다. src/openai/types/responses/response_<name>_event.py의 타입 정의를 정식 출처로 사용하라. 모든 이벤트에는 type 리터럴(JSON의 type 필드와 일치), sequence_number: int, 그리고 이벤트별 필드가 있다.

Alice2 리버싱 노트

Wed, 10 Jun 2026 00:00:00 GMT

Alice 2 - Jython 상호운용성 계층

분석 목적: Alice 2(JAVA)에 내장된 Jython 스크립팅 시스템의 전체 구조와 유저 접점. 분석 기준: TheAliceProject/alice2 소스 코드 + Alice 2.6.1 배포본 직접 분석. 마지막 업데이트: 2026-06-10

아키텍처 개요

flowchart TD
    AT["Alice 2 저작 도구<br/>(JAlice.java)"] -->|생성| W["World"]
    W -->|소유| SF["ScriptingFactory<br/>Jython 초기화, alice 패키지 로드"]
    W -->|소유| I["Interpreter<br/>월드별 Jython 엔진"]
    I -->|소유| NS["Namespace<br/>PyStringMap 서브클래스"]
    NS -->|이름 조회| WE["PyElement / PySandbox<br/>Alice 객체 프록시"]
    W -->|소유| SP["ScriptProperty<br/>캐싱 + .py 저장"]
    W -->|소유| SR["ScriptResponse<br/>매 프레임 EXEC_MULTIPLE"]
    W -->|소유| SDR["ScriptDefinedResponse<br/>프롤로그에서 EVAL"]

    subgraph UF["4가지 사용자 입력면"]
        S1["1. Sandbox Script<br/>우클릭 → Edit Script"]
        S2["2. ScriptResponse 블록<br/>드래그앤드롭 → 텍스트 입력"]
        S3["3. ScriptDefinedResponse 블록<br/>드래그앤드롭 → Response 표현식"]
        S4["4. ScriptComboWidget + ScratchPad<br/>하단 툴바 즉시 실행"]
    end

    S1 -->|"World.start() 시"| I
    S2 -->|"매 프레임 update(t)"| I
    S3 -->|"프롤로그(t) 평가"| I
    S4 -->|"유저 클릭 실행"| I
    I -->|"Py.exec / Py.eval"| JR["Jython 런타임"]
    JR -->|"__finditem__"| NS
    JR -->|"alice.* 함수"| PK["alice Python 패키지<br/>(Required/jython/Lib/alice/)"]
    PK -->|Java 상호운용| SF

⚠️ 중요: Script 기능 동작 안 함 (Alice 2.6.1)

소스 코드 분석 결과, Interpreter.java의 Py.compile_flags 호출 시 마지막 인자가 null로 전달되어 Jython 2.7.3에서 NPE가 발생. 이로 인해 모든 Script 기반 기능(Sandbox Script, ScriptResponse, ScriptDefinedResponse, ComboWidget, ScratchPad)이 실행되지 않음. 블록 기반 편집만 정상 작동.

읽기 가이드

전체 구조부터 보고 싶다?
  → 01-architecture.md     (Jython 부트스트랩, CompileType, World.start())
  → 05-behind-the-scenes.md (Java 클래스 전체 인벤토리)

이름이 어떻게 Alice 오브젝트에 연결되는지 궁금하다?
  → 02-name-resolution.md  (Namespace → PyElement 전 과정, PySandbox 변수 쓰기)

유저 입장에서 뭘 입력해야 하는지 알고 싶다?
  → 03-script-surfaces.md  (4가지 입력면 + 동작 안 함 확인)

API가 궁금하다?
  → 04-api-reference.md    (alice.* 함수 전수 + 버그 목록)

월드 파일을 뜯어보고 싶다?
  → 06-file-format-a2w.md  (a2w ZIP 구조, 저장/로드)
  → 07-file-format-a2c.md  (a2c 갤러리 오브젝트)
  → 08-element-data-xml.md (elementData.xml 스키마)
  → 09-storing-scripts.md   (ScriptProperty, .py 파일 저장)

블록이 어떻게 생성되는지 알고 싶다?
  → 10-drag-and-drop.md    (팔레트 → ResponsePrototype → Element)

실전 문제 해결이 필요하다?
  → 11-troubleshooting.md  (로딩 실패, 폰트, 변수, a2w 직접 수정)

문서 목록

#	파일	내용	분량
01	`01-architecture.md`	Jython 부트스트랩, World.start(), ScriptResponse/ScriptDefinedResponse	중
02	`02-name-resolution.md`	Namespace → PyElement 전체 체인, PySandbox 변수 할당	중
03	`03-script-surfaces.md`	유저 중심: 4가지 입력면 UI + 실행 시점	★ 많음
04	`04-api-reference.md`	alice.* API 전수, 발견된 버그 3건	중
05	`05-behind-the-scenes.md`	Java 클래스 계층, s_classnameMap, 호출 체인	중
06	`06-file-format-a2w.md`	a2w ZIP 내부, 저장/로드 플로우	중
07	`07-file-format-a2c.md`	a2c 갤러리 오브젝트 포맷	소
08	`08-element-data-xml.md`	elementData.xml 스키마 전수	중
09	`09-storing-scripts.md`	ScriptProperty, .py 저장, 4가지 입력면 저장 비교	중
10	`10-drag-and-drop.md`	팔레트 → ResponsePrototype → Element 인스턴스화	많음
11	`11-troubleshooting.md`	실전 문제: 로딩 실패, 폰트, 변수, a2w 직접 수정	중

빠른 참조

# Script의 API 참조 — 실제로는 동작하지 않지만 구조는 이렇다

import alice

# 이름으로 접근 가능한 객체
bunny.color = alice.red
bunny.opacity = 0.5

# 애니메이션 함수
alice.MoveAnimation(subject=bunny, direction=alice.forward, amount=2, duration=2)
alice.SayAnimation(subject=bunny, what="Hello!")

# 제어 흐름
alice.DoInOrder(
    alice.MoveAnimation(subject=bunny, amount=1, duration=1),
    alice.TurnAnimation(subject=bunny, direction=alice.left, amount=0.25),
)

# 센서
if alice.keyboard.isKeyPressed(alice.keyboard.VK_SPACE):
    print("Space pressed!")

주요 발견 사항 요약

발견 사항	근거	상태
Jython 2.7.3 null cflags NPE	`Interpreter.java` 56번째 줄 `null`	Script 전면 불가
HideAction = ShowAction	`animations.py` 702-703, 둘 다 `isShowing=true`	버그
IfElseInOrder elseAnimation 무시	`animations.py` 162-173, `#todo`로 남음	미구현
LoopNInOrder = None	`animations.py` 184-185	미구현
SoundAction 클래스로 저장 시 로드 실패	`s_classnameMap`에 매핑 없음	호환성 문제
Text3D / SayAnimation 한글 미지원	Alice 2.6.1 폰트	환경 제약

01 - 아키텍처 및 부트스트랩

Alice 2가 Jython을 기동하고 World에 스크립팅 레이어를 연결하는 전체 과정. 분석 기준: alice2 소스 + Alice 2.6.1 배포본.

1. Jython 부트스트랩 순서

sequenceDiagram
    participant JVM as JVM
    participant SF as ScriptingFactory<br/>(jython.ScriptingFactory)
    participant JY as Jython 런타임
    participant AT as 저작 도구
    participant W as World
    participant I as Interpreter

    JVM->>SF: new ScriptingFactory()
    SF->>JY: PySystemState.initialize(preProperties, ...)
    Note over SF,JY: python.home = Required/jython/
    SF->>JY: alice/__init__.py 읽기 및 컴파일
    SF->>JY: Py.exec(code, builtins, builtins)
    Note over SF,JY: alice.* 이름을 builtins에 주입<br/>(전체 alice를 모든 Interpreter가 공유)

    AT->>W: new World()
    AT->>W: setScriptingFactory(SF)
    W->>SF: manufactureInterpreter()
    SF-->>I: new Interpreter(this)
    I->>I: new Namespace() + new PyModule("main", dict)
    W->>I: setWorld(this)
    I->>I: Namespace.setWorld(world) → clear() + setWorld()

주요 포인트

alice/__init__.py가 builtins 네임스페이스에 로드된다 — 모든 alice.* 이름이 모든 인터프리터에서 바로 사용 가능
ScriptingFactory는 인터프리터 풀을 관리한다 (Vector<Interpreter>)
alice/__init__.py → animations.py, constants.py, linearalgebra.py 전부 임포트
JVM 속성: -Dpython.home=jython -Dpython.path=jython/Lib/alice

2. World 레벨 실행 체인

flowchart LR
    E["Element.compile(script, source, type)"] --> EW["getWorld().compile(...)"]
    EW --> WI["getInterpreter().compile(...)"]
    WI --> PY["Py.compile_flags(script, pathname, CompileMode, flags)"]
    PY --> JC["jython.Code(PyCode, CompileType)"]

    E2["Element.eval(code)"] --> EW2["getWorld().eval(code)"]
    EW2 --> WI2["getInterpreter().eval(code)"]
    WI2 --> PYE["Py.eval(code.getPyCode(), ns, ns)"]

    E3["Element.exec(code)"] --> EW3["getWorld().exec(code)"]
    EW3 --> WI3["getInterpreter().exec(code)"]
    WI3 --> PYX["Py.exec(code.getPyCode(), ns, ns)"]

실제 Java 구현

// Element.java
public Code compile(String script, Object source, CompileType compileType) {
    return getWorld().compile(script, source, compileType);
}
public Object eval(Code code) {
    return getWorld().eval(code);
}
public void exec(Code code) {
    getWorld().exec(code);
}

// World.java
public Code compile(String script, Object source, CompileType compileType) {
    return getInterpreter().compile(script, source, compileType);
}
public Object eval(Code code) {
    return getInterpreter().eval(code);
}
public void exec(Code code) {
    getInterpreter().exec(code);
}

3. CompileType 3종

CompileType	Jython CompileMode	특징	사용처
`EVAL`	`CompileMode.eval`	단일 표현식 평가, 결과 반환	ScriptDefinedResponse
`EXEC_SINGLE`	`CompileMode.single`	단일 구문 실행	ScriptComboWidget (Go 버튼)
`EXEC_MULTIPLE`	`CompileMode.exec`	여러 구문 실행	ScriptResponse, Sandbox Script, ScratchPad

4. World.start() — 실제 코드로 보는 실행 흐름

// World.java
public void start() {
    if (m_scriptingFactory != null) {
        getInterpreter().start();                     // Namespace 리셋
        Code code = script.getCode(EXEC_MULTIPLE);   // World.script Property → 컴파일
        if (code != null) exec(code);                 // Sandbox Script 1회 실행
    }
    bubbles.clear();
    started(this, m_clock.getTime());
    m_isRunning = true;
}

public void schedule() {
    m_currentSandbox = this;
    scheduleBehaviors(m_clock.getTime());             // 매 프레임 behavior 실행
    m_collisions = m_collisionManager.update(256);
    m_currentSandbox = null;
}

sequenceDiagram
    participant U as 유저가 Play 클릭
    participant W as World
    participant I as Interpreter
    participant NS as Namespace
    participant JB as Jython
    participant WOBJ as Alice 객체들

    U->>W: start()
    W->>I: start()
    I->>NS: resetNamespace() → clear() + setWorld()
    W->>W: script.getCode(EXEC_MULTIPLE)
    W->>I: exec(code)
    I->>JB: Py.exec(pyCode, ns, ns)
    JB->>NS: __finditem__("bunny")
    NS->>NS: 로컬에도 없고, 월드 이름도 아님
    NS->>WOBJ: m_pyWorld.__findattr__("bunny")
    WOBJ-->>NS: PyElement(bunny)
    NS-->>JB: PyElement
    JB->>PyElement: bunny.color = red
    PyElement->>WOBJ: property.set(red)

    loop 매 프레임
        W->>W: schedule()
        W->>W: scheduleBehaviors(t)
        Note over W: 모든 Sandbox behavior 실행
    end

5. ScriptResponse와 ScriptDefinedResponse

classDiagram
    class Response {
        +ScriptProperty script
        +manufactureRuntimeResponse()
    }
    class ScriptResponse {
        +update(t): exec(script, EXEC_MULTIPLE)
    }
    class ScriptDefinedResponse {
        +prologue(t): eval(script, EVAL)
        -m_actual: RuntimeResponse
        +update(t): m_actual.update(t)
        +getTimeRemaining(t): m_actual.getTimeRemaining(t)
    }
    class RuntimeResponse {
        +prologue(t)
        +update(t)
        +epilogue(t)
    }

    Response <|-- ScriptResponse
    Response <|-- ScriptDefinedResponse
    ScriptDefinedResponse --> RuntimeResponse : m_actual에 위임

ScriptResponse (실제 코드)

// ScriptResponse.java
public class RuntimeScriptResponse extends RuntimeResponse {
    public void update(double t) {
        super.update(t);
        ScriptResponse.this.exec(
            ScriptResponse.this.script.getCode(CompileType.EXEC_MULTIPLE));
    }
}

ScriptDefinedResponse (실제 코드)

// ScriptDefinedResponse.java
public void prologue(double t) {
    super.prologue(t);
    m_actual = null;
    Object o = ScriptDefinedResponse.this.eval(
        ScriptDefinedResponse.this.script.getCode(CompileType.EVAL));
    if (o instanceof Response) {
        m_actual = ((Response)o).manufactureRuntimeResponse();
        if (m_actual != null) m_actual.prologue(t);
    } else {
        throw new RuntimeException("does not evaluate to a response: " + script);
    }
}

public void update(double t) {
    super.update(t);
    if (m_actual != null) m_actual.update(t);
}

	ScriptResponse	ScriptDefinedResponse
CompileType	EXEC_MULTIPLE	EVAL
실행 시기	매 프레임 `update(t)`	`prologue(t)`에서 1회
요구사항	아무 Python 코드	`Response` 객체 반환 필수
지속 시간	0 (고정)	위임받은 response에 따름
용도	반복/연속 동작	Python으로 애니메이션 동적 구성

ScriptDefinedResponse 예

# 이 코드는 반드시 Response 객체를 반환해야 한다
alice.DoInOrder(
    alice.MoveAnimation(subject=bunny, amount=1, duration=1),
    alice.TurnAnimation(subject=bunny, direction=alice.left, amount=0.25),
)

6. ⚠️ 발견된 문제: Jython 2.7.3 null cflags (실제 코드 분석 결과)

현상

Alice 2.6.1에서 Script 기반 기능들이 런타임에 NPE로 크래시난다.

원인 (소스 코드 확인 완료)

// Interpreter.java (jython/Interpreter.java, line 56)
public Code compile(String script, Object source, CompileType compileType) {
    PyCode pyCode = Py.compile_flags(
        script, source.toString(), compileType.getMode(),
        null    // ← Jython 2.7.3의 ParserFacade.prepBufReader()가 이 null을 못 받음
    );
    return new Code(pyCode, compileType);
}

참고: ScriptingFactory.java에서는 같은 API를 올바르게 호출함:

PyCode code = Py.compile_flags(script, pathname, CompileMode.exec,
    Py.getCompilerFlags());  // ← flags를 제대로 전달

영향받는 기능

기능	결과
Sandbox Script (Edit Script)	World.start() 시점에 NPE
ScriptResponse 블록	update() 시점에 NPE
ScriptDefinedResponse 블록	prologue() 시점에 NPE
ScriptComboWidget (Go)	컴파일 시점에 NPE
ScriptScratchPad (Perform All)	컴파일 시점에 NPE
드래그앤드롭 블록 전반	✅ 정상 작동 (Script 미사용)

현실적 영향

Script로 무언가를 하는 것은 Alice 2.6.1에서 불가능
alice/__init__.py와 animations.py에 정의된 Python API는 사용할 수 없음 (ScriptAction, MoveAnimation 등)
블록 기반 편집만 가능

02 - 이름 해석: Python 이름 → Alice 객체

스크립트에 bunny라고 쓰면 어떻게 Alice 월드의 오브젝트가 연결되는지 설명한다. ⚠️ 실제 코드 분석 기반 — PyElement.findattr_ex, PySandbox.setattr 전체 추적.

1. 전체 조회 체인

Namespace.__finditem__(key)는 다음 순서로 이름을 찾는다:

flowchart TD
    START["bunny.color = red"] --> NS["Namespace.__finditem__('bunny')"]
    NS --> C1["1. local PyStringMap 확인<br/>(Python local/global var)"]
    C1 -->|찾음| RET1["return PyObject"]
    C1 -->|없음| C2["2. 월드 이름과 일치?"]
    C2 -->|예| RETW["return m_pyWorld"]
    C2 -->|아니오| C3["3. World.lookup(key)"]
    C3 --> SB["Sandbox.lookup(key)"]
    SB --> STK["a. currentBehavior.stackLookup(key)<br/>(파라미터, 지역 변수)"]
    STK -->|찾음| REXPR["return Expression.getValue()"]
    STK -->|없음| DTL["b. currentBehavior.detailLookup(key)<br/>(behavior 속성)"]
    DTL -->|찾음| REXPR
    DTL -->|없음| C4["4. m_pyWorld.__findattr__('bunny')"]
    C4 --> PE["PyElement.__findattr_ex__('bunny')"]
    PE --> CH["a. getChildNamedIgnoreCase('bunny')"]
    CH -->|표현식 발견| CHVE["return expression.getValue()"]
    CH -->|element 발견| CHVN["return PyElement(descendant)"]
    CH -->|없음| PR["b. getPropertyNamedIgnoreCase('bunny')"]
    PR -->|찾음| PRV["return property.get()"]
    PR -->|없음| USCORE["c. name.startsWith('_')?"]
    USCORE -->|예| RETRY["이름[1:]로 재시도<br/>child → property → reflection"]
    USCORE -->|아니오| SUP["d. super.__findattr_ex__(name)<br/>(Java reflection fallback)"]

2. Java: Namespace.finditem (실제 코드)

// Namespace.java
public synchronized PyObject __finditem__(String key) {
    // 1. Python local/global variables
    PyObject py = super.__finditem__(key);
    if (py != null) return py;

    // 2. 월드 이름과 일치? → world 자체 반환
    if (key.equalsIgnoreCase(m_world.name.getStringValue())) {
        return m_pyWorld;
    }

    // 3. Sandbox.lookup() — behavior context (파라미터/지역변수)
    Expression expression = m_world.lookup(key);
    if (expression != null) {
        return java2py(expression.getValue());
    }

    // 4. 최종 fallback: world의 child/property lookup
    return m_pyWorld.__findattr__(key);
}

3. Sandbox.lookup() — Behavior Context (실제 코드)

// Sandbox.java
public Expression lookup(String key) {
    if (m_currentBehavior != null) {
        // a. behavior stack → parameters, local variables
        Expression e = m_currentBehavior.stackLookup(key);
        if (e != null) return e;

        // b. behavior detail properties
        return m_currentBehavior.detailLookup(key);
    }
    return null;
}

중요: 현재 실행 중인 Behavior의 지역변수/파라미터가 전역 오브젝트명보다 항상 우선한다. stackLookup → detailLookup 순서로 검색.

4. PyElement.findattr_ex — 속성 읽기 (실제 코드)

// PyElement.java
public PyObject __findattr_ex__(String name) {
    // 1. Child Element 검색 (대소문자 구분 없음)
    Element descendant = m_element.getChildNamedIgnoreCase(name);
    if (descendant == null) {
        // 2. Property 검색
        Property property = m_element.getPropertyNamedIgnoreCase(name);
        if (property == null) {
            // 3. 언더스코어 prefix → child 건너뛰고 재시도
            if (name.startsWith("_")) {
                descendant = m_element.getChildNamed(name.substring(1));
                if (descendant != null) return m_namespace.getPyElement(descendant);
                property = m_element.getPropertyNamedIgnoreCase(name.substring(1));
                if (property != null) return Py.java2py(property);
            }
            // 4. Java reflection fallback
            return super.__findattr_ex__(name);
        }
        return m_namespace.java2py(property.get());
    }
    // Child가 Expression이면 getValue(), 아니면 PyElement로 래핑
    Object value;
    if (descendant instanceof Expression) {
        value = ((Expression)descendant).getValue();
    } else {
        value = descendant;
    }
    return m_namespace.java2py(value);
}

sequenceDiagram
    participant Script
    participant NS as Namespace
    participant PE as PyElement
    participant Elem as Alice Element

    Script->>NS: __finditem__("bunny")
    NS->>PE: __findattr_ex__("bunny")
    PE->>Elem: getChildNamedIgnoreCase("bunny")
    Elem-->>PE: Element(bunny Transformable)
    Note over PE: descendant is not Expression
    PE-->>NS: PyElement(bunny)
    NS-->>Script: PyElement(bunny)

    Script->>PE: bunny.color (읽기)
    PE->>Elem: getPropertyNamedIgnoreCase("color")
    Elem-->>PE: Color property
    PE->>PE: property.get() -> Color.RED
    PE-->>Script: PyColor(RED)

    Script->>PE: bunny.color = alice.red (쓰기)
    PE->>Elem: getPropertyNamedIgnoreCase("color")
    Elem-->>PE: Color property
    PE->>Elem: property.set(attr.__tojava__(Color.class))

5. ⭐ PySandbox.setattr — 변수에 값 쓰기 (실제 코드)

// PySandbox.java
public void __setattr__(String name, PyObject attr) {
    // 우선 Sandbox.variables 배열에서 이름이 일치하는 변수 찾기
    for (int i = 0; i < getSandbox().variables.size(); i++) {
        Variable variable = (Variable)getSandbox().variables.get(i);
        if (name.equalsIgnoreCase(variable.name.getStringValue())) {
            // Alice UI 변수에 직접 값 설정!
            variable.value.set(attr.__tojava__(variable.getValueClass()));
            return;
        }
    }
    // 없으면 일반 PyElement.__setattr__ 위임
    super.__setattr__(name, attr);
}

이것이 의미하는 것

# Alice UI에서 만든 전역 변수 score가 있을 때:
score = 5  # ← PySandbox.__setattr__가 가로챔!
           # ← Sandbox.variables 중 "score"를 찾아 value.set(5)
           # ← Python dict에 "score"가 생기지 않음!

# Alice UI 변수가 없으면:
my_python_var = 42  # ← 일반 Python 변수 (Namespace dict에 저장)

유저 입장: Alice UI 변수는 할당으로 바로 값 변경 가능하다.

score = score + 1  # ✅ Alice 전역 변수 증가

6. PyElement.setattr — Property 쓰기 (실제 코드)

// PyElement.java
public void __setattr__(String name, PyObject attr) {
    Property property = m_element.getPropertyNamedIgnoreCase(name);
    if (property != null) {
        // Python → Java 타입 변환 후 Property.set()
        property.set(attr.__tojava__(property.getValueClass()));
    } else {
        super.__setattr__(name, attr);  // Python instance attribute
    }
}

7. 특수 구문

구문	의미	예제
`__UnnamedN__`	인덱스로 이름 없는 child 접근	`__Unnamed0__`
`/` 구분자	계층적 경로 (internalGetDescendantKeyed)	`world.bunny.leftLeg`
`_name` prefix	child 조회 건너뛰고 바로 property로	`_color` (child가 있어도 property로)

8. 전체 추적: `bunny.color = alice.red`

1. Jython이 "bunny.color = alice.red" 파싱
   → bunny 평가: Namespace.__finditem__("bunny")

2. Namespace.__finditem__("bunny")
   → local dict: 없음
   → world name: "world" 아님
   → World.lookup("bunny"): m_currentBehavior == null → null 반환
   → m_pyWorld.__findattr__("bunny")

3. PyElement.__findattr_ex__("bunny")
   → getChildNamedIgnoreCase("bunny") → Element(bunny)
   → descendant is not Expression
   → return PyElement(bunny)

4. Python: bunny.color = alice.red
   → PyElement.__setattr__("color", red_pyobj)

5. PyElement.__setattr__("color", PyObject(alice.red))
   → getPropertyNamedIgnoreCase("color") → ColorProperty
   → attr.__tojava__(Color.class) → Java Color.RED
   → property.set(Color.RED)

6. "alice.red" 해석:
   from edu.cmu.cs.stage3.alice.scenegraph import Color
   red = Color.RED   # Java static field from constants.py

9. ⭐ 키 포인트 요약

이름은 대소문자를 구분하지 않는다 (getChildNamedIgnoreCase, equalsIgnoreCase)
Behavior의 지역변수 > 전역 오브젝트명 (stackLookup 우선)
Alice UI 변수 = Python 할당 가능 (PySandbox.__setattr__가 가로챔)
_name prefix = child 우회 (같은 이름의 child와 property가 있을 때 유용)
__UnnamedN__ = 이름 없는 child 접근 (DefinedResponse 내부 구조 분석용)
/ 경로 = 계층적 접근 (world.bunny.leftLeg 가능)

03 - 스크립트 입력면: 코드를 작성하는 4가지 방법

Alice 2에서 스크립트를 입력하고 실행하는 4가지 방법을 유저 입장에서 설명한다. 각 입력면마다: UI 위치, 조작 단계, 실행되는 시점, 실제 예제, 주의사항. 분석 기준: alice2 source + Alice 2.6.1 배포본.

개요

flowchart TD
    ALICE["Alice 2 실행"] -->|world 선택| CM["오른쪽 클릭"]
    CM -->|enableScripting=true| ES["Edit Script 메뉴"]
    ES --> SES["ScriptEditor 창<br/>여러 줄 코드 입력"]
    SES -->|"World.start()시"| EXEC1["EXEC_MULTIPLE 1회 실행"]

    ALICE -->|ResponseEditor| PALL["블록 팔레트"]
    PALL -->|드래그| SR["ScriptResponse 블록"]
    SR --> SRIN["script 필드에 코드 입력"]
    SRIN -->|매 프레임| EXEC2["EXEC_MULTIPLE 실행"]

    PALL -->|드래그| SDR["ScriptDefinedResponse 블록"]
    SDR --> SDRIN["Response 반환 표현식 입력"]
    SDRIN -->|프롤로그 1회| EVAL["EVAL"]

    ALICE -->|하단 UI| CW["ComboWidget + ScratchPad"]
    CW -->|한 줄 입력 + Go| EXEC3["EXEC_SINGLE 즉시 실행"]
    CW -->|여러 줄 + Perform All| EXEC4["EXEC_MULTIPLE 즉시 실행"]

🚨 실행 불가 확인 (Alice 2.6.1)

소스 코드 분석 결과: Alice 2.6.1에서 모든 Script 기능이 Jython 2.7.3의 Py.compile_flags null cflags 문제로 런타임에 동작하지 않는다.

관련 파일: Interpreter.java 56번째 줄 — Py.compile_flags(script, source, mode, null) 마지막 인자가 null
ScriptingFactory.java에서 builtins 로딩할 때는 Py.getCompilerFlags()를 제대로 사용

입력면	시점	결과
Sandbox Script	World.start() 시	NPE
ScriptResponse	매 프레임 update()	NPE
ScriptDefinedResponse	prologue() 시	NPE
ScriptComboWidget	컴파일 시	NPE
ScriptScratchPad	컴파일 시	NPE

블록 기반 편집은 정상 작동한다.

입력면 1: Sandbox Script (Edit Script)

UI 위치와 조작

1. Alice 2 실행, 월드 선택
2. 월드 또는 샌드박스 오브젝트에서 오른쪽 클릭
3. 컨텍스트 메뉴에서 "edit script" 선택
4. ScriptEditor 창이 열림 (줄 번호 표시 + 일반 텍스트 편집기)
5. Python 코드 입력

참고: 이 메뉴는 enableScripting = true 설정일 때만 나타난다.

편집 대상 (소스 코드 확인)

// ElementPopupUtilities.java — EditScriptRunnable
public void run() {
    if (element instanceof Sandbox) {
        authoringTool.editObject(((Sandbox)element).script);
    }
}

편집 대상 = Sandbox.script (ScriptProperty). ZIP 내 /script.py에 저장됨.

실행 시점 (소스 코드 확인)

// World.java start()
public void start() {
    if (m_scriptingFactory != null) {
        getInterpreter().start();
        Code code = script.getCode(EXEC_MULTIPLE);  // World.script Property
        if (code != null) exec(code);               // Sandbox Script 1회 실행
    }
    // ...
}

sequenceDiagram
    participant User
    participant World
    participant Interp as Interpreter
    participant Sandbox

    User->>World: Play 버튼 클릭
    World->>Interp: start()
    Interp->>Interp: Namespace.reset() → clear() + setWorld()
    World->>World: script.getCode(EXEC_MULTIPLE)
    World->>Interp: exec(code)
    Note over Interp: Sandbox Script **한 번** 실행
    World->>World: schedule()
    loop 매 프레임
        World->>World: scheduleBehaviors(t)
        World->>Sandbox: sandbox.scheduleBehaviors(t)
    end

입력면 2: ScriptResponse 블록

UI 위치와 조작

1. ResponseEditor 열기 (오브젝트 더블클릭 또는 편집 메뉴)
2. 좌측 블록 팔레트에서 "script" 라벨이 붙은 블록 찾기
3. 블록을 드래그하여 DoInOrder 등의 ContainerResponse에 드롭
4. 생성된 ScriptResponse 블록을 클릭
5. 속성 패널에 "script" 텍스트 필드가 나타남
6. 여기에 Python 코드 입력

실행 방식 (소스 코드)

// ScriptResponse.java
public class RuntimeScriptResponse extends RuntimeResponse {
    public void update(double t) {
        super.update(t);
        ScriptResponse.this.exec(
            ScriptResponse.this.script.getCode(CompileType.EXEC_MULTIPLE));
    }
}

sequenceDiagram
    participant Sched as 스케줄러
    participant Resp as ScriptResponse
    participant ScriptProp as ScriptProperty
    participant Int as Interpreter

    Sched->>Resp: update(t)
    Resp->>ScriptProp: getCode(EXEC_MULTIPLE)
    ScriptProp->>ScriptProp: 캐시 미스? compile()
    ScriptProp-->>Resp: Code (캐시됨)
    Resp->>Int: exec(code)
    Note over Resp,Int: 매 프레임마다 실행됨!
    Int-->>Resp: 완료
    Sched->>Resp: 다음 update(t+dt) ...

입력면 3: ScriptDefinedResponse 블록

UI 위치와 조작

1. ResponseEditor 열기
2. 팔레트에서 "script defined" 라벨 블록 찾기
3. ContainerResponse에 드롭
4. 블록 클릭 → "script" 속성 필드
5. 여기에 Response 객체를 반환하는 Python 표현식 입력

실행 방식 (소스 코드)

// ScriptDefinedResponse.java
public void prologue(double t) {
    super.prologue(t);
    m_actual = null;
    Object o = ScriptDefinedResponse.this.eval(
        ScriptDefinedResponse.this.script.getCode(CompileType.EVAL));
    if (o instanceof Response) {
        m_actual = ((Response)o).manufactureRuntimeResponse();
        if (m_actual != null) m_actual.prologue(t);
    } else {
        throw new RuntimeException("does not evaluate to a response: " + script);
    }
}

sequenceDiagram
    participant Sched as 스케줄러
    participant SDR as ScriptDefinedResponse
    participant Int as Interpreter
    participant Deleg as 위임받은 RuntimeResponse

    Sched->>SDR: prologue(t0)
    SDR->>Int: eval(code) -- EVAL 모드
    Int-->>SDR: Response 객체 (예: DoInOrder)
    SDR->>Deleg: manufactureRuntimeResponse()
    SDR->>Deleg: prologue(t0)

    loop 매 프레임
        Sched->>SDR: update(t)
        SDR->>Deleg: update(t)
    end

    Sched->>SDR: epilogue(tN)
    SDR->>Deleg: epilogue(tN)

입력면 4: ScriptComboWidget + ScriptScratchPad

UI 위치

Alice 하단 툴바 영역:

┌──────────────────────────────────────────────────────┐
│ [  입력 + 히스토리(콤보박스)        ] [ Go 버튼 ]    │  ← ScriptComboWidget
├──────────────────────────────────────────────────────┤
│ [  Perform All (Ctrl+F4) ] [ Perform Selected (F4) ] │  ← ScriptScratchPad 버튼
├──────────────────────────────────────────────────────┤
│ Scratch Pad (임시 편집기)                             │
│ ┌──────────────────────────────────────────────────┐ │
│ │                                                  │ │
│ │  여러 줄 입력 가능                                │ │
│ │                                                  │ │
│ └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

입력면 4a: ScriptComboWidget (Go)

// ScriptComboWidget.java
public void runScript() {
    String script = ((String)comboBox.getEditor().getItem()).trim();
    if (script.length() != 0) {
        Code code = sandbox.compile(script, "<Run Line>", EXEC_SINGLE);
        sandbox.exec(code);
        comboBox.insertItemAt(script, 0);
    }
}

한 줄 입력 → Go 또는 Enter → EXEC_SINGLE
실행 후 히스토리에 저장 (재선택 가능)
저장되지 않음 (휘발성)

입력면 4b: ScriptScratchPad (Perform All / Perform Selected)

// ScriptEditorPane.java
// Perform All (Ctrl+F4)
script = ScriptEditorPane.this.getText();
code = sandbox.compile(script, "<ScriptEditorPane>", EXEC_MULTIPLE);
sandbox.exec(code);

// Perform Selected (F4)
int selStart = getLineStartOffset(getLineOfOffset(getSelectionStart()));
int selEnd = getLineEndOffset(getLineOfOffset(getSelectionEnd()));
script = getText(selStart, selEnd - selStart);
code = sandbox.compile(script, "<ScriptEditorPane>", EXEC_MULTIPLE);
sandbox.exec(code);

저장되지 않음 (휘발성)
영구 저장 필요 시 Sandbox Script 또는 ScriptResponse 블록으로 이전 필요

입력면 5: ResponseEditor 팔레트 블록

팔레트 블록	Response 클래스	스크립트 필요?
Do in order	`DoInOrder`	하위 블록 필요
Do together	`DoTogether`	하위 블록 필요
Loop (N times)	`LoopNInOrder`	end/increment
If/Else	`IfElseInOrder`	condition
While	`WhileLoopInOrder`	condition
For each in order	`ForEachInOrder`	list
For all together	`ForEachTogether`	list
Script	`ScriptResponse`	script 필드
Script defined	`ScriptDefinedResponse`	script 필드
Wait	`Wait`	duration
Comment	`Comment`	(실행 안 됨)
Print	`Print`	text

저장/휘발 구분

편집 위치	a2w 내 저장 위치	지속성
Edit Script	`/script.py`	✅ 저장
ScriptResponse 블록	`/.../script.py`	✅ 저장
ScriptDefinedResponse 블록	`/.../script.py`	✅ 저장
ScriptComboWidget	메모리	❌ 휘발
ScriptScratchPad	메모리	❌ 휘발

04 - API 참조: `alice` Python 패키지

Required/jython/Lib/alice/ 아래 4개 파일이 제공하는 모든 함수와 상수. 분석 기준: Alice 2.6.1 배포본의 실제 .py 파일.

패키지 구조

Required/jython/Lib/alice/
  __init__.py        - 임포트, Keyboard, Mouse, Clock, copy(), exportToObj()
  animations.py      - 모든 애니메이션 + 제어 흐름 함수
  constants.py       - 색상, 방향, 스타일, HowMuch
  linearalgebra.py   - Vec3, dot(), cross()
  pinchgloves.py     - Pinch Gloves 하드웨어 연동 (직렬 COM 포트)

상수 (`constants.py`)

방향

Name	Java Source
`left`	`Direction.LEFT`
`right`	`Direction.RIGHT`
`up`	`Direction.UP`
`down`	`Direction.DOWN`
`forward`	`Direction.FORWARD`
`back` / `backward`	`Direction.BACKWARD`

차원

Name	Java Source
`leftToRight`	`Dimension.LEFT_TO_RIGHT`
`topToBottom`	`Dimension.TOP_TO_BOTTOM`
`frontToBack`	`Dimension.FRONT_TO_BACK`
`all`	`Dimension.ALL`

HowMuch (실행 범위)

Name	의미
`instance`	이 Element만
`instanceAndParts`	Element + parts
`instanceAndAllDescendants`	Element + 모든 하위 요소

애니메이션 스타일 (이징)

Name	Java Source	설명
`abruptly`	`LINEAR`	이징 없음
`beginGently`	`SLOW_IN`	시작만 느리게
`endGently`	`SLOW_OUT`	끝만 느리게
`gently`	`SLOW_IN_OUT`	시작과 끝 모두 느리게 (기본값)

색상

edu.cmu.cs.stage3.alice.scenegraph.Color의 static 필드:

Color
`red`	`pink`	`orange`	`yellow`
`green`	`blue`	`purple`	`brown`
`white`	`lightGray`	`gray`	`darkGray`
`black`	`cyan`	`magenta`

채우기 / 쉐이딩 스타일

Name	설명
`solid` / `wireframe` / `points`	채우기 스타일
`noShading` / `flatShading` / `smoothShading`	쉐이딩 스타일

공간 관계

선형대수 (`linearalgebra.py`)

v = alice.Vec3(1, 2, 3)
v2 = alice.Vec3(4, 5, 6)
v + v2       # Vec3(5, 7, 9)
v * 2        # Vec3(2, 4, 6)
v.getLength()       # 3.74
alice.dot(v, v2)    # 32
alice.cross(v, v2)  # Vec3(-3, 6, -3)

센서 (`init.py`)

키보드

kb = alice.keyboard
kb.isKeyPressed(kb.VK_SPACE)   # 현재 키 상태
kb.getKeyNames()               # 키 이름 목록

모든 java.awt.event.KeyEvent.VK_* 상수 사용 가능: VK_SPACE, VK_ENTER, VK_A ... VK_Z, VK_0 ... VK_9

마우스

pos = alice.mouse.getLocation()  # → java.awt.Point

시계

t = alice.clock.getTime()  # → System.currentTimeMillis / 1000 (초)

애니메이션 함수 (`animations.py` — 실제 코드 기반)

이동

함수	설명
`MoveAnimation(subject, direction, amount, duration, asSeenBy, style, isScaledBySize)`	이동
`TurnAnimation(subject, direction, amount, duration, ...)`	회전 (앞/뒤/좌/우)
`RollAnimation(subject, direction, amount, ...)`	굴림 (좌/우)
`ResizeAnimation(subject, dimension, amount, likeRubber, ...)`	크기 조절
`PositionAnimation(subject, position, ...)`	절대 위치 설정
`QuaternionAnimation(subject, quaternion, ...)`	절대 회전 (쿼터니언)
`EulerAnglesAnimation(subject, pitchYawRoll, ...)`	절대 회전 (오일러)
`SizeAnimation(subject, size, ...)`	절대 크기 설정
`PointAtAnimation(subject, target, offset, upGuide, onlyAffectYaw, ...)`	타겟 지향
`PointOfViewAnimation(subject, pointOfView, ...)`	전체 자세 설정
`StandUpAnimation(subject, ...)`	월드 업 정렬
`PathAnimation(subject, pointOfViews, times, ...)`	키프레임 경로
`ForwardVectorAnimation(subject, forward, upGuide, ...)`	전방 벡터 설정

텍스처

함수	설명
`TextureMapAnimation(subject, textureMaps, framesPerSecond, ...)`	텍스처 플립북

속성 및 차량

함수	설명
`PropertyAnimation(element, propertyName, value, ...)`	모든 Property를 시간에 따라 애니메이션
`VehiclePropertyAnimation(element, vehicle)`	Vehicle 즉시 설정 (duration=0)

소리 및 표시

함수	설명
`SoundAction(sound, volumeLevel, wait)`	소리 재생 (내부적으로 SoundResponse 사용)
`ShowAction(element, howMuch, wait)`	isShowing = true
`HideAction(element, howMuch, wait)`	⚠️ 실제로는 isShowing = true (소스 확인 완료)
`SayAnimation(subject, what, ...)`	말풍선
`ThinkAnimation(subject, what, ...)`	생각풍선

제어 흐름

함수	설명
`DoInOrder(*animations, wait)`	순차 실행
`DoTogether(*animations, wait)`	병렬 실행
`ForEachInOrder(each, list, *animations, wait)`	순차 반복
`ForEachTogether(each, list, *animations, wait)`	병렬 반복
`IfElseInOrder(condition, ifAnimation, elseAnimation)`	⚠️ elseAnimation 미구현 (소스 확인 완료)
`WhileLoopInOrder(condition, *animations)`	While 루프
`LoopNInOrder(...)`	❌ None 반환 (미구현)
`WaitAction(duration)`	대기
`ScriptAction(fcn_or_string, args, kwargs)`	Python 함수를 Response로 래핑

기본 파라미터 패턴

def AnimFunc(subject, ..., duration=1, style=gently, wait=0):

모든 파라미터에 callable 전달 가능 (ApplyQuestion으로 자동 래핑)
wait=1이면 DoInOrder 내에서 블로킹
subject, direction, amount 등 전부 callable 지원

⚠️ animations.py에서 발견된 버그 (실제 코드 분석)

버그 1: HideAction = ShowAction

# animations.py 699-703
def ShowAction(element, howMuch=instanceAndParts, wait=0):
    return PropertyAnimation(element, "isShowing", true, duration=0, ...)

def HideAction(element, howMuch=instanceAndParts, wait=0):
    return PropertyAnimation(element, "isShowing", true, duration=0, ...)  # ← false여야 함

두 함수가 완전히 동일. HideAction을 호출해도 isShowing = true로 설정됨.

버그 2: IfElseInOrder가 elseAnimation 미처리

# animations.py 162-173
def IfElseInOrder(condition, ifAnimation, elseAnimation=None):
    a = IfElseInOrder()
    a.addComponentResponse(ifAnimation)
    #todo          ← elseAnimation 파라미터를 전혀 사용하지 않음
    ...

elseAnimation 파라미터는 받지만 내부적으로 무시됨.

버그 3: LoopNInOrder = None

# animations.py 184-185
def LoopNInOrder(*args):
    return None

구현 자체가 없음.

고급: ScriptAction

def ScriptAction(fcn, args=(), kws={}):
    if type(fcn) == str:
        # 문자열 → ScriptResponse (매 프레임 실행)
        sr = ScriptResponse()
        sr.script.set(fcn)
        return sr
    else:
        # Callable → ApplyResponse (1회 호출)
        return ApplyResponse(fcn, args, kws)

고급: ApplyQuestion (동적 파라미터)

모든 animation 함수는 callable 파라미터를 자동으로 ApplyQuestion으로 래핑:

alice.MoveAnimation(
    subject=bunny,
    amount=lambda: alice.random.random() * 5,
)

유틸리티 함수

alice.copy(src, name="bunny2")              # 깊은 복사
alice.exportToObj(model, "bunny.obj")       # OBJ 내보내기
alice.ManufactureEach([bunny, snowman])     # ForEach 용 Variable

Pinch Gloves (`pinchgloves.py`)

import pinchgloves
pinchgloves.AddPinchResponse(
    (pinchgloves.LEFT_THUMB, pinchgloves.LEFT_INDEX),
    on_pinch_callback, on_release_callback,
)
pinchgloves.SetDefaultPort("COM1")
pinchgloves.Start()

05 - 내부 구조: Java 클래스 참조

Alice 2의 Jython 스크립팅 시스템을 구성하는 Java 클래스 전체 맵. 분석 기준: alice2 source 전체 트레이스.

클래스 계층

classDiagram
    class ScriptingFactory {
        <<interface>>
        +manufactureInterpreter()
        +getInterpreters()
        +setStdOut(OutputStream)
        +setStdErr(OutputStream)
    }
    class Interpreter {
        <<interface>>
        +setWorld(World)
        +start()/stop()
        +compile(String, Object, CompileType) Code
        +eval(Code) Object
        +exec(Code)
    }
    class Code {
        <<interface>>
        +getCompileType() CompileType
    }
    class CompileType {
        <<interface>>
        +EVAL / EXEC_SINGLE / EXEC_MULTIPLE
        +getMode() CompileMode
    }

    class jython_ScriptingFactory {
        +ScriptingFactory()
        -m_interpreters: Vector
    }
    class jython_Interpreter {
        -m_module: PyModule
        -m_dict: Namespace
        -m_world: World
    }
    class jython_Code {
        -m_pyCode: PyCode
        -m_compileType: CompileType
    }
    class Namespace {
        -m_world: World
        -m_pyWorld: PyElement
        -m_map: Hashtable
        +__finditem__(String) PyObject
        +java2py(Object) PyObject
    }
    class PyElement {
        -m_element: Element
        -m_namespace: Namespace
        +__findattr_ex__(String) PyObject
        +__setattr__(String, PyObject)
    }
    class PySandbox {
        +__setattr__(String, PyObject)
    }

    ScriptingFactory <|.. jython_ScriptingFactory
    Interpreter <|.. jython_Interpreter
    Code <|.. jython_Code
    jython_Interpreter --> Namespace : 소유
    Namespace --> PyElement : 생성
    PyElement <|-- PySandbox

Java 파일 인벤토리

Scripting API (인터페이스)

경로: src/main/java/edu/cmu/cs/stage3/alice/scripting/

파일	역할
`ScriptingFactory.java`	인터프리터 생성/해제, I/O 리디렉션
`Interpreter.java`	compile, eval, exec, start, stop
`Code.java`	컴파일된 스크립트 핸들
`CompileType.java`	EVAL / EXEC_SINGLE / EXEC_MULTIPLE

Jython 구현

경로: src/main/java/edu/cmu/cs/stage3/alice/scripting/jython/

파일	역할	특징
`ScriptingFactory.java`	Jython 초기화: PySystemState.initialize, alice/init.py 로드	builtins에 로드
`Interpreter.java`	compile: Py.compile_flags → 마지막 인자 null	⚠️ NPE 원인
`Code.java`	PyCode + CompileType 래핑
`Namespace.java`	PyStringMap 상속, 4단계 이름 해석	java2py로 Element → PyElement 변환
`PyElement.java`	PyInstance 상속, findattr_ex 4단계	child → property → _prefix → reflection
`PySandbox.java`	PyElement 상속, setattr 오버라이드	변수명 일치 시 variable.value.set()

Alice Core 통합

경로: src/main/java/edu/cmu/cs/stage3/alice/core/

파일	역할
`World.java`	ScriptingFactory 소유, compile/eval/exec 위임, start()에서 script 1회 실행
`Element.java`	compile/eval/exec을 getWorld()로 위임, getChildNamedIgnoreCase / getPropertyNamedIgnoreCase
`Sandbox.java`	ScriptProperty 보유, behavior 스케줄, lookup() 이름 해석

경로: src/main/java/edu/cmu/cs/stage3/alice/core/property/

파일	역할
`ScriptProperty.java`	StringProperty 상속, Code 캐싱, .py 파일 저장/로드

경로: src/main/java/edu/cmu/cs/stage3/alice/core/responses/

파일	역할
`ScriptResponse.java`	update(t) → exec(EXEC_MULTIPLE) 매 프레임
`ScriptDefinedResponse.java`	prologue(t) → eval(EVAL), 위임 패턴

저작 도구 (UI)

경로: src/main/java/edu/cmu/cs/stage3/alice/authoringtool/

파일	역할
`editors/scripteditor/ScriptEditor.java`	ScriptEditor 전체
`util/ScriptEditorPane.java`	Perform All/Selected, undo/redo
`util/ScriptScratchPad.java`	임시 메모장
`util/ScriptComboWidget.java`	한 줄 실행 콤보박스
`util/ElementPopupUtilities.java`	EditScriptRunnable

Element.s_classnameMap (전체 목록)

Element.java static initializer에서 확인된 클래스명 매핑 (이전 버전 → 현재):

// 이름이 바뀐 Response 클래스들
ConditionalLoopSequentialResponse → WhileLoopInOrder
ConditionalSequentialResponse    → IfElseInOrder
CountLoopSequentialResponse      → LoopNInOrder
ForEachInListSequentialResponse  → ForEach
OrientationAnimation             → ForwardVectorAnimation
ParallelForEachInListSequentialResponse → ForEachTogether
ParallelResponse                 → DoTogether
ProxyForScriptDefinedResponse    → ScriptDefinedResponse
SequentialForEachInListSequentialResponse → ForEachInOrder
SequentialResponse               → DoInOrder
MetaResponse                     → CallToUserDefinedResponse

// 내비게이션
KeyboardNavigationBehavior → KeyboardNavigationBehavior
MouseNavigationBehavior    → MouseLookingBehavior

// 포즈
Pose        → Pose
PoseAnimation → PoseAnimation
KeyMapping  → KeyMapping

⚠️ 없는 매핑 (참고)

edu.cmu.cs.stage3.alice.core.responses.SoundAction → ??? (없음)

a2w 파일에 SoundAction 클래스명으로 저장된 Response가 있으면 로드 실패. 직접 ZIP을 열어 elementData.xml을 수정하거나 Alice UI에서 블록을 다시 설정해야 함.

코드 실행 체인 요약

블록/Python 코드 → ScriptProperty.getCode()
  → owner.compile(script, owner, compileType)
    → World.compile()
      → Interpreter.compile()
        → Py.compile_flags(script, path, mode, flags) → PyCode
      → new Code(PyCode, CompileType)
    → Code 반환
  → Code 캐싱 (m_code)
→ exec(code) / eval(code)
  → World.exec() → Interpreter.exec()
    → Py.exec(pyCode, ns, ns) / __builtin__.eval(pyCode, ns, ns)

Alice 2 - a2w 파일 포맷 (World)

대상: Alice 2 World 파일 (.a2w)의 내부 구조와 저장/로드 메커니즘 출처: Element.java, AuthoringTool.java, ZipTreeStorer.java, ZipFileTreeStorer.java 마지막 업데이트: 2026-06-09

1. ZIP Archive 개요

a2w 파일은 ZIP archive다. 매직 바이트 PK\x03\x04로 시작하며, 기본적으로 Deflate 압축.

구분	값
매직 시그니처	`50 4B 03 04` (PK\x03\x04)
기본 압축	Deflate (java.util.zip)
로더 클래스	`ZipTreeLoader` / `ZipFileTreeLoader`
스토러 클래스	`ZipTreeStorer` (순차) / `ZipFileTreeStorer` (in-place)
World 확장자	`.a2w`

2. a2w ZIP 내부 파일 목록

실제 default_English.a2w 분석 결과:

flowchart TD
    subgraph ZIP["world.a2w (ZIP Archive)"]
        EH["elementCountHint.txt - 진행률 힌트"]
        TN["thumbnail.png - 120x90 미리보기"]
        SP["script.py - World Sandbox script"]
        EX["elementData.xml - 루트 World 직렬화"]
        CAM["camera/"]
        LIT["light/"]
        GRD["ground/ + __ita__/ + texture/"]
        BEH["behavior0/ + __Unnamed0__/ + __Unnamed1__/"]
        MET["my first method/"]
    end
    EH --> LOAD["Element.load()"]
    SP --- EX
    EX --> CAM & LIT & GRD & BEH & MET
    style SP fill:#ff0,stroke:#a80
    style EX fill:#aef,stroke:#08a

elementCountHint.txt

로딩 프로그레스바용 힌트. 한 줄 정수.

없어도 로딩에 지장 없음 (FileNotFoundException 무시)

thumbnail.png

120x90 PNG. 조건부 저장 (config.saveThumbnailWithWorld).

script.py

World의 Sandbox.script 프로퍼티의 외부 파일.

저장: ScriptProperty.encodeObject() > script.py 생성
로드: ScriptProperty.decodeObject() > script.py 읽어 set()
자세한 내용: 09-storing-scripts.md

elementData.xml

각 Element 하나당 하나씩 존재하는 XML 직렬화.

자세한 스키마: 08-element-data-xml.md

하위 디렉토리 규칙

종류	디렉토리명	예
named child	`child.name` 값	`camera`, `my first method`
unnamed child	`__UnnamedN__` (0-indexed)	`__Unnamed0__`, `__Unnamed1__`

3. World 저장 (Store) Flow

sequenceDiagram
    participant User as 유저
    participant AT as AuthoringTool
    participant ST as ZipFileTreeStorer
    participant EL as World (Element)
    participant SP as ScriptProperty

    User->>AT: Ctrl+S / Save World
    AT->>AT: saveWorldToFile(file)
    AT->>AT: fireWorldSaving, saveTabs, saveCount
    AT->>AT: thumbnail 생성 (설정 시)
    AT->>ST: open(file) / parse central dir
    ST->>EL: world.store(storer, observer, map)
    EL->>EL: elementCountHint.txt 쓰기
    EL->>EL: thumbnail.png 등 map 쓰기
    EL->>EL: internalStore() 재귀
    loop 각 child
        EL->>ST: createDir + setCurrentDir
        EL->>EL: child.internalStore() 재귀
    end
    SP->>ST: getKeepKey -> create or keep script.py
    EL->>ST: write elementData.xml
    AT->>ST: close() - delete, reorder, write CD

4. World 로드 (Load) Flow

sequenceDiagram
    participant AT as AuthoringTool
    participant LD as ZipFileTreeLoader
    participant EL as Element
    participant SP as ScriptProperty

    AT->>LD: new ZipFileTreeLoader().open(file)
    LD->>LD: read all entries to memory
    AT->>EL: Element.load(loader, externalRoot, observer)
    EL->>EL: read elementCountHint.txt
    EL->>EL: parse elementData.xml -> Class.forName -> instantiate
    SP->>SP: decodeObject -> read script.py -> set()
    loop 각 <child>
        EL->>EL: setCurrentDir -> recursive load -> addChild
    end
    EL->>EL: ReferenceResolver.resolve()
    AT-->>User: World loaded

5. ZIP 스토러 비교

특성	ZipTreeStorer	ZipFileTreeStorer
쓰기 방식	순차 ZipOutputStream	RandomAccessFile
in-place	❌	✅
getKeepKey	null	파일 기반
사용처	a2c (갤러리)	a2w (World)

6. 주요 포인트

a2w = Element 트리 -> ZIP 디렉토리 1:1 매핑
각 Element = elementData.xml 하나
스크립트 = ScriptProperty에 의해 별도 .py 파일로 분리 저장
Keep file 메커니즘으로 변경된 부분만 재기록
로드/저장 모두 재귀적 (internalStore() / 재귀 load())

Alice 2 - a2c 파일 포맷 (캐릭터/갤러리 오브젝트)

대상: Alice 2 Character/Gallery Object 파일 (.a2c)의 내부 구조 출처: TheAliceProject/alice2 - LocalGalleryObject.java, GalleryViewer.java 마지막 업데이트: 2026-06-09

1. a2c 개요

a2c 파일도 a2w와 동일하게 ZIP archive다. 차이점은:

용도: 갤러리에 표시되는 캐릭터/오브젝트/씬 조각
편집 가능?: a2c는 읽기 전용 (갤러리에서 드래그하여 월드로 가져오기만 가능)
저장 방식: ZipTreeStorer (순차 쓰기, 새 파일 생성)
필수 파일: elementData.xml, galleryData.xml, thumbnail.png

2. a2c ZIP 내부 구조

아래는 실제 BumperCars.a2c의 구조다.

flowchart TD
    subgraph ZIP["Bopper.a2c (ZIP Archive)"]
        EH["elementCountHint.txt\n3\n"]
        GD["galleryData.xml\n⭐ 갤러리 메타데이터"]
        TN["thumbnail.png\n갤러리 썸네일"]
        EX["elementData.xml\nModel (Bopper) 직렬화"]
        ITA["__ita__/\n  ├ elementData.xml\n  ├ indices.bin\n  └ vertices.bin"]
        MAT["Material #2_CL/\n  ├ elementData.xml\n  └ image.png"]
    end

    GD -->|갤러리 표시용| GV[GalleryViewer]
    EX -->|오브젝트 데이터| LOAD["Element.load()"]

    style GD fill:#fda,stroke:#a60

3. galleryData.xml

a2w와의 가장 큰 차이점은 galleryData.xml이 존재한다는 것이다.

<?xml version="1.0" encoding="UTF-8"?>
<model>
    <name>bumperCars</name>
    <parts>3</parts>
    <physicalsize>29.95m x 6.2m x 31.29m</physicalsize>
    <methods/>
    <questions/>
    <sounds/>
</model>

태그	의미
`<name>`	갤러리에 표시할 이름
`<parts>`	구성 파트 수 (계층에서 분리 가능한 자식 Model 수)
`<physicalsize>`	물리적 크기 (미터 단위)
`<methods>`	노출할 메서드 목록
`<questions>`	노출할 질문(Question) 목록
`<sounds>`	포함된 사운드 목록

갤러리에서 a2c를 드래그하여 월드에 놓으면, Alice는 elementData.xml을 로드하여 Model 인스턴스를 생성하고, galleryData.xml의 정보는 GalleryViewer UI에 표시되는 용도로만 사용된다.

4. elementData.xml (a2c 버전)

a2c의 루트 Element는 World가 아니라 Model 이다.

<?xml version="1.0" encoding="UTF-8"?>
<element class="edu.cmu.cs.stage3.alice.core.Model"
    modelName="Bopper" name="bopper" version="2.2">
    <child filename="__ita__"/>
    <child filename="Material #2_CL"/>
    <property name="color"><red>1.0</red><green>1.0</green><blue>1.0</blue><alpha>1.0</alpha></property>
    <property class="java.lang.Double" name="opacity">1.0</property>
</element>

특징	a2w (World)	a2c (Character)
루트 클래스	`World`	`Model`
`galleryData.xml`	없음	있음
`script.py`	있음 (빈 파일)	없음
`thumbnail.png`	옵션 (설정)	필수
저장 시 스토러	`ZipFileTreeStorer` (in-place)	`ZipTreeStorer` (순차)
편집 가능	✅	❌

5. a2c가 갤러리에서 동작하는 방식

Alice 실행 > GalleryViewer가 Required/gallery/ 디렉토리 스캔
각 .a2c 파일에 대해 LocalGalleryObject 생성
thumbnail.png - 썸네일, galleryData.xml - 이름/크기/파트 수 표시
사용자가 드래그하여 월드에 가져올 때: Element.load(a2cFile, externalRoot) > Model 인스턴스 생성
"Save Character"는 원본 a2c를 변경하지 않고 새 .a2c를 만듦

6. a2c와 스크립트

a2c 자체에는 Alice UI에서 직접 코드를 추가할 수 없다. 하지만 월드로 가져온 후에는 일반 World 오브젝트처럼 취급되므로 ScriptResponse 블록 등으로 Script를 작성할 수 있다.

# 월드에 가져온 bopper 조작
bopper.color = alice.red
alice.MoveAnimation(subject=bopper, direction=alice.forward, amount=1)

Alice 2 - elementData.xml 스키마

대상: elementData.xml의 태그 구조와 Property 직렬화 규칙 출처: Element.java (internalStore / load), Property 하위 클래스들의 encode/decode 마지막 업데이트: 2026-06-09

1. 기본 구조

flowchart LR
    subgraph XML["elementData.xml"]
        ROOT["<element class=#quot;...#quot; name=#quot;...#quot; version=#quot;...#quot;>"]
        CHILD["<child filename=#quot;...#quot;/>"]
        PROP["<property name=#quot;...#quot;>...</property>"]
    end

    ROOT -->|0..n| CHILD
    ROOT -->|0..n| PROP
    CHILD -->|ZIP 하위 디렉토리| SUB["하위 elementData.xml"]
    PROP -->|Class.forName| FIELD["Element의 Property 필드"]
    PROP -->|encode/decode 위임| PROPCLS["Property 하위 클래스"]
    PROP -->|참조 해결| REF["ReferenceResolver"]

2. 루트 노드: <element>

<element class="edu.cmu.cs.stage3.alice.core.World" name="world" version="2.001">

속성	설명
`class`	Element의 FQCN (Fully Qualified Class Name)
`name`	Element의 `name` Property 값
`version`	파일 포맷 버전 (현재 `2.001` 또는 `2.2`)

class 매핑: Element.s_classnameMap에 오래된/별칭 클래스명을 최신 클래스로 매핑.

// Element.java static initializer
s_classnameMap.put("edu.cmu.cs.stage3.alice.core.responses.SequentialResponse",
    edu.cmu.cs.stage3.alice.core.responses.DoInOrder.class);
s_classnameMap.put("edu.cmu.cs.stage3.alice.core.responses.ProxyForScriptDefinedResponse",
    edu.cmu.cs.stage3.alice.core.responses.ScriptDefinedResponse.class);

3. 자식 노드: <child>

<child filename="camera"/>
<child filename="my first method"/>
<child filename="__Unnamed0__"/>

filename = ZIP 내 상대 디렉토리명, getRepr(i)로 결정
named child: child.name.getStringValue() = 디렉토리명
unnamed child: "__Unnamed" + i 형식

로드 시: setCurrentDirectory(filename) > 재귀 load > addChild > 복귀

4. Property 태그 종류

4.1 기본형 (primitive + String)

<property class="java.lang.Double" name="opacity">1.0</property>
<property class="java.lang.Boolean" name="isFirstClass">false</property>
<property name="name">world</property>

class 속성 생략 시 기본값 java.lang.String
name은 Element의 Property 필드명과 일치

4.2 Color

<property name="color">
    <red>1.0</red><green>1.0</green><blue>1.0</blue><alpha>1.0</alpha>
</property>

4.3 Matrix4 / visualScale

<property name="visualScale">
    <row><item>0.00512</item><item>0.0</item><item>0.0</item></row>
    <row><item>0.0</item><item>0.00512</item><item>0.0</item></row>
</property>

4x4 행렬 = <row> 4개, 각 <row>에 <item> 4개.

4.4 내부 참조 (Element 간 연결)

<property criterionClass="edu.cmu.cs.stage3.alice.core.criterion.InternalReferenceKeyedCriterion"
    name="userDefinedResponse"><![CDATA[my first method]]></property>

criterionClass = InternalReferenceKeyedCriterion
값 = target Element의 key (name)
로드 시: ReferenceResolver가 key로 target 검색

예 - behavior의 triggerResponse:

<property criterionClass="..."
    name="triggerResponse">behavior0.__Unnamed1__</property>

4.5 파일 참조 (ScriptProperty)

<property name="script">java.io.File[script.py]</property>

ScriptProperty의 외부 파일 참조. java.io.File[파일명] 형식
로드 시 파일명 추출 > ZIP에서 읽기
자세한 내용: 09-storing-scripts.md

4.6 Enum

<property class="edu.cmu.cs.stage3.alice.scenegraph.FillingStyle"
    name="fillingStyle">edu.cmu.cs.stage3.alice.scenegraph.FillingStyle[SOLID]</property>

PackagePath[ENUM_NAME] 형식.

4.7 Dictionary (data Property)

<property name="data">
    <entry>
        <key class="java.lang.String">edu.cmu.cs.stage3.alice.authoringtool.worldOpenTime</key>
        <value class="java.lang.String">1980594</value>
    </entry>
</property>

4.8 Array (responses, behaviors 등)

<property componentClass="edu.cmu.cs.stage3.alice.core.Response" name="responses">
    <item criterionClass="..."><![CDATA[my first method]]></item>
</property>

5. Element 클래스별 주요 Property

World (Sandbox)

Property	타입	설명
`script`	File 참조	월드 스크립트
`responses`	Array	실행 가능한 Response
`behaviors`	Array	등록된 Behavior
`variables`	Array	전역 변수
`questions`	Array	질문(Question)
`textureMaps`	Array	텍스처 맵
`data`	Dictionary	AuthoringTool 설정

Response (ScriptResponse, UserDefinedResponse 등)

Property	타입	설명
`script`	File 참조	ScriptProperty -> .py 파일
`duration`	Double	실행 지속 시간 (초)
`isCommentedOut`	Boolean	주석 처리 여부
`componentResponses`	Array	자식 Response들
`requiredFormalParameters`	Array	메서드 파라미터
`localVariables`	Array	지역 변수

Behavior (WorldStartBehavior, KeyEventBehavior 등)

Property	타입	설명
`isEnabled`	Boolean	활성화 여부 (기본 true)
`details`	Array	상세 정보 (키 코드 등)
`triggerResponse`	InternalReference	트리거할 Response
`multipleRuntimeResponsePolicy`	Enum	중복 실행 정책

Model

Property	타입	설명
`color`	Color	모델 색상
`opacity`	Double	불투명도
`fillingStyle`	Enum	채우기 스타일
`visualScale`	Matrix4	변환
`diffuseColorMap`	InternalReference	텍스처 참조

Variable

Property	타입	설명
`value`	Value (any)	변수 값
`valueClass`	Class	값의 Java 타입

변수 값 타입에 따라 XML 직렬화 방식이 달라짐:

숫자/문자열/Boolean: 인라인 값
오브젝트 참조: InternalReferenceKeyedCriterion

6. UserDefinedResponse 전체 예시

<?xml version="1.0" encoding="UTF-8"?>
<element
    class="edu.cmu.cs.stage3.alice.core.response.UserDefinedResponse"
    name="my first method" version="2.001">
    <property name="isFirstClass">false</property>
    <property name="data"/>
    <property name="isCommentedOut"/>
    <property name="duration"/>
    <property name="componentResponses"/>
    <property name="requiredFormalParameters"/>
    <property name="keywordFormalParameters"/>
    <property name="localVariables"/>
</element>

비어 있는 Property (null)는 빈 태그로 저장. Alice는 null을 "기본값 사용"으로 해석.

7. Property Encoding 위임 구조

Property 클래스	XML 저장 방식
`StringProperty`	텍스트 노드
`NumberProperty`	`class` 속성 + 텍스트 노드
`BooleanProperty`	`true` / `false`
`ColorProperty`	`<red>`/`<green>`/`<blue>`/`<alpha>`
`Matrix44Property`	`<row>`/`<item>`
`DictionaryProperty`	`<entry>`/`<key>`/`<value>`
`ElementArrayProperty`	`componentClass` + `<item>`
`ClassProperty`	FQCN 문자열
`EnumProperty`	`PackagePath[ENUM_NAME]`
`ScriptProperty`	`java.io.File[filename.py]`
`ValueProperty`	값 타입에 따라 적절한 방식 선택

Alice 2 - 스크립트가 파일에 저장/로드되는 방식

대상: ScriptProperty 직렬화 메커니즘과 4가지 스크립트 입력면의 저장 차이 출처: ScriptProperty.java, ScriptResponse.java, ScriptDefinedResponse.java 분석 기준: alice2 source + Alice 2.6.1 배포본.

1. ScriptProperty 개요

ScriptProperty는 StringProperty의 하위 클래스로, 문자열 스크립트를 별도의 .py 파일로 저장한다.

classDiagram
    class Property {
        +encode(Document, Node, Storer, ReferenceGenerator)
        +decode(Node, Loader, Vector, double)
    }
    class StringProperty {
        +String getStringValue()
    }
    class ScriptProperty {
        -Code m_code
        -Object m_associatedFileKey
        +getCode(CompileType) Code
        +encodeObject()
        +decodeObject()
        +loadScript(InputStream) String
        +storeScript(OutputStream)
        +keepAnyAssociatedFiles()
    }
    Property <|-- StringProperty
    StringProperty <|-- ScriptProperty

핵심 특징

기능	설명
`m_code` 캐시	Jython 컴파일 결과 캐시, `set()` 시 `null` 초기화
`m_associatedFileKey`	ZIP 내 .py 파일의 keep key (변경 감지용)
`getCode(compileType)`	지연 컴파일 (lazy compilation)
파일명	`getName() + ".py"` (Property명 + ".py")

2. 저장 (encodeObject) 상세

sequenceDiagram
    participant E as Element.internalStore()
    participant SP as ScriptProperty
    participant ST as DirectoryTreeStorer
    participant ZIP as "[a2w] ZIP Archive"

    E->>SP: Property 저장 요청
    SP->>SP: filename = "script.py"
    SP->>ST: storer.getKeepKey("script.py")
    ST-->>SP: associatedFileKey (or null)
    alt 변경 또는 신규
        SP->>ST: createFile("script.py"), storeScript(os), close
    else 변경 없음
        SP->>ST: keepFile("script.py")
    end
    SP->>SP: node.appendChild("java.io.File[script.py]")
    E->>ST: writeXMLDocument → elementData.xml

protected void encodeObject(...) {
    String filename = getName()+".py";
    Object associatedFileKey = storer.getKeepKey(filename);
    if (m_associatedFileKey==null || !m_associatedFileKey.equals(associatedFileKey)) {
        m_associatedFileKey = null;
        OutputStream os = storer.createFile(filename, true);
        storeScript(os);
        storer.closeCurrentFile();
        m_associatedFileKey = storer.getKeepKey(filename);
    } else {
        storer.keepFile(filename);
    }
    node.appendChild(createNodeForString(document, "java.io.File["+filename+"]"));
}

3. 로드 (decodeObject) 상세

sequenceDiagram
    participant E as Element.load()
    participant SP as ScriptProperty
    participant LD as DirectoryTreeLoader
    participant ZIP as "[a2w] ZIP Archive"

    E->>E: XML > property name="script"
    E->>SP: decodeObject(node, loader, refs, version)
    SP->>SP: getNodeText(node) = "java.io.File[script.py]"
    SP->>SP: getFilename() = "script.py"
    SP->>LD: readFile("script.py")
    LD-->>SP: InputStream
    SP->>SP: loadScript(is) - BufferedReader로 한 줄씩 읽음
    SP->>SP: set(scriptString) - m_code = null
    SP->>LD: getKeepKey("script.py") - keep key 저장

private String loadScript(InputStream is) throws IOException {
    BufferedReader br = new BufferedReader(
        new InputStreamReader(new BufferedInputStream(is)));
    StringBuffer sb = new StringBuffer();
    while (true) {
        String s = br.readLine();
        if (s != null) {
            sb.append(s);
            sb.append('\n');
        } else break;
    }
    if (sb.length() > 0)
        return sb.substring(0, sb.length() - 1);
    return "";
}

4. 4가지 스크립트 입력면 저장 위치 비교

입력면	Property	ZIP 내 파일 경로
Sandbox.script (World)	ScriptProperty	`/script.py`
ScriptResponse.script	ScriptProperty	`/behaviorN/__UnnamedN__/script.py`
ScriptDefinedResponse.script	ScriptProperty	`/behaviorN/__UnnamedN__/script.py`
ComboWidget / ScratchPad	없음 (메모리)	저장되지 않음

중요: ScriptResponse와 ScriptDefinedResponse도 ScriptProperty를 사용한다! 세 가지 모두 ZIP 내 별도의 .py 파일로 저장된다. 유일한 차이는 ZIP 내 경로.

flowchart LR
    subgraph ZIP["world.a2w ZIP"]
        SPY["/script.py (Sandbox.script)"]
        RP1["/behavior0/__Unnamed0__/script.py (ScriptResponse)"]
        RP2["/behavior0/__Unnamed1__/script.py (ScriptDefinedResponse)"]
        EX["/elementData.xml"]
    end
    EX -->|"<property name=#quot;script#quot;>java.io.File[script.py]</property>"| SPY
    EX -->|behavior0 child| B0["behavior0/elementData.xml"]
    B0 -->|__Unnamed0__ child| U0["__Unnamed0__/elementData.xml"]
    U0 -->|script property →| RP1
    B0 -->|__Unnamed1__ child| U1["__Unnamed1__/elementData.xml"]
    U1 -->|script property →| RP2

5. 코드 컴파일과 캐싱

public Code getCode(CompileType compileType) {
    String script = getStringValue();
    if (script != null && script.length() > 0) {
        if (m_code == null) {
            m_code = getOwner().compile(script, this, compileType);
        }
    } else {
        m_code = null;
    }
    return m_code;
}

script 빈 문자열 → m_code = null 반환
m_code == null → owner.compile()으로 Jython 컴파일
결과 캐시, set() 호출 시 m_code = null로 초기화

6. 유저 입장 저장 요약

편집 위치	저장 위치	지속성
Edit Script > ScriptEditor	`/script.py` in a2w	✅ 저장됨
ScriptResponse 블록	`/.../script.py` in a2w	✅ 저장됨
ScriptDefinedResponse 블록	`/.../script.py` in a2w	✅ 저장됨
ScriptComboWidget (Go)	메모리 전용	❌ 휘발
ScriptScratchPad (Perform All)	메모리 전용	❌ 휘발

ComboWidget/ScratchPad 코드는 저장되지 않는다! 영구 유지하려면 ScriptResponse 블록이나 Sandbox Script로 옮겨야 함.

7. 변수/이벤트와 스크립트 관계

변수 (Variable)

Alice UI에서 만든 전역 변수는 Sandbox.variables 배열에 저장:

<property componentClass="edu.cmu.cs.stage3.alice.core.Variable" name="variables">
    <item criterionClass="...">myVariable</item>
</property>

각 Variable Element는 별도 디렉토리에 저장:

<!-- /myVariable/elementData.xml -->
<element class="edu.cmu.cs.stage3.alice.core.Variable" name="myVariable">
    <property class="java.lang.Double" name="value">42.0</property>
    <property class="java.lang.Class" name="valueClass">java.lang.Number</property>
</element>

스크립트에서 접근:

# Alice UI 변수는 이름으로 직접 접근 (Sandbox.lookup 자동)
print(myVariable)

# Python 지역 변수 (Alice 트리와 무관)
myNewVar = 100

Behavior와 Response 연결

triggerResponse Property로 Behavior가 실행할 Response 지정:

<element class="edu.cmu.cs.stage3.alice.core.behavior.WorldStartBehavior" name="behavior0">
    <property criterionClass="..." name="triggerResponse">behavior0.__Unnamed1__</property>
</element>

이벤트 등록 (KeyEventBehavior)

<element class="edu.cmu.cs.stage3.alice.core.behavior.KeyEventBehavior" name="keyHandler">
    <property name="keyCode">32</property>    <!-- VK_SPACE -->
    <property name="keyEventType">KEY_PRESSED</property>
    <property criterionClass="..." name="triggerResponse">myScriptResponse</property>
</element>

8. ⚠️ SoundAction → SoundResponse 호환성 문제 (a2w 로딩)

현상

Alice 2.2 등 이전 버전에서 만든 a2w 파일에 SoundAction 클래스명이 저장되어 있으면 Alice 2.6.1에서 로딩 실패.

원인

Element.s_classnameMap에 SoundAction → SoundResponse 매핑이 없음.

// Element.java static initializer — 확인된 매핑 목록
// SoundAction → SoundResponse 매핑 없음!

a2w ZIP 내부에서 확인하는 방법

a2w를 ZIP으로 열기

모든 elementData.xml에서 다음 문자열 검색:

class="edu.cmu.cs.stage3.alice.core.responses.SoundAction"

발견 시 SoundAction → SoundResponse로 수동 변경

수동 수정

<!-- before (로드 실패) -->
<element class="edu.cmu.cs.stage3.alice.core.responses.SoundAction" ...>

<!-- after (로드 성공) -->
<element class="edu.cmu.cs.stage3.alice.core.responses.SoundResponse" ...>

이 수정으로 ZIP을 저장하면 Alice 2.6.1에서 정상 로드된다.

Alice 2 - 드래그 앤 드롭 블록 생성 메커니즘

대상: ResponseEditor 팔레트에서 블록을 드래그하여 Element 인스턴스가 생성되는 전체 과정 출처: ResponseEditor.java, DnDGroupingPanel.java, CompositeComponentElementPanel.java, ElementPrototype.java, CompositeComponentResponsePanel.java, GUIFactory.java 마지막 업데이트: 2026-06-09

1. 전체 구조 개요

flowchart TD
    subgraph Palette["팔레트 (initPrototypes)"]
        DIO["doInOrderPrototype: DnDGroupingPanel"]
        DT["doTogetherPrototype: DnDGroupingPanel"]
        SCRIPT["scriptPrototype: DnDGroupingPanel<br/>label='script'"]
        SDR["scriptDefinedPrototype: DnDGroupingPanel<br/>label='script defined'"]
        IF["doIfTruePrototype: DnDGroupingPanel"]
        LOOP["loopPrototype: DnDGroupingPanel"]
        WL["whileLoopPrototype: DnDGroupingPanel"]
    end

    Palette -->|"DragGestureListener.dragGesturePerformed()"| DND["java.awt.dnd.DragSource"]
    DND -->|"startDrag() → Transferable"| TRANS["ResponsePrototypeReferenceTransferable<br/>ResponsePrototype 래핑"]
    TRANS -->|"DropTarget.drop()"| DROP["CompositeComponentResponsePanel.drop()"]
    DROP -->|"getTransferData(responsePrototypeReferenceFlavor)"| RP["ResponsePrototype"]
    RP -->|"createNewResponse() → createNewElement()"| NEW["새 Response 인스턴스<br/>(ScriptResponse, DoInOrder 등)"]
    NEW -->|"performDrop(response, dtde)"| TREE["Element 트리에 addChild"]

    style SCRIPT fill:#ff0,stroke:#a80
    style SDR fill:#ff0,stroke:#a80
    style NEW fill:#aef,stroke:#08a
    style RP fill:#fda,stroke:#a60

2. 팔레트 초기화 (initPrototypes)

ResponseEditor가 열릴 때, initPrototypes()가 각 블록 타입별로 DnDGroupingPanel + ResponsePrototype을 생성한다.

// ResponseEditor.initPrototypes()
protected void initPrototypes() {
    // 1. 각 블록 타입의 표시 문자열 가져오기
    String scriptString = AuthoringToolResources.getReprForValue(
        ScriptResponse.class);  // → "script"

    // 2. DnDGroupingPanel 생성 (Swing JPanel, 드래그 가능)
    scriptPrototype = new DnDGroupingPanel();
    scriptPrototype.setBackground(SCRIPT_COLOR);  // 노란색 계열

    // 3. 라벨 추가 (팔레트에 표시될 텍스트)
    JLabel scriptLabel = new JLabel(scriptString);
    scriptPrototype.add(scriptLabel, BorderLayout.CENTER);

    // 4. ★핵심★ Transferable 설정 (드래그 시 전달할 데이터)
    scriptPrototype.setTransferable(
        new ResponsePrototypeReferenceTransferable(
            new ResponsePrototype(ScriptResponse.class, null, null)));

    // 5. 드래그 소스 등록
    scriptPrototype.addDragSourceComponent(scriptLabel);

    // ScriptDefinedResponse도 동일한 패턴
    scriptDefinedPrototype = new DnDGroupingPanel();
    // ... 같은 패턴 ...
    scriptDefinedPrototype.setTransferable(
        new ResponsePrototypeReferenceTransferable(
            new ResponsePrototype(ScriptDefinedResponse.class, null, null)));
}

각 블록별로 생성되는 Prototype:

블록	Response 클래스	knownPropertyValues	desiredProperties
DoInOrder	`DoInOrder.class`	null	null
DoTogether	`DoTogether.class`	null	null
If/Else	`IfElseInOrder.class`	null	`{"condition"}`
Loop N times	`LoopNInOrder.class`	null	`{"end"}`
While	`WhileLoopInOrder.class`	null	`{"condition"}`
ForEach	`ForEachInOrder.class`	null	`{"list"}`
script	`ScriptResponse.class`	null	null
script defined	`ScriptDefinedResponse.class`	null	null
Comment	`Comment.class`	`{"text", "No comment"}`	null
Print	`Print.class`	null	null

knownPropertyValues: 생성 시 미리 설정할 Property 값 desiredProperties: 드롭 후 팝업 메뉴에서 사용자가 입력해야 할 Property 목록

3. 드래그 시작 (Drag Source)

sequenceDiagram
    participant User as 유저
    participant DGP as DnDGroupingPanel
    participant GDL as GroupingPanelDragGestureListener
    participant DS as DragSource
    participant TRANS as ResponsePrototypeReferenceTransferable
    participant DNDM as DnDManager

    User->>DGP: 팔레트의 "script" 블록 그립(grip) 클릭 + 드래그
    DGP->>GDL: dragGestureRecognizer 감지
    GDL->>GDL: dragGesturePerformed(DragGestureEvent dge)

    alt Transferable이 null이 아님
        GDL->>DS: dge.startDrag(DefaultCopyDrop, transferable, listener)
        DS->>DNDM: DnDManager.fireDragStarted(transferable, this)
    else Transferable이 null
        GDL->>DS: startDrag(DefaultCopyNoDrop, emptyImg, ...)
        Note over GDL: 드래그 불가, NoDrop 커서 표시
    end

    Note right of DS: 이제 Transferable이<br/>Drag-and-Drop 시스템을 통해<br/>DropTarget으로 전달됨

DnDGroupingPanel의 핵심 드래그 코드:

// DnDGroupingPanel.GroupingPanelDragGestureListener
public void dragGesturePerformed(DragGestureEvent dge) {
    if (DnDGroupingPanel.this.transferable != null) {
        dge.startDrag(DragSource.DefaultCopyDrop,
            DnDGroupingPanel.this.transferable,  // ← Transferable 객체
            DnDManager.getInternalListener());
        DnDManager.fireDragStarted(DnDGroupingPanel.this.transferable, this);
    } else {
        // 드래그 불가 — 빈 이미지로 시작 (NoDrop 커서)
        dge.startDrag(DragSource.DefaultCopyNoDrop, empty, new Point(), ...);
    }
}

4. 데이터 전달 (Transferable)

ResponsePrototypeReferenceTransferable이 드래그 데이터를 캡슐화한다.

public class ResponsePrototypeReferenceTransferable
    extends ElementPrototypeReferenceTransferable {

    // 이 Transferable이 지원하는 DataFlavor
    public final static DataFlavor responsePrototypeReferenceFlavor =
        new DataFlavor(
            DataFlavor.javaJVMLocalObjectMimeType
            + "; class=edu.cmu.cs.stage3.alice.authoringtool.util.ResponsePrototype",
            "responsePrototypeReferenceFlavor");

    protected ResponsePrototype responsePrototype;

    public ResponsePrototypeReferenceTransferable(
            ResponsePrototype responsePrototype) {
        super(responsePrototype);
        this.responsePrototype = responsePrototype;

        // 3가지 flavor 지원
        flavors = new DataFlavor[3];
        flavors[0] = responsePrototypeReferenceFlavor;  // Response 전용
        flavors[1] = elementPrototypeReferenceFlavor;   // 범용 Element
        flavors[2] = DataFlavor.stringFlavor;           // 디버그용 문자열
    }

    public Object getTransferData(DataFlavor flavor) {
        if (flavor.equals(responsePrototypeReferenceFlavor))
            return responsePrototype;     // ← ResponsePrototype 객체 반환
        if (flavor.equals(elementPrototypeReferenceFlavor))
            return responsePrototype;
        if (flavor.equals(DataFlavor.stringFlavor))
            return responsePrototype.toString();
        throw new UnsupportedFlavorException(flavor);
    }
}

지원되는 DataFlavor 3종:

Flavor	용도	반환 객체
`responsePrototypeReferenceFlavor`	ResponseEditor 전용 드롭	`ResponsePrototype`
`elementPrototypeReferenceFlavor`	범용 Element 드롭 처리	`ResponsePrototype`
`stringFlavor`	디버깅/폴백	`responsePrototype.toString()`

5. 드롭 처리 (Drop Target)

sequenceDiagram
    participant DROP as CompositeComponentResponsePanel<br/>(DropTarget)
    participant DNDM as DnDManager
    participant TRANS as Transferable
    participant RP as ResponsePrototype
    participant EP as ElementPrototype

    DROP->>DROP: drop(DropTargetDropEvent dtde)
    DROP->>DNDM: getCurrentTransferable()
    DROP->>TRANS: safeIsDataFlavorSupported(responsePrototypeReferenceFlavor)?

    alt Prototype 드롭 (팔레트에서)
        DROP->>TRANS: getTransferData(responsePrototypeReferenceFlavor)
        TRANS-->>DROP: ResponsePrototype

        DROP->>RP: getDesiredProperties().length
        alt desiredProperties 없거나 3개 초과
            RP->>EP: createNewElement() → Class.newInstance()
            EP-->>DROP: 새 ScriptResponse 인스턴스
            DROP->>DROP: performDrop(newResponse, dtde)
        else desiredProperties 1~3개
            DROP->>DROP: 팝업 메뉴 표시 (사용자 입력)
            User->>DROP: 팝업에서 값 선택
            DROP->>RP: createNewElement() (knownPropertyValues 적용)
            DROP->>DROP: performDrop(newResponse, dtde)
        end

    else Property 드롭 (속성 패널에서)
        DROP->>TRANS: getTransferData(propertyReferenceFlavor)
        TRANS-->>DROP: Property 객체
        DROP->>DROP: PropertyAnimation Response 생성
        DROP->>DROP: performDrop(animation, dtde)

    else 기존 Response 이동/복사
        DROP->>TRANS: getTransferData(responseReferenceFlavor)
        TRANS-->>DROP: Response 객체
        alt ACTION_MOVE
            DROP->>DROP: performDrop(response, dtde) → shift
        else ACTION_COPY
            DROP->>DROP: performDrop(response.copy(), dtde) → add
        end
    end

6. ElementPrototype.createNewElement() — ★핵심 공장 메서드★

ElementPrototype.createNewElement()가 실제로 Java 리플렉션을 통해 Element 인스턴스를 생성한다.

flowchart TD
    START["createNewElement()"] --> NEW["elementClass.newInstance()<br/>예: new ScriptResponse()"]
    NEW --> KNOWN{"knownPropertyValues<br/>있음?"}
    KNOWN -->|각 knownPropertyValue에 대해| PROP["property.set(value)"]
    PROP -->|value가 Element면| ADD["property.owner.addChild(valueElement)"]
    KNOWN -->|끝| SPECIAL{"특수 클래스인가?"}

    SPECIAL -->|ForEach| FOREACH["item Variable 생성 + addChild"]
    SPECIAL -->|LoopNInOrder| LOOP["index Variable 생성 + addChild"]
    SPECIAL -->|기타| DONE["Element 반환"]

    FOREACH --> DONE
    LOOP --> DONE

// ElementPrototype.createNewElement() — 핵심 로직
public Element createNewElement() {
    // 1. Class.newInstance()로 Element 생성
    Element element = (Element)elementClass.newInstance();

    // 2. knownPropertyValues 설정 (미리 지정된 값)
    if (knownPropertyValues != null) {
        for (int i = 0; i < knownPropertyValues.length; i++) {
            String propertyName = knownPropertyValues[i].getString();
            Object propertyValue = knownPropertyValues[i].getObject();
            Property property = element.getPropertyNamed(propertyName);
            property.set(propertyValue);

            // value가 Element이면 owner의 child로 추가
            if (propertyValue instanceof Element) {
                Element e = (Element)propertyValue;
                if (e.getParent() == null && !(e instanceof World)) {
                    property.getOwner().addChild(e);
                    e.data.put("associatedProperty", property.getName());
                }
            }
        }
    }

    // 3. 특수 클래스 처리 — 자동 변수 생성
    if (ForEachInOrder.class.isAssignableFrom(elementClass)) {
        Variable eachVar = new Variable();
        eachVar.name.set("item");
        eachVar.valueClass.set(Object.class);
        element.addChild(eachVar);
        ((ForEachInOrder)element).each.set(eachVar);
    } else if (LoopNInOrder.class.isAssignableFrom(elementClass)) {
        Variable indexVar = new Variable();
        indexVar.name.set("index");
        indexVar.valueClass.set(Number.class);
        element.addChild(indexVar);
        ((LoopNInOrder)element).index.set(indexVar);
    }
    // ... WhileLoop 등 유사 패턴

    return element;
}

7. performDrop() — Element 트리에 연결

드롭된 Element가 실제 Alice Element 트리에 추가되는 마지막 단계.

flowchart TD
    DROP["performDrop(toDrop, dtde)"] --> RECURSE{"재귀 호출?"}
    RECURSE -->|예| WARN["경고 다이얼로그 표시<br/>취소 가능"]
    RECURSE -->|아니오| COPY{"ACTION_COPY?"}
    COPY -->|예| CLONE["toDrop = toDrop.HACK_createCopy()"]
    COPY -->|아니오| MOVE{"이미 같은 배열에<br/>있는 Element?"}
    MOVE -->|예| SHIFT["componentElements.shift(old, new)"]
    MOVE -->|아니오| ADD["unhook(toDrop) → removeFromParent()"]
    ADD -->|"addToElement(toDrop, componentElements, position)"| FINAL
    SHIFT --> FINAL
    CLONE --> ADD2["addToElement(toDrop, componentElements, position)"]
    ADD2 --> FINAL
    FINAL["✅ UndoRedoStack.stopCompound()"]

// CompositeComponentElementPanel.performDrop() — 최종 Element 트리 삽입
protected void performDrop(Element toDrop, DropTargetDropEvent dtde) {
    // 재귀 호출 검사
    if (isRecursive(toDrop)) {
        // 경고 다이얼로그 → 사용자가 취소 가능
        int result = DialogManager.showOptionDialog(...);
        if (result != 0) return;
    }

    if (authoringTool != null)
        authoringTool.getUndoRedoStack().startCompound();

    int position = getInsertLocation(...);

    if ((dtde.getDropAction() & ACTION_COPY) > 0) {
        // ★복사: createCopy로 Element 복제
        toDrop = toDrop.HACK_createCopy(null, null, position, null, ...);
    }

    if (!isCopy && componentElements.contains(toDrop)) {
        // ★이동: 같은 배열 내에서 위치 변경
        int oldIndex = componentElements.indexOf(toDrop);
        position = adjustPosition(oldIndex, position);
        componentElements.shift(oldIndex, position);
    } else {
        // ★신규: 부모 변경 후 ObjectArrayProperty에 add
        unhook(toDrop);                     // 기존 부모에서 제거
        addToElement(toDrop, componentElements, position);
    }

    if (authoringTool != null)
        authoringTool.getUndoRedoStack().stopCompound();
}

8. 블록별 드롭 결과 예시

"script" 블록 드롭

팔레트 [script] → 드래그 → DoInOrder 위에 드롭
    ↓
ResponsePrototype(ScriptResponse.class, null, null)
    ↓
ElementPrototype.createNewElement()
    ↓
new ScriptResponse()  ← ScriptProperty(script="", duration=0)
    ↓
componentElements.add(position, scriptResponse)
    ↓
DoInOrder의 자식 Response로 등록

"script defined" 블록 드롭

팔레트 [script defined] → 드래그 → DoInOrder 위에 드롭
    ↓
ResponsePrototype(ScriptDefinedResponse.class, null, null)
    ↓
new ScriptDefinedResponse()  ← ScriptProperty(script="")
    ↓
componentElements.add(position, scriptDefinedResponse)

속성에서 PropertyAnimation 드롭

bunny.color 속성을 드래그 → DoInOrder 위에 드롭
    ↓
PropertyAnimation.response 팝업 (value/지속시간 선택)
    ↓
new PropertyAnimation()
    element = property.getOwner()  // bunny
    propertyName = "color"
    value = 사용자 선택 값

9. 키 포인트 요약

팔레트의 각 블록은 DnDGroupingPanel + ResponsePrototype 쌍이다.
드래그 시 ResponsePrototypeReferenceTransferable이 ResponsePrototype 객체를 전달한다.
드롭 시 CompositeComponentResponsePanel.drop()이 responsePrototypeReferenceFlavor 로 Prototype을 추출한다.
ElementPrototype.createNewElement()가 Class.newInstance() 로 Element를 생성하고, knownPropertyValues를 설정한다.
performDrop()이 Element 트리의 ObjectArrayProperty 에 새 Element를 추가한다.
복사/이동/신규 생성 모두 동일한 performDrop()을 통해 처리된다.
ForEach/LoopN 등 특수 블록은 자동으로 index/item 변수를 생성한다.
Undo/Redo는 startCompound()/stopCompound()로 그룹핑된다.

ScriptResponse와 ScriptDefinedResponse의 차이는 createNewElement() 시점에는 없다.
둘 다 동일한 패턴으로 new ScriptResponse() / new ScriptDefinedResponse() 인스턴스만 생성된다.
차이는 런타임에 CompileType.EXEC_MULTIPLE vs CompileType.EVAL로 나타난다.

11 - 문제 해결: 실전 문제 해결

Alice 2.6.1에서 a2w 월드를 만들고 수정할 때 실제로 마주친 문제들과 해결 방법. 분석 기준: 분할주의력검사 월드 개발 과정에서 확인된 내용.

1. 월드 로딩 실패 — "Unable to load world"

케이스 A: SoundAction ClassNotFoundException

에러 메시지:

ClassNotFoundException: edu.cmu.cs.stage3.alice.core.response.SoundAction

원인: Alice 2의 블록 편집기에서 SoundAction 클래스명으로 저장된 블록이 있는데, Element.s_classnameMap에 SoundAction → SoundResponse 매핑이 없다.

해결: a2w ZIP 파일을 직접 열어 elementData.xml에서 SoundAction을 검색하여 SoundResponse로 변경.

1. a2w 파일을 ZIP 유틸리티(7-Zip 등)로 열기
2. 모든 elementData.xml에서 "SoundAction" 검색
3. class="..." 속성을 SoundResponse로 변경
   - "edu.cmu.cs.stage3.alice.core.responses.SoundAction"
   → "edu.cmu.cs.stage3.alice.core.responses.SoundResponse"
4. ZIP 저장 후 다시 로드

케이스 B: Property.decodeObject RuntimeException

에러 메시지:

java.lang.RuntimeException
    at edu.cmu.cs.stage3.alice.core.Property.decodeObject(Property.java:663)

원인: elementData.xml의 Property 값 디코딩 실패. 특정 Property가 예상 타입과 다른 값이 저장된 경우. 주로 변수 valueClass 불일치, Reference 해석 실패 등.

해결:

Alice에서 "Yes" 눌러 None으로 설정하고 계속 진행
이후 해당 Property를 UI에서 직접 재설정
또는 ZIP 내 elementData.xml을 열어 해당 Property 값 확인/수정

케이스 C: InternalReferenceKeyedCriterion 경고

경고 메시지:

WARNING: unable to resolve references:
...triggerResponse → ...InternalReferenceKeyedCriterion[event2.Unnamed0]

원인: ZIP 내에 참조 대상 디렉토리(__Unnamed0__)가 없거나, 참조 키가 불일치. 블록 편집기에서 behavior의 triggerResponse 연결이 깨짐.

해결:

"Yes" 눌러 로딩 계속
Alice UI에서 해당 behavior의 triggerResponse 속성 재할당
또는 ZIP 내 elementData.xml에서 criterionClass 참조 수정

2. 수정된 월드가 로딩 시 Reference Warning

현상: 팀원이 저장한 a2w를 열면 수많은 unable to resolve references 경고가 뜸

원인: ZIP 내 unnamed child 디렉토리명(__UnnamedN__)의 인덱스가 elementData.xml의 참조와 불일치. 블록 편집기에서 복사/이동/삭제 시 내부 참조가 깨질 수 있음.

해결:

"Yes" 누르고 로딩 (모든 참조 None 처리)
Alice UI에서 behavior들의 triggerResponse를 다시 연결
저장 전에 모든 behavior 연결 확인

3. stopSign이 car와 함께 움직임

현상: carMoveLoop에서 car가 앞으로 갈 때 stopSign도 따라 움직임

원인: stopSign의 vehicle Property가 car로 설정되어 있거나, carMoveLoop에서 stopSign move backward 0.5 동기화 코드가 들어가 있음. 블록 구성에 따라 의도된 동작일 수도 있음 (stopSign을 car-relative로 배치한 경우).

확인 방법: Alice UI에서 stopSign 선택 → vehicle 속성 확인

vehicle = world: stopSign은 고정 (car와 무관)
vehicle = car: stopSign은 car의 자식처럼 움직임

수정: stopSign의 vehicle을 world로 설정하거나, carMoveLoop에서 stopSign 이동 블록 제거

4. SayAnimation에서 변수 값이 안 보임

현상:

car.say("결과: ${score}점")  # 스크립트는 동작하지 않음

또는 블록으로 car say score 했는데 레이블 없이 숫자만 뜸

원인 & 해결:

Script는 동작하지 않음 — Alice 2.6.1 Jython NPE 문제 (01-architecture.md 참고)
한글이 안 보임 — Alice 2의 Text3D/SayAnimation은 CJK 글리프를 지원하지 않음
레이블 + 값 표시 — DoTogether로 여러 SayAnimation 블록 연결:

DoTogether:
  car → say "Score: " (0.1초)
  car → say score (0.1초)
  car → say " | Wrong: " (0.1초)
  car → say wrongCount (0.1초)

Text3D 오브젝트 사용 — 미리 ScoreText 등의 Text3D를 배치해두고 text Property를 블록의 PropertyAnimation으로 업데이트 → 하지만 3D 공간에 위치하므로 차가 이동하면 화면 밖으로 나감

5. Print 구문이 안 보임

현상: ScriptScratchPad에서 print("test") 실행했는데 아무 출력도 안 보임

원인:

Alice 2의 System.out은 기본적으로 Alice 로그 창으로 리디렉션
ScriptingFactory.setStdOut()를 호출해야 출력 스트림이 연결됨
UI 상에 출력창이 보이지 않을 수 있음

대안:

Print 블록 사용 (ResponseEditor 팔레트에 있음)
SayAnimation 블록으로 car 등에 말풍선 표시

6. 테스트 종료 후에도 car가 계속 움직임

현상: checkEndCondition에서 testRunning = 0으로 설정했는데도 carMoveLoop가 계속 돎

원인: WhileLoopInOrder는 조건을 behavior 실행 시점에 평가. testRunning = 0이 설정된 후 다음 behavior 스케줄 시점까지 딜레이가 있을 수 있음. 또는 WhileLoopInOrder의 condition이 isShowing 등 다른 Property를 보고 있을 가능성.

해결 방법:

WhileLoop의 condition이 testRunning == 1 (Variable 비교)인지 확인
checkEndCondition 메서드가 WhileLoop보다 먼저 실행되는지 behavior 순서 확인
또는 WhileLoop 내부에 If testRunning == 0 → break 블록 추가

7. 한글/글자 깨짐

원인: Alice 2.6.1의 3D 텍스트 렌더러(Text3D, SayAnimation)가 CJK(CJK Unified Ideographs) 글리프를 지원하지 않음. 기본 폰트에 한글 글리프가 없음.

해결:

모든 사용자 텍스트를 영어로 작성
정답: 5 → Correct: 5 / Score: 5
오답: 2 → Wrong: 2
평균 반응시간 → Avg Time
검사 결과 → Results
시작하려면 스페이스바 → Press SPACE to start

8. 변수 값이 SayAnimation에 반영 안 됨

현상: score 값을 SayAnimation으로 표시했는데 항상 0

원인:

SayAnimation(what=score)는 variable reference를 사용
variable이 업데이트되어도 SayAnimation의 텍스트는 prologue 시점에 고정
또는 SayAnimation의 duration이 0이면 화면에 표시될 시간이 없음

해결:

duration을 충분히 설정 (0.5~1초)
값 업데이트 후 새로운 SayAnimation 실행
DoTogether로 여러 SayAnimation 동시 실행

9. a2w ZIP 직접 수정 가이드

ZIP 내부를 직접 수정해야 할 때:

world.a2w/
├── elementData.xml           # 월드 전체 구조
├── script.py                 # Sandbox Script (실행 안 됨)
├── camera/
├── car/
│   └── elementData.xml
├── stopSign/
│   └── elementData.xml
├── score/
│   └── elementData.xml
├── my first method/
│   └── elementData.xml       # 메서드 정의
├── behavior0/                 # World start behavior
│   ├── elementData.xml
│   └── __Unnamed0__/
│       └── elementData.xml   # triggerResponse의 내용
└── event/                     # 키 이벤트 behavior
    ├── elementData.xml
    └── __Unnamed0__/
        └── elementData.xml

수정 팁:

ZIP 파일 바로 열기 → 7-Zip 등으로 열고 텍스트 파일 직접 편집
elementData.xml에서 <property name="class"> 값 수정으로 클래스명 변경 가능
변수 값: <property class="java.lang.Double" name="value">5.0</property>
참조 복구: <property criterionClass="..." name="triggerResponse">behavior0.__Unnamed1__</property>
저장 후 Alice로 로드 확인

10. "enableScripting" 메뉴 안 보임

현상: 우클릭 메뉴에 "Edit Script"가 없음

원인: Alice 설정에서 enableScripting = false

해결: Alice 설치 디렉토리에서 설정 파일 확인

Required/ 아래 설정에서 enableScripting=true로 변경
또는 Alice.ini 등 설정 파일 수정

Bluesky의 ID

Tue, 10 Mar 2026 00:00:00 GMT

ID

내 프로필은 여기 있다. https://bsky.app/profile/euroka.moe

이 링크는 2개로 나눌 수 있다. bsky.app 앱뷰, euroka.moe 핸들. 그런데...

왜 도메인 형식을 지닐까?
PDS를 변경해도 핸들은 왜 같을까?
핸들을 변경해도 어떻게 게시글 등은 유지될까?

DID

이때 DID가 등장한다. Decentralized ID의 약자로, DID 종류(메서드)에 따라 탈중앙화된 식별자를 고유하게 생성한다. 180개 이상의 DID 종류가 있지만, ATProto에서 사용하는 DID는 두 가지가 있다.

`did:web`

did:web은 자신의 DID document를 .well-known/did.json 경로에 둔다. did:web:euroka.moe의 경우 https://euroka.moe/.well-known/did.json에 있는 것이다.

[!NOTE] 내 DID는 did:web을 쓰지 않는다! 예시용일 뿐이니 참고 바란다.

장점은,

탈중앙화에 더 가깝다.

DNS를 신뢰해야 한다는 문제가 있지만, 이건 뭐 어쩔 수 없지 않나. 공인되고 검증된 기관이 운영한다는 것에 기대는 게 그나마 나을 것이다.

did가 직관적이다.

did:plc:qjua73d5eq537nio2sucdaj3와 did:web:euroka.moe 중 기억하기 쉬운 것을 고르라 하면 당연히 후자 아닌가?

하지만 단점이 상당하다.

도메인의 .well-known/did.json 접근에만 의존한다.

도메인 만료, 호스팅 업체의 변덕, 레코드 작성 실수, 모든 것은 DID document의 제어권 유실로 이어진다. 그리고 DID document의 제어권 유실은 signing 키나 PDS 변경, 핸들(DID document의 alsoKnownAs 값) 등을 불가능하게 만든다. HTTPS 인증서 주던 CA가 터졌다? 다른 CA에서 인증서 받아오기 전까진, DID document는 다른 사람들에게 보이지 않게 되고, DID document가 없으니 존재하지 않는 자가 된다. 게시글, 팔로우 기록, 등등. 이것들은 존재하지 않는 사람이 한 것으로 나온다.

`did:plc`

did:plc는 제일 간결하고 탈중앙화는 아니지만 타협적인 방법이다. PLC Dictionary라는 중앙화된 원장에 저장한다. 그리고 이걸 REST API로 모두에게 공개한다. 감사 로그와 키 서명 검증을 통하여 투명성을 확보하지만, 그렇다고 완전히 염려가 없는 것은 아니다. 하지만, 이는 매우 큰 장점이 있다.

도메인의 사용처를 alsoKnownAs를 채우는 데만 쓰는 게 가능하다. PLC Directory가 망하지 않는 이상, 도메인이 털려도 PLC Directory는 털리지 않으니 원래 있던 recovery 키로 alsoKnownAs를 수정하면 그만이다. 이 장점 덕분에 절대 다수의 유저들은 did:plc를 사용한다.

DID의 검증

PDSls 서비스에서 DID document를 보기 쉽게 확인할 수 있다. 여기서 Identity 탭의 Aliases 항목을 보자.

이는 DID document의 alsoKnownAs를 알려주는 곳이다. DNS (TXT record) 항목에서 did:plc:qjua73d5eq537nio2sucdaj3가 적혀임을 알 수 있다. DID document에서 did:plc:qjua...가 euroka.moe를 통제한다고 주장한다. 주장일 뿐이고, 인증되지 않았다. 이제 euroka.moe가 did:plc:qjua...를 통제한다고 주장하면 상호 통제 상태가 되고, 즉 같은 사람에게 제어받는다 생각할 수 있다.

핸들의 ${핸들}/.well-known/atproto-did 파일을 확인해서 검증할 수도 있지만, 이는 예시로 쓸 사용자가 없어 생략한다.

서버 배포를 쌀먹하기 w. Hono

Sat, 07 Mar 2026 00:00:00 GMT

돈벌기

돈이 없다. 이것은 학생의 숙명이다. 프리티어를 떠도는 노마드의 삶이다. 그런데 코딩을 하면 배포할 일이 생긴다. 당연한 거 아닌가. 배포를 그럼 git clone하라고 할 수도 없지 않나.

FaaS/서버리스

서버리스의 장점은 그것이다. 24/7이 필요하긴 한데, 굳이 막 항상 사람이 들어오는 건 아닌 사이트 많지 않나? 그런 상황이 많다. 서버리스는 그 상황에 딱 맞는다. 트래픽 없다? 서버 내릴게. 서버 내려? 돈 안뺄게.

Azure Functions

Azure Functions는 마이크로소프트의 서버리스 플랫폼이다.

장점:

언어 독립적이다, 안 되면 커스텀 핸들러로 어떻게든 된다
SLA가 있다(무료티어 포함)
무료 티어도 있고 학생 크레딧을 쓸 수 있다

단점:

하드캡이 없다. 카드 넣어야 한다
콜드 스타트가 좀 걸린다
저장공간은 또 다른 서비스 써야 한다
~~꽤 고립적이다~~ Hono가 지원

Cloudflare Workers

Cloudflare Workers는 JS를 지원하는 FaaS이다.

장점:

빠른 콜드 스타트(0ms!!!!)
무료티어 넘어가면 청구 없이 터진다(Paid 플랜 업그레이드하지 않으면)
CI/CD를 CF에서 제공한다(=Github Action 요금 낼 필요 없다, 워크플로우 짤 필요 없다)
분당 1000회 무료 티어
다른 WinterTC 계열 서비스 대비 더 넉넉하다

단점:

JS와 WASM 컴파일을 지원하는 일부 언어만 가능하다
Github Action은 어짜피 퍼블릭레포 무제한 무료라 굳이...?
런타임은 Node.JS와 거리가 멀다, DOM 없다
CPU 타임이 제한적이다(무료플랜 10ms/콜)

Deno Deploy

Deno Deploy는 Cloudflare Workers와 유사한 FaaS 호스팅 서비스다.

장점:

Cloudflare Workers 대비 넉넉한 CPU 타임(15h/월)
빠른 콜드 스타트
셋업하기 쉽다(import { Hono } from "jsr:hono", TypeScript OOTB 지원 등)
제일 JS스럽고, 배워야 할 자체 개념이 적다

단점:

JS/TS만 지원한다
카드 등록이 필요하다(업그레이드하기 전까진 billing X)
Cloudflare Workers 대비 물리적 인프라가 떨어진다
다들 Cloudflare 계정은 있지만 Deno Deploy는 없는 경우도 있다

Hono

"신"

Hono는 각종 FaaS 프로바이더를 위한 프레임워크다. 지원하는 실행 환경은...

Node.js
Deno(Deno Deploy 포함)
Bun
WebAssembly
Service Worker

이러하다. 또 호스팅은 이 플랫폼들을 지원한다.

Cloudflare Workers, Cloudflare Pages
Fastly Compute
Vercel, Netlify
Next.js
AWS Lambda, Lambda@Edge
Azure Functions
Google Cloud Run
Supabase Functions
Ali Function Compute

이 무슨 개얼탱없는 라인업이란 말인가. 당장 써야지. 원래 FaaS 서비스들은 꽤 벤더 종속적이다. 벤더에서 제공한 API를 쓰게 되는데, 이러면 다른 곳으로 마이그레이션하기 상당히 어렵다.

// Cloudflare Workers, ES Modules 문법
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const name = url.searchParams.get('name');

    if (name) {
      return new Response(`Hello, ${name}! Welcome to Cloudflare Workers.`, {
        status: 200,
        headers: {
          'Content-Type': 'text/plain; charset=utf-8',
        },
      });
    } else {
      return new Response('Hello World! This is Cloudflare Workers.', {
        status: 200,
        headers: {
          'Content-Type': 'text/plain; charset=utf-8',
        },
      });
    }
  },
};

// Azure Functions
export async function serve(context, req) {
  context.log('HTTP trigger function processed a request.');

  const name = req.query.name || (req.body && req.body.name);

  if (name) {
    context.res = {
      status: 200,
      body: `Hello, ${name}! Welcome to Azure Functions.`
    };
  } else {
    context.res = {
      status: 200,
      body: 'Hello World! This is Azure Functions.'
    };
  }
};
export default serve;

네이티브 API를 쓰면 벌써 코드가 다르다. CF Workers는 함수를 객체에 담아 export default하고, 그 함수는 Response 객체를 리턴한다. 하지면 Azure Functions는 함수가 context.res를 수정한다.

그런데 그때, Hono가 등장한다...

import { Hono } from 'hono';

type Env = {
  Bindings: Record<string, unknown>;
};

const app = new Hono<Env>();

// POST 요청 처리 예제
app.post('/api/hello', async (c) => {
  const body = await c.req.json<{ name?: string }>();
  const name = body.name || 'World';

  return c.json({
    message: `Hello, ${name}!`,
    method: 'POST',
    framework: 'Hono',
  });
});

export default app;

이거, 어디선가 본 패턴이지 않은가?

import express, { Request, Response } from 'express';

const app = express();

app.use(express.json());

app.post('/api/hello', (req: Request, res: Response) => {
  const body = req.body as { name?: string };
  const name = body.name || 'World';

  res.json({
    message: `Hello, ${name}!`,
    method: 'POST',
    framework: 'Express',
  });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

export default app;

Express.js와 매우 유사하다. 선언적이고, 자유분방하다. 게다가 타입스크립트를 염두하고 만들어졌기 때문에,

//...
const app=new Hono()
    .post("/post", ...)
    .get("/get", ...);
export default app;

이와 같은 방식으로 메서드 체인을 걸면, app의 타입 자체에 라우트 정보가 작성된다. 이는 RPC나 테스팅 시 매우 유용하다.

개인 사용을 위해 Hono용 템플릿을 작성해두었다.

안녕 세계

Sat, 21 Feb 2026 00:00:00 GMT

안녕! 👋 오늘부터 블로그를 시작합니다.

작은 스크립트 파일은 Deno를 쓰는 것에 대하여

Sat, 21 Feb 2026 00:00:00 GMT

Node.js에서의 타입스크립트

Node.js에서 타입스크립트를 쓰려면, 3가지 방법이 있다.

타입스크립트용 REPL을 사용한다.
- tsx 패키지를 설치해야 한다.
- tsx 명령어로 타입스크립트 코드를 실행시킨다.
타입스크립트 프로젝트를 생성한다.
- tsconfig.json 파일을 만들어야 한다.
- esbuild나 tsc로 타입스크립트를 자바스크립트로 컴파일해야 한다.
- 그렇기에, package.json과 node_modules도 필요하다.
- 컴파일된 자바스크립트 파일을 실행해야 한다.
Node.js를 믿는다.
- 일단 타입스크립트 파일을 실행시킨다.
- Node.js의 --strip-types를 믿고 실행한다.
- strip 가능한 코드가 아니라면서, 에러가 난다.
- 이제 --experimental-transform-types를 쓴다.
- 매번 플래그 넘겨주려니까 귀찮다.
- 결국 tsx를 설치한다.

> 서기관 셰럼, 이건 좀 너무한다고 생각함.

그럼 타입스크립트 왜씀?

타입스크립트는 자바스크립트보다 빌드 타임에 많은 정보를 알게 된다. 이곳에서 오는 크나큰 장점이 있다.

자동완성

JS는 object의 프로퍼티가 무엇인지 알 수 없다. 그래서 자동완성이 안된다.

TS는 정보를 .ts 파일이나 .d.ts 파일에 모두 담아놓는다. number에는 toFixed가 있고, string에는 toUpperCase가 있다는 것을 알고 있다. toUpperCase는 파라미터를 아무것도 받지 않은 ()=>string 타입의 함수임을 lib.d.ts에 적어놓는다.

JS는 이상한 기교가 있다. 빈 배열과 느낌표, 더하기, 이상한 기호 몇 개로 모든 코드를 만들 수 있다.

[]+[] // ""
[]+{} // "[object Object]"
{}+[] // 0
{}+{} // NaN

이 무슨 쓰레기 언어란 말인가. 타입스크립트 안 쓸 이유가 없지 않나?

> 정체성의 유령도 한물 두물 세물 간 자바스크립트를 버리고 타입스크립트에 어울리는...

빨간약

하지만 타입스크립트는 딱 하나의 문제점이 있다. 결국 실행을 못 한다.

> 으에엥 타입스크립트 네르지 마세요

그러면 타입스크립트 코드를 자바스크립트 코드로 변환하고, 실행하고, 그걸 반복하면 되지 않을까? 가능하다. Node.js의 --strip-types가 비슷하게 한다. 하지만 이는 const enum과 같은 일부 기능을 지원하지 않는다. --experimental-transform-types 플래그를 써야 한다. 하지만 이름에서 알 수 있듯이 이는 실험적이다. 언제 터져도 이상하지 않다는 것이다.

그렇게 엄청 간단하지는 않은 스크립트

예시로, hello.ts라는 파일을 만들어보자.

console.log("Hello, world!");

이는 충분히 간단하다. tsx로도 실행할 수 있다. 하지만, 조금 복잡한 스크립트는 어떨까?

// openai.ts
const prompt='"크아앙"\n투명드래곤이 울부짖었다.\n\n이 다음 소설의 내용을 이어서 써줘.';

const response = await fetch("https://api.openai.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
  },
  body: JSON.stringify({
    model: "gpt-5-mini",
    messages: [{ role: "user", content: prompt }],
  }),
});
const data = await response.json();

> 한 동인지 작가의 흑역사를 드러내고 있다.

조금 복잡해진다. 이제 스트리밍도 추가해볼까?

// openai.ts
const prompt='"크아앙"\n투명드래곤이 울부짖었다.\n\n이 다음 소설의 내용을 이어서 써줘.';
const response = await fetch("https://api.openai.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
  },
  body: JSON.stringify({
    model: "gpt-5-mini",
    messages: [{ role: "user", content: prompt }],
    stream: true,
  }),
});
const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = new TextDecoder().decode(value);
  console.log(chunk);
}

물론 여기서 저 청크 하나하나도 JSON이니까, JSON.parse를 해야 한다. 메세지 델타들에 대해 조금씩 출력하고, 메세지 끝에 도달했는지 확인하는 로직도 필요하다.

Deno를 쓰세요

tsx는 Node.js다. 라이브러리를 설치하려면, node_modules에 넣어야 한다. 방법은? pnpm add와 package.json 관리, 그리고 기타 귀찮은 파일 관리를 해야 한다.

Deno는 Deno다. 라이브러리를 사용하려면,

import OpenAI from 'jsr:@openai/openai';

이 얼마나 간결한가. Deno로 위 예시를 다시 짜 보자.

import OpenAI from "jsr:@openai/openai";

const client = new OpenAI();

const stream = await client.responses.create({
  model: "gpt-5-mini",
  input: '"크아앙"\n투명드래곤이 울부짖었다.\n\n이 다음 소설의 내용을 이어서 써줘.',
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}

타입스크립트? Deno는 된다.

> 긴긴-팔다리의 출몰에 정신을 잃은 셰럼

Markdown Extended Features

Wed, 01 May 2024 00:00:00 GMT

GitHub Repository Cards

You can add dynamic cards that link to GitHub repositories, on page load, the repository information is pulled from the GitHub API.

::github{repo="Fabrizz/MMM-OnSpotify"}

Create a GitHub repository card with the code ::github{repo="<owner>/<repo>"}.

::github{repo="saicaca/fuwari"}

Admonitions

Following types of admonitions are supported: note tip important warning caution

:::note Highlights information that users should take into account, even when skimming. :::

:::tip Optional information to help a user be more successful. :::

:::important Crucial information necessary for users to succeed. :::

:::warning Critical content demanding immediate user attention due to potential risks. :::

:::caution Negative potential consequences of an action. :::

Basic Syntax

:::note
Highlights information that users should take into account, even when skimming.
:::

:::tip
Optional information to help a user be more successful.
:::

Custom Titles

The title of the admonition can be customized.

:::note[MY CUSTOM TITLE] This is a note with a custom title. :::

:::note[MY CUSTOM TITLE]
This is a note with a custom title.
:::

GitHub Syntax

[!TIP] The GitHub syntax is also supported.

> [!NOTE]
> The GitHub syntax is also supported.

> [!TIP]
> The GitHub syntax is also supported.

Spoiler

You can add spoilers to your text. The text also supports Markdown syntax.

The content :spoiler[is hidden ayyy]!

The content :spoiler[is hidden **ayyy**]!

Expressive Code Example

Wed, 10 Apr 2024 00:00:00 GMT

Here, we'll explore how code blocks look using Expressive Code. The provided examples are based on the official documentation, which you can refer to for further details.

Expressive Code

Syntax Highlighting

Regular syntax highlighting

console.log('This code is syntax highlighted!')

Rendering ANSI escape sequences

ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m

Editor & Terminal Frames

Code editor frames

console.log('Title attribute example')

<!-- src/content/index.html -->
<div>File name comment example</div>

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Overriding frame types

echo "Look ma, no frame!"

# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

Text & Line Markers

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
 no whitespace will be removed either

Combining syntax highlighting with diff-like syntax

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported';
}

Regular expressions

console.log('The words yes and yep will be marked.')

Escaping forward slashes

echo "Test" > /home/test.txt

Selecting inline marker types (mark, ins, del)

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

Word Wrap

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible Sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Line Numbers

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

Changing the starting line number

console.log('Greetings from line 5!')
console.log('I am on line 6')

Simple Guides for Fuwari

Mon, 01 Apr 2024 00:00:00 GMT

Cover image source: Source

This blog template is built with Astro. For the things that are not mentioned in this guide, you may find the answers in the Astro Docs.

Front-matter of Posts

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
---

Attribute	Description
`title`	The title of the post.
`published`	The date the post was published.
`description`	A short description of the post. Displayed on index page.
`image`	The cover image path of the post.<br/>1. Start with `http://` or `https://`: Use web image<br/>2. Start with `/`: For image in `public` dir<br/>3. With none of the prefixes: Relative to the markdown file
`tags`	The tags of the post.
`category`	The category of the post.
`draft`	If this post is still a draft, which won't be displayed.

Where to Place the Post Files

Your post files should be placed in src/content/posts/ directory. You can also create sub-directories to better organize your posts and assets.

src/content/posts/
├── post-1.md
└── post-2/
    ├── cover.png
    └── index.md

Markdown Example

Sun, 01 Oct 2023 00:00:00 GMT

An h1 header

Paragraphs are separated by a blank line.

2nd paragraph. Italic, bold, and monospace. Itemized lists look like:

this one
that one
the other one

Note that --- not considering the asterisk --- the actual text content starts at 4-columns in.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all in chapters 12--14"). Three dots ... will be converted to an ellipsis. Unicode is supported. ☺

An h2 header

Here's a numbered list:

first item
second item
third item

Note again how the actual text starts at 4 columns in (4 characters from the left side). Here's a code sample:

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

define foobar() {
    print "Welcome to flavor country!";
}

(which makes copying & pasting easier). You can optionally mark the delimited block for Pandoc to syntax highlight it:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

An h3 header

Now a nested list:

First, get these ingredients:
- carrots
- celery
- lentils
Boil some water.

Dump everything in the pot and follow this algorithm:

 find wooden spoon
 uncover pot
 stir
 cover pot
 balance wooden spoon precariously on pot handle
 wait 10 minutes
 goto first step (or shut off burner when done)

Do not bump wooden spoon or it will fall.

Notice again how text always lines up on 4-space indents (including that last line which continues item 3 above).

Here's a link to a website, to a local doc, and to a section heading in the current doc. Here's a footnote [^1].

[^1]: Footnote text goes here.

Tables can look like this:

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

A horizontal rule follows.

Here's a definition list:

apples : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Here's a "line block":

| Line one | Line too | Line tree

and images can be specified like so:

Inline math equations go in like so: $\omega = d\phi / dt$. Display math should get its own line and be put in in double-dollarsigns:

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: `foo`, *bar*, etc.

Include Video in the Posts

Tue, 01 Aug 2023 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili

push -f

Edit 툴 4종, 880회 실측 성공률 — replace가 이긴 이유와 patch의 토큰 블랙홀

Edit 툴 4종, 880회 실측 성공률 — replace가 이긴 이유와 patch의 토큰 블랙홀

TL;DR

1. 하네스의 4가지 edit 툴

2. 측정 설계

3. 툴별 성공률

4. 토큰 & 비용: 성공률 너머

5. 모델 × 툴 상호작용 매트릭스

6. 사례 연구: glm-5.2, 툴 하나로 50%p가 갈렸다

7. 왜 patch는 실패 루프에 빠지는가

8. 하네스에 주는 교훈

9. 데이터 & 재현

MVCC 그리고 PostgreSQL과 MySQL의 차이점

MVCC

그러니까 창팝으로 비유하자면...

이해가하나도안되잖아쿼리슝좍아

PostgreSQL의 MVCC 구현

MySQL의 MVCC 구현

그래서 뭐가 더 좋은데?

요약

OpenAI Responses API SSE Reversing Notes

OpenAI Responses API — SSE Streaming Internals

1. High-Level Architecture

2. SSE Wire Format

3. Full Event Catalog (53 types)

3.1 Response Lifecycle Events

3.2 Output Items — Structural

3.3 Text Content

3.4 Refusal

3.5 Function Calling

3.6 MCP (Model Context Protocol)

3.7 Audio

3.8 Web Search Tool

3.9 File Search Tool

3.10 Code Interpreter Tool

3.11 Reasoning

3.12 Image Generation

3.13 Custom Tool Call

4. SSE Parsing Pipeline (Wire to Typed Event)

Key decoder details

5. SDK Convenience API: ResponseStream / ResponseStreamState

5.1 ResponseStreamManager (entry point)

5.2 ResponseStream → ResponseStreamState

5.3 accumulate_event() — State Machine

5.4 Convenience methods

5.5 ResponseStreamEvent[TextFormatT] (SDK wrapper types)

6. Background Mode Streaming

7. Data Flow Summary

8. Wire-Level Example (Synthetic)

9. Implementation Reference (Key Files in SDK)

10. Event Taxonomy Diagram

OpenAI Responses API SSE 리버싱 노트

OpenAI Responses API — SSE 스트리밍 내부 구조

1. 상위 수준 아키텍처

2. SSE 와이어 포맷

3. 전체 이벤트 목록 (53종)

3.1 Response 생명주기 이벤트

3.2 출력 항목 — 구조적

3.3 텍스트 콘텐츠

3.4 거절(Refusal)

3.5 함수 호출(Function Calling)

3.6 MCP (Model Context Protocol)

3.7 오디오

3.8 웹 검색 도구

3.9 파일 검색 도구

3.10 코드 인터프리터 도구

3.11 추론(Reasoning)

3.12 이미지 생성

3.13 사용자 정의 도구 호출

4. SSE 파싱 파이프라인 (와이어 → 타입화된 이벤트)

디코더 주요 상세

5. SDK 편의 API: ResponseStream / ResponseStreamState

5.1 ResponseStreamManager (진입점)

5.2 ResponseStream → ResponseStreamState

5.3 accumulate_event() — 상태 머신

5.4 편의 메서드

5.5 ResponseStreamEvent[TextFormatT] (SDK 래퍼 타입)

6. 백그라운드 모드 스트리밍

7. 데이터 흐름 요약

Edit 툴 4종, 880회 실측 성공률 — `replace`가 이긴 이유와 `patch`의 토큰 블랙홀

7. 왜 `patch`는 실패 루프에 빠지는가

5. SDK Convenience API: `ResponseStream` / `ResponseStreamState`

5.1 `ResponseStreamManager` (entry point)

5.2 `ResponseStream` → `ResponseStreamState`

5.5 `ResponseStreamEvent`[TextFormatT] (SDK wrapper types)

8. 전체 추적: `bunny.color = alice.red`

04 - API 참조: `alice` Python 패키지

상수 (`constants.py`)

선형대수 (`linearalgebra.py`)

센서 (`init.py`)