@agent-native/core 0.88.0 → 0.90.1

package/corpus/core/docs/content/locales/zh-TW/agent-native-toolkit.mdx

@@ -1,61 +1,103 @@
 ---
-title: "Agent-Native 工具包"
-description: "用於協作、設定、分享、導覽、線上狀態、歷史、配置和 Agent UX 的可重用套件。"
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
 ---
 
-# Agent-Native 工具包
-
-Agent-Native 應用程式不應重複建置 workspace 的通用能力。應用程式負責自己的領域模型、
-領域 actions 和產品視圖。Framework 與 `@agent-native/toolkit` 負責每個應用程式都應繼承的
-可重用產品表面：協作、分享、設定、導覽、組織、配置、Agent UX、歷史和營運可見性。
-
-使用者應該只學會一種分享方式、一種連接金鑰的方式、一種看到 Agent 一起編輯的方式、一個設定入口，
-以及一種理解變更的方式。
-
-## 工具包契約 {#toolkit-contract}
-
-當行為符合以下條件時，應移到 toolkit：
-
-- **Workspace 層級** - 使用者期待所有應用程式都一致。
-- **Agent 可見** - Agent 需要透過 actions、instructions 或 application state 使用同一能力。
-- **受治理** - 權限、audit、secrets、組織政策、billing 或分享規則會參與。
-- **重複出現** - 兩個應用程式已經建了相似 UI 或邏輯。
-- **非領域專屬** - 應用程式提供 resource 名稱與 actions，但互動模式是通用的。
-
-如果行為綁定領域模型、專屬 workflow 或應用程式自己的心智模型，就保持 app-local。
-
-## 可重用套件 {#reusable-kits}
-
-- **Settings kit** - account、workspace、AI models、LLM keys、connections、secrets、
-  usage、notifications、changelog 和 app preferences 的標準 tabs。持久設定放在 Settings；
-  Agent sidebar 只保留情境 quick controls 與 deep links。
-- **Collaboration kit** - real-time editing、Yjs docs、presence、agent presence、live
-  cursors、remote selections、recent edit highlights 和 shared undo/redo。請參閱
-  [Real-Time Collaboration](/docs/real-time-collaboration)。
-- **Sharing kit** - 用一個隱私與權限模型處理 private、workspace、org、public link、invites、
-  roles、expirations 和 agent-readable access。請參閱 [Sharing & Privacy](/docs/sharing)。
-- **Navigation and command kit** - app shell、nav、breadcrumbs、app switcher、command
-  palette、recents、pinned resources 和 search。
-- **Organization kit** - folders、tags、favorites、archive、trash、ownership、membership
-  和 common metadata。
-- **Setup and connections kit** - API keys、OAuth、connections、model readiness、
-  missing secrets 和 declarative onboarding。請參閱
-  [Workspace Connections](/docs/workspace-connections)。
-- **Agent UX kit** - sidebar、composer、staged context、mentions、voice、human approval、
-  generative UI、progress 和 Agent-visible state。
-- **History and recovery kit** - audit log、activity feed、version history、checkpoints、
-  undo、redo、restore 和 proof-of-done。請參閱 [Audit Log](/docs/audit-log)。
-- **Comments and review kit** - anchored comments、pins、mentions、review requests、
-  resolved threads 和 Agent follow-up tasks。
-- **Workflow and observability kit** - notifications、approvals、background runs、
-  recurring jobs、traces、evals、feedback 和 run timelines。請參閱
-  [Observability](/docs/observability)。
-
-## 實作順序 {#implementation-order}
-
-1. 將持久設定合併到標準 Settings tabs。
-2. 用共享 adapters 統一 collaboration、presence、agent presence、undo/redo 和 real-time editing。
-3. 將 navigation、commands、recents、favorites、folders、tags、archive 和 trash 移入共享 primitives。
-4. 讓所有可分享 resource 註冊到同一 permissions 和 agent-readable access 模型。
-5. 為每個 collaborative resource 提供一致的 activity、comments、review、restore 和 audit 體驗。
-6. 統一 notifications、approvals、run status、traces、evals 和 feedback。
+# Toolkit
+
+`@agent-native/core` owns the foundational runtime: actions, app state, auth,
+SQL, server plugins, agent chat, sharing access checks, and collaboration
+transport. `@agent-native/toolkit` owns reusable app-building pieces that sit on
+top of that runtime: UI primitives, app-local adapters, shell helpers, sharing
+badges, and collaboration UI.
+
+Apps should compose those pieces through local adapters. That keeps app UI easy
+to customize without copying Toolkit implementation code.
+
+<WireframeBlock id="doc-block-toolkit-layering">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;padding:48px 36px;display:flex;align-items:center;justify-content:center'><div style='width:min(900px,100%);display:grid;grid-template-columns:1fr;gap:18px'><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>App</strong><p class='wf-muted' style='margin:6px 0 0'>Domain routes, actions, local UI adapters, product-specific views</p></div><span class='wf-pill'>@/components/ui/button</span></div></div><div class='wf-card' style='padding:22px 24px;border-color:hsl(var(--primary))'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Toolkit</strong><p class='wf-muted' style='margin:6px 0 0'>Reusable primitives, collab UI, sharing UI, app shell hooks</p></div><span class='wf-pill'>ToolkitProvider</span></div><div style='display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin-top:16px'><span class='wf-pill'>UI</span><span class='wf-pill'>Collab UI</span><span class='wf-pill'>Sharing UI</span><span class='wf-pill'>Shell</span></div></div><div class='wf-card' style='padding:22px 24px'><div style='display:flex;align-items:center;justify-content:space-between;gap:16px'><div><strong>Core</strong><p class='wf-muted' style='margin:6px 0 0'>Actions, SQL, auth, sharing runtime, Yjs transport, app state</p></div><span class='wf-pill'>@agent-native/core</span></div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## What Ships Today {#what-ships-today}
+
+- **UI primitives**: shadcn-style components under
+  `@agent-native/toolkit/ui/*`.
+- **App adapters**: template-local wrappers such as
+  `@/components/ui/button` that re-export Toolkit primitives until an app wants
+  to customize them.
+- **ToolkitProvider**: an override layer that lets reusable Toolkit UI use an
+  app's local primitives, starting with `Button`.
+- **Collaboration UI**: presence avatars, live cursors, remote selection rings,
+  recent edit highlights, and agent presence chips under
+  `@agent-native/toolkit/collab-ui`.
+- **Sharing UI**: the reusable `VisibilityBadge` under
+  `@agent-native/toolkit/sharing`.
+- **Shell and hooks**: app-shell header actions plus shared hooks such as
+  `useIsMobile` and `useToast`.
+
+## Compatibility {#compatibility}
+
+Existing imports from `@agent-native/core/client` keep working. Core now exposes
+thin re-export shims for Toolkit-owned visual pieces while keeping runtime
+behavior in core.
+
+Those core shims are temporary migration support, not the long-term dependency
+direction. The next major can remove them; after that, reusable app-building
+packages should import Toolkit directly, and behaviorful Toolkit kits may compose
+core runtime APIs as peer/runtime dependencies instead of pushing more UI back
+into core.
+
+Extract future behaviorful kits one at a time before broadening the split.
+Sharing is the first candidate to validate that model because it exercises
+access checks, action-backed data, and share-link UI together.
+
+That means this keeps working:
+
+```tsx
+import { PresenceBar, VisibilityBadge } from "@agent-native/core/client";
+```
+
+New reusable app code should prefer Toolkit or app-local adapters:
+
+```tsx
+import { PresenceBar } from "@agent-native/toolkit/collab-ui";
+import { Button } from "@/components/ui/button";
+```
+
+## Boundary {#boundary}
+
+Move code into Toolkit when it is reusable app-building UI or a pure UI contract.
+Keep code in core when it owns access control, SQL, actions, request context,
+Yjs transport, auth, or other runtime guarantees.
+
+Good Toolkit candidates:
+
+- Components that render the same interaction across apps.
+- Display-only helpers and structural prop types.
+- Base components that receive data and callbacks from an app or core wrapper.
+- App-shell hooks and adapters that do not own domain data.
+
+Keep app-local:
+
+- Domain-specific workflows.
+- Resource-specific mutations and routes.
+- Custom visual systems an app intentionally owns.
+
+Keep core-owned:
+
+- Sharing actions and access checks.
+- Collaboration storage, awareness transport, and Yjs document sync.
+- Auth, sessions, app state, SQL, and server plugins.
+
+## Pages {#pages}
+
+- [UI Primitives](/docs/toolkit-ui)
+- [App Adapters](/docs/toolkit-app-adapters)
+- [Collaboration UI](/docs/toolkit-collaboration-ui)
+- [Sharing UI](/docs/toolkit-sharing-ui)
+- [Shell & Hooks](/docs/toolkit-shell-hooks)

package/corpus/core/docs/content/locales/zh-TW/cloneable-saas.mdx

@@ -1,19 +1,19 @@
 ---
-title: "範本"
+title: "應用程式"
 description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包括代理。"
 ---
 
-# 範本
+# 應用程式
 
-想要發布您自己的人工智慧分析工具嗎？郵件用戶端？表格生成器？選取一個範本，您只需幾分鐘即可獲得一個可執行的 SaaS — 代理、資料庫、驗證和部署管道已連線完畢。
+想要發布您自己的人工智慧分析工具嗎？郵件用戶端？表格生成器？選取一個範例應用程式，您只需幾分鐘即可獲得一個可執行的 SaaS — 代理、資料庫、驗證和部署管道已連線完畢。
 
-大多數“範本”都會為您提供一個空白的腳手架和一個很長的 TODO 清單。Agent-Native 翻轉了這一點。每一個都是**完整的 SaaS 級產品** - 在第一天就已經可以執行，已經可以發貨，並且完全由您來定制、品牌化和部署。將它們視為可克隆的 SaaS，而不是入門工具包：您正在分叉成品，而不是盯著樣板檔案。
+大多數入門範本都會為您提供一個空白的腳手架和一個很長的 TODO 清單。Agent-Native 翻轉了這一點。每個範例應用程式都是**完整的 SaaS 級產品** - 在第一天就已經可以執行，已經可以發貨，並且完全由您來定制、品牌化和部署。將它們視為可克隆的 SaaS，而不是入門工具包：您正在分叉成品，而不是盯著樣板檔案。
 
-## 可用範本 {#catalog}
+## 範例應用程式 {#catalog}
 
 每一個都是您今天可以使用的真實應用程式，以及您自己版本的啟動板。
 
-| 範本                                      | 它是什麼                                                                                        |
+| 應用程式                                  | 它是什麼                                                                                        |
 | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
 | [**Chat**](/docs/template-chat)           | 最小的聊天優先應用程式，具有持久對話串、actions、驗證以及通往自訂 UI 或您自己的後端的幹淨路徑。 |
 | [**Mail**](/docs/template-mail)           | Agent-Native 超人。收件箱、標籤、人工智慧分類、鍵盤優先、透過代理起草和傳送。                   |
@@ -35,16 +35,16 @@ description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包
 
 ## 開箱即用的東西 {#what-you-get}
 
-每個範本都附帶通常需要數月才能建置的部件：
+每個範例應用程式都附帶通常需要數月才能建置的部件：
 
 - **工作代理** — 已經連線到應用程式，已經能夠在您的資料上取得 actions，已經能夠了解您正在檢視的內容。請參閱 [Messaging the agent](/docs/messaging) 了解其工作原理。
 - **Auth** — 登入、工作階段、組織、多租戶隔離。已經完成了。
-- **資料庫** — 每個範本都有其架構、查詢和遷移準備就緒。帶上您自己的 SQL 資料庫（Postgres、SQLite、Turso、D1）——框架會進行調整。
+- **資料庫** — 每個範例應用程式都有其架構、查詢和遷移準備就緒。帶上您自己的 SQL 資料庫（Postgres、SQLite、Turso、D1）——框架會進行調整。
 - **即時 UI** — 螢幕與代理的操作保持同步。在聊天中點選“草稿電子郵件”，草稿立即出現在您的收件箱中。
 - **部署就緒** — 推送到 Netlify、Vercel、Cloudflare、AWS 或執行 Node.js 的任何其他地方。沒有供應商鎖定。
 - **品牌掛鉤** - 名稱、顏色、徽標、文案都很容易更改。
 
-這不是理論上的主張。此框架的作者在郵件範本上執行他的實際收件箱，在行事曆範本上執行他的實際行事曆，在分析範本上執行他的實際分析。範本是日常驅動軟體。
+這不是理論上的主張。此框架的作者在 Mail 應用程式上執行他的實際收件箱，在 Calendar 應用程式上執行他的實際行事曆，在 Analytics 應用程式上執行他的實際分析。這些都是日常使用的應用程式。
 
 ## 你做什麼 {#what-you-do}
 
@@ -56,7 +56,7 @@ description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包
 <div class="diagram-fork">
   <div class="diagram-card">
     <span class="diagram-pill">1</span><strong>Pick</strong
-    ><small class="diagram-muted">a complete template</small>
+    ><small class="diagram-muted">完整應用程式</small>
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-card">
@@ -98,8 +98,8 @@ description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包
 
 </Diagram>
 
-1. **選取一個範本。**使用 CLI 選取器，或瀏覽檔案並選取一個開始。
-2. **打造品牌。**更改名稱、顏色、徽標和文案。大多數範本都將其公開在單一設定檔案中。
+1. **選取一個範例應用程式。**使用 CLI 選取器，或瀏覽檔案並選取一個開始。
+2. **打造品牌。**更改名稱、顏色、徽標和文案。大多數範例應用程式都將其公開在單一設定檔案中。
 3. **自訂它。** 要求代理新增您需要的列，更改收件箱分組的方式，連線到您的內部 API，新增新檢視。代理編輯程式碼；您檢視差異。
 4. **發貨。**執行部署指令。您現在在自己的域中擁有自己的正式環境 SaaS。
 
@@ -157,7 +157,7 @@ description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包
 
 ## 不想分叉？ {#hosted}
 
-你不必這樣做。每個範本還可以作為 `agent-native.com` 上的託管應用程式使用 - `mail.agent-native.com`、`calendar.agent-native.com` 等。免費或付費使用託管版本；僅當您想要更改託管版本未公開的內容時才進行分叉。
+你不必這樣做。每個範例應用程式還可以作為 `agent-native.com` 上的託管應用程式使用 - `mail.agent-native.com`、`calendar.agent-native.com` 等。免費或付費使用託管版本；僅當您想要更改託管版本未公開的內容時才進行分叉。
 
 ## 嘗試一下技巧 {#try-with-a-skill}
 
@@ -166,10 +166,10 @@ description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包
 ## 在此基礎上建置
 
 - [**Getting Started**](/docs/getting-started) - 建立聊天優先應用程式，新增 action，渲染結構化結果，並擴展為頁面
-- [**Messaging the agent**](/docs/messaging) - 使用者（和您）如何與每個範本附帶的代理對話
-- [**Multi-App Workspace**](/docs/multi-app-workspace) — 將多個範本捆綁到一個共用驗證、品牌和代理的工作區
-- [**Dispatch**](/docs/template-dispatch) — 工作區控制平面範本
-- [**Creating Templates**](/docs/creating-templates) — 創作並發布您自己的範本
+- [**Messaging the agent**](/docs/messaging) - 使用者（和您）如何與每個應用程式附帶的代理對話
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — 將多個應用程式捆綁到一個共用驗證、品牌和代理的工作區
+- [**Dispatch**](/docs/template-dispatch) — 工作區控制平面應用程式
+- [**Creating Templates**](/docs/creating-templates) — 創作並發布您自己的應用程式範本
 
 ### 對於開發者 {#dev-details}
 
@@ -179,10 +179,10 @@ description: "分叉一個可用的 SaaS 產品並使其成為您的產品 - 包
 npx @agent-native/core@latest create my-platform
 ```
 
-您將獲得一個多選選取器。選取一個應用程式（獨立）或多個應用程式（工作區 - 應用程式共用驗證、品牌、代理設定和資料庫）。每個挑選的範本都與您需要的每個檔案一起建置到 `apps/<name>/` 中。對於沒有瀏覽器 UI 的自動化應用程式，而不是範本 UI，請使用 `npx @agent-native/core@latest create my-agent --headless`。
+您將獲得一個多選選取器。選取一個應用程式（獨立）或多個應用程式（工作區 - 應用程式共用驗證、品牌、代理設定和資料庫）。每個挑選的應用程式都與您需要的每個檔案一起建置到 `apps/<name>/` 中。對於沒有瀏覽器 UI 的自動化應用程式，而不是應用程式 UI，請使用 `npx @agent-native/core@latest create my-agent --headless`。
 
 填寫`.env`（主要是`ANTHROPIC_API_KEY`和`DATABASE_URL`）、`pnpm install`、`pnpm dev`，就可以了。沒有“TODO：實現登入”，沒有預留位置路由。
 
 部署目標：任何 Nitro 相容主機（Node、Cloudflare、Netlify、Vercel、Deno、Lambda、Bun）和任何 Drizzle 相容 SQL 資料庫（SQLite、Postgres、Turso、D1、Supabase、Neon）。對於工作區，`npx @agent-native/core@latest deploy` 一次建置每個應用程式並將它們傳送到單一來源。參見[Deployment](/docs/deployment)。
 
-要創作和發布您自己的範本，請參閱 [Creating Templates](/docs/creating-templates)。
+要創作和發布您自己的應用程式範本，請參閱 [Creating Templates](/docs/creating-templates)。

package/corpus/core/docs/content/locales/zh-TW/components.mdx

@@ -25,7 +25,9 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` 或聚焦的 `@agent-native/core/client/*` 子路徑
 因此捆綁商選取瀏覽器安全的條目。
 
-將 `@agent-native/toolkit` 用於不屬於基礎執行階段合約的可重用應用程式建構部件：shadcn 風格 UI primitives、共享 hooks、簡單應用程式 shell helpers，以及其他範本組合模組。遷移期間 Core 會保留相容 re-export，但新的範本和應用程式程式碼應直接匯入 toolkit 模組：
+將 `@agent-native/toolkit` 用於不屬於基礎執行階段合約的可重用應用程式建構部件：shadcn 風格 UI primitives、共享 hooks、簡單應用程式 shell helpers，以及其他範本組合模組。遷移期間 Core 會保留相容 re-export。
+
+可重用套件可以直接匯入 Toolkit 模組：
 
 ```tsx
 import { Button } from "@agent-native/toolkit/ui/button";
@@ -34,6 +36,13 @@ import { useToast } from "@agent-native/toolkit/hooks/use-toast";
 import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
 ```
 
+在範本應用程式中，請優先使用 app-local adapter，讓團隊只替換一次 primitive，就能讓所有重用的 Toolkit surface 採用本地實作：
+
+```tsx
+import { Button } from "@/components/ui/button";
+import { useToast } from "@/hooks/use-toast";
+```
+
 <Diagram id="doc-block-174p2n3" title={"下拉一層，不脫離框架"} summary={"每個層都保持相同的執行時 - 操作、對話串狀態和 SQL-backed 同步 - 同時讓您更好地控制鑲邊。"}>
 
 ```html
@@ -435,15 +444,16 @@ function WorkspaceResources() {
 
 ## 其他公開 UI {#other-ui}
 
-| 區域         | APIs                                                  | 匯入路徑                                  |
-| ------------ | ----------------------------------------------------- | ----------------------------------------- |
-| 分享         | `<ShareButton>`, `<ShareDialog>`, `<VisibilityBadge>` | `@agent-native/core/client/sharing`       |
-| 通知         | `<NotificationsBell>`                                 | `@agent-native/core/client/notifications` |
-| 進度         | `<RunsTray>`，進度掛鉤和型別                          | `@agent-native/core/client/progress`      |
-| 入職         | `useOnboarding()`，入門面板掛鉤                       | `@agent-native/core/client/onboarding`    |
-| 可觀察性     | `<ObservabilityDashboard>`, `<ThumbsFeedback>`        | `@agent-native/core/client/observability` |
-| 資源         | `<ResourcesPanel>`、`<ResourceTree>`、資源掛鉤        | `@agent-native/core/client/resources`     |
-| 豐富的編輯器 | `<SharedRichEditor>`，斜杠指令，塊節點掛鉤            | `@agent-native/core/client/editor`        |
+| 區域         | APIs                                           | 匯入路徑                                  |
+| ------------ | ---------------------------------------------- | ----------------------------------------- |
+| 分享         | `<ShareButton>`, `<ShareDialog>`               | `@agent-native/core/client/sharing`       |
+| Sharing UI   | `<VisibilityBadge>`                            | `@agent-native/toolkit/sharing`           |
+| 通知         | `<NotificationsBell>`                          | `@agent-native/core/client/notifications` |
+| 進度         | `<RunsTray>`，進度掛鉤和型別                   | `@agent-native/core/client/progress`      |
+| 入職         | `useOnboarding()`，入門面板掛鉤                | `@agent-native/core/client/onboarding`    |
+| 可觀察性     | `<ObservabilityDashboard>`, `<ThumbsFeedback>` | `@agent-native/core/client/observability` |
+| 資源         | `<ResourcesPanel>`、`<ResourceTree>`、資源掛鉤 | `@agent-native/core/client/resources`     |
+| 豐富的編輯器 | `<SharedRichEditor>`，斜杠指令，塊節點掛鉤     | `@agent-native/core/client/editor`        |
 
 ## 一次性文字完成 {#one-off-text-completion}