Golden Image

프로젝트 구성

project.json의 parts로 프런트엔드·백엔드를 고르고, 정해진 폴더만 고쳐요. 앱 manifest(agents.json)가 앱이 쓸 자원과 권한을 선언해요.

parts

project.json의 parts가 켤 반쪽을 정해요. 백엔드는 backend(Python) 또는 backend-node(Node) 가운데 하나예요.

parts 만드는 것 등록
["frontend"] (기본) 프런트엔드 앱 하나 frontend/dist/<release>.zip 업로드
["frontend", "backend"] 프런트엔드 + Python worker ZIP + 비공개 백엔드 연결
["backend"] 백엔드 provider 하나(Python) 비공개 백엔드 연결(URL + 미리 나눈 키)
["frontend", "backend-node"] 프런트엔드 + Node worker ZIP + 비공개 백엔드 연결
["backend-node"] 백엔드 provider 하나(Node) 비공개 백엔드 연결
project.json
{
  "parts": ["frontend"],
  "repository_contract_version": "1.0.0",
  "ai_tiers": "fast-smart-deep",
  "runtime_secrets": [],
  "data_changes": { "compatibility": "compatible", "migration": "없음", "rollback": "기존 데이터 유지" }
}

폴더

경로 역할
frontend/agent/ 앱의 프런트엔드. src/App.tsx, 패널, agents.json(manifest)
frontend/agent/src/ui/ 공통 UI 킷(토큰, 컴포넌트, 글꼴)
frontend/packages/ 가져온 SDK와 계약(sdk-core, sdk-react, agent-contracts)
backend/agent/ Python worker의 app.py와 agents.json
backend-node/agent/ Node worker의 app.ts와 agents.json
scripts/check.py schema 검증, 등록 규칙, 짝 검사
scripts/preview.sh 로컬 미리보기(내부 호스트, 공개 터널은 고를 때만)
profiles/ 공식 프로필(최소 앱 등)
Makefile setup / build / check / test / serve / preview

고치는 곳은 frontend/agent/와 backend/agent/(또는 backend-node/agent/)뿐이에요. SDK, 계약, 빌드 스크립트는 기반 업데이트가 관리하는 파일이에요. 앱의 규칙과 설명은 AGENTS.md의 "이 앱" 절에 적어요.

manifest (agents.json)

앱이 무엇을 쓰고 무엇을 내는지를 선언해요. Mothership은 등록할 때 이것을 검증하고, 회사 관리자에게 "이 버전이 요청하는 접근"으로 보여 줘요.

항목 뜻
agent id, 이름, 설명, 종류(frontend/backend)
release release_id, artifact_hash(빌드가 채워요)
resources 레코드(record_schema, 접근 범위 user_private 등), 객체 저장소(api: "storage.objects")
state_namespaces 키·값 상태(value_schema). 이름은 키만("preferences"), 앱 id 접두어는 붙이지 않아요
claims 앱이 쓰는 권한 이름. 회사 관리자가 구성원마다 허용·거부해요
capabilities.requires, resource_requests 다른 앱이 내는 기능과 공용 데이터
connector_requests 쓸 외부 도구(MCP)
runtime_profiles Runtime 프로필
trigger_templates 자동화 트리거
usage_policy 분당 요청, 동시 실행 한도

Mothership은 각 자원 선언을 게시할 때 JSON 접근 정책으로 바꿔 요청마다 평가해요. 회사 격리는 이 애플리케이션 계층 하나에서 지켜요.

계약 버전

계약 1.2.0에서 AI 등급 이름이 fast/smart/deep이 됐어요(1.1.0의 smart가 deep, default가 smart). 1.1.0으로 만든 앱은 python3 scripts/rename_ai_tiers.py로 한 번에 옮겨요. make check는 옮기거나 확인을 남기기 전까지 멈춰요. 1.1.0으로 빌드한 릴리스는 Mothership에 그대로 등록되고 돌아요.

Esc