feat(automations): 自动化引擎（cron 调度 + 事件触发 + AI 管线动作 + 提醒调度，bus automation.result/reminder.trigger）

internal/services/automations/automations.go

@@ -0,0 +1,176 @@
+// Package automations implements the Cyrene v2 automation engine and reminder
+// scheduler (DevDocs/design/04-运行时.md §8.5). It is the "how she does things on
+// her own" layer: schedules and event rules fire a named action, the action runs
+// (either a plain function, a registered tool, or a prompt through the AI
+// loop/agent pipeline), and every outcome is published back to the bus so upper
+// layers can react or push notifications.
+//
+// The package is split into five files:
+//
+//   - automations.go — shared types: Config, Deps, the Pipeline abstraction, the
+//     published Result and the sentinel errors.
+//   - scheduler.go  — the cron-driven Scheduler (robfig/cron/v3).
+//   - rule.go       — the Rule model and the event-driven Engine.
+//   - action.go     — the Action interface plus func/tool/AI implementations.
+//   - reminder.go   — the time-based ReminderStore.
+//   - service.go    — the Service that composes the three for lifecycle control.
+//
+// Execution model: every trigger (cron fire, event match, reminder due) resolves
+// to the same runAction, which executes the Action under an optional deadline and
+// publishes a Result to the "automation.result" subject. This keeps reporting and
+// logging consistent across all trigger kinds (DevDocs/design/04-运行时.md §8.5:
+// task output returns to the message queue/agent).
+//
+// Identity and capability boundaries (Devedocs global red lines): automation
+// never decides who is allowed to do anything. It only fires named actions;
+// authorization stays in the channel/policy layer.
+package automations
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"time"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/bus"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/agent"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/loop"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+)
+
+// Bus subjects published by the automations engine. Upper layers subscribe to
+// these to observe outcomes or push notifications.
+const (
+	// SubjectResult is the subject every executed automation publishes its
+	// Result to.
+	SubjectResult = "automation.result"
+	// SubjectTrigger is the subject a due Reminder is published to. Upper layers
+	// subscribe to it to surface the reminder to the user.
+	SubjectTrigger = "reminder.trigger"
+)
+
+// Sentinel errors returned by this package. Use errors.Is to test for them.
+var (
+	// ErrNilBus is returned when a constructor receives a nil bus.
+	ErrNilBus = errors.New("automations: nil bus")
+	// ErrNilAction is returned when an action is nil or unnamed.
+	ErrNilAction = errors.New("automations: nil action")
+	// ErrInvalidRule is returned when a rule is malformed.
+	ErrInvalidRule = errors.New("automations: invalid rule")
+	// ErrInvalidCron is returned when a cron expression fails to parse.
+	ErrInvalidCron = errors.New("automations: invalid cron expression")
+	// ErrNotFound is returned when a rule or reminder is missing.
+	ErrNotFound = errors.New("automations: not found")
+	// ErrDuplicate is returned when a rule or reminder id is already registered.
+	ErrDuplicate = errors.New("automations: already exists")
+	// ErrNoPipeline is returned when an AI action is built without a pipeline.
+	ErrNoPipeline = errors.New("automations: no AI pipeline configured")
+)
+
+// Config configures the automations engine.
+type Config struct {
+	// Location is the timezone used for cron schedules and reminder firing. Nil
+	// uses time.Local.
+	Location *time.Location
+	// WithSeconds enables 6-field cron specs (with a leading seconds field) in
+	// addition to the standard 5-field format.
+	WithSeconds bool
+	// ActionTimeout bounds a single action execution. Non-positive disables the
+	// deadline.
+	ActionTimeout time.Duration
+	// ReminderInterval is how often the reminder loop polls for due reminders.
+	// Non-positive selects defaultReminderInterval.
+	ReminderInterval time.Duration
+}
+
+// Deps is the injected dependency set for the automations engine.
+type Deps struct {
+	// Bus is the in-process event bus. Required.
+	Bus bus.Bus
+	// Loop is the AI pipeline (the agent loop). When set, an AI action runs
+	// through it. Agent is used only when Loop is nil.
+	Loop *loop.Loop
+	// Agent is the single-step agent, used as the AI pipeline when Loop is nil.
+	Agent *agent.Agent
+	// Log is the base logger. A nil logger is replaced with a discard logger
+	// tagged with source "services/automations".
+	Log *slog.Logger
+	// Now supplies the current time for reminders. Nil uses time.Now.
+	Now func() time.Time
+}
+
+// Pipeline is the AI-execution surface an automation action runs through. It is
+// satisfied by *loop.Loop directly, so a real pipeline can be injected without
+// an adapter. Tests inject a fake to observe the prompt and return canned text.
+type Pipeline interface {
+	Run(ctx context.Context, sessionID string, messages []model.Message) (*loop.Result, error)
+}
+
+// AgentPipeline adapts an *agent.Agent to Pipeline by running a single step and
+// returning its text as the result. It is used when only an agent (not a full
+// loop) is injected.
+type AgentPipeline struct {
+	Agent *agent.Agent
+}
+
+// Run runs one agent step and returns its text as the loop-style Result.
+func (a *AgentPipeline) Run(ctx context.Context, sessionID string, messages []model.Message) (*loop.Result, error) {
+	if a.Agent == nil {
+		return nil, fmt.Errorf("automations: agent pipeline: %w", ErrNoPipeline)
+	}
+	sr, err := a.Agent.RunStep(ctx, sessionID, messages)
+	if err != nil {
+		return nil, fmt.Errorf("automations: agent pipeline run: %w", err)
+	}
+	return &loop.Result{Text: sr.Text, StopReason: sr.StopReason, Steps: 1}, nil
+}
+
+// pipeline returns the resolved AI pipeline from deps, or nil when neither a
+// loop nor an agent is configured.
+func (d Deps) pipeline() Pipeline {
+	if d.Loop != nil {
+		return d.Loop
+	}
+	if d.Agent != nil {
+		return &AgentPipeline{Agent: d.Agent}
+	}
+	return nil
+}
+
+// Result is the structured outcome of an executed automation, published to
+// SubjectResult. Upper layers subscribe to it to react or push notifications.
+type Result struct {
+	// Kind classifies the trigger: "schedule", "event" or "reminder".
+	Kind string `json:"kind"`
+	// RuleID identifies the schedule/rule/reminder that fired.
+	RuleID string `json:"rule_id"`
+	// Action is the action name that ran.
+	Action string `json:"action"`
+	// Payload is the trigger payload (nil for a cron fire).
+	Payload any `json:"payload"`
+	// Output is the action's returned value, or nil on error.
+	Output any `json:"output"`
+	// Error carries the action's error message when the run failed.
+	Error string `json:"error,omitempty"`
+}
+
+// sourcedLog returns a base logger tagged with the module source
+// "services/automations", replacing a nil logger with a discard one so callers
+// can always log safely.
+func sourcedLog(l *slog.Logger) *slog.Logger {
+	if l == nil {
+		l = slog.New(slog.NewTextHandler(io.Discard, nil))
+	}
+	return logger.WithSource(l, "services/automations")
+}
+
+// resolveNow returns f when non-nil, otherwise time.Now.
+func resolveNow(f func() time.Time) func() time.Time {
+	if f == nil {
+		return time.Now
+	}
+	return f
+}