@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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 Templates</h1><p class='wf-muted' style='margin:0'>Adoption and engagement across the last 12 weeks.</p><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card'><small class='wf-muted'>Weekly active users</small><br/><strong>24,318</strong><br/><span class='wf-pill accent'>+12.4%</span></div><div class='wf-card'><small class='wf-muted'>New signups</small><br/><strong>1,842</strong><br/><span class='wf-pill accent'>+8.7%</span></div><div class='wf-card'><small class='wf-muted'>Revenue 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>Weekly active users</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>Revenue over time</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>Signups by source</strong><br/><small class='wf-muted'>Lower chart begins below the main charts.</small></div></div>"
+}
+```
+
+它是 Amplitude、Mixpanel 和 Looker 的开源替代品——适合想要拥有代码、查询和数据的团队。
+
+```an-diagram title="Question to chart" summary="The agent consults the data dictionary, writes SQL, validates it against the warehouse, then renders a chart or saves a panel."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">Plain-English<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>Writes SQL</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">Dry-run validate</div><small class=\"diagram-muted\">BigQuery / source</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Chart, table, or<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="Analytics data model" 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": "Explorer and SQL dashboards",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "kind", "type": "text", "note": "\"explorer\" or \"sql\"" },
+        { "name": "config", "type": "text", "note": "JSON matching SqlDashboardConfig" }
+      ]
+    },
+    {
+      "id": "dashboard_views",
+      "name": "dashboard_views",
+      "note": "Saved filter presets per dashboard",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "dashboard_id", "type": "text", "fk": "dashboards.id" }
+      ]
+    },
+    {
+      "id": "analyses",
+      "name": "analyses",
+      "note": "Re-runnable ad-hoc investigations",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "question", "type": "text" },
+        { "name": "instructions", "type": "text", "note": "Re-run steps" },
+        { "name": "dataSources", "type": "text", "note": "Sources touched" },
+        { "name": "resultMarkdown", "type": "text" },
+        { "name": "resultData", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "bigquery_cache",
+      "name": "bigquery_cache",
+      "note": "Result cache keyed by SQL hash",
+      "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-CN/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'>Launch brand</h1><span class='wf-pill accent'>Blog heroes</span><span class='wf-pill'>Product shots</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>Create brand media</strong><div class='wf-box'>Three homepage hero options using the approved logo and product references.</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'>Web export</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'>Hero A</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Reference set</span></div><div class='wf-card' style='display:flex;align-items:end;min-height:130px'><span class='wf-pill'>Logo safe</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="Generate, review, reuse" summary="References and prompts feed a generate-and-choose session; chosen assets land in a library and flow out to other apps via the picker or A2A."
+{
+  "html": "<div class=\"diagram-assets\"><div class=\"diagram-col\"><div class=\"diagram-node\">References<br><small class=\"diagram-muted\">logos, product shots, style</small></div><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">chat or Generate controls</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\">Generation session</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\">chosen, brand-consistent 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 App</small></div><div class=\"diagram-node\">A2A<br><small class=\"diagram-muted\">Slides · Design · Content</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 Composer 和库生成控件使用 `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="Assets data model" 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": "Top-level ownable container", "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": "Framework shares table", "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 groupings", "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": "Nestable folders", "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": "Saved generation recipes", "fields": [
+      { "name": "media_type", "type": "text" },
+      { "name": "prompt_template", "type": "text" },
+      { "name": "model", "type": "text" }
+    ] },
+    { "id": "sessions", "name": "image_generation_sessions", "note": "Iterative generate-and-choose", "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": "Candidate assets in a session", "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": "The asset record", "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": "Generation audit log", "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
+# Easiest hosted install: exported skill instructions plus MCP connector.
+npx @agent-native/core@latest skills add assets
+
+# Vercel/open Skills CLI install: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Hosted install: URL-only MCP connector, no shared secrets in skill files.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Local editable launch.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported Assets bundle with the open skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Install from the generated Claude Code marketplace adapter.
+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) — 库级访问控制