Merge pull request #673 from pionxe/main

feat(tui-v2): launch TUI v2 framework and agent behavior stream with smart scroll engine (Phases 0-8)

Author: phantom5099

AGENTS.md

@@ -39,6 +39,14 @@
 
 如需了解当前各模块的具体实现细节（如 budget 闭环、事件协议、compact 策略），参考 `docs/` 目录下对应文档，而非本文件。
 
+### TUI v2 Phase 0 开发边界
+- TUI v1 (`internal/tui/`) 冻结不改；TUI v2 的新实现统一放在 `internal/tuiv2/`。
+- TUI v2 使用独立二进制入口 `cmd/neocode-tuiv2/main.go`，不复用或改写 TUI v1 入口。
+- TUI v2 禁止 import `internal/runtime`、`internal/session`、`internal/repository` 或任何 SQLite 相关包。
+- TUI v2 不直接使用真实 Gateway 内部 server；真实通信能力必须通过客户端适配器收敛。
+- Fake 实现模拟的是 Gateway 客户端接口，不是 `FakeRuntime`。
+- UI 组件不直接写死假数据，所有数据流必须从 Gateway 客户端接口进入。
+
 ## 5. AI 修改代码时的执行流程
 - 先定位改动所属模块，再检查是否会破坏职责边界。
 - 优先做最小闭环改动，避免无关重构。

cmd/neocode-tuiv2/main.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	tea "github.com/charmbracelet/bubbletea"
+
+	"neo-code/internal/tuiv2"
+	"neo-code/internal/tuiv2/fakegateway"
+	"neo-code/internal/tuiv2/gateway"
+)
+
+const (
+	backendFake    = "fake"
+	backendGateway = "gateway"
+)
+
+// main 是 TUI v2 独立二进制入口，只负责参数解析、客户端选择和启动 Bubble Tea 程序。
+func main() {
+	cfg, err := parseStartupConfig(os.Args[1:], os.Stderr)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+
+	client, err := newGatewayClient(cfg)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(2)
+	}
+	cfg.Client = client
+
+	if _, err := tea.NewProgram(
+		tuiv2.NewApp(cfg),
+		tea.WithInput(os.Stdin),
+		tea.WithOutput(os.Stdout),
+		tea.WithAltScreen(),
+	).Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "start TUI v2: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+// parseStartupConfig 解析 TUI v2 独立入口参数，保持与 v1 cobra 命令树完全隔离。
+func parseStartupConfig(args []string, stderr io.Writer) (tuiv2.StartupConfig, error) {
+	cfg := tuiv2.StartupConfig{
+		Backend:  backendFake,
+		Scenario: fakegateway.ScenarioDefault,
+	}
+
+	flags := flag.NewFlagSet("neocode-tuiv2", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	flags.StringVar(&cfg.Backend, "backend", cfg.Backend, "gateway backend: fake or gateway")
+	flags.StringVar(&cfg.Scenario, "scenario", cfg.Scenario, "fake gateway scenario")
+	flags.BoolVar(&cfg.Debug, "debug", false, "show TUI v2 debug information")
+
+	if err := flags.Parse(args); err != nil {
+		return tuiv2.StartupConfig{}, err
+	}
+	if flags.NArg() > 0 {
+		return tuiv2.StartupConfig{}, fmt.Errorf("unexpected positional arguments: %v", flags.Args())
+	}
+	if cfg.Backend == "" {
+		return tuiv2.StartupConfig{}, fmt.Errorf("--backend must not be empty")
+	}
+	if cfg.Scenario == "" {
+		return tuiv2.StartupConfig{}, fmt.Errorf("--scenario must not be empty")
+	}
+	return cfg, nil
+}
+
+// newGatewayClient 根据启动参数创建 Gateway 客户端，真实 Gateway 后端保留到后续阶段接入。
+func newGatewayClient(cfg tuiv2.StartupConfig) (gateway.Client, error) {
+	switch cfg.Backend {
+	case backendFake:
+		return fakegateway.New(fakegateway.Config{Scenario: cfg.Scenario})
+	case backendGateway:
+		return nil, fmt.Errorf("--backend=gateway is reserved for Phase 20")
+	default:
+		return nil, fmt.Errorf("unsupported --backend=%q", cfg.Backend)
+	}
+}

cmd/neocode-tuiv2/main_test.go

@@ -0,0 +1,102 @@
+package main
+
+import (
+	"io"
+	"testing"
+
+	"neo-code/internal/tuiv2"
+	"neo-code/internal/tuiv2/fakegateway"
+)
+
+func TestParseStartupConfigDefaults(t *testing.T) {
+	cfg, err := parseStartupConfig(nil, io.Discard)
+	if err != nil {
+		t.Fatalf("parseStartupConfig() error = %v", err)
+	}
+
+	if cfg.Backend != backendFake {
+		t.Fatalf("Backend = %q, want %q", cfg.Backend, backendFake)
+	}
+	if cfg.Scenario != fakegateway.ScenarioDefault {
+		t.Fatalf("Scenario = %q, want %q", cfg.Scenario, fakegateway.ScenarioDefault)
+	}
+	if cfg.Debug {
+		t.Fatal("Debug = true, want false")
+	}
+}
+
+func TestParseStartupConfigExplicitValues(t *testing.T) {
+	cfg, err := parseStartupConfig([]string{
+		"--backend=fake",
+		"--scenario=tool_approval",
+		"--debug",
+	}, io.Discard)
+	if err != nil {
+		t.Fatalf("parseStartupConfig() error = %v", err)
+	}
+
+	if cfg.Backend != backendFake {
+		t.Fatalf("Backend = %q, want %q", cfg.Backend, backendFake)
+	}
+	if cfg.Scenario != fakegateway.ScenarioToolApproval {
+		t.Fatalf("Scenario = %q, want %q", cfg.Scenario, fakegateway.ScenarioToolApproval)
+	}
+	if !cfg.Debug {
+		t.Fatal("Debug = false, want true")
+	}
+}
+
+func TestParseStartupConfigRejectsInvalidShape(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{name: "positional", args: []string{"extra"}},
+		{name: "empty backend", args: []string{"--backend="}},
+		{name: "empty scenario", args: []string{"--scenario="}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if _, err := parseStartupConfig(tt.args, io.Discard); err == nil {
+				t.Fatal("parseStartupConfig() error = nil, want error")
+			}
+		})
+	}
+}
+
+func TestNewGatewayClient(t *testing.T) {
+	cfg, err := parseStartupConfig([]string{"--scenario=gateway_offline"}, io.Discard)
+	if err != nil {
+		t.Fatalf("parseStartupConfig() error = %v", err)
+	}
+
+	client, err := newGatewayClient(cfg)
+	if err != nil {
+		t.Fatalf("newGatewayClient() error = %v", err)
+	}
+	if client == nil {
+		t.Fatal("newGatewayClient() client = nil")
+	}
+}
+
+func TestNewGatewayClientRejectsReservedAndUnknownBackends(t *testing.T) {
+	tests := []string{backendGateway, "other"}
+	for _, backend := range tests {
+		t.Run(backend, func(t *testing.T) {
+			_, err := newGatewayClient(mustConfig(t, []string{"--backend=" + backend}))
+			if err == nil {
+				t.Fatal("newGatewayClient() error = nil, want error")
+			}
+		})
+	}
+}
+
+func mustConfig(t *testing.T, args []string) tuiv2.StartupConfig {
+	t.Helper()
+	cfg, err := parseStartupConfig(args, io.Discard)
+	if err != nil {
+		t.Fatalf("parseStartupConfig() error = %v", err)
+	}
+	return cfg
+}