--- title: "Hướng dẫn Developer" description: "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." url: "https://sotaagents.ai/vi/manual/developer-guide" generated_by: "sotaagents-ldp" docs_index: "https://sotaagents.ai/manual/llms.txt" locale: "vi" --- # 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. - [App làm được gì](https://sotaagents.ai/vi/manual/developer-guide/what-apps-can-do): 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… - [Triết lý kiến trúc](https://sotaagents.ai/vi/manual/developer-guide/architecture-philosophy): SotaAgents 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 đã… - [Lifecycle & environment](https://sotaagents.ai/vi/manual/developer-guide/lifecycle-and-environments): Dữ 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. - [Sota CLI](https://sotaagents.ai/vi/manual/developer-guide/sota-cli): Sota 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. - [Tạo project](https://sotaagents.ai/vi/manual/developer-guide/create-a-project): sota 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… - [Giải thích Manifest](https://sotaagents.ai/vi/manual/developer-guide/manifest-explained): manifest.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… - [Trang Workspace](https://sotaagents.ai/vi/manual/developer-guide/workspace-pages): Workspace 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… - [Trang cài đặt người dùng](https://sotaagents.ai/vi/manual/developer-guide/user-settings-pages): User 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… - [Trang Admin](https://sotaagents.ai/vi/manual/developer-guide/admin-pages): Admin 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. - [Tool view](https://sotaagents.ai/vi/manual/developer-guide/tool-views): tool-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… - [Message part](https://sotaagents.ai/vi/manual/developer-guide/message-parts): Native 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… - [Artifact surface](https://sotaagents.ai/vi/manual/developer-guide/artifact-surfaces): Artifact 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… - [Workspace card](https://sotaagents.ai/vi/manual/developer-guide/workspace-cards): card 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. - [Composer action](https://sotaagents.ai/vi/manual/developer-guide/composer-actions): composer-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. - [Composer panel](https://sotaagents.ai/vi/manual/developer-guide/composer-panels): composer-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… - [useAppContext](https://sotaagents.ai/vi/manual/developer-guide/use-app-context): useAppContext() 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. - [useAppFetch](https://sotaagents.ai/vi/manual/developer-guide/use-app-fetch): useAppFetch() 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… - [useLocale](https://sotaagents.ai/vi/manual/developer-guide/use-locale): useLocale() 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… - [useTheme](https://sotaagents.ai/vi/manual/developer-guide/use-theme): useTheme() 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. - [Platform UI components](https://sotaagents.ai/vi/manual/developer-guide/platform-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… - [Platform icons](https://sotaagents.ai/vi/manual/developer-guide/platform-icons): @sota/platform/icons expose các icon name ổn định: alert, check, chevronDown, chevronLeft, chevronRight, close, info, loading, search, settings, warning. - [Lifecycle của surface](https://sotaagents.ai/vi/manual/developer-guide/surface-lifecycle): useAppContext().lifecycle sở hữu resource cho một surface mount. Cleanup chạy khi unmount hoặc exact runtime identity đổi. - [Platform UI bridge](https://sotaagents.ai/vi/manual/developer-guide/platform-ui-bridge): useAppContext().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. - [useComposer](https://sotaagents.ai/vi/manual/developer-guide/use-composer): useComposer(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… - [Deferred tool result](https://sotaagents.ai/vi/manual/developer-guide/deferred-tool-results): App 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… - [UI contract helpers](https://sotaagents.ai/vi/manual/developer-guide/ui-contract-helpers): Generated 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. - [Develop local](https://sotaagents.ai/vi/manual/developer-guide/local-development): Develop 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… - [Validate & test](https://sotaagents.ai/vi/manual/developer-guide/validate-and-test): - [Deploy Staging](https://sotaagents.ai/vi/manual/developer-guide/deploy-staging): Browser 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… - [Release Production](https://sotaagents.ai/vi/manual/developer-guide/release-production): Release 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 ở… - [Đưa lên App Store](https://sotaagents.ai/vi/manual/developer-guide/publish-to-app-store): Production 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. - [Best practices](https://sotaagents.ai/vi/manual/developer-guide/best-practices): Mỗi tool một nhiệm vụ, schema chặt, timeout hữu hạn, failure mode an toàn. - [Xử lý sự cố Developer](https://sotaagents.ai/vi/manual/developer-guide/developer-troubleshooting): Lệnh hữu ích: sota status, sota logs, sota manifest diff và sota docs.