Studio AI와 OKF 지식

Studio AI는 llamon studio 안에서 코드 변경안을 만들며 에이전트 런타임이나 사용자 요청 경로에는 관여하지 않습니다. 모델은 근거가 담긴 제안 JSON만 반환하고, 파일은 미리보기·서버 진단·사용자 적용을 거쳐 저장됩니다.

Flow evaluator 설정은 Studio AI 제안과 별개입니다. Flow 캔버스의 노드 설정 패널 Runtime 평가에서 app.evaluation named ref, 결과·오류 정렬 순서, timeout을 편집합니다. evaluator는 병렬로 실행되므로 정렬은 실행 순서가 아닙니다. selector는 app/evaluation.py를 import·실행하지 않고 정적으로 읽으며 inline constructor를 차단합니다. 상세 계약

어디까지 하는가

구분	역할
읽는 지식	SDK의 읽기 전용 OKF bundle, 프로젝트 `okf/*.md`, 현재 프로젝트 파일
만드는 결과	코드와 OKF 문서의 변경 제안
저장 경계	preview → 진단 → 사용자 apply
하지 않는 일	fine-tuning, 런타임 메모리, vector DB, 자동 파일 저장

SDK wheel에는 공통 개발 가이드와 core bundle이 들어 있습니다. 프로젝트 루트의 okf/는 팀이 설계 결정과 코드 접점을 남기는 wiki입니다. SDK는 이를 검색하지만 일반 package에 OKF producer를 넣지 않습니다.

Runtime은 v0.1 timestamp와 v0.2 중첩 metadata를 보존해 읽고, 새 제안은 generated.by·generated.at만 씁니다. lifecycle·trust는 관찰용이며 Attested Computation을 실행하지 않습니다. 기존 검색 확장 필드와 외부 bundle도 계속 지원합니다.

OKF는 Studio AI의 허용 목록이나 지식 한계가 아니라 프로젝트 규칙을 우선 적용하는 참고 근거입니다. OKF에 없는 Python 문법·표준 라이브러리·알고리즘·테스트·독립 예제도 일반 지식으로 다룹니다. 기존 API를 수정할 때는 실제 프로젝트 파일을 source of truth로 삼고, 파일과 OKF가 모두 없어 인터페이스를 추측해야 하면 확인 질문으로 멈춥니다.

프로젝트 지식 작성

프로젝트 지식은 concept 하나당 Markdown 파일 하나로 작성합니다. scaffold가 okf/를 자동 생성하지는 않습니다.

---
type: contract
title: Payment fallback routing
description: 결제 provider 실패 시 fallback provider로 라우팅하는 정책.
resource: docs/payment-routing.md
tags: [payment, routing]
aliases: 결제 fallback, payment failover
query_examples:
  - PG 장애 시 fallback 수정
negative_queries:
  - 결제 용어만 설명
symbols: PaymentRouter, route_payment
key_files: app/payment_router.py, app/graph.py
generated:
  by: process:llamon-studio-ai
  at: 2026-06-27T00:00:00+09:00
---

필드	작성 기준
`type`	`subsystem`, `flow`, `component`, `contract`, `port`, `adapter` 중 하나
`title`·`description`·`generated.by`·`generated.at`	정체성, 작성 actor, 변경 시각
`key_files`	실제 프로젝트 파일. 디렉터리는 `app/`처럼 끝에 `/`를 붙임
`query_examples`	사용자가 실제로 할 법한 요청. 강한 검색 신호
`negative_queries`	비슷하지만 이 concept가 맡지 않을 요청
`symbols`·`aliases`	코드 심볼과 다른 표현

.env 같은 secret 파일은 key_files로 가리킬 수 없고 .env.example은 경로 참조만 허용됩니다. .env.example도 모델 문맥에서는 운영 설정 allowlist를 제외한 값을 <redacted>로 바꿉니다. 본문은 Purpose, Key files, Runtime behavior, Relationships, Codegen notes 순서로 쓰면 사람과 모델이 같은 구조로 읽습니다.

요청부터 적용까지

작은 화면에서는 좌우로 스크롤하세요. 전체 화면은 검색 근거와 저장 전 안전 경계를 함께 보여 줍니다.전체 화면에서 보기 ↗

Studio AI는 요청마다 아래 순서로 필요한 근거만 모읍니다.

프로젝트 okf/와 SDK bundle에서 관련 concept를 찾습니다.
key_files, 명시한 경로와 코드 심볼로 현재 파일을 확인합니다.
선택한 문서와 파일을 예산 안의 context pack으로 줄입니다.
모델이 코드·지식 변경안을 JSON으로 반환합니다.
서버 진단과 checksum 검증을 통과한 제안만 사용자가 적용합니다.

일반 코딩 요청은 OKF 검색 결과가 없어도 모델 호출을 계속합니다. 사용자가 새 파일의 프로젝트 상대 경로를 지정하면 해당 경로의 변경안으로 만들 수 있고, 경로를 지정하지 않은 독립 예제는 파일을 임의로 만들지 않고 답변에 코드를 담습니다.

프로젝트 OKF가 있고 규칙 검색과 실제 파일 근거가 모두 약할 때만 검색어 확장 모델을 한 번 부릅니다. 경로·심볼이 바로 맞으면 이 단계를 건너뜁니다. 단순한 graph 노드 삭제처럼 서버가 안전하게 확정할 수 있는 작업은 fast_path_ready로 처리하고 모델 호출을 생략합니다.

검색 근거와 실행 여부

검색 신호는 대체로 경로·key_files → query_examples → symbols → 제목·별칭 → 설명·태그 → 본문 순으로 강합니다. 프로젝트 문서가 SDK bundle보다 우선하며, negative_queries가 맞으면 상위 결과라도 바로 실행 가능한 근거로 보지 않습니다.

직접 찾은 concept의 관계는 한 단계만 넓힙니다. key_files 공유, wiki link, 상대 Markdown link와 backlink를 사용하며 기본 상한은 concept당 2개, 전체 4개입니다. OKF 근거가 부족하면 Python signature와 검색어 주변의 실제 파일 snippet을 붙입니다. 빌드 산출물, 의존성 디렉터리와 secret 경로는 파일 검색에서 제외합니다. 아직 wiki에 없는 파일은 unindexedLiveFiles로 표시합니다.

context.retrieval.actionability가 모델 호출 여부를 결정합니다.

상태	의미	동작
`ready`	문서와 실제 파일 근거가 충분함	변경안 생성
`needs_review`	구현 표면은 찾았지만 근거가 일부 약함	안전 지시와 함께 생성, preview에서 검토
`needs_clarification`	기존 프로젝트 수정 대상이 불분명함	모델을 부르지 않고 기능명·오류·파일명 요청

confidence는 high, medium, low이며 topHit과 suggestedQuestions는 UI가 판단 근거를 설명할 때 사용합니다. 파일명을 말하지 않았더라도 안전한 구현 표면을 찾으면 진행할 수 있지만, *.py의 py처럼 넓은 토큰 일치만으로 ready가 되지는 않습니다.

context pack과 예산

검색 문서와 파일에는 contextHeader가 붙습니다. bundle, id, 제목, match reason, key_files와 live path를 담아 모델과 UI가 같은 근거를 가리키게 합니다. 여러 concept를 함께 볼 때만 link와 backlink로 계산한 conceptDigest를 추가합니다.

서버는 provider의 자동 truncation에 맡기지 않고 최종 프롬프트를 직접 줄입니다.

영역	기본 상한
전체 프롬프트	48k chars
OKF context	12k
현재 파일 snippet	10k
대기 중인 diff	4k
대화	최근 6개

safe compaction은 API가 반환하는 원본 context를 바꾸지 않고 모델에 넣을 복사본만 줄입니다. 문서 ID, 타입, 제목, 경로, 심볼과 query example은 보존합니다. 코드 fence, URL, 환경 변수와 명령어 같은 anchor도 중간에서 자르지 않습니다. 실제 파일, proposal schema, safety rule과 pending diff는 압축 대상이 아닙니다. 압축에 실패하면 프롬프트 복사본만 원본으로 되돌립니다.

최종 예산을 맞출 때는 대기 중인 diff와 오래된 대화를 먼저 줄이고, 현재 프로젝트 코드와 검색된 OKF 참고 조각이 함께 남도록 section 단위로 조정합니다. OKF가 프로젝트 코드보다 높은 권한을 갖는 것은 아니며, 둘이 충돌하면 현재 코드와 명시적인 사용자 요청을 기준으로 preview합니다.

prompt_ready 로그에는 okf_raw_chars, okf_compacted_chars, okf_saved_chars, prompt_raw_chars와 prompt_chars가 남습니다. 모두 토큰 수가 아니라 문자 수입니다. stream은 context_start, prompt_ready, fast_path_ready 또는 model_waiting, preview_ready 순서로 진행 상태를 알립니다.

지식 갱신과 적용 검증

Endpoint	역할
`GET /api/studio-ai/knowledge/status`	파일 fingerprint로 `covered`, `stale`, `unindexed` 계산
`POST /api/studio-ai/knowledge/refresh`	기존 OKF 원문을 보존 근거로 포함해 문서 갱신안을 preview로 생성
`POST /api/studio-ai/chat`	코드 변경과 wiki 갱신 필요성을 함께 판단
`POST /api/studio-ai/apply`	checksum과 `ProjectLock` 아래에서 승인한 edit를 파일별 atomic replace하고 오류 시 전체 edit를 복구

오류 응답

기본 HTTP 오류는 기존 detail 문자열을 유지합니다. X-LLaMON-Diagnostics: structured opt-in은 HTTP와 stream에 error·message·retryable·diagnostics·metadata를 노출하며 stream의 status·elapsedMs·optional stage도 보존합니다.

Core의 transport-neutral StudioAiError를 HTTP·SSE·향후 CLI adapter가 각 응답으로 투영합니다.

.llamon/studio-ai-knowledge.json은 파일 SHA와 concept coverage만 저장하는 보조 파일입니다. OKF 본문이나 검색 cache는 넣지 않습니다.

지식 갱신 프롬프트에는 선택한 코드와 연결된 기존 OKF 문서를 함께 넣습니다. 긴 문서가 예산을 넘으면 한 문서의 앞부분만 남기지 않고 top-level section별로 배분해 뒤쪽 Relationships, Codegen notes와 wiki link도 보존합니다. 모델은 source code나 사용자의 명시적 요청과 충돌하지 않는 한 사람이 작성한 설명과 관계를 유지해야 합니다.

적용 전 진단은 잘못된 Python 문법, 잘못된 type, 필수 metadata 누락, 잘못된 generated.by·generated.at, 존재하지 않는 key_files, secret 참조, 따옴표 없는 #, okf/README.md, 자기 자신만 가리키는 link와 과도한 검색 필드를 차단합니다. .env와 .env.*는 허용한 key만 수정하며 secret 값은 모델에 <redacted>로 전달합니다. credentials.*, private key, secrets/, .docker/, .kube/ 같은 credential 위치는 검색·프롬프트·편집 대상에서 제외합니다. preview 뒤 파일이 바뀌면 apply는 409로 실패합니다. 여러 파일 중 하나의 쓰기가 실패하면 앞서 쓴 파일과 OKF coverage sidecar, 이번 apply가 만든 빈 디렉터리도 원상 복구합니다. 완료 뒤 history 정리는 best-effort라 정리 실패가 이미 적용된 요청을 500으로 바꾸지 않습니다. 모델이 보낸 evidence도 이 검증을 우회하지 못합니다.

패키징과 폐쇄망

Bundle	내용	원본
`sdk-core`	SDK core concept	`tools/okf/corpus/core/`
`agent-dev-guide`	현재 Astro 개발 문서	`apps/docs/src/content/docs/`

두 bundle은 wheel에 포함되는 읽기 전용 package data라 폐쇄망에서도 검색됩니다. 프로젝트별 지식이 있을 때만 루트에 okf/를 추가하세요. 외부 okf-bundle/도 표준 필드와 본문만으로 읽습니다.

SDK maintainer는 문서를 바꾼 뒤 just okf-package로 bundle을 갱신하고 just okf-package-check로 원본과의 일치를 확인합니다. 패키지된 개발 가이드에서는 changelog를 제외해 과거 릴리스 설명이 현재 기능보다 먼저 검색되지 않게 합니다.