開発者ガイド
SotaAgents アプリの作成、テスト、デプロイ、リリース、App Store 公開までを一貫した流れで説明します。
01アプリでできることSotaAgents アプリは、組織とワークスペース内でプラットフォームを拡張する、バージョン管理された Capability パッケージです。Tool、Skill、Native UI、tool-result renderer、hook、event、prompt、スコープ付きデータアクセスを提供できます。プラットフォームは identity、インストー…02Architecture philosophySotaAgents は platform control plane と app data plane を意図的に分離します。Platform は user、organization、workspace、installation、selected environment、exact artifact、capability を理解し、app backe…03Lifecycle と environmentStaging data は Production に promote されません。両 binding が同じ外部 backend を使う場合、isolation はアプリ側の責任です。04Sota CLISota CLI は正式な developer interface です。Project scaffold、manifest 検証、UI contract build、Development session、Staging artifact、Production promote を扱います。05Project 作成sota init は manifest schema v3 対応 scaffold を作ります。--features なしでは capability を対話選択でき、--features admin-screen,skill,backend,tool,tool-result-ui（または all）で事前指定できます。後から sota add で追加で…06Manifest の説明manifest.yaml はアプリと SotaAgents 間の宣言的 contract です。Identity、contribution、backend、load 可能な native module、platform compatibility を記述します。Server が再検証するため、client manifest は authority で…07Workspace pageWorkspace page は workspace navigation から開く、アプリ所有の完全な画面です。Core は install 済み lane の current app execution を resolve し、routing と mount boundary を所有して export component を描画します。Bounda…08User settings pageUser settings page は Account Settings 内に表示されるアプリ所有のタブです。Core が明示的な active workspace を持ち、その workspace でアプリが install・enable・admit されている場合だけ表示されます。09Admin pageAdmin page は同じ native page primitive を workspace administration に配置したものです。App 設定と運用 control に使い、通常 member の workflow には使いません。10Tool viewtool-view は同じアプリが宣言した tool call の表示を置換または拡張します。空でない toolNames で結び、Core は一つの toolResult prop を渡して state 変化中も同じ mount を維持します。11Message partNative message-part は該当 chat message の下に mount される inline tool surface です。Tool view と同じ ToolResultSurfaceProps、state、producer lane context、toolNames、任意の renderBeforeOutput contr…12Artifact surfaceArtifact surface は durable side-panel view の body を所有します。安定した app namespace の artifactKind を宣言し、Core は open 時にその app lane の current native module を resolve します。13Workspace cardcard は workspace assistant 領域に置く compact app UI です。Card 固有 props はなく、context、data、action は platform hook から取得します。14Composer actioncomposer-action は chat input control の横に置く compact な app-owned action です。15Composer panelcomposer-panel は composer 上部の contextual app UI で、public composer API に bind される唯一の surface です。Draft の観察と atomic edit、exact execution の pending deferred result、composer lock を利用…16useAppContextuseAppContext() は hosted native surface の中心 runtime API です。@sota/platform から import し、app surface provider の外では throw します。17useAppFetchuseAppFetch() は surface の authenticated data-plane fetcher を返します。App-relative path と通常の RequestInit を渡すと、Core が選択 environment の backend 配下へ resolve し、bearer credential と mount c…18useLocaleuseLocale() は { locale, t } を返します。locale は app surface に実際に load された locale、t(key, values) は宣言済み app message を読み named value を補間します。不足した app key は shell translator へ fallback します。19useThemeuseTheme() は 'light' または 'dark' を返し host theme 変更時に re-render します。Read-only であり、app は workspace theme を変更しません。20Platform UI component@sota/platform/ui は native app 向けの public component library です。Core token、theme、focus behavior、portal、accessibility default を継承します。Core source path や別 copy の Radix/Recharts ではなく…21Platform icon@sota/platform/icons は安定 icon name alert、check、chevronDown、chevronLeft、chevronRight、close、info、loading、search、settings、warning を公開します。22Surface lifecycleuseAppContext().lifecycle は一つの surface mount の resource を所有し、unmount または exact runtime identity 変更時に cleanup します。23Platform UI bridgeuseAppContext().ui は app-owned UI から host-owned presentation を依頼する primitive です。Business workflow ではありません。24useComposeruseComposer(selector) は hosted composer-panel 内だけで利用でき、他では throw します。@sota/core/hooks から import し、component が必要な field だけを select します。25Deferred tool resultApp backend は user message を作らず、model に tool を再呼び出しさせずに現在の tool call result を defer できます。Core が理解するのは operation id と opaque app data だけで、login、approval、payment、device pairing など…26UI contract helper生成された @sota/platform は build contract metadata と typed descriptor helper も公開します。Manifest v3 が registration authority である点は変わりません。27Local 開発Local 開発では、2 つのターミナルで 2 つの独立した process を動かします。あなたがアプリの watcher を所有し、CLI が Development session と、手元のマシンへ届く tunnel を所有します。Sota CLI があなたの process を起動・再起動・停止することは一切ありません。Session を止め…28Validation と test29Staging deployBrowser は developer laptop の source を安全かつ再現可能には load できません。Deploy は declared surface を immutable な content-addressed bytes に変換し、全 screen、tool-result renderer、locale loader、artif…30Production releaseRelease は現在の exact Staging artifactを Production に promote します。Rebuild、Staging data copy、release approval は行いません。初回 Production は Private、以降は visibility と App Store eligibility を維…31App Store 公開Production release と App Store listing は別の判断です。Production は public catalog に出さず Private/Restricted にできます。32Best practicesTool は一つの責務、厳格な schema、有限 timeout、安全な failure mode を持たせます。33Developer troubleshooting有用な command：sota status、sota logs、sota manifest diff <left> <right>、sota docs。
