Hướng dẫn Developer
Xây dựng, kiểm thử, deploy, release và đưa một SotaAgents app lên App Store theo một quy trình thống nhất.
01App làm được gìSotaAgents app là một gói năng lực có version, dùng để mở rộng nền tảng trong tổ chức và workspace. Một app có thể cung cấp tools cho trợ lý gọi, skills hướng dẫn workflow, nati…02Triết lý kiến trúcSotaAgents chủ động tách platform control plane khỏi app data plane. Platform biết user, organization, workspace, installation, selected environment, exact artifact và quyền đã…03Lifecycle & environmentDữ liệu Staging không bao giờ tự sang Production. Nếu hai binding trỏ về cùng external backend thì app phải tự chịu trách nhiệm isolation.04Sota CLISota CLI là developer interface chính thức: tạo project, validate manifest, build UI contracts, mở Development session, tạo immutable Staging artifact và promote lên Production.05Tạo projectsota init tạo scaffold tương thích manifest schema v3. Chạy không kèm --features thì CLI hỏi capability cần scaffold; truyền --features admin-screen,skill,backend,tool,tool-resu…06Giải thích Manifestmanifest.yaml là contract khai báo giữa app và SotaAgents: app là gì, đóng góp gì, backend ở đâu, native module nào được load và hỗ trợ platform version nào. Server luôn validat…07Trang WorkspaceWorkspace page là một màn hình hoàn chỉnh do app sở hữu, mở từ navigation của workspace. Core resolve app execution hiện tại của lane đã cài, giữ routing và mount boundary rồi r…08Trang cài đặt người dùngUser settings page là tab do app sở hữu bên trong Account Settings. Tab chỉ xuất hiện khi Core có workspace đang hoạt động rõ ràng và app đã được cài, bật, cho phép trong worksp…09Trang AdminAdmin page vẫn là primitive page, nhưng được đặt trong phần quản trị workspace. Dùng nó cho cấu hình và vận hành app, không phải workflow thường ngày của member.10Tool viewtool-view thay thế hoặc bổ sung cách hiển thị tool call do cùng app khai báo. Gắn nó bằng toolNames không rỗng. Core truyền đúng một prop toolResult và giữ nguyên mount khi stat…11Message partNative message-part là tool surface inline đặt dưới chat message liên quan. Nó dùng cùng ToolResultSurfaceProps, state, context của producer lane, toolNames và renderBeforeOutpu…12Artifact surfaceArtifact surface sở hữu phần body của side panel bền vững. Khai báo artifactKind ổn định có namespace của app; Core dùng nó để resolve native module hiện tại trong app lane khi…13Workspace cardcard là UI gọn của app trong vùng assistant của workspace. Nó không nhận card-specific props; dùng platform hooks cho context, data và actions.14Composer actioncomposer-action là action gọn do app sở hữu, nằm cạnh control của chat input. Nó phù hợp để mở UI hoặc bắt đầu workflow của app.15Composer panelcomposer-panel là UI contextual phía trên composer. Đây là surface duy nhất được bind public composer API: quan sát draft, edit atomically, đọc deferred result pending của exact…16useAppContextuseAppContext() là runtime API chính cho mọi hosted native surface. Import từ @sota/platform; hook throw nếu không có app surface provider.17useAppFetchuseAppFetch() trả về authenticated data-plane fetcher của surface. Truyền path tương đối của app và RequestInit; Core resolve dưới backend của environment đã chọn, inject bearer…18useLocaleuseLocale() trả về { locale, t }. locale là locale thực sự load cho surface. t(key, values) đọc message file đã khai báo và interpolate named values; key app bị thiếu fallback s…19useThemeuseTheme() trả về 'light' hoặc 'dark' và re-render theo host theme. API này read-only: app thích ứng với workspace, không đổi theme của Core.20Platform UI components@sota/platform/ui là component library public cho native app. Component kế thừa token, theme, focus behavior, portal và accessibility default của Core. Import từ entry point này…21Platform icons@sota/platform/icons expose các icon name ổn định: alert, check, chevronDown, chevronLeft, chevronRight, close, info, loading, search, settings, warning.22Lifecycle của surfaceuseAppContext().lifecycle sở hữu resource cho một surface mount. Cleanup chạy khi unmount hoặc exact runtime identity đổi.23Platform UI bridgeuseAppContext().ui cho phép app-owned UI yêu cầu host thực hiện presentation thuộc host. Đây là primitives, không phải business workflow.24useComposeruseComposer(selector) chỉ chạy trong hosted composer-panel và throw ở nơi khác. Import từ @sota/core/hooks. Chỉ select field component cần để thay đổi không liên quan không gây…25Deferred tool resultApp backend có thể defer kết quả của chính tool call hiện tại mà không tạo user message hay bắt model gọi lại tool. Core chỉ hiểu operation id và app data opaque; login, approva…26UI contract helpersGenerated package @sota/platform còn expose metadata của build contract và một typed descriptor helper. Manifest v3 vẫn là authority đăng ký contribution.27Develop localDevelop local dùng hai process độc lập ở hai terminal. Bạn sở hữu watcher của app; CLI sở hữu Development session và tunnel dẫn về máy bạn. Sota CLI không bao giờ start, restart…28Validate & test29Deploy StagingBrowser không thể load source từ laptop developer một cách an toàn và reproducible. Deploy biến declared app surface thành immutable, content-addressed bytes để mọi screen, tool…30Release ProductionRelease promote chính exact Staging artifact hiện tại lên Production. Nó không rebuild, không copy Staging data và không chờ duyệt release. Production release đầu tiên bắt đầu ở…31Đưa lên App StoreProduction release và App Store listing là hai quyết định độc lập. Production có thể Private hoặc Restricted mà không xuất hiện trong public catalog.32Best practicesMỗi tool một nhiệm vụ, schema chặt, timeout hữu hạn, failure mode an toàn.33Xử lý sự cố DeveloperLệnh hữu ích: sota status, sota logs, sota manifest diff <left> <right> và sota docs.
