@agent-native/core 0.79.2 → 0.79.6

package/corpus/core/docs/content/locales/zh-TW/template-chat.md

@@ -0,0 +1,129 @@
+---
+title: "聊天範本"
+description: "一個最小的聊天優先代理本機應用程式：持久的聊天線程、actions、應用程式狀態、實時同步、驗證以及新增您自己的 UI 的空間。"
+---
+
+# 聊天範本
+
+聊天是基本的代理本機應用程式起點。它為您提供了一個幹淨的 ChatGPT 風格的 shell，聊天位於中心，線程列表位於左側，標準應用程式導覽、驗證、實時同步、actions 和一個範例操作。當您想要一個無需提交域範本即可建置的真正的瀏覽器應用程式時，請從這裡開始。
+
+如果您想要最小的僅操作執行時且沒有瀏覽器 UI，請從 [Pure-Agent Apps](/docs/pure-agent-apps) 開始。如果您想要成品域產品形狀，請從 [Calendar](/docs/template-calendar)、[Mail](/docs/template-mail)、[Content](/docs/template-content)、[Forms](/docs/template-forms)、[Analytics](/docs/template-analytics) 或其他域範本開始。
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='min-height:560px;box-sizing:border-box;display:flex;align-items:center;justify-content:center;padding:56px 40px'><div style='display:flex;flex-direction:column;align-items:center;justify-content:center;gap:28px;width:min(700px,92%);min-height:430px'><div style='height:34px'></div><div style='text-align:center'><h1 style='margin:0'>我能幫什么？</h1><p class='wf-muted' style='margin:10px 0 0'>聊任何事情。新增 actions、元件、頁面、工作或你自己的後端。</p></div><div class='wf-card' style='width:100%;min-height:150px;display:flex;flex-direction:column;gap:18px'><span class='wf-muted'>給代理發訊息...</span><div style='flex:1'></div><div style='display:flex;align-items:center;gap:10px'><span data-icon='plus' aria-label='Attach'></span><div style='flex:1'></div><span class='wf-pill'>Sonnet 4.6 · Auto</span><span class='wf-pill'>Act</span><button class='primary'>↑</button></div></div><div style='height:34px'></div></div></div>"
+}
+```
+
+## 裡面有什么 {#whats-in-it}
+
+- 使用框架聊天介面和持久聊天線程在 `/` 上進行**全頁面聊天**。
+- **應用側邊欄中的話題列表**，以便使用者可以建立、重新開啟、重命名、固定和存檔聊天。
+- **代理聊天外掛**已預先設定，因此一旦設定了代理憑證，聊天就會與內置的應用程式代理循環進行對話。
+- **Auth** 通過更好的驗證 - 登入、註冊、工作階段、組織。相同的流程在本機和正式環境中執行；在開發中，電子郵件驗證被跳過。
+- **Actions 目錄**，包含一個範例 (`actions/hello.ts`) 以及標準 `view-screen` 和 `navigate` actions。
+- **框架的核心表**，用於應用程式狀態、設定、工作階段、資源、聊天線程、執行歷史紀錄和其他執行時狀態。
+- **實時同步** (`useDbSync`) 已連線，因此當代理寫入 SQL 時，UI 會自動刷新。
+- **AGENTS.md** 包含用於新增 actions、路線、skills 和應用程式狀態的聊天優先指南。
+
+## 其中*不*有什么 {#not-in-it}
+
+- 沒有域表或種子資料。
+- 沒有儀表板、列表、圖表、表單或提供者整合。
+- 除了範例存根之外，沒有特定於域的 actions。
+
+這就是重點。聊天是您自己的代理的一個薄而有用的預設外殼，而不是一個假裝通用的領域產品。
+
+```an-diagram title="Chat shell 中包含哪些內容" summary="框架標準執行時上的精簡聊天介面（操作、持久線程、實時同步和驗證），有空間新增您自己的 UI。"
+{
+  "html": "<div class=\"diagram-chat\"><div class=\"diagram-col left\"><div class=\"diagram-node\">線程列表<br><small class=\"diagram-muted\">建立 · 重新開啟 · 固定 · 封存</small></div><div class=\"diagram-node\">整頁面聊天<br><small class=\"diagram-muted\">/ 上的框架聊天介面</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">hello.ts · view-screen · navigate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col right\"><div class=\"diagram-box\">核心 SQL 表<br><small class=\"diagram-muted\">threads · application_state · settings · sessions · runs</small></div><div class=\"diagram-pill ok\">實時同步 &#8635;</div><div class=\"diagram-box\">Better Auth<br><small class=\"diagram-muted\">登入 · 組織 · 工作階段</small></div></div></div>",
+  "css": ".diagram-chat{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-chat .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-chat .diagram-arrow{font-size:22px;line-height:1}.diagram-chat .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 何時采摘 {#when-to-pick}
+
+- **您想要一個使用者可以立即交談的基本應用程式**，然後使用 actions 和 UI 進行擴充功能。
+- **您有一個無頭應用程式，需要聊天**作為第一個瀏覽器介面。
+- **您希望將自己的代理後端插入熟悉的聊天 UI**，同時保持 Agent-Native 的 actions、狀態、驗證和部署形狀。
+- \*\*您正在建置一個與域範本不匹配的自訂內部工具原型。
+
+## 腳手架 {#scaffolding}
+
+```bash
+npx @agent-native/core@latest create my-chat-app --template chat
+cd my-chat-app
+pnpm install
+pnpm dev
+```
+
+或者從沒有 UI 開始，然後新增聊天介面：
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+從那裡，將聊天範本的 `/` 路由和側邊欄線程列表複製到您的應用程式中，或者建置聊天應用程式並將 actions 從無頭代理行動到其 `actions/` 目錄中。關鍵不變數保持不變：actions 是聊天的共用介面，UI、HTTP、MCP、A2A 和 CLI。
+
+## 要檢查的第一個程式碼 {#first-code}
+
+- `actions/hello.ts` 是代理可以調用的啟動行為。更換它或
+  在其旁邊新增 actions。
+- `app/routes/_index.tsx` 渲染全頁面聊天介面。調整
+  建議、空狀態、作曲家或週圍布局。
+- `AGENTS.md` 告訴內置代理如何在此應用程式內工作。
+
+```an-file-tree title="Chat 範本布局"
+{
+  "entries": [
+    { "path": "actions/hello.ts", "note": "一個範例 action；替換它或在旁邊新增 actions" },
+    { "path": "actions/view-screen.ts", "note": "代理讀取的標準上下文 action" },
+    { "path": "actions/navigate.ts", "note": "標準導覽 action" },
+    { "path": "app/routes/_index.tsx", "note": "渲染整頁面 chat 介面；編輯建議、空狀態和 composer" },
+    { "path": "AGENTS.md", "note": "內置代理讀取的以 chat 為先的指南" }
+  ]
+}
+```
+
+聊天頁面故意變薄：
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return (
+    <AgentChatSurface
+      mode="page"
+      suggestions={[
+        "What can you do?",
+        "Help me customize this chat app",
+        "Show me the actions and pages I can add",
+      ]}
+    />
+  );
+}
+```
+
+## 使用您自己的代理後端 {#own-agent-backend}
+
+該範本預設使用內置的應用程式代理循環。要連線自訂後端，請交換代理聊天外掛後面的聊天執行時，而不是重寫 UI。聊天路由應該在共用聊天介面週圍保留一個薄渲染器；後端選取屬於伺服器外掛/執行時適配器。
+
+當您的模型編排已經存在於其他地方，但您仍然想要一個具有驗證、線程、actions、UI 狀態和可部署頁面的應用程式時，請使用此選項。
+
+## 首次編輯 {#first-edits}
+
+搭好腳手架後，詢問代理：
+
+> 新增 `notes` 的資料模型。注釋有 ID、標題、內文和所有者。在 `/notes` 渲染筆記頁面，新增建立/列出 actions，並保持聊天能夠建立筆記。
+
+代理應新增 Drizzle 架構、actions、路線、導覽和說明。然後您可以使用 UI 或聊天中的注釋功能。
+
+## 下一步是什么
+
+- [**Getting Started**](/docs) — 在無頭、聊天和域範本之間進行選取
+- [**Agent Surfaces**](/docs/agent-surfaces) — 無頭、聊天、嵌入式和完整應用模式
+- [**Actions**](/docs/actions) - 操作系統聊天和 UI 都調用
+- [**Native 聊天介面**](/docs/native-chat-ui) — 聊天介面基元和執行時選項
+- [**Pure-Agent Apps**](/docs/pure-agent-apps) - 僅限操作的應用程式，稍後可以發展為聊天

package/corpus/core/docs/content/locales/zh-TW/template-clips.md

@@ -0,0 +1,368 @@
+---
+title: "剪輯"
+description: "非同步螢幕錄製、行事曆同步會議紀錄和一鍵通語音听寫 - 將 Clips 連結貼上到座席中，他們就可以閱讀文字紀錄、視覺效果和摘要。"
+search: "Clips 瀏覽器記錄 開發人員記錄 控制台記錄 網路記錄 獲取 XHR Chrome 擴充功能 診斷紀錄器 桌面應用"
+---
+
+# 剪輯
+
+一款捕獲一切的應用程式：螢幕錄製、行事曆中的會議紀錄以及按住 Fn 的語音听寫。代理會轉錄、標題、總結和索引所有內容 - 然後讓您詢問“找到我們討論推出計畫的剪輯”並搜尋您曾經制作的每個轉錄。
+
+```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'>工程 Clips</h1><span class='wf-pill accent'>Library</span><span class='wf-pill'>Meetings</span><span class='wf-pill'>Dictation</span><div style='flex:1'></div><button>Import</button><button class='primary'>Record</button></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card' style='height:120px;display:flex;flex-direction:column;justify-content:end'><strong>OKR 評審</strong><small>35 min</small></div><div class='wf-card' style='height:120px;display:flex;flex-direction:column;justify-content:end'><strong>入門流程</strong><small>12 min</small></div><div class='wf-card' style='height:120px;display:flex;flex-direction:column;justify-content:end'><strong>Bug 複現</strong><small>4 min</small></div></div><div class='wf-card' style='display:flex;gap:10px;align-items:center'><span class='wf-pill accent'>代理可讀</span><span>轉寫 + 幀已可用於分享連結</span><div style='flex:1'></div><button>分享</button></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><strong>轉錄搜尋</strong><div class='wf-box'>匹配章節 03:12 · 發布風險和負責人交接</div><div class='wf-box'>會議摘要和行動項</div></div></div>"
+}
+```
+
+沿著將 Loom + Granola + Wispr Flow 整合到一個應用程式中的思路來思考 — 但代理在每個介面上都是一流的編輯器，並且錄音、會議和听寫都是您的，而不是 SaaS 供應商的。 Clips 還使共用錄音可供代理讀取：將普通的 Clips 共用連結貼上到代理中，它可以“听到”文本形式的文字紀錄，並“看到”帶有時間戳的螢幕幀作為圖片 - 無需原始影片。幀檢視適用於任何具有圖片功能的代理（ChatGPT、Claude 程式碼、光標、Codex）；純文本網路聊天仍然可以獲得完整的文字紀錄，並且可以拍攝您上傳的幀。
+
+```an-diagram title="捕獲、轉錄、重用" summary="三種捕獲型別集中在一個庫中；代理進行抄寫、標題和總結，然後每個抄本都可以搜尋和共用。"
+{
+  "html": "<div class=\"diagram-clips\"><div class=\"diagram-col\"><div class=\"diagram-node\">螢幕錄製</div><div class=\"diagram-node\">行事曆會議</div><div class=\"diagram-node\">按住 Fn 听寫</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>一個庫<br><small class=\"diagram-muted\">recordings + transcripts (SQL)</small></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\">標題 · 摘要 · 章節</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">搜尋</div><div class=\"diagram-pill\">分享</div><div class=\"diagram-pill\">代理可讀 links</div></div></div>",
+  "css": ".diagram-clips{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-clips .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-clips .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-clips .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## 你可以用它做什么
+
+- **使用內置錄音機、網路攝像頭覆蓋、音訊捕獲和暫停/修剪來錄製螢幕**。
+- **從行事曆中捕獲會議。** 連線 Google Calendar，在側邊欄中檢視即將舉行的會議，並在任何一個會議上進行紀錄。您將在結束時獲得實時紀錄以及 AI 摘要、專案符號注釋和行動專案。
+- **一鍵通听寫。** 按住機器上的 Fn，說話，清理後的文本就會放入您正在使用的任何應用程式中。每個听寫都儲存在可搜尋的歷史紀錄中，原始版本和人工智能清理的版本並排儲存。
+- **為每個錄音獲取自動生成的標題、摘要和章節標記** - 客服人員會填寫這些內容並使其保持最新狀態。
+- **搜尋每一份紀錄** — 螢幕錄影、會議和听寫都在一個庫中。 “找到我們討論推出計畫的剪輯。”
+- **共用剪輯**以及每個剪輯的權限（公開、團隊、私人）。連結跟蹤和線索評論也有效。
+- **在 Slack 中預覽公開剪輯**，並在播放後使用 Loom 風格的可播放展開
+  工作區安裝您的 Clips Slack 應用。
+- **使用 Chrome 擴充功能捕獲瀏覽器記錄。**瀏覽器紀錄可以
+  附加經過編輯的控制台記錄和 fetch/XHR 元資料，這對
+  產品錯誤和僅限瀏覽器的重現。
+- **將剪輯連結貼上到代理中**，以便他們可以發現代理可讀的上下文：元資料、轉錄片段、推薦幀和帶時間戳的幀圖片，而無需接收原始影片檔案。
+- **智能圖書館視圖。**按專案分組、按演講者過濾、根據內容自動標記。
+- **通過聊天編輯文字紀錄。**“修複 1:42 處錯誤轉錄的單詞。” “為博客文章引用三個引號。”代理編輯文字紀錄並實時更新 UI。
+
+## 瀏覽器記錄和開發人員診斷
+
+當您需要錄製內容以及瀏覽器記錄時，請使用 Clips Chrome 擴充功能
+您正在偵錯的分頁。該擴充功能啟動活動標籤紀錄並且可以
+儲存編輯後的控制台記錄、JavaScript 異常和 fetch/XHR 網路
+元資料，例如方法、編輯的 URL、狀態、持續時間和失敗文本。它
+不儲存請求內文、回應內文或標頭。
+
+常規瀏覽器紀錄器頁面可以儲存紀錄器頁面的診斷資訊
+本身。 Chrome 擴充功能是活動分頁開發人員記錄的路徑，
+僅瀏覽器重現。在剪輯 UI 中，使用 Chrome 選項檢視瀏覽器記錄並
+桌面應用程式提供最無縫的日常捕捉路徑。
+
+Agent-Native Clips Chrome 擴充功能列表為
+`https://chromewebstore.google.com/detail/baoipacpchggcdigagnajakiidcgcffn`.
+如果您託管自己的 Clips 伺服器，請隱藏 Chrome 擴充功能選項，直到
+您的網上應用店列表已上線。設定`VITE_CLIPS_CHROME_EXTENSION_ENABLED=1`
+批準後在桌面應用程式下載提示旁邊顯示擴充功能。設定
+`VITE_CLIPS_CHROME_EXTENSION_URL` 僅當您需要覆蓋預設值時
+列出 URL。
+
+## 客服人員可讀的剪輯
+
+將普通的公開 Clips 共用連結貼上到代理中。分享頁面有廣告
+一個緊湊的代理上下文 URL，並且該上下文指向轉錄本和框架
+APIs，因此僅接受文本或靜態圖片的模型仍然可以理解內容
+發生在錄音中。
+
+任何可以將圖片 URL 提取到其視野中的代理 - ChatGPT、Claude 程式碼，
+光標、Codex 和 MCP 連線的代理 — 讀取腳本並檢視
+幀。一些純文本網路聊天會讀取文字紀錄，但不會提取幀圖片
+獨自一人；在那裡，上傳關鍵幀或以支持圖片的方式開啟剪輯
+代理。
+
+| 端點                                              | 代理可以獲得什么                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------- |
+| `/api/agent-context.json?id=<recordingId>`        | 剪輯元資料、轉錄狀態、章節、CTA、推薦幀以及指向轉錄/幀 API 的連結       |
+| `/api/agent-transcript.json?id=<recordingId>`     | 帶有 `startMs`、`endMs`、可讀時間戳、文本和可選來源標籤的時間戳轉錄片段 |
+| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | 以原始影片時間戳從影片中提取的 JPEG 幀                                  |
+
+端點遵循與共用頁面相同的公開/密碼/過期規則。
+受密碼保護的剪輯需要密碼一次；成功回應返回
+短暫的標記化連結，因此下游代理不需要明文
+密碼。
+
+Slack 預覽使用相同的共用邊界。 `/api/slack/unfurl` Webhook
+僅返回可播放的 Slack `video` 塊，用於準備就緒的公開剪輯，而無需
+密碼、過期命中、存檔標記或垃圾標記。其他剪輯仍然得到
+正常共用頁面標題/縮略圖元資料並需要開啟剪輯。
+
+```an-api title="代理上下文入口點"
+{
+  "method": "GET",
+  "path": "/api/agent-context.json",
+  "summary": "共用剪輯的緊湊、代理可讀的描述",
+  "description": "Returns clip metadata, transcript status, chapters, CTAs, recommended frames, and links to the transcript and frame APIs. Advertised by the public share page so a text- or image-only agent can understand a recording without ingesting raw video.",
+  "auth": "Same public / password / expiry rules as the share page",
+  "params": [
+    { "name": "id", "in": "query", "type": "string", "required": true, "description": "Recording id" }
+  ],
+  "responses": [
+    { "status": "200", "description": "Clip metadata plus transcript and frame API links" }
+  ]
+}
+```
+
+```an-api title="帶時間戳的文字紀錄"
+{
+  "method": "GET",
+  "path": "/api/agent-transcript.json",
+  "summary": "共用剪輯的帶時間戳的轉錄片段",
+  "params": [
+    { "name": "id", "in": "query", "type": "string", "required": true, "description": "Recording id" }
+  ],
+  "responses": [
+    { "status": "200", "description": "Segments with startMs, endMs, readable timestamps, text, and optional source labels" }
+  ]
+}
+```
+
+```an-api title="具有時間戳的幀"
+{
+  "method": "GET",
+  "path": "/api/agent-frame.jpg",
+  "summary": "在原始影片時間戳處從影片中提取的 JPEG 幀",
+  "params": [
+    { "name": "id", "in": "query", "type": "string", "required": true, "description": "Recording id" },
+    { "name": "atMs", "in": "query", "type": "integer", "required": true, "description": "Original-video timestamp in milliseconds" }
+  ],
+  "responses": [
+    { "status": "200", "description": "image/jpeg frame" }
+  ]
+}
+```
+
+## 開始使用
+
+現場演示：[clips.agent-native.com](https://clips.agent-native.com)。
+
+1. **開啟庫。**瀏覽螢幕錄音、會議錄音、听寫，
+   來自一個位置的資料夾和空間。
+2. **錄製或匯入。**捕獲螢幕錄製，從行事曆開始
+   會議，或使用一鍵通听寫。
+3. **讓代理清理它。**生成標題、摘要、章節、操作
+   專案，或清理後的轉錄文本。
+4. **搜尋和重複使用。**詢問您的剪輯、引言、行動專案或決定
+   需要，然後以正確的可見性分享結果。
+
+### 有用的提示
+
+- “總結此剪輯以進行產品更新。”
+- “查找我們討論推出計畫的會議。”
+- “從此紀錄中提取三個客戶報價。”
+- “根據上次銷售拜訪建立行動專案。”
+- “清理這個听寫並將其變成 Linear 票證。”
+
+## 對於開發者
+
+本檔案的其餘部分適用於任何派生 Clips 範本或擴充功能它的人。
+
+### 快速入門
+
+```bash
+npx @agent-native/core@latest create my-clips --standalone --template clips
+cd my-clips
+pnpm install
+pnpm dev
+```
+
+Clips 是一個帶有本機紀錄器的較大範本（它附帶了用於本機捕獲的桌面伴侶）。上傳錄音之前需要執行三個設定步驟：
+
+1. **影片存儲（必需）。** 通過入門向導連線存儲後端。最簡單的路徑是Builder.io（測試期間免費，一鍵式）。對於自託管存儲，請設定 `S3_ENDPOINT`、`S3_BUCKET`、`S3_ACCESS_KEY_ID`、`S3_SECRET_ACCESS_KEY` 以及可選的 `S3_REGION` 和 `S3_PUBLIC_BASE_URL`。 Cloudflare R2 和 DigitalOcean Spaces 使用帶有 `R2_*` 前綴的相同環境變數。
+2. **Google Calendar（可選）。** 要同步即將召開的會議，請從“設定”連線 Google Calendar 帳戶。 dev中的OAuth 回呼URL是`http://localhost:8094/_agent-native/google/callback`。在 [Google Cloud Console](https://console.cloud.google.com/) 中設定 Google OAuth 用戶端，並啟用 Gmail 和 Google Calendar API。
+3. **螢幕捕獲權限。** 在 macOS 上，在系統設定 → 隱私和安全 → 螢幕錄製中向瀏覽器（或桌面配套應用程式）授予螢幕錄製權限。瀏覽器紀錄可以儲存經過編輯的控制台並從紀錄器頁面獲取/XHR 診斷資訊。 Chrome 擴充功能列表可用後，啟用 `VITE_CLIPS_CHROME_EXTENSION_ENABLED=1`，以便使用者可以選取活動分頁瀏覽器記錄的擴充功能或桌面應用程式以獲得最流暢的本機捕獲路徑。
+4. **Slack 預覽（可選）。** 使用 `links:read`、`links:write` 和 `links.embed:write` 建立 Slack 應用程式；訂閱`link_shared`；在 **App Unfurl Domains** 下新增您的 Clips 共用域；將請求URL設定為`https://your-clips.example.com/api/slack/unfurl`；並新增 OAuth 重新導向 URL `https://your-clips.example.com/api/slack/oauth/callback`。設定 `SLACK_CLIENT_ID`、`SLACK_CLIENT_SECRET` 和 `SLACK_SIGNING_SECRET`，然後從剪輯設定連線工作區。
+
+### 託管您自己的 Clips 伺服器
+
+[clips.agent-native.com](https://clips.agent-native.com) 上託管的 Clips 應用
+只是 Clips 範本的部署副本。要執行您自己的伺服器，腳手架
+範本，像任何其他代理本機應用程式一樣部署它，然後指向桌面
+部署中的托盤應用程式。
+
+1. **建立應用程式。**
+
+   ```bash
+   npx @agent-native/core@latest 建立 my-clips --standalone --template 剪輯
+   cd my-clips
+   pnpm安裝
+   ```
+
+2. **設定正式環境狀態。**設定一個持久化的`DATABASE_URL`，正常
+   來自 [Deployment](/docs/deployment) 的正式環境授權/秘密變數，以及
+   影片存儲提供者。 Builder.io Connect是最簡單的存儲路徑；對於
+   自託管存儲，使用 `S3_*` 或 `R2_*` 變數進行 S3 兼容
+   桶。
+
+3. **部署 Web 應用程式。**對於普通節點部署：
+
+   ```bash
+   pnpm建置
+   節點.output/server/index.mjs
+   ```
+
+   您還可以使用 [Deployment](/docs/deployment) 中的任何 Nitro 目標，例如
+   作為 Netlify、Vercel、Cloudflare Pages、AWS Lambda 或 Deno Deploy。確保
+   例如，`BETTER_AUTH_URL` 是公開 Clips 來源
+   `https://clips.example.com`.
+
+4. **連線桌面托盤應用。**開啟 Clips Desktop 設定並進行設定
+   **將伺服器 URL** 剪輯到部署的公開基礎 URL，例如
+   `https://clips.example.com`。如果應用程式安裝在工作空間路徑下，
+   包含該路徑，例如 `https://example.com/clips`。點選**連線**，
+   然後使用該 Clips 伺服器上的帳戶登入。
+
+5. **發布後啟用 Chrome 擴充功能。**保留
+   `VITE_CLIPS_CHROME_EXTENSION_ENABLED` 在 Chrome 網上應用店上市之前未設定
+   已獲批準。然後將其設定為 `1` 以顯示瀏覽器記錄選項旁邊
+   桌面應用程式提示。預設列表URL是
+   `https://chromewebstore.google.com/detail/baoipacpchggcdigagnajakiidcgcffn`;
+   僅當您的部署使用時才設定 `VITE_CLIPS_CHROME_EXTENSION_URL`
+   不同的擴充功能名列表。
+
+6. **連線可選整合。** Google Calendar 為“會議”分頁提供支持，
+   `GEMINI_API_KEY` 或 Builder.io Connect 支持轉錄清理和標題，
+   `GROQ_API_KEY` 可以提供語音轉文本回退，而 Slack OAuth
+   “設定”中的連線可以展開可玩的 Slack。
+
+對於本機開發，請使用 `pnpm dev` 執行 Web 應用程式並指向桌面
+`http://localhost:8094` 上的托盤應用程式。
+
+### 主要功能
+
+**一個庫，三種捕獲型別。**螢幕錄製、行事曆會議和一鍵通听寫共用一個可搜尋庫。
+
+**文字紀錄和 AI 管道。** 錄音獲取帶有時間戳的文字紀錄片段、生成的標題、摘要和章節標記。
+
+**非破壞性編輯。**修剪、分割、填充詞刪除、靜音刪除和拼接保留在 `edits_json` 中，因此原始媒體保持完整。
+
+**客服人員可讀的共用連結。**公開共用連結公開文字紀錄和框架 API，以便客服人員無需攝取原始影片即可理解錄音。
+
+**Slack 可玩展開。**公開共用連結可以渲染 Slack `video` 塊
+指向現有的 `/embed/:id` 玩家。這是一個工作區 Slack 應用
+安裝，不是全域爬蟲行為：正常的 Open Graph/Twitter 元資料是
+未安裝應用程式時的後備。
+
+### 資料模型
+
+所有資料通過 Drizzle ORM 存儲在 SQL 中。架構：`templates/clips/server/db/schema.ts`。錄音、會議、听寫、行事曆帳戶和詞匯都帶有標準 `ownableColumns` 並具有匹配的框架共用表，因此它們屬於每使用者/每組織共用模型。
+
+```an-schema title="Clips 核心資料模型" summary="recordings is the source of truth for media; transcripts, meetings, and dictations compose with it rather than duplicating video. (Engagement and org tables omitted for clarity — see the full table below.)"
+{
+  "entities": [
+    {
+      "id": "recordings",
+      "name": "recordings",
+      "note": "Core resource; source of truth for media. ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "title", "type": "text" },
+        { "name": "video_url", "type": "text", "note": "plus format / size / duration / thumbnails" },
+        { "name": "status", "type": "text" },
+        { "name": "edits_json", "type": "text", "note": "非破壞性編輯" },
+        { "name": "chapters_json", "type": "text", "nullable": true },
+        { "name": "password", "type": "text", "nullable": true, "note": "隱私：密碼/有效期" }
+      ]
+    },
+    {
+      "id": "recording_transcripts",
+      "name": "recording_transcripts",
+      "note": "拆分以便庫和轉錄視圖可以快速渲染",
+      "fields": [
+        { "name": "recording_id", "type": "text", "fk": "recordings.id" },
+        { "name": "segments_json", "type": "text", "note": "{ startMs, endMs, text }" },
+        { "name": "full_text", "type": "text" },
+        { "name": "language", "type": "text" },
+        { "name": "status", "type": "text" }
+      ]
+    },
+    {
+      "id": "clips_meetings",
+      "name": "clips_meetings",
+      "note": "Calendar-sourced or ad-hoc; owns a recording",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "recording_id", "type": "text", "fk": "recordings.id", "nullable": true },
+        { "name": "summary_md", "type": "text", "nullable": true },
+        { "name": "bullets_json", "type": "text", "nullable": true },
+        { "name": "action_items_json", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "clips_dictations",
+      "name": "clips_dictations",
+      "note": "Push-to-talk dictation history; ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "full_text", "type": "text", "note": "原料" },
+        { "name": "cleaned_text", "type": "text", "nullable": true },
+        { "name": "source", "type": "text", "note": "fn-按住等" },
+        { "name": "target_app", "type": "text", "nullable": true }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "recordings", "to": "recording_transcripts", "kind": "1-1", "label": "transcript" },
+    { "from": "recordings", "to": "clips_meetings", "kind": "1-1", "label": "captured by" }
+  ]
+}
+```
+
+| 表                                              | 它包含什么                                                                                                                              |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `recordings`                                    | 核心資源 - 標題、影片 URL/格式/大小、持續時間、縮略圖、狀態、無損 `edits_json`、`chapters_json`、隱私（密碼、過期）和播放器切換         |
+| `recording_transcripts`                         | 每次錄製的文字紀錄：`segments_json` (`{startMs,endMs,text}`)、`full_text`、語言和狀態                                                   |
+| `recording_tags`                                | 錄音上的自由格式標籤                                                                                                                    |
+| `recording_ctas`                                | 覆蓋在錄音上的號召性用語按鈕（標籤、網址、顏色、位置）                                                                                  |
+| `recording_comments`                            | 帶有表情符號反應圖和已解決標志的線程化、帶時間戳的評論                                                                                  |
+| `recording_reactions`                           | 表情符號 reactions 固定到影片時間戳（允許匿名觀看者）                                                                                   |
+| `recording_viewers` / `recording_events`        | 觀看分析：每個觀看者的觀看時間和完成情況，以及精細事件（觀看開始、觀看進度、搜尋、暫停、CTA 點擊、反應）                                |
+| `clips_meetings`                                | 行事曆來源或臨時會議 - 計畫/實際跨度、平台、使用者注釋、AI `summary_md`、`bullets_json`、`action_items_json` 及其 `recording_id` 的連結 |
+| `meeting_participants` / `meeting_action_items` | 與會者和提取的會議行動專案                                                                                                              |
+| `calendar_accounts` / `calendar_events`         | 連線的行事曆帳戶（OAuth 代幣存在於 `app_secrets` 中，僅在此處引用）和同步的事件快照                                                     |
+| `clips_dictations`                              | 一鍵通听寫歷史紀錄 - 原始 `full_text`、可選 `cleaned_text`、來源（`fn-hold` 等）和目標應用                                              |
+| `clips_vocabulary`                              | 個人詞匯更正（術語→首選替換）會影響未來的听寫                                                                                           |
+| `spaces` / `space_members` / `folders`          | 庫組織 - 空間（主題範圍容器）、其成員和可嵌套資料夾                                                                                     |
+| `organization_settings`                         | 每個組織的 Clips sidecar：品牌顏色、徽標、預設可見性                                                                                    |
+
+錄音和文字紀錄是故意分開的表，因此庫和文字紀錄視圖都可以快速渲染。會議由錄音組成，而不是複製媒體：會議擁有其捕獲的錄音，但 `recordings` 行仍然是影片和每段文字紀錄的真實來源。
+
+UI 中的路由位於 `templates/clips/app/routes/` 下 - 經過驗證的應用程式位於 `_app.*` 下（庫、空間、資料夾、會議、听寫、見解、垃圾箱、設定），公開介面位於 `r.$recordingId`、`share.$shareId`、`embed.$shareId` 和 `invite.$token`。
+
+### 金鑰actions
+
+每個代理可調用操作都是 `templates/clips/actions/` 中的 TypeScript 檔案，自動安裝在 `POST /_agent-native/actions/:name` 上，並可作為 `pnpm action <name>` 從 CLI 執行。有~80個actions；有用的分組：
+
+- **錄製生命週期** — `create-recording`、`finalize-recording`、`update-recording`、`set-thumbnail`、`archive-recording` / `restore-recording` / `trash-recording` / `delete-recording-permanent`、`move-recording`、`tag-recording`。
+- **成績單和 AI** — `request-transcript`、`cleanup-transcript`、`regenerate-title` / `regenerate-summary` / `regenerate-chapters`、`set-chapters`、`generate-workflow`。 （`cleanup-transcript` 和 `finalize-meeting` 是伺服器端媒體管道調用；大多數其他 AI 功能委托給代理聊天。）
+- **編輯** — 非破壞性 `trim-recording`、`split-recording`、`remove-filler-words`、`remove-silences` 以及 `stitch-recordings`、`undo-edit`、`clear-edits`。編輯累積在`edits_json`；用戶端通過 ffmpeg.wasm 連線/匯出。
+- **會議** — `create-meeting`、`start-meeting-recording` / `stop-meeting-recording`、`finalize-meeting`、`update-meeting`、`get-meeting`、`list-meetings`，以及行事曆接線 `connect-calendar` / `disconnect-calendar` / `sync-calendars` / `list-calendar-accounts`。
+- **听寫** - `create-dictation`、`cleanup-dictation`、`update-dictation`、`list-dictations` 和 `add-vocabulary-term` / `list-vocabulary` 用於個人詞匯偏差。
+- **圖書館組織** — `create-space` / `rename-space` / `delete-space`、`add-space-member` / `remove-space-member`、`create-folder` / `rename-folder` / `delete-folder`、`add-recording-to-space`。
+- **分享、評論和參與** — 框架共用 actions 加上 `create-cta` / `update-cta` / `delete-cta`、`add-comment` / `reply-to-comment` / `resolve-comment` / `react-to-comment` / `delete-comment`、`react-to-recording`、 `list-viewers`。
+- **組織和成員** — `create-organization`、`set-organization-branding`、`invite-member` / `accept-invite` / `decline-invite` / `get-invite`、`remove-member`、`update-member-role`、`list-organization-state`、`list-notifications`。
+- **搜尋、見解和匯出** - `search-recordings`（匹配標題、描述、轉錄文本和評論，帶時間戳）、`get-recording-insights`、`get-organization-insights`、`export-insights-csv`、`export-to-brain`。
+- **上下文和導覽** — `view-screen`（目前剪輯、播放頭、選定的轉錄範圍）和 `navigate`；突變後的`refresh-list`。
+
+### 自訂它
+
+Clips 是一個完整的、可克隆的範本——分叉它並要求代理擴充功能它。一些例子：
+
+- “新增一個填充詞刪除按鈕，從紀錄中刪除 ums 和 uhs 並重新拼接影片。”
+- “每當會議結束時，自動將我的站立筆記發布到 Slack #eng。” （先通過[Messaging](/docs/messaging)連線Slack。）
+- “新增一個熱鍵，將最後一次听寫作為新票放入 Linear 中。”
+- “按專案對庫進行分組 - 從每個轉錄本的第一個單詞中檢測專案。”
+- “新增一個‘從此剪輯生成博客文章’按鈕，該按鈕可以從文字紀錄中起草一篇文章並將其另存為草稿。”
+- “讓觀看者在共用剪輯上留下帶時間戳的 reactions。”
+
+代理根據需要編輯路由、元件、轉錄管道和架構。請參閱 [Templates](/docs/cloneable-saas) 了解完整克隆、自訂、部署流程，如果這是您的第一個代理本機範本，請參閱 [Getting Started](/docs/getting-started)。
+
+## 下一步是什么
+
+- [**Templates**](/docs/cloneable-saas) — 克隆自有模型
+- [**Context Awareness**](/docs/context-awareness) — 代理如何知道目前剪輯和播放頭
+- [**Agent Teams**](/docs/agent-teams) — 將轉錄清理委托給專業子代理