@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,219 @@
+---
+title: "共享和隐私"
+description: "Google Docs 风格的共享，内置于框架中。每个用户创建的资源（文档、仪表板、设计、演示文稿、剪辑、录音、表单）都会获得相同的默认私有模型以及一致的共享 UI。"
+---
+
+# 共享和隐私
+
+用户在代理原生应用程序中创建的每个资源（文档、仪表板、设计、演示文稿、视频编辑、屏幕录制、会议记录、表单、预订链接）**默认情况下对创建者来说是私有的**。仅当创建者明确共享它或将其可见性更改为 `org` 或 `public` 时，其他人才能看到它。
+
+它的外观和工作方式与 Google 文档类似。相同的共享按钮、相同的对话框、相同的三层可见性模型、相同的每用户/每组织授权 - 跨每个模板，无需针对每个应用进行重新设计。
+
+## 为什么选择一种模型 {#why}
+
+大多数应用程序框架都会共享每个功能的项目。结果：每个类似文档的界面最终都会有自己的共享对话框、自己的权限模式、自己的访问检查错误。在代理原生中，共享是一个**框架原语**。架构列、访问检查帮助程序、共享弹出窗口和代理可调用共享 actions 均随核心一起提供。新模板通过添加两栏和一行注册来获得完整的分享故事。
+
+这也意味着代理永远不必为每个应用程序学习新的共享模型。告诉代理在任何模板中“与作为编辑者的 Alice 共享此内容”，并且会触发相同的 `share-resource` 操作。
+
+## 三个可见性级别 {#visibility}
+
+粗略的可见性取决于资源本身；细粒度的赠款位于同伴共享表中。
+
+| 可见度    | 谁可以看到它                                                              |
+| --------- | ------------------------------------------------------------------------- |
+| `private` | 所有者+明确授予的人员。 **每个新资源的默认值。**                          |
+| `org`     | 所有者+显式授权+同一组织中的任何人（只读）。                              |
+| `public`  | 所有者+明确授予+任何知道链接的人（只读）。不会出现在其他人的列表/搜索中。 |
+
+`public` 是一个故意安静的级别：可以通过直接链接访问公共资源，但它**不会**显示在其他用户的侧边栏、列表或搜索中。这使得“共享 URL 的公开”与“跨用户发现的公开”分开。真正想要跨用户发现的画廊和模板目录明确选择加入。
+
+```an-diagram title="Visibility, widening outward" summary="Coarse visibility on the resource sets the floor; explicit share grants in the companion table add named people on top."
+{
+  "html": "<div class=\"share-tiers\"><div class=\"diagram-card\"><span class=\"diagram-pill\">private</span><small class=\"diagram-muted\">owner + explicit grants only &middot; <strong>default</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">org</span><small class=\"diagram-muted\">+ anyone in the same org (read-only)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">public</span><small class=\"diagram-muted\">+ anyone with the link (read-only) &middot; hidden from others' lists/search</small></div></div>",
+  "css": ".share-tiers{display:flex;flex-direction:column;align-items:stretch;gap:8px}.share-tiers .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.share-tiers .diagram-arrow{text-align:center;font-size:20px;line-height:1}"
+}
+```
+
+## 股份授予中的角色 {#roles}
+
+当您与特定用户或组织共享时，您可以选择一个角色：
+
+- **查看者** — 只读。
+- **编辑器** — 读取 + 写入。
+- **管理员** — 读取+写入+管理共享（可以添加/删除其他人）。
+
+`admin` 是否会更改 NOT 的所有权 - 每个资源仍然只有一个所有者，这与共享授予不同。
+
+## 涵盖内容 {#covered}
+
+每个存储用户创作作品的模板都使用此模型。具体来说：
+
+- **内容** — 文档
+- **幻灯片** — 幻灯片
+- **设计** — 设计和资产
+- **视频** — 作品
+- **剪辑** — 屏幕录制（Loom 风格）
+- **表单** — 表单定义
+- **日历** — 活动和预订链接
+- **分析** - 仪表板（推出 - 请参阅分析模板的 `AGENTS.md`）
+- **扩展** - 沙盒迷你应用程序（参见 [Extensions](/docs/extensions#sharing)）
+
+其中每一个都使用相同的 `ownableColumns()` 模式助手、相同的 `share-resource` 操作和相同的 `<ShareButton>` UI。从一个模板移动到另一个模板，共享对话框看起来相同。
+
+## 未涵盖的内容 {#not-covered}
+
+一些区域故意位于共享系统之外：
+
+- **个人数据应用程序**（邮件、宏）- 按设计限定用户范围。没有“共享我的收件箱”概念。
+- **外部真实来源应用程序** - 访问控制位于上游系统中，而不是代理本机应用程序中。
+- **匿名公共 URLs** — 向注销用户公开 URL 的表单发布 slugs 和预订链接 slugs 是一个单独的轴。它们与共享系统并存，而不是在其之上。
+
+## 分享UI {#share-ui}
+
+每个可共享资源的标题中都有一个共享按钮。单击它会打开一个锚定到按钮（不是模式）的弹出窗口，其中包含：
+
+- 可见性选择器（`Private` / `Organization` / `Public link`）。
+- “添加人员或团队”自动完成 - 搜索组织中的用户或粘贴电子邮件。
+- 用于个人电子邮件授权的 Google 文档样式 `Notify people` 复选框。
+- 包含角色选择器和删除控件的当前授权列表。
+- 尊重当前可见性的复制链接按钮。
+
+共享按钮是一次导入：
+
+```tsx
+import { ShareButton } from "@agent-native/core/client";
+
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+对于列表，请在每行旁边放置一个 `<VisibilityBadge visibility={row.visibility} />`，以便用户可以一目了然地了解哪些是私有的，哪些是共享的。
+
+## 与UI相同型号、代理商 {#agent-and-ui}
+
+框架在每个模板中自动安装这些 actions - 代理将它们称为工具，UI 通过 `useActionQuery` / `useActionMutation` 调用它们：
+
+| 行动                      | 它的作用                                                             |
+| ------------------------- | -------------------------------------------------------------------- |
+| `share-resource`          | 授予用户或组织特定角色的访问权限。可选的 `notify` 控制电子邮件通知。 |
+| `unshare-resource`        | 撤销用户或组织的访问权限。                                           |
+| `list-resource-shares`    | 显示当前可见性以及所有显式授权。                                     |
+| `set-resource-visibility` | 更改为 `private`、`org` 或 `public`。                                |
+
+告诉代理“与作为编辑的营销团队共享此设计”，它会针对 UI 使用的同一端点调用 `share-resource`。结果将显示在下一次渲染的共享对话框中。
+
+## 将其构建到新模板中 {#building}
+
+如果您正在创建模板（请参阅 [Creating Templates](/docs/creating-templates)），则共享接线会很短。您的架构中添加了两项内容：
+
+```ts
+import {
+  table,
+  text,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+```an-schema title="Resource + companion shares table" summary="Coarse visibility lives on the resource; each fine-grained grant is a row in the shares table."
+{
+  "entities": [
+    {
+      "id": "deck",
+      "name": "decks",
+      "note": "...ownableColumns()",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "The single source of truth for ownership." },
+        { "name": "org_id", "type": "text", "nullable": true },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "private | org | public" }
+      ]
+    },
+    {
+      "id": "deckShare",
+      "name": "deck_shares",
+      "note": "createSharesTable() — one row per grant",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "resource_id", "type": "text", "fk": "decks.id", "nullable": false },
+        { "name": "principal_type", "type": "enum", "note": "user | org" },
+        { "name": "principal_id", "type": "text", "note": "email (user) or org id (org)" },
+        { "name": "role", "type": "enum", "note": "viewer | editor | admin" },
+        { "name": "created_by", "type": "text" },
+        { "name": "created_at", "type": "text" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "deckShare", "to": "deck", "kind": "n-n", "label": "grants access to" }
+  ]
+}
+```
+
+`server/db/index.ts` 中的一次注册电话：
+
+```ts
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+之后，列表/读取查询通过 `accessFilter()` 传递，写入 actions 使用 `assertAccess()` 来强制执行角色。
+
+### 可选的强化标志 {#hardening-flags}
+
+`registerShareableResource` 接受执行代码或承载提升信任的资源的两个安全标志：
+
+```ts
+registerShareableResource({
+  type: "extension",
+  resourceTable: schema.extensions,
+  sharesTable: schema.extensionShares,
+  // ...
+  allowPublic: false, // Reject set-resource-visibility → "public"
+  requireOrgMemberForUserShares: true, // Reject user grants to non-org emails
+});
+```
+
+`allowPublic: false` 阻止任何调用者（代理或 UI）将资源的可见性设置为 `public`。 `requireOrgMemberForUserShares: true` 拒绝个人用户向资源所有者组织外部的电子邮件地址授予权限。扩展设置了两者：扩展的 HTML 在调用 actions 和 DB 作为 _viewer_ 的 iframe 内运行，因此公共访问将是具有查看者凭据的任意代码。
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "For resources that execute code or carry elevated trust (like extensions), set `allowPublic: false` and `requireOrgMemberForUserShares: true`. Otherwise a public share becomes arbitrary code running with the *viewer's* credentials."
+}
+```
+
+当代理或其他非 UI 呼叫者创建共享时，`getResourcePath` 会向通知电子邮件提供直接后备链接。完整的模式（包括创建操作所有权标记和现有表的迁移配方）存在于 `sharing` 代理技能中 - 代理在构建共享感知功能时按需读取它。
+
+## 安全保证 {#security}
+
+共享依赖于框架更广泛的数据范围模型 - 对可拥有表的列表/读/写访问通过 `accessFilter()` / `resolveAccess()` / `assertAccess()`，并且 `org_id` 标记的资源在组织中不可见。有关完整管道、CI 防护和威胁面，请参阅 [Security → Data Scoping](/docs/security#data-scoping)。
+
+## 另请参阅 {#see-also}
+
+- [Security & Data Scoping](/docs/security) - 共享所依赖的访问过滤器和所有权模型。
+- [Authentication](/docs/authentication) — 会话、组织以及身份如何流入请求上下文。
+- [Extensions](/docs/extensions#sharing) — 在沙盒迷你应用表面中共享。
+- [Creating Templates](/docs/creating-templates) — 将 `ownableColumns` 连接到新模板的架构中。

package/docs/content/locales/zh-CN/skills-guide.md

@@ -0,0 +1,281 @@
+---
+title: "Skills指南"
+description: "skills 如何在代理原生中工作：框架 skills、域 skills 以及创建自定义 skills。"
+---
+
+# Skills指南
+
+Skills 是 Markdown 文件，可让代理深入了解特定模式和工作流程。
+
+## skills是什么 {#what-are-skills}
+
+Skills 位于 `.agents/skills/<name>/SKILL.md`，包含针对代理的详细指导。每项技能都专注于一个问题 - 如何存储数据、如何同步状态、如何将工作委托给代理聊天。
+
+每个技能的 frontmatter `name` 和 `description` 总是被注入到系统提示符的 skills 块中，以便代理知道 skills 存在什么。当代理确定技能与任务相关时，会按需加载完整的技能主体（也通过 `docs-search` 显示）。这就是为什么保持描述简短且特定于触发器很重要：描述是代理在决定是否加载其余部分之前读取的唯一内容。
+
+```an-diagram title="Progressive disclosure" summary="Only the name + description of every skill is always in context. The full body loads on demand when the task matches."
+{
+  "html": "<div class=\"sk-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Always in the system prompt</span><div class=\"sk-list\"><span class=\"diagram-pill\">storing-data &mdash; <small class=\"diagram-muted\">add data models&hellip;</small></span><span class=\"diagram-pill\">real-time-sync &mdash; <small class=\"diagram-muted\">wire polling&hellip;</small></span><span class=\"diagram-pill\">create-skill &mdash; <small class=\"diagram-muted\">add a skill&hellip;</small></span></div><small class=\"diagram-muted\">just name + description (cheap)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><small class=\"diagram-muted\">task matches a description</small><span class=\"diagram-pill accent\">load on demand</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Full <code>SKILL.md</code> body<br><small class=\"diagram-muted\">rules, code, do/don't</small></div></div>",
+  "css": ".sk-flow{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.sk-flow .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px;min-width:240px}.sk-flow .sk-list{display:flex;flex-direction:column;gap:6px}.sk-flow .center{display:flex;flex-direction:column;align-items:center;gap:6px}.sk-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## 框架skills {#framework-skills}
+
+这些是与 **默认模板** 捆绑在一起的 skills。任何给定应用程序中可用的确切集合取决于您构建的模板 - 检查该模板的 `.agents/skills/` 目录以了解它实际提供的内容。
+
+| 技能                   | 何时使用                                      |
+| ---------------------- | --------------------------------------------- |
+| `storing-data`         | 添加数据模型，读/写配置或状态                 |
+| `real-time-sync`       | 接线轮询同步，调试UI不更新                    |
+| `delegate-to-agent`    | 将 AI 工作从 UI 或 actions 委托给代理         |
+| `actions`              | 创建或运行代理actions                         |
+| `self-modifying-code`  | 编辑应用源、组件或样式                        |
+| `create-skill`         | 为代理添加新的 skills                         |
+| `capture-learnings`    | 记录更正和模式                                |
+| `frontend-design`      | 构建或设计任何 Web UI、组件或页面的样式       |
+| `adding-a-feature`     | 四个区域清单：UI、actions、skills、应用状态   |
+| `internationalization` | 更新本地化的 UI 副本、语言目录和 RTL 安全样式 |
+| `shadcn-ui`            | 使用 shadcn/ui 原语和组件                     |
+| `security`             | 身份验证、访问控制和秘密处理                  |
+| `real-time-collab`     | 多用户协作编辑                                |
+| `agent-engines`        | 交换或配置底层代理引擎                        |
+| `notifications`        | 应用内和推送通知模式                          |
+| `progress`             | 跟踪和显示后台任务进度                        |
+| `inline-embeds`        | 在代理聊天中嵌入应用程序或 iframe             |
+
+`context-awareness` 和 `a2a-protocol` 是框架级 skills，位于存储库根目录的 `.agents/skills/` 目录中 - 请参阅每个模板自己的 `.agents/skills/` 了解其继承的内容。
+
+## 域名skills {#domain-skills}
+
+模板包括特定于其域的 skills。它们位于相同的 `.agents/skills/` 目录中，但涵盖了特定于模板的模式。请参阅每个模板的 `.agents/skills/` 目录以获取完整列表；代表性样本：
+
+- **邮件模板** — `email-drafts`、`draft-queue`
+- **表单模板** — `form-building`、`form-publishing`、`form-responses`
+- **分析模板** — `adhoc-analysis`、`bigquery`、`cross-source-analysis`、`dashboard-management`、`data-querying`、`provider-api`、`gong`、`hubspot`、`prometheus`
+- **幻灯片模板** — `create-deck`、`deck-management`、`design-systems`、`slide-editing`、`slide-images`
+
+域 skills 遵循与框架 skills 相同的格式。它们对代理需要遵循的特定模板的模式进行编码。
+
+## 应用程序支持的 skills {#app-backed-skills}
+
+应用程序支持的 skills 将代理本机应用程序打包为技能市场工件。该捆绑包可以包含代理指令、导出的 skills、MCP 连接器元数据、托管/本地启动指令和 UI 表面（例如 MCP 应用程序）。
+
+> **完整详细信息如下：** [App-backed skills — full details](#app-backed-skills-full) 中介绍了应用程序支持的 skills 的机制（清单格式、CLI 命令、市场适配器、自动更新哈希）。
+
+## 创建自定义 skills {#creating-skills}
+
+在以下情况下创建技能：
+
+- 代理应该重复遵循一个模式
+- 工作流程需要分步指导
+- 您想要从模板中构建文件
+
+在以下情况下不要创建技能：
+
+- 该指导已存在于另一项技能中 - 请扩展它
+- 该指导是一次性的 - 将其放入 `AGENTS.md` 或工作区内存中
+
+## 技能格式 {#skill-format}
+
+每个技能都是一个 Markdown 文件，其 frontmatter 为 YAML：
+
+```an-annotated-code title="Anatomy of a SKILL.md"
+{
+  "filename": ".agents/skills/project-imports/SKILL.md",
+  "language": "markdown",
+  "code": "---\nname: project-imports\ndescription: >-\n  How to import projects from the legacy CSV export. Use when the user uploads\n  a project CSV or asks to migrate projects from the old system.\n---\n\n# Project Imports\n\n## Rule\n\nAlways validate the CSV header row before writing any rows. Reject unknown\ncolumns rather than silently dropping them.\n\n## How\n\n1. Call `get-import-schema` to fetch the expected columns.\n2. Parse the first CSV row and diff against the schema.\n3. If any required columns are missing, return an error — do not proceed.\n4. Stream remaining rows through `create-project-item` in batches of 50.\n\n## Don't\n\n- Don't hold all rows in memory — stream them.\n- Don't create duplicate projects; check for an existing name first.\n\n## Related Skills\n\n- **storing-data** — SQL schema and write patterns for new rows\n- **sharing** — exposing a project to other users after import",
+  "annotations": [
+    { "lines": "2", "label": "Discovery key", "note": "The `name` matches the folder; it is how the skill is invoked as `/project-imports`." },
+    { "lines": "3-5", "label": "The trigger", "note": "This `description` is the **only** text always in context. Make it state precisely *when* the skill applies." },
+    { "lines": "9-14", "label": "Rules first", "note": "Lead with the hard rule and the why; the agent reads the body only once the task matches." },
+    { "lines": "27-30", "label": "Cross-link", "note": "Point at related skills so the agent can chain them instead of re-deriving guidance." }
+  ]
+}
+```
+
+frontmatter `name` 和 `description` 由代理的工具系统用于技能发现。描述应说明技能何时触发——具体说明具体情况。
+
+将文件保存在 `.agents/skills/my-skill/SKILL.md`。目录名称应与 frontmatter 中的 `name` 匹配。
+
+> **另请参阅：** [Writing Agent Instructions](/docs/writing-agent-instructions) 了解如何措辞技能描述、应用渐进式披露以及保持 `AGENTS.md` 的精简。两个页面均使用 `project-imports` 技能作为运行示例。
+
+## 技能范围：运行时与开发 {#skill-scope}
+
+可选的 `scope` frontmatter 字段控制技能适用于哪个代理：
+
+| `scope`   | 由运行时代理加载？ | 用于                                                       |
+| --------- | ------------------ | ---------------------------------------------------------- |
+| `both`    | 是（默认）         | Skills 对于应用内代理有用。当省略 `scope` 时，这是默认值。 |
+| `runtime` | 是                 | Skills 仅适用于应用内运行时代理。                          |
+| `dev`     | 否                 | Skills 仅适用于人类的编码代理（例如 Claude 代码）。        |
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+当 `scope` 不存在（或设置为无法识别的值）时，它默认为 `both`，因此每个现有技能都会在运行时加载 - 该字段完全向后兼容。 `scope: dev` 技能对于任何地方的运行时代理都是不可见的：它被排除在注入系统提示符的 skills 块和 `docs-search` 结果之外。
+
+### 向您的编码代理公开仅限开发的技能 {#dev-only-skills}
+
+代理本机运行时从 `.agents/skills/` 读取 skills。 Claude 代码独立从 `.claude/skills/` 读取 skills。要使编码代理可用但对运行时代理隐藏的技能：
+
+- 将其标记为 `.agents/skills/<name>/SKILL.md` 中的 `scope: dev`，以便运行时代理永远不会加载它，和/或
+- 将技能放置或镜像到 `.claude/skills/<name>/SKILL.md` 下，以便 Claude 代码拾取它。
+
+这取代了依赖 Claude 代码仅读取 `.claude/skills` 的旧技巧 - `scope: dev` 使开发与运行时分割成为一流的显式选择。
+
+```an-diagram title="Which agent loads which skill" summary="scopedecides whether the in-app runtime agent sees a skill.dev skills are visible only to your coding agent."
+{
+"html": "<div class=\"sc-grid\"><div class=\"diagram-card\"><span class=\"diagram-pill\">.agents/skills/</span><div class=\"sc-row\"><span class=\"diagram-pill ok\">scope: both</span><small class=\"diagram-muted\">default</small></div><div class=\"sc-row\"><span class=\"diagram-pill ok\">scope: runtime</span></div><div class=\"sc-row\"><span class=\"diagram-pill warn\">scope: dev</span></div></div><div class=\"sc-targets\"><div class=\"diagram-box\">Runtime agent<br><small class=\"diagram-muted\">reads <code>both</code> + <code>runtime</code></small></div><div class=\"diagram-box\">Coding agent<br><small class=\"diagram-muted\">Claude Code reads <code>.claude/skills/</code> + <code>dev</code></small></div></div></div>",
+"css": ".sc-grid{display:flex;gap:24px;flex-wrap:wrap;align-items:flex-start}.sc-grid .diagram-card{display:flex;flex-direction:column;gap:8px;padding:14px 16px}.sc-grid .sc-row{display:flex;align-items:center;gap:8px}.sc-grid .sc-targets{display:flex;flex-direction:column;gap:10px}"
+}
+
+```
+
+> **另请参阅：** [Writing Agent Instructions](/docs/writing-agent-instructions) 了解如何措辞技能描述、应用渐进式披露以及保持 `AGENTS.md` 精简。
+
+## Skills vs AGENTS.md {#skills-vs-agents-md}
+
+> **AGENTS.md** — 概述。列出所有脚本，描述数据模型，解释应用程序架构。代理首先阅读此内容以了解应用程序。
+>
+> **Skills** — 深入研究。每项技能都侧重于一种模式，并包含详细规则、代码示例和“注意事项”列表。当代理需要遵循特定模式时，它会读取这些内容。
+
+`AGENTS.md` 告诉代理应用程序的用途。 Skills 告诉代理*如何*正确地做特定的事情。两者都是必需的 - `AGENTS.md` 用于定向，skills 用于执行。
+
+## Skills 与内存 {#skills-vs-memory}
+
+> **Skills** — 编写的、可重复使用的操作指南。适用于每个用户，在任务匹配时按需调用。
+>
+> **内存 (`LEARNINGS.md` / `memory/MEMORY.md`)** — 共享项目学习和每轮都会加载的个人结构化内存。
+
+如果这些知识适用于在应用程序中工作的*每个人*（“总是更喜欢 CTE 而不是子查询”），那么它就是一项技能或共享的 `LEARNINGS.md`。如果它是关于*这个特定用户*（“史蒂夫喜欢简洁的答案”），它就属于 `memory/MEMORY.md`。完整治疗请参见[Workspace Memory](/docs/workspace#memory)。
+
+---
+
+# 高级
+
+## 应用程序支持的 skills — 完整详细信息 {#app-backed-skills-full}
+
+应用程序支持的 skills 将代理本机应用程序打包为技能市场工件。
+捆绑包可以包含代理指令、导出的 skills、MCP 连接器
+元数据、托管/本地启动说明和 UI 界面，例如 MCP 应用程序。
+
+每个应用程序支持的技能都以应用程序根目录中的 `agent-native.app-skill.json` 开头：
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "assets",
+  "hosted": {
+    "url": "https://assets.agent-native.com",
+    "mcpUrl": "https://assets.agent-native.com/_agent-native/mcp"
+  },
+  "mcp": { "serverName": "agent-native-assets" },
+  "skills": [
+    {
+      "path": ".agents/skills/asset-generation",
+      "visibility": "both",
+      "exportAs": "assets"
+    }
+  ]
+}
+```
+
+技能可见性控制运送的内容：
+
+| 可见度     | 含义                                 |
+| ---------- | ------------------------------------ |
+| `internal` | 由应用自己的代理使用，不导出到市场。 |
+| `exported` | 导出到市场，但应用内部不需要。       |
+| `both`     | 内部使用并导出。                     |
+
+Hosted 是默认安装路径。本地启动是明确的定制，
+离线工作，或隐私敏感的使用。
+
+```bash
+# Happy path: exported instructions plus hosted MCP connector.
+npx @agent-native/core@latest skills add visual-plan
+npx @agent-native/core@latest skills add assets
+
+# Repo-first Content docs/blog/MDX editing.
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+
+# Vercel/open Skills CLI: exported instructions only, no MCP config.
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# Register a hosted MCP connector for local agent clients.
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Materialize and run editable local source.
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Build marketplace adapters: Codex plugin, Claude marketplace, Vercel skills,
+# plain/Claude skills, and MCP configs.
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install a local exported bundle with the Vercel/open Skills CLI.
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# Add the generated Claude Code marketplace, then install its Assets plugin.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+对技能文件保密。清单应包含仅 URL 连接器
+元数据； OAuth/设备设置发生在 MCP 主机中或通过应用程序的正常设置
+设置流程。
+
+Vercel Labs `skills` 适配器是便携式 `skills/<name>/SKILL.md` 捆绑包
+适用于 `npx skills@latest add ...`，但原始 `skills` CLI 仅安装说明。
+它不运行存储库定义的安装后脚本或注册 MCP 连接器。
+将 Agent Native CLI 保留为本地代理的默认文档路径，因为它
+还注册 MCP 连接器。 `BuilderIO/agent-native`是真正的GitHub
+Vercel/open Skills CLI 的存储库源； `skills.sh` 是一个发现，并且
+排行榜目录，而不是npm风格的包命名空间。
+
+Claude 代码市场适配器写入
+`adapters/claude-marketplace/.claude-plugin/marketplace.json` 加一个嵌套
+包含 `skills/<name>/SKILL.md` 和 `.mcp.json` 的插件目录。在Claude
+编码，添加市场，安装`agent-native-assets@agent-native-apps`，
+重新加载插件，然后从 `/mcp` 验证仅限 URL 的 MCP 连接器。
+
+生成的插件清单设置为自动更新：Claude 代码
+市场入口集 `autoUpdate: true`（带有 commit-SHA 版本控制）和
+Codex 插件 `version` 嵌入捆绑的 skills 和 MCP 的内容哈希
+端点，因此安装的插件无需重新打包即可获取技能更改。
+计划应用程序以这种方式发布为存储库根目录中的可随时添加的市场 —
+请参阅 [Plan plugin & marketplace](/docs/plan-plugin) 以了解端到端安装
+和自动更新流程。
+
+对于通过通用CLI而不是安装复制的skills的用户
+插件市场，使用CLI新鲜度命令：
+
+```bash
+npx @agent-native/core@latest skills status visual-plan
+npx @agent-native/core@latest skills update visual-plan
+```
+
+`skills update` 扫描已知的 Codex/Claude 项目和用户技能文件夹，进行比较
+将文件夹哈希复制到最新的捆绑技能，并重写旧文件夹
+地点。新复制的 Agent Native skills 包括 `agent-native-skill.json`
+标记，以便将来的状态输出可以识别源和哈希值。
+
+生成的 Agent Native 应用程序和工作区还包括框架提供的
+`.agents/skills` 下的 skills（或 `packages/shared/.agents/skills` 中的
+工作区）。使用以下命令从当前/最新的 CLI 刷新那些支架 skills：
+
+```bash
+npm run skills:update
+# or, without relying on the local package script:
+npx @agent-native/core@latest skills update scaffold --project
+```
+
+`AGENTS.md` 和 `.agents/skills` 保持规范。更新命令还可以修复
+Claude 兼容性链接（`CLAUDE.md` 和 `.claude/skills`），因此 Claude 代码可见
+相同的说明，无需维护第二个副本。