Documentation
¶
Overview ¶
Package customer 提供网站和Telegram共用的客服应用、身份、接待和AI执行能力。
Index ¶
- Variables
- func FetchKnowledge(ctx context.Context, kind, content string) (string, error)
- func Raw(v any) json.RawMessage
- func Realm(appID uint) string
- func SplitKnowledge(name, text string) []models.KnowledgeEntry
- func TokenHash(token string) string
- func ValidateConfig(cfg Config) error
- type Config
- type Entry
- type Evidence
- type IndexSpec
- type Manager
- func (m *Manager) AgentAccess(ctx context.Context, appID, adminID uint, action string) error
- func (m *Manager) AgentHeartbeat(ctx context.Context, adminID uint) (bool, error)
- func (m *Manager) App(ctx context.Context, id uint) (models.SupportApp, Config, Secrets, error)
- func (m *Manager) AppIDs(ctx context.Context, adminID uint, action string) ([]uint, error)
- func (m *Manager) AssignWaiting(ctx context.Context) error
- func (m *Manager) Authenticate(ctx context.Context, token string, appID uint) (Session, error)
- func (m *Manager) BuildIndex(ctx context.Context, appID uint) (err error)
- func (m *Manager) Cancel(tx *gorm.DB, conv *models.ChatConversation, draft bool, reason string) error
- func (m *Manager) CheckModel(ctx context.Context, cfg Config, key string) (map[string]any, error)
- func (m *Manager) ClaimVisitor(ctx context.Context, appID uint, ticket, receiver string) (models.User, error)
- func (m *Manager) ConfirmTelegramBinding(ctx context.Context, adminID uint, code string) error
- func (m *Manager) Conversation(ctx context.Context, id uint, session Session, adminID uint, action string) (models.ChatConversation, error)
- func (m *Manager) CreateApp(ctx context.Context, app *models.SupportApp, secrets Secrets) error
- func (m *Manager) CreateTelegramBinding(ctx context.Context, adminID uint) (string, error)
- func (m *Manager) CurrentSession(ctx context.Context, conversationID uint) (*models.SupportSession, error)
- func (m *Manager) DecideAction(ctx context.Context, id uint, session Session, adminID uint, approved bool) error
- func (m *Manager) DecideClosure(ctx context.Context, id uint, visitor Session, sessionID, version uint, ...) (models.ChatConversation, error)
- func (m *Manager) DispatchPending(ctx context.Context) error
- func (m *Manager) Event(tx *gorm.DB, conversationID uint, kind string, value any) error
- func (m *Manager) ExchangeVisitor(ctx context.Context, publicKey, ticket, proof string) (map[string]any, error)
- func (m *Manager) ExecuteTool(ctx context.Context, actor ToolActor, tool Tool, args map[string]any, ...) (result any, err error)
- func (m *Manager) ExpireOffline(ctx context.Context) (err error)
- func (m *Manager) FillVisitorPresence(ctx context.Context, conv *models.ChatConversation, subject string) error
- func (m *Manager) GenerateKnowledge(ctx context.Context, appID uint, content string) ([]map[string]any, error)
- func (m *Manager) GenerateText(ctx context.Context, appID uint, instructions, input string) (string, error)
- func (m *Manager) History(ctx context.Context, id uint, session Session, adminID, before uint, size int) ([]models.ChatMessage, bool, error)
- func (m *Manager) Identify(ctx context.Context, publicKey, token string, input OpenInput) (Session, error)
- func (m *Manager) IdentityTicket(ctx context.Context, userID, appID uint) (string, error)
- func (m *Manager) ImportSource(ctx context.Context, id uint) error
- func (m *Manager) Key(d constants.Definition, args ...any) string
- func (m *Manager) LocalIdentity(ctx context.Context, appID uint, token, visitorTicket string) (Session, string, error)
- func (m *Manager) Login(ctx context.Context, username, password string) (Session, error)
- func (m *Manager) Message(tx *gorm.DB, conv *models.ChatConversation, message *models.ChatMessage) error
- func (m *Manager) NewSession(ctx context.Context, user models.User, appID uint, verified bool) (Session, error)
- func (m *Manager) Open(ctx context.Context, publicKey, token string, input OpenInput) (Session, models.ChatConversation, error)
- func (m *Manager) PreviewInput(ctx context.Context, p realtime.Principal, conversationID uint, content string, ...) error
- func (m *Manager) ProcessRun(ctx context.Context, id uint) (err error)
- func (m *Manager) ProposeSkill(ctx context.Context, appID uint, prompt string) (string, error)
- func (m *Manager) QueueTelegram(ctx context.Context, conv models.ChatConversation, event models.ChatEvent) error
- func (m *Manager) Rate(ctx context.Context, id uint, visitor Session, sessionID, version uint, ...) error
- func (m *Manager) Read(ctx context.Context, id uint, session Session, adminID, messageID uint) error
- func (m *Manager) Reception(ctx context.Context, id uint, session Session, adminID, assignee uint, ...) (models.ChatConversation, error)
- func (m *Manager) Register(ctx context.Context, current Session, username, password, nickname string) (Session, error)
- func (m *Manager) RegisterQuery(name string, query Query)
- func (m *Manager) RegisterRetriever(name string, retriever Retriever)
- func (m *Manager) RegisterTelegramHandler(handler TelegramHandler)
- func (m *Manager) RegisterTool(name string, handler ToolHandler)
- func (m *Manager) RetryReply(ctx context.Context, id uint, visitor Session, messageID uint) error
- func (m *Manager) RunTelegram(ctx context.Context)
- func (m *Manager) Search(ctx context.Context, appID uint, question string) ([]Evidence, error)
- func (m *Manager) Send(ctx context.Context, id uint, session Session, adminID uint, ...) (models.ChatMessage, error)
- func (m *Manager) SetPresence(ctx context.Context, adminID uint, online bool) error
- func (m *Manager) SkillDirectory(appKey, scope string) string
- func (m *Manager) TelegramBinding(ctx context.Context, adminID uint, code string) (TelegramBinding, error)
- func (m *Manager) TelegramBot(ctx context.Context, appID uint) (*bot.Bot, error)
- func (m *Manager) TelegramUser(ctx context.Context, profile TelegramProfile) (models.User, error)
- func (m *Manager) TestModel(ctx context.Context, appID uint) (map[string]any, error)
- func (m *Manager) Validate(ctx context.Context, p realtime.Principal) error
- func (m *Manager) VisitorConnected(ctx context.Context, p realtime.Principal) error
- func (m *Manager) VisitorTicket(ctx context.Context, s Session) (string, error)
- type MessageInput
- type OpenInput
- type Preview
- type Query
- type Retriever
- type RunJob
- type Secrets
- type Session
- type Skill
- type TelegramBinding
- type TelegramEvent
- type TelegramGroup
- type TelegramHandler
- type TelegramProfile
- type Tool
- type ToolActor
- type ToolHandler
Constants ¶
This section is empty.
Variables ¶
var ( ErrForbidden = errors.New("无权访问此会话") ErrConflict = errors.New("会话已更新,请刷新后重试") ErrClosureExpired = errors.New("结束申请已失效,请刷新会话") ErrRated = errors.New("该次接待已经评价") ErrInvalid = errors.New("客服参数无效") ErrUnauthenticated = errors.New("用户会话已失效") )
var ErrLimited = fmt.Errorf("消息发送过于频繁")
var Web embed.FS
Web 包含独立访客页和无框架依赖的嵌入脚本,两个入口共用同一聊天应用。
Functions ¶
func FetchKnowledge ¶
FetchKnowledge 读取文本或公开网页,复用于预览生成与自动导入。
func Raw ¶
func Raw(v any) json.RawMessage
func SplitKnowledge ¶
func SplitKnowledge(name, text string) []models.KnowledgeEntry
SplitKnowledge 按Markdown章节与段落分块,代码围栏保持完整,标题保留文档归属。
func ValidateConfig ¶
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 Evidence ¶
type Evidence struct {
models.KnowledgeEntry
Score float64 `json:"score"`
}
type IndexSpec ¶
type IndexSpec struct {
ID uint `json:"id,omitempty"`
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 ¶
ManagerFrom 解析当前应用已注册的客服实例,不另建数据库或Redis连接。
func (*Manager) AgentAccess ¶
AgentAccess 对HTTP、Telegram和后台任务应用相同的账号及应用范围。
func (*Manager) AgentHeartbeat ¶
AgentHeartbeat只续租并读取共享接待状态,其他窗口不会覆盖人工设置的状态。
func (*Manager) Authenticate ¶
func (*Manager) BuildIndex ¶
BuildIndex 新代际全部完成后才切换活动配置,模型与维度不混用。
func (*Manager) Cancel ¶
func (m *Manager) Cancel(tx *gorm.DB, conv *models.ChatConversation, draft bool, reason string) error
Cancel 使旧执行和迟到片段失效;仅转人工且正在生成时保留内部草稿。
func (*Manager) CheckModel ¶
CheckModel 验证待保存配置,失败时调用方不得写入新密钥。
func (*Manager) ClaimVisitor ¶
func (m *Manager) ClaimVisitor(ctx context.Context, appID uint, ticket, receiver string) (models.User, error)
ClaimVisitor验证反向票据;同一接收方可幂等重试,不同接收方不能重复认领。
func (*Manager) ConfirmTelegramBinding ¶
func (*Manager) Conversation ¶
func (*Manager) CreateTelegramBinding ¶
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 ¶
DispatchPending 补偿事务已提交但尚未投递到队列的执行,重复Job由数据库租约挡住。
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 ¶
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) Identify ¶
func (m *Manager) Identify(ctx context.Context, publicKey, token string, input OpenInput) (Session, error)
Identify建立或恢复身份,不创建咨询,也不排队;外部游客与注册用户分别处理。
func (*Manager) IdentityTicket ¶
IdentityTicket由本站后端签发,绑定用户类型,交换后立即失效。
func (*Manager) ImportSource ¶
ImportSource 从文本或公开URL生成待审核分块,不直接发布资料。
func (*Manager) LocalIdentity ¶
func (m *Manager) LocalIdentity(ctx context.Context, appID uint, token, visitorTicket string) (Session, string, error)
LocalIdentity供共用users表的网站建立游客会话,并签发客服身份票据。
func (*Manager) Message ¶
func (m *Manager) Message(tx *gorm.DB, conv *models.ChatConversation, message *models.ChatMessage) error
func (*Manager) NewSession ¶
func (*Manager) PreviewInput ¶
func (m *Manager) PreviewInput(ctx context.Context, p realtime.Principal, conversationID uint, content string, sequence uint64) error
PreviewInput 只接受当前客户的会话,快照与消息历史分离。
func (*Manager) ProposeSkill ¶
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) Register ¶
func (m *Manager) Register(ctx context.Context, current Session, username, password, nickname string) (Session, error)
Register创建账号;传入本站游客会话时原地升级,保留用户编号与咨询记录。
func (*Manager) RegisterQuery ¶
func (*Manager) RegisterRetriever ¶
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 ¶
RetryReply重试当前AI接待中的失败回复,不重复创建客户消息。
func (*Manager) RunTelegram ¶
RunTelegram 在现有WS进程中管理机器人;每个应用拥有可取消的goroutine,Redis租约避免多实例重复轮询。
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 (*Manager) SkillDirectory ¶
SkillDirectory 返回全局或应用Skill目录,应用目录使用公开应用标识。
func (*Manager) TelegramBinding ¶
func (*Manager) TelegramBot ¶
TelegramBot 提供官方SDK客户端;调用方复用当前应用的密钥和HTTP资源,不输出带Token的URL。
func (*Manager) TelegramUser ¶
TelegramUser 根据Telegram可信数字ID查找或自动注册用户,用户名只作为可变资料。
func (*Manager) VisitorConnected ¶
VisitorConnected 仅重置当前网站接待的离线计时,不恢复已经结束的接待。
type MessageInput ¶
type Query ¶
type Query struct {
Table, UserColumn, AppColumn, IdentityProvider string
Columns, Filters []string
MaxRows int
}
Query 是开发者注册的只读数据集,应用配置不能替换表、字段或归属条件。
type Session ¶
type Session struct {
authsession.Record
User models.User `json:"user"`
Token string `json:"token,omitempty"`
}
func (Session) MarshalJSON ¶
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 ¶
ParseSkill 读取Agent Skills的SKILL.md;脚本仅作为资源,执行需显式注册工具。
type TelegramBinding ¶
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 ¶
TelegramGroup 是机器人实际收到更新的群组,仅用于后台候选选择。
type TelegramHandler ¶
type TelegramHandler func(context.Context, TelegramEvent) (bool, error)
type TelegramProfile ¶
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"`
}
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"`
}