@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/template-content.md

@@ -0,0 +1,402 @@
+---
+title: "内容"
+description: "MDX 的开源 Obsidian：编辑本地 Markdown/MDX 文件，生成丰富的交互式自定义块，并使用 AI 代理进行编写。"
+---
+
+# 内容
+
+内容是 MDX 的开源 Obsidian：本地文件友好文档
+代理可以在其中读取、写入、重新组织和发布页面的工作空间
+你。打开文档，要求“重写此段落以使其更加简洁”或“创建一个
+名为第四季度规划的页面，其中包含目标、指标和风险的子页面” - 相同
+无论你自己做还是要求，都会有结果。
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:grid;grid-template-columns:210px 1fr;gap:14px;padding:16px;min-height:500px;box-sizing:border-box'><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Content</strong><span class='wf-pill accent'>Q3 Roadmap</span><span class='wf-pill'>Goals</span><span class='wf-pill'>Metrics</span><span class='wf-pill'>Risks</span><hr/><span class='wf-pill'>Engineering wiki</span><span class='wf-pill'>Reading list</span><span class='wf-pill'>Weekly sync</span></aside><main style='display:flex;flex-direction:column;gap:12px;min-width:0;padding:8px 20px'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Q3 Roadmap</h1><div style='flex:1'></div><button>Share</button><button class='primary'>Publish</button></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:12px;padding:22px'><h2 style='margin:0'>Launch goals</h2><p style='margin:0'>Ship the onboarding flow, reduce setup time, and document owner handoffs.</p><div class='wf-box'>At a glance · owner, window, status</div><div class='wf-box'>Top objectives</div><div class='wf-box'>Workstreams table</div></div></main></div>"
+}
+```
+
+当您打开应用程序时，您将在编辑器旁边看到一个页面树。代理始终知道您正在查看哪个页面以及您选择了哪些文本，因此文档编辑可以保持在当前页面。
+
+```an-diagram title="One document, many editors" summary="You and the agent both write through the same Yjs pipeline. SQL is the canonical store; local files and Notion are optional sync surfaces."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">You type<br><small class=\"diagram-muted\">slash menu, toolbar</small></div><div class=\"diagram-node\">Agent edits<br><small class=\"diagram-muted\">edit-document find/replace</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Yjs CRDT</span><small class=\"diagram-muted\">live, conflict-free merge</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">documents (markdown)<br><small class=\"diagram-muted\">canonical SQL store</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Local .md / .mdx<br><small class=\"diagram-muted\">/local-files</small></div><div class=\"diagram-box\">Notion pages<br><small class=\"diagram-muted\">pull · push</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}"
+}
+```
+
+## 你可以用它做什么
+
+- **编写包含标题、列表、表格、代码块、图像和链接的富文本**。斜线命令（`/`）插入块；选择文本会弹出格式工具栏。
+- **在树中组织页面** — 无限嵌套、拖动重新排序、收藏您经常使用的页面。
+- **搜索所有内容**，通过标题和内容进行全文搜索。
+- **像 Obsidian 一样编辑本地 Markdown/MDX 文件。**使用 `/local-files` 视图
+  将工作区导出到文件，在您自己的工具中编辑它们，预览
+  更改，并将其导入回来。在本地文件模式下，内容直接写入
+  选定的 `.md` 或 `.mdx` 文件。
+- **生成丰富的交互式自定义块。**注册本地React组件，
+  将它们插入为 MDX，并让代理创建或更新组件文件
+  您的文档。
+- **与 Notion 同步。** 将本地文档链接到 Notion 页面，并向任一方向拉取或推送内容。评论也可以双向同步。
+- **实时协作。**多人（和代理）可以同时编辑同一份文档。
+- **与团队成员共享文档**或将其公开 - 默认情况下为私有，具有查看者/编辑者/管理员角色。
+- **向代理询问任何事情**：“重写此段落。” “在顶部添加 TL;DR。” “找到我上周的所有会议记录。” “让这个语气更加正式。”
+
+## 开始使用
+
+现场演示：[content.agent-native.com](https://content.agent-native.com)。
+
+打开应用程序后，单击侧边栏中的 **+ 新页面**，为其指定标题，然后开始编写。要使用代理，请在侧边栏中输入：
+
+- “创建一个名为 Onboarding 的页面，并在其下添加三个子页面。”
+- “重写此段落以使其更加简洁。” （打开页面）
+- “添加有关定价的部分，其中包含三个要点。”
+- “将此文档总结为顶部的 TL;DR。”
+- “从 Notion 中提取最新版本。” （链接 Notion 页面后）
+
+选择文本并按 Cmd+I 以使代理聚焦于预加载的选择 — “使此内容更加有力”，然后对您突出显示的内容进行操作。
+
+## 本地Markdown/MDX文件 {#local-files}
+
+内容可以通过本地文件往返文档，无需克隆或运行
+本地内容应用程序。感觉就像 MDX 的黑曜石：文件保持可检查
+并且可编辑，同时该应用程序为您提供丰富的编辑器、代理 actions、共享和
+自定义块。打开`/local-files`，在浏览器或Agent中选择一个文件夹
+Native Desktop，并将当前文档树导出为Markdown/MDX
+`content/`.
+
+每个导出的文件都包含文档元数据的 frontmatter（`id`、`title`、
+`parentId`、`position`、收藏夹/搜索/可见性标志和 `updatedAt`）加上
+文档正文为Markdown。您可以在普通编辑器中编辑这些文件，
+然后返回 `/local-files` 预览并将更改导入回内容中。
+
+当您想要源代码管理中的内容、想要批处理时，此工作流程非常有用
+使用本地工具编辑文档，或者希望为偏爱文件的团队提供非克隆路径
+作为审查表面。托管应用程序仍然是共享的事实来源，
+评论、权限和实时协作；本地文件夹是显式的
+同步表面。
+
+内容还可以在**本地文件模式**下运行，其中文件是内容的来源
+真相而不是SQL文件。将 `agent-native.json` 添加到仓库，设置
+`mode: "local-files"`，并配置`docs/`、`blog/`等根，
+`content/` 和 `resources/`。然后标准内容编辑器填充其
+来自本地 `.md`/`.mdx` 文件的左侧边栏，并将编辑写回
+通过普通文件actions选择文件。将其用于回购优先文档，
+由 MDX 驱动的博客、资源库或黑曜石风格的个人内容
+组件；当您需要托管协作时切换回数据库模式并且
+SQL 支持的共享。请参阅 [Local File Mode](/docs/local-file-mode)
+独立存储库布局、配置、自定义 MDX 组件、本地
+`extensions/`小部件、安全生产指南。
+
+要将内容本地文件技能安装到现有存储库中：
+
+```bash
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+```
+
+安装程序会复制您的编码代理的 `content` 技能并写入或
+使用 `docs/`、`blog/`、`content/` 的内容根更新 `agent-native.json`
+和`resources/`。当本地内容应用、Agent Native 桌面或受信任
+本地网桥正在运行，代理应使用内容actions，例如
+`list-documents`、`get-document`、`edit-document`、`update-document` 和
+`share-local-file-document` 而不是原始文件系统写入。没有那个本地
+bridge，已安装的技能仍然为代理提供了回购编辑合同
+安全 Markdown/MDX 编辑。
+
+## 对于开发者
+
+本文档的其余部分适用于任何分叉内容模板或扩展它的人。
+
+### 快速启动
+
+使用内容模板搭建新工作区：
+
+```bash
+npx @agent-native/core@latest create my-workspace --standalone --template content
+cd my-workspace
+pnpm install
+pnpm dev
+```
+
+打开 `http://localhost:8083` 并创建您的第一个页面。然后要求客服人员“创建一个名为 Onboarding 的页面，并在其下添加三个子页面”。
+
+### 主要功能 {#key-features}
+
+**嵌套页面。**文档形成一个可拖动的树，其中包含收藏夹、图标、排序和页面级共享。
+
+**丰富的 MDX 编辑器。** Tiptap 支持标题、列表、表格、代码块、图像、链接、斜线命令、选择工具栏和本地 React 组件。
+
+**实时协作。** Yjs 使多个编辑者和代理编辑保持同步，而不会相互干扰。
+
+**搜索和评论。**全文搜索、锚定评论、版本历史记录和恢复流程内置于文档界面中。
+
+**同步表面。**文档可以与 Notion 或本地 Markdown/MDX 文件夹同步，其中 SQL 充当协作缓存/历史记录层。
+
+### 本地文件同步
+
+受保护的 `/local-files` 路由使用浏览器文件系统访问 API，或
+保护Agent Native桌面内的本机文件夹桥，以进行读写
+用户选择的文件夹中的 Markdown/MDX 文件。链接文件夹后
+导入后，选择的文件被视为权限：打开页面读取
+文件，普通编辑器先保存写入文件。 SQL 然后更新为
+现有文档UI、搜索和版本面板的缓存/历史层，不
+作为真相的来源。右上角页面菜单公开本地源路径：
+相对路径始终可用，绝对路径在真正的本地文件中可用
+模式和 Agent Native 桌面，以及在 Finder 中显示可通过
+桌面桥或服务器支持的本地文件模式。
+
+批量同步路由调用：
+
+- `export-content-source` — 读取可访问的文档树并返回
+  确定性 `content/` 文件包。
+- `import-content-source` - 验证文件，创建新的私人文档，
+  更新调用者具有编辑访问权限的文档，保留版本
+  历史记录，并拒绝无效的父周期。
+
+源格式位于 `shared/content-source.ts`。将该文件保留为
+文件名、frontmatter、解析和序列化的单一合约。
+
+本地文件工作区还可以通过
+配置的`components`文件夹。内容开发服务器导入 PascalCase
+从这些文件导出，渲染匹配的 MDX 标签，例如 `<ImpactCounter />`
+在编辑器内，并在本地组件下的斜线菜单中公开它们。
+这是“Obsidian for MDX”层：自定义 MDX 块保留在本地
+工作空间，但编辑器可以渲染它们，代理可以生成或更新
+其来源，无需克隆内容应用程序。最小的工作区组件可以
+是：
+
+```tsx
+// components/ImpactCounter.tsx
+import { useState } from "react";
+
+export function ImpactCounter({
+  label = "points",
+  start = 3,
+}: {
+  label?: string;
+  start?: number;
+}) {
+  const [count, setCount] = useState(start);
+  return (
+    <button type="button" onClick={() => setCount(count + 1)}>
+      Impact: {count} {label}
+    </button>
+  );
+}
+
+export const ImpactCounterInputs = {
+  label: { type: "string", label: "Label", default: "points" },
+  start: { type: "number", label: "Starting count", default: 3 },
+};
+```
+
+在本地MDX中使用它作为`<ImpactCounter />`，或者从编辑器斜杠插入
+本地组件下的菜单。导出输入元数据时，选择
+编辑器中的组件显示一个角落编辑按钮，用于重写 MDX 属性
+在本地文件中。
+
+The browser **Local files** picker can read and write `.md` and `.mdx` files on
+其自己的可执行 React 组件预览需要本地编译器。运行
+本地内容或使用 Agent Native Desktop，以便选定的工作空间路径可以
+已注册到本地内容开发服务器。 Vite 然后导入
+`components/*.tsx`，热重载编辑现有组件文件，并重新加载
+添加或删除文件时的组件注册表。代理可以使用
+`list-local-component-files` 和 `write-local-component-file` 进行检查或
+更新注册的组件文件，同时编辑器从同一源更新。
+
+### 评论
+
+对带有引用文本锚点、回复和解决状态的文档进行线程化评论。由 `document_comments` 桌子和 `app/components/editor/CommentsSidebar.tsx` 提供支持。 Actions：`list-comments`、`add-comment`。 Notion评论可以通过`sync-notion-comments`双向同步。
+
+### 版本历史
+
+每个重要更新都会对 `document_versions` 表中的一行进行快照。 UI 在 `app/components/editor/VersionHistoryPanel.tsx` 中呈现这些。
+
+### 分享和可见性
+
+默认情况下，文档是私有的。您可以更改对 `org` 或 `public` 的可见性，或授予每个用户和每个组织角色（`viewer`、`editor`、`admin`）。该框架的自动安装共享 actions 开箱即用：
+
+- `share-resource --resourceType document --resourceId <id> --principalType user --principalId <email> --role editor`
+- `unshare-resource` / `list-resource-shares` / `set-resource-visibility`
+
+查看`sharing`技能。
+
+### 团队
+
+`/team` 上的专用团队页面（请参阅 `app/routes/_app.team.tsx`）使用框架的 `TeamPage` 组件来创建组织和管理成员。
+
+### 与代理合作
+
+由于代理会看到您当前的屏幕，因此大多数提示不需要您明确引用文档。当您打开一个页面时，“this”表示该页面。
+
+对于小型编辑，代理使用 `edit-document --find ... --replace ...`，因此只有更改的文本流经 Yjs — 您将看到差异应用到位，而不是整个页面重新渲染。对于更大的重写，它使用 `update-document --content ...`。
+
+如果您选择文本并按 Cmd+I（或将焦点放在代理面板上），则选择内容将与您的下一条消息一起作为上下文移动，因此“使此内容更加有力”会针对您突出显示的内容进行操作。
+
+### 数据库和属性
+
+文档可以托管内联数据库 - Notion 样式的表，其中每一行本身就是一个文档。代理可以通过 actions 创建数据库、添加项目、配置列定义以及设置属性值：`create-content-database`、`add-database-item`、`set-document-property`。属性定义（类型、可见性、选项、位置）位于 `document_property_definitions` 中；每行值位于 `document_property_values` 中。
+
+### 额外的actions
+
+除了数据模型中的 CRUD 表面之外，模板还提供了 `export-document` 用于将页面转换为 Markdown 或 HTML、`transcribe-media` 用于将脚本附加到页面，以及 `restore-document-version` 用于回滚到较早的快照。
+
+### 数据模型
+
+九个表，全部在`server/db/schema.ts`中定义：
+
+- **`documents`** — 页面树。列：`id`、`parent_id`、`title`、`content`（降价）、`icon`、`position`、`is_favorite`、`visibility`、`owner_email`、`org_id`、`created_at`、 `updated_at`。
+- **`document_versions`** — 版本历史记录的标题和内容的完整快照。使用`restore-document-version`回滚。
+- **`document_comments`** — 带有 `thread_id`、`parent_id`、`quoted_text`、`resolved` 的线程注释以及用于双向 Notion 同步的可选 `notion_comment_id`。
+- **`document_sync_links`** — 每个 Notion 链接文档一行跟踪远程页面 ID、上次同步时间、冲突状态、内容哈希和错误。
+- **`document_property_definitions`** — 内联数据库的列定义：名称、类型、可见性、选项和位置。
+- **`content_databases`** — 附加到 `document_id` 的内联数据库对象，带有标题和视图配置 JSON。
+- **`content_database_items`** — 内联数据库中的行，每行将 `database_id` 链接到 `document_id`。
+- **`document_property_values`** — 每个文档的属性值（`property_id` → `value_json`）。
+- **`document_shares`** — 通过 `createSharesTable` 创建的每用户和每组织拨款。
+
+```an-schema title="Content data model" summary="Nine tables in server/db/schema.ts. documents is the page tree; the rest hang off it for versions, comments, Notion sync, inline databases, and sharing."
+{
+  "entities": [
+    {
+      "id": "documents",
+      "name": "documents",
+      "note": "The page tree (ownable, markdown body)",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "parent_id", "type": "id", "fk": "documents.id", "nullable": true, "note": "infinite nesting" },
+        { "name": "title", "type": "string" },
+        { "name": "content", "type": "markdown" },
+        { "name": "icon", "type": "string", "nullable": true },
+        { "name": "position", "type": "int", "note": "sibling ordering" },
+        { "name": "is_favorite", "type": "bool" },
+        { "name": "visibility", "type": "enum", "note": "private | org | public" },
+        { "name": "owner_email", "type": "string" },
+        { "name": "org_id", "type": "id", "nullable": true }
+      ]
+    },
+    {
+      "id": "document_versions",
+      "name": "document_versions",
+      "note": "Full title/content snapshots for version history",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "document_id", "type": "id", "fk": "documents.id" },
+        { "name": "title", "type": "string" },
+        { "name": "content", "type": "markdown" }
+      ]
+    },
+    {
+      "id": "document_comments",
+      "name": "document_comments",
+      "note": "Threaded comments with quoted-text anchors",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "document_id", "type": "id", "fk": "documents.id" },
+        { "name": "thread_id", "type": "id" },
+        { "name": "parent_id", "type": "id", "fk": "document_comments.id", "nullable": true },
+        { "name": "quoted_text", "type": "string", "nullable": true },
+        { "name": "resolved", "type": "bool" },
+        { "name": "notion_comment_id", "type": "string", "nullable": true, "note": "bidirectional Notion sync" }
+      ]
+    },
+    {
+      "id": "document_sync_links",
+      "name": "document_sync_links",
+      "note": "One row per Notion-linked document",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "document_id", "type": "id", "fk": "documents.id" },
+        { "name": "notion_page_id", "type": "string" },
+        { "name": "conflict", "type": "bool" },
+        { "name": "content_hash", "type": "string" }
+      ]
+    },
+    {
+      "id": "content_databases",
+      "name": "content_databases",
+      "note": "Inline database objects attached to a document",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "document_id", "type": "id", "fk": "documents.id" },
+        { "name": "title", "type": "string" },
+        { "name": "view_config", "type": "json" }
+      ]
+    },
+    {
+      "id": "content_database_items",
+      "name": "content_database_items",
+      "note": "Rows in an inline database (each row is a document)",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "database_id", "type": "id", "fk": "content_databases.id" },
+        { "name": "document_id", "type": "id", "fk": "documents.id" }
+      ]
+    },
+    {
+      "id": "document_property_definitions",
+      "name": "document_property_definitions",
+      "note": "Column definitions for inline databases",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "name", "type": "string" },
+        { "name": "type", "type": "string" },
+        { "name": "options", "type": "json", "nullable": true },
+        { "name": "position", "type": "int" }
+      ]
+    },
+    {
+      "id": "document_property_values",
+      "name": "document_property_values",
+      "note": "Per-document property values",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "document_id", "type": "id", "fk": "documents.id" },
+        { "name": "property_id", "type": "id", "fk": "document_property_definitions.id" },
+        { "name": "value_json", "type": "json" }
+      ]
+    },
+    {
+      "id": "document_shares",
+      "name": "document_shares",
+      "note": "Per-user and per-org grants (createSharesTable)",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "document_id", "type": "id", "fk": "documents.id" },
+        { "name": "principal", "type": "string" },
+        { "name": "role", "type": "enum", "note": "viewer | editor | admin" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "documents", "to": "documents", "kind": "1-n", "label": "has children" },
+    { "from": "documents", "to": "document_versions", "kind": "1-n", "label": "has snapshots" },
+    { "from": "documents", "to": "document_comments", "kind": "1-n", "label": "has comments" },
+    { "from": "documents", "to": "document_sync_links", "kind": "1-1", "label": "links to Notion" },
+    { "from": "documents", "to": "content_databases", "kind": "1-n", "label": "hosts databases" },
+    { "from": "content_databases", "to": "content_database_items", "kind": "1-n", "label": "has rows" },
+    { "from": "document_property_definitions", "to": "document_property_values", "kind": "1-n", "label": "has values" },
+    { "from": "documents", "to": "document_shares", "kind": "1-n", "label": "has share grants" }
+  ]
+}
+```
+
+内容以降价形式存储。编辑器在内存中与 Tiptap JSON 模型进行相互转换； SQL 行始终是降价的，因此 actions、搜索和 Notion 同步可以在单一规范格式上运行。
+
+所有可拥有的表都包括通过 `ownableColumns()` 的 `owner_email` 和 `org_id`，因此从创建那一刻起，每一行的范围都仅限于登录用户（以及可选的活动组织）。
+
+### 自定义它
+
+改变行为时要注意的四个地方：
+
+- **`actions/`** — 代理或 UI 可以执行的每个操作。使用`defineAction`添加一个像`actions/publish-to-wordpress.ts`这样的新文件，双方都可以免费获得。现有actions主要：`create-document.ts`、`edit-document.ts`、`update-document.ts`、`delete-document.ts`、`list-documents.ts`、`search-documents.ts`、`get-document.ts`、`pull-notion-page.ts`、`push-notion-page.ts`、`add-comment.ts`、`view-screen.ts`、 `navigate.ts`。
+- **`app/routes/`** — 页面表面。 `_app.tsx` 是无路径布局，保持侧边栏和代理面板安装； `_app._index.tsx`为落地视图； `_app.page.$id.tsx`是编辑器路线； `_app.team.tsx`是团队设置页面。
+- **`app/components/editor/`** — Tiptap 编辑器。在`extensions/`下添加新的节点类型，并在`DocumentEditor.tsx`中注册。气泡工具栏、斜杠菜单和悬停预览都是您可以编辑的组件文件。
+- **`.agents/skills/`** — 代理在行动前阅读的指南。如果您添加新功能（例如，CMS 发布管道），请将 `SKILL.md` 放入新技能文件夹中，以便代理正确使用它。现有skills：`document-editing`、`notion-integration`、`real-time-sync`、`delegate-to-agent`、`storing-data`、`self-modifying-code`、`security`、`frontend-design`、`create-skill`、`capture-learnings`。
+- **`AGENTS.md`** — 带有操作备忘单和常见任务表的顶级代理指南。每当您添加主要功能时更新它，以便代理无需探索即可发现它。
+- **`server/db/schema.ts`** — 数据模型。此处添加列或表。内容模板没有 `db:push` 脚本；它依赖于在启动时运行的严格附加迁移。编辑 `server/db/schema.ts`，编写匹配的附加迁移，并在下次应用启动时应用更改 - 架构更新绝不能删除、重命名或破坏性地更改现有表或列（有关准则，请参阅 [Database](/docs/database#migrations)）。
+- **`shared/notion-markdown.ts`** — 降价到 Notion 块的转换。如果您添加需要通过 Notion 往返的新块类型，请扩展此功能。
+
+代理可以自行进行所有这些更改 - 要求它“向文档添加标签列并将其公开在侧边栏中”，它将更新架构、迁移、连接 UI 并编写操作。

package/docs/content/locales/zh-CN/template-design.md

@@ -0,0 +1,173 @@
+---
+title: "设计"
+description: "代理原生 HTML 原型工作室 — 使用代理生成、完善、预览和导出交互式 Alpine/Tailwind 设计。"
+---
+
+# 设计
+
+Design 是一家代理原生 HTML 原型工作室。该代理不是分层绘图画布，而是生成完整的独立 Alpine/Tailwind HTML 原型，将它们渲染在 iframe 中，并允许您通过提示和调整控件来优化结果。
+
+```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'>Product launch page</h1><span class='wf-pill accent'>Desktop</span><span class='wf-pill'>Tablet</span><span class='wf-pill'>Mobile</span><div style='flex:1'></div><button>Preview</button><button class='primary'>Export code</button></div><div class='wf-card' style='flex:1;display:grid;grid-template-rows:auto 1fr auto;gap:12px'><div style='display:flex;gap:8px'><span class='wf-pill accent'>Hero</span><span class='wf-pill'>Pricing</span><span class='wf-pill'>FAQ</span></div><div class='wf-box' style='display:flex;align-items:center;justify-content:center;min-height:230px'><strong>Generated HTML prototype</strong></div><div class='wf-card' style='display:flex;align-items:center;gap:10px'><span class='wf-muted'>Make the hero denser and the CTA clearer.</span><div style='flex:1'></div><button class='primary'>Apply revision</button></div></div></div>"
+}
+```
+
+当您打开应用程序时，生成的原型位于工作区的中心，预览模式、提示修订和导出控件触手可及。代理生产的所有东西都是真实的 HTML，您可以精炼、导出或移交。
+
+```an-diagram title="One artifact, no translation" summary="The agent generates standalone Alpine/Tailwind HTML; the iframe, the editable source, and every export all read the same files. A linked design system feeds tokens into each pass."
+{
+  "html": "<div class=\"diagram-design\"><div class=\"diagram-col\"><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">describe screen / page</small></div><div class=\"diagram-pill\">Design system</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill accent\">Agent generate</span><small class=\"diagram-muted\">standalone HTML / JSX files</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>iframe preview<br><small class=\"diagram-muted\">tweak knobs · Cmd+I refine</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill ok\">Export</span><small class=\"diagram-muted\">HTML · ZIP · PDF · handoff</small></div></div>",
+  "css": ".diagram-design{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-design .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:flex-start}.diagram-design .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-design .diagram-arrow{font-size:20px;line-height:1}.diagram-design .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 何时采摘
+
+- **您想要一个精美的登陆页面概念、产品 UI 方向或品牌探索**，可以让工具保持真实的 HTML — 而不是分层的画布。
+- **您需要一个可用的交互式原型**，具有 Alpine interactions 和 Tailwind 样式，而不是静态模型。
+- **您想要快速比较方向**，生成一些变体，选择最强的，然后不断完善。
+- **您想要自己拥有的设计输出** — 导出 HTML、ZIP 或 PDF，或将原型交给编码工具。
+
+## 你可以用它做什么
+
+- **生成完整的原型。**描述您需要的屏幕或页面，代理将创建一个具有 Tailwind 样式和 Alpine interactions 的工作 HTML 文档。
+- **比较变体。**从多个方向开始，选择最强的一个，然后继续完善。
+- **视觉上的调整。**使用内置的调整控件进行常见更改，或向代理询问副本、布局、颜色、间距和交互更新。
+- **应用设计系统。**保存并重用设计系统首选项，以便生成的作品更贴近您的品牌。
+- **导入参考。**引入现有的 HTML 或参考材料作为新设计阶段的上下文。
+- **导出真实文件。**从生成的原型中导出 HTML、ZIP 或 PDF。
+
+## 开始使用
+
+现场演示：[design.agent-native.com](https://design.agent-native.com)。
+
+1. **描述工件。**询问屏幕、流程、登陆页面或视觉效果
+   你想要的方向。包括受众、基调和任何产品限制。
+2. **比较方向。**生成一些变体，选择最强的一个，然后
+   不断完善而不是重新开始。
+3. **调整细节。**使用调整控件进行常见的视觉变化，或询问
+   布局、复制、响应式和交互更改的代理。
+4. **有用时导出。**原型完成后下载 HTML、ZIP 或 PDF
+   已准备好交给其他工具或队友。
+
+### 有用的提示
+
+- “为技术分析产品创建三个着陆页方向。”
+- “让此仪表板更密集，更易于运营团队扫描。”
+- “应用我们保存的设计系统并简化移动布局。”
+- “选择最终变体后，将此原型导出为 ZIP。”
+- “在不改变品牌颜色的情况下，将这个 HTML 变成更强大的定价页面。”
+
+## 对于开发者
+
+本文档的其余部分适用于任何派生设计模板或扩展它的人。
+
+### 快速启动
+
+```bash
+npx @agent-native/core@latest create my-design --standalone --template design
+cd my-design
+pnpm install
+pnpm dev
+```
+
+### 数据模型
+
+所有数据通过 Drizzle ORM 存储在 SQL 中。架构：`templates/design/server/db/schema.ts`。设计和设计系统采用标准 `ownableColumns` 和匹配的框架共享表，因此它们可以插入每用户/每组织共享模型。
+
+| 表                                       | 它包含什么                                                                                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `designs`                                | 一个设计项目 - `title`、`description`、`project_type` (`prototype` / `other`)、`data` JSON Blob 和可选的 `design_system_id` 链接 |
+| `design_files`                           | 属于某个设计的各个文件（`filename`、`content`、`file_type` 默认为 `html`）                                                       |
+| `design_versions`                        | 具有可选 `label` 的设计的时间点 `snapshot`，用于历史记录和回滚                                                                   |
+| `design_systems`                         | 可重复使用的品牌标记 - `data`（颜色/版式/间距）、`assets`、`custom_instructions` 和 `is_default` 标志                            |
+| `design_shares` / `design_system_shares` | 框架共享将主体（用户或组织）映射到角色（查看者、编辑者、管理员）的表                                                             |
+
+```an-schema title="Design data model" summary="A design owns its files and versioned snapshots, and optionally links a reusable design system. Both designs and systems are ownable, each with a framework shares table."
+{
+  "entities": [
+    { "id": "designs", "name": "designs", "note": "A design project (ownable)", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "title", "type": "text" },
+      { "name": "description", "type": "text", "nullable": true },
+      { "name": "project_type", "type": "text", "note": "prototype / other" },
+      { "name": "data", "type": "json", "note": "starts as {}" },
+      { "name": "design_system_id", "type": "id", "fk": "design_systems.id", "nullable": true }
+    ] },
+    { "id": "files", "name": "design_files", "note": "Files in a design", "fields": [
+      { "name": "design_id", "type": "id", "fk": "designs.id" },
+      { "name": "filename", "type": "text" },
+      { "name": "content", "type": "text" },
+      { "name": "file_type", "type": "text", "note": "defaults to html" }
+    ] },
+    { "id": "versions", "name": "design_versions", "note": "History / rollback", "fields": [
+      { "name": "design_id", "type": "id", "fk": "designs.id" },
+      { "name": "snapshot", "type": "json" },
+      { "name": "label", "type": "text", "nullable": true }
+    ] },
+    { "id": "systems", "name": "design_systems", "note": "Reusable brand tokens (ownable)", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "data", "type": "json", "note": "colors / typography / spacing" },
+      { "name": "assets", "type": "json", "nullable": true },
+      { "name": "custom_instructions", "type": "text", "nullable": true },
+      { "name": "is_default", "type": "boolean" }
+    ] },
+    { "id": "design_shares", "name": "design_shares", "note": "Framework shares table", "fields": [
+      { "name": "design_id", "type": "id", "fk": "designs.id" },
+      { "name": "role", "type": "text", "note": "viewer / editor / admin" }
+    ] },
+    { "id": "system_shares", "name": "design_system_shares", "note": "Framework shares table", "fields": [
+      { "name": "design_system_id", "type": "id", "fk": "design_systems.id" },
+      { "name": "role", "type": "text", "note": "viewer / editor / admin" }
+    ] }
+  ],
+  "relations": [
+    { "from": "designs", "to": "files", "kind": "1-n" },
+    { "from": "designs", "to": "versions", "kind": "1-n" },
+    { "from": "systems", "to": "designs", "kind": "1-n", "label": "applied to" },
+    { "from": "designs", "to": "design_shares", "kind": "1-n" },
+    { "from": "systems", "to": "system_shares", "kind": "1-n" }
+  ]
+}
+```
+
+设计项目在包含内容之前是一个外壳：`create-design` 生成一个空行 (`data: "{}"`)，然后 `generate-design` 写入实际的独立 HTML/JSX 文件。生成的工件、可编辑源以及每个导出都来自同一个 HTML，因此没有单独的“AI 模型”格式需要翻译。链接设计系统提供代币和 `custom_instructions`，代理在每一代传递中都会兑现这些代币和 `custom_instructions`。
+
+UI 中的路由位于 `templates/design/app/routes/` 下：`_index.tsx`（列表）、`design.$id.tsx`（编辑）、`present.$id.tsx`（演示）、`design-systems.tsx` 和 `design-systems_.setup.tsx`、`templates.tsx`、`examples.tsx`，以及 `settings.tsx` 和`team.tsx`。
+
+### 密钥actions
+
+每个代理可调用操作都是 `templates/design/actions/` 中的 TypeScript 文件，自动安装在 `POST /_agent-native/actions/:name` 上，并可作为 `pnpm action <name>` 从 CLI 运行。分组：
+
+- **设计** - `create-design`（空壳）、`generate-design`（写入生成的 HTML/JSX 内容）、`update-design`、`get-design`、`list-designs`、`duplicate-design`、`delete-design` 和 `apply-tweaks` 用于持久保存实时调整旋钮值（强调色、密度等）。
+- **文件** - `create-file`、`update-file`、`list-files`、`delete-file` 用于设计项目内的文件。
+- **设计系统** - `create-design-system`、`update-design-system`、`get-design-system`、`list-design-systems`、`delete-design-system`、`set-default-design-system` 和 `analyze-brand-assets` 用于在分析之前收集品牌数据。
+- **导入** - `import-code`、`import-figma`、`import-github`、`import-from-url`、`import-document` (DOCX/PPTX/PDF/XLSX) 和 `import-design-project` 将设计系统从现有项目中提升出来。
+- **导出和移交** - `export-html`、`export-pdf`、`export-svg`、`export-zip` 和 `export-coding-handoff` 将设计转变为编码工具移交。
+- **上下文和导航** - `view-screen`（当前设计、打开的文件、视图、待决问题或变体网格）、`get-design-snapshot`（外部代理继续的当前状态）和 `navigate`。
+
+### 与代理合作
+
+代理始终知道您打开了什么。当前设计、打开的文件、活动视图以及任何待处理的问题或变体网格均由 `view-screen` 返回并注入到每条消息中，因此您可以说“使此更密集”或“导出此变体”，而无需命名设计。
+
+因为设计只是独立的 HTML/JSX 文件，所以代理编辑 iframe 渲染和每个导出来自的相同源 - 没有单独的“AI 模型”格式需要翻译。链接设计系统提供代币和代理在每一代通行证上兑现的 `custom_instructions`。在预览中选择文本或区域，然后按 Cmd+I 将代理集中在该部分上。
+
+### 自定义它
+
+设计是一个完整的、可克隆的模板。一些实用的扩展想法：
+
+- “使用我们的令牌和示例组件添加可重用的电子商务设计系统。”
+- “添加一个导出步骤，将 ZIP 上传到我们的内部审核系统。”
+- “让我粘贴现有的登陆页面 HTML 并向代理询问三个更强的版本。”
+- “为产品页面、仪表板和入门屏幕简介添加已保存的提示库。”
+- “添加自定义 PDF 导出预设以供利益相关者审核。”
+
+代理根据需要编辑路线、组件、actions 和 SQL 支持的模型。请参阅 [Templates](/docs/cloneable-saas) 了解完整克隆、自定义、部署流程，如果这是您的第一个代理本机模板，请参阅 [Getting Started](/docs/getting-started)。
+
+## 下一步是什么
+
+- [**Templates**](/docs/cloneable-saas) — 克隆自有模型
+- [**Context Awareness**](/docs/context-awareness) — 代理如何知道用户正在查看的内容
+- [**Creating Templates**](/docs/creating-templates) — 代理原生模板的当前构建模式