@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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>What should we do next?</strong><div class='wf-box'>Ask Analytics for this week's signups and draft a Slack update.</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>Create app</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 DM needs reply</div><div class='wf-box'>A2A task completed</div><div class='wf-box'>Approval required</div></div></div>"
+}
+```
+
+如果您正在运行带有许多应用程序的 [multi-app workspace](/docs/multi-app-workspace)，Dispatch 就是粘合剂。
+
+```an-diagram title="Orchestrate, don't specialize" summary="Messages from every channel land in one inbox; the orchestrator triages and delegates domain work to the right specialist app over A2A — secrets, resources, and approvals stay central."
+{
+  "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 requests</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\">central inbox · triage · route</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">Mail agent</div><div class=\"diagram-node\">Analytics agent</div><div class=\"diagram-node\">Brain · Slides &hellip;</div></div></div><div class=\"diagram-shared\"><span class=\"diagram-pill\">Secrets vault</span><span class=\"diagram-pill\">Workspace resources</span><span class=\"diagram-pill warn\">Approvals</span><span class=\"diagram-pill\">Scheduled jobs</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 DM、电报消息、电子邮件通知、来自其他代理的 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 DM 发送至分析代理；一份关于电子邮件的信息将发送给邮件代理 - 派送选择。
+
+## 架构概览 {#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="Secrets vault schema" 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": "Stored credential values", "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": "Per-app access grant", "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": "Access request + review", "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": "Who used which secret when", "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
+# pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
+```
+
+如果您更喜欢直接命名模板而不是使用选择器：
+
+```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 DM 从通道 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-CN/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 signup</strong><span class='wf-pill accent'>published</span><div style='flex:1'></div><button>Share</button><button class='primary'>Unpublish</button></div><div style='display:flex;gap:8px;padding:12px 16px;border-bottom:1.4px solid var(--wf-line)'><span class='wf-pill accent'>Edit</span><span class='wf-pill'>Results 187</span><span class='wf-pill'>Settings</span><span class='wf-pill'>Integrations</span></div><div style='display:flex;flex-direction:column;gap:12px;padding:30px 78px;overflow:hidden'><h2 style='margin:0'>Beta signup</h2><p class='wf-muted' style='margin:0'>Reserve a spot in the upcoming private beta cohort.</p><div class='wf-card'><strong>Full name</strong><input value='Ada Lovelace'/></div><div class='wf-card'><strong>Work email</strong><input value='you@company.com'/></div><div class='wf-card'><strong>Your role</strong><input value='Select...'/></div><div class='wf-card'><strong>Team size</strong><input value='Select...'/></div></div></div>"
+}
+```
+
+当您打开应用程序时，您会看到表单、当前编辑器和实时预览。代理可以根据提示创建表单、更新字段标签和选项、更改验证以及使用 UI 使用的相同 actions 连接提交目的地。
+
+```an-diagram title="Build, publish, collect" summary="The agent and the visual editor edit one SQL-backed form definition. The public fill page is unauthenticated, and submissions route server-side to your destinations."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">Agent prompt<br><small class=\"diagram-muted\">\"add an NPS question\"</small></div><div class=\"diagram-node\">Visual editor<br><small class=\"diagram-muted\">labels, validation, order</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\">fields JSON, settings 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\">SQL via Drizzle</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Public fill page<br><small class=\"diagram-muted\">unauthenticated</small></div><div class=\"diagram-box\">responses<br><small class=\"diagram-muted\">+ Slack / webhook / Sheets</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="Forms data model" summary="Three tables. Fields and integrations are JSON columns on forms, so the agent's edits are surgical patches rather than cross-table row changes."
+{
+  "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[] — all field types" },
+        { "name": "settings", "type": "json", "note": "FormSettings — integrations, etc." },
+        { "name": "status", "type": "enum", "note": "draft | published | closed" },
+        { "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": "One submission per row",
+      "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": "Framework shares table — principals to roles per form",
+      "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": "viewer | editor | admin" }
+      ]
+    }
+  ],
+  "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 和其他提交目的地