# 插件与工具

DotCraft 把 Agent 可调用的"动作"分成两类：**内置工具**（文件 / Shell / Web / 搜索 / Plan / Todo 等，DotCraft 自己实现）和**插件提供的能力**（dynamic tools + skills，由你或第三方分发）。MCP servers 提供的是插件之外的另一条工具来源。

> 插件 = 一组可分发、可启用、可移除的 skills + tools + 元数据。

## 内置工具

DotCraft 默认提供一组通用工具，覆盖大多数 coding agent 需求：

| 类别 | 代表工具 | 可由配置控制 |
|---|---|---|
| 文件 | `ReadFile` / `WriteFile` / `EditFile` / `GrepFiles` / `FindFiles` | `Tools.File.*`、黑名单、工作区边界 |
| Shell | `Exec` | `Tools.Shell.*`、超时、审批策略、沙箱 |
| Web | `WebSearch` / `WebFetch` | `Tools.Web.*`、搜索 provider、字符上限 |
| LSP | 内置 LSP 工具 | `Tools.Lsp.Enabled`（默认关闭） |
| Plan / Todo | `CreatePlan` / `UpdateTodos` / `TodoWrite` | 由 SubAgent role 策略控制 |

只想启用部分工具时，使用 `EnabledTools`：

```json
{
  "EnabledTools": ["ReadFile", "GrepFiles", "WebSearch"]
}
```

为空（默认）时启用所有内置工具。完整字段表见 [配置完整参考](../developing/configuration.md)。

## 安装与使用插件

DotCraft 插件用来把可复用的工作区能力打包成可安装扩展，一个插件可以提供：

| 内容 | 说明 |
|---|---|
| Dynamic tool | Agent 可调用的工具，可由本地 stdio 进程执行 |
| Skill | 随插件分发的 plugin-contained skill，启用时进入 skill 列表 |
| 元数据 | 名称、描述、开发者、分类、图标、默认 prompt、相关链接 |

插件内置的 skill 跟随插件生命周期：启用插件时可用，禁用或移除插件后不再进入 Agent 上下文。

### 在 Desktop 中安装

![Plugin page](https://github.com/DotHarness/resources/raw/master/dotcraft/plugins.png)

1. 打开 DotCraft
2. 进入 **Plugins / 插件** 页面
3. 搜索或浏览插件，打开详情页
4. 点击 **Install / 安装**
5. 安装完成后可点 **Try in chat / 在对话中试用**，或在新对话中直接描述你想完成的任务

### 启用、禁用与移除

| 操作 | 含义 |
|---|---|
| 安装 | 将插件加入当前工作区可用能力 |
| 启用 / 禁用 | 保留插件文件，控制是否进入 Agent 上下文 |
| 移除 | 从当前工作区移除插件；对 `.craft/plugins/<plugin-id>` 下的本地插件，会删除对应目录 |

插件管理页可批量启用或禁用已安装插件。

### 安装本地插件

开发或测试本地插件时，有两种方式：

```text
.craft/plugins/<plugin-id>/.craft-plugin/plugin.json
```

把 plugin root 复制到当前工作区 `.craft/plugins/<plugin-id>/` 后，打开 Plugins 页面点击 **Refresh / 刷新**。这种安装可以在 Desktop 的插件详情页移除，移除时会删除该插件目录。

也可以让 DotCraft 直接读取你正在维护的外部目录：

```json
{
  "Plugins": {
    "PluginRoots": ["./samples/plugins"]
  }
}
```

`Plugins.PluginRoots` 中的目录 Desktop 不会主动删除；需要移除时请从配置中移除对应 root 或在文件系统中自行管理。

### 验证插件

1. 在 Plugins 页面点击 **Refresh / 刷新**
2. 搜索插件名称或 ID
3. 打开详情页确认 tools、skills 和链接信息
4. 如果插件没有出现，查看页面上的 diagnostics 提示，通常包含 manifest 路径和错误原因

## 创建插件

最快方式是让内置 `$plugin-creator` 先搭好结构，再补充说明、工具逻辑和验证步骤。

如果只是给当前项目补充一段工作流，优先创建普通 skill。需要把 skills、dynamic tools、图标和安装页信息一起打包分发时，再创建 plugin。

### 用 plugin creator 起步

在对话中直接描述你想要的插件：

```text
$plugin-creator 创建一个名为 External Process Echo 的插件，包含一个 skill 和一个外部进程 tool。
```

也可以把运行方式、语言和验证方式一起说清楚：

```text
$plugin-creator 创建一个本地插件，用 Python 进程提供 EchoText dynamic tool，并生成安装验证说明。
```

`plugin-creator` 会生成 DotCraft 插件目录、`.craft-plugin/plugin.json`、plugin-contained skill 以及可选的 process-backed dynamic tool scaffold。生成后通常只需要：

1. 替换 TODO 和示例文案
2. 实现或调整 tool 进程逻辑
3. 把插件安装到本地并在 Plugins 页面刷新验证

### 插件结构

DotCraft 使用 `.craft-plugin/plugin.json` 作为插件入口：

```text
my-plugin/
  .craft-plugin/
    plugin.json
  skills/
    my-skill/
      SKILL.md
  tools/
    tool_process.py
```

DotCraft v1 支持两类贡献：

| 内容 | 说明 |
|---|---|
| `skills` | 随插件分发的 DotCraft / Codex 兼容 skills |
| `tools` | Agent 可调用的 DotCraft dynamic tools，可由本地 stdio 进程执行 |

### 最小 manifest

一般不需要手写完整 manifest，了解基本结构在排查或高级定制时即可：

```json
{
  "schemaVersion": 1,
  "id": "my-plugin",
  "version": "0.1.0",
  "displayName": "My Plugin",
  "description": "Package reusable DotCraft capabilities.",
  "skills": "./skills/",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Reusable workflow for DotCraft",
    "developerName": "Your team",
    "category": "Coding"
  }
}
```

带外部进程 dynamic tool 的插件还会包含 `tools` 和 `processes`。建议让 `plugin-creator` 生成这部分结构，再按业务修改。

### 高级参考

需要处理这些高级内容时再查完整规格：

- process-backed dynamic tool 的 JSON-RPC 协议
- tool 的 `approval` 元数据
- manifest 路径规则
- 完整字段和 schema

参考位置：

- `src/DotCraft.Core/Skills/BuiltIn/plugin-creator/references/plugin-json-spec.md`
- [Plugin Architecture Spec](https://github.com/DotHarness/dotcraft/blob/master/specs/plugin-architecture.md)

## MCP Servers

除了内置工具和插件 dynamic tool，DotCraft 也支持通过 MCP 协议接入外部工具：

```json
{
  "McpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  },
  "Tools": {
    "DeferredLoading": {
      "Strategy": "Auto",
      "DeferThreshold": 10
    }
  }
}
```

`Tools.DeferredLoading.Strategy = Auto` 时：

- `openai-responses` 协议下使用 Responses 原生 client-executed `tool_search`
- chat-completions / Anthropic 下使用模拟 `SearchTools`
- 工具数量达到 `DeferThreshold` 才延迟加载

完整字段见 [配置完整参考](../developing/configuration.md#mcp-与-lsp)。

## 安全与信任

安装插件会把新的 tools 和 skills 加入工作区能力范围。启用带 `process` backend 的插件后，DotCraft 可以启动插件 manifest 中声明的本地 stdio 进程来执行 dynamic tools。**只安装和启用你信任来源、代码和依赖的插件**。

- 插件 tool 调用仍会经过 DotCraft 的会话、审批和工具调用记录。
- 插件详情中的网站、隐私政策和服务条款链接用于帮助你确认插件来源和行为边界。
- 黑名单、工作区边界、沙箱等限制对插件 tools 同样生效。详见 [安全与沙箱](./security.md)。

## 相关入口

- [Skills 与自学习](./skills.md) — Skill 与 Plugin 的关系
- [可观测性](./observability.md) — 在 Dashboard 看插件 tool 调用与审批
- [安全与沙箱](./security.md) — 工具能力的全局约束
- [Plugin Architecture Spec](https://github.com/DotHarness/dotcraft/blob/master/specs/plugin-architecture.md)
