refactor:美化/help界面

Author: creatang

internal/tui/core/app/app.go

@@ -37,6 +37,7 @@ const (
 	pickerProvider pickerMode = tuistate.PickerProvider
 	pickerModel    pickerMode = tuistate.PickerModel
 	pickerFile     pickerMode = tuistate.PickerFile
+	pickerHelp     pickerMode = tuistate.PickerHelp
 )
 
 type RuntimeMsg = tuistate.RuntimeMsg
@@ -74,6 +75,7 @@ type appComponents struct {
 	commandMenuMeta  tuistate.CommandMenuMeta
 	providerPicker   list.Model
 	modelPicker      list.Model
+	helpPicker       list.Model
 	fileBrowser      filepicker.Model
 	progress         progress.Model
 	transcript       viewport.Model
@@ -226,6 +228,7 @@ func newApp(container tuibootstrap.Container) (App, error) {
 			commandMenu:      commandMenu,
 			providerPicker:   newSelectionPickerItems(nil),
 			modelPicker:      newSelectionPickerItems(nil),
+			helpPicker:       newHelpPickerItems(nil),
 			fileBrowser:      fileBrowser,
 			progress:         progressBar,
 			transcript:       viewport.New(0, 0),
@@ -260,6 +263,9 @@ func newApp(container tuibootstrap.Container) (App, error) {
 	if err := app.refreshModelPicker(); err != nil {
 		return App{}, err
 	}
+	if err := app.refreshHelpPicker(); err != nil {
+		return App{}, err
+	}
 	app.selectCurrentProvider(cfg.SelectedProvider)
 	app.selectCurrentModel(cfg.CurrentModel)
 	app.modelRefreshID = cfg.SelectedProvider

internal/tui/core/app/commands.go

@@ -39,6 +39,8 @@ const (
 	providerPickerSubtitle = "Up/Down choose, Enter confirm, Esc cancel"
 	modelPickerTitle       = "Select Model"
 	modelPickerSubtitle    = "Up/Down choose, Enter confirm, Esc cancel"
+	helpPickerTitle        = "Slash Commands"
+	helpPickerSubtitle     = "Up/Down choose, Enter run, Esc cancel"
 	filePickerTitle        = "Browse Files"
 	filePickerSubtitle     = "Navigate folders, Enter choose file, Esc cancel"
 
@@ -69,6 +71,7 @@ const (
 	statusCompacting         = "Compacting context"
 	statusChooseProvider     = "Choose a provider"
 	statusChooseModel        = "Choose a model"
+	statusChooseHelp         = "Choose a slash command"
 	statusBrowseFile         = "Browse workspace files"
 	statusAwaitingPermission = "Awaiting permission (y=once, a=session, n=deny)"
 	statusPermissionApproved = "Permission approved"
@@ -123,6 +126,13 @@ func newSelectionPicker(items []list.Item) list.Model {
 	return picker
 }
 
+// newHelpPicker 创建 /help 专用选择器，禁用分页以保持单页展示体验。
+func newHelpPicker(items []list.Item) list.Model {
+	picker := newSelectionPicker(items)
+	picker.SetShowPagination(false)
+	return picker
+}
+
 func newCommandMenuModel(uiStyles styles) list.Model {
 	delegate := commandMenuDelegate{styles: uiStyles}
 	menu := list.New([]list.Item{}, delegate, 0, 0)
@@ -145,6 +155,15 @@ func newSelectionPickerItems(items []selectionItem) list.Model {
 	return newSelectionPicker(listItems)
 }
 
+// newHelpPickerItems 将 slash 命令映射为 /help 弹层列表项。
+func newHelpPickerItems(items []selectionItem) list.Model {
+	listItems := make([]list.Item, 0, len(items))
+	for _, item := range items {
+		listItems = append(listItems, item)
+	}
+	return newHelpPicker(listItems)
+}
+
 func mapProviderItems(items []config.ProviderCatalogItem) []selectionItem {
 	mapped := make([]selectionItem, 0, len(items))
 	for _, item := range items {
@@ -175,6 +194,13 @@ func replacePickerItems(current *list.Model, items []selectionItem) {
 	*current = next
 }
 
+// replaceHelpPickerItems 替换 /help 弹层条目并保持尺寸。
+func replaceHelpPickerItems(current *list.Model, items []selectionItem) {
+	next := newHelpPickerItems(items)
+	next.SetSize(current.Width(), current.Height())
+	*current = next
+}
+
 func (a *App) refreshProviderPicker() error {
 	items, err := a.providerSvc.ListProviders(context.Background())
 	if err != nil {
@@ -197,6 +223,21 @@ func (a *App) refreshModelPicker() error {
 	return nil
 }
 
+// refreshHelpPicker 刷新 /help 弹层中的 slash 命令列表。
+func (a *App) refreshHelpPicker() error {
+	items := make([]selectionItem, 0, len(builtinSlashCommands))
+	for _, command := range builtinSlashCommands {
+		items = append(items, selectionItem{
+			id:          command.Usage,
+			name:        command.Usage,
+			description: command.Description,
+		})
+	}
+	replaceHelpPickerItems(&a.helpPicker, items)
+	selectPickerItemByID(&a.helpPicker, "")
+	return nil
+}
+
 func (a *App) openProviderPicker() {
 	a.openPicker(pickerProvider, statusChooseProvider, &a.providerPicker, a.state.CurrentProvider)
 }
@@ -205,6 +246,11 @@ func (a *App) openModelPicker() {
 	a.openPicker(pickerModel, statusChooseModel, &a.modelPicker, a.state.CurrentModel)
 }
 
+// openHelpPicker 打开 slash 命令帮助弹层并进入可选择状态。
+func (a *App) openHelpPicker() {
+	a.openPicker(pickerHelp, statusChooseHelp, &a.helpPicker, "")
+}
+
 func (a *App) openPicker(mode pickerMode, statusText string, picker *list.Model, selectedID string) {
 	a.state.ActivePicker = mode
 	a.state.StatusText = statusText

internal/tui/core/app/commands_test.go

@@ -74,6 +74,7 @@ func TestStatusConstants(t *testing.T) {
 		{"statusCompacting", statusCompacting},
 		{"statusChooseProvider", statusChooseProvider},
 		{"statusChooseModel", statusChooseModel},
+		{"statusChooseHelp", statusChooseHelp},
 		{"statusBrowseFile", statusBrowseFile},
 	}
 
@@ -296,3 +297,24 @@ func TestExecuteStatusCommandFormatting(t *testing.T) {
 		t.Fatalf("expected Status header, got %q", output)
 	}
 }
+
+func TestRefreshHelpPicker(t *testing.T) {
+	app, _ := newTestApp(t)
+	if err := app.refreshHelpPicker(); err != nil {
+		t.Fatalf("refreshHelpPicker() error = %v", err)
+	}
+	if len(app.helpPicker.Items()) != len(builtinSlashCommands) {
+		t.Fatalf("expected %d help items, got %d", len(builtinSlashCommands), len(app.helpPicker.Items()))
+	}
+}
+
+func TestOpenHelpPicker(t *testing.T) {
+	app, _ := newTestApp(t)
+	app.openHelpPicker()
+	if app.state.ActivePicker != pickerHelp {
+		t.Fatalf("expected help picker to open")
+	}
+	if app.state.StatusText != statusChooseHelp {
+		t.Fatalf("expected help picker status, got %q", app.state.StatusText)
+	}
+}

internal/tui/core/app/update.go

@@ -372,6 +372,15 @@ func (a App) updateInputPanel(msg tea.Msg, typed tea.KeyMsg, cmds []tea.Cmd) (te
 			a.resetPasteHeuristics()
 
 			switch strings.ToLower(input) {
+			case slashCommandHelp:
+				if err := a.refreshHelpPicker(); err != nil {
+					a.state.ExecutionError = err.Error()
+					a.state.StatusText = err.Error()
+					a.appendActivity("system", "Failed to refresh slash help", err.Error(), true)
+					return a, tea.Batch(cmds...)
+				}
+				a.openHelpPicker()
+				return a, tea.Batch(cmds...)
 			case slashCommandProvider:
 				if err := a.refreshProviderPicker(); err != nil {
 					a.state.ExecutionError = err.Error()
@@ -572,6 +581,13 @@ func (a App) updatePicker(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 				return a, nil
 			}
 			return a, runModelSelection(a.providerSvc, item.id)
+		case pickerHelp:
+			item, ok := a.helpPicker.SelectedItem().(selectionItem)
+			a.closePicker()
+			if !ok {
+				return a, nil
+			}
+			return a, a.runSlashCommandSelection(item.id)
 		}
 	}
 
@@ -581,6 +597,8 @@ func (a App) updatePicker(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		a.providerPicker, cmd = a.providerPicker.Update(msg)
 	case pickerModel:
 		a.modelPicker, cmd = a.modelPicker.Update(msg)
+	case pickerHelp:
+		a.helpPicker, cmd = a.helpPicker.Update(msg)
 	case pickerFile:
 		a.fileBrowser, cmd = a.fileBrowser.Update(msg)
 		if didSelect, path := a.fileBrowser.DidSelectFile(msg); didSelect {
@@ -1455,6 +1473,12 @@ func (a *App) applyComponentLayout(rebuildTranscript bool) {
 
 	a.providerPicker.SetSize(max(24, tuiutils.Clamp(lay.rightWidth-14, 28, 52)), max(4, tuiutils.Clamp(lay.rightHeight-10, 6, 10)))
 	a.modelPicker.SetSize(max(24, tuiutils.Clamp(lay.rightWidth-14, 28, 52)), max(4, tuiutils.Clamp(lay.rightHeight-10, 6, 10)))
+	helpPickerMaxHeight := max(8, lay.rightHeight-6)
+	helpPickerDesiredHeight := (len(a.helpPicker.Items()) * 3) + 1
+	a.helpPicker.SetSize(
+		max(24, tuiutils.Clamp(lay.rightWidth-14, 28, 52)),
+		max(6, tuiutils.Clamp(helpPickerDesiredHeight, 6, helpPickerMaxHeight)),
+	)
 	a.fileBrowser.SetHeight(max(6, tuiutils.Clamp(lay.rightHeight-8, 8, 16)))
 	if rebuildTranscript || prevTranscriptWidth != a.transcript.Width {
 		a.rebuildTranscript()
@@ -1602,6 +1626,55 @@ func (a *App) handleImmediateSlashCommand(input string) (bool, tea.Cmd) {
 	}
 }
 
+// runSlashCommandSelection 根据 /help 弹层选中的命令执行对应 slash 行为。
+func (a *App) runSlashCommandSelection(command string) tea.Cmd {
+	command = strings.ToLower(strings.TrimSpace(command))
+	if command == "" {
+		return nil
+	}
+
+	if handled, cmd := a.handleImmediateSlashCommand(command); handled {
+		return cmd
+	}
+
+	switch command {
+	case slashCommandHelp:
+		if err := a.refreshHelpPicker(); err != nil {
+			a.state.ExecutionError = err.Error()
+			a.state.StatusText = err.Error()
+			a.appendActivity("system", "Failed to refresh slash help", err.Error(), true)
+			return nil
+		}
+		a.openHelpPicker()
+		return nil
+	case slashCommandProvider:
+		if err := a.refreshProviderPicker(); err != nil {
+			a.state.ExecutionError = err.Error()
+			a.state.StatusText = err.Error()
+			a.appendActivity("system", "Failed to refresh providers", err.Error(), true)
+			return nil
+		}
+		a.openProviderPicker()
+		return nil
+	case slashCommandModelPick:
+		if err := a.refreshModelPicker(); err != nil {
+			a.state.ExecutionError = err.Error()
+			a.state.StatusText = err.Error()
+			a.appendActivity("system", "Failed to refresh models", err.Error(), true)
+			return nil
+		}
+		a.openModelPicker()
+		return a.requestModelCatalogRefresh(a.state.CurrentProvider)
+	default:
+		a.state.StatusText = statusApplyingCommand
+		a.state.ExecutionError = ""
+		if isWorkspaceSlashCommand(command) {
+			return runSessionWorkdirCommand(a.runtime, a.state.ActiveSessionID, a.state.CurrentWorkdir, command)
+		}
+		return runLocalCommand(a.configManager, a.providerSvc, a.currentStatusSnapshot(), command)
+	}
+}
+
 func (a App) currentStatusSnapshot() tuistatus.Snapshot {
 	return tuistatus.BuildFromUIState(
 		a.state,

internal/tui/core/app/update_test.go

@@ -1064,3 +1064,77 @@ func TestHandleViewportKeys(t *testing.T) {
 	app.handleViewportKeys(&app.transcript, tea.KeyMsg{Type: tea.KeyDown})
 	app.handleViewportKeys(&app.transcript, tea.KeyMsg{Type: tea.KeyUp})
 }
+
+func TestUpdateEnterHelpOpensHelpPicker(t *testing.T) {
+	app, _ := newTestApp(t)
+	app.input.SetValue("/help")
+	app.state.InputText = "/help"
+
+	model, cmd := app.Update(tea.KeyMsg{Type: tea.KeyEnter})
+	if model == nil {
+		t.Fatalf("expected non-nil model")
+	}
+	app = model.(App)
+	if cmd != nil {
+		t.Fatalf("expected no async cmd when opening help picker")
+	}
+	if app.state.ActivePicker != pickerHelp {
+		t.Fatalf("expected help picker to be active")
+	}
+	if app.state.StatusText != statusChooseHelp {
+		t.Fatalf("expected status %q, got %q", statusChooseHelp, app.state.StatusText)
+	}
+	if len(app.helpPicker.Items()) != len(builtinSlashCommands) {
+		t.Fatalf("expected %d help options, got %d", len(builtinSlashCommands), len(app.helpPicker.Items()))
+	}
+}
+
+func TestUpdatePickerHelpSelectionOpensModelPicker(t *testing.T) {
+	app, _ := newTestApp(t)
+	if err := app.refreshHelpPicker(); err != nil {
+		t.Fatalf("refreshHelpPicker() error = %v", err)
+	}
+	app.openHelpPicker()
+	selectPickerItemByID(&app.helpPicker, slashCommandModelPick)
+
+	model, cmd := app.updatePicker(tea.KeyMsg{Type: tea.KeyEnter})
+	if model == nil {
+		t.Fatalf("expected model")
+	}
+	app = model.(App)
+	if cmd != nil {
+		_ = cmd()
+	}
+	if app.state.ActivePicker != pickerModel {
+		t.Fatalf("expected model picker to open from help selection")
+	}
+}
+
+func TestUpdatePickerHelpSelectionRunsSlashCommand(t *testing.T) {
+	app, _ := newTestApp(t)
+	if err := app.refreshHelpPicker(); err != nil {
+		t.Fatalf("refreshHelpPicker() error = %v", err)
+	}
+	app.openHelpPicker()
+	selectPickerItemByID(&app.helpPicker, slashCommandStatus)
+
+	model, cmd := app.updatePicker(tea.KeyMsg{Type: tea.KeyEnter})
+	if model == nil {
+		t.Fatalf("expected model")
+	}
+	app = model.(App)
+	if app.state.ActivePicker != pickerNone {
+		t.Fatalf("expected help picker to close after selecting /status")
+	}
+	if cmd == nil {
+		t.Fatalf("expected local slash command cmd")
+	}
+	msg := cmd()
+	result, ok := msg.(localCommandResultMsg)
+	if !ok {
+		t.Fatalf("expected localCommandResultMsg, got %T", msg)
+	}
+	if !strings.Contains(result.Notice, "Status:") {
+		t.Fatalf("expected status output in slash result, got %q", result.Notice)
+	}
+}

internal/tui/core/app/view.go

@@ -179,6 +179,11 @@ func (a App) renderPicker(width int, height int) string {
 		subtitle = filePickerSubtitle
 		body = a.fileBrowser.View()
 	}
+	if a.state.ActivePicker == pickerHelp {
+		title = helpPickerTitle
+		subtitle = helpPickerSubtitle
+		body = a.helpPicker.View()
+	}
 	content := lipgloss.JoinVertical(
 		lipgloss.Left,
 		a.styles.panelTitle.Render(title),

internal/tui/core/utils/view_helpers.go

@@ -15,6 +15,8 @@ func PickerLabelFromMode(mode tuistate.PickerMode) string {
 		return "model"
 	case tuistate.PickerFile:
 		return "file"
+	case tuistate.PickerHelp:
+		return "help"
 	default:
 		return "none"
 	}

internal/tui/core/utils/view_helpers_test.go

@@ -14,6 +14,7 @@ func TestPickerLabelFromMode(t *testing.T) {
 		{tuistate.PickerProvider, "provider"},
 		{tuistate.PickerModel, "model"},
 		{tuistate.PickerFile, "file"},
+		{tuistate.PickerHelp, "help"},
 		{tuistate.PickerMode(999), "none"},
 	}
 

internal/tui/state/state_test.go

@@ -6,8 +6,15 @@ func TestPanelAndPickerConstants(t *testing.T) {
 	if PanelSessions != 0 || PanelTranscript != 1 || PanelActivity != 2 || PanelInput != 3 {
 		t.Fatalf("unexpected panel constants: %d %d %d %d", PanelSessions, PanelTranscript, PanelActivity, PanelInput)
 	}
-	if PickerNone != 0 || PickerProvider != 1 || PickerModel != 2 || PickerFile != 3 {
-		t.Fatalf("unexpected picker constants: %d %d %d %d", PickerNone, PickerProvider, PickerModel, PickerFile)
+	if PickerNone != 0 || PickerProvider != 1 || PickerModel != 2 || PickerFile != 3 || PickerHelp != 4 {
+		t.Fatalf(
+			"unexpected picker constants: %d %d %d %d %d",
+			PickerNone,
+			PickerProvider,
+			PickerModel,
+			PickerFile,
+			PickerHelp,
+		)
 	}
 }