AI 助手

Doggy 提供全局 AI 助手，以浮动按钮 + 侧滑面板形式存在于所有页面，通过上下文注册机制与页面深度集成，支持 ReAct 推理循环和工具调用。

概述

AI 助手基于 symfony/ai-agent + symfony/ai-platform 技术栈构建，对接平台自有 LlmRouter 网关体系：

Client POST /api/admin/ai/chat  { context, message }
  → AiChatController
    → AiContextRegistry::get(context)
      → AiContextProviderInterface (e.g. ViewEditorAiContext)
        → AiAssistant::chat(roleCode, systemPrompt, toolProviders, message)
          → Agent::call(MessageBag, options)
            → AgentProcessor::processInput (注入 Tool)
            → LlmRouterPlatform::invoke → LlmRouter → LlmGatewayFactory
            → AgentProcessor::processOutput (ReAct 循环)
            ← string response

全局入口

AI 助手面板在 templates/base.html.twig 中无条件引入：

twig

<body>
    {% block body %}{% endblock %}
    {% include 'admin/ai_chat.html.twig' %}
</body>

打开/关闭：右下角浮动按钮 toggle-ai-chat / ai-chat-close
输入：Enter 发送，Shift+Enter 换行
加载态：请求期间禁用输入，显示"思考中..."
样式：public/sunui/admin/ai_chat.css

页面上下文注册

每个页面通过 window.__AI_CONTEXT__ 向助手注册上下文：

window.__AI_CONTEXT__ = {
    name: 'view_editor',                  // 后端 AiContextProviderInterface::getName()
    buildPrompt: function(msg) {          // 可选，构造发送给后端的消息
        return '[当前视图ID: xxx]\n\n' + msg;
    },
};

视图编辑器注册示例：

twig

<script>
  window.__VIEW_ID__ = {{ id|json_encode|raw }};
  window.__AI_CONTEXT__ = {
      name: 'view_editor',
      buildPrompt: function(msg) {
          var vid = window.__VIEW_ID__;
          return vid ? '[当前视图ID: ' + vid + ']\n\n' + msg : msg;
      },
  };
</script>

上下文提供者系统

AiContextProviderInterface 定义上下文提供者：

php

namespace App\Service\AI\Runtime;

interface AiContextProviderInterface
{
    public function getName(): string;                    // 上下文标识
    public function getRoleCode(): string;                // LlmRouter 角色代码
    public function getSystemPrompt(): string;            // Agent 系统提示词
    public function getToolProviders(): array;            // Tool 对象数组
}

通过 app.ai_context 标签注册：

yaml

App\Service\AI\Context\ViewEditorAiContext:
    tags:
        - { name: 'app.ai_context' }

新增页面上下文

创建类实现 AiContextProviderInterface
在 services.yaml 中添加 tags: [{ name: 'app.ai_context' }]
在页面模板中设置 window.__AI_CONTEXT__ = { name: 'your_name' }

Agent 运行时

AiAssistant 是泛化 Agent 工厂，每次 chat() 创建独立 Agent 实例，确保无状态污染：

php

$platform = new LlmRouterPlatform($this->router, $this->converter);
$toolbox = new Toolbox($toolProviders);

$agent = new Agent(
    platform: $platform,
    model: $roleCode,
    inputProcessors: [
        new SystemPromptInputProcessor($systemPrompt),
        new AgentProcessor($toolbox),
    ],
    outputProcessors: [
        new AgentProcessor($toolbox),
    ],
    name: 'ai-assistant',
);

ReAct 循环

AgentProcessor 同时作为输入/输出处理器，实现工具调用循环：

processInput：注入 Toolbox 的 Tool 元数据
processOutput：检测结果为 ToolCallResult 时：
1. 将 ToolCall 数组加入 MessageBag
2. 执行 ToolCall → ToolResult 写回 MessageBag
3. 递归调用直到返回 TextResult

工具体系

基于 symfony/ai-agent 的 #[AsTool] 属性标记工具方法：

php

use Symfony\AI\Agent\Toolbox\Attribute\AsTool;

class ViewEditorToolProvider
{
    #[AsTool(name: 'view.getInfo', description: '获取视图的完整信息')]
    public function getViewInfo(string $viewId): array { ... }

    #[AsTool(name: 'view.updateSectionConfig', description: '更新视图的布局配置')]
    public function updateSectionConfig(string $viewId, string $contentWidth, ...): array { ... }
}

当前视图编辑器工具

Tool	功能
`view.getInfo`	获取视图信息（实体、字段、布局）
`view.updateSectionConfig`	更新布局配置
`view.updateFieldConfig`	更新字段配置
`view.listEntityFields`	列出实体字段

设计原则

每个工具是单一职责的方法
参数名与 #[AsTool] JSON Schema 参数名一致（自动映射）
返回 array（转为工具结果文本）

API 端点

POST /api/admin/ai/chat

json

{
    "context": "view_editor",
    "message": "帮我改成三列布局"
}

成功响应：

json

{
    "code": 200,
    "message": "success",
    "data": { "reply": "已修改为三列布局。" }
}

文件	职责
`AiChatController.php`	接收 `{context, message}`，委派对应 Provider
`AiContextRegistry.php`	收集 `app.ai_context` 标签服务，按 name 索引
`AiAssistant.php`	泛化 Agent 工厂
`LlmRouterPlatform.php`	`PlatformInterface` 桥接（MessageBag ↔ 数组）
`ChatResultConverter.php`	响应数据 → TextResult/ToolCallResult
`ViewEditorToolProvider.php`	视图编辑器 Tool 方法
`ChromeDevToolsToolProvider.php`	CDP 浏览器调试工具
`ViewFileToolProvider.php`	视图文件读写工具

AI 助手 ​

概述 ​

全局入口 ​

页面上下文注册 ​

上下文提供者系统 ​

新增页面上下文 ​

Agent 运行时 ​

ReAct 循环 ​

工具体系 ​

当前视图编辑器工具 ​

设计原则 ​

API 端点 ​

POST /api/admin/ai/chat ​

相关文件 ​