> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Devin Local 自定义设置

> 通过规则、技能、插件、MCP 服务器和钩子扩展 Devin Desktop 中的 Devin 本地智能体，并查看每个会话已加载的内容。

Devin Local 提供多种方式，用于自定义智能体在你项目中的工作方式。可参考下表选择合适的方式：

| 功能 | 作用 | 激活方式 | 适用场景 |
| - | - | - | - |
| **[规则](#rules)** | 告诉智能体*应该如何行事* (例如“使用 bun，而不是 npm”) | 始终启用，或通过 `trigger` 前置元数据触发 | 编码规范、风格指南、项目约束 |
| **[技能](#skills)** | 与辅助文件 (脚本、模板) 打包在一起的多步骤流程 | 由模型在相关时调用，或由你手动调用 | 智能体需要参考文件的复杂任务 |
| **[插件](#plugins)** | 可安装的文件包，包含技能、规则、钩子、MCP 服务器和子 Agent | 只需安装一次，即可在多个项目和团队间共享 | 分发一整套自定义设置 |
| **[MCP 服务器](#mcp-servers)** | 为智能体提供来自外部服务的工具 | 按项目或按用户配置 | 问题跟踪系统、设计工具、内部 API |
| **[钩子](#hooks)** | 在智能体生命周期事件发生时运行 Shell 命令或提示 | 按项目或按用户配置 | 策略强制执行、日志记录、格式化工具、通知 |

由于 Devin Local 与 [Devin CLI](https://cli.devin.ai) 共享同一智能体运行框架，所有自定义设置均沿用 Devin CLI 的格式和自动发现机制，为其中一方编写的自定义设置在另一方中同样适用。

如需在 Desktop 和 Cloud 中复用其他智能体的项目规则和工作流程，请先使用[迁移提示](https://docs.devin.ai/zh/onboard-devin/migrate-from-other-agents.md)。

## Customize

Agents 窗口中的 **Customize** 页面包含 **插件**、**技能**、**MCPs**、**钩子**、**规则** 和 **子智能体** 选项卡。每个选项卡会列出智能体已加载的内容，以及您的代码仓库、组织和账户中可用的内容。

你可以点击智能体 sidebar 中的 **Customize** 打开该页面。

## 规则

规则是持久生效的指示，用于规范智能体在您的项目中的行为方式。规则会在每次会话开始时注入智能体的上下文，从而确保智能体在整个团队中的行为保持一致。

规则的常见用途包括编码标准、架构指南、首选库、测试规范以及项目特有的约束。

### AGENTS.md

添加规则最简单的方式，是在您的项目根目录下放置一个 `AGENTS.md` 文件。该文件使用纯 Markdown 编写，无需前置元数据：

```markdown theme={null}
# 项目规则

- 所有新文件都使用 TypeScript
- 遵循 src/components/ 中的现有模式
- commit 前务必运行 `npm run lint`
- 使用 pnpm，不要使用 npm 或 yarn
```

`AGENTS.md`、`AGENTS.local.md` (用于存放不纳入版本控制的个人规则) 和 `AGENT.md` 都会作为始终生效的规则被读取。智能体会读取工作区根目录，以及从工作区根目录到其当前工作目录之间每一级目录中的这些文件，因此放在子目录中的 `AGENTS.md` 可以为该目录提供专门的指导。

### 规则文件

如需更精细的控制，可将规则放在 `.devin/rules/*.md` 中，每个文件一条规则。每个文件都可以通过 `trigger` 前置元数据声明其适用时机：

```markdown theme={null}
---
trigger: glob
globs: "**/*.test.ts"
---

所有测试文件都必须使用 `describe`/`it` 块，并对外部 API 调用进行 mock。
```

| `trigger:` 值 | 规则何时传递给智能体 |
| - | - |
| `always_on` | 每个会话 |
| `glob` | 智能体处理与 `globs` 匹配的文件时 |
| `model_decision` | 智能体判断该规则的描述与当前任务相关时 |
| `manual` | 仅在你手动调用时 |

`.devin/global_rules.md` 是一个始终生效的单文件。将相同的文件放在你的主目录中 (`~/.devin/rules/*.md`、`~/.devin/global_rules.md`) ，即可应用于所有项目。

默认会导入旧版的 `.windsurf/rules/*.md`、`.windsurf/global_rules.md` 和 `.windsurfrules` 文件。`.devin/rules/` 和 `.windsurf/rules/` 中的规则文件都会加载；若两个 `global_rules.md` 文件同时存在，则仅加载 `.devin/global_rules.md`。完整的文件列表、导入设置以及来自其他工具的规则，请参阅[规则和 AGENTS.md](https://docs.devin.ai/zh/cli/extensibility/rules.md)。

### 最佳实践

* 规则应简短且具体。规则会包含在每个会话的上下文中，因此每条消息都会为此消耗令牌。
* 对于智能体只是偶尔需要的内容，优先使用技能；再通过规则指引智能体在特定场景下使用相应的技能。
* 使用项目符号、编号列表和 Markdown 标题来组织规则，这比一大段文字更便于遵循。
* 不要编写“编写优质代码”这类泛泛的规则。

## 技能

最困难的工程任务往往不只需要好的提示，还可能需要参考脚本、模板、检查清单以及其他辅助文件。借助技能，你可以将这些内容打包到文件夹中，供智能体调用。

技能采用**渐进式披露**机制：默认情况下，模型只能看到技能的 `name` 和 `description`。只有当智能体决定调用该技能，或由你手动调用时，才会加载完整的 `SKILL.md` 内容和辅助文件。这样即使定义了大量技能，你的上下文窗口也能保持精简。

### 创建技能

创建一个包含 `SKILL.md` 文件的目录，并在该文件的 YAML 前置元数据中填写技能的名称和描述：

```markdown theme={null}
---
name: deploy-to-production
description: 指导生产环境部署流程，并执行安全检查
---

## 部署前检查清单
1. 运行所有测试
2. 检查是否有未提交的更改
3. 验证环境变量

## 部署步骤
按照以下步骤安全部署……
```

* **name**：技能的唯一标识符 (仅限小写字母、数字和连字符) ，用于调用该技能。
* **description**：向模型展示的简要说明，帮助模型判断何时调用该技能。请具体说明该技能的用途及适用场景。

将辅助文件放在技能文件夹中，与 `SKILL.md` 并列存放。调用该技能时，智能体即可使用这些文件：

```
.devin/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml
```

### 调用技能

当你的请求与某个技能的描述相匹配时，智能体会自动调用该技能并按照其指示执行。你也可以使用 `/skill-name` 按名称调用技能，确保该技能一定会被使用。

### 技能作用域

| 作用域 | 位置 | 可用范围 |
| - | - | - |
| Workspace | `.devin/skills/<name>/` (也会读取 `.agents/skills/` 和旧版的 `.windsurf/skills/`) | 仅限当前 workspace。随您的代码仓库一起提交。 |
| 全局 | `~/.config/devin/skills/<name>/` (也会读取 `~/.agents/skills/`) | 你机器上的所有工作区。不会被提交。 |
| Plugin | 位于已安装的 [plugin](#plugins) 中 | 凡是安装了该 plugin 的地方均可用。 |

有关技能触发条件、权限和第三方技能，请参阅 [Devin CLI 技能文档](https://docs.devin.ai/zh/cli/extensibility/skills/overview.md)；有关编写指导，请参阅[创建技能](https://docs.devin.ai/zh/cli/extensibility/skills/creating-skills.md)。

## plugin

plugin 是可安装的文件包，可为智能体提供技能、规则、钩子、MCP 服务器和子 Agent。你可以从 GitHub 代码仓库、git URL、代码仓库的子文件夹或本地文件夹安装 plugin，安装后其技能会以 `/<plugin>:<skill>` 命令的形式提供。有关 plugin 格式、`devin plugins` 命令及治理的说明，请参阅[plugin](https://docs.devin.ai/zh/cli/extensibility/plugins/overview.md)。

> [!WARNING]
>
> 此处的**plugin**特指 Devin *智能体*plugin。它们与 [Windsurf plugin](https://docs.devin.ai/zh/windsurf/plugins/getting-started.md) (用于在 JetBrains、VS Code 等编辑器中使用 Devin) 无关，也与你在 Devin Desktop 中安装的[编辑器扩展](https://docs.devin.ai/zh/desktop/recommended-extensions.md)无关——后两者扩展的是 IDE，而非智能体。

## MCP 服务器

**MCP (模型上下文协议，Model Context Protocol) ** 是一种协议，可让智能体使用来自外部服务 (如 GitHub、数据库和问题跟踪系统) 的工具。如需了解更多信息，请参阅 [MCP 官方文档](https://modelcontextprotocol.io/)。

### 安装 MCP 服务器

在 Agents 窗口中打开 **Customize** 页面，然后点击 **MCPs**。通过顶部的 **Install MCPs for** 选择器选择作用域，例如 **此计算机**。

* **此计算机** 列出你的本地智能体为窗口中已打开的文件夹所加载的服务器。你可以启用或停用某个服务器、打开其配置文件，或刷新列表。
* **可用** 列出你的 MCP 注册表中的服务器。点击服务器对应的 **Install** 即可添加。

企业管理员可在团队设置的 **MCP & ACP** 下管理注册表。**MCP 注册表** 选项卡中有一个开关，开启后，除 MCP 允许列表中的服务器外，与注册表条目匹配的服务器也会被允许；另有一个 **Registry** 设置项 (**Configure**) ，用于配置注册表 URL。配置了多个注册表时，Devin Desktop 会取所有注册表的并集。自定义注册表必须遵循[官方 MCP 注册表 schema](https://modelcontextprotocol.io/)。

### 配置

MCP 服务器通过你本机上的[配置文件](https://docs.devin.ai/zh/cli/extensibility/mcp/configuration.md)进行配置。文件位置取决于作用域：

| 作用域 | 位置 | 是否与团队共享？ |
| - | - | - |
| 项目 | `.devin/mcp_config.json` | 是 (已提交到版本控制) |
| 本地覆盖设置 | `.devin/mcp_config.local.json` | 否 (已加入 gitignore) |
| 用户 | `~/.config/devin/mcp_config.json` | 否 |

Devin Local 支持 `stdio`、`Streamable HTTP` 和 `SSE` 三种传输方式，且均支持 OAuth。

### 权限

默认情况下，智能体在调用任何 MCP 工具前都会请求批准。如需了解如何允许某个工具或服务器，以及 Admin 如何将受信任的集成设为默认允许，请参阅 [MCP 权限](https://docs.devin.ai/zh/desktop/devin-local/permissions.md#mcp-permissions)。

### 重新进行身份验证

服务器存储的 OAuth 凭据过期后，该服务器会显示 **需要身份验证** 状态。此状态会显示在 **此计算机** 列表、**可用** 卡片以及服务器详情页中。

点击 **身份验证** 即可清除已存储的凭据，并重新运行浏览器授权流程。

## 钩子

钩子会在智能体生命周期中的特定事件 (例如工具调用之前) 运行自定义逻辑。每个钩子可以是一条 Shell 命令，也可以是一个 LLM 提示。你可以使用钩子来强制执行策略、添加上下文、记录操作、修改权限，或与外部系统集成。

钩子可以在您的项目的 `.devin/hooks.v1.json` 中配置，也可以在用户级别配置。例如，以下钩子会在每条 Shell 命令执行前运行一个脚本，并可阻止该命令执行：

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}
```

当 workspace 以[受限模式](https://docs.devin.ai/zh/desktop/devin-local/overview.md#restricted-mode)打开时，钩子既不会加载，也不会运行。

有关钩子事件、配置格式、退出码及示例，请参阅[钩子](https://docs.devin.ai/zh/cli/extensibility/hooks/overview.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.