customer

package
v0.1.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 58 Imported by: 0

Documentation

Overview

Package customer 提供网站和Telegram共用的客服应用、身份、接待和AI执行能力。

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrForbidden         = errors.New("无权访问此会话")
	ErrConflict          = errors.New("会话已更新,请刷新后重试")
	ErrClosureExpired    = errors.New("结束申请已失效,请刷新会话")
	ErrRatingUnavailable = errors.New("该次接待尚未结束")
	ErrRated             = errors.New("该次接待已经评价")
	ErrInvalid           = errors.New("客服参数无效")
	ErrUnauthenticated   = errors.New("用户会话已失效")
)
View Source
var ErrLimited = fmt.Errorf("消息发送过于频繁")
View Source
var Web embed.FS

Web 包含独立访客页和无框架依赖的嵌入脚本,两个入口共用同一聊天应用。

Functions

func FetchKnowledge

func FetchKnowledge(ctx context.Context, kind, content string) (string, error)

FetchKnowledge 读取文本或公开网页,复用于预览生成与自动导入。

func Raw

func Raw(v any) json.RawMessage

func Realm

func Realm(appID uint) string

func SplitKnowledge

func SplitKnowledge(name, text string) []models.KnowledgeEntry

SplitKnowledge 按Markdown章节与段落分块,代码围栏保持完整,标题保留文档归属。

func TokenHash

func TokenHash(token string) string

func ValidateConfig

func ValidateConfig(cfg Config) error

ValidateConfig 在配置写入边界检查工具契约,不在每层重复验证静态字段。

Types

type Config

type Config struct {
	Entries               []Entry    `json:"entries"`
	AgentIDs              []uint     `json:"agent_ids"`
	OfflineTimeoutMinutes *int       `json:"offline_timeout_minutes"`
	ClosingOfflineMinutes *int       `json:"closing_offline_minutes"`
	Capacity              int        `json:"capacity"`
	Greeting              string     `json:"greeting"`
	Instructions          string     `json:"instructions"`
	ModelProtocol         string     `json:"model_protocol"`
	ReasoningEffort       string     `json:"reasoning_effort"`
	MaxOutputTokens       int64      `json:"max_output_tokens"`
	Model                 string     `json:"model"`
	BaseURL               string     `json:"base_url"`
	EmbeddingURL          string     `json:"embedding_url"`
	EmbeddingModel        string     `json:"embedding_model"`
	EmbeddingDimensions   int        `json:"embedding_dimensions"`
	IndexProfile          string     `json:"index_profile"`
	IndexDriver           string     `json:"index_driver"`
	ActiveIndex           *IndexSpec `json:"active_index,omitempty"`
	AllowLocalUsers       bool       `json:"allow_local_users"`
	InputPreview          bool       `json:"input_preview"`
	AIEnabled             bool       `json:"ai_enabled"`
	TelegramEnabled       bool       `json:"telegram_enabled"`
	TelegramGroups        []int64    `json:"telegram_groups"`
	TelegramProactive     bool       `json:"telegram_proactive"`
	Tools                 []Tool     `json:"tools"`
	Skills                []Skill    `json:"skills"`
	ContextFields         []string   `json:"context_fields"`
}

func (Config) OfflineDeadline

func (cfg Config) OfflineDeadline(row *models.SupportSession) int64

OfflineDeadline 计算当前接待的离线截止时间,0表示不启用自动结束。

type Entry

type Entry struct {
	Key      string   `json:"key"`
	Origins  []string `json:"origins"`
	Theme    string   `json:"theme"`
	Greeting string   `json:"greeting"`
}

type Evidence

type Evidence struct {
	models.KnowledgeEntry
	Score float64 `json:"score"`
}

type IndexSpec

type IndexSpec struct {
	Credential string `json:"credential"`
	Profile    string `json:"profile"`
	Driver     string `json:"driver"`
	URL        string `json:"url"`
	Model      string `json:"model"`
	Dimensions int    `json:"dimensions"`
	CreatedAt  int64  `json:"created_at"`
}

IndexSpec固定查询所需的模型、维度和连接信息;Credential保存加密后的向量凭证。

type Manager

type Manager struct {
	Storage        string
	DB             *gorm.DB
	Sessions       *authsession.Store
	Redis          redis.UniversalClient
	Hub            *realtime.Hub
	Prefix         string
	Wake           func(context.Context)
	AuthorizeAdmin func(context.Context, uint, string) error
	Client         *http.Client
	TelegramURL    string
	// contains filtered or unexported fields
}

func ManagerFrom

func ManagerFrom(r cc.Resolver) (*Manager, error)

ManagerFrom 解析当前应用已注册的客服实例,不另建数据库或Redis连接。

func New

func New(db *gorm.DB, client redis.UniversalClient, hub *realtime.Hub, prefix string) (*Manager, error)

func Resolve

func Resolve() *Manager

func (*Manager) AgentAccess

func (m *Manager) AgentAccess(ctx context.Context, appID, adminID uint, action string) error

AgentAccess 对HTTP、Telegram和后台任务应用相同的账号及应用范围。

func (*Manager) AgentHeartbeat

func (m *Manager) AgentHeartbeat(ctx context.Context, adminID uint) (bool, error)

AgentHeartbeat只续租并读取共享接待状态,其他窗口不会覆盖人工设置的状态。

func (*Manager) App

func (*Manager) AppIDs

func (m *Manager) AppIDs(ctx context.Context, adminID uint, action string) ([]uint, error)

AppIDs 在执行查询前得到实际应用范围,计数、详情、消息和导出共用此边界。

func (*Manager) AssignWaiting

func (m *Manager) AssignWaiting(ctx context.Context) error

func (*Manager) Authenticate

func (m *Manager) Authenticate(ctx context.Context, token string, appID uint) (Session, error)

func (*Manager) BuildIndex

func (m *Manager) BuildIndex(ctx context.Context, appID uint) error

BuildIndex 新代际全部完成后才切换活动配置,模型与维度不混用。

func (*Manager) Cancel

func (m *Manager) Cancel(tx *gorm.DB, conv *models.ChatConversation, draft bool, reason string) error

Cancel 使旧执行和迟到片段失效;仅转人工且正在生成时保留内部草稿。

func (*Manager) CheckModel

func (m *Manager) CheckModel(ctx context.Context, cfg Config, key string) (map[string]any, error)

CheckModel 验证待保存配置,失败时调用方不得写入新密钥。

func (*Manager) ClaimVisitor

func (m *Manager) ClaimVisitor(ctx context.Context, appID uint, ticket, receiver string) (models.User, error)

ClaimVisitor验证反向票据;同一接收方可幂等重试,不同接收方不能重复认领。

func (*Manager) ConfirmTelegramBinding

func (m *Manager) ConfirmTelegramBinding(ctx context.Context, adminID uint, code string) error

func (*Manager) Conversation

func (m *Manager) Conversation(ctx context.Context, id uint, session Session, adminID uint, action string) (models.ChatConversation, error)

func (*Manager) CreateApp

func (m *Manager) CreateApp(ctx context.Context, app *models.SupportApp, secrets Secrets) error

CreateApp 建立独立AI身份,品牌资料只由应用配置提供。

func (*Manager) CreateTelegramBinding

func (m *Manager) CreateTelegramBinding(ctx context.Context, adminID uint) (string, error)

func (*Manager) CurrentSession

func (m *Manager) CurrentSession(ctx context.Context, conversationID uint) (*models.SupportSession, error)

CurrentSession返回最近一轮人工接待,AI咨询可以没有人工接待记录。

func (*Manager) DecideAction

func (m *Manager) DecideAction(ctx context.Context, id uint, session Session, adminID uint, approved bool) error

DecideAction 只确认已展示的工具及参数,客户端不能在确认时替换契约或身份。

func (*Manager) DecideClosure

func (m *Manager) DecideClosure(ctx context.Context, id uint, visitor Session, sessionID, version uint, approved bool) (models.ChatConversation, error)

DecideClosure允许客户直接结束本轮接待,或拒绝客服的结束申请。

func (*Manager) DispatchPending

func (m *Manager) DispatchPending(ctx context.Context) error

DispatchPending 补偿事务已提交但尚未投递到队列的执行,重复Job由数据库租约挡住。

func (*Manager) Event

func (m *Manager) Event(tx *gorm.DB, conversationID uint, kind string, value any) error

Event 与状态写入同一事务,提交后通过Wake通知现有聊天投递器。

func (*Manager) ExchangeVisitor

func (m *Manager) ExchangeVisitor(ctx context.Context, publicKey, ticket, proof string) (map[string]any, error)

ExchangeVisitor供外部网站后端交换游客票据,只返回该应用的公开编号和外部映射。

func (*Manager) ExecuteTool

func (m *Manager) ExecuteTool(ctx context.Context, actor ToolActor, tool Tool, args map[string]any, confirmed bool) (result any, err error)

ExecuteTool 强制注入真实身份,SQL查询始终追加Scope;确认通过独立授权入口执行。

func (*Manager) ExpireOffline

func (m *Manager) ExpireOffline(ctx context.Context) (err error)

ExpireOffline 由现有调度循环调用;Redis异常或长时间中断后重新计算离线时间。

func (*Manager) FillVisitorPresence

func (m *Manager) FillVisitorPresence(ctx context.Context, conv *models.ChatConversation, subject string) error

FillVisitorPresence 补充后台展示信息,Telegram及Redis不可用时不报告离线。

func (*Manager) GenerateKnowledge

func (m *Manager) GenerateKnowledge(ctx context.Context, appID uint, content string) ([]map[string]any, error)

GenerateKnowledge 将管理员提供的资料整理为可编辑知识,生成过程不发布内容。

func (*Manager) GenerateText

func (m *Manager) GenerateText(ctx context.Context, appID uint, instructions, input string) (string, error)

GenerateText uses the configured customer model for application text generation.

func (*Manager) History

func (m *Manager) History(ctx context.Context, id uint, session Session, adminID, before uint, size int) ([]models.ChatMessage, bool, error)

func (*Manager) Identify

func (m *Manager) Identify(ctx context.Context, publicKey, token string, input OpenInput) (Session, error)

Identify建立或恢复身份,不创建咨询,也不排队;外部游客与注册用户分别处理。

func (*Manager) IdentityTicket

func (m *Manager) IdentityTicket(ctx context.Context, userID, appID uint) (string, error)

IdentityTicket由本站后端签发,绑定用户类型,交换后立即失效。

func (*Manager) ImportSource

func (m *Manager) ImportSource(ctx context.Context, id uint) error

ImportSource 从文本或公开URL生成待审核分块,不直接发布资料。

func (*Manager) Key

func (m *Manager) Key(d constants.Definition, args ...any) string

func (*Manager) LocalIdentity

func (m *Manager) LocalIdentity(ctx context.Context, appID uint, token, visitorTicket string) (Session, string, error)

LocalIdentity供共用users表的网站建立游客会话,并签发客服身份票据。

func (*Manager) Login

func (m *Manager) Login(ctx context.Context, username, password string) (Session, error)

func (*Manager) Message

func (m *Manager) Message(tx *gorm.DB, conv *models.ChatConversation, message *models.ChatMessage) error

func (*Manager) NewSession

func (m *Manager) NewSession(ctx context.Context, user models.User, appID uint, verified bool) (Session, error)

func (*Manager) Open

func (m *Manager) Open(ctx context.Context, publicKey, token string, input OpenInput) (Session, models.ChatConversation, error)

func (*Manager) PreviewInput

func (m *Manager) PreviewInput(ctx context.Context, p realtime.Principal, conversationID uint, content string, sequence uint64) error

PreviewInput 只接受当前客户的会话,快照与消息历史分离。

func (*Manager) ProcessRun

func (m *Manager) ProcessRun(ctx context.Context, id uint) (err error)

func (*Manager) ProposeSkill

func (m *Manager) ProposeSkill(ctx context.Context, appID uint, prompt string) (string, error)

ProposeSkill 在管理员确认前只生成安装预览,不写文件或执行脚本。

func (*Manager) QueueTelegram

func (m *Manager) QueueTelegram(ctx context.Context, conv models.ChatConversation, event models.ChatEvent) error

QueueTelegram 将已提交的公开回复加入同一SQL执行表,投递失败可以重试。

func (*Manager) Rate

func (m *Manager) Rate(ctx context.Context, id uint, visitor Session, sessionID, version uint, rating int, comment string) error

Rate在待确认卡片中一次完成评分与结束,也允许评价已结束的历史接待。

func (*Manager) Read

func (m *Manager) Read(ctx context.Context, id uint, session Session, adminID, messageID uint) error

func (*Manager) Reception

func (m *Manager) Reception(ctx context.Context, id uint, session Session, adminID, assignee uint, version uint, action string) (models.ChatConversation, error)

func (*Manager) Register

func (m *Manager) Register(ctx context.Context, current Session, username, password, nickname string) (Session, error)

Register创建账号;传入本站游客会话时原地升级,保留用户编号与咨询记录。

func (*Manager) RegisterQuery

func (m *Manager) RegisterQuery(name string, query Query)

func (*Manager) RegisterRetriever

func (m *Manager) RegisterRetriever(name string, retriever Retriever)

RegisterRetriever 注册已有知识系统,必须按传入的appID限制数据范围。

func (*Manager) RegisterTelegramHandler

func (m *Manager) RegisterTelegramHandler(handler TelegramHandler)

func (*Manager) RegisterTool

func (m *Manager) RegisterTool(name string, handler ToolHandler)

RegisterTool 绑定真实业务能力;输入Schema与应用允许列表仍由运行时执行。

func (*Manager) RetryReply

func (m *Manager) RetryReply(ctx context.Context, id uint, visitor Session, messageID uint) error

RetryReply重试当前AI接待中的失败回复,不重复创建客户消息。

func (*Manager) RunTelegram

func (m *Manager) RunTelegram(ctx context.Context)

RunTelegram 在现有WS进程中管理机器人;每个应用拥有可取消的goroutine,Redis租约避免多实例重复轮询。

func (*Manager) Search

func (m *Manager) Search(ctx context.Context, appID uint, question string) ([]Evidence, error)

func (*Manager) Send

func (m *Manager) Send(ctx context.Context, id uint, session Session, adminID uint, input MessageInput) (models.ChatMessage, error)

func (*Manager) SetPresence

func (m *Manager) SetPresence(ctx context.Context, adminID uint, online bool) error

func (*Manager) SkillDirectory

func (m *Manager) SkillDirectory(appKey, scope string) string

SkillDirectory 返回全局或应用Skill目录,应用目录使用公开应用标识。

func (*Manager) TelegramBinding

func (m *Manager) TelegramBinding(ctx context.Context, adminID uint, code string) (TelegramBinding, error)

func (*Manager) TelegramBot

func (m *Manager) TelegramBot(ctx context.Context, appID uint) (*bot.Bot, error)

TelegramBot 提供官方SDK客户端;调用方复用当前应用的密钥和HTTP资源,不输出带Token的URL。

func (*Manager) TelegramUser

func (m *Manager) TelegramUser(ctx context.Context, profile TelegramProfile) (models.User, error)

TelegramUser 根据Telegram可信数字ID查找或自动注册用户,用户名只作为可变资料。

func (*Manager) TestModel

func (m *Manager) TestModel(ctx context.Context, appID uint) (map[string]any, error)

TestModel使用已保存配置验证真实流式输出,错误仅返回给应用配置管理员。

func (*Manager) Validate

func (m *Manager) Validate(ctx context.Context, p realtime.Principal) error

func (*Manager) VisitorConnected

func (m *Manager) VisitorConnected(ctx context.Context, p realtime.Principal) error

VisitorConnected 仅重置当前网站接待的离线计时,不恢复已经结束的接待。

func (*Manager) VisitorTicket

func (m *Manager) VisitorTicket(ctx context.Context, s Session) (string, error)

VisitorTicket将当前游客转换为短期反向票据,不能用来登录注册账号。

type MessageInput

type MessageInput struct {
	RequestID  string `json:"request_id"`
	Content    string `json:"content"`
	Visibility string `json:"visibility"`
	Version    uint   `json:"version"`
	// contains filtered or unexported fields
}

type OpenInput

type OpenInput struct {
	ConversationID uint           `json:"conversation_id"`
	EntryKey       string         `json:"entry_key"`
	Identity       string         `json:"identity"`
	Ticket         string         `json:"ticket"`
	Attributes     map[string]any `json:"attributes"`
	Observed       map[string]any `json:"observed"`
}

type Preview

type Preview struct {
	Content   string `json:"content"`
	Sequence  uint64 `json:"sequence"`
	UpdatedAt int64  `json:"updated_at"`
	Device    string `json:"device"`
}

type Query

type Query struct {
	Table, UserColumn, AppColumn, IdentityProvider string
	Columns, Filters                               []string
	MaxRows                                        int
}

Query 是开发者注册的只读数据集,应用配置不能替换表、字段或归属条件。

type Retriever

type Retriever func(context.Context, uint, string) ([]Evidence, error)

type RunJob

type RunJob struct {
	ID uint `json:"id"`
}

func (*RunJob) Handle

func (j *RunJob) Handle(ctx context.Context) error

type Secrets

type Secrets struct {
	EmbeddingAPIKey string                       `json:"embedding_api_key"`
	APIKey          string                       `json:"api_key"`
	IdentitySecret  string                       `json:"identity_secret"`
	TelegramToken   string                       `json:"telegram_token"`
	ToolHeaders     map[string]map[string]string `json:"tool_headers"`
}

type Session

type Session struct {
	authsession.Record
	User  models.User `json:"user"`
	Token string      `json:"token,omitempty"`
}

func (Session) MarshalJSON

func (s Session) MarshalJSON() ([]byte, error)

MarshalJSON只公开访客需要的字段,内部用户ID与会话记录ID不会发送到网站。

type Skill

type Skill struct {
	Scope        string            `json:"scope,omitempty" yaml:"-"`
	Name         string            `json:"name" yaml:"name"`
	Description  string            `json:"description" yaml:"description"`
	AllowedTools string            `json:"allowed_tools" yaml:"allowed-tools"`
	Instructions string            `json:"instructions" yaml:"-"`
	References   map[string]string `json:"references,omitempty" yaml:"-"`
}

func ParseSkill

func ParseSkill(content string) (Skill, error)

ParseSkill 读取Agent Skills的SKILL.md;脚本仅作为资源,执行需显式注册工具。

type TelegramBinding

type TelegramBinding struct {
	AdminID    uint   `json:"admin_id"`
	UserID     uint   `json:"user_id"`
	TelegramID int64  `json:"telegram_id"`
	Username   string `json:"username"`
	Nickname   string `json:"nickname"`
	ExpiresAt  int64  `json:"expires_at"`
}

type TelegramEvent

type TelegramEvent struct {
	AppID     uint            `json:"app_id"`
	User      models.User     `json:"user"`
	ChatID    int64           `json:"chat_id"`
	ThreadID  int             `json:"thread_id"`
	MessageID int             `json:"message_id"`
	Text      string          `json:"text"`
	Raw       json.RawMessage `json:"raw"`
}

TelegramEvent 统一扩展事件字段,Raw保留需要接入其他Bot API能力的原始更新。

type TelegramGroup

type TelegramGroup struct {
	ID    int64  `json:"id"`
	Title string `json:"title"`
}

TelegramGroup 是机器人实际收到更新的群组,仅用于后台候选选择。

type TelegramHandler

type TelegramHandler func(context.Context, TelegramEvent) (bool, error)

type TelegramProfile

type TelegramProfile struct {
	ID                                    int64
	Username, FirstName, LastName, Locale string
}

type Tool

type Tool struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
	Driver      string         `json:"driver"`
	URL         string         `json:"url,omitempty"`
	RemoteName  string         `json:"remote_name,omitempty"`
	// RequireAccount要求已验证的注册用户,RequireIdentity仍允许已验证游客。
	RequireAccount  bool   `json:"require_account"`
	RequireIdentity bool   `json:"require_identity"`
	AllowGroups     bool   `json:"allow_groups"`
	Confirmation    bool   `json:"confirmation"`
	Skill           string `json:"skill,omitempty"`
}

func AllowedTool

func AllowedTool(cfg Config, name string, activeSkills []string) (Tool, bool)

type ToolActor

type ToolActor struct {
	IdempotencyKey   string `json:"idempotency_key"`
	AppID            uint   `json:"app_id"`
	UserID           uint   `json:"user_id"`
	ExternalUserID   string `json:"external_user_id,omitempty"`
	IdentityProvider string `json:"identity_provider,omitempty"`
	Verified         bool   `json:"verified"`
	UserType         string `json:"user_type"`
	ConversationID   uint   `json:"conversation_id"`
	RunID            uint   `json:"run_id"`
	Public           bool   `json:"public"`
	Version          uint   `json:"version"`
	AdminID          uint   `json:"admin_id,omitempty"`
}

type ToolHandler

type ToolHandler func(context.Context, ToolActor, map[string]any) (any, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL