feat(kol): add SSE streaming for prompt assist

- Extract assist runtime (prompt building, response parsing, finalize)
  from the worker into kol_assist_runtime so the sync streaming path
  and the async task path share the same logic.
- Add POST /kol/manage/assist/stream as a Server-Sent Events endpoint
  emitting start/delta/completed/error events, and wire it to a
  streamAssist helper on kolManageApi that reports ApiClientError with
  the server's error envelope.
- Stream generated content live in KolPromptEditor and KolGenerateView,
  switching KolPromptEditArea to a boolean aiBusy flag and refining the
  generator page layout.
- Add KolAssistStreamEvent to shared types.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-18 16:17:11 +08:00
parent 79c65c1da7
commit 4bbce5f083
13 changed files with 1062 additions and 234 deletions
@@ -0,0 +1,423 @@
package app
import (
"context"
"encoding/json"
"fmt"
"strings"
"github.com/google/uuid"
"github.com/geo-platform/tenant-api/internal/shared/auth"
"github.com/geo-platform/tenant-api/internal/shared/llm"
"github.com/geo-platform/tenant-api/internal/shared/response"
)
const kolAssistSystemPrompt = "You are a prompt designer for marketing content. Respond ONLY with JSON. Output the `content` field first. Do not wrap in markdown fences."
var kolAssistResponseSchema = []byte(`{
"type": "object",
"additionalProperties": false,
"required": ["content"],
"properties": {
"content": {
"type": "string"
}
}
}`)
func (s *KolAssistService) Run(
ctx context.Context,
actor auth.Actor,
req AssistRequest,
onDelta func(string),
) (*KolAssistResult, string, error) {
if _, err := s.profileSvc.RequireActiveKol(ctx, actor); err != nil {
return nil, "", err
}
if err := s.llm.Validate(); err != nil {
return nil, "", response.ErrServiceUnavailable(50341, "llm_unavailable", err.Error())
}
req, _, err := normalizeAssistRequest(req)
if err != nil {
return nil, "", err
}
generateReq, err := BuildKolAssistGenerateRequest(req)
if err != nil {
return nil, "", response.ErrInternal(50087, "kol_assist_prompt_build_failed", err.Error())
}
streamAccumulator := newKolAssistContentStream(onDelta)
generated, err := s.llm.Generate(ctx, generateReq, streamAccumulator.ConsumeRawDelta)
if err != nil {
return nil, "", err
}
result, err := ParseKolAssistResponse(generated.Content)
if err != nil {
return nil, "", response.ErrInternal(50086, "kol_assist_result_invalid", err.Error())
}
result, err = FinalizeKolAssistResult(req, result)
if err != nil {
return nil, "", response.ErrInternal(50086, "kol_assist_result_invalid", err.Error())
}
return result, generated.Model, nil
}
func BuildKolAssistGenerateRequest(req AssistRequest) (llm.GenerateRequest, error) {
userPrompt, err := BuildKolAssistUserPrompt(req)
if err != nil {
return llm.GenerateRequest{}, err
}
return llm.GenerateRequest{
Prompt: fmt.Sprintf("SYSTEM:\n%s\n\nUSER:\n%s", kolAssistSystemPrompt, userPrompt),
ResponseFormat: &llm.ResponseFormat{
Type: llm.ResponseFormatTypeJSONSchema,
Name: "kol_assist_response",
Description: "JSON object with content:string",
SchemaJSON: kolAssistResponseSchema,
Strict: true,
},
}, nil
}
func BuildKolAssistUserPrompt(req AssistRequest) (string, error) {
switch strings.ToLower(strings.TrimSpace(req.Mode)) {
case kolAssistModeGenerate:
return req.Description, nil
case kolAssistModeOptimize:
schemaJSON := "null"
if req.Schema != nil {
payload, err := json.Marshal(req.Schema)
if err != nil {
return "", fmt.Errorf("encode schema: %w", err)
}
schemaJSON = string(payload)
}
return fmt.Sprintf(
"Optimize the following prompt. Keep variable placeholders intact. Current schema: %s\n\nPROMPT:\n%s",
schemaJSON,
req.CurrentContent,
), nil
default:
return "", fmt.Errorf("unsupported assist mode %q", req.Mode)
}
}
func ParseKolAssistResponse(content string) (*KolAssistResult, error) {
type rawPayload struct {
Content string `json:"content"`
Schema json.RawMessage `json:"schema"`
}
var lastErr error
for _, candidate := range extractJSONCandidates(content) {
var payload rawPayload
if err := json.Unmarshal([]byte(candidate), &payload); err != nil {
lastErr = err
continue
}
result := &KolAssistResult{
Content: strings.TrimSpace(payload.Content),
Schema: KolSchemaJSON{Variables: []KolVariableDefinition{}},
}
if result.Content == "" {
lastErr = fmt.Errorf("kol assist result content is empty")
continue
}
schema, err := decodeKolAssistSchema(payload.Schema)
if err != nil {
lastErr = err
continue
}
result.Schema = schema
return result, nil
}
if lastErr == nil {
lastErr = fmt.Errorf("empty content")
}
return nil, fmt.Errorf("decode kol assist result: %w", lastErr)
}
func FinalizeKolAssistResult(req AssistRequest, result *KolAssistResult) (*KolAssistResult, error) {
if result == nil {
return nil, fmt.Errorf("kol assist result is nil")
}
baseSchema := result.Schema
if req.Mode == kolAssistModeOptimize && req.Schema != nil {
merged := make([]KolVariableDefinition, 0, len(req.Schema.Variables)+len(result.Schema.Variables))
merged = append(merged, req.Schema.Variables...)
merged = append(merged, result.Schema.Variables...)
baseSchema = KolSchemaJSON{Variables: merged}
}
result.Schema = SyncKolSchemaWithContent(result.Content, baseSchema)
if err := ValidateSchema(result.Schema); err != nil {
return nil, fmt.Errorf("invalid kol assist schema: %w", err)
}
return result, nil
}
func SyncKolSchemaWithContent(content string, schema KolSchemaJSON) KolSchemaJSON {
keys := extractKolPlaceholderKeys(content)
if len(keys) == 0 {
return KolSchemaJSON{Variables: []KolVariableDefinition{}}
}
schema = normalizeKolSchema(schema)
byKey := make(map[string][]KolVariableDefinition, len(schema.Variables))
for _, variable := range schema.Variables {
key := strings.TrimSpace(variable.Key)
if key == "" {
key = strings.TrimSpace(variable.Label)
}
if key == "" {
continue
}
byKey[key] = append(byKey[key], variable)
}
usedIDs := make(map[string]struct{}, len(keys))
variables := make([]KolVariableDefinition, 0, len(keys))
for _, key := range keys {
var variable KolVariableDefinition
if candidates := byKey[key]; len(candidates) > 0 {
variable = candidates[0]
byKey[key] = candidates[1:]
} else {
variable = KolVariableDefinition{
Key: key,
Label: key,
Type: KolVariableTypeInput,
Required: true,
}
}
if strings.TrimSpace(variable.Key) == "" {
variable.Key = key
}
if strings.TrimSpace(variable.Label) == "" {
variable.Label = key
}
variable = normalizeKolVariableDefinition(variable)
id := strings.TrimSpace(variable.ID)
if id == "" || !strings.HasPrefix(id, "var_") {
id = newKolVariableID()
}
if _, exists := usedIDs[id]; exists {
id = newKolVariableID()
}
variable.ID = id
usedIDs[id] = struct{}{}
variables = append(variables, variable)
}
return normalizeKolSchema(KolSchemaJSON{Variables: variables})
}
func extractKolPlaceholderKeys(content string) []string {
text := strings.TrimSpace(content)
if text == "" {
return []string{}
}
seen := make(map[string]struct{})
keys := make([]string, 0)
matches := kolPlaceholderRE.FindAllStringSubmatch(text, -1)
for _, match := range matches {
if len(match) < 2 {
continue
}
key := strings.TrimSpace(match[1])
if key == "" {
continue
}
if _, exists := seen[key]; exists {
continue
}
seen[key] = struct{}{}
keys = append(keys, key)
}
return keys
}
func newKolVariableID() string {
return "var_" + strings.ReplaceAll(uuid.NewString(), "-", "")[:8]
}
type kolAssistContentStream struct {
raw strings.Builder
content string
onDelta func(string)
}
func newKolAssistContentStream(onDelta func(string)) *kolAssistContentStream {
return &kolAssistContentStream{onDelta: onDelta}
}
func (s *kolAssistContentStream) ConsumeRawDelta(chunk string) {
if s == nil || s.onDelta == nil || chunk == "" {
return
}
s.raw.WriteString(chunk)
current := extractKolAssistContentFromPartialJSON(s.raw.String())
if current == "" || current == s.content {
return
}
if strings.HasPrefix(current, s.content) {
delta := current[len(s.content):]
s.content = current
if delta != "" {
s.onDelta(delta)
}
}
}
func extractKolAssistContentFromPartialJSON(raw string) string {
keyIndex := strings.Index(raw, `"content"`)
if keyIndex < 0 {
return ""
}
index := keyIndex + len(`"content"`)
for index < len(raw) && isKolAssistJSONWhitespace(raw[index]) {
index++
}
if index >= len(raw) || raw[index] != ':' {
return ""
}
index++
for index < len(raw) && isKolAssistJSONWhitespace(raw[index]) {
index++
}
if index >= len(raw) || raw[index] != '"' {
return ""
}
index++
var builder strings.Builder
for index < len(raw) {
ch := raw[index]
if ch == '"' {
return builder.String()
}
if ch != '\\' {
builder.WriteByte(ch)
index++
continue
}
if index+1 >= len(raw) {
return builder.String()
}
escaped := raw[index+1]
switch escaped {
case '"', '\\', '/':
builder.WriteByte(escaped)
index += 2
case 'b':
builder.WriteByte('\b')
index += 2
case 'f':
builder.WriteByte('\f')
index += 2
case 'n':
builder.WriteByte('\n')
index += 2
case 'r':
builder.WriteByte('\r')
index += 2
case 't':
builder.WriteByte('\t')
index += 2
case 'u':
if index+6 > len(raw) {
return builder.String()
}
var codePoint rune
for _, hexChar := range raw[index+2 : index+6] {
codePoint <<= 4
switch {
case hexChar >= '0' && hexChar <= '9':
codePoint += rune(hexChar - '0')
case hexChar >= 'a' && hexChar <= 'f':
codePoint += rune(hexChar-'a') + 10
case hexChar >= 'A' && hexChar <= 'F':
codePoint += rune(hexChar-'A') + 10
default:
return builder.String()
}
}
builder.WriteRune(codePoint)
index += 6
default:
return builder.String()
}
}
return builder.String()
}
func isKolAssistJSONWhitespace(value byte) bool {
return value == ' ' || value == '\n' || value == '\r' || value == '\t'
}
func decodeKolAssistSchema(raw json.RawMessage) (KolSchemaJSON, error) {
cleaned := strings.TrimSpace(string(raw))
if cleaned == "" || cleaned == "null" {
return KolSchemaJSON{Variables: []KolVariableDefinition{}}, nil
}
var payload struct {
Variables []json.RawMessage `json:"variables"`
}
if err := json.Unmarshal([]byte(cleaned), &payload); err != nil {
return KolSchemaJSON{}, fmt.Errorf("decode kol assist schema: %w", err)
}
variables := make([]KolVariableDefinition, 0, len(payload.Variables))
for _, item := range payload.Variables {
if len(item) == 0 {
continue
}
var variable KolVariableDefinition
if err := json.Unmarshal(item, &variable); err == nil {
variables = append(variables, variable)
continue
}
var key string
if err := json.Unmarshal(item, &key); err == nil {
key = strings.TrimSpace(key)
if key == "" {
continue
}
variables = append(variables, KolVariableDefinition{
Key: key,
Label: key,
Type: KolVariableTypeInput,
Required: true,
})
continue
}
return KolSchemaJSON{}, fmt.Errorf("decode kol assist schema variable: unsupported item %s", string(item))
}
return normalizeKolSchema(KolSchemaJSON{Variables: variables}), nil
}
@@ -0,0 +1,81 @@
package app
import (
"testing"
"github.com/stretchr/testify/require"
)
func TestFinalizeKolAssistResultRepairsDuplicateVariableIDs(t *testing.T) {
t.Parallel()
result, err := FinalizeKolAssistResult(
AssistRequest{Mode: kolAssistModeGenerate},
&KolAssistResult{
Content: "围绕 {{城市}} 和 {{目标词}} 输出内容",
Schema: KolSchemaJSON{
Variables: []KolVariableDefinition{
{ID: "var_dup", Key: "城市", Label: "城市", Type: KolVariableTypeInput, Required: true},
{ID: "var_dup", Key: "目标词", Label: "目标词", Type: KolVariableTypeInput, Required: true},
},
},
},
)
require.NoError(t, err)
require.Len(t, result.Schema.Variables, 2)
require.NotEqual(t, result.Schema.Variables[0].ID, result.Schema.Variables[1].ID)
require.Equal(t, "城市", result.Schema.Variables[0].Key)
require.Equal(t, "目标词", result.Schema.Variables[1].Key)
}
func TestFinalizeKolAssistResultOptimizePreservesExistingSchemaByKey(t *testing.T) {
t.Parallel()
originalMaxLength := 80
result, err := FinalizeKolAssistResult(
AssistRequest{
Mode: kolAssistModeOptimize,
Schema: &KolSchemaJSON{
Variables: []KolVariableDefinition{
{ID: "var_city", Key: "城市", Label: "城市", Type: KolVariableTypeInput, Required: true, MaxLength: intPtr(originalMaxLength)},
},
},
},
&KolAssistResult{
Content: "围绕 {{城市}} 优化提示词",
Schema: KolSchemaJSON{
Variables: []KolVariableDefinition{
{ID: "var_dup", Key: "城市", Label: "城市", Type: KolVariableTypeTextarea, Required: false},
},
},
},
)
require.NoError(t, err)
require.Len(t, result.Schema.Variables, 1)
require.Equal(t, "var_city", result.Schema.Variables[0].ID)
require.Equal(t, KolVariableTypeInput, result.Schema.Variables[0].Type)
require.NotNil(t, result.Schema.Variables[0].MaxLength)
require.Equal(t, originalMaxLength, *result.Schema.Variables[0].MaxLength)
}
func TestParseKolAssistResponseSupportsStringVariables(t *testing.T) {
t.Parallel()
result, err := ParseKolAssistResponse(`{"content":"围绕 {{城市}} 写内容","schema":{"variables":["城市"]}}`)
require.NoError(t, err)
require.Equal(t, "围绕 {{城市}} 写内容", result.Content)
require.Len(t, result.Schema.Variables, 1)
require.Equal(t, "城市", result.Schema.Variables[0].Key)
}
func TestExtractKolAssistContentFromPartialJSON(t *testing.T) {
t.Parallel()
content := extractKolAssistContentFromPartialJSON("{\"content\":\"第一段\\n第二")
require.Equal(t, "第一段\n第二", content)
}
@@ -1,9 +1,12 @@
package transport
import (
"context"
"errors"
"io"
"net/http"
"strconv"
"strings"
"github.com/gin-gonic/gin"
@@ -21,6 +24,17 @@ type KolManageHandler struct {
assets *AssetHandler
}
type kolAssistStreamEvent struct {
Mode string `json:"mode,omitempty"`
Status string `json:"status"`
Delta string `json:"delta,omitempty"`
Content string `json:"content,omitempty"`
Schema *app.KolSchemaJSON `json:"schema,omitempty"`
Error string `json:"error,omitempty"`
Model string `json:"model,omitempty"`
Done bool `json:"done"`
}
func NewKolManageHandler(a *bootstrap.App, assets *AssetHandler) *KolManageHandler {
profileSvc := app.NewKolProfileService(a.KolProfiles).WithObjectStorage(a.ObjectStorage)
@@ -460,6 +474,92 @@ func (h *KolManageHandler) AssistSubmit(c *gin.Context) {
response.Success(c, app.KolAssistSubmitResponse{TaskID: taskID})
}
func (h *KolManageHandler) AssistStream(c *gin.Context) {
var req app.AssistRequest
if err := c.ShouldBindJSON(&req); err != nil {
response.Error(c, response.ErrBadRequest(40001, "invalid_params", err.Error()))
return
}
actor, ok := actorFromRequest(c)
if !ok {
return
}
c.Header("Content-Type", "text/event-stream")
c.Header("Cache-Control", "no-cache")
c.Header("Connection", "keep-alive")
c.Header("X-Accel-Buffering", "no")
flusher, ok := c.Writer.(http.Flusher)
if !ok {
response.Error(c, response.ErrInternal(50011, "stream_unsupported", "response writer does not support streaming"))
return
}
if err := writeSSE(c, "start", kolAssistStreamEvent{
Mode: req.Mode,
Status: "generating",
Done: false,
}); err != nil {
return
}
flusher.Flush()
var streamed strings.Builder
var streamWriteErr error
result, model, err := h.assistSvc.Run(c.Request.Context(), actor, req, func(delta string) {
if delta == "" || streamWriteErr != nil {
return
}
streamed.WriteString(delta)
if writeErr := writeSSE(c, "delta", kolAssistStreamEvent{
Mode: req.Mode,
Status: "generating",
Delta: delta,
Content: streamed.String(),
Done: false,
}); writeErr != nil {
streamWriteErr = writeErr
return
}
flusher.Flush()
})
if streamWriteErr != nil {
return
}
if err != nil {
if errors.Is(c.Request.Context().Err(), context.Canceled) || errors.Is(c.Request.Context().Err(), context.DeadlineExceeded) {
return
}
appErr := response.Normalize(err)
_ = writeSSE(c, "error", kolAssistStreamEvent{
Mode: req.Mode,
Status: "failed",
Content: strings.TrimSpace(streamed.String()),
Error: resolveKolAssistStreamErrorMessage(appErr),
Done: true,
})
flusher.Flush()
return
}
if err := writeSSE(c, "completed", kolAssistStreamEvent{
Mode: req.Mode,
Status: "completed",
Content: result.Content,
Schema: &result.Schema,
Model: model,
Done: true,
}); err != nil {
return
}
flusher.Flush()
}
func (h *KolManageHandler) AssistGet(c *gin.Context) {
taskID := c.Param("id")
if taskID == "" {
@@ -504,3 +604,16 @@ func parseInt64Param(c *gin.Context, key, label string) (int64, bool) {
}
return id, true
}
func resolveKolAssistStreamErrorMessage(appErr *response.AppError) string {
if appErr == nil {
return "AI 处理失败,请稍后重试"
}
if detail := strings.TrimSpace(appErr.Detail); detail != "" {
return detail
}
if message := strings.TrimSpace(appErr.Message); message != "" {
return message
}
return "AI 处理失败,请稍后重试"
}
@@ -77,6 +77,7 @@ func RegisterRoutes(app *bootstrap.App) {
kolManage.PUT("/prompts/:id/activate", kolManageHandler.ActivatePrompt)
kolManage.PUT("/prompts/:id/archive", kolManageHandler.ArchivePrompt)
kolManage.POST("/assist", kolManageHandler.AssistSubmit)
kolManage.POST("/assist/stream", kolManageHandler.AssistStream)
kolManage.GET("/assist/:id", kolManageHandler.AssistGet)
kolDash := protected.Group("/tenant/kol/dashboard")
@@ -6,7 +6,6 @@ import (
"errors"
"fmt"
"os"
"strings"
"time"
amqp "github.com/rabbitmq/amqp091-go"
@@ -18,8 +17,6 @@ import (
"github.com/geo-platform/tenant-api/internal/tenant/repository"
)
const kolAssistSystemPrompt = "You are a prompt designer for marketing content. Respond ONLY with JSON: {content: string, schema: {variables: [...]}}"
var errKolAssistConsumerClosed = errors.New("kol assist consumer channel closed")
type KolAssistWorker struct {
@@ -191,24 +188,21 @@ func (w *KolAssistWorker) processTask(ctx context.Context, job tenantapp.KolAssi
return fmt.Errorf("decode kol assist request: %w", err)
}
userPrompt, err := buildKolAssistUserPrompt(req)
generateReq, err := tenantapp.BuildKolAssistGenerateRequest(req)
if err != nil {
return err
}
result, err := w.llm.Generate(ctx, llm.GenerateRequest{
Prompt: fmt.Sprintf("SYSTEM:\n%s\n\nUSER:\n%s", kolAssistSystemPrompt, userPrompt),
ResponseFormat: &llm.ResponseFormat{
Type: llm.ResponseFormatTypeJSONObject,
Name: "kol_assist_response",
Description: "JSON object with content:string and schema:{variables:[]}",
},
}, nil)
result, err := w.llm.Generate(ctx, generateReq, nil)
if err != nil {
return fmt.Errorf("generate kol assist content: %w", err)
}
parsed, err := parseKolAssistResponse(result.Content)
parsed, err := tenantapp.ParseKolAssistResponse(result.Content)
if err != nil {
return err
}
parsed, err = tenantapp.FinalizeKolAssistResult(req, parsed)
if err != nil {
return err
}
@@ -223,44 +217,3 @@ func (w *KolAssistWorker) processTask(ctx context.Context, job tenantapp.KolAssi
}
return nil
}
func buildKolAssistUserPrompt(req tenantapp.AssistRequest) (string, error) {
switch strings.ToLower(strings.TrimSpace(req.Mode)) {
case "generate":
return req.Description, nil
case "optimize":
schemaJSON := "null"
if req.Schema != nil {
payload, err := json.Marshal(req.Schema)
if err != nil {
return "", fmt.Errorf("encode schema: %w", err)
}
schemaJSON = string(payload)
}
return fmt.Sprintf(
"Optimize the following prompt. Keep variable placeholders intact. Current schema: %s\n\nPROMPT:\n%s",
schemaJSON,
req.CurrentContent,
), nil
default:
return "", fmt.Errorf("unsupported assist mode %q", req.Mode)
}
}
func parseKolAssistResponse(content string) (*tenantapp.KolAssistResult, error) {
var result tenantapp.KolAssistResult
if err := json.Unmarshal([]byte(content), &result); err != nil {
return nil, fmt.Errorf("decode kol assist result: %w", err)
}
result.Content = strings.TrimSpace(result.Content)
if result.Content == "" {
return nil, fmt.Errorf("kol assist result content is empty")
}
if result.Schema.Variables == nil {
result.Schema.Variables = []tenantapp.KolVariableDefinition{}
}
if err := tenantapp.ValidateSchema(result.Schema); err != nil {
return nil, fmt.Errorf("invalid kol assist schema: %w", err)
}
return &result, nil
}