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에 그대로 등록되고 돌아요.