@agent-native/core 0.79.2 → 0.79.6

package/docs/content/locales/zh-TW/template-analytics.md

@@ -0,0 +1,259 @@
+---
+title: "分析"
+description: "用簡單的英語提出分析問題，獲取圖表和儀表板。 Amplitude、Mixpanel 和 Looker 的開來源替代品。"
+---
+
+# 分析
+
+用簡單的英語提出分析問題，獲取圖表和儀表板。該代理連線到 BigQuery、GA4、Amplitude、內置第一方事件收集器、HubSpot、Jira 和十幾個其他來源，為您編寫查詢、驗證查詢，並將答案呈現為圖表、表格或儲存的儀表板面板。
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:500px;box-sizing:border-box'><h1 style='margin:0'>Agent-Native 範本</h1><p class='wf-muted' style='margin:0'>過去 12 週的采用率和參與度。</p><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card'><small class='wf-muted'>每週活躍使用者</small><br/><strong>24,318</strong><br/><span class='wf-pill accent'>+12.4%</span></div><div class='wf-card'><small class='wf-muted'>新增註冊</small><br/><strong>1,842</strong><br/><span class='wf-pill accent'>+8.7%</span></div><div class='wf-card'><small class='wf-muted'>MRR 收入</small><br/><strong>$48,210</strong><br/><span class='wf-pill accent'>+21.3%</span></div></div><div style='display:grid;grid-template-columns:1fr 1fr;gap:12px;flex:1'><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>每週活躍使用者</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:38%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:44%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:58%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:74%;flex:1;background:var(--wf-accent-soft)'></div></div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>收入趨勢</strong><div style='flex:1;display:flex;align-items:end;gap:8px'><div style='height:32%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:48%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:63%;flex:1;background:var(--wf-accent-soft)'></div><div style='height:80%;flex:1;background:var(--wf-accent-soft)'></div></div></div></div><div class='wf-card'><strong>按來源劃分的註冊</strong><br/><small class='wf-muted'>下方圖表位於主圖表下方。</small></div></div>"
+}
+```
+
+它是 Amplitude、Mixpanel 和 Looker 的開來源替代品——適合想要擁有程式碼、查詢和資料的團隊。
+
+```an-diagram title="問題到圖表" summary="代理查閱資料字典，寫入 SQL，根據倉庫對其進行驗證，然後渲染圖表或儲存面板。"
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">簡明語言<br>question</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">reads data dictionary</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>寫入 SQL</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">Dry-run 校驗</div><small class=\"diagram-muted\">BigQuery / 來源</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">圖表、表格或<br>saved panel</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:6px;align-items:center}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 你可以用它做什么
+
+- **用簡單的英語詢問資料問題。**“上個月註冊轉化為付費的比例是多少？”或“顯示過去 6 個月的每週活躍使用者數”。代理選取正確的來源，寫入 SQL，並渲染圖表。
+- **使用過濾器、儲存的視圖和參數查詢建置可重用的 SQL 儀表板**。
+- **執行臨時分析**，交叉引用多個資料來源 - 與原始問題、說明和結果一起儲存為可重新執行的調查。
+- **維護指標、表和 SQL 配方的實時資料字典**，以便代理每次都使用正確的列名稱（當它實際上是 `hs_is_closed` 時，不再猜測 `is_closed`）。
+- **與您的團隊共用儀表板** - 預設情況下是私人的，可按使用者或按組織與檢視者/編輯者/管理員角色共用。
+- **連線到許多來源**，開箱即用：BigQuery、GA4、Mixpanel、Amplitude、PostHog、HubSpot、Jira、Apollo、Pylon、Gong、Common Room、Twitter，以及特定於應用程式的 SEO 來源。
+- \*\*當工作區已連線且
+  授予 Analytics 提供者。共用整合商店提供者
+  身分和憑證參考； Analytics 保留特定於應用程式的來源選取，
+  資料字典條目、儀表板 SQL 和分析歷史紀錄。
+
+## 開始使用
+
+現場演示：[analytics.agent-native.com](https://analytics.agent-native.com)。
+
+首次開啟應用程式時：
+
+1. 使用 Google 登入。
+2. 從側邊欄開啟**資料來源**頁面。
+3. 每個來源都有一個演練 - 連線您需要的來源（從一個開始，例如 BigQuery、GA4、Amplitude 或第一方跟蹤）。
+4. 與代理開啟新的聊天並提出問題：“上週我們獲得了多少註冊？”
+
+第一個問題足以確認連線是否有效。從那裡，要求代理“將其另存為儀表板”或“為我們的關鍵指標建置 4 面板概述儀表板。”
+
+### 有用的提示
+
+- “建置一個儀表板，顯示過去 6 個月的每週活躍使用者。”
+- “上個月註冊轉化為付費的比例是多少？”
+- “將按計畫比較收入的圖表新增到此儀表板。”
+- “重新排序此儀表板上的面板，使 MRR 指標排在第一位。”
+- “分析第一季度我們已結束的丟失交易並儲存分析。”
+- “使用本月的資料重新執行客戶流失分析。”
+- “在資料字典中紀錄此指標。”
+
+代理始終知道您在檢視什么 - 目前儀表板、過濾器、視圖 - 因此您可以直接說出“此儀表板”或“那個面板”。
+
+## 需要知道的三件事
+
+該應用程式具有三個主要介面，您將在其中花費時間：
+
+- **SQL 儀表板** — 帶有過濾器和儲存視圖的可重複使用面板。最適合您定期檢查的指標。
+- **臨時分析** — 從多個來源進行的長篇調查，並儲存重新執行說明。最適合您可能想重新審視的一次性問題。
+- **資料字典** — 指標、表、列和 SQL 配方的規範目錄。代理在寫入任何 SQL 之前會查閱它，因此它使用真實的倉庫列名稱，並了解“排除內部電子郵件”等警告。
+
+通過詢問代理來播種字典：“匯入我們的 dbt 定義”或“從我們的 Notion 手冊中提取指標”，它就會完成工作。
+
+## 對於開發者
+
+本檔案的其餘部分適用於任何派生 Analytics 範本或擴充功能它的人。
+
+### 快速入門
+
+從 CLI 建立新的 Analytics 應用：
+
+```bash
+npx @agent-native/core@latest create my-analytics --standalone --template analytics
+```
+
+本機開發：
+
+```bash
+cd my-analytics
+pnpm install
+pnpm dev
+```
+
+CLI 列印本機開發 URL。使用 Google 登入，然後開啟 **資料來源** 頁面以連線 BigQuery、GA4、第一方跟蹤、HubSpot、Jira 等。
+
+### 主要功能
+
+**提出問題，獲取圖表。**代理選取資料來源，寫入並驗證 SQL，然後呈現圖表、表格、指標或儲存的面板。
+
+**儀表板和調查。**可重複使用的儀表板保留 SQL 面板、過濾器、儲存的視圖和共用；臨時分析通過重新執行指令儲存更長的結果。
+
+**實時資料字典。**指標定義、所有者、來源表和已知警告在寫入查詢之前為代理提供真實的倉庫詞匯。
+
+**廣泛的連線器表面。** BigQuery、GA4、產品分析、CRM、支持、社區、GitHub/Jira、SEO 和第一方 `/track` 事件均來自代理可以調用的 actions。
+
+### 與代理合作
+
+代理始終知道您在看什么。目前螢幕狀態作為 `<current-screen>` 塊注入到每條訊息中 - 它包含活動視圖、開啟的儀表板或分析以及任何選定的過濾器。
+
+代理的系統提示符會獲取注入的 `<data-dictionary>` 塊，其中包含活動組織的已批準指標條目。當您請求儀表板時，代理首先查閱字典並逐字使用紀錄的 `table` / `columns` / `queryTemplate` - 它不會猜測列名稱。
+
+**它自動具有的上下文：**
+
+- **目前視圖** — `overview`、`adhoc`（使用 `dashboardId`）、`analyses`（使用 `analysisId`）、`data-dictionary`、`data-sources` 或 `settings`。
+- **活動組織** — 範圍所有查詢和寫入。
+- **批準的字典條目** - 用於活動工作區。
+
+**儀表板編輯。** 代理使用 `update-dashboard` 操作來編輯儀表板。它支持兩種模式：
+
+- `ops` — JSON-用於外科編輯的指針補丁（行動面板、替換一個 SQL 字串、刪除過濾器）。
+- `config` — 完全替換儀表板設定。
+
+在儲存儀表板之前，每個 BigQuery 面板的 SQL 都會針對倉庫進行試執行。如果列錯誤，則儲存會被拒絕，並出現 BigQuery 錯誤 - 代理會修複 SQL 並重試，而不是保留損壞的面板。
+
+### 連線資料來源
+
+開啟 **資料來源** 頁面 (`/data-sources`) 以連線提供者。每個
+來源程式碼公開了一個環境金鑰列表、一個演練和一個 **測試連線** 按鈕。
+當 Analytics 在工作區中執行時，`data-source-status` 也會報告
+為 `appId=analytics` 授予可重用工作區連線，以便代理可以
+請求應用程式授權，而不是同一提供者金鑰的另一個副本。
+對於可重用的提供程序（例如 Slack、HubSpot、Notion 和 GitHub），資料
+來源UI直接顯示共用整合狀態：通過工作區準備就緒，
+需要授權、需要憑證或本機憑證。
+
+可重用工作區整合是共用提供程序的執行時方向：
+該框架存儲提供者身分、帳戶元資料、憑證引用和
+每個應用程式授予一次； Analytics 存儲資料來源解釋、來源
+事實選取、指標定義、儀表板和分析。
+
+憑證通過框架的settings/env層存儲——git中沒有秘密。制作要求：
+
+| 變數                                     | 目的                               |
+| ---------------------------------------- | ---------------------------------- |
+| `DATABASE_URL`                           | 持久SQL連線URL                     |
+| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | 驗證                               |
+| `GOOGLE_SIGN_IN_CLIENT_ID` / `_SECRET`   | 首選 Google 登入用戶端 (OAuth 2.0) |
+| `GOOGLE_CLIENT_ID` / `_SECRET`           | 舊版登入回退/Google API 整合用戶端 |
+| `BIGQUERY_PROJECT_ID`                    | BigQuery 專案                      |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON`    | BigQuery 服務帳戶 JSON             |
+| `ANTHROPIC_API_KEY`                      | 代理聊天                           |
+
+特定於提供者的金鑰（HubSpot、Jira、Gong、Pylon 等）紀錄在資料來源頁面上每個來源的演練中。如果您新增需要 API 金鑰的新操作，它將通過範本的入門註冊在該頁面上顯示為新來源。
+
+注意：用於 Google 登入的 BigQuery OAuth 憑證是**單獨的**
+來自 BigQuery 服務帳號 JSON 的憑證。在
+GCP 控制台 → API 和服務 → 憑證 → OAuth 用戶端 ID，並首選
+`GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` 環境名稱是這樣的
+低範圍登入用戶端與 Google API 整合用戶端保持分離。
+
+### 資料模型
+
+核心表（參見`templates/analytics/server/db/schema.ts`）：
+
+```an-schema title="分析資料模型" summary="Dashboards and analyses are the resources; views, shares, and a query cache hang off them. Org tables come from @agent-native/core/org."
+{
+  "entities": [
+    {
+      "id": "dashboards",
+      "name": "dashboards",
+      "note": "資源管理器和 SQL 儀表板",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "kind", "type": "text", "note": "\"explorer\" or \"sql\"" },
+        { "name": "config", "type": "text", "note": "JSON 匹配 SqlDashboardConfig" }
+      ]
+    },
+    {
+      "id": "dashboard_views",
+      "name": "dashboard_views",
+      "note": "每個儀表板儲存的過濾器預設",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "dashboard_id", "type": "text", "fk": "dashboards.id" }
+      ]
+    },
+    {
+      "id": "analyses",
+      "name": "analyses",
+      "note": "可重新執行的臨時調查",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "question", "type": "text" },
+        { "name": "instructions", "type": "text", "note": "重新執行步驟" },
+        { "name": "dataSources", "type": "text", "note": "接觸的來源" },
+        { "name": "resultMarkdown", "type": "text" },
+        { "name": "resultData", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "bigquery_cache",
+      "name": "bigquery_cache",
+      "note": "結果快取由 SQL 哈希鍵控",
+      "fields": [
+        { "name": "sql_hash", "type": "text", "pk": true },
+        { "name": "bytes_processed", "type": "integer" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "dashboards", "to": "dashboard_views", "kind": "1-n", "label": "saved views" }
+  ]
+}
+```
+
+加上 `@agent-native/core/org` 提供的每個資源共用表（`dashboard_shares`、`analysis_shares`）和組織表（`organizations`、`org_members`、`org_invitations`）。資料字典位於框架的 `settings` 表中的作用域鍵下。
+
+- **`dashboards`** — Explorer 和 SQL 儀表板。 `kind`為`"explorer"`或`"sql"`； `config` 是與 `SqlDashboardConfig` 匹配的 JSON Blob。
+- **`dashboard_shares`** — 每個資源份額授予（主體、角色）。
+- **`dashboard_views`** — 每個儀表板儲存的過濾器預設。
+- **`analyses`** — 使用 `question`、`instructions`、`dataSources`、`resultMarkdown` 和可選的 `resultData` 進行臨時調查。
+- **`analysis_shares`** — 用於分析的每個資源份額授予。
+- **`bigquery_cache`** — 由 SQL 哈希鍵控的查詢結果快取，並進行字節處理記帳。
+
+加上`@agent-native/core/org`提供的組織表（`organizations`、`org_members`、`org_invitations`）。
+
+資料字典位於框架的 `settings` 表中，位於作用域鍵下；檢視 `list-data-dictionary` 和 `save-data-dictionary-entry` actions 的完整形狀。
+
+### 自訂它
+
+Analytics 範本旨在進行分叉和擴充功能。一切都存在於 `templates/analytics/` 中：
+
+- **`AGENTS.md`** — 代理的頂級指南。紀錄視圖、actions 和工作流程。
+- **`actions/`** — 每個代理可調用的操作。新增新檔案以新增新操作。值得注意的：
+  - `update-dashboard.ts` - 儀表板編輯（操作 + 完全替換）
+  - `save-analysis.ts` / `list-analyses.ts` - 特別分析
+  - `save-data-dictionary-entry.ts` / `list-data-dictionary.ts` — 字典
+  - `bigquery.ts` — 原始 BigQuery 執行
+  - `view-screen.ts` / `navigate.ts` — 情境感知
+- **`app/routes/`** — 基於檔案的路由。每個路由都是 `app/pages/` 中頁面的薄包裝。
+- **`app/pages/adhoc/sql-dashboard/`** — SQL 儀表板渲染器、面板編輯器、過濾器欄、儲存的視圖。
+- **`app/pages/analyses/`** — 分析列表和詳細視圖。
+- **`app/pages/DataSources.tsx`** — 資料來源載入 UI。
+- **`app/pages/DataDictionary.tsx`** — 詞典瀏覽器和編輯器。
+- **`.agents/skills/`** — 模式指導代理按需讀取：
+  - `dashboard-management` — 存儲、範圍分辨率、儀表板設定形狀
+  - `data-querying` — 要存取哪個腳本，過濾模式
+  - `adhoc-analysis` — 跨來源調查的工作流程
+  - `data-querying`, `real-time-sync`, `frontend-design`, `storing-data`, `self-modifying-code`
+- **`.builder/skills/<provider>/SKILL.md`** — 特定於提供者的問題（BigQuery、HubSpot、Jira、GA4 等）。查詢前請先閱讀；當您學到新東西時更新。
+- **`server/db/schema.ts`** - 用於儀表板、共用、視圖、分析、BigQuery 快取的 Drizzle 架構。
+- **`server/lib/dashboards-store.ts`** — 儀表板讀/寫，具有範圍解析和舊版 KV 遷移。
+- **`server/lib/bigquery.ts`** — BigQuery 用戶端、空執行驗證器、快取邏輯。
+
+要新增新資料來源，請在 `actions/` 中放置一個腳本，該腳本調用提供程序並通過 `output()` 幫助程序返回結果。它立即可供代理使用，並且可以在儀表板面板內使用（如果您通過伺服器處理程序公開結果）。
+
+要新增新的圖表型別，請在`app/pages/adhoc/sql-dashboard/types.ts`中擴充功能`ChartType`聯合，在`SqlChartCard.tsx`中進行處理，代理可以在任何面板中使用它。
+
+有關擴充功能範本的更廣泛模式，請參閱 [Skills guide](/docs/skills-guide) 和 [Actions](/docs/actions)。

package/docs/content/locales/zh-TW/template-assets.md

@@ -0,0 +1,303 @@
+---
+title: "資產"
+description: "代理原生數字資產管理器和跨代理生成服務，用於品牌一致的媒體。"
+---
+
+# 資產
+
+Assets 是一個代理原生工作區，用於建立和管理品牌一致的媒體。它將上傳和生成的結果組織到庫和資料夾中，讓團隊收集博客英雄、圖表、登陸頁面、產品鏡頭、影片和徽標的範例，然後通過代理聊天路由生成，以便可以審查和完善每個資產。
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>發布品牌</h1><span class='wf-pill accent'>博客 hero 圖</span><span class='wf-pill'>產品截圖</span><span class='wf-pill'>Logos</span><div style='flex:1'></div><button>Upload</button><button class='primary'>Generate</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>建立品牌媒體</strong><div class='wf-box'>使用已批準的 logo 和產品參考生成三個首頁面 hero 選項。</div><div style='display:flex;gap:8px;flex-wrap:wrap'><span class='wf-pill accent'>4 references</span><span class='wf-pill'>16:9</span><span class='wf-pill'>網頁面匯出</span></div></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px;flex:1'><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill accent'>主視覺 A</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>參考集</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Logo 安全</span></div></div><div class='wf-card' style='display:grid;grid-template-columns:repeat(4,1fr);gap:8px'><div class='wf-box'>Use</div><div class='wf-box'>Refine</div><div class='wf-box'>Compare</div><div class='wf-box'>Export</div></div></div>"
+}
+```
+
+當您開啟應用程式時，選定的庫、提示、參考文獻和生成的候選者將保留在一個工作區中。代理可以通過 UI 使用的同一個 actions 瀏覽、搜尋、生成、最佳化和匯出每個資產。
+
+```an-diagram title="生成、審查、重用" summary="參考和提示為生成和選取工作階段提供資訊；選定的資產進入庫並通過選取器或 A2A 流出到其他應用程式。"
+{
+  "html": "<div class=\"diagram-assets\"><div class=\"diagram-col\"><div class=\"diagram-node\">References<br><small class=\"diagram-muted\">logo、產品截圖、風格</small></div><div class=\"diagram-node\">提示<br><small class=\"diagram-muted\">聊天或 Generate 控件</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill accent\">生成工作階段</span><small class=\"diagram-muted\">image &amp; video candidates · audit log</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill ok\">Library</span><small class=\"diagram-muted\">已選、符合品牌的 assets</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">Picker<br><small class=\"diagram-muted\">iframe / MCP 應用</small></div><div class=\"diagram-node\">A2A<br><small class=\"diagram-muted\">幻燈片 · 設計 · 內容</small></div></div></div>",
+  "css": ".diagram-assets{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-assets .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-assets .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-assets .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## 何時采摘
+
+- **您的團隊需要可重複使用的視覺指導**，而不是一次性的通用媒體提示 - 收集經過批準的徽標、產品照片和風格範例，以便幾代人都能堅持品牌。
+- **您希望對生成的媒體進行審查和完善**，並為每次執行提供包含提示、模型、參考和沿襲的完整審核記錄。
+- **其他應用程式需要資產選取器或生成器** - 幻燈片、設計、內容、博客編輯器或網站建置器可以嵌入選取器或通過 A2A 調用資產。
+- **您希望編碼代理提供品牌媒體** - Codex、Claude Code、Claude 或 ChatGPT 無需離開聊天即可生成和選取資產。
+
+## 開始使用
+
+現場演示：[assets.agent-native.com](https://assets.agent-native.com)。
+
+1. **建立庫。**新增您的品牌、營銷活動、產品或內容流
+   想要管理。
+2. **上傳參考資料。**新增批準的徽標、產品照片、樣式範例或
+   現有影片，以便代理可以利用具體材料。
+3. **從聊天或庫中生成。**請求英雄圖片、圖表、產品
+   鏡頭或影片變體。資產存儲提示、參考、模型、狀態，
+   和血統供審查。
+4. **在其他地方使用該資源。**複製匯出，將選取器嵌入另一個
+   應用程式，或讓其他代理通過 A2A 調用 Assets。
+
+## 有用的提示
+
+- “使用 Acme 產品參考生成三個博客英雄選項。”
+- “以啟動活動風格建立方形社交形象。”
+- “查找用於重新設計的所有已批準資產。”
+- “將此上傳的圖表轉換為更清晰的產品解釋圖片。”
+- “建立影片故事板並將最佳幀集儲存到此庫。”
+
+## 你可以用它做什么
+
+- **建立資產庫。**按品牌、營銷活動、產品或類別對參考圖片、影片、規範徽標、樣式注釋、調色板、資料夾和生成的輸出進行分組。
+- **通過聊天生成。** Home 撰寫r 和庫生成控件使用 `sendToAgentChat()` 將提示發送給代理，以便使用者可以檢查變體、提供意見回饋和迭代。
+- **生成圖片和影片。** Builder 管理的圖片生成在啟用後可用，Gemini 負責影片生成以及手動圖片回退。
+- **上傳並描述參考資料。**從庫 UI 或提示作曲家附件按鈕新增圖片或影片，然後按標題、說明、替代文本、提示、模型、媒體型別、狀態、角色、資料夾或集合進行搜尋。
+- **保留生成審核記錄。**每次執行都會紀錄提示、模型、寬高比、參考、來源資產、沿襲、生成的資產、狀態、錯誤和時間戳，以供以後設計審查。
+- **保持徽標準確性。**代理可以生成預留位置區域，伺服器將上傳的規範徽標合成到最終圖片上，而不是依賴圖片模型重新繪制它。
+- **嵌入為選取器。**其他應用程式可以 iframe `/picker` 並偵听來自 `@agent-native/embedding` 的 `chooseAsset` 事件，將資產轉變為博客編輯器、網站建置器、幻燈片和自訂應用程式的資產選取器/生成器。選取器還會為現有的僅圖片主機發出舊版 `chooseImage` 別名。
+- **作為應用程式支持的技能安裝。** `agent-native.app-skill.json` 清單會匯出資產技能以及 MCP 連線器元資料，以便市場可以將應用程式、其說明及其選取器一起安裝。
+- **為其他代理提供服務。**幻燈片、設計、內容、郵件和調度可以通過 A2A 調用資產來列出庫、生成批次、建立影片、最佳化資產、獲取匯出以及在允許嵌入的情況下渲染內聯預覽。
+
+## 從編碼代理中使用它
+
+生成並選取品牌媒體，無需留下 Codex、Claude 程式碼、Claude 或 ChatGPT。
+
+1. **安裝一次。**這會新增技能說明並一起註冊託管的 MCP 連線器：
+
+   ```bash
+   npx @agent-native/core@latest skills 新增資產 # 別名：圖片生成
+   ```
+
+   預設用戶端為`codex`；為其他人新增 `--client claude-code` 或 `--client all`。
+   如果您只想通過Vercel/open獲得便攜技能說明
+   Skills CLI，使用：
+
+   ```bash
+   npx skills@最新新增BuilderIO/agent-native --技能資產
+   ```
+
+   Vercel/open Skills CLI 僅安裝指令檔案；它沒有
+   執行 MCP 連線器設定。需要時使用上面的 Agent Native CLI 路徑
+   單指令設定。
+
+2. **索要圖片。** 在代理的聊天中：“從 Acme 產品照片生成三個博客英雄選項。”代理會開啟包含候選圖片的選取器，您可以重新生成、重新調整（提示、方面、計數）並從中進行選取。
+3. **選取。** 在內聯主機（ChatGPT、Claude.ai、Claude 桌面主聊天）中，選取器直接在聊天中呈現 - 點選候選人，選取會自動返回。在 CLI/僅連結主機（Codex、Claude 程式碼、Claude 桌面“程式碼”分頁）上，您會獲得 **“在資產中開啟 →”** 連結；開啟它，在瀏覽器中進行選取，然後將複製的交接摘要貼上回聊天中 - 或者只是說“使用圖片 A”。
+
+   ```文本
+   將此選取貼上回您的聊天中，以便客服人員可以使用它。
+
+   為下一步選取的資產圖片：<label>
+   媒體URL：<url>
+   在目前工件或設計中使用此選定的資源。
+
+   選定的資產上下文：
+   { "selectedAsset": { "assetId": "...", "url": "...", "mediaType": "image", ... } }
+   ```
+
+4. **應用於程式碼。**所選媒體 URL 和 `assetId` 返回到代理，代理直接在其編寫的程式碼中使用 URL（`<img>` src，下載）或調用 `export-asset`。
+
+## 對於開發者
+
+本檔案的其餘部分適用於任何分叉資產範本或擴充功能它的人。
+
+### 腳手架
+
+```bash
+npx @agent-native/core@latest create my-assets --standalone --template assets
+```
+
+### 資料模型
+
+所有資料通過 Drizzle ORM 存儲在 SQL 中（二進制媒體存儲在物件存儲中，或開發期間的本機檔案上傳回退中）。架構：`templates/assets/server/db/schema.ts`。庫攜帶標準 `ownableColumns` 和匹配的框架共用表，因此它們屬於每使用者/每組織共用模型。
+
+注意：SQL 表名稱保留了應用程式被稱為 Images 時的舊 `image_*` 前綴。他們還涵蓋影片和其他媒體。
+
+| 表                               | 它包含什么                                                                                                                     |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `image_libraries`                | 庫 - 按品牌、營銷活動、產品或類別分組的頂級容器。儲存 `custom_instructions`、`style_brief`、規範徽標和封面資源引用以及存檔狀態 |
+| `image_library_shares`           | 框架共用表，將每個庫的主體（使用者或組織）對應到角色（檢視者、編輯者、管理員）                                                 |
+| `image_collections`              | 庫內的樣式/類別分組 - `style_brief`、`prompt_template`、預設寬高比和圖片大小                                                   |
+| `asset_folders`                  | 庫內的可嵌套資料夾（`parent_id` 表示層次結構）                                                                                 |
+| `image_generation_presets`       | 儲存的生成配方 - 媒體型別、提示範本、寬高比、模型和文本/參考策略                                                               |
+| `image_generation_sessions`      | 迭代生成和選取工作階段，包含簡介、狀態、活動資產和意見回饋摘要                                                                 |
+| `image_generation_session_items` | 工作階段中的候選資產，每個資產都有一個角色和注釋                                                                               |
+| `image_assets`                   | 資產紀錄 - 媒體型別、角色、狀態、標題/描述/替代文本、提示、模型、尺寸、MIME 型別、物件/縮略圖鍵和沿襲                          |
+| `image_generation_runs`          | 生成審核記錄 - 提示、編譯提示、模型、引用、狀態、錯誤以及觸發它的 `source` (`chat` / `ui` / `a2a`)                             |
+
+```an-schema title="資產資料模型" summary="Libraries are the ownable container; collections, folders, and presets organize them. Sessions drive generate-and-choose; assets and runs hold output and the audit log. Table names keep the legacy image_* prefix but cover all media."
+{
+  "entities": [
+    { "id": "library", "name": "image_libraries", "note": "頂級可擁有容器", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "custom_instructions", "type": "text", "nullable": true },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "logo_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true },
+      { "name": "archived", "type": "boolean" }
+    ] },
+    { "id": "library_shares", "name": "image_library_shares", "note": "框架股份表", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "role", "type": "text", "note": "viewer / editor / admin" }
+    ] },
+    { "id": "collections", "name": "image_collections", "note": "Style/category 分組", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "style_brief", "type": "text", "nullable": true },
+      { "name": "prompt_template", "type": "text", "nullable": true }
+    ] },
+    { "id": "folders", "name": "asset_folders", "note": "可嵌套資料夾", "fields": [
+      { "name": "library_id", "type": "id", "fk": "image_libraries.id" },
+      { "name": "parent_id", "type": "id", "fk": "asset_folders.id", "nullable": true }
+    ] },
+    { "id": "presets", "name": "image_generation_presets", "note": "已儲存的生成食譜", "fields": [
+      { "name": "media_type", "type": "text" },
+      { "name": "prompt_template", "type": "text" },
+      { "name": "model", "type": "text" }
+    ] },
+    { "id": "sessions", "name": "image_generation_sessions", "note": "迭代生成和選取", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "status", "type": "text" },
+      { "name": "active_asset_id", "type": "id", "fk": "image_assets.id", "nullable": true }
+    ] },
+    { "id": "session_items", "name": "image_generation_session_items", "note": "工作階段中的候選資產", "fields": [
+      { "name": "session_id", "type": "id", "fk": "image_generation_sessions.id" },
+      { "name": "asset_id", "type": "id", "fk": "image_assets.id" },
+      { "name": "role", "type": "text" }
+    ] },
+    { "id": "assets", "name": "image_assets", "note": "資產紀錄", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "media_type", "type": "text", "note": "image / video" },
+      { "name": "status", "type": "text" },
+      { "name": "prompt", "type": "text", "nullable": true },
+      { "name": "object_key", "type": "text", "nullable": true }
+    ] },
+    { "id": "runs", "name": "image_generation_runs", "note": "生成審核記錄", "fields": [
+      { "name": "model", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "source", "type": "text", "note": "chat / ui / a2a" }
+    ] }
+  ],
+  "relations": [
+    { "from": "library", "to": "collections", "kind": "1-n" },
+    { "from": "library", "to": "folders", "kind": "1-n" },
+    { "from": "library", "to": "assets", "kind": "1-n" },
+    { "from": "sessions", "to": "session_items", "kind": "1-n" },
+    { "from": "library", "to": "library_shares", "kind": "1-n" }
+  ]
+}
+```
+
+### 自訂它
+
+Assets 是一個完整的、可克隆的範本。一些實用的擴充功能想法：
+
+- “新增產品目錄連線器，以便 SKU 可以選取產品參考鏡頭。”
+- “在生成的資產被標記為可用於營銷之前新增嚴格的審批佇列。”
+- “新增品牌審核儀表板，按型號過濾失敗或評價較低的產品。”
+- “建立一個工作區範圍的預設資源庫並通過它生成幻燈片圖片。”
+- “檢查最新的提供程序檔案後，在圖片生成介面後面新增新的提供程序。”
+
+代理根據需要編輯路線、元件、actions、skills 和 SQL 支持的模型。請參閱 [Templates](/docs/cloneable-saas) 了解完整克隆、自訂、部署流程，並參閱 [A2A Protocol](/docs/a2a-protocol) 了解跨應用生成。
+
+### 嵌入選取器
+
+當人們在內部選取或生成資產時使用選取器路線
+another product. Image is the default media type; pass `mediaType=video` when
+您想要瀏覽/選取影片：
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+<EmbeddedApp
+  url="https://assets.agent-native.com/picker?mediaType=image"
+  onMessage={(name, payload) => {
+    if (name === "chooseAsset") {
+      insertAsset((payload as { url: string }).url);
+    }
+  }}
+/>;
+```
+
+外部MCP主機應該調用`open-asset-picker`而不是構造這個
+手動 iframe。該操作返回瀏覽器後備連結和 MCP 應用元資料
+對於內聯主機。當使用者選取資產時，選取器會發出 `chooseAsset`，
+圖片資源的舊版 `chooseImage` 別名，並更新 MCP 應用模型
+主機支持的上下文。當主機開啟後備連結時
+普通瀏覽器分頁，而不是內聯渲染 MCP 應用程式，選取資產
+複製切換摘要並顯示可複製的上下文塊；貼上該摘要
+返回聊天，以便外部代理可以使用所選媒體 URL 和
+資產元資料。
+
+Codex、Claude 程式碼和 Claude 桌面程式碼應被視為連結輸出主機
+對於此流程。他們可能不會內聯渲染 MCP 應用程式和遠端 CDN markdown
+圖片可能無法在聊天紀錄中可靠顯示。代理商應保留
+資產連結作為事實來源；當需要可見的內嵌預覽時
+程式碼編輯器聊天，下載選中的`previewUrl`/`downloadUrl`到本機
+圖片檔案並嵌入該絕對本機路徑。
+
+對於生成並選取流，請使用 `prompt` 調用 `open-asset-picker`，
+`autoGenerate: true` 和 `count: 3`（可自訂 1-6）。選取器開啟
+包含候選圖片，並讓使用者調整計數、長寬比或
+選取最終資產URL之前的生成預設。
+
+當其他代理需要在沒有代理的情況下建立、搜尋或匯出資產時，請使用 A2A
+人工揀選員 UI。
+
+### 開發者：分發應用技能
+
+資產應用技能的應用 ID為 `assets` 並託管 MCP URL
+`https://assets.agent-native.com/_agent-native/mcp`.
+
+```bash
+# 最簡單的託管安裝：匯出的技能說明加上 MCP 連線器。
+npx @agent-native/core@latest skills add assets
+
+# Vercel/open技能CLI安裝：僅匯出指令，無MCP設定。
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# 託管安裝：URL-僅限MCP連線器，技能檔案中沒有共用機密。
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# 本機可編輯啟動。
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Marketplace 包，包括 Claude Code 市場和 Vercel Labs 技能適配器。
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# 使用開放技能 CLI 安裝本機匯出的資源包。
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# 從生成的 Claude Code 市場適配器安裝。
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+匯出的技能教代理使用選取器進行人機互動
+選取，直接actions用於無人值守圖片/影片生成，以及瀏覽器
+內聯 MCP 應用程式不可用時的連結。
+
+Claude 市場適配器包含 `.claude-plugin/marketplace.json`
+目錄和帶有 `skills/assets/SKILL.md` plus 的 `agent-native-assets` 外掛
+託管的 `.mcp.json`。在互動式 Claude 程式碼中，可以使用相同的流程
+為 `/plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace`，
+`/plugin install agent-native-assets@agent-native-apps`、`/reload-plugins` 和
+`/mcp` 用於 MCP 驗證。
+
+如果您從帶有 `npx skills@latest` 的原始市場捆綁包安裝，請註冊
+託管 MCP 連線器，以便這些指令可以調用實時資產應用：
+
+```bash
+npx @agent-native/core@latest app-skill ensure --manifest ./dist/assets-skill/agent-native.app-skill.json --yes
+```
+
+## 下一步是什么
+
+- [**Templates**](/docs/cloneable-saas) — 克隆自有模型
+- [**Embedding SDK**](/docs/embedding-sdk) — iframe 選取器和 sidecar 模式
+- [**A2A Protocol**](/docs/a2a-protocol) — 其他應用如何調用資產
+- [**File Uploads**](/docs/file-uploads) - 存儲和經過驗證的資產服務
+- [**Sharing & Privacy**](/docs/sharing) — 庫級存取控制