@agent-native/core 0.102.2 → 0.103.0

package/docs/content/locales/zh-CN/local-file-mode.mdx

@@ -1,523 +1,65 @@
 ---
-title: "本地文件模式"
-description: "使用本地 Markdown、MDX 和其他存储库文件作为事实来源运行代理本机应用 - 包括带有自定义组件的黑曜石风格 MDX 文档。"
+title: "本地文件夹源"
+description: "将 Markdown 和 MDX 文件夹连接到由数据库支持的 Content 空间。"
 ---
 
-# 本地文件模式
+# 本地文件夹源
 
-本地文件模式允许代理本机应用程序附加其正常的 UI 和操作界面
-直接到存储库或工作区中的文件。该应用程序仍然感觉像是托管的
-产品，但其列表视图、编辑器和代理工具可读写本地文件
-而不是 SQL 支持的应用记录。
+Content 现在只有一个数据模型：每个页面都存储在 SQL 中，属于一个**空间**，并且
+是该空间系统 **Files** 数据库的条目。本地文件夹是连接到 Files 的数据源，而不是
+另一种应用模式。`AGENT_NATIVE_MODE` 开关已被移除。
 
-第一个实现是在内容模板中：左侧边栏是
-从本地 `.md` 和 `.mdx` 文件填充，选择一个页面打开标准
-内容编辑器，并保存写回到所选文件。相同的文件可以
-也可以由 Codex、Claude 代码、Agent-Native 侧边栏代理或普通编辑
-编辑器。
+每位用户有个人空间，每个可访问的组织有组织空间；个人 **Workspaces** 目录决定
+应用中显示哪些空间。Files 是普通的 Content 数据库，因此它的属性、筛选、排序、
+分组和保存视图也可以呈现为侧边栏。
 
-对于内容，这使得该产品感觉像是 MDX 的开源黑曜石：
-您的文档以文件形式存在，而应用程序添加了可视化编辑器、代理 actions，
-可共享的副本，以及丰富的交互式 MDX 组件。
+## 连接文件夹
 
-当您想要回购优先的工作流程时，请使用本地文件模式：
+通过浏览器或 Agent Native Desktop 选择文件夹，将它连接到现有空间，或创建一个
+由该文件夹支持的私有空间。SQL 只保存不透明的连接 ID、相对路径、哈希和数据源
+元数据；不保存绝对路径、浏览器句柄或原始文件正文。
 
-- `docs/*.mdx` 的文档存储库
-- `blog/*.mdx` 的博客
-- `resources/*.md` 中的定位、消息传递或团队笔记等资源
-- 个人黑曜石风格的知识库，具有更丰富的MDX编辑器
-- 需要从本地 React 代码生成的交互式自定义 MDX 块的文档
-- 应用程序工件应该易于编码代理检查和修补
+可选策略为 `database_primary`、`source_primary` 和
+`reviewed_bidirectional`。同步会把文件实体化为普通 SQL 页面。如果文件与 Content
+页面同时更改，系统会创建待审核变更，而不会悄悄覆盖任一方。断开连接会保留页面
+和本地文件。
 
-当您需要托管协作应用程序体验时，请使用数据库模式：
-多用户共享、SQL 支持的权限、评论、版本历史记录和
-没有本地文件系统访问权限的生产托管。
-
-## 心智模型
-
-有两种真相来源模式：
-
-| 模式         | 事实来源                          | 最适合                                                  |
-| ------------ | --------------------------------- | ------------------------------------------------------- |
-| 数据库模式   | SQL 行至 Drizzle                  | 托管应用、协作、共享、评论、版本历史记录                |
-| 本地文件模式 | `agent-native.json`声明的Repo文件 | 本地/开发工作流程、Git 审核、编码代理编辑、文件本机内容 |
-
-UI 和特工 actions 在两种模式下都应保持相同的形状。内容
-编辑器仍然编辑文档；区别在于这些文档是否解析
-到 SQL 行或本地文件。
-
-<Diagram id="doc-block-bob9ei" title={"相同的行为，两个事实来源"} summary={"UI 和代理在两种模式下调用相同的操作。操作层决定每个调用是否解析为 SQL 行或存储库文件。"}>
-
-```html
-<div class="diagram-mode">
-  <div class="diagram-col entry">
-    <div class="diagram-node">内容 UI</div>
-    <div class="diagram-node">
-      代理 + actions<br /><small class="diagram-muted"
-        >list/get/update-document</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-  <div class="diagram-row resolve">
-    <div class="diagram-panel" data-rough>
-      <span class="diagram-pill accent">数据库模式</span
-      ><small class="diagram-muted">SQL rows via Drizzle</small
-      ><small class="diagram-muted">托管 · 分享 · 评论 · 历史</small>
-    </div>
-    <div class="diagram-panel" data-rough>
-      <span class="diagram-pill ok">Local File Mode</span
-      ><small class="diagram-muted">repo files via agent-native.json</small
-      ><small class="diagram-muted">Git 评审 · 编码代理编辑</small>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-mode {
-  display: flex;
-  align-items: center;
-  gap: 14px;
-  flex-wrap: wrap;
-}
-.diagram-mode .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-mode .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-.diagram-mode .resolve {
-  display: flex;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-mode .diagram-panel {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 12px 14px;
-}
-```
-
-</Diagram>
-
-## 示例存储库
-
-内容工作区可以像这样小：
-
-<FileTree
-  id="doc-block-1mk9qsi"
-  title={"一个 Content workspace repo"}
-  entries={[
-    {
-      path: "agent-native.json",
-      note: "声明哪些文件夹是内容根以及它们的类型",
-    },
-    {
-      path: "docs/",
-      note: "内容根：在侧边栏中显示为页面",
-    },
-    {
-      path: "docs/getting-started.mdx",
-    },
-    {
-      path: "docs/guides/custom-components.mdx",
-    },
-    {
-      path: "blog/",
-      note: "内容根",
-    },
-    {
-      path: "blog/launch-post.mdx",
-    },
-    {
-      path: "resources/",
-      note: "内容根",
-    },
-    {
-      path: "resources/messaging/positioning.md",
-    },
-    {
-      path: "components/",
-      note: "不是内容根：MDX 可导入的 preview 组件库",
-    },
-    {
-      path: "components/FrameworkTabs.tsx",
-    },
-    {
-      path: "components/Callout.tsx",
-    },
-    {
-      path: "extensions/",
-      note: "不是内容根：本地 extension 库（沙盒 widgets）",
-    },
-    {
-      path: "extensions/doc-status/extension.json",
-    },
-    {
-      path: "extensions/doc-status/index.html",
-    },
-  ]}
-/>
-
-在本地文件模式下，内容侧边栏显示 `docs/`、`blog/` 和
-`resources/` 树为页面。选择 `docs/getting-started.mdx` 打开
-标准内容编辑器中的文件；在 UI 中编辑写回
-`docs/getting-started.mdx`.
-
-`components/` 不是内容根。 MDX
-文件可以导入或引用。编辑器可以渲染简单的本地MDX组件
-无需您克隆或分叉整个内容应用。
-
-`extensions/` 也不是内容根。它是一个本地扩展库：
-小型沙盒小部件，可以在应用程序槽中呈现，同时其源保留在
-存储库。
-
-## 将内容安装到存储库中
-
-对于现有文档、博客或 MDX 工作区，安装内容本地文件
-技能：
+## 从仓库启动
 
 ```bash
-npx @agent-native/core@latest skills add content --mode local-files --scope project
+npx @agent-native/core@latest content .
 ```
 
-这会将 `content` 技能复制到存储库的代理技能文件夹中并写入
-或使用内容默认值更新 `agent-native.json`：
-
-- 工作区级别的 `mode: "local-files"`
-- `apps.content.mode: "local-files"`
-- `docs/`、`blog/`、`content/` 和 `resources/` 的内容根
-- `components/` 用于本地 MDX 组件
-- `extensions/` 用于本地扩展小部件
-
-安装的技能告诉编码代理使用内容actions
-(`list-documents`, `get-document`, `edit-document`, `update-document`,
-`share-local-file-document` 和组件文件 actions）（当本地内容应用时）
-或 Agent Native 桌面桥公开它们。如果没有桥在运行，则该技能
-退回到安全的直接存储库编辑，同时保留 frontmatter、导入、JSX，
-和未知的 MDX。
+此命令启动正常的数据库版 Content，将文件夹注册为数据源并打开连接界面；它不会
+设置模式环境变量。
 
 ## 配置
 
-将 `agent-native.json` 添加到存储库或工作区根目录：
-
 ```json
 {
   "version": 1,
   "apps": {
     "content": {
-      "mode": "local-files",
       "roots": [
         {
           "name": "Docs",
           "path": "docs",
           "kind": "docs",
-          "extensions": [".md", ".mdx"]
-        },
-        {
-          "name": "Blog",
-          "path": "blog",
-          "kind": "blog",
-          "extensions": [".md", ".mdx"]
-        },
-        {
-          "name": "Resources",
-          "path": "resources",
-          "kind": "resources",
-          "extensions": [".md", ".mdx"]
+          "extensions": [".md", ".mdx"],
+          "source": {
+            "type": "local-folder",
+            "connectionId": "local-folder:<opaque-id>",
+            "truthPolicy": "source_primary"
+          }
         }
       ],
       "components": "components",
-      "extensions": "extensions",
-      "hide": ["**/_*.md", "**/_*.mdx"]
+      "extensions": "extensions"
     }
   }
 }
 ```
 
-您还可以使用 `AGENT_NATIVE_MODE=local-files` 或启用本地文件
-`AGENT_NATIVE_DATA_MODE=local-files`；清单是首选，因为它
-在存储库本身中记录文件夹合同。
-
-## 内容文件格式
-
-内容为 Markdown 和 MDX。 Frontmatter 保存页面元数据，正文为
-可编辑文档：
-
-```mdx
----
-title: "开始使用"
-icon: "sparkles"
-isFavorite: true
-updatedAt: "2026-06-12T20:00:00.000Z"
----
-
-# 开始使用
-
-Use <FrameworkTabs value="react" /> to show framework-specific code.
-```
-
-标题来自 `title` frontmatter（如果存在），否则来自
-文件名。编辑器保留了 MDX 源代码，但尚无法进行可视化编辑，因此
-编码代理和普通文本编辑器仍然是安全的逃生舱口。
-
-## 自定义 MDX 组件
-
-内容可以从配置的 `components` 文件夹中预览本地组件。
-这适用于文档样式的 MDX 组件，例如选项卡、标注、包
-安装片段或特定于框架的代码块。
-
-例如，在您的内容旁边添加一个交互式组件：
-
-```tsx
-// components/ImpactCounter.tsx
-import { useState } from "react";
-
-export function ImpactCounter({
-  label = "points",
-  accent = "blue",
-  featured = false,
-}: {
-  label?: string;
-  accent?: "blue" | "green" | "purple";
-  featured?: boolean;
-}) {
-  const [count, setCount] = useState(3);
-  const accentClass =
-    accent === "green"
-      ? "border-green-300 bg-green-50"
-      : accent === "purple"
-        ? "border-purple-300 bg-purple-50"
-        : "border-blue-300 bg-blue-50";
-
-  return (
-    <div className={`rounded-md border p-4 ${accentClass}`}>
-      <div className="text-sm text-muted-foreground">Launch impact</div>
-      <div className="mt-1 text-3xl font-semibold">
-        {count} {label}
-      </div>
-      {featured ? <div className="mt-1 text-sm">Featured metric</div> : null}
-      <button
-        type="button"
-        className="mt-3 rounded border px-3 py-1 text-sm"
-        onClick={() => setCount((value) => value + 1)}
-      >
-        Add point
-      </button>
-    </div>
-  );
-}
-
-export const ImpactCounterInputs = {
-  label: {
-    type: "string",
-    label: "Metric label",
-    default: "points",
-  },
-  accent: {
-    type: "select",
-    label: "Accent",
-    options: ["blue", "green", "purple"],
-    default: "blue",
-  },
-  featured: {
-    type: "boolean",
-    label: "Featured",
-    default: false,
-  },
-};
-```
-
-然后从任何本地 MDX 文件使用它：
-
-```mdx
----
-title: "发布说明"
----
-
-# 发布说明
-
-<ImpactCounter label="wins" />
-```
-
-内容开发服务器发现 PascalCase 命名导出和 PascalCase 默认
-从 `components/` 下的 `.tsx`、`.jsx`、`.ts` 和 `.js` 文件导出。那些
-组件在编辑器内呈现并出现在
-**本地组件**。斜线插入创建一个最小的标签，例如
-`<ImpactCounter />`；需要时在 MDX 源中添加 props。
-
-组件执行有意成为本地开发/桌面桥接功能，而不是
-普通托管浏览器文件夹访问。如果你打开`content.agent-native.com`，
-选择**本地文件**，并在Chrome中选择一个文件夹，应用程序可以读写
-通过浏览器文件系统访问`.md`和`.mdx`文件API，但是
-Chrome 不会公开 Vite 编译的绝对文件夹路径
-`components/*.tsx`。要预览和热重载自定义 React 组件，请运行
-本地内容或使用 Agent Native Desktop，以便受信任的本地网桥可以
-将所选工作区注册到本地内容开发服务器。在该模式下，
-通过Vite编辑现有组件文件热重载，并添加或
-删除组件文件会重新加载组件注册表和斜杠菜单。
-
-代理还可以使用这些已注册的组件文件。使用
-`list-local-component-files` 找到注册的工作空间id，然后
-`write-local-component-file` 创建或更新 `.tsx`、`.jsx`、`.ts` 或
-`.js` 文件位于工作区的 `components/` 文件夹下。 MDX 文件仍然是
-组件使用的真实来源；组件文件保持正常仓库
-使用 Git 审核源文件。
-
-如果组件导出输入元数据，则在编辑器中选择该组件
-在组件的右上角显示一个编辑按钮。支持的输入类型
-为 `string`、`textarea`、`number`、`boolean` 和 `select`。表格写
-更改回 MDX 标签，因此本地文件仍然是事实来源。
-元数据可以导出为 `ComponentNameInputs`、`ComponentNameConfig.inputs`、
-`Component.inputs`，或`agentNative.inputs`。
-
-带有文字属性的简单组件标签可以内联预览：
-
-```mdx
-<FrameworkTabs value="react" />
-
-<Callout tone="warning">
-
-This setting affects production deploys.
-
-</Callout>
-```
-
-复杂的 JSX 表达式保留在源代码中。如果编辑者不能安全
-预览组件道具，它显示一个警告占位符而不是
-默默地丢弃数据。
-
-## 共享本地文件
-
-本地文件不会直接共享，因为其他用户无法读取路径
-你的机器。内容工具栏的共享按钮创建或刷新
-所选文件的数据库支持副本，导航到该副本，然后打开
-正常共享弹出窗口。原始本地文件保留在本地文件下；
-数据库副本出现在本地文件模式下的共享副本下，并使用
-标准文档共享模型。
-
-## 本地扩展
-
-本地文件模式还可以从配置中加载存储库支持的扩展
-`extensions` 文件夹。每个扩展都是一个带有 `extension.json`
-清单和 HTML 条目文件：
-
-```text
-extensions/
-  doc-status/
-    extension.json
-    index.html
-```
-
-```json
-{
-  "id": "doc-status",
-  "name": "Doc Status",
-  "description": "Shows metadata for the selected Content file.",
-  "entry": "index.html",
-  "slots": ["content.sidebar.bottom"],
-  "permissions": {
-    "appActions": ["list-documents"],
-    "extensionData": true
-  }
-}
-```
-
-`index.html` 与普通使用的 Alpine/Tailwind 扩展主体格式相同
-数据库支持的扩展。当内容应用看到本地扩展程序时
-声明了 `content.sidebar.bottom`，它在底部呈现该扩展
-内容侧边栏。主机通过选择的`window.slotContext`
-文档 ID、标题、源元数据以及内容是否处于本地文件模式。
-
-本地扩展由应用程序预览，但作为文件进行编辑。扩展
-列表显示它们带有本地文件徽章，整页查看器指向
-入口文件。 SQL 支持的扩展 actions，例如更新、删除、共享和
-历史记录不适用；使用您的编辑器、Codex、Claude 代码或 Git 历史记录
-源代码更改。
-
-对于 v1，本地扩展有意保守：
-
-- 他们可以将 `extensionData` 用于自己的小型运行时状态
-- 他们只能调用`extension.json`中列出的`appAction`
-- 原始 SQL 助手和外部 `extensionFetch` 已禁用
-- slot 目标在 `extension.json` 中声明，而不是通过 SQL 安装
-
-这为本地工作空间提供了类似黑曜石的插件界面，而无需让
-任意存储库文件继承数据库支持的扩展的所有功能。
-
-## 应用程序如何使用它
-
-本地文件模式是通过框架的本地工件助手实现的。
-应用程序声明其拥有的工件类型的根，然后读取和写入
-通过 UI 和代理已经使用的相同操作界面。
-
-对于内容，这意味着：
-
-- `list-documents` 列出配置的 `.md` 和 `.mdx` 文件。
-- `get-document` 读取选定的本地文件。
-- `update-document` 写入选定的本地文件。
-- `create-document` 在所选文件夹中创建新的本地 `.mdx` 文件。
-- `delete-document`删除本地文件。
-- 搜索在配置的本地文件中运行。
-
-不能从内容 UI 中移动、重命名和重新排序本地文件页面
-尚支持。在工作区或使用编码代理执行这些操作；
-内容侧边栏将反映生成的文件树。
-
-这使代理合约变得简单：代理可以继续使用内容 actions，
-而这些 actions 决定目标是 SQL 支持的还是文件支持的。
-
-随着时间的推移，其他应用程序可以采用相同的模式。幻灯片应用程序可以映射
-`slides/*.mdx` 到甲板，计划应用程序可以将 `plans/*` 映射到计划文档，以及
-仪表板应用程序可以将 `dashboards/*.mdx` 映射到仪表板。那些特定于应用程序的
-文件夹是位于同一本地工件合约之上的约定。
-
-## 本地文件与导出/导入
-
-内容有两种不同的文件工作流程：
-
-| 工作流程                 | 发生了什么                                                               |
-| ------------------------ | ------------------------------------------------------------------------ |
-| `/local-files` 导出/导入 | 数据库模式仍然是事实来源。文件是您导出、编辑、预览和导入的显式同步表面。 |
-| 本地文件模式             | 文件是真相的来源。内容侧边栏和编辑器直接对本地文件进行操作。             |
-
-当您需要偶尔查看托管工作区的文件时，请使用导出/导入。
-当存储库本身是工作区时，使用本地文件模式。
-
-## 历史与合作
-
-本地文件模式依赖于文件本机历史记录：
-
-- 向 Git 提交重要更改
-- 使用拉取请求进行审核
-- 让编码代理直接编辑相同的文件
-- 使用普通文件差异来了解更改
-
-数据库模式仍然更适合托管协作功能，例如
-共享、评论、SQL 支持的版本历史记录和实时多用户编辑。
-
-提供者同步可以分层在任一模式之上。例如，文档存储库可以
-添加 actions，将内容从 CMS 提取到本地 MDX 文件或推送所选内容
-本地文件返回到那个CMS。
-
-## 安全生产
-
-本地文件模式为应用程序 actions 提供对配置的工作区的直接写入访问权限
-文件。这适合本地开发和可信单租户文件
-桥梁，但它不是默认的生产安全模型。
-
-当 `NODE_ENV=production` 时，框架拒绝 `local-files` 模式，除非您
-设置：
-
-```bash
-AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
-```
-
-仅针对受信任的单租户部署进行设置，其中每个人都可以使用
-应用程序可以读取和写入配置的文件。对于普通托管，
-多用户应用程序，使用数据库模式和SQL支持的共享。
+迁移时请删除 `mode: "local-files"` 和 `AGENT_NATIVE_MODE=local-files`，保留
+roots 并添加 `source`。frontmatter ID 能在重命名和移动时保持页面身份。本地组件
+和扩展仍通过受信任的本地桥接加载。

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

@@ -89,9 +89,8 @@ description: "MDX 的开源 Obsidian：编辑本地 Markdown/MDX 文件，生成
 - **在树中组织页面** — 无限嵌套、拖动重新排序、收藏您经常使用的页面。
 - **搜索所有内容**，通过标题和内容进行全文搜索。
 - **像 Obsidian 一样编辑本地 Markdown/MDX 文件。**使用 `/local-files` 视图
-  将工作区导出到文件，在您自己的工具中编辑它们，预览
-  更改，并将其导入回来。在本地文件模式下，内容直接写入
-  选定的 `.md` 或 `.mdx` 文件。
+  将文件夹连接到 Files，使用自己的工具编辑并同步更改，然后在 SQL 应用中
+  审核冲突。
 - **生成丰富的交互式自定义块。**注册本地React组件，
   将它们插入为 MDX，并让代理创建或更新组件文件
   您的文档。
@@ -134,32 +133,18 @@ Native Desktop，并将当前文档树导出为Markdown/MDX
 评论、权限和实时协作；本地文件夹是显式的
 同步表面。
 
-内容还可以在**本地文件模式**下运行，其中文件是内容的来源
-真相而不是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/`小部件、安全生产指南。
+本地文件夹现在与所有页面使用相同的 SQL 模型。每个页面属于一个空间和它的
+Files 数据库；文件夹是该数据库的数据源适配器。策略、冲突、MDX 组件和旧模式
+迁移请参阅[本地文件夹源](/docs/local-file-mode)。
 
-要将内容本地文件技能安装到现有存储库中：
+要在现有仓库中打开 Content：
 
 ```bash
-npx @agent-native/core@latest skills add content --mode local-files --scope project
+npx @agent-native/core@latest content .
 ```
 
-安装程序会复制您的编码代理的 `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 编辑。
+CLI 会启动正常的数据库版 Content，注册文件夹源，并在不设置模式环境变量的
+情况下打开连接界面。
 
 ## 对于开发者