@agent-native/core 0.79.2 → 0.79.5

package/corpus/core/docs/content/locales/zh-TW/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="視野，向外擴大" summary="資源的粗略可見性奠定了基礎；伴隨表中的顯式共用授予會在頂部新增指定人員。"
+{
+  "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 檔案樣式 `通知 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="資源+同伴分享表" 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": "所有權的唯一事實來源。" },
+        { "name": "org_id", "type": "text", "nullable": true },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "私人|組織|民眾" }
+      ]
+    },
+    {
+      "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": "使用者 |組織" },
+        { "name": "principal_id", "type": "text", "note": "email (user) or org id (org)" },
+        { "name": "role", "type": "enum", "note": "觀眾|編輯|行政" },
+        { "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/corpus/core/docs/content/locales/zh-TW/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="漸進式披露" summary="只有每個技能的名稱+描述始終處於上下文中。當工作匹配時，全身會按需載入。"
+{
+  "html": "<div class=\"sk-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">始終在系統提示中</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\">規則、程式碼、應該做和不要做</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="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": "發現鑰匙", "note": "The `name` matches the folder; it is how the skill is invoked as `/project-imports`." },
+    { "lines": "3-5", "label": "觸發器", "note": "這個 `description` 是始終處於上下文中的**唯一**文本。準確地說明該技能“何時”應用。" },
+    { "lines": "9-14", "label": "規則第一", "note": "Lead with the hard rule and the why; the agent reads the body only once the task matches." },
+    { "lines": "27-30", "label": "交聯", "note": "指出相關技能，以便代理可以將它們連結起來，而不是重新得出指導。" }
+  ]
+}
+```
+
+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="哪個代理載入哪個技能" summary="範圍決定應用程式內執行時代理是否看到技能。開發技能僅對您的編碼代理可見。"
+{
+"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\">編碼 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
+# 愉快的路徑：匯出的指令加上託管的 MCP 連線器。
+npx @agent-native/core@latest skills add visual-plan
+npx @agent-native/core@latest skills add assets
+
+# 回購優先內容 docs/blog/MDX 編輯。
+npx @agent-native/core@latest skills add content --mode local-files --scope project
+
+# Vercel/open技能CLI：僅匯出指令，無MCP設定。
+npx skills@latest add BuilderIO/agent-native --skill assets
+
+# 為本機代理用戶端註冊託管 MCP 連線器。
+npx @agent-native/core@latest app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# 實現並執行可編輯的本機來源。
+npx @agent-native/core@latest app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# 建置市場適配器：Codex 外掛、Claude 市場、Vercel 技能、
+# plain/Claude技能和MCP設定。
+npx @agent-native/core@latest app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# 使用 Vercel/open 技能 CLI 安裝本機匯出的包。
+npx skills@latest add ./dist/assets-skill --skill assets -a codex -y
+
+# 新增生成的 Claude Code 市場，然後安裝其 Assets 外掛。
+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
+# 或者，不依賴本機包腳本：
+npx @agent-native/core@latest skills update scaffold --project
+```
+
+`AGENTS.md` 和 `.agents/skills` 保持規範。更新指令還可以修複
+Claude 兼容性連結（`CLAUDE.md` 和 `.claude/skills`），因此 Claude 程式碼可見
+相同的說明，無需維護第二個副本。