@agent-native/core 0.79.2 → 0.79.6

package/corpus/core/docs/content/locales/zh-TW/workspace.md

@@ -0,0 +1,323 @@
+---
+title: "工作區"
+description: "Claude - 每個使用者的程式碼級自訂 - skills、內存、指令、自訂代理、計畫作業、MCP 伺服器 - 由 SQL 支持，而不是檔案系統。"
+---
+
+# 工作區
+
+> **哪個工作區檔案？** 此頁面涵蓋 **自訂層** — 工作區*是什么*。對於部署形狀（一個單一儲存庫，許多應用程式），請參閱 [Multi-App Workspaces](/docs/multi-app-workspace)；有關治理（誰審查、批準和擁有什么），請參閱 [Workspace Governance](/docs/workspace-management)。
+
+每個代理本機應用程式都附帶一個**工作區**：使代理成為您的自訂層。它包含團隊指令 (`AGENTS.md`)、共用學習內容 (`LEARNINGS.md`)、個人結構化內存 (`memory/MEMORY.md`)、代理按需拉入的 skills、自訂子代理、計畫作業和連線的 MCP 伺服器 — 您期望從 Claude 程式碼 / Codex 設定獲得的一切。
+
+變化：**它是 SQL 行，而不是檔案系統檔案。**每個使用者都將自己的工作區存儲在資料庫中。沒有要啟動的開發盒，沒有每個使用者的容器，沒有要安裝的檔案。多租戶 SaaS 可以為每個使用者提供基本上免費的完全可定制的代理，因為所有這些都是行——個人內存、個人 MCP 伺服器、個人 skills、個人子代理——並且共用程式碼庫同時託管所有這些。
+
+```an-diagram title="Claude-Code 工作區，但存儲在 SQL 中" summary="相同的定制層——指令、技能、內存、代理、作業、MCP——除了每個檔案都是共用多租戶資料庫中的一行。"
+{
+  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native 工作區</span><small class=\"diagram-muted\">rows in one SQL 資料庫</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">一個程式碼庫，多使用者，有作用域 <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
+  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+}
+```
+
+| Claude程式碼/Codex            | 代理本機工作區                          |
+| ----------------------------- | --------------------------------------- |
+| 本機磁盤上的檔案              | 共用 SQL 資料庫中的行                   |
+| 每個開發人員一個程式碼庫      | 一個程式碼庫，多個使用者                |
+| 需要開發盒或容器              | 在任何無伺服器/邊缘主機上執行           |
+| `~/.claude/` 定制             | 按使用者自訂，範圍為 `u:<email>:…`      |
+| 每個專案 `CLAUDE.md` / skills | 每個應用 `AGENTS.md` + 工作區內存資源   |
+| JSON 檔案中的 MCP 設定        | JSON 中的 MCP 設定*或*設定 UI，每個範圍 |
+
+相同的功能。不同的經濟。請參閱 [Templates](/docs/cloneable-saas) 了解為什么這對 SaaS 很重要。
+
+## 概述 {#overview}
+
+資源具有三個執行時範圍：
+
+- **個人** — 範圍僅限於單個使用者（他們的電子郵件）。適合偏好設定、注釋和每個使用者的上下文。
+- **共用/組織** — 對應用程式或組織中的所有使用者可見。適合應用/團隊說明、skills 和共用設定。
+- **工作空間** — 繼承了從調度資源管理的全域預設值。適合公司事實、定位、品牌指南、全球護欄、工作區範圍的 skills 和共用 MCP 伺服器。應用程式在執行時讀取這些；它們不會複製到每個應用程式中。
+
+應用內工作區面板顯示所有三個範圍。個人和共用/組織資源可以在那裡編輯。工作區範圍的資源在應用面板中是唯讀的，並通過 Dispatch 進行集中編輯，因此每個應用都可以看到相同的規範檔案，而無需同步步驟。
+
+控制代理如何使用每個資源的規範路徑：
+
+| 執行時資源           | 路徑                                  | 代理如何使用它                       |
+| -------------------- | ------------------------------------- | ------------------------------------ |
+| 護欄說明             | `AGENTS.md`或`instructions/<slug>.md` | 在每個收到它的應用程式中載入每個回合 |
+| 全域skills           | `skills/<slug>/SKILL.md`              | 列為工作區 skills 並按需閱讀         |
+| 品牌/公司資源        | `context/<slug>.md`                   | 每回合都編入索引，相關時閱讀         |
+| 自訂代理設定檔案     | `agents/<slug>.md`                    | 可作為可重複使用的本機代理設定檔案   |
+| 共用 HTTP MCP 伺服器 | `mcp-servers/<slug>.json`             | 載入到授權應用的MCP工具註冊表        |
+
+這些路徑適用於所有三個範圍 - 工作空間、組織/應用程式和個人。當同一路徑存在於多個級別時，後面的範圍獲勝。
+
+```an-diagram title="三個範圍，一個有效檔案" summary="執行時在讀取時解析跨工作區、應用程式和個人範圍的相同路徑 - 最具體的範圍獲勝。"
+{
+  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">來自 Dispatch 的公司級預設值</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">組織 / 應用</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
+  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+}
+```
+
+## 入門：1 分鐘演練 {#getting-started}
+
+在 60 秒內更改代理的行為方式。
+
+1. 開啟 **工作空間** 分頁 → **共用** → `AGENTS.md`（使用 `+` 建立它 → **檔案** 如果缺少）。
+2. 新增一條規則，例如：
+
+   ```降價
+   ## 語氣
+
+   要簡潔。以答案開頭。
+   ```
+
+3. 儲存，切換到**聊天**，詢問任何問題 - 客服人員立即遵循新規則。
+
+```an-callout
+{ "tone": "info", "body": "無需重新啟動，無需重新部署。 `AGENTS.md` 在每個回合開始時都會被讀取，因此您現在儲存的編輯會更改代理在下一條訊息中的行為。" }
+```
+
+**後續步驟（當您需要時）：**
+
+- **Skills** (`+` → **技能**) — 在與 `/skill-name` 聊天時調用的重點操作方法檔案。
+- **代理** (`+` → **代理**) — 使用 `@agent-name` 調用的可重用子代理角色。
+- **計畫工作** (`+` → **計畫工作**) — 在 cron 上執行的提示。有關計畫和觸發器，請參閱 [Recurring Jobs](/docs/recurring-jobs)。
+- **內存** - 共用 `LEARNINGS.md` 和個人 `memory/MEMORY.md` 在對話中保持持久上下文可用。
+
+## 全域資源和規範路徑 {#global-resources}
+
+工作區範圍的資源通過 Dispatch 的 **資源** 頁面進行管理，並在執行時由應用程式繼承 - 無需複製或同步步驟。 Dispatch 支持兩種授予範圍：
+
+- **所有應用程式** — 工作區中的每個應用程式繼承的全域資源。大多數公司、品牌、角色、定位、訊息傳遞和護欄上下文應該是**所有應用**。
+- **選定的應用程式** — 授予特定應用程式用於特定於應用程式的上下文或工具的資源。謹慎使用這些。
+
+路徑決定代理如何使用資源（請參閱上面 [Overview](#overview) 中的表）。這是核心角色、定位、訊息傳遞、公司事實、品牌指南、支持政策、共用 skills 或共用 HTTP MCP 工具的正確之家，許多應用都應該從中受益。
+
+適用於新工作區的有用入門包：
+
+```text
+context/company.md              # 公司的業務、ICP、產品、連結
+context/brand.md                # 聲音、視覺識別、拼寫、禁止使用
+context/messaging.md            # 定位、價值支柱、證據點、反對意見
+instructions/guardrails.md      # 合規、升級和批準規則
+skills/company-voice/SKILL.md   # on-demand guidance for customer-facing writing
+agents/<slug>.md                # reusable custom agent profiles
+```
+
+保持 `context/` 檔案真實且易於瀏覽。將每回合都必須適用的規則放入 `instructions/guardrails.md` 中。當代理需要故意轉換或審查公司聲音的副本時，請使用`skills/company-voice/SKILL.md`。
+
+要覆蓋一個應用或團隊的全域預設值，請在該應用中使用相同的路徑建立共用/組織資源。要為一個人覆蓋它，請建立具有相同路徑的個人資源。不要將工作區檔案複製到每個應用程式中；執行時解析讀取時的堆堆疊：
+
+```text
+workspace context/brand.md
+-> shared/app context/brand.md
+-> personal context/brand.md
+```
+
+保持 `context/` 檔案簡短且真實——代理可以瀏覽的一些要點：
+
+```text
+<!-- context/brand.md -->
+
+# 品牌
+
+- Voice: direct, warm, concrete
+- Use: "workspace", "agent", "team"
+- Avoid: unsupported superlatives and vague AI claims
+```
+
+## 工作區面板 {#workspace-panel}
+
+代理面板包括一個 **工作區** 分頁以及聊天和 CLI。它顯示了所有資源的資料夾組織樹、任何文本檔案的內聯編輯器（Markdown、JSON、YAML、純文本）以及 `+` 選單的型別化建立流程（檔案、Skills、代理、計畫工作）。使用者可以瀏覽繼承的工作區預設設定並建立/編輯/刪除個人或組織資源。
+
+當您開啟資源時，編輯器會顯示帶有 `workspace default -> organization/app override -> personal override` 堆堆疊的 **有效上下文** 條帶，以便您可以檢視繼承的內容以及覆蓋為何處於活動狀態。 Dispatch 從控制平面端顯示相同的模型：在 **Resources** 頁面上使用 **Effective in app**，或在應用程式卡的 **Context** 對話框中的資源行上展開 **Stack**。
+
+啟用 Dispatch 審批策略後，建立、更新或刪除 **所有應用** 資源會將審批請求排隊，而不是立即應用。建立/編輯/刪除對話框在儲存之前顯示影響預覽。
+
+點選工作區工具列中的 `?` 圖標可隨時跳回這些檔案。
+
+## 代理如何使用資源 {#how-the-agent-uses-resources}
+
+內置應用程式代理使用統一的 `resources` 工具管理資源：使用 `action: "list"`、`"read"`、`"effective"`、`"write"`、`"promote"` 或 `"delete"`。外部CLI/程式碼代理可以使用等效的`pnpm action resource-*`指令。
+
+在每次對話開始時，代理會自動讀取：
+
+### AGENTS.md 及說明 {#agents-md}
+
+`AGENTS.md` 是預設播種的指令資源，並按順序從工作區、共用/組織和個人範圍每次載入 - 工作區用於公司範圍的預設設定，共用/應用程式用於團隊規則，個人用於每個使用者的偏好設定。 `instructions/` 下的檔案是單獨的護欄檔案，也適用於每個回合（合規規則、升級政策、品牌聲音）並遵循相同的優先級。正常的聊天和整合觸發的執行都會在回應之前載入它們。
+
+```text
+AGENTS.md
+instructions/customer-support-guardrails.md
+instructions/legal-review-policy.md
+```
+
+### 參考資源 {#reference-resources}
+
+可重複使用的公司背景位於 `context/` 下（角色、定位、產品事實、品牌指南、競爭說明）。當工作可能依賴於它時，代理會看到這些索引並使用 `resources` 工具 (`action: "read"`) 讀取相關檔案；使用 `action: "effective"` 檢視工作區預設值是否被應用或使用者覆蓋。
+
+### 內存 {#memory}
+
+工作區有兩個目前內存表面：
+
+- `LEARNINGS.md` 在**共用**範圍內，用於專案範圍的約定、更正和持久的團隊知識。
+- `memory/MEMORY.md` 位於有關目前使用者的結構化內存的**個人**範圍內。
+
+資源系統還播種個人 `LEARNINGS.md` 以與舊工作區兼容，但聊天預載入路徑是共用的 `LEARNINGS.md` 加上個人 `memory/MEMORY.md`。
+
+**儲存什么。**當您糾正代理（“始終使用 X 而不是 Y”）、共用偏好（“我更喜歡簡潔的答案”）或揭示上下文（“我的團隊將此稱為“調度層””）時，代理會捕獲該學習內容，因此不會重複錯誤或重新詢問。專案範圍內的學習內容在共用的 `LEARNINGS.md` 中；使用者特定內存位於 `memory/` 下。 `capture-learnings` 技能說明了何時以及如何進行。
+
+**適合的地方。**
+
+| 表面               | 範圍        | 作者                               | 閱讀時間                     |
+| ------------------ | ----------- | ---------------------------------- | ---------------------------- |
+| `AGENTS.md`        | 共用        | 根據要求提供人類/代理              | 每個回合                     |
+| `LEARNINGS.md`     | 共用        | 根據要求提供人類/代理              | 每回合（僅限共用副本）       |
+| `memory/MEMORY.md` | 個人        | 特工/人類                          | 每個回合                     |
+| `instructions/…`   | 共用        | 根據要求提供人類/代理              | 每個回合                     |
+| `skills/…`         | 共用        | 根據要求提供人類/代理              | 按需（`/slash` 指令）        |
+| `context/…`        | 共用        | 根據要求提供人類/代理              | 每回合都編入索引，相關時閱讀 |
+| `mcp-servers/…`    | 工作區/共用 | 人類通過 Dispatch 或應用程式工作區 | MCP設定刷新                  |
+
+使用者可以直接在“工作空間”分頁中編輯這些內存檔案 - 它們是常規資源。刪除代理出錯的行，將個人偏好保留在 `memory/MEMORY.md` 中，或將團隊範圍的規則推廣到 `AGENTS.md` 中。
+
+這些表面中的每一個 - `AGENTS.md`、skills、內存、自訂代理、MCP 伺服器 - 都是相同的底層資源形狀：`path` + `scope` + `content`，以相同的方式尋址和解析。
+
+```an-schema title="工作區資源模型" summary="一種資源形狀支持每個工作區檔案。執行時按路徑和範圍對其進行鍵控，並解析讀取時的有效值。"
+{
+  "entities": [
+    {
+      "id": "resource",
+      "name": "workspace resource",
+      "note": "使用者工作區中的單個檔案 - 說明、技能、內存、代理、MCP 設定或作業。",
+      "fields": [
+        { "name": "path", "type": "string", "note": "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md" },
+        { "name": "scope", "type": "workspace | shared | personal", "note": "該行位於哪一層" },
+        { "name": "owner", "type": "string", "nullable": true, "note": "u:<email> for personal scope" },
+        { "name": "content", "type": "text", "note": "Markdown / JSON / YAML 內文" }
+      ]
+    }
+  ]
+}
+```
+
+## Skills {#skills}
+
+Skills 是 `skills/` 路徑（最好是 `skills/<name>/SKILL.md`）下的 Markdown 資源檔案，為代理提供按需領域知識，在與 `/skill-name` 聊天時調用。從“工作空間”分頁新增它們，或者在“程式碼”模式下從 `.agents/skills/` 新增它們。
+
+請參閱 [Skills Guide](/docs/skills-guide) — 技能格式、範圍、發現和創作的單一來源。
+
+## 自訂代理 {#custom-agents}
+
+自訂代理是可重用的本機子代理設定檔案，存儲為 `agents/*.md` 下的 Markdown 資源。這是自訂代理格式的規範主頁面。
+
+當您想要一個具有自己的名稱、描述、模型偏好設定和指令集的集中委托時，請使用它們。與 skills 不同，自訂代理不是被動指導 - 它們是主代理可以通過 `@` 提及或在子代理生成期間選取它們來調用的操作角色。
+
+### 代理格式 {#agent-format}
+
+自訂代理使用 YAML frontmatter 加上 Markdown 指令：
+
+```an-annotated-code title="自訂代理設定檔案"
+{
+  "filename": "agents/design.md",
+  "language": "markdown",
+  "code": "---\nname: Design\ndescription: >-\n  Reviews layouts, interaction patterns, and product UX decisions.\nmodel: inherit\ntools: inherit\ndelegate-default: false\n---\n\n# 角色\n\n您是一名專注的設計代理。\n\n##職責\n\n-審查布局和互動流程\n-提出更強的視覺方向\n-簡潔且有主見",
+  "annotations": [
+    { "lines": "2", "label": "@mention handle", "note": "`name` 是 `@` 下拉列表中顯示的內容，也是主代理委托的內容。" },
+    { "lines": "3-4", "label": "何時委托", "note": "`description` 是協調器讀取的內容，以確定此設定檔案適合工作。" },
+    { "lines": "5", "label": "型號", "note": "`inherit` 重用主代理的模型。僅當設定檔案明確需要不同的設定檔案時才覆蓋。" },
+    { "lines": "6", "note": "`tools: inherit` 目前 - 該欄位是為未來的每代理工具策略保留的。" }
+  ]
+}
+```
+
+推薦約定：
+
+- 將定制代理存儲在`agents/<slug>.md`
+- 使用 `model: inherit` 除非設定檔案明確需要不同的模型
+- 暫時保留`tools: inherit`；該欄位是為未來的工具策略保留的
+
+### 遠端代理與自訂代理 {#remote-vs-custom-agents}
+
+工作區中有兩種代理型別：
+
+- **自訂代理** — `agents/*.md` 中的本機設定檔案，在目前應用/執行時內執行
+- **連線的代理** — 由 `remote-agents/*.json` 中的清單描述的遠端 A2A 對等點（仍可識別舊版 `agents/*.json` 清單）
+
+在一個應用程式內使用自訂代理進行委派。當您需要通過 A2A 調用另一個應用程式時，請使用連線的代理。
+
+## @標記 {#at-tagging}
+
+在聊天輸入中鍵入 `@` 以引用工作區專案。光標處會出現一個下拉列表，顯示匹配的代理和檔案。使用箭頭鍵進行導覽並使用 Enter 進行選取。所選專案在輸入中顯示為內聯芯片。
+
+當您發送訊息時，**檔案/資源**作為代理可以讀取的引用進行傳遞，**自訂代理**使用其設定檔案指令在本機執行，並且**連線的代理**通過 A2A 進行調用。
+
+## / 斜線指令 {#slash-commands}
+
+在行首鍵入 `/` 以調用技能。下拉列表顯示可用的 skills 及其名稱和描述；選取一個會新增一個內聯芯片，並在發送訊息時將其內容作為上下文包含在內。如果未設定 skills，則下拉列表連結到這些檔案。
+
+## 程式碼與應用程式模式 {#dev-vs-prod}
+
+資源系統在兩種模式下的工作方式相同。不同之處在於可用於 `@` 標記和 `/` 指令的其他來源：
+
+| 功能           | 程式碼模式                                      | 應用模式                         |
+| -------------- | ----------------------------------------------- | -------------------------------- |
+| @標記          | 程式碼庫檔案 + 工作區資源 + 自訂代理 + 連線代理 | 工作區資源 + 自訂代理 + 連線代理 |
+| /斜線指令      | .agents/skills/ + 資源 skills                   | 僅資源skills                     |
+| 代理檔案存取   | 檔案系統+資源                                   | 僅限資源                         |
+| 工作區面板     | 完全存取權限                                    | 完全存取權限                     |
+| AGENTS.md/內存 | 可用                                            | 可用                             |
+
+## 工作區連線 {#workspace-connections}
+
+工作區連線允許應用程式共用相同的提供者帳戶（Slack、GitHub、HubSpot 等），而無需重複憑證。連線在 SQL 中紀錄提供者身分、帳戶標籤、狀態、範圍、應用程式授權和憑證引用。秘密保留在憑證存儲中；連線僅指向憑證金鑰名稱，例如 `SLACK_BOT_TOKEN`。
+
+請參閱 [Workspace Connections](/docs/workspace-connections) 了解快速入門、connection/grant/credentialRef API 以及具體的 Slack、HubSpot 和 GitHub 範例。
+
+---
+
+# 參考
+
+## 資源API {#resource-api}
+
+可以通過伺服器程式碼、actions 或 REST API 管理資源。
+
+### 伺服器API {#server-api}
+
+自動安裝REST端點：
+
+| 方法     | 端點                                          | 描述                 |
+| -------- | --------------------------------------------- | -------------------- |
+| `GET`    | `/_agent-native/resources?scope=all`          | 列出資源             |
+| `GET`    | `/_agent-native/resources?scope=workspace`    | 列出繼承的工作區資源 |
+| `GET`    | `/_agent-native/resources/tree?scope=all`     | 獲取資料夾樹         |
+| `GET`    | `/_agent-native/resources/effective?path=...` | 顯示有效繼承堆堆疊   |
+| `POST`   | `/_agent-native/resources`                    | 建立資源             |
+| `GET`    | `/_agent-native/resources/:id`                | 獲取包含內容的資源   |
+| `PUT`    | `/_agent-native/resources/:id`                | 更新資源             |
+| `DELETE` | `/_agent-native/resources/:id`                | 刪除資源             |
+| `POST`   | `/_agent-native/resources/upload`             | 上傳檔案作為資源     |
+
+### 動作API {#script-api}
+
+代理使用這些內置的 actions。您也可以從您自己的 actions 中調用它們：
+
+```bash
+# 列出所有資源
+pnpm action resource-list --scope all
+
+# 閱讀資源
+pnpm action resource-read --path "skills/my-skill/SKILL.md"
+
+# 讀取由 Dispatch 管理的繼承工作區上下文
+pnpm action resource-read --scope workspace --path "context/brand.md"
+
+# Show workspace -> organization/app -> personal precedence for a path
+pnpm action resource-effective --path "context/brand.md"
+
+# 寫一個資源
+pnpm action resource-write --path "notes/meeting.md" --content "# 會議紀錄...”
+
+# 刪除資源
+pnpm action resource-delete --path "notes/old.md"
+```

package/corpus/core/docs/content/locales/zh-TW/writing-agent-instructions.md

@@ -0,0 +1,173 @@
+---
+title: "撰寫代理說明和技能"
+description: "如何為代理原生應用或範本編寫出色的代理指令：AGENTS.md、skills 和工具說明。"
+---
+
+# 撰寫代理說明和技能
+
+代理在代理本機應用程式中的行為僅與您給出的說明一樣好。三個表面承載該指導：`AGENTS.md`（地圖）、skills（深入研究）和操作/工具描述（代理如何選取正確的工具）。寫下每一篇都是為了快速檢索，而不是為了散文。
+
+```an-diagram title="三個創作表面 + 一個執行時表面" summary="AGENTS.md 和工具描述每回合都會載入；按需載入技能； application_state 由您的 UI 實時編寫。"
+{
+  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">每一輪</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">地圖：用途、核心規則、狀態鍵、action + skills 索引</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">每一輪</span><strong>工具描述</strong><small class=\"diagram-muted\">驅動工具選取 — 每個工具一句精確說明</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">按需</span><strong>技能</strong><small class=\"diagram-muted\">深度指南，在描述匹配時載入</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">由你的 UI 寫入：導覽、選取、焦點</small></div></div>",
+  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+## 保持 AGENTS.md 小且可瀏覽 {#small-agents-md}
+
+`AGENTS.md` 作為方向載入。它應該是讓代理正確行動的最小事物，所有內容都深入到 skills 中。瞄準這些部分而不是其他部分：
+
+- **目的行** — 一句話介紹應用程式是什么以及主要工作流程。
+- **核心規則** - 必須始終保持的少數不變數（SQL 中的資料，操作通過 actions，AI 通過代理聊天，模式更改是附加的）。簡短、指令式的專案符號。
+- **應用程式狀態鍵** — 代理讀取 `navigation`/選取/焦點鍵以了解使用者正在檢視的內容及其形狀。
+- **操作表** — 操作名稱與目的的緊湊表。
+- **技能 索引** — 存在的 skills 列表以及何時讀取每個 skills。
+
+如果一個部分超出了螢幕，那么它就屬於一項技能。 `AGENTS.md` 回答“這個應用程式是什么以及我能做什么”，而不是“我到底如何做困難的事情。”
+
+```markdown
+# 專案應用程式
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## 核心規則
+
+- Data lives in 通過 Drizzle 使用 SQL. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## 應用狀態
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## 行動
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## 技能
+
+- `project-imports` — read before importing legacy CSV exports.
+- `sharing` — read before exposing a project to other users.
+```
+
+## 單來源AGENTS.md {#single-source}
+
+保留一個規範指令檔案：`AGENTS.md`。如果用戶端需要 `CLAUDE.md`，請將其設為 `AGENTS.md` 的符號連結，而不是第二個副本。兩個手工維護的檔案發生了偏差，特工最終得出了相互矛盾的規則。真相的一個來源，在需要的地方連結。
+
+## SKILL.md frontmatter 必須說 AND 時的內容 {#skill-frontmatter}
+
+`description` 是代理在決定是否讀取技能時唯一看到的東西。它必須回答兩個問題：技能涵蓋什么以及何時觸發它。僅描述主題的描述不會觸發。
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+```
+
+- 以功能開頭，然後新增明確的 **“何時使用…”** 子句。
+- 稍微咄咄逼人——過度觸發會打敗永遠不會載入的技能。
+- 將其控制在約 40 個字以內；它會載入到每次對話的上下文中。
+
+## 漸進式披露 {#progressive-disclosure}
+
+將 `SKILL.md` 編寫為精益的必知層：規則、如何做、該做/不該做的列表以及指針。將長範例、詳盡的欄位引用、API 怪癖和邊缘情況表推送到 `references/` 檔案中，代理僅在需要時讀取它們。
+
+```text
+.agents/skills/project-imports/
+├── SKILL.md            # 規則 + 快樂路徑 + do/don't
+└── references/
+    └── csv-format.md   # 全列規範、編碼、邊缘情況
+```
+
+這使始終載入的表面保持較小，並允許深度縮放而不會使上下文膨脹。完整技能格式請參見 [技能 Guide](/docs/skills-guide)。
+
+## 編寫面向行動的表格 {#action-tables}
+
+代理掃描表格的速度比掃描散文的速度快。優先使用名稱表而不是描述每個操作的段落。這同樣適用於狀態鍵、欄位型別和任何可枚舉集。表格可瀏覽、可比較，並且在新增操作時易於保持同步。
+
+## 編寫清晰的工具說明 {#tool-descriptions}
+
+操作描述是工具描述——它們驅動工具選取。讓每一個句子成為一個精確的、單一目的的句子：
+
+- 說明它的作用和返回什么，而不是它的實現方式。
+- 描述其 `.describe()` 中的每個參數，以便代理正確填寫。
+- 每個操作都有一個責任。如果描述需要“而且還……”，請將其拆分。
+- 標記唯讀 actions（`readOnly: true` 或 `http: { method: "GET" }`），以便客服人員知道他們可以安全地自由呼叫。
+
+```ts
+defineAction({
+  description: "Create a project. Returns the new project id and title.",
+  schema: z.object({
+    title: z.string().min(1).describe("Project title shown in the sidebar"),
+  }),
+  // ...
+});
+```
+
+## 技能 vs actions {#skills-vs-actions}
+
+技能 和 actions 是互補的。技能是代理閱讀的指南；一個
+action 是代理可以執行的程式碼。
+
+| 需要                                       | 使用             |
+| ------------------------------------------ | ---------------- |
+| 客服人員需要遵循工作流程、政策、清單或準則 | **技能**         |
+| 代理需要範例、參考資料或特定領域的規則     | **技能**         |
+| 代理需要讀取或寫入應用資料                 | **操作**         |
+| 代理需要調用外部API或執行審批              | **操作**         |
+| 代理以錯誤的方式調用正確的操作             | 提高**技能**     |
+| 代理無法可靠地調用操作                     | 改進**操作**     |
+| 代理選取了錯誤的工具                       | 改進**動作描述** |
+
+大多數實際功能都會同時使用這兩種功能：技能解釋如何完成工作，並且
+該操作提供型別化操作。例如，`invoice-review`技能
+可以解釋審核政策和升級規則，同時`list-invoices`，
+`flag-invoice` 和 `approve-invoice` actions 執行實際的讀寫操作。
+
+## 烘焙反加工並在完成前進行驗證 {#anti-fabrication}
+
+應用說明應將誠實和驗證作為預設行為：
+
+- **切勿捏造。**如果未找到資料或操作失敗，請說出來並恢復 - 不要發明結果或聲稱成功。在報告之前通過操作或查詢讀取實際值。
+- **在聲明完成之前進行驗證。**更改後，通過讀回確認（重新查詢行，通過 `view-screen` 重新讀取螢幕），而不是假設寫入有效。
+- **恢復，不要放棄。** 對於可恢復的錯誤（失敗的查詢、短暫的提取），重試或修複輸入而不是放棄工作。將其與反捏造規則分開——不要將“不要編造事情”與“在第一個錯誤處停止”混為一談。
+
+將這些作為 `AGENTS.md` 中的核心規則，以便它們適用於每個回合。
+
+## 代理看到的四個表面 {#four-surfaces}
+
+您編寫的每一條指導都會落在四個表面之一上。知道使用哪個表面可以防止重複和錯位細節：
+
+| 表面                      | 誰寫的                   | 載入時                       | 那裡屬於什么                                    |
+| ------------------------- | ------------------------ | ---------------------------- | ----------------------------------------------- |
+| `AGENTS.md`說明           | 您（開發者）             | 每個回合，作為方向           | 目的、核心規則、狀態鍵、動作索引、skills索引    |
+| 技能 (`SKILL.md`)         | 您（開發者）             | 當客服人員認為技能相關時按需 | 特定模式的分步操作方法，列出了該做/不該做的事情 |
+| 操作描述（工具）          | 您（開發者）             | 每回合，如工具列表           | 操作的作用、返回內容、參數語義                  |
+| `application_state`上下文 | 您的 UI 程式碼（執行時） | 每回合，作為實時應用狀態     | 目前導覽、選取、聚焦物件、URL                   |
+
+**快速診斷：**
+
+- “即使開啟一條紀錄，代理也會不斷詢問要操作哪條紀錄” → 修複：將目前專案 ID 從 UI 寫入 `application_state`（`navigation` 金鑰）。這是 `application_state` 差距，而不是技能差距。
+- “代理調用了錯誤的操作或誤用了參數”→修複：改進操作在參數上的`description`和`.describe()`。這是工具描述修複，而不是技能。
+
+## 什么去哪裡 {#what-goes-where}
+
+- **AGENTS.md** — 適用於整個應用程式，每回合：目的、核心規則、狀態鍵、操作索引、skills 索引。
+- **技能** — 針對特定模式的可重用操作方法，按需載入。適用於在該應用中工作的每個人。
+- **內存 (`memory/MEMORY.md`)** — 每個使用者的偏好和更正，而非編寫的指導。
+
+## 下一步是什么 {#whats-next}
+
+- [技能 Guide](/docs/skills-guide) — 技能檔案格式、框架 skills 和應用程式支持的 skills。
+- [Creating Templates](/docs/creating-templates) — `AGENTS.md` 和 skills 如何融入可交付範本。
+- [The four-area checklist](/docs/key-concepts#four-area-checklist) - 每個特征都必須滿足的四區域模型。

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.79.2",
+  "version": "0.79.6",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -179,7 +179,7 @@
     "provenance": true
   },
   "scripts": {
-    "build": "tsgo && tsgo -p tsconfig.cli.json && node scripts/finalize-build.mjs",
+    "build": "tsgo && tsgo -p tsconfig.cli.json && node scripts/finalize-build.mjs && node scripts/check-dist-imports.mjs",
     "dev": "tsgo --watch",
     "typecheck": "tsgo --noEmit",
     "test": "vitest --run src",

package/corpus/core/scripts/check-dist-imports.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Postbuild guard: actually import the SSR-critical entry points under Node's
+// strict ESM resolver. This reproduces the failure class where compiled client
+// code reaches into copy-only template scaffolding (src/templates ships verbatim
+// .ts, so its .js never exists in dist). Such imports work under Vite's
+// on-the-fly client transform but throw ERR_MODULE_NOT_FOUND during SSR.
+//
+// A static scan can't tell a real broken import from a JSDoc example, a codegen
+// string literal, or a dynamic import of a consumer-generated file, so we run
+// the real resolver instead.
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const ENTRY_POINTS = ["dist/client/i18n.js"];
+
+let failed = false;
+for (const entry of ENTRY_POINTS) {
+  if (!existsSync(entry)) {
+    console.error(`[check-dist-imports] missing entry ${entry} — build first`);
+    failed = true;
+    continue;
+  }
+  try {
+    await import(pathToFileURL(entry).href);
+  } catch (error) {
+    failed = true;
+    console.error(`[check-dist-imports] failed to import ${entry}:`);
+    console.error(`  ${error?.message ?? error}`);
+  }
+}
+
+if (failed) process.exit(1);
+console.log(
+  `[check-dist-imports] SSR entry points import cleanly (${ENTRY_POINTS.join(", ")})`,
+);

package/corpus/core/src/client/ErrorBoundary.tsx

@@ -54,6 +54,16 @@ const errorCopy: Record<
     goHome: "回到首页",
     reload: "重新加载",
   },
+  "zh-TW": {
+    loadingLatest: "正在載入最新版本...",
+    genericTitle: "發生錯誤",
+    genericDetails: "發生未預期的錯誤。",
+    notFoundTitle: "找不到頁面",
+    notFoundDetails: "找不到這個頁面。",
+    statusTitle: (status) => `${status} 錯誤`,
+    goHome: "回首頁",
+    reload: "重新載入",
+  },
   "es-ES": {
     loadingLatest: "Cargando la versión más reciente...",
     genericTitle: "Algo salió mal",

package/corpus/core/src/client/FeedbackButton.tsx

@@ -69,6 +69,18 @@ const FEEDBACK_COPY: Record<
     sendError: "无法发送反馈",
     keyboardHint: "{{shortcut}}+Enter 发送",
   },
+  "zh-TW": {
+    label: "意見回饋",
+    placeholder: "哪些地方好用、哪裡壞了，或你想改什麼？",
+    submit: "送出意見回饋",
+    submitting: "正在送出...",
+    success: "感謝你的意見回饋。",
+    loadError: "無法載入意見回饋表單",
+    invalidUrl: "意見回饋 URL 無效",
+    emptyError: "請先輸入內容",
+    sendError: "無法送出意見回饋",
+    keyboardHint: "{{shortcut}}+Enter 送出",
+  },
   "es-ES": {
     label: "Comentarios",
     placeholder: "¿Qué funciona, qué falla o qué cambiarías?",

package/corpus/core/src/client/blocks/library/block-copy.ts

@@ -103,6 +103,38 @@ const BLOCK_COPY: Record<
     lineAnnotation: "第 {{line}} 行注释",
     hiddenLinesExpand: "{{count}} 行 - 点击展开",
   },
+  "zh-TW": {
+    added: "已新增",
+    modified: "已修改",
+    removed: "已移除",
+    renamed: "已重新命名",
+    deprecated: "已棄用",
+    requiresAuthentication: "需要驗證",
+    auth: "驗證",
+    parameters: "參數",
+    name: "名稱",
+    in: "位置",
+    type: "型別",
+    requiredColumn: "必填",
+    description: "描述",
+    required: "必填",
+    optional: "選填",
+    requestBody: "請求本文",
+    responses: "回應",
+    expandDiagram: "展開圖表",
+    loadingDiagram: "正在載入圖表...",
+    couldNotRenderDiagram: "無法呈現圖表",
+    addDiagramDefinition: "新增圖表定義以呈現。",
+    switchToCleanDiagrams: "切換到簡潔圖表",
+    switchToHandDrawnDiagrams: "切換到手繪圖表",
+    cleanDiagramsSwitch: "簡潔圖表 - 切換到手繪",
+    handDrawnDiagramsSwitch: "手繪圖表 - 切換到簡潔",
+    clean: "簡潔",
+    sketchy: "手繪",
+    switchVisualStyle: "切換到 {{style}} 視覺樣式",
+    lineAnnotation: "第 {{line}} 行註解",
+    hiddenLinesExpand: "{{count}} 行 - 點擊展開",
+  },
   "es-ES": {
     added: "Añadido",
     modified: "Modificado",