패키지

ObjectOS의 조직 단위 — 버전 관리되고, 설치 가능하며, 공유할 수 있습니다.

ObjectOS에서 만드는 모든 것은 패키지 안에 존재합니다. 패키지는 버전이 관리되고 자체적으로 완결된 메타데이터 번들입니다. 패키지는 AI Builder가 작업하는 단위이자, marketplace가 배포하는 단위이며, ObjectOS가 업데이트를 추적하는 단위입니다.

패키지의 구성 요소

com.acme.crm@1.2.0
├── manifest          id, version, namespace, dependencies
├── objects/          *.object.ts, *.state.ts, *.hook.ts
├── views/            *.view.ts, *.page.ts, *.form.ts
├── actions/          *.action.ts
├── flows/            *.flow.ts, *.approval.ts
├── agents/           *.agent.ts, *.skill.ts
├── permissions/      *.permission.ts
├── sharing/          *.sharing.ts
├── translations/     en.ts, zh-CN.ts, ...
├── apps/             *.app.ts  (navigation)
└── data/             defineDataset(...) seed

모든 메타데이터 아티팩트(object, action, flow 등)는 정확히 하나의 패키지에 속합니다. 패키지 id는 reverse-DNS(com.acme.crm, org.mycompany.helpdesk) 형식이며, 네임스페이스 접두사(crm_, hd_)는 같은 테넌트에 설치된 여러 패키지 간에 테이블/object 이름이 충돌하지 않도록 합니다.

패키지 생성하기

AI Builder에서

"우리 내부 CRM용 새 패키지를 시작하고, 네임스페이스는 crm으로 해줘."

AI는 create_package와 set_active_package를 호출합니다. 그 이후로 당신이 설명하는 모든 object / field / action은 crm에 들어갑니다.

CLI에서

os init my-crm -t app
cd my-crm
# manifest lives in the `manifest:` block of ./objectstack.config.ts
pnpm dev

Console에서

Console → Packages → New Package — 이름, id, 버전, 네임스페이스.

활성 패키지

AI Builder에서는 대화가 **활성 패키지(active package)**를 가지고 있습니다. 이는 새 메타데이터의 기본 컨테이너입니다. 당신이 *"com.acme.helpdesk로 전환해줘."*와 같이 말하면 AI가 set_active_package 도구로 이를 설정합니다. CLI에서 활성 패키지는 단순히 프로젝트의 objectstack.config.ts(manifest: 블록)에 선언된 패키지입니다.

버전 관리

패키지는 semver를 따릅니다. 런타임과 동일한 규칙입니다 — Changelog & Versioning을 참고하세요.

버전을 올리더라도 게시(publish)하기 전까지는 아무것도 바뀌지 않습니다. 런타임은 테넌트별, 패키지별로 installed_version을 추적하며, 카탈로그에 더 최신 버전이 있으면 marketplace에 "Update available" 배지가 표시됩니다.

의존성

패키지는 다른 패키지에 의존할 수 있습니다:

{
  "id": "com.acme.helpdesk",
  "version": "0.3.0",
  "dependencies": {
    "com.acme.crm": "^1.0.0",
    "sys.feeds":   "*"
  }
}

런타임은 설치 시 의존성을 해석합니다. com.acme.crm이 설치되어 있지 않으면 helpdesk 설치는 명확한 오류와 함께 실패합니다.

시스템 패키지(sys.*)는 항상 존재합니다 — feeds, attachments, audit, identity 등.

게시하기

os compile                     # → dist/objectstack.json
os package publish             # → ObjectStack cloud catalog

os package publish는 컴파일된 manifest를 OS_CLOUD_URL로 구성된 클라우드 컨트롤 플레인에 업로드하며, OS_CLOUD_API_KEY로 인증합니다. 비공개/에어갭(air-gapped) 배포의 경우 게시를 건너뛰고 컴파일된 dist/objectstack.json을 대상 설치 환경에 직접 전달하세요(아래 설치 섹션 참조). Marketplace를 참고하세요.

설치하기

경로	방법
Console	Marketplace 탭 → 패키지 선택 → Install
REST	`POST /api/v1/marketplace/install-local` (본문: `{ packageId, versionId? }`)
에어갭	컴파일된 `dist/objectstack.json` 아티팩트를 마운트 (참고: Air-gapped)

설치는 패키지의 메타데이터를 실행 중인 커널에 병합하고, 해당 object들을 ObjectQL에 등록하며, 최초 설치 시 초기 데이터를 시드합니다 — 재시작이 필요 없습니다. 캐시된 설치는 다음 부팅 시 다시 등록되므로 프로세스 재시작에도 유지됩니다.

제거하기

제거는 패키지의 캐시된 manifest를 삭제하여 다음 부팅 시 더 이상 재등록되지 않도록 합니다. object 등록은 누적 방식이므로, 이미 실행 중인 패키지의 object를 완전히 언로드하려면 커널 재시작이 필요합니다. 데이터는 기본적으로 유지되므로, 다시 설치하여 이어서 사용할 수 있습니다.

패키지 간 규약

여러 패키지가 공존할 때 충돌을 방지하기 위해:

아티팩트	규약
Object 이름	항상 접두사 사용: `crm_account`, `hd_ticket`
Action 이름	접두사 사용: `crm_assign_owner`, `hd_close_ticket`
Flow 이름	접두사 사용: `hd_overdue_alert`
번역 키	네임스페이스 하위로 스코프 지정: `crm.account.label`
시드 `externalId`	`<prefix>:<key>`, 예: `crm:demo-account-1`
시스템 이름	예약됨: `sys_*` (커스텀 패키지에서 절대 사용 금지)

CLI와 AI Builder 모두 생성 시 이 규약을 강제합니다.

시스템 패키지

런타임은 항상 존재하면서 다형적(polymorphic) 서비스를 제공하는 소수의 패키지를 함께 제공합니다:

패키지	제공 항목
`sys.identity`	`sys_user`, `sys_organization`, `sys_member`, 세션, API 키
`sys.feeds`	`sys_comment`, `sys_activity`, `sys_attachment`
`sys.audit`	`sys_audit_log`
`sys.files`	`sys_file`
`sys.ai`	`ai_conversations`, `ai_pending_actions`
`sys.settings`	`sys_setting`

object에서 enable: { feeds: true, trackHistory: true, … }를 통해 활성화할 수 있습니다 — Data Model을 참고하세요.

다음으로 볼 곳

Marketplace — 다른 테넌트에 패키지 배포
Data Model — 패키지 안에 들어가는 것
os package commands — 전체 CLI 레퍼런스

On this page