feat(runtime+admin): A2 LLM异步提取接线 + A4 Tracing接线 + A6通知后端聚合
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

A2 异步记忆提取:
- loop/memory.go: asyncExtractor接口(ExtractAsync)+extractMemoryAsync(60s超时,WithOutCancel,dispatch即返回,后台落库,失败仅Warn)+persistMemories共用
- run.go 三个回合落定点改异步提取; 删除run.go逐步提取(design/03'每轮后', 避免多轮工具N次LLM调用/重复写)
- cmd/cyrene/extractor.go buildMemoryExtractor: llmGroupUsable为真→LLMExtractor, 否则回落ManualExtractor(日志说明); keylessEndpoint放行loopback/私网

A4 可观测性 Tracing:
- cmd/cyrene/observability.go: newAppTraceWriter+traceFanout(多sink)+gatewaySpanSink(走gw.ObserveSpan,喂环形缓冲+LLM/subagent指标)
- wire.go 注入; 未改trace/gateway数据结构

A6 通知后端:
- internal/services/gateway/notifications.go(311行): GET /admin/notifications?type=&before=&limit= (adminAuth)
- 聚合已有源(obs.audit SQLite + s.backthink), createdAt倒序, id=source:id; 类型派生(channel/system/audit/backthink); 无新建表/无新Deps/wire零改动
- 诚实: backthink仅shouldPush计, 未注入源为空, 报错500, 未读游标后置
- 契约与前端Y一致: {id,type,title,body,source,createdAt}, before含游标(<=), type未知400
- Docs/api-client v0.33

全仓 build/vet/test绿(56包)+win/darwin/linux-arm64交叉编译绿; 新增测试(memory_async/extractor/observability/notifications)
This commit is contained in:
AskaEth committed 2026-09-30 09:03:16 +08:00
1 parent 34c8cc4dca
commit 153a9d6211
12 files changed
+1427 -11

No files matched your search

+75
View File
@@ -3,11 +3,26 @@ package loop
import (
"context"
"strings"
"time"
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
)
// memoryExtractTimeout bounds one background extraction. It only governs the
// detached extraction context, so a hung model call cannot leak a goroutine for
// the process lifetime.
const memoryExtractTimeout = 60 * time.Second
// asyncExtractor is the extractor capability the loop detaches to a background
// goroutine: memory.LLMExtractor implements it through ExtractAsync (design/03 §1
// LLM 异步自动提取), returning a channel that delivers exactly one result.
// Deterministic extractors (memory.ManualExtractor) do not implement it and stay
// on the synchronous path.
type asyncExtractor interface {
ExtractAsync(ctx context.Context, conversation []model.Message) (<-chan memory.AsyncResult, error)
}
// injectMemory retrieves the persona's relevant long-term memories and prepends
// them as a leading system message, so the model can ground its answer in recalled
// context (design §6 / §2). It is re-run every round via assembleContext so the
@@ -157,6 +172,66 @@ func (l *Loop) extractMemory(ctx context.Context, messages []model.Message, step
l.log.Warn("memory extract", "step", step, "error", err)
return
}
l.persistMemories(ctx, items, step)
}
// extractMemoryAsync triggers the extraction hook at the turn boundary without
// blocking the reply (design/03 §1: 每轮对话后后台异步抽取). When the configured
// extractor can extract asynchronously (the LLM extractor) the conversation is
// handed to a background goroutine and this call returns immediately, so a slow
// extraction model never delays the response. A deterministic extractor
// (ManualExtractor) does not implement asyncExtractor and is run inline, which
// keeps its cheap "记住 X" path observable and unchanged.
//
// The same gates as extractMemory apply: a restricted conversation is never
// extracted (read-only isolation, design/02 §3 / design/11 §2), and a missing
// extractor or store is a no-op. Extraction failures and store failures are
// logged with the loop's source and never propagated.
func (l *Loop) extractMemoryAsync(ctx context.Context, messages []model.Message, step int) {
env := sessionEnvFrom(ctx)
if env.Restricted() {
l.log.Debug("memory extract skipped: read-only context", "step", step, "env", env.ActorEnv)
return
}
if l.extractor == nil || l.memory == nil {
return
}
async, ok := l.extractor.(asyncExtractor)
if !ok {
l.extractMemory(ctx, messages, step)
return
}
// The turn's context dies with the request while the extraction deliberately
// outlives it, so the goroutine gets a detached copy of the context (values —
// the session env among them — are kept) under its own timeout.
dctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), memoryExtractTimeout)
// The caller keeps appending to messages as the turn continues, so the
// goroutine reads a private snapshot instead of racing on the shared slice.
snapshot := append([]model.Message(nil), messages...)
results, err := async.ExtractAsync(dctx, snapshot)
if err != nil {
cancel()
l.log.Warn("memory extract dispatch", "step", step, "error", err)
return
}
go func() {
defer cancel()
res, ok := <-results
if !ok {
return
}
if res.Err != nil {
l.log.Warn("memory extract", "step", step, "error", res.Err)
return
}
l.persistMemories(dctx, res.Items, step)
}()
}
// persistMemories writes extracted items to the memory store, scoping any item
// the extractor left unscoped to the loop's persona. Store failures are logged
// and never fatal, so one rejected item cannot abort a turn.
func (l *Loop) persistMemories(ctx context.Context, items []memory.MemoryItem, step int) {
for _, it := range items {
if it.PersonaID == "" && l.personaID != "" {
it.PersonaID = l.personaID
+228
View File
@@ -0,0 +1,228 @@
package loop
import (
"context"
"testing"
"time"
"git.yeij.top/AskaEth/Cyrene_v2/internal/capability/restrict"
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
)
// The LLM extractor is the async-capable implementation behind design/03 §1: the
// loop type-asserts this capability to detach extraction to a background
// goroutine, so the contract is locked here rather than discovered at runtime.
var (
_ memory.Extractor = (*memory.LLMExtractor)(nil)
_ asyncExtractor = (*memory.LLMExtractor)(nil)
_ memory.Extractor = (*memory.ManualExtractor)(nil)
)
// gatedExtractor is a memory.Extractor that also implements asyncExtractor. Its
// extraction blocks until release is closed (or ctx is canceled), so a test can
// prove the loop's turn finishes while extraction is still in flight, and that
// the extraction survives the caller's own cancellation.
type gatedExtractor struct {
release chan struct{}
started chan struct{}
items []memory.MemoryItem
dispatch int
}
func newGatedExtractor() *gatedExtractor {
return &gatedExtractor{
release: make(chan struct{}),
started: make(chan struct{}, 1),
items: []memory.MemoryItem{{
Scope: memory.ScopeUser,
Kind: memory.KindRelationship,
Content: "用户习惯:爱喝冰美式",
Confidence: 0.9,
DecayWeight: 1,
}},
}
}
func (g *gatedExtractor) Extract(ctx context.Context, _ []model.Message) ([]memory.MemoryItem, error) {
select {
case g.started <- struct{}{}:
default:
}
select {
case <-g.release:
return g.items, nil
case <-ctx.Done():
return nil, ctx.Err()
}
}
func (g *gatedExtractor) ExtractAsync(ctx context.Context, conv []model.Message) (<-chan memory.AsyncResult, error) {
g.dispatch++
out := make(chan memory.AsyncResult, 1)
go func() {
defer close(out)
items, err := g.Extract(ctx, conv)
out <- memory.AsyncResult{Items: items, Err: err}
}()
return out, nil
}
// TestExtractMemoryAsync_LLMExtractorThroughLoop wires the real LLM extractor
// (not a fake) into the loop: after the turn settles, the extractor's own model
// call runs in the background and its parsed items land in the store, so the
// production path (design/03 §1 LLM 异步自动提取) is exercised end to end.
func TestExtractMemoryAsync_LLMExtractorThroughLoop(t *testing.T) {
t.Parallel()
store := newTestMemoryStore(t)
ad := &mockAdapter{chat: []mgResp{
{resp: model.Response{Content: "记住了"}},
{resp: model.Response{Content: `[{"content":"用户爱喝冰美式","scope":"user","kind":"relationship","confidence":0.92}]`}},
}}
a := newTestAgent(t, ad, nil)
l := New(Options{
Agent: a, Memory: store, PersonaID: "persona-a", MaxRounds: 8,
Extractor: memory.NewLLMExtractor(ad, "persona-a", "owner"),
})
if _, err := l.Run(context.Background(), "sess", []model.Message{model.TextMessage(model.RoleUser, "我喜欢冰美式")}); err != nil {
t.Fatalf("Run: %v", err)
}
waitForMemoryCount(t, store, "persona-a", 1)
items, err := store.ListByPersona(context.Background(), "persona-a")
if err != nil {
t.Fatalf("ListByPersona: %v", err)
}
if items[0].Content != "用户爱喝冰美式" || items[0].Scope != memory.ScopeUser {
t.Fatalf("stored item = %+v, want the extracted user-scope memory", items[0])
}
if items[0].PersonaID != "persona-a" {
t.Fatalf("item persona = %q, want persona-a", items[0].PersonaID)
}
extractCalls := 0
for _, req := range ad.reqs {
if req.Purpose == "memory_extract" {
extractCalls++
}
}
if extractCalls != 1 {
t.Fatalf("memory_extract model calls = %d, want 1 (the LLM extractor drove the background call)", extractCalls)
}
}
// waitForMemoryCount polls the persona's stored memories until want is reached,
// failing the test when the extraction never lands.
func waitForMemoryCount(t *testing.T, store *memory.Store, personaID string, want int) {
t.Helper()
deadline := time.Now().Add(2 * time.Second)
for {
items, err := store.ListByPersona(context.Background(), personaID)
if err != nil {
t.Fatalf("ListByPersona: %v", err)
}
if len(items) == want {
return
}
if time.Now().After(deadline) {
t.Fatalf("stored memories = %d, want %d (extraction never landed)", len(items), want)
}
time.Sleep(5 * time.Millisecond)
}
}
// TestExtractMemoryAsync_DoesNotBlockTurn proves the turn returns while the LLM
// extraction is still running, and that the extraction completes (and persists)
// after the caller's context has already been canceled — the detached context
// keeps a request-scoped cancellation from aborting the background extraction.
func TestExtractMemoryAsync_DoesNotBlockTurn(t *testing.T) {
t.Parallel()
store := newTestMemoryStore(t)
ext := newGatedExtractor()
ad := &mockAdapter{chat: []mgResp{{resp: model.Response{Content: "记住了"}}}}
a := newTestAgent(t, ad, nil)
l := New(Options{Agent: a, Memory: store, Extractor: ext, PersonaID: "persona-a", MaxRounds: 8})
ctx, cancel := context.WithCancel(context.Background())
done := make(chan error, 1)
go func() {
_, err := l.Run(ctx, "sess", []model.Message{model.TextMessage(model.RoleUser, "记住 我爱喝冰美式")})
done <- err
}()
select {
case err := <-done:
if err != nil {
t.Fatalf("Run: %v", err)
}
case <-time.After(2 * time.Second):
t.Fatal("Run blocked on memory extraction: the async path must not gate the reply")
}
if ext.dispatch != 1 {
t.Fatalf("async dispatch count = %d, want 1 (one extraction per settled turn)", ext.dispatch)
}
items, err := store.ListByPersona(context.Background(), "persona-a")
if err != nil {
t.Fatalf("ListByPersona: %v", err)
}
if len(items) != 0 {
t.Fatalf("store already holds %d items after Run, want 0 (extraction still in flight)", len(items))
}
// The turn is over, so its context is canceled; the background extraction
// must still finish and persist.
cancel()
select {
case <-ext.started:
case <-time.After(2 * time.Second):
t.Fatal("extraction goroutine never started")
}
close(ext.release)
waitForMemoryCount(t, store, "persona-a", 1)
}
// TestExtractMemoryAsync_RestrictedEnvNeverDispatches proves the group-chat /
// stranger isolation still gates the async path: nothing is dispatched, so no
// owner-private memory can be written from a read-only conversation.
func TestExtractMemoryAsync_RestrictedEnvNeverDispatches(t *testing.T) {
t.Parallel()
store := newTestMemoryStore(t)
ext := newGatedExtractor()
l := New(Options{Memory: store, Extractor: ext, PersonaID: "persona-a"})
ctx := WithSessionEnv(context.Background(), SessionEnv{ActorEnv: restrict.ActorGroupMember, MemWritable: false})
l.extractMemoryAsync(ctx, []model.Message{model.TextMessage(model.RoleUser, "记住 我爱喝冰美式")}, 1)
if ext.dispatch != 0 {
t.Fatalf("async dispatch count = %d, want 0 (restricted context is read-only)", ext.dispatch)
}
items, err := store.ListByPersona(context.Background(), "persona-a")
if err != nil {
t.Fatalf("ListByPersona: %v", err)
}
if len(items) != 0 {
t.Fatalf("restricted async extract wrote %d items, want 0 (read-only isolation)", len(items))
}
}
// TestExtractMemoryAsync_ManualExtractorStaysSync proves the deterministic path
// is unchanged: an extractor without the async capability is still run inline, so
// the explicit "记住 X" memory is stored by the time the call returns.
func TestExtractMemoryAsync_ManualExtractorStaysSync(t *testing.T) {
t.Parallel()
store := newTestMemoryStore(t)
l := New(Options{Memory: store, Extractor: memory.NewManualExtractor("persona-a", "owner"), PersonaID: "persona-a"})
ctx := WithSessionEnv(context.Background(), OwnerEnv())
l.extractMemoryAsync(ctx, []model.Message{model.TextMessage(model.RoleUser, "记住 我爱喝冰美式")}, 1)
items, err := store.ListByPersona(context.Background(), "persona-a")
if err != nil {
t.Fatalf("ListByPersona: %v", err)
}
if len(items) != 1 {
t.Fatalf("stored memories = %d, want 1 (deterministic extractor runs inline)", len(items))
}
}
+7 -6
View File
@@ -18,8 +18,10 @@ import (
// timeout and fed back as RoleTool messages so the model can continue.
// A checkpoint is persisted at every step, every step is traced as a
// state_transition span (with an llm_call child and tool_call spans for each
// invocation), and after each step the memory Extractor runs with errors logged
// rather than fatal.
// invocation), and when the turn settles the memory Extractor runs over the
// turn's conversation (design/03 §1: the LLM extractor on a background
// goroutine, so extraction never delays the reply) with errors logged rather
// than fatal.
//
// When a turn settles with a Result, the OnTurnEnd hook is called once for that
// turn (never per step) and its mood label is recorded on Result.Mood, so the
@@ -84,7 +86,7 @@ func (l *Loop) Run(ctx context.Context, sessionID string, messages []model.Messa
res.Text = outcome.text
res.StopReason = outcome.stopReason
l.saveCheckpoint(ctx, sessionID, step, msgs, outcome.stopReason)
l.extractMemory(ctx, msgs, step)
l.extractMemoryAsync(ctx, msgs, step)
l.settleTurn(ctx, sessionID, msgs, res)
return res, nil
}
@@ -96,7 +98,6 @@ func (l *Loop) Run(ctx context.Context, sessionID string, messages []model.Messa
msgs = batch.messages
res.ToolCallsExecuted += batch.executed
l.saveCheckpoint(ctx, sessionID, step, msgs, agent.StopReasonToolCalls)
l.extractMemory(ctx, msgs, step)
// The critical-tool-loop safety net (or a terminating hook) stops the
// round without waiting for a real final answer.
@@ -104,7 +105,7 @@ func (l *Loop) Run(ctx context.Context, sessionID string, messages []model.Messa
res.Text = criticalToolLoopTerminalReason
res.StopReason = StopReasonToolLoopTerminated
l.saveCheckpoint(ctx, sessionID, step, msgs, StopReasonToolLoopTerminated)
l.extractMemory(ctx, msgs, step)
l.extractMemoryAsync(ctx, msgs, step)
l.settleTurn(ctx, sessionID, msgs, res)
return res, nil
}
@@ -114,7 +115,7 @@ func (l *Loop) Run(ctx context.Context, sessionID string, messages []model.Messa
res.Steps = l.maxRounds
res.StopReason = StopReasonMaxRounds
l.saveCheckpoint(ctx, sessionID, l.maxRounds, msgs, StopReasonMaxRounds)
l.extractMemory(ctx, msgs, l.maxRounds)
l.extractMemoryAsync(ctx, msgs, l.maxRounds)
l.settleTurn(ctx, sessionID, msgs, res)
return res, nil
}
+311
View File
@@ -0,0 +1,311 @@
package gateway
import (
"context"
"fmt"
"net/http"
"sort"
"strconv"
"strings"
"time"
"unicode/utf8"
apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
"git.yeij.top/AskaEth/Cyrene_v2/internal/services/backthink"
)
// Notification feed limits (design/10 §3 #16). Compile-time constants so no bare
// magic number appears in the run path (project rule §10).
const (
defaultNotificationLimit = 50
maxNotificationLimit = 200
// notificationFetchFactor widens the per-source read. The merged page must be
// the newest N of the union, which the per-source newest-N always contains,
// but with a `before` cursor one source can dominate the newest window and
// starve the other — the factor pays for that.
notificationFetchFactor = 4
// notificationBodyRunes caps a backthink summary in the feed; the full text
// stays available on GET /api/v1/admin/backthink.
notificationBodyRunes = 200
)
// The unified feed's families, used both as the item `type` and as the `?type=`
// filter. They are derived from the sources the composition root already has
// (design/10 §3 #16: 先聚合现有源为统一 feed,避免新建重模型).
const (
// NotificationTypeSystem is a system/security operation: backup & restore,
// JWT rotation, API-key revocation, plugin install/uninstall, tool policy.
NotificationTypeSystem = "system"
// NotificationTypeChannel is a channel lifecycle or connection event
// (channel.open / close / save / reject / login).
NotificationTypeChannel = "channel"
// NotificationTypeBackthink is one proactive push the background thinker
// decided to send.
NotificationTypeBackthink = "backthink"
// NotificationTypeAudit is the remaining admin audit trail: personas, memory,
// users, RAG, sessions, uploads, audio.
NotificationTypeAudit = "audit"
)
// Provenance labels carried on an item's `source` field.
const (
notificationSourceAudit = "audit"
notificationSourceBackthink = "backthink"
// notificationIDPrefixAudit / ...Backthink namespace the source's own record id
// so the merged feed has stable, collision-free, client-dedupable ids.
notificationIDPrefixAudit = "audit:"
notificationIDPrefixBackthink = "backthink:"
)
// AdminNotification is one item of the unified notification feed (design/10 §3
// #16). It is a read-only projection of an existing record — audit rows and
// backthink records — never a new persisted model: `id` is "<source>:<原生 id>",
// `title`/`body` are derived from the source record, and `createdAt` is epoch
// milliseconds.
type AdminNotification struct {
ID string `json:"id"`
Type string `json:"type"`
Title string `json:"title"`
Body string `json:"body,omitempty"`
Source string `json:"source"`
CreatedAt int64 `json:"createdAt"`
}
// adminListNotifications returns the unified notification feed (owner/admin
// read): the admin audit trail and the background thinker's proactive pushes,
// merged newest-first and filterable by family and by a `before` cursor.
//
// A source that is not injected contributes no items — the feed reports what
// actually exists instead of fabricating a family — so a deployment without the
// backthink service simply has no `backthink` items.
func (s *Server) adminListNotifications(w http.ResponseWriter, r *http.Request) {
limit := parseNotificationLimit(r)
typ := strings.TrimSpace(r.URL.Query().Get("type"))
if typ != "" && !validNotificationType(typ) {
writeError(w, apperr.Wrap(apperr.ErrBadRequest, "invalid_type",
"type must be one of system|channel|backthink|audit"))
return
}
before, hasBefore := parseNotificationBefore(r)
items, err := s.notificationItems(r.Context(), notificationFetchLimit(limit))
if err != nil {
s.log.Error("list notifications", "err", err)
writeError(w, apperr.Wrap(apperr.ErrInternal, "notifications_failed",
"failed to list notifications"))
return
}
out := make([]AdminNotification, 0, limit)
for _, it := range items {
if typ != "" && it.Type != typ {
continue
}
if hasBefore && it.CreatedAt > before {
continue
}
out = append(out, it)
if len(out) == limit {
break
}
}
writeJSON(w, http.StatusOK, out)
}
// notificationItems reads both sources and returns their merge, newest first. A
// source failure is returned (never swallowed into a silently shorter feed), so
// the endpoint answers a clear error instead of pretending there was no event.
func (s *Server) notificationItems(ctx context.Context, fetch int) ([]AdminNotification, error) {
auditItems, err := s.notificationsFromAudit(ctx, fetch)
if err != nil {
return nil, err
}
btItems, err := s.notificationsFromBackthink(ctx, fetch)
if err != nil {
return nil, err
}
items := append(auditItems, btItems...)
sort.SliceStable(items, func(i, j int) bool {
if items[i].CreatedAt != items[j].CreatedAt {
return items[i].CreatedAt > items[j].CreatedAt
}
// Descending id keeps the order deterministic for items sharing a
// millisecond (the cursor can split one millisecond across pages).
return items[i].ID > items[j].ID
})
return items, nil
}
// notificationsFromAudit projects the admin audit trail (audit_logs, persisted
// by NewSQLiteAuditStore) into feed items. The fallback in-memory store holds
// only records really appended in this process, so an unwired store yields an
// empty family rather than fabricated entries.
func (s *Server) notificationsFromAudit(ctx context.Context, fetch int) ([]AdminNotification, error) {
if s.obs == nil || s.obs.audit == nil {
return nil, nil
}
records, err := s.obs.audit.List(ctx, fetch)
if err != nil {
return nil, fmt.Errorf("gateway: notification audit source: %w", err)
}
out := make([]AdminNotification, 0, len(records))
for _, rec := range records {
out = append(out, AdminNotification{
ID: notificationIDPrefixAudit + strconv.FormatInt(rec.ID, 10),
Type: notificationTypeOfAudit(rec.What),
Title: rec.What,
Body: notificationAuditBody(rec),
Source: notificationSourceAudit,
CreatedAt: notificationAuditAt(rec.When),
})
}
return out, nil
}
// notificationsFromBackthink projects the background thinker's records into feed
// items. Only records that decided to push are notifications (a plain thinking
// record is not an event the owner needs to be told about); each carries the
// delivery state so the feed never claims an undelivered push was sent.
func (s *Server) notificationsFromBackthink(ctx context.Context, fetch int) ([]AdminNotification, error) {
if s.backthink == nil {
return nil, nil
}
records, err := s.backthink.List(ctx, fetch)
if err != nil {
return nil, fmt.Errorf("gateway: notification backthink source: %w", err)
}
out := make([]AdminNotification, 0, len(records))
for _, rec := range records {
if !rec.ShouldPush {
continue
}
out = append(out, AdminNotification{
ID: notificationIDPrefixBackthink + strconv.FormatInt(rec.ID, 10),
Type: NotificationTypeBackthink,
Title: backthinkNotificationTitle(rec),
Body: clipRunes(strings.TrimSpace(rec.Conclusion), notificationBodyRunes),
Source: notificationSourceBackthink,
CreatedAt: rec.At.UnixMilli(),
})
}
return out, nil
}
// notificationTypeOfAudit classifies an audit operation into a feed family: the
// channel lifecycle is `channel`, and the system/plugin/policy operations are
// `system`; everything else stays `audit`.
func notificationTypeOfAudit(what string) string {
switch {
case strings.HasPrefix(what, "channel."):
return NotificationTypeChannel
case strings.HasPrefix(what, "system."),
strings.HasPrefix(what, "plugin."),
strings.HasPrefix(what, "policy."):
return NotificationTypeSystem
default:
return NotificationTypeAudit
}
}
// notificationAuditBody derives an audit item's body from its who/what/result
// trail, e.g. "owner:owner · ok".
func notificationAuditBody(rec AuditRecord) string {
parts := make([]string, 0, 2)
if who := strings.TrimSpace(rec.Who); who != "" {
parts = append(parts, who)
}
if result := strings.TrimSpace(rec.Result); result != "" {
parts = append(parts, result)
}
return strings.Join(parts, " · ")
}
// notificationAuditAt parses an audit record's RFC3339 timestamp into epoch
// milliseconds. An unparseable timestamp yields 0: the item still appears (oldest
// first) instead of being dropped or stamped with a made-up time.
func notificationAuditAt(when string) int64 {
ts, err := time.Parse(time.RFC3339Nano, strings.TrimSpace(when))
if err != nil {
return 0
}
return ts.UnixMilli()
}
// backthinkNotificationTitle labels one proactive push with its trigger and
// delivery state, so the feed distinguishes "sent" from "decided but not
// delivered" (route none / no online client / push failure).
func backthinkNotificationTitle(rec backthink.Record) string {
state := "未送达"
if rec.PushResult.Pushed {
state = "已送达"
}
if trigger := strings.TrimSpace(rec.Trigger); trigger != "" {
return "主动推送(" + trigger + " · " + state + ")"
}
return "主动推送(" + state + ")"
}
// clipRunes truncates s to at most max runes, appending an ellipsis when it was
// cut. It never splits a multi-byte rune.
func clipRunes(s string, max int) string {
if max <= 0 || utf8.RuneCountInString(s) <= max {
return s
}
runes := []rune(s)
return string(runes[:max]) + "…"
}
// parseNotificationLimit parses the ?limit= query param, clamping to
// [1, maxNotificationLimit] and selecting defaultNotificationLimit when absent or
// invalid.
func parseNotificationLimit(r *http.Request) int {
n, err := strconv.Atoi(r.URL.Query().Get("limit"))
if err != nil || n <= 0 {
return defaultNotificationLimit
}
if n > maxNotificationLimit {
return maxNotificationLimit
}
return n
}
// parseNotificationBefore parses the ?before= epoch-millisecond cursor. The
// cursor is inclusive (items with createdAt <= before are returned): the sources
// resolve to milliseconds, so a page boundary can fall inside one millisecond,
// and the client deduplicates by id. An absent or malformed cursor means "from
// the newest item".
func parseNotificationBefore(r *http.Request) (int64, bool) {
raw := strings.TrimSpace(r.URL.Query().Get("before"))
if raw == "" {
return 0, false
}
ms, err := strconv.ParseInt(raw, 10, 64)
if err != nil || ms <= 0 {
return 0, false
}
return ms, true
}
// notificationFetchLimit widens a page request into the per-source read window,
// capped at maxObsLimit (the audit store's own ceiling) and never below the page.
func notificationFetchLimit(limit int) int {
fetch := limit * notificationFetchFactor
if fetch > maxObsLimit {
fetch = maxObsLimit
}
if fetch < limit {
fetch = limit
}
return fetch
}
// validNotificationType reports whether t names a feed family. An unknown family
// is rejected with 400 rather than answered with a silently empty feed.
func validNotificationType(t string) bool {
switch t {
case NotificationTypeSystem, NotificationTypeChannel, NotificationTypeBackthink, NotificationTypeAudit:
return true
default:
return false
}
}
@@ -0,0 +1,357 @@
package gateway
import (
"context"
"encoding/json"
"errors"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
"git.yeij.top/AskaEth/Cyrene_v2/internal/services/backthink"
)
// stubAuditFeed is an AuditStore over scripted records (already newest first),
// so the feed tests control millisecond timestamps exactly — the in-memory
// fallback store only keeps second precision.
type stubAuditFeed struct {
records []AuditRecord
err error
}
func (s *stubAuditFeed) Append(context.Context, string, string, string, time.Time) error { return nil }
func (s *stubAuditFeed) List(_ context.Context, limit int) ([]AuditRecord, error) {
if s.err != nil {
return nil, s.err
}
if limit <= 0 || limit > len(s.records) {
limit = len(s.records)
}
return append([]AuditRecord(nil), s.records[:limit]...), nil
}
// stubBackthinkFeed is a BackthinkStore over scripted records (newest first).
type stubBackthinkFeed struct {
records []backthink.Record
err error
}
func (s *stubBackthinkFeed) List(_ context.Context, limit int) ([]backthink.Record, error) {
if s.err != nil {
return nil, s.err
}
if limit <= 0 || limit > len(s.records) {
limit = len(s.records)
}
return append([]backthink.Record(nil), s.records[:limit]...), nil
}
// notificationMS renders epoch milliseconds as the RFC3339 timestamp an audit
// record carries.
func notificationMS(ms int64) string {
return time.UnixMilli(ms).UTC().Format(time.RFC3339Nano)
}
// notificationFeedFixture scripts both sources: channel + system + audit rows in
// the audit trail and one delivered / one undelivered / one non-push backthink
// record.
func notificationFeedFixture() (*stubAuditFeed, *stubBackthinkFeed) {
audit := &stubAuditFeed{records: []AuditRecord{
{ID: 5, Who: "owner:owner", What: "channel.open", When: notificationMS(3000), Result: "ok"},
{ID: 4, Who: "bridge:telegram", What: "channel.reject", When: notificationMS(2900), Result: "群聊白名单外"},
{ID: 3, Who: "owner:owner", What: "system.backup", When: notificationMS(2000), Result: "ok"},
{ID: 2, Who: "owner:owner", What: "persona.update", When: notificationMS(1000), Result: "ok"},
{ID: 1, Who: "owner:owner", What: "plugin.install", When: notificationMS(500), Result: "error"},
}}
bt := &stubBackthinkFeed{records: []backthink.Record{
{ID: 8, Trigger: "idle", At: time.UnixMilli(2600), Conclusion: "该喝水了", ShouldPush: true,
PushResult: backthink.PushResult{Pushed: true}},
{ID: 7, Trigger: "event", At: time.UnixMilli(2400), Conclusion: "只是想了一下", ShouldPush: false},
{ID: 6, Trigger: "heartbeat", At: time.UnixMilli(1500), Conclusion: strings.Repeat("很长的结论", 60), ShouldPush: true},
}}
return audit, bt
}
// listNotifications calls the endpoint and decodes the feed.
func listNotifications(t *testing.T, ts *httptest.Server, tok, query string) (int, []AdminNotification, []byte) {
t.Helper()
resp, body := doReq(t, http.MethodGet, ts.URL+"/api/v1/admin/notifications"+query, nil, tok)
if resp.StatusCode != http.StatusOK {
return resp.StatusCode, nil, body
}
var out []AdminNotification
if err := json.Unmarshal(decodeBody(t, body)["data"], &out); err != nil {
t.Fatalf("decode notifications %s: %v", body, err)
}
return resp.StatusCode, out, body
}
// TestAdminListNotifications_MergesAuditAndBackthink proves the feed is the two
// existing sources merged newest-first with source-namespaced ids, the audit
// family classification, and that a backthink record which decided not to push is
// not an event.
func TestAdminListNotifications_MergesAuditAndBackthink(t *testing.T) {
t.Parallel()
audit, bt := notificationFeedFixture()
_, ts, jwt := buildEnv(t, nil, Deps{AuditStore: audit, Backthink: bt})
tok := signAny(t, jwt, "acct", auth.RoleOwner)
status, items, body := listNotifications(t, ts, tok, "")
if status != http.StatusOK {
t.Fatalf("status = %d, want 200 (body=%s)", status, body)
}
wantOrder := []struct {
id string
typ string
src string
when int64
}{
{"audit:5", NotificationTypeChannel, notificationSourceAudit, 3000},
{"audit:4", NotificationTypeChannel, notificationSourceAudit, 2900},
{"backthink:8", NotificationTypeBackthink, notificationSourceBackthink, 2600},
{"audit:3", NotificationTypeSystem, notificationSourceAudit, 2000},
{"backthink:6", NotificationTypeBackthink, notificationSourceBackthink, 1500},
{"audit:2", NotificationTypeAudit, notificationSourceAudit, 1000},
{"audit:1", NotificationTypeSystem, notificationSourceAudit, 500},
}
if len(items) != len(wantOrder) {
t.Fatalf("feed = %d items, want %d (%+v)", len(items), len(wantOrder), items)
}
for i, want := range wantOrder {
got := items[i]
if got.ID != want.id || got.Type != want.typ || got.Source != want.src || got.CreatedAt != want.when {
t.Fatalf("feed[%d] = %+v, want {id:%s type:%s source:%s createdAt:%d}",
i, got, want.id, want.typ, want.src, want.when)
}
if got.Title == "" {
t.Fatalf("feed[%d] has no title: %+v", i, got)
}
if want.id == "backthink:8" && !strings.Contains(got.Title, "已送达") {
t.Fatalf("backthink title = %q, want the delivery state", got.Title)
}
}
// The undelivered push is older and its conclusion is long: both the body cap
// and the "未送达" label must show.
for _, it := range items {
if it.ID == "backthink:6" {
if !strings.Contains(it.Title, "未送达") {
t.Fatalf("backthink title = %q, want 未送达 for an undelivered push", it.Title)
}
if len([]rune(it.Body)) > notificationBodyRunes+1 {
t.Fatalf("body = %d runes, want <= %d (+ellipsis)", len([]rune(it.Body)), notificationBodyRunes)
}
}
}
// A thinking record that decided not to push never becomes a notification.
for _, it := range items {
if it.ID == "backthink:7" {
t.Fatalf("non-push backthink record leaked into the feed: %+v", it)
}
}
}
// TestAdminListNotifications_TypeFilter proves `?type=` selects one family and
// that a family without any source data answers an empty feed (never a fabricated
// row).
func TestAdminListNotifications_TypeFilter(t *testing.T) {
t.Parallel()
audit, bt := notificationFeedFixture()
_, ts, jwt := buildEnv(t, nil, Deps{AuditStore: audit, Backthink: bt})
tok := signAny(t, jwt, "acct", auth.RoleAdmin)
cases := []struct {
query string
want []string
}{
{"?type=channel", []string{"audit:5", "audit:4"}},
{"?type=backthink", []string{"backthink:8", "backthink:6"}},
{"?type=system", []string{"audit:3", "audit:1"}},
{"?type=audit", []string{"audit:2"}},
}
for _, tc := range cases {
status, items, body := listNotifications(t, ts, tok, tc.query)
if status != http.StatusOK {
t.Fatalf("%s status = %d, want 200 (body=%s)", tc.query, status, body)
}
if len(items) != len(tc.want) {
t.Fatalf("%s = %+v, want %v", tc.query, items, tc.want)
}
for i, want := range tc.want {
if items[i].ID != want {
t.Fatalf("%s[%d] = %s, want %s", tc.query, i, items[i].ID, want)
}
}
}
// An empty source (no backthink service injected) yields an empty family.
_, auditOnly, jwtOnly := buildEnv(t, nil, Deps{AuditStore: audit})
tokAudit := signAny(t, jwtOnly, "acct", auth.RoleOwner)
status, items, body := listNotifications(t, auditOnly, tokAudit, "?type=backthink")
if status != http.StatusOK || len(items) != 0 {
t.Fatalf("no-backthink feed = %d items / status %d, want 0 / 200 (body=%s)", len(items), status, body)
}
}
// TestAdminListNotifications_BeforeCursorPagination proves the `before` cursor:
// pages walk older, the cursor item itself is included (the sources resolve to
// milliseconds and the client dedupes by id), and `limit` caps a page.
func TestAdminListNotifications_BeforeCursorPagination(t *testing.T) {
t.Parallel()
audit, bt := notificationFeedFixture()
_, ts, jwt := buildEnv(t, nil, Deps{AuditStore: audit, Backthink: bt})
tok := signAny(t, jwt, "acct", auth.RoleOwner)
status, page1, body := listNotifications(t, ts, tok, "?limit=2")
if status != http.StatusOK {
t.Fatalf("page1 status = %d, want 200 (body=%s)", status, body)
}
if len(page1) != 2 || page1[0].ID != "audit:5" || page1[1].ID != "audit:4" {
t.Fatalf("page1 = %+v, want [audit:5 audit:4]", page1)
}
status, page2, body := listNotifications(t, ts, tok, "?limit=2&before=2900")
if status != http.StatusOK {
t.Fatalf("page2 status = %d, want 200 (body=%s)", status, body)
}
if len(page2) != 2 || page2[0].ID != "audit:4" || page2[1].ID != "backthink:8" {
t.Fatalf("page2 = %+v, want [audit:4 backthink:8] (cursor inclusive)", page2)
}
status, page3, body := listNotifications(t, ts, tok, "?limit=2&before=2600")
if status != http.StatusOK {
t.Fatalf("page3 status = %d, want 200 (body=%s)", status, body)
}
if len(page3) != 2 || page3[0].ID != "backthink:8" || page3[1].ID != "audit:3" {
t.Fatalf("page3 = %+v, want [backthink:8 audit:3]", page3)
}
// A cursor older than every item ends the walk with an empty page.
status, tail, body := listNotifications(t, ts, tok, "?before=1")
if status != http.StatusOK || len(tail) != 0 {
t.Fatalf("tail = %+v / status %d, want empty / 200 (body=%s)", tail, status, body)
}
}
// TestAdminListNotifications_NoSourcesNoFabrication proves the honest empty feed:
// with neither source injected the endpoint returns an empty array, not invented
// notices.
func TestAdminListNotifications_NoSourcesNoFabrication(t *testing.T) {
t.Parallel()
_, ts, jwt := buildEnv(t, nil, Deps{})
tok := signAny(t, jwt, "acct", auth.RoleOwner)
status, items, body := listNotifications(t, ts, tok, "")
if status != http.StatusOK {
t.Fatalf("status = %d, want 200 (body=%s)", status, body)
}
if len(items) != 0 {
t.Fatalf("unwired feed = %+v, want empty", items)
}
if got := strings.TrimSpace(string(decodeBody(t, body)["data"])); got != "[]" {
t.Fatalf("data = %s, want []", got)
}
}
// TestAdminListNotifications_Errors proves the endpoint fails loudly: an unknown
// family is a 400, a failing source is a 500 (never a silently shortened feed),
// and a viewer is rejected by RBAC.
func TestAdminListNotifications_Errors(t *testing.T) {
t.Parallel()
audit, bt := notificationFeedFixture()
_, ts, jwt := buildEnv(t, nil, Deps{AuditStore: audit, Backthink: bt})
tok := signAny(t, jwt, "acct", auth.RoleOwner)
status, _, body := listNotifications(t, ts, tok, "?type=bogus")
if status != http.StatusBadRequest {
t.Fatalf("unknown type status = %d, want 400 (body=%s)", status, body)
}
broken := &stubAuditFeed{err: errors.New("audit exploded")}
_, brokenTS, brokenJWT := buildEnv(t, nil, Deps{AuditStore: broken, Backthink: bt})
status, _, body = listNotifications(t, brokenTS, signAny(t, brokenJWT, "acct", auth.RoleOwner), "")
if status != http.StatusInternalServerError {
t.Fatalf("broken source status = %d, want 500 (body=%s)", status, body)
}
viewer := signAny(t, jwt, "acct", auth.RoleViewer)
if status, _, _ := listNotifications(t, ts, viewer, ""); status != http.StatusForbidden {
t.Fatalf("viewer status = %d, want 403", status)
}
}
// TestNotificationAuditAt_ParsesBothStoreFormats locks the timestamp contract with
// the two real audit stores: SQLiteAuditStore writes RFC3339Nano, the in-memory
// fallback writes RFC3339, and an unparseable value degrades to 0 (oldest) rather
// than being dropped or faked.
func TestNotificationAuditAt_ParsesBothStoreFormats(t *testing.T) {
t.Parallel()
base := time.Date(2026, 9, 30, 10, 0, 0, 123456000, time.UTC)
cases := []struct {
when string
want int64
}{
{base.Format(time.RFC3339Nano), base.UnixMilli()},
{base.Truncate(time.Second).Format(time.RFC3339), base.Truncate(time.Second).UnixMilli()},
{"2026-09-30T18:00:00+08:00", time.Date(2026, 9, 30, 10, 0, 0, 0, time.UTC).UnixMilli()},
{"", 0},
{"not-a-time", 0},
}
for _, tc := range cases {
if got := notificationAuditAt(tc.when); got != tc.want {
t.Fatalf("notificationAuditAt(%q) = %d, want %d", tc.when, got, tc.want)
}
}
}
// TestNotificationQueryParsing locks the query knobs: the limit defaults to 50 and
// clamps at 200, and an absent or malformed `before` means "from newest".
func TestNotificationQueryParsing(t *testing.T) {
t.Parallel()
limitCases := []struct {
raw string
want int
}{
{"", defaultNotificationLimit},
{"?limit=0", defaultNotificationLimit},
{"?limit=-3", defaultNotificationLimit},
{"?limit=abc", defaultNotificationLimit},
{"?limit=10", 10},
{"?limit=1000", maxNotificationLimit},
}
for _, tc := range limitCases {
req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/notifications"+tc.raw, nil)
if got := parseNotificationLimit(req); got != tc.want {
t.Fatalf("parseNotificationLimit(%q) = %d, want %d", tc.raw, got, tc.want)
}
}
beforeCases := []struct {
raw string
want int64
wantOK bool
}{
{"", 0, false},
{"?before=0", 0, false},
{"?before=-5", 0, false},
{"?before=abc", 0, false},
{"?before=1700000000000", 1700000000000, true},
}
for _, tc := range beforeCases {
req := httptest.NewRequest(http.MethodGet, "/api/v1/admin/notifications"+tc.raw, nil)
got, ok := parseNotificationBefore(req)
if got != tc.want || ok != tc.wantOK {
t.Fatalf("parseNotificationBefore(%q) = %d,%v, want %d,%v", tc.raw, got, ok, tc.want, tc.wantOK)
}
}
if got := notificationFetchLimit(defaultNotificationLimit); got < defaultNotificationLimit || got > maxObsLimit {
t.Fatalf("notificationFetchLimit(50) = %d, want within [50, %d]", got, maxObsLimit)
}
if got := notificationFetchLimit(maxNotificationLimit); got != maxObsLimit {
t.Fatalf("notificationFetchLimit(200) = %d, want the %d cap", got, maxObsLimit)
}
}
+4
View File
@@ -515,6 +515,10 @@ func (s *Server) Handler() http.Handler {
mux.Handle("GET /api/v1/admin/observability/metrics", adminAuth(http.HandlerFunc(s.adminObservabilityMetrics)))
mux.Handle("GET /api/v1/admin/observability/trace", adminAuth(http.HandlerFunc(s.adminObservabilityTrace)))
mux.Handle("GET /api/v1/admin/observability/audit", adminAuth(http.HandlerFunc(s.adminObservabilityAudit)))
// Unified notification feed (design/10 §3 #16): a read-only projection of the
// audit trail + backthink pushes, so the panel's notification page needs no
// new persisted model.
mux.Handle("GET /api/v1/admin/notifications", adminAuth(http.HandlerFunc(s.adminListNotifications)))
mux.Handle("POST /api/v1/admin/plugins/policy", s.auth.Authorize(auth.RoleOwner)(http.HandlerFunc(s.adminSetPolicy)))
// Admin writes: owner-only, audited. Reads above accept owner/admin; writes