@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/zh-CN/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="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
+{
+  "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 workspace</span><small class=\"diagram-muted\">rows in one SQL database</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\">one codebase, many users, scoped <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="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
+{
+  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from 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\">Organization / app</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": "No restart, no redeploy. `AGENTS.md` is read at the start of every turn, so an edit you save now changes the agent's behavior on the very next message." }
+```
+
+**后续步骤（当您需要时）：**
+
+- **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              # what the company does, ICP, products, links
+context/brand.md                # voice, visual identity, spelling, forbidden usage
+context/messaging.md            # positioning, value props, proof points, objections
+instructions/guardrails.md      # compliance, escalation, and approval rules
+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 -->
+
+# Brand
+
+- 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="The workspace resource model" summary="One resource shape backs every workspace file. The runtime keys it by path and scope and resolves the effective value on read."
+{
+  "entities": [
+    {
+      "id": "resource",
+      "name": "workspace resource",
+      "note": "A single file in a user's workspace — instructions, skill, memory, agent, MCP config, or job.",
+      "fields": [
+        { "name": "path", "type": "string", "note": "Canonical path, e.g. AGENTS.md, skills/<slug>/SKILL.md" },
+        { "name": "scope", "type": "workspace | shared | personal", "note": "Which level this row lives at" },
+        { "name": "owner", "type": "string", "nullable": true, "note": "u:<email> for personal scope" },
+        { "name": "content", "type": "text", "note": "Markdown / JSON / YAML body" }
+      ]
+    }
+  ]
+}
+```
+
+## 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="A custom agent profile"
+{
+  "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# Role\n\nYou are a focused design agent.\n\n## Responsibilities\n\n- Review layouts and interaction flows\n- Suggest stronger visual direction\n- Be concise and opinionated",
+  "annotations": [
+    { "lines": "2", "label": "@mention handle", "note": "`name` is what appears in the `@`-dropdown and what the main agent delegates to." },
+    { "lines": "3-4", "label": "When to delegate", "note": "The `description` is what the orchestrator reads to decide this profile fits a task." },
+    { "lines": "5", "label": "Model", "note": "`inherit` reuses the main agent's model. Override only when the profile clearly needs a different one." },
+    { "lines": "6", "note": "`tools: inherit` for now — the field is reserved for future per-agent tool policies." }
+  ]
+}
+```
+
+推荐约定：
+
+- 将定制代理存储在`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
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill/SKILL.md"
+
+# Read inherited workspace context managed by 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"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+```

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

@@ -0,0 +1,173 @@
+---
+title: "撰写代理说明和Skills"
+description: "如何为代理原生应用或模板编写出色的代理指令：AGENTS.md、skills 和工具说明。"
+---
+
+# 撰写代理说明和Skills
+
+代理在代理本机应用程序中的行为仅与您给出的说明一样好。三个表面承载该指导：`AGENTS.md`（地图）、skills（深入研究）和操作/工具描述（代理如何选择正确的工具）。写下每一篇都是为了快速检索，而不是为了散文。
+
+```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
+{
+  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</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 列表以及何时读取每个 skills。
+
+如果一个部分超出了屏幕，那么它就属于一项技能。 `AGENTS.md` 回答“这个应用程序是什么以及我能做什么”，而不是“我到底如何做困难的事情。”
+
+```markdown
+# Projects App
+
+One workspace for projects, tasks, and notes. Agent and UI share the same SQL
+data and the same actions.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes.
+- All AI work goes through the agent chat; never call an LLM inline.
+- Schema changes are additive only.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                     |
+| ---------------- | --------------------------- |
+| `list-projects`  | List accessible projects    |
+| `create-project` | Create a project            |
+| `update-project` | Rename or archive a project |
+
+## Skills
+
+- `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            # rule + happy path + do/don't
+└── references/
+    └── csv-format.md   # full column spec, encodings, edge cases
+```
+
+这使始终加载的表面保持较小，并允许深度缩放而不会使上下文膨胀。完整技能格式请参见 [Skills 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"),
+  }),
+  // ...
+});
+```
+
+## Skills vs actions {#skills-vs-actions}
+
+Skills 和 actions 是互补的。技能是代理阅读的指南；一个
+action 是代理可以运行的代码。
+
+| 需要                                       | 使用             |
+| ------------------------------------------ | ---------------- |
+| 客服人员需要遵循工作流程、政策、清单或准则 | **技能**         |
+| 代理需要示例、参考资料或特定领域的规则     | **技能**         |
+| 代理需要读取或写入应用数据                 | **操作**         |
+| 代理需要调用外部API或执行审批              | **操作**         |
+| 代理以错误的方式调用正确的操作             | 提高**技能**     |
+| 代理无法可靠地调用操作                     | 改进**操作**     |
+| 代理选择了错误的工具                       | 改进**动作描述** |
+
+大多数实际功能都会同时使用这两种功能：技能解释如何完成任务，并且
+该操作提供类型化操作。例如，`invoice-review`技能
+可以解释审核政策和升级规则，同时`list-invoices`，
+`flag-invoice` 和 `approve-invoice` actions 执行实际的读写操作。
+
+## 烘焙反加工并在完成前进行验证 {#anti-fabrication}
+
+应用说明应将诚实和验证作为默认行为：
+
+- **切勿捏造。**如果未找到数据或操作失败，请说出来并恢复 - 不要发明结果或声称成功。在报告之前通过操作或查询读取实际值。
+- **在声明完成之前进行验证。**更改后，通过读回确认（重新查询行，通过 `view-screen` 重新读取屏幕），而不是假设写入有效。
+- **恢复，不要放弃。** 对于可恢复的错误（失败的查询、短暂的提取），重试或修复输入而不是放弃任务。将其与反捏造规则分开——不要将“不要编造事情”与“在第一个错误处停止”混为一谈。
+
+将这些作为 `AGENTS.md` 中的核心规则，以便它们适用于每个回合。
+
+## 代理看到的四个表面 {#four-surfaces}
+
+您编写的每一条指导都会落在四个表面之一上。知道使用哪个表面可以防止重复和错位细节：
+
+| 表面                      | 谁写的                 | 加载时                       | 那里属于什么                                    |
+| ------------------------- | ---------------------- | ---------------------------- | ----------------------------------------------- |
+| `AGENTS.md`说明           | 您（开发者）           | 每个回合，作为方向           | 目的、核心规则、状态键、动作索引、skills索引    |
+| Skills (`SKILL.md`)       | 您（开发者）           | 当客服人员认为技能相关时按需 | 特定模式的分步操作方法，列出了该做/不该做的事情 |
+| 操作描述（工具）          | 您（开发者）           | 每回合，如工具列表           | 操作的作用、返回内容、参数语义                  |
+| `application_state`上下文 | 您的 UI 代码（运行时） | 每回合，作为实时应用状态     | 当前导航、选择、聚焦对象、URL                   |
+
+**快速诊断：**
+
+- “即使打开一条记录，代理也会不断询问要操作哪条记录” → 修复：将当前项目 ID 从 UI 写入 `application_state`（`navigation` 密钥）。这是 `application_state` 差距，而不是技能差距。
+- “代理调用了错误的操作或误用了参数”→修复：改进操作在参数上的`description`和`.describe()`。这是工具描述修复，而不是技能。
+
+## 什么去哪里 {#what-goes-where}
+
+- **AGENTS.md** — 适用于整个应用程序，每回合：目的、核心规则、状态键、操作索引、skills 索引。
+- **Skills** — 针对特定模式的可重用操作方法，按需加载。适用于在该应用中工作的每个人。
+- **内存 (`memory/MEMORY.md`)** — 每个用户的偏好和更正，而非编写的指导。
+
+## 下一步是什么 {#whats-next}
+
+- [Skills 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.76.5",
+  "version": "0.76.6",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/agent/run-store.ts

@@ -517,6 +517,19 @@ export const RUN_DIAG_STAGE = {
    * recovered by running the turn inline. The run still completes for the user.
    */
   foregroundInlineRecovery: "foreground_inline_recovery",
+  /**
+   * bg-fn wrapper self-diagnostics (the generated `server-agent-background`
+   * wrapper reports these via the `_bg-diag` route, since its own logs are
+   * unreadable). `bgfnWrapperEntered`: the wrapper actually ran in the bg-fn
+   * isolate. `bgfnHandoffReturned`: the in-isolate handoff to the Nitro handler
+   * RETURNED — detail carries the HTTP status (404=route mismatch, 401=auth,
+   * 2xx/5xx=route ran). `bgfnWrapperThrew`: the import/handoff THREW before
+   * returning — detail carries the error. Read in the pre-grace window before
+   * the circuit-breaker overwrites diag_stage.
+   */
+  bgfnWrapperEntered: "bgfn_wrapper_entered",
+  bgfnHandoffReturned: "bgfn_handoff_returned",
+  bgfnWrapperThrew: "bgfn_wrapper_threw",
 } as const;
 
 export type RunDiagStage = (typeof RUN_DIAG_STAGE)[keyof typeof RUN_DIAG_STAGE];