Merge pull request #48 from BetaGoRobot/feature-agentic

commit agentic result

Author: kevinmatthe

.gitignore

@@ -9,4 +9,5 @@ __debug_bin*
 .cache
 .env
 *.test
-script/neteaseapi/api_repo/*
+script/neteaseapi/api_repo/*
+**__pycache__**

Agents.md

@@ -203,6 +203,17 @@ BetaGo-Redefine/
 | dynamic_configs | 动态配置 |
 | cron_cmd_tasks | 定时任务 |
 
+## Agent 数据库变更约束
+
+凡是涉及新建表、改表、索引或约束变更，先遵循 `script/AGENT_DB_CHANGE_SOP.md`。
+
+硬约束：
+
+- 先生成 SQL，并保存到 `script/sql/`
+- 先等待用户执行 SQL
+- 再等待用户执行 `go run ./cmd/generate`
+- 用户确认前，不继续写依赖新 schema 的业务代码
+
 ## 本地开发
 
 ### 前置要求

cmd/larkrobot/bootstrap.go

@@ -6,6 +6,9 @@ import (
 	"fmt"
 
 	appconfig "github.com/BetaGoRobot/BetaGo-Redefine/internal/application/config"
+	"github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/agentruntime"
+	"github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/agentruntime/runtimecutover"
+	"github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/agentruntime/runtimewire"
 	appcardaction "github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/cardaction"
 	larkchunking "github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/chunking"
 	"github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/handlers"
@@ -14,7 +17,7 @@ import (
 	"github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/reaction"
 	scheduleapp "github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/schedule"
 	todoapp "github.com/BetaGoRobot/BetaGo-Redefine/internal/application/lark/todo"
-	"github.com/BetaGoRobot/BetaGo-Redefine/internal/infrastructure/aktool"
+	"github.com/BetaGoRobot/BetaGo-Redefine/internal/infrastructure/akshareapi"
 	"github.com/BetaGoRobot/BetaGo-Redefine/internal/infrastructure/ark_dal"
 	infraConfig "github.com/BetaGoRobot/BetaGo-Redefine/internal/infrastructure/config"
 	"github.com/BetaGoRobot/BetaGo-Redefine/internal/infrastructure/db"
@@ -31,6 +34,7 @@ import (
 	"github.com/BetaGoRobot/BetaGo-Redefine/pkg/logs"
 	"github.com/BetaGoRobot/BetaGo-Redefine/pkg/xhttp"
 	"github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
 )
 
 type appComponents struct {
@@ -45,7 +49,23 @@ type appComponents struct {
 
 // scheduler 仍保留为包级句柄，是因为当前调度器本身还没有实现
 // runtime.Module。真正的生命周期仍由装配阶段注册的模块接管。
-var scheduler *scheduleapp.Scheduler
+var (
+	scheduler                     *scheduleapp.Scheduler
+	resumeWorker                  workerHandle
+	buildAgentRuntimeResumeWorker = func(ctx context.Context) workerHandle {
+		return runtimewire.BuildResumeWorker(ctx)
+	}
+)
+
+func startAgentRuntimeResumeWorker(ctx context.Context) error {
+	worker := buildAgentRuntimeResumeWorker(ctx)
+	if worker == nil || !worker.Available() {
+		return fmt.Errorf("%w: agent runtime resume worker unavailable", appruntime.ErrDisabled)
+	}
+	resumeWorker = worker
+	resumeWorker.Start()
+	return nil
+}
 
 // buildApp 是当前单体进程的装配根。这里集中完成：
 // 1. 构造受控执行器和 handler 入口；
@@ -79,6 +99,13 @@ func newAppComponents(cfg *infraConfig.BaseConfig) *appComponents {
 	chunkExecutor := appruntime.NewExecutor(executorConfigs["chunk"])
 	scheduleExecutor := appruntime.NewExecutor(executorConfigs["schedule"])
 
+	agentruntime.SetRuntimeAgenticCutoverBuilder(runtimecutover.BuildDefaultHandler)
+	// agentruntime.SetRuntimeStandardCutoverBuilder(runtimecutover.BuildDefaultStandardHandler)
+	agentruntime.SetDefaultChatToolProvider(handlers.BuildLarkTools)
+	agentruntime.SetChatGenerationPlanExecutor(agentruntime.NewDefaultChatGenerationPlanExecutor())
+	runtimewire.SetDefaultCapabilityProvider(func() []agentruntime.Capability {
+		return agentruntime.BuildToolCapabilities(handlers.BuildLarkTools(), nil, (*larkim.P2MessageReceiveV1)(nil))
+	})
 	messageProcessor := messages.NewMessageProcessor(appconfig.GetManager())
 	reactionProcessor := reaction.NewReactionProcessor()
 	handlerSet := larkiface.NewHandlerSet(larkiface.HandlerSetOptions{
@@ -173,10 +200,10 @@ func addInfrastructureModules(app *appruntime.App, cfg *infraConfig.BaseConfig)
 	}, func(context.Context) error {
 		return gotify.ErrUnavailable()
 	}))
-	app.AddModule(newOptionalModule("aktool", func() {
-		aktool.Init()
+	app.AddModule(newOptionalModule("akshareapi", func() {
+		akshareapi.Init()
 	}, func(context.Context) error {
-		if ok, reason := aktool.Status(); !ok {
+		if ok, reason := akshareapi.Status(); !ok {
 			return errors.New(reason)
 		}
 		return nil
@@ -276,13 +303,39 @@ func addApplicationModules(app *appruntime.App, cfg *infraConfig.BaseConfig, com
 		},
 		Stats: components.scheduleExecutor.Stats,
 	}))
+	app.AddModule(appruntime.NewFuncModule(appruntime.FuncModuleOptions{
+		Name:     "agent_runtime_resume_worker",
+		Critical: false,
+		Start: func(ctx context.Context) error {
+			return startAgentRuntimeResumeWorker(ctx)
+		},
+		Stop: func(context.Context) error {
+			if resumeWorker != nil {
+				resumeWorker.Stop()
+			}
+			return nil
+		},
+		Stats: func() map[string]any {
+			if resumeWorker == nil {
+				return nil
+			}
+			return resumeWorker.Stats()
+		},
+	}))
 	app.AddModule(appruntime.NewLarkWSModule(
 		cfg.LarkConfig.AppID,
 		cfg.LarkConfig.AppSecret,
 		components.eventDispatcher,
 	))
 }
 
+type workerHandle interface {
+	Start()
+	Stop()
+	Stats() map[string]any
+	Available() bool
+}
+
 // newEventDispatcher 负责把运行时管理的 HandlerSet 绑定到当前订阅的
 // Lark 事件类型上。
 func newEventDispatcher(handlerSet *larkiface.HandlerSet) *dispatcher.EventDispatcher {

cmd/larkrobot/bootstrap_test.go

@@ -0,0 +1,99 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	infraConfig "github.com/BetaGoRobot/BetaGo-Redefine/internal/infrastructure/config"
+	appruntime "github.com/BetaGoRobot/BetaGo-Redefine/internal/runtime"
+)
+
+type fakeWorkerHandle struct {
+	available bool
+	started   bool
+	stopped   bool
+}
+
+func (f *fakeWorkerHandle) Start() {
+	f.started = true
+}
+
+func (f *fakeWorkerHandle) Stop() {
+	f.stopped = true
+}
+
+func (f *fakeWorkerHandle) Stats() map[string]any {
+	return nil
+}
+
+func (f *fakeWorkerHandle) Available() bool {
+	return f != nil && f.available
+}
+
+func TestStartAgentRuntimeResumeWorkerStartsAvailableWorkerWithoutGlobalConfigGate(t *testing.T) {
+	originalBuilder := buildAgentRuntimeResumeWorker
+	originalResumeWorker := resumeWorker
+	defer func() {
+		buildAgentRuntimeResumeWorker = originalBuilder
+		resumeWorker = originalResumeWorker
+	}()
+
+	fake := &fakeWorkerHandle{available: true}
+	buildAgentRuntimeResumeWorker = func(context.Context) workerHandle {
+		return fake
+	}
+	resumeWorker = nil
+
+	if err := startAgentRuntimeResumeWorker(context.Background()); err != nil {
+		t.Fatalf("startAgentRuntimeResumeWorker() error = %v", err)
+	}
+	if !fake.started {
+		t.Fatal("expected resume worker to be started")
+	}
+	if resumeWorker != fake {
+		t.Fatal("expected started worker to be stored globally")
+	}
+}
+
+func TestStartAgentRuntimeResumeWorkerReturnsDisabledWhenUnavailable(t *testing.T) {
+	originalBuilder := buildAgentRuntimeResumeWorker
+	originalResumeWorker := resumeWorker
+	defer func() {
+		buildAgentRuntimeResumeWorker = originalBuilder
+		resumeWorker = originalResumeWorker
+	}()
+
+	buildAgentRuntimeResumeWorker = func(context.Context) workerHandle {
+		return &fakeWorkerHandle{available: false}
+	}
+	resumeWorker = nil
+
+	err := startAgentRuntimeResumeWorker(context.Background())
+	if !errors.Is(err, appruntime.ErrDisabled) {
+		t.Fatalf("startAgentRuntimeResumeWorker() error = %v, want %v", err, appruntime.ErrDisabled)
+	}
+}
+
+func TestAddInfrastructureModulesRegistersAKShareAPIModule(t *testing.T) {
+	app := appruntime.NewApp()
+
+	addInfrastructureModules(app, &infraConfig.BaseConfig{})
+
+	snapshot := app.Registry().Snapshot()
+	if hasComponent(snapshot.Components, "aktool") {
+		t.Fatalf("unexpected aktool module in registry: %+v", snapshot.Components)
+	}
+	if !hasComponent(snapshot.Components, "akshareapi") {
+		t.Fatalf("expected akshareapi module in registry: %+v", snapshot.Components)
+	}
+}
+
+func hasComponent(items []appruntime.ComponentStatus, name string) bool {
+	for _, item := range items {
+		if item.Name == name {
+			return true
+		}
+	}
+	return false
+}

docs/akshare/README.md

@@ -0,0 +1,15 @@
+# AkShare Generated Docs
+
+- `generated/akshare_api_catalog.md`: human-readable Markdown catalog.
+- `generated/akshare_api_catalog.json`: structured extraction of the official docs.
+- `generated/akshare_openapi.json`: OpenAPI 3.1 skeleton using AKTools' `/api/public/{接口名}` convention.
+
+## Notes
+
+- Sources: `https://akshare.akfamily.xyz/` and `https://aktools.akfamily.xyz/aktools/`.
+- Live server: `http://192.168.31.74:1828`.
+- Live service reachable: `True`; Swagger docs reachable: `True`; OpenAPI reachable: `True`.
+- Live validation for uncertain endpoints: attempted `0`, succeeded `0`, failed `0`.
+- The live service currently reports AKShare 1.18.27 while the official docs expose AKShare 1.18.40 content, so newer interfaces may be documentation-only until the service catches up.
+- Re-run with `python3 script/akshare_docgen.py` to refresh the source catalog and OpenAPI skeleton.
+- Re-run with `python3 script/akshare_focus_codegen.py` to refresh the SDK/focus catalogs and Go client catalog.