@agent-native/core 0.79.2 → 0.79.5

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

@@ -0,0 +1,220 @@
+---
+title: "調度"
+description: "Dispatch 是工作區控制平面 - 中央收件箱、跨應用編排、秘密庫、Slack/Telegram 整合和計畫作業。"
+---
+
+# 調度
+
+> **另請參閱：** 有關 Dispatch 功能以及何時需要它的概念概述，請參閱 [Dispatch](/docs/dispatch)。此頁面是特定於範本的參考。
+
+Dispatch 是**工作區控制平面**。其他範本是域應用程式（郵件、行事曆、分析、大腦），而 Dispatch 是您與它們一起執行以協調一切的應用程式：中央收件箱、機密庫、計畫作業、Slack/Telegram 整合以及通過 [A2A](/docs/a2a-protocol) 將域工作委托給正確的專業應用程式的協調器代理。
+
+```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'>Dispatch</h1><span class='wf-pill accent'>Overview</span><span class='wf-pill'>Inbox</span><span class='wf-pill'>Secrets</span><span class='wf-pill'>Approvals</span><div style='flex:1'></div><button>Schedules</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>接下來該做什么？</strong><div class='wf-box'>詢問 Analytics 本週註冊數並起草 Slack 更新。</div><button class='primary'>Delegate</button></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:10px'><div class='wf-card'><strong>Mail</strong><br/><small>/mail</small></div><div class='wf-card'><strong>Calendar</strong><br/><small>/calendar</small></div><div class='wf-card'><strong>Analytics</strong><br/><small>/analytics</small></div><div class='wf-card'><strong>Slides</strong><br/><small>/slides</small></div><div class='wf-card'><strong>Forms</strong><br/><small>/forms</small></div><div class='wf-card'><strong>建立應用</strong><br/><small>+</small></div></div><div class='wf-card' style='display:grid;grid-template-columns:repeat(3,1fr);gap:8px'><div class='wf-box'>Slack 私信 needs reply</div><div class='wf-box'>A2A 工作已完成</div><div class='wf-box'>需要批準</div></div></div>"
+}
+```
+
+如果您正在執行帶有許多應用程式的 [multi-app workspace](/docs/multi-app-workspace)，Dispatch 就是粘合劑。
+
+```an-diagram title="統筹安排，不要專門化" summary="來自每個渠道的訊息都會集中在一個收件箱中；編排器通過 A2A 對域工作進行分類和委托給正確的專業應用程式 — 秘密、資源和批準保持核心。"
+{
+  "html": "<div class=\"diagram-dispatch\"><div class=\"diagram-col\"><div class=\"diagram-node\">Slack · Telegram</div><div class=\"diagram-node\">Email</div><div class=\"diagram-node\">A2A 請求</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill accent\">Orchestrator</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-node\">郵件 Agent</div><div class=\"diagram-node\">分析 Agent</div><div class=\"diagram-node\">Brain · Slides &hellip;</div></div></div><div class=\"diagram-shared\"><span class=\"diagram-pill\">金鑰保險庫</span><span class=\"diagram-pill\">工作區資源</span><span class=\"diagram-pill warn\">Approvals</span><span class=\"diagram-pill\">計畫工作</span></div>",
+  "css": ".diagram-dispatch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-dispatch .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-dispatch .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-dispatch .diagram-arrow{font-size:20px;line-height:1}.diagram-shared{display:flex;gap:8px;flex-wrap:wrap;margin-top:12px}"
+}
+```
+
+## 它的作用 {#what-it-does}
+
+- **中央收件箱。** Slack 私信、電報訊息、電子郵件通知、來自其他代理的 A2A 請求 — 全部集中在一個地方。 Dispatch 代理會進行分類並自行處理或委托處理。請參閱 [Messaging](/docs/messaging) 了解如何將 Slack、電子郵件和 Telegram 連線到您的工作區。
+- **協調者，而不是專家。** Dispatch 並不嘗試成為電子郵件應用程式或分析應用程式。當有人詢問“總結上週的註冊情況”時，Dispatch 會通過 A2A 調用分析代理並返回答案。當有人要求“起草給 Alice 的回複”時，Dispatch 會致電郵件代理。
+- **控制平面 shell。** 聊天、專案、執行、工作區應用程式、代理和自動化位於一個操作 shell 中，具有狀態優先列表和深入分析，而不是一次性儀表板。
+- **秘密庫。** API 金鑰、OAuth 權杖和共用憑證的中央存儲。工作區中的應用程式從 Dispatch 解析機密，而不是在每個 `.env` 中複製它們。敏感存取的請求+批準。
+- **工作區資源。** 全域 skills、護欄指令、自訂代理設定檔案、參考資源和 HTTP MCP 伺服器可以在 Dispatch 中建立一次。所有應用程式資源在執行時由每個應用程式繼承，無需複製或手動同步步驟；選定的補助金適用於特定於應用程式的例外情況。
+- **可重複使用的整合。**連線提供者帳戶、跟蹤的一處
+  憑證參考，並授予應用程式存取權限。 Dispatch 擁有提供者身分並且
+  應用補助金；域應用程式仍然擁有特定於應用程式的來源選取，例如 Brain 的
+  Slack 渠道允許列表或 Analytics 的指標/儀表板設定。
+- **預定工作中心。**跨應用 [recurring jobs](/docs/recurring-jobs) 在此直播：“每個工作日 7 點，從分析中提取昨天的關鍵指標，並起草一份早晨摘要電子郵件。”
+- **夢想。** Dispatch 可以審查最近的代理執行、失敗、意見回饋和成功模式，以在應用任何持久性措施之前提出記憶、技能、工作和指令改進建議。
+- **批準流程。** 破壞性或外部 actions（匯款、發送出站電子郵件、大規模發布到 Slack）可能需要管理員同意才能觸發。調度擁有佇列。
+
+## 何時使用它 {#when-to-use}
+
+在以下情況下使用 Dispatch：
+
+- 您在工作區中有**兩個或更多**代理本機應用程式，並且希望在一個地方在它們之間進行協調。
+- 您需要**集中式機密**以及每個應用程式的授權和審計跟蹤。
+- 您需要一個**訊息中心**，將 Slack 或 Telegram 路由到正確的域代理。
+- 您想要**預定作業**從多個應用程式中提取資料。
+
+跳過單個應用程式支架 - 直接使用 [Chat template](/docs/template-chat) 或任何域範本。
+
+現場演示：[dispatch.agent-native.com](https://dispatch.agent-native.com)。
+
+## 你將用它做什么 {#what-youll-do}
+
+日常工作中，Dispatch 是管理員和操作人員保持工作區執行的場所：
+
+- **連線 Slack、電子郵件和 Telegram**，以便人們可以從他們已經工作的任何地方向您的代理發送訊息。接線步驟參見[Messaging](/docs/messaging)。
+- **儲存共用機密一次。** API 金鑰、OAuth 權杖和服務憑證位於保管庫中，工作區中的其他應用程式從那裡提取，而不是每個團隊成員都忙於處理自己的 `.env`。
+- **連線提供者一次。**可重複使用的整合存儲安全帳戶元資料
+  和憑證參考，然後授予 Brain、Analytics、Mail 等應用程式
+  在不複製原始機密的情況下分派存取權限。應用程式特定來源
+  設定保留在使用提供程序的應用程式中。
+- **暴露一個 MCP 連線器。**新增
+  `https://dispatch.agent-native.com/_agent-native/mcp`，Claude、ChatGPT，
+  Codex、Cursor 或其他 MCP 主機，然後選取要執行的工作區應用
+  連線器可以從 Dispatch 的 **代理** 頁面進行存取。使用直接應用程式URL
+  僅當該主機應與一個應用隔離時。
+- **管理自動化。**自動化視圖顯示啟用狀態、上次執行
+  下一次執行，以及底層 `jobs/*.md` 調度的最後一個錯誤，讓
+  您無需手動編輯檔案即可啟用或停用作業。
+- **保持公司背景全球化。**將角色、定位、訊息傳遞、公司事實、品牌指南和護欄放入調度資源一次，然後預覽任何應用程式/使用者的有效工作區 -> 應用程式/組織 -> 個人堆堆疊，或從應用程式卡的上下文視圖檢查堆堆疊。
+- **設定重複作業。**“每週一早上 7 點，向分析代理詢問上週的註冊情況，然後通過電子郵件向我發送摘要。”參見[Recurring Jobs](/docs/recurring-jobs)。
+- **審查夢想提案。** Dispatch Dreams 檢查之前的代理執行情況，並為工作區應記住的內容、應清理哪些過時的筆記以及哪些重複的課程應成為 skills 或工作建立支持來源的提案。
+- **在 actions 觸發之前批準出站。** 匯款、群發電子郵件給客戶或發布到公開 Slack 頻道都可以在管理員的後台進行控制。
+- **檢視誰有權存取什么。**每個應用程式授權、請求佇列以及誰何時使用哪個秘密的審核記錄。
+- **將訊息路由到正確的專家。** 有關分析的 Slack 私信 發送至分析代理；一份關於電子郵件的資訊將發送給郵件代理 - 派送選取。
+
+## 架構概覽 {#architecture}
+
+_它的底層工作原理（對於開發人員）。_
+
+- **Orchestrator 代理。** 聊天設定為路由器：它讀取 `AGENTS.md`、`LEARNINGS.md`，並路由到專業子代理或遠端 A2A 代理。
+- **遠端代理註冊表。** A2A 代理清單是工作區執行時條目（不是簽入的範本來源資料夾）：在多應用工作區中，`apps/` 下的同級應用程式會自動發現為 A2A 對等應用程式 — 無需手動註冊。 Dispatch 使用 `call-agent` 操作調用它們。
+- **Vault 架構。** Drizzle 表，用於存儲機密、授權、請求、批準和審核記錄。它們位於 `@agent-native/dispatch` 包 (`packages/dispatch/src/db/schema.ts`) 中，並通過 `templates/dispatch/server/db/index.ts` 重新匯出到範本中 — 沒有範本本機 `server/db/schema.ts`。 Dispatch 的執行時在包中提供，而不是在範本來源中提供（與下面 `@agent-native/dispatch` 擁有 shell、側邊欄和內置頁面的注釋一致）。
+- **Slack / Telegram 外掛。**註冊 webhooks 並將傳入訊息轉發到 Orchestrator 代理的伺服器外掛。
+- **工作區 MCP 資源。** 在資源中的 `mcp-servers/*.json` 下新增 HTTP MCP 伺服器定義，然後將其範圍限定為所有應用或選定的應用授權，就像 skills 和上下文一樣。
+
+```an-schema title="秘密庫架構" summary="Secrets are stored once; grants give a named app access; requests + reviews gate sensitive access; the audit log records who used which secret when. Defined in @agent-native/dispatch (packages/dispatch/src/db/schema.ts)."
+{
+  "entities": [
+    { "id": "secrets", "name": "vault_secrets", "note": "存儲的憑證值", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "owner_email", "type": "text" },
+      { "name": "org_id", "type": "text", "nullable": true },
+      { "name": "name", "type": "text" },
+      { "name": "credential_key", "type": "text" },
+      { "name": "value", "type": "text", "note": "secret value" },
+      { "name": "provider", "type": "text", "nullable": true }
+    ] },
+    { "id": "grants", "name": "vault_grants", "note": "每個應用程式存取權限授予", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "secret_id", "type": "text", "fk": "vault_secrets.id" },
+      { "name": "app_id", "type": "text" },
+      { "name": "granted_by", "type": "text" },
+      { "name": "status", "type": "text" }
+    ] },
+    { "id": "requests", "name": "vault_requests", "note": "存取請求+審核", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "credential_key", "type": "text" },
+      { "name": "app_id", "type": "text" },
+      { "name": "reason", "type": "text", "nullable": true },
+      { "name": "status", "type": "text" },
+      { "name": "reviewed_by", "type": "text", "nullable": true }
+    ] },
+    { "id": "audit", "name": "vault_audit_log", "note": "誰在什么時候使用了哪個秘密", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "secret_id", "type": "text", "fk": "vault_secrets.id", "nullable": true },
+      { "name": "app_id", "type": "text", "nullable": true },
+      { "name": "action", "type": "text" },
+      { "name": "actor", "type": "text" }
+    ] }
+  ],
+  "relations": [
+    { "from": "secrets", "to": "grants", "kind": "1-n", "label": "granted via" },
+    { "from": "secrets", "to": "audit", "kind": "1-n", "label": "use recorded by" }
+  ]
+}
+```
+
+- **MCP 集線器模式。** Dispatch 仍然可以充當工作區的 [MCP hub](/docs/mcp-clients#hub)，因此工作區中的每個其他應用程式都會拉取相同的組織範圍 MCP 伺服器列表。另外，對於 Claude、ChatGPT 和其他應存取多個工作區應用的主機，Dispatch 自己的 `/_agent-native/mcp` 端點是推薦的外部 MCP 連線器。
+
+## 夢想 {#dreams}
+
+夢想是 Dispatch 的特工記憶回顧循環。夢想通行證會檢查現有代理執行、線程偵錯資料、意見回饋、評估和重複的工具故障，然後編寫包含建議更改的報告。這些建議可以針對個人記憶、共用 `LEARNINGS.md`、工作區說明、工作區 skills、工作區知識、工作區代理或重複工作，但共用和工作區級別的更改保持可審查狀態，而不是默默應用。
+
+夢想提案在儲存之前會根據個人記憶索引、現有 `memory/*.md` 檔案和共用 `LEARNINGS.md` 進行檢查。報告中跳過了重複的課程，同時更新了可能陳舊的個人記憶，而不是生成平行筆記。在報告中，Dreams 還按線程、信號型別和標準化引用刪除重複的證據，從使用者更正檢測中剝離注入的上下文，並在原始評估/工具行出現在提案文本中之前將其匯總為人類可讀的專案符號。當傳遞發現信號但故意不建立建議時，報告會包含護欄注釋，解釋哪些證據被壓制。
+
+啟用調度審批策略後，應用共用或團隊範圍的夢想提案會建立待處理的審批請求，而不是立即寫入。建立、更新或刪除全應用工作區資源也會將批準請求排隊。個人記憶建議和僅限選定的資源編輯仍然可以在審核後直接應用。
+
+當您想要回答諸如“代理本週一直犯錯什么？”、“我們應該記住什么？”或“哪些重複的課程值得掌握技能？”等問題時，請使用夢想。入站 Slack、電子郵件、Telegram、WhatsApp 和網路衍生證據被視為不受信任的輸入，因此來自這些來源的提案在影響共用內存之前需要進行審查和出處。工作空間指令提案需要跨越至少兩個線程或兩個來源應用程式的持久證據；僅評估噪音、帳戶設定問題、配額限制和單個應用程式 UI 措辭更正不屬於全域說明。
+
+### 夢想輸入驗證邊界
+
+由於證據是從外部、不受信任的來源（例如聊天紀錄、webhooks 和第三方整合）收集的，因此 Dream 處理器強制執行嚴格的輸入驗證邊界，以防止提示注入和有效負載大小攻擊：
+
+- **字節大小限制：**每條訊息的單個線程有效負載最多為 10KB 的文本內容，如果候選掃描總數超過 100KB，則會被截斷，以防止上下文耗盡。
+- **清理：** 所有文本輸入都經過清理，以去除控制字符、二進制負載和不可列印的 Unicode 範圍。
+- **架構驗證：** 入站偵錯資料和線程歷史紀錄在編譯為 LLM 提示之前根據嚴格的 Zod 架構進行解析。任何未通過模式驗證的候選結構都會立即從處理批次中丟棄。
+- **轉義：**所有使用者提供的文本塊在格式化為提示範本時都會動態轉義，以防止提示注入（例如，嘗試劫持 Dream 循環以編寫任意指令）。
+
+在 Dispatch UI 中，開啟 **Dreams** 以執行手動通行證、審核候選線程、檢查報告，並在應用或拒絕每個提案之前開啟每個提案的審核表。使用 **設定** 編輯循環 cron 計畫、來源範圍、超時/並發限制、候選限制和最小候選閾值；當您希望從這些設定中實現 `jobs/dispatch-dream.md` 重複作業時，請在儲存後使用**確保計畫**。審核表顯示批準行為、目前目標內容、建議內容和來源證據。代理通過 actions 使用相同的工作流程：
+
+- `list-dream-candidates` 查找帶有接地信號的最新線程，例如顯式使用者更正、失敗的執行、工具錯誤、意見回饋、評估失敗和成功的檢查點工作流程。通過 `sourceId: "all"` 或 `sourceIds` 掃描多個線程偵錯來源； `sourceTimeoutMs`、`sourceConcurrency`、`sourceStartStaggerMs`、`threadConcurrency` 和 `threadTimeoutMs` 保持正式環境掃描部分且有限，並且回應包括每個來源的執行狀況。
+- `create-dream-report` 建立報告和待處理提案。多來源報告包括“來源執行狀況”部分，因此在審核期間可以看到部分掃描。反複修正和反複出現的失敗可以成為工作空間資源建議，例如`workspace-instruction`；重複成功的檢查點工作流程可以成為 `workspace-skill` 提案。
+- `get-dream-settings` 和 `set-dream-settings` 讀取並更新重複夢想計畫、來源範圍、超時/並發控制、限制和最小候選閾值。
+- `get-dream`、`preview-dream-proposal`、`apply-dream-proposal` 和 `reject-dream-proposal` 負責審核。
+- 一旦手動報告有用，`ensure-dream-job` 就會建立安全的重複性夢想工作。
+
+Dispatch 範本的本機操作執行程序還公開打包的 Dispatch actions，因此在開發中您可以從 `apps/dispatch` 執行相同的工作流程：
+
+```bash
+pnpm action get-dream-settings
+pnpm action set-dream-settings --enabled true --schedule "0 9 * * 1" --allSources true --limit 8
+pnpm action create-dream-report --allSources true --sourceTimeoutMs 30000 --limit 8
+```
+
+## 腳手架 {#scaffolding}
+
+```bash
+npx @agent-native/core@latest create my-platform
+# 在多選選取器中選取“Dispatch”，以及您想要的任何域應用程式
+```
+
+如果您更喜歡直接命名範本而不是使用選取器：
+
+```bash
+npx @agent-native/core@latest create my-platform --template dispatch
+# add more apps in the same workspace as you go
+```
+
+Dispatch 通常與它協調的應用程式一起建置在工作區中。對於工作區，Dispatch 的共用驗證、資料庫和品牌繼承自工作區核心 - 請參閱 [Multi-App Workspace](/docs/multi-app-workspace)。
+
+沒有有意義的 `--standalone` 調度：沒有任何可協調的控制平面只是一個空收件箱。將其搭建到至少包含一個域應用程式的工作區中，以便它具有可通過 A2A 路由到的代理。 （該標志仍然有效並生成可執行的應用程式，但在您新增同級應用程式之前，協調器沒有可以委托的專家。）
+
+## 首次本機執行 {#first-local-run}
+
+從工作區根目錄：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+開啟開發伺服器列印的Dispatch URL。本機開發使用與正式環境相同的 Better Auth 登入流程。使用電子郵件+密碼建立本機帳戶；開發過程中會跳過電子郵件驗證，密碼僅存儲在本機應用程式資料庫中。預設腳手架中不支持驗證旁路，因為代理、工作區資源、保管庫和共用模型都依賴於真實的使用者工作階段。
+
+您可以在登入後點選“Dispatch UI”。要使用聊天編輯器或執行代理工作，請先連線 LLM 提供者：
+
+1. 開啟**設定**。
+2. 在 **LLM** 中，連線 Builder.io 或新增您自己的提供者金鑰，例如 `ANTHROPIC_API_KEY`。
+3. 返回**概述**並嘗試使用composer。
+
+## 自訂它 {#customize}
+
+Dispatch 是一個像其他範本一樣的完整範本 — 請參閱 [Templates](/docs/cloneable-saas)。要求代理“為 Datadog 新增新的整合”或“將 Slack 私信 從通道 X 路由到分析代理”，它將編輯路由設定、新增 Webhook 處理程序並將其連線起來。
+
+對於特定於工作區的管理螢幕，新增本機 React 路由器頁面和
+將它們註冊到`app/dispatch-extensions.tsx`中。生成的工作空間擁有
+只有額外的分頁和路線； `@agent-native/dispatch` 繼續擁有 shell，
+側邊欄、內置頁面和未來的軟件包更新。
+
+## 下一步是什么
+
+- [**Messaging**](/docs/messaging) — 連線 Slack、電子郵件和 Telegram，以便您可以在任何地方與您的客服人員交談
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — 與多個應用程式一起執行 Dispatch
+- [**A2A Protocol**](/docs/a2a-protocol) — Dispatch 如何委托給專業代理
+- [**MCP Clients — Hub Mode**](/docs/mcp-clients#hub) — 在工作區共用 MCP 伺服器
+- [**Recurring Jobs**](/docs/recurring-jobs) — 調度工作調度執行

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

@@ -0,0 +1,178 @@
+---
+title: "表格"
+description: "代理原生表單生成器 - 通過自然語言和可視化編輯器建立、編輯、發布和路由表單提交。"
+---
+
+# 表格
+
+Forms 是一個代理原生表單建置器。描述您想要的表單，在編輯器中對其進行完善，然後發布一個公開表單，將提交內容存儲在您自己的 SQL 資料庫中。
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px;padding:14px 16px;border-bottom:1.4px solid var(--wf-line)'><strong>Beta 註冊</strong><span class='wf-pill accent'>published</span><div style='flex:1'></div><button>分享</button><button class='primary'>取消發布</button></div><div style='display:flex;gap:8px;padding:12px 16px;border-bottom:1.4px solid var(--wf-line)'><span class='wf-pill accent'>編輯</span><span class='wf-pill'>結果 187</span><span class='wf-pill'>設定</span><span class='wf-pill'>整合</span></div><div style='display:flex;flex-direction:column;gap:12px;padding:30px 78px;overflow:hidden'><h2 style='margin:0'>Beta 註冊</h2><p class='wf-muted' style='margin:0'>預留即將開始的私密 beta 名額。</p><div class='wf-card'><strong>姓名</strong><input value='Ada Lovelace'/></div><div class='wf-card'><strong>工作郵箱</strong><input value='you@company.com'/></div><div class='wf-card'><strong>你的角色</strong><input value='Select...'/></div><div class='wf-card'><strong>團隊規模</strong><input value='Select...'/></div></div></div>"
+}
+```
+
+當您開啟應用程式時，您會看到表單、目前編輯器和實時預覽。代理可以根據提示建立表單、更新欄位標籤和選項、更改驗證以及使用 UI 使用的相同 actions 連線提交目的地。
+
+```an-diagram title="建置、發布、收集" summary="代理和可視化編輯器編輯一個 SQL-backed 表單定義。公開填寫頁面未經驗證，提交內容將通過伺服器端路由到您的目的地。"
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">代理提示詞<br><small class=\"diagram-muted\">\"add an NPS question\"</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\">create-form · update-form</span><small class=\"diagram-muted\">欄位 JSON，設定 JSON</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">forms table<br><small class=\"diagram-muted\">通過 Drizzle 使用 SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">公開填寫頁面<br><small class=\"diagram-muted\">unauthenticated</small></div><div class=\"diagram-box\">responses<br><small class=\"diagram-muted\">+ Slack / webhook / 表格</small></div></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:10px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 你可以用它做什么
+
+- **以對話方式建置表單。**“建立聯系表單”、“新增 NPS 分數問題”、“將電子郵件欄位設為必填”。代理更新表單架構，並從 SQL 支持的狀態更新預覽。
+- **視覺上進行微調。**當您需要直接控制時，可以從建置器 UI 編輯標籤、預留位置、所需狀態、選項和欄位順序。
+- **使用附帶的欄位型別。**開箱即用地支持文本、電子郵件、數字、長文本、選取、多選、核取方塊、單選、日期、評級和比例欄位。
+- **收集回複。**每次提交都存儲在 SQL 中，並帶有每個回複的詳細資訊視圖和用於審核條目的儀表板。
+- **路由提交。**使用內置整合將提交有效負載發送到 webhooks、Slack、Discord 或 Google 表格。
+- **發布公開表單。**分享公開表單 URL 並在提交後顯示感謝訊息。
+
+## 開始使用
+
+現場演示：[forms.agent-native.com](https://forms.agent-native.com)。
+
+1. **根據提示建立表單。**詢問您想要的表單，包括
+   受眾以及提交後會發生什么。
+2. **在編輯器中最佳化。**調整標籤、驗證、選取和順序
+   直接編輯時的視覺生成器速度更快。
+3. **發布並分享。**使用受訪者公開表單 URL，然後觀看
+   結果到達回應視圖。
+4. **連線目的地。**將新提交內容路由至 Slack、Discord、Google
+   工作表、webhooks 或您自己的擴充功能點。
+
+### 有用的提示
+
+- “建立包含角色、團隊規模和優先用例的測試版註冊表單。”
+- “新增必填的 NPS 問題和自由文本後續問題。”
+- “將每個新回複發布到產品 Slack 頻道。”
+- “總結本週提交的內容並按客戶細分進行分組。”
+- “在不丟失路由所需欄位的情況下縮短此表單。”
+
+## 對於開發者
+
+本檔案的其餘部分適用於任何分叉表單範本或擴充功能它的人。
+
+### 快速入門
+
+```bash
+npx @agent-native/core@latest create my-forms --standalone --template forms
+cd my-forms
+pnpm install
+pnpm dev
+```
+
+對於包含 Forms 和其他應用程式的工作區：
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+在工作區設定過程中選取您想要的表單和任何其他範本。
+
+### 主要功能 {#key-features}
+
+**JSON 表單定義。** 欄位位於一個 `fields` JSON 列中，因此代理可以進行外科手術編輯，而無需更改每種欄位型別的架構。
+
+**公開填寫頁面。**受訪者可以提交未經驗證的表單，而私人設定會在資料到達瀏覽器之前被刪除。
+
+**伺服器端目標。** Slack、Discord、Google Sheets 和 Webhook 整合存在於表單設定中並在提交後執行。
+
+### 資料模型
+
+所有資料通過 Drizzle ORM 存儲在 SQL 中。架構：`templates/forms/server/db/schema.ts`。表單攜帶標準 `ownableColumns` 和匹配的框架共用表，因此它們可以插入每使用者/每組織共用模型。
+
+| 表            | 它包含什么                                                                                                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forms`       | 表單定義 - `title`、`description`、唯一 `slug`、`fields`（`FormField` 的 JSON 陣列）、`settings`（JSON `FormSettings`）、`status`（`draft` / `published` / `closed`），以及軟刪除 `deleted_at` |
+| `responses`   | 每行一次提交 - `form_id`、`data` (JSON `{ fieldId: value }`)、`submitted_at`、可選的 `ip` 和 `submitter_email`                                                                                 |
+| `form_shares` | 框架共用每個表單將主體（使用者或組織）對應到角色（檢視者、編輯者、管理員）的表                                                                                                                 |
+
+`fields` 和 `settings` JSON 形狀在 `templates/forms/shared/types.ts`（`FormField`、`FormSettings`）中定義。在任何資料通過 `toPublicFormSettings` 到達公開填充頁面之前，所有者私人設定（例如整合 Webhook URL 和允許的來源）都會被刪除。
+
+```an-schema title="表單資料模型" summary="三張桌子。欄位和整合是表單上的 JSON 列，因此代理的編輯是外科手術補丁，而不是跨表行更改。"
+{
+  "entities": [
+    {
+      "id": "forms",
+      "name": "forms",
+      "note": "A form definition (ownable)",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "title", "type": "string" },
+        { "name": "description", "type": "string", "nullable": true },
+        { "name": "slug", "type": "string", "note": "unique; public URL" },
+        { "name": "fields", "type": "json", "note": "FormField[] — 所有欄位型別" },
+        { "name": "settings", "type": "json", "note": "FormSettings — 整合等" },
+        { "name": "status", "type": "enum", "note": "草稿|發表 |關閉" },
+        { "name": "deleted_at", "type": "datetime", "nullable": true, "note": "soft delete" },
+        { "name": "owner_email", "type": "string" },
+        { "name": "org_id", "type": "id", "nullable": true }
+      ]
+    },
+    {
+      "id": "responses",
+      "name": "responses",
+      "note": "每行一次提交",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "form_id", "type": "id", "fk": "forms.id" },
+        { "name": "data", "type": "json", "note": "{ fieldId: value }" },
+        { "name": "submitted_at", "type": "datetime" },
+        { "name": "ip", "type": "string", "nullable": true },
+        { "name": "submitter_email", "type": "string", "nullable": true }
+      ]
+    },
+    {
+      "id": "form_shares",
+      "name": "form_shares",
+      "note": "框架份額表——每個表格的角色原則",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "form_id", "type": "id", "fk": "forms.id" },
+        { "name": "principal", "type": "string", "note": "user or org" },
+        { "name": "role", "type": "enum", "note": "觀眾|編輯|行政" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "forms", "to": "responses", "kind": "1-n", "label": "has responses" },
+    { "from": "forms", "to": "form_shares", "kind": "1-n", "label": "has share grants" }
+  ]
+}
+```
+
+### 金鑰actions
+
+每個操作都是`templates/forms/actions/`中的一個TypeScript檔案，自動掛載在`POST /_agent-native/actions/:name`：
+
+- `create-form` — 建立一個新表單（標題、描述、欄位、設定）
+- `update-form` — 更新欄位、設定或狀態
+- `get-form` — 通過 id 或 slug 檢索表單
+- `list-forms` — 列出可存取的表單
+- `delete-form` — 軟刪除（設定 `deleted_at`）
+- `restore-form` — 恢復軟刪除的表單
+- `list-responses` — 列出帶有可選過濾器的表單提交內容
+- `export-responses` — 將回應匯出為 CSV 或 JSON
+
+### 自訂
+
+首先向代理詢問發貨行為：
+
+- “為首選聯系方式新增必填單選欄位。”
+- “將每個新提交發布到 Slack。”先通過[Messaging](/docs/messaging)連線Slack。
+- “為我們的 CRM 新增 Webhook 目標。”
+- “建立一個具有 1-10 等級和長文本跟進的客戶意見回饋表。”
+- “將某些表單設為公開，其他表單僅供登入。”
+
+如果您需要檔案上傳、簽名或自訂欄位小部件等新功能，請將它們視為範本擴充功能：將 SQL 形狀、actions、UI 編輯器控件、公開渲染器支持和代理指令新增在一起。請參閱 [Creating Templates](/docs/creating-templates) 了解目前的建置模式。
+
+## 下一步是什么
+
+- [**Templates**](/docs/cloneable-saas) — 克隆自有模型
+- [**Actions**](/docs/actions) — 為建置器提供動力的動作系統
+- [**Messaging**](/docs/messaging) — Slack 和其他提交目的地