@agent-native/core 0.87.0 → 0.90.1

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

@@ -0,0 +1,103 @@
+---
+title: "Toolkit"
+description: "Reusable app-building primitives that sit between @agent-native/core and template apps."
+---
+
+# 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}
 

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

@@ -0,0 +1,329 @@
+---
+title: "資料程式"
+description: "由 agent 撰寫並儲存的 JS 腳本，在伺服器端擷取、連接與彙整資料，快取於 SQL 中，並由 dashboard 面板渲染——介於一次性 run-code 查詢與硬編碼 provider action 之間的即時資料折衷方案。"
+search: "data program emit rows schema providerFetch dashboard panel program source refresh TTL viewer-scoped cache save-data-program run-data-program"
+---
+
+# 資料程式
+
+**資料程式（data program）**是一個具名、儲存、由 agent 撰寫的 JS 腳本，用來擷取、連接、篩選或彙整資料——透過 `providerFetch` / `providerFetchAll` / `providerSearchAll` 存取 provider API，透過 `appAction` 存取 app 資料，或存取以 Resources 為基礎的 workspace 檔案——並且恰好呼叫一次 `emit(rows, schema)` 來提交結果。結果會快取在 SQL 中，任何圖表/表格元件都能渲染它，依你選擇的策略更新，而不是每次頁面瀏覽都重新擷取。
+
+只要 [`run-code`](/docs/actions) 可用，它就會自動可用——不需要依 app 掛載或設定任何東西。如果你的 app 已啟用 run-code，`save-data-program`、`preview-data-program`、`run-data-program`、`list-data-programs`、`get-data-program` 與 `delete-data-program` 就已經是已註冊的 actions。
+
+<Diagram id="doc-block-dp-overview" title={"從臨時查詢到即時面板"} summary={"一段 run-code 腳本一旦呼叫 emit()，就會變成一個儲存的程式；任何 dashboard 面板都能綁定到它，之後由快取／更新策略接手。"}>
+
+```html
+<div class="dp-flow">
+  <div class="diagram-card" data-rough>
+    <span class="diagram-pill">run-code script</span
+    ><small class="diagram-muted">providerFetch, joins, aggregation</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel">
+    <span class="diagram-pill accent">emit(rows, schema)</span
+    ><small class="diagram-muted"
+      >save-data-program dry-runs, then persists</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    data_program_runs<br /><small class="diagram-muted"
+      >cached per (program, params, viewer)</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">儀表板面板</span
+    ><small class="diagram-muted"><code>source: "program"</code></small>
+  </div>
+</div>
+```
+
+```css
+.dp-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dp-flow .diagram-card,
+.dp-flow .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
+  min-width: 180px;
+}
+.dp-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 為什麼需要它 {#why}
+
+若沒有儲存的資料程式，「為 X 建立即時檢視」通常會落入兩個糟糕情況之一：
+
+- **為每種 vendor／查詢形態撰寫硬編碼 action。** 脆弱，且無法預見每位客戶的自訂屬性、跨 provider 的連接，或你沒想到要支援的任意篩選條件。
+- **每次頁面瀏覽都從頭重新執行相同的擷取／連接邏輯。** 緩慢，且每次有人查看圖表都會重新消耗相同的 provider API 配額。
+
+資料程式是折衷方案：將擷取／連接／彙整邏輯以普通 `run-code` 撰寫一次，儲存它，然後讓快取與更新策略決定它實際需要多久重新執行一次。
+
+## 何時該使用它 {#when-to-use-one}
+
+| 情境                                                                                                     | 應使用                                                                   |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 標準彙總已有一流 action（預先建置的 `hubspot-deals` 篩選器、內建指標）                                   | 使用現有 action——不要把它包裝成程式                                      |
+| 你之後不會再看的一次性聊天問題                                                                           | 直接使用普通 `run-code` 或 `provider-api-request` 回答，不要保存任何東西 |
+| 擴充功能需要一個帶有自身 UI 的小型、按使用者互動的元件                                                   | [擴充功能](/docs/extensions)——資料程式沒有自己的 UI                      |
+| 群組需要任意屬性篩選、對自訂值的 IN 搜尋，或跨兩個 provider 的連接，**而且**有人會想用最新資料再次查看它 | 資料程式                                                                 |
+| dashboard 面板需要顯示這個連接／彙整結果，並依快取策略更新                                               | 綁定到 `"program"` 面板的資料程式                                        |
+
+與其他 run-code 形態選項的比較：
+
+|                                 | 一次性 `run-code`  | 硬編碼 provider action                     | 資料程式                               |
+| ------------------------------- | ------------------ | ------------------------------------------ | -------------------------------------- |
+| **呼叫之間是否持久**            | 否                 | 不適用（它是原始碼）                       | 是——儲存的資料列＋結果快取             |
+| **結果是否快取／更新**          | 否，每次都重新執行 | 沒有內建快取                               | 是——`refreshMode`/`refreshTtlMs`       |
+| **是否處理任意篩選／連接**      | 是，但用完即丟     | 否——受限於該 action 的 schema 所揭露的內容 | 是——它仍是一般程式碼                   |
+| **是否可綁定到 dashboard 面板** | 否                 | 只有專門為此建置了面板來源才行             | 是——通用的 `"program"` 來源            |
+| **是否需要部署**                | 否                 | 是（新 action = 程式碼變更）               | 否——由 agent 在執行期建立              |
+| **讀取時使用的憑證**            | 呼叫者的           | 呼叫者的                                   | **檢視者的**，依每次讀取解析（見下文） |
+
+## 撰寫工作流程 {#authoring-workflow}
+
+1. **先在聊天中製作原型。** 將擷取／連接／彙整邏輯寫成普通的 `run-code` 腳本，並確認它會回傳你期望的資料列。
+2. **修改它，使其在最後恰好呼叫一次 `emit(rows, schema?)`**，而不是回傳或印出結果。
+3. **使用 `save-data-program` 儲存它。** 這會在持久化之前**以 `defaultParams` 對程式碼進行一次 dry-run**，若失敗則以結構化錯誤拒絕儲存，因此損壞的程式永遠不會被儲存。成功時會回傳 `{ programId, rowCount, columns, sampleRows }`——在告訴使用者「已就緒」之前，將此視為程式確實產生預期資料列的證明。
+4. **將 dashboard 面板綁定到它**，或直接從你自己的讀取路徑呼叫 `run-data-program`。這個基礎元件本身並未內建任何 dashboard 專屬的接線——analytics 範本的 `"program"` 面板來源（見下文）只是其中一種採用方式，並非必要模式。
+5. **不需儲存即可疊代**，使用 `preview-data-program({ code, params? })`——相同的 dry-run 路徑，不儲存資料列。
+
+### 一個實際的範例
+
+假設某個 app 想要一個「近期高價值支援工單」的即時表格，資料來自某個支援類 provider，並依任何內建 action 都未揭露的門檻篩選：
+
+```ts
+// The program's stored `code` — ordinary run-code, with one emit() call.
+const minValue = Number(params.minValue || 5000);
+
+const tickets = await providerFetchAll("acme-support", "/v1/tickets", {
+  query: { status: "open" },
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "next_cursor",
+    maxPages: 10,
+  },
+});
+
+const rows = (tickets.items || [])
+  .filter((t) => Number(t.contract_value || 0) >= minValue)
+  .map((t) => ({
+    ticket_id: t.id,
+    subject: t.subject,
+    account: t.account_name,
+    contract_value: Number(t.contract_value || 0),
+    opened_at: t.created_at,
+  }));
+
+emit(rows, [
+  { name: "ticket_id", type: "string" },
+  { name: "subject", type: "string" },
+  { name: "account", type: "string" },
+  { name: "contract_value", type: "number" },
+  { name: "opened_at", type: "string" },
+]);
+```
+
+儲存它：
+
+```ts
+await appAction("save-data-program", {
+  name: "high-value-open-tickets",
+  title: "High-Value Open Tickets",
+  description:
+    "Open support tickets above a configurable contract-value threshold.",
+  code: "/* the script above */",
+  defaultParams: { minValue: 5000 },
+  refreshMode: "ttl",
+  refreshTtlMs: 300_000,
+});
+```
+
+回應中會帶有 `{ programId, rowCount, columns, sampleRows }`——這是 dry-run 的完成證明。之後，`run-data-program({ programId, params: { minValue: 10000 } })` 會針對不同門檻重新執行它（或提供快取），dashboard 面板也能用同樣的方式綁定到 `programId`。
+
+## 沙箱能力介面 {#sandbox-surface}
+
+資料程式運行在與 `run-code` 完全相同的 `executeSandboxCode` 沙箱中——這個基礎元件並未新增任何沙箱、憑證、SSRF 或配額相關的程式碼。它擁有相同的全域物件（`providerFetch`、`providerFetchAll`、`providerSearchAll`、`appAction`、`webFetch`、`workspace*` Resources 輔助函式），外加框架注入的一小段前導程式碼帶來的兩項補充：
+
+- **`params`** ——一個**凍結**的全域物件，保存本次執行的參數（`defaultParams` 與傳給 `run-data-program` 或面板描述符的內容合併）。讀取它沒問題；修改它會擲出錯誤。
+- **`emit(rows, schema?)`** ——在結尾**恰好呼叫一次**。第二次呼叫會擲出錯誤。`rows` 必須是純物件組成的陣列。`schema`（如有提供）為 `{ name: string, type: string }[]`；省略時會依前 50 列推斷（若樣本中各列在原始型別上不一致，該欄就是 `"json"`，否則為 `"number"` / `"string"` / `"boolean"`）。`console.log` 仍完全自由，可用於除錯——執行器會擷取合併後的 stdout/stderr，並在解析結果時僅移除 `emit()` 寫入的哨兵行。
+
+每次執行都會強制套用的上限（無法依程式個別設定）：
+
+| 限制                                       | 數值                                                                                                        |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| 最大提交列數                               | 10,000——超出的列會被捨棄，`truncated: true`                                                                 |
+| 最大提交結果大小                           | 4 MiB——從結尾捨棄資料列以符合限制；單一列超過上限則屬硬性 `result_too_large` 失敗，因為沒有可安全截斷的內容 |
+| 每個 app 的最大使用中（未封存）程式數      | 200——封存未使用的程式以釋放空間                                                                             |
+| 最小更新 TTL                               | 60,000 毫秒                                                                                                 |
+| 每個（程式、params、檢視者）保留的執行列數 | 最近 5 筆——較舊的紀錄會在每次寫入時自動清除                                                                 |
+
+截斷永遠是明確的（結果中的 `truncated: true`）——絕不會靜默捨棄。
+
+## Params 與 dashboard 面板綁定 {#params-and-panel-binding}
+
+程式可宣告一個選用的 `paramsSchema`（描述所接受 params 的 JSON Schema）以及 `defaultParams`。dashboard 採用 `"program"` 面板來源的方式，是在面板的查詢欄位中放入一個小型 JSON 描述符，而非查詢字串：
+
+```json
+{ "programId": "dp_a1b2c3d4e5f6", "params": { "minValue": 10000 } }
+```
+
+該面板透過與其他任何面板來源完全相同的圖表／表格元件渲染——它永遠只會收到 `{ rows, schema }`。將面板綁定到程式，僅僅是「綁定到哪個儲存的程式、覆寫哪些 params」；不存在在別處重複實作的 dashboard 專屬執行路徑。
+
+## 更新、TTL 與快取語意 {#refresh-and-caching}
+
+每個 `(programId, paramsHash)` 組合在 `data_program_runs` 中都有自己的執行歷史，而 `paramsHash` 除了 params 之外還納入了**檢視者**（原因見安全章節）。每次讀取時會發生：
+
+| 情況                                                                            | 行為                                                                                                                                 |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 新鮮快取（比 `refreshTtlMs` 更新，或 `refreshMode: "manual"` 且先前有成功紀錄） | 立即回傳快取的資料列，`cacheHit: true`                                                                                               |
+| 快取比 TTL 更舊                                                                 | 同步重新執行——面板檢視觸發的讀取預算為 25 秒，agent／手動呼叫為 120 秒——並在成功時取代快取                                           |
+| `refreshMode: "manual"`                                                         | 永不自動更新；只有明確的 `forceRefresh: true`（或 UI 上的手動更新 action）才會重新執行                                               |
+| 尚無快取                                                                        | 像一般的首次擷取一樣同步執行                                                                                                         |
+| `background: true` 的程式，無新鮮快取                                           | 立即以 `stale: true` 提供最近一次成功結果，並將一次持久的背景執行加入佇列（10 分鐘預算）；之後的呼叫會在執行完成後完成結果的最終確認 |
+| 背景程式仍在執行，且先前無成功紀錄                                              | `background_pending` 失敗——應顯示明確的「仍在計算中」狀態，絕不回傳空白結果                                                          |
+| 執行失敗（逾時、沙箱錯誤、`emit()` 形狀不合法）                                 | 結構化的 `{ code, message }` 失敗；若存在先前的成功結果，會作為 `lastGoodRun` 附加，以便面板可提供過時資料，而非顯示空白             |
+| 程式已被封存（透過 `delete-data-program` 軟刪除）                               | 明確的 `archived` 失敗——絕不是靜默的空白面板                                                                                         |
+
+只對那些經常超出前景逾時的程式使用 `background: true`——例如大型多 provider 連接、深度分頁。其餘情況都應保持前景執行：更容易推理，也能更快提供新鮮資料。
+
+### 為什麼快取依檢視者劃分範圍 {#per-viewer-cache}
+
+程式內部的 `providerFetch` 使用**呼叫檢視者自己的請求脈絡**來解析身分驗證——絕不使用程式作者的。無論呼叫來自 agent、`run-data-program` 呼叫，或是團隊成員正在查看的 dashboard 面板，皆是如此。兩位不同的檢視者以相同 params 執行同一個程式，完全可能合理地得到兩個不同的結果：一位設定了 HubSpot 金鑰而另一位沒有，或是列層級的 provider 權限因人而異。
+
+正因如此，`hashDataProgramParams` 在快取金鑰中除了正規化的 params 之外，也納入了呼叫者的身分。這對**共用 dashboard** 尤其重要：若快取僅依 params 分鍵，第一位查看面板的人就會悄悄決定其他每位檢視者所看到的內容，包括那些不具備產生該快取結果所需憑證的檢視者。依檢視者劃分範圍，代表缺少憑證的團隊成員會在該面板上看到自己的身分驗證錯誤，而非他人的資料。
+
+## 安全模型 {#security}
+
+<Callout id="doc-block-dp-security" tone="success">
+
+**原始 provider 權杖永遠不會抵達模型或瀏覽器。** 離開沙箱的唯一內容，是 `emit()` 呼叫所產生的 `{ rows, schema }`——與其他任何 run-code 執行、其他任何 dashboard 面板來源相同的信任邊界。
+
+</Callout>
+
+- **僅限伺服器端。** 資料程式的程式碼只在伺服器上的 `executeSandboxCode` 內部執行。無論是儲存的原始碼，還是它所觸及的任何憑證，都不會傳送到瀏覽器或模型——只有提交的資料列／schema，以及精簡的執行中繼資料（列數、欄位、範例列）會被傳送。
+- **憑證永遠是呼叫檢視者的，絕非程式原作者的。** 參見上文的[更新、TTL 與快取語意](#per-viewer-cache)，了解這為何也決定了快取金鑰。
+- **`allowPublic: false` 是硬性不變量，而非預設值。** 資料程式以與[擴充功能](/docs/extensions#security)相同的方式向共用註冊表註冊，且停用公開共用。公開的程式會讓任何已驗證使用者以自己的權杖執行任意儲存的程式碼——共用一個程式僅限於你的組織範圍內，且永遠只代表「團隊成員可查看其快取結果並觸發重新執行」，絕不代表「公眾網際網路可執行它」。
+- **變更與執行類的 actions 無法從沙箱化的擴充功能／iframe 橋接以工具形式呼叫。** `save-data-program`、`preview-data-program`、`run-data-program` 與 `delete-data-program` 皆為 `toolCallable: false`——只有 agent 或伺服器端的讀取路徑能呼叫它們，絕不能由開啟者工作階段下的擴充功能 iframe 呼叫。`list-data-programs` 與 `get-data-program` 為唯讀，並透過與其他任何 ownable 資源相同的共用輔助函式進行存取範圍限定。
+- **程式的範圍限定於建立它的那個 app 內。** 向查詢傳入 `appId`，代表在共用資料庫部署中，某個 app 建立的程式無法從另一個 app 的 agent 聊天中執行，即使呼叫者在列層級（擁有者／組織／共用）原本對其擁有存取權。
+- **只綁定或查看你信任的程式。** 由於執行永遠使用檢視者自己的憑證，查看一個共用程式的結果，就完全等同於開啟他人的擴充功能——要信任的是程式碼本身，而不只是存取授權。
+
+## Risk Meeting 實作範例 {#risk-meeting-example}
+
+analytics 範本附帶了一個具體、可執行的案例研究：`ensure-risk-meeting-dashboard` action 會冪等地安裝兩個資料程式，外加一個雙面板的「Risk Meeting」dashboard，展示了硬編碼 action 無法為每位客戶預見的三件事。
+
+<FileTree
+  id="doc-block-dp-risk-meeting-files"
+  title={"Risk Meeting 安裝器"}
+  entries={[
+    {
+      path: "templates/analytics/actions/ensure-risk-meeting-dashboard.ts",
+      note: "冪等 action：依穩定名稱更新兩個程式，再依 id 更新 dashboard",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-cohort.js",
+      note: "儲存的程式負載——純 JS 文字，不是建置原始檔",
+    },
+    {
+      path: "templates/analytics/seeds/data-programs/risk-meeting-pylon-early-warning.js",
+      note: "配套的早期預警程式",
+    },
+  ]}
+/>
+
+**`risk-meeting-cohort.js`** ——依任意的 `risk_status` 屬性（一種預先建置的 action 無法預見的、針對自訂值的 IN 搜尋）搜尋可設定的 CRM deal 群組，透過批次關聯查詢解析每個 deal 的公司，解析每間公司的網域，取得第二個不相關 provider 的帳戶情緒，並依網域將兩者連接：
+
+```js
+// params: { riskStatuses?: string[], enterpriseOnly?: boolean }
+const riskStatuses = params.riskStatuses?.length
+  ? params.riskStatuses
+  : ["On the Radar", "Churn Risk", "Confirmed Churn", "No Save Attempted"];
+
+// 1. Arbitrary property IN-search — not expressible through a canned filter.
+const dealSearch = await providerFetchAll("crm-provider", "/deals/search", {
+  method: "POST",
+  body: {
+    filterGroups: [
+      {
+        filters: [
+          { propertyName: "risk_status", operator: "IN", values: riskStatuses },
+        ],
+      },
+    ],
+  },
+  itemsPath: "results",
+  pagination: {
+    cursorBodyPath: "after",
+    nextCursorPath: "paging.next.after",
+    maxPages: 20,
+  },
+});
+
+// 2-3. Batched deal -> company -> domain resolution (elided here; see the
+// real seed file for the full batching helper).
+
+// 4. A second, unrelated provider — zero bespoke glue action required.
+const accounts = await providerFetchAll("support-provider", "/accounts", {
+  itemsPath: "data",
+  pagination: {
+    cursorParam: "cursor",
+    nextCursorPath: "pagination.cursor",
+    maxPages: 20,
+  },
+});
+
+// 5. Join + emit.
+const rows = dealSearch.items.map((deal) => ({
+  deal_id: deal.id,
+  risk_status: deal.properties.risk_status,
+  arr: Number(deal.properties.total_contract_value || 0),
+  // ...domain lookup + sentiment join...
+}));
+
+emit(rows, [
+  { name: "deal_id", type: "string" },
+  { name: "risk_status", type: "string" },
+  { name: "arr", type: "number" },
+]);
+```
+
+**`risk-meeting-pylon-early-warning.js`** ——配套檢視：已被支援情緒標記為風險、但**尚未**出現在上述 CRM 群組中的帳戶。這個落差——支援訊號領先於 CRM 訊號——需要將一個 provider 的群組從另一個 provider 的群組中排除，這正是單一 vendor 的 action 無法表達的跨 provider 集合邏輯。
+
+這兩個程式都由 `ensure-risk-meeting-dashboard` 安裝並保持最新，它會：
+
+- 依穩定的 `name` 更新每個程式，因此重新執行安裝器會更新相同的資料列，而非重複建立。
+- 安裝時不需要 CRM／支援類憑證——provider 身分驗證只有在面板真正被渲染或呼叫了 `run-data-program` 時，才會依檢視者解析，與上文依檢視者的快取範圍劃分一致。
+- 建置一個雙面板 dashboard，其面板使用 `source: "program"`，綁定到各自程式的 id。
+
+完整附註解的原始碼請參見 `data-programs` skill。
+
+## 其他 app 如何採用面板來源 {#adopting-the-panel-source}
+
+`"program"` dashboard 面板來源是這個基礎元件的一種採用方式，完全實作在主機 app 自己的面板查詢層中——`@agent-native/core/data-programs` 本身並未內建任何 dashboard 專屬的東西。analytics 範本的實作是接上你自己系統時的實用參考：
+
+- 面板的 `sql` 欄位帶有一個小型 JSON 描述符——`{ programId, params? }`——而非查詢字串。
+- 渲染面板會以 `triggeredBy: "panel_view"` 及目前檢視者的身分呼叫 `runDataProgram`，因此依檢視者的快取與憑證解析會自動生效。
+- 成功時，面板取得 `{ rows, schema }`——與其他任何面板來源回傳的形狀相同，因此可不經修改流經現有的圖表／表格元件。
+- 失敗時，只要存在 `lastGoodRun`，就會優先使用它而非顯示損壞的面板；只有在沒有先前成功紀錄時，面板才會顯示結構化錯誤（針對 `access_denied`、`archived`、`background_pending` 等常見代碼有更友善的文案）。
+
+任何 app 都可以為自己的 dashboard／表格實作相同的採用方式：從你自己的讀取路徑呼叫 `run-data-program`（若在同一個伺服器程序內，也可直接呼叫 `runDataProgram`），並將回傳的 `rows`/`schema` 交給你自己的渲染元件。
+
+## 相關文件 {#related}
+
+- [擴充功能](/docs/extensions) ——資料程式與之共享安全姿態與共用模型的沙箱化 mini-app 基礎元件，但擁有自己的 UI。
+- [Actions](/docs/actions) ——資料程式所建構於其上的 `run-code` 慣例與沙箱全域物件（`providerFetch`、`appAction` 等）。
+- [共用與隱私](/docs/sharing) ——資料程式所使用的、僅限組織內部、絕不公開的共用模型。
+- [安全性](/docs/security) ——框架的憑證處理與存取範圍限定不變量。

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

@@ -384,24 +384,22 @@ openssl rand -hex 32
 ## 正式環境代理工具 {#production-agent-tools}
 
 正式環境代理從
-代理聊天外掛。預設情況下啟用資料庫寫入，因為原始資料庫
-工具的範圍僅限於經過驗證的使用者/組織，但應用程式所有者可以縮小範圍
-何時部署應該更加固執己見：
+代理聊天外掛。預設啟用 SQL 檢查；資料庫寫入會透過型別化應用程式 actions，
+除非應用程式明確啟用原始寫入工具：
 
 ```ts
 // server/plugins/agent-chat.ts
 export default createAgentChatPlugin({
-  // Default: "write" (also true)
+  // Default: "read"
   databaseTools: "read", // "write" | "read" | "off"
   extensionTools: false,
 });
 ```
 
-- `databaseTools: "write"` — 預設。寄存器`db-schema`、`db-query`、
-  `db-exec` 和 `db-patch`。寫入範圍僅限於目前使用者/組織和
-  架構更改被阻止。
-- `databaseTools: "read"` — 僅註冊 `db-schema` 和 `db-query`；代理
-  使用 SQL 檢查資料，但必須使用型別化應用程式 actions 進行寫入。
+- `databaseTools: "read"` — 預設。僅註冊 `db-schema` 和 `db-query`；
+  代理使用 SQL 檢查資料，但必須使用型別化應用程式 actions 進行寫入。
+- `databaseTools: "write"` 或 `true` — 也會註冊 `db-exec` 和 `db-patch`
+  供有意的原始 SQL 維護使用。寫入範圍限定為目前使用者/組織，並阻止架構變更。
 - `databaseTools: "off"` 或 `false` — 從
   代理表面，因此應用程式的 actions 是唯一的資料存取路徑。
 - `extensionTools: false` — 刪除框架擴充功能管理 actions 和