Version: 0.5.8.dev.260315
♻️ refactor(agent): 拆分 agentsvc，并增强 quicknote/outbox 注释与可维护性 - 📦 将 Agent 服务实现从 `service` 根目录迁移到 `service/agentsvc`，包含 `agent.go`、`agent_quick_note.go` 及相关测试 - 🔌 新增 service 层兼容桥接 `agent_bridge.go`，保持 `service.NewAgentService` 与 `*service.AgentService` 现有调用方式不变 - 📝 为 `quicknote` 补充高密度中文步骤化注释，覆盖 `graph` / `runner` / `nodes` / `tool` / `state` / `prompt`，明确职责边界、分支条件、重试与兜底策略 - 🧭 为 `infra/outbox` 与 service agent 链路补充详细中文注释，覆盖状态机流转、幂等处理、失败回写与异步持久化语义 - ✅ 统一格式化相关文件，并通过全量后端测试：`go test ./...` 📝 chore(docs): 更新 AGENTS.md 注释强制规范 - 📚 追加“注释规范（强制）”与“注释风格示例” - ✍️ 明确复杂逻辑必须使用步骤化注释、跨文件调用需写调用目的、注释需同步维护
This commit is contained in:
Losita
78
backend/infra/kafka/admin.go
Normal file
78
backend/infra/kafka/admin.go
Normal file
@@ -0,0 +1,78 @@
|
||||
package kafka
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
segmentkafka "github.com/segmentio/kafka-go"
|
||||
)
|
||||
|
||||
// WaitTopicReady 在指定超时时间内等待 Kafka topic 可用。
|
||||
// 背景：初次部署时 broker 可能已启动，但 topic/partition 还没就绪。
|
||||
// 这里启动前先探测，可减少“应用已启动但实际无法消费”的静默窗口。
|
||||
func WaitTopicReady(parent context.Context, brokers []string, topic string, timeout time.Duration) error {
|
||||
if len(brokers) == 0 {
|
||||
return errors.New("kafka brokers is empty")
|
||||
}
|
||||
if topic == "" {
|
||||
return errors.New("kafka topic is empty")
|
||||
}
|
||||
if timeout <= 0 {
|
||||
timeout = 30 * time.Second
|
||||
}
|
||||
|
||||
ctx, cancel := context.WithTimeout(parent, timeout)
|
||||
defer cancel()
|
||||
|
||||
ticker := time.NewTicker(1 * time.Second)
|
||||
defer ticker.Stop()
|
||||
|
||||
var lastErr error
|
||||
for {
|
||||
if err := probeTopic(ctx, brokers, topic); err == nil {
|
||||
return nil
|
||||
} else {
|
||||
lastErr = err
|
||||
}
|
||||
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
if lastErr != nil {
|
||||
return fmt.Errorf("wait topic ready timeout, topic=%s: %w", topic, lastErr)
|
||||
}
|
||||
return fmt.Errorf("wait topic ready timeout, topic=%s", topic)
|
||||
case <-ticker.C:
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// probeTopic 轮询所有 broker，只要任一 broker 能读到 topic 分区信息即视为就绪。
|
||||
func probeTopic(ctx context.Context, brokers []string, topic string) error {
|
||||
var lastErr error
|
||||
for _, broker := range brokers {
|
||||
conn, err := segmentkafka.DialContext(ctx, "tcp", broker)
|
||||
if err != nil {
|
||||
lastErr = err
|
||||
continue
|
||||
}
|
||||
|
||||
partitions, readErr := conn.ReadPartitions(topic)
|
||||
_ = conn.Close()
|
||||
if readErr != nil {
|
||||
lastErr = readErr
|
||||
continue
|
||||
}
|
||||
if len(partitions) == 0 {
|
||||
lastErr = fmt.Errorf("topic %s has no partitions yet", topic)
|
||||
continue
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
if lastErr != nil {
|
||||
return lastErr
|
||||
}
|
||||
return errors.New("unable to probe topic readiness")
|
||||
}
|
||||
63
backend/infra/kafka/config.go
Normal file
63
backend/infra/kafka/config.go
Normal file
@@ -0,0 +1,63 @@
|
||||
package kafka
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/spf13/viper"
|
||||
)
|
||||
|
||||
const (
|
||||
DefaultTopic = "smartflow.agent.outbox"
|
||||
DefaultGroup = "smartflow-agent-outbox-consumer"
|
||||
)
|
||||
|
||||
// Config 描述 outbox 异步链路所需的 Kafka 配置。
|
||||
// 说明：这些参数同时影响“发送端（producer）”与“消费端（consumer）”。
|
||||
type Config struct {
|
||||
Enabled bool
|
||||
Brokers []string
|
||||
Topic string
|
||||
GroupID string
|
||||
// RetryScanInterval/RetryBatchSize/MaxRetry 作用于 outbox 扫描与失败重试。
|
||||
RetryScanInterval time.Duration
|
||||
RetryBatchSize int
|
||||
MaxRetry int
|
||||
}
|
||||
|
||||
// LoadConfig 从配置中心读取 Kafka 配置，并做兜底默认值。
|
||||
// 兼容性：优先读取 kafka.brokers（数组），为空时降级读取 kafka.broker（单值）。
|
||||
func LoadConfig() Config {
|
||||
brokers := viper.GetStringSlice("kafka.brokers")
|
||||
if len(brokers) == 0 {
|
||||
single := strings.TrimSpace(viper.GetString("kafka.broker"))
|
||||
if single != "" {
|
||||
brokers = []string{single}
|
||||
}
|
||||
}
|
||||
cfg := Config{
|
||||
Enabled: viper.GetBool("kafka.enabled"),
|
||||
Brokers: brokers,
|
||||
Topic: strings.TrimSpace(viper.GetString("kafka.topic")),
|
||||
GroupID: strings.TrimSpace(viper.GetString("kafka.groupID")),
|
||||
RetryScanInterval: viper.GetDuration("kafka.retryScanInterval"),
|
||||
RetryBatchSize: viper.GetInt("kafka.retryBatchSize"),
|
||||
MaxRetry: viper.GetInt("kafka.maxRetry"),
|
||||
}
|
||||
if cfg.Topic == "" {
|
||||
cfg.Topic = DefaultTopic
|
||||
}
|
||||
if cfg.GroupID == "" {
|
||||
cfg.GroupID = DefaultGroup
|
||||
}
|
||||
if cfg.RetryScanInterval <= 0 {
|
||||
cfg.RetryScanInterval = time.Second
|
||||
}
|
||||
if cfg.RetryBatchSize <= 0 {
|
||||
cfg.RetryBatchSize = 100
|
||||
}
|
||||
if cfg.MaxRetry <= 0 {
|
||||
cfg.MaxRetry = 20
|
||||
}
|
||||
return cfg
|
||||
}
|
||||
50
backend/infra/kafka/consumer.go
Normal file
50
backend/infra/kafka/consumer.go
Normal file
@@ -0,0 +1,50 @@
|
||||
package kafka
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
|
||||
segmentkafka "github.com/segmentio/kafka-go"
|
||||
)
|
||||
|
||||
type Consumer struct {
|
||||
reader *segmentkafka.Reader
|
||||
}
|
||||
|
||||
func NewConsumer(cfg Config) (*Consumer, error) {
|
||||
if len(cfg.Brokers) == 0 {
|
||||
return nil, errors.New("kafka brokers 未配置")
|
||||
}
|
||||
reader := segmentkafka.NewReader(segmentkafka.ReaderConfig{
|
||||
Brokers: cfg.Brokers,
|
||||
Topic: cfg.Topic,
|
||||
GroupID: cfg.GroupID,
|
||||
MinBytes: 1,
|
||||
MaxBytes: 10e6,
|
||||
CommitInterval: 0,
|
||||
StartOffset: segmentkafka.FirstOffset,
|
||||
})
|
||||
return &Consumer{reader: reader}, nil
|
||||
}
|
||||
|
||||
// Dequeue 从 Kafka 拉取一条消息（不自动提交 offset）。
|
||||
func (c *Consumer) Dequeue(ctx context.Context) (segmentkafka.Message, error) {
|
||||
if c == nil || c.reader == nil {
|
||||
return segmentkafka.Message{}, errors.New("kafka consumer 未初始化")
|
||||
}
|
||||
return c.reader.FetchMessage(ctx)
|
||||
}
|
||||
|
||||
func (c *Consumer) Commit(ctx context.Context, msg segmentkafka.Message) error {
|
||||
if c == nil || c.reader == nil {
|
||||
return errors.New("kafka consumer 未初始化")
|
||||
}
|
||||
return c.reader.CommitMessages(ctx, msg)
|
||||
}
|
||||
|
||||
func (c *Consumer) Close() error {
|
||||
if c == nil || c.reader == nil {
|
||||
return nil
|
||||
}
|
||||
return c.reader.Close()
|
||||
}
|
||||
14
backend/infra/kafka/envelope.go
Normal file
14
backend/infra/kafka/envelope.go
Normal file
@@ -0,0 +1,14 @@
|
||||
package kafka
|
||||
|
||||
import "encoding/json"
|
||||
|
||||
// Envelope 是 outbox 投递到 Kafka 的统一包裹结构。
|
||||
// 设计目的：
|
||||
// 1) 消费端先拿到 outbox_id，可直接回写状态；
|
||||
// 2) biz_type 做分发，支持后续扩展更多异步业务；
|
||||
// 3) payload 保持原始 JSON，按业务类型再反序列化。
|
||||
type Envelope struct {
|
||||
OutboxID int64 `json:"outbox_id"`
|
||||
BizType string `json:"biz_type"`
|
||||
Payload json.RawMessage `json:"payload"`
|
||||
}
|
||||
45
backend/infra/kafka/producer.go
Normal file
45
backend/infra/kafka/producer.go
Normal file
@@ -0,0 +1,45 @@
|
||||
package kafka
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
|
||||
segmentkafka "github.com/segmentio/kafka-go"
|
||||
)
|
||||
|
||||
type Producer struct {
|
||||
writer *segmentkafka.Writer
|
||||
}
|
||||
|
||||
func NewProducer(cfg Config) (*Producer, error) {
|
||||
if len(cfg.Brokers) == 0 {
|
||||
return nil, errors.New("kafka brokers 未配置")
|
||||
}
|
||||
writer := &segmentkafka.Writer{
|
||||
Addr: segmentkafka.TCP(cfg.Brokers...),
|
||||
Balancer: &segmentkafka.Hash{},
|
||||
RequiredAcks: segmentkafka.RequireOne,
|
||||
Async: false,
|
||||
}
|
||||
return &Producer{writer: writer}, nil
|
||||
}
|
||||
|
||||
// Enqueue 将消息写入 Kafka。
|
||||
func (p *Producer) Enqueue(ctx context.Context, topic, key string, value []byte) error {
|
||||
if p == nil || p.writer == nil {
|
||||
return errors.New("kafka producer 未初始化")
|
||||
}
|
||||
msg := segmentkafka.Message{
|
||||
Topic: topic,
|
||||
Key: []byte(key),
|
||||
Value: value,
|
||||
}
|
||||
return p.writer.WriteMessages(ctx, msg)
|
||||
}
|
||||
|
||||
func (p *Producer) Close() error {
|
||||
if p == nil || p.writer == nil {
|
||||
return nil
|
||||
}
|
||||
return p.writer.Close()
|
||||
}
|
||||
Reference in New Issue
Block a user