gochat/docs/captain-ai-auto-replay-prompt.md

Captain AI — LLM 自动回复 Prompt 配置

概述

自动回复规则支持三种模式：static（静态文本）、llm（LLM 生成）、mixed（静态引导 + LLM 正文）。
本文档仅涉及 llm 和 mixed 模式下的 LLM Prompt 配置。

架构

客户消息 → Widget/Fake/Webhook Channel
  → AutoReplyListener.OnEvent()
    → AutoReplyRuleService.EvaluateRules()
      → 条件匹配成功
        → LLM ChatCompletion（mode=llm/mixed）
          → 生成回复内容
    → AutoReplyListener.sendAutoReply()
      → MessageService.Create() 生成消息
        → sender_type="AgentBot", sender_id=AgentBotID

LLM Provider 配置

Provider 通过 installation_configs 表持久化，key 如下：

Key	说明
COPILOT_PROVIDER_CONFIG	JSON: chat/embedding/generation/request 设置
COPILOT_CHAT_API_KEY	Chat API 密钥
COPILOT_EMBEDDING_API_KEY	Embedding API 密钥

配置格式

{
  "chat": {
    "provider": "openai_compatible",
    "base_url": "http://<host>:<port>/v1",
    "model": "<model-name>"
  },
  "embedding": {
    "mode": "reuse_chat_credentials",
    "provider": "openai_compatible",
    "base_url": "http://<host>:<port>/v1",
    "model": "<model-name>",
    "dimensions": 1024
  },
  "generation": {
    "temperature": 0.7,
    "max_tokens": 2048
  },
  "request": {
    "timeout_seconds": 60,
    "max_retries": 2
  }
}

SQL 注入示例

DELETE FROM installation_configs WHERE name IN ('COPILOT_PROVIDER_CONFIG', 'COPILOT_CHAT_API_KEY', 'COPILOT_EMBEDDING_API_KEY');

INSERT INTO installation_configs (name, value, created_at, updated_at)
VALUES ('COPILOT_PROVIDER_CONFIG', '{"chat":{"provider":"openai_compatible","base_url":"http://<host>:<port>/v1","model":"<model>"},"embedding":{"mode":"reuse_chat_credentials","provider":"openai_compatible","base_url":"http://<host>:<port>/v1","model":"<model>","dimensions":1024},"generation":{"temperature":0.7,"max_tokens":2048},"request":{"timeout_seconds":60,"max_retries":2}}', NOW(), NOW());

INSERT INTO installation_configs (name, value, created_at, updated_at)
VALUES ('COPILOT_CHAT_API_KEY', '<api-key>', NOW(), NOW());

INSERT INTO installation_configs (name, value, created_at, updated_at)
VALUES ('COPILOT_EMBEDDING_API_KEY', '<api-key>', NOW(), NOW());

API 配置

也可以通过 Platform API 配置：

# Platform API 需要 platform_app access_token
curl -X PUT "http://localhost:3000/platform/api/v1/copilot/config" \
  -H 'api_access_token: <platform-app-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat": {
      "provider": "openai_compatible",
      "base_url": "http://<host>:<port>/v1",
      "model": "<model>",
      "api_key": "<api-key>"
    },
    "embedding": {
      "mode": "reuse_chat_credentials",
      "provider": "openai_compatible",
      "base_url": "http://<host>:<port>/v1",
      "model": "<model>",
      "dimensions": 1024,
      "api_key": "<api-key>"
    }
  }'

自动回复 Prompt 流程

规则评估（EvaluateRules）

文件: backend/internal/service/auto_reply_rule_service.go

EvaluateRules()
  → 按 priority 降序遍历 active 规则
  → matchConditions() 检查每条条件:
    - message_content: contains / equals / regex / starts_with
    - sender_type: Contact / User / AgentBot
    - conversation_status: open / resolved / bot
    - language: language_is
  → 匹配成功:
    - static 模式: 直接返回 ResponseText
    - llm 模式: composeLLMReply()
    - mixed 模式: ResponseText + "\n\n" + composeLLMReply()

LLM 回复组装（composeLLMReply）

func (s *AutoReplyRuleService) composeLLMReply(ctx context.Context, rule *model.CaptainAutoReplyRule, evalCtx *AutoReplyEvaluationContext) (string, error) {
    // 1. 加载 Assistant 配置（response_guidelines、config）
    // 2. 构建 System Prompt:
    //    - 从 Assistant.ResponseGuidelines 获取行为指南
    //    - 从 rule.LLMPromptOverride 获取 prompt 覆盖
    // 3. 构建历史消息上下文
    // 4. 调用 llmProvider.ChatCompletion()
    // 5. 返回生成的回复文本
}

System Prompt 构建

System: You are a helpful customer support assistant for {{account_name}}.
{{response_guidelines}}
{{llm_prompt_override}}

Context:
- Account: {{account_name}}
- Inbox: {{inbox_name}}
- Customer: {{contact_name}}

Previous conversation:
{{previous_messages_formatted}}

Current customer message: {{message_content}}

Please provide a helpful, concise response.

生产部署检查清单

• LLM Provider API 可访问（curl http://<host>:<port>/v1/chat/completions）
• COPILOT_PROVIDER_CONFIG 已写入 installation_configs
• COPILOT_CHAT_API_KEY 已配置
• 环境变量 GOCHAT_ENV 未设置为 production 时自动回复规则默认为 draft
• AgentBot 已创建并关联到目标 Inbox
• 规则 status 设为 active
• Prompt 注入防护已启用（llm_prompt_override 来自管理员配置而非用户输入）

已知限制

1. Auto-reply 发送的 sender_type 目前为 AgentBot，需要先创建 AgentBot 记录并关联到 Inbox
2. LLM 回复为同步阻塞（在 AutoReplyListener 的 OnEvent 中执行），生产环境中建议移入异步 worker
3. one_time_only 的去重策略是通过检查同一 conversation 中是否存在 agent_bot 消息实现，精确度有限