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