# 开发AI插件

这份教程专门讲一件事：

怎样在 BeikeShop 里，用一个插件给 AI 系统增加新功能。

这里的“AI 功能”，主要包括 4 类：

增加一个新的 AI 助手（Agent）
给某个助手增加新工具（Tool）
把插件能力挂到后台 AI 菜单和聊天场景里
增加对应权限，让后台角色可以控制谁能用

本文会直接结合当前项目里的真实代码来讲，重点参考这些文件：

beike/Ai/Support/AiPluginBootstrap.php
beike/Ai/Services/AiExtensionService.php
beike/Shop/Providers/PluginServiceProvider.php
beike/Ai/Support/AiUiConfig.php
plugins/AiArticleManager/Bootstrap.php
plugins/AiArticleManager/Agents/ArticleManagerAgent.php
plugins/AiArticleManager/Tools/Articles/*

# 1. 先理解这套机制是什么

先说结论：

插件扩展 AI，不是直接改核心 AI 文件，而是通过插件自己的 Bootstrap.php 注册进去。

也就是说：

核心 AI 系统先启动
插件再通过 boot() 把自己的 Agent、Tool、权限、菜单扩展进去

这样做的好处是：

不容易改坏主系统
插件可以独立安装、启用、停用
一个插件可以只扩展自己负责的业务

# 2. AI 插件是怎么自动生效的

# 2.1 插件启动入口

项目里插件启动逻辑在：

beike/Shop/Providers/PluginServiceProvider.php

关键逻辑是：

$className = "Plugin\\{$pluginCode}\\Bootstrap";
if (method_exists($className, 'boot')) {
    (new $className)->boot();
}

这段代码的意思很简单：

只要插件启用了
并且插件目录下有 Bootstrap.php
系统就会自动调用这个类的 boot()

所以你平时写 AI 插件时，不需要手动再去某个地方“注册一次”。

# 3. AI 插件最核心的基类

# 3.1 `AiPluginBootstrap`

文件：

beike/Ai/Support/AiPluginBootstrap.php

这个类的作用是：

规定 AI 插件该怎么接入系统。

它要求你实现 3 个方法：

abstract public function pluginCode(): string;
abstract public function registerAgents(AiExtensionService $ai): void;
abstract public function registerTools(AiExtensionService $ai): void;

另外还留了一个可选扩展点：

protected function registerHooks(): void {}

最终 boot() 会自动按这个顺序执行：

registerAgents()
registerTools()
registerHooks()

这个顺序很重要，因为通常是：

先注册 AI 助手
再注册工具
最后再补菜单、权限、场景说明

# 4. 一个 AI 插件通常长什么样

当前项目里已经有一个真实示例：

plugins/AiArticleManager/

目录结构大致是：

plugins/AiArticleManager/
├── Agents/
│   └── ArticleManagerAgent.php
├── Bootstrap.php
├── config.json
├── Migrations/
│   └── 2026_04_29_000000_add_ai_article_manager_permissions.php
└── Tools/
    ├── Articles/
    │   ├── ArticleCreateTool.php
    │   ├── ArticleDeleteTool.php
    │   ├── ArticleListTool.php
    │   └── ArticleUpdateTool.php
    └── Orders/
        └── OrderAnalyticsTool.php

你可以把它理解成：

Bootstrap.php：总入口，负责“告诉系统这个插件要加什么 AI 能力”
Agents/：放 AI 助手
Tools/：放 AI 可调用工具
Migrations/：放权限迁移等数据库改动
config.json：插件基本信息

# 5. 第一步：准备插件基础信息

# 5.1 `config.json`

文件：

plugins/AiArticleManager/config.json

这个文件不是 AI 专属，但插件要正常显示和安装，通常都需要它。

示例：

{
    "code": "ai_article_manager",
    "name": {
        "zh_cn": "AI文章管理助手",
        "en": "AI Article Manager"
    },
    "description": {
        "zh_cn": "为现有文章模块提供 AI 增删改查能力，并扩展 AI 菜单、快捷提问和权限。",
        "en": "Adds AI CRUD capabilities for existing articles with chat navigation, quick prompts, and permissions."
    },
    "type": "feature",
    "version": "v1.0.0"
}

这里最关键的是：

code：插件唯一标识
type：插件类型
name / description：后台展示用

# 6. 第二步：写插件 Bootstrap

# 6.1 最小骨架

你先建一个：

plugins/你的插件名/Bootstrap.php

最小写法：

<?php

namespace Plugin\YourPlugin;

use Beike\Ai\Services\AiExtensionService;
use Beike\Ai\Support\AiPluginBootstrap;

class Bootstrap extends AiPluginBootstrap
{
    public function pluginCode(): string
    {
        return 'your_plugin_code';
    }

    public function registerAgents(AiExtensionService $ai): void
    {
    }

    public function registerTools(AiExtensionService $ai): void
    {
    }

    protected function registerHooks(): void
    {
    }
}

这就是 AI 插件的主控制台。

# 7. 第三步：如果你要新增一个 AI 助手

# 7.1 写 Agent 类

以文章助手为例：

plugins/AiArticleManager/Agents/ArticleManagerAgent.php

它继承的是：

Beike\Ai\Agents\BaseAgent

一个最基本的 Agent 至少要说明：

它是谁
它负责什么
它的场景标识是什么
它推荐哪些快捷提问

关键方法：

public function getScene(): string
{
    return 'articles';
}

这个 scene 很重要，你可以把它理解成：

这个 AI 助手在系统里的唯一场景名。

后面菜单切换、场景配置、欢迎语、快捷提问，都会围绕这个名字走。

# 7.2 在 Bootstrap 里注册 Agent

public function registerAgents(AiExtensionService $ai): void
{
    $ai->registerPluginAgent(
        $this->pluginCode(),
        'articles',
        \Plugin\AiArticleManager\Agents\ArticleManagerAgent::class
    );
}

这段话的意思是：

这个插件叫 ai_article_manager
它新增了一个场景叫 articles
这个场景对应的类是 ArticleManagerAgent

# 7.3 第三步补充：怎么给“新增 Agent”写提示词文件

这一节非常重要。

很多人会以为：

Agent 只能在代码里写死 instructions()
或者提示词文件只能放到核心目录 prompts/agents

现在这个项目不是这样。

当前核心 AI 模块已经支持：

Agent 通过 $promptFile 指定提示词文件
这个文件既可以放核心目录，也可以直接放到插件目录

对应核心代码在：

beike/Ai/Agents/BaseAgent.php

# 7.3.1 最推荐的做法

如果你是插件开发者，要新增一个自己的 Agent，推荐这样组织：

plugins/YourPlugin/
├── Agents/
│   └── YourAgent.php
└── Prompts/
    └── your-agent.md

也就是说：

Agent 类放 Agents/
提示词文件放 Prompts/
两者都跟着插件走

这样做的好处是：

插件自己就能把能力带完整
不需要改核心 prompts/agents
插件停用后，不会污染主系统

# 7.3.2 Agent 类里怎么接提示词文件

<?php

namespace Plugin\YourPlugin\Agents;

use Beike\Ai\Agents\BaseAgent;

class YourAgent extends BaseAgent
{
    protected ?string $promptFile = 'plugins/YourPlugin/Prompts/your-agent.md';

    public function description(): string
    {
        return '你的插件助手描述';
    }

    public function getScene(): string
    {
        return 'your-scene';
    }
}

这段配置的意思是：

这个 Agent 的系统提示词，不再从默认目录找
而是直接读取插件里的 your-agent.md

# 7.3.3 提示词文件怎么写

提示词文件就是普通 Markdown 文本。

例如：

你是店铺运营助手。

你的职责：
- 帮管理员处理活动配置
- 优先调用活动相关工具
- 如果参数不完整，先追问缺失信息
- 不要编造数据和执行结果

操作要求：
- 查数据先确认筛选条件
- 写数据前先确认目标对象
- 删除操作要特别谨慎

你可以把它理解成：

这份文件就是这个 Agent 的“角色说明书”。

# 7.3.4 真实项目里的例子

可以直接参考：

plugins/AiArticleManager/Agents/ArticleManagerAgent.php
plugins/AiArticleManager/Prompts/article-manager.md

ArticleManagerAgent 现在就是这样接的：

protected ?string $promptFile = 'plugins/AiArticleManager/Prompts/article-manager.md';

# 7.3.5 不推荐的做法

不推荐在插件新增 Agent 时这样做：

直接把提示词写死在 instructions() 里，导致内容很长、难维护
把插件 Agent 的提示词文件丢到核心 prompts/agents

第一种问题是维护成本高。第二种问题是插件和主系统耦合太紧，后面升级和卸载都容易乱。

# 7.4 第三步补充：怎么扩展“已有 Agent”的提示词

这个需求跟“新增自己的 Agent”不是一回事。

如果你要改的是系统里已经存在的助手，例如：

admin
order-analysis
customer-insight
product-catalog

不要直接去改核心提示词文件。

比如不要直接改这些文件：

prompts/agents/admin-assistant.md
prompts/agents/order-analysis.md
prompts/agents/customer-insight.md
prompts/agents/product-catalog.md

推荐方式是：

在插件 Bootstrap.php 里使用 Hook
扩展 ai.agent.{scene}.instructions

这个能力同样已经接在核心：

beike/Ai/Agents/BaseAgent.php

# 7.4.1 追加式修改

这是最推荐的方式。

add_hook_filter('ai.agent.order-analysis.instructions', function (string $instructions): string {
    return $instructions . "\n\n【插件扩展能力】\n你现在可以额外使用 `orders.xxx` 工具处理补充分析。";
});

它的意思是：

先保留原来的订单分析提示词
再在后面追加一段插件自己的规则

这样做最稳，因为：

原系统的角色设定还在
原系统已有工具说明还在
插件只补自己关心的部分

# 7.4.2 整体替换式修改

如果你真的要彻底接管某个已有 Agent 的提示词，也可以这样：

add_hook_filter('ai.agent.order-analysis.instructions', function (string $instructions): string {
    return <<<TEXT
你是新的订单分析助手。

要求：
- 优先完成插件定义的统计逻辑
- 信息不足时先追问
- 不要编造分析结果
TEXT;
});

但是我不推荐默认这样干。

原因很简单：

很容易把核心原本的行为约束覆盖掉
一旦主系统升级了原提示词，你的插件也接收不到这些改进

# 7.4.3 scene 名怎么确定

ai.agent.{scene}.instructions 里的 {scene}，就是目标 Agent 的 getScene() 返回值。

例如：

admin
order-analysis
customer-insight
product-catalog
articles

你可以从这些类里确认：

beike/Ai/Agents/AdminAssistant.php
beike/Ai/Agents/OrderAnalysisAgent.php
beike/Ai/Agents/CustomerInsightAgent.php
beike/Ai/Agents/ProductCatalogAgent.php

# 7.4.4 什么时候该用“新增 Agent”，什么时候该用“扩展已有 Agent”

判断标准很简单：

如果这是插件自己的独立业务场景，用“新增 Agent”
如果这只是给系统已有助手补能力，用“扩展已有 Agent”

例如：

文章管理、售后备注、发票助手，这些通常适合新增 Agent
订单统计增强、客户标签增强、商品分析增强，这些通常适合扩展已有 Agent

# 7.4.5 推荐结论

插件开发里关于提示词，最推荐的规范就是：

新增 Agent：用 $promptFile 指向插件自己的 .md
改已有 Agent：用 ai.agent.{scene}.instructions Hook
不要直接改核心 prompts/agents/*.md

# 8. 第四步：如果你要给助手增加工具

# 8.1 Tool 是什么

Tool 可以理解成：

AI 真正拿来干活的“能力函数”。

比如：

查文章列表
新建文章
改文章
删除文章
查订单统计

AI 本身只会理解你的问题，真正读数据库、写数据库、返回结构化结果的，是 Tool。

# 8.2 Tool 的最小结构

插件里的文章工具示例：

plugins/AiArticleManager/Tools/Articles/ArticleListTool.php

一个 Tool 一般会有这几部分：

description()：告诉 AI 这个工具干嘛用
schema()：定义输入参数
doHandle()：真正处理逻辑
requiredPermission：可选，自定义权限名

如果你不定义 requiredPermission，系统会根据类名自动猜。但在插件里，建议你明确写出来，这样最稳。

# 9. 第五步：把 Tool 注册进系统

# 9.1 注册工具本身

在 Bootstrap.php 里：

public function registerTools(AiExtensionService $ai): void
{
    $tools = [
        'articles.list'   => \Plugin\AiArticleManager\Tools\Articles\ArticleListTool::class,
        'articles.create' => \Plugin\AiArticleManager\Tools\Articles\ArticleCreateTool::class,
        'articles.update' => \Plugin\AiArticleManager\Tools\Articles\ArticleUpdateTool::class,
        'articles.delete' => \Plugin\AiArticleManager\Tools\Articles\ArticleDeleteTool::class,
    ];

    foreach ($tools as $name => $class) {
        $ai->registerPluginTool($this->pluginCode(), $name, $class, 'article');
    }
}

这里有 3 个概念：

$name：工具注册名，给 AI 系统识别用
$class：工具类
'article'：工具分类

# 9.2 再把工具挂到某个 Agent

只注册工具还不够。

注册工具 = 系统知道有这个工具 挂到 Agent = 某个助手真的能调用这个工具

例如：

foreach (['articles.list', 'articles.create', 'articles.update', 'articles.delete'] as $toolName) {
    $ai->addToolToAgent('articles', $toolName);
}

这句的意思是：

文章助手 articles
可以调用这 4 个工具

# 10. 重点：新增 Tool 和扩展已有 Agent，不是一回事

这是最容易写错的地方。

# 10.1 情况 A：你新增一个自己的助手

例如：

你新建了 articles 助手
你想让它能查文章、改文章

那就应该：

注册 articles.* 工具
再 addToolToAgent('articles', ...)

# 10.2 情况 B：你不是新增助手，而是扩展已有助手

例如你想：

不新建订单助手
只是给系统原来的 order-analysis 增加一个插件工具

那正确做法是：

$ai->registerPluginTool(
    $this->pluginCode(),
    'orders.order-analytics',
    \Plugin\AiArticleManager\Tools\Orders\OrderAnalyticsTool::class,
    'order'
);

$ai->addToolToAgent('order-analysis', 'orders.order-analytics');

注意这里：

工具属于插件
但是工具挂到的是已有 agent：order-analysis

# 10.3 为什么这个区别重要

如果你挂错了，会出现两类问题：

工具职责串线例如文章助手里突然能做订单分析
UI 和提示词乱掉 AI 在不该出现的场景里调用不相关工具

所以判断标准很简单：

这个能力是给谁用的？
就挂到谁的 Agent 上

# 11. 第六步：给 AI 菜单和场景加 UI 扩展

# 11.1 为什么不用直接改前端菜单

因为这个项目已经预留了 Hook。

也就是说：

核心前端会先拿默认菜单
插件可以通过 Hook 追加菜单项

这比直接改核心 Blade / JS 稳得多。

# 11.2 给左侧功能菜单增加一项

plugins/AiArticleManager/Bootstrap.php 里：

add_hook_filter('ai.ui.navigation.features', function (array $items): array {
    $items[] = [
        'key'         => 'articles',
        'title'       => '文章管理',
        'group'       => 'feature',
        'groupTitle'  => '',
        'action'      => 'scene',
        'target'      => 'articles',
        'icon'        => 'file-earmark-text',
        'sort'        => 60,
        'description' => '文章查询与内容维护',
    ];

    return $items;
});

这段配置的意思：

左侧菜单增加一个“文章管理”
点击后切换到 articles 场景

# 11.3 给场景增加标题和欢迎语

add_hook_filter('ai.ui.scenes', function (array $scenes): array {
    $scenes['articles'] = [
        'title'          => '文章管理',
        'welcomeMessage' => '你好！我是文章管理助手，可以帮你查询、新建、修改和删除文章。请直接告诉我文章标题、内容或文章编号。',
    ];

    return $scenes;
});

这一步决定了：

聊天页顶部标题
空白聊天页里的欢迎语
快捷提问挂载位置

# 11.4 场景配置最终从哪里汇总

在：

beike/Ai/Support/AiUiConfig.php

核心系统会把：

默认场景
插件追加场景
插件追加菜单
快捷提问

统一整理成一个前端配置对象，再给 AI 前端使用。

# 12. 第七步：给 AI 功能加权限

# 12.1 为什么一定要加权限

因为后台 AI 不是给所有管理员无条件开放的。

系统会按权限决定：

能不能进入某个助手
能不能执行某个工具

# 12.2 菜单里的 AI 权限从哪来

在：

beike/Admin/Repositories/PermissionRepo.php

系统先准备一批默认 AI 权限，再通过 Hook 合并插件权限：

$routes = hook_filter('ai.permissions.routes', $routes);
$names = hook_filter('ai.permission.names', $names);

所以插件正确做法是：

用 Hook 把自己的权限代码追加进去
再给这些权限代码配中文名称

# 12.3 示例

add_hook_filter('ai.permissions.routes', function (array $routes): array {
    return array_merge($routes, [
        'ai_agent_articles',
        'ai_tool_articles_read',
        'ai_tool_articles_write',
        'ai_tool_articles_delete',
        'ai_tool_order_analytics',
    ]);
});

add_hook_filter('ai.permission.names', function (array $names): array {
    return array_merge($names, [
        'ai_agent_articles'       => '访问文章管理助手',
        'ai_tool_articles_read'   => '文章查询工具',
        'ai_tool_articles_write'  => '文章编辑工具',
        'ai_tool_articles_delete' => '文章删除工具',
        'ai_tool_order_analytics' => '订单统计扩展工具',
    ]);
});

# 12.4 工具执行时实际检查什么

工具执行时，最终走的是：

beike/Ai/Tools/BaseTool.php

它会检查：

$permissionName = $this->resolvePermissionName($input);

如果你给 Tool 写了：

protected ?string $requiredPermission = 'articles_write';

那系统实际检查的是：

ai_tool_articles_write

所以要记住：

Tool 内的 requiredPermission 写的是后半截
后台权限表里存的是 ai_tool_ 前缀完整名

# 13. 第八步：写权限迁移

如果只是 Hook 显示权限名，但数据库里没有权限记录，后台角色还是没法正确分配。

所以插件一般还要有迁移文件，例如：

plugins/AiArticleManager/Migrations/2026_04_29_000000_add_ai_article_manager_permissions.php

示例逻辑：

private array $permissions = [
    'ai_agent_articles',
    'ai_tool_articles_read',
    'ai_tool_articles_write',
    'ai_tool_articles_delete',
    'ai_tool_order_analytics',
];

up() 做两件事：

创建权限
可选地给 admin 角色默认授权

这样你安装插件后，后台就能直接看到这些权限项。

# 14. 第九步：给 Agent 配快捷提问

# 14.1 快捷提问写在哪

通常写在 Agent 里：

public function quickPrompts(): array
{
    return [
        [
            'key'  => 'article-list',
            'text' => '查看文章列表',
            'tool' => 'articles.list',
            'sort' => 10,
        ],
    ];
}

# 14.2 快捷提问怎么进入前端

系统会通过：

beike/Ai/Services/AgentQuickPromptService.php

把 Agent 的 quickPrompts() 收集起来，再交给：

beike/Ai/Support/AiUiConfig.php

最后前端聊天页就能显示。

# 14.3 什么时候适合写快捷提问

适合这些场景：

工具很多，用户不知道怎么开口
有明显高频动作
你想引导用户用对工具

不适合这些场景：

这个 Agent 只有 1 个很简单的动作
你还没把工具行为稳定下来

# 15. 第十步：怎样区分“核心工具”和“插件扩展工具”

这个项目里要特别注意一件事：

系统核心已经有一些 Tool 了，插件不一定非要自己重写一份。

比如订单分析这条线，核心里本来就已经有：

beike/Ai/Tools/Orders/OrderAnalyticsTool.php

如果你插件里又写了一个：

plugins/AiArticleManager/Tools/Orders/OrderAnalyticsTool.php

那你要先想清楚你是哪一种需求：

# 方案 A：只是新增一个插件工具

意思是：

核心工具继续保留
你的插件再额外加一个新工具

这种做法最稳，但要避免命名混乱。

# 方案 B：你想扩展已有 agent

比如：

工具写在插件里
但挂到 order-analysis

这也是合理的。

关键是：

不要因为插件目录叫“文章管理”，就把所有工具都挂到 articles。

工具应该挂到它真正服务的 Agent 上。

# 方案 C：你想替换核心工具

这个就不是“普通挂载”了。

你要进一步设计：

新旧工具同名怎么处理
AI 优先调用谁
权限沿用旧的还是新的

如果只是想先跑通，建议优先用方案 A 或方案 B。

# 16. 第十一步：怎样验证插件扩展成功

# 16.1 先看注册是否成功

当前项目已经有集成测试示例：

tests/Integration/Ai/ArticleAiPluginBootstrapTest.php

这个测试会验证：

articles 助手有没有注册
articles.list/create/update/delete 有没有注册
orders.order-analytics 有没有注册
orders.order-analytics 有没有挂到 order-analysis

这个测试特别适合你写完插件第一时间跑。

# 16.2 再看场景配置是否正常

测试文件：

tests/Feature/Admin/ArticleAiSceneConfigTest.php

它会验证：

左侧导航里有没有“文章管理”
场景配置里有没有 articles
快捷提问有没有进前端配置

# 16.3 推荐命令

php artisan test tests/Integration/Ai/ArticleAiPluginBootstrapTest.php
php artisan test tests/Feature/Admin/ArticleAiSceneConfigTest.php

如果你改了 AI 前端，还可以跑：

php artisan test tests/Feature/Admin/AiAgentWidgetAssetTest.php

# 17. 第十二步：写一个最小可运行示例

假设你要做一个“售后备注助手”插件，最小路径可以按这个顺序：

# 第 1 步：建插件目录

plugins/AiAfterSaleNote/
├── Bootstrap.php
├── config.json
├── Agents/
│   └── AfterSaleNoteAgent.php
├── Tools/
│   └── Notes/
│       └── NoteCreateTool.php
└── Migrations/
    └── 2026_05_01_000000_add_ai_after_sale_note_permissions.php

# 第 2 步：写 `config.json`

先让插件能被系统识别。

# 第 3 步：写 `Bootstrap.php`

pluginCode()
registerAgents()
registerTools()
registerHooks()

# 第 4 步：写 Agent

至少实现：

description()
instructions()
getName()
getDescription()
getScene()
quickPrompts()

# 第 5 步：写 Tool

至少实现：

description()
schema()
doHandle()

# 第 6 步：把 Tool 挂到 Agent

只注册不挂载，AI 调不到。

# 第 7 步：补权限 Hook 和迁移

不然后台角色管理里看不到，也可能没法执行。

# 第 8 步：补测试

至少验证：

Agent 注册成功
Tool 注册成功
Tool 挂载到正确 Agent
前端场景配置正常

# 18. 常见坑

# 坑 1：写了 Tool，但 AI 根本不用

常见原因：

只 registerPluginTool() 了
没有 addToolToAgent()

# 坑 2：菜单里有场景，但点进去空白

常见原因：

前端把聊天场景写死了
新增场景没有进入动态场景列表

这个项目里现在已经改成动态场景方案，新增插件场景时，优先走后端 navigation + scenes 配置，不要再写死。

# 坑 3：权限名写乱

要分清两层：

Tool 类里 requiredPermission
后台角色权限里的 ai_tool_xxx

# 坑 4：工具挂错 Agent

例如：

工具是订单分析工具
却挂进文章助手

判断标准只有一个：

这个工具是给哪个助手用的，就挂到哪个助手。

# 坑 5：插件目录里有代码，但系统没生效

先检查：

插件有没有启用
Bootstrap.php 命名空间对不对
类名是不是 Plugin\\插件目录名\\Bootstrap
boot() 有没有跑到

# 19. 推荐实践

# 19.1 一个插件只管一类清晰职责

例如：

文章插件主要管文章 AI
订单插件主要管订单 AI

如果确实要跨域扩展，也可以，但要明确写清：

这个插件在扩展哪个现有 agent

# 19.2 Tool 名称用“域.动作”更清楚

例如：

articles.list
articles.create
orders.order-analytics

这样一眼就知道它属于哪条业务线。

# 19.3 权限名保持和工具语义一致

例如：

文章工具不要起成订单权限
订单工具不要起成文章权限

# 19.4 先做最小闭环，再做复杂能力

推荐顺序：

先做一个 Agent
先挂一个 Tool
菜单能显示
能真正执行一次
再逐步加更多 Tool、快捷提问、权限细分

# 20. 你以后照着抄的模板

如果你只想快速开工，可以直接按这个清单做：

# 新增一个 AI 助手

建插件目录
写 config.json
写 Bootstrap.php
写 Agent 类
写 Tool 类
registerPluginAgent()
registerPluginTool()
addToolToAgent()
registerHooks() 里补菜单、场景、权限
写迁移
跑测试

# 扩展已有 Agent

不一定要新建 Agent
直接写插件 Tool
registerPluginTool()
addToolToAgent('已有scene', '你的工具名')
补权限
测试“工具挂到了正确 agent”

# 21. 最后给一个判断口诀

你可以记住这 4 句：

Bootstrap 决定插件往系统里加什么
Agent 决定助手是谁、会说什么
Tool 决定 AI 真正能做什么
Hook 决定菜单、场景、权限怎么露出来

如果你后面要继续扩展 AI，基本都绕不开这 4 个点。

# 22. 结合当前项目的直接建议

基于现在这套代码，如果你后面继续开发，我建议你这样分工：

AiArticleManager：专注文章 AI 助手
如果只是顺手给订单分析增加一个插件能力，可以保留在插件里，但一定明确它是“扩展 order-analysis”
如果订单扩展越来越多，最好单独拆成一个订单 AI 插件，避免插件职责越来越混

这样后面维护最省事。

← 开发订阅插件发布插件市场 →

# 开发AI插件

# 1. 先理解这套机制是什么

# 2. AI 插件是怎么自动生效的

# 2.1 插件启动入口

# 3. AI 插件最核心的基类

# 3.1 AiPluginBootstrap

# 4. 一个 AI 插件通常长什么样

# 5. 第一步：准备插件基础信息

# 5.1 config.json

# 6. 第二步：写插件 Bootstrap

# 6.1 最小骨架

# 7. 第三步：如果你要新增一个 AI 助手

# 7.1 写 Agent 类

# 7.2 在 Bootstrap 里注册 Agent

# 7.3 第三步补充：怎么给“新增 Agent”写提示词文件

# 7.3.1 最推荐的做法

# 7.3.2 Agent 类里怎么接提示词文件

# 7.3.3 提示词文件怎么写

# 7.3.4 真实项目里的例子

# 7.3.5 不推荐的做法

# 7.4 第三步补充：怎么扩展“已有 Agent”的提示词

# 7.4.1 追加式修改

# 7.4.2 整体替换式修改

# 7.4.3 scene 名怎么确定

# 7.4.4 什么时候该用“新增 Agent”，什么时候该用“扩展已有 Agent”

# 7.4.5 推荐结论

# 8. 第四步：如果你要给助手增加工具

# 8.1 Tool 是什么

# 8.2 Tool 的最小结构

# 9. 第五步：把 Tool 注册进系统

# 9.1 注册工具本身

# 9.2 再把工具挂到某个 Agent

# 10. 重点：新增 Tool 和扩展已有 Agent，不是一回事

# 10.1 情况 A：你新增一个自己的助手

# 10.2 情况 B：你不是新增助手，而是扩展已有助手

# 10.3 为什么这个区别重要

# 11. 第六步：给 AI 菜单和场景加 UI 扩展

# 11.1 为什么不用直接改前端菜单

# 11.2 给左侧功能菜单增加一项

# 11.3 给场景增加标题和欢迎语

# 11.4 场景配置最终从哪里汇总

# 12. 第七步：给 AI 功能加权限

# 12.1 为什么一定要加权限

# 12.2 菜单里的 AI 权限从哪来

# 12.3 示例

# 12.4 工具执行时实际检查什么

# 13. 第八步：写权限迁移

# 14. 第九步：给 Agent 配快捷提问

# 14.1 快捷提问写在哪

# 14.2 快捷提问怎么进入前端

# 14.3 什么时候适合写快捷提问

# 15. 第十步：怎样区分“核心工具”和“插件扩展工具”

# 方案 A：只是新增一个插件工具

# 方案 B：你想扩展已有 agent

# 方案 C：你想替换核心工具

# 16. 第十一步：怎样验证插件扩展成功

# 16.1 先看注册是否成功

# 16.2 再看场景配置是否正常

# 16.3 推荐命令

# 17. 第十二步：写一个最小可运行示例

# 第 1 步：建插件目录

# 第 2 步：写 config.json

# 第 3 步：写 Bootstrap.php

# 第 4 步：写 Agent

# 第 5 步：写 Tool

# 第 6 步：把 Tool 挂到 Agent

# 第 7 步：补权限 Hook 和迁移

# 第 8 步：补测试

# 18. 常见坑

# 坑 1：写了 Tool，但 AI 根本不用

# 坑 2：菜单里有场景，但点进去空白

# 坑 3：权限名写乱

# 坑 4：工具挂错 Agent

# 坑 5：插件目录里有代码，但系统没生效

# 19. 推荐实践

# 19.1 一个插件只管一类清晰职责

# 19.2 Tool 名称用“域.动作”更清楚

# 19.3 权限名保持和工具语义一致

# 19.4 先做最小闭环，再做复杂能力

# 20. 你以后照着抄的模板

# 3.1 `AiPluginBootstrap`

# 5.1 `config.json`

# 第 2 步：写 `config.json`

# 第 3 步：写 `Bootstrap.php`