Merge pull request #391 from pionxe/main

feat(architecture): [EPIC-INT-01C] 斩断直连实现纯净架构，引入网关无感自动拉起与高可用加固

Author: phantom5099

AGENTS.md

@@ -3,16 +3,17 @@
 本文件是本仓库的 AI 协作规则。任何 AI 在本项目中进行改写、续写、重构、修复、补测试或补文档时，都应优先遵守本文件。
 
 ## 1. 任务目标
-- 本仓库的目标是实现 `NeoCode Coding Agent MVP`。
-- 当前主链路必须始终围绕以下闭环保持可用：
-  `用户输入 -> Agent 推理 -> 调用工具 -> 获取结果 -> 继续推理 -> UI 展示`
+- 本仓库的目标是实现 `NeoCode Coding Agent`。
+- 系统已完成控制面与数据面解耦，当前主链路必须始终围绕以下闭环保持可用：
+  `用户输入(TUI) -> 网关中继(Gateway) -> Agent推理(Runtime) -> 调用工具(Tools) -> 结果回传 -> UI展示`
 - 做改动时，优先保证主链路可运行、模块边界清晰、实现可验证。
 
 ## 2. 最高优先级规则
 - 不要为了“可能兼容旧版本”破坏当前架构；若新设计已确定，优先直接切换到新实现。
 - 不允许过度设计、过度包装
 - 项目中可能存在语义不清的地方，必须要谨慎分析
-- 不要跨层直连；新功能默认沿 `TUI -> Runtime -> Provider / Tool Manager` 主链路设计。
+- **强制编码准则 (防乱码)**：所有文件的读取、修改、重写操作必须强制使用标准 **UTF-8 (无 BOM)** 编码。严禁使用破坏多字节字符的正则替换；严禁在输出中文注释时出现截断或混入 GBK 等其他编码。发现乱码先修编码再修逻辑。
+- 不要跨层直连；新功能默认沿 `TUI -> Gateway -> Runtime -> Provider / Tool Manager` 主链路设计。
 - 不要把模型厂商差异泄漏到 `runtime`、`tui` 或上层调用方。
 - 不要在 `runtime` 或 `tui` 里直接写工具执行逻辑；所有可被模型调用的能力必须进入 `internal/tools`。
 - 不要把会话状态、消息历史、工具调用记录散落到 UI；这些状态优先由 `runtime` 管理。
@@ -23,13 +24,14 @@
 
 ### 3.1 关键目录
 - `cmd/neocode`：CLI 入口。
-- `internal/app`：应用装配与 bootstrap，负责连接 config、provider、tools、runtime、tui。
-- `internal/config`：配置模型、YAML 加载、环境变量管理、配置校验和并发安全访问。
-- `internal/provider`：provider 抽象、领域模型和各厂商适配器。
-- `internal/runtime`：ReAct 主循环、事件流、Prompt 编排、token 累积与自动压缩触发。
-- `internal/session`：会话领域模型、存储抽象与 JSON 持久化实现。
+- `internal/app`：应用装配与 bootstrap，负责组装 Gateway、Runtime、TUI 等组件。
+- `internal/config`：配置模型、YAML 加载、环境变量管理及校验。
+- `internal/tui`：纯 UI 渲染层、Bubble Tea 状态机。仅负责消费事件并展示，不存业务状态。
+- `internal/gateway`：协议路由中枢。负责 IPC/网络监听、JSON-RPC 归一化、ACL 鉴权和流式事件中继。
+- `internal/runtime`：业务大脑。负责 ReAct 循环、事件流、Prompt 编排、Token 累积与压缩触发。不接触 UI。
+- `internal/provider`：各厂商模型适配器、请求组装与流式响应解析。
+- `internal/session`：会话领域模型、存储抽象与 JSON/SQLite 持久化。
 - `internal/tools`：工具契约、注册表、参数校验和具体工具实现。
-- `internal/tui`：Bubble Tea 状态机、渲染层、Slash Command 和事件桥接。
 - `docs`：架构、配置、事件流、会话持久化等说明文档。
 
 ### 3.2 模块职责

README.md

@@ -100,18 +100,11 @@ $env:QINIU_API_KEY = "your_key_here"
 go run ./cmd/neocode --workdir /path/to/workspace
 ```
 
-运行模式切换（默认 `local`）：
+Gateway 转发与自动拉起说明：
 
-```bash
-go run ./cmd/neocode --runtime-mode local
-go run ./cmd/neocode --runtime-mode gateway
-```
-
-说明：
-
-- `--runtime-mode` 仅影响当前进程，不会回写 `config.yaml`
-- `gateway` 模式会通过本地 Gateway（优先 IPC）转发 runtime 请求与事件流
-- 若 Gateway 不可达或握手失败会直接报错退出（Fail Fast），不会自动回退到 `local`
+- `neocode` 默认通过本地 Gateway（优先 IPC）转发 runtime 请求与事件流
+- 启动时会先探测本地网关；若未运行会自动后台拉起并等待就绪（无感）
+- 若自动拉起后仍不可达或握手失败，会直接报错退出（Fail Fast）
 
 ### 4) 首次使用与常用命令
 - `/help`：查看命令帮助
@@ -144,7 +137,7 @@ go run ./cmd/neocode --runtime-mode gateway
 
 - API Key 通过环境变量注入，不写入 `config.yaml`
 - `--workdir` 只影响当前运行，不会回写到配置文件
-- `--runtime-mode` 默认 `local`，用于灰度切换到 `gateway` 模式
+- TUI 默认通过 Gateway 连接 runtime，启动时会自动探测并在必要时后台拉起网关
 
 详细配置请参考：[docs/guides/configuration.md](docs/guides/configuration.md)
 

docs/guides/configuration.md

@@ -246,22 +246,20 @@ $env:GEMINI_API_KEY = "AI..."
 
 ## CLI 运行参数覆盖
 
-工作目录与运行模式都不写入 `config.yaml`，只通过启动参数覆盖：
+工作目录不写入 `config.yaml`，只通过启动参数覆盖：
 
 ```bash
 go run ./cmd/neocode --workdir /path/to/workspace
-go run ./cmd/neocode --runtime-mode local
-go run ./cmd/neocode --runtime-mode gateway
 ```
 
 说明：
 
 - `--workdir` 只影响本次进程
 - 不会回写到 `config.yaml`
 - 工具根目录与 session 隔离都会使用该工作区
-- `--runtime-mode` 默认为 `local`，可切换为 `gateway`
-- `gateway` 模式会通过本地 Gateway（优先 IPC）转发 runtime 请求
-- 连接或握手失败会直接退出（Fail Fast），不会自动回退到 `local`
+- TUI 默认通过本地 Gateway（优先 IPC）转发 runtime 请求
+- 启动时会先探测本地网关；若未运行会自动后台拉起并等待就绪
+- 若自动拉起后仍连接或握手失败会直接退出（Fail Fast）
 
 ## 常见错误
 

internal/app/bootstrap.go

@@ -2,7 +2,6 @@ package app
 
 import (
 	"context"
-	"errors"
 	"log"
 	"path/filepath"
 	"strings"
@@ -36,13 +35,6 @@ import (
 
 const utf8CodePage = 65001
 
-const (
-	// RuntimeModeLocal 表示继续使用进程内 runtime 直连模式。
-	RuntimeModeLocal = "local"
-	// RuntimeModeGateway 表示通过 Gateway JSON-RPC 转发 runtime 调用。
-	RuntimeModeGateway = "gateway"
-)
-
 var (
 	setConsoleOutputCodePage = platformSetConsoleOutputCodePage
 	setConsoleInputCodePage  = platformSetConsoleInputCodePage
@@ -60,19 +52,24 @@ var (
 
 // BootstrapOptions 描述应用启动时可注入的运行时选项。
 type BootstrapOptions struct {
-	Workdir     string
-	RuntimeMode string
+	Workdir string
 }
 
 type memoExtractorScheduler interface {
 	ScheduleWithExtractor(sessionID string, messages []providertypes.Message, extractor memo.Extractor)
 }
 
 type runtimeWithClose interface {
-	agentruntime.Runtime
+	services.Runtime
 	Close() error
 }
 
+type bootstrapSharedBundle struct {
+	Config            config.Config
+	ConfigManager     *config.Manager
+	ProviderSelection *configstate.Service
+}
+
 func newMemoExtractorAdapter(
 	factory agentruntime.ProviderFactory,
 	cm *config.Manager,
@@ -129,35 +126,13 @@ func EnsureConsoleUTF8() {
 	_ = setConsoleInputCodePage(utf8CodePage)
 }
 
-// BuildRuntime 构建 CLI 与 TUI 共用的运行时依赖。
-func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, error) {
-	runtimeMode, err := resolveBootstrapRuntimeMode(opts.RuntimeMode)
+// BuildGatewayServerDeps 构建 Gateway 服务端运行时依赖，包含 runtime/tool/session 全栈能力。
+func BuildGatewayServerDeps(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, error) {
+	sharedDeps, providerRegistry, modelCatalogs, err := BuildSharedConfigDeps(ctx, opts)
 	if err != nil {
 		return RuntimeBundle{}, err
 	}
-
-	defaultCfg, err := bootstrapDefaultConfig(opts)
-	if err != nil {
-		return RuntimeBundle{}, err
-	}
-
-	loader := config.NewLoader("", defaultCfg)
-	manager := config.NewManager(loader)
-	if _, err := manager.Load(ctx); err != nil {
-		return RuntimeBundle{}, err
-	}
-
-	providerRegistry, err := builtin.NewRegistry()
-	if err != nil {
-		return RuntimeBundle{}, err
-	}
-	modelCatalogs := providercatalog.NewService(manager.BaseDir(), providerRegistry, nil)
-	providerSelection := configstate.NewService(manager, providerRegistry, modelCatalogs)
-	if _, err := providerSelection.EnsureSelection(ctx); err != nil {
-		return RuntimeBundle{}, err
-	}
-
-	cfg := manager.Get()
+	cfg := sharedDeps.Config
 
 	toolRegistry, toolsCleanup, err := buildToolRegistry(cfg)
 	if err != nil {
@@ -184,7 +159,7 @@ func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, er
 
 	// Session Store 绑定到启动时的 workdir 哈希分桶，整个应用生命周期内不可变。
 	// 这意味着所有会话都归属到启动时指定的项目目录下，运行时不会因配置变更而迁移存储位置。
-	sessionStore = agentsession.NewStore(loader.BaseDir(), cfg.Workdir)
+	sessionStore = agentsession.NewStore(sharedDeps.ConfigManager.BaseDir(), cfg.Workdir)
 
 	// 启动时自动清理过期会话，避免数据库无限膨胀。
 	if _, err := cleanupExpiredSessions(ctx, sessionStore, agentsession.DefaultSessionMaxAge); err != nil {
@@ -197,7 +172,7 @@ func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, er
 	var contextBuilder agentcontext.Builder = agentcontext.NewBuilderWithToolPoliciesAndSummarizers(toolRegistry, toolRegistry)
 	var memoSvc *memo.Service
 	if cfg.Memo.Enabled {
-		memoStore := memo.NewFileStore(loader.BaseDir(), cfg.Workdir)
+		memoStore := memo.NewFileStore(sharedDeps.ConfigManager.BaseDir(), cfg.Workdir)
 		memoSource := memo.NewContextSource(memoStore)
 		var sourceInvl func()
 		if invalidator, ok := memoSource.(interface{ InvalidateCache() }); ok {
@@ -212,15 +187,15 @@ func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, er
 	}
 
 	runtimeSvc := agentruntime.NewWithFactory(
-		manager,
+		sharedDeps.ConfigManager,
 		toolManager,
 		sessionStore,
 		providerRegistry,
 		contextBuilder,
 	)
 	runtimeSvc.SetSessionAssetStore(sessionStore)
 	runtimeSvc.SetUserInputPreparer(agentruntime.NewSessionInputPreparer(sessionStore, sessionStore))
-	runtimeSvc.SetSkillsRegistry(buildSkillsRegistry(ctx, loader.BaseDir()))
+	runtimeSvc.SetSkillsRegistry(buildSkillsRegistry(ctx, sharedDeps.ConfigManager.BaseDir()))
 	runtimeSvc.SetAutoCompactThresholdResolver(runtimeAutoCompactThresholdResolverFunc(
 		func(ctx context.Context, cfg config.Config) (int, error) {
 			resolution, err := configstate.ResolveAutoCompactThreshold(ctx, cfg, modelCatalogs)
@@ -235,55 +210,109 @@ func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, er
 	if memoSvc != nil && cfg.Memo.AutoExtract {
 		runtimeSvc.SetMemoExtractor(newMemoExtractorAdapter(
 			providerRegistry,
-			manager,
+			sharedDeps.ConfigManager,
 			memo.NewAutoExtractor(nil, memoSvc, time.Duration(cfg.Memo.ExtractTimeoutSec)*time.Second),
 		))
 	}
 
 	runtimeImpl := agentruntime.Runtime(runtimeSvc)
 	closeFns := []func() error{toolsCleanup, sessionStore.Close}
-	if runtimeMode == RuntimeModeGateway {
-		remoteRuntime, remoteErr := newRemoteRuntimeAdapter(services.RemoteRuntimeAdapterOptions{})
-		if remoteErr != nil {
-			return RuntimeBundle{}, remoteErr
-		}
-		runtimeImpl = remoteRuntime
-		closeFns = append([]func() error{remoteRuntime.Close}, closeFns...)
-	}
 
 	needCleanup = false
 
 	closeBundle := combineRuntimeClosers(closeFns...)
 
 	return RuntimeBundle{
 		Config:            cfg,
-		ConfigManager:     manager,
+		ConfigManager:     sharedDeps.ConfigManager,
 		Runtime:           runtimeImpl,
-		ProviderSelection: providerSelection,
+		ProviderSelection: sharedDeps.ProviderSelection,
 		MemoService:       memoSvc,
 		Close:             closeBundle,
 	}, nil
 }
 
+// BuildRuntime 兼容旧入口，内部转发到 BuildGatewayServerDeps。
+func BuildRuntime(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, error) {
+	return BuildGatewayServerDeps(ctx, opts)
+}
+
 // NewProgram 基于共享运行时依赖构建并返回 TUI 程序，同时返回退出时应调用的资源清理函数。
 func NewProgram(ctx context.Context, opts BootstrapOptions) (*tea.Program, func() error, error) {
-	bundle, err := BuildRuntime(ctx, opts)
+	bundle, err := BuildTUIClientDeps(ctx, opts)
 	if err != nil {
 		return nil, nil, err
 	}
 
-	tuiApp, err := newTUIWithMemo(&bundle.Config, bundle.ConfigManager, bundle.Runtime, bundle.ProviderSelection, bundle.MemoService)
+	tuiRuntime, err := newRemoteRuntimeAdapter(services.RemoteRuntimeAdapterOptions{})
 	if err != nil {
 		if bundle.Close != nil {
 			_ = bundle.Close()
 		}
 		return nil, nil, err
 	}
+	cleanup := combineRuntimeClosers(tuiRuntime.Close, bundle.Close)
+
+	tuiApp, err := newTUIWithMemo(&bundle.Config, bundle.ConfigManager, tuiRuntime, bundle.ProviderSelection, bundle.MemoService)
+	if err != nil {
+		if cleanup != nil {
+			_ = cleanup()
+		}
+		return nil, nil, err
+	}
 	return tea.NewProgram(
 		tuiApp,
 		tea.WithAltScreen(),
 		tea.WithMouseCellMotion(),
-	), bundle.Close, nil
+	), cleanup, nil
+}
+
+// BuildSharedConfigDeps 统一构建共享配置依赖：配置、Provider 注册与当前选择服务。
+func BuildSharedConfigDeps(
+	ctx context.Context,
+	opts BootstrapOptions,
+) (bootstrapSharedBundle, agentruntime.ProviderFactory, *providercatalog.Service, error) {
+	defaultCfg, err := bootstrapDefaultConfig(opts)
+	if err != nil {
+		return bootstrapSharedBundle{}, nil, nil, err
+	}
+
+	loader := config.NewLoader("", defaultCfg)
+	manager := config.NewManager(loader)
+	if _, err := manager.Load(ctx); err != nil {
+		return bootstrapSharedBundle{}, nil, nil, err
+	}
+
+	providerRegistry, err := builtin.NewRegistry()
+	if err != nil {
+		return bootstrapSharedBundle{}, nil, nil, err
+	}
+	modelCatalogs := providercatalog.NewService(manager.BaseDir(), providerRegistry, nil)
+	providerSelection := configstate.NewService(manager, providerRegistry, modelCatalogs)
+	if _, err := providerSelection.EnsureSelection(ctx); err != nil {
+		return bootstrapSharedBundle{}, nil, nil, err
+	}
+
+	return bootstrapSharedBundle{
+		Config:            manager.Get(),
+		ConfigManager:     manager,
+		ProviderSelection: providerSelection,
+	}, providerRegistry, modelCatalogs, nil
+}
+
+// BuildTUIClientDeps 构建 TUI 客户端依赖，仅保留配置与 Provider 选择，不创建本地 runtime/tool 栈。
+func BuildTUIClientDeps(ctx context.Context, opts BootstrapOptions) (RuntimeBundle, error) {
+	sharedDeps, _, _, err := BuildSharedConfigDeps(ctx, opts)
+	if err != nil {
+		return RuntimeBundle{}, err
+	}
+	return RuntimeBundle{
+		Config:            sharedDeps.Config,
+		ConfigManager:     sharedDeps.ConfigManager,
+		ProviderSelection: sharedDeps.ProviderSelection,
+		MemoService:       nil,
+		Close:             nil,
+	}, nil
 }
 
 // bootstrapDefaultConfig 负责计算本次启动应使用的默认配置快照。
@@ -307,20 +336,6 @@ func resolveBootstrapWorkdir(workdir string) (string, error) {
 	return agentsession.ResolveExistingDir(workdir)
 }
 
-// resolveBootstrapRuntimeMode 归一化并校验 runtime 运行模式。
-func resolveBootstrapRuntimeMode(mode string) (string, error) {
-	normalized := strings.ToLower(strings.TrimSpace(mode))
-	if normalized == "" {
-		return RuntimeModeLocal, nil
-	}
-	switch normalized {
-	case RuntimeModeLocal, RuntimeModeGateway:
-		return normalized, nil
-	default:
-		return "", errors.New("bootstrap: runtime mode must be local or gateway")
-	}
-}
-
 func buildToolRegistry(cfg config.Config) (*tools.Registry, func() error, error) {
 	toolRegistry := tools.NewRegistry()
 	toolRegistry.Register(filesystem.New(cfg.Workdir))