feat(backthink/admin): ③b — rag/delete 真实现 + D1 推送出口钩子(自建优先→个推兜底) + api-reference 补 D2/D3/D5 补丁
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

- B5: POST /admin/rag/delete 真做(DeleteDocument→DeleteProject 级联删章节+索引清理, owner+审计, 200/404/500, 500降级兜底); users/iot scenarios+rules 诚实501(无用户表/IoT场景规则模型, 消息写明缺什么, 不伪造), 锁住 501+not_implemented
- D1: backthink/push_outlet.go PushExporter{Export}; pushOutlet 自建HTTP(2xx=送达, token仅Authorization头+error脱敏)优先→Getui兜底(未接入, 诚实日志'getui not integrated'+(false,nil)); backthink.Deps.Exporter → pusher.withExporter, Push 在WS/IM后 exportAsync(detached+5s超时, 失败仅日志, 不破坏现有投递, 限流不上报); config PushOutletConfig(PUSH_EXPORTER_* + GETUI_*占位)
- 前端 Rag.tsx/api.ts 删除后 reload + 类型; Docs/api-client v0.31 + api-reference(#23 owner/200-404, §8.4, 端点表PATCH/DELETE messages + pinned + messages?q=)
- 测试(push_outlet/admin_rag_delete/admin_honest501/knowledge store), 后端+前端build全绿+3平台交叉编译
- 刻意: Getui SDK 未接入(无SDK不硬造), 主人自建服务填 PUSH_EXPORTER_URL/TOKEN 即可
This commit is contained in:
AskaEth committed 2026-09-09 00:08:29 +08:00
1 parent 844b2a74c1
commit 2dee372fb2
23 files changed
+927 -95

No files matched your search

+5 -1
View File
@@ -82,6 +82,10 @@ type Deps struct {
Active ActiveClient
// IM is the IM bridge sink, used as the fallback when no active client is up.
IM IMAdapter
// Exporter mirrors a proactive message to the external push outlet (the
// owner's self-hosted unified push service, then Getui). Optional: nil
// disables the hook. It never blocks or breaks the Active/IM delivery.
Exporter PushExporter
// Gate is the proactive-push rate limiter. Nil builds a default from Config.
Gate PushGate
// DB is the SQLite handle for the think store. Required.
@@ -146,7 +150,7 @@ func New(cfg Config, deps Deps) (*Backthink, error) {
}
pusher := deps.Pusher
if pusher == nil {
pusher = newPusher(deps.Active, deps.IM, gate, log)
pusher = newPusher(deps.Active, deps.IM, gate, log).withExporter(deps.Exporter)
}
now := deps.Now
+51 -5
View File
@@ -128,20 +128,34 @@ type Pusher interface {
// pusher is the concrete Pusher: it consults the gate, then routes the message to
// exactly one target — the active client for a "web" hint, otherwise the IM bridge.
// After the local delivery it mirrors the message to the optional push outlet
// (self-hosted service → Getui fallback) without blocking that delivery.
type pusher struct {
active ActiveClient
im IMAdapter
gate PushGate
log *slog.Logger
active ActiveClient
im IMAdapter
gate PushGate
exporter PushExporter
log *slog.Logger
// exportDone, when non-nil, receives one value after each asynchronous export
// completes. It exists so tests can deterministically observe the hook; the
// send is non-blocking, so a full channel never stalls the exporter.
exportDone chan struct{}
}
// newPusher builds a Pusher from the optional active-client sink, IM sink and
// rate gate. Any of them may be nil; a nil target simply makes that route
// unavailable.
// unavailable. The push outlet is attached separately with withExporter.
func newPusher(active ActiveClient, im IMAdapter, gate PushGate, log *slog.Logger) *pusher {
return &pusher{active: active, im: im, gate: gate, log: log}
}
// withExporter attaches the push outlet hook and returns the pusher for fluent
// use. A nil exporter leaves the hook disabled.
func (p *pusher) withExporter(exporter PushExporter) *pusher {
p.exporter = exporter
return p
}
// Push implements Pusher: it applies the rate gate, then routes the message to a
// single target. A "web" hint reaches the active web/native client; every other
// hint ("im", "auto", or a concrete platform) goes over the IM bridge once, where
@@ -192,6 +206,11 @@ func (p *pusher) Push(ctx context.Context, req PushRequest) PushResult {
if res.Pushed && p.gate != nil && !eventDriven {
p.gate.RecordPush(kind)
}
// D1: mirror the proactive message to the external push outlet (self-hosted
// unified push service → Getui fallback). Fire-and-forget: a slow or failing
// outlet never delays or breaks the local delivery above, and a rate-limited
// push returned before reaching here.
p.exportAsync(msg)
res = annotateHint(res, req.ChannelHint)
if eventDriven {
res.Bypassed = true
@@ -200,6 +219,33 @@ func (p *pusher) Push(ctx context.Context, req PushRequest) PushResult {
return res
}
// exportAsync reports msg to the push outlet on a detached, bounded goroutine so
// the proactive path never blocks on the outlet. A nil exporter (hook disabled)
// or a nil outlet result is a no-op; a delivery miss or error is only logged.
func (p *pusher) exportAsync(msg adapter.UnifiedMessage) {
if p.exporter == nil {
return
}
timeout := defaultExportTimeout
go func() {
ctx, cancel := context.WithTimeout(context.Background(), timeout)
defer cancel()
delivered, err := p.exporter.Export(ctx, msg)
switch {
case err != nil:
p.log.Warn("push outlet export failed", "error", err)
case !delivered:
p.log.Info("push outlet did not deliver", "hint", "getui fallback not integrated")
}
if p.exportDone != nil {
select {
case p.exportDone <- struct{}{}:
default:
}
}
}()
}
// pushActive delivers only to the active web/native client.
func (p *pusher) pushActive(ctx context.Context, msg adapter.UnifiedMessage) PushResult {
if p.active != nil {
+193
View File
@@ -0,0 +1,193 @@
package backthink
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"log/slog"
"net/http"
"strings"
"time"
"git.yeij.top/AskaEth/Cyrene_v2/internal/channel/adapter"
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
)
// The push outlet (D1, design/12 §4/§6): proactive messages are mirrored to an
// external push service so the owner's mobile client is reached even when no
// WebSocket client or IM channel is live. Delivery is two-tier by design:
//
// 1. the owner's self-hosted unified push service (primary; PUSH_EXPORTER_URL),
// 2. Getui (个推) as the fallback for when the self-hosted service is down.
//
// Tier 2 has no SDK integration yet, so an unavailable primary logs an explicit
// "Getui fallback not integrated" note and reports not-delivered instead of
// pretending the message went out. The hook is fire-and-forget: it never delays
// or breaks the existing active-client / IM delivery.
// defaultExportTimeout bounds one export attempt so a hung endpoint cannot pin a
// goroutine forever.
const defaultExportTimeout = 5 * time.Second
// maxExportResponseBytes caps how much of the outlet's response body is drained
// before the connection is reused, so a hostile/buggy endpoint cannot stream an
// unbounded body into memory.
const maxExportResponseBytes = 4 << 10
// PushExporter reports one proactive message to an external push outlet. Export
// must be safe for concurrent use and must honor ctx. A nil error with
// delivered=false means the outlet could not deliver (for example the fallback
// tier is not wired); the caller treats that as a logged miss, never a failure
// of the local push path.
type PushExporter interface {
Export(ctx context.Context, msg adapter.UnifiedMessage) (delivered bool, err error)
}
// PushOutletConfig carries the push-outlet wiring. Enabled=false disables the
// hook entirely (NewPushOutlet returns nil). URL/Token/Timeout describe the
// self-hosted primary service; the Getui* fields are reserved for the deferred
// fallback and are not consumed yet.
type PushOutletConfig struct {
// Enabled turns the outlet hook on.
Enabled bool
// URL is the self-hosted unified push service endpoint (HTTP POST JSON).
// Empty leaves the primary tier unconfigured.
URL string
// Token is sent as "Authorization: Bearer <token>". It is never logged.
Token string
// Timeout bounds one export attempt. Zero uses defaultExportTimeout.
Timeout time.Duration
// Log is the base logger. Nil uses a discard logger.
Log *slog.Logger
}
// NewPushOutlet builds the two-tier push outlet from cfg. It returns nil when
// the hook is disabled, so the pusher simply skips the export step. When it is
// enabled the primary tier is the self-hosted HTTP endpoint (present only when
// URL is set) and the fallback tier is Getui, which is not integrated yet.
func NewPushOutlet(cfg PushOutletConfig) PushExporter {
if !cfg.Enabled {
return nil
}
log := logger.WithSource(baseLog(cfg.Log), "services/backthink/push_outlet")
timeout := cfg.Timeout
if timeout <= 0 {
timeout = defaultExportTimeout
}
var primary PushExporter
if url := strings.TrimSpace(cfg.URL); url != "" {
primary = &httpPushExporter{
url: url,
token: cfg.Token,
client: &http.Client{Timeout: timeout},
}
} else {
log.Warn("push outlet enabled but PUSH_EXPORTER_URL is empty; only the (unwired) Getui fallback remains")
}
log.Info("push outlet configured", "primary", primary != nil, "fallback", "getui (not integrated)")
return &pushOutlet{primary: primary, log: log}
}
// pushOutlet is the two-tier exporter: self-hosted service first, Getui second.
// The fallback is nil until the Getui SDK is integrated, so a primary miss is
// logged and reported as not delivered rather than silently dropped.
type pushOutlet struct {
primary PushExporter
fallback PushExporter
log *slog.Logger
}
// Export implements PushExporter. It tries the primary tier and, when that does
// not deliver, the fallback tier. With no fallback wired it logs the pending
// integration and returns (false, nil): the caller treats that as a miss, never
// as a reason to fail the proactive push.
func (o *pushOutlet) Export(ctx context.Context, msg adapter.UnifiedMessage) (bool, error) {
if o.primary != nil {
delivered, err := o.primary.Export(ctx, msg)
if err == nil && delivered {
return true, nil
}
if err != nil {
o.log.Warn("push outlet primary failed", "error", err)
} else {
o.log.Warn("push outlet primary did not deliver")
}
}
if o.fallback != nil {
return o.fallback.Export(ctx, msg)
}
o.log.Info("push outlet not delivered; getui fallback not integrated",
"hint", "wire the Getui SDK + GETUI_* credentials to enable the fallback tier")
return false, nil
}
// pushExportPayload is the JSON body POSTed to the self-hosted push service. It
// is deliberately small and stable: the service owns device targeting, the
// message carries only what is needed to render and de-duplicate it.
type pushExportPayload struct {
// Source identifies the producer so the service can route/filter.
Source string `json:"source"`
// Title is a short display title (the persona name).
Title string `json:"title"`
// Content is the proactive message body (already stripped of internal
// decision markers by buildProactiveMessage).
Content string `json:"content"`
// Platform is the outbound platform tag (cyrene-backthink or a concrete IM
// platform).
Platform string `json:"platform"`
// Timestamp is the message time in Unix milliseconds.
Timestamp int64 `json:"timestamp"`
}
// httpPushExporter posts the message to the self-hosted push service. A 2xx
// response means delivered; any other status or transport error is an error.
// The token travels only in the Authorization header and never reaches a log.
type httpPushExporter struct {
url string
token string
client *http.Client
}
// Export implements PushExporter over HTTP POST JSON.
func (e *httpPushExporter) Export(ctx context.Context, msg adapter.UnifiedMessage) (bool, error) {
body, err := json.Marshal(pushExportPayload{
Source: "cyrene/backthink",
Title: msg.Sender.DisplayName,
Content: msg.Content,
Platform: msg.Platform,
Timestamp: msg.Timestamp.UnixMilli(),
})
if err != nil {
return false, fmt.Errorf("push outlet: marshal payload: %w", err)
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, e.url, bytes.NewReader(body))
if err != nil {
return false, fmt.Errorf("push outlet: build request: %w", e.redact(err))
}
req.Header.Set("Content-Type", "application/json")
if e.token != "" {
req.Header.Set("Authorization", "Bearer "+e.token)
}
resp, err := e.client.Do(req)
if err != nil {
return false, fmt.Errorf("push outlet: post: %w", e.redact(err))
}
defer func() { _ = resp.Body.Close() }()
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxExportResponseBytes))
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return false, fmt.Errorf("push outlet: unexpected status %d", resp.StatusCode)
}
return true, nil
}
// redact removes the endpoint URL from a transport error so a secret embedded in
// the URL (for example a query token) never reaches a log line.
func (e *httpPushExporter) redact(err error) error {
if err == nil || e.url == "" {
return err
}
msg := strings.ReplaceAll(err.Error(), e.url, "[push-outlet-url]")
return fmt.Errorf("%s", msg)
}
@@ -0,0 +1,261 @@
package backthink
import (
"bytes"
"context"
"encoding/json"
"errors"
"log/slog"
"net/http"
"net/http/httptest"
"strings"
"sync"
"testing"
"time"
"git.yeij.top/AskaEth/Cyrene_v2/internal/channel/adapter"
)
// mockExporter records exported messages and can block or fail on demand so the
// pusher hook's non-blocking / failure-tolerant behaviour is testable.
type mockExporter struct {
mu sync.Mutex
msgs []adapter.UnifiedMessage
delivered bool
err error
started chan struct{}
startOnce sync.Once
release chan struct{}
}
func (m *mockExporter) Export(ctx context.Context, msg adapter.UnifiedMessage) (bool, error) {
m.startOnce.Do(func() {
if m.started != nil {
close(m.started)
}
})
if m.release != nil {
<-m.release
}
m.mu.Lock()
m.msgs = append(m.msgs, msg)
m.mu.Unlock()
return m.delivered, m.err
}
func (m *mockExporter) messages() []adapter.UnifiedMessage {
m.mu.Lock()
defer m.mu.Unlock()
return append([]adapter.UnifiedMessage(nil), m.msgs...)
}
// TestPushOutletHTTPPrimaryDelivers proves the self-hosted service is the
// primary tier: the payload is POSTed with the bearer token and a 2xx response
// is reported as delivered.
func TestPushOutletHTTPPrimaryDelivers(t *testing.T) {
t.Parallel()
type payload struct {
Source string `json:"source"`
Title string `json:"title"`
Content string `json:"content"`
Platform string `json:"platform"`
Timestamp int64 `json:"timestamp"`
}
var (
got payload
auth string
ct string
)
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
auth = r.Header.Get("Authorization")
ct = r.Header.Get("Content-Type")
if err := json.NewDecoder(r.Body).Decode(&got); err != nil {
t.Errorf("decode payload: %v", err)
}
w.WriteHeader(http.StatusNoContent)
}))
defer srv.Close()
exp := NewPushOutlet(PushOutletConfig{
Enabled: true,
URL: srv.URL,
Token: "s3cret-token",
Timeout: 2 * time.Second,
Log: discardLog(),
})
if exp == nil {
t.Fatal("NewPushOutlet returned nil for an enabled outlet")
}
delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{
Platform: "cyrene-backthink",
Content: "晚安,早点睡。",
Sender: adapter.Actor{DisplayName: "Cyrene"},
Timestamp: time.UnixMilli(1700000000000),
})
if err != nil || !delivered {
t.Fatalf("Export = (%v, %v), want (true, nil)", delivered, err)
}
if got.Source != "cyrene/backthink" || got.Title != "Cyrene" || got.Content != "晚安,早点睡。" || got.Platform != "cyrene-backthink" {
t.Fatalf("payload = %+v, want source/title/content/platform set", got)
}
if got.Timestamp != 1700000000000 {
t.Fatalf("timestamp = %d, want 1700000000000", got.Timestamp)
}
if auth != "Bearer s3cret-token" {
t.Fatalf("Authorization = %q, want the bearer token", auth)
}
if ct != "application/json" {
t.Fatalf("Content-Type = %q, want application/json", ct)
}
}
// TestPushOutletUnreachableLogsGetuiFallback asserts an unreachable primary is a
// logged miss (not an error), names the pending Getui fallback, and never logs
// the token.
func TestPushOutletUnreachableLogsGetuiFallback(t *testing.T) {
t.Parallel()
srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
url := srv.URL
srv.Close() // now unreachable
var buf bytes.Buffer
log := slog.New(slog.NewTextHandler(&buf, nil))
exp := NewPushOutlet(PushOutletConfig{Enabled: true, URL: url, Token: "s3cret-token", Timeout: 300 * time.Millisecond, Log: log})
delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{Content: "hi"})
if err != nil {
t.Fatalf("Export err = %v, want nil (logged miss)", err)
}
if delivered {
t.Fatal("Export delivered = true, want false for an unreachable primary")
}
if !strings.Contains(buf.String(), "getui") {
t.Fatalf("log = %q, want the pending Getui fallback note", buf.String())
}
if strings.Contains(buf.String(), "s3cret-token") {
t.Fatalf("log leaked the token: %q", buf.String())
}
}
// TestPushOutletHTTPErrorReportsMiss asserts a non-2xx primary response is a miss.
func TestPushOutletHTTPErrorReportsMiss(t *testing.T) {
t.Parallel()
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
http.Error(w, "nope", http.StatusInternalServerError)
}))
defer srv.Close()
exp := NewPushOutlet(PushOutletConfig{Enabled: true, URL: srv.URL, Timeout: 2 * time.Second, Log: discardLog()})
delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{Content: "hi"})
if err != nil {
t.Fatalf("Export err = %v, want nil (logged miss)", err)
}
if delivered {
t.Fatal("Export delivered = true, want false for a 500 response")
}
}
// TestNewPushOutletDisabledOrUnconfigured covers the two degraded shapes: the
// hook off (nil) and enabled without a primary URL (miss + Getui note).
func TestNewPushOutletDisabledOrUnconfigured(t *testing.T) {
t.Parallel()
if exp := NewPushOutlet(PushOutletConfig{Enabled: false, URL: "http://example.invalid"}); exp != nil {
t.Fatalf("NewPushOutlet disabled = %v, want nil", exp)
}
var buf bytes.Buffer
log := slog.New(slog.NewTextHandler(&buf, nil))
exp := NewPushOutlet(PushOutletConfig{Enabled: true, Log: log})
if exp == nil {
t.Fatal("NewPushOutlet enabled without a URL = nil, want a fallback-only outlet")
}
delivered, err := exp.Export(context.Background(), adapter.UnifiedMessage{Content: "hi"})
if err != nil || delivered {
t.Fatalf("Export = (%v, %v), want (false, nil)", delivered, err)
}
if !strings.Contains(buf.String(), "getui") {
t.Fatalf("log = %q, want the Getui fallback note", buf.String())
}
}
// TestPusherExportsProactiveToOutlet asserts the hook mirrors the delivered
// proactive message to the outlet after the IM delivery.
func TestPusherExportsProactiveToOutlet(t *testing.T) {
t.Parallel()
exp := &mockExporter{delivered: true}
im := &mockIMAdapter{}
p := newPusher(nil, im, &mockGate{allow: true}, discardLog()).withExporter(exp)
p.exportDone = make(chan struct{}, 1)
res := p.Push(context.Background(), PushRequest{Message: adapter.UnifiedMessage{Content: "在吗"}})
if !res.Pushed || res.Route != RouteIMBridge {
t.Fatalf("push = %+v, want pushed via IM bridge", res)
}
if im.count() != 1 {
t.Fatalf("im calls = %d, want 1", im.count())
}
select {
case <-p.exportDone:
case <-time.After(2 * time.Second):
t.Fatal("export hook did not run")
}
msgs := exp.messages()
if len(msgs) != 1 || msgs[0].Content != "在吗" {
t.Fatalf("exported = %+v, want the proactive content", msgs)
}
}
// TestPusherExportHookNonBlockingAndFailureTolerant asserts a hung/failing outlet
// never delays the push and never turns a delivered proactive message into a
// failure.
func TestPusherExportHookNonBlockingAndFailureTolerant(t *testing.T) {
t.Parallel()
started := make(chan struct{})
release := make(chan struct{})
exp := &mockExporter{delivered: false, err: errors.New("outlet down"), started: started, release: release}
im := &mockIMAdapter{}
p := newPusher(nil, im, &mockGate{allow: true}, discardLog()).withExporter(exp)
p.exportDone = make(chan struct{}, 1)
begin := time.Now()
res := p.Push(context.Background(), PushRequest{Message: adapter.UnifiedMessage{Content: "hi"}})
if elapsed := time.Since(begin); elapsed > 100*time.Millisecond {
t.Fatalf("Push blocked on the outlet for %v, want non-blocking", elapsed)
}
if !res.Pushed || res.Route != RouteIMBridge {
t.Fatalf("push = %+v, want pushed via IM bridge despite the outlet failure", res)
}
select {
case <-started:
case <-time.After(2 * time.Second):
t.Fatal("exporter was never invoked")
}
close(release)
select {
case <-p.exportDone:
case <-time.After(2 * time.Second):
t.Fatal("export hook did not finish")
}
}
// TestPusherRateLimitedPushIsNotExported asserts a rate-limited push never
// reaches the outlet: the hook mirrors real proactive sends only.
func TestPusherRateLimitedPushIsNotExported(t *testing.T) {
t.Parallel()
exp := &mockExporter{delivered: true}
p := newPusher(nil, &mockIMAdapter{}, &mockGate{allow: false}, discardLog()).withExporter(exp)
p.exportDone = make(chan struct{}, 1)
res := p.Push(context.Background(), PushRequest{Message: adapter.UnifiedMessage{Content: "hi"}})
if res.Route != RouteRateLimited {
t.Fatalf("route = %q, want rate_limited", res.Route)
}
select {
case <-p.exportDone:
t.Fatal("rate-limited push should not be exported")
case <-time.After(50 * time.Millisecond):
}
if len(exp.messages()) != 0 {
t.Fatalf("exported = %+v, want none", exp.messages())
}
}
+3 -3
View File
@@ -25,10 +25,10 @@ func (b *Backthink) SetIMSink(im IMAdapter) {
b.rebuildPusherLocked()
}
// rebuildPusherLocked replaces the pusher from the current sinks and gate. The
// caller must hold b.mu.
// rebuildPusherLocked replaces the pusher from the current sinks, gate and push
// outlet. The caller must hold b.mu.
func (b *Backthink) rebuildPusherLocked() {
b.pusher = newPusher(b.deps.Active, b.deps.IM, b.gate, b.log)
b.pusher = newPusher(b.deps.Active, b.deps.IM, b.gate, b.log).withExporter(b.deps.Exporter)
}
// currentPusher returns the active pusher under the lifecycle lock, so a sink