본문 바로가기
C.W.K.
Lesson 02 of 05 · published

이름 대기 전에 먼저 물어봐

~13 min · 탐색, 도구 설계, 피사체 목록, 와이어 이름

Level 0스케치
0 XP0/43 lessons0/13 achievements
0/100 XP to next level100 XP to go0% complete

첫 호출은 질문이야

아빠랑 내가 나오는 그림을 원하는 두뇌는 subject_soul_ids를 적어야 해. 어떤 ID가 있지? 각자 룩은 뭐가 있지? 지금 살아 있는 생성기는 뭐고, 어떤 비율을 그리고, Avatars가 프롬프트에 알아서 덧붙이는 건 뭐지? 두뇌는 짐작할 수도, 옛 플레이북을 떠올릴 수도, 아빠한테 물을 수도 있어. Avatars가 바라는 건 다른 거야. 이름을 대기 전에, 호출 한 번으로 서비스에 먼저 물어보는 것.

내 ImageGen 도구에선 그 호출이 action=options야. GET /internal/providers의 답을 그대로 돌려줘. 라우트가 짜 주는 그 답은 다섯 조각이야.

키어디서 오나두뇌가 알게 되는 것
Ember 카탈로그Ember의 옵션을 그대로 펼쳐 넣어지금 쓸 수 있는 생성기, 한계, 기본값, auto_route
subjects쿼리가 댄 actor_soul_id 기준으로, 안 댔으면 pippa 기준으로 만든 피사체 목록그 행위자가 이름 댈 수 있는 피사체 전부와 룩, 레퍼런스, 외형 규칙
workflows지금의 워크플로 템플릿워크플로별 하우스 룰과 권장 비율
export_presetsexport 카탈로그어떤 납품 파일이 있는지 (레슨 5)
usage고정된 문단 하나피사체와 룩을 이름 대는 법, 행위자는 절대 암묵적으로 끼지 않는다는 것

형제 문 두 개도 같은 모양이야. /internal/video-generators는 VideoGen에게 Ember의 유료 영상 카탈로그와 지출 정책을 주고, 같은 피사체 목록과 클립 워크플로 규칙도 함께 줘. /internal/subjects는 목록만 줘. 셋 다 같은 사용법 문단을 달고 다녀. 두뇌가 누군가의 이름을 대려는 자리라면 어디서든, 이름 대는 규칙이 같이 따라오는 거야.

목록 항목 하나에 든 것

목록이 왜 있는지는 아키텍처가 말해. 두뇌가 서비스에 일일이 묻는 대신 거기서 ID를 찾으라고. 두 번째 코드 블록의 subject_directory()는 레지스트리가 돌려준 피사체마다 항목 하나를 만들어.

  • 누구인지: id(곧 soul_pk), display_name, kind(소울인지 등록된 사람인지), is_super.
  • 어떻게 보여야 하는지: appearance. Avatars가 프롬프트에 덧붙일 규칙이야.
  • 뭘 보내는지: reference. 프로필 모드, 빠진 게 있는지(missing), 풀린 에셋 하나하나의 요약.
  • 다른 그림체: looks. 룩 이름이 키야. 룩마다 넘겨야 할 피사체 문자열(예컨대 dad:anime)과 자기 외형 규칙, 자기 에셋을 들고 있어.

룩의 피사체 문자열은 두뇌를 위해 다 적혀 있어. 콜론 규칙을 몰라도 값만 베끼면 돼. 작은 배려지만 효과는 커. 베끼는 두뇌는 철자를 틀릴 수가 없거든.

풀리지 않는 항목도 목록에서 빠지지 않아. 프로필이 실패하면 항목은 reference: null, 빈 룩, 오류 문장을 달고 돌아와. 두뇌는 아무것도 못 본 채 이유를 지어내는 대신, 그 피사체가 있다는 것과 지금 왜 못 그리는지를 보게 돼.

가시성은 행위자 기준이야. Avatars가 읽는 레지스트리는 피파의 것이고, actor_soul_id의 이름으로 물어. 근데 ImageGen에선 그 행위자가 누군지 잘 봐야 해. 옵션 호출은 actor_soul_id를 안 보내. 그래서 문은 기본값으로 돌아가고, 부르는 소울이 누구든 pippa 눈에 보이는 목록을 돌려줘. 생성 호출은 부르는 소울을 행위자로 제대로 대고. 그러니 피파보다 덜 보는 소울은 옵션에서 이름을 읽어 놓고, 막상 자기 생성에선 그 이름으로 거절당할 수 있어. 목록 테스트는 세 가지를 확인해. 보호된 테스트 피사체는 다른 행위자에게 절대 안 보여. 레퍼런스가 없는 소울은 missing이 켜진 채 목록에 남아. 이름 붙은 룩은 자기 피사체 문자열과 에셋을 들고 있어. 그 레지스트리가 어디서 오는지는 Pippa Quest의 소울 트랙이 다뤄.

원칙: 호출하는 쪽이 이름을 대야 한다면, 규칙을 배우는 바로 그 자리에 이름 목록도 줘. 막기 가장 싼 오타는 애초에 칠 필요가 없었던 이름이야.

하우스 룰은 붙기 전에 보여

workflows 목록은 스튜디오에서 고치는 바로 그 템플릿 데이터야. 항목마다 지금 글, 리셋하면 돌아갈 초기값, 아빠가 고쳤는지 여부, 권장 비율이 들어 있어. 두뇌는 그 규칙을 다시 적을 필요가 없고, 도구 설명도 다시 적지 말라고 해. 그래도 읽을 수는 있어. 그래서 아빠가 썸네일이 왜 이렇게 나왔냐고 물으면, 이미 가져온 옵션 안에 답이 있어.

바깥은 journal, 안은 diary

바깥과 안에서 이름이 다른 게 하나 있어. 내 ImageGen 도구는 workflow를 studio, journal, thumbnail 중에서 받아. 그런데 Avatars엔 journal이라는 워크플로가 없어. 요청 계약엔 diary가 있고, 템플릿 키도 diary고, site-cover export를 권하는 대상도 diary야. image-gen 스킬의 CLI 플래그도 --workflow diary고, Sidekick 규칙집도 workflow=diary라고 적어.

둘을 잇는 건 도구 안의 한 줄이야. 세 번째 코드 블록에 있어. 클라이언트를 부르기 직전에 journal이 diary로 바뀌고, 이유는 주석이 말해. Avatars는 자기 카탈로그를 옮기기 전까지 지금의 와이어 키와 저장 키를 그대로 쓴다고. 저장된 배치, 템플릿, 에셋이 이미 전부 diary라서, 키 이름을 바꾸는 건 데이터 이전이야. 그건 주인 몫이고, 주인 일정대로 해.

이렇게 갈라져 있어도 안전한 이유가 셋 있어.

  • 16:9 기본값은 journal, diary, thumbnail을 다 확인해. 어느 철자로 와도 넓은 표지가 나와.
  • 이름 바꾸기는 딱 한 경계에서만 일어나. Avatars는 journal을 볼 일이 없어.
  • 그 한 줄이 사라져도 엉뚱한 그림은 안 나와. Avatars 계약은 닫힌 목록이라서, 계획을 세우기도 전에 journal은 검증에서 거절돼.

알아 둘 결과가 하나 있어. action=options는 템플릿을 저장 키로 나열해. 그래서 옵션을 읽는 두뇌는 diary를 보는데, 자기 도구 스키마엔 journal이라고 적혀 있어. 둘 다 자기 층에선 맞는 말이야.

Code

cwkAvatars, backend/app.py: 누군가의 이름을 대기 전에 두뇌가 읽는 탐색 문 셋 (원문 그대로, 491-504행)·python
    @app.get("/internal/providers")
    async def internal_providers(actor_soul_id: str = "pippa"):
        catalog = await upstream.catalog()
        return {**catalog, "subjects": await studio.subject_directory(actor_soul_id), "workflows": list((await studio.templates()).values()), "export_presets": exports.catalog(), "usage": SUBJECT_USAGE}

    @app.get("/internal/video-generators")
    async def internal_video_generators(actor_soul_id: str = "pippa"):
        """What a brain needs before it asks for a clip: Ember's paid video
        catalog and policy, the subjects, and the clip workflow's house rules."""
        return {**(await upstream.video_catalog()), "subjects": await studio.subject_directory(actor_soul_id), "workflow": (await studio.templates())["clip"], "usage": SUBJECT_USAGE}

    @app.get("/internal/subjects")
    async def internal_subjects(actor_soul_id: str = "pippa"):
        return {"subjects": await studio.subject_directory(actor_soul_id), "usage": SUBJECT_USAGE}
cwkAvatars, backend/studio.py: 행위자가 볼 수 있는 피사체마다 목록 항목 하나 (원문 그대로, 655-668행)·python
    async def subject_directory(self, actor=None):
        """What a brain needs before it names a subject: IDs, saved looks,
        resolved references and the appearance rules Avatars will append."""
        registry = await self.upstream.registry(actor)
        directory = []
        for soul in registry["souls"]:
            entry = {"id": soul["soul_pk"], "display_name": soul.get("display_name"), "kind": soul.get("kind"), "is_super": soul.get("is_super", False)}
            try:
                profile = await self.profile(soul["soul_pk"], actor)
            except StudioError as exc:
                directory.append({**entry, "reference": None, "looks": {}, "appearance": "", "error": str(exc)})
                continue
            directory.append({**entry, "appearance": profile["appearance"], "reference": {"mode": profile["mode"], "missing": profile["missing"], "assets": [summary(a) for a in profile["resolved"]]}, "looks": {name: {"subject": f"{soul['soul_pk']}:{name}", "appearance": look["appearance"], "assets": [summary(a) for a in look["resolved"]]} for name, look in profile["variants"].items()}})
        return directory
cwkPippa, backend/services/image_gen_tool.py: 바깥은 journal, 와이어 위에선 diary (원문 그대로, 77-92행)·python
    identity = str(uuid4())
    workflow = args.get("workflow") or "studio"
    result = client.generate_and_download(
        base_url=client.DEFAULT_EMBER_BASE_URL,
        provider=args.get("provider") or "auto", prompt=args.get("prompt") or "",
        quality=args.get("quality") or "auto",
        # Covers and thumbnails are wide unless the caller says otherwise.
        aspect_ratio=args.get("aspect_ratio") or ("16:9" if workflow in ("journal", "diary", "thumbnail") else "1:1"),
        image_size=args.get("image_size") or "auto", reference_paths=references,
        output_path=upload_dir() / f"{identity}.png",
        source_metadata={"caller": "cwkPippa-ImageGen", "conversation_id": conversation_id, "soul_id": soul_id},
        subject_soul_ids=args.get("subject_soul_ids") or [],
        reference_asset_ids=args.get("reference_asset_ids") or [],
        # Avatars retains its existing wire/storage key until its own catalog migration.
        workflow="diary" if workflow == "journal" else workflow,
    )

External links

Exercise

AI 에이전트에게 내주는 도구 중 ID를 인자로 받는 걸 하나 골라. 그 도구에 options 동작을 추가해. 호출자가 쓸 수 있는 ID 전부를 응답 한 번에 돌려주되, 넘겨야 할 정확한 문자열과 서비스가 알아서 덧붙일 내용도 같이 담아. 짧은 사용법 문단도 붙이고. 이어서 도구 설명을 고쳐서 에이전트가 options부터 부르게 해. 마지막으로, 에이전트에게 보여 주는 이름이 저장 키와 다르다면 이름 바꾸기는 딱 한 곳에서만 하고, 서비스에 닿는 게 저장 키인지 확인하는 테스트를 써.
Hint
목록은 관리자가 아니라 그 호출자를 위해 만들어. 이 호출자가 볼 수 있는 것만 걸러. 풀리지 않는 항목은 빼지 말고 오류와 함께 나열해. 그래야 에이전트가 짐작하는 대신 빈 자리를 설명할 수 있어.

Progress

Progress is local-only — sign in to sync across devices.
← Previous안에서만 열리는 문Next →ImageGen, VideoGen, 스킬은 클라이언트 하나야
이 페이지에서 버그를 발견하셨거나 피드백이 있으세요?문제 신고

댓글 0

🔔 답글 알림 (로그인 필요)
로그인 — 댓글을 남기려면 로그인해 주세요.

아직 댓글이 없어요. 첫 댓글을 남겨보세요.